Package arc.graphics.g2d

Class Font

java.lang.Object
arc.graphics.g2d.Font
All Implemented Interfaces:
Disposable
Direct Known Subclasses:
DistanceFieldFont
public class Font extends Object implements Disposable
Renders bitmap fonts. The font consists of 2 files: an image file or TextureRegion containing the glyphs and a file in the AngleCode BMFont text format that describes where each glyph is on the image.

Text is drawn using a Batch. Text can be cached in a FontCache for faster rendering of static text, which saves needing to compute the location of each glyph each frame.

* The texture for a BitmapFont loaded from a file is managed. dispose() must be called to free the texture when no longer needed. A BitmapFont loaded using a TextureRegion is managed if the region's texture is managed. Disposing the BitmapFont disposes the region's texture, which may not be desirable if the texture is still being used elsewhere.

The code was originally based on Matthias Mann's TWL BitmapFont class. Thanks for sharing, Matthias! :)

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Font.FontData
    Backing data for a Font.
    static class 
    Font.Glyph
    Represents a single character in a font page.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Font(Fi fontFile)
    Creates a BitmapFont from a BMFont file.
    Font(Fi fontFile, boolean flip)
    Creates a BitmapFont from a BMFont file.
    Font(Fi fontFile, Fi imageFile, boolean flip)
    Creates a BitmapFont from a BMFont file, using the specified image for glyphs.
    Font(Fi fontFile, Fi imageFile, boolean flip, boolean integer)
    Creates a BitmapFont from a BMFont file, using the specified image for glyphs.
    Font(Fi fontFile, TextureRegion region)
    Creates a BitmapFont with the glyphs relative to the specified region.
    Font(Fi fontFile, TextureRegion region, boolean flip)
    Creates a BitmapFont with the glyphs relative to the specified region.
    Font(Font.FontData data, TextureRegion region, boolean integer)
    Constructs a new BitmapFont from the given Font.FontData and TextureRegion.
    Font(Font.FontData data, Seq<TextureRegion> pageRegions, boolean integer)
    Constructs a new BitmapFont from the given Font.FontData and array of TextureRegion.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    dispose()
    Disposes the texture used by this BitmapFont's region IF this BitmapFont created the texture.
    void
    draw(GlyphLayout layout, float x, float y)
    Draws text at the specified position.
    GlyphLayout
    draw(CharSequence str, float x, float y)
    Draws text at the specified position.
    GlyphLayout
    draw(CharSequence str, float x, float y, float targetWidth, int halign, boolean wrap)
    Draws text at the specified position.
    GlyphLayout
    draw(CharSequence str, float x, float y, int halign)
     
    GlyphLayout
    draw(CharSequence str, float x, float y, int start, int end, float targetWidth, int halign, boolean wrap)
    Draws text at the specified position.
    GlyphLayout
    draw(CharSequence str, float x, float y, int start, int end, float targetWidth, int halign, boolean wrap, String truncate)
    Draws text at the specified position.
    GlyphLayout
    draw(CharSequence str, float x, float y, Color color, float scale, boolean integer, int halign)
     
    float
    getAscent()
    Returns the ascent, which is the distance from the cap height to the top of the tallest glyph.
    FontCache
    getCache()
    For expert usage -- returns the BitmapFontCache used by this font, for rendering to a sprite batch.
    float
    getCapHeight()
    Returns the cap height, which is the distance from the top of most uppercase characters to the baseline.
    Color
    getColor()
    Returns the color of text drawn with this font.
    Font.FontData
    getData()
    Gets the underlying Font.FontData for this BitmapFont.
    float
    getDescent()
    Returns the descent, which is the distance from the bottom of the glyph that extends the lowest to the baseline.
    float
    getLineHeight()
    Returns the line height, which is the distance from one line of text to the next.
    TextureRegion
    getRegion()
    Returns the first texture region.
    TextureRegion
    getRegion(int index)
    Returns the texture page at the given index.
    Seq<TextureRegion>
    getRegions()
    Returns the array of TextureRegions that represents each texture page of glyphs.
    float
    getScaleX()
     
    float
    getScaleY()
     
    float
    getSpaceXadvance()
    Returns the x-advance of the space character.
    float
    getXHeight()
    Returns the x-height, which is the distance from the top of most lowercase characters to the baseline.
    boolean
    isDisposed()
     
    boolean
    isFlipped()
    Returns true if this BitmapFont has been flipped for use with a y-down coordinate system.
    protected void
    load(Font.FontData data)
     
    FontCache
    newFontCache()
    Creates a new BitmapFontCache for this font.
    boolean
    ownsTexture()
     
    void
    setColor(float r, float g, float b, float a)
    A convenience method for setting the font color.
    void
    setColor(Color color)
    A convenience method for setting the font color.
    void
    setFixedWidthGlyphs(CharSequence glyphs)
    Makes the specified glyphs fixed width.
    void
    setOwnsTexture(boolean ownsTexture)
    Sets whether the font owns the texture.
    void
    setUseIntegerPositions(boolean integer)
    Specifies whether to use integer positions.
    String
    toString()
     
    boolean
    usesIntegerPositions()
    Checks whether this font uses integer positions for drawing.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • Font

      public Font(Fi fontFile, TextureRegion region)
      Creates a BitmapFont with the glyphs relative to the specified region. If the region is null, the glyph textures are loaded from the image file given in the font file. The dispose() method will not dispose the region's texture in this case!

      The font data is not flipped.

      Parameters:
      fontFile - the font definition file
      region - The texture region containing the glyphs. The glyphs must be relative to the lower left corner (ie, the region should not be flipped). If the region is null the glyph images are loaded from the image path in the font file.

    • Font

      public Font(Fi fontFile, TextureRegion region, boolean flip)
      Creates a BitmapFont with the glyphs relative to the specified region. If the region is null, the glyph textures are loaded from the image file given in the font file. The dispose() method will not dispose the region's texture in this case!
      Parameters:
      region - The texture region containing the glyphs. The glyphs must be relative to the lower left corner (ie, the region should not be flipped). If the region is null the glyph images are loaded from the image path in the font file.
      flip - If true, the glyphs will be flipped for use with a perspective where 0,0 is the upper left corner.

    • Font

      public Font(Fi fontFile)
      Creates a BitmapFont from a BMFont file. The image file name is read from the BMFont file and the image is loaded from the same directory. The font data is not flipped.

    • Font

      public Font(Fi fontFile, boolean flip)
      Creates a BitmapFont from a BMFont file. The image file name is read from the BMFont file and the image is loaded from the same directory.
      Parameters:
      flip - If true, the glyphs will be flipped for use with a perspective where 0,0 is the upper left corner.

    • Font

      public Font(Fi fontFile, Fi imageFile, boolean flip)
      Creates a BitmapFont from a BMFont file, using the specified image for glyphs. Any image specified in the BMFont file is ignored.
      Parameters:
      flip - If true, the glyphs will be flipped for use with a perspective where 0,0 is the upper left corner.

    • Font

      public Font(Fi fontFile, Fi imageFile, boolean flip, boolean integer)
      Creates a BitmapFont from a BMFont file, using the specified image for glyphs. Any image specified in the BMFont file is ignored.
      Parameters:
      flip - If true, the glyphs will be flipped for use with a perspective where 0,0 is the upper left corner.
      integer - If true, rendering positions will be at integer values to avoid filtering artifacts.

    • Font

      public Font(Font.FontData data, TextureRegion region, boolean integer)
      Constructs a new BitmapFont from the given Font.FontData and TextureRegion. If the TextureRegion is null, the image path(s) will be read from the BitmapFontData. The dispose() method will not dispose the texture of the region(s) if the region is != null.

      Passing a single TextureRegion assumes that your font only needs a single texture page. If you need to support multiple pages, either let the Font read the images themselves (by specifying null as the TextureRegion), or by specifying each page manually with the TextureRegion[] constructor.

      Parameters:
      integer - If true, rendering positions will be at integer values to avoid filtering artifacts.

    • Font

      public Font(Font.FontData data, Seq<TextureRegion> pageRegions, boolean integer)
      Constructs a new BitmapFont from the given Font.FontData and array of TextureRegion. If the TextureRegion is null or empty, the image path(s) will be read from the BitmapFontData. The dispose() method will not dispose the texture of the region(s) if the regions array is != null and not empty.
      Parameters:
      integer - If true, rendering positions will be at integer values to avoid filtering artifacts.

  • Method Details

    • load

      protected void load(Font.FontData data)

    • draw

      public GlyphLayout draw(CharSequence str, float x, float y)
      Draws text at the specified position.
      See Also:

    • draw

      public GlyphLayout draw(CharSequence str, float x, float y, Color color, float scale, boolean integer, int halign)

    • draw

      public GlyphLayout draw(CharSequence str, float x, float y, int halign)

    • draw

      public GlyphLayout draw(CharSequence str, float x, float y, float targetWidth, int halign, boolean wrap)
      Draws text at the specified position.
      See Also:

    • draw

      public GlyphLayout draw(CharSequence str, float x, float y, int start, int end, float targetWidth, int halign, boolean wrap)
      Draws text at the specified position.
      See Also:

    • draw

      public GlyphLayout draw(CharSequence str, float x, float y, int start, int end, float targetWidth, int halign, boolean wrap, String truncate)
      Draws text at the specified position.
      See Also:

    • draw

      public void draw(GlyphLayout layout, float x, float y)
      Draws text at the specified position.
      See Also:

    • getColor

      public Color getColor()
      Returns the color of text drawn with this font.

    • setColor

      public void setColor(Color color)
      A convenience method for setting the font color. The color can also be set by modifying getColor().

    • setColor

      public void setColor(float r, float g, float b, float a)
      A convenience method for setting the font color. The color can also be set by modifying getColor().

    • getScaleX

      public float getScaleX()

    • getScaleY

      public float getScaleY()

    • getRegion

      public TextureRegion getRegion()
      Returns the first texture region. This is included for backwards compatibility, and for convenience since most fonts only use one texture page. For multi-page fonts, use getRegions().
      Returns:
      the first texture region

    • getRegions

      public Seq<TextureRegion> getRegions()
      Returns the array of TextureRegions that represents each texture page of glyphs.
      Returns:
      the array of texture regions; modifying it may produce undesirable results

    • getRegion

      public TextureRegion getRegion(int index)
      Returns the texture page at the given index.
      Returns:
      the texture page at the given index

    • getLineHeight

      public float getLineHeight()
      Returns the line height, which is the distance from one line of text to the next.

    • getSpaceXadvance

      public float getSpaceXadvance()
      Returns the x-advance of the space character.

    • getXHeight

      public float getXHeight()
      Returns the x-height, which is the distance from the top of most lowercase characters to the baseline.

    • getCapHeight

      public float getCapHeight()
      Returns the cap height, which is the distance from the top of most uppercase characters to the baseline. Since the drawing position is the cap height of the first line, the cap height can be used to get the location of the baseline.

    • getAscent

      public float getAscent()
      Returns the ascent, which is the distance from the cap height to the top of the tallest glyph.

    • getDescent

      public float getDescent()
      Returns the descent, which is the distance from the bottom of the glyph that extends the lowest to the baseline. This number is negative.

    • isFlipped

      public boolean isFlipped()
      Returns true if this BitmapFont has been flipped for use with a y-down coordinate system.

    • dispose

      public void dispose()
      Disposes the texture used by this BitmapFont's region IF this BitmapFont created the texture.
      Specified by:
      dispose in interface Disposable

    • isDisposed

      public boolean isDisposed()
      Specified by:
      isDisposed in interface Disposable

    • setFixedWidthGlyphs

      public void setFixedWidthGlyphs(CharSequence glyphs)
      Makes the specified glyphs fixed width. This can be useful to make the numbers in a font fixed width. Eg, when horizontally centering a score or loading percentage text, it will not jump around as different numbers are shown.

    • setUseIntegerPositions

      public void setUseIntegerPositions(boolean integer)
      Specifies whether to use integer positions. Default is to use them so filtering doesn't kick in as badly.

    • usesIntegerPositions

      public boolean usesIntegerPositions()
      Checks whether this font uses integer positions for drawing.

    • getCache

      public FontCache getCache()
      For expert usage -- returns the BitmapFontCache used by this font, for rendering to a sprite batch. This can be used, for example, to manipulate glyph colors within a specific index.
      Returns:
      the bitmap font cache used by this font

    • getData

      public Font.FontData getData()
      Gets the underlying Font.FontData for this BitmapFont.

    • ownsTexture

      public boolean ownsTexture()
      Returns:
      whether the texture is owned by the font, font disposes the texture itself if true

    • setOwnsTexture

      public void setOwnsTexture(boolean ownsTexture)
      Sets whether the font owns the texture. In case it does, the font will also dispose of the texture when dispose() is called. Use with care!
      Parameters:
      ownsTexture - whether the font owns the texture

    • newFontCache

      public FontCache newFontCache()
      Creates a new BitmapFontCache for this font. Using this method allows the font to provide the BitmapFontCache implementation to customize rendering.

      Note this method is called by the BitmapFont constructors. If a subclass overrides this method, it will be called before the subclass constructors.

    • toString

      public String toString()
      Overrides:
      toString in class Object