Searchable EnumProperty #118004

New Issue

Nick Alberelli · 2024-02-08T17:20:31+01:00

Nick Alberelli commented

2024-02-08 17:20:31 +01:00

Issue

EnumProperty is very useful when displaying a human-readable name for an item as the value/name, and a machine-readable key/identifier that is used in code.

Currently, EnumProperty only supports non-searchable lists, a workaround is to use a StringProperty with a search, and a custom getter/setter that reads the human-readable input string finding the matching machine-readable key/identifier to store in another property.

Work Around

key: bpy.props.StringProperty(name="Key") # machine read-able key/identifier

def get_name(self):
    return self['name']

def set_name(self, input):
    key = set_key_via_enum_name( # Sets self.key to the matching key if input is a value
        self=self,
        input_name=input,
        items=get_enum_items() # Returns a list of tuples
        value='name',
        key='key',
    )
    return

def get_search_list(self, context, edit_text):
    return [e[1] for e in get_enum_items()] # Returns list of values

name: bpy.props.StringProperty( # name is the value/name of enum items list
    name="Name",
    get=get_name,
    set=set_name,
    search=get_search_list,
)

An example of this is in the Blender Kitsu Add-On, users are required to select a Task Type from a list, this task type has a human read-able value/name, and a machine-readable key/identifier that is stored in the add-on. An implementation of the above workaround can be found in the add-on's props.py file.

A challenege with this workaround is that the developer needs to ensure that these two values are always in sync with each-other.

Solution

Add a search property to the EnumProperty could make the above implementation a lot simpler and more reliable.

EnumProperty should be used so a user can select a value/name, and accessing that property via python returns the key/identifier. This list should be searchable, so users can quickly find the value/name they need without scrolling a large list.

API

bpy.props.EnumProperty(
    items,
    name='',
    searchable=True,  # Bool Property to determine if list is searchable
    search_options= {'SORT'} # sorts the resulting items.

The search_options set does NOT include the ’SUGGESTION’ flag found in StringProperty search_options because users can ONLY enter values found in search candidates, otherwise cancel the user's input.

UI

The UI could be very similar to the StringProperty search, where a text field when selected draws a list. In the case of EnumProperty this list would contain only the names of the enum items list. A user can select the desired name/value, then accessing this property via python would return the matching key/identifier.

# Issue EnumProperty is very useful when displaying a human-readable name for an item as the value/name, and a machine-readable key/identifier that is used in code. Currently, EnumProperty only supports non-searchable lists, a workaround is to use a StringProperty with a search, and a custom getter/setter that reads the human-readable input string finding the matching machine-readable key/identifier to store in another property. ### Work Around ```python key: bpy.props.StringProperty(name="Key") # machine read-able key/identifier def get_name(self): return self['name'] def set_name(self, input): key = set_key_via_enum_name( # Sets self.key to the matching key if input is a value self=self, input_name=input, items=get_enum_items() # Returns a list of tuples value='name', key='key', ) return def get_search_list(self, context, edit_text): return [e[1] for e in get_enum_items()] # Returns list of values name: bpy.props.StringProperty( # name is the value/name of enum items list name="Name", get=get_name, set=set_name, search=get_search_list, ) ``` An example of this is in the Blender Kitsu Add-On, users are required to select a Task Type from a list, this task type has a human read-able value/name, and a machine-readable key/identifier that is stored in the add-on. An implementation of the above workaround can be found in the add-on's [props.py](https://projects.blender.org/studio/blender-studio-pipeline/src/commit/7c980aabb4d36c04aef157f596318f6d2845a515/scripts-blender/addons/blender_kitsu/props.py) file. A challenege with this workaround is that the developer needs to ensure that these two values are always in sync with each-other. # Solution Add a search property to the EnumProperty could make the above implementation a lot simpler and more reliable. EnumProperty should be used so a user can select a value/name, and accessing that property via python returns the key/identifier. This list should be searchable, so users can quickly find the value/name they need without scrolling a large list. ## API ```python bpy.props.EnumProperty( items, name='', searchable=True, # Bool Property to determine if list is searchable search_options= {'SORT'} # sorts the resulting items. ``` The search_options set does NOT include the `’SUGGESTION’` flag found in [StringProperty search_options](https://docs.blender.org/api/current/bpy.props.html#:~:text=search_options%20(set)%20%E2%80%93) because users can ONLY enter values found in search candidates, otherwise cancel the user's input. ## UI The UI could be very similar to the StringProperty search, where a text field when selected draws a list. In the case of EnumProperty this list would contain only the names of the enum items list. A user can select the desired name/value, then accessing this property via python would return the matching key/identifier. ![image](/attachments/014d84e8-2c89-4833-a73a-0ac8016dc487)

image.png

18 KiB

👍 3

Nick Alberelli added the

Type

Design

label 2024-02-08 17:20:31 +01:00

Nick Alberelli commented

2024-02-08 17:22:08 +01:00

@fsiddi as requested here is the proposal for searchable enums, please let me know your feedback.

Thomas Barlow commented

2024-02-08 23:04:59 +01:00

Another workaround is using an operator with WindowManager.invoke_search_popup(): https://docs.blender.org/api/current/bpy.types.Operator.html#enum-search-popup

The main issues with the operator setup are having to define and register a separate operator for every enum that should be searchable and that it can sometimes be complicated to set the desired enum property from the current context in execute().

Also, from a UI standpoint (and there might be a way around this that I don't know about), it doesn't look great because operators are drawn as buttons.

import bpy

my_enum_prop = bpy.props.EnumProperty(items=[("FIRST", "First", ""), ("SECOND", "Second", "")])

bpy.types.Scene.my_enum = my_enum_prop

class SearchMyEnum(bpy.types.Operator):
    bl_idname = "test.my_enum_search"
    bl_label = ""
    bl_property = "my_enum"

    my_enum: my_enum_prop

    def execute(self, context):
        context.scene.my_enum = self.my_enum
        context.region.tag_redraw()
        return {'FINISHED'}
    
    def invoke(self, context, event):
        wm = context.window_manager
        wm.invoke_search_popup(self)
        return {'RUNNING_MODAL'}


class HelloWorldPanel(bpy.types.Panel):
    """Creates a Panel in the Object properties window"""
    bl_label = "Hello World Panel"
    bl_idname = "OBJECT_PT_hello"
    bl_space_type = 'PROPERTIES'
    bl_region_type = 'WINDOW'
    bl_context = "object"

    def draw(self, context):
        layout = self.layout

        # Standard dropdown list for comparison
        row = layout.row()
        row.prop(context.scene, "my_enum")

        row = layout.row()
        current_item_name = layout.enum_item_name(context.scene, "my_enum", context.scene.my_enum)
        row.operator(SearchMyEnum.bl_idname, text=current_item_name)


def register():
    bpy.utils.register_class(SearchMyEnum)
    bpy.utils.register_class(HelloWorldPanel)


def unregister():
    bpy.utils.unregister_class(HelloWorldPanel)
    bpy.utils.unregister_class(SearchMyEnum)


if __name__ == "__main__":
    register()

Another workaround is using an operator with `WindowManager.invoke_search_popup()`: https://docs.blender.org/api/current/bpy.types.Operator.html#enum-search-popup The main issues with the operator setup are having to define and register a separate operator for every enum that should be searchable and that it can sometimes be complicated to set the desired enum property from the current context in `execute()`. Also, from a UI standpoint (and there might be a way around this that I don't know about), it doesn't look great because operators are drawn as buttons. ![image](/attachments/5ba442f6-5114-4ffe-9594-eb6386506abb) ```py import bpy my_enum_prop = bpy.props.EnumProperty(items=[("FIRST", "First", ""), ("SECOND", "Second", "")]) bpy.types.Scene.my_enum = my_enum_prop class SearchMyEnum(bpy.types.Operator): bl_idname = "test.my_enum_search" bl_label = "" bl_property = "my_enum" my_enum: my_enum_prop def execute(self, context): context.scene.my_enum = self.my_enum context.region.tag_redraw() return {'FINISHED'} def invoke(self, context, event): wm = context.window_manager wm.invoke_search_popup(self) return {'RUNNING_MODAL'} class HelloWorldPanel(bpy.types.Panel): """Creates a Panel in the Object properties window""" bl_label = "Hello World Panel" bl_idname = "OBJECT_PT_hello" bl_space_type = 'PROPERTIES' bl_region_type = 'WINDOW' bl_context = "object" def draw(self, context): layout = self.layout # Standard dropdown list for comparison row = layout.row() row.prop(context.scene, "my_enum") row = layout.row() current_item_name = layout.enum_item_name(context.scene, "my_enum", context.scene.my_enum) row.operator(SearchMyEnum.bl_idname, text=current_item_name) def register(): bpy.utils.register_class(SearchMyEnum) bpy.utils.register_class(HelloWorldPanel) def unregister(): bpy.utils.unregister_class(HelloWorldPanel) bpy.utils.unregister_class(SearchMyEnum) if __name__ == "__main__": register() ```

image.png

18 KiB

👍 1

Campbell Barton commented

2024-02-09 01:40:13 +01:00

Adding the ability to search an enum seems fine.

There are a few things to consider but overall I think the tradeoffs are acceptable.

Enums are animatable, using a text box makes it seem this is a string which users wont expect to be animated.
- In practice items that are accessed via search are likely to be dynamic, so I think it's fine not to allow them to be animated.
Which elements of an enum would display?
- Icons can be supported.
- Probably not UI separators & headings.

Adding the ability to search an enum seems fine. There are a few things to consider but overall I think the tradeoffs are acceptable. - Enums are animatable, using a text box makes it seem this is a string which users wont expect to be animated. - In practice items that are accessed via search are likely to be dynamic, so I think it's fine not to allow them to be animated. - Which elements of an enum would display? - Icons can be supported. - Probably not UI separators & headings.

❤️ 1

Campbell Barton added the

Module

User Interface

label 2024-02-09 03:34:47 +01:00

Nick Alberelli commented

2024-02-09 15:03:15 +01:00

@Mysteryem That is a great point, from a UI design perspective I know that @fsiddi didn't love that solution, I believe because it appears to be an operator and not a field where a user should select something, (but I will let him explain that further), this change was made in studio/blender-studio-pipeline#187. In that PR you can see the new vs old UI

@ideasman42 Thanks for your feedback!
I agree not animated is probably fine in this context. I would like to propse another UI (pictured below) that would be more consistent visually with the existing enum property UI.

Which elements of an enum would display?

Icon's seem smart to support agreed
And I assumed that it would display the 'name' property [(identifier, name, description, icon, number)] for each item
- Maybe the desciption property can be used as a tooltip for each item

@Mysteryem That is a great point, from a UI design perspective I know that @fsiddi didn't love that solution, I believe because it appears to be an operator and not a field where a user should select something, (but I will let him explain that further), this change was made in https://projects.blender.org/studio/blender-studio-pipeline/pulls/187. In that PR you can see the new vs old UI @ideasman42 Thanks for your feedback! I agree not animated is probably fine in this context. I would like to propse another UI (pictured below) that would be more consistent visually with the existing enum property UI. ![EnumProp_Search_UI](/attachments/52b37c4b-25f1-432f-9966-5c60b1c3c286) > Which elements of an enum would display? - Icon's seem smart to support agreed - And I assumed that it would display the 'name' property `[(identifier, name, description, icon, number)]` for each item - Maybe the desciption property can be used as a tooltip for each item

EnumProp_Search_UI.png

20 KiB

👍 1

Philipp Oeser commented

2024-02-09 15:36:52 +01:00

This would also solve part of the issues discussed in #117711 (#93814)

❤️ 1

Francesco Siddi commented

2024-02-09 22:34:58 +01:00

The design proposed by @TinyNick looks good. This was also discussed with @JulianEisel. Perhaps @Harley has time to look into this?