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 <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 /** Internal data for a cell annotation. */
  40 struct SC_DLLPUBLIC ScNoteData
  41 {
  42     typedef ::boost::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, bool bShown );
  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;
 100
 101     /** Returns the creation date of this note. */
 102     const OUString& GetDate() const;
 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;
 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     /** Changes the caption text of this note. All text formatting will be lost. */
 122     void                SetText( const ScAddress& rPos, const OUString& rText );
 123
 124     /** Returns an existing note caption object. returns null, if the note
 125         contains initial caption data needed to construct a caption object. */
 126     SdrCaptionObj* GetCaption() const;
 127     /** Returns the caption object of this note. Creates the caption object, if
 128         the note contains initial caption data instead of the caption. */
 129     SdrCaptionObj*      GetOrCreateCaption( const ScAddress& rPos ) const;
 130     /** Forgets the pointer to the note caption object. */
 131     void                ForgetCaption();
 132
 133     /** Shows or hides the note caption object. */
 134     void                ShowCaption( const ScAddress& rPos, bool bShow = true );
 135     /** Returns true, if the caption object is visible. */
 136     bool IsCaptionShown() const;
 137
 138     /** Shows or hides the caption temporarily (does not change internal visibility state). */
 139     void                ShowCaptionTemp( const ScAddress& rPos, bool bShow = true );
 140
 141     /** Updates caption position according to position of the passed cell. */
 142     void                UpdateCaptionPos( const ScAddress& rPos );
 143
 144 private:
 145                         ScPostIt( const ScPostIt& );
 146     ScPostIt&           operator=( const ScPostIt& );
 147
 148     /** Creates the caption object from initial caption data if existing. */
 149     void                CreateCaptionFromInitData( const ScAddress& rPos ) const;
 150     /** Creates a new caption object at the passed cell position, clones passed existing caption. */
 151     void                CreateCaption( const ScAddress& rPos, const SdrCaptionObj* pCaption = 0 );
 152     /** Removes the caption object from the drawing layer, if this note is its owner. */
 153     void                RemoveCaption();
 154
 155 private:
 156     ScDocument&         mrDoc;              /// Parent document containing the note.
 157     mutable ScNoteData  maNoteData;         /// Note data with pointer to caption object.
 158 };
 159
 160 class SC_DLLPUBLIC ScNoteUtil
 161 {
 162 public:
 163
 164     /** Creates and returns a caption object for a temporary caption. */
 165     static SdrCaptionObj* CreateTempCaption( ScDocument& rDoc, const ScAddress& rPos,
 166                             SdrPage& rDrawPage, const OUString& rUserText,
 167                             const Rectangle& rVisRect, bool bTailFront );
 168
 169     /** Creates a cell note using the passed caption drawing object.
 170
 171         This function is used in import filters to reuse the imported drawing
 172         object as note caption object.
 173
 174         @param rCaption  The drawing object for the cell note. This object MUST
 175             be inserted into the document at the correct drawing page already.
 176
 177         @return  Pointer to the new cell note object if insertion was
 178             successful (i.e. the passed cell position was valid), null
 179             otherwise. The Calc document is the owner of the note object. The
 180             passed item set and outliner object are deleted automatically if
 181             creation of the note was not successful.
 182      */
 183     static ScPostIt*    CreateNoteFromCaption(
 184                             ScDocument& rDoc, const ScAddress& rPos,
 185                             SdrCaptionObj& rCaption, bool bShown );
 186
 187     /** Creates a cell note based on the passed caption object data.
 188
 189         This function is used in import filters to use an existing imported
 190         item set and outliner object to create a note caption object. For
 191         performance reasons, it is possible to specify that the caption drawing
 192         object for the cell note is not created yet but the note caches the
 193         passed data needed to create the caption object on demand (see
 194         parameter bAlwaysCreateCaption).
 195
 196         @param pItemSet  Pointer to an item set on heap memory containing all
 197             formatting attributes of the caption object. This function takes
 198             ownership of the passed item set.
 199
 200         @param pOutlinerObj  Pointer to an outliner object on heap memory
 201             containing (formatted) text for the caption object. This function
 202             takes ownership of the passed outliner object.
 203
 204         @param rCaptionRect  The absolute position and size of the caption
 205             object. The rectangle may be empty, in this case the default
 206             position and size is used.
 207
 208         @param bAlwaysCreateCaption  If sal_True is passed, the caption drawing
 209             object will be created immediately. If sal_False is passed, the caption
 210             drawing object will not be created if the note is not visible
 211             (bShown = sal_False), but the cell note will cache the passed data.
 212             MUST be set to sal_False outside of import filter implementations!
 213
 214         @return  Pointer to the new cell note object if insertion was
 215             successful (i.e. the passed cell position was valid), null
 216             otherwise. The Calc document is the owner of the note object.
 217      */
 218     static ScPostIt*    CreateNoteFromObjectData(
 219                             ScDocument& rDoc, const ScAddress& rPos,
 220                             SfxItemSet* pItemSet, OutlinerParaObject* pOutlinerObj,
 221                             const Rectangle& rCaptionRect, bool bShown,
 222                             bool bAlwaysCreateCaption );
 223
 224     /** Creates a cell note based on the passed string and inserts it into the
 225         document.
 226
 227         @param rNoteText  The text used to create the note caption object. Must
 228             not be empty.
 229
 230         @param bAlwaysCreateCaption  If sal_True is passed, the caption drawing
 231             object will be created immediately. If sal_False is passed, the caption
 232             drawing object will not be created if the note is not visible
 233             (bShown = sal_False), but the cell note will cache the passed data.
 234             MUST be set to sal_False outside of import filter implementations!
 235
 236         @return  Pointer to the new cell note object if insertion was
 237             successful (i.e. the passed cell position was valid), null
 238             otherwise. The Calc document is the owner of the note object.
 239      */
 240     static ScPostIt*    CreateNoteFromString(
 241                             ScDocument& rDoc, const ScAddress& rPos,
 242                             const OUString& rNoteText, bool bShown,
 243                             bool bAlwaysCreateCaption );
 244
 245 };
 246
 247 namespace sc {
 248
 249 struct NoteEntry
 250 {
 251     ScAddress maPos;
 252     const ScPostIt* mpNote;
 253
 254     NoteEntry( const ScAddress& rPos, const ScPostIt* pNote );
 255 };
 256
 257 }
 258
 259 #endif
 260 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */