42cf5bc1 |
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 | #ifndef _TDocStd_Application_HeaderFile |
18 | #define _TDocStd_Application_HeaderFile |
19 | |
20 | #include <Standard.hxx> |
21 | #include <Standard_Type.hxx> |
22 | |
23 | #include <Standard_Boolean.hxx> |
24 | #include <CDF_Application.hxx> |
83ae3591 |
25 | #include <Message_Messenger.hxx> |
42cf5bc1 |
26 | #include <Standard_CString.hxx> |
27 | #include <Standard_Integer.hxx> |
4ff92abe |
28 | #include <Standard_IStream.hxx> |
2613378e |
29 | #include <TColStd_SequenceOfAsciiString.hxx> |
42cf5bc1 |
30 | #include <PCDM_ReaderStatus.hxx> |
31 | #include <PCDM_StoreStatus.hxx> |
6fe96f84 |
32 | |
42cf5bc1 |
33 | class Resource_Manager; |
34 | class Standard_NoSuchObject; |
35 | class TDocStd_Document; |
36 | class TCollection_ExtendedString; |
37 | |
42cf5bc1 |
38 | class TDocStd_Application; |
39 | DEFINE_STANDARD_HANDLE(TDocStd_Application, CDF_Application) |
40 | |
41 | |
42 | //! The abstract root class for all application classes. |
43 | //! They are in charge of: |
44 | //! - Creating documents |
45 | //! - Storing documents and retrieving them |
46 | //! - Initializing document views. |
47 | //! To create a useful OCAF-based application, you |
48 | //! derive a class from Application and implement |
49 | //! the methods below. You will have to redefine the |
50 | //! deferred (virtual) methods Formats, |
51 | //! InitDocument, and Resources, and override others. |
52 | //! The application is a container for a document, |
53 | //! which in its turn is the container of the data |
54 | //! framework made up of labels and attributes. |
55 | //! Besides furnishing a container for documents, |
56 | //! TDocStd_Application provides the following |
57 | //! services for them: |
58 | //! - Creation of new documents |
59 | //! - Activation of documents in sessions of an application |
60 | //! - Storage and retrieval of documents |
61 | //! - Initialization of document views. |
62 | //! Note: |
63 | //! If a client needs detailed information concerning |
83ae3591 |
64 | //! the events during the Open/Store operation, a MessageDriver |
65 | //! based on Message_PrinterOStream may be used. In case of need client |
66 | //! can implement his own version inheriting from Message_Printer class |
67 | //! and add it to the Messanger. |
68 | //! Also the trace level of messages can be tuned by setting trace level (SetTraceLevel (Gravity )) for the used Printer. |
69 | //! By default, trace level is Message_Info, so that all messages are output. |
70 | |
42cf5bc1 |
71 | class TDocStd_Application : public CDF_Application |
72 | { |
73 | |
74 | public: |
75 | |
6fe96f84 |
76 | //! Constructs the new instance and registers it in CDM_Session |
77 | Standard_EXPORT TDocStd_Application(); |
42cf5bc1 |
78 | |
79 | //! Check if meta data driver was successfully loaded |
80 | //! by the application constructor |
81 | Standard_EXPORT Standard_Boolean IsDriverLoaded() const; |
6fe96f84 |
82 | |
04232180 |
83 | //! Redefines message driver, by default outputs to std::cout. |
83ae3591 |
84 | Standard_EXPORT virtual Handle(Message_Messenger) MessageDriver() Standard_OVERRIDE; |
42cf5bc1 |
85 | |
6fe96f84 |
86 | //! Returns resource manager defining supported persistent formats. |
87 | //! |
88 | //! Default implementation loads resource file with name ResourcesName(), |
89 | //! unless field myResources is already initialized (either by |
90 | //! previous call or in any other way). |
91 | //! |
92 | //! The resource manager should define: |
93 | //! |
94 | //! * Format name for each file extension supported: |
95 | //! - [Extension].FileFormat: [Format] |
96 | //! |
97 | //! * For each format supported (as returned by Formats()), |
98 | //! its extension, description string, and (when applicable) |
99 | //! GUIDs of storage and retrieval plugins: |
100 | //! - [Format].Description: [Description] |
101 | //! - [Format].FileExtension: [Extension] |
102 | //! - [Format].RetrievalPlugin: [GUID] (optional) |
103 | //! - [Format].StoragePlugin: [GUID] (optional) |
42cf5bc1 |
104 | Standard_EXPORT virtual Handle(Resource_Manager) Resources() Standard_OVERRIDE; |
105 | |
106 | //! Returns the name of the file containing the |
6fe96f84 |
107 | //! resources of this application, for support of legacy |
108 | //! method of loading formats data from resource files. |
109 | //! |
110 | //! Method DefineFormat() can be used to define all necessary |
111 | //! parameters explicitly without actually using resource files. |
112 | //! |
113 | //! In a resource file, the application associates the |
114 | //! schema name of the document with the storage and |
42cf5bc1 |
115 | //! retrieval plug-ins that are to be loaded for each |
116 | //! document. On retrieval, the application reads the |
117 | //! schema name in the heading of the CSF file and |
118 | //! loads the plug-in indicated in the resource file. |
119 | //! This plug-in instantiates the actual driver for |
120 | //! transient-persistent conversion. |
121 | //! Your application can bring this process into play |
122 | //! by defining a class which inherits |
123 | //! CDF_Application and redefines the function |
124 | //! which returns the appropriate resources file. At |
125 | //! this point, the function Retrieve and the class |
126 | //! CDF_Store can be called. This allows you to |
127 | //! deal with storage and retrieval of - as well as |
128 | //! copying and pasting - documents. |
129 | //! To implement a class like this, several virtual |
130 | //! functions should be redefined. In particular, you |
131 | //! must redefine the abstract function Resources |
132 | //! inherited from the superclass CDM_Application. |
6fe96f84 |
133 | //! |
134 | //! Default implementation returns empty string. |
135 | Standard_EXPORT virtual Standard_CString ResourcesName(); |
136 | |
137 | //! Sets up resources and registers read and storage drivers for |
138 | //! the specified format. |
139 | //! |
140 | //! @param theFormat - unique name for the format, used to identify it. |
141 | //! @param theDescription - textual description of the format. |
142 | //! @param theExtension - extension of the files in that format. |
143 | //! The same extension can be used by several formats. |
144 | //! @param theReader - instance of the read driver for the format. |
145 | //! Null value is allowed (no possibility to read). |
146 | //! @param theWriter - instance of the write driver for the format. |
147 | //! Null value is allowed (no possibility to write). |
148 | Standard_EXPORT void DefineFormat (const TCollection_AsciiString& theFormat, |
149 | const TCollection_AsciiString& theDescription, |
150 | const TCollection_AsciiString& theExtension, |
151 | const Handle(PCDM_RetrievalDriver)& theReader, |
152 | const Handle(PCDM_StorageDriver)& theWriter); |
2613378e |
153 | |
154 | //! Returns the sequence of reading formats supported by the application. |
155 | //! |
156 | //! @param theFormats - sequence of reading formats. Output parameter. |
157 | Standard_EXPORT void ReadingFormats(TColStd_SequenceOfAsciiString &theFormats); |
158 | |
159 | //! Returns the sequence of writing formats supported by the application. |
160 | //! |
161 | //! @param theFormats - sequence of writing formats. Output parameter. |
162 | Standard_EXPORT void WritingFormats(TColStd_SequenceOfAsciiString &theFormats); |
163 | |
42cf5bc1 |
164 | //! returns the number of documents handled by the current applicative session. |
165 | Standard_EXPORT Standard_Integer NbDocuments() const; |
166 | |
167 | //! Constructs the new document aDoc. |
168 | //! aDoc is identified by the index index which is |
169 | //! any integer between 1 and n where n is the |
170 | //! number of documents returned by NbDocument. |
171 | //! Example |
172 | //! Handle(TDocStd_Application) |
173 | //! anApp; |
174 | //! if (!CafTest::Find(A)) return 1; |
175 | //! Handle(TDocStd) aDoc; |
176 | //! Standard_Integer nbdoc = anApp->NbDocuments(); |
177 | //! for (Standard_Integer i = 1; i <= nbdoc; i++) { |
178 | //! aApp->GetDocument(i,aDoc); |
179 | Standard_EXPORT void GetDocument (const Standard_Integer index, Handle(TDocStd_Document)& aDoc) const; |
180 | |
42cf5bc1 |
181 | //! Constructs the empty new document aDoc. |
182 | //! This document will have the format format. |
183 | //! If InitDocument is redefined for a specific |
184 | //! application, the new document is handled by the |
185 | //! applicative session. |
186 | Standard_EXPORT virtual void NewDocument (const TCollection_ExtendedString& format, Handle(TDocStd_Document)& aDoc); |
187 | |
188 | //! Initialize the document aDoc for the applicative session. |
189 | //! This virtual function is called by NewDocument |
190 | //! and is to be redefined for each specific application. |
191 | //! Modified flag (different of disk version) |
192 | //! ============= |
193 | //! to open/save a document |
194 | //! ======================= |
195 | Standard_EXPORT virtual void InitDocument (const Handle(TDocStd_Document)& aDoc) const; |
196 | |
197 | //! Close the given document. the document is not any more |
198 | //! handled by the applicative session. |
199 | Standard_EXPORT void Close (const Handle(TDocStd_Document)& aDoc); |
200 | |
201 | //! Returns an index for the document found in the |
202 | //! path path in this applicative session. |
203 | //! If the returned value is 0, the document is not |
204 | //! present in the applicative session. |
205 | //! This method can be used for the interactive part |
206 | //! of an application. For instance, on a call to |
207 | //! Open, the document to be opened may already |
208 | //! be in memory. IsInSession checks to see if this |
209 | //! is the case. Open can be made to depend on |
210 | //! the value of the index returned: if IsInSession |
211 | //! returns 0, the document is opened; if it returns |
212 | //! another value, a message is displayed asking the |
213 | //! user if he wants to override the version of the |
214 | //! document in memory. |
215 | //! Example: |
216 | //! Standard_Integer insession = A->IsInSession(aDoc); |
217 | //! if (insession > 0) { |
04232180 |
218 | //! std::cout << "document " << insession << " is already in session" << std::endl; |
42cf5bc1 |
219 | //! return 0; |
220 | //! } |
221 | Standard_EXPORT Standard_Integer IsInSession (const TCollection_ExtendedString& path) const; |
222 | |
223 | //! Retrieves the document aDoc stored under the |
224 | //! name aName in the directory directory. |
225 | //! In order not to override a version of aDoc which |
226 | //! is already in memory, this method can be made |
227 | //! to depend on the value returned by IsInSession. |
6d8f9f4a |
228 | Standard_EXPORT PCDM_ReaderStatus Open (const TCollection_ExtendedString& path, |
229 | Handle(TDocStd_Document)& aDoc, |
230 | const Handle(Message_ProgressIndicator)& theProgress = NULL); |
4ff92abe |
231 | |
232 | //! Retrieves aDoc from standard SEEKABLE stream theIStream. |
233 | //! the stream should support SEEK fuctionality |
6d8f9f4a |
234 | Standard_EXPORT PCDM_ReaderStatus Open (Standard_IStream& theIStream, Handle(TDocStd_Document)& theDoc, |
235 | const Handle(Message_ProgressIndicator)& theProgress = NULL); |
4ff92abe |
236 | |
42cf5bc1 |
237 | |
238 | //! Save the active document in the file <name> in the |
239 | //! path <path> ; o verwrites the file if it already exists. |
6d8f9f4a |
240 | Standard_EXPORT PCDM_StoreStatus SaveAs (const Handle(TDocStd_Document)& aDoc, |
241 | const TCollection_ExtendedString& path, |
242 | const Handle(Message_ProgressIndicator)& theProgress = NULL); |
4ff92abe |
243 | |
244 | //! Save theDoc to standard SEEKABLE stream theOStream. |
245 | //! the stream should support SEEK fuctionality |
6d8f9f4a |
246 | Standard_EXPORT PCDM_StoreStatus SaveAs (const Handle(TDocStd_Document)& theDoc, |
247 | Standard_OStream& theOStream, |
248 | const Handle(Message_ProgressIndicator)& theProgress = NULL); |
42cf5bc1 |
249 | |
250 | //! Save aDoc active document. |
251 | //! Exceptions: |
252 | //! Standard_NotImplemented if the document |
253 | //! was not retrieved in the applicative session by using Open. |
6d8f9f4a |
254 | Standard_EXPORT PCDM_StoreStatus Save (const Handle(TDocStd_Document)& aDoc, |
255 | const Handle(Message_ProgressIndicator)& theProgress = NULL); |
42cf5bc1 |
256 | |
257 | //! Save the active document in the file <name> in the |
258 | //! path <path> . overwrite the file if it |
259 | //! already exist. |
6d8f9f4a |
260 | Standard_EXPORT PCDM_StoreStatus SaveAs (const Handle(TDocStd_Document)& aDoc, |
261 | const TCollection_ExtendedString& path, |
262 | TCollection_ExtendedString& theStatusMessage, |
263 | const Handle(Message_ProgressIndicator)& theProgress = NULL); |
4ff92abe |
264 | |
265 | //! Save theDoc TO standard SEEKABLE stream theOStream. |
266 | //! the stream should support SEEK fuctionality |
6d8f9f4a |
267 | Standard_EXPORT PCDM_StoreStatus SaveAs (const Handle(TDocStd_Document)& theDoc, |
268 | Standard_OStream& theOStream, |
269 | TCollection_ExtendedString& theStatusMessage, |
270 | const Handle(Message_ProgressIndicator)& theProgress = NULL); |
42cf5bc1 |
271 | |
272 | //! Save the document overwriting the previous file |
6d8f9f4a |
273 | Standard_EXPORT PCDM_StoreStatus Save (const Handle(TDocStd_Document)& aDoc, |
274 | TCollection_ExtendedString& theStatusMessage, |
275 | const Handle(Message_ProgressIndicator)& theProgress = NULL); |
42cf5bc1 |
276 | |
42cf5bc1 |
277 | //! Notification that is fired at each OpenTransaction event. |
278 | Standard_EXPORT virtual void OnOpenTransaction (const Handle(TDocStd_Document)& theDoc); |
279 | |
280 | //! Notification that is fired at each CommitTransaction event. |
281 | Standard_EXPORT virtual void OnCommitTransaction (const Handle(TDocStd_Document)& theDoc); |
282 | |
283 | //! Notification that is fired at each AbortTransaction event. |
284 | Standard_EXPORT virtual void OnAbortTransaction (const Handle(TDocStd_Document)& theDoc); |
285 | |
bc73b006 |
286 | //! Dumps the content of me into the stream |
287 | Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const; |
288 | |
6fe96f84 |
289 | DEFINE_STANDARD_RTTIEXT(TDocStd_Application,CDF_Application) |
290 | |
291 | protected: |
83ae3591 |
292 | Handle(Message_Messenger) myMessageDriver; |
42cf5bc1 |
293 | Handle(Resource_Manager) myResources; |
294 | Standard_Boolean myIsDriverLoaded; |
42cf5bc1 |
295 | }; |
296 | |
42cf5bc1 |
297 | #endif // _TDocStd_Application_HeaderFile |