Finale PDK Framework 0.67
Public Types | Public Member Functions | List of all members
FCLuaScriptItem Class Reference

Class that represents a single Lua script item. This class is not part of the C++ PDK Framework. More...

#include <fflua_luascriptitem.h>

Inheritance diagram for FCLuaScriptItem:
__FCBase

Public Types

enum  LUASCRIPT_REQVERSION_TYPES {
  REQVERSIONTYPE_MINIMUM_FINALE = 0 , REQVERSIONTYPE_MAXIMUM_FINALE , REQVERSIONTYPE_MINIMUM_FINALE_MAJOR , REQVERSIONTYPE_MAXIMUM_FINALE_MAJOR ,
  REQVERSIONTYPE_MINIMUM_LUAX1000 , REQVERSIONTYPE_MAXIMUM_LUAX1000
}
 Settings used to get required version information for a script. More...
 
- Public Types inherited from __FCBase
enum  PDKFRAMEWORK_CLASSID {
  FCID_UNKNOWN = 0 , FCID_ACCIDENTALMOD , FCID_ALLOTMENT , FCID_ARTICULATION ,
  FCID_ARTICULATIONDEF , FCID_BACKWARDREPEAT , FCID_BASELINE , FCID_BEAMMOD ,
  FCID_BEATCHARTELEMENT , FCID_BROKENBEAMMOD , FCID_CATEGORYDEF , FCID_CELLCLEFCHANGE ,
  FCID_CELLFRAMEHOLD , FCID_CELLGRAPHIC , FCID_CELLTEXT , FCID_CENTERSMARTSHAPE ,
  FCID_CHORD , FCID_CHORDPREFS , FCID_CHORDSUFFIXELEMENT , FCID_CHORUSSYLLABLE ,
  FCID_CLEFDEF , FCID_COMPOSITETIMESIGBOTTOMELEMENT , FCID_COMPOSITETIMESIGTOPELEMENT , FCID_CROSSSTAFFMOD ,
  FCID_CUSTOMSMARTLINEDEF , FCID_CUSTOMSTEMMOD , FCID_DISTANCEPREFS , FCID_DOTMOD ,
  FCID_ENCLOSURE , FCID_ENDINGREPEAT , FCID_ENTRYALTERMOD , FCID_EXECUTABLESHAPEDEF ,
  FCID_EXPRESSION , FCID_FONTINFO , FCID_FONTPREFS , FCID_FREEZESYSTEM ,
  FCID_FRETBOARDSTYLEDEF , FCID_FRETBOARDSTYLEDEFS , FCID_FRETBOARDGROUPDEF , FCID_FRETBOARDGROUPDEFS ,
  FCID_FRETINSTRUMENTDEF , FCID_GENERALPREFS , FCID_GRIDSGUIDESPREFS , FCID_GROUP ,
  FCID_GROUPNAMEPOSITIONPREFS , FCID_HUMANPLAYBACKPREFS , FCID_INDEPENDENTCELLDETAIL , FCID_INSTRUMENTDEF ,
  FCID_INSTRUMENTPLAYBACKDATA , FCID_KEYSIGNATURE , FCID_LAYERPREFS , FCID_LYRICSBASELINE ,
  FCID_LYRICSPREFS , FCID_MEASURE , FCID_MEASURENUMBERREGION , FCID_METATOOLASSIGNMENT ,
  FCID_MIDIEXPRESSION , FCID_MISCDOCPREFS , FCID_MULTIMEASUREREST , FCID_MULTIMEASURERESTPREFS ,
  FCID_MULTISTAFFINSTRUMENT , FCID_MULTISTAFFINSTRUMENTS , FCID_MUSICCHARACTERPREFS , FCID_MUSICSPACINGPREFS ,
  FCID_NUMBER , FCID_NOTEHEADMOD , FCID_OTHERINCI , FCID_PERCUSSIONLAYOUTNOTE ,
  FCID_PERCUSSIONSTAFF , FCID_PERFORMANCEMOD , FCID_PAGE , FCID_PAGEFORMATPREFS ,
  FCID_PAGEGRAPHIC , FCID_PAGETEXT , FCID_PART , FCID_PARTEXTRACTPREFS ,
  FCID_PARTSCOPEPREFS , FCID_PARTSTAFFVOICING , FCID_PERCUSSIONNOTEMOD , FCID_PIANOBRACEPREFS ,
  FCID_PLAYBACKPREFS , FCID_RAWTEXT , FCID_REPEATPREFS , FCID_SECONDARYBEAMBREAKMOD ,
  FCID_BEAMEXTENSIONMOD , FCID_SECTIONSYLLABLE , FCID_SEPARATEMEASURENUMBER , FCID_SEPARATEPLACEMENT ,
  FCID_SHAPEDEF , FCID_SHAPEEXPRESSIONDEF , FCID_SLURCONTOURPREFS , FCID_SIZEPREFS ,
  FCID_SMARTSHAPE , FCID_SMARTSHAPEENTRYMARK , FCID_SMARTSHAPEMEASUREMARK , FCID_SMARTSHAPEPREFS ,
  FCID_STAFF , FCID_STAFFLIST , FCID_STAFFNAMEPOSITION , FCID_STAFFNAMEPOSITIONPREFS ,
  FCID_STAFFSTYLEASSIGN , FCID_STAFFSTYLEDEF , FCID_STAFFSYSTEM , FCID_STEMCONNECTIONTABLE ,
  FCID_STEMMOD , FCID_STRING , FCID_SYLLABLEENTRYMOD , FCID_SYSTEMSTAFF ,
  FCID_TABLATURENOTEMOD , FCID_TEMPOELEMENT , FCID_TEXTBLOCK , FCID_TEXTEXPRESSIONDEF ,
  FCID_TEXTREPEAT , FCID_TEXTREPEATDEF , FCID_TIEMOD , FCID_TIEPREFS ,
  FCID_TIECONTOURPREFS , FCID_TIEPLACEMENTPREFS , FCID_TIMESIGNATURE , FCID_TUPLET ,
  FCID_TUPLETPREFS , FCID_VERSESYLLABLE
}
 Constants for the GetClassID method. More...
 
enum  MEASUREMENTUNITS {
  MEASUREMENTUNIT_DEFAULT = UNIT_DEFAULT , MEASUREMENTUNIT_EVPUS = UNIT_EVPUS , MEASUREMENTUNIT_INCHES = UNIT_INCHES , MEASUREMENTUNIT_CENTIMETERS = UNIT_CENTS ,
  MEASUREMENTUNIT_POINTS = UNIT_POINTS , MEASUREMENTUNIT_PICAS = UNIT_PICAS , MEASUREMENTUNIT_SPACES = UNIT_SPACES , MEASUREMENTUNIT_MILLIMETERS = 100
}
 Constants for Finale's standard measurement units. More...
 

Public Member Functions

const char * ClassName () const override
 Returns the name of the class, for diagnostic purposes. This method MUST be overwritten in each child class. More...
 
bool IsExecuting () const
 Returns true if the script associated with this script item is currently executing. More...
 
const char * GetFilePath () const
 Returns the fully-qualified file path for the script. More...
 
const char * GetMenuItemText () const
 Returns the menu item text for the script. More...
 
const char * GetUndoText () const
 Returns the undo text for the script. More...
 
const char * GetDescription () const
 Returns the description for the script. More...
 
const char * GetPrefix () const
 Returns the prefix for the script. More...
 
bool GetDebug () const
 Return true if the script should be run in debug mode. More...
 
bool GetLoadAsString () const
 Return true if the script should be loaded as a string. More...
 
int GetExecutableIndex () const
 Returns the executable index for this script. More...
 
bool GetVersionCompatible () const
 If false, this script is not compatible with either the running Finale or the running Lua plugin version or both. More...
 
EVERSION GetRequiredVersion (int versiontype) const
 Returns a required version number from one of the LUASCRIPT_REQVERSION_TYPES constants. More...
 
FCStringCreateFinalePluginValue (const char *fieldname)
 Return the requested finaleplugin value. More...
 
void SetMenuItemText (const char *value)
 Sets the menu item text for the script. More...
 
void SetUndoText (const char *value)
 Sets the undo text for the script. More...
 
void SetDescription (const char *value)
 Sets the description for the script. More...
 
void SetPrefix (const char *value)
 Sets the prefix for the script. More...
 
void SetDebug (bool state)
 Sets if the script should be run in debug mode. More...
 
void SetLoadAsString (bool state)
 Sets if the script should be loaded as a string. More...
 
- Public Member Functions inherited from __FCBase
virtual const PDKFRAMEWORK_CLASSID GetClassID () const
 Returns the internal class ID for the PDK Framework class. This is implemented mostly because Lua has problems to resolve the true classes of inherited objects. More...
 
virtual ~__FCBase ()
 Virtual destructor, so all inherited classes get the virtual destructor.
 
void DebugMsgInt (const char *pszPrefixText, int i)
 Creates a simple Message Box for debug purposes. The text appears with the extra digit (in decimal presentation) appearing afterwards. More...
 
void DebugMsgHex (const char *pszPrefixText, int i)
 Creates a simple Message Box for debug purposes. The text appears with the extra digit (as a hexadecimal number) appearing afterwards. More...
 
void DebugMsgString (const char *pszPrefixText, const char *thestring)
 Creates a simple Message Box for debug purposes. The text appears with the extra string appearing afterwards. More...
 
void DebugMsg (const char *pszMsg)
 Creates a simple Message Box for debug purposes with just one text string. More...
 
void DebugOutMenuInfo (FCUI *pUI, int menuixd_horiz, int menuixd_vert) const
 Outputs the menu command info for debugging purposes. More...
 
int DebugOutFormat (const char *fmt,...)
 Outputs debug text using C style "printf" syntax. More...
 
virtual void DebugDump ()
 Outputs the class data/information for debugging purposes. More...
 
virtual void DebugDataDump ()
 Outputs a memory dump of the data block in the object for debugging purposes. More...
 
virtual void DebugDataByteArrayDump ()
 Outputs a memory dump of the data block in the object for debugging purposes, as a C++ byte array. More...
 
void Set16BitFlag (FLAG_16 *flag, FLAG_16 flagbits, bool state)
 Sets a 16 bit flag. More...
 
void Set32BitFlag (FLAG_32 *flag, FLAG_32 flagbits, bool state)
 Sets/resets a 32 bit flag, by using a bit mask. More...
 
bool GetBitFlag (FLAG_32 flag, FLAG_32 flagbits) const
 Gets a state from flag bits. Returns true if any bit in the mask is set. More...
 
int GetBitCount (FLAG_32 flag)
 Returns the total number of set bits in a 32-bit unsigned int.
 
void SetSpecific32Bit (FLAG_32 *flag, int bitnumber, bool state)
 Sets/resets a single bit in a 32 bit flag, by specifying one specific bit. More...
 
void SetUserData (void *pData)
 Sets the user data attached to the instance of an object. More...
 
void SetUserData2 (void *pData)
 Sets the additional user data attached to the instance of an object. More...
 
void * GetUserData () const
 Gets the user data attached to the instance of an object. More...
 
void * GetUserData2 () const
 Gets the additional user data attached to the instance of an object. More...
 
virtual bool IsIdentical (__FCBase *pCompareObject)
 Returns true if the data in the passed object is considered to be identical to the current object, otherwise false. More...
 
void StoreXML_String (tinyxml2::XMLElement *pParentNode, const char *pszElementName, FCString *pStringValue)
 Helper function to store FCString objects in the XML file. More...
 
void StoreXML_Integer (tinyxml2::XMLElement *pParentNode, const char *pszElementName, int value)
 Helper function to store integer objects in the XML file. More...
 
void StoreXML_Bool (tinyxml2::XMLElement *pParentNode, const char *pszElementName, bool value)
 Helper function to store boolean objects in the XML file. More...
 
void StoreXML_StringAttribute (tinyxml2::XMLElement *pNode, const char *pszAttributeName, FCString *pStringValue)
 Helper function to store FCString objects in the XML file, as an attribute to a node. More...
 
void StoreXML_IntegerAttribute (tinyxml2::XMLElement *pNode, const char *pszAttributeName, int value)
 Helper function to store integer objects in the XML file, as an attribute to a node. More...
 
void StoreXML_BoolAttribute (tinyxml2::XMLElement *pNode, const char *pszAttributeName, bool value)
 Helper function to store boolean objects in the XML file, as an attribute to a node. More...
 
void StoreXML_FloatAttribute (tinyxml2::XMLElement *pNode, const char *pszAttributeName, float value)
 Helper function to store floating point objects in the XML file, as an attribute to a node. More...
 
virtual void StoreToXML (tinyxml2::XMLElement *pParentNode)
 Virtual method that is used to store an object's data. More...
 
bool ReadXML_String (tinyxml2::XMLElement *pParentNode, const char *pszElementName, FCString *pStringValue)
 Helper method to read FCString objects from the XML file. More...
 
bool ReadXML_Integer (tinyxml2::XMLElement *pParentNode, const char *pszElementName, int *pValue)
 Helper method to read integer objects from the XML file. More...
 
bool ReadXML_Bool (tinyxml2::XMLElement *pParentNode, const char *pszElementName, bool *pValue)
 Helper method to read boolean objects from the XML file. More...
 
bool ReadXML_StringAttribute (tinyxml2::XMLElement *pNode, const char *pszAttributeName, FCString *pStringValue)
 Helper method to read FCString objects from the XML file, as an attribute to a node. More...
 
bool ReadXML_IntegerAttribute (tinyxml2::XMLElement *pNode, const char *pszAttributeName, int *pValue)
 Helper method to read integer objects from the XML file, as an attribute to a node. More...
 
bool ReadXML_BoolAttribute (tinyxml2::XMLElement *pNode, const char *pszAttributeName, bool *pValue)
 Helper method to read boolean objects from the XML file, as an attribute to a node. More...
 
bool ReadXML_FloatAttribute (tinyxml2::XMLElement *pNode, const char *pszAttributeName, float *pValue)
 Helper method to read floating point objects from the XML file, as an attribute to a node. More...
 
virtual bool ReadFromXML (tinyxml2::XMLElement *pParentNode)
 Virtual method that is used to read object data. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from __FCBase
static void DebugOutPtr (const char *pszPrefixText, void *ptr)
 Static method that outputs a line for debugging purposes. The prefix text appears with the extra ptr (in hexadeximal representation) appearing afterwards. More...
 
static void DebugOutInt (const char *pszPrefixText, int i)
 Static method that outputs a line for debugging purposes. The text appears with the extra digit (in decimal presentation) appearing afterwards. More...
 
static void DebugOutFloat (const char *pszPrefixText, double f)
 Static method that outputs a line for debugging purposes. The text appears with the extra float value appearing afterwards. More...
 
static void DebugOutTag (const char *pszPrefixText, EXTAG extag)
 Static method that outputs a line for debugging purposes. The text appears with the EXTAG (in text) appearing afterwards. More...
 
static void DebugOutHex (const char *pszPrefixText, int i)
 Static method that outputs a line for debugging purposes. The text appears with the extra digit (in hexadecimal presentation) appearing afterwards. More...
 
static void DebugOutBin (const char *pszPrefixText, int i)
 Static method that outputs a line for debugging purposes. The text appears with the extra digit (in binary presentation) appearing afterwards. More...
 
static void DebugOutString (const char *pszPrefixText, const char *thestring)
 Static method that outputs a line for debugging purposes (C string version). The text appears with the extra string appearing afterwards. More...
 
static void DebugOutString (const char *pszPrefixText, FCString *pString)
 Static method that outputs a line for debugging purposes (FCString version). The text appears with the extra string appearing afterwards. More...
 
static void DebugOutBool (const char *pszPrefixText, bool state)
 Static method that outputs a line for debugging purposes. The boolean state appears afterwards as either "TRUE" or "FALSE". More...
 
static void DebugOutBlock (const void *pBuffer, int startoffset, int size)
 Static method that outputs a memory block for debugging purposes. Eight bytes per line will appear (as hex digits) until the whole memory block is dumped. More...
 
static void DebugOutByteArrayBlock (const void *pBuffer, int startoffset, int size)
 Static method that outputs a memory block for debugging purposes. Eight bytes per line will appear (as hex digits) as a C++ onebyte array, until the whole memory block is dumped. More...
 
static void DebugOut (const char *pszLine)
 Static method to output a line of text for debugging purposes. More...
 
- Protected Member Functions inherited from __FCBase
 __FCBase ()
 The constructor.
 

Detailed Description

Class that represents a single Lua script item. This class is not part of the C++ PDK Framework.

The finenv namespace offers the following ways to use this class. (The full documentation for these functions is at https://www.finalelua.com/docs/rgp-lua.)

Method Description
CreateLuaScriptItems Returns a FCLuaScriptItems collection containing all configured script items from the Finale Plug-In menu for the running instance of RGP Lua.
CreateLuaScriptItemsFromFilePath(pathstr) Returns a FCLuaScriptItems collection populated from the input file path and that file's plugindef function, if any.
ExecuteLuaScriptItem(item) Executes the input script FCLuaScriptItem with its own Lua state.

The collection returned by CreateLuaScriptItemsFromFilePath(pathstr) contains one item for the script file plus one for each additional menu item defined in the file's plugindef function, if it has one.

When your script executes a script item returned by CreateLuaScriptItems, it is indentical to invoking it from Finale's Plug-Ins menu. There are no further dependencies, and all behavior is identical. The invoked script can continue to run (for example, in a modeless window) even if your script terminates.

When your script executes a script item from the collection returned by CreateLuaScriptItemFromFilePath, your script must maintain that instance of FCLuaScriptItem until it terminates. This includes any modeless dialog or RetainLuaState executed by the invoked script. If your instance of FCLuaScriptItem goes out of scope and is destroyed by Lua garbage collection, the corresponding invoked script terminates immediately.

Warning
Be careful not to create conflcts on Finale's undo stack.

The safest approach to avoid undo conflicts is to include the following in your plugindef function.

function plugindef()
finaleplugin.NoStore = true
finaleplugin.HandlesUndo = true
.
.
.
end

If you choose to ignore this advice and allow your launcher script to make document modifications, they will be rolled back with finenv.EndUndoBlock(false) before the new script is executed. Therefore, if you wish to keep document modifications, commit them with finenv.EndUndoBlock(true) before calling finenv.ExecuteLuaScriptItem. If your script will be invoking scripts that open modeless dialogs or retain Lua state, do not allow document modifications. Instead, use the plugindef settings above.

Member Enumeration Documentation

◆ LUASCRIPT_REQVERSION_TYPES

Settings used to get required version information for a script.

Lua-supported (0.64).

Enumerator
REQVERSIONTYPE_MINIMUM_FINALE 

Minimum Finale version (raw)

REQVERSIONTYPE_MAXIMUM_FINALE 

Maximum Finale version (raw)

REQVERSIONTYPE_MINIMUM_FINALE_MAJOR 

Minimum Finale major version (version year or 64-bit major version + 10000)

REQVERSIONTYPE_MAXIMUM_FINALE_MAJOR 

Maximum Finale major version (version year or 64-bit major version + 10000)

REQVERSIONTYPE_MINIMUM_LUAX1000 

Minimum Lua plugin version x 1000 (e.g. 0.64 is returned as 640)

REQVERSIONTYPE_MAXIMUM_LUAX1000 

Maximum Lua plugin version (e.g. 0.64 is returned as 640)

Member Function Documentation

◆ ClassName()

const char * FCLuaScriptItem::ClassName ( ) const
inlineoverridevirtual

Returns the name of the class, for diagnostic purposes. This method MUST be overwritten in each child class.

Lua-supported.

Implements __FCBase.

◆ CreateFinalePluginValue()

FCString * FCLuaScriptItem::CreateFinalePluginValue ( const char *  fieldname)
inline

Return the requested finaleplugin value.

Values in the finaleplugin namespace are defined in the script's plugindef() function.

Lua-supported (0.64).

Returns
The value of the requested field in a newly created FCString instance, or NULL if it does not exist. C++ clients must delete it when they are finished.

◆ GetDebug()

bool FCLuaScriptItem::GetDebug ( ) const
inline

Return true if the script should be run in debug mode.

Lua-supported (also as property) (0.64).

◆ GetDescription()

const char * FCLuaScriptItem::GetDescription ( ) const
inline

Returns the description for the script.

Lua-supported (also as property) (0.64).

◆ GetExecutableIndex()

int FCLuaScriptItem::GetExecutableIndex ( ) const
inline

Returns the executable index for this script.

Remarks
This value is managed by RGP Lua and may be different every time Finale is started. However, it remains constant throughout a single session of Finale.

Lua-supported (also as read-only property) (0.64).

◆ GetFilePath()

const char * FCLuaScriptItem::GetFilePath ( ) const
inline

Returns the fully-qualified file path for the script.

Remarks
Only items returned by finenv.CreateLuaScriptItemFromFilePath have a file path. Items returned by finenv.CreateLuaScriptItems use GetExecutableIndex.

Lua-supported (also as read-only property) (0.64).

◆ GetLoadAsString()

bool FCLuaScriptItem::GetLoadAsString ( ) const
inline

Return true if the script should be loaded as a string.

Lua-supported (also as property) (0.64).

◆ GetMenuItemText()

const char * FCLuaScriptItem::GetMenuItemText ( ) const
inline

Returns the menu item text for the script.

Lua-supported (also as property) (0.64).

◆ GetPrefix()

const char * FCLuaScriptItem::GetPrefix ( ) const
inline

Returns the prefix for the script.

Lua-supported (also as property) (0.64).

◆ GetRequiredVersion()

EVERSION FCLuaScriptItem::GetRequiredVersion ( int  versiontype) const
inline

Returns a required version number from one of the LUASCRIPT_REQVERSION_TYPES constants.

If the script does not specify a minimum version, this function returns 0. If the script does not specify a maximum version, this function returns a very large value that is larger than any potential version number.

Lua-supported (0.64).

◆ GetUndoText()

const char * FCLuaScriptItem::GetUndoText ( ) const
inline

Returns the undo text for the script.

Lua-supported (also as property) (0.64).

◆ GetVersionCompatible()

bool FCLuaScriptItem::GetVersionCompatible ( ) const
inline

If false, this script is not compatible with either the running Finale or the running Lua plugin version or both.

You should not execute the script if this value is false. You will get an error return if you try. You can use GetRequiredVersion to obtain more information about which version(s) the script requires.

When GetVersionCompatible is false, the string returned by GetDescription is a message that describes the version incompatibility.

Lua-supported (also as read-only property) (0.64)

◆ IsExecuting()

bool FCLuaScriptItem::IsExecuting ( ) const
inline

Returns true if the script associated with this script item is currently executing.

Lua-supported (0.64)

◆ SetDebug()

void FCLuaScriptItem::SetDebug ( bool  state)
inline

Sets if the script should be run in debug mode.

Lua-supported (also as property) (0.64).

◆ SetDescription()

void FCLuaScriptItem::SetDescription ( const char *  value)
inline

Sets the description for the script.

Lua-supported (also as property) (0.64).

◆ SetLoadAsString()

void FCLuaScriptItem::SetLoadAsString ( bool  state)
inline

Sets if the script should be loaded as a string.

Lua-supported (also as property) (0.64).

◆ SetMenuItemText()

void FCLuaScriptItem::SetMenuItemText ( const char *  value)
inline

Sets the menu item text for the script.

Lua-supported (also as property) (0.64).

◆ SetPrefix()

void FCLuaScriptItem::SetPrefix ( const char *  value)
inline

Sets the prefix for the script.

Lua-supported (also as property) (0.64).

◆ SetUndoText()

void FCLuaScriptItem::SetUndoText ( const char *  value)
inline

Sets the undo text for the script.

Lua-supported (also as property) (0.64).