Widgets and Hints ================= .. highlight:: xml .. contents:: :local: :depth: 2 :backlinks: none Hint Types ---------- 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 ```` XML element. Strings are delimited using a pipe character (``|``). The following two forms are equivalent:: Child elements of ```` may be of type ````, ```` or ````, 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 ```` 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:: Child elements of ```` may be of type ````, ```` or ````, and may specify their value in either ``value`` or ``default`` attributes. They must also specify a ``name`` attribute. Common Hints ------------ The following hints are applicable to most widget types. .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``label`` * String * Alters the display name of the widget. Please use this rarely as it can create confusion with regards to expressions and `NodegraphAPI` scripting. - * ``readOnly`` * Boolean * If *true*, the value of the corresponding parameter is not editable via the :kat:ui:`Parameters` tab. This does not affect scripting. - * ``infoText`` * String * Displays a line of informational text below the editing widget for the parameter. Please use this sparingly as the same mechanism is used for displaying error messages on some widget contexts. - * ``externalEditorSuffix`` * String * The file extension to use for the temporary file that is created when :kat:ui:`External editor...` is chosen from the parameter's context menu. - * ``help`` * String * See :ref:`args-help`. - * ``mono`` * Boolean * If *true*, text in the editing widget is displayed using a monospace font. Pages and Groups ---------------- ``group`` ''''''''' ```` and ```` elements use the ``group`` widget type be default. It supports these hints: .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``open`` * Boolean * If *true*, the page/group is expanded in the UI to reveal its contents. - * ``closed`` * Boolean * If *false*, the page/group is expanded in the UI. Use ``open`` in preference to this hint. ``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 :kat:ui:`Parameters` tab for the parameters. Widget type-specific hints: .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``policies`` * String * Specifies the parameter names for which to set default values, separated by commas. - * ``presets`` * String * Specifies the default values for the different presets. Each preset is defined by a name and a list of values, one for each parameter specified in the ``policies`` attribute. The value and parameter types need to match. Presets are separated by a pipe character (``|``). .. note:: Only floats, list of floats, and strings are allowed in the ``presets`` attribute. In the example below, the ```` element's widget is set to ``presetsGroup``, and the element defines presets for four parameters: :kat:param:`Kd`, :kat:param:`Kd_color`, :kat:param:`ColMap`, and :kat:param:`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``. .. code-block:: xml Basic Widgets ------------- ``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: .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``min`` * Float or integer * Specifies the minimum value when dragging on a parameter's label. Values entered via the text field are not clamped. - * ``max`` * Float or integer * Specifies the maximum value when dragging on a parameter's label. Values entered via the text field are not clamped. - * ``sensitivity`` * Float or integer * Specifies the label drag increment. - * ``digits`` * Integer * Specifies the number of digits to display after the decimal point. The default value of -1 indicates full precision. - * ``int`` * Boolean * If *true*, floating-point parameter types are displayed as integers. This affects display and also applies clamping on numeric entry. - * ``constant`` * Boolean * If *true*, animation via curves is disabled. - * ``slider`` * Boolean * If *true*, a slider is displayed to the right of the text entry field. - * ``slidermin`` * Float or integer * Specifies the minimum value of the slider. - * ``slidermax`` * Float or integer * Specifies the maximum value of the slider. - * ``slidercenter`` * Float or integer * Specifies the origin value of the slider. - * ``sliderexponent`` * Integer * Specifies a non-linear scaling of the slider. - * ``slidersensitivity`` * Float or integer * Specifies the sensitivity of the slider. ``string`` '''''''''' Displays a widget for entering text. This is the default widget type used for string parameters. Widget type-specific hints: .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``replaceRegex`` * String * A regular expression whose matching values will be replaced upon text entry. These characters are replaced by ``_`` unless specified by a matching ``replaceWith`` hint. - * ``replaceWith`` * String * Used with ``replaceRegex`` to filter characters on text entry. For example:: .. _widget-checkbox: ``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: .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``color_enableFilmlookVis`` * Boolean * Enable Filmlook visualization. - * ``color_enableNoFilmlookColorSpace`` * Boolean * Enable No-Filmlook colorspace. - * ``color_restrictComponents`` * Boolean * Restrict color components to the range 0 --> 1. ``scenegraphLocation`` '''''''''''''''''''''' Displays a widget for entering and jumping to a scene graph location path. Can be used for string parameters. Widget type-specific hints: .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``allowRelativePath`` * Boolean * If *true*, relative scene graph location paths are allowed. - * ``adjustRelativeToPath`` * String * If defined, the :kat:ui:`Adjust Path Relative To ` menu command is available from the widget. When chosen, the absolute path stored in the parameter is transformed to a relative path. The path is relative to the scene graph location stored in the parameter given in this hint. - * ``allowAdoptScenegraphSelection`` * Boolean * If *true*, the :kat:ui:`Adopt Scene Graph Selection` menu command is available from the widget. - * ``omitEmptyWarning`` * Boolean * If *true*, a warning icon is not displayed in the widget when zero paths are present. ``cel`` ''''''' Displays a CEL statement widget. Can be used for string parameters. Widget type-specific hints: .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``omitEmptyWarning`` * Boolean * See above. ``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: .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``resistLabelResize`` * Boolean * If *true*, the size of the widget's label is minimized. This gives the script editor more space at the expense of its left edge not lining up with nearby widgets. - * ``supportsNonmodalExternalEditing`` * String * If *true*, a :kat:ui:`Edit in External Editor` button is displayed above the text field. - * ``highlighter`` * String * The syntax highlighter to use. Currently only "python" is supported. ``scriptButton`` '''''''''''''''' Displays a button that executes a Python script when pressed. All submodules from the :mod:`Katana` module are available from within the script. Additionally, the following local variables are available: .. py:data:: parameter The parameter object corresponding to the script button. .. py:data:: node The node object that owns the parameter corresponding to the script button. .. py:function:: exit() Exits the script button script. Can be used for string parameters. Widget type-specific hints: .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``buttonText`` * String * The text to display on the button. - * ``scriptText`` * String * The Python script to execute when the button is pressed. Pull-down Widgets ----------------- ``boolean`` ''''''''''' Like :ref:`widget-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:: Can be used for string parameters. Widget type-specific hints: .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``options`` * List of strings * This is the list of choices to be displayed in the pop-up menu or combo box. It may be specified as a child ```` element or as a pipe-delimited string. The following two examples are equivalent:: - * ``editable`` * Boolean * If *true*, the pop-up menu will instead be displayed as a combo box which supports direct text entry of values not in the options list. This can also be done by using ``*`` as the value in the option list. The following three examples are equivalent:: ``mapper`` '''''''''' The ``mapper`` widget presents a pop-up menu with associative choices. Each value has an associated display value. For example:: Can be used for string parameters. Widget type-specific hints: .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``options`` * Dictionary * The dictionary keys are the ordered display values of the pop-up menu. Each is paired with a unique literal value for the parameter. This may be specified as either a string property of a ```` child element. The following options are equivalent:: - * ``options__order`` * List * When ``options`` is a dictionary, ``options__order`` defines the order of keys. ``nonexclusiveCheckboxPopup`` ''''''''''''''''''''''''''''' The ``nonexclusiveCheckboxPopup`` widget allows multiple options to be chosen from a pop-up menu. Widget type-specific hints: .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``emptyLabel`` * String * The text to display when no option is chosen. ``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: .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``hideNumberFields`` * String * If *true*, widgets for entering a resolution numerically are hidden. File Widgets ------------ .. widget-asset-id: ``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: .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``fileTypes`` * List of strings * Specifies the default file extensions to filter by in the dialog. - * ``sequenceListing`` * Boolean * If *true*, file sequences can be chosen from the file browser. - * ``acceptDir`` * Boolean * If *true*, directories can be chosen from the file browser. - * ``dirsOnly`` * Boolean * If *true*, only directories can be chosen from the file browser. ``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. Array Widgets ------------- Katana determines whether a parameter should be declared as an array by inspecting its type and default value. For shaders, the renderer plug-in is responsible for supplying this information. In other cases, the ``default`` or ``value`` XML attribute is used and delimited by the comma character (``,``). Any widget assigned to an array parameter is used to display *the entire array*, rather than used once per element. Only certain widget types are equipped to work with arrays. In addition to those listed below, the ``string`` and ``number`` widget types can work with arrays of any size, and the ``color`` widget type works with 3- or 4-element arrays. Dynamic arrays allow the addition, re-ordering and removal of array elements. All dynamic arrays should set the ``isDynamicArray`` hint to *true*. The following hints are broadly applicable to arrays: .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``size`` * Integer * Specifies the size of the array. This is only needed when writing :doc:`ForRendererProcedurals`. - * ``isDynamicArray`` * Boolean * Specifies whether the array can expand and contract. - * ``tupleSize`` * Integer * Specifies the tuple size (column count). The following example displays two rows and three columns:: ``sortableDelimitedString`` ''''''''''''''''''''''''''' The ``sortableDelimitedString`` widget shows a dynamic array of ``string`` widgets. Widget type-specific hints: .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``size`` * Integer * Specifies the size of the array. This is only needed when writing :doc:`ForRendererProcedurals`. - * ``isDynamicArray`` * Boolean * Must be *true*. - * ``tupleSize`` * Integer * Specifies the tuple size (column count). - * ``delimiter`` * String * Delimiter used to split the default value. Defaults to a pipe character (``|``). - * ``childHints`` * Dictionary * Hints to pass to underlying ``string`` widget. ``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:: To display a dynamic array of 2 4x4 matrices:: Widget type-specific hints: .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``size`` * Integer * Specifies the size of the array. This is only needed when writing :doc:`ForRendererProcedurals`. - * ``isDynamicArray`` * Boolean * Must be *true*. - * ``tupleSize`` * Integer * Specifies the tuple size (column count). This is passed to the child widgets. - * ``tupleGroupSize`` * Integer * Specifies the number of tuples each child widget should handle. - * ``panelWidget`` * String * Specifies the widget type to use for child widgets. If not given, ``string`` or ``number`` are used. Ramp Widgets ------------ Color ramp widgets allow users to define a color gradient. Float ramp widgets allow users to define a curve. Both types of widgets allow users to define ramps through a series of knots. Each knot is defined through its position on the ramp and its value at that position. The value of a knot is either a set of three floating-point numbers representing a color (color ramp) or a single floating-point number representing the Y coordinate of a point on a curve (float ramp). A number of presets are available for users to choose from for individual color and float ramp widgets. Both types of widgets support two different structures for their underlying parameters. They work with either one of: 1. A set of sibling parameters. This structure is typically used for shader parameters, where grouping of parameters is only available via pages. 2. A group parameter with a set of child parameters. This structure is typically used for user parameters. In both cases, the widget type (one of ``colorRamp`` or ``floatRamp``) and hints are defined on the main parameter. In both cases, ramps are defined by number array parameters that are considered companion parameters of the main parameter. Widget type-specific hints: .. list-table:: :header-rows: 1 :widths: 25 25 50 - * Hint * Type * Description - * ``gradientHeight`` * Integer * (Color ramps only) The height of the gradient widget. - * ``rampInterp`` * String * Defines the name of the interpolation parameter to use. - * ``rampKnots`` * String * Defines the name of the knots parameter to use. - * ``rampColors`` * String * (Color ramps only) Defines the name of the colors parameter to use. - * ``rampFloats`` * String * (Float ramps only) Defines the name of the floats parameter to use. ``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:: ``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. .. _args-conditional-vis: Conditional Visibility and Locking ---------------------------------- Conditional Visibility and Conditional Locking allow for parameters and pages to be conditionally visible or locked (against edits) based on value comparisons of referenced other parameters. Hints representing the parse tree of a conditional statement are supported as string hints or string entries within a dictionary hint. When specifying hints for visibility, the root hint is named ``conditionalVisOp``. For locking, it's ``conditionalLockOp``. When using a ```` element to store the hints, that ```` itself is named ``conditionalVisOps`` and ``conditionalLockOps`` respectively. All examples will be displayed in the ```` form and describe conditional visibility. Each conditional is specified with a prefix name suffixed with ``Op``. The prefix for the root-level condition is always ``conditionalVis``. Operators which compare values address the referenced parameters via POSIX-style paths relative to the parameter or page on which the hint is defined. Page names are included in the parameter path. A conditional expression which evaluates to *false* results in the hinted widget being hidden. Comparison values are always specified as strings and converted to the type of the parameter against which they're compared. The available operators and their operands are: .. list-table:: :header-rows: 1 :widths: 10 10 10 70 - * Operator * Operand 1 * Operand 2 * Description - * ``isEqualTo`` * :samp:`{prefix}Path` * :samp:`{prefix}Value` * Does an equality test with the value specified by :samp:`{prefix}Path` of the specified parameter against the provided :samp:`{prefix}Value`. - * ``isNotEqualTo`` * :samp:`{prefix}Path` * :samp:`{prefix}Value` * See above. - * ``isGreaterThan`` * :samp:`{prefix}Path` * :samp:`{prefix}Value` * Does an comparison test with the value specified by :samp:`{prefix}Path` of the specified parameter against the provided :samp:`{prefix}Value`. - * ``isLessThan`` * :samp:`{prefix}Path` * :samp:`{prefix}Value` * See above. - * ``isGreaterThanOrEqualTo`` * :samp:`{prefix}Path` * :samp:`{prefix}Value` * See above. - * ``isLessThanOrEqualTo`` * :samp:`{prefix}Path` * :samp:`{prefix}Value` * See above. - * ``and`` * :samp:`{prefix}Left` * :samp:`{prefix}Right` * The values of the :samp:`{prefix}Left` and :samp:`{prefix}Right` operands are the prefixes of additional conditional operators. If both evaluate to *true*, this operator also evaluates to *true*. - * ``or`` * :samp:`{prefix}Left` * :samp:`{prefix}Right` * The values of the :samp:`{prefix}Left` and :samp:`{prefix}Right` operands are the prefixes of additional conditional operators. If either evaluate to *true*, this operator also evaluates to *true*. .. to be documented: in notIn endsWith contains doesNotContain numChildrenEqualTo numChildrenGreaterThanOrEqualTo regex Here is a simple example in which we'll hint a subpage to be visible only if the parameter value of its peer is non-zero:: Another example demonstrating the ``or`` operator and the relationship of :samp:`{prefix}` in the operand values. This will display the "Advanced" page if either the :kat:param:`showAdvancedOptions` parameter is non-zero or the :kat:param:`someParameter` value is greater than 1.0:: Please note that only the root operation is required to have a :samp:`{prefix}` starting with ``conditionalVis``. The prefixes of the second and third operations are defined here by the values of ``conditionalVisLeft`` and ``conditionalVisRight`` - and could be anything.