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

  • 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

  • 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

    • 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