XLComments.hpp

Go to the documentation of this file.

#ifndef OPENXLSX_XLCOMMENTS_HPP
#define OPENXLSX_XLCOMMENTS_HPP
 
// ===== External Includes ===== //
#include <cstdint>          // uint8_t, uint16_t, uint32_t
#include <ostream>          // std::basic_ostream
#include <unordered_map>    // std::unordered_map
 
// ===== OpenXLSX Includes ===== //
#include "OpenXLSX-Exports.hpp"
// #include "XLDocument.hpp"
#include "XLDrawing.hpp"    // XLVmlDrawing
#include "XLException.hpp"
#include "XLRichText.hpp"
#include "XLXmlData.hpp"
#include "XLXmlFile.hpp"
 
namespace OpenXLSX
{
    class OPENXLSX_EXPORT XLComment
    {
    public:
        XLComment() = delete;    // do not allow default constructor (for now) - could still be constructed with an empty XMLNode
 
        explicit XLComment(XMLNode node);
 
        XLComment(const XLComment& other) = default;
 
        XLComment(XLComment&& other) noexcept = default;
        ~XLComment()                          = default;
 
        XLComment& operator=(const XLComment& other) = default;
 
        XLComment& operator=(XLComment&& other) noexcept = default;
 
        bool        valid() const;
        std::string ref() const;    // the cell reference of the comment
        std::string text() const;
        XLRichText  richText() const;
        uint16_t    authorId() const;
        XLComment&  setText(const std::string& newText);
        XLComment&  setRichText(const XLRichText& richText);
        XLComment&  setAuthorId(uint16_t newAuthorId);
 
        // /**
        //  * @brief Return a string summary of the comment properties
        //  * @return string with info about the comment object
        //  */
        // std::string summary() const;
 
    private:
        mutable XMLNode m_commentNode; 
    };
 
    class OPENXLSX_EXPORT XLComments : public XLXmlFile
    {
        friend class XLWorksheet;    // for access to XLXmlFile::getXmlPath
    public:
        XLComments();
 
        explicit XLComments(XLXmlData* xmlData);
 
        XLComments(const XLComments& other) = default;
 
        XLComments(XLComments&& other) noexcept = default;
 
        ~XLComments() = default;
 
        XLComments& operator=(XLComments&& other) noexcept = default;
 
        XLComments& operator=(const XLComments& other) = default;
 
        bool setVmlDrawing(const XLVmlDrawing& vmlDrawing);
 
    private:
        XMLNode authorNode(uint16_t index) const;
        XMLNode commentNode(size_t index) const;
        XMLNode commentNode(const std::string& cellRef) const;
        void    setupVmlShape(const std::string& cellRef,
                              uint32_t           destRow,
                              uint16_t           destCol,
                              bool               newCommentCreated,
                              uint16_t           widthCols  = 4,
                              uint16_t           heightRows = 6);
 
    public:
        uint16_t authorCount() const;
 
        std::string author(uint16_t index) const;
 
        bool deleteAuthor(uint16_t index);
 
        uint16_t addAuthor(const std::string& authorName);
 
        size_t count() const;
 
        uint16_t authorId(const std::string& cellRef) const;
 
        bool deleteComment(const std::string& cellRef);
 
        XLComment get(size_t index) const;
 
        std::string get(std::string const& cellRef) const;
 
        bool set(std::string const& cellRef,
                 std::string const& comment,
                 uint16_t           authorId_  = 0,
                 uint16_t           widthCols  = 4,
                 uint16_t           heightRows = 6);
 
        bool set(std::string const& cellRef,
                 std::string const& comment,
                 std::string const& authorName,
                 uint16_t           widthCols  = 4,
                 uint16_t           heightRows = 6);
 
        bool setRichText(std::string const& cellRef,
                         const XLRichText&  richText,
                         uint16_t           authorId_  = 0,
                         uint16_t           widthCols  = 4,
                         uint16_t           heightRows = 6);
 
        bool setRichText(std::string const& cellRef,
                         const XLRichText&  richText,
                         std::string const& authorName,
                         uint16_t           widthCols  = 4,
                         uint16_t           heightRows = 6);
 
        XLShape shape(std::string const& cellRef);
 
        bool setVisible(std::string const& cellRef, bool visible);
 
        void print(std::basic_ostream<char>& ostr) const;
 
    private:
        XMLNode                                          m_authors{};
        XMLNode                                          m_commentList{};
        XLVmlDrawing                                     m_vmlDrawing;
        mutable std::unordered_map<std::string, XMLNode> m_commentMap{};
        mutable XMLNode m_hintNode{};    // the last comment XML Node accessed by index is stored here, if any - will be reset when comments
                                         // are inserted or deleted
        mutable size_t m_hintIndex{0};    // this has the index at which m_hintNode was accessed, only valid if not m_hintNode.empty()
        inline static const std::vector<std::string_view> m_nodeOrder = {// comments XML node required child sequence
                                                                         "authors",
                                                                         "commentList"};
    };
}    // namespace OpenXLSX
 
#endif    // OPENXLSX_XLCOMMENTS_HPP