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

#ifndef __UN_Port_h__
#define __UN_Port_h__

#include "UN_API.h"
#include "UN_Iterator.h"
#include "UN_Handle.h"


class UN_Node;
template<typename> class UT_Array;


// ============================================================================
/// A light-weight handle for a port data object.
/// 
/// The actual port data (UN_PortData) is owned and managed by UN_GraphData,
/// and UN_Port serves as a handle for clients to refer to that port data.

class UN_API UN_Port : public UN_Handle
{
public:

    /// Convenience constructor for the port handle.
                UN_Port( UN_GraphData *graph_data, 
                         UN_PortIndex port_index, 
                         UN_PortID port_id );

    /// @{ Default destructor, constructors and assignment operators.
                UN_Port();
               ~UN_Port();
                UN_Port( const UN_Port & );
                UN_Port( UN_Port && );
    UN_Port&    operator=( const UN_Port & );
    UN_Port&    operator=( UN_Port && );
    /// @}

    /// @{ Returns true if the parameter exists; false otherwise.
    bool                        isValid() const;
    explicit operator           bool() const
                                    { return isValid(); }
    /// @}

    /// @{ Comparison operators
    bool                        operator==( const UN_Port &other ) const
                                    { return UN_Handle::operator==( other ); }
    bool                        operator!=( const UN_Port &other ) const
                                    { return UN_Handle::operator!=( other ); }
    /// @}


    /// Returns the parent of this node.
    UN_Node                     node() const;

    /// Returns the kind of a port. Ie, if a port is an input or an output.
    UN_PortKind                 kind() const;

    /// Returns the name of the port.
    UT_StringHolder             name() const;

    /// Returns name of the type of the port.
    UT_StringHolder             typeName() const;


    /// Connects this port to a source from which to obtain data or a value.
    /// Returns the newly created connection wire (may be invalid, if error).
    // TODO: FIXME: add a 'mode' parm to specify whether to replace, append, or
    //      prepend the new connection. Currently we replace.
    UN_Wire                     connectSource( 
                                        const UN_Port &src_port ) const;

    /// Disconnects this port from the given source.
    void                        disconnectSource( 
                                        const UN_Port &src_port ) const;

    /// Disconnect this port from all its connected sources.
    void                        disconnectSources() const;

    /// Disconnect this port from all its connected destinations,
    /// to which this port provides data.
    void                        disconnectDestinations() const;


    /// Returns the wires connecting this port to its sources.
    /// Ie, connection wires from which this port takes (receives) data.
    UT_Array<UN_Wire>           sourceWires() const;

    /// Returns the wires connecting this port to its destinations. 
    /// Ie, connection wires to which this port provides (sends) data.
    UT_Array<UN_Wire>           destinationWires() const;

    /// Returns the first source port connected to this port.
    /// May return an invalid port if no source port is connected.
    /// This is a convenience method for very common graphs,  
    /// where ports can have at most one source.
    UN_Port                     sourcePort() const;


    /// And iterator and a range for iterating over connected source ports.
    using SourcePortIterator = UN_WireArrayPortIterator< /*src=*/ true >;
    using SourcePortRange = UT_IteratorRange< SourcePortIterator >;

    /// Returns a range for iterating over this port's source ports.
    SourcePortRange             sourcePortRange() const;


    /// And iterator and a range for iterating over connected destination ports.
    using DestinationPortIterator = UN_WireArrayPortIterator< /*src=*/ false >;
    using DestinationPortRange = UT_IteratorRange< DestinationPortIterator >;

    /// Returns a range for iterating over this port's destination ports.
    DestinationPortRange        destinationPortRange() const;


    /// Deletes this port.
    void                        destroy() const;

    /// Returns the port data index this handle refers to.
    UN_PortIndex                portIndex() const 
                                    { return UN_PortIndex( dataIndex() ); }

    /// Returns the unique ID of the port data this handle refers to.
    UN_PortID                   portID() const
                                    { return UN_PortID( dataID() ); }
};


#endif