Creating and Retrieving Nodes
=============================

.. currentmodule:: NodegraphAPI

Creating a Node
---------------

New nodes must be parented to a node that accepts child nodes, such as the *root node* (a special node representing the
top level of the node graph), a :kat:node:`Group` or :kat:node:`LiveGroup` node, or a SuperTool. For example, to add a
:kat:node:`PrimitiveCreate` node under the root node enter the following in the :kat:ui:`Python` tab::

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

    # Create a new node under the root node
    primNode = NodegraphAPI.CreateNode('PrimitiveCreate', rootNode)

This creates a new *PrimitiveCreate* node, which - in turn - generates a scene graph location containing a single
primitive. By default the *PrimitiveCreate* node is set to type 'sphere'.

The new node is an instance of a Python class that represents that node type, and may contain additional methods
specifically for working with that node. For example, a GafferThree node has a ``getRootPackage()`` method that does
not exist for other node types.

.. note:: You can use the Python help function to get information about a
    particular function call. For example::

        help(NodegraphAPI.CreateNode)

.. autofunction:: CreateNode

Retrieving a Node
-----------------

You can reference a node using the function :func:`GetNode`. For example, to retrieve a node called
:kat:node:`PrimitiveCreate` use::

    primNode = NodegraphAPI.GetNode('PrimitiveCreate')

Parameters are referenced in a similar way to nodes, using the function :meth:`~Nodes3D.Node3D.getParameter`. For
example, to retrieve the :kat:param:`type` parameter of a node called :kat:node:`PrimitiveCreate`, use::

    primTypeParam = NodegraphAPI.GetNode('PrimitiveCreate').getParameter('type')

.. tip:: Shift+middle-drag to the Python tab from a node in the
    :kat:ui:`Node Graph` tab, or a parameter in the :kat:ui:`Parameters` tab to
    automatically create the path to that node or parameter. For example,
    dragging from a node :kat:node:`PrimitiveCreate` in the node graph
    produces::

        NodegraphAPI.GetNode('PrimitiveCreate')


.. autofunction:: GetNode
.. autofunction:: GetRootNode
.. autofunction:: SetRootNode
.. autofunction:: GetAllNodes
.. autofunction:: GetAllNodesByType
.. autofunction:: GetViewNode
.. autofunction:: GetViewNodes
.. autofunction:: GetAllEditedNodes
.. autofunction:: GetAllSelectedNodes
.. autofunction:: GetAllSelectedNodesAndParent
.. autofunction:: GetAllFloatingNodes
.. autofunction:: GetAllThumbnailEnabledNodes