+++ /dev/null
-
-.. _pysalome:
-
-================================================================
-Guide for the development of a SALOME module in Python
-================================================================
-
-The purpose of this document is to describe briefly the different steps in the development of a SALOME module
-in Python.
-
-Steps in construction of the example module
-====================================================
-The example module chosen to illustrate the process to construct a module is extremely simple.
-It will contain a single component and this component will have a single service called getBanner that
-will accept a character string as the sole argument and that will return a character string obtained by
-concatenation of “Hello” and the input chain. This component will be completed by a graphic GUI written in PyQt.
-
-The different steps in the development will be as follows:
-
- - create a module tree structure
- - create a SALOME component that can be loaded by a Python container
- - configure the module so that the component is known to SALOME
- - add a graphic GUI
-
-Create the module tree structure
-=======================================
-Firstly, we will simply put a SALOME component written in Python and that can be loaded by a Python
-container, into the example module. An idl interface and a Python implementation of the component will be
-all that are necessary.
-The following file structure is necessary so that this can be implemented in a SALOME module::
-
- + PYHELLO1_SRC
- + build_configure
- + configure.ac
- + Makefile.am
- + adm_local
- + Makefile.am
- + unix
- + Makefile.am
- + make_common_starter.am
- + config_files
- + Makefile.am
- + check_PYHELLO.m4
- + bin
- + Makefile.am
- + VERSION.in
- + runAppli.in
- + myrunSalome.py
- + idl
- + Makefile.am
- + PYHELLO_Gen.idl
- + src
- + Makefile.am
- + PYHELLO
- + Makefile.am
- + PYHELLO.py
- + doc
-
-The module name is PYHELLO, the component name is PYHELLO and all the files will be put in a directory named PYHELLO1_SRC.
-All files are essential except for VERSION.in, runAppli.in and runSalome.py.
-VERSION.in is used to document the module, it must give its version and its compatibilities or
-incompatibilities with other modules. Therefore, it is strongly recommended but is not essential for operation.
-The runAppli.in and runSalome.py files are not essential but make the example easier to use.
-
-**Warning**: the files of the basic platform (KERNEL) must not be copied to initialise a module tree structure.
-It is usually preferable to copy files from another module such as GEOM or MED.
-
-Implementation of automake, configure
---------------------------------------
-SALOME uses autoconf and automake to build the configure script that is used for the installation to test
-the system configuration and to preconfigure the module construction Makefile files.
-The build_configure file contains a procedure that starts from configure.ac and uses automake to build
-the configure script.
-automake starts from Makefile.am files to build Makefile.in files.
-All files with an "in" extension are skeletons that will be transformed by the configure process.
-
-Almost all files used for this process are located in the basic platform that is referenced by the
-KERNEL_ROOT_DIR environment variable as well as GUI_ROOT_DIR for the graphical user interface (GUI).
-However, some files must be modified as a function of the target
-module. This is the case for build_configure and configure.ac files that usually need to be adapted.
-
-The basic files for configuration of the KERNEL module and other modules are collected in the salome_adm
-directory of the KERNEL module. However, in order to be able to use the CORBA objects of the KERNEL module,
-the files in the salome_adm directory have to be overwritten, using the make_common_starter.am file in
-the adm_local directory of the example module.
-
-config_files is a directory in which the m4 files that are used to test the configuration of the system in the
-configure process can be placed. If the salome_adm files are not sufficient, others can be added in adm_local.
-
-The idl directory
---------------------------------------
-The idl directory requires a Makefile.am that must make the compilation of the idl PYHELLO_Gen.idl file
-and install all the generated files in the right module installation directories. The BASE_IDL_FILES target has
-to be modified to reach this goal.
-
-The idl file itself must define a CORBA module for which the name must be different from the module
-name to avoid name conflicts and define a CORBA interface that is derived at least from the Component interface
-of the Engines module.
-The name of the CORBA module will be PYHELLO_ORB and the name of the interface will be PYHELLO_Gen.
-
-The src directory
---------------------------------------
-The src directory will contain all components and the GUI for the module. Each of these entities must have
-its own directory.
-
-For the moment, the module will only contain a single directory for the engine of the PYHELLO component
-and its name will be PYHELLO.
-
-The Makefile.am will simply trigger the path of sub-directories described by the SUBDIRS target.
-
-The PYHELLO directory
-'''''''''''''''''''''''
-This directory contains the Python module that represents the component and therefore contains the PYHELLO class
-and a Makefile.am file that simply exports the PYHELLO.py module into the installation directory of the SALOME module.
-
-The PYHELLO.py module contains the PYHELLO class that is derived from the PYHELLO_Gen interface of the CORBA
-PYHELLO_ORB_POA module and the SALOME_ComponentPy_i class of the SALOME_ComponentPy module.
-
-The doc directory
---------------------------------------
-This contains nothing for the moment. It could contain this document.
-
-The bin directory
---------------------------------------
-VERSION.in is used to document the module, it must define its version and its compatibilities
-or incompatibilities with other modules. Therefore, it is strongly recommended but is not essential for operation.
-
-The runAppli.in file is the equivalent of the runSalome in the KERNEL module configured to implement the KERNEL
-module and this PYHELLO module.
-
-The myrunSalome.py file is the file of the KERNEL module modified to run only with a Python container,
-with the test function that creates the PYHELLO component instead of a MED component,
-and automatic completion in Python.
-
-Creating a component that can be loaded by a container
-======================================================
-The files presented above are sufficient to build and install the PYHELLO1_SRC module, to start
-the SALOME platform composed of the KERNEL and PYHELLO1 modules, and to request the Python container
-to load a PYHELLO component.
-
-All the following steps are only possible if the SALOME prerequisite software is accessible in the module
-developer environment.
-
-Construction, installation
----------------------------------
-In PYHELLO1_SRC, enter::
-
- export KERNEL_ROOT_DIR=<KERNEL installation path>
- ./build_configure
-
-Go into ../PYHELLO1_BUILD and enter::
-
- ../PYHELLO1_SRC/configure --prefix=<PYHELLO1 installation path>
- make
- make install
-
-Running the platform
--------------------------------
-Move into the <PYHELLO1 module installation path> and enter::
-
- ./bin/salome/runAppli
-
-This command runs SALOME configured for KERNEL and the PYHELLO1 module. At the end of running,
-the user sees a Python interpreter configured for SALOME that provides access to SALOME CORBA objects.
-
-runAppli is a shell that executes a Python script, by passing arguments to it in a command line::
-
- python -i $PYHELLO_ROOT_DIR/bin/salome/myrunSalome.py --modules=PYHELLO --killall
-
-These arguments state that the myrunSalome.py script located in the PYHELLO module will be used, that the PYHELLO
-component will be activated and all SALOME processes that existed before the run will be killed.
-
-This command will not function unless the following environment variables have previously been set::
-
- export KERNEL_ROOT_DIR=<KERNEL installation path>
- export PYHELLO_ROOT_DIR=<PYHELLO installation path>
-
-**Warning**: it is possible that the SALOME run will not reach the end. In some circumstances, the time to
-start CORBA servers may be long and could exceed the timeout. If the reason for
-this is that the time to load dynamic libraries is long, it is possible that a second run immediately
-afterwards will be successful.
-
-Loading the example component
-------------------------------------
-The PYHELLO_ORB module has to be imported before making a request to load the component into the Python
-container, to obtain access to methods of the component. This Python container was made accessible
-in the runSalome.py by means of the container variable::
-
- import PYHELLO_ORB
- c=container.load_impl("PYHELLO","PYHELLO")
- c.makeBanner("Christian")
-
-The last instruction must return ‘Hello Christian’.
-
-Proceed as follows to see CORBA objects created by these actions::
-
- clt.showNS()
-
-Declared SALOME component
-==============================
-For the moment, the PYHELLO component was loaded by making a direct request to the Python container. This is
-not the standard method for loading a component. The normal method uses the LifeCycle service that uses
-catalog services to identify the component and its properties and then calls the requested container to load the component.
-
-Before this method can be used, the component must be declared in a catalog in the XML format, for which
-the name must be <Module>Catalog.xml. In our case, it will be PYHELLOCatalog.xml. This catalog will be stored in
-the resources directory.
-
-Updated tree structure::
-
- + PYHELLO1_SRC
- + build_configure
- + configure.ac
- + Makefile.am
- + adm_local
- + bin
- + idl
- + src
- + doc
- + resources
- + PYHELLOCatalog.xml
-
-The remainder of the files are identical, apart from adding the resources directory and the PYHELLOCatalog.xml file.
-However, the Makefile.am has to be modified so that the catalog is actually installed in the installation
-directory. It simply needs to be specified in the salomeres_SCRIPTS target.
-
-Construction, installation
----------------------------------
-There is no need to do another configure to take account of this modification.
-All that is necessary is to enter PYHELLO1_BUILD and then::
-
- ./config.status
- make
- make install
-
-Starting the platform
--------------------------------
-The platform is started in the same way as before. Go into PYHELLO1_INSTALL and do::
-
- ./bin/salome/runAppli
-
-Loading the example component
-------------------------------------
-The method of loading the component is not very different from that described above. The services of the
-LifeCycle module are used in this case instead of calling the container directly.
-The call sequence is contained in the runSalome.Py test function. ::
-
- c=test(clt)
- c.makeBanner("Christian")
-
-The test function creates the LifeCycle. It then asks for the PYHELLO component to be loaded in the FactoryServerPy container::
-
- def test(clt):
- """
- Test function that creates an instance of PYHELLO component
- usage : pyhello=test(clt)
- """
- import LifeCycleCORBA
- lcc = LifeCycleCORBA.LifeCycleCORBA(clt.orb)
- import PYHELLO_ORB
- pyhello = lcc.FindOrLoadComponent("FactoryServerPy", "PYHELLO")
- return pyhello
-
-Loading from the application interface (IAPP)
-----------------------------------------------------------
-Before a component can be loaded dynamically using the IAPP components bar, the icon representing the
-component will have to be declared in the catalog.
-It is declared by simply adding a line for the icon to the component catalog::
-
- <component-icon>PYHELLO.png</component-icon>
-
-and putting the corresponding file in the module resources directory.
-
-Adding a graphic GUI
-===========================
-The next step to complete the module consists of adding a graphic interface to the PYHELLO component, that will
-be written in Python using the Qt widgets library. This graphic interface must be integrated into the SALOME
-application interface (IAPP), and therefore must respect some constraints that we will see.
-
-Firstly note the contour of the GUI of a component. The behaviour of the GUI is given by a Python module
-that has a standard name <Module>GUI.py. It must propose conventional entry points that the IAPP will use to
-activate this GUI or to inform it of specific events. GUI commands are activated through a menu bar and a
-button bar that are integrated into the menu bar and into the IAPP button bar.
-
-Python module implanting the behaviour of the GUI
------------------------------------------------------
-The behaviour of the PYHELLO component GUI is implanted in the Python PYHELLOGUI.py module in the
-PYHELLOGUI sub-directory. The Makefile.am located in the src directory must be updated to include
-the PYHELLOGUI subdirectory. A Makefile.am must be added into the PYHELLOGUI subdirectory.
-Important targets are salomescript_SCRIPTS and salomeres_DATA.
-
-The salomescript_SCRIPTS target must be updated with the name of the Python modules to be made visible in Salome, in other
-words mainly so that they are importable (Python import command).
-
-The salomeres_DATA target must be updated with the names of files that are used for multi-linguism.
-
-Menu bar and button bar
-----------------------------------
-The menu bar and button bar for the PYHELLO component are dynamically added when importing the PYHELLOGUI module.
-They are created by calling the Python functions createMenu, createAction and createTool from the sgPyQt SALOME
-interface object. Every action must have a unique id.
-Some icons are used. They must be installed in the resources directory.
-
--- /dev/null
+/*!
+
+\mainpage Introduction to PYHELLO sample module
+
+The purpose of the \b PYHELLO module is to describe briefly the different
+steps in the development of a SALOME module in Python.
+
+Contents:
+- \subpage dev_steps
+- \subpage tree_structure
+- \subpage build_proc_files
+- \subpage idl_dir
+- \subpage src_dir
+- \subpage bin_dir
+- \subpage doc_dir
+- \subpage build_procedure
+- \subpage run_procedure
+- \subpage load_module
+- \subpage catalog_def
+- \subpage load_lcc
+- \subpage load_iapp
+
+\ref dev_steps ">> Next"
+
+\page dev_steps Steps in construction of the example module
+
+The example module chosen to illustrate the process of SALOME module
+development is extremely simple. The module contains a single
+component and this component provides a single service called \b
+makeBanner that accepts a character string as the sole argument and
+that returns a character string obtained by the concatenation of a
+'Hello' and the input string. The component also provides a simple
+GUI.
+
+The steps in the development are as follows:
+- create a module tree structure
+- create a SALOME component that can be loaded by a Python SALOME container
+- configure the module so that the component is known to SALOME
+- add a graphic GUI
+
+\ref main "<< Previous"<br>\ref tree_structure ">> Next"
+
+\page tree_structure Create the module tree structure
+
+The first step in the development process is the creation of the
+module tree file structure. The typical SALOME module usually includes
+some set of the configuration files (used in the build procedure of a
+module), Makefiles, IDL file that provides a definition of a CORBA
+services implemented in a module and a set of source Python files
+which implement the module CORBA engine and (optionally) its GUI.
+
+The following file structure is typical for the SALOME module:
+
+<pre>
++ PYHELLO1_SRC
+ + build_configure
+ + configure.ac
+ + Makefile.am
+ + adm_local
+ + Makefile.am
+ + unix
+ + Makefile.am
+ + make_common_starter.am
+ + config_files
+ + Makefile.am
+ + check_PYHELLO.m4
+ + bin
+ + Makefile.am
+ + VERSION.in
+ + runAppli.in
+ + myrunSalome.py
+ + idl
+ + Makefile.am
+ + PYHELLO_Gen.idl
+ + src
+ + Makefile.am
+ + PYHELLO
+ + Makefile.am
+ + PYHELLO.py
+ + PYHELLO_utils.py
+ + PYHELLOGUI
+ + Makefile.am
+ + PYHELLOGUI.py
+ + PYHELLO_msg_en.ts
+ + PYHELLO_icons.ts
+ + resources
+ + Makefile.am
+ + PYHELLO.png
+ + PYHELLO_small.png
+ + ExecPYHELLO.png
+ + handshake.png
+ + stop.png
+ + PYHELLOCatalog.xml.in
+ + SalomeApp.xml
+ + doc
+ + Makefile.am
+ + doxyfile.in
+ + index.doc
+</pre>
+
+Note that other files can be optionally present. For example, in some
+SALOME modules sources tree you can find such files as AUTHORS,
+INSTALL, ChangeLog, COPYING, NEWS, README, etc. Some files are
+specific only for this PYHELLO sample module, for example PNG images
+in the resources directory which are used in the GUI dialog boxes etc.
+
+The usual way of the sources directory tree structure initial creation
+is to copy it from the existing SALOME module.
+
+\warning The files of the platform base module (KERNEL) must not be
+copied to initialise a module tree structure. It is usually preferable
+to copy files from another module such as GEOM or MED.
+
+The module name is PYHELLO, the component name is PYHELLO and all the
+files are put in a directory named PYHELLO1_SRC.
+Below is a short description of these files. Note, that files with .in
+suffix are the autoconf templates from which the actual files are
+generated during the build procedure.
+
+- build_configure, configure.ac, Makefile.am, make_common_starter.am
+
+These files are a part of the build system based on GNU
+automake/autoconf auto-tools. These files define the build procedure,
+namely, compilation and installation rules like compiler and linker
+options, installation destination folder, package version etc.
+
+- adm_local/unix/config_files/check_PYHELLO.m4
+
+The files in this directory are also a part of the GNU auto-tools
+-based build procedure. The scripts written in m4 language are usually
+used to test an availability of some 3rd-party pre-requisite product,
+compiler feature, different configuration options.
+
+- bin/VERSION.in
+
+This file is used to document the module, it must give its version (at
+least) and (optionally) compatibilities or incompatibilities with
+other modules. This file is strongly recommended but is not essential
+for operation of the module.
+
+- bin/runAppli.in
+- bin/runSalome.py
+
+These files are not essential but make the example easier to
+use. These are scripts that can be used to run SALOME session with
+PYHELLO module.
+
+- idl/PYHELLO_Gen.idl
+
+This is the CORBA IDL definition of the services implemented by SALOME
+PYHELLO module.
+
+- src/PYHELLO/PYHELLO.py
+- src/PYHELLO/PYHELLO_utils.py
+
+These files provide the implementation of a CORBA engine of the
+PYHELLO module. In particular, this is an implementation of the
+services defined in the PYHELLO_Gen.idl file.
+
+- src/PYHELLOGUI/PYHELLOGUI.py
+
+The src/PYHELLOGUI is an optional directory that provides an
+implementation of PYHELLO module's GUI. Strictly speaking, the
+GUI is optional for each SALOME module. In some cases it's
+enough to implement CORBA engine only. Then, the services of the
+module will be avaiable in a CORBA environment. The module can be
+loaded to the SALOME container and its services can be used in the
+Supervisor computation schemas, in Python scripts or/and refer to it
+in other modules. A GUI is necessary in the cases if it is planned to
+access to the module functionality from the SALOME GUI session via
+menu actions, dialog boxes and so on.
+
+- src/PYHELLOGUI/PYHELLO_msg_en.ts
+- src/PYHELLOGUI/PYHELLO_icons.ts
+
+These files provide a description (internationalization) of GUI
+resources of the PYHELLO module. PYHELLO_msg_en.ts provides an English
+translation of the string resources used in a module. PYHELLO_icons.ts
+defines images and icons resources used within the GUI of the
+PYHELLO module. Please refer to Qt linguist documentation for more
+details.
+
+- resources/PYHELLO.png
+- resources/PYHELLO_small.png
+- resources/ExecPYHELLO.png
+- resources/handshake.png
+- resources/stop.png
+
+The resources folder usually includes different resource files used
+within the SALOME module. For example, PYHELLO.png file provides an icon
+of PYHELLO module to be shown in the SALOME GUI desktop. ExecPYHELLO.png is
+an icon for the makeBanner() function used in the menu and
+toolbar. The icons handshake.png and stop.png are used in the dialog
+boxes and PYHELLO_small.png icon is used to display in the Object
+browser for root PYHELLO entity.
+
+- resources/PYHELLOCatalog.xml.in
+
+The XML description of the CORBA services provided by the PYHELLO
+module. This file is parsed by Supervisor and YACS module to generate
+the list of service nodes to be used in the calculation schemas. The
+simplest way to create this file is to use Catalog Generator utility
+provided by the SALOME KERNEL module, that can automatically generate
+XML description file from the IDL file.
+
+- resources/SalomeApp.xml
+
+This file is essential for the module. It provides some parameters of
+the module which define module behavior in SALOME. In particular it
+should provide a section with the name corresponding to the name of a
+module ("PYHELLO" in this case) with the following parameters:
+\code
+ <section name="PYHELLO">
+ <parameter name="name" value="PyHello"/>
+ <parameter name="icon" value="PYHELLO.png"/>
+ <parameter name="library" value="SalomePyQtGUI"/>
+ </section>
+\endcode
+
+The "name" parameter defines GUI name of a module. The "icon"
+parameter defines a GUI icon of a module. The parameter "library"
+specifies the name of the C++ library representing the front-end of
+the module in the SALOME GUI desktop. The Python modules which do not
+implement its own C++ front-end GUI library should specify
+"SalomePyQtGUI" value in this parameter.
+
+The section "resources" also specifies the directory that contains
+resources of a module (icons, translation files, etc).
+
+\code
+ <section name="resources">
+ <parameter name="PYHELLO" value="${PYHELLO_ROOT_DIR}/share/salome/resources/pyhello"/>
+ </section>
+\endcode
+
+- doc/doxyfile.in
+
+The Doxygen configuration file. The Doxygen is used to build this
+documentation. The file doxyfile.in provides a rules for the
+generation of module documentation.
+
+- doc/index.doc
+
+An input file for the Doxygen, which provides a source of this documentation.
+
+\ref dev_steps "<< Previous"<br>\ref build_proc_files ">> Next"
+
+\page build_proc_files Build procedure input files
+
+SALOME uses autoconf and automake GNU auto-tools to build the
+modules. The configure script is used for the build procedure to test
+the system configuration and to pre-configure the module construction
+Makefile files.
+
+The \b build_configure script provides a procedure that uses \b
+configure.ac and set of \b Makefile.am files as input and uses autoconf
+to generate the configure script and automake to generate Makefile.in
+files.
+
+The files with an .in extension are the skeletons that are the input
+of the configure script (to be more precise, these files should be
+listed in the end of the configure.ac file in the AC_OUTPUT()
+autoconf macro) and are transformed by the configure process.
+
+Almost all files used for this process are located in the platform
+base module KERNEL that is referenced by the KERNEL_ROOT_DIR
+environment variable, namely in its salome_adm sub-folder.
+Similarly, the GUI_ROOT_DIR environment variable is used for the
+graphical user interface (GUI), that also provides a set of
+configuration utilities (m4 files) in its adm_local folder. However,
+some files must be modified as a function of the target module. This
+is the case for build_configure and configure.ac files which usually
+need to be adapted to the module needs.
+
+The file \b make_common_starter.am file in the adm_local directory of
+the example module provides basic build rules to be used in other
+Makefile.am files. To refer to this file in the Makefile.am it is
+necessary to use "include" clause:
+
+\code
+include $(top_srcdir)/adm_local/unix/make_common_starter.am
+\endcode
+
+The adm_local/unix/config_files is a directory in which the m4 files
+that are used to test the configuration of the system in the configure
+process can be placed. If the salome_adm files are not sufficient,
+additional configuration files can be put to the adm_local directory.
+
+\ref tree_structure "<< Previous"<br>\ref idl_dir ">> Next"
+
+\page idl_dir The idl directory
+
+The idl directory requires a Makefile.am that must make the
+compilation of the idl PYHELLO_Gen.idl file and install all the
+generated files into the correct module installation directories. The
+BASEIDL_FILES target has to be modified to reach this goal.
+
+The idl file itself must define a CORBA module for which the name must
+be different from the module name to avoid name conflicts and define a
+CORBA interface that is derived at least from the Component interface
+of the Engines module. The name of the CORBA module will be
+\b PYHELLO_ORB and the name of the interface will be \b PYHELLO_Gen.
+
+\ref build_proc_files "<< Previous"<br>\ref src_dir ">> Next"
+
+\page src_dir The src directory
+
+The src contains all source files required to build and install CORBA
+engine and (optionally) GUI of the module. Each of these entities usually
+has (but this is not actually obligatory) its own directory.
+
+The Makefile.am simply triggers the path of sub-directories described
+by the SUBDIRS target.
+
+- The src/PYHELLO directory
+
+This directory contains the Python files that implement the engine
+of the module. The Makefile.am defines the rules used to install these
+files to the destination folder. The name of the module
+engine Python file is predefined and should be set as <MODULE>.py
+where <MODULE> is a name of the module. In the case of the PYHELLO
+module, the name of the engine Python script should be PYHELLO.so.
+
+The PYHELLO.py Python script implements PYHELLO class that is derived
+from the PYHELLO_Gen interface of the PYHELLO_ORB__POA CORBA module,
+the SALOME_ComponentPy_i class (base implementation of SALOME
+Python module engine exported by the KERNEL module) and
+SALOME_DriverPy_i class that provides base implementation of
+persistence mechanism.
+
+In particular, PYHELLO class implements makeBanner() function that is
+defined in the IDL interface PYHELLO_ORB::PYHELLO_Gen.
+
+\code
+def makeBanner( self, name ):
+ banner = "Hello %s!" % name
+ return banner
+\endcode
+
+Other services
+defined in PYHELLO_Gen CORBA interface also should be implemented by
+this class.
+
+- The src/PYHELLOGUI directory
+
+This directory contains the Python files that implement the GUI
+of PYHELLO module. The name of the module GUI Python script is
+predefined and should be set as <MODULE>GUI.py where <MODULE> is a
+name of the module. In the case of the PYHELLO module, the name of the
+GUI Python script should be PYHELLOGUI.py.
+
+The implementation of GUI of the PYHELLO module should be done
+according to the architecture and rules specified by the SALOME GUI
+module. The PYHELLO.py script should implement a set of the functions
+which define the module behavior in GUI, for example, create menus,
+toolbars, define context popup menus, objects selection behavior,
+implement dialog boxes etc.
+
+Here below is a short description of these methods. For more details
+please refer to the SALOME GUI module documentation.
+
+- initialize() - module first initialization; usually used to create
+ GUI actions, menus, toolbars and so on;
+- activate() - module activation; perform actions which should
+ be done when the module is activated by the user;
+- deactivate() - module deactivation; perform actions which should
+ be done when the module is deactivated by the user;
+- windows() - get a list and a position of the windows to be
+ associated with the module; these windows will be automatically
+ opened and positioned according to the setting defined by the value
+ returned by this function;
+- views() - get a list of the compatible viewers; these viewers
+ will be automatically opened/raised on the module activation;
+- createPopupMenu() - create and return context popup menu according
+ to the current selection;
+- createPreferences() - initialize module's preferences;
+- preferenceChanged() - callback function that is called when some
+ module's preference is changed by the user; allows to perform the
+ corresponding actions;
+- engineIOR() - to get the reference to the module CORBA engine
+
+Note, that some of these methods are optional and need not be
+obligatory implemented because SalomePyQtGUI_Module class provides a
+base implementation of these functions. It's sometimes enough to
+implement only some of them, depending on the module needs.
+
+In the case of PYHELLO module, some of these functions are
+implemented to provide a sample for the development:
+
+- engineIOR() that initializes PYHELLO module's eggine:
+
+\code
+def engineIOR():
+ IOR = ""
+ if getORB() and getEngine():
+ IOR = getORB().object_to_string( getEngine() )
+ pass
+ return IOR
+\endcode
+
+- initialize() that sets default module preferences
+
+\code
+def initialize():
+ if not sgPyQt.hasSetting( "PYHELLO", "def_obj_name"):
+ sgPyQt.addSetting( "PYHELLO", "def_obj_name", GUIcontext.DEFAULT_NAME )
+ if not sgPyQt.hasSetting( "PYHELLO", "creation_mode"):
+ sgPyQt.addSetting( "PYHELLO", "creation_mode", 0 )
+\endcode
+
+- createPreferences() that initializes module preferences for the
+ application's Preferences dialog box
+
+\code
+def createPreferences():
+ if verbose() : print "PYHELLOGUI.createPreferences() : study : %d" % _getStudyId()
+ gid = sgPyQt.addPreference( "General" )
+ gid = sgPyQt.addPreference( "Object creation", gid )
+ pid = sgPyQt.addPreference( "Default name", gid, SalomePyQt.PT_String, "PYHELLO", "def_obj_name" )
+ pid = sgPyQt.addPreference( "Default creation mode", gid, SalomePyQt.PT_Selector, "PYHELLO", "creation_mode" )
+ strings = QStringList()
+ strings.append( "Default name" )
+ strings.append( "Generate name" )
+ strings.append( "Ask name" )
+ indexes = []
+ indexes.append( QVariant(0) )
+ indexes.append( QVariant(1) )
+ indexes.append( QVariant(2) )
+ sgPyQt.setPreferenceProperty( pid, "strings", QVariant( strings ) )
+ sgPyQt.setPreferenceProperty( pid, "indexes", QVariant( indexes ) )
+ pass
+\endcode
+
+- windows() that defines dockable windows layout
+
+\code
+def windows():
+ if verbose() : print "PYHELLOGUI.windows() : study : %d" % _getStudyId()
+ wm = {}
+ wm[SalomePyQt.WT_ObjectBrowser] = Qt.LeftDockWidgetArea
+ wm[SalomePyQt.WT_PyConsole] = Qt.BottomDockWidgetArea
+ return wm
+\endcode
+
+Please refer to PYHELLOGUI.py script for more details about
+implementation of other callback functions.
+
+An implemention of the ShowHello() function is quite simple. It shows
+the small dialog box allowing user to enter the name, and then uses
+reference to the module CORBA engine to invoke its makeBanner()
+service.
+
+Note, that GUI elements of the Python module are implemented with help
+of PyQt toolkit which provides a Python wrappings of the Qt library.
+
+\ref idl_dir "<< Previous"<br>\ref bin_dir ">> Next"
+
+\page bin_dir The bin directory
+
+The file VERSION.in is used to document the module, it must define its
+version and (optionally) its compatibilities or incompatibilities with
+other modules. Therefore, it is strongly recommended but is not
+essential for correct operation of the module.
+
+The runAppli.in file is the equivalent of the runSalome script
+distributed by the KERNEL module but configured to start SALOME
+session with PYHELLO module only.
+
+The myrunSalome.py file reuses part of functionality provided by the
+KERNEL's runSalome.py script. It is used to run SALOME session and
+start PYHELLO module in this session.
+
+\ref src_dir "<< Previous"<br>\ref doc_dir ">> Next"
+
+\page doc_dir The doc directory
+
+This directory provides documentation files of the module. The
+documentation of the module can be implemented in the arbitrary
+way. But if you want your documentation to appear in the SALOME GUI
+desktop's Help menu, some specific actions should be done as follows.
+
+The documentation should be generated in the HTML format. For example,
+the documentation of the PYHELLO module is generated using Doxygen
+tool. It allows to generate structured set of HTML pages from the set
+of input plain text files. Input source files should include Doxygen
+tags and optionally direct HTML tags. For more details please refer to
+the Doxygen documentation.
+
+The resulting documentation of a module should include at least one
+file index.html. All the HTML and image files should be exported by
+the build procedure to the following directory:
+<module_installation_dir>/share/doc/salome/gui/<MODULE>
+where <module_installation_dir> is a module installation folder and
+MODULE is its name. For example, for PYHELLO module, at least one file
+should exist:
+<PYHELLO_module_installation_dir>/share/doc/salome/gui/PYHELLO/index.html.
+
+The SALOME GUI automatically searches for the index.html file in the
+mentioned module directory. If the file is found, the corresponding
+menu command is automatically added to the Help menu of the SALOME GUI
+desktop.
+
+\ref bin_dir "<< Previous"<br>\ref build_procedure ">> Next"
+
+\page build_procedure Construction, installation
+
+Before building PYHELLO module, please ensure that SALOME environment is
+set properly. Assume that SALOME environment is set in env_products.sh
+script. In order to build and install PYHELLO module, you have to
+perform several steps:
+
+<pre>
+[bash% ] source env_products.sh
+[bash% ] mkdir PYHELLO_BUILD
+[bash% ] cd PYHELLO_BUILD
+[bash% ] ../PYHELLO1_SRC/build_configure
+[bash% ] ../PYHELLO1_SRC/configure --prefix=<PYHELLO_module_installation_dir>
+[bash% ] make
+[bash% ] make install
+</pre>
+
+The first command creates a build directory for the PYHELLO module. Then
+next step is to cd to this build directory. From this directory you
+sequentially invoke build_configure, configure, make and make install
+commands. On each step, you have to ensure that the operation is
+finished correctly (no errors raised).
+
+The <PYHELLO_module_installation_dir> variable above defines the
+destination directory to which the PYHELLO module should be
+installed. After the last step is finished, the PYHELLO module is built
+and installed to the <PYHELLO_module_installation_dir> directory.
+
+\ref doc_dir "<< Previous"<br>\ref run_procedure ">> Next"
+
+\page run_procedure Running SALOME
+
+Go to the the <PYHELLO_module_installation_dir> directory and type:
+
+<pre>
+[bash% ] ./bin/salome/runAppli
+</pre>
+
+This command runs SALOME session configured for KERNEL and the PYHELLO
+module. At the end of running, the user will be prompted by the
+Python interpreter command line configured for SALOME that provides
+access to SALOME Python API (including CORBA interfaces).
+
+The runAppli file is a shell script that executes a Python commands
+running SALOME session by passing arguments to it in a command line:
+
+<pre>
+${KERNEL_ROOT_DIR}/bin/salome/envSalome.py python -i $PYHELLO_ROOT_DIR/bin/salome/myrunSalome.py --modules=PYHELLO --killall
+</pre>
+
+These arguments state that the myrunSalome.py script located in the
+PYHELLO module will be used, that the PYHELLO component will be
+activated and all previously running SALOME sessions should be
+shutdowned.
+
+This command will not function unless the following environment
+variables have previously been set:
+
+<pre>
+export KERNEL_ROOT_DIR=<KERNEL installation path>
+export PYHELLO_ROOT_DIR=<PYHELLO installation path>
+</pre>
+
+\warning It is possible that the SALOME run will not reach the end.
+In some circumstances, the time to start CORBA servers may be long and
+could exceed the timeout. If the reasons is that the time to
+load dynamic libraries is long, it is possible that a second run
+immediately afterwards will be successful.
+
+\ref build_procedure "<< Previous"<br>\ref load_module ">> Next"
+
+\page load_module Loading PYHELLO component
+
+The PYHELLO_ORB module has to be imported before making a request to
+load the component into the container, to obtain access to methods of
+the component. This container is made accessible in the runSalome.py
+by means of the \b container variable:
+
+<pre>
+>> import PYHELLO_ORB
+>> c=container.load_impl("PYHELLO","PYHELLO")
+>> c.makeBanner("Christian")
+</pre>
+
+The last instruction returns a string "Hello Christian". Proceed as
+follows to see the CORBA objects created by these actions:
+
+<pre>
+>> clt.showNS()
+</pre>
+
+\ref run_procedure "<< Previous"<br>\ref catalog_def ">> Next"
+
+\page catalog_def PYHELLO module catalog definition
+
+In the example from the previous chapter, the PYHELLO component was
+loaded by making a direct request to the SALOME container. This is not
+the standard method for loading of a component. The normal way uses
+the SALOME LifeCycle service that invokes SALOME Module Catalog
+services to identify the component and its properties and then calls
+the requested container to load the component.
+
+Before this method can be used, the component must be declared in a
+catalog in the XML format, for which the name must be
+<Module>Catalog.xml. In our case, it will be PYHELLOCatalog.xml.
+Usually this catalog is put to the resources sub-directory of the
+directory tree. The simplest way to create this file is to use Catalog
+Generator utility provided by the SALOME KERNEL module, that can
+automatically generate XML description file from the IDL file.
+
+\ref load_module "<< Previous"<br>\ref load_lcc ">> Next"
+
+\page load_lcc Loading PYHELLO component via LifeCycle service
+
+The method of loading the component is not very different from that
+is described above. The services of the LifeCycle module are used in
+this case instead of calling the container directly. The call sequence
+is contained in the runSalome.Py \b test() function.
+
+<pre>
+ c=test(clt)
+ c.makeBanner("Christian")
+</pre>
+
+The test function creates the LifeCycle object. It then asks for the
+PYHELLO component to be loaded in the FactoryServer container:
+
+\code
+def test(clt):
+ """
+ Test function that creates an instance of PYHELLO component
+ usage : hello=test(clt)
+ """
+ import LifeCycleCORBA
+ lcc = LifeCycleCORBA.LifeCycleCORBA(clt.orb)
+ import PYHELLO_ORB
+ pyhello = lcc.FindOrLoadComponent("FactoryServePy", "PYHELLO")
+ return pyhello
+\endcode
+
+\ref catalog_def "<< Previous"<br>\ref load_iapp ">> Next"
+
+\page load_iapp Loading from the GUI (IAPP)
+
+In order to activate PYHELLO module in the SALOME GUI desktop, the user
+should press the PYHELLO module's button on the "Modules" toolbar or
+select the name of the module in the combo box on this toolbar.
+
+The image file to be used as an icon of a module should be exported by
+the module build procedure. The icon file name is defined in the
+corresponding SalomeApp.xml configuration file:
+\code
+ <section name="PYHELLO">
+ <parameter name="name" value="Hello"/>
+ <parameter name="icon" value="PYHELLO.png"/>
+ <parameter name="library" value="SalomePyQtGUI"/>
+ </section>
+\endcode
+
+\ref load_lcc "<< Previous"
+
+*/
