Changes in src/UIElements/Dialog.hpp [4cf323d:e4afb4]

File:

• src/UIElements/Dialog.hpp (modified) (5 diffs)

src/UIElements/Dialog.hpp

@@ -33 +33 @@
  * 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 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.
+ *
  */
 class Dialog
@@ -210 +314 @@
     virtual void setResult();
   protected:
-    molecule *tmp;
+    const molecule *tmp;
   };
 
@@ -220 +324 @@
     virtual void setResult();
   protected:
-    molecule * temp;
-    std::vector<molecule *> tmp;
+    const molecule * temp;
+    std::vector<const molecule *> tmp;
   };
 
@@ -231 +335 @@
     virtual void setResult();
   protected:
-    atom *tmp;
+    const atom *tmp;
   };
 
@@ -241 +345 @@
     virtual void setResult();
   protected:
-    atom *temp;
-    std::vector<atom *> tmp;
+    const atom *temp;
+    std::vector<const atom *> tmp;
   };