/*=========================================================================

   Program: ParaView
   Module:    $RCSfile: pqObjectBuilder.h,v $

   Copyright (c) 2005-2008 Sandia Corporation, Kitware Inc.
   All rights reserved.

   ParaView is a free software; you can redistribute it and/or modify it
   under the terms of the ParaView license version 1.2. 

   See License_v1.2.txt for the full ParaView license.
   A copy of this license can be obtained by contacting
   Kitware Inc.
   28 Corporate Drive
   Clifton Park, NY 12065
   USA

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

========================================================================*/
#ifndef __pqObjectBuilder_h
#define __pqObjectBuilder_h

#include <QObject>
#include "pqCoreExport.h"
#include <QMap>

class pqAnimationScene;
class pqDataRepresentation;
class pqNameCount;
class pqOutputPort;
class pqPipelineSource;
class pqProxy;
class pqRepresentation;
class pqScalarBarRepresentation;
class pqScalarsToColors;
class pqServer;
class pqView;
class vtkSMProxy;
class pqServerResource;

/// pqObjectBuilder is loosely based on the \c Builder design pattern.
/// It is used to create as well as destroy complex objects such as 
/// views, displays, sources etc. Since most of the public API is 
/// virtual, it is possible for custom applications to subclass
/// pqObjectBuilder to provide their own implementation for creation/
/// destroying these objects. The application layer accesses the
/// ObjectBuilder through the pqApplicationCore singleton.
/// NOTE: pqObjectBuilder replaces the previously supported 
/// pqPipelineBuilder. Unlink, pqPipelineBuilder, this class
/// no longer deals with undo/redo stack. The application layer
/// components that use the ObjectBuilder are supposed to bother
/// about the undo stack i.e. call begin/end on the undo stack
/// before/after calling creation/destruction method on the ObjectBuilder.
class PQCORE_EXPORT pqObjectBuilder : public QObject
{
  Q_OBJECT
  typedef QObject Superclass;

public:
  pqObjectBuilder(QObject* parent=0);
  virtual ~pqObjectBuilder();
  
  /// Create a server connection give a server resource
  pqServer* createServer(const pqServerResource& resource);
 
  /// Destroy a server connection 
  void removeServer(pqServer *server);

  /// Creates a source of the given server manager group (\c sm_group) and 
  /// name (\c sm_name) on the given \c server. On success, returns the
  /// pqPipelineSource for the created proxy.
  virtual pqPipelineSource* createSource(const QString& sm_group,
    const QString& sm_name, pqServer* server);

  /// Creates a filter with the given Server Manager group (\c sm_group) and
  /// name (\c sm_name). If the filter accepts multiple inputs, all the inputs
  /// provided in the list are set as input, instead only the first one
  /// is set as the input. All inputs must be on the same server.
  virtual pqPipelineSource* createFilter(
    const QString& group, const QString& name,
    QMap<QString, QList<pqOutputPort*> > namedInputs, pqServer* server);

  /// Convenience method that takes a single input source.
  virtual pqPipelineSource* createFilter(
    const QString& group, const QString& name,
    pqPipelineSource* input);

  /// Creates a reader of the given server manager group (\c sm_group) and 
  /// name (\c sm_name) on the given \c server. On success, returns the
  /// pqPipelineSource for the created proxy.
  virtual pqPipelineSource* createReader(const QString& sm_group,
    const QString& sm_name, const QStringList& files, pqServer* server);

  /// Creates a new view module of the given type on the given server.
  virtual pqView* createView(const QString& type, 
    pqServer* server);

  /// Destroys the view module. This destroys the view module
  /// as well as all the displays in the view module.
  virtual void destroy(pqView* view);

  /// Creates a representation to show the data from the given output port of a
  /// source in the given \c view.
  virtual pqDataRepresentation* createDataRepresentation(
    pqOutputPort* source, pqView* view, const QString &representationType="");

  /// Destroys the data display. It will remove the display from any 
  /// view modules it is added to and then unregister it.
  virtual void destroy(pqRepresentation* repr);

  /// Creates a scalar bar display to show a lookup table
  /// in the view.
  virtual pqScalarBarRepresentation* createScalarBarDisplay(
    pqScalarsToColors* lookupTable, pqView* view);


  /// Creates an animation scene on the given server connection.
  virtual pqAnimationScene* createAnimationScene(pqServer* server);

  /// Convenience method to create a proxy of any type on the given server.
  /// One can alternatively use the vtkSMProxyManager to create new proxies 
  /// directly. This method additionally set the connection ID on
  /// the new proxy. If reg_name is empty, then a new name is assigned.
  virtual vtkSMProxy* createProxy(const QString& sm_group, 
    const QString& sm_name, pqServer* server, 
    const QString& reg_group, const QString& reg_name=QString());

  /// Destroys a source/filter. Removing a source involves the following:
  // \li removing all displays belonging to the source,
  // \li breaking any input connections.
  // \li unregistering the source.
  // Note that the source must have no consumers, otherwise,
  // one cannot delete the source.
  virtual void destroy(pqPipelineSource* source);

  /// Convenience method, simply unregisters the Server Manager proxy 
  /// which the pqProxy represents.
  virtual void destroy(pqProxy* proxy);

  /// Destroy all sources/filters on a server.
  virtual void destroySources(pqServer* server=0);

  /// Destroy all lookup tables and scalar bars associated with them.
  virtual void destroyLookupTables(pqServer* server=0);

  /// Destroys all proxies that are involved in pipelines i.e. simply calls
  /// destroySources(), destroyLookupTables().
  virtual void destroyPipelineProxies(pqServer* server=0);

  /// This method unregisters all proxies on the given server. 
  /// This is usually done in anticipate of a disconnect
  /// or starting afresh.
  virtual void destroyAllProxies(pqServer* server);

  /// This is a convenience method to return the name of the
  /// property on the proxy, if any, which can be used to set the filename.
  /// If no such property exists, this retruns a null string.
  QString getFileNamePropertyName(vtkSMProxy*)  const;
  
  // HACK: pqSimpleServerStartup needs to fire the
  // finishedAddingServer() signal on successful
  // reverse connection. Server creation and correspoinding
  // signals need a bit reorganizing.
  void fireFinishedAddingServer(pqServer* server)
    {
    emit this->finishedAddingServer(server);
    }

signals:
  
  /// Emitted after a new server connection is created
  void finishedAddingServer(pqServer *server);

  /// Fired on successful completion of createSource().
  /// Remember that this signal is fired only when the creation of the object
  /// is requested by the GUI. It wont be triggered when the python client
  /// creates the source or when state is loaded or on undo/redo. 
  void sourceCreated(pqPipelineSource*);

  /// Fired on successful completion of createFilter().
  /// Remember that this signal is fired only when the creation of the object
  /// is requested by the GUI. It wont be triggered when the python client
  /// creates the source or when state is loaded or on undo/redo. 
  void filterCreated(pqPipelineSource*);

  /// Fired on successful completion of createReader().
  /// Remember that this signal is fired only when the creation of the object
  /// is requested by the GUI. It wont be triggered when the python client
  /// creates the source or when state is loaded or on undo/redo. 
  void readerCreated(pqPipelineSource*, const QString& filename);
  void readerCreated(pqPipelineSource*, const QStringList& filename);

  /// Fired on successful completion of createView().
  /// Remember that this signal is fired only when the creation of the object
  /// is requested by the GUI. It wont be triggered when the python client
  /// creates the source or when state is loaded or on undo/redo. 
  void viewCreated(pqView*);

  /// Fired on successful completion of createDataRepresentation().
  /// Remember that this signal is fired only when the creation of the object
  /// is requested by the GUI. It wont be triggered when the python client
  /// creates the source or when state is loaded or on undo/redo. 
  void dataRepresentationCreated(pqDataRepresentation*);

  /// Fired on successful completion of createScalarBarDisplay().
  /// Remember that this signal is fired only when the creation of the object
  /// is requested by the GUI. It wont be triggered when the python client
  /// creates the source or when state is loaded or on undo/redo. 
  void scalarBarDisplayCreated(pqScalarBarRepresentation*);

  /// Fired on successful completion of any method that creates a pqProxy
  /// or subclass including createScalarBarDisplay, createDataRepresentation,
  /// createView, createFilter, createSource,
  /// createReader etc.
  void proxyCreated(pqProxy*);

  /// Fired on successful completion of createProxy().
  /// Remember that this signal is fired only when the creation of the object
  /// is requested by the GUI. It wont be triggered when the python client
  /// creates the source or when state is loaded or on undo/redo. 
  void proxyCreated(vtkSMProxy*);

  /// Fired when destroy(pqView*) is called. 
  /// This signal is fired before the process for destruction of the object 
  /// begins. Remember that this signal is fired only when the destruction of 
  /// the object is requested by the GUI. It wont be triggered when the python 
  /// client unregisters the source or when state is loaded or on undo/redo. 
  void destroying(pqView* view);
 
  /// Fired when destroy(pqRepresentation*) is called. 
  /// This signal is fired before the process for destruction of the object 
  /// begins. Remember that this signal is fired only when the destruction of 
  /// the object is requested by the GUI. It wont be triggered when the python 
  /// client unregisters the source or when state is loaded or on undo/redo. 
  void destroying(pqRepresentation* display);

  /// Fired when destroy(pqPipelineSource*) is called. 
  /// This signal is fired before the process for destruction of the object 
  /// begins. Remember that this signal is fired only when the destruction of 
  /// the object is requested by the GUI. It wont be triggered when the python 
  /// client unregisters the source or when state is loaded or on undo/redo. 
  void destroying(pqPipelineSource* source);

  /// Fired when destroy(pqProxy*) is called. 
  /// This signal is fired before the process for destruction of the object 
  /// begins. Remember that this signal is fired only when the destruction of 
  /// the object is requested by the GUI. It wont be triggered when the python 
  /// client unregisters the source or when state is loaded or on undo/redo. 
  void destroying(pqProxy* proxy);

protected:
  /// Create a proxy of the given type. If reg_name=QString(),
  /// a new name will be assigned to it.
  virtual vtkSMProxy* createProxyInternal(const QString& sm_group, 
    const QString& sm_name, pqServer* server, 
    const QString& reg_group, const QString& reg_name=QString());

  /// Unregisters a proxy.
  virtual void destroyProxyInternal(pqProxy* proxy);

  /// Called after a data representation to created. 
  /// This use the <InheritRepresentationProperties /> hints to inherit
  /// properties from input representation is possible.
  virtual void initializeInheritedProperties(pqDataRepresentation* repr);

  /// Used to create names for registering proxies.
  pqNameCount* NameGenerator;

private:
  pqObjectBuilder(const pqObjectBuilder&); // Not implemented.
  void operator=(const pqObjectBuilder&); // Not implemented.
};

#endif


