org.axsl.fontR
Interface FontConsumer

public interface FontConsumer

FontConsumer provides many of the font-related services that a client application may require, such as font resolution (obtaining a FontUse instance to use), and getting a collection of Font and FontUse instances actually used.

A separate FontConsumer implementation should be obtained for each document or other item that uses fonts. FontConsumer keeps track of which fonts and glyphs have been used by each consumer. This provides the following benefits:

• Subsetting information can be kept separate.
• Multiple documents can safely be handled by the same FontServer implementation.

Field Summary

static byte	FONT_SOURCE_FREE_STANDING Free standing fonts are those fonts which are available to the application through means other than the operating system.
static byte	FONT_SOURCE_SYSTEM System fonts are those fonts which are available to the application through the operating system.

Method Summary

Font[]	getUsedFonts() Returns an array of the Font instances that have been used by this FontConsumer.
FontUse[]	getUsedFontUses() Returns an array of the FontUse instances that have been used by this FontConsumer.
void	optimizeFonts() Optimizes the fonts used by this FontConsumer.
FontUse	selectFontCSS(java.lang.String[] familyList, int style, int weight, int variant, int stretch, int size, int codePoint) The same as selectFontXSL(int, java.lang.String[], int, int, int, int, int, int), except that the algorithm specified by CSS 2.1 is used instead.
FontUse	selectFontXSL(int selectionStrategy, java.lang.String[] familyList, int style, int weight, int variant, int stretch, int size, int codePoint) Accepts the client's description of the desired font, and returns the best-fitting Font found, using the algorithm specified by the XSL-FO 1.1 Standard.
void	setFontSources(int[] fontSources) Sets the font sources that can be selected for this FontConsumer.

Field Detail

FONT_SOURCE_FREE_STANDING

public static final byte FONT_SOURCE_FREE_STANDING

Free standing fonts are those fonts which are available to the application through means other than the operating system.

See Also:

Constant Field Values

FONT_SOURCE_SYSTEM

public static final byte FONT_SOURCE_SYSTEM

System fonts are those fonts which are available to the application through the operating system.

See Also:

Constant Field Values

Method Detail

selectFontXSL

public FontUse selectFontXSL(int selectionStrategy,
                             java.lang.String[] familyList,
                             int style,
                             int weight,
                             int variant,
                             int stretch,
                             int size,
                             int codePoint)
                      throws FontException

Accepts the client's description of the desired font, and returns the best-fitting Font found, using the algorithm specified by the XSL-FO 1.1 Standard.

Parameters:

selectionStrategy - One of Font.FONT_SELECTION_CBC (for "character-by-character" selection) or Font.FONT_SELECTION_AUTO (for "auto" selection").

familyList - An array of possible font family names from which to choose the font. The most desirable font-family name is listed first, then the next most desirable, etc. Elements should not contain leading or trailing quotation marks or spaces. Client applications may use FontUtility.foFontFamily(String) to convert String input into the value expected here.

style - The style of the font desired. Valid values are Font.FONT_STYLE_NORMAL, Font.FONT_STYLE_ITALIC, Font.FONT_STYLE_OBLIQUE, and Font.FONT_STYLE_BACKSLANT. Client applications may use FontUtility.foFontStyle(String, boolean) to convert String input into the value expected here.

weight - The weight of the font desired. Valid values are Font.FONT_WEIGHT_100, Font.FONT_WEIGHT_200, Font.FONT_WEIGHT_300, Font.FONT_WEIGHT_400, Font.FONT_WEIGHT_500, Font.FONT_WEIGHT_600, Font.FONT_WEIGHT_700, Font.FONT_WEIGHT_800, Font.FONT_WEIGHT_900, Font.FONT_WEIGHT_NORMAL, and Font.FONT_WEIGHT_BOLD. Client applications may use FontUtility.foFontWeight(String, boolean) to convert String input into the value expected here.

variant - The variant (normal or small-caps) of the font desired. Valid values are Font.FONT_VARIANT_NORMAL and Font.FONT_VARIANT_SMALL_CAPS. Client applications may use FontUtility.foFontVariant(String, boolean) to convert String input into the value expected here.

stretch - The stretch (normal, condensed, expanded, etc.) of the font desired. Valid values Font.FONT_STRETCH_ULTRA_CONDENSED, Font.FONT_STRETCH_EXTRA_CONDENSED, Font.FONT_STRETCH_CONDENSED, Font.FONT_STRETCH_SEMI_CONDENSED, Font.FONT_STRETCH_NORMAL, Font.FONT_STRETCH_SEMI_EXPANDED, Font.FONT_STRETCH_EXPANDED, Font.FONT_STRETCH_EXTRA_EXPANDED, Font.FONT_STRETCH_ULTRA_EXPANDED. Client applications may use FontUtility.foFontStretch(String, boolean) to convert String input into the value expected here.

size - The size (in millipoints) of the font. This is only meaningful for bitmapped fonts.

codePoint - The first character to be painted using the selected FontUse. This allows the selection process to avoid selecting a FontUse that cannot even paint the first character.

Returns:

The best-fitting FontUse instance associated with the descriptive input.

Throws:

FontException - if there is no matching font.

See Also:

selectFontCSS(java.lang.String[], int, int, int, int, int, int)

selectFontCSS

public FontUse selectFontCSS(java.lang.String[] familyList,
                             int style,
                             int weight,
                             int variant,
                             int stretch,
                             int size,
                             int codePoint)
                      throws FontException

The same as selectFontXSL(int, java.lang.String[], int, int, int, int, int, int), except that the algorithm specified by CSS 2.1 is used instead. Note also that CSS has no concept of a font-selection-strategy as XSL-FO does.

Parameters:

familyList - See selectFontXSL(int, java.lang.String[], int, int, int, int, int, int). Client applications may use FontUtility.cssFontFamily(String) to convert String input into the value expected here.

style - See selectFontXSL(int, java.lang.String[], int, int, int, int, int, int). Client applications may use FontUtility.cssFontStyle(String, boolean) to convert String input into the value expected here.

weight - See selectFontXSL(int, java.lang.String[], int, int, int, int, int, int). Client applications may use FontUtility.cssFontWeight(String, boolean) to convert String input into the value expected here.

variant - See selectFontXSL(int, java.lang.String[], int, int, int, int, int, int). Client applications may use FontUtility.cssFontVariant(String, boolean) to convert String input into the value expected here.

stretch - See selectFontXSL(int, java.lang.String[], int, int, int, int, int, int). Client applications may use FontUtility.cssFontStretch(String, boolean) to convert String input into the value expected here.

size - The size (in millipoints) of the font. This is only meaningful for bitmapped fonts.

codePoint - The first character to be painted using the selected FontUse. This allows the selection process to avoid selecting a FontUse that cannot even paint the first character.

Returns:

The best-fitting FontUse instance associated with the descriptive input.

Throws:

FontException - if there is no matching font.

See Also:

selectFontXSL(int, java.lang.String[], int, int, int, int, int, int)

getUsedFonts

public Font[] getUsedFonts()

Returns an array of the Font instances that have been used by this FontConsumer.

Returns:

The array of Font instances used by this FontConsumer.

getUsedFontUses

public FontUse[] getUsedFontUses()

Returns an array of the FontUse instances that have been used by this FontConsumer.

Returns:

The array of FontUse instances used by this FontConsumer.

optimizeFonts

public void optimizeFonts()

Optimizes the fonts used by this FontConsumer. This is only useful if two passes are made at the document contents, one before running this method, the other after doing so. To be effective, the fonts must be selected and the characters registered identically between the two passes. The first pass tells the system what fonts and characters will be used. Then running this method allows the system to take the "big picture" view of the document contents, and optimize things like encodings and character sets before actually processing the document contents.

Note that implementations are free to make this method a no-op, that is to do nothing at all. Even if something is done, there is no guarantee that it is worth the extra cost of processing the document twice. Consult implementation documentation for details.

Caveat: The timing of when this process should be run is very critical. It should only be run after all glyph indices that are used by the FontConsumer have been registered. It should also only be run before any glyph indices have been written to actual document output. If the client runs the registration and writing tasks concurrently, it should not use this method, as doing so will corrupt the logical connection between the glyph indices used to embed the font and those used to write the document contents.

setFontSources

public void setFontSources(int[] fontSources)

Sets the font sources that can be selected for this FontConsumer. Please note that implementations are not required to support either free-standing or system fonts, although they should presumably support at least one. This method is provided for implementations that want to use this information during font selection, but implementations are not required to do anything with the values set here.

Parameters:

fontSources - The array of valid font sources that can be used by this consumer. Valid array values are FONT_SOURCE_FREE_STANDING and FONT_SOURCE_SYSTEM. The order of the array signifies the order of preference for selection purposes. For example, if both system fonts and free-standing fonts can be used, but free-standing fonts are preferred, the array should contain { FONT_SOURCE_FREE_STANDING, FONT_SOURCE_SYSTEM };