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 CEikDocument::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()constGets the caption of the application that created the document.
• AppFileMode()constGets the document's file sharing and access mode.
• CEikDocument()Constructor for CEikDocument
• CEikDocument(CEikApplication &)Constructs a new document.
• CreateAppUiL()Constructs the application UI.
• CreateFileStoreLC(RFs &,const TDesC &)Creates a file store for a new default document.
• EditL(MApaEmbeddedDocObserver *,TBool)Creates an embedded document's app UI and opens the document for editing or view...
• EditStore()constGets the file store object which is used to edit the document.
• ExternalizeL(RWriteStream &)constExternalises an object to a write stream.
• HasChanged()constGets the document's 'Has changed' flag.
• IsEmpty()constTests whether the document contains any content.
• NewDocumentL()This empty function can be implemented in file-based applications to initialise ...
• OpenFileL(CFileStore *&,RFile &)Restores the document's state from the specified file.
• OpenFileL(TBool,const TDesC &,RFs &)Restores the document's state from the specified file, or creates a new default ...
• PrepareToEditL()Prepares a main (non-embedded) document for editing, by creating its app UI.
• PrepareToEditL(MApaEmbeddedDocObserver *,TBool)Prepares an embedded document for editing by creating its app UI.
• PrintL(const CStreamStore &)Prints a document without opening it first.
• Reserved_2()
• RestoreL(const CStreamStore &,const CStreamDictionary &)Restores the document.
• SaveL()Saves the document's state.
• SetAppFileMode(TUint)Sets the document's file sharing and access mode.
• SetChanged(TBool)Sets this document's 'Has changed' flag.
• SetEditStoreL(CStreamStore *)Sets the document's stream store.
• StoreL(CStreamStore &,CStreamDictionary &)constStores the document.
• UpdateTaskNameL(CApaWindowGroupName *)Updates a window group (or task) name with information about a main (non-embedde...
• ValidatePasswordL()constChecks the document password. The default implementation is empty.
• iAppUiA pointer to the app UI which the document is associated with.
• iEditStoreA pointer to the file store object which is used to edit the document.
• ~CEikDocument()Destructor.

Inherited from CApaDocument:

• Application()constReturns a pointer to the application that created the document.
• CApaDocument(CApaApplication &,CApaProcess &)Constructs the document object with the specified application and process.
• Capability()constGets the document's capabilities.
• GlassPictureL()Gets an object that can draw a representation of the document's content.
• Process()constReturns a pointer to the application process associated with this document.
• TCapability CApaDocument capabilities.
• iContainer

Inherited from CBase:

• Delete(CBase *)Deletes the specified object.
• Extension_(TUint,TAny *&,TAny *)Extension function
• operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TAny *)Initialises the object to binary zeroes.
• operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

See also:

• CEikApplication::CreateDocumentL()
• CEikAppUiHandles application-wide aspects of the application's user interface such as the...

Related Topics

 » Symbian OS v9.4 » Examples » Application Framework example code » ControlFramework: An UI application with a toolbar

• ControlFramework: A UI application with a toolbar

 » Symbian OS v9.4 » Examples » Application Framework example code » EmbApp: An embedded application

• EmbApp: An embedded application » Class summary

 » Symbian OS v9.4 » Examples » Application Framework example code » Minimal: A minimal UI application

• Minimal: A minimal UI application » Class Summary

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.

IMPORT_C virtual 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 TDesC16 &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 CEikDocument::EditL(MApaEmbeddedDocObserver *,TBool).

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.

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.

IMPORT_C virtual 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 TBuf & The caption of the application that created the document.

See also:

• CEikApplication::AppCaption()constGets the caption for this application.

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.

IMPORT_C virtual 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.

IMPORT_C virtual 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.

IMPORT_C virtual 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 TDesC16 &aFileName The path and name of the file to create.

Return value

CFileStore * The newly created file store.

IMPORT_C virtual 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.

IMPORT_C virtual 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

IMPORT_C virtual void SaveL();

Description

Saves the document's state.

It calls CEikDocument::StoreL(CStreamStore &,CStreamDictionary &)const 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().

IMPORT_C virtual 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 CEikDocument::RestoreL(const CStreamStore &,const CStreamDictionary &).

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 CEikDocument::ExternalizeL(RWriteStream &)const). 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()Saves the app UI's associated document, or sets the document as changed, if the ...

IMPORT_C virtual 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 CEikDocument::StoreL(CStreamStore &,CStreamDictionary &)const.

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.

IMPORT_C virtual void ExternalizeL(RWriteStream &aStream) const;

Description

Externalises an object to a write stream.

Implementations of this function are normally called from CEikDocument::StoreL(CStreamStore &,CStreamDictionary &)const.

Parameters

RWriteStream &aStream A write stream inside the stream store passed to CEikDocument::StoreL(CStreamStore &,CStreamDictionary &)const, to which the object's state is written.

IMPORT_C virtual 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).

IMPORT_C virtual TBool HasChanged() const;

Description

Gets the document's 'Has changed' flag.

The flag is set and unset using CEikDocument::SetChanged(TBool). Also, calling CEikDocument::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()Saves any changes made to the app UI's associated document, if the document is m...

IMPORT_C virtual 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.

IMPORT_C virtual 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.

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.

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: IMPORT_C virtual 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.