XLDrawing.hpp

Go to the documentation of this file.

#ifndef OPENXLSX_XLDRAWING_HPP
#define OPENXLSX_XLDRAWING_HPP
 
// ===== External Includes ===== //
#include <cstdint>    // uint8_t, uint16_t, uint32_t
#include <gsl/pointers>
#include <ostream>    // std::basic_ostream
#include <string_view>
 
// ===== OpenXLSX Includes ===== //
#include "OpenXLSX-Exports.hpp"
// #include "XLDocument.hpp"
#include "XLConstants.hpp"
#include "XLException.hpp"
#include "XLImageOptions.hpp"
#include "XLXmlData.hpp"
#include "XLXmlFile.hpp"
 
#include <memory>
#include "XLRichText.hpp"
 
namespace OpenXLSX
{
    class XLRelationships;
 
    extern const std::string_view ShapeNodeName;        // = "v:shape"
    extern const std::string_view ShapeTypeNodeName;    // = "v:shapetype"
 
    // NOTE: numerical values of XLShapeTextVAlign and XLShapeTextHAlign are shared with the same alignments from XLAlignmentStyle
    // (XLStyles.hpp)
    enum class XLShapeTextVAlign : uint8_t {
        Center  = 3,     // value="center",           both
        Top     = 4,     // value="top",              vertical only
        Bottom  = 5,     // value="bottom",           vertical only
        Invalid = 255    // all other values
    };
    constexpr const XLShapeTextVAlign XLDefaultShapeTextVAlign = XLShapeTextVAlign::Top;
 
    enum class XLShapeTextHAlign : uint8_t {
        Left    = 1,     // value="left",             horizontal only
        Right   = 2,     // value="right",            horizontal only
        Center  = 3,     // value="center",           both
        Invalid = 255    // all other values
    };
    constexpr const XLShapeTextHAlign XLDefaultShapeTextHAlign = XLShapeTextHAlign::Left;
 
    class OPENXLSX_EXPORT XLShapeClientData
    {
    public:
        XLShapeClientData();
 
        explicit XLShapeClientData(const XMLNode& node);
 
        XLShapeClientData(const XLShapeClientData& other) = default;
 
        XLShapeClientData(XLShapeClientData&& other) noexcept = default;
 
        ~XLShapeClientData() = default;
 
        XLShapeClientData& operator=(const XLShapeClientData& other) = default;
 
        XLShapeClientData& operator=(XLShapeClientData&& other) noexcept = default;
 
        std::string objectType() const;    // attribute ObjectType, value "Note"
        bool moveWithCells() const;    // element x:MoveWithCells - true = present or lowercase node_pcdata "true", false = not present or
                                       // lowercase node_pcdata "false"
        bool              sizeWithCells() const;    // element x:SizeWithCells - logic as in MoveWithCells
        std::string       anchor() const;           // element x:Anchor - e.g. "3, 23, 0, 0, 4, 25, 3, 5"
        bool              autoFill() const;         // element x:AutoFill - logic as in MoveWithCells
        XLShapeTextVAlign textVAlign() const;       // element x:TextVAlign - Top, ???
        XLShapeTextHAlign textHAlign() const;       // element x:TextHAlign - Left, ???
        uint32_t          row() const;              // element x:Row, 0-indexed row of cell to which this shape is linked
        uint16_t          column() const;           // element x:Column, 0-indexed column of cell to which this shape is linked
 
        bool setObjectType(std::string_view newObjectType);
        bool setMoveWithCells(bool set = true);
        bool setSizeWithCells(bool set = true);
        bool setAnchor(std::string_view newAnchor);
        bool setAutoFill(bool set = true);
        bool setTextVAlign(XLShapeTextVAlign newTextVAlign);
        bool setTextHAlign(XLShapeTextHAlign newTextHAlign);
        bool setRow(uint32_t newRow);
        bool setColumn(uint16_t newColumn);
 
    private:
        mutable XMLNode                                   m_clientDataNode; 
        inline static const std::vector<std::string_view> m_nodeOrder =
            {"x:MoveWithCells", "x:SizeWithCells", "x:Anchor", "x:AutoFill", "x:TextVAlign", "x:TextHAlign", "x:Row", "x:Column"};
    };
 
    struct XLShapeStyleAttribute
    {
        std::string name;
        std::string value;
    };
 
    class OPENXLSX_EXPORT XLShapeStyle
    {
    public:
        XLShapeStyle();
 
        explicit XLShapeStyle(const std::string& styleAttribute);
 
        explicit XLShapeStyle(const XMLAttribute& styleAttribute);
 
    private:
        int16_t attributeOrderIndex(std::string_view attributeName) const;
        XLShapeStyleAttribute getAttribute(std::string_view attributeName, std::string_view valIfNotFound = "") const;
        bool                  setAttribute(std::string_view attributeName, std::string_view attributeValue);
 
    public:
        std::string position() const;
        uint16_t    marginLeft() const;
        uint16_t    marginTop() const;
        uint16_t    width() const;
        uint16_t    height() const;
        std::string msoWrapStyle() const;
        std::string vTextAnchor() const;
        bool        hidden() const;
        bool        visible() const;
 
        std::string raw() const { return m_style; }
 
        bool setPosition(std::string_view newPosition);
        bool setMarginLeft(uint16_t newMarginLeft);
        bool setMarginTop(uint16_t newMarginTop);
        bool setWidth(uint16_t newWidth);
        bool setHeight(uint16_t newHeight);
        bool setMsoWrapStyle(std::string_view newMsoWrapStyle);
        bool setVTextAnchor(std::string_view newVTextAnchor);
        bool hide();    // set visibility:hidden
        bool show();    // set visibility:visible
 
        bool setRaw(std::string_view newStyle)
        {
            m_style = newStyle;
            return true;
        }
 
    private:
        mutable std::string  m_style;    // mutable so getter functions can update it from m_styleAttribute if the latter is not empty
        mutable XMLAttribute m_styleAttribute;
        inline static const std::vector<std::string_view> m_nodeOrder = {"position",
                                                                         "margin-left",
                                                                         "margin-top",
                                                                         "width",
                                                                         "height",
                                                                         "mso-wrap-style",
                                                                         "mso-fit-shape-to-text",    // Added for auto-size support
                                                                         "v-text-anchor",
                                                                         "visibility"};
    };
 
    class OPENXLSX_EXPORT XLShape
    {
        friend class XLVmlDrawing;    // for access to m_shapeNode in XLVmlDrawing::addShape
        friend class XLComments;      // added for access to m_shapeNode in XLComments::set
    public:
        XLShape();
 
        explicit XLShape(const XMLNode& node);
 
        XLShape(const XLShape& other) = default;
 
        XLShape(XLShape&& other) noexcept = default;
 
        ~XLShape() = default;
 
        XLShape& operator=(const XLShape& other);
 
        XLShape& operator=(XLShape&& other) noexcept = default;
 
        std::string  shapeId() const;        // v:shape attribute id - shape_# - can't be set by the user
        std::string  fillColor() const;      // v:shape attribute fillcolor, #<3 byte hex code>, e.g. #ffffc0
        bool         stroked() const;        // v:shape attribute stroked "t" ("f"?)
        std::string  type() const;           // v:shape attribute type, link to v:shapetype attribute id
        bool         allowInCell() const;    // v:shape attribute o:allowincell "f"
        XLShapeStyle style();                // v:shape attribute style, but constructed from the XMLAttribute
 
        XLShapeClientData clientData();    // v:shape subnode x:ClientData
 
        // NOTE: setShapeId is not available because shape id is managed by the parent class in createShape
        bool setFillColor(std::string_view newFillColor);
        bool setStroked(bool set);
        bool setType(std::string_view newType);
        bool setAllowInCell(bool set);
        bool setStyle(std::string_view newStyle);
        bool setStyle(XLShapeStyle const& newStyle);
 
    private:
        mutable XMLNode                                   m_shapeNode; 
        inline static const std::vector<std::string_view> m_nodeOrder =
            {"v:shadow", "v:fill", "v:stroke", "v:path", "v:textbox", "x:ClientData"};
    };
 
    enum class XLVectorShapeType {
        Rectangle,
        Ellipse,
        Line,
        Triangle,
        RightTriangle,
        Arrow,
        Diamond,
        Parallelogram,
        Hexagon,
        Star4,
        Star5,
        Star16,
        Star24,
        Heart,
        SmileyFace,
        Cloud,
        Donut,
        Ribbon,
        Sun,
        Moon,
        LightningBolt,
        FlowChartProcess,
        FlowChartDecision,
        FlowChartDocument,
        FlowChartData
    };
 
    struct XLVectorShapeOptions
    {
        XLVectorShapeType type      = XLVectorShapeType::Rectangle;
        std::string       name      = "Shape 1";
        std::string       text      = "";
        std::string       fillColor = "4286F4";    // ARGB, no #
        std::string       lineColor = "000000";
        double            lineWidth = 1.0;
 
        uint32_t width   = 100;
        uint32_t height  = 100;
        int32_t  offsetX = 0;
        int32_t  offsetY = 0;
 
        // If endRow and endCol are specified, the shape uses a twoCellAnchor (resizes with cells)
        std::optional<uint32_t> endRow;
        std::optional<uint32_t> endCol;
        int32_t                 endOffsetX = 0;
        int32_t                 endOffsetY = 0;
 
        // Shape transformations
        uint32_t rotation = 0; // rotation in degrees
        bool     flipH    = false;
        bool     flipV    = false;
 
        // Advanced outline properties
        std::string lineDash   = ""; // e.g. "dash", "sysDash", "dot", "dashDot"
        std::string arrowStart = ""; // e.g. "triangle", "stealth", "diamond"
        std::string arrowEnd   = "";
 
        // Text properties
        std::optional<XLRichText> richText = std::nullopt;
        std::string               horzAlign = ""; // e.g. "ctr", "l", "r"
        std::string               vertAlign = ""; // e.g. "ctr", "t", "b"
 
        std::string macro = "";
    };
    class OPENXLSX_EXPORT XLDrawingItem
    {
    public:
        XLDrawingItem();
        explicit XLDrawingItem(const XMLNode& node, XLDocument* parentDoc = nullptr);
        XLDrawingItem(const XLDrawingItem& other)                = default;
        XLDrawingItem(XLDrawingItem&& other) noexcept            = default;
        ~XLDrawingItem()                                         = default;
        XLDrawingItem& operator=(const XLDrawingItem& other)     = default;
        XLDrawingItem& operator=(XLDrawingItem&& other) noexcept = default;
 
        std::string name() const;
        std::string description() const;
        uint32_t    row() const;
        uint32_t    col() const;
        uint32_t    width() const;     // in pixels (converted from EMUs)
        uint32_t    height() const;    // in pixels (converted from EMUs)
        std::string relationshipId() const;
        
        std::vector<uint8_t> imageBinary() const;
 
    private:
        mutable XMLNode m_anchorNode;
        XLDocument*     m_parentDoc{nullptr};
    };
 
    class OPENXLSX_EXPORT XLDrawing : public XLXmlFile
    {
        friend class XLWorksheet;
        friend class XLDocument;
 
    public:
        XLDrawing() : XLXmlFile(nullptr) {};
 
        explicit XLDrawing(gsl::not_null<XLXmlData*> xmlData);
 
        XLDrawing(const XLDrawing& other);
 
        XLDrawing(XLDrawing&& other) noexcept;
 
        ~XLDrawing() = default;
 
        XLDrawing& operator=(const XLDrawing& other);
 
        XLDrawing& operator=(XLDrawing&& other) noexcept;
 
        void addImage(std::string_view      rId,
                      std::string_view      name,
                      std::string_view      description,
                      uint32_t              row,
                      uint32_t              col,
                      uint32_t              width,
                      uint32_t              height,
                      const XLImageOptions& options = XLImageOptions());
 
        void addShape(uint32_t row, uint32_t col, const XLVectorShapeOptions& options = XLVectorShapeOptions());
        void addChartAnchor(std::string_view rId, std::string_view name, uint32_t row, uint32_t col, uint32_t width, uint32_t height);
 
        void addChartAnchor(std::string_view rId, std::string_view name, uint32_t row, uint32_t col, XLDistance width, XLDistance height);
 
        void addScaledImage(std::string_view rId,
                            std::string_view name,
                            std::string_view description,
                            std::string_view data,
                            uint32_t         row,
                            uint32_t         col,
                            double           scalingFactor = 1.0);
 
        XLRelationships& relationships();
 
        uint32_t imageCount() const;
 
        XLDrawingItem image(uint32_t index) const;
 
    private:
        // Helper to add namespaces if missing
        void initXml();
 
        std::unique_ptr<XLRelationships> m_relationships; 
    };
 
    class OPENXLSX_EXPORT XLVmlDrawing : public XLXmlFile
    {
        friend class XLWorksheet;    // for access to XLXmlFile::getXmlPath
        friend class XLComments;     // for access to firstShapeNode
    public:
        XLVmlDrawing() : XLXmlFile(nullptr) {};
 
        explicit XLVmlDrawing(gsl::not_null<XLXmlData*> xmlData);
 
        XLVmlDrawing(const XLVmlDrawing& other) = default;
 
        XLVmlDrawing(XLVmlDrawing&& other) noexcept = default;
 
        ~XLVmlDrawing() = default;
 
        XLVmlDrawing& operator=(const XLVmlDrawing&) = default;
 
        XLVmlDrawing& operator=(XLVmlDrawing&& other) noexcept = default;
 
    private:    // helper functions with repeating code
        XMLNode firstShapeNode() const;
        XMLNode lastShapeNode() const;
        XMLNode shapeNode(uint32_t index) const;
 
    public:
        XMLNode shapeNode(std::string_view cellRef) const;
 
        uint32_t shapeCount() const;
 
        XLShape shape(uint32_t index) const;
 
        bool deleteShape(uint32_t index);
        bool deleteShape(std::string_view cellRef);
 
        XLShape createShape(const XLShape& shapeTemplate = XLShape());
 
        void print(std::basic_ostream<char>& ostr) const;
 
    private:
        uint32_t    m_shapeCount{0};
        uint32_t    m_lastAssignedShapeId{0};
        std::string m_defaultShapeTypeId{};
    };
}    // namespace OpenXLSX
 
#endif    // OPENXLSX_XLDRAWING_HPP