Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
App::Link functionality #2350
Forum thread: https://forum.freecadweb.org/viewtopic.php?f=17&t=37757
I have logically grouped all the changes into individual commits with detailed comments. Many of the commits are interrelated, meaning that they can only be applied in whole. It most likely won't compile if checkout in the middle.
PS: I just notice that github reorder my commits in its original time stamp, but I have rebased it multiple times with a refined order. For a more coherent view of the commits, please checkout git commit logs in my branch.
Setting ReadWrite permssion removes executable permission, causing error when removing directory on Linux.
DocumentObject: * getSubObject(): the most important API for Link to work with hierarchies. The function is a inspired from and replaces the getPySubObjects(). It returns a child object following a dot separated subname reference, and can optionally return accumulated transformation, and/or a python object of the refered sub-object/element. The default implementation here is to look for link type property, and search for the referenced object. This patch also include other specialized implementation of this API, such as (GeoFeature)GroupExtension (through extensionGetSubObject()), PartDesign::Body, and so on. A link type object is expected to call the linked object's getSubObject() for resolving. * getSubObjects(): return a list of subname references of all children objects. Container type object is expected to implement this function. The reason it returns subname references instead of just object is to allow the container to skip hierarchies. For example, the Assembly3 container uses this to skip the constraint and element group. * getLinkedObject(), obtain the linked object, and optionally with the accumulated transformation. It is expected to return a linked object or the object itself if it is not a link. In case there are multiple levels of linking involved, this function allows the caller to retrieve the linked object recursively. * hasChildElement(), set/isElementVisible(), controls the children visibility for a group type object. Because the child object may be claimed by other objects, it is essential to have independent control of children visibilities. These APIs are designed to abstract how group manages the child visibility. For performance reason, these function are meant to control only the immediate child object. * resolve(), helper function to parse subname reference and resolve the final object, and optionally the immediate parent of the final object, the final object reference name (for calling `set/isElementVisible()`), and the subname reference if there is one. * touch(), add optional argument 'noRecompute' for better backward compatibility with the NoRecompute flag. By default, touch() causes recompute unless noRecompute is true * signalChanged/signalBeforeChange, two new signal for tracking changes of a specific object. * getViewProviderNameOverride(), return a string of the view provider type of this object. This allows Python class to override the view provider of an object. This feature will be used by ViewProviderLink which is designed to work with any object that has LinkBaseExtension. * canLinkProperties(), will be used by Gui::PropertyView to display linked object properties together with the object's own properties. * redirectSubname(), will be used by Gui::Tree to allow an object to redirect selection to some other object when (pre)selected in the tree view. * Visibility, new property serve as the same purpose as view provider property of the same name. It is added here so that App namespace code can check for visibility without Gui module. This is useful, for example, when constructing a compound shape of a container that respects the children visibility. * (has)hasHiddenMarker(), return or check for a special sub-element name used as marker for overriding sub-object visibility. Will be used by Gui::ViewProvider, it is put here for the same reason as adding Visibility property. * getID(), return object internal identifier. Each object is now assigned an integer identifier that is unique within its containing document. Document: * ShowHidden, new property to tell tree view whether to show hidden object items. * signalTouchedObject, new signal triggered when manually touch an object when calling its touch() function * getObjectByID(), get object by its identifier * addObject() is modified to allow overriding view provider * has/getLinksTo(), helper function to obtain links to a given object. Application: * checkLinkDepth(), helper function to check recursive depth for link traversal. The depth is checked against the total object count of all opened documents. The count (_objCount) is internally updated whenever object is added or removed. * has/getLinksTo(), same as Document::has/getLinksTo() but return links from all opened documents. GroupExtension/OriginGroupExtension/DatumFeature/DatumCS/Part::Feature: implement sepcialized getSubObject/getSubObjects().
Property: * Extended property status bitset. Mirror most of PropertyType and allow dynamic change property type. * Cache property name and type to improve performance * Centralize property status change signalling * Change aboutToSetValue()/hasSetValue() to virtual * Add new API getFullName() to obtain full quanlified name of the property AtomicPropertyChangeInterface: * Allow calling aboutToSetValue()/hasSetValue() when actually changed PropertyLists: * Refactor implementation by an abstract class PropertyListBase and a template class PropertyListsT, to allow better code reuse. PropertyListT is derived from AtomicPropertyChangeInterface to allow more efficient change on individual elements. * All list type property now accept setting python value as a dictionary with index as key to set individual element of a list. * Add touch list for more efficient handling of value changes. The list contains the index of changed value. And empty touch list should be treated as the entire list is changed. PropertyContainerPy expose this functionality with getPropertyTouchList(). PropertyPersistentObject: * New property to allow dynamic creation of any FreeCAD object derived from Base::Persistence, and use it as a property. DynamicProperty: * Use boost multi_index_container for efficient property lookup while keeping order. * Modify to be allowed to use in PropertyContainer directly PropertyContainer: * Use boost multi_index_container for efficient property lookup while keeping order. * Allow adding/removing dynamic property on all property container * Modify Save/Restore() to persist property status, and better handle transient property which can now be dynamically enabled/disabled per object. * Add new API getFullName() to obtain full quanlified name of the property. Implemented by Document, DocumentObject, and also ViewProviderDocumentObject if future patch DocumentObject and FeaturePython are modified to accommondate the dynamic property changes. Removed get/setCustomAttribute() implementation from DocumentObjectPy, and rely on PropertyContainerPy for the implementation, because of the additional dynamic property support in property container. Gui::ViewProviderDocumentObject, which is derived from PropertyContainer, is also modified accordingly
Introduce a new concept of transaction ID. Each transaction must be unique inside the document. Multiple transactions from different documents can be grouped together with the same transaction ID. This makes it possible to undo/redo single operation that contains changes from multiple documents due to external linking. Application: * get/set/closeActiveTransaction() is used to setup potential transactions with a given name. The transaction is only created when there is actual changes. If objects from multiple documents are changed under the same active transaction, they will have the same trasnaction ID, and can be undo/redo togtether later. * signalUndo/signalRedo, new signals triggered once after an undo/redo operation. Unlike signalUndo/RedoDocument, these signals will only be triggered once even if there may be multiple documents involved during undo/redo. * signal(Before)CloseTransaction, new signals triggered before/after an actual transaction is created or aborted. AutoTransaction: * Helper class to enable automatic management of transactions. See class document for more details. This class will be used by Gui::Command in later patches to allow better automation of transactions in command. Document: * open/commit/abortTransaction() are now redirected to call Application::get/set/closeActiveTransaction() instead. * _openTransaction() is added to do the real creation of transaction. * _checkTransaction() is modified to create transaction on actual change of any property. * getTransactionID() is used to find out the position of a transaction with a given ID. When triggering undo in external document, it may be necessary to perform multi-step undo/redo in order to match for the transaction ID. Transaction/TransactionObject: * Various changes for the new transaction ID concept. * Support undo/redo add/remove dynamic property
Create new class PropertyLinkBase as the common parent class for all type of links. See the class document for details of its API. Added new link scope 'Hidden' that is ignored during normal object dependency calculation, but still keep tracks of object remove, relabel, etc. DocumentObject added a new API adjustRelativeLink() and a helper resolveRelativeLink() function.
Convenience macros/function (in Interpreter.h) * FC_PY_GetObject/Callable(), look for callables in a python object, which will be used in future patch to improve performance in various python observer/features. * pyCall(WithKeywords)(), helper function to invoke the callable Matrix4D: * hasScale(), check if there is any scale in the transformation. If so, further check if the scale is uniform or not. This will be used in future patch for Part::TopoShape to decide which type of transform to apply. Placement: * translate/rotate(), new convenience API Rotation: * isSame/multiVec(), new convenience API Polygon2d: * Intersect(), GetCenter(), new convenience API. FlagToggler: * New class for exception safe flag toggling, similar to StateLocker but with template (actually, FlagToggler is added earlier by me). BitsetLocker: * New class for exception manipulation of a std::bitset variable.
PropertyExpressionEngine is changed to derived from a new class PropertyExpressionContainer, which is in turn derives from PropertyXLinkContainer. This makes PropertyExpressionEngine a link type property that is capable of external linking. It now uses the unified link property APIs for dependency management and tracking of object life time, re-labeling, etc. ObjectIdentifier is modified to support sub-object reference, but is not exposed to end-user, because expression syntax is kept mostly unchanged, which will be submitted in future PR. There is, however, one small change in expression syntax (ExpressionParser.y) to introduce local property reference to avoid ambiguity mentioned in #1619 Modified Expression/ExpressionModifier interface to support various link property API for link modification.
PropertySheet is changed to derive from PropertyExpressionContainer, which makes it a link type property that is capable of external linking. It now relies on the unified link property API to manage object depenency, and tracking of object life time, relabeling, etc. This patch also includes various fix and improvement of Spreadsheet, such as improved recompute efficiency, correct handling of document label change, etc.
These two APIs allow an object to control its own labeling rules. The previous auto re-labeling for uniqueness logic is moved from ObjectLabelObserver (resides in Application.cpp) to PropertyString. DocumentObject::allowDuplicateLabel() is used to inform PropertyString that the object allows duplicate label regardless of application setting. onBeforeChangeLabel() is called before actual label change to give object a chance to override the new label.
Added getInListEx() as a more efficient algorithm for recursive in list. Replacing the original getInListRecursive(). Added out list object and name cache to improve default implementation of getSubObject().
This patch adds support of recomputation with external linked object, as well as external document auto loading and partial loading. Application: * Modified new/openDocument()/signalNewDocument to choose whether to signal GUI for creating a view for the document. This makes it possible to suppress view creation when opening external documents. * New API openDocuments() which does the actual job of loading the document together with any external dependencies. There are afew extra arguments to allow setting FileName property differently from the actual file path, which are required when auto loading dependencies during document recovery (with future patch to Gui::DocumentRecovery) * openDocumentPrivate() is an internal helper for opening individual document. * New signalStart/FinishOpenDocument to be signaled before and after opening a document. There may be multiple depending documents actually opened in between these two signals. * New signalBeforeRecomputeDocument signaled before recompute a document. * New API addPendingDocument() for use by external capable link properties' to queue up external documents. * isRestoring/isClosingAll(), for convenience status reporting. Document: * signalFinishImport/RestoreObjects, new signal triggered after imported or restored all input objects * signalBeforeRecompute, signaled before start recomputing this document * Modified signalRecomputed with additional recomputed objects, this is to make it more efficient for Gui::TreeWidget to check recomputation result. * signalSkipRecompute, signal to inform which objects are skipped during recomputation because of their owner document SkipRecompute setting. * restore/save/read/writeObjects() modified to suport partial loading. See [here](https://git.io/fj6PY) for more information. * afterRestore(), internal function called to finish restore. The function is separated from restore() because there is quite a few critical steps needed to fully restore a document with external linking. See [here](https://git.io/fj6P4) for more information. * DocumentP::_RecomputeLog is modified to store more accurate object recomputation error, including those happened during restore/import. * isExporting(), new API for checking if an object is exporting. External linking properties will use this function to decide how to export. * copyObject(), modified to support external linking objects, and accepts multiple input objects. * moveObject(), modified to support arbitary object moves. The original implementation may cause crash if undo/redo is enabled. Furthermore, because the original information fakes the object's deletion to break its dependency, it does not work for objects that may auto delete their children when being deleted. The new implementation copy the object, and than paste it to the other document. It then deletes the input objects from the original document. In case of recursive move, it only deletes the depending object if it has an empty in list. * importLinks(), new API to import any external object linked by the input objects into this document. It will auto correct all link references after importing. * getDependencyList/_rebuildDependencyList(), these two APIs are unified and implemented by an internal function _buildDependencyList() with a new algorithm to handle external objects. The returned dependency list will now include objects from external documents. In case of cyclic dependencies, getDpendencyList() will report the actual objects involved in dependency loops. * mustExecute(), new API to check if there are any object requires recomputation. This function will call _buildDependencyList() and check for external objects as well. * addRecomputeObject(), new API for marking changes during document restore. It only marks the object but does not actually recompute them for performance reason. One use case is for geo feature to request for recomputation to generate geometry topological names. * recompute(), support partial, external, and inverse dependency recomputation. Improve error handling during recomputation. See [here](https://git.io/fj6PO) for more information. * _recomputeFeature(), suppoert user abort. * getDependentDocuments/getInList(), new API to obtain an optional dependency sorted list of depending documents. DocumentObject: * Add various ObjectStatus flags * isExporting/getExportName(), return a safe name for exporting, in the form of <ObjName>@<DocName>, which is guarrenteed to be unique. Various link property will save linked object using this name if the the linked object is exported together with the owner object, see [PropertyLinkBase::restoreLabelReference()](https://git.io/fj6XO) for more information. * recomputeFeature(), add option to recompute this object together with all its dependent objects. * canLoadPartial(), new API for [partial document loading](https://git.io/fj6PY). MergeDocuments: * Move object name mapping logic to various link properties. See Base::Sequencer: * Add new API checkAbort() for checking user abort.
The future patch will introduce Part::getTopoShape() to construct a compound shape from a group. It will rely on the children visibility to determine whether to include the child shape or not. This patch adds children visibility tracking capability to group, and makes sure that the group object will be marked for recomputation in case of any change in group member, and their visibility status. * Remove Prop_Output from 'Group' property. * Added hidden property _GroupTouched to help propagate children change. * Track children visibility change using signal * GeoFeatureGroupExtension uses new PropertyLinkBase interface for scope checking.
See bug description: https://bitbucket.org/Coin3D/coin/pull-requests/119/fix-sochildlist-auditing/diff Because of path based rendering (SoFCPathAnnotation) in mouse over highlight, this bug causes crash more frequently here comparing to upstream. All C++ calling of SoGroup::removeAllChildren() is replaced by Gui::coinRemoveAllChildren(), and python code is fixed by monkey patching SoGroup.removeAllChildren() in FreeCADGuiInit.py.
Some of these new APIs are not strictly needed for Link to work, but good to have. Summary of the API changes: * getModeSwitch/getTransformNode() exposes view provider mode switch and transformation coin3D node, required by ViewProviderLink to override placement and visibility. * canAddToSceneGraph() inform 3D viewer whether to add the root node to scenegraph. Some object only exists as a child of some coordinate system. Not adding them can simplify scenegraph and visibility management. * showInTree() inform tree view whether to show the corresponding tree item. * getDefaultMode() to expose the current active mode regardless of the view provider's visibility * (can)DropObjectEx() superseds (can)DropObject() with additional support of subname reference, which makes it easy to support linking to sub-objects. One of the use case is cross coordinate system linking. * getDropPrefix() is used to tell tree view where the object is dropped into. A non empty return means the object is actually dropped into a sub-object. For example, Assembly3 container puts all dropped object into its child container PartGroup. * canDragAndDropObject() is used to inform tree view whether the object dropped need to be dragged out of its original parent, which usually does not make sure for Link type object. * beforeDelete() will be called by Gui::Document when either the object itself is being deleted or when the document is being destoried. * is/setLinkVisibility() allows to show/hide a link to this object. This may be used during editing, to prevent showing editing geometry in multiple places. * update() is made a virtual function, it will be overridden by ViewProviderDocumentObject in future patch. * startEditing() now becomes virtual, and return a ViewProvider that actually handles the editing. This is for future Link type object to forward editing request * covert(), convenience function to convert between Coin3D and FC matrix ViewProviderExtension also gains many relavant extension point of the new API. There is also the new extensionModeSwitchChange() for notifying mode switch changes ViewProviderPy exposes several method/attribute for the new API as well.
A convenience class to obtain common view parameters, analogous to existing WindowParameter class.
Context aware selection makes it possible to select the same Coin3D node in different hierarchies (i.e. context) without ambiguity. New/modified APIs in ViewProvider (the first two are the most crucial APIs for context aware selection to work): * getElementPicked(), supercedes getElement(). Given a Coin3D pick point, this function returns a dot separated subname reference as a path leads to the selected object. * getDetailPath(), supercedes getDetail(). Given a subname reference, this function returns an SoFullPath leads to the Coin3D node of the selected object or sub-element (with SoDetail). * (has)HiddenMarker(), check/return a special text marker for context aware override of object visibility. * partialRender(), render only part of the object based on given subname references. It can render, e.g. some faces of a solid, or some children of a container. It uses the 'secondary' extension of SoSelectionElementAction to select which elements to render or hide. The actually rendering functionality will be added in the following patch. * update()/onChanged(), modified to sync Visibility property from DocumentObject. * useNewSelectionModel(), modified to return the default true view parameter. This is for test in the early stage of Link development, probably not needed anymore. * getBoundingBox(), a convenience function to obtain the bounding box of a sub-object/element regardless of object's visibility. It uses getDetailPath() and SoGetBoundingBoxAction to obtain bounding box through Coin3D. It will be used in later sub-element box selection functionality. New/modified APIs in ViewProviderDocumentObject: * getElementPicked()/getDetailPath() provides actual implementation to support container like (sub)object selection without ambiguity. It relies on DocumentObject::getSubObject() to walk the path. * reattach(), called when undo deleteion * forceUpdate()/isUpdateForced(), force update even if object is invisible. These are used by Link to force update the visual of a linked object regardless of its visibility. * getLinkedViewProvider(), return the linked view provider with hierarchy. ViewProviderDocumentObjectPy: * Object attribute is made writtable. Assigning it is equaivalant of calling ViewProviderDocumentObject::attach() in Python.
* invoke(), distinguish between command triggering source. Also add support of auto transaction using App::AutoTransaction. Now all command will support undo/redo by default. * setupCheckable(), a helper function to Improve support of PythonGroupCommand * getObjectCmd(), helper function to output Python command to refer to an object without ambiguity. Because with introduction of external linking, an object can no longer be safely referred through the current active document. * Support auto MacroManager command logger. For commands that does not log any output to MacroManager, a log entry of 'Gui.runCommand()' will be auto generated. * Support linked object in copyVisual() * Modified do/runCommand() to print calling file and line number. * Add various helper macros for run command involving a document or object.
The patch implements context-aware selection and rendering in 3D view. Please check [here](https://git.io/fjiY5) for more details, including the following 'Render Caching' section. The patch also includes modification of View3DInventorViewer to support always-on-top selection rendering using the secondary selection context and the new coin node SoFCPathAnnotation. Another small change in SoQtQuarterAdaptor for more responsive frame rate display. The original implementation reports skewed frame rate in the presence of long idle period.
* Fix AutoSaver inconsistent BinaryBrep setting * Use temperary name when auto saving, so that it won't overwrite the original file, which may cause corruption when crashing in the middel of auto saving, especially if auto saving in a separate thread. * Support auto recovery document containing external links * Do not mark success after auto recover, in case the program crash again before the user remember to save the just recovered file. Only mark when user saves the document.
Future GuiDocument.xml will save recursive tree item expansion status using child element with the same name as the parent.
The link support means that an object can now appear in more than one places, and even inside a document different from its own. This patch adds support for in-place editing, meaning that the object can be edited at correct place regardless where it is. See [here](https://git.io/fjPIk) for more info about the relavent APIs. This patch includes two example of modifications to support in-place editing. One is the ViewProviderDragger, which simply adds the dragger node to editing root node by calling View3DInventorViewer::setupEditingRoot(dragger). The other much more complex one is ViewProviderSketch which calls setupEditingRoot(0) to transfer all its children node into editing root. ViewProviderSketch also includes various modifications to command invocation, because we can no longer assume the active document is the owner of the editing object. This patch also includes necessary modification of the 'Show' module to support in-place editing.
Application: * signalNewDocument, check the extra argument, isMainDoc, the decide whether to create view of the new document. This is so that external linked document can be opened in background without crowding the tab list. * slotDeleteDocument, calls Document::beforeDelete() * slotActiveDocument, creates view if none, because external document is now opened without view. * onLastWindowClosed(), switch to next active document, and creates view if none. * send(Has)MsgToFocusView(), new API to send message to the active view in focus. This is to solve the ambiguity of things like pressing delete key, copy, paste handling when the active new is not in focus. For example, when spread sheet view is active, delete/copy/paste handling should be different when the focus on the spread sheet view or focus on tree view. * tryClose(), delegate to MainWindow for close confirmation * reopen(), new API to reload a partial document in full Document/DocumentP: * _CoinMap, new internal map for quick access view provider from its root node. * slotNewObject, modified to support view provider override from App::FeaturePython, through new API DocumentObject::getViewProviderNameOverride(). * slotDeletedObject/slotTransactionRemove, improve handling of geo group children rebuild * slotSkipRecompute, add special handling of document with skip recompute. Some command cannot work when skip recompute is active. For example, sketcher command will check if recompute is successful on many commands, and will undo if not. New 'PartialCompute' flag is added to allow recompute only the editing object and all its dependencies if 'SkipRecompute' is active. * slotTouchedObject, new signal handling of manually touched object. * setModified(), do nothing if already modified. This is a critical performance improvement, because marking tab window as modified turns out to be a relatively expensive operation, and will cause massive slow down if calling it on every property change. * getViewProviderByPathFromHead/getViewProvidersByPath(), new APIs to obtain view provider(s) from coin SoPath. * save/saveAll/saveCopy, modified to support external document saving. * Save/RestoreDocFile(), save and restore tree item recursive expansion status. * slotFinishRestoreObject(), handle new signal signalFinishRestoreObject(), unifies postprocessing in restore and import operation. * createView/setActiveView(), add support of delayed view creations * canClose(), delegate to MainWindows to ask for confirmation * undo/redo(), support grouped transaction undo/redo. Transactions may be grouped by the same transaction ID if they are triggered by a single operation but involves objects from multiple documents. * toggleInSceneGraph(), new API to add or remove root node from or to scenegraph without deleting the view object. MainWindow: * Update command status using a single shot timer instead of periodical one. * Improve message display is status bar. Give error and warning message higher priority (using QStatusBar::showMessage()) than normal status message (using actionLabel), reversed from original implementation. * confirmSave(), new API to check for modification, and ask user to save the document before closing. The confirmation dialog allows user to apply the answer to all document for convenience. * saveAll(), new API to save all document with correct ordering in case of external linking. * createMimeDataFromSelection/insertFromMimeData(), support copy paste object with external linking. A new dialog DlgObjectSelection is used to let user select exactly which object to export. CommandDoc/CommandWindow: * Related changes to object delete, document import, export, and save.
Always check for version changes when building. Version.h is only updated if actually changed.
This patch includes the actual implementation of Link, which is implemented as an extension named LinkBaseExtension in App namespace, and a full view provider ViewProviderLink in Gui. The reason of not using ViewProviderExtension is because it need full control when display, not just extending existing functionalities. Please see [here](https://git.io/fjPue) for more details of the implementation. This patch also includes a set of link manipulation commands, and a task panel for overriding geometry element colors.
* Display property from linked object, colored green, * Change DlgPropertyLink to support external linking and sub-object selection * Improve large selection performance by using a timer * Improve TAB key behavior in property editor * Add context menu to show hidden properties, change property status, set expression on any and property, and add/remove dynamic properties * Optimize expression completer model construction, as the original implementation gets prohibitively slow for moderate number of objects.
A PPA for this branch is now available providing
Each command will create an App::AutoTransaction to auto create and commit a transaction for proper undo/redo. But if the command starts editing, the current transaction may be required to out live the current command. Note that the command can only detect editing if the code calls Gui::Document::setEdit(). There are objects that starts editing by calling its own ViewProvider::setEdit(), e.g. various TechDraw ViewProviders. In this case, to avoid auto committing, one can call App::Application::setActiveTransaction() with the second argument set to true, or call App::AutoTransaction::setEnable(false).