GUIDOLib  1.6.8
A Music Score Rendering Engine
Typedefs | Functions
GUIDO Factory

Typedefs

typedef void * ARFactoryHandler
 

Functions

GuidoErrCode GuidoFactoryOpen (ARFactoryHandler *outFactory)
 Opens the Guido Factory. More...
 
void GuidoFactoryClose (ARFactoryHandler inFactory)
 Closes the Guido Factory. More...
 
GuidoErrCode GuidoFactoryOpenMusic (ARFactoryHandler inFactory)
 Creates and opens a new music score. More...
 
ARHandler GuidoFactoryCloseMusic (ARFactoryHandler inFactory)
 Closes the current music score. More...
 
GuidoErrCode GuidoFactoryOpenVoice (ARFactoryHandler inFactory)
 Creates and opens a new voice. More...
 
GuidoErrCode GuidoFactoryCloseVoice (ARFactoryHandler inFactory)
 Closes the current voice. More...
 
GuidoErrCode GuidoFactoryOpenChord (ARFactoryHandler inFactory)
 Creates and open a new chord. More...
 
GuidoErrCode GuidoFactoryCloseChord (ARFactoryHandler inFactory)
 Closes the current chord. More...
 
GuidoErrCode GuidoFactoryInsertCommata (ARFactoryHandler inFactory)
 Begins a new chord note commata. More...
 
GuidoErrCode GuidoFactoryOpenEvent (ARFactoryHandler inFactory, const char *inEventName)
 Creates and opens a new event (note or rest). More...
 
GuidoErrCode GuidoFactoryCloseEvent (ARFactoryHandler inFactory)
 Closes the current event. More...
 
GuidoErrCode GuidoFactoryAddSharp (ARFactoryHandler inFactory)
 Adds a sharp to the current event. More...
 
GuidoErrCode GuidoFactoryAddFlat (ARFactoryHandler inFactory)
 Add a flat to the current event. More...
 
GuidoErrCode GuidoFactorySetEventDots (ARFactoryHandler inFactory, int dots)
 Sets the number of dots the current event. More...
 
GuidoErrCode GuidoFactorySetEventAccidentals (ARFactoryHandler inFactory, int accident)
 Sets the accidentals of the current event. More...
 
GuidoErrCode GuidoFactorySetOctave (ARFactoryHandler inFactory, int octave)
 Sets the register (octave) of the current event. More...
 
GuidoErrCode GuidoFactorySetDuration (ARFactoryHandler inFactory, int numerator, int denominator)
 Sets the duration of the current event. More...
 
GuidoErrCode GuidoFactoryOpenTag (ARFactoryHandler inFactory, const char *name, long tagID)
 
GuidoErrCode GuidoFactoryOpenRangeTag (ARFactoryHandler inFactory, const char *name, long tagID)
 
GuidoErrCode GuidoFactoryEndTag (ARFactoryHandler inFactory)
 Indicates the end of a range tag. More...
 
GuidoErrCode GuidoFactoryCloseTag (ARFactoryHandler inFactory)
 Closes the current tag. More...
 
GuidoErrCode GuidoFactoryAddTagParameterString (ARFactoryHandler inFactory, const char *val)
 Adds a new string parameter to the current tag. More...
 
GuidoErrCode GuidoFactoryAddTagParameterInt (ARFactoryHandler inFactory, int val)
 Adds a new integer parameter to the current tag. More...
 
GuidoErrCode GuidoFactoryAddTagParameterFloat (ARFactoryHandler inFactory, double val)
 Adds a new floating-point parameter to the current tag. More...
 
GuidoErrCode GuidoFactorySetParameterName (ARFactoryHandler inFactory, const char *name)
 Defines the name (when applicable) of the last added tag-parameter. More...
 
GuidoErrCode GuidoFactorySetParameterUnit (ARFactoryHandler inFactory, const char *unit)
 Defines the unit of the last added tag-parameter. More...
 

Detailed Description

The GUIDO Factory API provides a set of functions to create a GUIDO abstract representation from scratch and to convert it into a graphical representation.

The GUIDO Factory is a state machine that operates on implicit current elements: for example, once you open a voice (GuidoFactoryOpenVoice()), it becomes the current voice and all subsequent created events are implicitly added to this current voice. The elements of the factory state are:

Some elements of the factory state reflects the GUIDO format specification:

Typedef Documentation

◆ ARFactoryHandler

typedef void* ARFactoryHandler

Function Documentation

◆ GuidoFactoryAddFlat()

GuidoErrCode GuidoFactoryAddFlat ( ARFactoryHandler  inFactory)

Add a flat to the current event.

The current event must be a note.

Returns
an error code.

◆ GuidoFactoryAddSharp()

GuidoErrCode GuidoFactoryAddSharp ( ARFactoryHandler  inFactory)

Adds a sharp to the current event.

The current event must be a note.

Returns
an error code

◆ GuidoFactoryAddTagParameterFloat()

GuidoErrCode GuidoFactoryAddTagParameterFloat ( ARFactoryHandler  inFactory,
double  val 
)

Adds a new floating-point parameter to the current tag.

Parameters
inFactorya handler to a Guido Factory (created with GuidoFactoryOpen)
valthe parameter value
Returns
an error code.

◆ GuidoFactoryAddTagParameterInt()

GuidoErrCode GuidoFactoryAddTagParameterInt ( ARFactoryHandler  inFactory,
int  val 
)

Adds a new integer parameter to the current tag.

Parameters
inFactorya handler to a Guido Factory (created with GuidoFactoryOpen)
valthe parameter value
Returns
an error code.

◆ GuidoFactoryAddTagParameterString()

GuidoErrCode GuidoFactoryAddTagParameterString ( ARFactoryHandler  inFactory,
const char *  val 
)

Adds a new string parameter to the current tag.

Parameters
inFactorya handler to a Guido Factory (created with GuidoFactoryOpen)
valthe string parameter value
Returns
an error code.

◆ GuidoFactoryClose()

void GuidoFactoryClose ( ARFactoryHandler  inFactory)

Closes the Guido Factory.

Must be called to release the factory associated resources.

◆ GuidoFactoryCloseChord()

GuidoErrCode GuidoFactoryCloseChord ( ARFactoryHandler  inFactory)

Closes the current chord.

The function modifies the factory state if a chord is currently opened: the current factory chord is set to null. It fails if no chord is opened. The chord is added to the current voice.

Returns
an error code

◆ GuidoFactoryCloseEvent()

GuidoErrCode GuidoFactoryCloseEvent ( ARFactoryHandler  inFactory)

Closes the current event.

The function modifies the factory state if an event is currently opened: the current factory event is set to null. It fails if no event is opened. The event is added to the current voice.

Returns
an error code

◆ GuidoFactoryCloseMusic()

ARHandler GuidoFactoryCloseMusic ( ARFactoryHandler  inFactory)

Closes the current music score.

The function modifies the factory state if a music score is currently opened: the current factory score is set to null. It fails if no music score is opened. You must not have pending events nor pending voice at this point.

The logicical music layout (conversion from abstract to abstract representation) is part of the function operations. Next, the caller is expected to call GuidoFactoryMakeGR() with the returned value in order to proceed with the graphical score layout.

Returns
a GUIDO handler to the new AR structure, or 0.
See also
GuidoFactoryMakeGR()

◆ GuidoFactoryCloseTag()

GuidoErrCode GuidoFactoryCloseTag ( ARFactoryHandler  inFactory)

Closes the current tag.

The function is applied to the current tag. Must be called after parameter and before the range.
With the following examples:

  • tag<1,2,3>(c d e ) : call the function before parsing c
  • tag<1,2> c d : call the function before parsing c
Parameters
inFactorya handler to a Guido Factory (created with GuidoFactoryOpen)
Returns
an error code.

◆ GuidoFactoryCloseVoice()

GuidoErrCode GuidoFactoryCloseVoice ( ARFactoryHandler  inFactory)

Closes the current voice.

The function modifies the factory state if a voice is currently opened: the current factory voice is set to null. It fails if no voice is opened. You must not have pending events at this point. The voice is first converted to its normal form and next added to the current score.

Returns
an error code

◆ GuidoFactoryEndTag()

GuidoErrCode GuidoFactoryEndTag ( ARFactoryHandler  inFactory)

Indicates the end of a range tag.

The function is applied to the current tag. It must be called when the end of a tag's range has been reached.

Parameters
inFactorya handler to a Guido Factory (created with GuidoFactoryOpen)
Returns
an error code.

◆ GuidoFactoryInsertCommata()

GuidoErrCode GuidoFactoryInsertCommata ( ARFactoryHandler  inFactory)

Begins a new chord note commata.

Called to tell the factory that a new chord-voice is beginning. This is important for the ranges that need to be added (dispdur and shareStem)

Returns
an error code

◆ GuidoFactoryOpen()

GuidoErrCode GuidoFactoryOpen ( ARFactoryHandler outFactory)

Opens the Guido Factory.

Must be called before any other call to the Guido Factory API.

Returns
an integer that is an error code if not null.

◆ GuidoFactoryOpenChord()

GuidoErrCode GuidoFactoryOpenChord ( ARFactoryHandler  inFactory)

Creates and open a new chord.

The function modifies the factory state: the new chord becomes the current factory chord. It fails if a chord is already opened. A chord has to be closed using GuidoFactoryCloseChord()

Returns
an error code

◆ GuidoFactoryOpenEvent()

GuidoErrCode GuidoFactoryOpenEvent ( ARFactoryHandler  inFactory,
const char *  inEventName 
)

Creates and opens a new event (note or rest).

The function modifies the factory state: the new event becomes the current factory event. It fails if an event is already opened. An event has to be closed using GuidoFactoryCloseEvent()

Returns
an error code

◆ GuidoFactoryOpenMusic()

GuidoErrCode GuidoFactoryOpenMusic ( ARFactoryHandler  inFactory)

Creates and opens a new music score.

The function modifies the factory state: the new score becomes the current factory score. It fails if a music score is already opened. A music score has to be closed using GuidoFactoryCloseMusic()

Returns
an integer that is an error code if not null.

◆ GuidoFactoryOpenRangeTag()

GuidoErrCode GuidoFactoryOpenRangeTag ( ARFactoryHandler  inFactory,
const char *  name,
long  tagID 
)

◆ GuidoFactoryOpenTag()

GuidoErrCode GuidoFactoryOpenTag ( ARFactoryHandler  inFactory,
const char *  name,
long  tagID 
)

◆ GuidoFactoryOpenVoice()

GuidoErrCode GuidoFactoryOpenVoice ( ARFactoryHandler  inFactory)

Creates and opens a new voice.

The function modifies the factory state: the new voice becomes the current factory voice. It fails if a voice is already opened. A voice has to be closed using GuidoFactoryCloseVoice() Voices are similar to sequence is GMN.

Returns
an error code

◆ GuidoFactorySetDuration()

GuidoErrCode GuidoFactorySetDuration ( ARFactoryHandler  inFactory,
int  numerator,
int  denominator 
)

Sets the duration of the current event.

Durations are expressed as fractional value of a whole note: for example, a quarter note duration is 1/4. The duration becomes the current duration ie next notes will carry this duration until otherwise specified.

Parameters
inFactorya handler to a Guido Factory (created with GuidoFactoryOpen)
numeratorthe rational duration numerator
denominatorthe rational duration denominator
Returns
an error code.

◆ GuidoFactorySetEventAccidentals()

GuidoErrCode GuidoFactorySetEventAccidentals ( ARFactoryHandler  inFactory,
int  accident 
)

Sets the accidentals of the current event.

Parameters
inFactorya handler to a Guido Factory (created with GuidoFactoryOpen)
accidentpositive values are used for sharp and negative values for flats
Returns
an error code.

◆ GuidoFactorySetEventDots()

GuidoErrCode GuidoFactorySetEventDots ( ARFactoryHandler  inFactory,
int  dots 
)

Sets the number of dots the current event.

Parameters
inFactorya handler to a Guido Factory (created with GuidoFactoryOpen)
dotsthe number of dots to be carried by the current event.
Returns
an error code.

◆ GuidoFactorySetOctave()

GuidoErrCode GuidoFactorySetOctave ( ARFactoryHandler  inFactory,
int  octave 
)

Sets the register (octave) of the current event.

The current event must be a note. The register becomes the current register ie next notes will carry this register until otherwise specified.

Parameters
inFactorya handler to a Guido Factory (created with GuidoFactoryOpen)
octaveis an integer value indicating the octave of the note where a1 is A 440Hz. All octaves start with the pitch class c.
Returns
an error code.

◆ GuidoFactorySetParameterName()

GuidoErrCode GuidoFactorySetParameterName ( ARFactoryHandler  inFactory,
const char *  name 
)

Defines the name (when applicable) of the last added tag-parameter.

Parameters
inFactorya handler to a Guido Factory (created with GuidoFactoryOpen)
namethe tag parameter name
Returns
an error code.

◆ GuidoFactorySetParameterUnit()

GuidoErrCode GuidoFactorySetParameterUnit ( ARFactoryHandler  inFactory,
const char *  unit 
)

Defines the unit of the last added tag-parameter.

Parameters
inFactorya handler to a Guido Factory (created with GuidoFactoryOpen)
unita string defining the unit. The following units are supported:
  • m - meter
  • cm - centimeter
  • mm - millimeter
  • in - inch
  • pt - point (= 1/72.27 inch)
  • pc - pica (= 12pt)
  • hs - halfspace (half of the space between two lines of the current staff)
  • rl - relative measure in percent (used for positioning on score page)
Returns
an error code.

Guido Project Copyright © 2019 Grame-CNCM