org.axsl.fontR
Interface FontUse

All Superinterfaces:

java.lang.Comparable

public interface FontUse

extends java.lang.Comparable

The FontUse interface exposes a font resource to the client application. It encapsulates a Font as it is used by a specific FontConsumer, for a specific Encoding and for a specific font family. It is possible for a FontConsumer to use the same Font instance in more than one way, due to more than one encoding or the font being configured in more than one font family.

Method Summary

int	encodeCharacter(int codePoint) Retrieve the font glyph index for a specified Unicode character.
Encoding	getEncoding() Get the Encoding scheme that is used to encode characters in this Font.
Font	getFont() Return the parent Font.
FontConsumer	getFontConsumer() Returns the FontConsumer for whom this FontUse exists.
FontOutput	getFontOutput(java.lang.String mimeType) Provide a FontOutput implementation for a given mime type.
java.lang.String	getPostscriptName() Returns the PostScript name of the font.
boolean	glyphAvailable(int codePoint) Reports whether a glyph can be encoded for a given character.
FontUse	nextBolderFont() Returns the next bolder font in this font's font-family, if one exists, or null if this is the boldest font.
short	nextBolderWeight() Returns the weight of the next bolder font in this font's font-family, if one exists.
FontUse	nextLighterFont() Returns the next lighter font in this font's font-family, if one exists, or null if this is the lightest font.
short	nextLighterWeight() Returns the weight of the next lighter font in this font's font-family, if one exists.
void	registerCharsUsed(java.lang.CharSequence charSequence) Convenience method that provides the equivalent of running registerCharUsed(int) for each char in a given String, StringBuffer or other CharSequence.
void	registerCharUsed(int codePoint) Records the fact that a FontConsumer is using a particular character.
float	simulateBackslant() If this font has been configured to simulate the "backslant" font-style, return the percentage of 90 degrees that should be used to compute the angle at which the characters should be skewed to obtain that effect.
float	simulateCondensed() If this font has been configured to simulate the "condensed" font-stretch, return the percentage that should be applied to the width of characters in this font to achieve that effect.
float	simulateExpanded() If this font has been configured to simulate the "expanded" font-stretch, return the percentage that should be applied to the width of characters in this font to achieve that effect.
float	simulateExtraCondensed() If this font has been configured to simulate the "extra-condensed" font-stretch, return the percentage that should be applied to the width of characters in this font to achieve that effect.
float	simulateExtraExpanded() If this font has been configured to simulate the "extra-expanded" font-stretch, return the percentage that should be applied to the width of characters in this font to achieve that effect.
float	simulateOblique() If this font has been configured to simulate the "oblique" font-style, return the percentage of 90 degrees that should be used to compute the angle at which the characters should be skewed to obtain that effect.
float	simulateSemiCondensed() If this font has been configured to simulate the "semi-condensed" font-stretch, return the percentage that should be applied to the width of characters in this font to achieve that effect.
float	simulateSemiExpanded() If this font has been configured to simulate the "semi-expanded" font-stretch, return the percentage that should be applied to the width of characters in this font to achieve that effect.
float	simulateUltraCondensed() If this font has been configured to simulate the "ultra-condensed" font-stretch, return the percentage that should be applied to the width of characters in this font to achieve that effect.
float	simulateUltraExpanded() If this font has been configured to simulate the "ultra-expanded" font-stretch, return the percentage that should be applied to the width of characters in this font to achieve that effect.
int	smallCapsSize(int fontSize) Computes the size, in millipoints, which should be used for the intrinsically lowercase characters in this font.
int	unavailableChar(java.lang.CharSequence chars, int beginIndex) Examines each character in a specified portion of a String or other CharSequence to determine whether a glyph can be encoded for that character.
int[]	unavailableChars(java.lang.CharSequence chars, int beginIndex) Examines each character in a specified portion of a String or other CharSequence to determine whether a glyph can be encoded for that character.
boolean	wasUsed() Indicates whether any characters registered use.

Methods inherited from interface java.lang.Comparable

compareTo

Method Detail

getFont

public Font getFont()

Return the parent Font.

Returns:

The parent Font.

encodeCharacter

public int encodeCharacter(int codePoint)

Retrieve the font glyph index for a specified Unicode character. Note that if the font is subsetted, the glyph index returned is that for the subsetted font, not for the original font. This is needed to properly build and retrieve font subset information and to ensure that the right encoding is used.

Design Note: This method returns an int (instead of a char) because it is conceivable that some fonts will need more than 16 bits to express their glyph indexes.

Parameters:

codePoint - The Unicode character for which the glyph index is desired.

Returns:

The glyph index for codePoint. This is normally the code that is written to an output document (such as PDF or PostScript).

getEncoding

public Encoding getEncoding()

Get the Encoding scheme that is used to encode characters in this Font. Note that this may be different from the font's internal encoding.

Returns:

The Encoding scheme that is used to encode characters in this Font.

See Also:

Font.getInternalEncoding()

nextBolderWeight

public short nextBolderWeight()

Returns the weight of the next bolder font in this font's font-family, if one exists. If no bolder font exists, returns the next bolder numerical weight value. If the weight of this Font is already the boldest, Font.FONT_WEIGHT_900, then returns that value.

Returns:

One of 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

nextLighterWeight

public short nextLighterWeight()

Returns the weight of the next lighter font in this font's font-family, if one exists. If no lighter font exists, returns the next lighter numerical weight value. If the weight of this Font is already the lightest, Font.FONT_WEIGHT_100, then returns that value.

Returns:

One of 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

nextBolderFont

public FontUse nextBolderFont()

Returns the next bolder font in this font's font-family, if one exists, or null if this is the boldest font.

Returns:

Either the next bolder font, or null if there is no such font.

nextLighterFont

public FontUse nextLighterFont()

Returns the next lighter font in this font's font-family, if one exists, or null if this is the lightest font.

Returns:

Either the next lighter font, or null if there is no such font.

unavailableChar

public int unavailableChar(java.lang.CharSequence chars,
                           int beginIndex)

Examines each character in a specified portion of a String or other CharSequence to determine whether a glyph can be encoded for that character. If a glyph cannot be encoded, either because the Font does not have a glyph for the character, or because the FontUse encoding cannot encode the character, the character's index in the CharSequence is returned.

Parameters:

chars - The String, StringBuffer or other CharSequence to be examined.

beginIndex - The first index in chars to be examined.

Returns:

The first index into chars at or after beginIndex which contains an unencodable character. If all characters in chars can be encoded, -1 is returned.

unavailableChars

public int[] unavailableChars(java.lang.CharSequence chars,
                              int beginIndex)

Examines each character in a specified portion of a String or other CharSequence to determine whether a glyph can be encoded for that character. If a glyph cannot be encoded, either because the Font does not have a glyph for the character, or because the FontUse encoding cannot encode the character, it is included in an array of indexes that is returned.

Parameters:

chars - The String, StringBuffer or other CharSequence to be examined.

beginIndex - The first index in chars to be examined.

Returns:

An int array, each element of which contains the index to one char in chars for which no glyph can be encoded. If all characters in chars can be encoded, null is returned.

glyphAvailable

public boolean glyphAvailable(int codePoint)

Reports whether a glyph can be encoded for a given character.

Note that, even if the Font has a glyph for the character, this method will return false if the character cannot be encoded with this FontUse's encoding.

Parameters:

codePoint - The Unicode character to be tested.

Returns:

True iff a glyph can be encoded for this character.

smallCapsSize

public int smallCapsSize(int fontSize)

Computes the size, in millipoints, which should be used for the intrinsically lowercase characters in this font. If the font has true small-caps glyphs or is unable to simulate small-caps, the value returned will be the same as the value passed. In other words, no scaling is implied. Only if the font is capable of simulating small-caps will the value returned be different from the value passed.

Not all font-families have a small-caps variant, but small-caps can be simulated by the client application. To do so, 1) convert all text to uppercase characters, and 2) switch back and forth between a larger font size (for characters originally in uppercase) and a smaller font size (for characters originally in lowercase). If the requested font size is 12 points, and the lowercase characters should be scaled at 80%, then the font size to use for the lowercase characters is 9.6 points.

Note that the simulation of small-caps is done entirely outside of the font system. As far as the font system is concerned, the same font is being used regardless of whether it is being used at the size for uppercase characters or the size for lowercase characters. All that is being reported in this method is the computation of what has been configured for the font.

Parameters:

fontSize - The size, in millipoints, of the font at normal size. In other words, the size that will be used to create the uppercase glyphs.

Returns:

The size, in millipoints, that should be used for creating the instrinsically lowercase glyphs in this font. For a font that is capable of simulating small-caps, this value will be scaled to a percentage configured for the font.

simulateOblique

public float simulateOblique()

If this font has been configured to simulate the "oblique" font-style, return the percentage of 90 degrees that should be used to compute the angle at which the characters should be skewed to obtain that effect. A positive value skews the character clockwise, and a negative value skews the character counter-clockwise. Presumably values returned should be positive.

Returns:

The percentage that characters from this font should be skewed when the "oblique" font-style is requested, or zero if the font has not been configured to simulate oblique.

simulateBackslant

public float simulateBackslant()

If this font has been configured to simulate the "backslant" font-style, return the percentage of 90 degrees that should be used to compute the angle at which the characters should be skewed to obtain that effect. A positive value skews the character clockwise, and a negative value skews the character counter-clockwise. Presumably values returned should be negative.

Returns:

The percentage that characters from this font should be skewed when the "backslant" font-style is requested, or zero if the font has not been configured to simulate backslant.

simulateUltraCondensed

public float simulateUltraCondensed()

If this font has been configured to simulate the "ultra-condensed" font-stretch, return the percentage that should be applied to the width of characters in this font to achieve that effect. Values over 100% will result in wider characters, and a values less than 100% will result in narrower characters. Presumably values returned should be less than 100%.

Returns:

The percentage that should be applied to the width of characters from this font when the "ultra-condensed" font-stretch is requested, or 100% if the font has not been configured to simulate ultra-condensed.

simulateExtraCondensed

public float simulateExtraCondensed()

If this font has been configured to simulate the "extra-condensed" font-stretch, return the percentage that should be applied to the width of characters in this font to achieve that effect. Values over 100% will result in wider characters, and a values less than 100% will result in narrower characters. Presumably values returned should be less than 100%.

Returns:

The percentage that should be applied to the width of characters from this font when the "extra-condensed" font-stretch is requested, or 100% if the font has not been configured to simulate extra-condensed.

simulateCondensed

public float simulateCondensed()

If this font has been configured to simulate the "condensed" font-stretch, return the percentage that should be applied to the width of characters in this font to achieve that effect. Values over 100% will result in wider characters, and a values less than 100% will result in narrower characters. Presumably values returned should be less than 100%.

Returns:

The percentage that should be applied to the width of characters from this font when the "condensed" font-stretch is requested, or 100% if the font has not been configured to simulate condensed.

simulateSemiCondensed

public float simulateSemiCondensed()

If this font has been configured to simulate the "semi-condensed" font-stretch, return the percentage that should be applied to the width of characters in this font to achieve that effect. Values over 100% will result in wider characters, and a values less than 100% will result in narrower characters. Presumably values returned should be less than 100%.

Returns:

The percentage that should be applied to the width of characters from this font when the "semi-condensed" font-stretch is requested, or 100% if the font has not been configured to simulate semi-condensed.

simulateSemiExpanded

public float simulateSemiExpanded()

If this font has been configured to simulate the "semi-expanded" font-stretch, return the percentage that should be applied to the width of characters in this font to achieve that effect. Values over 100% will result in wider characters, and a values less than 100% will result in narrower characters. Presumably values returned should be greater than 100%.

Returns:

The percentage that should be applied to the width of characters from this font when the "semi-expanded" font-stretch is requested, or 100% if the font has not been configured to simulate semi-expanded.

simulateExpanded

public float simulateExpanded()

If this font has been configured to simulate the "expanded" font-stretch, return the percentage that should be applied to the width of characters in this font to achieve that effect. Values over 100% will result in wider characters, and a values less than 100% will result in narrower characters. Presumably values returned should be greater than 100%.

Returns:

The percentage that should be applied to the width of characters from this font when the "expanded" font-stretch is requested, or 100% if the font has not been configured to simulate expanded.

simulateExtraExpanded

public float simulateExtraExpanded()

If this font has been configured to simulate the "extra-expanded" font-stretch, return the percentage that should be applied to the width of characters in this font to achieve that effect. Values over 100% will result in wider characters, and a values less than 100% will result in narrower characters. Presumably values returned should be greater than 100%.

Returns:

The percentage that should be applied to the width of characters from this font when the "extra-expanded" font-stretch is requested, or 100% if the font has not been configured to simulate extra-expanded.

simulateUltraExpanded

public float simulateUltraExpanded()

If this font has been configured to simulate the "ultra-expanded" font-stretch, return the percentage that should be applied to the width of characters in this font to achieve that effect. Values over 100% will result in wider characters, and a values less than 100% will result in narrower characters. Presumably values returned should be greater than 100%.

Returns:

The percentage that should be applied to the width of characters from this font when the "ultra-expanded" font-stretch is requested, or 100% if the font has not been configured to simulate ultra-expanded.

getPostscriptName

public java.lang.String getPostscriptName()

Returns the PostScript name of the font. If this FontUse uses the Font's internal encoding, this name should be the same as the Font's PostScript name. If not, this name should be a combination of the Font's PostScript name and the name of the encoding.

Returns:

The PostScript name of the font.

getFontConsumer

public FontConsumer getFontConsumer()

Returns the FontConsumer for whom this FontUse exists.

Returns:

The FontConsumer instance attached to this FontUse.

registerCharUsed

public void registerCharUsed(int codePoint)

Records the fact that a FontConsumer is using a particular character. This is important for subsetting.

Parameters:

codePoint - The Unicode character to be registered.

registerCharsUsed

public void registerCharsUsed(java.lang.CharSequence charSequence)

Convenience method that provides the equivalent of running registerCharUsed(int) for each char in a given String, StringBuffer or other CharSequence.

Parameters:

charSequence - The CharSequence whose contents should be registered.

getFontOutput

public FontOutput getFontOutput(java.lang.String mimeType)

Provide a FontOutput implementation for a given mime type.

Parameters:

mimeType - The mime type for which the FontOutput instance should be obtained.

Returns:

A FontOutput implementation, or null if the mimeType is not registered.

See Also:

for details on registering {@link FontOutputFactory} instances.

wasUsed

public boolean wasUsed()

Indicates whether any characters registered use. Character use is registered at registerCharUsed(int) and registerCharsUsed(CharSequence).

Returns:

True if any characters were actually registered as used.