|
HDK
|
.ui Script is a simple text-based script which Houdini parses to build user interfaces. Its basic syntax looks like:
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.
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:
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.
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 "".
Commands can also be used in the .ui file:
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.
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. |
| 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:
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).
MENU() attribute will cause an error. 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). |
| 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. |
| 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. |
| 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. |
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. |
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 "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. |
| 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. |
| 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. |
| 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. |
| MENU_STRIP "Title" MENU(menuref) | A menu strip with a title menu item placed above it. |
| 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. |
Containers | |
| SCROLLER direction | Creates a scrollable area with either one or two scrollbars. |
| TOOLSCROLLER | Creates a scrollable area in one direction, specified by the |
| SWITCHER [tight] | Shows only one of the child feels. The VALUE() defines which feel is shown. A |
| SPLITPARENT | Divides two child feels with a resizeable split. Only two feels are supported. The direction of the split motion is determined by the |
| OPENNOTIFIER | A regular feel that sets its value to 1 when it is opened, and 0 when it is closed. If the |
| STOWBAR direction "Stowbar name" | Creates a stowbar that hides the contained gadgets and replaces them with a stowbar. |
| 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
|
| 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 |
| 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 |
| ICON_STRIP_GROUP | Creates a button strip that can contain various types of icon buttonstrips: |
| TABDIALOG | Defines folders and the tabs to switch between them. Inside TABDIALOG there are TAB gadgets that specify the contents of each folder. Eg, |
The syntax of all containers is:
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. |
| 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. |
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 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 |
| LAYOUT(layout) | Sets the layout of a container feel.
|
| 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 |
| 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 |
| 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 |
| LOOK( looktype ) | Specifies the look of the gadget, though this is mostly used for container feels and windows. The common look types are |
| 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 |
| 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. |
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 |
| 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. |
1.8.6