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

#ifndef __UN_Handle_h__
#define __UN_Handle_h__


#include "UN_API.h"
#include "UN_Include.h"

class UN_GraphData;

// ============================================================================
/// A handle that references a graph entity (eg, node, port, wire, etc).
/// It abstracts the APIs that operate on this entity's data stored 
/// inside graph's data containers.
/// It is a constant handle, so allows only queries of the entity's data,
/// but does not allow setting new values for.
class UN_ConstHandle
{
public:
    /// Constructs a reference handle for an invalid entity in the graph.
    UN_ConstHandle() 
        : UN_ConstHandle( nullptr,  UN_DataID() )
    {
        UT_ASSERT( !isNumericallyValid() );
    }

    /// Constructs reference handle to the data for a given entity in the graph.
    UN_ConstHandle( const UN_GraphData *graph_data, UN_DataID data_id )
        : myGraphData( graph_data )
        , myDataID( data_id )
    {}

    /// @{ Returns the underlying graph data object.
    const UN_GraphData *graphData() const
                            { return myGraphData; }
    const UN_GraphData *constGraphData() const
                            { return myGraphData; }
    /// @}

    /// The unique number identifying this data object during the lifespan 
    /// of the owner graph. Used for referring to this object in the graph.
    UN_DataID           dataID() const
                            { return myDataID; }

protected:
    /// @{ Comparison operators, for use by the derived classes.
    /// Note, protected to prevent comparing against incompatible handles,
    /// for example, UN_Port against UN_Wire.
    bool operator==( const UN_ConstHandle &other ) const
    { 
        return // both handles are equal to each other
            (myGraphData == other.myGraphData && 
             myDataID    == other.myDataID) 
            || // or both handles are invalid
            (!isNumericallyValid() && !other.isNumericallyValid());
    }

    bool operator!=( const UN_ConstHandle &other ) const
    {   
        return !( *this == other ); 
    }
    /// @}

    /// Returns true if the handle can refer to a valid data.
    /// Note, subclasses have a stricter notion of a valid handle:
    /// not only it needs to be numerically valid, but 
    // /it also must have an entry in the data ID map (ie not deleted).
    bool                isNumericallyValid() const
                            { return myGraphData && myDataID; }

private:
    /// The graph that owns, manages, and operates on data object.
    const UN_GraphData *myGraphData = nullptr;

    /// The unique identification number of a data object during the lifespan
    /// of the graph above. Used for referring to the data object in a graph.
    UN_DataID           myDataID;
};


// ============================================================================
/// A handle that references a graph entity (eg, node, port, wire, etc).
/// It abstracts the APIs that operate on this entity's data stored 
/// inside graph's data containers.
/// It is a mutable handle, so allows setting the entity's data.
class UN_Handle : public UN_ConstHandle
{
public:
    /// Constructs a reference handle for an invalid entity in the graph.
    UN_Handle() 
        : UN_Handle( nullptr,  UN_DataID() )
    {}

    /// Constructs reference handle to the data for a given entity in the graph.
    UN_Handle( UN_GraphData *graph_data, UN_DataID data_id )
        : UN_ConstHandle( graph_data, data_id )
    {}

    /// Returns the graph that owns, manages, and operates on the data object.
    UN_GraphData *graphData() const
    { 
        // Note, casting away the const is fine, since the base class is 
        // always constructed with a *mutable* graph data pointer.
        return const_cast <UN_GraphData*>( constGraphData());
    }

    /// Returns the graph that owns, manages, and operates on the data object.
    const UN_GraphData *constGraphData() const
    { 
        return UN_ConstHandle::constGraphData(); 
    }
};


#endif