Getting and Setting Parameters
==============================

.. py:currentmodule:: NodegraphAPI

The parameters of a node are organized in a tree inside the node. The tree
allows better organization of nodes with many parameters, avoids parameter name
collisions, and makes it simple to construct more complex re-usable parameter
definitions.

The function :func:`~Nodes3DAPI.Node3D.getParameters` returns the root parameter of a
node. The children of that root parameter are the top level entries you see in
the :kat:ui:`Parameters` tab. For example, to get the children of the root
parameter on a node enter::

    >>> node = NodegraphAPI.GetNode("PrimitiveCreate")
    >>> for p in node.getParameters().getChildren():
    ...     print(p)
    <Parameter 'name'>
    <Parameter 'type'>
    <Parameter 'fileName'>
    <Parameter 'previewTexture'>
    <Parameter 'previewAlpha'>
    <Parameter 'enableClippingPlane'>
    <Parameter 'reverseClippingDirection'>
    <Parameter 'transform'>
    <Parameter 'makeInteractive'>
    <Parameter 'includeBounds'>
    <Parameter 'viewerPickable'>

You can get a complete text dump of all parameters on a node using
:meth:`~Parameter.getXML`. For example, to see the XML structure of all the
parameters on a node::

    >>> print (node.getParameters().getXML())
    <group_parameter name="PrimitiveCreate">
        <string_parameter name="name" value="/root/world/geo/primitive"/>
        <string_parameter name="type" value="sphere"/>
        ...
    </group_parameter>

.. automethod:: Parameter.getType
.. automethod:: Parameter.getNode
.. automethod:: Parameter.getFullName
.. automethod:: Parameter.getName
.. automethod:: Parameter.setName
.. automethod:: Parameter.getParent
.. automethod:: Parameter.getIndex
.. automethod:: Parameter.reparentAtomic


Getting Values
--------------

To return the value of a parameter, use ``getParameter().getValue()``. For
example, to return the value of the name parameter at time 0, enter the
following::

    >>> node.getParameter('name').getValue(0)

.. py:currentmodule:: Nodes3DAPI
.. automethod:: Node3D.getParameter
.. automethod:: Node3D.getParameters

.. py:currentmodule:: NodegraphAPI
.. automethod:: Parameter.getValue


Setting Values
--------------

Values on a node are set using ``getParameter().setValue()``. As node behavior
is set by parameters who’s values can change over time, you must specify a
value and a time, when setting a parameter.

For example, to change the :kat:param:`type` parameter of a
:kat:node:`PrimitiveCreate` node to "teapot", when time is 10, enter the
following::

    node.getParameter('type').setValue("teapot", 10)

.. automethod:: Parameter.setValue
.. automethod:: Parameter.finalizeValue