XLSlicer.hpp

Go to the documentation of this file.

#ifndef OPENXLSX_XLSLICER_HPP
#define OPENXLSX_XLSLICER_HPP
 
#include "OpenXLSX-Exports.hpp"
#include "XLXmlFile.hpp"
#include "XLXmlParser.hpp"
#include <string>
#include <string_view>
#include <vector>
#include <cstdint>
 
namespace OpenXLSX
{
    class XLWorksheet;
    class XLDocument;
 
    // ─────────────────────────────────────────────────────────────────────────
    // XLSlicerStyle — strongly-typed enum replacing magic strings
    // ─────────────────────────────────────────────────────────────────────────
    enum class XLSlicerStyle : uint8_t {
        // Light styles
        Light1 = 0, Light2, Light3, Light4, Light5, Light6,
        // Dark styles
        Dark1, Dark2, Dark3, Dark4, Dark5, Dark6,
        // Other styles
        Other1, Other2,
        // Custom (use setStyleRaw for arbitrary names)
        Custom = 255
    };
 
    OPENXLSX_EXPORT std::string xlSlicerStyleToString(XLSlicerStyle style);
    OPENXLSX_EXPORT XLSlicerStyle xlSlicerStyleFromString(std::string_view s);
 
    // ─────────────────────────────────────────────────────────────────────────
    // XLSlicer — three-source unified handle
    //
    // A slicer's full state lives across three XML parts:
    //   1. xl/slicers/slicerN.xml     → name, caption, style, showCaption …
    //   2. xl/slicerCaches/slicerCacheN.xml → selectedItems, sortOrder …
    //   3. xl/drawings/drawingM.xml  → position anchor (cellRef, width, height)
    //
    // This class holds references to all three so every property is readable
    // and writable from a single handle. All setters return *this for chaining.
    // ─────────────────────────────────────────────────────────────────────────
    class OPENXLSX_EXPORT XLSlicer
    {
    public:
        // ── Constructors ────────────────────────────────────────────────────
        XLSlicer() = default;
 
        explicit XLSlicer(XLXmlData* slicerXml);
 
        XLSlicer(XLXmlData* slicerXml,
                 XMLNode    slicerNode,
                 XLXmlData* cacheXml,
                 XMLNode    anchorNode,
                 XLWorksheet* worksheet);
 
        XLSlicer(const XLSlicer&)            = default;
        XLSlicer(XLSlicer&&) noexcept        = default;
        XLSlicer& operator=(const XLSlicer&) = default;
        XLSlicer& operator=(XLSlicer&&)      = default;
        ~XLSlicer()                          = default;
 
        // ── Validity ────────────────────────────────────────────────────────
        [[nodiscard]] bool valid() const { return m_slicerXml != nullptr; }
        explicit operator bool() const   { return valid(); }
 
        // ── Source 1: slicer XML properties ─────────────────────────────────
 
        [[nodiscard]] std::string   name()         const;
        [[nodiscard]] std::string   caption()      const;
        [[nodiscard]] std::string   cache()        const;  
        [[nodiscard]] XLSlicerStyle style()        const;
        [[nodiscard]] std::string   styleRaw()     const;  
        [[nodiscard]] bool          showCaption()  const;
        [[nodiscard]] int           columnCount()  const;  
        [[nodiscard]] bool          lockedPosition() const;
        [[nodiscard]] int           rowHeight()    const;  
 
        void setName(std::string_view name);
        XLSlicer& setCaption(std::string_view caption);
        XLSlicer& setStyle(XLSlicerStyle style);
        XLSlicer& setStyleRaw(std::string_view rawStyleName); 
        XLSlicer& setShowCaption(bool show);
        XLSlicer& setColumnCount(int cols);        
        XLSlicer& setLockedPosition(bool locked);
        XLSlicer& setRowHeight(int emuHeight);     
 
        // ── Source 2: cache XML — filter items ──────────────────────────────
 
        [[nodiscard]] std::vector<std::string> items()         const;
        [[nodiscard]] std::vector<std::string> selectedItems() const;
        [[nodiscard]] bool isSortDescending() const;
 
        XLSlicer& showOnly(const std::vector<std::string>& itemsToShow);
        XLSlicer& showAll();
        XLSlicer& hideItems(const std::vector<std::string>& itemsToHide);
        XLSlicer& setSortDescending(bool desc);
 
        // ── Source 3: drawing anchor — position & size ───────────────────────
 
        [[nodiscard]] std::string cellRef() const;
        [[nodiscard]] uint32_t    width()   const;
        [[nodiscard]] uint32_t    height()  const;
 
        XLSlicer& moveTo(std::string_view cellRef);
        XLSlicer& resize(uint32_t widthPx, uint32_t heightPx);
 
        // ── Internals used by XLSlicerCollection ────────────────────────────
        XLXmlData*   slicerXml()  const { return m_slicerXml; }
        XLXmlData*   cacheXml()   const { return m_cacheXml;  }
 
    private:
        XMLNode slicerNode() const;
        XMLNode cacheRoot()  const;
 
        XLXmlData*   m_slicerXml{nullptr};
        XMLNode      m_slicerNode;
        XLXmlData*   m_cacheXml{nullptr};
        XMLNode      m_anchorNode;       
        XLWorksheet* m_worksheet{nullptr};
    };
 
} // namespace OpenXLSX
 
#endif // OPENXLSX_XLSLICER_HPP