Class for Lua callback iterators. This class is not part of the C++ PDK Framework. More...

#include <fflua_luaiterator.h>

Inheritance diagram for FCLuaIterator:

Public Types
enum	LUAITERATOR_ENTRYFILTERS { LIEFILTER_NOTE = 0 , LIEFILTER_REST , LIEFILTER_CHORD , LIEFILTER_SINGLENOTE , LIEFILTER_ARTICULATIONFLAG , LIEFILTER_SMARTSHAPEFLAG , LIEFILTER_NOTEDETAILFLAG , LIEFILTER_PERFORMANCEDATAFLAG , LIEFILTER_SPECIALALTSFLAG , LIEFILTER_TUPLETSTARTFLAG , LIEFILTER_LYRICFLAG , LIEFILTER_STEMDETAILFLAG , LIEFILTER_SECONDARYBEAMFLAG , LIEFILTER_GRACENOTE , LIEFILTER_DOTTED , LIEFILTER_DURWHOLE , LIEFILTER_DURHALF , LIEFILTER_DURQUARTER , LIEFILTER_DUR8TH , LIEFILTER_DUR16TH , LIEFILTER_DUR32ND , LIEFILTER_DUR64TH }
	Constants for the note entry filters. More...

enum	LUAITERATOR_NOTEFILTERS { LINFILTER_TIE , LINFILTER_ACCIDENTAL , LINFILTER_ACCIDENTALPARENTHESES , LINFILTER_ACCIDENTALFREEZE }
	Constants for the note filters. More...

enum	LUAITERATOR_LOGICMETHOD { LILOGIC_AND = 0 , LILOGIC_OR = 1 , LILOGIC_NOT = 2 }
	Logical operators that are used for filters. If no filters are added/activated, all items are automatically processed. 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.

	FCLuaIterator ()
	The constructor.

int	ForEach (__FCCollectionData *pCollection, luabridge::LuaRef lua_callback_function)
	Browses through the items in a collection and sends the object to a Lua callback function, similar to the each() iterator in JW Lua.

int	ForEachSaved (__FCCollectionData *pCollection, luabridge::LuaRef lua_callback_function)
	Browses through the items in a collection. After the Lua callback function has processed the object, the object is saved.

int	ForEachEntry (FCMusicRegion *pRegion, luabridge::LuaRef lua_callback_function)
	Browses through the entries in a region, similar to the eachentry() iterator in JW Lua.

int	ForEachEntrySaved (FCMusicRegion *pRegion, luabridge::LuaRef lua_callback_function)
	Browses through and saves the entries in a region, similar to the eachentrysaved() iterator in JW Lua.

int	ForEachNote (FCMusicRegion *pRegion, luabridge::LuaRef lua_callback_function)
	Browses through all notes (as in noteheads) in a region. If a note entry consists of a chord with multiple notes, the Lua callback function is called for each note.

int	ForEachNoteSaved (FCMusicRegion *pRegion, luabridge::LuaRef lua_callback_function)
	Browses through all notes (as in noteheads) in a region and saves the entries. If a note entry consists of a chord with multiple notes, the callback function is called for each note.

int	ForEachCell (FCMusicRegion *pRegion, luabridge::LuaRef lua_callback_function)
	Browses through each cell in a region, similar to the eachcell() iterator in JW Lua.

int	ForEachPart (luabridge::LuaRef lua_callback_function)
	Browses through all the parts in the current document, and passes the part to the callback function. When the callback function is called, the part has already automatically been set in editing focus.

int	ForEachObject (int classID, luabridge::LuaRef lua_callback_function)
	Loads all the objects of a specific type and sends them to a Lua callback function.

int	ForEachObjectSaved (int classID, luabridge::LuaRef lua_callback_function)
	Loads all the objects of a specific type and sends them to a Lua callback function. After callback has processed the object, each object is saved.

int	ForEachRegionObject (FCMusicRegion *pRegion, int classID, luabridge::LuaRef lua_callback_function)
	Loads all the objects of a specific type within a selected region and sends them to a Lua callback function.

int	ForEachRegionObjectSaved (FCMusicRegion *pRegion, int classID, luabridge::LuaRef lua_callback_function)
	Loads all the objects of a specific type that appears within a region and sends them to a Lua callback function. After callback has processed the object, each object is saved.

int	ForEachDocument (luabridge::LuaRef lua_callback_function)
	Browses through all the currently opened documents, and passes the document to the Lua callback function. When the Lua callback function is called, the document has already automatically been set in editing focus.

int	ForEachDocumentSaved (luabridge::LuaRef lua_callback_function)
	Browses through all the currently opened documents, passes the document to the Lua callback function, and saves the file to disk. When the Lua callback function is called, the document has already automatically been set in editing focus.

int	ForEachFile (FCStrings *pFileStrings, luabridge::LuaRef lua_callback_function)
	Opens all the files in a list of strings (as a FCStrings object), and passes the document to the Lua callback function. When the Lua callback function is called, the document has already automatically been set in editing focus.

int	ForEachFileSaved (FCStrings *pFileStrings, luabridge::LuaRef lua_callback_function)
	Opens all the files in a list of strings (as a FCStrings object), passes the document to the Lua callback function, and saves the file to disk. When the Lua callback function is called, the document has already automatically been set in editing focus.

int	ForEachInteger (int integer1, int integer2, luabridge::LuaRef lua_callback_function)
	Passes an integer range to the Lua callback function, one by one. This iterator automatically handles upwards/downwards movement.

bool	GetUseProgressBar () const
	Returns if the update progress bar should be used or not.

int	GetProgressUpdateFrequency () const
	Returns the update frequency for the progress bar.

bool	GetAbortableProgressBar () const
	Returns if the progress bar should be abortable (by the Esc key).

bool	GetProgressBarUserAborted () const
	Returns true if the processing was aborted by the user (using the Esc key) during the last processing.

int	GetLoadLayerMode () const
	Returns the load layer mode for the note entry iterators, such as ForEachEntry(), ForEachNote(), etc.

bool	GetProcessScorePart () const
	Returns if the score part (the part with part ID 0) should be processed in ForEachPart calls.

bool	GetProcessCurrentPart () const
	Returns if the part currently in editing focus should be processed in ForEachPart calls.

bool	GetProcessCurrentDocument () const
	Returns if the document currently in editing focus should be processed in ForEachDocument and ForEachDocumentSaved calls.

bool	GetNullRegionEqualsAll () const
	Returns if NULL regions should automatically be interpreted as a full document region, or not. This setting affects all region-based iterators.

bool	GetForwardProcessing () const
	Returns the direction of the iteration.

bool	GetDownwardProcessing () const
	Returns the vertical direction for processing staves in the iteration, for region-based iterators.

bool	GetPartialMeasureSelections () const
	Returns partially selected measures should be processed.

void	SetUseProgressBar (bool use)
	Sets if the update progress bar should be used or not.

void	SetProgressUpdateFrequency (int freq)
	Sets the update frequency for the progress bar.

void	SetAbortableProgressBar (bool state)
	Sets if the progress bar should be abortable (by the Esc key).

void	SetLoadLayerMode (int loadlayermode)
	Sets the load layer mode for the note entry iterators, such as ForEachEntry(), ForEachNote(), etc.

void	SetProcessScorePart (bool state)
	Sets if the score part (the part with part ID 0) should be processed in ForEachPart calls.

void	SetProcessCurrentPart (bool state)
	Sets if the part currently in editing focus should be processed in ForEachPart calls.

void	SetProcessCurrentDocument (bool state)
	Sets if the document currently in editing focus should be processed in ForEachDocument and ForEachDocumentSaved calls.

void	SetNullRegionEqualsAll (bool state)
	Sets if NULL regions should automatically be interpreted as a full document region, or not. This setting affects all region-based iterators.

void	SetForwardProcessing (bool forward)
	Sets the direction of the iteration.

void	SetDownwardProcessing (bool downward)
	Sets the vertical direction for processing staves in the iteration, for region-based iterators.

void	SetPartialMeasureSelections (bool partialselections)
	Returns partially selected measures should be processed.

bool	AddEntryFilter (int filter, int logicmode)
	Adds/activates a note entry filter.

bool	RemoveEntryFilter (int filter, int logicmode)
	Removes a note entry filter.

void	ClearAllEntryFilters ()
	Removes all entry filters. This will result in all entry being processed by the ForEachEntry and ForEachEntrySaved methods.

bool	IsEntryFilterAdded (int filter, int logicmode)
	Returns true if a specific note entry filter has been added/activated for the iterator.

bool	AddNoteFilter (int filter, int logicmode)
	Adds/activates a note filter.

bool	RemoveNoteFilter (int filter, int logicmode)
	Removes a note filter.

void	ClearAllNoteFilters ()
	Removes all note filters.

bool	IsNoteFilterAdded (int filter, int logicmode)
	Returns true if a specific note filter has been added/activated for the iterator.

bool	AddAltNotationFilter (int filter, int logicmode)
	Adds/activates an alternate notation filter.

bool	RemoveAltNotationFilter (int filter, int logicmode)
	Removes a alternate notation filter.

void	ClearAllAltNotationFilters ()
	Removes all filters for alternate notation. This will result in all items being processed.

bool	IsAltNotationFilterAdded (int filter, int logicmode)
	Returns true if a specific filter for alternate notation has been added/activated for the iterator.

bool	AddNotationStyleFilter (int filter, int logicmode)
	Adds/activates an notation style filter.

bool	RemoveNotationStyleFilter (int filter, int logicmode)
	Removes a notation style filter.

void	ClearAllNotationStyleFilters ()
	Removes all filters for notation styles. This will result in all items being processed.

bool	IsNotationStyleFilterAdded (int filter, int logicmode)
	Returns true if a specific filter for a notation style has been added/activated for the iterator.

double	CalcLastDuration ()
	Reports the duration of the last iterator run.

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 for Lua callback iterators. This class is not part of the C++ PDK Framework.

All iterator methods starts with the prefix 'ForEach'. Iterator methods that automatically stores modified data or save files use a 'Saved' suffix.

Each iterator feeds the data to a Lua callback function. If the Lua callback function returns false, processing of any further items will stop.

This class contain these iterators:

Loaded data collections: ForEach and ForEachSaved
Note entries/rests for a region: ForEachEntry and ForEachEntrySaved
Individual notes in a note entry for a region: ForEachNote and ForEachNoteSaved
All objects of a specific class: ForEachObject and ForEachObjectSaved
Note-or measure-attached information in a region: ForEachRegionObject and ForEachRegionObjectSaved
Cell locations for a region: ForEachCell
Parts in the current document: ForEachPart
Currently opened documents: ForEachDocument and ForEachDocumentSaved
Currently unopened documents: ForEachFile and ForEachFileSaved

Except for reporting timing values, one single iterator object can be used to call nested iterators (for example, if the callback function for ForEachEntry uses the same iterator object to call ForEach for some other data).

The table below shows the fiters that are supported by each iterator method.

Iterator Method	Entry Filter	Note Filter	Notation Style Filter	Alternate Notation Filter
ForEach	No	No	No	No
ForEachSaved	No	No	No	No
ForEachEntry	YES	No	YES	YES
ForEachEntrySaved	YES	No	YES	YES
ForEachNote	YES	YES	YES	YES
ForEachNoteSaved	YES	YES	YES	YES
ForEachCell	No	No	*YES ()**	*YES ()**
ForEachPart	No	No	No	No
ForEachObject	No	No	No	No
ForEachObjectSaved	No	No	No	No
ForEachRegionObject	YES ()**	No	YES	YES
ForEachRegionObjectSaved	YES ()**	No	YES	YES
ForEachDocument	No	No	No	No
ForEachDocumentSaved	No	No	No	No
ForEachFile	No	No	No	No
ForEachFileSaved	No	No	No	No
ForEachInteger	No	No	No	No

(*) Start of cell only (**) If the object type supports it

Member Enumeration Documentation

◆ LUAITERATOR_ENTRYFILTERS

enum FCLuaIterator::LUAITERATOR_ENTRYFILTERS

Constants for the note entry filters.

Accessed by AddEntryFilter and RemoveEntryFilter and similar methods. Used by the ForEachEntry and ForEachEntrySaved iterators.

Lua-supported.

Enumerator
LIEFILTER_NOTE	Note entries that are notes.
LIEFILTER_REST	Note entries that are rests.
LIEFILTER_CHORD	Note entries with 2 notes or more.
LIEFILTER_SINGLENOTE	Note entries that have 1 single note. Rests are not processed.
LIEFILTER_ARTICULATIONFLAG	Note entries where FCNoteEntry::GetArticulationFlag() returns true.
LIEFILTER_SMARTSHAPEFLAG	Note entries where FCNoteEntry::GetSmartShapeFlag() returns true.
LIEFILTER_NOTEDETAILFLAG	Note entries where FCNoteEntry::GetNoteDetailFlag() returns true.
LIEFILTER_PERFORMANCEDATAFLAG	Note entries where FCNoteEntry::GetPerformanceDataFlag() returns true.
LIEFILTER_SPECIALALTSFLAG	Note entries where FCNoteEntry::GetSpecialAltsFlag() returns true.
LIEFILTER_TUPLETSTARTFLAG	Note entries where FCNoteEntry::GetTupletStartFlag() returns true.
LIEFILTER_LYRICFLAG	Note entries where FCNoteEntry::GetLyricFlag() returns true.
LIEFILTER_STEMDETAILFLAG	Note entries where FCNoteEntry::GetStemDetailFlag() returns true.
LIEFILTER_SECONDARYBEAMFLAG	Note entries where FCNoteEntry::GetSecondaryBeamFlag() returns true.
LIEFILTER_GRACENOTE	Note entries where FCNoteEntry::GetGraceNote() returns true.
LIEFILTER_DOTTED	Note entries that have augmentation dots.
LIEFILTER_DURWHOLE	Note entries with whole note duration.
LIEFILTER_DURHALF	Note entries with half note duration.
LIEFILTER_DURQUARTER	Note entries with quarter note duration.
LIEFILTER_DUR8TH	Note entries with eighth note duration.
LIEFILTER_DUR16TH	Note entries with 16th note duration.
LIEFILTER_DUR32ND	Note entries with 32nd note duration.
LIEFILTER_DUR64TH	Note entries with 64th note duration.

◆ LUAITERATOR_LOGICMETHOD

enum FCLuaIterator::LUAITERATOR_LOGICMETHOD

Logical operators that are used for filters. If no filters are added/activated, all items are automatically processed.

Lua-supported.

Enumerator
LILOGIC_AND	Logical "AND": Each activated filter must match for an item to be processed.
LILOGIC_OR	Logical "OR": Any of the active filters can match, but at least one of the filters must match.
LILOGIC_NOT	Logical "NOT": None of the filters are allowed to match.

◆ LUAITERATOR_NOTEFILTERS

enum FCLuaIterator::LUAITERATOR_NOTEFILTERS

Constants for the note filters.

Accessed by AddNoteFilter and RemoveNoteFilter and similar methods. Used by the ForEachNote and ForEachNoteSaved iterators.

Lua-supported.

Enumerator
LINFILTER_TIE	Note that starts a tie.
LINFILTER_ACCIDENTAL	Note that displays an accidental.
LINFILTER_ACCIDENTALPARENTHESES	Note that has parentheses for accidentals set. This might be set event if the accidental isn't displayed.
LINFILTER_ACCIDENTALFREEZE	Note with frozen accidental state.

Constructor & Destructor Documentation

◆ FCLuaIterator()

FCLuaIterator::FCLuaIterator ( )

inline

The constructor.

Lua-supported.

Member Function Documentation

◆ AddAltNotationFilter()

bool FCLuaIterator::AddAltNotationFilter	(	int	filter,
		int	logicmode )

inline

Adds/activates an alternate notation filter.

Lua-supported.

Parameters

[in]	filter	Any of the ALTSTAFF_ constants.
[in]	logicmode	Any of the LILOGIC_ constants (LILOGIC_AND, LILOGIC_OR, LILOGIC_NOT)

Returns: True if the filter was added. False if it already was available.

◆ AddEntryFilter()

bool FCLuaIterator::AddEntryFilter	(	int	filter,
		int	logicmode )

inline

Adds/activates a note entry filter.

Lua-supported.

Parameters

[in]	filter	The type of filter. Any of the LIEFILTER_ constants.
[in]	logicmode	Any of the LILOGIC_ constants (LILOGIC_AND, LILOGIC_OR, LILOGIC_NOT).

Returns: True if the filter was added. False if it already was available.

◆ AddNotationStyleFilter()

bool FCLuaIterator::AddNotationStyleFilter	(	int	filter,
		int	logicmode )

inline

Adds/activates an notation style filter.

Lua-supported.

Parameters

[in]	filter	Any of the STAFFNOTATION_ constants.
[in]	logicmode	Any of the LILOGIC_ constants (LILOGIC_AND, LILOGIC_OR, LILOGIC_NOT)

Returns: True if the filter was added. False if it already was available.

◆ AddNoteFilter()

bool FCLuaIterator::AddNoteFilter	(	int	filter,
		int	logicmode )

inline

Adds/activates a note filter.

Lua-supported.

Parameters

[in]	filter	Any of the LINFILTER_ constants.
[in]	logicmode	Any of the LILOGIC_ constants (LILOGIC_AND, LILOGIC_OR, LILOGIC_NOT).

Returns: True if the filter was added. False if it already was available.

◆ CalcLastDuration()

double FCLuaIterator::CalcLastDuration ( )

inline

Reports the duration of the last iterator run.

Timing only works correctly for "non-stacked" iterators in one iterator object. If one single iterator object calls nested iterators (=when the callback function starts yet another iterator process for some other objects), the returned value will not be accurate.

Lua-supported.

Returns: The duration of the last iterator run, in seconds (as a floating point value).

◆ ClassName()

const char * FCLuaIterator::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.

◆ ClearAllAltNotationFilters()

void FCLuaIterator::ClearAllAltNotationFilters ( )

inline

Removes all filters for alternate notation. This will result in all items being processed.

Lua-supported.

◆ ClearAllEntryFilters()

void FCLuaIterator::ClearAllEntryFilters ( )

inline

Removes all entry filters. This will result in all entry being processed by the ForEachEntry and ForEachEntrySaved methods.

Lua-supported.

◆ ClearAllNotationStyleFilters()

void FCLuaIterator::ClearAllNotationStyleFilters ( )

inline

Removes all filters for notation styles. This will result in all items being processed.

Lua-supported.

◆ ClearAllNoteFilters()

void FCLuaIterator::ClearAllNoteFilters ( )

inline

Removes all note filters.

Lua-supported.

◆ ForEach()

int FCLuaIterator::ForEach	(	__FCCollectionData *	pCollection,
		luabridge::LuaRef	lua_callback_function )

inline

Browses through the items in a collection and sends the object to a Lua callback function, similar to the each() iterator in JW Lua.

The Lua callback function recieves 1 parameter: the object in the collection.

If the callback function script produces an error, the iteration stops and the error message is added to the script output. However, the script doesn't abort when a callback function produces an error.

Lua-supported.

Example of usage:

local function mymeasurehandler(measure)
   print ("Measure: ", measure.ItemNo, "Width: ", measure.Width)
end
 
local allmeasures = finale.FCMeasures()
allmeasures:LoadAll()
local iterator = finale.FCLuaIterator()
iterator:ForEach(allmeasures, mymeasurehandler)

Parameters

[in]	pCollection	The collection with loaded items, of any class that inherits __FCCollectionData.
[in]	lua_callback_function	The Lua callback function.

Returns: The number of processed items.

◆ ForEachCell()

int FCLuaIterator::ForEachCell	(	FCMusicRegion *	pRegion,
		luabridge::LuaRef	lua_callback_function )

inline

Browses through each cell in a region, similar to the eachcell() iterator in JW Lua.

The Lua callback function recieves 2 parameters: first parameter is the 1-based measure number, second parameter is the Staff ID.

Please refer to the table in the class details for info about the filters that are compatible with this method.

If the callback function script produces an error, the iteration stops and the error message is added to the script output. However, the script doesn't abort when a callback function produces an error.

Cells with partial selections are processed.

Lua-supported.

Parameters

[in]	pRegion	The region where the notes should be processed. If this is NULL and GetNullRegionEqualsAll() is true, the full document will be used as region.
[in]	lua_callback_function	The Lua callback function.

Returns: The number of processed cells.

◆ ForEachDocument()

int FCLuaIterator::ForEachDocument ( luabridge::LuaRef lua_callback_function )

inline

Browses through all the currently opened documents, and passes the document to the Lua callback function. When the Lua callback function is called, the document has already automatically been set in editing focus.

The Lua callback function recieves 1 parameter: a FCDocument object.

The method GetProcessCurrentDocument affects if the current document should also be processed in the iteration.

If the callback function script produces an error, the iteration stops and the error message is added to the script output. However, the script doesn't abort when a callback function produces an error.

Lua-supported.

Example of usage:

local function mydocumentcallback(doc)
   local str = finale.FCString()
   doc:GetPath(str)
   systemstaves = finale.FCSystemStaves()
   systemstaves:LoadScrollView()
   print ("Document ", str.LuaString, "has" , systemstaves.Count, "staves.")
end
     
local iterator = finale.FCLuaIterator()
iterator:ForEachDocument(mydocumentcallback)

Parameters

[in] lua_callback_function The Lua callback function.

Returns: The number of processed documents.

◆ ForEachDocumentSaved()

int FCLuaIterator::ForEachDocumentSaved ( luabridge::LuaRef lua_callback_function )

inline

Browses through all the currently opened documents, passes the document to the Lua callback function, and saves the file to disk. When the Lua callback function is called, the document has already automatically been set in editing focus.

The Lua callback function recieves 1 parameter: a FCDocument object.

Please note that this method saves changes to disk. Only documents that have file names are saved. (Untitled documents are unsaved.)

The method GetProcessCurrentDocument affects if the current document should also be processed in the iteration.

If the callback function script produces an error, the iteration stops and the error message is added to the script output. However, the script doesn't abort when a callback function produces an error.

Lua-supported.

Example of usage:

local function mydocsavecallback(doc)
   local sizeprefs = finale.FCSizePrefs()
   sizeprefs:Load(1)
   sizeprefs.ThinBarlineThickness = 142
   sizeprefs:Save()
end
     
local iterator = finale.FCLuaIterator()
iterator:ForEachDocumentSaved(mydocsavecallback)

\param [in] lua_callback_function The Lua callback function.

\return The number of processed documents.

◆ ForEachEntry()

int FCLuaIterator::ForEachEntry	(	FCMusicRegion *	pRegion,
		luabridge::LuaRef	lua_callback_function )

inline

Browses through the entries in a region, similar to the eachentry() iterator in JW Lua.

The Lua callback function recieves 1 parameter: a FCNoteEntry object.

Please refer to the table in the class details for info about the filters that are compatible with this method.

If the callback function script produces an error, the iteration stops and the error message is added to the script output. However, the script doesn't abort when a callback function produces an error.

Lua-supported.

Parameters

[in]	pRegion	The region where the entries should be processed. If this is NULL and GetNullRegionEqualsAll() is true, the full document will be used as region.
[in]	lua_callback_function	The Lua callback function.

Returns: The number of processed entries.

◆ ForEachEntrySaved()

int FCLuaIterator::ForEachEntrySaved	(	FCMusicRegion *	pRegion,
		luabridge::LuaRef	lua_callback_function )

inline

Browses through and saves the entries in a region, similar to the eachentrysaved() iterator in JW Lua.

This method is identical to ForEachEntry, except that each object is saved as well.

The Lua callback function recieves 1 parameter: a FCNoteEntry object.

Please refer to the table in the class details for info about the filters that are compatible with this method.

If the callback function script produces an error, the iteration stops and the error message is added to the script output. However, the script doesn't abort when a callback function produces an error.

Lua-supported.

Example of usage:

local function myentrysavedcallback(entry)
   if not entry.GraceNote then
      entry.ManualPosition = 0
   end
end
 
local iterator = finale.FCLuaIterator()
iterator:ForEachEntrySaved(finenv.Region(), myentrysavedcallback)

Parameters

[in]	pRegion	The region where the entries should be processed. If this is NULL and GetNullRegionEqualsAll() is true, the full document will be used as region.
[in]	lua_callback_function	The Lua callback function.

Returns: The number of processed entries.

◆ ForEachFile()

int FCLuaIterator::ForEachFile	(	FCStrings *	pFileStrings,
		luabridge::LuaRef	lua_callback_function )

inline

Opens all the files in a list of strings (as a FCStrings object), and passes the document to the Lua callback function. When the Lua callback function is called, the document has already automatically been set in editing focus.

The Lua callback function recieves 2 parameter: the 1st parameter is a FCDocument object (which can be nil if the file can't be loaded), the 2nd parameter is the original FCString object that contains the file name path.

If the callback function script produces an error, the iteration stops and the error message is added to the script output. However, the script doesn't abort when a callback function produces an error.

Lua-supported.

Example of usage:

local function myfilecallback(doc, filename)
   if not doc then return end
   local measures = finale.FCMeasures()
   measures:LoadAll()
   print ("File", filename.LuaString, "has", measures.Count, "measures.")
end
 
local filenames = finale.FCStrings()
local str = finale.FCString()
str.LuaString = "d:\\file1.musx"
filenames:AddCopy(str)
str.LuaString = "d:\\file2.musx"
filenames:AddCopy(str)
 
local iterator = finale.FCLuaIterator()
iterator:ForEachFile(filenames, myfilecallback)

Parameters

[in]	pFileStrings	The collection of files to open. Each string must be a full path to a Finale document.
[in]	lua_callback_function	The Lua callback function.

Returns: The number of processed files.

◆ ForEachFileSaved()

int FCLuaIterator::ForEachFileSaved	(	FCStrings *	pFileStrings,
		luabridge::LuaRef	lua_callback_function )

inline

Opens all the files in a list of strings (as a FCStrings object), passes the document to the Lua callback function, and saves the file to disk. When the Lua callback function is called, the document has already automatically been set in editing focus.

The Lua callback function recieves 2 parameter: the 1st parameter is a FCDocument object (which can be nil if the file can't be loaded), the 2nd parameter is the original FCString object that contains the file name path.

Please note that this method saves changes to disk.

If the callback function script produces an error, the iteration stops and the error message is added to the script output. However, the script doesn't abort when a callback function produces an error.

Lua-supported.

Example of usage:

local function myfilesavedcallback(doc, filename)
   if not doc then return end
   local miscdocprefs = finale.FCMiscDocPrefs()
   miscdocprefs:Load(1)
   miscdocprefs.AllowFloatingRests = true
   miscdocprefs:Save()
end
 
local filenames = finale.FCStrings()
local str = finale.FCString()
str.LuaString = "d:\\file1.musx"
filenames:AddCopy(str)
str.LuaString = "d:\\file2.musx"
filenames:AddCopy(str)
 
local iterator = finale.FCLuaIterator()
iterator:ForEachFileSaved(filenames, myfilesavedcallback)

Parameters

[in]	pFileStrings	The collection of files to open. Each string must be a full path to a Finale document.
[in]	lua_callback_function	The Lua callback function.

Returns: The number of processed files.

◆ ForEachInteger()

int FCLuaIterator::ForEachInteger	(	int	integer1,
		int	integer2,
		luabridge::LuaRef	lua_callback_function )

inline

Passes an integer range to the Lua callback function, one by one. This iterator automatically handles upwards/downwards movement.

The Lua callback function recieves 1 parameter: the integer value.

If the callback function script produces an error, the iteration stops and the error message is added to the script output. However, the script doesn't abort when a callback function produces an error.

Lua-supported.

Example of usage:

local function myintcallback(i)
   print ("Number: ", i)
end
    
local iterator = finale.FCLuaIterator()
iterator:ForEachInteger(10, 1, myintcallback) -- Go downwards

Parameters

[in]	integer1	The first (source) integer. If this value is larger than integer2, the iteration will go downwards.
[in]	integer2	The second (target) integer.
[in]	lua_callback_function	The Lua callback function.

Returns: The number of processed integers.

◆ ForEachNote()

int FCLuaIterator::ForEachNote	(	FCMusicRegion *	pRegion,
		luabridge::LuaRef	lua_callback_function )

inline

Browses through all notes (as in noteheads) in a region. If a note entry consists of a chord with multiple notes, the Lua callback function is called for each note.

Rests entries are not processed.

The Lua callback function recieves 1 parameter: a FCNote object.

Please refer to the table in the class details for info about the filters that are compatible with this method.

If the callback function script produces an error, the iteration stops and the error message is added to the script output. However, the script doesn't abort when a callback function produces an error.

Lua-supported.

Example of usage:

local dsharpcount = 0
 
local function mynotecallback(note)
   local str = finale.FCString()
   note:GetString(str, nil, true)
   if str:StartsWith("D#") then
      dsharpcount = dsharpcount + 1
   end
end
 
local iterator = finale.FCLuaIterator()
iterator:ForEachNote(finenv.Region(), mynotecallback)
print("Number of D Sharps:", dsharpcount)

Parameters

[in]	pRegion	The region where the notes should be processed. If this is NULL and GetNullRegionEqualsAll() is true, the full document will be used as region.
[in]	lua_callback_function	The Lua callback function.

Returns: The number of processed entries.

◆ ForEachNoteSaved()

int FCLuaIterator::ForEachNoteSaved	(	FCMusicRegion *	pRegion,
		luabridge::LuaRef	lua_callback_function )

inline

Browses through all notes (as in noteheads) in a region and saves the entries. If a note entry consists of a chord with multiple notes, the callback function is called for each note.

Rests entries are not processed.

This method is identical to ForEachNote, except that each note entry is saved as well.

The Lua callback function recieves 1 parameter: a FCNote object.

Please refer to the table in the class details for info about the filters that are compatible with this method.

If the callback function script produces an error, the iteration stops and the error message is added to the script output. However, the script doesn't abort when a callback function produces an error.

Lua-supported.

Example of usage:

local iterator = finale.FCLuaIterator()

iterator:ForEachNoteSaved(finenv.Region(), function(note) note.Tie = false end)

Parameters

[in]	pRegion	The region where the notes should be processed. If this is NULL and GetNullRegionEqualsAll() is true, the full document will be used as region.
[in]	lua_callback_function	The Lua callback function.

Returns: The number of processed entries.

◆ ForEachObject()

int FCLuaIterator::ForEachObject	(	int	classID,
		luabridge::LuaRef	lua_callback_function )

inline

Loads all the objects of a specific type and sends them to a Lua callback function.

The Lua callback function recieves 1 parameter: the object in the collection.

This method is a bit similar 'loadall()' iterator, used in 'for' loops in JW Lua. The main difference is that this method uses the single object class as the parameter, while 'loadall()' uses the collection class.

After loading the data, the iterator itself is based on ForEach.

These class ID constants are supported by this method:

FCID_ARTICULATIONDEF
FCID_CATEGORYDEF
FCID_CHORD
FCID_CLEFDEF
FCID_CUSTOMSMARTLINEDEF
FCID_EXECUTABLESHAPEDEF
FCID_FRETBOARDSTYLEDEF
FCID_FRETBOARDGROUPDEF
FCID_FRETINSTRUMENTDEF
FCID_GROUP
FCID_INSTRUMENTDEF
FCID_MEASURE
FCID_MEASURENUMBERREGION
FCID_MULTIMEASUREREST
FCID_MULTISTAFFINSTRUMENT
FCID_PAGE
FCID_PAGEGRAPHIC
FCID_PAGETEXT
FCID_SHAPEDEF
FCID_SHAPEEXPRESSIONDEF
FCID_SMARTSHAPE
FCID_STAFF
FCID_STAFFSTYLEDEF
FCID_STAFFSYSTEM
FCID_TEXTEXPRESSIONDEF
FCID_TEXTREPEATDEF

Lua-supported.

Example of usage:

local function mycallback(textexprdef)
   if textexprdef.ExecutableShapeID ~= 0 then
      print ("Text Expression Def", textexprdef.ItemNo, "has an executable shape.")
   end
end
 
local iterator = finale.FCLuaIterator()
iterator:ForEachObject(finale.FCID_TEXTEXPRESSIONDEF, mycallback)

Parameters

[in]	classID	The class ID constant. Any of the supported FCID_ constants listed in the documentation for this method.
[in]	lua_callback_function	The Lua callback function.

Returns: The number of processed objects.

◆ ForEachObjectSaved()

int FCLuaIterator::ForEachObjectSaved	(	int	classID,
		luabridge::LuaRef	lua_callback_function )

inline

Loads all the objects of a specific type and sends them to a Lua callback function. After callback has processed the object, each object is saved.

The Lua callback function recieves 1 parameter: the object in the collection.

This method is identical to ForEachObject, except that the objects are saved.

Lua-supported.

Example of usage:

local function mycallback(texrepeatdef)
   texrepeatdef.UseThisFont = false
end
 
local iterator = finale.FCLuaIterator()
iterator:ForEachObjectSaved(finale.FCID_TEXTREPEATDEF, mycallback)

Parameters

[in]	classID	The class ID constant. Any of the supported FCID_ constants listed in the documentation for ForEachObject.
[in]	lua_callback_function	The Lua callback function.

Returns: The number of processed objects.

◆ ForEachPart()

int FCLuaIterator::ForEachPart ( luabridge::LuaRef lua_callback_function )

inline

Browses through all the parts in the current document, and passes the part to the callback function. When the callback function is called, the part has already automatically been set in editing focus.

The Lua callback function recieves 1 parameter: The FCPart object.

The method GetProcessScorePart and GetProcessCurrentPart affect which of the parts that will be processed.

If the callback function script produces an error, the iteration stops and the error message is added to the script output. However, the script doesn't abort when a callback function produces an error.

Lua-supported.

Parameters

[in] lua_callback_function The Lua callback function.

Returns: The number of processed parts.

◆ ForEachRegionObject()

int FCLuaIterator::ForEachRegionObject	(	FCMusicRegion *	pRegion,
		int	classID,
		luabridge::LuaRef	lua_callback_function )

inline

Loads all the objects of a specific type within a selected region and sends them to a Lua callback function.

The Lua callback function recieves 1 parameter: the object.

Please refer to the table in the class details for info about the filters that are compatible with this method.

These class ID constants are supported by this method:

FCID_ACCIDENTALMOD
FCID_ARTICULATION
FCID_BEATCHARTELEMENT
FCID_BROKENBEAMMOD
FCID_CELLTEXT
FCID_CHORD
FCID_CROSSSTAFFMOD
FCID_CUSTOMSTEMMOD
FCID_DOTMOD
FCID_ENTRYALTERMOD
FCID_EXPRESSION
FCID_MIDIEXPRESSION
FCID_NOTEHEADMOD
FCID_PERCUSSIONNOTEMOD
FCID_PERFORMANCEMOD
FCID_SECONDARYBEAMBREAKMOD
FCID_SEPARATEMEASURENUMBER
FCID_SMARTSHAPEENTRYMARK
FCID_STEMMOD
FCID_SYLLABLEENTRYMOD
FCID_TABLATURENOTEMOD
FCID_TUPLET

Lua-supported.

Parameters

[in]	pRegion	The pointer to the region object. If this is NULL and GetNullRegionEqualsAll() is true, the full document will be used as region.
[in]	classID	The class ID constant. Any of the supported FCID_ constants listed in the documentation for this method.
[in]	lua_callback_function	The Lua callback function.

Returns: The number of processed objects.

◆ ForEachRegionObjectSaved()

int FCLuaIterator::ForEachRegionObjectSaved	(	FCMusicRegion *	pRegion,
		int	classID,
		luabridge::LuaRef	lua_callback_function )

inline

Loads all the objects of a specific type that appears within a region and sends them to a Lua callback function. After callback has processed the object, each object is saved.

The Lua callback function recieves 1 parameter: the object.

Please refer to the table in the class details for info about the filters that are compatible with this method.

This method is identical to ForEachRegionObject, except that the objects are saved.

Lua-supported.

Parameters

[in]	pRegion	The pointer to the region object. If this is NULL and GetNullRegionEqualsAll() is true, the full document will be used as region.
[in]	classID	The class ID constant. Any of the supported FCID_ constants listed in the documentation for ForEachRegionObject.
[in]	lua_callback_function	The Lua callback function.

Returns: The number of processed objects.

◆ ForEachSaved()

int FCLuaIterator::ForEachSaved	(	__FCCollectionData *	pCollection,
		luabridge::LuaRef	lua_callback_function )

inline

Browses through the items in a collection. After the Lua callback function has processed the object, the object is saved.

This method is identical to ForEach, except that each object is saved as well.

The Lua callback function recieves 1 parameter: the object in the collection.

Lua-supported.

Example of usage:

local function mymeasurehandler(measure)
   measure.Width = measure.Width * 1.10
end
 
local allmeasures = finale.FCMeasures()
allmeasures:LoadAll()
local iterator = finale.FCLuaIterator()
iterator:ForEachSaved(allmeasures, mymeasurehandler)

Parameters

[in]	pCollection	The collection with loaded items, of any class that inherits __FCCollectionData.
[in]	lua_callback_function	The Lua callback function.

Returns: The number of processed items.

◆ GetAbortableProgressBar()

bool FCLuaIterator::GetAbortableProgressBar ( ) const

inline

Returns if the progress bar should be abortable (by the Esc key).

Lua-supported (also as property).

◆ GetDownwardProcessing()

bool FCLuaIterator::GetDownwardProcessing ( ) const

inline

Returns the vertical direction for processing staves in the iteration, for region-based iterators.

Lua-supported (also as property).

Returns: true - Iteration goes from top-selected staff and downwards. false - Iteration goes from bottom-selected staff and upwards.

◆ GetForwardProcessing()

bool FCLuaIterator::GetForwardProcessing ( ) const

inline

Returns the direction of the iteration.

By default, the iterator processes the lowest/first element first and goes upwards towards the last element. For some actions however (such as deleting data or inserting data that affects the end of a list), iterating backwards through the data is required.

Lua-supported (also as property).

Returns: true - Iteration goes from first element to last. false - Iteration goes from last element to first.

◆ GetLoadLayerMode()

int FCLuaIterator::GetLoadLayerMode ( ) const

inline

Returns the load layer mode for the note entry iterators, such as ForEachEntry(), ForEachNote(), etc.

This method is identical to the one found at FCNoteEntryCell::GetLoadLayerMode().

Lua-supported (also as property).

◆ GetNullRegionEqualsAll()

bool FCLuaIterator::GetNullRegionEqualsAll ( ) const

inline

Returns if NULL regions should automatically be interpreted as a full document region, or not. This setting affects all region-based iterators.

Lua-supported (also as property).

◆ GetPartialMeasureSelections()

bool FCLuaIterator::GetPartialMeasureSelections ( ) const

inline

Returns partially selected measures should be processed.

Lua-supported (also as property).

Returns: true - Measures which are partially selected will also be processed (in addition to fully processed measures). false - Only fully selected measure will be processed.

◆ GetProcessCurrentDocument()

bool FCLuaIterator::GetProcessCurrentDocument ( ) const

inline

Returns if the document currently in editing focus should be processed in ForEachDocument and ForEachDocumentSaved calls.

Lua-supported (also as property).

◆ GetProcessCurrentPart()

bool FCLuaIterator::GetProcessCurrentPart ( ) const

inline

Returns if the part currently in editing focus should be processed in ForEachPart calls.

Lua-supported (also as property).

◆ GetProcessScorePart()

bool FCLuaIterator::GetProcessScorePart ( ) const

inline

Returns if the score part (the part with part ID 0) should be processed in ForEachPart calls.

Lua-supported (also as property).

◆ GetProgressBarUserAborted()

bool FCLuaIterator::GetProgressBarUserAborted ( ) const

inline

Returns true if the processing was aborted by the user (using the Esc key) during the last processing.

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

◆ GetProgressUpdateFrequency()

int FCLuaIterator::GetProgressUpdateFrequency ( ) const

inline

Returns the update frequency for the progress bar.

Lua-supported (also as property).

◆ GetUseProgressBar()

bool FCLuaIterator::GetUseProgressBar ( ) const

inline

Returns if the update progress bar should be used or not.

Lua-supported (also as property).

◆ IsAltNotationFilterAdded()

bool FCLuaIterator::IsAltNotationFilterAdded	(	int	filter,
		int	logicmode )

inline

Returns true if a specific filter for alternate notation has been added/activated for the iterator.

Lua-supported.

\param [in] filter Any of the ALTSTAFF_ constants.

\param [in] logicmode Any of the LILOGIC_ constants (#LILOGIC_AND, #LILOGIC_OR, #LILOGIC_NOT).

\return True if the alternate notation filter is available.

◆ IsEntryFilterAdded()

bool FCLuaIterator::IsEntryFilterAdded	(	int	filter,
		int	logicmode )

inline

Returns true if a specific note entry filter has been added/activated for the iterator.

Lua-supported.

Parameters

[in]	filter	Any of the LIEFILTER_ constants.
[in]	logicmode	Any of the LILOGIC_ constants (LILOGIC_AND, LILOGIC_OR, LILOGIC_NOT)

Returns: True if the note entry filter is available.

◆ IsNotationStyleFilterAdded()

bool FCLuaIterator::IsNotationStyleFilterAdded	(	int	filter,
		int	logicmode )

inline

Returns true if a specific filter for a notation style has been added/activated for the iterator.

Lua-supported.

Parameters

[in]	filter	Any of the STAFFNOTATION_ constants.
[in]	logicmode	Any of the LILOGIC_ constants (LILOGIC_AND, LILOGIC_OR, LILOGIC_NOT)

Returns: True if the notation style filter is available.

◆ IsNoteFilterAdded()

bool FCLuaIterator::IsNoteFilterAdded	(	int	filter,
		int	logicmode )

inline

Returns true if a specific note filter has been added/activated for the iterator.

Lua-supported.

Parameters

[in]	filter	Any of the LINFILTER_ constants.
[in]	logicmode	Any of the LILOGIC_ constants (LILOGIC_AND, LILOGIC_OR, LILOGIC_NOT).

Returns: True if the note entry filter is available.

◆ RemoveAltNotationFilter()

bool FCLuaIterator::RemoveAltNotationFilter	(	int	filter,
		int	logicmode )

inline

Removes a alternate notation filter.

If all alternate notation filters should be removed/cleared, use ClearAllAltNotationFilters() instead.

Lua-supported.

Parameters

[in]	filter	Any of the ALTSTAFF_ constants.
[in]	logicmode	Any of the LILOGIC_ constants (LILOGIC_AND, LILOGIC_OR, LILOGIC_NOT)

Returns: True if the filter was removed. False if it didn't exist.

◆ RemoveEntryFilter()

bool FCLuaIterator::RemoveEntryFilter	(	int	filter,
		int	logicmode )

inline

Removes a note entry filter.

If all note entry filters should be removed/cleared, use ClearAllEntryFilters() instead.

Lua-supported.

Parameters

[in]	filter	Any of the LIEFILTER_ constants.
[in]	logicmode	Any of the LILOGIC_ constants (LILOGIC_AND, LILOGIC_OR, LILOGIC_NOT)

Returns: True if the filter was removed. False if it didn't exist.

◆ RemoveNotationStyleFilter()

bool FCLuaIterator::RemoveNotationStyleFilter	(	int	filter,
		int	logicmode )

inline

Removes a notation style filter.

If all notation style filters should be removed/cleared, use ClearAllAltNotationFilters() instead.

Lua-supported.

Parameters

[in]	filter	Any of the STAFFNOTATION_ constants.
[in]	logicmode	Any of the LILOGIC_ constants (LILOGIC_AND, LILOGIC_OR, LILOGIC_NOT)

Returns: True if the filter was removed. False if it didn't exist.

◆ RemoveNoteFilter()

bool FCLuaIterator::RemoveNoteFilter	(	int	filter,
		int	logicmode )

inline

Removes a note filter.

If all note filters should be removed/cleared, use ClearAllNoteFilters() instead.

Lua-supported.

Parameters

[in]	filter	Any of the LINFILTER_ constants.
[in]	logicmode	Any of the LILOGIC_ constants (LILOGIC_AND, LILOGIC_OR, LILOGIC_NOT)

Returns: True if the filter was removed. False if it didn't exist.

◆ SetAbortableProgressBar()

void FCLuaIterator::SetAbortableProgressBar ( bool state )

inline

Sets if the progress bar should be abortable (by the Esc key).

Lua-supported (also as property).

◆ SetDownwardProcessing()

void FCLuaIterator::SetDownwardProcessing ( bool downward )

inline

Sets the vertical direction for processing staves in the iteration, for region-based iterators.

There's no performance difference between going downwards or upwards in an iterator.

Lua-supported (also as property).

Parameters

downward true - Iteration goes from top-selected staff and downwards. false - Iteration goes from bottom-selected staff and upwards.

◆ SetForwardProcessing()

void FCLuaIterator::SetForwardProcessing ( bool forward )

inline

Sets the direction of the iteration.

By default, the iterator processes the lowest/first element first and goes upwards towards the last element. For some actions however (such as deleting data or inserting data that affects the end of a list), iterating backwards through the data is required.

Please note that some types of backward iteration can be slower than forward iteration, so don't use it unless required.

Lua-supported (also as property).

Parameters

forward true - Iteration goes from first element to last. false - Iteration goes from last element to first.

◆ SetLoadLayerMode()

void FCLuaIterator::SetLoadLayerMode ( int loadlayermode )

inline

Sets the load layer mode for the note entry iterators, such as ForEachEntry(), ForEachNote(), etc.

This method is identical to the one found at FCNoteEntryCell::SetLoadLayerMode().

Lua-supported (also as property).

◆ SetNullRegionEqualsAll()

void FCLuaIterator::SetNullRegionEqualsAll ( bool state )

inline

Sets if NULL regions should automatically be interpreted as a full document region, or not. This setting affects all region-based iterators.

Lua-supported (also as property).

◆ SetPartialMeasureSelections()

void FCLuaIterator::SetPartialMeasureSelections ( bool partialselections )

inline

Returns partially selected measures should be processed.

Lua-supported (also as property).

Parameters

partialselections true - Measures which are partially selected will also be processed (in addition to fully processed measures). false - Only fully selected measure will be processed.

◆ SetProcessCurrentDocument()

void FCLuaIterator::SetProcessCurrentDocument ( bool state )

inline

Sets if the document currently in editing focus should be processed in ForEachDocument and ForEachDocumentSaved calls.

Lua-supported (also as property).

◆ SetProcessCurrentPart()

void FCLuaIterator::SetProcessCurrentPart ( bool state )

inline

Sets if the part currently in editing focus should be processed in ForEachPart calls.

Lua-supported (also as property).

◆ SetProcessScorePart()

void FCLuaIterator::SetProcessScorePart ( bool state )

inline

Sets if the score part (the part with part ID 0) should be processed in ForEachPart calls.

Lua-supported (also as property).

◆ SetProgressUpdateFrequency()

void FCLuaIterator::SetProgressUpdateFrequency ( int freq )

inline

Sets the update frequency for the progress bar.

Higher frequency values improves performance, but reduces accuracy of the progress bar.

Lua-supported (also as property).

Parameters

[in] freq The number of items processed items that should be made before the progress bar is visually updated. 1 or above are allowed. 1 means a progress bar update for every processed item.

◆ SetUseProgressBar()

void FCLuaIterator::SetUseProgressBar ( bool use )

inline

Sets if the update progress bar should be used or not.

Please note that, although it provides info to the user, the progress bar will slow down the processing.

Lua-supported (also as property).

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ LUAITERATOR_ENTRYFILTERS

◆ LUAITERATOR_LOGICMETHOD

◆ LUAITERATOR_NOTEFILTERS

Constructor & Destructor Documentation

◆ FCLuaIterator()

Member Function Documentation

◆ AddAltNotationFilter()

◆ AddEntryFilter()

◆ AddNotationStyleFilter()

◆ AddNoteFilter()

◆ CalcLastDuration()

◆ ClassName()

◆ ClearAllAltNotationFilters()

◆ ClearAllEntryFilters()

◆ ClearAllNotationStyleFilters()

◆ ClearAllNoteFilters()

◆ ForEach()

◆ ForEachCell()

◆ ForEachDocument()

◆ ForEachDocumentSaved()

◆ ForEachEntry()

◆ ForEachEntrySaved()

◆ ForEachFile()

◆ ForEachFileSaved()

◆ ForEachInteger()

◆ ForEachNote()

◆ ForEachNoteSaved()

◆ ForEachObject()

◆ ForEachObjectSaved()

◆ ForEachPart()

◆ ForEachRegionObject()

◆ ForEachRegionObjectSaved()

◆ ForEachSaved()

◆ GetAbortableProgressBar()

◆ GetDownwardProcessing()

◆ GetForwardProcessing()

◆ GetLoadLayerMode()

◆ GetNullRegionEqualsAll()

◆ GetPartialMeasureSelections()

◆ GetProcessCurrentDocument()

◆ GetProcessCurrentPart()

◆ GetProcessScorePart()

◆ GetProgressBarUserAborted()

◆ GetProgressUpdateFrequency()

◆ GetUseProgressBar()

◆ IsAltNotationFilterAdded()

◆ IsEntryFilterAdded()

◆ IsNotationStyleFilterAdded()

◆ IsNoteFilterAdded()

◆ RemoveAltNotationFilter()

◆ RemoveEntryFilter()

◆ RemoveNotationStyleFilter()

◆ RemoveNoteFilter()

◆ SetAbortableProgressBar()

◆ SetDownwardProcessing()

◆ SetForwardProcessing()

◆ SetLoadLayerMode()

◆ SetNullRegionEqualsAll()

◆ SetPartialMeasureSelections()

◆ SetProcessCurrentDocument()

◆ SetProcessCurrentPart()

◆ SetProcessScorePart()

◆ SetProgressUpdateFrequency()

◆ SetUseProgressBar()