FontUse (aXSL API)

```
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

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`boolean`	`canMakeFontOutput(java.lang.String mimeType)` Indicates whether this FontUse instance is capable of creating a `FontOutput` instance for a given mime type.
`IntSequence`	`encode(java.lang.CharSequence chars, int offset, int length, FontOptions options, Orthography orthography)` Retrieve the array of font glyph indexes for a specified Word.
`int`	`encode(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`	`simulateSmallCaps()` If this font has been configured to simulate small-caps, returns the percentage of the font-size that will be used to compute the faux small-caps size.
`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.
`int`	`width(java.lang.CharSequence chars, int offset, int length, int fontSize, int letterSpacing, int wordSpacing, FontOptions options, Orthography orthography)` Calculates the width of a given character sequence, considering letter spacing, word spacing, and font options such as kerning and ligatures.
`int`	`width(int codePoint, int fontSize)` Returns the width of a Unicode character for this font, at a specified point size.

- Method Detail
  - getFont
```
Font getFont()
```
    Return the parent Font.
    
    Returns:
    
    The parent Font.
  - getFontConsumer
```
FontConsumer getFontConsumer()
```
    Returns the FontConsumer for whom this FontUse exists.
    
    Returns:
    
    The FontConsumer instance attached to this FontUse.
  - 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()
  - encode
```
int encode(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).
  - encode
```
IntSequence encode(java.lang.CharSequence chars,
                   int offset,
                   int length,
                   FontOptions options,
                   Orthography orthography)
```
    Retrieve the array of font glyph indexes for a specified Word. Note that the results of this method may not be equal to the sum of the results of encode(int) because of possible font substitutions such as ligatures. 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 ints (instead of a chars) because it is conceivable that some fonts will need more than 16 bits to express their glyph indexes.
    
    Parameters:
    
    chars - The character sequence containing the characters that should be encoded.
    
    offset - The zero-based index into chars that is the start of what should be encoded.
    
    length - The number of chars in chars that should be encoded. Implementations should assume that each word will be hyphenated no more than one time, i.e that the word will span, at most, two lines. Therefore, this index should always be zero or one. For the first option (index 0), the index should always be zero, as there will always be only one segment for that option.
    
    options - The font options, such as ligatures and small-caps that should be used when computing the glyphs for this word.
    
    orthography - The orthography that should be used when applying font features like subsitutions.
    
    Returns:
    
    The glyph indexes that should be used to encode the given segment (group of syllables) in a given option (possible hyphenation break) for a given word using this font. This is normally the code that is written to an output document (such as PDF or PostScript).
  - 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)
  - width
```
int width(int codePoint,
          int fontSize)
```
    Returns the width of a Unicode character for this font, at a specified point size.
    
    Parameters:
    
    codePoint - The Unicode character for which the width should be returned.
    
    fontSize - The size, in millipoints, of the font.
    
    Returns:
    
    The width, in millipoints, of the glyph in this font for codePoint, or Integer.MIN_VALUE if such a glyph is not found.
  - width
```
int width(java.lang.CharSequence chars,
          int offset,
          int length,
          int fontSize,
          int letterSpacing,
          int wordSpacing,
          FontOptions options,
          Orthography orthography)
```
    Calculates the width of a given character sequence, considering letter spacing, word spacing, and font options such as kerning and ligatures.
    
    Parameters:
    
    chars - The character sequence whose width should be computed.
    
    offset - The zero-based index into chars that is the start of what should be computed.
    
    length - The number of chars in chars that should be computed.
    
    fontSize - The size, in millipoints, of the font.
    
    letterSpacing - The size, in millipoints, of any letter-spacing.
    
    wordSpacing - The size, in millipoints, of any word-spacing.
    
    options - Options indicating how the font should use its features.
    
    orthography - The orthography that should be used when applying locale-sensitive font features.
    
    Returns:
    
    The width, in millipoints, of chars. Letter-spacing and kerning are added between characters in chars, but are not added either before or after. (Adding letter-spacing or kerning before or after would require making assumptions about the context of chars, including whether it is at the beginning or end of the line, what fonts surround it, etc.) Word-spacing is added only to space characters (0x20). Any other whitespace characters that the client applications wishes to have considered as word-spacing must first be normalized to 0x20. If there is no glyph for a character in chars, the width returned will be that of the "missing glyph".
  - 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.
  - simulateSmallCaps
```
float simulateSmallCaps()
```
    If this font has been configured to simulate small-caps, returns the percentage of the font-size that will be used to compute the faux small-caps size.
    
    Returns:
    
    The percentage that will be applied to the font-size to get the faux small-caps font-size. If the font has not been configured to simulate small-caps, returns FontServer.SMALL_CAP_SIMULATION_INVALID.
  - 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.
  - 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. If the mime type is not supported, an unchecked UnsupportedOperationException will be thrown. To avoid this, use canMakeFontOutput(String) to check the capability first.
    
    Parameters:
    
    mimeType - The mime type for which the FontOutput instance should be obtained.
    
    Returns:
    
    A FontOutput implementation for the requested mime type.
  - canMakeFontOutput
```
boolean canMakeFontOutput(java.lang.String mimeType)
```
    Indicates whether this FontUse instance is capable of creating a FontOutput instance for a given mime type.
    
    Parameters:
    
    mimeType - The mime type for which we are checking the capability.
    
    Returns:
    
    True iff this FontUse instance is able to create a FontOutput instance for the given mime type.
  - 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.

This documentation was created 2017-01-24 at 21:26 GMT by The aXSL Group and may be freely copied. See license for details.

Interface FontUse

Method Summary

Method Detail

getFont

getFontConsumer

getEncoding

encode

encode

unavailableChar

unavailableChars

glyphAvailable

width

width

nextBolderWeight

nextLighterWeight

nextBolderFont

nextLighterFont

simulateSmallCaps

smallCapsSize

simulateOblique

simulateBackslant

simulateUltraCondensed

simulateExtraCondensed

simulateCondensed

simulateSemiCondensed

simulateSemiExpanded

simulateExpanded

simulateExtraExpanded

simulateUltraExpanded

getPostscriptName

registerCharUsed

registerCharsUsed

getFontOutput

canMakeFontOutput

wasUsed