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