CEikDocument Class Reference

class CEikDocument : public CApaDocument

The base class for all GUI applications' documents.

In file-based applications, the document represents the data that relates to a particular instance of the application, and should handle storing and restoring it. In all applications, whether file-based or not, the document is used to create the application UI.

A class derived from CEikDocument must be defined by each GUI application, and minimally it must implement CreateAppUiL(). Note that UIs may implement their own document base class, derived from CEikDocument, which applications may need to derive from instead.

The document is created by the application's CreateDocumentL() function.

CEikApplication::CreateDocumentL()

CEikAppUi

Inherits from

CEikDocument
- CApaDocument
  - CBase

Public Member Functions
	~CEikDocument()
IMPORT_C const TApaAppCaption &	AppCaption()
IMPORT_C TUint	AppFileMode()
CEikAppUi *	CreateAppUiL()
IMPORT_C CFileStore *	CreateFileStoreLC(RFs &, const TDesC &)
IMPORT_C void	EditL(MApaEmbeddedDocObserver *, TBool)
CStreamStore *	EditStore()
IMPORT_C void	ExternalizeL(RWriteStream &)
IMPORT_C TBool	HasChanged()
IMPORT_C TBool	IsEmpty()
IMPORT_C void	NewDocumentL()
IMPORT_C CFileStore *	OpenFileL(TBool, const TDesC &, RFs &)
IMPORT_C void	OpenFileL(CFileStore *&, RFile &)
IMPORT_C void	PrepareToEditL(MApaEmbeddedDocObserver *, TBool)
IMPORT_C void	PrepareToEditL()
IMPORT_C void	PrintL(const CStreamStore &)
IMPORT_C void	RestoreL(const CStreamStore &, const CStreamDictionary &)
IMPORT_C void	SaveL(MSaveObserver::TSaveType)
IMPORT_C void	SaveL()
IMPORT_C void	SetAppFileMode(TUint)
IMPORT_C void	SetChanged(TBool)
IMPORT_C void	SetEditStoreL(CStreamStore *)
void	SetEditStoreWithoutAppUiNotificationL(CStreamStore *)
IMPORT_C void	StoreL(CStreamStore &, CStreamDictionary &)
IMPORT_C void	UpdateTaskNameL(CApaWindowGroupName *)
IMPORT_C void	ValidatePasswordL()

Protected Member Functions
	CEikDocument()
	CEikDocument(CEikApplication &)

Private Member Functions
void	NullAppUi()
IMPORT_C void	Reserved_2()

Inherited Functions
	CApaDocument::Application()const
	CApaDocument::CApaDocument()
	CApaDocument::CApaDocument(CApaApplication &,CApaProcess &)
	CApaDocument::Capability()const
	CApaDocument::DetachFromStoreL(CPicture::TDetach)
	CApaDocument::GlassPictureL()
	CApaDocument::Process()const
	CApaDocument::~CApaDocument()
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Protected Attributes
CEikAppUi *	iAppUi
CStreamStore *	iEditStore

Private Attributes
TUint	iAppFileMode
TBool	iChanged

Inherited Attributes
	CApaDocument::iContainer

Constructor & Destructor Documentation

CEikDocument()

IMPORT_C

CEikDocument

(

)

[protected]

CEikDocument(CEikApplication &)

IMPORT_C

CEikDocument

(

CEikApplication &

aApp

)

[protected]

Parameters

CEikApplication & aApp

~CEikDocument()

IMPORT_C

~CEikDocument

(

)

Member Functions Documentation

AppCaption()

IMPORT_C const TApaAppCaption &

AppCaption

(

)

const

AppFileMode()

IMPORT_C TUint

AppFileMode

(

)

const

CreateAppUiL()

CEikAppUi *

CreateAppUiL

(

)

[pure virtual]

Constructs the application UI.

This function is called by the UI framework during application start-up. It should only carry out first phase construction of the app UI, in other words, using new(ELeave). It should not call the app UI's ConstructL(), because the UI framework is responsible for this. Note also that the UI framework takes ownership of the app UI, so the document does not need to destroy it.

A partially-constructed app UI object.

CreateFileStoreLC(RFs &, const TDesC &)

IMPORT_C CFileStore *	CreateFileStoreLC	(	RFs &	aFs,
			const TDesC &	aFileName
		)	[virtual]

Creates and fully initialises a new filestore and stores the document into it, replacing any existing file of the same name.

The function should put the pointer to the filestore object onto the cleanup stack.

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

A pointer to the newly constructed file store.

CEikDocument

Parameters

RFs & aFs	Handle to a file server session.
const TDesC & aFileName	The full path name of the file to be created.

EditL(MApaEmbeddedDocObserver *, TBool)

IMPORT_C void	EditL	(	MApaEmbeddedDocObserver *	aContainer,
			TBool	aReadOnly = EFalse
		)	[virtual]

Starts an editing session on an embedded document.

The function should cause the application's UI to be created and the document to be fully restored for editing.

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

CEikDocument

Parameters

MApaEmbeddedDocObserver * aContainer	This document's observer.
TBool aReadOnly = EFalse	True, the document should be opened in read-only mode and should not persist any changes made to the content. False, the document can be opened in read/write mode; this is the default.

EditStore()

CStreamStore *

EditStore

(

)

const [inline]

Gets the file store object which is used to edit the document.

A pointer to the file store object which is used to edit the document.

ExternalizeL(RWriteStream &)

IMPORT_C void

ExternalizeL

(

RWriteStream &

aStream

)

const [virtual]

Parameters

RWriteStream & aStream

HasChanged()

IMPORT_C TBool

HasChanged

(

)

const [virtual]

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

An implementation of this function is supplied by the UI framework and need not be changed by the UI application.

True, if the document has changed since the last time that it was persisted, false, otherwise.

CEikDocument

IsEmpty()

IMPORT_C TBool

IsEmpty

(

)

const [virtual]

Tests whether the document is empty.

The UI framework provides a default implementation which always returns a true value.

The UI application can provide its own implementation. Typically, any application that has editable content should supply an implementation that acts according to the state of that content. Applications without associated document data need not supply an implementation.

True if the document is empty, false otherwise.

CEikDocument

NewDocumentL()

IMPORT_C void

NewDocumentL

(

)

[virtual]

Initialises a new, empty, document with a default setup.

This can be the main document or an embedded document. The function is called by the UI framework when it creates a default document file.

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

If initialisation fails, the document must be left in the same state as it was before the function was called.

NullAppUi()

void

NullAppUi

(

)

[private]

OpenFileL(TBool, const TDesC &, RFs &)

IMPORT_C CFileStore *	OpenFileL	(	TBool	aDoOpen,
			const TDesC &	aFilename,
			RFs &	aFs
		)	[virtual]

Parameters

TBool aDoOpen
const TDesC & aFilename
RFs & aFs

OpenFileL(CFileStore *&, RFile &)

IMPORT_C void	OpenFileL	(	CFileStore *&	aFileStore,
			RFile &	aFile
		)	[virtual]

Parameters

CFileStore *& aFileStore
RFile & aFile

PrepareToEditL(MApaEmbeddedDocObserver *, TBool)

IMPORT_C void	PrepareToEditL	(	MApaEmbeddedDocObserver *	aObserver,
			TBool	aReadOnly
		)

Parameters

MApaEmbeddedDocObserver * aObserver
TBool aReadOnly

PrepareToEditL()

IMPORT_C void

PrepareToEditL

(

)

PrintL(const CStreamStore &)

IMPORT_C void

PrintL

(

const CStreamStore &

aSourceStore

)

[virtual]

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

Typically, this is called from a shell or a file manager type application that wants to print the document without opening it fully.

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

The UI application can provide its own implementation.

CEikDocument

Parameters

const CStreamStore & aSourceStore

A reference to the store containing the document.

Reserved_2()

IMPORT_C void

Reserved_2

(

)

[private, virtual]

RestoreL(const CStreamStore &, const CStreamDictionary &)

IMPORT_C void	RestoreL	(	const CStreamStore &	aStore,
			const CStreamDictionary &	aStreamDic
		)	[virtual]

Restores the document's content and state from data persisted in the specified store.

An empty implementation of this function is supplied by the UI framework. UI applications that need to restore data must provide their own implementation.

If the function leaves, an implementation should ensure that the store and the stream dictionary are returned to the state they were in before the function was called.

CEikDocument

Parameters

const CStreamStore & aStore	The store from which document data is to be restored.
const CStreamDictionary & aStreamDic	The stream dictionary containing stream IDs and associated UIDs.

SaveL(MSaveObserver::TSaveType)

IMPORT_C void

SaveL

(

MSaveObserver::TSaveType

aSaveType

)

[virtual]

Parameters

MSaveObserver::TSaveType aSaveType

SaveL()

IMPORT_C void

SaveL

(

)

[virtual]

Stores the document to the current file, commits the changes, and marks the document status as unchanged.

Typically, the function is called by the application when it implements a "Save" type menu option in its User Interface.

An implementation of this function is supplied by the UI framework. This is adequate for direct file store applications. Applications using a permanent file store model, need to provide their own implementation.

If the function leaves, an implementation should ensure that any changes made to the file are rolled back, leaving the file in the state it was in before the function was called.

CEikDocument

SetAppFileMode(TUint)

IMPORT_C void

SetAppFileMode

(

TUint

aMode

)

Parameters

TUint aMode

SetChanged(TBool)

IMPORT_C void

SetChanged

(

TBool

aHasChanged

)

Parameters

TBool aHasChanged

SetEditStoreL(CStreamStore *)

IMPORT_C void

SetEditStoreL

(

CStreamStore *

aStore

)

Parameters

CStreamStore * aStore

SetEditStoreWithoutAppUiNotificationL(CStreamStore *)

void

SetEditStoreWithoutAppUiNotificationL

(

CStreamStore *

aStore

)

Parameters

CStreamStore * aStore

StoreL(CStreamStore &, CStreamDictionary &)

IMPORT_C void	StoreL	(	CStreamStore &	aStore,
			CStreamDictionary &	aStreamDic
		)	const [virtual]

Stores the document's content and state to the specified store, recording the identity of any headstreams created in the specified stream dictionary.

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

An empty implementation of this function is supplied by the UI framework. UI applications that need to persist any data must provide their own implementation.

If the function leaves, an implementation should ensure that the store and the stream dictionary are returned to the state they were in before the function was called.

CEikDocument

Parameters

CStreamStore & aStore	The store into which document data is to be stored.
CStreamDictionary & aStreamDic	The stream dictionary into which stream IDs and associated UIDs are to be recorded.

UpdateTaskNameL(CApaWindowGroupName *)

IMPORT_C void

UpdateTaskNameL

(

CApaWindowGroupName *

aWgName

)

[virtual]

Parameters

CApaWindowGroupName * aWgName

ValidatePasswordL()

IMPORT_C void

ValidatePasswordL

(

)

const [virtual]

Member Data Documentation

TUint iAppFileMode

TUint

iAppFileMode

[private]

CEikAppUi * iAppUi

CEikAppUi *

iAppUi

[protected]

A pointer to the app UI which the document is associated with.

TBool iChanged

TBool

iChanged

[private]

CStreamStore * iEditStore

CStreamStore *

iEditStore

[protected]

A pointer to the file store object which is used to edit the document.