[Bf-taskforce25] Operator standardization

Tue Feb 3 02:20:27 CET 2009

> -->  (context _OT_ subcontext) _ (operation) _ (optional operation info)
+1, using sub-contexts like this makes sense.

Shaul, Id really not want to use english language word ordering, its
unpredictable since word order would depend on the words used for each
operator.
Tons suggestion means functions are usefully grouped when sorted
alphabetically in documentation, it also gives more useful
auto-complete.
MESH_OT_faces_* gives a nice list of all mesh face ops.

Though this is also a preference from my first language being lingo
which tried to be user friendly by mimicking English. yuck!

On Mon, Feb 2, 2009 at 9:35 AM, 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
>

-- 
- Campbell