musx::dom::NoteInfoPtr Class Reference

Wraps an EntryInfo instance and a note index. More...

#include <Entries.h>

Classes
struct	ArpeggiatedTieInfo
	Metadata for a smart-shape arpeggiated tie match. More...
struct	NoteheadInfo
	The resolved font, character, size, and offset for a note's notehead. More...
struct	PseudoTieInfo
	Metadata for pseudo tie and pseudo tie-end detection. More...
struct	TieStandInSource
	Identifies one surrogate tie source matched for a note. More...

Public Member Functions
	NoteInfoPtr ()
	Default constructor.
	NoteInfoPtr (const EntryInfoPtr &entryInfo, size_t noteIndex)
	Constructor.
	operator bool () const noexcept
	Provides a boolean conversion based on whether the EntryInfoPtr is valid and the note index is valid.
bool	isSameNote (const NoteInfoPtr &src) const
	Returns whether the input and the current instance refer to the same note.
NoteInfoPtr	findEqualPitch (const EntryInfoPtr &entry) const
	Finds a note with the same pitch in the supplied entry.
MusxInstance< Note >	operator-> () const
	Allows -> access to the underlying Note instance.
EntryInfoPtr	getEntryInfo () const
	Gets the entry info for this note.
size_t	getNoteIndex () const
	Gets the note index for this note.
Note::NoteProperties	calcNoteProperties (NotePropertiesOptions options={}) const
	Calculates the note name, octave number, actual alteration, and staff position. The staff position takes into account percussion notes and their staff position override.
MusxInstance< others::PercussionNoteInfo >	calcPercussionNoteInfo () const
	Calculates the percussion note info for this note, if any.
NoteheadInfo	calcNoteheadInfo () const
	Resolves the effective font and character used to render this note's notehead, along with any size or position adjustments.
NoteInfoPtr	calcTieTo () const
	Calculates the note that this note could tie to. Check the return value's Note::tieEnd to see if there is actually a tie end. (Note that Finale shows a tie whether there Note::tieEnd is true or not.)
NoteInfoPtr	calcTieFrom (bool requireTie=true) const
	Calculates the note that this note could tie from.
CurveContourDirection	calcFreezeTieDirection (bool forTieEnd=false) const
	Calculates the user-frozen tie direction for this note, if any.
CurveContourDirection	calcEffectiveTieDirection (bool forTieEnd=false) const
	Determines whether this note has an outer tie at the specified endpoint.
bool	calcHasOuterTie (bool forTieEnd=false) const
	Determines whether this note has an outer tie at the specified endpoint.
bool	calcHasInnerTie (bool forTieEnd=false) const
	Determines whether this note has an inner tie at the specified endpoint.
StaffCmper	calcStaff () const
	Calculates the staff number, taking into account cross staffing.
std::unique_ptr< music_theory::Transposer >	createTransposer () const
	Creates a transposer for this Note instance.
NoteInfoPtr	getNext () const
	Gets the next note in a chord on the same entry.
NoteInfoPtr	getPrevious () const
	Gets the next note in a chord on the same entry.
bool	calcIsEnharmonicRespell () const
	Returns if this note is enharmonically respelled in the current part view.
std::pair< int, int >	calcDefaultEnharmonic () const
	Calculates the default enharmonic equivalent of this note. This is the value that Finale uses when details::NoteAlterations::enharmonic is true.
bool	calcIsEnharmonicRespellInAnyPart () const
	Calculates if any linked part has this note enharmonically respelled.
int	calcCrossStaffDirection (DeferredReference< MusxInstanceList< others::StaffUsed > > staffList={}) const
	Calculates if this note is cross-staffed and if so, which direction.
bool	calcIsIncludedInVoicing () const
	Returns true if this note is included in the part voicing. This function returns the correct value even if the document's PartVoicingPolicy is to ignore part voicing.
bool	calcIsTop () const
	Return true if this is the top note in the entry.
bool	calcIsBottom () const
	Return true if this is the bottom note in the entry.
std::optional< ArpeggiatedTieInfo >	calcArpeggiatedTieInfo () const
	If this note has a smart shape acting as an arpeggio tie, returns tie metadata. If this note is part of a chord, the function always returns std::nullopt.
PseudoTieInfo	calcPseudoLvTieInfo () const
	Calculates whether this note has a stand-in laissez-vibrer tie and returns tie metadata. For a match, the entry must have a number of qualifying stand-in items equal to the number of notes in the entry.
PseudoTieInfo	calcPseudoTieEndInfo () const
	Calculates whether this note has a stand-in tie-end and returns tie metadata. For a match, the entry must have a number of qualifying stand-in items equal to the number of notes in the entry.
std::vector< std::pair< NoteInfoPtr, CurveContourDirection > >	calcJumpTieContinuationsFrom () const
	Calculates the notes in prior measures that continue a "jump" tie into this note.

Detailed Description

Wraps an EntryInfo instance and a note index.

Constructor & Destructor Documentation

NoteInfoPtr()

musx::dom::NoteInfoPtr::NoteInfoPtr ( const EntryInfoPtr &  entryInfo, size_t  noteIndex  )

inline

Constructor.

Parameters

entryInfo	The entry info containing the note.
noteIndex	The index of this note within Entry::notes.

Member Function Documentation

calcArpeggiatedTieInfo()

std::optional< NoteInfoPtr::ArpeggiatedTieInfo > musx::dom::NoteInfoPtr::calcArpeggiatedTieInfo

(

)

const

If this note has a smart shape acting as an arpeggio tie, returns tie metadata. If this note is part of a chord, the function always returns std::nullopt.

Returns

Tie metadata when an arpeggiated stand-in tie exists; otherwise std::nullopt.

calcCrossStaffDirection()

int musx::dom::NoteInfoPtr::calcCrossStaffDirection

(

DeferredReference< MusxInstanceList< others::StaffUsed > >

staffList = {}

)

const

Calculates if this note is cross-staffed and if so, which 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 the note crosses upward to a higher staff
• 0 if the note is not cross-staffed
• −1 if the note crosses downward to a lower staff

calcDefaultEnharmonic()

std::pair< int, int > musx::dom::NoteInfoPtr::calcDefaultEnharmonic ( ) const

inline

Calculates the default enharmonic equivalent of this note. This is the value that Finale uses when details::NoteAlterations::enharmonic is true.

Normally you do not have to call this function directly. It is called inside calcNoteProperties. But the function is available if you need it.

Returns

A std::pair containing

• int: the enharmonic equivalent's displacement value relative to the tonic.
• int: the enharmonic equivalent's alteration value relative to the key signature.

calcEffectiveTieDirection()

CurveContourDirection musx::dom::NoteInfoPtr::calcEffectiveTieDirection

(

bool

forTieEnd = false

)

const

Determines whether this note has an outer tie at the specified endpoint.

Calculates the effective tie direction for this note, taking into account all options and overrides.

Parameters

forTieEnd

If forTieEnd is true, the direction for the tie-end stub on this note is returned. Otherwise the direction for the tie starting on this note is returned.

Returns

The contour direction that applies to the tie, or CurveContourDirection::Unspecified when the contour cannot be determined.

calcFreezeTieDirection()

CurveContourDirection musx::dom::NoteInfoPtr::calcFreezeTieDirection

(

bool

forTieEnd = false

)

const

Calculates the user-frozen tie direction for this note, if any.

Parameters

forTieEnd

If forTieEnd is true, the user-frozen direction for the tie-end stub on this note is returned. Otherwise the direction for the tie starting on this note is returned.

Returns

The contour direction if the tie is user-frozen, or CurveContourDirection::Unspecified when the contour has not been user-frozen.

calcHasInnerTie()

bool musx::dom::NoteInfoPtr::calcHasInnerTie

(

bool

forTieEnd = false

)

const

Determines whether this note has an inner tie at the specified endpoint.

If the note does not participate in a tie at the specified endpoint, this function returns false.

Parameters

forTieEnd

True to examine the tie end; false to examine the tie start.

Returns

True if the note has an inner tie at the specified endpoint; false if there is no tie or the tie is outer.

calcHasOuterTie()

bool musx::dom::NoteInfoPtr::calcHasOuterTie

(

bool

forTieEnd = false

)

const

Determines whether this note has an outer tie at the specified endpoint.

If the note does not participate in a tie at the specified endpoint, this function returns false.

Parameters

forTieEnd

True to examine the tie end; false to examine the tie start.

Returns

True if the note has an outer tie at the specified endpoint; false if there is no tie or the tie is inner.

calcIsBottom()

bool musx::dom::NoteInfoPtr::calcIsBottom

(

)

const

Return true if this is the bottom note in the entry.

Note

This function takes part voicing into account if the document's part voicing policy is PartVoicingPolicy::Apply.

calcIsEnharmonicRespellInAnyPart()

bool musx::dom::NoteInfoPtr::calcIsEnharmonicRespellInAnyPart

(

)

const

Calculates if any linked part has this note enharmonically respelled.

Returns

True if a part exists with the note enharmonically respelled, otherwise false.

calcIsTop()

bool musx::dom::NoteInfoPtr::calcIsTop

(

)

const

Return true if this is the top note in the entry.

Note

This function takes part voicing into account if the document's part voicing policy is PartVoicingPolicy::Apply.

calcJumpTieContinuationsFrom()

std::vector< std::pair< NoteInfoPtr, CurveContourDirection > > musx::dom::NoteInfoPtr::calcJumpTieContinuationsFrom

(

)

const

Calculates the notes in prior measures that continue a "jump" tie into this note.

A jump tie is a tie that skips over intervening measures due to repeat or navigation (e.g., back to a prior bar or forward to a coda). The implementation should identify the source note that ties into this note by walking the playback path, not just the immediate previous measure.

Returns

A list of tied-from notes and their contour directions if any continuations are found; otherwise empty.

calcNoteheadInfo()

NoteInfoPtr::NoteheadInfo musx::dom::NoteInfoPtr::calcNoteheadInfo

(

)

const

Resolves the effective font and character used to render this note's notehead, along with any size or position adjustments.

Resolution is in order of precedence:

• A per-note details::NoteAlterations::altNhead override, if one is set for this note (with its own font override, if details::NoteAlterations::useOwnFont is set).
• The percussion note's shape, if this note is on a percussion staff with a mapped percussion note. (See calcPercussionNoteInfo.)
• The staff's shape-note convention, if shape notes are in effect for the staff. (See others::Staff::getNoteShapes.)
• Otherwise, the document's default notehead codepoints for the note's duration category. (See #options::MusicSymbolOptions.)

In every case except a custom-font #details::NoteAlterations override, the font is others::Staff::noteFont if the staff specifies a custom notehead font, or the document's default options::FontOptions::FontType::Noteheads font otherwise.

Returns

The resolved notehead info. This function always returns a usable result.

calcNoteProperties()

Note::NoteProperties musx::dom::NoteInfoPtr::calcNoteProperties

(

NotePropertiesOptions

options = {}

)

const

Calculates the note name, octave number, actual alteration, and staff position. The staff position takes into account percussion notes and their staff position override.

Note

In Finale, the default whole rest staff position is the middle staff line. Other music notation systems frequently expect the standard whole rest staff position to be the second line from the top. You may need to interpolate the staff position returned by calcNoteProperties for whole rests.

Parameters

options

Calculation options, including pitch representation, enharmonic behavior, and cross-staff handling.

Returns

#Note::NoteProperties

calcPercussionNoteInfo()

MusxInstance< others::PercussionNoteInfo > musx::dom::NoteInfoPtr::calcPercussionNoteInfo

(

)

const

Calculates the percussion note info for this note, if any.

Returns

If the note is on a percussion staff and has percussion note info assigned, returns it. Otherwise nullptr.

calcTieFrom()

NoteInfoPtr musx::dom::NoteInfoPtr::calcTieFrom

(

bool

requireTie = true

)

const

Calculates the note that this note could tie from.

Parameters

requireTie

If requireTie is true, the returned value must have its Note::tieStart flag set to true. You can set requireTie to false to find the potential note this note might be tied from.

Returns

The candidate note or an empty NoteInfoPtr if no candidate was found.

calcTieTo()

NoteInfoPtr musx::dom::NoteInfoPtr::calcTieTo

(

)

const

Calculates the note that this note could tie to. Check the return value's Note::tieEnd to see if there is actually a tie end. (Note that Finale shows a tie whether there Note::tieEnd is true or not.)

Returns

The candidate note or an empty NoteInfoPtr if no candidate was found.

createTransposer()

std::unique_ptr< music_theory::Transposer > musx::dom::NoteInfoPtr::createTransposer

(

)

const

Creates a transposer for this Note instance.

Returns

A unique pointer to a transposer for this Note.

findEqualPitch()

NoteInfoPtr musx::dom::NoteInfoPtr::findEqualPitch

(

const EntryInfoPtr &

entry

)

const

Finds a note with the same pitch in the supplied entry.

Parameters

entry

the entry to search

Returns

The found note or an null instance of NoteInfoPtr.

getNext()

NoteInfoPtr musx::dom::NoteInfoPtr::getNext ( ) const

inline

Gets the next note in a chord on the same entry.

Returns

The next note or nullptr if none.

getPrevious()

NoteInfoPtr musx::dom::NoteInfoPtr::getPrevious ( ) const

inline

Gets the next note in a chord on the same entry.

Returns

The next note or nullptr if none.

isSameNote()

bool musx::dom::NoteInfoPtr::isSameNote ( const NoteInfoPtr &  src ) const

inline

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

Parameters

src	The EntryInfoPtr to compare with.