1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/apadoc.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,319 @@
1.4 +// Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// The main startup of the AppArc server
1.18 +//
1.19 +// apadoc.h
1.20 +//
1.21 +
1.22 +#ifndef __APADOC_H__
1.23 +#define __APADOC_H__
1.24 +
1.25 +#include <e32std.h>
1.26 +#include <e32base.h>
1.27 +#include <gdi.h> // class CPicture::TDetach
1.28 +
1.29 +class CApaApplication;
1.30 +class CApaProcess;
1.31 +class MApaEmbeddedDocObserver;
1.32 +class RFile;
1.33 +class RWriteStream;
1.34 +class CFileStore;
1.35 +class CStreamDictionary;
1.36 +class RFs;
1.37 +class CPicture;
1.38 +class CStreamStore;
1.39 +
1.40 +/** Defines basic behaviour for documents.
1.41 +
1.42 +This is the base class for all documents. A document contains the data associated
1.43 +with the application's content.
1.44 +
1.45 +The class is derived from by the UI framework and is further derived from
1.46 +by the UI application.
1.47 +
1.48 +@publishedAll
1.49 +@released
1.50 +@see CEikDocument */
1.51 +class CApaDocument : public CBase
1.52 +// base class for documents; allows insertion of glass doors.
1.53 + {
1.54 +public:
1.55 + class TCapability
1.56 + /** CApaDocument capabilities.*/
1.57 + {
1.58 + public:
1.59 + IMPORT_C TCapability();
1.60 + inline TBool CanDrawGlass()const;
1.61 + inline TBool CanPrint()const;
1.62 + inline void SetCanDrawGlass();
1.63 + inline void SetCanPrint();
1.64 + private:
1.65 + enum {
1.66 + ECanDrawGlass =0x01,
1.67 + ECanPrint =0x02
1.68 + };
1.69 + private:
1.70 + TUint iCapability;
1.71 + TInt TCapability_Reserved1;
1.72 + };
1.73 +public:
1.74 + // document instantiation functions
1.75 +
1.76 + /** Initialises a new, empty, document with a default setup.
1.77 +
1.78 + This can be the main document or an embedded document. The function is called
1.79 + by the UI framework when it creates a default document file.
1.80 +
1.81 + An implementation of this function must be supplied by the UI application.
1.82 +
1.83 + If initialisation fails, the document must be left in the same state as it
1.84 + was before the function was called. */
1.85 + virtual void NewDocumentL()=0; // builds a new embedded or main document without loading from a store (may create the content from eg code or a template file).
1.86 +
1.87 + /** Creates and fully initialises a new filestore and stores the document into it,
1.88 + replacing any existing file of the same name.
1.89 +
1.90 + The function should put the pointer to the filestore object onto the cleanup
1.91 + stack.
1.92 +
1.93 + An implementation of this function is supplied by the UI framework.
1.94 +
1.95 + @param aFs Handle to a file server session.
1.96 + @param aFileName The full path name of the file to be created.
1.97 + @return A pointer to the newly constructed file store.
1.98 + @see CEikDocument */
1.99 + virtual CFileStore* CreateFileStoreLC(RFs& aFs,const TDesC& aFileName)=0; // creates a file for a document and stores itself to that store (store should be put on cleanup stack).
1.100 +
1.101 + // interaction functions
1.102 + IMPORT_C virtual CPicture* GlassPictureL(); // Does nothing by default, override to return handle to glass picture.
1.103 +
1.104 + /** Starts an editing session on an embedded document.
1.105 +
1.106 + The function should cause the application's UI to be created and the document
1.107 + to be fully restored for editing.
1.108 +
1.109 + An implementation of this function is supplied by the UI framework.
1.110 +
1.111 + @param aContainer This document's observer.
1.112 + @param aReadOnly True, the document should be opened in read-only mode and
1.113 + should not persist any changes made to the content. False, the document can
1.114 + be opened in read/write mode; this is the default.
1.115 + @see CEikDocument */
1.116 + virtual void EditL(MApaEmbeddedDocObserver* aContainer,TBool aReadOnly=EFalse)=0; // Edit the document in the context of the container's environment. If aContainer is null, edit as the main document
1.117 +
1.118 + /** Prints the document without a need for it to be open for editing.
1.119 +
1.120 + Typically, this is called from a shell or a file manager type application
1.121 + that wants to print the document without opening it fully.
1.122 +
1.123 + An empty implementation of this function is supplied by the UI framework.
1.124 +
1.125 + The UI application can provide its own implementation.
1.126 +
1.127 + @param aSourceStore A reference to the store containing the document.
1.128 + @see CEikDocument */
1.129 + virtual void PrintL(const CStreamStore& aSourceStore) = 0; // default print parameters, assume print context supplied by environment
1.130 + //
1.131 + // persistence functions
1.132 +
1.133 + /** Stores the document to the current file, commits the changes, and marks the
1.134 + document status as unchanged.
1.135 +
1.136 + Typically, the function is called by the application when it implements a
1.137 + "Save" type menu option in its User Interface.
1.138 +
1.139 + An implementation of this function is supplied by the UI framework. This is
1.140 + adequate for direct file store applications. Applications using a permanent
1.141 + file store model, need to provide their own implementation.
1.142 +
1.143 + If the function leaves, an implementation should ensure that any changes made
1.144 + to the file are rolled back, leaving the file in the state it was in before
1.145 + the function was called.
1.146 +
1.147 + @see CEikDocument */
1.148 + virtual void SaveL() = 0; // save the doc to the file in the custody of iAppProcess. This fn should be called by any "Save" menu option. store->Commit() should be called within it.
1.149 + /** Stores the document's content and state to the specified store, recording the
1.150 + identity of any headstreams created in the specified stream dictionary.
1.151 +
1.152 + The store must be fully constructed before this function is called.
1.153 +
1.154 + An empty implementation of this function is supplied by the UI framework.
1.155 + UI applications that need to persist any data must provide their own implementation.
1.156 +
1.157 + If the function leaves, an implementation should ensure that the store and
1.158 + the stream dictionary are returned to the state they were in before the function
1.159 + was called.
1.160 +
1.161 + @param aStore The store into which document data is to be stored.
1.162 + @param aStreamDic The stream dictionary into which stream IDs and associated
1.163 + UIDs are to be recorded.
1.164 + @see CEikDocument */
1.165 + virtual void StoreL(CStreamStore& aStore,CStreamDictionary& aStreamDic) const = 0; // store to aStore, lodging the headstream in aStreamDic
1.166 +
1.167 + /** Restores the document's content and state from data persisted in the specified
1.168 + store.
1.169 +
1.170 + An empty implementation of this function is supplied by the UI framework.
1.171 + UI applications that need to restore data must provide their own implementation.
1.172 +
1.173 + If the function leaves, an implementation should ensure that the store and
1.174 + the stream dictionary are returned to the state they were in before the function
1.175 + was called.
1.176 +
1.177 + @param aStore The store from which document data is to be restored.
1.178 + @param aStreamDic The stream dictionary containing stream IDs and associated
1.179 + UIDs.
1.180 + @see CEikDocument */
1.181 + virtual void RestoreL(const CStreamStore& aStore, const CStreamDictionary& aStreamDic) = 0; // restore from aStore using aStreamDic
1.182 +
1.183 + /** Restores the document to the extent that it does not need the store
1.184 + further.
1.185 +
1.186 + A document only keeps a pointer to a store if it implements deferred
1.187 + loading. This also tells the document that any store pointer that it
1.188 + might have is just about to become invalid.
1.189 +
1.190 + An empty implementation of this function is supplied by the UI framework.
1.191 + UI applications that support deferred loading or embedding should provide an
1.192 + implementation.
1.193 +
1.194 + If a document supports embedding, then it should
1.195 + propagate the DetachFromStoreL() call on to all embedded objects that
1.196 + it contains.
1.197 +
1.198 + If the function leaves, the operation should be aborted
1.199 + because the document has not successfully detached from the store.
1.200 + Continuing with the operation may leave the document in an unsafe
1.201 + state or cause user data to be lost.
1.202 +
1.203 + @param aDegree The degree of detachment required. */
1.204 + virtual void DetachFromStoreL(CPicture::TDetach /*aDegree*/=CPicture::EDetachFull) {} // supply an implementation if you support deferred loading or embedding
1.205 +
1.206 + IMPORT_C virtual void ExternalizeL(RWriteStream& aStream) const;
1.207 + //
1.208 + // enquiry functions
1.209 +
1.210 + /** Tests whether the document is empty.
1.211 +
1.212 + The UI framework provides a default implementation which always returns a
1.213 + true value.
1.214 +
1.215 + The UI application can provide its own implementation. Typically, any application
1.216 + that has editable content should supply an implementation that acts according
1.217 + to the state of that content. Applications without associated document data
1.218 + need not supply an implementation.
1.219 +
1.220 + @return True if the document is empty, false otherwise.
1.221 + @see CEikDocument */
1.222 + virtual TBool IsEmpty() const = 0; // return ETrue if the document is empty
1.223 + IMPORT_C virtual void ValidatePasswordL() const; // return EFalse if there *is* a password *and* the user doesn't get it right, ETrue otherwise (ie they get it right or there isn't one). Returns ETrue by default
1.224 +
1.225 + IMPORT_C virtual TCapability Capability() const; // returns "cant do anything" by default
1.226 + inline CApaApplication* Application() const;
1.227 + inline CApaProcess* Process() const;
1.228 +
1.229 + /** Tests whether the document has changed since it was last persisted.
1.230 +
1.231 + An implementation of this function is supplied by the UI framework and need
1.232 + not be changed by the UI application.
1.233 +
1.234 + @return True, if the document has changed since the last time that it was
1.235 + persisted, false, otherwise.
1.236 + @see CEikDocument */
1.237 + virtual TBool HasChanged()const = 0;
1.238 + //
1.239 + IMPORT_C virtual ~CApaDocument();
1.240 +protected:
1.241 + IMPORT_C CApaDocument();
1.242 + IMPORT_C CApaDocument(CApaApplication& aApp,CApaProcess& aProcess);
1.243 +private:
1.244 + IMPORT_C virtual void OpenFileL(CFileStore*& aFileStore, RFile& aFile); // was previously Reserved_1
1.245 + // Reserved virtual functions...
1.246 + IMPORT_C virtual void Reserved_2();
1.247 +protected:
1.248 + MApaEmbeddedDocObserver* iContainer; // null unless this is an embedded object currently being edited
1.249 +private:
1.250 + CApaApplication* iApplication; // the doc's associated application
1.251 + CApaProcess* iApaProcess;
1.252 + TInt iSpare;
1.253 + };
1.254 +
1.255 +
1.256 +/** An interface class for handling the completion of the editing of an embedded
1.257 +document.
1.258 +
1.259 +@publishedAll
1.260 +@released
1.261 +@see CApaDocument::EditL() */
1.262 +class MApaEmbeddedDocObserver
1.263 + {
1.264 +public:
1.265 + /** Defines the state of the embedded document on completion of editing. */
1.266 + enum TExitMode {
1.267 + /** Changes to the embedded document must be saved. */
1.268 + EKeepChanges,
1.269 + /** Reverts back to the saved version of the embedded document, i.e. reloads the
1.270 + whole document. */
1.271 + ERevertToSaved,
1.272 + /** No changes have been made to the embedded document. */
1.273 + ENoChanges,
1.274 + /** The embedded document is empty. */
1.275 + EEmpty
1.276 + };
1.277 +public:
1.278 + /** Implements the required behaviour when the editing of an embedded document completes.
1.279 +
1.280 + @param aMode Indicates the state of the document. */
1.281 + virtual void NotifyExit(TExitMode aMode)=0; // called on completion of editing of an embedded document
1.282 +protected:
1.283 + IMPORT_C MApaEmbeddedDocObserver();
1.284 +private:
1.285 + IMPORT_C virtual void MApaEmbeddedDocObserver_Reserved1();
1.286 + IMPORT_C virtual void MApaEmbeddedDocObserver_Reserved2();
1.287 +private:
1.288 + TInt iMApaEmbeddedDocObserver_Reserved1;
1.289 + };
1.290 +
1.291 +
1.292 +// inlines //
1.293 +
1.294 +/** Returns a pointer to the application that created the document.
1.295 +@return A pointer to the document's associated application. */
1.296 +inline CApaApplication* CApaDocument::Application() const
1.297 + { return iApplication; }
1.298 +
1.299 +/** Returns a pointer to the application process associated with this document.
1.300 +@return A pointer to the application process associated with this document. */
1.301 +inline CApaProcess* CApaDocument::Process()const
1.302 + { return iApaProcess; }
1.303 +
1.304 +/** Tests whether the document supports being embedded as a glass door.
1.305 +@return True if embedding as a glass door is supported; false otherwise. */
1.306 +inline TBool CApaDocument::TCapability::CanDrawGlass()const
1.307 + { return iCapability&ECanDrawGlass; }
1.308 +
1.309 +/** Tests whether the document supports being printed without using the full application UI.
1.310 +@return True, if printing is supported; false, otherwise. */
1.311 +inline TBool CApaDocument::TCapability::CanPrint()const
1.312 + { return iCapability&ECanPrint; }
1.313 +
1.314 +/** Sets the document as being capable of being embedded as a glass door. */
1.315 +inline void CApaDocument::TCapability::SetCanDrawGlass()
1.316 + { iCapability = iCapability|ECanDrawGlass; }
1.317 +
1.318 +/** Sets the document as being capable of being printed without using the full application UI. */
1.319 +inline void CApaDocument::TCapability::SetCanPrint()
1.320 + { iCapability = iCapability|ECanPrint; }
1.321 +
1.322 +#endif // __APADOC_H__