| 17 | | 1 First of all, there is an action class called !MoleculeTranslateAction defined in [source:src/Actions/MoleculeAction/TranslateAction.cpp]. It has a unique(!) '''NAME'''. |
| 18 | | |
| 19 | | 1 Furthermore, all actions are instantiated in the so-called !MapOfActions::populateActions() [source:src/Actions/MapOfActions.cpp], also the !MoleculeTranslateAction(). Thereby, its '''NAME''' and the pointer to its instance is placed in an !ActionRegistry [source:src/Actions/ActionRegistry.cpp], which is a singleton, can be called from anywhere and asked for the instance of a specific action when knowing its name. In this registry the instantiated actions are simply sitting there and waiting to be called forth to do something. |
| | 17 | I will break it down into three steps: |
| | 18 | 1. Parsing the input file |
| | 19 | 1. Doing the translation |
| | 20 | 1. Storing updated coordinates to file |
| 23 | | 1 See the main() function in [source:src/builder.cpp] for an overview what has happened so far and happens now: The !CommandLineParser was set, it has parsed all command line arguments and has also noted down their specific ordering on the command line in !CommandLineParser::!SequenceOfActions. Now, the !MainWindow is called. This is the central instance of any user interface (whether textmenu, commandline or graphical) to wait for user interaction. |
| | 24 | 1. What happens exactly here, i.e. how the command line argument ''-i test.conf'' is parsed, is explained further below with the translation action. Here, we will emphasize on the parsers for transfering information about molecular systems from the hard drive into the memory. |
| | 25 | 2. For this purpose there is a [source:src/Parser/FormatParser.hpp FormatParser] and a [source:src/Parser/ChangeTracker.hpp ChangeTracker] class. The latter is just an observer of the [source:src/World.hpp World], noting when something changes, i.e. an atom changes position or its element. Note that the World is the single most important class, containing all atoms, all molecules. !FormatParser is a general class to be derived from, i.e. it has virtual functions load() and save() that have to be written in the specializations such as [source:src/Parser/XyzParser.cpp XyzParser] or [source:src/Parser/XyzParser.cpp TremoloParser]. For each format specification there is such specialization of this !FormatParser. Note that not every change in the World is instantly written, just a variable is set noting that something has changed. |
| | 26 | 3. Now, by the file suffix we recognize its format (".conf" means pcp format, i.e. [source:src/Parser/PcpParser.cpp PcpParser]). Then, this parser is instantiated with the [source:src/Parser/FormatParserStorage.hpp FormatParserStorage] which is simply a container for all instantiated parsers and handles that all output files consist of the same filename only with different suffixes. And the parser's load function will extract the atoms, coordinates and elements, out of the input stream and put them into the World. |
| 27 | | 1 In MoleculeTranslateAction::performCall() [source:src/Actions/MoleculeAction/TranslateAction.cpp] you notice that first a dialog is constructed and then its display() function is called. This will wait for user interaction and return with a success-or-not statement. If the user input has been complete (success), we proceed and translate the molecule. For this translation action the following information is necessary: The molecule to translate, the vector to translate by and a statement whether periodic boundary conditions shall be adhered. |
| | 30 | 1. Now, there is an action class called [source:src/Actions/MoleculeAction/TranslateAction.cpp MoleculeTranslateAction]. It has a unique(!) '''NAME'''. An Action is nothing but a class containing some data and a performCall() member function wherein the specific doing of the action is coded. |
| | 31 | 1. All actions are instantiated in the so-called !MapOfActions by its member function [source:src/Actions/MapOfActions.cpp populateActions()], hence also the !MoleculeTranslateAction(). Thereby, its '''NAME''' and the pointer to its instance is placed in an [source:src/Actions/ActionRegistry.cpp ActionRegistry], which is a singleton, can be called from anywhere and asked for the instance of a specific action when knowing its name. In this registry the instantiated actions are simply sitting there and waiting to be called forth to do something. |
| | 32 | 1. Moreover, the !MapOfActions has lists about which Action belongs to which menu, a short description, what the short form for the command-option is (the long form is always --NAME), what type its parameter has (if any) and also default values (also if any). This information is used by the [source:src/CommandLineParser.cpp CommandLineParser] to fill in the [[http://www.boost.org/doc/libs/1_43_0/doc/html/program_options.html boost::program_options]] with the necessary details to parse all command line arguments into a map for later retrieval. |
| | 33 | 1. See the [source:src/builder.cpp main() function] for an overview what has happened so far and happens now: The !CommandLineParser was set, it has parsed all command line arguments and has also noted down their specific ordering on the command line in CommandLineParser::!SequenceOfActions. Now, the !MainWindow is called. This is the central instance of any user interface (whether textmenu, commandline or graphical) to wait for user interaction. |
| | 34 | 1. In the [source:src/UIElements/CommandLineUI/CommandLineWindow.cpp CommandLineUI variant of the MainWindow] in the function display(), we go through this !SequenceOfActions. All actions are asked from the repository. If not present, we assume that is not an action but an additonal argument (such as --input or -i above). If it is present, the action is called forth to do the user's bidding. |
| | 35 | 1. In [source:src/Actions/MoleculeAction/TranslateAction.cpp MoleculeTranslateAction::performCall()] you notice that first a dialog is constructed and then its display() function is called. This will wait for user interaction and return with a success-or-not statement. If the user input has been complete (success), we proceed and translate the molecule. For this translation action the following information is necessary: The molecule to translate, the vector to translate by and a statement whether periodic boundary conditions shall be adhered. |
| | 36 | 1. These dialogs and their queries are bit more difficult. Each UIFactory variant has its own queries. In case of the text menu, the user is asked on the console for the specific set of values, in the graphical interface a window pops up with boxes to enter the values. However, on the commandline these values have to be fed in already by the knowledgable user: In our case the parameter to our (-t) command line argument, i.e. to our action is the vector. Hence, the dialog receives the action's '''NAME''' as reference, whereas for the molecule and the periodicity statement we give the names of options that are defined in !MapOfActions. Note that periodicity has a default value of ''0'' and thus may be omitted. |
| | 37 | 1. These references are necessary for the queries. As in our command line case the queries themselves will turn to !CommandLineParser and ask its parsed map of command line arguments for the value belonging to this reference. I.e. for "molecule-by-id" [source:src/CommandLineParser.hpp CommandLineParser::vm], contains ''0'' |
| | 38 | 1. With the complete information we call upon [source:src/molecule_geometry.cpp molecule::Translate()] or [source:src/molecule_geometry.cpp molecule::TranslatePeriodically()] for the molecule instance obtained via the query. |
| 35 | | 1 At the end of the main function, a !FormatParserStorage [source:src/Parser/FormatParseStorage.cpp] is called which will create the output streams for all desired formats and !ChangeTracker will tell the specific !FormatParsers to write the updated information from the World [source:src/World.hpp] to file. |
| | 46 | |
| | 47 | And that's it. |
| | 48 | |
| | 49 | It might sound complicated but here is a break-down of what is actually needed to create a new action: |
| | 50 | * write a new class that inherits from Action as in !MoleculeTranslateAction |
| | 51 | * give it a decent '''NAME''' |
| | 52 | * add this '''NAME''' along with information about short form, placing in menu, type of parameter into the maps of !MapOfActions and insert it also into the generic map. |
| | 53 | * if it needs more than one option, check whether appropriatly called options are already in place in the !MapOfActions. If not, add your own along type and description information. |
| | 54 | |
| | 55 | And that's all. |
