MCoeFepAwareTextEditor Class Reference

class MCoeFepAwareTextEditor

Specifies a protocol for FEP-aware text editors.

TCoeInputCapabilities::FepAwareTextEditor() returns a pointer to an object of this class. A NULL return value indicates that the interface is not supported by any of the currently focused controls.

Inline editing means composing text directly in the target text editor control rather than in the FEP's edit window first. The target text editor must implement the MCoeFepAwareTextEditor interface in order to support inline text. The inline text may be differentiated from the surrounding text by the use of different formatting. These differences are removed when the inline text transaction is committed (causing the inline text to become a real part of the document). Cancelling the inline text transaction deletes the inline text and restores any previously selected text. A benefit of inline editing is that the user only has to concentrate on one area of the screen rather than two.

An inline editing transaction consists of the following sequence of function calls:

a call to StartFepInlineEditL()

zero, one or more calls to UpdateFepInlineTextL()

a call to either CommitFepInlineEditL() or CancelFepInlineEdit()

Public Member Functions
void	CancelFepInlineEdit()
IMPORT_C void	CommitFepInlineEditL(CCoeEnv &)
TInt	DocumentLengthForFep()
TInt	DocumentMaximumLengthForFep()
IMPORT_C MCoeFepAwareTextEditor_Extension1 *	Extension1()
void	GetCursorSelectionForFep(TCursorSelection &)
void	GetEditorContentForFep(TDes &, TInt, TInt)
void	GetFormatForFep(TCharFormat &, TInt)
void	GetScreenCoordinatesForFepL(TPoint &, TInt &, TInt &, TInt)
void	SetCursorSelectionForFepL(const TCursorSelection &)
void	SetInlineEditingCursorVisibilityL(TBool)
void	StartFepInlineEditL(const TDesC &, TInt, TBool, const MFormCustomDraw *, MFepInlineTextFormatRetriever &, MFepPointerEventHandlerDuringInlineEdit &)
void	UpdateFepInlineTextL(const TDesC &, TInt)

Private Member Functions
void	DoCommitFepInlineEditL()
IMPORT_C MCoeFepAwareTextEditor_Extension1 *	Extension1(TBool &)
IMPORT_C void	MCoeFepAwareTextEditor_Reserved_2()

Member Functions Documentation

CancelFepInlineEdit()

void

CancelFepInlineEdit

(

)

[pure virtual]

Cancels the inline editing transaction.

The edit window should be rolled back to the state it was in before the FEP transaction started, i.e. any inline text in the document which has not yet been committed should be removed. If the inline text has replaced existing text, (e.g. a selection) the replaced text should be reinstated.

CommitFepInlineEditL(CCoeEnv &)

IMPORT_C void

CommitFepInlineEditL

(

CCoeEnv &

aConeEnvironment

)

Parameters

CCoeEnv & aConeEnvironment

DoCommitFepInlineEditL()

void

DoCommitFepInlineEditL

(

)

[private, pure virtual]

Private function called by CommitFepInlineEditL().

Implementations should commit the inline text to the document. This ends the inline editing transaction and causes the inline text to become a part of the document.

DocumentLengthForFep()

TInt

DocumentLengthForFep

(

)

const [pure virtual]

Returns the total number of characters in the text editor.

The total number of characters in the text editor.

DocumentMaximumLengthForFep()

TInt

DocumentMaximumLengthForFep

(

)

const [pure virtual]

Returns the upper limit (if any) on the length of text that the text editor can hold.

The maximum number of characters that the text editor can hold.

Extension1()

IMPORT_C MCoeFepAwareTextEditor_Extension1 *

Extension1

(

)

Extension1(TBool &)

IMPORT_C MCoeFepAwareTextEditor_Extension1 *

Extension1

(

TBool &

aSetToTrue

)

[private, virtual]

Parameters

TBool & aSetToTrue

GetCursorSelectionForFep(TCursorSelection &)

void

GetCursorSelectionForFep

(

TCursorSelection &

aCursorSelection

)

const [pure virtual]

Gets the range of characters in the text editor which are selected.

Parameters

TCursorSelection & aCursorSelection

On return, contains the cursor and anchor positions of the selection.

GetEditorContentForFep(TDes &, TInt, TInt)

void	GetEditorContentForFep	(	TDes &	aEditorContent,
			TInt	aDocumentPosition,
			TInt	aLengthToRetrieve
		)	const [pure virtual]

Copies a portion of the text editor's text content into a descriptor.

Parameters

TDes & aEditorContent	A descriptor; on return contains a copy of a portion of the text.
TInt aDocumentPosition	The document position in the text editor from which to copy.
TInt aLengthToRetrieve	The number of characters to copy.

GetFormatForFep(TCharFormat &, TInt)

void	GetFormatForFep	(	TCharFormat &	aFormat,
			TInt	aDocumentPosition
		)	const [pure virtual]

Gets the character formatting which applies to the document position specified.

This function allows FEPs to find out the ambient formatting so that the FEP can choose a format for the inline text that will clearly differentiate it from the surrounding text.

Parameters

TCharFormat & aFormat	On return, contains the character formatting which applies to the character at aDocumentPosition.
TInt aDocumentPosition	The document position of interest.

GetScreenCoordinatesForFepL(TPoint &, TInt &, TInt &, TInt)

void	GetScreenCoordinatesForFepL	(	TPoint &	aLeftSideOfBaseLine,
			TInt &	aHeight,
			TInt &	aAscent,
			TInt	aDocumentPosition
		)	const [pure virtual]

Gets the x,y screen coordinates for the left hand side of the baseline of the character located at a specified document position.

Also gets the height (ascent + descent) and ascent of the font of the character. This function could be used to position the FEP window as close as possible to the insertion point in the text editor.

Parameters

TPoint & aLeftSideOfBaseLine	On return, contains the x,y coordinates of the left side of the baseline of the character located at aDocumentPosition.
TInt & aHeight	On return, contains the height (ascent + descent) of the font of the character at aDocumentPosition.
TInt & aAscent	On return, contains the ascent of the font of the character at aDocumentPosition.
TInt aDocumentPosition	The document position of interest.

MCoeFepAwareTextEditor_Reserved_2()

IMPORT_C void

MCoeFepAwareTextEditor_Reserved_2

(

)

[private, virtual]

SetCursorSelectionForFepL(const TCursorSelection &)

void

SetCursorSelectionForFepL

(

const TCursorSelection &

aCursorSelection

)

[pure virtual]

Sets the range of characters in the text editor which should be selected.

Parameters

const TCursorSelection & aCursorSelection

Contains the cursor and anchor positions for the selection.

SetInlineEditingCursorVisibilityL(TBool)

void

SetInlineEditingCursorVisibilityL

(

TBool

aCursorVisibility

)

[pure virtual]

Sets the visibility of the text cursor in the text editor.

The cursor visibility is initialised using StartFepInlineEditL(). SetInlineEditingCursorVisibilityL() is provided for FEPs which need to change the visibility of the cursor during the inline editing transaction.

Parameters

TBool aCursorVisibility

ETrue for visible text cursor, EFalse for invisible text cursor.

StartFepInlineEditL(const TDesC &, TInt, TBool, const MFormCustomDraw *, MFepInlineTextFormatRetriever &, MFepPointerEventHandlerDuringInlineEdit &)

void	StartFepInlineEditL	(	const TDesC &	aInitialInlineText,
			TInt	aPositionOfInsertionPointInInlineText,
			TBool	aCursorVisibility,
			const MFormCustomDraw *	aCustomDraw,
			MFepInlineTextFormatRetriever &	aInlineTextFormatRetriever,
			MFepPointerEventHandlerDuringInlineEdit &	aPointerEventHandlerDuringInlineEdit
		)	[pure virtual]

Starts a FEP inline editing transaction.

Inserts a descriptor containing the initial inline text into the text editor. The inline text should normally replace any selected text.

The final three parameters are instances of abstract classes, so that the caller of this function must create and instantiate classes deriving from them. These instances must remain in existence for the entire duration of the inline editing transaction.

Inline editing should not already be taking place when this function is called.

Parameters

const TDesC & aInitialInlineText	The inline text to insert into the text editor.
TInt aPositionOfInsertionPointInInlineText	An insertion position within the inline text. This is an offset from the start of the inline text.
TBool aCursorVisibility	ETrue for visible text cursor, EFalse for invisible text cursor in the text editor.
const MFormCustomDraw * aCustomDraw	Pointer to a custom drawing object. May be used to do advanced formatting of the inline text. This parameter is optional; a NULL pointer may be specified.
MFepInlineTextFormatRetriever & aInlineTextFormatRetriever	Defines a single member function, GetFormatOfFepInlineText() which is used by the text editor to find out the formatting to apply to the inline text. It is also possible to apply different formatting to different parts of the inline text.
MFepPointerEventHandlerDuringInlineEdit & aPointerEventHandlerDuringInlineEdit	Defines a single function, HandlePointerEventInInlineTextL() which is called when a pointer event is received within the inline text. This function might update the cursor position within the inline text and do text selection.

UpdateFepInlineTextL(const TDesC &, TInt)

void	UpdateFepInlineTextL	(	const TDesC &	aNewInlineText,
			TInt	aPositionOfInsertionPointInInlineText
		)	[pure virtual]

Updates the inline text.

Called when a character is added to or deleted from the inline text.

The descriptor aNewInlineText contains the entire new inline text string, not just the new text to be combined with the old inline text.

Parameters

const TDesC & aNewInlineText	Descriptor which holds the entire new inline text string.
TInt aPositionOfInsertionPointInInlineText	The position of the insertion point (i.e. the cursor) within the inline text string aNewInlineText. This is an offset from the start of the string.