UN_Graph.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_Graph.h ( UN Library, C++)
 *
 * COMMENTS:
 *      
 */

#ifndef __UN_Graph_h__
#define __UN_Graph_h__

#include "UN_API.h"
#include "UN_Node.h"
#include <UT/UT_StringHolder.h>

class UN_GraphData;


// ============================================================================
/// A light-weight handle/pointer for the graph data. 
/// 
/// The actual graph data and logic is implemented in UN_GraphData
/// owned by UN_Context.
///
/// UN_Graph serves as a handle/pointer for clients to refer to that graph data.

class UN_API UN_Graph
{
public:
    /// Defaul constructor that creates an invalid UN_Graph handle.
                            UN_Graph();

    /// Constructor that creates a valid UN_Graph handle (if parm is not null).
    /// Takes a pointer to the graph data owned by the graph owner.
                            UN_Graph( UN_GraphData *graph_data );

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

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

    /// @{ Comparison operators
    bool                    operator==( const UN_Graph &other ) const
                                { return myGraphData == other.myGraphData; }
    bool                    operator!=( const UN_Graph &other ) const
                                { return !( *this == other ); }
    /// @}

    /// Returns the root node of the graph's node parental hierarchy.
    /// The root is a special node that holds graph's top-level nodes.
    /// It cannot be deleted or renamed.
    UN_Node                 rootNode() const;

    // TODO: FIXME: consider having UN_GraphConfig object that would
    //      indicate whether to ensureValidNodeNames(), then automatically
    //      call this method to validate name of any created node
    //      This would propagate to UN_Node::createChild() too.
    //      Then adjust calls to findUniqueNodeNames() in testun.
    /// Returns a name that is not used by any of the top level nodes.
    UT_StringHolder         findUniqueNodeName( 
                                    const UT_StringRef &name = UT_StringRef()
                                    ) const;
    
    /// Creates a new top-level node in the graph.
    UN_Node                 createNode( 
                                    const UT_StringRef &name = UT_StringRef(), 
                                    const UT_StringRef &type = UT_StringRef(),
                                    const UT_StringRef &category =UT_StringRef()
                                    ) const;

    /// Returns a top-level node by the given name. 
    /// Note, the return object may be invalid if no such node was found.
    UN_Node                 findNode( const UT_StringRef &node_name ) const;

    /// Removes and deletes the top-level node from this graph.
    void                    deleteNode( const UT_StringRef &node_name ) const;

    /// Returns the names of the graph's top-level nodes.
    UT_Array< UT_StringHolder > nodeNames() const;
    

    /// Iterarates over the top-level nodes of the graph.
    using NodeIterator = UN_Node::ChildIterator;
    using NodeRange = UT_IteratorRange< NodeIterator >;

    /// Returns a range for iterating over graph's top-level nodes.
    NodeRange               nodeRange() const; 


    /// Iterarates over all the nodes in the graph; the top-level nodes
    /// and their descendants too.
    using AllNodeIterator = UN_Node::DescendantIterator;
    using AllNodeRange = UT_IteratorRange< AllNodeIterator >;

    /// Returns a range for iterating over graph's top-level nodes.
    AllNodeRange            allNodeRange() const; 


    /// An iterator and a range for the top-level wires inside this graph.
    using WireIterator = UN_Node::ChildWireIterator;
    using WireRange = UT_IteratorRange< WireIterator >;

    /// Returns a range for iterating over graph's top-level connection wires.
    WireRange               wireRange() const;


    /// An iterator and a range for all the connection wires in this graph.
    using AllWireIterator = UN_Node::DescendantWireIterator;
    using AllWireRange = UT_IteratorRange< AllWireIterator >;

    /// Returns a range for iterating over graph's top-level connection wires.
    AllWireRange            allWireRange() const;


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

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


private:
    /// Graph data structures, containing details about the graph as a whole,
    /// such as its nodes and connections between them.
    UN_GraphData *          myGraphData;
};

#endif