bwl21/sandbox

trying out markdown

bwl21 opened this issue · 0 comments

bwl21 commented

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 usually 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 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

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

    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 the same 7 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
    These 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 variables

The global variable abc2svg is an object which contains:

  • version
    current version of abc2svg
  • vdate
    date of the distribution of current version

Version: v1.16.4-15-gcb9a000