HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
The .ui Script Language

.ui Script Overview

.ui Script is a simple text-based script which Houdini parses to build user interfaces. Its basic syntax looks like:

// Single UI value assignment
value := <int|float|string> ;
// Simple menu item list
menuvalue = [SELECT_MENU|STRING_MENU]
{
"item1"
"item2"
}
//grouping gadget
[gadgetname =] [containertype]
{
[attributes]
[gadgets]
}
//single gadget
gadgetname = type attributes ;

Values and gadgets can have names assigned to them, which must be unique in the script (and if an AP_Interface parses more than one script, unique in all scripts parsed). Names are alphanumeric strings with underscores and periods allowed.

A gadget is a UI_Feel/UI_Look pair which defines a single UI element, like a button or a menu. An attribute modifies the default behavior or look of the gadget. Gadgets can be nested inside other grouping gadgets. The simplest group gadgets are "ROW { }" and "COL { }", which create horizontal and vertical layouts.

UI Basics

A .ui script file can use basic preprocessing commands, such as include and define. Otherwise, the file is basically a series of value assignments, gadget container blocks and commands.

A value assignment will create the named value if it does not already exist, and assign a value to it. All values are created on the fly as they are referenced unless previously set using AP_Interface::setValueSymbol(). Some examples of variable declarations:

lod.val := 1.0;
filename.val := "defgeo.bgeo"
color.val[0] = 0.0f;
color.val[1] = 0.0f;
color.val[2] = 0.0f;
color.val[3] = 1.0f;

In the above examples, color.val must be a UI_Vector (which can be defined in the .ui file as color.val[4]).

Top-level gadget definitions must have a name in order for them to be referenced elsewhere in the .ui file and by Houdini. Nested gadgets can also have names in case they need to be referenced as well. To insert a gadget into a container, reference it by name. Additional attributes can be specified on the gadget if desired.

filename.val := "defgeo.bgeo";
filename.gad = FILENAME_FIELD(geo) "Geometry File":1.5 VALUE(filename.val);
dialog.win = DIALOG "Save As..."
{
HSTRETCH LOOK(plain) LAYOUT(vertical) JUSTIFY(center, center)
VALUE(open.val)
filename.gad HSTRETCH;
ROW
{
ACTION_BUTTON "Save" VALUE(save.val) SENDS(1);
ACTION_BUTTON "Cancel" VALUE(save.val) SENDS(0);
}
}

Note in the above example that 'save.val' was not declared or assigned before being used by both the Save and Cancel buttons. It would be created by the Save button, and re-referenced by the Cancel button. All values have a initial value of 0 or "".

Note
Gadgets must be defined before being referenced, or an error will occur.

Commands can also be used in the .ui file:

OPEN dialog.win;
DISABLE filename.val;
Note
OPEN commands are normally just for debugging, as they will only be executed once when parsing the .ui file. If it is reused, the dialog won't be opened.

List of Gadgets

Single gadgets are always specified as gadget attributes; while containers are specified as gadget { attributes gadgets } . If there are parameters listed beside the gadget type, these must be present in the order specified. Some parameters are optional (in []).

Buttons

ACTION_BUTTON "Label"

An action button changes a value temporarily. The actual value of the value is rarely important, however, you can use the SENDS(#) syntax to send a specific value (useful for closing windows).

TOGGLE_BUTTON "Label"

A toggle button switches between 0 and 1. 1 is selected.

ACTION_ICONBUTTON "iconname"

An icon action button is similar to a regular action button, but instead of using a text label, it uses an icon. The behavior is the same. This type of button is best used in toolbars and other places where space is at a premium.

TOGGLE_ICONBUTTON "iconname" An icon version of TOGGLE_BUTTON.

The "Label" syntax can be extended with :#. The floating point constant after the colon defines the width of the label area. ie, "Filename":1.5 would create a left justified, 1.5 unit-wide label. 1 unit is about 90 pixels in the Normal UI size.

Note
Icons must be in the HOUDINI_UI_PATH in order to be found.

Menu Buttons

SELECT_MENU_BUTTON ["Label"] MENU(dynmenuref)

This menu button allows the user to select one of the choices, and displays the currently picked choice as the label of the button. dynmenuref is a reference to a dynamic menu, either a SELECT_MENU or a STRING_MENU. The optional "Label" is placed to the left of the menu.

SELECT_MENU_ICONBUTTON MENU(dynmenuref)

This menu is a selection menu, but it only displays the icon as the label, not the text. This is used almost exclusively in toolbars, where space is premium. It should not be used in dialogs. dynmenuref is a reference to a dynamic icon menu, either SELECT_ICON_MENU or STRING_ICON_MENU. Regular SELECT_MENUs or STRING_MENUs are not compatible with this gadget.

ACTION_MENU_BUTTON "Label" MENU(menuref)

ACTION_MENU_BUTTON valueref MENU(menuref)

This menu button allows the user to select a choice, which performs some action. The choice does not remain selected. The label on the button is static.
menuref is a reference to either a static or dynamic menu.
valueref is a value, which allows you to change the name of the label.

ACTION_MENU_ICONBUTTON "iconname" MENU(menuref)

ACTION_MENU_ICONBUTTON valueref MENU(menuref)
This menu button allows the user to select a choice, which performs some action. The choice does not remain selected. The icon on the button is static.
menuref is a reference to either a static or dynamic menu.
valueref is a value, which allows you to change the icon.

Menu buttons can use dynamic menu values rather than regular values. These are defined as:

menuref = SELECT_MENU
{
"item1"
"item2"
"item3"
}
menuref = STRING_MENU
{
"item1"
"item2"
"item3"
}
menuref = SELECT_MENU
{
ICONTEXT( "iconfile1", "item1" )
ICONTEXT( "iconfile2", "item2" )
ICONTEXT( "iconfile3", "item3" )
}

The first menu would have a menu of three items named item1, item2 and item3, and report the selected value as 0, 1 or 2.

The second menu would have the same menu items, but report the selected value as "item1", "item2" or "item3" (minus the quotes).

The third menu uses both mix both icons and text, and must be used for the ICON versions of the buttons. Both the icon and the text are shown in the popdown menu. SELECT_MENU or STRING_MENU can be used (the string value returned is still the text).

Warning
Using a regular value for a MENU() attribute will cause an error.
Do not use a VALUE() attribute with MENU().

Fields

STRING_FIELD ["Label"[:label_width]]

Basic string field, allows all characters. All fields come with an optional "Label" parameter which is specified after the field and an optional numeric value for the label width.

ALPHANUM_FIELD ["Label"[:label_width]]

Same as string, but only allows a-zA-Z0-9 and _. Variables are allowed, but the string is converted to alphanum after expansion.

STRING_LIMITED_FIELD("chars" ) ["Label"]

A string field, with a list of valid characters that can be entered. chars is a list of allowed characters. Ranges may be used ("A-z", "0-9"). To use '-', backslash it, or specify that character first.

FILENAME_FIELD(type) ["Label"]

Field for file names. Comes with a history field, and a file browser button (to the right).
type - specifies the file type: all, pic, picseq, geo, geoseq, chan, audio, script, otl, hip.

STRING_MENU_FIELD ["Label"] MENU(menuref)

STRING_MENU_FIELD(type) ["Label"] MENU(menuref)

A field which combines a string field and a menu. The menu can be used to replace or add/remove an item to the list. The menu button looks like the RHS of a SELECT_MENU_BUTTON, attached to the field.
type - the replacement type that occurs when a menu item is selected: replace, append, appendwild ('*' replaces the entire string). If not specified, 'replace' is used.

LABEL "Label"

LABEL VALUE(value)

LABEL(textlook) VALUE(value)|"Label";

A non-interactive label. The second usage uses a variable to determine the label value. VALUE() does not need to be next to LABEL, you can mix it in with other attributes, or assign it manually with setValueReference(). A LABEL with no string or value is an error.
The third usage allows you to specify a specific text look for the label, such as bold or fine print (among many others).

SQUISHY_LABEL "Label"

SQUISHY_LABEL VALUE(value)

SQUISHY_LABEL(numchars) VALUE(value)|"Label"

The SQUISHY_LABEL types are, for the lack of a better word, "squishy". They can shrink to smaller than their full label size, down to numchars letters (or 4 letters, if not specified) if space is not available. You should use squishy labels when the text is user-defined (like a node name, file path, etc), as these text strings can be quite verbose. If you don't, your nice compact layout may suddenly become undesirably wide. Other than this, they behave like normal labels.

INT_FIELD ["Label"]

Allows ints and variables, always returns an int to its value. Invalid entries turn the field red. Expressions will not work in these fields.

FLOAT_FIELD ["Label"]

Allows floats and variables, always returns a floating point value. Invalid entries turn the field red. Expressions will not work in these fields.

FLOAT_VECTOR_FIELD(size) ["Label"]

Creates several fields beside one another for generic vector input. size is the vector size (must be at least 2)

INT_VECTOR_FIELD(size)

Creates several fields beside one another for generic vector input. The values are always returned as ints (useful for resolution, divisions, etc). size is the vector size (must be at least 2)

COLOR_FIELD ["Label"]

Creates a vector3 field for RGB plus a color swatch which will popup a color editor. The swatch is located on the LHS of the fields.

COLOR_ALPHA_FIELD ["Label"] Creates a vector4 field plus a color swatch for RGBA. Otherwise, the same as a COLOR_FIELD.
Note
To read values from a vector field, you must use the vector UI_Value::getValue() methods.

Sliders

FLOAT_SLIDER ["Label"]

A slider that returns a FP value between min & max (default 0-1).

INT_SLIDER ["Label"]

A slider that returns an integer between min & max. Tick marks are drawn, and the thumb will only stop at integral positions.

FLOAT_SLIDER_FIELD ["Label"]

This field provide a FP field with a FP slider, tied together. A label is optional.

INT_SLIDER_FIELD ["Label"]

This field provide an integer field with an integer slider, tied together. A label is optional.

INT_SPINNER_FIELD(incrementsize) ["Label"]

A spinner fields contain a field and a set of plus/minus buttons (the spinner), with an optional label. They are laid out as label, field, spinner. The label is fixed, depending on the string width (or the size specified with the label). The spinner buttons may be held down for continuous incrementing/decrementing.

FLOAT_SPINNER_FIELD(incrementsize) ["Label"] The floating point version of a SPINNER_FIELD.
Note
The RANGE(min,max) attribute can be used to specify the range of the slider. The value may be end up outside this range, unless additional LOCK_RANGE_MIN, LOCK_RANGE_MAX, or LOCK_RANGE attributes are specified. RANGE() and the other attributes may be specified in any order after the SLIDER declaration.

Static Menus

MENUBAR { menubaritems }

Defines a menubar with a list of MENUBAR_ITEM's.

MENUBAR_ITEM "Label" MENU(staticmenuref);

staticmenuref is a reference to a static menu. Dynamic menus can be used by embedding a dynamic menu strip in the static menu.

MENU { menuitem ; menuitems }

Defines a static menu with a list of menuitems.

MENU_ITEM_ACTION "Label" [HOTKEY(h.pane.hotkey, keyvalue)]

MENU_ITEM_ACTION namevalue VALUE(valueref) [HOTKEY(h.pane.hotkey, keyvalue)]

Action menu items are similar to action buttons, in that they send a value but don't store any values.
namevalue is a value whose string will be used for the label instead of a static label.
h.pane.hotkey is the hotkey symbol that will be sent to keyvalue.
valueref will be assigned '1' when pressed.

MENU_ITEM_TOGGLE "Label"|namevalue VALUE(togglevalue)

MENU_ITEM_TOGGLE "Label"|namevalue VALUE(togglevalue) HOTKEY(h.pane.hotkey)

A Toggle menu item is a regular checkbox toggle, but inside a menu.
namevalue is a value whose string will be used for the label instead of a static label.
h.pane.hotkey is the hotkey that is displayed. Pressing it while the menu is opened will toggle the item.
togglevalue is the value that contains the on (1) / off (0) state of the toggle.

MENU_ITEM_PARENT "Label" MENU(menuref)

A parent menu item is an item that has a submenu off to the right. It does not send values or hotkeys; the user locating over it will open its submenu.
menuref is a reference to a static or dynamic menu.

MENU_SEPARATOR

Draws an unselectable divider.

MENU_ITEM_TITLE "Label"

A non-selectable title used to introduce a logical group of items (use sparingly - most logical groups should be obvious from their items' names).

MENU_STRIP_RADIO { VALUE(valueref) radioitem ; radioitems }

Radio buttons must be used inside a radio strip.

MENU_ITEM_RADIO "Label"

A radio menu item is used to select one of several persistent exclusive choices. Radio menu items can only be used inside a RADIO_MENU_STRIP. The first item will be assigned a index of 0, and subsequent items increment by 1. Selecting the radio item sets the radio strip's value to the appropriate index.

MENU_STRIP MENU(menuref)

A menu strip allows you to embed another MENU feel inside a MENU, which is good for keeping logical sets of menu items in chunks. It's entirely optional o use; embedding a menu is identical to just adding its items to the parent menu.
menuref is the static MENU feel to embed. To embed a dynamic menu, use a dynamic menu strip instead (below).

MENU_STRIP "Title" MENU(menuref)

A menu strip with a title menu item placed above it.
menuref is the static MENU feel to embed. To embed a dynamic menu, use a dynamic menu strip instead (below).

MENU_STRIP_DYNAMIC MENU(menuref)

MENU_STRIP_DYNAMIC_RADIO MENU(menuref)
A dynamic menu strip allows you to embed a dynamic menu into a MENU, with a variable number of items, often used for list selection (history lists, takes, renderers, etc). The first syntax simply lists the items; the second adds radio buttons beside the items and indicates the currently chosen item.
menuref is a reference to a dynamic menu.
Note
The :# label syntax is not supported in menus. The menu will be as wide as its largest item.

Containers

SCROLLER direction

Creates a scrollable area with either one or two scrollbars.
direction may be horizontal, vertical or full (both).

TOOLSCROLLER

Creates a scrollable area in one direction, specified by the LAYOUT attribute. Scroll arrows pop up at either end when the area is cramped.

SWITCHER [tight]

Shows only one of the child feels. The VALUE() defines which feel is shown. A tight switcher is sized to the currently displayed child, while a regular switcher always takes the size of the largest child dimensions.

SPLITPARENT

Divides two child feels with a resizeable split. Only two feels are supported. The direction of the split motion is determined by the LAYOUT attribute.

OPENNOTIFIER

A regular feel that sets its value to 1 when it is opened, and 0 when it is closed. If the VALUE() attribute is not set, it acts as a normal feel.

STOWBAR direction "Stowbar name"

Creates a stowbar that hides the contained gadgets and replaces them with a stowbar.
direction can be left, right, top or bottom, which determines both the orientation and the layout of the collapse hint arrow.

COLLAPSER "Label"

Creates a gadget with a title label and its children underneath. When the title bar is clicked, it hides its children and restore them when clicked again.

ROW

A simple horizontal layout.

COL

A simple vertical layout.

BUTTONSTRIP striptype

Defines a strip of buttons. striptype can be one of

  • normal - Each button has its own value and acts independent of the others.
  • radio - Exactly one button is selected in the group, and the button strip value is the index of the button selected.
  • bitmap - Each button can be toggled on or off, and the resulting buttonstrip value is a bitmask of the on/off states (first button = bit 1).
  • onemax - Either one or no buttons can be selected in the group. The value is the index of the button selected, or -1 if nothing is selected.

ICON_BUTTON_STRIP

Defines a button strip populated with the *_ICONBUTTON types (ACTION, TOGGLE, MENU).

ICON_RADIO_STRIP

Defines a button strip populated with icon buttons, where exactly one button is be selected at once. All children must be RADIO_ICONBUTTONs. The strip should have a VALUE() attribute to report the button selected. The first button is indexed as 0.

ICON_ONEMAX_STRIP

Defines a button strip populated with icon buttons, where at most one button can be selected at once. All children must be RADIO_ICONBUTTONs. The strip should have a VALUE() attribute to report the button selected. The first button is indexed as 0.

ICON_STRIP_GROUP

Creates a button strip that can contain various types of icon buttonstrips: ICON_BUTTON_STRIP, ICON_RADIO_STRIP and ICON_ONEMAX_STRIP.

TABDIALOG

Defines folders and the tabs to switch between them. Inside TABDIALOG there are TAB gadgets that specify the contents of each folder. Eg,

folderA.gad = { LABEL "Contents of folder A."; }
folderB.gad = { LABEL "Contents of folder B."; }
TABDIALOG
{
VALUE(folder_value.val) STRETCH
TAB "Folder A" : folderA.gad;
TAB "Folder B" : folderB.gad;
}

The syntax of all containers is:

<containertype>
{
<attributes>
<gadgets>
}
ie.
TOOLSCROLLER
{
LAYOUT(horizontal) HSTRETCH
ACTION_ICONBUTTON "BUTTON_go" VALUE(go.val) SENDS(1);
ACTION_ICONBUTTON "BUTTON_stop" VALUE(go.val) SENDS(0);
}

Windows

NORMAL_WINDOW "Window Name" [ICON(iconname)]

Creates a floating window which has its own minimize/maximize buttons, which is not associated with the main Houdini window. These types of windows are normally used for long term dialogs.
iconname specifies an icon for the window to be used by the window manager.

DIALOG "Window Name" [ICON(iconname)] Creates a floating window which is parented to the main Houdini window. Most window managers will not allow this window to be pushed behind the main Houdini window, nor be minimized.
iconname specifies an icon for the window to be used by the window manager.
Note
Behavior of NORMAL_WINDOWs and DIALOGs can differ slightly between platforms and window managers. A common pitfall is a missing maximize button if the window does not have the STRETCH attribute applied.

Attributes

Attributes can be used to modify the default look and feel of a gadget, as well as its layout. Container gadgets tend to have attributes that affect layout and look, while interaction gadgets tend to have attributes that deal with the manipulation of its value.

Some attributes can only be used on specific types of gadgets. These attributes are listed separately below. Attributes can be listed after the gadget declaration in any order.

General Attributes

VALUE( val )
VALUE( val, val [,val [,val]])

Associates a value (or values) with a gadget. Almost all gadgets that have some user interaction require a value in order to communicate changes back to Houdini. The second signature can be used for vector-based fields, like a COLOR_FIELD or a FLOAT_VECTOR_FIELD.

KEYVALUE( val )

Normally set on windows, this value is changed whenever a key is pressed and contains the key value.

LAYOUT(layout)

Sets the layout of a container feel.

  • horizontal - gadgets are laid out left to right.
  • vertical - gadgets are laid out top to bottom.
  • overlap - gadgets are laid out on top of one another, from bottommost to topmost
  • cell - gadgets specify which cells they occupy in a grid

STRETCH
STRETCH(h, v)

Makes the gadget stretchable in both directions. The second signature allows you to specify floating point values for the amount of stretchiness, 0 being none and 1 being normal (and the default for STRETCH). All stretchiness values are relative to one another within the same container. A gadget with stretchiness of 2 would stretch twice as much as one of stretchiness 1; the same would occur if they were assigned as 1 and 0.5.

HSTRETCH
HSTRETCH(h)

Makes the gadget stretchable horizontally. The second signature allows the stretchiness to be specified. Useful for fields and sliders.

VSTRETCH
VSTRETCH(v)

Makes the gadget stretchable vertically. The second signature allows the stretchiness to be specified.

SIZE(w, h)

Specifies a fixed size for the gadget, in UI units. Pixels can also be used by suffixing the value with 'p' (ie, 20p). One UI unit is about 90p. Fixed sized gadgets ignore any stretch attributes applied to them.

WIDTH(w)

Specifies a fixed width for the gadget, in UI units. Any horizontal stretch is ignored, though the gadget can still stretch vertically.

HEIGHT(h)

Specifies a fixed height for the gadget, in UI units. Any vertical stretch is ignored, though the gadget can still stretch horizontally.

MIN_SIZE(w,h)
MIN_WIDTH(w)
MIN_HEIGHT(v)

Sets the minimum size of the gadget, in UI units. The gadget will never shrink to smaller than this size. The minimum can be specified together or separately in both dimensions.

PREF_SIZE(w,h)
PREF_WIDTH(w)
PREF_HEIGHT(h)

Sets the preferred size of the gadget, in UI units. The preferred size is the size the gadget would like to be laid out at, if space is available. If a min and preferred size are specified for the same dimension, but no stretch is set, the size will still float between the min and preferred size. It can be specified together or separately for both dimensions. The preferred size must be between the min and max sizes, if specified.

MAX_SIZE(w,h)
MAX_WIDTH(w)
MAX_HEIGHT(h)

Sets the maximum size of a gadget, in UI units. This is generally used in conjunction with STRETCH, to prevent a gadget from getting undesirably large. The max size must be larger than both the minimum and preferred size, if specified. The maximum can be specified together or separately in both dimensions.

MARGIN(m)
HMARGIN(hm)
HMARGIN(l,r)
VMARGIN(vm)
VMARGIN(t,b)

Sets the margins around the child gadget area in a container, in UI units.

SPACING( s )
SPACING( h, v)

Sets the spacing between children in a container, in UI units. The second signature can be used for cell layouts. This is ignored for overlap layouts.

JUSTIFY( h, v )

If the children in a container cannot grow to fill the entire area of the container, this specifies where to position the child box within the container. The horizontal options are left, center and right, while the vertical options are top, center, and bottom.

CELL(x,y)
CELL(x1,y1, x2,x2)
CELLSIZE(w,h)

Children of a cell layout must specify which cell they reside in. The layout grid grows to accommodate all the cells. By default, a cell is 1x1, but the four parameter CELL() attribute and the CELLSIZE() attribute can allow a gadget to span multiple cells.

LOOK( looktype )

Specifies the look of the gadget, though this is mostly used for container feels and windows. The common look types are plain, line, groove, bevel and beveldown.

RMBMENU( menuref )

Attaches a menu to a gadget which is triggered when the user clicks the RMB. menuref can be a static menu or a dynamic menu value.

The following attributes apply to only some gadgets.

Specific Attributes

Used on

EXCLUSIVE Windows

Specifies that the window has exclusive user access; the user cannot interact with the rest of the application while this window is open. Use sparingly.

LOOKFLAT Icon buttons

Removes the border shadow around icon buttons and draws them "inline" with the background.

LOOKFLATSTRIP Icon button strips

Removes the border shadow around icon button strips and draws them as if they were separate flat icon buttons.

LOOKSTRIP Containers

Sets the button strip border type around the container feel.

RANGE( low, high ) Sliders

Sets the usable range of a slider, from low to high.

LOCK_RANGE
LOCK_RANGE_MIN
LOCK_RANGE_MAX
Sliders

Locks the minimum and/or maximum range of a slider. Values below or above the slider will be clamped. Normally, the slider just shows an "out-of-range" arrow for values below the minimum or above the maximum.

RANGEVALUE ( value ) Sliders

Uses a dynamic range for a slider. The value must be of size 2.

MENU( menuref ) Menu Buttons, Strips

Specifies the menu to be used by the button or strip. It most cases it can be a static or a dynamic menu.

UI_FLAT_ICON_BTN_SIZE_LARGE
UI_FLAT_ICON_BTN_SIZE_SMALL
UI_FLAT_ICON_BTN_SIZE_TINY
UI_FLAT_ICON_BTN_SIZE_MICRO
Icon buttons

Defines the size of an icon button, based on some standard sizes.

UI_ICON_BUTTONSTRIP_SIZE_LARGE UI_ICON_BUTTONSTRIP_SIZE_NORMAL UI_ICON_BUTTONSTRIP_SIZE_SMALL Icon button strips

Defines the size of icon buttons within the strip.

INIT_SIZE(w,h) Icon Button Strips

Defines the default size of icons in the button strip. It is preferred that the symbolic constants for buttonstrip sizes (above) are used wherever possible.

SENDS( constant ) Action, Radio buttons Defines the constant set to the value attached to the gadget when the button is pressed. This allows multiple action buttons to share a value, but send different numbers through it when clicked.

UI commands

These commands can be run outside of any container gadget definitions.

OPEN windowref;

Opens the window called windowref. The window must already be defined. This only occurs once upon parsing the dialog, so do not use this if you plan to reuse the interface.

DISABLE valueref;

Disables the value named 'valueref'. Initially, all values are enabled. Any gadgets using this value as their VALUE() will appear dimmed.

EXPORT valueref;

Exports the value named 'valueref' to the UI_Manager. This value can then be accessed anywhere in Houdini. If used more than once with the same value name, it will overwrite the previous value. Use sparingly.