Houdini 20.5 Reference Windows

Viewer Handle Browser window

The Viewer Handle Browser window lets you list and manage python viewer handles loaded in Houdini.

On this page

Overview

The browser offers the following functionalities:

  • List all registered Python handles.

  • Inspect the content of Python handles.

  • Identify Python handles with errors.

  • Access the Python handle code from a file.

  • Display messages in a console area.

  • Add message markers to the console.

  • Trace the execution of a Python handle.

  • Display the content of a Python handle object in the console.

  • Edit, load, reload and unload Python handles.

  • Code generator to help with the implementation and learning curve of Python handles.

The main components of the browser are the toolbar to access all the functionalities, a tree view to display the Python handles currently registered in Houdini and a console for logging information messages. In addition, the viewerhandle.utils.DebugAid utility lets you to drive the browser debugging features from a Python handle class.

The browser is available as a Python panel. You can access the browser by clicking the new tab icon in the network editor and selecting New Pane Tab Type ▸ Inspectors ▸ Viewer Handle Browser.

Tree View

The browser lists all registered python handles in a tree view located on the left side. Each tree node represents a python handle.

Tree Node

Tree nodes can be expanded to inspect the handle properties along with its bound elements. A tree node will typically (but not always) contain the following information:

  • Categories: List of state context categories (e.g. SOP or Object) the Python handle can be used from.

  • Errors: Runtime and registration error messages.

  • Exported Parameters: The list of handle parameters usable by states for binding node parameters.

  • Gadgets: List of gadget drawables registered by the handle.

  • Icon: The name of the handle icon.

  • Label: The handle UI label (used for the tree node name).

  • Menus: The handle context menu structure.

  • Parameters: The list of parameters registered for the handle.

  • Settings: The list of settings registered for the handle.

  • Source: The path to the handle implementation.

  • Type: The handle type name.

  • Warnings: Runtime and registration warning messages.

Tree Node Menu

A contextual menu is available for each tree node and contains action items specific to Python handles.

  • Edit: Opens a python editor and load the underlying Python handle module file.

  • Expand All: Expands the tree node along with all its sub-nodes.

  • Reload: Reload the handle.

  • Unload: Unload the handle. Unload removes the entry from the browser, use File|Load Handle... to load the handle again.

Console

The console window is used for logging messages such as runtime errors, warnings, debugging and user messages.

The following buttons are available:

Clears the content of the console.

Prefix messages logged in the console with the actual time.

Adds a line marker in the console. Can be used as a message separator.

Dumps the content of the active handle to the console for inspection.

Toggle button for enabling or disabling the message logging of the active handle.

Toggle button for enabling or disabling a call trace of the active handle event methods.

Toolbar

You use the toolbar to access the browser functionality through menus, select filters for displaying Python handles in the tree view or to open the help page for python viewer handles.

Toolbar menus

  • File

    • New Handle…

      Opens the Viewer Handle Code Generator dialog to create a new Python handle. The tree view should list the new handle if the creation is successful.

    • Open File…

      Opens a python file in the Python file editor. If you opened a Python handle file, the handle is not registered upon closing the Python file editor, therefore it will not be listed in the tree view.

    • Load Handle…:

      Loads (registers) a Python handle file from disk. The tree view should list the handle if the load is successful.

    • Unload Selected Handle:

      Unloads (unregisters) the selected handle in the tree view.

    • Reload Selected Handle:

      Reloads (unregisters/registers) the selected handle in the tree view.

    • Reload All Handles:

      Reloads all Python handles currently listed in the tree view along with new Python handle files.

    • Load Examples:

      Loads the Python Handle examples into Houdini. This installs all resources required to run the example scenes. See the Demo Viewer Handle shelf tools for the example scenes you can load.

  • Edit

    • Edit Selected Handle…

      Opens the selected handle in a Python editor for editing.

  • Debug

    • Inspect Handle

      Inspects the content of the selected handle.

    • Trace Options

      Opens a dialog for configuring the tracing functionality of viewer handles. For instance, you can select the event handlers you want to enable for tracing, or unselect event handlers to keep them off tracing.

Display Filters

Display filters are used for listing specific Python handles in the tree view.

  • All

    Show all handles.

  • Dop

    Show all DOP handles only.

  • Lop

    Show all LOP handles only.

  • Object

    Show all OBJ handles only.

  • Sop

    Show all SOP handles only.

  • Unknown * NOTE:

    The Unknown category typically lists Python handles with errors.

Buttons

The following buttons are available in the toolbar.

Reloads all handles currently listed in the tree view.

Opens the python viewer handles documentation page.

Windows