3 \page using_pluginsmanager Extend SALOME gui functions using python plugins
5 -# \ref S1_SALOMEPLUGINS
6 -# \ref S2_SALOMEPLUGINS
7 -# \ref S3_SALOMEPLUGINS
8 -# \ref S4_SALOMEPLUGINS
9 -# \ref S5_SALOMEPLUGINS
11 \section S1_SALOMEPLUGINS Objectives
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:
19 The default menu for plugins is "Tool->Extensions":
20 \image html SALOME_pythonplugins_menu.png
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
26 Then creates the mesh model:
27 \image html SALOME_pythonplugins_result.png
29 In this example, the end user has to write:
31 -# the python script that creates the mesh from the parameters, using
32 the GEOM and SMESH python interface, as in a clasic use case.
33 -# the dialog box in PyQt to input the parameters
34 -# the file salome_plugins.py that declares the plugins
36 This page explains only the last point.
38 \section S2_SALOMEPLUGINS Principles
40 The general form of the file salome_plugins.py is:
43 import salome_pluginsmanager
45 # Creation of the plugin
46 def myplugin1(context):
48 # Here is the code of the plugin myplugin1
51 def myplugin2(context):
53 # Here is the code of the plugin myplugin2
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)
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.
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 at least the following attributes:
73 activeStudy = context.study
74 salomegui = context.sg
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):
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
87 -# Any path in the shell variable SALOME_PLUGIN_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.
91 \section S3_SALOMEPLUGINS A complete example
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
99 # Intialize the geompy factory with the active study
102 from salome.geom import geomBuilder
103 geompy = geomBuilder.New(salome.myStudy)
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)
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" )
118 The job consists in creating the file salome_plugins.py as follows:
121 import salome_pluginsmanager
122 def trihedron(context):
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)
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" )
140 # Register the function in the plugin manager
141 salome_pluginsmanager.AddFunction('O,Vx,Vy,Vz',
142 'Creates the trihedron',
147 Move this script in the directory
148 ~/.config/salome/Plugins, run SALOME and enjoy your new function.
150 \section S4_SALOMEPLUGINS How to select an object of the object browser
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.
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
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:
173 shape = salomeObj.GetShapeToMesh()
175 print "The selection is not a mesh"
178 A example of those methods is available with the demo examples.
179 See the next chapter \ref S5_SALOMEPLUGINS.
181 \section S5_SALOMEPLUGINS Other examples
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.
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.
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
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
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
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.