1 // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // The main startup of the AppArc server

    15 // 

    16 // apadoc.h

    17 //

    18 

    19 #ifndef __APADOC_H__

    20 #define __APADOC_H__

    21 

    22 #include <e32std.h>

    23 #include <e32base.h>

    24 #include <gdi.h>	// class CPicture::TDetach

    25 

    26 class CApaApplication;

    27 class CApaProcess;

    28 class MApaEmbeddedDocObserver;

    29 class RFile;

    30 class RWriteStream;

    31 class CFileStore;

    32 class CStreamDictionary;

    33 class RFs;

    34 class CPicture;

    35 class CStreamStore;

    36 

    37 /** Defines basic behaviour for documents.

    38 

    39 This is the base class for all documents. A document contains the data associated 

    40 with the application's content.

    41 

    42 The class is derived from by the UI framework and is further derived from 

    43 by the UI application.

    44 

    45 @publishedAll 

    46 @released

    47 @see CEikDocument */

    48 class CApaDocument : public CBase

    49 // base class for documents; allows insertion of glass doors.

    50 	{

    51 public:

    52 	class TCapability

    53 	/** CApaDocument capabilities.*/

    54 		{

    55 	public:

    56 		IMPORT_C TCapability();

    57 		inline TBool CanDrawGlass()const;

    58 		inline TBool CanPrint()const;

    59 		inline void SetCanDrawGlass();

    60 		inline void SetCanPrint();

    61 	private:

    62 		enum {

    63 			ECanDrawGlass	=0x01,

    64 			ECanPrint		=0x02

    65 			};

    66 	private:

    67 		TUint iCapability;

    68 		TInt TCapability_Reserved1;

    69 		};

    70 public:

    71 	// document instantiation functions

    72 

    73 	/** Initialises a new, empty, document with a default setup.

    74 	

    75 	This can be the main document or an embedded document. The function is called 

    76 	by the UI framework when it creates a default document file.

    77 	

    78 	An implementation of this function must be supplied by the UI application.

    79 	

    80 	If initialisation fails, the document must be left in the same state as it 

    81 	was before the function was called. */

    82 	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).

    83 	

    84 	/** Creates and fully initialises a new filestore and stores the document into it, 

    85 	replacing any existing file of the same name.

    86 	

    87 	The function should put the pointer to the filestore object onto the cleanup 

    88 	stack.

    89 	

    90 	An implementation of this function is supplied by the UI framework.

    91 	

    92 	@param aFs Handle to a file server session. 

    93 	@param aFileName The full path name of the file to be created. 

    94 	@return A pointer to the newly constructed file store. 

    95 	@see CEikDocument */

    96 	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).

    97 	

    98 	// interaction functions

    99 	IMPORT_C virtual CPicture* GlassPictureL(); // Does nothing by default, override to return handle to glass picture.

   100 	

   101 	/** Starts an editing session on an embedded document.

   102 	

   103 	The function should cause the application's UI to be created and the document 

   104 	to be fully restored for editing.

   105 	

   106 	An implementation of this function is supplied by the UI framework.

   107 	

   108 	@param aContainer This document's observer.

   109 	@param aReadOnly True, the document should be opened in read-only mode and 

   110 	should not persist any changes made to the content. False, the document can 

   111 	be opened in read/write mode; this is the default. 

   112 	@see CEikDocument */

   113 	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

   114 	

   115 	/** Prints the document without a need for it to be open for editing.

   116 	

   117 	Typically, this is called from a shell or a file manager type application 

   118 	that wants to print the document without opening it fully.

   119 	

   120 	An empty implementation of this function is supplied by the UI framework.

   121 	

   122 	The UI application can provide its own implementation.

   123 	

   124 	@param aSourceStore A reference to the store containing the document. 

   125 	@see CEikDocument */

   126 	virtual void PrintL(const CStreamStore& aSourceStore) = 0; // default print parameters, assume print context supplied by environment

   127 	//

   128 	// persistence functions

   129 

   130 	/** Stores the document to the current file, commits the changes, and marks the 

   131 	document status as unchanged.

   132 	

   133 	Typically, the function is called by the application when it implements a 

   134 	"Save" type menu option in its User Interface.

   135 	

   136 	An implementation of this function is supplied by the UI framework. This is 

   137 	adequate for direct file store applications. Applications using a permanent 

   138 	file store model, need to provide their own implementation.

   139 	

   140 	If the function leaves, an implementation should ensure that any changes made 

   141 	to the file are rolled back, leaving the file in the state it was in before 

   142 	the function was called.

   143 	

   144 	@see CEikDocument */

   145 	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.	

   146 	/** Stores the document's content and state to the specified store, recording the 

   147 	identity of any headstreams created in the specified stream dictionary.

   148 	

   149 	The store must be fully constructed before this function is called.

   150 	

   151 	An empty implementation of this function is supplied by the UI framework. 

   152 	UI applications that need to persist any data must provide their own implementation.

   153 	

   154 	If the function leaves, an implementation should ensure that the store and 

   155 	the stream dictionary are returned to the state they were in before the function 

   156 	was called.

   157 	

   158 	@param aStore The store into which document data is to be stored. 

   159 	@param aStreamDic The stream dictionary into which stream IDs and associated 

   160 	UIDs are to be recorded. 

   161 	@see CEikDocument */

   162 	virtual void StoreL(CStreamStore& aStore,CStreamDictionary& aStreamDic) const = 0; // store to aStore, lodging the headstream in aStreamDic

   163 	

   164 	/** Restores the document's content and state from data persisted in the specified 

   165 	store.

   166 	

   167 	An empty implementation of this function is supplied by the UI framework. 

   168 	UI applications that need to restore data must provide their own implementation.

   169 	

   170 	If the function leaves, an implementation should ensure that the store and 

   171 	the stream dictionary are returned to the state they were in before the function 

   172 	was called.

   173 	

   174 	@param aStore The store from which document data is to be restored. 

   175 	@param aStreamDic The stream dictionary containing stream IDs and associated 

   176 	UIDs. 

   177 	@see CEikDocument */

   178 	virtual void RestoreL(const CStreamStore& aStore, const CStreamDictionary& aStreamDic) = 0; // restore from aStore using aStreamDic

   179 	

   180 	/** Restores the document to the extent that it does not need the store

   181 	further.

   182 

   183 	A document only keeps a pointer to a store if it implements deferred

   184 	loading. This also tells the document that any store pointer that it

   185 	might have is just about to become invalid.

   186 	

   187 	An empty implementation of this function is supplied by the UI framework. 

   188 	UI applications that support deferred loading or embedding should provide an

   189 	implementation.

   190 	

   191 	If a document supports embedding, then it should

   192 	propagate the DetachFromStoreL() call on to all embedded objects that

   193 	it contains.

   194 	

   195 	If the function leaves, the operation should be aborted

   196 	because the document has not successfully detached from the store.

   197 	Continuing with the operation may leave the document in an unsafe

   198 	state or cause user data to be lost.

   199 

   200 	@param aDegree The degree of detachment required. */

   201 	virtual void DetachFromStoreL(CPicture::TDetach /*aDegree*/=CPicture::EDetachFull) {} // supply an implementation if you support deferred loading or embedding

   202 

   203 	IMPORT_C virtual void ExternalizeL(RWriteStream& aStream) const;

   204 	//

   205 	// enquiry functions

   206 	

   207 	/** Tests whether the document is empty.

   208 	

   209 	The UI framework provides a default implementation which always returns a 

   210 	true value.

   211 	

   212 	The UI application can provide its own implementation. Typically, any application 

   213 	that has editable content should supply an implementation that acts according 

   214 	to the state of that content. Applications without associated document data 

   215 	need not supply an implementation.

   216 	

   217 	@return True if the document is empty, false otherwise. 

   218 	@see CEikDocument */

   219 	virtual TBool IsEmpty() const = 0; // return ETrue if the document is empty

   220 	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

   221 	

   222 	IMPORT_C virtual TCapability Capability() const; // returns "cant do anything" by default

   223 	inline CApaApplication* Application() const;

   224 	inline CApaProcess* Process() const;

   225 	

   226 	/** Tests whether the document has changed since it was last persisted.

   227 	

   228 	An implementation of this function is supplied by the UI framework and need 

   229 	not be changed by the UI application.

   230 	

   231 	@return True, if the document has changed since the last time that it was 

   232 	persisted, false, otherwise.

   233 	@see CEikDocument */

   234 	virtual TBool HasChanged()const = 0;

   235 	//

   236 	IMPORT_C virtual ~CApaDocument();

   237 protected:

   238 	IMPORT_C CApaDocument();

   239 	IMPORT_C CApaDocument(CApaApplication& aApp,CApaProcess& aProcess);

   240 private:

   241 	IMPORT_C virtual void OpenFileL(CFileStore*& aFileStore, RFile& aFile); // was previously Reserved_1

   242 	// Reserved virtual functions...

   243 	IMPORT_C virtual void Reserved_2();

   244 protected:

   245 	MApaEmbeddedDocObserver* iContainer; // null unless this is an embedded object currently being edited

   246 private:

   247 	CApaApplication* iApplication; // the doc's associated application

   248 	CApaProcess* iApaProcess;

   249 	TInt iSpare;

   250 	};

   251 

   252 

   253 /** An interface class for handling the completion of the editing of an embedded 

   254 document.

   255 

   256 @publishedAll 

   257 @released

   258 @see CApaDocument::EditL() */

   259 class MApaEmbeddedDocObserver

   260 	{

   261 public:

   262 	/** Defines the state of the embedded document on completion of editing. */

   263 	enum TExitMode {

   264 		/** Changes to the embedded document must be saved. */

   265 		EKeepChanges,

   266 		/** Reverts back to the saved version of the embedded document, i.e. reloads the 

   267 		whole document. */

   268 		ERevertToSaved,

   269 		/** No changes have been made to the embedded document. */

   270 		ENoChanges,

   271 		/** The embedded document is empty. */

   272 		EEmpty

   273 		};

   274 public:

   275 	/** Implements the required behaviour when the editing of an embedded document completes.

   276 	

   277 	@param aMode Indicates the state of the document. */

   278 	virtual void NotifyExit(TExitMode aMode)=0; // called on completion of editing of an embedded document

   279 protected:

   280 	IMPORT_C MApaEmbeddedDocObserver();

   281 private:

   282 	IMPORT_C virtual void MApaEmbeddedDocObserver_Reserved1();

   283 	IMPORT_C virtual void MApaEmbeddedDocObserver_Reserved2();

   284 private:

   285 	TInt iMApaEmbeddedDocObserver_Reserved1;

   286 	};

   287 

   288 

   289 // inlines //

   290 

   291 /** Returns a pointer to the application that created the document.

   292 @return A pointer to the document's associated application. */

   293 inline CApaApplication* CApaDocument::Application() const

   294 	{ return iApplication; }

   295 

   296 /** Returns a pointer to the application process associated with this document.

   297 @return A pointer to the application process associated with this document. */

   298 inline CApaProcess* CApaDocument::Process()const

   299 	{ return iApaProcess; }

   300 

   301 /** Tests whether the document supports being embedded as a glass door.

   302 @return True if embedding as a glass door is supported; false otherwise. */

   303 inline TBool CApaDocument::TCapability::CanDrawGlass()const

   304 	{ return iCapability&ECanDrawGlass; }

   305 

   306 /** Tests whether the document supports being printed without using the full application UI.

   307 @return True, if printing is supported; false, otherwise. */

   308 inline TBool CApaDocument::TCapability::CanPrint()const

   309 	{ return iCapability&ECanPrint; }

   310 

   311 /** Sets the document as being capable of being embedded as a glass door. */

   312 inline void CApaDocument::TCapability::SetCanDrawGlass()

   313 	{ iCapability = iCapability|ECanDrawGlass; }

   314 

   315 /** Sets the document as being capable of being printed without using the full application UI. */

   316 inline void CApaDocument::TCapability::SetCanPrint()

   317 	{ iCapability = iCapability|ECanPrint; }

   318 	

   319 #endif	// __APADOC_H__