Tie

This library encapsulates Finale’s behavior for initializing FCTieMod endpoints, as well as providing other useful information about ties.

Functions

calc_tied_to

tie.calc_tied_to(note)

View source

Calculates the note that the input note could be (or is) tied to. For this function to work correctly across barlines, the input note must be from an instance of FCNoteEntryLayer that contains both the input note and the tied-to note.

@ [tie_must_exist] if true, only returns a note if the tie already exists.

Input Type Description
note FCNote the note for which to return the tied-to note
Return type Description
FCNote Returns the tied-to note or nil if none

calc_tied_from

tie.calc_tied_from(note)

View source

Calculates the note that the input note could be (or is) tied from. For this function to work correctly across barlines, the input note must be from an instance of FCNoteEntryLayer that contains both the input note and the tied-from note.

@ [tie_must_exist] if true, only returns a note if the tie already exists.

Input Type Description
note FCNote the note for which to return the tied-from note
Return type Description
FCNote Returns the tied-from note or nil if none

calc_tie_span

tie.calc_tie_span(note, for_tied_to, tie_must_exist)

View source

Calculates the (potential) start and end notes for a tie, given an input note. The input note can be from anywhere, including from the eachentry() iterator functions. The function returns 3 values:

  • A FCNoteLayerEntry containing both the start and and notes (if they exist). You must maintain the lifetime of this variable as long as you are referencing either of the other two values.
  • The potential or actual start note of the tie (taken from the FCNoteLayerEntry above).
  • The potential or actual end note of the tie (taken from the FCNoteLayerEntry above).

Be very careful about modifying the return values from this function. If you do it within an iterator loop from eachentry() or eachentrysaved() you could end up overwriting your changes with stale data from the iterator loop. You may discover that this function is more useful for gathering information than for modifying the values it returns.

Input Type Description
note FCNote the note for which to calculated the tie span
for_tied_to (optional) boolean if true, searches for a note tying to the input note. Otherwise, searches for a note tying from the input note.
tie_must_exist (optional) boolean if true, only returns notes for ties that already exist.
Return type Description
FCNoteLayerEntry A new FCNoteEntryLayer instance that contains both the following two return values.
FCNote The start note of the tie.
FCNote The end note of the tie.

calc_default_direction

tie.calc_default_direction(note, for_tieend, tie_prefs)

View source

Calculates the default direction of a tie based on context and FCTiePrefs but ignoring multi-voice and multi-layer overrides. It also does not take into account the direction being overridden in FCTieMods. Use tie.calc_direction to calculate the actual current tie direction.

Input Type Description
note FCNote the note for which to return the tie direction.
for_tieend boolean specifies that this request is for a tie_end.
tie_prefs (optional) FCTiePrefs use these tie prefs if supplied
Return type Description
number Returns either TIEMODDIR_UNDER or TIEMODDIR_OVER. If the input note has no applicable tie, it returns 0.

calc_direction

tie.calc_direction(note, tie_mod, tie_prefs)

View source

Calculates the current direction of a tie based on context and FCTiePrefs, taking into account multi-voice and multi-layer overrides. It also takes into account if the direction has been overridden in FCTieMods.

Input Type Description
note FCNote the note for which to return the tie direction.
tie_mod FCTieMod the tie mods for the note, if any.
tie_prefs (optional) FCTiePrefs use these tie prefs if supplied
Return type Description
number Returns either TIEMODDIR_UNDER or TIEMODDIR_OVER. If the input note has no applicable tie, it returns 0.

calc_connection_code

tie.calc_connection_code(note, placement, direction, for_endpoint, for_tieend, for_pageview, tie_prefs)

View source

Calculates the correct connection code for activating a Tie Placement Start Point or End Point in FCTieMod.

Input Type Description
note FCNote the note for which to return the code
placement number one of the TIEPLACEMENT_INDEXES values
direction number one of the TIEMOD_DIRECTION values
for_endpoint boolean if true, calculate the end point code, otherwise the start point code
for_tieend boolean if true, calculate the code for a tie end
for_pageview boolean if true, calculate the code for page view, otherwise for scroll/studio view
tie_prefs (optional) FCTiePrefs use these tie prefs if supplied
Return type Description
number Returns one of TIEMOD_CONNECTION_CODES. If the input note has no applicable tie, it returns TIEMODCNCT_NONE.

calc_placement

tie.calc_placement(note, tie_mod, for_pageview, direction, tie_prefs)

View source

Calculates the current placement of a tie based on context and FCTiePrefs.

Input Type Description
note FCNote the note for which to return the tie direction.
tie_mod FCTieMod the tie mods for the note, if any.
for_pageview bool true if calculating for Page View, false for Scroll/Studio View
direction number one of the TIEMOD_DIRECTION values or nil (if you don’t know it yet)
tie_prefs (optional) FCTiePrefs use these tie prefs if supplied
Return type Description
number TIEPLACEMENT_INDEXES value for start point
number TIEPLACEMENT_INDEXES value for end point

activate_endpoints

tie.activate_endpoints(note, tie_mod, for_pageview, tie_prefs)

View source

Activates the placement endpoints of the input tie_mod and initializes them with their default values. If an endpoint is already activated, that endpoint is not touched.

Input Type Description
note FCNote the note for which to return the tie direction.
tie_mod FCTieMod the tie mods for the note, if any.
for_pageview bool true if calculating for Page View, false for Scroll/Studio View
tie_prefs (optional) FCTiePrefs use these tie prefs if supplied
Return type Description
boolean returns true if anything changed

calc_contour_index

tie.calc_contour_index(note, tie_mod, for_pageview, direction, tie_prefs)

View source

Calculates the current contour index of a tie based on context and FCTiePrefs.

Input Type Description
note FCNote the note for which to return the tie direction.
tie_mod FCTieMod the tie mods for the note, if any.
for_pageview bool true if calculating for Page View, false for Scroll/Studio View
direction number one of the TIEMOD_DIRECTION values or nil (if you don’t know it yet)
tie_prefs (optional) FCTiePrefs use these tie prefs if supplied
Return type Description
number CONTOUR_INDEXES value for tie
number calculated length of tie in EVPU

activate_contour

tie.activate_contour(note, tie_mod, for_pageview, tie_prefs)

View source

Activates the contour fields of the input tie_mod and initializes them with their default values. If the contour fields are already activated, nothing is changed. Note that for interpolated Medium span types, the interpolated values may not be identical to those calculated by Finale, but they should be close enough to make no appreciable visible difference.

Input Type Description
note FCNote the note for which to return the tie direction.
tie_mod FCTieMod the tie mods for the note, if any.
for_pageview bool true if calculating for Page View, false for Scroll/Studio View
tie_prefs (optional) FCTiePrefs use these tie prefs if supplied
Return type Description
boolean returns true if anything changed