diff --git a/api/src/main/java/net/md_5/bungee/api/chat/BaseComponent.java b/api/src/main/java/net/md_5/bungee/api/chat/BaseComponent.java index c94299f5..16cae74d 100644 --- a/api/src/main/java/net/md_5/bungee/api/chat/BaseComponent.java +++ b/api/src/main/java/net/md_5/bungee/api/chat/BaseComponent.java @@ -19,28 +19,61 @@ public abstract class BaseComponent @Setter(AccessLevel.NONE) BaseComponent parent; - //Formatting + /** + * The color of this component and any child + * components (unless overridden) + */ @Getter(AccessLevel.NONE) private ChatColor color; + /** + * Whether this component and any child + * components (unless overridden) is bold + */ @Getter(AccessLevel.NONE) private Boolean bold; + /** + * Whether this component and any child + * components (unless overridden) is italic + */ @Getter(AccessLevel.NONE) private Boolean italic; + /** + * Whether this component and any child + * components (unless overridden) is underlined + */ @Getter(AccessLevel.NONE) private Boolean underlined; + /** + * Whether this component and any child + * components (unless overridden) is strikethrough + */ @Getter(AccessLevel.NONE) private Boolean strikethrough; + /** + * Whether this component and any child + * components (unless overridden) is obfuscated + */ @Getter(AccessLevel.NONE) private Boolean obfuscated; - //Appended components + /** + * Appended components that inherit this component's + * formatting and events + */ private List extra; - //Events + /** + * The action to preform when this component (and + * child components) are clicked + */ private ClickEvent clickEvent; + /** + * The action to preform when this component (and + * child components) are hovered over + */ private HoverEvent hoverEvent; - public BaseComponent(BaseComponent old) + protected BaseComponent(BaseComponent old) { setColor( old.getColorRaw() ); setBold( old.isBoldRaw() ); @@ -50,6 +83,12 @@ public abstract class BaseComponent setObfuscated( old.isObfuscatedRaw() ); } + /** + * Converts the components to a string that uses the + * old formatting codes ({@link net.md_5.bungee.api.ChatColor#COLOR_CHAR} + * @param components the components to convert + * @return the string in the old format + */ public static String toLegacyText(BaseComponent... components) { StringBuilder builder = new StringBuilder(); @@ -60,6 +99,12 @@ public abstract class BaseComponent return builder.toString(); } + /** + * Converts the components into a string without + * any formatting + * @param components the components to convert + * @return the string as plain text + */ public static String toPlainText(BaseComponent... components) { StringBuilder builder = new StringBuilder(); @@ -273,6 +318,11 @@ public abstract class BaseComponent extra.add( component ); } + /** + * Returns whether the component has any formatting + * or events applied to it + * @return + */ public boolean hasFormatting() { return color != null || bold != null || @@ -281,6 +331,12 @@ public abstract class BaseComponent hoverEvent != null || clickEvent != null; } + + /** + * Converts the component into a string without + * any formatting + * @return the string as plain text + */ public String toPlainText() { StringBuilder builder = new StringBuilder(); @@ -299,6 +355,12 @@ public abstract class BaseComponent } } + + /** + * Converts the component to a string that uses the + * old formatting codes ({@link net.md_5.bungee.api.ChatColor#COLOR_CHAR} + * @return the string in the old format + */ public String toLegacyText() { StringBuilder builder = new StringBuilder(); diff --git a/api/src/main/java/net/md_5/bungee/api/chat/ClickEvent.java b/api/src/main/java/net/md_5/bungee/api/chat/ClickEvent.java index e412b23c..23d83ee2 100644 --- a/api/src/main/java/net/md_5/bungee/api/chat/ClickEvent.java +++ b/api/src/main/java/net/md_5/bungee/api/chat/ClickEvent.java @@ -12,19 +12,44 @@ import lombok.Setter; @NoArgsConstructor public class ClickEvent { + /** + * The type of action to preform on click + */ private Action action; + /** + * Depends on action + * @see net.md_5.bungee.api.chat.ClickEvent.Action + */ private String value; public enum Action { + /** + * Open a url at the path given by + * {@link net.md_5.bungee.api.chat.ClickEvent#setValue(String)} + */ OPEN_URL, + /** + * Open a file at the path given by + * {@link net.md_5.bungee.api.chat.ClickEvent#setValue(String)} + */ OPEN_FILE, + /** + * Run the command given by + * {@link net.md_5.bungee.api.chat.ClickEvent#setValue(String)} + */ RUN_COMMAND, + /** + * Inserts the string given by + * {@link net.md_5.bungee.api.chat.ClickEvent#setValue(String)} + * into the players text box + */ SUGGEST_COMMAND } @Override - public String toString() { + public String toString() + { return String.format( "ClickEvent{action=%s, value=%s}", action, value ); } } diff --git a/api/src/main/java/net/md_5/bungee/api/chat/HoverEvent.java b/api/src/main/java/net/md_5/bungee/api/chat/HoverEvent.java index 8f38d338..a1516173 100644 --- a/api/src/main/java/net/md_5/bungee/api/chat/HoverEvent.java +++ b/api/src/main/java/net/md_5/bungee/api/chat/HoverEvent.java @@ -22,7 +22,8 @@ public class HoverEvent } @Override - public String toString() { + public String toString() + { return String.format( "HoverEvent{action=%s, value=%s}", action, value ); } } diff --git a/api/src/main/java/net/md_5/bungee/api/chat/TextComponent.java b/api/src/main/java/net/md_5/bungee/api/chat/TextComponent.java index d4e79706..839e355d 100644 --- a/api/src/main/java/net/md_5/bungee/api/chat/TextComponent.java +++ b/api/src/main/java/net/md_5/bungee/api/chat/TextComponent.java @@ -19,6 +19,12 @@ public class TextComponent extends BaseComponent private static final Pattern url = Pattern.compile( "^(?:(https?)://)?([-\\w_\\.]{2,}\\.[a-z]{2,4})(/\\S*)?$" ); + /** + * Converts the old formatting system that used {@link net.md_5.bungee.api.ChatColor#COLOR_CHAR} + * into the new json based system. + * @param message the text to convert + * @return the components needed to print the message to the client + */ public static BaseComponent[] fromLegacyText(String message) { ArrayList components = new ArrayList<>(); @@ -116,12 +122,21 @@ public class TextComponent extends BaseComponent return components.toArray( new BaseComponent[components.size()] ); } + /** + * The text of the component that will be + * displayed to the client + */ private String text; - public TextComponent(TextComponent old) + /** + * Creates a TextComponent with formatting and text + * from the passed component + * @param textComponent the component to copy from + */ + public TextComponent(TextComponent textComponent) { - super( old ); - setText( old.getText() ); + super( textComponent ); + setText( textComponent.getText() ); } @Override diff --git a/api/src/main/java/net/md_5/bungee/api/chat/TranslatableComponent.java b/api/src/main/java/net/md_5/bungee/api/chat/TranslatableComponent.java index 2730aa2a..9f96b010 100644 --- a/api/src/main/java/net/md_5/bungee/api/chat/TranslatableComponent.java +++ b/api/src/main/java/net/md_5/bungee/api/chat/TranslatableComponent.java @@ -17,12 +17,28 @@ import java.util.regex.Pattern; @NoArgsConstructor public class TranslatableComponent extends BaseComponent { - public final ResourceBundle locales = ResourceBundle.getBundle( "mojang-translations/en_US" ); + private final ResourceBundle locales = ResourceBundle.getBundle( "mojang-translations/en_US" ); private final Pattern format = Pattern.compile( "%(?:(\\d+)\\$)?([A-Za-z%]|$)" ); + /** + * The key into the Minecraft locale files to use for the + * translation. The text depends on the client's locale setting. + * The console is always en_US + */ private String translate; + /** + * The components to substitute into the translation + */ private List with; + /** + * Creates a translatable component with the passed substitutions + * @see #setTranslate(String) + * @see #setWith(java.util.List) + * @param translate the translation key + * @param with the {@link java.lang.String}s and {@link net.md_5.bungee.api.chat.BaseComponent}s + * to use into the translation + */ public TranslatableComponent(String translate, Object... with) { setTranslate( translate ); @@ -40,6 +56,12 @@ public class TranslatableComponent extends BaseComponent setWith( temp ); } + /** + * Sets the translation substitutions to be used in + * this component. Removes any previously set + * substitutions + * @param components the components to substitute + */ public void setWith(List components) { for ( BaseComponent component : components ) @@ -49,6 +71,33 @@ public class TranslatableComponent extends BaseComponent with = components; } + /** + * Adds a text substitution to the component. The text will + * inherit this component's formatting + * + * @param text the text to substitute + */ + public void addWith(String text) + { + addWith( new TextComponent( text ) ); + } + + /** + * Adds a component substitution to the component. The text will + * inherit this component's formatting + * + * @param component the component to substitute + */ + public void addWith(BaseComponent component) + { + if ( with == null ) + { + with = new ArrayList<>(); + } + component.parent = this; + with.add( component ); + } + @Override protected void toPlainText(StringBuilder builder) {