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.
As of TextraTypist 2.6.0, Layout no longer uses Line objects at all. In all earlier versions, a Layout contained one or more Line objects, and each Line knew its own width, height, and glyph contents. Now, since Layout was already tracking advances, sizing, rotations, and so on independently of lines, it also tracks glyphs, the starting indices of lines, and the sizes of lines.

  • 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
     
    final com.badlogic.gdx.utils.LongArray
    glyphs
    Contains one long per glyph; each long encodes a 16-bit char, 32-bit color, and 16 bits of style info.
    protected Justify
    justification
     
    final com.badlogic.gdx.utils.FloatArray
    lineSizes
    Contains two floats per line of text; even items are line widths (0-indexed), odd items are line heights.
    final com.badlogic.gdx.utils.IntArray
    lineStarts
    Contains one int per line of text, with each int the index in glyphs of the first glyph on that line.
    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.
    float
    addToLastHeight(float additional)
     
    float
    addToLastWidth(float additional)
     
    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()
    Clears the glyph contents of this Layout, but does not reset the targetWidth, baseColor, or ellipsis.
    int
    countGlyphs()
    Returns how many long glyphs are currently in this layout.
    int
    countGlyphsBeforeLine(int lineIndex)
    Gets 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()
     
    float
    getLastHeight()
     
    float
    getLastWidth()
     
    float
    getLineHeight(int ln)
     
    int
    getLineIndex(int index)
    Given an index into this Layout's glyphs, this returns the index of the line in the Layout that holds the glyph at that index.
    int
    getLineLength(int ln)
     
    float
    getLineWidth(int ln)
     
    int
    getMaxLines()
    The maximum number of lines this Layout can contain.
    float
    getTargetWidth()
     
    float
    getWidth()
     
    int
    lines()
     
    boolean
    pushLineBare()
    Adds a new size-0 line if this hasn't reached its limit and returns true, or returns false if this has reached its limit of getMaxLines().
    void
    reset()
    Resets the object for reuse.
    void
    set(int index, long newGlyph)
    If index is at least 0 and less than countGlyphs(), this will set the glyph at that index to be newGlyph.
    void
    set(int index, long newGlyph, float scale, float advance, float offsetX, float offsetY, float rotation)
    If index is at least 0 and less than countGlyphs(), this will set the glyph at that index to be newGlyph.
    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)
     
    float
    setLastHeight(float newValue)
     
    float
    setLastWidth(float newValue)
     
    void
    setLineHeight(int ln, float height)
     
    void
    setLineWidth(int ln, float width)
     
    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.
    Layout
    truncateExtra(int i)
    Mostly intended for internal use; when lines have been removed but the other fields here have not been changed, this will trim advances, rotations, sizing, and offsets to match the size of the total glyphs in all lines.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • font

      protected Font font

    • maxLines

      protected int maxLines

    • atLimit

      protected boolean atLimit

    • ellipsis

      protected String ellipsis

    • targetWidth

      protected float targetWidth

    • baseColor

      protected float baseColor

    • justification

      protected Justify justification

    • glyphs

      public final com.badlogic.gdx.utils.LongArray glyphs
      Contains one long per glyph; each long encodes a 16-bit char, 32-bit color, and 16 bits of style info. If a glyph's upper 32 bits are all 0, it is fully transparent, which can be used as a sort of neutral value.

    • lineStarts

      public final com.badlogic.gdx.utils.IntArray lineStarts
      Contains one int per line of text, with each int the index in glyphs of the first glyph on that line. This should always start with an item 0, and the exclusive end index of the last line can be obtained with countGlyphs().

    • lineSizes

      public final com.badlogic.gdx.utils.FloatArray lineSizes
      Contains two floats per line of text; even items are line widths (0-indexed), odd items are line heights. There is no neutral value for a line size, but 0 is reasonable for an empty line width and height.

    • 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

    • getLineIndex

      public int getLineIndex(int index)
      Given an index into this Layout's glyphs, this returns the index of the line in the Layout that holds the glyph at that index. A line index can be used with setLineHeight(int, float), getLineWidth(int) and similar methods.
      Parameters:
      index - an index into the given Layout
      Returns:
      the index of the line in the Layout containing the given index; will be 0 if index is -1, or the last line index if index is -2 or out of bounds

    • 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

    • set

      public void set(int index, long newGlyph)
      If index is at least 0 and less than countGlyphs(), this will set the glyph at that index to be newGlyph. This does not change the sizing, advances, offsets, or rotations.
      Parameters:
      index - should be at least 0 and less than countGlyphs(); the index to change
      newGlyph - usually produced by Font to store color and style info with the char

    • set

      public void set(int index, long newGlyph, float scale, float advance, float offsetX, float offsetY, float rotation)
      If index is at least 0 and less than countGlyphs(), this will set the glyph at that index to be newGlyph. This also sets the various FloatArray fields to have potentially-new values at that index.
      Parameters:
      index - should be at least 0 and less than countGlyphs(); the index to change
      newGlyph - 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

    • clear

      public Layout clear()
      Clears the glyph contents of this Layout, but does not reset the targetWidth, baseColor, or ellipsis. One empty line will be present in this Layout after it is cleared.
      Returns:
      this Layout, after changes, for chaining

    • getWidth

      public float getWidth()

    • getHeight

      public float getHeight()

    • lines

      public int lines()

    • getLineLength

      public int getLineLength(int ln)

    • getLineWidth

      public float getLineWidth(int ln)

    • setLineWidth

      public void setLineWidth(int ln, float width)

    • getLineHeight

      public float getLineHeight(int ln)

    • setLineHeight

      public void setLineHeight(int ln, float height)

    • pushLineBare

      public boolean pushLineBare()
      Adds a new size-0 line if this hasn't reached its limit and returns true, or returns false if this has reached its limit of getMaxLines().
      Returns:
      true if a new line was added, or false if this couldn't add a line because it has reached its limit

    • 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 lines 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 lines 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()
      Returns how many long glyphs are currently in this layout. This takes constant time.
      Returns:
      how many long glyphs are in this Layout

    • countGlyphsBeforeLine

      public int countGlyphsBeforeLine(int lineIndex)
      Gets how many long glyphs are currently in this layout before the start of the line with the given lineIndex, and returns that count.
      This takes constant time.
      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. For example, it will show 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. For example, it will show 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

    • truncateExtra

      public Layout truncateExtra(int i)
      Mostly intended for internal use; when lines have been removed but the other fields here have not been changed, this will trim advances, rotations, sizing, and offsets to match the size of the total glyphs in all lines.
      Parameters:
      i - the length to truncate to; often countGlyphs()
      Returns:
      this, for chaining

    • getLastWidth

      public float getLastWidth()

    • getLastHeight

      public float getLastHeight()

    • setLastWidth

      public float setLastWidth(float newValue)

    • setLastHeight

      public float setLastHeight(float newValue)

    • addToLastWidth

      public float addToLastWidth(float additional)

    • addToLastHeight

      public float addToLastHeight(float additional)