Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

37    Fonts

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

This chapter provides the following information regarding font support:

The header files Font.h and FontSelect.h declare the API that this chapter describes. For more information on fonts, see Chapter 8, "Text," of the Palm OS Programmer's Companion, vol. I.

Font Data Structures ^TOP^

FontCharInfoPtr Typedef ^TOP^

Purpose

The FontCharInfoPtr type points to a FontCharInfoType structure.

Prototype

typedef FontCharInfoType *FontCharInfoPtr;

FontCharInfoType Struct ^TOP^

Purpose

The FontCharInfoType structure defines an entry in the offset/width table for a font.


WARNING! Palm, Inc. does not support or provide backward compatibility for the FontCharInfoType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.

Prototype

typedef struct FontCharInfoTag {
Int8 offset;
Int8 width;
} FontCharInfoType;

Fields

offset
This value is not currently used and must be set to 0.
width
The exact width in pixels of the glyph. You can retrieve this information using the function FntWCharWidth() or FntCharWidth().

FontDensityType Struct ^TOP^

Purpose

The FontDensityType structure defines an entry in the densities array in the FontTypeV2 structure. The densities array specifies the location of each set of glyphs within an extended font resource.


WARNING! Palm, Inc. does not support or provide backward compatibility for the FontDensityType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.

Prototype

typedef struct FontDensityTag {
Int16 density;
UInt32 glyphBitsOffset;
} FontDensityType;

Fields

density
Either kDensityLow, kDensityOneAndAHalf, or kDensityDouble.
glyphBitsOffset
Offset in bytes from the beginning of the font data to the start of the font image for this density.

Compatibility

This structure is only defined if the High-Density Display Feature Set is present.

FontID Enum ^TOP^

Purpose

The FontID enum specifies the IDs of available fonts. A font can either be a system-defined font or an application-defined font. You can obtain the ID of the current font using FntGetFont() and change the font using FntSetFont().

Prototype

enum fontID {
stdFont = 0x00, 
boldFont, 
largeFont, 
symbolFont, 
symbol11Font, 
symbol7Font, 
ledFont, 
largeBoldFont, 
fntAppCustomBase = 0x80
};
typdef enum fontID FontID;

Constants

stdFont
A small standard font used to display user input. This font is small to display as much text as possible.
boldFont
Same size as stdFont but bold for easier reading. Used for text labels in the user interface.
largeFont
A larger font provided as an alternative for users who find the standard font too small to read.
symbolFont
Contains many special characters such as arrows, shift indicators, and so on.
symbol11Font
Contains the check boxes, the large left arrow, and the large right arrow.
symbol7Font
Contains the up and down arrows used for the repeating button scroll arrows and the dimmed version of the same arrows.
ledFont
Contains the numbers 0 through 9, –, ., and the comma (,). Used by the Calculator application for its numeric display.
largeBoldFont
In Palm OS® 3.0 and later only. Same size as largeFont but bold.
fntAppCustomBase
The first available ID for application-defined fonts.

FontPtr Typedef ^TOP^

Purpose

The FontPtr type defines a pointer to a FontType structure.

Prototype

typedef FontType *FontPtr;

FontType Struct ^TOP^

Purpose

The FontType structure defines a font resource's header. The fields in this structure give general information about the font. Following the structure are several tables that Palm OS uses to draw the font on the screen. See "Font Resource" for more information about the font resource.


WARNING! Palm, Inc. does not support or provide backward compatibility for the FontType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.

Prototype

typedef struct FontTag {
Int16 fontType;
Int16 firstChar;
Int16 lastChar;
Int16 maxWidth;
Int16 kernMax;
Int16 nDescent;
Int16 fRectWidth; 
Int16 fRectHeight;
Int16 owTLoc;
Int16 ascent;
Int16 descent;
Int16 leading;
Int16 rowWords;
} FontType;

Fields

fontType
A mask providing the general characteristics of the font. When creating an application-defined font resource, use 0x9000.
firstChar
Character code of first glyph in the font.
lastChar
Character code of last glyph in the font.
maxWidth
The maximum width in pixels of any glyph. In Palm OS, there is currently no difference between this field and fRectWidth.
kernMax
This value is not currently used and must be set to 0.
nDescent
This value is not currently used and must be set to 0.
fRectWidth
A metric of the font image. In Palm OS, this metric is equivalent to the maximum width in pixels of any glyph in the font. Use FntAverageCharWidth() to obtain this value.
fRectHeight
The height, including ascenders and descenders, of the glyphs in this font. Use FntCharHeight() to obtain this value.
owTLoc
The offset in 16-bit words from this field to the first byte of the offset/width table. The offset/width table is a table of FontCharInfoType structures giving the width of each character in the font. Do not access the offset/width table directly. Use FntWCharWidth() or FntCharWidth() instead.
ascent
The distance in pixels from the top of the font rectangle to its baseline. Use FntBaseLine() to obtain this value.
descent
The distance in pixels from the baseline to the bottom of the font rectangle. Use FntDescenderHeight() to obtain this value.
leading
The font's leading, which is the vertical space between lines of text, in pixels. This field is unused in Palm OS and must be set to 0. If your font requires a leading value, add blank space to the bottom of each of your glyphs. The FntLineHeight() function returns the size of the font's character cell plus the leading.
rowWords
The number of 16-bit words stored for each row of a glyph's bitmap where fRectHeight is the number of rows.

FontTypeV2 Struct ^TOP^

Purpose

The FontTypeV2 structure defines the header for an extended font resource, which contains a separate set of glyphs for each screen density. Currently the only supported densities are kDensityLow and kDensityDouble. See "Extended Font Resource" for more information.


WARNING! Palm, Inc. does not support or provide backward compatibility for the FontCharTypeV2 structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.

Prototype

typedef struct FontTagV2 {
Int16 fontType;
Int16 firstChar;
Int16 lastChar;
Int16 maxWidth;
Int16 kernMax;
Int16 nDescent;
Int16 fRectWidth; 
Int16 fRectHeight;
Int16 owTLoc;
Int16 ascent;
Int16 descent;
Int16 leading;
Int16 rowWords;
Int16 version;
Int16 densityCount;
FontDensityType densities[0];
} FontTypeV2;

NOTE: All pixel values given in the fields below are in terms of the single-density font data.

Fields

fontType
A mask providing the general characteristics of the font. When creating an application-defined extended font resource, use the value fntExtendedFormatMask | 0x9000.
firstChar
Character code of first glyph in the font.
lastChar
Character code of last glyph in the font.
maxWidth
The maximum width in pixels of any glyph. In Palm OS, there is currently no difference between this field and fRectWidth.
kernMax
This value is not currently used and must be set to 0.
nDescent
This value is not currently used and must be set to 0.
fRectWidth
A metric of the font image. In Palm OS, this metric is equivalent to the maximum width in pixels of any glyph in the font. Use FntAverageCharWidth() to obtain this value.
fRectHeight
The height, including ascenders and descenders, of the glyphs in this font. Use FntCharHeight() to obtain this value.
owTLoc
The offset in 16-bit words from this field to the first byte of the offset/width table. The offset/width table is a table of FontCharInfoType structures giving the width of each character in the font. Do not access the offset/width table directly. Use FntWCharWidth() or FntCharWidth() instead.
ascent
The distance in pixels from the top of the font rectangle to its baseline. Use FntBaseLine() to obtain this value.
descent
The distance in pixels from the baseline to the bottom of the font rectangle. Use FntDescenderHeight() to obtain this value.
leading
The font's leading, which is the vertical space between lines of text, in pixels. This field is unused in Palm OS and must be set to 0. If your font requires a leading value, add blank space to the bottom of each of your glyphs. The FntLineHeight() function returns the size of the font's character cell plus the leading.
rowWords
The number of 16-bit words stored for each row of a glyph's bitmap where fRectHeight is the number of rows.
version
The version of the extended font resource. This value should be set to 1.
densityCount
The number of entries in the densities array.
densities
An array of one or more FontDensityType structures identifying the glyphs for each supported density.

Compatibility

This structure is only defined if the High-Density Display Feature Set is present.

Font Constants ^TOP^

Constant

Value

Description

checkboxFont

symbol11Font

A convenience constant that points to the font containing the checkbox bitmap.

fntMissingChar

–1

The value used for a character that does not have a definition in the current font. The missing character symbol is usually an open rectangle.

fntExtendedFormatMask

0x0200

A constant used for the fontType field of a font to indicate that it is an extended font resource.

fntTabChrWidth

20

The width of the tab character in pixels.

Font Resources ^TOP^

Font Resource ^TOP^

The font resource ('NFNT') represents a version 1 single-density font. This resource is the same as the Macintosh 'NFNT' resource with some restrictions. It contains a header followed by several tables that provide information about each glyph in the font.

Figure 37.1 shows how the font resource is laid out in memory. Table 37.1 describes each table within the font resource.

Figure 37.1  Font resource ('NFNT')

Table 37.1  Font resource description

Field

Description

FontType header

Contains general information about the glyphs in the font. See FontType.

Font image

A raw bitmap image containing the packed character glyphs from left to right (see Figure 37.2). This part of the resource tells Palm OS how to draw each character in the font. The height of the image is fRectHeight and the size is rowWords * 2 * fRectHeight.

Place glyphs sequentially in order of increasing character code. Leave at least a one-pixel wide vertical column of space to the right of each image so that there is space between characters when Palm OS draws text on the screen. If your font requires leading, leave horizontal space at the bottom of the characters as well. The font image must end with the glyph for the missing character symbol.

Bitmap location table

A table of 16-bit words that specify the location of each glyph's entry in the font image. The location is specified as the bit offset from the start of the image to the glyph in the first row of the font image. The last entry in the table contains the offset of the column after the last bitmap. (See Figure 37.2.)

If you have skipped characters within an encoding, for each glyph that is missing, specify the same value for its location as the entry for the next glyph in the table.

Offset/width table

A table that specifies how wide each glyph in the font is. On Macintosh systems, this table also specifies how each glyph kerns. Palm OS does not support kerning, as the offset value is ignored.

Each entry in the offset/width table is two bytes long. The first byte should be 0, and the second byte should contain the glyph width, which must be greater than or equal to 0. If the glyph at this index does not have a bitmap in the font image, the values should be –1 and –1.

Figure 37.2 shows an example of the font image for a font that defines glyphs for four characters (A, B, C, and the missing character symbol) and the portion of the bitmap location table that provides the offsets for these characters. The last entry in the bitmap location table is the offset to the column after the last bitmap, or 0x0014.

Figure 37.2  Font image and bitmap location table

Extended Font Resource ^TOP^

The extended font resource ('nfnt') defines a font that supports multiple screen densities. The High-Density Display Feature Set supports two or more screen densities. As shown in Figure 37.3, the extended font resource is essentially:

  • A FontTypeV2 header giving all general information about the glyphs in the font. All metrics are in terms of the low-density version of the font.
  • Tables for the low-density font. See "Font Resource" for a description of these tables.
  • The font image (set of glyphs) for each density specified by the font.

NOTE: It is not required that an extended font resource contain a font image for the low-density font. It may contain a font image only for a double-density font, for example. All of the metrics and the font tables must be given in standard coordinates, as if there were a low-density version of the font present in the resource.

Compatibility

This resource is only defined if the High-Density Display Feature Set is present. 1.5x density fonts are only supported if the 1.5x Display Feature Set is present.

Figure 37.3  Extended font resource

Font Functions ^TOP^

FntAverageCharWidth Function ^TOP^

Purpose

Gets the maximum character width in pixels of the current font.

Declared In

Font.h

Prototype

Int16 FntAverageCharWidth (
   void
)

Parameters

None.

Returns

Returns the maximum character width (in pixels).

Comments

This function returns the value of the fRectHeight field in the FontType structure for the current font. Because Palm OS does not support kerning, this value is the maximum width in pixels rather than the average width.

FntBaseLine Function ^TOP^

Purpose

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

Declared In

Font.h

Prototype

Int16 FntBaseLine (
   void
)

Parameters

None.

Returns

Returns the ascent of the font (in pixels).

FntCharHeight Function ^TOP^

Purpose

Gets the character height of the current font including accents and descenders.

Declared In

Font.h

Prototype

Int16 FntCharHeight (
   void
)

Parameters

None.

Returns

Returns the height of the characters in the current font, expressed in pixels.

FntCharsInWidth Function ^TOP^

Purpose

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

Declared In

Font.h

Prototype

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

Parameters

string
A pointer to the character string.
stringWidthP
The maximum width to allow (in pixels). Upon return, contains the actual width allowed. Note that this value does not include any trailing spaces or tabs, which are stripped by this function.
stringLengthP
The maximum length of text to allow, in bytes (assumes current font). Upon return, contains the number of bytes of text that can appear within the width. Note that this value does not include any trailing space or tabs, which are stripped by this function.
fitWithinWidth
Upon return, false if the string is considered truncated, true if it isn't.

Returns

Returns nothing.

Comments

Spaces and tabs at the end of a string are ignored and removed. If the string fits within the specified width after spaces and tabs are removed, the fitWithinWidth value contains true. Characters after a carriage return are ignored, and the string is considered truncated.

This function is specifically designed for the code used to draw text fields. Consider using FntWidthToOffset() in your application code instead, particularly if you do not want the special processing of trailing spaces, tabs, and carriage returns.

FntCharsWidth Function ^TOP^

Purpose

Gets the width of the specified character string. The missing character symbol (an open rectangle) is substituted for any character that does not exist in the current font.

Declared In

Font.h

Prototype

Int16 FntCharsWidth (
   Charconst*chars,
   Int16len
)

Parameters

chars
Pointer to a string of characters.
len
Length in bytes of the string.

Returns

Returns the width of the string, in pixels.

Comments

Like all functions that work with strings, this function returns correct results for strings with multi-byte characters as well as strings with only single-byte characters.

See Also

FntCharWidth()

FntCharWidth Function ^TOP^

Purpose

Gets the width of the specified character. If the specified character does not exist within the current font, the missing character symbol is substituted.

Declared In

Font.h

Prototype

Int16 FntCharWidth (
   Charch
)

Parameters

ch
Character whose width is needed.

Returns

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 FntWCharWidth() instead of this function in Palm OS 4.0 and higher. Alternatively, for compatibility with earlier versions of Palm OS, link with the PalmOSGlue library and call FntGlueWCharWidth. For more information, see Chapter 80, "PalmOSGlue Library."

See Also

FntCharsWidth()

FntDefineFont Function ^TOP^

Purpose

Makes a custom font available to your application.

Declared In

Font.h

Prototype

Err FntDefineFont (
   FontIDfont,
   FontPtrfontP
)

Parameters

font
A value greater than or equal to fntAppFontCustomBase that identifies the custom font to the system. Values less than that are reserved for system use. Note that font IDs are 8-bit unsigned values and so must be less than 256. See FontID.
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.

Returns

errNone
No error
memErrNotEnoughSpace
Insufficient dynamic heap space

Comments

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.

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.

Before you use this function, you must load the font resource from the database and obtain a pointer to it. See "Creating Custom Fonts" of the Palm OS Programmer's Companion, vol. I for more information.

Compatibility

Implemented only if 3.0 New Feature Set is present.

Palm OS 4.0 and later do not allow a NULL value for the fontP parameter; therefore, you cannot undefine a font using FntDefineFont(myFontID, NULL). Earlier versions of Palm OS allowed the NULL value. Note that there is usually no need to undefine a font.

Palm OS 3.0 and 3.1 have problems with font ID values greater than 131. These problems are fixed in later releases of Palm OS.

See Also

FontSelect(), FntSetFont()

FntDescenderHeight Function ^TOP^

Purpose

Gets the height of a character's descender in the current font. The height of a descender is the distance between the baseline and the bottom of the character cell.

Declared In

Font.h

Prototype

Int16 FntDescenderHeight (
   void
)

Parameters

None.

Returns

Returns the height of a descender, expressed in pixels.

FntGetFont Function ^TOP^

Purpose

Gets the font ID of the current font.

Declared In

Font.h

Prototype

FontID FntGetFont (
   void
)

Parameters

None.

Returns

Returns the ID of the current font.

Comments

The current font is the font stored in the draw state. It is used when drawing characters directly onto the screen. Most user interface elements, such as fields, tables, labels, and buttons, do not use the current font.

See Also

FntSetFont(), FntGetFontPtr(), FontID

FntGetFontPtr Function ^TOP^

Purpose

Gets a pointer to the current font.

Declared In

Font.h

Prototype

FontPtr FntGetFontPtr (
   void
)

Parameters

None.

Returns

Returns a pointer to the current font.

Comments

The current font is the font stored in the draw state. It is used when drawing characters directly onto the screen. Most user interface elements, such as fields, tables, labels, and buttons, do not use the current font.

See Also

FntGetFont()

FntGetScrollValues Function ^TOP^

Purpose

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

Declared In

Font.h

Prototype

void FntGetScrollValues (
   Charconst*chars,
   UInt16width,
   UInt16scrollPos,
   UInt16*linesP,
   UInt16*topLine
)

Parameters

chars
A null-terminated string.
width
The width of a line of text in the display, given in pixels.
scrollPos
The byte offset of the first character displayed on the topmost line.
linesP
Number of lines required to display the string.
topLine
The line of text that is the topmost visible line. Line numbering starts with 0.

Returns

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.

See Also

FldGetScrollValues()

FntIsAppDefined Macro ^TOP^

Purpose

Returns true if the font is defined by the application or false if it is defined by the system.

Declared In

Font.h

Prototype

#define FntIsAppDefined (
   fnt
) 

Parameters

fnt
The FontID of a font.

Returns

Boolean that indicates if the font is an application-defined font. Returns true if application-defined, false if system-defined.

FntLineHeight Function ^TOP^

Purpose

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

Declared In

Font.h

Prototype

Int16 FntLineHeight (
   void
)

Parameters

None.

Returns

Returns the height in pixels of a line in the current font.

FntLineWidth Function ^TOP^

Purpose

Gets the width of the specified line of text, taking tab characters into 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.

Declared In

Font.h

Prototype

Int16 FntLineWidth (
   Charconst*pChars,
   UInt16length
)

Parameters

pChars
Pointer to a string of characters.
length
Length in bytes of the string.

Returns

Returns the line width (in pixels).

FntSetFont Function ^TOP^

Purpose

Sets the current font.

Declared In

Font.h

Prototype

FontID FntSetFont (
   FontIDfont
)

Parameters

font
ID of the font to make the current font.

Returns

Returns the ID of the previous font.

Comments

If the specified font ID is invalid, this function sets the current font to stdFont.

The current font is the font stored in the draw state. It is used when drawing characters directly onto the screen. Most user interface elements, such as fields, tables, labels, and buttons, do not use the current font. To set the font for one of these elements, check the API for that element. If the element's API doesn't have a function to set the font programmatically, check the PalmOSGlue library.

See Also

FntGetFont()

FntWCharWidth Function ^TOP^

Purpose

Gets the width of the specified character. If the specified character does not exist within the current font, the missing character symbol is substituted.

Declared In

Font.h

Prototype

Int16 FntWCharWidth (
   WChariChar
)

Parameters

iChar
Character whose width is needed.

Returns

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

Comments

FntWCharWidth works with both single-byte characters and multi-byte characters. However, you should always pass a WChar variable to this function rather than a Char to avoid sign extension problems on values 0x80 and higher.

Compatibility

Implemented only if 4.0 New Feature Set is present. If you want to use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call FntGlueWCharWidth. For more information, see Chapter 80, "PalmOSGlue Library."

See Also

FntCharWidth()

FntWidthToOffset Function ^TOP^

Purpose

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

Declared In

Font.h

Prototype

Int16 FntWidthToOffset (
   Charconst*pChars,
   UInt16length,
   Int16pixelWidth,
   Boolean*leadingEdge,
   Int16*truncWidth
)

Parameters

pChars
Pointer to the character string.
length
The length in bytes of pChars.
pixelWidth
A horizontal pixel offset from the beginning of the string.
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 but not including the returned offset. Pass NULL for this parameter if you don't need this information.

Returns

Returns the byte offset into pChars of the character that contains the pixel offset pixelWidth. If pixelWidth is past the right edge of the string, the function returns the byte offset past the last character in pChars, and truncWidth contains the width required to display the entire string.

Compatibility

Implemented only if 3.1 New Feature Set is present. If you want to use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call FntGlueWidthToOffset. For more information, see Chapter 80, "PalmOSGlue Library."

FntWordWrap Function ^TOP^

Purpose

Given a string, determines how many bytes of text can be displayed within the specified width with a line break at a tab or space character.

Declared In

Font.h

Prototype

UInt16 FntWordWrap (
   Charconst*chars,
   UInt16maxWidth
)

Parameters

chars
A pointer to a null-terminated string.
maxWidth
The maximum line width in pixels.

Returns

Returns the length of the line, in bytes. If the entire string cannot be displayed within maxWidth, the value that this function returns specifies the offset where the line should be broken, which is typically following a space, tab, or line-feed character.

Compatibility

Implemented only if 2.0 New Feature Set is present.

See Also

FldWordWrap()

FntWordWrapReverseNLines Function ^TOP^

Purpose

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

Declared In

Font.h

Prototype

void FntWordWrapReverseNLines(
   Charconst*constchars,
   UInt16maxWidth,
   UInt16*linesToScrollP,
   UInt16*scrollPosP
)

Parameters

chars
A pointer to a null-terminated string.
maxWidth
The maximum line width in pixels.
linesToScrollP
The number of lines to scroll. Upon return, contains the number of lines that were scrolled.
scrollPosP
The byte offset of the first character displayed on the topmost line. Upon return, contains the first character after wrapping.

Returns

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 Function ^TOP^

Purpose

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

Declared In

FontSelect.h

Prototype

FontID FontSelect (
   FontIDfontID
)

Parameters

fontID
A FontID value specifying the font to be highlighted as the default choice in the dialog box that this function displays. This value must be one of the following system-supplied constants:
stdFont
Standard plain text font.
boldFont
Bold version of stdFont.
largeFont
A large plain text font.
largeBoldFont
Larger version of boldFont.

Returns

Returns a FontID value representing the font that the user chose.

Comments

When your application launches for the first time, it should determine the system's default font. The default font varies based on locale. You can use FntGlueGetDefaultFontID() from the PalmOSGlue library to determine the default font as follows:


fntID =
FntGlueGetDefaultFontID(defaultSystemFont); 

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

FntGetFont(), FntSetFont()