Structure
=========

.. highlight:: xml

Args Files are XML document files with a ``.args`` file extension [#f1]_ that
contain a top-level ``<args>`` element::

    <args format="1.0">
      <!-- content -->
    </args>

Within the top-level ``<args>`` element, an Args File may contain ``<param>``,
``<page>``, and ``<group>`` elements. A single ``<help>`` or (for shader
args) ``<outputs>`` element may also be present. ``<param>`` elements are used
to expose parameters in the user interface.

.. [#f1] Args Files for GenericAssign use a ``.xml`` file extension.

Parameters
----------

``<param>`` XML elements describe the presence and order of parameters within
the UI. Each ``<param>`` element is required to have a ``name`` attribute; all
other properties are optional.

Args Files can be used to specify the types of widgets to use for parameters in
Katana's UI. The type of widget to use for a particular parameter can be
specified using a ``widget`` XML attribute on a ``<param>`` element::

     <param name="someParameter" widget="fileInput"/>

A number of hints can be specified to affect the appearance and behavior of a
widget of the respective type. Some hints are respected by most or all widget
types, such as :ref:`args-conditional-vis`; other hints are specific to only
particular types of widgets.

In their simplest form, hints can be specified using an XML attribute named
the same as the hint name::

    <param name="someParameter" widget="fileInput" fileTypes="exr|png"/>

.. seealso::

    :doc:`WidgetsAndHints` for a list of available widgets and hints.


Pages and Groups
----------------

Pages can be used to visually group parameters. Pages can be nested with
dot-delimited values::

    <param name="someParameter" page="Lighting" />
    <param name="anotherParameter" page="Lighting.Advanced"/>

Page grouping may also be specified via enclosing ``<page>`` elements. This is
often preferable as it provides a place to attach UI hints to pages themselves.
Nested ``<page>`` elements specify their name properties as a dot-delimited
path relative to the enclosing value. The following is equivalent to the
previous example::

    <page name="Lighting">
      <param name="someParameter"/>
      <page name="Advanced">
        <param name="anotherParameter"/>
      </page>
    </page>

Pages appear in Katana's UI as groups of their contents under a common header,
with a disclosure triangle allowing the user to open or close the respective
group. The initial state of whether a page's group appears as open or closed
can be specified with the ``open`` property, which accepts a boolean value.
Pages default to appearing as closed unless otherwise specified. For example::

    <page name="Lighting" open="true"></page>

A group is visually identical to a page, but differs in that it creates a
group parameter to contain its children, whereas pages have no impact on the
underlying parameter structure. This is most useful when writing
:doc:`ForGenericAssign`, where parameter groups correspond with attribute
groups.

.. _args-help:

Help Text
---------

Help text may be defined for any ``<param>``, ``<page>``, or ``<group>``
element by adding a ``help`` attribute or element to it, for example::

    <!-- Using an attribute -->
    <param type="float" name="color" help="The color of the light"/>

    <!-- Using an element -->
    <param type="float" name="color">
      <help>The color of the light</help>
    </param>

``<help>`` elements may contain arbitrary HTML.

Additional emphasis may be placed on given help text via the ``helpAlert``
attribute, which can be set to one of three values:

``normal``
  The help button's icon is shown in its default appearance.
``warning``
  The help button's icon appears with a yellow border.
``error``
  The help button's icon appears with a red border.

For example::

    <param name="someParameter" helpAlert="warning">
      <help>
        This parameter is <strong>very</strong> important. Be careful!
      </help>
    </param>

Help may also be added at the top level with a ``<help>`` element, for
example::

    <args format="1.0">
      <help>
        This is a <em>lovely</em> shader.
      </help>
      <!-- content -->
    </args>


Comments
--------

Comments use standard XML markup::

    <!-- Useful commentary goes here. -->