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 TPtrCChooseScalableText(const TDesC &, const CFont &, TInt)
IMPORT_C voidChopToArrayAndClipL(TDes &, const CArrayFix< TInt > &, const CFont &, CArrayFix< TPtrC > &)
IMPORT_C voidChopToArrayAndClipL(TDes &, TInt, const CFont &, CArrayFix< TPtrC > &)
voidChopToArrayAndClipL(TDes &, const CArrayFix< TInt > *, const CFont &, CArrayFix< TPtrC > &, TInt)
IMPORT_C HBufC *ClipAccordingScreenOrientationLC(CCoeEnv &, HBufC *)
IMPORT_C TBoolClipToFit(TDes &, const CFont &, TInt, TClipDirection, TInt, const TDesC &)
IMPORT_C TBoolClipToFit(TDes &, TClipDirection, CEikFormattedCellListBox *, TInt, TInt)
IMPORT_C TBoolClipToFit(TDes &, TClipDirection, CEikColumnListBox *, TInt, TInt)
IMPORT_C voidConvertDigitsTo(TDes &, TDigitType)
IMPORT_C HBufC *ConvertFileNameL(const TDesC &)
IMPORT_C TBidiText::TDirectionalityCurrentScriptDirectionality()
IMPORT_C TBoolDigitModeQuery(TDigitModeQueryType)
TDigitType DisplayTextLanguageFilteredDigitType()
IMPORT_C voidDisplayTextLanguageSpecificNumberConversion(TDes &)
TBool DoClipToFit(TDes &, const CFont &, TInt, TClipDirection, TInt, const TDesC &)
TDigitType InputLanguageFilteredDigitType()
TBool IsEmptyText(const TDesC &)
IMPORT_C voidLanguageSpecificNumberConversion(TDes &)
IMPORT_C TIntLoadScalableText(CCoeEnv &, TInt, TDes &)
IMPORT_C HBufC *LoadScalableTextL(CCoeEnv &, TInt)
IMPORT_C HBufC *LoadScalableTextLC(CCoeEnv &, TInt)
IMPORT_C TDigitTypeNumericEditorDigitType()
IMPORT_C voidPackWhiteSpaces(TDes &, const TDesC &)
IMPORT_C voidReplaceCharacters(TDes &, const TDesC &, TChar)
IMPORT_C voidStripCharacters(TDes &, const TDesC &)
IMPORT_C TDigitTypeTextEditorDigitType()
IMPORT_C voidWrapToArrayAndClipL(TDes &, const CArrayFix< TInt > &, const CFont &, CArrayFix< TPtrC > &)
IMPORT_C voidWrapToArrayL(const TDesC &, const CArrayFix< TInt > &, const CFont &, CArrayFix< TPtrC > &)
IMPORT_C voidWrapToArrayL(const TDesC &, TInt, const CFont &, CArrayFix< TPtrC > &)
voidWrapToArrayL(TDes &, const CArrayFix< TInt > *, const CFont &, CArrayFix< TPtrC > &, TInt, TInt, TInt)
IMPORT_C voidWrapToStringAndClipL(const TDesC &, const CArrayFix< TInt > &, const CFont &, TDes &)
IMPORT_C voidWrapToStringL(const TDesC &, const CArrayFix< TInt > &, const CFont &, TDes &)
voidWrapToStringL(const TDesC &, const CArrayFix< TInt > &, const CFont &, TDes &, TInt, TInt)
Public Member Enumerations
enumTClipDirection { EDoNotClip, EClipFromEnd, EClipFromBeginning }
enumTDigitModeQueryType { EDigitModeEditorDefault, EDigitModeUserModifiableEditor, EDigitModeShownToUser, EDigitModeNumberEditor, EDigitModeLatinNumberEditor }

Member Functions Documentation

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

IMPORT_C TPtrCChooseScalableText(const TDesC &aText,
const CFont &aFont,
TIntaMaxWidthInPixels
)[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 & aTextText 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 & aFontFont used to render the text.
TInt aMaxWidthInPixelsMax width in pixels.

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

IMPORT_C voidChopToArrayAndClipL(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 & aStringToChopString that needs to be chopped
const CArrayFix< TInt > & aLineWidthArrayLine widths in pixels
const CFont & aFontUsed font
CArrayFix< TPtrC > & aChoppedArrayPointers to chopped lines

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

IMPORT_C voidChopToArrayAndClipL(TDes &aStringToChop,
TIntaLineWidth,
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 & aStringToChopString that needs to be chopped
TInt aLineWidthConstant line width in pixels
const CFont & aFontUsed font
CArrayFix< TPtrC > & aChoppedArrayPointers to chopped lines

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

voidChopToArrayAndClipL(TDes &aStringToChop,
const CArrayFix< TInt > *aLineWidthArray,
const CFont &aFont,
CArrayFix< TPtrC > &aChoppedArray,
TIntaLineWidth
)[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 TBoolClipToFit(TDes &aBuffer,
const CFont &aFont,
TIntaMaxWidthInPixels,
TClipDirectionaDir = EClipFromEnd,
TIntaClipWidth =  KDefaultClipWidth ,
const TDesC &aClipString = _L("...")
)[static]

ClipToFit() Generic clipping

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

Parameters

TDes & aBufferString that needs to be clipped. will be modified by this call
const CFont & aFontFont used in the code
TInt aMaxWidthInPixelsMaximum length of text that will not be clipped.
TClipDirection aDir = EClipFromEndWhere 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 TBoolClipToFit(TDes &aBuffer,
TClipDirectionaDir,
CEikFormattedCellListBox *aListBox,
TIntaItemIndex,
TIntaSubCellNumber
)[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 TBoolClipToFit(TDes &aBuffer,
TClipDirectionaDir,
CEikColumnListBox *aListBox,
TIntaItemIndex,
TIntaColumnNumber
)[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 voidConvertDigitsTo(TDes &aDes,
TDigitTypeaDigitType
)[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 & aDesParameter to change. It can contain digits from several digit types.
TDigitType aDigitTypeDestination 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 & aDescontains the file name in logical format.

CurrentScriptDirectionality()

IMPORT_C TBidiText::TDirectionalityCurrentScriptDirectionality()[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 TBoolDigitModeQuery(TDigitModeQueryTypeaQueryType = 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 = EDigitModeShownToUserwhat 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 voidDisplayTextLanguageSpecificNumberConversion(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 & aDesParameter to change

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

TBool DoClipToFit(TDes &aBuffer,
const CFont &aFont,
TIntaMaxWidthInPixels,
TClipDirectionaDir,
TIntaClipWidth,
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 voidLanguageSpecificNumberConversion(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 & aDesParameter to change

LoadScalableText(CCoeEnv &, TInt, TDes &)

IMPORT_C TIntLoadScalableText(CCoeEnv &aCoe,
TIntaResourceId,
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,
TIntaResourceId
)[static]

Do not use. This method will be removed.

Parameters

CCoeEnv & aCoe
TInt aResourceId

LoadScalableTextLC(CCoeEnv &, TInt)

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

Do not use. This method will be removed.

Parameters

CCoeEnv & aCoe
TInt aResourceId

NumericEditorDigitType()

IMPORT_C TDigitTypeNumericEditorDigitType()[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 voidPackWhiteSpaces(TDes &aDes,
const TDesC &aWhiteSpaceChars
)[static]

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

Parameters

TDes & aDesParameter to change
const TDesC & aWhiteSpaceChars

ReplaceCharacters(TDes &, const TDesC &, TChar)

IMPORT_C voidReplaceCharacters(TDes &aDes,
const TDesC &aChars,
TCharaReplacement
)[static]

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

KAknReplaceTabs KAknReplaceListControlChars ('s and 's)

Parameters

TDes & aDesParameter to change
const TDesC & aChars
TChar aReplacementa character used as replacement

StripCharacters(TDes &, const TDesC &)

IMPORT_C voidStripCharacters(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 & aDesParameter to change
const TDesC & aCharactersA set of characters to remove

TextEditorDigitType()

IMPORT_C TDigitTypeTextEditorDigitType()[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 voidWrapToArrayAndClipL(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 & aStringToWrapString that needs to be wrapped
const CArrayFix< TInt > & aLineWidthArrayLine widths in pixels
const CFont & aFontUsed font
CArrayFix< TPtrC > & aWrappedArrayPointers to wrapped lines

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

IMPORT_C voidWrapToArrayL(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 & aStringToWrapString that needs to be wrapped
const CArrayFix< TInt > & aLineWidthArrayLine widths in pixels
const CFont & aFontUsed font
CArrayFix< TPtrC > & aWrappedArrayPointers to wrapped lines

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

IMPORT_C voidWrapToArrayL(const TDesC &aStringToWrap,
TIntaLineWidth,
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 & aStringToWrapString that needs to be wrapped
TInt aLineWidthConstant line width in pixels
const CFont & aFontUsed font
CArrayFix< TPtrC > & aWrappedArrayPointers to wrapped lines

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

voidWrapToArrayL(TDes &aStringToWrap,
const CArrayFix< TInt > *aLineWidthArray,
const CFont &aFont,
CArrayFix< TPtrC > &aWrappedArray,
TIntaLineWidth,
TIntaFlags,
TIntaDirectionality
)[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 voidWrapToStringAndClipL(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 & aStringToWrapString that needs to be wrapped
const CArrayFix< TInt > & aLineWidthArrayWidth of lines in pixels
const CFont & aFontUsed font
TDes & aWrappedStringWrapped string

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

IMPORT_C voidWrapToStringL(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 & aStringToWrapString that needs to be wrapped
const CArrayFix< TInt > & aLineWidthArrayLines widths in pixels
const CFont & aFontUsed font
TDes & aWrappedStringWrapped string

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

voidWrapToStringL(const TDesC &aStringToWrap,
const CArrayFix< TInt > &aLineWidthArray,
const CFont &aFont,
TDes &aWrappedString,
TIntaFlags,
TIntaDirectionality
)[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