abc2svg interface 1
This document describes the interface of the abc2svg core
version 1 (abc2svg-1.js).
Initialization
The abc2svg core may be included in html/xhtml documents by:
<script src="http://moinejf.free.fr/js/abc2svg-1.js" type="text/javascript"></script>
Before any first or new ABC to SVG translation, an instance of the class
Abc must be created:
var abc = new Abc(user)
The user argument of this function is a javascript Object which
must or may contain:
- img_out (optional)
- Callback function which called when a new SVG image has been generated.
This function receives one argument, a string, which is a part of
a SVG image.
This function may be absent when no graphic generation is needed
as, for example, for playing only.
- errbld (mandatory if no errmsg)
- Callback function which is called when some error has been found
during the ABC parsing or the SVG generation
This function receives 5 arguments:
- severity_level
- It may be:
0: warning1: error- other value: fatal error
- message
- Text of the error.
- file_name
- The file name may be
undefined.
- line_number and column_number
- Position of the error in the ABC source.
This information may not be known in which case
line_number is undefined.
The line and column numbers start from 0.
- errmsg (mandatory if no errbld)
- Callback function which is called when some error has been found
during the ABC parsing or the SVG generation
This function receives 3 arguments:
- message
- Text of the error.
Generally, this text includes a reference of the error in the
ABC source format:
file_name ":" line_number ":" column_number " " error_message
- line_number and column_number
- Position of the error in the ABC source, same as the
corresponding argument in
errbld().
- read_file (mandatory)
- Callback function which is called to read a file.
This function receives one argument, the name of the file as a string.
It must return the file content as a string.
It is called when a %%abc-include command has been found
in the ABC source.
- anno_start (optional)
- Callback function for setting ABC references in the SVG images.
This function is called just before the generation of a music element.
It receives 7 arguments:
- music_type
- It is one of
annot, bar, clef,
gchord, grace, key,
meter, note, part,
rest, tempo.
- start_offset
- Offset of the music element in the ABC source.
- stop_offset
- Offset of the end of music element in the ABC source.
- x, y, w, h
- Coordinates of a rectangle which
covers the music element.
- anno_stop (optional)
- Callback function for setting ABC references in the SVG images.
This function is called just after the generation of a music element.
It receives same 7 arguments as the callback function anno_stop.
- get_abcmodel (optional)
- Callback function to get the internal representation of the music
just before SVG generation.
This function receives 4 arguments:
- tsfirst (object)
- First musical symbol in the time sequence.
The symbols are double-linked by time by
ts_next / ts_prev.
The start of a new sequence is marked by
seqst.
- voice_tb (array of objects)
- Voice table.
The first symbol of a voice is sym.
The symbols are double-linked in a voice by
next / prev.
- music_types (array of strings)
- Array giving the symbol type from integer
value of the symbol attribute
type.
- info (object)
- Text of the information fields (T:, M:, Q:, P:...).
A newline ('\n') separates the appended values.
The returned representation is destroyed by the generation, so, either
- use it immediately before returning from the function, or
- unset the
user.img_out function.
- imagesize (string)
- Define the SVG image size.
When imagesize is not set, the size of the SVG images
is the one of a sheet, as defined by %%pagewidth.
When imagesize is defined, it must contain
width="image_width" height="image_height",
image_width and image_height being any value
accepted in the <svg> tag.
- page_format (boolean)
- Group the SVG images into non-page-breakable blocks.
When page_format is not set, the SVG images are generated
as text, on the right of the previous markup element (inlined images).
When page_format is set, the images are vertically aligned.
ABC to SVG translation
A ABC to SVG translation is done calling the Abc method tosvg:
abc.tosvg(file_name, ABC_source)
file_name- is the name of the ABC source.
It is used for information only in error messages.
ABC_source- is the ABC source as a (UTF-16) string
with the
'\n' (\u000a) as the end of line marker.
This function may be called many times in which case the values set by
previous calls are kept.
The ABC source must contain full tunes, i.e. a same tune cannot be continued
by a second call to tosvg.
Exported attributes and methods of the Abc class
- blk_out function to start the output of a block of images
-
It is useful in case of fatal error. See blk_flush.
This function takes no argument.
- blk_flush function to terminate a block of images.
-
In case of crash during the SVG generation in page_format mode,
blk_out and blk_flush (in this order) may be called
in the error callback function to output the last SVG elements.
This function takes no argument.
- out_svg function to add text in the current SVG image
-
It may be used only in the callback functions.
This function expects one mandatory argument:
- text (string)
- Text to be added.
- sx function to convert the x coordinate
-
This function expects one mandatory argument:
- x (number)
- Local
x.
It returns the absolute x coordinate.
- sy function to convert the y coordinate
-
This function expects one mandatory argument:
- y (number)
- Local
y.
It returns the absolute y coordinate.
- out_sxsy function to output x,y coordinates
-
It may be used only in the callback functions.
This function expects 3 mandatory arguments:
- x (number)
- x offset
- separator (string)
- text between x and y in the SVG element
- y (number)
- y offset
Global variables
The global variable abc2svg is an object which contains:
- version
- current version of abc2svg
- vdate
- date of the distribution of current version