LibMusicXML 3.22
|
Functions | |
EXP TFactory | factoryOpen () |
Creates a new MusicXML factory. | |
EXP void | factoryClose (TFactory f) |
Close a MusicXML factory. | |
EXP void | factoryPrint (TFactory f, std::ostream &out) |
Print the MusicXML representation to stream. | |
EXP void | factoryHeader (TFactory f, const char *worknumber, const char *worktitle, const char *movementnumber, const char *movementtitle) |
Creates header information. | |
EXP void | factoryCreator (TFactory f, const char *c, const char *type) |
Creates creator information. | |
EXP void | factoryRights (TFactory f, const char *r, const char *type) |
Creates rights information. | |
EXP void | factoryEncoding (TFactory f, const char *software) |
Creates encoding information. | |
EXP void | factoryAddPart (TFactory f, TElement part) |
Adds a part. | |
EXP void | factoryAddGroup (TFactory f, int number, const char *name, const char *abbrev, bool groupbarline, TElement *parts) |
Adds parts grouped in a 'part-group'. | |
EXP void | factoryAddElement (TFactory f, TElement elt, TElement subelt) |
Adds an element to another element. | |
EXP void | factoryAddElements (TFactory f, TElement elt, TElement *subelts) |
Adds a set of elements to another element. | |
EXP void | factoryAddAttribute (TFactory f, TElement elt, TAttribute attr) |
Adds an attribute to an element. | |
EXP TElement | factoryScorepart (TFactory f, const char *id, const char *name, const char *abbrev) |
Creates a 'score-part' element. | |
EXP TElement | factoryPart (TFactory f, const char *id) |
Creates a 'part' element. | |
EXP TElement | factoryMeasure (TFactory f, int number) |
Creates a 'measure' element. | |
EXP TElement | factoryMeasureWithAttributes (TFactory f, int number, const char *time, const char *clef, int line, int key, int division) |
Creates a 'measure' element with a set of attributes. | |
EXP TElement | factoryNote (TFactory f, const char *step, float alter, int octave, int duration, const char *type) |
Creates a note. | |
EXP TElement | factoryDynamic (TFactory f, int type, const char *placement) |
Creates a dynamics element containing a dynamic type . | |
EXP TElement | factoryBarline (TFactory f, const char *location, const char *barstyle, const char *repeat) |
Creates a barline element with the corresponding sub-elements. | |
EXP void | factoryTuplet (TFactory f, int actual, int normal, TElement *notes) |
Makes a tuplet with notes. | |
EXP void | factoryTie (TFactory f, TElement from, TElement to) |
Tie two notes. | |
EXP void | factoryNotation (TFactory f, TElement elt, TElement notation) |
Add an element to a note notations element. | |
EXP void | factoryArticulation (TFactory f, TElement elt, TElement articulation) |
Add an articulation to a note. | |
EXP TElement | factoryRest (TFactory f, int duration, const char *type) |
Creates a rest. | |
EXP void | factoryChord (TFactory f, TElement *notes) |
Makes a chord from the gievn notes. | |
EXP TElement | factoryElement (TFactory f, int type) |
Creates an arbitrary MusicXML element. | |
EXP TElement | factoryStrElement (TFactory f, int type, const char *value) |
Creates an arbitrary MusicXML element with a string value. | |
EXP TElement | factoryIntElement (TFactory f, int type, int value) |
Creates an arbitrary MusicXML element with an integer value. | |
EXP TElement | factoryFloatElement (TFactory f, int type, float value) |
Creates an arbitrary MusicXML element with a float value. | |
EXP TAttribute | factoryStrAttribute (TFactory f, const char *name, const char *value) |
Creates an arbitrary attribute with a string value. | |
EXP TAttribute | factoryIntAttribute (TFactory f, const char *name, int value) |
Creates an arbitrary attribute with an integer value. | |
EXP TAttribute | factoryFloatAttribute (TFactory f, const char *name, float value) |
Creates an arbitrary attribute with a float value. | |
EXP void | factoryFreeElement (TFactory f, TElement elt) |
Frees a previously allocated element. | |
EXP void | factoryFreeAttribute (TFactory f, TAttribute attr) |
Frees a previously allocated attribute. |
The MusicXMl factory API.
The factory provides a high level API to build a MusicXML tree but gives also a low level access to the music representation. The idea is to make simple scores easy to build while complex scores accessible with a godd knowledge of the MusicXML format. The main feature of the factory is the automatic sort of the representation according to the dtd. Actually, only a small subset of the containers is not handled due to forms like (A, B)* where ordering should be specified at element construction. These containers are:
Note: for many elements (e.g. the measure element) the dtd do not impose an order. They have a form like ( A | B | C )* and thus any order is legal and the corresponding elements are not sorted. However, the elements semantic may require a given order, for example, the division attribute may be expected before a first duration element is encountered. It's the encoding application responsibility to build the elements with the appropriate order. These elements are:
Note concerning the memory management: all the elements or attributes allocated using the factory API (functions that return a TElement or a TAttribute) should be released using factoryFreeElement or factoryFreeAttribute unless they are added to the other elements (factoryAddElement or factoryAddAttribute) or to the music description (factoryAddPartlist)
Overview of the format and API
A MusicXML partwise score structure is basically made of a header containing various information and a require parts list, followed by a list of parts, including measures, made of various 'music data'.
'partwise score' := 'opt. header' 'part-list' 'part' ... 'part' 'part' := 'measure' ... 'measure' 'measure' := 'music-data' ... 'music-data'
The factory API reflects this structure:
EXP void factoryAddAttribute | ( | TFactory | f, |
TElement | elt, | ||
TAttribute | attr ) |
f | the MusicXML factory |
elt | an element. |
attr | the attribute to be added. |
f | the MusicXML factory |
elt | a container element. |
subelt | the element added to the container element. |
f | the MusicXML factory |
elt | the destination container. |
subelts | a null terminated array of elements. |
EXP void factoryAddGroup | ( | TFactory | f, |
int | number, | ||
const char * | name, | ||
const char * | abbrev, | ||
bool | groupbarline, | ||
TElement * | parts ) |
f | the MusicXML factory |
number | the group number |
name | the group name |
abbrev | the group abbreviated name |
groupbarline | a boolean for group barlines |
parts | a null terminated array of parts to be grouped |
f | the MusicXML factory |
part | actually a 'score-part' or a 'part' element. Pushed to the adequate location, depending on the element type. |
f | the MusicXML factory |
elt | a note element |
articulation | an articulation element |
EXP TElement factoryBarline | ( | TFactory | f, |
const char * | location, | ||
const char * | barstyle, | ||
const char * | repeat ) |
f | the MusicXML factory |
location | the barline location attribute. A null value prevents the attribute creation. |
barstyle | optional optional bar-style element. Should be in regular, dotted, dashed, heavy, light-light, light-heavy, heavy-light, heavy-heavy, tick (a short stroke through the top line), short (a partial barline between the 2nd and 4th lines), and none. A null value prevents the barstyle creation. |
repeat | optional repeat element with the corresponding required direction attribute. Should be in backward or forward. A null value prevents the repeat creation. |
f | the MusicXML factory |
notes | a null terminated list of notes. Actually, chords are denoted by a 'chord' element included to the note element, indicating that the note is an additional chord tone with the preceding note. For convenience, all the chord notes should be given to the function but the first one is skipped when adding the 'chord' element. |
EXP void factoryClose | ( | TFactory | f | ) |
f | the MusicXML factory |
EXP void factoryCreator | ( | TFactory | f, |
const char * | c, | ||
const char * | type ) |
f | the MusicXML factory |
c | the creator name (should not be null or empty) |
type | the creator type, corresponds to the 'type' attribute. A null pointer prevents the attribute creation. |
f | the MusicXML factory |
type | the dynamic type |
placement | optional placement dynamics attribute. Should be in "above" or "below". A null value prevents the attribute creation. |
f | the MusicXML factory |
type | the element type. |
EXP void factoryEncoding | ( | TFactory | f, |
const char * | software ) |
f | the MusicXML factory |
software | corresponds to the 'software' encoding element. Uses the default when null. |
EXP TAttribute factoryFloatAttribute | ( | TFactory | f, |
const char * | name, | ||
float | value ) |
f | the MusicXML factory |
name | the attribute name. |
value | the attribute value. |
f | the MusicXML factory |
type | the element type. |
value | the element value. |
EXP void factoryFreeAttribute | ( | TFactory | f, |
TAttribute | attr ) |
f | the MusicXML factory |
attr | an attribute. |
f | the MusicXML factory |
elt | an element. |
EXP void factoryHeader | ( | TFactory | f, |
const char * | worknumber, | ||
const char * | worktitle, | ||
const char * | movementnumber, | ||
const char * | movementtitle ) |
f | the MusicXML factory |
worknumber | corresponds to the 'work-number' element |
worktitle | corresponds to the 'work-titel' element |
movementnumber | corresponds to the 'movement-number' element |
movementtitle | corresponds to the 'movement-title' element |
A null pointer prevents the corresponding element creation.
EXP TAttribute factoryIntAttribute | ( | TFactory | f, |
const char * | name, | ||
int | value ) |
f | the MusicXML factory |
name | the attribute name. |
value | the attribute value. |
f | the MusicXML factory |
type | the element type. |
value | the element value. |
f | the MusicXML factory |
number | the required 'number' attribute |
EXP TElement factoryMeasureWithAttributes | ( | TFactory | f, |
int | number, | ||
const char * | time, | ||
const char * | clef, | ||
int | line, | ||
int | key, | ||
int | division ) |
f | the MusicXML factory |
number | the required 'number' attribute |
time | the time signature encoded as a string with the form "n/n". A null pointer prevents the 'time' element creation. |
clef | the clef in "G", "F", "C", "percussion", "TAB" or "none" |
line | an optional clef line (0 prevents the line element creation) |
key | an optional key signature (0 prevents the key element creation) |
division | an optional divisions element (0 prevents the divisions element creation) |
f | the MusicXML factory |
elt | a note element |
notation | an element to add to the note notations |
EXP TElement factoryNote | ( | TFactory | f, |
const char * | step, | ||
float | alter, | ||
int | octave, | ||
int | duration, | ||
const char * | type ) |
f | the MusicXML factory |
step | the pitch step using letters A through G |
alter | chromatic alteration in number of semitones (0 prevents the alter element creation) |
octave | a number in 0 to 9, where 4 indicates the octave started by middle C. |
duration | the sounding duration (in divisions count) (0 prevents the duration element creation) |
type | the graphic note type; in 256th, 128th, 64th, 32nd, 16th, eighth, quarter, half, whole, breve or long |
EXP TFactory factoryOpen | ( | ) |
f | the MusicXML factory |
id | the required 'id' attribute |
EXP void factoryPrint | ( | TFactory | f, |
std::ostream & | out ) |
f | the MusicXML factory |
out | the output stream |
f | the MusicXML factory |
duration | the sounding duration (in divisions count) (0 prevents the duration element creation) |
type | the graphic note type; in 256th, 128th, 64th, 32nd, 16th, eighth, quarter, half, whole, breve or long |
EXP void factoryRights | ( | TFactory | f, |
const char * | r, | ||
const char * | type ) |
f | the MusicXML factory |
r | the rights string (should not be null or empty) |
type | the rights type, corresponds to the 'type' attribute. A null pointer prevents the attribute creation. |
EXP TElement factoryScorepart | ( | TFactory | f, |
const char * | id, | ||
const char * | name, | ||
const char * | abbrev ) |
f | the MusicXML factory |
id | the required 'id' attribute |
name | the part name |
abbrev | the part abbreviated named |
EXP TAttribute factoryStrAttribute | ( | TFactory | f, |
const char * | name, | ||
const char * | value ) |
f | the MusicXML factory |
name | the attribute name. |
value | the attribute value. |
f | the MusicXML factory |
type | the element type. |
value | the element value. |
f | the MusicXML factory |
from | the tie start note |
to | the tie end note |
f | the MusicXML factory |
actual | the actual notes count |
normal | the normal notes count |
notes | a null terminated list of notes. |