bb.gui
Class FontUtil

java.lang.Object
  extended by bb.gui.FontUtil

public class FontUtil
extends Object

This class provides miscellaneous static Font utility methods.

This class is multithread safe. All non-multithread safe fields are only accessed inside synchronized methods.

Author:
Brent Boyer

Nested Class Summary
static class FontUtil.FontRank
          The main purpose of this class is simply to record a Font and some associated rank of that Font.
static class FontUtil.UnitTest
          See the Overview page of the project's javadocs for a general description of this unit test class.
 
Field Summary
private static Font[] fonts
          Records all the Fonts available on this local system.
private static float fontSize_default
          The default Font point size.
 
Constructor Summary
private FontUtil()
          This sole private constructor suppresses the default (public) constructor, ensuring non-instantiability outside of this class.
 
Method Summary
static boolean canHandle(Component component, String s)
          Determines whether or not the component's Font is capable of displaying all of the chars of s that require a glyph.
static Font findBestFont(String s)
          Determines that Font in the local system which can display the highest percentage of s's chars.
static String findBestFontFamily(String... namesDesired)
          Returns the first element of namesDesired which is actually available on this system.
static double findDisplayableCharPercent(Font font, String s)
          Returns the percent of chars in the supplied String that can be displayed by the supplied Font.
static SortedSet<String> getFontFamilyNames()
          Determines the names of all the Font Families that are available on this system.
static Font[] getFonts()
          Returns all the Fonts available on this system.
static FontUtil.FontRank[] rankFonts(String s)
          Retrieves every Font in the local system by calling getFonts.
static boolean requiresGlyph(char c)
          Determines whether or not c requires a glyph from a Font or not.
static void resetFonts()
          Determines all the Fonts which are currently available on the running system and stores them in an internal field.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

fontSize_default

private static final float fontSize_default
The default Font point size.

See Also:
Constant Field Values

fonts

private static Font[] fonts
Records all the Fonts available on this local system. Is initialized/reset by resetFonts.

Contract: once initialized, has a length >= 20, and each Font's size will be fontSize_default. +++ need a sort guarantee

Constructor Detail

FontUtil

private FontUtil()
This sole private constructor suppresses the default (public) constructor, ensuring non-instantiability outside of this class.

Method Detail

getFontFamilyNames

public static SortedSet<String> getFontFamilyNames()
                                            throws IllegalStateException
Determines the names of all the Font Families that are available on this system.

Contract: the result has a size >= 5, because the JVM guarantees the presence of these logical fonts: Dialog, DialogInput, Monospaced, Serif, and SansSerif. It is sorted by the natural String ordering.

Throws:
IllegalStateException

getFonts

public static Font[] getFonts()
                       throws IllegalStateException
Returns all the Fonts available on this system.

The result reflects the state of this system as of the last call to resetFonts. If resetFonts has never been called, then this method will automaticly call it. So, resetFonts never needs to be explicitly called, unless Fonts are added/removed.

Contract: the result will have a length >= 20, and each Font's size will be fontSize_default; see resetFonts.

Throws:
IllegalStateException - if some problem in determining the Fonts is encountered

resetFonts

public static void resetFonts()
                       throws IllegalStateException
Determines all the Fonts which are currently available on the running system and stores them in an internal field.

Throws:
IllegalStateException - if some problem in determining the Fonts is encountered

canHandle

public static boolean canHandle(Component component,
                                String s)
                         throws IllegalArgumentException
Determines whether or not the component's Font is capable of displaying all of the chars of s that require a glyph.

This method is needed because the Font.canDisplayUpTo method does not exclude chars that are highly unlikely to have a glyph in any Font.

To see why this method is needed, suppose you want to determine if a JTextArea, say, is currently set to a Font that is capable of displaying some text that contains line returns. Here, you do not want the line returns to count in the Font determination because they will require no glyphs.

Throws:
IllegalArgumentException - if component == null; s == null

requiresGlyph

public static boolean requiresGlyph(char c)
Determines whether or not c requires a glyph from a Font or not. This method assumes that all chars which are not whitespace characters or control characters require glyphs.


findBestFontFamily

public static String findBestFontFamily(String... namesDesired)
                                 throws IllegalArgumentException
Returns the first element of namesDesired which is actually available on this system.

Throws:
IllegalArgumentException - if every element of namesDesired is unavailable on this machine; in order to avoid this, it is highly recommended that the user supply one of the 5 logical font family names that the JVM guarantees to be present (e.g. Serif, SansSerif, Monospaced, Dialog, or DialogInput)

findBestFont

public static Font findBestFont(String s)
                         throws IllegalArgumentException,
                                IllegalStateException
Determines that Font in the local system which can display the highest percentage of s's chars. In the event of ties (e.g. several Fonts can display 100% of s's chars), it returns that Font which was encountered first.

Contract: the result is never null, and will have a Font size of fontSize_default.

Throws:
IllegalArgumentException - if s == null
IllegalStateException - if GraphicsEnvironment.getLocalGraphicsEnvironment().getAllFonts().length < 20

rankFonts

public static FontUtil.FontRank[] rankFonts(String s)
                                     throws IllegalArgumentException,
                                            IllegalStateException
Retrieves every Font in the local system by calling getFonts. Determines the FontUtil.FontRank for each using this constructor. Returns these FontRanks as an array, sorted by FontRank's natural ordering.

Contract: see getFonts for guarantees on the Fonts in the result.

Throws:
IllegalArgumentException - if s == null
IllegalStateException - if GraphicsEnvironment.getLocalGraphicsEnvironment().getAllFonts().length < 20

findDisplayableCharPercent

public static double findDisplayableCharPercent(Font font,
                                                String s)
                                         throws IllegalArgumentException
Returns the percent of chars in the supplied String that can be displayed by the supplied Font.

Throws:
IllegalArgumentException - if font == null; s == null or s.length() == 0