SSScore

Introduction

the main Objective-C interface to SeeScore

Discussion

The main class of the SeeScore API, this encapsulates all information about the score loaded from a MusicXML file. You will find it more convenient and much simpler to use this interface from your Objective-C app rather than the pure C interface in sscore.h etc.

loadXMLFile() or loadXMLData() should be used to load a file and create a SScore object

layout() should be called on a background thread to create a layout, and SSystems are generated sequentially from the top and can be added to the display as they are produced, but you should ensure you do any UI operations on the foreground thread (using dispatch_after). This is all handled by SSView supplied as part of the sample app

numBars, numParts, getHeader(), getPartNameForPart(), getBarNumberForIndex() all return basic information about the score.

setTranspose() allows you to transpose the score.

Other methods return detailed information about items in the score and require a contents or contents-detail licence.

Methods

-actualBeatsForBar:

return the time signature operating in a particular bar in the score

-addChangeHandler:

add a handler to be called on each state change (edit, undo or redo)

-barContentsForPart:bar:err:

Get information about the contents of a particular part/bar.

-barNumberForIndex:

Get the bar number (String) given the index.

-barTypeForBar:

is the bar a full bar?

-convertTempoToBpm:

convert a tempo value into a beats-per-minute value using the time signature

-convertTempoToBpm:timeSig:

convert a tempo value into a beats-per-minute value using the time signature

-deleteItem:

delete an item from the score

-getBarBeats:

get information about beats in a bar

-getBarBeats:bpm:barType:

get information about beats in a bar

-hasRedo

is there a redo state?

-hasUndo

-hasUndo

editing methods

-hasUndo

is there an undo state?

+headerFromXMLFile:

get the MusicXML header information quickly from the file without loading the whole file

-insertDirectionWords:atNote:fontInfo:

attempt to insert the given text as <direction&gt<direction-type&gt<words&gt in the score immediately before the given note, above the staff.

-insertDirectionWords:atNote:where:fontInfo:

attempt to insert the given text as <direction&gt<direction-type&gt<words&gt in the score immediately before the given note, above the staff.

-instrumentNameForPart:

return the name for the instrument for the part.

-itemForPart:bar:handle:err:

-itemForPart:bar:handle:err:

return detailed information about an item in the score.

-layout1SystemWithContext:

Layout a single system with a single part.

-layout1SystemWithContext:startbar:maxBars:width:maxheight:part:magnification:options:

Layout a single system with a single part.

-layoutWithContext:

Layout a set of systems and return them through a callback function.

-layoutWithContext:width:maxheight:parts:magnification:options:callback:

Layout a set of systems and return them through a callback function.

-metronomeForBar:

get the metronome if defined in a bar

-partNameForPart:

return the name for the part.

-redo

redo the last undone edit

-removeChangeHandler:

remove the change handler added with addChangeHandler:

-saveToFile:

save the score to a MusicXML file

+scoreWithXMLData:

load the XML in-memory data and return a SSScore or null if error

+scoreWithXMLData:options:error:

load the XML in-memory data and return a SSScore or null if error

+scoreWithXMLFile:

load the XML file and return a SSScore or null if error

+scoreWithXMLFile:options:error:

load the XML file and return a SSScore or null if error

-setTranspose:

-setTranspose:

Set a transposition for the score.

-tempoAtBar:

get the tempo at a particular bar

-tempoAtStart

get the tempo at the start of the score if defined

-timeSigForBar:

return any time signature actually defined in a particular bar in the score, or zero if none

-transpose

-tryInsertItem:at:

attempt to insert the item in the score at the target location, return true if succeeded

-tryInsertMultiItem:left:right:

attempt to insert the multiple item (eg slur,tied,wedge) in the score at the left/right target locations, return true if succeeded

-undo

undo the last edit

-updateHeader

change a field in the header

-updateHeader:val:

change a field in the header

+version

the version of the SeeScore library

-xmlForPart:bar:err:

Return the raw XML for this given part/bar index as a String.

-xmlForPart:bar:handle:err:

Return the XML for the item in the part/bar.

actualBeatsForBar:

return the time signature operating in a particular bar in the score

-(sscore_timesig)actualBeatsForBar:(int)barIndex; 

Parameters

Return Value

the time signature in operation in the bar

addChangeHandler:

add a handler to be called on each state change (edit, undo or redo)

-(sscore_changehandler_id)addChangeHandler:(id<ScoreChangeHandler>)handler; 

Parameters

Return Value

a unique id for the handler to be used as an argument to removeChangeHandler

Discussion

the handler is called with the old and new state. These states can be compared so if the change affects only one bar then only that needs to be updated. All parts of the UI which show a representation of any part of the score should use a handler so everything updates automatically on a state change

barContentsForPart:bar:err:

Get information about the contents of a particular part/bar.

-(SSBarGroup*)barContentsForPart:(int)partindex bar:(int)barindex 
        err:(enum sscore_error*)err; 

Parameters

Return Value

the SSBarGroup containing an array of SSDisplayedItem. To get more information call itemForPart:bar:handle:err: using the item_h field

Discussion

Requires contents licence.

barNumberForIndex:

Get the bar number (String) given the index.

-(NSString*)barNumberForIndex:(int)barindex; 

Parameters

Return Value

the score-defined number String (usually "1" for index 0)

barTypeForBar:

is the bar a full bar?

-(enum sscore_bartype_e)barTypeForBar:(int)barIndex; 

Parameters

Return Value

the type of bar (full or partial/anacrusis)

convertTempoToBpm:

convert a tempo value into a beats-per-minute value using the time signature

-(int)convertTempoToBpm:(sscore_pd_tempo) tempo timeSig:(sscore_timesig)timesig; 

Parameters

Return Value

beats per minute value

See Also

convertTempoToBpm:timeSig:

convert a tempo value into a beats-per-minute value using the time signature

-(int)convertTempoToBpm:(sscore_pd_tempo) tempo timeSig:(sscore_timesig)timesig; 

Parameters

See Also

deleteItem:

delete an item from the score

-(bool)deleteItem:(SSEditItem*)item; 

Parameters

Return Value

true if it succeeded

Discussion

get the item from SSSystem

getBarBeats:

get information about beats in a bar

-(sscore_pd_barbeats)getBarBeats:(int)barindex bpm:(int)bpm 
        barType:(enum sscore_bartype_e) bartype; 

Parameters

Return Value

information about number of beats and the beat time in ms for a bar

See Also

getBarBeats:bpm:barType:

get information about beats in a bar

-(sscore_pd_barbeats)getBarBeats:(int)barindex bpm:(int)bpm 
        barType:(enum sscore_bartype_e) bartype; 

Parameters

See Also

hasRedo

is there a redo state?

-(bool)hasRedo; 

Return Value

true if is possible to redo the last undo

hasUndo

-(bool)hasUndo; 

Discussion

The information required for playing the score is available through the SSPData class (only if a playdata licence is available)

hasUndo

editing methods

-(bool)hasUndo; 

Discussion

each edit creates a new state and adds it to a list. The change handler is called with new and old state on each state change. Undo and redo just change the current index into the list of states

hasUndo

is there an undo state?

-(bool)hasUndo; 

Return Value

true if is possible to undo the last edit

headerFromXMLFile:

get the MusicXML header information quickly from the file without loading the whole file

+(SSHeader*)headerFromXMLFile:(NSString*)filePath; 

Return Value

the header strings only (empty credits/parts). Return nil on error

insertDirectionWords:atNote:fontInfo:

attempt to insert the given text as <direction&gt<direction-type&gt<words&gt in the score immediately before the given note, above the staff.

-(bool)insertDirectionWords:(NSString*)words atNote:(SSComponent *)noteComponent 
        fontInfo:(const sscore_edit_fontinfo*)finfo; 

Parameters

See Also

insertDirectionWords:atNote:where:fontInfo:

attempt to insert the given text as <direction&gt<direction-type&gt<words&gt in the score immediately before the given note, above the staff.

-(bool)insertDirectionWords:(NSString*)words atNote:(SSComponent *)noteComponent 
        fontInfo:(const sscore_edit_fontinfo*)finfo; 

Parameters

Return Value

true if insert succeeded

See Also

instrumentNameForPart:

return the name for the instrument for the part.

-(NSString*)instrumentNameForPart:(int)partindex; 

Parameters

Return Value

instrument name, empty if not defined

Discussion

This is often not defined in the XML, in which case the part name is probably the instrument name

itemForPart:bar:handle:err:

-(SSTimedItem*)itemForPart:(int)partindex bar:(int)barindex 
        handle:(sscore_item_handle)item_h err:(enum sscore_error*)err; 

Discussion

The contents methods are available if we have a contents licence

itemForPart:bar:handle:err:

return detailed information about an item in the score.

-(SSTimedItem*)itemForPart:(int)partindex bar:(int)barindex 
        handle:(sscore_item_handle)item_h err:(enum sscore_error*)err; 

Parameters

Return Value

SSTimedItem which can be cast to the specific derived type - NoteItem/DirectionItem etc.

Discussion

Requires contents-detail licence.

layout1SystemWithContext:

Layout a single system with a single part.

-(SSSystem*)layout1SystemWithContext:(CGContextRef)ctx 
        startbar:(int)startbarindex maxBars:(int)maxBars width:(float)width 
        maxheight:(float)max_height part:(int)partindex magnification:(float)magnification 
        options:(SSLayoutOptions*)layoutOptions; 

Parameters

Return Value

the system

Discussion

You specify a start bar index and a width and magnification and it will display as many bars as will fit into this width, up to a limit of maxBars if > 0.

Useful for display of individual parts for part selection.

See Also

layout1SystemWithContext:startbar:maxBars:width:maxheight:part:magnification:options:

Layout a single system with a single part.

-(SSSystem*)layout1SystemWithContext:(CGContextRef)ctx 
        startbar:(int)startbarindex maxBars:(int)maxBars width:(float)width 
        maxheight:(float)max_height part:(int)partindex magnification:(float)magnification 
        options:(SSLayoutOptions*)layoutOptions; 

Parameters

Discussion

You specify a start bar index and a width and magnification and it will display as many bars as will fit into this width, up to a limit of maxBars if > 0.

Useful for display of individual parts for part selection.

See Also

layoutWithContext:

Layout a set of systems and return them through a callback function.

-(enum sscore_error)layoutWithContext:(CGContextRef)ctx width:(float)width 
        maxheight:(float)max_system_height parts:(NSArray<NSNumber*>*)parts 
        magnification:(float)magnification options:(SSLayoutOptions*)layoutOptions 
        callback:(sslayout_callback_block_t)callback; 

Parameters

Discussion

This should be called on a background thread and it will call cb for each system laid out, from top to bottom. cb will normally add the system to a list and schedule an update on the foreground (gui event dispatch) thread to allow the UI to remain active during concurrent layout. cb can return false to abort the layout.

See Also

layoutWithContext:width:maxheight:parts:magnification:options:callback:

Layout a set of systems and return them through a callback function.

-(enum sscore_error)layoutWithContext:(CGContextRef)ctx width:(float)width 
        maxheight:(float)max_system_height parts:(NSArray<NSNumber*>*)parts 
        magnification:(float)magnification options:(SSLayoutOptions*)layoutOptions 
        callback:(sslayout_callback_block_t)callback; 

Parameters

Discussion

This should be called on a background thread and it will call cb for each system laid out, from top to bottom. cb will normally add the system to a list and schedule an update on the foreground (gui event dispatch) thread to allow the UI to remain active during concurrent layout. cb can return false to abort the layout.

See Also

metronomeForBar:

get the metronome if defined in a bar

-(sscore_pd_tempo)metronomeForBar:(int)barIndex; 

Parameters

Return Value

any metronome defined in the bar

partNameForPart:

return the name for the part.

-(SSPartName*)partNameForPart:(int)partindex; 

Parameters

Return Value

PartName (full + abbreviated)

redo

redo the last undone edit

-(void)redo; 

removeChangeHandler:

remove the change handler added with addChangeHandler:

-(void)removeChangeHandler:(sscore_changehandler_id)handlerId; 

Parameters

saveToFile:

save the score to a MusicXML file

-(enum sscore_error)saveToFile:(NSString*)filePath; 

Parameters

Return Value

any error

scoreWithXMLData:

load the XML in-memory data and return a SSScore or null if error

+(SSScore*)scoreWithXMLData:(NSData *)data options:(SSLoadOptions*)loadOptions 
        error:(sscore_loaderror*)err; 

Parameters

Return Value

the SSScore or NULL if error with the error returned in err

Discussion

When loading mxl compressed data you must set the compressed flag in SSLoadOptions Any warnings are returned in err.warn[] if SSLoadOptions.checkxml was set Swift signature SSScore(XMLData:data : NSData, options: loadOptions : SSLoadOptions, error: err : sscore_loaderror)

See Also

scoreWithXMLData:options:error:

load the XML in-memory data and return a SSScore or null if error

+(SSScore*)scoreWithXMLData:(NSData *)data options:(SSLoadOptions*)loadOptions 
        error:(sscore_loaderror*)err; 

Parameters

Discussion

When loading mxl compressed data you must set the compressed flag in SSLoadOptions Any warnings are returned in err.warn[] if SSLoadOptions.checkxml was set Swift signature SSScore(XMLData:data : NSData, options: loadOptions : SSLoadOptions, error: err : sscore_loaderror)

See Also

scoreWithXMLFile:

load the XML file and return a SSScore or null if error

+(SSScore*)scoreWithXMLFile:(NSString *)filePath options:(SSLoadOptions*)loadOptions 
        error:(sscore_loaderror*)err; 

Parameters

Return Value

the SSScore or NULL if error with the error returned in err

Discussion

This uses the .mxl file extension to detect mxl data Any warnings are returned in err.warn[] if SSLoadOptions.checkxml was set Swift signature SSScore(XMLFile: xmlFilePath : String, options: loadOptions : SSLoadOptions, error: err : sscore_loaderror)

See Also

scoreWithXMLFile:options:error:

load the XML file and return a SSScore or null if error

+(SSScore*)scoreWithXMLFile:(NSString *)filePath options:(SSLoadOptions*)loadOptions 
        error:(sscore_loaderror*)err; 

Parameters

Discussion

This uses the .mxl file extension to detect mxl data Any warnings are returned in err.warn[] if SSLoadOptions.checkxml was set Swift signature SSScore(XMLFile: xmlFilePath : String, options: loadOptions : SSLoadOptions, error: err : sscore_loaderror)

See Also

setTranspose:

-(enum sscore_error)setTranspose:(int)semitones; 

Discussion

The transpose methods

setTranspose:

Set a transposition for the score.

-(enum sscore_error)setTranspose:(int)semitones; 

Parameters

Discussion

Call layout() after calling setTranspose for a new transposed layout.

Requires the transpose licence.

tempoAtBar:

get the tempo at a particular bar

-(sscore_pd_tempo)tempoAtBar:(int)barIndex; 

Parameters

Return Value

information about the tempo in the bar

tempoAtStart

get the tempo at the start of the score if defined

-(sscore_pd_tempo)tempoAtStart; 

Return Value

information about the tempo to use at the start of the piece

timeSigForBar:

return any time signature actually defined in a particular bar in the score, or zero if none

-(sscore_timesig)timeSigForBar:(int)barIndex; 

Parameters

Return Value

the time signature in the bar - return beats = 0 if there is none

Discussion

actualBeatsForBar: is more useful to find the operating time signature in a bar

transpose

-(int)transpose; 

Return Value

the current transpose

Discussion

Get the current transpose value set with setTranspose.

tryInsertItem:at:

attempt to insert the item in the score at the target location, return true if succeeded

-(bool)tryInsertItem:(const sscore_edit_insertinfo*)info at:(SSTargetLocation*)target; 

Parameters

Return Value

true if insert succeeded

tryInsertMultiItem:left:right:

attempt to insert the multiple item (eg slur,tied,wedge) in the score at the left/right target locations, return true if succeeded

-(bool)tryInsertMultiItem:(const sscore_edit_insertinfo*)info 
        left:(SSTargetLocation*)target_left right:(SSTargetLocation*)target_right; 

Parameters

Return Value

true if insert succeeded

undo

undo the last edit

-(void)undo; 

updateHeader

change a field in the header

-(void)updateHeader:(enum sscore_header_fieldid)fieldId val:(NSString*)val; 

Parameters

See Also

updateHeader:val:

change a field in the header

-(void)updateHeader:(enum sscore_header_fieldid)fieldId val:(NSString*)val; 

Parameters

See Also

version

the version of the SeeScore library

+(sscore_version)version; 

Return Value

the version hi.lo

xmlForPart:bar:err:

Return the raw XML for this given part/bar index as a String.

-(NSString*)xmlForPart:(int)partindex bar:(int)barindex err:(enum sscore_error*)err; 

Parameters

Return Value

the XML as a NSString

Discussion

Requires contents-detail licence.

xmlForPart:bar:handle:err:

Return the XML for the item in the part/bar.

-(NSString*)xmlForPart:(int)partindex bar:(int)barindex handle:(sscore_item_handle)item_h 
        err:(enum sscore_error*)err; 

Parameters

Return Value

the XML as a NSString

Discussion

Requires contents licence.

Properties

header

the MusicXML header information

numBars

the total number of bars in the score.

numParts

the total number of parts in the score.

rawscore

the low level C API to the score

scoreHasDefinedTempo

true if there is a metronome or sound tempo defined in the XML

header

the MusicXML header information

@property (readonly) SSHeader *header; 

numBars

the total number of bars in the score.

@property (readonly) int numBars; 

numParts

the total number of parts in the score.

@property (readonly) int numParts; 

rawscore

the low level C API to the score

@property (readonly) sscore* rawscore; 

scoreHasDefinedTempo

true if there is a metronome or sound tempo defined in the XML

@property (readonly) bool scoreHasDefinedTempo;