SSSystem

Introduction

interface to a SeeScore System

Discussion

A System is a range of bars able to draw itself in a CGContextRef, and is a product of calling SScore layoutXXX:

drawWithContext draws the system into a CGContextRef, the call with colourRender argument allowing item colouring (and requiring an additional licence)

partIndexForYPos, barIndexForXPos can be used to locate the bar and part under the cursor/finger

hitTest is used to find the exact layout components (eg notehead, stem, beam) at a particular location (requiring a contents licence)

componentsForItem is used to find all the layout components of a particular score item (requiring a contents licence)

Methods

-addTiedToNotehead:

add a tied pair if there is a suitable note to the right which can be tied to the notehead defined by target

-barIndexForXPos:

get the bar index of the bar enclosing the given x coordinate in this system

-barLayout:

get barline measurements for the part in this system

-boundsForItem:

get a bounding box which encloses all layout components for a score item in this system

-canAddTiedToNotehead:

is there a suitable note to the right which can be tied to the notehead defined by target

-closeFeatures:

get an array of components within a certain distance of a given a point in this system

-closeFeatures:distance:

get an array of components within a certain distance of a given a point in this system

-componentsForItem:

get an array of layout components which belong to a particular score item in this system

-cursorRectForBar:context:

get the cursor rectangle for a particular system and bar

-deselectAll

deselect all selected items in this system

-deselectItem:

deselect the item previously selected item

-directionForComponent:

find the direction-type from a layout component created from it

-directionsNearComponent:

find the directions around the point defined by the (note or direction) component

-directionTypeForComponent:

find the direction-type from a layout component created from it

-drawDragItem:withContext:topleft:translate:

redraw an existing item in the system when dragged (eg update slur when control point dragged)

-drawDragItem:withContext:translate:

redraw an existing item in the system when dragged (eg update slur when control point dragged)

-drawDragType:itemType:pos:

draw any required decoration - (ledgers) for the item type being dragged in the system

-drawDragType:withContext:topleft:pos:

draw any required decoration - (ledgers) for the item type being dragged in the system

-drawWithContext:at:magnification:

draw this system at the given point.

-drawWithContext:at:magnification:colourRender:

draw this system at the given point allowing optional colouring of particular items/components in the layout.

-dropItem:translate:

drop dragged existing item in the score (eg slur control point)

-hitTest:

get an array of components which intersect a given a point in this system

-includesBar:

does this system include the bar?

-includesBarRange:

does this system include the bar range?

-insertPosForTarget

calculate and return a suitable approximation to the insertion position for this target to show in the UI while dragging

-insertPosForTarget:lr:

calculate and return a suitable approximation to the insertion position for this target to show in the UI while dragging

-itemForComponent:

get the editable item for a SSComponent

-itemForDirectionType:

get the editable item for a SSDirectionType

-nearestDirectionComponentAt: maxDistance:

find the closest layout component within maxDistance of pos that is part of a direction (words etc)

-nearestDirectionComponentAt:type:maxDistance:

find the closest layout component within maxDistance of pos that is part of a direction (words etc)

-nearestInsertTargetFor:at:

return the nearest valid target location to insert an item of given type in the score

-nearestInsertTargetFor:at:max:

return the nearest valid target location to insert an item of given type in the score

-nearestNoteComponentAt:maxDistance:

find the closest layout component within maxDistance of pos that is part of a note (notehead,stem,dot,accidental etc)

-partIndexForYPos:

get the part index of the part enclosing the given y coordinate in this system

-partLayout:

get staff measurement for the part in this system

-pointsToFontSize:

get the pointsize of a UIFont (of type "Georgia") which will look exactly like a SeeScore direction with this fontsize

-printTo:at:magnification:

draw this system at the given point with optimisation for printing (ie without special pixel alignment).

-selectItem:part:bar:foreground:background:

select the item in the system/part/bar and colour it

-staffIndexForYPos:

get the index of the staff within the part closest to the given y coordinate in this system

-staffLayout:

get staff measurement for the part in this system

-staffLocationForYPos:

from the ypos return above or below according to the ypos relative to the closest staff

-tiedRect:

get the bounding box of the tie which can be added to the right of the given notehead so we can draw it in temporarily

-updateLayout:newState:

update the layout to show the state in the sscore_state_container (called by state change handler)

addTiedToNotehead:

add a tied pair if there is a suitable note to the right which can be tied to the notehead defined by target

-(bool)addTiedToNotehead:(SSTargetLocation*)target; 

Parameters

Return Value

true if added pair successfully, false if not possible, with no change to score

barIndexForXPos:

get the bar index of the bar enclosing the given x coordinate in this system

-(int)barIndexForXPos:(float) xpos; 

Parameters

Return Value

the 0-based bar index

barLayout:

get barline measurements for the part in this system

-(SSBarLayout*)barLayout:(int)partIndex; 

Parameters

Return Value

barline dimensions

boundsForItem:

get a bounding box which encloses all layout components for a score item in this system

-(CGRect)boundsForItem:(sscore_item_handle)item_h; 

Parameters

Return Value

the bounds of (all components of) the item - empty if not licensed

Discussion

a contents licence is required

canAddTiedToNotehead:

is there a suitable note to the right which can be tied to the notehead defined by target

-(bool)canAddTiedToNotehead:(SSTargetLocation*)target; 

Parameters

Return Value

true if a valid tied pair of elements can be added to the given notehead and one immediately to the right with the same pitch

closeFeatures:

get an array of components within a certain distance of a given a point in this system

-(NSArray<SSComponent*> *)closeFeatures:(CGPoint)p distance:(float)distance; 

Parameters

Return Value

array of intersecting SSComponent - empty if unlicensed

Discussion

results are sorted in order of increasing distance. A contents licence is required

See Also

closeFeatures:distance:

get an array of components within a certain distance of a given a point in this system

-(NSArray<SSComponent*> *)closeFeatures:(CGPoint)p distance:(float)distance; 

Parameters

Discussion

results are sorted in order of increasing distance. A contents licence is required

See Also

componentsForItem:

get an array of layout components which belong to a particular score item in this system

-(NSArray<SSComponent*>*)componentsForItem:(sscore_item_handle)item_h; 

Parameters

Return Value

array of SSComponent - empty if unlicensed

Discussion

a contents licence is required

cursorRectForBar:context:

get the cursor rectangle for a particular system and bar

-(SSCursorRect)cursorRectForBar:(int)barIndex context:(CGContextRef)ctx; 

Parameters

Return Value

the bar rectangle which can be used for a cursor

deselectAll

deselect all selected items in this system

-(void)deselectAll; 

deselectItem:

deselect the item previously selected item

-(void)deselectItem:(sscore_item_handle)item_h; 

Parameters

directionForComponent:

find the direction-type from a layout component created from it

-(SSDirectionType*)directionTypeForComponent:(SSComponent*)directionComponent; 

Parameters

Return Value

the direction-type

See Also

directionsNearComponent:

find the directions around the point defined by the (note or direction) component

-(NSArray<SSDirectionType*>*)directionsNearComponent:(SSComponent*)comp; 

Parameters

Return Value

array of SSDirectionType* . Those of type sscore_dir_words can be cast to SSDirectionTypeWords, and then the text is readable and writeable

directionTypeForComponent:

find the direction-type from a layout component created from it

-(SSDirectionType*)directionTypeForComponent:(SSComponent*)directionComponent; 

Parameters

See Also

drawDragItem:withContext:topleft:translate:

redraw an existing item in the system when dragged (eg update slur when control point dragged)

-(void)drawDragItem:(SSEditItem *)item withContext:(CGContextRef)ctx 
        topleft:(CGPoint)tl translate:(CGPoint)translate; 

Parameters

See Also

drawDragItem:withContext:translate:

redraw an existing item in the system when dragged (eg update slur when control point dragged)

-(void)drawDragItem:(SSEditItem *)item withContext:(CGContextRef)ctx 
        topleft:(CGPoint)tl translate:(CGPoint)translate; 

Parameters

See Also

drawDragType:itemType:pos:

draw any required decoration - (ledgers) for the item type being dragged in the system

-(void)drawDragType:(const sscore_edit_type *)itemType 
        withContext:(CGContextRef)ctx topleft:(CGPoint)tl pos:(CGPoint)pos; 

Parameters

See Also

drawDragType:withContext:topleft:pos:

draw any required decoration - (ledgers) for the item type being dragged in the system

-(void)drawDragType:(const sscore_edit_type *)itemType 
        withContext:(CGContextRef)ctx topleft:(CGPoint)tl pos:(CGPoint)pos; 

Parameters

See Also

drawWithContext:at:magnification:

draw this system at the given point.

-(void)drawWithContext:(CGContextRef)ctx at:(CGPoint)tl 
        magnification:(float)magnification; 

Parameters

drawWithContext:at:magnification:colourRender:

draw this system at the given point allowing optional colouring of particular items/components in the layout.

-(enum sscore_error)drawWithContext:(CGContextRef)ctx at:(CGPoint)tl 
        magnification:(float)magnification colourRender:(SSColourRender*)colourRender; 

Parameters

dropItem:translate:

drop dragged existing item in the score (eg slur control point)

-(bool)dropItem:(SSEditItem *)item translate:(CGPoint)translate; 

Parameters

hitTest:

get an array of components which intersect a given a point in this system

-(NSArray<SSComponent*> *)hitTest:(CGPoint)p; 

Parameters

Return Value

array of intersecting SSComponent - empty if unlicensed

Discussion

a contents licence is required

includesBar:

does this system include the bar?

-(bool)includesBar:(int)barIndex; 

Return Value

true if this system includes the bar with given index

includesBarRange:

does this system include the bar range?

-(bool)includesBarRange:(const sscore_barrange*)barrange; 

Return Value

true if this system includes any bars in barrange

insertPosForTarget

calculate and return a suitable approximation to the insertion position for this target to show in the UI while dragging

-(CGPoint)insertPosForTarget:(SSTargetLocation*)target lr:(enum sscore_edit_leftrightlocation_e)lr; 

Parameters

Return Value

the insertion point in the system

See Also

insertPosForTarget:lr:

calculate and return a suitable approximation to the insertion position for this target to show in the UI while dragging

-(CGPoint)insertPosForTarget:(SSTargetLocation*)target lr:(enum sscore_edit_leftrightlocation_e)lr; 

Parameters

See Also

itemForComponent:

get the editable item for a SSComponent

-(SSEditItem*)itemForComponent:(SSComponent*)component; 

Return Value

item

itemForDirectionType:

get the editable item for a SSDirectionType

-(SSEditItem*)itemForDirectionType:(SSDirectionType*)directionType; 

Return Value

item

nearestDirectionComponentAt: maxDistance:

find the closest layout component within maxDistance of pos that is part of a direction (words etc)

-(SSComponent*)nearestDirectionComponentAt:(CGPoint)pos type:(enum sscore_direction_type)type 
        maxDistance:(float)maxDist; 

Parameters

Return Value

the closest note component

See Also

nearestDirectionComponentAt:type:maxDistance:

find the closest layout component within maxDistance of pos that is part of a direction (words etc)

-(SSComponent*)nearestDirectionComponentAt:(CGPoint)pos type:(enum sscore_direction_type)type 
        maxDistance:(float)maxDist; 

Parameters

See Also

nearestInsertTargetFor:at:

return the nearest valid target location to insert an item of given type in the score

-(SSTargetLocation*)nearestInsertTargetFor:(const sscore_edit_type *)itemType 
        at:(CGPoint)pos max:(float)max_distance; 

Parameters

Return Value

return the nearest valid target location at which the itemType can be inserted in the score. Return nil if not near a valid point

See Also

nearestInsertTargetFor:at:max:

return the nearest valid target location to insert an item of given type in the score

-(SSTargetLocation*)nearestInsertTargetFor:(const sscore_edit_type *)itemType 
        at:(CGPoint)pos max:(float)max_distance; 

Parameters

See Also

nearestNoteComponentAt:maxDistance:

find the closest layout component within maxDistance of pos that is part of a note (notehead,stem,dot,accidental etc)

-(SSComponent*)nearestNoteComponentAt:(CGPoint)pos 
        maxDistance:(float)maxDist; 

Parameters

Return Value

the closest note component

partIndexForYPos:

get the part index of the part enclosing the given y coordinate in this system

-(int)partIndexForYPos:(float)ypos; 

Parameters

Return Value

the 0-based part index

partLayout:

get staff measurement for the part in this system

-(SSStaffLayout*)staffLayout:(int)partIndex; 

Parameters

Return Value

staff measurements

See Also

pointsToFontSize:

get the pointsize of a UIFont (of type "Georgia") which will look exactly like a SeeScore direction with this fontsize

-(float)pointsToFontSize:(float)points; 

Parameters

Return Value

the fontsize to use in the call [UIFont fontWithName:at"Georgia" size:fontsize];

printTo:at:magnification:

draw this system at the given point with optimisation for printing (ie without special pixel alignment).

-(void)printTo:(CGContextRef)ctx at:(CGPoint)tl magnification:(float)magnification; 

Parameters

selectItem:part:bar:foreground:background:

select the item in the system/part/bar and colour it

-(void)selectItem:(sscore_item_handle)item_h part:(int)partIndex 
        bar:(int)barIndex foreground:(CGColorRef)fgCol background:(CGColorRef)bgCol; 

Parameters

staffIndexForYPos:

get the index of the staff within the part closest to the given y coordinate in this system

-(int)staffIndexForYPos:(float)ypos; 

Parameters

Return Value

the 0-based staff index - 0 for a single-staff part

staffLayout:

get staff measurement for the part in this system

-(SSStaffLayout*)staffLayout:(int)partIndex; 

Parameters

See Also

staffLocationForYPos:

from the ypos return above or below according to the ypos relative to the closest staff

-(enum sscore_system_stafflocation_e)staffLocationForYPos:(float)ypos; 

Parameters

Return Value

above/below relative to the staff

tiedRect:

get the bounding box of the tie which can be added to the right of the given notehead so we can draw it in temporarily

-(CGRect)tiedRect:(SSTargetLocation*)target; 

Parameters

Return Value

rectangle in cg units

updateLayout:newState:

update the layout to show the state in the sscore_state_container (called by state change handler)

-(void)updateLayout:(CGContextRef)ctx newState:(const sscore_state_container*)newstate; 

Parameters

Properties

barRange

the start bar index and number of bars for this system.

bounds

the bounding box of this system.

defaultSpacing

a default value for vertical system spacing

index

the index of this system from the top of the score. Index 0 is the topmost.

magnification

the magnification this system - a value of 1.0 approximates to a standard 6mm staff height as in a printed score

rawsystem

access the underlying C type

barRange

the start bar index and number of bars for this system.

@property (nonatomic,
    readonly) sscore_barrange barRange; 

bounds

the bounding box of this system.

@property (nonatomic,
    readonly) CGSize bounds; 

defaultSpacing

a default value for vertical system spacing

@property (nonatomic,
    readonly) float defaultSpacing; 

index

the index of this system from the top of the score. Index 0 is the topmost.

@property (nonatomic,
    readonly) int index; 

magnification

the magnification this system - a value of 1.0 approximates to a standard 6mm staff height as in a printed score

@property (nonatomic,
    readonly) float magnification; 

rawsystem

access the underlying C type

@property (nonatomic,
    readonly) sscore_system *rawsystem;