32 Fonts

This chapter provides reference material for font support. The API that this chapter describes is declared in the header files Font.h and FontSelect.h. For more information on fonts, see the "Text" section in the Palm OS Programmer's Companion.

Font Functions

FntAverageCharWidth

Purpose

Return the average character width in the current font.

Prototype

Int16 FntAverageCharWidth (void)

Parameters

None.

Result

Returns the average character width (in pixels).

FntBaseLine

Purpose

Return the distance from the top of character cell to the baseline for the current font.

Prototype

Int16 FntBaseLine (void)

Parameters

None.

Result

Returns the baseline of the font (in pixels).

FntCharHeight

Purpose

Return the character height, in the current font including accents and descenders.

Prototype

Int16 FntCharHeight (void)

Parameters

None

Result

Height of the characters in the current font, expressed in pixels.

FntCharsInWidth

Purpose

Find the length in bytes of the characters from a specified string that fit within a passed width.

Prototype

void FntCharsInWidth (Char const * string, Int16 *stringWidthP, Int16 *stringLengthP, Boolean *fitWithinWidth)

Parameters

string

Pointer to the character string.

stringWidthP

Maximum width to allow (in pixels).

stringLengthP

Maximum length of text to allow, in bytes (assumes current font).

fitWithinWidth

Set to true if string is considered truncated.

Result

When the call is completed, the information is updated as follows:

stringWidthP

Set to the width of the characters allowed.

stringLengthP

Set to the length in bytes of the text that can appear within the width.

fitWithinWidth

true if the string is considered truncated, false if it isn't.

Comments

Spaces at the end of a string are ignored and removed. Characters after a carriage return are ignored, the string is considered truncated.

FntCharsWidth

Purpose

Return the width of the specified character string. The Missing Character Symbol is substituted for any character which does not exist in the current font.

Prototype

Int16 FntCharsWidth (Char const *chars, Int16 len)

Parameters

chars

Pointer to a string of characters.

len

Length in bytes of the string.

Result

Returns the width of the string, in pixels.

FntCharWidth

Purpose

Return the width of the specified character. If the specified character does not exist within the current font, the Missing Character Symbol is substituted.

Prototype

Int16 FntCharWidth (Char ch)

Parameters

ch

Character whose width is needed.

Result

Returns the width of the specified character (in pixels).

Comments

FntCharWidth works with single-byte characters only. To determine the pixel width of a single-byte character or a multi-byte character, use TxtCharWidth instead of this function on systems that support the Text Manager.

FntDefineFont

Purpose

Makes a custom font available to your application. The custom font is available only when the application that called this function is running; when the application quits, the custom font is uninstalled automatically.

Prototype

Err FntDefineFont (FontID font, FontPtr fontP)

Parameters

font

An application-defined value greater than 128 that identifies the custom font to the system. Although this value is local to the application that called the FntDefineFont function, it must be greater than 128 because values less than 128 are reserved for system use.

fontP

Pointer to the custom font resource to be used by this function. This resource must remain locked until the calling application undefines the custom font or quits.

Result

0

no error

memErrNotEnoughSpace

Insufficient dynamic heap space

Comments

The font this function specifies is not available at build time; as a result, some UI elements--labels, for example--cannot determine their bounds automatically as they do when using the built-in fonts. This mechanism and its associated tools may be augmented in the near future; for more information, stay in contact with Palm.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

FontSelect, FntSetFont

FntDescenderHeight

Purpose

Return the height of a character's descender in the current font. The height of a descender is the distance between the base line an the bottom of the character cell.

Prototype

Int16 FntDescenderHeight (void)

Parameters

None.

Result

Returns the height of a descender, expressed in pixels.

FntGetFont

Purpose

Return the Font ID of the current font.

Prototype

FontID FntGetFont (void)

Parameters

None.

Result

Returns the Font ID of the current font.

FntGetFontPtr

Purpose

Return a pointer to the current font.

Prototype

FontPtr FntGetFontPtr (void)

Parameters

None.

Result

Returns the FontPtr of the current font.

FntGetScrollValues

Purpose

Return the values needed to update a scroll bar based on a specified string and the position within the string.

Prototype

void FntGetScrollValues (Char const *chars, UInt16 width, UInt16 scrollPos, UInt16 *linesP, UInt16 *topLine)

Parameters

chars

Null-terminated string.

width

Width to word wrap at, in pixels.

scrollPos

Character position of the first visible character.

linesP

(returned) number of lines of text.

topLine

(returned) top visible line.

Result

Returns nothing. Stores the number of lines of text in linesP and the top visible line in topLine.

Compatibility

Implemented only if 2.0 New Feature Set is present.

FntLineHeight

Purpose

Return the height of a line in the current font. The height of a line is the height of the character cell plus the space between lines (the external leading).

Prototype

Int16 FntLineHeight (void)

Parameters

None.

Result

Returns the height of a line in the current font.

FntLineWidth

Purpose

Return the width of the specified line of text, taking tab characters in to account. The function assumes that the characters passed are left-aligned and that the first character in the string is the first character drawn on a line. In other words, this routine doesn't work for characters that don't start at the beginning of a line.

Prototype

Int16 FntLineWidth (Char const *pChars, UInt16 length)

Parameters

pChars

Pointer to a string of characters.

length

Length in bytes of the string.

Result

Returns the line width (in pixels).

FntSetFont

Purpose

Set the current font.

Prototype

FontID FntSetFont (FontID font)

Parameters

font

ID of the font to make the active font.

Result

Returns the ID of the current font before the change.

FntWidthToOffset

Purpose

Given a pixel position, return the offset of the character displayed at that location.

Prototype

Int16 FntWidthToOffset (Char const *pChars, UInt16 length, Int16 pixelWidth, Boolean *leadingEdge, Int16 *truncWidth)

Parameters

-> pChars

Pointer to the character string. Must not be NULL.

-> length

Length in bytes of pChars.

-> pixelWidth

A horizontal location on the screen, given in pixels.

<- leadingEdge

Set to true if the pixel position pixelWidth falls on the left side of the character. Pass NULL for this parameter if you don't need this information.

<- truncWidth

The width of the text (in pixels) up to the returned offset. Pass NULL for this parameter if you don't need this information.

Result

Returns the offset into pChars of the character displayed at the location pixelWidth.

Compatibility

Implemented only if 3.1 New Feature Set is present.

FntWordWrap

Purpose

Given a string, determine how many bytes of text can be displayed within the specified width.

Prototype

UInt16 FntWordWrap (Char const *chars, UInt16 maxWidth)

Parameters

chars

Pointer to a null-terminated string.

maxWidth

Maximum line width in pixels.

Result

Returns the length of the line, in bytes.

Compatibility

Implemented only if 2.0 New Feature Set is present.

FntWordWrapReverseNLines

Purpose

Word wrap a text string backwards by the number of lines specified. The character position of the start of the first line and the number of lines that are actually word wrapped are returned.

Prototype

void FntWordWrapReverseNLines (Char const *const chars, UInt16 maxWidth, UInt16 *linesToScrollP, UInt16 *scrollPosP)

Parameters

chars

Pointer to a null-terminated string.

maxWidth

Maximum line width in pixels.

linesToScrollP

The number of lines to scroll. Upon return, contains the number lines that were scrolled.

scrollPosP

Byte offset of the first character. Upon return, contains the first character after wrapping.

Result

Returns nothing. Stores the first character after wrapping and the number of lines scrolled in scrollPosP and linesToScrollP.

Compatibility

Implemented only if 2.0 New Feature Set is present.

FontSelect

Purpose

Displays a dialog box in which the user can choose one of three system-supplied fonts, and returns a FontID value representing the user's choice.

Prototype

FontID FontSelect (FontID fontID)

Parameters

fontID

A fontID value specifying the font to be highlighted as the default choice in the dialog box this function displays. This value must be one of the following system-supplied constants:

stdFont

Standard plain text font

boldFont

Bold version of stdFont

largeBoldFont

Larger version of boldFont

Result

Returns a fontID value representing the font that the user chose in the dialog box this function displays.

Comments

When your application starts up for the first time, it should use the features sysFtrDefaultFont and sysFtrDefaultBoldFont to determine the default font for the application. For example:

FtrGet(sysFtrCreator, sysFtrDefaultFont,
&fntID)

After this call returns, fntID contains an ID compatible with the FontSelect function.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

FntGetFont, FntSetFont