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 fields
 324
 325     ---Purpose: storage format
 326
 327     myStorageFormat   : ExtendedString from  TCollection is protected;
 328
 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;
 335
 336     myFromUndo        : Delta        from TDF;
 337     myFromRedo        : Delta        from TDF;
 338
 339     mySaveTime        : Integer      from Standard;
 340
 341     ---Purpose: data for the nested transactions
 342
 343     myIsNestedTransactionMode : Boolean   from Standard;
 344     myUndoFILO                : DeltaList from TDF;
 345
 346     ---Purpose: data for protection of changes outside transactions
 347
 348     myOnlyTransactionModification : Boolean from Standard;
 349
 350 end Document;
 351