0024164: Optimization of OCAF document closing
[occt.git] / src / TDocStd / TDocStd_Document.cdl
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
21
22
23
24 class 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
39 uses 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
50 is
51    
52     -- Destroy (me : mutable) is redefined protected;
53     ---Purpose: Will Abort any execution, clear fields
54     ---C++: alias ~
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
322
323     BeforeClose(me : mutable) is virtual;
324     ---Purpose: Prepares document for closing
325
326 fields
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;
336     myUndos           : DeltaList    from TDF is protected;
337     myRedos           : DeltaList    from TDF is protected;
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     
353 end Document;
354