App::ExtensionContainer Class Reference

#include <App/ExtensionContainer.h>

Detailed Description

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 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, 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 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.

if (object->hasExtension(GroupExtension::getClassTypeId())) {
    App::GroupExtension* group = object->getExtensionByType<GroupExtension>();
    group->hasObject(...); 
}

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 special macros.
2. The extensions need to be initialised in the constructor

Here a working example:

class AppExport Part : public App::DocumentObject, public App::FirstExtension, public App::SecondExtension {
  PROPERTY_HEADER_WITH_EXTENSIONS(App::Part);
};
PROPERTY_SOURCE_WITH_EXTENSIONS(App::Part, App::DocumentObject)
Part::Part(void) {
  FirstExtension::initExtension(this);
  SecondExtension::initExtension(this);
}

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 "Python" at the end of the extension name.

class Test():
  __init(self)__:
    registerExtension("App::FirstExtensionPython", self)
    registerExtension("App::SecondExtensionPython", self)

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.

For information on howto create extension see the documentation of Extension

Public Member Functions
Access properties
virtual Property *	getPropertyByName (const char *name) const override
	find a property by its name
virtual const char *	getPropertyName (const Property *prop) const override
	get the name of a property
virtual void	getPropertyMap (std::map< std::string, Property * > &Map) const override
	get all properties of the class (including properties of the parent)
virtual void	getPropertyList (std::vector< Property * > &List) const override
	get all properties of the class (including properties of the parent)
virtual short	getPropertyType (const Property *prop) const override
	get the Type of a Property
virtual short	getPropertyType (const char *name) const override
	get the Type of a named Property
virtual const char *	getPropertyGroup (const Property *prop) const override
	get the Group of a Property
virtual const char *	getPropertyGroup (const char *name) const override
	get the Group of a named Property
virtual const char *	getPropertyDocumentation (const Property *prop) const override
	get the Group of a Property
virtual const char *	getPropertyDocumentation (const char *name) const override
	get the Group of a named Property
Public Member Functions inherited from App::PropertyContainer
	PropertyContainer ()
virtual	~PropertyContainer ()
void	setPropertyStatus (unsigned char bit, bool value)
	set the Status bit of all properties at once
bool	isReadOnly (const Property *prop) const
	check if the property is read-only
bool	isReadOnly (const char *name) const
	check if the named property is read-only
bool	isHidden (const Property *prop) const
	check if the property is hidden
bool	isHidden (const char *name) const
	check if the named property is hidden
Public Member Functions inherited from Base::Persistence
virtual void	SaveDocFile (Writer &) const
virtual void	RestoreDocFile (Reader &)
Public Member Functions inherited from Base::BaseClass
	BaseClass ()
	Construction.
virtual	~BaseClass ()
	Destruction.

Additional Inherited Members
Static Public Member Functions inherited from Base::Persistence
static std::string	encodeAttribute (const std::string &)
	Encodes an attribute upon saving.
Protected Member Functions inherited from App::PropertyContainer
virtual void	onBeforeChange (const Property *)
	get called before the value is changed