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:

The following values are supported for the optional 'What' field:

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.

Copyright © 2019 NoteWorthy Software™, Inc.
All Rights Reserved.