OpenCascade.js
API ReferenceApplicationFrameworkTKLCAF

TDocStd

OCCT package TDocStd: TDocStd, TDocStd_Application, TDocStd_ApplicationDelta, TDocStd_CompoundDelta, and 11 more bound classes.

TDocStd

This package define CAF main classes.

  • The standard application root class
  • The standard document which contains data
  • The external reference mechanism between documents
  • Attributes for Document management Standard documents offer you a ready-to-use document containing a TDF-based data structure.
    The documents themselves are contained in a class inheriting from TDocStd_Application which manages creation, storage and retrieval of documents.
    You can implement undo and redo in your document, and refer from the data framework of one document to that of another one. This is done by means of external link attributes, which store the path and the entry of external links. To sum up, standard documents alone provide access to the data framework. They also allow you to:
  • Update external links
  • Manage the saving and opening of data
  • Manage undo/redo functionality. Note For information on the relations between this component of OCAF and the others, refer to the OCAF User's Guide.

Constructors(1)

Static methods(1)

  • specific GUID of this package
    Appends to <anIDList> the list of the attributes IDs of this package. CAUTION: <anIDList> is NOT cleared before use.

    Parameters (1)
    • anIDList
      Mutated in place; read the updated value from this argument after the call.

TDocStd_Application

The abstract root class for all application classes. They are in charge of:

  • Creating documents
  • Storing documents and retrieving them
  • Initializing document views. To create a useful OCAF-based application, you derive a class from Application and implement the methods below. You will have to redefine the deferred (virtual) methods Formats, InitDocument, and Resources, and override others. The application is a container for a document, which in its turn is the container of the data framework made up of labels and attributes. Besides furnishing a container for documents, TDocStd_Application provides the following services for them:
  • Creation of new documents
  • Activation of documents in sessions of an application
  • Storage and retrieval of documents
  • Initialization of document views. Note: If a client needs detailed information concerning the events during the Open/Store operation, a MessageDriver based on Message_PrinterOStream may be used. In case of need client can implement his own version inheriting from Message_Printer class and add it to the Messenger. Also the trace level of messages can be tuned by setting trace level (SetTraceLevel (Gravity )) for the used Printer. By default, trace level is Message_Info, so that all messages are output.

Constructors(1)

Static methods(2)

Instance methods(25)

  • Returns resource manager defining supported persistent formats.
    Default implementation loads resource file with name ResourcesName(), unless field myResources is already initialized (either by previous call or in any other way).
    The resource manager should define:

    • Format name for each file extension supported:[Extension].FileFormat: [Format]
    • For each format supported (as returned by Formats()), its extension, description string, and (when applicable) GUIDs of storage and retrieval plugins:[Format].Description: [Description][Format].FileExtension: [Extension][Format].RetrievalPlugin: [GUID] (optional)[Format].StoragePlugin: [GUID] (optional)
  • ResourcesName(): string

    Returns the name of the file containing the resources of this application, for support of legacy method of loading formats data from resource files.
    Method DefineFormat() can be used to define all necessary parameters explicitly without actually using resource files.
    In a resource file, the application associates the schema name of the document with the storage and retrieval plug-ins that are to be loaded for each document.
    On retrieval, the application reads the schema name in the heading of the CSF file and loads the plug-in indicated in the resource file. This plug-in instantiates the actual driver for transient-persistent conversion.
    Your application can bring this process into play by defining a class which inherits CDF_Application and redefines the function which returns the appropriate resources file. At this point, the function Retrieve and the class CDF_Store can be called. This allows you to deal with storage and retrieval of - as well as copying and pasting - documents. To implement a class like this, several virtual functions should be redefined.
    In particular, you must redefine the abstract function Resources inherited from the superclass CDM_Application.
    Default implementation returns empty string.

  • Sets up resources and registers read and storage drivers for the specified format.

    Parameters (5)
    • theFormat
      • unique name for the format, used to identify it.
    • theDescription
      • textual description of the format.
    • theExtension
      • extension of the files in that format. The same extension can be used by several formats.
    • theReader
      • instance of the read driver for the format. Null value is allowed (no possibility to read).
    • theWriter
      • instance of the write driver for the format. Null value is allowed (no possibility to write).
  • Returns the sequence of reading formats supported by the application.

    Parameters (1)
    • theFormats
      • sequence of reading formats. Output parameter. Mutated in place; read the updated value from this argument after the call.
  • Returns the sequence of writing formats supported by the application.

    Parameters (1)
    • theFormats
      • sequence of writing formats. Output parameter. Mutated in place; read the updated value from this argument after the call.
  • NbDocuments(): number

    returns the number of documents handled by the current applicative session.

  • Returns the document at the given 1-based index. The index is any integer between 1 and NbDocuments().

    Parameters (1)
    • index
      1-based document index
    Returns

    handle to the document

  • Returns the document at the given 1-based index. The index is any integer between 1 and NbDocuments().

    Parameters (1)
    • index
      1-based document index
    Returns

    handle to the document

  • GetDocument_2(index: number): { aDoc: TDocStd_Document; [Symbol.dispose](): void }
    Deprecated
    Parameters (1)
    • index
    Returns

    A result object with fields:

    • aDoc: owned by the returned envelope.
      Dispose the returned envelope to release owned Handle fields.
  • NewDocument(theFormat: TCollection_ExtendedString): { theDoc: CDM_Document; [Symbol.dispose](): void }

    Constructs the empty new document aDoc. This document will have the format format. If InitDocument is redefined for a specific application, the new document is handled by the applicative session.

    Parameters (1)
    • theFormat
    Returns

    A result object with fields:

    • theDoc: owned by the returned envelope.
      Dispose the returned envelope to release owned Handle fields.
  • NewDocument(format: TCollection_ExtendedString): { theDoc: TDocStd_Document; [Symbol.dispose](): void }

    A non-virtual method taking a TDocStd_Documment object as an input. Internally it calls a virtual method NewDocument() with CDM_Document object.

    Parameters (1)
    • format
    Returns

    A result object with fields:

    • theDoc: owned by the returned envelope.
      Dispose the returned envelope to release owned Handle fields.
  • InitDocument(theDoc: CDM_Document): void

    Initialize the document aDoc for the applicative session. This virtual function is called by NewDocument and is to be redefined for each specific application.
    Modified flag (different of disk version)
    to open/save a document

    Parameters (1)
    • theDoc
  • Close(aDoc: TDocStd_Document): void

    Close the given document. the document is not any more handled by the applicative session.

    Parameters (1)
    • aDoc
  • Close(aDocument: CDM_Document): void

    Close the given document. the document is not any more handled by the applicative session.

    Parameters (1)
    • aDocument
  • Returns an index for the document found in the path path in this applicative session. If the returned value is 0, the document is not present in the applicative session. This method can be used for the interactive part of an application. For instance, on a call to Open, the document to be opened may already be in memory. IsInSession checks to see if this is the case.
    Open can be made to depend on the value of the index returned: if IsInSession returns 0, the document is opened; if it returns another value, a message is displayed asking the user if he wants to override the version of the document in memory. Example: int insession = A->IsInSession(aDoc); if (insession > 0) { std::cout << "document " << insession << " is already in session" << std::endl; return 0; }.

    Parameters (1)
    • path
  • Open(thePath: TCollection_ExtendedString, theRange: Message_ProgressRange): { returnValue: PCDM_ReaderStatus; theDoc: TDocStd_Document; [Symbol.dispose](): void }

    Retrieves the document from specified file. In order not to override a version of the document which is already in memory, this method can be made to depend on the value returned by IsInSession.

    Parameters (2)
    • thePath
      file path to open
    • theRange
      optional progress indicator
    Returns

    A result object with fields:

    • returnValue: reading status
    • theDoc: result document, owned by the returned envelope.
      Dispose the returned envelope to release owned Handle fields.
  • Open(aDocument: CDM_Document): void

    Retrieves the document from specified file. In order not to override a version of the document which is already in memory, this method can be made to depend on the value returned by IsInSession.

    Parameters (1)
    • aDocument
    Returns

    reading status

  • Save the active document in the file <name> in the path <path>. overwrites the file if it already exists.

    Parameters (3)
    • theDoc
    • path
    • theRange
  • Save the active document in the file <name> in the path <path>. overwrite the file if it already exists.

    Parameters (4)
    • theDoc
    • path
    • theStatusMessage
      Mutated in place; read the updated value from this argument after the call.
    • theRange
  • Save aDoc active document. Exceptions: Standard_NotImplemented if the document was not retrieved in the applicative session by using Open.

    Parameters (2)
    • theDoc
    • theRange
  • Save the document overwriting the previous file.

    Parameters (3)
    • theDoc
    • theStatusMessage
      Mutated in place; read the updated value from this argument after the call.
    • theRange
  • Notification that is fired at each OpenTransaction event.

    Parameters (1)
    • theDoc
  • Notification that is fired at each CommitTransaction event.

    Parameters (1)
    • theDoc
  • Notification that is fired at each AbortTransaction event.

    Parameters (1)
    • theDoc

TDocStd_Document

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: occ::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)

Constructors(1)

  • Constructs a document object defined by the string astorageformat. If a document is created outside of an application using this constructor, it must be managed by a Handle. Otherwise memory problems could appear: call of TDocStd_Owner::GetDocument creates a occ::handle<TDocStd_Document>, so, releasing it will produce a crash.

    Parameters (1)
    • astorageformat

Static methods(4)

Instance methods(47)

  • IsSaved(): boolean

    the document is saved in a file.

  • IsChanged(): boolean

    returns True if document differs from the state of last saving. this method have to be called only working in the transaction mode

  • SetSaved(): void

    This method have to be called to show document that it has been saved.

  • SetSavedTime(theTime: number): void

    Say to document what it is not saved. Use value, returned earlier by GetSavedTime().

    Parameters (1)
    • theTime
  • GetSavedTime(): number

    Returns value of <mySavedTime> to be used later in SetSavedTime().

  • raise if <me> is not saved.

  • returns the OS path of the file, in which one <me> is saved. Raise an exception if <me> is not saved.

  • SetData(data: TDF_Data): void
    Parameters (1)
    • data
  • Returns the main label in this data framework. By definition, this is the label with the entry 0:1.

  • IsEmpty(): boolean

    Returns True if the main label has no attributes.

  • IsValid(): boolean

    Returns False if the document has been modified but not recomputed.

  • Notify the label as modified, the Document becomes UnValid. returns True if <L> has been notified as modified.

    Parameters (1)
    • L
  • Remove all modifications. After this call The document becomesagain Valid.

  • Returns the labels which have been modified in this document.

  • NewCommand(): void

    Launches a new command. This command may be undone.

  • HasOpenCommand(): boolean

    returns True if a Command transaction is open in the current .

  • OpenCommand(): void

    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(): boolean

    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(): void

    Abort the Command transaction. Does nothing If there is no Command transaction open.

  • GetUndoLimit(): number

    The current limit on the number of undos.

  • SetUndoLimit(L: number): void

    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.

    Parameters (1)
    • L
  • ClearUndos(): void

    Remove all stored Undos and Redos.

  • ClearRedos(): void

    Remove all stored Redos.

  • Returns the number of undos stored in this document. If this figure is greater than 0, the method Undo can be used.

  • Undo(): boolean

    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.

  • Returns the number of redos stored in this document. If this figure is greater than 0, the method Redo can be used.

  • Redo(): boolean

    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.

  • Removes the first undo in the list of document undos. It is used in the application when the undo limit is exceed.

  • Initializes the procedure of delta compaction Returns false if there is no delta to compact Marks the last delta as a "from" delta.

  • Performs the procedure of delta compaction Makes all deltas starting from "from" delta till the last one to be one delta.

  • Set modifications on labels impacted by external references to the entry. The document becomes invalid and must be recomputed.

    Parameters (1)
    • aDocEntry
  • Recompute(): void

    Recompute if the document was not valid and propagate the recorded modification.

  • The Storage Format is the key which is used to determine in the application resources the storage driver plugin, the file extension and other data used to store the document.

  • SetEmptyLabelsSavingMode(isAllowed: boolean): void

    Sets saving mode for empty labels. If true, empty labels will be saved.

    Parameters (1)
    • isAllowed
  • Returns saving mode for empty labels.

  • methods for the nested transaction mode

    Parameters (1)
    • newStorageFormat
  • SetNestedTransactionMode(isAllowed?: boolean): void

    Sets nested transaction mode if isAllowed == true.

    Parameters (1)
    • isAllowed
  • Returns true if mode is set.

  • SetModificationMode(theTransactionOnly: boolean): void

    if theTransactionOnly is True changes is denied outside transactions

    Parameters (1)
    • theTransactionOnly
  • ModificationMode(): boolean

    returns True if changes allowed only inside transactions

  • BeforeClose(): void

    Prepares document for closing.

  • Returns version of the format to be used to store the document.

  • Sets version of the format to be used to store the document.

    Parameters (1)
    • theVersion

TDocStd_FormatVersion

Properties(12)

TDocStd_Modified

Transient attribute which register modified labels. This attribute is attached to root label.

Constructors(1)

Static methods(9)

Instance methods(10)

  • IsEmpty(): boolean
  • returns modified label map

  • Clear(): void
  • AddLabel(L: TDF_Label): boolean

    add <L> as modified

    Parameters (1)
    • L
  • RemoveLabel(L: TDF_Label): boolean

    remove <L> as modified

    Parameters (1)
    • L
  • Returns the ID of the attribute.

  • Restore(anAttribute: TDF_Attribute): void

    Restores the backuped contents from <anAttribute> into this one. It is used when aborting a transaction.

    Parameters (1)
    • anAttribute
  • Returns an new empty attribute from the good end type. It is used by the copy algorithm.

  • Paste(intoAttribute: TDF_Attribute, aRelocationTable: TDF_RelocationTable): void

    This method is different from the "Copy" one, because it is used when copying an attribute from a source structure into a target structure. This method may paste the contents of <me> into <intoAttribute>.
    The given pasted attribute can be full or empty of its contents. But don't make a NEW! Just set the contents!
    It is possible to use <aRelocationTable> to get/set the relocation value of a source attribute.

    Parameters (2)
    • intoAttribute
    • aRelocationTable

TDocStd_MultiTransactionManager

Class for synchronization of transactions within multiple documents. Each transaction of this class involvess one transaction in each modified document.
The documents to be synchronized should be added explicitly to the manager; then its interface is used to ensure that all transactions (Open/Commit, Undo/Redo) are performed synchronously in all managed documents.
The current implementation does not support nested transactions on multitransaction manager level. It only sets the flag enabling or disabling nested transactions in all its documents, so that a nested transaction can be opened for each particular document with TDocStd_Document class interface.
NOTE: When you invoke CommitTransaction of multi transaction manager, all nested transaction of its documents will be closed (committed).

Constructors(1)

Static methods(2)

Instance methods(22)

  • SetUndoLimit(theLimit: number): void

    Sets undo limit for the manager and all documents.

    Parameters (1)
    • theLimit
  • GetUndoLimit(): number

    Returns undo limit for the manager.

  • Undo(): void

    Undoes the current transaction of the manager. It calls the Undo () method of the document being on top of the manager list of undos (list.First()) and moves the list item to the top of the list of manager redos (list.Prepend(item)).

  • Redo(): void

    Redoes the current transaction of the application. It calls the Redo () method of the document being on top of the manager list of redos (list.First()) and moves the list item to the top of the list of manager undos (list.Prepend(item)).

  • Returns available manager undos.

  • Returns available manager redos.

  • OpenCommand(): void

    Opens transaction in each document and sets the flag that transaction is opened. If there are already opened transactions in the documents, these transactions will be aborted before opening new ones.

  • AbortCommand(): void

    Unsets the flag of started manager transaction and aborts transaction in each document.

  • CommitCommand(): boolean

    Commits transaction in all documents and fills the transaction manager with the documents that have been changed during the transaction. Returns True if new data has been added to myUndos. NOTE: All nested transactions in the documents will be committed.

  • Makes the same steps as the previous function but defines the name for transaction. Returns True if new data has been added to myUndos.

    Parameters (1)
    • theName
  • HasOpenCommand(): boolean

    Returns true if a transaction is opened.

  • Removes undo information from the list of undos of the manager and all documents which have been modified during the transaction.

  • Adds the document to the transaction manager and checks if it has been already added.

    Parameters (1)
    • theDoc
  • Removes the document from the transaction manager.

    Parameters (1)
    • theDoc
  • Returns the added documents to the transaction manager.

  • SetNestedTransactionMode(isAllowed?: boolean): void

    Sets nested transaction mode if isAllowed == true NOTE: field myIsNestedTransactionMode exists only for synchronization between several documents and has no effect on transactions of multitransaction manager.

    Parameters (1)
    • isAllowed
  • Returns true if NestedTransaction mode is set. Methods for protection of changes outside transactions.

  • SetModificationMode(theTransactionOnly: boolean): void

    If theTransactionOnly is True, denies all changes outside transactions.

    Parameters (1)
    • theTransactionOnly
  • ModificationMode(): boolean

    Returns True if changes are allowed only inside transactions.

  • ClearUndos(): void

    Clears undos in the manager and in documents.

  • ClearRedos(): void

    Clears redos in the manager and in documents.

TDocStd_Owner

This attribute located at the root label of the framework contains a back reference to the owner TDocStd_Document, providing access to the document from any label. private class Owner;.

Constructors(1)

Static methods(5)

Instance methods(7)

  • SetDocument(document: TDocStd_Document): void
    Parameters (1)
    • document
  • Returns the ID of the attribute.

  • Restore(anAttribute: TDF_Attribute): void

    Restores the backuped contents from <anAttribute> into this one. It is used when aborting a transaction.

    Parameters (1)
    • anAttribute
  • Returns an new empty attribute from the good end type. It is used by the copy algorithm.

  • Paste(intoAttribute: TDF_Attribute, aRelocationTable: TDF_RelocationTable): void

    This method is different from the "Copy" one, because it is used when copying an attribute from a source structure into a target structure. This method may paste the contents of <me> into <intoAttribute>.
    The given pasted attribute can be full or empty of its contents. But don't make a NEW! Just set the contents!
    It is possible to use <aRelocationTable> to get/set the relocation value of a source attribute.

    Parameters (2)
    • intoAttribute
    • aRelocationTable

TDocStd_XLinkIterator

Iterates on Reference attributes. This is an iterator giving all the external references of a Document.

Constructors(2)

Instance methods(4)

  • Restarts an iteration with <D>.

    Parameters (1)
    • D
  • More(): boolean

    Returns True if there is a current Item in the iteration.

  • Next(): void

    Move to the next item; raises if there is no more item.

  • Returns the current item; a null handle if there is none.

TDocStd_XLinkRoot

This attribute is the root of all external references contained in a Data from TDF. Only one instance of this class is added to the TDF_Data root label. Starting from this attribute all the Reference are linked together, to be found easily.

Static methods(6)

Instance methods(6)

TDocStd_XLinkTool

This tool class is used to copy the content of source label under target label.
Only child labels and attributes of source are copied. attributes located out of source scope are not copied by this algorithm. Depending of the called method an external reference is set in the target document to registered the externallink. Provide services to set, update and perform external references. Warning1: Nothing is provided in this class about the opportunity to copy, set a link or update it. Such decisions must be under application control. Warning2: If the document manages shapes, use after copy TNaming::ChangeShapes(target,M) to make copy of shapes.

Constructors(1)

Instance methods(6)

  • Copy(intarget: TDF_Label, fromsource: TDF_Label): void

    Copy the content of <fromsource> under <intarget>. No link is registered. No check is done.
    Example occ::handle<TDocStd_Document> DOC, XDOC; TDF_Label L, XL; TDocStd_XLinkTool xlinktool; xlinktool.Copy(L,XL); Exceptions: Standard_DomainError if the contents of fromsource are not entirely in the scope of this label, in other words, are not self-contained. !!! ==> Warning: If the document manages shapes use the next way: TDocStd_XLinkTool xlinktool; xlinktool.Copy(L,XL); NCollection_DataMap<TopoDS_Shape, TopoDS_Shape, TopTools_ShapeMapHasher> M; TNaming::ChangeShapes(target,M);.

    Parameters (2)
    • intarget
    • fromsource
  • IsDone(): boolean