Added sphinx documentation for gui (attention contains binary images!)

git-svn-id: https://dng.biozentrum.unibas.ch/svn/openstructure/trunk@2415 5a81b35b-ba03-0410-adc8-b2c5c5119f08

modules/gui/doc/inspector_gadget.rst

+The Inspector Gadget
+================================================================================
+.. currentmodule:: ost.gui
+
+With our Inspector Gadget it is straightforward to modify rendering and coloring
+options of scene objects without using the keyboard:
+ 
+.. image:: images/100614_Inspector_gadget.png
+   
+The render and coloring options affect only the currently selected objects of
+the scene win. The Shortcut `Ctrl+I` toggles the visibility of the inspector.

modules/gui/doc/python_cpp.rst

+Mixing PyQt and C++ Widgets
+================================================================================
+.. currentmodule:: ost.gui
+
+PyQt4 is a set of python bindings for Qt4. The exposure from C++ to Python is 
+done with SIP, which has a different mechanism than boost::python.
+ 
+To access a exported boost::python Qt-Object from python we provide a method 
+which wraps the Object into a Python SIP Object.
+
+  .. code-block:: python
+   
+    seq_viewer = gui.SequenceViewer() # Create SequenceViewer Object
+    qobj = seq_viewer.qobject #Get Python SIP Object
+    print qobj.size()   # Call function on QWidget
+
+The other way around, each boost::python Qt Object accepts python objects as 
+input for Qt Objects. It handles the cast to a C++ Qt Object internally.
+
+  .. code-block:: python
+   
+    persp=gui.GostyApp.Instance().perspective
+    test=persp.GetMenu("Test") #Get boost::python qobject
+    test_action = QtGui.QAction('&Test me', test) #Create Python SIP Object 
+    test.addAction(test_action) #Add Action to boost::python object

modules/gui/doc/python_shell.rst

+The Python Shell
+================================================================================
+.. currentmodule:: ost.gui
+
+.. class:: PythonShell
+
+OpenStructure has a powerful Python Shell which has some handy features. It is 
+completely integrated into OpenStructure and allows you enter Python code. 
+
+Multi line detection
+--------------------------------------------------------------------------------
+The Python Shell detects automatically if a code block is complete or not. 
+For example a simple print statement in the command line is a complete code 
+block. Therefore the code will be executed after pressing enter:
+ 
+.. image:: images/100210_single_line.png
+
+When a multiline codeblock (like a for loop or an if instruction) is being 
+entered in the command line, the code is not executed until the code block is 
+complete:
+
+.. image:: images/100210_multi_line.png
+ 
+When a code block is not complete, pressing enter appends an empty line at the 
+end of the code block. To execute such a code block, you simply have to press 
+enter twice. 
+
+Auto completion
+--------------------------------------------------------------------------------
+After pressing tab in the Python Shell, it returns you possible extensions 
+to your entered text. This feature can be used for completing variable names 
+or functions:
+  
+.. image:: images/100210_auto_completion.png
+ 
+It is also possible to complete a file system path string. By pressing tab while
+editing a string, the shell displays all file or folders of the given 
+directory: 
+ 
+.. image:: images/100210_path_completion.png

modules/gui/doc/scene_win.rst

+Scene Window
+================================================================================
+.. currentmodule:: ost.gui
+
+The scene win holds a list of all graphical objects currently registered to
+the :class:`gfx.Scene`.
+
+.. image:: images/100208_Scene_Win.png
+
+Every node of the graphical scene tree is shown as a subnode of the scene. It 
+is possible to select one or more objects in the scenewin (`ctrl + <left mouse>`
+). The available actions of the context menu are applied to all currently 
+selected objects.
+
+.. class:: SceneWin
+
+  .. method:: GetContextMenu()
+  
+     Returns the :class:`ContextMenu`-instance.
+     
+    :rtype: ContextMenu
+
+  .. method:: GetQObject()
+
+    Get the SIP-QObject (QWidget), learn more about :doc:`python_cpp`.
+    
+    :rtype: PyQt4.QWidget
+
+  .. method:: Hide()
+  
+    Hide the Widget
+
+  .. method:: Show()
+
+    Shows the Widget
+    
+Context Menu
+--------------------------------------------------------------------------------
+
+The Context Menu of the Scene Window is context sensitive. So, dependent on what
+is selected in the :class:`SceneWin` the context menu changes.
+
+Context menu of an entity
+  .. image:: images/100614_entity_context_menu.png
+ 
+Context menu of an entity view
+  .. image:: images/100614_context_menu_view.png
+  
+It is possible to extend the Context Menu from python, by creating a QAction and 
+add it to the ContextMenu-Class. If you want to display the action only for 
+certain objects / states, you can pass flags which marks when the action should 
+be shown.
+
+  .. code-block:: python
+  
+    cm=gui.GostyApp.Instance().scene_win.GetContextMenu()
+    action = QtGui.QAction("Test single entity", cm.qobject)
+    cm.AddAction(action, gui.ContextActionType.ENTITY | gui.ContextActionType.SINGLE)
+
+.. class:: ContextMenu
+  
+  The ContextMenu is shown whenever the user presses `<right click>` on the :class:`SceneWin` 
+  
+  .. method:: AddAction(action, flags)
+  
+     Adds the given action to the context menu of the scene window. 
+
+     :param action: The Action which should be displayed in the context menu
+    
+     :type  action: :class:`QtCore.QAction`
+     
+     :param flags: Flags that indicates, when the context_menu should be active. The action 
+                   will be shown, when all flags are true.
+    
+     :type  flags: :data:`ContextActionTypes`
+
+
+  .. method:: GetQObject()
+
+    Get the SIP-QObject (QObject), learn more about :doc:`python_cpp`.
+    
+    :rtype: PyQt4.QObject
+
+    
+.. data:: ContextActionType
+ 
+  It is possible to specify flags for new :class:`ContextMenu` actions of the :class:`SceneWin`
+  These flags are used, to specify when the action should be shown on the scene window. The 
+  actions can be combined by `oring` them (|). When flags are combined with an `or`, the 
+  resulting object is a :data:`ContextActionTypes`-object.
+  The following flags are defined by default: 
+
+  * NOT_SCENE
+     All selected objects are not the root node  
+  * GFX_OBJECT
+     All selected objects are :class:`gfx.GfxObj`
+  * ENTITY
+      All selected objects are :class:`gfx.Entity`
+  * MAP
+      All selected objects are :class:`gfx.MapIso`
+  * ENTITY_VIEW
+      All selected objects are parts of the same Entity (either Queries or Views)
+  * CUSTOM_VIEW
+      All selected objects are named views (created by the user)  
+  * NOT_HIDDEN
+      All selected objects are visible (can not be combined with the ENTITY_VIEW flag)
+  * NOT_VISIBLE
+      All selected objects are hidden (can not be combined with the ENTITY_VIEW flag)
+  * SINGLE
+      There is only one selected object in the :class:`SceneWin`
+  * MULTI
+      There are multiple objects selected object in the :class:`SceneWin`
+   
+.. data:: ContextActionTypes
+
+  When multiple :data:`ContextActionType` objects are being combined with an or (|) you will get an 
+  :data:`ContextActionTypes`-Object.
+  
+  .. code-block:: python
+    
+    ctx_act_types = gui.ContextActionType.ENTITY | gui.ContextActionType.SINGLE
+
+  
+  
\ No newline at end of file

modules/gui/doc/sequence_viewer.rst

+The Sequence Viewer
+================================================================================
+.. currentmodule:: ost.gui
+
+The sequence viewer of OpenStructure can be used to display sequences or
+alignments.
+
+The following example adds an alignment to a sequence viewer and shows it in a 
+new sequence viewer instance:
+
+.. code-block:: python
+  
+  aln=io.LoadAlignment('sh2.aln')
+  v=gui.SequenceViewer()
+  v.AddAlignment(aln)
+  v.Show()
+
+Core Features
+--------------------------------------------------------------------------------
+
+Display styles
+^^^^^^^^^^^^^^
+It is possible to display the data in different ways. To change the display 
+style, click the tool icon of the menubar and select the 
+display style from the list.
+
+  .. image:: images/100615_select_display_style.png
+
+For the moment there are four different display styles:
+
+
+
+  **1. Highlight propteries**
+    
+    .. image:: images/100615_property_type.png
+       :width: 500pt
+    
+    Color groups of amino acids
+  
+    =====  ======  ======  =====  ===  ====  ====
+    grey   orange  yellow  green  red  blue  cyan
+    =====  ======  ======  =====  ===  ====  ====
+    G      F       C       S      K    D     P
+    A      Y       M       T      R    E      
+    V      W                      H    N      
+    L                                  Q      
+    I                                         
+    =====  ======  ======  =====  ===  ====  ====
+
+  
+  **2. Secondary structure**
+  
+    .. image:: images/100615_secondary_structure.png
+       :width: 500pt
+      
+    Display secondary structure information
+    
+    This mode is only available, when a :class:`mol.EntityView` is connected to 
+    the sequence.
+   
+  **3. Highlight conservation 1**
+  
+    .. image:: images/100615_conservation_1.png
+       :width: 500pt
+  
+    Display conservation
+     
+    This display style uses the :meth:`seq.alg.Conservation`-Algorithm which calculates
+    the Conservation for each column. This Mode is only available for alignments.
+  
+  **4. Highlight conservation 2**
+  
+    .. image:: images/100615_conservation_2.png
+       :width: 500pt
+      
+    Display conservation
+    
+    This implementation of conservation colors the columns grey, if all amino acids are 
+    from the same type. If all amino acids are from the same group, it colors the column with 
+    a light grey. Otherwise the column is colored white. This Mode is also only available for
+    alignments.
+
+
+Zoom
+^^^^
+
+With the sequence viewer of Openstructure it is possible to zoom in and out `<ctrl + mousewheel>`.
+
+ .. image:: images/100616_zoom_in.png
+ 
+ Zoom in, if you lost your glasses at home 
+ 
+ .. image:: images/100616_zoom_out.png
+ 
+ Zoom out, if you need a better overview of the sequence 
+ 
+Copy and Paste
+^^^^^^^^^^^^^^
+
+It is possible to copy sequence text from the sequence viewer by pressing `<ctrl + c>`. If you paste 
+the text (for example into a text editor), all the gaps will be filled with `-`.
+
+ .. image:: images/100616_copy_paste.png
+
+Search
+^^^^^^
+
+With `<ctrl + f>` you can show or hide the search bar which help you finding parts of a sequence.
+
+ .. image:: images/100617_search_bar.png
+
+.. class:: SequenceViewer
+  
+The SequenceViewer class represents a graphical sequence viewer. To see the sequences of a :class:`gfx.Entity`, you
+can use the :meth:`AddEntity` method. If you want to load an alignment, the :meth:`AddAlignment` method can be used.
+
+  .. method:: AddAlignment(alignment)
+        
+    Add :class:`seq.AlignmentHandle` to SequenceViewer.  
+    
+    :param alignment: an alignment instance
+    :type  alignment: :class:`seq.AlignmentHandle`
+
+  .. method:: RemoveAlignment(alignment)
+  
+    Remove alignment from sequenceviewer.
+    
+    :param alignment: an alignment instance
+    :type  alignment: :class:`seq.AlignmentHandle`
+    :rtype: None
+
+  .. method:: ChangeDisplayMode(style [, obj : None])
+    
+    Change the display style of all alignments and sequences to the given style. If the obj parameter is given, it 
+    changes only the display style of the given object. 
+
+    If the style is not known, nothing happens
+    
+    See also :meth:`GetDisplayModes`, :meth:`GetCurrentDisplayMode`
+    
+    :param style: The display style
+    :type  style: :class:`string`
+    :param obj: The object you would like to change
+    :type obj: :class:`gfx.Entity`, :class:`seq.AlignmentHandle`
+    
+
+  .. method:: GetCurrentDisplayMode([obj : None])
+    
+    Returns the current display style. If there are objects with different display styles, " " will be returned 
+    otherwise the string of the display style.
+
+    :rtype: str
+    :param obj: The object you would like to get the display style
+    :type obj: :class:`gfx.Entity`, :class:`seq.AlignmentHandle`
+
+  .. method:: GetDisplayModes([obj : None])
+
+    Returns a list with all available display styles. If you pass an object, you will get only the display styles for 
+    the given object.
+
+    :rtype: StringList
+    :param obj: The object you would like to get all display styles
+    :type obj: :class:`gfx.Entity`, :class:`seq.AlignmentHandle`
+
+  .. method:: GetQObject()
+    
+    Get the SIP-QObject (QWidget), learn more about :doc:`python_cpp`.
+    
+    :rtype: PyQt4.QWidget
+
+  .. method:: Hide()
+  
+    Hide the Widget
+
+  .. method:: Show()
+
+    Shows the Widget
+

modules/index.rst

@@ -28,6 +28,7 @@ Modules
   seq/base/seq
   base/base
   io/io
+  gui/gui
 
 Extending OpenStructure
 --------------------------------------------------------------------------------