[Wiki Discussion] Scripted Objects Complete Method Reference

Need help, or want to share a macro? Post here!
User avatar
gbroques
Posts: 73
Joined: Thu Jan 23, 2020 3:28 am
Location: St. Louis, Missouri

[Wiki Discussion] Scripted Objects Complete Method Reference

Postby gbroques » Mon Aug 03, 2020 12:30 pm

Within Creating a FeaturePython Box, Part II, there's a nice reference of the available "callbacks" or methods for "trapping events" on custom scripted objects documenting execute, onBeforeChanged, onChanged, and onDocumentRestored. See Trapping Events, and FeaturePython basic callbacks.

I would've expected this table to live in FeaturePython Objects or Scripted Objects. In my opinion, It kind of gets lost in this tutorial-style page when trying to find it again.

Also, this table is a list of "basic callbacks", and I want a complete reference table. Is there corresponding documentation in the auto-generated docs defining which methods we can "hook into" for these classes?

Does anyone have suggestions for improving this?

Maybe a new section in either FeaturePython objects or Scripted objects, or a new page entirely? I might suggest removing this table from the Creating a FeaturePython Box, Part II page, and referencing this new location instead.

Thoughts on this proposal, or different ideas?
vocx wrote: :bell:
vocx
Posts: 5206
Joined: Thu Oct 18, 2018 9:18 pm

Re: [Wiki Discussion] Scripted Objects Complete Method Reference

Postby vocx » Mon Aug 03, 2020 3:43 pm

gbroques wrote:
Mon Aug 03, 2020 12:30 pm
...
Thoughts on this proposal, or different ideas?
I like your proposal. This power user documentation really needs to be rewritten because it hasn't been refreshed significantly in years.

Maybe I would create a new page, like "FeaturePython methods", and place it there, and then link to it from the "Scripted objects" (or "FeaturePython objects") page, just to keep this page relatively small. And "Creating a FeaturePython Box, Part II" should be structured like a proper tutorial; it shouldn't define new information, just use the information defined in the other pages.

I've noticed this issue as well in many old pages of the wiki. New information is presented in a tutorial style; in my opinion, there should be some pages where the information is centralized, while tutorials should use this information by referring to those other pages.

Also check the source code; there is a fake workbench called TemplatePyMod, which contains examples of the scripted objects and viewproviders, and Commands. You can see all methods of the objects there; it's a tedious work, but you could test every single method by creating a single class with a single method and see how it behaves. Also ideally you would cross reference with the C++ code to make sure it works in the same way, and that the Python examples are not obsolete (old, seldom used files tend to go obsolete without anybody noticing).
Always add the important information to your posts if you need help. Also see Tutorials and Video tutorials.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
User avatar
gbroques
Posts: 73
Joined: Thu Jan 23, 2020 3:28 am
Location: St. Louis, Missouri

Re: [Wiki Discussion] Scripted Objects Complete Method Reference

Postby gbroques » Tue Aug 04, 2020 12:02 am

vocx wrote:
Mon Aug 03, 2020 3:43 pm
I like your proposal. This power user documentation really needs to be rewritten because it hasn't been refreshed significantly in years.

Maybe I would create a new page, like "FeaturePython methods", and place it there, and then link to it from the "Scripted objects" (or "FeaturePython objects") page, just to keep this page relatively small. And "Creating a FeaturePython Box, Part II" should be structured like a proper tutorial; it shouldn't define new information, just use the information defined in the other pages.

I've noticed this issue as well in many old pages of the wiki. New information is presented in a tutorial style; in my opinion, there should be some pages where the information is centralized, while tutorials should use this information by referring to those other pages.
I agree. Thanks for the suggestion.

I created FeaturePython methods with the copy-pasted content from Creating a FeaturePython Box, Part II, and simply linked to it in this change.

I added links to this new page from FeaturePython Objects and Scripted objects pages where I felt it was appropriate.
vocx wrote:
Mon Aug 03, 2020 3:43 pm
Also check the source code; there is a fake workbench called TemplatePyMod, which contains examples of the scripted objects and viewproviders, and Commands. You can see all methods of the objects there; it's a tedious work, but you could test every single method by creating a single class with a single method and see how it behaves.
That example doesn't really have any good examples for FeaturePython classes other than execute and onChanged.
vocx wrote:
Mon Aug 03, 2020 3:43 pm
Also ideally you would cross reference with the C++ code to make sure it works in the same way, and that the Python examples are not obsolete (old, seldom used files tend to go obsolete without anybody noticing).
I found the public API of the FeaturePython class below:
https://github.com/FreeCAD/FreeCAD/blob ... .h#L51-L86

I'm assuming there's not a one-to-one correspondence between the C++ header file and API exposed through Python.

There's a FeaturePythonPyImp.h and FeaturePythonPyImp.inl that I'm assuming are responsible for the Python binding, but it's not clear what Python methods are bound and how.

Anyone able to shed light on this?
wmayer wrote: :bell:
vocx
Posts: 5206
Joined: Thu Oct 18, 2018 9:18 pm

Re: [Wiki Discussion] Scripted Objects Complete Method Reference

Postby vocx » Tue Aug 04, 2020 12:31 am

gbroques wrote:
Tue Aug 04, 2020 12:02 am
...
That example doesn't really have any good examples for FeaturePython classes other than execute and onChanged.
Remember that the base class is not "FeaturePython", it's "DocumentObject", that's the origin of everything (see the diagram in App DocumentObject). The TemplatePyMod example has some files that list a bunch of those functions. But indeed, there is no example of the usage of every single method; this is the reason I say you may have to create a small workbench, with a small class, and implement every single method yourself to test its behavior; then you can describe it in the wiki, and at the same time update the TemplatePyMod workbench in the source code with proper examples.
Always add the important information to your posts if you need help. Also see Tutorials and Video tutorials.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
wmayer
Site Admin
Posts: 16649
Joined: Thu Feb 19, 2009 10:32 am

Re: [Wiki Discussion] Scripted Objects Complete Method Reference

Postby wmayer » Tue Aug 04, 2020 11:29 am

gbroques wrote:
Tue Aug 04, 2020 12:02 am
That example doesn't really have any good examples for FeaturePython classes other than execute and onChanged.
This is easy to explain. The example file was created more than 10 years ago and at that time it was only possible to customize two or three methods via Python.
gbroques wrote:
Tue Aug 04, 2020 12:02 am
I found the public API of the FeaturePython class below:
Look at the template class: https://github.com/FreeCAD/FreeCAD/blob ... hon.h#L167
Each virtual method that invokes "imp->" is a method that can be customized with your Python proxy class.
gbroques wrote:
Tue Aug 04, 2020 12:02 am
There's a FeaturePythonPyImp.h and FeaturePythonPyImp.inl that I'm assuming are responsible for the Python binding, but it's not clear what Python methods are bound and how.
At the very beginning it offered the methods addProperty and removeProperty to add/remove properties to the FeaturePython classes at runtime. Each FeaturePython had to override its getPyObject() method to instantiate FeaturePythonPyT to make sure custom properties could be added or removed.

This however caused an explosion of many additional classes and that's why the methods addProperty/removeProperty have been moved to a base class.
User avatar
gbroques
Posts: 73
Joined: Thu Jan 23, 2020 3:28 am
Location: St. Louis, Missouri

Re: [Wiki Discussion] Scripted Objects Complete Method Reference

Postby gbroques » Tue Aug 04, 2020 12:38 pm

wmayer wrote:
Tue Aug 04, 2020 11:29 am
Look at the template class: https://github.com/FreeCAD/FreeCAD/blob ... hon.h#L167
Each virtual method that invokes "imp->" is a method that can be customized with your Python proxy class.
Based on that, then it would appear there are currently 18 total methods we can override in the Python proxy class, and only 4 are documented in FeaturePython methods.
  • mustExecute
  • execute
  • getViewProviderName
  • getSubObject
  • getSubObjects
  • getLinkedObject
  • hasChildElement
  • isElementVisible
  • canLinkProperties
  • allowDuplicateLabel
  • redirectSubName
  • canLoadPartial
  • getPyObject - Override to instantiate FeaturePythonPyT to make sure custom properties could be added or removed. (is this description right?)
  • onBeforeChange
  • onBeforeChangeLabel
  • init
  • onChanged
  • onDocumentRestored
Are all of the above methods intended to be overridden in the Proxy class? Then I can work on adding them to FeaturePython methods.

Which ones are the most useful that we currently don't have documented?

How do we determine the signature of bound Python methods?
In the code we see imp->execute(), and in Python we know that execute receives obj as the first argument.

How can we determine the signatures of the these bound methods?

EDIT: Also added Determining Available Ptyhon Methods to FeaturePython methods page. Please add more detail and clarity as you see fit.
Last edited by gbroques on Tue Aug 04, 2020 1:05 pm, edited 1 time in total.
wmayer
Site Admin
Posts: 16649
Joined: Thu Feb 19, 2009 10:32 am

Re: [Wiki Discussion] Scripted Objects Complete Method Reference

Postby wmayer » Tue Aug 04, 2020 1:05 pm

The methods getPyObject() and init() can be dropped from the list because they cannot be controlled by the Python proxy class.
Which ones are the most useful that we currently don't have documented?
The most important methods are the green one. All others are only needed to do very sophisticated things and in 99% of all cases people don't have to worry about them.

Since the list has been extended by realthunder I cannot even give you some sensible examples for each item. When looking at the Python code base of FreeCAD I only found simplistic examples for getViewProviderName and canLinkProperties
User avatar
gbroques
Posts: 73
Joined: Thu Jan 23, 2020 3:28 am
Location: St. Louis, Missouri

Re: [Wiki Discussion] Scripted Objects Complete Method Reference

Postby gbroques » Tue Aug 04, 2020 11:15 pm

wmayer wrote:
Tue Aug 04, 2020 1:05 pm
The methods getPyObject() and init() can be dropped from the list because they cannot be controlled by the Python proxy class.
Which ones are the most useful that we currently don't have documented?
The most important methods are the green one. All others are only needed to do very sophisticated things and in 99% of all cases people don't have to worry about them.

Since the list has been extended by realthunder I cannot even give you some sensible examples for each item. When looking at the Python code base of FreeCAD I only found simplistic examples for getViewProviderName and canLinkProperties
Thank you werner! I will update that page with something to the effect of what you just said.

I'll report back in this thread once I've made that wiki change in case anyone cares to comment.
User avatar
gbroques
Posts: 73
Joined: Thu Jan 23, 2020 3:28 am
Location: St. Louis, Missouri

Re: [Wiki Discussion] Scripted Objects Complete Method Reference

Postby gbroques » Tue Aug 04, 2020 11:55 pm

wmayer wrote:
Tue Aug 04, 2020 1:05 pm
When looking at the Python code base of FreeCAD I only found simplistic examples for getViewProviderName and canLinkProperties

I updated FeaturePython methods accordingly based on your response.

If you can share, or link to those simplistic examples, then I think it's worth documenting in that page.

Happy to update it if you or anyone else cares to post more in this thread about these "Additional Methods" that people won't have to worry about in most cases.