3 \mainpage Introduction to :sat:{PYCMP} sample module
5 The purpose of the \b :sat:{PYCMP} module is to describe briefly the different
6 steps in the development of a SALOME module in Python.
10 - \subpage tree_structure
11 - \subpage build_proc_files
16 - \subpage build_procedure
17 - \subpage run_procedure
18 - \subpage load_module
19 - \subpage catalog_def
23 \ref dev_steps ">> Next"
25 \page dev_steps Steps in construction of the example module
27 The example module chosen to illustrate the process of SALOME module
28 development is extremely simple. The module contains a single
29 component and this component provides a single service called \b
30 makeBanner that accepts a character string as the sole argument and
31 that returns a character string obtained by the concatenation of a
32 ':sat:{PYCMP}' and the input string. The component also provides a simple
35 The steps in the development are as follows:
36 - create a module tree structure
37 - create a SALOME component that can be loaded by a Python SALOME container
38 - configure the module so that the component is known to SALOME
41 \ref main "<< Previous"<br>\ref tree_structure ">> Next"
43 \page tree_structure Create the module tree structure
45 The first step in the development process is the creation of the
46 module tree file structure. The typical SALOME module usually includes
47 some set of the configuration files (used in the build procedure of a
48 module), Makefiles, IDL file that provides a definition of a CORBA
49 services implemented in a module and a set of source Python files
50 which implement the module CORBA engine and (optionally) its GUI.
52 The following file structure is typical for the SALOME module:
63 + make_common_starter.am
66 + check_:sat:{PYCMP}.m4
74 + :sat:{PYCMP}_Gen.idl
80 + :sat:{PYCMP}_utils.py
84 + :sat:{PYCMP}_msg_en.ts
85 + :sat:{PYCMP}_icons.ts
89 + :sat:{PYCMP}_small.png
90 + Exec:sat:{PYCMP}.png
93 + :sat:{PYCMP}Catalog.xml.in
101 Note that other files can be optionally present. For example, in some
102 SALOME modules sources tree you can find such files as AUTHORS,
103 INSTALL, ChangeLog, COPYING, NEWS, README, etc. Some files are
104 specific only for this :sat:{PYCMP} sample module, for example PNG images
105 in the resources directory which are used in the GUI dialog boxes etc.
107 The usual way of the sources directory tree structure initial creation
108 is to copy it from the existing SALOME module.
110 \warning The files of the platform base module (KERNEL) must not be
111 copied to initialise a module tree structure. It is usually preferable
112 to copy files from another module such as GEOM or MED.
114 The module name is :sat:{PYCMP}, the component name is :sat:{PYCMP} and all the
115 files are put in a directory named :sat:{PYCMP}1_SRC.
116 Below is a short description of these files. Note, that files with .in
117 suffix are the autoconf templates from which the actual files are
118 generated during the build procedure.
120 - build_configure, configure.ac, Makefile.am, make_common_starter.am
122 These files are a part of the build system based on GNU
123 automake/autoconf auto-tools. These files define the build procedure,
124 namely, compilation and installation rules like compiler and linker
125 options, installation destination folder, package version etc.
127 - adm_local/unix/config_files/check_:sat:{PYCMP}.m4
129 The files in this directory are also a part of the GNU auto-tools
130 -based build procedure. The scripts written in m4 language are usually
131 used to test an availability of some 3rd-party pre-requisite product,
132 compiler feature, different configuration options.
136 This file is used to document the module, it must give its version (at
137 least) and (optionally) compatibilities or incompatibilities with
138 other modules. This file is strongly recommended but is not essential
139 for operation of the module.
144 These files are not essential but make the example easier to
145 use. These are scripts that can be used to run SALOME session with
148 - idl/:sat:{PYCMP}_Gen.idl
150 This is the CORBA IDL definition of the services implemented by SALOME
153 - src/:sat:{PYCMP}/:sat:{PYCMP}.py
154 - src/:sat:{PYCMP}/:sat:{PYCMP}_utils.py
156 These files provide the implementation of a CORBA engine of the
157 :sat:{PYCMP} module. In particular, this is an implementation of the
158 services defined in the :sat:{PYCMP}_Gen.idl file.
160 - src/:sat:{PYCMP}GUI/:sat:{PYCMP}GUI.py
162 The src/:sat:{PYCMP}GUI is an optional directory that provides an
163 implementation of :sat:{PYCMP} module's GUI. Strictly speaking, the
164 GUI is optional for each SALOME module. In some cases it's
165 enough to implement CORBA engine only. Then, the services of the
166 module will be avaiable in a CORBA environment. The module can be
167 loaded to the SALOME container and its services can be used in the
168 Supervisor computation schemas, in Python scripts or/and refer to it
169 in other modules. A GUI is necessary in the cases if it is planned to
170 access to the module functionality from the SALOME GUI session via
171 menu actions, dialog boxes and so on.
173 - src/:sat:{PYCMP}GUI/:sat:{PYCMP}_msg_en.ts
174 - src/:sat:{PYCMP}GUI/:sat:{PYCMP}_icons.ts
176 These files provide a description (internationalization) of GUI
177 resources of the :sat:{PYCMP} module. :sat:{PYCMP}_msg_en.ts provides an English
178 translation of the string resources used in a module. :sat:{PYCMP}_icons.ts
179 defines images and icons resources used within the GUI of the
180 :sat:{PYCMP} module. Please refer to Qt linguist documentation for more
183 - resources/:sat:{PYCMP}.png
184 - resources/:sat:{PYCMP}_small.png
185 - resources/Exec:sat:{PYCMP}.png
186 - resources/handshake.png
189 The resources folder usually includes different resource files used
190 within the SALOME module. For example, :sat:{PYCMP}.png file provides an icon
191 of :sat:{PYCMP} module to be shown in the SALOME GUI desktop. Exec:sat:{PYCMP}.png is
192 an icon for the makeBanner() function used in the menu and
193 toolbar. The icons handshake.png and stop.png are used in the dialog
194 boxes and :sat:{PYCMP}_small.png icon is used to display in the Object
195 browser for root :sat:{PYCMP} entity.
197 - resources/:sat:{PYCMP}Catalog.xml.in
199 The XML description of the CORBA services provided by the :sat:{PYCMP}
200 module. This file is parsed by Supervisor and YACS module to generate
201 the list of service nodes to be used in the calculation schemas. The
202 simplest way to create this file is to use Catalog Generator utility
203 provided by the SALOME KERNEL module, that can automatically generate
204 XML description file from the IDL file.
206 - resources/SalomeApp.xml
208 This file is essential for the module. It provides some parameters of
209 the module which define module behavior in SALOME. In particular it
210 should provide a section with the name corresponding to the name of a
211 module (":sat:{PYCMP}" in this case) with the following parameters:
213 <section name=":sat:{PYCMP}">
214 <parameter name="name" value=":sat:{PYCMP}"/>
215 <parameter name="icon" value=":sat:{PYCMP}.png"/>
216 <parameter name="library" value="SalomePyQtGUI"/>
220 The "name" parameter defines GUI name of a module. The "icon"
221 parameter defines a GUI icon of a module. The parameter "library"
222 specifies the name of the C++ library representing the front-end of
223 the module in the SALOME GUI desktop. The Python modules which do not
224 implement its own C++ front-end GUI library should specify
225 "SalomePyQtGUI" value in this parameter.
227 The section "resources" also specifies the directory that contains
228 resources of a module (icons, translation files, etc).
231 <section name="resources">
232 <parameter name=":sat:{PYCMP}" value="${:sat:{PYCMP}_ROOT_DIR}/share/salome/resources/:sat:{PYCMP}"/>
238 The Doxygen configuration file. The Doxygen is used to build this
239 documentation. The file doxyfile.in provides a rules for the
240 generation of module documentation.
244 An input file for the Doxygen, which provides a source of this documentation.
246 \ref dev_steps "<< Previous"<br>\ref build_proc_files ">> Next"
248 \page build_proc_files Build procedure input files
250 SALOME uses autoconf and automake GNU auto-tools to build the
251 modules. The configure script is used for the build procedure to test
252 the system configuration and to pre-configure the module construction
255 The \b build_configure script provides a procedure that uses \b
256 configure.ac and set of \b Makefile.am files as input and uses autoconf
257 to generate the configure script and automake to generate Makefile.in
260 The files with an .in extension are the skeletons that are the input
261 of the configure script (to be more precise, these files should be
262 listed in the end of the configure.ac file in the AC_OUTPUT()
263 autoconf macro) and are transformed by the configure process.
265 Almost all files used for this process are located in the platform
266 base module KERNEL that is referenced by the KERNEL_ROOT_DIR
267 environment variable, namely in its salome_adm sub-folder.
268 Similarly, the GUI_ROOT_DIR environment variable is used for the
269 graphical user interface (GUI), that also provides a set of
270 configuration utilities (m4 files) in its adm_local folder. However,
271 some files must be modified as a function of the target module. This
272 is the case for build_configure and configure.ac files which usually
273 need to be adapted to the module needs.
275 The file \b make_common_starter.am file in the adm_local directory of
276 the example module provides basic build rules to be used in other
277 Makefile.am files. To refer to this file in the Makefile.am it is
278 necessary to use "include" clause:
281 include $(top_srcdir)/adm_local/unix/make_common_starter.am
284 The adm_local/unix/config_files is a directory in which the m4 files
285 that are used to test the configuration of the system in the configure
286 process can be placed. If the salome_adm files are not sufficient,
287 additional configuration files can be put to the adm_local directory.
289 \ref tree_structure "<< Previous"<br>\ref idl_dir ">> Next"
291 \page idl_dir The idl directory
293 The idl directory requires a Makefile.am that must make the
294 compilation of the idl :sat:{PYCMP}_Gen.idl file and install all the
295 generated files into the correct module installation directories. The
296 BASEIDL_FILES target has to be modified to reach this goal.
298 The idl file itself must define a CORBA module for which the name must
299 be different from the module name to avoid name conflicts and define a
300 CORBA interface that is derived at least from the EngineComponent interface
301 of the Engines module. The name of the CORBA module will be
302 \b :sat:{PYCMP}_ORB and the name of the interface will be \b :sat:{PYCMP}_Gen.
304 \ref build_proc_files "<< Previous"<br>\ref src_dir ">> Next"
306 \page src_dir The src directory
308 The src contains all source files required to build and install CORBA
309 engine and (optionally) GUI of the module. Each of these entities usually
310 has (but this is not actually obligatory) its own directory.
312 The Makefile.am simply triggers the path of sub-directories described
313 by the SUBDIRS target.
315 - The src/:sat:{PYCMP} directory
317 This directory contains the Python files that implement the engine
318 of the module. The Makefile.am defines the rules used to install these
319 files to the destination folder. The name of the module
320 engine Python file is predefined and should be set as <MODULE>.py
321 where <MODULE> is a name of the module. In the case of the :sat:{PYCMP}
322 module, the name of the engine Python script should be :sat:{PYCMP}.so.
324 The :sat:{PYCMP}.py Python script implements :sat:{PYCMP} class that is derived
325 from the :sat:{PYCMP}_Gen interface of the :sat:{PYCMP}_ORB__POA CORBA module,
326 the SALOME_ComponentPy_i class (base implementation of SALOME
327 Python module engine exported by the KERNEL module) and
328 SALOME_DriverPy_i class that provides base implementation of
329 persistence mechanism.
331 In particular, :sat:{PYCMP} class implements makeBanner() function that is
332 defined in the IDL interface :sat:{PYCMP}_ORB:::sat:{PYCMP}_Gen.
335 def makeBanner( self, name ):
336 banner = ":sat:{PYCMP} %s!" % name
341 defined in :sat:{PYCMP}_Gen CORBA interface also should be implemented by
344 - The src/:sat:{PYCMP}GUI directory
346 This directory contains the Python files that implement the GUI
347 of :sat:{PYCMP} module. The name of the module GUI Python script is
348 predefined and should be set as <MODULE>GUI.py where <MODULE> is a
349 name of the module. In the case of the :sat:{PYCMP} module, the name of the
350 GUI Python script should be :sat:{PYCMP}GUI.py.
352 The implementation of GUI of the :sat:{PYCMP} module should be done
353 according to the architecture and rules specified by the SALOME GUI
354 module. The :sat:{PYCMP}.py script should implement a set of the functions
355 which define the module behavior in GUI, for example, create menus,
356 toolbars, define context popup menus, objects selection behavior,
357 implement dialog boxes etc.
359 Here below is a short description of these methods. For more details
360 please refer to the SALOME GUI module documentation.
362 - initialize() - module first initialization; usually used to create
363 GUI actions, menus, toolbars and so on;
364 - activate() - module activation; perform actions which should
365 be done when the module is activated by the user;
366 - deactivate() - module deactivation; perform actions which should
367 be done when the module is deactivated by the user;
368 - windows() - get a list and a position of the windows to be
369 associated with the module; these windows will be automatically
370 opened and positioned according to the setting defined by the value
371 returned by this function;
372 - views() - get a list of the compatible viewers; these viewers
373 will be automatically opened/raised on the module activation;
374 - createPopupMenu() - create and return context popup menu according
375 to the current selection;
376 - createPreferences() - initialize module's preferences;
377 - preferenceChanged() - callback function that is called when some
378 module's preference is changed by the user; allows to perform the
379 corresponding actions;
380 - engineIOR() - to get the reference to the module CORBA engine
382 Note, that some of these methods are optional and need not be
383 obligatory implemented because SalomePyQtGUI_Module class provides a
384 base implementation of these functions. It's sometimes enough to
385 implement only some of them, depending on the module needs.
387 In the case of :sat:{PYCMP} module, some of these functions are
388 implemented to provide a sample for the development:
390 - engineIOR() that initializes :sat:{PYCMP} module's eggine:
395 if getORB() and getEngine():
396 IOR = getORB().object_to_string( getEngine() )
401 - initialize() that sets default module preferences
405 if not sgPyQt.hasSetting( ":sat:{PYCMP}", "def_obj_name"):
406 sgPyQt.addSetting( ":sat:{PYCMP}", "def_obj_name", GUIcontext.DEFAULT_NAME )
407 if not sgPyQt.hasSetting( ":sat:{PYCMP}", "creation_mode"):
408 sgPyQt.addSetting( ":sat:{PYCMP}", "creation_mode", 0 )
411 - createPreferences() that initializes module preferences for the
412 application's Preferences dialog box
415 def createPreferences():
416 if verbose() : print ":sat:{PYCMP}GUI.createPreferences() : study : %d" % _getStudyId()
417 gid = sgPyQt.addPreference( "General" )
418 gid = sgPyQt.addPreference( "Object creation", gid )
419 pid = sgPyQt.addPreference( "Default name", gid, SalomePyQt.PT_String, ":sat:{PYCMP}", "def_obj_name" )
420 pid = sgPyQt.addPreference( "Default creation mode", gid, SalomePyQt.PT_Selector, ":sat:{PYCMP}", "creation_mode" )
421 strings = QStringList()
422 strings.append( "Default name" )
423 strings.append( "Generate name" )
424 strings.append( "Ask name" )
426 indexes.append( QVariant(0) )
427 indexes.append( QVariant(1) )
428 indexes.append( QVariant(2) )
429 sgPyQt.setPreferenceProperty( pid, "strings", QVariant( strings ) )
430 sgPyQt.setPreferenceProperty( pid, "indexes", QVariant( indexes ) )
434 - windows() that defines dockable windows layout
438 if verbose() : print ":sat:{PYCMP}GUI.windows() : study : %d" % _getStudyId()
440 wm[SalomePyQt.WT_ObjectBrowser] = Qt.LeftDockWidgetArea
441 wm[SalomePyQt.WT_PyConsole] = Qt.BottomDockWidgetArea
445 Please refer to :sat:{PYCMP}GUI.py script for more details about
446 implementation of other callback functions.
448 An implemention of the Show:sat:{PYCMP}() function is quite simple. It shows
449 the small dialog box allowing user to enter the name, and then uses
450 reference to the module CORBA engine to invoke its makeBanner()
453 Note, that GUI elements of the Python module are implemented with help
454 of PyQt toolkit which provides a Python wrappings of the Qt library.
456 \ref idl_dir "<< Previous"<br>\ref bin_dir ">> Next"
458 \page bin_dir The bin directory
460 The file VERSION.in is used to document the module, it must define its
461 version and (optionally) its compatibilities or incompatibilities with
462 other modules. Therefore, it is strongly recommended but is not
463 essential for correct operation of the module.
465 The runAppli.in file is the equivalent of the runSalome script
466 distributed by the KERNEL module but configured to start SALOME
467 session with :sat:{PYCMP} module only.
469 The myrunSalome.py file reuses part of functionality provided by the
470 KERNEL's runSalome.py script. It is used to run SALOME session and
471 start :sat:{PYCMP} module in this session.
473 \ref src_dir "<< Previous"<br>\ref doc_dir ">> Next"
475 \page doc_dir The doc directory
477 This directory provides documentation files of the module. The
478 documentation of the module can be implemented in the arbitrary
479 way. But if you want your documentation to appear in the SALOME GUI
480 desktop's Help menu, some specific actions should be done as follows.
482 The documentation should be generated in the HTML format. For example,
483 the documentation of the :sat:{PYCMP} module is generated using Doxygen
484 tool. It allows to generate structured set of HTML pages from the set
485 of input plain text files. Input source files should include Doxygen
486 tags and optionally direct HTML tags. For more details please refer to
487 the Doxygen documentation.
489 The resulting documentation of a module should include at least one
490 file index.html. All the HTML and image files should be exported by
491 the build procedure to the following directory:
492 <module_installation_dir>/share/doc/salome/gui/<MODULE>
493 where <module_installation_dir> is a module installation folder and
494 MODULE is its name. For example, for :sat:{PYCMP} module, at least one file
496 <:sat:{PYCMP}_module_installation_dir>/share/doc/salome/gui/:sat:{PYCMP}/index.html.
498 The SALOME GUI automatically searches for the index.html file in the
499 mentioned module directory. If the file is found, the corresponding
500 menu command is automatically added to the Help menu of the SALOME GUI
503 \ref bin_dir "<< Previous"<br>\ref build_procedure ">> Next"
505 \page build_procedure Construction, installation
507 Before building :sat:{PYCMP} module, please ensure that SALOME environment is
508 set properly. Assume that SALOME environment is set in env_products.sh
509 script. In order to build and install :sat:{PYCMP} module, you have to
510 perform several steps:
513 [bash% ] source env_products.sh
514 [bash% ] mkdir :sat:{PYCMP}_BUILD
515 [bash% ] cd :sat:{PYCMP}_BUILD
516 [bash% ] ../:sat:{PYCMP}1_SRC/build_configure
517 [bash% ] ../:sat:{PYCMP}1_SRC/configure --prefix=<:sat:{PYCMP}_module_installation_dir>
519 [bash% ] make install
522 The first command creates a build directory for the :sat:{PYCMP} module. Then
523 next step is to cd to this build directory. From this directory you
524 sequentially invoke build_configure, configure, make and make install
525 commands. On each step, you have to ensure that the operation is
526 finished correctly (no errors raised).
528 The <:sat:{PYCMP}_module_installation_dir> variable above defines the
529 destination directory to which the :sat:{PYCMP} module should be
530 installed. After the last step is finished, the :sat:{PYCMP} module is built
531 and installed to the <:sat:{PYCMP}_module_installation_dir> directory.
533 \ref doc_dir "<< Previous"<br>\ref run_procedure ">> Next"
535 \page run_procedure Running SALOME
537 Go to the the <:sat:{PYCMP}_module_installation_dir> directory and type:
540 [bash% ] ./bin/salome/runAppli
543 This command runs SALOME session configured for KERNEL and the :sat:{PYCMP}
544 module. At the end of running, the user will be prompted by the
545 Python interpreter command line configured for SALOME that provides
546 access to SALOME Python API (including CORBA interfaces).
548 The runAppli file is a shell script that executes a Python commands
549 running SALOME session by passing arguments to it in a command line:
552 ${KERNEL_ROOT_DIR}/bin/salome/envSalome.py python -i $:sat:{PYCMP}_ROOT_DIR/bin/salome/myrunSalome.py --modules=:sat:{PYCMP} --killall
555 These arguments state that the myrunSalome.py script located in the
556 :sat:{PYCMP} module will be used, that the :sat:{PYCMP} component will be
557 activated and all previously running SALOME sessions should be
560 This command will not function unless the following environment
561 variables have previously been set:
564 export KERNEL_ROOT_DIR=<KERNEL installation path>
565 export :sat:{PYCMP}_ROOT_DIR=<:sat:{PYCMP} installation path>
568 \warning It is possible that the SALOME run will not reach the end.
569 In some circumstances, the time to start CORBA servers may be long and
570 could exceed the timeout. If the reasons is that the time to
571 load dynamic libraries is long, it is possible that a second run
572 immediately afterwards will be successful.
574 \ref build_procedure "<< Previous"<br>\ref load_module ">> Next"
576 \page load_module Loading :sat:{PYCMP} component
578 The :sat:{PYCMP}_ORB module has to be imported before making a request to
579 load the component into the container, to obtain access to methods of
580 the component. This container is made accessible in the runSalome.py
581 by means of the \b container variable:
584 >> import :sat:{PYCMP}_ORB
585 >> c=container.load_impl(":sat:{PYCMP}",":sat:{PYCMP}")
586 >> c.makeBanner("Christian")
589 The last instruction returns a string ":sat:{PYCMP} Christian". Proceed as
590 follows to see the CORBA objects created by these actions:
596 \ref run_procedure "<< Previous"<br>\ref catalog_def ">> Next"
598 \page catalog_def :sat:{PYCMP} module catalog definition
600 In the example from the previous chapter, the :sat:{PYCMP} component was
601 loaded by making a direct request to the SALOME container. This is not
602 the standard method for loading of a component. The normal way uses
603 the SALOME LifeCycle service that invokes SALOME Module Catalog
604 services to identify the component and its properties and then calls
605 the requested container to load the component.
607 Before this method can be used, the component must be declared in a
608 catalog in the XML format, for which the name must be
609 <Module>Catalog.xml. In our case, it will be :sat:{PYCMP}Catalog.xml.
610 Usually this catalog is put to the resources sub-directory of the
611 directory tree. The simplest way to create this file is to use Catalog
612 Generator utility provided by the SALOME KERNEL module, that can
613 automatically generate XML description file from the IDL file.
615 \ref load_module "<< Previous"<br>\ref load_lcc ">> Next"
617 \page load_lcc Loading :sat:{PYCMP} component via LifeCycle service
619 The method of loading the component is not very different from that
620 is described above. The services of the LifeCycle module are used in
621 this case instead of calling the container directly. The call sequence
622 is contained in the runSalome.Py \b test() function.
626 c.makeBanner("Christian")
629 The test function creates the LifeCycle object. It then asks for the
630 :sat:{PYCMP} component to be loaded in the FactoryServer container:
635 Test function that creates an instance of :sat:{PYCMP} component
636 usage : myCompo=test(clt)
638 import LifeCycleCORBA
639 lcc = LifeCycleCORBA.LifeCycleCORBA(clt.orb)
640 import :sat:{PYCMP}_ORB
641 myCompo = lcc.FindOrLoadComponent("FactoryServePy", ":sat:{PYCMP}")
645 \ref catalog_def "<< Previous"<br>\ref load_iapp ">> Next"
647 \page load_iapp Loading from the GUI (IAPP)
649 In order to activate :sat:{PYCMP} module in the SALOME GUI desktop, the user
650 should press the :sat:{PYCMP} module's button on the "Modules" toolbar or
651 select the name of the module in the combo box on this toolbar.
653 The image file to be used as an icon of a module should be exported by
654 the module build procedure. The icon file name is defined in the
655 corresponding SalomeApp.xml configuration file:
657 <section name=":sat:{PYCMP}">
658 <parameter name="name" value=":sat:{PYCMP}"/>
659 <parameter name="icon" value=":sat:{PYCMP}.png"/>
660 <parameter name="library" value="SalomePyQtGUI"/>
664 \ref load_lcc "<< Previous"