SHOW Signed

net.rim.device.api.ui
Class Font

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

public 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.

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).

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

A transformation matrix specifies how to transform the coordinate pairs of one coordinate space into another coordinate space. Postscript notation is used for the transformation matrix definition (see more at http://partners.adobe.com/asn/developer/pdfs/tn/PLRM.pdf 4.3.3). A two-dimensional transformation is described mathematically by a 3-by-3 matrix:

       a b 0
       c d 0
       tx ty 1
 

Translation by a specified displacement (tx, ty) is described by the matrix

   1 0 0
   0 1 0
   tx ty 1
 

Scaling by the factor sx in the horizontal dimension and sy in the vertical dimension is accomplished by the matrix

       sx 0 0
       0 sy 0
       0 0 1
 

Rotation counterclockwise about the origin by an angle q is described by the matrix

       q cos q sin 0
       q sin – q cos 0
       0 0 1
 

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 (must specify UNDERLINED 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.
	Font	derive(int style, int height, int units) Derives a font of a given style and size.
	Font	derive(int style, int height, int units, int antialiasMode, int effects) Derives a font of a given style and size, antialias mode and glyph effects Works like derive(int), except you can also specify a new font size as well as style.
	Font	derive(int style, int height, int units, int antialiasMode, int effects, int[] transform) Derives a font of a given style and size, antialias mode, glyph effects, affine transformation Works like derive(int), except you can also specify a new font size as well as style.
	Font	derive(int style, int height, int units, int antialiasMode, int effects, int A, int B, int C, int D, int Tx, int Ty) Derives a font of a given style and size, antialias mode and glyph effects.
	int	getAdvance(char c) Determines particular glyph width.
	int	getAdvance(char[] text, int offset, int length) Determines advance of a character array's substring.
	int	getAdvance(String text) Determines advance of a text string.
	int	getAdvance(StringBuffer text, int offset, int length) Determines advance of a string buffer's substring.
	int	getAdvance(String text, int offset, int length) Determines advance 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() Determines if this font is bold.
	boolean	isItalic() Determines if this font is italic.
	boolean	isPlain() Determines if this font is plain.
	boolean	isUnderlined() Determines 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 (must specify UNDERLINED 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 this method to retrieve a new font derived from this font. For instance, 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 variation doesn't already exist in the system, then this method simply hands back a handle to this font.

Parameters:

style - New style desired.

Returns:

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

Since:

JDE 4.0.0

derive

public Font derive(int style,
                   int height)

Derives a font of a given style and size.

Works 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 4.0.0

derive

public Font derive(int style,
                   int height,
                   int units)

Derives a font of a given style and size.

Works 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.

units - Units modifier in height, must be one of Ui.UNITS_*.

Returns:

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

Since:

JDE 4.0.0

derive

public Font derive(int style,
                   int height,
                   int units,
                   int antialiasMode,
                   int effects)

Derives a font of a given style and size, antialias mode and glyph effects

Works 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.

units - Units modifier in height, must be one of Ui.UNITS_*.

antialiasMode - New antialias mode desired.

effects - New glyph effects desired.

Returns:

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

Since:

JDE 4.0.0

derive

public Font derive(int style,
                   int height,
                   int units,
                   int antialiasMode,
                   int effects,
                   int[] transform)

Derives a font of a given style and size, antialias mode, glyph effects, affine transformation

Works 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.

units - Units modifier in height, must be one of Ui.UNITS_*.

antialiasMode - New antialias mode desired.

effects - New glyph effects desired.

transform - An affine two-dimensional geometric transform represented by 3x2 matrix. The coefficients are stored using 16.16 fixed point, so cannot be outside the range -32768...32767.

Returns:

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

Since:

JDE 4.0.0

derive

public Font derive(int style,
                   int height,
                   int units,
                   int antialiasMode,
                   int effects,
                   int A,
                   int B,
                   int C,
                   int D,
                   int Tx,
                   int Ty)

Derives a font of a given style and size, antialias mode and glyph effects.

The names for the coefficients echo those used in the PostScript Language Reference Manual, which contains a good explanation of this type of transform.

Parameters:

style - New style desired.

height - New height desired.

units - Units modifier in height, must be one of Ui.UNITS_*.

antialiasMode - New antialias mode desired.

effects - New glyph effects desired.

A - The A (x scale) coefficient.

B - The B (x slant) coefficient.

C - The C (y slant) coefficient.

D - The D (y scale) coefficient.

Tx - The Tx (X offset) coefficient.

Ty - The Ty (Y offset) coefficient.

Returns:

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

Since:

JDE 4.0.0

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 4.0.0

getAdvance

public int getAdvance(char c)

Determines particular glyph width.

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

Parameters:

c - Character glyph for which to calculate width.

Returns:

Pixels of width used by specified glyph.

Since:

JDE 4.0.0

getAdvance

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

Determines advance of a text string's substring.

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

Parameters:

text - String for which to calculate a width.

offset - Character offset into the string to use as start of substring. If illegal return 0.

length - Length of substring. If Integer.MAX_VALUE, calculates the maximum valid length.

Returns:

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

Throws:

NullPointerException - If provided text parameter is null and the requested length is not 0.

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

Since:

JDE 4.0.0

getAdvance

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

Determines advance 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.

Parameters:

text - String buffer for which to calculate a width.

offset - Character offset into the string buffer to use as start of substring. If illegal return 0.

length - Length of substring. If Integer.MAX_VALUE, calculates the maximum valid length.

Returns:

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

Throws:

NullPointerException - If provided text parameter is null and the requested length is not 0.

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

Since:

JDE 4.0.0

getAdvance

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

Determines advance 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.

Parameters:

text - Character array for which to calculate a width.

offset - Array element to use as start of substring. If illegal return 0.

length - Length of substring. If Integer.MAX_VALUE, calculates the maximum valid length.

Returns:

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

Throws:

NullPointerException - If provided text parameter is null and the requested length is not 0.

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

Since:

JDE 4.0.0

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:

Ascent height for tis font.

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:

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:

Descent height of this font.

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()

isBold

public boolean isBold()

Determines if this font is bold.

Returns:

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

isItalic

public boolean isItalic()

Determines if this font is italic.

Returns:

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

isUnderlined

public boolean isUnderlined()

Determines if this font is underlined.

Returns:

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

isPlain

public boolean isPlain()

Determines 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.

The GUID_FONT_CHANGED event is sent to the current application. If the font is set prior to the application instance being created, no notification is sent to this application that the font has been changed.

Parameters:

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

Since:

JDE 4.0.0

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.