src/TDocStd/TDocStd_Application.cdl

   1 -- Created on: 1999-06-30
   2 -- Created by: Denis PASCAL
   3 -- Copyright (c) 1999 Matra Datavision
   4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
   5 --
   6 -- This file is part of Open CASCADE Technology software library.
   7 --
   8 -- This library is free software; you can redistribute it and/or modify it under
   9 -- the terms of the GNU Lesser General Public License version 2.1 as published
  10 -- by the Free Software Foundation, with special exception defined in the file
  11 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  12 -- distribution for complete text of the license and disclaimer of any warranty.
  13 --
  14 -- Alternatively, this file may be used under the terms of Open CASCADE
  15 -- commercial license or contractual agreement.
  16
  17 deferred class Application from TDocStd inherits Application from CDF
  18
  19         ---Purpose:
  20         -- The abstract root class for all application classes.
  21         -- They are in charge of:
  22         -- -   Creating documents
  23         -- -   Storing documents and retrieving them
  24         -- -   Initializing document views.
  25         -- To create a useful OCAF-based application, you
  26         -- derive a class from Application and implement
  27         -- the methods below. You will have to redefine the
  28         -- deferred (virtual) methods Formats,
  29         -- InitDocument, and Resources, and override others.
  30         -- The application is a container for a document,
  31         -- which in its turn is the container of the data
  32         -- framework made up of labels and attributes.
  33         -- Besides furnishing a container for documents,
  34         -- TDocStd_Application provides the following
  35         -- services for them:
  36         -- -   Creation of new documents
  37         -- -   Activation of documents in sessions of an application
  38         -- -   Storage and retrieval of documents
  39         -- -   Initialization of document views.
  40         -- Note:
  41         -- If a client needs detailed information concerning
  42         -- the events during the Open/Store operation, MessageDriver
  43         -- inherited from CDM_MessageDriver of the
  44         -- corresponding application has to be implemented.
  45         -- If the MessageDriver is not defined all messages
  46         -- will be (by default) directed to
  47         -- CDM_NullMessageDriver and will be lost.
  48
  49 uses Manager                  from Resource,
  50      Document                 from TDocStd,
  51      CString                  from Standard,
  52      ExtendedString           from TCollection,
  53      SequenceOfExtendedString from TColStd,
  54      ReaderStatus             from PCDM,
  55      StoreStatus              from PCDM
  56
  57 raises NoSuchObject from Standard
  58
  59 is
  60
  61     Initialize;
  62
  63     IsDriverLoaded (me)
  64         ---Purpose: Check if meta data driver was successfully loaded
  65         --          by the application constructor
  66     returns Boolean from Standard;
  67
  68
  69
  70     Resources (me: mutable)
  71         ---Purpose: create  (if  not done)  a Manager  using ResourcesName
  72         --          method.
  73     returns Manager from Resource
  74     is redefined virtual;
  75
  76     ResourcesName (me: mutable)
  77         ---Purpose:  Returns the name of the file containing the
  78         -- resources of this application.
  79         -- In a resource file, the application associates the schema name
  80         -- of the document with the storage and
  81         -- retrieval plug-ins that are to be loaded for each
  82         -- document. On retrieval, the application reads the
  83         -- schema name in the heading of the CSF file and
  84         -- loads the plug-in indicated in the resource file.
  85         -- This plug-in instantiates the actual driver for
  86         -- transient-persistent conversion.
  87         -- Your application can bring this process into play
  88         -- by defining a class which inherits
  89         -- CDF_Application and redefines the function
  90         -- which returns the appropriate resources file. At
  91         -- this point, the function Retrieve and the class
  92         -- CDF_Store can be called. This allows you to
  93         -- deal with storage and retrieval of - as well as
  94         -- copying and pasting - documents.
  95         -- To implement a class like this, several virtual
  96         -- functions should be redefined. In particular, you
  97         -- must redefine the abstract function Resources
  98         -- inherited from the superclass CDM_Application.
  99     returns CString from Standard
 100     is deferred;
 101
 102     NbDocuments (me)
 103         ---Purpose: returns the number of documents handled by the current applicative session.
 104     returns Integer from Standard;
 105
 106     GetDocument (me; index : Integer from Standard; aDoc : in out Document from TDocStd);
 107         ---Purpose: Constructs the new document aDoc.
 108         -- aDoc is identified by the index index which is
 109         -- any integer between 1 and n where n is the
 110         -- number of documents returned by NbDocument.
 111         -- Example
 112         -- Handle(TDocStd_Application)
 113         -- anApp;
 114         -- if (!CafTest::Find(A)) return 1;
 115         --  Handle(TDocStd) aDoc;
 116         -- Standard_Integer nbdoc = anApp->NbDocuments();
 117         -- for (Standard_Integer i = 1; i <= nbdoc; i++) {
 118         -- aApp->GetDocument(i,aDoc);
 119
 120     Formats(me: mutable; Formats: out SequenceOfExtendedString from TColStd)
 121         ---Purpose:
 122         -- Returns the format name Formats
 123         -- representing the format supported for
 124         -- application documents.
 125         -- This virtual function is to be redefined for each
 126         -- specific application.
 127     is redefined deferred;
 128
 129     NewDocument (me : mutable; format : ExtendedString from TCollection; aDoc : out Document from TDocStd)
 130         ---Purpose: Constructs the empty new document aDoc.
 131         -- This document will have the format format.
 132         -- If InitDocument is redefined for a specific
 133         -- application, the new document is handled by the
 134         -- applicative session.
 135     is virtual;
 136
 137     InitDocument (me; aDoc : Document from TDocStd)
 138         ---Purpose: Initialize the document aDoc for the applicative session.
 139         -- This virtual function is called by NewDocument
 140         -- and is to be redefined for each specific application.
 141
 142     is virtual;
 143
 144
 145     ---Purpose: Modified flag (different of disk version)
 146     --          =============
 147
 148     --Modify(me: mutable); (see CDM_Document)
 149
 150
 151     --IsModified(me) returns Boolean from Standard; (see CDM_Document)
 152
 153
 154     ---Purpose: to open/save a document
 155     --          =======================
 156
 157     Close  (me : mutable; aDoc : Document from TDocStd);
 158     ---Purpose: Close the given document. the document is not any more
 159     --          handled by the applicative session.
 160
 161
 162     IsInSession (me; path : ExtendedString from TCollection)
 163         ---Purpose:  Returns an index for the document found in the
 164         -- path path in this applicative session.
 165         -- If the returned value is 0, the document is not
 166         -- present in the applicative session.
 167         -- This method can be used for the interactive part
 168         -- of an application. For instance, on a call to
 169         -- Open, the document to be opened may already
 170         -- be in memory. IsInSession checks to see if this
 171         -- is the case. Open can be made to depend on
 172         -- the value of the index returned: if IsInSession
 173         --  returns 0, the document is opened; if it returns
 174         -- another value, a message is displayed asking the
 175         --  user if he wants to override the version of the
 176         --  document in memory.
 177         -- Example:
 178         -- Standard_Integer insession = A->IsInSession(aDoc);
 179         -- if (insession > 0) {
 180         -- cout << "document " << insession << " is already in session" << endl;
 181         -- return 0;
 182         -- }
 183
 184     returns Integer from Standard;
 185
 186     Open (me : mutable; path :     ExtendedString from TCollection;
 187                         aDoc : out Document from TDocStd)
 188         ---Purpose: Retrieves the document aDoc stored under the
 189         -- name aName in the directory directory.
 190         -- In order not to override a version of aDoc which
 191         -- is already in memory, this method can be made
 192         -- to depend on the value returned by IsInSession.
 193     returns ReaderStatus from PCDM;
 194
 195     SaveAs (me : mutable; aDoc : Document from TDocStd;
 196                           path : ExtendedString from TCollection)
 197         ---Purpose:  Save the  active document  in the file  <name> in the
 198         --           path <path> ; o verwrites  the file  if  it already exists.
 199     returns StoreStatus from PCDM;
 200
 201
 202     Save (me : mutable; aDoc : Document from TDocStd)
 203         ---Purpose: Save aDoc active document.
 204         -- Exceptions:
 205         --  Standard_NotImplemented if the document
 206         -- was not retrieved in the applicative session by using Open.
 207     returns StoreStatus from PCDM;
 208
 209     SaveAs (me : mutable; aDoc : Document from TDocStd;
 210                           path : ExtendedString from TCollection;
 211                           theStatusMessage:  out  ExtendedString from TCollection)
 212         ---Purpose:  Save the  active document  in the file  <name> in the
 213         --           path <path>  .  overwrite  the file  if  it
 214         --          already exist.
 215     returns StoreStatus from PCDM;
 216
 217     Save (me : mutable; aDoc : Document from TDocStd;
 218                         theStatusMessage:  out  ExtendedString from TCollection)
 219         ---Purpose: Save the document overwriting the previous file
 220     returns StoreStatus from PCDM;
 221
 222     --Exit (me)
 223     --  to quit the application. the applicative documents must be closed before.
 224     OnOpenTransaction   (me:mutable; theDoc: Document from TDocStd)
 225     is virtual protected;
 226     ---Purpose: Notification that is fired at each OpenTransaction event.
 227
 228     OnCommitTransaction (me:mutable; theDoc: Document from TDocStd)
 229     is virtual protected;
 230     ---Purpose: Notification that is fired at each CommitTransaction event.
 231
 232     OnAbortTransaction  (me:mutable; theDoc: Document from TDocStd)
 233     is virtual protected;
 234     ---Purpose: Notification that is fired at each AbortTransaction event.
 235
 236
 237 fields
 238
 239     myResources      : Manager from Resource is protected;
 240     myIsDriverLoaded : Boolean from Standard is protected;
 241
 242 friends
 243     class Document from TDocStd
 244
 245 end Application;