AknTextUtils Class Reference

class AknTextUtils

Text utilities. Text truncating and wrapping methods in this class do not support text that requires conversion from logical to visual form, e.g. Arabic/Hebrew, Thai and Hindi text. Code that needs to support that kind of text should use corresponding methods in AknBidiTextUtils instead.

Public Member Functions
IMPORT_C TPtrC ChooseScalableText (const TDesC &, const CFont &, TInt )
IMPORT_C void ChopToArrayAndClipL ( TDes &, const CArrayFix < TInt > &, const CFont &, CArrayFix < TPtrC > &)
IMPORT_C void ChopToArrayAndClipL ( TDes &, TInt , const CFont &, CArrayFix < TPtrC > &)
void ChopToArrayAndClipL ( TDes &, const CArrayFix < TInt > *, const CFont &, CArrayFix < TPtrC > &, TInt )
IMPORT_C HBufC * ClipAccordingScreenOrientationLC ( CCoeEnv &, HBufC *)
IMPORT_C TBool ClipToFit ( TDes &, const CFont &, TInt , TClipDirection , TInt , const TDesC &)
IMPORT_C TBool ClipToFit ( TDes &, TClipDirection , CEikFormattedCellListBox *, TInt , TInt )
IMPORT_C TBool ClipToFit ( TDes &, TClipDirection , CEikColumnListBox *, TInt , TInt )
IMPORT_C void ConvertDigitsTo ( TDes &, TDigitType )
IMPORT_C HBufC * ConvertFileNameL (const TDesC &)
IMPORT_C TBidiText::TDirectionality CurrentScriptDirectionality ()
IMPORT_C TBool DigitModeQuery ( TDigitModeQueryType )
TDigitType DisplayTextLanguageFilteredDigitType ()
IMPORT_C void DisplayTextLanguageSpecificNumberConversion ( TDes &)
TBool DoClipToFit ( TDes &, const CFont &, TInt , TClipDirection , TInt , const TDesC &)
TDigitType InputLanguageFilteredDigitType ()
TBool IsEmptyText (const TDesC &)
IMPORT_C void LanguageSpecificNumberConversion ( TDes &)
IMPORT_C TInt LoadScalableText ( CCoeEnv &, TInt , TDes &)
IMPORT_C HBufC * LoadScalableTextL ( CCoeEnv &, TInt )
IMPORT_C HBufC * LoadScalableTextLC ( CCoeEnv &, TInt )
IMPORT_C TDigitType NumericEditorDigitType ()
IMPORT_C void PackWhiteSpaces ( TDes &, const TDesC &)
IMPORT_C void ReplaceCharacters ( TDes &, const TDesC &, TChar )
IMPORT_C void StripCharacters ( TDes &, const TDesC &)
IMPORT_C TDigitType TextEditorDigitType ()
IMPORT_C void WrapToArrayAndClipL ( TDes &, const CArrayFix < TInt > &, const CFont &, CArrayFix < TPtrC > &)
IMPORT_C void WrapToArrayL (const TDesC &, const CArrayFix < TInt > &, const CFont &, CArrayFix < TPtrC > &)
IMPORT_C void WrapToArrayL (const TDesC &, TInt , const CFont &, CArrayFix < TPtrC > &)
void WrapToArrayL ( TDes &, const CArrayFix < TInt > *, const CFont &, CArrayFix < TPtrC > &, TInt , TInt , TInt )
IMPORT_C void WrapToStringAndClipL (const TDesC &, const CArrayFix < TInt > &, const CFont &, TDes &)
IMPORT_C void WrapToStringL (const TDesC &, const CArrayFix < TInt > &, const CFont &, TDes &)
void WrapToStringL (const TDesC &, const CArrayFix < TInt > &, const CFont &, TDes &, TInt , TInt )
Public Member Enumerations
enum TClipDirection { EDoNotClip , EClipFromEnd , EClipFromBeginning }
enum TDigitModeQueryType { EDigitModeEditorDefault , EDigitModeUserModifiableEditor , EDigitModeShownToUser , EDigitModeNumberEditor , EDigitModeLatinNumberEditor }

Member Functions Documentation

ChooseScalableText(const TDesC &, const CFont &, TInt)

IMPORT_C TPtrC ChooseScalableText ( const TDesC & aText,
const CFont & aFont,
TInt aMaxWidthInPixels
) [static]

Utility method used in scalable UI for choosing the longest fitting text variant. Truncating and wrapping methods in classes AknTextUtils and AknBidiTextUtils do the choice by themselves, so whenever they are used to process the text, it is not necessary to call this method.

Applications do not need to call this method if they pass their localized texts to Avkon's UI components.

Since
2.8
Longest fitting text. If none of the variants fits, the shortest one in pixels is returned.

Parameters

const TDesC & aText Text containing one or many variants with varying text widths, separated with the character 0x0001. The text is supposed to be in logical order.
const CFont & aFont Font used to render the text.
TInt aMaxWidthInPixels Max width in pixels.

ChopToArrayAndClipL(TDes &, const CArrayFix< TInt > &, const CFont &, CArrayFix< TPtrC > &)

IMPORT_C void ChopToArrayAndClipL ( TDes & aStringToChop,
const CArrayFix < TInt > & aLineWidthArray,
const CFont & aFont,
CArrayFix < TPtrC > & aChoppedArray
) [static]

Chops a string when a line break character is encountered. Clips at the end of each line if there isn't enough space on that line. When clipping, KEllipsis (shown as 3 dots) is inserted at the end of the line. The number of lines and line widths are specified by aLineWidthArray. The pointers in aChoppedArray point to positions inside aStringToChop.

Expect the string to be modified if clipping is needed (Clipping character KEllipsis is inserted in the end of the lines)

Parameters

TDes & aStringToChop String that needs to be chopped
const CArrayFix < TInt > & aLineWidthArray Line widths in pixels
const CFont & aFont Used font
CArrayFix < TPtrC > & aChoppedArray Pointers to chopped lines

ChopToArrayAndClipL(TDes &, TInt, const CFont &, CArrayFix< TPtrC > &)

IMPORT_C void ChopToArrayAndClipL ( TDes & aStringToChop,
TInt aLineWidth,
const CFont & aFont,
CArrayFix < TPtrC > & aChoppedArray
) [static]

Chops a string when a line break character is encountered. Clips at the end of each line if there isn't enough space on that line. When clipping, KEllipsis (shown as 3 dots) is inserted at the end of the line. Constant line width is given. The pointers in aChoppedArray point to positions inside aStringToChop.

Expect the string to be modified if clipping is needed (Clipping character KEllipsis is inserted in the end of the lines)

Parameters

TDes & aStringToChop String that needs to be chopped
TInt aLineWidth Constant line width in pixels
const CFont & aFont Used font
CArrayFix < TPtrC > & aChoppedArray Pointers to chopped lines

ChopToArrayAndClipL(TDes &, const CArrayFix< TInt > *, const CFont &, CArrayFix< TPtrC > &, TInt)

void ChopToArrayAndClipL ( TDes & aStringToChop,
const CArrayFix < TInt > * aLineWidthArray,
const CFont & aFont,
CArrayFix < TPtrC > & aChoppedArray,
TInt aLineWidth
) [static]

Parameters

TDes & aStringToChop
const CArrayFix < TInt > * aLineWidthArray
const CFont & aFont
CArrayFix < TPtrC > & aChoppedArray
TInt aLineWidth

ClipAccordingScreenOrientationLC(CCoeEnv &, HBufC *)

IMPORT_C HBufC * ClipAccordingScreenOrientationLC ( CCoeEnv & aCoe,
HBufC * aBuf
) [static]

Do not use. This method will be removed.

Parameters

CCoeEnv & aCoe
HBufC * aBuf

ClipToFit(TDes &, const CFont &, TInt, TClipDirection, TInt, const TDesC &)

IMPORT_C TBool ClipToFit ( TDes & aBuffer,
const CFont & aFont,
TInt aMaxWidthInPixels,
TClipDirection aDir = EClipFromEnd,
TInt aClipWidth =  KDefaultClipWidth ,
const TDesC & aClipString = _L("...")
) [static]

ClipToFit() Generic clipping

returns true if the text was clipped and 3 dots were added.

Parameters

TDes & aBuffer String that needs to be clipped. will be modified by this call
const CFont & aFont Font used in the code
TInt aMaxWidthInPixels Maximum length of text that will not be clipped.
TClipDirection aDir = EClipFromEnd Where is the text clipped from. EDoNotClip, EClipFromEnd, EClipFromBeginning.
TInt aClipWidth =  KDefaultClipWidth The length of the text after clipping. KDefaultClipWidth will make it use aMaxWidthInPixels.
const TDesC & aClipString = _L("...") The representation of three dots. (not really used anywhere - use the default value always or "")

ClipToFit(TDes &, TClipDirection, CEikFormattedCellListBox *, TInt, TInt)

IMPORT_C TBool ClipToFit ( TDes & aBuffer,
TClipDirection aDir,
CEikFormattedCellListBox * aListBox,
TInt aItemIndex,
TInt aSubCellNumber
) [static]

ClipToFit() for clipping text inside lists

NOTICE: This method cannot handle situation where the text may dynamically change its size! Especially when you have bitmaps on the right side!

This needs to be done AFTER the listbox has done its SizeChanged()!

Parameters

TDes & aBuffer
TClipDirection aDir
CEikFormattedCellListBox * aListBox
TInt aItemIndex
TInt aSubCellNumber

ClipToFit(TDes &, TClipDirection, CEikColumnListBox *, TInt, TInt)

IMPORT_C TBool ClipToFit ( TDes & aBuffer,
TClipDirection aDir,
CEikColumnListBox * aListBox,
TInt aItemIndex,
TInt aColumnNumber
) [static]

ClipToFit() for clipping text inside lists

NOTICE: This method cannot handle situation where the text may dynamically change its size! Especially when you have bitmaps on the right side!

This needs to be done AFTER the listbox has done its SizeChanged()!

Parameters

TDes & aBuffer
TClipDirection aDir
CEikColumnListBox * aListBox
TInt aItemIndex
TInt aColumnNumber

ConvertDigitsTo(TDes &, TDigitType)

IMPORT_C void ConvertDigitsTo ( TDes & aDes,
TDigitType aDigitType
) [static]

This routine is used to convert digits from any digit format to another format eg. from european digits to arabic-indic digits.

Since
2.0

Parameters

TDes & aDes Parameter to change. It can contain digits from several digit types.
TDigitType aDigitType Destination digit type.

ConvertFileNameL(const TDesC &)

IMPORT_C HBufC * ConvertFileNameL ( const TDesC & aDes ) [static]

Converts a filename ABCDE.EXT to format which is suitable for display. This method is needed for bi-directional language support. The method adds directionality markers to the filename so that the filename can correctly be rendered to screen.

Since
2.6

Parameters

const TDesC & aDes contains the file name in logical format.

CurrentScriptDirectionality()

IMPORT_C TBidiText::TDirectionality CurrentScriptDirectionality ( ) [static]

Convenience routine to obtain the directionality of the current input language This routine will attempt to access this information in a system-efficient way.

This is not to be confused with either the directionality of the display text language or (a closely associated concept) the layout direction of the UI (accessed via AknLayoutUtils::LayoutMirrored() )

Since
2.0

DigitModeQuery(TDigitModeQueryType)

IMPORT_C TBool DigitModeQuery ( TDigitModeQueryType aQueryType = EDigitModeShownToUser ) [static]

This routine can be used to check what modes digits can be on.

It uses input language, display language and the setting from general settings to calculate whether foreign digits need to be used.

This is useful for editor implementation and anyone that needs to convert digits for display.

Since
2.0

Parameters

TDigitModeQueryType aQueryType = EDigitModeShownToUser what is the situation where the digits are to be used.

DisplayTextLanguageFilteredDigitType()

TDigitType DisplayTextLanguageFilteredDigitType ( ) [static]

Method used to constrain the digit type to use to that consisted with the current display text language

Since
2.0

DisplayTextLanguageSpecificNumberConversion(TDes &)

IMPORT_C void DisplayTextLanguageSpecificNumberConversion ( TDes & aDes ) [static]

This routine is used to convert between arabic-indic digits and european digits. based on existing language setting. So it'll convert any digit from the string to use either european digits or arabic-indic digits based on current settings.

This routine builds in the constraints imposed by current display text languages.

The number of characters in the buffer is not changed by this routine. It can therefore be safely used easily with existing (modifiable) descriptors.

This method should only be used just before displaying the number as unicode descriptor. Never store the converted string.

Since
2.0

Parameters

TDes & aDes Parameter to change

DoClipToFit(TDes &, const CFont &, TInt, TClipDirection, TInt, const TDesC &)

TBool DoClipToFit ( TDes & aBuffer,
const CFont & aFont,
TInt aMaxWidthInPixels,
TClipDirection aDir,
TInt aClipWidth,
const TDesC & aClipString
) [static]

Parameters

TDes & aBuffer
const CFont & aFont
TInt aMaxWidthInPixels
TClipDirection aDir
TInt aClipWidth
const TDesC & aClipString

InputLanguageFilteredDigitType()

TDigitType InputLanguageFilteredDigitType ( ) [static]

Method used to constrain the digit type to use to that consisted with the current input language

Since
2.0

IsEmptyText(const TDesC &)

TBool IsEmptyText ( const TDesC & aTextToTest ) [static]

This utility is used to see if a text is empty according to the conventions of Avkon.

Parameters

const TDesC & aTextToTest

LanguageSpecificNumberConversion(TDes &)

IMPORT_C void LanguageSpecificNumberConversion ( TDes & aDes ) [static]

This routine is used to convert between arabic-indic digits and european digits. based on existing language setting. So it'll convert any digit from the string to use either european digits or arabic-indic digits based on current settings.

NOTE: THis method can be also called in european release. The method is required to do the correct thing with all the languages.

This method should only be used just before displaying the number as unicode string. Also, never store the converted string as unicode.

Since
2.0

Parameters

TDes & aDes Parameter to change

LoadScalableText(CCoeEnv &, TInt, TDes &)

IMPORT_C TInt LoadScalableText ( CCoeEnv & aCoe,
TInt aResourceId,
TDes & aBuffer
) [static]

Do not use. This method will be removed.

Parameters

CCoeEnv & aCoe
TInt aResourceId
TDes & aBuffer

LoadScalableTextL(CCoeEnv &, TInt)

IMPORT_C HBufC * LoadScalableTextL ( CCoeEnv & aCoe,
TInt aResourceId
) [static]

Do not use. This method will be removed.

Parameters

CCoeEnv & aCoe
TInt aResourceId

LoadScalableTextLC(CCoeEnv &, TInt)

IMPORT_C HBufC * LoadScalableTextLC ( CCoeEnv & aCoe,
TInt aResourceId
) [static]

Do not use. This method will be removed.

Parameters

CCoeEnv & aCoe
TInt aResourceId

NumericEditorDigitType()

IMPORT_C TDigitType NumericEditorDigitType ( ) [static]

Returns the digit type to be used for editors that are purely numeric in quality.

Since
2.0

PackWhiteSpaces(TDes &, const TDesC &)

IMPORT_C void PackWhiteSpaces ( TDes & aDes,
const TDesC & aWhiteSpaceChars
) [static]

This routine is used to remove extra whitespaces from text before showing on screen

Parameters

TDes & aDes Parameter to change
const TDesC & aWhiteSpaceChars

ReplaceCharacters(TDes &, const TDesC &, TChar)

IMPORT_C void ReplaceCharacters ( TDes & aDes,
const TDesC & aChars,
TChar aReplacement
) [static]

This routine is used to replace all control chars with a single character, usually a whitespace.

KAknReplaceTabs KAknReplaceListControlChars ('s and 's)

Parameters

TDes & aDes Parameter to change
const TDesC & aChars
TChar aReplacement a character used as replacement

StripCharacters(TDes &, const TDesC &)

IMPORT_C void StripCharacters ( TDes & aDes,
const TDesC & aCharacters
) [static]

This routine is used to strip away a set of characters from a descriptor.

Useful for example for listboxes to make sure strings from network or typed by the end user does not have tab or linefeed characters. (as those will make listbox broken.)

There exists predefined character sets to remove: KAknStripTabs KAknStripListControlChars ('s and 's and 's)

Parameters

TDes & aDes Parameter to change
const TDesC & aCharacters A set of characters to remove

TextEditorDigitType()

IMPORT_C TDigitType TextEditorDigitType ( ) [static]

Returns the digit type to be used for editors that are alphanumeric. (Note that these editors may be configurable to be purely numeric - that is have a numeric mode, but they remain alphanumeric editors for the sake of this API.)

This may be useful for instance for input processors that convert numeric key events to the currently set input digit type.

Since
2.0

WrapToArrayAndClipL(TDes &, const CArrayFix< TInt > &, const CFont &, CArrayFix< TPtrC > &)

IMPORT_C void WrapToArrayAndClipL ( TDes & aStringToWrap,
const CArrayFix < TInt > & aLineWidthArray,
const CFont & aFont,
CArrayFix < TPtrC > & aWrappedArray
) [static]

Wraps a string to an array of pointers and clips at the end of the last line if there aren't enough lines to accomodate the entire text. When clipping three dots are inserted at the end of the last line. The number of lines and line widths are specified by aLineWidthArray. The pointers in aWrappedArray point to positions inside aWrappedString.

Expect the string to be modified if clipping is needed. (Clipping character KEllipsis is inserted at the ending point)

Parameters

TDes & aStringToWrap String that needs to be wrapped
const CArrayFix < TInt > & aLineWidthArray Line widths in pixels
const CFont & aFont Used font
CArrayFix < TPtrC > & aWrappedArray Pointers to wrapped lines

WrapToArrayL(const TDesC &, const CArrayFix< TInt > &, const CFont &, CArrayFix< TPtrC > &)

IMPORT_C void WrapToArrayL ( const TDesC & aStringToWrap,
const CArrayFix < TInt > & aLineWidthArray,
const CFont & aFont,
CArrayFix < TPtrC > & aWrappedArray
) [static]

Wraps a string to an array of pointers. The number of lines and line widths are specified by aLineWidthArray. The pointers in aWrappedArray point to positions inside aWrappedString.

Parameters

const TDesC & aStringToWrap String that needs to be wrapped
const CArrayFix < TInt > & aLineWidthArray Line widths in pixels
const CFont & aFont Used font
CArrayFix < TPtrC > & aWrappedArray Pointers to wrapped lines

WrapToArrayL(const TDesC &, TInt, const CFont &, CArrayFix< TPtrC > &)

IMPORT_C void WrapToArrayL ( const TDesC & aStringToWrap,
TInt aLineWidth,
const CFont & aFont,
CArrayFix < TPtrC > & aWrappedArray
) [static]

Wraps a string to an array of pointers. Constant line width is given. The pointers in aWrappedArray point to positions inside aWrappedString.

Parameters

const TDesC & aStringToWrap String that needs to be wrapped
TInt aLineWidth Constant line width in pixels
const CFont & aFont Used font
CArrayFix < TPtrC > & aWrappedArray Pointers to wrapped lines

WrapToArrayL(TDes &, const CArrayFix< TInt > *, const CFont &, CArrayFix< TPtrC > &, TInt, TInt, TInt)

void WrapToArrayL ( TDes & aStringToWrap,
const CArrayFix < TInt > * aLineWidthArray,
const CFont & aFont,
CArrayFix < TPtrC > & aWrappedArray,
TInt aLineWidth,
TInt aFlags,
TInt aDirectionality
) [static]

Parameters

TDes & aStringToWrap
const CArrayFix < TInt > * aLineWidthArray
const CFont & aFont
CArrayFix < TPtrC > & aWrappedArray
TInt aLineWidth
TInt aFlags
TInt aDirectionality

WrapToStringAndClipL(const TDesC &, const CArrayFix< TInt > &, const CFont &, TDes &)

IMPORT_C void WrapToStringAndClipL ( const TDesC & aStringToWrap,
const CArrayFix < TInt > & aLineWidthArray,
const CFont & aFont,
TDes & aWrappedString
) [static]

Wraps a string (aStringToWrap) into lines according to the number of lines and line widths specified in aLineWidthArray. Inserts '' at the end of lines. Clips the last line if there aren't enough lines to fit the entire string. Copies the result into aWrappedString. Leaves if aWrappedString isn't big enough.

Parameters

const TDesC & aStringToWrap String that needs to be wrapped
const CArrayFix < TInt > & aLineWidthArray Width of lines in pixels
const CFont & aFont Used font
TDes & aWrappedString Wrapped string

WrapToStringL(const TDesC &, const CArrayFix< TInt > &, const CFont &, TDes &)

IMPORT_C void WrapToStringL ( const TDesC & aStringToWrap,
const CArrayFix < TInt > & aLineWidthArray,
const CFont & aFont,
TDes & aWrappedString
) [static]

Wraps a string (aStringToWrap) into lines according to the number of lines and line widths specified in aLineWidthArray. Inserts '' at the end of lines. Copies the result into aWrappedString. Leaves if aWrappedString isn't big enough.

Parameters

const TDesC & aStringToWrap String that needs to be wrapped
const CArrayFix < TInt > & aLineWidthArray Lines widths in pixels
const CFont & aFont Used font
TDes & aWrappedString Wrapped string

WrapToStringL(const TDesC &, const CArrayFix< TInt > &, const CFont &, TDes &, TInt, TInt)

void WrapToStringL ( const TDesC & aStringToWrap,
const CArrayFix < TInt > & aLineWidthArray,
const CFont & aFont,
TDes & aWrappedString,
TInt aFlags,
TInt aDirectionality
) [static]

Parameters

const TDesC & aStringToWrap
const CArrayFix < TInt > & aLineWidthArray
const CFont & aFont
TDes & aWrappedString
TInt aFlags
TInt aDirectionality

Member Enumerations Documentation

Enum TClipDirection

Enumerators

EDoNotClip
EClipFromEnd
EClipFromBeginning

Enum TDigitModeQueryType

Enumerators

EDigitModeEditorDefault
EDigitModeUserModifiableEditor
EDigitModeShownToUser
EDigitModeNumberEditor
EDigitModeLatinNumberEditor