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

#include <Entries.h>

Classes
struct	WorkaroundAwareResult
	The result returned by voice iteration function that are aware of beamed rest workaround. More...

Public Types
enum class	BeamIterationMode { Normal , IncludeAll , WorkaroundAware }
	Controls which entries are included when iterating over beams. More...

Public Member Functions
	EntryInfoPtr ()
	Default constructor.

	EntryInfoPtr (const std::shared_ptr< const EntryFrame > &entryFrame, size_t index=0)
	Constructor function.

const std::shared_ptr< const EntryInfo >	operator-> () const
	Allows `->` access to the underlying EntryInfo instance.

	operator bool () const noexcept
	Provides a boolean conversion based on whether the frame is valid and contains entries.

bool	isSameEntry (const EntryInfoPtr &src) const
	Returns whether the input and the current instance refer to the same entry.

bool	calcIsSamePitchContent (const EntryInfoPtr &src, bool compareConcert=true) const
	Returns whether this entry and `src` contain the same pitch content or rest value.

bool	calcIsSamePitchContentAndDuration (const EntryInfoPtr &src, bool compareConcert=true, bool requireSameVoice=true, bool requireSameGraceElapsedDura=false) const
	Returns whether this entry and `src` represent the same notated value.

std::shared_ptr< const EntryFrame >	getFrame () const
	Returns the frame.

size_t	getIndexInFrame () const
	Returns the index within the frame.

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

StaffCmper	getStaff () const
	Get the staff cmper.

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

MeasCmper	getMeasure () const
	Get the measure cmper.

MusxInstance< KeySignature >	getKeySignature () const
	Get the key signature of the entry.

MusxInstance< details::EntryPartFieldDetail >	getPartFieldData () const
	Gets the applicable part data for the entry, or nullptr if none.

Evpu	calcManuaOffset () const
	Returns the manual offset of the entry for the current requested part. This function encapsulates handling of the case when the manual offset is unlinked and different in score and part(s).

unsigned	calcReverseGraceIndex () const
	Caclulates the grace index counting leftward (used by other standards such as MNX)

util::Fraction	calcGraceElapsedDuration () const
	Calculates a grace note's symbolic starting duration as a negative offset from the main note. This is useful for comparing grace note sequences.

std::optional< size_t >	calcNextTupletIndex (std::optional< size_t > currentIndex=0) const
	Returns the next higher tuplet index that this entry starts, or std::nullopt if none.

EntryInfoPtr	getNextInFrame () const
	Get the next entry in the frame.

EntryInfoPtr	getNextInLayer () const
	Get the next entry in the same layer and staff. This can be in the next measure.

EntryInfoPtr	getNextSameV () const
	Get the next entry in the frame in the same voice.

EntryInfoPtr	getNextSameVNoGrace () const
	Get the next entry in the frame in the same voice, skipping grace notes.

EntryInfoPtr	getPreviousInLayer () const
	Get the previous entry in the same layer and staff. This can be in the previous measure.

EntryInfoPtr	getPreviousInFrame () const
	Get the previous entry in the frame.

EntryInfoPtr	getPreviousSameV () const
	Get the previous entry in the frame in the same voice.

EntryInfoPtr	getPreviousSameVNoGrace () const
	Get the previous entry in the frame in the same voice, skipping grace notes.

EntryInfoPtr	getNextInVoice (int voice) const
	Returns the next entry in the frame in the specified v1/v2 or null if none.

EntryInfoPtr	getPreviousInVoice (int voice) const
	Returns the previous entry in the frame in the specified v1/v2 or null if none.

WorkaroundAwareResult	getNextInVoiceWorkaroundAware (int voice) const
	Returns the next forward entry in this voice using musxdom's workaround-aware interpretation.

WorkaroundAwareResult	asWorkaroundAwareResult () const
	Returns this EntryInfoPtr in a WorkaroundAwareResult instance.

EntryInfoPtr	getNextInBeamGroup (BeamIterationMode beamIterationMode=BeamIterationMode::Normal) const
	Gets the next entry in a beamed group or nullptr if the entry is not beamed or is the last in the group.

EntryInfoPtr	getPreviousInBeamGroup (BeamIterationMode beamIterationMode=BeamIterationMode::Normal) const
	Gets the previous entry in a beamed group or nullptr if the entry is not beamed or is the first in the group.

EntryInfoPtr	getNextInBeamGroupAcrossBars (BeamIterationMode beamIterationMode=BeamIterationMode::Normal) const
	Gets the next entry in a beamed group, or nullptr if the entry is not beamed or is the last in the group. This function is simular to getNextInBeamGroup but it traverses into the next bar when it detects a beam across a barline, as created by the Beam Over Barline plugin.

EntryInfoPtr	getPreviousInBeamGroupAcrossBars (BeamIterationMode beamIterationMode=BeamIterationMode::Normal) const
	Gets the previous entry in a beamed group or nullptr if the entry is not beamed or is the first in the group. This function is simular to getPreviousInBeamGroup but it traverses into the previous bar when it detects a beam across a barline, as created by the Beam Over Barline plugin.

bool	calcDisplaysAsRest () const
	Calculates if an entry displays as a rest.

std::pair< int, int >	calcTopBottomStaffPositions () const
	Calculates the top and bottom staff positions of the entry, taking into account percussion notes. This function must not be called on a floating rest. It asserts and throws if so.

std::pair< bool, bool >	calcEntryStemSettings () const
	Returns the Entry stem settings for the current requested part. This function encapsulates handling of the case when the two booleans are unlinked and different in score and part(s).

bool	calcUpStemDefault () const
	Calculates if the entry is upstem by default, without considering voices, layers, staff options, cross-staffing, or manual overrides.

bool	calcUpStem () const
	Determines the effective stem direction of the entry, taking into account voices, layers, staff options, manual overrides, and cross-staff notation.

bool	calcUnbeamed () const
	Returns whether this is an unbeamed entry.

bool	calcIsBeamStart () const
	Returns whether this is the start of a primary beam.

bool	calcCreatesSingletonBeamLeft () const
	Determines if this entry contains a tuplet that creates a singleton beam left. See EntryFrame::TupletInfo::calcCreatesSingletonBeamLeft for more information.

bool	calcCreatesSingletonBeamRight () const
	Determines if this entry contains a tuplet that creates a singleton beam right. See EntryFrame::TupletInfo::calcCreatesSingletonBeamRight for more information.

EntryInfoPtr	calcBeamContinuesLeftOverBarline () const
	Determines if this entry continues a beam across a barline from the previous measure.

EntryInfoPtr	calcBeamContinuesRightOverBarline () const
	Determines if this entry continues a beam across a barline to the next measure.

bool	calcIsFeatheredBeamStart (Evpu &outLeftY, Evpu &outRightY) const
	Calculates if the entry starts a feathered beam and returns information about it if so.

EntryInfoPtr	findBeamStartOrCurrent () const
	Finds the first entry of a beamed group or returns the current entry if it is not beams.

EntryInfoPtr	findBeamEnd () const
	Finds the end entry of a beamed group.

unsigned	calcNumberOfBeams () const
	Calculates the number of beams or flags on the entry.

unsigned	calcLowestBeamStart (bool considerBeamOverBarlines=false) const
	Returns the lowest beam number starting at this entry, where 1 = 8th note beam, 2 = 16th note beam, etc.

unsigned	calcLowestBeamEnd () const
	Returns the lowest beam number ending at this entry, where 1 = 8th note beam, 2 = 16th note beam, etc.

unsigned	calcLowestBeamEndAcrossBarlines () const
	Returns the lowest beam number ending at this entry, where 1 = 8th note beam, 2 = 16th note beam, etc. This function takes into account beams the cross barlines, as created by the Beam Over Barline plugin.

unsigned	calcLowestBeamStub () const
	Returns the lowest beam stub at this entry, where 2 = 16th note stub, 3 = 32nd note stub, etc.

bool	calcBeamStubIsLeft () const
	Calculates if a beam stub on this entry would go left or right. It does not check that an entry actually has a beam stub. Use calcLowestBeamStub to discover if the entry has a beam stub.

util::Fraction	calcGlobalElapsedDuration () const
	Calculates the elapsed duration in global edu, removing any time stretch due to independent time signature.

util::Fraction	calcGlobalActualDuration () const
	Calculates the actual duration in global edu, removing any time stretch due to independent time signature.

bool	calcCanBeBeamed () const
	Determines if this entry can be beamed.

bool	calcBeamMustStartHere () const
	Determines if a beam must start on this entry.

int	calcEntrySize () const
	Returns the entry size as a percentage, taking into account the beaming.

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

bool	calcIsFullMeasureRest () const
	Returns whether this is a full measure rest.

bool	calcIsBeamedRestWorkaroundHiddenRest () const
	A common workaround in Finale is to hide a rest in v1 and supply it in v2. Typically it is used when a beam starts or ends with a 16th beam hook, has a 16th rest in the middle and an 8th note on the other end. This code detects that situation.

bool	calcIsBeamedRestWorkaroundVisibleRest () const
	A common workaround in Finale is to hide a rest in v1 and supply it in v2. Typically it is used when a beam starts or ends with a 16th beam hook, has a 16th rest in the middle and an 8th note on the other end. This code detects that situation.

std::vector< size_t >	findTupletInfo () const
	Finds the tuplet info for tuplets that include this entry.

bool	calcIfLayerSettingsApply () const
	Calculates whether the conditions are met for the layer attributes dependent on others::LayerAttributes::onlyIfOtherLayersHaveNotes. This also takes into account others::LayerAttributes::ignoreHiddenNotesOnly and others::LayerAttributes::ignoreHiddenLayers.

int	calcCrossStaffDirectionForAll (DeferredReference< MusxInstanceList< others::StaffUsed > > staffList={}) const
	Calculates if this entry has cross-staffed notes all in a single direction.

bool	calcIsSingletonGrace () const
	Return true if this entry is a grace note and the only grace in the sequence at this location.

int	calcIsAuxiliaryPitchMarker () const
	Return true if this entry is an auxiliary pitch marker (specifically, a trill-to or gliss-to pitch marker.)

bool	calcIsTrillToGraceEntry () const
	Calculates if this entry is a trill-to entry as created by the Parenthesize Trill-To Notes plugin.

bool	calcIsGlissToGraceEntry () const
	Calculates if this entry is a gliss-to entry as created by the Parenthesize Trill-To Notes plugin.

EntryInfoPtr	findHiddenSourceForBeamOverBarline () const
	Find the hidden source entry for a mid-system beam created by the Beam Over Barline plugin. This code captures the logic from the Beam Over Barling plugin, allowing the caller to unwind that plugin's workarounds and detect the entries in a beam that crosses a barline.

EntryInfoPtr	findDisplayEntryForBeamOverBarline () const
	Find the display entry for a hidden source entry. The display entry is one or more bars previous to the source entry. This code captures the logic from the Beam Over Barling plugin, allowing the caller to unwind that plugin's workarounds and detect the entries in a beam that crosses a barline.

EntryInfoPtr	findMainEntryForGraceNote (bool ignoreRests=false) const
	Finds the main entry for a grace note, taking into account hidden entries for beams over barlines.

bool	operator< (const EntryInfoPtr &other) const
	Explicit operator< for std::map.

Static Public Member Functions
static EntryInfoPtr	fromPositionOrNull (const DocumentPtr &document, Cmper partId, StaffCmper staffId, MeasCmper measureId, EntryNumber entryNumber, util::Fraction timeOffset=0)
	Searches the given position at `staffId` and `measureId` for the `entryNumber`.

static EntryInfoPtr	fromEntryNumber (const DocumentPtr &document, Cmper partId, EntryNumber entryNumber, util::Fraction timeOffset=0)
	Returns an EntryInfoPtr for the entry specified by `entryNumber`.

Detailed Description

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.

Member Enumeration Documentation

◆ BeamIterationMode

enum class musx::dom::EntryInfoPtr::BeamIterationMode

strong

Controls which entries are included when iterating over beams.

Enumerator
Normal	Skip hidden entries. This is how Finale displays beams.
IncludeAll	Include all entries, even if they are hidden.
WorkaroundAware	Apply musxdom's interpretation of known entry workarounds when iterating beams. Depending on the situation, this mode may skip, include, or reinterpret entries that participate in recognized workarounds. See EntryFrame::getFirstInVoiceWorkaroundAware for detailed behavior.

Constructor & Destructor Documentation

◆ EntryInfoPtr()

musx::dom::EntryInfoPtr::EntryInfoPtr	(	const std::shared_ptr< const EntryFrame > &	entryFrame,
		size_t	index = `0`
	)

inlineexplicit

Constructor function.

Parameters

entryFrame	The entry frame.
index	The index of this instance within the frame.

Member Function Documentation

◆ calcBeamContinuesLeftOverBarline()

EntryInfoPtr musx::dom::EntryInfoPtr::calcBeamContinuesLeftOverBarline ( ) const

Determines if this entry continues a beam across a barline from the previous measure.

Note: The Beam Over Barlines plugin has poor support for v1/v2. This function detects v1/v2 correctly on the chance that a user may have manually setup v1/v2 the way Beam Over Barlines should have.

Returns: If the function returns non-null, the return value here is the previous real entry in the beam over a barline, taking into account tuplets that create faux singleton beams.

◆ calcBeamContinuesRightOverBarline()

EntryInfoPtr musx::dom::EntryInfoPtr::calcBeamContinuesRightOverBarline ( ) const

Determines if this entry continues a beam across a barline to the next measure.

Note: The Beam Over Barlines plugin has poor support for v1/v2. This function detects v1/v2 correctly on the chance that a user may have manually setup v1/v2 the way Beam Over Barlines should have.

Returns: If the function returns non-null, the return value here is the next real entry in the beam over a barline, taking into account tuplets that create faux singleton beams.

◆ calcBeamStubIsLeft()

bool musx::dom::EntryInfoPtr::calcBeamStubIsLeft ( ) const

Calculates if a beam stub on this entry would go left or right. It does not check that an entry actually has a beam stub. Use calcLowestBeamStub to discover if the entry has a beam stub.

Note: This is a best approximation of Finale's behavior for default beam stub direction. No doubt there are edge cases where it does not match.

Returns: True if a beam stub would go left; false if it would go right or if no calculation is possible.

◆ calcCrossStaffDirectionForAll()

int musx::dom::EntryInfoPtr::calcCrossStaffDirectionForAll ( DeferredReference< MusxInstanceList< others::StaffUsed > > staffList = {} ) const

Calculates if this entry has cross-staffed notes all in a single direction.

Parameters

staffList Optional staff list used to determine staff order. If it is not supplied, the function automatically retrieves the scroll-view staff order from the document. Supplying an explicit list can be used to avoid repeatedly fetching the staff list when calling this function in a loop (for example, within a beam).

Returns

1 if all cross-staffed notes cross upward to a higher staff.
0 if the note is not cross-staffed, or if notes are crossed both up and down.
−1 if all cross-staffed notes cross downward to a lower staff.

◆ calcDisplaysAsRest()

bool musx::dom::EntryInfoPtr::calcDisplaysAsRest ( ) const

Calculates if an entry displays as a rest.

Todo:: Eventually calcDisplaysAsRest should take into account voiced parts.

Todo:: Add code to detect that the entry is converted to a rest by voiced part settings

◆ calcEntrySize()

int musx::dom::EntryInfoPtr::calcEntrySize ( ) const

Returns the entry size as a percentage, taking into account the beaming.

Returns: Integer percentage where 100 means 100%.

◆ calcEntryStemSettings()

std::pair< bool, bool > musx::dom::EntryInfoPtr::calcEntryStemSettings ( ) const

Returns the Entry stem settings for the current requested part. This function encapsulates handling of the case when the two booleans are unlinked and different in score and part(s).

Note: This function is only for getting the entry's two boolean stem settings. Use calcUpStem to get the entry's effective stem direction, taking into account all options and situations.

Returns: A std::pair<bool, bool> with the first being the freezeStem setting and the second being the upStem setting.

◆ calcGraceElapsedDuration()

util::Fraction musx::dom::EntryInfoPtr::calcGraceElapsedDuration ( ) const

Calculates a grace note's symbolic starting duration as a negative offset from the main note. This is useful for comparing grace note sequences.

Returns: Negative symbolic offset from the main note, or zero if not a grace note.

◆ calcIfLayerSettingsApply()

bool musx::dom::EntryInfoPtr::calcIfLayerSettingsApply ( ) const

Calculates whether the conditions are met for the layer attributes dependent on others::LayerAttributes::onlyIfOtherLayersHaveNotes. This also takes into account others::LayerAttributes::ignoreHiddenNotesOnly and others::LayerAttributes::ignoreHiddenLayers.

Returns: true if the layer settings dependent on others::LayerAttributes::onlyIfOtherLayersHaveNotes are in effect. Otherwise false.

◆ calcIsAuxiliaryPitchMarker()

int musx::dom::EntryInfoPtr::calcIsAuxiliaryPitchMarker ( ) const

Return true if this entry is an auxiliary pitch marker (specifically, a trill-to or gliss-to pitch marker.)

The conditions that must be met are:

The entry is a singleton grace note.
The entry has a hidden custom stem.

◆ calcIsBeamedRestWorkaroundHiddenRest()

bool musx::dom::EntryInfoPtr::calcIsBeamedRestWorkaroundHiddenRest ( ) const

A common workaround in Finale is to hide a rest in v1 and supply it in v2. Typically it is used when a beam starts or ends with a 16th beam hook, has a 16th rest in the middle and an 8th note on the other end. This code detects that situation.

Returns: True if this is either the hidden rest in v1.

◆ calcIsBeamedRestWorkaroundVisibleRest()

bool musx::dom::EntryInfoPtr::calcIsBeamedRestWorkaroundVisibleRest ( ) const

A common workaround in Finale is to hide a rest in v1 and supply it in v2. Typically it is used when a beam starts or ends with a 16th beam hook, has a 16th rest in the middle and an 8th note on the other end. This code detects that situation.

Returns: True if this is either the visible replacement rest in v2.

◆ calcIsCue()

bool musx::dom::EntryInfoPtr::calcIsCue ( bool includeVisibleInScore = false ) const

Calculates if this entry is part of a cue.

Parameters

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

Returns

true if

the entry is reduced in size
the entry is hidden by "Blank Notation" or "Blank Notation with Rests" alternate notation in the score but not in a part.

◆ calcIsFeatheredBeamStart()

bool musx::dom::EntryInfoPtr::calcIsFeatheredBeamStart	(	Evpu &	outLeftY,
		Evpu &	outRightY
	)		const

Calculates if the entry starts a feathered beam and returns information about it if so.

Parameters

[out]	outLeftY	The height of the left side of the feathered beam
[out]	outRightY	The height of the right side of the feathered beam

Returns: true if this is a feathered beam. If the return value is false, outLeftY and outRightY are unchanged.

◆ calcIsFullMeasureRest()

bool musx::dom::EntryInfoPtr::calcIsFullMeasureRest ( ) const

Returns whether this is a full measure rest.

Note: Note that in Finale, only whole rests are used as full measure rests.

◆ calcIsGlissToGraceEntry()

bool musx::dom::EntryInfoPtr::calcIsGlissToGraceEntry ( ) const

Calculates if this entry is a gliss-to entry as created by the Parenthesize Trill-To Notes plugin.

The conditions that must be met are:

The entry is an auxiliary pitch marker. (See calcIsAuxiliaryPitchMarker.)
The entry must be the terminator for one of the standard entry-attached SmartShape gliss lines.

Only the standard SmartShape gliss lines are checked. Other CustomLine values do no qualify.

◆ calcIsSamePitchContent()

bool musx::dom::EntryInfoPtr::calcIsSamePitchContent	(	const EntryInfoPtr &	src,
		bool	compareConcert = `true`
	)		const

Returns whether this entry and src contain the same pitch content or rest value.

For note entries, only pitch content is compared; duration is ignored. For rest entries, non-floating rests are compared using their assigned display levels.

Parameters

src	The EntryInfoPtr to compare.
compareConcert	If true, compares concert pitches. If false, compares scale degrees relative to the prevailing key.

Returns: true if both pointers are non-null and represent the same pitch content or rest value, false otherwise.

◆ calcIsSamePitchContentAndDuration()

bool musx::dom::EntryInfoPtr::calcIsSamePitchContentAndDuration	(	const EntryInfoPtr &	src,
		bool	compareConcert = `true`,
		bool	requireSameVoice = `true`,
		bool	requireSameGraceElapsedDura = `false`
	)		const

Returns whether this entry and src represent the same notated value.

This function performs the same pitch/rest comparison as calcIsSamePitchContent and additionally compares symbolic duration, actual duration, and optionally v1v2 voice number and grace-note elapsed duration.

Parameters

src	The EntryInfoPtr to compare.
compareConcert	If true, compares concert pitches. If false, compares scale degrees relative to the prevailing key.
requireSameVoice	If true, the entries must have identical v1v2 voice numbers.
requireSameGraceElapsedDura	If true, grace-note elapsed durations must match.

Returns: true if both pointers are non-null and all required properties match; false otherwise.

◆ calcIsTrillToGraceEntry()

bool musx::dom::EntryInfoPtr::calcIsTrillToGraceEntry ( ) const

Calculates if this entry is a trill-to entry as created by the Parenthesize Trill-To Notes plugin.

The conditions that must be met are:

The entry is an auxiliary pitch marker. (See calcIsAuxiliaryPitchMarker.)
The entry has a main entry.
The entry is positioned at least 1 space to the right of the main entry.

Note that the main note is not checked for the existence of a trill. Callers should decide on their own whether this is important and, if so, how to check for it. Finale provides too many different fonts and options for creating trill markers to reliably check for it in this function.

◆ calcLowestBeamEnd()

unsigned musx::dom::EntryInfoPtr::calcLowestBeamEnd ( ) const

Returns the lowest beam number ending at this entry, where 1 = 8th note beam, 2 = 16th note beam, etc.

Returns: 0 if not beamed or no beam ends this entry; otherwise, the beam number

◆ calcLowestBeamEndAcrossBarlines()

unsigned musx::dom::EntryInfoPtr::calcLowestBeamEndAcrossBarlines ( ) const

Returns the lowest beam number ending at this entry, where 1 = 8th note beam, 2 = 16th note beam, etc. This function takes into account beams the cross barlines, as created by the Beam Over Barline plugin.

Returns: 0 if not beamed or no beam ends this entry; otherwise, the beam number

◆ calcLowestBeamStart()

unsigned musx::dom::EntryInfoPtr::calcLowestBeamStart ( bool considerBeamOverBarlines = false ) const

Returns the lowest beam number starting at this entry, where 1 = 8th note beam, 2 = 16th note beam, etc.

Parameters

considerBeamOverBarlines If true, consider beams over barlines as created for system breaks by the Beam Over Barlines plugin.

Returns: 0 if not beamed or no beam starts this entry; otherwise, the beam number

◆ calcLowestBeamStub()

unsigned musx::dom::EntryInfoPtr::calcLowestBeamStub ( ) const

Returns the lowest beam stub at this entry, where 2 = 16th note stub, 3 = 32nd note stub, etc.

Returns: 0 if not beamed or no beam stub exists on this entry; otherwise, the lowest beam stub number

◆ calcTopBottomStaffPositions()

std::pair< int, int > musx::dom::EntryInfoPtr::calcTopBottomStaffPositions ( ) const

Calculates the top and bottom staff positions of the entry, taking into account percussion notes. This function must not be called on a floating rest. It asserts and throws if so.

Returns: A std::pair<int, int> with the first being the top staff position and the second being the bottom staff position.

◆ calcUnbeamed()

bool musx::dom::EntryInfoPtr::calcUnbeamed ( ) const

Returns whether this is an unbeamed entry.

Returns

◆ calcUpStem()

bool musx::dom::EntryInfoPtr::calcUpStem ( ) const

inline

Determines the effective stem direction of the entry, taking into account voices, layers, staff options, manual overrides, and cross-staff notation.

The function is designed to handle all common combinations of musical options and contexts, although some rare cases may still produce incorrect results. The concept of an "up stem" becomes ambiguous when the entry uses a reverse stem. (See Entry::reverseUpStem and Entry::reverseDownStem.) The goal is to compute the logical stem direction that governs the entry's behavior. This allows selecting the correct up or down variant for any entry detail records or entry properties that have them, including which reverse-stem value to recognize. In cases involving reverse stems, the result of calcUpStem may not match the visible direction in a Finale-generated PDF.

Note: The Entry::upStemScore flag may appear to provide this information, but it can be wrong if the layer context changed without the entry frame being re-edited. It also does not reflect cross-staff stem directions or staff-level overrides of stem direction.

Returns: True if the stem is up; false if it is down.

◆ calcUpStemDefault()

bool musx::dom::EntryInfoPtr::calcUpStemDefault ( ) const

Calculates if the entry is upstem by default, without considering voices, layers, staff options, cross-staffing, or manual overrides.

Returns: True if the entry is upstem barring any other factors that would override the stem direction. False if it is downstem.

◆ createCurrentStaff()

MusxInstance< others::StaffComposite > musx::dom::EntryInfoPtr::createCurrentStaff ( const std::optional< StaffCmper > & forStaffId = std::nullopt ) const

Creates the current StaffComposite for the entry.

Parameters

forStaffId Specifies optional staff ID. If supplied, it overrides the entry's staff ID. (Useful when notes are cross-staffed.)

◆ findBeamEnd()

EntryInfoPtr musx::dom::EntryInfoPtr::findBeamEnd ( ) const

Finds the end entry of a beamed group.

Returns: The entry if found, NULL if the entry cannot be beamed or if it is not part of a beamed group.

◆ findBeamStartOrCurrent()

EntryInfoPtr musx::dom::EntryInfoPtr::findBeamStartOrCurrent ( ) const

Finds the first entry of a beamed group or returns the current entry if it is not beams.

Note: This behavior is different than other beam functions in that it returns the current entry if there is no beam rather than returning NULL.

Returns: The first entry of a beamed group or the current entry if no beam.

◆ findDisplayEntryForBeamOverBarline()

EntryInfoPtr musx::dom::EntryInfoPtr::findDisplayEntryForBeamOverBarline ( ) const

Find the display entry for a hidden source entry. The display entry is one or more bars previous to the source entry. This code captures the logic from the Beam Over Barling plugin, allowing the caller to unwind that plugin's workarounds and detect the entries in a beam that crosses a barline.

Returns: The display entry if this is a hidden source entry, otherwise nullptr.

◆ findHiddenSourceForBeamOverBarline()

EntryInfoPtr musx::dom::EntryInfoPtr::findHiddenSourceForBeamOverBarline ( ) const

Find the hidden source entry for a mid-system beam created by the Beam Over Barline plugin. This code captures the logic from the Beam Over Barling plugin, allowing the caller to unwind that plugin's workarounds and detect the entries in a beam that crosses a barline.

Returns: The hidden source entry if found, otherwise nullptr.

◆ findMainEntryForGraceNote()

EntryInfoPtr musx::dom::EntryInfoPtr::findMainEntryForGraceNote ( bool ignoreRests = false ) const

Finds the main entry for a grace note, taking into account hidden entries for beams over barlines.

Parameters

ignoreRests If true, the returned entry must not be a rest.

Returns: The main entry if found. If the grace note is at the end of a measure or v2 sequence, or if ignoring rests and the next non-grace is a rest, returns null. Also returns null if this is not a grace note.

◆ findTupletInfo()

std::vector< size_t > musx::dom::EntryInfoPtr::findTupletInfo ( ) const

Finds the tuplet info for tuplets that include this entry.

Returns: A list of indices of TupletInfo records that include the entry.

◆ fromEntryNumber()

EntryInfoPtr musx::dom::EntryInfoPtr::fromEntryNumber	(	const DocumentPtr &	document,
		Cmper	partId,
		EntryNumber	entryNumber,
		util::Fraction	timeOffset = `0`
	)

static

Returns an EntryInfoPtr for the entry specified by entryNumber.

If you are directly importing a musx file last saved in a version before Finale 25, it may contain mirrors. If so, one of the locations is chosen. (This applies to musx files last saved by Finale 2014 or 2014.5.)

Parameters

document	The document to search.
partId	The part within the document for which to create the EntryInfoPtr.
entryNumber	The entry to find.
timeOffset	Subtract this amount from elapsed durations. A common usage might be to pass in here the value returned by others::Measure::calcMinLegacyPickupSpacer.

Returns: An EntryInfoPtr corresponding to the input entryNumber or null if the entry is not in the requested part or otherwise is not found.

◆ fromPositionOrNull()

EntryInfoPtr musx::dom::EntryInfoPtr::fromPositionOrNull	(	const DocumentPtr &	document,
		Cmper	partId,
		StaffCmper	staffId,
		MeasCmper	measureId,
		EntryNumber	entryNumber,
		util::Fraction	timeOffset = `0`
	)

static

Searches the given position at staffId and measureId for the entryNumber.

Parameters

document	The document to search.
partId	The part within the document for which to create the EntryInfoPtr.
staffId	The ID of the staff to search.
measureId	The ID of the measure to search.
entryNumber	The EntryNumber to search for.
timeOffset	Subtract this amount from elapsed durations. A common usage might be to pass in here the value returned by others::Measure::calcMinLegacyPickupSpacer.

Returns: If found, an EntryInfoPtr for the given entry number. Otherwise an null instance.

◆ getNextInLayer()

EntryInfoPtr musx::dom::EntryInfoPtr::getNextInLayer ( ) const

Get the next entry in the same layer and staff. This can be in the next measure.

Returns: The next continguous entry. Returns nullptr if it encounters an empty frame or end of file.

◆ getNextInVoice()

EntryInfoPtr musx::dom::EntryInfoPtr::getNextInVoice ( int voice ) const

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

Unlike getNextSameV, this returns the next v2 entry in any v2 launch sequence.

Parameters

voice Must be 1 or 2.

◆ getNextInVoiceWorkaroundAware()

EntryInfoPtr::WorkaroundAwareResult musx::dom::EntryInfoPtr::getNextInVoiceWorkaroundAware ( int voice ) const

Returns the next forward entry in this voice using musxdom's workaround-aware interpretation.

This function continues forward traversal from this EntryInfoPtr. It applies the same workaround-aware rules used by EntryFrame::getFirstInVoiceWorkaroundAware. Currently this means the beamed-rest workaround, where additional visible or hidden rests are inserted solely to break beams over internal rests when the beam is otherwise a hook. Other workarounds may be added in the future.

The following rules govern selection of the next entry:

Extra visible voice-2 workaround rests inserted solely to influence beam display are skipped.
Hidden voice-1 workaround rests used to force a beam shape are returned with EntryInfoPtr::WorkaroundAwareResult::effectiveHidden set to false.
All other entries are returned with EntryInfoPtr::WorkaroundAwareResult::effectiveHidden matching their stored isHidden value.

If no further usable entry exists, the returned EntryInfoPtr::WorkaroundAwareResult will have a null EntryInfoPtr::WorkaroundAwareResult::entry.

Parameters

voice Must be 1 or 2.

Returns: A WorkaroundAwareResult containing the next usable entry (or null) and its effective-hidden flag.

◆ getNextSameV()

EntryInfoPtr musx::dom::EntryInfoPtr::getNextSameV ( ) const

Get the next entry in the frame in the same voice.

For V2, it returns null after the current V2 launch sequence.

◆ getNextSameVNoGrace()

EntryInfoPtr musx::dom::EntryInfoPtr::getNextSameVNoGrace ( ) const

Get the next entry in the frame in the same voice, skipping grace notes.

Returns: The same as getNextSameV except grace notes are skipped.

◆ getPreviousInLayer()

EntryInfoPtr musx::dom::EntryInfoPtr::getPreviousInLayer ( ) const

Get the previous entry in the same layer and staff. This can be in the previous measure.

Returns: The previous continguous entry. Returns nullptr if it encounters an empty frame or the beginning of the file.

◆ getPreviousInVoice()

EntryInfoPtr musx::dom::EntryInfoPtr::getPreviousInVoice ( int voice ) const

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

Unlike getPreviousSameV, this returns the next v2 entry in any v2 launch sequence.

Parameters

voice Must be 1 or 2.

◆ getPreviousSameV()

EntryInfoPtr musx::dom::EntryInfoPtr::getPreviousSameV ( ) const

Get the previous entry in the frame in the same voice.

For V2, it returns null when it hits the v2Launch note for the current V2 launch sequence.

◆ getPreviousSameVNoGrace()

EntryInfoPtr musx::dom::EntryInfoPtr::getPreviousSameVNoGrace ( ) const

Get the previous entry in the frame in the same voice, skipping grace notes.

Returns: The same as getPreviousSameV except grace notes are skipped.

◆ isSameEntry()

bool musx::dom::EntryInfoPtr::isSameEntry ( const EntryInfoPtr & src ) const

Returns whether the input and the current instance refer to the same entry.

Returns: false if either this or src is null and true if they are both non null and refer to the same entry.

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ BeamIterationMode

Constructor & Destructor Documentation

◆ EntryInfoPtr()

Member Function Documentation

◆ calcBeamContinuesLeftOverBarline()

◆ calcBeamContinuesRightOverBarline()

◆ calcBeamStubIsLeft()

◆ calcCrossStaffDirectionForAll()

◆ calcDisplaysAsRest()

◆ calcEntrySize()

◆ calcEntryStemSettings()

◆ calcGraceElapsedDuration()

◆ calcIfLayerSettingsApply()

◆ calcIsAuxiliaryPitchMarker()

◆ calcIsBeamedRestWorkaroundHiddenRest()

◆ calcIsBeamedRestWorkaroundVisibleRest()

◆ calcIsCue()

◆ calcIsFeatheredBeamStart()

◆ calcIsFullMeasureRest()

◆ calcIsGlissToGraceEntry()

◆ calcIsSamePitchContent()

◆ calcIsSamePitchContentAndDuration()

◆ calcIsTrillToGraceEntry()

◆ calcLowestBeamEnd()

◆ calcLowestBeamEndAcrossBarlines()

◆ calcLowestBeamStart()

◆ calcLowestBeamStub()

◆ calcTopBottomStaffPositions()

◆ calcUnbeamed()

◆ calcUpStem()

◆ calcUpStemDefault()

◆ createCurrentStaff()

◆ findBeamEnd()

◆ findBeamStartOrCurrent()

◆ findDisplayEntryForBeamOverBarline()

◆ findHiddenSourceForBeamOverBarline()

◆ findMainEntryForGraceNote()

◆ findTupletInfo()

◆ fromEntryNumber()

◆ fromPositionOrNull()

◆ getNextInLayer()

◆ getNextInVoice()

◆ getNextInVoiceWorkaroundAware()

◆ getNextSameV()

◆ getNextSameVNoGrace()

◆ getPreviousInLayer()

◆ getPreviousInVoice()

◆ getPreviousSameV()

◆ getPreviousSameVNoGrace()

◆ isSameEntry()