Class CTextLayout

CTextLayout

Support

Supported from 5.0

Description

Text layout.

CTextLayout is the lowest-level text formatting class in the Text Views API. It obtains text and formatting attributes via the MLayDoc interface class and formats the text to a certain width.

It has functions for drawing the text and performing hit-detection — that is, converting x-y coordinates to document positions, and vice versa. It defines many public functions that are not generally useful, but are called by the higher-level CTextView class, or exist only for the convenience of closely associated classes like the printing and pagination systems. These are identified in the documentation by the text "not generally useful".

When using the CTextLayout class, you must be aware of what functions have previously been called. For example:

1) Formatting and scrolling functions must not be called if a CTextView object owns the CTextLayout object, because the CTextView object may be reformatting the CTextLayout object asynchronously by means of an active object, or may hold some state information about the CTextLayout object that would be invalidated by reformatting. These functions are identified in the documentation by the text "Do not use if a CTextView object owns this CTextLayout object.".

2) Functions that raise out of memory exceptions can leave the object in an inconsistent state; these functions can be identified as usual by their trailing L. When this occurs, it is necessary to discard the formatting information by calling DiscardFormat().

3) Some functions change formatting parameters like the wrap width or band height, but do not reformat to reflect the change. These functions are identified in the documentation by the text "Reformat needed".

Derivation

CBase Base class for all classes to be instantiated on the heap CTextLayout Text layout

Defined in CTextLayout:
AdjustVerticalAlignment(), Anonymous, BandHeight(), CalculateHorizontalExtremesL(), ChangeBandTopL(), CustomDraw(), DiscardFormat(), DocPosToXyPosL(), DocumentLength(), DrawBorders(), DrawL(), EFAllParagraphsNotWrapped, EFAllowScrollingBlankSpace, EFCharacterInsert, EFDisallowScrollingBlankSpace, EFFormatAllText, EFFormatBand, EFIndividualChars, EFLeftDelete, EFMaximumLineWidth, EFNoCurrentFormat, EFNotInCurrentFormat, EFParagraphDelimiter, EFParagraphsWrappedByDefault, EFRightDelete, EFScrollRedrawWholeScreen, EFViewDiscardAllFormat, EFViewDontDiscardFormat, EFWholeLinesOnly, ExcludingPartialLines(), FirstCharOnLine(), FirstDocPosFullyInBand(), FirstFormattedPos(), FirstLineInBand(), FontHeightIncreaseFactor(), ForceNoWrapping(), FormatBandL(), FormatCharRangeL(), FormatLineL(), FormatNextLineL(), FormattedHeightInPixels(), FormattedLength(), GetCharacterHeightAndAscentL(), GetFontHeightAndAscentL(), GetLineRect(), GetLineRectL(), GetMinimumSizeL(), HandleAdditionalCharactersAtEndL(), HandleBlockChangeL(), HandleCharEditL(), InvertRangeL(), IsBackgroundFormatting(), IsFormattingBand(), IsWrapping(), MinimumLineDescent(), NewL(), NonPrintingCharsVisibility(), NotifyTerminateBackgroundFormatting(), NumFormattedLines(), PageDownL(), PageUpL(), ParagraphHeight(), ParagraphRectL(), PictureRectangleL(), PixelsAboveBand(), PosInBand(), PosIsFormatted(), PosRangeInBand(), ReformatVerticalSpaceL(), ScrollLinesL(), ScrollParagraphsL(), SetAmountToFormat(), SetBandHeight(), SetCustomDraw(), SetExcludePartialLines(), SetFontHeightIncreaseFactor(), SetFormatMode(), SetImageDeviceMap(), SetLabelsDeviceMap(), SetLabelsMarginWidth(), SetLayDoc(), SetMinimumLineDescent(), SetNonPrintingCharsVisibility(), SetTruncating(), SetTruncatingEllipsis(), SetViewL(), SetWrapWidth(), TAllowDisallow, TAmountFormatted, TCurrentFormat, TDiscard, ToParagraphStart(), Truncating(), TruncatingEllipsis(), XyPosToDocPosL(), YBottomLastFormattedLine(), ~CTextLayout()

Inherited from CBase:
operator new()

static CTextLayout *NewL(MLayDoc *aDoc,TInt aWrapWidth);

Description

Allocates and constructs a CTextLayout object. By default, the formatting is set to the entire document (EFFormatAllText).

Reformat needed.

Parameters

MLayDoc *aDoc Pointer to the MLayDoc implementation that is the source of the text and formatting information. Must not be NULL or a panic occurs. TInt aWrapWidth The wrapping width in pixels.

Return value

CTextLayout * Pointer to the new CTextLayout object.

~CTextLayout();

Description

The destructor frees all resources owned by the object, prior to its destruction.

void SetBandHeight(TInt aHeight);

Description

Sets the height of the band in pixels or twips. This is the height of the visible text, or the view window, and it is also the page height for the purposes of scrolling up and down by page. If aHeight is less than 1 the value 1 is used. If the current mode is screen mode (CLayoutData::EFScreenMode) or what-you-see-is-what-you-get mode (CLayoutData::EFWysiwygMode), aHeight is in pixels, otherwise it is in twips.

Reformat needed.

Parameters

TInt aHeight The band height in pixels or twips.

TInt BandHeight() const;

Description

Gets the height of the band in pixels or twips.

Return value

TInt The height of the band in pixels or twips.

void SetAmountToFormat(TAmountFormatted aAmountOfFormat=EFFormatBand);

Description

Sets whether to format all the text (if aAmountOfFormat is EFFormatAllText), or just the visible band (if aAmountOfFormat is EFFormatBand). If band formatting is selected, enough text is formatted to fill the visible height.

Reformat needed.

Parameters

TAmountFormatted aAmountOfFormat CTextLayout::EFFormatBand (the default) to format the visible text only. CTextLayout::EFFormatAllText to format all the text in the document.

TBool IsFormattingBand() const;

Description

Tests whether band formatting is on, as set by CTextLayout::SetAmountToFormat().

Return value

TBool True if band formatting is on, false if not.

TInt PosRangeInBand(TInt& aDocPos) const;

Description

Returns the number of fully or partially visible characters in the visible band.

Parameters

TInt& aDocPos On return, contains the document position of the first fully or partially visible character in the band.

Return value

TInt The total number of characters in the band.

TBool PosInBand(TInt aDocPos,TPoint& aXyPos) const;

Description

Tests whether the document position aDocPos is fully or partially visible. If it is, puts the y coordinate of the left-hand end of the baseline of the line containing aDocPos into aXyPos.

Parameters

TInt aDocPos The document position of interest. TPoint& aXyPos On return, contains the y coordinate of the left-hand end of the baseline of the line containing aDocPos.

Return value

TBool True if the position is visible. False if the position is not visible.

TInt FirstLineInBand() const;

Description

Returns the line number, counting from 0, of the first fully visible line.

Return value

TInt The line number of the first fully visible line.

TInt FirstDocPosFullyInBand() const;

Description

Gets the first document position in a line that starts at or below the top of the visible area. If there is no such line, returns the position after the last formatted character.

Return value

TInt The document position of the first character in a line within the visible area.

TInt PixelsAboveBand() const;

Description

Returns the height in pixels of any formatted text above the visible region.

Return value

TInt The height in pixels of any formatted text above the visible region.

void SetWrapWidth(TInt aWrapWidth);

Description

Sets the wrap width. If the current format mode is screen mode (CLayoutData::EFScreenMode) aWrapWidth is in pixels, otherwise it is in twips.

Reformat needed.

Parameters

TInt aWrapWidth The wrap width in pixels or twips.

void ForceNoWrapping(TBool aNoWrapping=EFAllParagraphsNotWrapped);

Description

Turns wrapping on (if aNoWrapping is EFParagraphsWrappedByDefault) or off (if aNoWrapping is EFAllParagraphsNotWrapped). Overrides the paragraph format when wrapping is turned off — paragraphs are not broken into lines even if the iWrap member of CParaFormat is true. If wrapping is turned on, CParaFormat::iWrap is honoured.

Reformat needed.

Parameters

TBool aNoWrapping EFAllParagraphsNotWrapped (the default) to turn wrapping off, EFParagraphsWrappedByDefault to turn wrapping on.

TBool IsWrapping() const;

Description

Tests whether wrapping is on or off.

Return value

TBool True if wrapping is on, false if off.

void SetTruncating(TBool aOn);

Support

Supported from 6.0

Description

Sets the truncation mode. If truncation is on, lines that exceed the wrap width, either because they have no legal line break, or because wrapping is off, are truncated, and an ellipsis is inserted.

Parameters

TBool aOn If ETrue, lines which extend beyond the wrap width are truncated with an ellipsis character. If EFalse, no ellipsis is used.

TBool Truncating() const;

Support

Supported from 6.0

Description

Tests whether truncation is on (as set by SetTruncating()).

Return value

TBool True if truncation is on, false if not.

void SetTruncatingEllipsis(TChar aEllipsis);

Support

Supported from 6.0

Description

Sets the ellipsis character to be used if truncation is on. Specify the value 0xFFFF (the illegal Unicode character) if no ellipsis character should be used. By default, the ellipsis character is 0x2026, the ordinary horizontal ellipsis.

Parameters

TChar aEllipsis The Unicode value of the truncating ellipsis character.

TChar TruncatingEllipsis() const;

Support

Supported from 6.0

Description

Returns the ellipsis character used when truncation is on. The value 0xFFFF (the illegal Unicode character) means that no ellipsis character is appended to truncated text.

Return value

TChar The Unicode value of the truncating ellipsis character.

void GetMinimumSizeL(TInt aWrapWidth,TSize& aSize);

Support

Supported from 6.0

Description

Gets the width and height of the bounding box of the text, including indents and margins, when formatted to the specified wrap width.

This is useful for applications like a web browser that need to determine the minimum width for a piece of text: if you specify zero as the wrap width, the returned aSize.iWidth contains the minimum width that could be used for the text without illegal line breaks, and if you specify KMaxTInt for aWrapWidth, the returned aSize.iHeight contains the minimum height: the height when each paragraph is a single line of unlimited length.

Parameters

TInt aWrapWidth The wrap width for the bounding box. TSize& aSize On return, contains the width and height of the bounding box.

void DiscardFormat();

Description

Discards all formatting information. This function is used by the CTextView and the printing classes, but should be called by higher-level classes that need to clean up after any CTextLayout function has caused an out-of-memory exception.

void SetFormatMode(CLayoutData::TFormatMode aFormatMode,TInt aWrapWidth,MGraphicsDeviceMap* aFormatDevice);

Description

Sets the format mode and wrap width and (for certain format modes only) sets the formatting device.

Reformat needed.

Notes:

• If aFormatMode is CLayoutData::EFWysiwygMode or CLayoutData::EFPrintPreviewMode, the format device is set to aFormatDevice, which must not be NULL.

• If aFormatMode is CLayoutData::EFScreenMode or CLayoutData::EFPrintMode, aFormatDevice is ignored and should be NULL; the format device is set to the image device.

• The wrap width is set in either twips or pixels using the same rule as for SetWrapWidth().

Parameters

CLayoutData::TFormatMode aFormatMode The format mode. TInt aWrapWidth The wrap width in pixels or twips. MGraphicsDeviceMap* aFormatDevice The formatting device or NULL, depending on the format mode.

TBool IsBackgroundFormatting() const;

Description

Tests whether background formatting is currently taking place. Background formatting is managed by CTextView, using an active object, when the CTextLayout object is owned by a CTextView object.

Not generally useful.

Return value

TBool True if background formatting is currently taking place. False if not.

void NotifyTerminateBackgroundFormatting();

Description

CTextView calls this function when background formatting has ended. It allows the CTextLayout object to discard information used only during background formatting.

Not generally useful.

TInt FormattedHeightInPixels() const;

Description

Returns the height in pixels of the formatted text.

Return value

TInt The height in pixels of all the formatted text.

TInt FirstFormattedPos() const;

Support

Supported from 5.1

Description

Returns the document position of the first formatted character.

Return value

TInt The document position of the first formatted character.

TBool PosIsFormatted(TInt aDocPos) const;

Description

Tests whether the character aDocPos is formatted.

Note:

If a section of text contains characters p to q, it contains document positions p to q + 1; but this function returns true for positions p to q only, so it refers to characters, not positions. However, it will return true for q if q is the end of the document.

Parameters

TInt aDocPos The document position of interest.

Return value

TBool True if the character at the document position specified is formatted. False if not.

TInt FormattedLength() const;

Description

Returns the number of formatted characters. This will be one more than expected if the formatted text runs to the end of the document, because it will include the end-of-text character.

Return value

TInt The number of formatted characters in the document.

TInt NumFormattedLines() const;

Description

Gets the number of formatted lines.

Return value

TInt The number of formatted lines in the document.

void SetImageDeviceMap(MGraphicsDeviceMap *aGd);

Description

Sets the device map used for drawing and formatting. This device map is also used for formatting and drawing paragraph labels unless a separate label device map has been set (see SetLabelsDeviceMap()).

Reformat needed.

Note:

Although the name of the function suggests that only the image device is set, the formatting device is also set.

Parameters

MGraphicsDeviceMap *aGd The device map used for drawing and formatting.

void SetLabelsDeviceMap(MGraphicsDeviceMap *aDeviceMap);

Description

Sets the device map used for formatting and drawing paragraph labels. If not set, the device map used for labels will be the same as that used for the text.

Reformat needed.

Parameters

MGraphicsDeviceMap *aDeviceMap The device map used for formatting and drawing paragraph labels.

TBool DocPosToXyPosL(TInt aDocPos,TPoint& aPos,TUint aFlags=CLayoutData::EFIndividualChars) const;

Description

Returns the x-y coordinates of the document position aDocPos in aPos. The return value is true if the postion is formatted, or false if it is not, in which case aPos is undefined.

Parameters

TInt aDocPos The document position. TPoint& aPos On return, contains the x-y coordinates of aDocPos. TUint aFlags Two possible values: CLayoutData::EFIndividualChars is the default, and performs the task at full accuracy, and CLayoutData::EFWholeLinesOnly, which examines lines only and sets aXyPos.iY only, and cannot leave.

Return value

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

TInt XyPosToDocPosL(TPoint &aPos,TUint aFlags=CLayoutData::EFIndividualChars) const;

Description

Returns the document position of the nearest character edge to aPos. Sets aPos to the actual position of the intersection of the line's baseline with the character's edge. If aPos is before the start of the formatted area, returns the first formatted character; if it is after the end of the formatted area, returns the position after the last formatted character, or the end of the document, whichever is less.

Parameters

TPoint &aPos Contains coordinates to convert to a document position. On return, contains the exact coordinates of the intersection of the line's baseline with the character edge at the document position. TUint aFlags Two possible values: CLayoutData::EFIndividualChars is the default, and performs the task at full accuracy (the function returns the document position of the character edge nearest to the coordinates).CLayoutData::EFWholeLinesOnly examines lines only and returns the position at the right end of the line if aPos.iX > 0, otherwise the position at the left end.

Return value

TInt The document position of the nearest character to the coordinates, or of the start or end of the line, depending on the value of aFlags.

TInt FirstCharOnLine(TInt aLineNo) const;

Description

Gets the document position of the first character in the specified line, counting the first line as line one (not zero) in the band. If the line is after the band, returns the last character position of the band. If there is no formatted text, returns CTextLayout::EFNoCurrentFormat.

Parameters

TInt aLineNo Line number in formatted text, counting the first line as line one.

Return value

TInt The document position of the first character on the line.

TInt GetLineRect(TInt aYPos,TRect& aLine) const;

Description

Gets the rectangle enclosing the formatted line that contains or is closest to y coordinate aYPos. If aYPos is above the first formatted line, the rectangle returned is that of the first formatted line. If aYPos is below the last formatted line the rectangle returned is that of the last formatted line. If there is no formatted text, returns CTextLayout::EFNoCurrentFormat.

Parameters

TInt aYPos The y coordinate of the line of interest. TRect& aLine On return, contains the rectangle which encloses the line at aYPos.

Return value

TInt The line width in pixels.

TRect GetLineRectL(TInt aDocPos1,TInt aDocPos2) const;

Description

Gets a rectangle enclosing two formatted document positions on the same line. If the second position is less than the first, or on a different line, it is taken to indicate the end of the line. This function panics if either position is unformatted.

Parameters

TInt aDocPos1 The first document position on the line. TInt aDocPos2 The second document position on the line.

Return value

TRect The minimal rectangle, which bounds both positions.

TBool PictureRectangleL(TInt aDocPos,TRect& aPictureRect,TBool* const aCanScaleOrCrop=NULL) const;
TBool PictureRectangleL(const TPoint& aXyPos,TRect& aPictureRect,TBool* const aCanScaleOrCrop=NULL) const;

Description

Gets the bounding rectangle of the picture, if any, located at the document position or 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. TPoint aXyPos The layout coordinates of interest. TRect& aPictureRect On return, contains the rectangle which encloses the picture located at the position specified. TBool* const aCanScaleOrCrop If non-NULL and the function returns true, on return, indicates whether the picture can be scaled or cropped. By default, NULL.

Return value

TBool True 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). False if any of these conditions are not met.

TInt ToParagraphStart(TInt& aDocPos) const;

Description

Sets aDocPos to the paragraph start and returns the amount by which aDocPos has changed, as a non-negative number.

Parameters

TInt& aDocPos A document position. On return, contains the document position of the first character in the paragraph.

Return value

TInt The number of characters skipped in moving to the new document position.

TInt ParagraphHeight(TInt aDocPos) const;

Description

Returns the height of the paragraph containing aDocPos. If the paragraph is not formatted, returns zero. If the paragraph is partially formatted, returns the height of the formatted part.

Parameters

TInt aDocPos A document position within the paragraph of interest.

Return value

TInt The height in pixels of the paragraph. Zero if the paragraph is not formatted.

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.

TInt DocumentLength() const;

Description

Returns the document length in characters, including all the text, not just the formatted portion, but not including the final paragraph delimiter (the "end-of-text character") if any. Thus the length of an empty document is zero.

Return value

TInt The number of characters in the document

TInt YBottomLastFormattedLine() const;

Description

Returns the y coordinate of the bottom of the last formatted line, relative to the top of the visible region.

Return value

TInt The y coordinate of the bottom of the last formatted line.

TBool CalculateHorizontalExtremesL(TInt& aLeftX,TInt& aRightX,TBool aOnlyVisibleLines,TBool aIgnoreWrapCharacters=EFalse) const;

Description

Returns the left and right extremes, in layout 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. TBool aIgnoreWrapCharacters If ETrue, doesn’t include wrap characters in the measurement (paragraph delimiters, forced line breaks, etc.). If EFalse, includes them.

Return value

TBool False if there is no formatted text, otherwise true.

void GetCharacterHeightAndAscentL(TInt aDocPos,TInt& aHeight,TInt& aAscent) const;

Description

Gets the height (ascent + descent) and ascent of the font of the character at aDocPos, as created using the graphics device map used for drawing (the "image device") and returns them in aHeight and aAscent, after increasing aHeight by the font height increase factor (see SetFontHeightIncreaseFactor()).

Parameters

TInt aDocPos A document position. TInt& aHeight On return contains the height in pixels of the character at aDocPos. TInt& aAscent On return, contains the ascent in pixels of the character at aDocPos.

void GetFontHeightAndAscentL(const TFontSpec& aFontSpec,TInt& aHeight,TInt& aAscent) const;

Description

Gets the height (ascent + descent) and ascent of the font specified by aFontSpec, as created using the graphics device map used for drawing (the "image device") and puts them into aHeight and aAscent, after increasing aHeight by the font height increase factor (see SetFontHeightIncreaseFactor()).

Parameters

const TFontSpec& aFontSpec Font specification. TInt& aHeight On return, contains the height in pixels of the font. TInt& aAscent On return, contains the ascent in pixels of the font.

void SetFontHeightIncreaseFactor(TInt aPercentage);

Support

Supported from 5.1

Description

Sets the percentage by which font heights are increased in order to provide automatic extra spacing (leading) between lines. This amount is set to CLayoutData::EFFontHeightIncreaseFactor, which is 7, when a CTextLayout object is created.

Reformat needed.

Parameters

TInt aPercentage Factor by which to increase font heights.

TInt FontHeightIncreaseFactor() const;

Support

Supported from 5.1

Description

Returns the font height increase factor as a percentage (i.e. a return value of 7 means that font heights are increased by 7% to provide automatic extra spacing between lines).

Return value

TInt Factor by which font heights are increased.

void SetMinimumLineDescent(TInt aPixels);

Support

Supported from 5.1

Description

Sets the minimum line descent in pixels. This amount is set to CLayoutData::EFMinimumLineDescent, which is 3, when a CTextLayout object is created.

Reformat needed.

Parameters

TInt aPixels The minimum line descent in pixels.

TInt MinimumLineDescent() const;

Support

Supported from 5.1

Description

Returns the minimum line descent in pixels.

Return value

TInt The minimum line descent in pixels.

void SetLayDoc(MLayDoc *aDoc);

Description

Sets the layout object's source text to aDoc.

Reformat needed.

Parameters

MLayDoc *aDoc Pointer to the MLayDoc implementation that is the source of the text and formatting information. Must not be NULL or a panic occurs.

void SetLabelsMarginWidth(TInt aWidth);

Description

Sets the width in pixels of the margin in which labels are drawn.

Reformat needed.

Parameters

TInt aWidth The width in pixels of the labels margin.

void SetNonPrintingCharsVisibility(TNonPrintingCharVisibility aVisibility);

Description

Specifies which non-printing characters (e.g. space, paragraph break, etc.) are to be drawn using symbols.

Reformat needed (because non-printing characters may differ in width from their visible representations).

Parameters

TNonPrintingCharVisibility aVisibility Indicates which non-printing characters are drawn using symbols.

TNonPrintingCharVisibility NonPrintingCharsVisibility() const;

Description

Returns which non-printing characters are drawn using symbols.

Return value

TNonPrintingCharVisibility Indicates which non-printing characters are drawn using symbols.

void SetExcludePartialLines(TBool aExcludePartialLines=ETrue);

Description

Specifies whether partially displayed lines (at the top and bottom of the view) are to be prevented from being drawn, and whether the top of the display is to be aligned to the nearest line. This function takes effect only when the text is next formatted or scrolled.

Note:

This function was designed for non-editable text in the Agenda application, and there is an important restriction:CTextView functions that reformat the text after editing must not be used while partial lines are excluded; these functions are CTextView::HandleCharEditL(), CTextView::HandleInsertDeleteL() and CTextView::HandleRangeFormatChangeL().

Parameters

TBool aExcludePartialLines ETrue (the default) to exclude partially displayed lines from the view. EFalse to include them.

TBool ExcludingPartialLines() const;

Description

Tests whether partial lines at the top and bottom of the view are currently excluded.

Return value

TBool True if partial lines are excluded, false if they are displayed.

void FormatBandL();

Description

Formats enough text to fill the visible band.

Note:

Do not use if a CTextView object owns this CTextLayout object.

void FormatCharRangeL(TInt aStartDocPos,TInt aEndDocPos);

Description

Sets the formatted text to begin at the start of the paragraph including aStartPos and end at aEndPos. Moves the line containing aStartDocPos to the top of the visible area.

Notes:

• This function is not generally useful; it exists for the convenience of the printing system.

• Do not use if a CTextView object owns this CTextLayout object.

Parameters

TInt aStartDocPos A document position within the paragraph from which to begin formatting. TInt aEndDocPos Document position at which to end formatting.

TBool FormatNextLineL(TInt& aBotPixel);

Description

A special function to support background formatting by the higher level CTextView class. It formats the next pending line. The return value is true if there is more formatting to do. On entry, aBotPixel contains the y coordinate of the bottom of the formatted text; this is updated by the function.

Notes:

• Not generally useful.

• Do not use if a CTextView object owns this CTextLayout object.

Parameters

TInt& aBotPixel On entry, contains the y coordinate of the bottom of the formatted text; this is updated by the function.

Return value

TBool True if there is more formatting to do. False if not.

TBool FormatLineL(CParaFormat* aParaFormat,TInt& aDocPos,TInt& aHeight,TBool& aPageBreak);

Description

Controls the height of a single line, for use by the pagination system only. Using the format supplied in aParaFormat, determines the height of the line containing aDocPos and returns it in aHeight. Changes aDocPos to the end of the line and returns true if that position is not the end of the paragraph.

Notes:

• Not generally useful; it exists for use by the pagination system only.

• Do not use if a CTextView object owns this CTextLayout object.

Parameters

CParaFormat* aParaFormat Contains paragraph formatting. TInt& aDocPos A document position. On return, contains the document position of the end of the line. TInt& aHeight On return, contains the height of the formatted line containing aDocPos. TBool& aPageBreak On return, true if the last character on the line is a page break. False if not.

Return value

TBool True if the line is not the last line in the paragraph. False if it is the last line.

TInt ScrollParagraphsL(TInt& aNumParas,TAllowDisallow aScrollBlankSpace);

Description

Scrolls the text up or down by aNumParas paragraphs, disallowing blank space at the bottom of the visible area if aScrollBlankSpace is CTextLayout::EFDisallowScrollingBlankSpace.

Do not use if a CTextView object owns this CTextLayout object.

Parameters

TInt& aNumParas The number of paragraphs to scroll; may be a positive or negative value. On return, contains the number of paragraphs not scrolled; that is the difference between the requested number and the number of paragraphs actually scrolled. 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 actually scrolled.

TInt ScrollLinesL(TInt& aNumLines, TAllowDisallow aScrollBlankSpace=EFDisallowScrollingBlankSpace);

Description

Scrolls the text up or down by aNumLines lines, disallowing blank space at the bottom of the visible area if aScrollBlankSpace is CTextLayout::EFDisallowScrollingBlankSpace.

Do not use if a CTextView object owns this CTextLayout object.

Parameters

TInt& aNumLines The number of lines to scroll; may be a positive or negative value. On return, contains the number of lines not scrolled; that is, the requested number, minus the number actually scrolled. TAllowDisallow aScrollBlankSpace=EFDisallowScrollingBlankSpace 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 actually scrolled.

TInt ChangeBandTopL(TInt& aPixels,TAllowDisallow aScrollBlankSpace=EFDisallowScrollingBlankSpace);

Description

Scrolls the text up or down by aPixels pixels, disallowing blank space at the bottom of the visible area if aScrollBlankSpace is CTextLayout::EFDisallowScrollingBlankSpace.

The return value (not aPixels, as you would expect from ScrollParagraphsL() and ScrollLinesL()) contains the number of pixels not successfully scrolled, that is, the original value of aPixels, minus the number of pixels actually scrolled. On return, aPixels is set to the number of pixels actually scrolled.

Do not use if a CTextView object owns this CTextLayout object.

Parameters

TInt& aPixels The number of pixels to scroll; may be a positive or negative value. On return, contains the number of pixels actually scrolled. TAllowDisallow aScrollBlankSpace=EFDisallowScrollingBlankSpace 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 difference between the requested number of pixels to scroll and the number of pixels actually scrolled.

void PageUpL(TInt& aYCursorPos,TInt& aPixelsScrolled);

Description

Scrolls up by a page (that is the band height as set by SetBandHeight(), or half that amount if scrolling over lines taller than this), moving the text downwards. The current desired vertical cursor position is passed in aYCursorPos and updated to a new suggested position as near as possible to it, but within the visible text and on a baseline.

Do not use if a CTextView object owns this CTextLayout object.

Parameters

TInt& aYCursorPos The current desired vertical cursor position. On return, updated to a new suggested position as near as possible to it. TInt& aPixelsScrolled On return, contains the number of pixels scrolled.

void PageDownL(TInt& aYCursorPos,TInt& aPixelsScrolled);

Description

Scrolls down by a page (that is the band height as set by SetBandHeight(), or half that amount if scrolling over lines taller than this), moving the text upwards. The current desired vertical cursor position is passed in aYCursorPos and updated to a new suggested position as near as possible to it, but within the visible text and on a baseline.

Do not use if a CTextView object owns this CTextLayout object.

Parameters

TInt& aYCursorPos The current desired vertical cursor position. On return, updated to a new suggested position as near as possible to it. TInt& aPixelsScrolled On return, contains the number of pixels scrolled — a negative value.

TInt SetViewL(TInt aDocPos,TInt& aYPos,TViewYPosQualifier aYPosQualifier, TDiscard aDiscardFormat=EFViewDontDiscardFormat);

Description

Changes the top of the visible area so that the line containing aDocPos is vertically positioned at aYPos. Which part of the line is set to appear at aYPos (top, baseline, or bottom) is controlled by the TViewYPosQualifier argument, which also specifies whether the visible area is to be filled and whether the line should be made fully visible if possible.

Do not use if a CTextView object owns this CTextLayout object.

Parameters

TInt aDocPos A valid document position. TInt& aYPos The y coordinate at which to display the character at aDocPos. On return, contains the actual vertical position of the specified part of the line. TViewYPosQualifier aYPosQualifier Controls which part of the line is set to appear at aYPos. TDiscard aDiscardFormat If true (EFViewDiscardAllFormat), the text is reformatted to include aDocPos, otherwise text is formatted only as necessary when bringing new lines into the visible area.

Return value

TInt 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, and so there is no point in blitting text; a full redraw is needed.

TBool HandleCharEditL(TUint aType,TInt& aCursorPos,TInt& aGood,TInt& aFormattedUpTo,TInt& aFormattedFrom,TInt& aScroll,TBool aFormatChanged);

Description

Reformats to reflect a single character edit.

Do not use if a CTextView object owns this CTextLayout object.

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 document position. TInt& aCursorPos The document position at which the edit took place, before the edit. If this position is not formatted, a panic occurs; it is modified in accordance with the edit. TInt& aGood On return, the y coordinate of the top of the paragraph following the paragraph which has been edited, before the edit. TInt& aFormattedUpTo On return, the y coordinate of the bottom of the reformatted line or lines, after the edit. TInt& aFormattedFrom On return, the vertical layout coordinate of the top of the reformatted line or lines, after the edit. TInt& aScroll The number of pixels by which the text had to be scrolled (positive means text moved down). 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

TBool False if no more lines need to be reformatted. True if some more lines need to be reformatted.

void HandleBlockChangeL(TCursorSelection aSelection,TInt aOldCharsChanged,TViewRectChanges& aViewChanges,TBool aFormatChanged);

Description

Reformats to reflect changes to a block of text.

Do not use if a CTextView object owns this CTextLayout object.

Parameters

TCursorSelection aSelection The start and new length of the changed block. When inserting, specify the insertion position. When deleting, specify the position of the start of the deletion. When reformatting, specify the start and length of the reformatted block. TInt aOldCharsChanged The old length of the changed block. When inserting, specify zero. When deleting, specify the number of deleted characters. When reformatting, specify the number of reformatted characters. TViewRectChanges& aViewChanges On return, contains the top of the reformatted text (iFormattedFrom), the bottom of the reformatted text (iFormattedTo), the amount by which the text above the reformatted text has scrolled (iScrollAtTop) and the amount by which the text below the reformatted text has scrolled (iScrollAtBottom) (positive values mean the text moves down). TBool aFormatChanged Indicates whether the paragraph format for the first or last affected paragraph has changed, meaning that the text to be reformatted must extend out to paragraph boundaries and cannot be restricted to only some lines.

void HandleAdditionalCharactersAtEndL(TInt& aFirstPixel,TInt& aLastPixel);

Description

Reformats to reflect the addition of one or more complete paragraphs at the end of the text.

Do not use if a CTextView object owns this CTextLayout object.

Parameters

TInt& aFirstPixel On return, the top y coordinate of the added material. TInt& aLastPixel On return, the bottom y coordinate of the added material.

void ReformatVerticalSpaceL();

Description

Reformats to reflect changes to the space above and below paragraphs (CParaFormat::iSpaceBeforeInTwips and iSpaceAfterInTwips).

Do not use if a CTextView object owns this CTextLayout object.

void AdjustVerticalAlignment(CParaFormat::TAlignment aVerticalAlignment);

Description

Temporarily changes the vertical alignment of the text with respect to the visible height.

Notes:

• Not generally useful; intended for the Agenda application.

• Do not use if a CTextView object owns this CTextLayout object.

Parameters

CParaFormat::TAlignment aVerticalAlignment Specifies whether the formatted text should be placed at the top (CParaFormat::ETopAlign), vertical centre (CParaFormat::ECenterAlign or CParaFormat::EJustifiedAlign) or bottom (CParaFormat::EBottomAlign) of the band. CParaFormat::EUnspecifiedAlign or CParaFormat::ECustomAlign may also be specified. These values cause the baseline of the first formatted line to be positioned 82% of the way down the band (provided for the Agenda's application's year view).

static void DrawBorders(const MGraphicsDeviceMap* aGd,CGraphicsContext& aGc,const TRect& aRect, const TParaBorderArray& aBorder,const TRgb* aBackground=NULL,TRegion *aClipRegion=NULL,const TRect* aDrawRect=NULL);

Description

Draws paragraph borders, optionally with a background colour for the border and a clip region. Provided for applications that display a menu of border styles, like a wordprocessor.

Parameters

const MGraphicsDeviceMap* aGd Provides twip-to-pixel conversion. CGraphicsContext& aGc Graphics context to which to draw the border. Its pen settings are overridden by the values specified by aBorder and its draw mode is set to CGraphicsContext::EDrawModePEN. const TRect& aRect The outer bounds of the border. const TParaBorderArray& aBorder Specifies the four sides of the border. const TRgb* aBackground If not null, the background colour, (used between double border lines, or between dots or dashes). TRegion *aClipRegion If non-null, specifies a clip region. const TRect* aDrawRect If non-null, and if aClipRegion is non-null, specifies a rectangle to be subtracted from the clip region.

void DrawL(const TRect& aDrawRect,const TDrawTextLayoutContext* aDrawTextLayoutContext,const TCursorSelection* aHighlight=NULL);

Description

Draws the text. Draws any lines that intersect aDrawRect, which is specified in window coordinates. The drawing parameters, including the graphics context, are given in aDrawTextLayoutContext. If aHighlight is non-null, highlights (by exclusive-ORing) the specified range of text.

Parameters

const TRect& aDrawRect The function draw the lines within the visible area, which intersect this rectangle (which is specified in window coordinates). const TDrawTextLayoutContext* aDrawTextLayoutContext Provides a graphics context and other parameters for the function. const TCursorSelection* aHighlight=NULL If not NULL, this range of text is drawn highlighted.

void InvertRangeL(const TCursorSelection& aHighlight,const TRect& aDrawRect,const TDrawTextLayoutContext* aDrawTextLayoutContext);

Description

Toggles the range of text in aHighlight by exclusive-ORing. Highlights only those lines that intersect aDrawRect, which is specified in window coordinates. The drawing parameters, including the graphics context, are given in aDrawTextLayoutContext.

Parameters

const TCursorSelection& aHighlight The range of characters for which to invert the highlighting. const TRect& aDrawRect Only lines which intersect this rectangle are affected (it is specified in window coordinates). const TDrawTextLayoutContext* aDrawTextLayoutContext Provides a graphics context and other parameters for the function.

void SetCustomDraw(const MFormCustomDraw* aCustomDraw);

Support

Supported from 6.0

Description

Sets the custom drawing object, for customising the way text and its background are drawn.

Parameters

const MFormCustomDraw* aCustomDraw Pointer to a custom drawing object.

const MFormCustomDraw* CustomDraw() const;

Support

Supported from 6.0

Description

Returns a pointer to the current custom drawing implementation. Returns NULL if custom drawing is not in force.

Return value

MFormCustomDraw* Pointer to the custom drawing object.

Anonymous

Description

Amount of vertical scroll. Used by CTextLayout::SetViewL().

EFScrollRedrawWholeScreen A value greater than any possible display height — indicates that the entire visible area, at least, was scrolled, and so there is no point in blitting text; a full redraw is needed.

Anonymous

Description

Maximum line width.

EFMaximumLineWidth The maximum line width when wrapping is unset.

TCurrentFormat

Description

Formatting information.

EFNoCurrentFormat Returned by some CTextLayout enquiry functions to indicate that no formatting has taken place so that the requested value cannot be calculated. EFNotInCurrentFormat Returned by CTextLayout::ParagraphHeight() when the paragraph is not formatted.

TDiscard

Description

Flags used by CTextLayout::SetViewL().

EFViewDiscardAllFormat Discard all the formatting. EFViewDontDiscardFormat Do not discard formatting until it is known that it is not needed.

Anonymous

Description

Flags used by CTextView::HandleCharEditL().

EFCharacterInsert Insert a character, (not a paragraph delimiter). EFParagraphDelimiter Insert a paragraph delimiter. EFLeftDelete Delete single character to the left. EFRightDelete Delete single character to the right.

TAmountFormatted

Description

Amount to format.

Used by CTextLayout::SetAmountToFormat().

EFFormatAllText Format the whole document. EFFormatBand Format the visible band only.

TAllowDisallow

Description

Indicates whether blank space should scroll.

Used by several CTextView and CTextLayout scrolling functions.

EFAllowScrollingBlankSpace Allow blank space to scroll. EFDisallowScrollingBlankSpace Disallow blank space from scrolling.

Anonymous

Description

Indicates whether wrapping should be forced on or off. Used by CTextLayout::ForceNoWrapping().

EFAllParagraphsNotWrapped Wrapping off; overrides the paragraph format. EFParagraphsWrappedByDefault Wrapping on, unless CParaFormat::iWrap is false.

Anonymous

Description

Flags used by CTextLayout::XyPosToDocPosL() and DocPosToXyPosL().

EFIndividualChars Convert coordinates to nearest character. EFWholeLinesOnly Convert coordinates to start or end of line.