kindred/create
1
1
Fork 0
Code Issues 37 Pull Requests Actions Packages Projects 9 Releases 2 Wiki Activity

App: [skip ci] improve whitespaces

Browse Source
This commit is contained in:
wmayer
2020-09-12 17:43:01 +02:00
parent f66b2953b7
commit 6c2c84df4f
2 changed files with 118 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
src/App/ExtensionContainer.h
View File

@@ -33,54 +33,54 @@
#include <Base/Reader.h>
namespace App {
/**
* @brief Container which can hold extensions
*
* In FreeCAD normally inheritance is a chain, it is not possible to use multiple inheritance.
* The reason for this is that all objects need to be exposed to python, and it is basically
*
* In FreeCAD normally inheritance is a chain, it is not possible to use multiple inheritance.
* The reason for this is that all objects need to be exposed to python, and it is basically
* impossible to handle multiple inheritance in the C-API for python extensions. Also using multiple
* parent classes in python is currently not possible with the default object approach.
*
* The concept of extensions allow to circumvent those problems. Extensions are FreeCAD objects
* which work like normal objects in the sense that they use properties and class methods to define
* their functionality. However, they are not exposed as individual usable entities but are used to
* extend other objects. A extended object gets all the properties and methods of the extension.
* Therefore it is like c++ multiple inheritance, which is indeed used to achieve this on c++ side,
*
* The concept of extensions allow to circumvent those problems. Extensions are FreeCAD objects
* which work like normal objects in the sense that they use properties and class methods to define
* their functionality. However, they are not exposed as individual usable entities but are used to
* extend other objects. A extended object gets all the properties and methods of the extension.
* Therefore it is like c++ multiple inheritance, which is indeed used to achieve this on c++ side,
* but provides a few important additional functionalities:
* - Property persistence is handled, save and restore work out of the box
* - The objects python API gets extended too with the extension python API
* - Extensions can be added from c++ and python, even from both together
*
* The interoperability with python is highly important, as in FreeCAD all functionality should be
* as easily accessible from python as from c++. To ensure this, and as already noted, extensions can
* The interoperability with python is highly important, as in FreeCAD all functionality should be
* as easily accessible from python as from c++. To ensure this, and as already noted, extensions can
* be added to a object from python. However, this means that it is not clear from the c++ object type
* if an extension was added or not. If added from c++ it becomes clear in the type due to the use of
* multiple inheritance. If added from python it is a runtime extension and not visible from type.
* Hence querying existing extensions of an object and accessing its methods works not by type
* casting but by the interface provided in ExtensionContainer. The default workflow is to query if
* an extension exists and then get the extension object. No matter if added from python or c++ this
* interface works always the same.
* multiple inheritance. If added from python it is a runtime extension and not visible from type.
* Hence querying existing extensions of an object and accessing its methods works not by type
* casting but by the interface provided in ExtensionContainer. The default workflow is to query if
* an extension exists and then get the extension object. No matter if added from python or c++ this
* interface works always the same.
* @code
* if (object->hasExtension(GroupExtension::getClassTypeId())) {
* App::GroupExtension* group = object->getExtensionByType<GroupExtension>();
* group->hasObject(...);
* group->hasObject(...);
* }
* @endcode
*
* To add a extension to an object, it must comply to a single restriction: it must be derived
* from ExtensionContainer. This is important to allow adding extensions from python and also to
* access the universal extension API. As DocumentObject itself derives from ExtensionContainer this
* should be the case automatically in most circumstances.
*
* Note that two small boilerplate changes are needed next to the multiple inheritance when adding
*
* To add a extension to an object, it must comply to a single restriction: it must be derived
* from ExtensionContainer. This is important to allow adding extensions from python and also to
* access the universal extension API. As DocumentObject itself derives from ExtensionContainer this
* should be the case automatically in most circumstances.
*
* Note that two small boilerplate changes are needed next to the multiple inheritance when adding
* extensions from c++.
* 1. It must be ensured that the property and type registration is aware of the extensions by using
* 1. It must be ensured that the property and type registration is aware of the extensions by using
* special macros.
* 2. The extensions need to be initialised in the constructor
*
*
* Here a working example:
* @code
* @code
* class AppExport Part : public App::DocumentObject, public App::FirstExtension, public App::SecondExtension {
* PROPERTY_HEADER_WITH_EXTENSIONS(App::Part);
* };
@@ -90,10 +90,10 @@ namespace App {
* SecondExtension::initExtension(this);
* }
* @endcode
*
* From python adding an extension is easier, it must be simply registered to a document object
*
* From python adding an extension is easier, it must be simply registered to a document object
* at object initialisation like done with properties. Note that the special python extension objects
* need to be added, not the c++ objects. Normally the only difference in name is the additional
* need to be added, not the c++ objects. Normally the only difference in name is the additional
* "Python" at the end of the extension name.
* @code{.py}
* class Test():
@@ -101,14 +101,14 @@ namespace App {
* registerExtension("App::FirstExtensionPython", self)
* registerExtension("App::SecondExtensionPython", self)
* @endcode
*
*
* Extensions can provide methods that should be overridden by the extended object for customisation
* of the extension behaviour. In c++ this is as simple as overriding the provided virtual functions.
* In python a class method must be provided which has the same name as the method to override. This
* method must not necessarily be in the object that is extended, it must be in the object which is
* provided to the "registerExtension" call as second argument. This second argument is used as a
* proxy and enqueired if the method to override exists in this proxy before calling it.
*
* In python a class method must be provided which has the same name as the method to override. This
* method must not necessarily be in the object that is extended, it must be in the object which is
* provided to the "registerExtension" call as second argument. This second argument is used as a
* proxy and enqueired if the method to override exists in this proxy before calling it.
*
* For information on howto create extension see the documentation of Extension
*/
class AppExport ExtensionContainer : public App::PropertyContainer
@@ -117,7 +117,7 @@ class AppExport ExtensionContainer : public App::PropertyContainer
TYPESYSTEM_HEADER_WITH_OVERRIDE();
public:
typedef std::map<Base::Type, App::Extension*>::iterator ExtensionIterator;
ExtensionContainer();
@@ -127,31 +127,31 @@ public:
bool hasExtension(Base::Type, bool derived=true) const; //returns first of type (or derived from if set to true) and throws otherwise
bool hasExtension(const std::string& name) const; //this version does not check derived classes
bool hasExtensions() const;
App::Extension* getExtension(Base::Type, bool derived = true, bool no_except=false) const;
App::Extension* getExtension(Base::Type, bool derived = true, bool no_except=false) const;
App::Extension* getExtension(const std::string& name) const; //this version does not check derived classes
//returns first of type (or derived from) and throws otherwise
template<typename ExtensionT>
ExtensionT* getExtensionByType(bool no_except=false, bool derived=true) const {
return static_cast<ExtensionT*>(getExtension(ExtensionT::getExtensionClassTypeId(),derived,no_except));
}
//get all extensions which have the given base class
std::vector<Extension*> getExtensionsDerivedFrom(Base::Type type) const;
template<typename ExtensionT>
std::vector<ExtensionT*> getExtensionsDerivedFromType() const {
std::vector<ExtensionT*> typevec;
for(auto entry : _extensions) {
for(auto entry : _extensions) {
if(entry.first.isDerivedFrom(ExtensionT::getExtensionClassTypeId()))
typevec.push_back(static_cast<ExtensionT*>(entry.second));
}
return typevec;
}
ExtensionIterator extensionBegin() {return _extensions.begin();};
ExtensionIterator extensionEnd() {return _extensions.end();};
ExtensionIterator extensionBegin() {return _extensions.begin();}
ExtensionIterator extensionEnd() {return _extensions.end();}
/** @name Access properties */
//@{
/// find a property by its name
@@ -176,17 +176,17 @@ public:
/// get the Group of a named Property
virtual const char* getPropertyDocumentation(const char *name) const override;
//@}
virtual void onChanged(const Property*) override;
virtual void Save(Base::Writer& writer) const override;
virtual void Restore(Base::XMLReader& reader) override;
//those methods save/restore the dynamic extensions without handling properties, which is something
//done by the default Save/Restore methods.
void saveExtensions(Base::Writer& writer) const;
void restoreExtensions(Base::XMLReader& reader);
private:
//stored extensions
std::map<Base::Type, App::Extension*> _extensions;