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

#ifndef __UN_Parm_h__
#define __UN_Parm_h__

#include "UN_API.h"
#include "UN_Handle.h"
#include "UN_ParmUtils.h"

class UN_ConstGraph;
class UN_ConstNode;
class UN_Graph;
class UN_Node;


// ============================================================================
/// Base class template for the UN parameter handle.
/// Its main purpose is to factor common code for const and non-const handles.
template <typename BASE_CLASS,  // class to derive from
          typename GRAPH_DATA>  // UN_GraphData or const UN_GraphData
class UN_ParmBase : public BASE_CLASS
{
protected:
    /// Constructs a handle for an invalid parameter.
    UN_ParmBase() = default;

    /// Constructs a handle that references the given parm in the given graph.
    // Note, it's a template to allow either a const or a non-const graph.
    template <typename GRAPH>
    UN_ParmBase( GRAPH *graph_data, UN_ParmID parm_id )
        : BASE_CLASS( graph_data, parm_id ) 
        {}

public:
    /// @{ Returns the owner of the underlying graph data structures.
    GRAPH_DATA *            graphData() const
                                { return BASE_CLASS::graphData(); }
    const UN_GraphData *    constGraphData() const
                                { return BASE_CLASS::constGraphData(); }
    /// @}

    /// Returns the unique ID of the parameter this handle refers to.
    UN_ParmID               parmID() const
                                { return UN_ParmID( BASE_CLASS::dataID() ); }

    /// @{ Returns true if this parm is valid within the graph; false otherwise.
    bool                    isValid() const
                                { 
                                    return UN_ParmUtils::isValid(
                                            graphData(), parmID());
                                }

    explicit operator       bool() const
                                { return isValid(); }
    /// @}

    
    /// Returns the parameter name that identifies it on the node.
    const UT_StringHolder & name() const
    { 
        return UN_ParmUtils::name( graphData(), parmID() );
    }

    /// Returns the parameter's type that determines the value type.
    const UT_StringHolder & typeName() const
    { 
        return UN_ParmUtils::typeName( graphData(), parmID() );
    }

    /// Returns the value of the parameter.
    UT_OptionEntryPtr value() const
    {
        return UN_ParmUtils::value( graphData(), parmID() );
    }
};


// ============================================================================
/// A handle that references a mutable parameter in a graph.
/// It abstracts the APIs that operate on this parameter's data, 
/// which is stored inside graph's data containers.
/// It is a non-const (read-write) handle, so allows both queries 
/// and mutations (edits) of the parameter's data.
class UN_API UN_Parm : public UN_ParmBase< UN_Handle, UN_GraphData >
{
public:
    /// Constructs a handle for an invalid node.
    UN_Parm() = default;

    /// Constructs a handle referencing the given parameter in the given graph.
    UN_Parm( UN_GraphData *graph_data, UN_ParmID parm_id )
        : UN_ParmBase( graph_data, parm_id ) 
    {}

    /// @{ Comparison operators.  
    // Allows comparing parm handles, but guards against 
    // comparing parms to wires, for example.
    bool    operator==( const UN_Parm &other ) const
                { return UN_ConstHandle::operator==( other ); }
    bool    operator!=( const UN_Parm &other ) const
                { return UN_ConstHandle::operator!=( other ); }
    /// @}


    /// Returns the graph whithin which this port exists.
    UN_Graph graph() const;

    /// Returns the node to which this parameter belongs.
    UN_Node node() const;


    /// Sets the parameter value. 
    void setValue( const UT_OptionEntry &value ) const
    {
        UN_ParmUtils::setValue( graphData(), parmID(), value);
    }

    /// Sets the parameter value using move-assignment. 
    void setValue( UT_OptionEntryPtr &&value ) const
    {
        UN_ParmUtils::setValue( graphData(), parmID(), std::move( value ));
    }

    /// Deletes this parameter and removes from the node and the graph.
    void destroy() const
    {
        UN_ParmUtils::deleteParm( graphData(), parmID() );
    }
};

// ============================================================================
/// A handle that references a const parameter in a graph.
/// It abstracts the APIs that operate on this parameter's data stored inside 
/// graph's data containers.
/// It is a constant handle, so allows only queries of the parameter's data,
/// but does not allow setting any new values on it.
class UN_API UN_ConstParm : public UN_ParmBase< UN_ConstHandle,
    const UN_GraphData >
{
public:
    /// Constructs a handle for an invalid parameter.
    UN_ConstParm() = default;

    /// Constructs a handle referencing the given parameter in the given graph.
    UN_ConstParm( const UN_GraphData *graph_data, UN_ParmID parm_id )
        : UN_ParmBase( graph_data, parm_id ) 
    {}

    /// Constructs a const handle from a mutable parm handle.
    UN_ConstParm( const UN_Parm &parm )
        : UN_ConstParm( parm.constGraphData(), parm.parmID() ) 
    {}

    /// @{ Comparison operators.  
    // Allows comparing parm handles, but guards against 
    // comparing parm to wires, for example.
    bool    operator==( const UN_ConstParm &other ) const
                { return UN_ConstHandle::operator==( other ); }
    bool    operator!=( const UN_ConstParm &other ) const
                { return UN_ConstHandle::operator!=( other ); }
    /// @}


    /// Returns the graph whithin which this parameter exists.
    UN_ConstGraph graph() const;

    /// Returns the node to which this parameter belongs.
    UN_ConstNode node() const;
};

// ============================================================================
// Free functions to compare a non-const parm handle to a const parm handle.
// Note, the const to non-const comparison is covered by implicit conversion
// of non-const handle to const handle, and using const to const handle comp.
static inline bool
operator==( const UN_Parm &a,  const UN_ConstParm &b )
{
    return b == UN_ConstParm(a);
}

static inline bool
operator!=( const UN_Parm &a,  const UN_ConstParm &b )
{
    return !(b == a);
}

// ============================================================================

#endif