doc/salome/gui/input/text_user_interface.doc

   1 /*!
   2
   3 \page tui_page Using salome.py module
   4
   5 The Python module salome.py provides a functionality to access main
   6 SALOME features from the Python console (either embedded in GUI
   7 desktop or external one).
   8
   9 To use salome.py module, import it into the Python interpreter and
  10 initialize it by calling \c salome_init() function:
  11
  12 \code
  13 import salome
  14 salome.salome_init()
  15 \endcode
  16
  17 The salome.py Python module provides a set of variables and functions
  18 allowing access to different elements of the current SALOME
  19 session (this Python interpreter is connected to).
  20 This page gives a short description of most useful variables and
  21 functions.
  22
  23 \li \b orb Reference to the CORBA::ORB instance
  24
  25 This variable can be used to initialize different CORBA-related
  26 elements of the SALOME session (for example, naming service, etc).
  27 For example, to get an access to the SALOME naming service, you can
  28 use the following commands:
  29 \code
  30 import SALOME_NamingServicePy
  31 NS = SALOME_NamingServicePy.SALOME_NamingServicePy_i(salome.orb)
  32 \endcode
  33
  34 The \b orb variable is also useful when it is necessary to convert
  35 CORBA reference object to its string representation (IOR) and vice
  36 versa:
  37 \code
  38 studyIOR = salome.orb.object_to_string(salome.myStudy)
  39 study    = salome.orb.string_to_object(studyIOR)
  40 is_same  = salome.myStudy._is_equivalent(study) # is_same = True
  41 \endcode
  42
  43 \li \b naming_service SALOME naming service instance
  44
  45 This variable can be used to register/find objects created in a
  46 distributed environment. For example, to get access to the SALOME
  47 Module Catalog server, use \c Resolve() method:
  48 \code
  49 import SALOME_ModuleCatalog
  50 mc = salome.naming_service.Resolve('/Kernel/ModulCatalog')
  51 \endcode
  52
  53 Similarly, method \c Register() can be used to register objects
  54 in the naming service:
  55 \code
  56 salome.naming_service.Register(myObject,'/My/Object/Path')
  57 o = salome.naming_service.Resolve('/My/Object/Path')
  58 is_same = myObject._is_equivalent(o) # is_same = True
  59 \endcode
  60
  61 \li \b lcc Life Cycle CORBA class instance
  62
  63 This object can be used to get access to CORBA engine part of some
  64 SALOME module, available in the current SALOME session. The following
  65 code returns a reference to the Geometry module engine, loading it if
  66 necessary:
  67 \code
  68 import GEOM
  69 geom = salome.lcc.FindOrLoadComponent('FactoryServer', 'GEOM')
  70 \endcode
  71 \b Note, that in the above example, \e "FactoryServer" is a name of the
  72 SALOME container, where Geometry module engine should be loaded.
  73
  74 \li \b myStudyManager Reference to the study manager
  75
  76 SALOMEDS Study manager is used to manipulate with the studies: create,
  77 open, save, close. It also can be used to find the study by its
  78 numerical ID or name. The code below demonstrates main
  79 functionalities of a study manager:
  80 \code
  81 # create new study with the name "MyStudy"
  82 new_study = salome.myStudyManager.NewStudy("MyStudy")
  83
  84 # open study from file /home/user/MyStudy.hdf
  85 study = salome.myStudyManager.OpenStudy("/home/user/MyStudy.hdf")
  86
  87 # save study
  88 salome.myStudyManager.Save(study, False) # not using multifile save mode
  89
  90 # save study in ASCII format
  91 salome.myStudyManager.SaveASCII(study, True) # using multifile save mode
  92
  93 # save study with the new file path
  94 salome.myStudyManager.SaveAs("/home/user/MyStudy.hdf", study, False)
  95
  96 # save study with the new file path in ASCII format
  97 salome.myStudyManager.SaveAsASCII("/home/user/MyStudy.hdf", study, False)
  98
  99 # close study
 100 salome.myStudyManager.Close(study)
 101
 102 # get list of all opened studies
 103 studies = salome.myStudyManager.GetOpenStudies()
 104
 105 # find study by its numerical ID (integer value starting from 1)
 106 study = salome.myStudyManager.GetStudyByID(studyID)
 107
 108 # find study by its name
 109 study = salome.myStudyManager.GetStudyByName("/home/user/MyStudy.hdf")
 110
 111 # ...
 112 \endcode
 113
 114 \li \b myStudy Reference to the current (active) study
 115
 116 This variable can be used to manipulate with the date of the study:
 117 create data tree, assign attributes of different types to the objects
 118 in a data tree, create references between objects, etc.
 119
 120 \b Note, that the term "active" or "current" study does not make much
 121 sense outise the GUI Python console. When working in GUI, user always
 122 deals with one only top-level study, which desktop is currently on the
 123 top if the windows stack. This is what is called \e "active study".
 124 In TUI mode (without GUI or outside GUI), user has to manipulate with
 125 studies manually; no any special control for the life cycle of the
 126 study is done. In TUI mode, \c salome.muStudy variable is an instance
 127 of the first study created when you call salome_init() function.
 128
 129 The following code demonstrates some examples of \c salome.myStudy
 130 variable usage. For more details please refer to the SALOMEDS.idl file
 131 documentation.
 132
 133 \code
 134 # get study name
 135 studyName = salome.myStudy._get_Name()
 136
 137 # get study numerical ID
 138 studyID = salome.myStudy._get_StudyId()
 139
 140 # find SALOMEDS component by its type
 141 scomponent = FindComponent("MyComponent")
 142
 143 # find SALOMEDS component by its entry ID
 144 scomponent = FindComponentID("0:1:1") # "0:1:1" is a component ID
 145
 146 # find SALOMEDS object by its name (first found object is returned)
 147 sobject = salome.myStudy.FindObject("MyObject")
 148
 149 # find SALOMEDS object by its entry ID
 150 sobject = salome.myStudy.FindObjectID() # "0:1:1:1" is an object ID
 151
 152 # find SALOMEDS object by its IOR attribute
 153 sobject = salome.myStudy.FindObjectIOR(IOR)
 154
 155 # find SALOMEDS object by its path in the data tree
 156 sobject = salome.myStudy.FindObjectByPath("/MyComponent/MyObject/MySubObject")
 157
 158 # get SALOMEDS object's path in a study data tree
 159 sobject_path = salome.myStudy.GetObjectPath(sobject)
 160
 161 # get study properties
 162 prop = salome.myStudy.GetProperties()
 163 prop.GetCreationDate() # get creation date
 164 prop.IsModified() # check if study has been modified (and not yet saved)
 165 prop.SetLocked(True) # lock the study (prohibit modifications)
 166 prop.IsLocked() # check if study is locked
 167
 168 # create objects with study builder
 169 builder = salome.myStudy.NewBuilder() # create builder
 170 comp = builder.NewComponent("MyComponent") # create a component of the "MyComponent" type
 171 attrName = builder.FindOrCreateAttribute(comp, "AttributeName")
 172 attrName.SetValue("MyComponent") # set name to the component
 173 object = builder.NewObject(comp) # create new object, a child of the component
 174 attrName = builder.FindOrCreateAttribute(object, "AttributeName")
 175 attrName.SetValue("MyObject") # set name to the object
 176 attrInt = builder.FindOrCreateAttribute(object, "AttributeInteger")
 177 attrInt.SetValue(123) # assign integer attribute to the object
 178 attrIOR = builder.FindOrCreateAttribute(object, "AttributeIOR")
 179 attrIOR.SetValue(IOR) # assign IOR attribute to the object (to point to some CORBA object)
 180
 181 # iterate through objects of the data tree with child iterator
 182 iter = salome.myStudy.NewChildIterator(comp) # initialize from the component
 183 iter.InitEx(True) # init recursive mode
 184 while iter.More():
 185       c = iter.Value()
 186       print c.GetID()
 187       iter.Next()
 188       pass
 189
 190 # ...
 191 \endcode
 192
 193 \li \b myStudyId Identifier of the current (active) study
 194
 195 This variable contains the numerical identifier of the current
 196 (active) study. It is an equivalent of \c
 197 salome.myStudy._get_StudyId() code.
 198
 199 \li \b myStudyName Name of the current (active) study
 200
 201 This variable contains the name of the current (active) study. It is
 202 an equivalent of \c salome.myStudy._get_Name() code.
 203
 204 \li \b DumpStudy() Print study contents
 205
 206 This function prints the study data object tree to the terminal
 207 window. The output for each object includes its entry ID, name, IOR
 208 (if there is one) and referenced object ID (for references). I.e.
 209 this is the same data the user can see in the Object Browser columns.
 210 \code
 211 salome.DumpStudy(salome.myStudy)
 212 \endcode
 213
 214 \li \b IDToSObject() Get SALOMEDS object by its entry ID.
 215
 216 This function checks if the SObject with the specified entry ID exists
 217 in the current study and returns it. Otherwise \c None is returned.
 218 \code
 219 sobject = salome.IDToSObject("0:1:1:1") # "0:1:1:1" is an object ID
 220 \endcode
 221 Actually this function is just a shortcut to the following code:
 222 \code
 223 sobject = salome.myStudy.FindObjectID("0:1:1:1")
 224 \endcode
 225
 226 \li \b IDToObject() Get CORBA object by its entry ID.
 227
 228 This function checks if the SObject with the specified entry ID exists
 229 in the current study, then retrieves IOR attribute from it and,
 230 finally, if IOR is not empty, returns CORBA object corresponding to
 231 the found SObject:
 232 \code
 233 object = salome.IDToObject("0:1:1:1") # "0:1:1:1" is an object ID
 234 \endcode
 235 Actually this function is just a shortcut to the following code:
 236 \code
 237 sobject = salome.myStudy.FindObjectID("0:1:1:1")
 238 if sobject:
 239    object = sobject.GetObject()
 240 else:
 241    object = None
 242 \endcode
 243
 244 \li \b ObjectToSObject() Get SALOMEDS object corresponding to the
 245 CORBA object.
 246
 247 This function finds an object in the current study which corresponds
 248 to the specified CORBA object (i.e. it has IOR attribute, pointing to
 249 the CORBA object). If there is no corresponding SALOMEDS object in the
 250 study, \c None is returned:
 251 \code
 252 sobject = salome.ObjectToSObject(object)
 253 \endcode
 254 Actually this function is just a shortcut to the following code:
 255 \code
 256 ior = salome.orb.object_to_string(object)
 257 sobject = salome.myStudy.FindObjectIOR(ior)
 258 \endcode
 259
 260 \li \b ObjectToID() Get SALOMEDS object entry ID corresponding to the
 261 CORBA object.
 262
 263 This function finds an object in the current study which corresponds
 264 to the specified CORBA object (i.e. it has IOR attribute, pointing to
 265 the CORBA object). If the object is found, its entry ID is returned,
 266 otherwise empty string is returned:
 267 \code
 268 entry = salome.ObjectToID(object)
 269 \endcode
 270 Actually this function is just a shortcut to the following code:
 271 \code
 272 ior = salome.orb.object_to_string(object)
 273 sobject = salome.myStudy.FindObjectIOR(ior)
 274 if sobject:
 275    entry = sobject.GetID()
 276 else:
 277    entry = ""
 278 \endcode
 279
 280 \li \b createNewStudy() Create new study
 281
 282 This function can be used to create new SALOME study. Returns an ID of
 283 the created study.
 284 \code
 285 studyId = salome.createNewStudy()
 286 study   = salome.myStudyManager.GetStudyByID(s)
 287 \endcode
 288
 289 \li \b generateName() Generate unique name
 290
 291 This function adds random numerical suffix to the passed string
 292 parameter ("Study" by default) and returns the resulting string:
 293 \code
 294 name_1 = salome.generateName() # name_1 is something like "Study682"
 295 name_1 = salome.generateName("Obj") # name_1 is something like "Obj32"
 296 \endcode
 297
 298 \li \b sg SWIG interface to the SALOME GUI
 299
 300 This variable provides an access to some GUI functions.
 301
 302 \b Note, that this variable is not available if you use salome.py
 303 Python module outside the GUI desktop, i.e. not in the embedded Python
 304 console (since SWIG library is linked directly to the GUI library).
 305
 306 The example of usage:
 307 \code
 308 # update Object browser contents
 309 salome.sg.updateObjBrowser(True)
 310
 311 # get active study ID
 312 studyId = salome.sg.getActiveStudyId()
 313
 314 # get active study name
 315 studyName = salome.sg.getActiveStudyName()
 316
 317 # get selected objects
 318 selCount = salome.sg.SelectedCount() # total number of selected items
 319 for i in range(selCount):
 320     print salome.sg.getSelected(i) # print entry ID of i-th selected item
 321
 322 # get list of all selected objects' IDs
 323 selected = salome.sg.getAllSelected()
 324
 325 # add object to the selection
 326 salome.sg.AddIObject("0:1:1:1") # "0:1:1:1" is an object ID
 327
 328 # remove object from the selection (make it unselected)
 329 salome.sg.RemoveIObject("0:1:1:1") # "0:1:1:1" is an object ID
 330
 331 # clear selection (set all objects unselected)
 332 salome.sg.ClearIObjects()
 333
 334 # display object in the current view (if possible)
 335 salome.sg.Display("0:1:1:1") # "0:1:1:1" is an object ID
 336 salome.sg.UpdateView() # update view
 337
 338 # erase object from the current view
 339 salome.sg.Erase("0:1:1:1") # "0:1:1:1" is an object ID
 340 salome.sg.UpdateView() # update view
 341
 342 # display all objects in the current view (if possible)
 343 salome.sg.DisplayAll()
 344 salome.sg.UpdateView() # update view
 345
 346 # erase all objects from the current view
 347 salome.sg.EraseAll()
 348 salome.sg.UpdateView() # update view
 349
 350 # set top, bottom, front, rear, left, right view
 351 salome.sg.ViewTop() # top view
 352 salome.sg.ViewBottom() # bottom view
 353 salome.sg.ViewFront() # front view
 354 salome.sg.ViewTop() #  back view
 355 salome.sg.ViewLeft() # left view
 356 salome.sg.ViewRight() # right view
 357
 358 # reset current view
 359 salome.sg.ResetView()
 360
 361 # get component symbolic name by its user name
 362 compName = salome.sg.getComponentName("Geometry") # compoName = "GEOM"
 363
 364 # get component user name by its symbolic name
 365 compName = salome.sg.getComponentUserName("SMESH") # compoName = "Mesh"
 366
 367 # ...
 368 \endcode
 369
 370 */