Class that encapsulates EREGION and provides additional functionality to region handling. More...

#include <ff_region.h>

Inheritance diagram for FCMusicRegion:

Public Types
enum	REBARSTOPS { REBARSTOP_NONE = REBAR_NO_STOP , REBARSTOP_KEY = REBAR_STOP_KEYCHANGE , REBARSTOP_TIME = REBAR_STOP_TIMECHANGE , REBARSTOP_REGIONEND = REBAR_STOP_ENDOFREGION , REBARSTOP_SPECIALBARLINE = REBAR_STOP_SPECIALBARLINE , REBARSTOP_EMPTYFRAME = REBAR_STOP_EMPTYFRAME , REBARSTOP_EMPTYFRAMEAFTERREGION = REBAR_STOP_EMPTYFRAMEAFTERREGION }
	Stop constants for the FCMusicRegion::RebarMusic() method. 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. More...

	FCMusicRegion (EREGION *pRegion=NULL)
	The constructor. Copies the EREGION data to the object, if available. More...

virtual	~FCMusicRegion ()
	The destructor.

void	AssureSortedStaves ()
	Makes sure that the start staff is above the end staff in the instrument list for the region. More...

void	Clear ()
	Empties the region. More...

bool	IsEmpty () const
	Returns true if the region is empty. More...

bool	IsSinglePos () const
	Returns true if the region is empty, but represents a single horizontal location in the document. More...

bool	IsEmptyAndNotSinglePos () const
	Returns true if the region is empty and it is not a single-position region. Finale itself treats single-position regions as non-empty, so use this function if you need to find out if the region is empty from a Finale perspective. More...

bool	IsMeasureIncluded (twobyte measureno)
	Returns true if the measure number is with the region. Please note that it doesn't check for partial measures. More...

bool	IsAbsoluteEndMeasurePos ()
	Returns true if the right-side measure position in the end measure is at the absolute far right end (beyond all duration positions). More...

bool	IsFullMeasureIncluded (twobyte measureno)
	Returns true if the full measure is with the region. More...

bool	IsStaffIncluded (twobyte staffnumber) const
	Returns true if the staff number is with the region. More...

bool	IsSlotIncluded (twobyte slotnumber) const
	Returns true if the slot number is with the region. More...

bool	IsMeasurePosWithin (int measure, TimeEdu32 pos)
	Returns true if the measure/edu position is horizontally within the region span. This method doesn't check for a staff match. More...

bool	IsStartPos (const int measure, const TimeEdu32 pos)
	Returns true if the supplied measure/edu values are identical to the region's start position. More...

bool	IsCellPosWithin (const FCCell *pCell, const TimeEdu32 pos)
	Checks if a cell position is within the region. This checks for partial measures. More...

bool	IsIdentical (const __FCBase *pCompareObject) const override
	Overridden virtual method. More...

bool	IsEntryPosWithin (const FCNoteEntry *pEntry)
	Checks if a entry is within the region. This checks for partial measures. More...

bool	IsPartial ()
	Returns true if the region contains a partially selected measure. More...

bool	IsMeasurePartial (eMeas measure)
	Returns true if a specific measure is partially selected. More...

bool	IsOverlapping (FCMusicRegion *pRegion)
	Returns true if the region overlaps with another region. More...

bool	IsFullDocumentSpan ()
	Returns true if the "width" of the region is the same as the whole document span. More...

bool	IsLastEndMeasure ()
	Returns true if the end measure in the selection is the end measure of the document. More...

bool	SetFullDocument ()
	Sets the region to span the full document. More...

bool	SetCurrentSelection ()
	Sets the region object to span the current selection in the document. More...

void	SetEnigmaRegion (EREGION *pRegion)
	Assigns an Enigma region to the document region.

void	SetRegion (FCMusicRegion *pSourceRegion)
	Copies another document region to the document region. More...

void	GetEnigmaRegion (EREGION *pRegion)
	Assigns the document region to an Enigma region structure.

void	SetStartMeasure (twobyte measure)
	Sets the start measure. More...

void	SetStartMeasurePos (TimeEdu32 pos)
	Sets the start measure pos in the start measure. More...

void	SetStartMeasurePosLeft ()
	Sets the start measure pos to the left-most edge of the region's start measure. More...

void	SetEndMeasure (twobyte measure)
	Sets the end measure for the region. More...

void	SetEndMeasurePos (TimeEdu32 pos)
	Sets the end measure pos in the end measure. More...

void	SetEndMeasurePosRight ()
	Sets the the end measure pos to the right-most edge of the region's end measure. More...

bool	SetFullMeasureStack ()
	Sets the full height of the measure stack for the current region. More...

void	SetInstrumentList (twobyte list)
	Sets the instrument list for the selection. If this method is called,' the start/end staff must be modified as well. More...

void	SetStartStaff (twobyte staff)
	Sets the start staff for the region. The staff must be available in the region's current instrument list, and it must be a higher staff than the end staff (staves starts counting from the top). More...

void	SetStartSlot (twobyte slot)
	Sets the start slot for the region directly. More...

void	SetEndStaff (twobyte staff)
	Sets the end staff for the region. The staff must be available in the region's current instrument list, and it must be a lower staff than the start staff (staves starts counting from the top). More...

void	SetEndSlot (twobyte slot)
	Sets the end slot for the region directly. More...

twobyte	GetStartMeasure () const
	Returns the start measure for the region. More...

twobyte	GetEndMeasure () const
	Returns the end measure for the region. More...

twobyte	GetInstrumentList () const
	Returns the instrument list number for the selection. More...

twobyte	GetStartSlot () const
	Returns the start slot (staff) for the region. More...

twobyte	GetEndSlot () const
	Returns the end slot (staff) for the region. More...

twobyte	GetStartStaff () const
	Returns the start staff number for the region. More...

twobyte	GetEndStaff () const
	Returns the end staff number for the region. More...

TimeEdu32	GetStartMeasurePos () const
	Returns the start position of the region within the measure. More...

TimeEdu32	GetEndMeasurePos () const
	Returns the end position of the region within the measure. More...

int	CalcMeasureSpan ()
	Calculates the number of measures in the region. More...

int	CalcStaffSpan ()
	Calculates the number of staves in the region. More...

twobyte	CalcStaffNumber (twobyte slot)
	Calculates the staff number, based on the region's slot number. More...

twobyte	CalcSlotNumber (twobyte staff) const
	Calculates the slot number based on a staff number. More...

TimeEdu32	CalcDuration ()
	Calculates the duration of the selection, in EDUs. More...

bool	SetDurationOffsetLeft (TimeEdu32 durationoffset)
	Sets position of the left side as a distance from the right region edge, in EDUs. More...

bool	SetDurationOffsetRight (TimeEdu32 durationoffset)
	Sets position of the right region side as a distance from the left region edge, in EDUs. More...

bool	IsCurrentDocument ()
	Returns true if the region belongs to the current document. More...

void	SetInDocument ()
	Updates the region visually in the document, if the region belongs to the current document. More...

void	ConvertToGlobalInstrumentList ()
	Transforms the region to use the global instrument list (instrument list 0). More...

int	ForEachStaff (FCIteratorHandler *pHandler)
	Iterates through each staff in the current selection through an iterator handler. More...

bool	CopyMusic ()
	Copies music to a clip file. It can then be pasted with PasteMusic. More...

bool	CutMusic ()
	Cuts out music to a clip file. It can then be pasted with PasteMusic. More...

bool	CutDeleteMusic ()
	Cuts out music to a clip file and deletes the area. It can then be pasted with PasteMusic. More...

bool	PasteMusic ()
	Paste a clip file that has been created with CopyMusic or CutMusic. More...

bool	ReleaseMusic ()
	Disposes a clip file that has been created with CopyMusic or CutMusic. More...

void	Redraw ()
	Redraws the music in the region. More...

void	RebeamMusic ()
	Rebeams the music in the region. More...

void	RebarMusic (int stopflags, bool rebeam, bool padwithrests)
	Rebars the music in the region. More...

bool	MusicMassMoverFrom (FCMusicRegion *pSourceRegion)
	Performs a Finale "mass mover" task from another FCMusicRegion to the object's region. More...

bool	AddMeasureOffset (int offset)
	"Moves" the music region horizontally by adding the offset to both the start and end measure values. Both negative and positive offsets can be added. More...

FCCells *	CreateCells ()
	Creates a FCCells object with all cells in the region. More...

bool	Playback (bool playtoend=false) const
	Playback the region. Only entire measures play back, so playback starts at the beginning of the first measure and stops at the end of the last measure of the FCMusicRegion. Only selected staves in the region play back. The user can click in the document window at any time to interrupt and end playback. More...

bool	PlaybackSingleStaff (eStaff staffnum, bool playtoend=false) const
	Playback a single staff in the region. Only entire measures play back, so playback starts at the beginning of the first measure and stops at the end of the last measure of the FCMusicRegion. More...

void	FixMeasureWidthsInScore () const
	Works around a bug in Finale when modifying measure widths with a part in edit focus. More...

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

Public Member Functions inherited from __FCBase
virtual const PDKFRAMEWORK_CLASSID	GetClassID () const
	Returns the internal class ID for the PDK Framework class. This is implemented mostly because Lua has problems to resolve the true classes of inherited objects. More...

virtual	~__FCBase ()
	Virtual destructor, so all inherited classes get the virtual destructor.

void	DebugMsgInt (const char *pszPrefixText, int i)
	Creates a simple Message Box for debug purposes. The text appears with the extra digit (in decimal presentation) appearing afterwards. More...

void	DebugMsgHex (const char *pszPrefixText, int i)
	Creates a simple Message Box for debug purposes. The text appears with the extra digit (as a hexadecimal number) appearing afterwards. More...

void	DebugMsgString (const char pszPrefixText, const char thestring)
	Creates a simple Message Box for debug purposes. The text appears with the extra string appearing afterwards. More...

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

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

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

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

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

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

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

bool	GetBitFlag (FLAG_32 flag, FLAG_32 flagbits) const
	Gets a state from flag bits. Returns true if any bit in the mask is set. More...

int	GetBitCount (FLAG_32 flag)
	Returns the total number of set bits in a 32-bit unsigned int.

void	SetSpecific32Bit (FLAG_32 *flag, int bitnumber, bool state)
	Sets/resets a single bit in a 32 bit flag, by specifying one specific bit. More...

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

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

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

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

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

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

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

void	StoreXML_StringAttribute (tinyxml2::XMLElement pNode, const char pszAttributeName, FCString *pStringValue)
	Helper function to store FCString objects in the XML file, as an attribute to a node. More...

void	StoreXML_IntegerAttribute (tinyxml2::XMLElement pNode, const char pszAttributeName, int value)
	Helper function to store integer objects in the XML file, as an attribute to a node. More...

void	StoreXML_BoolAttribute (tinyxml2::XMLElement pNode, const char pszAttributeName, bool value)
	Helper function to store boolean objects in the XML file, as an attribute to a node. More...

void	StoreXML_FloatAttribute (tinyxml2::XMLElement pNode, const char pszAttributeName, float value)
	Helper function to store floating point objects in the XML file, as an attribute to a node. More...

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

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

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

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

bool	ReadXML_StringAttribute (tinyxml2::XMLElement pNode, const char pszAttributeName, FCString *pStringValue)
	Helper method to read FCString objects from the XML file, as an attribute to a node. More...

bool	ReadXML_IntegerAttribute (tinyxml2::XMLElement pNode, const char pszAttributeName, int *pValue)
	Helper method to read integer objects from the XML file, as an attribute to a node. More...

bool	ReadXML_BoolAttribute (tinyxml2::XMLElement pNode, const char pszAttributeName, bool *pValue)
	Helper method to read boolean objects from the XML file, as an attribute to a node. More...

bool	ReadXML_FloatAttribute (tinyxml2::XMLElement pNode, const char pszAttributeName, float *pValue)
	Helper method to read floating point objects from the XML file, as an attribute to a node. More...

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

Additional Inherited Members
Static Public Member Functions inherited from __FCBase
static void	DebugOutPtr (const char pszPrefixText, void ptr)
	Static method that outputs a line for debugging purposes. The prefix text appears with the extra ptr (in hexadeximal representation) appearing afterwards. More...

static void	DebugOutInt (const char *pszPrefixText, int i)
	Static method that outputs a line for debugging purposes. The text appears with the extra digit (in decimal presentation) appearing afterwards. More...

static void	DebugOutFloat (const char *pszPrefixText, double f)
	Static method that outputs a line for debugging purposes. The text appears with the extra float value appearing afterwards. More...

static void	DebugOutTag (const char *pszPrefixText, EXTAG extag)
	Static method that outputs a line for debugging purposes. The text appears with the EXTAG (in text) appearing afterwards. More...

static void	DebugOutHex (const char *pszPrefixText, int i)
	Static method that outputs a line for debugging purposes. The text appears with the extra digit (in hexadecimal presentation) appearing afterwards. More...

static void	DebugOutBin (const char *pszPrefixText, int i)
	Static method that outputs a line for debugging purposes. The text appears with the extra digit (in binary presentation) appearing afterwards. More...

static void	DebugOutString (const char pszPrefixText, const char thestring)
	Static method that outputs a line for debugging purposes (C string version). The text appears with the extra string appearing afterwards. More...

static void	DebugOutString (const char pszPrefixText, FCString pString)
	Static method that outputs a line for debugging purposes (FCString version). The text appears with the extra string appearing afterwards. More...

static void	DebugOutBool (const char *pszPrefixText, bool state)
	Static method that outputs a line for debugging purposes. The boolean state appears afterwards as either "TRUE" or "FALSE". More...

static void	DebugOutBlock (const void *pBuffer, int startoffset, int size)
	Static method that outputs a memory block for debugging purposes. Eight bytes per line will appear (as hex digits) until the whole memory block is dumped. More...

static void	DebugOutByteArrayBlock (const void *pBuffer, int startoffset, int size)
	Static method that outputs a memory block for debugging purposes. Eight bytes per line will appear (as hex digits) as a C++ onebyte array, until the whole memory block is dumped. More...

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

Protected Member Functions inherited from __FCBase
	__FCBase ()
	The constructor.

Detailed Description

Class that encapsulates EREGION and provides additional functionality to region handling.

The document ID is also stored when the region is set, so a plug-in can optionally check that the region really "belongs" to the correct document.

Member Enumeration Documentation

◆ REBARSTOPS

enum FCMusicRegion::REBARSTOPS

Stop constants for the FCMusicRegion::RebarMusic() method.

Lua-supported.

Enumerator
REBARSTOP_NONE	Rebar until end of piece.
REBARSTOP_KEY	Stop at key signature changes.
REBARSTOP_TIME	Stop at time signature changes.
REBARSTOP_REGIONEND	Stop at the end of the region.
REBARSTOP_SPECIALBARLINE	Stop at any non-normal barline.
REBARSTOP_EMPTYFRAME	Stop at empty frame
REBARSTOP_EMPTYFRAMEAFTERREGION	Always rebar through region, but stop at an empty frame after that.

Constructor & Destructor Documentation

◆ FCMusicRegion()

FCMusicRegion::FCMusicRegion ( EREGION * pRegion = NULL )

The constructor. Copies the EREGION data to the object, if available.

If pRegion is NULL, the region will be empty. Lua scripts omit the pRegion parameter.

Lua-supported.

Member Function Documentation

◆ AddMeasureOffset()

bool FCMusicRegion::AddMeasureOffset ( int offset )

inline

"Moves" the music region horizontally by adding the offset to both the start and end measure values. Both negative and positive offsets can be added.

This method only affects the internal measure values for the region, not the visual representation of a region.

Parameters

offset A negative value will result in a move to the left.

Returns: True on success. False if the offset results in measure numbers outside the 1..32767 range measures, or if the region is empty.

◆ AssureSortedStaves()

void FCMusicRegion::AssureSortedStaves ( )

Makes sure that the start staff is above the end staff in the instrument list for the region.

Lua-supported.

◆ CalcDuration()

TimeEdu32 FCMusicRegion::CalcDuration ( )

Calculates the duration of the selection, in EDUs.

Lua-supported.

◆ CalcMeasureSpan()

int FCMusicRegion::CalcMeasureSpan ( )

inline

Calculates the number of measures in the region.

Lua-supported.

Returns: The number of measures of the total region span. Partial measures counts as one full measure. 1 if IsSinglePos() returns true. 0 if IsEmpty() returns true.

◆ CalcSlotNumber()

twobyte FCMusicRegion::CalcSlotNumber ( twobyte staff ) const

inline

Calculates the slot number based on a staff number.

The slot number is based on the instrument list that the region uses.

Lua-supported.

Parameters

staff The staff number is a 1-based absolute number, that can be used to load the staff specification.

Returns: The 1-based slot in the region's instrument list. 0 on error.

◆ CalcStaffNumber()

twobyte FCMusicRegion::CalcStaffNumber ( twobyte slot )

inline

Calculates the staff number, based on the region's slot number.

The slot number is based on the instrument list that the region uses. The staff number is a 1-based absolute number, that can be used to load the staff specification.

Lua-supported.

Parameters

slot	The 1-based slot in the region's instrument list.

Returns: The 1-based staff number. 0 on error.

◆ CalcStaffSpan()

int FCMusicRegion::CalcStaffSpan ( )

inline

Calculates the number of staves in the region.

Lua-supported.

Returns: The number of staves in the region.

◆ ClassName()

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

◆ Clear()

void FCMusicRegion::Clear ( )

inline

Empties the region.

Mirrors the EREGION method for clearing the region.

Lua-supported.

◆ ConvertToGlobalInstrumentList()

void FCMusicRegion::ConvertToGlobalInstrumentList ( )

Transforms the region to use the global instrument list (instrument list 0).

Lua-supported.

◆ CopyMusic()

bool FCMusicRegion::CopyMusic ( )

Copies music to a clip file. It can then be pasted with PasteMusic.

After the clip has been used, the clip file MUST be disposed with the ReleaseMusic method.

Lua-supported.

Returns: True on success. It's an error to use this method twice in succession without calling ReleaseMusic

◆ CreateCells()

FCCells * FCMusicRegion::CreateCells ( )

Creates a FCCells object with all cells in the region.

The caller is responsible for deleting the object from the heap after use.

If the cell is partially selected, it's included in the collection. A FCCells object will always be created, even if the region is empty.

Lua-supported.

Returns: The pointer to the created object.

◆ CutDeleteMusic()

bool FCMusicRegion::CutDeleteMusic ( )

Cuts out music to a clip file and deletes the area. It can then be pasted with PasteMusic.

After the clip has been used, the clip file MUST be disposed with the ReleaseMusic method.

Lua-supported.

Returns: True on success. It's an error to use this method twice in succession without calling ReleaseMusic

◆ CutMusic()

bool FCMusicRegion::CutMusic ( )

Cuts out music to a clip file. It can then be pasted with PasteMusic.

After the clip has been used, the clip file MUST be disposed with the ReleaseMusic method.

Lua-supported.

Returns: True on success. It's an error to use this method twice in succession without calling ReleaseMusic

◆ DebugDump()

void FCMusicRegion::DebugDump ( )

inlineoverridevirtual

Outputs the class data/information for debugging purposes.

Accessible if PDK_FRAMEWORK_DEBUG is defined.

When child class inherit this method to output the contents of its own members, it should call the parent before providing its own output.

Reimplemented from __FCBase.

◆ FixMeasureWidthsInScore()

void FCMusicRegion::FixMeasureWidthsInScore ( ) const

Works around a bug in Finale when modifying measure widths with a part in edit focus.

As of at least Finale 27.4 (the last version tested), Finale contains a bug that occasionally wreaks havoc on score spacing if you change the width of a measure with a part in edit focus. The bug is not limited to plugins. It also can happen if a user simply applies Note Spacing from the menu while the part is in view. What triggers the bug is the user executing Undo then Redo immediately following the part edit.

This function implements a workaround that side-steps the bug, at least in the test cases that have reproduced it. It checks if the score is in edit focus. If not, it

switches edit focus to the score.
loads each measure in the region.
adds 1 to its width, saves, subtracts 1 from its width, and saves.
switches edit focus back to the part.

This function should be called with the part in edit focus and be part of the same Undo block as the measure width edits in the part.

Lua-supported (0.73).

◆ ForEachStaff()

int FCMusicRegion::ForEachStaff ( FCIteratorHandler * pHandler )

Iterates through each staff in the current selection through an iterator handler.

The iterator handler is passed a loaded staff.

◆ GetEndMeasure()

twobyte FCMusicRegion::GetEndMeasure ( ) const

inline

Returns the end measure for the region.

Lua-supported (also as property).

Returns: The end measure of the region.

◆ GetEndMeasurePos()

TimeEdu32 FCMusicRegion::GetEndMeasurePos ( ) const

inline

Returns the end position of the region within the measure.

This value is useful for partial measure selections.

Lua-supported (also as property).

Returns: The start position of the region in the measure.

◆ GetEndSlot()

twobyte FCMusicRegion::GetEndSlot ( ) const

inline

Returns the end slot (staff) for the region.

The slot is an index in the instrument list for the region, see GetInstrumentList

If you want the staff number instead, use GetEndStaff.

Lua-supported (also as property).

Returns: The end slot.

◆ GetEndStaff()

twobyte FCMusicRegion::GetEndStaff ( ) const

inline

Returns the end staff number for the region.

Lua-supported (also as property).

Returns: The end staff number

◆ GetInstrumentList()

twobyte FCMusicRegion::GetInstrumentList ( ) const

inline

Returns the instrument list number for the selection.

Returns

The instrument list number. It can be:

0 (meaning the global score)
A 1-based "optimized" system number
A staff set constant (IU_STAFFSET1 and above)
The temporary instrument list (see FCSystemStaves::SaveToTemporaryInstrumentList)
The Special Part Extraction instrument list (see FCMiscDocPrefs::GetSpecialExtractionID)

Lua-supported.

◆ GetStartMeasure()

twobyte FCMusicRegion::GetStartMeasure ( ) const

inline

Returns the start measure for the region.

Lua-supported (also as property).

Returns: The start measure of the region.

◆ GetStartMeasurePos()

TimeEdu32 FCMusicRegion::GetStartMeasurePos ( ) const

inline

Returns the start position of the region within the measure.

This value is useful for partial measure selections.

Lua-supported (also as property).

Returns: The start position of the region in the measure. For full-measure selections, this is 0.

◆ GetStartSlot()

twobyte FCMusicRegion::GetStartSlot ( ) const

inline

Returns the start slot (staff) for the region.

The slot is an index in the instrument list for the region, see GetInstrumentList

If you want the staff number instead, use GetStartStaff.

Lua-supported (also as property).

Returns: The start slot.

◆ GetStartStaff()

twobyte FCMusicRegion::GetStartStaff ( ) const

inline

Returns the start staff number for the region.

Warning: Staff numbers can be in any order. If you need to iterate staff numbers in a region, iterate from GetStartSlot to GetEndSlot and use CalcStaffNumber inside the loop to get the staff number.

Lua-supported (also as property).

Returns: The start staff number

◆ IsAbsoluteEndMeasurePos()

bool FCMusicRegion::IsAbsoluteEndMeasurePos ( )

Returns true if the right-side measure position in the end measure is at the absolute far right end (beyond all duration positions).

Lua-supported.

◆ IsCellPosWithin()

bool FCMusicRegion::IsCellPosWithin	(	const FCCell *	pCell,
		const TimeEdu32	pos
	)

Checks if a cell position is within the region. This checks for partial measures.

Lua-supported.

◆ IsCurrentDocument()

bool FCMusicRegion::IsCurrentDocument ( )

Returns true if the region belongs to the current document.

(Each time the region is set, the current document ID is stored with it.)

Lua-supported.

◆ IsEmpty()

bool FCMusicRegion::IsEmpty ( ) const

inline

Returns true if the region is empty.

If the region ends at the same horizontal point as it starts, it is considered to be an empty region. Use IsSinglePos() to find out if that's the case.

Lua-supported.

Returns: True if the region is empty.

◆ IsEmptyAndNotSinglePos()

bool FCMusicRegion::IsEmptyAndNotSinglePos ( ) const

inline

Returns true if the region is empty and it is not a single-position region. Finale itself treats single-position regions as non-empty, so use this function if you need to find out if the region is empty from a Finale perspective.

Lua-supported (0.63).

◆ IsEntryPosWithin()

bool FCMusicRegion::IsEntryPosWithin ( const FCNoteEntry * pEntry )

Checks if a entry is within the region. This checks for partial measures.

This method requires PDK_FRAMEWORK_ENTRIES to be defined.

Lua-supported.

◆ IsFullDocumentSpan()

bool FCMusicRegion::IsFullDocumentSpan ( )

Returns true if the "width" of the region is the same as the whole document span.

Lua-supported.

◆ IsFullMeasureIncluded()

bool FCMusicRegion::IsFullMeasureIncluded ( twobyte measureno )

Returns true if the full measure is with the region.

Lua-supported.

◆ IsIdentical()

bool FCMusicRegion::IsIdentical ( const __FCBase * pCompareObject ) const

overridevirtual

Overridden virtual method.

It does NOT check the instrument list (comparison against start/end staves).

Lua-supported.

Reimplemented from __FCBase.

◆ IsLastEndMeasure()

bool FCMusicRegion::IsLastEndMeasure ( )

Returns true if the end measure in the selection is the end measure of the document.

Lua-supported.

◆ IsMeasureIncluded()

bool FCMusicRegion::IsMeasureIncluded ( twobyte measureno )

Returns true if the measure number is with the region. Please note that it doesn't check for partial measures.

Lua-supported.

◆ IsMeasurePartial()

bool FCMusicRegion::IsMeasurePartial ( eMeas measure )

Returns true if a specific measure is partially selected.

Parameters

measure The 1-based measure number.

Returns: true - The measure is partially selected. false - The measure is either unselected or fully selected.

◆ IsMeasurePosWithin()

bool FCMusicRegion::IsMeasurePosWithin	(	int	measure,
		TimeEdu32	pos
	)

Returns true if the measure/edu position is horizontally within the region span. This method doesn't check for a staff match.

Lua-supported.

◆ IsOverlapping()

bool FCMusicRegion::IsOverlapping ( FCMusicRegion * pRegion )

Returns true if the region overlaps with another region.

Lua-supported.

Parameters

pRegion The region to compare with.

◆ IsPartial()

bool FCMusicRegion::IsPartial ( )

Returns true if the region contains a partially selected measure.

Lua-supported.

◆ IsSinglePos()

bool FCMusicRegion::IsSinglePos ( ) const

inline

Returns true if the region is empty, but represents a single horizontal location in the document.

Lua-supported.

Returns: True if the start and end of the region point to the same horizontal location in the document.

◆ IsSlotIncluded()

bool FCMusicRegion::IsSlotIncluded ( twobyte slotnumber ) const

Returns true if the slot number is with the region.

The slot number is 1-based and in sequence, based on the region's instrument list.

Lua-supported.

◆ IsStaffIncluded()

bool FCMusicRegion::IsStaffIncluded ( twobyte staffnumber ) const

Returns true if the staff number is with the region.

Please note that the staff number might be any value and might not reflect the order of the staves in the score.

Lua-supported.

◆ IsStartPos()

bool FCMusicRegion::IsStartPos	(	const int	measure,
		const TimeEdu32	pos
	)

Returns true if the supplied measure/edu values are identical to the region's start position.

Lua-supported.

◆ MusicMassMoverFrom()

bool FCMusicRegion::MusicMassMoverFrom ( FCMusicRegion * pSourceRegion )

Performs a Finale "mass mover" task from another FCMusicRegion to the object's region.

Parameters

pSourceRegion The object containing the source region for the mass mover task.

Returns: True on success.

◆ PasteMusic()

bool FCMusicRegion::PasteMusic ( )

Paste a clip file that has been created with CopyMusic or CutMusic.

After the clip has been used, the clip file MUST be disposed with the ReleaseMusic method.

Lua-supported.

Returns: True on success.

◆ Playback()

bool FCMusicRegion::Playback ( bool playtoend = false ) const

Playback the region. Only entire measures play back, so playback starts at the beginning of the first measure and stops at the end of the last measure of the FCMusicRegion. Only selected staves in the region play back. The user can click in the document window at any time to interrupt and end playback.

Use PlaybackSingleStaff to play back a single staff in the region.

Use FCSystemStaves::SaveToTemporaryInstrumentList and FCSystemStaves::CreateMusicRegion to create a region that can play back an arbitrary collection of staves.

The Playback function makes a direct call to a playback function in the Finale PDK, and the PDK Framework has no control over how it behaves. The macOS version of Finale (as of 27.3) has a bug that when the document window is in focus, the user must click in the document window before playback starts. (Otherwise, playback starts when you call the function.) The easiest way to avoid the document window being in focus is to trigger the call to Playback from a command button on a dialog box. If the dialog box is modeless, you can use FCCustomLuaWindow::ShowModelessWithGrabbyFocus to open the dialog box. This allows the dialog box to grab focus when the user presses the button, so the document window can never have focus when Playback is called.

Another limitation is that the PDK playback function is a legacy function older than the Human Playback feature, and it does not recognize Human Playback options. Nevertheless, the function may be useful for quick audio proofing of selected staves over a limited range of measures. An example implementation that uses the underlying PDK function is the Play button in the Canonical Utilities plugin.

Note that in order to play back the exact staves in the region, Playback must modify the temporary instrument list. In order to minimize the impact of this, you should probably start a new Undo block for Playback and then roll it back when finished. Here is an example that might be used to implement a playback button on a dialog box.

finenv.StartNewUndoBlock("Playback Region", false) -- use true if you wish to save previous document edits.
finenv.Region():Playback()
finenv.EndUndoBlock(false) -- use finenv.StartNewUndoBlock if you will make further edits before returning to Finale.

Lua-supported (0.68).

Parameters

playtoend (optional) if true, play to the end of the piece (or until the user clicks in the document window)

Returns: false if error (no staves selected in region or unable to save the temporary instrument list)

◆ PlaybackSingleStaff()

bool FCMusicRegion::PlaybackSingleStaff	(	eStaff	staffnum,
		bool	playtoend = `false`
	)		const

inline

Playback a single staff in the region. Only entire measures play back, so playback starts at the beginning of the first measure and stops at the end of the last measure of the FCMusicRegion.

See comments at Playback for more information about the playback function.

Lua-supported (0.68).

Parameters

staffnum	the staff number to play back.
playtoend	(optional) if true, play to the end of the piece (or until the user clicks in the document window)

Returns: false if staffnum is not contained in FCMusicRegion::GetInstrumentList

◆ RebarMusic()

void FCMusicRegion::RebarMusic	(	int	stopflags,
		bool	rebeam,
		bool	padwithrests
	)

Rebars the music in the region.

Lua-supported.

Parameters

stopflags	Any of the REBARSTOP_ constants. Typically, this should be set to REBARSTOP_REGIONEND. REBARSTOP_NONE (0) means to continue until the end of the document. Any other constant combination can be added together as a bit set.
rebeam	If the region should be rebeamed or not.
padwithrests	If the end of the region should be padded with rests after the rebar.

◆ RebeamMusic()

void FCMusicRegion::RebeamMusic ( )

Rebeams the music in the region.

Lua-supported.

◆ Redraw()

void FCMusicRegion::Redraw ( )

Redraws the music in the region.

Lua-supported.

◆ ReleaseMusic()

bool FCMusicRegion::ReleaseMusic ( )

Disposes a clip file that has been created with CopyMusic or CutMusic.

Lua-supported.

Returns: True on success.

◆ SetCurrentSelection()

bool FCMusicRegion::SetCurrentSelection ( )

Sets the region object to span the current selection in the document.

Lua-supported

Returns: True if there was a user region. False if no user selection.

◆ SetDurationOffsetLeft()

bool FCMusicRegion::SetDurationOffsetLeft ( TimeEdu32 durationoffset )

Sets position of the left side as a distance from the right region edge, in EDUs.

Lua-supported.

Parameters

durationoffset Duration from the right region edge.

Returns: True if successful.

◆ SetDurationOffsetRight()

bool FCMusicRegion::SetDurationOffsetRight ( TimeEdu32 durationoffset )

Sets position of the right region side as a distance from the left region edge, in EDUs.

Lua-supported.

Parameters

durationoffset Duration from the left region edge.

Returns: True if successful.

◆ SetEndMeasure()

void FCMusicRegion::SetEndMeasure ( twobyte measure )

inline

Sets the end measure for the region.

Lua-supported (also as property).

Parameters

measure The 1-based measure number for the end measure.

◆ SetEndMeasurePos()

void FCMusicRegion::SetEndMeasurePos ( TimeEdu32 pos )

inline

Sets the end measure pos in the end measure.

Lua-supported (also as property).

Parameters

pos	The end position within the end measure, in Enigma duration units.

◆ SetEndMeasurePosRight()

void FCMusicRegion::SetEndMeasurePosRight ( )

inline

Sets the the end measure pos to the right-most edge of the region's end measure.

Lua-supported.

◆ SetEndSlot()

void FCMusicRegion::SetEndSlot ( twobyte slot )

inline

Sets the end slot for the region directly.

Lua-supported (also as property).

◆ SetEndStaff()

void FCMusicRegion::SetEndStaff ( twobyte staff )

inline

Sets the end staff for the region. The staff must be available in the region's current instrument list, and it must be a lower staff than the start staff (staves starts counting from the top).

Lua-supported (also as property).

◆ SetFullDocument()

bool FCMusicRegion::SetFullDocument ( )

Sets the region to span the full document.

Lua-supported.

Returns: True if the region was set. False on error.

◆ SetFullMeasureStack()

bool FCMusicRegion::SetFullMeasureStack ( )

Sets the full height of the measure stack for the current region.

This is dependent of the current staff/instrument list for the region. It's not necessarily so that the top/bottom staves will be the same as for the full document.

Lua-supported.

Returns: True if successful.

◆ SetInDocument()

void FCMusicRegion::SetInDocument ( )

Updates the region visually in the document, if the region belongs to the current document.

The document might need to redraw to display the change. The region will only be visually present if the currently selected tool in Finale supports regions.

Lua-supported.

◆ SetInstrumentList()

void FCMusicRegion::SetInstrumentList ( twobyte list )

inline

Sets the instrument list for the selection. If this method is called,' the start/end staff must be modified as well.

See GetInstrumentList() for more information on instrument lists.

Lua-supported.

◆ SetRegion()

void FCMusicRegion::SetRegion ( FCMusicRegion * pSourceRegion )

Copies another document region to the document region.

Lua-supported.

◆ SetStartMeasure()

void FCMusicRegion::SetStartMeasure ( twobyte measure )

inline

Sets the start measure.

Lua-supported (also as property).

Parameters

measure The 1-based measure number for the start measure.

◆ SetStartMeasurePos()

void FCMusicRegion::SetStartMeasurePos ( TimeEdu32 pos )

inline

Sets the start measure pos in the start measure.

Lua-supported (also as property).

Parameters

pos	The position within the start measure, in Enigma duration units.

◆ SetStartMeasurePosLeft()

void FCMusicRegion::SetStartMeasurePosLeft ( )

inline

Sets the start measure pos to the left-most edge of the region's start measure.

Lua-supported.

◆ SetStartSlot()

void FCMusicRegion::SetStartSlot ( twobyte slot )

inline

Sets the start slot for the region directly.

Lua-supported (also as property).

◆ SetStartStaff()

void FCMusicRegion::SetStartStaff ( twobyte staff )

inline

Sets the start staff for the region. The staff must be available in the region's current instrument list, and it must be a higher staff than the end staff (staves starts counting from the top).

Lua-supported (also as property).

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ REBARSTOPS

Constructor & Destructor Documentation

◆ FCMusicRegion()

Member Function Documentation

◆ AddMeasureOffset()

◆ AssureSortedStaves()

◆ CalcDuration()

◆ CalcMeasureSpan()

◆ CalcSlotNumber()

◆ CalcStaffNumber()

◆ CalcStaffSpan()

◆ ClassName()

◆ Clear()

◆ ConvertToGlobalInstrumentList()

◆ CopyMusic()

◆ CreateCells()

◆ CutDeleteMusic()

◆ CutMusic()

◆ DebugDump()

◆ FixMeasureWidthsInScore()

◆ ForEachStaff()

◆ GetEndMeasure()

◆ GetEndMeasurePos()

◆ GetEndSlot()

◆ GetEndStaff()

◆ GetInstrumentList()

◆ GetStartMeasure()

◆ GetStartMeasurePos()

◆ GetStartSlot()

◆ GetStartStaff()

◆ IsAbsoluteEndMeasurePos()

◆ IsCellPosWithin()

◆ IsCurrentDocument()

◆ IsEmpty()

◆ IsEmptyAndNotSinglePos()

◆ IsEntryPosWithin()

◆ IsFullDocumentSpan()

◆ IsFullMeasureIncluded()

◆ IsIdentical()

◆ IsLastEndMeasure()

◆ IsMeasureIncluded()

◆ IsMeasurePartial()

◆ IsMeasurePosWithin()

◆ IsOverlapping()

◆ IsPartial()

◆ IsSinglePos()

◆ IsSlotIncluded()

◆ IsStaffIncluded()

◆ IsStartPos()

◆ MusicMassMoverFrom()

◆ PasteMusic()

◆ Playback()

◆ PlaybackSingleStaff()

◆ RebarMusic()

◆ RebeamMusic()

◆ Redraw()

◆ ReleaseMusic()

◆ SetCurrentSelection()

◆ SetDurationOffsetLeft()

◆ SetDurationOffsetRight()

◆ SetEndMeasure()

◆ SetEndMeasurePos()

◆ SetEndMeasurePosRight()

◆ SetEndSlot()

◆ SetEndStaff()

◆ SetFullDocument()

◆ SetFullMeasureStack()

◆ SetInDocument()

◆ SetInstrumentList()

◆ SetRegion()

◆ SetStartMeasure()

◆ SetStartMeasurePos()

◆ SetStartMeasurePosLeft()

◆ SetStartSlot()

◆ SetStartStaff()