The `nwc` Object

The nwc object provides initialization and debugging methods for use the NoteWorthy Composer plugin system. These include:

txt	VERSIONDATE	VERSION	VERSIONTEXT	VERSIONKEY
drawpos	ntnidx
churnCount	churnRate	debug	memusage
getRunContext	hasTypeface	isset	rawget

nwc.VERSIONDATE

This is a constant string that indicates the build day of the current program, in the form YYYYMMDD. This is the easiest way to establish the API vintage of the current environment.

nwc.VERSION

This is a constant that indicates the current version of nwctxt when written to a file. It should generallly indicate the current program version as well, but VERSIONKEY will uniquely identify the sepcific instance of a program version.

nwc.VERSIONTEXT

This is a constant that provides the user readable version text for the program.

nwc.VERSIONKEY

This is a constant that uniquely identifies the current plugin API. It uses a series of version numbers, separated by dots, with each subsequent number being a more minor version indicator. There can be up to five version point release indicators, such as 2.74.97.35.1.

nwc.ntnidx

This is the default instance of a ntnidx reference object. It is used to reference an existing notation object in a NWC staff.

nwc.drawpos

This is the default instance of a drawpos reference object. It is used to reference an existing notation drawing position while running an object's width and draw methods.

nwc.getRunContext(), Returns 'context1','context2'

This returns a value pair that generally reveals the packages that are available in the currently running context. The returns pairs include:

Returns	Description
`init` nil	This is generally used while a script is being compiled and loaded into the NWC environment. The nwc package is available.
`obj` `edit`	This is the context used for the `create`, `spin`, `onChar`, and `menuClick` event methods. Available packages include nwc, nwc.ntnidx, and nwcui (except for `spin`).
`obj` `fetch`	This is the context used for the `menuInit` and `span` event methods. Available packages include nwc and nwc.ntnidx.
`obj` `predraw`	This is the context used for the `width` event method. Available packages include nwc, nwc.ntnidx, and some parts of nwcdraw and nwc.drawpos.
`obj` `draw`	This is the context used for the `draw` event method. Available packages include nwc, nwc.ntnidx, nwcdraw and nwc.drawpos.
`obj` `vplay`	This is the context used for the `transpose` event method. Available packages include nwc, nwc.ntnidx, and read-only parts of nwcplay.
`obj` `play`	This is the context used for the `play` event method. Available packages include nwc, nwc.ntnidx, and nwcplay.

nwc.hasTypeface('font-typeface'), Returns Boolean

This method can be used to identify if a particular font typeface is available on the system before trying to use it. For best performance, it is recommended that this action be done within the plugin startup code. When the plugin is running in the Viewer, this method will trigger a dynamic load of eligible typefaces.

nwc.isset(t,'PropertyName'), Returns Boolean

This method can be used to determine if an object property is currently defined in t, which is passed into an object's event method.

nwc.rawget(t,'PropertyName'), Returns 'PropertyValue'

This method can be used to retrieve the raw property value in the object's property table t. This method can be used to bypass the object's spec table. This also works for ntnidx user object refences.

nwc.memusage(), Returns Integer

This returns how much memory (in KB) is used by the Lua machine.

nwc.churnCount(), Returns Integer

This returns the count of new memory requests since the plugin engine was started.

Note that printing or displaying this number will often generate memory churn when the number is converted to a string.

nwc.churnRate(), Returns Number

This returns a ratio of memory requests versus plugin method calls. Lower numbers are better.

Note that printing or displaying this result will often generate memory churn when the number is converted to a string.

nwc.debug('Message',...)

This directs a message to the debug console. You can also use print to do the same thing.

nwc.txt

This is a collection of commonly used text data types used by NoteWorthy Composer. It can be iterated by a script to discover all of its contents. The following script yields the contents for use in the nwcut environment:

print('| nwc.txt | Contains |')
print('|:--------:|:---------|')
local typnames = {}
for typname in pairs(nwc.txt) do table.insert(typnames,typname) end
table.sort(typnames)
for i,typname in ipairs(typnames) do
    print('| `'..typname..'` | ',tostring(nwc.txt[typname]),' |')
end

The plugin environment has slightly different contents, as shown here:

nwc.txt	Contains
`AttachLyricSyllable`	Default,Always,Never
`BarLineType`	Single,Double,BrokenSingle,BrokenDouble,SectionOpen,SectionClose,LocalRepeatOpen,LocalRepeatClose,MasterRepeatOpen,MasterRepeatClose,Transparent
`BoundaryTypes`	Reset,NewSize,Collapse,EndCollapse,Gap,NewSystem
`ClefType`	Treble,Bass,Alto,Tenor,Percussion
`DrawFillStyle`	fill,stroke,strokeandfill
`DrawPenStyle`	solid,dot,dash
`DrawTextAlign`	left,center,right
`DrawTextVAlign`	top,middle,baseline,bottom
`DynamicLevels`	ppp,pp,p,mp,mf,f,ff,fff
`DynamicVariance`	Crescendo,Decrescendo,Diminuendo,Rinforzando,Sforzando
`ExpressionJustify`	Left,Center,Right
`ExpressionPlacement`	BestFit,BestFitForward,AsStaffSignature,AtNextNote
`FlowDirTypes`	Coda,Segno,Fine,ToCoda,DaCapo,DCalCoda,DCalFine,DalSegno,DSalCoda,DSalFine
`ItemColor`	Default,Highlight 1,Highlight 2,Highlight 3,Highlight 4,Highlight 5,Highlight 6,Highlight 7
`ItemVisibility`	Default,Always,TopStaff,SingleStaff,MultiStaff,Never
`Lyric2NoteAlignment`	Start of Accidental/Note,Standard Rules
`LyricAlignment`	Bottom,Top
`MPCControllers`	tempo,vol,pan,bc,pitch,mod,foot,portamento,datamsb,bal,exp,fx1,fx2,reverb,tremolo,chorus,detune,phaser
`MPCStyle`	Absolute,Linear Sweep
`MarkerTargets`	Articulation,Slur,Triplet
`MeasureNumStyles`	None,Plain,Circled,Boxed
`NoteConnectState`	None,First,Middle,End
`NoteDurBase`	Whole,Half,4th,8th,16th,32nd,64th
`NoteDuration`	Whole,Half,Quarter,Eighth,Sixteenth,Thirtysecond,Sixtyfourth
`NoteScale`	A,B,C,D,E,F,G
`ObjLabels`	Clef,Key,Bar,Ending,Instrument,TimeSig,Tempo,Dynamic,Note,Rest,Chord,SustainPedal,Flow,MPC,TempoVariance,DynamicVariance,PerformanceStyle,Text,RestChord,User,Spacer,RestMultiBar,Boundary,Marker
`OctaveShift`	None,Octave Up,Octave Down
`PageMarginFields`	Left,Top,Right,Bottom,Mirror
`PageSetupFields`	TitlePage,JustifyVertically,PrintSystemSepMark,ExtendLastSystem,DurationPadding,PageNumbers,StaffLabels,BarNumbers,StartingBar,AllowLayering
`PerformanceStyle`	Ad Libitum,Animato,Cantabile,Con brio,Dolce,Espressivo,Grazioso,Legato,Maestoso,Marcato,Meno mosso,Poco a poco,Più mosso,Semplice,Simile,Solo,Sostenuto,Sotto Voce,Staccato,Subito,Tenuto,Tutti,Volta Subito
`PlayMidiCmds`	noteOff,noteOn,keyAftertouch,controller,patch,channelAftertouch,pitchBend
`SongInfoFields`	Title,Author,Lyricist,Copyright1,Copyright2,Comments
`SpanTypes`	notes,syllables,bars,ticks,items
`SpecialSignatures`	Standard,Common,AllaBreve
`StaffEndBarLineType`	Section Close,Master Repeat Close,Single,Double,Open (hidden)
`StaffLabelStyles`	None,First System,Top Systems,All Systems
`StaffProperties`	Name,Label,LabelAbbr,Group,EndingBar,BoundaryTop,BoundaryBottom,Lines,BracketWithNext,BraceWithNext,ConnectBarsWithNext,LayerWithNext,MultiPartDotPlacement,Color,Muted,Volume,StereoPan,Device,Channel
`SustainPedalStatus`	Down,Released
`TempoBase`	Eighth,Eighth Dotted,Quarter,Quarter Dotted,Half,Half Dotted
`TempoVariance`	Breath Mark,Caesura,Fermata,Accelerando,Allargando,Rallentando,Ritardando,Ritenuto,Rubato,Stringendo
`TextExpressionFonts`	StaffSymbols,StaffCueSymbols,StaffItalic,StaffBold,StaffLyric,PageTitleText,PageText,PageSmallText,User1,User2,User3,User4,User5,User6
`TieDir`	Default,Upward,Downward
`UserObjClassTypes`	Standard,StaffSig,Span
`UserPropValueTypes`	text,enum,bool,int,float

The nwc Object

The `nwc` Object