musx::dom::others::SmartShape Class Reference

Represents a Finale smart shape. More...

#include <SmartShape.h>

Inheritance diagram for musx::dom::others::SmartShape:

Classes
class	TerminationSeg
	Represents the termination segment of the smart shape. More...

Public Types
enum class	ShapeType : int {   SlurDown = 0 , SlurUp , Decrescendo , Crescendo ,   OctaveDown , OctaveUp , DashLineUp , DashLineDown ,   DashSlurDown , DashSlurUp , DashLine , SolidLine ,   SolidLineDown , SolidLineUp , Trill , SlurAuto ,   DashSlurAuto , TrillExtension , SolidLineDownBoth , SolidLineUpBoth ,   TwoOctaveDown , TwoOctaveUp , DashLineDownBoth , DashLineUpBoth ,   Glissando = 25 , TabSlide , BendHat , BendCurve ,   CustomLine , SolidLineUpLeft , SolidLineDownLeft , DashLineUpLeft ,   DashLineDownLeft , SolidLineUpDown , SolidLineDownUp , DashLineUpDown ,   DashLineDownUp , Hyphen , WordExtension , DashContourSlurDown ,   DashContourSlurUp , DashContourSlurAuto }
	All the smart shape types supported by Finale. More...
enum class	EngraverSlurState { Auto , Off , On }
	The selection for engraver slurs. (Only applicable for slurs.) More...
enum class	SlurAvoidAccidentalsState { Auto , Off , On , Invalid = -1 }
	The selection whether this shape avoids accidentals. (Only applicable for slurs.) More...
enum class	SystemBreakType { Same , Opposite }
	How this shape breaks across systems. Represents the choice between "Make Horizontal Over System Break" and "Maintain Angle Over System Break" in the Finale U.I. More...
enum class	LyricTextType { None , Verse , Chorus , Section }
	The lyric text type if this is a lyrics smart shape. 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
	SmartShape (const DocumentWeakPtr &document, Cmper partId, ShareMode shareMode, Cmper cmper)
	Constructor function.
bool	calcAppliesTo (const EntryInfoPtr &entryInfo) const
	Calculates if the smart shape applies to the specified entry.
void	integrityCheck (const std::shared_ptr< Base > &ptrToThis) 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.
Public Member Functions inherited from musx::dom::OthersBase
	OthersBase (const OthersBase &)=default
	explicit default copy constructor
	OthersBase (OthersBase &&) noexcept=default
	explicit default move constructor
Cmper	getCmper () const
	Gets the cmper 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::Base
virtual	~Base () noexcept(false)=default
	Virtual destructor for polymorphic behavior.
DocumentPtr	getDocument () const
	Gets a reference to the Document.
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 bool	requireAllFields () const
	Specifies if the parser should alert (print or throw) when an unknown xml tag is found for this class.

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

Public Attributes
ShapeType	shapeType {}
	Type of smart shape.
bool	entryBased {}
	Whether the shape is entry-based.
bool	rotate {}
	Purpose unknown: always set for slurs.
bool	noPresetShape {}
	Legacy flag that may no longer be used.
bool	makeHorz {}
	"Make Horizontal"
bool	noPushEndStart {}
	Legacy flag that should always be false in modern files going back to at least Finale 2000.
bool	makeVert {}
	This option has no obvious setting in the Finale U.I. A plugin could perhaps set it, but whether it works is untested.
EngraverSlurState	engraverSlurState {}
	The engraver slur setting if this is a slur.
SlurAvoidAccidentalsState	slurAvoidAcciState {}
	The avoid accidentals settings if this is a slur.
SystemBreakType	yBreakType {}
	Whether a system break should honor makeHorz or do its opposite.
std::shared_ptr< TerminationSeg >	startTermSeg
	Start termination segment.
std::shared_ptr< TerminationSeg >	endTermSeg
	End termination segment.
std::shared_ptr< smartshape::ControlPointAdjustment >	fullCtlPtAdj
	If the shape is only on one staff system, this is where the manual edits are.
bool	hidden {}
	Inverse of "Show" option.
NoteNumber	startNoteId {}
	If non-zero, the specific note with the entry that this shape starts from. (xml node is <startNoteID>)
NoteNumber	endNoteId {}
	If non-zero, the specific note with the entry that this shape ends on. (xml node is <endNoteID>)
Cmper	lineStyleId {}
	If non-zero, the SmartShapeCustomLine for this shape. Several ShapeType values use it. (xml node is <lineStyleID>)
Cmper	startLyricNum {}
	The text block of the lyrics text if this is a word extension or hyphen smart shape.
Cmper	endLyricNum {}
LyricTextType	startLyricType {}
	The type of lyrics block for startLyricNum. (xml node is <startLyricTag>)
LyricTextType	endLyricType {}

Static Public Attributes
static constexpr std::string_view	XmlNodeName = "smartShape"
	XML node name.

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.
OthersBase &	operator= (const OthersBase &other)
	Assignment operator delegates to base, preserving OthersBase state.
OthersBase &	operator= (OthersBase &&other) noexcept
	Assignment operator delegates to base, preserving OthersBase state.
Protected Member Functions inherited from musx::dom::Base
	Base (const DocumentWeakPtr &document, Cmper partId, ShareMode shareMode)
	Constructs the base class.
	Base (const Base &)=default
	explicit default copy constructor
	Base (Base &&) noexcept=default
	explicit default move constructor
Base &	operator= (const Base &)
	no-op copy assignment operator allows subclasses to copy their values.
Base &	operator= (Base &&) noexcept
	no-op move assignment operator allows subclasses to move their values.

Detailed Description

Represents a Finale smart shape.

This class is identified by the XML node name "smartShape".

Member Enumeration Documentation

EngraverSlurState

enum class musx::dom::others::SmartShape::EngraverSlurState

strong

The selection for engraver slurs. (Only applicable for slurs.)

Enumerator
Auto	Take the engraver slur setting from options::SmartShapeOptions::useEngraverSlurs. (Default value.)
Off	Do not use engraver slur behaviour.
On	Use engraver slur behaviour.

LyricTextType

enum class musx::dom::others::SmartShape::LyricTextType

strong

The lyric text type if this is a lyrics smart shape.

Enumerator
None	The default, for when there is no lyrics text block.
Verse	The assignment is to a Verse lyrics text block.
Chorus	The assignment is to a Chorus lyrics text block.
Section	The assignment is to a Section lyrics text block.

ShapeType

enum class musx::dom::others::SmartShape::ShapeType : int

strong

All the smart shape types supported by Finale.

The enum values match Finale's internal values. (Note that 24 is skipped.) However, they are saved in the xml as text values. These are camel case and otherwise match the enum names, except as noted.

Enumerator
SlurDown	Downward Slur (tips point up). This is the default and may not appear in the xml, but the text is in the Finale binary.
SlurUp	Upward Slur (tips point down).
Decrescendo	Decrescendo hairpin. (xml value is "decresc")
Crescendo	Crescendo hairpin. (xml value is "cresc")
OctaveDown	Ottava bassa. (8vb)
OctaveUp	Ottava. (8va)
DashLineUp	Dashed line with upward hook.
DashLineDown	Dashed line with downward hook. == 7.
DashSlurDown	Thin line dashed downward slur (tips point up).
DashSlurUp	Thin line dashed upward slur (tips point down).
DashLine	Dashed line.
SolidLine	Solid line.
SolidLineDown	Solid line with downward right hook.
SolidLineUp	Solid line with upward right hook.
Trill	Trill (includes "tr" symbol at the beginning). == 14.
SlurAuto	Slur with direction automatically determined.
DashSlurAuto	Thin line dashed slur with direction automatically determined.
TrillExtension	Trill extension: only the wavy line. (xml value is "trillExt")
SolidLineDownBoth	Solid line with downward hooks on both ends. (xml value is "solidLineDown2")
SolidLineUpBoth	Solid line with upward hooks on both ends. (xml value is "solidLineUp2")
TwoOctaveDown	Quindicesima bassa (15ma bassa)
TwoOctaveUp	Quindicesima (15ma) == 21.
DashLineDownBoth	Dashed line with downward hooks on both ends. (xml value is "dashLineDown2")
DashLineUpBoth	Dashed line with upward hooks on both ends. (xml value is "dashLineUp2")
Glissando	Glissando (shape is determined by lineStyleId) == 25 (24 has no value)
TabSlide	Tab slide (a solid line that is often used as a note-attached glissando)
BendHat	Bend hat (solid up-down line with a corner in the middle)
BendCurve	Bend curve.
CustomLine	User-created custom line with shape determined by lineStyleId. (xml value is "smartLine")
SolidLineUpLeft	Solid line with upward left hook.
SolidLineDownLeft	Solid line with downward left hook.
DashLineUpLeft	Dashed line with upward left hook. == 32.
DashLineDownLeft	Dashed line with downward left hook.
SolidLineUpDown	Solid line with upward left hook and downward right hook.
SolidLineDownUp	Solid line with downward left hook and upward right hook.
DashLineUpDown	Dashed line with upward left hook and downward right hook.
DashLineDownUp	Dashed line with downward left hook and upward right hook.
Hyphen	Lyric hyphen, used only with lyric assignments.
WordExtension	Lyric word extension, used only with lyric assignments. (xml value is "wordExt")
DashContourSlurDown	Contoured line dashed downward slur (tips point up).
DashContourSlurUp	Contoured line dashed upward slur (tips point down).
DashContourSlurAuto	Contoured line dashed slur with direction automatically determined.

SlurAvoidAccidentalsState

enum class musx::dom::others::SmartShape::SlurAvoidAccidentalsState

strong

The selection whether this shape avoids accidentals. (Only applicable for slurs.)

Enumerator
Auto	Take the avoid accidentals setting from options::SmartShapeOptions::slurAvoidAccidentals. (Default value.)
Off	Do not use avoid accidentals behaviour.
On	Use avoid accidentals behaviour.
Invalid	May not be used, but exists as a possibility in the Finale app.

SystemBreakType

enum class musx::dom::others::SmartShape::SystemBreakType

strong

How this shape breaks across systems. Represents the choice between "Make Horizontal Over System Break" and "Maintain Angle Over System Break" in the Finale U.I.

Note

Although this is presented in the xml as an enum, it appears to have only two values. There is some evidence that at one point the developers had intentions to expand to more options here, but it seems those plans never materialized.

Enumerator
Same	System break honors makeHorz setting over a system break. (Default)
Opposite	System break is the opposite of makeHorz over a system break. So if makeHorz is true, this allows the system break to be angled. If makeHorz is false, this forces the system break to be horizontal.

Member Function Documentation

calcAppliesTo()

bool musx::dom::others::SmartShape::calcAppliesTo

(

const EntryInfoPtr &

entryInfo

)

const

Calculates if the smart shape applies to the specified entry.

This function is most useful for shape types like ottavas and hairpins. It does not check layers or staves in between start and end staves, so it may be less useful for slurs.

Parameters

entryInfo

The entry to check

integrityCheck()

void musx::dom::others::SmartShape::integrityCheck ( const std::shared_ptr< Base > &  ptrToThis )

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.

Parameters

ptrToThis

This instance in a shared_ptr. (Avoids need for shared_from_this.)

Exceptions

musx::dom::integrity_error

if there is a problem.

Reimplemented from musx::dom::Base.

Member Data Documentation

endLyricNum

Cmper musx::dom::others::SmartShape::endLyricNum {}

This value appears to be meaningless. It is often zero for word extensions or the same value as startLyricNum for hyphens. It can also have an apparent nonsense value (.e.g, "-2"). The meaning of this is not known. The Finale U.I. does not appear to allow hyphen or word extensions between syllables from two different lyric blocks, so the need for start and end blocks is unclear.

endLyricType

LyricTextType musx::dom::others::SmartShape::endLyricType {}

The type of lyrics block for endLyricNum. The speculative comments at endLyricNum also apply here. This value has never been seen to be different than startLyricNum unless endLyricNum is zero. (xml node is <endLyricTag>)