Package com.github.tommyettinger.textra

Class Layout

java.lang.Object
com.github.tommyettinger.textra.Layout
public class Layout extends Object
A replacement for libGDX's GlyphLayout, more or less; stores one or more (possibly empty) Lines of text, which can use color and style markup from Font, and can be drawn with Font.drawGlyphs(Batch, Layout, float, float, int). You can obtain a Layout with new Layout() followed by setting the font, or just using a constructor.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final com.badlogic.gdx.utils.FloatArray
    advances
    Contains one float per glyph; each is a multiplier to the x-advance of that glyph.
    protected boolean
    atLimit
     
    protected float
    baseColor
     
    protected String
    ellipsis
     
    protected Font
    font
     
    protected Justify
    justification
     
    protected final com.badlogic.gdx.utils.Array<Line>
    lines
     
    protected int
    maxLines
     
    final com.badlogic.gdx.utils.FloatArray
    offsets
    Contains two floats per glyph; even items are x offsets (0-indexed), odd items are y offsets.
    final com.badlogic.gdx.utils.FloatArray
    rotations
    Contains one float per glyph; each is a rotation in degrees to apply to that glyph (around its center).
    final com.badlogic.gdx.utils.FloatArray
    sizing
    Contains two floats per glyph, as size multipliers; even items (0-indexed) apply to x, odd items apply to y.
    protected float
    targetWidth
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    Layout()
     
    Layout(Font font)
     
    Layout(Layout other)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    Layout
    add(long glyph)
    Adds a long glyph as processed by Font to store color and style info with the char.
    Layout
    add(long glyph, float scale, float advance, float offsetX, float offsetY, float rotation)
    Adds a long glyph as processed by Font to store color and style info with the char.
    StringBuilder
    appendInto(StringBuilder sb)
    Primarily used by toString(), but can be useful if you want to append many Layouts into a StringBuilder.
    StringBuilder
    appendIntoDirect(StringBuilder sb)
    Can be useful if you want to append many Layouts into a StringBuilder.
    StringBuilder
    appendSubstringInto(StringBuilder sb, int start, int end)
    Gets a String representation of part of this Layout, made of only the char portions of the glyphs from start (inclusive) to end (exclusive).
    Layout
    clear()
     
    int
    countGlyphs()
    Calculates how many long glyphs are currently in this layout, and returns that count.
    int
    countGlyphsBeforeLine(int lineIndex)
    Calculates how many long glyphs are currently in this layout before the start of the Line with the given lineIndex, and returns that count.
    Layout
    font(Font font)
    One of the ways to set the font on a Layout; this one returns this Layout for chaining.
    float
    getBaseColor()
    Gets the base color of the Layout, as the float bits of a Color.
    String
    getEllipsis()
    Gets the ellipsis, which may be null, or may be a String that can be placed at the end of the text if its max lines are exceeded.
    Font
    getFont()
     
    float
    getHeight()
     
    Justify
    getJustification()
     
    Line
    getLine(int i)
    Gets a Line from this by its index.
    int
    getMaxLines()
    The maximum number of Lines this Layout can contain.
    float
    getTargetWidth()
     
    float
    getWidth()
     
    Line
    insertLine(int index)
     
    int
    lines()
     
    Line
    peekLine()
     
    Line
    pushLine()
     
    Line
    pushLineBare()
     
    void
    reset()
    Resets the object for reuse.
    Layout
    setBaseColor(float baseColor)
    Sets the base color of the Layout; this is what font color will be used immediately after resetting formatting with [], as well as the initial color used by text that hasn't been formatted.
    Layout
    setBaseColor(com.badlogic.gdx.graphics.Color baseColor)
    Sets the base color of the Layout; this is what font color will be used immediately after resetting formatting with [], as well as the initial color used by text that hasn't been formatted.
    Layout
    setEllipsis(String ellipsis)
    Sets the ellipsis text, which replaces the last few glyphs if non-null and the text added would exceed the getMaxLines() of this Layout.
    void
    setFont(Font font)
    One of the ways to set the font on a Layout; this is a traditional setter.
    Layout
    setJustification(Justify justification)
     
    Layout
    setMaxLines(int maxLines)
    Sets the maximum number of Lines this Layout can contain; this is always at least 1.
    Layout
    setTargetWidth(float targetWidth)
     
    String
    toString()
    Simply delegates to calling appendInto(StringBuilder) with a new StringBuilder, calling toString(), and then returning.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • font

      protected Font font

    • lines

      protected final com.badlogic.gdx.utils.Array<Line> lines

    • maxLines

      protected int maxLines

    • atLimit

      protected boolean atLimit

    • ellipsis

      protected String ellipsis

    • targetWidth

      protected float targetWidth

    • baseColor

      protected float baseColor

    • justification

      protected Justify justification

    • offsets

      public final com.badlogic.gdx.utils.FloatArray offsets
      Contains two floats per glyph; even items are x offsets (0-indexed), odd items are y offsets. The neutral value for a glyph (the value that this defaults to, and means no change should be made) is 0.0f.

    • sizing

      public final com.badlogic.gdx.utils.FloatArray sizing
      Contains two floats per glyph, as size multipliers; even items (0-indexed) apply to x, odd items apply to y. The neutral value for a glyph (the value that this defaults to, and means no change should be made) is 1.0f.

    • rotations

      public final com.badlogic.gdx.utils.FloatArray rotations
      Contains one float per glyph; each is a rotation in degrees to apply to that glyph (around its center). The neutral value for a glyph (the value that this defaults to, and means no change should be made) is 0.0f.

    • advances

      public final com.badlogic.gdx.utils.FloatArray advances
      Contains one float per glyph; each is a multiplier to the x-advance of that glyph. The neutral value for a glyph (the value that this defaults to, and means no change should be made) is 1.0f.

  • Constructor Details

    • Layout

      public Layout()

    • Layout

      public Layout(Font font)

    • Layout

      public Layout(Layout other)

  • Method Details

    • font

      public Layout font(Font font)
      One of the ways to set the font on a Layout; this one returns this Layout for chaining.
      Parameters:
      font - the font to use
      Returns:
      this Layout, for chaining

    • getFont

      public Font getFont()

    • setFont

      public void setFont(Font font)
      One of the ways to set the font on a Layout; this is a traditional setter.
      Parameters:
      font - the font to use

    • add

      public Layout add(long glyph)
      Adds a long glyph as processed by Font to store color and style info with the char.
      Parameters:
      glyph - usually produced by Font to store color and style info with the char
      Returns:
      this Layout, for chaining

    • add

      public Layout add(long glyph, float scale, float advance, float offsetX, float offsetY, float rotation)
      Adds a long glyph as processed by Font to store color and style info with the char.
      Parameters:
      glyph - usually produced by Font to store color and style info with the char
      scale - 1.0f if unchanged; multiplies the size of the glyph
      advance - 1.0f if unchanged; multiplies the x-advance of the glyph, and is usually related to scale
      offsetX - 0.0f if unchanged; added to the initial x-position of the glyph
      offsetY - 0.0f if unchanged; added to the y-position of the glyph (with descenders lower than ascenders)
      rotation - 0.0f if unchanged; added to the rotation of the glyph, in degrees
      Returns:
      this Layout, for chaining

    • clear

      public Layout clear()

    • getWidth

      public float getWidth()

    • getHeight

      public float getHeight()

    • lines

      public int lines()

    • getLine

      public Line getLine(int i)
      Gets a Line from this by its index.
      Parameters:
      i - index for the Line to fetch; must be at least 0 and less than lines().
      Returns:
      the Line at the given index

    • peekLine

      public Line peekLine()

    • pushLine

      public Line pushLine()

    • pushLineBare

      public Line pushLineBare()

    • insertLine

      public Line insertLine(int index)

    • getTargetWidth

      public float getTargetWidth()

    • setTargetWidth

      public Layout setTargetWidth(float targetWidth)

    • getBaseColor

      public float getBaseColor()
      Gets the base color of the Layout, as the float bits of a Color. The base color is what font color will be used immediately after resetting formatting with [], as well as the initial color used by text that hasn't been formatted. You can fill a Color object with this value using Color.abgr8888ToColor(Color, float) (it modifies the Color you give it).
      Returns:
      the base color of the Layout, as float bits

    • setBaseColor

      public Layout setBaseColor(float baseColor)
      Sets the base color of the Layout; this is what font color will be used immediately after resetting formatting with [], as well as the initial color used by text that hasn't been formatted. This takes the color as a primitive float, which you can get from a Color object with Color.toFloatBits(), or in some cases from existing data produced by Font.
      Parameters:
      baseColor - the float bits of a Color, as obtainable via Color.toFloatBits()

    • setBaseColor

      public Layout setBaseColor(com.badlogic.gdx.graphics.Color baseColor)
      Sets the base color of the Layout; this is what font color will be used immediately after resetting formatting with [], as well as the initial color used by text that hasn't been formatted. If the given Color is null, this treats it as white.
      Parameters:
      baseColor - a Color to use for text that hasn't been formatted; if null, will be treated as white

    • getMaxLines

      public int getMaxLines()
      The maximum number of Lines this Layout can contain.
      Returns:
      the maximum number of Line objects this Layout can contain

    • setMaxLines

      public Layout setMaxLines(int maxLines)
      Sets the maximum number of Lines this Layout can contain; this is always at least 1. For effectively unlimited lines, pass Integer.MAX_VALUE to this.
      Parameters:
      maxLines - the limit for how many Line objects this Layout can contain; always 1 or more

    • getEllipsis

      public String getEllipsis()
      Gets the ellipsis, which may be null, or may be a String that can be placed at the end of the text if its max lines are exceeded.
      Returns:
      an ellipsis String or null

    • setEllipsis

      public Layout setEllipsis(String ellipsis)
      Sets the ellipsis text, which replaces the last few glyphs if non-null and the text added would exceed the getMaxLines() of this Layout. For the ellipsis to appear, this has to be called with a non-null String (often "...", or "…" if the font supports it), and setMaxLines(int) needs to have been called with a small enough number, such as 1.
      Parameters:
      ellipsis - a String for a Layout to end with if its max lines are exceeded, or null to avoid such truncation

    • getJustification

      public Justify getJustification()

    • setJustification

      public Layout setJustification(Justify justification)

    • countGlyphs

      public int countGlyphs()
      Calculates how many long glyphs are currently in this layout, and returns that count. This takes time proportional to the value of lines(), not the number of glyphs.
      Returns:
      how many long glyphs are in this Layout

    • countGlyphsBeforeLine

      public int countGlyphsBeforeLine(int lineIndex)
      Calculates how many long glyphs are currently in this layout before the start of the Line with the given lineIndex, and returns that count. This is mainly useful for mapping an index into a Line to an index in a Layout's non-Line-based FloatArray fields, such as advances or rotations. Some FloatArray fields use two floats per glyph, such as offsets and sizing; see their docs for more.
      This takes time proportional to the value of lineIndex, not the number of glyphs.
      Returns:
      how many long glyphs exist in this Layout before the start of the given Line

    • reset

      public void reset()
      Resets the object for reuse. The font is nullified, but the lines are cleared and then one blank line is re-added to lines so it can be used normally later.

    • appendIntoDirect

      public StringBuilder appendIntoDirect(StringBuilder sb)
      Can be useful if you want to append many Layouts into a StringBuilder. This does not treat character u0002 any differently from other characters, which is where it differs from appendInto(StringBuilder). This does not add or remove newlines from the Layout's contents, and can produce line breaks if they appear.
      Parameters:
      sb - a non-null StringBuilder from the JDK
      Returns:
      sb, for chaining

    • appendSubstringInto

      public StringBuilder appendSubstringInto(StringBuilder sb, int start, int end)
      Gets a String representation of part of this Layout, made of only the char portions of the glyphs from start (inclusive) to end (exclusive). This can retrieve text from across multiple lines. If this encounters the special placeholder character u0002, it treats it as '[', like the rest of the library does. If this encounters emoji, icons, or other inline images assigned to the font with Font.addAtlas(TextureAtlas), then this will use a name that can be used to look up that inline image (such as an actual emoji like 🤖 instead of the gibberish character that [+robot] produces internally).
      Parameters:
      sb - a non-null StringBuilder from the JDK; will be modified if this Layout is non-empty
      start - inclusive start index to begin taking chars from
      end - exclusive end index to stop taking chars before
      Returns:
      sb, for chaining

    • appendInto

      public StringBuilder appendInto(StringBuilder sb)
      Primarily used by toString(), but can be useful if you want to append many Layouts into a StringBuilder. If this encounters the special placeholder character u0002, it treats it as '[', like the rest of the library does. If this encounters emoji, icons, or other inline images assigned to the font with Font.addAtlas(TextureAtlas), then this will use a name that can be used to look up that inline image (such as an actual emoji like 🤖 instead of the gibberish character that [+robot] produces internally). This does not add or remove newlines from the Layout's contents, and can produce line breaks if they appear.
      Parameters:
      sb - a non-null StringBuilder from the JDK; will be modified if this Layout is non-empty
      Returns:
      sb, for chaining

    • toString

      public String toString()
      Simply delegates to calling appendInto(StringBuilder) with a new StringBuilder, calling toString(), and then returning. See the documentation for appendInto for more details.
      Overrides:
      toString in class Object
      Returns:
      a String holding the char portions of every glyph in this Layout, substituting in names for inline image codes