AbstractNode.h

/* ********************************************************************
    itom software
    URL: http://www.uni-stuttgart.de/ito
    Copyright (C) 2020, Institut fuer Technische Optik (ITO),
    Universitaet Stuttgart, Germany

    This file is part of itom and its software development toolkit (SDK).

    itom is free software; you can redistribute it and/or modify it
    under the terms of the GNU Library General Public Licence as published by
    the Free Software Foundation; either version 2 of the Licence, or (at
    your option) any later version.
   
    In addition, as a special exception, the Institut fuer Technische
    Optik (ITO) gives you certain additional rights.
    These rights are described in the ITO LGPL Exception version 1.0,
    which can be found in the file LGPL_EXCEPTION.txt in this package.

    itom is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library
    General Public Licence for more details.

    You should have received a copy of the GNU Library General Public License
    along with itom. If not, see <http://www.gnu.org/licenses/>.
*********************************************************************** */

#ifndef ABSTRACTNODE_H
#define ABSTRACTNODE_H

#include "plotCommon.h"
#include "../common/sharedStructures.h"

#include <qlist.h>
#include <qobject.h>
#include <qhash.h>
#include <qpair.h>
#include <qsharedpointer.h>
#include <qscopedpointer.h>

namespace ito {

class Channel; // forward declaration
class AbstractNode;

//----------------------------------------------------------------------------------------------------------------------------------
/* runtime type information enumeration for type of plot

*/
typedef enum 
{
    rttiUnknown             = 0x0000, //default node type
    rttiPlotNode            = 0x1000, //arbitray nodes in a tree of graphic nodes
    rttiFilterNode          = 0x2000,
    rttiPlotNodeDObj        = 0x0100,
    rttiPlotNodePCL         = 0x0200,
    rttiPlotNode1D          = 0x0001,
    rttiPlotNode2D          = 0x0002,
    rttiPlotNode25D         = 0x0003,
    rttiPlotNode3D          = 0x0004
} rttiNodeType;

class ChannelPrivate;      //forward declaration
class AbstractNodePrivate; //forward declaration

//----------------------------------------------------------------------------------------------------------------------------------
class ITOMCOMMONPLOT_EXPORT Channel
{    
public:

    /* the UpdateState enumeration defines possible states during the
       of the sender parameter of a channel.

       Usually, the update state is idle. If a parameter has been changed,
       its connected channels are set to StateUpdatePending, such that the
       channel is informed about the upcoming propagation of this changed input
       parameter. This update information is then recursively propagated to
       all child nodes (and their child nodes) of the affected node.

       Then, the value of the changed sender parameter is copied via all
       affected channels to their respective receiver parameters. The state
       is then changed to StateUpdateReceived.

       The view of affected nodes is then updated once all input channels,
       whose state has been set to StateUpdatePending is changed to StateUpdateReceived.
       This guarantees that the real update of the view is only done once all
       input channels have finished propagating their changed parameters.
    */
    enum UpdateState
    {
        StateIdle,          
        StateUpdatePending, 
        StateUpdateReceived 
    };


    Channel();


    Channel(AbstractNode *sender, ito::Param *senderParam, 
        AbstractNode *receiver, ito::Param *receiverParam);
    
    virtual ~Channel();

    Channel(const Channel& cpy);

    Channel &operator=(const Channel& rhs);
    
    AbstractNode* getSender() const;
    
    AbstractNode* getReceiver() const;

    UpdateState getUpdateState() const;

    /* This is equivalent to QLatin1String(getSender()->getName())
    */
    QString getSenderParamName() const;

    /* This is equivalent to QLatin1String(getReceiver()->getName())
    */
    QString getReceiverParamName() const;

    /*
    By propagating updates, the whole sub tree of nodes, which has a direct or indirect channel connection to the sender
    of this channel is informed about an incoming update.

    Note: this function does not propagate any updated data. It only informs about a future update of data.

    \return ito::retOk if the update pending flag has been set or if it was already set. Returns ito::retError if an error occurred. 
    */
    RetVal propagateUpdatePending();

    RetVal setUpdateReceived();

    uint getHash() const;

    ito::Param * getSenderParam() const;

    ito::Param * getReceiverParam() const;

    void resetUpdateState(void);

    bool isSender(const AbstractNode *node) const;

    bool isReceiver(const AbstractNode *node) const;

    //----------------------------------------------------------------------------------------------------------------------------------
    static uint calcChannelHash(const AbstractNode *sender, 
        const ito::Param *senderParam, 
        const AbstractNode *receiver, 
        const ito::Param *receiverParam);

private:
    QScopedPointer<ChannelPrivate> d_ptr; 
    Q_DECLARE_PRIVATE(Channel);
};

//----------------------------------------------------------------------------------------------------------------------------------
class ITOMCOMMONPLOT_EXPORT AbstractNode
{
    public:

        typedef QPair<QString, QString> ParamNamePair;

        AbstractNode();

        virtual ~AbstractNode(); //>! will delete the node and all data associated with it, except m_pCurrentData if m_isCurrent is set to TRUE

        virtual RetVal applyUpdate(void) = 0; 
        /* if all channels, whose receiver is this node and that are marked for updates (pending updates), 
        are updated with new values, this method is internally called. It calls applyUpdate, that has to be overwritten
        by the real plot/figure class, and starts to update all outgoing channels afterwards.
        */
        virtual RetVal update(void) = 0; 
        /* 
        If the channel is created, it is appended to the channel list of this node and also attached to the channel list of the receiver node.

        \param senderParamName is the output parameter name of this node, that is used as sending parameter
        \param receiver is the receiver node
        \param receiverParamName is the input parameter of the receiver, that is used as destination for the channel.
        \param replaceChannelIfExists defines if an existing channel with the same sender / receiver combination should be destroyed and created again or if
                                      the existing channel is kept without creating the new one.

        \seealso attachChannel
        */
        RetVal createChannel(const QString &senderParamName, AbstractNode *receiver, const QString &receiverParamName, bool replaceChannelIfExists = false);

        /*
        \seealso detachChannel
        */
        RetVal removeChannel(QSharedPointer<Channel> channel);

        /*
        @excludedConnections can be an optional pair of two strings, where the first string is the name of the sender parameter and the 2nd string the name of the receiver parameter.
                             If channels to the given receiver are found, that match to one entry in excludedConnections, they will not be removed.
        */
        RetVal removeAllChannelsToReceiver(const AbstractNode *receiver, QList<ParamNamePair> excludedConnections = QList<ParamNamePair>());

        QList<QSharedPointer<Channel> > getConnectedInputChannels(const QString &inputParamName) const;

        QList<QSharedPointer<Channel> > getConnectedInputChannels(const ito::Param *inputParam) const;

        QList<QSharedPointer<Channel> > getConnectedOutputChannels(const QString &outputParamName) const;

        QList<QSharedPointer<Channel> > getConnectedOutputChannels(const ito::Param *outputParam) const;

        /* This method has to copy the new value to the receiver and continue the recursive update to other child nodes.
        */
        RetVal updateChannelData(QSharedPointer<Channel> updatedChannel);
        
        /*
        if the parameter singleOutputChannel is a null object, this method calls Channel::propagateUpdatePending to 
        all channels, whose sender is this node. Else, the propagateUpdatePending method is only called for the
        one singleOutputChannel.

        \return ito::retError if singleOutputChannel is valid, however not part of the current output channels of this node. Else: ito::retOk.
        */
        RetVal setUpdatePending(QSharedPointer<ito::Channel> singleOutputChannel = QSharedPointer<ito::Channel>());

        ito::Param* getInputParam(const QString &paramName) const;

        ito::Param* getOutputParam(const QString &paramName) const;

        /* This node takes the ownership of the parameter and deletes it during the destructor.
        */
        RetVal addOutputParam(ito::Param* param);

        RetVal removeAndDeleteOutputParam(const QString &paramName);

        /* This node takes the ownership of the parameter and deletes it during the destructor.
        */
        RetVal addInputParam(ito::Param* param);

        RetVal removeAndDeleteInputParam(const QString &paramName);
        
        /* If one or multiple output parameters of a node have been changed, call this method to let the changes
        be propagated to the receiver parameters of all channels, whose sender is this node and whose sender parameter
        is equal to the given names.        
        */
        RetVal updateChannels(const QList<QString> &outputParamNames);

        rttiNodeType getType() const;

        bool isConnected() const;

        unsigned int getUniqueID(void) const;
    
    protected:
        /*
        This method does not detach this channel from the other node, that is sender or receiver of the channel.
        */
        RetVal detachChannel(QSharedPointer<Channel> channel);

        RetVal attachChannel(QSharedPointer<Channel> channel);

        RetVal inputParamChanged(const ito::ParamBase *updatedInputParam); 
        static unsigned int UID;
    
    private:
        QScopedPointer<AbstractNodePrivate> d_ptr; 
        Q_DECLARE_PRIVATE(AbstractNode);
};

//----------------------------------------------------------------------------------------------------------------------------------
} // namespace ito

#endif //ABSTRACTNODE_H