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 <Standard_CString.hxx>
26 #include <Standard_Integer.hxx>
27 #include <Standard_IStream.hxx>
28 #include <TColStd_SequenceOfExtendedString.hxx>
29 #include <PCDM_ReaderStatus.hxx>
30 #include <PCDM_StoreStatus.hxx>
31 class Resource_Manager;
32 class Standard_NoSuchObject;
33 class TDocStd_Document;
34 class TCollection_ExtendedString;
37 class TDocStd_Application;
38 DEFINE_STANDARD_HANDLE(TDocStd_Application, CDF_Application)
41 //! The abstract root class for all application classes.
42 //! They are in charge of:
43 //! - Creating documents
44 //! - Storing documents and retrieving them
45 //! - Initializing document views.
46 //! To create a useful OCAF-based application, you
47 //! derive a class from Application and implement
48 //! the methods below. You will have to redefine the
49 //! deferred (virtual) methods Formats,
50 //! InitDocument, and Resources, and override others.
51 //! The application is a container for a document,
52 //! which in its turn is the container of the data
53 //! framework made up of labels and attributes.
54 //! Besides furnishing a container for documents,
55 //! TDocStd_Application provides the following
56 //! services for them:
57 //! - Creation of new documents
58 //! - Activation of documents in sessions of an application
59 //! - Storage and retrieval of documents
60 //! - Initialization of document views.
62 //! If a client needs detailed information concerning
63 //! the events during the Open/Store operation, MessageDriver
64 //! inherited from CDM_MessageDriver of the
65 //! corresponding application has to be implemented.
66 //! If the MessageDriver is not defined all messages
67 //! will be (by default) directed to
68 //! CDM_NullMessageDriver and will be lost.
69 class TDocStd_Application : public CDF_Application
75 //! Check if meta data driver was successfully loaded
76 //! by the application constructor
77 Standard_EXPORT Standard_Boolean IsDriverLoaded() const;
79 //! create (if not done) a Manager using ResourcesName
81 Standard_EXPORT virtual Handle(Resource_Manager) Resources() Standard_OVERRIDE;
83 //! Returns the name of the file containing the
84 //! resources of this application.
85 //! In a resource file, the application associates the schema name
86 //! of the document with the storage and
87 //! retrieval plug-ins that are to be loaded for each
88 //! document. On retrieval, the application reads the
89 //! schema name in the heading of the CSF file and
90 //! loads the plug-in indicated in the resource file.
91 //! This plug-in instantiates the actual driver for
92 //! transient-persistent conversion.
93 //! Your application can bring this process into play
94 //! by defining a class which inherits
95 //! CDF_Application and redefines the function
96 //! which returns the appropriate resources file. At
97 //! this point, the function Retrieve and the class
98 //! CDF_Store can be called. This allows you to
99 //! deal with storage and retrieval of - as well as
100 //! copying and pasting - documents.
101 //! To implement a class like this, several virtual
102 //! functions should be redefined. In particular, you
103 //! must redefine the abstract function Resources
104 //! inherited from the superclass CDM_Application.
105 Standard_EXPORT virtual Standard_CString ResourcesName() = 0;
107 //! returns the number of documents handled by the current applicative session.
108 Standard_EXPORT Standard_Integer NbDocuments() const;
110 //! Constructs the new document aDoc.
111 //! aDoc is identified by the index index which is
112 //! any integer between 1 and n where n is the
113 //! number of documents returned by NbDocument.
115 //! Handle(TDocStd_Application)
117 //! if (!CafTest::Find(A)) return 1;
118 //! Handle(TDocStd) aDoc;
119 //! Standard_Integer nbdoc = anApp->NbDocuments();
120 //! for (Standard_Integer i = 1; i <= nbdoc; i++) {
121 //! aApp->GetDocument(i,aDoc);
122 Standard_EXPORT void GetDocument (const Standard_Integer index, Handle(TDocStd_Document)& aDoc) const;
125 //! Returns the format name Formats
126 //! representing the format supported for
127 //! application documents.
128 //! This virtual function is to be redefined for each
129 //! specific application.
130 Standard_EXPORT virtual void Formats (TColStd_SequenceOfExtendedString& Formats) Standard_OVERRIDE = 0;
132 //! Constructs the empty new document aDoc.
133 //! This document will have the format format.
134 //! If InitDocument is redefined for a specific
135 //! application, the new document is handled by the
136 //! applicative session.
137 Standard_EXPORT virtual void NewDocument (const TCollection_ExtendedString& format, Handle(TDocStd_Document)& aDoc);
139 //! Initialize the document aDoc for the applicative session.
140 //! This virtual function is called by NewDocument
141 //! and is to be redefined for each specific application.
142 //! Modified flag (different of disk version)
144 //! to open/save a document
145 //! =======================
146 Standard_EXPORT virtual void InitDocument (const Handle(TDocStd_Document)& aDoc) const;
148 //! Close the given document. the document is not any more
149 //! handled by the applicative session.
150 Standard_EXPORT void Close (const Handle(TDocStd_Document)& aDoc);
152 //! Returns an index for the document found in the
153 //! path path in this applicative session.
154 //! If the returned value is 0, the document is not
155 //! present in the applicative session.
156 //! This method can be used for the interactive part
157 //! of an application. For instance, on a call to
158 //! Open, the document to be opened may already
159 //! be in memory. IsInSession checks to see if this
160 //! is the case. Open can be made to depend on
161 //! the value of the index returned: if IsInSession
162 //! returns 0, the document is opened; if it returns
163 //! another value, a message is displayed asking the
164 //! user if he wants to override the version of the
165 //! document in memory.
167 //! Standard_Integer insession = A->IsInSession(aDoc);
168 //! if (insession > 0) {
169 //! cout << "document " << insession << " is already in session" << endl;
172 Standard_EXPORT Standard_Integer IsInSession (const TCollection_ExtendedString& path) const;
174 //! Retrieves the document aDoc stored under the
175 //! name aName in the directory directory.
176 //! In order not to override a version of aDoc which
177 //! is already in memory, this method can be made
178 //! to depend on the value returned by IsInSession.
179 Standard_EXPORT PCDM_ReaderStatus Open (const TCollection_ExtendedString& path, Handle(TDocStd_Document)& aDoc);
181 //! Retrieves aDoc from standard SEEKABLE stream theIStream.
182 //! the stream should support SEEK fuctionality
183 Standard_EXPORT PCDM_ReaderStatus Open (Standard_IStream& theIStream, Handle(TDocStd_Document)& theDoc);
186 //! Save the active document in the file <name> in the
187 //! path <path> ; o verwrites the file if it already exists.
188 Standard_EXPORT PCDM_StoreStatus SaveAs (const Handle(TDocStd_Document)& aDoc, const TCollection_ExtendedString& path);
190 //! Save theDoc to standard SEEKABLE stream theOStream.
191 //! the stream should support SEEK fuctionality
192 Standard_EXPORT PCDM_StoreStatus SaveAs(const Handle(TDocStd_Document)& theDoc, Standard_OStream& theOStream);
194 //! Save aDoc active document.
196 //! Standard_NotImplemented if the document
197 //! was not retrieved in the applicative session by using Open.
198 Standard_EXPORT PCDM_StoreStatus Save (const Handle(TDocStd_Document)& aDoc);
200 //! Save the active document in the file <name> in the
201 //! path <path> . overwrite the file if it
203 Standard_EXPORT PCDM_StoreStatus SaveAs (const Handle(TDocStd_Document)& aDoc, const TCollection_ExtendedString& path, TCollection_ExtendedString& theStatusMessage);
205 //! Save theDoc TO standard SEEKABLE stream theOStream.
206 //! the stream should support SEEK fuctionality
207 Standard_EXPORT PCDM_StoreStatus SaveAs(const Handle(TDocStd_Document)& theDoc, Standard_OStream& theOStream, TCollection_ExtendedString& theStatusMessage);
209 //! Save the document overwriting the previous file
210 Standard_EXPORT PCDM_StoreStatus Save (const Handle(TDocStd_Document)& aDoc, TCollection_ExtendedString& theStatusMessage);
213 friend class TDocStd_Document;
216 DEFINE_STANDARD_RTTIEXT(TDocStd_Application,CDF_Application)
221 Standard_EXPORT TDocStd_Application();
223 //! Notification that is fired at each OpenTransaction event.
224 Standard_EXPORT virtual void OnOpenTransaction (const Handle(TDocStd_Document)& theDoc);
226 //! Notification that is fired at each CommitTransaction event.
227 Standard_EXPORT virtual void OnCommitTransaction (const Handle(TDocStd_Document)& theDoc);
229 //! Notification that is fired at each AbortTransaction event.
230 Standard_EXPORT virtual void OnAbortTransaction (const Handle(TDocStd_Document)& theDoc);
232 Handle(Resource_Manager) myResources;
233 Standard_Boolean myIsDriverLoaded;
249 #endif // _TDocStd_Application_HeaderFile