Filtering values available for selection through the UILayout.prop()

When creating custom properties, the values of which the user can choose from a list, it is often necessary to filter the list of values offered for selection. We can use the poll function to shorten the proposed list of values by removing unwanted elements.

.blend file on Patreon

Let’s see, how we can use such filtering for example fot selecting a collection into a custom property.

First, let’s create a custom property for the “Scene” object with a pointer to the collection:

bpy.types.Scene.my_collection = bpy.props.PointerProperty(
    type=bpy.types.Collection
)

bpy.types.Scene.my_collection = bpy.props.PointerProperty(

type=bpy.types.Collection

)

Let’s append a custom panel to the 3D Viewport area UI and place the custom property we created on it:

class SAMPLE_PT_Panel(bpy.types.Panel):
    bl_idname = 'SAMPLE_PT_panel'
    bl_label = 'SAMPLE'
    bl_space_type = 'VIEW_3D'
    bl_region_type = 'UI'
    bl_category = 'SAMPLE'

    def draw(self, context):
        self.layout.prop(context.scene, 'my_collection', text='')

bpy.utils.register_class(SAMPLE_PT_Panel)

class SAMPLE_PT_Panel(bpy.types.Panel):

bl_idname = 'SAMPLE_PT_panel'

bl_label = 'SAMPLE'

bl_space_type = 'VIEW_3D'

bl_region_type = 'UI'

bl_category = 'SAMPLE'

def draw(self, context):

self.layout.prop(context.scene, 'my_collection', text='')

bpy.utils.register_class(SAMPLE_PT_Panel)

In the “draw” function, we show our custom scene property “my_collection” on the panel through the UILayout.prop(), specifying in its parameters a link to the scene and the name of the displayed property.

Now the user can select any collection with no restrictions.

We can limit the list of collections available for selection, for example, only to those collections that are marked with a green icon.

Let’s define the filter function that will return True if the collection has a green icon and False for all other collections.

def filter(self, collection):
    return True if collection.color_tag == 'COLOR_04' else False

1 2	def filter(self, collection): return True if collection.color_tag == 'COLOR_04' else False

Since we will be calling this function as a handler of a custom property, it must take two parameters:

self – a pointer to the property container, in our case – the Scene;

collection – the current collection for which we need to determine whether to display it or not;

The following condition

collection.color_tag == 'COLOR_04'

1	collection.color_tag == 'COLOR_04'

determines if the collection has a green “COLOR_04” icon.

Now we need to change the definition of the custom property with a pointer to the collection by assigning our filter function as a poll handler:

bpy.types.Scene.my_collection = bpy.props.PointerProperty(
    type=bpy.types.Collection,
    poll=filter
)

bpy.types.Scene.my_collection = bpy.props.PointerProperty(

type=bpy.types.Collection,

poll=filter

)

Now, when showing the collections list, the filter we assigned is used, and the user can select only “green” collections.

Also, a collection already selected by the user could be removed from the list. To do this, let’s modify our filter function by adding one more condition:

def filter(self, collection):
    return True if collection.color_tag == 'COLOR_04' \
                and collection != bpy.context.scene.my_collection \
        else False

def filter(self, collection):

return True if collection.color_tag == 'COLOR_04' \

and collection != bpy.context.scene.my_collection \

else False

This way we can filter any data lists proposed for user selection to a custom property in the way we need.