FeaturePython methods: Difference between revisions

From FreeCAD Documentation
(Add initial Determining Available Python Methods section.)
(Removed 'in progress'.)
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<languages/>
<languages/>
<translate>

</translate>
{{TOCright}}
<translate>
<translate>


Line 7: Line 11:
This page serves as a reference for the available overridable methods on [[FeaturePython Objects]] or [[Scripted objects]].
This page serves as a reference for the available overridable methods on [[FeaturePython Objects]] or [[Scripted objects]].


==Reference== <!--T:3-->
==Primary reference== <!--T:3-->
The below methods account for ~99% of the use-cases power-users may have for Python proxy classes.


<!--T:4-->
<!--T:8-->
{| class="wikitable" cellpadding="5px" width="100%"
{| class="wikitable" cellpadding="5px" width="100%"
|style="width:25%" | {{incode|execute(self, obj)}}
|style="width:25%" | {{incode|execute(self, obj)}}
Line 28: Line 33:
|}
|}


<!--T:5-->
<!--T:9-->
It is not uncommon to encounter a situation where the Python callbacks are not being triggered as they should. Beginners in this area can rest assured that the FeaturePython callback system is not fragile or broken. Invariably when callbacks fail to run it is because a reference is lost or undefined in the underlying code. If, however, callbacks appear to be breaking with no explanation, providing object/proxy references in the {{incode|onDocumentRestored()}} callback (as noted in the first table above) may alleviate these problems. Until you are comfortable with the callback system, it may be useful to add print statements in each callback to print messages to the console during development.
It is not uncommon to encounter a situation where the Python callbacks are not being triggered as they should. Beginners in this area can rest assured that the FeaturePython callback system is not fragile or broken. Invariably when callbacks fail to run it is because a reference is lost or undefined in the underlying code. If, however, callbacks appear to be breaking with no explanation, providing object/proxy references in the {{incode|onDocumentRestored()}} callback (as noted in the first table above) may alleviate these problems. Until you are comfortable with the callback system, it may be useful to add print statements in each callback to print messages to the console during development.


==Additional methods== <!--T:10-->
==Determining Available Python Methods==
The below methods are for '''advanced''' usage of Python proxy classes and you won't have a need for them most of the time.

<!--T:11-->
* mustExecute
* getViewProviderName
* getSubObject
* getSubObjects
* getLinkedObject
* hasChildElement
* isElementVisible
* canLinkProperties
* allowDuplicateLabel
* redirectSubName
* canLoadPartial
* onBeforeChangeLabel

==Determining available Python methods== <!--T:12-->
Within the [https://github.com/FreeCAD/FreeCAD/blob/76e74294894bbce46d006e149315c6274d206278/src/App/FeaturePython.h#L161-L351 FeaturePython Template Class] exists various <code>imp-><method name>()</code> calls.
Within the [https://github.com/FreeCAD/FreeCAD/blob/76e74294894bbce46d006e149315c6274d206278/src/App/FeaturePython.h#L161-L351 FeaturePython Template Class] exists various <code>imp-><method name>()</code> calls.


<!--T:13-->
Each of these correspond to an available bound Python method.
Each of these correspond to an available bound Python method.


<!--T:14-->
For example, <code>imp->execute()</code> [https://github.com/FreeCAD/FreeCAD/blob/76e74294894bbce46d006e149315c6274d206278/src/App/FeaturePython.h#L193 on line 193] means the <code>execute</code> method is available.
For example, <code>imp->execute()</code> [https://github.com/FreeCAD/FreeCAD/blob/76e74294894bbce46d006e149315c6274d206278/src/App/FeaturePython.h#L193 on line 193] means the <code>execute</code> method is available.


==See Also== <!--T:6-->
<!--T:15-->
Note, <code>getPyObject()</code> and <code>init()</code> are special-cases and don't follow the above heuristic.

==See also== <!--T:6-->


<!--T:7-->
<!--T:7-->
Line 44: Line 71:
* [https://github.com/FreeCAD/FreeCAD/blob/76e74294894bbce46d006e149315c6274d206278/src/App/FeaturePython.h#L167 FreeCAD GitHub: FeaturePythonT template class]
* [https://github.com/FreeCAD/FreeCAD/blob/76e74294894bbce46d006e149315c6274d206278/src/App/FeaturePython.h#L167 FreeCAD GitHub: FeaturePythonT template class]
* [https://forum.freecadweb.org/viewtopic.php?f=22&t=49194 FreeCAD Forum Discussion: Scripted Objects Complete Method Reference]
* [https://forum.freecadweb.org/viewtopic.php?f=22&t=49194 FreeCAD Forum Discussion: Scripted Objects Complete Method Reference]



</translate>
</translate>

Revision as of 14:32, 20 August 2020

Introduction

This page serves as a reference for the available overridable methods on FeaturePython Objects or Scripted objects.

Primary reference

The below methods account for ~99% of the use-cases power-users may have for Python proxy classes.

execute(self, obj) Called during document recomputes Do not call recompute() from this method (or any method called from execute()) as this causes a nested recompute.
onBeforeChange(self, obj, prop) Called before a property value is changed prop is the name of the property to be changed, not the property object itself. Property changes cannot be cancelled. Previous / next property values are not simultaneously available for comparison.
onChanged(self, obj, prop) Called after a property is changed prop is the name of the property to be changed, not the property object itself.
onDocumentRestored(self, obj) Called after a document is restored or a FeaturePython object is copied. Occasionally, references to the FeaturePython object from the class, or the class from the FeaturePython object may be broken, as the class __init__() method is not called when the object is reconstructed. Adding self.Object = obj or obj.Proxy = self often solves these issues.

It is not uncommon to encounter a situation where the Python callbacks are not being triggered as they should. Beginners in this area can rest assured that the FeaturePython callback system is not fragile or broken. Invariably when callbacks fail to run it is because a reference is lost or undefined in the underlying code. If, however, callbacks appear to be breaking with no explanation, providing object/proxy references in the onDocumentRestored() callback (as noted in the first table above) may alleviate these problems. Until you are comfortable with the callback system, it may be useful to add print statements in each callback to print messages to the console during development.

Additional methods

The below methods are for advanced usage of Python proxy classes and you won't have a need for them most of the time.

  • mustExecute
  • getViewProviderName
  • getSubObject
  • getSubObjects
  • getLinkedObject
  • hasChildElement
  • isElementVisible
  • canLinkProperties
  • allowDuplicateLabel
  • redirectSubName
  • canLoadPartial
  • onBeforeChangeLabel

Determining available Python methods

Within the FeaturePython Template Class exists various imp-><method name>() calls.

Each of these correspond to an available bound Python method.

For example, imp->execute() on line 193 means the execute method is available.

Note, getPyObject() and init() are special-cases and don't follow the above heuristic.

See also