Class CFont

class CFont : public CBase;

Description

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.

Derivation

• CBase - Base class for all classes to be instantiated on the heap

• CFont - Abstract font interface

Members

Defined in CFont:
AscentInPixels(), BaselineOffsetInPixels(), CharWidthInPixels(), CharactersJoin(), DescentInPixels(), DoDescentInPixels(), DoGetCharacterData(), EAllCharacterData, ECharacterWidthOnly, EHorizontal, ENoCharacterData, EVertical, ExtendedFunction(), FontCapitalAscent(), FontLineGap(), FontMaxAscent(), FontMaxDescent(), FontMaxHeight(), FontSpecInTwips(), FontStandardDescent(), GetCharacterData(), GetCharacterPosition2(), HeightInPixels(), MaxCharWidthInPixels(), MaxNormalCharWidthInPixels(), MeasureText(), TCharacterDataAvailability, TMeasureTextInput, TMeasureTextOutput, TPositionParam, TTextDirection, TextCount(), TextCount(), TextWidthInPixels(), TypeUid(), WidthZeroInPixels(), ~CFont()

Inherited from CBase:
Delete(), Extension_(), operator new()

See also:

• CGraphicsContext::UseFont()

protected: virtual IMPORT_C ~CFont();

Description

Default destructor.

private: virtual IMPORT_C TInt DoDescentInPixels() const;

Description

Gets the font descent in pixels. It is defined to be HeightInPixels() minus AscentInPixels().

Return value

TInt The font descent in pixels.

See also:

• FontStandardDescent()
• FontMaxDescent()

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

Description

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).

Return value

TCharacterDataAvailability ECharacterWidthOnly

inline TInt FontCapitalAscent() const;

Description

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

Return value

TInt The positive distance from the font baseline to the top of a standard ANSI capital letter

See also:

• AscentInPixels()

inline TInt FontMaxAscent() const;

Description

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.

Return value

TInt The positive distance from the font baseline to the top of the highest pre-composed glyph (including accents) above the baseline

See also:

• AscentInPixels()

inline TInt FontStandardDescent() const;

Description

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

Return value

TInt The positive distance from the font baseline to the bottom of the lowest ANSI descender

See also:

• DescentInPixels()

inline TInt FontMaxDescent() const;

Description

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.

Return value

TInt The positive distance from the font baseline to the bottom of the lowest pre-composed glyph (including accents) below the baseline

See also:

• DescentInPixels()

inline TInt FontLineGap() const;

Description

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

Return value

TInt The positive recommended gap between successive lines

inline TInt FontMaxHeight() const;

Description

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

Return value

TInt The maximum height of the font.

See also:

• HeightInPixels()

IMPORT_C TUid TypeUid() const;

Description

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.

Return value

TUid The font-type identifier.

IMPORT_C TInt HeightInPixels() const;

Description

Gets the font height in pixels.

Return value

TInt The font height in pixels.

See also:

• FontMaxHeight()

IMPORT_C TInt AscentInPixels() const;

Description

Gets the font ascent in pixels.

Return value

TInt The font ascent in pixels.

See also:

• FontCapitalAscent()
• FontMaxAscent()

IMPORT_C TInt DescentInPixels() const;

Description

Gets the font descent in pixels.

Return value

TInt The font descent in pixels.

See also:

• FontStandardDescent()
• FontMaxDescent()

IMPORT_C TInt CharWidthInPixels(TChar aChar) const;

Description

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

Parameters

TChar aChar The character whose width should be determined.

Return value

TInt The width in pixels of the specified character in this font.

IMPORT_C TInt TextWidthInPixels(const TDesC &aText) const;

Description

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.

Return value

TInt The width of the specified descriptor when displayed in this font, in pixels.

IMPORT_C TInt BaselineOffsetInPixels() const;

Description

Gets the baseline offset in pixels.

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

Return value

TInt Offset from normal baseline, in pixels.

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

Description

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.

Return value

TInt The number of characters which will be able to be displayed without exceeding the specified width. The count starts from the beginning of the descriptor.

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

Description

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.

Return value

TInt The number of characters which will be able to be displayed without exceeding the specified width. The count starts from the beginning of the descriptor.

IMPORT_C TInt MaxCharWidthInPixels() const;

Description

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

Return value

TInt The width of the maximum width character, in pixels.

IMPORT_C TInt MaxNormalCharWidthInPixels() const;

Description

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).

Return value

TInt The width of the maximum width normal character, in pixels.

IMPORT_C TFontSpec FontSpecInTwips() const;

Description

Gets the font specification of this font in twips.

Return value

TFontSpec The font specification of this font (in twips).

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

Description

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).

Return value

TCharacterDataAvailability ECharacterWidthOnly

IMPORT_C TInt WidthZeroInPixels() const;

Description

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.

Return value

TInt The width of the "0" character, in pixels.

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

Description

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.

• Get the advance width or advance height (return value). The advance width is the amount by which the pen advances when drawing the text horizontally, while the advance height is the amount by which the pen advances when drawing the text vertically.

• Measure some text in context, so that shaping behaviour (e.g. in Arabic) can be affected by what comes before and after the text. Do this using TMeasureTextInput::iStartInputChar and TMeasureTextInput::iEndInputChar to tell the function where to start and end in the supplied descriptor.

• Determine how much text fits a given size by setting TMeasureTextInput::iMaxAdvance or TMeasureTextInput::iMaxBounds.

• Specify letter spacing and word spacing using TMeasureTextInput::iCharJustNum, TMeasureTextInput::iCharJustExcess, TMeasureTextInput::iWordJustNum and TMeasureTextInput::iWordJustExcess.

• Get the number of characters drawn in TMeasureTextOutput::iChars when applying the various constraints in TMeasureTextInput.

• Get the number of glyphs drawn in TMeasureTextOutput::iGlyphs.

• Get the number of groups (formed by ligation or diacritic placement) in TMeasureTextOutput::iGroups. Groups are units of cursor movement: the cursor hops over a character-plus-accent group or an Arabic or other ligature in one go.

• Get the number of word spaces in TMeasureTextOutput::iSpaces.

• Get the bounds of the inked-in pixels in TMeasureTextOutput::iBounds.

• Get the size of the biggest glyph that would be drawn in TMeasureTextOutput::iMaxGlyphSize.

Parameters

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

Return value

TInt The advance width if the text is drawn horizontally or the advance height if the text is drawn vertically.

Panic codes

GDI 1 In debug builds only, if TMeasureTextInput::iStartInputChar is negative.

static IMPORT_C TBool CharactersJoin(TInt aLeftCharacter, TInt aRightCharacter);

Description

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.

Return value

TBool EFalse if the characters do not affect the contextual glyphs that are be chosen when the two are rendered together, compared to being separated (for example by a space).

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

Description

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 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.

Return value

TInt Integer return value from extension function

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

Description

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.

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.

Return value

TBool ETrue if glyphs for supplied text have been produced, EFalse in failure.

See also:

• CFont::TPositionParam

class TPositionParam;

Description

Complicated parameter block used for contextual glyph selection, ligature creation and diacritic placement when drawing text in complex scripts

This class declares a constructor, another scoped class, and several other enums. However this class is unlikely to be useful to third party developers.

Members

Defined in CFont::TPositionParam:
EFLogicalOrder, EMaxInputChars, EMaxOutputGlyphs, TFlags, TOutput, TPositionParam(), anonymous, iDirection, iFlags, iOutput, iOutputGlyphs, iPen, iPosInText, iText

See also:

• CFont::GetCharacterPosition2()

Construction and destruction

---

TPositionParam()

inline TPositionParam();

Description

Standard constructor.

Member classes

---

Class TOutput

class TOutput;

Description

Output of GetCharacterPosition and GetCharacterPosition2.

Members

Defined in CFont::TPositionParam::TOutput:
TOutput(), iBitmap, iBitmapSize, iBounds, iCode

Construction and destruction

---

TOutput()

inline TOutput();

Description

Standard constructor.

Member data

---

iCode

TUint iCode;

Description

Character or glyph code.

---

iBitmap

const TUint8 * iBitmap;

Description

Bitmap data for the glyph, if available

---

iBitmapSize

TSize iBitmapSize;

Description

Size of the bitmap before algorithmic bolding, size multiplication, etc.

---

iBounds

TRect iBounds;

Description

Bitmap bounds relative to the original pen position.

Member enumerations

---

Enum anonymous

n/a

Description

EMaxInputChars EMaxOutputGlyphs

---

Enum TFlags

TFlags

Description

Flags for TPositionParam::iFlags.

EFLogicalOrder Input text is logically ordered not visually ordered.

Member data

---

iDirection

TInt16 iDirection;

Description

Input: Orientation (EHorizontal or EVertical) in which to draw the text.

---

iFlags

TUint16 iFlags;

Description

Input: Flags from TFlags.

---

iText

TPtrC iText;

Description

Input: Text containing the characters to be positioned.

---

iPosInText

TInt iPosInText;

Description

Input and output: Position within iText to shape. On exit it will index the first character not positioned

---

iPen

TPoint iPen;

Description

Input and output: Pen position.

---

iOutput

TOutput iOutput;

Description

Information about the glyphs that were output.

---

iOutputGlyphs

TInt iOutputGlyphs;

Description

Number of glyphs actually output.

class TMeasureTextInput;

Description

Input parameter block.

This is optionally used by CFont::MeasureText(), which is the powerful text measurement function underlying all the other text measurement functions.

Members

Defined in CFont::TMeasureTextInput:
EFIncludePenPositionInBoundsCheck, EFVisualOrder, EFVisualOrderRightToLeft, TFlags, TMeasureTextInput(), iCharJustExcess, iCharJustNum, iDirection, iEndInputChar, iFlags, iMaxAdvance, iMaxBounds, iStartInputChar, iWordJustExcess, iWordJustNum

See also:

• CFont::MeasureText()

Construction and destruction

---

TMeasureTextInput()

inline TMeasureTextInput();

Description

Member enumerations

---

Enum TFlags

TFlags

Description

Flags for TMeasureTextInput::iFlags.

EFVisualOrder Input text is visually ordered left-to-right. EFVisualOrderRightToLeft Input text is visually ordered right-to-left. Overrides EFVisualOrder. EFIncludePenPositionInBoundsCheck Flag to consider side bearings when checking bounds for line-break

Member data

---

iStartInputChar

TInt iStartInputChar;

Description

Starting index specifying first input character in iText.

Together with iEndInputChar, this allows some context before and after the measured text to be supplied so that shaping can work properly.

---

iEndInputChar

TInt iEndInputChar;

Description

Index specifying the final input character.

Together with iStartInputChar, this allows some context before and after the measured text to be supplied so that shaping can work properly.

---

iDirection

TUint16 iDirection;

Description

The direction in which to draw the text.

---

iFlags

TUint16 iFlags;

Description

Flags from TFlags.

---

iMaxAdvance

TInt iMaxAdvance;

Description

The maximum advance.

---

iMaxBounds

TInt iMaxBounds;

Description

The maximum width (or height if drawing vertically) of bounds.

---

iCharJustNum

TInt iCharJustNum;

Description

The number of glyph groups to be letter-spaced.

---

iCharJustExcess

TInt iCharJustExcess;

Description

The amount of space to be used for letter spacing.

---

iWordJustNum

TInt iWordJustNum;

Description

The number of spaces to be used for word spacing.

---

iWordJustExcess

TInt iWordJustExcess;

Description

The amount of space to be used for word spacing.

class TMeasureTextOutput;

Description

Output parameter block.

This is optionally used by CFont::MeasureText(), which is the powerful text measurement function underlying all the other text measurement functions.

Members

Defined in CFont::TMeasureTextOutput:
iBounds, iChars, iGlyphs, iGroups, iMaxGlyphSize, iSpaces

See also:

• CFont::MeasureText()

Member data

---

iChars

TInt iChars;

Description

The number of input characters that would be drawn.

This may be less than the length of the text if a maximum advance or bounding box size is specified.

---

iGlyphs

TInt iGlyphs;

Description

The number of glyphs that would be drawn.

---

iGroups

TInt iGroups;

Description

The number of groups that would be drawn.

A group is a base glyph plus one or more combining characters.

---

iSpaces

TInt iSpaces;

Description

The number of word spaces (U+0020) that would be drawn.

---

iBounds

TRect iBounds;

Description

The bounding box of all the glyphs that would be drawn.

---

iMaxGlyphSize

TSize iMaxGlyphSize;

Description

The maximum width and height of any glyph.

TTextDirection

Description

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.

See also:

• TMeasureTextInput

EHorizontal Text is drawn horizontally. EVertical Text is drawn vertically.

TCharacterDataAvailability

Description

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.

See also:

• GetCharacterData()

ENoCharacterData No font information available. ECharacterWidthOnly Width information only is available. EAllCharacterData All character data is available.