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
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.
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.
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.
24 class Document from TDocStd inherits Document from CDM
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)
42 ExtendedString from TCollection,
43 AsciiString from TCollection,
48 CompoundDelta from TDocStd
52 Destroy (me : mutable) is redefined protected;
53 ---Purpose: Will Abort any execution, clear fields
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;
61 Create (astorageformat : ExtendedString from TCollection)
62 returns mutable Document from TDocStd;
63 ---Purpose: Constructs a document object defined by the
64 -- string astorageformat.
68 ---Purpose: the document is saved in a file.
69 returns Boolean from Standard;
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
77 SetSaved (me : mutable);
78 ---Purpose: This method have to be called to show document that it has been saved
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().
87 ---Purpose: Returns value of <mySavedTime> to be used later in SetSavedTime()
89 returns Integer from Standard;
92 ---Purpose: raise if <me> is not saved.
93 returns ExtendedString from TCollection;
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;
100 ---Category: Data Framework
103 SetData (me : mutable ; data : Data from TDF);
106 returns Data from TDF;
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;
114 ---Purpose: Returns True if the main label has no attributes
115 returns Boolean from Standard;
117 ---Category: Durty Flag and Modified labels
118 -- ==============================
120 IsValid(me) returns Boolean;
121 ---Purpose: Returns False if the document has been modified
122 -- but not recomputed.
124 SetModified (me : mutable; L : Label from TDF);
125 ---Purpose: Notify the label as modified, the Document becomes UnValid.
127 --IsModified (me; L : Label from TDF)
128 --returns Boolean from Standard;
129 ---Purpose: returns True if <L> has been notified as modified.
131 PurgeModified (me : mutable);
132 ---Purpose: Remove all modifications. After this call The document
133 -- becomesagain Valid.
136 ---Purpose: Returns the labels which have been modified in
138 ---C++: return const&
139 returns LabelMap from TDF;
141 ---Category: COMMAND Transaction and UNDO/REDO
142 -- =================================
144 NewCommand (me : mutable);
145 ---Purpose: Launches a new command. This command may be undone.
148 ---Purpose: returns True if a Command transaction is open in the curret .
149 returns Boolean from Standard;
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.
155 -- Standard_DomainError if a command is already open in this document.
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.
164 AbortCommand (me : mutable);
165 ---Purpose: Abort the Command transaction. Does nothing If there is
166 -- no Command transaction open.
168 GetUndoLimit(me) returns Integer;
169 ---Purpose: The current limit on the number of undos
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
178 ClearUndos(me : mutable);
179 ---Purpose: Remove all stored Undos and Redos
181 ClearRedos(me : mutable);
182 ---Purpose: Remove all stored Redos
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
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.
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
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.
206 ---C++: return const &
207 returns DeltaList from TDF;
210 ---C++: return const &
211 returns DeltaList from TDF;
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.
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;
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;
230 ---Category: External references
231 -- ===================
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.
238 Recompute (me : mutable);
239 ---Purpose: Recompute if the document was not valid and propagate
240 -- the reccorded modification.
242 ---Category: deferred methods CDM_Document
243 -- =============================
245 Update (me: mutable; aToDocument : Document from CDM;
246 aReferenceIdentifier : Integer from Standard;
247 aModifContext : Address from Standard)
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
261 --Update (me: mutable)
264 ---Purpose: Update the document by propagation
265 -- ==================================
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.
273 ---Purpose: to change format (advanced programming)
277 returns ExtendedString from TCollection
280 ChangeStorageFormat(me : mutable; newStorageFormat : ExtendedString from TCollection)
284 ---Purpose: methods for the nested transaction mode
286 SetNestedTransactionMode(me : mutable; isAllowed : Boolean = Standard_True);
287 ---Purpose: Sets nested transaction mode if isAllowed == Standard_True
289 IsNestedTransactionMode (me)
290 returns Boolean from Standard;
291 ---Purpose: Returns Standard_True if mode is set
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
300 ---Purpose: private methods
303 CommitTransaction (me : mutable) returns Boolean
304 is virtual protected;
305 ---Purpose: Returns Standard_True done
307 AbortTransaction (me : mutable)
308 is virtual protected;
310 OpenTransaction (me : mutable)
311 is virtual protected;
313 ---Purpose: methods for protection of changes outside transactions
315 SetModificationMode (me : mutable; theTransactionOnly : Boolean from Standard);
316 ---Purpose: if theTransactionOnly is True changes is denied outside transactions
319 ModificationMode (me) returns Boolean from Standard;
320 ---Purpose: returns True if changes allowed only inside transactions
325 ---Purpose: storage format
327 myStorageFormat : ExtendedString from TCollection is protected;
329 ---Purpose: data framework
330 myData : Data from TDF;
331 myUndoLimit : Integer from Standard;
332 myUndoTransaction : Transaction from TDF;
333 myUndos : DeltaList from TDF is protected;
334 myRedos : DeltaList from TDF is protected;
336 myFromUndo : Delta from TDF;
337 myFromRedo : Delta from TDF;
339 mySaveTime : Integer from Standard;
341 ---Purpose: data for the nested transactions
343 myIsNestedTransactionMode : Boolean from Standard;
344 myUndoFILO : DeltaList from TDF;
346 ---Purpose: data for protection of changes outside transactions
348 myOnlyTransactionModification : Boolean from Standard;