`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, and width events. These events can run concurrently while nwcui methods are invoked. For this reason, object references used across calls to nwcui methods should not be shared with other event handlers.

The following methods are provided in the ntnidx object:

new	reset	< <= > >= ==
find	articulationCount	indexOffset	durationBase
isBeamed	isDotted	isCresc	isDecresc
isAccented	isMarcato	isStaccatissimo	isStaccato	isTenuto
isGrace	isLyricPos	isMelisma	isMute	isSlurIn
isSlurOut	isSplitVoice	isTieIn	isTieOut	isTriplet
noteCount	noteDurBase	notePos	notePitchPos
objProp	objType	propTable	userProp	userType
sppOffset	staffPos	stemDir

Available Methods

The following methods are available from ntnidx:

nwc.ntnidx.new()

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.

{ntnidx}:reset()

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 the ntnidx referenced object.
nwc.drawpos
Finds the drawpos object.
'span'
Finds the last item that completes the span, which is indicated by the same value pair as is returned by the span 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 static spec table is not used in this process.
objType, ['Type', ...]
This finds a matching object type, as returned from the objType() 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.

ntnidx References

Available Methods

`ntnidx` References