Merge branch 'V9_13_BR'

[samples/hello.git] / doc / input / index.doc

/*!

\mainpage Introduction to HELLO sample module

The purpose of the \b HELLO module is to describe briefly the different
steps in the development of a SALOME module in C++.  

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 very simple. The module contains a single
component and this component provides several services called \b
hello and \b goodbye. 
Each of these functions accepts
a character string as the arguments and returns the status of the operation.
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 C++ SALOME container
- configure the module so that the component is known to SALOME
- add a GUI

\ref index "<< 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 hierarchy. The typical SALOME module usually includes
configuration files (used in the build procedure of a
module), CMakeLists.txt files, IDL file that provides a definition 
of a CORBA services implemented in a module and a set of source files 
which are compiled by the build procedure to the module 
CORBA engine library and (optionally) GUI library.

The following file structure is typical for the SALOME module:

<pre>
+ HELLO1_SRC
   + CMakeLists.txt
   + SalomeHELLOConfig.cmake.in
   + HELLO_version.h.in
   + AUTHORS
   + COPYING
   + ChangeLog
   + INSTALL
   + NEWS
   + README
   + adm_local
     + CMakeLists.txt
     + cmake_files
       + CMakeLists.txt
       + FindSalomeHELLO.cmake
   + bin
     + CMakeLists.txt
     + VERSION.in
     + runHELLO.in
     + runHELLO.py
   + idl
     + CMakeLists.txt
     + HELLO_Gen.idl
   + src
     + CMakeLists.txt
     + HELLO
       + CMakeLists.txt
       + HELLO.hxx
       + HELLO.cxx
     + HELLOGUI
       + CMakeLists.txt
       + HELLOGUI.h
       + HELLOGUI.cxx
       + HELLO_msg_en.ts
       + HELLO_msg_fr.ts
       + HELLO_icons.ts
   + resources
     + CMakeLists.txt
     + HELLO.png
     + goodbye.png
     + handshake.png
     + testme.png
     + HELLOCatalog.xml.in
     + SalomeApp.xml.in
   + doc
     + CMakeLists.txt
     + doxyfile.in
     + index.doc
     + images
       + head.png
     + static
       + doxygen.css
       + footer.html
       + header.html.in
</pre>

Note that other files can be optionally present. 

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 HELLO, the component name is HELLO and all the
files are put in a directory named HELLO1_SRC.
Below is a short description of these files. Note, that files with .in
suffix are the cmake templates from which the actual files are
generated during the build procedure.

- \c CMakeLists.txt

These files are input text files that contain the project parameters 
and describe the flow control of the build process in simple CMake language as 
a part of the build system based on CMake. These files define 
the build procedure, namely, compilation and installation rules such as compiler 
and linker options, installation destination folder, package version etc.

- \c AUTHORS
- \c COPYING
- \c ChangeLog
- \c INSTALL
- \c NEWS
- \c README

These files are a usual part of open source projects. These files are 
used by developers to provide an additional information on a product,
like license, authors and distribution information, change log between
versions of a product, installation hints, etc.

- \c HELLO_version.h.in 

This is an optional C++ header file, that specifies the version
macro-definitions which can be used, for example, in other modules to
check the version of the SALOME module (HELLO module in this
case).

- \c adm_local

This directory contains additional administrative files used by the
build procedure.

- \c adm_local/cmake_files/FindSalomeHELLO.cmake

Some modules can need some external packages in order to compile and 
run properly. The usual approach is to write a special *.cmake file
for the purpose of finding a certain piece of software and to set it's
libraries, include files and definitions into appropriate variables so that
they can be used in the build process of another project.
It is possible to include the standard CMake detection modules (FindXyz.cmake files,
located in the standard CMake installation directory) or, if CMake does not provide
a search procedure for some required software, it is necessary to create *.cmake
module for each pre-requisite.

Also, it is good idea to create and distribute *.cmake file for the project being
developed; it can be used then in the dependent projects. For example, HELLO module
installs a file FindSalomeHELLO.cmake that can be used for its detection.

To search SALOME HELLO module in some other project it will be only needed to write
the following code in CMakeLists.txt: 

\code
FIND_PACKAGE(SalomeHELLO)
\endcode

- \c bin

This directory usually contains different scripts.

- \c 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.

- \c bin/runHELLO.in
- \c bin/runHELLO.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
HELLO module.

- \c idl

This directory contains IDL files that specify the CORBA services
supplied by SALOME module.

- \c idl/HELLO_Gen.idl

This is the CORBA IDL definition of the services implemented by SALOME
HELLO module.

- \c src

This is a root directory of the module source codes. Usually it contains
one or more sub-directories that provide an implementation of module
libraries, executables, Python API modules, etc. The hierarchy of the
sources tree is arbitrary; it follows the specific module needs.

- \c src/HELLO

This directory provides implementation of engine library.

- \c src/HELLO/HELLO.hxx
- \c src/HELLO/HELLO.cxx

These files provide the implementation of a CORBA engine library of
the HELLO module. In particular, this is an implementation of the
services defined in the \c HELLO_Gen.idl file.

- \c HELLOGUI

It is an optional directory that provides an implementation of HELLO
module's GUI library.

Strictly speaking, the GUI library 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 available in a CORBA environment.
The module can be loaded to the SALOME container and its services
can be used in the SALOME supervision computation schemas, in Python
scripts or/and in C++ implementation of other modules.

A GUI library is necessary only if it is planned to access the module
functionality from the SALOME GUI session via menu actions, dialog boxes
and so on. 

- \c src/HELLOGUI/HELLOGUI.h
- \c src/HELLOGUI/HELLOGUI.cxx

These files provide the implementation of a GUI library of
the HELLO module. In particular, these files specify menus, toolbars,
dialog boxes and other such staff.

- \c src/HELLOGUI/HELLO_msg_en.ts
- \c src/HELLOGUI/HELLO_msg_fr.ts
- \c src/HELLOGUI/HELLO_icons.ts

These files provide a description (internationalization) of GUI
resources of the HELLO module. \c HELLO_msg_en.ts provides an English
translation of the string resources used in a module (there can be also
translation files for other languages, for instance French; these files
are distinguished by the language suffix). \c HELLO_icons.ts
defines images and icons resources used within the GUI library of
HELLO module. Please refer to Qt linguist documentation for more
details.

- \c resources

This optional directory usually contains different resources files
required for the correct operation of SALOME module.

- \c resources/HELLO.png
- \c resources/handshake.png
- \c resources/goodbye.png
- \c resources/testme.png

These are different module icon files. \c HELLO.png file provides main icon
of HELLO module to be shown in the SALOME GUI desktop. Other files are
the icons for the functions implemented by the module; they are used
in the menus and toolbars.

- \c resources/HELLOCatalog.xml.in

The XML description of the CORBA services provided by the HELLO
module. This file is parsed by SALOME supervision module (YACS) 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. In GUI, this utility is available
via the Tools main menu.

- \c resources/SalomeApp.xml.in

This file is essential for each SALOME module. It provides some parameters of
the module which define its behavior in SALOME. In particular it
should provide a section with the name corresponding to the name of a
module ("HELLO" in our case) with the following parameters:
\code
  <section name="HELLO">
    <parameter name="name"          value="Hello"/>
    <parameter name="icon"          value="HELLO.png"/>
    <parameter name="version"       value="@SALOMEHELLO_VERSION@"/>
    <parameter name="documentation" value="hello_help"/>
  </section>
\endcode

The \a "name" parameter defines GUI name of a module. The \a "icon"
parameter defines a GUI icon of a module. Optional \a "version" parameter
defines the version of the module. The \a "documentation" parameter
provides a name for the help-related resource section (see below).

The section \a "resources" of a file specifies the directory that contains
resources of a module (icons, translation files, etc).

\code
  <section name="resources">
    <parameter name="HELLO" value="%HELLO_ROOT_DIR%/share/salome/resources/hello"/>
  </section>
\endcode

The section \a "hello_help" provides information on the location of 
the help page(s) and the eventual sub-menu in the Help menu. The name of this section
can be arbitrary, in such a case it should be specified in the main module's resources
section (see above). Alternatively, this section's name can have syntax
\a "<module_name>_documentation", where \a module_name is a name of the module.
If such section is present in the resource file, it is not necessary to specify it
in the module's main section.

Parameter \a "sub_menu" of the documentation section allows sepecifying the name of the
sub-menu in the Help main menu where the documentation materials of a module should be
put.

\code
  <section name="hello_help" >
    <parameter name="sub_menu"        value="Samples"/>
    <parameter name="%1 User's Guide" value="%HELLO_ROOT_DIR%/share/doc/salome/gui/HELLO/index.html"/>
  </section>
\endcode

- \c doc

This directory containes the files related to the module's documentation.

- \c doc/doxyfile.in

The \b Doxygen configuration file. The Doxygen is used to build this
documentation. The file \c doxyfile.in provides a rules for the
generation of module documentation.

- \c doc/index.doc

An input file for the Doxygen, which provides a source of this documentation.

- \c doc/images

This sub-folder contains images used in the documentation.

- \c doc/static

This sub-folder contains auxiliary files used when generating documentation
by Doxygen, like header (\c header.html.in) and footer (\c footer.html)
of the HTML pages, style sheet (\c doxygen.css) etc.

\ref dev_steps "<< Previous"<br>\ref build_proc_files ">> Next"

\page build_proc_files Build procedure input files

In most cases SALOME uses \b CMake-based build system for modules.
CMake is a cross-platform build system which works on Linux, Windows
and other operating systems.

The \c CMakeLists.txt files are used to describe the build procedure,
in particular:
- Test platform;
- Test system configuration;
- Detect pre-requisites;
- Generate build rules (for example, standard UNIX makefiles on Linux,
  MSVC solutions, etc).

Project's root directory provides main CMake configuration that allows 
build all targets into one set of binaries and libraries. Each sub-directory
also includes CMake configuration file (CMakeLists.txt) that specifies
targets being build.

The file \c CMakeLists.txt in root directory of the HELLO module provides 
basic build rules to be used in other \c CMakeLists.txt files. 
It sets main properties of project: name, version, pre-requisites, 
installation paths, programming languages being used by the project,
tree of sub-directories, etc.

A lot of files used by the build procedure of HELLO module are located
in SALOME KERNEL module (that is referenced by the \c KERNEL_ROOT_DIR
environment variable), namely in its \c salome_adm sub-folder.
Similarly, the \c GUI_ROOT_DIR environment variable is used for the
graphical user interface (GUI) module of SALOME; this module also
provides a set of configuration utilities (\c *.cmake files) in its 
\c adm_local folder.

The files with an \c .in extension are the skeletons which are processed
by CMake to transform it to the resulting files in the build directory during
the configuration process.

\ref tree_structure "<< Previous"<br>\ref idl_dir ">> Next"

\page idl_dir The idl directory

The \c idl directory requires a \c CMakeLists.txt that must make the
compilation of the CORBA IDL \c HELLO_Gen.idl file and install all the
generated files into the correct module installation directories.
This is done by using \c OMNIORB_ADD_MODULE() CMake macro:

\code
OMNIORB_ADD_MODULE(SalomeIDLHELLO HELLO_Gen.idl ${KERNEL_ROOT_DIR}/idl/salome ${KERNEL_SalomeIDLKernel})
INSTALL(TARGETS SalomeIDLHELLO EXPORT ${PROJECT_NAME}TargetGroup DESTINATION ${SALOME_INSTALL_LIBS})
\endcode


The IDL file itself must define a CORBA component 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 \a EngineComponent interface  
of the \a Engines module. In case of HELLO module, the name of the CORBA 
component is \b HELLO_ORB and the name of the interface is \b HELLO_Gen. 

\ref build_proc_files "<< Previous"<br>\ref src_dir ">> Next"

\page src_dir The src directory

The \c src directory contains all source files required to build CORBA engine and
(optionally) GUI libraries of the module. Each of these entities usually
has (but this is not actually obligatory) its own directory.

The \c CMakeLists.txt file triggers the path of sub-directories described
by the \a ADD_SUBDIRECTORY() command.

- \c src/HELLO sub-directory

This sub-directory contains the C++ source files that implement the engine
library of the module. The \c CMakeLists.txt defines the rules used to build
the engine library from these source files. The name of the module
engine library is predefined and should be set as \c lib\<MODULE\>Engine.so
where \c MODULE is a name of the module. In the case of the HELLO
module, the name of the engine library should be \c libHELLOEngine.so.

The \c HELLO.h, \c HELLO.cxx files implement \a HELLO class that is derived
from the \a HELLO_Gen interface of the \a HELLO_ORB__POA CORBA module and the
\a SALOME_Component_i class (base implementation of SALOME module engine
exported by the KERNEL module).

In particular, \a HELLO class implements \a hello() and \a goodbye() functions
that are defined in the IDL interface \a HELLO_ORB::HELLO_Gen.

\code
HELLO_ORB::status HELLO::hello( const char* name )
{
...
}
HELLO_ORB::status HELLO::goodbye( const char* name )
{
...
}
\endcode

In addition, \c HELLO.cxx implements a factory function which is used by
the SALOME container to create an instance of the HELLO CORBA engine
by demand:

\code
extern "C"
{
  PortableServer::ObjectId* HELLOEngine_factory( 
    CORBA::ORB_ptr orb,
    PortableServer::POA_ptr poa, 
    PortableServer::ObjectId* contId,
    const char* instanceName, 
    const char* interfaceName )
  {
    HELLO* component = new HELLO( orb, poa, contId, instanceName, interfaceName );
    return component->getId();
  }
}
\endcode

- \c src/HELLOGUI sub-directory

This directory contains the C++ source files that implement the GUI
library of HELLO module. By default, the name of the module
GUI library is predefined and should be set as \c lib\<MODULE\>.so
where \c MODULE is a name of the module. In the case of the HELLO
module, the name of the GUI library should be \c libHELLO.so. It is
also possible to use custom name of the GUI library of a module, but
in this case, in order to be possible to use this module in SALOME GUI
desktop, the name of the GUI library should be defined in the
\c SalomeApp.xml file, in the module's main section, using \a "library"
parameter, for example:

\code
  <section name="HELLO">
    <parameter name="name" value="Hello"/>
    <parameter name="icon" value="HELLO.png"/>
    <parameter name="library" value="libMyHelloGUIlibrary.so"/>
  </section>
\endcode

The implementation of GUI library of the HELLO module should be done
according to the architecture and rules specified by the SALOME GUI
module. The main GUI module class (a\ HELLOGUI in our case) should be
derived from the \a SalomeApp_Module class.

The developer has to redefine a set of methods 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.

- \a initialize() - module initialization; usually used to create
  GUI actions, menus, toolbars and so on;
- \a activateModule() - module activation; perform actions which should
  be done when the module is activated by the user, for example, show
  related menus and toolbars;
- \a deactivateModule() - module deactivation; perform actions which should
  be done when the module is deactivated by the user, for example,
  hide related menus and toolbars;
- \a windows() - get a list and a position of the dockable windows to be
  associated with the module; these windows will be automatically
  opened and positioned according to the settings defined by the value
  returned by this function;
- \a viewManagers() - get a list of the compatible viewers; these viewers
  will be automatically opened/raised on the module activation;
- \a contextMenuPopup() - create and return context popup menu according
  to the current selection;
- \a createPreferences() - initialize module's preferences;
- \a preferencesChanged() - callback function that is called when some
  module's preference is changed by the user; allows to perform the
  corresponding actions;
- \a createSelection() - create and return menu selection object; this is
  a part of the context popup menu definition API;
- \a engineIOR() - get the reference to the module CORBA engine;
- \a moduleIcon() and \a iconName() - these methods can be used to customize
  the module's main icon;
- \a displayer() - get the reference to the module's \a Displayer class; this
  is the part of common Show/Hide functionality mechanism;
- \a storeVisualParameters() and \a restoreVisualParameters() - these methods
  can be redefined to store/restore different visualization attributes of the 
  presentable data if it is supported by the module, for example transparency,
  colors, display mode and other presentable parameters;
- \a canCopy(), \a copy(), \a canPaste(), \a paste() - these methods are the
  part of the common Copy/Paste functionality;
- \a isDraggable(), \a isDropAccepted(), \a dropObjects() - these methods
  are the part of the common Drag-n-Drop functionality;
- \a createOperation() - this function can be used as a part of the
  transaction-based operations mechanism.
- \a renameAllowed(), \a renameObject() - can be used for in-place (Object
  browser) renaming of the data entities, if it is supported by the module.

Note, that all of these methods are optional and need not be
obligatory implemented because \a SalomeApp_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 HELLO module, only the following methods are
implemented (other ones are just stubs, added for sample reasons):

- \a engineIOR() that initializes HELLO module's engine:

\code
QString HELLOGUI::engineIOR() const
{
  init(); // initialize engine, if necessary
  CORBA::String_var anIOR = getApp()->orb()->object_to_string( myEngine.in() );
  return QString( anIOR.in() );
}
\endcode

- \a initialize() that creates actions, menus and toolbars for module's services
  service:

\code
void HELLOGUI::initialize( CAM_Application* app )
{
  // call the parent implementation
  SalomeApp_Module::initialize( app );

  // get reference to the desktop (used as a parent for actions)
  QWidget* dsk = app->desktop();
  // get resources manager
  SUIT_ResourceMgr* resMgr = app->resourceMgr();

  // create actions
  // ... Test me operation
  createAction( OpTestMe,                                               // operation id
                tr( "TLT_OP_TESTME" ),                                  // tooltip
                resMgr->loadPixmap( "HELLO",tr( "ICON_OP_TESTME" ) ),   // icon
                tr( "MEN_OP_TESTME" ),                                  // menu title
                tr( "STS_OP_TESTME" ),                                  // status tip
                0,                                                      // accelerator (not set)
                dsk,                                                    // parent
                false,                                                  // togglable flag (no)
                this,                                                   // action receiver
                SLOT( testMe() ) );                                     // action slot
  // create other actions ............

  // create menus
  int menuId;
  menuId = createMenu( tr( "MEN_FILE" ), -1, -1 );                      // File menu
  createMenu( separator(), menuId, -1, 10 );                            // add separator to File menu
  menuId = createMenu( tr( "MEN_FILE_HELLO" ), menuId, -1, 10 );        // File - Hello submenu
  createMenu( OpTestMe, menuId );                                       // File - Hello - Test me
  // create other menus ............

  // create toolbars
  int aToolId;
  aToolId = createTool ( tr( "TOOL_TEST" ) );                           // Test toolbar
  createTool( OpTestMe, aToolId );                                      // Test - Test me
  // create other toolbars ............

  // set-up popup menu
  QtxPopupMgr* mgr = popupMgr();
  mgr->insert( action( OpHello ),   -1, -1 );                           // Hello
  mgr->setRule( action( OpHello ),   baseRule + " and isComponent",  QtxPopupMgr::VisibleRule );
  // create other popup menu commands ............
}
\endcode

- \a activateModule() that activates menus and toolbars
 
\code
bool HELLOGUI::activateModule( SUIT_Study* theStudy )
{
  // call parent implementation
  bool bOk = SalomeApp_Module::activateModule( theStudy );

  // show own menus
  setMenuShown( true );
  // show own toolbars
  setToolShown( true );

  // return the activation status
  return bOk;
}
\endcode

- \a deactivateModule() that deactivates menus and toolbars

\code
bool HELLOGUI::deactivateModule( SUIT_Study* theStudy )
{
  // hide own menus
  setMenuShown( false );
  // hide own toolbars
  setToolShown( false );

  // call parent implementation and return the activation status
  return SalomeApp_Module::deactivateModule( theStudy );
}
\endcode

- \a windows() that set-ups dockable windows requested by the module

\code
void HELLOGUI::windows( QMap<int, int>& theMap ) const
{
  // want Object browser, in the left area
  theMap.insert( SalomeApp_Application::WT_ObjectBrowser,
                 Qt::LeftDockWidgetArea );
  // want Python console, in the bottom area
  theMap.insert( SalomeApp_Application::WT_PyConsole,
                 Qt::BottomDockWidgetArea );
}
\endcode

- \a isDragable(), \a isDropAccepted() and \a dropObjects() methods that handle
the Drag-n-Drop operation

\code
bool HELLOGUI::isDragable( const SUIT_DataObject* what ) const
{
  // we allow dragging any HELLO object, except the top-level component
  const SalomeApp_ModuleObject* aModObj = dynamic_cast<const SalomeApp_ModuleObject*>( what );
  return ( aModObj == 0 );
}

bool HELLOGUI::isDropAccepted( const SUIT_DataObject* where ) const
{
  // we allow dropping of all objects
  return true;
}

void HELLOGUI::dropObjects( const DataObjectList& what, SUIT_DataObject* where,
                            const int row, Qt::DropAction action )
{
  if (action != Qt::CopyAction && action != Qt::MoveAction)
    return; // unsupported action

  // get parent object
  SalomeApp_DataObject* dataObj = dynamic_cast<SalomeApp_DataObject*>( where );
  if ( !dataObj ) return; // wrong parent
  _PTR(SObject) parentObj = dataObj->object();

  // collect objects being dropped
  HELLO_ORB::object_list_var objects = new HELLO_ORB::object_list();
  objects->length( what.count() );
  int count = 0;
  for ( int i = 0; i < what.count(); i++ ) {
    dataObj = dynamic_cast<SalomeApp_DataObject*>( what[i] );
    if ( !dataObj ) continue;  // skip wrong objects
    _PTR(SObject) sobj = dataObj->object();
    objects[i] = _CAST(SObject, sobj)->GetSObject();
    count++;
  }
  objects->length( count );

  // call engine function
  engine()->copyOrMove( objects.in(),                              // what
                        _CAST(SObject, parentObj)->GetSObject(),   // where
                        row,                                       // row
                        action == Qt::CopyAction );                // isCopy

  // update Object browser
  getApp()->updateObjectBrowser( false );
}
\endcode

An implemention of the \a hello() and \a goodbye() methods is quite simple. 
These operations show the dialog box proposing the user to enter the name and
pass the name entered by the user to the engine side, using the corresponding
CORBA service.

\code
void HELLOGUI::hello()
{
  // request user name
  bool ok;
  QString name = QInputDialog::getText( getApp()->desktop(), tr( "QUE_HELLO_TITLE" ), tr( "QUE_ENTER_NAME" ),
                                        QLineEdit::Normal, QString::null, &ok );

  if ( ok && !name.trimmed().isEmpty() ) {
    // say hello to SALOME
    HELLO_ORB::status status = engine()->hello( (const char*)name.toLatin1() );

    // update Object browser
    getApp()->updateObjectBrowser(true);

    // process operation status
    switch( status ) {
    case HELLO_ORB::OP_OK:
      // everything's OK
      SUIT_MessageBox::information( getApp()->desktop(),
                                    tr( "INF_HELLO_TITLE" ), 
                                    tr( "INF_HELLO_MSG" ).arg( name ),
                                    tr( "BUT_OK" ) );
      break;
    case HELLO_ORB::OP_ERR_ALREADY_MET:
      // error: already said hello
      SUIT_MessageBox::warning( getApp()->desktop(),
                                tr( "INF_HELLO_TITLE" ), 
                                tr( "ERR_HELLO_ALREADY_MET" ).arg( name ),
                                tr( "BUT_OK" ) );
      break;
    case HELLO_ORB::OP_ERR_UNKNOWN:
    default:
      // other errors
      SUIT_MessageBox::critical( getApp()->desktop(),
                                 tr( "INF_HELLO_TITLE" ), 
                                 tr( "ERR_ERROR" ),
                                 tr( "BUT_OK" ) );
      break;
    }
  }
}

void HELLOGUI::goodbye()
{
  SalomeApp_Application* app = dynamic_cast<SalomeApp_Application*>( application() );
  SalomeApp_Study* study = dynamic_cast<SalomeApp_Study*>( application()->activeStudy() );
  _PTR(Study) studyDS = study->studyDS();
  LightApp_SelectionMgr* aSelMgr = app->selectionMgr();

  QString name;

  // get selection
  SALOME_ListIO selected;
  aSelMgr->selectedObjects( selected );
  if ( selected.Extent() == 1 ) {
    Handle(SALOME_InteractiveObject) io = selected.First();
    _PTR(SObject) so = studyDS->FindObjectID( io->getEntry() );
    if ( so ) { 
      _PTR(SComponent) comp = so->GetFatherComponent();
      if ( comp && comp->ComponentDataType() == "HELLO" && io->getEntry() != comp->GetID() ) {
        name = so->GetName().c_str();
      }
    }
  }

  // request user name if not specified
  if ( name.isEmpty() ) {
    bool ok;
    name = QInputDialog::getText( getApp()->desktop(), tr( "QUE_GOODBYE_TITLE" ), tr( "QUE_ENTER_NAME" ),
                                  QLineEdit::Normal, QString::null, &ok );
  }

  if ( !name.trimmed().isEmpty() ) {
    // say goodby to SALOME
    HELLO_ORB::status status = engine()->goodbye( (const char*)name.toLatin1() );

    // update Object browser
    getApp()->updateObjectBrowser(true);

    // process operation status
    switch( status ) {
    case HELLO_ORB::OP_OK:
      // everything's OK
      SUIT_MessageBox::information( getApp()->desktop(),
                                    tr( "INF_GOODBYE_TITLE" ), 
                                    tr( "INF_GOODBYE_MSG" ).arg( name ),
                                    tr( "BUT_OK" ) );
      break;
    case HELLO_ORB::OP_ERR_DID_NOT_MEET:
      // error: did not say hello yet
      SUIT_MessageBox::warning( getApp()->desktop(),
                                tr( "INF_GOODBYE_TITLE" ), 
                                tr( "ERR_GOODBYE_DID_NOT_MEET" ).arg( name ),
                                tr( "BUT_OK" ) );
      break;
    case HELLO_ORB::OP_ERR_UNKNOWN:
    default:
      // other errors
      SUIT_MessageBox::critical( getApp()->desktop(),
                                 tr( "INF_GOODBYE_TITLE" ), 
                                 tr( "ERR_ERROR" ),
                                 tr( "BUT_OK" ) );
      break;
    }
  }
}
\endcode

Also, \c HELLOGUI.cxx provide an implementation of a factory function that is used
by the SALOME GUI to create an instance of the HELLO GUI class by demand.
It implements also another factory function to retrieve the
version number of the module (in the About dialog box for example):

\code
extern "C" {
  CAM_Module* createModule()
  {
    return new HELLOGUI();
  }

  char* getModuleVersion() 
  {
    return (char*)HELLO_VERSION_STR;
  }
}
\endcode

\ref idl_dir "<< Previous"<br>\ref bin_dir ">> Next"

\page bin_dir The bin directory

The file \c 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 \c runHELLO.in file is the equivalent of the \c runSalome script
distributed by the KERNEL module but configured to start SALOME
session with HELLO module only.

The \c runHELLO.py file reuses part of functionality provided by the
KERNEL's \c runSalome.py script. It is used to run SALOME session and
start HELLO 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 HELLO 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 \c index.html. All the HTML and image files should be exported by
the build procedure to the following directory:
\c \<module_installation_dir\>/share/doc/salome/gui/\<MODULE\>
where \c module_installation_dir is a module installation folder and
\c MODULE is its name. For example, for HELLO module, at least one file
should exist:
\c \<HELLO_module_installation_dir\>/share/doc/salome/gui/HELLO/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 HELLO 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 HELLO module, you have to
perform several steps:

<pre>
[bash% ] source env_products.sh
[bash% ] mkdir HELLO_BUILD
[bash% ] cd HELLO_BUILD
[bash% ] cmake -DCMAKE_BUILD_TYPE=<Mode> -DCMAKE_INSTALL_PREFIX=<HELLO_module_installation_dir> ../HELLO1_SRC
[bash% ] make
[bash% ] make install
</pre>

The first command sets environment for building project.

Second command creates a build directory for the HELLO module. Then
next step is to cd to this build directory. From this directory you 
invoke cmake command, where <Mode> is build mode (Release or Debug),
<HELLO_module_installation_dir> is a destination folder to install HELLO module of SALOME.
By default (if CMAKE_INSTALL_PREFIX option is not given), HELLO module will be 
configured for installation to the /usr directory that requires root permissions 
to complete the installation. 

Next steps - build the package (\c make) and install it (\c make install). 

On each step, you have to ensure that the operation is finished correctly 
(no errors raised). After the last step is finished, the HELLO module is built
and installed to the \c \<HELLO_module_installation_dir\> directory.

\ref doc_dir "<< Previous"<br>\ref run_procedure ">> Next"

\page run_procedure Running SALOME

Go to the the \c \<HELLO_module_installation_dir\> directory and type:

<pre>
[bash% ] ./bin/salome/runHELLO
</pre>

This command runs SALOME session configured for KERNEL and the HELLO
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 \c runHELLO 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 $HELLO_ROOT_DIR/bin/salome/runHELLO.py --modules=HELLO --killall
</pre>

These arguments state that the \c runHELLO.py script located in the
HELLO module will be used, that the HELLO 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 HELLO_ROOT_DIR=\<HELLO_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 HELLO component

The \a HELLO_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 \c runHELLO.py
by means of the \a container variable:

<pre>
>> import salome
>> salome.salome_init()
>> import HELLO_ORB
>> c = container.load_impl("HELLO", "HELLO")
>> c.hello("Christian")
</pre>

The last instruction invokes HELLO module's service \a hello(). 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 HELLO module catalog definition

In the example from the previous chapter, the HELLO 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
\c \<MODULE\>Catalog.xml. In our case, it will be \c HELLOCatalog.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 HELLO 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 \c runHELLO.py \a test() function.

<pre>
    import salome
    salome.salome_init()
    c = test(clt)
    c.hello("Christian")
</pre>

The test function creates the LifeCycle object. It then asks for the
HELLO component to be loaded in the \a FactoryServer container:

\code
def test(clt):
    """
    Test function that creates an instance of HELLO component
    usage : hello=test(clt)
    """
    import LifeCycleCORBA
    lcc = LifeCycleCORBA.LifeCycleCORBA(clt.orb)
    import HELLO_ORB
    hello = lcc.FindOrLoadComponent("FactoryServer", "HELLO")
    return hello
\endcode

\ref catalog_def "<< Previous"<br>\ref load_iapp ">> Next"

\page load_iapp Loading from the GUI (IAPP)

In order to activate HELLO module in the SALOME GUI desktop, the user
should press the HELLO module's button on the \a 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 \c SalomeApp.xml:
\code
  <section name="HELLO">
    <parameter name="name" value="Hello"/>
    <parameter name="icon" value="HELLO.png"/>
  </section>
\endcode

\ref load_lcc "<< Previous"

*/