Changes between Version 4 and Version 5 of ExampleSpatialTranslation

Timestamp:

Oct 14, 2010, 10:22:45 AM (14 years ago)

Author:

FrederikHeber

Comment:

As the dialogs are now hidden inside macro implementation, we changed the description of the action slightly. Also the Box class is used to wrap and finally undo/redo and selection added.

ExampleSpatialTranslation

@@ -7 +7 @@
 The following will start molecuilder with the [source:src/UIElements/CommandLineUIUIFactory.hpp CommandLineUI] as the [source:src/UIElements/UIFactory.hpp UIFactory]
 {{{
-molecuilder -i test.conf --molecule-by-id 0 -t "2,0,0" 
+molecuilder -i test.conf --select-atom-by-id 0 -t "2,0,0" 
 }}}
-It will parse the molecular system found in the pcp config file ''test.conf'' and translate it by (2,0,0), i.e. by 2 angstroem in the x direction, and save the file on exit.
+It will parse the molecular system found in the pcp config file ''test.conf'' and translate atom with id 0 by (2,0,0), i.e. by 2 angstroem in the x direction, and save the file on exit.
 
 But what happens exactly, behind the scenes inside molecuilder?
@@ -26 +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.
 
+=== Selecting the atom ===
+
+ 1. As a matter of fact selecting the atom is an action all by itself, see [source:src/Action/SelectionAction/AtomByIdAction.cpp].The World class offers specifics storages for [source:src/World.hpp selectedAtoms] and [source:src/World.hpp selectedMolecules] in order to select a specific subset of atoms. The World class offers various methods to select and unselect which are simply projected onto actions.
+
 === Doing the translation ===
 
@@ -33 +37 @@
  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.
  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.
- 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.
- 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.
- 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''
- 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.
+ 1. In [source:src/Actions/MoleculeAction/TranslateAction.cpp MoleculeTranslateAction::performCall()] you notice that first a "macrofied" function [[source:src/Actions/Action_impl_pre.hpp getParametersfromValueStorage()] is called. The construction of dialogs and querying information necessary for the execution of the action has been hidden inside macros such that the actual implementation really only deals with the perform...() functions. This single call fills a parameter structure, basically defined in [source:src/Actions/MoleculeAction/TranslateAction.def] and residing inside the Action class from user input. Afterwards, we may proceed and simply translate the selected atoms. For this translation action the following information is necessary: The atoms to translate, the vector to translate by and a statement whether periodic boundary conditions shall be adhered.
+ 1. These dialogs and their queries hidden inside the macro 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 command line 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 a 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.
+ 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 "select-atom-by-id" [source:src/CommandLineParser.hpp CommandLineParser::vm], which contains ''0''.
+ 1. With the complete information we simply add the desired vector onto the position of each selected atom. Afterwards, if periodic boundary conditions are enforced, we call upon [source:src/box.cpp Box::WrapPeriodically()] for the periodic correction of the whole system.
+ 1. Finally, we return an !ActionState which contains all the selected atoms that have been translated to allow for undoing of the action.
 
+=== Undoing and Redoing ===
+
+ 1. Within the additional functions performUndo() and performRedo() we specify how to undo and redo said translation. 
+ 1. For a translation this is very simple: We simply negate the vector and perform the same operation again. However, we pick the atoms to translate from the stored state.
+ 1. Redoing is the same as undoing only without negating the vector.
 
 === Storing update info to file ===