Node Properties
===============

.. currentmodule:: NodegraphAPI

Node Instance Methods
---------------------

Name
~~~~

In Katana, each node has a name that is guaranteed to be unique across an
entire Katana project. This means that when setting the name of a node, the
resulting node name may be different from the one that was specified::

    node = NodegraphAPI.GetNode('TeapotCreate')
    node.setName('Teapot')
    print(node.getName())

If the specified name is already in use by another node in the Katana project,
:py:func:`Node.setName` adds a numeric suffix to the name, and returns the new
unique node name, for example :kat:ui:`Teapot4` instead of :kat:ui:`Teapot`.

It's possible to store a string user parameter on a node that custom tools can
search for, in order to reference a node in a smaller context. This is a simple
pattern that can provide a more localized pseudo node name. See
:doc:`Parameters/index` for more on adding parameters.

.. note:: Node names cannot contain spaces. Any spaces or invalid characters
    that are used in a specified node name are converted into underscores. For
    example, the node name `'Material Plastic'` becomes `'Material_Plastic'`.

.. automethod:: Node.getName
.. automethod:: Node.setName

Type
~~~~

.. automethod:: Node.getBaseType
.. automethod:: Node.getType
.. automethod:: Node.setType

Parent Node
~~~~~~~~~~~

.. automethod:: Node.getParent
.. automethod:: Node.setParent

Parameters
~~~~~~~~~~

See :doc:`Parameters/index`.

.. automethod:: Node.customReset
.. automethod:: Node.isResetPossible

Ports
~~~~~

See :doc:`ConnectingNodes`.

The following instance methods are available to control the routing of ports
for nodes that are disabled:

.. automethod:: Node.getBypassRouting
.. automethod:: Node.setBypassRouting

Flags
~~~~~

.. automethod:: Node.isAutoRenameAllowed
.. automethod:: Node.setAutoRenameAllowed
.. automethod:: Node.isBypassed
.. automethod:: Node.setBypassed
.. automethod:: Node.isLocked
.. automethod:: Node.setLocked
.. automethod:: Node.isMarkedForDeletion

Node Attributes
~~~~~~~~~~~~~~~

Node attributes are mappings of property names to values that will be written
to and read from Katana project files when serializing the node graph document.
They consist of:

- Attributes that represent standard node properties, like `Name`_ and `Type`_.
- `Node Shape Attributes`_
- Attributes from `Node Extensions`_, like the presence of the node's view and
  edit flags, the node's selection state, and the node's `Position`_ in the
  :kat:ui:`Node Graph` tab's canvas.

.. automethod:: Node.getAttributes
.. automethod:: Node.setAttributes

.. caution::

    Node attributes should not be confused with scene graph attributes.

Miscellaneous
~~~~~~~~~~~~~

.. automethod:: Node.delete
.. automethod:: Node.getUpstreamContributingNodes

Node Extensions
---------------

*Node Extensions* are custom Python modules that provide additional properties
on top of the basic properties that are provided by the :py:class:`Node` class.

At present, only one Node Extensions module is registered in Katana. It
provides storage for a number of additional properties, and corresponding API
functions for querying and modifying them, which are made available in the main
:py:mod:`NodegraphAPI` namespace.

Flags
~~~~~

.. autofunction:: IsNodeEdited
.. autofunction:: SetNodeEdited
.. autofunction:: IsNodeViewed
.. autofunction:: SetNodeViewed
.. autofunction:: IsNodeSelected
.. autofunction:: SetNodeSelected
.. autofunction:: SetAllSelectedNodes
.. autofunction:: IsNodeHidden
.. autofunction:: SetNodeHidden
.. autofunction:: IsNodeFloating
.. autofunction:: SetNodeFloating
.. autofunction:: IsNodeThumbnailEnabled
.. autofunction:: SetNodeThumbnailEnabled
.. autofunction:: IsNodeLockedByParents

Node Shape Attributes
~~~~~~~~~~~~~~~~~~~~~

*Node Shape Attributes* are `Node Attributes`_ that control the appearance of
nodes in the :kat:ui:`Node Graph` tab, such as the node color to display.

.. autofunction:: GetNodeShapeAttr
.. autofunction:: GetNodeShapeAttrs
.. autofunction:: SetNodeShapeAttr
.. autofunction:: SetNodeShapeNodeAttrs
.. autofunction:: DeleteNodeShapeAttr

.. caution::

    Custom node shape attributes can be added, which will be stored and
    restored when saving and loading a Katana project file
    (see `Node Attributes`_).
    It is recommended to store only small amounts of data in custom node shape
    attributes, so as to keep Katana project files light and fast to load.

Comments
~~~~~~~~

.. autofunction:: GetNodeComment
.. autofunction:: SetNodeComment

Position
~~~~~~~~

The :func:`SetNodePosition` function sets the position of a node in the
:kat:ui:`Node Graph` tab. The following example code demonstrates how a
:kat:node:`PrimitiveCreate` node can be created and then positioned::

    # Get the root node
    rootNode = NodegraphAPI.GetRootNode()

    # Create a new node at the root level
    primitiveCreateNode = NodegraphAPI.CreateNode('PrimitiveCreate', rootNode)

    # Define X & Y values
    position = (0, 100)

    # Set node position
    NodegraphAPI.SetNodePosition(primitiveCreateNode, position)

.. autofunction:: GetNodePosition
.. autofunction:: SetNodePosition

Miscellaneous
~~~~~~~~~~~~~

.. autofunction:: GetMenuPath
.. autofunction:: CheckNodeType