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://www.adobe.com/products/postscript/pdfs/PLRM.pdf). 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

       cos(q) -sin(q) 0
       sin(q) cos(q)  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 the given style.
 Font derive(int style, int height)
          Derives a font with the given style and size.
 Font derive(int style, int height, int units)
          Derives a font with the given style, size and units.
 Font derive(int style, int height, int units, int antialiasMode, int effects)
          Derives a font with the given style, size, units, antialias mode and glyph effects.
 Font derive(int style, int height, int units, int antialiasMode, int effects, int[] transform)
          Derives a font with the given style, size, antialias mode, glyph effects, and affine transformation.
 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 with the given style, size, antialias mode, glyph effects, and affine transformation.
 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


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.

BOLD

public static final int BOLD
Bold 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.

ITALIC

public static final int ITALIC
Italic font style modifier.

PLAIN

public static final int PLAIN
Plain font style.

UNDERLINED

public static final int UNDERLINED
Underlined font style modifier.
Method Detail

derive

public Font derive(int style)
Derives a font with the given style.

Use this method to retrieve a font derived from this font. For example, if this font is a plain font, you can retrieve the bold version by invoking derive(this.BOLD).

Parameters:
style - New style desired. The style can include the Han hint. ex. Font.BOLD | FONT.TRADITIONAL_CHINESE_HINT
Returns:
The derived font, or this font if the provided style is the same as this font's style.

derive

public Font derive(int style,
                   int height)
Derives a font with the given style and size.

Works like derive(int), except you can also specify a new font size. If a font with the specified size cannot be derived, then this method returns a handle to this font.

Parameters:
style - New style desired.
height - New height desired.
Returns:
The derived font, or this font if the desired font could not be derived.

derive

public Font derive(int style,
                   int height,
                   int units)
Derives a font with the given style, size and units.

Works like derive(int), except you can also specify a new font size and height unit. If a font with the specified size or units cannot be derived, then this method returns a handle to this font.

Parameters:
style - New style desired.
height - New height desired.
units - Units modifier in height, must be one of Ui.UNITS_*.
Returns:
The derived font, or this font if the desired font could not be derived.
Since:
JDE 3.7.0

derive

public Font derive(int style,
                   int height,
                   int units,
                   int antialiasMode,
                   int effects)
Derives a font with the given style, size, units, antialias mode and glyph effects.

Works like derive(int), except you can also specify a new font size, height unit, antialias mode and glyph effects. If a font with the specified size, units, antialias mode and glyph effects cannot be derived, then this method returns a handle to this font.

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:
The derived font, or this font if the desired font could not be derived.
Since:
JDE 3.7.0

derive

public Font derive(int style,
                   int height,
                   int units,
                   int antialiasMode,
                   int effects,
                   int[] transform)
Derives a font with the given style, size, antialias mode, glyph effects, and affine transformation.

Works like derive(int), except you can also specify a new font size, height unit, antialias mode, glyph effects and affine transformation. If a font with the specified size, units, antialias mode, glyph effects and affine transformation cannot be derived, then this method returns a handle to this font.

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 a 16.16 fixed point notation which is a means of using the ‘int’ primitive data type for storing a decimal number. The upper 16 bits are used to represent the whole part of the number, and the lower 16 bits are used to represent the decimal part of the number. Using this notation, the number 1 is actually 1 << 16, or 0x10000, and only numbers in the range -32768...32767 can be represented.
Returns:
The derived font, or this font if the desired font could not be derived.
Since:
JDE 3.7.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 with the given style, size, antialias mode, glyph effects, and affine transformation.

Works like derive(int), except you can also specify a new font size, height unit, antialias mode, glyph effects and affine transformation. If a font with the specified size, units, antialias mode, glyph effects and affine transformation cannot be derived, then this method returns a handle to this font.

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:
The derived font, or this font if the desired font could not be derived.
Since:
JDE 3.7.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.

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.

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.

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.

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.

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

isPlain

public boolean isPlain()
Determines if this font is plain.
Returns:
True if this font has the PLAIN style; otherwise false.

isUnderlined

public boolean isUnderlined()
Determines if this font is underlined.
Returns:
True if this font has the UNDERLINED 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 3.6.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.


Copyright 1999-2007 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.