Merge from V6_main_20120808 08Aug12

[samples/pyhello.git] / doc / index.doc

/*!

\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.in
   + 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/myrunSalome.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.in

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"/>
    <parameter name="version" value="@VERSION@"/>
  </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 "version" parameter 
defines the version of the module.

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

The section [module_name]_help provides information on the location of 
the help page and the eventual sub-menu in the Help menu.

\code
  <section name="pyhello_help" >
    <parameter name="sub_menu"        value="Samples"/>
    <parameter name="%1 User's Guide" value="%PYHELLO_ROOT_DIR%/share/doc/salome/gui/PYHELLO/index.html"/>
  </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 EngineComponent 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_module_installation_dir>
export PYHELLO_ROOT_DIR=<PYHELLO_module_installation_dir>
</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 myrunSalome.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 myrunSalome.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"

*/