Details.h

/*
 * Copyright (C) 2025, Robert Patterson
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
#pragma once
#include <functional>
#include <vector>
#include <unordered_set>
#include <cmath>
#include <map>
 
#include "music_theory/music_theory.hpp"
 
#include "musx/util/EnigmaString.h"
#include "MusxInstance.h"
#include "BaseClasses.h"
#include "CommonClasses.h"
#include "Options.h"
#include "Others.h"
#include "Staff.h"
 // do not add other dom class dependencies. Use Implementations.h for implementations that need total class access.
 
namespace musx {
namespace dom {
 
class EntryInfoPtr;
class EntryFrame;
class EntryInfo;
 
namespace others {
class ChordSuffixElement;
class FretboardGroup;
class FretInstrument;
class FretboardStyle;
class StaffUsed;
class Measure;
class MultiStaffInstrumentGroup;
class TextBlock;
} // namespace others
 
namespace texts {
class ExpressionText;
class LyricsChorus;
class LyricsSection;
class LyricsVerse;
} // namespace others
 
namespace details {
 
class AccidentalAlterations : public NoteDetailsBase
{
public:
    explicit AccidentalAlterations(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum, Inci inci)
        : NoteDetailsBase(document, partId, shareMode, entnum, inci), customFont(std::make_shared<FontInfo>(document))
    {
    }
 
    NoteNumber noteId{};                            
    int percent{};                                  
    Evpu vOffset{};                                 
    Evpu hOffset{};                                 
    char32_t altChar{};                             
    std::shared_ptr<FontInfo> customFont;           
    bool useOwnFont{};                              
    bool allowVertPos{};                            
 
    NoteNumber getNoteId() const override { return noteId; }
 
    constexpr static std::string_view XmlNodeName = "acciAlter";   
    static const xml::XmlElementArray<AccidentalAlterations>& xmlMappingArray(); 
};
 
class ArticulationAssign : public EntryDetailsBase
{
public:
    explicit ArticulationAssign(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum, Inci inci)
        : EntryDetailsBase(document, partId, shareMode, entnum, inci) {}
 
    Cmper articDef{};               
    Evpu horzOffset{};              
    Evpu horzAdd{};                 
    Evpu vertOffset{};              
    Evpu vertAdd{};                 
    bool overridePlacement{};       
    bool aboveEntry{};              
    bool hide{};                    
    bool neverStack{};              
    bool avoidSlur{};               
    int numSlursAvoided{};          
 
    static const xml::XmlElementArray<ArticulationAssign>& xmlMappingArray();   
    constexpr static std::string_view XmlNodeName = "articAssign"; 
};
 
class Baseline : public DetailsBase
{
public:
    explicit Baseline(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, Cmper system, Cmper staff, std::optional<Inci> inci)
        : DetailsBase(document, partId, shareMode, system, staff, inci) {}
 
    Evpu baselineDisplacement{};        
    std::optional<Cmper> lyricNumber{}; 
 
    static const xml::XmlElementArray<Baseline>& xmlMappingArray();   
};
 
class BaselineNoInci : public Baseline
{
public:
    explicit BaselineNoInci(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, Cmper system, Cmper staff)
        : Baseline(document, partId, shareMode, system, staff, std::nullopt) {}
};
 
class BaselineSystemChords : public BaselineNoInci
{
public:
    using BaselineNoInci::BaselineNoInci;
 
    constexpr static std::string_view XmlNodeName = "baselinesSysChords"; 
};
 
class BaselineSystemExpressionsAbove : public BaselineNoInci
{
public:
    using BaselineNoInci::BaselineNoInci;
 
    constexpr static std::string_view XmlNodeName = "baselinesSysExprAboveStaff"; 
};
 
class BaselineSystemExpressionsBelow : public BaselineNoInci
{
public:
    using BaselineNoInci::BaselineNoInci;
 
    constexpr static std::string_view XmlNodeName = "baselinesSysExprBelowStaff"; 
};
 
class BaselineSystemFretboards : public BaselineNoInci
{
public:
    using BaselineNoInci::BaselineNoInci;
 
    constexpr static std::string_view XmlNodeName = "baselinesSysFingerboards"; 
};
 
class BaselineSystemLyricsChorus : public Baseline
{
public:
    using Baseline::Baseline;
 
    constexpr static std::string_view XmlNodeName = "baselinesSysLyricsChorus"; 
};
 
class BaselineSystemLyricsSection : public Baseline
{
public:
    using Baseline::Baseline;
 
    constexpr static std::string_view XmlNodeName = "baselinesSysLyricsSection"; 
};
 
class BaselineSystemLyricsVerse : public Baseline
{
public:
    using Baseline::Baseline;
 
    constexpr static std::string_view XmlNodeName = "baselinesSysLyricsVerse"; 
};
 
class BaselineChords : public BaselineNoInci
{
public:
    using BaselineNoInci::BaselineNoInci;
 
    using PerSystemType = BaselineSystemChords; 
    constexpr static std::string_view XmlNodeName = "baselinesChords"; 
};
 
class BaselineExpressionsAbove : public BaselineNoInci
{
public:
    using BaselineNoInci::BaselineNoInci;
 
    using PerSystemType = BaselineSystemExpressionsAbove; 
    constexpr static std::string_view XmlNodeName = "baselinesExprAboveStaff"; 
};
 
class BaselineExpressionsBelow : public BaselineNoInci
{
public:
    using BaselineNoInci::BaselineNoInci;
 
    using PerSystemType = BaselineSystemExpressionsBelow; 
    constexpr static std::string_view XmlNodeName = "baselinesExprBelowStaff"; 
};
 
class BaselineFretboards : public BaselineNoInci
{
public:
    using BaselineNoInci::BaselineNoInci;
 
    using PerSystemType = BaselineSystemFretboards; 
    constexpr static std::string_view XmlNodeName = "baselinesFingerboards"; 
};
 
class BaselineLyricsChorus : public Baseline
{
public:
    using Baseline::Baseline;
 
    using PerSystemType = BaselineSystemLyricsChorus; 
    using TextType = texts::LyricsChorus; 
    constexpr static std::string_view XmlNodeName = "baselinesLyricsChorus"; 
};
 
class BaselineLyricsSection : public Baseline
{
public:
    using Baseline::Baseline;
 
    using PerSystemType = BaselineSystemLyricsSection; 
    using TextType = texts::LyricsSection; 
    constexpr static std::string_view XmlNodeName = "baselinesLyricsSection"; 
};
 
class BaselineLyricsVerse : public Baseline
{
public:
    using Baseline::Baseline;
 
    using PerSystemType = BaselineSystemLyricsVerse; 
    using TextType = texts::LyricsVerse; 
    constexpr static std::string_view XmlNodeName = "baselinesLyricsVerse"; 
};
 
class BeamAlterations : public EntryDetailsBase
{
private:
    bool m_active = true; // this value is set by the factory.
 
protected:
    template <typename SecondaryBeamType>
    static bool calcIsFeatheredBeamImpl(const EntryInfoPtr& entryInfo, Evpu& outLeftY, Evpu& outRightY);
 
    template <typename SecondaryBeamType>
    static MusxInstanceList<SecondaryBeamType> getSecondaryBeamArray(const EntryInfoPtr& entryInfo);
 
public:
    explicit BeamAlterations(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum, std::optional<Inci> inci = std::nullopt)
        : EntryDetailsBase(document, partId, shareMode, entnum, inci) {}
 
    using FlattenStyle = options::BeamOptions::FlattenStyle;
 
    Evpu leftOffsetH{};         
    Evpu leftOffsetY{};         
    Evpu rightOffsetH{};        
    Evpu rightOffsetY{};        
    Edu dura{};                 
    FlattenStyle flattenStyle{}; 
    Efix beamWidth{};            
 
    Efix calcEffectiveBeamWidth() const;
 
    bool isActive() const { return m_active; }
 
    template <typename T,
              std::enable_if_t<std::is_base_of_v<BeamAlterations, T>, int> = 0>
    static void calcAllActiveFlags(const DocumentPtr& document);
 
    static MusxInstance<BeamAlterations> getPrimaryForStem(const EntryInfoPtr& entryInfo, StemSelection stemSelection = StemSelection::MatchEntry);  // must be defined in Details.cpp
 
    static MusxInstance<BeamAlterations> getSecondaryForStem(const EntryInfoPtr& entryInfo, Edu dura, StemSelection stemSelection = StemSelection::MatchEntry);  // must be defined in Details.cpp
 
    static const xml::XmlElementArray<BeamAlterations>& xmlMappingArray(); 
};
 
class BeamAlterationsDownStem : public BeamAlterations
{
public:
    explicit BeamAlterationsDownStem(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum)
        : BeamAlterations(document, partId, shareMode, entnum) {}
 
    constexpr static std::string_view XmlNodeName = "beamAltPrimDownStem"; 
};
 
class BeamAlterationsUpStem : public BeamAlterations
{
public:
    explicit BeamAlterationsUpStem(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum)
        : BeamAlterations(document, partId, shareMode, entnum) {}
 
    constexpr static std::string_view XmlNodeName = "beamAltPrimUpStem"; 
};
 
class BeamExtension : public EntryDetailsBase
{
public:
    explicit BeamExtension(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum)
        : EntryDetailsBase(document, partId, shareMode, entnum) {}
 
    Evpu leftOffset{};      
    Evpu rightOffset{};     
    unsigned mask{};        
    bool extBeyond8th{};    
 
    unsigned calcMaxExtension() const;
 
    static MusxInstance<BeamExtension> getForStem(const EntryInfoPtr& entryInfo, StemSelection stemSelection = StemSelection::MatchEntry);  // must be defined in Details.cpp
 
    static const xml::XmlElementArray<BeamExtension>& xmlMappingArray(); 
};
 
class BeamExtensionDownStem : public BeamExtension
{
public:
    using BeamExtension::BeamExtension;
 
    constexpr static std::string_view XmlNodeName = "beamExtendDownStem"; 
};
 
class BeamExtensionUpStem : public BeamExtension
{
public:
    using BeamExtension::BeamExtension;
 
    constexpr static std::string_view XmlNodeName = "beamExtendUpStem"; 
};
 
class BeamStubDirection : public EntryDetailsBase
{
public:
    explicit BeamStubDirection(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum)
        : EntryDetailsBase(document, partId, shareMode, entnum)
    {
    }
 
    unsigned mask{};        
 
    bool isLeft() const { return mask != 0; }
 
    constexpr static std::string_view XmlNodeName = "beamStub"; 
    static const xml::XmlElementArray<BeamStubDirection>& xmlMappingArray(); 
};
 
class Bracket : public DetailsBase
{
public:
    explicit Bracket(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, Cmper cmper1, Cmper cmper2, Inci inci)
        : DetailsBase(document, partId, shareMode, cmper1, cmper2, inci)
    {
    }
 
    explicit Bracket(const DocumentWeakPtr& document)
        : DetailsBase(document, SCORE_PARTID, Base::ShareMode::All, 0, 0, 0)
    {
    }
 
    enum class BracketStyle : int
    {
        None = 0,                   
        ThickLine = 1,              
        BracketStraightHooks = 2,   
        PianoBrace = 3,             
        Unknown4,                   
        Unknown5,                   
        BracketCurvedHooks = 6,     
        Unknown7,                   
        DeskBracket = 8             
    };
 
    BracketStyle style{};       
    Evpu horzAdjLeft{};         
    Evpu vertAdjTop{};          
    Evpu vertAdjBot{};          
    bool showOnSingleStaff{};   
 
    constexpr static std::string_view XmlNodeName = "brackSpec"; 
    static const xml::XmlElementArray<Bracket>& xmlMappingArray(); 
};
 
class ChordAssign : public DetailsBase
{
    Cmper calcFretboardGroupCmper() const;
 
public:
    explicit ChordAssign(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, Cmper staffId, Cmper meas, Inci inci)
        : DetailsBase(document, partId, shareMode, staffId, meas, inci)
    {
    }
 
    enum class BassPosition
    {
        AfterRoot,                  // default value may not appear in xml (but text appears in Finale binary)
        UnderRoot,
        Subtext
    };
 
    Cmper suffixId{};               
    Cmper fbStyleId{};              
    int rootScaleNum{};             
    int rootAlter{};                
    bool rootLowerCase{};           
    bool playSuffix{};              
    bool showRoot{};                
    bool playRoot{};                
    bool showFretboard{};           
    bool showSuffix{};              
    bool playFretboard{};           
    int bassScaleNum{};             
    int bassAlter{};                
    bool bassLowerCase{};           
    BassPosition bassPosition{};    
    bool showAltBass{};             
    bool playAltBass{};             
    int capoValue{};                
    bool useLocalCapo{};            
    Inci fretboardGroupInci{};      
    bool useFretboardFont{};        
    Evpu horzOff{};                 
    Evpu vertOff{};                 
    Evpu fbHorzOff{};               
    Evpu fbVertOff{};               
    Edu horzEdu{};                  
    int chPercent{};                
    int fbPercent{};                
 
    MusxInstanceList<others::ChordSuffixElement> getChordSuffix() const;
 
    MusxInstance<others::FretboardGroup> getFretboardGroup() const;
 
    MusxInstance<others::FretboardStyle> getFretboardStyle() const;
 
    constexpr static std::string_view XmlNodeName = "chordAssign"; 
    static const xml::XmlElementArray<ChordAssign>& xmlMappingArray(); 
};
 
class ClefOctaveFlats : public DetailsArray<int, 7>
{
    std::string_view xmlTag() const override { return XmlNodeName; }
 
public:
    using DetailsArray::DetailsArray;
 
    constexpr static std::string_view XmlNodeName = "clefOctvFlats"; 
    static const xml::XmlElementArray<ClefOctaveFlats>& xmlMappingArray(); 
};
 
class ClefOctaveSharps : public DetailsArray<int, 7>
{
    std::string_view xmlTag() const override { return XmlNodeName; }
 
public:
    using DetailsArray::DetailsArray;
 
    constexpr static std::string_view XmlNodeName = "clefOctvSharps"; 
    static const xml::XmlElementArray<ClefOctaveSharps>& xmlMappingArray(); 
};
 
class CrossStaff : public NoteDetailsBase
{
public:
    explicit CrossStaff(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum, Inci inci)
        : NoteDetailsBase(document, partId, shareMode, entnum, inci)
    {
    }
 
    NoteNumber noteId{};    
    StaffCmper staff{};     
 
    NoteNumber getNoteId() const override { return noteId; }
 
    constexpr static std::string_view XmlNodeName = "crossStaff";    
    static const xml::XmlElementArray<CrossStaff>& xmlMappingArray();   
};
 
class CustomStem : public EntryDetailsBase
{
public:
    explicit CustomStem(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum)
        : EntryDetailsBase(document, partId, shareMode, entnum) {}
 
    Cmper shapeDef{}; 
    Evpu xOffset{};   
    Evpu yOffset{};   
 
    bool calcIsHiddenStem() const;
 
    static MusxInstance<CustomStem> getForStem(const EntryInfoPtr& entryInfo, StemSelection stemSelection = StemSelection::MatchEntry);  // must be defined in Details.cpp
 
    static const xml::XmlElementArray<CustomStem>& xmlMappingArray(); 
};
 
class CustomDownStem : public CustomStem
{
public:
    using CustomStem::CustomStem;
 
    constexpr static std::string_view XmlNodeName = "stemDefDown"; 
};
 
class CustomUpStem : public CustomStem
{
public:
    using CustomStem::CustomStem;
 
    constexpr static std::string_view XmlNodeName = "stemDefUp"; 
};
 
class DotAlterations : public NoteDetailsBase
{
public:
    explicit DotAlterations(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum, Inci inci)
        : NoteDetailsBase(document, partId, shareMode, entnum, inci)
    {
    }
 
    NoteNumber noteId{};         
    Evpu hOffset{};              
    Evpu vOffset{};              
    Evpu interdotSpacing{};      
 
    NoteNumber getNoteId() const override { return noteId; }
 
    constexpr static std::string_view XmlNodeName = "dotOffset";   
    static const xml::XmlElementArray<DotAlterations>& xmlMappingArray(); 
};
 
class EntryPartFieldDetail : public EntryDetailsBase
{
public:
    explicit EntryPartFieldDetail(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum)
        : EntryDetailsBase(document, partId, shareMode, entnum) {}
 
    Evpu hOffset{};         
    bool freezeStem{};      
    bool upStem{};          
 
    static const xml::XmlElementArray<EntryPartFieldDetail>& xmlMappingArray(); 
    constexpr static std::string_view XmlNodeName = "entryPartFieldDetail";     
};
 
class EntrySize : public EntryDetailsBase
{
public:
    explicit EntrySize(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum)
        : EntryDetailsBase(document, partId, shareMode, entnum) {}
 
    int percent{}; 
 
    static const xml::XmlElementArray<EntrySize>& xmlMappingArray(); 
    constexpr static std::string_view XmlNodeName = "entrySize"; 
};
 
class FretboardDiagram : public DetailsBase
{
public:
    explicit FretboardDiagram(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, Cmper cmper1, Cmper cmper2)
        : DetailsBase(document, partId, shareMode, cmper1, cmper2)
    {}
 
    enum class Shape
    {
        None,       
        Closed,     
        Open,       
        Muted,      
        Custom      
    };
 
    class Cell
    {
    public:
        int string{};       
        int fret{};         
        Shape shape{};      
        int fingerNum{};    
 
        static const xml::XmlElementArray<Cell>& xmlMappingArray(); 
    };
 
    class Barre
    {
    public:
        int fret{};         
        int startString{};  
        int endString{};    
 
        static const xml::XmlElementArray<Barre>& xmlMappingArray(); 
    };
 
    int numFrets{};         
    int fretboardNum{};     
    bool lock{};            
    bool showNum{};         
    int numFretCells{};     
    int numFretBarres{};    
 
    std::vector<std::shared_ptr<Cell>> cells;   
    std::vector<std::shared_ptr<Barre>> barres; 
 
    void integrityCheck(const std::shared_ptr<Base>& ptrToThis) override
    {
        this->DetailsBase::integrityCheck(ptrToThis);
        if (numFretCells != int(cells.size())) {
            const int oldVal = numFretCells;
            numFretCells = int(cells.size());
            MUSX_INTEGRITY_ERROR("FretboardDiagram " + std::to_string(getCmper1()) + ", " + std::to_string(getCmper2())
                + " specifies the wrong number of cells (" + std::to_string(oldVal) + ").");
        }
        if (numFretBarres != int(barres.size())) {
            const int oldVal = numFretBarres;
            numFretBarres = int(barres.size());
            MUSX_INTEGRITY_ERROR("FretboardDiagram " + std::to_string(getCmper1()) + ", " + std::to_string(getCmper2())
                + " specifies the wrong number of barres (" + std::to_string(oldVal) + ").");
        }
    }
 
    constexpr static std::string_view XmlNodeName = "fretboard"; 
    static const xml::XmlElementArray<FretboardDiagram>& xmlMappingArray(); 
};
 
class GFrameHold : public DetailsBase
{
public:
    explicit GFrameHold(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, Cmper staffId, Cmper meas)
        : DetailsBase(document, partId, shareMode, staffId, meas), frames(MAX_LAYERS) {}
 
    // Public properties corresponding to the XML structure
    std::optional<ClefIndex> clefId;        
    Cmper clefListId{};                     
    ShowClefMode showClefMode{};            
    bool mirrorFrame{};                     
    bool clefAfterBarline{};                
    int clefPercent{};                      
    std::vector<Cmper> frames;              
 
    StaffCmper getStaff() const { return StaffCmper(getCmper1()); }
 
    MeasCmper getMeasure() const { return MeasCmper(getCmper2()); }
 
    bool calcIsMultiLayer() const
    {
        return std::count_if(frames.begin(), frames.end(), [](Cmper frameId) { return frameId != 0; }) > 1;
    }
 
    bool calcContainsMusic() const
    {
        return std::find_if(frames.begin(), frames.end(), [](Cmper frameId) { return frameId != 0; }) != frames.end();
    }
 
    std::pair<MusxInstance<others::Frame>, Edu> findLayerFrame(LayerIndex layerIndex) const;
 
    bool iterateRawEntries(std::function<bool(const MusxInstance<Entry>&, LayerIndex)> iterator) const;
 
    void integrityCheck(const std::shared_ptr<Base>& ptrToThis) override
    {
        this->DetailsBase::integrityCheck(ptrToThis);
        if (clefListId && clefId.has_value()) {
            MUSX_INTEGRITY_ERROR("GFrameHold for staff " + std::to_string(getCmper1()) + " and measure " + std::to_string(getCmper2()) + " has both clef and clef list.");
        }
        if (!clefListId && !clefId.has_value()) {
            MUSX_INTEGRITY_ERROR("GFrameHold for staff " + std::to_string(getCmper1()) + " and measure " + std::to_string(getCmper2()) + " has neither clef nor clef list.");
        }
    }
 
    constexpr static std::string_view XmlNodeName = "gfhold"; 
    static const xml::XmlElementArray<GFrameHold>& xmlMappingArray(); 
};
 
class IndependentStaffDetails : public DetailsBase
{
public:
    explicit IndependentStaffDetails(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, Cmper staffId, Cmper meas)
        : DetailsBase(document, partId, shareMode, staffId, meas)
    {
    }
 
    // Key signature info
    std::shared_ptr<KeySignature> keySig; 
    bool hasKey{};                        
 
    // Time signature info
    Cmper beats{};                      
    Cmper divBeat{};                    
    Cmper dispBeats{};                  
    Cmper dispDivBeat{};                
 
    bool displayAltNumTsig{};           
    bool displayAltDenTsig{};           
    bool altNumTsig{};                  
    bool altDenTsig{};                  
    bool displayAbbrvTime{};            
    bool hasDispTime{};                 
    bool hasTime{};                     
 
    MusxInstance<TimeSignature> createTimeSignature() const;
 
    MusxInstance<TimeSignature> createDisplayTimeSignature() const;
 
    void integrityCheck(const std::shared_ptr<Base>& ptrToThis) override
    {
        DetailsBase::integrityCheck(ptrToThis);
        if (hasKey && !keySig) {
            keySig = std::make_shared<KeySignature>(getDocument());
        }
    }
 
    constexpr static std::string_view XmlNodeName = "floats"; 
    static const xml::XmlElementArray<IndependentStaffDetails>& xmlMappingArray(); 
};
 
class KeySymbolListElement : public DetailsBase {
public:
    explicit KeySymbolListElement(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, Cmper cmper1, Cmper cmper2)
        : DetailsBase(document, partId, shareMode, cmper1, cmper2) {}
 
    std::string accidentalString;   
 
    int getAlterationValue() const {
        return static_cast<int16_t>(getCmper2());
    }
 
    void integrityCheck(const std::shared_ptr<Base>& ptrToThis) override
    {
        DetailsBase::integrityCheck(ptrToThis);
        if (std::abs(getAlterationValue()) > MAX_ALTERATIONS) {
            util::Logger::log(util::Logger::LogLevel::Verbose,
                "KeySymbolListElement for list " + std::to_string(getCmper1()) + " has invalid value " + std::to_string(getAlterationValue()));
        }
    }
 
    constexpr static std::string_view XmlNodeName = "keySymList"; 
    static const xml::XmlElementArray<KeySymbolListElement>& xmlMappingArray(); 
};
 
class LyricAssign : public EntryDetailsBase
{
public:
    explicit LyricAssign(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum, Inci inci)
        : EntryDetailsBase(document, partId, shareMode, entnum, inci) {}
 
    Cmper lyricNumber{};            
    unsigned syllable{};            
    Evpu horzOffset{};              
    Evpu vertOffset{};              
    Evpu floatingHorzOff{};         
    Evpu wext{};                    
    bool displayVerseNum{};         
 
    virtual MusxInstance<texts::LyricsTextBase> getLyricText() const = 0;
 
    virtual LyricTextType getLyricTextType() const = 0;
 
    util::EnigmaParsingContext getRawTextCtx() const;
 
    EntryInfoPtr calcWordExtensionEndpoint() const;
 
    static const xml::XmlElementArray<LyricAssign>& xmlMappingArray();   
};
 
class LyricAssignChorus : public LyricAssign
{
public:
    using LyricAssign::LyricAssign;
 
    MusxInstance<texts::LyricsTextBase> getLyricText() const override;
    LyricTextType getLyricTextType() const override;
        
    using BaselineType = BaselineLyricsChorus; 
    using TextType = texts::LyricsChorus; 
    constexpr static std::string_view XmlNodeName = "lyrDataChorus"; 
};
 
class LyricAssignSection : public LyricAssign
{
public:
    using LyricAssign::LyricAssign;
 
    MusxInstance<texts::LyricsTextBase> getLyricText() const override;
    LyricTextType getLyricTextType() const override;
 
    using BaselineType = BaselineLyricsSection; 
    using TextType = texts::LyricsSection; 
    constexpr static std::string_view XmlNodeName = "lyrDataSection"; 
};
 
class LyricAssignVerse : public LyricAssign
{
public:
    using LyricAssign::LyricAssign;
 
    MusxInstance<texts::LyricsTextBase> getLyricText() const override;
    LyricTextType getLyricTextType() const override;
 
    using BaselineType = BaselineLyricsVerse; 
    using TextType = texts::LyricsVerse; 
    constexpr static std::string_view XmlNodeName = "lyrDataVerse"; 
};
 
class LyricEntryInfo : public EntryDetailsBase
{
public:
    using AlignJustify = options::LyricOptions::AlignJustify;
 
    explicit LyricEntryInfo(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum, std::optional<Inci> inci = std::nullopt)
        : EntryDetailsBase(document, partId, shareMode, entnum, inci) {}
 
    std::optional<AlignJustify> justify{}; 
    std::optional<AlignJustify> align{};   
 
    static const xml::XmlElementArray<LyricEntryInfo>& xmlMappingArray(); 
    constexpr static std::string_view XmlNodeName = "lyricEntryInfo"; 
};
 
class MeasureNumberIndividualPositioning : public DetailsBase
{
public:
    explicit MeasureNumberIndividualPositioning(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, Cmper staffId, Cmper meas, Inci inci)
        : DetailsBase(document, partId, shareMode, staffId, meas, inci)
    {
    }
 
    enum class ForceVisibility
    {
        None,       
        Show,       
        Hide        
    };
 
    Cmper measNumRegion{};                          
    Evpu xOffset{};                                 
    Evpu yOffset{};                                 
    Evpu xOffset2{};                                
    ForceVisibility forceVisibility{};              
    bool useEnclosure{};                            
    std::shared_ptr<others::Enclosure> enclosure;   
 
    constexpr static std::string_view XmlNodeName = "measNumbIndivPos"; 
    static const xml::XmlElementArray<MeasureNumberIndividualPositioning>& xmlMappingArray(); 
};
 
class MeasureTextAssign : public DetailsBase
{
public:
    explicit MeasureTextAssign(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, Cmper staffId, Cmper meas, Inci inci)
        : DetailsBase(document, partId, shareMode, staffId, meas, inci)
    {
    }
 
    Cmper block{};      
    Edu xDispEdu{};     
    Evpu xDispEvpu{};   
    Evpu yDisp{};       
    bool hidden{};      
 
    MusxInstance<others::TextBlock> getTextBlock() const;
 
    util::EnigmaParsingContext getRawTextCtx(Cmper forPartId) const;
 
    constexpr static std::string_view XmlNodeName = "measTextAssign"; 
    static const xml::XmlElementArray<MeasureTextAssign>& xmlMappingArray(); 
};
 
class NoteAlterations : public NoteDetailsBase
{
public:
    explicit NoteAlterations(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum, Inci inci)
        : NoteDetailsBase(document, partId, shareMode, entnum, inci), customFont(new FontInfo(document))
    {
    }
 
    NoteNumber noteId{};                    
    int percent{};                          
    Evpu nxdisp{};                          
    char32_t altNhead{};                    
    bool useOwnFont{};                      
    std::shared_ptr<FontInfo> customFont{}; 
    bool allowVertPos{};                    
    Evpu nydisp{};                          
    bool enharmonic{};                      
 
    NoteNumber getNoteId() const override { return noteId; }
 
    constexpr static std::string_view XmlNodeName = "noteAlter"; 
    static const xml::XmlElementArray<NoteAlterations>& xmlMappingArray(); 
};
 
class PercussionNoteCode : public NoteDetailsBase
{
public:
    explicit PercussionNoteCode(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum, Inci inci)
        : NoteDetailsBase(document, partId, shareMode, entnum, inci)
    {
    }
 
    NoteNumber noteId{};                
    PercussionNoteTypeId noteCode{};    
 
    NoteNumber getNoteId() const override { return noteId; }
 
    constexpr static std::string_view XmlNodeName = "percussionNoteCode"; 
    static const xml::XmlElementArray<PercussionNoteCode>& xmlMappingArray(); 
};
 
class SecondaryBeamAlterationsDownStem : public BeamAlterations
{
public:
    explicit SecondaryBeamAlterationsDownStem(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum, Inci inci)
        : BeamAlterations(document, partId, shareMode, entnum, inci) {}
 
    static bool calcIsFeatheredBeam(const EntryInfoPtr& entryInfo, Evpu& outLeftY, Evpu& outRightY)
    { return calcIsFeatheredBeamImpl<SecondaryBeamAlterationsDownStem>(entryInfo, outLeftY, outRightY); }
 
    constexpr static std::string_view XmlNodeName = "beamAltSecDownStem"; 
};
 
class SecondaryBeamAlterationsUpStem : public BeamAlterations
{
public:
    explicit SecondaryBeamAlterationsUpStem(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum, Inci inci)
        : BeamAlterations(document, partId, shareMode, entnum, inci) {}
 
    static bool calcIsFeatheredBeam(const EntryInfoPtr& entryInfo, Evpu& outLeftY, Evpu& outRightY)
    { return calcIsFeatheredBeamImpl<SecondaryBeamAlterationsUpStem>(entryInfo, outLeftY, outRightY); }
 
    constexpr static std::string_view XmlNodeName = "beamAltSecUpStem"; 
};
 
class SecondaryBeamBreak : public EntryDetailsBase
{
public:
    explicit SecondaryBeamBreak(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum)
        : EntryDetailsBase(document, partId, shareMode, entnum)
    {
    }
 
    unsigned mask{};        
    bool breakThrough{};    
 
    BeamNumber calcLowestBreak() const
    {
        MUSX_ASSERT_IF(!mask || mask >= unsigned(NoteType::Eighth)) {
            return 0; // invalid mask values have already been flagged and supposedly corrected by #integrityCheck.
        }
        for (unsigned shift = 0; true; shift++) {
            if (mask & (unsigned(NoteType::Note16th) >> shift)) {
                return shift + 2; // the 2nd beam is the 16th beam and the first one we checked.
            }
        }
        assert(false); // should not be able to get here
        return 0;
    }
 
    void integrityCheck(const std::shared_ptr<Base>& ptrToThis) override
    {
        EntryDetailsBase::integrityCheck(ptrToThis);
        if (!mask) {
            mask = unsigned(NoteType::Note4096th);
            MUSX_INTEGRITY_ERROR("Secondary beam break for entry" + std::to_string(getEntryNumber()) + " has no breaks.");
        }
        if (mask >= unsigned(NoteType::Eighth)) {
            mask = unsigned(NoteType::Eighth) - 1;
            MUSX_INTEGRITY_ERROR("Secondary beam break for entry" + std::to_string(getEntryNumber()) + " specifies a value that cannot be a secondary beam.");
        }
    }
 
    constexpr static std::string_view XmlNodeName = "secBeamBreak"; 
    static const xml::XmlElementArray<SecondaryBeamBreak>& xmlMappingArray(); 
};
 
class ShapeNoteBase : public DetailsBase
{
public:
    explicit ShapeNoteBase(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, Cmper cmper1, Cmper cmper2)
        : DetailsBase(document, partId, shareMode, cmper1, cmper2)
    {}
 
    class NoteShapes
    {
    public:
        char32_t doubleWhole{};     
        char32_t whole{};           
        char32_t half{};            
        char32_t quarter{};         
 
        static const xml::XmlElementArray<NoteShapes>& xmlMappingArray();    
    };
 
    std::vector<std::shared_ptr<NoteShapes>> noteShapes; 
    bool arrangedByPitch{};     
 
    void integrityCheck(const std::shared_ptr<Base>& ptrToThis) override
    {
        this->DetailsBase::integrityCheck(ptrToThis);
        const size_t currentSize = noteShapes.size();
        if (currentSize < music_theory::STANDARD_DIATONIC_STEPS) {
            for (size_t x = currentSize; x < music_theory::STANDARD_DIATONIC_STEPS; x++) {
                noteShapes.emplace_back(std::make_shared<NoteShapes>());
            }
            MUSX_INTEGRITY_ERROR("For ShapeNoteBase cmper " + std::to_string(getCmper1()) + ", only " + std::to_string(currentSize)
                + " note shapes were provided but at least " + std::to_string(music_theory::STANDARD_DIATONIC_STEPS) + " were expected.");
        }
    }
 
    static const xml::XmlElementArray<ShapeNoteBase>& xmlMappingArray();    
};
 
class ShapeNote: public ShapeNoteBase
{
public:
    using ShapeNoteBase::ShapeNoteBase;
 
    constexpr static std::string_view XmlNodeName = "shapeNote"; 
};
 
class ShapeNoteStyle: public ShapeNoteBase
{
public:
    using ShapeNoteBase::ShapeNoteBase;
 
    constexpr static std::string_view XmlNodeName = "shapeNoteStyle"; 
};
 
class StaffGroup : public DetailsBase {
public:
    StaffGroup(const DocumentWeakPtr& document, Cmper partId, Base::ShareMode shareMode, Cmper cmper1, Cmper cmper2)
        : DetailsBase(document, partId, shareMode, cmper1, cmper2) {}
 
    using BarlineType = others::Measure::BarlineType;
 
    using AlignJustify = others::NamePositioning::AlignJustify;
 
    enum class DrawBarlineStyle
    {
        OnlyOnStaves,       
        ThroughStaves,      
        Mensurstriche       
    };
 
    enum class HideStaves
    {
        Normally,       
        AsGroup,        
        None            
    };
 
    // Public properties corresponding to the XML structure, ordered as they appear in the XML
    StaffCmper startInst{};                   
    StaffCmper endInst{};                     
    MeasCmper startMeas{};                    
    MeasCmper endMeas{};                      
    Cmper fullNameId{};                       
    int fullNameXadj{};                       
    int fullNameYadj{};                       
    std::shared_ptr<Bracket> bracket{};       
    BarlineType barlineType{};                
    AlignJustify fullNameJustify{};           
    AlignJustify abbrvNameJustify{};          
    DrawBarlineStyle drawBarlines;            
    bool ownBarline{};                        
    bool fullNameIndivPos{};                  
    bool abbrvNameIndivPos{};                 
    bool hideName{};                          
    Cmper abbrvNameId{};                      
    int abbrvNameXadj{};                      
    int abbrvNameYadj{};                      
    AlignJustify fullNameAlign{};             
    AlignJustify abbrvNameAlign{};            
    bool fullNameExpand{};                    
    bool abbrvNameExpand{};                   
    HideStaves hideStaves{};                  
 
    Cmper multiStaffGroupId{};      
    std::unordered_set<StaffCmper> staves; 
 
    std::string getFullName(util::EnigmaString::AccidentalStyle accidentalStyle = util::EnigmaString::AccidentalStyle::Ascii) const;
 
    std::string getAbbreviatedName(util::EnigmaString::AccidentalStyle accidentalStyle = util::EnigmaString::AccidentalStyle::Ascii) const;
 
    MusxInstance<others::MultiStaffInstrumentGroup> getMultiStaffInstGroup() const;
 
    std::string getFullInstrumentName(util::EnigmaString::AccidentalStyle accidentalStyle = util::EnigmaString::AccidentalStyle::Ascii) const;
 
    std::string getAbbreviatedInstrumentName(util::EnigmaString::AccidentalStyle accidentalStyle = util::EnigmaString::AccidentalStyle::Ascii) const;
 
    bool isAllMeasures() const
    { return (startMeas == 1 && endMeas == (std::numeric_limits<MeasCmper>::max)()); }
 
    void integrityCheck(const std::shared_ptr<Base>& ptrToThis) override
    {
        this->DetailsBase::integrityCheck(ptrToThis);
        if (endMeas <= startMeas || startMeas <= 0) {
            MUSX_INTEGRITY_ERROR("Staff group " + std::to_string(getCmper2()) + " for part " + std::to_string(getSourcePartId())
                + " starts at measure " + std::to_string(startMeas) + " and ends at measure " + std::to_string(endMeas));
        }
        if (!bracket) {
            // this is not an error. Finale omits the bracket node for groups with entirely default bracket info.
            bracket = std::make_shared<Bracket>(getDocument());
        }
    }
 
    constexpr static std::string_view XmlNodeName = "staffGroup"; 
    static const xml::XmlElementArray<StaffGroup>& xmlMappingArray(); 
};
 
class StaffGroupInfo
{
public:
    std::optional<size_t> startSlot;                    
    std::optional<size_t> endSlot;                      
    MusxInstance<StaffGroup> group;                     
    MusxInstanceList<others::StaffUsed> systemStaves;    
 
    StaffGroupInfo(const MusxInstance<StaffGroup>& staffGroup,
        const MusxInstanceList<others::StaffUsed>& inpSysStaves);
 
    std::optional<size_t> numStaves() const
    {
        if (startSlot && endSlot) {
            return endSlot.value() - startSlot.value() + 1;
        }
        return std::nullopt;
    }
 
    void iterateStaves(MeasCmper measId, Edu eduPosition, std::function<bool(const MusxInstance<others::StaffComposite>&)> iterator) const;
 
    static std::vector<StaffGroupInfo> getGroupsAtMeasure(MeasCmper measureId, Cmper linkedPartId,
        const MusxInstanceList<others::StaffUsed>& systemStaves);
};
 
class StaffSize : public DetailsBase
{
public:
    explicit StaffSize(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, Cmper system, Cmper staffId)
        : DetailsBase(document, partId, shareMode, system, staffId)
    {
    }
 
    int staffPercent{}; 
 
    util::Fraction calcStaffScaling() const
    { return util::Fraction::fromPercent(staffPercent); }
 
    constexpr static std::string_view XmlNodeName = "staffSize"; 
    static const xml::XmlElementArray<StaffSize>& xmlMappingArray(); 
};
 
class StemAlterations : public EntryDetailsBase
{
public:
    explicit StemAlterations(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum)
        : EntryDetailsBase(document, partId, shareMode, entnum)
    {
    }
 
    Evpu upVertAdjust{};    
    Evpu downVertAdjust{};  
    Evpu upHorzAdjust{};    
    Evpu downHorzAdjust{};  
 
    constexpr static std::string_view XmlNodeName = "stemAdjust"; 
    static const xml::XmlElementArray<StemAlterations>& xmlMappingArray(); 
};
 
class StemAlterationsUnderBeam : public StemAlterations
{
public:
    using StemAlterations::StemAlterations;
 
    constexpr static std::string_view XmlNodeName = "beamStemAdjust"; 
};
 
class TablatureNoteMods : public NoteDetailsBase
{
public:
    explicit TablatureNoteMods(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum, Inci inci)
        : NoteDetailsBase(document, partId, shareMode, entnum, inci)
    {
    }
 
    NoteNumber noteId{};   
    int stringNumber{};    
 
    NoteNumber getNoteId() const override { return noteId; }
 
    constexpr static std::string_view XmlNodeName = "tabAlter"; 
    static const xml::XmlElementArray<TablatureNoteMods>& xmlMappingArray(); 
};
 
class TieAlterBase : public NoteDetailsBase
{
public:
    explicit TieAlterBase(const DocumentWeakPtr& document, Cmper partId, Base::ShareMode shareMode, EntryNumber entnum, Inci inci)
        : NoteDetailsBase(document, partId, shareMode, entnum, inci)
    {
    }
 
    enum class ConnectionType
    {
        None,                   
        EntryLeftNoteCenter,    
        EntryRightNoteCenter,   
        NoteLeftNoteCenter,     
        NoteRightNoteCenter,    
        NoteCenterNoteBottom,   
        NoteCenterNoteTop,      
        DotRightNoteCenter,     
        AccidentalLeftNoteCenter, 
        EntryCenterNoteBottom,  
        EntryCenterNoteTop,     
        NoteLeftNoteBottom,     
        NoteRightNoteBottom,    
        NoteLeftNoteTop,        
        NoteRightNoteTop,       
        SystemEnd,              
        SystemStart             
    };
 
    enum class DirectionContext
    {
        None,       
        Under,      
        Over        
    };
 
    NoteNumber noteId{};                   
    Evpu xStart{};                         
    Evpu xEnd{};                           
    Evpu yStart{};                         
    Evpu yEnd{};                           
    bool outerLocal{};                     
    bool outerOn{};                        
    bool afterSingleDotLocal{};            
    bool afterSingleDotOn{};               
    bool afterMultiDotsLocal{};            
    bool afterMultiDotsOn{};               
    bool shiftForSecondsLocal{};           
    bool shiftForSecondsOn{};              
    bool beforeSingleAcciLocal{};          
    bool beforeSingleAcciOn{};             
    bool down{};                           
    bool breakTimeLocal{};                 
    bool breakTimeOn{};                    
    bool breakKeyLocal{};                  
    bool breakKeyOn{};                     
    bool freezeDirection{};                
    bool noSpecialArc{};                   
    bool stPtAdjOn{};                      
    ConnectionType stPtEntCnct{};          
    DirectionContext stPtContext{};        
    bool enPtAdjOn{};                      
    ConnectionType enPtEntCnct{};          
    DirectionContext enPtContext{};        
    Evpu insetRatio1{};                    
    Evpu height1{};                        
    Evpu insetRatio2{};                    
    Evpu height2{};                        
    bool ctlPtAdjOn{};                     
    bool ctlPtFixed{};                     
 
    NoteNumber getNoteId() const override { return noteId; }
 
    static const xml::XmlElementArray<TieAlterBase>& xmlMappingArray(); 
};
 
class TieAlterEnd : public TieAlterBase
{
public:
    using TieAlterBase::TieAlterBase;
 
    constexpr static std::string_view XmlNodeName = "tieAlterEnd"; 
    static const xml::XmlElementArray<TieAlterEnd>& xmlMappingArray(); 
};
 
class TieAlterStart : public TieAlterBase
{
public:
    using TieAlterBase::TieAlterBase;
 
    constexpr static std::string_view XmlNodeName = "tieAlterStart"; 
    static const xml::XmlElementArray<TieAlterStart>& xmlMappingArray(); 
};
 
class TupletDef : public EntryDetailsBase
{
public:
    explicit TupletDef(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum, Inci inci)
        : EntryDetailsBase(document, partId, shareMode, entnum, inci)
    {
    }
 
    using AutoBracketStyle = options::TupletOptions::AutoBracketStyle;
    using NumberStyle = options::TupletOptions::NumberStyle;
    using PositioningStyle = options::TupletOptions::PositioningStyle;
    using BracketStyle = options::TupletOptions::BracketStyle;
 
    int displayNumber{};                    
    Edu displayDuration{};                  
    int referenceNumber{};                  
    Edu referenceDuration{};                
    bool alwaysFlat{};                      
    bool fullDura{};                        
    bool metricCenter{};                    
    bool avoidStaff{};                      
    AutoBracketStyle autoBracketStyle{};    
    bool hidden{};                          
    Evpu tupOffX{};                         
    Evpu tupOffY{};                         
    Evpu brackOffX{};                       
    Evpu brackOffY{};                       
    NumberStyle numStyle{};                 
    PositioningStyle posStyle{};            
    bool allowHorz{};                       
    bool ignoreHorzNumOffset{};             
    bool breakBracket{};                    
    bool matchHooks{};                      
    bool useBottomNote{};                   
    BracketStyle brackStyle{};              
    bool smartTuplet{};                     
    Evpu leftHookLen{};                     
    Evpu leftHookExt{};                     
    Evpu rightHookLen{};                    
    Evpu rightHookExt{};                    
    Evpu manualSlopeAdj{};                  
 
    util::Fraction calcReferenceDuration() const { return util::Fraction(referenceNumber * referenceDuration, Edu(NoteType::Whole)); }
 
    util::Fraction calcDisplayDuration() const { return util::Fraction(displayNumber * displayDuration, Edu(NoteType::Whole)); }
 
    util::Fraction calcRatio() const { return util::Fraction(referenceNumber * referenceDuration, displayNumber * displayDuration); }
 
    constexpr static std::string_view XmlNodeName = "tupletDef";    
    static const xml::XmlElementArray<TupletDef>& xmlMappingArray();   
};
 
} // namespace details
} // namespace dom
} // namespace entries