This chapter provides the following information regarding bitmapped font support:
Bitmapped Font Structures and Types
Bitmapped Font Constants
Bitmapped Font Resources
Bitmapped Font Functions and Macros
The header files Font.h
and FontSelect.h
declare the API that this chapter describes. For more information on using fonts, see Chapter 5, "Displaying Text." For reference information on scalable fonts, see Chapter 29, "Scalable Font Reference."
Bitmapped Font Structures and Types
FontDensityTypeType Struct
Purpose
An entry in the densities
array in the FontTypeV2Type
structure. The densities
array specifies the location of each set of glyphs within an extended font resource.
Declared In
Font.h
Prototype
typedef struct FontDensityTypeTag { int16_t density; int16_t reserved; uint32_t glyphBitsOffset; } FontDensityTypeType
Fields
-
density
- One of the
DensityType
constants. -
reserved
- Reserved for future use.
-
glyphBitsOffset
- Offset in bytes from the beginning of the font data to the start of the font image for this density.
FontTablePtr Typedef
Purpose
A pointer to a pointer to a FontType
structure.
Declared In
Font.h
Prototype
typedef FontPtr *FontTablePtr
FontType Struct
Purpose
Defines a font resource's header. The FontPtr
type defines a pointer to a FontType
structure.
WARNING! PalmSource, 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.
Declared In
Font.h
Prototype
typedef struct FontTag { int16_t fontType; int16_t firstChar; int16_t lastChar; int16_t maxWidth; int16_t kernMax; int16_t nDescent; int16_t fRectWidth; int16_t fRectHeight; int16_t owTLoc; int16_t ascent; int16_t descent; int16_t leading; int16_t rowWords; } FontType;
typedef FontType *FontPtr
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 standard coordinates 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 standard coordinates 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 gives the width of each character in the font. Do not access the offset/width table directly. Use
FntCharWidth()
instead. -
ascent
- The distance in standard coordinates from the top of the font rectangle to its baseline. Use
FntBaseLine()
to obtain this value. -
descent
- The distance in standard coordinates 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 standard coordinates. 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.
Comments
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 Also
FontTypeV2Type Struct
Purpose
Defines the header for an extended font resource, which contains a separate set of glyphs for each screen density.
WARNING! PalmSource, 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.
Declared In
Font.h
Prototype
typedef struct FontTypeV2Tag { int16_t fontType; int16_t firstChar; int16_t lastChar; int16_t maxWidth; int16_t kernMax; int16_t nDescent; int16_t fRectWidth; int16_t fRectHeight; int16_t owTLoc; int16_t ascent; int16_t descent; int16_t leading; int16_t rowWords; int16_t version; int16_t densityCount; int16_t reserved; FontDensityTypeType densities[1]; } FontTypeV2Type
Fields
-
fontType
- A mask providing the general characteristics of the font. When creating an application-defined extended font resource, use the value
0x9200
. -
firstChar
- Character code of first glyph in the font.
-
lastChar
- Character code of last glyph in the font.
-
maxWidth
- The maximum width in standard coordinates of any glyph. 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 standard coordinates 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 gives the width of each character in the font. Do not access the offset/width table directly. Use
FntCharWidth()
instead. -
ascent
- The distance in standard coordinates from the top of the font rectangle to its baseline. Use
FntBaseLine()
to obtain this value. -
descent
- The distance in standard coordinates 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 standard coordinates. 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. -
reserved
- Reserved for future use.
-
densities
- An array of one or more
FontDensityTypeType
structures identifying the glyphs for each supported density.
See Also
Bitmapped Font Constants
FontDefaultType Enum
Purpose
Specifies the default fonts defined in the system.
Declared In
Font.h
Constants
-
defaultSmallFont = 0
- The default small font.
-
defaultLargeFont
- The default large font.
-
defaultBoldFont
- The default bold font.
-
defaultSystemFont
- The default font for the system.
Comments
Although the standard bitmapped fonts are included on all systems, each locale might choose a different default font. For example, Latin ROMs tend to use stdFont
as the default system bitmapped font, while Japanese ROMs might use largeFont
instead.
See Also
FontID Typedef
Purpose
The IDs of available fonts. A font can either be a system-defined font or an application-defined font.
Declared In
Font.h
Prototype
typedef Enum8 FontID
Constants
-
stdFont = 0x00
- 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
- Same size as
largeFont
but bold. -
fntAppFontCustomBase = 0x80
- The first available ID for application-defined fonts.
See Also
Miscellaneous Font Constants
Purpose
Other constants defined in Font.h
.
Declared In
Font.h
Constants
-
#define checkboxFont symbol11Font
- A convenience constant that points to the font containing the check box bitmap.
-
#define fntTabChrWidth 20
- The width of the tab character in standard coordinates.
Bitmapped Font Resources
Font Resource
The font resource ('NFNT'
) represents a version 1 single-density bitmapped 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 13.1 shows how the font resource is laid out in memory. Table 13.1 describes each table within the font resource.
Figure 13.1 Font resource ('NFNT')

Table 13.1 Font resource description
Contains general information about the glyphs in the font. See |
|
A raw bitmap image containing the packed character glyphs from left to right (see Figure 13.2). This part of the resource tells Palm OS how to draw each character in the font. The height of the image is |
|
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. |
|
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 13.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. |
|
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 13.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 13.2 Font image and bitmap location table

Extended Font Resource
The extended font resource ('nfnt'
) defines a font that supports multiple screen densities. As shown in Figure 13.3, the extended font resource is essentially:
- A
FontTypeV2Type
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.
Figure 13.3 Extended font resource

Bitmapped Font Functions and Macros
FntAverageCharWidth Function
Purpose
Gets the maximum character width of the current font.
Declared In
Font.h
Prototype
Coord FntAverageCharWidth ( void )
Parameters
Returns
The maximum character width (in the active coordinate system).
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 rather than the average width.
FntBaseLine Function
Purpose
Gets the distance from the top of the character cell to the baseline for the current font.
Declared In
Font.h
Prototype
Coord FntBaseLine ( void )
Parameters
Returns
The ascent of the font (in the active coordinate system).
FntCharHeight Function
Purpose
Gets the character height of the current font including accents and descenders.
Declared In
Font.h
Prototype
Coord FntCharHeight ( void )
Parameters
Returns
The height (in the active coordinate system) of the characters in the current font.
FntCharsInWidth Function
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 ( const char*string
, Coord*stringWidthP
, size_t*stringLengthP
, Boolean*fitWithinWidth
)
Parameters
-
→
string
- A pointer to the character string.
-
↔
stringWidthP
- The maximum width (in the active coordinate system) to allow. 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
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()
or FntTruncateString()
in your application code instead, particularly if you do not want the special processing of trailing spaces, tabs, and carriage returns.
FntCharsWidth Function
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
Coord FntCharsWidth ( const char*chars
, size_tlen
)
Parameters
Returns
The width of the string (in the active coordinate system).
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 Function
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
Coord FntCharWidth (
wchar32_t ch
)
Parameters
Returns
The width of the specified character (in the active coordinate system).
See Also
FntCharWidthV50 Function
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
Coord FntCharWidthV50 (
char ch
)
Parameters
Returns
The width of the specified character.
Comments
Do not use this function. Instead use FntCharWidth()
, which can check the width of either single-byte or multi-byte characters.
FntGetDefaultFontID Function
Purpose
Returns the font ID of a default font.
Declared In
Font.h
Prototype
FontID FntGetDefaultFontID (
FontDefaultType inFontType
)
Parameters
-
→
inFontType
- A
FontDefaultType
constant specifying one of the system default fonts.
Returns
Comments
Use this function whenever you need to obtain a font ID for one of the system default fonts. The default fonts (and thus, the IDs for the default fonts) vary depending on the system's locale. For example, Japanese systems have a different set of default fonts than systems using the Latin character encoding.
Use this function in place of the constants that specify the IDs of default fonts, as shown in the following table.
Note that defaultSystemFont
and defaultSmallFont
might return the same font ID or different font IDs, depending on the system locale.
See Also
FontSelect()
, FntGetFont()
, FntSetFont()
FntDefineFont Function
Purpose
Makes a custom font available to your application.
Declared In
Font.h
Prototype
status_t FntDefineFont ( FontIDfont
, const FontType*fontP
)
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. SeeFontID
. -
→
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
upon success or one of the following errors:
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 and Using Custom Bitmapped Fonts" for more information.
See Also
FntDescenderHeight Function
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
Coord FntDescenderHeight ( void )
Parameters
Returns
The height of a descender (in the active coordinate system).
FntGetFont Function
Purpose
Gets the font ID of the current bitmapped font.
Declared In
Font.h
Prototype
FontID FntGetFont ( void )
Parameters
Returns
Comments
The current bitmapped font is the font stored in the Window Manager version of the draw state. It is used when drawing characters directly onto the screen using WinDrawChars()
or WinDrawChar()
. Most user interface elements, such as fields, tables, labels, and buttons, do not use the current font. The graphics context function GcDrawTextAt()
uses the scalable font specified in GcSetFont()
.
See Also
FntSetFont()
, FntGetFontPtr()
, FontID
FntGetFontPtr Function
Purpose
Gets a pointer to the current bitmapped font.
Declared In
Font.h
Prototype
const FontType *FntGetFontPtr ( void )
Parameters
Returns
A pointer to the current font.
Comments
The current bitmapped font is the font stored in the Window Manager version of the draw state. It is used when drawing characters directly onto the screen using WinDrawChars()
or WinDrawChar()
. Most user interface elements, such as fields, tables, labels, and buttons, do not use the current font. The graphics context function GcDrawTextAt()
uses the scalable font specified in GcSetFont()
.
See Also
FntGetScrollValues Function
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 ( const char*chars
, CoordmaxWidth
, size_tscrollPos
, uint32_t*linesP
, uint32_t*topLine
)
Parameters
-
→
chars
- A null-terminated string.
-
→ maxWidth
- The width (in the active coordinate system) of a line of text in the display.
-
→ 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
Nothing. Stores the number of lines of text in linesP
and the top visible line in topLine
.
See Also
FntIsAppDefined Macro
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
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
Coord FntLineHeight ( void )
Parameters
Returns
The height (in the active coordinate system) of a line in the current font.
FntLineWidth Function
Purpose
Gets the width of the specified line of text, taking tab characters into account.
Declared In
Font.h
Prototype
Coord FntLineWidth ( const char*chars
, size_tlength
)
Parameters
Returns
The line width (in the active coordinate system).
Comments
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 function doesn't work for characters that don't start at the beginning of a line.
FntSetFont Function
Purpose
Declared In
Font.h
Prototype
FontID FntSetFont (
FontID font
)
Parameters
Returns
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 Window Manager's draw state. It is used when drawing characters directly onto the screen using WinDrawChars()
or WinDrawChar()
. 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.
The graphics context function GcDrawTextAt()
uses the scalable font specified in GcSetFont()
. You can use GcCreateFontFromID()
to use a bitmapped font when drawing into the graphics context.
See Also
FntTruncateString Function
Purpose
Returns a string truncated to fit in the specified width.
Declared In
Font.h
Prototype
Boolean FntTruncateString ( char*iDstString
, const char*iSrcString
, FontIDiFont
, CoordiMaxWidth
, BooleaniAddEllipsis
)
Parameters
-
← iDstString
- Upon return, contains
iSrcString
truncated, if necessary, to fit in the specified width. -
→ iSrcString
- The string to be truncated.
-
→ iFont
- The
FontID
of the font to use when checking the width. -
→ iMaxWidth
- The maximum width of the characters to be drawn. The width is given using the active coordinate system.
-
→ iAddEllipsis
-
true
ifiDstString
should end in an ellipsis (...) ifiSrcString
is too wide for the space. If that is the case,iSrcString
is truncated further to fit the ellipsis within the specified width. Iffalse
, theiDstString
simply contains the truncated version ofiSrcString
without a trailing ellipsis.
Returns
true
if iDstString
contains a truncated version of iSrcString
. false
if iDstString
is an exact copy of iSrcString
.
Comments
This function uses FntWidthToOffset()
to determine if the destination string should be truncated. It differs from FntWidthToOffset()
in that it returns the truncated string rather than the offset at which the string should be truncated. It differs from WinDrawTruncChars()
in that it does not draw the truncated string onto the screen.
This function may display a fatal error message if either iDstString
or iSrcString
are NULL
or if iMaxWidth
is invalid.
FntWCharWidthV50 Function
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
Coord FntWCharWidthV50 (
wchar32_t iChar
)
Parameters
Returns
The width of the specified character.
Comments
Do not use this function. Instead use FntCharWidth()
, which works with both single-byte and multi-byte characters in Palm OS Cobalt.
FntWidthToOffset Function
Purpose
Given a pixel position, gets the offset of the character displayed at that location.
Declared In
Font.h
Prototype
size_t FntWidthToOffset ( const char*chars
, size_tlength
, CoordpixelWidth
, Boolean*leadingEdge
, Coord*truncWidth
)
Parameters
-
→ chars
- Pointer to the character string.
-
→
length
- The length in bytes of
chars
. -
→
pixelWidth
- A horizontal offset from the beginning of the string. The offset is given using the active coordinate system.
-
←
leadingEdge
- Set to
true
if the pixel positionpixelWidth
falls on the left side of the character. PassNULL
for this parameter if you don't need this information. -
←
truncWidth
- The width of the text up to but not including the returned offset. The width is given using the active coordinate system. Pass
NULL
for this parameter if you don't need this information.
Returns
The byte offset into chars
of the character that contains the offset pixelWidth
. If pixelWidth
is past the right edge of the string, the function returns the byte offset past the last character in chars
, and truncWidth
contains the width required to display the entire string.
FntWordWrap Function
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
size_t FntWordWrap ( const char*string
, CoordmaxWidth
)
Parameters
-
→ string
- A pointer to a null-terminated string.
-
→
maxWidth
- The maximum line width given using the active coordinate system.
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.
See Also
FntWordWrapReverseNLines Function
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 ( const char*pChars
, CoordmaxWidth
, uint32_t*linesToScrollP
, size_t*scrollPosP
)
Parameters
-
→ pChars
- A pointer to a null-terminated string.
-
→ maxWidth
- The maximum line width (in active coordinates).
-
↔
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
FontSelect Function
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 (
FontID fontID
)
Parameters
-
→ fontID
- A
FontID
value specifying the font to be highlighted as the default choice in the dialog that this function displays. This value must be one of the following system-supplied constants:
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 FntGetDefaultFontID()
to determine the default font as follows:
fntID =
FntGlueGetDefaultFontID(defaultSystemFont);