Dev:Source/Architecture/Tool Specification
Note: superseded by BlenderDev/Blender2.5/Operators and BlenderDev/Blender2.5/DataAPI.
Intro
This is just an idea of what a tool could be in the tool API. This is merely a proposal, I don't have any concrete plans to work on a tool API :). A goal for this design was to have something that is compatible with the way Blender currently works, that doesn't make declaring a tool require a lot of code, while still allowing the tool to be usable in different ways.
-- Brecht
Uses of a Tool API
- Random notes regarding use of a tool api: http://wiki.blender.org/index.php/BlenderDev/EventsToolApiNotes
- Customizable Hotkeys
- Toolbar/Shelf
- Macro Recording
- Python Tools
- .. ?
Inputs as Tools
Anything that drives a button, hotkey or menu item, would be a tool, including check boxes, dropdown menu's, text and number inputs, .. . There's a good reason to make all inputs tools:
- They often have associated code that needs to be executed.
- It would be possible to have them in a shelf, or driven by a hotkey. Think for example of a hotkey for selecting a vertex group from a popup menu in the 3d view, or a hotkey to increase/decrease the subsurf resolution.
- Macro recording could also record changes to values.
- Python tools could provide things like string or number inputs through a tool. So if the contents of a panel is just a collection of tools, python tools would integrate naturally.
Tool Specification
- Name: unique identifier for the tool.
- Type: runnable, checkbox, multiple choice, number input, string input, color input, .. .
- Description: button/menu text, tooltip, undo string, documentation link, ..
- Mode: specification of the mode(s) in which the tool is enabled. This would also include transform mode or circle select for example.
- Parameters: input parameters for the tool, like object or material to which it is applied. These would have default values like 'current node' or 'current 3d view'. This would allow killing the use of some globals, better re-use of macro's, and for example using a material tool in both the material buttons and the outliner.
- Tool Function: function that executes the tool or provides access to a value.
For most tools, the mode and parameters should fully describe the context in which the tool can be executed. If the modes don't match, or a parameter cannot be set, the tool is disabled. More complicated enabled/disabled checks could be provided by the tool function if needed. Buttons or menu items could be automatically hidden or drawn based on the tool being enabled or disabled.
Creating a tool would involve writing a declaration and a tool function. The declaration describes the tool properties, and the tool function handles events for the tool. Such events may be 'run', 'get value', 'set value', .. . For many input tools these events can just be handled by a standard function, passing a pointer to the value. But other tools can override that behaviour by manually handling events.
Declaring a tool for every button in the user interface would lead to a lot of duplicate code. It should be possible to declare many tools with one declaration and tool function, if they have a common mode and paramaters. For example, a panel in the material buttons could be handled by a single tool function, much like there is a single drawing function now. But all the tools would be separately available from the outside.
Existing Tool APIs
XSI: http://softimage.wiki.avid.com/sdkdocs/cus_cmds.htm
Maya: http://caad.arch.ethz.ch/info/maya/manual/DevKit/PlugInsAPI/PlugInsCommand.doc.html
