D 2018-08-08T09:11:49.740
L interface-1
N text/x-markdown
P dbc64cea3cc6379a807adc0c6e9c976dc7b77554
U moinejf
W 10657
# 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:
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 `