App::ExtensionContainer Class Reference

Container which can hold extensions. More...

#include <ExtensionContainer.h>

Public Types

typedef std::map< Base::Type, App::Extension * >::iterator ExtensionIterator
 

Public Member Functions

ExtensionIterator extensionBegin ()
 
 ExtensionContainer ()
 
ExtensionIterator extensionEnd ()
 
App::ExtensiongetExtension (Base::Type, bool derived=true, bool no_except=false) const
 
App::ExtensiongetExtension (const std::string &name) const
 
template<typename ExtensionT >
ExtensionTgetExtensionByType (bool no_except=false, bool derived=true) const
 
std::vector< Extension * > getExtensionsDerivedFrom (Base::Type type) const
 
template<typename ExtensionT >
std::vector< ExtensionT * > getExtensionsDerivedFromType () const
 
bool hasExtension (Base::Type, bool derived=true) const
 
bool hasExtension (const std::string &name) const
 
bool hasExtensions () const
 
void registerExtension (Base::Type extension, App::Extension *ext)
 
virtual ~ExtensionContainer ()
 
Access properties
virtual PropertygetPropertyByName (const char *name) const override
 find a property by its name More...
 
virtual const char * getPropertyName (const Property *prop) const override
 get the name of a property More...
 
virtual void getPropertyMap (std::map< std::string, Property * > &Map) const override
 get all properties of the class (including properties of the parent) More...
 
virtual void getPropertyList (std::vector< Property * > &List) const override
 get all properties of the class (including properties of the parent) More...
 
virtual short getPropertyType (const Property *prop) const override
 get the Type of a Property More...
 
virtual short getPropertyType (const char *name) const override
 get the Type of a named Property More...
 
virtual const char * getPropertyGroup (const Property *prop) const override
 get the Group of a Property More...
 
virtual const char * getPropertyGroup (const char *name) const override
 get the Group of a named Property More...
 
virtual const char * getPropertyDocumentation (const Property *prop) const override
 get the Group of a Property More...
 
virtual const char * getPropertyDocumentation (const char *name) const override
 get the Group of a named Property More...
 
virtual void onChanged (const Property *) override
 get called by the container when a property has changed More...
 
virtual void Save (Base::Writer &writer) const override
 This method is used to save properties to an XML document. More...
 
virtual void Restore (Base::XMLReader &reader) override
 This method is used to restore properties from an XML document. More...
 
void saveExtensions (Base::Writer &writer) const
 
void restoreExtensions (Base::XMLReader &reader)
 
- Public Member Functions inherited from App::PropertyContainer
virtual App::PropertyaddDynamicProperty (const char *type, const char *name=nullptr, const char *group=nullptr, const char *doc=nullptr, short attr=0, bool ro=false, bool hidden=false)
 
bool changeDynamicProperty (const Property *prop, const char *group, const char *doc)
 
virtual void editProperty (const char *)
 
virtual App::PropertygetDynamicPropertyByName (const char *name) const
 
DynamicProperty::PropData getDynamicPropertyData (const Property *prop) const
 
virtual std::vector< std::string > getDynamicPropertyNames () const
 
virtual std::string getFullName () const
 
virtual unsigned int getMemSize (void) const
 This method is used to get the size of objects It is not meant to have the exact size, it is more or less an estimation which runs fast! Is it two bytes or a GB? More...
 
virtual PropertygetPropertyByName (const char *name) const
 find a property by its name More...
 
virtual const char * getPropertyDocumentation (const char *name) const
 get the Group of a named Property More...
 
virtual const char * getPropertyDocumentation (const Property *prop) const
 get the Group of a Property More...
 
virtual const char * getPropertyGroup (const char *name) const
 get the Group of a named Property More...
 
virtual const char * getPropertyGroup (const Property *prop) const
 get the Group of a Property More...
 
virtual void getPropertyList (std::vector< Property * > &List) const
 get all properties of the class (including properties of the parent) More...
 
virtual void getPropertyMap (std::map< std::string, Property * > &Map) const
 get all properties of the class (including properties of the parent) More...
 
virtual const char * getPropertyName (const Property *prop) const
 get the name of a property More...
 
virtual void getPropertyNamedList (std::vector< std::pair< const char *, Property * > > &List) const
 get all properties with their names, may contain duplicates and aliases More...
 
const char * getPropertyPrefix () const
 
virtual short getPropertyType (const char *name) const
 get the Type of a named Property More...
 
virtual short getPropertyType (const Property *prop) const
 get the Type of a Property More...
 
bool isHidden (const char *name) const
 check if the named property is hidden More...
 
bool isHidden (const Property *prop) const
 check if the property is hidden More...
 
bool isReadOnly (const char *name) const
 check if the named property is read-only More...
 
bool isReadOnly (const Property *prop) const
 check if the property is read-only More...
 
virtual void onPropertyStatusChanged (const Property &prop, unsigned long oldStatus)
 
 PropertyContainer ()
 A constructor. More...
 
virtual bool removeDynamicProperty (const char *name)
 
virtual void Restore (Base::XMLReader &reader)
 This method is used to restore properties from an XML document. More...
 
virtual void Save (Base::Writer &writer) const
 This method is used to save properties to an XML document. More...
 
void setPropertyPrefix (const char *prefix)
 
void setPropertyStatus (unsigned char bit, bool value)
 set the Status bit of all properties at once More...
 
virtual ~PropertyContainer ()
 A destructor. More...
 
- Public Member Functions inherited from Base::Persistence
void dumpToStream (std::ostream &stream, int compression)
 
virtual unsigned int getMemSize () const =0
 This method is used to get the size of objects It is not meant to have the exact size, it is more or less an estimation which runs fast! Is it two bytes or a GB? More...
 
virtual Base::Type getTypeId (void) const
 
virtual void Restore (XMLReader &)=0
 This method is used to restore properties from an XML document. More...
 
virtual void RestoreDocFile (Reader &)
 This method is used to restore large amounts of data from a file In this method you simply stream in your SaveDocFile() saved data. More...
 
void restoreFromStream (std::istream &stream)
 
virtual void Save (Writer &) const =0
 This method is used to save properties to an XML document. More...
 
virtual void SaveDocFile (Writer &) const
 This method is used to save large amounts of data to a binary file. More...
 
- Public Member Functions inherited from Base::BaseClass
 BaseClass ()
 Construction. More...
 
 BaseClass (const BaseClass &)=default
 
virtual PyObjectgetPyObject ()
 This method returns the Python wrapper for a C++ object. More...
 
virtual Type getTypeId () const
 
bool isDerivedFrom (const Type type) const
 
BaseClassoperator= (const BaseClass &)=default
 
virtual void setPyObject (PyObject *)
 
virtual ~BaseClass ()
 Destruction. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from Base::Persistence
static void * create (void)
 
static std::string encodeAttribute (const std::string &)
 Encodes an attribute upon saving. More...
 
static Base::Type getClassTypeId (void)
 
static void init (void)
 
- Static Public Member Functions inherited from Base::BaseClass
static void * create ()
 
static Type getClassTypeId ()
 
static void init ()
 
- Protected Member Functions inherited from App::PropertyContainer
virtual const PropertyDatagetPropertyData (void) const
 
virtual void handleChangedPropertyName (Base::XMLReader &reader, const char *TypeName, const char *PropName)
 PropertyContainer::handleChangedPropertyName is called during restore to possibly fix reading of older versions of this property container. More...
 
virtual void handleChangedPropertyType (Base::XMLReader &reader, const char *TypeName, Property *prop)
 PropertyContainer::handleChangedPropertyType is called during restore to possibly fix reading of older versions of the property container. More...
 
virtual void onBeforeChange (const Property *)
 get called before the value is changed More...
 
virtual void onChanged (const Property *)
 get called by the container when a property has changed More...
 
- Static Protected Member Functions inherited from App::PropertyContainer
static const PropertyDatagetPropertyDataPtr (void)
 
- Static Protected Member Functions inherited from Base::BaseClass
static void initSubclass (Base::Type &toInit, const char *ClassName, const char *ParentName, Type::instantiationMethod method=nullptr)
 
- Protected Attributes inherited from App::PropertyContainer
DynamicProperty dynamicProps
 

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 is 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

Member Typedef Documentation

◆ ExtensionIterator

Constructor & Destructor Documentation

◆ ExtensionContainer()

ExtensionContainer::ExtensionContainer ( )

◆ ~ExtensionContainer()

ExtensionContainer::~ExtensionContainer ( )
virtual

Member Function Documentation

◆ extensionBegin()

ExtensionIterator App::ExtensionContainer::extensionBegin ( )

◆ extensionEnd()

ExtensionIterator App::ExtensionContainer::extensionEnd ( )

◆ getExtension() [1/2]

Extension * ExtensionContainer::getExtension ( Base::Type  t,
bool  derived = true,
bool  no_except = false 
) const

Referenced by restoreExtensions().

◆ getExtension() [2/2]

Extension * ExtensionContainer::getExtension ( const std::string &  name) const

◆ getExtensionByType()

◆ getExtensionsDerivedFrom()

std::vector< Extension * > ExtensionContainer::getExtensionsDerivedFrom ( Base::Type  type) const

◆ getExtensionsDerivedFromType()

template<typename ExtensionT >
std::vector< ExtensionT * > App::ExtensionContainer::getExtensionsDerivedFromType ( ) const

◆ getPropertyByName()

Property * ExtensionContainer::getPropertyByName ( const char *  name) const
overridevirtual

find a property by its name

Reimplemented from App::PropertyContainer.

Reimplemented in Spreadsheet::Sheet, and Gui::ViewProviderLink.

References App::PropertyContainer::getPropertyByName().

Referenced by FemGui::TaskDlgFemConstraintFluidBoundary::accept(), MeshGui::ViewProviderMesh::canHighlightColors(), MeshGui::ViewProviderMeshCurvature::curvatureInfo(), App::FunctionExpression::evalAggregate(), Mesh::HarmonizeNormals::execute(), Mesh::FlipNormals::execute(), Mesh::FixNonManifolds::execute(), Mesh::FixDuplicatedFaces::execute(), Mesh::FixDuplicatedPoints::execute(), Mesh::FixDegenerations::execute(), Mesh::FixDeformations::execute(), Mesh::FixIndices::execute(), Mesh::FillHoles::execute(), Mesh::RemoveComponents::execute(), Mesh::SegmentByMesh::execute(), TechDraw::DrawViewArch::execute(), App::LinkBaseExtension::extensionExecute(), InspectionGui::ViewProviderInspection::getIcon(), TechDraw::DrawProjGroupItem::getLegacyX(), Gui::ViewProviderLink::getPropertyByName(), App::ObjectIdentifier::getPyValue(), Spreadsheet::PropertySheet::getPyValue(), TechDraw::ShapeExtractor::getShapesFromObject(), App::ObjectIdentifier::getValue(), TechDraw::DrawViewPart::getXDirection(), TechDraw::DrawProjGroupItem::getXDirection(), TechDraw::DrawViewSection::getXDirection(), MeshGui::ViewProviderMesh::highlightColors(), InspectionGui::ViewProviderInspection::inspectDistance(), App::RangeExpression::isTouched(), Gui::ViewProviderAnnotationLabel::onChanged(), App::ObjectIdentifier::resolveProperty(), Part::Box::Restore(), InspectionGui::ViewProviderInspection::setDistances(), App::LinkBaseExtension::setupCopyOnChange(), FemGui::TaskFemConstraintFluidBoundary::TaskFemConstraintFluidBoundary(), PartDesignGui::ViewProviderBody::unifyVisualProperty(), PartDesign::SubShapeBinder::update(), and InspectionGui::ViewProviderInspection::updateData().

◆ getPropertyDocumentation() [1/2]

const char * ExtensionContainer::getPropertyDocumentation ( const char *  name) const
overridevirtual

get the Group of a named Property

Reimplemented from App::PropertyContainer.

References App::PropertyContainer::getPropertyDocumentation().

◆ getPropertyDocumentation() [2/2]

const char * ExtensionContainer::getPropertyDocumentation ( const Property prop) const
overridevirtual

get the Group of a Property

Reimplemented from App::PropertyContainer.

References App::PropertyContainer::getPropertyDocumentation().

◆ getPropertyGroup() [1/2]

const char * ExtensionContainer::getPropertyGroup ( const char *  name) const
overridevirtual

get the Group of a named Property

Reimplemented from App::PropertyContainer.

References App::PropertyContainer::getPropertyGroup().

◆ getPropertyGroup() [2/2]

const char * ExtensionContainer::getPropertyGroup ( const Property prop) const
overridevirtual

get the Group of a Property

Reimplemented from App::PropertyContainer.

References App::PropertyContainer::getPropertyGroup().

◆ getPropertyList()

void ExtensionContainer::getPropertyList ( std::vector< Property * > &  List) const
overridevirtual

◆ getPropertyMap()

◆ getPropertyName()

const char * ExtensionContainer::getPropertyName ( const Property prop) const
overridevirtual

◆ getPropertyType() [1/2]

short int ExtensionContainer::getPropertyType ( const char *  name) const
overridevirtual

get the Type of a named Property

Reimplemented from App::PropertyContainer.

References App::PropertyContainer::getPropertyType().

◆ getPropertyType() [2/2]

short int ExtensionContainer::getPropertyType ( const Property prop) const
overridevirtual

get the Type of a Property

Reimplemented from App::PropertyContainer.

References App::PropertyContainer::getPropertyType().

Referenced by Part::Box::Restore().

◆ hasExtension() [1/2]

◆ hasExtension() [2/2]

bool ExtensionContainer::hasExtension ( const std::string &  name) const

◆ hasExtensions()

bool ExtensionContainer::hasExtensions ( ) const

◆ onChanged()

void ExtensionContainer::onChanged ( const Property )
overridevirtual

get called by the container when a property has changed

Reimplemented from App::PropertyContainer.

Reimplemented in App::VRMLObject, FemGui::ViewProviderFemPostPlaneFunction, Part::Circle, Part::Vertex, Part::Line, Part::Ellipse, PartDesignGui::ViewProviderDatumCoordinateSystem, Surface::GeomFillSurface, PartDesign::Chamfer, Sketcher::SketchObject, TechDrawGui::ViewProviderBalloon, TechDrawGui::ViewProviderDimension, TechDrawGui::ViewProviderLeader, TechDrawGui::ViewProviderRichAnno, TechDrawGui::ViewProviderWeld, Gui::ViewProvider, Gui::ViewProviderAnnotation, Gui::ViewProviderAnnotationLabel, Gui::ViewProviderGeometryObject, Gui::ViewProviderMeasureDistance, Gui::ViewProviderOrigin, Gui::ViewProviderOriginFeature, Gui::ViewProviderTextDocument, Drawing::FeatureClip, Drawing::FeaturePage, Drawing::FeatureViewSymbol, Fem::Constraint, Fem::ConstraintBearing, Fem::ConstraintContact, Fem::ConstraintDisplacement, Fem::ConstraintFixed, Fem::ConstraintFluidBoundary, Fem::ConstraintForce, Fem::ConstraintGear, Fem::ConstraintHeatflux, Fem::ConstraintInitialTemperature, Fem::ConstraintPlaneRotation, Fem::ConstraintPressure, Fem::ConstraintPulley, Fem::ConstraintSpring, Fem::ConstraintTemperature, Fem::ConstraintTransform, Fem::FemMeshObject, Fem::FemPostClipFilter, Fem::FemPostDataAlongLineFilter, Fem::FemPostDataAtPointFilter, Fem::FemPostScalarClipFilter, Fem::FemPostWarpVectorFilter, Fem::FemPostCutFilter, Fem::FemPostFunctionProvider, Fem::FemPostPlaneFunction, Fem::FemPostSphereFunction, Fem::FemPostPipeline, FemGui::ViewProviderFemConstraint, FemGui::ViewProviderFemMesh, FemGui::ViewProviderFemPostFunctionProvider, FemGui::ViewProviderFemPostFunction, FemGui::ViewProviderFemPostObject, InspectionGui::ViewProviderInspection, Mesh::Feature, MeshGui::ViewProviderMesh, MeshGui::ViewProviderMeshCurvature, MeshGui::ViewProviderMeshDefects, MeshGui::ViewProviderMeshNode, Part::Mirroring, Part::Box, Part::RuledSurface, Part::Loft, Part::Sweep, Part::Helix, Part::Spiral, Part::Wedge, PartGui::ViewProvider2DObjectGrid, PartGui::ViewProviderCustom, PartGui::ViewProviderPartReference, PartDesign::Line, PartDesign::Plane, PartDesign::FeatureBase, PartDesign::DressUp, PartDesign::Helix, PartDesign::Hole, PartDesign::ProfileBased, PartDesignGui::ViewProviderDatumPoint, Path::Feature, PathGui::ViewProviderPath, Points::Feature, PointsGui::ViewProviderPoints, Robot::Edge2TracObject, Robot::RobotObject, Robot::TrajectoryDressUpObject, Robot::TrajectoryObject, RobotGui::ViewProviderRobotObject, Sandbox::SandboxObject, SketcherGui::ViewProviderCustom, Spreadsheet::Sheet, TechDraw::DrawParametricTemplate, TechDraw::DrawRichAnno, TechDraw::DrawSVGTemplate, TechDraw::DrawTemplate, TechDraw::DrawTile, TechDraw::DrawTileWeld, TechDraw::DrawViewAnnotation, TechDraw::DrawViewClip, TechDraw::DrawViewCollection, TechDraw::DrawViewDimExtent, TechDraw::DrawViewSpreadsheet, TechDraw::DrawWeldSymbol, TechDrawGui::ViewProviderImage, TechDrawGui::ViewProviderProjGroup, TechDrawGui::ViewProviderViewPart, TechDrawGui::ViewProviderViewSection, Gui::ViewProviderDocumentObject, Gui::ViewProviderLink, Gui::ViewProviderPart, Gui::ViewProviderPlacement, Part::BodyBase, Part::Revolution, Part::Feature, Part::Primitive, PartGui::ViewProviderPartExt, PartDesign::Body, PartDesign::Point, PartDesign::Boolean, PartDesign::FeaturePrimitive, PartDesign::ShapeBinder, PartDesign::SubShapeBinder, PartDesignGui::ViewProvider, PartDesignGui::ViewProviderBody, PartDesignGui::ViewProviderBoolean, PartDesignGui::ViewProviderSubShapeBinder, SketcherGui::ViewProviderSketch, Surface::Extend, TechDraw::DrawGeomHatch, TechDraw::DrawHatch, TechDraw::DrawLeaderLine, TechDraw::DrawPage, TechDraw::DrawProjGroup, TechDraw::DrawProjGroupItem, TechDraw::DrawView, TechDraw::DrawViewBalloon, TechDraw::DrawViewDetail, TechDraw::DrawViewDimension, TechDraw::DrawViewImage, TechDraw::DrawViewMulti, TechDraw::DrawViewPart, TechDraw::DrawViewSection, TechDraw::DrawViewSymbol, TechDraw::LandmarkDimension, TechDrawGui::ViewProviderDrawingView, TechDrawGui::ViewProviderGeomHatch, TechDrawGui::ViewProviderHatch, TechDrawGui::ViewProviderPage, TechDrawGui::ViewProviderTemplate, App::MeasureDistance, App::TextDocument, and App::DocumentObject.

References App::PropertyContainer::onChanged().

Referenced by ArchStructure.CommandStructuralSystem::Activated(), draftviewproviders.view_base.ViewProviderDraft::attach(), ArchSite.Compass::buildCoordinates(), draftobjects.wire.Wire::execute(), Gui::ViewProvider::onChanged(), ArchBuildingPart.ViewProviderBuildingPart::updateData(), ArchPanel.ViewProviderPanelCut::updateData(), ArchPanel.ViewProviderPanelSheet::updateData(), draftviewproviders.view_label.ViewProviderLabel::updateData(), draftviewproviders.view_layer.ViewProviderLayer::updateData(), and draftviewproviders.view_wpproxy.ViewProviderWorkingPlaneProxy::updateData().

◆ registerExtension()

void ExtensionContainer::registerExtension ( Base::Type  extension,
App::Extension ext 
)

◆ Restore()

◆ restoreExtensions()

◆ Save()

void ExtensionContainer::Save ( Base::Writer ) const
overridevirtual

This method is used to save properties to an XML document.

A good example you'll find in PropertyStandard.cpp, e.g. the vector:

void PropertyVector::Save (Writer &writer) const
{
writer << writer.ind() << "<PropertyVector valueX=\"" << _cVec.x <<
"\" valueY=\"" << _cVec.y <<
"\" valueZ=\"" << _cVec.z <<"\"/>" << endl;
}

The writer.ind() expression writes the indentation, just for pretty printing of the XML. As you see, the writing of the XML document is not done with a DOM implementation because of performance reasons. Therefore the programmer has to take care that a valid XML document is written. This means closing tags and writing UTF-8.

See also
Base::Writer

Reimplemented from App::PropertyContainer.

Reimplemented in Robot::RobotObject, Sketcher::SketchObject, App::VRMLObject, and App::DocumentObject.

References App::PropertyContainer::Save(), and saveExtensions().

Referenced by Gui::Document::exportObjects().

◆ saveExtensions()


The documentation for this class was generated from the following files: