FCDocument Class Reference

Class for an opened Finale document. An opened Finale document has a 1-based ID and can be displayed in multiple document windows. More...

#include <ff_documents.h>

Inheritance diagram for FCDocument:

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.
	FCDocument (EDOCID id=-1)
	The constructor.
EDOCID	GetID () const
	Returns the document ID.
bool	IsCurrent ()
	Returns true if the current document is the current document.
bool	IsIdentical (const __FCBase *pCompareObject) const override
	Overridden method for comparison of documents.
bool	IsUntitled ()
	Returns true if the document has no file connected to it.
bool	GetPath (FCString *pString)
	Gets the full path of the document in a FCString object.
bool	GetPathSpec (void *pathspec, EVERSION convertversion)
	Copies the document path to a path spec.
bool	SetToCurrent ()
	Remaps the object to the current document.
bool	_SetID (EDOCID docID)
	Directly sets the ID.
bool	SwitchTo (const FCString *pUndoString, bool saveedits, _state_ptr S=nullptr)
	Switch document focus to this document and start a new undo/redo record, without closing the previous one. The document is not displayed visually.
bool	SwitchBack (bool saveedits, _state_ptr S=nullptr)
	Ends the started edit block and switch back to the previous document.
bool	DisplayVisually ()
	Moves the visual focus to the document.
bool	Save (const FCString *pFilePath=nullptr)
	Saves the current document at the current document path or the specified document path.
bool	Open (const FCString *pFilePath, bool createwindow, const FCString *pUndoString, bool saveedits, bool addtorecents, bool hidedialogs, _state_ptr S=nullptr)
	Opens a file as a new Finale document. The new document automatically gets editing focus. This is the equivalent of calling SwitchTo. That means that any call to Open should be balanced with a call to SwitchBack, even if the call to Open fails.
bool	New (const FCString *pUndoString, bool saveedits, _state_ptr S=nullptr)
	Creates an new untitled Finale documnent. The new document automatically gets editing focus. This is the equivalent of calling SwitchTo, which means that any call to New should be balanced with a call to SwitchBack.
bool	CloseCurrentDocumentAndWindow (bool saveedits=true, _state_ptr S=nullptr)
	Closes the current document and any windows it has open. Use this function to close a document if you opened a document window when you called Open.
bool	Close (bool saveedits=true, _state_ptr S=nullptr)
	Closes the document. Use this function to close a document if you did not open a document window when you called Open.
bool	Print (FCPrintSettings *pSettings)
	Prints the document, using the specified printer settings.
bool	GetDirty () const
	Returns the "dirty" flag for document (that indicates that the document needs to be saved).
void	SetDirty (bool state)
	Sets the "dirty" flag for the document (that indicates that the document needs to be saved).
void	DebugDump () override
	Outputs the class data/information for debugging purposes.
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	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.
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
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...
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 an opened Finale document. An opened Finale document has a 1-based ID and can be displayed in multiple document windows.

Use SwitchTo() to switch document context to another document. Make sure to always use SwitchBack() to move the context back to the original document.

When switching to another document, please be aware that much of previously loaded data will not make sense in the context of the new document. Be especially careful while handling fonts and objects with linked data.

Constructor & Destructor Documentation

FCDocument()

FCDocument::FCDocument ( EDOCID id = -1 )

inline

The constructor.

If the id is below 1, the object will be set to the current document.

Lua-supported.

Member Function Documentation

ClassName()

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

Close()

bool FCDocument::Close	(	bool	saveedits = true,
		_state_ptr	S = nullptr )

Closes the document. Use this function to close a document if you did not open a document window when you called Open.

Lua-supported (0.75).

Parameters

saveedits	[in] If true, save any edits that have been applied to the document.
S	[in] State pointer. See comments at SwitchTo. Lua callers omit this parameter.

Returns

True if the document was successfully closed.

CloseCurrentDocumentAndWindow()

bool FCDocument::CloseCurrentDocumentAndWindow	(	bool	saveedits = true,
		_state_ptr	S = nullptr )

Closes the current document and any windows it has open. Use this function to close a document if you opened a document window when you called Open.

Lua-supported (0.75).

Parameters

saveedits	[in] If true, save any edits that have been applied to the document.
S	[in] State pointer. See comments at SwitchTo. Lua callers omit this parameter.

Returns

This is the value returned by Finale. It may be false even when the window was successfully closed, so it probably is not worth checking.

DebugDump()

void FCDocument::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.

DisplayVisually()

bool FCDocument::DisplayVisually ( )

inline

Moves the visual focus to the document.

In versions of Finale for macOS before 27.3, this function always returns false even if it successfully displays the window.

Lua-supported (0.65)

GetDirty()

bool FCDocument::GetDirty ( ) const

inline

Returns the "dirty" flag for document (that indicates that the document needs to be saved).

Lua-supported (also as property).

GetID()

EDOCID FCDocument::GetID ( ) const

inline

Returns the document ID.

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

GetPath()

bool FCDocument::GetPath

(

FCString *

pString

)

Gets the full path of the document in a FCString object.

Remarks

Please note that untitled documents are treated differently between the platforms. On macOS, depending on the Finale version, an untitled document may result in an empty string or the document window name relative to ./. On Windows, an untitled document results in the document window name.

Lua-supported.

IsCurrent()

bool FCDocument::IsCurrent ( )

inline

Returns true if the current document is the current document.

Lua-supported.

IsIdentical()

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

inlineoverridevirtual

Overridden method for comparison of documents.

Reimplemented from __FCBase.

New()

bool FCDocument::New	(	const FCString *	pUndoString,
		bool	saveedits,
		_state_ptr	S = nullptr )

Creates an new untitled Finale documnent. The new document automatically gets editing focus. This is the equivalent of calling SwitchTo, which means that any call to New should be balanced with a call to SwitchBack.

This function is currently untested and may not actually work correctly. Do not use for now.

Parameters

pUndoString	[in] The undo string to be used for the document. NULL to use the last value.
saveedits	[in] True if any current changes should be saved.
S	[in] State pointer. See comments at SwitchTo.

Returns

True if the document was successfully created.

Open()

bool FCDocument::Open	(	const FCString *	pFilePath,
		bool	createwindow,
		const FCString *	pUndoString,
		bool	saveedits,
		bool	addtorecents,
		bool	hidedialogs,
		_state_ptr	S = nullptr )

Opens a file as a new Finale document. The new document automatically gets editing focus. This is the equivalent of calling SwitchTo. That means that any call to Open should be balanced with a call to SwitchBack, even if the call to Open fails.

Lua-supported (0.75).

Parameters

pFilePath	[in] The full path to the file that should be opened.
createwindow	[in] True if a visual document window should be created in the Finale UI.
pUndoString	[in] The undo string to be used for the document. NULL to use the last value.
saveedits	[in] True if any current changes should be saved.
addtorecents	[in] True if this file should be added to the recent files opened list. Only works in Finale 26.1 and higher.
hidedialogs	[in] True if this file should be opened without any popup dialogs. (Useful for batch processing.) Only works in Finale 26.1 and higher.
S	[in] State pointer. See comments at SwitchTo. Lua callers omit this parameter.

Returns

True if the file was successfully opened.

Print()

bool FCDocument::Print

(

FCPrintSettings *

pSettings

)

Prints the document, using the specified printer settings.

Lua-supported.

Parameters

pSettings

Pointer to the printer settings object.

Save()

bool FCDocument::Save

(

const FCString *

pFilePath = nullptr

)

Saves the current document at the current document path or the specified document path.

Warning

If you specify a new file location, the file is moved to that location and may be removed from the previous location. Finale's behavior is not 100% consistent in this regard. It appears that if the new location already exists, it is overwritten but the previous location is preserved. However, if the new location does not already exist, the previous location is removed.

Lua-supported.

Parameters

[in]

pFilePath

[optional] the full path and file name where to save the document. (Not available before 0.76.)

Returns

True if the document was successfully saved to disk.

SetDirty()

void FCDocument::SetDirty ( bool state )

inline

Sets the "dirty" flag for the document (that indicates that the document needs to be saved).

Lua-supported (also as property).

SetToCurrent()

bool FCDocument::SetToCurrent ( )

inline

Remaps the object to the current document.

This method will fail if the object is in an unresolved SwitchTo statement.

SwitchBack()

bool FCDocument::SwitchBack	(	bool	saveedits,
		_state_ptr	S = nullptr )

Ends the started edit block and switch back to the previous document.

Lua-supported.

Parameters

saveedits	[in] True if the edits made in the document should be kept in the edit block. False to cancel the edits.
S	[in] State pointer. See comments at SwitchTo.

Returns

True on success.

SwitchTo()

bool FCDocument::SwitchTo	(	const FCString *	pUndoString,
		bool	saveedits,
		_state_ptr	S = nullptr )

Switch document focus to this document and start a new undo/redo record, without closing the previous one. The document is not displayed visually.

A SwitchTo() call must be combined with a subsequent SwitchBack() call.

Since Undo/Redo stack can't handle edits through multiple documents, it's very important that plug-ins that switch and write to other documents create their own Undo/Redo event for that document. Furthermore, Finale cannot hold two Undo/Redo events open at once, so you must end any current redo event.

The state pointer is used to track the last undo string separately per state value. Lua automatically supplies the Lua state in this parameter, which means the script must omit it. C++ clients can supply a value (any pointer value associated with the state) or accept the NULL default, which means there is no separate state tracking.

Here is a Lua example that modifies all open documents while safely maintaining Finale's Undo states. Note that the saveedits parameter is false on the call to SwitchTo. This discards any previous edits. The current edits get saved on the SwitchBack call.

local docs = finale.FCDocuments()
docs:LoadAll()
for doc in each(docs) do
    doc:SwitchTo("Multiple File Edit", false) -- Lua clients omit the state pointer
    local region = finale.FCMusicRegion()
    region:SetFullDocument()
    for entry in eachentrysaved(region) do
        entry.ManualPosition = entry.ManualPosition - 144
    end
    region:Redraw()
    doc:SwitchBack(true)
end

Lua-supported.

Parameters

pUndoString	The pointer to the Undo string. If this value is NULL, the last Undo string value is used.
saveedits	True if the edits made in the current document should be kept in the edit block. False to cancel the edits.
S	State pointer. (See comment above.) Lua scripts omit this parameter.

Returns

True on success.