This class is used for defining a python viewer handle template. Use this class to set the configuration and create the handle bindings like gadgets, parameters and context menu in order to create the template. Houdini uses this template for registering the viewer handle and to create instances of the viewer handle.
See Python handles for more details on how to create your python viewer handles.
Methods ¶
__init__(name, label, categories)
Creates a new instance of ViewerHandleTemplate
representing a viewer handle type.
A viewer handle is identified by a name and a list of categories such as SOP
and OBJ
. The name
is the custom type of the viewer handle and must be unique. The list of categories specifies in
which context(s) the viewer handle can be used.
name
A unique name to define the handle type.
label
A string representing the handle descriptive name.
categories
A list of hou.NodeTypeCategory objects to describe the context(s) supported by the handle.
Here’s the list of the supported contexts:
Use the functions below for adding the contexts to the categories
list.
For SOP states use:
hou.sopNodeTypeCategory()
For OBJ states use:
hou.objNodeTypeCategory()
For LOP states use:
hou.lopNodeTypeCategory()
For DOP states use:
hou.dopNodeTypeCategory()
typeName()
→ str
Returns the handle type name.
categories()
→ list
of hou.NodeTypeCategory
Returns the list of supported contexts for this template.
bindFactory(callable)
Takes a callable object (such as a class or function) that returns the viewer handle class.
bindGadget(drawable_type, gadget_name, gadget_label=None, parms=None)
Binds a gadget drawable to a viewer handle. A gadget is a special geometry drawable which provides visual interaction support to viewer handles with picking and locating capabilities. Gadget drawable instances are created by Houdini, you don’t create objects of this type by yourself. See hou.ViewerHandleTemplate.bindFactory for details on how to access the gadgets in a viewer handle class.
geometry_drawable_type
The gadget geometry type. The following types are supported:
gadget_name
The gadget name string identifier.
gadget_label
An optional description name. Defaults to None.
parms
A list of handle parameter names the gadget requires for visual interaction. Houdini will make the gadget available
to the python handle’s handle_gadgets dictionary only when all its required parameters are
bound to an asset. For instance, if the gadget requires parms X and Y and all of them are bound, the gadget will be
made available when the handle is activated. However, if only parm X is bound, the gadget will not be available at all.
This means the gadget will not be part of handle_gadgets
. In this case, the python handle implementation should make
sure to not access an unbound gadget.
Defaults to None.
bindMenu(menu)
Attaches a context menu to this viewer handle. You can only bind one single context menu per template.
bindParameter(param_type, name, label=None, default_value=None, num_components=1, min_limit=0, max_limit=1, visible=True)
Defines a viewer handle visual parameter. A viewer handle implementation can expose these parameters to Houdini so users can change them visually through its gadgets. You can also change these parameters from the Handle dialog (with the 'P' hotkey or from the viewport context menu). This workflow however is mostly used for debugging purposes.
A viewer handle should implement the onParmChangeEvent
handler to react to parameter changes.
See viewer handle event handlers for details.
name
The parameter name identifier. The name cannot be empty and must be unique within the handle.
default_value
The default value of the parameter. This is the value Houdini uses to initialize the parameter.
The value type should ideally match param_type
but Houdini will do its best to convert the
type appropriately. Defaults to None.
label
The parameter label. If sets to None
(default), the label is set with the parameter name.
min_limit
Describes the minimum value the parameter can be set with. Defaults to 0. Used with the following types:
max_limit
Describes the maximum value the parameter can be set with. Defaults to 1. Used with the following types:
num_components
Specifies the number of components to create for the parameter template. A maximum of 3 components is allowed, the default number of component is 1. Exceptions are raised if the value is invalid.
num_components
> 1 is supported for the following types:
param_type
The viewer handle parameter type. These types are supported:
An exception is raised for other types.
visible
Controls whether the parameter is visible or not in the Handle Parameter Dialog. Defaults to True.
Note
If the parameter is not exported, Houdini will mark it as invisible regardless of the visible
argument setting.
bindSetting(param_type, name, label=None, menu_as_button_strip=False, menu_items=None, num_components=1, default_value=None, min_limit=0, max_limit=1, align=False)
Binds a setting parameter to a viewer handle. A setting is a non-visual parameter typically used for configuring or setting a viewer handle workflow. They are accessible from the Handle dialog.
A viewer handle should implement the onParmChangeEvent
handler to react to setting parameter
changes. See viewer handle event handlers for details.
align
Specifies how the parameter is aligned in the Handle Dialog
. If True, the parameter is
aligned horizontally with the next bound parameter. If False, the parameter is displayed below
the previous one. Defaults to False.
default_value
The default value of the parameter. This is the value Houdini uses to initialize the parameter.
The value type should ideally match param_type
but Houdini will do its best to convert the
type appropriately. Defaults to None.
Parameter type |
Value type |
---|---|
The value is ignored. |
|
Menu item identifier as defined with |
|
Toggle state as a bool or int. |
name
The parameter string identifier. The name cannot be empty and must be unique in the handle template or an exception is raised.
label
The parameter label. If sets to None
(default), the label is set with the parameter name.
min_limit
Describes the minimum value the parameter can be set in the UI dialog. Defaults to 0. Used with the following types:
max_limit
Describes the maximum value the parameter can be set in the UI dialog. Defaults to 1. Used with the following types:
num_components
Specifies the number of components to create for the parameter template. Defaults to 1. Exceptions are raised if the value is invalid.
num_components
> 1 is supported for the following types:
param_type
The type of parameter to bind. The following types are supported:
An exception is raised for other types.
bindIcon(icon_name)
Sets the icon image of this viewer handle.
icon_name
The name of the icon. Defaults to MISC_python
. The icon name can be specified as follows:
-
As a single name.
-
As a path to the image icon file on disk. There is no convention for where to put icon files on disk.
eg.
template.bindIcon("$HOUDINI_USER_PREF_DIR/config/Icons/myicon.pic")
exportParameters(params)
Exposes specific viewer handle parameters to Houdini. Exported parameters can be used by viewer states for binding dynamically or statically viewer handles.
params
List of parameters defined with hou.ViewerHandleTemplate.bindParameter.
bindHotkeyDefinitions(definitions)
Binds a hotkey definitions object to this viewer handle that defines the hotkey commands and contexts implemented by the handle. You can only bind one such definitions object per template.
definitions
The hou.PluginHotkeyDefinitions object to add.
See also |