doc/salome/gui/input/using_pluginsmanager.rst

   1
   2
   3 .. _using_pluginsmanager:
   4
   5 ************************************************
   6 Extend SALOME gui functions using python plugins
   7 ************************************************
   8
   9 #. :ref:`S1_SALOMEPLUGINS`
  10 #. :ref:`S2_SALOMEPLUGINS`
  11 #. :ref:`S3_SALOMEPLUGINS`
  12 #. :ref:`S4_SALOMEPLUGINS`
  13 #. :ref:`S5_SALOMEPLUGINS`
  14
  15 .. _S1_SALOMEPLUGINS:
  16
  17 Objectives
  18 ==========
  19
  20 The SALOME python plugin manager allows the end user to extend the
  21 graphic interface of SALOME with custom functions written as python
  22 modules. The screenshots below show the example of a tool that creates
  23 a mesh from a set of geometrical parameters with the support of
  24 simple graphical interface:
  25
  26 The default menu for plugins is "Tool->Extensions":
  27
  28 .. image:: ../images/SALOME_pythonplugins_menu.png
  29         :align: center
  30
  31 In this example, the plugin provides a small interface to input the
  32 parameters (not provided by the plugin manager):
  33
  34 .. image:: ../images/SALOME_pythonplugins_dialog.png
  35         :align: center
  36
  37 Then creates the mesh model:
  38
  39 .. image:: ../images/SALOME_pythonplugins_result.png
  40         :align: center
  41
  42 In this example, the end user has to write:
  43
  44 #. the python script that creates the mesh from the parameters, using the GEOM and SMESH python interface, as in a classic use case,
  45 #. the dialog box in PyQt to input the parameters,
  46 #. the file salome_plugins.py that declares the plugins.
  47
  48 This page explains only the last point.
  49
  50 .. _S2_SALOMEPLUGINS:
  51
  52 Principles
  53 ==========
  54
  55 The general form of the file salome_plugins.py is:
  56
  57 .. code-block:: python
  58    :linenos:
  59
  60         import salome_pluginsmanager
  61
  62         # Creation of the plugin
  63         def myplugin1(context):
  64            ...
  65            # Here is the code of the plugin myplugin1
  66            ...
  67
  68         def myplugin2(context):
  69            ...
  70            # Here is the code of the plugin myplugin2
  71            ...
  72
  73         # Declaration of the plugins to the pluginsmanager
  74         salome_pluginsmanager.AddFunction('My plugin n°1', 'This action runs the plugin n°1', myplugin1)
  75         salome_pluginsmanager.AddFunction('My plugin n°2', 'This action runs the plugin n°2', myplugin2)
  76         ...
  77
  78 The procedure is to define a function that implements the plugin, and
  79 to declare this function to the plugins manager. The implementation
  80 can be very variable. It is advisable to consider this function as a
  81 proxy to your code that you can manage in a python package
  82 installed in the standard SALOME python directories.
  83
  84 In this code, the variable "context" is automatically transmitted by
  85 the pluginmanager when you request the plugin. This context provides
  86 you with at least the following attributes:
  87
  88 .. code-block:: python
  89    :linenos:
  90
  91         activeStudy = context.study
  92         salomegui = context.sg
  93
  94 Once written, this script salome_plugin.py has to be moved to a
  95 specific place on your filesystem where SALOME is programmed to search
  96 for plugins. The possible directories are (in search order):
  97
  98 #. The directory <\*_ROOT_DIR>/share/salome/plugins/<module_name>, when this plugin is developped in the framework of a SALOME module (<\*_ROOT_DIR> is the root installation directory of the module, and <module_name> is the name of the module in low letters).
  99 #. The directory ~/.config/salome/Plugins for personnal end user plugins.
 100 #. Any path in the shell variable SALOME_PLUGINS_PATH (each path must be separated by a comma ":" for unix and ";" for windows). This variable should be set and exported before running the SALOME application.
 101
 102 .. _S3_SALOMEPLUGINS:
 103
 104 A complete example
 105 ==================
 106
 107 Suppose that you write a SALOME script that creates a trihedron for each of
 108 your studies (a simple and standard SALOME script, that every end user
 109 is capable to write if he reads the documentation and follows the
 110 training course):
 111
 112 .. code-block:: python
 113    :linenos:
 114
 115         # Intialize the geompy factory with the active study
 116         import salome
 117         import GEOM
 118         from salome.geom import geomBuilder
 119         geompy = geomBuilder.New(salome.myStudy)
 120
 121         # Create the objects
 122         Vx = geompy.MakeVectorDXDYDZ(10, 0, 0)
 123         Vy = geompy.MakeVectorDXDYDZ(0, 10, 0)
 124         Vz = geompy.MakeVectorDXDYDZ(0, 0, 10)
 125         origin = geompy.MakeVertex(0, 0, 0)
 126
 127         # Register the objects in the active study
 128         geompy.addToStudy( Vx, "Vx" )
 129         geompy.addToStudy( Vy, "Vy" )
 130         geompy.addToStudy( Vz, "Vz" )
 131         geompy.addToStudy( origin, "origin" )
 132
 133 The job consists in creating the file salome_plugins.py as follows:
 134
 135 .. code-block:: python
 136    :linenos:
 137
 138         import salome_pluginsmanager
 139         def trihedron(context):
 140             import GEOM
 141             from salome.geom import geomBuilder
 142             geompy = geomBuilder.New(salome.myStudy)
 143             # Intialize the geompy factory with the active study
 144             activeStudy = context.study
 145             geompy.init_geom(activeStudy)
 146             # Create the objects
 147             Vx = geompy.MakeVectorDXDYDZ(10, 0, 0)
 148             Vy = geompy.MakeVectorDXDYDZ(0, 10, 0)
 149             Vz = geompy.MakeVectorDXDYDZ(0, 0, 10)
 150             origin = geompy.MakeVertex(0, 0, 0)
 151             # Register the objects in the active study
 152             geompy.addToStudy( Vx, "Vx" )
 153             geompy.addToStudy( Vy, "Vy" )
 154             geompy.addToStudy( Vz, "Vz" )
 155            geompy.addToStudy( origin, "origin" )
 156
 157         # Register the function in the plugin manager
 158         salome_pluginsmanager.AddFunction('O,Vx,Vy,Vz',
 159                                           'Creates the trihedron',
 160                                           trihedron)
 161
 162
 163 Move this script in the directory ~/.config/salome/Plugins, run SALOME and enjoy your new function.
 164
 165 .. _S4_SALOMEPLUGINS:
 166
 167 How to select an object of the object browser
 168 =============================================
 169
 170 Sometimes it can be useful to retrieve an object of the object browser to perform
 171 an action on it, for example, to select a mesh and display some information related to it.
 172
 173 Some important methods and objects to use are as follows:
 174
 175 #. context.sg.getObjectBrowser():  to connect the signal event `selectionChanged()` to a custom slot
 176 #. context.salome.sg.getAllSelected(): to get the list of selected object in the object browser
 177 #. objId = context.salome.sg.getSelected(0): to get the first selected object in the object browser
 178 #. salomeObj = context.salome.study.FindObjectID(objId).GetObject(): to retrieve the salome object from selection. It can be a GEOM, SMESH, or any other module object.
 179
 180   If it is a mesh, then it is possible to call methods of the SMESH::SMESH_Mesh interface
 181   on the object, for example GetShapeToMesh().
 182   If it is not a mesh, this call will raise an exception.
 183   So it is possible to write the code retrieving the shape a mesh is built on in the following way:
 184
 185 .. code-block:: python
 186    :linenos:
 187
 188         mesh = None
 189         try:
 190           shape = salomeObj.GetShapeToMesh()
 191         except:
 192           print "The selection is not a mesh"
 193
 194 An example of those methods is available with the demo examples.
 195 See the next chapter :ref:`S5_SALOMEPLUGINS`.
 196
 197 .. _S5_SALOMEPLUGINS:
 198
 199 Other examples
 200 ==============
 201
 202 The GUI module provides you with some basic demo examples located in
 203 the directory src/SalomeApp/pluginsdemo of the source space and
 204 installed in the directory $GUI_ROOT_DIR/share/salome/plugins/gui/demo.
 205
 206 .. note:: These examples are automatically installed when you install the GUI but are not activated. To activate the plugins, edit the file $GUI_ROOT_DIR/share/salome/plugins/gui/demo/salome_plugins.py and turn the variable DEMO_IS_ACTIVATED to True.
 207
 208 The demo examples are:
 209
 210 #. **trihedron:** create a trihedron and display it with fit on the size
 211 #. **tube_shapewithgui:** create a geom object from parameters given by a dialog box.
 212 #. **tube_meshwithgui:** create a mesh object from parameters given by a dialog box. This illustrates that a plugin can work with more than one SALOME module.
 213 #. **tube_shapewithguiAndPreview:** same than tube_shapewithgui but with an additionnal preview function (button apply in the dialog box).
 214 #. **runSalomeShellSession:** run a SALOME prepared shell session in a xterm.
 215 #. **minmax:** computes the min and max values of a control on a selected mesh.
 216         .. note:: This plugin is available in the SMESH module only. To activate it, edit the file $GUI_ROOT_DIR/share/salome/plugins/gui/demo/smesh_plugins.py and turn the variable DEMO_IS_ACTIVATED to True.
 217
 218