Assigns an articulation to an entry. More...

#include <Details.h>

Inheritance diagram for musx::dom::details::ArticulationAssign:

Classes
class	SelectedSymbolContext
	Provides information about the best analysis as to which articulation symbol in being used on this assignment. More...

Public Member Functions
	ArticulationAssign (const DocumentWeakPtr &document, Cmper partId, ShareMode shareMode, EntryNumber entnum, Inci inci)
	Constructor function.

NoteInfoPtr	calcAssociatedNote (const EntryInfoPtr &entryInfo) const
	Heuristically finds the note in the entry that this articulation assignment appears to be associated with.

std::optional< utils::PseudoTieShapeInfo >	calcIsPseudoTie (utils::PseudoTieMode mode, const EntryInfoPtr &forStartEntry) const
	Calculates the pseudo-tie shape info if this articulation is acting as a pseudo tie for the specified mode.

std::optional< SelectedSymbolContext >	calcSelectedSymbolContext (const EntryInfoPtr &entryInfo) const
	Resolves the symbol information used by this articulation assignment on the specified entry.

Public Member Functions inherited from musx::dom::EntryDetailsBase
EntryNumber	getEntryNumber () const
	Gets the `entnum` key value.

Public Member Functions inherited from musx::dom::DetailsBase
	DetailsBase (const DetailsBase &)=default
	explicit default copy constructor

	DetailsBase (DetailsBase &&) noexcept=default
	explicit default move constructor

Cmper	getCmper1 () const
	Gets the `cmper1` key value.

Cmper	getCmper2 () const
	Gets the `cmper2` key value.

std::optional< Inci >	getInci () const
	Gets the optional array index (`inci`).

Cmper	getRequestedPartId () const
	If this instance was retrieved from an object pool, it contains the part ID that was used to retrieve it. If this value is different than getSourcePartId, then this instance is a copy of the pool instance.

Public Member Functions inherited from musx::dom::EnigmaBase
Cmper	getSourcePartId () const
	Gets the source partId for this instance. If an instance is fully shared with the score, the source is SCORE_PARTID. If an instance is partially shared or non shared, the source is the ID of the part that sourced it.

ShareMode	getShareMode () const
	Gets the sharing mode for this instance.

const SharedNodes &	getUnlinkedNodes () const
	Gets the unlinked nodes for this instance. (Only populated for `ShareMode::Partial`)

void	addUnlinkedNode (const std::string &nodeName)
	Adds a shared node for this instance.

virtual void	integrityCheck (const std::shared_ptr< EnigmaBase > &ptrToThis)
	Performs a final consistency check after population.

virtual bool	requireAllFields () const
	Returns true if all fields are required for valid input.

Public Member Functions inherited from musx::dom::DocumentElement
virtual	~DocumentElement () noexcept(false)=default
	Virtual destructor for polymorphic behavior.

DocumentPtr	getDocument () const
	Gets a reference to the Document.

Cmper	getPartId () const
	Gets the part id associated with this instance.

Static Public Member Functions
static const xml::XmlElementArray< ArticulationAssign > &	xmlMappingArray ()
	Required for musx::factory::FieldPopulator.

Public Attributes
Cmper	articDef {}
	The articulation definition ID.

Evpu	horzOffset {}
	Horizontal offset from the default position.

Evpu	horzAdd {}
	Horizontal displacement for character copying. (E.g., trill lines)

Evpu	vertOffset {}
	Vertical offset from the default position.

Evpu	vertAdd {}
	Vertical displacement for character copying. (E.g., arpeggiated chord lines)

bool	overridePlacement {}
	Whether the default placement is overridden.

bool	aboveEntry {}
	When overridePlacement is true: whether the articulation is forced above or below the entry.

bool	hide {}
	Inverse of "Show" option.

bool	neverStack {}
	Whether the articulation should never stack relative to others.

bool	avoidSlur {}
	Whether the articulation should avoid slurs.

int	numSlursAvoided {}
	Number of slurs avoided. Used internally by Finale's stacking algorithm.

Static Public Attributes
static constexpr std::string_view	XmlNodeName = "articAssign"
	The XML node name for this type.

Additional Inherited Members
Public Types inherited from musx::dom::EntryDetailsBase
enum class	StemSelection { MatchEntry , UpStem , DownStem , Any }
	The options for choosing which version to retrieve for stem-specific details. More...

Public Types inherited from musx::dom::EnigmaBase
enum class	ShareMode { All , Partial , None }
	Describes how this instance is shared between part and score. More...

using	SharedNodes = std::set< std::string >
	The container type for shared nodes.

Protected Member Functions inherited from musx::dom::EntryDetailsBase
	EntryDetailsBase (const DocumentWeakPtr &document, Cmper partId, ShareMode shareMode, EntryNumber entnum, std::optional< Inci > inci=std::nullopt)
	Constructs a EntryDetailsBase object.

Protected Member Functions inherited from musx::dom::DetailsBase
	DetailsBase (const DocumentWeakPtr &document, Cmper partId, ShareMode shareMode, Cmper cmper1, Cmper cmper2, std::optional< Inci > inci=std::nullopt)
	Constructs a DetailsBase object.

DetailsBase &	operator= (const DetailsBase &other)
	Assignment operator delegates to base, preserving OthersBase state.

DetailsBase &	operator= (DetailsBase &&other) noexcept
	Assignment operator delegates to base, preserving OthersBase state.

Protected Member Functions inherited from musx::dom::EnigmaBase
	EnigmaBase (const DocumentWeakPtr &document, Cmper partId, ShareMode shareMode)
	Constructs the base class.

	EnigmaBase (const EnigmaBase &)=default
	explicit default copy constructor

	EnigmaBase (EnigmaBase &&) noexcept=default
	explicit default move constructor

EnigmaBase &	operator= (const EnigmaBase &)
	no-op copy assignment operator allows subclasses to copy their values.

EnigmaBase &	operator= (EnigmaBase &&) noexcept
	no-op move assignment operator allows subclasses to move their values.

Protected Member Functions inherited from musx::dom::DocumentElement
	DocumentElement (const DocumentWeakPtr &document, Cmper partId)
	Constructs the document element.

	DocumentElement (const DocumentElement &)=default
	explicit default copy constructor

	DocumentElement (DocumentElement &&) noexcept=default
	explicit default move constructor

DocumentElement &	operator= (const DocumentElement &)
	no-op copy assignment operator allows subclasses to copy their values.

DocumentElement &	operator= (DocumentElement &&) noexcept
	no-op move assignment operator allows subclasses to move their values.

Static Protected Member Functions inherited from musx::dom::EntryDetailsBase
template<typename EDUP , typename EDDOWN , typename EDBASE >
static MusxInstance< EDBASE >	getStemDependentDetail (const EntryInfoPtr &entryInfo, StemSelection stemSelection)
	Implement retrieval of stem-specific details. (Actual functions are defined per stem-specific class)

Detailed Description

Assigns an articulation to an entry.

Entry::articDetail is set if the entry has any articulations.

Constructor & Destructor Documentation

◆ ArticulationAssign()

musx::dom::details::ArticulationAssign::ArticulationAssign	(	const DocumentWeakPtr &	document,
		Cmper	partId,
		ShareMode	shareMode,
		EntryNumber	entnum,
		Inci	inci
	)

inlineexplicit

Constructor function.

Parameters

document	A weak pointer to the associated document.
partId	The part that this is for (probably always 0).
shareMode	The sharing mode for this ArticulationAssign (probably always ShareMode::All)
entnum	The entry number of this assignment.
inci	The 0-based inci. Each articulation assignment has a separate instance.

Member Function Documentation

◆ calcAssociatedNote()

NoteInfoPtr musx::dom::details::ArticulationAssign::calcAssociatedNote ( const EntryInfoPtr & entryInfo ) const

Heuristically finds the note in the entry that this articulation assignment appears to be associated with.

Finale cannot model an articulation attached to a specific note of a chord, but users approximate it by giving the articulation definition manual vertical positioning and setting vertOffset so that the symbol aligns with the staff position of the target note, where zero is the staff position of the note furthest from the stem. This function reverses that convention: it rounds vertOffset to the nearest staff position and returns the note (if any) at exactly that position. Definition-level offsets are ignored, since they orient the symbol relative to the selected note rather than select it.

Note: This is a heuristic classification aid. Combine it with other signals (such as the glyph) before concluding that an articulation is note-associated.

Parameters

entryInfo The entry to which this articulation is assigned. Its entry number must match this assignment's entry number.

Returns: The associated note, or an empty NoteInfoPtr if the heuristic does not identify one.

Exceptions

std::logic_error if entryInfo does not match this assignment's entry number.

◆ calcIsPseudoTie()

std::optional< utils::PseudoTieShapeInfo > musx::dom::details::ArticulationAssign::calcIsPseudoTie	(	utils::PseudoTieMode	mode,
		const EntryInfoPtr &	forStartEntry
	)		const

Calculates the pseudo-tie shape info if this articulation is acting as a pseudo tie for the specified mode.

Returns: The pseudo-tie shape info when a qualifying shape exists; otherwise std::nullopt.

◆ calcSelectedSymbolContext()

std::optional< details::ArticulationAssign::SelectedSymbolContext > musx::dom::details::ArticulationAssign::calcSelectedSymbolContext ( const EntryInfoPtr & entryInfo ) const

Resolves the symbol information used by this articulation assignment on the specified entry.

The returned symbol context reflects the assignment-level placement semantics used by this library. Manual placement cases are evaluated exactly from the assignment data. Automatic placement cases use the best available policy-based interpretation of Finale's settings and may differ from Finale's final rendered side after layout-dependent positioning or manual dragging.

Returns: The resolved symbol context, or std::nullopt if the entry context or articulation definition cannot be resolved.

Classes

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes