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:

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...

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...

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

enum FCLuaScriptItem::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).

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ LUASCRIPT_REQVERSION_TYPES

Member Function Documentation

◆ ClassName()

◆ CreateFinalePluginValue()

◆ GetDebug()

◆ GetDescription()

◆ GetExecutableIndex()

◆ GetFilePath()

◆ GetLoadAsString()

◆ GetMenuItemText()

◆ GetPrefix()

◆ GetRequiredVersion()

◆ GetUndoText()

◆ GetVersionCompatible()

◆ IsExecuting()

◆ SetDebug()

◆ SetDescription()

◆ SetLoadAsString()

◆ SetMenuItemText()

◆ SetPrefix()

◆ SetUndoText()