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 SC_POSTIT_HXX
  21 #define SC_POSTIT_HXX
  22
  23 #include <boost/shared_ptr.hpp>
  24 #include <rtl/ustring.hxx>
  25 #include "address.hxx"
  26 #include "scdllapi.h"
  27
  28 #include <map>
  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 // ============================================================================
  40
  41 /** Internal data for a cell annotation. */
  42 struct SC_DLLPUBLIC ScNoteData
  43 {
  44     typedef ::boost::shared_ptr< ScCaptionInitData > ScCaptionInitDataRef;
  45
  46     OUString     maDate;             /// Creation date of the note.
  47     OUString     maAuthor;           /// Author of the note.
  48     ScCaptionInitDataRef mxInitData;        /// Initial data for invisible notes without SdrObject.
  49     SdrCaptionObj*      mpCaption;          /// Drawing object representing the cell note.
  50     bool                mbShown;            /// True = note is visible.
  51
  52     explicit            ScNoteData( bool bShown = false );
  53                         ~ScNoteData();
  54 };
  55
  56 // ============================================================================
  57
  58 /**
  59  * Additional class containing cell annotation data.
  60  */
  61 class SC_DLLPUBLIC ScPostIt
  62 {
  63 public:
  64     /** Creates an empty note and its caption object and places it according to
  65         the passed cell position. */
  66     explicit            ScPostIt( ScDocument& rDoc, const ScAddress& rPos, bool bShown );
  67
  68     /** Copy constructor. Clones the note and its caption to a new document. */
  69     explicit            ScPostIt( ScDocument& rDoc, const ScAddress& rPos, const ScPostIt& rNote );
  70
  71     /** Creates a note from the passed note data with existing caption object.
  72
  73         @param bAlwaysCreateCaption  Instead of a pointer to an existing
  74             caption object, the passed note data structure may contain a
  75             reference to an ScCaptionInitData structure containing information
  76             about how to construct a missing caption object. If sal_True is passed,
  77             the caption drawing object will be created immediately from that
  78             data. If sal_False is passed and the note is not visible, it will
  79             continue to cache that data until the caption object is requested.
  80      */
  81     explicit            ScPostIt(
  82                             ScDocument& rDoc, const ScAddress& rPos,
  83                             const ScNoteData& rNoteData, bool bAlwaysCreateCaption );
  84
  85     /** Removes the caption object from drawing layer, if this note is its owner. */
  86                         ~ScPostIt();
  87
  88     /** Clones this note and its caption object, if specified.
  89
  90         @param bCloneCaption  If sal_True is passed, clones the caption object and
  91             inserts it into the drawing layer of the destination document. If
  92             sal_False is passed, the cloned note will refer to the old caption
  93             object (used e.g. in Undo documents to restore the pointer to the
  94             existing caption object).
  95      */
  96     ScPostIt*           Clone(
  97                             const ScAddress& rOwnPos,
  98                             ScDocument& rDestDoc, const ScAddress& rDestPos,
  99                             bool bCloneCaption ) const;
 100
 101     /** Returns the data struct containing all note settings. */
 102     inline const ScNoteData& GetNoteData() const { return maNoteData; }
 103
 104     /** Returns the creation date of this note. */
 105     inline const OUString& GetDate() const { return maNoteData.maDate; }
 106     /** Sets a new creation date for this note. */
 107     inline void         SetDate( const OUString& rDate ) { maNoteData.maDate = rDate; }
 108
 109     /** Returns the author date of this note. */
 110     inline const OUString& GetAuthor() const { return maNoteData.maAuthor; }
 111     /** Sets a new author date for this note. */
 112     inline void         SetAuthor( const OUString& rAuthor ) { maNoteData.maAuthor = rAuthor; }
 113
 114     /** Sets date and author from system settings. */
 115     void                AutoStamp();
 116
 117     /** Returns the pointer to the current outliner object, or null. */
 118     const OutlinerParaObject* GetOutlinerObject() const;
 119     /** Returns the pointer to the current edit text object, or null. */
 120     const EditTextObject* GetEditTextObject() const;
 121
 122     /** Returns the caption text of this note. */
 123     OUString     GetText() const;
 124     /** Changes the caption text of this note. All text formatting will be lost. */
 125     void                SetText( const ScAddress& rPos, const OUString& rText );
 126
 127     /** Returns an existing note caption object. returns null, if the note
 128         contains initial caption data needed to construct a caption object. */
 129     inline SdrCaptionObj* GetCaption() const { return maNoteData.mpCaption; }
 130     /** Returns the caption object of this note. Creates the caption object, if
 131         the note contains initial caption data instead of the caption. */
 132     SdrCaptionObj*      GetOrCreateCaption( const ScAddress& rPos ) const;
 133     /** Forgets the pointer to the note caption object. */
 134     void                ForgetCaption();
 135
 136     /** Shows or hides the note caption object. */
 137     void                ShowCaption( const ScAddress& rPos, bool bShow = true );
 138     /** Returns true, if the caption object is visible. */
 139     inline bool         IsCaptionShown() const { return maNoteData.mbShown; }
 140
 141     /** Shows or hides the caption temporarily (does not change internal visibility state). */
 142     void                ShowCaptionTemp( const ScAddress& rPos, bool bShow = true );
 143
 144     /** Updates caption position according to position of the passed cell. */
 145     void                UpdateCaptionPos( const ScAddress& rPos );
 146
 147 private:
 148                         ScPostIt( const ScPostIt& );
 149     ScPostIt&           operator=( const ScPostIt& );
 150
 151     /** Creates the caption object from initial caption data if existing. */
 152     void                CreateCaptionFromInitData( const ScAddress& rPos ) const;
 153     /** Creates a new caption object at the passed cell position, clones passed existing caption. */
 154     void                CreateCaption( const ScAddress& rPos, const SdrCaptionObj* pCaption = 0 );
 155     /** Removes the caption object from the drawing layer, if this note is its owner. */
 156     void                RemoveCaption();
 157
 158 private:
 159     ScDocument&         mrDoc;              /// Parent document containing the note.
 160     mutable ScNoteData  maNoteData;         /// Note data with pointer to caption object.
 161 };
 162
 163 // ============================================================================
 164
 165 class SC_DLLPUBLIC ScNoteUtil
 166 {
 167 public:
 168     /** Tries to update the position of note caption objects in the specified range. */
 169     static void         UpdateCaptionPositions( ScDocument& rDoc, const ScRange& rRange );
 170
 171     /** Creates and returns a caption object for a temporary caption. */
 172     static SdrCaptionObj* CreateTempCaption( ScDocument& rDoc, const ScAddress& rPos,
 173                             SdrPage& rDrawPage, const OUString& rUserText,
 174                             const Rectangle& rVisRect, bool bTailFront );
 175
 176     /** Creates a cell note using the passed caption drawing object.
 177
 178         This function is used in import filters to reuse the imported drawing
 179         object as note caption object.
 180
 181         @param rCaption  The drawing object for the cell note. This object MUST
 182             be inserted into the document at the correct drawing page already.
 183
 184         @return  Pointer to the new cell note object if insertion was
 185             successful (i.e. the passed cell position was valid), null
 186             otherwise. The Calc document is the owner of the note object. The
 187             passed item set and outliner object are deleted automatically if
 188             creation of the note was not successful.
 189      */
 190     static ScPostIt*    CreateNoteFromCaption(
 191                             ScDocument& rDoc, const ScAddress& rPos,
 192                             SdrCaptionObj& rCaption, bool bShown );
 193
 194     /** Creates a cell note based on the passed caption object data.
 195
 196         This function is used in import filters to use an existing imported
 197         item set and outliner object to create a note caption object. For
 198         performance reasons, it is possible to specify that the caption drawing
 199         object for the cell note is not created yet but the note caches the
 200         passed data needed to create the caption object on demand (see
 201         parameter bAlwaysCreateCaption).
 202
 203         @param pItemSet  Pointer to an item set on heap memory containing all
 204             formatting attributes of the caption object. This function takes
 205             ownership of the passed item set.
 206
 207         @param pOutlinerObj  Pointer to an outliner object on heap memory
 208             containing (formatted) text for the caption object. This function
 209             takes ownership of the passed outliner object.
 210
 211         @param rCaptionRect  The absolute position and size of the caption
 212             object. The rectangle may be empty, in this case the default
 213             position and size is used.
 214
 215         @param bAlwaysCreateCaption  If sal_True is passed, the caption drawing
 216             object will be created immediately. If sal_False is passed, the caption
 217             drawing object will not be created if the note is not visible
 218             (bShown = sal_False), but the cell note will cache the passed data.
 219             MUST be set to sal_False outside of import filter implementations!
 220
 221         @return  Pointer to the new cell note object if insertion was
 222             successful (i.e. the passed cell position was valid), null
 223             otherwise. The Calc document is the owner of the note object.
 224      */
 225     static ScPostIt*    CreateNoteFromObjectData(
 226                             ScDocument& rDoc, const ScAddress& rPos,
 227                             SfxItemSet* pItemSet, OutlinerParaObject* pOutlinerObj,
 228                             const Rectangle& rCaptionRect, bool bShown,
 229                             bool bAlwaysCreateCaption );
 230
 231     /** Creates a cell note based on the passed string and inserts it into the
 232         document.
 233
 234         @param rNoteText  The text used to create the note caption object. Must
 235             not be empty.
 236
 237         @param bAlwaysCreateCaption  If sal_True is passed, the caption drawing
 238             object will be created immediately. If sal_False is passed, the caption
 239             drawing object will not be created if the note is not visible
 240             (bShown = sal_False), but the cell note will cache the passed data.
 241             MUST be set to sal_False outside of import filter implementations!
 242
 243         @return  Pointer to the new cell note object if insertion was
 244             successful (i.e. the passed cell position was valid), null
 245             otherwise. The Calc document is the owner of the note object.
 246      */
 247     static ScPostIt*    CreateNoteFromString(
 248                             ScDocument& rDoc, const ScAddress& rPos,
 249                             const OUString& rNoteText, bool bShown,
 250                             bool bAlwaysCreateCaption );
 251 };
 252
 253 class SC_DLLPUBLIC ScNotes
 254 {
 255 private:
 256     typedef std::pair<SCCOL, SCROW> ScAddress2D;
 257     typedef std::map<ScAddress2D, ScPostIt*> ScNoteMap;
 258     ScNoteMap maNoteMap;
 259
 260     ScNotes(const ScNotes& rNotes);
 261     ScNotes operator=(const ScNotes& rNotes);
 262     ScDocument* mpDoc;
 263 public:
 264     ScNotes(ScDocument* pDoc);
 265     ~ScNotes();
 266
 267     typedef ScNoteMap::iterator iterator;
 268     typedef ScNoteMap::const_iterator const_iterator;
 269
 270     iterator begin();
 271     iterator end();
 272
 273     const_iterator begin() const;
 274     const_iterator end() const;
 275
 276     size_t size() const;
 277     bool empty() const;
 278
 279     ScPostIt* findByAddress(SCCOL nCol, SCROW nRow);
 280     const ScPostIt* findByAddress(SCCOL nCol, SCROW nRow) const;
 281
 282     ScPostIt* findByAddress(const ScAddress& rAddress);
 283     const ScPostIt* findByAddress(const ScAddress& rAddress) const;
 284     /**
 285      * takes ownership of the
 286      */
 287     bool insert( SCCOL nCol, SCROW nRow, ScPostIt* );
 288     bool insert( const ScAddress& rPos, ScPostIt* );
 289
 290     void erase(SCCOL, SCROW, bool bForgetCaption = false);
 291     void erase(const ScAddress& rPos);
 292
 293     /** Returns and forgets the cell note object at the passed cell address. */
 294     ScPostIt*       ReleaseNote( const ScAddress& rPos );
 295     ScPostIt*       ReleaseNote( SCCOL nCol, SCROW nRow );
 296     /** Returns the pointer to an existing or created cell note object at the passed cell address. */
 297     ScPostIt* GetOrCreateNote( const ScAddress& rPos );
 298
 299     void clear();
 300
 301     void clone(ScDocument* pDoc, SCCOL nCol1, SCROW nRow1, SCCOL nCol2, SCROW nRow2, bool bCloneNoteCaption, SCTAB nTab, ScNotes& rTarget);
 302     void CopyFromClip(const ScNotes& maNotes, ScDocument* pDoc, SCCOL nCol1, SCROW nRow1, SCCOL nCol2, SCROW nRow2, SCsCOL nDx, SCsROW nDy, SCTAB nTab, bool bCloneCaption);
 303
 304     void erase(SCCOL nCol1, SCROW nRow1, SCCOL nCol2, SCROW nRow2, bool bForgetCaption = false);
 305
 306     void CreateAllNoteCaptions(SCTAB nTab);
 307 };
 308
 309 // ============================================================================
 310
 311 #endif
 312
 313 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */