Widgets and Hints¶

Strings and Numbers¶

Integer, float or string hint values should use the common literal representation of such values (e.g. 1, 2.3, foo).

Booleans¶

Boolean hint values can be specified using true or false. For historical reasons, the following strings are also accepted: yes, no, on, off, 1, 0.

Lists¶

List hint values can be specified either using a delimited string or a nested <hintlist> XML element. Strings are delimited using a pipe character (|). The following two forms are equivalent:

<param name="someParameter" widget="fileInput" fileTypes="exr|png"/>
<param name="anotherParameter" widget="fileInput">
  <hintlist name="fileTypes">
    <string value="exr"/>
    <string value="png"/>
  </hintlist>
</param>

Child elements of <hintlist> may be of type <int>, <float> or <string>, and may specify their value in either value or default properties.

Dictionaries¶

Dictionary hint values can be specified using a delimited string or a nested <hintdict> XML element. Items in strings are delimited using a pipe character (|); keys and values are separated by a colon character (:). The following two forms are equivalent:

<param name="someParameter" widget="mapper" options="a:1.0|b:2.0|c:3.0"/>
<param name="anotherParameter" widget="mapper">
  <hintdict name="options">
    <float name="a" value="1.0"/>
    <float name="b" value="2.0"/>
    <float name="c" value="3.0"/>
  </hintdict>
</param>

Child elements of <hintdict> may be of type <int>, <float> or <string>, and may specify their value in either value or default attributes. They must also specify a name attribute.

group¶

<page> and <group> elements use the group widget type be default. It supports these hints:

presetsGroup¶

The presetsGroup widget type for pages allows you to define default values for specific parameters that are contained in/on the respective group/page. Defining a presetsGroup for a specific page results in a menu that displays in the Parameters tab for the parameters.

Widget type-specific hints:

In the example below, the <page> element’s widget is set to presetsGroup, and the element defines presets for four parameters: Kd, Kd_color, ColMap, and Ks. Each preset then contains four values: a float, a list of three floats (color), a string, and a float. For instance, the preset called Low contains the following values: 0.1,(0.1, 0.1, 0.1),"low_map",1.0.

<args format="1.0">
  <page name="Basics" open="True" widget='presetsGroup' policies='Kd,Kd_color,ColMap,Ks' presets='
      Low,0.1,(0.1, 0.1, 0.1),"low_map",1.0|
      Medium,0.4,(0.4, 0.4, 0.4),"mid_map",0.4|
      High,0.8,(0.8, 0.8, 0.8),"hi_map",0.5|
      MyPreset,1.0,(0.1, 0.2, 0.3),"Goofy",0.9'>

    <param name="Kd"/>
    <param name="Kd_color" widget="color"/>
    <param name="ColMap" widget="fileInput"/>
    <param name="Ks"/>
    <param name="Ks_color" widget="color"/>
    <param name="SpecularExponent"/>
    <param name="Ka"/>
    <param name="Ka_color" widget="color"/>
    <param name="opacity"/>
  </page>
  <page name="Textures" open="True" hide="False">
    <param name="SpecMap" widget="fileInput"/>
    <param name="RepeatS" widget="boolean"/>
    <param name="RepeatT" widget="boolean"/>
  </page>
  <page name="Bump Mapping" open="False">
    <param name="BumpMap" widget="fileInput"/>
    <param name="BumpVal"/>
  </page>
  <page name="Reflection">
    <param name="EnvMap" widget="fileInput"/>
    <param name="EnvVal"/>
    <param name="UseFresnel" widget="boolean"/>
  </page>
  <page name="Refraction">
    <param name="RefractMap" widget="fileInput"/>
    <param name="RefractVal"/>
    <param name="RefractEta"/>
  </page>
</args>

null¶

Parameters that are hinted with the null widget type are effectively hidden from the UI: no widgets are created for them. No other hints are evaluated for this type of widget.

number¶

Displays widgets for entering numeric values.

This is the default widget type used for number parameters.

Widget type-specific hints:

string¶

Displays a widget for entering text.

This is the default widget type used for string parameters.

Widget type-specific hints:

<param name="someParameter" replaceRegex="[^A-Za-z0-9_ ]" replaceWith=" "/>

checkBox¶

Displays a check box widget. When applied to string parameters, either Yes or No are set as values. When applied to numeric parameters, either 0 or 1 are applied. It has no widget type-specific hints.

color¶

Displays a widget for picking color component values.

Can be used for number parameters.

Widget type-specific hints:

scenegraphLocation¶

Displays a widget for entering and jumping to a scene graph location path.

Can be used for string parameters.

Widget type-specific hints:

cel¶

Displays a CEL statement widget.

Can be used for string parameters.

Widget type-specific hints:

text¶

Displays a multi-line text field.

Can be used for string parameters.

scriptEditor¶

Displays a multi-line text field for entering a script.

Can be used for string parameters.

Widget type-specific hints:

scriptButton¶

Displays a button that executes a Python script when pressed. All submodules from the Katana module are available from within the script. Additionally, the following local variables are available:

parameter¶

The parameter object corresponding to the script button.

node¶

The node object that owns the parameter corresponding to the script button.

exit()¶

Exits the script button script.

Can be used for string parameters.

Widget type-specific hints:

boolean¶

Like checkBox, but displayed as a menu.

popup¶

The popup widget displays a pop-up menu or combo box with literal choices for parameter values. For example:

<param name="opacity" widget="popup">
  <hintlist name="options">
    <string value="0.0"/>
    <string value="0.5"/>
    <string value="1.0"/>
  </hintlist>
</param>

Can be used for string parameters.

Widget type-specific hints:

<param name="someParameter" widget="popup" options="a|b|c"/>
<param name="anotherParameter" widget="popup">
  <hintlist name="options">
    <string value="a"/>
    <string value="b"/>
    <string value="c"/>
  </hintlist>
</param>

<param name="someParameter" widget="popup" options="a|b|c" editable="true"/>
<param name="anotherParameter" widget="popup" options="a|b|c|*"/>
<param name="yetAnotherParameter" widget="popup">
  <hintlist name="options">
    <string value="a"/>
    <string value="b"/>
    <string value="c"/>
    <string value="*"/>
  </hintlist>
</param>

mapper¶

The mapper widget presents a pop-up menu with associative choices. Each value has an associated display value. For example:

<param name="opacity" widget="mapper">
  <hintdict name="options">
    <float value="0.0" name="A"/>
    <float value="0.5" name="B"/>
    <float value="1.0" name="C"/>
  </hintdict>
</param>

Can be used for string parameters.

Widget type-specific hints:

<param name="someParameter" widget="mapper" options="a:1.0|b:2.0|c:3.0"/>
<param name="anotherParameter" widget="mapper">
  <hintdict name="options">
    <float name="a" value="1.0"/>
    <float name="b" value="2.0"/>
    <float name="c" value="3.0"/>
  </hintdict>
</param>

nonexclusiveCheckboxPopup¶

The nonexclusiveCheckboxPopup widget allows multiple options to be chosen from a pop-up menu.

Widget type-specific hints:

resolution¶

The resolution widget shows a list of pre-defined resolutions in addition to allowing a resolution to be entered manually.

Widget type-specific hints:

assetIdInput¶

The assetIdInput widget allows an asset to be chosen using the current asset plug-in’s browser or the built-in file browser.

Widget type-specific hints:

assetIdOutput¶

Like assetIdInput, except that file paths that do not yet exist on disk can be chosen.

fileInput¶

Like assetIdInput, except that the default Katana file widget and browser are used, rather than the delegate and browser provided by the current asset plug-in.

sortableDelimitedString¶

The sortableDelimitedString widget shows a dynamic array of string widgets.

Widget type-specific hints:

scenegraphLocationArray¶

The scenegraphLocationArray widget shows a dynamic array of scenegraphLocation widgets. It supports the size, isDynamicArray and tupleSize hints

dynamicArray¶

The dynamicArray widget shows a dynamic array of widgets of a particular type. All widget hints are passed through to the child widgets. Each child widget handles tupleSize*tupleGroupSize array elements.

For example, to display a dynamic array with 2 default colors:

<param
    name="colors"
    isDynamicArray="1"
    widget="dynamicArray"
    panelWidget="color"
    default="1,0,0,0,1,0"
    tupleSize="3"/>

To display a dynamic array of 2 4x4 matrices:

<param
    name="transforms"
    isDynamicArray="1"
    widget="dynamicArray"
    default="1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1"
    tupleSize="4"
    tupleGroupSize="4"/>

Widget type-specific hints:

colorRamp¶

The following parameters are required in order to use a color ramp widget based on a set of sibling parameters:

• A number parameter that acts as the main parameter for the widget. The value of the parameter is interpreted as the number of knots that define the ramp. The parameter can have any name; here we use myRamp.
• A string parameter to define the interpolator to use for interpolating values in between two adjacent knots, named like myRamp_Interpolation.
• A number array parameter for knot positions, named like myRamp_Knots.
• A number array parameter for knot values, named like myRamp_Colors. Each value in myRamp_Knots corresponds to three values in myRamp_Colors.

Example:

<param name='myRamp' type='int' widget='colorRamp'/>
<param name='myRamp_Interpolation' type='string' widget='null'
  default='linear' options='linear|catmull-rom|bspline'/>
<param name='myRamp_Knots' type='float' widget='null'
  default='0,0,0.5,1,1' size='5' isDynamicArray='1'/>
<param name='myRamp_Colors' type='float' widget='null'
  default='1,0,0,1,0,0,0,1,0,0,0,1,0,0,1' size='15' isDynamicArray='1' />

floatRamp¶

Float ramps use a similar parameter structure to color ramps, except that the myRamp_Colors parameter, which contains three values per knot, is replaced by a myRamp_Floats parameter containing one value per knot.