414 lines
17 KiB
C++
414 lines
17 KiB
C++
/***************************************************************************
|
|
* Copyright (c) 2016 Stefan Tröger <stefantroeger@gmx.net> *
|
|
* *
|
|
* This file is part of the FreeCAD CAx development system. *
|
|
* *
|
|
* This library is free software; you can redistribute it and/or *
|
|
* modify it under the terms of the GNU Library General Public *
|
|
* License as published by the Free Software Foundation; either *
|
|
* version 2 of the License, or (at your option) any later version. *
|
|
* *
|
|
* This library is distributed in the hope that it will be useful, *
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
|
|
* GNU Library General Public License for more details. *
|
|
* *
|
|
* You should have received a copy of the GNU Library General Public *
|
|
* License along with this library; see the file COPYING.LIB. If not, *
|
|
* write to the Free Software Foundation, Inc., 59 Temple Place, *
|
|
* Suite 330, Boston, MA 02111-1307, USA *
|
|
* *
|
|
***************************************************************************/
|
|
|
|
|
|
#ifndef APP_EXTENSION_H
|
|
#define APP_EXTENSION_H
|
|
|
|
#include "PropertyContainer.h"
|
|
#include "PropertyPythonObject.h"
|
|
#include "ExtensionContainer.h"
|
|
#include "Base/Interpreter.h"
|
|
#include <CXX/Objects.hxx>
|
|
|
|
namespace App {
|
|
|
|
class ExtensionContainer;
|
|
|
|
/// define Extension types
|
|
#define EXTENSION_TYPESYSTEM_HEADER() \
|
|
public: \
|
|
static Base::Type getExtensionClassTypeId(void); \
|
|
virtual Base::Type getExtensionTypeId(void) const; \
|
|
static void init(void);\
|
|
static void *create(void);\
|
|
private: \
|
|
static Base::Type classTypeId
|
|
|
|
/// Like EXTENSION_TYPESYSTEM_HEADER, with getExtensionTypeId declared override
|
|
#define EXTENSION_TYPESYSTEM_HEADER_WITH_OVERRIDE() \
|
|
public: \
|
|
static Base::Type getExtensionClassTypeId(void); \
|
|
virtual Base::Type getExtensionTypeId(void) const override; \
|
|
static void init(void);\
|
|
static void *create(void);\
|
|
private: \
|
|
static Base::Type classTypeId
|
|
|
|
/// define to implement a subclass of Base::BaseClass
|
|
#define EXTENSION_TYPESYSTEM_SOURCE_P(_class_) \
|
|
Base::Type _class_::getExtensionClassTypeId(void) { return _class_::classTypeId; } \
|
|
Base::Type _class_::getExtensionTypeId(void) const { return _class_::classTypeId; } \
|
|
Base::Type _class_::classTypeId = Base::Type::badType(); \
|
|
void * _class_::create(void){\
|
|
return new _class_ ();\
|
|
}
|
|
|
|
/// define to implement a subclass of Base::BaseClass
|
|
#define EXTENSION_TYPESYSTEM_SOURCE_ABSTRACT_P(_class_) \
|
|
Base::Type _class_::getExtensionClassTypeId(void) { return _class_::classTypeId; } \
|
|
Base::Type _class_::getExtensionTypeId(void) const { return _class_::classTypeId; } \
|
|
Base::Type _class_::classTypeId = Base::Type::badType(); \
|
|
void * _class_::create(void){return 0;}
|
|
|
|
/// define to implement a subclass of Base::BaseClass
|
|
#define EXTENSION_TYPESYSTEM_SOURCE(_class_, _parentclass_) \
|
|
EXTENSION_TYPESYSTEM_SOURCE_P(_class_)\
|
|
void _class_::init(void){\
|
|
initExtensionSubclass(_class_::classTypeId, #_class_ , #_parentclass_, &(_class_::create) ); \
|
|
}
|
|
|
|
#define EXTENSION_TYPESYSTEM_SOURCE_TEMPLATE(_class_) \
|
|
template<> Base::Type _class_::classTypeId = Base::Type::badType(); \
|
|
template<> Base::Type _class_::getExtensionClassTypeId(void) { return _class_::classTypeId; } \
|
|
template<> Base::Type _class_::getExtensionTypeId(void) const { return _class_::classTypeId; } \
|
|
template<> void * _class_::create(void){\
|
|
return new _class_ ();\
|
|
}
|
|
|
|
// init property stuff
|
|
#define EXTENSION_PROPERTY_HEADER(_class_) \
|
|
EXTENSION_TYPESYSTEM_HEADER(); \
|
|
protected: \
|
|
static const App::PropertyData * extensionGetPropertyDataPtr(void); \
|
|
virtual const App::PropertyData &extensionGetPropertyData(void) const; \
|
|
private: \
|
|
static App::PropertyData propertyData
|
|
|
|
/// Like EXTENSION_PROPERTY_HEADER, but with override declarations.
|
|
#define EXTENSION_PROPERTY_HEADER_WITH_OVERRIDE(_class_) \
|
|
EXTENSION_TYPESYSTEM_HEADER_WITH_OVERRIDE(); \
|
|
protected: \
|
|
static const App::PropertyData * extensionGetPropertyDataPtr(void); \
|
|
virtual const App::PropertyData &extensionGetPropertyData(void) const override; \
|
|
private: \
|
|
static App::PropertyData propertyData
|
|
|
|
#define EXTENSION_PROPERTY_SOURCE(_class_, _parentclass_) \
|
|
EXTENSION_TYPESYSTEM_SOURCE_P(_class_)\
|
|
const App::PropertyData * _class_::extensionGetPropertyDataPtr(void){return &propertyData;} \
|
|
const App::PropertyData & _class_::extensionGetPropertyData(void) const{return propertyData;} \
|
|
App::PropertyData _class_::propertyData; \
|
|
void _class_::init(void){\
|
|
initExtensionSubclass(_class_::classTypeId, #_class_ , #_parentclass_, &(_class_::create) ); \
|
|
_class_::propertyData.parentPropertyData = _parentclass_::extensionGetPropertyDataPtr();\
|
|
}
|
|
|
|
#define EXTENSION_PROPERTY_SOURCE_TEMPLATE(_class_, _parentclass_) \
|
|
EXTENSION_TYPESYSTEM_SOURCE_TEMPLATE(_class_)\
|
|
template<> App::PropertyData _class_::propertyData = App::PropertyData(); \
|
|
template<> const App::PropertyData * _class_::extensionGetPropertyDataPtr(void){return &propertyData;} \
|
|
template<> const App::PropertyData & _class_::extensionGetPropertyData(void) const{return propertyData;} \
|
|
template<> void _class_::init(void){\
|
|
initExtensionSubclass(_class_::classTypeId, #_class_ , #_parentclass_, &(_class_::create) ); \
|
|
_class_::propertyData.parentPropertyData = _parentclass_::extensionGetPropertyDataPtr();\
|
|
}
|
|
|
|
/**
|
|
* @brief Base class for all extension that can be added to a DocumentObject
|
|
*
|
|
* For general documentation on why extension system exists and how to use it see the ExtensionContainer
|
|
* documentation. Following is a description howto create custom extensions.
|
|
*
|
|
* Extensions are like every other FreeCAD object and based on properties. All information storage
|
|
* and persistence should be achieved by use of those. Additional any number of methods can be
|
|
* added to provide functionality around the properties. There are 3 small difference to normal objects:
|
|
* 1. They must be derived from Extension class
|
|
* 2. Properties must be handled with special extension macros
|
|
* 3. Extensions must be initialised
|
|
* This works as simple as
|
|
* @code
|
|
* class MyExtension : public Extension {
|
|
* EXTENSION_PROPERTY_HEADER(MyExtension);
|
|
* PropertyInt MyProp;
|
|
* virtual bool overridableMethod(DocumentObject* obj) {};
|
|
* };
|
|
*
|
|
* EXTENSION_PROPERTY_SOURCE(App::MyExtension, App::Extension)
|
|
* MyExtension::MyExtension() {
|
|
*
|
|
* EXTENSION_ADD_PROPERTY(MyProp, (0)) *
|
|
* initExtension(MyExtension::getExtensionClassTypeId());
|
|
* }
|
|
* typedef ExtensionPythonT<MyExtension> MyExtensionPython;
|
|
* @endcode
|
|
*
|
|
* The special python extension type created above is important, as only those python extensions
|
|
* can be added to an object from python. It does not work to add the c++ version directly there.
|
|
*
|
|
* Note that every method of the extension becomes part of the extended object when added from c++.
|
|
* This means one should carefully design the API and make only necessary methods public or protected.
|
|
* Every internal method should be private.
|
|
*
|
|
* The automatic availability of methods in the class does not hold for the python interface, only
|
|
* for c++ classes. This is like every where else in FreeCAD, there is no automatic creation of python
|
|
* API from c++ classes. Hence the extension creator must also create a custom python object of its
|
|
* extension, which works exactly like the normal FreeCAD python object workflow. There is nothing
|
|
* special at all for extension python objects, the normal xml + imp.cpp approach is used. It must
|
|
* only be taken care that the objects father is the correct extension base class. Of course also
|
|
* make sure your extension returns the correct python object in its "getPyObject" call.
|
|
* Every method you create in the extensions python will be later added to an extended object. This
|
|
* happens automatically for both, c++ and python extension, if "getPyObject" returns the correct
|
|
* python object. No extra work needs to be done.
|
|
*
|
|
* A special case that needs to be handled for extensions is the possibility of overridden methods.
|
|
* Often it is desired to customise extension behaviour by allowing the user to override methods
|
|
* provided by the extension. On c++ side this is trivial, such methods are simply marked as "virtual"
|
|
* and can than be overridden in any derived class. This is more involved for the python interface and
|
|
* here special care needs to be taken.
|
|
*
|
|
* As already seen above one needs to create a special ExtensionPythonT<> object for extension from
|
|
* python. This is done exactly for the purpose of allowing to have overridable methods. The
|
|
* ExtensionPythonT wrapper adds a proxy property which holds a PyObject which itself will contain
|
|
* the implementations for the overridden methods. This design is equal to the ObjectPythonT<> design
|
|
* of normal document objects.
|
|
* As this wrapper inherits the c++ extension class it can also override the virtual functions the
|
|
* user designed to be overridden. What it should do at a call of the virtual method is to check if
|
|
* this method is implemented in the proxy object and if so call it, and if not call the normal
|
|
* c++ version. It is the extensions creators responsibility to implement this check and call behaviour
|
|
* for every overridable method.
|
|
* This is done by creating a custom wrapper just like ExtensionPythonT<> and overriding all virtual
|
|
* methods.
|
|
* @code
|
|
* template<typename ExtensionT> class MyExtensionPythonT : public ExtensionT {
|
|
* public:
|
|
*
|
|
* MyExtensionPythonT() {}
|
|
* virtual ~MyExtensionPythonT() {}
|
|
*
|
|
* virtual bool overridableMethod(DocumentObject* obj) override {
|
|
* Py::Object pyobj = Py::asObject(obj->getPyObject());
|
|
* EXTENSION_PROXY_ONEARG(allowObject, pyobj);
|
|
*
|
|
* if(result.isNone())
|
|
* ExtensionT::allowObject(obj);
|
|
*
|
|
* if(result.isBoolean())
|
|
* return result.isTrue();
|
|
*
|
|
* return false;
|
|
* };
|
|
* };
|
|
* @endcode
|
|
* @Note As seen in the code there are multiple helper macros to ease the repetitive work of querying
|
|
* and calling methods of the proxy object. See the macro documentation for how to use them.
|
|
*
|
|
* To ensure that your wrapper is used when a extension is created from python the extension type must
|
|
* be exposed as follows:
|
|
* @code
|
|
* typedef ExtensionPythonT<MyExtensionPythonT<MyExtension>> MyExtensionPython;
|
|
* @endcode
|
|
*
|
|
* This boilerplate is absolutely necessary to allow overridable methods in python and it is the
|
|
* extension creator's responsibility to ensure full implementation.
|
|
*
|
|
*/
|
|
class AppExport Extension
|
|
{
|
|
|
|
//The cass does not have properties itself, but it is important to provide the property access
|
|
//functions. see cpp file for details
|
|
EXTENSION_PROPERTY_HEADER(App::Extension);
|
|
|
|
public:
|
|
|
|
Extension();
|
|
virtual ~Extension();
|
|
|
|
virtual void initExtension(App::ExtensionContainer* obj);
|
|
|
|
App::ExtensionContainer* getExtendedContainer() {return m_base;}
|
|
const App::ExtensionContainer* getExtendedContainer() const {return m_base;}
|
|
|
|
//get extension name without namespace
|
|
std::string name() const;
|
|
|
|
bool isPythonExtension() {return m_isPythonExtension;}
|
|
|
|
virtual PyObject* getExtensionPyObject(void);
|
|
|
|
|
|
/** @name Access properties */
|
|
//@{
|
|
/// find a property by its name
|
|
virtual Property *extensionGetPropertyByName(const char* name) const;
|
|
/// get the name of a property
|
|
virtual const char* extensionGetPropertyName(const Property* prop) const;
|
|
/// get all properties of the class (including properties of the parent)
|
|
virtual void extensionGetPropertyMap(std::map<std::string,Property*> &Map) const;
|
|
/// get all properties of the class (including properties of the parent)
|
|
virtual void extensionGetPropertyList(std::vector<Property*> &List) const;
|
|
|
|
/// get the Type of a Property
|
|
virtual short extensionGetPropertyType(const Property* prop) const;
|
|
/// get the Type of a named Property
|
|
virtual short extensionGetPropertyType(const char *name) const;
|
|
/// get the Group of a Property
|
|
virtual const char* extensionGetPropertyGroup(const Property* prop) const;
|
|
/// get the Group of a named Property
|
|
virtual const char* extensionGetPropertyGroup(const char *name) const;
|
|
/// get the Group of a Property
|
|
virtual const char* extensionGetPropertyDocumentation(const Property* prop) const;
|
|
/// get the Group of a named Property
|
|
virtual const char* extensionGetPropertyDocumentation(const char *name) const;
|
|
//@}
|
|
|
|
/** @name Persistence */
|
|
//@{
|
|
virtual void extensionSave(Base::Writer&) const {}
|
|
virtual void extensionRestore(Base::XMLReader&) {}
|
|
//@}
|
|
|
|
/** @name TypeHandling */
|
|
//@{
|
|
bool extensionIsDerivedFrom(const Base::Type type) const {return getExtensionTypeId().isDerivedFrom(type);}
|
|
protected:
|
|
static void initExtensionSubclass(Base::Type &toInit,const char* ClassName, const char *ParentName,
|
|
Base::Type::instantiationMethod method=0);
|
|
//@}
|
|
|
|
virtual void extensionOnChanged(const Property* p) {(void)(p);}
|
|
|
|
friend class App::ExtensionContainer;
|
|
|
|
protected:
|
|
void initExtensionType(Base::Type type);
|
|
bool m_isPythonExtension = false;
|
|
Py::Object ExtensionPythonObject;
|
|
|
|
private:
|
|
Base::Type m_extensionType;
|
|
App::ExtensionContainer* m_base = nullptr;
|
|
};
|
|
|
|
// Property define
|
|
#define _EXTENSION_ADD_PROPERTY(_name, _prop_, _defaultval_) \
|
|
do { \
|
|
this->_prop_.setValue _defaultval_;\
|
|
propertyData.addProperty(static_cast<App::Extension*>(this), _name, &this->_prop_); \
|
|
} while (0)
|
|
|
|
|
|
#define EXTENSION_ADD_PROPERTY(_prop_, _defaultval_) \
|
|
_EXTENSION_ADD_PROPERTY(#_prop_, _prop_, _defaultval_)
|
|
|
|
#define _EXTENSION_ADD_PROPERTY_TYPE(_name, _prop_, _defaultval_, _group_,_type_,_Docu_) \
|
|
do { \
|
|
this->_prop_.setValue _defaultval_;\
|
|
propertyData.addProperty(static_cast<App::Extension*>(this), _name, &this->_prop_, (_group_),(_type_),(_Docu_)); \
|
|
} while (0)
|
|
|
|
#define EXTENSION_ADD_PROPERTY_TYPE(_prop_, _defaultval_, _group_,_type_,_Docu_) \
|
|
_EXTENSION_ADD_PROPERTY_TYPE(#_prop_, _prop_, _defaultval_, _group_,_type_,_Docu_)
|
|
|
|
|
|
/**
|
|
* Generic Python extension class which allows every extension derived
|
|
* class to behave as a Python extension -- simply by subclassing.
|
|
*/
|
|
template <class ExtensionT>
|
|
class ExtensionPythonT : public ExtensionT
|
|
{
|
|
EXTENSION_PROPERTY_HEADER(App::ExtensionPythonT<ExtensionT>);
|
|
|
|
public:
|
|
typedef ExtensionT Inherited;
|
|
|
|
ExtensionPythonT() {
|
|
ExtensionT::m_isPythonExtension = true;
|
|
ExtensionT::initExtensionType(ExtensionPythonT::getExtensionClassTypeId());
|
|
|
|
EXTENSION_ADD_PROPERTY(ExtensionProxy,(Py::Object()));
|
|
}
|
|
virtual ~ExtensionPythonT() {
|
|
}
|
|
|
|
PropertyPythonObject ExtensionProxy;
|
|
};
|
|
|
|
typedef ExtensionPythonT<App::Extension> ExtensionPython;
|
|
|
|
// Helper macros to define python extensions
|
|
#define EXTENSION_PROXY_FIRST(function) \
|
|
Base::PyGILStateLocker lock;\
|
|
Py::Object result;\
|
|
try {\
|
|
Property* proxy = this->extensionGetPropertyByName("ExtensionProxy");\
|
|
if (proxy && proxy->getTypeId() == PropertyPythonObject::getClassTypeId()) {\
|
|
Py::Object feature = static_cast<PropertyPythonObject*>(proxy)->getValue();\
|
|
if (feature.hasAttr(std::string("function"))) {\
|
|
if (feature.hasAttr("__object__")) {\
|
|
Py::Callable method(feature.getAttr(std::string("function")));
|
|
|
|
|
|
|
|
|
|
#define EXTENSION_PROXY_SECOND(function)\
|
|
result = method.apply(args);\
|
|
}\
|
|
else {\
|
|
Py::Callable method(feature.getAttr(std::string("function")));
|
|
|
|
#define EXTENSION_PROXY_THIRD()\
|
|
result = method.apply(args);\
|
|
}\
|
|
}\
|
|
}\
|
|
}\
|
|
catch (Py::Exception&) {\
|
|
Base::PyException e;\
|
|
e.ReportException();\
|
|
}
|
|
|
|
#define EXTENSION_PROXY_NOARG(function)\
|
|
EXTENSION_PROXY_FIRST(function) \
|
|
Py::Tuple args;\
|
|
EXTENSION_PROXY_SECOND(function) \
|
|
Py::Tuple args(1);\
|
|
args.setItem(0, Py::Object(this->getExtensionPyObject(), true));\
|
|
EXTENSION_PROXY_THIRD()
|
|
|
|
#define EXTENSION_PROXY_ONEARG(function, arg)\
|
|
EXTENSION_PROXY_FIRST(function) \
|
|
Py::Tuple args;\
|
|
args.setItem(0, arg); \
|
|
EXTENSION_PROXY_SECOND(function) \
|
|
Py::Tuple args(2);\
|
|
args.setItem(0, Py::Object(this->getExtensionPyObject(), true));\
|
|
args.setItem(1, arg); \
|
|
EXTENSION_PROXY_THIRD()
|
|
|
|
#define EXTENSION_PYTHON_OVERRIDE_VOID_NOARGS(function)\
|
|
virtual void function() override {\
|
|
EXTENSION_PROXY_NOARGS(function)\
|
|
};
|
|
|
|
#define EXTENSION_PYTHON_OVERRIDE_OBJECT_NOARGS(function)\
|
|
virtual PyObject* function() override {\
|
|
EXTENSION_PROXY_NOARGS(function)\
|
|
return res.ptr();\
|
|
};
|
|
|
|
} //App
|
|
|
|
#endif // APP_EXTENSION_H
|