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

#include <Document.h>

Public Member Functions
HeaderPtr &	getHeader ()
	Retrieves the header.

const HeaderPtr &	getHeader () const
	Retrieves the const header.

OptionsPoolPtr &	getOptions ()
	Retrieves the options pool.

const OptionsPoolPtr &	getOptions () const
	Retrieves the const options pool.

OthersPoolPtr &	getOthers ()
	Retrieves the others pool.

const OthersPoolPtr &	getOthers () const
	Retrieves the const others pool.

DetailsPoolPtr &	getDetails ()
	Retrieves the details pool.

const DetailsPoolPtr &	getDetails () const
	Retrieves the const others pool.

EntryPoolPtr &	getEntries ()
	Retrieves the entry pool.

const EntryPoolPtr &	getEntries () const
	Retrieves the entry others pool.

TextsPoolPtr &	getTexts ()
	Retrieves the texts pool.

const TextsPoolPtr &	getTexts () const
	Retrieves the const texts pool.

PartVoicingPolicy	getPartVoicingPolicy () const
	Retrieves the document's part voicing policy.

std::optional< double >	getScoreDurationSeconds () const
	Returns the score playback duration in seconds, if provided by NotationMetadata.xml.

const EmbeddedGraphicsMap &	getEmbeddedGraphics () const
	Returns all embedded graphics keyed by graphic cmper.

constexpr Cmper	calcScrollViewCmper (Cmper partId) const noexcept
	Returns the Scroll View Cmper for the given `partId`.

MusxInstanceList< others::StaffUsed >	getScrollViewStaves (Cmper partId) const
	Returns the Scroll View staves for the given `partId`.

MusxInstanceList< others::StaffUsed >	getStudioViewStaves (Cmper partId) const
	Returns the Studio View staves for the given `partId`. Normally this is only one staff and is invariant between parts.

std::optional< KnownShapeDefType >	getCachedShapeRecognition (Cmper shapeCmper) const
	Retrieves a cached shape recognition result, if available.

void	setCachedShapeRecognition (Cmper shapeCmper, KnownShapeDefType type) const
	Stores a shape recognition result in the cache.

std::optional< bool >	getCachedFontIsSMuFL (Cmper fontId) const
	Retrieves a cached SMuFL font recognition result, if available.

void	setCachedFontIsSMuFL (Cmper fontId, bool isSmufl) const
	Stores a SMuFL font recognition result in the cache.

MusxInstance< others::Page >	calcPageFromMeasure (Cmper partId, MeasCmper measureId) const
	Searches pages to find the page that contains the measure.

MusxInstance< others::StaffSystem >	calcSystemFromMeasure (Cmper partId, MeasCmper measureId) const
	Searches systems to find the system that contains the measure.

int	getMaxBlankPages () const
	Returns the maximum number of blank pages in any part. This is calculated by factory::DocumentFactory::create.

const InstrumentMap &	getInstruments () const
	Returns the instrument map for this document. It is computed by the factory.

const std::optional< InstrumentMap > &	getInstrumentsIfAvailable () const noexcept
	Returns the optional instrument map, which is empty until the map has been constructed.

const std::optional< std::filesystem::path > &	getSourcePath () const
	Returns the path to the musx (or EnigmaXML) file used to create this document, if provided.

std::optional< std::filesystem::path >	resolveExternalGraphicPath (Cmper fileDescId) const
	Resolve an external graphic path using SCORE_PARTID.

const InstrumentInfo &	getInstrumentForStaff (StaffCmper staffId) const
	Get the instrument info for the given staffId.

std::optional< InstrumentInfo >	getInstrumentForStaff (Cmper partId, StaffCmper staffId) const
	Get the instrument info for the given staffId in the specified part.

std::optional< RehearsalMarkInfo >	getRehearsalMarkInfo (MeasCmper measureId, Cmper textExpressionId) const
	Returns the rehearsal mark info for a rehearsal mark text expression assignment.

InstrumentMap	createInstrumentMap (Cmper forPartId) const
	Builds an instrument map for the specified linked part ID.

bool	calcHasVaryingSystemStaves (Cmper forPartId) const
	Calculate if the current score/part has staves that differ from system to system.

MusicRange	calcEntireDocument () const
	Calcuate a MusicRange instance for the entire document.

std::vector< MeasCmper >	calcJumpFromMeasures (Cmper partId, MeasCmper currentMeasure) const
	Calculates the measures from which playback jumped into `currentMeasure`.

bool	iterateEntries (Cmper partId, std::function< bool(const EntryInfoPtr &)> iterator) const
	Iterate all entries in the document by staff and then measure. This function wraps MusxInstanceList<others::StaffUsed>::iterateEntries.

Friends
class	musx::factory::DocumentFactory

Detailed Description

Represents a document object that encapsulates the entire EnigmaXML structure.

Member Function Documentation

◆ calcHasVaryingSystemStaves()

bool musx::dom::Document::calcHasVaryingSystemStaves ( Cmper forPartId ) const

Calculate if the current score/part has staves that differ from system to system.

Parameters

forPartId The linked score or part ID to check.

◆ calcJumpFromMeasures()

std::vector< MeasCmper > musx::dom::Document::calcJumpFromMeasures	(	Cmper	partId,
		MeasCmper	currentMeasure
	)		const

Calculates the measures from which playback jumped into currentMeasure.

This function inspects repeat endings and text repeats to detect jumps that land on the specified measure. The result is the measure immediately preceding the jump origin, when determinable. It is intended for jump-aware tie continuation logic.

Parameters

partId	The linked part to inspect (use SCORE_PARTID for score).
currentMeasure	The measure that playback has jumped into.

Returns: A list of measures immediately preceding jump origins, ordered by preference (forward jump origins first in ascending order, then backward origins in descending order).

◆ calcPageFromMeasure()

MusxInstance< others::Page > musx::dom::Document::calcPageFromMeasure	(	Cmper	partId,
		MeasCmper	measureId
	)		const

Searches pages to find the page that contains the measure.

Returns: The page, or nullptr if the part's page layout is unavailable or the measure is not found.

Parameters

partId	the linked part to search
measureId	the measure to find

◆ calcScrollViewCmper()

constexpr Cmper musx::dom::Document::calcScrollViewCmper ( Cmper partId ) const

inlineconstexprnoexcept

Returns the Scroll View Cmper for the given partId.

Parameters

partId The linked part to check.

◆ calcSystemFromMeasure()

MusxInstance< others::StaffSystem > musx::dom::Document::calcSystemFromMeasure	(	Cmper	partId,
		MeasCmper	measureId
	)		const

Searches systems to find the system that contains the measure.

Returns: The system, or nullptr if the part's page layout is unavailable or the measure is not found.

Parameters

partId	the linked part to search
measureId	the measure to find

◆ createInstrumentMap()

InstrumentMap musx::dom::Document::createInstrumentMap ( Cmper forPartId ) const

Builds an instrument map for the specified linked part ID.

This routine detects instrument groupings in three stages:

Defined multi-staff instruments (via multiStaffInstId).
Visually bracketed staves with matching instrument UUIDs.
Remaining single staves as individual instruments.

This is especially important for supporting legacy .musx files created before multi-staff instruments were defined explicitly.

Parameters

forPartId The linked part for which to create the map.

◆ getInstrumentForStaff() [1/2]

std::optional< InstrumentInfo > musx::dom::Document::getInstrumentForStaff	(	Cmper	partId,
		StaffCmper	staffId
	)		const

Get the instrument info for the given staffId in the specified part.

Parameters

partId	The linked part to search.
staffId	The staffId to find.

Returns: The instrument info for the given staff, or std::nullopt if the staff is not mapped to an instrument.

◆ getInstrumentForStaff() [2/2]

const InstrumentInfo & musx::dom::Document::getInstrumentForStaff ( StaffCmper staffId ) const

Get the instrument info for the given staffId.

Parameters

staffId The staffId to find.

◆ getInstrumentsIfAvailable()

const std::optional< InstrumentMap > & musx::dom::Document::getInstrumentsIfAvailable ( ) const

inlinenoexcept

Returns the optional instrument map, which is empty until the map has been constructed.

This supports interpretation helpers that can provide a useful fallback while the document factory is still resolving relationships. Call getInstruments when the map is required.

◆ getRehearsalMarkInfo()

std::optional< RehearsalMarkInfo > musx::dom::Document::getRehearsalMarkInfo	(	MeasCmper	measureId,
		Cmper	textExpressionId
	)		const

Returns the rehearsal mark info for a rehearsal mark text expression assignment.

Returns: The rehearsal mark info or std::nullopt if none.

◆ getScrollViewStaves()

MusxInstanceList< others::StaffUsed > musx::dom::Document::getScrollViewStaves ( Cmper partId ) const

Returns the Scroll View staves for the given partId.

Parameters

partId The linked part to check.

◆ getStudioViewStaves()

MusxInstanceList< others::StaffUsed > musx::dom::Document::getStudioViewStaves ( Cmper partId ) const

Returns the Studio View staves for the given partId. Normally this is only one staff and is invariant between parts.

Parameters

partId The linked part to check.

◆ iterateEntries()

bool musx::dom::Document::iterateEntries	(	Cmper	partId,
		std::function< bool(const EntryInfoPtr &)>	iterator
	)		const

Iterate all entries in the document by staff and then measure. This function wraps MusxInstanceList<others::StaffUsed>::iterateEntries.

Parameters

partId	The linked part id to iterate. (Use SCORE_PARTID to iterate the score.)
iterator	The callback function.

Returns: True if iteration completed. False if the iterator returned false and exited early.

◆ resolveExternalGraphicPath()

std::optional< std::filesystem::path > musx::dom::Document::resolveExternalGraphicPath ( Cmper fileDescId ) const

Resolve an external graphic path using SCORE_PARTID.

Parameters

fileDescId The FileDescription cmper associated with the graphic.

Returns: A resolved path if the file can be located, otherwise std::nullopt.

Public Member Functions

Friends

Detailed Description

Member Function Documentation

◆ calcHasVaryingSystemStaves()

◆ calcJumpFromMeasures()

◆ calcPageFromMeasure()

◆ calcScrollViewCmper()

◆ calcSystemFromMeasure()

◆ createInstrumentMap()

◆ getInstrumentForStaff() [1/2]

◆ getInstrumentForStaff() [2/2]

◆ getInstrumentsIfAvailable()

◆ getRehearsalMarkInfo()

◆ getScrollViewStaves()

◆ getStudioViewStaves()

◆ iterateEntries()

◆ resolveExternalGraphicPath()