1 // Created on: 1999-04-07
2 // Created by: Denis PASCAL
3 // Copyright (c) 1999 Matra Datavision
4 // Copyright (c) 1999-2014 OPEN CASCADE SAS
6 // This file is part of Open CASCADE Technology software library.
8 // This library is free software; you can redistribute it and/or modify it under
9 // the terms of the GNU Lesser General Public License version 2.1 as published
10 // by the Free Software Foundation, with special exception defined in the file
11 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
12 // distribution for complete text of the license and disclaimer of any warranty.
14 // Alternatively, this file may be used under the terms of Open CASCADE
15 // commercial license or contractual agreement.
17 #ifndef _TDocStd_Document_HeaderFile
18 #define _TDocStd_Document_HeaderFile
20 #include <Standard.hxx>
21 #include <Standard_Type.hxx>
23 #include <TCollection_ExtendedString.hxx>
24 #include <Standard_Integer.hxx>
25 #include <TDF_Transaction.hxx>
26 #include <TDF_DeltaList.hxx>
27 #include <Standard_Boolean.hxx>
28 #include <CDM_Document.hxx>
29 #include <TDF_LabelMap.hxx>
30 #include <Standard_Address.hxx>
34 class TCollection_ExtendedString;
35 class TCollection_AsciiString;
37 class TDocStd_CompoundDelta;
40 class TDocStd_Document;
41 DEFINE_STANDARD_HANDLE(TDocStd_Document, CDM_Document)
43 //! The contents of a TDocStd_Application, a
44 //! document is a container for a data framework
45 //! composed of labels and attributes. As such,
46 //! TDocStd_Document is the entry point into the data framework.
47 //! To gain access to the data, you create a document as follows:
48 //! Handle(TDocStd_Document) MyDF = new TDocStd_Document
49 //! The document also allows you to manage:
50 //! - modifications, providing Undo and Redo functions.
51 //! - command transactions.
52 //! Warning: The only data saved is the framework (TDF_Data)
53 class TDocStd_Document : public CDM_Document
59 //! Will Abort any execution, clear fields
60 //! returns the document which contains <L>. raises an
61 //! exception if the document is not found.
62 Standard_EXPORT static Handle(TDocStd_Document) Get (const TDF_Label& L);
64 //! Constructs a document object defined by the
65 //! string astorageformat.
66 //! If a document is created outside of an application using this constructor, it must be
67 //! managed by a Handle. Otherwise memory problems could appear: call of TDocStd_Owner::GetDocument
68 //! creates a Handle(TDocStd_Document), so, releasing it will produce a crash.
69 Standard_EXPORT TDocStd_Document(const TCollection_ExtendedString& astorageformat);
71 //! the document is saved in a file.
72 Standard_EXPORT Standard_Boolean IsSaved() const;
74 //! returns True if document differs from the state of last saving.
75 //! this method have to be called only wroking in the transaction mode
76 Standard_Boolean IsChanged() const;
78 //! This method have to be called to show document that it has been saved
81 //! Say to document what it is not saved.
82 //! Use value, returned earlier by GetSavedTime().
83 void SetSavedTime (const Standard_Integer theTime);
85 //! Returns value of <mySavedTime> to be used later in SetSavedTime()
86 Standard_Integer GetSavedTime() const;
88 //! raise if <me> is not saved.
89 Standard_EXPORT TCollection_ExtendedString GetName() const;
91 //! returns the OS path of the file, in wich one <me> is
92 //! saved. Raise an exception if <me> is not saved.
93 Standard_EXPORT TCollection_ExtendedString GetPath() const;
95 Standard_EXPORT void SetData (const Handle(TDF_Data)& data);
97 Standard_EXPORT Handle(TDF_Data) GetData() const;
99 //! Returns the main label in this data framework.
100 //! By definition, this is the label with the entry 0:1.
101 Standard_EXPORT TDF_Label Main() const;
103 //! Returns True if the main label has no attributes
104 Standard_EXPORT Standard_Boolean IsEmpty() const;
106 //! Returns False if the document has been modified
107 //! but not recomputed.
108 Standard_EXPORT Standard_Boolean IsValid() const;
110 //! Notify the label as modified, the Document becomes UnValid.
111 //! returns True if <L> has been notified as modified.
112 Standard_EXPORT void SetModified (const TDF_Label& L);
114 //! Remove all modifications. After this call The document
115 //! becomesagain Valid.
116 Standard_EXPORT void PurgeModified();
118 //! Returns the labels which have been modified in
120 Standard_EXPORT const TDF_LabelMap& GetModified() const;
122 //! Launches a new command. This command may be undone.
123 Standard_EXPORT void NewCommand();
125 //! returns True if a Command transaction is open in the curret .
126 Standard_EXPORT Standard_Boolean HasOpenCommand() const;
128 //! Opens a new command transaction in this document.
129 //! You can use HasOpenCommand to see whether a command is already open.
131 //! Standard_DomainError if a command is already open in this document.
132 Standard_EXPORT void OpenCommand();
134 //! Commits documents transactions and fills the
135 //! transaction manager with documents that have
136 //! been changed during the transaction.
137 //! If no command transaction is open, nothing is done.
138 //! Returns True if a new delta has been added to myUndos.
139 Standard_EXPORT Standard_Boolean CommitCommand();
141 //! Abort the Command transaction. Does nothing If there is
142 //! no Command transaction open.
143 Standard_EXPORT void AbortCommand();
145 //! The current limit on the number of undos
146 Standard_EXPORT Standard_Integer GetUndoLimit() const;
148 //! Set the limit on the number of Undo Delta stored 0
149 //! will disable Undo on the document A negative value
150 //! means no limit. Note that by default Undo is disabled.
151 //! Enabling it will take effect with the next call to
152 //! NewCommand. Of course this limit is the same for Redo
153 Standard_EXPORT void SetUndoLimit (const Standard_Integer L);
155 //! Remove all stored Undos and Redos
156 Standard_EXPORT void ClearUndos();
158 //! Remove all stored Redos
159 Standard_EXPORT void ClearRedos();
161 //! Returns the number of undos stored in this
162 //! document. If this figure is greater than 0, the method Undo
164 Standard_EXPORT Standard_Integer GetAvailableUndos() const;
166 //! Will UNDO one step, returns False if no undo was
167 //! done (Undos == 0).
168 //! Otherwise, true is returned and one step in the
169 //! list of undoes is undone.
170 Standard_EXPORT Standard_Boolean Undo();
172 //! Returns the number of redos stored in this
173 //! document. If this figure is greater than 0, the method Redo
175 Standard_EXPORT Standard_Integer GetAvailableRedos() const;
177 //! Will REDO one step, returns False if no redo was
178 //! done (Redos == 0).
179 //! Otherwise, true is returned, and one step in the list of redoes is done again.
180 Standard_EXPORT Standard_Boolean Redo();
182 Standard_EXPORT const TDF_DeltaList& GetUndos() const;
184 Standard_EXPORT const TDF_DeltaList& GetRedos() const;
186 //! Removes the first undo in the list of document undos.
187 //! It is used in the application when the undo limit is exceed.
188 Standard_EXPORT void RemoveFirstUndo();
190 //! Initializes the procedure of delta compaction
191 //! Returns false if there is no delta to compact
192 //! Marks the last delta as a "from" delta
193 Standard_EXPORT Standard_Boolean InitDeltaCompaction();
195 //! Performs the procedure of delta compaction
196 //! Makes all deltas starting from "from" delta
197 //! till the last one to be one delta.
198 Standard_EXPORT Standard_Boolean PerformDeltaCompaction();
200 //! Set modifications on labels impacted by external
201 //! references to the entry. The document becomes invalid
202 //! and must be recomputed.
203 Standard_EXPORT void UpdateReferences (const TCollection_AsciiString& aDocEntry);
205 //! Recompute if the document was not valid and propagate
206 //! the reccorded modification.
207 Standard_EXPORT void Recompute();
209 //! This method Update will be called
210 //! to signal the end of the modified references list.
211 //! The document should be recomputed and
212 //! UpdateFromDocuments should be called. Update should
213 //! returns True in case of success, false otherwise. In
214 //! case of Failure, additional information can be given in
216 //! Update the document by propagation
217 //! ==================================
218 //! Update the document from internal stored
219 //! modifications. If you want to undoing this
220 //! operation, please call NewCommand before.
221 //! to change format (advanced programming)
223 Standard_EXPORT virtual void Update (const Handle(CDM_Document)& aToDocument, const Standard_Integer aReferenceIdentifier, const Standard_Address aModifContext) Standard_OVERRIDE;
225 Standard_EXPORT virtual TCollection_ExtendedString StorageFormat() const Standard_OVERRIDE;
227 //! Sets saving mode for empty labels. If Standard_True, empty labels will be saved.
228 void SetEmptyLabelsSavingMode (const Standard_Boolean isAllowed);
230 //! Returns saving mode for empty labels.
231 Standard_Boolean EmptyLabelsSavingMode() const;
233 //! methods for the nested transaction mode
234 Standard_EXPORT virtual void ChangeStorageFormat (const TCollection_ExtendedString& newStorageFormat);
236 //! Sets nested transaction mode if isAllowed == Standard_True
237 void SetNestedTransactionMode (const Standard_Boolean isAllowed = Standard_True);
239 //! Returns Standard_True if mode is set
240 Standard_Boolean IsNestedTransactionMode() const;
242 //! if theTransactionOnly is True changes is denied outside transactions
243 void SetModificationMode (const Standard_Boolean theTransactionOnly);
245 //! returns True if changes allowed only inside transactions
246 Standard_Boolean ModificationMode() const;
248 //! Prepares document for closing
249 Standard_EXPORT virtual void BeforeClose();
251 //! Dumps the content of me into the stream
252 Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
257 DEFINE_STANDARD_RTTIEXT(TDocStd_Document,CDM_Document)
262 //! Returns Standard_True done
263 Standard_EXPORT virtual Standard_Boolean CommitTransaction();
265 Standard_EXPORT virtual void AbortTransaction();
267 //! methods for protection of changes outside transactions
268 Standard_EXPORT virtual void OpenTransaction();
270 TCollection_ExtendedString myStorageFormat;
271 TDF_DeltaList myUndos;
272 TDF_DeltaList myRedos;
278 //! Appends delta to the first delta in the myUndoFILO
281 Standard_EXPORT static void AppendDeltaToTheFirst (const Handle(TDocStd_CompoundDelta)& theDelta1, const Handle(TDF_Delta)& theDelta2);
283 Handle(TDF_Data) myData;
284 Standard_Integer myUndoLimit;
285 TDF_Transaction myUndoTransaction;
286 Handle(TDF_Delta) myFromUndo;
287 Handle(TDF_Delta) myFromRedo;
288 Standard_Integer mySaveTime;
289 Standard_Boolean myIsNestedTransactionMode;
290 TDF_DeltaList myUndoFILO;
291 Standard_Boolean myOnlyTransactionModification;
292 Standard_Boolean mySaveEmptyLabels;
297 #include <TDocStd_Document.lxx>
303 #endif // _TDocStd_Document_HeaderFile