Class CEikDocument

CEikDocument

Support

Supported from 6.0

Description

The base for all Uikon applications’ documents. A class derived from CEikDocument is used in each Uikon application. In file-based applications, the document provides an intermediate layer between the user interface, the model and the file the model will be stored in. Non-file-based applications will only use a document to create the application UI.

Each Uikon application should use a class derived from CEikDocument to represent its document. The derived class must implement at least CreateAppUiL().

Derivation

CApaDocument Defines basic behaviour for documents CBase Base class for all classes to be instantiated on the heap CEikDocument The base for all Uikon applications' documents

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

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

Inherited from CBase:
operator new()

See also:

• CEikApplication
• CEikAppUi

Description

Uikon document objects are created by CEikApplication::CreateDocumentL().

protected: CEikDocument(CEikApplication& aApp);

Description

Default constructor

Allocates a new CEikDocument and initialises its references to its associated application and managing process.

Parameters

CEikApplication& aApp The application instance with which the new document is associated.

~CEikDocument();

Description

Destructor.

Releases any resources and storage acquired during this object’s construction phases.

Description

The document object in a Uikon application framework is responsible for creating the application’s UI.

virtual CEikAppUi* CreateAppUiL() = 0;

Description

Allocates the application UI.

Called by the application framework to create an instance of an application UI for this document and its associated application. The object returned is owned by the Uikon framework, and should not be deleted before the application terminates.

Return value

CEikAppUi* A freshly-allocated application UI. This should be constructed via New(ELeave), but not initialised.

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

Description

Called by the Uikon framework to open a file. If aDoOpen is ETrue, this function attempts to open a file for exclusive writes (EFileShareExclusive|EFileWrite); failing that, the function attempts to open the file for exclusive reads (EFileRead|EFileShareReadersOnly). If the file cannot be opened at all when aDoOpen is ETrue, this function Leave()s.

If aDoOpen is EFalse, this function attempts to create and open a new file for exclusive writes.

Parameters

TBool aDoOpen Open an existing file if ETrue; otherwise create a new file. const TDesC& aFilename The file to open or create. RFs& aFs File server session to use.

Return value

CFileStore* File store object referring to the newly-opened file.

void NewDocumentL();

Description

Called by the framework to initialise a new default document file. This occurs when the application is started without a file, and there is no existing default document file in the file system.

This function should set the document model and the default document to some default settings (for example, a default template file).

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

Description

Creates a new file store for a file. Creates a new file or overwrites an existing one as necessary. A StoreL() is performed immediately.

Parameters

RFs& aFs File server session to use. const TDesC& aFileName Full path to the file.

Return value

CFileStore* The newly created file store.

TBool HasChanged() const;

Description

Gets this document’s document-changed flag.

Return value

TBool ETrue if the document-changed flag is ETrue, otherwise EFalse.

void SetChanged(TBool aHasChanged);

Description

Sets this document’s document-changed flag.

Parameters

TBool aHasChanged New state for the document-changed flag, this can be either ETrue or EFalse.

TBool IsEmpty() const;

Description

Tests whether this document contains any content. As the Uikon implementation of this function simply returns ETrue, any applications which use documents to represent and store data should override it.

This function is declared as virtual in CApaDocument.

Return value

TBool ETrue (in CEikDocument).

const TApaAppCaption& AppCaption() const;

Description

Gets the associated application’s caption.

Return value

TApaAppCaption& Caption of the application with which this document is associated. See CEikApplication::AppCaption().

virtual void UpdateTaskNameL(CApaWindowGroupName* aWgName);

Description

Updates the task name.

Parameters

CApaWindowGroupName* aWgName New task name.

TUint AppFileMode() const;

Description

Gets the file mode.

Return value

TUint The file mode field of this CEikDocument: a bitwise OR of values defined in TFileMode.

void SetAppFileMode(TUint aMode);

Description

Sets the file mode

Parameters

TUint aMode New value for the file mode field of this CEikDocument: a bitwise OR of values defined in TFileMode.

void SaveL();

Description

Saves this document to its current direct file store. Marks the document as not having changed. This function is called by the framework when an application exits: the current state of the application’s document is saved to the currently opened file, and the application can then exit cleanly.

This function is declared virtual in CApaDocument, and therefore may be overridden to provide custom behaviour.

See also:

• SetChanged()

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

Description

Stores the document’s content and state, recording the identity of any headstreams created. The stream store to which data is saved, aStore, must be fully constructed before StoreL() is called.

The Uikon implementation of this function is empty. Applications that wish to persist any data must provide their own version.

Parameters

CStreamStore& aStore Stream store to which data is saved. CStreamDictionary& aStreamDic Stream dictionary in which to record headstreams.

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

Description

Restores this document from a stream store.

Sets the document’s state and content. Any existing data in the document will belost.

The Uikon implementation of this function is empty. Applications that wish to load any persisted data must provide their own version.

Parameters

const CStreamStore& aStore Stream store from which to read the new state and content. const CStreamDictionary& aStreamDic Stream dictionary in which to look up head streams.

Leave codes

If this function leaves the document should be rolled back to the state in which it was before the function was called.

void ExternalizeL(RWriteStream& aStream) const;

Description

Externalise.

The Uikon implementation of this function is blank, and it is never called by the framework.

Parameters

RWriteStream& aStream The write stream to which information is written.

void PrintL(const CStreamStore& aSourceStore);

Description

Prints a document without opening it for editing first. It would typically be called from a shell or file manager application that wanted to print the document without opening it fully.

This function is empty. Applications that want to support printing should override this with a function that uses default print parameters.

Parameters

const CStreamStore& aSourceStore Observer for the editing session.

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

Description

Starts an editing session on an embedded document. This causes the application’s UI to be created, and the document is fully restored for editing or viewing.

Parameters

MApaEmbeddedDocObserver* aObserver Pointer to an observer that should be informed when editing has been completed (see MApaEmbeddedDocObserver). TBool aReadOnly=EFalse If ETrue, the document is opened as read only, and changes made to its content do not persist.

void PrepareToEditL(MApaEmbeddedDocObserver* aObserver, TBool aReadOnly);

Description

Prepares an embedded document for editing.

Parameters

MApaEmbeddedDocObserver* aObserver The observer of this embedded document TBool aReadOnly If ETrue, the document is opened as read-only and changes made to its content do not persist.

void PrepareToEditL();

Description

Prepares this document for editing by the user

An alias for PrepareToEditL(NULL, NULL);

CStreamStore* EditStore() const;

Description

Gets the edit store.

Return value

CStreamStore* Pointer to the stream store set as the edit store.

void SetEditStoreL(CStreamStore* aStore);

Description

Sets the edit store to aStore.

Parameters

CStreamStore* aStore The edit store to use.

CEikAppUi* iAppUi

Description

Pointer to the application UI through which the user manipulates this document’s data.

CStreamStore* iEditStore

Description

Pointer to the stream store set as the edit store.