source: src/UIElements/Dialog.hpp@ 25e18e7

/*
 * Dialog.hpp
 *
 *  Created on: Jan 5, 2010
 *      Author: crueger
 */

#ifndef DIALOG_HPP_
#define DIALOG_HPP_

// include config.h
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif


#include<string>
#include<list>
#include<vector>

#include <boost/filesystem.hpp>
#include "LinearAlgebra/RealSpaceMatrix.hpp"
#include "LinearAlgebra/Vector.hpp"
#include "RandomNumbers/RandomNumberDistribution_Parameters.hpp"
#include "Parameters/Parameter.hpp"

class atom;
class RealSpaceMatrix;
class element;
class molecule;


/** Dialog is one of the two main classes of the UIFactory base class.
 *
 * The Dialog is meant for asking the user for information needed to perform
 * actions he desires, such as asking for a position in space or a length.
 *
 * For this purpose there is the base class Query and numerous specializations
 * for each of the types to be asked. There are primitives integer, doubles and
 * string, but also advanced types such as element, molecule or Vector. There
 * is also an empty query for displaying text.
 *
 * Note that the templatization of Dialog::query() allows for easy implementation
 * of new types that correspond to/are derived from old ones.
 *
 * <H3>How do Dialogs operate?</H3>
 *
 * Dialogs are initiated by Action::FillDialog() function calls. Within Action::Call()
 * a dialog is created and passed on to FillDialog(), which is specialized in each
 * specific Action to ask for the specific parameter it needs.
 *
 * Dialogs are derived for each of the UI types
 *  -# CommandLineDialog
 *  -# QtDialog
 *  -# TextDialog
 *
 * This "asking" for parameters is done via the Query class.  There are four types
 * of Query types:
 *  -# Query, members in class Dialog
 *  -# CommandLineQuery, members in class CommandLineDialog
 *  -# QtQuery, members in class QtDialog
 *  -# TextQuery, members in class TextDialog
 * Each embodies a certain way of asking the user for the specific type of parameter
 * needed, e.g. a file via the TextMenu interface would be done in member functions of
 * TextDialog::FileTextQuery.
 *
 *
 * Generally, the sequence of events is as follows:
 *  -# Action::fillDialog() calls upon Dialog::query<T> for some type T, let's say T
 *     stands for double
 *  -# Dialog::query<double> call a function queryDouble()
 *  -# depending on the currently used UIFactory, the Dialog above is actually either
 *     of the three specialized types, let's say CommandLine. And we see that within
 *     CommandLineDialog we have the respective method ueryDouble() that registers
 *     a new instance of the class CommandLineDialog::DoubleCommandLineQuery.
 *  -# The Query's are first registered, as multiple parameters may be needed for
 *     a single Action and we don't want the popping up of a dialog window for each
 *     alone. Rather, we want to merge the Query's into a single Dialog. Therefore,
 *     they are first registered and then executed in sequence. This is done in
 *     Dialog::display(), i.e. when the dialog is finally shown to the user.
 *  -# Then each of the registered Query's, here our CommandLineDialog::
 *     DoubleCommandLineQuery, constructor is called.
 *     -# This will call the constructor of its base class, where the actual value
 *        is stored and later stored into the ValueStorage class by
 *        Dialog::Query::setResult().
 *     -# Also, e.g. for the Qt interface, the buttons, labels and so forth are
 *        created and added to the dialog.
 *  -# Now the users enters information for each UI something different happens:
 *    -# CommandLine: The actual value retrieval is done by the CommandLineParser and
 *       the boost::program_options library, the value is stored therein for the moment.
 *       (see here: http://www.boost.org/doc/libs/1_44_0/doc/html/program_options/)
 *    -# TextMenu: The value is requested via std::cin from the user.
 *    -# QtMenu: The users enters the value in a Dialog. Due to Qt necessities a
 *       Pipe class obtains the value from the Dialog with Qt's signal/slot mechanism
 *       and put it into Dialog::...Query value.
 *  -# in our case DoubleCommandLineQuery::handle() will be called. The value is
 *     retrieved and put into Dialog::DoubleQuery::tmp
 *  -# Finally, for each Query, also Dialog::DoubleQuery, setResult() is called which
 *     puts the value as a string into the ValueStorage under a given token that is
 *     associated with a type (and thereby we assure type-safety).
 *
 * <H3>Regarding derived types of types with already present queries</H3>
 *
 * Example: We have got a derived Vector class, called BoxVector, that is by any means
 * a Vector but with one difference: it is always bound to lie within the current domain.
 * With regards to type-casting it to and from a string however, nothing is different
 * between Vector and BoxVector.
 *
 * So, do we need a new Query for this?
 * No.
 *
 * We just have to do this:
 *  -# add a specialization of Dialog::query<BoxVector> where queryVector()is used.
 *     @code
 *     template <> void Dialog::query<BoxVector>(const char *token, std::string description) {
 *        queryVector(token, false, description);
 *     }
 *     @endcode
 *  -# make sure that
 *     -# ValueStorage::setCurrentValue() the specialization for class Vector has an
 *     if case also for BoxVector and does something appropriate.
 *     -# ValueStorage::queryCurrentValue() has another specialization doing the same
 *     as for Vector but for BoxVector in its signature.
 *
 * And that's all.
 *
 *
 * <H3>Adding new queries</H3>
 *
 * Check first whether you really need a new query or whether we can derive it and re-use
 * one of the present ones.
 *
 * Due to the three present UI interfaces we have to add a specific Query for each, here
 * is a list:
 *   -# add ValueStorage::setCurrentValue() and ValueStorage::queryCurrentValue() for
 *      both types
 *   -# add Dialog::query...()
 *   -# add Dialog::query<>() specialization calling the above function
 *   -# add CommandLineDialog::query...(), TextDialog::query...(), and QtDialog::query...(),
 *      i.e. for each of the three interface
 *   -# add empty definition DummyDialog::query...() to the stub for Action unittests in DummUI.hpp.
 *   -# add Dialog::...Query class with tmp value of desired type
 *   -# add CommandLineDialog::...Query, TextDialog::...Query, QtDialog::...Query
 *   -# you probably also need a QtDialog::...QueryPipe() to handle the signal/slot stuff,
 *      Qt's moc does not like nested classes. Hence, this has to go extra.
 *   -# TypeEnumContainer add new type to query
 *   -# CommandLineParser::AddOptionToParser() add new type to query
 *   -# CommandLineParser_valdiates.[ch]pp: If given above as a new type
 *      program_options::value, define and implement a validate() function here.
 *
 */
class Dialog
{
public:
  Dialog();
  virtual ~Dialog();

  template <class T> void query(Parameter<T> &, const char *, std::string = "");

  virtual void queryEmpty(const char *, std::string = "")=0;
  virtual void queryBoolean(Parameter<bool> &, const char *, std::string = "")=0;
  virtual void queryInt(Parameter<int> &, const char *, std::string = "")=0;
  virtual void queryInts(Parameter<std::vector<int> > &, const char *, std::string = "")=0;
  virtual void queryUnsignedInt(Parameter<unsigned int> &, const char *, std::string = "")=0;
  virtual void queryUnsignedInts(Parameter<std::vector<unsigned int> > &, const char *, std::string = "")=0;
  virtual void queryDouble(Parameter<double> &, const char*, std::string = "")=0;
  virtual void queryDoubles(Parameter<std::vector<double> > &, const char*, std::string = "")=0;
  virtual void queryString(Parameter<std::string> &, const char*, std::string = "")=0;
  virtual void queryStrings(Parameter<std::vector<std::string> > &, const char*, std::string = "")=0;
  virtual void queryAtom(Parameter<const atom *> &, const char*,std::string = "")=0;
  virtual void queryAtoms(Parameter<std::vector<const atom *> > &, const char*,std::string = "")=0;
  virtual void queryMolecule(Parameter<const molecule *> &, const char*, std::string = "")=0;
  virtual void queryMolecules(Parameter<std::vector<const molecule *> > &, const char*, std::string = "")=0;
  virtual void queryVector(Parameter<Vector> &, const char*, std::string = "")=0;
  virtual void queryVectors(Parameter<std::vector<Vector> > &, const char*, std::string = "")=0;
  virtual void queryRealSpaceMatrix(Parameter<RealSpaceMatrix> &, const char*, std::string = "")=0;
  virtual void queryElement(Parameter<const element *> &, const char*, std::string = "")=0;
  virtual void queryElements(Parameter<std::vector<const element *> > &, const char*, std::string = "")=0;
  virtual void queryFile(Parameter<boost::filesystem::path> &, const char*, std::string = "")=0;
  virtual void queryFiles(Parameter< std::vector<boost::filesystem::path> > &, const char*, std::string = "")=0;
  virtual void queryRandomNumberDistribution_Parameters(Parameter<RandomNumberDistribution_Parameters> &, const char*, std::string = "")=0;

  virtual bool display();

  virtual void handleAll();
  virtual bool checkAll();
  virtual void setAll();

  virtual bool hasQueries();

  virtual void update(){}

public:
  // methodology for handling queries
  // all queries are stored and then performed at appropriate times

  //these queries can be handled by this dialog

  /** Base class for all queries.
   *
   * A query is request to the user for a value of a specific type.
   * E.g. All \ref Action's need parameters to perform a specific function.
   * These are obtained from the user at run-time via a Query regardless
   * of the interface that the user is using.
   *
   * A Query just has title and description and serves as the general interface
   * to queries. TQuery is a templatization of the Query containing a protected
   * member variable of the specific type and also a Parameter<> reference of
   * the type that actually belongs to the Action that triggered/created the
   * Query. handle() is UI-specific and sets the (temporary) member variable. 
   * However, isValid() in TQuery checks via the Parameter<> reference whether
   * the variable is valid with the given Validators and setResult() finally
   * set the Parameter with the temporary variable.
   *
   * For each type there is a derived class per \b UI, e.g. for the
   * \link userinterfaces-textmenu textmenu \endlink we have 
   * \ref BooleanTextQuery that derives from \ref TQuery<bool>. This derived
   * class has to implement the Query::handle() function that actually sets
   * the protected member variable to something the user has entered. 
   *
   * Thanks to the templated TQuery this is a as simple as it can get. The
   * handle() has to be UI-specific, hence has to be implemented once for
   * every present UI. But all other code can be used for either of them.
   *
   * \section query-howto How to add another query?
   *
   * Let's say  we want to query for a type called \a Value.
   *
   * Then, we do the following:
   *  -# add a virtual function queryValue inside class Dialog.
   *  -# now, for each of the GUIs we basically have to add a sub-class for the
   *     respective Query inside the derived Dialog that implements handle().
   *    -# QT: typically we use a onUpdate() function here attached the Qt
   *       signals and handle then just does nothing.
   *    -# CommandLine: nothing special, handle() imports value from \a
   *       CommandLineParser and sets the tmp variable.
   *    -# Text: nothing special, handle() queries the user and sets the tmp
   *       variable
   */
  class Query {
    friend class Dialog;
  public:
    Query(std::string _title, std::string _description = "");
    virtual ~Query();
    virtual bool handle()=0;
    virtual bool isValid()=0;
    virtual void setResult()=0;
  protected:
    const std::string getTitle() const;
    const std::string getDescription() const;
  private:
    std::string title;  //!< short title of the query
    std::string description; //!< longer description for tooltips or for help
  };


  template<class T>
  class TQuery : public Query {
  public:
    TQuery(Parameter<T> &_param, std::string title, std::string _description = "") :
      Query(title, _description), param(_param) {}
    virtual ~TQuery(){}
    virtual bool handle()=0;
    virtual bool isValid(){ return param.isValid(temp);  }
    virtual void setResult(){ param.set(temp);  }
  protected:
    T temp;
    Parameter<T> &param;
  };

  // Empty Query is just meant for showing text, such as version, help, initial message or alike
  class EmptyQuery : public Query {
  public:
    EmptyQuery(std::string title, std::string _description = "");
    virtual ~EmptyQuery();
    virtual bool handle()=0;
    virtual bool isValid(){ return true;  }
    virtual void setResult();
  };

void registerQuery(Query* query);

private:
  std::list<Query*> queries;

};


#endif /* DIALOG_HPP_ */