musx::dom Namespace Reference

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	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	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	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	ShowClefMode { WhenNeeded , Never , Always }
	Enum representing the clef display mode for a frame. More...
enum class	KnownShapeDefType { Blank , TenutoMark }
	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
std::pair< NoteType, unsigned >	calcNoteInfoFromEdu (Edu duration)
	Calculates the NoteType and number of dots in an Edu value.
unsigned	calcNumberOfBeamsInEdu (Edu duration)
	Calculates the number of beams or flags in the Edu value.

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 Cmper	BASE_SYSTEM_ID = 0
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 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

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
Blank	A blank shape containing no instructions.
TenutoMark	A horizontal tenuto mark, typically used as an articulation symbol.

NoteType

enum class musx::dom::NoteType : Edu

strong

Enum class representing note types based on EDU values.

The values are expressed in hexadecimal.

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 only used to specify built-in vs. custom arrowhead
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

calcNoteInfoFromEdu()

std::pair< NoteType, unsigned > musx::dom::calcNoteInfoFromEdu

(

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

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.