net.rim.device.api.ui
Class Font

java.lang.Object
  net.rim.device.api.ui.Font

public class Font
extends Object

A font is a set of glyphs in a certain style and size, and an associated set of metrics describing their placement and overall size. Font objects are immutable, allowing references to Font objects to be used freely with the guarantee that they will always refer to the same style and size.

The size of a font is the height of an imaginary rectangle, the 'em square', in which the glyphs are drawn.

A glyph is drawn relative to its origin, which is a point on the baseline of the line. After the glyph is drawn, the current drawing position is moved by 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 normally refer to the font's block height, which includes leading, but can optionally refer to the height excluding leading (the sum of ascent and descent) if the flag HEIGHT_EXCLUDES_LEADING is used.

When fonts are created their heights can be given in various units including points, millimeters and pixels; but font metrics obtained by inquiry functions are always given in pixels.

Transformations can be used to scale, rotate, and otherwise modify the glyphs of a font. Their principal use is in scaling web pages. The transformation is applied after hinting, therefore the relative proportions and metrics all scale by the same amount. For a good explanation of how to use transformations, using the same notation that is used here in the documentation of the Font and FontFamily classes, see http://www.adobe.com/products/postscript/pdfs/PLRM.pdf, pages 187-189.

Field Summary
static int	ANTIALIAS_DEFAULT Default anti-aliasing: the anti-alias mode which best suits the font technology.
static int	ANTIALIAS_LOW_RES Anti-aliasing using 16 intensity levels.
static int	ANTIALIAS_NONE No anti-aliasing.
static int	ANTIALIAS_STANDARD Anti-aliasing using 256 intensity levels.
static int	ANTIALIAS_SUBPIXEL Anti-aliasing by treating the three sub-pixels of a pixel on an LCD display separately.
static int	APPLICATION In a global event, check this flag to see if the change was an application or a global one.
static int	ARABIC_SCRIPT A script flag to select the Arabic script.
static int	ARMENIAN_SCRIPT A script flag to select the Armenian script.
static int	BENGALI_SCRIPT A script flag to select the Bengali script.
static int	BOLD A style bit for bold-face.
static int	BROKEN_LINE_UNDERLINED A style bit for broken underlining.
static int	CJK_SCRIPT A script flag to select the CJK script (Han ideographs used in Chinese, Japanese and Korean).
static int	CURSIVE_STYLE A style value to select a cursive font.
static int	CYRILLIC_SCRIPT A script flag to select the Cyrillic script.
static int	DEVANAGARI_SCRIPT A script flag to select the Devanagari script.
static int	DOTTED_UNDERLINED A style bit for dotted underlining.
static int	ETHIOPIC_SCRIPT A script flag to select the Ethiopic script.
static int	EXTRA_BOLD A style bit for extra-bold.
static int	FANTASY_STYLE A style value to select a fantasy font as described in http://www.w3.org/TR/CSS2/fonts.html#generic-font-families.
static int	GEORGIAN_SCRIPT A script flag to select the Georgian script.
static int	GREEK_SCRIPT A script flag to select the Greek script.
static long	GUID_FONT_CHANGED The GUID for the global event sent when the system font changes.
static int	GUJARATI_SCRIPT A script flag to select the Gujarati script.
static int	GURMUKHI_SCRIPT A script flag to select the Gurmukhi script.
static int	HANGUL_SCRIPT A script flag to select the Hangul (Korean) script.
static int	HEBREW_SCRIPT A script flag to select the Hebrew script.
static int	HIRAGANA_SCRIPT A script flag to select the Hiragana script.
static int	ITALIC A style bit for italics.
static int	KANNADA_SCRIPT A script flag to select the Kannada script.
static int	KATAKANA_SCRIPT A script flag to select the Katakana script.
static int	KHMER_SCRIPT A script flag to select the Khmer (Cambodian) script.
static int	LAO_SCRIPT A script flag to select the Lao script.
static int	LATIN_SCRIPT A script flag to select the Latin script.
static int	MALAYALAM_SCRIPT A script flag to select the Malayalam script.
static int	MONGOLIAN_SCRIPT A script flag to select the Mongolian script.
static int	MYANMAR_SCRIPT A script flag to select the Myanmar (Burmese) script.
static int	ORIYA_SCRIPT A script flag to select the Oriya script.
static int	PLAIN A style value: plain, not bold, italic, underlined, etc.
static int	SANS_SERIF_STYLE A style value to select a sans-serif font.
static int	SERIF_STYLE A style value to select a serif font.
static int	SERIF_STYLE_MASK The serif/sans-serif style is stored in these two bits in the style flags.
static int	SINHALA_SCRIPT A script flag to select the Sinhala script.
static int	STRIKE_THROUGH A style bit for strike-through.
static int	TAMIL_SCRIPT A script flag to select the Tamil script.
static int	TELUGU_SCRIPT A script flag to select the Telugu script.
static int	THAI_SCRIPT A script flag to select the Thai script.
static int	TIBETAN_SCRIPT A script flag to select the Tibetan script.
static int	UNDERLINED A style bit for underlining.
static int	UNSPECIFIED_SERIF_STYLE A style value for an unspecified serif/sans-serif style.
static int	WAVY_UNDERLINED A style bit for wavy underlining.

Method Summary
Font	derive(int style) Creates a new font that is the same except for the specified style.
Font	derive(int style, int height) Creates a new font that is the same except for the specified style and height.
Font	derive(int style, int height, int units) Creates a new font that is the same except for the specified style and height.
Font	derive(int style, int height, int units, int aAntialiasMode, int aEffects) Creates a new font that is the same except for the specified style, height, anti-alias mode, and effects.
Font	derive(int style, int height, int units, int aAntialiasMode, int aEffects, int aA, int aB, int aC, int aD, int aTx, int aTy) Creates a new font that is the same except for the specified style, height, anti-alias mode, effects and affine transform.
Font	derive(int style, int height, int units, int aAntialiasMode, int aEffects, int[] aTransform) Creates a new font that is the same except for the specified style, height, anti-alias mode, effects and affine transform.
int	getAdvance(char aChar) Returns the advance width of a character.
int	getAdvance(char[] aText, int aOffset, int aLength) Returns the advance width of a substring of some text.
int	getAdvance(String aText) Returns the advance width of some text.
int	getAdvance(String aText, int aOffset, int aLength) Returns the advance width of a substring of some text.
int	getAdvance(StringBuffer aText, int aOffset, int aLength) Returns the advance width of a substring of some text.
int	getAntialiasMode() Returns the anti-alias mode.
int	getAscent() Returns the ascent height.
int	getBaseline() Returns the baseline position.
int	getBounds(char aChar) Returns the horizontal width needed to draw a character: which is the maximum of the advance width and the width of the inked pixels.
int	getBounds(char[] aText, int aOffset, int aLength) Returns the horizontal width needed to draw a text string: which is the maximum of the advance width and the width of the inked pixels.
int	getBounds(String aText) Returns the horizontal width needed to draw a text string: which is the maximum of the advance width and the width of the inked pixels.
int	getBounds(String aText, int aOffset, int aLength) Returns the horizontal width needed to draw a text string: which is the maximum of the advance width and the width of the inked pixels.
int	getBounds(StringBuffer aText) Returns the horizontal width needed to draw a text string: which is the maximum of the advance width and the width of the inked pixels.
int	getBounds(StringBuffer aText, int aOffset, int aLength) Returns the horizontal width needed to draw a text string: which is the maximum of the advance width and the width of the inked pixels.
static Font	getDefault() Returns the default font.
int	getDescent() Returns the font's descent.
FontFamily	getFontFamily() Returns the font family containing this font.
FontSpec	getFontSpec() Returns an instance of the FontSpec class.
int	getHeight() Returns the 'em-square' height of the font based on the capital M glyph in the Latin character set.
int	getHeight(int units) This method behaves in the same way as Font.getHeight() but allows control over the unit of measurement for the returned height value.
int	getLeading() Returns the font's leading.
void	getMetrics(FontMetrics aFontMetrics) Returns the font metrics.
void	getMetrics(FontMetrics aFontMetrics, int aScripts) Gets font metrics for the combination of available fonts supporting the specified scripts, and matching this font as closely as possible.
void	getMetrics(FontMetrics aFontMetrics, int aScripts, int aLocale) Gets font metrics for the combination of available fonts supporting the specified scripts, and matching this font as closely as possible.
void	getMetricsForLocale(FontMetrics aFontMetrics, int aLocale) Gets font metrics for the combination of available fonts supporting the specified locale, and matching this font as closely as possible.
String	getName(int aNameCode) Gets one of the font's name or other strings (e.g., copyright, family, version, license, etc.).
int	getStyle() Returns the font's style flags - bold, italic, underline, strikethrough, etc.
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.
int	measureText(char[] aText, int aOffset, int aLength, DrawTextParam aParam, TextMetrics aMetrics) Measures some text.
int	measureText(String aText, int aOffset, int aLength, DrawTextParam aParam, TextMetrics aMetrics) Measures some text.
int	measureText(StringBuffer aText, int aOffset, int aLength, DrawTextParam aParam, TextMetrics aMetrics) Measures some text.
static void	setDefaultFont(Font aDefaultFont) Deprecated. Use FontManager.setApplicationFont(net.rim.device.api.ui.Font).
String	toString() Retrieves the 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

A style value: plain, not bold, italic, underlined, etc.

See Also:

Constant Field Values

BOLD

public static final int BOLD

A style bit for bold-face.

See Also:

Constant Field Values

ITALIC

public static final int ITALIC

A style bit for italics.

See Also:

Constant Field Values

UNDERLINED

public static final int UNDERLINED

A style bit for underlining.

See Also:

Constant Field Values

DOTTED_UNDERLINED

public static final int DOTTED_UNDERLINED

A style bit for dotted underlining. {@link #UNDERLINED) must also be set.

See Also:

Constant Field Values

BROKEN_LINE_UNDERLINED

public static final int BROKEN_LINE_UNDERLINED

A style bit for broken underlining. {@link #UNDERLINED) must also be set.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

STRIKE_THROUGH

public static final int STRIKE_THROUGH

A style bit for strike-through.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

EXTRA_BOLD

public static final int EXTRA_BOLD

A style bit for extra-bold. Note: at small sizes, depending on the font, extra-bold may not differ from ordinary bold-face.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

WAVY_UNDERLINED

public static final int WAVY_UNDERLINED

A style bit for wavy underlining. {@link #UNDERLINED) must also be set.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

SERIF_STYLE_MASK

public static final int SERIF_STYLE_MASK

The serif/sans-serif style is stored in these two bits in the style flags.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

UNSPECIFIED_SERIF_STYLE

public static final int UNSPECIFIED_SERIF_STYLE

A style value for an unspecified serif/sans-serif style.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

SANS_SERIF_STYLE

public static final int SANS_SERIF_STYLE

A style value to select a sans-serif font.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

SERIF_STYLE

public static final int SERIF_STYLE

A style value to select a serif font.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

CURSIVE_STYLE

public static final int CURSIVE_STYLE

A style value to select a cursive font.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

FANTASY_STYLE

public static final int FANTASY_STYLE

A style value to select a fantasy font as described in http://www.w3.org/TR/CSS2/fonts.html#generic-font-families.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

ANTIALIAS_DEFAULT

public static final int ANTIALIAS_DEFAULT

Default anti-aliasing: the anti-alias mode which best suits the font technology.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

ANTIALIAS_NONE

public static final int ANTIALIAS_NONE

No anti-aliasing.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

ANTIALIAS_STANDARD

public static final int ANTIALIAS_STANDARD

Anti-aliasing using 256 intensity levels.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

ANTIALIAS_SUBPIXEL

public static final int ANTIALIAS_SUBPIXEL

Anti-aliasing by treating the three sub-pixels of a pixel on an LCD display separately. The ANTIALIAS_SUBPIXEL mode is not currently supported by the font engine.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

ANTIALIAS_LOW_RES

public static final int ANTIALIAS_LOW_RES

Anti-aliasing using 16 intensity levels.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

GUID_FONT_CHANGED

public static final long GUID_FONT_CHANGED

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

See Also:

Constant Field Values

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.

See Also:

Constant Field Values

LATIN_SCRIPT

public static final int LATIN_SCRIPT

A script flag to select the Latin script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

GREEK_SCRIPT

public static final int GREEK_SCRIPT

A script flag to select the Greek script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

CYRILLIC_SCRIPT

public static final int CYRILLIC_SCRIPT

A script flag to select the Cyrillic script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

ARMENIAN_SCRIPT

public static final int ARMENIAN_SCRIPT

A script flag to select the Armenian script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

HEBREW_SCRIPT

public static final int HEBREW_SCRIPT

A script flag to select the Hebrew script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

ARABIC_SCRIPT

public static final int ARABIC_SCRIPT

A script flag to select the Arabic script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

DEVANAGARI_SCRIPT

public static final int DEVANAGARI_SCRIPT

A script flag to select the Devanagari script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

BENGALI_SCRIPT

public static final int BENGALI_SCRIPT

A script flag to select the Bengali script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

GURMUKHI_SCRIPT

public static final int GURMUKHI_SCRIPT

A script flag to select the Gurmukhi script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

GUJARATI_SCRIPT

public static final int GUJARATI_SCRIPT

A script flag to select the Gujarati script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

ORIYA_SCRIPT

public static final int ORIYA_SCRIPT

A script flag to select the Oriya script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

TAMIL_SCRIPT

public static final int TAMIL_SCRIPT

A script flag to select the Tamil script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

TELUGU_SCRIPT

public static final int TELUGU_SCRIPT

A script flag to select the Telugu script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

KANNADA_SCRIPT

public static final int KANNADA_SCRIPT

A script flag to select the Kannada script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

MALAYALAM_SCRIPT

public static final int MALAYALAM_SCRIPT

A script flag to select the Malayalam script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

SINHALA_SCRIPT

public static final int SINHALA_SCRIPT

A script flag to select the Sinhala script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

THAI_SCRIPT

public static final int THAI_SCRIPT

A script flag to select the Thai script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

LAO_SCRIPT

public static final int LAO_SCRIPT

A script flag to select the Lao script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

TIBETAN_SCRIPT

public static final int TIBETAN_SCRIPT

A script flag to select the Tibetan script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

MYANMAR_SCRIPT

public static final int MYANMAR_SCRIPT

A script flag to select the Myanmar (Burmese) script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

GEORGIAN_SCRIPT

public static final int GEORGIAN_SCRIPT

A script flag to select the Georgian script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

HANGUL_SCRIPT

public static final int HANGUL_SCRIPT

A script flag to select the Hangul (Korean) script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

ETHIOPIC_SCRIPT

public static final int ETHIOPIC_SCRIPT

A script flag to select the Ethiopic script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

KHMER_SCRIPT

public static final int KHMER_SCRIPT

A script flag to select the Khmer (Cambodian) script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

MONGOLIAN_SCRIPT

public static final int MONGOLIAN_SCRIPT

A script flag to select the Mongolian script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

HIRAGANA_SCRIPT

public static final int HIRAGANA_SCRIPT

A script flag to select the Hiragana script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

KATAKANA_SCRIPT

public static final int KATAKANA_SCRIPT

A script flag to select the Katakana script.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

CJK_SCRIPT

public static final int CJK_SCRIPT

A script flag to select the CJK script (Han ideographs used in Chinese, Japanese and Korean).

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

Method Detail

derive

public Font derive(int style)

Creates a new font that is the same except for the specified style. For example, if this font is a plain font, you can get a bold version by calling derive(Font.BOLD).

Parameters:

style - The new style.

derive

public Font derive(int style,
                   int height)

Creates a new font that is the same except for the specified style and height. A height of zero or less causes the height of the default font to be used. Heights greater than 256 pixels are clamped to 256 pixels.

Parameters:

style - The new style.

height - The new height in pixels.

derive

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

Creates a new font that is the same except for the specified style and height. A height of zero or less causes the height of the default font to be used. Heights greater than 256 pixels are clamped to 256 pixels.

Parameters:

style - The new style.

height - The new height, in units specified by units.

units - The units for height. See the UNITS_* constants in the Ui class.

Since:

BlackBerry API 3.7.0

derive

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

Creates a new font that is the same except for the specified style, height, anti-alias mode, and effects. A height of zero or less causes the height of the default font to be used. Heights greater than 256 pixels are clamped to 256 pixels. If the anti-alias mode or effects are illegal the original font is returned unchanged.

Parameters:

style - The new style.

height - The new height, in units specified by units.

units - The units for height. See the UNITS_* constants in the Ui class.

aAntialiasMode - Desired anti-alias mode. See the ANTIALIAS_* constants. The ANTIALIAS_SUBPIXEL mode is not currently supported by the font engine.

aEffects - Desired glyph effects. See the *_EFFECT constants.

Since:

BlackBerry API 3.7.0

derive

public Font derive(int style,
                   int height,
                   int units,
                   int aAntialiasMode,
                   int aEffects,
                   int[] aTransform)

Creates a new font that is the same except for the specified style, height, anti-alias mode, effects and affine transform. A height of zero or less causes the height of the default font to be used. Heights greater than 256 pixels are clamped to 256 pixels. If the anti-alias mode or effects are illegal the original font is returned unchanged. The affine transform converts 2D coordinates (x, y) to (x', y') using the assignments x' = A * x + C * y + Tx; y' = B * x + D * y + Ty. It can be used to scale, rotate or otherwise modify the appearance of the font. The parameters are 16.16 fixed-point numbers, and the translation parameters Tx and Ty are in pixels. The identity transform (which does nothing) is therefore A=1<<16, B=0, C=0, D=1<<16, Tx=0, Ty=0. The parameters A, B, C, D, Tx and Ty are stored in that order in the six elements of an integer array.

Parameters:

style - The new style.

height - The new height, in units specified by units.

units - The units for height. See the UNITS_* constants in the Ui class.

aAntialiasMode - Desired anti-alias mode. See the ANTIALIAS_* constants. The ANTIALIAS_SUBPIXEL mode is not currently supported by the font engine.

aEffects - Desired glyph effects. See the *_EFFECT constants.

aTransform - The six elements of the affine transform, as described above.

Since:

BlackBerry API 3.7.0

derive

public Font derive(int style,
                   int height,
                   int units,
                   int aAntialiasMode,
                   int aEffects,
                   int aA,
                   int aB,
                   int aC,
                   int aD,
                   int aTx,
                   int aTy)

Creates a new font that is the same except for the specified style, height, anti-alias mode, effects and affine transform. A height of zero or less causes the height of the default font to be used. Heights greater than 256 pixels are clamped to 256 pixels. If the anti-alias mode or effects are illegal the original font is returned unchanged. The affine transform converts 2D coordinates (x, y) to (x', y') using the assignments x' = A * x + C * y + Tx; y' = B * x + D * y + Ty. It can be used to scale, rotate or otherwise modify the appearance of the font. The parameters are 16.16 fixed-point numbers, and the translation parameters Tx and Ty are in pixels. The identity transform (which does nothing) is therefore A=1<<16, B=0, C=0, D=1<<16, Tx=0, Ty=0.

Parameters:

style - The new style.

height - The new height, in units specified by units.

units - The units for height. See the UNITS_* constants in the Ui class.

aAntialiasMode - Desired anti-alias mode. See the ANTIALIAS_* constants. The ANTIALIAS_SUBPIXEL mode is not currently supported by the font engine.

aEffects - Desired glyph effects. See the *_EFFECT constants.

aA - The A parameter of the affine transform, as a 16.16 fixed-point number.

aB - The B parameter of the affine transform, as a 16.16 fixed-point number.

aC - The C parameter of the affine transform, as a 16.16 fixed-point number.

aD - The D parameter of the affine transform, as a 16.16 fixed-point number.

aTx - The Tx parameter of the affine transform, as a 16.16 fixed-point number.

aTy - The Ty parameter of the affine transform, as a 16.16 fixed-point number.

Since:

BlackBerry API 3.7.0

getFontSpec

public FontSpec getFontSpec()

Returns an instance of the FontSpec class.

Returns:

FontSpec object.

Since:

BlackBerry API 7.0.0

getAdvance

public final int getAdvance(String aText)

Returns the advance width of some text.

Parameters:

aText - The text, which may be null.

Returns:

The advance width in pixels.

getAdvance

public int getAdvance(char aChar)

Returns the advance width of a character.

Parameters:

aChar - The character.

Returns:

The advance width in pixels.

getAdvance

public int getAdvance(String aText,
                      int aOffset,
                      int aLength)
               throws IllegalArgumentException

Returns the advance width of a substring of some text.

Parameters:

aText - The text, which may be null if the length is zero.

aOffset - The start offset of the text to be measured.

aLength - The length of the text to be measured; the special value Integer.MAX_VALUE specifies the whole of the text from aOffset onwards.

Returns:

The advance width in pixels.

Throws:

IllegalArgumentException

getAdvance

public int getAdvance(StringBuffer aText,
                      int aOffset,
                      int aLength)
               throws IllegalArgumentException

Returns the advance width of a substring of some text.

Parameters:

aText - The text, which may be null if the length is zero.

aOffset - The start offset of the text to be measured.

aLength - The length of the text to be measured; the special value Integer.MAX_VALUE specifies the whole of the text from aOffset onwards.

Returns:

The advance width in pixels.

Throws:

IllegalArgumentException

getAdvance

public int getAdvance(char[] aText,
                      int aOffset,
                      int aLength)
               throws IllegalArgumentException

Returns the advance width of a substring of some text.

Parameters:

aText - The text, which may be null if the length is zero.

aOffset - The start offset of the text to be measured.

aLength - The length of the text to be measured; the special value Integer.MAX_VALUE specifies the whole of the text from aOffset onwards.

Returns:

The advance width in pixels.

Throws:

IllegalArgumentException

getAntialiasMode

public int getAntialiasMode()

Returns the anti-alias mode.

Since:

BlackBerry API 5.0.0

getAscent

public int getAscent()

Returns the ascent height.

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

Returns:

Ascent for this font, in pixels.

getBaseline

public int getBaseline()

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

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

Returns the font's descent.

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

Returns:

Descent of this font, in pixels.

getFontFamily

public FontFamily getFontFamily()

Returns the font family containing this font.

Returns:

Font family object for this current font.

getHeight

public int getHeight()

Returns the 'em-square' height of the font based on the capital M glyph in the Latin character set.

Use this method to retrieve the 'em-square' height value, which is the height of the capital M glyph of the Latin character set based on the current font settings. This method does not return the actual height of the text. Instead it returns the height of the imaginary rectangle created by the glyph of the capital Latin letter, M. Refer to measureText if the actual height of the text is desired.

Returns:

The font's 'em-square' height in pixels.

getHeight

public int getHeight(int units)

This method behaves in the same way as Font.getHeight() but allows control over the unit of measurement for the returned height value.

Parameters:

units - The units in which to return the height; must be one of Ui.UNITS_*

Returns:

The font's 'em-square' height in pixels.

Since:

BlackBerry API 5.0.0

getLeading

public int getLeading()

Returns the 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 principally at the top of the font "block" height.

Returns:

Leading of this font in pixels.

getStyle

public int getStyle()

Returns the font's style flags - bold, italic, underline, strikethrough, etc.

Returns:

Bitfield containing this font's style.

See Also:

Font.isBold(), Font.isItalic(), Font.isPlain()

isBold

public boolean isBold()

Determines if this font is bold.

Returns:

True if this font has the Font.BOLD or Font.EXTRA_BOLD style; otherwise false.

isItalic

public boolean isItalic()

Determines if this font is italic.

Returns:

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

isUnderlined

public boolean isUnderlined()

Determines if this font is underlined.

Returns:

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

isPlain

public boolean isPlain()

Determines if this font is plain.

Returns:

True if this font is not bold, italic, underlined or struck through; false otherwise.

measureText

public int measureText(String aText,
                       int aOffset,
                       int aLength,
                       DrawTextParam aParam,
                       TextMetrics aMetrics)
                throws IllegalArgumentException

Measures some text. If aParam is non-null it contains parameters to control the way the measurement is made. If aMetrics is non-null the full metrics are returned. The ordinary return value is the horizontal component of the advance width: that is, the amount to add to the x coordinate of the drawing position after drawing the text.

Parameters:

aText - The text to measure; may be null only if aLength is 0.

aOffset - Start offset of the substring.

aLength - Length of substring.

aParam - Parameters to control the measurement.

aMetrics - Full text metrics for the given substring.

Returns:

The advance width of the specified substring.

Throws:

IllegalArgumentException

Since:

BlackBerry API 6.0.0

measureText

public int measureText(StringBuffer aText,
                       int aOffset,
                       int aLength,
                       DrawTextParam aParam,
                       TextMetrics aMetrics)
                throws IllegalArgumentException

Measures some text. If aParam is non-null it contains parameters to control the way the measurement is made. If aMetrics is non-null the full metrics are returned. The ordinary return value is the horizontal component of the advance width: that is, the amount to add to the x coordinate of the drawing position after drawing the text.

Parameters:

aText - The text to measure; may be null only if aLength is 0.

aOffset - Start offset of the substring.

aLength - Length of substring.

aParam - Parameters to control the measurement.

aMetrics - Full text metrics for the given substring.

Returns:

The advance width of the specified substring.

Throws:

IllegalArgumentException

Since:

BlackBerry API 6.0.0

measureText

public int measureText(char[] aText,
                       int aOffset,
                       int aLength,
                       DrawTextParam aParam,
                       TextMetrics aMetrics)
                throws IllegalArgumentException

Measures some text. If aParam is non-null it contains parameters to control the way the measurement is made. If aMetrics is non-null the full metrics are returned. The ordinary return value is the horizontal component of the advance width: that is, the amount to add to the x coordinate of the drawing position after drawing the text.

Parameters:

aText - The text to measure; may be null only if aLength is 0.

aOffset - Start offset of the substring.

aLength - Length of substring.

aParam - Parameters to control the measurement.

aMetrics - Full text metrics for the given substring.

Returns:

The advance width of the specified substring.

Throws:

IllegalArgumentException

Since:

BlackBerry API 6.0.0

getBounds

public int getBounds(String aText)

Returns the horizontal width needed to draw a text string: which is the maximum of the advance width and the width of the inked pixels.

Parameters:

aText - The text: may be null.

Returns:

The width in pixels.

Since:

BlackBerry API 5.0.0

getBounds

public int getBounds(StringBuffer aText)

Returns the horizontal width needed to draw a text string: which is the maximum of the advance width and the width of the inked pixels.

Parameters:

aText - The text: may be null.

Returns:

The width in pixels.

Since:

BlackBerry API 5.0.0

getBounds

public int getBounds(char aChar)

Returns the horizontal width needed to draw a character: which is the maximum of the advance width and the width of the inked pixels.

Parameters:

aChar - The character.

Returns:

The width in pixels.

Since:

BlackBerry API 5.0.0

getBounds

public int getBounds(StringBuffer aText,
                     int aOffset,
                     int aLength)
              throws IllegalArgumentException

Returns the horizontal width needed to draw a text string: which is the maximum of the advance width and the width of the inked pixels.

Parameters:

aText - The text to measure; may be null only if aLength is 0.

aOffset - Start offset of the substring.

aLength - Length of substring.

Returns:

The width in pixels.

Throws:

IllegalArgumentException

Since:

BlackBerry API 5.0.0

getBounds

public int getBounds(String aText,
                     int aOffset,
                     int aLength)
              throws IllegalArgumentException

Returns the horizontal width needed to draw a text string: which is the maximum of the advance width and the width of the inked pixels.

Parameters:

aText - The text to measure; may be null only if aLength is 0.

aOffset - Start offset of the substring.

aLength - Length of substring.

Returns:

The width in pixels.

Throws:

IllegalArgumentException

Since:

BlackBerry API 5.0.0

getBounds

public int getBounds(char[] aText,
                     int aOffset,
                     int aLength)
              throws IllegalArgumentException

Returns the horizontal width needed to draw a text string: which is the maximum of the advance width and the width of the inked pixels.

Parameters:

aText - The text to measure; may be null only if aLength is 0.

aOffset - Start offset of the substring.

aLength - Length of substring.

Returns:

The width in pixels.

Throws:

IllegalArgumentException

Since:

BlackBerry API 5.0.0

getMetrics

public void getMetrics(FontMetrics aFontMetrics)

Returns the font metrics.

Parameters:

aFontMetrics - the font metrics to be filled in. Equivalent to calling the three-parameter version of getMetrics with aScripts = 0 and aLocale = 0.

Since:

BlackBerry API 6.0.0

getMetrics

public void getMetrics(FontMetrics aFontMetrics,
                       int aScripts)

Gets font metrics for the combination of available fonts supporting the specified scripts, and matching this font as closely as possible. Equivalent to calling the three-parameter version of getMetrics with aLocale = 0.

Parameters:

aFontMetrics - the font metrics to be filled in.

aScripts - a bit field representing the required scripts

Since:

BlackBerry API 6.0.0

getMetricsForLocale

public void getMetricsForLocale(FontMetrics aFontMetrics,
                                int aLocale)

Gets font metrics for the combination of available fonts supporting the specified locale, and matching this font as closely as possible. Equivalent to calling the three-paramater version of getMetrics with aScripts = 0.

Parameters:

aFontMetrics - the font metrics to be filled in.

aLocale - if non-zero, a locale code

Since:

BlackBerry API 6.0.0

getMetrics

public void getMetrics(FontMetrics aFontMetrics,
                       int aScripts,
                       int aLocale)

Gets font metrics for the combination of available fonts supporting the specified scripts, and matching this font as closely as possible. For example, to know how large a line height to allocate for text containing English and Chinese, which may have different baselines, etc., call this function with aScripts = LATIN_SCRIPT | CJK_SCRIPT, then use the values in aMetrics.getAscent(), aMetrics.getDescent(), etc. If aLocale is non-zero, it does two things: (i) it sets the Han style, and (ii) it causes extra scripts to be examined if necessary. Therefore to get metrics for a given locale it is adequate to set aLocale to the locale number, while setting aScripts to zero. The returned metrics are the maximum values found in any of the typefaces examined. If both aScripts and aLocale are zero the font's own metrics are returned.

Parameters:

aFontMetrics - the font metrics to be filled in.

aScripts - a bit field representing the required scripts

aLocale - if non-zero, a locale code specifying further scripts

Since:

BlackBerry API 6.0.0

setDefaultFont

public static void setDefaultFont(Font aDefaultFont)

Deprecated. Use FontManager.setApplicationFont(net.rim.device.api.ui.Font).

Sets the default font for this application.

The Font.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:

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

Since:

BlackBerry API 3.6.0

toString

public String toString()

Retrieves the 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.

getName

public String getName(int aNameCode)

Gets one of the font's name or other strings (e.g., copyright, family, version, license, etc.).

Parameters:

aNameCode - the name code as defined for the TrueType and OpenType 'name' table.

Since:

BlackBerry API 5.0.0