/*=========================================================================
                                                                                
  Program:   bbtk
  Module:    $RCSfile: bbtkUserBlackBox.h,v $
  Language:  C++
  Date:      $Date: 2008/01/22 15:02:00 $
  Version:   $Revision: 1.1.1.1 $
                                                                                
  Copyright (c) CREATIS (Centre de Recherche et d'Applications en Traitement de
  l'Image). All rights reserved. See Doc/License.txt or
  http://www.creatis.insa-lyon.fr/Public/bbtk/License.html for details.
                                                                                
     This software is distributed WITHOUT ANY WARRANTY; without even
     the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
     PURPOSE.  See the above copyright notices for more information.
                                                                                
=========================================================================*/


/**
 *  \file 
 *  \brief class bbtk::UserBlackBox : Ancestor of all user defined (concrete) black boxes
 */

/**
 *  \class bbtk::UserBlackBox
 *  \brief Ancestor of all user defined (concrete) black boxes.
 */
 
#ifndef __bbtkUserBlackBox_h__
#define __bbtkUserBlackBox_h__

#include "bbtkBlackBox.h"
#include "bbtkUserBlackBoxDescriptor.h"

namespace bbtk
{

 
  //==================================================================
  class BBTK_EXPORT UserBlackBox : public bbtk::BlackBox
  {
    //==================================================================
  public: 
    //==================================================================
    /// Gets the output Data of a given label
    Data bbGetOutput( const std::string &label );
    ///  Gets the input Data of a given label
    Data bbGetInput( const std::string &label );
    ///  Sets the data of the output called <name>
    void bbSetOutput( const std::string &name, Data data);
    ///  Sets the data of the input called <name>
    void bbSetInput( const std::string &name, Data data, 
		     bool setModified = true);
    ///  Sets the data of the input called <name>
    void bbBruteForceSetInputPointer( const std::string &name, 
				      void* data, 
				      bool setModified = true);
    //==================================================================

    //==================================================================
    ///  Destructor
    virtual ~UserBlackBox();
    //==================================================================

    //==================================================================
  protected:
    //==================================================================
    ///  Constructor with the UserBlackBox's instance name
    UserBlackBox(const std::string &name, bool alloc = true);
    /// Constructor from an existing box (copy) with a new instance name 
    UserBlackBox(UserBlackBox& from, const std::string &name, 
		 bool alloc = true);
    //==================================================================

  public:
    //==================================================================   
    /// Recursive pipeline processing in backward direction 
    /// (recursion is in backward direction however execution always goes forward).
    /// 
    /// \returns The final status of the box (UPTODATE or MODIFIED)
    ///
    /// First checks that re-processing is needed (either Status==MODIFIED or InputProcessMode==Always)
    /// then : 
    /// - updates its inputs by calling bbUpdateInputs (which recursively calls bbBackwardUpdate on amont boxes)
    /// - calls bbCreateWidget
    /// - calls bbProcess which is the user callback which does the actual processing
    /// - calls bbUpdateChildren
    /// - calls bbShowWidget which shows the widget associated to the box (if any)
    IOStatus bbBackwardUpdate(Connection* caller);
    //==================================================================

    //==================================================================
    /// Recursive pipeline processing in forward direction along "Child"-"Parent" connections
    /// 
    /// First checks that re-processing is needed (either Status==MODIFIED or InputProcessMode==Always)
    /// then : 
    /// - calls bbCreateWidget
    /// - calls bbProcess which is the user callback which does the actual processing
    /// - calls bbUpdateChildren which recursively calls bbForwardUpdate on connections attached the "Child" output
    // void bbForwardUpdate(Connection* caller);
    //==================================================================
  protected:
    //==================================================================
    /// User callback which computes the outputs as a function of the inputs. 
    /// It is assumed to be deterministic and thus is only called is the inputs have changed 
    /// (i.e. if the black box is marked as modified)
    virtual void bbProcess() 
    {
      bbtkWarning("UserBlackBox::bbProcess() not overloaded for box '"
		  <<bbGetFullName()
		  <<"' : the box does nothing. Is it a bug or a feature ?"
		  <<std::endl);
    }
    //==================================================================

    //==================================================================
    /// User callback called in the box contructor
    virtual void bbUserConstructor() {}
    /// User callback called in the box copy constructor
    virtual void bbUserCopyConstructor() {}
    /// User callback called in the box destructor
    virtual void bbUserDestructor() {}
    //==================================================================    

     //==================================================================
  private:
    //================================================================== 
    /// Default constructor is private : 
    /// derived classes must use the constructor with the UserBlackBox's name
    UserBlackBox() : BlackBox("") {}
    //================================================================== 


  };
  // Class UserBlackBox
  //===========================================================================



}
// namespace bbtk


#include "bbtkUserBlackBoxMacros.h"

#endif