diff --git a/modules/gui/doc/gui.rst b/modules/gui/doc/gui.rst new file mode 100644 index 0000000000000000000000000000000000000000..6c25f35ec22beff4a9ba89d8dccee83229c42569 --- /dev/null +++ b/modules/gui/doc/gui.rst @@ -0,0 +1,111 @@ +:mod:`~ost.gui` -- Graphical User Interface +================================================================================ + +.. 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 + +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:: + + 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. diff --git a/modules/gui/doc/images/100208_OpenStructure_UI_Colored.png b/modules/gui/doc/images/100208_OpenStructure_UI_Colored.png new file mode 100644 index 0000000000000000000000000000000000000000..53338891b594d8dc23e2b9ea509a30c01b5dcb45 Binary files /dev/null and b/modules/gui/doc/images/100208_OpenStructure_UI_Colored.png differ diff --git a/modules/gui/doc/images/100208_Scene_Win.png b/modules/gui/doc/images/100208_Scene_Win.png new file mode 100644 index 0000000000000000000000000000000000000000..6a473dd9edac11351e5de2a06e615ecc46f8585c Binary files /dev/null and b/modules/gui/doc/images/100208_Scene_Win.png differ diff --git a/modules/gui/doc/images/100208_Tools.png b/modules/gui/doc/images/100208_Tools.png new file mode 100644 index 0000000000000000000000000000000000000000..7d6a4c87d28975b575b25201e6e6b8f758eebf75 Binary files /dev/null and b/modules/gui/doc/images/100208_Tools.png differ diff --git a/modules/gui/doc/images/100210_auto_completion.png b/modules/gui/doc/images/100210_auto_completion.png new file mode 100644 index 0000000000000000000000000000000000000000..ba3f14437cb98d612c6a1b7f07e080f595a0397a Binary files /dev/null and b/modules/gui/doc/images/100210_auto_completion.png differ diff --git a/modules/gui/doc/images/100210_multi_line.png b/modules/gui/doc/images/100210_multi_line.png new file mode 100644 index 0000000000000000000000000000000000000000..8a37894d787737e0d7278edd29273518f22c5f39 Binary files /dev/null and b/modules/gui/doc/images/100210_multi_line.png differ diff --git a/modules/gui/doc/images/100210_path_completion.png b/modules/gui/doc/images/100210_path_completion.png new file mode 100644 index 0000000000000000000000000000000000000000..fa1e1d820417382addaa75b23d2a41996058b005 Binary files /dev/null and b/modules/gui/doc/images/100210_path_completion.png differ diff --git a/modules/gui/doc/images/100210_single_line.png b/modules/gui/doc/images/100210_single_line.png new file mode 100644 index 0000000000000000000000000000000000000000..de79f55106aceb62d5d8a33af7f539415b317d76 Binary files /dev/null and b/modules/gui/doc/images/100210_single_line.png differ diff --git a/modules/gui/doc/images/100614_Inspector_gadget.png b/modules/gui/doc/images/100614_Inspector_gadget.png new file mode 100644 index 0000000000000000000000000000000000000000..a51df19f08231202b5697e2956c7e27c9db35fd2 Binary files /dev/null and b/modules/gui/doc/images/100614_Inspector_gadget.png differ diff --git a/modules/gui/doc/images/100614_context_menu_view.png b/modules/gui/doc/images/100614_context_menu_view.png new file mode 100644 index 0000000000000000000000000000000000000000..39a95e7c646360b13dfc3d8b133b5e60fc8695e1 Binary files /dev/null and b/modules/gui/doc/images/100614_context_menu_view.png differ diff --git a/modules/gui/doc/images/100614_entity_context_menu.png b/modules/gui/doc/images/100614_entity_context_menu.png new file mode 100644 index 0000000000000000000000000000000000000000..edd1884276d890f2733130c7b34098ba37cb2e48 Binary files /dev/null and b/modules/gui/doc/images/100614_entity_context_menu.png differ diff --git a/modules/gui/doc/images/100615_conservation_1.png b/modules/gui/doc/images/100615_conservation_1.png new file mode 100644 index 0000000000000000000000000000000000000000..3425bc9ec9c839ae00c48008ee64f93aad32acbf Binary files /dev/null and b/modules/gui/doc/images/100615_conservation_1.png differ diff --git a/modules/gui/doc/images/100615_conservation_2.png b/modules/gui/doc/images/100615_conservation_2.png new file mode 100644 index 0000000000000000000000000000000000000000..62fa128fbe19f06eb79585c163f649948d6f7982 Binary files /dev/null and b/modules/gui/doc/images/100615_conservation_2.png differ diff --git a/modules/gui/doc/images/100615_property_type.png b/modules/gui/doc/images/100615_property_type.png new file mode 100644 index 0000000000000000000000000000000000000000..e29b26d9be74dbca371044c0ccf1857fdf3a5e6c Binary files /dev/null and b/modules/gui/doc/images/100615_property_type.png differ diff --git a/modules/gui/doc/images/100615_secondary_structure.png b/modules/gui/doc/images/100615_secondary_structure.png new file mode 100644 index 0000000000000000000000000000000000000000..fffe0f08b359023544a5aaf6146c6f4f795b461c Binary files /dev/null and b/modules/gui/doc/images/100615_secondary_structure.png differ diff --git a/modules/gui/doc/images/100615_select_display_style.png b/modules/gui/doc/images/100615_select_display_style.png new file mode 100644 index 0000000000000000000000000000000000000000..8907c662352e76cfe91f5ff38cf18a47c8bb3d2e Binary files /dev/null and b/modules/gui/doc/images/100615_select_display_style.png differ diff --git a/modules/gui/doc/images/100616_copy_paste.png b/modules/gui/doc/images/100616_copy_paste.png new file mode 100644 index 0000000000000000000000000000000000000000..b5508add6dd85540ffdd82f318a23225ca105906 Binary files /dev/null and b/modules/gui/doc/images/100616_copy_paste.png differ diff --git a/modules/gui/doc/images/100616_zoom_in.png b/modules/gui/doc/images/100616_zoom_in.png new file mode 100644 index 0000000000000000000000000000000000000000..9c1e19565036badac39f35ae0b9d4c98b174b9db Binary files /dev/null and b/modules/gui/doc/images/100616_zoom_in.png differ diff --git a/modules/gui/doc/images/100616_zoom_out.png b/modules/gui/doc/images/100616_zoom_out.png new file mode 100644 index 0000000000000000000000000000000000000000..9dbc1474ce678ecc59ff1be92326cba340f38100 Binary files /dev/null and b/modules/gui/doc/images/100616_zoom_out.png differ diff --git a/modules/gui/doc/images/100617_search_bar.png b/modules/gui/doc/images/100617_search_bar.png new file mode 100644 index 0000000000000000000000000000000000000000..315ceadede69ae1d508b304b2fd77c44ba6bad45 Binary files /dev/null and b/modules/gui/doc/images/100617_search_bar.png differ diff --git a/modules/gui/doc/inspector_gadget.rst b/modules/gui/doc/inspector_gadget.rst new file mode 100644 index 0000000000000000000000000000000000000000..116746d1ef090a10f1c110a08434476ed8b81392 --- /dev/null +++ b/modules/gui/doc/inspector_gadget.rst @@ -0,0 +1,11 @@ +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. diff --git a/modules/gui/doc/python_cpp.rst b/modules/gui/doc/python_cpp.rst new file mode 100644 index 0000000000000000000000000000000000000000..9b30010fee0b2257936c4ae8b885cc5e38c249ae --- /dev/null +++ b/modules/gui/doc/python_cpp.rst @@ -0,0 +1,25 @@ +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 diff --git a/modules/gui/doc/python_shell.rst b/modules/gui/doc/python_shell.rst new file mode 100644 index 0000000000000000000000000000000000000000..780bd42bfba20e774da06af7e8356ffb0fc46edd --- /dev/null +++ b/modules/gui/doc/python_shell.rst @@ -0,0 +1,40 @@ +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 diff --git a/modules/gui/doc/scene_win.rst b/modules/gui/doc/scene_win.rst new file mode 100644 index 0000000000000000000000000000000000000000..8cbd6875219bca8d774bb359863e667d6a5c6b1f --- /dev/null +++ b/modules/gui/doc/scene_win.rst @@ -0,0 +1,124 @@ +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 diff --git a/modules/gui/doc/sequence_viewer.rst b/modules/gui/doc/sequence_viewer.rst new file mode 100644 index 0000000000000000000000000000000000000000..87c2ae384729475de71273cc0f78d1081457d298 --- /dev/null +++ b/modules/gui/doc/sequence_viewer.rst @@ -0,0 +1,178 @@ +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 + diff --git a/modules/index.rst b/modules/index.rst index cdb3284d5b4d8ba64311e151052d0200d4a1d66f..c70e751c08e24eda54a2318c11ac46f829b97810 100644 --- a/modules/index.rst +++ b/modules/index.rst @@ -28,6 +28,7 @@ Modules seq/base/seq base/base io/io + gui/gui Extending OpenStructure --------------------------------------------------------------------------------