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).

  • Field Summary

    Fields
    Modifier and Type Field Description
    int align  
    protected Font font  
    Layout layout  
    java.lang.String storedText  
    com.badlogic.gdx.scenes.scene2d.ui.Label.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​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Label.LabelStyle style)
    Creates a TextraLabel with the given text (which may be multi-line) and using the given style.
    TextraLabel​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Label.LabelStyle style, boolean makeGridGlyphs)
    Creates a TextraLabel with the given text (which may be multi-line) and using the given style.
    TextraLabel​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Label.LabelStyle style, Font replacementFont)
    Creates a TextraLabel with the given text (which may be multi-line) and using the given style.
    TextraLabel​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, java.lang.String styleName)
    Creates a TextraLabel with the given text (which may be multi-line) and using the specified style from the given Skin.
    TextraLabel​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, java.lang.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​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, java.lang.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​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, java.lang.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​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, java.lang.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​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, java.lang.String styleName, java.lang.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​(java.lang.String text, Font font)
    Creates a TextraLabel with the given text (which may be multi-line) and using the given Font.
    TextraLabel​(java.lang.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.

  • 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.
    java.lang.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​(java.lang.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​(java.lang.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.
    void skipToTheEnd()
    By default, does nothing; this is overridden in TypingLabel to skip its text progression ahead.
    java.lang.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).
    java.lang.String toString()  
    TextraLabel useIntegerPositions​(boolean integer)  

    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 java.lang.String storedText

    • style

      public com.badlogic.gdx.scenes.scene2d.ui.Label.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​(java.lang.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.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      skin - the default Label.LabelStyle will be obtained from this and used

    • TextraLabel

      public TextraLabel​(java.lang.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.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      skin - the default Label.LabelStyle will be obtained from this and used
      makeGridGlyphs - if true, the font should have a solid block glyph available, and underline/strikethrough may be drawn more clearly; if false, underline/strikethrough will use underscore/dash

    • TextraLabel

      public TextraLabel​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, java.lang.String styleName)
      Creates a TextraLabel with the given text (which may be multi-line) and using the specified style from the given Skin.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      skin - the named Label.LabelStyle will be obtained from this and used
      styleName - the name of a Label.LabelStyle to use from the Skin

    • TextraLabel

      public TextraLabel​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, java.lang.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.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      skin - the named Label.LabelStyle will be obtained from this and used
      styleName - the name of a Label.LabelStyle to use from the Skin
      makeGridGlyphs - if true, the font should have a solid block glyph available, and underline/strikethrough may be drawn more clearly; if false, underline/strikethrough will use underscore/dash

    • TextraLabel

      public TextraLabel​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, java.lang.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.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      skin - the named Label.LabelStyle will be obtained from this and used
      styleName - the name of a Label.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​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, java.lang.String styleName, java.lang.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.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      skin - the named Label.LabelStyle will be obtained from this and used
      styleName - the name of a Label.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​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Label.LabelStyle style)
      Creates a TextraLabel with the given text (which may be multi-line) and using the given style.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      style - the Label.LabelStyle to use

    • TextraLabel

      public TextraLabel​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Label.LabelStyle style, boolean makeGridGlyphs)
      Creates a TextraLabel with the given text (which may be multi-line) and using the given style.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      style - the Label.LabelStyle to use
      makeGridGlyphs - if true, the font should have a solid block glyph available, and underline/strikethrough may be drawn more clearly; if false, underline/strikethrough will use underscore/dash

    • TextraLabel

      public TextraLabel​(java.lang.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.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      skin - the default Label.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​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, java.lang.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.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      skin - the named Label.LabelStyle will be obtained from this and used
      styleName - the name of a Label.LabelStyle to use from the Skin
      replacementFont - a Font that will be used in place of the one in style

    • TextraLabel

      public TextraLabel​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, java.lang.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.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      skin - the named Label.LabelStyle will be obtained from this and used
      styleName - the name of a Label.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​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Label.LabelStyle style, Font replacementFont)
      Creates a TextraLabel with the given text (which may be multi-line) and using the given style.
      Parameters:
      text - the text to use; may be multi-line, but will default to not wrapping
      style - the Label.LabelStyle to use, except for its font
      replacementFont - a Font that will be used in place of the one in style

    • TextraLabel

      public TextraLabel​(java.lang.String text, Font font)
      Creates a TextraLabel with the given text (which may be multi-line) and using the given Font.
      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​(java.lang.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.
      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)

    • 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​(java.lang.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 void 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 java.lang.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 java.lang.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​(java.lang.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 java.lang.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