doc/salome/gui/input/using_help_panel.rst

   1 .. _using_help_panel:
   2
   3 ****************
   4 Using Help Panel
   5 ****************
   6
   7 .. contents:: Table of Contents
   8
   9 In SALOME, each module can show introduction information and/or context help
  10 in the **Help panel**. This panel is shown in the right dock area of the
  11 SALOME GUI desktop.
  12
  13 .. figure:: ../images/help_panel.png
  14    :align: center
  15    :alt: Help panel
  16
  17 .. _hp_show_help_panel:
  18
  19 Show help panel
  20 ===============
  21
  22 In order to show *Help panel*, the module must request it in the standard way, in
  23 the ``windows()`` method, for example:
  24
  25 .. code-block:: c++
  26    :emphasize-lines: 4
  27
  28     void GeometryGUI::windows(QMap<int, int>& map) const
  29     {
  30       map.insert(SalomeApp_Application::WT_ObjectBrowser, Qt::LeftDockWidgetArea);
  31       map.insert(SalomeApp_Application::WT_InfoPanel, Qt::RightDockWidgetArea);
  32       map.insert(SalomeApp_Application::WT_NoteBook, Qt::LeftDockWidgetArea);
  33       map.insert(SalomeApp_Application::WT_PyConsole, Qt::BottomDockWidgetArea);
  34     }
  35
  36 .. note:: The dock area position flag is ignored for the *Help panel*.
  37
  38 .. _hp_module_description:
  39
  40 Module description
  41 ==================
  42
  43 To display short annotation of the module in the desktop in the application's
  44 *neutral point* (when there's no active module, see figure above),
  45 add the ``<description>`` parameter to the main module's section in the configuration
  46 file - ``LightApp.xml`` or ``SalomeApp.xml``, for example:
  47
  48 .. code-block:: xml
  49    :emphasize-lines: 6
  50
  51     <document>
  52       <section name="SMESH">
  53         <parameter name="name" value="Mesh"/>
  54         <parameter name="icon" value="ModuleMesh.png"/>
  55         <parameter name="version" value="9.6.0"/>
  56         <parameter name="description" value="Generate mesh from CAD model or import mesh"/>
  57       </section>
  58     </document>
  59
  60 Also, provide a translation of the module description to other languages in the
  61 corresponding translation files (``*.ts``).
  62
  63 .. _hp_api:
  64
  65 API of Help panel
  66 =================
  67
  68 .. _hp_api_cpp:
  69
  70 C++
  71 ---
  72
  73 Help panel is implemented in SALOME GUI module, via the ``QtxInfoPanel`` class.
  74 To obtain a reference to the Help panel, use method ``infoPanel()`` of the
  75 ``LightApp_Application`` or ``SalomeApp_Application`` class:
  76
  77 .. code-block:: c++
  78
  79     #include <QtxInfoPanel.h>
  80     ...
  81     SalomeApp_Application* app = dynamic_cast<SalomeApp_Application*>(application());
  82     QtxInfoPanel* ip = app->infoPanel();
  83
  84 The class ``QtxInfoPanel`` provides several methods which can be used to manage
  85 content of the *Help panel*. It is possible to add text labels and actions (these latter
  86 are presented as buttons). The items can be arranged into the logical blocks - groups;
  87 groups can contain other groups. All methods creating content items return unique
  88 identifier which can be later used to change item's visibility, enable/disable it
  89 (actions can be also enabled/disable directly), remove it or clear its contents
  90 (for groups). Top level container has identifier ``-1``.
  91
  92 .. code-block:: c++
  93
  94     // Set panel's title (put empty string to hide title)
  95     ip->setTitle("Welcome to my module");
  96
  97     // Create group box
  98     int gb = ip->addGroup("General features");
  99
 100     // Add action to the group box
 101     QAction* action = new QAction("My feature");
 102     int id1 = ip->addAction(action, gb);
 103
 104     // Add informative label to the group box
 105     int id2 = ip->addLabel("My cool feature", gb);
 106
 107     // Add another label, right-aligned, to the top-level container
 108     int id3 = ip->addLabel("Some information", Qt::AlignRight);
 109
 110     // Change visibility of given item
 111     ip->setVisible(id3, false);
 112
 113     // Enable/disable given item
 114     ip->setEnabled(gb, false);
 115
 116     // Remove given item
 117     ip->remove(id1);
 118
 119     // Remove all content of group
 120     ip->clear(gb);
 121
 122     // Clear Help panel
 123     ip->clear();
 124
 125 .. _hp_api_python:
 126
 127 Python
 128 ------
 129
 130 For Python modules, *Help panel* can be accessed via the ``SalomePyQt`` Python module.
 131
 132 .. code-block:: python
 133
 134     from PyQt5 import Qt as Q
 135     from SalomePyQt import SalomePyQt as sg
 136
 137     # Set panel's title (put empty string to hide title)
 138     sg.infoSetTitle("Welcome to my module")
 139
 140     # Create group box
 141     gb = sg.infoAddGroup("General features")
 142
 143     # Add action to the group box
 144     action = Q.QAction("My feature")
 145     id1 = sg.infoAddAction(action, gb)
 146
 147     # Add informative label to the group box
 148     id2 = sg.infoAddLabel("My cool feature", gb)
 149
 150     # Add another label, right-aligned, to the top-level container
 151     # Note: -1 is used explicitly as group identifier
 152     id3 = sg.infoAddLabel("Some information", Q.Qt.AlignRight, -1)
 153
 154     # Change visibility of given item
 155     sg.infoSetVisible(id3, False)
 156
 157     # Enable/disable given item
 158     sg.infoSetEnabled(gb, False)
 159
 160     # Remove given item
 161     sg.infoRemove(id1)
 162
 163     # Remove all content of group
 164     sg.infoClear(gb)
 165
 166     # Clear Help panel
 167     sg.infoClear()
 168
 169 .. _hp_update_panel
 170
 171 Notifications
 172 =============
 173
 174 Each time when *Help panel* is shown, currently active module is informed via
 175 the virtual method ``updateInfoPanel()``. This method can be used to properly
 176 update the contents of the *Help panel*, depending on the current context.