sphinx doc, added some gui stuff

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

modules/gui/doc/gui.rst

@@ -4,108 +4,19 @@
 .. module:: ost.gui
 
 The GUI of OpenStructure is designed to be intuitive, flexible and extensible. 
-Most of the widgets are organized in a big main window which is divided into
-four parts: the main area and three panels containing one or more 
-smaller widgets:
 
-.. image:: images/100208_OpenStructure_UI_Colored.png
+.. image:: images/100622_gui.png
+    :width: 600
 
-The panels primarily contains widgets interacting with the 3D window.
 All parts of the GUI are exported to Python and can be expanded with 
 C++ Qt widgets as well as with PyQt widgets. Learn more about :doc:`python_cpp`.
 
 .. toctree::
 
+  layout
   python_cpp
   scene_win
-  inspector_gadget
   tools
-  drag_and_drop
   python_shell
-  menubar
-  panels
   sequence_viewer
 
-Tools
---------------------------------------------------------------------------------
-OpenStructure has several :class:`Tool` which are all listed in the toolbar
-close to the 3D window. A tool is activated upon selecting it in the toolbar.
-Input events are sent to the tool as long as the `Ctrl` key (`Cmd` on Mac) is
-pressed. For example the rigid body manipulator will rotate and shift the
-currently selected nodes in the scene win. Upon releasing `Ctrl`, the events are
-sent to the camera, making it possible to rapidly switch between adjusting the
-viewing angle of the camera and manipulating the position and orientation of
-scene objects.
- 
-.. image:: images/100208_Tools.png  
- 
-The example `Write a Tool in Python` demonstrates how to add a simple tool
-(written in python) to OpenStructure.
-
-Drag and Drop support
---------------------------------------------------------------------------------
-The user interface of OpenStructure supports drag and drop events. Every file
-format that is supported by Openstructure can be opened by dragging and dropping
-it on the main window. When a python script (ending with .py) is being dropped
-on the UI, the script will be executed. For any other file type (for example PDB
-files, images and density maps), OpenStructure will try to load the file and
-display it in the 3D window, in the data viewer for images or in the sequence
-viewer.
-
-Python Shell
---------------------------------------------------------------------------------
-OpenStructure has a integrated python shell which allows you interactively enter
-Python commands. Learn more about it in :doc:`python_shell`-Tutorial.  
-
-The Side Panels
---------------------------------------------------------------------------------
-View Modes
-^^^^^^^^^^
-Each :class:`PanelBar` can have different :class:`PanelWidgetContainer` also
-called view modes. View modes can display the widgets which are held by the Side
-Panel in a different style. Every panel has the splitter and the tabbed view
-mode.
-The view mode can be changed in the Window menu of the Menubar.
-
-Drag and Drop
-^^^^^^^^^^^^^
-The widgets which are held by a Side Panel can be moved to an other position in
-the panel or even to another side panel. The widget can be moved by simply
-clicking on the border of the widget and drag and drop it to the desired
-position. The drag and drop feature is currently only supported by the splitter
-view mode.
-
-Adding a custom Widget
-^^^^^^^^^^^^^^^^^^^^^^
-The Left-, Bottom- and Right-Panel are organized by the :class:`Panels`-class. 
-It is only possible to display a widget which is in the :class:`WidgetPool` of 
-the panels class. Once a widget is in the pool all the methods of the Panels
-class can be used to display / hide the widget in any position of the panels.
-The Example `Add a custom Widget` describes, how to add a fancy PyQt Widget to
-the widget pool and finally display it in the right side bar.
-OpenStructure remembers the size and location of a Widget. So, OpenStructure 
-should look the same after restarting it.
-
-Main Area
---------------------------------------------------------------------------------
-Adding an own Widget
-^^^^^^^^^^^^^^^^^^^^
-The :class:`MainArea` is a mdi (multi document interface). Therefore it's
-possible to display multiple widgets in it. The example `Add a Widget to MDI` 
-demonstrates how to add a  widget to the MDI area.
-
-Menubar
---------------------------------------------------------------------------------
-Adding an new Menupoint
-^^^^^^^^^^^^^^^^^^^^^^^
-It is really straightforward to add a custom menupoint. Since the menubar is 
-exported to Python it is even easier to create such e menupoint. See the example 
-`Adding a Menu` which describes how this is done within python and PyQt.
-
-Nice to know
----------------------------------------------------------------------------------
-As you might have noticed nearly every gui example needs the :class:`GostyApp` 
-and the :class:`Perspective` within the code. Gosty app is a singleton class 
-which has getter methods to all important gui classes. The perspective class has 
-all the information about the layout of the whole application, it is accessible 
-over the gosty app instance.  

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/layout.rst

+Layout
+================================================================================
+.. currentmodule:: ost.gui
+
+Most of the widgets are organized in a big main window which is divided into
+four parts: the :class:`MainArea` and three panels (which are organized by the 
+:class:`PanelManager`) containing one or more smaller widgets:
+
+.. image:: images/100208_OpenStructure_UI_Colored.png
+
+The panels primarily contain widgets interacting with the 3D window.
+
+Drag and Drop support
+--------------------------------------------------------------------------------
+The user interface of OpenStructure supports drag and drop events. Every file
+format that is supported by Openstructure can be opened by dragging and dropping
+it on the main window. When a python script (ending with .py) is being dropped
+on the UI, the script will be executed. For any other file type (for example PDB
+files, images and density maps), OpenStructure will try to load the file and
+display it in the 3D window, in the data viewer for images or in the sequence
+viewer.
+
+Perspective
+--------------------------------------------------------------------------------
+
+.. class:: Perspective
+
+  The perspective manages the layout of the widgets inside the main window.
+  It contains important classes which itself manages again a sub part of the whole layout.
+  You can get the active perspective object from the gosty app:
+
+  .. code-block:: python
+  
+    app=gui.GostyApp.Instance()
+    perspective=app.perspective
+
+  .. method:: GetMainArea()
+  
+    Returns the main area which is used in this perspective.
+    
+    :rtype: :class:`MainArea`
+
+  .. method:: GetMenu(name)
+    
+    Get QMenu that corresponds to the given name.
+    If it does not exist, it will be created and returned.
+    
+    :param name: The name of the menu
+    :type  arg2: :class:`str`
+    :rtype: :class:`QtCore.QMenu`
+
+  .. method:: GetMenuBar()
+  
+    Returns the Menubar of the Application. Can be used to add some menupoints.
+    
+    :rtype: :class:`QtCore.QMenuBar`
+
+  .. method:: GetPanels()
+
+    The PanelManager class organizes all the widgets in the side panels.
+    Returns the PanelManager instance which is used in this perspective.
+
+    :rtype: :class:`PanelManager`
+
+  .. method:: HideAllBars()
+
+     Hides all side bars. Can be used if the MainArea should be expanded to full size.
+  
+  .. method:: StatusMessage(message)
+  
+    Set a status message. This method can also be called from Qt as slot.
+    
+    :param message: The message that will be displayed in the status bar.
+    :type  message: :class:`str`
+
+
+
+
+Main Area
+--------------------------------------------------------------------------------
+Adding an own Widget
+^^^^^^^^^^^^^^^^^^^^
+The :class:`MainArea` is a mdi (multi document interface). Therefore it's
+possible to display multiple widgets in it. The following example demonstrates 
+how to add a  widget to the MDI area:
+
+  .. code-block:: python
+  
+    app=gui.GostyApp.Instance()
+    main_area=app.perspective.main_area
+    label=QtGui.QLabel("Hello World")
+    main_area.AddWidget("The beginning..", label)
+    
+.. class:: MainArea
+
+   It is implemented as a MDI (multi document interface). This allows you to add custom widgets to it.
+
+  .. method:: AddPersistentWidget(title, name, widget [, window_state])
+
+    add a widget whose geometry is preserved across application relaunches.
+    For widgets that are volatile, use :meth:`AddWidget`
+    If tabbed mode is enabled, the widget geometry is ignored.
+
+    :param title: string that is displayed in the gui
+    :type  title: :class:`str`
+    :param name: is the unique name (within the scope of the main area) for the widget that is used to restore and save the widget geometry.
+    :type  name: :class:`str`
+    :param widget: is the widget to be added to the main area
+    :type  widget: :class:`QtCore.QWidget`
+    :param window_state: custom window_state for the widget. See Qt Documentation to learn more about WindowStates.
+    :type  name: :class:`QWindowState`
+
+  .. method:: AddPersistentWidget(title, name, widget, width, height, x, y)
+
+     add a widget whose geometry is preserved across application relaunches
+     For widgets that are volatile, use #AddWidget()
+     If tabbed mode is enabled, the widget geometry is ignored.
+
+    :param title: string that is displayed in the gui
+    :type  title: :class:`str`
+    :param name: is the unique name (within the scope of the main area) for the widget that is used to restore and save the widget geometry.
+    :type  name: :class:`str`
+    :param widget: is the widget to be added to the main area
+    :type  widget: :class:`QtCore.QWidget`
+    :param width: width of the widget inside the mdi
+    :type  width: :class:`int`
+    :param height: height of the widget inside the mdi
+    :type  height: :class:`int`
+    :param x: x position of the widget inside the mdi
+    :type  x: :class:`int`
+    :param y: y position of the widget inside the mdi
+    :type  y: :class:`int`
+
+  .. method:: AddWidget(title, widget)
+  
+    add volatile widget
+  
+    :param title: string that is displayed in the gui
+    :type  title: :class:`str`
+    :param widget: is the widget to be added to the main area
+    :type  widget: :class:`QtCore.QWidget`
+
+  .. method:: ShowSubWindow(widget)
+  
+    display the given widget inside the main area
+    This method can be used to make a widget visible that has been added to the mdi area.
+    This method should only be called if you are sure, that the widget has been added to the main area.
+    Otherwise, there might be an unexpected behavior!
+  
+    :param widget: widget which you want to make visible
+    :type  widget: :class:`QtCore.QWidget`
+
+  
+  .. method:: HideSubWindow(widget)
+  
+    brief hides the given widget inside the main area
+    This method can be used to hide a widget that has been added to this mdi area.
+    This method should only be called if you are sure, that the widget has been added to the main area.
+    Otherwise, there might be an unexpected behavior!
+  
+    :param widget: widget which you want to hide
+    :type  widget: :class:`QtCore.QWidget`
+  
+  .. method:: EnableTabbedMode(tabbed_mode)
+    
+    brief switch between free window and tabbed window mode
+     
+    :param tabbed_mode: whether you want to enable or disable the tabbed mode. Default is True
+    :type  tabbed_mode: :class:`bool`
+  
+Panels
+--------------------------------------------------------------------------------
+
+View Modes
+^^^^^^^^^^
+
+Each side panel can have different view modes. View modes can display the widgets 
+which are held by the Side Panel in a different style. Every panel has the 
+`splitter` and the `tabbed` view mode. The view mode can be changed in the Window 
+menu of the Menubar:
+
+.. image:: images/100622_view_modes.png
+
+Drag and Drop
+^^^^^^^^^^^^^
+
+The widgets which are held by a Side Panel can be moved to an other position in 
+the panel or even to another side panel. The widget can be moved by simply 
+clicking on the border of the widget and drag and drop it to the desired position.
+The drag and drop feature is currently only supported by the splitter view mode.
+
+Adding a custom Widget
+^^^^^^^^^^^^^^^^^^^^^^
+
+The Left-, Bottom- and Right-Panel are organized by one Superclass. It is only 
+possible to display a widget which is in the widget pool of the panels class. 
+Once a widget is in the pool all the methods of the Panels class can be used to 
+display / hide the widget in any position of the panels. OpenStructure remembers 
+the size and location of a Widget. So, OpenStructure should look the same after 
+restarting it.
+
+The following example shows, how to add a PyQt Widget to the widget pool and finally 
+display it in the right side bar:
+
+  .. code-block:: python
+  
+    qwidget = QtGui.QLabel("Test")
+    widget=gui.WrappedWidget(qwidget)
+    panels=gui.GostyApp.Instance().perspective.GetPanels()
+    panels.AddWidgetToPool("Test Label",widget)
+    panels.AddWidget(gui.PanelPosition.RIGHT_PANEL, widget)
+    qwidget.show()
+
+.. class:: PanelManager
+
+  Class which organizes all widgets which are in the side panels
+  This class handles all side bar widgets. It can be used to display, hide or move a widget to a :class:`PanelBar`. There are three Bars (left, bottom, right) which are organized by this class.
+  Whenever a widget is being removed or added it checks first if the widget type is known and if there are available instances.
+  
+  .. method:: AddWidget(pos, widget[, hidden])
+
+    Display a Widget in a PanelBar. 
+    With Method you can add a widget to the given PanelBar. The widget which finally will be added to the gui will be created from the WidgetRegistry.
+    If the WidgetPool does not know the class name of the given widget or if there are no instances left, nothing will happen.
+
+    :param pos: Indicates which PanelBar is affected
+    :type  pos: :data:`PanelPosition`
+    :param widget: the widget will not directly added to the PanelBar. The class_name will be used to identify the widget in the WidgetRegistry which will return a fresh instance of this class.
+    :type  arg3: :class:`int`
+    :param hidden: marks if the class should be displayed in the gui. Default the widget will be shown. By default False is set
+    :type  hidden: bool
+
+  .. method:: AddWidgetByName(pos, class_name, hidden)
+
+    Display a Widget in a PanelBar
+    Same as :meth:`AddWidget`
+
+    :param pos: Indicates which PanelBar is affected
+    :type  pos: :class:`PanelPosition`
+    :param class_name: the class_name of the widget you would like to add.
+    :type  class_name: :class:`str`
+    :param hidden: marks if the class should be displayed in the gui. Default the widget will be shown.
+    :type  hidden: bool
+
+  .. method:: AddWidgetToPool(class_name, limit)
+
+     Add a widget to the widget pool.
+     The widget must already be in the WidgetRegistry.
+     If you are not sure if the Widget is in the WidgetRegistry, use the other `AddWidgetToPool` Method instead.
+
+    :param class_name: class name of class which should be added to the widget pool.
+    :type  class_name: :class:`str`
+    :param limit: amount of parallel instances allowed (-1 if infinite)
+    :type  limit: :class:`int`
+
+  .. method:: AddWidgetToPool(name, widget)
+
+     Add a widget to the widget pool. Same as :meth:`AddWidgetToPool`
+     
+    :param name: Name which is displayed in the gui.
+    :type  name: :class:`str`
+    :param widget: Widget which will be added to the WidgetPool of this class and the WidgetRegistry. 
+    :type  widget: :class:`WrappedWidget`
+
+  .. method:: GetMenu()
+    
+     The GetMenu method returns a QMenu reference, which contains various actions. The action states will be updated automatically.
+     Returns a reference to a QMenu which can be used for example in a QMenuBar
+     
+    :rtype: :class:`QObject`
+
+  .. method:: GetQObject()
+
+    Get the SIP-QObject (QObject), learn more about :doc:`python_cpp`.
+    
+    :rtype: PyQt4.QObject
+
+  .. method:: RemoveWidget(widget)
+
+    Remove a Widget out of a PanelBar
+    The widget will be removed if it is in a PanelBar
+  
+    :param arg2: widget which should be removed
+    :type  arg2: :class:`WrappedWidget`
+
+.. data:: PanelPosition
+ 
+  This enum indicates the Position of the Panel
+
+  * BOTTOM_PANEL
+     The bottom panel  
+  * LEFT_PANEL
+     The left panel
+  * RIGHT_PANEL
+      The right panel
+
+Menubar
+--------------------------------------------------------------------------------
+Adding an new Menupoint
+^^^^^^^^^^^^^^^^^^^^^^^
+It is really straightforward to add a custom menupoint. Since the menubar is 
+exported to Python it is even easier to create such e menupoint. The following example 
+describes how this is done within python and PyQt:
+
+.. code-block:: python
+
+  menu_bar=gui.GostyApp.Instance().perspective.GetMenuBar()
+  test_action = QtGui.QAction('Test Menu Point', menu_bar) 
+  test = menu_bar.addMenu('&Test')
+  test.addAction(test_action)
+
+The MenuBar class is a normal Qt QMenubar (see the Qt Documentation for more information 
+about QMenubar). By getting the Menubar from the perspective, it is automatically 
+converted to a SIP Object which can be used within python.
+
+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.
+ 
\ No newline at end of file

modules/gui/doc/python_cpp.rst

@@ -8,18 +8,18 @@ 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
+.. 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
+  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
+.. 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/scene_win.rst

@@ -16,7 +16,7 @@ selected objects.
 
   .. method:: GetContextMenu()
   
-     Returns the :class:`ContextMenu`-instance.
+    Returns the :class:`ContextMenu`-instance.
      
     :rtype: ContextMenu
 

modules/gui/doc/tools.rst

+Tools
+--------------------------------------------------------------------------------
+.. currentmodule:: ost.gui
+
+OpenStructure has several :class:`Tool` which are all listed in the toolbar
+close to the 3D window. A tool is activated upon selecting it in the toolbar.
+Input events are sent to the tool as long as the `Ctrl` key (`Cmd` on Mac) is
+pressed. For example the rigid body manipulator will rotate and shift the
+currently selected nodes in the scene win. Upon releasing `Ctrl`, the events are
+sent to the camera, making it possible to rapidly switch between adjusting the
+viewing angle of the camera and manipulating the position and orientation of
+scene objects.
+ 
+.. image:: images/100208_Tools.png  
+ 
+The example `Write a Tool in Python` demonstrates how to add a simple tool
+(written in python) to OpenStructure.
+
+.. class:: Tool
+
+  Parameters of the tool that are configurable should be implemented using the
+  ToolOptions facility. This automatically takes care of remembering the
+  used options over different sessions (in the future) and creates a widget 
+  to modify these options.
+
+  input_events Input Events
+
+  Tools receive input events when the Control key (Command on MacOS X) is
+  pressed. This includes both keyboard events and mouse events such as mouse
+  move events, clicks and Real clicks.
+
+  Tools only receive mouse move events when one of the mouse buttons is 
+  pressed. 
+
+  .. method:: CanOperateOn(nodes)
+
+    determines if the tool can manipulate a certain :class:`gfx.GfxNode`. 
+    This method is used to enabled/disable certain actions (in the toolbar, for example).
+
+    Return True if the Tool can operate on all GfxNodes which are in the given list. Otherwise False 
+
+    :param nodes: List with :class:`gfx.GfxNode`
+    :type  nodes: :class:`NodePtrList`
+    :rtype: bool
+
+  .. method:: Click(event)
+
+    left mouse click
+
+    :param event: object with the event information
+    :type  arg2: :class:`MouseEvent`
+
+  .. method:: DoubleClick(event)
+    
+    double click
+    
+    :param event: object with the event information
+    :type  event: :class:`MouseEvent`
+
+  .. method:: GetIconPath()
+    
+    Returns the path to an shiny icon. 
+    If no path is given, no icon will be displayed
+    
+    :rtype: :class:`str`
+
+  .. method:: GetName()
+    
+    Returns the name of the Tool which will be displayed in the gui.
+    
+    :rtype: :class:`str`
+
+  .. method:: GetToolOptions()
+
+       
+    :rtype: :class:`ToolOptions`
+