[occt.git] / src / TDocStd / TDocStd_Document.cdl

-- Created on: 1999-04-07
-- Created by: Denis PASCAL
-- Copyright (c) 1999 Matra Datavision
-- Copyright (c) 1999-2012 OPEN CASCADE SAS
--
-- The content of this file is subject to the Open CASCADE Technology Public
-- License Version 6.5 (the "License"). You may not use the content of this file
-- except in compliance with the License. Please obtain a copy of the License
-- at http://www.opencascade.org and read it completely before using this file.
--
-- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
-- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
--
-- The Original Code and all software distributed under the License is
-- distributed on an "AS IS" basis, without warranty of any kind, and the
-- Initial Developer hereby disclaims all such warranties, including without
-- limitation, any warranties of merchantability, fitness for a particular
-- purpose or non-infringement. Please see the License for the specific terms
-- and conditions governing the rights and limitations under the License.


class Document from TDocStd inherits Document from CDM
	
    	---Purpose: The contents of a TDocStd_Application, a
    	-- document is a container for a data framework
    	-- composed of labels and attributes. As such,
    	-- TDocStd_Document is the entry point into the data framework.
    	-- To gain access to the data, you create a document as follows:
    	-- Handle(TDocStd_Document) MyDF = new TDocStd_Document
    	-- The document also allows you to manage:
    	-- -   modifications, providing Undo and Redo functions.
    	-- -   command transactions.          
    	--  Warning: The only data saved is the framework (TDF_Data)

	---Purpose: 

uses Data           from TDF,
     Label          from TDF,
     LabelMap       from TDF,
     ExtendedString from TCollection,
     AsciiString    from TCollection,
     Context        from TDocStd,
     Delta          from TDF,
     DeltaList      from TDF,
     Transaction    from TDF,
     CompoundDelta  from TDocStd

is
   
    -- Destroy (me : mutable) is redefined protected;
    ---Purpose: Will Abort any execution, clear fields
    ---C++: alias ~

    Get (myclass; L : Label from TDF)
    	---Purpose: returns the    document which contains <L>.  raises  an
    	--          exception if the document is not found. 
    returns Document from TDocStd;

    Create (astorageformat : ExtendedString from TCollection)
    returns mutable Document from TDocStd;
    	---Purpose: Constructs a document object defined by the
    	-- string astorageformat.
             
    
    IsSaved (me)
    	---Purpose: the document is saved in a file.
    returns Boolean from Standard;    

    IsChanged (me)
    returns Boolean from Standard;
    	---Purpose: returns True if document differs from the state of last saving.
    	--          this method have to be called only wroking in the transaction mode
    	---C++: inline
    
    SetSaved (me : mutable);
    	---Purpose: This method have to be called to show document that it has been saved
    	---C++: inline
    
    SetSavedTime (me : mutable; theTime : Integer from Standard);
    ---Purpose: Say to document what it is not saved.
    --          Use value, returned earlier by GetSavedTime().
    ---C++: inline
    
    GetSavedTime (me)
    ---Purpose: Returns value of <mySavedTime> to be used later in SetSavedTime()
    ---C++: inline
    returns Integer from Standard;      
    
    GetName (me)
    ---Purpose: raise if <me> is not saved.
    returns ExtendedString from TCollection;      

    GetPath (me)
    ---Purpose: returns the OS  path of the  file, in wich one <me> is
    --          saved. Raise an exception if <me> is not saved.
    returns ExtendedString from TCollection;   

    ---Category: Data Framework
    --           ==============

    SetData (me : mutable ; data : Data from TDF);

    GetData (me)
    returns Data from TDF;
      
    Main (me)
    	---Purpose: Returns the main label in this data framework.
    	-- By definition, this is the label with the entry 0:1.
    returns Label from TDF;
    
    IsEmpty(me)
    ---Purpose: Returns True if the main label has no attributes
    returns Boolean from Standard;
    
    ---Category: Durty Flag and Modified labels
    --           ==============================

    IsValid(me) returns Boolean;
    	---Purpose:  Returns False if the  document has been modified
    	-- but not recomputed.

    SetModified (me : mutable; L : Label from TDF);
    ---Purpose: Notify the label as modified, the Document becomes UnValid.    

    --IsModified (me; L : Label from TDF)
    --returns Boolean from Standard;
    ---Purpose: returns True if <L> has been notified as modified.
    
    PurgeModified (me : mutable);
    ---Purpose: Remove all modifications. After this call The document
    --          becomesagain Valid.
    
    GetModified (me)
    	---Purpose: Returns the labels which have been modified in
    	-- this document.
    ---C++: return const&
    returns LabelMap from TDF;
        
    ---Category: COMMAND Transaction and UNDO/REDO
    --           =================================

    NewCommand (me : mutable);
    ---Purpose: Launches a new command. This command may be undone.

    HasOpenCommand  (me)
    ---Purpose: returns True if a Command transaction is open in the curret .
    returns Boolean from Standard;

    OpenCommand (me : mutable);
    	---Purpose: Opens a new command transaction in this document.
    	-- You can use HasOpenCommand to see whether a command is already open.
    	-- Exceptions
    	-- Standard_DomainError if a command is already open in this document.

    CommitCommand (me : mutable) returns Boolean;
    	---Purpose: Commits documents transactions and fills the
    	-- transaction manager with documents that have
    	-- been changed during the transaction.
    	-- If no command transaction is open, nothing is done.
    	-- Returns True if a new delta has been added to myUndos.
    
    AbortCommand (me : mutable);   
    	---Purpose: Abort the  Command  transaction. Does nothing If there is
    	--          no Command transaction open.

    GetUndoLimit(me) returns Integer;
    	---Purpose: The current limit on the number of undos
    
    SetUndoLimit(me : mutable; L : Integer);
    	---Purpose: Set the  limit on  the number of  Undo Delta  stored 0
    	--          will disable  Undo  on the  document A negative  value
    	--          means no limit. Note that by default Undo is disabled.
    	--          Enabling  it will  take effect with  the next  call to
    	--          NewCommand. Of course this limit is the same for Redo

    ClearUndos(me : mutable);
	---Purpose: Remove all stored Undos and Redos
    
    ClearRedos(me : mutable);
	---Purpose: Remove all stored Redos

    GetAvailableUndos (me) returns Integer;
	---Purpose: Returns the number of undos stored in this
    	-- document. If this figure is greater than 0, the method Undo
    	-- can be used.

    Undo (me:mutable) returns Boolean;
	---Purpose: Will UNDO  one step, returns  False if no undo was
	--          done (Undos == 0).
	-- Otherwise, true is returned and one step in the
    	-- list of undoes is undone.
    
    GetAvailableRedos (me) returns Integer;
	---Purpose: Returns the number of redos stored in this
    	-- document. If this figure is greater than 0, the method Redo
    	--  can be used.
    
    Redo (me : mutable) returns Boolean;
	---Purpose: Will REDO  one step, returns  False if no redo was
	--          done (Redos == 0). 
    	-- Otherwise, true is returned, and one step in the list of redoes is done again.
	
    GetUndos (me)
    ---C++: return const &
    returns DeltaList from TDF;
    
    GetRedos (me) 
    ---C++: return const &
    returns DeltaList from TDF;

    RemoveFirstUndo (me : mutable);
    ---Purpose: Removes the first undo in the list of document undos.
    --          It is used in the application when the undo limit is exceed.


    InitDeltaCompaction(me : mutable)
    ---Purpose: Initializes the procedure of delta compaction
    --          Returns false if there is no delta to compact    
    --          Marks the last delta as a "from" delta
    returns Boolean from Standard;

    PerformDeltaCompaction(me : mutable)
    ---Purpose: Performs the procedure of delta compaction
    --          Makes all deltas starting from "from" delta
    --          till the last one to be one delta. 
    returns Boolean from Standard;

    ---Category: External references
    --           ===================

    UpdateReferences (me : mutable; aDocEntry : AsciiString from TCollection);
    ---Purpose: Set   modifications on  labels  impacted  by  external
    --          references to the entry.  The document becomes invalid
    --          and must be recomputed.

    Recompute (me : mutable);
    ---Purpose: Recompute if the document was  not valid and propagate
    --          the reccorded modification.

    ---Category: deferred methods CDM_Document 
    --           =============================

    Update (me: mutable; aToDocument          : Document from CDM;
    	    	    	 aReferenceIdentifier : Integer from Standard;
			 aModifContext        : Address from Standard)
    is redefined;
    
    --Update(me:mutable; ErrorString: out ExtendedString from TCollection)
    --returns Boolean from Standard
    ---Purpose: This method Update   will be called
    --          to signal the end   of the modified references list.
    --          The    document     should    be  recomputed     and
    --          UpdateFromDocuments  should be called.  Update should
    --          returns True in case  of success, false otherwise.  In
    --          case of Failure, additional information can be given in
    --          ErrorString.
    --is redefined;
    
    --Update (me: mutable)
    --is redefined;

    ---Purpose: Update the document by propagation
    --          ==================================

    --Propagate (me: mutable);
    ---Purpose:   Update   the    document    from   internal   stored
    --            modifications.   If   you   want  to   undoing  this
    --           operation, please call NewCommand before.
    

    ---Purpose: to change format (advanced programming)
    --          ================

    StorageFormat(me) 
    returns ExtendedString from  TCollection
    is virtual;

    ChangeStorageFormat(me : mutable; newStorageFormat : ExtendedString from TCollection)
    is virtual;


    ---Purpose: methods for the nested transaction mode

    SetNestedTransactionMode(me : mutable; isAllowed : Boolean = Standard_True);
    ---Purpose: Sets nested transaction mode if isAllowed == Standard_True

    IsNestedTransactionMode (me)
    returns Boolean from Standard;
    ---Purpose: Returns Standard_True if mode is set
    ---C++: inline

    AppendDeltaToTheFirst (myclass;
    	    	    	   theDelta1 : CompoundDelta from TDocStd;
    	    	    	   theDelta2 : Delta         from TDF) is private;
    ---Purpose: Appends delta to the first delta in the myUndoFILO


    ---Purpose: private methods
    --          ===============

    CommitTransaction (me : mutable) returns Boolean
        is virtual protected;
    ---Purpose: Returns Standard_True done
    
    AbortTransaction (me : mutable)
        is virtual protected;

    OpenTransaction (me : mutable)
        is virtual protected;

    ---Purpose: methods for protection of changes outside transactions

    SetModificationMode (me : mutable; theTransactionOnly : Boolean from Standard);
    ---Purpose: if theTransactionOnly is True changes is denied outside transactions
    ---C++: inline
    
    ModificationMode (me) returns Boolean from Standard;
    ---Purpose: returns True if changes allowed only inside transactions
    ---C++: inline

    BeforeClose(me : mutable) is virtual;
    ---Purpose: Prepares document for closing

fields

    ---Purpose: storage format 

    myStorageFormat   : ExtendedString from  TCollection is protected;

    ---Purpose: data framework
    myData            : Data         from TDF;    
    myUndoLimit       : Integer      from Standard;
    myUndoTransaction : Transaction  from TDF;
    myUndos           : DeltaList    from TDF is protected;
    myRedos           : DeltaList    from TDF is protected;

    myFromUndo        : Delta        from TDF;
    myFromRedo        : Delta        from TDF;

    mySaveTime        : Integer      from Standard;

    ---Purpose: data for the nested transactions

    myIsNestedTransactionMode : Boolean   from Standard;
    myUndoFILO                : DeltaList from TDF;
    
    ---Purpose: data for protection of changes outside transactions

    myOnlyTransactionModification : Boolean from Standard;
    
end Document;
Commit	Line	Data
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
	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
1c9cffdb	52	-- Destroy (me : mutable) is redefined protected;
24de79c3	53	---Purpose: Will Abort any execution, clear fields
24de79c3	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	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;
3086e085 A	336	myUndos : DeltaList from TDF is protected;
3086e085 A	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
	353	end Document;
	354