musx::dom::NoteInfoPtr Class Reference

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

#include <Entries.h>

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 (EnharmonicOverride enharmonicOverride=EnharmonicOverride::None, bool alwaysUseEntryStaff=false) const
	Calculates the note name, octave number, actual alteration, and staff position. This function does not take into account percussion notes and their staff position override. To get the staff position taking into account percussion notes, use calcStaffPosition.
Note::NoteProperties	calcNotePropertiesConcert (bool alwaysUseEntryStaff=false) const
	Calculates the note name, octave number, actual alteration, and staff position for the concert pitch of the note. This function does not take into account percussion notes and their staff position override. To discover if a note is a percussion note, call calcPercussionNoteInfo. If it returns non-null, use that for staff position instead of this function.
Note::NoteProperties	calcNotePropertiesInView (bool alwaysUseEntryStaff=false) const
	Calculates the note name, octave number, actual alteration, and staff position for the pitch of the note in the currently selected "Display In Concert Pitch" view for the current part. This may be particularly useful with non-floating rests, but it can be used with any note. As with other versions of the function, it does not handle the staff position override of percussion notes.
MusxInstance< others::PercussionNoteInfo >	calcPercussionNoteInfo () const
	Calculates the percussion note info for this note, if any.
int	calcStaffPosition () const
	Calculates the staff position for this note, taking into account percussion notes.
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	calcEffectiveTieDirection (bool forTieEnd=false) const
	Calculates the effective tie direction for this note, taking into account all options and overrides.
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.
NoteInfoPtr	calcArpeggiatedTieToNote (CurveContourDirection *tieDirection=nullptr) const
	If this note has a smart shape acting as an arpeggio tie, return the tied-to note. If this note is part of a chord, the function always returns null.
bool	calcHasPseudoLvTie (CurveContourDirection *tieDirection=nullptr) const
	Calculates if this note has a smart shape, shape expression, or shape articulation acting as a laissez vibrer tie. For any of these to count, the entry must have a number of these stand-in items equal to the number of notes in the entry.
bool	calcHasPseudoTieEnd (CurveContourDirection *tieDirection=nullptr) const
	Calculates if this note has a smart shape, shape expression, or shape articulation acting as a tie end. For any of these to count, the entry must have a number of these 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

calcArpeggiatedTieToNote()

NoteInfoPtr musx::dom::NoteInfoPtr::calcArpeggiatedTieToNote

(

CurveContourDirection *

tieDirection = nullptr

)

const

If this note has a smart shape acting as an arpeggio tie, return the tied-to note. If this note is part of a chord, the function always returns null.

Parameters

[out]

tieDirection

Optional output parameter receiving the tie's curve contour direction. It is set to CurveContourDirection::Down for under ties, CurveContourDirection::Up for over ties, or CurveContourDirection::Unspecified if the contour cannot be determined.

Returns

The arpeggio-tied note, or null if no such tie exists or this note is part of a chord.

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

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.

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.

calcHasPseudoLvTie()

bool musx::dom::NoteInfoPtr::calcHasPseudoLvTie

(

CurveContourDirection *

tieDirection = nullptr

)

const

Calculates if this note has a smart shape, shape expression, or shape articulation acting as a laissez vibrer tie. For any of these to count, the entry must have a number of these stand-in items equal to the number of notes in the entry.

Parameters

[out]

tieDirection

Optional output parameter receiving the tie's curve contour direction. It is set to CurveContourDirection::Down for under ties, CurveContourDirection::Up for over ties, or CurveContourDirection::Unspecified if the contour cannot be determined.

Returns

True if a pseudo laissez vibrer tie exists; otherwise false.

calcHasPseudoTieEnd()

bool musx::dom::NoteInfoPtr::calcHasPseudoTieEnd

(

CurveContourDirection *

tieDirection = nullptr

)

const

Calculates if this note has a smart shape, shape expression, or shape articulation acting as a tie end. For any of these to count, the entry must have a number of these stand-in items equal to the number of notes in the entry.

Parameters

[out]

tieDirection

Optional output parameter receiving the tie's curve contour direction. It is set to CurveContourDirection::Down for under ties, CurveContourDirection::Up for over ties, or CurveContourDirection::Unspecified if the contour cannot be determined.

Returns

True if a pseudo tie end exists; otherwise false.

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.

calcNoteProperties()

Note::NoteProperties musx::dom::NoteInfoPtr::calcNoteProperties	(	EnharmonicOverride	enharmonicOverride = EnharmonicOverride::None,
		bool	alwaysUseEntryStaff = false
	)		const

Calculates the note name, octave number, actual alteration, and staff position. This function does not take into account percussion notes and their staff position override. To get the staff position taking into account percussion notes, use calcStaffPosition.

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

enharmonicOverride	Overrides the enharmonic respelling behavior. Use EnharmonicOverride::None to defer to the score/part data (default), EnharmonicOverride::Respell to force respelling, or EnharmonicOverride::NoRespell to prevent respelling even if the part would otherwise respell.
alwaysUseEntryStaff	If true, the entry is not checked for cross-staff staffing. Normally you omit this.

Returns

Note::NoteProperties

calcNotePropertiesConcert()

Note::NoteProperties musx::dom::NoteInfoPtr::calcNotePropertiesConcert

(

bool

alwaysUseEntryStaff = false

)

const

Calculates the note name, octave number, actual alteration, and staff position for the concert pitch of the note. This function does not take into account percussion notes and their staff position override. To discover if a note is a percussion note, call calcPercussionNoteInfo. If it returns non-null, use that for staff position instead of this function.

Parameters

alwaysUseEntryStaff

If true, the entry is not checked for cross-staff staffing. Normally you omit this.

Returns

Note::NoteProperties

calcNotePropertiesInView()

Note::NoteProperties musx::dom::NoteInfoPtr::calcNotePropertiesInView

(

bool

alwaysUseEntryStaff = false

)

const

Calculates the note name, octave number, actual alteration, and staff position for the pitch of the note in the currently selected "Display In Concert Pitch" view for the current part. This may be particularly useful with non-floating rests, but it can be used with any note. As with other versions of the function, it does not handle the staff position override of percussion notes.

Parameters

alwaysUseEntryStaff

If true, the entry is not checked for cross-staff staffing. Normally you omit this.

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.

calcStaffPosition()

int musx::dom::NoteInfoPtr::calcStaffPosition

(

)

const

Calculates the staff position for this note, taking into account percussion notes.

Returns

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.