Version: 7.8.0
The src directory

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

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

  • src/HELLO sub-directory

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

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

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

HELLO_ORB::status HELLO::hello( SALOMEDS::Study_ptr study, const char* name )
{
...
}
HELLO_ORB::status HELLO::goodbye( SALOMEDS::Study_ptr study, const char* name )
{
...
}

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

extern "C"
{
PortableServer::ObjectId* HELLOEngine_factory(
CORBA::ORB_ptr orb,
PortableServer::POA_ptr poa,
PortableServer::ObjectId* contId,
const char* instanceName,
const char* interfaceName )
{
HELLO* component = new HELLO( orb, poa, contId, instanceName, interfaceName );
return component->getId();
}
}
  • src/HELLOGUI sub-directory

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

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

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

The developer has to redefine a set of methods which define the module behavior in GUI, for example, create menus, toolbars, define context popup menus, objects selection behavior, implement dialog boxes etc.

Here below is a short description of these methods. For more details please refer to the SALOME GUI module documentation.

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

Note, that all of these methods are optional and need not be obligatory implemented because SalomeApp_Module class provides a base implementation of these functions. It's sometimes enough to implement only some of them, depending on the module needs.

In the case of HELLO module, only the following methods are implemented (other ones are just stubs, added for sample reasons):

  • engineIOR() that initializes HELLO module's engine:
QString HELLOGUI::engineIOR() const
{
init(); // initialize engine, if necessary
CORBA::String_var anIOR = getApp()->orb()->object_to_string( myEngine.in() );
return QString( anIOR.in() );
}
  • initialize() that creates actions, menus and toolbars for module's services service:
void HELLOGUI::initialize( CAM_Application* app )
{
// call the parent implementation
SalomeApp_Module::initialize( app );
// get reference to the desktop (used as a parent for actions)
QWidget* dsk = app->desktop();
// get resources manager
SUIT_ResourceMgr* resMgr = app->resourceMgr();
// create actions
// ... Test me operation
createAction( OpTestMe, // operation id
tr( "TLT_OP_TESTME" ), // tooltip
resMgr->loadPixmap( "HELLO",tr( "ICON_OP_TESTME" ) ), // icon
tr( "MEN_OP_TESTME" ), // menu title
tr( "STS_OP_TESTME" ), // status tip
0, // accelerator (not set)
dsk, // parent
false, // togglable flag (no)
this, // action receiver
SLOT( testMe() ) ); // action slot
// create other actions ............
// create menus
int menuId;
menuId = createMenu( tr( "MEN_FILE" ), -1, -1 ); // File menu
createMenu( separator(), menuId, -1, 10 ); // add separator to File menu
menuId = createMenu( tr( "MEN_FILE_HELLO" ), menuId, -1, 10 ); // File - Hello submenu
createMenu( OpTestMe, menuId ); // File - Hello - Test me
// create other menus ............
// create toolbars
int aToolId;
aToolId = createTool ( tr( "TOOL_TEST" ) ); // Test toolbar
createTool( OpTestMe, aToolId ); // Test - Test me
// create other toolbars ............
// set-up popup menu
QtxPopupMgr* mgr = popupMgr();
mgr->insert( action( OpHello ), -1, -1 ); // Hello
mgr->setRule( action( OpHello ), baseRule + " and isComponent", QtxPopupMgr::VisibleRule );
// create other popup menu commands ............
}
  • activateModule() that activates menus and toolbars
bool HELLOGUI::activateModule( SUIT_Study* theStudy )
{
// call parent implementation
bool bOk = SalomeApp_Module::activateModule( theStudy );
// show own menus
setMenuShown( true );
// show own toolbars
setToolShown( true );
// return the activation status
return bOk;
}
  • deactivateModule() that deactivates menus and toolbars
bool HELLOGUI::deactivateModule( SUIT_Study* theStudy )
{
// hide own menus
setMenuShown( false );
// hide own toolbars
setToolShown( false );
// call parent implementation and return the activation status
return SalomeApp_Module::deactivateModule( theStudy );
}
  • windows() that set-ups dockable windows requested by the module
void HELLOGUI::windows( QMap<int, int>& theMap ) const
{
// want Object browser, in the left area
theMap.insert( SalomeApp_Application::WT_ObjectBrowser,
Qt::LeftDockWidgetArea );
// want Python console, in the bottom area
theMap.insert( SalomeApp_Application::WT_PyConsole,
Qt::BottomDockWidgetArea );
}
  • isDragable(), isDropAccepted() and dropObjects() methods that handle the Drag-n-Drop operation
bool HELLOGUI::isDragable( const SUIT_DataObject* what ) const
{
// we allow dragging any HELLO object, except the top-level component
const SalomeApp_ModuleObject* aModObj = dynamic_cast<const SalomeApp_ModuleObject*>( what );
return ( aModObj == 0 );
}
bool HELLOGUI::isDropAccepted( const SUIT_DataObject* where ) const
{
// we allow dropping of all objects
return true;
}
void HELLOGUI::dropObjects( const DataObjectList& what, SUIT_DataObject* where,
const int row, Qt::DropAction action )
{
if (action != Qt::CopyAction && action != Qt::MoveAction)
return; // unsupported action
// get parent object
SalomeApp_DataObject* dataObj = dynamic_cast<SalomeApp_DataObject*>( where );
if ( !dataObj ) return; // wrong parent
_PTR(SObject) parentObj = dataObj->object();
// collect objects being dropped
HELLO_ORB::object_list_var objects = new HELLO_ORB::object_list();
objects->length( what.count() );
int count = 0;
for ( int i = 0; i < what.count(); i++ ) {
dataObj = dynamic_cast<SalomeApp_DataObject*>( what[i] );
if ( !dataObj ) continue; // skip wrong objects
_PTR(SObject) sobj = dataObj->object();
objects[i] = _CAST(SObject, sobj)->GetSObject();
count++;
}
objects->length( count );
// call engine function
engine()->copyOrMove( objects.in(), // what
_CAST(SObject, parentObj)->GetSObject(), // where
row, // row
action == Qt::CopyAction ); // isCopy
// update Object browser
getApp()->updateObjectBrowser( false );
}

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

void HELLOGUI::hello()
{
SalomeApp_Study* study = dynamic_cast<SalomeApp_Study*>( application()->activeStudy() );
_PTR(Study) studyDS = study->studyDS();
// request user name
bool ok;
QString name = QInputDialog::getText( getApp()->desktop(), tr( "QUE_HELLO_TITLE" ), tr( "QUE_ENTER_NAME" ),
QLineEdit::Normal, QString::null, &ok );
if ( ok && !name.trimmed().isEmpty() ) {
// say hello to SALOME
HELLO_ORB::status status = engine()->hello( _CAST(Study, studyDS)->GetStudy(), (const char*)name.toLatin1() );
// update Object browser
getApp()->updateObjectBrowser(true);
// process operation status
switch( status ) {
case HELLO_ORB::OP_OK:
// everything's OK
SUIT_MessageBox::information( getApp()->desktop(),
tr( "INF_HELLO_TITLE" ),
tr( "INF_HELLO_MSG" ).arg( name ),
tr( "BUT_OK" ) );
break;
case HELLO_ORB::OP_ERR_ALREADY_MET:
// error: already said hello
SUIT_MessageBox::warning( getApp()->desktop(),
tr( "INF_HELLO_TITLE" ),
tr( "ERR_HELLO_ALREADY_MET" ).arg( name ),
tr( "BUT_OK" ) );
break;
case HELLO_ORB::OP_ERR_UNKNOWN:
default:
// other errors
SUIT_MessageBox::critical( getApp()->desktop(),
tr( "INF_HELLO_TITLE" ),
tr( "ERR_ERROR" ),
tr( "BUT_OK" ) );
break;
}
}
}
void HELLOGUI::goodbye()
{
SalomeApp_Application* app = dynamic_cast<SalomeApp_Application*>( application() );
SalomeApp_Study* study = dynamic_cast<SalomeApp_Study*>( application()->activeStudy() );
_PTR(Study) studyDS = study->studyDS();
LightApp_SelectionMgr* aSelMgr = app->selectionMgr();
QString name;
// get selection
SALOME_ListIO selected;
aSelMgr->selectedObjects( selected );
if ( selected.Extent() == 1 ) {
Handle(SALOME_InteractiveObject) io = selected.First();
_PTR(SObject) so = studyDS->FindObjectID( io->getEntry() );
if ( so ) {
_PTR(SComponent) comp = so->GetFatherComponent();
if ( comp && comp->ComponentDataType() == "HELLO" && io->getEntry() != comp->GetID() ) {
name = so->GetName().c_str();
}
}
}
// request user name if not specified
if ( name.isEmpty() ) {
bool ok;
name = QInputDialog::getText( getApp()->desktop(), tr( "QUE_GOODBYE_TITLE" ), tr( "QUE_ENTER_NAME" ),
QLineEdit::Normal, QString::null, &ok );
}
if ( !name.trimmed().isEmpty() ) {
// say goodby to SALOME
HELLO_ORB::status status = engine()->goodbye( _CAST(Study, studyDS)->GetStudy(), (const char*)name.toLatin1() );
// update Object browser
getApp()->updateObjectBrowser(true);
// process operation status
switch( status ) {
case HELLO_ORB::OP_OK:
// everything's OK
SUIT_MessageBox::information( getApp()->desktop(),
tr( "INF_GOODBYE_TITLE" ),
tr( "INF_GOODBYE_MSG" ).arg( name ),
tr( "BUT_OK" ) );
break;
case HELLO_ORB::OP_ERR_DID_NOT_MEET:
// error: did not say hello yet
SUIT_MessageBox::warning( getApp()->desktop(),
tr( "INF_GOODBYE_TITLE" ),
tr( "ERR_GOODBYE_DID_NOT_MEET" ).arg( name ),
tr( "BUT_OK" ) );
break;
case HELLO_ORB::OP_ERR_UNKNOWN:
default:
// other errors
SUIT_MessageBox::critical( getApp()->desktop(),
tr( "INF_GOODBYE_TITLE" ),
tr( "ERR_ERROR" ),
tr( "BUT_OK" ) );
break;
}
}
}

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

extern "C" {
CAM_Module* createModule()
{
return new HELLOGUI();
}
char* getModuleVersion()
{
return (char*)HELLO_VERSION_STR;
}
}

<< Previous
>> Next