]> SALOME platform Git repositories - modules/kernel.git/blob - src/KERNEL_PY/kernel/studyedit.py
Salome HOME
Merge branch 'V9_9_BR'
[modules/kernel.git] / src / KERNEL_PY / kernel / studyedit.py
1 # Copyright (C) 2007-2022  CEA/DEN, EDF R&D, OPEN CASCADE
2 #
3 # This library is free software; you can redistribute it and/or
4 # modify it under the terms of the GNU Lesser General Public
5 # License as published by the Free Software Foundation; either
6 # version 2.1 of the License, or (at your option) any later version.
7 #
8 # This library is distributed in the hope that it will be useful,
9 # but WITHOUT ANY WARRANTY; without even the implied warranty of
10 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
11 # Lesser General Public License for more details.
12 #
13 # You should have received a copy of the GNU Lesser General Public
14 # License along with this library; if not, write to the Free Software
15 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
16 #
17 # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
18 #
19
20 ## \defgroup studyedit studyedit
21 #  \{ 
22 #  \details
23 #  This module provides a new class \bStudyEditor to complement \bStudy
24 #  and \bStudyBuilder classes.
25 #  \}
26
27 """
28 This module provides a new class :class:`StudyEditor` to complement
29 :class:`Study` and :class:`StudyBuilder` classes.
30 """
31
32 import re
33
34 from salome.kernel import termcolor
35 from salome.kernel.logger import Logger
36
37
38 logger = Logger("salome.kernel.studyedit", color=termcolor.PURPLE)
39
40 _DEFAULT_CONTAINER = "FactoryServer"
41
42
43 ## This class provides utility methods to complement \b Study and
44 #  \b StudyBuilder classes. Those methods may be moved in those classes
45 #  in the future.
46 #  The preferred way to get a StudyEditor object is through the method
47 #  \b getStudyEditor which allows to reuse existing instance or through
48 #  the global module attribute \b EDITOR.
49 #
50 #  \param lcc This instance attribute provides access to the SALOME life cycle
51 #  CORBA service.
52 #
53 #  \param study This instance attribute provides access to the \b Study object.
54 #  It can be used to access the study but the attribute itself cannot
55 #  be modified.
56 #
57 #  \param builder This instance attribute provides access to the \b StudyBuilder
58 #  object. It can be used to edit the study but the attribute itself
59 #  cannot be modified.
60 #  \ingroup studyedit
61 class StudyEditor:
62     """
63     This class provides utility methods to complement :class:`Study` and
64     :class:`StudyBuilder` classes. Those methods may be moved in those classes
65     in the future.
66     The preferred way to get a StudyEditor object is through the method
67     :meth:`getStudyEditor` which allows to reuse existing instances.
68
69     .. attribute:: lcc
70     
71        This instance attribute provides access to the SALOME life cycle
72        CORBA service.
73
74     .. attribute:: study
75     
76        This instance attribute provides access to the :class:`Study` object.
77        It can be used to access the study but the attribute itself cannot
78        be modified.
79
80     .. attribute:: builder
81
82        This instance attribute provides access to the :class:`StudyBuilder`
83        object. It can be used to edit the study but the attribute itself
84        cannot be modified.
85
86     """
87
88     @property
89     def study(self):
90         """Attribute that provides access to the study."""
91         import salome
92         salome.salome_init()
93         if salome.myStudy is None:
94             raise Exception("Study doesn't exist")
95         return salome.myStudy
96
97     @property
98     def builder(self):
99         """Attribute that provides access to the study builder."""
100         import salome
101         salome.salome_init()
102         if salome.myStudy is None:
103             raise Exception("Study doesn't exist")
104         return salome.myStudy.NewBuilder()
105
106     @property
107     def lcc(self):
108         """Attribute that providess access to the SALOME life cycle CORBA service."""
109         import salome
110         salome.salome_init()
111         return salome.lcc
112
113     ## Find a component corresponding to the Salome module \b moduleName in
114     #  the study. If none is found, create a new component and associate it
115     #  with the corresponding engine (i.e. the engine named \b moduleName).
116     #  Note that in Salome 5, the module name and engine name must be
117     #  identical (every module must provide an engine with the same name).
118     #  In Salome 6 it will be possible to define a different name for the
119     #  engine.
120     #
121     #  \param moduleName (string) name of the module corresponding to the component
122     #  (the module name is the string value in the
123     #  attribute "AttributeComment" of the component)
124     #
125     #  \param componentName (string) name of the new component if created. 
126     #  If \b None, use \b moduleName instead.
127     #
128     #  \param icon (string) icon for the new component (attribute "AttributePixMap").
129     #
130     #  \param containerName (string) name of the container in which the engine should be
131     #  loaded.
132     #
133     #  \return the SComponent found or created.
134     def findOrCreateComponent(self, moduleName, componentName = None,
135                               icon = None, containerName = _DEFAULT_CONTAINER):
136         """
137         Find a component corresponding to the Salome module `moduleName` in
138         the study. If none is found, create a new component and associate it
139         with the corresponding engine (i.e. the engine named `moduleName`).
140         Note that in Salome 5, the module name and engine name must be
141         identical (every module must provide an engine with the same name).
142         In Salome 6 it will be possible to define a different name for the
143         engine.
144
145         :type  moduleName: string
146         :param moduleName: name of the module corresponding to the component
147                            (the module name is the string value in the
148                            attribute "AttributeComment" of the component)
149
150         :type  componentName: string
151         :param componentName: name of the new component if created. If
152                               :const:`None`, use `moduleName` instead.
153
154         :type  icon: string
155         :param icon: icon for the new component (attribute "AttributePixMap").
156
157         :type  containerName: string
158         :param containerName: name of the container in which the engine should be
159                               loaded.
160
161         :return: the SComponent found or created.
162
163         """
164         sComponent = self.study.FindComponent(moduleName)
165         if sComponent is None:
166             sComponent = self.builder.NewComponent(moduleName)
167             # Note that the NewComponent method set the "comment" attribute to the
168             # value of its argument (moduleName here)
169             if componentName is None:
170                 componentName = moduleName
171             self.builder.SetName(sComponent, componentName)
172             if icon is not None:
173                 # _MEM_ : This will be effective if and only if "moduleName"
174                 # really corresponds to the module name (as specified in the
175                 # SalomeApp.xml)
176                 self.setIcon(sComponent, icon)
177
178             # This part will stay inactive until Salome 6. In Salome 6, the
179             # engine name will be stored separately from the module name.
180             # An internal convention (in this class) is to store the name of the
181             # associated engine in the parameter attribute of the scomponent (so that
182             # it could be retrieved in a future usage of this scomponent, for example,
183             # for the need of the function loadComponentEngine). The comment attribute
184             # SHOULD NOT be used for this purpose  because it's used by the SALOME
185             # resources manager to identify the SALOME module and then localized
186             # the resource files
187             #attr = self.builder.FindOrCreateAttribute( sComponent, "AttributeParameter" )
188             #attr.SetString( "ENGINE_NAME", engineName )
189
190             engine = self.lcc.FindOrLoadComponent(containerName, moduleName)
191             if engine is None:
192                 raise Exception("Cannot load engine %s in container %s. See "
193                                 "logs of container %s for more details." %
194                                 (moduleName, containerName, containerName))
195             self.builder.DefineComponentInstance(sComponent, engine)
196
197         return sComponent
198
199     ## Load the engine corresponding to \b sComponent in the container
200     #  \b containerName, associate the engine with the component and load the
201     #  CORBA objects of this component in the study.
202     def loadComponentEngine(self, sComponent,
203                             containerName = _DEFAULT_CONTAINER):
204         """
205         Load the engine corresponding to `sComponent` in the container
206         `containerName`, associate the engine with the component and load the
207         CORBA objects of this component in the study.
208         """
209         # This part will stay inactive until Salome 6. In Salome 6, the
210         # engine name will be stored separately from the module name.
211         #attr = self.builder.FindOrCreateAttribute( sComponent, "AttributeParameter" )
212         #engineName = attr.GetString( "ENGINE_NAME" )
213         engine = self.lcc.FindOrLoadComponent(containerName,
214                                               sComponent.GetComment())
215         if engine is None:
216             raise Exception("Cannot load component %s in container %s. See "
217                             "logs of container %s for more details." %
218                             (sComponent.GetComment(), containerName,
219                              containerName))
220         self.builder.LoadWith(sComponent, engine)
221
222     ## Get the CORBA object associated with the SObject \b item, eventually by
223     #  first loading it with the corresponding engine.
224     def getOrLoadObject(self, item):
225         """
226         Get the CORBA object associated with the SObject `item`, eventually by
227         first loading it with the corresponding engine.
228         """
229         object = item.GetObject()
230         if object is None: # the engine has not been loaded yet
231             sComponent = item.GetFatherComponent()
232             self.loadComponentEngine(sComponent)
233             object = item.GetObject()
234         return object
235
236     ## Find an object under \b fatherItem in the study with the given
237     #  attributes. Return the first one found if at least one exists,
238     #  otherwise create a new one with the given attributes and return it.
239     #
240     #  See \b setItem() for the description of the parameters.
241     def findOrCreateItem(self, fatherItem, name, fileType = None,
242                          fileName = None, comment = None, icon = None,
243                          IOR = None, typeId = None):
244         """
245         Find an object under `fatherItem` in the study with the given
246         attributes. Return the first one found if at least one exists,
247         otherwise create a new one with the given attributes and return it.
248         
249         See :meth:`setItem` for the description of the parameters.
250         """
251         sObject = self.findItem(fatherItem, name, fileType, fileName, comment,
252                                 icon, IOR, typeId)
253         if sObject is None:
254             sObject = self.createItem(fatherItem, name, fileType, fileName,
255                                       comment, icon, IOR, typeId)
256         return sObject
257
258     ## Find an item with given attributes under \b fatherItem in the study. If
259     #  none is found, return \b None. If several items correspond to
260     #  the parameters, only the first one is returned. The search is made
261     #  only on given parameters (i.e. not \b None). To look explicitly
262     #  for an empty attribute, use an empty string in the corresponding
263     #  parameter.
264     #    
265     #  See \b setItem() for the description of the parameters.
266     def findItem(self, fatherItem, name = None, fileType = None,
267                  fileName = None, comment = None, icon = None, IOR = None,
268                  typeId = None):
269         """
270         Find an item with given attributes under `fatherItem` in the study. If
271         none is found, return :const:`None`. If several items correspond to
272         the parameters, only the first one is returned. The search is made
273         only on given parameters (i.e. not :const:`None`). To look explicitly
274         for an empty attribute, use an empty string in the corresponding
275         parameter.
276         
277         See :meth:`setItem` for the description of the parameters.
278         """
279         foundItem = None;
280         childIterator = self.study.NewChildIterator(fatherItem)
281         while childIterator.More() and foundItem is None:
282             childItem = childIterator.Value()
283             if childItem and \
284                (name is None or self.getName(childItem) == name) and \
285                (fileType is None or \
286                 self.getFileType(childItem) == fileType) and \
287                (fileName is None or \
288                 self.getFileName(childItem) == fileName) and \
289                (comment is None or self.getComment(childItem) == comment) and \
290                (icon is None or \
291                 self.getIcon(childItem) == icon) and \
292                (IOR is None or childItem.GetIOR() == IOR) and \
293                (typeId is None or \
294                 self.getTypeId(childItem) == typeId):
295                 foundItem = childItem
296             childIterator.Next()
297         return foundItem
298
299     ## Create a new object named \b name under \b fatherItem in the study, with
300     #  the given attributes. If an object named \b name already exists under
301     #  the father object, the new object is created with a new name \b name_X
302     #  where X is the first available index.
303     #
304     #  param fatherItem (SObject) item under which the new item will be added.
305     #  \return new SObject created in the study.
306     #
307     #  See \b setItem() for the description of the other parameters.
308     def createItem(self, fatherItem, name, fileType=None, fileName=None,
309                    comment=None, icon=None, IOR=None, typeId=None):
310         """
311         Create a new object named `name` under `fatherItem` in the study, with
312         the given attributes. If an object named `name` already exists under
313         the father object, the new object is created with a new name `name_X`
314         where X is the first available index.
315
316         :type  fatherItem: SObject
317         :param fatherItem: item under which the new item will be added.
318
319         :return: new SObject created in the study
320
321         See :meth:`setItem` for the description of the other parameters.
322         """
323         aSObject = self.builder.NewObject(fatherItem)
324
325         aChildIterator = self.study.NewChildIterator(fatherItem)
326         aMaxId = -1
327         aLength = len(name)
328         aDelim = "_"
329         anIdRE = re.compile("^" + aDelim + "[0-9]+")
330         aNameRE = re.compile("^" + name)
331         while aChildIterator.More():
332             aSObj = aChildIterator.Value()
333             aChildIterator.Next()
334             aName = aSObj.GetName()
335             if re.match(aNameRE, aName):
336                 aTmp = aName[aLength:]
337                 if re.match(anIdRE, aTmp):
338                     anId = int(aTmp[1:])
339                     if aMaxId < anId:
340                         aMaxId = anId
341                         pass
342                     pass
343                 elif aMaxId < 0:
344                     aMaxId = 0
345                     pass
346                 pass
347             pass
348
349         aMaxId = aMaxId + 1
350         aName = name
351         if aMaxId > 0:
352             aName = aName + aDelim + str(aMaxId)
353             pass
354
355         self.setItem(aSObject, aName, fileType, fileName, comment, icon,
356                      IOR, typeId)
357
358         return aSObject
359
360     ## Modify the attributes of an item in the study. Unspecified attributes
361     #  (i.e. those set to \b None) are left unchanged.
362     #
363     #  \param item (SObject) item to modify.
364     #
365     #  \param name (string or unicode) item name (attribute \b AttributeName).
366     #
367     #  \param fileType (string or unicode) item file type (attribute \b AttributeFileType).
368     #
369     #  \param fileName (string or unicode) item file name (attribute \b AttributeExternalFileDef).
370     #
371     #  \param comment (string or unicode) item comment (attribute \b AttributeComment). Note that
372     #  this attribute will appear in the \b Value column in the object browser.
373     #
374     #  \param icon (string or unicode) item icon name (attribute \b AttributePixMap).
375     #
376     #  \param IOR (string) IOR of a CORBA object associated with the item
377     #  (attribute \b AttributeIOR).
378     #
379     #  \param typeId (integer) item type (attribute \b AttributeLocalID).
380     def setItem(self, item, name = None, fileType = None, fileName = None,
381                 comment = None, icon = None, IOR = None, typeId = None):
382         """
383         Modify the attributes of an item in the study. Unspecified attributes
384         (i.e. those set to :const:`None`) are left unchanged.
385
386         :type  item: SObject
387         :param item: item to modify.
388
389         :type  name: string or unicode
390         :param name: item name (attribute 'AttributeName').
391
392         :type  fileType: string or unicode
393         :param fileType: item file type (attribute 'AttributeFileType').
394
395         :type  fileName: string or unicode
396         :param fileName: item file name (attribute
397                          'AttributeExternalFileDef').
398
399         :type  comment: string or unicode
400         :param comment: item comment (attribute 'AttributeComment'). Note that
401                         this attribute will appear in the 'Value' column in
402                         the object browser.
403
404         :type  icon: string or unicode
405         :param icon: item icon name (attribute 'AttributePixMap').
406
407         :type  IOR: string
408         :param IOR: IOR of a CORBA object associated with the item
409                     (attribute 'AttributeIOR').
410
411         :type  typeId: integer
412         :param typeId: item type (attribute 'AttributeLocalID').
413         """
414         logger.debug("setItem (ID=%s): name=%s, fileType=%s, fileName=%s, "
415                      "comment=%s, icon=%s, IOR=%s" %
416                      (item.GetID(), name, fileType, fileName, comment,
417                       icon, IOR))
418         if name is not None:
419             self.setName(item, name)
420         if fileType is not None:
421             self.setFileType(item, fileType)
422         if fileName is not None:
423             self.setFileName(item, fileName)
424         if comment is not None:
425             self.setComment(item, comment)
426         if icon is not None:
427             self.setIcon(item, icon)
428         if IOR is not None:
429             self.builder.SetIOR(item, IOR)
430         if typeId is not None:
431             self.setTypeId(item, typeId)
432
433     ## Remove the given item from the study. Note that the items are never
434     #  really deleted. They just don't appear in the study anymore.
435     #
436     #  \param item (SObject) the item to be removed
437     #
438     #  \param withChildren (boolean) if \b True, also remove the children of item
439     #
440     #  \return \b True if the item was removed successfully, or 
441     #  \b False if an error happened.
442     def removeItem(self, item, withChildren = False ):
443         """
444         Remove the given item from the study. Note that the items are never
445         really deleted. They just don't appear in the study anymore.
446
447         :type  item: SObject
448         :param item: the item to be removed
449
450         :type  withChildren: boolean
451         :param withChildren: if :const:`True`, also remove the children of
452                              `item`
453
454         :return: :const:`True` if the item was removed successfully, or
455                  :const:`False` if an error happened.
456         """
457         ok = False
458         try:
459             if withChildren:
460                 self.builder.RemoveObjectWithChildren(item)
461             else:
462                 self.builder.RemoveObject(item)
463             ok = True
464         except Exception:
465             ok = False
466         return ok
467
468     ## Find an item tagged \b tag under \b fatherItem in the study tree or
469     #  create it if there is none, then set its attributes.
470     #
471     #  \param fatherItem (SObject) item under which the tagged item will be looked for
472     #  and eventually created.
473     #
474     #  \param tag integer) tag of the item to look for.
475     #
476     #  \return the SObject at \b tag if found or created successfully, or
477     #  \b None if an error happened.
478     #    
479     #  See \b setItem() for the description of the other parameters.
480     def setItemAtTag(self, fatherItem, tag, name = None, fileType = None,
481                      fileName = None, comment = None, icon = None, IOR = None,
482                      typeId = None):
483         """
484         Find an item tagged `tag` under `fatherItem` in the study tree or
485         create it if there is none, then set its attributes.
486         
487         :type  fatherItem: SObject
488         :param fatherItem: item under which the tagged item will be looked for
489                            and eventually created.
490
491         :type  tag: integer
492         :param tag: tag of the item to look for.
493
494         :return: the SObject at `tag` if found or created successfully, or
495                  :const:`None` if an error happened.
496         
497         See :meth:`setItem` for the description of the other parameters.
498         """
499         found, sObj = fatherItem.FindSubObject(tag)
500         if not found:
501             sObj = self.builder.NewObjectToTag(fatherItem, tag)
502         self.setItem(sObj, name, fileType, fileName, comment, icon,
503                      IOR, typeId)
504         return sObj
505
506     ## Return the name of the object sObject
507     def getName(self, sObject):
508         return sObject.GetName()
509
510     ## Set the name of the object sObject
511     def setName(self, sObject, name):
512         self.builder.SetName(sObject, name)
513
514     ## Return the comment of the object sObject
515     def getComment(self, sObject):
516         return sObject.GetComment()
517
518     ## Set the comment of the object sObject
519     def setComment(self, sObject, comment):
520         self.builder.SetComment(sObject, comment)
521
522     ## Return the value of the attribute named \b attributeName on the object
523     #  sObject, or \b default if the attribute doesn't exist.
524     def getAttributeValue(self, sObject, attributeName, default = None):
525         """
526         Return the value of the attribute named `attributeName` on the object
527         `sObject`, or `default` if the attribute doesn't exist.
528         """
529         value = default
530         found, attr = self.builder.FindAttribute(sObject, attributeName)
531         if found:
532             value = attr.Value()
533         return value
534
535     ## Set the value of the attribute named \b attributeName on the object
536     #  sObject to the value \b attributeValue.
537     def setAttributeValue(self, sObject, attributeName, attributeValue):
538         """
539         Set the value of the attribute named `attributeName` on the object
540         `sObject` to the value `attributeValue`.
541         """        
542         attr = self.builder.FindOrCreateAttribute(sObject, attributeName)
543         attr.SetValue(attributeValue)
544
545     ## Return the value of the attribute "AttributeLocalID" of the object
546     #  sObject, or \b None if it is not set.
547     def getTypeId(self, sObject):
548         """
549         Return the value of the attribute "AttributeLocalID" of the object
550         `sObject`, or :const:`None` if it is not set.
551         """
552         return self.getAttributeValue(sObject, "AttributeLocalID")
553
554     ## Set the attribute "AttributeLocalID" of the object \b sObject to the
555     #  value \b value.
556     def setTypeId(self, sObject, value):
557         """
558         Set the attribute "AttributeLocalID" of the object `sObject` to the
559         value `value`.
560         """
561         self.setAttributeValue(sObject, "AttributeLocalID", value)
562
563     ## Return the value of the attribute "AttributeFileType" of the object
564     #  sObject, or an empty string if it is not set.
565     def getFileType(self, sObject):
566         """
567         Return the value of the attribute "AttributeFileType" of the object
568         `sObject`, or an empty string if it is not set.
569         """
570         return self.getAttributeValue(sObject, "AttributeFileType", "")
571
572     ## Set the attribute "AttributeFileType" of the object sObject to the
573     #  value value.
574     def setFileType(self, sObject, value):
575         """
576         Set the attribute "AttributeFileType" of the object `sObject` to the
577         value `value`.
578         """
579         self.setAttributeValue(sObject, "AttributeFileType",
580                                value)
581
582     ## Return the value of the attribute "AttributeExternalFileDef" of the
583     #  object sObject, or an empty string if it is not set.
584     def getFileName(self, sObject):
585         """
586         Return the value of the attribute "AttributeExternalFileDef" of the
587         object `sObject`, or an empty string if it is not set.
588         """
589         return self.getAttributeValue(sObject, "AttributeExternalFileDef", "")
590
591     ## Set the attribute "AttributeExternalFileDef" of the object sObject
592     #  to the value value.
593     def setFileName(self, sObject, value):
594         """
595         Set the attribute "AttributeExternalFileDef" of the object `sObject`
596         to the value `value`.
597         """
598         self.setAttributeValue(sObject, "AttributeExternalFileDef",
599                                value)
600
601     ## Return the value of the attribute "AttributePixMap" of the object
602     #  sObject, or an empty string if it is not set.
603     def getIcon(self, sObject):
604         """
605         Return the value of the attribute "AttributePixMap" of the object
606         `sObject`, or an empty string if it is not set.
607         """
608         value = ""
609         found, attr = self.builder.FindAttribute(sObject, "AttributePixMap")
610         if found and attr.HasPixMap():
611             value = attr.GetPixMap()
612         return value
613
614     ## Set the attribute "AttributePixMap" of the object sObject to the
615     #  value value.
616     def setIcon(self, sObject, value):
617         """
618         Set the attribute "AttributePixMap" of the object `sObject` to the
619         value `value`.
620         """
621         attr = self.builder.FindOrCreateAttribute(sObject, "AttributePixMap")
622         attr.SetPixMap(value)
623
624 ## Singleton study editor instance.
625 #  \ingroup studyedit
626 EDITOR = StudyEditor()
627 """Singleton study editor instance."""
628
629 ## Return a \b StudyEditor instance to edit the study. 
630 #  \deprecated This function is kept for backward compatibility. Use \a EDITOR instead.
631 #  \ingroup studyedit
632 def getStudyEditor():
633     """
634     Return a :class:`StudyEditor` instance to edit the study.
635     """
636     global EDITOR
637     return EDITOR