AknTextUtils Class Reference

API published in: S60 1st Ed

Link against: avkon.lib eikcore.lib

Capability Information

Required Capabilities

None

#include <aknutils.h>

Detailed Description

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 Types
enum	TClipDirection { EDoNotClip, EClipFromEnd, EClipFromBeginning }
enum	TDigitModeQueryType { EDigitModeEditorDefault, EDigitModeUserModifiableEditor, EDigitModeShownToUser, EDigitModeNumberEditor, EDigitModeLatinNumberEditor }
Static Public Member Functions
static IMPORT_C TBool	ClipToFit (TDes &aBuffer, const CFont &aFont, TInt aMaxWidthInPixels, TClipDirection aDir=EClipFromEnd, TInt aClipWidth=KDefaultClipWidth, const TDesC &aClipString=_L("..."))
	ClipToFit() Generic clipping.
static IMPORT_C TBool	ClipToFit (TDes &aBuffer, TClipDirection aDir, CEikFormattedCellListBox *aListBox, TInt aItemIndex, TInt aSubCellNumber)
	ClipToFit() for clipping text inside lists.
static IMPORT_C TBool	ClipToFit (TDes &aBuffer, TClipDirection aDir, CEikColumnListBox *aListBox, TInt aItemIndex, TInt aColumnNumber)
	ClipToFit() for clipping text inside lists.
static TBool	DoClipToFit (TDes &aBuffer, const CFont &aFont, TInt aMaxWidthInPixels, TClipDirection aDir, TInt aClipWidth, const TDesC &aClipString)
static IMPORT_C void	WrapToArrayL (const TDesC &aStringToWrap, const CArrayFix< TInt > &aLineWidthArray, const CFont &aFont, CArrayFix< TPtrC > &aWrappedArray)
	Wraps a string to an array of pointers.
static IMPORT_C void	WrapToArrayL (const TDesC &aStringToWrap, TInt aLineWidth, const CFont &aFont, CArrayFix< TPtrC > &aWrappedArray)
	Wraps a string to an array of pointers.
static IMPORT_C void	WrapToArrayAndClipL (TDes &aStringToWrap, const CArrayFix< TInt > &aLineWidthArray, const CFont &aFont, CArrayFix< TPtrC > &aWrappedArray)
	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.
static IMPORT_C void	ChopToArrayAndClipL (TDes &aStringToChop, const CArrayFix< TInt > &aLineWidthArray, const CFont &aFont, CArrayFix< TPtrC > &aChoppedArray)
	Chops a string when a line break character is encountered.
static IMPORT_C void	ChopToArrayAndClipL (TDes &aStringToChop, TInt aLineWidth, const CFont &aFont, CArrayFix< TPtrC > &aChoppedArray)
	Chops a string when a line break character is encountered.
static IMPORT_C void	WrapToStringL (const TDesC &aStringToWrap, const CArrayFix< TInt > &aLineWidthArray, const CFont &aFont, TDes &aWrappedString)
	Wraps a string (aStringToWrap) into lines according to the number of lines and line widths specified in aLineWidthArray.
static IMPORT_C void	WrapToStringAndClipL (const TDesC &aStringToWrap, const CArrayFix< TInt > &aLineWidthArray, const CFont &aFont, TDes &aWrappedString)
	Wraps a string (aStringToWrap) into lines according to the number of lines and line widths specified in aLineWidthArray.
static IMPORT_C void	StripCharacters (TDes &aDes, const TDesC &aCharacters)
	This routine is used to strip away a set of characters from a descriptor.
static IMPORT_C void	ReplaceCharacters (TDes &aDes, const TDesC &aChars, TChar aReplacement)
	This routine is used to replace all control chars with a single character, usually a whitespace.
static IMPORT_C void	PackWhiteSpaces (TDes &aDes, const TDesC &aWhiteSpaceChars)
	This routine is used to remove extra whitespaces from text before showing on screen.
static void	WrapToStringL (const TDesC &aStringToWrap, const CArrayFix< TInt > &aLineWidthArray, const CFont &aFont, TDes &aWrappedString, TInt aFlags, TInt aDirectionality)
static void	WrapToArrayL (TDes &aStringToWrap, const CArrayFix< TInt > *aLineWidthArray, const CFont &aFont, CArrayFix< TPtrC > &aWrappedArray, TInt aLineWidth, TInt aFlags, TInt aDirectionality)
static void	ChopToArrayAndClipL (TDes &aStringToChop, const CArrayFix< TInt > *aLineWidthArray, const CFont &aFont, CArrayFix< TPtrC > &aChoppedArray, TInt aLineWidth)
static TBool	IsEmptyText (const TDesC &aTextToTest)
	This utility is used to see if a text is empty according to the conventions of Avkon.
static IMPORT_C void	LanguageSpecificNumberConversion (TDes &aDes)
	This routine is used to convert between arabic-indic digits and european digits.
static IMPORT_C void	ConvertDigitsTo (TDes &aDes, TDigitType aDigitType)
	This routine is used to convert digits from any digit format to another format eg.
static IMPORT_C TBidiText::TDirectionality	CurrentScriptDirectionality ()
	Convenience routine to obtain the directionality of the current input language This routine will attempt to access this information in a system-efficient way.
static TDigitType	InputLanguageFilteredDigitType ()
	Method used to constrain the digit type to use to that consisted with the current input language.
static TDigitType	DisplayTextLanguageFilteredDigitType ()
	Method used to constrain the digit type to use to that consisted with the current display text language.
static IMPORT_C TDigitType	NumericEditorDigitType ()
	Returns the digit type to be used for editors that are purely numeric in quality.
static IMPORT_C void	DisplayTextLanguageSpecificNumberConversion (TDes &aDes)
	This routine is used to convert between arabic-indic digits and european digits.
static IMPORT_C TDigitType	TextEditorDigitType ()
	Returns the digit type to be used for editors that are alphanumeric.
static IMPORT_C TBool	DigitModeQuery (TDigitModeQueryType aQueryType=EDigitModeShownToUser)
	This routine can be used to check what modes digits can be on.
static IMPORT_C HBufC *	ConvertFileNameL (const TDesC &aDes)
	Converts a filename ABCDE.EXT to format which is suitable for display.
static IMPORT_C HBufC *	LoadScalableTextL (CCoeEnv &aCoe, TInt aResourceId)
static IMPORT_C HBufC *	LoadScalableTextLC (CCoeEnv &aCoe, TInt aResourceId)
static IMPORT_C TInt	LoadScalableText (CCoeEnv &aCoe, TInt aResourceId, TDes &aBuffer)
static IMPORT_C HBufC *	ClipAccordingScreenOrientationLC (CCoeEnv &aCoe, HBufC *aBuf)
static IMPORT_C TPtrC	ChooseScalableText (const TDesC &aText, const CFont &aFont, TInt aMaxWidthInPixels)
	Utility method used in scalable UI for choosing the longest fitting text variant.

Member Enumeration Documentation

enum AknTextUtils::TClipDirection

Enumerator:

EDoNotClip
EClipFromEnd
EClipFromBeginning

enum AknTextUtils::TDigitModeQueryType

Enumerator:

EDigitModeEditorDefault
EDigitModeUserModifiableEditor
EDigitModeShownToUser
EDigitModeNumberEditor
EDigitModeLatinNumberEditor

Member Function Documentation

static IMPORT_C TPtrC AknTextUtils::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.

Parameters:

	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.
	aFont	Font used to render the text.
	aMaxWidthInPixels	Max width in pixels.

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

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

static IMPORT_C void AknTextUtils::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:

	aStringToChop	String that needs to be chopped
	aLineWidth	Constant line width in pixels
	aFont	Used font
	aChoppedArray	Pointers to chopped lines

static IMPORT_C void AknTextUtils::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:

	aStringToChop	String that needs to be chopped
	aLineWidthArray	Line widths in pixels
	aFont	Used font
	aChoppedArray	Pointers to chopped lines

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

Deprecated:: Do not use. This method will be removed.

static IMPORT_C TBool AknTextUtils::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()!

static IMPORT_C TBool AknTextUtils::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()!

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

ClipToFit() Generic clipping.

Parameters:

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

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

static IMPORT_C void AknTextUtils::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.

Parameters:

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

static IMPORT_C HBufC* AknTextUtils::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.

Parameters:

aDes

contains the file name in logical format.

Returns:: file name in logical format with needed directionality markers.

static IMPORT_C TBidiText::TDirectionality AknTextUtils::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() )

Returns:: TBidiText::ELeftToRight if the current input language is left to right TBidiText::ERightToLeft if the current input langauge is right to left

static IMPORT_C TBool AknTextUtils::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.

Parameters:

aQueryType

what is the situation where the digits are to be used.

Returns:: ETrue to indicate whether digit conversions need to be used.
EFalse to indicate that no conversion is needed.

static TDigitType AknTextUtils::DisplayTextLanguageFilteredDigitType ( ) [static]

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

Returns:: TDigitType consistent with the current input language

static IMPORT_C void AknTextUtils::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.

Parameters:

aDes

Parameter to change

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

static TDigitType AknTextUtils::InputLanguageFilteredDigitType ( ) [static]

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

Returns:: TDigitType consistent with the current input language

static TBool AknTextUtils::IsEmptyText ( const TDesC & aTextToTest ) [static]

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

Parameters:

aTextToTest

Returns:: ETrue if the text is empty according to Avkon

static IMPORT_C void AknTextUtils::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.

Parameters:

aDes

Parameter to change

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

Deprecated:: Do not use. This method will be removed.

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

Deprecated:: Do not use. This method will be removed.

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

Deprecated:: Do not use. This method will be removed.

static IMPORT_C TDigitType AknTextUtils::NumericEditorDigitType ( ) [static]

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

Returns:: TDigitType to use for purely numeric editors

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

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

Parameters:

	aDes	Parameter to change
	aWhiteSpaceCharacters	A set of whitespace characters to remove

static IMPORT_C void AknTextUtils::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.

Parameters:

	aDes	Parameter to change
	aCharacters	A set of characters to remove
	aReplacement	a character used as replacement

KAknReplaceTabs KAknReplaceListControlChars ('s and
's)

static IMPORT_C void AknTextUtils::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.)

Parameters:

	aDes	Parameter to change
	aCharacters	A set of characters to remove

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

static IMPORT_C TDigitType AknTextUtils::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.

Returns:: TDigitType to editors with alphanumeric capability

static IMPORT_C void AknTextUtils::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:

	aStringToWrap	String that needs to be wrapped
	aLineWidthArray	Line widths in pixels
	aFont	Used font
	aWrappedArray	Pointers to wrapped lines

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

static IMPORT_C void AknTextUtils::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:

	aStringToWrap	String that needs to be wrapped
	aLineWidth	Constant line width in pixels
	aFont	Used font
	aWrappedArray	Pointers to wrapped lines

static IMPORT_C void AknTextUtils::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:

	aStringToWrap	String that needs to be wrapped
	aLineWidthArray	Line widths in pixels
	aFont	Used font
	aWrappedArray	Pointers to wrapped lines

static IMPORT_C void AknTextUtils::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:

	aStringToWrap	String that needs to be wrapped
	aLineWidthArray	Width of lines in pixels
	aFont	Used font
	aWrappedString	Wrapped string

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

static IMPORT_C void AknTextUtils::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:

	aStringToWrap	String that needs to be wrapped
	aLineWidthArray	Lines widths in pixels
	aFont	Used font
	aWrappedString	Wrapped string

The documentation for this class was generated from the following file:

aknutils.h

AknTextUtils Class Reference

Capability Information

Detailed Description

Public Types

Static Public Member Functions

Member Enumeration Documentation

Member Function Documentation