[Bf-taskforce25] Operator standardization

Nathan Letwory jesterking at letwory.net
Tue Feb 3 10:24:36 CET 2009 

2009/2/3 Campbell Barton <ideasman42 at gmail.com>:
> This would mean adding  sub-grouping to operators, the RNA grouping
> stuff doesn't apply here.
> It still wouldn't be as nice for auto-completion .

+1 for anything that improves autocompletion/intellisense mechanisms.
It also makes it much easier to 'guess' for operator names when you're
working with editors that don't do any of those fancy stuff.

/Nathan

>
> I meant not using English grammar - or "word ordering" as us
> uneducated people say :)
>
>
> On Mon, Feb 2, 2009 at 7:09 PM, Shaul Kedem <shaul.kedem at gmail.com> wrote:
>> Well, if this is a documentation issue I think we can solve it with grouping.
>>
>> As for not using the english language, I have a gut feeling that's
>> what we'll end with..
>>
>> On Mon, Feb 2, 2009 at 8:20 PM, Campbell Barton <ideasman42 at gmail.com> wrote:
>>>> -->  (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
>>> _______________________________________________
>>> 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
> _______________________________________________
> 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