UNI_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:        UNI_Graph.h ( UNI Library, C++)
 *
 * COMMENTS:
 *      
 */

#ifndef __UNI_Graph_h__
#define __UNI_Graph_h__

#include "UNI_API.h"
#include "UNI_Include.h"
#include <UT/UT_Array.h>
#include <UT/UT_Color.h>
#include <UT/UT_Function.h>
#include <UT/UT_IntrusivePtr.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_Map.h>
#include <UT/UT_Ramp.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_StringMap.h>
#include <UT/UT_OptionEntry.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_Vector2.h>
#include <iostream>

class UNI_Graph;
class UNI_GraphHandle;

enum class UNI_ContainerConnectType
{
    INPUTS,
    OUTPUTS
};

using UNI_SelectableItemID = std::variant<UNI_NodeID,
                                          UNI_WireID,
                                          UNI_StickyNoteID,
                                          UNI_ContainerConnectType>;

// ============================================================================
/// Different types of changes that can be generated by a session graph.
/// This is a bit field
class UNI_GraphChangeType
{
public:
    UNI_GraphChangeType(int value = NONE)
        : myValue(value)
    {}

    UNI_GraphChangeType operator|(const UNI_GraphChangeType &other)
        { return UNI_GraphChangeType(myValue | other.myValue); }
    UNI_GraphChangeType operator&(const UNI_GraphChangeType &other)
        { return UNI_GraphChangeType(myValue & other.myValue); }
    bool operator==(int value) const
        { return (myValue == value); }
    bool operator!=(int value) const
        { return (myValue != value); }

    bool isSet() const
        { return myValue != NONE; }
    bool isSet(exint value) const
        { return ((myValue & value) != 0); }

    // Nothing changed - callbacks will not be invoked:
    static constexpr exint NONE                             = 0;
    // Something not covered by any other change type:
    static constexpr exint GENERIC                          = (1 <<  0);
    // The topology of the graph was changed (eg, added new nodes, 
    // new connection wires to ports, or deleted old nodes/wires, etc.):
    static constexpr exint TOPOLOGY                         = (1 <<  1);
    // The name of a node has changed:
    static constexpr exint NAME                             = (1 <<  2);
    // The signature of a node has changed:
    static constexpr exint SIGNATURE                        = (1 <<  3);
    // A parameter on the graph or a node changed:
    static constexpr exint PARAMETER                        = (1 <<  4);
    // Changed node selection or current node:
    static constexpr exint SELECTION                        = (1 <<  5);
    // The graph is about to be deleted (deleting a
    // Node in the graph is a TOPOLOGY change):
    static constexpr exint DELETED                          = (1 <<  6);
    // An aspect of the graph's UI changed (eg, wire drawing style):
    static constexpr exint UI                               = (1 <<  7);

    // NB: When adding new event types, you must also update UTformatBuffer().

private:
    /// Internal numeric representation of the graph change type.
    int          myValue;
};

size_t UNI_API
UTformatBuffer(char *buffer, size_t buffer_size, const UNI_GraphChangeType &t);

// ============================================================================
/// Intrusive pointer definition.
using UNI_GraphPtr = UT_IntrusivePtr<UNI_Graph>;
using UNI_ConstGraphPtr = UT_IntrusivePtr<const UNI_Graph>;
/// Special parm value type indicating an invalid/unset value type.
enum UNI_InvalidParmValue { UNI_INVALID_PARM_VALUE = 0 };
/// Special parm value type indicating the parm should be returned to its
/// default value.
enum UNI_DefaultParmValue { UNI_DEFAULT_PARM_VALUE = 0 };
/// Simple data type that allows passing a ramp along with a specification of
/// whether it is a color ramp or float ramp.
using UNI_RampParmValue = std::pair<bool, UT_Ramp>;
/// Variant data type that holds all the parm value types allowed in UNI parms.
using UNI_ParmValue = std::variant<
    UNI_InvalidParmValue,
    UNI_DefaultParmValue,
    bool,
    int64,
    fpreal64,
    UT_Vector2D,
    UT_Vector3D,
    UT_Vector4D,
    UT_Matrix3D,
    UT_Matrix4D,
    UT_StringHolder,
    UNI_RampParmValue>;

// ============================================================================
/// Removes the graph from the lookup table and deletes it.
struct UNI_API UNI_GraphDeleter
{
    /// Destroys the UNI graph removing it from the Houdini session.
    void operator()(UNI_Graph* graph);
};

// ============================================================================
/// A class that represents a UNI graph within the GUI layer, used by
/// node network editor classes (FUSE/OPUI/HOMF) to implement user interactions.
/// UNI graphs are available globally in a Houdini session, using graph ID
/// and static method UNI_Graph::findGraph() in this class.
class UNI_API UNI_Graph
    : public UT_IntrusiveRefCounter<UNI_Graph, UNI_GraphDeleter>
{
protected:
    /// Constructor.
    /// Intended to be used by only the (static) factory functions
    /// in the sub-classes, which create UNI_Graph instances.
    /// The constructor assigns a unique session ID to the graph and registers
    /// it in the internal look-up table; the destructor removes it from there.
    /// Subclass factory functions wrap the created graph in a UNI_GraphHandle,
    /// which takes ownership of it.
    UNI_Graph();

private:
    /// The graph deleter is a friend so that, when the last handle referencing
    /// the graph is released, it can send out the "deleted" change
    /// notification and then destroy the graph (whose destructor removes it
    /// from the look-up table).
    friend UNI_GraphDeleter;

public:
    /// Returns a UNI graph given its ID. Returns a null if not found.
    static UNI_Graph *          findGraph( UNI_GraphID id );
    
    /// Non-copyable. An internal map should be the sole owner of graph objects,
    /// since we are using ID and handles to identify them and track life span.
    UT_NON_COPYABLE(UNI_Graph)

    /// Destructor.
    virtual ~UNI_Graph();

    /// Returns the unique ID of this graph in the current Houdini session.
    /// Note, this ID can change from session to session, so should not be 
    /// serialized or saved for persistence outside of the session.
    UNI_GraphID             graphID() const
                                { return myGraphID; }

    /// @{ Control whether this graph is editable.
    bool                    isEditable() const
                                { return myIsEditable; }
    void                    setEditable(bool editable)
                                { myIsEditable = editable; }
    /// @}

    /// Returns the name of the graph. Used for human readability and UI
    /// presentation. 
    virtual UT_StringHolder name() const = 0;
    /// Returns true if the graph has no nodes.
    virtual bool            isEmpty() const = 0;
    /// Returns the ID of the root node.
    /// Ie, the ID of the parent of the top-level nodes in the graph.
    virtual UNI_NodeID      rootNode() const = 0;

    /// @{ The drawing style of the connection wires in the graph.
    virtual UNI_WireStyle   wireStyle() const = 0;
    virtual void            setWireStyle(UNI_WireStyle wire_style) = 0;
    /// @}

    /// @{ Returns true if the given ID refers to a valid item in this graph.
    virtual bool            isValid( UNI_NodeID node_id ) const = 0;
    virtual bool            isValid( UNI_PortID port_id ) const = 0;
    virtual bool            isValid( UNI_WireID wire_id ) const = 0;
    virtual bool            isValid( UNI_StickyNoteID note_id ) const = 0;
    /// @}

    /// @{ Generic functions related to entity naming.
    virtual bool            isValidName(const UT_StringRef &name) const = 0;
    virtual bool            isNameInUse(UNI_NodeID parent_id,
                                const UT_StringRef &name) const = 0;
    virtual UT_StringHolder findUniqueName(UNI_NodeID parent_id,
                                const UT_StringHolder &name) const = 0;
    /// @}

    /// @{ APIs for getting information about a node.
    /// Returns the parent of the given node. Ie, nodes can be nested, so
    /// this returns the node inside which the given child node lives.
    virtual UNI_NodeID      parentNode( UNI_NodeID node_id ) const = 0;
    /// Returns true if the given node is a subnet (can have child nodes).
    virtual bool            isSubnet( UNI_NodeID node_id ) const = 0;
    /// Returns true if the given node can be modified (ie, is inside
    /// an editable subnet). Ie, it can be connected to a new source,
    /// and its parameters can be set.
    virtual bool            isEditable( UNI_NodeID node_id ) const = 0;
    /// Returns true if the subnet inside the given parent node can be modified.
    /// Eg, new connections can be made between children,
    /// their parameters can be set, etc.
    virtual bool            isEditableSubnet( UNI_NodeID parent_id ) const = 0;
    /// Returns the children nodes that live inside the given parent node.
    virtual UNI_NodeIDList  childNodes( UNI_NodeID parent_id ) const = 0;
    /// Finds the node at the specified path relative to the given node.
    /// If the path is an absolute path, the from_id isn't used.
    virtual UNI_NodeID      findNode( UNI_NodeID from_id,
                                const UT_StringRef &path) const = 0;
    /// The name of a node.
    virtual UT_StringHolder name( UNI_NodeID node_id ) const = 0;
    /// The full path of the node.
    virtual UT_StringHolder path( UNI_NodeID node_id ) const = 0;
    /// The category name of the node.
    virtual UT_StringHolder categoryName( UNI_NodeID node_id ) const = 0;
    /// The type name of the node.
    virtual UT_StringHolder typeName( UNI_NodeID node_id ) const = 0;
    /// The name of the current signature of the given node.
    virtual UT_StringHolder signatureName( UNI_NodeID node_id ) const =0;
    /// Returns true if the node has many signatures to choose from.
    virtual bool            isMultiSignature( UNI_NodeID node_id ) const = 0;
    /// The list of function signature names this node (or node's type) offers.
    /// If @p compatible_only is true, the list contains signatures whose
    /// input/output types are compatible with current wire connections
    /// on the node; otherwise, resturns all available signatures.
    /// If @p force_include_current is true, the list will include the
    /// current node signature name eve if it may not be part of official list.
    virtual UT_Array<UNI_Signature> 
                            signatures( UNI_NodeID node_id,
                                bool compatible_only,
                                bool force_include_current) const = 0;
    /// The help URL for the node.
    /// Used for UT_HelpManager::openURL() which accepts protocols such as
    /// "http://u.r.l", "hdox://u.r.l", "operator:category/name", etc.
    virtual UT_StringHolder helpURL( UNI_NodeID node_id ) const = 0;
    /// The position of the node in the graph editor.
    virtual UT_Vector2D     position( UNI_NodeID node_id ) const = 0;
    /// The color tint of the node in the graph editor.
    virtual UT_Color        color( UNI_NodeID node_id ) const = 0;
    /// Returns the icon name for the given node.
    virtual UT_StringHolder iconName( UNI_NodeID node_id ) const = 0;
    /// The user-authored comment for a node.
    virtual UT_StringHolder comment( UNI_NodeID node_id ) const = 0;
    /// The list of tags associated with a node.
    virtual UT_StringArray  tags( UNI_NodeID node_id ) const = 0;
    /// The parameter descriptions for the specified node. This is used to
    /// build a parm dialog.
    virtual UT_StringHolder parmDialogScript( UNI_NodeID node_id ) const = 0;
    /// Get the value of a parm on this node.
    virtual UNI_ParmValue   parmValue( UNI_NodeID node_id,
                                const UT_StringRef &parm_name ) const = 0;
    /// Return true if there is a port corresponding to this parm, and that
    /// port is connected, resulting in this parm having no effect.
    virtual bool            parmOverriddenByConnection( UNI_NodeID node_id,
                                const UT_StringRef &parm_name ) const = 0;
    /// @}

    /// @{ Input ports of a node.
    virtual int             numberOfInputPorts( UNI_NodeID node_id ) const = 0;
    virtual UNI_PortIDList  inputPorts( UNI_NodeID node_id ) const = 0;
    virtual UNI_PortID      inputPort( UNI_NodeID node_id, 
                                int port_index ) const = 0;
    virtual int             findInputPortIndex( UNI_NodeID node_id, 
                                UNI_PortID port_id ) const = 0;
    /// @}

    /// @{ Output ports of a node.
    virtual int             numberOfOutputPorts( UNI_NodeID node_id ) const = 0;
    virtual UNI_PortIDList  outputPorts( UNI_NodeID node_id ) const = 0;
    virtual UNI_PortID      outputPort( UNI_NodeID node_id, 
                                int port_index ) const = 0;
    virtual int             findOutputPortIndex( UNI_NodeID node_id, 
                                UNI_PortID port_id ) const = 0;
    /// @}

    /// Return true if a node has a variable number of inputs or outputs.
    /// This does not include "subports" in APEX, which are not individually
    /// named and are not "real" ports.
    virtual bool            hasDynamicPorts( UNI_NodeID node_id ) const = 0;

    /// @{ Some graphs allow wiring directly from a container node to nodes
    /// inside the container. In this case, wireDirectlyToContainer will return
    /// true. The other methods here are for controlling the appearance of the
    /// UI for making connections to the container node when inside that
    /// container.
    virtual bool            wireDirectlyToContainer() const = 0;
    virtual UT_Vector2D     containerConnectPosition( UNI_NodeID parent_id,
                                UNI_ContainerConnectType contype ) const = 0;
    virtual UT_Color        containerConnectColor( UNI_NodeID parent_id,
                                UNI_ContainerConnectType contype ) const = 0;
    /// @}

    /// @{ APIs for dealing with Ports.
    /// Returns the node that owns the specified port.
    virtual UNI_NodeID      ownerNode( UNI_PortID port_id ) const = 0;
    /// Returns what kind of a port this is: input or output.
    virtual UNI_PortKind    portKind( UNI_PortID port_id ) const = 0;
    /// Returns whether the port accepts subports.
    virtual bool            portAcceptsSubPorts( UNI_PortID port_id ) const = 0;
    /// Returns whether the port is a subport.
    virtual bool            portIsSubPort( UNI_PortID port_id ) const = 0;
    /// Returns the "outer port" of a subport.
    virtual UNI_PortID      outerPort( UNI_PortID port_id ) const = 0;
    /// Returns the port to which wires must connect in order to serve as
    /// the src wire for a subnet's output port. Returns an empty list if
    /// the provided port isn't an output port of a subnet node.
    virtual UNI_PortIDList  subnetOutputPorts( UNI_PortID port_id ) const = 0;
    /// Returns the port to which wires must connect in order to act as
    /// a dst wire from a subnet's input port. Returns an empty list if
    /// the provided port isn't an input port of a subnet node.
    virtual UNI_PortIDList  subnetInputPorts( UNI_PortID port_id ) const = 0;
    /// The name of the port. Some ports can be renamed.
    virtual UT_StringHolder name( UNI_PortID port_id ) const = 0;
    /// Some graphs support setting port names.
    virtual bool            canSetName( UNI_PortID port_id ) const = 0;
    /// The label of the port. Some ports can be renamed.
    virtual UT_StringHolder label( UNI_PortID port_id ) const = 0;
    /// Returns the data type name for the given port.
    virtual UT_StringHolder typeName( UNI_PortID port_id ) const = 0;
    /// Returns the UI color name for the given port.
    /// The color name should adhere to the UIgetMiscColor() conventions.
    /// This method allows for color scheme adjustment of the actual color.
    virtual UT_StringHolder colorName( UNI_PortID port_id ) const = 0;
    /// Returns the visual shape of the port in the UI.
    virtual UNI_PortShape   shape( UNI_PortID port_id ) const = 0;
    /// Returns the wires that live directly inside the given parent node.
    virtual UNI_WireIDList  childWires( UNI_NodeID parent_id ) const = 0;
    /// @}

    /// @{ Return the wires that connect to a given port.
    virtual UNI_WireIDList  srcWires( UNI_PortID port_id ) const = 0;
    virtual UNI_WireIDList  dstWires( UNI_PortID port_id ) const = 0;
    /// @}

    /// @{ Get the start (src) and end (dst) ports for a wire.
    /// Note that either an input or output port may be the start or end
    /// point of a wire. The permissibility and meaning of this will depend
    /// on the specific graph implementation.
    virtual UNI_PortID      srcPort( UNI_WireID wire_id ) const = 0;
    virtual UNI_PortID      dstPort( UNI_WireID wire_id ) const = 0;
    /// @}

    /// @{ APIs for dealing with Sticky Notes.
    /// Returns the sticky notes that live inside the given parent node.
    virtual UNI_StickyNoteIDList childStickyNotes( UNI_NodeID parent_id ) const = 0;
    /// Find the sticky note at a path relative to a starting node.
    virtual UNI_StickyNoteID findStickyNote( UNI_NodeID from_id,
                                const UT_StringRef &path) const = 0;
    /// The name of a sticky note.
    virtual UT_StringHolder name( UNI_StickyNoteID note_id ) const = 0;
    /// The full path of the sticky note.
    virtual UT_StringHolder path( UNI_StickyNoteID note_id ) const = 0;
    /// Returns the id of the node that contains this sticky note.
    virtual UNI_NodeID      ownerNode( UNI_StickyNoteID note_id ) const = 0;
    /// Returns the sticky note's contents.
    virtual UT_StringHolder text( UNI_StickyNoteID note_id ) const = 0;
    /// Returns the sticky note's text (foreground) color.
    virtual UT_Color        textColor( UNI_StickyNoteID note_id ) const = 0;
    /// Returns the sticky note's text size.
    virtual float           textSize( UNI_StickyNoteID note_id ) const = 0;
    /// Returns the sticky note's (background) color.
    virtual UT_Color        color( UNI_StickyNoteID note_id ) const = 0;
    /// Returns the sticky note's position in the graph editor.
    virtual UT_Vector2D     position( UNI_StickyNoteID note_id ) const = 0;
    /// Returns the sticky note's size (width & height).
    virtual UT_Vector2D     size( UNI_StickyNoteID note_id ) const = 0;
    /// Returns true if the sticky note is collapsed (minimized).
    virtual bool            isCollapsed( UNI_StickyNoteID note_id ) const = 0;
    /// Returns true if the background of the sticky note is not drawn,
    /// effectively making it transparent.
    virtual bool            isBackgroundHidden( UNI_StickyNoteID note_id ) const = 0;
    /// @}

    /// Fill the supplied output stream with data that can be used to make
    /// copies of the specified items.
    virtual bool            copyItems(UNI_NodeID parent_id,
                                const UNI_NodeIDList &node_ids,
                                const UNI_StickyNoteIDList &note_ids,
                                std::ostream &os) const = 0;

    /// @{ Functions for tracking the current and selected nodes and wires.
    UNI_NodeID          currentChildNode( UNI_NodeID parent_id );
    const UT_Array<UNI_SelectableItemID> &selectedItems() const;
    template<typename T> UT_Array<T> selectedItemsOfType() const
    {
        UT_Array<T> items;
        for (auto &&item : mySelectedItems)
            if (auto *t_id = std::get_if<T>(&item))
                items.append(*t_id);
        return items;
    }
    bool                isItemSelected(UNI_SelectableItemID id);
    void                addSelectedItem(UNI_SelectableItemID id);
    void                removeSelectedItem(UNI_SelectableItemID id);
    void                clearSelection();
    /// @}

    /// Callback method signature when a session graph changes.
    /// The third argument indicates whether it's the outermost block 
    /// of nested change blocks.
    /// The callbacks are run on any change in the graph, whether it 
    /// occurs in outermost or inner nested scopes. It's up to the callback
    /// to check and decide whether to handle the change immediately
    /// or postpone it until the outmost block is done.
    /// Each callback is invoked with the union of all change type
    /// that occured until then, including any nested change blocks.
    using ChangeCallback = 
        UT_Function<void(UNI_Graph &, UNI_GraphChangeType, bool)>;
    using ChangeCallbackID = int;

    /// @{ Functions for managing callbacks that are invoked when this
    /// graph changes.
    ChangeCallbackID    addChangeCallback(const UNI_Graph::ChangeCallback &cb);
    void                removeChangeCallback(ChangeCallbackID id);
    /// @}

    /// @{ Utility class for invoking a graph's change callbacks.
    /// See the comment about ChangeCallback function.
    class UNI_API ChangeBlock
    {
    public:
        UT_NON_COPYABLE(ChangeBlock)
        explicit     ChangeBlock(UNI_Graph &graph,
                                 UNI_GraphChangeType change_type);
        ~ChangeBlock();

        /// Clear the graph; used only when the graph has been deleted.
        void        resetGraph()
        { myGraph = nullptr; }

        /// Returns the graph that changed.
        UNI_Graph   *graph() const
        { return myGraph; }

        /// Returns the types of changes that occurred in the graph.
        UNI_GraphChangeType changeType() const
        { return myChangeType; }

        /// Reports a change that occurred in the graph.
        void         addChangeType(UNI_GraphChangeType change_type)
        { myChangeType = myChangeType | change_type; }

    private:
        UNI_Graph           *myGraph;       // The graph that changed.
        UNI_GraphChangeType  myChangeType;  // Kind of change in the graph.
    };
    /// @}

protected:
    /// All non-const methods are protected, and should only be called by
    /// these friend classes. This ensures that the proper change notifications
    /// are sent out without subclasses ever having to worry about them.
    friend class UNI_Node;
    friend class UNI_Port;
    friend class UNI_Wire;
    friend class UNI_StickyNote;

    /// Create a new node inside the provided node.
    virtual UNI_NodeID
        createNode( UNI_NodeID parent_id,
            const UT_StringHolder &node_name,
            const UT_StringHolder &node_type_name,
            const UT_StringHolder &signature_name = UT_StringHolder() ) = 0;

    /// Create a subnet inside the provided node, and pre-populates it with
    /// input and output ports that match the supplied port ids. The subnet
    /// input and output ports will be ordered the same way they are in the
    /// provided arrays.
    virtual UNI_NodeID      createSubnet( UNI_NodeID parent_id,
                                const UT_StringHolder &subnet_node_name,
                                const UNI_PortIDList &create_input_ports,
                                const UNI_PortIDList &create_output_ports) = 0;
    /// Set the name of a node.
    virtual void            setName( UNI_NodeID node_id,
                                const UT_StringHolder &name ) = 0;
    /// Sets the new signature on a node.
    virtual void            setSignature( UNI_NodeID node_id,
                                const UT_StringHolder &signature_name ) = 0;
    /// Ensures the signatures and port types are up-to-date for 
    /// all the nodes downstream of the given node.
    /// If @p update_node is true, the given node and its ports are updated too.
    virtual void            updateDownstreamPortTypes( UNI_NodeID node_id,
                                bool update_node ) = 0;
    /// Ensures the node signatures and port types are up-to-date for 
    /// all the nodes downstream of the given port.
    /// If @p update_port is true, the given port is updated too.
    virtual void            updateDownstreamPortTypes( UNI_PortID port_id,
                                bool update_port ) = 0;
    /// Set the position of the node in the graph editor.
    virtual void            setPosition( UNI_NodeID node_id,
                                const UT_Vector2D &pos ) = 0;
    /// Set the color tint of the node in the graph editor.
    virtual void            setColor( UNI_NodeID node_id,
                                const UT_Color &clr ) = 0;
    /// Set the user-authored comment for a node.
    virtual void            setComment( UNI_NodeID node_id,
                                const UT_StringHolder &comment ) = 0;
    /// Set the list of tags associated with a node.
    virtual void            setTags( UNI_NodeID node_id,
                                const UT_StringArray &tags ) = 0;
    /// Set the value of a parm on this node.
    virtual void            setParmValue( UNI_NodeID node_id,
                                const UT_StringRef &parm_name,
                                const UNI_ParmValue &value ) = 0;
    /// Destroy a node.
    virtual void            destroy( UNI_NodeID node_id ) = 0;

    /// Set the position of the special "connect to my container"
    /// UI element in the graph editor.
    virtual void            setContainerConnectPosition( UNI_NodeID parent_id,
                                UNI_ContainerConnectType contype,
                                const UT_Vector2D &pos ) = 0;
    /// Set the color of the special "connect to my container"
    /// UI element in the graph editor.
    virtual void            setContainerConnectColor( UNI_NodeID parent_id,
                                UNI_ContainerConnectType contype,
                                const UT_Color &clr ) = 0;

    /// Set the name of the port. Some ports can be renamed.
    virtual void            setName( UNI_PortID port_id,
                                const UT_StringHolder &name ) = 0;
    /// Connect two ports.
    virtual UNI_WireID      createWire( UNI_PortID src, UNI_PortID dst ) = 0;

    /// Disconnect two ports.
    virtual void            destroy( UNI_WireID wire_id ) = 0;

    /// Create a new sticky note inside the provided node.
    virtual UNI_StickyNoteID createStickyNote( UNI_NodeID parent_id,
                                const UT_StringHolder &name ) = 0;
    /// Set the name of a sticky note.
    virtual void            setName( UNI_StickyNoteID note_id,
                                const UT_StringHolder &name ) = 0;
    /// Set the position of the sticky note in the graph editor.
    virtual void            setPosition( UNI_StickyNoteID note_id,
                                const UT_Vector2D &pos ) = 0;
    /// Set the size of the sticky note in the graph editor.
    virtual void            setSize( UNI_StickyNoteID note_id,
                                const UT_Vector2D &size ) = 0;
    /// Set the color of the sticky note background in the graph editor.
    virtual void            setColor( UNI_StickyNoteID note_id,
                                const UT_Color &clr ) = 0;
    /// Set the sticky note text in the graph editor.
    virtual void            setText( UNI_StickyNoteID note_id,
                              const UT_StringHolder &text ) = 0;
    /// Set the color of the sticky note text in the graph editor.
    virtual void            setTextColor( UNI_StickyNoteID note_id,
                                const UT_Color &clr ) = 0;
    /// Set the size of the sticky note text in the graph editor.
    virtual void            setTextSize( UNI_StickyNoteID note_id,
                              const float size ) = 0;
    /// Returns true if the sticky note is collapsed (minimized).
    virtual void            setCollapsed( UNI_StickyNoteID note_id,
                                bool collapsed ) = 0;
    /// Returns true if the background of the sticky note is not drawn,
    /// effectively making it transparent.
    virtual void            setBackgroundHidden( UNI_StickyNoteID note_id,
                                 bool hidden ) = 0;
    /// Destroy a sticky note.
    virtual void            destroy( UNI_StickyNoteID note_id ) = 0;

    /// Paste the contents of the supplied stream (generated by calling
    /// copyItems) into the specified parent network.
    virtual bool            pasteItems(UNI_NodeID parent_id,
                                UNI_NodeIDList &node_ids,
                                UNI_StickyNoteIDList &note_ids,
                                std::istream &is,
                                UT_StringMap<UT_StringHolder> *rename_map) = 0;

    /// Force handling of any pending change callbacks. We may need to do this
    /// in cases where the implementation of a subclass function requires an
    /// immediate update to the data that drives the graph. One example
    /// is HUSD_MaterialUniGraph::pasteItems.
    void                    forceTriggerChangeCallbacks(
                                const UNI_GraphChangeType &
                                    add_change_type = UNI_GraphChangeType());

private:
    /// Run all our callbacks. Should only be invoked by the
    /// UNI_Graph::ChangeBlock destructor.
    void                    runCallbacks( UNI_GraphChangeType change_type );

    /// A number uniquely identifying this UNI graph in the current session.
    UNI_GraphID                         myGraphID;

    /// Bookkeeping selection state of graph items.
    UT_Array<UNI_SelectableItemID>      mySelectedItems;

    /// Keeps track of the current node in each subnet.
    UT_Map<UNI_NodeID, UNI_NodeID>      myCurrentChildNodeIDs;
    
    /// @{ Data for managing change callbacks.
    UT_SortedMap<int, ChangeCallback>   myCallbacks;
    UT_Array<ChangeBlock *>             myChangeBlocks;
    UNI_GraphChangeType                 myAccumulatedChangeType;
    /// @}

    /// True if the graph can be edited; false for read-only graphs.
    bool                                myIsEditable = true;
};


#endif