From c093fd484c5b530f1bccc8bf0832fb975e0b98c6 Mon Sep 17 00:00:00 2001 From: Pieter Hijma Date: Sun, 8 Jun 2025 17:52:41 +0200 Subject: [PATCH] Doc: Add a topic for App::DocumentObject --- src/App/core-app.dox | 110 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 109 insertions(+), 1 deletion(-) diff --git a/src/App/core-app.dox b/src/App/core-app.dox index adb1bf8770..4b67de039e 100644 --- a/src/App/core-app.dox +++ b/src/App/core-app.dox @@ -48,7 +48,115 @@ /** * @defgroup DocumentObjectGroup Document Object * @ingroup APP - * @brief %Base class of all objects handled in the Document. + * @brief %Base class of all objects handled in the @ref App::Document "Document". + * + * A DocumentObject is the base class of all objects that can be contained in a + * FreeCAD @ref App::Document "Document". Document objects can represent any + * object that can be created in a FreeCAD Document, such as features: + * Part::Feature, Mesh::Feature, Sketcher::SketchObject, but also other objects + * such as App::Link, App::DocumentObjectGroup, App::VarSet, or + * SpreadSheet::Sheet that do not necessary represent geometry. + * + * Document objects provide the functionality to handle properties (it extends + * @ref App::PropertyContainer "PropertyContainer"), transactions (it extends + * @ref App::TransactionalObject "TransactionalObject") and extensions (it + * extends @ref App::ExtensionContainer "ExtensionContainer"), and expressions. + * Expressions are managed by the property @ref + * App::DocumentObject::ExpressionEngine "ExpressionEngine", which is a special + * type of a link property that contains expressions that may link to other + * document objects. + * + * @section SecDocumentObjectRecompute Recomputing Document Objects + * + * Objects can be recomputed, which means that the properties of the object are + * recomputed. Since properties may depend on other document objects, for + * example because of the @ref App::DocumentObject::ExpressionEngine + * "ExpressionEngine" property, these document objects have to be computed + * first. Managing the order of recomputation is managed by the @ref + * App::Document "Document" which calls the @ref + * App::DocumentObject::recompute() "recompute()" on the document object. To + * signal that a document object needs to be recomputed, the document object + * can be touched (see @ref App::DocumentObject::touch() "touch()" and @ref + * App::DocumentObject::isTouched() "isTouched()"). + * + * As part of recomputation, the document object can also be executed or + * "invoked", (see @ref App::DocumentObject::execute() "execute()") which + * results in recomputing the output properties of the object. + * + * Although recomputation is mostly orchestrated by the @ref App::Document + * "Document", document objects play an important role in capturing the + * dependencies between document objects in terms of OutLists and InLists. + * + * Dependencies between document objects come into existence because of links + * and if a document object `A` links to another document object `B`, then `B` + * is in the OutList of `A` and `A` is in the InList of `B`. The InList for an + * object `Obj` represents the document objects that are dependent on it. The + * outlist of an object `Obj` represent the dependencies of it. So, to + * recompute `Obj`, first the objects in the outlist need to be recomputed. + * Vice versa, if a property of an object is changed, the InList indicates + * which other objects depend on it and need to be recomputed. + * + * So, as mentioned above, links define dependencies between document objects + * These dependencies are recorded by means of setting the value of a @ref + * App::PropertyLink "PropertyLink" (and similar properties) in a document + * object `Obj` to a document object `Value`. Within @ref + * App::PropertyLink::setValue() "PropertyLink::setValue()" (and similar + * methods for other link properties), the (internal) methods _addBackLink() or + * _removeBackLink() will be called on `Value` with as argument the container + * of the property link `Obj`, indicating that `Obj` depends on `Value`. With + * this methodology, each document object will build up its own InList that can + * be used during recomputation to query which other document objects need to + * be computed. + * + * The OutList and InList can be accessed by the methods @ref + * App::DocumentObject::getOutList() "getOutList()" and @ref + * App::DocumentObject::getInList() "getInList()". + * + * @section SecDocumentObjectProperties Properties + * + * The document object introduces three properties: + * + * - @ref App::DocumentObject::Label "Label" which is a string that identifies + * the object in the document and is used to display the object in the GUI. + * - @ref App::DocumentObject::Label2 "Label2" which is a string that contains + * additional information about the object and is used for the description of + * the object. + * - @ref App::DocumentObject::ExpressionEngine "ExpressionEngine" which + * contains a mapping from @ref App::ObjectIdentifier "ObjectIdentifier" to + * @ref App::Expression "Expression". The object identifier defines the + * properties that store the result of the expression. + * - @ref App::DocumentObject::Visibility "Visibility" which is a boolean + * that indicates whether the object is visible in App namespace. + * + * @section SecDocumentObjectSignals Signals + * + * A document object has three signals that can be connected to: + * + * - @ref App::DocumentObject::signalBeforeChange "signalBeforeChange" which is + * emitted before a property of the document object is changed. This signal + * can be used to prepare for changes to the document object. + * - @ref App::DocumentObject::signalChanged "signalChanged" which is emitted + * after a property of the document object has changed. + * - @ref App::DocumentObject::signalEarlyChanged "signalEarlyChanged" which + * is also emitted after a property has changed but emitted right before + * "signalChanged". + * + * Note that at the @ref App::Document "Document" level, there are also similar + * signals. + * + * @section SecDocumentObjectSeparation Separation App/Gui + * + * In FreeCAD there is a strict separation between the App and Gui parts. A + * @ref App::DocumentObject "DocumentObject" typically has a Gui::ViewProvider + * class associated with it. The method @ref + * App::DocumentObject::getViewProviderName() "getViewProviderName()" defines + * what the type of the class of the view provider is, allowing the Gui to + * retrieve the type and construct a view provider. + * + * Another intresting aspect of the separation is that the property @ref + * App::DocumentObject::Visibility "Visibility" is defined both in + * App::DocumentObject and in @ref Gui::ViewProviderDocumentObject::Visibility + * "Gui::ViewProviderDocumentObject". */ /**