< Home < Developers < Development Support < Documentation

## 34 Fonts

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 34 Fonts Font Functions FntAverageCharWidth FntBaseLine FntCharHeight FntCharsInWidth FntCharsWidth FntCharWidth FntDefineFont FntDescenderHeight FntGetFont FntGetFontPtr FntGetScrollValues FntLineHeight FntLineWidth FntSetFont FntWCharWidth FntWidthToOffset FntWordWrap FntWordWrapReverseNLines FontSelect |  |  |  | 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 #####
Returns nothing.
#### 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 #####
errNone | no error
#####
memErrNotEnoughSpace | Insufficient dynamic heap space
#### Comments The font this function specifies is not available at build time; as a result, some UI elements-labels, for example-cannot determine their bounds automatically as they do when using the built-in fonts. This mechanism and its associated tools may be augmented in the near future; for more information, stay in contact with 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 |