FCCustomKeyModeDef Class Reference

Class that allows access to custom key modes. (Finale calls them "Nonstandard Key Signatures", but they define modes rather than key signatures.) More...

#include <ff_other.h>

Inheritance diagram for FCCustomKeyModeDef:

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.
const PDKFRAMEWORK_CLASSID	GetClassID () const override
	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.
	FCCustomKeyModeDef ()
	The constructor.
bool	SaveNewLinear ()
	saves the current instance as new linear custom key mode.
bool	SaveNewNonLinear ()
	saves the current instance as new non-linear custom key mode.
eKey	GetKeyID (int accidentalnumber=0) const
	Returns the key ID for this custom key mode, based on the input number of sharps or flats (for linear key modes). This value can be used to update the key signature of a measure or cell using FCKeySignature::SetID.
bool	IsLinear () const
	Returns true if this is a linear mode.
bool	IsNonLinear () const
	Returns true if this is a non-linear mode.
bool	IsPredefined () const
	Returns true if this is a predefined mode (major or minor).
twobyte	GetHarmonicReference () const
	Returns the "Harmonic Reference" value from the Special Key Signature Attributes dialog.
void	SetHarmonicReference (twobyte value)
	Sets the "Harmonic Reference" value from the Special Key Signature Attributes dialog.
twobyte	GetMiddleKeyNumber () const
	Returns the "Middle Key Number" value from the Special Key Signature Attributes dialog.
void	SetMiddleKeyNumber (twobyte value)
	Sets the "Middle Key Number" value from the Special Key Signature Attributes dialog.
twobyte	GetGoToKeyUnit () const
	Returns the "Go to Key Unit" value from the Special Key Signature Attributes dialog.
void	SetGoToKeyUnit (twobyte value)
	Sets the "Go to Key Unit" value from the Special Key Signature Attributes dialog.
twobyte	GetSymbolListID () const
	Returns the item number (ID) of the custom symbol list for accidentals, or zero if none. (When this value is zero, default symbols are used.)
void	SetSymbolListID (twobyte value)
	Sets the item number (ID) of the custom symbol list for accidentals. (Setting this value to zero causes the FCCustomKeyModeDef item to use the default symbols.)
bool	GetHasClefAccidentalPlacements () const
	Returns whether the custom key mode has accidental octave placement records.
void	SetHasClefAccidentalPlacements (bool state)
	Sets whether the custom key mode has accidental octave placement records.
EFONTID	GetAccidentalFontID () const
	Returns the font ID for accidental symbols.
void	SetAccidentalFontID (const EFONTID value)
	Sets the font ID for accidental symbols.
FCFontInfo *	CreateAccidentalFontInfo () const
	Creates an instance of FCFontInfo that matches the current setting of GetAccidentalFontID. See comments at SetAccidentalFontID for more information about how this value is constructed.
twobyte	GetTotalChromaticSteps () const
	Returns the "Total Steps" value from the Key Step Map dialog.
void	SetTotalChromaticSteps (twobyte value)
	Sets the "Total Steps" value from the Key Step Map dialog.
std::vector< eHarmLev >	GetDiatonicStepsMap () const
	Returns a list specifying the chromatic step where each diatonic step occurs.
void	SetDiatonicStepsMap (const std::vector< eHarmLev > &list)
	Sets a list specifiying the chromatic step where each diatonic step occurs.
std::map< twobyte, twobyte >	GetTonalCenters () const
	Returns the table of tonal centers by number of sharps/flats.
void	SetTonalCenters (const std::map< twobyte, twobyte > &values)
	Sets the table of tonal centers by number of sharps/flats.
twobyte	GetBaseTonalCenter () const
	Returns the base tonal center for the key mode.
void	SetBaseTonalCenter (twobyte value)
	Sets the base tonal center for the key mode.
std::map< twobyte, twobyte >	GetAccidentalOrder () const
void	SetAccidentalOrder (const std::map< twobyte, twobyte > &values)
std::map< twobyte, twobyte >	GetAccidentalAmounts () const
void	SetAccidentalAmounts (const std::map< twobyte, twobyte > &values)
std::vector< std::map< twobyte, twobyte > >	GetClefAccidentalPlacements () const
void	SetClefAccidentalPlacements (const std::vector< std::map< twobyte, twobyte > > &values)
FCKeySignature *	CreateKeySignature (eHarmAlt alteration=0) const
	Creates a FCKeySignature instance for this custom key signature.
Public Member Functions inherited from __FCNoInciOther
	__FCNoInciOther ()
	The constructor.
virtual bool	Load (CMPER itemno)
	Loads the indicated item.
bool	Reload () override
	Overridden Reload() method to support complex data types.
virtual bool	SaveAs (CMPER itemno)
	Saves the data under another item number. The object will now be connected to the new item number.
virtual bool	DeepSaveAs (CMPER itemno)
	Saves the data under another item number, but also makes a deep copy of the object.
bool	DeepDeleteData () override
	Deletes the data and all related data available in other data structures.
virtual CMPER	GetItemNo () const
	Returns the item number. This typically points to items such as a page number, a measure number, a 1-based expression definition number, etc.
void	SetItemNo (CMPER cmper)
	Sets the item number. Use with extreme care! This is mostly intended for situations when creating new records isn't supported by Finale (preventing SaveAs to work).
bool	LoadFirst () override
	Loads the first element of 1-based data.
void	DebugDump () override
	Outputs the class data/information for debugging purposes.
Public Member Functions inherited from __FCOther
void	SetCmperAndInci (CMPER cmper, twobyte inci)
	Sets both the CMPER and the incident number in the dataID record. Mainly for internal use.
	__FCOther ()
	The constructor.
bool	IsIdenticalRecord (__FCOther *pCompare)
	Compares an object to see if both objects point to the same data record.
Public Member Functions inherited from __FCBaseData
EDOCID	GetConnectedDocID () const
	Returns the document ID that was connected to the last load/save of the data.
bool	VerifyConnectedDocID ()
	Checks that the stored document ID for the data object matches the current document's ID.
virtual EXTAG	Tag () const =0
	The Enigma tag for the derived class.
virtual EVERSION	EnigmaVersion () const
	The Enigma version for save/load/create/delete operations.
virtual int	DataSizeLoad () const =0
	Returns the data size for the data structure that should be loaded.
virtual int	DataSizeSave () const
	Returns the data size for the data structure that should be saved or created.
void	_CloneFrom (__FCBaseData *pSource)
	For internal use only. Copies object data (except data block) from another object.
virtual void	CloneMemoryFrom (__FCBaseData *pSource)
const EDataID *	_GetDataID ()
	Intended ONLY for the _CloneFrom implementation.
int	_GetLoadedSize () const
	Intended ONLY for the _CloneFrom implementation.
const void *	GetDataBlock ()
	Intended ONLY for the _CloneFrom implementation.
EXTAG	GetCustomTag () const
	Returns the custom Enigma tag, if any.
void	SetCustomTag (EXTAG tag)
	Sets the custom Enigma tag, for classes that support multiple Enigma tags.
	__FCBaseData ()
	The constructor.
virtual	~__FCBaseData ()
	Virtual destructor.
virtual bool	Save ()
	Saves the currently loaded to its current location.
virtual bool	DeleteData ()
	Deletes the associated data from Finale's database. Be careful when deleting multiple objects.
virtual bool	LoadLast ()
	Loads the very last element in the database, if any.
virtual bool	LoadNext ()
	Loads the next element from the database, if any.
virtual bool	LoadPrevious ()
	Loads the previous element in the database, if any.
bool	RelinkToCurrentView ()
	Relinks the contents in the current view so that the score and part(s) match.
bool	RelinkToScore ()
	Relinks all parts to the contents of the score.
__FCBaseData *	CreateClone ()
	Creates an identical copy of an object.
void	DebugDataDump () override
	Outputs a memory dump of the data block in the object for debugging purposes.
void	DebugDataByteArrayDump () override
	Outputs a memory dump of the data block in the object for debugging purposes, as a C++ byte array.
void	DebugDataOffsetDump (int offset, int size)
	For debug mode only. Dumps a data memory block at a specific offset and with a specific size.
FCNumbers *	CreateRawDataDump ()
	Creates a byte collection with the raw loaded data block for the object (if the object type supports single data blocks). This method is only intended for debug purposes.
Public Member Functions inherited from __FCBase
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.
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 bool	DeleteItemNo (CMPER itemno)
	Class function that deletes all data associated with an item number.
static std::map< twobyte, twobyte >	GetDefaultTonalCenters ()
	Class method that returns the default tonal centers for the major mode in common practice notation.
static bool	CalcIsDefaultTonalCenters (const std::map< twobyte, twobyte > &values)
	Class function that returns true if the input tonal centers match the default setting.
static std::map< twobyte, twobyte >	GetDefaultAccidentalOrder ()
	Class method that returns the default accidental order for the key signatures in common practice notation.
static bool	CalcIsDefaultAccidentalOrder (const std::map< twobyte, twobyte > &values)
	Class function that returns true if the input accidental order matches the default setting.
static std::map< twobyte, twobyte >	GetDefaultAccidentalAmounts ()
	Class method that returns the default accidental amounts for the key signatures in common practice notation.
static bool	CalcIsDefaultAccidentalAmounts (const std::map< twobyte, twobyte > &values)
	Class function that returns true if the input accidental amounts match the default setting.
static std::vector< std::map< twobyte, twobyte > >	GetDefaultClefAccidentalPlacements ()
	Class method that returns the default clef accidental placements for the key signatures in common practice notation.
static bool	CalcIsDefaultClefAccidentalPlacements (const std::vector< std::map< twobyte, twobyte > > &values)
	Class function that returns true if the input clef accidental placements match the default setting.
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
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 __FCBaseData
virtual void *	Allocate ()=0
virtual void	Deallocate ()
virtual bool	IsDynamicSize ()
bool	LoadDataBlock ()
	Loads the data. If the object is of dynamic size, the old memory block is freed and a new is allocated.
void	ClearData ()
virtual twobyte	CalcLastInci ()
	For internal use only!
virtual __FCBaseData *	CreateObject ()=0
	Creates a new instance of the object.
bool	DataIsLoaded () const
	Returns true is any data has been loaded into the object.
void	_TagDocumentID ()
	For internal use only.
Protected Member Functions inherited from __FCBase
	__FCBase ()
	The constructor.
Protected Attributes inherited from __FCBaseData
EDOCID	_connecteddocID
	The "connected" document ID., which is the document the where the document was loaded (or last saved). This is for a mechanism to prevent resaving of certain data in other documents.
void *	_datablock
	Pointer to the object's data block, the meaning is implementation-specific for each derived subclass.
bool	_heapdatablock
	Variable that tells if _datablock is dynamically created on the heap (and should be deleted at object destruction).
int	_loadedsize
	Loaded size of the data block for a loaded object, in bytes. Since the datablock is implementation-specific, the _loadedsize should be updated by child classes that create new data.
EDataID	_dataid
	The EdataID for the last loaded/saved object.

Detailed Description

Class that allows access to custom key modes. (Finale calls them "Nonstandard Key Signatures", but they define modes rather than key signatures.)

Custom key modes in Finale serve multiple functions. They can

• define diatonic modes other than Major or Minor (e.g, Dorian, Phrygian, etc.)
• define non-diatonic modes, such as Freygish that is Phrygian with a major 3rd.
• define microtonal scales such as 24-EDO, 31-EDO, etc.
• define special character sequences for accidentals.
• define a special font for accidentals that is specific to the custom mode.
• define tonal centers for modes other than major or minor.
• define sequence and octave placement for accidental symbols in the key signature.

A FCCustomKeyModeDef does not have to specify all of these. In fact, Finale is extremely permissive about allowing the use of a custom key mode item number without any data defined for it. (It then behaves like a major key.) The PDK Framework, however, cannot load an existing custom key signature unless at least some of its data have been defined. Clicking any of the AccOrder, ToneCenter, AccOctaves, or Attributes buttons along the bottom of the "Nonstandard Key Signature" dialog opens another dialog. If you OK out of any of these four dialogs, this is enough to make it visible to the PDK Framework as a FCCustomKeyModeDef. (You do not have to actually apply the Nonstandard Key Signature to your score.)

Custom key modes come in two flavors, linear and non-linear. A linear key mode can be transposed to have a key signature for any tonal center whereas a non-linear key mode has a fixed key signature. A Finale document can have no more than 64 linear modes. Major and minor modes are predefined with the IDs 0 and 1. Therefore, linear custom key modes have a GetItemNo between 2 and 63.

You can load information for predefined major and minor modes, but the GetTotalChromaticSteps and GetDiatonicStepsMap values are meaningless for them. (For predefined modes, GetTotalChromaticSteps should be 0 and GetDiatonicStepsMap should have no values.) Use FCKeySignature::CalcTotalChromaticSteps and FCKeySignature::CalcDiatonicStepsMap to get these values for any key mode, whether predefined or not.

Non-linear key modes have a GetItemNo between 16834 (0x4000) and 32767 (0x7fff). The Finale UI strips the top bit from the ID, so when you see "Nonlinear Key Signature 0" in the Nonstandard Key Signature dialog, it refers to non-linear custom key mode 0x4000.

Constructor & Destructor Documentation

FCCustomKeyModeDef()

FCCustomKeyModeDef::FCCustomKeyModeDef ( )

inline

The constructor.

Lua-supported (0.72)

Member Function Documentation

CalcIsDefaultAccidentalAmounts()

static bool FCCustomKeyModeDef::CalcIsDefaultAccidentalAmounts ( const std::map< twobyte, twobyte > & values )

inlinestatic

Class function that returns true if the input accidental amounts match the default setting.

Lua-supported (0.72)

CalcIsDefaultAccidentalOrder()

static bool FCCustomKeyModeDef::CalcIsDefaultAccidentalOrder ( const std::map< twobyte, twobyte > & values )

inlinestatic

Class function that returns true if the input accidental order matches the default setting.

Lua-supported (0.72)

CalcIsDefaultClefAccidentalPlacements()

static bool FCCustomKeyModeDef::CalcIsDefaultClefAccidentalPlacements ( const std::vector< std::map< twobyte, twobyte > > & values )

inlinestatic

Class function that returns true if the input clef accidental placements match the default setting.

Lua-supported (0.72)

CalcIsDefaultTonalCenters()

static bool FCCustomKeyModeDef::CalcIsDefaultTonalCenters ( const std::map< twobyte, twobyte > & values )

inlinestatic

Class function that returns true if the input tonal centers match the default setting.

Lua-supported (0.72)

ClassName()

const char * FCCustomKeyModeDef::ClassName ( ) const

inlineoverridevirtual

Returns the name of the class, for diagnostic purposes. This method MUST be overwritten in each child class.

Lua-supported.

Reimplemented from __FCNoInciOther.

CreateAccidentalFontInfo()

FCFontInfo * FCCustomKeyModeDef::CreateAccidentalFontInfo

(

)

const

Creates an instance of FCFontInfo that matches the current setting of GetAccidentalFontID. See comments at SetAccidentalFontID for more information about how this value is constructed.

C callers must dispose of the return value either with delete or a smart pointer.

Lua-supported (0.72)

Returns

an instance of FCFontInfo that matches the font for the accidentals of the key signature, or NULL if no document is open or there is an error.

CreateKeySignature()

FCKeySignature * FCCustomKeyModeDef::CreateKeySignature

(

eHarmAlt

alteration = 0

)

const

Creates a FCKeySignature instance for this custom key signature.

One use for getting an instance of FCKeySignature is to call FCKeySignature::CalcDiatonicStepsMap to get the steps map for the specified tonal center.

C++ callers must dispose of the result, either with a smart pointer or by deleting it.

Lua-supported (0.72)

Parameters

alteration

(optional on both C++ and Lua) the number of sharps (positive) or flats (negative). Ignored if the key mode is non-linear. Defaults to zero.

Returns

an instance of FCKeySignature that represents this FCCustomKeyModeDef.

DeleteItemNo()

static bool FCCustomKeyModeDef::DeleteItemNo ( CMPER itemno )

inlinestatic

Class function that deletes all data associated with an item number.

Remarks

Finale allows FCCustomKeyModeDef items to be created with any combination of dependent data or none. This function allows you to delete any and all data associated with an item number, including predefined items 0 (major) and 1 (minor).

Note that after deletion, the item numbers may still be associated with FCMeasure and/or FCCell instances. In this case the predefined values 0 and 1 behave as standard major and minor, respectively. All other values behave as standard major.

Lua-supported (0.72)

Parameters

itemno

The item number to delete.

GetAccidentalAmounts()

std::map< twobyte, twobyte > FCCustomKeyModeDef::GetAccidentalAmounts ( ) const

inline

Returns a table for the amount (in chromatic steps) of each successive accidental in the key signature

See SetAccidentalAmounts for more information.

Lua-supported (also as property) (0.72)

Returns

a table (Lua) or std::map (C++) with integer indices representing the nth flat or sharp and a positive or negative value representing the alteration amount for that flat or sharp (in chromatic steps).

GetAccidentalFontID()

EFONTID FCCustomKeyModeDef::GetAccidentalFontID ( ) const

inline

Returns the font ID for accidental symbols.

See SetAccidentalFontID for more information.

Lua-supported (also as property) (0.72)

GetAccidentalOrder()

std::map< twobyte, twobyte > FCCustomKeyModeDef::GetAccidentalOrder ( ) const

inline

Returns a table for the order of accidentals in the custom key mode.

See SetAccidentalOrder for more information.

Lua-supported (also as property) (0.72)

Returns

a table (Lua) or std::map (C++) with integer indices representing the nth of flat or sharp and a value from 0..6 that corresponds to the pitch name that recieves the nth flat or sharp.

GetBaseTonalCenter()

twobyte FCCustomKeyModeDef::GetBaseTonalCenter ( ) const

inline

Returns the base tonal center for the key mode.

See comments at SetBaseTonalCenter for more information.

Lua-supported (also as property) (0.72)

Returns

For linear key modes, the tonal center when there is no key signature. For non-linear key modes, the (only) tonal center for the mode.

GetClassID()

const PDKFRAMEWORK_CLASSID FCCustomKeyModeDef::GetClassID ( ) const

inlineoverridevirtual

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.

This method must be overwritten by all child classes.

Lua-supported (also read-only property) (0.55).

Implements __FCBaseData.

GetClefAccidentalPlacements()

std::vector< std::map< twobyte, twobyte > > FCCustomKeyModeDef::GetClefAccidentalPlacements ( ) const

inline

Returns a table for the octave placements for each clef for each nth accidental

See SetClefAccidentalPlacements for more information.

Lua-supported (also as property) (0.72)

Returns

a table (Lua) or std::vector (C++) with a table of values per clef.

GetDefaultAccidentalAmounts()

static std::map< twobyte, twobyte > FCCustomKeyModeDef::GetDefaultAccidentalAmounts ( )

inlinestatic

Class method that returns the default accidental amounts for the key signatures in common practice notation.

Lua-supported (0.72)

Returns

table (Lua) or std::map (C++) representing default accidental amounts that may be altered and then passed to SetAccidentalAmounts.

GetDefaultAccidentalOrder()

static std::map< twobyte, twobyte > FCCustomKeyModeDef::GetDefaultAccidentalOrder ( )

inlinestatic

Class method that returns the default accidental order for the key signatures in common practice notation.

If you are modifying the accidental amounts but wish to keep the default accidental order, pass this value to SetAccidentalOrder.

Lua-supported (0.72)

Returns

table (Lua) or std::map (C++) representing the default accidental order that may be altered and then passed to SetAccidentalOrder.

GetDefaultClefAccidentalPlacements()

static std::vector< std::map< twobyte, twobyte > > FCCustomKeyModeDef::GetDefaultClefAccidentalPlacements ( )

inlinestatic

Class method that returns the default clef accidental placements for the key signatures in common practice notation.

If you only need to modify a few values, you may find it easier to start from this table rather than creating the entire thing from scratch.

Lua-supported (0.72)

Returns

table (Lua) or std::map (C++) representing default clef accidental placements that may be altered and then passed to SetClefAccidentalPlacements.

GetDefaultTonalCenters()

static std::map< twobyte, twobyte > FCCustomKeyModeDef::GetDefaultTonalCenters ( )

inlinestatic

Class method that returns the default tonal centers for the major mode in common practice notation.

Adding to the same amount to all these values (modulo 7) is a simple way to get the tonal centers for the church modes. (Or use SetBaseTonalCenter.)

Lua-supported (0.72)

Returns

table (Lua) or std::map (C++) representing the default tonal centers that may be altered and then passed to SetTonalCenters.

GetDiatonicStepsMap()

std::vector< eHarmLev > FCCustomKeyModeDef::GetDiatonicStepsMap ( ) const

inline

Returns a list specifying the chromatic step where each diatonic step occurs.

The first element is always zero. The elements always increase, and the final element must be less than GetTotalChromaticSteps. If the array has a number of elements other than 7, it can't easily be represented on a traditional staff, so the chance of a number of elements other than 7 is vanishingly small. But Finale allows it.

Remarks

GetDiatonicStepsMap does not handle the following:

• Tonal centers. The table returned by GetDiatonicStepsMap is the map starting on C, regardless of the values in SetTonalCenters.
• Predefined modes. Predefined modes use hard-coded step maps, so for predefined modes GetDiatonicStepsMap may return an empty list.

Use FCKeySignature::CalcDiatonicStepsMap to get the correct diatonic steps map for any mode with any tonal center, whether predefined or not. GetDiatonicStepsMap and SetDiatonicStepsMap are for managing the settings of FCCustomKeyModeDef instances.

Lua-supported (also as property) (0.72)

Returns

a table (Lua) or std::vector (C++) containing a list of integers.

GetGoToKeyUnit()

twobyte FCCustomKeyModeDef::GetGoToKeyUnit ( ) const

inline

Returns the "Go to Key Unit" value from the Special Key Signature Attributes dialog.

See SetGoToKeyUnit for more information.

Lua-supported (also as property) (0.72)

GetHarmonicReference()

twobyte FCCustomKeyModeDef::GetHarmonicReference ( ) const

inline

Returns the "Harmonic Reference" value from the Special Key Signature Attributes dialog.

See SetHarmonicReference for more information.

Lua-supported (also as property) (0.72)

GetHasClefAccidentalPlacements()

bool FCCustomKeyModeDef::GetHasClefAccidentalPlacements ( ) const

inline

Returns whether the custom key mode has accidental octave placement records.

This is an optimization flag so that Finale does not have to look for them every time it needs to get other information about the mode.

Lua-supported (also as property) (0.72)

GetKeyID()

eKey FCCustomKeyModeDef::GetKeyID ( int accidentalnumber = 0 ) const

inline

Returns the key ID for this custom key mode, based on the input number of sharps or flats (for linear key modes). This value can be used to update the key signature of a measure or cell using FCKeySignature::SetID.

Lua-supported (0.72)

Parameters

accidentalnumber

(optional on both Lua and C++) the number of sharps (positive) or flats (negative). This value is ignored if IsLinear is false.

GetMiddleKeyNumber()

twobyte FCCustomKeyModeDef::GetMiddleKeyNumber ( ) const

inline

Returns the "Middle Key Number" value from the Special Key Signature Attributes dialog.

See SetMiddleKeyNumber for more information.

Lua-supported (also as property) (0.72)

GetSymbolListID()

twobyte FCCustomKeyModeDef::GetSymbolListID ( ) const

inline

Returns the item number (ID) of the custom symbol list for accidentals, or zero if none. (When this value is zero, default symbols are used.)

Lua-supported (also as property) (0.72)

Returns

an ID that can be used to load the corresponding FCCustomKeyModeSymbolList, if it is non-zero. Note that multiple FCCustomKeyModeDef items can share the same custom symbol list.

GetTonalCenters()

std::map< twobyte, twobyte > FCCustomKeyModeDef::GetTonalCenters ( ) const

inline

Returns the table of tonal centers by number of sharps/flats.

See SetTonalCenters for more information.

Lua-supported (also as property) (0.72)

Returns

a table (Lua) or std::map (C++) with integer indices -7..+7 representing the number of flats or sharps and a value from 0..6 that corresponds to the pitch name that is the tonal center.

GetTotalChromaticSteps()

twobyte FCCustomKeyModeDef::GetTotalChromaticSteps ( ) const

inline

Returns the "Total Steps" value from the Key Step Map dialog.

See SetTotalChromaticSteps for more information.

Lua-supported (also as property) (0.72)

IsLinear()

bool FCCustomKeyModeDef::IsLinear ( ) const

inline

Returns true if this is a linear mode.

Warning

Linear key mode item numbers can only be in the range 0..63, whereas non-linear key mode items numbers can only be in the range 0x4000..0x7fff. That means values in the range 64..0x3fff will return false for both IsLinear and IsNonLinear. If you encounter such a value, it is evidence of Finale file corruption or a bug either in Finale or the PDK Framework.

Lua-supported (0.72)

IsNonLinear()

bool FCCustomKeyModeDef::IsNonLinear ( ) const

inline

Returns true if this is a non-linear mode.

See comments at IsLinear for when both IsNonLinear and IsLinear may be false.

Lua-supported (0.72)

IsPredefined()

bool FCCustomKeyModeDef::IsPredefined ( ) const

inline

Returns true if this is a predefined mode (major or minor).

Lua-supported (0.72)

SaveNewLinear()

bool FCCustomKeyModeDef::SaveNewLinear

(

)

saves the current instance as new linear custom key mode.

Lua-supported (0.72)

SaveNewNonLinear()

bool FCCustomKeyModeDef::SaveNewNonLinear

(

)

saves the current instance as new non-linear custom key mode.

Lua-supported (0.72)

SetAccidentalAmounts()

void FCCustomKeyModeDef::SetAccidentalAmounts ( const std::map< twobyte, twobyte > & values )

inline

Sets a table for the amount (in chromatic steps) of each successive accidental in the key signature

Remarks

The table has valid index values in the range -7..-1 and +1..+7. Zero is not a valid index and if you assign a table containing a zero index, a run-time error occurs. A run-time error also occurs for any index less than -7 or greater than +7. The meaning of these indices varies slightly depending on if the key mode is linear or non-linear.

• Linear key modes. The positive indices represent the nth sharp in the key signature and the negative indices represent the nth flat. You should provide values for all 14 possible indices.
• Nonlinear key modes. The positive indices correspond to the indices in the GetAccidentalOrder table for the non-linear key mode. You should provide values only for the 7 positive indices.

The values can be any positive or negative value. For linear key modes they typically all have the magnitude of a chromatic half-step and are positive for positive indices and negative for negative indices. Here are are the magnitude values for chromatic half-steps in frequently-used microtone systems:

• 12-EDO: 1 (this is the default common-practice value)
• 19-EDO: 1
• 24-EDO: 2 (equal-tempered quarter tones)
• 31-EDO: 2
• 48-EDO: 4
• 72-EDO: 6
• 96-EDO: 8 (however, since Finale cannot represent alterations greater than magnitude 7, this value results in no visible key signatures.)

The values for non-linear key modes can be either positive or negative depending on whether the nth accidental is sharp or a flat. Only supply the positive indices. To terminate the key signature before 7 accidentals, set the last value to 0. (For an example, see D_freygish_accidental_amounts in the code example.)

-- D Freygish has Bb, Eb, and F#.
local D_freygish_accidental_amounts =
{
    [1] = -1, -- flat (the B is provided in the GetAccidentalOrder table)
    [2] = -1, -- flat (the E is provided in the GetAccidentalOrder table)
    [3] = 1,  -- sharp (the F is provided in the GetAccidentalOrder table)
    [4] = 0,  -- the zero terminates the key signature
    -- the rest of these values don't matter because of the zero at index 4.
    -- The values shown are initialized zeros, but they could just as easily
    -- be any other values.
    [5] = 0,
    [6] = 0,
    [7] = 0
}
-- alternatively, you could pass a table with the first three values and the
-- zeros will automatically be added by SetAccidentalAmounts:
local keymode = finale.FCCustomKeyModeDef()
-- Set D Freygish accidental amounts:
keymode:SetAccidentalAmounts({-1, -1, 1}) -- the other four values are added as zero

Lua-supported (also as property) (0.72)

Parameters

values

a table (Lua) or std::map (C++) with integer indices representing the nth flat or sharp and a positive or negative value representing the alteration amount for that flat or sharp (in chromatic steps).

SetAccidentalFontID()

void FCCustomKeyModeDef::SetAccidentalFontID ( const EFONTID value )

inline

Sets the font ID for accidental symbols.

You can only specify a custom font ID for accidental symbols. The symbols will use the same size and style as the default accidentals font. (See FCFontPrefs::FONTPREF_KEYSIG.) This somewhat limits your choices as to which fonts may be used here.

Set this value to zero to use the default value. (FCFontPrefs::FONTPREF_KEYSIG)

Lua-supported (also as property) (0.72)

SetAccidentalOrder()

void FCCustomKeyModeDef::SetAccidentalOrder ( const std::map< twobyte, twobyte > & values )

inline

Sets a table for the order of accidentals in the custom key mode.

Remarks

The table has valid index values in the range -7..-1 and +1..+7. Zero is not a valid index and if you assign a table containing a zero index, a run-time error occurs. A run-time error also occurs for any index less than -7 or greater than +7. The meaning of these indices varies slightly depending on if the key mode is linear or non-linear.

• Linear key modes. The positive indices represent the number of sharps and the negative indices represent the number of flats. You should provide values for all 14 possible indices. (See common_practice_accidental_order in the code example.)
• Nonlinear key modes. The positive indices can be either sharps or flats in arbitrary order, and the negative indices are ignored. You should provide values for only the 7 positive indices. The number of sharps or flats is determined by the first 0-value in the parallel table GetAccidentalAmounts. The values after that index are ignored. (See D_freygish_accidental_order in the code example.

The values are numbers corresponding to the seven pitch names, where C=0, D=1, E=2, F=3, G=4, A=5, B=6.

If you only want the common-practice diatonic progression of sharps and flats, you do not need to provide a table. However, you should provide a table here (even if it is the default diatonic table) if you set a table with SetAccidentalAmounts. An example of when you would do this is when defining a microtone system with sharp and flat key signatures that display normally. You should then set this table to the common-practice diatonic progression (shown in the code example).

local common_practice_accidental_order =
{
    [1] = 3,  -- F is the 1st sharp
    [2] = 0,  -- C is the 2nd sharp
    [3] = 4,  -- G is the 3rd sharp
    [4] = 1,  -- D is the 4th sharp
    [5] = 5,  -- A is the 5th sharp
    [6] = 2,  -- E is the 6th sharp
    [7] = 6,  -- B is the 7th sharp
    [-1] = 6, -- B is the 1st flat
    [-2] = 2, -- E is the 2nd flat
    [-3] = 5, -- A is the 3rd flat
    [-4] = 1, -- D is the 4th flat
    [-5] = 4, -- G is the 5th flat
    [-6] = 0, -- C is the 6th flat
    [-7] = 3  -- F is the 7th flat
}
 
-- D Freygish has Bb, Eb, and F#.
local D_freygish_accidental_order =
{
    [1] = 6, -- B (the flat is provided in the GetAccidentalAmounts table)
    [2] = 2, -- E (the flat is provided in the GetAccidentalAmounts table)
    [3] = 3, -- F (the sharp is provided in the GetAccidentalAmounts table)
    -- the rest of these values don't matter because the GetAccidentalAmounts
    -- table will have a 0 at index 4, which stops the key signature. The values
    -- shown are left-over diatonic default values, but they could just as easily
    -- be any other values between 0..6.
    [4] = 1,
    [5] = 5,
    [6] = 2,
    [7] = 6
}
-- alternatively, you could pass a table with the first three values and
-- zeros will automatically be added by SetAccidentalOrder:
local keymode = finale.FCCustomKeyModeDef()
-- Set D Freygish accidental order:
keymode:SetAccidentalOrder({6, 2, 3}) -- the other four values are added as zero

Lua-supported (also as property) (0.72)

Parameters

values

a table (Lua) or std::map (C++) with integer indices representing the nth of flat or sharp and a value from 0..6 that corresponds to the pitch name that recieves the nth flat or sharp.

SetBaseTonalCenter()

void FCCustomKeyModeDef::SetBaseTonalCenter ( twobyte value )

inline

Sets the base tonal center for the key mode.

Remarks

This method may be used instead of SetTonalCenters. It is recommend to use SetBaseTonalCenter for

• non-linear key modes.
• linear key modes with key signatures that follow the circle of fifths in a manner similar to common practice.

SetBaseTonalCenter populates SetTonalCenters with appropriate values based on the input value and whether the mode is linear or non-linear.

Lua-supported (also as property) (0.72)

Parameters

value

For linear key modes, the tonal center when there is no key signature. For non-linear key modes, the (only) tonal center for the mode.

SetClefAccidentalPlacements()

void FCCustomKeyModeDef::SetClefAccidentalPlacements ( const std::vector< std::map< twobyte, twobyte > > & values )

inline

Sets a table for the octave placements for each clef for each nth accidental

Remarks

The value passed into SetClefAccidentalPlacements is an array of tables. The top-level array contains one element for each clef index. (See FCClefDef::GetClefIndex.) As of Finale 27, there are 18 possible clef definitions, so with C++ the indices range from 0..17, matching the clef indices. For Lua the indices range from 1..18, which means you must add 1 to the clef index to access the corresponding element in this array.

The elements of the top-level array are themselves tables. The indices of the tables range from -1..-7 (for the 1st to the 7th flat) and +1..+7 (for the 1st to the 7th sharp). The values of the tables specify the octave in which to place the accidental for that slot. Octave 0 corresponds to the C4 octave (from middle-C to the B above it). -1 specifies the C3 octave, +1 specifies C5 octave, etc.

Non-linear key modes should provide only the positive indices +1..+7. These specify the octave for each successive accidental in the key signature, be it sharp or flat. Linear key modes should always provide all 14 indices. Any index outside the values -1..-7 and +1..+7 results in a runtime error when the table is passed to SetClefAccidentalPlacements.

If your FCCustomKeyModeDef does not require special accidental placement, you do not have to supply a table. However, if you need accidental placements other than the default, you must provide all the clefs and all the settings per clef. You can use the class-level function GetDefaultClefAccidentalPlacements to populate a table with the defaults for all clefs and accidentals, and you can then modify it from there.

Lua-supported (also as property) (0.72)

Parameters

values

a table (Lua) or std::vector (C++) with a table of values per clef.

SetDiatonicStepsMap()

void FCCustomKeyModeDef::SetDiatonicStepsMap ( const std::vector< eHarmLev > & list )

inline

Sets a list specifiying the chromatic step where each diatonic step occurs.

Leave this list empty for predefined modes major and minor. Specify it for all other custom key modes.

See comments at GetDiatonicStepsMap for more information.

Lua-supported (also as property) (0.72)

Parameters

list	a table (Lua) or std::vector (C++) containing a list of integers.

SetGoToKeyUnit()

void FCCustomKeyModeDef::SetGoToKeyUnit ( twobyte value )

inline

Sets the "Go to Key Unit" value from the Special Key Signature Attributes dialog.

The Finale Manual states: this is the number of scale steps Finale should consider to be between each pair of keys on your MIDI keyboard. In other words, if you’ve specified a quarter-tone scale, tell Finale that the Key Unit is 2—there are two scale tones, not one, between one synthesizer key and the next. (If your synthesizer can produce quarter tones, however, leave the Key Unit at 1, so that Finale correctly plays your quarter-tone score.) If you’ve specified the correct Key Unit value, Finale transcribes and plays any music performed in the usual way correctly. If you created a quarter-tone scale without changing the Key Unit, by contrast, you’d have to drastically modify your playing style.

Unfortunately, empirical evidence suggests that this feature is not well-implemented. Modes other than 12-EDO do not play back correctly no matter what value you choose here. Even if it worked as documented for 24-EDO (as the manual text implies), it could never work correctly for EDO values where diatonic half-steps differ in size from chromatic half-steps (e.g., 19-EDO or 31-EDO.) Therefore, you probably should leave this value at 1 and let your playback system handle it if it can.

Lua-supported (also as property) (0.72)

SetHarmonicReference()

void FCCustomKeyModeDef::SetHarmonicReference ( twobyte value )

inline

Sets the "Harmonic Reference" value from the Special Key Signature Attributes dialog.

The number in this text box identifies the note that all other dialog boxes in Finale’s key system will consider to be the C, or fundamental root tone. Zero is used for C, 1 for D, 2 for E, and so on. There’s little reason ever to change the default setting in this text box (zero, or C).

Lua-supported (also as property) (0.72)

SetHasClefAccidentalPlacements()

void FCCustomKeyModeDef::SetHasClefAccidentalPlacements ( bool state )

inline

Sets whether the custom key mode has accidental octave placement records.

The PDK Framework sets this appropriately when Save is called. Normally the caller should not set it.

Lua-supported (also as property) (0.72)

SetMiddleKeyNumber()

void FCCustomKeyModeDef::SetMiddleKeyNumber ( twobyte value )

inline

Sets the "Middle Key Number" value from the Special Key Signature Attributes dialog.

The Finale Manual states: the number in this text box specifies the MIDI key number that corresponds to the Harmonic Reference number. (In the MIDI key numbering system, the keys on a synthesizer are numbered sequentially from bottom to top. Middle C is note 60, C sharp is 61, and so on.)

Observed behavior, however, is that the Middle Key Number is not dependent on the Harmonic Reference. The Middle Key Number always corresponds to the note on the first ledger line below the treble clef staff (i.e. the note that looks like Middle C), regardless of what the Harmonic Reference Number is, and regardless of what name Finale assigns to said note.

Remarks

You can use this parameter to good advantage if you want to transform your synthesizer into a transposing synthesizer (as far as Finale is concerned). For example, if you set the Middle Key Number to 48 (C below middle C), Finale interprets every note you play as a note an octave higher; likewise, when Finale plays back a score, it plays notes on your synthesizer an octave lower than written.

Lua-supported (also as property) (0.72)

SetSymbolListID()

void FCCustomKeyModeDef::SetSymbolListID ( twobyte value )

inline

Sets the item number (ID) of the custom symbol list for accidentals. (Setting this value to zero causes the FCCustomKeyModeDef item to use the default symbols.)

Lua-supported (also as property) (0.72)

Parameters

value

an ID that can be used to load the corresponding FCCustomKeyModeSymbolList, if it is non-zero. Note that multiple FCCustomKeyModeDef items can share the same custom symbol list.

SetTonalCenters()

void FCCustomKeyModeDef::SetTonalCenters ( const std::map< twobyte, twobyte > & values )

inline

Sets the table of tonal centers by number of sharps/flats.

Remarks

Finale allows your linear key signature to specify the tonal centers that correspond to each key signature from 1 sharp up to 7 sharps and 1 flat down to 7 flats. The number of sharps is given by a positive number and the number of flats by a negative number. Zero specifies the tonal center when no sharps or flats are present. These are the indices of the table.

The values that correspond to each index represents the pitch name that is the tonal center for that number of sharps or flats. Valid values are in the range 0..6, where C=0, D=1, E=2, F=3, G=4, A=5, B=6. Other values are not valid and may produce unpredictable results. The key signature takes care of any alterations (sharps or flats) on the pitch name, so all that's needed is the number corresponding to the pitch name itself.

A primary use case for SetTonalCenters would be to define one of the church modes that is not major or minor. For example, with Dorian mode, the tonal center when there are no sharps or flats is 1 (D). You would populate this array with the tonal centers for Dorian mode in keys containing from 7 flats up to 7 sharps. (See code example below.) Alternatively, you could start with the table returned by GetDefaultTonalCenters and add 1 (modulo 7) to each of the values in the table.

If you do not care about tonal centers, or if you are happy with major scale tonal centers, you do not need to populate this value at all. It is possible to populate only the sharp keys (plus no key signature) or only the flat keys. However, for linear key modes it is recommend to populate SetTonalCenters either with an empty table or the complete set of 15 values with index values from -7..+7.

local dorian_tonal_centers =
{
    -- (Accidentals in parentheses are in the key signature)
    [-7] = 1,   -- 7 flats, Dorian tonal center is D(b)
    [-6] = 5,   -- 6 flats, Dorian tonal center is A(b)
    [-5] = 2,   -- 5 flats, Dorian tonal center is E(b)
    [-4] = 6,   -- 4 flats, Dorian tonal center is B(b)
    [-3] = 3,   -- 3 flats, Dorian tonal center is F
    [-2] = 0,   -- 2 flats, Dorian tonal center is C
    [-1] = 4,   -- 1 flat,  Dorian tonal center is G
    [0] = 1,    -- 0 flats or sharps, Dorian tonal center is D
    [1] = 5,    -- 1 sharp,  Dorian tonal center is A
    [2] = 2,    -- 2 sharps, Dorian tonal center is E
    [3] = 6,    -- 3 sharps, Dorian tonal center is B
    [4] = 3,    -- 4 sharps, Dorian tonal center is F(#)
    [5] = 0,    -- 5 sharps, Dorian tonal center is C(#)
    [6] = 4,    -- 6 sharps, Dorian tonal center is G(#)
    [7] = 1,    -- 7 sharps, Dorian tonal center is D(#)
}
-- alternate method to calculate a table of Dorian tonal centers:
local dorian_tonal_centers = finale.FCCustomKeyModeDef.GetDefaultTonalCenters()
for k, v in pairs(dorian_tonal_centers)
    -- adding 1 moves the tonal center up from do to re
    dorian_tonal_centers[k] = (v + 1) % 7
end

Non-linear key modes only use the value at index 0, which gives the tonal center of the mode. Although you must supply indices 0..7 at a minimum, the values at indices 1..7 do not matter.

Lua-supported (also as property) (0.72)

Parameters

values

a table (Lua) or std::map (C++) with integer indices -7..+7 representing the number of flats or sharps and a value from 0..6 that corresponds to the pitch name that is the tonal center.

SetTotalChromaticSteps()

void FCCustomKeyModeDef::SetTotalChromaticSteps ( twobyte value )

inline

Sets the "Total Steps" value from the Key Step Map dialog.

The number of chromatic scale steps in your scale. For standard Western modes, this value is 12. If you are creating a microtonal scale, you would set this to the number of divisions of the octave. That is, for 31-EDO you would set this value to 31.

Remarks

The Finale UI limits this value to no more than 100. For predefined modes, this value should always be zero. Use FCKeySignature::CalcTotalChromaticSteps to get the number of chromatic steps for any mode, whether predefined or not.

Lua-supported (also as property) (0.72)