# UnicodeFont (Slick - The 2D Library)
Date: 2013-06-03

## org.newdawn.slick
Class UnicodeFont

    java.lang.Object
      org.newdawn.slick.UnicodeFont

All Implemented Interfaces:
  Font

    public class UnicodeFont

extends java.lang.Object
implements Font

A Slick bitmap font that can display unicode glyphs from a TrueTypeFont. For efficiency, glyphs are packed on to textures. Glyphs can be loaded to the textures on the fly, when they are first needed for display. However, it is best to load the glyphs that are known to be needed at startup.

Author:
  Nathan Sweet <misc@n4te.com>

Nested Class Summary
`static class` `UnicodeFont.DisplayList` A simple descriptor for display lists cached within this font

Constructor Summary
`UnicodeFont(java.awt.Font font)` Creates a new UnicodeFont.
`UnicodeFont(java.awt.Font font, HieroSettings settings)` Creates a new UnicodeFont.
`UnicodeFont(java.awt.Font font, int size, boolean bold, boolean italic)` Creates a new UnicodeFont.
`UnicodeFont(java.awt.Font font, java.lang.String hieroFileRef)` Creates a new UnicodeFont.
`UnicodeFont(java.lang.String ttfFileRef, HieroSettings settings)` Create a new unicode font based on a TTF file and a set of heiro configuration
`UnicodeFont(java.lang.String ttfFileRef, int size, boolean bold, boolean italic)` Create a new unicode font based on a TTF file alone
`UnicodeFont(java.lang.String ttfFileRef, java.lang.String hieroFileRef)` Create a new unicode font based on a TTF file

Method Summary
`void` `addAsciiGlyphs()` Queues the glyphs in the ASCII character set (codepoints 32 through 255) to be loaded.
`void` `addGlyphs(int startCodePoint, int endCodePoint)` Queues the glyphs in the specified codepoint range (inclusive) to be loaded.
`void` `addGlyphs(java.lang.String text)` Queues the glyphs in the specified text to be loaded.
`void` `addNeheGlyphs()` Queues the glyphs in the NEHE character set (codepoints 32 through 128) to be loaded.
`void` `clearGlyphs()` Clears all loaded and queued glyphs.
`void` `destroy()` Releases all resources used by this UnicodeFont.
`UnicodeFont.DisplayList` `drawDisplayList(float x, float y, java.lang.String text, Color color, int startIndex, int endIndex)` Identical to `drawString(float, float, String, Color, int, int)` but returns a DisplayList which provides access to the width and height of the text drawn.
`void` `drawString(float x, float y, java.lang.String text)` Draw a string to the screen
`void` `drawString(float x, float y, java.lang.String text, Color col)` Draw a string to the screen
`void` `drawString(float x, float y, java.lang.String text, Color color, int startIndex, int endIndex)` Draw part of a string to the screen.
`int` `getAscent()` Gets the distance from the baseline to the y drawing location.
`int` `getDescent()` Gets the distance from the baseline to the bottom of most alphanumeric characters with descenders.
`java.util.List` `getEffects()` Returns a list of `Effect`s that will be applied to the glyphs.
`java.awt.Font` `getFont()` Returns the TrueTypeFont for this UnicodeFont.
`java.lang.String` `getFontFile()` Returns the path to the TTF file for this UnicodeFont, or null.
`int` `getGlyphPageHeight()` Returns the height of the backing textures.
`java.util.List` `getGlyphPages()` Returns the GlyphPages for this UnicodeFont.
`int` `getGlyphPageWidth()` Returns the width of the backing textures.
`int` `getHeight(java.lang.String text)` Get the height of the given string
`int` `getLeading()` Gets the extra distance between the descent of one line of text to the ascent of the next.
`int` `getLineHeight()` Returns the distance from one line of text to the next.
`int` `getPaddingAdvanceX()` Gets the additional amount to offset glyphs on the x axis.
`int` `getPaddingAdvanceY()` Gets the additional amount to offset a line of text on the y axis.
`int` `getPaddingBottom()` Returns the padding below a glyph on the GlyphPage to allow for effects to be drawn.
`int` `getPaddingLeft()` Returns the padding to the left of a glyph on the GlyphPage to allow for effects to be drawn.
`int` `getPaddingRight()` Returns the padding to the right of a glyph on the GlyphPage to allow for effects to be drawn.
`int` `getPaddingTop()` Returns the padding above a glyph on the GlyphPage to allow for effects to be drawn.
`int` `getSpaceWidth()` Returns the width of the space character.
`int` `getWidth(java.lang.String text)` Get the width of the given string
`int` `getYOffset(java.lang.String text)` Returns the distance from the y drawing location to the top most pixel of the specified text.
`boolean` `isCaching()` Returns true if this UnicodeFont caches the glyph drawing instructions to improve performance.
`boolean` `loadGlyphs()` Loads all queued glyphs to the backing textures.
`boolean` `loadGlyphs(int maxGlyphsToLoad)` Loads up to the specified number of queued glyphs to the backing textures.
`void` `setDisplayListCaching(boolean displayListCaching)` Sets if this UnicodeFont caches the glyph drawing instructions to improve performance.
`void` `setGlyphPageHeight(int glyphPageHeight)` Sets the height of the backing textures.
`void` `setGlyphPageWidth(int glyphPageWidth)` Sets the width of the backing textures.
`void` `setPaddingAdvanceX(int paddingAdvanceX)` Sets the additional amount to offset glyphs on the x axis.
`void` `setPaddingAdvanceY(int paddingAdvanceY)` Sets the additional amount to offset a line of text on the y axis.
`void` `setPaddingBottom(int paddingBottom)` Sets the padding below a glyph on the GlyphPage to allow for effects to be drawn.
`void` `setPaddingLeft(int paddingLeft)` Sets the padding to the left of a glyph on the GlyphPage to allow for effects to be drawn.
`void` `setPaddingRight(int paddingRight)` Sets the padding to the right of a glyph on the GlyphPage to allow for effects to be drawn.
`void` `setPaddingTop(int paddingTop)` Sets the padding above a glyph on the GlyphPage to allow for effects to be drawn.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### UnicodeFont

    public UnicodeFont(java.lang.String ttfFileRef,
                       java.lang.String hieroFileRef)
                throws SlickException

  Create a new unicode font based on a TTF file

  Parameters:
    `ttfFileRef` - The file system or classpath location of the TrueTypeFont file.
    `hieroFileRef` - The file system or classpath location of the Hiero settings file.
  Throws:
    `SlickException` - if the UnicodeFont could not be initialized.

### UnicodeFont

    public UnicodeFont(java.lang.String ttfFileRef,
                       HieroSettings settings)
                throws SlickException

  Create a new unicode font based on a TTF file and a set of heiro configuration

  Parameters:
    `ttfFileRef` - The file system or classpath location of the TrueTypeFont file.
    `settings` - The settings configured via the Hiero tool
  Throws:
    `SlickException` - if the UnicodeFont could not be initialized.

### UnicodeFont

    public UnicodeFont(java.lang.String ttfFileRef,
                       int size,
                       boolean bold,
                       boolean italic)
                throws SlickException

  Create a new unicode font based on a TTF file alone

  Parameters:
    `ttfFileRef` - The file system or classpath location of the TrueTypeFont file.
    `size` - The point size of the font to generated
    `bold` - True if the font should be rendered in bold typeface
    `italic` - True if the font should be rendered in bold typeface
  Throws:
    `SlickException` - if the UnicodeFont could not be initialized.

### UnicodeFont

    public UnicodeFont(java.awt.Font font,
                       java.lang.String hieroFileRef)
                throws SlickException

  Creates a new UnicodeFont.

  Parameters:
    `font` - The AWT font to render
    `hieroFileRef` - The file system or classpath location of the Hiero settings file.
  Throws:
    `SlickException` - if the UnicodeFont could not be initialized.

### UnicodeFont

    public UnicodeFont(java.awt.Font font,
                       HieroSettings settings)

  Creates a new UnicodeFont.

  Parameters:
    `font` - The AWT font to render
    `settings` - The settings configured via the Hiero tool

### UnicodeFont

    public UnicodeFont(java.awt.Font font)

  Creates a new UnicodeFont.

  Parameters:
    `font` - The AWT font to render

### UnicodeFont

    public UnicodeFont(java.awt.Font font,
                       int size,
                       boolean bold,
                       boolean italic)

  Creates a new UnicodeFont.

  Parameters:
    `font` - The AWT font to render
    `size` - The point size of the font to generated
    `bold` - True if the font should be rendered in bold typeface
    `italic` - True if the font should be rendered in bold typeface

Method Detail

### addGlyphs

    public void addGlyphs(int startCodePoint,
                          int endCodePoint)

  Queues the glyphs in the specified codepoint range (inclusive) to be loaded. Note that the glyphs are not actually loaded until `loadGlyphs()` is called. Some characters like combining marks and non-spacing marks can only be rendered with the context of other glyphs. In this case, use `addGlyphs(String)`.

  Parameters:
    `startCodePoint` - The code point of the first glyph to add
    `endCodePoint` - The code point of the last glyph to add

### addGlyphs

    public void addGlyphs(java.lang.String text)

  Queues the glyphs in the specified text to be loaded. Note that the glyphs are not actually loaded until `loadGlyphs()` is called.

  Parameters:
    `text` - The text containing the glyphs to be added

### addAsciiGlyphs

    public void addAsciiGlyphs()

  Queues the glyphs in the ASCII character set (codepoints 32 through 255) to be loaded. Note that the glyphs are not actually loaded until `loadGlyphs()` is called.

### addNeheGlyphs

    public void addNeheGlyphs()

  Queues the glyphs in the NEHE character set (codepoints 32 through 128) to be loaded. Note that the glyphs are not actually loaded until `loadGlyphs()` is called.

### loadGlyphs

    public boolean loadGlyphs()
                       throws SlickException

  Loads all queued glyphs to the backing textures. Glyphs that are typically displayed together should be added and loaded at the same time so that they are stored on the same backing texture. This reduces the number of backing texture binds required to draw glyphs.

  Returns:
    True if the glyphs were loaded entirely
  Throws:
    `SlickException` - if the glyphs could not be loaded.

### loadGlyphs

    public boolean loadGlyphs(int maxGlyphsToLoad)
                       throws SlickException

  Loads up to the specified number of queued glyphs to the backing textures. This is typically called from the game loop to load glyphs on the fly that were requested for display but have not yet been loaded.

  Parameters:
    `maxGlyphsToLoad` - The maximum number of glyphs to be loaded this time
  Returns:
    True if the glyphs were loaded entirely
  Throws:
    `SlickException` - if the glyphs could not be loaded.

### clearGlyphs

    public void clearGlyphs()

  Clears all loaded and queued glyphs.

### destroy

    public void destroy()

  Releases all resources used by this UnicodeFont. This method should be called when this UnicodeFont instance is no longer needed.

### drawDisplayList

    public UnicodeFont.DisplayList drawDisplayList(float x,
                                                   float y,
                                                   java.lang.String text,
                                                   Color color,
                                                   int startIndex,
                                                   int endIndex)

  Identical to `drawString(float, float, String, Color, int, int)` but returns a DisplayList which provides access to the width and height of the text drawn.

  Parameters:
    `text` - The text to render
    `x` - The horizontal location to render at
    `y` - The vertical location to render at
    `color` - The colour to apply as a filter on the text
    `startIndex` - The start index into the string to start rendering at
    `endIndex` - The end index into the string to render to
  Returns:
    The reference to the display list that was drawn and potentiall ygenerated

### drawString

    public void drawString(float x,
                           float y,
                           java.lang.String text,
                           Color color,
                           int startIndex,
                           int endIndex)

  Description copied from interface: `Font`
  Draw part of a string to the screen. Note that this will still position the text as though it's part of the bigger string.

  Specified by:
    `drawString` in interface `Font`
  Parameters:
    `x` - The x location at which to draw the string
    `y` - The y location at which to draw the string
    `text` - The text to be displayed
    `color` - The colour to draw with
    `startIndex` - The index of the first character to draw
    `endIndex` - The index of the last character from the string to draw

### drawString

    public void drawString(float x,
                           float y,
                           java.lang.String text)

  Description copied from interface: `Font`
  Draw a string to the screen

  Specified by:
    `drawString` in interface `Font`
  Parameters:
    `x` - The x location at which to draw the string
    `y` - The y location at which to draw the string
    `text` - The text to be displayed

### drawString

    public void drawString(float x,
                           float y,
                           java.lang.String text,
                           Color col)

  Description copied from interface: `Font`
  Draw a string to the screen

  Specified by:
    `drawString` in interface `Font`
  Parameters:
    `x` - The x location at which to draw the string
    `y` - The y location at which to draw the string
    `text` - The text to be displayed
    `col` - The colour to draw with

### getSpaceWidth

    public int getSpaceWidth()

  Returns the width of the space character.

### getWidth

    public int getWidth(java.lang.String text)

  Description copied from interface: `Font`
  Get the width of the given string

  Specified by:
    `getWidth` in interface `Font`
  Parameters:
    `text` - The string to obtain the rendered with of
  Returns:
    The width of the given string
  See Also:
    `Font.getWidth(java.lang.String)`

### getHeight

    public int getHeight(java.lang.String text)

  Description copied from interface: `Font`
  Get the height of the given string

  Specified by:
    `getHeight` in interface `Font`
  Parameters:
    `text` - The string to obtain the rendered with of
  Returns:
    The width of the given string
  See Also:
    `Font.getHeight(java.lang.String)`

### getYOffset

    public int getYOffset(java.lang.String text)

  Returns the distance from the y drawing location to the top most pixel of the specified text.

  Parameters:
    `text` - The text to analyse
  Returns:
    The distance fro the y drawing location ot the top most pixel of the specified text

### getFont

    public java.awt.Font getFont()

  Returns the TrueTypeFont for this UnicodeFont.

  Returns:
    The AWT Font being rendered

### getPaddingTop

    public int getPaddingTop()

  Returns the padding above a glyph on the GlyphPage to allow for effects to be drawn.

  Returns:
    The padding at the top of the glyphs when drawn

### setPaddingTop

    public void setPaddingTop(int paddingTop)

  Sets the padding above a glyph on the GlyphPage to allow for effects to be drawn.

  Parameters:
    `paddingTop` - The padding at the top of the glyphs when drawn

### getPaddingLeft

    public int getPaddingLeft()

  Returns the padding to the left of a glyph on the GlyphPage to allow for effects to be drawn.

  Returns:
    The padding at the left of the glyphs when drawn

### setPaddingLeft

    public void setPaddingLeft(int paddingLeft)

  Sets the padding to the left of a glyph on the GlyphPage to allow for effects to be drawn.

  Parameters:
    `paddingLeft` - The padding at the left of the glyphs when drawn

### getPaddingBottom

    public int getPaddingBottom()

  Returns the padding below a glyph on the GlyphPage to allow for effects to be drawn.

  Returns:
    The padding at the bottom of the glyphs when drawn

### setPaddingBottom

    public void setPaddingBottom(int paddingBottom)

  Sets the padding below a glyph on the GlyphPage to allow for effects to be drawn.

  Parameters:
    `paddingBottom` - The padding at the bottom of the glyphs when drawn

### getPaddingRight

    public int getPaddingRight()

  Returns the padding to the right of a glyph on the GlyphPage to allow for effects to be drawn.

  Returns:
    The padding at the right of the glyphs when drawn

### setPaddingRight

    public void setPaddingRight(int paddingRight)

  Sets the padding to the right of a glyph on the GlyphPage to allow for effects to be drawn.

  Parameters:
    `paddingRight` - The padding at the right of the glyphs when drawn

### getPaddingAdvanceX

    public int getPaddingAdvanceX()

  Gets the additional amount to offset glyphs on the x axis.

  Returns:
    The padding applied for each horizontal advance (i.e. when a glyph is rendered)

### setPaddingAdvanceX

    public void setPaddingAdvanceX(int paddingAdvanceX)

  Sets the additional amount to offset glyphs on the x axis. This is typically set to a negative number when left or right padding is used so that glyphs are not spaced too far apart.

  Parameters:
    `paddingAdvanceX` - The padding applied for each horizontal advance (i.e. when a glyph is rendered)

### getPaddingAdvanceY

    public int getPaddingAdvanceY()

  Gets the additional amount to offset a line of text on the y axis.

  Returns:
    The padding applied for each vertical advance (i.e. when a glyph is rendered)

### setPaddingAdvanceY

    public void setPaddingAdvanceY(int paddingAdvanceY)

  Sets the additional amount to offset a line of text on the y axis. This is typically set to a negative number when top or bottom padding is used so that lines of text are not spaced too far apart.

  Parameters:
    `paddingAdvanceY` - The padding applied for each vertical advance (i.e. when a glyph is rendered)

### getLineHeight

    public int getLineHeight()

  Returns the distance from one line of text to the next. This is the sum of the descent, ascent, leading, padding top, padding bottom, and padding advance y. To change the line height, use `setPaddingAdvanceY(int)`.

  Specified by:
    `getLineHeight` in interface `Font`
  Returns:
    The maxium height of any line drawn by this font

### getAscent

    public int getAscent()

  Gets the distance from the baseline to the y drawing location.

  Returns:
    The ascent of this font

### getDescent

    public int getDescent()

  Gets the distance from the baseline to the bottom of most alphanumeric characters with descenders.

  Returns:
    The distance from the baseline to the bottom of the font

### getLeading

    public int getLeading()

  Gets the extra distance between the descent of one line of text to the ascent of the next.

  Returns:
    The leading edge of the font

### getGlyphPageWidth

    public int getGlyphPageWidth()

  Returns the width of the backing textures.

  Returns:
    The width of the glyph pages in this font

### setGlyphPageWidth

    public void setGlyphPageWidth(int glyphPageWidth)

  Sets the width of the backing textures. Default is 512.

  Parameters:
    `glyphPageWidth` - The width of the glyph pages in this font

### getGlyphPageHeight

    public int getGlyphPageHeight()

  Returns the height of the backing textures.

  Returns:
    The height of the glyph pages in this font

### setGlyphPageHeight

    public void setGlyphPageHeight(int glyphPageHeight)

  Sets the height of the backing textures. Default is 512.

  Parameters:
    `glyphPageHeight` - The width of the glyph pages in this font

### getGlyphPages

    public java.util.List getGlyphPages()

  Returns the GlyphPages for this UnicodeFont.

  Returns:
    The glyph pages that have been loaded into this font

### getEffects

    public java.util.List getEffects()

  Returns a list of `Effect`s that will be applied to the glyphs.

  Returns:
    The list of effects to be applied to the font

### isCaching

    public boolean isCaching()

  Returns true if this UnicodeFont caches the glyph drawing instructions to improve performance.

  Returns:
    True if caching is turned on

### setDisplayListCaching

    public void setDisplayListCaching(boolean displayListCaching)

  Sets if this UnicodeFont caches the glyph drawing instructions to improve performance. Default is true. Text rendering is very slow without display list caching.

  Parameters:
    `displayListCaching` - True if caching should be turned on

### getFontFile

    public java.lang.String getFontFile()

  Returns the path to the TTF file for this UnicodeFont, or null. If this UnicodeFont was created without specifying the TTF file, it will try to determine the path using Sun classes. If this fails, null is returned.

  Returns:
    The reference to the font file that the kerning was loaded from

Copyright © 2006 New Dawn Software. All Rights Reserved.