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

#ifndef __UNI_Node_h__
#define __UNI_Node_h__

#include "UNI_API.h"
#include "UNI_Item.h"

// ============================================================================
class UNI_ConstNode : public UNI_ConstItem<UNI_NodeID>
{
public:
    /// Expose base class constructors.
    using UNI_ConstItem::UNI_ConstItem;

    /// Returns true if this is the graph root node.
    bool                isRootNode() const
    { return graph() ? id() == graph()->rootNode() : false; }

    /// Returns true if this node is a subnet (can contain other nodes).
    bool                isSubnet() const
    { return graph() ? graph()->isSubnet(id()) : false; }
    /// Returns true if this subnet's contents can be modified.
    bool                isEditableSubnet() const
    { return graph() ? graph()->isEditableSubnet(id()) : false; }
    /// Returns true if this is the graph root node.
    bool                isEditable() const
    { return graph() ? graph()->isEditable(id()) : false; }
    /// Returns the name of the node.
    UT_StringHolder     name() const
    { return graph() ? graph()->name(id()) : UT_StringHolder(); }
    /// Return the full path from the root of the graph to this node.
    UT_StringHolder     path() const
    { return graph() ? graph()->path(id()) : UT_StringHolder(); }
    /// Returns the category name of the node.
    UT_StringHolder     categoryName() const
    { return graph() ? graph()->categoryName(id()) : UT_StringHolder(); }
    /// Returns the type name of the node.
    UT_StringHolder     typeName() const
    { return graph() ? graph()->typeName(id()) : UT_StringHolder(); }
    /// Returns the name of the current signature of this node.
    UT_StringHolder     signatureName() const
    { return graph() ? graph()->signatureName(id()) : UT_StringHolder(); }
    /// Returns the node position in the graph editor.
    UT_Vector2D         position() const
    { return graph() ? graph()->position(id()) : UT_Vector2D(); }
    /// Returns the color tint of the node in the graph editor.
    UT_Color            color() const
    { return graph() ? graph()->color(id()) : UT_Color(); }
    /// Returns the icon name for the given node.
    UT_StringHolder     iconName() const
    { return graph() ? graph()->iconName(id()) : UT_StringHolder(); }
    /// Returns the comment for the node.
    UT_StringHolder     comment() const
    { return graph() ? graph()->comment(id()) : UT_StringHolder(); }
    /// Returns the tags (a set of keywords) assigned to the node.
    UT_StringArray      tags() const
    { return graph() ? graph()->tags(id()) : UT_StringArray(); }
    /// Returns a dialog script describing this node's parms.
    UT_StringHolder     parmDialogScript() const
    { return graph() ? graph()->parmDialogScript(id()) : UT_StringHolder(); }
    /// Get the value of a parm on this node.
    UNI_ParmValue       parmValue( const UT_StringRef &parm_name ) const
    { return graph() ? graph()->parmValue(id(), parm_name) : UNI_ParmValue(); }

    /// Returns the id of our parent node. This may be the root node. The
    /// parent of the root node will be an invalid node.
    UNI_NodeID          parent() const
    {
        return (graph() && id() != graph()->rootNode())
            ? graph()->parentNode(id())
            : UNI_NodeID();
    }
    /// Returns the id of the node specified by the provided path, which may
    /// be absolute or relative to this node.
    UNI_NodeID          findNode( const UT_StringRef &path ) const
    { return graph() ? graph()->findNode(id(), path) : UNI_NodeID(); }
    /// Returns array of ids of all direct children of this node.
    UNI_NodeIDList      childNodes() const
    { return graph() ? graph()->childNodes(id()) : UT_Array<UNI_NodeID>(); }

    /// Returns all sticky notes contained by this node.
    UNI_StickyNoteIDList childStickyNotes() const
    { return graph() ? graph()->childStickyNotes(id()) : UNI_StickyNoteIDList(); }
    /// Find a sticky note using a path specified relative to this node.
    UNI_StickyNoteID    findStickyNote(const UT_StringRef &path) const
    { return graph() ? graph()->findStickyNote(id(), path) : UNI_StickyNoteID(); }

    /// Input ports of a node.
    UNI_PortIDList      inputPorts() const
    { return graph() ? graph()->inputPorts(id()) : UNI_PortIDList(); }
    /// Output ports of a node.
    UNI_PortIDList      outputPorts() const
    { return graph() ? graph()->outputPorts(id()) : UNI_PortIDList(); }
    /// Does this node have dynamic input or output ports (not subports).
    bool                hasDynamicPorts( UNI_NodeID node_id) const
    { return graph() ? graph()->hasDynamicPorts(id()) : false; }

    /// The position of the UI gadget for connecting to inputs or outputs of
    /// the container node.
    UT_Vector2D         containerConnectPosition(
                            UNI_ContainerConnectType contype ) const
    { return graph() ? graph()->containerConnectPosition(id(), contype) : UT_Vector2D(); }
    /// The color of the UI gadget for connecting to inputs or outputs of
    /// the container node.
    UT_Color            containerConnectColor(
                            UNI_ContainerConnectType contype ) const
    { return graph() ? graph()->containerConnectColor(id(), contype) : UT_Color(); }

    /// Copy items contained by this node.
    bool copyItems(const UNI_NodeIDList &node_ids,
        const UNI_StickyNoteIDList &note_ids,
        std::ostream &os) const
    { return graph() ? graph()->copyItems(id(), node_ids, note_ids, os) : false; }
};

// ============================================================================
class UNI_API UNI_Node : public UNI_Item<UNI_NodeID,
                                         UNI_SessionNodeID,
                                         UNI_ConstNode>
{
public:
    /// Expose base class constructors.
    using UNI_Item::UNI_Item;

    /// Create a new child node.
    UNI_NodeID createNode( const UT_StringHolder &node_name,
            const UT_StringHolder &node_type_name,
            const UT_StringHolder &signature_name = UT_StringHolder() ) const;
    /// Create a new subnet node with a pre-populates its inputs and outputs.
    UNI_NodeID createSubnet( const UT_StringHolder &subnet_node_name,
        const UNI_PortIDList &create_input_ports,
        const UNI_PortIDList &create_output_ports ) const;
    /// Sets the node name.
    void setName( const UT_StringHolder &name ) const;
    /// Sets the current signature for this node.
    void setSignature( const UT_StringHolder &signature_name ) const;
    /// Ensures the node signatures and port types for the downstream nodes 
    /// are up-to-date.
    /// If @p update_node is true, this node is updated too.
    void updateDownstreamPortTypes( bool update_node ) const;
    /// Sets the node position in the graph editor.
    void setPosition( const UT_Vector2D &pos ) const;
    /// Sets the node color.
    void setColor( const UT_Color &clr ) const;
    /// Sets the node comment.
    void setComment( const UT_StringHolder &comment ) const;
    /// Sets the node tags.
    void setTags( const UT_StringArray &tags ) const;
    /// Sets a parm value.
    void setParmValue( const UT_StringRef &parm_name,
        const UNI_ParmValue &value );

    /// Create a sticky note child.
    UNI_StickyNoteID createStickyNote( const UT_StringHolder &name ) const;
    /// Destroys this node.
    void destroy() const;

    /// Set the position of the special "connect to my container"
    /// UI element in the graph editor when viewing inside this node.
    void setContainerConnectPosition( UNI_ContainerConnectType contype,
        const UT_Vector2D &pos );
    /// Set the color of the special "connect to my container"
    /// UI element in the graph editor when viewing inside this node.
    void setContainerConnectColor( UNI_ContainerConnectType contype,
        const UT_Color &clr );

    /// Paste items into this node from a stream (created by copyItems).
    bool pasteItems(UNI_NodeIDList &node_ids,
        UNI_StickyNoteIDList &note_ids,
        std::istream &is,
        UT_StringMap<UT_StringHolder> *rename_map);
};

#endif