Creating custom tool in Blender

In Blender version 2.8x and later, a new toolbar has appeared, located in the 3D viewport area on the left side. We can create custom tools and add them to this panel using the Blender Python API.

.blend file on Patreon

To create a custom user tool, just like custom user operators, we must define a special class.

The custom tool class must be inherited from the bpy.types.WorkSpaceTool base class.

Next, just like for operators, we need to define the required class parameters:

bl_space_type – the area in which the tool will be used. For example, “VIEW_3D” for a 3D viewport area.

bl_context_mode – The context of the tool, for example “EDIT” if the tool is used for objects only in the edit mode.

bl_idname – standard identifier for the tool.

bl_label – short tool description. Appears when hovering over the icon with the mouse cursor.

bl_description – full description of the tool. Appears when the cursor is hovered over the tool icon for a fiew seconds. Can be multiline if defined in tuple format.

bl_icon – A pointer to the icon for the tool that will be displayed on the toolbar. All icons available for tools are placed in separate files in the following Blender directory:

File names correspond to the icon identifier, which must be specified in the bl_icon parameter.

And, the main bl_keymap parameter – the actions that the tool will perform.

This parameter describes the list of possible actions of the tool as a tuple. Each element is a single action.

Each action is described by a separate tuple.

The first element of this tuple is the operator identifier, without the “bpy.ops” prefix. This operator will be executed when the user uses the tool. For example, to select an object in the viewport, the “view3d.select” value should be specified.

The second element of the tuple is a dictionary with tool calling parameters. It describes the user’s actions. For example, clicking the left mouse button is described as follows:

The third element of the tuple is another dictionary that specifies the parameters passed to the operator. For example, in order to deselect all objects, the “deselect_all” parameter with the True value must be passed to the “view3d.select” operator. In our case, the parameter indication will be set as follows:

An example of a class for creating a custom tool that emulates selecting objects in the 3D viewport with clicks and border select:

Code author: Andrej

In order to append this tool to the 3D viewport toolbar, we need to register this class in the Blender Python API:

If this code is executed from the Blender text editor, we need to update the viewport area by moving the mouse cursor to it, or by calling the force update by code: