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 measureId, util::Fraction timeOffset=0)
	Constructs a context-aware GFrameHold wrapper.

Cmper	getRequestedPartId () const
	Returns the requested part ID associated with this context.

MusxInstance< others::PartVoicing >	getPartVoicing () const
	Returns the part voicing for the requested part.

MusxInstance< others::PartVoicing >	getPolicyPartVoicing () const
	Returns the part voicing for the requested part, based on the document's `PartVoicingPolicy`.

const GFrameHold *	operator-> () const
	Provides const pointer-style access to the underlying GFrameHold.

	operator bool () const noexcept
	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) 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, int >	calcVoices (bool excludeHidden=false) 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 (util::Fraction position, 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 `position`.

util::Fraction	calcMinLegacyPickupSpacer () const
	Calculates the minimum legacy pickup spacer, if any.

bool	calcVoicingIncludesLayer (LayerIndex layerIndex) const
	Calculates if the part voicing for the current requested part includes the specified layer. This function returns the correct value even if the document's `PartVoicingPolicy` is to ignore part voicing.

bool	calcPolicyVoicingIncludesLayer (LayerIndex layerIndex) const
	Similar to calcVoicingIncludesLayer, but honoring the document's part voicing policy.

util::Fraction	getTimeOffset () const
	Return the time offset applied to entries in this instance. One reason this might be non-zero is if the instance is for a meausure that contains a legacy pickup spacer.

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	measureId,
		util::Fraction	timeOffset = `0`
	)

Constructs a context-aware GFrameHold wrapper.

Parameters

document	Weak pointer to the owning Document.
partId	The requested part ID.
staffId	The instrument ID for.
measureId	The measure ID for.
timeOffset	Subtract this amount from elapsed durations in created entry frames. A common usage might be to pass in here the value returned by others::Measure::calcMinLegacyPickupSpacer.

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	(	util::Fraction	position,
		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 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.
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, int > musx::dom::details::GFrameHoldContext::calcVoices ( bool excludeHidden = false ) const

Calculates the number of voices used by the GFrameHold instance.

Parameters

excludeHidden If true, hidden entries are excluded from consideration.

Returns: A list of each layer that contains entries and the number voice2 entries in that layer.

◆ calcVoicingIncludesLayer()

bool musx::dom::details::GFrameHoldContext::calcVoicingIncludesLayer ( LayerIndex layerIndex ) const

Calculates if the part voicing for the current requested part includes the specified layer. This function returns the correct value even if the document's PartVoicingPolicy is to ignore part voicing.

Parameters

layerIndex The 0-based layer indes to check.

Returns: True if the layer is included in the part voicing, otherwise false.

◆ createEntryFrame()

std::shared_ptr< const EntryFrame > musx::dom::details::GFrameHoldContext::createEntryFrame ( LayerIndex layerIndex ) const

Returns the EntryFrame for all entries in the given layer.

Parameters

layerIndex The layer index (0..3) to iterate.

Returns: EntryFrame for layer or nullptr if none.

◆ getPartVoicing()

MusxInstance< others::PartVoicing > musx::dom::details::GFrameHoldContext::getPartVoicing ( ) const

inline

Returns the part voicing for the requested part.

Returns: The part voicing or nullptr if none.

◆ getPolicyPartVoicing()

MusxInstance< others::PartVoicing > musx::dom::details::GFrameHoldContext::getPolicyPartVoicing ( ) const

inline

Returns the part voicing for the requested part, based on the document's PartVoicingPolicy.

Returns: The part voicing if it exists and if the document's PartVoicingPolicy applies part voicing. Otherwise nullptr.

◆ 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 the caller should continue iteration; false to stop early.

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 the caller should continue iteration; false to stop early.

◆ operator bool()

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

inlineexplicitnoexcept

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.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ GFrameHoldContext()

Member Function Documentation

◆ calcClefIndexAt() [1/2]

◆ calcClefIndexAt() [2/2]

◆ calcIsCuesOnly()

◆ calcMinLegacyPickupSpacer()

◆ calcNearestEntry()

◆ calcVoices()

◆ calcVoicingIncludesLayer()

◆ createEntryFrame()

◆ getPartVoicing()

◆ getPolicyPartVoicing()

◆ getRequestedPartId()

◆ iterateEntries() [1/2]

◆ iterateEntries() [2/2]

◆ operator bool()

◆ operator->()