Symbian^3 Application Developer Library >

CFont Class Reference

class CFont : public CBase

Abstract font interface.

The CFont class provides a device-independent interface to a device-dependent font usually obtained from a call to GetNearestFont...() on a graphics device. It is used as a handle in CGraphicsContext::UseFont() and to obtain device-dependent information about the font - notably the pixel width of a text string.

CFbsFont CGraphicsContext::UseFont()

Inherits from

Nested Classes and Structures

Public Member Functions
IMPORT_C TInt AscentInPixels ()
IMPORT_C TInt BaselineOffsetInPixels ()
IMPORT_C TInt CharWidthInPixels ( TChar )
IMPORT_C TBool CharactersJoin ( TInt , TInt )
IMPORT_C TInt DescentInPixels ()
IMPORT_C TInt ExtendedFunction ( TUid , TAny *)
TInt FontCapitalAscent ()
TInt FontLineGap ()
TInt FontMaxAscent ()
TInt FontMaxDescent ()
TInt FontMaxHeight ()
IMPORT_C TFontSpec FontSpecInTwips ()
TInt FontStandardDescent ()
IMPORT_C TCharacterDataAvailability GetCharacterData ( TUint , TOpenFontCharMetrics &, const TUint8 *&, TSize &)
IMPORT_C TBool GetCharacterPosition ( TPositionParam &)
IMPORT_C TBool GetCharacterPosition2 ( TPositionParam &, RShapeInfo &)
IMPORT_C TInt HeightInPixels ()
IMPORT_C TInt MaxCharWidthInPixels ()
IMPORT_C TInt MaxNormalCharWidthInPixels ()
IMPORT_C TInt MeasureText (const TDesC &, const TMeasureTextInput *, TMeasureTextOutput *)
IMPORT_C TInt TextCount (const TDesC &, TInt )
IMPORT_C TInt TextCount (const TDesC &, TInt , TInt &)
IMPORT_C TInt TextWidthInPixels (const TDesC &)
IMPORT_C TInt TextWidthInPixels (const TDesC &, const TMeasureTextInput *)
IMPORT_C TUid TypeUid ()
IMPORT_C TInt WidthZeroInPixels ()
Protected Member Functions
~CFont ()
IMPORT_C TInt DoExtendedFunction ( TUid , TAny *)
IMPORT_C TCharacterDataAvailability DoGetCharacterData ( TUint , TOpenFontCharMetrics &, const TUint8 *&, TSize &)
IMPORT_C TBool DoGetCharacterPosition ( TPositionParam &)
Private Member Functions
TInt DoAscentInPixels ()
TInt DoBaselineOffsetInPixels ()
TInt DoCharWidthInPixels ( TChar )
IMPORT_C TInt DoDescentInPixels ()
TFontSpec DoFontSpecInTwips ()
TInt DoHeightInPixels ()
TInt DoMaxCharWidthInPixels ()
TInt DoMaxNormalCharWidthInPixels ()
TInt DoTextCount (const TDesC &, TInt )
TInt DoTextCount (const TDesC &, TInt , TInt &)
TInt DoTextWidthInPixels (const TDesC &)
TUid DoTypeUid ()
Inherited Functions
CBase::CBase()
CBase::Delete(CBase *)
CBase::Extension_(TUint,TAny *&,TAny *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()
Public Member Enumerations
enum TCharacterDataAvailability { ENoCharacterData , ECharacterWidthOnly , EAllCharacterData }
enum TTextDirection { EHorizontal , EVertical }

Constructor & Destructor Documentation

~CFont()

IMPORT_C ~CFont ( ) [protected, virtual]

Default destructor.

Member Functions Documentation

AscentInPixels()

IMPORT_C TInt AscentInPixels ( ) const

Gets the font ascent in pixels. Note that this deprecated function is replaced by the new FontMaxAscent() or in some cases FontCapitalAscent() .

FontCapitalAscent() FontMaxAscent()

BaselineOffsetInPixels()

IMPORT_C TInt BaselineOffsetInPixels ( ) const

Gets the baseline offset in pixels.

The baseline offset is how far a font is raised or lowered from its normal baseline.

CharWidthInPixels(TChar)

IMPORT_C TInt CharWidthInPixels ( TChar aChar ) const

Gets the width in pixels in this font of the specified character.

Note: For OpenType fonts this function returns the horizontal advance of the character, which may be different from the actual width.

Parameters

TChar aChar The character whose width should be determined.

CharactersJoin(TInt, TInt)

IMPORT_C TBool CharactersJoin ( TInt aLeftCharacter,
TInt aRightCharacter
) [static]

Determines if aLeftCharacter and aRightCharacter affect each other's contextual glyph form if placed next to each other. If either character is a combining character, EFalse will be returned, which is not generally useful information. Pass in base characters ignoring intervening combining characters.

Parameters

TInt aLeftCharacter Unicode code for the character that stands on the left.
TInt aRightCharacter Unicode code for the character that stands on the right.

DescentInPixels()

IMPORT_C TInt DescentInPixels ( ) const

Gets the font descent in pixels. Note that this deprecated function is replaced by the new FontMaxDescent() or in some cases FontStandardDescent() .

FontStandardDescent() FontMaxDescent()

DoAscentInPixels()

TInt DoAscentInPixels ( ) const [private, pure virtual]

WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation.

DoBaselineOffsetInPixels()

TInt DoBaselineOffsetInPixels ( ) const [private, pure virtual]

WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation.

DoCharWidthInPixels(TChar)

TInt DoCharWidthInPixels ( TChar aChar ) const [private, pure virtual]

WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation.

Parameters

TChar aChar

DoDescentInPixels()

IMPORT_C TInt DoDescentInPixels ( ) const [private, virtual]

Gets the font descent in pixels. It is defined to be HeightInPixels() minus AscentInPixels() . Note that this deprecated function is replaced by the new FontMaxDescent() or in some cases FontStandardDescent() .

FontStandardDescent() FontMaxDescent()

DoExtendedFunction(TUid, TAny *)

IMPORT_C TInt DoExtendedFunction ( TUid aFunctionId,
TAny * aParam = NULL
) const [protected, virtual]

API extension system that enables the caller to access a particular API extension function. N.B. Any overload of this function in a derived class should call its immediate parent implementation for any extension function Uid that it does not recognize and handle.

Parameters

TUid aFunctionId
TAny * aParam = NULL Pointer to an arbitrary parameter block that can be used to provide and/or return information to/from the particular extension function, defaults to NULL.

DoFontSpecInTwips()

TFontSpec DoFontSpecInTwips ( ) const [private, pure virtual]

WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation.

DoGetCharacterData(TUint, TOpenFontCharMetrics &, const TUint8 *&, TSize &)

IMPORT_C TCharacterDataAvailability DoGetCharacterData ( TUint aCode,
TOpenFontCharMetrics & aMetrics,
const TUint8 *& aBitmap,
TSize & aBitmapSize
) const [protected, virtual]

Gets the character metrics for a character.

Parameters

TUint aCode The character code.
TOpenFontCharMetrics & aMetrics On return, contains the character bitmap.
const TUint8 *& aBitmap On return, this points to NULL.
TSize & aBitmapSize On return, this has a size of (0,0).

DoGetCharacterPosition(TPositionParam &)

IMPORT_C TBool DoGetCharacterPosition ( TPositionParam & aParam ) const [protected, virtual]

Overridable function innards of GetCharacterPosition and GetCharacterPosition2. It is generally not useful to override this function. GetCharacterPosition GetCharacterPosition2

Parameters

TPositionParam & aParam

DoHeightInPixels()

TInt DoHeightInPixels ( ) const [private, pure virtual]

WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation.

DoMaxCharWidthInPixels()

TInt DoMaxCharWidthInPixels ( ) const [private, pure virtual]

WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation.

DoMaxNormalCharWidthInPixels()

TInt DoMaxNormalCharWidthInPixels ( ) const [private, pure virtual]

WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation.

DoTextCount(const TDesC &, TInt)

TInt DoTextCount ( const TDesC & aText,
TInt aWidthInPixels
) const [private, pure virtual]

WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation.

Parameters

const TDesC & aText
TInt aWidthInPixels

DoTextCount(const TDesC &, TInt, TInt &)

TInt DoTextCount ( const TDesC & aText,
TInt aWidthInPixels,
TInt & aExcessWidthInPixels
) const [private, pure virtual]

WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation.

Parameters

const TDesC & aText
TInt aWidthInPixels
TInt & aExcessWidthInPixels

DoTextWidthInPixels(const TDesC &)

TInt DoTextWidthInPixels ( const TDesC & aText ) const [private, pure virtual]

WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation.

Parameters

const TDesC & aText

DoTypeUid()

TUid DoTypeUid ( ) const [private, pure virtual]

WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases. Please see derived class for implementation.

ExtendedFunction(TUid, TAny *)

IMPORT_C TInt ExtendedFunction ( TUid aFunctionId,
TAny * aParam = NULL
) const

Enables the caller to access a particular API extension function. N.B. Any overload of this function in a derived class should call its immediate parent implementation for any extension function UID that it does not recognize and handle.

Parameters

TUid aFunctionId UID of the required extension function
TAny * aParam = NULL Pointer to an arbitrary parameter block that can be used to provide and/or return information to/from the particular extension function, defaults to NULL.

FontCapitalAscent()

TInt FontCapitalAscent ( ) const [inline]

Gets the ascent of an ANSI capital letter in the font whether or not there are any ANSI capitals in the font.

FontLineGap()

TInt FontLineGap ( ) const [inline]

Gets the suggested line gap for the font. This is the recommended baseline to baseline distance between successive lines of text in the font.

FontMaxAscent()

TInt FontMaxAscent ( ) const [inline]

Gets the max ascent of any pre-composed glyph in the font. This will include accents or diacritics that form part of pre-composed glyphs. It is not guaranteed to cover the max ascent of composite glyphs that have to be created by a layout engine. This is also the recommended distance between the top of a text box and the baseline of the first line of text.

FontMaxDescent()

TInt FontMaxDescent ( ) const [inline]

Gets the max descent of any pre-composed glyph in the font. This will include accents or diacritics that form part of pre-composed glyphs. It is not guaranteed to cover the max descent of composite glyphs that have to be created by a layout engine.

FontMaxHeight()

TInt FontMaxHeight ( ) const [inline]

Gets the (positive) maximum height in pixels of the font. This may differ from the design height.

FontSpecInTwips()

IMPORT_C TFontSpec FontSpecInTwips ( ) const

Gets the font specification of this font in twips.

FontStandardDescent()

TInt FontStandardDescent ( ) const [inline]

Gets the descent of an ANSI descending character in the font. Whether or not there are any ANSI descenders in the font.

GetCharacterData(TUint, TOpenFontCharMetrics &, const TUint8 *&, TSize &)

IMPORT_C TCharacterDataAvailability GetCharacterData ( TUint aCode,
TOpenFontCharMetrics & aMetrics,
const TUint8 *& aBitmap,
TSize & aBitmapSize
) const

Gets the character metrics for a character.

Parameters

TUint aCode The character code.
TOpenFontCharMetrics & aMetrics On return, contains the character bitmap.
const TUint8 *& aBitmap On return, this points to NULL.
TSize & aBitmapSize On return, this has a size of (0,0).

GetCharacterPosition(TPositionParam &)

IMPORT_C TBool GetCharacterPosition ( TPositionParam & aParam ) const

Transforms one cluster of characters (base character plus combining marks, ligature or indic syllable) into one cluster of glyphs together with their positions. Repeated calls of this function (for the same input text) are considerably slower than repeated calls of GetCharacterPosition2 for Indic text (such as Hindi), as GetCharacterPosition2 can cache information between calls. GetCharacterPosition2

Parameters

TPositionParam & aParam Input and output parameters

GetCharacterPosition2(TPositionParam &, RShapeInfo &)

IMPORT_C TBool GetCharacterPosition2 ( TPositionParam & aParam,
RShapeInfo & aShapeInfo
) const

Takes Unicode text and produces the glyph cluster for the first character in that text plus any combining mark characters, or for the first indic syllable. It is responsible for contextual glyph selection, ligature creation and diacritic placement.

CFont::TPositionParam

Parameters

TPositionParam & aParam The input/output parameter of the text/glyph data for the algorithm.
RShapeInfo & aShapeInfo The function will cache "shaped" text (e.g. complex scripts such as Devanagari) here. aShapeInfo must be freshly-constructed or closed for each new piece of text in aParam.iText. If aParam.iText is unchanged between calls, aShapeInfo should be passed back in unchanged as well.

HeightInPixels()

IMPORT_C TInt HeightInPixels ( ) const

Gets the font height in pixels. Note that this deprecated function is replaced by the new FontMaxHeight() .

FontMaxHeight()

MaxCharWidthInPixels()

IMPORT_C TInt MaxCharWidthInPixels ( ) const

Gets the width in pixels of the widest character in this font.

MaxNormalCharWidthInPixels()

IMPORT_C TInt MaxNormalCharWidthInPixels ( ) const

Gets the width in pixels of the widest normal character in this font.

Normal characters include all character in a character set except non-alphabetic characters (e.g. the copyright symbol, or a block graphics symbol, for example).

MeasureText(const TDesC &, const TMeasureTextInput *, TMeasureTextOutput *)

IMPORT_C TInt MeasureText ( const TDesC & aText,
const TMeasureTextInput * aInput = NULL,
TMeasureTextOutput * aOutput = NULL
) const

Text measurement function.

This is a powerful text measurement function underlying all the other text measurement functions. It takes optional input and output parameter blocks, which may be null, and returns the advance width (change in pen position when drawn horizontally) of the text, or the advance height, if the text is drawn vertically.

Some of the functions that can be performed using this function are listed below. Many of them are used by the Text Views API to do its typographic layout.
panic
GDI 1 In debug builds only, if TMeasureTextInput::iStartInputChar is negative.

Parameters

const TDesC & aText The text to be measured.
const TMeasureTextInput * aInput = NULL The input block. This may be NULL.
TMeasureTextOutput * aOutput = NULL The output block. This may be NULL.

TextCount(const TDesC &, TInt)

IMPORT_C TInt TextCount ( const TDesC & aText,
TInt aWidthInPixels
) const

Gets how much of the specified descriptor can be displayed in this font without exceeding the specified width.

Note:

This function does not display any of the descriptor itself - it is used before display, to test whether the whole descriptor can be displayed.

Parameters

const TDesC & aText The descriptor.
TInt aWidthInPixels The available width for character display.

TextCount(const TDesC &, TInt, TInt &)

IMPORT_C TInt TextCount ( const TDesC & aText,
TInt aWidthInPixels,
TInt & aExcessWidthInPixels
) const

Gets how much of the specified descriptor can be displayed in this font without exceeding the specified width.

It also returns the excess width - defined as the specified available width minus the width of the portion of the descriptor which can be displayed without exceeding the available width.

Parameters

const TDesC & aText The descriptor.
TInt aWidthInPixels The available width for character display.
TInt & aExcessWidthInPixels The excess width after displaying the portion of the descriptor, in pixels.

TextWidthInPixels(const TDesC &)

IMPORT_C TInt TextWidthInPixels ( const TDesC & aText ) const

Gets the width in pixels of the specified descriptor when displayed in this font.

Parameters

const TDesC & aText The descriptor whose width should be determined.

TextWidthInPixels(const TDesC &, const TMeasureTextInput *)

IMPORT_C TInt TextWidthInPixels ( const TDesC & aText,
const TMeasureTextInput * aParam
) const

Gets the width in pixels of the specified descriptor when displayed in this font.

Parameters

const TDesC & aText The descriptor whose width should be determined.
const TMeasureTextInput * aParam Parameter block that controls how much of aText is measured

TypeUid()

IMPORT_C TUid TypeUid ( ) const

Gets run-time identity of the actual font type. This enables safe casting to a derived type.

For example, if the derived type is a CFbsFont, the return value is KCFbsFontUid. You would need to cast to a CFbsFont to get a character bounding box. Similarly, a CBitmapFont returns KCBitmapFontUidVal.

WidthZeroInPixels()

IMPORT_C TInt WidthZeroInPixels ( ) const

Gets the width of the zero character of this font in pixels.

This function is provided as the "0" character is roughly the average width of the characters of any font.

Member Enumerations Documentation

Enum TCharacterDataAvailability

Data availability flags.

Some fonts like printer fonts may only have width information and can return ECharacterWidthOnly to show this: the text drawing routines in CFont synthesize the rest of the data if necessary.

GetCharacterData()

Enumerators

ENoCharacterData

No font information available.

ECharacterWidthOnly

Width information only is available.

EAllCharacterData

All character data is available.

Enum TTextDirection

Text direction flags.

This enum is used in TMeasureTextInput and determines whether the text is drawn horizontally or vertically. Note: text is drawn vertically in some styles of Japanese, etc.

TMeasureTextInput

Enumerators

EHorizontal

Text is drawn horizontally. Text is drawn horizontally.

EVertical

Text is drawn vertically.

Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License v1.0.