.. _cppsalome:
===========================================================
-Guide pour le développement d'un module SALOME en C++
+Guide for the development of a SALOME module in C++
===========================================================
-Ce document a pour objectif de décrire les différentes étapes
-du développement d'un module SALOME en C++.
-Il fait suite au document :ref:`pysalome`, qui documente le module PYHELLO, et en reprend la démarche :
-construction pas à pas d'un module HELLO.
-Comme de nombreux points ne sont pas repris, il est recommendé de lire ce
-document préalablement.
+The purpose of this document is to describe the different steps in the development of a SALOME module in C++.
+It follows on from the :ref:`pysalome` document, that documents the PYHELLO module, and it uses the same
+approach: step by step construction of a HELLO module. Since many points are not repeated, it is recommended
+that this document should be read first.
-
-Les étapes de construction du module exemple
+Steps in the construction of the example module
====================================================
-Le composant choisi pour illustrer le processus de construction en C++
-est le même que celui choisi pour illustrer la construction du module python :
-il implémentera donc la même interface idl Corba.
-Il sera complété par un GUI graphique écrit en Qt.
-
-Les différentes étapes du développement seront les suivantes :
-
- - créer une arborescence de module
- - créer un composant SALOME chargeable par un container C++
- - configurer le module pour que le composant soit connu de SALOME
- - ajouter un GUI graphique
- - rendre le composant utilisable dans le superviseur
-
-Création de l'arborescence du module
+The component chosen to illustrate the C++ construction process is the same as the process chosen to illustrate
+construction of the Python module: therefore, it will implement the same Corba idl interface. It will be
+completed by a graphic GUI written in Qt.
+
+The various steps of the development will be as follows:
+ - create a module structure
+ - create a SALOME component that can be loaded by a C++ container
+ - configure the module so that the component is known to SALOME
+ - add a graphic GUI
+ - make the component usable in the YACS module.
+
+Creating the module tree structure
=======================================
-Dans un premier temps, on se contentera de mettre dans le module exemple un composant
-SALOME écrit en C++ qui sera chargeable par un container C++.
-Il suffit donc d'une interface idl et d'une implantation C++ du composant.
-Pour mettre en oeuvre ceci dans un module SALOME, il nous faut reproduire l'arborescence de
-fichier standard suivante::
+We will start by simply putting a SALOME component written in C++ and that can be loaded by a C++ container, into the
+example module. Therefore, all that is necessary is an idl interface and a C++ implantation of the component.
+We need to reproduce the following standard file tree structure, to use it in a SALOME module::
+ HELLO1_SRC
- + build_configure
- + configure.in.base
- + Makefile.in
+ + CMakeLists.txt
+ adm_local
- + unix
- + make_commence.in
- + make_omniorb.in
- + config_files
+ + CMakeLists.txt
+ + cmake_files
+ + CMakeLists.txt
+ + FindSalomeHELLO.cmake
+ bin
+ + CMakeLists.txt
+ VERSION
+ runAppli.in
+ runSalome.py
+ idl
- + Makefile.in
+ + CMakeLists.txt
+ HELLO_Gen.idl
+ src
- + Makefile.in
+ + CMakeLists.txt
+ HELLO
- + Makefile.in
+ + CMakeLists.txt
+ HELLO.cxx
+ HELLO.hxx
+ doc
-Pour cela, on recopie l'arborescence de PYHELLO, et on modifie où nécessaire
-PYHELLO en HELLO::
+This is done by copying the PYHELLO tree structure, and modifying PYHELLO to HELLO if necessary::
cp -r PYHELLO1_SRC HELLO1_SRC
cd HELLO1_SRC
mv src/PYHELLO src/HELLO
-Interface idl
+IDL interface
==================
-Dans le répertoire idl, nous modifions le fichier idl HELLO_Gen.idl : le
-module défini est renommé HELLO_ORB, et l'interface en HELLO_Gen.
-Le service rendu reste le même : à partir d'une chaine de caractères
-fournie comme unique argument, retour d'une chaine de caractères obtenue
-par concaténation de "Hello, " et de la chaine d'entrée.
-Ce service est spécifié par la fonction makeBanner.
-
-Un utilitaire de documentation basé sur doxygen a été mis en place pour
-compiler une documentation des services corba à partir de commentaires se
-trouvant dans les fichiers idl. Nous rajouter donc à notre idl quelques
-commentaires, en respectant le formalisme doxygen.
-Un commentaire doxygen commence par "/\*!" et se finit par "\*/".
-Pour structurer un minimum les pages générées, on les regroupe par module ou
-sujet. Dans notre exemple, nous utilisons la directive::
-
- \ingroup EXAMPLES
-
-spécifiant que la documentation générée fait partie du groupe EXAMPLES.
-(pour plus d'information sur doxygen, consulter le site http://www.doxygen.org).
-
-Pour finir, nous mettons à jour le Makefile avec le nouveau nom de composant::
-
+We modify the HELLO_Gen.idl file in the idl directory: the defined module is named HELLO_ORB, and the interface
+is named HELLO_Gen. The service provided remains the same: starting from a character string supplied as the
+single argument, a character string derived from the concatenation of “Hello” and the input string is returned.
+This service is specified by the hello function.
+
+A documentation utility based on doxygen has been implemented to compile a documentation of corba services
+starting from comments located in idl files. Therefore, we will add few comments to our idl, respecting the
+doxygen formalism.
+A doxygen comment begins with "/\*" and ends with "\*/".
+They are grouped by module or subject, to provide a minimum structure for generated pages.
+We will use the following directive in our example::
+
+ \ingroup EXAMPLES
+
+specifying that the generated documentation forms part of the EXAMPLES group (please refer to
+the http://www.doxygen.org site for further information about doxygen).
+
+Finally, we will update the Makefile with the new component name::
+
IDL_FILES = HELLO_Gen.idl
-Implémentation C++
+C++ implementation
==================
-
-Les sources
+Sources
-----------
-
-L'implémentation C++ de notre module CORBA HELLO (interface idl HELLO_Gen) est faite dans le répertoire
-/src/HELLO::
+The C++ implementation of our CORBA HELLO module (HELLO_Gen idl interface) is made in the src/HELLO directory::
HELLO.hxx
HELLO.cxx
-Au début du header de notre module (HELLO.hxx), les inclusions suivantes sont
-nécessaires::
+The following inclusions are necessary at the beginning of the header of our module (HELLO.hxx)::
#include <SALOMEconfig.h>
#include CORBA_SERVER_HEADER(HELLO_Gen)
#include "SALOME_Component_i.hxx"
-Le fichier SALOMEconfig.h contient un certain nombre de définitions utiles
-pour assurer l'indépendance du code par rapport à la version de CORBA
-utilisée. SALOME_Component_i.hxx contient l'interface de la classe
-d'implémentation C++ du composant de base Salome (idl Engines::Component).
-Enfin, la macro CORBA_SERVER_HEADER assure l'indépendance des noms de fichiers
-d'inclusion par rapport à l'implémentation de l'ORB CORBA.
+The SALOMEconfig.h file contains a number of definitions useful for making the code independent from
+the version of CORBA used. SALOME_Component_i.hxx contains the interface of the C++ implementation class
+of the SALOME basic component (idl Engines::EngineComponent). Finally, the CORBA_SERVER_HEADER macro
+makes inclusion file names independent of the implementation of the CORBA ORB.
-Après cela, nous définissons une classe d'implémentation, nommée HELLO, dérivant de
-POA_HELLO_ORB::HELLO_Gen (classe abstraite générée automatiquement par CORBA lors de la
-compilation de l'idl) et de Engines_Component_i (car l'interface idl HELLO_Gen
-dérive de Engines::Component comme tout composant Salome). Cette classe
-contient un constructeur dont les arguments sont imposés par CORBA, un
-destructeur virtuel, et une méthode makeBanner fournissant le service souhaité::
+The next step is to define an implementation class called HELLO, derived from POA_HELLO_ORB::HELLO_Gen (abstract class
+generated automatically by CORBA during the compilation of the idl) and Engines_Component_i (because
+the HELLO_Gen idl interface is derived from Engines::EngineComponent like every SALOME component).
+This class contains a constructor whose arguments are imposed by SALOME, a virtual destructor, hello, goodbye and copyOrMove methods providing the required service::
class HELLO:
public POA_HELLO_ORB::HELLO_Gen,
public Engines_Component_i
{
public:
- HELLO(CORBA::ORB_ptr orb,
- PortableServer::POA_ptr poa,
- PortableServer::ObjectId * contId,
- const char *instanceName,
- const char *interfaceName);
- virtual ~HELLO();
- char* makeBanner(const char* name);
+ HELLO(CORBA::ORB_ptr orb,
+ PortableServer::POA_ptr poa,
+ PortableServer::ObjectId * contId,
+ const char *instanceName,
+ const char *interfaceName);
+ virtual ~HELLO();
+ HELLO_ORB::status hello ( const char* name );
+ HELLO_ORB::status goodbye( const char* name );
+ void copyOrMove( const HELLO_ORB::object_list& what,
+ SALOMEDS::SObject_ptr where,
+ CORBA::Long row, CORBA::Boolean isCopy );
+
};
-La fonction makeBanner prend comme argument et renvoit un char*, projection C++ du type CORBA/IDL
-string.
-La documentation complète du mapping c++ de l'IDL est fournie par l'OMG sur
-son site internet : http://www.omg.org/cgi-bin/doc?ptc/00-01-02.
+The hello and goodbye functions use a char* as an argument and return status of the operation.
+The list of the statuses is defined in the HELLO_Gen.idl, see status enumeration for details.
-Enfin, nous fournissons l'interface (normalisé) de la fonction HELLOEngine_factory, qui
-sera appelée par le "FactoryServer C++" pour charger le composant HELLO:
-::
+Finally, we supply the standard interface of the HELLOEngine_factory function that will be called by the “FactoryServer C++”
+to load the HELLO component::
extern "C"
- PortableServer::ObjectId * HELLOEngine_factory(
- CORBA::ORB_ptr orb,
- PortableServer::POA_ptr poa,
- PortableServer::ObjectId * contId,
- const char *instanceName,
- const char *interfaceName);
-
-
-Dans le fichier source (HELLO.cxx) se trouvent les définitions
-du constructeur et de la fonction d'instanciation
-HELLOEngine_factory (toutes deux normalisées!), et de makeBanner:
-
-::
-
- char* HELLO::makeBanner(const char* name)
- {
- string banner="Hello, ";
- banner+=name;
- return CORBA::string_dup(banner.c_str());
- }
-
-Dans cette fonction, l'emploi de string_dup (fonction déclarée dans le
-namespace CORBA) n'est pas obligatoire (on aurait pu utiliser l'opérateur new),
-mais conseillé car ces fonctions permettent aux ORB d'utiliser des mécanismes
-spéciaux de gestion de la mémoire sans avoir à redéfinir les opérateurs new
-globaux.
-
-Makefile
---------
-
-Dans le makefile, il faut définir certaines cibles::
-
- VPATH=.:@srcdir@:@top_srcdir@/idl
- LIB = libHELLOEngine.la
- LIB_SRC = HELLO.cxx
- LIB_SERVER_IDL = HELLO_Gen.idl
- LIB_CLIENT_IDL = SALOME_Component.idl SALOME_Exception.idl Logger.idl
- CPPFLAGS += -I${KERNEL_ROOT_DIR}/include/salome
- LDFLAGS+= -lSalomeContainer -lOpUtil -L${KERNEL_ROOT_DIR}/lib/salome
-
-Passons en revue chacune de ces cibles.
-
-- LIB contient le nom *normalisé* (lib<Nom_Module>Engine.la) le nom de la
- librairie, LIB_SRC définit le nom des fichiers sources, et VPATH les
- repertoire où l'on peut les trouver.
-- LIB_SERVER_IDL contient le nom des fichiers idl implémentés par le module.
-- LIB_CLIENT_IDL contient le nom des idl où sont définis les services CORBA
- utilisés par le module. HELLO utilise Logger.idl via les macros "MESSAGE",
- SALOME_Component.idl et SALOME_Exception.idl via l'héritage de HELLO_ORB
-- Il faut ajouter à CPPFLAGS le chemin pour les fichiers includes utilisés
- (SALOMEconfig.h, SALOME_Component_i.hxx et utilities.h se trouvent dans
- ${KERNEL_ROOT_DIR}/include/salome)
-- La classe HELLO utilise les librairies lib (pour Engines_Component_i) et
- libOptUtil (pour PortableServer et Salome_Exception). On indique donc le nom
- de ces librairies et leur chemin dans LDFLAGS.
- D'autres librairies sont souvent utiles, par exemple libsalomeDS si on
- implémente la persistence, ou libSalomeNS si on utilise le naming service.
-
-
-Pilotage du composant depuis Python (mode TUI)
-==============================================
-
-Lors de la compilation du module, la cible lib du Makefile dans /idl a
-provoqué la génération d'un stub python (souche côté client générée à partir
-de l'idl et offrant une interface dans le langage client - ici python.
-Concrètement, un module python HELLO_ORB contenant une classe
-_objref_HELLO_Gen sont créés, permettant de faire appel aux services de notre
-module C++ depuis python. Mettons ceci en application. Pour cela, nous lançons
-Salome en mode TUI::
-
- cd $HELLO_ROOT_DIR/bin/salome
- python -i runSalome.py --modules=HELLO --xterm --logger --containers=cpp,python --killall
-
-Depuis la fenêtre python, nous importons le module LifeCycle, et utilisons ses
-services pour charger notre composant Dans la conteneur C++ FactoryServer::
+ PortableServer::ObjectId * HELLOEngine_factory(CORBA::ORB_ptr orb,
+ PortableServer::POA_ptr poa,
+ PortableServer::ObjectId * contId,
+ const char *instanceName,
+ const char *interfaceName);
+
+
+The definitions of the constructor and the HELLOEngine_factory instantiation function (both normalized!),
+hello, goodbye and copyOrMove are given in the source file (HELLO.cxx)::
+
+ HELLO_ORB::status HELLO::hello( const char* name )
+ {
+ ...
+ }
+
+ HELLO_ORB::status HELLO::goodbye( const char* name )
+ {
+ ...
+ }
+
+ void HELLO::copyOrMove( const HELLO_ORB::object_list& what,
+ SALOMEDS::SObject_ptr where,
+ CORBA::Long row, CORBA::Boolean isCopy )
+ {
+ ...
+ }
+
+CMakeLists.txt
+--------------
+Create and add library to the project::
+
+ # --- options ---
+ # additional include directories
+ INCLUDE_DIRECTORIES(
+ ${KERNEL_INCLUDE_DIRS}
+ ${OMNIORB_INCLUDE_DIR}
+ ${PROJECT_BINARY_DIR}
+ ${PROJECT_BINARY_DIR}/idl
+ )
+ # libraries to link to
+ SET(_link_LIBRARIES
+ ${OMNIORB_LIBRARIES}
+ ${KERNEL_SalomeIDLKernel}
+ ${KERNEL_OpUtil}
+ ${KERNEL_SalomeContainer}
+ SalomeIDLHELLO
+ )
+ # --- headers ---
+ # header files / no moc processing
+ SET(HELLO_HEADERS
+ HELLO.hxx
+ )
+ # --- sources ---
+ # sources / static
+ SET(HELLO_SOURCES
+ HELLO.cxx
+ )
+ # --- rules ---
+ ADD_LIBRARY(HELLOEngine ${HELLO_SOURCES})
+ TARGET_LINK_LIBRARIES(HELLOEngine ${_link_LIBRARIES} )
+ INSTALL(TARGETS HELLOEngine EXPORT ${PROJECT_NAME}TargetGroup DESTINATION ${SALOME_INSTALL_LIBS})
+ INSTALL(FILES ${HELLO_HEADERS} DESTINATION ${SALOME_INSTALL_HEADERS})
+
+Review some of components:
+
+- HELLO_HEADERS contains the header files.
+- HELLO_SOURCES defines the name of source files
+- HELLOEngine - library name.
+- SALOME_INSTALL_LIBS path defines the directories in which library will be install.
+- Command INCLUDE_DIRECTORIES used to add /bin directories of some modules and packages.
+- Variable _link_LIBRARIES contains path to libraries of dependent modules and packages.
+
+Controlling the component from Python (TUI mode)
+=====================================================
+When the module is compiled, the lib target of the Makefile in /idl provoked generation of a Python
+stub (stub at the customer end generated from the idl and providing an interface in the client language – in this case Python).
+Specifically, a HELLO_ORB python module containing a classe_objref_HELLO_Gen is created and used to call services of our
+C++ module from Python. To put this into application, we run SALOME in TUI mode::
+
+ runSalome --modules=HELLO -t --pinter --logger --killall
+
+We import the LifeCycle module from the Python window, and use its services to load our component into the FactoryServer C++ container::
>>> import LifeCycleCORBA
- >>> lcc = LifeCycleCORBA.LifeCycleCORBA(clt.orb)
+ >>> lcc = LifeCycleCORBA.LifeCycleCORBA()
+ >>> import salome
+ >>> salome.salome_init()
+ createNewStudy
+ []
+ extStudy_1 1
>>> import HELLO_ORB
>>> hello = lcc.FindOrLoadComponent("FactoryServer", "HELLO")
-L'import de HELLO_ORB est nécessaire avant l'appel de FindOrLoadComponent,
-pour permettre de retourner un objet typé (opération de "narrowing"). Sinon,
-l'objet retourné est générique de type Engines::Component. Vérifions que notre
-objet hello est correctement typé, et appelons le service makeBanner::
+HELLO_ORB has to be imported before FindOrLoadComponent is called, so that a typed object can be
+returned (“narrowing” operation). Otherwise, the returned object is generic of the
+Engines::EngineComponent type.
+Let us check that hello object is correctly typed, and we will call the hello service::
>>> print hello
<HELLO_ORB._objref_HELLO_Gen instance at 0x8274e94>
- >>> mybanner=hello.makeBanner("Nicolas")
- >>> print mybanner
- Hello, Nicolas
-
-Les commandes précédentes ont été regroupées dans la fonction test du script
-/bin/runSalome.py.
+ >>> status=hello.hello("Nicolas")
+ >>> print status
+ OP_OK
+The previous commands were grouped in the test function of the /bin/runSalome.py script.
-Interface graphique
+Graphic interface
===================
-
Introduction
-------------
-
-Pour aller plus loin dans l'intégration de notre module, nous allons ajouter
-une interface graphique (développée en Qt), s'intégrant dans l'interface
-applicative de Salome (IAPP).
-On ne détaillera pas ici le fonctionnement de l'IAPP de Salome, mais pour
-résumer, l'IAPP gère une boucle d'évènements (clics souris, clavier, etc), et
-redirige après traitement ces évènements vers le module actif (le principe est
-qu'à un instant donné, *un* module est actif. Lorsqu'un module est activé, son
-IHM est chargée dynamiquement).
-Le programmeur de la GUI d'un module a donc à charge de définir les méthodes
-permettant de traiter correctement les évènements transmis. Parmi ces
-méthodes, citons les principales : OnGUIEvent(), OnMousePress(), OnMouseMove(),
-OnKeyPress(), DefinePopup(), CustomPopup().
-
-Choix des widgets
------------------
-
-Description xml
-```````````````
-La description des items de notre module se fait dans le fichier XML
-/ressources/HELLO_en.xml. Ce fichier est utilisé par l'IAPP pour charger
-dynamiquement l'IHM du module quand celle-ci est activée.
-Le principe est de définir par des balises les menus et boutons souhaités, et
-d'y associer des ID, qui seront récupérés par les fonctions gérant les
-évènemements IHM. Plusieures possibilités sont offertes:
-
-- ajout d'items à des menus déjà existant, auquel cas il faut reprendre les
- balises du menu pré-existant, et y ajouter les nouveaux items. Dans
- l'exemple qui suis, on ajoute le Menu **Hello** et l'item **MyNewItem** au
- menu File, dont l'ID vaut 1::
-
- <menu-item label-id="File" item-id="1" pos-id="">
- <submenu label-id="Hello" item-id="19" pos-id="8">
- <popup-item item-id="190" pos-id="" label-id="MyNewItem" icon-id="" tooltip-id="" accel-id="" toggle-id="" execute-action=""/>
- </submenu>
- <endsubmenu />
- </menu-item>
-
-- Création de nouveaux menus. Pour le module HELLO, nous ajoutons un menu
- HELLO, avec un unique item de label "Get banner"::
-
- <menubar>
- <menu-item label-id="HELLO" item-id="90" pos-id="3">
- <popup-item item-id="901" label-id="Get banner" icon-id="" tooltip-id="Get HELLO banner" accel-id="" toggle-id="" execute-action=""/>
- </menu-item>
- </menubar>
-
-- Ajout d'un bouton dans la barre à boutons. Dans l'exemple suivant, nous
- créons un deuxième point d'entrée pour notre action "Get banner", sous forme
- d'un bouton associé au même ID "901". L'icône est spécifiée par la le champ
- icon-id, qui doit être un fichier graphique 20x20 pixels au format png::
-
- <toolbar label-id="HELLO">
- <toolbutton-item item-id="901" label-id="Get banner" icon-id="ExecHELLO.png"
- tooltip-id="Get HELLO banner" accel-id="" toggle-id="" execute-action=""/>
- </toolbar>
-
-Convention
-``````````
-A chaque menu ou item est associé un ID. Les numéros entre 1 et 40 sont
-réservés à l'IAPP. Les numéros d'ID suivent une certaine règle, quoique
-celle-ci ne soit pas obligatoire. Au menu "HELLO" est associé l'ID 90. Son
-unique item "Get banner" a l'ID 901. Un deuxième item aurait l'ID 902, et un
-sous item l'ID 9021.
-
-
-Implémentation de l'IHM
------------------------
-
-L'implémentation C++ de l'IHM est faite dans le répertoire /src/HELLOGUI.
-Le header HELLOGUI.h déclare de la classe HELLOGUI, et
-contient des directives Qt (Q_OBJECT). De ce fait, il doit être processé par
-le compilateur moc (Qt Meta Model Compiler). Pour cette raison, l'extension du
-fichier est .h et dans le Makefile nous ajoutons la cible::
-
- LIB_MOC = HELLOGUI.h
-
-Le fichier source HELLO.cxx contient la définition des fonctions membres, et
-le Makefile permet de construire une librairie libHELLOGUI (le nom est
-normalisé poour permettre le chargement dynamique : lib<NomModule>GUI.
-
-Gestion des évènements
-``````````````````````
-Pour l'IHM d'HELLO, nous définissons la fonction HELLOGUI::OnGUIEvent, qui
-sera appelé à chaque évènement. Cette fonction contient essentiellement une
-structure switch permettant de traiter l'ID reçu en argument::
-
- switch (theCommandID)
- {
- case 901:
- // Traitement de "Get banner"
- ...
- case 190:
- // Traitement de "MyNewItem"
- ...
- }
-
-Le traitement standard consiste à récupérer des données d'entrée (ici, le
-prénom via une fenêtre de dialogue QInputDialog::getText), à récupérer une
-poignée sur le composant CORBA interfacé afin d'appeler le service souhaité
-(ici, getBanner), et d'afficher le résultat obtenu ().
+----------------
+To go further with the integration of our module, we will add a graphic interface (developed in Qt) that is
+integrated into the SALOME application interface (IAPP). We will not describe operation of the SALOME IAPP herein,
+but in summary, the IAPP manages an event loop (mouse click, keyboard, etc.) and after processing these events
+redirects them towards the active module (the principle is that **a single** module is active at a given moment.
+When a module is activated, its Graphic User Interface is dynamically loaded).
+Therefore the programmer of a module GUI defines methods to process transmitted events correctly.
+The most important of these events are OnGUIEvent(), OnMousePress(), OnMouseMove(), OnKeyPress(), DefinePopup(), CustomPopup().
-Classes disponibles
-````````````````````
-Pour les dialogues avec l'utilisateur, il est possible d'utiliser n'importe
-quelle classe fournie par Qt (http://doc.trolltech.com/3.2/classes.html).
-Cependant, lorque c'eset possible, il est préférable d'utiliser les fonctions
-QAD (Qt Application Desktop), définies dans KERNEL_SRC/src/SALOMEGUI, qui
-encapsulent les fonctions Qt correspondantes et gèrent mieux les
-communications avec l'IAPP. Ainsi, dans HELLOGUI, nous utilisons la classe
-QAD_MessageBox en lieu et place de la classe Qt QMessageBox.
+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 avaiable 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.
-Gestion du multi-linguisme
-``````````````````````````
-Qt fournit un outil d'aide au support du multi-linguisme. Celui-ci est
-repris dans salome. Le principe est simple : toutes les chaînes de caractères
-utilisées pour les labels des menus et les dialogues avec l'utilisateur
-sont encapsulés dans des appels à la fonction Qt tr() (pour translate), qui
-prend en argument un nom de label. Par exemple, pour demander à l'utilisateur
-de rentrer un prénom, nous utilisons la fonction getText, où les deux premiers
-arguments sont des labels encapsulés par tr()::
+- src/HELLOGUI/HELLOGUI.h
+- src/HELLOGUI/HELLOGUI.cxx
- myName = QInputDialog::getText( tr("QUE_HELLO_LABEL"), tr("QUE_HELLO_NAME"),
- QLineEdit::Normal, QString::null, &ok);
+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.
-Le nom des label est préfixé à titre indicatif par trois lettres et un underscore. Les codes
-suivants sont utilisés::
+- src/HELLOGUI/HELLO_msg_en.ts
+- src/HELLOGUI/HELLO_msg_fr.ts
+- src/HELLOGUI/HELLO_icons.ts
- - MEN_ : label menu
- - BUT_ : label bouton
- - TOT_ : aide tooltip
- - ERR_ : message d'erreur
- - WRN_ : message d'alerte
- - INF_ : message d'information
- - QUE_ : question
- - PRP_ : prompt dans la barre des status
+These files provide a description (internationalization) of GUI
+resources of the HELLO module. 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). 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.
+- resources
-La traduction des labels encapsulés par tr() est faite pour différents
-langages cibles (par exemple français et anglais) dans des fichiers nommés "<nom_module>_msg_<langage>.po".
-<langage> correspond au code du langage, on a choisi **en** pour l'anglais et
-**fr** pour le français. Ce fichier doit contenir pour chaque clé sa
-traduction, par exemple::
+This optional directory usually contains different resources files
+required for the correct operation of SALOME module.
- msgid "HELLOGUI::INF_HELLO_BANNER"
- msgstr "HELLO Information"
+- resources/HELLO.png
+- resources/handshake.png
+- resources/goodbye.png
+- resources/testme.png
-Le squelette de ce fichier peut être généré par l'utilitaire Qt findtr::
+These are different module icon files. 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.
- findtr HELLOGUI.cxx > HELLO_msg_en.po
-puis éditer le fichier HELLO_msg_en.po pour remplir les traductions.
-Ces fichiers sont ensuite compilés par l'utilitaire **msg2qm** pour générer
-des binaires *.qm*. Pour cela, il faut remplir la cible LIB_MOC dans le
-Makefile::
+- resources/HELLOCatalog.xml.in
- PO_FILES = HELLO_msg_en.po HELLO_msg_fr.po
+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.
-Pour l'utilisateur final, le choix du langage se fait au niveau de chaque
-module dans le fichier ressources/config, en utilisant la commande::
- langage=<langage>
-
-Règles syntaxiques de nommage
+Syntax naming rules
=============================
-
-Dans ce qui précède, nous avons utilisé un certain nombre de règles de
-nommage. Le présent chapitre se propose de faire le point sur ces règles.
-Celles-ci ne sont pas toutes obligatoires, mais simplifient la compréhension
-si on les suit!
-
-+-------------------+------------------+----------------+---------------------------------------+
-| Règle | Formalisme | Exemple HELLO | Commentaire |
-+===================+==================+================+=======================================+
-| Nom du module | <Module> | HELLO | C'est le nom qui figure dans le |
-| | | | catalogue des modules |
-+-------------------+------------------+----------------+---------------------------------------+
-| Base CVS | <Module> | EXAMPLES | Si la base cvs contient plusieurs |
-| | | | modules, on prend un autre nom |
-+-------------------+------------------+----------------+---------------------------------------+
-| Repertoire source | <Module>_SRC | HELLO1_SRC | L'indice 1 est utilisé car on prévoit |
-| | | | plusieurs version du module |
-+-------------------+------------------+----------------+---------------------------------------+
-| Fichier idl | <Module>_Gen.idl | HELLO_Gen.idl | |
-| | | | |
-+-------------------+------------------+----------------+---------------------------------------+
-| Nom du module | <Module>_ORB | HELLO_ORB | On évite d'utiliser le nom du module |
-| CORBA | | | (conflits) |
-+-------------------+------------------+----------------+---------------------------------------+
-| Nom de | <Module>_Gen | HELLO_Gen | La compilation de l'idl génère une |
-| l'interface CORBA | | | classe abstraite |
-| | | | POA_<Module>_ORB::<Module>_Gen |
-+-------------------+------------------+----------------+---------------------------------------+
-| fichier source | <Module>.cxx | HELLO.cxx | Dans le répertoire /src/<Module> |
-| | | | |
-+-------------------+------------------+----------------+---------------------------------------+
-| Classe | <Module> | HELLO | Cette classe hérite de |
-| d'implémentation | | | POA_HELLO_ORB::HELLO_Gen |
-+-------------------+------------------+----------------+---------------------------------------+
-| Fonction | <Module>_ | HELLO_Engine | Cette fonction est appelée par |
-| d'instanciation | Engine_factory | factory | le FactoryServer de Salome |
-+-------------------+------------------+----------------+---------------------------------------+
-| Catalogue des | <Module>Catalog | HELLOCatalog | Dans /ressources |
-| modules | .xml | .xml | |
-+-------------------+------------------+----------------+---------------------------------------+
-| Nom de la | lib<Module>Engine| libHELLOEngine | Dans le répertoire /src/<Module> |
-| librairie C++ | | | |
-+-------------------+------------------+----------------+---------------------------------------+
-| Librairie C++ | lib<Module>GUI | libHELLOGUI | Dans le répertoire /src/<Module>GUI |
-| de l'IHM | | | |
-+-------------------+------------------+----------------+---------------------------------------+
-| Variable | <Module>_ROOT_DIR| HELLO_ROOT_DIR | |
-| d'environnement | | | |
-+-------------------+------------------+----------------+---------------------------------------+
-| ... | ... | ... | ... |
-| | | | |
-+-------------------+------------------+----------------+---------------------------------------+
+A number of naming rules were used in the above description. This chapter gives more details about these rules.
+They are not all compulsory, but they make it easy to understand the program if they are respected!
+
+======================== ======================== ===================== =============================================================================
+ Rules Formalism HELLO example Comment
+======================== ======================== ===================== =============================================================================
+ Module name <Module> HELLO This is the name that appears in the modules catalog
+ CVS base <Module> EXAMPLES If the cvs base contains several modules, another name will be used.
+ Source directory <Module>_SRC HELLO1_SRC Index 1 is used because several versions of the module are provided.
+ Idl file <Module>_Gen.idl HELLO_Gen.idl
+ CORBA module name <Module>_ORB HELLO_ORB Avoid the use of the module name (conflicts)
+ CORBA interface name <Module>_Gen HELLO_Gen The idl compilation generates an abstract class POA_<Module>_ORB::<Module>_Gen
+ Source file <Module>.cxx HELLO.cxx In the /src/<Module> directory
+ Implementation class <Module> HELLO This class inherits from POA_HELLO_ORB::HELLO_Gen
+ Instantiation function <Module>_Engine_factory HELLO_Engine_factory This function is called by the SALOME Container
+ Modules catalog <Module>Catalog.xml HELLOCatalog.xml In /resources
+ C++ library name lib<Module>Engine HELLO-Engine In the /src/<Module> directory
+ GUI C++ name lib<Module>GUI libHELLOGUI In the /src/<Module>GUI directory
+ Environment variable <Module>_ROOT_DIR… HELLO_ROOT_DIR
+ ... ... ... ...
+======================== ======================== ===================== =============================================================================
