CApaDocument Class Reference

#include <mw/apadoc.h>

class CApaDocument : public CBase

Inherits from

CApaDocument
- CBase

Nested Classes and Structures

CApaDocument::TCapability

Protected Attributes
MApaEmbeddedDocObserver *	iContainer

Public Member Functions
virtual	~CApaDocument()
CApaApplication *	Application()
virtual IMPORT_C TCapability	Capability()
pure virtual CFileStore *	CreateFileStoreLC(RFs &, const TDesC &)
virtual void	DetachFromStoreL(CPicture::TDetach)
pure virtual void	EditL(MApaEmbeddedDocObserver *, TBool)
virtual IMPORT_C void	ExternalizeL(RWriteStream &)
virtual IMPORT_C CPicture *	GlassPictureL()
pure virtual TBool	HasChanged()
pure virtual TBool	IsEmpty()
pure virtual void	NewDocumentL()
pure virtual void	PrintL(const CStreamStore &)
CApaProcess *	Process()
pure virtual void	RestoreL(const CStreamStore &, const CStreamDictionary &)
pure virtual void	SaveL()
pure virtual void	StoreL(CStreamStore &, CStreamDictionary &)
virtual IMPORT_C void	ValidatePasswordL()

Protected Member Functions
	CApaDocument()
	CApaDocument(CApaApplication &, CApaProcess &)

Inherited Functions
	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()

Detailed Description

Defines basic behaviour for documents.

This is the base class for all documents. A document contains the data associated with the application's content.

The class is derived from by the UI framework and is further derived from by the UI application.

See also: CEikDocument

Member Attribute Documentation

iContainer

MApaEmbeddedDocObserver *

iContainer

[protected]

Constructor & Destructor Documentation

CApaDocument ( )

IMPORT_C

CApaDocument

(

)

[protected]

Constructor for CApaDocument

CApaDocument ( CApaApplication &, CApaProcess & )

IMPORT_C	CApaDocument	(	CApaApplication &	aApp,
			CApaProcess &	aProcess
		)	[protected]

Constructs the document object with the specified application and process.

Derived classes must define and implement a constructor through which both the associated application and process can be specified. A typical implementation calls this constructor through a constructor initialization list.

See also: CEikDocument

Parameters
aApp	The application.
aProcess	The process.

~CApaDocument ( )

IMPORT_C

~CApaDocument

(

)

[virtual]

Destructor.

The implementation is empty.

Member Function Documentation

Application ( )

CApaApplication *

Application

(

)

const [inline]

Returns a pointer to the application that created the document.

Return Value: A pointer to the document's associated application.

Capability ( )

IMPORT_C TCapability

Capability

(

)

const [virtual]

Gets the document's capabilities.

Capabilities are encapsulated by an instance of a TCapability class, a public class defined inside this class.

The default implementation returns a default TCapability object, indicating that the document does not support any of the defined capabilities.

If a document does support one or more of the capabilities, it should override this function to return a suitably initialised object.

Return Value: The document's capabilities

CreateFileStoreLC ( RFs &, const TDesC & )

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

Creates and fully initialises a new filestore and stores the document into it, replacing any existing file of the same name.

The function should put the pointer to the filestore object onto the cleanup stack.

An implementation of this function is supplied by the UI framework.

See also: CEikDocument

Parameters
aFs	Handle to a file server session.
aFileName	The full path name of the file to be created.

Return Value: A pointer to the newly constructed file store.

DetachFromStoreL ( CPicture::TDetach )

void

DetachFromStoreL

(

CPicture::TDetach

= CPicture::EDetachFull

)

[inline, virtual]

Restores the document to the extent that it does not need the store further.

A document only keeps a pointer to a store if it implements deferred loading. This also tells the document that any store pointer that it might have is just about to become invalid.

An empty implementation of this function is supplied by the UI framework. UI applications that support deferred loading or embedding should provide an implementation.

If a document supports embedding, then it should propagate the DetachFromStoreL() call on to all embedded objects that it contains.

If the function leaves, the operation should be aborted because the document has not successfully detached from the store. Continuing with the operation may leave the document in an unsafe state or cause user data to be lost.

EditL ( MApaEmbeddedDocObserver *, TBool )

void	EditL	(	MApaEmbeddedDocObserver *	aContainer,
			TBool	aReadOnly = EFalse
		)	[pure virtual]

Starts an editing session on an embedded document.

The function should cause the application's UI to be created and the document to be fully restored for editing.

An implementation of this function is supplied by the UI framework.

See also: CEikDocument

Parameters
aContainer	This document's observer.
aReadOnly	True, the document should be opened in read-only mode and should not persist any changes made to the content. False, the document can be opened in read/write mode; this is the default.

ExternalizeL ( RWriteStream & )

IMPORT_C void

ExternalizeL

(

RWriteStream &

aStream

)

const [virtual]

GlassPictureL ( )

IMPORT_C CPicture *

GlassPictureL

(

)

[virtual]

Gets an object that can draw a representation of the document's content.

If the document supports being embedded as a glass door, then the UI application must provide an implementation for this function.

The default implementation raises an APPARC 8 panic.

Return Value: A pointer to a glass door.

HasChanged ( )

TBool

HasChanged

(

)

const [pure virtual]

Tests whether the document has changed since it was last persisted.

An implementation of this function is supplied by the UI framework and need not be changed by the UI application.

See also: CEikDocument

Return Value: True, if the document has changed since the last time that it was persisted, false, otherwise.

IsEmpty ( )

TBool

IsEmpty

(

)

const [pure virtual]

Tests whether the document is empty.

The UI framework provides a default implementation which always returns a true value.

The UI application can provide its own implementation. Typically, any application that has editable content should supply an implementation that acts according to the state of that content. Applications without associated document data need not supply an implementation.

See also: CEikDocument

Return Value: True if the document is empty, false otherwise.

NewDocumentL ( )

void

NewDocumentL

(

)

[pure virtual]

Initialises a new, empty, document with a default setup.

This can be the main document or an embedded document. The function is called by the UI framework when it creates a default document file.

An implementation of this function must be supplied by the UI application.

If initialisation fails, the document must be left in the same state as it was before the function was called.

PrintL ( const CStreamStore & )

void

PrintL

(

const CStreamStore &

aSourceStore

)

[pure virtual]

Prints the document without a need for it to be open for editing.

Typically, this is called from a shell or a file manager type application that wants to print the document without opening it fully.

An empty implementation of this function is supplied by the UI framework.

The UI application can provide its own implementation.

See also: CEikDocument

Parameters
aSourceStore	A reference to the store containing the document.

Process ( )

CApaProcess *

Process

(

)

const [inline]

Returns a pointer to the application process associated with this document.

Return Value: A pointer to the application process associated with this document.

RestoreL ( const CStreamStore &, const CStreamDictionary & )

void	RestoreL	(	const CStreamStore &	aStore,
			const CStreamDictionary &	aStreamDic
		)	[pure virtual]

Restores the document's content and state from data persisted in the specified store.

An empty implementation of this function is supplied by the UI framework. UI applications that need to restore data must provide their own implementation.

If the function leaves, an implementation should ensure that the store and the stream dictionary are returned to the state they were in before the function was called.

See also: CEikDocument

Parameters
aStore	The store from which document data is to be restored.
aStreamDic	The stream dictionary containing stream IDs and associated UIDs.

SaveL ( )

void

SaveL

(

)

[pure virtual]

Stores the document to the current file, commits the changes, and marks the document status as unchanged.

Typically, the function is called by the application when it implements a "Save" type menu option in its User Interface.

An implementation of this function is supplied by the UI framework. This is adequate for direct file store applications. Applications using a permanent file store model, need to provide their own implementation.

If the function leaves, an implementation should ensure that any changes made to the file are rolled back, leaving the file in the state it was in before the function was called.

See also: CEikDocument

StoreL ( CStreamStore &, CStreamDictionary & )

void	StoreL	(	CStreamStore &	aStore,
			CStreamDictionary &	aStreamDic
		)	const [pure virtual]

Stores the document's content and state to the specified store, recording the identity of any headstreams created in the specified stream dictionary.

The store must be fully constructed before this function is called.

An empty implementation of this function is supplied by the UI framework. UI applications that need to persist any data must provide their own implementation.

If the function leaves, an implementation should ensure that the store and the stream dictionary are returned to the state they were in before the function was called.

See also: CEikDocument

Parameters
aStore	The store into which document data is to be stored.
aStreamDic	The stream dictionary into which stream IDs and associated UIDs are to be recorded.

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.