com.sun.dtv.lwuit
Class Font

java.lang.Object
  com.sun.dtv.lwuit.Font

public abstract class Font
extends Object

A simple abstraction of platform fonts and library fonts that enables the library to use more elaborate fonts unsupported by a specific device. This abstraction also supports bitmap fonts using an Ant task (more details about the unifier are explained in the javadoc overview document).

A bitmap font can be created manually but that is tedious, normally you would use the Ant task as illustrated bellow to produce a resource file containing the supported bitmap font. For further detail read the overview document and Resources.

<target name="pre-init">
     <taskdef classpath="ImageUnifier.jar" classname="com.sun.jwt.resource.Builder" name="build" />
     <build dest="src/font.res">
        <font src="images/arial.ttf" bold="true" italic="true" size="11" />
        <font logicalName="Dialog" />
    </build>
</target>

The following attributes can be expressed for a font ant task:

• name - name for the font to load from the resource file (optional: defaults to logical name or file name).
• charset - defaults to the English alphabet, numbers and common signs. Should contain a list of all characters that should be supported by a font. E.g. if a font would always be used for uppercase letters then it would save space to define the charset as: "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
• src - font file in the case of using a file, defaults to TrueType font
• size - floating point size of the font
• bold - defaults to false indicates if the font should be bold
• italic - defaults to false indicates if the font should be italic
• trueType - defaults to true, relevant only when src is used. If set to false type 1 fonts are assumed.
• antiAliasing - defaults to true otherwise fonts will be aliased
• logicalName - logical name of the font as specified by java.awt.Font in Java SE: Dialog, DialogInput, Monospaced, Serif, or SansSerif

For usage of LWUIT within the DTV specification, a Font object always wraps an instance of java.awt.Font. The access to the wrapped object is encouraged only if this is really necessary in order to handle a specific LWUIT vs. AWT integration issue. It should not be used for ordinary tasks.

Field Summary

static int	FACE_MONOSPACE Constant allowing us to author portable system fonts.
static int	FACE_PROPORTIONAL Constant allowing us to author portable system fonts.
static int	FACE_SYSTEM Constant allowing us to author portable system fonts.
static int	SIZE_LARGE Constant allowing us to author portable system fonts.
static int	SIZE_MEDIUM Constant allowing us to author portable system fonts.
static int	SIZE_SMALL Constant allowing us to author portable system fonts.
static int	STYLE_BOLD Constant allowing us to author portable system fonts.
static int	STYLE_ITALIC Constant allowing us to author portable system fonts.
static int	STYLE_PLAIN Constant allowing us to author portable system fonts.
static int	STYLE_UNDERLINED Constant allowing us to author portable system fonts.

Constructor Summary

protected	Font() Constructs a Font object.
	Font(Font f) Create a LWUIT Font object using an AWT Font instance to be wrapped.
	Font(String name, int style, int size) Constructs a Font object.

Method Summary

void	addContrast(byte value) Increase the contrast of the bitmap font for rendering on top of a surface whose color is darker.
int	charsWidth(char[] ch, int offset, int length) Return the width of the given characters in this font instance.
abstract int	charWidth(char ch) Return the width of the specific character when rendered alone.
static void	clearBitmapCache() Bitmap fonts are cached.
static Font	createBitmapFont(Image bitmap, int[] cutOffsets, int[] charWidth, String charsets) Creates a bitmap font with the given arguments.
static Font	createBitmapFont(String name, Image bitmap, int[] cutOffsets, int[] charWidth, String charsets) Creates a bitmap font with the given arguments and places said font in the cache.
static Font	createSystemFont(int face, int style, int size) Creates a system native font in a similar way to common MIDP fonts.
static Font	decode(String str) Returns the Font described by the argument.
abstract void	drawChar(Graphics g, char character, int x, int y) Draw the given char using the current font and color in the x,y coordinates.
boolean	equals(Object obj) Compares this Font object to the specified.
Map	getAttributes() Returns a map of attributes available in this Font.
Font	getAWTFont() Obtains the java.awt.Font object wrapped by this Font instance.
static Font	getBitmapFont(String fontName) Returns a previously loaded bitmap font from cache.
String	getCharset() Returns a string containing all the characters supported by this font.
static Font	getDefaultFont() Return the global default font instance.
int	getFace() Return Optional operation returning the font face for system fonts.
String	getFamily() Returns the family name of this Font.
static Font	getFont(Map attributes) Returns a Font appropriate to this attribute set.
static Font	getFont(String nm) Returns a Font object from the system properties list.
static Font	getFont(String nm, Font font) Gets the specified Font from the system.
abstract int	getHeight() Return the total height of the font.
String	getName() Returns the logical name of this Font.
int	getSize() Return Optional operation returning the font size for system fonts.
int	getStyle() Return Optional operation returning the font style for system fonts.
int	hashCode() Returns a hash code for this Font.
boolean	isBold() Indicates whether this Font is BOLD.
boolean	isItalic() Indicates whether this Font is ITALIC.
boolean	isPlain() Indicates whether this Font is PLAIN.
static void	setDefaultFont(Font f) Sets the global default font instance.
int	stringWidth(String str) Return the width of the given string in this font instance.
int	substringWidth(String str, int offset, int len) Return the width of the given string subset in this font instance.
String	toString() Converts this Font object into a String.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

FACE_MONOSPACE

public static final int FACE_MONOSPACE

Constant allowing us to author portable system fonts.

See Also:

Constant Field Values

FACE_PROPORTIONAL

public static final int FACE_PROPORTIONAL

Constant allowing us to author portable system fonts.

See Also:

Constant Field Values

FACE_SYSTEM

public static final int FACE_SYSTEM

Constant allowing us to author portable system fonts.

See Also:

Constant Field Values

SIZE_LARGE

public static final int SIZE_LARGE

Constant allowing us to author portable system fonts.

See Also:

Constant Field Values

SIZE_MEDIUM

public static final int SIZE_MEDIUM

Constant allowing us to author portable system fonts.

See Also:

Constant Field Values

SIZE_SMALL

public static final int SIZE_SMALL

Constant allowing us to author portable system fonts.

See Also:

Constant Field Values

STYLE_BOLD

public static final int STYLE_BOLD

Constant allowing us to author portable system fonts.

See Also:

Constant Field Values

STYLE_ITALIC

public static final int STYLE_ITALIC

Constant allowing us to author portable system fonts.

See Also:

Constant Field Values

STYLE_UNDERLINED

public static final int STYLE_UNDERLINED

Constant allowing us to author portable system fonts.

See Also:

Constant Field Values

STYLE_PLAIN

public static final int STYLE_PLAIN

Constant allowing us to author portable system fonts.

See Also:

Constant Field Values

Constructor Detail

Font

protected Font()

Constructs a Font object.

Font

public Font(String name,
            int style,
            int size)

Constructs a Font object.

Parameters:

name - the font's name

style - the font's style

size - the font's size

Font

public Font(Font f)

Create a LWUIT Font object using an AWT Font instance to be wrapped.

Parameters:

f - an AWT Font instance to be wrapped

Method Detail

getBitmapFont

public static Font getBitmapFont(String fontName)

Returns a previously loaded bitmap font from cache.

Parameters:

fontName - the font name is the logical name of the font

Returns:

a Font object

See Also:

clearBitmapCache()

clearBitmapCache

public static void clearBitmapCache()

Bitmap fonts are cached. This method allows to flush the cache thus allows to reload a font.

addContrast

public void addContrast(byte value)

Increase the contrast of the bitmap font for rendering on top of a surface whose color is darker. This is useful when drawing anti-aliased bitmap fonts using a light color (e.g. white) on top of a dark surface (e.g. black), the font often breaks down if its contrast is not increased due to the way alpha blending appears to the eye.

Notice that this method only works in one way, contrast cannot be decreased properly in a font and it should be cleared and reloaded with a Look and Feel switch.

Parameters:

value - the value to increase

createBitmapFont

public static Font createBitmapFont(String name,
                                    Image bitmap,
                                    int[] cutOffsets,
                                    int[] charWidth,
                                    String charsets)

Creates a bitmap font with the given arguments and places said font in the cache.

Parameters:

name - the name for the font in the cache

bitmap - a transparency map in red and black that indicates the characters

cutOffsets - character offsets matching the bitmap pixels and characters in the font

charWidth - The width of the character when drawing... this should not be confused with the number of cutOffset[o + 1] - cutOffset[o]. They are completely different since a character can be "wider" and "seep" into the next region. This is especially true with italic characters all of which "lean" outside of their bounds.

charsets - the set of characters in the font

Returns:

a font object to draw bitmap fonts

createBitmapFont

public static Font createBitmapFont(Image bitmap,
                                    int[] cutOffsets,
                                    int[] charWidth,
                                    String charsets)

Creates a bitmap font with the given arguments.

Parameters:

bitmap - a transparency map in red and black that indicates the characters

cutOffsets - character offsets matching the bitmap pixels and characters in the font

charWidth - The width of the character when drawing... this should not be confused with the number of cutOffset[o + 1] - cutOffset[o]. They are completely different since a character can be "wider" and "seep" into the next region. This is especially true with italic characters all of which "lean" outside of their bounds.

charsets - the set of characters in the font

Returns:

a font object to draw bitmap fonts

createSystemFont

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

Creates a system native font in a similar way to common MIDP fonts.

Parameters:

face - One of FACE_SYSTEM, FACE_PROPORTIONAL, FACE_MONOSPACE

style - one of STYLE_PLAIN, STYLE_ITALIC, STYLE_BOLD

size - One of SIZE_SMALL, SIZE_MEDIUM, SIZE_LARGE

Returns:

A newly created system font instance

charsWidth

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

Return the width of the given characters in this font instance.

Parameters:

ch - array of characters

offset - characters offsets

length - characters length

Returns:

the width of the given characters in this font instance

substringWidth

public int substringWidth(String str,
                          int offset,
                          int len)

Return the width of the given string subset in this font instance.

Parameters:

str - the given string

offset - the string offset

len - the len od string

Returns:

the width of the given string subset in this font instance

stringWidth

public int stringWidth(String str)

Return the width of the given string in this font instance.

Parameters:

str - the given string *

Returns:

the width of the given string in this font instance

charWidth

public abstract int charWidth(char ch)

Return the width of the specific character when rendered alone.

Parameters:

ch - the specific character

Returns:

the width of the specific character when rendered alone

getHeight

public abstract int getHeight()

Return the total height of the font.

Returns:

the total height of the font

drawChar

public abstract void drawChar(Graphics g,
                              char character,
                              int x,
                              int y)

Draw the given char using the current font and color in the x,y coordinates.

Parameters:

g - the graphics object

character - the given character

x - the x coordinate to draw the char

y - the y coordinate to draw the char

getDefaultFont

public static Font getDefaultFont()

Return the global default font instance.

Returns:

the global default font instance

See Also:

setDefaultFont(com.sun.dtv.lwuit.Font)

setDefaultFont

public static void setDefaultFont(Font f)

Sets the global default font instance.

Parameters:

f - the global default font instance

See Also:

getDefaultFont()

getFace

public int getFace()

Return Optional operation returning the font face for system fonts.

Returns:

Optional operation returning the font face for system fonts

getSize

public int getSize()

Return Optional operation returning the font size for system fonts.

Returns:

Optional operation returning the font size for system fonts

getStyle

public int getStyle()

Return Optional operation returning the font style for system fonts.

Returns:

Optional operation returning the font style for system fonts

getCharset

public String getCharset()

Returns a string containing all the characters supported by this font. Will return null for system fonts.

Returns:

String containing the characters supported by a bitmap font or null otherwise.

getAWTFont

public Font getAWTFont()

Obtains the java.awt.Font object wrapped by this Font instance.

Returns:

the wrapped java.awt.Font object

decode

public static Font decode(String str)

Returns the Font described by the argument.

IMPLEMENTATION NOTE: Delegate to the wrapped AWT font object.

Parameters:

str - the description

Returns:

the Font to be found

equals

public boolean equals(Object obj)

Compares this Font object to the specified.

IMPLEMENTATION NOTE: Delegate to the wrapped AWT font object.

Overrides:

equals in class Object

Parameters:

obj - the object to compare with.

Returns:

true if equals, false otherwise.

getAttributes

public Map getAttributes()

Returns a map of attributes available in this Font.

IMPLEMENTATION NOTE: Delegate to the wrapped AWT font object.

Returns:

the attribute map

getFamily

public String getFamily()

Returns the family name of this Font.

IMPLEMENTATION NOTE: Delegate to the wrapped AWT font object.

Returns:

the family name

getFont

public static Font getFont(Map attributes)

Returns a Font appropriate to this attribute set.

IMPLEMENTATION NOTE: Delegate to the wrapped AWT font object.

Parameters:

attributes - the attribute set

Returns:

the appropriate Font

getFont

public static Font getFont(String nm)

Returns a Font object from the system properties list.

IMPLEMENTATION NOTE: Delegate to the wrapped AWT font object.

Parameters:

nm - the property name

Returns:

the appropriate Font

getFont

public static Font getFont(String nm,
                           Font font)

Gets the specified Font from the system.

IMPLEMENTATION NOTE: Delegate to the wrapped AWT font object.

Parameters:

nm - the property name

font - a default Font to be returned if the property name does not exist

Returns:

the Font found

getName

public String getName()

Returns the logical name of this Font.

IMPLEMENTATION NOTE: Delegate to the wrapped AWT font object.

Returns:

the logical name

hashCode

public int hashCode()

Returns a hash code for this Font.

IMPLEMENTATION NOTE: Delegate to the wrapped AWT font object.

Overrides:

hashCode in class Object

Returns:

the hashcode

isBold

public boolean isBold()

Indicates whether this Font is BOLD.

IMPLEMENTATION NOTE: Delegate to the wrapped AWT font object.

Returns:

true if Font is BOLD, false otherwise

isItalic

public boolean isItalic()

Indicates whether this Font is ITALIC.

IMPLEMENTATION NOTE: Delegate to the wrapped AWT font object.

Returns:

true if Font is ITALIC, false otherwise

isPlain

public boolean isPlain()

Indicates whether this Font is PLAIN.

IMPLEMENTATION NOTE: Delegate to the wrapped AWT font object.

Returns:

true if Font is PLAIN, false otherwise

toString

public String toString()

Converts this Font object into a String.

IMPLEMENTATION NOTE: Delegate to the wrapped AWT font object.

Overrides:

toString in class Object

Returns:

a String representation of this Font