Collapse all Symbian^3 Product Developer Library

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]

Constructor for CEikDocument

CEikDocument(CEikApplication &)

IMPORT_C

CEikDocument

(

CEikApplication &

aApp

)

[protected]

Constructs a new document.

This constructor is typically called from a derived UI-specific document class constructor.

Parameters

CEikApplication & aApp

The application instance that is creating the document.

~CEikDocument()

IMPORT_C

~CEikDocument

(

)

Destructor.

Member Functions Documentation

AppCaption()

IMPORT_C const TApaAppCaption &

AppCaption

(

)

const

Gets the caption of the application that created the document.

The application's caption is usually specified in its localisable resource file. CEikApplication::AppCaption().

AppFileMode()

IMPORT_C TUint

AppFileMode

(

)

const

Gets the document's file sharing and access mode.

By default, the access mode is EFileShareExclusive|EFileWrite, except when the file could not be opened for exclusive writing, in which case, its default access mode is EFileRead|EFileShareReadersOnly.

TFileMode

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.

CreateFileStoreLC(RFs &, const TDesC &)

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

Creates a file store for a new default document.

This function is called by the UI framework during application start-up, as part of creating a default document.

Parameters

RFs & aFs	The file server session to use.
const TDesC & aFileName	The path and name of the file to create.

EditL(MApaEmbeddedDocObserver *, TBool)

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

Creates an embedded document's app UI and opens the document for editing or viewing.

leave: KErrNotSupported An observer is specified but the application is not embeddable.

Parameters

MApaEmbeddedDocObserver * aObserver	Optional pointer to an embedded document observer. This is informed when editing is complete. An observer should only be supplied if the document is embedded.
TBool aReadOnly = EFalse	If ETrue, the embedded document is opened as read-only.

EditStore()

CStreamStore *

EditStore

(

)

const [inline]

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

ExternalizeL(RWriteStream &)

IMPORT_C void

ExternalizeL

(

RWriteStream &

aStream

)

const [virtual]

Externalises an object to a write stream.

Implementations of this function are normally called from StoreL().

Parameters

RWriteStream & aStream

A write stream inside the stream store passed to StoreL(), to which the object's state is written.

HasChanged()

IMPORT_C TBool

HasChanged

(

)

const [virtual]

Gets the document's 'Has changed' flag.

The flag is set and unset using SetChanged(). Also, calling SaveL() unsets it.

CEikAppUi::SaveAnyChangesL() tests the value of this flag to identify whether the document needs to be saved.

CEikAppUi::SaveAnyChangesL()

IsEmpty()

IMPORT_C TBool

IsEmpty

(

)

const [virtual]

Tests whether the document contains any content.

This implementation always returns ETrue. Any applications that persist data may optionally override it. It is not called by the UI framework.

NewDocumentL()

IMPORT_C void

NewDocumentL

(

)

[virtual]

This empty function can be implemented in file-based applications to initialise a new default document.

It is called by the UI framework during application start-up when the application is launched without a document being associated with it and when no default document exists.

NullAppUi()

void

NullAppUi

(

)

[private]

Deletes reference to associated appUi

OpenFileL(TBool, const TDesC &, RFs &)

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

Restores the document's state from the specified file, or creates a new default document.

If aDoOpen is true, the function tries to open the file for exclusive writing. If that fails, it tries to open it for reading only. If that fails, it leaves.

If aDoOpen is false, the function creates a new default document whose path and name are specified in aFilename.

This function is called by the UI framework during application start-up.

Parameters

TBool aDoOpen	True to open an existing file, false to create a new default file.
const TDesC & aFilename	The path and name of the file to open or create.
RFs & aFs	File server session to use.

OpenFileL(CFileStore *&, RFile &)

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

Restores the document's state from the specified file.

This virtual function should be overridden if the file is not a "native" Symbian OS file (i.e. is not a CFileStore). In this case, the override should set the aFileStore parameter to NULL.

Overrides of this function must only set aFileStore once all leave-prone operations have succesfully completed.

This function is called by the UI framework during application start-up.

When a file is opened, the current write position is automatically set to the start of the file, therefore there is no need to call RFile::Seek(ESeekStart,0). A call to RFile::Close() should be made when the file handle is no longer required. The file handle should not be passed to another process or application as it will be closed automatically when its associated file-server session is closed.

RFile RFs

Parameters

CFileStore *& aFileStore	This is set by the function to the file store that stores the main document, if the file is a "native" Symbian OS file, otherwise it is set to NULL.
RFile & aFile	The path and name of the file to read from.

PrepareToEditL(MApaEmbeddedDocObserver *, TBool)

IMPORT_C void	PrepareToEditL	(	MApaEmbeddedDocObserver *	aObserver,
			TBool	aReadOnly
		)

Prepares an embedded document for editing by creating its app UI.

This function is called by EditL().

Parameters

MApaEmbeddedDocObserver * aObserver	Pointer to an embedded document observer. This is notified when editing is complete.
TBool aReadOnly	If ETrue, the embedded document is opened as read-only.

PrepareToEditL()

IMPORT_C void

PrepareToEditL

(

)

Prepares a main (non-embedded) document for editing, by creating its app UI.

This function is called by the UI framework during application start-up.

PrintL(const CStreamStore &)

IMPORT_C void

PrintL

(

const CStreamStore &

aSourceStore

)

[virtual]

Prints a document without opening it first.

This function is empty. It might be used to print a document directly from a shell or file manager application rather than from the document's associated application, using default print parameters.

Parameters

const CStreamStore & aSourceStore

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.

This function is empty. Applications that need to persist data must provide their own implementation of this function, and StoreL().

This function is called by the UI framework during application start-up when there is a document associated with the application.

Parameters

const CStreamStore & aStore	Stream store which holds the document's state.
const CStreamDictionary & aStreamDic	Stream dictionary which holds the IDs of the streams in the store.

SaveL(MSaveObserver::TSaveType)

IMPORT_C void

SaveL

(

MSaveObserver::TSaveType

aSaveType

)

[virtual]

Saves the document's state.

This function is called by the UI framework when it needs to close down the application and the parameter provides the reason. For instance, it might be due to RAM running out.

This function simply calls the other overload, and ignores the parameter. Applications should override this function if they need to take account of the parameter.

Parameters

MSaveObserver::TSaveType aSaveType

Notification code. This indicates to the application why this function was called.

SaveL()

IMPORT_C void

SaveL

(

)

[virtual]

Saves the document's state.

It calls StoreL() to save the document and also stores the application's identifier, (a TApaAppIdentifier). The document is left open and its 'Has changed' flag is unset.

This function is called by CEikAppUi::SaveL().

SetAppFileMode(TUint)

IMPORT_C void

SetAppFileMode

(

TUint

aMode

)

Sets the document's file sharing and access mode.

TFileMode

Parameters

TUint aMode

The new file sharing and access mode. This is a bitwise OR of values enumerated in TFileMode.

SetChanged(TBool)

IMPORT_C void

SetChanged

(

TBool

aHasChanged

)

Sets this document's 'Has changed' flag.

Parameters

TBool aHasChanged

New value for the 'Has changed' flag.

SetEditStoreL(CStreamStore *)

IMPORT_C void

SetEditStoreL

(

CStreamStore *

aStore

)

Sets the document's stream store.

This function is called by the UI framework during application start-up.

Parameters

CStreamStore * aStore

The stream store.

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.

This function is empty. Applications that need to persist data must provide their own implementation of this function, and RestoreL().

This function is called by CEikAppUi::SaveL().

CEikAppUi::SaveL()

Parameters

CStreamStore & aStore	Stream store which holds one or more streams, each of which is generally used to store the state of an object (by calling ExternalizeL()).
CStreamDictionary & aStreamDic	Stream dictionary which is used to store the IDs of the streams in the store so they can be identified and restored later.

UpdateTaskNameL(CApaWindowGroupName *)

IMPORT_C void

UpdateTaskNameL

(

CApaWindowGroupName *

aWgName

)

[virtual]

Updates a window group (or task) name with information about a main (non-embedded) document.

The window group name is updated to contain the application's caption and UID, and the filename of the main document.

The filename is also written to the application's ini file, to identify the application's most recently opened file. An ini file is created if one doesn't exist.

This function is called by the UI framework during application start-up.

Parameters

CApaWindowGroupName * aWgName

Window group (or task) name. On return, this is updated to contain information about the main document.

ValidatePasswordL()

IMPORT_C void

ValidatePasswordL

(

)

const [virtual]

Checks the document password. The default implementation is empty.

If a document is intended to be password protected, the UI application should provide an implementation that forces the user to enter the password and validate the input. If the document is protected by a password and the password entered by the user is incorrect, the function should leave with KErrLocked, otherwise it should just return.

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.