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). This is a Poolable class, and you can obtain a Layout with new Layout() followed by setting the font, or just using a constructor.

  • 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

  • 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

    • 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()

    • 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 void 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 void 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 void 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 void 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

    • 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

    • reset

      public void reset()
      Resets the object for reuse. The font is nulled, but the lines are freed, 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