ntnidx
References
This object references notation items found within a staff. An existing instance is available as nwc.ntnidx
in the nwc
module. Additional ntnidx
reference objects must be declared during the plugin init
context. This is done using the new method:
local myNotationPtr = nwc.ntnidx.new()
Care should be taken when sharing global object instances across multiple event methods, such as using the same object references between
create
,draw
, andwidth
events. These events can run concurrently whilenwcui
methods are invoked. For this reason, object references used across calls tonwcui
methods should not be shared with other event handlers.
The following methods are provided in the ntnidx
object:
Available Methods
The following methods are available from ntnidx
:
This creates a new ntnidx
reference, which can only be done during the plugin's init
context.
All ntnidx
objects always reference the current object when first used in an event hook.
This sets a ntnidx
reference back to the current object.
{ntnidx}:(operators) < <= > >= ==, Returns Boolean
ntnidx
and drawpos
objects can be compared using the standard operators. An object is less than other objects when it is located earlier in the staff.
local idx1 = nwc.ntnidx.new()
local idx2 = nwc.ntnidx.new()
...
if idx1 < idx2 then
-- idx1 is located before idx2 on the staff
end
...
if idx2 > 0 then
-- idx2 is located after the currently active object
end
{ntnidx}:indexOffset(), Returns IntegerOffset
This returns the offset index from the current object.
{ntnidx}:sppOffset(), Returns IntegerOffset
This returns the relative song position pointer offset from the current object. This value is suitable for use in nwcplay functions. This value will be negative when the current ntnidx
is behind the current anchoring index.
{ntnidx}:objType(), Returns 'ObjType'
This method returns the name of the current staff object.
{ntnidx}:objProp('PropertyName'), Returns 'PropertyValue'
This returns the nwctxt property value for the current object, or Nil if this property would not appear in the nwctxt depiction of the object.
{ntnidx}:staffPos(), returns Number
This returns the staff position of the object. This works best with expression and objects.
{ntnidx}:durationBase([#NoteNumber]), returns nwc.txt.NoteDuration
or nil
Returns the note position's named duration using the nwc.txt.NoteDuration
enumeration.
Returns nil if this is not a valid note or rest position.
{ntnidx}:noteDurBase([#NoteNumber]), returns nwc.txt.NoteDurBase
or nil
Returns the note position's named duration using the nwc.txt.NoteDurBase
enumeration.
Returns nil if this is not a valid note or rest position.
{ntnidx}:isBeamed([#NoteNumber]), returns 'BeamStatus' or false or nil
Returns First, Middle, or End when a valid note position is part of a beamed group. Returns false
when a valid note position is not part of a beam.
{ntnidx}:isDotted([#NoteNumber]), returns #Number or false or nil
If this is a note position and is dotted, then the number of dots are returned. Returns false
if this note position is not dotted. Returns nil if this is not a valid note or rest position.
{ntnidx}:isDotted([#NoteNumber]), returns #Number or false or nil
If this is a note position and is dotted, then the number of dots are returned. Returns false
if this note position is not dotted. Returns nil if this is not a valid note or rest position.
{ntnidx}:isGrace([#NoteNumber]), returns Boolean or nil
Returns true
when a valid note position is a grace note.
{ntnidx}:isLyricPos([#NoteNumber]), returns Boolean or nil
Returns true
when a valid note position accepts attached lyric text.
{ntnidx}:isMelisma([#NoteNumber]), returns Boolean or nil
Returns true
when a valid note position accepts attached lyric text, and the position starts a melisma.
{ntnidx}:isMute([#NoteNumber]), returns Boolean or nil
Returns true
when a valid note position has been specifically muted by the user.
{ntnidx}:isSlurIn([#NoteNumber]), returns Boolean or nil
Returns true
when a valid note position receives a built-in slur from earlier in the staff.
{ntnidx}:isSlurOut([#NoteNumber]), returns Boolean or nil
Returns true
when a valid note position starts or extends a slur.
{ntnidx}:isSplitVoice([#NoteNumber]), returns Boolean or nil
Returns true
when a valid note position contains dual voicing, such as a split stem chord or a rest chord.
{ntnidx}:isTieIn([#NoteNumber]), returns Boolean or nil
Returns true
when a valid note position receives a note tie from earlier in the staff.
{ntnidx}:isTieOut([#NoteNumber]), returns Boolean or nil
Returns true
when a valid note position starts or extends a tie to the next note at its position.
{ntnidx}:isCresc([#NoteNumber]), returns Boolean or nil
Returns true
when a valid note position has been marked with Cresc.
{ntnidx}:isDecresc([#NoteNumber]), returns Boolean or nil
Returns true
when a valid note position has been marked with Decresc.
{ntnidx}:articulationCount([#NoteNumber]), returns Number or nil
When on a valid note position, this returns the number of articulations currently applied to it.
{ntnidx}:isAccented([#NoteNumber]), returns Boolean or nil
Returns true
when a valid note position has been marked with an Accent.
{ntnidx}:isMarcato([#NoteNumber]), returns Boolean or nil
Returns true
when a valid note position has been marked with Marcato.
{ntnidx}:isStaccatissimo([#NoteNumber]), returns Boolean or nil
Returns true
when a valid note position has been marked with Staccatissimo.
{ntnidx}:isStaccato([#NoteNumber]), returns Boolean or nil
Returns true
when a valid note position has been marked with Staccato.
{ntnidx}:isTenuto([#NoteNumber]), returns Boolean or nil
Returns true
when a valid note position has been marked with Tenuto.
{ntnidx}:isTriplet([#NoteNumber]), returns 'TripletPosition' or false or nil
Returns First, Middle, or End when a valid note position is part of a triplet grouping. Returns false
when a valid note position is not part of a triplet.
{ntnidx}:propTable(), Returns PropertyTable
This method returns a table containing the nwctxt properties for the object.
{ntnidx}:userType(), Returns 'UserObjType'
This method returns the type of the current object. If the item is not a custom object (User type), then nil
is returned.
{ntnidx}:userProp('PropertyLabel'), Returns 'PropertyValue'
This returns the value for any custom property that exists in the current object, or nil
if this is not a custom User
object. This value is filtered through the object's spec
table.
{ntnidx}:noteCount(), Returns #NoteCount
This returns the number of notes found in the object.
{ntnidx}:notePos(#NoteNumber), Returns #NotePosition
This returns the staff Y coordinate for the given NoteNumber. The NoteNumber must start from 1, and will yield valid positions up through {ntnidx}:noteCount() note numbers. This function returns nil
if there is no such note number.
{ntnidx}:notePitchPos(#NoteNumber), Returns 'PitchPosText'
This returns the PitchPos nwctxt for the given NoteNumber. The NoteNumber must start from 1, and will yield valid positions up through {ntnidx}:noteCount(). This function returns nil
if there is no such note number.
Unlike the notePos
function, the position information contained in the PitchPosText
uses an absolute staff position, and would need to be normalized with an object's current staff position when drawing.
{ntnidx}:stemDir(#NoteNumber), Returns -1,1, or nil
This returns a number indicating the stem direction for any valid note position. This returns what is essentially a voicing direction for rests and notes without an actual stem.
{ntnidx}:find(Action,['What',...]), Returns Boolean
This method can be used to find other items on the same staff as the current object. The following values are supported for the Action
field:
- nwc.ntnidx
Finds thentnidx
referenced object. - nwc.drawpos
Finds thedrawpos
object. - 'span'
Finds the last item that completes the span, which is indicated by the same value pair as is returned by thespan
event method. Returns false if the span could not be completed. - 'next'
Finds the next match to the right of the current object. - 'prior'
Finds the prior match to the left of the current object. - 'first'
Finds the first match from the start of the staff. - 'last'
Finds the last match from the end of the staff.
The following values are supported for the optional 'What' field:
-
user, ['UserObjType', 'UserPropertyLabel']
This finds a matching custom object. If 'UserObjType' is indicated, then only objects of this type will be matched. If 'UserPropertyLabel' is indicated, then only objects that contain a value for this property will be matched. The object's staticspec
table is not used in this process. -
objType, ['Type', ...]
This finds a matching object type, as returned from theobjType()
method. Multiple object type strings can be included in the method call, and this will match against any included type. -
duration
This matches any non-grace note or rest items. -
note
This matches any items that contain one or more notes. -
noteOrRest
This matches any note or rest item, including grace notes. -
noteRestBar
This matches any note, rest, or bar item, including grace notes and multi-measure rests. -
noteAt, #NotePosition
This matches any item that contains a note at the designated NotePosition. -
bar
This matches any bar line. -
clef
This matches any clef. -
key
This matches any key signature. -
timesig
This matches any time signature. -
dynamic
This matches any dynamic.
If a match is found, then the ntnidx
object is moved to this new position, and true
is returned.
If a match is not found, then the ntnidx
object is unchanged, and false
is returned.