Finale PDK Framework 0.67
|
Class that represents a single Lua script item. This class is not part of the C++ PDK Framework. More...
#include <fflua_luascriptitem.h>
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... | |
![]() | |
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... | |
FCString * | CreateFinalePluginValue (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... | |
![]() | |
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 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... | |
![]() | |
__FCBase () | |
The constructor. | |
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.
The safest approach to avoid undo conflicts is to include the following in your plugindef function.
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.
Settings used to get required version information for a script.
Lua-supported (0.64).
|
inlineoverridevirtual |
Returns the name of the class, for diagnostic purposes. This method MUST be overwritten in each child class.
Lua-supported.
Implements __FCBase.
|
inline |
Return the requested finaleplugin value.
Values in the finaleplugin namespace are defined in the script's plugindef() function.
Lua-supported (0.64).
|
inline |
Return true if the script should be run in debug mode.
Lua-supported (also as property) (0.64).
|
inline |
Returns the description for the script.
Lua-supported (also as property) (0.64).
|
inline |
Returns the executable index for this script.
Lua-supported (also as read-only property) (0.64).
|
inline |
Returns the fully-qualified file path for the script.
Lua-supported (also as read-only property) (0.64).
|
inline |
Return true if the script should be loaded as a string.
Lua-supported (also as property) (0.64).
|
inline |
Returns the menu item text for the script.
Lua-supported (also as property) (0.64).
|
inline |
Returns the prefix for the script.
Lua-supported (also as property) (0.64).
|
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).
|
inline |
Returns the undo text for the script.
Lua-supported (also as property) (0.64).
|
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)
|
inline |
Returns true if the script associated with this script item is currently executing.
Lua-supported (0.64)
|
inline |
Sets if the script should be run in debug mode.
Lua-supported (also as property) (0.64).
|
inline |
Sets the description for the script.
Lua-supported (also as property) (0.64).
|
inline |
Sets if the script should be loaded as a string.
Lua-supported (also as property) (0.64).
|
inline |
Sets the menu item text for the script.
Lua-supported (also as property) (0.64).
|
inline |
Sets the prefix for the script.
Lua-supported (also as property) (0.64).
|
inline |
Sets the undo text for the script.
Lua-supported (also as property) (0.64).