The DOM (document object model) for musx files. More...

Namespaces
namespace	details
	Classes in the DetailsPool.

namespace	header
	Document header classes are in this namespace.

namespace	options
	Classes in the OptionsPool.

namespace	others
	Classes in the OthersPool.

namespace	texts
	Classes in the TextsPool.

namespace	uuid
	Constants for all supported instruments (identified by UUID) in Finale.

Classes
class	Base
	Base class to enforce polymorphism across all DOM classes. More...

class	CommonClassBase
	Base class for classes that are commonly used among others, details, entries, and/or texts. They can be constructed in atypical contexts, so their Part and Sharing info is not meaningful. More...

class	ContainedClassBase
	Base class for classes that are contained by other classes. More...

class	DeferredReference
	Wraps a reference to an existing object or owns a temporary value if needed. More...

class	DetailsArray
	Template pattern for DetailsBase items consisting of an array of a single item. More...

class	DetailsBase
	Base class for all "details" types. More...

class	DetailsPool
	A pool that manages collections of `DetailsBase` objects, organized by XML node names and `Cmper` values. More...

class	Document
	Represents a document object that encapsulates the entire EnigmaXML structure. More...

class	Entry
	Represents an entry containing metadata and notes. More...

class	EntryDetailsBase
	Base class for all "details" types that use `entnum` rather than `cmper` and `cmper`. More...

class	EntryFrame
	Represents a vector of EntryInfo instances for a given frame, along with computed information. More...

class	EntryInfo
	Information an entry along with the entry. More...

class	EntryInfoPtr
	Wraps a frame of shared_ptr<const EntryInfo> and an index for per entry access. This class manages ownership of the frame so that any instance of it keeps the frame alive without the need for circular references. More...

class	EntryPool
	Entry pool. More...

struct	FontInfo
	Represents the default font settings for a particular element type. More...

class	InstrumentInfo
	Represents information about each instrument in the document. This is calculated from the staves, staff groups, and multistaff instrument groups. More...

class	integrity_error
	Exception for integrity errors. (Used when `MUSX_THROW_ON_INTEGRITY_CHECK_FAIL` is defined.) More...

struct	is_pool_type
	Type trait to determine if a class in a given pool. More...

struct	is_pool_type< DetailsPool, T >
	Pool type specialization for RegisteredDetails. More...

struct	is_pool_type< EntryPool, T >
	Pool type specialization for RegisteredEntries. More...

struct	is_pool_type< OptionsPool, T >
	Pool type specialization for RegisteredOptions. More...

struct	is_pool_type< OthersPool, T >
	Pool type specialization for RegisteredOthers. More...

struct	is_pool_type< TextsPool, T >
	Pool type specialization for RegisteredTexts. More...

class	KeySignature
	Shared key signature class that is contained in other classes. (See others::Measure) More...

class	LyricsLineInfo
	Contains information about a line of lyrics on a system. More...

class	LyricsSyllableInfo
	Contains the syllable information for a single syllable. (See texts::LyricsTextBase) More...

class	MusicRange
	Utility class that represents of a range of musical time. More...

class	MusxInstanceList
	Provides optional per-type extension methods for MusxInstanceList. More...

class	MusxInstanceList< others::StaffUsed >
	Specialization for others::StaffUsed that adds methods for processing the array as a whole. More...

class	MusxInstanceListBase
	A container of pooled shared object instances from an ObjectPool. More...

class	Note
	Represents a single note element in an entry. More...

class	NoteDetailsBase
	Base class note details. Note details are entry details associated with a note ID. More...

class	NoteInfoPtr
	Wraps an EntryInfo instance and a note index. More...

class	ObjectPool
	A pool that manages collections of `OthersBase` objects, organized by XML node names and `Cmper` values. More...

class	OptionsBase
	Base class for all "options" types. More...

class	OptionsPool
	A pool that manages collections of `OptionsBase` objects that have no Cmper value. More...

class	OthersArray
	Template pattern for OthersBase items consisting of an array of a single item. More...

class	OthersBase
	Base class for all "others" types. More...

class	OthersName
	Many element names are embedded directly in top-level xml tags. This encapsulates that pattern. More...

class	OthersPool
	A pool that manages collections of `OthersBase` objects. More...

struct	ShapeDefInstruction
	Helper functions and structs for decoding instruction data vectors in others::ShapeDef. More...

class	TextsBase
	Base class for all text blocks. More...

class	TextsPool
	Text pool. More...

class	TimeSignature
	Shared time signature class that is derived from other classes. (See others::Measure) More...

Typedefs
using	DocumentPtr = std::shared_ptr< Document >
	Shared `Document` pointer.

using	DocumentWeakPtr = std::weak_ptr< Document >
	Shared weak `Document` pointer.

using	Duration = std::pair< NoteType, unsigned >
	Expresses a duration as a NoteType and a number of dots (unsigned)

using	InstrumentMap = std::unordered_map< StaffCmper, InstrumentInfo >

using	Cmper = uint16_t
	Enigma "comperator" key type.

using	Inci = int16_t
	Enigma "incident" key type.

using	Evpu = int32_t
	EVPU value (288 per inch)

using	EvpuFloat = double
	EVPU fractional value (288.0 per inch)

using	Evpu16ths = int32_t
	1/16 of an EVPU.

using	Efix = int32_t
	EFIX value (64 per EVPU, 64*288=18432 per inch)

using	Edu = int32_t
	"Enigma Durational Units" value (1024 per quarter note)

using	EduFloat = double
	"Enigma Durational Units" floating point value (1024.0 per quarter note)

using	MeasCmper = int16_t
	Enigma meas Cmper (may be negative when not applicable)

using	StaffCmper = int16_t
	Enigma staff (staffId) Cmper (may be negative when not applicable)

using	SystemCmper = int16_t
	Enigma systems Cmper (may be negative when not applicable)

using	PageCmper = int16_t
	Enigma page Cmper (may be negative when not applicable)

using	ClefIndex = uint16_t
	Index into options::ClefOptions::clefDefs.

using	EntryNumber = int32_t
	Entry identifier.

using	NoteNumber = uint16_t
	Note identifier.

using	LayerIndex = unsigned int
	Layer index (valid values are 0..3)

using	BeamNumber = unsigned int
	A number where 1 corresponds to the primary (8th note) beam, 2 the 16th beam, 3 the 32nd beam, etc.

using	PercussionNoteTypeId = uint16_t
	multiple times in one layout. The rest are the "pure" note type. See percussion::PercussionNoteType.

template<typename T >
using	MusxInstance = std::shared_ptr< const T >
	Defines the type of a musx instance stored in a pool.

template<typename T >
using	MusxInstanceWeak = std::weak_ptr< const T >
	Defines a weak ptr to the type of a musx instance stored in a pool.

using	OptionsPoolPtr = std::shared_ptr< OptionsPool >
	Shared `OptionsPool` pointer.

using	OthersPoolPtr = std::shared_ptr< OthersPool >
	Shared `OthersPool` pointer.

using	DetailsPoolPtr = std::shared_ptr< DetailsPool >
	Shared `DetailsPool` pointer.

using	EntryPoolPtr = std::shared_ptr< EntryPool >
	Shared `EntryPool` pointer.

using	TextsPoolPtr = std::shared_ptr< TextsPool >
	Shared `OthersPool` pointer.

Enumerations
enum class	PartVoicingPolicy { Ignore , Apply }
	Controls whether Finale-style part voicing is applied when iterating entries via musx::dom::details::GFrameHoldContext. More...

enum class	AlignJustify { Left , Right , Center }
	Alignment and justification options for staff and group names. More...

enum class	ArrowheadPreset : int { SmallFilled = 1 , SmallOutline = 2 , SmallCurved = 3 , LargeCurved = 4 , MediumCurved = 5 }
	Finale-defined arrowhead presets. More...

enum class	CurveContourDirection { Auto , Down , Up }
	Curve contour direction for ties and slurs. More...

enum class	DateFormat : int { Short = 0 , Long = 1 , Abbrev = 2 }
	Date format options. This value is coded into the Enigma `date` insert when the page title is created. More...

enum class	DefaultClefType : ClefIndex { Treble = 0 , Alto = 1 , Tenor = 2 , Bass = 3 , Percussion = 4 , Treble8vb = 5 , Bass8vb = 6 , Baritone = 7 , FrenchViolin = 8 , BaritoneC = 9 , MezzoSoprano = 10 , Soprano = 11 , AltPercussion = 12 , Treble8va = 13 , Bass8va = 14 , Blank = 15 , Tab1 = 16 , Tab2 = 17 }
	Clef types used by default in Finale documents. The values correspond to indices into musx::dom::options::ClefOptions::clefDefs. Note that the user may change the clef list to any clefs the user wishes. These are only defaults, but they are frequently left unchanged. More...

enum class	LyricTextType { Verse , Chorus , Section }
	The lyric text type if this is a lyrics smart shape. More...

enum class	NoteType : Edu { Maxima = 0x8000 , Longa = 0x4000 , Breve = 0x2000 , Whole = EDU_PER_WHOLE_NOTE , Half = 0x0800 , Quarter = 0x0400 , Eighth = 0x0200 , Note16th = 0x0100 , Note32nd = 0x0080 , Note64th = 0x0040 , Note128th = 0x0020 , Note256th = 0x0010 , Note512th = 0x0008 , Note1024th = 0x0004 , Note2048th = 0x0002 , Note4096th = 0x0001 }
	Enum class representing note types based on EDU values. More...

enum class	ShowClefMode { WhenNeeded , Never , Always }
	Enum representing the clef display mode for a frame. More...

enum class	KnownShapeDefType { Unrecognized , Blank , TenutoMark , SlurTieCurveRight , SlurTieCurveLeft , PedalArrowheadDown , PedalArrowheadUp , PedalArrowheadShortUpDownLongUp , PedalArrowheadLongUpDownShortUp }
	Enumerates the shape types we can recognize semantically. More...

enum class	ShapeDefInstructionType { Undocumented , Bracket , CloneChar , ClosePath , CurveTo , DrawChar , Ellipse , EndGroup , ExternalGraphic , FillAlt , FillSolid , GoToOrigin , GoToStart , LineWidth , Rectangle , RLineTo , RMoveTo , SetArrowhead , SetBlack , SetDash , SetFont , SetGray , SetWhite , Slur , StartGroup , StartObject , Stroke , VerticalMode }
	Defines the instruction types for Shape Designer shapes. More...

Functions
Duration	calcDurationInfoFromEdu (Edu duration)
	Calculates the NoteType and number of dots in an Edu value.

unsigned	calcNumberOfBeamsInEdu (Edu duration)
	Returns the number of beams implied by an EDU duration.

Variables
constexpr Cmper	MUSX_GLOBALS_CMPER = 65534
	The prefs cmper for global variables (used sparingly since Finale 26.2)

constexpr int	MAX_LAYERS = 4
	The maximum number of music layers in a Finale document.

constexpr int	MAX_ALTERATIONS = 7
	Maximum absolute value for chromatic alterations supported in Finale.

constexpr Cmper	SCORE_PARTID = 0
	The part id of the score.

constexpr double	EVPU_PER_INCH = 288.0
	Number of Evpu units per inch.

constexpr double	EVPU_PER_POINT = 4.0
	Number of Evpu units per 72 DPI point.

constexpr double	EVPU_PER_MM = EVPU_PER_INCH / 25.4
	Number of Evpu units per millimeter.

constexpr double	EVPU_PER_SPACE = 24.0
	Number of Evpu units per space (spatium)

constexpr double	EFIX_PER_EVPU = 64.0
	Number of Efix units per Evpu.

constexpr double	EFIX_PER_SPACE = EVPU_PER_SPACE * EFIX_PER_EVPU
	Number of Efix units per space (spatium)

constexpr Edu	EDU_PER_WHOLE_NOTE = 0x1000
	Number of Edu units per whole note.

constexpr Cmper	BASE_SYSTEM_ID = 0

constexpr Cmper	STAFF_SET_1_SYSTEM_ID = 65500

constexpr Cmper	STUDIO_VIEW_SYSTEM_ID = 65400
	The system cmper for Studio View. Studio View has entries for every click in the click track.

constexpr Cmper	SPECIAL_PART_EXTRACTION_SYSTEM_ID = 65528

constexpr Cmper	TEMP_SYSTEM_ID = 65529

constexpr int	MAX_CUE_PERCENTAGE = 90
	Arbitrary value that determines the max scaling value for cue notes. This could be configurable in the future.

template<typename Pool , typename T >
constexpr bool	is_pool_type_v = is_pool_type<Pool, T>::value
	Value shortcut for is_pool_type.

Detailed Description

The DOM (document object model) for musx files.

classes representing the musx document

Typedef Documentation

◆ InstrumentMap

using musx::dom::InstrumentMap = typedef std::unordered_map<StaffCmper, InstrumentInfo>

A list of instruments, which may be single- or multi-staff

◆ MusxInstance

template<typename T >

using musx::dom::MusxInstance = typedef std::shared_ptr<const T>

Defines the type of a musx instance stored in a pool.

Template Parameters

T	The musx type

◆ MusxInstanceWeak

template<typename T >

using musx::dom::MusxInstanceWeak = typedef std::weak_ptr<const T>

Defines a weak ptr to the type of a musx instance stored in a pool.

Template Parameters

T	The musx type

Enumeration Type Documentation

◆ AlignJustify

enum class musx::dom::AlignJustify

strong

Alignment and justification options for staff and group names.

Enumerator
Left	Left alignment or justification (the default value.)
Right	Right alignment.
Center	Center alignment.

◆ ArrowheadPreset

enum class musx::dom::ArrowheadPreset : int

strong

Finale-defined arrowhead presets.

These values correspond to a fixed set of arrowhead shapes built into Finale. The numeric values are significant and match Finale’s internal preset IDs. The same preset is used for both the start and end of a line: the arrowhead is automatically mirrored based on whether it appears at the line start or the line end.

The presets differ only by shape and scale. Their sizes are fixed and not user-adjustable:

Small arrowheads are just under 1 staff space tall.
The medium curved arrowhead is nearly 2.5 staff spaces tall.
The large curved arrowhead is roughly 4 staff spaces tall. In each case, the arrowhead length appears equal to its height.

Enumerator
SmallFilled	Small filled arrowhead preset (≈1 staff space tall).
SmallOutline	Small outlined arrowhead preset (≈1 staff space tall).
SmallCurved	Small curved-back arrowhead preset (≈1 staff space tall).
LargeCurved	Large curved-back arrowhead preset (≈4 staff spaces tall).
MediumCurved	Medium curved-back arrowhead preset (≈2.5 staff spaces tall).

◆ CurveContourDirection

enum class musx::dom::CurveContourDirection

strong

Curve contour direction for ties and slurs.

Enumerator
Auto	contour is automatic, indeterminate, or does not apply
Down	contour is curved downward (tips face up)
Up	contour is curved upward (tips face down)

◆ DateFormat

enum class musx::dom::DateFormat : int

strong

Date format options. This value is coded into the Enigma date insert when the page title is created.

Enumerator
Short	Short date format, based on locale. US format is MM/DD/YY (Default value may not appear in the xml)
Long	Long date format, based on locale. US format is Month DD, YYYY.
Abbrev	Abbreviated date format, based on locale. US format is Mon DD, YYYY.

◆ DefaultClefType

enum class musx::dom::DefaultClefType : ClefIndex

strong

Clef types used by default in Finale documents. The values correspond to indices into musx::dom::options::ClefOptions::clefDefs. Note that the user may change the clef list to any clefs the user wishes. These are only defaults, but they are frequently left unchanged.

Enumerator
Treble	G clef, standard treble.
Alto	C clef, centered on third line (Alto clef).
Tenor	C clef, centered on fourth line (Tenor clef).
Bass	F clef, standard bass.
Percussion	Percussion clef, open rectangle (no pitch).
Treble8vb	G clef, sounds one octave lower (8vb).
Bass8vb	F clef, sounds one octave lower (8vb).
Baritone	F clef on third line (Baritone clef).
FrenchViolin	G clef placed on first line (French violin clef).
BaritoneC	C clef on fifth line (Baritone clef).
MezzoSoprano	C clef on second line (Mezzo-soprano clef).
Soprano	C clef on first line (Soprano clef).
AltPercussion	Alternate percussion clef, heavy vertical hash marks (no pitch).
Treble8va	G clef, sounds one octave higher (8va).
Bass8va	F clef, sounds one octave higher (8va).
Blank	Blank clef (invisible, no symbol).
Tab1	Tablature clef (5 lines).
Tab2	Tablature clef (5 lines, alternative style).

◆ KnownShapeDefType

enum class musx::dom::KnownShapeDefType

strong

Enumerates the shape types we can recognize semantically.

Enumerator
Unrecognized	Fallback when recognition fails.
Blank	A blank shape containing no instructions.
TenutoMark	A horizontal tenuto mark, typically used as an articulation symbol.
SlurTieCurveRight	Horizontal slur or tie shape curving toward the right.
SlurTieCurveLeft	Horizontal slur or tie shape curving toward the left.
PedalArrowheadDown	Downward wedge used for pedal markings.
PedalArrowheadUp	Upward wedge used for pedal markings.
PedalArrowheadShortUpDownLongUp	Pedal arrowhead: short up, down, long up.
PedalArrowheadLongUpDownShortUp	Pedal arrowhead: long up, down, short up.

◆ LyricTextType

enum class musx::dom::LyricTextType

strong

The lyric text type if this is a lyrics smart shape.

Enumerator
Verse	The assignment is to a Verse lyrics text block.
Chorus	The assignment is to a Chorus lyrics text block.
Section	The assignment is to a Section lyrics text block.

◆ NoteType

enum class musx::dom::NoteType : Edu

strong

Enum class representing note types based on EDU values.

The values are expressed in hexadecimal.

◆ PartVoicingPolicy

enum class musx::dom::PartVoicingPolicy

strong

Controls whether Finale-style part voicing is applied when iterating entries via musx::dom::details::GFrameHoldContext.

Enumerator

Ignore

Default. Part voicing is ignored entirely. All layers in a staff are visible to all parts, and entries behave as if no part-voicing definitions exist.

Apply

Apply Finale’s voiced-part interpretation. When enabled, entry iteration filters layers according to the active part voicing, and individual notes may be included or excluded based on voicing rules. Callers that operate at the note level should use NoteInfoPtr::calcIsIncludedInVoicing to test note visibility. If all notes in an entry are excluded by voicing, then EntryInfoPtr::calcDisplaysAsRest returns true for that entry.

◆ ShapeDefInstructionType

enum class musx::dom::ShapeDefInstructionType

strong

Defines the instruction types for Shape Designer shapes.

Enumerator
Undocumented	catch-all for possible undocumented instruction tags.
Bracket	bracket data items: (1) bracket type (piano brace, bracket, etc.) Note This does not actually draw the bracket. It simply indicates the start of automatically created instructions that draw the bracket, ending with ClosePath.
CloneChar	cloned character for horizontal lines (e.g. trills) data items: (5) 0, 1: x and y of endpoint (y ignored) 2: unused 3: baseline shift in EMs (1/1000 of current point size) 4: the 32-bit codepoint of the character to clone
ClosePath	close path data items: none
CurveTo	relative curveto (bezier) data items: (6) 2 bezier control points and an end point
DrawChar	draw character (current font) data items: (1) The 32-bit codepoint of the character to draw
Ellipse	ellipse data items: (2) width and height of bounding rectangle current point is lower left corner
EndGroup	marks the end of a group data items: none
ExternalGraphic	external graphic (eps, pict, tiff, etc) data items: (3) width, height of graphic, cmper of corresponding graphic. See others::PageGraphicAssign::graphicCmper for explanation.
FillAlt	fill path (alternating, or even-odd rule) data items: none
FillSolid	fill path (solid, or non-zero winding rule) data items: none
GoToOrigin	go to origin point data items: none
GoToStart	go to start of path, same as close path for filled shapes data items: none
LineWidth	line width data items: (1) the new line width in Efix
Rectangle	rectangle data items: (2) width and height of rectangle current point is lower left corner
RLineTo	relative lineto data items: (2) X, Y endpoint
RMoveTo	relative moveto data items: (2) X, Y endpoint
SetArrowhead	set arrowhead data items: (4) startArrowID, endArrowID, startFlags, endFlags The meaning of the flags is currently untested, but they are likely used to specify either a built-in ArrowheadPreset or custom arrowhead (which is also a others::ShapeDef).
SetBlack	set black: equivalent to `SetGray(0)` data items: none
SetDash	set dash data items: (2) dash length, space between dashes
SetFont	set font data items: (3) font id, size, efx
SetGray	set gray data items: (1) gray value between 1 and 100 where 0=black and 100=white
SetWhite	set white: equivalent to `SetGray(100)` data items: none
Slur	slur data items: (6) 2 bezier control points and an end point like curve, except 2 more control points are deduced from a global slur thickness setting
StartGroup	start group data items: (11) same as StartObject
StartObject	start object data items: (11) with indices as noted: 0, 1: origin point (x, y) 2..5: bounding rect (left, top, right, bottom) 6, 7: x and y transform (scale ratio * 1000) 8: rotation transform 9,10: unused/undocumented
Stroke	stroke path data items: none
VerticalMode	pen vertical mode data items: (1) 1=center, 2=left, 3=right tells line-drawing commands to draw the line center, on the left, or on the right of the drawing coordinates specified.

◆ ShowClefMode

enum class musx::dom::ShowClefMode

strong

Enum representing the clef display mode for a frame.

Enumerator
WhenNeeded	Clef is displayed only when needed (the default).
Never	Clef is never displayed. (xml value is "hidden")
Always	Clef is always displayed. (xml value is "forced")

Function Documentation

◆ calcDurationInfoFromEdu()

Duration musx::dom::calcDurationInfoFromEdu ( Edu duration )

Calculates the NoteType and number of dots in an Edu value.

Parameters

duration The Edu duration to check.

Returns

A std::pair containing:

NoteType: The note type (Whole, Quarter, Eighth, etc.)
unsigned: The number of augmentation dots

Exceptions

std::invalid_argument if the duration is out of valid range (> 1 and < 0x10000).

◆ calcNumberOfBeamsInEdu()

unsigned musx::dom::calcNumberOfBeamsInEdu ( Edu duration )

Returns the number of beams implied by an EDU duration.

Uses calcDurationInfoFromEdu to determine the base note value. Durations greater than a quarter note return 0 flags. Dots are ignored.

Variable Documentation

◆ BASE_SYSTEM_ID

constexpr Cmper musx::dom::BASE_SYSTEM_ID = 0

constexpr

The base system cmper that gives a list of all available staves and their score order (others::StaffUsed cmper) Generally you should avoid using this directly and instead use Document::calcScrollViewCmper or Document::getScrollViewStaves for the list of scroll view staves.

◆ SPECIAL_PART_EXTRACTION_SYSTEM_ID

constexpr Cmper musx::dom::SPECIAL_PART_EXTRACTION_SYSTEM_ID = 65528

constexpr

The system comper for Special Part Extraction (mostly obsolete in Finale 27.) See others::PartGlobals::specialPartExtractionIUList for more information.

◆ STAFF_SET_1_SYSTEM_ID

constexpr Cmper musx::dom::STAFF_SET_1_SYSTEM_ID = 65500

constexpr

The system cmoper for the first Scroll View staff set. Add 0..7 to this value to get one of the 8 staff sets.

◆ TEMP_SYSTEM_ID

constexpr Cmper musx::dom::TEMP_SYSTEM_ID = 65529

constexpr

This is a scratch value. Finale and/or plugins can use this systemId to aggregate an arbitary list of staves for batch processing. It is possible that a plugin might have saved a file with it.

Namespaces

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ InstrumentMap

◆ MusxInstance

◆ MusxInstanceWeak

Enumeration Type Documentation

◆ AlignJustify

◆ ArrowheadPreset

◆ CurveContourDirection

◆ DateFormat

◆ DefaultClefType

◆ KnownShapeDefType

◆ LyricTextType

◆ NoteType

◆ PartVoicingPolicy

◆ ShapeDefInstructionType

◆ ShowClefMode

Function Documentation

◆ calcDurationInfoFromEdu()

◆ calcNumberOfBeamsInEdu()

Variable Documentation

◆ BASE_SYSTEM_ID

◆ SPECIAL_PART_EXTRACTION_SYSTEM_ID

◆ STAFF_SET_1_SYSTEM_ID

◆ TEMP_SYSTEM_ID