javax.microedition.lcdui
Class Font

java.lang.Object
  javax.microedition.lcdui.Font

public final class Font
extends java.lang.Object

The Font class represents fonts, which are used to render text in a visible way. A font provides the information needed to map sequences of characters to sequences of glyphs and to render sequences of glyphs on Graphics and Component objects.

Characters and Glyphs

A character is a symbol that represents a unit of text content - an item such as a letter, a digit, or punctuation represented in an abstract way by its character code. For example, 'g', LATIN SMALL LETTER G, is a character.

A glyph is a shape that is used to render a character, and represents a unit of text display. Each character may be represented using one of many possible glyphs that differ in appearance and style. Collections of glyphs designed in the same style are called typefaces, and are represented by different fonts.

A glyph may represent a single character or a sequence of characters. In simple writing systems, such as Latin, typically one glyph represents one character. In general, however, characters and glyphs do not have one-to-one correspondence. For example, the character 'á' LATIN SMALL LETTER A WITH ACUTE, can be represented by two glyphs: one for 'a' and one for '´'. On the other hand, the two-character string "fi" can be represented by a single glyph, a "fi" ligature. In complex writing systems, such as Arabic or the South and South-East Asian writing systems, the relationship between characters and glyphs can be more complicated and involve context-dependent selection of glyphs as well as glyph reordering. A font encapsulates the collection of glyphs needed to render a selected set of characters as well as the tables needed to map sequences of characters to corresponding sequences of glyphs.

Each glyph has a set of metrics that summarize the geometry of the glyph. The methods to get the metrics are: getHeight, getAscent, getMaxAscent, getDescent, getMaxDescent, and getBaselinePosition, getLeading. The metrics are illustrated below:

Physical and Logical Fonts

The Java 2 platform distinguishes between two kinds of fonts: physical fonts and logical fonts.

Physical fonts are the actual font files containing glyph data and tables to map from character sequences to glyph sequences, using a font technology such as OpenType, TrueType or PostScript Type 1. All implementations MUST support OpenType fonts with TrueType outlines. Implementations SHOULD support TrueType hinting and MAY support advanced typographic functions. Support for other font technologies is optional and implementation dependent. Physical fonts use distinct (and, sometimes, trademarked) names such as Helvetica, Palatino, HonMincho, or any other font names. Typically, each physical font supports only a limited character set, for example, only Latin characters or only Japanese and Basic Latin. The set of available physical fonts varies between configurations. Applications that require specific fonts can bundle them and instantiate them using the getFont or createFont methods.

Logical fonts are the five font families defined by the Java platform which must be supported by any Java runtime environment: Serif, SansSerif, Monospaced, Dialog, and DialogInput. These logical fonts are not actual font libraries. Instead, the logical font names are mapped to physical fonts by the Java runtime environment. The mapping is implementation- and (usually) locale- dependent, so the look and the metrics provided by them vary. Typically, each logical font name maps to several physical fonts in order to cover a large range of characters.

Font Faces and Names

A font (typeface) can have many styles and/or weights, such as heavy, medium, oblique, gothic and regular. All of these faces have similar typographic design.

There are three different names that application can get from a Font object. The logical font name is simply the name that was used to construct the font. The font face name, or just font name for short, is the name of a particular font that specifies its family and style, like "Helvetica Bold". The family name is the name of the font family that determines the typographic design across several faces, like "Helvetica".

The Font class represents an instance of a font face from a collection of font faces that are present in the system resources of the host system. As examples, Arial Bold and Courier Bold Italic are font faces. There can be several Font objects associated with a font face, each differing in size, style and font features.

A Font's attributes are style, size (or pixelSize) and font name (or font specifier). Values for size attribute may be specified as either integer or symbolic constant; values for pixelSize shall always be specified as positive, non-zero integer. Values for style attribute 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 symbolic 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:

• STYLE_PLAIN
• SIZE_MEDIUM
• FACE_SYSTEM

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.

Font Size

Most users are familiar with the idea of using point size to specify the size of glyphs in a font, which is based on typographic points, approximately 1/72 of an inch. The use of point size allows creating text documents that preserve the absolute size of the text, regardless of whether a document is reproduced in print or displayed on a computer screen. However, in some circumstances, a relative size of different objects of multimedia content (e.g. graphics, images and text) needs to be preserved in order to assure the content layout and appearance, especially, if scalable media content is intended to be displayed on screens with different sizes and resolutions.

Mobile devices have a wide variety of display sizes and resolutions. MIDlets can query the display size and resolution of a particular device, and can calculate the required size of graphics, text and image objects. For this reason, the size of MIDP Font objects is always calculated and defined as device-specific, in pixels. Implementations SHOULD map the values of symbolic constants SIZE_LARGE, SIZE_MEDIUM and SIZE_SMALL to actual pixel sizes, based on the primary device screen size and resolution. The default size of a new Font object (when it's not specified) is SIZE_MEDIUM.

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_IDLE_HIGHLIGHTED_TEXT Font specifier for focused text on the idle screen.
static int	FONT_IDLE_TEXT Font specifier for unfocused text on the idle screen.
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 for showing a substring of the array ch in this Font; 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.
static Font	createFont(java.io.InputStream fontData) Returns a new Font using the specified font input data.
Font	deriveFont(int pixelSize) Creates a new Font object by replicating this Font object and applying a new size to it.
Font	deriveFont(int style, int pixelSize) Creates a new Font object by replicating this Font object and applying a new style and size.
boolean	equals(java.lang.Object obj) Compares this Font object to the specified Object.
int	getAscent() Gets the font ascent of this Font object.
static Font[]	getAvailableFonts() Returns an array of Font where each Font object represents a physical font available in the system.
static Font[]	getAvailableFonts(int style) Returns an array of Font objects where each object represents a physical font having specified style.
static Font[]	getAvailableFonts(int face, int style, int pixelSize) Returns an array of Font objects where each object represents a physical font having specified face, style and pixelSize.
int	getBaselinePosition() Gets the distance in pixels from the top of the text to the text's baseline, which is defined by the MaxAscent value of a font.
static Font	getDefaultFont() Gets the default font of the system.
int	getDescent() Gets the font descent of this Font object.
int	getFace() Gets the face of the font.
java.lang.String	getFamily() Gets the family name of this 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 (including custom fonts that are either packaged with a MIDlet or downloaded at run-time, if applicable) having the specified face, style and size.
static Font	getFont(java.lang.String name, int style, int pixelSize) Returns a new Font object from the font specified by name, style and size in pixels.
java.lang.String	getFontName() Gets the font face name of this Font.
int	getHeight() Gets the standard height of a line of text in this font.
int	getLeading() Gets the standard leading, in pixels, of this Font object.
int	getMaxAscent() Gets the maximum ascent of this Font.
int	getMaxDescent() Gets the maximum descent of this Font.
java.lang.String	getName() Gets the logical name of this Font.
int	getPixelSize() Gets the pixelSize of this Font.
static int	getPixelSize(java.lang.String name) Gets the pixelSize supported by the font specified by name, in pixels.
int	getSize() Gets the size of this Font.
int	getStyle() Gets the style of this Font.
static int	getStyle(java.lang.String name) Gets the style of the font specified by name.
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(java.lang.String str) Gets the total advance width for showing the specified String in this Font.
int	substringWidth(java.lang.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

getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

STYLE_PLAIN

public static final int STYLE_PLAIN

The plain style constant.

Value 0 is assigned to STYLE_PLAIN.

See Also:

Constant Field Values

STYLE_BOLD

public static final int STYLE_BOLD

The bold style constant. This may be combined with the other style constants (except STYLE_PLAIN) for mixed styles.

Value 1 is assigned to STYLE_BOLD.

See Also:

Constant Field Values

STYLE_ITALIC

public static final int STYLE_ITALIC

The italicized style constant. This may be combined with the other style constants (except STYLE_PLAIN) for mixed styles.

Value 2 is assigned to STYLE_ITALIC.

See Also:

Constant Field Values

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.

See Also:

Constant Field Values

SIZE_LARGE

public static final int SIZE_LARGE

The "large" system-dependent font size.

Value 16 is assigned to SIZE_LARGE. Implementations SHOULD map this value to a particular font size in pixels, depending on device screen resolution and size.

See Also:

Constant Field Values

SIZE_MEDIUM

public static final int SIZE_MEDIUM

The "medium" system-dependent font size.

Value 0 is assigned to SIZE_MEDIUM. Implementations SHOULD map this value to a particular font size in pixels, depending on device screen resolution and size.

See Also:

Constant Field Values

SIZE_SMALL

public static final int SIZE_SMALL

The "small" system-dependent font size.

Value 8 is assigned to SIZE_SMALL. Implementations SHOULD map this value to a particular font size in pixels, depending on device screen resolution and size.

See Also:

Constant Field Values

FACE_SYSTEM

public static final int FACE_SYSTEM

The "system" font face.

Value 0 is assigned to FACE_SYSTEM.

See Also:

Constant Field Values

FACE_MONOSPACE

public static final int FACE_MONOSPACE

The "monospace" font face.

Value 32 is assigned to FACE_MONOSPACE.

See Also:

Constant Field Values

FACE_PROPORTIONAL

public static final int FACE_PROPORTIONAL

The "proportional" font face.

Value 64 is assigned to FACE_PROPORTIONAL.

See Also:

Constant Field Values

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.

Since:

MIDP 2.0

See Also:

getFont(int fontSpecifier), Constant Field Values

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.

Since:

MIDP 2.0

See Also:

getFont(int fontSpecifier), Constant Field Values

FONT_IDLE_TEXT

public static final int FONT_IDLE_TEXT

Font specifier for unfocused text on the idle screen.

FONT_IDLE_TEXT can be is used with getFont to retrieve the appropriate Font for unfocused text on the IdleItem on the idle screen.

FONT_IDLE_TEXT has the value 2.

Since:

MIDP 3.0

See Also:

Constant Field Values

FONT_IDLE_HIGHLIGHTED_TEXT

public static final int FONT_IDLE_HIGHLIGHTED_TEXT

Font specifier for focused text on the idle screen.

FONT_IDLE_HIGHLIGHTED_TEXT can be is used with getFont to retrieve the appropriate Font for focused text on the IdleItem on the idle screen.

FONT_IDLE_HIGHLIGHTED_TEXT has the value 3.

Since:

MIDP 3.0

See Also:

Constant Field Values

Method Detail

createFont

public static Font createFont(java.io.InputStream fontData)
                       throws java.io.IOException

Returns a new Font using the specified font input data. The new Font is created with a default size SIZE_MEDIUM and style STYLE_PLAIN. This base font can then be used with the deriveFont methods in this class to derive new Font objects with varying sizes and styles. This method does not close the InputStream.

Font data can be made persistent. When the createFont method is called (using either downloaded font data, or the data from the Record Store as an InputStream), the input font data shall be validated before the font is created. Implementations MUST insure that the availability and use of fonts created using createFont method is limited to the execution environment of a MIDlet suite that instantiated the font. The created fonts can be discovered using getAvailableFonts methods and can also be queried by getStyle method. After createFont is called, a new Font may also be instantiated using getFont or deriveFont methods.

Parameters:

fontData - an InputStream object representing the input data for the font.

Returns:

a new Font created from the specified font type and input data.

Throws:

FontFormatException - if the fontData contains invalid font information, or if a font format is not supported.

java.io.IOException - if the fontData cannot be completely read.

Since:

MIDP 3.0

getFont

public static Font getFont(java.lang.String name,
                           int style,
                           int pixelSize)

Returns a new Font object from the font specified by name, style and size in pixels.

The font name can be a font face name or a font family name. It is used together with the style to find an appropriate font face. When a font family name is specified, the style argument is used to select the most appropriate face from the family. When a font face name is specified, the face's style and the style argument are merged to locate the best matching font from the same family. For example if face name "Arial Bold" is specified with style Font.ITALIC, the font system looks for a face in the "Arial" family that is bold and italic, and may associate the font instance with the physical font face "Arial Bold Italic". The style argument is merged with the specified face's style, not added or subtracted. This means, specifying a bold face and a bold style does not double-embolden the font, and specifying a bold face and a plain style does not lighten the font. If the font face name specifies a particular style that is not the same as style argument, the font face name definition takes priority. For example, if name = "Arial Italic", and style = STYLE_PLAIN, the Font object will reference "Arial Italic".

Fonts that are packaged with a MIDlet and declared in its Manifest can be instantiated using this method. Fonts that are downloaded at run-time or stored in the Record Store may be referenced using this method, but only after they are instantiated using createFont method.

If no face for the requested style can be found, the font system may apply algorithmic styling to achieve the desired style. For example, if ITALIC is requested, but no italic face is available, glyphs from the plain face may be algorithmically obliqued (slanted).

Font name lookup is case insensitive, using the case folding rules of the US locale.

Parameters:

name - the font name. This can be a font face name or a font family name, and may represent either a logical font or a physical font. The family names for logical fonts are: Dialog, DialogInput, Monospaced, Serif, or SansSerif. If name is null, the logical font name of the new Font as returned by getName() is set to the name "Default".

style - the style constant for the Font. The style argument is an integer bitmask that may be STYLE_PLAIN, or a bitwise union of STYLE_BOLD and/or STYLE_ITALIC (for example, STYLE_ITALIC or STYLE_BOLD | STYLE_ITALIC). If the style argument does not conform to one of the expected integer bitmasks then the style is set to STYLE_PLAIN.

pixelSize - a positive integer value representing the size of this Font in pixels. When value of this argument is equal to zero, the Font object will have the default size SIZE_MEDIUM.

Returns:

font that corresponds to the passed in font name, style and size attributes.

Throws:

java.lang.IllegalArgumentException - if the font with the specified name is not found, or if style or pixelSize are not legal values.

Since:

MIDP 3.0

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, FONT_STATIC_TEXT, FONT_IDLE_TEXT or FONT_IDLE_HIGHLIGHTED_TEXT

Returns:

font that corresponds to the passed-in font specifier

Throws:

java.lang.IllegalArgumentException - if fontSpecifier is not a valid fontSpecifier

Since:

MIDP 2.0

getFont

public static Font getFont(int face,
                           int style,
                           int size)

Obtains an object representing a font (including custom fonts that are either packaged with a MIDlet or downloaded at run-time, if applicable) 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, STYLE_BOLD or STYLE_ITALIC, or a combination of STYLE_BOLD and STYLE_ITALIC.

size - one of SIZE_SMALL, SIZE_MEDIUM, or SIZE_LARGE.

Returns:

font instance of the nearest font found.

Throws:

java.lang.IllegalArgumentException - if face, style, or size are not legal values

getFamily

public java.lang.String getFamily()

Gets the family name of this Font.

The family name of a font is font specific. Two fonts such as Helvetica Italic and Helvetica Bold have the same family name, Helvetica, whereas their font face names are Helvetica Bold and Helvetica Italic.

Use getName() to get the logical name of the font. Use getFontName() to get the font face name of the font.

Returns:

String that is the family name of this Font.

Since:

MIDP 3.0

See Also:

getName(), getFontName()

getName

public java.lang.String getName()

Gets the logical name of this Font.

Use getFamily() to get the family name of the font. Use getFontName() to get the font face name of the font.

Returns:

String representing the logical name of this Font.

See Also:

getFamily(), getFontName()

getFontName

public java.lang.String getFontName()

Gets the font face name of this Font. For example, Helvetica Bold could be returned as a font face name.

Use getFamily() to get the family name of the font. Use getName() to get the logical name of the font.

Returns:

String representing the font face name of this Font.

See Also:

getFamily(), getName()

getSize

public int getSize()

Gets the size of this Font. For a font object that was created using custom size in pixels, the return value indicates the range of a pixel size of a font.

• SIZE_SMALL is returned if the size of a font (in pixels) is smaller or equal to the system-dependent SIZE_SMALL;
• SIZE_MEDIUM is returned if the size of a font (in pixels) is larger then system-dependent SIZE_SMALL but smaller then system-dependent SIZE_LARGE;
• SIZE_LARGE is returned if the size of a font (in pixels) is equal or larger then system-dependent SIZE_LARGE;

Returns:

one of SIZE_SMALL, SIZE_MEDIUM or SIZE_LARGE.

getPixelSize

public int getPixelSize()

Gets the pixelSize of this Font. This pixelSize defines the height of the em box - a distance (in pixels) between the baselines of two unadjusted, adjacent lines of text in a single spaced text document.

Returns:

the size of this Font, in pixels.

Since:

MIDP 3.0

getPixelSize

public static int getPixelSize(java.lang.String name)

Gets the pixelSize supported by the font specified by name, in pixels.

If font is scalable, this method should return the value of 'zero'. If a font is the bitmap font, this pixelSize defines the height of the em box - a distance (in pixels) between the baselines of two unadjusted, adjacent lines of text in a single spaced text document.

Parameters:

name - the font name. This can be a font face name or a font family name, and may represent either a logical font or a physical font. The family names for logical fonts are: Dialog, DialogInput, Monospaced, Serif, or SansSerif. If name is null, the return value will indicate the size of the default system font.

Returns:

the size supported by the specified font, in pixels.

Throws:

java.lang.IllegalArgumentException - if the font with the specified name is not found.

Since:

MIDP 3.0

getStyle

public int getStyle()

Gets the style of this Font. The value can be STYLE_PLAIN, STYLE_BOLD, STYLE_ITALIC, or STYLE_BOLD | STYLE_ITALIC, or a combination of them OR'ed with STYLE_UNDERLINED.

Returns:

style of this Font.

See Also:

isPlain(), isBold(), isItalic(), isUnderlined()

getStyle

public static int getStyle(java.lang.String name)

Gets the style of the font specified by name. The return value can be STYLE_PLAIN, STYLE_BOLD, STYLE_ITALIC, or STYLE_BOLD | STYLE_ITALIC.

Parameters:

name - the font name. This can be a font face name or a font family name, and may represent either a logical font or a physical font. The family names for logical fonts are: Dialog, DialogInput, Monospaced, Serif, or SansSerif. If name is null, the return value will indicate the style of the default system font.

Returns:

style of the specified font.

Throws:

java.lang.IllegalArgumentException - if the font with the specified name is not found.

Since:

MIDP 3.0

isPlain

public boolean isPlain()

Returns true if the font is plain.

Indicates whether or not this Font object's style is STYLE_PLAIN.

Returns:

true if this Font is plain, false otherwise.

See Also:

getStyle()

isBold

public boolean isBold()

Returns true if the font is bold.

Indicates whether or not this Font object's style is STYLE_BOLD.

Returns:

true if this Font is bold, false otherwise.

See Also:

getStyle()

isItalic

public boolean isItalic()

Returns true if the font is italic.

Indicates whether or not this Font object's style is STYLE_ITALIC.

Returns:

true if this Font is italic, false otherwise.

See Also:

getStyle()

isUnderlined

public boolean isUnderlined()

Returns true if the font is underlined.

Indicates whether or not this Font object's style is STYLE_UNDERLINED.

Returns:

true if this Font is underlined.

See Also:

getStyle()

getDefaultFont

public static Font getDefaultFont()

Gets the default font of the system.

Returns:

the default font

getFace

public int getFace()

Gets the face of the font.

When this method is called with a Font object that was created from font data packaged with a MIDlet or downloaded at run-time and instantiated using createFont method, the call may return either FACE_PROPORTIONAL or FACE_MONOSPACE values, based on the information encoded in a font data.

Returns:

one of FACE_SYSTEM, FACE_PROPORTIONAL, FACE_MONOSPACE

getAvailableFonts

public static Font[] getAvailableFonts()

Returns an array of Font where each Font object represents a physical font available in the system. Font object will be created for each font face, even if they belong to the same font family. For example, if four different fonts representing faces "Arial", "Arial Italic", "Arial Bold" and "Arial Bold Italic" are available, the array returned by getAvailableFonts will have four different Font objects.

Fonts that are packaged with a MIDlet and declared in its manifest will be instantiated and included in the Font array. Fonts that are downloaded at run-time or stored in the Record Store will be included only after they are instantiated using createFont method.

Returns:

an array of Font representing all available physical fonts. Font objects are created with the default size.

Since:

MIDP 3.0

See Also:

getAvailableFonts(int style), getAvailableFonts(int face, int style, int pixelSize)

getAvailableFonts

public static Font[] getAvailableFonts(int style)

Returns an array of Font objects where each object represents a physical font having specified style. For example, if three different font families "Arial", "Courier New" and "Times New Roman" are available, and if style = STYLE_ITALIC - the Font[] will have three objects representing font faces "Arial Italic", "Courier New Italic" and "Times New Roman Italic".

Fonts that are packaged with a MIDlet and declared in its manifest will be instantiated and included in the Font array. Fonts that are downloaded at run-time or stored in the Record Store will be included only after they are instantiated using createFont method.

Parameters:

style - STYLE_PLAIN, STYLE_BOLD or STYLE_ITALIC, or a combination of STYLE_BOLD and STYLE_ITALIC.

Returns:

an array of Font representing available physical fonts having specified style. Font objects are created with the default size.

Since:

MIDP 3.0

See Also:

getAvailableFonts(), getAvailableFonts(int face, int style, int pixelSize)

getAvailableFonts

public static Font[] getAvailableFonts(int face,
                                       int style,
                                       int pixelSize)

Returns an array of Font objects where each object represents a physical font having specified face, style and pixelSize. For example, if three different font families "Arial", "Courier New" and "Times New Roman" are available, and if face = FACE_PROPORTIONAL and style = STYLE_PLAIN - the Font[] will have two objects representing proportional font faces "Arial" and "Times New Roman" in the specified pixelSize.

Fonts that are packaged with a MIDlet and declared in its manifest will be instantiated and included in the Font array. Fonts that are downloaded at run-time or stored in the Record Store will be included only after they are instantiated using createFont method.

Parameters:

face - one of FACE_SYSTEM, FACE_MONOSPACE, or FACE_PROPORTIONAL

style - STYLE_PLAIN, STYLE_BOLD or STYLE_ITALIC, or a combination of STYLE_BOLD and STYLE_ITALIC

pixelSize - a positive integer value representing the size of this Font in pixels. When value of this argument is equal to zero, the Font object will have the default size SIZE_MEDIUM.

Returns:

an array of Font representing available fonts having specified face, style and size.

Since:

MIDP 3.0

See Also:

getAvailableFonts(), getAvailableFonts(int style)

equals

public boolean equals(java.lang.Object obj)

Compares this Font object to the specified Object.

The equality of two Font objects is determined based on the comparison of their parameters such as font face name, style, pixel size, ascent and descent. However, since two Font objects may be instantiated from different font resources (either downloaded or resident) they may still differ, e.g. in character set coverage.

Overrides:

equals in class Object

Overrides:

equals in class java.lang.Object

Parameters:

obj - the Object to compare.

Returns:

true if the argument is a Font object having the same name, style, pixelSize, ascent and descent as this object; false otherwise.

Since:

MIDP 3.0

deriveFont

public Font deriveFont(int style,
                       int pixelSize)

Creates a new Font object by replicating this Font object and applying a new style and size.

Parameters:

style - STYLE_PLAIN, STYLE_BOLD or STYLE_ITALIC, or a combination of STYLE_BOLD and STYLE_ITALIC, or a combination of them and STYLE_UNDERLINED

pixelSize - a positive integer value representing the size of this Font in pixels. When value of this argument is equal to zero, the Font object will have the default size SIZE_MEDIUM.

Returns:

a new Font object.

Throws:

java.lang.IllegalArgumentException - if style or pixelSize are not legal values (e.g. when the current font object is a non-scalable bitmap font)

Since:

MIDP 3.0

deriveFont

public Font deriveFont(int pixelSize)

Creates a new Font object by replicating this Font object and applying a new size to it.

Parameters:

pixelSize - a positive integer value representing the size of this Font in pixels. When value of this argument is equal to zero, the Font object will have the default size SIZE_MEDIUM.

Returns:

a new Font object.

Throws:

java.lang.IllegalArgumentException - if pixelSize is not a legal value (e.g. when the current font object is a non-scalable bitmap font)

Since:

MIDP 3.0

getBaselinePosition

public int getBaselinePosition()

Gets the distance in pixels from the top of the text to the text's baseline, which is defined by the MaxAscent value of a font.

Returns:

the distance in pixels from the top of the text to the text's baseline

See Also:

getMaxAscent(), getMaxDescent()

stringWidth

public int stringWidth(java.lang.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. Note that the advance of a String is not necessarily the sum of the advance widths of its characters.

Parameters:

str - the String to be measured

Returns:

the total advance width

Throws:

java.lang.NullPointerException - if str is null

See Also:

charsWidth(char[] ch, int offset, int length), substringWidth(String str, int offset, int len)

substringWidth

public int substringWidth(java.lang.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. Note that the advance of a String is not necessarily the sum of the advance widths of its characters.

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:

java.lang.StringIndexOutOfBoundsException - if offset and length specify an invalid range

java.lang.NullPointerException - if str is null

See Also:

charsWidth(char[] ch, int offset, int length)

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 for showing a substring of the array ch in this Font; 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 be measured

Returns:

the width of the character range

Throws:

java.lang.ArrayIndexOutOfBoundsException - if offset and length specify an invalid range

java.lang.NullPointerException - if ch is null

See Also:

substringWidth(String str, int offset, int len)

getLeading

public int getLeading()

Gets the standard leading, in pixels, of this Font object. The standard leading, or interline spacing, is the logical amount of space to be reserved between the descent of one line of text and the ascent of the next line. The height metric is calculated to include this extra space.

Returns:

standard leading of the Font in pixels.

Since:

MIDP 3.0

See Also:

getHeight(), getAscent(), getDescent()

getAscent

public int getAscent()

Gets the font ascent of this Font object. The font ascent is the distance from the font's baseline to the top of most alphanumeric characters. Some characters in the Font might extend above the font ascent line.

Returns:

the font ascent of the Font in pixels.

Since:

MIDP 3.0

See Also:

getMaxAscent()

getDescent

public int getDescent()

Gets the font descent of this Font object. The font descent is the distance from the font's baseline to the bottom of most alphanumeric characters. Some characters in the Font might extend below the font descent line.

Returns:

the font descent of the Font in pixels.

Since:

MIDP 3.0

See Also:

getMaxDescent()

getHeight

public int getHeight()

Gets the standard height of a line of text in this font. This is the distance in pixels between two baselines of adjacent lines of text and is equal to the sum of the leading + ascent + descent. Due to rounding this may not be the same as getAscent() + getDescent() + getLeading(). There is no guarantee that lines of text spaced at this distance are disjoint; such lines may overlap if some characters overshoot either the standard ascent or the standard descent metric.

Returns:

standard height of a line of text in this font (a non-negative value), in pixels.

See Also:

getLeading(), getAscent(), getDescent()

getMaxAscent

public int getMaxAscent()

Gets the maximum ascent of this Font. No character extends further above the font's maximum ascent line.

Returns:

the maximum ascent of the Font in pixels.

Since:

MIDP 3.0

See Also:

getAscent()

getMaxDescent

public int getMaxDescent()

Gets the maximum descent of this Font. No character extends further below the font's maximum descent line.

Returns:

the font descent of the Font in pixels.

Since:

MIDP 3.0

See Also:

getDescent()