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¶

Color Ramp widgets allow users to define a 1D color gradient through a series of knots, each specified with a position value and 3 color component values (RGB).

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

1. A number parameter that acts as the main parameter for the widget.

• The parameter can have any name. In the examples below, we use 'myColorRamp' as the name.

• The value of the parameter is interpreted as the number of knots that define the ramp.

• The following widget type-specific hints can be set on the main parameter:

  Hint	Type	Description
  rampInterp	String	Defines the name of the interpolation parameter to use, if a name is used that does not follow the convention (see below).
  rampKnots	String	Defines the name of the number array parameter for knot positions to use, if a name is used that does not follow the convention (see below).
  rampColors	String	Defines the name of the number array parameter for knot values to use, if a name is used that does not follow the convention (see below).
  gradientHeight	Integer	The height of the gradient widget in pixels. Defaults to 10. Minimum is 5.

2. A string parameter to define the interpolator to use for interpolating values in between two adjacent knots.

• By convention, the parameter is expected to be named <name-of-main-parameter>_Interpolation, e.g. myColorRamp_Interpolation.
• A different name can be used, in which case that name needs to be specified in the rampInterp hint on the main parameter.
• Valid options for interpolator types are 'linear' and 'constant'.

3. A number array parameter for knot positions.

• By convention, the parameter is expected to be named <name-of-main-parameter>_Knots, e.g. myColorRamp_Knots.
• A different name can be used, in which case that name needs to be specified in the rampKnots hint on the main parameter.

4. A number array parameter for knot values.

• By convention, the parameter is expected to be named <name-of-main-parameter>_Colors, e.g. myColorRamp_Colors.
• A different name can be used, in which case that name needs to be specified in the rampColors hint on the main parameter.
• Each value in myColorRamp_Knots corresponds to three values in myColorRamp_Colors.

Example:

<!-- A Color Ramp compound parameter, consisting of 4 sibling parameters -->
<int name='myColorRamp' default='5' widget='colorRamp' gradientHeight='15'/>
<string name='myColorRamp_Interpolation' default='linear' options='linear|constant' widget='null'/>
<float name='myColorRamp_Knots' default='0,0,0.5,1,1' size='5' widget='null'/>
<float name='myColorRamp_Colors' default='1,0,0,1,0,0,0,1,0,0,0,1,0,0,1' size='15' tupleSize='3' widget='null'/>

floatRamp¶

Float Ramp widgets allow users to define a curve through a series of knots, each specified with a position (X) value and a Y value.

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

1. A number parameter that acts as the main parameter for the widget.

• The parameter can have any name. In the examples below, we use 'myFloatRamp' as the name.

• The value of the parameter is interpreted as the number of knots that define the ramp.

• The following widget type-specific hints can be set on the main parameter:

  Hint	Type	Description
  rampInterp	String	Defines the name of the interpolation parameter to use, if a name is used that does not follow the convention (see below).
  rampKnots	String	Defines the name of the number array parameter for knot positions to use, if a name is used that does not follow the convention (see below).
  rampFloats	String	Defines the name of the number array parameter for knot values to use, if a name is used that does not follow the convention (see below).
  minPosition	Float or integer	The smallest value to which the X coordinate of a knot on the curve can be set. Defaults to 0.
  maxPosition	Float or integer	The largest value to which the X coordinate of a knot on the curve can be set. Defaults to 1.
  minValue	Float or integer	The smallest value to which the Y coordinate of a knot on the curve can be set. Defaults to 0.
  maxValue	Float or integer	The largest value to which the Y coordinate of a knot on the curve can be set. Defaults to 1.
  panZoomEnabled	Boolean	Controls whether panning and zooming of the curve is allowed. Defaults to true.

2. A string parameter to define the interpolator to use for interpolating values in between two adjacent knots.

• By convention, the parameter is expected to be named <name-of-main-parameter>_Interpolation, e.g. myFloatRamp_Interpolation.
• A different name can be used, in which case that name needs to be specified in the rampInterp hint on the main parameter.
• Valid options for interpolator types are:
  • 'linear'
  • 'constant'
  • 'bspline' (currently drawn as a Catmull-Rom-like spline)
  • 'catmull-rom' (currently drawn as a Catmull-Rom-like spline)
  • 'hermite' (currently drawn as a Catmull-Rom-like spline)
  • 'bezier'

3. A number array parameter for knot positions.

• By convention, the parameter is expected to be named <name-of-main-parameter>_Knots, e.g. myFloatRamp_Knots.
• A different name can be used, in which case that name needs to be specified in the rampKnots hint on the main parameter.

4. A number array parameter for knot values.

• By convention, the parameter is expected to be named <name-of-main-parameter>_Floats, e.g. myFloatRamp_Floats.
• A different name can be used, in which case that name needs to be specified in the rampFloats hint on the main parameter.
• Each value in myFloatRamp_Knots corresponds to a value in myFloatRamp_Floats.

Example:

<!-- A Float Ramp compound parameter, consisting of 4 sibling parameters -->
<int name='myFloatRamp' default='5' widget='floatRamp' panZoomEnabled='false'/>
<string name='myFloatRamp_Interpolation' default='linear' options='linear|catmull-rom|bspline' widget='null'/>
<float name='myFloatRamp_Knots' default='0,0,0.4,1,1' size='5' widget='null'/>
<float name='myFloatRamp_Floats' default='0,0,0.7,0.4,0.4' size='5' widget='null'/>