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

Public Member Functions
~CEikDocument()
IMPORT_C const TApaAppCaption &AppCaption()
IMPORT_C TUintAppFileMode()
CEikAppUi *CreateAppUiL()
IMPORT_C CFileStore *CreateFileStoreLC(RFs &, const TDesC &)
IMPORT_C voidEditL(MApaEmbeddedDocObserver *, TBool)
CStreamStore *EditStore()
IMPORT_C voidExternalizeL(RWriteStream &)
IMPORT_C TBoolHasChanged()
IMPORT_C TBoolIsEmpty()
IMPORT_C voidNewDocumentL()
IMPORT_C CFileStore *OpenFileL(TBool, const TDesC &, RFs &)
IMPORT_C voidOpenFileL(CFileStore *&, RFile &)
IMPORT_C voidPrepareToEditL(MApaEmbeddedDocObserver *, TBool)
IMPORT_C voidPrepareToEditL()
IMPORT_C voidPrintL(const CStreamStore &)
IMPORT_C voidRestoreL(const CStreamStore &, const CStreamDictionary &)
IMPORT_C voidSaveL(MSaveObserver::TSaveType)
IMPORT_C voidSaveL()
IMPORT_C voidSetAppFileMode(TUint)
IMPORT_C voidSetChanged(TBool)
IMPORT_C voidSetEditStoreL(CStreamStore *)
voidSetEditStoreWithoutAppUiNotificationL(CStreamStore *)
IMPORT_C voidStoreL(CStreamStore &, CStreamDictionary &)
IMPORT_C voidUpdateTaskNameL(CApaWindowGroupName *)
IMPORT_C voidValidatePasswordL()
Protected Member Functions
CEikDocument()
CEikDocument(CEikApplication &)
Private Member Functions
voidNullAppUi()
IMPORT_C voidReserved_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_CCEikDocument()[protected]

Constructor for CEikDocument

CEikDocument(CEikApplication &)

IMPORT_CCEikDocument(CEikApplication &aApp)[protected]

Constructs a new document.

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

Parameters

CEikApplication & aAppThe 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 TUintAppFileMode()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 & aFsThe file server session to use.
const TDesC & aFileNameThe path and name of the file to create.

EditL(MApaEmbeddedDocObserver *, TBool)

IMPORT_C voidEditL(MApaEmbeddedDocObserver *aObserver,
TBoolaReadOnly = 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 * aObserverOptional 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 = EFalseIf 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 voidExternalizeL(RWriteStream &aStream)const [virtual]

Externalises an object to a write stream.

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

Parameters

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

HasChanged()

IMPORT_C TBoolHasChanged()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 TBoolIsEmpty()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 voidNewDocumentL()[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()

voidNullAppUi()[private]

Deletes reference to associated appUi

OpenFileL(TBool, const TDesC &, RFs &)

IMPORT_C CFileStore *OpenFileL(TBoolaDoOpen,
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 aDoOpenTrue to open an existing file, false to create a new default file.
const TDesC & aFilenameThe path and name of the file to open or create.
RFs & aFsFile server session to use.

OpenFileL(CFileStore *&, RFile &)

IMPORT_C voidOpenFileL(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 *& aFileStoreThis 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 & aFileThe path and name of the file to read from.

PrepareToEditL(MApaEmbeddedDocObserver *, TBool)

IMPORT_C voidPrepareToEditL(MApaEmbeddedDocObserver *aObserver,
TBoolaReadOnly
)

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

This function is called by EditL().

Parameters

MApaEmbeddedDocObserver * aObserverPointer to an embedded document observer. This is notified when editing is complete.
TBool aReadOnlyIf ETrue, the embedded document is opened as read-only.

PrepareToEditL()

IMPORT_C voidPrepareToEditL()

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 voidPrintL(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 voidReserved_2()[private, virtual]

RestoreL(const CStreamStore &, const CStreamDictionary &)

IMPORT_C voidRestoreL(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 & aStoreStream store which holds the document's state.
const CStreamDictionary & aStreamDicStream dictionary which holds the IDs of the streams in the store.

SaveL(MSaveObserver::TSaveType)

IMPORT_C voidSaveL(MSaveObserver::TSaveTypeaSaveType)[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 aSaveTypeNotification code. This indicates to the application why this function was called.

SaveL()

IMPORT_C voidSaveL()[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 voidSetAppFileMode(TUintaMode)

Sets the document's file sharing and access mode.

TFileMode

Parameters

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

SetChanged(TBool)

IMPORT_C voidSetChanged(TBoolaHasChanged)

Sets this document's 'Has changed' flag.

Parameters

TBool aHasChangedNew value for the 'Has changed' flag.

SetEditStoreL(CStreamStore *)

IMPORT_C voidSetEditStoreL(CStreamStore *aStore)

Sets the document's stream store.

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

Parameters

CStreamStore * aStoreThe stream store.

SetEditStoreWithoutAppUiNotificationL(CStreamStore *)

voidSetEditStoreWithoutAppUiNotificationL(CStreamStore *aStore)

Parameters

CStreamStore * aStore

StoreL(CStreamStore &, CStreamDictionary &)

IMPORT_C voidStoreL(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 & aStoreStream store which holds one or more streams, each of which is generally used to store the state of an object (by calling ExternalizeL()).
CStreamDictionary & aStreamDicStream 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 voidUpdateTaskNameL(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 * aWgNameWindow group (or task) name. On return, this is updated to contain information about the main document.

ValidatePasswordL()

IMPORT_C voidValidatePasswordL()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.