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

	FCDocument (EDOCID id=-1)
	The constructor. More...

EDOCID	GetID () const
	Returns the document ID. More...

bool	IsCurrent ()
	Returns true if the current document is the current document. More...

bool	IsIdentical (const __FCBase *pCompareObject) const override
	Overridden method for comparison of documents. More...

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

bool	GetPathSpec (void *pathspec, EVERSION convertversion)
	Copies the document path to a path spec.

bool	SetToCurrent ()
	Remaps the object to the current document. More...

bool	_SetID (EDOCID docID)
	Directly sets the ID.

bool	SwitchTo (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. More...

bool	SwitchBack (bool saveedits)
	Ends the started edit block and switch back to the previous document. More...

bool	DisplayVisually ()
	Moves the visual focus to the document. More...

bool	Save ()
	Saves the current document at the current document path. More...

bool	Open (FCString pFilePath, bool createwindow, FCString pUndoString)
	Opens a file as a new Finale documnent. The new document will automatically get editing focus. More...

bool	New (FCString *pUndoString)
	Creates an new untitled Finale documnent. The new document will automatically get editing focus. More...

bool	CloseCurrentDocumentWindow ()
	Closes the current document Window. More...

bool	Close ()
	Closes the document. More...

bool	Print (FCPrintSettings *pSettings)
	Prints the document, using the specified printer settings. More...

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

void	SetDirty (bool state)
	Sets the "dirty" flag for the document (that indicates that the document needs to be saved). 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...

Static Public Member Functions
static void	_SetLastUndoString (const FCString *pString, _state_ptr S _NOLUACODE(=nullptr))
	For internal use only. This method should be called whenever a new undo block is started.

static void	GetLastUndoString (FCString *pString, _state_ptr S _NOLUACODE(=nullptr))
	Fetches the last undo string for the edit block.

static void	RemoveLastUndoString (_state_ptr S)
	Clears out the last undo string from the std::map (for use when the session state terminates)

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

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

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

Closes the document.

Returns: True if the document was successfully closed.

◆ CloseCurrentDocumentWindow()

bool FCDocument::CloseCurrentDocumentWindow ( )

Closes the current document Window.

Returns: True if the document was successfully closed.

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

Please note that untitled documents are treated differently between the platforms. On the Mac, an untitled document will result in an empty string. On Windows, an untitled document will result 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 ( FCString * pUndoString )

Creates an new untitled Finale documnent. The new document will automatically get editing focus.

Unsure how and if this work in actually works correcty. Don't use for now.

Parameters

pUndoString [in] The undo string to be used for the document.

Returns: True if the document was successfully created.

◆ Open()

bool FCDocument::Open	(	FCString *	pFilePath,
		bool	createwindow,
		FCString *	pUndoString
	)

Opens a file as a new Finale documnent. The new document will automatically get editing focus.

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.

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

Saves the current document at the current document path.

Lua-supported.

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 )

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

Lua-supported.

Parameters

saveedits True if the edits made in the document should be kept in the edit block. False to cancel the edits.

Returns: True on success.

◆ SwitchTo()

bool FCDocument::SwitchTo	(	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. And object must be supplied.
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.

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ FCDocument()

Member Function Documentation

◆ ClassName()

◆ Close()

◆ CloseCurrentDocumentWindow()

◆ DebugDump()

◆ DisplayVisually()

◆ GetDirty()

◆ GetID()

◆ GetPath()

◆ IsCurrent()

◆ IsIdentical()

◆ New()

◆ Open()

◆ Print()

◆ Save()

◆ SetDirty()

◆ SetToCurrent()

◆ SwitchBack()

◆ SwitchTo()