3 \mainpage Introduction to HELLO sample module
5 The purpose of the \b HELLO module is to describe briefly the different
6 steps in the development of a SALOME module in C++.
10 - \subpage tree_structure
11 - \subpage build_proc_files
16 - \subpage build_procedure
17 - \subpage run_procedure
18 - \subpage load_module
19 - \subpage catalog_def
23 \ref dev_steps ">> Next"
25 \page dev_steps Steps in construction of the example module
27 The example module chosen to illustrate the process of SALOME module
28 development is very simple. The module contains a single
29 component and this component provides several services called \b
31 Each of these functions accepts a reference to the SALOME study and
32 a character string as the arguments and returns the status of the operation.
33 The component also provides a simple GUI.
35 The steps in the development are as follows:
36 - create a module tree structure
37 - create a SALOME component that can be loaded by a C++ SALOME container
38 - configure the module so that the component is known to SALOME
41 \ref index "<< Previous"<br>\ref tree_structure ">> Next"
43 \page tree_structure Create the module tree structure
45 The first step in the development process is the creation of the
46 module tree file hierarchy. The typical SALOME module usually includes
47 some set of the configuration files (used in the build procedure of a
48 module), Makefiles, IDL file that provides a definition of a CORBA
49 services implemented in a module and a set of source files which are
50 compiled by the build procedure to the module CORBA engine library and
51 (optionally) GUI library.
53 The following file structure is typical for the SALOME module:
72 + make_common_starter.am
103 + HELLOCatalog.xml.in
117 Note that other files can be optionally present.
119 The usual way of the sources directory tree structure initial creation
120 is to copy it from the existing SALOME module.
122 \warning The files of the platform base module (KERNEL) must not be
123 copied to initialise a module tree structure. It is usually preferable
124 to copy files from another module such as GEOM or MED.
126 The module name is HELLO, the component name is HELLO and all the
127 files are put in a directory named HELLO1_SRC.
128 Below is a short description of these files. Note, that files with .in
129 suffix are the autoconf templates from which the actual files are
130 generated during the build procedure.
135 - \c make_common_starter.am
138 These files are a part of the build system based on GNU
139 automake/autoconf auto-tools. These files define the build procedure,
140 namely, compilation and installation rules like compiler and linker
141 options, installation destination folder, package version etc.
150 These files are also a usual part of the GNU auto-tools based build
151 procedure. These files are used by developers to provide an additional
152 information on a product, like license, authors and distribution
153 information, change log between versions of a product, installation
156 - \c HELLO_version.h.in
158 This is an optional C++ header file, specifying the version
159 macro-definitions which can be used, for example, in other modules to
160 check the version of the SALOME module (HELLO module in this
165 This directory contains additional administrative files used by the
168 - \c adm_local/unix/config_files/check_GUI.m4
169 - \c adm_local/unix/config_files/check_HELLO.m4
171 These files are another part of the GNU auto-tools based build
172 procedure. The scripts written in m4 language are usually used to test
173 an availability of some 3rd-party pre-requisite product, compiler
174 feature, different configuration options. For example, check_GUI.m4
175 file provides a procedure to test availability of SALOME GUI
176 module and thus specify if GUI library of HELLO module should be built
181 This directory usually contains different scripts.
185 This file is used to document the module, it must give its version (at
186 least) and (optionally) compatibilities or incompatibilities with
187 other modules. This file is strongly recommended but is not essential
188 for operation of the module.
191 - \c bin/myrunSalome.py
193 These files are not essential but make the example easier to
194 use. These are scripts that can be used to run SALOME session with
199 This directory contains IDL files that specify the CORBA services
200 supplied by SALOME module.
202 - \c idl/HELLO_Gen.idl
204 This is the CORBA IDL definition of the services implemented by SALOME
209 This is a root directory of the module source codes. Usually it contains
210 one or more sub-directories that provide an implementation of module
211 libraries, executables, Python API modules, etc. The hierarchy of the
212 sources tree is arbitrary; it follows the specific module needs.
216 This directory provides implementation of engine library.
218 - \c src/HELLO/HELLO.hxx
219 - \c src/HELLO/HELLO.cxx
221 These files provide the implementation of a CORBA engine library of
222 the HELLO module. In particular, this is an implementation of the
223 services defined in the \c HELLO_Gen.idl file.
227 It is an optional directory that provides an implementation of HELLO
228 module's GUI library.
230 Strictly speaking, the GUI library is optional for each SALOME module.
231 In some cases it's enough to implement CORBA engine only. Then,
232 the services of the module will be avaiable in a CORBA environment.
233 The module can be loaded to the SALOME container and its services
234 can be used in the SALOME supervision computation schemas, in Python
235 scripts or/and in C++ implementation of other modules.
237 A GUI library is necessary only if it is planned to access the module
238 functionality from the SALOME GUI session via menu actions, dialog boxes
241 - \c src/HELLOGUI/HELLOGUI.h
242 - \c src/HELLOGUI/HELLOGUI.cxx
244 These files provide the implementation of a GUI library of
245 the HELLO module. In particular, these files specify menus, toolbars,
246 dialog boxes and other such staff.
248 - \c src/HELLOGUI/HELLO_msg_en.ts
249 - \c src/HELLOGUI/HELLO_icons.ts
251 These files provide a description (internationalization) of GUI
252 resources of the HELLO module. \c HELLO_msg_en.ts provides an English
253 translation of the string resources used in a module (there can be also
254 translation files for other languages, for instance French; these files
255 are distinguished by the language suffix). \c HELLO_icons.ts
256 defines images and icons resources used within the GUI library of
257 HELLO module. Please refer to Qt linguist documentation for more
262 This optional directory usually contains different resources files
263 required for the correct operation of SALOME module.
265 - \c resources/HELLO.png
266 - \c resources/handshake.png
267 - \c resources/goodbye.png
268 - \c resources/testme.png
270 These are different module icon files. \c HELLO.png file provides main icon
271 of HELLO module to be shown in the SALOME GUI desktop. Other files are
272 the icons for the functions implemented by the module; they are used
273 in the menus and toolbars.
275 - \c resources/HELLOCatalog.xml.in
277 The XML description of the CORBA services provided by the HELLO
278 module. This file is parsed by SALOME supervision module (YACS) to generate
279 the list of service nodes to be used in the calculation schemas. The
280 simplest way to create this file is to use Catalog Generator utility
281 provided by the SALOME KERNEL module, that can automatically generate
282 XML description file from the IDL file. In GUI, this utility is available
283 via the Tools main menu.
285 - \c resources/SalomeApp.xml.in
287 This file is essential for each SALOME module. It provides some parameters of
288 the module which define its behavior in SALOME. In particular it
289 should provide a section with the name corresponding to the name of a
290 module ("HELLO" in our case) with the following parameters:
292 <section name="HELLO">
293 <parameter name="name" value="Hello"/>
294 <parameter name="icon" value="HELLO.png"/>
295 <parameter name="version" value="@VERSION@"/>
296 <parameter name="documentation" value="hello_help"/>
300 The \a "name" parameter defines GUI name of a module. The \a "icon"
301 parameter defines a GUI icon of a module. Optional \a "version" parameter
302 defines the version fo the module. The \a "documentation" parameter
303 provides a name for the help-related resource section (see below).
305 The section \a "resources" of a file specifies the directory that contains
306 resources of a module (icons, translation files, etc).
309 <section name="resources">
310 <parameter name="HELLO" value="%HELLO_ROOT_DIR%/share/salome/resources/hello"/>
314 The section \a "hello_help" provides information on the location of
315 the help page(s) and the eventual sub-menu in the Help menu. The name of this section
316 can be arbitrary, in such a case it should be specified in the main module's resources
317 section (see above). Alternatively, this section's name can have syntax
318 \a "<module_name>_documentation", where \a module_name is a name of the module.
319 If such section is present in the resource file, it is not necessary to specify it
320 in the module's main section.
322 Parameter \a "sub_menu" of the documentation section allows sepecifying the name of the
323 sub-menu in the Help main menu where the documentation materials of a module should be
327 <section name="hello_help" >
328 <parameter name="sub_menu" value="Samples"/>
329 <parameter name="%1 User's Guide" value="%HELLO_ROOT_DIR%/share/doc/salome/gui/HELLO/index.html"/>
335 This directory containes the files related to the module's documentation.
339 The \b Doxygen configuration file. The Doxygen is used to build this
340 documentation. The file \c doxyfile.in provides a rules for the
341 generation of module documentation.
345 An input file for the Doxygen, which provides a source of this documentation.
349 This sub-folder contains images used in the documentation.
353 This sub-folder contains auxiliary files used when generating documentation
354 by Doxygen, like header (\c header.html.in) and footer (\c footer.html)
355 of the HTML pages, style sheet (\c doxygen.css) etc.
357 \ref dev_steps "<< Previous"<br>\ref build_proc_files ">> Next"
359 \page build_proc_files Build procedure input files
361 In most cases SALOME uses \b autoconf, \b automake and other GNU auto-tools
362 to build the modules. The \c configure script is used for the build procedure
363 to test the system configuration and to pre-configure the module construction
366 The \c build_configure script provides a procedure that uses
367 \c configure.ac and set of \c Makefile.am files as input and uses \b autoconf
368 to generate the \c configure script and \b automake to generate \c Makefile.in
371 The files with an \c .in extension are the skeletons that are the input
372 of the \c configure script (to be more precise, these files should be
373 listed in the end of the \c configure.ac file in the \c AC_OUTPUT()
374 autoconf macro) and are transformed to the resulting files during the
375 configuration process.
377 Almost all files used for this process are located in SALOME
378 base module KERNEL that is referenced by the \c KERNEL_ROOT_DIR
379 environment variable, namely in its \c salome_adm sub-folder.
380 Similarly, the \c GUI_ROOT_DIR environment variable is used for the
381 graphical user interface (GUI) module of SALOME; this module also
382 provides a set of configuration utilities (m4 files) in its
383 \c adm_local folder. However, some files must be modified as a
384 function of the target module. This is the case for \c build_configure
385 and \c configure.ac files which usually need to be adapted to the module needs.
387 The file \c make_common_starter.am file in the \c adm_local directory of
388 the HELLO module provides basic build rules to be used in other
389 \c Makefile.am files. To refer to this file in any \c Makefile.am it is
390 necessary to use \a "include" clause:
393 include $(top_srcdir)/adm_local/unix/make_common_starter.am
396 The \c adm_local/unix/config_files is a directory in which the m4 files
397 that are used to test the configuration of the system in the configuration
398 process can be placed. If the \c salome_adm files are not sufficient,
399 additional configuration files can be put to the \c adm_local directory.
401 \ref tree_structure "<< Previous"<br>\ref idl_dir ">> Next"
403 \page idl_dir The idl directory
405 The \c idl directory requires a \c Makefile.am that must make the
406 compilation of the CORBA IDL \c HELLO_Gen.idl file and install all the
407 generated files into the correct module installation directories. The
408 \a BASEIDL_FILES target has to be modified to reach this goal.
410 The IDL file itself must define a CORBA component for which the name must
411 be different from the module name to avoid name conflicts and define a
412 CORBA interface that is derived at least from the \a EngineComponent interface
413 of the \a Engines module. In case of HELLO module, the name of the CORBA
414 component is \b HELLO_ORB and the name of the interface is \b HELLO_Gen.
416 \ref build_proc_files "<< Previous"<br>\ref src_dir ">> Next"
418 \page src_dir The src directory
420 The \c src directory contains all source files required to build CORBA engine and
421 (optionally) GUI libraries of the module. Each of these entities usually
422 has (but this is not actually obligatory) its own directory.
424 The \c Makefile.am simply triggers the path of sub-directories described
425 by the \a SUBDIRS target.
427 - \c src/HELLO sub-directory
429 This sub-directory contains the C++ source files that implement the engine
430 library of the module. The \c Makefile.am defines the rules used to build
431 the engine library from these source files. The name of the module
432 engine library is predefined and should be set as \c lib\<MODULE\>Engine.so
433 where \c MODULE is a name of the module. In the case of the HELLO
434 module, the name of the engine library should be \c libHELLOEngine.so.
436 The \c HELLO.h, \c HELLO.cxx files implement \a HELLO class that is derived
437 from the \a HELLO_Gen interface of the \a POA_HELLO_ORB CORBA module and the
438 \a SALOME_Component_i class (base implementation of SALOME module engine
439 exported by the KERNEL module).
441 In particular, \a HELLO class implements \a hello() and \a goodbye() functions
442 that are defined in the IDL interface \a HELLO_ORB::HELLO_Gen.
445 HELLO_ORB::status HELLO::hello( SALOMEDS::Study_ptr study, const char* name )
449 HELLO_ORB::status HELLO::goodbye( SALOMEDS::Study_ptr study, const char* name )
455 In addition, \c HELLO.cxx implements a factory function which is used by
456 the SALOME container to create an instance of the HELLO CORBA engine
462 PortableServer::ObjectId* HELLOEngine_factory(
464 PortableServer::POA_ptr poa,
465 PortableServer::ObjectId* contId,
466 const char* instanceName,
467 const char* interfaceName)
469 HELLO* myHELLO = new HELLO(orb, poa, contId, instanceName, interfaceName);
470 return myHELLO->getId();
475 - \c src/HELLOGUI sub-directory
477 This directory contains the C++ source files that implement the GUI
478 library of HELLO module. By default, the name of the module
479 GUI library is predefined and should be set as \c lib\<MODULE\>.so
480 where \c MODULE is a name of the module. In the case of the HELLO
481 module, the name of the GUI library should be \c libHELLO.so. It is
482 also possible to use custom name of the GUI library of a module, but
483 in this case, in order to be possible to use this module in SALOME GUI
484 desktop, the name of the GUI library should be defined in the
485 \c SalomeApp.xml file, in the module's main section, using \a "library"
486 parameter, for example:
489 <section name="HELLO">
490 <parameter name="name" value="Hello"/>
491 <parameter name="icon" value="HELLO.png"/>
492 <parameter name="library" value="libMyHelloGUIlibrary.so"/>
496 The implementation of GUI library of the HELLO module should be done
497 according to the architecture and rules specified by the SALOME GUI
498 module. The main GUI module class (a\ HELLOGUI in our case) should be
499 derived from the \a SalomeApp_Module class.
501 The developer has to redefine a set of methods which define the
502 module behavior in GUI, for example, create menus, toolbars, define
503 context popup menus, objects selection behavior, implement dialog
506 Here below is a short description of these methods. For more details
507 please refer to the SALOME GUI module documentation.
509 - \a initialize() - module initialization; usually used to create
510 GUI actions, menus, toolbars and so on;
511 - \a activateModule() - module activation; perform actions which should
512 be done when the module is activated by the user, for example, show
513 related menus and toolbars;
514 - \a deactivateModule() - module deactivation; perform actions which should
515 be done when the module is deactivated by the user, for example,
516 hide related menus and toolbars;
517 - \a windows() - get a list and a position of the dockable windows to be
518 associated with the module; these windows will be automatically
519 opened and positioned according to the settings defined by the value
520 returned by this function;
521 - \a viewManagers() - get a list of the compatible viewers; these viewers
522 will be automatically opened/raised on the module activation;
523 - \a contextMenuPopup() - create and return context popup menu according
524 to the current selection;
525 - \a createPreferences() - initialize module's preferences;
526 - \a preferencesChanged() - callback function that is called when some
527 module's preference is changed by the user; allows to perform the
528 corresponding actions;
529 - \a createSelection() - create and return menu selection object; this is
530 a part of the context popup menu definition API;
531 - \a engineIOR() - get the reference to the module CORBA engine;
532 - \a moduleIcon() and \a iconName() - these methods can be used to customize
533 the module's main icon;
534 - \a displayer() - get the reference to the module's \a Displayer class; this
535 is the part of common Show/Hide functionality mechanism;
536 - \a storeVisualParameters() and \a restoreVisualParameters() - these methods
537 can be redefined to store/restore different visualization attributes of the
538 presentable data if it is supported by the module, for example transparency,
539 colors, display mode and other presentable parameters;
540 - \a canCopy(), \a copy(), \a canPaste(), \a paste() - these methods are the
541 part of the common Copy/Paste functionality;
542 - \a isDraggable(), \a isDropAccepted(), \a dropObjects() - these methods
543 are the part of the common Drag-n-Drop functionality;
544 - \a createOperation() - this function can be used as a part of the
545 transaction-based operations mechanism.
546 - \a renameAllowed(), \a renameObject() - can be used for in-place (Object
547 browser) renaming of the data entities, if it is supported by the module.
549 Note, that all of these methods are optional and need not be
550 obligatory implemented because \a SalomeApp_Module class provides a
551 base implementation of these functions. It's sometimes enough to
552 implement only some of them, depending on the module needs.
554 In the case of HELLO module, only the following methods are
555 implemented (other ones are just stubs, added for sample reasons):
557 - \a engineIOR() that initializes HELLO module's engine:
560 QString HELLOGUI::engineIOR() const
562 init(); // initialize engine, if necessary
563 CORBA::String_var anIOR = getApp()->orb()->object_to_string( myEngine.in() );
564 return QString( anIOR.in() );
568 - \a initialize() that creates actions, menus and toolbars for module's services
572 void HELLOGUI::initialize( CAM_Application* app )
574 // call the parent implementation
575 SalomeApp_Module::initialize( app );
577 // get reference to the desktop (used as a parent for actions)
578 QWidget* dsk = app->desktop();
579 // get resources manager
580 SUIT_ResourceMgr* resMgr = app->resourceMgr();
583 // ... Test me operation
584 createAction( OpTestMe, // operation id
585 tr( "TLT_OP_TESTME" ), // tooltip
586 resMgr->loadPixmap( "HELLO",tr( "ICON_OP_TESTME" ) ), // icon
587 tr( "MEN_OP_TESTME" ), // menu title
588 tr( "STS_OP_TESTME" ), // status tip
589 0, // accelerator (not set)
591 false, // togglable flag (no)
592 this, // action receiver
593 SLOT( testMe() ) ); // action slot
594 // create other actions ............
598 menuId = createMenu( tr( "MEN_FILE" ), -1, -1 ); // File menu
599 createMenu( separator(), menuId, -1, 10 ); // add separator to File menu
600 menuId = createMenu( tr( "MEN_FILE_HELLO" ), menuId, -1, 10 ); // File - Hello submenu
601 createMenu( OpTestMe, menuId ); // File - Hello - Test me
602 // create other menus ............
606 aToolId = createTool ( tr( "TOOL_TEST" ) ); // Test toolbar
607 createTool( OpTestMe, aToolId ); // Test - Test me
608 // create other toolbars ............
611 QtxPopupMgr* mgr = popupMgr();
612 mgr->insert( action( OpHello ), -1, -1 ); // Hello
613 mgr->setRule( action( OpHello ), baseRule + " and isComponent", QtxPopupMgr::VisibleRule );
614 // create other popup menu commands ............
618 - \a activateModule() that activates menus and toolbars
621 bool HELLOGUI::activateModule( SUIT_Study* theStudy )
623 // call parent implementation
624 bool bOk = SalomeApp_Module::activateModule( theStudy );
627 setMenuShown( true );
629 setToolShown( true );
631 // return the activation status
636 - \a deactivateModule() that deactivates menus and toolbars
639 bool HELLOGUI::deactivateModule( SUIT_Study* theStudy )
642 setMenuShown( false );
644 setToolShown( false );
646 // call parent implementation and return the activation status
647 return SalomeApp_Module::deactivateModule( theStudy );
651 - \a windows() that set-ups dockable windows requested by the module
654 void HELLOGUI::windows( QMap<int, int>& theMap ) const
656 // want Object browser, in the left area
657 theMap.insert( SalomeApp_Application::WT_ObjectBrowser,
658 Qt::LeftDockWidgetArea );
659 // want Python console, in the bottom area
660 theMap.insert( SalomeApp_Application::WT_PyConsole,
661 Qt::BottomDockWidgetArea );
665 - \a isDragable(), \a isDropAccepted() and \a dropObjects() methods that handle
666 the Drag-n-Drop operation
669 bool HELLOGUI::isDragable( const SUIT_DataObject* what ) const
671 // we allow dragging any HELLO object, except the top-level component
672 const SalomeApp_ModuleObject* aModObj = dynamic_cast<const SalomeApp_ModuleObject*>( what );
673 return ( aModObj == 0 );
676 bool HELLOGUI::isDropAccepted( const SUIT_DataObject* where ) const
678 // we allow dropping of all objects
682 void HELLOGUI::dropObjects( const DataObjectList& what, SUIT_DataObject* where,
683 const int row, Qt::DropAction action )
685 if (action != Qt::CopyAction && action != Qt::MoveAction)
686 return; // unsupported action
689 SalomeApp_DataObject* dataObj = dynamic_cast<SalomeApp_DataObject*>( where );
690 if ( !dataObj ) return; // wrong parent
691 _PTR(SObject) parentObj = dataObj->object();
693 // collect objects being dropped
694 HELLO_ORB::object_list_var objects = new HELLO_ORB::object_list();
695 objects->length( what.count() );
697 for ( int i = 0; i < what.count(); i++ ) {
698 dataObj = dynamic_cast<SalomeApp_DataObject*>( what[i] );
699 if ( !dataObj ) continue; // skip wrong objects
700 _PTR(SObject) sobj = dataObj->object();
701 objects[i] = _CAST(SObject, sobj)->GetSObject();
704 objects->length( count );
706 // call engine function
707 engine()->copyOrMove( objects.in(), // what
708 _CAST(SObject, parentObj)->GetSObject(), // where
710 action == Qt::CopyAction ); // isCopy
712 // update Object browser
713 getApp()->updateObjectBrowser( false );
717 An implemention of the \a hello() and \a goodbye() methods is quite simple.
718 These operations show the dialog box proposing the user to enter the name and
719 pass the name entered by the user to the engine side, using the corresponding
723 void HELLOGUI::hello()
725 SalomeApp_Study* study = dynamic_cast<SalomeApp_Study*>( application()->activeStudy() );
726 _PTR(Study) studyDS = study->studyDS();
730 QString name = QInputDialog::getText( getApp()->desktop(), tr( "QUE_HELLO_TITLE" ), tr( "QUE_ENTER_NAME" ),
731 QLineEdit::Normal, QString::null, &ok );
733 if ( ok && !name.trimmed().isEmpty() ) {
734 // say hello to SALOME
735 HELLO_ORB::status status = engine()->hello( _CAST(Study, studyDS)->GetStudy(), (const char*)name.toLatin1() );
737 // update Object browser
738 getApp()->updateObjectBrowser(true);
740 // process operation status
742 case HELLO_ORB::OP_OK:
744 SUIT_MessageBox::information( getApp()->desktop(),
745 tr( "INF_HELLO_TITLE" ),
746 tr( "INF_HELLO_MSG" ).arg( name ),
749 case HELLO_ORB::OP_ERR_ALREADY_MET:
750 // error: already said hello
751 SUIT_MessageBox::warning( getApp()->desktop(),
752 tr( "INF_HELLO_TITLE" ),
753 tr( "ERR_HELLO_ALREADY_MET" ).arg( name ),
756 case HELLO_ORB::OP_ERR_UNKNOWN:
759 SUIT_MessageBox::critical( getApp()->desktop(),
760 tr( "INF_HELLO_TITLE" ),
768 void HELLOGUI::goodbye()
770 SalomeApp_Application* app = dynamic_cast<SalomeApp_Application*>( application() );
771 SalomeApp_Study* study = dynamic_cast<SalomeApp_Study*>( application()->activeStudy() );
772 _PTR(Study) studyDS = study->studyDS();
773 LightApp_SelectionMgr* aSelMgr = app->selectionMgr();
778 SALOME_ListIO selected;
779 aSelMgr->selectedObjects( selected );
780 if ( selected.Extent() == 1 ) {
781 Handle(SALOME_InteractiveObject) io = selected.First();
782 _PTR(SObject) so = studyDS->FindObjectID( io->getEntry() );
784 _PTR(SComponent) comp = so->GetFatherComponent();
785 if ( comp && comp->ComponentDataType() == "HELLO" && io->getEntry() != comp->GetID() ) {
786 name = so->GetName().c_str();
791 // request user name if not specified
792 if ( name.isEmpty() ) {
794 name = QInputDialog::getText( getApp()->desktop(), tr( "QUE_GOODBYE_TITLE" ), tr( "QUE_ENTER_NAME" ),
795 QLineEdit::Normal, QString::null, &ok );
798 if ( !name.trimmed().isEmpty() ) {
799 // say goodby to SALOME
800 HELLO_ORB::status status = engine()->goodbye( _CAST(Study, studyDS)->GetStudy(), (const char*)name.toLatin1() );
802 // update Object browser
803 getApp()->updateObjectBrowser(true);
805 // process operation status
807 case HELLO_ORB::OP_OK:
809 SUIT_MessageBox::information( getApp()->desktop(),
810 tr( "INF_GOODBYE_TITLE" ),
811 tr( "INF_GOODBYE_MSG" ).arg( name ),
814 case HELLO_ORB::OP_ERR_DID_NOT_MEET:
815 // error: did not say hello yet
816 SUIT_MessageBox::warning( getApp()->desktop(),
817 tr( "INF_GOODBYE_TITLE" ),
818 tr( "ERR_GOODBYE_DID_NOT_MEET" ).arg( name ),
821 case HELLO_ORB::OP_ERR_UNKNOWN:
824 SUIT_MessageBox::critical( getApp()->desktop(),
825 tr( "INF_GOODBYE_TITLE" ),
834 Also, \c HELLOGUI.cxx provide an implementation of a factory function that is used
835 by the SALOME GUI to create an instance of the HELLO GUI class by demand.
836 It implements also another factory function to retrieve the
837 version number of the module (in the About dialog box for example):
841 CAM_Module* createModule()
843 return new HELLOGUI();
846 char* getModuleVersion()
848 return (char*)HELLO_VERSION_STR;
853 \ref idl_dir "<< Previous"<br>\ref bin_dir ">> Next"
855 \page bin_dir The bin directory
857 The file \c VERSION.in is used to document the module, it must define its
858 version and (optionally) its compatibilities or incompatibilities with
859 other modules. Therefore, it is strongly recommended but is not
860 essential for correct operation of the module.
862 The \c runAppli.in file is the equivalent of the \c runSalome script
863 distributed by the KERNEL module but configured to start SALOME
864 session with HELLO module only.
866 The \c myrunSalome.py file reuses part of functionality provided by the
867 KERNEL's \c runSalome.py script. It is used to run SALOME session and
868 start HELLO module in this session.
870 \ref src_dir "<< Previous"<br>\ref doc_dir ">> Next"
872 \page doc_dir The doc directory
874 This directory provides documentation files of the module. The
875 documentation of the module can be implemented in the arbitrary
876 way. But if you want your documentation to appear in the SALOME GUI
877 desktop's Help menu, some specific actions should be done as follows.
879 The documentation should be generated in the HTML format. For example,
880 the documentation of the HELLO module is generated using Doxygen
881 tool. It allows to generate structured set of HTML pages from the set
882 of input plain text files. Input source files should include Doxygen
883 tags and optionally direct HTML tags. For more details please refer to
884 the Doxygen documentation.
886 The resulting documentation of a module should include at least one
887 file \c index.html. All the HTML and image files should be exported by
888 the build procedure to the following directory:
889 \c \<module_installation_dir\>/share/doc/salome/gui/\<MODULE\>
890 where \c module_installation_dir is a module installation folder and
891 \c MODULE is its name. For example, for HELLO module, at least one file
893 \c \<HELLO_module_installation_dir\>/share/doc/salome/gui/HELLO/index.html.
895 The SALOME GUI automatically searches for the index.html file in the
896 mentioned module directory. If the file is found, the corresponding
897 menu command is automatically added to the Help menu of the SALOME GUI
900 \ref bin_dir "<< Previous"<br>\ref build_procedure ">> Next"
902 \page build_procedure Construction, installation
904 Before building HELLO module, please ensure that SALOME environment is
905 set properly. Assume that SALOME environment is set in env_products.sh
906 script. In order to build and install HELLO module, you have to
907 perform several steps:
910 [bash% ] source env_products.sh
911 [bash% ] mkdir HELLO_BUILD
912 [bash% ] cd HELLO_BUILD
913 [bash% ] ../HELLO1_SRC/build_configure
914 [bash% ] ../HELLO1_SRC/configure --prefix=\<HELLO_module_installation_dir\>
916 [bash% ] make install
919 The first command creates a build directory for the HELLO module. Then
920 next step is to cd to this build directory. From this directory you
921 sequentially invoke \c build_configure, \c configure, \c make and \c make install
922 commands. On each step, you have to ensure that the operation is
923 finished correctly (no errors raised).
925 The \c \<HELLO_module_installation_dir\> variable above defines the
926 destination directory to which the HELLO module should be
927 installed. After the last step is finished, the HELLO module is built
928 and installed to the \c \<HELLO_module_installation_dir\> directory.
930 \ref doc_dir "<< Previous"<br>\ref run_procedure ">> Next"
932 \page run_procedure Running SALOME
934 Go to the the \c \<HELLO_module_installation_dir\> directory and type:
937 [bash% ] ./bin/salome/runAppli
940 This command runs SALOME session configured for KERNEL and the HELLO
941 module. At the end of running, the user will be prompted by the
942 Python interpreter command line configured for SALOME that provides
943 access to SALOME Python API (including CORBA interfaces).
945 The \c runAppli file is a shell script that executes a Python commands
946 running SALOME session by passing arguments to it in a command line:
949 ${KERNEL_ROOT_DIR}/bin/salome/envSalome.py python -i $HELLO_ROOT_DIR/bin/salome/myrunSalome.py --modules=HELLO --killall
952 These arguments state that the \c myrunSalome.py script located in the
953 HELLO module will be used, that the HELLO component will be
954 activated and all previously running SALOME sessions should be
957 This command will not function unless the following environment
958 variables have previously been set:
961 export KERNEL_ROOT_DIR=\<KERNEL_module_installation_dir\>
962 export HELLO_ROOT_DIR=\<HELLO_module_installation_dir\>
965 \warning It is possible that the SALOME run will not reach the end.
966 In some circumstances, the time to start CORBA servers may be long and
967 could exceed the timeout. If the reasons is that the time to
968 load dynamic libraries is long, it is possible that a second run
969 immediately afterwards will be successful.
971 \ref build_procedure "<< Previous"<br>\ref load_module ">> Next"
973 \page load_module Loading HELLO component
975 The \a HELLO_ORB module has to be imported before making a request to
976 load the component into the container, to obtain access to methods of
977 the component. This container is made accessible in the \c myrunSalome.py
978 by means of the \a container variable:
982 >> salome.salome_init()
984 >> c = container.load_impl("HELLO", "HELLO")
985 >> c.hello(salome.myStudy, "Christian")
988 The last instruction invokes HELLO module's service \a hello(). Proceed as
989 follows to see the CORBA objects created by these actions:
995 \ref run_procedure "<< Previous"<br>\ref catalog_def ">> Next"
997 \page catalog_def HELLO module catalog definition
999 In the example from the previous chapter, the HELLO component was
1000 loaded by making a direct request to the SALOME container. This is not
1001 the standard method for loading of a component. The normal way uses
1002 the SALOME LifeCycle service that invokes SALOME Module Catalog
1003 services to identify the component and its properties and then calls
1004 the requested container to load the component.
1006 Before this method can be used, the component must be declared in a
1007 catalog in the XML format, for which the name must be
1008 \c \<MODULE\>Catalog.xml. In our case, it will be \c HELLOCatalog.xml.
1009 Usually this catalog is put to the resources sub-directory of the
1010 directory tree. The simplest way to create this file is to use Catalog
1011 Generator utility provided by the SALOME KERNEL module, that can
1012 automatically generate XML description file from the IDL file.
1014 \ref load_module "<< Previous"<br>\ref load_lcc ">> Next"
1016 \page load_lcc Loading HELLO component via LifeCycle service
1018 The method of loading the component is not very different from that
1019 is described above. The services of the LifeCycle module are used in
1020 this case instead of calling the container directly. The call sequence
1021 is contained in the \c myrunSalome.py \a test() function.
1025 salome.salome_init()
1027 c.hello(salome.myStudy, "Christian")
1030 The test function creates the LifeCycle object. It then asks for the
1031 HELLO component to be loaded in the \a FactoryServer container:
1036 Test function that creates an instance of HELLO component
1037 usage : hello=test(clt)
1039 import LifeCycleCORBA
1040 lcc = LifeCycleCORBA.LifeCycleCORBA(clt.orb)
1042 hello = lcc.FindOrLoadComponent("FactoryServer", "HELLO")
1046 \ref catalog_def "<< Previous"<br>\ref load_iapp ">> Next"
1048 \page load_iapp Loading from the GUI (IAPP)
1050 In order to activate HELLO module in the SALOME GUI desktop, the user
1051 should press the HELLO module's button on the \a Modules toolbar or
1052 select the name of the module in the combo box on this toolbar.
1054 The image file to be used as an icon of a module should be exported by
1055 the module build procedure. The icon file name is defined in \c SalomeApp.xml:
1057 <section name="HELLO">
1058 <parameter name="name" value="Hello"/>
1059 <parameter name="icon" value="HELLO.png"/>
1063 \ref load_lcc "<< Previous"