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

#include <Entries.h>

Inheritance diagram for musx::dom::EntryFrame:

Classes
struct	TupletInfo
	class to track tuplets in the frame More...

Public Member Functions
	EntryFrame (const details::GFrameHoldContext &gfhold, LayerIndex layerIndex, util::Fraction timeStretch, const MusxInstance< others::StaffComposite > &startStaff)
	Constructor function.

DocumentPtr	getDocument () const
	Get the document for the entry frame.

const details::GFrameHoldContext &	getContext () const
	Get the frame context for this frame.

Cmper	getRequestedPartId () const
	Get the requested part ID for the entry frame.

StaffCmper	getStaff () const
	Get the staff for the entry.

MeasCmper	getMeasure () const
	Get the measure for the entry frame.

LayerIndex	getLayerIndex () const
	Get the layer index (0..3) of the entry frame.

MusxInstance< others::LayerAttributes >	getLayerAttributes () const
	Get the LayerAttributes for this entry frame.

util::Fraction	getTimeStretch () const
	Get the time stretch in this frame. Rather than accessing this value directly, consider using EntryInfoPtr::calcGlobalElapsedDuration or EntryInfoPtr::calcGlobalActualDuration instead.

const std::vector< std::shared_ptr< const EntryInfo > > &	getEntries () const
	Get the entry list.

EntryInfoPtr	getFirstInVoice (int voice) const
	Returns the first entry in the specified v1/v2 or null if none.

EntryInfoPtr	getLastInVoice (int voice) const
	Returns the last entry in the specified v1/v2 or null if none.

EntryInfoPtr::InterpretedIterator	getFirstInterpretedIterator (int voice, bool remapBeamOverBarlineEntries=true) const
	Returns a workaround-aware iterator at the first entry in the specified voice.

void	addEntry (const std::shared_ptr< const EntryInfo > &entry)
	Add an entry to the list.

std::shared_ptr< const EntryFrame >	getNext () const
	Gets the entry frame for the next measure with the same staff and layer.

std::shared_ptr< const EntryFrame >	getPrevious () const
	Gets the entry frame for the previous measure with the same staff and layer.

MusxInstance< others::StaffComposite >	getStartStaffInstance () const
	Gets the staff at eduPosition 0 without needing to create it again.

MusxInstance< others::StaffComposite >	createCurrentStaff (Edu eduPosition, const std::optional< StaffCmper > &forStaffId=std::nullopt) const
	Creates a current StaffComposite for the entry frame.

MusxInstance< others::Measure >	getMeasureInstance () const
	Get the measure instance.

bool	calcIsCueFrame (bool includeVisibleInScore=false) const
	Calculates if this entry frame is part of a cue.

bool	calcAreAllEntriesHiddenInFrame () const
	Calculates if this all notes in the frame are hidden. This routine only checks that entries are individually hidden. The caller must separately check others::Staff::calcAlternateNotationHidesEntries according to its specific needs. For example, to determine if a layer is hidden for the purposes of checking validity of layer attributes, only the staff at edu position 0 should be checked.

EntryInfoPtr	calcNearestEntry (util::Fraction position, bool findExact=true, std::optional< bool > matchVoice2=std::nullopt, util::Fraction atGraceNoteDuration=0) const
	Calculates the nearest non-grace-note entry at the given `position`.

bool	iterateEntries (std::function< bool(const EntryInfoPtr &)> iterator) const
	Iterates the entries for the specified layer in this EntryFrame from left to right.

Public Attributes
std::vector< TupletInfo >	tupletInfo
	A list of the tuplets in the frame and their calculated starting and ending information.

MusxInstance< KeySignature >	keySignature
	This can be different than the measure key sig if the staff has independent key signatures.

util::Fraction	measureStaffDuration
	The duration of the measure in staff duration units.

util::Fraction	maxElapsedStaffDuration

Detailed Description

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

Its pointers are owned by EntryInfoPtr

Constructor & Destructor Documentation

◆ EntryFrame()

musx::dom::EntryFrame::EntryFrame	(	const details::GFrameHoldContext &	gfhold,
		LayerIndex	layerIndex,
		util::Fraction	timeStretch,
		const MusxInstance< others::StaffComposite > &	startStaff
	)

inlineexplicit

Constructor function.

Parameters

gfhold	The details::GFrameHoldContext instance creating this EntryFrame.
layerIndex	The LayerIndex (0..3) of the entry frame.
timeStretch	The ratio of global Edu to staff edu.
startStaff	The staff at the start of the measure containing this EntryFrame.

Member Function Documentation

◆ calcAreAllEntriesHiddenInFrame()

bool musx::dom::EntryFrame::calcAreAllEntriesHiddenInFrame ( ) const

Calculates if this all notes in the frame are hidden. This routine only checks that entries are individually hidden. The caller must separately check others::Staff::calcAlternateNotationHidesEntries according to its specific needs. For example, to determine if a layer is hidden for the purposes of checking validity of layer attributes, only the staff at edu position 0 should be checked.

Returns: true if all entries in the frame are hidden.

Todo:: check if the entry is hidden by voiced parts.

◆ calcIsCueFrame()

bool musx::dom::EntryFrame::calcIsCueFrame ( bool includeVisibleInScore = false ) const

Calculates if this entry frame is part of a cue.

Todo:: Revisit this algorithm if needed. The current algorithm is chosen to be mostly accurate while being fast to compute when there is no cue.

Parameters

includeVisibleInScore If true, include cues that are visible in the score.

Returns: true if all entries in the frame are either cue entries or hidden.

◆ calcNearestEntry()

EntryInfoPtr musx::dom::EntryFrame::calcNearestEntry	(	util::Fraction	position,
		bool	findExact = `true`,
		std::optional< bool >	matchVoice2 = `std::nullopt`,
		util::Fraction	atGraceNoteDuration = `0`
	)		const

Calculates the nearest non-grace-note entry at the given position.

Parameters

position	The measure position to find.
findExact	If true, only find an entry that matches to within 1 evpu. Otherwise find the closest entry in the measure.
matchVoice2	If specified, the value of Entry::voice2 must match the specified value.
atGraceNoteDuration	Match on this grace note duration. When it is zero, grace notes are skipped.

Returns: The entry if found, otherwise nullptr.

◆ createCurrentStaff()

MusxInstance< others::StaffComposite > musx::dom::EntryFrame::createCurrentStaff	(	Edu	eduPosition,
		const std::optional< StaffCmper > &	forStaffId = `std::nullopt`
	)		const

Creates a current StaffComposite for the entry frame.

Parameters

eduPosition	The Edu position for which to create the staff.
forStaffId	Specifies optional staff ID. If supplied, it overrides the entry's staff ID. (Useful when notes are cross-staffed.)

◆ getFirstInterpretedIterator()

EntryInfoPtr::InterpretedIterator musx::dom::EntryFrame::getFirstInterpretedIterator	(	int	voice,
		bool	remapBeamOverBarlineEntries = `true`
	)		const

Returns a workaround-aware iterator at the first entry in the specified voice.

The returned iterator begins forward traversal at the first raw entry for the given voice (1 or 2) and applies the workaround rules described in EntryInfoPtr::InterpretedIterator.

Use EntryInfoPtr::InterpretedIterator::getNext to advance.

Parameters

voice	Must be 1 or 2.
remapBeamOverBarlineEntries	Controls how mid-system "beam over barline" workarounds created by Finale's Beam Over Barline plugin are presented by this iterator.

Background: one way the plugin encodes a beam that crosses a barline is by cramming all visible continuation notes into the frame where the beam starts. The continuation entries that would normally appear in later measures are then hidden in their source measures. As a result, the raw data contains:

A cluster of visible continuation entries in the starting frame, and
Hidden source entries in the subsequent measures where those notes would logically belong.

musxdom can handle this workaround in two ways:

**(1) Remap continuation entries to their logical measures (default: true)** When remapBeamOverBarlineEntries is true, the iterator presents each hidden source entry as its corresponding visible continuation entry, effectively remapping the continuation notes back into their logical source measures. In other words, hidden source entries are not skipped; they are substituted with their display-entry counterparts and returned from the iterator as if Finale had stored them in their proper measures. In this mode, callers must use EntryInfoPtr::InterpretedIterator::calcIsPastLogicalEndOfFrame to determine the logical end of each frame so as not to encounter the physically crammed display entries where they appear in the raw data.

**(2) Process raw frames and skip hidden source entries in the caller (set to false)** When remapBeamOverBarlineEntries is false, the iterator presents the entries exactly as they appear in the raw data: the visible continuation entries remain in the starting frame, and the hidden source entries appear in the subsequent measures. In this mode, callers are responsible for ignoring the hidden source entries, because their visible counterparts were already handled when the starting measure was processed. Callers should not use EntryInfoPtr::InterpretedIterator::calcIsPastLogicalEndOfFrame for iteration termination in this mode; instead they should exhaust the frame using a structural validity check (such as operator bool on the iterator).

Returns: A InterpretedIterator positioned at the first usable entry, or an empty iterator if no usable entry exists.

◆ getFirstInVoice()

EntryInfoPtr musx::dom::EntryFrame::getFirstInVoice ( int voice ) const

Returns the first entry in the specified v1/v2 or null if none.

Parameters

voice Must be 1 or 2.

◆ getLastInVoice()

EntryInfoPtr musx::dom::EntryFrame::getLastInVoice ( int voice ) const

Returns the last entry in the specified v1/v2 or null if none.

Parameters

voice Must be 1 or 2.

◆ getNext()

std::shared_ptr< const EntryFrame > musx::dom::EntryFrame::getNext ( ) const

Gets the entry frame for the next measure with the same staff and layer.

Returns: Frame or nullpter if the next measure has no matching frame.

◆ getPrevious()

std::shared_ptr< const EntryFrame > musx::dom::EntryFrame::getPrevious ( ) const

Gets the entry frame for the previous measure with the same staff and layer.

Returns: Frame or nullpter if the previous measure has no matching frame,

◆ iterateEntries()

bool musx::dom::EntryFrame::iterateEntries ( std::function< bool(const EntryInfoPtr &)> iterator ) const

Iterates the entries for the specified layer in this EntryFrame from left to right.

Parameters

iterator The callback function for each iteration.

Returns: true if the caller should continue iteration; false to stop early.

Exceptions

std::invalid_argument if the layer index is out of range.

Member Data Documentation

◆ maxElapsedStaffDuration

util::Fraction musx::dom::EntryFrame::maxElapsedStaffDuration

The max elapsed staff duration that was calculated for the frame. This does not have to equal the measure duration, but normally it does.

◆ tupletInfo

std::vector<TupletInfo> musx::dom::EntryFrame::tupletInfo

A list of the tuplets in the frame and their calculated starting and ending information.

Note: Tuplets that start on grace notes are omitted from this list. Finale does not display them, and it is not possible to calculate their endpoints correctly in the general case. (Which is probably why Finale does not display them.)

Classes

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ EntryFrame()

Member Function Documentation

◆ calcAreAllEntriesHiddenInFrame()

◆ calcIsCueFrame()

◆ calcNearestEntry()

◆ createCurrentStaff()

◆ getFirstInterpretedIterator()

◆ getFirstInVoice()

◆ getLastInVoice()

◆ getNext()

◆ getPrevious()

◆ iterateEntries()

Member Data Documentation

◆ maxElapsedStaffDuration

◆ tupletInfo