diff --git a/src/App/core-app.dox b/src/App/core-app.dox index 4b67de039e..7dd9afc185 100644 --- a/src/App/core-app.dox +++ b/src/App/core-app.dox @@ -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". */ /**