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> |
6fe96f84 |
25 | #include <CDM_MessageDriver.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 |
64 | //! the events during the Open/Store operation, MessageDriver |
65 | //! inherited from CDM_MessageDriver of the |
66 | //! corresponding application has to be implemented. |
67 | //! If the MessageDriver is not defined all messages |
68 | //! will be (by default) directed to |
69 | //! CDM_NullMessageDriver and will be lost. |
70 | class TDocStd_Application : public CDF_Application |
71 | { |
72 | |
73 | public: |
74 | |
6fe96f84 |
75 | //! Constructs the new instance and registers it in CDM_Session |
76 | Standard_EXPORT TDocStd_Application(); |
42cf5bc1 |
77 | |
78 | //! Check if meta data driver was successfully loaded |
79 | //! by the application constructor |
80 | Standard_EXPORT Standard_Boolean IsDriverLoaded() const; |
6fe96f84 |
81 | |
82 | //! Redefines message driver, by default outputs to cout. |
83 | Standard_EXPORT virtual Handle(CDM_MessageDriver) MessageDriver() Standard_OVERRIDE; |
42cf5bc1 |
84 | |
6fe96f84 |
85 | //! Returns resource manager defining supported persistent formats. |
86 | //! |
87 | //! Default implementation loads resource file with name ResourcesName(), |
88 | //! unless field myResources is already initialized (either by |
89 | //! previous call or in any other way). |
90 | //! |
91 | //! The resource manager should define: |
92 | //! |
93 | //! * Format name for each file extension supported: |
94 | //! - [Extension].FileFormat: [Format] |
95 | //! |
96 | //! * For each format supported (as returned by Formats()), |
97 | //! its extension, description string, and (when applicable) |
98 | //! GUIDs of storage and retrieval plugins: |
99 | //! - [Format].Description: [Description] |
100 | //! - [Format].FileExtension: [Extension] |
101 | //! - [Format].RetrievalPlugin: [GUID] (optional) |
102 | //! - [Format].StoragePlugin: [GUID] (optional) |
42cf5bc1 |
103 | Standard_EXPORT virtual Handle(Resource_Manager) Resources() Standard_OVERRIDE; |
104 | |
105 | //! Returns the name of the file containing the |
6fe96f84 |
106 | //! resources of this application, for support of legacy |
107 | //! method of loading formats data from resource files. |
108 | //! |
109 | //! Method DefineFormat() can be used to define all necessary |
110 | //! parameters explicitly without actually using resource files. |
111 | //! |
112 | //! In a resource file, the application associates the |
113 | //! schema name of the document with the storage and |
42cf5bc1 |
114 | //! retrieval plug-ins that are to be loaded for each |
115 | //! document. On retrieval, the application reads the |
116 | //! schema name in the heading of the CSF file and |
117 | //! loads the plug-in indicated in the resource file. |
118 | //! This plug-in instantiates the actual driver for |
119 | //! transient-persistent conversion. |
120 | //! Your application can bring this process into play |
121 | //! by defining a class which inherits |
122 | //! CDF_Application and redefines the function |
123 | //! which returns the appropriate resources file. At |
124 | //! this point, the function Retrieve and the class |
125 | //! CDF_Store can be called. This allows you to |
126 | //! deal with storage and retrieval of - as well as |
127 | //! copying and pasting - documents. |
128 | //! To implement a class like this, several virtual |
129 | //! functions should be redefined. In particular, you |
130 | //! must redefine the abstract function Resources |
131 | //! inherited from the superclass CDM_Application. |
6fe96f84 |
132 | //! |
133 | //! Default implementation returns empty string. |
134 | Standard_EXPORT virtual Standard_CString ResourcesName(); |
135 | |
136 | //! Sets up resources and registers read and storage drivers for |
137 | //! the specified format. |
138 | //! |
139 | //! @param theFormat - unique name for the format, used to identify it. |
140 | //! @param theDescription - textual description of the format. |
141 | //! @param theExtension - extension of the files in that format. |
142 | //! The same extension can be used by several formats. |
143 | //! @param theReader - instance of the read driver for the format. |
144 | //! Null value is allowed (no possibility to read). |
145 | //! @param theWriter - instance of the write driver for the format. |
146 | //! Null value is allowed (no possibility to write). |
147 | Standard_EXPORT void DefineFormat (const TCollection_AsciiString& theFormat, |
148 | const TCollection_AsciiString& theDescription, |
149 | const TCollection_AsciiString& theExtension, |
150 | const Handle(PCDM_RetrievalDriver)& theReader, |
151 | const Handle(PCDM_StorageDriver)& theWriter); |
2613378e |
152 | |
153 | //! Returns the sequence of reading formats supported by the application. |
154 | //! |
155 | //! @param theFormats - sequence of reading formats. Output parameter. |
156 | Standard_EXPORT void ReadingFormats(TColStd_SequenceOfAsciiString &theFormats); |
157 | |
158 | //! Returns the sequence of writing formats supported by the application. |
159 | //! |
160 | //! @param theFormats - sequence of writing formats. Output parameter. |
161 | Standard_EXPORT void WritingFormats(TColStd_SequenceOfAsciiString &theFormats); |
162 | |
42cf5bc1 |
163 | //! returns the number of documents handled by the current applicative session. |
164 | Standard_EXPORT Standard_Integer NbDocuments() const; |
165 | |
166 | //! Constructs the new document aDoc. |
167 | //! aDoc is identified by the index index which is |
168 | //! any integer between 1 and n where n is the |
169 | //! number of documents returned by NbDocument. |
170 | //! Example |
171 | //! Handle(TDocStd_Application) |
172 | //! anApp; |
173 | //! if (!CafTest::Find(A)) return 1; |
174 | //! Handle(TDocStd) aDoc; |
175 | //! Standard_Integer nbdoc = anApp->NbDocuments(); |
176 | //! for (Standard_Integer i = 1; i <= nbdoc; i++) { |
177 | //! aApp->GetDocument(i,aDoc); |
178 | Standard_EXPORT void GetDocument (const Standard_Integer index, Handle(TDocStd_Document)& aDoc) const; |
179 | |
42cf5bc1 |
180 | //! Constructs the empty new document aDoc. |
181 | //! This document will have the format format. |
182 | //! If InitDocument is redefined for a specific |
183 | //! application, the new document is handled by the |
184 | //! applicative session. |
185 | Standard_EXPORT virtual void NewDocument (const TCollection_ExtendedString& format, Handle(TDocStd_Document)& aDoc); |
186 | |
187 | //! Initialize the document aDoc for the applicative session. |
188 | //! This virtual function is called by NewDocument |
189 | //! and is to be redefined for each specific application. |
190 | //! Modified flag (different of disk version) |
191 | //! ============= |
192 | //! to open/save a document |
193 | //! ======================= |
194 | Standard_EXPORT virtual void InitDocument (const Handle(TDocStd_Document)& aDoc) const; |
195 | |
196 | //! Close the given document. the document is not any more |
197 | //! handled by the applicative session. |
198 | Standard_EXPORT void Close (const Handle(TDocStd_Document)& aDoc); |
199 | |
200 | //! Returns an index for the document found in the |
201 | //! path path in this applicative session. |
202 | //! If the returned value is 0, the document is not |
203 | //! present in the applicative session. |
204 | //! This method can be used for the interactive part |
205 | //! of an application. For instance, on a call to |
206 | //! Open, the document to be opened may already |
207 | //! be in memory. IsInSession checks to see if this |
208 | //! is the case. Open can be made to depend on |
209 | //! the value of the index returned: if IsInSession |
210 | //! returns 0, the document is opened; if it returns |
211 | //! another value, a message is displayed asking the |
212 | //! user if he wants to override the version of the |
213 | //! document in memory. |
214 | //! Example: |
215 | //! Standard_Integer insession = A->IsInSession(aDoc); |
216 | //! if (insession > 0) { |
217 | //! cout << "document " << insession << " is already in session" << endl; |
218 | //! return 0; |
219 | //! } |
220 | Standard_EXPORT Standard_Integer IsInSession (const TCollection_ExtendedString& path) const; |
221 | |
222 | //! Retrieves the document aDoc stored under the |
223 | //! name aName in the directory directory. |
224 | //! In order not to override a version of aDoc which |
225 | //! is already in memory, this method can be made |
226 | //! to depend on the value returned by IsInSession. |
227 | Standard_EXPORT PCDM_ReaderStatus Open (const TCollection_ExtendedString& path, Handle(TDocStd_Document)& aDoc); |
4ff92abe |
228 | |
229 | //! Retrieves aDoc from standard SEEKABLE stream theIStream. |
230 | //! the stream should support SEEK fuctionality |
231 | Standard_EXPORT PCDM_ReaderStatus Open (Standard_IStream& theIStream, Handle(TDocStd_Document)& theDoc); |
232 | |
42cf5bc1 |
233 | |
234 | //! Save the active document in the file <name> in the |
235 | //! path <path> ; o verwrites the file if it already exists. |
236 | Standard_EXPORT PCDM_StoreStatus SaveAs (const Handle(TDocStd_Document)& aDoc, const TCollection_ExtendedString& path); |
4ff92abe |
237 | |
238 | //! Save theDoc to standard SEEKABLE stream theOStream. |
239 | //! the stream should support SEEK fuctionality |
240 | Standard_EXPORT PCDM_StoreStatus SaveAs(const Handle(TDocStd_Document)& theDoc, Standard_OStream& theOStream); |
42cf5bc1 |
241 | |
242 | //! Save aDoc active document. |
243 | //! Exceptions: |
244 | //! Standard_NotImplemented if the document |
245 | //! was not retrieved in the applicative session by using Open. |
246 | Standard_EXPORT PCDM_StoreStatus Save (const Handle(TDocStd_Document)& aDoc); |
247 | |
248 | //! Save the active document in the file <name> in the |
249 | //! path <path> . overwrite the file if it |
250 | //! already exist. |
251 | Standard_EXPORT PCDM_StoreStatus SaveAs (const Handle(TDocStd_Document)& aDoc, const TCollection_ExtendedString& path, TCollection_ExtendedString& theStatusMessage); |
4ff92abe |
252 | |
253 | //! Save theDoc TO standard SEEKABLE stream theOStream. |
254 | //! the stream should support SEEK fuctionality |
255 | Standard_EXPORT PCDM_StoreStatus SaveAs(const Handle(TDocStd_Document)& theDoc, Standard_OStream& theOStream, TCollection_ExtendedString& theStatusMessage); |
42cf5bc1 |
256 | |
257 | //! Save the document overwriting the previous file |
258 | Standard_EXPORT PCDM_StoreStatus Save (const Handle(TDocStd_Document)& aDoc, TCollection_ExtendedString& theStatusMessage); |
259 | |
42cf5bc1 |
260 | //! Notification that is fired at each OpenTransaction event. |
261 | Standard_EXPORT virtual void OnOpenTransaction (const Handle(TDocStd_Document)& theDoc); |
262 | |
263 | //! Notification that is fired at each CommitTransaction event. |
264 | Standard_EXPORT virtual void OnCommitTransaction (const Handle(TDocStd_Document)& theDoc); |
265 | |
266 | //! Notification that is fired at each AbortTransaction event. |
267 | Standard_EXPORT virtual void OnAbortTransaction (const Handle(TDocStd_Document)& theDoc); |
268 | |
6fe96f84 |
269 | DEFINE_STANDARD_RTTIEXT(TDocStd_Application,CDF_Application) |
270 | |
271 | protected: |
272 | Handle(CDM_MessageDriver) myMessageDriver; |
42cf5bc1 |
273 | Handle(Resource_Manager) myResources; |
274 | Standard_Boolean myIsDriverLoaded; |
42cf5bc1 |
275 | }; |
276 | |
42cf5bc1 |
277 | #endif // _TDocStd_Application_HeaderFile |