FileDocCategorySizeDatePackage
Font.javaAPI DocphoneME MR2 API (J2ME)19023Wed May 02 18:00:08 BST 2007javax.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:

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

since
MIDP 1.0

Fields Summary
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.

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.

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.

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.

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

Value 8 is assigned to STYLE_SMALL.

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

Value 0 is assigned to STYLE_MEDIUM.

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

Value 16 is assigned to SIZE_LARGE.

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

Value 0 is assigned to FACE_SYSTEM.

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

Value 32 is assigned to FACE_MONOSPACE.

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

Value 64 is assigned to FACE_PROPORTIONAL.

public static final int
FONT_STATIC_TEXT
Default font specifier used to draw Item and Screen contents. FONT_STATIC_TEXT has the value 0.
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.
private int
face
The face of this Font
private int
style
The style of this Font
private int
size
The point size of this Font
private int
baseline
The baseline of this Font
private int
height
The height of this Font
private int
glyphHeight
The height without leading of this Font
com.sun.me.gci.renderer.GCIFont
gciFont
GCI Font mapping
private static Font
DEFAULT_FONT
The "default" font, constructed from the 'system' face, plain style, and 'medium' size point.
private static Hashtable
table
A hashtable used to maintain a store of created Fonts so they are not re-created in the future
Constructors Summary
private Font(int inp_face, int inp_style, int inp_size)
Construct a new Font object

param
inp_face The face to use to construct the Font
param
inp_style The style to use to construct the Font
param
inp_size The point size to use to construct the Font

        face  = inp_face;
        style = inp_style;
        size  = inp_size;

        // TODO mapping of face, style, size
        gciFont = GCIFontEnvironment.getInstance().getFont("Courier", 
                                                           inp_style,
                                                           12,
                                                           isUnderlined(),
                                                           false);

        baseline = gciFont.getMaxAscent();
        glyphHeight = baseline + gciFont.getMaxDescent();
        height = glyphHeight + gciFont.getLeading();
    
Methods Summary
public intcharWidth(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.

param
ch the character to be measured
return
the total advance width (a non-negative value)

        return gciFont.getStringWidth(new String(new char[]{ch}));
    
public intcharsWidth(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.

param
ch the array of characters
param
offset the index of the first character to measure
param
length the number of characters to measure
return
the width of the character range
throws
ArrayIndexOutOfBoundsException if offset and length specify an invalid range
throws
NullPointerException if ch is null

        if (ch == null) {
            throw new NullPointerException();
        }

        try {
            String strToRender = new String(ch, offset, length);
            return gciFont.getStringWidth(strToRender);
        } catch (IndexOutOfBoundsException i) {
            throw new ArrayIndexOutOfBoundsException();
        }
    
public intgetBaselinePosition()
Gets the distance in pixels from the top of the text to the text's baseline.

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

        // SYNC NOTE: return of atomic value, no locking necessary
        return baseline;
    
public static javax.microedition.lcdui.FontgetDefaultFont()
Gets the default font of the system.

return
the default font

        synchronized (Display.LCDUILock) {
            if (DEFAULT_FONT == null)
                DEFAULT_FONT = new Font(FACE_SYSTEM, STYLE_PLAIN, SIZE_MEDIUM);
            return DEFAULT_FONT;
        }
    
public intgetFace()
Gets the face of the font.

return
one of FACE_SYSTEM, FACE_PROPORTIONAL, FACE_MONOSPACE

 
        // SYNC NOTE: return of atomic value, no locking necessary
        return face;
    
public static javax.microedition.lcdui.FontgetFont(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.

param
fontSpecifier one of FONT_INPUT_TEXT, or FONT_STATIC_TEXT
return
font that corresponds to the passed in font specifier
throws
IllegalArgumentException if fontSpecifier is not a valid fontSpecifier


                                                                    
         

        Font font;

        switch (fontSpecifier) {
        case FONT_STATIC_TEXT: 
        case FONT_INPUT_TEXT:
            font = getDefaultFont();
            break;
        default:
            throw new IllegalArgumentException();
        }
        return font;
    
public static javax.microedition.lcdui.FontgetFont(int inp_face, int inp_style, int inp_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.

param
inp_face one of FACE_SYSTEM, FACE_MONOSPACE, or FACE_PROPORTIONAL
param
inp_style STYLE_PLAIN, or a combination of STYLE_BOLD, STYLE_ITALIC, and STYLE_UNDERLINED
param
inp_size one of SIZE_SMALL, SIZE_MEDIUM, or SIZE_LARGE
return
instance the nearest font found
throws
IllegalArgumentException if face, style, or size are not legal values

        if ((inp_face != FACE_SYSTEM) 
            && (inp_face != FACE_MONOSPACE)
            && (inp_face != FACE_PROPORTIONAL)) {
            throw new IllegalArgumentException("Unsupported face");
        }

        if ((inp_style & ((STYLE_UNDERLINED << 1) - 1)) != inp_style) {
            throw new IllegalArgumentException("Illegal style");
        }

        if ((inp_size != SIZE_SMALL) 
            && (inp_size != SIZE_MEDIUM)
            && (inp_size != SIZE_LARGE)) {
            throw new IllegalArgumentException("Unsupported size");
        }

        synchronized (Display.LCDUILock) {
            /* IMPL_NOTE: this makes garbage.  
             * But hashtables need Object keys. */
            Integer key = new Integer(inp_face | inp_style | inp_size);
            Font f = (Font)table.get(key);
            if (f == null) {
                f = new Font(inp_face, inp_style, inp_size);
                table.put(key, f);
            }

            return f;
        }
    
public intgetHeight()
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.

return
standard height of a line of text in this font (a non-negative value)

        // SYNC NOTE: return of atomic value, no locking necessary
        return height;
    
intgetMaxGlyphHeight()
Gets the standard height of a line of text in this font. This extra space (leading) occurs below the text is not included in this value.

return
standard height of a line of text in this font (a non-negative value)

        // SYNC NOTE: return of atomic value, no locking necessary
        return glyphHeight;
    
public intgetSize()
Gets the size of the font.

return
one of SIZE_SMALL, SIZE_MEDIUM, SIZE_LARGE

        // SYNC NOTE: return of atomic value, no locking necessary
        return size;
    
public intgetStyle()
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).

return
style of the current font
see
#isPlain()
see
#isBold()
see
#isItalic()

        // SYNC NOTE: return of atomic value, no locking necessary
        return style;
    
public booleanisBold()
Returns true if the font is bold.

see
#getStyle()
return
true if font is bold

        // SYNC NOTE: return of atomic value, no locking necessary
        return (style & STYLE_BOLD) == STYLE_BOLD;
    
public booleanisItalic()
Returns true if the font is italic.

see
#getStyle()
return
true if font is italic

        // SYNC NOTE: return of atomic value, no locking necessary
        return (style & STYLE_ITALIC) == STYLE_ITALIC;
    
public booleanisPlain()
Returns true if the font is plain.

see
#getStyle()
return
true if font is plain

        // SYNC NOTE: return of atomic value, no locking necessary
        return style == STYLE_PLAIN;
    
public booleanisUnderlined()
Returns true if the font is underlined.

see
#getStyle()
return
true if font is underlined

        // SYNC NOTE: return of atomic value, no locking necessary
        return (style & STYLE_UNDERLINED) == STYLE_UNDERLINED;
    
public intstringWidth(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.

param
str the String to be measured
return
the total advance width
throws
NullPointerException if str is null

        if (str == null) {
            throw new NullPointerException();
        }
        return gciFont.getStringWidth(str);
    
public intsubstringWidth(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.

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

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

        try {
            // This will generate NullPointerException
            String strToRender = str.substring(offset, offset + len);
            return gciFont.getStringWidth(strToRender);
        } catch (IndexOutOfBoundsException i) {
            throw new StringIndexOutOfBoundsException();
        }