Changes in / [bdb143:13892b]

Location:

src

Files:

• CommandLineParser.hpp (modified) (1 diff)
• UIElements/CommandLineUI/CommandLineUIFactory.hpp (modified) (1 diff)
• UIElements/Dialog.hpp (modified) (1 diff)
• UIElements/UIFactory.hpp (modified) (1 diff)

src/CommandLineParser.hpp

@@ -17 +17 @@
 #include <list>
 
+/** This class is a wrapper for boost::program_options.
+ *
+ * <h1> CommandLine Howto </h1>
+ * <h2> Introduction </h2>
+ *
+ * The UIFactory is a base class for the User Interaction. There are three UI specializations:
+ * Text, GUI and CommandLine. Accessing functionality via the CommandLine UI is explained here.
+ *
+ * First, an Action has to be written for the specific functionality. This Action should
+ * be added in Actions/...Action in the respective subdirectory of the following types:
+ *  -# Analysis: Analysis actions like evaluating pair correlation, bonds, ...
+ *  -# Atom: adding, removing, manipulating atoms
+ *  -# Cmd: specifying data bases, verbosity, ...
+ *  -# Fragmentation: fragmenting a system, performing graph analysis, ...
+ *  -# Molecule: adding, removing, manipulating molecules
+ *  -# Parser: Parsing files (loading, saving)
+ *  -# Tesselation: obtaining (non)convex surface of a molecule, embedding, ...
+ *  -# World: Setting Box dimensions, default name of new molecules, ...
+ *
+ *  The CommandLineUIFactory is a specialization of the UIFactory for parsing command
+ *  line parameters, generating and executing actions there from.
+ *
+ *  The idea of the CommandLineFactory is explained elsewhere, here we would like to give a
+ *  receipe for creating new actions.
+ *
+ * <h3>Introducing new actions</h3>
+ *
+ * Let us now introduce what to do if a new action is to be implemented. Here, we use the
+ * CommandLineVersionAction as an example.
+ * This consists if basically three parts:
+ * 1. Create the files, write the classes and make them compilable
+ *   - Create new source and header files in one of the above subfolders in the Actions folder,
+ *     e.g. create VersionAction.cpp and VersionAction.hpp in Actions/Cmd/
+ *   - Give it a sensible class name, the convention is <type><what it does>Action,
+ *     where <type> is basically the naming (written out) of the subdirectory,
+ *     e.g. class CommandLineVersionAction.
+ *   - Add the source and header file to the respective variables in molecuilder/src/Makefile.am,
+ *     e.g. if you add a Cmd action the variables are CMDACTIONSOURCE and CMDACTIONHEADER,
+ *     such that they get compiled.
+ * 2. Add an instance to the CommandLineUIFactory, such that they are known to the UI.
+ *   - Add the header file as an include to UIElements/CommandLineWindow.cpp, e.g.
+ *     #include "Actions/Cmd/VersionAction.hpp"
+ *   - Add an instance of your class to the specific populater-function in
+ *     UIElements/CommandLineWindow.cpp, e.g. for the above Cmd action, add to populateCmdActions()
+ *     add new CommandLineVersionAction().
+ *     This will automatically register in the ActionRegistry.
+ * 3. Give them an option name, short hand an description, such that they can be referenced from
+ *    the command line.
+ *   - think of a new key name, e.g. "version", which is the long form of the command parameter,
+ *     i.e. --version).
+ *   - add this key to every map of MapofActions, i.e. to
+ *     - MapofActions::DescriptionMap: the description which appears as help and tooltip
+ *     - MapofActions::ShortFormMap: the short form of the command parameter (e.g. -v)
+ *     - MapofActions::ValueMap: the value the command parameter has (do not create if it does not need one)
+ *   - If your action requires additional parameters, these need to be added in the same manner as in
+ *     the list item above.
+ *
+ *  Don't forget to write the actual code. :)
+ *
+ * <h3>Writing an action</h3>
+ *
+ *  As you write a new action you may think in terms of the command line, i.e. you want to use this
+ *  new functionality you add by calling molecuilder as: ./molecuilder --super-action foobar.txt, where
+ *  the key of your new action would be "super-action". While this is fine, keep in mind, that your action
+ *  should be useable for the other UI specializations as well, i.e. from the menu and the GUI. Therefore,
+ *  -# Don't use cin to ask the user for input: Use Query...()!
+ *  -# Rather don't use cout/cerrs, but either give Log() or eLog() or use QueryEmpty() if you want to give
+ *     the user specific information what you ask of him.
+ *
+ */
 class CommandLineParser : public Singleton<CommandLineParser> {
   friend class Singleton<CommandLineParser>;

src/UIElements/CommandLineUI/CommandLineUIFactory.hpp

@@ -11 +11 @@
 #include "UIFactory.hpp"
 
+/** This class is a specialization of the UIFactory.
+ *
+ * <h2> Introduction </h2>
+ *
+ * The UIFactory is a base class for the User Interaction. There are three UI specializations:
+ * Text, GUI and CommandLine.
+ *
+ * The idea of the command line part is as follows:
+ *
+ * All actions that can be called from the command line are instantiated via populater-functions.
+ * In the constructor of an action it is automatically registered with the ActionRegistry and can
+ * henceforth be looked up there.
+ *
+ * There is a CommandLineParser which parses the command line parameters and puts all found values
+ * into a map. Then, MainWindow::Display of the CommandLineUIFactory is called, which goes through
+ * every action (by the ActionRegistry) and looks through the parsed commands whether the action is
+ * desired.
+ *
+ * In the action itself, Query's ask for user input. In the CommandLine case, we don't want direct
+ * user interaction, but the user has to have those values already delivered along with the desired
+ * action. Hence, the Query implementations just look up the desired values in the CommandLineParser
+ * vaults. When they are not found, an exception is thrown. When all are found, the action is performed.
+ *
+ */
 class CommandLineUIFactory : public UIFactory
 {

src/UIElements/Dialog.hpp

@@ -18 +18 @@
 class Vector;
 
+
+/** 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.
+ */
 class Dialog
 {

src/UIElements/UIFactory.hpp

@@ -25 +25 @@
  * only create UIelements of that certain type, so that all UIElements match. This way different
  * UIs can be handled in a concise abstract way.
+ *
+ * The main functionality is the MainWindow and the Dialog.
+ *
+ * MainWindow basically is the framework if the UI. The MainWindow has a run function which is
+ * called MainWindow::Display(), which will listen for user input and react to it via actions for
+ * as long as the user desires or tells the MainWindow to quit.
+ *
+ * Within the MainWindow Dialog classes may be instantiated which ask the user for input to
+ * certain actions he wants to perform.
+ *
  */
 class UIFactory : public Singleton<UIFactory,false>