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, vol. I.
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 | 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. |
Result
Comments
Spaces and tabs at the end of a string are ignored and removed. Characters after a carriage return are ignored, and the string is considered truncated.
See Also
FntWidthToOffset
FntCharsWidth

Purpose
Return 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.
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 FntWCharWidth instead of this function on 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 76, "PalmOSGlue Library.".
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 single-byte value greater than fntAppFontCustomBase (currently 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 fntAppCustomBase because 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. |
-> 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
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 PalmTM.
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 | 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. |
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.
See Also
FldGetScrollValues
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.
New FntWCharWidth

Purpose
Returns 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 FntWCharWidth (WChar iChar)
Parameters
-> iChar | Character whose width is needed. |
Result
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 76, "PalmOSGlue Library."
See Also
FntCharWidth
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. |
-> 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 the returned offset. Pass NULL for this parameter if you don't need this information. |
Result
Returns the byte offset into pChars of the character that contains the pixel offset 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 | A pointer to a null-terminated string. |
-> maxWidth | The maximum line width in pixels. |
Result
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 typical following a space, tab, or line-feed character.
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 | 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. |
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 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 (Japanese devices only). |
largeBoldFont | Larger version of boldFont. |
Result
Returns a fontID value representing the font that the user chose in the dialog box that 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.
If you link with the PalmOSGlue library for backwards compatibility, you should instead call FntGlueGetDefaultFontID to determine the correct default font. For example:
fntID = FntGlueGetDefaultFontID(defaultSystemFont);
Compatibility
Implemented only if 3.0 New Feature Set is present. The sysFtrDefaultFont and sysFtrDefaultBoldFont features are implemented only if 3.1 New Feature Set is present.
See Also
FntGetFont, FntSetFont
|