Doc: Improve the topic for App::Document
This commit is contained in:
Pieter Hijma
@@ -19,30 +19,111 @@
|
||||
/**
|
||||
* @defgroup DocumentGroup Document
|
||||
* @ingroup APP
|
||||
* @brief The class that represents a FreeCAD document
|
||||
* @brief The class that represents a FreeCAD document.
|
||||
*
|
||||
* This (besides the App::Application class) is the most important class in FreeCAD.
|
||||
* It contains all the data of the opened, saved, or newly created FreeCAD Document.
|
||||
* The App::Document manages the Undo and Redo mechanism and the linking of documents.
|
||||
* This (besides the App::Application class) is the most important class in
|
||||
* FreeCAD. It contains all the data of the opened, saved, or newly created
|
||||
* FreeCAD %Document. The App::Document class manages the undo and redo
|
||||
* mechanism and linking of documents.
|
||||
*
|
||||
* Note: the documents are not free objects. They are completely handled by the
|
||||
* App::Application. Only the Application can Open or destroy a document.
|
||||
* Note: Documents are not freestanding objects. They are completely handled by the
|
||||
* App::Application class. Only the application can open or destroy a document.
|
||||
*
|
||||
* \section Exception Exception handling
|
||||
* As the document is the main data structure of FreeCAD we have to take a close
|
||||
* look at how Exceptions affect the integrity of the App::Document.
|
||||
* @section SecDocumentProperties Documents as property containers
|
||||
*
|
||||
* \section UndoRedo Undo Redo an Transactions
|
||||
* Undo Redo handling is one of the major mechanism of a document in terms of
|
||||
* user friendliness and speed (no one will wait for Undo too long).
|
||||
* The main role of a document is being a container of @ref DocumentObjectGroup
|
||||
* "DocumentObjects". Both a @ref DocumentObjectGroup "DocumentObject" and a
|
||||
* @ref App::Document "Document" are @ref PropertyFramework
|
||||
* "PropertyContainers" and can hold properties.
|
||||
*
|
||||
* \section Dependency Graph and dependency handling
|
||||
* The FreeCAD document handles the dependencies of its DocumentObjects with
|
||||
* an adjacency list. This gives the opportunity to calculate the shortest
|
||||
* recompute path. Also, it enables more complicated dependencies beyond trees.
|
||||
* However, there is a crucial difference between the properties in a document
|
||||
* and in a document object. The properties in a document cannot be the target
|
||||
* of expressions and they do not take part in the dependency check mechanism.
|
||||
* This means that if a document object references a property of a document and
|
||||
* the document property is changed, the document object that references the
|
||||
* document property will not be marked to be recomputed. As such, the
|
||||
* properties in a document should be regarded as simple properties for
|
||||
* file-related information.
|
||||
*
|
||||
* @see App::Application
|
||||
* @see App::DocumentObject
|
||||
* @section SecObjectManagement Object management
|
||||
*
|
||||
* As mentioned above, a document is a container of document objects. Document
|
||||
* objects can only exist inside a document and the document provides
|
||||
* functionality to create, remove, and access document objects. For example,
|
||||
* it is possible to get objects of a specific type or with a specific
|
||||
* extension.
|
||||
*
|
||||
* The document also manages the names and labels document objects, ensuring
|
||||
* that names are unique and that labels are unique if configured to have
|
||||
* unique labels.
|
||||
*
|
||||
* @section DependencyGraph Dependencies between document objects
|
||||
*
|
||||
* Objects can link to other objects in the same document or in other documents
|
||||
* and as such dependencies between document objects come into existence. The
|
||||
* document is responsible for recomputing document objects if some property of
|
||||
* a document object changes. The dependencies between document objects
|
||||
* determine in which order the objects must be recomputed.
|
||||
*
|
||||
* To compute the objects in the right order, the document computes a
|
||||
* dependency graph based on the information contained in the OutLists and
|
||||
* InLists of the document objects. For more information on OutLists and
|
||||
* InLists, see @ref SecDocumentObjectRecompute "Document Objects". Given the
|
||||
* dependency graph, the document computes the list of objects in topological
|
||||
* order (not to be confused with topological naming) which means that the
|
||||
* objects without dependencies come first and then the objects that depend on
|
||||
* these objects, etc.
|
||||
*
|
||||
* The document will check for each object in the list whether the object is
|
||||
* "touched", which means that it is marked to be recomputed. If so, the
|
||||
* object is recomputed and the objects in the InList of that object are
|
||||
* touched as well. Because of the topological order, these objects will come
|
||||
* in a later iteration.
|
||||
*
|
||||
* This mechanism allows FreeCAD to recompute only the objects that need to be
|
||||
* recomputed and in only one pass over the list of objects. However, it is
|
||||
* important that the dependency graph does not contain cycles and is a
|
||||
* "Directed Acyclic Graph" or DAG. As such, cyclic dependencies are not
|
||||
* allowed in FreeCAD.
|
||||
*
|
||||
* @section SecUndoRedo Undo Redo and Transactions
|
||||
*
|
||||
* Another important responsbility of documents is to manage undo and redo
|
||||
* actions. The information to support undo and redo is captured in
|
||||
* transactions. It is important to understand that transactions are a feature
|
||||
* of document objects and not of documents. This means that a change of a
|
||||
* property inside a document (as opposed to inside a document object) is not
|
||||
* captured by the transaction system (similar to the fact that document
|
||||
* properties do not support expressions).
|
||||
*
|
||||
* The transaction system is quite complex and acts on various levels.
|
||||
* Although the transactions themselves only capture changes regarding document
|
||||
* objects, the transactions are managed in the document. Although the
|
||||
* transactions are managed inside a document, it is possible to support
|
||||
* transactions that affect multiple documents. This is managed by the GUI and
|
||||
* if a change affects multiple documents, then all documents will store
|
||||
* transactions that change its document and they will all have the same
|
||||
* transaction ID.
|
||||
*
|
||||
* The mechanisms for undo and redo are part of the @ref APP "App" level, but
|
||||
* the GUI defines the transactions (where to open a transaction, where to
|
||||
* commit or abort) and it initiates the undo and redo actions.
|
||||
*
|
||||
* The transaction system makes use of classes with very similar names which
|
||||
* can be confusing. Here is a short overview:
|
||||
*
|
||||
* - A @ref App::TransactionalObject "TransactionalObject" is a base class that
|
||||
* provides the functionality to support transactions. It is inherited by
|
||||
* @ref App::DocumentObject "DocumentObject".
|
||||
* - A @ref App::TransactionObject "TransactionObject" is a class that
|
||||
* represents a single action and can express adding a new object, removing
|
||||
* an object or changing an object. Subclasses of the transaction object are
|
||||
* @ref App::TransactionDocumentObject "TransactionDocumentObject" and
|
||||
* @ref Gui::TransactionViewProvider "Gui::TransactionViewProvider".
|
||||
* - A @ref App::Transaction "Transaction" captures a single undo or redo
|
||||
* action and consists of multiple @ref App::TransactionObject
|
||||
* "TransactionObjects" associated with their @ref App::TransactionalObject
|
||||
* "TransactionalObject", often a @ref App::DocumentObject "DocumentObject".
|
||||
*/
|
||||
|
||||
/**
|
||||
|
||||
Reference in New Issue
Block a user