Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

29    Scalable Font Reference

User Interface

Exploring Palm OS®

This chapter provides the following information regarding scalable font support:

Scalable Font Structures and Types
Scalable Font Constants
Scalable Font Functions and Macros

The header file GcFont.h declares the API that this chapter describes. For more information on using fonts, see Chapter 5, "Displaying Text." For reference information on bitmapped fonts, see Chapter 13, "Bitmapped Font Reference."

Scalable Font Structures and Types ^TOP^

FAbsRectType Struct ^TOP^

Purpose

A rectangle describing the dimensions of a character or string of characters within a font.

Declared In

GcFont.h

Prototype

typedef struct FAbsRectType {
   fcoord_t left;
   fcoord_t top;
   fcoord_t right;
   fcoord_t bottom;
} FAbsRectType

Fields

left
x coordinate of the left side of the rectangle.
top
y coordinate of the top of the rectangle.
right
x coordinate of the right side of the rectangle.
bottom
y coordinate of the bottom of the rectangle.

Comments

The rectangle described by this type includes all coordinates from the top-left coordinate up to but not including the bottom-right coordinates.

See Also

GcGetFontBoundingBox(), GcFontStringBounds(), AbsRectType, RectangleType

FontFamily Typedef ^TOP^

Purpose

A string describing the font family.

Declared In

GcFont.h

Prototype

typedef char FontFamily[kFontFamilyLength + 1]

FontHeightType Struct ^TOP^

Purpose

Describes the vertical spacing of a font.

Declared In

GcFont.h

Prototype

typedef struct FontHeightType {
   fcoord_t ascent;
   fcoord_t descent;
   fcoord_t leading;
} FontHeightType

Fields

ascent
The distance in native coordinates from the top of the font rectangle to its baseline.
descent
The distance in native coordinates from the baseline to the bottom of the font rectangle.
leading
The vertical space between lines of text, in native coordinates.

See Also

GcGetFontHeight()

FontStyle Typedef ^TOP^

Purpose

A string describing the font's style.

Declared In

GcFont.h

Prototype

typedef char FontStyle[kFontStyleLength + 1]

GcFontHandle Struct ^TOP^

Purpose

The handle to a font. You pass this handle to all of the functions described in this chapter.

Declared In

GcFont.h

Prototype

typedef struct GcFontType *GcFontHandle

Fields

None.

See Also

GcCreateFont(), GcCreateFontFromFamily(), GcCreateFontFromID(), GcReleaseFont()

GcFontType Struct ^TOP^

Purpose

Private structure representing the font.

Declared In

GcFont.h

Prototype

struct GcFontType

Fields

None.

GcPointType Struct ^TOP^

Purpose

Represents a point.

Declared In

GcFont.h

Prototype

typedef struct {
   fcoord_t x;
   fcoord_t y;
} GcPointType

Fields

x
The x coordinate.
y
The y coordinate.

See Also

GcInitGradient()

Scalable Font Constants ^TOP^

GcAliasingTag Enum ^TOP^

Purpose

Specifies whether to use antialiasing.

Declared In

GcFont.h

Constants

kDisableAntialiasing = 0
Disable antialiasing. A pixel is only drawn if its center point lies within the current path.
kNormalAntialiasing = 1
Enable antialiasing. Pixels get a percentage of the color if any portion of the pixel lies within the current path.

See Also

GcSetAntialiasing(), GcGetFontAntialiasing(), GcSetFontAntialiasing()

Font Faces Enum ^TOP^

Purpose

Common font faces. A font face is a logical description of a style. You may specify a font face instead of trying to find the name of a desired font style.

Declared In

GcFont.h

Constants

kItalicFace = 0x0001
Italics or oblique.
kBoldFace = 0x0020
Bold.
kRegularFace = 0x0040
Plain.

See Also

GcSetFontFace(), GcGetFontFace()

Font Height Enum ^TOP^

Purpose

Invalid font height constant.

Declared In

GcFont.h

Constants

kInvalidFontHeight = -1
Invalid font height.

Font Name String Length Constants ^TOP^

Purpose

The lengths of the strings that store the font family and style.

Declared In

GcFont.h

Constants

#define kFontFamilyLength 63
The maximum length of the FontFamily string.
#define kFontStyleLength 63
The maximum length of the FontStyle string.

Scalable Font Functions and Macros ^TOP^

GcApplyFontSpec Function ^TOP^

Purpose

Applies a font specification to a particular font.

Declared In

GcFont.h

Prototype

status_t GcApplyFontSpec (
   GcFontHandle font,
   const char *fontSpec
)

Parameters

font
A handle to the font to which to apply the specification.
fontSpec
The attributes of a font. See the Comments section in GcCreateFont() for the syntax of a font specification string.

Returns

errNone upon success or one of the following values:

sysErrParamErr
fontSpec could not be parsed.
sysErrNoInit
The font has not been initialized.
sysErrNameNotFound
fontSpec has an invalid family name.

Comments

You can use this function to modify an existing font. For example, you could use this function to apply the bold style to the current font family.

See Also

GcCreateFont(), GcSetFontFace(), GcSetFontSize(), GcSetFontStyle()

GcCheckFont Function ^TOP^

Purpose

Verifies that the font handle is valid.

Declared In

GcFont.h

Prototype

status_t GcCheckFont (
   GcFontHandle font
)

Parameters

font
A font handle.

Returns

errNone if the font is valid, or one of the following errors:

sysErrNoInit
The font has not been initialized.
sysErrNameNotFound
The font cannot be found.

GcCountFontFamilies Function ^TOP^

Purpose

Returns the number of font families installed in the system.

Declared In

GcFont.h

Prototype

int32_t GcCountFontFamilies (
   void
)

Parameters

None.

Returns

The number of font families installed in the system.

See Also

GcGetFontFamily()

GcCountFontStyles Function ^TOP^

Purpose

Returns the number of font styles (such as "Italic" or "Bold") available for the specified family.

Declared In

GcFont.h

Prototype

int32_t GcCountFontStyles (
   const char *family
)

Parameters

family
The name of a font family installed in the system.

Returns

The number of different styles defined for the font, or 0 if the font family cannot be found.

See Also

GcSetFontStyle(), GcGetFontStyle()

GcCreateFont Function ^TOP^

Purpose

Returns a font handle given a fully specified font.

Declared In

GcFont.h

Prototype

GcFontHandle GcCreateFont (
   const char *fontSpec
)

Parameters

fontSpec
A CSS-style font specification. See the "Comments" section.

Returns

The handle to the specified font or NULL if the font can't be found.

Comments

A font specification is a CSS-style text string describing the font characteristics. This string has the following format:

[face] [size[/lineHeight]] family [, [size[/
lineHeight]] alternateFamily ]

where:

face
The name of a font face such as "regular" or "italic." You can specify one of the following strings:
100, 200, ... 900
Specifies a level of darkness where each value is a degree darker than the previous level or at least as dark as the previous level. 400 specifies the normal face, and 700 specifies the bold face.
normal
Applies the regular face of the family to the current specification.
bold
Applies the bold face to the current specification.
bolder
Makes the current font one degree darker.
lighter
Makes the current font a degree lighter.
italic
Applies an italic face to the current specification.
oblique
Applies an italic face to the current specification.
small-caps
No change.
In the current implementation, the varying degrees of darkness are not implemented. 100 through 500 specify the regular font face, and 600 through 900 specify the bold font face.
size
A numeric value specifying the size, followed by px for native coordinates or db for standard coordinates.

IMPORTANT: Do not use the standard CSS "pt" units.
The size can also be a relative value from the current size, expressed as a percentage (50%) or one of the following:
xx-small
x-small
small
medium
large
x-large
xx-large
The size can also be one of the following relative sizes to make a font larger or smaller than it currently is:
larger
smaller
lineHeight
Not currently used.
family
Specifies the font family such as "Albany" or "Times." If the name contains spaces, it must be contained in single or double quotes (' ' or " ").
alternateFamily
Specifies the name of an alternative font family to use if the family cannot be found.

The family and alternateFamily can also be one of the following system standard fonts:

  • "palmos-plain"
  • "palmos-bold"
  • "palmos-large-plain"
  • "palmos-large-bold"

These four fonts are not equivalent to the similarly named system-defined bitmapped fonts unless the device does not have a scalable font engine installed. Instead, these are TrueType fonts.

If you always specify one of the system-defined fonts as at least an alternate family, then GcCreateFont() always returns a non-NULL handle.

The system does not treat the fontSpec as an exact list of requirements. In some cases, it may return a close match if, for example, the font won't scale well to the requested size. The application must deal gracefully with the font returned by this function and not assume that all specifications have been met.

When you are finished with the font, use GcReleaseFont() to release the memory associated with it.

Example

The following code draws text in the Cumberland font if it exists. If not, it uses the system-defined plain font.


GcHandle gcH; 
GcFontHandle myFontH; 
char *string = "Hi, Mom!"; 
 
myFontH = GcCreateFont("bold 9db 'Cumberland AMT', palmos-
plain"); 
... 
gcH = GcGetCurrentContext(); 
if (gcH) { 
   GcSetFont(gcH, myFontH); 
   GcSetCoordinateSystem(gcH, kCoordinatesNative); 
   GcDrawTextAt(gcH, 160, 100, string, strlen(string)); 
   GcReleaseContext(gcH); 
} 
GcReleaseFont(myFontH); 

See Also

GcCreateFontFromFamily(), GcCreateFontFromID(), GcApplyFontSpec()

GcCreateFontFromFamily Function ^TOP^

Purpose

Returns a font handle given a font family.

Declared In

GcFont.h

Prototype

GcFontHandle GcCreateFontFromFamily (
   const char *family
)

Parameters

family
The name of a font family.

Returns

A handle to the specified font. Returns NULL if it cannot find a font with the specified family or it cannot create a handle for the font.

Comments

The font returned by this function uses the default style for the specified family and a size of 0. For example, if you specify "Helvetica" as the font family, the returned font uses the Helvetica plain style. You'll want to use GcSetFontSize() to specify a size. You can also change the style later.

When you are finished with the font, use GcReleaseFont() to release the memory associated with it.

See Also

GcGetFontFamily()

GcCreateFontFromID Function ^TOP^

Purpose

Create a font handle for a bitmapped font.

Declared In

GcFont.h

Prototype

GcFontHandle GcCreateFontFromID (
   FontID id
)

Parameters

id
The FontID of a bitmapped font.

Returns

A font handle for the specified font. Returns NULL if the specified font cannot be found or there was a problem creating the font handle.

Comments

You can use this function to manipulate a bitmapped font as you would a scalable font. The returned font uses the size and style specified in the bitmapped font version; however, you can use the functions described in this chapter to resize or transform the font in any way that you want.

You still must use the returned font only with the GcDrawTextAt() function.

When you are finished with the font, use GcReleaseFont() to release the memory associated with it.

See Also

FntGetFont()

GcFontStringBounds Function ^TOP^

Purpose

Returns the bounds of a string if displayed in the specified font.

Declared In

GcFont.h

Prototype

status_t GcFontStringBounds (
   GcFontHandle font,
   const char *string,
   size_t length,
   FAbsRectType *outBounds
)

Parameters

font
A handle to a font.
string
A string.
length
The length of the string. This can be less than the actual length of the string to determine the bounds of displaying a substring.
outBounds
An FAbsRectType rectangle giving the dimensions of the string in native coordinates if it were displayed in the specified font.

Returns

Always returns errNone.

See Also

GcFontStringWidth()

GcFontStringBytesInWidth Function ^TOP^

Purpose

Returns the size in bytes of the substring that can be displayed in a specified width.

Declared In

GcFont.h

Prototype

size_t GcFontStringBytesInWidth (
   GcFontHandle font,
   const char *string,
   size_t maxWidth
)

Parameters

font
A handle to a font.
string
A string.
maxWidth
The maximum width given in native coordinates in which to display the string.

Returns

The number of bytes of full characters from string that can be displayed in maxWidth.

See Also

GcFontStringBytesInWidth()

GcFontStringCharsInWidth Function ^TOP^

Purpose

Returns the number of characters that can be displayed in a specified width.

Declared In

GcFont.h

Prototype

size_t GcFontStringCharsInWidth (
   GcFontHandle font,
   const char *string,
   size_t maxWidth
)

Parameters

font
A handle to a font.
string
A string.
maxWidth
The maximum width given in native coordinates in which to display the string.

Returns

The number of glyphs that can be displayed in the width. This return value means that the first n characters you can obtain from string can be displayed within the specified width.


IMPORTANT: The return value does not equal the number of bytes in string that can be displayed. A character within a string may be either a single byte long or multiple bytes long.

See Also

GcFontStringBytesInWidth()

GcFontStringEscapement Function ^TOP^

Purpose

Returns the dimensions of the string when displayed in the specified font.

Declared In

GcFont.h

Prototype

void GcFontStringEscapement (
   GcFontHandle font,
   const char *string,
   size_t length,
   GcPointType *outEscapement
)

Parameters

font
A handle to a font.
string
A string.
length
The length of the string. This can be less than the total number of bytes in the string if you want to find out the width of a prefix of string.
outEscapement
The dimensions of the string, both width and height, in native coordinates.

Returns

None.

GcFontStringWidth Function ^TOP^

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

GcFont.h

Prototype

fcoord_t GcFontStringWidth (
   GcFontHandle font,
   const char *string,
   size_t length
)

Parameters

font
A handle to a font.
string
A string.
length
The length of the string. This can be less than the total number of bytes in the string if you want to find out the width of a prefix of string.

Returns

The width in native coordinates required to display the string in its entirety.

See Also

GcFontStringBounds()

GcGetFontAntialiasing Function ^TOP^

Purpose

Returns whether antialiasing is used when drawing text.

Declared In

GcFont.h

Prototype

uint32_t GcGetFontAntialiasing (
   GcFontHandle font
)

Parameters

font
A handle to a font.

Returns

One of the GcAliasingTag constants.

See Also

GcSetAntialiasing(), GcSetFontAntialiasing()

GcGetFontBoundingBox Function ^TOP^

Purpose

Returns a rectangle specifying an average character's dimensions in the specified font.

Declared In

GcFont.h

Prototype

status_t GcGetFontBoundingBox (
   GcFontHandle font,
   FAbsRectType *bbox
)

Parameters

font
A handle to a font.
bbox
An FAbsRectType, which describes the dimensions of a character in the font.

Returns

errNone upon success or sysErrParamErr if bbox is NULL.

Comments

The returned dimensions give the average character width and the tallest possible characters in the font including any ascenders and descenders. Most characters will be shorter than the dimensions returned here, and they may be narrower or wider.

See Also

GcGetFontHeight()

GcGetFontFace Function ^TOP^

Purpose

Returns the face currently used in the font.

Declared In

GcFont.h

Prototype

uint16_t GcGetFontFace (
   GcFontHandle font
)

Parameters

font
A handle to a font.

Returns

One of the Font Faces.

See Also

GcSetFontFace()

GcGetFontFamily Function ^TOP^

Purpose

Returns a font family given its index into the system's font family list.

Declared In

GcFont.h

Prototype

status_t GcGetFontFamily (
   int32_t index,
   FontFamily *family
)

Parameters

index
An index into the font family list. Families are indexed from 0 to GcCountFontFamilies()–1.
family
The name of the font family at index.

Returns

errNone if the family was found or sysErrBadIndex if the family cannot be found.

Comments

Use this function in conjunction with GcCountFontFamilies() to iterate through the system's list of font families.

See Also

GcCreateFontFromFamily()

GcGetFontFamilyAndStyle Function ^TOP^

Purpose

Returns the family and style of the specified font.

Declared In

GcFont.h

Prototype

status_t GcGetFontFamilyAndStyle (
   GcFontHandle font,
   FontFamily *family,
   FontStyle *style
)

Parameters

font
A handle to a font.
family
The font's family.
style
The font's style.

Returns

errNone upon success or one of the following:

sysErrParamErr
If family or style is NULL.

See Also

GcGetFontFamily(), GcGetFontStyle()

GcGetFontHeight Function ^TOP^

Purpose

Returns the font's height at its current size.

Declared In

GcFont.h

Prototype

status_t GcGetFontHeight (
   GcFontHandle font,
   struct FontHeightType *height
)

Parameters

font
A handle to a font.
height
A FontHeightType structure.

Returns

errNone upon success, or one of the following errors:

sysErrNoInit
The font has not been initialized.
sysErrNameNotFound
The font cannot be found.

GcGetFontHinting Function ^TOP^

Purpose

Returns whether font hinting is enabled or disabled.

Declared In

GcFont.h

Prototype

Boolean GcGetFontHinting (
   GcFontHandle font
)

Parameters

font
A handle to a font.

Returns

true if font hinting is enabled, meaning that glyphs are drawn so that their lines are always on exact pixel boundaries. false if the path of a glyph may land on sub-pixel boundaries.

Comments

Characters are always positioned on exact pixel boundaries. Font hinting controls wether the rest of a glyph's path lies on exact pixel boundaries. If enabled, characters in a string may be drawn wider than when text hinting is off.

See Also

GcSetFontHinting()

GcGetFontSize Function ^TOP^

Purpose

Returns the size of the font.

Declared In

GcFont.h

Prototype

fcoord_t GcGetFontSize (
   GcFontHandle font
)

Parameters

font
A handle to a font.

Returns

The font size in native coordinates.

See Also

GcSetFontSize()

GcGetFontStyle Function ^TOP^

Purpose

Returns the style (such as "Regular" or "Bold") stored at a given index within the font family.

Declared In

GcFont.h

Prototype

status_t GcGetFontStyle (
   const char *family,
   int32_t index,
   FontStyle *style
)

Parameters

family
The name of a font family installed on the device.
index
An index into the font family's list of styles. Styles are indexed from 0 to GcCountFontStyles()–1.
style
Upon return, a string containing the style name.

Returns

errNone upon success or one of the following:

sysErrBadIndex
The style cannot be found.
sysErrNameNotFound
The specified family does not exist.

Comments

Use this function in conjunction with GcCountFontStyles() to iterate through the list of available styles for a font family.

See Also

GcGetFontFamily()

GcGetFontTransform Function ^TOP^

Purpose

Returns the font's transformation.

Declared In

GcFont.h

Prototype

status_t GcGetFontTransform (
   GcFontHandle font,
   fcoord_t *out_matrix
)

Parameters

font
A handle to a font.
out_matrix
An array of four elements that specify the transformation matrix. See GcTransform() for more information about the transformation matrix.

Returns

Always returns errNone.

Comments

This transformation is applied when text is rendered to the screen with the font.

See Also

GcSetFontTransform()

GcReleaseFont Function ^TOP^

Purpose

Frees the memory associated with the font handle.

Declared In

GcFont.h

Prototype

void GcReleaseFont (
   GcFontHandle font
)

Parameters

font
The font handle to free.

Returns

Nothing.

GcSetFontAntialiasing Function ^TOP^

Purpose

Specifies whether the rendering system uses antialiasing when drawing text with the specified font.

Declared In

GcFont.h

Prototype

status_t GcSetFontAntialiasing (
   GcFontHandle font,
   uint32_t value
)

Parameters

font
A handle to a font.
value
One of the GcAliasingTag values.

Returns

Always returns errNone.

Comments

You rarely need to use this function. Do so only if you are creating a drawing application and want more control over the quality of the rendered image. The default value for text antialiasing suffices in most cases.

See Also

GcSetAntialiasing()

GcSetFontFace Function ^TOP^

Purpose

Sets the font to the closest match to the specified flags.

Declared In

GcFont.h

Prototype

status_t GcSetFontFace (
   GcFontHandle font,
   uint16_t face
)

Parameters

font
A handle to a font.
face
One of the Font Faces.

Returns

errNone upon success or one of the following:

sysErrParamErr
The font handle is invalid.
sysErrNameNotFound
The font family for font cannot be found.

Comments

If the font does not support the specified face, this function returns errNone, and the font is set to use the face that is considered the closest possible match. This may be the regular face.

See Also

GcGetFontFace()

GcSetFontHinting Function ^TOP^

Purpose

Enables or disables font hinting. If hinting is enabled, letters are drawn to exact pixel boundaries.

Declared In

GcFont.h

Prototype

status_t GcSetFontHinting (
   GcFontHandle font,
   Boolean enabled
)

Parameters

font
A handle to a font.
enabled
If true, enables hinting for the font so that the glyph's path is aligned to exact pixel boundaries. If false, disable font hinting.

Returns

Always returns errNone.

Comments

Characters are always positioned on exact pixel boundaries. Font hinting controls wether the rest of a glyph's path lies on exact pixel boundaries. If enabled, characters in a string may be drawn wider than when text hinting is off.

GcSetFontSize Function ^TOP^

Purpose

Sets the font to a specified size.

Declared In

GcFont.h

Prototype

status_t GcSetFontSize (
   GcFontHandle font,
   fcoord_t size
)

Parameters

font
A handle to a font.
size
A size given in native coordinates.

Returns

Always returns errNone.

See Also

GcGetFontSize()

GcSetFontStyle Function ^TOP^

Purpose

Sets the font to use the specified style (such as "Regular" or "Bold").

Declared In

GcFont.h

Prototype

status_t GcSetFontStyle (
   GcFontHandle font,
   const char *style
)

Parameters

font
A handle to a font.
style
A string containing a font style. This style must be valid for the specified font.

Returns

errNone upon success or sysErrParamErr if the style is not supported by the font.

See Also

GcGetFontStyle(), GcSetFontFace()

GcSetFontTransform Function ^TOP^

Purpose

Applies a general transformation matrix to the font.

Declared In

GcFont.h

Prototype

status_t GcSetFontTransform (
   GcFontHandle font,
   const fcoord_t *matrix
)

Parameters

font
A handle to the font.
matrix
An array of four elements. See GcTransform() for more information about the transformation matrix.

Returns

Always returns errNone.

Comments

The matrix that is applied is considered to be a 2 X 2 matrix.

This transformation is applied when text is rendered to the screen with the font.

See Also

GcGetFontTransform()