org.axsl.font
Interface FontUse

public interface FontUse

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 Unicode code point.
FontUse	nextBolderFont() Returns the next bolder font in this font's font-family, if one exists, or null if this is the boldest font.
Font.Weight	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.
Font.Weight	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.

Method Detail

getFont

Font getFont()

Return the parent Font.

Returns:

The parent Font.

encodeCharacter

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

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

Font.Weight 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.Weight.BLACK, then returns that value.

Returns:

One of Font.Weight.EXTREMELY_LIGHT, Font.Weight.VERY_LIGHT, Font.Weight.LIGHT, Font.Weight.NORMAL, Font.Weight.DARK, Font.Weight.SEMI_BOLD, Font.Weight.BOLD, Font.Weight.EXTRA_BOLD, Font.Weight.BLACK

nextLighterWeight

Font.Weight 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.Weight.EXTREMELY_LIGHT, then returns that value.

Returns:

One of Font.Weight.EXTREMELY_LIGHT, Font.Weight.VERY_LIGHT, Font.Weight.LIGHT, Font.Weight.NORMAL, Font.Weight.DARK, Font.Weight.SEMI_BOLD, Font.Weight.BOLD, Font.Weight.EXTRA_BOLD, Font.Weight.BLACK

nextBolderFont

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

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

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. Unprintable code points for spacing, breaking, and layout control are treated by all fonts as "available".

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.

See Also:

unavailableChars(CharSequence, int), glyphAvailable(int)

unavailableChars

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, its index is included in an array of indexes that is returned. Unprintable code points for spacing, breaking, and layout control are treated by all fonts as "available".

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.

See Also:

unavailableChar(CharSequence, int), glyphAvailable(int)

glyphAvailable

boolean glyphAvailable(int codePoint)

Reports whether a glyph can be encoded for a given Unicode code point.

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. Unprintable code points for spacing, breaking, and layout control are treated by all fonts as "available".

Parameters:

codePoint - The Unicode character to be tested.

Returns:

True iff a glyph can be encoded for this character.

See Also:

unavailableChar(CharSequence, int), unavailableChars(CharSequence, int)

smallCapsSize

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

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

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

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

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

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

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

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

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

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

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

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

FontConsumer getFontConsumer()

Returns the FontConsumer for whom this FontUse exists.

Returns:

The FontConsumer instance attached to this FontUse.

registerCharUsed

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

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

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

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.