PyAPI: Support for custom tool registration

Added a module bpy.utils.toolsystem which only exposes ToolDef,
to avoid scripts referencing bl_ui internals.

4 files changed, 101 insertions, 2 deletions

diff --git a/release/scripts/modules/bpy/utils/__init__.py b/release/scripts/modules/bpy/utils/__init__.py
index 80e48697b2f..bb1ba5eb719 100644
--- a/release/scripts/modules/bpy/utils/__init__.py
+++ b/release/scripts/modules/bpy/utils/__init__.py
@@ -709,6 +709,48 @@ def register_submodule_factory(module_name, submodule_names):
 
 
 # -----------------------------------------------------------------------------
+# Tool Registraion
+
+def register_tool(space_type, context_mode, tool_def):
+    from bl_ui.space_toolsystem_common import ToolSelectPanelHelper
+    cls = ToolSelectPanelHelper._tool_class_from_space_type(space_type)
+    if cls is None:
+        raise Exception(f"Space type {space_type!r} has no toolbar")
+    tools = cls._tools[context_mode]
+
+    keymap_data = tool_def.keymap
+    if keymap_data is not None:
+        if context_mode is None:
+            context_descr = "All"
+        else:
+            context_descr = context_mode.replace("_", " ").title()
+        from bpy import context
+        wm = context.window_manager
+        kc = wm.keyconfigs.default
+        if callable(keymap_data[0]):
+            cls._km_action_simple(kc, context_descr, tool_def.text, keymap_data)
+
+    tools.append(tool_def)
+
+
+def unregister_tool(space_type, context_mode, tool_def):
+    from bl_ui.space_toolsystem_common import ToolSelectPanelHelper
+    cls = ToolSelectPanelHelper._tool_class_from_space_type(space_type)
+    if cls is None:
+        raise Exception(f"Space type {space_type!r} has no toolbar")
+    tools = cls._tools[context_mode]
+    tools.remove(tool_def)
+
+    keymap_data = tool_def.keymap
+    if keymap_data is not None:
+        from bpy import context
+        wm = context.window_manager
+        kc = wm.keyconfigs.default
+        km = keymap_data[0]
+        kc.keymaps.remove(km)
+
+
+# -----------------------------------------------------------------------------
 # Manual lookups, each function has to return a basepath and a sequence
 # of...
 
diff --git a/release/scripts/modules/bpy/utils/toolsystem.py b/release/scripts/modules/bpy/utils/toolsystem.py
new file mode 100644
index 00000000000..e2431536b4f
--- /dev/null
+++ b/release/scripts/modules/bpy/utils/toolsystem.py
@@ -0,0 +1,23 @@
+# ##### BEGIN GPL LICENSE BLOCK #####
+#
+#  This program is free software; you can redistribute it and/or
+#  modify it under the terms of the GNU General Public License
+#  as published by the Free Software Foundation; either version 2
+#  of the License, or (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program; if not, write to the Free Software Foundation,
+#  Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+# ##### END GPL LICENSE BLOCK #####
+
+# <pep8 compliant>
+
+# Until we untangle ToolDef from bl_ui internals,
+# use this module to document ToolDef.
+from bl_ui.space_toolsystem_common import ToolDef
diff --git a/release/scripts/startup/bl_ui/space_toolsystem_common.py b/release/scripts/startup/bl_ui/space_toolsystem_common.py
index 5a32264bc5a..4db2fee4bae 100644
--- a/release/scripts/startup/bl_ui/space_toolsystem_common.py
+++ b/release/scripts/startup/bl_ui/space_toolsystem_common.py
@@ -348,8 +348,7 @@ class ToolSelectPanelHelper:
             for item in cls._tools_flatten_with_keymap(tools):
                 keymap_data = item.keymap
                 if callable(keymap_data[0]):
-                    text = item.text
-                    cls._km_action_simple(kc, context_descr, text, keymap_data)
+                    cls._km_action_simple(kc, context_descr, item.text, keymap_data)
 
     @classmethod
     def keymap_ui_hierarchy(cls, context_mode):
diff --git a/release/scripts/templates_py/ui_tool_simple.py b/release/scripts/templates_py/ui_tool_simple.py
new file mode 100644
index 00000000000..920a23b081a
--- /dev/null
+++ b/release/scripts/templates_py/ui_tool_simple.py
@@ -0,0 +1,35 @@
+# This example adds an object mode tool to the toolbar.
+# This is just the circle-select tool.
+import bpy
+from bpy.utils.toolsystem import ToolDef
+
+@ToolDef.from_fn
+def my_tool():
+    def draw_settings(context, layout, tool):
+        props = tool.operator_properties("view3d.select_circle")
+        layout.prop(props, "radius")
+    return dict(
+        text="My Circle Select",
+        description=(
+            "This is a tooltip\n"
+            "with multiple lines"
+        ),
+        icon="ops.generic.select_circle",
+        widget=None,
+        keymap=(
+            ("view3d.select_circle", dict(deselect=False), dict(type='ACTIONMOUSE', value='PRESS')),
+            ("view3d.select_circle", dict(deselect=True), dict(type='ACTIONMOUSE', value='PRESS', ctrl=True)),
+        ),
+        draw_settings=draw_settings,
+    )
+
+
+def register():
+    bpy.utils.register_tool('VIEW_3D', 'OBJECT', my_tool)
+
+
+def unregister():
+    bpy.utils.unregister_tool('VIEW_3D', 'OBJECT', my_tool)
+
+if __name__ == "__main__":
+    register()