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

#ifndef __UNI_Category_h__
#define __UNI_Category_h__

#include "UNI_API.h"
#include "UNI_Include.h"
#include <UT/UT_NonCopyable.h>
#include <UT/UT_Notifier.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_UniquePtr.h>

class UNI_NodeTypeEvent;


// ============================================================================
/// The category of node types, nodes, and port types that work together
/// in a domain-specific specialization context of the UNI graph.
/// 
/// It groups these concepts into one umbrella, isolating them from other
/// incompatible nodes and types. It allows presenting available node types
/// and determine connectability of node ports, avoiding type collisions, etc.
/// 
class UNI_API UNI_Category 
{
public:
    /// @{ Constructor and destructor
                 UNI_Category( const UT_StringRef &name,
                               const UT_StringRef &label = UT_StringRef() );
    virtual     ~UNI_Category();
                 UT_NON_COPYABLE(UNI_Category)
    /// @}

    /// Returns the name of this category.
    /// It is used for finding node types in the category, filtering
    /// shelved tools in the Tab menu, filtering RMB node menu items, etc.
    const UT_StringHolder & name() const    { return myName; }

    /// Returns the label of this category.
    /// It is used for user-facing label of the category, such as the name 
    /// that appears in the upper-right corner of network editor, etc.
    const UT_StringHolder & label() const
    {
        return myLabel ? myLabel : myName; 
    }

    /// Returns the list of known node type names in this category.
    virtual UT_StringArray  nodeTypeNames() const = 0;

    /// Returns true if the given node type name is valid in this category.
    virtual bool            isValidNodeType(
                                    const UT_StringRef &type_name ) const = 0;

    /// Returns true if the given node type is hidden from the Tab menu.
    virtual bool            isHiddenNodeType(
                                    const UT_StringRef &type_name ) const = 0;

    /// Returns the label of the given node type for the display in UI.
    virtual UT_StringHolder nodeTypeLabel(
                                    const UT_StringRef &type_name ) const = 0;

    /// Returns the name of the icon for the given node type.
    virtual UT_StringHolder nodeTypeIcon(
                                    const UT_StringRef &type_name ) const = 0;

    /// Returns the list of function signature names node type offers.
    virtual UT_Array<UNI_Signature> nodeTypeSignatures( 
                                    const UT_StringRef &type_name ) const = 0;

    /// Returns node types names in the preferred order for the given node type.
    /// Some node types may have several versions as well as namespaces,
    /// and Houdini may be configured to prefer one namespace or version over
    /// the other. This method returns the node types in that preferred ordered.
    virtual UT_StringArray  nodeTypeNamesInPrecedenceOrder(
                                    const UT_StringRef &type_name ) const = 0;

    /// Returns the node type name used for a generic subnet in this context,
    /// if there is any. Otherwise, returns an empty string.
    virtual UT_StringHolder subnetNodeTypeName() const = 0;

    /// Returns the node type category names that can be children of the
    /// specified node type.
    virtual UT_StringArray  childCategoryNames(
                                    const UT_StringRef &type_name) const = 0;

    /// Returns true if Houdini should create a default shelf tool for
    /// the given node type, if there is no such tool already.
    virtual bool            shouldGenerateToolForNodeType(
                                    const UT_StringRef &type_name) const = 0;

    /// Information about the default shelf tool for a UNI node type.
    class ToolInfo
    {
    public:
        /// Shelf tool label.
        void                    setLabel( const UT_StringRef &label ) 
                                    { myLabel = label; }
        const UT_StringHolder & label() const
                                    { return myLabel; }

        /// Shelf tool sub-menu in the Tab menu.
        void                    setSubmenus( const UT_StringArray &submenus ) 
                                    { mySubmenus = submenus; }
        const UT_StringArray &  submenus() const
                                    { return mySubmenus; }

        /// Shelf tool icon.
        void                    setIcon( const UT_StringRef &icon ) 
                                    { myIcon = icon; }
        const UT_StringHolder & icon() const
                                    { return myIcon; }

        /// Default name for the nodes created by the tool.
        void                    setDefaultNodeName( const UT_StringRef &name ) 
                                    { myDefaultNodeName = name; }
        const UT_StringHolder & defaultNodeName() const
                                    { return myDefaultNodeName; }

        /// Shelf tool script.
        void                    setScript( const UT_StringRef &script )
                                    { myScript = script; }
        const UT_StringHolder & script() const
                                    { return myScript; }

    private:
        UT_StringHolder myLabel;            // Tool label
        UT_StringArray  mySubmenus;         // Tab menu submenus for the tool
        UT_StringHolder myIcon;             // Tool icon
        UT_StringHolder myDefaultNodeName;  // Name of the created node
        UT_StringHolder myScript;           // Tool script
    };

    /// Returns information about a default shelf tool for the given node type.
    virtual ToolInfo        nodeTypeToolInfo(
                                    const UT_StringRef &type_name ) const = 0;


    /// Returns an object for notifying interested parties about
    /// changes to the known node types (adding a new or removing old one).
    virtual UT_NotifierImpl<const UNI_NodeTypeEvent &> &
                            getNodeTypeEventNotifier() = 0;

private:
    /// The unique name of the category.
    UT_StringHolder     myName;

    /// The label of the category.
    UT_StringHolder     myLabel;
};

/// A handle to the category object, for expressing the ownership.
using UNI_CategoryHandle = UT_UniquePtr< UNI_Category >;


// ============================================================================
/// Class containing info about node type registry change event.
class UNI_NodeTypeEvent
{
public:
    /// Enumeration of event types.
    enum class Type
    {
        NodeTypeAdded,      // Node type added
        NodeTypeRemoved     // Node type removed
    };

    /// Constructor.
    UNI_NodeTypeEvent(
            const UNI_Category &category, Type type, const UT_StringRef name ) 
        : myCategory(category)
        , myType(type)
        , myName(name)
    {}

    /// Category issuing the event.
    const UNI_Category &    category() const
                                { return myCategory; }

    /// Event type.
    Type                    type() const
                                { return myType; }

    /// Name of added/removed node type.
    const UT_StringHolder & name() const
                                { return myName; }

private:
    const UNI_Category &    myCategory; // The category issuing event
    Type                    myType;     // Type of the event
    const UT_StringHolder   myName;     // Name of affected node type
};

#endif