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_ACTIVELYRIC , FCID_ALLOTMENT , FCID_ARTICULATION , FCID_ARTICULATIONDEF , FCID_BACKWARDREPEAT , FCID_BASELINE , FCID_BEAMMOD , FCID_BEATCHARTELEMENT , FCID_BOOKMARK , 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_ENIGMATEXTSTYLE , 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_KEYMODEDEF , 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.

bool	IsExecuting () const
	Returns true if the script associated with this script item is currently executing.

void	StopExecuting ()
	Stops execution and terminates the Lua state.

const char *	GetFilePath () const
	Returns the fully-qualified file path for the script or empty string if none.

const char *	GetFileName () const
	Returns the file name of the script or empty string if none.

const char *	GetOptionalScriptText () const
	Returns the optional script text.

const char *	GetMenuItemText () const
	Returns the menu item text for the script.

const char *	GetUndoText () const
	Returns the undo text for the script.

const char *	GetDescription () const
	Returns the description for the script.

const char *	GetPrefix () const
	Returns the prefix for the script.

bool	GetDebug () const
	Return true if the script should be run in debug mode.

bool	GetLoadAsString () const
	Return true if the script should be loaded as a string.

int	GetExecutableIndex () const
	Returns the executable index for this script.

bool	GetVersionCompatible () const
	If false, this script is not compatible with either the running Finale or the running Lua plugin version or both.

EVERSION	GetRequiredVersion (int versiontype) const
	Returns a required version number from one of the LUASCRIPT_REQVERSION_TYPES constants.

bool	GetAutomaticallyReportErrors () const
	Gets if errors should automatically be reported by the Lua connector. The default value is true.

bool	GetTrusted () const
	Gets if the script should run in trusted mode. Default is false.

__FCUserWindow *	GetControllingWindow () const
	Gets the controlling window for this script item.

FCString *	CreateFinalePluginValue (const char *fieldname)
	Return the requested finaleplugin value.

void	SetOptionalScriptText (const char *value)
	Sets the optional script text.

void	SetMenuItemText (const char *value)
	Sets the menu item text for the script.

void	SetUndoText (const char *value)
	Sets the undo text for the script.

void	SetDescription (const char *value)
	Sets the description for the script.

void	SetPrefix (const char *value)
	Sets the prefix for the script.

void	SetDebug (bool state)
	Sets if the script should be run in debug mode.

void	SetLoadAsString (bool state)
	Sets if the script should be loaded as a string.

void	SetAutomaticallyReportErrors (bool state)
	Sets if errors should automatically be reported by the Lua connector. The default value is true.

void	SetTrusted (bool state)
	Sets if the script should run in trusted mode. If you set this to true, the script that calls finenv.ExecuteLuaScriptItem must also be running in trusted mode. Otherwise an error occurs.`.

void	SetControllingWindow (__FCUserWindow *value)
	Sets the controlling window for this script item.

bool	RegisterPrintFunction (luabridge::LuaRef lua_callback_function)
	Registers a Lua function that replaces called script's print function.

bool	RegisterOnExecutionWillStart (luabridge::LuaRef lua_callback_function)
	Registers a Lua function that gets called when the script item starts executing. For the function to be called, the FCLuaScriptItem must have been created with `finenv.CreateLuaScriptItemsFromFilePath`.

bool	RegisterOnExecutionDidStop (luabridge::LuaRef lua_callback_function)
	Registers a Lua function that gets called when the script item stops executing. For the function to be called, the FCLuaScriptItem must have been created with `finenv.CreateLuaScriptItemsFromFilePath`.

bool	RegisterOnModalWindowWillOpen (luabridge::LuaRef lua_callback_function)
	Registers a Lua function that gets called when the script item opens a modal dialog. For the function to be called, the FCLuaScriptItem must have been created with `finenv.CreateLuaScriptItemsFromFilePath`.

bool	RegisterOnModalWindowDidClose (luabridge::LuaRef lua_callback_function)
	Registers a Lua function that gets called when the script item closes a modal dialog. For the function to be called, the FCLuaScriptItem must have been created with `finenv.CreateLuaScriptItemsFromFilePath`.

void	OnExecutionWillStart ()
	Function that is called when script execution starts.

void	OnExecutionDidStop (bool success, const char msg, int msgtype, int linenumber, const char source)
	Function that is called when script execution stops and its Lua state is closed.

void	OnModalWindowWillOpen ()
	Function that is called when the script execution will open a modal dialog.

void	OnModalWindowDidClose ()
	Function that is called when the script execution has closed a modal dialog.

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.

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.

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.

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.

void	DebugMsg (const char *pszMsg)
	Creates a simple Message Box for debug purposes with just one text string.

void	DebugOutMenuInfo (FCUI *pUI, int menuixd_horiz, int menuixd_vert) const
	Outputs the menu command info for debugging purposes.

int	DebugOutFormat (const char *fmt,...)
	Outputs debug text using C style "printf" syntax.

virtual void	DebugDump ()
	Outputs the class data/information for debugging purposes.

virtual void	DebugDataDump ()
	Outputs a memory dump of the data block in the object for debugging purposes.

virtual void	DebugDataByteArrayDump ()
	Outputs a memory dump of the data block in the object for debugging purposes, as a C++ byte array.

void	Set16BitFlag (FLAG_16 *flag, FLAG_16 flagbits, bool state)
	Sets a 16 bit flag.

void	Set32BitFlag (FLAG_32 *flag, FLAG_32 flagbits, bool state)
	Sets/resets a 32 bit flag, by using a bit mask.

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.

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.

void	SetUserData (void *pData)
	Sets the user data attached to the instance of an object.

void	SetUserData2 (void *pData)
	Sets the additional user data attached to the instance of an object.

void *	GetUserData () const
	Gets the user data attached to the instance of an object.

void *	GetUserData2 () const
	Gets the additional user data attached to the instance of an object.

virtual bool	IsIdentical (const __FCBase *pCompareObject) const
	Returns true if the data in the passed object is considered to be identical to the current object, otherwise false.

void	StoreXML_String (tinyxml2::XMLElement pParentNode, const char pszElementName, FCString *pStringValue)
	Helper function to store FCString objects in the XML file.

void	StoreXML_Integer (tinyxml2::XMLElement pParentNode, const char pszElementName, int value)
	Helper function to store integer objects in the XML file.

void	StoreXML_Bool (tinyxml2::XMLElement pParentNode, const char pszElementName, bool value)
	Helper function to store boolean objects in the XML file.

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.

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.

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.

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.

virtual void	StoreToXML (tinyxml2::XMLElement *pParentNode)
	Virtual method that is used to store an object's data.

bool	ReadXML_String (tinyxml2::XMLElement pParentNode, const char pszElementName, FCString *pStringValue)
	Helper method to read FCString objects from the XML file.

bool	ReadXML_Integer (tinyxml2::XMLElement pParentNode, const char pszElementName, int *pValue)
	Helper method to read integer objects from the XML file.

bool	ReadXML_Bool (tinyxml2::XMLElement pParentNode, const char pszElementName, bool *pValue)
	Helper method to read boolean objects from the XML file.

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.

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.

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.

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.

virtual bool	ReadFromXML (tinyxml2::XMLElement *pParentNode)
	Virtual method that is used to read object data.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

static void	DebugOut (const char *pszLine)
	Static method to output a line of text for debugging purposes.

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/finenv-properties.)

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[,scrtext])	Returns a FCLuaScriptItems collection populated from the input file path or text and that item's plugindef function, if any.
ExecuteLuaScriptItem(item)	Executes the input script FCLuaScriptItem with its own separate Lua state.

The collection returned by CreateLuaScriptItemsFromFilePath(pathstr) contains one item for the script 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 CreateLuaScriptItemsFromFilePath, 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
   .
   .
   .
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.

◆ GetAutomaticallyReportErrors()

bool FCLuaScriptItem::GetAutomaticallyReportErrors ( ) const

inline

Gets if errors should automatically be reported by the Lua connector. The default value is true.

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

◆ GetControllingWindow()

__FCUserWindow * FCLuaScriptItem::GetControllingWindow ( ) const

inline

Gets the controlling window for this script item.

The script that creates this instance of FCLuaScriptItem can set this value to a window that it owns. Scripts that run modal dialogs will launch from this window by default if no other parent is supplied. This includes built-in modal dialogs launched from FCUI, including alerts, file open and save dialogs, and built-in Finale dialogs. It addresses an issue on Windows where modal dialogs that are not modal to the contolling window cause Finale crashes if the the controlling window is closed before the modal dialog.

Remarks: If the controlling script sets this value, the controlling window must remain open while the script runs. If the controlling window will close before the script finished, it must terminate the script using StopExecuting and then clear this value.

Lua-supported (also as property) (0.72)

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

◆ GetFileName()

const char * FCLuaScriptItem::GetFileName ( ) const

inline

Returns the file name of the script or empty string if none.

Remarks: This value is valid even for items returned by finenv.CreateLuaScriptItems. It allows you to identify a configured script without depending on its menu text. The menu text may vary by locale, so you should use this instead.

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

◆ GetFilePath()

const char * FCLuaScriptItem::GetFilePath ( ) const

inline

Returns the fully-qualified file path for the script or empty string if none.

Remarks: Only items returned by finenv.CreateLuaScriptItemsFromFilePath 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.

Note: If a script has an explicit setting of LoadAsString in its plugindef function, it overrides this value. That said, as long as you do not modify it, the initial value will always be the value that RGP Lua uses to run the script, which takes into account an explicit setting in plugindef.

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

◆ GetOptionalScriptText()

const char * FCLuaScriptItem::GetOptionalScriptText ( ) const

inline

Returns the optional script text.

If this value is non-NULL, it is executed instead of the contents of GetFilePath. The file path may still used for informational display or security purposes by RGP Lua.

You can set this value with an optional second parameter to finenv.CreateLuaScriptItemsFromFilePath as follows.

local script_text = "print('hello world')"
local script_items = finenv.CreateLuaScriptItemsFromFilePath("hello_world.lua", script_text)
if script_items.Count > 0 then
    finenv.ExecuteLuaScriptItem(script_items:GetItemAt(0))
end

This code prints "hello world" irrespective of the contents of hello_world.lua. In fact, the file does not have to exist. The intended use case is to allow for on-the-fly edits to a script without the need to save it first.

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

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

◆ GetTrusted()

bool FCLuaScriptItem::GetTrusted ( ) const

inline

Gets if the script should run in trusted mode. Default is false.

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

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

◆ OnExecutionDidStop()

void FCLuaScriptItem::OnExecutionDidStop	(	bool	success,
		const char *	msg,
		int	msgtype,
		int	linenumber,
		const char *	source )

inline

Function that is called when script execution stops and its Lua state is closed.

The current instance of FCLuaScriptItem is passed to Lua as the first parameter.

Parameters

success	true if the script ran without error, otherwise false.
msg	the message returned by the script or NULL if none.
msgtype	a code inidicating the type of message being returned. This meaning of this value is determined by the Lua connector. With RGP Lua, it is one of the `finenv.MessageResultType` values.
linenumber	if Lua was executed, the top-level line number where execution stopped, otherwise 0.
source	if there was an error, the name of the code block where executions stopped, otherwise NULL. If non NULL, this should match either the file path or the optional script text, if it exists.

◆ OnExecutionWillStart()

void FCLuaScriptItem::OnExecutionWillStart ( )

inline

Function that is called when script execution starts.

The current instance of FCLuaScriptItem is passed to Lua as the first parameter.

◆ OnModalWindowDidClose()

void FCLuaScriptItem::OnModalWindowDidClose ( )

inline

Function that is called when the script execution has closed a modal dialog.

Warning: If the executing script item error aborts or is externally terminated, a balancing call to OnModalWindowDidClose may not be called for open modal windows. Your controlling script should reset its open-modal count whenever OnExecutionDidStop is called.

The current instance of FCLuaScriptItem is passed to Lua as the first parameter.

◆ OnModalWindowWillOpen()

void FCLuaScriptItem::OnModalWindowWillOpen ( )

inline

Function that is called when the script execution will open a modal dialog.

The current instance of FCLuaScriptItem is passed to Lua as the first parameter.

◆ RegisterOnExecutionDidStop()

bool FCLuaScriptItem::RegisterOnExecutionDidStop ( luabridge::LuaRef lua_callback_function )

inline

Registers a Lua function that gets called when the script item stops executing. For the function to be called, the FCLuaScriptItem must have been created with finenv.CreateLuaScriptItemsFromFilePath.

Lua-supported (0.68).

Parameters

lua_callback_function The Lua callback function. See OnExecutionDidStop for the call signature.

Returns: True on succesful callback registration.

◆ RegisterOnExecutionWillStart()

bool FCLuaScriptItem::RegisterOnExecutionWillStart ( luabridge::LuaRef lua_callback_function )

inline

Registers a Lua function that gets called when the script item starts executing. For the function to be called, the FCLuaScriptItem must have been created with finenv.CreateLuaScriptItemsFromFilePath.

Lua-supported (0.68).

Parameters

lua_callback_function The Lua callback function. See OnExecutionWillStart for the call signature.

Returns: True on succesful callback registration.

◆ RegisterOnModalWindowDidClose()

bool FCLuaScriptItem::RegisterOnModalWindowDidClose ( luabridge::LuaRef lua_callback_function )

inline

Registers a Lua function that gets called when the script item closes a modal dialog. For the function to be called, the FCLuaScriptItem must have been created with finenv.CreateLuaScriptItemsFromFilePath.

Lua-supported (0.68).

Parameters

lua_callback_function The Lua callback function. See OnModalWindowDidClose for the call signature.

Returns: True on succesful callback registration.

◆ RegisterOnModalWindowWillOpen()

bool FCLuaScriptItem::RegisterOnModalWindowWillOpen ( luabridge::LuaRef lua_callback_function )

inline

Registers a Lua function that gets called when the script item opens a modal dialog. For the function to be called, the FCLuaScriptItem must have been created with finenv.CreateLuaScriptItemsFromFilePath.

Remarks: Your calling script can use this callback to prevent itself from being terminated until the modal window closes. If your calling script terminates while a modal window is open in the called script, it can cause Finale to crash.

Lua-supported (0.68).

Parameters

lua_callback_function The Lua callback function. See OnModalWindowWillOpen for the call signature.

Returns: True on succesful callback registration.

◆ RegisterPrintFunction()

bool FCLuaScriptItem::RegisterPrintFunction ( luabridge::LuaRef lua_callback_function )

inline

Registers a Lua function that replaces called script's print function.

This function must be registered before the script starts executing.

Lua-supported (0.68).

Parameters

lua_callback_function The Lua callback function. For the function to be called, the FCLuaScriptItem must have been created with finenv.CreateLuaScriptItemsFromFilePath.

This function receives an unspecified number of arguments. Nil, booleans, numbers, and strings are passed through as-is. All other types are converted to strings.

Returns: True on succesful callback registration.

◆ SetAutomaticallyReportErrors()

void FCLuaScriptItem::SetAutomaticallyReportErrors ( bool state )

inline

Sets if errors should automatically be reported by the Lua connector. The default value is true.

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

◆ SetControllingWindow()

void FCLuaScriptItem::SetControllingWindow ( __FCUserWindow * value )

inline

Sets the controlling window for this script item.

See comments at GetControllingWindow for details about this value.

Remarks: The safest way to use this value is to set it right before calling finenv.ExecuteLuaScriptItem and to clear it when the script terminates. That way, it won't contain a window pointer that has gone out of scope and been destroyed. Note that some scripts open modeless dialog or retain Lua state. The safest method to know that a script item has terminated is to register a callback function with RegisterOnExecutionDidStop.

Lua-supported (also as property) (0.72)

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

Note: This function cannot override an explicit setting of LoadAsString in the plugindef function of a script, either true or false. In this regard it functions similar to the RGP Lua configuration setting.

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

◆ SetOptionalScriptText()

void FCLuaScriptItem::SetOptionalScriptText ( const char * value )

inline

Sets the optional script text.

See comments at GetOptionalScriptText for more information about the optional script text. Setting this has no effect for instances of FCLuaScriptItem created with finenv.CreateLuaScriptItems

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

Parameters

value the optional string or NULL to clear it

◆ SetPrefix()

void FCLuaScriptItem::SetPrefix ( const char * value )

inline

Sets the prefix for the script.

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

◆ SetTrusted()

void FCLuaScriptItem::SetTrusted ( bool state )

inline

Sets if the script should run in trusted mode. If you set this to true, the script that calls finenv.ExecuteLuaScriptItem must also be running in trusted mode. Otherwise an error occurs.`.

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

◆ SetUndoText()

void FCLuaScriptItem::SetUndoText ( const char * value )

inline

Sets the undo text for the script.

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

◆ StopExecuting()

void FCLuaScriptItem::StopExecuting ( )

inline

Stops execution and terminates the Lua state.

This function only works for instances of FCLuaScriptItem created with finenv.CreateLuaScriptItemsFromFilePath.

Lua-supported (0.68).

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ LUASCRIPT_REQVERSION_TYPES

Member Function Documentation

◆ ClassName()

◆ CreateFinalePluginValue()

◆ GetAutomaticallyReportErrors()

◆ GetControllingWindow()

◆ GetDebug()

◆ GetDescription()

◆ GetExecutableIndex()

◆ GetFileName()

◆ GetFilePath()

◆ GetLoadAsString()

◆ GetMenuItemText()

◆ GetOptionalScriptText()

◆ GetPrefix()

◆ GetRequiredVersion()

◆ GetTrusted()

◆ GetUndoText()

◆ GetVersionCompatible()

◆ IsExecuting()

◆ OnExecutionDidStop()

◆ OnExecutionWillStart()

◆ OnModalWindowDidClose()

◆ OnModalWindowWillOpen()

◆ RegisterOnExecutionDidStop()

◆ RegisterOnExecutionWillStart()

◆ RegisterOnModalWindowDidClose()

◆ RegisterOnModalWindowWillOpen()

◆ RegisterPrintFunction()

◆ SetAutomaticallyReportErrors()

◆ SetControllingWindow()

◆ SetDebug()

◆ SetDescription()

◆ SetLoadAsString()

◆ SetMenuItemText()

◆ SetOptionalScriptText()

◆ SetPrefix()

◆ SetTrusted()

◆ SetUndoText()

◆ StopExecuting()