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