Class CTextView

class CTextView : public CBase;

Description

Lays out formatted text for display.

The class provides functions to:

convert between document positions and x,y coordinates

set the dimensions of the rectangle in which text can be viewed (the view rectangle)

set margin widths

do horizontal and vertical scrolling

do text selection

set the cursor position and appearance

After a change has been made to the text layout, a reformat and redraw should normally take place. CTextView provides functions which are optimised to reformat the minimum amount necessary. For example, when a global formatting parameter is changed (e.g. the wrap width), the whole document's layout needs to be recalculated, so HandleGlobalChangeL() should be called. If the change involves the insertion or deletion of a single character, only a single line may be affected; for this, HandleCharEditL() is appropriate. Most CTextView reformatting functions do scrolling (using block transfer), if necessary, and a redraw.

For maximum responsiveness, CTextView uses an active object to carry out reformatting as a background task, so that the application can continue to receive user input. Many CTextView functions force background formatting to complete before they take effect.

When scrolling vertically, positive numbers of pixels, lines, paragraphs, pages, etc., mean that the text moves down, and vice versa. When scrolling horizontally, positive numbers of pixels mean that the text moves left and vice versa.

A text view can display up to two cursors and up to three margins. The cursors are the text cursor and the line cursor. The purpose of the line cursor is to make it easier to see which line the text cursor (or the selection extension point) is on. The three margins are the label margin (for paragraph labels), the line cursor margin (for the line cursor) and the left text margin (the gap between the edge of the page and the text). All are optional, but if present, they appear in that order, starting at the left edge of the view rectangle.

An object of class CTextLayout is used by the text view to calculate changes to the layout. This object must be specified when constructing the text view. It is also used to set layout attributes, including the wrap width, the height of the visible portion of the document (the "band"), whether formatting is set to the band or to the whole document and the text object which is the source of the text and formatting information.

The x-y pixel coordinates used by CTextView are called window coordinates. Window coordinates have their origin at the top left corner of the view window (unlike class CTextLayout whose coordinates have their origin at the top left corner of the area within the view rectangle in which text can appear). As in most bitmap graphics systems, x coordinates increase rightwards and y coordinates increase downwards.

Derivation

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

• CTextView - Lays out formatted text for display

Members

Defined in CTextView:
AlterViewRect(), AlteredViewRect(), CalculateHorizontalExtremesL(), CancelSelectionL(), ClearSelectionL(), DisableFlickerFreeRedraw(), DocPosToXyPosL(), DrawL(), DrawL(), EFBackgroundFormattingPriority, EFCharacterAfter, EFCharacterBefore, EFCheckForHorizontalScroll, EFFirstCharOnLine, EFLastCharOnLine, EFNoHorizontalScroll, EFViewDiscardAllFormat, EFViewDiscardAllNoRedraw, EFViewDontDiscardFormat, EFViewDontDiscardFullRedraw, EnableFlickerFreeRedraw(), EnablePictureFrameL(), FindDocPosL(), FindXyPosL(), FinishBackgroundFormattingL(), FlickerFreeRedraw(), FormatTextL(), GetBackwardDeletePositionL(), GetCursorPos(), GetForwardDeletePositionL(), GetOrigin(), GetPictureRectangleL(), GetPictureRectangleL(), HandleAdditionalCharactersAtEndL(), HandleCharEditL(), HandleGlobalChangeL(), HandleGlobalChangeNoRedrawL(), HandleInsertDeleteL(), HandleRangeFormatChangeL(), HorizontalScrollJump(), IsPictureFrameSelected(), Layout(), LeftTextMargin(), MObserver, MakeVisible(), MarginWidths(), MatchCursorHeightL(), MatchCursorHeightToAdjacentChar(), MoveCursorL(), NewL(), ParagraphRectL(), ScrollDisplayL(), ScrollDisplayLinesL(), ScrollDisplayParagraphsL(), ScrollDisplayPixelsL(), Selection(), SelectionVisible(), SetBackgroundColor(), SetCursorExtensions(), SetCursorFlash(), SetCursorPlacement(), SetCursorVisibilityL(), SetCursorWeight(), SetCursorWidthTypeL(), SetCursorXorColor(), SetDisplayContextL(), SetDocPosL(), SetDocPosL(), SetDocPosL(), SetHorizontalScrollJump(), SetLatentXPosition(), SetLayout(), SetLeftTextMargin(), SetLineCursorBitmap(), SetMarginWidths(), SetObserver(), SetOpaque(), SetParagraphFillTextOnly(), SetPendingSelection(), SetSelectionL(), SetSelectionVisibilityL(), SetTextColorOverride(), SetViewL(), SetViewLineAtTopL(), SetViewRect(), SetXyPosL(), TBeforeAfter, TDiscard, TDoHorizontalScroll, TPriorities, TTagmaForwarder, ViewRect(), VisualEndOfRunL(), XyPosToDocPosL(), anonymous, ~CTextView()

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

static IMPORT_C CTextView *NewL(CTextLayout *aLayout, const TRect &aDisplay, CBitmapDevice *aGd, MGraphicsDeviceMap *aDeviceMap, RWindow *aWin, RWindowGroup *aGroupWin, RWsSession *aSession);

Description

Allocates and constructs a CTextView object.

Parameters

CTextLayout *aLayout Pointer to the layout object referenced by the text view. Must not be NULL or a panic occurs. const TRect &aDisplay The rectangle in which text is displayed (the "view rectangle"). CBitmapDevice *aGd Bitmapped graphics device to draw to, e.g. the screen. MGraphicsDeviceMap *aDeviceMap The device map used for drawing and formatting. RWindow *aWin The window to draw to. Should not be NULL. RWindowGroup *aGroupWin Window group. Must be provided if a text cursor is to be displayed. It can be NULL if you don't need a text cursor. RWsSession *aSession Pointer to the window server session.

Return value

CTextView * Pointer to the new CTextView object.

IMPORT_C ~CTextView();

Description

IMPORT_C void SetDisplayContextL(CBitmapDevice *aGd, RWindow *aWin, RWindowGroup *aGroupWin, RWsSession *aSession);

Description

Changes the window server handles which the display uses. Any of the parameters can be NULL in which case they are not changed.

Parameters

CBitmapDevice *aGd Pointer to the bitmapped graphics device to draw to. RWindow *aWin Pointer to the view window. RWindowGroup *aGroupWin Pointer to the window group. RWsSession *aSession Pointer to the window server session.

IMPORT_C void SetLayout(CTextLayout *aLayout);

Description

Changes the text layout object used by the text view.

Parameters

CTextLayout *aLayout Pointer to the text layout object used by the text view. Must not be NULL or a panic occurs.

inline const CTextLayout *Layout() const;

Description

Returns a pointer to the text layout object used by the text view.

Return value

const CTextLayout * A pointer to the text layout object used by the text view.

IMPORT_C void SetViewRect(const TRect &aDisplay);

Description

Sets the rectangle in which the text is displayed.

Parameters

const TRect &aDisplay The view rectangle.

IMPORT_C void AlterViewRect(const TRect &aViewRect);

Description

Parameters

const TRect &aViewRect

IMPORT_C void SetMarginWidths(TInt aLabels, TInt aLineCursor);

Description

Sets the label and line cursor margin widths.

Does not redraw.

Parameters

TInt aLabels The width in pixels of the label margin. TInt aLineCursor The width in pixels of the line cursor margin.

IMPORT_C void SetHorizontalScrollJump(TInt aScrollJump);

Description

Sets the number of pixels by which a horizontal scroll jump will cause the view to scroll. To carry out a horizontal scroll, use ScrollDisplayL().

Parameters

TInt aScrollJump The number of pixels by which a horizontal scroll jump will cause the view to scroll. Must be a positive value or a panic occurs.

IMPORT_C void SetLineCursorBitmap(const CFbsBitmap *aLineCursorBitmap);

Description

Sets the bitmap to be used as a line cursor. This function must be called before attempting to draw the line cursor. Use SetCursorVisibilityL() to make the line cursor visible.

Parameters

const CFbsBitmap *aLineCursorBitmap The bitmap which represents the line cursor.

IMPORT_C void SetBackgroundColor(TRgb aColor);

Description

Sets the background colour for the view rectangle.

Does not redraw.

Parameters

TRgb aColor The background colour.

IMPORT_C void SetTextColorOverride(const TRgb *aOverrideColor=0);

Description

Overrides the text colour, so that when redrawn, all text has the colour specified, rather than the colour which is set in the text object. When text is in this overridden state, no highlighting is visible. To return the text colour to its original state, call this function again with an argument of NULL. This also has the effect that if selection visibility is set, any highlighting will be made visible again.

Does not do a redraw.

Parameters

const TRgb *aOverrideColor If not NULL, overrides the text colour.

IMPORT_C void SetCursorVisibilityL(TUint aLineCursor, TUint aTextCursor);

Description

Sets the visibility of the line and text cursors.

Notes:

A group window must have been provided before a text cursor can be drawn.

Before making the line cursor visible, a line cursor bitmap must have been provided (see SetLineCursorBitmap()).

Parameters

TUint aLineCursor Sets whether the line cursor should be displayed. For possible values, see the TCursor::TVisibility enumeration. TUint aTextCursor Sets whether the text cursor should be displayed and if so, whether it should flash. For possible values, see the TCursor::TVisibility enumeration.

IMPORT_C void SetSelectionVisibilityL(TBool aSelectionVisible);

Description

Sets whether the text and pictures within a selection should be highlighted. If necessary, the view is redrawn.

An example of when this function may need to be used is when a control loses or gains focus.

Parameters

TBool aSelectionVisible ETrue for highlighted selection. EFalse for unhighlighted selection.

IMPORT_C TBool SelectionVisible() const;

Description

Returns if the selection is currently visible.

In particular, the selection is invisible if the text color has been overridden.

Return value

TBool

IMPORT_C void EnablePictureFrameL(TBool aEnabled);

Description

Sets whether a picture frame should be displayed when the text cursor is located at a picture character.

Note:

If a picture frame is currently displayed, and aEnabled is EFalse, a redraw takes place, so that the frame is removed.

Parameters

TBool aEnabled True to enable picture frames, false to disable them.

IMPORT_C const TRect &ViewRect() const;

Description

Gets the rectangle in which the text is displayed.

Return value

const TRect & The view rectangle.

IMPORT_C const TRect &AlteredViewRect() const;

Description

Return value

const TRect &

IMPORT_C void MarginWidths(TInt &aLabels, TInt &aLineCursor) const;

Description

Gets the label and line cursor margin widths in pixels.

Parameters

TInt &aLabels On return contains the width in pixels of the label margin. TInt &aLineCursor On return contains the width in pixels of the line cursor margin.

IMPORT_C TInt HorizontalScrollJump() const;

Description

Gets the number of pixels by which a horizontal scroll jump will cause the view to scroll. On construction, the default horizontal scroll jump value is set to 20 pixels.

Return value

TInt The number of pixels by which a horizontal scroll jump will cause the view to scroll.

IMPORT_C TInt LeftTextMargin() const;

Description

Gets the left text margin width in pixels.

Return value

TInt The left text margin width in pixels.

IMPORT_C void SetLatentXPosition(TInt aLatentX);

Description

Sets the pending horizontal text cursor position. This is the horizontal coordinate to which the text cursor is moved after a scroll up or down by a line or a page.

Parameters

TInt aLatentX The horizontal coordinate to which the text cursor should be moved after a line or page scroll.

IMPORT_C void SetParagraphFillTextOnly(TBool aFillTextOnly);

Description

Sets the horizontal extent of the view rectangle to fill with paragraph fill colour (CParaFormat::iFillColor).

Does not redraw.

Parameters

TBool aFillTextOnly If true, the region filled with paragraph fill colour is the area within the paragraph's bounding rectangle only (see ParagraphRectL()). If false, the filled region includes the left text margin, if one has been set. By default, false.

IMPORT_C void SetCursorWidthTypeL(TTextCursor::EType aType, TInt aWidth=0);

Description

Sets the text cursor's type and weight and redraws it. If the cursor's placement is vertical (ECursorVertical), the weight is the width of the cursor. If the placement is horizontal, the weight is the height of the cursor.

Parameters

TTextCursor::EType aType The text cursor type. TInt aWidth The weight in pixels of the text cursor. Specify zero (the default) to leave the current weight unchanged.

IMPORT_C void SetCursorPlacement(TTmCursorPlacement aPlacement);

Description

Sets the text cursor's placement (its shape and position relative to the insertion position) and redraws it.

Parameters

TTmCursorPlacement aPlacement The text cursor's placement

IMPORT_C void SetCursorWeight(TInt aWeight);

Description

Sets the weight of the text cursor and redraws it.

If the cursor's placement is vertical (ECursorVertical), the weight is the width of the cursor. If the placement is horizontal, the weight is the height of the cursor. Has no effect if the weight value specified is zero or less.

Parameters

TInt aWeight The weight in pixels of the text cursor.

IMPORT_C void SetCursorFlash(TBool aEnabled);

Description

Sets the flashing state of the text cursor and redraws it.

Parameters

TBool aEnabled ETrue for a flashing cursor, EFalse for a non-flashing cursor.

IMPORT_C void SetCursorXorColor(TRgb aColor);

Description

Sets the text cursor's colour and redraws it. The cursor is drawn using an Exclusive OR draw mode which ensures that the cursor's colour is different from the background colour.

Parameters

TRgb aColor The text cursor's colour.

IMPORT_C void SetCursorExtensions(TInt aFirstExtension, TInt aSecondExtension);

Description

Parameters

TInt aFirstExtension TInt aSecondExtension

IMPORT_C TCursorSelection Selection() const;

Description

Gets the current selection.

Return value

TCursorSelection The current selection.

IMPORT_C TBool IsPictureFrameSelected(TRect &aPictureFrameRect, TInt &aDocPos) const;

Description

Tests whether there is a picture with a picture frame at the current cursor position. If there is, the aPictureFrameRect and aDocPos arguments are set to contain the picture frame rectangle and the document position of the picture, respectively.

Parameters

TRect &aPictureFrameRect If the function returns true, on return contains the picture frame rectangle. TInt &aDocPos If the function returns true, on return contains the document position of the picture.

Return value

TBool ETrue if there is a picture with a picture frame at the current cursor position. EFalse if not.

IMPORT_C TBool GetPictureRectangleL(TInt aDocPos, TRect &aPictureRect, TBool *aCanScaleOrCrop=0) const;

Description

Gets the bounding rectangle of the picture, if any, located at the document position or x,y coordinates specified, and returns it in aPictureRect.

If aCanScaleOrCrop is non-null, sets aCanScaleOrCrop to indicate whether the picture can be scaled or cropped. Returns true if the operation was successful. Returns false otherwise; that is, if there is no picture at the position, or if the position is unformatted.

Parameters

TInt aDocPos The document position of interest. TRect &aPictureRect On return, contains the rectangle which encloses the picture located at the position specified. TBool *aCanScaleOrCrop If non null and the function returns true, indicates whether the picture can be scaled or cropped. By default, null.

Return value

TBool ETrue if the operation was successful, (i.e. there is a picture character at the position, it has been loaded into memory, and the position is formatted). EFalse if any of these conditions are not met.

IMPORT_C TBool GetPictureRectangleL(TPoint aXyPos, TRect &aPictureRect, TBool *aCanScaleOrCrop=0);

Description

Returns EFalse if the specified position is not contained within a formatted picture.

Parameters

TPoint aXyPos TRect &aPictureRect TBool *aCanScaleOrCrop

Return value

TBool

IMPORT_C TBool FindXyPosL(const TPoint &aXyPos, TTmPosInfo2 &aPosInfo, TTmLineInfo *aLineInfo=0);

Description

Gets the document position of of the nearest character edge to the window coordinates specified.

Parameters

const TPoint &aXyPos The window coordinates to investigate. TTmPosInfo2 &aPosInfo If non-null, on return contains information about the position located in the text. TTmLineInfo *aLineInfo If non-null, on return contains information on the line that the position is in.

Return value

TBool ETrue if the position was in the text and aPosInfo and aLineInfo have been set.

IMPORT_C TInt XyPosToDocPosL(TPoint &aPoint);

Description

Gets the document position of of the nearest character edge to the window coordinates specified. The function first identifies the line which contains, or is nearest to, the vertical coordinate. Then it identifies the character in that line closest to the horizontal coordinate.

Parameters

TPoint &aPoint Window coordinates. On return, contains the window coordinates of the nearest character to the point.

Return value

TInt Nearest document position to specified window coordinates.

IMPORT_C TBool FindDocPosL(const TTmDocPosSpec &aDocPos, TTmPosInfo2 &aPosInfo, TTmLineInfo *aLineInfo=0);

Description

Finds the x-y position of the document position aDocPos.

If aDocPos is formatted, TRUE is returned and aPosInfo returns information about the document position and aLineInfo returns information about the line containing the document position, if it is non-null.

Parameters

const TTmDocPosSpec &aDocPos The document position to investigate. TTmPosInfo2 &aPosInfo If non-null, on return, contains information about the document position. TTmLineInfo *aLineInfo If non-null, on return, contains information on the line that the position is in.

Return value

TBool ETrue if the position was in the text and aPosInfo and aLineInfo have been set; EFalse otherwise.

IMPORT_C TBool DocPosToXyPosL(TInt aDocPos, TPoint &aPoint);

Description

Gets the window coordinates of the character located at the specified document position. If the document position specified has not been formatted, the function returns a value of false.

Parameters

TInt aDocPos The document position. TPoint &aPoint On return, contains the window coordinates of aDocPos. This value is undefined if the position has not been formatted.

Return value

TBool True if the document position is formatted, false if not.

IMPORT_C TRect ParagraphRectL(TInt aDocPos) const;

Description

Returns the rectangle enclosing the paragraph containing aDocPos. If the paragraph is not formatted, returns an empty rectangle. If the paragraph is partially formatted, returns the rectangle enclosing the formatted part.

Parameters

TInt aDocPos A document position within the paragraph.

Return value

TRect The rectangle which encloses the paragraph containing aDocPos.

IMPORT_C void CalculateHorizontalExtremesL(TInt &aLeftX, TInt &aRightX, TBool aOnlyVisibleLines);

Description

Returns the left and right extremes, in window coordinates, of the formatted text.

Parameters

TInt &aLeftX On return, contains the x coordinate of the leftmost point of the formatted text. TInt &aRightX On return, contains the x coordinate of the rightmost point of the formatted text. TBool aOnlyVisibleLines If ETrue, only scans partially or fully visible lines. If EFalse, scans all the formatted text.

IMPORT_C void MatchCursorHeightL(const TFontSpec &aFontSpec);

Description

Sets the height and ascent of the text cursor to the values contained in aFontSpec and redraws it.

Note:

The values set by this function are temporary. If the cursor is subsequently moved, it reverts to being based on the preceding character (unless at the start of a paragraph, in which case, it is based on the following character).

Parameters

const TFontSpec &aFontSpec Specifies a height and ascent to which to set the text cursor.

IMPORT_C void MatchCursorHeightToAdjacentChar(TBeforeAfter aBasedOn=EFCharacterBefore);

Description

Sets the height and ascent of the text cursor to be the same as an adjacent character and redraws it. By default, the values are set to be based on the preceding character.

Parameters

TBeforeAfter aBasedOn EFCharacterBefore to base the height and ascent of the text cursor on the preceding character. EFCharacterAfter to base them on the following character.

IMPORT_C TPoint SetSelectionL(const TCursorSelection &aSelection);

Description

Sets a selection. The selection is highlighted unless selection visibility has been unset. Any existing selection is cancelled. If necessary, the view is scrolled and redrawn.

Any background formatting is forced to complete first.

Parameters

const TCursorSelection &aSelection Specifies the start and end positions of the selection.

Return value

TPoint The number of pixels scrolled in the x (horizontal) and y (vertical) directions.

IMPORT_C void CancelSelectionL();

Description

Removes a selection, and redraws the affected part of the screen.

Any background formatting is forced to complete first.

IMPORT_C void ClearSelectionL();

Description

Un-draws a selection, redraws the affected part of the screen. The cursor selection remains as before. Analogous to CancelSelectionL(), but leaves the cursor selection untouched. This function should be called before calling CTextView::SetPendingSelection() _and_ SetHighlightExtensions has been used to extend the size of the highlight. Any background formatting is forced to complete first.

IMPORT_C TPoint SetDocPosL(const TTmDocPosSpec &aDocPos, TBool aDragSelectOn=EFalse);

Description

Moves the text cursor to a new document position. The view is scrolled so that the line containing the new cursor position is at the top, or the bottom, if the scroll direction was downwards.

Any background formatting is forced to complete first.

Parameters

const TTmDocPosSpec &aDocPos The new document position of the text cursor. TBool aDragSelectOn ETrue if the region between the old and new cursor positions should be selected, EFalse if not. If ETrue, any existing selection remains selected, so that this function can be used to extend or shorten a selected region. EFalse cancels any existing selection.

Return value

TPoint The number of pixels scrolled horizontally and vertically.

IMPORT_C TPoint SetDocPosL(TInt aDocPos, TBool aDragSelectOn=EFalse);

Description

Moves the text cursor to a new document position. The view is scrolled so that the line containing the new cursor position is at the top, or the bottom, if the scroll direction was downwards.

Any background formatting is forced to complete first.

Parameters

TInt aDocPos The new document position of the text cursor. TBool aDragSelectOn ETrue if the region between the old and new cursor positions should be selected, EFalse if not. If ETrue, any existing selection remains selected, so that this function can be used to extend or shorten a selected region. EFalse cancels any existing selection.

Return value

TPoint The number of pixels scrolled horizontally and vertically.

IMPORT_C TPoint SetXyPosL(TPoint aPos, TBool aDragSelectOn, TRect *&aPictureRect, TInt &aPictureFrameEdges);

Description

Moves the text cursor to the nearest point on the screen to the x,y coordinates specified.

Any background formatting is forced to complete first.

Parameters

TPoint aPos The window coordinates to which to move the text cursor. TBool aDragSelectOn ETrue if the region between the old and new cursor positions should be selected, EFalse if not. If ETrue, any existing selection remains selected, so that this function can be used to extend or shorten a selected region::EFalse cancels any existing selection. TRect *&aPictureRect On return, a pointer to the rectangle enclosing the picture at position aPos. If there is no picture at this position, returns NULL. TInt &aPictureFrameEdges On return, indicates whether aPos is located within the active region around a picture edge. The active region is the region inside which the cursor can be used to resize the picture. A value of zero indicates that aPos is not within this region. Otherwise, this value indicates which active region aPos is located in. For more information, see TFrameOverlay::TEdges.

Return value

TPoint The number of pixels scrolled horizontally and vertically.

IMPORT_C TPoint MoveCursorL(TCursorPosition::TMovementType &aMovement, TBool aDragSelectOn);

Description

Moves the text cursor in the direction and manner specified. If necessary, the view is scrolled so that the line containing the new cursor position is visible.

Any background formatting is forced to complete first.

Parameters

TCursorPosition::TMovementType &aMovement The direction and manner in which to move the cursor. On return set to the actual cursor movement. The actual cursor movement may be different from the one requested if for example the desired cursor movement is upwards and the cursor is already on the top line. In this case, this argument will return TCursorPosition::EFLineBeg. A return value of TCursorPosition::EFNoMovement indicates that no cursor movement took place. TBool aDragSelectOn ETrue if the region between the old and new cursor positions should be selected, EFalse if not. If ETrue, any existing selection remains selected, so that this function can be used to extend or shorten a selected region. EFalse cancels any existing selection.

Return value

TPoint The number of pixels scrolled horizontally and vertically.

IMPORT_C TInt ScrollDisplayL(TCursorPosition::TMovementType aMovement, CTextLayout::TAllowDisallow aScrollBlankSpace=CTextLayout::EFDisallowScrollingBlankSpace);

Pre-Condition

aMovement must not scroll the display beyond the formatted range. If aMovement scrolls beyond the formatted range, this method will leave with the error code CTextLayout::EPosNotFormatted

Description

Scrolls the view either horizontally or vertically and does a redraw.

Any background formatting is forced to complete first.

Parameters

TCursorPosition::TMovementType aMovement Controls the direction and the amount of scroll. CTextLayout::TAllowDisallow aScrollBlankSpace CTextLayout::EFAllowScrollingBlankSpace allows blank space to scroll into the visible area (applies when scrolling horizontally as well as vertically), CTextLayout::EFDisallowScrollingBlankSpace prevents blank space from scrolling into the visible area.

Return value

TInt The number of pixels scrolled

IMPORT_C TPoint SetViewLineAtTopL(TInt aLineNo);

Description

Moves the view vertically and redraws, so that the top of the specified line is located flush with the top of the view rectangle.

Note:

Line numbering is relative to formatted text only and the first formatted line is numbered one.

Parameters

TInt aLineNo The number of the line to be displayed at the top of the view rectangle.

Return value

TPoint The number of pixels the text was scrolled, may be positive or negative. A value of CTextLayout::EFScrollRedrawWholeScreen indicates that the entire visible area, at least, was scrolled.

IMPORT_C void ScrollDisplayPixelsL(TInt &aDeltaY);

Description

Scrolls the view vertically by a number of pixels, disallowing blank space from scrolling into the bottom of the visible area. Redraws the newly visible lines.

Any background formatting is forced to complete first.

Parameters

TInt &aDeltaY The number of pixels to scroll; may be a positive or negative value. On return, contains the number of pixels actually scrolled. Positive values move the text down, negative move it up.

IMPORT_C TInt ScrollDisplayLinesL(TInt &aDeltaLines, CTextLayout::TAllowDisallow aScrollBlankSpace=CTextLayout::EFDisallowScrollingBlankSpace);

Pre-Condition

aDeltaLines must not scroll the display beyond the formatted range. If aDeltaLines scrolls beyond the formatted range, this method will leave with the error code CTextLayout::EPosNotFormatted

Description

Scrolls the view vertically by a number of wholly or partially visible lines, disallowing blank space at the bottom of the visible area if aScrollBlankSpace is CTextLayout::EFDisallowScrollingBlankSpace. Redraws the newly visible lines.

Any background formatting is forced to complete first.

Parameters

TInt &aDeltaLines The number of lines to scroll; may be a positive or negative value. Positive values move the text down, negative move it up. On return, contains the number of lines not scrolled; that is, the requested number, minus the number actually scrolled. CTextLayout::TAllowDisallow aScrollBlankSpace Only relevant when scrolling downwards. CTextLayout::EFAllowScrollingBlankSpace allows blank space to scroll into the visible area. CTextLayout::EFDisallowScrollingBlankSpace prevents blank space from scrolling into the visible area.

Return value

TInt The number of pixels scrolled.

IMPORT_C TInt ScrollDisplayParagraphsL(TInt &aDeltaParas, CTextLayout::TAllowDisallow aScrollBlankSpace=CTextLayout::EFDisallowScrollingBlankSpace);

Pre-Condition

aDeltaParas must not scroll the display beyond the formatted range. If aDeltaParas scrolls beyond the formatted range, this method will leave with the error code CTextLayout::EPosNotFormatted

Description

Scrolls the view by a number of wholly or partially visible paragraphs disallowing blank space at the bottom of the visible area if aScrollBlankSpace is CTextLayout::EFDisallowScrollingBlankSpace. Redraws the newly visible paragraphs.

Any background formatting is forced to complete first.

Parameters

TInt &aDeltaParas The number of paragraphs to scroll; may be a positive or negative value; positive values move the text down, negative move it up. On return, contains the number of paragraphs not scrolled; that is the difference between the requested number and the number of paragraphs actually scrolled. CTextLayout::TAllowDisallow aScrollBlankSpace Only relevant when scrolling downwards. CTextLayout::EFAllowScrollingBlankSpace allows blank space to scroll into the visible area. CTextLayout::EFDisallowScrollingBlankSpace prevents blank space from scrolling into the visible area.

Return value

TInt The number of pixels scrolled.

IMPORT_C TPoint SetViewL(TInt aDocPos, TInt &aYPos, TViewYPosQualifier aYPosQualifier=TViewYPosQualifier(), TDiscard aDiscardFormat=EFViewDontDiscardFormat, TDoHorizontalScroll aDoHorizontalScroll=EFCheckForHorizontalScroll);

Description

Sets the vertical position of the view, so that the line containing aDocPos is located as close as possible to the vertical window coordinate aYPos.

Which part of the line is set to appear at aYPos (top, baseline, or bottom) is controlled by aYPosQualifier, which also specifies whether the visible area is to be filled and whether the line should be made fully visible if possible.

Parameters

TInt aDocPos The document position. Must be valid or a panic occurs. TInt &aYPos The y coordinate at which to position the character at aDocPos. On return, contains the actual vertical window coordinate at which the document position has been set. TViewYPosQualifier aYPosQualifier Controls which part of the line should appear at aYPos. TDiscard aDiscardFormat If EFViewDiscardAllFormat or EFViewDiscardAllNoRedraw the text is reformatted to include aDocPos, otherwise text is formatted only as necessary when bringing new lines into the visible area. If EFViewDiscardAllNoRedraw, no redraw takes place. TDoHorizontalScroll aDoHorizontalScroll

Return value

TPoint The number of pixels scrolled horizontally and vertically. The vertical coordinate may have a value of CTextLayout::EFScrollRedrawWholeScreen. This indicates that the entire visible area, at least, was scrolled, and so a full redraw was needed.

IMPORT_C void SetLeftTextMargin(TInt aLeftMargin);

Description

Sets the left text margin width in pixels.

The left text margin width is the distance between the text and the left edge of the page. Increasing the left text margin width causes text to move leftwards and decreasing the left text margin width causes text to move rightwards.

Does not redraw.

Parameters

TInt aLeftMargin The left text margin width in pixels.

IMPORT_C void DrawL(TRect aRect);

Description

Draws the text to a rectangle. Enters OOM state before leaving. RWindow::BeginRedraw() should always be called before calling this function, for the window that the textview draws to.

Parameters

TRect aRect Rectangle to which the text is drawn, normally the view rectangle.

IMPORT_C void DrawL(TRect aRect, CBitmapContext &aGc);

Description

Draws the text to a rectangle.

Draw to a specific GC rather than the stored one. This is essential when drawing CTextView objects that are embedded inside others, as happens for editable text controls in WEB (the outermost WEB object is a CTextView, which has embedded controls that own CEikEdwins, and these own CTextView objects).

Parameters

TRect aRect Rectangle to which the text is drawn, normally the view rectangle. CBitmapContext &aGc Graphics context to be drawn to. Flicker-free redrawing will not be applied, so this parameter should not be a window gc if flickering is to be avoided. Notice that the fonts drawn to this context will be taken from the graphics device map given to the constructor of this object or in subsequent calls to CTextLayout::SetImageDeviceMap. If such fonts cannot be used with this bitmap context, the behaviour is undefined.

inline void SetObserver(MObserver *aObserver);

Description

Sets a text view observer. This provides notification to the owner of the text view object of changes to the formatting. Its OnReformatL() function is called after reformatting but before redisplay, so that edit windows etc. can be resized.

Parameters

MObserver *aObserver Pointer to text view observer object.

IMPORT_C void SetPendingSelection(const TCursorSelection &aSelection);

Description

Makes a selection, but without updating the view.

This function would only be used before calling CTextView::HandleRangeFormatChangeL() or HandleInsertDeleteL() to make a selection which will become visible (if selection visibility is on) after the change handling function has returned.

Parameters

const TCursorSelection &aSelection The range to be selected after calling CTextView::HandleRangeFormatChangeL() or HandleInsertDeleteL().

inline void EnableFlickerFreeRedraw();

Description

inline void DisableFlickerFreeRedraw();

Description

inline TBool FlickerFreeRedraw() const;

Description

Return value

TBool

inline void GetOrigin(TPoint &aPoint) const;

Description

Gets the origin of the cursor.

Parameters

TPoint &aPoint On return, the cursor origin.

IMPORT_C TCursorSelection GetForwardDeletePositionL();

Description

Returns a selection for which characters should be deleted in a forwards delete.

Return value

TCursorSelection A selection for which characters should be deleted in a forwards delete.

IMPORT_C TCursorSelection GetBackwardDeletePositionL();

Description

Returns a selection for which characters should be deleted in a backwards delete.

Return value

TCursorSelection A selection for which characters should be deleted in a backwards delete.

IMPORT_C void FormatTextL();

Description

Reformats the whole document, or just the visible text, if formatting is set to the band only (see CTextLayout::SetAmountToFormat()).

Notes:

Reformatting the entire document may be time consuming, so only use this function if necessary.

This function does not redraw the reformatted text.

IMPORT_C TInt HandleCharEditL(TUint aType=CTextLayout::EFCharacterInsert, TBool aFormatChanged=EFalse);

Description

Reformats and redraws the view in response to a single key press. The precise amount of text to be reformatted is controlled by the second parameter.

Parameters

TUint aType Indicates the type of edit which has taken place. CTextLayout::EFCharacterInsert (the default) for a character insertion, CTextLayout::EFParagraphDelimiter for a paragraph delimiter insertion, CTextLayout::EFLeftDelete or CTextLayout::EFRightDelete for a character or paragraph delimiter deletion to the left or right of the cursor position. TBool aFormatChanged ETrue if text is to be reformatted from the start of the paragraph the cursor was on before the edit, EFalse if from the start of the line the cursor was on before the edit.

Return value

TInt The number of pixels by which the text had to be scrolled vertically (positive means text moved down).

IMPORT_C TPoint HandleRangeFormatChangeL(TCursorSelection aSelection, TBool aFormatChanged=EFalse);

Description

Reformats and redraws the view after changes to the character or paragraph formatting of a block of text. Reformatting can take place either from the start of the line or the start of the paragraph containing the cursor position, depending on aFormatChanged.

Can be used in combination with SetPendingSelection() to set a selection which should remain after the function has returned.

Note:

A panic occurs if partial lines are excluded from the view (see CTextLayout::ExcludingPartialLines()).

Any background formatting is forced to complete first.

Parameters

TCursorSelection aSelection Indicates the text range which has been reformatted. TBool aFormatChanged ETrue if text is to be reformatted from the start of the paragraph the cursor was on before the edit, EFalse if from the start of the line the cursor was on before the edit.

Return value

TPoint The number of pixels scrolled horizontally and vertically.

IMPORT_C TPoint HandleInsertDeleteL(TCursorSelection aSelection, TInt aDeletedChars, TBool aFormatChanged=EFalse);

Description

Reformats and redraws the view after inserting, deleting or replacing a block of text.

Can be used in combination with SetPendingSelection() to set a selection which should remain after the function has returned.

Notes:

If inserting or deleting a single character, use CTextView::HandleCharEditL() instead.

A panic occurs if partial lines are excluded from the view (see CTextLayout::ExcludingPartialLines()).

Parameters

TCursorSelection aSelection The start and new length of the changed block. If this function is being used to handle deletion only, this argument should be of length zero and its start position should be the beginning of the deletion. TInt aDeletedChars The number of deleted characters. Specify zero if this function is being used to handle insertion only. TBool aFormatChanged ETrue if text is to be reformatted from the start of the paragraph the cursor was on before the edit, EFalse if from the start of the line the cursor was on before the edit.

Return value

TPoint The number of pixels scrolled horizontally and vertically.

IMPORT_C void HandleGlobalChangeL(TViewYPosQualifier aYPosQualifier=TViewYPosQualifier());

Description

Reformats and redraws the view after a global change has been made to the layout. Examples of global layout changes include changing the format mode, the wrap width, or the visibility of nonprinting characters.

Forces any background formatting to complete.

Parameters

TViewYPosQualifier aYPosQualifier Specifies whether the visible area is to be filled and whether the top line should be made fully visible if possible.

IMPORT_C void HandleGlobalChangeNoRedrawL(TViewYPosQualifier aYPosQualifier=TViewYPosQualifier());

Description

Reformats the view after a global change has been made to the layout, but without causing a redraw. Examples of global layout changes include changing the format mode, the wrap width, or the visibility of nonprinting characters.

Forces any background formatting to complete.

Parameters

TViewYPosQualifier aYPosQualifier Specifies whether the visible area is to be filled and whether the top line should be made fully visible if possible.

IMPORT_C void HandleAdditionalCharactersAtEndL();

Description

Reformats and redraws to reflect the addition of one or more complete paragraphs at the end of the text. For instance, it may be used where information is being found by an active object and appended to a document.

Note:

This function should not be used to handle the situation where text is added to the final paragraph. In this case, use HandleInsertDeleteL() or HandleCharEditL() instead.

IMPORT_C void FinishBackgroundFormattingL();

Description

Forces completion of background formatting.

This is called automatically by all CTextView functions which depend on the formatting being up to date.

IMPORT_C const TTmDocPos &VisualEndOfRunL(const TTmDocPos &aStart, const TTmDocPos &aEnd, TCursorPosition::TVisualEnd aDirection);

Description

Calculates which of two document positions would be considered more left or more right, depending on the value of aDirection.

Parameters

const TTmDocPos &aStart First document position to compare. const TTmDocPos &aEnd Second document position to compare. TCursorPosition::TVisualEnd aDirection If EVisualLeft, the function returns the left-most of aStart and aEnd. If EVisualRight, the function returns the right-most.

Return value

const TTmDocPos & The left-most of aStart and aEnd if aDirection was EVisualLeft; otherwise, the right-most.

IMPORT_C void GetCursorPos(TTmDocPos &aPos) const;

Description

Gets the cursor position as a TTmDocPos.

Parameters

TTmDocPos &aPos On return, the cursor position.

IMPORT_C TPoint SetDocPosL(const TTmDocPos &aDocPos, TBool aDragSelectOn=EFalse);

Description

Moves the text cursor to a new document position. The view is scrolled so that the line containing the new cursor position is at the top, or the bottom, if the scroll direction was downwards.

Any background formatting is forced to complete first.

Parameters

const TTmDocPos &aDocPos The new document position of the text cursor. TBool aDragSelectOn ETrue if the region between the old and new cursor positions should be selected, EFalse if not. If ETrue, any existing selection remains selected, so that this function can be used to extend or shorten a selected region. EFalse cancels any existing selection.

Return value

TPoint The number of pixels scrolled horizontally and vertically.

IMPORT_C void SetOpaque(TBool aDrawOpaque);

Description

Sets and unsets an opaque flag on the text view's window.

Parameters

TBool aDrawOpaque If true, opaque drawing mode is switched on. If false, normal drawing will be used.

IMPORT_C void MakeVisible(TBool aVisible);

Description

Stops or allows text to be drawn. Included to allow users to control visibility if text is part of an invisible control.

Parameters

TBool aVisible ETrue to make the text visible, EFalse to make it invisible.

class MObserver;

Description

Provides notification to the owner of the text view object of changes to the formatting.

Its OnReformatL() function is called after reformatting but before redisplay, so that edit windows etc. can be resized.

Members

Defined in CTextView::MObserver:
OnReformatL()

Member functions

---

OnReformatL()

virtual void OnReformatL(const CTextView *aTextView)=0;

Description

Called after reformatting but before redisplay, so that edit windows, etc., can be resized.

Parameters

const CTextView *aTextView A pointer to the current text view object.

class TTagmaForwarder : public MTmTextLayoutForwarder;

Description

A standard inquiry interface for the text formatting engine, built on top of a CTextView object.

To use it, construct a TTagmaForwarder object, then call InitL(), which finishes background formatting, then call the MTmTextLayoutForwarder functions.

Derivation

• MTmTextLayoutForwarder - No description.

• CTextView::TTagmaForwarder - A standard inquiry interface for the text formatting engine, built on top of a CTextView object

Members

Defined in CTextView::TTagmaForwarder:
GetOrigin(), InitL(), TTagmaForwarder(), TextLayout()

Construction and destruction

---

TTagmaForwarder()

inline TTagmaForwarder();

Description

This constructor deliberately does not take a pointer or reference to CTextView, to prevent the class from being used unless InitL() is called.

Member functions

---

InitL()

inline void InitL(CTextView *aView);

Description

Called after construction, to complete background reformatting.

Parameters

CTextView *aView A pointer to the text view object.

---

TextLayout()

private: virtual inline const CTmTextLayout &TextLayout() const;

Description

Returns a reference to the CTmTextLayoutObject this MTmTextLayoutForwarder forwards inquiries to.

Return value

const CTmTextLayout &

---

GetOrigin()

private: virtual inline void GetOrigin(TPoint &aPoint) const;

Description

The origin is subtracted from coordinates passed in and added to those passed out.

Parameters

TPoint &aPoint

TPriorities

Description

EFBackgroundFormattingPriority

n/a

Description

deprecated 8.0

EFFirstCharOnLine EFLastCharOnLine

TBeforeAfter

Description

Cursor height matching.

Passed as an argument to MatchCursorHeightToAdjacentChar().

EFCharacterBefore Text cursor height is matched to preceding character. EFCharacterAfter Text cursor height is matched to following character.

TDiscard

Description

Whether to reformat and redraw. Argument to SetViewL().

EFViewDiscardAllFormat Discard all formatting; redraw. EFViewDontDiscardFormat Do not discard all formatting; redraw. EFViewDiscardAllNoRedraw Discard all formatting; no redraw. EFViewDontDiscardFullRedraw Do not discard all formatting; redraw.

TDoHorizontalScroll

Description

EFNoHorizontalScroll EFCheckForHorizontalScroll