What's New In MIDP 3.0 ? Part 25: LCDUI - Fonts

1. Terminology And Definitions

1.1 Font Names

1.1.1 The Family Name

The family name of a Font can be either a foundry or design name, for example, Courier or Geneva, or a logical name.

The logical names are

• Dialog

• DialogInput

• Monospaced

• Serif

• SansSerif

1.1.2 The Face Name

The face name specifies the family and style of the font, for example, Arial Narrow Bold or Times Italic.

1.1.3 The Logical Name

The logical name of a Font is the the name that was used to construct the font.

The logical name of a Font that was constructed without a name is “Default”.

1.1.4 The Name Of The Default System Font

The MIDP 3 Font methods which take a Font name can be passed null in which case the method is applied to the default system Font.

1.2 Font Pixel Size

The specification defines the pixel size of a Font to be

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.

A pixel size argument of zero is equivalent to a pixel size equal to the value corresponding to the logical size SIZE_MEDIUM.

1.3 Logical Font Attributes

Prior to MIDP 3 Fonts were specified in terms of logical attributes. These continue to be used by some of the new MIDP 3 Font functionality, and the following is included for reference.

1.3.1 Face

There are three logical faces defined by the following Font constants

• FACE_MONOSPACE

• FACE_PROPORTIONAL

• FACE_SYSTEM

1.3.2 Size

There are three logical sizes defined by the following Font constants

• SIZE_SMALL

• SIZE_MEDIUM

• SIZE_PROPORTIONAL

1.3.3 Style

There are four style constants defined in the Font class

• STYLE_PLAIN

• STYLE_BOLD

• STYLE_ITALIC

• STYLE_UNDERLINED

These are all bit-flags and can be used in the following combinations

• STYLE_PLAIN

• STYLE_PLAIN|STYLE_UNDERLINED

• STYLE_BOLD

• STYLE_BOLD|STYLE_UNDERLINED

• STYLE_ITALIC

• STYLE_ITALIC|STYLE_UNDERLINED

• STYLE_BOLD|STYLE_ITALIC

• STYLE_BOLD|STYLE_ITALIC|STYLE_UNDERLINED

2. Font Format Support

The specification requires that when creating Fonts from Font data supplied by a MIDlet Suite, LIBlet, or a MIDlet at runtime, an implementation support OpenType fonts with TrueType outlines of up to 200KB in size.

The specification permits an implementation to discard individual fonts with a file size that exceeds 200KB.

3. Bundled Fonts

Fonts can be bundled with a MIDlet Suite or LIBlet. At runtime they can be used by a MIDlet in exactly the same way as built-in fonts.

Fonts bundled with a MIDlet Suite are specified at installation time using the

    MIDlet-Font

attribute.

The value should be a comma separated list of pathnames which identify files within the MIDlet Suite Jar which contain font data in a supported format.

The equivalent attribute for use in a LIBlet is

    LIBlet-Font

4. New Functionality

4.1 Font Creation

A Font can be created at runtime using the Font method

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

The fontData should specify an InputStream giving access to Font data in a supported format.

The method will not close the specified InputStream.

If the Font data is invalid or in an unsupported format then a FontFormatException will be thrown.

The style and size of the created Font will be the same as those of a Font created with a style of STYLE_PLAIN and a size of SIZE_MEDIUM.

Note

• It is not clear what the scope of a Font created is in this way is.

  The method documentation says

  the availability and use of fonts created using createFont method is limited to the execution environment of a MIDlet suite that instantiated the font.

  However, in the Downloadable Fonts section of the javax.microedition.lcdui package documentation
  it says

  Implementations MUST make all individual fonts available (whether downloaded or packaged) to all MIDlets in the MIDlet suite at runtime if the individual font file size does not exceed 200KB.

  and also

  Implementations MUST ensure that the availability and use of fonts packaged with a MIDlet suite in a JAR, packaged with any dependency LIBlets, or downloaded at runtime and created using createFont method are limited to the MIDlet’s runtime execution environment.

  which might just be three ways of saying the same thing. It is difficult to say given the variations in terminology
  being employed.

4.2 Font Discovery

4.2.1 Listing All The Available Fonts

A MIDlet can obtain a list of all the Fonts available to it by calling the Font method.

    public static Font[] getAvailableFonts()

The method result will include all bundled and created fonts.

4.2.2 Listing All The Available Fonts Of A Given Style

A MIDlet can obtain a list of all the Fonts of a given style available to it by calling the Font method.

    public static Font[] getAvailableFonts(int style)

The style argument should be one of

• STYLE_PLAIN

• STYLE_BOLD

• STYLE_ITALIC

• STYLE_BOLD|STYLE_ITALIC

The method result will include all bundled and created fonts.

Note

• The behaviour when the style argument is not legal is not specified.

4.2.3 Listing All The Available Fonts Of A Given Face, Style And Size

A MIDlet can obtain a list of all the Fonts of a given style and pixel size available to it by calling the Font method.

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

The face argument should specify a legal logical Font face.

The style argument should be one of

• STYLE_PLAIN

• STYLE_BOLD

• STYLE_ITALIC

• STYLE_BOLD|STYLE_ITALIC

The method result will include all bundled and created fonts.

Note

• The behaviour when the face, style or pixelSize argument is not legal is not specified.

4.3 Accessing Fonts

A named Font with a specific style and pixel size can be obtained by calling the Font method.

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

The name argument can specify either a face name or a family name or null.

It is an error if the Font specified by the name argument cannot be found an IllegalArgumentException.

The style argument should be one of

• STYLE_PLAIN

• STYLE_BOLD

• STYLE_ITALIC

• STYLE_BOLD|STYLE_ITALIC

If it is not then a value of STYLE_PLAIN is used.

It is an error if the pixelSize argument is less than zero and an IllegalArgumentException will be thrown.

If the name argument specifies a face name which includes style information, then if the specified style argument is the same or contradicts that in the face name it is ignored. Otherwise the style information from the face name and the style argument is combined.

Note

• The method documentation for the style argument says

  If the style argument does not conform to one of the expected integer bitmasks then the style is set to STYLE_PLAIN.

  It then goes on to say that an IllegalArgumentException will be thrown

  if style or pixelSize are not legal values.

4.4 Font Characteristics

4.4.1 Getting The Pixel Size Of A Named Font

The pixel size of a named font can be obtained by calling the Font method

    public static int getPixelSize(String name)

The name argument can be a font face name or a font family name or null.

If the named Font is scalable then the method will return zero.

It is an error if the named Font cannot be found and an IllegalArgumentException will be thrown

4.4.2 Getting The Style Of A Named Font

The style of a named font can be obtained by calling the Font method

    public static int getStyle(String name)

The name argument can be a font face name or a font family name or null.

It is an error if the named Font cannot be found and an IllegalArgumentException will be thrown

4.5 Deriving A Font Of A Specific Size From An Existing Font

A new Font of a specific pixel size can be derived from an existing Font using that Font’s

    public Font deriveFont(int pixelSize)

method.

It is an error if the pixelSize is less than zero, or if the Font is not scalable, and an IllegalArgumentException will be thrown.

4.6 Deriving A Font Of A Specific Style And Size From An Existing Font

A new Font of a specific style and pixel size can be derived from an existing Font using that Font’s

    public Font deriveFont(int style, int pixelSize)

method.

It is an error if the style argument does not specify a legal style and an IllegalArgumentException will be thrown.

It is an error if the pixelSize is less than zero, or if the Font is not scalable, and an IllegalArgumentException will be thrown.

4.7 Getting The Family Name Of A Font

The family name of a Font can be obtained by calling its

    public String getFamily()

method.

4.8 Additional Font Metrics

The following additional metrics can be obtained from a Font

• ascent
• descent
• leading
• max ascent
• max descent
• pixel size

4.9 Miscellaneous Constants

There are two new constants defined in the Font class

• public static final int FONT_IDLE_TEXT

• public static final int FONT_IDLE_HIGHLIGHTED_TEXT

Note

• It is not clear what the constants are for. In each case the documentation says

  … can be is [sic] used with getFont to retrieve the appropriate Font ...

  where getFont links to the getFont(String,int,int) method.

  As it is an int it is presumably intended to be used as a style, but the method documentation for the style argument
  reads

  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.[Emphasis added]

  which specifically prevents their use.

• Update

  The explanation turns out to be quite simple. The documentation links to the wrong version of the getFont() method. It should actually link to the

          public static int getFont(int fontSpecifier)
  

  version whose documentation explicitly mentions both constants

---

Copyright (c) 2009 By Simon Lewis. All Rights Reserved.

About these ads