[Bf-taskforce25] Operator standardization

[Campbell Barton]

Reply inline...

On Sun, Feb 1, 2009 at 6:58 AM, Blender Institute <institute at blender.org> wrote:
> Hi,
>
> We've got now over 250 operators defined, time for some thoughts about
> what good standards are for naming, flags, and property definitions.
>
> Campbell did interesting test with epydoc output, see here:
>
> Operators
> http://www.graphicall.org/ftp/ideasman42/html/bpyoperator-module.html
> RNA
> http://www.graphicall.org/ftp/ideasman42/html/class-tree.html
>
> Some issues we noted;
>
> - operator names should try to keep in mind the part after _OT_ should
> fit as a useful api name. (not MESH_OT_mesh_delete, but MESH_OT_delete)
IMHO we should go further and define some basics for word ordering for
operator names..
Below are some orderings that conflict, Id also like to go with more
specific terms at the end of the operator name. OP_OT_add_foo rather
then  OP_OT_foo_add this is how most operators are already done.


- MESH_OT_add_primitive_monkey  - (add as a prefix is used mostly).
- OBJECT_OT_curve_add -> OBJECT_OT_add_curve

- MESH_OT_select_invert - (select as a prefix is used mostly)
- GRAPHEDIT_OT_keyframes_borderselect ->GRAPHEDIT_OT_keyframes_select_border
- ED_FILE_OT_border_select -> ED_FILE_OT_select_border
- MESH_OT_similar_edge_select -> MESH_OT_select_similar_edge
- UV_OT_loop_select -> UV_OT_select_loop

Should operators specifically say they operate on the selection. Seems
default, maybe operators should only have a prefix if they DONT use
the select as their context (add an _all prefix). Examples
- NODE_OT_delete_selection -> NODE_OT_delete
- UV_OT_unlink_selection -> UV_OT_unlink

For consistency? add to scene and new datatype are a bit different.....
GROUP_OT_group_create -> GROUP_OT_group_add

Operators that use the mouse location, what word should be used to show this
pick, click, mouseclick, cursor?
Assuming "click" is preferred, and "pick" when only the mouse location
is used, here are my suggestions.

- ACT_OT_keyframes_clickselect -> ACT_OT_keyframes_select_cick
- ANIM_OT_channels_mouseclick -> ANIM_OT_channels_click
- GRAPHEDIT_OT_keyframes_clickselect  -> GRAPHEDIT_OT_keyframes_select_click
- OUTLINER_OT_activate_click (good)
- MESH_OT_select_linked_pick -> MESH_OT_select_linked_pick
- SEQUENCER_OT_select_pick_linked -> should be SEQUENCER_OT_select_linked_pick

yesterday, I looked over the props and found for percent, 1 used
"percentage" others "percent", some were floats, most ints. Im not
really fussed but Id like to try keep some of these variable inputs
consistent.
I settled on percent, float since a python script may want to run an
operator like vertex to sphere with a percentage of 66.6666. and I
dont see any reason to force using ints.

General gripe, some devs are being slack with properties, using int's
instead where enum's should go, and not giving useful hard/soft limits
to properties.


> - selection operators should use default boolean for 'extend' and for
> 'deselect' ?
agree, unless anyone can think of a third option you'd want for select
extend (holding shift)

> - toggle operators (editmode, vpaint) should get standard enum "set,
> clear, toggle", so the op->invoke() can check for this enum, and
> optionally then handle toggle.
agree

> - add a tooltip/doc string to operators, describing the intended
> operation well?
agree

> - classify operators well that heavily rely on mouse input, or cannot
> be redone or cannot be used for the py api.
agree

> - standard border-select or circle-select ops should not return 'event
> type' property, but some other standard like the default booleans
> 'extend' and 'deselect'. Those then can later always become configured
> with modal keymaps.
dont understand the problem, no comment.

> - in order to make a nice UI after operator executed, the used
> properties should be useful in UI too. When an operator uses internal
> props it should be set as such.
>
> - Transform is currently the most gigantic one... how can we extract
> from a transform operator the useful (used?) ones, and how to
> communicate the api well?
agree, each 'mode' could be its own operator, will be used heavily by
macro's, so having too many arguments that are only relevant in
certain cases is confusing.

> So! I guess people can name more issues, let's get them listed and work
> to a proposal of some kind?
>
> -Ton-
>
> ------------------------------------------------------------------------
> Ton Roosendaal  Blender Foundation   ton at blender.org    www.blender.org
> Blender Institute BV  Entrepotdok 57A  1018AD Amsterdam The Netherlands
>
> _______________________________________________
> Bf-taskforce25 mailing list
> Bf-taskforce25 at blender.org
> http://lists.blender.org/mailman/listinfo/bf-taskforce25
>



-- 
- Campbell