A single beat chart element from Finale's music spacing system. More...
#include <Others.h>
Inheritance diagram for musx::dom::others::BeatChartElement:
Classes | |
| class | Control |
| Control settings for a beat chart, only used when inci == 0. More... | |
Public Member Functions | |
| BeatChartElement (const DocumentWeakPtr &document, Cmper partId, ShareMode shareMode, Cmper cmper, Inci inci) | |
| Constructor function. | |
| 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. | |
| 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. | |
| 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< BeatChartElement > & | xmlMappingArray () |
| Required for musx::factory::FieldPopulator. | |
Public Attributes | |
| std::shared_ptr< Control > | control |
| Control data for this beat chart element (only present for inci == 0) | |
| Edu | dur {} |
| Duration of this beat span. | |
| Evpu | pos {} |
| Horizontal position within the measure. | |
| Evpu | endPos {} |
| End position of the beat span. | |
| Evpu | minPos {} |
| Minimum position (see remarks in the class-level description of BeatChartElement) | |
Static Public Attributes | |
| static constexpr std::string_view | XmlNodeName = "beatChart" |
| The XML node name for this type. | |
Additional Inherited Members | |
| 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. | |
| 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
A single beat chart element from Finale's music spacing system.
Beat charts define graphical spacing in measures with custom horizontal layout. They typically consist of a control element followed by several beat positions, each indicating its duration, position, and spacing information.
Each instance corresponds to a <beatChart> XML node. Only one <control> is expected per measure (inci = 0), and it must precede other entries.
The cmper is the 1-based measure number for the beat chart. The inci is a 0-based index into the list of elements in that measure’s beat chart. The cmper is shared among all entries for a given measure; inci increases with each new item.
Only inci 0 has the Control instance, but this control data is needed by all subsequent elements in the same measure. The only data member of interest in inci 0 is the control. Inci 0 is not a member of the list but rather a header.
After automatic note spacing, the pos / endPos fields contain the “ideal width” for each duration, based on the Music Spacing settings in Document Options. Any additional space is represented in the minPos fields.
For any beat chart array of N elements, the display width for element n may be calculated as:
If the user manually edits a beat chart, Finale transitions the array from automatic to manual as follows: The first pos is set to the first minPos, and then the width value (as calculated above) is used to determine the rest of the pos and endPos fields. The final endPos value is stored in totalWidth. Finale also sets the first minPos to 0 and all others (including control->minWidth) to 1.
The control->allotWidth member has a purpose and effect, but it has proved elusive to document exactly how it works.
This class is identified by the XML node name "beatChart".
Member Function Documentation
◆ 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.
