abc2svg interface 1

This document describes the interface of the abc2svg core version 1 (abc2svg-1.js).

Changes in the version 1.17.0

• class Abc in the global variable abc2svg

• addition of the modules

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>

This script defines a global variable, abc2svg, which contains the global variables and functions of the core.

Before any first or new ABC to SVG translation, an instance of the class Abc must be created:

var abc = new abc2svg.Abc(user)

The user argument of this function is a javascript Object which must or may contain:

• img_out (optional):
  Callback function which is called when a new SVG image has been generated.

  This function receives one argument, a string, which is usually a SVG image.
  It 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 (integer)
    Level of the message which may be:
    • 0: warning
    • 1: error
    • other value: fatal error
  • message (String)
    Text of the error.
  • file_name (String):
    The name of the abc file, used for reporting. The file name may be undefined.
  • line_number and column_number (integer):
    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 or null.
  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 8 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.
  • s
    Pointeur to the internal representation of 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 the same 8 arguments as the callback function anno_start.

• 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, only the SVG images are generated. With XHTML output, the images go to the right of the previous ones (inlined images).
  When page_format is set, the images are grouped in <div> containers with a class "nobrk", and a class "newpage" in case of %%newpage.

ABC to SVG translation

ABC to SVG translation is done calling the Abc method tosvg:

        abc.tosvg(file_name, ABC_source, start_offset, end_offset)

• 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.

• start_offset, end_offset
  are the character offsets of the ABC sequence in the ABC_source.
  They are optional and their default values are 0 and ABC_source.length

abc.tosvg 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_flush:
  function to terminate a block of images.

  In case of fatal error during the SVG generation, this function may be called in the error callback function to output the last SVG elements.
  bkl_flush 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.

  sx returns the x coordinate in the current SVG container.

• sy:
  function to convert the y coordinate

  This function expects one mandatory argument:

  • y: (number)
    Local y.

  sy returns the y coordinate in the current SVG container.

• 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

• sh:
  function to convert a height

  This function expects one mandatory argument:

  • h (number)
    Local height.

  sh returns the height in the current SVG container.

• ax: function to convert the x coordinate

• ay: function to convert the y coordinate

• ah: function to convert a height

  The last 3 functions return values relative to the global SVG container.
  They may be used in place of sx, sy and sh when elements must be globally added (by out_svg).
  When %%pagescale is 1 (default), there is no global container (the coordinates are the ones of the SVG image).
  When this is not the case, a global <g> container is added, with the class "g".

Global variable

The global variable abc2svg contains the global variables and functions of the abc2svg core.

• version and vdate
  are the current version and distribution date of the abc2svg package.

• loadjs
  is the function used by the module subsystem to inject dynamically javascript code inside the core. It is also used to load the soundfounds when playing is done by the HTML5 audio subsystem.
  This function must be defined in the script using the abc2svg core. If it is not defined, nor the dynamic modules nor the soundfonts will be loaded.

  This function expects three arguments:

  • script_name (string)
    URL of the script.
    
  • onload (function)
    Callback function which is called when the script has been sucessfully loaded.
    This function has no argument.
  • onerror (function)
    Callback function which is called when the script cannot be loaded.
    This function has no argument.

Modules

Some abc2svg specific features are not directly included in the core. They are handled in separate modules.

These modules may be concatenated with the core or may stay on the Web server.

When the modules stay on the server, each ABC source must be scanned to find if it uses some specific features.
This is done calling the function abc2svg.modules.load(). This function expects one or two arguments:

• ABC_source (source)

• ondone (function)
  This optional callback function is called when all needed modules have been loaded (by abc2svg.loadjs()).
  It has no argument.

• errmsg (function)
  This optional function is called in case of error.
  When undefined, a context dependant function is used.
  It gets one argument: the error message.

It returns true when all the needed modules are loaded (no new feature). In this case, the function ondone() is not called.
When false is returned, the caller is alerted via the callback function ondone().