0024164: Optimization of OCAF document closing
[occt.git] / src / TDocStd / TDocStd_Document.cdl
CommitLineData
b311480e 1-- Created on: 1999-04-07
2-- Created by: Denis PASCAL
3-- Copyright (c) 1999 Matra Datavision
4-- Copyright (c) 1999-2012 OPEN CASCADE SAS
5--
6-- The content of this file is subject to the Open CASCADE Technology Public
7-- License Version 6.5 (the "License"). You may not use the content of this file
8-- except in compliance with the License. Please obtain a copy of the License
9-- at http://www.opencascade.org and read it completely before using this file.
10--
11-- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
12-- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
13--
14-- The Original Code and all software distributed under the License is
15-- distributed on an "AS IS" basis, without warranty of any kind, and the
16-- Initial Developer hereby disclaims all such warranties, including without
17-- limitation, any warranties of merchantability, fitness for a particular
18-- purpose or non-infringement. Please see the License for the specific terms
19-- and conditions governing the rights and limitations under the License.
20
7fd59977 21
22
23
24class Document from TDocStd inherits Document from CDM
25
26 ---Purpose: The contents of a TDocStd_Application, a
27 -- document is a container for a data framework
28 -- composed of labels and attributes. As such,
29 -- TDocStd_Document is the entry point into the data framework.
30 -- To gain access to the data, you create a document as follows:
31 -- Handle(TDocStd_Document) MyDF = new TDocStd_Document
32 -- The document also allows you to manage:
33 -- - modifications, providing Undo and Redo functions.
34 -- - command transactions.
35 -- Warning: The only data saved is the framework (TDF_Data)
36
37 ---Purpose:
38
39uses Data from TDF,
40 Label from TDF,
41 LabelMap from TDF,
42 ExtendedString from TCollection,
43 AsciiString from TCollection,
44 Context from TDocStd,
45 Delta from TDF,
46 DeltaList from TDF,
47 Transaction from TDF,
48 CompoundDelta from TDocStd
49
50is
51
1c9cffdb 52 -- Destroy (me : mutable) is redefined protected;
24de79c3 53 ---Purpose: Will Abort any execution, clear fields
54 ---C++: alias ~
7fd59977 55
56 Get (myclass; L : Label from TDF)
57 ---Purpose: returns the document which contains <L>. raises an
58 -- exception if the document is not found.
59 returns Document from TDocStd;
60
61 Create (astorageformat : ExtendedString from TCollection)
62 returns mutable Document from TDocStd;
63 ---Purpose: Constructs a document object defined by the
64 -- string astorageformat.
65
66
67 IsSaved (me)
68 ---Purpose: the document is saved in a file.
69 returns Boolean from Standard;
70
71 IsChanged (me)
72 returns Boolean from Standard;
73 ---Purpose: returns True if document differs from the state of last saving.
74 -- this method have to be called only wroking in the transaction mode
75 ---C++: inline
76
77 SetSaved (me : mutable);
78 ---Purpose: This method have to be called to show document that it has been saved
79 ---C++: inline
80
81 SetSavedTime (me : mutable; theTime : Integer from Standard);
82 ---Purpose: Say to document what it is not saved.
83 -- Use value, returned earlier by GetSavedTime().
84 ---C++: inline
85
86 GetSavedTime (me)
87 ---Purpose: Returns value of <mySavedTime> to be used later in SetSavedTime()
88 ---C++: inline
89 returns Integer from Standard;
90
91 GetName (me)
92 ---Purpose: raise if <me> is not saved.
93 returns ExtendedString from TCollection;
94
95 GetPath (me)
96 ---Purpose: returns the OS path of the file, in wich one <me> is
97 -- saved. Raise an exception if <me> is not saved.
98 returns ExtendedString from TCollection;
99
100 ---Category: Data Framework
101 -- ==============
102
103 SetData (me : mutable ; data : Data from TDF);
104
105 GetData (me)
106 returns Data from TDF;
107
108 Main (me)
109 ---Purpose: Returns the main label in this data framework.
110 -- By definition, this is the label with the entry 0:1.
111 returns Label from TDF;
112
113 IsEmpty(me)
114 ---Purpose: Returns True if the main label has no attributes
115 returns Boolean from Standard;
116
117 ---Category: Durty Flag and Modified labels
118 -- ==============================
119
120 IsValid(me) returns Boolean;
121 ---Purpose: Returns False if the document has been modified
122 -- but not recomputed.
123
124 SetModified (me : mutable; L : Label from TDF);
125 ---Purpose: Notify the label as modified, the Document becomes UnValid.
126
127 --IsModified (me; L : Label from TDF)
128 --returns Boolean from Standard;
129 ---Purpose: returns True if <L> has been notified as modified.
130
131 PurgeModified (me : mutable);
132 ---Purpose: Remove all modifications. After this call The document
133 -- becomesagain Valid.
134
135 GetModified (me)
136 ---Purpose: Returns the labels which have been modified in
137 -- this document.
138 ---C++: return const&
139 returns LabelMap from TDF;
140
141 ---Category: COMMAND Transaction and UNDO/REDO
142 -- =================================
143
144 NewCommand (me : mutable);
145 ---Purpose: Launches a new command. This command may be undone.
146
147 HasOpenCommand (me)
148 ---Purpose: returns True if a Command transaction is open in the curret .
149 returns Boolean from Standard;
150
151 OpenCommand (me : mutable);
152 ---Purpose: Opens a new command transaction in this document.
153 -- You can use HasOpenCommand to see whether a command is already open.
154 -- Exceptions
155 -- Standard_DomainError if a command is already open in this document.
156
157 CommitCommand (me : mutable) returns Boolean;
158 ---Purpose: Commits documents transactions and fills the
159 -- transaction manager with documents that have
160 -- been changed during the transaction.
161 -- If no command transaction is open, nothing is done.
162 -- Returns True if a new delta has been added to myUndos.
163
164 AbortCommand (me : mutable);
165 ---Purpose: Abort the Command transaction. Does nothing If there is
166 -- no Command transaction open.
167
168 GetUndoLimit(me) returns Integer;
169 ---Purpose: The current limit on the number of undos
170
171 SetUndoLimit(me : mutable; L : Integer);
172 ---Purpose: Set the limit on the number of Undo Delta stored 0
173 -- will disable Undo on the document A negative value
174 -- means no limit. Note that by default Undo is disabled.
175 -- Enabling it will take effect with the next call to
176 -- NewCommand. Of course this limit is the same for Redo
177
178 ClearUndos(me : mutable);
179 ---Purpose: Remove all stored Undos and Redos
180
181 ClearRedos(me : mutable);
182 ---Purpose: Remove all stored Redos
183
184 GetAvailableUndos (me) returns Integer;
185 ---Purpose: Returns the number of undos stored in this
186 -- document. If this figure is greater than 0, the method Undo
187 -- can be used.
188
189 Undo (me:mutable) returns Boolean;
190 ---Purpose: Will UNDO one step, returns False if no undo was
191 -- done (Undos == 0).
192 -- Otherwise, true is returned and one step in the
193 -- list of undoes is undone.
194
195 GetAvailableRedos (me) returns Integer;
196 ---Purpose: Returns the number of redos stored in this
197 -- document. If this figure is greater than 0, the method Redo
198 -- can be used.
199
200 Redo (me : mutable) returns Boolean;
201 ---Purpose: Will REDO one step, returns False if no redo was
202 -- done (Redos == 0).
203 -- Otherwise, true is returned, and one step in the list of redoes is done again.
204
205 GetUndos (me)
206 ---C++: return const &
207 returns DeltaList from TDF;
208
209 GetRedos (me)
210 ---C++: return const &
211 returns DeltaList from TDF;
212
213 RemoveFirstUndo (me : mutable);
214 ---Purpose: Removes the first undo in the list of document undos.
215 -- It is used in the application when the undo limit is exceed.
216
217
218 InitDeltaCompaction(me : mutable)
219 ---Purpose: Initializes the procedure of delta compaction
220 -- Returns false if there is no delta to compact
221 -- Marks the last delta as a "from" delta
222 returns Boolean from Standard;
223
224 PerformDeltaCompaction(me : mutable)
225 ---Purpose: Performs the procedure of delta compaction
226 -- Makes all deltas starting from "from" delta
227 -- till the last one to be one delta.
228 returns Boolean from Standard;
229
230 ---Category: External references
231 -- ===================
232
233 UpdateReferences (me : mutable; aDocEntry : AsciiString from TCollection);
234 ---Purpose: Set modifications on labels impacted by external
235 -- references to the entry. The document becomes invalid
236 -- and must be recomputed.
237
238 Recompute (me : mutable);
239 ---Purpose: Recompute if the document was not valid and propagate
240 -- the reccorded modification.
241
242 ---Category: deferred methods CDM_Document
243 -- =============================
244
245 Update (me: mutable; aToDocument : Document from CDM;
246 aReferenceIdentifier : Integer from Standard;
247 aModifContext : Address from Standard)
248 is redefined;
249
250 --Update(me:mutable; ErrorString: out ExtendedString from TCollection)
251 --returns Boolean from Standard
252 ---Purpose: This method Update will be called
253 -- to signal the end of the modified references list.
254 -- The document should be recomputed and
255 -- UpdateFromDocuments should be called. Update should
256 -- returns True in case of success, false otherwise. In
257 -- case of Failure, additional information can be given in
258 -- ErrorString.
259 --is redefined;
260
261 --Update (me: mutable)
262 --is redefined;
263
264 ---Purpose: Update the document by propagation
265 -- ==================================
266
267 --Propagate (me: mutable);
268 ---Purpose: Update the document from internal stored
269 -- modifications. If you want to undoing this
270 -- operation, please call NewCommand before.
271
272
273 ---Purpose: to change format (advanced programming)
274 -- ================
275
276 StorageFormat(me)
277 returns ExtendedString from TCollection
278 is virtual;
279
280 ChangeStorageFormat(me : mutable; newStorageFormat : ExtendedString from TCollection)
281 is virtual;
282
283
284 ---Purpose: methods for the nested transaction mode
285
286 SetNestedTransactionMode(me : mutable; isAllowed : Boolean = Standard_True);
287 ---Purpose: Sets nested transaction mode if isAllowed == Standard_True
288
289 IsNestedTransactionMode (me)
290 returns Boolean from Standard;
291 ---Purpose: Returns Standard_True if mode is set
292 ---C++: inline
293
294 AppendDeltaToTheFirst (myclass;
295 theDelta1 : CompoundDelta from TDocStd;
296 theDelta2 : Delta from TDF) is private;
297 ---Purpose: Appends delta to the first delta in the myUndoFILO
298
299
300 ---Purpose: private methods
301 -- ===============
302
303 CommitTransaction (me : mutable) returns Boolean
304 is virtual protected;
305 ---Purpose: Returns Standard_True done
306
307 AbortTransaction (me : mutable)
308 is virtual protected;
309
310 OpenTransaction (me : mutable)
311 is virtual protected;
312
313 ---Purpose: methods for protection of changes outside transactions
314
315 SetModificationMode (me : mutable; theTransactionOnly : Boolean from Standard);
316 ---Purpose: if theTransactionOnly is True changes is denied outside transactions
317 ---C++: inline
318
319 ModificationMode (me) returns Boolean from Standard;
320 ---Purpose: returns True if changes allowed only inside transactions
321 ---C++: inline
1c9cffdb 322
323 BeforeClose(me : mutable) is virtual;
324 ---Purpose: Prepares document for closing
325
7fd59977 326fields
327
328 ---Purpose: storage format
329
330 myStorageFormat : ExtendedString from TCollection is protected;
331
332 ---Purpose: data framework
333 myData : Data from TDF;
334 myUndoLimit : Integer from Standard;
335 myUndoTransaction : Transaction from TDF;
3086e085
A
336 myUndos : DeltaList from TDF is protected;
337 myRedos : DeltaList from TDF is protected;
7fd59977 338
339 myFromUndo : Delta from TDF;
340 myFromRedo : Delta from TDF;
341
342 mySaveTime : Integer from Standard;
343
344 ---Purpose: data for the nested transactions
345
346 myIsNestedTransactionMode : Boolean from Standard;
347 myUndoFILO : DeltaList from TDF;
348
349 ---Purpose: data for protection of changes outside transactions
350
351 myOnlyTransactionModification : Boolean from Standard;
352
353end Document;
354