musx::dom::details::GFrameHoldContext Class Reference

A context wrapper for GFrameHold associated with a specific part and location. More...

#include <Entries.h>

Public Member Functions
	GFrameHoldContext (const DocumentPtr &document, Cmper partId, Cmper staffId, Cmper meas)
	Constructs a context-aware GFrameHold wrapper.
Cmper	getRequestedPartId () const
	Returns the requested part ID associated with this context.
const GFrameHold *	operator-> () const
	Provides const pointer-style access to the underlying GFrameHold.
	operator bool () const
	Returns true if the internal GFrameHold is valid.
ClefIndex	calcClefIndexAt (Edu position) const
	Returns the clef index in effect for at the specified Edu position. This function does not take into account transposing clefs. Those are addressed in createEntryFrame.
ClefIndex	calcClefIndexAt (util::Fraction position) const
	Returns the clef index in effect for at the specified util::Fraction position (as a fraction of whole notes). This function does not take into account transposing clefs. Those are addressed in createEntryFrame.
std::shared_ptr< const EntryFrame >	createEntryFrame (LayerIndex layerIndex, util::Fraction timeOffset=0) const
	Returns the EntryFrame for all entries in the given layer.
bool	iterateEntries (LayerIndex layerIndex, std::function< bool(const EntryInfoPtr &)> iterator) const
	iterates the entries for the specified layer in this GFrameHold from left to right
bool	iterateEntries (std::function< bool(const EntryInfoPtr &)> iterator) const
	iterates the entries for this GFrameHold from left to right for each layer in order
std::map< LayerIndex, bool >	calcVoices () const
	Calculates the number of voices used by the GFrameHold instance.
bool	calcIsCuesOnly (bool includeVisibleInScore=false) const
	Calculates if this staff in this measure contains only a cue layer and full-measure rest layers.
EntryInfoPtr	calcNearestEntry (Edu eduPosition, bool findExact=true, std::optional< LayerIndex > matchLayer=std::nullopt, std::optional< bool > matchVoice2=std::nullopt, util::Fraction atGraceNoteDuration=0) const
	Calculates the nearest non-grace-note entry at the given eduPosition.
util::Fraction	calcMinLegacyPickupSpacer () const
	Calculates the minimum legacy pickup spacer, if any.

Detailed Description

A context wrapper for GFrameHold associated with a specific part and location.

This class retrieves the appropriate GFrameHold from a Document using part, instrument, and measure IDs, and enables part-aware operations like iterating over EntryFrame objects.

Constructor & Destructor Documentation

GFrameHoldContext()

musx::dom::details::GFrameHoldContext::GFrameHoldContext	(	const DocumentPtr &	document,
		Cmper	partId,
		Cmper	staffId,
		Cmper	meas
	)

Constructs a context-aware GFrameHold wrapper.

Parameters

document	Weak pointer to the owning Document.
partId	The requested part ID.
staffId	The instrument ID for.
meas	The measure ID for.

Member Function Documentation

calcClefIndexAt() [1/2]

ClefIndex musx::dom::details::GFrameHoldContext::calcClefIndexAt

(

Edu

position

)

const

Returns the clef index in effect for at the specified Edu position. This function does not take into account transposing clefs. Those are addressed in createEntryFrame.

Parameters

position

The Edu position of the clef in staff-level Edus. (The staff-level matters for Independent Key Signature staves.)

calcClefIndexAt() [2/2]

ClefIndex musx::dom::details::GFrameHoldContext::calcClefIndexAt ( util::Fraction  position ) const

inline

Returns the clef index in effect for at the specified util::Fraction position (as a fraction of whole notes). This function does not take into account transposing clefs. Those are addressed in createEntryFrame.

Parameters

position

The staff-level position of the clef. (The staff-level matters for Independent Key Signature staves.)

calcIsCuesOnly()

bool musx::dom::details::GFrameHoldContext::calcIsCuesOnly

(

bool

includeVisibleInScore = false

)

const

Calculates if this staff in this measure contains only a cue layer and full-measure rest layers.

Parameters

includeVisibleInScore

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

calcMinLegacyPickupSpacer()

util::Fraction musx::dom::details::GFrameHoldContext::calcMinLegacyPickupSpacer

(

)

const

Calculates the minimum legacy pickup spacer, if any.

Legacy pickup spacers, created by the legacy Mirror Tool, can differ for each staff and layer. The spacer takes away time from the beginning of the layer, leaving the time at the end for the pickup to the next measure.

Returns

The smallest legacy pickup spacer encountered in a layer for this measure and staff. Zero if none.

calcNearestEntry()

EntryInfoPtr musx::dom::details::GFrameHoldContext::calcNearestEntry	(	Edu	eduPosition,
		bool	findExact = true,
		std::optional< LayerIndex >	matchLayer = std::nullopt,
		std::optional< bool >	matchVoice2 = std::nullopt,
		util::Fraction	atGraceNoteDuration = 0
	)		const

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

Parameters

eduPosition	The EDU position to find.
findExact	If true, only find an entry that matches to within 1 evpu. Otherwise find the closest entry in the measure.
matchLayer	If specified, only find entries in this 0-based layer index. (Values 0..3)
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.

calcVoices()

std::map< LayerIndex, bool > musx::dom::details::GFrameHoldContext::calcVoices

(

)

const

Calculates the number of voices used by the GFrameHold instance.

Returns

A list of each layer that contains entries and whether that layer uses voice2.

createEntryFrame()

std::shared_ptr< const EntryFrame > musx::dom::details::GFrameHoldContext::createEntryFrame	(	LayerIndex	layerIndex,
		util::Fraction	timeOffset = 0
	)		const

Returns the EntryFrame for all entries in the given layer.

Parameters

layerIndex	The layer index (0..3) to iterate.
timeOffset	Subtract this amount from elapsed durations. A common usage might be to pass in here the value returned by others::Measure::calcMinLegacyPickupSpacer.

Returns

EntryFrame for layer or nullptr if none.

getRequestedPartId()

Cmper musx::dom::details::GFrameHoldContext::getRequestedPartId ( ) const

inline

Returns the requested part ID associated with this context.

Returns

The requested part ID.

iterateEntries() [1/2]

bool musx::dom::details::GFrameHoldContext::iterateEntries	(	LayerIndex	layerIndex,
		std::function< bool(const EntryInfoPtr &)>	iterator
	)		const

iterates the entries for the specified layer in this GFrameHold from left to right

Parameters

layerIndex	The layer index (0..3) to iterate.
iterator	The callback function for each iteration.

Returns

true if higher-level iteration should continue. false if it should halt.

Exceptions

std::invalid_argument

if the layer index is out of range

iterateEntries() [2/2]

bool musx::dom::details::GFrameHoldContext::iterateEntries

(

std::function< bool(const EntryInfoPtr &)>

iterator

)

const

iterates the entries for this GFrameHold from left to right for each layer in order

Parameters

iterator

The callback function for each iteration.

Returns

true if higher-level iteration should continue. false if it should halt.

operator bool()

musx::dom::details::GFrameHoldContext::operator bool ( ) const

inlineexplicit

Returns true if the internal GFrameHold is valid.

Returns

True if the GFrameHold was successfully retrieved; false otherwise.

operator->()

const GFrameHold * musx::dom::details::GFrameHoldContext::operator-> ( ) const

inline

Provides const pointer-style access to the underlying GFrameHold.

Returns

A const pointer to GFrameHold.