Class CEikDocument

class CEikDocument : public CApaDocument, public MSaveObserver;

Description

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.

Derivation

• MSaveObserver - No description.

• CBase - Base class for all classes to be instantiated on the heap

• CApaDocument - Defines basic behaviour for documents

• CEikDocument - The base class for all GUI applications' documents

Members

Defined in CEikDocument:
AppCaption(), AppFileMode(), CEikDocument(), CEikDocument(), CreateAppUiL(), CreateFileStoreLC(), EditL(), EditStore(), ExternalizeL(), HasChanged(), IsEmpty(), NewDocumentL(), OpenFileL(), OpenFileL(), PrepareToEditL(), PrepareToEditL(), PrintL(), Reserved_2(), RestoreL(), SaveL(), SaveL(), SetAppFileMode(), SetChanged(), SetEditStoreL(), StoreL(), UpdateTaskNameL(), ValidatePasswordL(), iAppUi, iEditStore, ~CEikDocument()

Inherited from CApaDocument:
Application(), Capability(), DetachFromStoreL(), GlassPictureL(), Process(), TCapability, iContainer

Inherited from CBase:
Delete(), Extension_(), operator new()

See also

• Class summary
• ControlFramework: A UI application with a toolbar
• Class Summary

See also:

• CEikApplication::CreateDocumentL()
• CEikAppUi

IMPORT_C ~CEikDocument();

Description

Destructor.

protected: IMPORT_C CEikDocument();

Description

Constructor for CEikDocument

protected: IMPORT_C CEikDocument(CEikApplication &aApp);

Description

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.

virtual CEikAppUi *CreateAppUiL()=0;

Description

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.

Return value

CEikAppUi * A partially-constructed app UI object.

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

Description

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.

Return value

CFileStore * The file store that stores the main document.

IMPORT_C void PrepareToEditL(MApaEmbeddedDocObserver *aObserver, TBool aReadOnly);

Description

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.

IMPORT_C void PrepareToEditL();

Description

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.

IMPORT_C void SetAppFileMode(TUint aMode);

Description

Sets the document's file sharing and access mode.

Parameters

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

See also:

• TFileMode

IMPORT_C TUint AppFileMode() const;

Description

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.

Return value

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

See also:

• TFileMode

virtual IMPORT_C void UpdateTaskNameL(CApaWindowGroupName *aWgName);

Description

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.

IMPORT_C const TApaAppCaption &AppCaption() const;

Description

Gets the caption of the application that created the document.

The application's caption is usually specified in its localisable resource file.

Return value

const TApaAppCaption & The caption of the application that created the document.

See also:

• CEikApplication::AppCaption()

IMPORT_C void SetChanged(TBool aHasChanged);

Description

Sets this document's 'Has changed' flag.

Parameters

TBool aHasChanged New value for the 'Has changed' flag.

IMPORT_C void SetEditStoreL(CStreamStore *aStore);

Description

Sets the document's stream store.

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

Parameters

CStreamStore *aStore The stream store.

inline CStreamStore *EditStore() const;

Description

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

Return value

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

virtual IMPORT_C void SaveL(MSaveObserver::TSaveType aSaveType);

Description

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.

virtual IMPORT_C void NewDocumentL();

Description

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.

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

Description

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.

Return value

CFileStore * The newly created file store.

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

Description

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

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 If ETrue, the embedded document is opened as read-only.

Leave codes

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

virtual IMPORT_C void PrintL(const CStreamStore &aSourceStore);

Description

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

virtual IMPORT_C void SaveL();

Description

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

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

Description

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

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.

See also:

• CEikAppUi::SaveL()

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

Description

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.

virtual IMPORT_C void ExternalizeL(RWriteStream &aStream) const;

Description

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.

virtual IMPORT_C TBool IsEmpty() const;

Description

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.

Return value

TBool Always ETrue (in CEikDocument).

virtual IMPORT_C TBool HasChanged() const;

Description

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.

Return value

TBool The value of the document's 'Has changed' flag.

See also:

• CEikAppUi::SaveAnyChangesL()

virtual IMPORT_C void ValidatePasswordL() const;

Description

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.

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

Description

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.

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.

private: virtual IMPORT_C void Reserved_2();

Description

protected: CEikAppUi * iAppUi;

Description

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

protected: CStreamStore * iEditStore;

Description

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