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