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> |
42cf5bc1 |
29 | #include <TColStd_SequenceOfExtendedString.hxx> |
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); |
42cf5bc1 |
152 | |
153 | //! returns the number of documents handled by the current applicative session. |
154 | Standard_EXPORT Standard_Integer NbDocuments() const; |
155 | |
156 | //! Constructs the new document aDoc. |
157 | //! aDoc is identified by the index index which is |
158 | //! any integer between 1 and n where n is the |
159 | //! number of documents returned by NbDocument. |
160 | //! Example |
161 | //! Handle(TDocStd_Application) |
162 | //! anApp; |
163 | //! if (!CafTest::Find(A)) return 1; |
164 | //! Handle(TDocStd) aDoc; |
165 | //! Standard_Integer nbdoc = anApp->NbDocuments(); |
166 | //! for (Standard_Integer i = 1; i <= nbdoc; i++) { |
167 | //! aApp->GetDocument(i,aDoc); |
168 | Standard_EXPORT void GetDocument (const Standard_Integer index, Handle(TDocStd_Document)& aDoc) const; |
169 | |
42cf5bc1 |
170 | //! Constructs the empty new document aDoc. |
171 | //! This document will have the format format. |
172 | //! If InitDocument is redefined for a specific |
173 | //! application, the new document is handled by the |
174 | //! applicative session. |
175 | Standard_EXPORT virtual void NewDocument (const TCollection_ExtendedString& format, Handle(TDocStd_Document)& aDoc); |
176 | |
177 | //! Initialize the document aDoc for the applicative session. |
178 | //! This virtual function is called by NewDocument |
179 | //! and is to be redefined for each specific application. |
180 | //! Modified flag (different of disk version) |
181 | //! ============= |
182 | //! to open/save a document |
183 | //! ======================= |
184 | Standard_EXPORT virtual void InitDocument (const Handle(TDocStd_Document)& aDoc) const; |
185 | |
186 | //! Close the given document. the document is not any more |
187 | //! handled by the applicative session. |
188 | Standard_EXPORT void Close (const Handle(TDocStd_Document)& aDoc); |
189 | |
190 | //! Returns an index for the document found in the |
191 | //! path path in this applicative session. |
192 | //! If the returned value is 0, the document is not |
193 | //! present in the applicative session. |
194 | //! This method can be used for the interactive part |
195 | //! of an application. For instance, on a call to |
196 | //! Open, the document to be opened may already |
197 | //! be in memory. IsInSession checks to see if this |
198 | //! is the case. Open can be made to depend on |
199 | //! the value of the index returned: if IsInSession |
200 | //! returns 0, the document is opened; if it returns |
201 | //! another value, a message is displayed asking the |
202 | //! user if he wants to override the version of the |
203 | //! document in memory. |
204 | //! Example: |
205 | //! Standard_Integer insession = A->IsInSession(aDoc); |
206 | //! if (insession > 0) { |
207 | //! cout << "document " << insession << " is already in session" << endl; |
208 | //! return 0; |
209 | //! } |
210 | Standard_EXPORT Standard_Integer IsInSession (const TCollection_ExtendedString& path) const; |
211 | |
212 | //! Retrieves the document aDoc stored under the |
213 | //! name aName in the directory directory. |
214 | //! In order not to override a version of aDoc which |
215 | //! is already in memory, this method can be made |
216 | //! to depend on the value returned by IsInSession. |
217 | Standard_EXPORT PCDM_ReaderStatus Open (const TCollection_ExtendedString& path, Handle(TDocStd_Document)& aDoc); |
4ff92abe |
218 | |
219 | //! Retrieves aDoc from standard SEEKABLE stream theIStream. |
220 | //! the stream should support SEEK fuctionality |
221 | Standard_EXPORT PCDM_ReaderStatus Open (Standard_IStream& theIStream, Handle(TDocStd_Document)& theDoc); |
222 | |
42cf5bc1 |
223 | |
224 | //! Save the active document in the file <name> in the |
225 | //! path <path> ; o verwrites the file if it already exists. |
226 | Standard_EXPORT PCDM_StoreStatus SaveAs (const Handle(TDocStd_Document)& aDoc, const TCollection_ExtendedString& path); |
4ff92abe |
227 | |
228 | //! Save theDoc to standard SEEKABLE stream theOStream. |
229 | //! the stream should support SEEK fuctionality |
230 | Standard_EXPORT PCDM_StoreStatus SaveAs(const Handle(TDocStd_Document)& theDoc, Standard_OStream& theOStream); |
42cf5bc1 |
231 | |
232 | //! Save aDoc active document. |
233 | //! Exceptions: |
234 | //! Standard_NotImplemented if the document |
235 | //! was not retrieved in the applicative session by using Open. |
236 | Standard_EXPORT PCDM_StoreStatus Save (const Handle(TDocStd_Document)& aDoc); |
237 | |
238 | //! Save the active document in the file <name> in the |
239 | //! path <path> . overwrite the file if it |
240 | //! already exist. |
241 | Standard_EXPORT PCDM_StoreStatus SaveAs (const Handle(TDocStd_Document)& aDoc, const TCollection_ExtendedString& path, TCollection_ExtendedString& theStatusMessage); |
4ff92abe |
242 | |
243 | //! Save theDoc TO standard SEEKABLE stream theOStream. |
244 | //! the stream should support SEEK fuctionality |
245 | Standard_EXPORT PCDM_StoreStatus SaveAs(const Handle(TDocStd_Document)& theDoc, Standard_OStream& theOStream, TCollection_ExtendedString& theStatusMessage); |
42cf5bc1 |
246 | |
247 | //! Save the document overwriting the previous file |
248 | Standard_EXPORT PCDM_StoreStatus Save (const Handle(TDocStd_Document)& aDoc, TCollection_ExtendedString& theStatusMessage); |
249 | |
42cf5bc1 |
250 | //! Notification that is fired at each OpenTransaction event. |
251 | Standard_EXPORT virtual void OnOpenTransaction (const Handle(TDocStd_Document)& theDoc); |
252 | |
253 | //! Notification that is fired at each CommitTransaction event. |
254 | Standard_EXPORT virtual void OnCommitTransaction (const Handle(TDocStd_Document)& theDoc); |
255 | |
256 | //! Notification that is fired at each AbortTransaction event. |
257 | Standard_EXPORT virtual void OnAbortTransaction (const Handle(TDocStd_Document)& theDoc); |
258 | |
6fe96f84 |
259 | DEFINE_STANDARD_RTTIEXT(TDocStd_Application,CDF_Application) |
260 | |
261 | protected: |
262 | Handle(CDM_MessageDriver) myMessageDriver; |
42cf5bc1 |
263 | Handle(Resource_Manager) myResources; |
264 | Standard_Boolean myIsDriverLoaded; |
42cf5bc1 |
265 | }; |
266 | |
42cf5bc1 |
267 | #endif // _TDocStd_Application_HeaderFile |