-
Notifications
You must be signed in to change notification settings - Fork 5
Tool Shelf
Tool shelf is a small productivity add-on for Blender to collect all commonly used tools and scripts in one easy to access panel. This is most helpful for users coming from other DCC packages where such tool spaces are part of the workflow.
It also greatly reduces the need to create separate custom add-ons and operators for alls sorts of workflow helper scripts.
All contained commands and buttons can be organized in groups, edited, sorted and having their code viewed for inspection.
The complete configuration is saved as a json file and can easily be shared across other workstations or artists.
A group is a collapsible collection of tools. The name of each group must be unique.
A tool is either a single button executing a single command or script. A tool can also contain one or more properties if it's necessary to specify how the tool is executed.
A set is a special case of tool which contains multiple buttons, where each button can have it's own command or script. A set can also have one or more properties which are available for all buttons contained in the set.
Tools can only be added when a group is selected in the Group dropdown menu. Therefore it's necessary to have at least one existing group.
- Select New Group.
- Enter a name for the group in the Name field.
- To add the new group after an existing group, choose it from the After Group dropdown menu. If no group is selected here it will be added after the last group.
- Press Add Group.
- Select the group the tool should be placed in from the Group dropdown menu.
- To add the new tool after an existing tool, choose it from the After Tool dropdown menu. If no tool is selected here it will be added after the last tool.
- Enter a name for the tool in the Name field. A tool name must be unique with the group it's been added to.
- Enter the tool command in the Command field. If the command is using a bpy command the import of the bpy module will be added automatically. Alternatively you can have the content of the current text editor used as the source of the button command. See Script from Text Editor for more details.
- Optionally add a tooltip for the button. If nothing is provided the name of the command will be used.
- Optionally enter an icon for the button. This can either be a PNG file, located in the add-ons icons folder (i.e. myIcon.png), the name of a standard Blender icon in single quotes (i.e. 'MONKEY') or a unicode character (i.e. →). If only the icon should be displayed on the button and not the button label activate the Icon Only checkbox.
- Press Add Tool.
For assigning commands or scripts to a button you can also use the currently open text editor document for convenience. If no command has been entered in the Command field when adding or editing a button the content of the text editor is being used. The following rules apply:
- If no text is selected the entire content of the text editor front document will be used as the command.
- If several lines are selected only the selection is used.
- If the command or script only contains one or two lines add a final line break at the end so that the selection includes two lines (in case of one line of code) or three lines (in case of two lines of code). When using selections it's always recommended to include a last empty line.
- For sets, which include more than one command or script, make sure that the individual lines of code are semicolon-separated.
- Follow steps 1-6 from Create a simple tool.
- Turn on the Property checkbox.
- Add a name for the property in the Name field.
- Enter a default value for the property in the Value field. The string entered defines the property type. Enter True or False for a checkbox, a floating point number (i.e. 1.0) for a float field, an integer value for an integer field (i.e. 1) or string for a string field. You can also set a minimum and maximum value for the value by providing the values in a comma-separated manner, i.e. 1.0,0.0,10.0.
- To direct the command for the button to use the property use PROP or PROP1 in the code where the property value should be placed.
To include a dropdown list, or enum property, add the values of the list separated by colons, i.e. body:head:arms:legs. To set one specific entry as the default value add an asterisk before the name, i.e. body:head:*arms:legs. When querying the selection from the button command a string is returned, representing the 0-based index of the list item which is selected.
To add a tool with more than one property enter the names for the properties in the property Name field separated by semicolons. The same goes for the values in the Value field. The number of semicolon-separated items have to be the same in the Name and Value fields. To access the properties from the button command use PROP1 for the first property, PROP2 for the second and so on.
By default all properties are organized in a single layout column, making them appear stacked in the panel. To safe space or organize them visually it's possible to have two or more properties aligned in a row. When entering the property names in the Name field enclose the ones to be grouped in either round or corner brackets, i.e. (X Axis;Y Axis;Z Axis) or [X Axis;YAxis;Z Axis]. The values in the Value field don't need to be grouped. When more than two properties are grouped their labels will not be shown to safe space.
- Select the group the tool should be placed in from the Group dropdown menu.
- Choose the tool the new tool should be added after from the After Tool dropdown menu.
- Activate the New Set checkbox.
- Enter a name for the set in the Set Name field.
- Enter the number of buttons per row in the Row Buttons field. If there are more buttons than the defined number a new row will be added.
- Enter the Labels, Commands, Tooltips and Icons in the respective fields in a semicolon-separated style. The number of items have to match across each of the fields. If the buttons only should contain icons or symbols, as defined by the Icons field and the optional check box Icon Only, the button Labels still need to be defined as this is mandatory for registering the buttons.
- Optionally add one or more properties to the set.
- Press Add Tool.
- Select the group the toggle should be placed in from the Group dropdown menu.
- Choose the tool the new toggle should be added after from the After Tool dropdown menu.
- Activate the Add-on Toggle checkbox.
- Select the add-on from the Add-on dopdown menu. Note: Not all add-ons can be activated/deactivated outside of the preferences window. If a add-on is not listed it's likely that it's not compatible with the toggle script. For any non-default Blender add-ons please also check if toggling the add-on creates any errors in the console window.
- Optionally edit the Name and Tooltip for the add-on.
- Press Add Tool.
- Select the group you want to delete from the Group dropdown menu.
- Make sure the Tool dropdown menu shows ––– Select –––.
- Press Delete.
- Select the group the tool belongs to from the Group dropdown menu.
- Select the tool you want to delete from the Tool dropdown menu.
- Press Delete.
- Select the group you want to edit from the Group dropdown menu.
- Make sure the Tool dropdown menu shows ––– Select –––.
- Edit the name for the group in the Name field.
- Press Edit.
- Select the group the tool belongs to from the Group dropdown menu.
- Select the tool you want to delete from the Tool dropdown menu.
- Edit the tool data as when adding a tool. To keep the current data contained in a field it's also possible to put in an asterisk (*) for better readability.
- Press Edit.
Note: When editing tools the Add-on Toggle and New Set checkboxes are being shown, to indicate if a tool belongs to either of them. This assignment is read-only, even though it's possible to toggle the state of the checkbox; changing the state doesn't affect the updated configuration.
- Select the group you want to reorder from the Group dropdown menu.
- Make sure the Tool dropdown menu shows ––– Select –––.
- Press the Move Up or Move Down button to change the position of the group in the list. The new order is only being updated when applying the changes. But when opening the Group downdown list the changed position can be reviewed.
- Press Apply Order.
- Select the group the tool belongs to from the Group dropdown menu.
- Select the tool you want to reorder from the Tool dropdown menu.
- Press the Move Up or Move Down button to change the position of the tool in the list. The new order is only being updated when applying the changes. But when opening the Tool downdown list the changed position can be reviewed.
- Press Apply Order.
- Make sure that you have a text editor open to view the command in.
- Select the group the tool belongs to from the Group dropdown menu.
- Select the tool you want to delete from the Tool dropdown menu.
- Press View Command.
- Press the folder icon to the right of the Import field.
- Select the JSON file of the configuration you want to import a group or tool from.
- From the Command dropdown menu choose the group or tool. Tools are indented in the list for better recignition. If a group name is selected the entire group with all included tools is imported. If a tool name is selected only this tool will be imported.
- From the Group dropdown menu choose the group the tool should be added to.
- Press Import.
Adding a new language for the interface only requires a few steps.
- Create a new language file. There is a separate file for each language located in the subfolder locales of the add-on. The naming convention follows the ISO 639-1 language codes. Use the strings_en.py as a starting point for an automated translation and correct the result if needed.
- To add the new language to the selector in the add-on preferences it's necessary to edit the file language.py. Add the new language to the variables LANGUAGE_FILES and LANGUAGE_ITEMS, following the style of the existing items.
- Restart Blender.