All Implemented Interfaces:
Component, TextGUIElement
Direct Known Subclasses:
AnimatedLabel, FileDialog.FileSystemLocationLabel

public class Label extends AbstractComponent<Label>
Label is a simple read-only text display component. It supports customized colors and multi-line text.
  • Field Details

    • lines

      private String[] lines
    • labelWidth

      private Integer labelWidth
    • labelSize

      private TerminalSize labelSize
    • foregroundColor

      private TextColor foregroundColor
    • backgroundColor

      private TextColor backgroundColor
    • additionalStyles

      private final EnumSet<SGR> additionalStyles
  • Constructor Details

    • Label

      public Label(String text)
      Main constructor, creates a new Label displaying a specific text.
      Parameters:
      text - Text the label will display
  • Method Details

    • setLines

      protected void setLines(String[] lines)
      Protected access to set the internal representation of the text in this label, to be used by sub-classes of label in certain cases where setText(..) doesn't work. In general, you probably want to stick to setText(..) instead of this method unless you have a good reason not to.
      Parameters:
      lines - New lines this label will display
    • setText

      public void setText(String text)
      Updates the text this label is displaying
      Parameters:
      text - New text to display
    • getText

      public String getText()
      Returns the text this label is displaying. Multi-line labels will have their text concatenated with \n, even if they were originally set using multi-line text having \r\n as line terminators.
      Returns:
      String of the text this label is displaying
    • splitIntoMultipleLines

      protected String[] splitIntoMultipleLines(String text)
      Utility method for taking a string and turning it into an array of lines. This method is used in order to deal with line endings consistently.
      Parameters:
      text - Text to split
      Returns:
      Array of strings that forms the lines of the original string
    • getBounds

      protected TerminalSize getBounds(String[] lines, TerminalSize currentBounds)
      Returns the area, in terminal columns and rows, required to fully draw the lines passed in.
      Parameters:
      lines - Lines to measure the size of
      currentBounds - Optional (can pass null) terminal size to use for storing the output values. If the method is called many times and always returning the same value, passing in an external reference of this size will avoid creating new TerminalSize objects every time
      Returns:
      Size that is required to draw the lines
    • setForegroundColor

      public Label setForegroundColor(TextColor foregroundColor)
      Overrides the current theme's foreground color and use the one specified. If called with null, the override is cleared and the theme is used again.
      Parameters:
      foregroundColor - Foreground color to use when drawing the label, if null then use the theme's default
      Returns:
      Itself
    • getForegroundColor

      public TextColor getForegroundColor()
      Returns the foreground color used when drawing the label, or null if the color is read from the current theme.
      Returns:
      Foreground color used when drawing the label, or null if the color is read from the current theme.
    • setBackgroundColor

      public Label setBackgroundColor(TextColor backgroundColor)
      Overrides the current theme's background color and use the one specified. If called with null, the override is cleared and the theme is used again.
      Parameters:
      backgroundColor - Background color to use when drawing the label, if null then use the theme's default
      Returns:
      Itself
    • getBackgroundColor

      public TextColor getBackgroundColor()
      Returns the background color used when drawing the label, or null if the color is read from the current theme.
      Returns:
      Background color used when drawing the label, or null if the color is read from the current theme.
    • addStyle

      public Label addStyle(SGR sgr)
      Adds an additional SGR style to use when drawing the label, in case it wasn't enabled by the theme
      Parameters:
      sgr - SGR style to enable for this label
      Returns:
      Itself
    • removeStyle

      public Label removeStyle(SGR sgr)
      Removes an additional SGR style used when drawing the label, previously added by addStyle(..). If the style you are trying to remove is specified by the theme, calling this method will have no effect.
      Parameters:
      sgr - SGR style to remove
      Returns:
      Itself
    • setLabelWidth

      public Label setLabelWidth(Integer labelWidth)
      Use this method to limit how wide the label can grow. If set to null there is no limit but if set to a positive integer then the preferred size will be calculated using word wrapping for lines that are longer than this label width. This may make the label increase in height as new rows may be requested. Please note that some layout managers might assign more space to the label and because of this the wrapping might not be as you expect it. If set to 0, the label will request the same space as if set to null, but when drawing it will apply word wrapping instead of truncation in order to fit the label inside the designated area if it's smaller than what was requested. By default this is set to 0.
      Parameters:
      labelWidth - Either null or 0 for no limit on how wide the label can be, where 0 indicates word wrapping should be used if the assigned area is smaller than the requested size, or a positive integer setting the requested maximum width at what point word wrapping will begin
      Returns:
      Itself
    • getLabelWidth

      public Integer getLabelWidth()
      Returns the limit how wide the label can grow. If set to null or 0 there is no limit but if set to a positive integer then the preferred size will be calculated using word wrapping for lines that are longer than the label width. This may make the label increase in height as new rows may be requested. Please note that some layout managers might assign more space to the label and because of this the wrapping might not be as you expect it. If set to 0, the label will request the same space as if set to null, but when drawing it will apply word wrapping instead of truncation in order to fit the label inside the designated area if it's smaller than what was requested.
      Returns:
      Either null or 0 for no limit on how wide the label can be, where 0 indicates word wrapping should be used if the assigned area is smaller than the requested size, or a positive integer setting the requested maximum width at what point word wrapping will begin
    • createDefaultRenderer

      protected ComponentRenderer<Label> createDefaultRenderer()
      Description copied from class: AbstractComponent
      When you create a custom component, you need to implement this method and return a Renderer which is responsible for taking care of sizing the component, rendering it and choosing where to place the cursor (if Interactable). This value is intended to be overridden by custom themes.
      Specified by:
      createDefaultRenderer in class AbstractComponent<Label>
      Returns:
      Renderer to use when sizing and drawing this component