Fonts
 

 < 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.
<-> stringWidthPThe 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.
<-> stringLengthPThe 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.
<- fitWithinWidthUpon 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

-> charsPointer to a string of characters.
-> lenLength 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

-> fontAn 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.
-> fontPPointer 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

errNoneno error
memErrNotEnoughSpaceInsufficient 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

-> charsA null-terminated string.
-> widthThe width of a line of text in the display, given in pixels.
-> scrollPosThe byte offset of the first character displayed on the topmost line.
<- linesPNumber of lines required to display the string.
<- topLineThe 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

-> iCharCharacter 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.
-> lengthThe length in bytes of pChars.
-> pixelWidthA horizontal pixel offset from the beginning of the string.
<- leadingEdgeSet 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.
<- truncWidthThe 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

-> charsA pointer to a null-terminated string.
-> maxWidthThe 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

-> charsA pointer to a null-terminated string.
-> maxWidthThe maximum line width in pixels.
<-> linesToScrollPThe number of lines to scroll. Upon return, contains the number of lines that were scrolled.
<-> scrollPosPThe 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

-> fontIDA 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:
stdFontStandard plain text font.
boldFontBold version of stdFont.
largeFontA large plain text font (Japanese devices only).
largeBoldFontLarger 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