mkremins.fanciful

Class FancyMessage

java.lang.Object

mkremins.fanciful.FancyMessage

All Implemented Interfaces:

java.lang.Cloneable, java.lang.Iterable<MessagePart>, org.bukkit.configuration.serialization.ConfigurationSerializable

public class FancyMessage
extends java.lang.Object
implements java.lang.Cloneable, java.lang.Iterable<MessagePart>, org.bukkit.configuration.serialization.ConfigurationSerializable

Represents a formattable message. Such messages can use elements such as colors, formatting codes, hover and click data, and other features provided by the vanilla Minecraft JSON message formatter. This class allows plugins to emulate the functionality of the vanilla Minecraft tellraw command.

This class follows the builder pattern, allowing for method chaining. It is set up such that invocations of property-setting methods will affect the current editing component, and a call to then() or then(String) will append a new editing component to the end of the message, optionally initializing it with text. Further property-setting method calls will affect that editing component.

Constructor Summary

Constructors

Constructor and Description
FancyMessage() Creates a JSON message without text.
FancyMessage(java.lang.String firstPartText) Creates a JSON message with text.
FancyMessage(TextualComponent firstPartText)

Method Summary

Modifier and Type	Method and Description
FancyMessage	achievementTooltip(java.lang.String name) Set the behavior of the current editing component to display information about an achievement when the client hovers over the text.
FancyMessage	clone()
FancyMessage	color(org.bukkit.ChatColor color) Sets the color of the current editing component to a value.
FancyMessage	command(java.lang.String command) Set the behavior of the current editing component to instruct the client to send the specified string to the server as a chat message when the currently edited part of the FancyMessage is clicked.
static FancyMessage	deserialize(java.util.Map<java.lang.String,java.lang.Object> serialized) Deserializes a JSON-represented message from a mapping of key-value pairs.
static FancyMessage	deserialize(java.lang.String json) Deserializes a fancy message from its JSON representation.
FancyMessage	file(java.lang.String path) Set the behavior of the current editing component to instruct the client to open a file on the client side filesystem when the currently edited part of the FancyMessage is clicked.
FancyMessage	formattedTooltip(FancyMessage... lines) Set the behavior of the current editing component to display the specified lines of formatted text when the client hovers over the text.
FancyMessage	formattedTooltip(FancyMessage text) Set the behavior of the current editing component to display formatted text when the client hovers over the text.
FancyMessage	formattedTooltip(java.lang.Iterable<FancyMessage> lines) Set the behavior of the current editing component to display the specified lines of formatted text when the client hovers over the text.
FancyMessage	insert(java.lang.String command) Set the behavior of the current editing component to instruct the client to append the chat input box content with the specified string when the currently edited part of the FancyMessage is SHIFT-CLICKED.
java.util.Iterator<MessagePart>	iterator() Internally called method.
FancyMessage	link(java.lang.String url) Set the behavior of the current editing component to instruct the client to open a webpage in the client's web browser when the currently edited part of the FancyMessage is clicked.
void	send(org.bukkit.command.CommandSender sender) Sends this message to a command sender.
void	send(java.lang.Iterable<? extends org.bukkit.command.CommandSender> senders) Sends this message to multiple command senders.
void	send(org.bukkit.entity.Player player) Sends this message to a player.
java.util.Map<java.lang.String,java.lang.Object>	serialize()
FancyMessage	style(org.bukkit.ChatColor... styles) Sets the stylization of the current editing component.
FancyMessage	suggest(java.lang.String command) Set the behavior of the current editing component to instruct the client to replace the chat input box content with the specified string when the currently edited part of the FancyMessage is clicked.
FancyMessage	text(java.lang.String text) Sets the text of the current editing component to a value.
FancyMessage	text(TextualComponent text) Sets the text of the current editing component to a value.
FancyMessage	then() Terminate construction of the current editing component, and begin construction of a new message component.
FancyMessage	then(java.lang.String text) Terminate construction of the current editing component, and begin construction of a new message component.
FancyMessage	then(TextualComponent text) Terminate construction of the current editing component, and begin construction of a new message component.
java.lang.String	toJSONString() Serialize this fancy message, converting it into syntactically-valid JSON using a JsonWriter.
java.lang.String	toOldMessageFormat() Convert this message to a human-readable string with limited formatting.
FancyMessage	tooltip(java.lang.Iterable<java.lang.String> lines) Set the behavior of the current editing component to display raw text when the client hovers over the text.
FancyMessage	tooltip(java.lang.String... lines) Set the behavior of the current editing component to display raw text when the client hovers over the text.
FancyMessage	tooltip(java.lang.String text) Set the behavior of the current editing component to display raw text when the client hovers over the text.
FancyMessage	translationReplacements(FancyMessage... replacements) If the text is a translatable key, and it has replaceable values, this function can be used to set the replacements that will be used in the message.
FancyMessage	translationReplacements(java.lang.Iterable<FancyMessage> replacements) If the text is a translatable key, and it has replaceable values, this function can be used to set the replacements that will be used in the message.
FancyMessage	translationReplacements(java.lang.String... replacements) If the text is a translatable key, and it has replaceable values, this function can be used to set the replacements that will be used in the message.
void	writeJson(JsonWriter writer) Writes the JSON representation of this object to the specified writer.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

FancyMessage

public FancyMessage(java.lang.String firstPartText)

Creates a JSON message with text.

Parameters:

firstPartText - The existing text in the message.

FancyMessage

public FancyMessage(TextualComponent firstPartText)

FancyMessage

public FancyMessage()

Creates a JSON message without text.

Method Detail

clone

public FancyMessage clone()
                   throws java.lang.CloneNotSupportedException

Overrides:

clone in class java.lang.Object

Throws:

java.lang.CloneNotSupportedException

text

public FancyMessage text(java.lang.String text)

Sets the text of the current editing component to a value.

Parameters:

text - The new text of the current editing component.

Returns:

This builder instance.

text

public FancyMessage text(TextualComponent text)

Sets the text of the current editing component to a value.

Parameters:

text - The new text of the current editing component.

Returns:

This builder instance.

color

public FancyMessage color(org.bukkit.ChatColor color)

Sets the color of the current editing component to a value.

Parameters:

color - The new color of the current editing component.

Returns:

This builder instance.

Throws:

java.lang.IllegalArgumentException - If the specified ChatColor enumeration value is not a color (but a format value).

style

public FancyMessage style(org.bukkit.ChatColor... styles)

Sets the stylization of the current editing component.

Parameters:

styles - The array of styles to apply to the editing component.

Returns:

This builder instance.

Throws:

java.lang.IllegalArgumentException - If any of the enumeration values in the array do not represent formatters.

file

public FancyMessage file(java.lang.String path)

Set the behavior of the current editing component to instruct the client to open a file on the client side filesystem when the currently edited part of the FancyMessage is clicked.

Parameters:

path - The path of the file on the client filesystem.

Returns:

This builder instance.

link

public FancyMessage link(java.lang.String url)

Set the behavior of the current editing component to instruct the client to open a webpage in the client's web browser when the currently edited part of the FancyMessage is clicked.

Parameters:

url - The URL of the page to open when the link is clicked.

Returns:

This builder instance.

suggest

public FancyMessage suggest(java.lang.String command)

Set the behavior of the current editing component to instruct the client to replace the chat input box content with the specified string when the currently edited part of the FancyMessage is clicked. The client will not immediately send the command to the server to be executed unless the client player submits the command/chat message, usually with the enter key.

Parameters:

command - The text to display in the chat bar of the client.

Returns:

This builder instance.

insert

public FancyMessage insert(java.lang.String command)

Set the behavior of the current editing component to instruct the client to append the chat input box content with the specified string when the currently edited part of the FancyMessage is SHIFT-CLICKED. The client will not immediately send the command to the server to be executed unless the client player submits the command/chat message, usually with the enter key.

Parameters:

command - The text to append to the chat bar of the client.

Returns:

This builder instance.

command

public FancyMessage command(java.lang.String command)

Set the behavior of the current editing component to instruct the client to send the specified string to the server as a chat message when the currently edited part of the FancyMessage is clicked. The client will immediately send the command to the server to be executed when the editing component is clicked.

Parameters:

command - The text to display in the chat bar of the client.

Returns:

This builder instance.

achievementTooltip

public FancyMessage achievementTooltip(java.lang.String name)

Set the behavior of the current editing component to display information about an achievement when the client hovers over the text.

Tooltips do not inherit display characteristics, such as color and styles, from the message component on which they are applied.

Parameters:

name - The name of the achievement to display, excluding the "achievement." prefix.

Returns:

This builder instance.

tooltip

public FancyMessage tooltip(java.lang.String text)

Set the behavior of the current editing component to display raw text when the client hovers over the text.

Tooltips do not inherit display characteristics, such as color and styles, from the message component on which they are applied.

Parameters:

text - The text, which supports newlines, which will be displayed to the client upon hovering.

Returns:

This builder instance.

tooltip

public FancyMessage tooltip(java.lang.Iterable<java.lang.String> lines)

Set the behavior of the current editing component to display raw text when the client hovers over the text.

Tooltips do not inherit display characteristics, such as color and styles, from the message component on which they are applied.

Parameters:

lines - The lines of text which will be displayed to the client upon hovering. The iteration order of this object will be the order in which the lines of the tooltip are created.

Returns:

This builder instance.

tooltip

public FancyMessage tooltip(java.lang.String... lines)

Set the behavior of the current editing component to display raw text when the client hovers over the text.

Tooltips do not inherit display characteristics, such as color and styles, from the message component on which they are applied.

Parameters:

lines - The lines of text which will be displayed to the client upon hovering.

Returns:

This builder instance.

formattedTooltip

public FancyMessage formattedTooltip(FancyMessage text)

Set the behavior of the current editing component to display formatted text when the client hovers over the text.

Tooltips do not inherit display characteristics, such as color and styles, from the message component on which they are applied.

Parameters:

text - The formatted text which will be displayed to the client upon hovering.

Returns:

This builder instance.

formattedTooltip

public FancyMessage formattedTooltip(FancyMessage... lines)

Set the behavior of the current editing component to display the specified lines of formatted text when the client hovers over the text.

Tooltips do not inherit display characteristics, such as color and styles, from the message component on which they are applied.

Parameters:

lines - The lines of formatted text which will be displayed to the client upon hovering.

Returns:

This builder instance.

formattedTooltip

public FancyMessage formattedTooltip(java.lang.Iterable<FancyMessage> lines)

Set the behavior of the current editing component to display the specified lines of formatted text when the client hovers over the text.

Tooltips do not inherit display characteristics, such as color and styles, from the message component on which they are applied.

Parameters:

lines - The lines of text which will be displayed to the client upon hovering. The iteration order of this object will be the order in which the lines of the tooltip are created.

Returns:

This builder instance.

translationReplacements

public FancyMessage translationReplacements(java.lang.String... replacements)

If the text is a translatable key, and it has replaceable values, this function can be used to set the replacements that will be used in the message.

Parameters:

replacements - The replacements, in order, that will be used in the language-specific message.

Returns:

This builder instance.

translationReplacements

public FancyMessage translationReplacements(FancyMessage... replacements)

If the text is a translatable key, and it has replaceable values, this function can be used to set the replacements that will be used in the message.

Parameters:

replacements - The replacements, in order, that will be used in the language-specific message.

Returns:

This builder instance.

translationReplacements

public FancyMessage translationReplacements(java.lang.Iterable<FancyMessage> replacements)

If the text is a translatable key, and it has replaceable values, this function can be used to set the replacements that will be used in the message.

Parameters:

replacements - The replacements, in order, that will be used in the language-specific message.

Returns:

This builder instance.

then

public FancyMessage then(java.lang.String text)

Terminate construction of the current editing component, and begin construction of a new message component. After a successful call to this method, all setter methods will refer to a new message component, created as a result of the call to this method.

Parameters:

text - The text which will populate the new message component.

Returns:

This builder instance.

then

public FancyMessage then(TextualComponent text)

Terminate construction of the current editing component, and begin construction of a new message component. After a successful call to this method, all setter methods will refer to a new message component, created as a result of the call to this method.

Parameters:

text - The text which will populate the new message component.

Returns:

This builder instance.

then

public FancyMessage then()

Terminate construction of the current editing component, and begin construction of a new message component. After a successful call to this method, all setter methods will refer to a new message component, created as a result of the call to this method.

Returns:

This builder instance.

writeJson

public void writeJson(JsonWriter writer)
               throws java.io.IOException

Writes the JSON representation of this object to the specified writer.

Parameters:

writer - The JSON writer which will receive the object.

Throws:

java.io.IOException - If an error occurs writing to the stream.

toJSONString

public java.lang.String toJSONString()

Serialize this fancy message, converting it into syntactically-valid JSON using a JsonWriter. This JSON should be compatible with vanilla formatter commands such as /tellraw.

Returns:

The JSON string representing this object.

send

public void send(org.bukkit.entity.Player player)

Sends this message to a player. The player will receive the fully-fledged formatted display of this message.

Parameters:

player - The player who will receive the message.

send

public void send(org.bukkit.command.CommandSender sender)

Sends this message to a command sender. If the sender is a player, they will receive the fully-fledged formatted display of this message. Otherwise, they will receive a version of this message with less formatting.

Parameters:

sender - The command sender who will receive the message.

See Also:

toOldMessageFormat()

send

public void send(java.lang.Iterable<? extends org.bukkit.command.CommandSender> senders)

Sends this message to multiple command senders.

Parameters:

senders - The command senders who will receive the message.

See Also:

send(CommandSender)

toOldMessageFormat

public java.lang.String toOldMessageFormat()

Convert this message to a human-readable string with limited formatting. This method is used to send this message to clients without JSON formatting support.

Serialization of this message by using this message will include (in this order for each message part):

1. The color of each message part.
2. The applicable stylizations for each message part.
3. The core text of the message part.

The primary omissions are tooltips and clickable actions. Consequently, this method should be used only as a last resort.

Color and formatting can be removed from the returned string by using ChatColor.stripColor(String).

Returns:

A human-readable string representing limited formatting in addition to the core text of this message.

serialize

public java.util.Map<java.lang.String,java.lang.Object> serialize()

Specified by:

serialize in interface org.bukkit.configuration.serialization.ConfigurationSerializable

deserialize

public static FancyMessage deserialize(java.util.Map<java.lang.String,java.lang.Object> serialized)

Deserializes a JSON-represented message from a mapping of key-value pairs. This is called by the Bukkit serialization API. It is not intended for direct public API consumption.

Parameters:

serialized - The key-value mapping which represents a fancy message.

iterator

public java.util.Iterator<MessagePart> iterator()

Internally called method. Not for API consumption.

Specified by:

iterator in interface java.lang.Iterable<MessagePart>

deserialize

public static FancyMessage deserialize(java.lang.String json)
                                throws java.io.IOException

Deserializes a fancy message from its JSON representation. This JSON representation is of the format of that returned by toJSONString(), and is compatible with vanilla inputs.

Parameters:

json - The JSON string which represents a fancy message.

Returns:

A FancyMessage representing the parameterized JSON message.

Throws:

java.io.IOException