MID Profile

javax.microedition.lcdui
Class Font

java.lang.Object
  |
  +--javax.microedition.lcdui.Font

public final class Font
extends Object

The Font class represents fonts and font metrics. Fonts cannot be created by applications. Instead, applications query for fonts based on font attributes and the system will attempt to provide a font that matches the requested attributes as closely as possible.

A Font's attributes are style, size, and face. Values for attributes must be specified in terms of symbolic constants. Values for the style attribute may be combined using the bit-wise OR operator, whereas values for the other attributes may not be combined. For example, the value

STYLE_BOLD | STYLE_ITALIC

may be used to specify a bold-italic font; however

SIZE_LARGE | SIZE_SMALL

is illegal.

The values of these constants are arranged so that zero is valid for each attribute and can be used to specify a reasonable default font for the system. For clarity of programming, the following symbolic constants are provided and are defined to have values of zero:

Values for other attributes are arranged to have disjoint bit patterns in order to raise errors if they are inadvertently misused (for example, using FACE_PROPORTIONAL where a style is required). However, the values for the different attributes are not intended to be combined with each other.

Since:
MIDP 1.0

Field Summary
static int FACE_MONOSPACE
          The "monospace" font face.
static int FACE_PROPORTIONAL
          The "proportional" font face.
static int FACE_SYSTEM
          The "system" font face.
static int FONT_INPUT_TEXT
          Font specifier used by the implementation to draw text input by a user.
static int FONT_STATIC_TEXT
          Default font specifier used to draw Item and Screen contents.
static int SIZE_LARGE
          The "large" system-dependent font size.
static int SIZE_MEDIUM
          The "medium" system-dependent font size.
static int SIZE_SMALL
          The "small" system-dependent font size.
static int STYLE_BOLD
          The bold style constant.
static int STYLE_ITALIC
          The italicized style constant.
static int STYLE_PLAIN
          The plain style constant.
static int STYLE_UNDERLINED
          The underlined style constant.
 
Method Summary
 int charsWidth(char[] ch, int offset, int length)
          Returns the advance width of the characters in ch, starting at the specified offset and for the specified number of characters (length).
 int charWidth(char ch)
          Gets the advance width of the specified character in this Font.
 int getBaselinePosition()
          Gets the distance in pixels from the top of the text to the text's baseline.
static Font getDefaultFont()
          Gets the default font of the system.
 int getFace()
          Gets the face of the font.
static Font getFont(int fontSpecifier)
          Gets the Font used by the high level user interface for the fontSpecifier passed in.
static Font getFont(int face, int style, int size)
          Obtains an object representing a font having the specified face, style, and size.
 int getHeight()
          Gets the standard height of a line of text in this font.
 int getSize()
          Gets the size of the font.
 int getStyle()
          Gets the style of the font.
 boolean isBold()
          Returns true if the font is bold.
 boolean isItalic()
          Returns true if the font is italic.
 boolean isPlain()
          Returns true if the font is plain.
 boolean isUnderlined()
          Returns true if the font is underlined.
 int stringWidth(String str)
          Gets the total advance width for showing the specified String in this Font.
 int substringWidth(String str, int offset, int len)
          Gets the total advance width for showing the specified substring in this Font.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

STYLE_PLAIN

public static final int STYLE_PLAIN
The plain style constant. This may be combined with the other style constants for mixed styles.

Value 0 is assigned to STYLE_PLAIN.


STYLE_BOLD

public static final int STYLE_BOLD
The bold style constant. This may be combined with the other style constants for mixed styles.

Value 1 is assigned to STYLE_BOLD.


STYLE_ITALIC

public static final int STYLE_ITALIC
The italicized style constant. This may be combined with the other style constants for mixed styles.

Value 2 is assigned to STYLE_ITALIC.


STYLE_UNDERLINED

public static final int STYLE_UNDERLINED
The underlined style constant. This may be combined with the other style constants for mixed styles.

Value 4 is assigned to STYLE_UNDERLINED.


SIZE_SMALL

public static final int SIZE_SMALL
The "small" system-dependent font size.

Value 8 is assigned to STYLE_SMALL.


SIZE_MEDIUM

public static final int SIZE_MEDIUM
The "medium" system-dependent font size.

Value 0 is assigned to STYLE_MEDIUM.


SIZE_LARGE

public static final int SIZE_LARGE
The "large" system-dependent font size.

Value 16 is assigned to SIZE_LARGE.


FACE_SYSTEM

public static final int FACE_SYSTEM
The "system" font face.

Value 0 is assigned to FACE_SYSTEM.


FACE_MONOSPACE

public static final int FACE_MONOSPACE
The "monospace" font face.

Value 32 is assigned to FACE_MONOSPACE.


FACE_PROPORTIONAL

public static final int FACE_PROPORTIONAL
The "proportional" font face.

Value 64 is assigned to FACE_PROPORTIONAL.


FONT_STATIC_TEXT

public static final int FONT_STATIC_TEXT
Default font specifier used to draw Item and Screen contents. FONT_STATIC_TEXT has the value 0.
See Also:
getFont(int fontSpecifier)
Since:
MIDP 2.0

FONT_INPUT_TEXT

public static final int FONT_INPUT_TEXT
Font specifier used by the implementation to draw text input by a user. FONT_INPUT_TEXT has the value 1.
See Also:
getFont(int fontSpecifier)
Since:
MIDP 2.0
Method Detail

getFont

public static Font getFont(int fontSpecifier)
Gets the Font used by the high level user interface for the fontSpecifier passed in. It should be used by subclasses of CustomItem and Canvas to match user interface on the device.
Parameters:
fontSpecifier - one of FONT_INPUT_TEXT, or FONT_STATIC_TEXT
Returns:
font that corresponds to the passed in font specifier
Throws:
IllegalArgumentException - if fontSpecifier is not a valid fontSpecifier
Since:
MIDP 2.0

getDefaultFont

public static Font getDefaultFont()
Gets the default font of the system.
Returns:
the default font

getFont

public static Font getFont(int face,
                           int style,
                           int size)
Obtains an object representing a font having the specified face, style, and size. If a matching font does not exist, the system will attempt to provide the closest match. This method always returns a valid font object, even if it is not a close match to the request.
Parameters:
face - one of FACE_SYSTEM, FACE_MONOSPACE, or FACE_PROPORTIONAL
style - STYLE_PLAIN, or a combination of STYLE_BOLD, STYLE_ITALIC, and STYLE_UNDERLINED
size - one of SIZE_SMALL, SIZE_MEDIUM, or SIZE_LARGE
Returns:
instance the nearest font found
Throws:
IllegalArgumentException - if face, style, or size are not legal values

getStyle

public int getStyle()
Gets the style of the font. The value is an OR'ed combination of STYLE_BOLD, STYLE_ITALIC, and STYLE_UNDERLINED; or the value is zero (STYLE_PLAIN).
Returns:
style of the current font
See Also:
isPlain(), isBold(), isItalic()

getSize

public int getSize()
Gets the size of the font.
Returns:
one of SIZE_SMALL, SIZE_MEDIUM, SIZE_LARGE

getFace

public int getFace()
Gets the face of the font.
Returns:
one of FACE_SYSTEM, FACE_PROPORTIONAL, FACE_MONOSPACE

isPlain

public boolean isPlain()
Returns true if the font is plain.
Returns:
true if font is plain
See Also:
getStyle()

isBold

public boolean isBold()
Returns true if the font is bold.
Returns:
true if font is bold
See Also:
getStyle()

isItalic

public boolean isItalic()
Returns true if the font is italic.
Returns:
true if font is italic
See Also:
getStyle()

isUnderlined

public boolean isUnderlined()
Returns true if the font is underlined.
Returns:
true if font is underlined
See Also:
getStyle()

getHeight

public int getHeight()
Gets the standard height of a line of text in this font. This value includes sufficient spacing to ensure that lines of text painted this distance from anchor point to anchor point are spaced as intended by the font designer and the device. This extra space (leading) occurs below the text.
Returns:
standard height of a line of text in this font (a non-negative value)

getBaselinePosition

public int getBaselinePosition()
Gets the distance in pixels from the top of the text to the text's baseline.
Returns:
the distance in pixels from the top of the text to the text's baseline

charWidth

public int charWidth(char ch)
Gets the advance width of the specified character in this Font. The advance width is the horizontal distance that would be occupied if ch were to be drawn using this Font, including inter-character spacing following ch necessary for proper positioning of subsequent text.
Parameters:
ch - the character to be measured
Returns:
the total advance width (a non-negative value)

charsWidth

public int charsWidth(char[] ch,
                      int offset,
                      int length)
Returns the advance width of the characters in ch, starting at the specified offset and for the specified number of characters (length). The advance width is the horizontal distance that would be occupied if the characters were to be drawn using this Font, including inter-character spacing following the characters necessary for proper positioning of subsequent text.

The offset and length parameters must specify a valid range of characters within the character array ch. The offset parameter must be within the range [0..(ch.length)], inclusive. The length parameter must be a non-negative integer such that (offset + length) <= ch.length.

Parameters:
ch - the array of characters
offset - the index of the first character to measure
length - the number of characters to measure
Returns:
the width of the character range
Throws:
ArrayIndexOutOfBoundsException - if offset and length specify an invalid range
NullPointerException - if ch is null

stringWidth

public int stringWidth(String str)
Gets the total advance width for showing the specified String in this Font. The advance width is the horizontal distance that would be occupied if str were to be drawn using this Font, including inter-character spacing following str necessary for proper positioning of subsequent text.
Parameters:
str - the String to be measured
Returns:
the total advance width
Throws:
NullPointerException - if str is null

substringWidth

public int substringWidth(String str,
                          int offset,
                          int len)
Gets the total advance width for showing the specified substring in this Font. The advance width is the horizontal distance that would be occupied if the substring were to be drawn using this Font, including inter-character spacing following the substring necessary for proper positioning of subsequent text.

The offset and len parameters must specify a valid range of characters within str. The offset parameter must be within the range [0..(str.length())], inclusive. The len parameter must be a non-negative integer such that (offset + len) <= str.length().

Parameters:
str - the String to be measured
offset - zero-based index of first character in the substring
len - length of the substring
Returns:
the total advance width
Throws:
StringIndexOutOfBoundsException - if offset and length specify an invalid range
NullPointerException - if str is null

MID Profile

Submit a comment or suggestion Version 2.0 of MID Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright (c) 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A. All Rights Reserved.