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
FAbsRectType Struct
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
Purpose
A string describing the font family.
Declared In
GcFont.h
Prototype
typedef char FontFamily[kFontFamilyLength + 1]
FontHeightType Struct
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
FontStyle Typedef
Purpose
A string describing the font's style.
Declared In
GcFont.h
Prototype
typedef char FontStyle[kFontStyleLength + 1]
GcFontHandle Struct
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
See Also
GcCreateFont()
, GcCreateFontFromFamily()
, GcCreateFontFromID()
, GcReleaseFont()
GcFontType Struct
Purpose
Private structure representing the font.
Declared In
GcFont.h
Prototype
struct GcFontType
Fields
GcPointType Struct
Purpose
Declared In
GcFont.h
Prototype
typedef struct { fcoord_t x; fcoord_t y; } GcPointType
Fields
See Also
Scalable Font Constants
GcAliasingTag Enum
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
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
See Also
GcSetFontFace()
, GcGetFontFace()
Font Height Enum
Purpose
Declared In
GcFont.h
Constants
Font Name String Length Constants
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
GcApplyFontSpec Function
Purpose
Applies a font specification to a particular font.
Declared In
GcFont.h
Prototype
status_t GcApplyFontSpec ( GcFontHandlefont
, 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
Purpose
Verifies that the font handle is valid.
Declared In
GcFont.h
Prototype
status_t GcCheckFont (
GcFontHandle font
)
Parameters
Returns
errNone
if the font is valid, or one of the following errors:
GcCountFontFamilies Function
Purpose
Returns the number of font families installed in the system.
Declared In
GcFont.h
Prototype
int32_t GcCountFontFamilies ( void )
Parameters
Returns
The number of font families installed in the system.
See Also
GcCountFontStyles Function
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
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
Purpose
Returns a font handle given a fully specified font.
Declared In
GcFont.h
Prototype
GcFontHandle GcCreateFont (
const char *fontSpec
)
Parameters
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 ]
-
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 ordb
for standard coordinates.
- The size can also be a relative value from the current size, expressed as a percentage (
50%
) or one of the following: - The size can also be one of the following relative sizes to make a font larger or smaller than it currently is:
-
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:
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
Purpose
Returns a font handle given a font family.
Declared In
GcFont.h
Prototype
GcFontHandle GcCreateFontFromFamily (
const char *family
)
Parameters
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
GcCreateFontFromID Function
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
GcFontStringBounds Function
Purpose
Returns the bounds of a string if displayed in the specified font.
Declared In
GcFont.h
Prototype
status_t GcFontStringBounds ( GcFontHandlefont
, const char*string
, size_tlength
, 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
See Also
GcFontStringBytesInWidth Function
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 ( GcFontHandlefont
, const char*string
, size_tmaxWidth
)
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
GcFontStringCharsInWidth Function
Purpose
Returns the number of characters that can be displayed in a specified width.
Declared In
GcFont.h
Prototype
size_t GcFontStringCharsInWidth ( GcFontHandlefont
, const char*string
, size_tmaxWidth
)
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
GcFontStringEscapement Function
Purpose
Returns the dimensions of the string when displayed in the specified font.
Declared In
GcFont.h
Prototype
void GcFontStringEscapement ( GcFontHandlefont
, const char*string
, size_tlength
, 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
GcFontStringWidth 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
GcFont.h
Prototype
fcoord_t GcFontStringWidth ( GcFontHandlefont
, const char*string
, size_tlength
)
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
GcGetFontAntialiasing Function
Purpose
Returns whether antialiasing is used when drawing text.
Declared In
GcFont.h
Prototype
uint32_t GcGetFontAntialiasing (
GcFontHandle font
)
Parameters
Returns
One of the GcAliasingTag
constants.
See Also
GcSetAntialiasing()
, GcSetFontAntialiasing()
GcGetFontBoundingBox Function
Purpose
Returns a rectangle specifying an average character's dimensions in the specified font.
Declared In
GcFont.h
Prototype
status_t GcGetFontBoundingBox ( GcFontHandlefont
, 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
GcGetFontFace Function
Purpose
Returns the face currently used in the font.
Declared In
GcFont.h
Prototype
uint16_t GcGetFontFace (
GcFontHandle font
)
Parameters
Returns
One of the Font Faces.
See Also
GcGetFontFamily Function
Purpose
Returns a font family given its index into the system's font family list.
Declared In
GcFont.h
Prototype
status_t GcGetFontFamily ( int32_tindex
, 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
GcGetFontFamilyAndStyle Function
Purpose
Returns the family and style of the specified font.
Declared In
GcFont.h
Prototype
status_t GcGetFontFamilyAndStyle ( GcFontHandlefont
, FontFamily*family
, FontStyle*style
)
Parameters
Returns
errNone
upon success or one of the following:
See Also
GcGetFontFamily()
, GcGetFontStyle()
GcGetFontHeight Function
Purpose
Returns the font's height at its current size.
Declared In
GcFont.h
Prototype
status_t GcGetFontHeight ( GcFontHandlefont
, struct FontHeightType*height
)
Parameters
-
→ font
- A handle to a font.
-
← height
- A
FontHeightType
structure.
Returns
errNone
upon success, or one of the following errors:
GcGetFontHinting Function
Purpose
Returns whether font hinting is enabled or disabled.
Declared In
GcFont.h
Prototype
Boolean GcGetFontHinting (
GcFontHandle font
)
Parameters
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
GcGetFontSize Function
Purpose
Declared In
GcFont.h
Prototype
fcoord_t GcGetFontSize (
GcFontHandle font
)
Parameters
Returns
The font size in native coordinates.
See Also
GcGetFontStyle Function
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_tindex
, 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:
Comments
Use this function in conjunction with GcCountFontStyles()
to iterate through the list of available styles for a font family.
See Also
GcGetFontTransform Function
Purpose
Returns the font's transformation.
Declared In
GcFont.h
Prototype
status_t GcGetFontTransform ( GcFontHandlefont
, 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
Comments
This transformation is applied when text is rendered to the screen with the font.
See Also
GcReleaseFont Function
Purpose
Frees the memory associated with the font handle.
Declared In
GcFont.h
Prototype
void GcReleaseFont (
GcFontHandle font
)
Parameters
Returns
GcSetFontAntialiasing Function
Purpose
Specifies whether the rendering system uses antialiasing when drawing text with the specified font.
Declared In
GcFont.h
Prototype
status_t GcSetFontAntialiasing ( GcFontHandlefont
, uint32_tvalue
)
Parameters
-
→ font
- A handle to a font.
-
→ value
- One of the
GcAliasingTag
values.
Returns
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
GcSetFontFace Function
Purpose
Sets the font to the closest match to the specified flags.
Declared In
GcFont.h
Prototype
status_t GcSetFontFace ( GcFontHandlefont
, uint16_tface
)
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
GcSetFontHinting Function
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 ( GcFontHandlefont
, Booleanenabled
)
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. Iffalse
, disable font hinting.
Returns
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
Purpose
Sets the font to a specified size.
Declared In
GcFont.h
Prototype
status_t GcSetFontSize ( GcFontHandlefont
, fcoord_tsize
)
Parameters
Returns
See Also
GcSetFontStyle Function
Purpose
Sets the font to use the specified style (such as "Regular" or "Bold").
Declared In
GcFont.h
Prototype
status_t GcSetFontStyle ( GcFontHandlefont
, 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
Purpose
Applies a general transformation matrix to the font.
Declared In
GcFont.h
Prototype
status_t GcSetFontTransform ( GcFontHandlefont
, 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
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.