SHOW Signed

net.rim.device.api.ui
Class Font

java.lang.Object
  |
  +--net.rim.device.api.ui.Font

public abstract class Font

extends Object

Encapsulates a specific set of character glyphs.

Font also contains metrics, since rendering characteristics are not abstracted on small device platforms. Currently, the font system assumes that all Fonts have roman baselines (characters read horizontally, and bottom align on the baseline).

Font construction
Characters are layed out as follows. The nearby diagram shows the pixels consumed by two glyhps ('Ig'). Notice that each glyph consumes pixels that are never used to draw the glyph itself. A line of one pixel along the top is used for the line leading (to ensure vertical space between lines of glyphs). In addtion, each glyph also has one or more columns of empty pixels to its right reserved to preserve horizontal space between glyphs.

The horizontal space taken up by the glyph itself is called the glyph width. More important is the total width used to display the glyph, called the advance.

The total vertical space used to display the glyph (the block height is equal to the leading plus the ascent (the space reserved to draw the glyph above the baseline) plus the descent (the space reserved to draw the glyph below the baseline). Notice that even glyphs that do not use any descent pixels still reserve them to preserve the baseline position across a line of text.

Font sizes always refer to the font's block height (in the case of the shown example, 10), and are always measured in pixels.

Italic text
Note that the blocks of italic glyphs form a parallelogram, not a rectangle. The blocks lean over to ensure that italic characters positioned next to one another kern properly. However, the advance of the glyph is still the distance between one side of the block and the other (and not measured from bottom-left across to a vertical line dropped from top-right corner).

This means that a non-italic glyph rendered just right of an italic glyph may occlude the leaning corner of the italic glyph.

Field Summary

	static int	APPLICATION In a global event, check this flag to see if the change was an application or a global one.
	static int	BOLD Bold font style modifier
	static int	DOTTED_UNDERLINED Dotted underlined font style modifier (UNDERLINED must be specified as well)
	static long	GUID_FONT_CHANGED The GUID for the global event sent when the system font changes.
	static int	ITALIC Italic font style modifier
	static int	PLAIN Plain font style
	static int	UNDERLINED Underlined font style modifier

Method Summary

	Font	derive(int style) Derives a font with a given style and the current size.
	Font	derive(int style, int height) Derives a font of a given style and size.
	abstract int	getAdvance(char ch) Determines particular glyph advance.
	abstract int	getAdvance(char[] text, int offset, int length) Determines width of a character array's substring.
	int	getAdvance(String text) Determines advance of a text string.
	abstract int	getAdvance(StringBuffer text, int offset, int length) Determines width of a string buffer's substring.
	abstract int	getAdvance(String text, int offset, int length) Determines width of a text string's substring.
	int	getAscent() Retrieves this font's ascent height.
	int	getBaseline() Retrieve this font's baseline position.
	static Font	getDefault() Retrieves the default font.
	int	getDescent() Retrieves this font's descender height.
	FontFamily	getFontFamily() Retrieves the font family containing this font.
	int	getHeight() Retrieves this font's height.
	int	getLeading() Retrieve this font's leading.
	int	getStyle() Retrieves this font's style.
	boolean	isBold() Indicates if this font is bold.
	boolean	isItalic() Indicates if this font is italic.
	boolean	isPlain() Indicates if this font is plain.
	boolean	isUnderlined() Indicates if this font is underlined.
	static void	setDefaultFont(Font defaultFont) Sets the default font for this application.
	String	toString() Retrieves font name as a string.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

PLAIN

public static final int PLAIN

Plain font style

BOLD

public static final int BOLD

Bold font style modifier

ITALIC

public static final int ITALIC

Italic font style modifier

UNDERLINED

public static final int UNDERLINED

Underlined font style modifier

DOTTED_UNDERLINED

public static final int DOTTED_UNDERLINED

Dotted underlined font style modifier (UNDERLINED must be specified as well)

GUID_FONT_CHANGED

public static final long GUID_FONT_CHANGED

The GUID for the global event sent when the system font changes.

APPLICATION

public static final int APPLICATION

In a global event, check this flag to see if the change was an application or a global one.

Method Detail

derive

public Font derive(int style)

Derives a font with a given style and the current size.

Use derive to retrieve a new font derived from this font. For isntance, if this font is a plain font, you can retrieve the bold version with derive(this.BOLD).

This method doesn't make up new fonts out of whole cloth: if the font doesn't already exist in the system, then this method simply returns this font.

Parameters:

style - New style desired.

Returns:

Derived font, if it exists; otherwise, returns this font.

Since:

JDE 3.6

derive

public Font derive(int style,
                   int height)

Derives a font of a given style and size.

Like derive(int), except you can also specify a new font size as well as style.

Parameters:

style - New style desired.

height - New height desired.

Returns:

Derived font, if it exists; otherwise, returns this font.

Since:

JDE 3.6

See Also:

derive(int)

getAscent

public int getAscent()

Retrieves this font's ascent height.

Use this method to retrieve the height, in pixels, reserved for drawing glyphs above the baseline.

Returns:

This font's ascent height.

getBaseline

public int getBaseline()

Retrieve this font's baseline position.

Use this method to retrieve the position of this font's baseline, in pixels from the top of the font.

Notice that this.getBaseline - this.getAscent produces the amount of leading at the top of this font.

Returns:

Baseline position, in pixels from the top.

getDefault

public static Font getDefault()

Retrieves the default font.

If the current application doesn't have a default font, it automatically inherits (and this method returns) the current system font.

Returns:

The application's current default font. If no default is set for the application, return the system font. If the system font cannot be found, then return null (this should be treated as an unrecoverable error).

getDescent

public int getDescent()

Retrieves this font's descender height.

Use this method to retrieve the height, in pixels, reserved for drawing glyphs below the baseline.

Returns:

This font's descent height.

getFontFamily

public FontFamily getFontFamily()

Retrieves the font family containing this font.

Returns:

Font family object for this current font.

getHeight

public int getHeight()

Retrieves this font's height.

Use this method to retrieve this font's "block" height (the drawing area for glyphs plus the leading).

Returns:

Height of this font in pixels.

getLeading

public int getLeading()

Retrieve this font's leading.

Use this method to retrieve this font's leading (pixels in font blocks reserved for inter-line spacing). In our font system, a font's leading height is drawn at the top of the font "block" height.

Returns:

Leading of this font in pixels.

getStyle

public int getStyle()

Retrieves this font's style.

Use this method to retrieve a bitfield formed from a combination of font style modifiers (BOLD, ITALIC, PLAIN, UNDERLINED).

Returns:

Bitfield containing this font's style.

See Also:

isBold(), isItalic(), isPlain()

getAdvance

public abstract int getAdvance(char ch)

Determines particular glyph advance.

Use this method to determine the advance (in pixels) of a specified glyph in this font's character set.

Parameters:

ch - Character glyph for which to calculate width.

Returns:

Pixels advanced by specified glyph.

Since:

JDE 3.6

getAdvance

public final int getAdvance(String text)

Determines advance of a text string.

Use this method to calculate the advance (in pixels) of a provided string drawn with this font.

Parameters:

text - String for which to calculate width (may be null).

Returns:

Pixels advanced by specified text string. If text parameter is null, this method returns 0.

Since:

JDE 3.6

getAdvance

public abstract int getAdvance(String text,
                               int offset,
                               int length)
                        throws IllegalArgumentException

Determines width of a text string's substring.

Use this method to calculate the advance (in pixels) of a substring drawn with this font.

Parameters:

text - String for which to calculate a width (may be null).

offset - Character offset into the string to use as start of substring.

length - Length of substring.

Returns:

Pixels advanced by the specified substring. If text parameter is null, this method returns 0.

Throws:

IllegalArgumentException - If substring specified with offset/length parameters wouldn't fit in provided string.

Since:

JDE 3.6

getAdvance

public abstract int getAdvance(StringBuffer text,
                               int offset,
                               int length)
                        throws IllegalArgumentException

Determines width of a string buffer's substring.

Use this method to calculate the width (in pixels) of a substring of a string buffer in this font's character set.

Subclasses must implement this method as appropriate for their glyphs. Implementations should throw ArrayIndexOutOfBoundsException for substrings that violate the length of the string buffer.

Parameters:

text - String buffer for which to calculate a width (may be null).

offset - Character offset into the string buffer to use as start of substring.

length - Length of substring.

Returns:

Pixels of width used by specified substring. If text parameter is null, this method returns 0.

Throws:

IllegalArgumentException - If substring specified with offset/length parameters wouldn't fit in provided string.

Since:

JDE 3.6

getAdvance

public abstract int getAdvance(char[] text,
                               int offset,
                               int length)
                        throws IllegalArgumentException

Determines width of a character array's substring.

Use this method to calculate the width (in pixels) of a substring of a character array in this font's character set.

Subclasses must implement this method as appropriate for their glyphs. Implementations should throw ArrayIndexOutOfBoundsException for substrings that violate the length of the string buffer.

Parameters:

text - Character arry for which to calculate a width (may be null).

offset - Array element to use as start of substring.

length - Length of substring.

Returns:

Pixels of width used by specified substring. If text parameter is null, this method returns 0.

Throws:

IllegalArgumentException - If substring specified with offset/length parameters wouldn't fit in provided string.

Since:

JDE 3.6

isBold

public boolean isBold()

Indicates if this font is bold.

Returns:

True if this font has the BOLD style; otherwise, false.

isItalic

public boolean isItalic()

Indicates if this font is italic.

Returns:

True if this font has the ITALIC style; otherwise, false.

isUnderlined

public boolean isUnderlined()

Indicates if this font is underlined.

Returns:

True if this font has the UNDERLINED style; otherwise false.

isPlain

public boolean isPlain()

Indicates if this font is plain.

Returns:

True if this font has the PLAIN style; otherwise false.

setDefaultFont

public static void setDefaultFont(Font defaultFont)

Sets the default font for this application.

Parameters:

defaultFont - Font to set as default; if null, application inherits the default system font.

Since:

JDE 3.6

toString

public String toString()

Retrieves font name as a string.

You should not use this method to compare two fonts, particularly because the style value is internationalized and therefore changes from locale to locale.

Overrides:

toString in class Object

Returns:

Combination of the family name, size (in pixels), and style of this font.