idl/SALOMEDS.idl

   1 //  Copyright (C) 2003  OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN,
   2 //  CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS
   3 //
   4 //  This library is free software; you can redistribute it and/or
   5 //  modify it under the terms of the GNU Lesser General Public
   6 //  License as published by the Free Software Foundation; either
   7 //  version 2.1 of the License.
   8 //
   9 //  This library is distributed in the hope that it will be useful,
  10 //  but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 //  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12 //  Lesser General Public License for more details.
  13 //
  14 //  You should have received a copy of the GNU Lesser General Public
  15 //  License along with this library; if not, write to the Free Software
  16 //  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  17 //
  18 //  See http://www.opencascade.org/SALOME/ or email : webmaster.salome@opencascade.org
  19 //
  20 //
  21 //
  22 //  File   : SALOMEDS.idl
  23 //  Author : Yves FRICAUD
  24 //  $Header$
  25
  26 /*! \mainpage
  27     \image html Application-About.png
  28 */
  29
  30 /*!
  31   \file SALOMEDS.idl This file contains a set of interfaces used for creation, managment
  32   and modification of the %Study
  33 */
  34
  35 #ifndef _SALOMEDS_IDL_
  36 #define _SALOMEDS_IDL_
  37
  38 #include "SALOME_Exception.idl"
  39
  40 /*!
  41      This package contains the interfaces used for creation, managment
  42      and modification of the %Study
  43 */
  44 module SALOMEDS
  45 {
  46 /*! \typedef URL
  47     Name of the file in which the %Study is saved.
  48
  49 */
  50   typedef string URL;
  51
  52 /*! Main identifier of an object in %SALOME application
  53 */
  54   typedef string ID;
  55
  56 /*! While saving the data, IOR is transformed into persistent reference
  57 */
  58   typedef string PersistentReference;
  59
  60 /*! IOR of the study in %SALOME application
  61 */
  62   typedef string SalomeReference;
  63
  64 /*! List of the names of studies which are currently open in this %SALOME session.
  65 Since %SALOME is a multi-study application, it allows to open a lot of studies
  66 during each working session.
  67 */
  68   typedef sequence<string> ListOfOpenStudies;
  69 /*! List of file names
  70 */
  71   typedef sequence<string> ListOfFileNames;
  72 /*! List of modification dates of a study
  73 */
  74   typedef sequence<string> ListOfDates ;
  75 /*! An unbounded sequence of strings
  76 */
  77   typedef sequence<string> ListOfStrings ;
  78 /*! A byte stream which is used for binary data transfer between different components
  79 */
  80   typedef sequence<octet> TMPFile;
  81
  82   // Reference to other objects is treated with function AddReference
  83   // and ReferencedObject
  84   // All other type of attributes defined in AttributeType enum are
  85   // treated with AddAdttribute and GetAttribute
  86   // The difference is made because Reference attribute don't contain
  87   // strings but reference to ID of other objects
  88
  89   interface GenericAttribute;
  90   interface Study;
  91   interface StudyManager;
  92   interface StudyBuilder;
  93   interface SObject;
  94   interface SComponent;
  95   interface SComponentIterator;
  96   interface ChildIterator;
  97   interface Driver;
  98   interface AttributeStudyProperties;
  99   interface UseCaseIterator;
 100   interface UseCaseBuilder;
 101   interface Callback;
 102
 103 /*! List of attributes of %SObjects
 104 */
 105   typedef sequence<GenericAttribute> ListOfAttributes;
 106
 107 /*! Exception indicating that this feature hasn't been implemented in %SALOME PRO application.
 108 */
 109   exception NotImplemented {};
 110
 111
 112   //===========================================================================
 113  /*! \brief %Study Interface
 114
 115     The purpose of the %Study is to manage the data produced by various components of %SALOME platform.
 116    Most of the %Study operations are handled by the StudyManager and the StudyBuilder.
 117    What is left in the %Study interface are elementary inquiries.
 118    (Incidentally, we recall that a CORBA attribute is implemented as a pair of get
 119       and set methods.) A %Study is explored by a set of tools, mainly iterators
 120     , which are described further. Nevertheless, the %Study
 121      interface allows the search of an object by name or by ID.
 122      \note
 123      <BR><VAR>The Path </VAR>of an object in %SALOME application is much alike a standard path of a file.
 124     In general it's a string of names of directories divided by a slash '/'.
 125      <BR><VAR>The Context</VAR> is the current directory of an object.</P>
 126 */
 127
 128   interface Study
 129   {
 130
 131     exception StudyInvalidContext {};
 132     exception StudyInvalidComponent {};
 133 /*! Invalid directory of the %study exception
 134 */
 135     exception StudyInvalidDirectory {};
 136 /*! Exception pointing that this name of the study has already been used.
 137 */
 138     exception StudyNameAlreadyUsed {};
 139     exception StudyObjectAlreadyExists {};
 140 /*! Invalid name of the %study exception
 141 */
 142     exception StudyNameError {};
 143     exception StudyCommentError {};
 144 /*! \brief The name of the %Study
 145
 146    This is equivalent to the methods setName() & getName()
 147 */
 148     attribute string     Name; // equivalent to setName() & getName()
 149 /*! \brief The ID of the %Study
 150
 151    This is equivalent to the methods setID() & getID()
 152 */
 153     attribute short      StudyId;
 154 /*! Sequence containing %SObjects
 155 */
 156     typedef sequence<SObject> ListOfSObject;
 157 /*!
 158   Gets the persistent reference to the %Study.
 159 */
 160     PersistentReference  GetPersistentReference();
 161 /*!
 162   Gets a transient reference to the %Study.
 163 */
 164     SalomeReference      GetTransientReference();
 165
 166 /*!
 167     Returns True if the %Study is empty
 168 */
 169     boolean IsEmpty();
 170 /*!
 171     Allows to find a %SComponent by its name.
 172    \param aComponentName    It's a string value in the Comment Attribute of the Component,
 173     which is looked for, defining the data type of this Component.
 174
 175 <BR><VAR>See also <A href=exemple/Example1.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 176 */
 177     SComponent FindComponent  (in string aComponentName);
 178 /*!
 179     Allows to find a %SComponent by ID of the according %SObject
 180 */
 181     SComponent FindComponentID(in ID aComponentID);
 182 /*!
 183     Allows to find a %SObject by the Name Attribute of this %SObject
 184
 185     \param anObjectName String parameter defining the name of the object
 186     \return The obtained %SObject
 187
 188 <BR><VAR>See also <A href=exemple/Example19.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 189
 190 */
 191     SObject       FindObject      (in string anObjectName);
 192 /*!
 193     Allows to find a %SObject by its ID
 194     \param aObjectID This parameter defines the ID of the required object
 195     \return The obtained %SObject
 196
 197 */
 198     SObject       FindObjectID    (in ID aObjectID);
 199 /*!
 200     Allows to find a %SObject by IOR of the object belonging to this %SObject.
 201     \param anObjectName This parameter defines the IOR of the object
 202     \return The obtained %SObject
 203
 204 */
 205     SObject       FindObjectIOR   (in ID aObjectIOR);
 206 /*!
 207     Finds in the study all %SObjects produced by a given %Component.
 208     \param anObjectName The Name Attribute of the searched %SObjects should correspond to <VAR>anObjectName</VAR>.
 209     \param aComponentName The name of the component, which objects are searched for.
 210 */
 211     ListOfSObject FindObjectByName(in string anObjectName, in string aComponentName);
 212 /*!
 213     Allows to find a %SObject by the path to it.
 214
 215     \param thePath The path to the required %SObject.
 216     \return The obtained %SObject.
 217
 218 */
 219     SObject FindObjectByPath(in string thePath);
 220 /*!
 221     Returns the path to the %SObject.
 222 */
 223     string  GetObjectPath(in Object theObject);
 224
 225 /*!
 226     Sets the context of the %Study.
 227     \param thePath String parameter defining the context of the study.
 228
 229 <BR><VAR>See also <A href=exemple/Example23.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 230
 231 */
 232     void SetContext(in string thePath);
 233 /*!
 234     Gets the context of the %Study.
 235
 236 <BR><VAR>See also <A href=exemple/Example23.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 237
 238 */
 239     string GetContext();
 240 /*!
 241    Returns a list of names of objects corresponding to the context.
 242    \note  If the parameter <VAR>theContext</VAR> is empty, then the current context will be used.
 243 */
 244     ListOfStrings GetObjectNames(in string theContext);
 245 /*!
 246    Returns a list of names of directories and subdirectories corresponding to the context.
 247    \note  If the parameter <VAR>theContext</VAR> is empty, then the current context will be used.
 248 */
 249     ListOfStrings GetDirectoryNames(in string theContext);
 250 /*!
 251    Returns a list of names of Files corresponding to the context.
 252     \note  If the parameter <VAR>theContext</VAR> is empty, then the current context will be used.
 253 */
 254     ListOfStrings GetFileNames(in string theContext);
 255 /*!
 256    Returns a list of names of Components corresponding to the context.
 257    \note  If the parameter <VAR>theContext</VAR> is empty, then the current context will be used.
 258 */
 259     ListOfStrings GetComponentNames(in string theContext);
 260 /*!
 261     Creates a new iterator of child levels of the given %SObject.
 262     \param aSO The given %SObject
 263     \return A new iterator of child levels of the given %SObject.
 264 */
 265     ChildIterator      NewChildIterator(in SObject aSO);
 266 /*!
 267
 268     Creates a new iterator of the %SComponents.
 269
 270     \return A new iterator of the %SComponents.
 271 */
 272     SComponentIterator NewComponentIterator();
 273 /*!
 274    Creates a new %StudyBuilder to add or modify an object in the study.
 275
 276    \return A new %StudyBuilder.
 277
 278 <BR><VAR>See also <A href=exemple/Example20.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 279
 280 */
 281     StudyBuilder NewBuilder() ;
 282 /*! \brief Labels dependency
 283
 284     Updates the map with IOR attribute. It's an inner method used for optimization.
 285 */
 286     void UpdateIORLabelMap(in string anIOR, in string anEntry);
 287
 288 /*! \brief Getting properties of the study
 289
 290    Returns the attriubte, which contains the properties of this study.
 291
 292 <BR><VAR>See also <A href=exemple/Example20.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 293
 294 */
 295     AttributeStudyProperties GetProperties();
 296 /*!
 297    Determines whether the %study has been saved
 298 */
 299     attribute boolean IsSaved;
 300 /*!
 301   Returns True if the %study has been modified and not saved.
 302 */
 303     boolean IsModified();
 304 /*!
 305    Determines the file where the %study has been saved
 306 */
 307     attribute string  URL;
 308
 309 /*! \brief List of %SObjects
 310
 311     Returns the list of %SObjects which refers to %anObject.
 312 */
 313     ListOfSObject FindDependances(in SObject anObject);
 314
 315 /*! \brief The date of the last saving of the study
 316
 317     Returns the date of the last saving of study with format: "DD/MM/YYYY HH:MM"
 318 */
 319     string GetLastModificationDate();
 320 /*! \brief The list of modification dates of the study
 321
 322     Returns the list of modification dates (without creation date) with format "DD/MM/YYYY HH:MM".
 323       Note : the first modification begins the list.
 324 */
 325     ListOfDates GetModificationsDate();
 326 /*! \brief Object conversion.
 327
 328     Converts an object into IOR.
 329     \return    IOR
 330 */
 331     string ConvertObjectToIOR(in Object theObject);
 332 /*! \brief Object conversion.
 333
 334     Converts IOR into an object.
 335     \return    An object
 336 */
 337     Object ConvertIORToObject(in string theIOR);
 338 /*!
 339     Gets a new %UseCaseBuilder.
 340 */
 341     UseCaseBuilder  GetUseCaseBuilder();
 342
 343 /*!
 344     Closes the components in the study, removes itself from the %StudyManager.
 345 */
 346     void Close();
 347
 348 /*!
 349     Enables(if isEnabled = True)/disables automatic addition of new %SObjects to the use case.
 350 */
 351     void EnableUseCaseAutoFilling(in boolean isEnabled);
 352
 353 /*!
 354     Functions for internal usage only
 355 */
 356     void AddPostponed(in string theIOR);
 357
 358     void AddCreatedPostponed(in string theIOR);
 359
 360     void RemovePostponed(in long theUndoLimit);
 361
 362     void UndoPostponed(in long theWay);
 363   };
 364
 365   //==========================================================================
 366 /*! \brief %Study Builder Interface
 367
 368   The purpose of the Builder is to add and/or remove objects and attributes.
 369   A %StudyBuilder is linked to a %Study. A
 370   command management is provided for the undo/redo functionalities.
 371   \note
 372   <BR><VAR>The Tag</VAR> of an item in %SALOME application is a symbolic description of
 373   item's position in the tree-type structure of the browser. In general it has the following
 374   form: <TT>0:2:1:1</TT>
 375 */
 376   //==========================================================================
 377
 378   interface StudyBuilder
 379   {
 380 /*! \brief %LockProtection Exception
 381
 382     This exception is raised while attempting to modify a locked %study.
 383 */
 384     exception LockProtection {};
 385 /*! \brief Creation of a new %SComponent.
 386
 387    Creates a new %SComponent
 388    \param ComponentDataType    Data type of the %SComponent which will be created.
 389
 390 <BR><VAR>See also <A href=exemple/Example17.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 391
 392 */
 393     SComponent NewComponent(in string ComponentDataType) raises(LockProtection);
 394 /*! \brief Definition of the instance to the %SComponent
 395
 396     Defines the instance to the %SComponent.
 397 */
 398     void       DefineComponentInstance (in SComponent aComponent,in Object ComponentIOR) raises(LockProtection);
 399 /*! \brief Deletion of a %SComponent
 400
 401   Removes a %SComponent.
 402 */
 403     void       RemoveComponent(in SComponent aComponent) raises(LockProtection);
 404
 405 /*! \brief Creation of a new %SObject
 406
 407    Creates a new %SObject under a definite father %SObject.
 408
 409    \param theFatherObject The father %SObject under which this one should be created.
 410    \return New %SObject
 411
 412 <BR><VAR>See also <A href=exemple/Example18.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 413
 414 */
 415
 416     SObject NewObject      (in SObject theFatherObject) raises(LockProtection);
 417
 418 /*! \brief Creation of a new %SObject with a definite %tag
 419
 420    Creates a new %SObject with a definite %tag.
 421
 422    \param atag Long value corresponding to the tag of the new %SObject.
 423    \return New %SObject
 424
 425 */
 426     SObject NewObjectToTag (in SObject theFatherObject, in long atag) raises(LockProtection);
 427 /*! \brief Deletion of the %SObject
 428
 429   Removes a %SObject from the %StudyBuilder.
 430
 431   \param anObject The %SObject to be deleted.
 432 */
 433     void    RemoveObject   (in SObject anObject) raises(LockProtection);
 434 /*! \brief Deletion of the %SObject with all his child objects.
 435
 436   Removes the %SObject with all his child objects.
 437
 438   \param anObject The %SObject to be deleted with all child objects.
 439 */
 440     void    RemoveObjectWithChildren(in SObject anObject) raises(LockProtection);
 441
 442 /*!
 443    Loads a %SComponent.
 444
 445 <BR><VAR>See also <A href=exemple/Example19.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 446
 447 */
 448     void  LoadWith (in SComponent sco, in Driver Engine) raises (SALOME::SALOME_Exception);
 449 /*!
 450    Loads a %SObject.
 451
 452    \param sco %SObject to be loaded.
 453 */
 454     void  Load (in SObject sco);
 455
 456 /*! \brief Looking for or creating an attribute assigned to the %SObject
 457
 458     Allows to find or create an attribute of a specific type which is assigned to the object.
 459     \param anObject        The %SObject corresponding to the attribute which is looked for.
 460     \param aTypeOfAttribute     Type of the attribute.
 461
 462   <BR><VAR>See also <A href=exemple/Example1.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 463 */
 464
 465     GenericAttribute FindOrCreateAttribute(in  SObject        anObject,
 466                                          in  string         aTypeOfAttribute) raises(LockProtection);
 467
 468 /*! \brief Looking for an attribute assigned to a %SObject
 469
 470     Allows to find an attribute of a specific type which is assigned to the object.
 471     \param anObject        The %SObject corresponding to the attribute which is looked for.
 472     \param aTypeOfAttribute     Type of the attribute.
 473     \param anAttribute       Where the attribute is placed if it's found.
 474     \return True if it finds an attribute.
 475  */
 476
 477     boolean FindAttribute(in  SObject        anObject,
 478                                  out GenericAttribute anAttribute,
 479                                  in  string         aTypeOfAttribute);
 480 /*! \brief Deleting the attribute assigned to the %SObject
 481
 482     Removes the attribute of a specific type which is assigned to the object.
 483     \param anObject        The %SObject corresponding to the attribute.
 484     \param aTypeOfAttribute     Type of the attribute.
 485
 486 <BR><VAR>See also <A href=exemple/Example17.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 487 */
 488     void RemoveAttribute(in  SObject        anObject,
 489                          in  string         aTypeOfAttribute) raises(LockProtection);
 490 /*!
 491     Adds a reference between %anObject and %theReferencedObject.
 492     \param anObject The %SObject which will get a reference
 493     \param theReferencedObject The %SObject having a reference
 494 */
 495
 496     void Addreference(in SObject anObject,
 497                       in SObject theReferencedObject) ;
 498 /*!
 499    Adds a directory in the %Study.
 500    \param theName String parameter defining the name of the directory.
 501
 502 <BR><VAR>See also <A href=exemple/Example23.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 503
 504 */
 505     void AddDirectory(in string theName) raises(LockProtection);
 506
 507 /*! \brief Identification of the %SObject's substructure.
 508
 509       Identification of the %SObject's substructure by GUID.
 510
 511
 512       \param anObject The %SObject which will be identified
 513       \param theGUID GUID has the following format "00000000-0000-0000-0000-000000000000"
 514 */
 515
 516      void SetGUID(in SObject anObject, in string theGUID) raises(LockProtection);
 517 /*!
 518 Searches for a definite %SObject with a definite GUID and returns True if it finds it.
 519
 520 \param anObject A definite %SObject which will be identified
 521 \param theGUID GUID has the following format "00000000-0000-0000-0000-000000000000"
 522 */
 523      boolean IsGUID(in SObject anObject, in string theGUID);
 524
 525 /*! \brief Creation of a new command
 526
 527    Creates a new command which can contain several different actions.
 528
 529 <BR><VAR>See also <A href=exemple/Example3.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 530
 531 */
 532     void NewCommand(); // command management
 533 /*! \brief Execution of the command
 534
 535    Commits all actions declared within this command.
 536
 537    \exception LockProtection This exception is raised, when trying to perform this command a study, which is protected for modifications.
 538
 539 <BR><VAR>See also <A href=exemple/Example16.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 540
 541 */
 542     void CommitCommand() raises(LockProtection); // command management
 543 /*!
 544     Returns True if at this moment there is a command under execution.
 545 */
 546     boolean HasOpenCommand();
 547 /*! \brief Cancelation of the command
 548
 549     Cancels all actions declared within the command.
 550
 551 <BR><VAR>See also <A href=exemple/Example17.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 552 */
 553     void AbortCommand(); // command management
 554 /*! \brief Undolimit
 555
 556     The number of actions which can be undone
 557 */
 558     attribute long  UndoLimit;
 559 /*! \brief Undo method
 560
 561     Cancels all actions of the last command.
 562
 563     \exception LockProtection This exception is raised, when trying to perform this command a study, which is protected for modifications.
 564
 565 <BR><VAR>See also <A href=exemple/Example16.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 566
 567 */
 568     void Undo() raises (LockProtection);
 569 /*! \brief Redo method
 570
 571     Redoes all actions of the last command.
 572
 573 \exception LockProtection This exception is raised, when trying to perform this command a study, which is protected for modifications.
 574
 575  <BR><VAR>See also <A href=exemple/Example16.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 576
 577 */
 578     void Redo() raises (LockProtection);
 579 /*!
 580     Returns True if at this moment there are any actions which can be canceled.
 581
 582    <BR><VAR>See also <A href=exemple/Example16.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 583
 584 */
 585     boolean GetAvailableUndos();
 586 /*!
 587     Returns True if at this moment there are any actions which can be redone.
 588
 589    <BR><VAR>See also <A href=exemple/Example3.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 590
 591 */
 592     boolean GetAvailableRedos();
 593 /*!
 594     This method is called when adding an object into study.
 595     It sets the callback for addition of the given %SObject.
 596     \param theCallback New assigned callback.
 597     \return The previous callback.
 598 */
 599     Callback SetOnAddSObject(in Callback theCallback);
 600 /*!
 601     This method is called when adding an object into study.
 602     It sets the callback for removal of the given %SObject.
 603
 604     \return The previous callback.
 605     \param theCallback New assigned callback.
 606 */
 607     Callback SetOnRemoveSObject(in Callback theCallback);
 608
 609   };
 610
 611   //==========================================================================
 612 /*! \brief %Study Manager interface
 613
 614     The purpose of the Manager is to manipulate the %Studies. You will find in this
 615     interface the methods to create, open,
 616     close, and save a %Study. Since a %SALOME session is multi-document, you will
 617     also find the methods allowing to navigate
 618     through the collection of studies present in a session.
 619 */
 620   //==========================================================================
 621
 622   interface StudyManager
 623   {
 624 /*!
 625     Determines whether the server has already been loaded or not.
 626 */
 627     void ping();
 628
 629 /*! \brief Creation of a new study
 630
 631      Creates a new study with a definite name.
 632
 633      \param study_name String parameter defining the name of the study
 634
 635 <BR><VAR>See also <A href=exemple/Example17.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 636
 637 */
 638     Study NewStudy(in string study_name);
 639
 640 /*! \brief Open a study
 641
 642      Reads and activates the structure of the study %Objects.
 643      \param aStudyUrl The path to the study
 644     \warning This method doesn't activate the corba objects. Only a component can do it.
 645
 646 <BR><VAR>See also <A href=exemple/Example1.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 647 */
 648     Study Open (in URL aStudyUrl) raises (SALOME::SALOME_Exception);
 649
 650 /*! \brief Closing the study
 651
 652     Closes a study.
 653 */
 654     void  Close(in Study aStudy);
 655 /*! \brief Saving the study in a HDF file (or files).
 656
 657     Saves a study.
 658
 659     \param theMultiFile If this parameter is True the study will be saved in several files.
 660
 661 <BR><VAR>See also <A href=exemple/Example19.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 662
 663 */
 664     void  Save(in  Study aStudy, in boolean theMultiFile);
 665 /*! \brief Saving a study in a ASCII file (or files).
 666
 667     Saves a study in an ASCII format file (or files).
 668     \param theMultiFile If this parameter is True the study will be saved in several files.
 669 */
 670     void  SaveASCII(in  Study aStudy, in boolean theMultiFile);
 671 /*! \brief Saving the study in a specified HDF file (or files).
 672
 673     Saves the study in a specified file (or files).
 674     \param aUrl The path to the definite file in whcih the study will be saved
 675     \param aStudy The study which will be saved
 676     \param theMultiFile If this parameter is True the study will be saved in several files.
 677
 678  <BR><VAR>See also <A href=exemple/Example1.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 679 */
 680     void  SaveAs(in URL   aUrl, // if the file already exists
 681                 in Study aStudy,
 682                 in boolean theMultiFile); // overwrite (as option)
 683 /*! \brief Saving the study in a specified ASCII file (or files).
 684
 685     Saves the study in a specified ASCII file (or files).
 686
 687     \param aUrl The path to the definite file in whcih the study will be saved
 688     \param aStudy The study which will be saved
 689     \param theMultiFile If this parameter is True the study will be saved in several files.
 690 */
 691     void  SaveAsASCII(in URL   aUrl, // if the file already exists
 692                       in Study aStudy,
 693                       in boolean theMultiFile); // overwrite (as option)
 694
 695
 696 /*! \brief List of open studies.
 697
 698 Gets the list of open studies
 699
 700     \return A list of open studies in the current session.
 701 */
 702     ListOfOpenStudies GetOpenStudies();
 703
 704 /*! \brief Getting a particular %Study picked by name
 705
 706     Activates a particular %Study
 707     among the session collection picking it by name.
 708     \param aStudyName The name of the study
 709 */
 710     Study GetStudyByName  (in string aStudyName);
 711
 712 /*! \brief Getting a particular %Study picked by ID
 713
 714     Activates a particular %Study
 715     among the session collection picking it by ID.
 716     \param aStudyID The ID of the study
 717 */
 718     Study GetStudyByID  (in short aStudyID);
 719
 720     // copy/paste methods
 721
 722 /*!
 723     Returns True, if the given %SObject can be copied to the clipboard.
 724 */
 725     boolean CanCopy(in SObject theObject);
 726 /*!
 727     Returns True, if the given %SObject is copied to the clipboard.
 728     \param theObject The %SObject which will be copied
 729 */
 730     boolean Copy(in SObject theObject);
 731 /*!
 732     Returns True, if the object from the clipboard can be pasted to the given %SObject.
 733     \param theObject The %SObject stored in the clipboard.
 734 */
 735     boolean CanPaste(in SObject theObject);
 736 /*!
 737     Returns the %SObject in which the object from the clipboard was pasted to.
 738     \param theObject The %SObject which will be pasted
 739     \exception SALOMEDS::StudyBuilder::LockProtection This exception is raised, when trying to paste
 740     an object into a study, which is protected for modifications.
 741 */
 742     SObject Paste(in SObject theObject) raises (SALOMEDS::StudyBuilder::LockProtection);
 743   };
 744
 745
 746   //==========================================================================
 747 /*! \brief %SObject interface
 748
 749    The objects in the %study are built by the %StudyBuilder. The %SObject interface
 750    provides methods for elementary inquiries, like getting an object %ID or its attribuites.
 751  \note
 752
 753    <BR><VAR>Tag</VAR> of an item in %SALOME application is an integer value uniquely defining an item
 754    in the tree-type data structure.
 755    <BR><VAR>ID</VAR> of an item is a description of item's position in the tree-type data structure.
 756    ID is a list of tags and it has the following form: <TT>0:2:1:1</TT>.
 757 */
 758   //==========================================================================
 759
 760   interface SObject
 761   {
 762 /*! Name of the %SObject
 763 */
 764     attribute string Name; // equivalent to setName() & getName()
 765 /*! Gets an object %ID
 766
 767    \return ID of the %SObject.
 768 */
 769     ID GetID();
 770 /*!  Acquisition of the father %Component of the %SObject
 771
 772   \return The father %Component of the %SObject.
 773 */
 774     SComponent GetFatherComponent();
 775 /*! Acquisition of the father %SObject of the %SObject
 776
 777    \return the father %SObject of the given %SObject.
 778 */
 779     SObject    GetFather();
 780 /*! Gets the %tag of a %SObject
 781
 782     \return the %tag of a %SObject.
 783 */
 784     short      Tag();
 785 /*! Looks for subobjects of a given %SObject.
 786
 787     \param atag Tag of the given %SObject
 788     \return True if it finds a subobject of the %SObject with a definite tag as well as the required subobject.
 789 */
 790
 791     boolean FindSubObject (in long atag, out SObject obj);
 792 /*! Looks for attributes of a given %SObject
 793
 794    \param aTypeOfAttribute String value defining the type of the required attribute of the given %SObject.
 795    \return True if it finds an attribute of a definite type of the given %SObject as well as the discovered attribute.
 796
 797 <BR><VAR>See also <A href=exemple/Example1.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 798 */
 799     boolean FindAttribute(out GenericAttribute anAttribute,
 800                                   in  string         aTypeOfAttribute);
 801 /*! Looks for a %SObject which the given %SObject refers to.
 802
 803     \return The object which the given %SObject refers to as well as True if it finds
 804     this object.
 805 */
 806     boolean ReferencedObject(out SObject obj); // A REVOIR
 807 /*! Gets all attributes of a given %SObject
 808
 809     \return The list of all attributes of the given %SObject.
 810
 811 <BR><VAR>See also <A href=exemple/Example17.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 812
 813 */
 814     ListOfAttributes     GetAllAttributes();
 815 /*! Gets the study of a given %SObject.
 816
 817     /return The study containing the given %SObject.
 818 */
 819     Study GetStudy();
 820   };
 821
 822
 823   //==========================================================================
 824 /*! \brief %Generic attribute interface
 825
 826    %Generic attribute is a base interface for all attributes which can be assigned to the SObjects created in the study.
 827 */
 828   //==========================================================================
 829   interface GenericAttribute
 830   {
 831 /*! \brief Exception locking all changes
 832
 833     This exception locks all modifications in attributes.
 834 */
 835     exception LockProtection {};
 836 /*! \brief Method CheckLocked
 837
 838    Checks whether the %Study is protected for modifications.
 839
 840    \note <BR>This exception is raised only outside a transaction.
 841 */
 842     void CheckLocked() raises (LockProtection);
 843   };
 844
 845
 846
 847   //==========================================================================
 848 /*! \brief %SComponent interface
 849
 850    The %SComponent interface establishes in the study a permanent assocition to the Components integrated into %SALOME platform.
 851    The %SComponent interface is a specialization of the %SObject interface.
 852    It inherits the most of its methods from the %SObject interface.
 853 */
 854   //==========================================================================
 855   interface SComponent : SObject
 856   {
 857 /*! Gets the data type of the given %SComponent
 858
 859     \return The data type of this %SComponent.
 860 */
 861     string  ComponentDataType();
 862 /*! Gets the IOR of the given component
 863
 864   \return True (if there is an instance of the given component) and its IOR.
 865 */
 866     boolean ComponentIOR (out ID theID); //returns True if there is an instance
 867                                          //In this case ID identifies this one
 868   };
 869
 870
 871   //==========================================================================
 872 /*! \brief %SComponentIterator interface
 873
 874   This interface contains the methods allowing to iterate over all components in the list.
 875   The search is started from the first %SComponent in the list.
 876 */
 877   //==========================================================================
 878   interface SComponentIterator
 879   {
 880 /*!
 881 Activates the %SComponentIterator.
 882 */
 883     void Init();
 884 /*!  Method More
 885
 886    \return True if there is one more %SComponent in the list.
 887 */
 888     boolean More();
 889 /*!
 890 Moves the iterator to the next %SComponent in the list.
 891 */
 892     void Next();
 893 /*!
 894     Returns the %SComponent corresponding to the current %SComponent found by the iterator.
 895
 896  <BR><VAR>See also <A href=exemple/Example1.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
 897
 898 */
 899     SComponent Value();
 900   };
 901
 902   //==========================================================================
 903 /*! \brief %ChildIterator interface
 904
 905     This interface contains methods which allow to iterate over all child
 906     levels.
 907 */
 908   //==========================================================================
 909   interface ChildIterator
 910   {
 911 /*!
 912
 913 Activates the %ChildIterator.
 914 */
 915     void Init();
 916 /*!
 917
 918 Activates the %ChildIterator for all child levels.
 919
 920 \param allLevels If this boolean parameter is True, the %ChildIterator will be activated for all child levels.
 921 */
 922     void InitEx(in boolean allLevels);
 923 /*! Method More
 924
 925    \return True if there is one more %ChildIterator in the list.
 926 */
 927     boolean More();
 928 /*!
 929     Passes the iterator to the next level.
 930 */
 931     void Next();
 932 /*!
 933     Returns the %SObject corresponding to the current object found by the iterator.
 934 */
 935     SObject Value();
 936   };
 937
 938   //==========================================================================
 939   //==========================================================================
 940 /*! \brief Interface of the %UseCaseIterator.
 941
 942    This interface contains a set of methods used for iteration over the objects in the use case.
 943 */
 944   interface UseCaseIterator
 945   {
 946 /*!
 947 Activates the %UseCaseIterator.
 948 \param allLevels If the value of this parameter is True the Iterator is activated for all subobjects.
 949 */
 950     void Init(in boolean allLevels);
 951 /*! Method More
 952
 953     \return True if the %UseCaseIterator finds one more object.
 954 */
 955     boolean More();
 956 /*!
 957     Passes the iterator to the next object.
 958 */
 959     void Next();
 960 /*!
 961     Returns the %SObject corresponding to the current object found by the Iterator.
 962 */
 963     SObject Value();
 964   };
 965
 966   //==========================================================================
 967   //==========================================================================
 968 /*! \brief Interface of the %UseCaseBuilder
 969
 970    Use case in the study represents a user-managed subtree, containing all or some of the objects which exist in the study.
 971    The %UseCaseBuilder interface contains a set of methods used for management of the use case in the study.
 972 */
 973   interface UseCaseBuilder
 974   {
 975 /*!
 976    Adds to the use case an object as a child of the current object of the use case.
 977
 978    \param theObject The added %SObject.
 979    \return True if this %SObject has been added in the use case.
 980 */
 981     boolean Append(in SObject theObject);
 982 /*!
 983    Removes an object from the use case.
 984
 985    \param theObject The deleted %SObject
 986    \return True if this %SObject has been deleted from the use case.
 987 */
 988     boolean Remove(in SObject theObject);
 989 /*!
 990    Adds a child object <VAR>theObject</VAR> to the given father <VAR>theFather</VAR> object in the use case.
 991 */
 992     boolean AppendTo(in SObject theFather, in SObject theObject);
 993 /*!
 994     Inserts in the use case the object <VAR>theFirst</VAR> before the object <VAR>theNext</VAR>.
 995 */
 996     boolean InsertBefore(in SObject theFirst, in SObject theNext);
 997 /*!
 998     Sets the current object of the use case.
 999 */
1000     boolean SetCurrentObject(in SObject theObject);
1001 /*!
1002     Makes the root object to be the current object of the use case.
1003 */
1004     boolean SetRootCurrent();
1005 /*!
1006    Returns True if the given object <VAR>theObject</VAR> of the use case has child objects.
1007 */
1008     boolean HasChildren(in SObject theObject);
1009 /*!
1010    Sets the name of the use case.
1011 */
1012     boolean SetName(in string theName);
1013 /*!
1014    Gets the name of the use case.
1015 */
1016     string GetName();
1017 /*!
1018    Returns True if the given object <VAR>theObject</VAR> represents a use case.
1019 */
1020     boolean IsUseCase(in SObject theObject);
1021 /*!
1022     Gets the current object of the use case.
1023 */
1024     SObject GetCurrentObject();
1025 /*!
1026     Creates a new use case in the use case browser.
1027 */
1028     SObject AddUseCase(in string theName);
1029 /*!
1030     Returns the %UseCaseIterator for the given object <VAR>theObject</VAR> in the use case.
1031 */
1032     UseCaseIterator GetUseCaseIterator(in SObject theObject);
1033   };
1034   //==========================================================================
1035   //==========================================================================
1036 /*! \brief The callback interface
1037
1038   The %StudyBuilder can be created with the method <VAR>NewBuilder</VAR>. While invocation of this method a new object of the class <VAR>Callback</VAR> is created
1039   and this object is assigned to the newly created Builder as callback which should be called when adding and removing of the ojects.
1040 */
1041   interface Callback
1042   {
1043 /*!
1044      Invokes the corresponding method <VAR>Append</VAR> of the %UseCaseBuilder.
1045 */
1046      void OnAddSObject(in SObject theObject);
1047 /*!
1048      Invokes the corresponding method <VAR>Remove</VAR> of the %UseCaseBuilder.
1049 */
1050      void OnRemoveSObject(in SObject theObject);
1051   };
1052
1053   //==========================================================================
1054 /*! \brief %Driver interface
1055
1056 This class represents a common tool for all components integrated into SALOME application, that allows them to communicate with the study. It contains a set of methods which
1057 can be called by any component and which provide the following functionality:
1058 <ul>
1059     <li> publishing in the study of the objects created by a definite component
1060     <li> saving/loading of the data created by a definite component. These methods are called by the StudyManager when loading/saving a study containing the data created by a definite component.
1061     <li> transforming of the transient references into persistant references (or vice versa) of the SObjects when saving (or loading) a study
1062     <li> copy/paste common functionality. These methods can be called by any component in order to copy/paste its object created in the study
1063 </ul>
1064
1065 */
1066   //==========================================================================
1067   interface Driver
1068   {
1069
1070     /*! \brief Saving the data produced by a definite component.
1071
1072         This method is called by the StudyManager when saving a study.
1073        \param theComponent    %SComponent corresponding to this Component
1074        \param theURL  The path to the file in which the data will be saved.
1075        \param isMultiFile  If the value of this boolean parameter is True, the data will be saved in several files.
1076        \return A byte stream TMPFile that contains all saved data
1077
1078 <BR><VAR>See also <A href=exemple/Example19.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
1079
1080      */
1081
1082
1083     TMPFile Save(in SComponent theComponent, in string theURL, in boolean isMultiFile);
1084
1085 /*! \brief Saving the data in ASCII format produced by a definite component.
1086
1087         This method is called by the StudyManager when saving a study in ASCII format.
1088        \param theComponent    %SComponent corresponding to this Component
1089        \param theURL  The path to the file in which the data will be saved.
1090        \param isMultiFile  If the value of this boolean parameter is True, the data will be saved in several files.
1091        \return A byte stream TMPFile that will contain all saved data
1092
1093 <BR><VAR>See also <A href=exemple/Example19.html> an example </A> of this method usage in batchmode of %SALOME application.</VAR>
1094
1095      */
1096     TMPFile SaveASCII(in SComponent theComponent, in string theURL, in boolean isMultiFile);
1097
1098     /*! \brief Loading the data.
1099
1100        This method is called by the StudyManager when opening a study.
1101        \param theComponent      %SComponent corresponding to this Component
1102        \param theStream   The file which contains all data saved by the component on Save method
1103        \param isMultiFile  If the value of this boolean parameter is True, the data will be loaded from several files
1104
1105      */
1106
1107     boolean Load(in SComponent theComponent, in TMPFile theStream, in string theURL, in boolean isMultiFile);
1108
1109     /*! \brief Loading the data from files in ASCII format.
1110
1111        This method is called by the StudyManager when opening a study.
1112        \param theComponent      %SComponent corresponding to this Component
1113        \param theStream   The file which contains all data saved by the component on Save method
1114        \param isMultiFile  If the value of this boolean parameter is True, the data will be loaded from several files
1115
1116      */
1117
1118     boolean LoadASCII(in SComponent theComponent, in TMPFile theStream, in string theURL, in boolean isMultiFile);
1119
1120     /*! \brief Closing of the study
1121
1122       This method Close is called by the StudyManager when closing a study.
1123     \param aSComponent The according %SComponent
1124      */
1125
1126     void Close (in SComponent aSComponent);
1127     //void Close ( in string  aIORSComponent);
1128
1129     /*! Gets the type of the data
1130
1131         \return The type of data produced by the Component in the study.
1132      */
1133
1134      string ComponentDataType();
1135
1136     // Driver Transient -> persistent called for each object in study
1137 /*!
1138    Transforms IOR of a given %SObject into PersistentID. It is called for each
1139    object in the %study.
1140 \note <br> In %SALOME the objects which are present in an active study are identified by an IOR, when this
1141 study is saved these references are transformed into persintent IDs.
1142
1143    \param theSObject The given %SObject.
1144    \param IORString The IOR of the given %SObject.
1145    \param isMultiFile If this parameter is True the study containing the given %SObject is stored in several files.
1146    \param isASCII If this parameter is True the study containing the given %SObject is stored in ASCII format.
1147
1148    \return The persistent ID of the given %SObject
1149
1150 */
1151     string IORToLocalPersistentID (in SObject theSObject,
1152                                    in string IORString,
1153                                    in boolean isMultiFile,
1154                                    in boolean isASCII);
1155 /*!
1156   Transforms PersistentID into IOR of the object. It is called for each
1157    object in the %study.
1158
1159    \note <br> In %SALOME the objects which are present in an saved study (file) are identified by a persistent ID, when this
1160 study is open, these references are transformed into persintent IORs.
1161
1162    \param theSObject The given %SObject.
1163    \param IORString The IOR of the given %SObject.
1164    \param isMultiFile If this parameter is True the study containing the given %SObject is stored in several files.
1165    \param isASCII If this parameter is True the study containing the given %SObject is stored in ASCII format.
1166
1167    \return The IOR of the given %SObject
1168
1169 */
1170     string LocalPersistentIDToIOR (in SObject theSObject,
1171                                    in string aLocalPersistentID,
1172                                    in boolean isMultiFile,
1173                                    in boolean isASCII)
1174       raises (SALOME::SALOME_Exception);
1175
1176     // Publishing in the study
1177 /*! Publishing in the study
1178
1179     \return True if the given %Component can publish a definite object with a given IOR in the %study.
1180     \param theIOR The IOR of a definite object
1181 */
1182     boolean CanPublishInStudy(in Object theIOR) raises (SALOME::SALOME_Exception);
1183 /*! \brief Publishing in the study
1184
1185    Publishes the given object in the %study, using the algorithm of this component.
1186     \param theStudy     The %study in which the object is published
1187     \param theSObject     If this parameter is null the object is published for the first time. Otherwise
1188     this parameter should contain a reference to the object published earlier
1189     \param theObject      The object which is published
1190     \param theName      The name of the published object. If this parameter is empty, the name is generated
1191     automatically by the component.
1192
1193     \return The published %SObject.
1194 */
1195     SObject PublishInStudy(in Study theStudy, in SObject theSObject, in Object theObject, in string theName);
1196
1197     // copy/paste methods
1198
1199 /*!
1200     Returns True, if the given %SObject can be copied to the clipboard.
1201
1202     \param theObject The given %SObject which should be copied.
1203 */
1204     boolean CanCopy(in SObject theObject);
1205 /*!
1206     Returns the object %ID and the %TMPFile of the object from the given %SObject.
1207 */
1208     TMPFile CopyFrom(in SObject theObject, out long theObjectID);
1209 /*!
1210     Returns True, if the component can paste the object with given %ID of the component with name <VAR>theComponentName</VAR>.
1211 */
1212     boolean CanPaste(in string theComponentName, in long theObjectID);
1213 /*!
1214     Returns the %SObject of the pasted object.
1215 */
1216     SObject PasteInto(in TMPFile theStream, in long theObjectID, in SObject theObject);
1217
1218   };
1219 };
1220
1221 #endif