3 \mainpage Introduction to PYHELLO sample module
5 The purpose of the \b PYHELLO 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 'Hello' 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
93 + PYHELLOCatalog.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 PYHELLO 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 PYHELLO, the component name is PYHELLO and all the
115 files are put in a directory named PYHELLO1_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_PYHELLO.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/PYHELLO_Gen.idl
150 This is the CORBA IDL definition of the services implemented by SALOME
153 - src/PYHELLO/PYHELLO.py
154 - src/PYHELLO/PYHELLO_utils.py
156 These files provide the implementation of a CORBA engine of the
157 PYHELLO module. In particular, this is an implementation of the
158 services defined in the PYHELLO_Gen.idl file.
160 - src/PYHELLOGUI/PYHELLOGUI.py
162 The src/PYHELLOGUI is an optional directory that provides an
163 implementation of PYHELLO 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/PYHELLOGUI/PYHELLO_msg_en.ts
174 - src/PYHELLOGUI/PYHELLO_icons.ts
176 These files provide a description (internationalization) of GUI
177 resources of the PYHELLO module. PYHELLO_msg_en.ts provides an English
178 translation of the string resources used in a module. PYHELLO_icons.ts
179 defines images and icons resources used within the GUI of the
180 PYHELLO module. Please refer to Qt linguist documentation for more
183 - resources/PYHELLO.png
184 - resources/PYHELLO_small.png
185 - resources/ExecPYHELLO.png
186 - resources/handshake.png
189 The resources folder usually includes different resource files used
190 within the SALOME module. For example, PYHELLO.png file provides an icon
191 of PYHELLO module to be shown in the SALOME GUI desktop. ExecPYHELLO.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 PYHELLO_small.png icon is used to display in the Object
195 browser for root PYHELLO entity.
197 - resources/PYHELLOCatalog.xml.in
199 The XML description of the CORBA services provided by the PYHELLO
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.in
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 ("PYHELLO" in this case) with the following parameters:
213 <section name="PYHELLO">
214 <parameter name="name" value="PyHello"/>
215 <parameter name="icon" value="PYHELLO.png"/>
216 <parameter name="library" value="SalomePyQtGUI"/>
217 <parameter name="version" value="@VERSION@"/>
221 The "name" parameter defines GUI name of a module. The "icon"
222 parameter defines a GUI icon of a module. The parameter "library"
223 specifies the name of the C++ library representing the front-end of
224 the module in the SALOME GUI desktop. The Python modules which do not
225 implement its own C++ front-end GUI library should specify
226 "SalomePyQtGUI" value in this parameter. The "version" parameter
227 defines the version of the module.
229 The section "resources" also specifies the directory that contains
230 resources of a module (icons, translation files, etc).
233 <section name="resources">
234 <parameter name="PYHELLO" value="${PYHELLO_ROOT_DIR}/share/salome/resources/pyhello"/>
238 The section [module_name]_help provides information on the location of
239 the help page and the eventual sub-menu in the Help menu.
242 <section name="pyhello_help" >
243 <parameter name="sub_menu" value="Samples"/>
244 <parameter name="%1 User's Guide" value="%PYHELLO_ROOT_DIR%/share/doc/salome/gui/PYHELLO/index.html"/>
250 The Doxygen configuration file. The Doxygen is used to build this
251 documentation. The file doxyfile.in provides a rules for the
252 generation of module documentation.
256 An input file for the Doxygen, which provides a source of this documentation.
258 \ref dev_steps "<< Previous"<br>\ref build_proc_files ">> Next"
260 \page build_proc_files Build procedure input files
262 SALOME uses autoconf and automake GNU auto-tools to build the
263 modules. The configure script is used for the build procedure to test
264 the system configuration and to pre-configure the module construction
267 The \b build_configure script provides a procedure that uses \b
268 configure.ac and set of \b Makefile.am files as input and uses autoconf
269 to generate the configure script and automake to generate Makefile.in
272 The files with an .in extension are the skeletons that are the input
273 of the configure script (to be more precise, these files should be
274 listed in the end of the configure.ac file in the AC_OUTPUT()
275 autoconf macro) and are transformed by the configure process.
277 Almost all files used for this process are located in the platform
278 base module KERNEL that is referenced by the KERNEL_ROOT_DIR
279 environment variable, namely in its salome_adm sub-folder.
280 Similarly, the GUI_ROOT_DIR environment variable is used for the
281 graphical user interface (GUI), that also provides a set of
282 configuration utilities (m4 files) in its adm_local folder. However,
283 some files must be modified as a function of the target module. This
284 is the case for build_configure and configure.ac files which usually
285 need to be adapted to the module needs.
287 The file \b make_common_starter.am file in the adm_local directory of
288 the example module provides basic build rules to be used in other
289 Makefile.am files. To refer to this file in the Makefile.am it is
290 necessary to use "include" clause:
293 include $(top_srcdir)/adm_local/unix/make_common_starter.am
296 The adm_local/unix/config_files is a directory in which the m4 files
297 that are used to test the configuration of the system in the configure
298 process can be placed. If the salome_adm files are not sufficient,
299 additional configuration files can be put to the adm_local directory.
301 \ref tree_structure "<< Previous"<br>\ref idl_dir ">> Next"
303 \page idl_dir The idl directory
305 The idl directory requires a Makefile.am that must make the
306 compilation of the idl PYHELLO_Gen.idl file and install all the
307 generated files into the correct module installation directories. The
308 BASEIDL_FILES target has to be modified to reach this goal.
310 The idl file itself must define a CORBA module for which the name must
311 be different from the module name to avoid name conflicts and define a
312 CORBA interface that is derived at least from the EngineComponent interface
313 of the Engines module. The name of the CORBA module will be
314 \b PYHELLO_ORB and the name of the interface will be \b PYHELLO_Gen.
316 \ref build_proc_files "<< Previous"<br>\ref src_dir ">> Next"
318 \page src_dir The src directory
320 The src contains all source files required to build and install CORBA
321 engine and (optionally) GUI of the module. Each of these entities usually
322 has (but this is not actually obligatory) its own directory.
324 The Makefile.am simply triggers the path of sub-directories described
325 by the SUBDIRS target.
327 - The src/PYHELLO directory
329 This directory contains the Python files that implement the engine
330 of the module. The Makefile.am defines the rules used to install these
331 files to the destination folder. The name of the module
332 engine Python file is predefined and should be set as <MODULE>.py
333 where <MODULE> is a name of the module. In the case of the PYHELLO
334 module, the name of the engine Python script should be PYHELLO.so.
336 The PYHELLO.py Python script implements PYHELLO class that is derived
337 from the PYHELLO_Gen interface of the PYHELLO_ORB__POA CORBA module,
338 the SALOME_ComponentPy_i class (base implementation of SALOME
339 Python module engine exported by the KERNEL module) and
340 SALOME_DriverPy_i class that provides base implementation of
341 persistence mechanism.
343 In particular, PYHELLO class implements makeBanner() function that is
344 defined in the IDL interface PYHELLO_ORB::PYHELLO_Gen.
347 def makeBanner( self, name ):
348 banner = "Hello %s!" % name
353 defined in PYHELLO_Gen CORBA interface also should be implemented by
356 - The src/PYHELLOGUI directory
358 This directory contains the Python files that implement the GUI
359 of PYHELLO module. The name of the module GUI Python script is
360 predefined and should be set as <MODULE>GUI.py where <MODULE> is a
361 name of the module. In the case of the PYHELLO module, the name of the
362 GUI Python script should be PYHELLOGUI.py.
364 The implementation of GUI of the PYHELLO module should be done
365 according to the architecture and rules specified by the SALOME GUI
366 module. The PYHELLO.py script should implement a set of the functions
367 which define the module behavior in GUI, for example, create menus,
368 toolbars, define context popup menus, objects selection behavior,
369 implement dialog boxes etc.
371 Here below is a short description of these methods. For more details
372 please refer to the SALOME GUI module documentation.
374 - initialize() - module first initialization; usually used to create
375 GUI actions, menus, toolbars and so on;
376 - activate() - module activation; perform actions which should
377 be done when the module is activated by the user;
378 - deactivate() - module deactivation; perform actions which should
379 be done when the module is deactivated by the user;
380 - windows() - get a list and a position of the windows to be
381 associated with the module; these windows will be automatically
382 opened and positioned according to the setting defined by the value
383 returned by this function;
384 - views() - get a list of the compatible viewers; these viewers
385 will be automatically opened/raised on the module activation;
386 - createPopupMenu() - create and return context popup menu according
387 to the current selection;
388 - createPreferences() - initialize module's preferences;
389 - preferenceChanged() - callback function that is called when some
390 module's preference is changed by the user; allows to perform the
391 corresponding actions;
392 - engineIOR() - to get the reference to the module CORBA engine
394 Note, that some of these methods are optional and need not be
395 obligatory implemented because SalomePyQtGUI_Module class provides a
396 base implementation of these functions. It's sometimes enough to
397 implement only some of them, depending on the module needs.
399 In the case of PYHELLO module, some of these functions are
400 implemented to provide a sample for the development:
402 - engineIOR() that initializes PYHELLO module's eggine:
407 if getORB() and getEngine():
408 IOR = getORB().object_to_string( getEngine() )
413 - initialize() that sets default module preferences
417 if not sgPyQt.hasSetting( "PYHELLO", "def_obj_name"):
418 sgPyQt.addSetting( "PYHELLO", "def_obj_name", GUIcontext.DEFAULT_NAME )
419 if not sgPyQt.hasSetting( "PYHELLO", "creation_mode"):
420 sgPyQt.addSetting( "PYHELLO", "creation_mode", 0 )
423 - createPreferences() that initializes module preferences for the
424 application's Preferences dialog box
427 def createPreferences():
428 if verbose() : print "PYHELLOGUI.createPreferences() : study : %d" % _getStudyId()
429 gid = sgPyQt.addPreference( "General" )
430 gid = sgPyQt.addPreference( "Object creation", gid )
431 pid = sgPyQt.addPreference( "Default name", gid, SalomePyQt.PT_String, "PYHELLO", "def_obj_name" )
432 pid = sgPyQt.addPreference( "Default creation mode", gid, SalomePyQt.PT_Selector, "PYHELLO", "creation_mode" )
433 strings = QStringList()
434 strings.append( "Default name" )
435 strings.append( "Generate name" )
436 strings.append( "Ask name" )
438 indexes.append( QVariant(0) )
439 indexes.append( QVariant(1) )
440 indexes.append( QVariant(2) )
441 sgPyQt.setPreferenceProperty( pid, "strings", QVariant( strings ) )
442 sgPyQt.setPreferenceProperty( pid, "indexes", QVariant( indexes ) )
446 - windows() that defines dockable windows layout
450 if verbose() : print "PYHELLOGUI.windows() : study : %d" % _getStudyId()
452 wm[SalomePyQt.WT_ObjectBrowser] = Qt.LeftDockWidgetArea
453 wm[SalomePyQt.WT_PyConsole] = Qt.BottomDockWidgetArea
457 Please refer to PYHELLOGUI.py script for more details about
458 implementation of other callback functions.
460 An implemention of the ShowHello() function is quite simple. It shows
461 the small dialog box allowing user to enter the name, and then uses
462 reference to the module CORBA engine to invoke its makeBanner()
465 Note, that GUI elements of the Python module are implemented with help
466 of PyQt toolkit which provides a Python wrappings of the Qt library.
468 \ref idl_dir "<< Previous"<br>\ref bin_dir ">> Next"
470 \page bin_dir The bin directory
472 The file VERSION.in is used to document the module, it must define its
473 version and (optionally) its compatibilities or incompatibilities with
474 other modules. Therefore, it is strongly recommended but is not
475 essential for correct operation of the module.
477 The runAppli.in file is the equivalent of the runSalome script
478 distributed by the KERNEL module but configured to start SALOME
479 session with PYHELLO module only.
481 The myrunSalome.py file reuses part of functionality provided by the
482 KERNEL's runSalome.py script. It is used to run SALOME session and
483 start PYHELLO module in this session.
485 \ref src_dir "<< Previous"<br>\ref doc_dir ">> Next"
487 \page doc_dir The doc directory
489 This directory provides documentation files of the module. The
490 documentation of the module can be implemented in the arbitrary
491 way. But if you want your documentation to appear in the SALOME GUI
492 desktop's Help menu, some specific actions should be done as follows.
494 The documentation should be generated in the HTML format. For example,
495 the documentation of the PYHELLO module is generated using Doxygen
496 tool. It allows to generate structured set of HTML pages from the set
497 of input plain text files. Input source files should include Doxygen
498 tags and optionally direct HTML tags. For more details please refer to
499 the Doxygen documentation.
501 The resulting documentation of a module should include at least one
502 file index.html. All the HTML and image files should be exported by
503 the build procedure to the following directory:
504 <module_installation_dir>/share/doc/salome/gui/<MODULE>
505 where <module_installation_dir> is a module installation folder and
506 MODULE is its name. For example, for PYHELLO module, at least one file
508 <PYHELLO_module_installation_dir>/share/doc/salome/gui/PYHELLO/index.html.
510 The SALOME GUI automatically searches for the index.html file in the
511 mentioned module directory. If the file is found, the corresponding
512 menu command is automatically added to the Help menu of the SALOME GUI
515 \ref bin_dir "<< Previous"<br>\ref build_procedure ">> Next"
517 \page build_procedure Construction, installation
519 Before building PYHELLO module, please ensure that SALOME environment is
520 set properly. Assume that SALOME environment is set in env_products.sh
521 script. In order to build and install PYHELLO module, you have to
522 perform several steps:
525 [bash% ] source env_products.sh
526 [bash% ] mkdir PYHELLO_BUILD
527 [bash% ] cd PYHELLO_BUILD
528 [bash% ] ../PYHELLO1_SRC/build_configure
529 [bash% ] ../PYHELLO1_SRC/configure --prefix=<PYHELLO_module_installation_dir>
531 [bash% ] make install
534 The first command creates a build directory for the PYHELLO module. Then
535 next step is to cd to this build directory. From this directory you
536 sequentially invoke build_configure, configure, make and make install
537 commands. On each step, you have to ensure that the operation is
538 finished correctly (no errors raised).
540 The <PYHELLO_module_installation_dir> variable above defines the
541 destination directory to which the PYHELLO module should be
542 installed. After the last step is finished, the PYHELLO module is built
543 and installed to the <PYHELLO_module_installation_dir> directory.
545 \ref doc_dir "<< Previous"<br>\ref run_procedure ">> Next"
547 \page run_procedure Running SALOME
549 Go to the the <PYHELLO_module_installation_dir> directory and type:
552 [bash% ] ./bin/salome/runAppli
555 This command runs SALOME session configured for KERNEL and the PYHELLO
556 module. At the end of running, the user will be prompted by the
557 Python interpreter command line configured for SALOME that provides
558 access to SALOME Python API (including CORBA interfaces).
560 The runAppli file is a shell script that executes a Python commands
561 running SALOME session by passing arguments to it in a command line:
564 ${KERNEL_ROOT_DIR}/bin/salome/envSalome.py python -i $PYHELLO_ROOT_DIR/bin/salome/myrunSalome.py --modules=PYHELLO --killall
567 These arguments state that the myrunSalome.py script located in the
568 PYHELLO module will be used, that the PYHELLO component will be
569 activated and all previously running SALOME sessions should be
572 This command will not function unless the following environment
573 variables have previously been set:
576 export KERNEL_ROOT_DIR=<KERNEL_module_installation_dir>
577 export PYHELLO_ROOT_DIR=<PYHELLO_module_installation_dir>
580 \warning It is possible that the SALOME run will not reach the end.
581 In some circumstances, the time to start CORBA servers may be long and
582 could exceed the timeout. If the reasons is that the time to
583 load dynamic libraries is long, it is possible that a second run
584 immediately afterwards will be successful.
586 \ref build_procedure "<< Previous"<br>\ref load_module ">> Next"
588 \page load_module Loading PYHELLO component
590 The PYHELLO_ORB module has to be imported before making a request to
591 load the component into the container, to obtain access to methods of
592 the component. This container is made accessible in the myrunSalome.py
593 by means of the \b container variable:
596 >> import PYHELLO_ORB
597 >> c=container.load_impl("PYHELLO","PYHELLO")
598 >> c.makeBanner("Christian")
601 The last instruction returns a string "Hello Christian". Proceed as
602 follows to see the CORBA objects created by these actions:
608 \ref run_procedure "<< Previous"<br>\ref catalog_def ">> Next"
610 \page catalog_def PYHELLO module catalog definition
612 In the example from the previous chapter, the PYHELLO component was
613 loaded by making a direct request to the SALOME container. This is not
614 the standard method for loading of a component. The normal way uses
615 the SALOME LifeCycle service that invokes SALOME Module Catalog
616 services to identify the component and its properties and then calls
617 the requested container to load the component.
619 Before this method can be used, the component must be declared in a
620 catalog in the XML format, for which the name must be
621 <Module>Catalog.xml. In our case, it will be PYHELLOCatalog.xml.
622 Usually this catalog is put to the resources sub-directory of the
623 directory tree. The simplest way to create this file is to use Catalog
624 Generator utility provided by the SALOME KERNEL module, that can
625 automatically generate XML description file from the IDL file.
627 \ref load_module "<< Previous"<br>\ref load_lcc ">> Next"
629 \page load_lcc Loading PYHELLO component via LifeCycle service
631 The method of loading the component is not very different from that
632 is described above. The services of the LifeCycle module are used in
633 this case instead of calling the container directly. The call sequence
634 is contained in the myrunSalome.py \b test() function.
638 c.makeBanner("Christian")
641 The test function creates the LifeCycle object. It then asks for the
642 PYHELLO component to be loaded in the FactoryServer container:
647 Test function that creates an instance of PYHELLO component
648 usage : hello=test(clt)
650 import LifeCycleCORBA
651 lcc = LifeCycleCORBA.LifeCycleCORBA(clt.orb)
653 pyhello = lcc.FindOrLoadComponent("FactoryServePy", "PYHELLO")
657 \ref catalog_def "<< Previous"<br>\ref load_iapp ">> Next"
659 \page load_iapp Loading from the GUI (IAPP)
661 In order to activate PYHELLO module in the SALOME GUI desktop, the user
662 should press the PYHELLO module's button on the "Modules" toolbar or
663 select the name of the module in the combo box on this toolbar.
665 The image file to be used as an icon of a module should be exported by
666 the module build procedure. The icon file name is defined in the
667 corresponding SalomeApp.xml configuration file:
669 <section name="PYHELLO">
670 <parameter name="name" value="Hello"/>
671 <parameter name="icon" value="PYHELLO.png"/>
672 <parameter name="library" value="SalomePyQtGUI"/>
676 \ref load_lcc "<< Previous"