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
FontCharInfoPtr Typedef
Purpose
The FontCharInfoPtr
type points to a FontCharInfoType
structure.
Prototype
typedef FontCharInfoType *FontCharInfoPtr;
FontCharInfoType Struct
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()
orFntCharWidth()
.
FontDensityType Struct
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
, orkDensityDouble
. -
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
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
Purpose
The FontPtr
type defines a pointer to a FontType
structure.
Prototype
typedef FontType *FontPtr;
FontType Struct
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. UseFntWCharWidth()
orFntCharWidth()
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
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;
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. UseFntWCharWidth()
orFntCharWidth()
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
Font Resources
Font Resource
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
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 37.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 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. |
|
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
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
FntAverageCharWidth Function
Purpose
Gets the maximum character width in pixels of the current font.
Declared In
Font.h
Prototype
Int16 FntAverageCharWidth ( void )
Parameters
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
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
Returns
Returns the ascent of the font (in pixels).
FntCharHeight Function
Purpose
Gets the character height of the current font including accents and descenders.
Declared In
Font.h
Prototype
Int16 FntCharHeight ( void )
Parameters
Returns
Returns the height of the characters in the current font, expressed in pixels.
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 ( Char const *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
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
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 ( Char const *chars, Int16 len )
Parameters
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 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
Int16 FntCharWidth ( Char ch )
Parameters
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
FntDefineFont Function
Purpose
Makes a custom font available to your application.
Declared In
Font.h
Prototype
Err FntDefineFont ( FontID font, FontPtr 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
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
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
Int16 FntDescenderHeight ( void )
Parameters
Returns
Returns the height of a descender, expressed in pixels.
FntGetFont Function
Purpose
Gets the font ID of the current font.
Declared In
Font.h
Prototype
FontID FntGetFont ( void )
Parameters
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
Purpose
Gets a pointer to the current font.
Declared In
Font.h
Prototype
FontPtr FntGetFontPtr ( void )
Parameters
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
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 ( Char const *chars, UInt16 width, UInt16 scrollPos, 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
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
Int16 FntLineHeight ( void )
Parameters
Returns
Returns the height in pixels of a line in the current font.
FntLineWidth Function
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 ( Char const *pChars, UInt16 length )
Parameters
Returns
Returns the line width (in pixels).
FntSetFont Function
Purpose
Declared In
Font.h
Prototype
FontID FntSetFont ( FontID font )
Parameters
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
FntWCharWidth 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
Int16 FntWCharWidth ( WChar iChar )
Parameters
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
FntWidthToOffset Function
Purpose
Given a pixel position, gets the offset of the character displayed at that location.
Declared In
Font.h
Prototype
Int16 FntWidthToOffset ( Char const *pChars, UInt16 length, Int16 pixelWidth, 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 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 (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
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 ( Char const *chars, UInt16 maxWidth )
Parameters
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
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( Char const *const chars, UInt16 maxWidth, 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
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 box that this function displays. This value must be one of the following system-supplied constants:
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.