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 configuration files (used in the build procedure of a
48 module), CMakeLists.txt files, IDL file that provides a definition
49 of a CORBA services implemented in a module and a set of source files
50 which are compiled by the build procedure to the module
51 CORBA engine library and (optionally) GUI library.
53 The following file structure is typical for the SALOME module:
58 + SalomeHELLOConfig.cmake.in
70 + FindSalomeHELLO.cmake
112 Note that other files can be optionally present.
114 The usual way of the sources directory tree structure initial creation
115 is to copy it from the existing SALOME module.
117 \warning The files of the platform base module (KERNEL) must not be
118 copied to initialise a module tree structure. It is usually preferable
119 to copy files from another module such as GEOM or MED.
121 The module name is HELLO, the component name is HELLO and all the
122 files are put in a directory named HELLO1_SRC.
123 Below is a short description of these files. Note, that files with .in
124 suffix are the cmake templates from which the actual files are
125 generated during the build procedure.
129 These files are input text files that contain the project parameters
130 and describe the flow control of the build process in simple CMake language as
131 a part of the build system based on CMake. These files define
132 the build procedure, namely, compilation and installation rules such as compiler
133 and linker options, installation destination folder, package version etc.
142 These files are a usual part of open source projects. These files are
143 used by developers to provide an additional information on a product,
144 like license, authors and distribution information, change log between
145 versions of a product, installation hints, etc.
147 - \c HELLO_version.h.in
149 This is an optional C++ header file, that specifies the version
150 macro-definitions which can be used, for example, in other modules to
151 check the version of the SALOME module (HELLO module in this
156 This directory contains additional administrative files used by the
159 - \c adm_local/cmake_files/FindSalomeHELLO.cmake
161 Some modules can need some external packages in order to compile and
162 run properly. The usual approach is to write a special *.cmake file
163 for the purpose of finding a certain piece of software and to set it's
164 libraries, include files and definitions into appropriate variables so that
165 they can be used in the build process of another project.
166 It is possible to include the standard CMake detection modules (FindXyz.cmake files,
167 located in the standard CMake installation directory) or, if CMake does not provide
168 a search procedure for some required software, it is necessary to create *.cmake
169 module for each pre-requisite.
171 Also, it is good idea to create and distribute *.cmake file for the project being
172 developed; it can be used then in the dependent projects. For example, HELLO module
173 installs a file FindSalomeHELLO.cmake that can be used for its detection.
175 To search SALOME HELLO module in some other project it will be only needed to write
176 the following code in CMakeLists.txt:
179 FIND_PACKAGE(SalomeHELLO)
184 This directory usually contains different scripts.
188 This file is used to document the module, it must give its version (at
189 least) and (optionally) compatibilities or incompatibilities with
190 other modules. This file is strongly recommended but is not essential
191 for operation of the module.
194 - \c bin/myrunSalome.py
196 These files are not essential but make the example easier to
197 use. These are scripts that can be used to run SALOME session with
202 This directory contains IDL files that specify the CORBA services
203 supplied by SALOME module.
205 - \c idl/HELLO_Gen.idl
207 This is the CORBA IDL definition of the services implemented by SALOME
212 This is a root directory of the module source codes. Usually it contains
213 one or more sub-directories that provide an implementation of module
214 libraries, executables, Python API modules, etc. The hierarchy of the
215 sources tree is arbitrary; it follows the specific module needs.
219 This directory provides implementation of engine library.
221 - \c src/HELLO/HELLO.hxx
222 - \c src/HELLO/HELLO.cxx
224 These files provide the implementation of a CORBA engine library of
225 the HELLO module. In particular, this is an implementation of the
226 services defined in the \c HELLO_Gen.idl file.
230 It is an optional directory that provides an implementation of HELLO
231 module's GUI library.
233 Strictly speaking, the GUI library is optional for each SALOME module.
234 In some cases it's enough to implement CORBA engine only. Then,
235 the services of the module will be available in a CORBA environment.
236 The module can be loaded to the SALOME container and its services
237 can be used in the SALOME supervision computation schemas, in Python
238 scripts or/and in C++ implementation of other modules.
240 A GUI library is necessary only if it is planned to access the module
241 functionality from the SALOME GUI session via menu actions, dialog boxes
244 - \c src/HELLOGUI/HELLOGUI.h
245 - \c src/HELLOGUI/HELLOGUI.cxx
247 These files provide the implementation of a GUI library of
248 the HELLO module. In particular, these files specify menus, toolbars,
249 dialog boxes and other such staff.
251 - \c src/HELLOGUI/HELLO_msg_en.ts
252 - \c src/HELLOGUI/HELLO_msg_fr.ts
253 - \c src/HELLOGUI/HELLO_icons.ts
255 These files provide a description (internationalization) of GUI
256 resources of the HELLO module. \c HELLO_msg_en.ts provides an English
257 translation of the string resources used in a module (there can be also
258 translation files for other languages, for instance French; these files
259 are distinguished by the language suffix). \c HELLO_icons.ts
260 defines images and icons resources used within the GUI library of
261 HELLO module. Please refer to Qt linguist documentation for more
266 This optional directory usually contains different resources files
267 required for the correct operation of SALOME module.
269 - \c resources/HELLO.png
270 - \c resources/handshake.png
271 - \c resources/goodbye.png
272 - \c resources/testme.png
274 These are different module icon files. \c HELLO.png file provides main icon
275 of HELLO module to be shown in the SALOME GUI desktop. Other files are
276 the icons for the functions implemented by the module; they are used
277 in the menus and toolbars.
279 - \c resources/HELLOCatalog.xml.in
281 The XML description of the CORBA services provided by the HELLO
282 module. This file is parsed by SALOME supervision module (YACS) to generate
283 the list of service nodes to be used in the calculation schemas. The
284 simplest way to create this file is to use Catalog Generator utility
285 provided by the SALOME KERNEL module, that can automatically generate
286 XML description file from the IDL file. In GUI, this utility is available
287 via the Tools main menu.
289 - \c resources/SalomeApp.xml.in
291 This file is essential for each SALOME module. It provides some parameters of
292 the module which define its behavior in SALOME. In particular it
293 should provide a section with the name corresponding to the name of a
294 module ("HELLO" in our case) with the following parameters:
296 <section name="HELLO">
297 <parameter name="name" value="Hello"/>
298 <parameter name="icon" value="HELLO.png"/>
299 <parameter name="version" value="@SALOMEHELLO_VERSION@"/>
300 <parameter name="documentation" value="hello_help"/>
304 The \a "name" parameter defines GUI name of a module. The \a "icon"
305 parameter defines a GUI icon of a module. Optional \a "version" parameter
306 defines the version of the module. The \a "documentation" parameter
307 provides a name for the help-related resource section (see below).
309 The section \a "resources" of a file specifies the directory that contains
310 resources of a module (icons, translation files, etc).
313 <section name="resources">
314 <parameter name="HELLO" value="%HELLO_ROOT_DIR%/share/salome/resources/hello"/>
318 The section \a "hello_help" provides information on the location of
319 the help page(s) and the eventual sub-menu in the Help menu. The name of this section
320 can be arbitrary, in such a case it should be specified in the main module's resources
321 section (see above). Alternatively, this section's name can have syntax
322 \a "<module_name>_documentation", where \a module_name is a name of the module.
323 If such section is present in the resource file, it is not necessary to specify it
324 in the module's main section.
326 Parameter \a "sub_menu" of the documentation section allows sepecifying the name of the
327 sub-menu in the Help main menu where the documentation materials of a module should be
331 <section name="hello_help" >
332 <parameter name="sub_menu" value="Samples"/>
333 <parameter name="%1 User's Guide" value="%HELLO_ROOT_DIR%/share/doc/salome/gui/HELLO/index.html"/>
339 This directory containes the files related to the module's documentation.
343 The \b Doxygen configuration file. The Doxygen is used to build this
344 documentation. The file \c doxyfile.in provides a rules for the
345 generation of module documentation.
349 An input file for the Doxygen, which provides a source of this documentation.
353 This sub-folder contains images used in the documentation.
357 This sub-folder contains auxiliary files used when generating documentation
358 by Doxygen, like header (\c header.html.in) and footer (\c footer.html)
359 of the HTML pages, style sheet (\c doxygen.css) etc.
361 \ref dev_steps "<< Previous"<br>\ref build_proc_files ">> Next"
363 \page build_proc_files Build procedure input files
365 In most cases SALOME uses \b CMake-based build system for modules.
366 CMake is a cross-platform build system which works on Linux, Windows
367 and other operating systems.
369 The \c CMakeLists.txt files are used to describe the build procedure,
372 - Test system configuration;
373 - Detect pre-requisites;
374 - Generate build rules (for example, standard UNIX makefiles on Linux,
375 MSVC solutions, etc).
377 Project's root directory provides main CMake configuration that allows
378 build all targets into one set of binaries and libraries. Each sub-directory
379 also includes CMake configuration file (CMakeLists.txt) that specifies
382 The file \c CMakeLists.txt in root directory of the HELLO module provides
383 basic build rules to be used in other \c CMakeLists.txt files.
384 It sets main properties of project: name, version, pre-requisites,
385 installation paths, programming languages being used by the project,
386 tree of sub-directories, etc.
388 A lot of files used by the build procedure of HELLO module are located
389 in SALOME KERNEL module (that is referenced by the \c KERNEL_ROOT_DIR
390 environment variable), namely in its \c salome_adm sub-folder.
391 Similarly, the \c GUI_ROOT_DIR environment variable is used for the
392 graphical user interface (GUI) module of SALOME; this module also
393 provides a set of configuration utilities (\c *.cmake files) in its
396 The files with an \c .in extension are the skeletons which are processed
397 by CMake to transform it to the resulting files in the build directory during
398 the configuration process.
400 \ref tree_structure "<< Previous"<br>\ref idl_dir ">> Next"
402 \page idl_dir The idl directory
404 The \c idl directory requires a \c CMakeLists.txt that must make the
405 compilation of the CORBA IDL \c HELLO_Gen.idl file and install all the
406 generated files into the correct module installation directories.
407 This is done by using \c OMNIORB_ADD_MODULE() CMake macro:
410 OMNIORB_ADD_MODULE(SalomeIDLHELLO HELLO_Gen.idl ${KERNEL_ROOT_DIR}/idl/salome ${KERNEL_SalomeIDLKernel})
411 INSTALL(TARGETS SalomeIDLHELLO EXPORT ${PROJECT_NAME}TargetGroup DESTINATION ${SALOME_INSTALL_LIBS})
415 The IDL file itself must define a CORBA component for which the name must
416 be different from the module name to avoid name conflicts and define a
417 CORBA interface that is derived at least from the \a EngineComponent interface
418 of the \a Engines module. In case of HELLO module, the name of the CORBA
419 component is \b HELLO_ORB and the name of the interface is \b HELLO_Gen.
421 \ref build_proc_files "<< Previous"<br>\ref src_dir ">> Next"
423 \page src_dir The src directory
425 The \c src directory contains all source files required to build CORBA engine and
426 (optionally) GUI libraries of the module. Each of these entities usually
427 has (but this is not actually obligatory) its own directory.
429 The \c CMakeLists.txt file triggers the path of sub-directories described
430 by the \a ADD_SUBDIRECTORY() command.
432 - \c src/HELLO sub-directory
434 This sub-directory contains the C++ source files that implement the engine
435 library of the module. The \c CMakeLists.txt defines the rules used to build
436 the engine library from these source files. The name of the module
437 engine library is predefined and should be set as \c lib\<MODULE\>Engine.so
438 where \c MODULE is a name of the module. In the case of the HELLO
439 module, the name of the engine library should be \c libHELLOEngine.so.
441 The \c HELLO.h, \c HELLO.cxx files implement \a HELLO class that is derived
442 from the \a HELLO_Gen interface of the \a HELLO_ORB__POA CORBA module and the
443 \a SALOME_Component_i class (base implementation of SALOME module engine
444 exported by the KERNEL module).
446 In particular, \a HELLO class implements \a hello() and \a goodbye() functions
447 that are defined in the IDL interface \a HELLO_ORB::HELLO_Gen.
450 HELLO_ORB::status HELLO::hello( SALOMEDS::Study_ptr study, const char* name )
454 HELLO_ORB::status HELLO::goodbye( SALOMEDS::Study_ptr study, const char* name )
460 In addition, \c HELLO.cxx implements a factory function which is used by
461 the SALOME container to create an instance of the HELLO CORBA engine
467 PortableServer::ObjectId* HELLOEngine_factory(
469 PortableServer::POA_ptr poa,
470 PortableServer::ObjectId* contId,
471 const char* instanceName,
472 const char* interfaceName )
474 HELLO* component = new HELLO( orb, poa, contId, instanceName, interfaceName );
475 return component->getId();
480 - \c src/HELLOGUI sub-directory
482 This directory contains the C++ source files that implement the GUI
483 library of HELLO module. By default, the name of the module
484 GUI library is predefined and should be set as \c lib\<MODULE\>.so
485 where \c MODULE is a name of the module. In the case of the HELLO
486 module, the name of the GUI library should be \c libHELLO.so. It is
487 also possible to use custom name of the GUI library of a module, but
488 in this case, in order to be possible to use this module in SALOME GUI
489 desktop, the name of the GUI library should be defined in the
490 \c SalomeApp.xml file, in the module's main section, using \a "library"
491 parameter, for example:
494 <section name="HELLO">
495 <parameter name="name" value="Hello"/>
496 <parameter name="icon" value="HELLO.png"/>
497 <parameter name="library" value="libMyHelloGUIlibrary.so"/>
501 The implementation of GUI library of the HELLO module should be done
502 according to the architecture and rules specified by the SALOME GUI
503 module. The main GUI module class (a\ HELLOGUI in our case) should be
504 derived from the \a SalomeApp_Module class.
506 The developer has to redefine a set of methods which define the
507 module behavior in GUI, for example, create menus, toolbars, define
508 context popup menus, objects selection behavior, implement dialog
511 Here below is a short description of these methods. For more details
512 please refer to the SALOME GUI module documentation.
514 - \a initialize() - module initialization; usually used to create
515 GUI actions, menus, toolbars and so on;
516 - \a activateModule() - module activation; perform actions which should
517 be done when the module is activated by the user, for example, show
518 related menus and toolbars;
519 - \a deactivateModule() - module deactivation; perform actions which should
520 be done when the module is deactivated by the user, for example,
521 hide related menus and toolbars;
522 - \a windows() - get a list and a position of the dockable windows to be
523 associated with the module; these windows will be automatically
524 opened and positioned according to the settings defined by the value
525 returned by this function;
526 - \a viewManagers() - get a list of the compatible viewers; these viewers
527 will be automatically opened/raised on the module activation;
528 - \a contextMenuPopup() - create and return context popup menu according
529 to the current selection;
530 - \a createPreferences() - initialize module's preferences;
531 - \a preferencesChanged() - callback function that is called when some
532 module's preference is changed by the user; allows to perform the
533 corresponding actions;
534 - \a createSelection() - create and return menu selection object; this is
535 a part of the context popup menu definition API;
536 - \a engineIOR() - get the reference to the module CORBA engine;
537 - \a moduleIcon() and \a iconName() - these methods can be used to customize
538 the module's main icon;
539 - \a displayer() - get the reference to the module's \a Displayer class; this
540 is the part of common Show/Hide functionality mechanism;
541 - \a storeVisualParameters() and \a restoreVisualParameters() - these methods
542 can be redefined to store/restore different visualization attributes of the
543 presentable data if it is supported by the module, for example transparency,
544 colors, display mode and other presentable parameters;
545 - \a canCopy(), \a copy(), \a canPaste(), \a paste() - these methods are the
546 part of the common Copy/Paste functionality;
547 - \a isDraggable(), \a isDropAccepted(), \a dropObjects() - these methods
548 are the part of the common Drag-n-Drop functionality;
549 - \a createOperation() - this function can be used as a part of the
550 transaction-based operations mechanism.
551 - \a renameAllowed(), \a renameObject() - can be used for in-place (Object
552 browser) renaming of the data entities, if it is supported by the module.
554 Note, that all of these methods are optional and need not be
555 obligatory implemented because \a SalomeApp_Module class provides a
556 base implementation of these functions. It's sometimes enough to
557 implement only some of them, depending on the module needs.
559 In the case of HELLO module, only the following methods are
560 implemented (other ones are just stubs, added for sample reasons):
562 - \a engineIOR() that initializes HELLO module's engine:
565 QString HELLOGUI::engineIOR() const
567 init(); // initialize engine, if necessary
568 CORBA::String_var anIOR = getApp()->orb()->object_to_string( myEngine.in() );
569 return QString( anIOR.in() );
573 - \a initialize() that creates actions, menus and toolbars for module's services
577 void HELLOGUI::initialize( CAM_Application* app )
579 // call the parent implementation
580 SalomeApp_Module::initialize( app );
582 // get reference to the desktop (used as a parent for actions)
583 QWidget* dsk = app->desktop();
584 // get resources manager
585 SUIT_ResourceMgr* resMgr = app->resourceMgr();
588 // ... Test me operation
589 createAction( OpTestMe, // operation id
590 tr( "TLT_OP_TESTME" ), // tooltip
591 resMgr->loadPixmap( "HELLO",tr( "ICON_OP_TESTME" ) ), // icon
592 tr( "MEN_OP_TESTME" ), // menu title
593 tr( "STS_OP_TESTME" ), // status tip
594 0, // accelerator (not set)
596 false, // togglable flag (no)
597 this, // action receiver
598 SLOT( testMe() ) ); // action slot
599 // create other actions ............
603 menuId = createMenu( tr( "MEN_FILE" ), -1, -1 ); // File menu
604 createMenu( separator(), menuId, -1, 10 ); // add separator to File menu
605 menuId = createMenu( tr( "MEN_FILE_HELLO" ), menuId, -1, 10 ); // File - Hello submenu
606 createMenu( OpTestMe, menuId ); // File - Hello - Test me
607 // create other menus ............
611 aToolId = createTool ( tr( "TOOL_TEST" ) ); // Test toolbar
612 createTool( OpTestMe, aToolId ); // Test - Test me
613 // create other toolbars ............
616 QtxPopupMgr* mgr = popupMgr();
617 mgr->insert( action( OpHello ), -1, -1 ); // Hello
618 mgr->setRule( action( OpHello ), baseRule + " and isComponent", QtxPopupMgr::VisibleRule );
619 // create other popup menu commands ............
623 - \a activateModule() that activates menus and toolbars
626 bool HELLOGUI::activateModule( SUIT_Study* theStudy )
628 // call parent implementation
629 bool bOk = SalomeApp_Module::activateModule( theStudy );
632 setMenuShown( true );
634 setToolShown( true );
636 // return the activation status
641 - \a deactivateModule() that deactivates menus and toolbars
644 bool HELLOGUI::deactivateModule( SUIT_Study* theStudy )
647 setMenuShown( false );
649 setToolShown( false );
651 // call parent implementation and return the activation status
652 return SalomeApp_Module::deactivateModule( theStudy );
656 - \a windows() that set-ups dockable windows requested by the module
659 void HELLOGUI::windows( QMap<int, int>& theMap ) const
661 // want Object browser, in the left area
662 theMap.insert( SalomeApp_Application::WT_ObjectBrowser,
663 Qt::LeftDockWidgetArea );
664 // want Python console, in the bottom area
665 theMap.insert( SalomeApp_Application::WT_PyConsole,
666 Qt::BottomDockWidgetArea );
670 - \a isDragable(), \a isDropAccepted() and \a dropObjects() methods that handle
671 the Drag-n-Drop operation
674 bool HELLOGUI::isDragable( const SUIT_DataObject* what ) const
676 // we allow dragging any HELLO object, except the top-level component
677 const SalomeApp_ModuleObject* aModObj = dynamic_cast<const SalomeApp_ModuleObject*>( what );
678 return ( aModObj == 0 );
681 bool HELLOGUI::isDropAccepted( const SUIT_DataObject* where ) const
683 // we allow dropping of all objects
687 void HELLOGUI::dropObjects( const DataObjectList& what, SUIT_DataObject* where,
688 const int row, Qt::DropAction action )
690 if (action != Qt::CopyAction && action != Qt::MoveAction)
691 return; // unsupported action
694 SalomeApp_DataObject* dataObj = dynamic_cast<SalomeApp_DataObject*>( where );
695 if ( !dataObj ) return; // wrong parent
696 _PTR(SObject) parentObj = dataObj->object();
698 // collect objects being dropped
699 HELLO_ORB::object_list_var objects = new HELLO_ORB::object_list();
700 objects->length( what.count() );
702 for ( int i = 0; i < what.count(); i++ ) {
703 dataObj = dynamic_cast<SalomeApp_DataObject*>( what[i] );
704 if ( !dataObj ) continue; // skip wrong objects
705 _PTR(SObject) sobj = dataObj->object();
706 objects[i] = _CAST(SObject, sobj)->GetSObject();
709 objects->length( count );
711 // call engine function
712 engine()->copyOrMove( objects.in(), // what
713 _CAST(SObject, parentObj)->GetSObject(), // where
715 action == Qt::CopyAction ); // isCopy
717 // update Object browser
718 getApp()->updateObjectBrowser( false );
722 An implemention of the \a hello() and \a goodbye() methods is quite simple.
723 These operations show the dialog box proposing the user to enter the name and
724 pass the name entered by the user to the engine side, using the corresponding
728 void HELLOGUI::hello()
730 SalomeApp_Study* study = dynamic_cast<SalomeApp_Study*>( application()->activeStudy() );
731 _PTR(Study) studyDS = study->studyDS();
735 QString name = QInputDialog::getText( getApp()->desktop(), tr( "QUE_HELLO_TITLE" ), tr( "QUE_ENTER_NAME" ),
736 QLineEdit::Normal, QString::null, &ok );
738 if ( ok && !name.trimmed().isEmpty() ) {
739 // say hello to SALOME
740 HELLO_ORB::status status = engine()->hello( _CAST(Study, studyDS)->GetStudy(), (const char*)name.toLatin1() );
742 // update Object browser
743 getApp()->updateObjectBrowser(true);
745 // process operation status
747 case HELLO_ORB::OP_OK:
749 SUIT_MessageBox::information( getApp()->desktop(),
750 tr( "INF_HELLO_TITLE" ),
751 tr( "INF_HELLO_MSG" ).arg( name ),
754 case HELLO_ORB::OP_ERR_ALREADY_MET:
755 // error: already said hello
756 SUIT_MessageBox::warning( getApp()->desktop(),
757 tr( "INF_HELLO_TITLE" ),
758 tr( "ERR_HELLO_ALREADY_MET" ).arg( name ),
761 case HELLO_ORB::OP_ERR_UNKNOWN:
764 SUIT_MessageBox::critical( getApp()->desktop(),
765 tr( "INF_HELLO_TITLE" ),
773 void HELLOGUI::goodbye()
775 SalomeApp_Application* app = dynamic_cast<SalomeApp_Application*>( application() );
776 SalomeApp_Study* study = dynamic_cast<SalomeApp_Study*>( application()->activeStudy() );
777 _PTR(Study) studyDS = study->studyDS();
778 LightApp_SelectionMgr* aSelMgr = app->selectionMgr();
783 SALOME_ListIO selected;
784 aSelMgr->selectedObjects( selected );
785 if ( selected.Extent() == 1 ) {
786 Handle(SALOME_InteractiveObject) io = selected.First();
787 _PTR(SObject) so = studyDS->FindObjectID( io->getEntry() );
789 _PTR(SComponent) comp = so->GetFatherComponent();
790 if ( comp && comp->ComponentDataType() == "HELLO" && io->getEntry() != comp->GetID() ) {
791 name = so->GetName().c_str();
796 // request user name if not specified
797 if ( name.isEmpty() ) {
799 name = QInputDialog::getText( getApp()->desktop(), tr( "QUE_GOODBYE_TITLE" ), tr( "QUE_ENTER_NAME" ),
800 QLineEdit::Normal, QString::null, &ok );
803 if ( !name.trimmed().isEmpty() ) {
804 // say goodby to SALOME
805 HELLO_ORB::status status = engine()->goodbye( _CAST(Study, studyDS)->GetStudy(), (const char*)name.toLatin1() );
807 // update Object browser
808 getApp()->updateObjectBrowser(true);
810 // process operation status
812 case HELLO_ORB::OP_OK:
814 SUIT_MessageBox::information( getApp()->desktop(),
815 tr( "INF_GOODBYE_TITLE" ),
816 tr( "INF_GOODBYE_MSG" ).arg( name ),
819 case HELLO_ORB::OP_ERR_DID_NOT_MEET:
820 // error: did not say hello yet
821 SUIT_MessageBox::warning( getApp()->desktop(),
822 tr( "INF_GOODBYE_TITLE" ),
823 tr( "ERR_GOODBYE_DID_NOT_MEET" ).arg( name ),
826 case HELLO_ORB::OP_ERR_UNKNOWN:
829 SUIT_MessageBox::critical( getApp()->desktop(),
830 tr( "INF_GOODBYE_TITLE" ),
839 Also, \c HELLOGUI.cxx provide an implementation of a factory function that is used
840 by the SALOME GUI to create an instance of the HELLO GUI class by demand.
841 It implements also another factory function to retrieve the
842 version number of the module (in the About dialog box for example):
846 CAM_Module* createModule()
848 return new HELLOGUI();
851 char* getModuleVersion()
853 return (char*)HELLO_VERSION_STR;
858 \ref idl_dir "<< Previous"<br>\ref bin_dir ">> Next"
860 \page bin_dir The bin directory
862 The file \c VERSION.in is used to document the module, it must define its
863 version and (optionally) its compatibilities or incompatibilities with
864 other modules. Therefore, it is strongly recommended but is not
865 essential for correct operation of the module.
867 The \c runAppli.in file is the equivalent of the \c runSalome script
868 distributed by the KERNEL module but configured to start SALOME
869 session with HELLO module only.
871 The \c myrunSalome.py file reuses part of functionality provided by the
872 KERNEL's \c runSalome.py script. It is used to run SALOME session and
873 start HELLO module in this session.
875 \ref src_dir "<< Previous"<br>\ref doc_dir ">> Next"
877 \page doc_dir The doc directory
879 This directory provides documentation files of the module. The
880 documentation of the module can be implemented in the arbitrary
881 way. But if you want your documentation to appear in the SALOME GUI
882 desktop's Help menu, some specific actions should be done as follows.
884 The documentation should be generated in the HTML format. For example,
885 the documentation of the HELLO module is generated using Doxygen
886 tool. It allows to generate structured set of HTML pages from the set
887 of input plain text files. Input source files should include Doxygen
888 tags and optionally direct HTML tags. For more details please refer to
889 the Doxygen documentation.
891 The resulting documentation of a module should include at least one
892 file \c index.html. All the HTML and image files should be exported by
893 the build procedure to the following directory:
894 \c \<module_installation_dir\>/share/doc/salome/gui/\<MODULE\>
895 where \c module_installation_dir is a module installation folder and
896 \c MODULE is its name. For example, for HELLO module, at least one file
898 \c \<HELLO_module_installation_dir\>/share/doc/salome/gui/HELLO/index.html.
900 The SALOME GUI automatically searches for the index.html file in the
901 mentioned module directory. If the file is found, the corresponding
902 menu command is automatically added to the Help menu of the SALOME GUI
905 \ref bin_dir "<< Previous"<br>\ref build_procedure ">> Next"
907 \page build_procedure Construction, installation
909 Before building HELLO module, please ensure that SALOME environment is
910 set properly. Assume that SALOME environment is set in env_products.sh
911 script. In order to build and install HELLO module, you have to
912 perform several steps:
915 [bash% ] source env_products.sh
916 [bash% ] mkdir HELLO_BUILD
917 [bash% ] cd HELLO_BUILD
918 [bash% ] cmake -DCMAKE_BUILD_TYPE=<Mode> -DCMAKE_INSTALL_PREFIX=<HELLO_module_installation_dir> ../HELLO1_SRC
920 [bash% ] make install
923 The first command sets environment for building project.
925 Second command creates a build directory for the HELLO module. Then
926 next step is to cd to this build directory. From this directory you
927 invoke cmake command, where <Mode> is build mode (Release or Debug),
928 <HELLO_module_installation_dir> is a destination folder to install HELLO module of SALOME.
929 By default (if CMAKE_INSTALL_PREFIX option is not given), HELLO module will be
930 configured for installation to the /usr directory that requires root permissions
931 to complete the installation.
933 Next steps - build the package (\c make) and install it (\c make install).
935 On each step, you have to ensure that the operation is finished correctly
936 (no errors raised). After the last step is finished, the HELLO module is built
937 and installed to the \c \<HELLO_module_installation_dir\> directory.
939 \ref doc_dir "<< Previous"<br>\ref run_procedure ">> Next"
941 \page run_procedure Running SALOME
943 Go to the the \c \<HELLO_module_installation_dir\> directory and type:
946 [bash% ] ./bin/salome/runAppli
949 This command runs SALOME session configured for KERNEL and the HELLO
950 module. At the end of running, the user will be prompted by the
951 Python interpreter command line configured for SALOME that provides
952 access to SALOME Python API (including CORBA interfaces).
954 The \c runAppli file is a shell script that executes a Python commands
955 running SALOME session by passing arguments to it in a command line:
958 ${KERNEL_ROOT_DIR}/bin/salome/envSalome.py python -i $HELLO_ROOT_DIR/bin/salome/myrunSalome.py --modules=HELLO --killall
961 These arguments state that the \c myrunSalome.py script located in the
962 HELLO module will be used, that the HELLO component will be
963 activated and all previously running SALOME sessions should be
966 This command will not function unless the following environment
967 variables have previously been set:
970 export KERNEL_ROOT_DIR=\<KERNEL_module_installation_dir\>
971 export HELLO_ROOT_DIR=\<HELLO_module_installation_dir\>
974 \warning It is possible that the SALOME run will not reach the end.
975 In some circumstances, the time to start CORBA servers may be long and
976 could exceed the timeout. If the reasons is that the time to
977 load dynamic libraries is long, it is possible that a second run
978 immediately afterwards will be successful.
980 \ref build_procedure "<< Previous"<br>\ref load_module ">> Next"
982 \page load_module Loading HELLO component
984 The \a HELLO_ORB module has to be imported before making a request to
985 load the component into the container, to obtain access to methods of
986 the component. This container is made accessible in the \c myrunSalome.py
987 by means of the \a container variable:
991 >> salome.salome_init()
993 >> c = container.load_impl("HELLO", "HELLO")
994 >> c.hello(salome.myStudy, "Christian")
997 The last instruction invokes HELLO module's service \a hello(). Proceed as
998 follows to see the CORBA objects created by these actions:
1004 \ref run_procedure "<< Previous"<br>\ref catalog_def ">> Next"
1006 \page catalog_def HELLO module catalog definition
1008 In the example from the previous chapter, the HELLO component was
1009 loaded by making a direct request to the SALOME container. This is not
1010 the standard method for loading of a component. The normal way uses
1011 the SALOME LifeCycle service that invokes SALOME Module Catalog
1012 services to identify the component and its properties and then calls
1013 the requested container to load the component.
1015 Before this method can be used, the component must be declared in a
1016 catalog in the XML format, for which the name must be
1017 \c \<MODULE\>Catalog.xml. In our case, it will be \c HELLOCatalog.xml.
1018 Usually this catalog is put to the resources sub-directory of the
1019 directory tree. The simplest way to create this file is to use Catalog
1020 Generator utility provided by the SALOME KERNEL module, that can
1021 automatically generate XML description file from the IDL file.
1023 \ref load_module "<< Previous"<br>\ref load_lcc ">> Next"
1025 \page load_lcc Loading HELLO component via LifeCycle service
1027 The method of loading the component is not very different from that
1028 is described above. The services of the LifeCycle module are used in
1029 this case instead of calling the container directly. The call sequence
1030 is contained in the \c myrunSalome.py \a test() function.
1034 salome.salome_init()
1036 c.hello(salome.myStudy, "Christian")
1039 The test function creates the LifeCycle object. It then asks for the
1040 HELLO component to be loaded in the \a FactoryServer container:
1045 Test function that creates an instance of HELLO component
1046 usage : hello=test(clt)
1048 import LifeCycleCORBA
1049 lcc = LifeCycleCORBA.LifeCycleCORBA(clt.orb)
1051 hello = lcc.FindOrLoadComponent("FactoryServer", "HELLO")
1055 \ref catalog_def "<< Previous"<br>\ref load_iapp ">> Next"
1057 \page load_iapp Loading from the GUI (IAPP)
1059 In order to activate HELLO module in the SALOME GUI desktop, the user
1060 should press the HELLO module's button on the \a Modules toolbar or
1061 select the name of the module in the combo box on this toolbar.
1063 The image file to be used as an icon of a module should be exported by
1064 the module build procedure. The icon file name is defined in \c SalomeApp.xml:
1066 <section name="HELLO">
1067 <parameter name="name" value="Hello"/>
1068 <parameter name="icon" value="HELLO.png"/>
1072 \ref load_lcc "<< Previous"