FCUI Class Reference

Standard class for basic user interface functionality. More...

#include <ff_ui.h>

Inheritance diagram for FCUI:

Public Types
enum	ALERT_RETURNS {   OKRETURN = 0 , CANCELRETURN , YESRETURN , NORETURN ,   UNKNOWNRETURN }
	The return values used by the alert box methods. More...
enum	MENU_COMMANDS {   MENUCMD_NULL = 0 , MENUCMD_NOTESPACING , MENUCMD_BEATSPACING , MENUCMD_TIMESIGSPACING ,   MENUCMD_RESPELLNOTES , MENUCMD_MOVETOPREVSYSTEM , MENUCMD_MOVETONEXTSYSTEM , MENUCMD_LOCKSYSTEMS ,   MENUCMD_UNLOCKSYSTEMS , MENUCMD_CHECKTIES , MENUCMD_FILLWITHRESTS , MENUCMD_REMOVEMANUALSLURADJUSTMENTS ,   MENUCMD_RESETALLGROUPSANDBRACKETS , MENUCMD_STEMDIRECTIONUP , MENUCMD_STEMDIRECTIONDOWN , MENUCMD_STEMDIRECTIONDEFAULT ,   MENUCMD_CLEARALLITEMS , MENUCMD_EHSPELLING_DEFAULT , MENUCMD_EHSPELLING_FAVORSHARPS , MENUCMD_EHSPELLING_FAVORFLATS ,   MENUCMD_EHSPELLING_USESPELLINGTABLES , MENUCMD_REBEAM , MENUCMD_VIEWSCROLLVIEW , MENUCMD_VIEWPAGEVIEW ,   MENUCMD_VIEWSTUDIOVIEW , MENUCMD_REDRAWSCREEN , MENUCMD_EDITSCORE , MENUCMD_STAFFSETALLSTAVES ,   MENUCMD_STAFFSET1 , MENUCMD_STAFFSET2 , MENUCMD_STAFFSET3 , MENUCMD_STAFFSET4 ,   MENUCMD_STAFFSET5 , MENUCMD_STAFFSET6 , MENUCMD_STAFFSET7 , MENUCMD_STAFFSET8 ,   MENUCMD_RETRANSCRIBE , MENUCMD_CREATEMMRESTS , MENUCMD_BREAKMMRESTS , MENUCMD_SELECTIONTOOL ,   MENUCMD_STAFFTOOL , MENUCMD_MEASURETOOL , MENUCMD_KEYSIGTOOL , MENUCMD_TIMESIGTOOL ,   MENUCMD_CLEFTOOL , MENUCMD_REPEATTOOL , MENUCMD_ARTICULATIONTOOL , MENUCMD_CHORDTOOL ,   MENUCMD_EXPRESSIONTOOL , MENUCMD_GRAPHICSTOOL , MENUCMD_HANDGRABBERTOOL , MENUCMD_HYPERSCRIBETOOL ,   MENUCMD_LYRICSTOOL , MENUCMD_MIDITOOL , MENUCMD_MIRRORTOOL , MENUCMD_NOTEMOVERTOOL ,   MENUCMD_OSSIATOOL , MENUCMD_PAGELAYOUTTOOL , MENUCMD_RESIZETOOL , MENUCMD_SPEEDYENTRYTOOL ,   MENUCMD_TEMPOTOOL , MENUCMD_TEXTTOOL , MENUCMD_TUPLETTOOL , MENUCMD_ZOOMTOOL }
	The menu commands available to the FCUI::MenuCommand() 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
	FCUI (EWND parent)
	The constructor.
const char *	ClassName () const override
	Returns the name of the class, for diagnostic purposes. This method MUST be overwritten in each child class.
void	AlertErrorCString (const char *pszMessage, const char *pszTitle=NULL)
	Displays a error message box / alert, with an OK button. C string version.
void	AlertErrorUTF8 (const char *pszMessage, const char *pszTitle=NULL)
	Displays a error message box / alert, with an OK button. UTF8 string version.
void	AlertError (FCString *pMessage, FCString *pTitle=NULL)
	Displays a error message box / alert, with an OK button. FCString version.
ALERT_RETURNS	AlertYesNoCString (const char *pszMessage, const char *pszTitle=NULL)
	Displays a error message box / alert, with Yes+No buttons. C string version.
ALERT_RETURNS	AlertYesNoUTF8 (const char *pszMessage, const char *pszTitle=NULL)
	Displays a error message box / alert, with Yes+No buttons. UTF8 version.
ALERT_RETURNS	AlertYesNo (FCString *pMessage, FCString *pTitle=NULL)
	Displays a error message box / alert, with Yes+No buttons. FCString version.
FCUI::ALERT_RETURNS	AlertYesNoCancelUTF8 (const char *pszMessage, const char *pszTitle)
	Displays a error message box / alert, with Yes+No+Cancel buttons. UTF8 version.
ALERT_RETURNS	AlertYesNoCancel (FCString *pMessage, FCString *pTitle=NULL)
	Displays a error message box / alert, with Yes+No+Cancel buttons. FCString version.
ALERT_RETURNS	AlertOkCancelCString (const char *pszMessage, const char *pszTitle=NULL)
	Displays a error message box / alert, with OK+Cancel buttons. C string version.
ALERT_RETURNS	AlertOkCancelUTF8 (const char *pszMessage, const char *pszTitle=NULL)
	Displays a error message box / alert, with OK+Cancel buttons. UTF8 version.
ALERT_RETURNS	AlertOkCancel (FCString *pMessage, FCString *pTitle=NULL)
	Displays a error message box / alert, with Ok+Cancel buttons. FCString version.
void	AlertNeutralCString (const char *pszMessage, const char *pszTitle=NULL)
	Displays a standard message box / alert, with an OK button. C string verison.
void	AlertNeutralUTF8 (const char *pszMessage, const char *pszTitle=NULL)
	Displays a standard message box / alert, with an OK button. UTF8 verison.
void	AlertNeutral (FCString *pMessage, FCString *pTitle=NULL)
	Displays a standard message box / alert, with an OK button. FCString version.
void	AlertInfoCString (const char *pszMessage, const char *pszTitle=NULL)
	Displays an information message box / alert, with an OK button. C string version.
void	AlertInfoUTF8 (const char *pszMessage, const char *pszTitle=NULL)
	Displays an information message box / alert, with an OK button. UTF8 version.
void	AlertInfo (FCString *pMessage, FCString *pTitle=NULL)
	Displays an information message box / alert, with an OK button. FCString version.
bool	MenuCommand (MENU_COMMANDS menucmd)
	Executes a supported menu command from Finale's menu.
EMENUID	GetOSMenuCommandFromItemText (const char *pszTopMenu, const char *pszItemText)
	Returns the OS-dependent menu command for a specific item in one of Finale's main menus.
bool	ExecuteOSMenuCommand (EMENUID osmenucmd, bool usemacfinaleapi=false) const
	Executes an OS menu command returned by GetOSMenuCommandFromItemText.
bool	MenuPositionCommand (int mainmenuidx, int dropdownidx, int submenuidx)
	Executes a menu command from a specific location in Finale's menu. Use this method with care!
void	RedrawDocument ()
	Visually redraws the current document.
bool	IsPageView () const
	Returns true if the current view for the current document is Page View.
bool	IsPartView () const
	Returns true if the current view is in a part (=not in the score).
bool	IsLayerVisible (twobyte layernum) const
	Returns true for any valid layer number unless "Show Active Layer Only" is checked. Then it returns true for the active layer and false for any other layer.
void	GetDecimalSeparator (FCString *pString)
	Fills a FCString with the decimal separator used for the current user's locale.
void	GetUserLocaleName (FCString *pString)
	Fills a FCString with the locale name used for the current user's locale.
void	SetUseIsFontAvailableAPI (bool state)
	Sets if Finale's own API for checking font availability should be used for IsFontAvailable().
bool	GetUseIsFontAvailableAPI () const
	Returns if Finale's own API for checking font availability should be used for IsFontAvailable().
bool	IsOnWindows () const
	Returns true if the user runs on Windows.
bool	IsOnMac () const
	Returns true if the user runs on the Mac.
bool	TextToClipboard (const char *pszText)
	Copies text to the operating system's clipboard.
bool	TextToClipboardUTF8 (const char *pszText)
	Copies text to the operating system's clipboard from an UTF8 source.
twobyte	GetCurrentPage () const
	Returns the currently displayed page number in Page View.
twobyte	GetCurrentMeasure () const
	Returns the currently displayed measure number in Scroll View.
twobyte	GetZoomLevel () const
	Returns the current zoom level.
int	GetMaxLayers () const
	Returns the maximum number of layers that Finale supports.
EWND	GetDocumentWindow ()
	Return the window handle to the current document window.
bool	ActivateDocumentWindow ()
	Brings the current document window to user focus.
EWND	GetActiveWindow ()
	Returns the currently active window.
bool	ActivateWindow (EWND hwnd)
	Activates a specific window.
FXWND	GetParentWindow ()
	Returns the window handle to the main window (that was passed to the constructor.)
void	MoveToMeasure (int measure, int staffno=0)
	Moves the view to the indicated 1-based measure.
void	Beep ()
	Gives a beep from the speaker.
int	GetScreenWidth () const
	Returns the width in pixels of the primary screen.
int	GetScreenHeight () const
	Returns the height in pixels of the primary screen.
CMPER	DisplayTextExpressionDialog (CMPER cmperinit=0)
	Displays the expression selection dialog.
std::pair< CMPER, bool >	DisplayExpressionDialog (CMPER cmperinit=0, bool isshape=false)
	Displays the expression selection dialog.
CMPER	DisplayArticulationDialog (CMPER cmperinit=0)
	Displays the articulation definition selection dialog.
CMPER	DisplayShapeDialog (CMPER cmperinit=0)
	Displays the shape definition selection dialog box.
eUniChar32	DisplaySymbolDialog (FCFontInfo *pFontInfo, eUniChar32 symbolinit=0)
	Displays the symbol selection dialog.
bool	DisplayListenToMidiDialog (FCListenToMidiResult *result)
	Displays the ListenToMidi dialog.
bool	IsFontAvailable (FCString *pFontName)
	Returns true if the font name exists on the running system.
bool	DisplayWebURL (FCString *pURLString)
	Displays an URL in an external web browser.
bool	DisplayShellFolder (FCString *pFolderString)
	Opens the file or folder in the operating system's workspace.
void	StartPerformanceTimer ()
	Starts the high-resolution timer.
void	StopPerformanceTimer ()
	Stops the high-resolution timer.
double	ReturnPerformanceTiming ()
	Calculates the time difference after a start+stop of the hi-resolution timer.
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.
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.

Static Public Member Functions
static double	GetHiResTimer ()
	Returns a high-resolution timer value, mainly for use with internal profilers.
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.

Additional Inherited Members
Protected Member Functions inherited from __FCBase
	__FCBase ()
	The constructor.

Detailed Description

Standard class for basic user interface functionality.

See comments about best practice for instantiating this class at FCUI::FCUI.

Member Enumeration Documentation

ALERT_RETURNS

enum FCUI::ALERT_RETURNS

The return values used by the alert box methods.

Lua-supported.

Enumerator
OKRETURN	'OK' button was pressed
CANCELRETURN	'Cancel' button was pressed
YESRETURN	'Yes' button was pressed
NORETURN	'No' button was pressed
UNKNOWNRETURN	Unknown alert box behaviour.

MENU_COMMANDS

enum FCUI::MENU_COMMANDS

The menu commands available to the FCUI::MenuCommand() method.

Lua-supported.

Enumerator
MENUCMD_NULL	No menu command
MENUCMD_NOTESPACING	Apply Note Spacing. A region selection must exist. Please note that Finale might display a warning alert to the user if the region selection isn't using the full-measure boundaries.
MENUCMD_BEATSPACING	Apply Beat Spacing. A region selection must exist. Please note that Finale might display a warning alert to the user if the region selection isn't using the full-measure boundaries.
MENUCMD_TIMESIGSPACING	Apply Time Signature Spacing. A region selection must exist. Please note that Finale might display a warning alert to the user if the region selection isn't using the full-measure boundaries.
MENUCMD_RESPELLNOTES	"Respell Notes" in the "Utilities" menu. A selected measure region is required.
MENUCMD_MOVETOPREVSYSTEM	"Move to Previous System" in the "Utilities" menu. A selected measure region in Page View is required.
MENUCMD_MOVETONEXTSYSTEM	"Move to Next System" in the "Utilities" menu. A selected measure region in Page View is required.
MENUCMD_LOCKSYSTEMS	"Lock Systems" in the "Utilities" menu. A selected measure region in Page View is required.
MENUCMD_UNLOCKSYSTEMS	"Unlock Systems" in the "Utilities" menu. A selected measure region in Page View is required.
MENUCMD_CHECKTIES	"Check Ties" in the "Utilities" menu. A selected measure region is required.
MENUCMD_FILLWITHRESTS	"Fill with Rests" in the "Utilities" menu. A selected measure region is required.
MENUCMD_REMOVEMANUALSLURADJUSTMENTS	"Remove Manual Slur Adjustments" in the "Utilities" menu. A selected measure region is required.
MENUCMD_RESETALLGROUPSANDBRACKETS	"Reset all Groups and Brackets" in the "Utilities" menu. A selected measure region is required.
MENUCMD_STEMDIRECTIONUP	"Stem Direction - Up" in the "Utilities" menu. A selected measure region is required.
MENUCMD_STEMDIRECTIONDOWN	"Stem Direction - Down" in the "Utilities" menu. A selected measure region is required.
MENUCMD_STEMDIRECTIONDEFAULT	"Stem Direction - Default" in the "Utilities" menu. A selected measure region is required.
MENUCMD_CLEARALLITEMS	"Clear all Items" in the "Edit" menu. A selected measure region is required.
MENUCMD_EHSPELLING_DEFAULT	Set the "Enharmonic Spelling" setting to "Default" in the "Edit" menu (or "Finale" menu on the Mac). This setting affects the MENUCMD_RESPELLNOTES menu command.
MENUCMD_EHSPELLING_FAVORSHARPS	Set the "Enharmonic Spelling" setting to "Favor Sharps" in the "Edit" menu (or "Finale" menu on the Mac). This setting affects the MENUCMD_RESPELLNOTES menu command.
MENUCMD_EHSPELLING_FAVORFLATS	Set the "Enharmonic Spelling" setting to "Favor Flats" in the "Edit" menu (or "Finale" menu on the Mac). This setting affects the MENUCMD_RESPELLNOTES menu command.
MENUCMD_EHSPELLING_USESPELLINGTABLES	Set the "Enharmonic Spelling" setting to "Use Spelling Tables" in the "Edit" menu (or "Finale" menu on the Mac). This setting affects the MENUCMD_RESPELLNOTES menu command.
MENUCMD_REBEAM	Rebeam the selected region. More control is available through the FCMusicRegion::RebeamMusic() method.
MENUCMD_VIEWSCROLLVIEW	Switch to Scroll View.
MENUCMD_VIEWPAGEVIEW	Switch to Page View.
MENUCMD_VIEWSTUDIOVIEW	Switch to Studio View.
MENUCMD_REDRAWSCREEN	The Redraw Screen command from the View menu. Normally, the RedrawDocument should be used for refreshing the current document, but this menu command will behave identically to the Finale user interface.
MENUCMD_EDITSCORE	Switch to Score editing mode.
MENUCMD_STAFFSETALLSTAVES	View the full staff set
MENUCMD_STAFFSET1	View Staff Set 1
MENUCMD_STAFFSET2	View Staff Set 2
MENUCMD_STAFFSET3	View Staff Set 3
MENUCMD_STAFFSET4	View Staff Set 4
MENUCMD_STAFFSET5	View Staff Set 5
MENUCMD_STAFFSET6	View Staff Set 6
MENUCMD_STAFFSET7	View Staff Set 7
MENUCMD_STAFFSET8	View Staff Set 8
MENUCMD_RETRANSCRIBE	Retranscribe (in the MIDI/Audio menu). A region selection must exist.
MENUCMD_CREATEMMRESTS	Create multi-measure rest(s) (command available in the Edit/Multimeasure Rests menu). A region selection must exist.
MENUCMD_BREAKMMRESTS	Break multi-measure rest(s) (command available in the Edit/Multimeasure Rests menu). A region selection must exist.
MENUCMD_SELECTIONTOOL	Select the Selection Tool.
MENUCMD_STAFFTOOL	Select the Staff Tool.
MENUCMD_MEASURETOOL	Select the Measure Tool.
MENUCMD_KEYSIGTOOL	Select the Key Signature Tool.
MENUCMD_TIMESIGTOOL	Select the Time Signature Tool.
MENUCMD_CLEFTOOL	Select the Clef Tool.
MENUCMD_REPEATTOOL	Select the Repeat Tool.
MENUCMD_ARTICULATIONTOOL	Select the Articulation Tool.
MENUCMD_CHORDTOOL	Select the Chord Tool.
MENUCMD_EXPRESSIONTOOL	Select the Expression Tool.
MENUCMD_GRAPHICSTOOL	Select the Graphics Tool.
MENUCMD_HANDGRABBERTOOL	Select the Hand Grabber Tool.
MENUCMD_HYPERSCRIBETOOL	Select the HyperScribe Tool.
MENUCMD_LYRICSTOOL	Select the Lyrics Tool.
MENUCMD_MIDITOOL	Select the MIDI Tool.
MENUCMD_MIRRORTOOL	Select the Mirror Tool. Not available on Finale 25 and later.
MENUCMD_NOTEMOVERTOOL	Select the Note Mover Tool.
MENUCMD_OSSIATOOL	Select the Ossia Tool.
MENUCMD_PAGELAYOUTTOOL	Select the Page Layout Tool.
MENUCMD_RESIZETOOL	Select the Resize Tool.
MENUCMD_SPEEDYENTRYTOOL	Select the Speedy Entry Tool.
MENUCMD_TEMPOTOOL	Select the Tempo Tool. Not available on Finale 25 and later.
MENUCMD_TEXTTOOL	Select the Text Tool.
MENUCMD_TUPLETTOOL	Select the Tuplet Tool.
MENUCMD_ZOOMTOOL	Select the Zoom Tool.

Constructor & Destructor Documentation

FCUI()

FCUI::FCUI ( EWND parent )

inline

The constructor.

If you are using an instance of FCUI to pop up built-in dialogs from another dialog, you should create an instance using __FCUserWindow::CreateChildUI and then call the dialog methods from that instance. This is particularly important with Windows Finale when launching build-in dialogs from a modeless dialog window. But it is best practice in any case.

Similarly, if you are opening standard file dialog from another dialog, pass an FCUI instance created with __FCUserWindow::CreateChildUI from the parent dialog to the constructors of standard file dialogs (for example, FCFileSaveAsDialog).

Lua scripts cannot construct instances of FCUI directly. There is a global instance in finenv.UI() which is a child of the main Finale frame window. But (as noted) you should use an instance created with __FCUserWindow::CreateChildUI to open built-in dialogs off a dialog box you have created. Other methods not related to built-in dialogs can safely use the global instance. Also, you can use the global instance to open built-in dialogs directly, if they are not opening from another dialog box.

Methods that query Finale's menu items must use the global instance, because that is the instance constructed from Finale's frame window that contains the main menu.

Parameters

parent

The parent Finale window, as passed to FinaleExtensionInvoke, or the window handle of a running __FCUserWindow.

Member Function Documentation

ActivateDocumentWindow()

bool FCUI::ActivateDocumentWindow

(

)

Brings the current document window to user focus.

Lua-supported.

Returns

True on success.

AlertError()

void FCUI::AlertError	(	FCString *	pMessage,
		FCString *	pTitle = NULL )

Displays a error message box / alert, with an OK button. FCString version.

Parameters

pMessage	Message box message.
pTitle	Optional title for the message box (Windows only).

AlertErrorCString()

void FCUI::AlertErrorCString	(	const char *	pszMessage,
		const char *	pszTitle = NULL )

Displays a error message box / alert, with an OK button. C string version.

Parameters

pszMessage	Message box message.
pszTitle	Optional title for the message box (Windows only).

AlertErrorUTF8()

void FCUI::AlertErrorUTF8	(	const char *	pszMessage,
		const char *	pszTitle = NULL )

Displays a error message box / alert, with an OK button. UTF8 string version.

Lua-supported (as AlertError).

Parameters

pszMessage	Message box message.
pszTitle	Optional title for the message box (Windows only).

AlertInfo()

void FCUI::AlertInfo	(	FCString *	pMessage,
		FCString *	pTitle = NULL )

Displays an information message box / alert, with an OK button. FCString version.

Parameters

[in]	pMessage	Message box message.
[in]	pTitle	Optional title for the message box (Windows only).

AlertInfoCString()

void FCUI::AlertInfoCString	(	const char *	pszMessage,
		const char *	pszTitle = NULL )

Displays an information message box / alert, with an OK button. C string version.

Parameters

pszMessage	Message box message.
pszTitle	Optional title for the message box (Windows only).

AlertInfoUTF8()

void FCUI::AlertInfoUTF8	(	const char *	pszMessage,
		const char *	pszTitle = NULL )

Displays an information message box / alert, with an OK button. UTF8 version.

Lua-supported (as AlertInfo).

Parameters

pszMessage	Message box message.
pszTitle	Optional title for the message box (Windows only).

AlertNeutral()

void FCUI::AlertNeutral	(	FCString *	pMessage,
		FCString *	pTitle = NULL )

Displays a standard message box / alert, with an OK button. FCString version.

Parameters

[in]	pMessage	Message box message.
[in]	pTitle	Optional title for the message box (Windows only).

AlertNeutralCString()

void FCUI::AlertNeutralCString	(	const char *	pszMessage,
		const char *	pszTitle = NULL )

Displays a standard message box / alert, with an OK button. C string verison.

Parameters

pszMessage	Message box message.
pszTitle	Optional title for the message box (Windows only).

AlertNeutralUTF8()

void FCUI::AlertNeutralUTF8	(	const char *	pszMessage,
		const char *	pszTitle = NULL )

Displays a standard message box / alert, with an OK button. UTF8 verison.

Lua-supported (as AlertNeutral).

Parameters

pszMessage	Message box message.
pszTitle	Optional title for the message box (Windows only).

AlertOkCancel()

FCUI::ALERT_RETURNS FCUI::AlertOkCancel	(	FCString *	pMessage,
		FCString *	pTitle = NULL )

Displays a error message box / alert, with Ok+Cancel buttons. FCString version.

Parameters

pMessage	Message box message.
pTitle	Optional title for the message box (Windows only).

Returns

OKRETURN or CANELRETURN.

AlertOkCancelCString()

FCUI::ALERT_RETURNS FCUI::AlertOkCancelCString	(	const char *	pszMessage,
		const char *	pszTitle = NULL )

Displays a error message box / alert, with OK+Cancel buttons. C string version.

Parameters

pszMessage	Message box message.
pszTitle	Optional title for the message box (Windows only).

Returns

OKRETURN or CANCELRETURN.

AlertOkCancelUTF8()

FCUI::ALERT_RETURNS FCUI::AlertOkCancelUTF8	(	const char *	pszMessage,
		const char *	pszTitle = NULL )

Displays a error message box / alert, with OK+Cancel buttons. UTF8 version.

Lua-support (as AlertOkCancel)

Parameters

pszMessage	Message box message.
pszTitle	Optional title for the message box (Windows only).

Returns

OKRETURN or CANCELRETURN.

AlertYesNo()

FCUI::ALERT_RETURNS FCUI::AlertYesNo	(	FCString *	pMessage,
		FCString *	pTitle = NULL )

Displays a error message box / alert, with Yes+No buttons. FCString version.

Parameters

pMessage	Message box message.
pTitle	Optional title for the message box (Windows only).

Returns

YESRETURN or NORETURN.

AlertYesNoCancel()

FCUI::ALERT_RETURNS FCUI::AlertYesNoCancel	(	FCString *	pMessage,
		FCString *	pTitle = NULL )

Displays a error message box / alert, with Yes+No+Cancel buttons. FCString version.

Parameters

pMessage	Message box message.
pTitle	Optional title for the message box (Windows only).

Returns

YESRETURN, NORETURN or CANCELRETURN.

AlertYesNoCancelUTF8()

FCUI::ALERT_RETURNS FCUI::AlertYesNoCancelUTF8	(	const char *	pszMessage,
		const char *	pszTitle )

Displays a error message box / alert, with Yes+No+Cancel buttons. UTF8 version.

Lua-supported (as AlertYesNoCancel).

Parameters

pszMessage	Message box message.
pszTitle	Optional title for the message box (Windows only).

Returns

YESRETURN, NORETURN or CANCELRETURN.

AlertYesNoCString()

FCUI::ALERT_RETURNS FCUI::AlertYesNoCString	(	const char *	pszMessage,
		const char *	pszTitle = NULL )

Displays a error message box / alert, with Yes+No buttons. C string version.

Parameters

pszMessage	Message box message.
pszTitle	Optional title for the message box (Windows only).

Returns

YESRETURN or NORETURN.

AlertYesNoUTF8()

FCUI::ALERT_RETURNS FCUI::AlertYesNoUTF8	(	const char *	pszMessage,
		const char *	pszTitle = NULL )

Displays a error message box / alert, with Yes+No buttons. UTF8 version.

Lua-supported (as AlertYesNo).

Parameters

pszMessage	Message box message.
pszTitle	Optional title for the message box (Windows only).

Returns

YESRETURN or NORETURN.

Beep()

void FCUI::Beep

(

)

Gives a beep from the speaker.

Lua-supported.

ClassName()

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

DebugDump()

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

DisplayArticulationDialog()

CMPER FCUI::DisplayArticulationDialog

(

CMPER

cmperinit = 0

)

Displays the articulation definition selection dialog.

When the dialog box is closed, the previously active window automatically becomes active again.

Lua-supported.

Returns

0 if the cancel button was pressed. Otherwise, the selected articulation definition ID.

DisplayExpressionDialog()

std::pair< CMPER, bool > FCUI::DisplayExpressionDialog	(	CMPER	cmperinit = 0,
		bool	isshape = false )

Displays the expression selection dialog.

When the dialog box is closed, the previously active window automatically becomes active again.

Lua-supported (0.66).

Parameters

cmperinit	The initial expression ID to select. Pass 0 for Finale's default selection.
isshape	Pass true if the initial expression ID is a shape expression.

Returns

On Lua, this returns two values:

• The first value returned is the ID of the selected expression definition or 0 if the cancel button was pressed.
• The second value returned is a boolean indicating if the value is a shape expression.

On C++, the two values are returned as a std::pair.

DisplayListenToMidiDialog()

bool FCUI::DisplayListenToMidiDialog

(

FCListenToMidiResult *

result

)

Displays the ListenToMidi dialog.

When the dialog box is closed, the previously active window automatically becomes active again.

Lua-supported (0.68).

Returns

true if a MIDI event was detected, false if the user canceled the dialog box.

DisplayShapeDialog()

CMPER FCUI::DisplayShapeDialog

(

CMPER

cmperinit = 0

)

Displays the shape definition selection dialog box.

When the dialog box is closed, the previously active window automatically becomes active again.

Lua-supported.

Returns

0 if the cancel button was pressed. Otherwise, the selected shape definition ID.

DisplayShellFolder()

bool FCUI::DisplayShellFolder

(

FCString *

pFolderString

)

Opens the file or folder in the operating system's workspace.

Lua-supported.

Parameters

pFolderString

The pointer to the FCString object containing the full folder path.

Returns

true if successful.

DisplaySymbolDialog()

eUniChar32 FCUI::DisplaySymbolDialog	(	FCFontInfo *	pFontInfo,
		eUniChar32	symbolinit = 0 )

Displays the symbol selection dialog.

When the dialog box is closed, the previously active window automatically becomes active again.

Lua-supported.

Returns

0 if the cancel button was pressed. Otherwise, the selected character number.

DisplayTextExpressionDialog()

CMPER FCUI::DisplayTextExpressionDialog

(

CMPER

cmperinit = 0

)

Displays the expression selection dialog.

When the dialog box is closed, the previously active window automatically becomes active again.

Despite the name of the function, the dialog box allows selection of both text and shape expressions. However, there is no way to determine if the returned id was for a text or shape expression.

Deprecated

As of v0.66 this function is deprecated. Use DisplayExpressionDialog instead.

Lua-supported.

Returns

0 if the cancel button was pressed. Otherwise, the selected text expression definition ID.

DisplayWebURL()

bool FCUI::DisplayWebURL

(

FCString *

pURLString

)

Displays an URL in an external web browser.

Lua-supported.

ExecuteOSMenuCommand()

bool FCUI::ExecuteOSMenuCommand	(	EMENUID	osmenucmd,
		bool	usemacfinaleapi = false ) const

Executes an OS menu command returned by GetOSMenuCommandFromItemText.

An OS menu command is a fixed numeric value that selects a specific menu option. It does not change from version to version of Finale, and it does not vary according to locale or Language. However, please note that Windows and macOS use different menu codes. Your program can interrogate IsOnWindows or IsOnMac to determine which menu code to use.

Warning

On macOS, some menu items may only work if the Finale document window is in focus.

Lua-supported (0.58).

Parameters

[in]	osmenucmd	The value returned by GetOSMenuCommandFromItemText for the menu item.\
[in]	usemacfinaleapi	On macOS, some menu commands do not work with the API that the Finale PDK provides to plugins. Therefore by default, the PDK Framework skips the Finale API and uses the macOS API. You can override that behavior with this optional parameter. It has no effect on Windows, which always uses the Finale API.

Returns

true on success, otherwise false.

GetCurrentMeasure()

twobyte FCUI::GetCurrentMeasure

(

)

const

Returns the currently displayed measure number in Scroll View.

Lua-supported.

Returns

0 if it's Page View. The currently displayed measure number in Scroll View.

GetCurrentPage()

twobyte FCUI::GetCurrentPage

(

)

const

Returns the currently displayed page number in Page View.

Lua-supported.

Returns

The currently displayed page number in Page View. 0 if not in Page View.

GetDecimalSeparator()

void FCUI::GetDecimalSeparator

(

FCString *

pString

)

Fills a FCString with the decimal separator used for the current user's locale.

Typically, this will be '.' (American style) or ',' (European style).

Lua-supported.

Parameters

[out]

pString

The FCString object that should contain the decimal separator.

GetDocumentWindow()

EWND FCUI::GetDocumentWindow

(

)

Return the window handle to the current document window.

Returns

The handle to the current document window. 0 on error.

GetHiResTimer()

double FCUI::GetHiResTimer ( )

static

Returns a high-resolution timer value, mainly for use with internal profilers.

This is static method that should be called without any class instance.

Lua-supported.

GetMaxLayers()

int FCUI::GetMaxLayers

(

)

const

Returns the maximum number of layers that Finale supports.

If the maximum number of layers is changed in future Finale releases, this method will give the accurate number. It's highly recommended that this return value is used, rather than hard-coding to a fixed number of layers.

Lua-supported.

GetOSMenuCommandFromItemText()

EMENUID FCUI::GetOSMenuCommandFromItemText	(	const char *	pszTopMenu,
		const char *	pszItemText )

Returns the OS-dependent menu command for a specific item in one of Finale's main menus.

Warning

Because menu item text differs between languages and sometimes even between Finale versions and platforms, it is recommended to use this function only as part of code development. Hardcode the return value from this function in your source code and then pass that hardcoded value to ExecuteOSMenuCommand in the production version of your script or program. An exception to this is plug-ins. Because each system has a different set of plug-ins installed, there is no guarantee that a plug-in's menu command will be the same across systems and version.

This function is dependent on the language in which Finale is running. Pass the menu item text for the currently running Finale, whichever language it happens to be. The strings should be encoded utf-8. For Lua scripts, the script file itself may be encoded utf-8 if it contains non-ASCII characters.

Except for plug-ins, OS menu command values remain constant from version to version of Finale, and they remain the same regardless of the language in which Finale is running. But they are different on macOS and Windows. If your code supports both operating systems, hardcode the value returned by this function on each platform and then use IsOnWindows or IsOnMac to determine which value to pass to ExecuteOSMenuCommand.

For macOS, only Finale 2012 and later versions are supported.

On Windows, menu hotkeys are ignored. Send the string the way it looks on screen. This allows the same text to work on either operating system.

You only need to supply enough characters to uniquely identify the menu item. For example, if the menu item is "Open..." you only need to pass in "Open". Or if the top menu is "MIDI/Audio" you only need to pass in "MIDI". A match occurs when the first item is found whose text starts with the input string.

Lua-supported (0.58).

Parameters

[in]	pszTopMenu	The utf-8 encoded text of the top menu item to search in the language Finale is currently running. For English this would be, e.g., "File", "Edit", "Utilities", etc.
[in]	pszItemText	The utf-8 encoded text of the item to find in the language Finale is currently running. Any submenus under the top menu item are searched as well.

Returns

The OS-dependent menu command value. If the menu item is not found, or if it does not have an OS menu command, the function returns -1.

GetParentWindow()

FXWND FCUI::GetParentWindow ( )

inline

Returns the window handle to the main window (that was passed to the constructor.)

Returns

The handle to the main Finale window.

GetScreenHeight()

int FCUI::GetScreenHeight

(

)

const

Returns the height in pixels of the primary screen.

Lua-supported.

GetScreenWidth()

int FCUI::GetScreenWidth

(

)

const

Returns the width in pixels of the primary screen.

Lua-supported.

GetUseIsFontAvailableAPI()

bool FCUI::GetUseIsFontAvailableAPI ( ) const

inline

Returns if Finale's own API for checking font availability should be used for IsFontAvailable().

If set, the Finale API will only be used on Finale 25 and above. On earlier Finale versions, the PDK Framework's own implementation will always be used.

Lua-supported (also as property).

Returns

True if Finale's own API should be used (on Finale 25 and above). False if the PDK Framework's implementation should be used.

GetUserLocaleName()

void FCUI::GetUserLocaleName

(

FCString *

pString

)

Fills a FCString with the locale name used for the current user's locale.

Lua-supported (0.64).

Parameters

[out]

pString

The FCString object that should contain the locale name.

GetZoomLevel()

twobyte FCUI::GetZoomLevel

(

)

const

Returns the current zoom level.

Lua-supported.

IsFontAvailable()

bool FCUI::IsFontAvailable

(

FCString *

pFontName

)

Returns true if the font name exists on the running system.

An empty font name will return false.

Lua-supported.

IsLayerVisible()

bool FCUI::IsLayerVisible ( twobyte layernum ) const

inline

Returns true for any valid layer number unless "Show Active Layer Only" is checked. Then it returns true for the active layer and false for any other layer.

Lua-supported (0.63).

Parameters

layernum

The 1-based layer number.

IsOnMac()

bool FCUI::IsOnMac ( ) const

inline

Returns true if the user runs on the Mac.

Lua-supported.

IsOnWindows()

bool FCUI::IsOnWindows ( ) const

inline

Returns true if the user runs on Windows.

Lua-supported.

IsPageView()

bool FCUI::IsPageView

(

)

const

Returns true if the current view for the current document is Page View.

Lua-supported.

IsPartView()

bool FCUI::IsPartView ( ) const

inline

Returns true if the current view is in a part (=not in the score).

Lua-supported.

MenuCommand()

bool FCUI::MenuCommand

(

FCUI::MENU_COMMANDS

menucmd

)

Executes a supported menu command from Finale's menu.

Lua-supported.

Parameters

menucmd

The menu command to execute. Any of the MENUCMD_ constants.

Returns

True on success.

MenuPositionCommand()

bool FCUI::MenuPositionCommand	(	int	mainmenuidx,
		int	dropdownidx,
		int	submenuidx )

Executes a menu command from a specific location in Finale's menu. Use this method with care!

NOTE! If possible, use MenuCommand or ExecuteOSMenuCommand instead of this method. Be aware that menu item locations may differ between Finale versions and even between operating systems.

On macOS, some menu items will only work if the Finale document window is in focus. Also, only macOS versions Finale 2012 and later are supported.

Deprecated

This method is deprecated in 0.58 and higher versions. Use GetOSMenuCommandFromItemText and ExecuteOSMenuCommand instead.

Lua-supported (deprecated 0.58).

Parameters

[in]	mainmenuidx	The 0-based left-right index of the location for the menu item within the main Finale menu. Index 0 is the "File" menu in Finale. On the Mac, there's also the special value 100, which indicates the "Finale" menu to the left of the "File" menu.
[in]	dropdownidx	The 0-based index within a dropdown menu. Separator lines does not count as a separate item.
[in]	submenuidx	The 0-based index in a submenu to the dropdown menu. This is only used if the dropdown leads to a submenu. If the item is not located in a submenu, this must be -1.

Returns

True on success.

MoveToMeasure()

void FCUI::MoveToMeasure	(	int	measure,
		int	staffno = 0 )

Moves the view to the indicated 1-based measure.

Finale will only move the document view if the cell is completely out of view.

Lua-supported.

Parameters

[in]	measure	The 1-based measure number in the document
[in]	staffno	(Optional parameter) The 1-based staff number. If it's 0 or omitted, the top staff will be used.

RedrawDocument()

void FCUI::RedrawDocument

(

)

Visually redraws the current document.

This method doesn't affect the document's data.

Lua-supported.

SetUseIsFontAvailableAPI()

void FCUI::SetUseIsFontAvailableAPI ( bool state )

inline

Sets if Finale's own API for checking font availability should be used for IsFontAvailable().

If set, the Finale API will only be used on Finale 25 and above. On earlier Finale versions, the PDK Framework's own implementation will always be used.

Lua-supported (also as property).

Parameters

[in]

state

True if Finale's own API should be used (on Finale 25 and above). False if the PDK Framework's implementation should be used.

TextToClipboard()

bool FCUI::TextToClipboard

(

const char *

pszText

)

Copies text to the operating system's clipboard.

Parameters

pszText

The NULL-terminated text to copy to the OS clipboard.

Returns

true on success.

TextToClipboardUTF8()

bool FCUI::TextToClipboardUTF8

(

const char *

pszText

)

Copies text to the operating system's clipboard from an UTF8 source.

Lua-supported (as TextToClipboard).

Parameters

pszText

The NULL-terminated text to copy to the OS clipboard.

Returns

true on success.