UN_Node.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UN_Node.h ( UN Library, C++)
 *
 * COMMENTS:
 *      
 */

#ifndef __UN_Node_h__
#define __UN_Node_h__

#include "UN_API.h"
#include "UN_Iterator.h"
#include "UN_Handle.h"
#include "UN_Parm.h"            // for ParmIterator implementation
#include "UN_Port.h"            // for PortIterator implementation

#include <UT/UT_StringHolder.h>


class UN_Graph;
class UT_Options;


// ============================================================================
/// A light-weight handle for a node data.
/// 
/// The actual node data (UN_NodeData) is owned and managed by UN_GraphData.
/// UN_Node serves as a handle for clients to refer to that node data.

// TODO: FIXME: consider constant handles too, UN_ConstNode, to enforce
//      const-correctness:
//      - they hold 'const UN_GraphData*' and can call only const functions
//      - they have methods that access graph, but never modify it
//      - UN_Node is a subclass of UN_ConstNode and adds methods
//        that modify the graph. 
//        - it takes non-const 'UN_GraphData *' as now, and passes it as
//          to base constructor, but is able to cast away constness
//          to regain non-const data to operate on
//      - This allows having const iterators, that can just reference index
//        arrays, since there is no danger of such arrays getting reallocated,
//        because adding new data objects inside the loop would not be allowed.
//        Eg, currently UN_Node::childRange() makes a copy of index array.
//        The child node ID could also be looked up on demand, when 
//        dereferencing iterator, instad of pre-fetching it into an ID array.

class UN_API UN_Node : public UN_Handle
{
public:
    /// Convenience constructor for the node handle.
                 UN_Node( UN_GraphData *graph_data,
                        UN_NodeIndex node_index,
                        UN_NodeID node_id );

    /// @{ Default constructors and assignment operators.
                 UN_Node();
                ~UN_Node();
                 UN_Node( const UN_Node& );
                 UN_Node( UN_Node&& );
    UN_Node &    operator=( const UN_Node& );
    UN_Node &    operator=( UN_Node&& );
    /// @}


    /// @{ Returns true if this is a valid node; false otherwise.
    bool                        isValid() const;
    explicit operator           bool() const
                                    { return isValid(); }
    /// @}


    /// @{ Comparison operators
    bool                        operator==( const UN_Node &other ) const
                                    { return UN_Handle::operator==( other ); }
    bool                        operator!=( const UN_Node &other ) const
                                    { return UN_Handle::operator!=( other ); }
    /// @}

    /// Returns the graph which owns this node.
    UN_Graph                    graph() const;

    /// Returns the parent of this node.
    UN_Node                     parent() const;


    /// @{ The node name that differentiates it among its siblings. 
    const UT_StringHolder &     name() const;
    void                        setName( const UT_StringRef &name ) const;
    /// @}

    /// @{ The node's type that determines its functional behavour.
    const UT_StringHolder &     typeName() const;
    void                        setTypeName( 
                                        const UT_StringRef &type_name ) const;
    /// @}

    /// @{ Sets and gets the node's category that groups it with other nodes 
    /// that are operationally compatible (and connectable).
    const UT_StringHolder &     categoryName() const;
    void                        setCategoryName( 
                                        const UT_StringRef &category ) const;
    /// @}


    /// Deletes this node from the graph.
    void                        destroy() const;


    /// Adds and returns a new parameter to this node.
    /// If another parameter of a given name already exists, returns an
    /// invalid parameter, indicating a failure due to the name collision.
    UN_Parm             createParm( const UT_StringRef &parm_name,
                                    const UT_StringRef &parm_type_name =
                                        UN_UNDEFINED_PARM_TYPE_NAME.asRef()
                                    ) const;

    /// Returns a parameter by the given name, or null if not found.
    UN_Parm             findParm( const UT_StringRef &parm_name ) const;
    
    /// Returns the names of the node parameters.
    UT_Array< UT_StringHolder > parmNames() const;

    /// An iterator and a range for parameters that belong to this node.
    using ParmIterator =
        UN_DataArrayIterator< UN_Parm, UN_ParmIndexArray, UN_ParmIDArray >;
    using ParmRange = UT_IteratorRange< ParmIterator >;

    /// Returns a range for iterating over node parameters.
    ParmRange           parmRange() const; 


    /// Adds and returns a new port to this node.
    /// If another port of a given kind and name already exists, returns an
    /// invalid port, indicating a failure due to the name collision.
    UN_Port             createPort( UN_PortKind port_kind,
                                const UT_StringRef &port_name,
                                const UT_StringRef &port_type_name =
                                    UN_UNDEFINED_PORT_TYPE_NAME.asRef()) const;

    /// Returns a input port by the given name, or null if not found.
    UN_Port             findPort( UN_PortKind port_kind,
                                  const UT_StringRef &port_name ) const;

    /// Returns the names of the node ports of a given kind
    UT_Array< UT_StringHolder > portNames( UN_PortKind port_kind ) const;

    /// And iterator and a range for ports that belong to this node.
    using PortIterator =
        UN_DataArrayIterator< UN_Port, UN_PortIndexArray, UN_PortIDArray >;
    using PortRange = UT_IteratorRange< PortIterator >;

    /// Returns a range for iterating over node input ports.
    PortRange           portRange( UN_PortKind port_kind ) const;


    /// Adds and returns a new input port to this node.
    /// If another input port of a given name already exists, returns an
    /// invalid port, indicating a failure due to the name collision.
    UN_Port             createInputPort( const UT_StringRef &port_name,
                                const UT_StringRef &port_type_name =
                                    UN_UNDEFINED_PORT_TYPE_NAME.asRef()) const
                            { 
                                return createPort( UN_PortKind::INPUT,
                                        port_name, port_type_name ); 
                            }


    /// Returns a input port by the given name, or null if not found.
    UN_Port             findInputPort( const UT_StringRef &port_name ) const
                            { return findPort(UN_PortKind::INPUT, port_name); }

    /// Returns the names of the node input ports.
    UT_Array< UT_StringHolder > inputPortNames() const
                            { return portNames(UN_PortKind::INPUT); }

    /// Returns a range for iterating over node input ports.
    PortRange           inputPortRange() const
                            { return portRange( UN_PortKind::INPUT ); }

    /// Returns true if any of the node's input ports has a connected source.
    /// Ie, if the node is not a leaf in the tree formed by input chains.
    bool                hasConnectedInputPortSource() const;


    /// Adds and returns a new output port to this node.
    /// If another outupt port of a given name already exists, returns an
    /// invalid port, indicating a failure due to the name collision.
    UN_Port             createOutputPort( const UT_StringRef &port_name,
                                const UT_StringRef &port_type_name =
                                    UN_UNDEFINED_PORT_TYPE_NAME.asRef()) const
                            { 
                                return createPort( UN_PortKind::OUTPUT,
                                        port_name, port_type_name ); 
                            }

    /// Returns an output port by the given name, or null if not found.
    UN_Port             findOutputPort( const UT_StringRef &port_name ) const
                            { return findPort(UN_PortKind::OUTPUT, port_name); }
    
    /// Returns the names of the node output ports.
    UT_Array< UT_StringHolder > outputPortNames() const
                            { return portNames(UN_PortKind::OUTPUT); }

    /// Returns a range for iterating over node output ports.
    PortRange           outputPortRange() const
                            { return portRange( UN_PortKind::OUTPUT ); }

    /// Returns true if any of the nodes output ports has a connected
    /// destination. Ie, if the node is not a terminal node. 
    /// Ie, if hte node is not a root in the tree formed by input chains.
    bool                hasConnectedOutputPortDestination() const;


    /// Returns a node name that is not taken by any of this nodes' children.
    UT_StringHolder     findUniqueChildName( const UT_StringRef &name ) const;

    /// Creates and returns a new node that is a child of this node.
    /// @param child_name - The name of the node that uniquely identifies it 
    ///     among other children inside this network.
    UN_Node             createChild( 
                                const UT_StringRef &child_name = UT_StringRef(),
                                const UT_StringRef &child_type = UT_StringRef(),
                                const UT_StringRef &child_category = 
                                    UT_StringRef()) const;

    /// Returns the child node by the given name. 
    /// Note, the return object may be invalid if no such child node was found.
    UN_Node             findChild( const UT_StringRef &child_name ) const;

    /// Removes and deletes the child node from this network.
    void                deleteChild( const UT_StringRef &child_name ) const;

    /// Returns true if the node has immediate child nodes.
    bool                hasChildren() const;
    
    /// Returns the names of the node children nodes.
    UT_Array< UT_StringHolder > childNames() const;
    
    /// An iterator and a range for the children of this parent node.
    using ChildIterator = 
        UN_DataArrayIterator< UN_Node, UN_NodeIndexArray, UN_NodeIDArray >;
    using ChildRange = UT_IteratorRange< ChildIterator >;

    /// Returns a range for iterating over node's immediate children.
    ChildRange          childRange() const; 
    
    /// An iterator and a range for the descendants (children, grandchildren,
    /// etc) of this ancestor node.
    using DescendantIterator = UN_NodeDescendantIterator;
    using DescendantRange = UT_IteratorRange< DescendantIterator >;

    /// Returns a range for iterating over nodes's descendants 
    /// (ie, children, and their grand children, etc).
    DescendantRange     descendantRange() const;


    /// An iterator and a range for the connection wires between immediate
    /// children inside this node.
    /// (And also direct wires between inputs and outputs on this node).
    using ChildWireIterator = UN_NodeWireIterator< /*child_only=*/ true >;
    using ChildWireRange = UT_IteratorRange< ChildWireIterator >;

    /// Returns a range for iterating over the connection wires between
    /// this node's immediate children.
    /// (And also direct wires between inputs and outputs on this node).
    ChildWireRange      childWireRange() const;


    /// An iterator and a range for the connection wires between 
    /// the descendants inside this node.
    /// (And also direct wires between inputs and outputs on this node).
    using DescendantWireIterator = UN_NodeWireIterator< /*child_only=*/ false >;
    using DescendantWireRange = UT_IteratorRange< DescendantWireIterator >;

    /// Returns a range for iterating over the connection wires between
    /// this node's descendants (ie, its children and grandchildren, etc).
    /// (And also direct wires between inputs and outputs on this node).
    DescendantWireRange descendantWireRange() const;


    /// Returns the options object representing this node.
    /// This can be then used for serialization to JSON, etc.
    UT_Options          asOptions() const;

    /// Configure the node based on the given options.
    void                setFromOptions( const UT_Options &node_opts ) const;


    /// Returns the node data index this handle refers to.
    UN_NodeIndex        nodeIndex() const 
                            { return UN_NodeIndex( dataIndex() ); }

    /// Returns the unique ID of the node data this handle refers to.
    UN_NodeID           nodeID() const
                            { return UN_NodeID( dataID() ); }
};


#endif