[Bf-taskforce25] Operator standardization

Ton Roosendaal ton at blender.org
Mon Feb 2 18:35:36 CET 2009 

Hi Campbell,

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

In the 2.5 spec we've noted a convention the other way around for C  
code functions. A lot of opeators follow this convention already too.  
:)

The reason is that a function beginning with 'copy' or 'add' doesn't  
say much about the context it works in, especially when there's a  
subcontext. It also makes it a bit easier to locate, a function like  
wm_window_copy() looks a bit more at home in wm_window.c than the  
wm_copy_window().

I would therefore prefer to use as ordering:

-->  (context _OT_ subcontext) _ (operation) _ (optional operation info)

Then we always use the verb to separate the information in 'what it  
works on' and what it does. This then gives straight information about  
what the operator needs as input, and is less arbitrary to apply than a  
rule to put the "more specific terms at the end".

so it becomes something like

MESH_OT_faces_delete
MESH_OT_faces_select_similar

MESH_OT_add_primitive_monkey
    (operation info is 'primitive monkey')

MESH_OT_edges_select_shortest_path
    (requires selected edges to work)

MESH_OT_edges_select_sharp

Operations on items like modifiers, constraints, etc also get nicer  
grouped:

OBJECT_OT_modifier_delete
OBJECT_OT_modifier_add

OBJECT_OT_constraint_delete
OBJECT_OT_constraint_add

and you can give more info like

OBJECT_OT_modifier_add_duplicate
OBJECT_OT_constraint_delete_unused
etc.

But maybe this is just personal preference :)

-Ton-

------------------------------------------------------------------------
Ton Roosendaal  Blender Foundation   ton at blender.org    www.blender.org
Blender Institute BV  Entrepotdok 57A  1018AD Amsterdam The Netherlands

On 2 Feb, 2009, at 2:50, Campbell Barton wrote:

> 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
> _______________________________________________
> Bf-taskforce25 mailing list
> Bf-taskforce25 at blender.org
> http://lists.blender.org/mailman/listinfo/bf-taskforce25
>

More information about the Bf-taskforce25 mailing list