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 :kat:node:`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 :kat:node:`LogFile` node type becomes available in the :kat:ui:`Node Graph`
  tab's node creation menus. :kat:node:`LogFile` nodes have one input and one
  output, and feature a single :kat:param:`logFile` parameter.
- When multiple :kat:node:`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:


``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
  statement.
``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 statement is given as a parameter expression.
``baseNodeType``
  The name of a type of node to use as the base class for the
  GenericAssign-based node type, e.g. ``RenderSettingsBaseType`` or
  ``LookFileGlobalsAssignBaseType`` (for internal use only).
``claimExclusivity``
  Whether or not the :kat:attr:`attributeEditor.exclusiveTo` attribute is to be
  set by an instance of the GenericAssign-based node type.
``makeInteractive``
  Synonym for ``claimExclusivity``.
``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.
``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``, ``no``, or ``0``. 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``.


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>