sc/inc/postit.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_SC_INC_POSTIT_HXX
  21 #define INCLUDED_SC_INC_POSTIT_HXX
  22
  23 #include <rtl/ustring.hxx>
  24 #include "address.hxx"
  25 #include "scdllapi.h"
  26
  27 #include <map>
  28 #include <memory>
  29
  30 class EditTextObject;
  31 class OutlinerParaObject;
  32 class SdrCaptionObj;
  33 class SdrPage;
  34 class SfxItemSet;
  35 class ScDocument;
  36 class Rectangle;
  37 struct ScCaptionInitData;
  38
  39 /** Internal data for a cell annotation. */
  40 struct SC_DLLPUBLIC ScNoteData
  41 {
  42     typedef std::shared_ptr< ScCaptionInitData > ScCaptionInitDataRef;
  43
  44     OUString     maDate;             /// Creation date of the note.
  45     OUString     maAuthor;           /// Author of the note.
  46     ScCaptionInitDataRef mxInitData;        /// Initial data for invisible notes without SdrObject.
  47     SdrCaptionObj*      mpCaption;          /// Drawing object representing the cell note.
  48     bool                mbShown;            /// True = note is visible.
  49
  50     explicit            ScNoteData( bool bShown = false );
  51                         ~ScNoteData();
  52 };
  53
  54 /**
  55  * Additional class containing cell annotation data.
  56  */
  57 class SC_DLLPUBLIC ScPostIt
  58 {
  59 public:
  60
  61     /** Creates an empty note and its caption object and places it according to
  62         the passed cell position. */
  63     explicit            ScPostIt( ScDocument& rDoc, const ScAddress& rPos );
  64
  65     /** Copy constructor. Clones the note and its caption to a new document. */
  66     explicit            ScPostIt( ScDocument& rDoc, const ScAddress& rPos, const ScPostIt& rNote );
  67
  68     /** Creates a note from the passed note data with existing caption object.
  69
  70         @param bAlwaysCreateCaption  Instead of a pointer to an existing
  71             caption object, the passed note data structure may contain a
  72             reference to an ScCaptionInitData structure containing information
  73             about how to construct a missing caption object. If sal_True is passed,
  74             the caption drawing object will be created immediately from that
  75             data. If sal_False is passed and the note is not visible, it will
  76             continue to cache that data until the caption object is requested.
  77      */
  78     explicit            ScPostIt(
  79                             ScDocument& rDoc, const ScAddress& rPos,
  80                             const ScNoteData& rNoteData, bool bAlwaysCreateCaption );
  81
  82     /** Removes the caption object from drawing layer, if this note is its owner. */
  83                         ~ScPostIt();
  84
  85     /** Clones this note and its caption object, if specified.
  86
  87         @param bCloneCaption  If sal_True is passed, clones the caption object and
  88             inserts it into the drawing layer of the destination document. If
  89             sal_False is passed, the cloned note will refer to the old caption
  90             object (used e.g. in Undo documents to restore the pointer to the
  91             existing caption object).
  92      */
  93     ScPostIt*           Clone(
  94                             const ScAddress& rOwnPos,
  95                             ScDocument& rDestDoc, const ScAddress& rDestPos,
  96                             bool bCloneCaption ) const;
  97
  98     /** Returns the data struct containing all note settings. */
  99     const ScNoteData& GetNoteData() const { return maNoteData;}
 100
 101     /** Returns the creation date of this note. */
 102     const OUString& GetDate() const { return maNoteData.maDate;}
 103     /** Sets a new creation date for this note. */
 104     void SetDate( const OUString& rDate );
 105
 106     /** Returns the author date of this note. */
 107     const OUString& GetAuthor() const { return maNoteData.maAuthor;}
 108     /** Sets a new author date for this note. */
 109     void SetAuthor( const OUString& rAuthor );
 110
 111     /** Sets date and author from system settings. */
 112     void                AutoStamp();
 113
 114     /** Returns the pointer to the current outliner object, or null. */
 115     const OutlinerParaObject* GetOutlinerObject() const;
 116     /** Returns the pointer to the current edit text object, or null. */
 117     const EditTextObject* GetEditTextObject() const;
 118
 119     /** Returns the caption text of this note. */
 120     OUString     GetText() const;
 121     /** Returns true, if the caption text of this note contains line breaks. */
 122     bool                HasMultiLineText() const;
 123     /** Changes the caption text of this note. All text formatting will be lost. */
 124     void                SetText( const ScAddress& rPos, const OUString& rText );
 125
 126     /** Returns an existing note caption object. returns null, if the note
 127         contains initial caption data needed to construct a caption object. */
 128     SdrCaptionObj* GetCaption() const { return maNoteData.mpCaption;}
 129     /** Returns the caption object of this note. Creates the caption object, if
 130         the note contains initial caption data instead of the caption. */
 131     SdrCaptionObj*      GetOrCreateCaption( const ScAddress& rPos ) const;
 132     /** Forgets the pointer to the note caption object. */
 133     void                ForgetCaption();
 134
 135     /** Shows or hides the note caption object. */
 136     void                ShowCaption( const ScAddress& rPos, bool bShow = true );
 137     /** Returns true, if the caption object is visible. */
 138     bool IsCaptionShown() const { return maNoteData.mbShown;}
 139
 140     /** Shows or hides the caption temporarily (does not change internal visibility state). */
 141     void                ShowCaptionTemp( const ScAddress& rPos, bool bShow = true );
 142
 143     /** Updates caption position according to position of the passed cell. */
 144     void                UpdateCaptionPos( const ScAddress& rPos );
 145
 146 private:
 147                         ScPostIt( const ScPostIt& ) = delete;
 148     ScPostIt&           operator=( const ScPostIt& ) = delete;
 149
 150     /** Creates the caption object from initial caption data if existing. */
 151     void                CreateCaptionFromInitData( const ScAddress& rPos ) const;
 152     /** Creates a new caption object at the passed cell position, clones passed existing caption. */
 153     void                CreateCaption( const ScAddress& rPos, const SdrCaptionObj* pCaption = nullptr );
 154     /** Removes the caption object from the drawing layer, if this note is its owner. */
 155     void                RemoveCaption();
 156
 157 private:
 158     ScDocument&         mrDoc;              /// Parent document containing the note.
 159     mutable ScNoteData  maNoteData;         /// Note data with pointer to caption object.
 160 };
 161
 162 class SC_DLLPUBLIC ScNoteUtil
 163 {
 164 public:
 165
 166     /** Creates and returns a caption object for a temporary caption. */
 167     static SdrCaptionObj* CreateTempCaption( ScDocument& rDoc, const ScAddress& rPos,
 168                             SdrPage& rDrawPage, const OUString& rUserText,
 169                             const Rectangle& rVisRect, bool bTailFront );
 170
 171     /** Creates a cell note using the passed caption drawing object.
 172
 173         This function is used in import filters to reuse the imported drawing
 174         object as note caption object.
 175
 176         @param rCaption  The drawing object for the cell note. This object MUST
 177             be inserted into the document at the correct drawing page already.
 178
 179         @return  Pointer to the new cell note object if insertion was
 180             successful (i.e. the passed cell position was valid), null
 181             otherwise. The Calc document is the owner of the note object. The
 182             passed item set and outliner object are deleted automatically if
 183             creation of the note was not successful.
 184      */
 185     static ScPostIt*    CreateNoteFromCaption(
 186                             ScDocument& rDoc, const ScAddress& rPos,
 187                             SdrCaptionObj& rCaption, bool bShown );
 188
 189     /** Creates a cell note based on the passed caption object data.
 190
 191         This function is used in import filters to use an existing imported
 192         item set and outliner object to create a note caption object. For
 193         performance reasons, it is possible to specify that the caption drawing
 194         object for the cell note is not created yet but the note caches the
 195         passed data needed to create the caption object on demand (see
 196         parameter bAlwaysCreateCaption).
 197
 198         @param pItemSet  Pointer to an item set on heap memory containing all
 199             formatting attributes of the caption object. This function takes
 200             ownership of the passed item set.
 201
 202         @param pOutlinerObj  Pointer to an outliner object on heap memory
 203             containing (formatted) text for the caption object. This function
 204             takes ownership of the passed outliner object.
 205
 206         @param rCaptionRect  The absolute position and size of the caption
 207             object. The rectangle may be empty, in this case the default
 208             position and size is used.
 209
 210         @param bAlwaysCreateCaption  If sal_True is passed, the caption drawing
 211             object will be created immediately. If sal_False is passed, the caption
 212             drawing object will not be created if the note is not visible
 213             (bShown = sal_False), but the cell note will cache the passed data.
 214             MUST be set to sal_False outside of import filter implementations!
 215
 216         @return  Pointer to the new cell note object if insertion was
 217             successful (i.e. the passed cell position was valid), null
 218             otherwise. The Calc document is the owner of the note object.
 219      */
 220     static ScPostIt*    CreateNoteFromObjectData(
 221                             ScDocument& rDoc, const ScAddress& rPos,
 222                             SfxItemSet* pItemSet, OutlinerParaObject* pOutlinerObj,
 223                             const Rectangle& rCaptionRect, bool bShown,
 224                             bool bAlwaysCreateCaption );
 225
 226     /** Creates a cell note based on the passed string and inserts it into the
 227         document.
 228
 229         @param rNoteText  The text used to create the note caption object. Must
 230             not be empty.
 231
 232         @param bAlwaysCreateCaption  If sal_True is passed, the caption drawing
 233             object will be created immediately. If sal_False is passed, the caption
 234             drawing object will not be created if the note is not visible
 235             (bShown = sal_False), but the cell note will cache the passed data.
 236             MUST be set to sal_False outside of import filter implementations!
 237
 238         @return  Pointer to the new cell note object if insertion was
 239             successful (i.e. the passed cell position was valid), null
 240             otherwise. The Calc document is the owner of the note object.
 241      */
 242     static ScPostIt*    CreateNoteFromString(
 243                             ScDocument& rDoc, const ScAddress& rPos,
 244                             const OUString& rNoteText, bool bShown,
 245                             bool bAlwaysCreateCaption );
 246
 247 };
 248
 249 namespace sc {
 250
 251 struct NoteEntry
 252 {
 253     ScAddress maPos;
 254     const ScPostIt* mpNote;
 255
 256     NoteEntry( const ScAddress& rPos, const ScPostIt* pNote );
 257 };
 258
 259 }
 260
 261 #endif
 262 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */