Package com.github.tommyettinger.textra

Class TextraLabel

java.lang.Object
com.badlogic.gdx.scenes.scene2d.Actor
com.badlogic.gdx.scenes.scene2d.ui.Widget
com.github.tommyettinger.textra.TextraLabel
All Implemented Interfaces:
com.badlogic.gdx.scenes.scene2d.utils.Layout
Direct Known Subclasses:
TypingLabel
public class TextraLabel extends com.badlogic.gdx.scenes.scene2d.ui.Widget
A scene2d.ui Widget that displays text using a Font rather than a libGDX BitmapFont. This supports being laid out in a Table just like the typical Label (when wrap is false, which is the default). This permits square-bracket tag markup from Font, such as [light blue] to change the font color, or [_] to underline text. It does not support the curly-brace token markup that its subclass TypingLabel does, nor does this handle input in the way TypingLabel can. It also, naturally, doesn't have the typing effect TypingLabel does, which makes this more suitable for some kinds of text. TypingLabel can be told to immediately TypingLabel.skipToTheEnd(), which does make it look like a TextraLabel, but permits effects.
This is meant to work with FWSkin or one of its subclasses, such as FreeTypistSkin, and isn't guaranteed to work with a regular Skin. FWSkin can load the same JSON files Skin uses, and it extends Skin.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    int
    align
     
    protected Font
    font
     
    Layout
    layout
     
    String
    storedText
     
    Styles.LabelStyle
    style
     
    boolean
    wrap
    If true; allows text to wrap when it would go past the layout's targetWidth and continue on the next line; if false, uses a very long target width and only adds newlines when they are in the label's text.

  • Constructor Summary

    Constructors
    Constructor
    Description
    TextraLabel()
    Creates a TextraLabel that uses the default libGDX font (lsans-15 in the current version) with white color.
    TextraLabel(String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin)
    Creates a TextraLabel with the given text (which may be multi-line) and using the specified Skin's LabelStyle.
    TextraLabel(String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, boolean makeGridGlyphs)
    Creates a TextraLabel with the given text (which may be multi-line) and using the specified Skin's LabelStyle.
    TextraLabel(String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, Font replacementFont)
    Creates a TextraLabel with the given text (which may be multi-line) and using the default style from a Skin, replacing any font that would be drawn from the style with replacementFont.
    TextraLabel(String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, String styleName)
    Creates a TextraLabel with the given text (which may be multi-line) and using the specified style from the given Skin.
    TextraLabel(String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, String styleName, boolean makeGridGlyphs)
    Creates a TextraLabel with the given text (which may be multi-line) and using the specified style from the given Skin.
    TextraLabel(String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, String styleName, com.badlogic.gdx.graphics.Color color)
    Creates a TextraLabel with the given text (which may be multi-line), using the specified style from the given Skin, with the default Color overridden by the given one.
    TextraLabel(String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, String styleName, Font replacementFont)
    Creates a TextraLabel with the given text (which may be multi-line) and using the given style taken by name from a Skin, replacing any font that would be drawn from the style with replacementFont.
    TextraLabel(String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, String styleName, Font replacementFont, com.badlogic.gdx.graphics.Color color)
    Creates a TextraLabel with the given text (which may be multi-line) and using the given style taken by name from a Skin, replacing any font that would be drawn from the style with replacementFont.
    TextraLabel(String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, String styleName, String colorName)
    Creates a TextraLabel with the given text (which may be multi-line), using the specified style from the given Skin, with the default Color overridden by the color with the given name in the skin.
    TextraLabel(String text, Font font)
    Creates a TextraLabel with the given text (which may be multi-line) and using the given Font.
    TextraLabel(String text, Font font, com.badlogic.gdx.graphics.Color color)
    Creates a TextraLabel with the given text (which may be multi-line), using the given Font, and using the given default color.
    TextraLabel(String text, Styles.LabelStyle style)
    Creates a TextraLabel with the given text (which may be multi-line) and using the given style.
    TextraLabel(String text, Styles.LabelStyle style, boolean makeGridGlyphs)
    Creates a TextraLabel with the given text (which may be multi-line) and using the given style.
    TextraLabel(String text, Styles.LabelStyle style, Font replacementFont)
    Creates a TextraLabel with the given text (which may be multi-line) and using the given style.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    draw(com.badlogic.gdx.graphics.g2d.Batch batch, float parentAlpha)
     
    int
    getAlignment()
    Gets the alignment for the text in this TextraLabel.
    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()
     
    long
    getGlyph(int index)
    Gets a glyph from this label's layout, where a glyph is a long encoded how Font uses it.
    float
    getLineHeight(int index)
    Gets the height of the Line containing the glyph at the given index.
    int
    getMaxLines()
    The maximum number of Lines this label can display.
    float
    getPrefHeight()
     
    float
    getPrefWidth()
     
    boolean
    isWrap()
    Gets the current wrapping mode.
    void
    layout()
     
    boolean
    remove()
     
    void
    setAlignment(int alignment)
    Sets the alignment for the text in this TextraLabel.
    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 label's layout.
    void
    setFont(Font font)
    Sets the font to the specified Font and then regenerates the layout using Font.regenerateLayout(Layout).
    void
    setFont(Font font, boolean regenerate)
    Just like setFont(Font), except this only regenerates the layout if regenerate is true.
    void
    setMaxLines(int maxLines)
    Sets the maximum number of Lines this Layout can display; this is always at least 1.
    protected void
    setParent(com.badlogic.gdx.scenes.scene2d.Group parent)
    Called by the framework when an actor is added to or removed from a group.
    void
    setSize(float width, float height)
     
    void
    setStage(com.badlogic.gdx.scenes.scene2d.Stage stage)
    Called by the framework when this actor or any ascendant is added to a group that is in the stage.
    void
    setText(String markupText)
    Changes the text in this TextraLabel to the given String, parsing any markup in it.
    TextraLabel
    setWrap(boolean wrap)
    Sets the wrapping mode; if this changes the mode, then this invalidates the hierarchy.
    TextraLabel
    skipToTheEnd()
    By default, does nothing; this is overridden in TypingLabel to skip its text progression ahead.
    String
    substring(int start, int end)
    Gets a String from the layout of this label, made of only the char portions of the glyphs from start (inclusive) to end (exclusive).
    String
    toString()
     
    TextraLabel
    useIntegerPositions(boolean integer)
    A no-op unless font is a subclass that overrides Font.handleIntegerPosition(float).

    Methods inherited from class com.badlogic.gdx.scenes.scene2d.ui.Widget

    getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, invalidate, invalidateHierarchy, needsLayout, pack, setFillParent, setLayoutEnabled, sizeChanged, validate

    Methods inherited from class com.badlogic.gdx.scenes.scene2d.Actor

    act, addAction, addCaptureListener, addListener, ancestorsVisible, ascendantsVisible, clear, clearActions, clearListeners, clipBegin, clipBegin, clipEnd, debug, drawDebug, drawDebugBounds, fire, firstAscendant, getActions, getCaptureListeners, getColor, getDebug, getHeight, getListeners, getName, getOriginX, getOriginY, getParent, getRight, getRotation, getScaleX, getScaleY, getStage, getTop, getTouchable, getUserObject, getWidth, getX, getX, getY, getY, getZIndex, hasActions, hasKeyboardFocus, hasParent, hasScrollFocus, hit, isAscendantOf, isDescendantOf, isTouchable, isTouchFocusListener, isTouchFocusTarget, isVisible, localToActorCoordinates, localToAscendantCoordinates, localToParentCoordinates, localToScreenCoordinates, localToStageCoordinates, moveBy, notify, parentToLocalCoordinates, positionChanged, removeAction, removeCaptureListener, removeListener, rotateBy, rotationChanged, scaleBy, scaleBy, scaleChanged, screenToLocalCoordinates, setBounds, setColor, setColor, setDebug, setHeight, setName, setOrigin, setOrigin, setOriginX, setOriginY, setPosition, setPosition, setRotation, setScale, setScale, setScaleX, setScaleY, setTouchable, setUserObject, setVisible, setWidth, setX, setX, setY, setY, setZIndex, sizeBy, sizeBy, stageToLocalCoordinates, toBack, toFront

    Methods inherited from class java.lang.Object

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

  • Field Details

    • layout

      public Layout layout

    • font

      protected Font font

    • align

      public int align

    • wrap

      public boolean wrap
      If true; allows text to wrap when it would go past the layout's targetWidth and continue on the next line; if false, uses a very long target width and only adds newlines when they are in the label's text. This should typically be false for widgets that use scene2d.ui layout, but should be true for any widget that dynamically adjusts to fill an area with wrapped text.

    • storedText

      public String storedText

    • style

      public Styles.LabelStyle style

  • Constructor Details

    • TextraLabel

      public TextraLabel()
      Creates a TextraLabel that uses the default libGDX font (lsans-15 in the current version) with white color.

    • TextraLabel

      public TextraLabel(String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin)
      Creates a TextraLabel with the given text (which may be multi-line) and using the specified Skin's LabelStyle. The skin should almost certainly be an FWSkin or one of its subclasses.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      skin - almost always an FWSkin or one of its subclasses; must have a Styles.LabelStyle or Label.LabelStyle registered as "default"

    • TextraLabel

      public TextraLabel(String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, boolean makeGridGlyphs)
      Creates a TextraLabel with the given text (which may be multi-line) and using the specified Skin's LabelStyle. The skin should almost certainly be an FWSkin or one of its subclasses.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      skin - almost always an FWSkin or one of its subclasses; must have a Styles.LabelStyle or Label.LabelStyle registered as "default"
      makeGridGlyphs - currently ignored

    • TextraLabel

      public TextraLabel(String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, String styleName)
      Creates a TextraLabel with the given text (which may be multi-line) and using the specified style from the given Skin. The skin should almost certainly be an FWSkin or one of its subclasses.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      skin - almost always an FWSkin or one of its subclasses; must have a Styles.LabelStyle or Label.LabelStyle registered with the given styleName
      styleName - the name of a Styles.LabelStyle to use from the Skin

    • TextraLabel

      public TextraLabel(String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, String styleName, boolean makeGridGlyphs)
      Creates a TextraLabel with the given text (which may be multi-line) and using the specified style from the given Skin. The skin should almost certainly be an FWSkin or one of its subclasses.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      skin - almost always an FWSkin or one of its subclasses; must have a Styles.LabelStyle or Label.LabelStyle registered with the given styleName
      styleName - the name of a Styles.LabelStyle to use from the Skin
      makeGridGlyphs - currently ignored

    • TextraLabel

      public TextraLabel(String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, String styleName, com.badlogic.gdx.graphics.Color color)
      Creates a TextraLabel with the given text (which may be multi-line), using the specified style from the given Skin, with the default Color overridden by the given one. The skin should almost certainly be an FWSkin or one of its subclasses.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      skin - almost always an FWSkin or one of its subclasses; must have a Styles.LabelStyle or Label.LabelStyle registered with the given styleName
      styleName - the name of a Styles.LabelStyle to use from the Skin
      color - the color to use for the font when unspecified (at the start and when reset)

    • TextraLabel

      public TextraLabel(String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, String styleName, String colorName)
      Creates a TextraLabel with the given text (which may be multi-line), using the specified style from the given Skin, with the default Color overridden by the color with the given name in the skin. The skin should almost certainly be an FWSkin or one of its subclasses.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      skin - almost always an FWSkin or one of its subclasses; must have a Styles.LabelStyle or Label.LabelStyle registered with the given styleName
      styleName - the name of a Styles.LabelStyle to use from the Skin
      colorName - the name in the skin of the color to use for the font when unspecified (at the start and when reset)

    • TextraLabel

      public TextraLabel(String text, Styles.LabelStyle style)
      Creates a TextraLabel with the given text (which may be multi-line) and using the given style. This does not require a Skin to be available.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      style - the Styles.LabelStyle to use

    • TextraLabel

      public TextraLabel(String text, Styles.LabelStyle style, boolean makeGridGlyphs)
      Creates a TextraLabel with the given text (which may be multi-line) and using the given style. This does not require a Skin to be available.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      style - the Styles.LabelStyle to use
      makeGridGlyphs - currently ignored

    • TextraLabel

      public TextraLabel(String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, Font replacementFont)
      Creates a TextraLabel with the given text (which may be multi-line) and using the default style from a Skin, replacing any font that would be drawn from the style with replacementFont. The skin should almost certainly be an FWSkin or one of its subclasses.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      skin - the default Styles.LabelStyle will be obtained from this and used
      replacementFont - a Font that will be used in place of the one in style

    • TextraLabel

      public TextraLabel(String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, String styleName, Font replacementFont)
      Creates a TextraLabel with the given text (which may be multi-line) and using the given style taken by name from a Skin, replacing any font that would be drawn from the style with replacementFont. The skin should almost certainly be an FWSkin or one of its subclasses.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      skin - almost always an FWSkin or one of its subclasses; must have a Styles.LabelStyle or Label.LabelStyle registered with the given styleName
      styleName - the name of a Styles.LabelStyle to use from the Skin
      replacementFont - a Font that will be used in place of the one in style

    • TextraLabel

      public TextraLabel(String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, String styleName, Font replacementFont, com.badlogic.gdx.graphics.Color color)
      Creates a TextraLabel with the given text (which may be multi-line) and using the given style taken by name from a Skin, replacing any font that would be drawn from the style with replacementFont. The skin should almost certainly be an FWSkin or one of its subclasses.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      skin - almost always an FWSkin or one of its subclasses; must have a Styles.LabelStyle or Label.LabelStyle registered with the given styleName
      styleName - the name of a Styles.LabelStyle to use from the Skin
      replacementFont - a Font that will be used in place of the one in style
      color - the base color to use for the label, used when reset

    • TextraLabel

      public TextraLabel(String text, Styles.LabelStyle style, Font replacementFont)
      Creates a TextraLabel with the given text (which may be multi-line) and using the given style. This does not require a Skin to be available.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      style - the Styles.LabelStyle to use, except for its font
      replacementFont - a Font that will be used in place of the one in style

    • TextraLabel

      public TextraLabel(String text, Font font)
      Creates a TextraLabel with the given text (which may be multi-line) and using the given Font. This does not require a Skin to be available.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      font - a Font from this library, such as one obtained from KnownFonts

    • TextraLabel

      public TextraLabel(String text, Font font, com.badlogic.gdx.graphics.Color color)
      Creates a TextraLabel with the given text (which may be multi-line), using the given Font, and using the given default color. This does not require a Skin to be available.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      font - a Font from this library, such as one obtained from KnownFonts
      color - the color to use for the font when unspecified (at the start and when reset)

  • Method Details

    • draw

      public void draw(com.badlogic.gdx.graphics.g2d.Batch batch, float parentAlpha)
      Overrides:
      draw in class com.badlogic.gdx.scenes.scene2d.ui.Widget

    • getPrefWidth

      public float getPrefWidth()
      Specified by:
      getPrefWidth in interface com.badlogic.gdx.scenes.scene2d.utils.Layout
      Overrides:
      getPrefWidth in class com.badlogic.gdx.scenes.scene2d.ui.Widget

    • getPrefHeight

      public float getPrefHeight()
      Specified by:
      getPrefHeight in interface com.badlogic.gdx.scenes.scene2d.utils.Layout
      Overrides:
      getPrefHeight in class com.badlogic.gdx.scenes.scene2d.ui.Widget

    • useIntegerPositions

      public TextraLabel useIntegerPositions(boolean integer)
      A no-op unless font is a subclass that overrides Font.handleIntegerPosition(float).
      Parameters:
      integer - usually ignored
      Returns:
      this for chaining

    • isWrap

      public boolean isWrap()
      Gets the current wrapping mode. When wrap is enabled, the preferred and/or min/max sizes must be used so this knows where to wrap. If wrap is disabled, lines that are too wide will just widen the size of the widget.
      Returns:
      whether this is currently wrapping

    • setWrap

      public TextraLabel setWrap(boolean wrap)
      Sets the wrapping mode; if this changes the mode, then this invalidates the hierarchy. When wrap is enabled, the preferred and/or min/max sizes must be used so this knows where to wrap. If wrap is disabled, lines that are too wide will just widen the size of the widget.
      Parameters:
      wrap - whether to wrap or not

    • setSize

      public void setSize(float width, float height)
      Overrides:
      setSize in class com.badlogic.gdx.scenes.scene2d.Actor

    • layout

      public void layout()
      Specified by:
      layout in interface com.badlogic.gdx.scenes.scene2d.utils.Layout
      Overrides:
      layout in class com.badlogic.gdx.scenes.scene2d.ui.Widget

    • getAlignment

      public int getAlignment()
      Gets the alignment for the text in this TextraLabel. This is a constant in Align.
      Returns:
      the alignment used by this TextraLabel, as a constant from Align
      See Also:
      • Align

    • setAlignment

      public void setAlignment(int alignment)
      Sets the alignment for the text in this TextraLabel.
      Parameters:
      alignment - a constant from Align
      See Also:
      • Align

    • getFont

      public Font getFont()

    • setFont

      public void setFont(Font font)
      Sets the font to the specified Font and then regenerates the layout using Font.regenerateLayout(Layout). This is equivalent to calling setFont(Font, boolean) with true for regenerate. This won't regenerate the layout if the given font is equal to the current font for this TextraLabel.
      Parameters:
      font - the non-null font to use for this TextraLabel

    • setFont

      public void setFont(Font font, boolean regenerate)
      Just like setFont(Font), except this only regenerates the layout if regenerate is true. (To contrast, setFont(Font) always regenerates the layout.) This won't regenerate the layout if the given font is equal to the current font for this TextraLabel.
      Parameters:
      font - the non-null font to use for this TextraLabel
      regenerate - if true, the layout will be re-wrapped and its size re-calculated for the new font

    • setText

      public void setText(String markupText)
      Changes the text in this TextraLabel to the given String, parsing any markup in it.
      Parameters:
      markupText - a String that can contain Font markup

    • skipToTheEnd

      public TextraLabel skipToTheEnd()
      By default, does nothing; this is overridden in TypingLabel to skip its text progression ahead.

    • remove

      public boolean remove()
      Overrides:
      remove in class com.badlogic.gdx.scenes.scene2d.Actor

    • setStage

      public void setStage(com.badlogic.gdx.scenes.scene2d.Stage stage)
      Called by the framework when this actor or any ascendant is added to a group that is in the stage. This is overridden as public instead of protected because most of its usage in scene2d.ui code is not actually in inheriting classes, but in other classes in the same package. That's a problem here, so we make it public.
      Overrides:
      setStage in class com.badlogic.gdx.scenes.scene2d.Actor
      Parameters:
      stage - May be null if the actor or any ascendant is no longer in a stage.

    • setParent

      protected void setParent(com.badlogic.gdx.scenes.scene2d.Group parent)
      Called by the framework when an actor is added to or removed from a group. This is overridden as public instead of protected because most of its usage in scene2d.ui code is not actually in inheriting classes, but in other classes in the same package. That's a problem here, so we make it public.
      Overrides:
      setParent in class com.badlogic.gdx.scenes.scene2d.Actor
      Parameters:
      parent - May be null if the actor has been removed from the parent.

    • toString

      public String toString()
      Overrides:
      toString in class com.badlogic.gdx.scenes.scene2d.Actor

    • getGlyph

      public long getGlyph(int index)
      Gets a glyph from this label's layout, where a glyph is a long encoded how Font uses it. In a TextraLabel, this is effectively equivalent to TypingLabel.getInWorkingLayout(int), but it may be different from that method in a TypingLabel, depending on word wrap.
      Parameters:
      index - the 0-based index of the glyph to retrieve
      Returns:
      the glyph, if it was found, or 16777215 (0xFFFFFF in hexadecimal) if the index was out of bounds

    • getMaxLines

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

    • setMaxLines

      public void setMaxLines(int maxLines)
      Sets the maximum number of Lines this Layout can display; 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 display; 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 label's 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

    • substring

      public String substring(int start, int end)
      Gets a String from the layout of this label, made of only the char portions of the glyphs from start (inclusive) to end (exclusive). This can retrieve text from across multiple lines.
      Parameters:
      start - inclusive start index
      end - exclusive end index
      Returns:
      a String made of only the char portions of the glyphs from start to end

    • getLineHeight

      public float getLineHeight(int index)
      Gets the height of the Line containing the glyph at the given index. If the index is out of bounds, this just returns Font.cellHeight.
      Parameters:
      index - the 0-based index of the glyph to measure
      Returns:
      the height of the Line containing the specified glyph