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
6 // This file is part of Open CASCADE Technology software library.
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.
14 // Alternatively, this file may be used under the terms of Open CASCADE
15 // commercial license or contractual agreement.
17 #ifndef _TDocStd_Application_HeaderFile
18 #define _TDocStd_Application_HeaderFile
20 #include <Standard.hxx>
21 #include <Standard_Type.hxx>
23 #include <Standard_Boolean.hxx>
24 #include <CDF_Application.hxx>
25 #include <Message_Messenger.hxx>
26 #include <Standard_CString.hxx>
27 #include <Standard_Integer.hxx>
28 #include <Standard_IStream.hxx>
29 #include <TColStd_SequenceOfAsciiString.hxx>
30 #include <PCDM_ReaderStatus.hxx>
31 #include <PCDM_StoreStatus.hxx>
32 #include <TDocStd_Document.hxx>
34 class Resource_Manager;
35 class Standard_NoSuchObject;
37 class TCollection_ExtendedString;
39 class TDocStd_Application;
40 DEFINE_STANDARD_HANDLE(TDocStd_Application, CDF_Application)
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.
64 //! If a client needs detailed information concerning
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
68 //! and add it to the Messenger.
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.
72 class TDocStd_Application : public CDF_Application
77 //! Constructs the new instance and registers it in CDM_Session
78 Standard_EXPORT TDocStd_Application();
80 //! Check if meta data driver was successfully loaded
81 //! by the application constructor
82 Standard_EXPORT Standard_Boolean IsDriverLoaded() const;
84 //! Returns resource manager defining supported persistent formats.
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).
90 //! The resource manager should define:
92 //! * Format name for each file extension supported:
93 //! - [Extension].FileFormat: [Format]
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)
102 Standard_EXPORT virtual Handle(Resource_Manager) Resources() Standard_OVERRIDE;
104 //! Returns the name of the file containing the
105 //! resources of this application, for support of legacy
106 //! method of loading formats data from resource files.
108 //! Method DefineFormat() can be used to define all necessary
109 //! parameters explicitly without actually using resource files.
111 //! In a resource file, the application associates the
112 //! schema name of the document with the storage and
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.
132 //! Default implementation returns empty string.
133 Standard_EXPORT virtual Standard_CString ResourcesName();
135 //! Sets up resources and registers read and storage drivers for
136 //! the specified format.
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);
152 //! Returns the sequence of reading formats supported by the application.
154 //! @param theFormats - sequence of reading formats. Output parameter.
155 Standard_EXPORT void ReadingFormats(TColStd_SequenceOfAsciiString &theFormats);
157 //! Returns the sequence of writing formats supported by the application.
159 //! @param theFormats - sequence of writing formats. Output parameter.
160 Standard_EXPORT void WritingFormats(TColStd_SequenceOfAsciiString &theFormats);
162 //! returns the number of documents handled by the current applicative session.
163 Standard_EXPORT Standard_Integer NbDocuments() const;
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.
170 //! Handle(TDocStd_Application)
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;
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.
184 Standard_EXPORT virtual void NewDocument (const TCollection_ExtendedString& format, Handle(CDM_Document)& aDoc) Standard_OVERRIDE;
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);
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)
195 //! to open/save a document
196 //! =======================
197 Standard_EXPORT virtual void InitDocument (const Handle(CDM_Document)& aDoc) const Standard_OVERRIDE;
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);
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.
218 //! Standard_Integer insession = A->IsInSession(aDoc);
219 //! if (insession > 0) {
220 //! std::cout << "document " << insession << " is already in session" << std::endl;
223 Standard_EXPORT Standard_Integer IsInSession (const TCollection_ExtendedString& path) const;
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,
234 Handle(TDocStd_Document)& theDoc,
235 const Handle(PCDM_ReaderFilter)& theFilter,
236 const Message_ProgressRange& theRange = Message_ProgressRange());
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())
249 return Open (thePath, theDoc, Handle(PCDM_ReaderFilter)(), theRange);
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,
261 const Message_ProgressRange& theRange = Message_ProgressRange());
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())
272 return Open (theIStream, theDoc, Handle(PCDM_ReaderFilter)(), theRange);
276 //! Save the active document in the file <name> in the
277 //! path <path> ; o verwrites the file if it already exists.
278 Standard_EXPORT PCDM_StoreStatus SaveAs (const Handle(TDocStd_Document)& theDoc,
279 const TCollection_ExtendedString& path,
280 const Message_ProgressRange& theRange = Message_ProgressRange());
282 //! Save theDoc to standard SEEKABLE stream theOStream.
283 //! the stream should support SEEK functionality
284 Standard_EXPORT PCDM_StoreStatus SaveAs (const Handle(TDocStd_Document)& theDoc,
285 Standard_OStream& theOStream,
286 const Message_ProgressRange& theRange = Message_ProgressRange());
288 //! Save aDoc active document.
290 //! Standard_NotImplemented if the document
291 //! was not retrieved in the applicative session by using Open.
292 Standard_EXPORT PCDM_StoreStatus Save (const Handle(TDocStd_Document)& theDoc,
293 const Message_ProgressRange& theRange = Message_ProgressRange());
295 //! Save the active document in the file <name> in the
296 //! path <path> . overwrite the file if it
298 Standard_EXPORT PCDM_StoreStatus SaveAs (const Handle(TDocStd_Document)& theDoc,
299 const TCollection_ExtendedString& path,
300 TCollection_ExtendedString& theStatusMessage,
301 const Message_ProgressRange& theRange = Message_ProgressRange());
303 //! Save theDoc TO standard SEEKABLE stream theOStream.
304 //! the stream should support SEEK functionality
305 Standard_EXPORT PCDM_StoreStatus SaveAs (const Handle(TDocStd_Document)& theDoc,
306 Standard_OStream& theOStream,
307 TCollection_ExtendedString& theStatusMessage,
308 const Message_ProgressRange& theRange = Message_ProgressRange());
310 //! Save the document overwriting the previous file
311 Standard_EXPORT PCDM_StoreStatus Save (const Handle(TDocStd_Document)& theDoc,
312 TCollection_ExtendedString& theStatusMessage,
313 const Message_ProgressRange& theRange = Message_ProgressRange());
315 //! Notification that is fired at each OpenTransaction event.
316 Standard_EXPORT virtual void OnOpenTransaction (const Handle(TDocStd_Document)& theDoc);
318 //! Notification that is fired at each CommitTransaction event.
319 Standard_EXPORT virtual void OnCommitTransaction (const Handle(TDocStd_Document)& theDoc);
321 //! Notification that is fired at each AbortTransaction event.
322 Standard_EXPORT virtual void OnAbortTransaction (const Handle(TDocStd_Document)& theDoc);
324 //! Dumps the content of me into the stream
325 Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
327 DEFINE_STANDARD_RTTIEXT(TDocStd_Application, CDF_Application)
331 Handle(Resource_Manager) myResources;
332 Standard_Boolean myIsDriverLoaded;
335 #endif // _TDocStd_Application_HeaderFile