From cd8350764b881fbf75b1a0d0ee0f46cd798d17ae Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Tue, 9 Nov 2021 00:14:45 +1100 Subject: Docs: improve comments & doc-strings for the tool-system --- .../startup/bl_ui/space_toolsystem_common.py | 34 ++++++++++++++++++++-- .../startup/bl_ui/space_toolsystem_toolbar.py | 22 ++++++++++++-- 2 files changed, 51 insertions(+), 5 deletions(-) (limited to 'release') diff --git a/release/scripts/startup/bl_ui/space_toolsystem_common.py b/release/scripts/startup/bl_ui/space_toolsystem_common.py index 4305476cb0f..9d41a0fa02f 100644 --- a/release/scripts/startup/bl_ui/space_toolsystem_common.py +++ b/release/scripts/startup/bl_ui/space_toolsystem_common.py @@ -202,13 +202,41 @@ class ToolSelectPanelHelper: - keymap_prefix: The text prefix for each key-map for this spaces tools. - tools_all(): - Returns (context_mode, tools) tuple pair for all tools defined. + Generator (context_mode, tools) tuple pairs for all tools defined. - tools_from_context(context, mode=None): - Returns tools available in this context. + A generator for all tools available in the current context. - Each tool is a 'ToolDef' or None for a separator in the toolbar, use ``None``. + Tool Sequence Structure + ======================= + + Sequences of tools as returned by tools_all() and tools_from_context() are comprised of: + + - A `ToolDef` instance (representing a tool that can be activated). + - None (a visual separator in the tool list). + - A tuple of `ToolDef` or None values + (representing a group of tools that can be selected between using a click-drag action). + Note that only a single level of nesting is supported (groups cannot contain sub-groups). + - A callable which takes a single context argument and returns a tuple of values described above. + When the context is None, all potential tools must be returned. """ + @classmethod + def tools_all(cls): + """ + Return all tools for this toolbar, this must include all available tools ignoring the current context. + The value is must be a sequence of (mode, tool_list) pairs, where mode may be object-mode edit-mode etc. + The mode may be None for tool-bars that don't make use of sub-modes. + """ + raise Exception("Sub-class %r must implement this method!" % cls) + + @classmethod + def tools_from_context(cls, context, mode=None): + """ + Return all tools for the current context, + this result is used at run-time and may filter out tools to display. + """ + raise Exception("Sub-class %r must implement this method!" % cls) + @staticmethod def _tool_class_from_space_type(space_type): return next( diff --git a/release/scripts/startup/bl_ui/space_toolsystem_toolbar.py b/release/scripts/startup/bl_ui/space_toolsystem_toolbar.py index 1a448046f7a..c07487079de 100644 --- a/release/scripts/startup/bl_ui/space_toolsystem_toolbar.py +++ b/release/scripts/startup/bl_ui/space_toolsystem_toolbar.py @@ -2583,7 +2583,8 @@ class IMAGE_PT_tools_active(ToolSelectPanelHelper, Panel): def tools_all(cls): yield from cls._tools.items() - # for reuse + # Private tool lists for convenient reuse in `_tools`. + _tools_transform = ( _defs_image_uv_transform.translate, _defs_image_uv_transform.rotate, @@ -2609,6 +2610,9 @@ class IMAGE_PT_tools_active(ToolSelectPanelHelper, Panel): ), ) + # Private tools dictionary, store data to implement `tools_all` & `tools_from_context`. + # The keys match image spaces modes: 'context.space_data.mode'. + # The values represent the tools, see `ToolSelectPanelHelper` for details. _tools = { None: [ # for all modes @@ -2674,6 +2678,8 @@ class NODE_PT_tools_active(ToolSelectPanelHelper, Panel): def tools_all(cls): yield from cls._tools.items() + # Private tool lists for convenient reuse in `_tools`. + _tools_select = ( ( _defs_node_select.select, @@ -2692,6 +2698,9 @@ class NODE_PT_tools_active(ToolSelectPanelHelper, Panel): ), ) + # Private tools dictionary, store data to implement `tools_all` & `tools_from_context`. + # The keys is always `None` since nodes don't use use modes to access different tools. + # The values represent the tools, see `ToolSelectPanelHelper` for details. _tools = { None: [ *_tools_select, @@ -2730,7 +2739,8 @@ class VIEW3D_PT_tools_active(ToolSelectPanelHelper, Panel): def tools_all(cls): yield from cls._tools.items() - # for reuse + # Private tool lists for convenient reuse in `_tools`. + _tools_transform = ( _defs_transform.translate, _defs_transform.rotate, @@ -2786,6 +2796,9 @@ class VIEW3D_PT_tools_active(ToolSelectPanelHelper, Panel): _defs_view3d_generic.ruler, ) + # Private tools dictionary, store data to implement `tools_all` & `tools_from_context`. + # The keys match object-modes from: 'context.mode'. + # The values represent the tools, see `ToolSelectPanelHelper` for details. _tools = { None: [ # Don't use this! because of paint modes. @@ -3095,6 +3108,8 @@ class SEQUENCER_PT_tools_active(ToolSelectPanelHelper, Panel): def tools_all(cls): yield from cls._tools.items() + # Private tool lists for convenient reuse in `_tools`. + _tools_select = ( ( _defs_sequencer_select.select, @@ -3110,6 +3125,9 @@ class SEQUENCER_PT_tools_active(ToolSelectPanelHelper, Panel): ), ) + # Private tools dictionary, store data to implement `tools_all` & `tools_from_context`. + # The keys match sequence editors view type: 'context.space_data.view_type'. + # The values represent the tools, see `ToolSelectPanelHelper` for details. _tools = { None: [ ], -- cgit v1.2.3