Package net.md_5.bungee.api.chat

# Class ComponentBuilder

java.lang.Object
net.md_5.bungee.api.chat.ComponentBuilder

public final class ComponentBuilder extends Object

ComponentBuilder simplifies creating basic messages by allowing the use of a chainable builder.

     new ComponentBuilder("Hello ").color(ChatColor.RED).
     append("World").color(ChatColor.BLUE). append("!").bold(true).create();

All methods (excluding `append(String)` and `create()` work on the last part appended to the builder, so in the example above "Hello " would be `ChatColor.RED` and "World" would be `ChatColor.BLUE` but "!" would be bold and `ChatColor.BLUE` because append copies the previous part's formatting

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `ComponentBuilder.FormatRetention`
  `static interface`
  `ComponentBuilder.Joiner`
  Functional interface to join additional components to a ComponentBuilder.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ComponentBuilder()`
  `ComponentBuilder(String text)`
  Creates a ComponentBuilder with the given text as the first part.
  `ComponentBuilder(BaseComponent component)`
  Creates a ComponentBuilder with the given component as the first part.
  `ComponentBuilder(ComponentBuilder original)`
  Creates a ComponentBuilder from the other given ComponentBuilder to clone it.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ComponentBuilder`
  `append(String text)`
  Appends the text to the builder and makes it the current target for formatting.
  `ComponentBuilder`
  `append(String text, ComponentBuilder.FormatRetention retention)`
  Appends the text to the builder and makes it the current target for formatting.
  `ComponentBuilder`
  `append(BaseComponent component)`
  Appends a component to the builder and makes it the current target for formatting.
  `ComponentBuilder`
  `append(BaseComponent[] components)`
  Appends the components to the builder and makes the last element the current target for formatting.
  `ComponentBuilder`
  `append(BaseComponent[] components, ComponentBuilder.FormatRetention retention)`
  Appends the components to the builder and makes the last element the current target for formatting.
  `ComponentBuilder`
  `append(BaseComponent component, ComponentBuilder.FormatRetention retention)`
  Appends a component to the builder and makes it the current target for formatting.
  `ComponentBuilder`
  `append(ComponentBuilder.Joiner joiner)`
  Allows joining additional components to this builder using the given `ComponentBuilder.Joiner` and `ComponentBuilder.FormatRetention.ALL`.
  `ComponentBuilder`
  `append(ComponentBuilder.Joiner joiner, ComponentBuilder.FormatRetention retention)`
  Allows joining additional components to this builder using the given `ComponentBuilder.Joiner`.
  `ComponentBuilder`
  `append(TranslationProvider translatable)`
  Appends the `TranslationProvider` object to the builder and makes the last element the current target for formatting.
  `ComponentBuilder`
  `append(TranslationProvider translatable, ComponentBuilder.FormatRetention retention)`
  Appends the `TranslationProvider` object to the builder and makes the last element the current target for formatting.
  `ComponentBuilder`
  `appendLegacy(String text)`
  Parse text to BaseComponent[] with colors and format, appends the text to the builder and makes it the current target for formatting.
  `ComponentBuilder`
  `bold(boolean bold)`
  Sets whether the current part is bold.
  `BaseComponent`
  `build()`
  Returns the component built by this builder.
  `ComponentBuilder`
  `color(ChatColor color)`
  Sets the color of the current part.
  `BaseComponent[]`
  `create()`
  Returns the components needed to display the message created by this builder.git
  `ComponentBuilder`
  `event(ClickEvent clickEvent)`
  Sets the click event for the current part.
  `ComponentBuilder`
  `event(HoverEvent hoverEvent)`
  Sets the hover event for the current part.
  `ComponentBuilder`
  `font(String font)`
  Sets the font of the current part.
  `BaseComponent`
  `getComponent(int pos)`
  Gets the component part at the position of given index.
  `BaseComponent`
  `getCurrentComponent()`
  Gets the component at the position of the cursor.
  `int`
  `getCursor()`
  The position for the current part to modify.
  `List<BaseComponent>`
  `getParts()`
  `ComponentBuilder`
  `insertion(String insertion)`
  Sets the insertion text for the current part.
  `ComponentBuilder`
  `italic(boolean italic)`
  Sets whether the current part is italic.
  `ComponentBuilder`
  `obfuscated(boolean obfuscated)`
  Sets whether the current part is obfuscated.
  `void`
  `removeComponent(int pos)`
  Remove the component part at the position of given index.
  `ComponentBuilder`
  `reset()`
  Sets the current part back to normal settings.
  `ComponentBuilder`
  `resetCursor()`
  Resets the cursor to index of the last element.
  `ComponentBuilder`
  `retain(ComponentBuilder.FormatRetention retention)`
  Retains only the specified formatting.
  `ComponentBuilder`
  `setCursor(int pos)`
  Sets the position of the current component to be modified
  `ComponentBuilder`
  `shadowColor(Color color)`
  Sets the shadow color of the current part.
  `ComponentBuilder`
  `strikethrough(boolean strikethrough)`
  Sets whether the current part is strikethrough.
  `ComponentBuilder`
  `style(ComponentStyle style)`
  Applies the provided `ComponentStyle` to the current part.
  `ComponentBuilder`
  `underlined(boolean underlined)`
  Sets whether the current part is underlined.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### ComponentBuilder

    public ComponentBuilder(ComponentBuilder original)
    Creates a ComponentBuilder from the other given ComponentBuilder to clone it.
    Parameters:
      `original` - the original for the new ComponentBuilder.

  - ### ComponentBuilder

    public ComponentBuilder(String text)
    Creates a ComponentBuilder with the given text as the first part.
    Parameters:
      `text` - the first text element

  - ### ComponentBuilder

    public ComponentBuilder(BaseComponent component)
    Creates a ComponentBuilder with the given component as the first part.
    Parameters:
      `component` - the first component element

  - ### ComponentBuilder

    public ComponentBuilder()

- ## Method Details

  - ### resetCursor

    public ComponentBuilder resetCursor()
    Resets the cursor to index of the last element.
    Returns:
      this ComponentBuilder for chaining

  - ### setCursor

    public ComponentBuilder setCursor(int pos) throws IndexOutOfBoundsException
    Sets the position of the current component to be modified
    Parameters:
      `pos` - the cursor position synonymous to an element position for a list
    Returns:
      this ComponentBuilder for chaining
    Throws:
      `IndexOutOfBoundsException` - if the index is out of range (`index < 0 || index >= size()`)

  - ### append

    public ComponentBuilder append(BaseComponent component)
    Appends a component to the builder and makes it the current target for formatting. The component will have all the formatting from previous part.
    Parameters:
      `component` - the component to append
    Returns:
      this ComponentBuilder for chaining

  - ### append

    public ComponentBuilder append(BaseComponent component, ComponentBuilder.FormatRetention retention)
    Appends a component to the builder and makes it the current target for formatting. You can specify the amount of formatting retained from previous part.
    Parameters:
      `component` - the component to append
      `retention` - the formatting to retain
    Returns:
      this ComponentBuilder for chaining

  - ### append

    public ComponentBuilder append(BaseComponent[] components)
    Appends the components to the builder and makes the last element the current target for formatting. The components will have all the formatting from previous part.
    Parameters:
      `components` - the components to append
    Returns:
      this ComponentBuilder for chaining

  - ### append

    public ComponentBuilder append(BaseComponent[] components, ComponentBuilder.FormatRetention retention)
    Appends the components to the builder and makes the last element the current target for formatting. You can specify the amount of formatting retained from previous part.
    Parameters:
      `components` - the components to append
      `retention` - the formatting to retain
    Returns:
      this ComponentBuilder for chaining

  - ### append

    public ComponentBuilder append(TranslationProvider translatable)
    Appends the `TranslationProvider` object to the builder and makes the last element the current target for formatting. The components will have all the formatting from previous part.
    Parameters:
      `translatable` - the translatable object to append
    Returns:
      this ComponentBuilder for chaining

  - ### append

    public ComponentBuilder append(TranslationProvider translatable, ComponentBuilder.FormatRetention retention)
    Appends the `TranslationProvider` object to the builder and makes the last element the current target for formatting. You can specify the amount of formatting retained from previous part.
    Parameters:
      `translatable` - the translatable object to append
      `retention` - the formatting to retain
    Returns:
      this ComponentBuilder for chaining

  - ### append

    public ComponentBuilder append(String text)
    Appends the text to the builder and makes it the current target for formatting. The text will have all the formatting from previous part.
    Parameters:
      `text` - the text to append
    Returns:
      this ComponentBuilder for chaining

  - ### appendLegacy

    public ComponentBuilder appendLegacy(String text)
    Parse text to BaseComponent[] with colors and format, appends the text to the builder and makes it the current target for formatting. The component will have all the formatting from previous part.
    Parameters:
      `text` - the text to append
    Returns:
      this ComponentBuilder for chaining

  - ### append

    public ComponentBuilder append(String text, ComponentBuilder.FormatRetention retention)
    Appends the text to the builder and makes it the current target for formatting. You can specify the amount of formatting retained from previous part.
    Parameters:
      `text` - the text to append
      `retention` - the formatting to retain
    Returns:
      this ComponentBuilder for chaining

  - ### append

    public ComponentBuilder append(ComponentBuilder.Joiner joiner)
    Allows joining additional components to this builder using the given `ComponentBuilder.Joiner` and `ComponentBuilder.FormatRetention.ALL`. Simply executes the provided joiner on this instance to facilitate a chain pattern.
    Parameters:
      `joiner` - joiner used for operation
    Returns:
      this ComponentBuilder for chaining

  - ### append

    public ComponentBuilder append(ComponentBuilder.Joiner joiner, ComponentBuilder.FormatRetention retention)
    Allows joining additional components to this builder using the given `ComponentBuilder.Joiner`. Simply executes the provided joiner on this instance to facilitate a chain pattern.
    Parameters:
      `joiner` - joiner used for operation
      `retention` - the formatting to retain
    Returns:
      this ComponentBuilder for chaining

  - ### removeComponent

    public void removeComponent(int pos) throws IndexOutOfBoundsException
    Remove the component part at the position of given index.
    Parameters:
      `pos` - the index to remove at
    Throws:
      `IndexOutOfBoundsException` - if the index is out of range (`index < 0 || index >= size()`)

  - ### getComponent

    public BaseComponent getComponent(int pos) throws IndexOutOfBoundsException
    Gets the component part at the position of given index.
    Parameters:
      `pos` - the index to find
    Returns:
      the component
    Throws:
      `IndexOutOfBoundsException` - if the index is out of range (`index < 0 || index >= size()`)

  - ### getCurrentComponent

    public BaseComponent getCurrentComponent()
    Gets the component at the position of the cursor.
    Returns:
      the active component or null if builder is empty

  - ### color

    public ComponentBuilder color(ChatColor color)
    Sets the color of the current part.
    Parameters:
      `color` - the new color
    Returns:
      this ComponentBuilder for chaining

  - ### shadowColor

    public ComponentBuilder shadowColor(Color color)
    Sets the shadow color of the current part.
    Parameters:
      `color` - the new shadow color
    Returns:
      this ComponentBuilder for chaining
    Since:
      Minecraft 1.21.4-pre1

  - ### font

    public ComponentBuilder font(String font)
    Sets the font of the current part.
    Parameters:
      `font` - the new font
    Returns:
      this ComponentBuilder for chaining

  - ### bold

    public ComponentBuilder bold(boolean bold)
    Sets whether the current part is bold.
    Parameters:
      `bold` - whether this part is bold
    Returns:
      this ComponentBuilder for chaining

  - ### italic

    public ComponentBuilder italic(boolean italic)
    Sets whether the current part is italic.
    Parameters:
      `italic` - whether this part is italic
    Returns:
      this ComponentBuilder for chaining

  - ### underlined

    public ComponentBuilder underlined(boolean underlined)
    Sets whether the current part is underlined.
    Parameters:
      `underlined` - whether this part is underlined
    Returns:
      this ComponentBuilder for chaining

  - ### strikethrough

    public ComponentBuilder strikethrough(boolean strikethrough)
    Sets whether the current part is strikethrough.
    Parameters:
      `strikethrough` - whether this part is strikethrough
    Returns:
      this ComponentBuilder for chaining

  - ### obfuscated

    public ComponentBuilder obfuscated(boolean obfuscated)
    Sets whether the current part is obfuscated.
    Parameters:
      `obfuscated` - whether this part is obfuscated
    Returns:
      this ComponentBuilder for chaining

  - ### style

    public ComponentBuilder style(ComponentStyle style)
    Applies the provided `ComponentStyle` to the current part.
    Parameters:
      `style` - the style to apply
    Returns:
      this ComponentBuilder for chaining

  - ### insertion

    public ComponentBuilder insertion(String insertion)
    Sets the insertion text for the current part.
    Parameters:
      `insertion` - the insertion text
    Returns:
      this ComponentBuilder for chaining

  - ### event

    public ComponentBuilder event(ClickEvent clickEvent)
    Sets the click event for the current part.
    Parameters:
      `clickEvent` - the click event
    Returns:
      this ComponentBuilder for chaining

  - ### event

    public ComponentBuilder event(HoverEvent hoverEvent)
    Sets the hover event for the current part.
    Parameters:
      `hoverEvent` - the hover event
    Returns:
      this ComponentBuilder for chaining

  - ### reset

    public ComponentBuilder reset()
    Sets the current part back to normal settings. Only text is kept.
    Returns:
      this ComponentBuilder for chaining

  - ### retain

    public ComponentBuilder retain(ComponentBuilder.FormatRetention retention)
    Retains only the specified formatting. Text is not modified.
    Parameters:
      `retention` - the formatting to retain
    Returns:
      this ComponentBuilder for chaining

  - ### build

    public BaseComponent build()
    Returns the component built by this builder. If this builder is empty, an empty text component will be returned.
    Returns:
      the component

  - ### create

    public BaseComponent[] create()
    Returns the components needed to display the message created by this builder.git

    NOTE: `build()` is preferred as it will consolidate all components into a single BaseComponent with extra contents as opposed to an array of components which is non-standard and may result in unexpected behavior.

    Returns:
      the created components

  - ### getCursor

    public int getCursor()
    The position for the current part to modify. Modified cursors will automatically reset to the last part after appending new components. Default value at -1 to assert that the builder has no parts.

  - ### getParts

    public List<BaseComponent> getParts()