doc/gui.txt

   1 *****************
   2 The GUI interface
   3 *****************
   4
   5 Orignially by Rolf Schmidt <rschmidt@alcor.concordia.ca>.
   6
   7 Run the GUI with::
   8
   9     $ ./bin/hk.py --ui gui
  10
  11 Alternatively, select `gui` in your config file (see :doc:`config`)::
  12
  13     [user interfaces]
  14     command line = False
  15     gui = True
  16
  17 Interface
  18 =========
  19 Starting Hooke's GUI for the first time, you will see the central plot
  20 area with the current plot surrounded by the following windows (the `F*`
  21 key toggles the visibility of the panel):
  22
  23 * Commands (`F5`)
  24 * Folders (`F6`)
  25 * Note (`F7`)
  26 * Output (`F8`)
  27 * Playlists (`F9`)
  28 * Properties (`F10`)
  29
  30 .. image:: img/gui_screenshot.jpg
  31
  32 Initially, the window will be rather small in order to work with small
  33 screen resolutions.  Adjust the size and position to your liking.
  34
  35 Underneath the menus at thte top of the window there is a navigation
  36 toolbar to switch from one curve to another (next/previous).
  37
  38 Plot area
  39 =========
  40
  41 The plot area displays the current curve.  You can select the data
  42 column to use as the x axis using the dropdown menu in the plot
  43 navigation bar (under the plot, not to be confused with the navigation
  44 bar under the menus).  You can select the columns to plot by clicking
  45 the `y column(s)` button and checking interesting columns.  We suggest
  46 you stick to columns with a single unit, and not try and dispay, for
  47 example, both meters and newtons on the same y axis.
  48
  49 You can move about the plot using its navigation toolbar.  See the
  50 `Matplotlib manual`_ for details.
  51
  52 .. _Matplotlib manual:
  53   http://matplotlib.sourceforge.net/users/navigation_toolbar.html
  54
  55 You can measure distances and forces directly in the plot.  If you
  56 want to know the coordinates of a single point, left click on it.  The
  57 index and coordinates of the nearest data point will be displayed in
  58 the status bar along with the x and y coordinates of your click.
  59
  60 To find the distance between two points, just issue the command
  61 ``delta``.  You will be asked to click two points.  When you click a
  62 point, a blue dot should appear.  When you click the second point, the
  63 distances will appear in the output panel.  Hooke automatically
  64 adjusts the position of the clicked point to the nearest point in the
  65 graph, so you will be always measuring distances and forces between
  66 points in the graph.
  67
  68 .. todo:: Implement blue dots and click handler.
  69
  70 Folders
  71 =======
  72 Here you can navigate your file system and double click on a saved
  73 playlist to open it.  You can change the initial folder by modifying
  74 `workdir` in the `preferences` (core plugin).
  75
  76 .. todo:: Implement folders panel.
  77
  78 Playlists
  79 =========
  80 You can manage several playlists in this window.  As the GUI is rather
  81 flexible, it is possible to display the curves from different
  82 playlists side by side to compare them (relatively handy when
  83 comparing different fit parameters).  You can double-click a file in
  84 the playlist to display it in the plot area.  Deleting entire playlists
  85 or single files can be accomplished by right-clicking and selecting
  86 `Delete`.
  87
  88 .. todo:: Do we need side-by-side comparison?  How did this work in
  89   the old GUI?
  90
  91 Commands
  92 ========
  93 All available commands are listed under their corresponding plugin.
  94 In order to see a plugin and its commands, you have to edit
  95 :file:`hooke.conf` and enable th plugin in the plugins section.
  96 Selecting a plugin or command will display the associated properties
  97 in the `Properties`_ window.  You can edit the properties and click
  98 `Execute` to run the selected command.  If you do not need to modify
  99 any properties, you can also double-click a command to run it.
 100
 101 Mousing over a plugin or command in the `Commands`_ window will
 102 display the associated help in a tooltip.  The help for the plugin
 103 should give a general description of the plugin.  The help for a
 104 command should describe the properties available for this command and
 105 suggest reasonable default values if possible.  Feel free to point out
 106 missing help content.
 107
 108 Properties
 109 ==========
 110 The properties for the command selected in the `Commands`_ window are
 111 displayed here.  Edit the properties to your satisfaction (some need to
 112 be confirmed by hitting enter, this seems to be a problem in
 113 wxPropertyGrid) and click the `Execute` button to run the selected
 114 command.  Floating point values are limited to a certain number of
 115 decimals (limitation of wxPropertyGrid?) so be careful when using
 116 floating point values.
 117
 118 .. todo:: Document new, non-PropGrid
 119   :mod:`~hooke.ui.gui.panel.propertyeditor`.
 120
 121 Output
 122 ======
 123 The Output window serves as a log where pertinent information is
 124 displayed.  The output is generally the same as what you would see if
 125 you were running the commands from the command line.
 126
 127 Note
 128 ====
 129 A note can be added to every curve: enter your note and click `Update
 130 note`.  With the `note filter playlist` command (`playlist` plugin)
 131 you can copy all the curves with a note into a new playlist.
 132
 133 General remarks
 134 ===============
 135 Read :doc:`hacking` for an overview of how Hooke works internally and
 136 :doc:`config` for more information about configuring Hooke.
 137
 138 Ignore the text on the `Welcome` tab.  This tab is more like a proof of
 139 principle and will contain a short how-to in the future (once the
 140 howto is written).
 141
 142 Hooke's GUI will remember the size and position of the main window
 143 (stored in the config file, see :doc:`config`).  You can arrange the
 144 panels any which way you like and save this arrangement as a
 145 perspective.
 146
 147 .. image:: img/gui_perspective.jpg
 148
 149 Hooke will always start with the last used perspective and you can
 150 switch from one perspective to another by selecting a perspective from
 151 the perspectives menu.  After deleting a perspective, the radio
 152 indicator in the perspectives menu disappears (known bug in
 153 wxPython).  This is only a visual problem and does not affect anything
 154 else.
 155
 156 In order to pan the plot, zoom in and out and export the plot of your
 157 force curves, use the plot toolbar under the plot.  A more detailed
 158 description is available on the `Matplotlib website`_
 159
 160 .. _Matplotlib website:
 161   http://matplotlib.sourceforge.net/users/navigation_toolbar.html
 162
 163 Some plugins and commands
 164 =========================
 165
 166 * overlay (export): exports all retraction curves in a playlist on the
 167   same scale.  This is achieved by determining the maximum x window and
 168   adding x(max) and x(min) to all curves that are shorter than the
 169   maximum x window.  Make sure to filter your playlist before running
 170   this command!
 171
 172 .. todo:: Implement overlay.
 173
 174 Basic analysis and autopeak
 175 ===========================
 176
 177 .. todo:: Implement autopeak.  Bring in autopeak tutorial from the wiki?
 178
 179 Please follow the steps in the :doc:`tutorial`.  Instead of typing in
 180 the command at the command-line, select it in the `Commands`_ window,
 181 set your properties in the `Properties`_ window and click on
 182 `Execute` back in the `Commands`_ window.
 183
 184 The :doc:`autopeak` tutorial is also applicable.  You need to setup the
 185 type of fit you want to use: in the Properties of the autopeak command
 186 (autopeak plugin) select `WLC`, `FJC` or `FJC_PEG` from the dropdown
 187 list for the `polymer model` argument of `polymer fit`.
 188
 189 Fast curve reviewing and saving
 190 ===============================
 191 .. todo:: Update curve review tutorial section.
 192
 193 When automatic routines are not good enough to filter your data, use
 194 ``review`` command to cycle through your playlist presenting ten
 195 curves in the same graph.  You can then enter the numbers of the
 196 interesting curves and automatically save a copy of them into another
 197 directory.