On this page |
Overview ¶
The Handle
class lets you manipulate handles bound to viewer states.
Methods ¶
__init__(scene_viewer, name)
Creates an object for accessing a handle of a given name. hou.Handle is typically used with python viewer states.
Warning
Handle objects are typically created from a python viewer state constructor. However, calling
methods on Handle
objects must be done once the state has been entered, exceptions will be
raised otherwise.
scene_viewer
A hou.SceneViewer object referencing the scene viewer where the handle is going to be used. Exception is thrown if the scene viewer is not compatible.
name
A string to identify the handle object. The name corresponds to the handle’s name used at binding time. See hou.ViewerStateTemplate.bindHandle or hou.ViewerStateTemplate.bindStaticHandle for details.
class MyState(object): def __init__(self, state_name, scene_viewer): self.state_name = state_name self.scene_viewer = scene_viewer self.handle = hou.Handle(scene_viewer, "Transform") # Create a template to describe the state and its bindings template = hou.ViewerStateTemplate("mystate", "My Custom State", hou.sopNodeTypeCategory()) template.bindFactory(MyState) template.bindHandle("xform", "Transform")
name()
: → string
The name of this handle.
label()
: → string
The label of this handle for UI display purposes.
show(value)
Shows or hides the handle.
value
Bool
value, True
to show the handle, False
to hide it.
type()
: → string
Returns the type name of the handle. The return value corresponds to the type used for binding the handle. See hou.ViewerStateTemplate.bindHandle or hou.ViewerStateTemplate.bindStaticHandle for details.
update(immediate, node_update=False, force_update=False)
Updates the handle if the value in any of its parameters has changed. Useful if a change made to a viewer state requires one of its handle to get updated. For dynamic handles, this will trigger a call to the onStateToHandle
callback, allowing the viewer state to update the proper handle parameter(s).
immediate
Controls when the update is performed. If False, the update is delayed until Houdini is on idle. If True, the update is performed immediately. Defaults to False.
node_update
Calling update
updates the handle parms by default. Set node_update
to True
to update the state node parms bound to the handle instead.
Note
This flag is supported for python viewer handles only.
force_update
Forces the underlying handle to update (default to False). Typically used with HUD handles to refresh their UI.
Note
This flag is supported for python viewer handles only.
visible()
: → bool
Returns True
if the handle is visible, False
otherwise.
isValid()
: → bool
Returns True
if the handle has been created properly, False
otherwise.
isActive()
: → bool
Returns True
if the handle has been activated, False
otherwise. This method indicates the handle has been initialized and activated by the current state.
enableParms(parm_names)
Dynamically enables the parms of this handle specified with parm_names
. If handle_parms
is
empty (default), all handle parms are enabled.
Raises exception if the handle is not bound dynamically to a viewer state.
Note
Some handles like xform
may not display its components right away when enabled. This can
happen if the components were previously disabled. For instance, disabling the rotation (rx,ry,rz)
and re-enabling it again will not restore the previous rotate mode to display the rotation knobs.
Restoring the rotate mode must rather be achieved by cycling the Y
key or by calling
hou.Handle.applySetting.
See also hou.Handle.disableParms.
parm_names
A list of names specifying the handle parms to enable. parm_names
must contain the handle
parm names as described here. Exception is raised if
parm_names
contains unknown parm names.
disableParms(parm_names)
This method does the opposite of hou.Handle.enableParms and dynamically disables the
handle parms specified in parm_names
. If handle_parms
is empty (default), all handle parms
are disabled.
Raises exception if the handle is not bound dynamically to a viewer state.
parm_names
A list of names specifying the handle parms to disable. parm_names
must contain the handle
parm names as described here. Exception is raised if
parm_names
contains unknown parm names.
applySettings(settings)
Apply one or more settings to this handle.
settings
A string containing the handle specific settings. Multiple settings must be space separated.
isPersistent()
: → bool
Returns True
if the handle is a persistent handle, False
otherwise.
makePersistent(value)
Turns this handle to a persistent handle to make it visible when the node’s handle is not selected.
value
If True
, the handle is set as a persistent handle. If False
, the handle is set to non-persistent and will only be visible when the node is selected.
Note
HUD handles, like HUD handles for parameters, are deleted and removed from the viewer if value
is False
.
parmPaths()
: → list of string
Returns all parm paths mapped to this handle. A parm path is useful for creating a hou.Parm
object.
nodePath(index)
: → string
Returns the node path for this handle.
index
The node index. Defaults to 0.
info()
: → string
Returns a JSON dictionary string representing the python handle definition for this handle. Returns an empty string if the underlying handle type is not a python handle.
See also hou.ui.viewerHandleInfo
isDynamic()
: → bool
Returns True
if the handle is bound to a python state dynamically.
makeAsDefault()
Make the current handle parms values the new default for the underlying handle type.
revertToDefault()
Set the current handle parms values with the handle default values.
revertToFactoryDefault()
Set the current handle parms values with the parms default values of the node definition. NOTE
This method overwrites the current handle parms default values as well.
exportToHDA()
Adds the handle and its parms to the currently open digital asset editor.
exportParmsToHDA()
Adds the handle parms to the currently open digital asset editor.
beginUndo()
Opens an undo block to perform undoable operations with the underlying handle. All operations performed after
endUndo()
Closes an undo block previously opened with hou.Handle.beginUndo.