Package me.croabeast.prismatic.chat

Interface MultiComponent

All Superinterfaces:
ChatComponent<MultiComponent>
public interface MultiComponent extends ChatComponent<MultiComponent>
A composite ChatComponent that splits a raw message into interactive segments and manages them as a unified, fluent unit.

MultiComponent understands a compact markup language for attaching click and hover events to specific portions of text. The default markup format is: 


 <action:"argument">visible text</text>
 <action:"arg1"|action2:"arg2">visible text</text>

For example: 


 BaseComponent[] msg = PrismaticAPI
         .multiComponent(
             "<run:\"/spawn\">&aGo to Spawn</text>" +
             " &7| " +
             "<suggest:\"/msg \">&bSend a Message</text>"
         )
         .compile(player);

 player.spigot().sendMessage(msg);

Segments that contain no markup tags are treated as plain text. URLs found in plain segments are automatically wrapped in an OPEN_URL click event.

The setClick* / setHover* / setHoverItem* methods come in two flavors: ones that target only the last segment (matching the behavior of ChatComponent) and ones suffixed with ToAll that apply the event to every segment in the component.

Color continuity is maintained automatically: if a segment does not start with an explicit color code, the last color from the preceding segment is prepended, preventing unexpected color resets between segments.

Since:
1.5.0
See Also:

  • Field Details

    • CLICK_REGEX

      static final String CLICK_REGEX
      Regex fragment that matches all recognized click-action aliases accepted in markup.

      This fragment is incorporated into DEFAULT_REGEX and can be reused by custom ChatFormat implementations that want to extend the default syntax while staying consistent with the recognized action names.

      Recognized aliases include: execute, click, run, run_command, suggest, suggest_command, url, open_url, file, open_file, page, change_page, copy and copy_to_clipboard.

      See Also:

    • DEFAULT_REGEX

      static final String DEFAULT_REGEX
      The default markup regex used by DEFAULT_FORMAT to identify interactive segments.

      A segment matches when it is wrapped in opening and closing tags of the form: 

      
 <action:"argument">text</text>
 <action:"arg1"|action2:"arg2">text</text>

      Recognized opening-tag actions are: hover_item, hover and any alias listed in CLICK_REGEX. The closing tag is always </text>.

      See Also:

    • DEFAULT_FORMAT

      static final ChatFormat<ChatComponent<?>> DEFAULT_FORMAT
      The default ChatFormat instance used when a MultiComponent is created without an explicit format.

      It parses DEFAULT_REGEX markup and wires up the corresponding ChatComponent events. It also implements ChatFormat.toFormattedString(T) so that components can be round-tripped back to markup.

  • Method Details

    • getFormat

      @NotNull @NotNull ChatFormat<ChatComponent<?>> getFormat()
      Returns the ChatFormat used by this component to parse markup and serialize segments back to their string representation.
      Returns:
      the current format; never null

    • setFormat

      @NotNull @NotNull MultiComponent setFormat(@NotNull @NotNull ChatFormat<ChatComponent<?>> format)
      Replaces the ChatFormat used by this component.

      Changing the format does not reparse already-created segments. It only affects how subsequent calls to append(String) parse new text, and how toFormattedString() serializes the component.

      Parameters:
      format - the new format; must not be null
      Returns:
      this component for fluent chaining

    • copy

      @NotNull @NotNull MultiComponent copy()
      Returns a deep copy of this multi-component, including all current segments and the current format.

      Modifying the copy does not affect the original.

      Returns:
      a new MultiComponent with the same segments and format

    • append

      @NotNull @NotNull MultiComponent append(String message)
      Parses the given raw text and appends the resulting segments to this component.

      The text is processed by the current ChatFormat: markup segments are extracted and interactive events are wired up, while plain text spans are kept as-is. URLs in plain spans are automatically turned into ChatComponent.Click.OPEN_URL events.

      Parameters:
      message - the raw text to parse and append
      Returns:
      this component for fluent chaining

    • append

      @NotNull @NotNull MultiComponent append(@NotNull @NotNull ChatComponent<?> component)
      Appends an existing ChatComponent as a new segment at the end of this component.

      The component is not re-parsed; it is added directly. Color continuity is still maintained between the new segment and its predecessor.

      Parameters:
      component - the component to append; must not be null
      Returns:
      this component for fluent chaining

    • append

      @NotNull default @NotNull MultiComponent append(Object object)
      Appends the string representation of an object as a new raw-text segment.

      Equivalent to append(String.valueOf(object)).

      Parameters:
      object - the value whose toString() is appended
      Returns:
      this component for fluent chaining

    • setClickToAll

      @NotNull @NotNull MultiComponent setClickToAll(ChatComponent.Click click, String input)
      Applies a click event to every segment in this component.
      Parameters:
      click - the click action
      input - the click payload
      Returns:
      this component for fluent chaining

    • setClickToAll

      @NotNull default @NotNull MultiComponent setClickToAll(String click, String input)
      Applies a click event to every segment in this component using a string alias.

      The alias is resolved via ChatComponent.Click.fromName(String).

      Parameters:
      click - a case-insensitive click-action alias
      input - the click payload
      Returns:
      this component for fluent chaining

    • setClickToAll

      @NotNull default @NotNull MultiComponent setClickToAll(String input)
      Applies a click event to every segment from a compact "action:payload" string.
      Parameters:
      input - combined action and payload string (e.g. "run:/spawn")
      Returns:
      this component for fluent chaining

    • setHoverToAll

      @NotNull @NotNull MultiComponent setHoverToAll(List<String> list)
      Applies a text hover event to every segment in this component.
      Parameters:
      list - ordered list of hover text lines
      Returns:
      this component for fluent chaining

    • setHoverToAll

      @NotNull default @NotNull MultiComponent setHoverToAll(String... strings)
      Applies a text hover event to every segment in this component.

      Convenience overload for setHoverToAll(List).

      Parameters:
      strings - ordered hover text lines
      Returns:
      this component for fluent chaining

    • setHoverToAll

      @NotNull @NotNull MultiComponent setHoverToAll(String string)
      Applies a text hover event to every segment from a single, optionally multi-line string.

      The string is split into lines using the processor's line-separator regex (default: <n>).

      Parameters:
      string - raw hover content; may contain <n> separators
      Returns:
      this component for fluent chaining

    • setHoverItemToAll

      @NotNull @NotNull MultiComponent setHoverItemToAll(String json)
      Applies an item hover event to every segment in this component.
      Parameters:
      json - raw item JSON or "b64:<base64>" encoded payload
      Returns:
      this component for fluent chaining

    • toFormattedString

      @NotNull default @NotNull String toFormattedString()
      Serializes this component back to its formatted markup string using the current ChatFormat.

      The result can be passed to fromString(String) to reconstruct an equivalent component, making it useful for persistence or network transport.

      Returns:
      the formatted markup string representation of this component

    • setMessage

      @NotNull default @NotNull MultiComponent setMessage(@NotNull @NotNull String message)
      Unsupported — the message of a MultiComponent is derived from its individual segments and cannot be replaced as a single string.
      Specified by:
      setMessage in interface ChatComponent<MultiComponent>
      Parameters:
      message - ignored
      Returns:
      never returns normally
      Throws:
      IllegalStateException - always

    • fromString

      static MultiComponent fromString(ChatProcessor processor, String message)
      Creates a new MultiComponent backed by a custom ChatProcessor.

      The raw message is immediately parsed using DEFAULT_FORMAT.

      Parameters:
      processor - the text processor used to colorize segments and hover content
      message - the initial raw message text, parsed into segments on construction
      Returns:
      a new MultiComponent instance

    • fromString

      static MultiComponent fromString(String message)
      Creates a new MultiComponent backed by the default Prismatic processor.

      This is the recommended factory method for most use cases. The raw message is immediately parsed using DEFAULT_FORMAT.

      Parameters:
      message - the initial raw message text, parsed into segments on construction
      Returns:
      a new MultiComponent instance