doc/salome/gui/input/using_pluginsmanager.doc

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