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: warning
1: 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

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 %%paperwidth.
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