From fac384d677b13fb4cc9a47a51f60dc9667c03bae Mon Sep 17 00:00:00 2001 From: Pieter Hijma Date: Mon, 20 Oct 2025 16:04:48 +0200 Subject: [PATCH] Doc: Add a topic for App::link --- src/App/Link.h | 7 +++++- src/App/core-app.dox | 60 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+), 1 deletion(-) diff --git a/src/App/Link.h b/src/App/Link.h index b99293a507..bc4b4d785b 100644 --- a/src/App/Link.h +++ b/src/App/Link.h @@ -53,6 +53,7 @@ namespace App /** * @brief The base class of the link extension. + * @ingroup LinksGroup * * The functionality in this class is reused in LinkExtension, LinkElement, and * LinkGroup. @@ -841,6 +842,7 @@ using LinkBaseExtensionPython = ExtensionPythonT; /** * @brief The link extension class. + * @ingroup LinksGroup * * This class implements the link extension functionality and is the extension * that makes @ref App::Link "Link" a link. @@ -963,7 +965,8 @@ using LinkExtensionPython = ExtensionPythonT; /** - * @brief The Link class. + * @brief The %Link class. + * @ingroup LinksGroup * * Instances of this class represent links to other objects in the document or * even to objects in other documents. @@ -1027,6 +1030,7 @@ using LinkPython = App::FeaturePythonT; /** * @brief A class that represents an element of a link. + * @ingroup LinksGroup * * A link with an element count greater than 0 will contain multiple links to * the linked object, all with their own placement, scale, and visibility. @@ -1094,6 +1098,7 @@ using LinkElementPython = App::FeaturePythonT; /** * @brief A class that represents a group of links. + * @ingroup LinksGroup * * Other than "upgrading" a normal Link to having multiple @ref * App::LinkElement "LinkElements", a link group is a grouping for document diff --git a/src/App/core-app.dox b/src/App/core-app.dox index 4a665598a1..672fbf243b 100644 --- a/src/App/core-app.dox +++ b/src/App/core-app.dox @@ -692,6 +692,66 @@ * handle multiple inheritance in the C-API for Python extensions. */ +/** + * @defgroup LinksGroup Links + * @ingroup APP + * @brief Links determine relations between document objects and documents. + * + * App::Link document objects are special document objects that create links to + * other document objects, potentially in other documents. Links are special + * document objects that inherit most properties from the object they are + * linked to, but they can override some properties as well, such as the + * placement, color, or scale. More precisely, the properties that can be + * overridden typically apply simple transforms on the shape of the linked + * object. + * + * The most visible part of links to users is App::Link. It inherits from @ref + * App::DocumentObject "DocumentObject" and from @ref App::LinkExtension + * "LinkExtension" which gives it the functionality to link to other document + * objects. @ref App::LinkExtension "LinkExtension" inherits from @ref + * App::LinkBaseExtension "LinkBaseExtension" and gets most of its + * functionality from that class. + * + * There are two other classes that inherit from @ref App::LinkBaseExtension + * "LinkBaseExtension", namely @ref App::LinkGroup "LinkGroup" and @ref + * App::LinkElement "LinkElement". A %LinkGroup is a group of document objects + * or links with, for example, a common placement. + * + * A @ref App::LinkElement "LinkElement" is a container for link elements to + * form a special kind of group based on only one link. This can be achieved + * by creating an App::Link to an object and increase the element count to + * greater than 0. Each link is then represented by a @ref App::LinkElement + * "LinkElement". + * + * Links are very cheap in the sense that there is no copy of the object it + * links to, although it does have its own shape. The view provider of the + * link also simply makes use the document objects in the original linked + * object. Changing a property in the link (unless it is one of the overridden + * ones) will typically also affect the original linked object. + * + * @section SecCopyOnChange Copy-on-change links + * + * Links can be created as "copy-on-change" links. To create copy-on-change + * links, the source object needs to have a property that is marked as + * "copy-on-change". Creating an App::Link from this source objects creates a + * normal link where the property `LinkedObject` points to the source object. + * + * The user can then change the property `LinkCopyOnChange` to `Enabled` which + * provides the user with copy-on-link behavior although the link is still a + * regular link. What is special, is that the link adopts the copy-on-change + * property from the source object in order for users to change the value in + * the link. As soon as the adopted copy-on-change property is changed, a + * special hidden document object is created inside the link will contain a + * copy of the source object. The link's `LinkedObject` property is then + * changed to point to this hidden object, the changed property is applied on + * this hidden object and the link is now a variant of the original source + * object. + * + * Instead of changing the property `LinkCopyOnChange` to `Enabled`, the user + * can also set it to `Tracking` which means that changes in the original + * object are tracked and applied on the copy. + */ + /** * @namespace App * @ingroup APP