Args Files for GenericAssign
============================

.. highlight:: xml

As a variant of Args Files, *GenericAssign* XML files specify attribute
conventions and typically define node types capable of editing such attributes.
GenericAssign Args Files are loaded from :file:`GenericAssign` folders within
:envvar:`KATANA_RESOURCES` directories.

The example below registers a :kat:attr:`logFile` attribute convention on
:kat:loc:`/root/world`, and a ``LogFile`` node type capable of editing that
attribute::

    <args format="1.0" scope="/root/world" fixedCEL="/root/world">
      <string name="logFile" widget="assetIdOutput"/>
    </args>

The contents above can be saved to a file named
:file:`/your/plugins/GenericAssign/LogFile.xml`, and Katana launched with
:envvar:`KATANA_RESOURCES` set to :file:`/your/plugins`. With the file loaded,
Katana's behaviour changes as follows:

- When :kat:loc:`/root/world` is selected in the :kat:ui:`Scene Graph` tab,
  the :kat:ui:`Attributes` tab displays :kat:attr:`logFile` as a *default
  attribute*. This is used purely for informational purposes in the
  :kat:ui:`Attributes` tab, and does not affect the scene data.
- A ``LogFile`` node type becomes available in the :kat:ui:`Node Graph` tab's
  node creation menus. ``LogFile`` nodes have one input and one output, and
  feature a single :kat:attr:`logFile` parameter.
- When multiple ``LogFile`` nodes are chained together, a downstream
  node displays the upstream value of the :kat:attr:`logFile` attribute in
  its :kat:param:`logFile` parameter; this is shown alongside a *state badge*.
  This mechanism works however the upstream attribute came to be set.


Top-level ``<args>`` Attributes
-------------------------------

The following XML attributes can be specified on the top-level ``<args>``
element, and are specific to GenericAssign Args Files:


``fixedCEL``
  If given, a GenericAssign node's :kat:ui:`CEL` parameter is not shown when
  editing the node's parameters in a :kat:ui:`Parameters` tab. Instead, the
  node targets locations specified by the given value of ``fixedCEL``.
``fixedCELExpression``
  As above, but the CEL expression is given as a parameter expression.
``scope``
  If given, the :kat:ui:`Attributes` tab shows *default attributes* at
  locations specified by the given value of ``scope``, which should be a CEL
  expression.
``createGenericAssignNodeType``
  By default, for each GenericAssign XML file, a node type is registered, which
  can be used to display and edit scene graph attributes as declared in the XML
  document. This registration of a GenericAssign node type can be omitted by
  specifying the ``createGenericAssignNodeType`` XML attribute with a value of
  ``false``. Note that in that case, default attributes as defined in the
  GenericAssign XML file are still shown in the :kat:ui:`Attributes` tab for
  locations targeted by ``scope``.
``nodeFlavors``
  A comma-separated list of *node flavors* to give the node type, such as
  ``_hide`` to hide the node from the :kat:ui:`Node Graph` tab's node creation
  menus.


Forcing Parameters to be Arrays
-------------------------------

The ``forceArray`` attribute can be used to turn number and string parameters
into number array and string array parameters, even if they contain only one
value, as shown in the following example::

    <args format='1.0' scope='/root' fixedCEL='/root'>
      <float name='myNumber' default='0.123'/>
      <string name='myString'/>
      <float name='myNumberArray' default='0.123' forceArray='True'/>
      <string name='myStringArray' forceArray='True'/>
    </args>