README

   1 --------------------------------------
   2 LIGHT module : README file
   3 --------------------------------------
   4
   5 Contents:
   6
   7 1. General description
   8 2. Functionality
   9 3. Implementation
  10 4. Building
  11 5. Launching
  12
  13 ----------------------
  14 1. General description
  15 ----------------------
  16
  17 The LIGHT module presents a simple no-CORBA-engine SALOME 3 compliant module.
  18 This module proposes a way how to create a modules which have only GUI library but nevertheless
  19 should be integrated into SALOME 3 CORBA-based architecture.
  20
  21 The LIGHT module uses default SALOMEDS-based persistence mechanism provided by SALOME GUI library
  22 in order to store/load it's data.
  23
  24 This sample module is a simple text file reader. Each empty line in the file read from the file
  25 is presented in the data tree as the beginning of new paragraph. Paragraphs can be empty.
  26 So the data tree hierarchy has tree levels:
  27
  28 Root
  29   |__ Paragraph
  30   |        |____ Text line
  31   |        |____ Text line
  32   |        |____ ...
  33   |__ Paragraph
  34   |__ Paragraph
  35   |        |____ Text line
  36   |        |____ ...
  37   |__ ...
  38
  39
  40 ----------------------
  41 2. Functionality
  42 ----------------------
  43
  44 The module functionality includes the following user actions:
  45
  46 - "File" menu:
  47
  48   - "Load text file"       : reads and loads the contents of text file to the data model;
  49                              the previous contents of data model is erased.
  50
  51   - "Save text flie"       : dumps the contents of the data model to the text file.
  52
  53 - "LIGHT" menu:
  54
  55   - "Edit selected line"   : allows user to edit the selected text line.
  56
  57   - "Insert new text line" : inserts the new text line entered by the user before the selected one;
  58                              if there is no selection, new line is added to the end of the data tree.
  59
  60   - "Remove line"          : removes the selected line.
  61
  62   - "Clear all"            : clears all the contents of the data model.
  63
  64
  65 All these actions except saving of the text file change the structure of the underlying text file, so the data tree is
  66 rebuilt correspondingly.
  67 Some of these commands are also avaiable via the context popup menu for the selected in the Object Browser data objects.
  68
  69 Saving/restoring of the data is performed by using of default SALOMEDS-based persistence mechanism provided by SALOME GUI
  70 via embedded SalomeApp engine.
  71 Note: immediately after opening of the sudy file the LIGHT module data are not displayed in the Object Browser. To see it
  72 you should activate the module. Such behaviour takes place because the LIGHT module does not publish any data in the SALOMEDS study.
  73
  74 ----------------------
  75 3. Implementation
  76 ----------------------
  77
  78 Here below is a short description of classes implemented in this package.
  79
  80 * LIGHTGUI.h + LIGHTGUI.cxx :
  81
  82 LIGHTGUI class                : This class presents a GUI module itself, exported by the static function.
  83 inherits SalomeApp_Module     : SALOME GUI application loads it when user activates the module by clicking the
  84                               : corresponding button on the components toolbar.
  85                               : The LIGHTGUI class is responsible for the creation of the data model. It creates
  86                               : user actions and then dispatches them to the corresponding slots.
  87                               : Method engineIOR() of this class returns empty string which means that this
  88                               : module uses default persistence mechanism provided by the SALOME GUI via SalomeApp
  89                               : engine (ensure that your configuration file SalomeApp.xml or .SalomeApprc.3.x.x
  90                               : includes "SalomeAppEngine" module in the <embedded> parameter of the <launch> section.
  91
  92 * LIGHTGUI_DataModel.h + LIGHTGUI_DataModel.cxx :
  93
  94 LIGHTGUI_DataModel class     : This class defines an internal organization of the module's data and the way how these
  95 inherits SalomeApp_DataModel : data should be presented in the study (e.g. in the Object Browser). In addition this class
  96                              : includes methods which modify the data tree: loading/saving of the text file,
  97                              : inserting/removing of the text line, etc.
  98
  99 * LIGHTGUI_DataObject.h + LIGHTGUI_DataObject.cxx :
 100
 101 LIGHTGUI_DataObject class    : This class presents an elementary unit of the data model. It includes presentation methods
 102 inherits CAM_DataObject      : like: name(), icon(), toolTip(), etc.
 103                              : Take an attention on the virtual inheritance of this class.
 104
 105 LIGHTGUI_ModuleObject class  : This class presents a root object of the module's data tree.
 106 inherits LIGHTGUI_DataObject,: LIGHTGUI_ModuleObject inherits SUIT_DataObject through the different branches, so virtual
 107          CAM_RootObject      : inheritance is needed here (see above).
 108
 109 * LIGHTGUI_DataOwner.h + LIGHTGUI_DataOwner.cxx :
 110
 111 LIGHTGUI_DataOwner class     : The instances of this class are engaged in the selection mechanism allowing the identification
 112 inherits SUIT_DataOwner      : of the data objects.
 113
 114 * LIGHTGUI_OBSelector.h + LIGHTGUI_OBSelector.cxx :
 115
 116 LIGHTGUI_OBSelector class    : This class allows the interacting with the LIGHT module's data objects in the Object Browser.
 117 inherits SUIT_Selector       : When activating the LIGHT module replaces the Object Browser selector by it's own one and
 118                              : restores the previous selector back when deactivating. The main goal of this class is to pick up
 119                              : selected objects and notify the application when selection is changed by the user.
 120
 121 * LIGHTGUI_Selection.h + LIGHTGUI_Selection.cxx
 122
 123 LIGHTGUI_Selection class     : This class provides the methods of defining the context popup menu contents for the selected
 124 inherits Selection           : objects by using of popup menu manager from the Qtx library.
 125          from QtxPopupMgr    :
 126
 127 * LIGHT_msg_en.po + LIGHT_images.po :
 128                              : Text and graphic resources of the module..
 129
 130 ----------------------
 131 4. Building
 132 ----------------------
 133
 134 The building process of the LIGHT module is inherited from standard SALOME packages and includes the following steps:
 135
 136 >> cd LIGHT_SRC
 137 >> mkdir ../LIGHT_BUILD
 138 >> cd ../LIGHT_BUILD
 139 >> ../LIGHT_SRC/build_configure
 140 >> ../LIGHT_SRC/configure [ configure-flags ]
 141 >> make
 142 >> make install (optional)
 143
 144 ----------------------
 145 5. Launching
 146 ----------------------
 147
 148 Set the LIGHT_ROOT_DIR environment variable to point to your LIGHT module binary distribution.
 149 Then append the following parameters in your configuration file (SalomeApp.xml in ${GUI_ROOT_DIR}/share/salome/resources
 150 folder or .SalomeApprc.3.x.x in your home directory, where 3.x.x is a your SALOME distribution version number):
 151
 152 ...
 153 <section name="launch" >
 154   <parameter name="modules" value="LIGHT" />
 155 </section>
 156 <section name="resources" >
 157   <parameter name="LIGHT" value="${LIGHT_ROOT_DIR}/share/salome/resources" />
 158 </section>
 159 <section name="LIGHT" >
 160   <parameter name="name" value="Light" />
 161   <parameter name="icon" value="LIGHT.png" />
 162 </section>
 163 ...
 164
 165 The launch SALOME in a usual way:
 166
 167 ${KERNEL_ROOT_DIR}/bin/salome/runSalome