[Bf-taskforce25] Operator standardization

Mon Feb 2 20:53:12 CET 2009

Well, although I understand what you are saying, I beg to differ. In
the long term non-intuitive formats are lost and the resulting mess is
bigger. I think that the order should mach the english languague. so
"window copy" is ok, but "edges select sharp" is a bit too much for
the eye :)

so taking your list I'd say:
MESH_OT_delete_faces

MESH_OT_select_similar_faces

MESH_OT_add_primitive_monkey

MESH_OT_select_edges_shortest_path

MESH_OT_select_sharp_faces

Operations on items like modifiers, constraints, etc also get nicer
grouped: - no change here

On Mon, Feb 2, 2009 at 12:35 PM, Ton Roosendaal <ton at blender.org> wrote:
> 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
>>
>
> _______________________________________________
> Bf-taskforce25 mailing list
> Bf-taskforce25 at blender.org
> http://lists.blender.org/mailman/listinfo/bf-taskforce25
>