Represents the definition of a Finale staff. More...

#include <Others.h>

Inheritance diagram for musx::dom::others::Staff:

Classes
class	ChromaticTransposition
	Represents chromatic transposition details. More...

class	KeySigTransposition
	Represents key signature transposition details. More...

class	Transposition
	Encapsulates transposition options for a staff. More...

Public Types
enum class	AutoNumberingStyle { ArabicSuffix , RomanSuffix , OrdinalPrefix , AlphaSuffix , ArabicPrefix }
	Enum for auto-numbering style. Auto-numbering is based on instUuid. More...

enum class	StemDirection { Default , AlwaysUp , AlwaysDown }
	Enum for staff-level stem direction override. More...

Public Types inherited from musx::dom::Base
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.

Public Member Functions
	Staff (const DocumentWeakPtr &document, Cmper partId, ShareMode shareMode, Cmper cmper)
	Constructor function.

std::string	getFullName (util::EnigmaString::AccidentalStyle accidentalStyle=util::EnigmaString::AccidentalStyle::Ascii) const
	Returns the full staff name without Enigma tags.

std::string	getAbbreviatedName (util::EnigmaString::AccidentalStyle accidentalStyle=util::EnigmaString::AccidentalStyle::Ascii) const
	Returns the abbreviated staff name without Enigma tags.

std::shared_ptr< MultiStaffInstrumentGroup >	getMultiStaffInstGroup () const
	Returns the MultiStaffInstrumentGroup for this staff if it is part of one. Otherwise nullptr.

std::string	getFullInstrumentName (util::EnigmaString::AccidentalStyle accidentalStyle=util::EnigmaString::AccidentalStyle::Ascii, bool preferStaffName=false) const
	Returns the full instrument name for this staff without Enigma tags and with autonumbering (if any)

std::string	getAbbreviatedInstrumentName (util::EnigmaString::AccidentalStyle accidentalStyle=util::EnigmaString::AccidentalStyle::Ascii, bool preferStaffName=false) const
	Returns the abbreviated instrument name for this staff without Enigma tags and with autonumbering (if any)

bool	showNamesForPart (Cmper partId) const
	Returns if names should be shown for the specified part.

std::string	addAutoNumbering (const std::string &plainName) const
	Add auto numbering as a prefix or suffix, if needed.

ClefIndex	calcClefIndexAt (MeasCmper measureId, Edu position) const
	Returns the clef in this staff at the specified location.

ClefIndex	calcFirstClefIndex () const
	Returns the first clef in this staff.

int	calcMiddleStaffPosition () const
	Returns the middle staff position. For staves with even numbers of lines, it is the middle space.

void	integrityCheck () override
	Allows a class to determine if it has been properly contructed by the factory and fix issues that it can, such as creating default instances of contained classes.

bool	requireAllFields () const override
	Specifies if the parser should alert (print or throw) when an unknown xml tag is found for this class.

Public Member Functions inherited from musx::dom::OthersBase
Cmper	getCmper () const
	Gets the `cmper` key value.

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

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

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

Cmper	getPartId () const
	Gets the partId for this instance (or 0 for score)

std::shared_ptr< others::PartDefinition >	getPartDefinition () const
	Gets the others::PartDefinition corresponding to getPartId.

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.

Static Public Member Functions
static void	calcAutoNumberValues (const DocumentPtr &document)
	Get the auto-numbering value for this staff, if applicable.

static ClefIndex	calcFirstClefIndex (const DocumentPtr &document, Cmper partId, InstCmper staffCmper)
	Returns the first clef in the specified staff in the document.

static const xml::XmlElementArray< Staff > &	xmlMappingArray ()
	Required for musx::factory::FieldPopulator.

Public Attributes
ClefIndex	defaultClef {}
	Index of default clef for the staff.

ClefIndex	transposedClef {}
	Index of transposed clef for the staff. Only used if Transposition::setToClef is true.

std::optional< int >	staffLines {}
	Number of lines in the staff (if no custom staff)

std::optional< std::vector< int > >	customStaff
	A list of stafflines from 0..26 where a standard 5-line staff is values 11, 12, 13, 14, 15.

Evpu	lineSpace {}
	Distance between staff lines.

std::string	instUuid
	Unique identifier for the type of instrument.

bool	floatKeys {}
	"Independent Key Signature"

bool	floatTime {}
	"Independent Time Signature"

bool	hasStyles {}
	Indicates that this staff has staff style assignments.

bool	showNameInParts {}
	"Display Staff Name in Parts" (xml node is `<showNameParts>`)

std::shared_ptr< Transposition >	transposition
	Transposition details, if non-null.

bool	hideNameInScore {}
	Inverse of "Display Staff Name in Score" (xml node is `<hideStfNameInScore>`)

Evpu	topBarlineOffset {}
	Offset for the top barline.

Evpu	botBarlineOffset {}
	Offset for the bottom barline.

Evpu	dwRestOffset {}
	Offset for downstem rests.

Evpu	wRestOffset {}
	Offset for whole rests.

Evpu	hRestOffset {}
	Offset for half rests.

Evpu	otherRestOffset {}
	Offset for other rests.

int	stemReversal {}
	Stem reversal value.

Cmper	fullNameTextId {}
	Full name TextBlock ID. (xml node is `<fullName>`)

Cmper	abbrvNameTextId {}
	Abbreviated name TextBlock ID. (xml node is `<abbrvName>`)

Evpu	botRepeatDotOff {}
	Offset for bottom repeat dots.

Evpu	topRepeatDotOff {}
	Offset for top repeat dots.

Evpu	vertTabNumOff {}
	Vertical offset for tab number.

bool	hideStems {}
	Inverse of "Display Stems".

bool	hideBeams {}
	Inverse of "Show Beams".

StemDirection	stemDirection {}
	stem direction for staff (xml node is `<stemDir>`)

AutoNumberingStyle	autoNumbering {}
	Autonumbering style if useAutoNumbering is true. (xml node is `<autoNum>`)

bool	useAutoNumbering {}
	Whether names should be auto-numbered. (xml node is `<useAutoNum>`)

bool	hideKeySigsShowAccis {}
	"Hide Key Signature and Show Accidentals" transposition option.

Cmper	multiStaffInstId {}

std::optional< int >	autoNumberValue
	Calculated autonumbering value. It is computed by calcAutoNumberValues.

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

Additional Inherited Members
Protected Member Functions inherited from musx::dom::OthersBase
	OthersBase (const DocumentWeakPtr &document, Cmper partId, ShareMode shareMode, Cmper cmper, std::optional< Inci > inci=std::nullopt)
	Constructs an OthersBase object.

Protected Member Functions inherited from musx::dom::Base
	Base (const DocumentWeakPtr &document, Cmper partId, ShareMode shareMode)
	Constructs the base class and enforces the static constexpr XmlNodeName.

Base &	operator= (const Base &)
	assignment constructor: m_unlinkedNodes is intentionally omitted

Detailed Description

Represents the definition of a Finale staff.

The cmper is the staff ID. This class is identified by the XML node name "staffSpec".

Member Enumeration Documentation

◆ AutoNumberingStyle

enum class musx::dom::others::Staff::AutoNumberingStyle

strong

Enum for auto-numbering style. Auto-numbering is based on instUuid.

Enumerator
ArabicSuffix	Arabic numeral suffix (default). May not appear in xml.
RomanSuffix	Roman numeral suffix.
OrdinalPrefix	Ordinal number prefix: 1st 2nd 3rd, ...
AlphaSuffix	Alphabetic suffix.
ArabicPrefix	Arabic numeral prefix (with dot): 1. 2. 3. ...

◆ StemDirection

enum class musx::dom::others::Staff::StemDirection

strong

Enum for staff-level stem direction override.

Enumerator
Default	the default (may not occur in xml)
AlwaysUp	stems are always up on this staff
AlwaysDown	stems are always down on this staff

Member Function Documentation

◆ addAutoNumbering()

std::string musx::dom::others::Staff::addAutoNumbering ( const std::string & plainName ) const

Add auto numbering as a prefix or suffix, if needed.

Parameters

plainName The name (full or abbreviated) to which to add the auto numbering

Returns: Auto numbered name.

◆ calcAutoNumberValues()

void musx::dom::others::Staff::calcAutoNumberValues ( const DocumentPtr & document )

static

Get the auto-numbering value for this staff, if applicable.

Calculates autoNumberValue for every staff based on the occurrences of the instrument UUID and in each staff instance. If numbering is not applicable (e.g., auto numbering is disabled, the UUID is empty, or there is only one instance), autoNumberValue has no value.

This function is called by the DocumentFactory when the document is created.

◆ calcClefIndexAt()

ClefIndex musx::dom::others::Staff::calcClefIndexAt	(	MeasCmper	measureId,
		Edu	position
	)		const

Returns the clef in this staff at the specified location.

Parameters

measureId	The measure of the location
position	The Edu elapsed time with the measure

Todo:: Take into accound clef changes caused by transposition.

◆ calcFirstClefIndex()

ClefIndex musx::dom::others::Staff::calcFirstClefIndex	(	const DocumentPtr &	document,
		Cmper	partId,
		InstCmper	staffCmper
	)

static

Returns the first clef in the specified staff in the document.

Parameters

document	the document to search
partId	the linked part to search
staffCmper	the staff cmper to search

◆ getAbbreviatedInstrumentName()

std::string musx::dom::others::Staff::getAbbreviatedInstrumentName	(	util::EnigmaString::AccidentalStyle	accidentalStyle = `util::EnigmaString::AccidentalStyle::Ascii`,
		bool	preferStaffName = `false`
	)		const

Returns the abbreviated instrument name for this staff without Enigma tags and with autonumbering (if any)

Note: Ordinal prefix numbering is currently supported only for English.

Parameters

accidentalStyle	The style for accidental subsitution in names like "Clarinet in Bb".
preferStaffName	When true, use the staff name if there is one (rather than the multi-instrument group name)

◆ getAbbreviatedName()

std::string musx::dom::others::Staff::getAbbreviatedName ( util::EnigmaString::AccidentalStyle accidentalStyle = util::EnigmaString::AccidentalStyle::Ascii ) const

Returns the abbreviated staff name without Enigma tags.

Parameters

accidentalStyle The style for accidental subsitution in names like "Clarinet in Bb".

◆ getFullInstrumentName()

std::string musx::dom::others::Staff::getFullInstrumentName	(	util::EnigmaString::AccidentalStyle	accidentalStyle = `util::EnigmaString::AccidentalStyle::Ascii`,
		bool	preferStaffName = `false`
	)		const

Returns the full instrument name for this staff without Enigma tags and with autonumbering (if any)

Note: Ordinal prefix numbering is currently supported only for English.

Parameters

accidentalStyle	The style for accidental subsitution in names like "Clarinet in Bb".
preferStaffName	When true, use the staff name if there is one (rather than the multi-instrument group name)

◆ getFullName()

std::string musx::dom::others::Staff::getFullName ( util::EnigmaString::AccidentalStyle accidentalStyle = util::EnigmaString::AccidentalStyle::Ascii ) const

Returns the full staff name without Enigma tags.

Parameters

accidentalStyle The style for accidental subsitution in names like "Clarinet in Bb".

◆ integrityCheck()

void musx::dom::others::Staff::integrityCheck ( )

inlineoverridevirtual

Allows a class to determine if it has been properly contructed by the factory and fix issues that it can, such as creating default instances of contained classes.

The default implementation should always be called inside an overridden implementation.

Exceptions

musx::dom::integrity_error if there is a problem.

Reimplemented from musx::dom::Base.

Reimplemented in musx::dom::others::StaffStyle.

◆ requireAllFields()

bool musx::dom::others::Staff::requireAllFields ( ) const

inlineoverridevirtual

Specifies if the parser should alert (print or throw) when an unknown xml tag is found for this class.

Some classes make it difficult to discover all the possible xml tags that might be used for all its options. An example is others::TextBlock. By overriding this function, a class can allow its members to be discovered as needed without causing error messages or throwing exceptions.

Remarks: This value only escapes errors on fields. Enum values must still have all values provided to avoid error messages or exceptions.

Reimplemented from musx::dom::Base.

Reimplemented in musx::dom::others::StaffStyle.

Member Data Documentation

◆ multiStaffInstId

Cmper musx::dom::others::Staff::multiStaffInstId {}

Calculated cmper for MultiStaffInstrumentGroup, if any. This value is not in the xml. It is set by the factory with the Resolver function for MultiStaffInstrumentGroup.

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ AutoNumberingStyle

◆ StemDirection

Member Function Documentation

◆ addAutoNumbering()

◆ calcAutoNumberValues()

◆ calcClefIndexAt()

◆ calcFirstClefIndex()

◆ getAbbreviatedInstrumentName()

◆ getAbbreviatedName()

◆ getFullInstrumentName()

◆ getFullName()

◆ integrityCheck()

◆ requireAllFields()

Member Data Documentation

◆ multiStaffInstId