diff --git a/dialog/src/main/java/net/md_5/bungee/api/dialog/DialogListDialog.java b/dialog/src/main/java/net/md_5/bungee/api/dialog/DialogListDialog.java index 2f8bfa18..9fb9cc2b 100644 --- a/dialog/src/main/java/net/md_5/bungee/api/dialog/DialogListDialog.java +++ b/dialog/src/main/java/net/md_5/bungee/api/dialog/DialogListDialog.java @@ -35,7 +35,7 @@ public final class DialogListDialog implements Dialog */ private int columns; /** - * The width of the dialog buttons (default: 150). + * The width of the dialog buttons (default: 150, minimum: 1, maximum: 1024). */ @SerializedName("button_width") private int buttonWidth; diff --git a/dialog/src/main/java/net/md_5/bungee/api/dialog/ServerLinksDialog.java b/dialog/src/main/java/net/md_5/bungee/api/dialog/ServerLinksDialog.java index f3e2651c..e1ab54a9 100644 --- a/dialog/src/main/java/net/md_5/bungee/api/dialog/ServerLinksDialog.java +++ b/dialog/src/main/java/net/md_5/bungee/api/dialog/ServerLinksDialog.java @@ -31,7 +31,7 @@ public final class ServerLinksDialog implements Dialog */ private int columns; /** - * The width of the dialog buttons (default: 150). + * The width of the dialog buttons (default: 150, minimum: 1, maximum: 1024). */ @SerializedName("button_width") private int buttonWidth; diff --git a/dialog/src/main/java/net/md_5/bungee/api/dialog/action/DialogAction.java b/dialog/src/main/java/net/md_5/bungee/api/dialog/action/DialogAction.java index 7f0ae94b..36208aed 100644 --- a/dialog/src/main/java/net/md_5/bungee/api/dialog/action/DialogAction.java +++ b/dialog/src/main/java/net/md_5/bungee/api/dialog/action/DialogAction.java @@ -21,7 +21,7 @@ public class DialogAction */ private BaseComponent tooltip; /** - * The width of the button (default: 150). + * The width of the button (default: 150, minimum: 1, maximum: 1024). */ private int width; diff --git a/dialog/src/main/java/net/md_5/bungee/api/dialog/body/PlainMessageBody.java b/dialog/src/main/java/net/md_5/bungee/api/dialog/body/PlainMessageBody.java index 6d710273..e92e5f9b 100644 --- a/dialog/src/main/java/net/md_5/bungee/api/dialog/body/PlainMessageBody.java +++ b/dialog/src/main/java/net/md_5/bungee/api/dialog/body/PlainMessageBody.java @@ -20,7 +20,7 @@ public class PlainMessageBody extends DialogBody */ private BaseComponent contents; /** - * The maximum width (default: 200). + * The maximum width (default: 200, minimum: 1, maximum: 1024). */ private int width; diff --git a/dialog/src/main/java/net/md_5/bungee/api/dialog/chat/package-info.java b/dialog/src/main/java/net/md_5/bungee/api/dialog/chat/package-info.java new file mode 100644 index 00000000..afb6b906 --- /dev/null +++ b/dialog/src/main/java/net/md_5/bungee/api/dialog/chat/package-info.java @@ -0,0 +1,4 @@ +/** + * Contains dialog extensions to the chat API. + */ +package net.md_5.bungee.api.dialog.chat; diff --git a/dialog/src/main/java/net/md_5/bungee/api/dialog/input/BooleanInput.java b/dialog/src/main/java/net/md_5/bungee/api/dialog/input/BooleanInput.java index 4ffecd2f..be9e15a4 100644 --- a/dialog/src/main/java/net/md_5/bungee/api/dialog/input/BooleanInput.java +++ b/dialog/src/main/java/net/md_5/bungee/api/dialog/input/BooleanInput.java @@ -7,6 +7,9 @@ import lombok.ToString; import lombok.experimental.Accessors; import net.md_5.bungee.api.chat.BaseComponent; +/** + * Represents a checkbox input control. + */ @Data @Accessors(fluent = true) @ToString(callSuper = true) @@ -14,10 +17,22 @@ import net.md_5.bungee.api.chat.BaseComponent; public class BooleanInput extends DialogInput { + /** + * The input label. + */ private BaseComponent label; + /** + * The initial value (default: false/unchecked). + */ private boolean initial; + /** + * The string value to be submitted when true/checked (default: "true"). + */ @SerializedName("on_true") private String onTrue; + /** + * The string value to be submitted when false/unchecked (default: "false"). + */ @SerializedName("on_false") private String onFalse; diff --git a/dialog/src/main/java/net/md_5/bungee/api/dialog/input/DialogInput.java b/dialog/src/main/java/net/md_5/bungee/api/dialog/input/DialogInput.java index ecf4880e..b1878e10 100644 --- a/dialog/src/main/java/net/md_5/bungee/api/dialog/input/DialogInput.java +++ b/dialog/src/main/java/net/md_5/bungee/api/dialog/input/DialogInput.java @@ -2,12 +2,25 @@ package net.md_5.bungee.api.dialog.input; import lombok.Data; import lombok.experimental.Accessors; +import org.jetbrains.annotations.ApiStatus; +/** + * Represents a type of input which may be displayed/submitted with a form + * dialog. + */ @Data @Accessors(fluent = true) public class DialogInput { + /** + * The internal input type. + */ + @ApiStatus.Internal private final String type; + /** + * The key corresponding to this input and associated with the value + * submitted. + */ private final String key; } diff --git a/dialog/src/main/java/net/md_5/bungee/api/dialog/input/InputOption.java b/dialog/src/main/java/net/md_5/bungee/api/dialog/input/InputOption.java index ae15f5c6..ba7ce86b 100644 --- a/dialog/src/main/java/net/md_5/bungee/api/dialog/input/InputOption.java +++ b/dialog/src/main/java/net/md_5/bungee/api/dialog/input/InputOption.java @@ -5,14 +5,29 @@ import lombok.Data; import lombok.experimental.Accessors; import net.md_5.bungee.api.chat.BaseComponent; +/** + * Represents an option choice which may form part of a + * {@link SingleOptionInput}. + */ @Data @AllArgsConstructor @Accessors(fluent = true) public class InputOption { + /** + * The string value associated with this option, to be submitted when + * selected. + */ private String id; + /** + * The text to display for this option. + */ private BaseComponent display; + /** + * Whether this option is the one initially selected. Only one option may + * have this value as true (default: first option). + */ private boolean initial; public InputOption(String id) diff --git a/dialog/src/main/java/net/md_5/bungee/api/dialog/input/NumberRangeInput.java b/dialog/src/main/java/net/md_5/bungee/api/dialog/input/NumberRangeInput.java index 4194864b..9eb5ad77 100644 --- a/dialog/src/main/java/net/md_5/bungee/api/dialog/input/NumberRangeInput.java +++ b/dialog/src/main/java/net/md_5/bungee/api/dialog/input/NumberRangeInput.java @@ -6,6 +6,9 @@ import lombok.ToString; import lombok.experimental.Accessors; import net.md_5.bungee.api.chat.BaseComponent; +/** + * Represents a number slider input. + */ @Data @Accessors(fluent = true) @ToString(callSuper = true) @@ -14,28 +17,33 @@ public class NumberRangeInput extends DialogInput { /** - * The width of the input (default 200) + * The width of the input (default: 200, minimum: 1, maximum: 1024). */ private int width; /** - * The label of the slider + * The label of the slider. */ private BaseComponent label; + /** + * A translate key used to display the label value (default: + * options.generic_value). + */ private String labelFormat; /** - * The start position of the slider (leftmost position) + * The start position of the slider (leftmost position). */ private float start; /** - * The end position of the slider (rightmost position) + * The end position of the slider (rightmost position). */ private float end; /** - * The steps in which the input will be increased or decreased, or null if no specific steps + * The steps in which the input will be increased or decreased, or null if + * no specific steps. */ private Float step; /** - * The initial value of number input, or null to fall back to the middle + * The initial value of number input, or null to fall back to the middle. */ private Float initial; diff --git a/dialog/src/main/java/net/md_5/bungee/api/dialog/input/SingleOptionInput.java b/dialog/src/main/java/net/md_5/bungee/api/dialog/input/SingleOptionInput.java index 0f92ffa4..54c6159d 100644 --- a/dialog/src/main/java/net/md_5/bungee/api/dialog/input/SingleOptionInput.java +++ b/dialog/src/main/java/net/md_5/bungee/api/dialog/input/SingleOptionInput.java @@ -1,5 +1,6 @@ package net.md_5.bungee.api.dialog.input; +import com.google.common.base.Preconditions; import com.google.gson.annotations.SerializedName; import java.util.Arrays; import java.util.List; @@ -9,6 +10,9 @@ import lombok.ToString; import lombok.experimental.Accessors; import net.md_5.bungee.api.chat.BaseComponent; +/** + * Represents a single option (dropdown) input. + */ @Data @Accessors(fluent = true) @ToString(callSuper = true) @@ -16,10 +20,22 @@ import net.md_5.bungee.api.chat.BaseComponent; public class SingleOptionInput extends DialogInput { + /** + * The width of the input (default: 200, minimum: 1, maximum: 1024). + */ private int width; + /** + * The input label. + */ private BaseComponent label; + /** + * Whether the label is visible (default: true). + */ @SerializedName("label_visible") private boolean labelVisible; + /** + * The non-empty list of options to be selected from. + */ private List options; public SingleOptionInput(String key, BaseComponent label, InputOption... options) @@ -30,6 +46,8 @@ public class SingleOptionInput extends DialogInput public SingleOptionInput(String key, int width, BaseComponent label, boolean labelVisible, List options) { super( "minecraft:single_option", key ); + Preconditions.checkArgument( options != null && !options.isEmpty(), "At least one option must be provided" ); + this.width = width; this.label = label; this.labelVisible = labelVisible; diff --git a/dialog/src/main/java/net/md_5/bungee/api/dialog/input/TextInput.java b/dialog/src/main/java/net/md_5/bungee/api/dialog/input/TextInput.java index d13ebfb0..399e7340 100644 --- a/dialog/src/main/java/net/md_5/bungee/api/dialog/input/TextInput.java +++ b/dialog/src/main/java/net/md_5/bungee/api/dialog/input/TextInput.java @@ -7,6 +7,9 @@ import lombok.ToString; import lombok.experimental.Accessors; import net.md_5.bungee.api.chat.BaseComponent; +/** + * Represents a textbox input. + */ @Data @Accessors(fluent = true) @ToString(callSuper = true) @@ -15,26 +18,29 @@ public class TextInput extends DialogInput { /** - * The width of this text input + * The width of this text input (default: 200, minimum: 1, maximum: 1024). */ private int width; /** - * The label of this text input + * The label of this text input. */ private BaseComponent label; /** - * The visibility of this text inputs label + * The visibility of this text input's label. */ @SerializedName("label_visible") private boolean labelVisible; /** - * The initial value of this text input + * The initial value of this text input. */ private String initial; + /** + * The maximum length of the input (default: 32). + */ @SerializedName("max_length") private int maxLength; /** - * if set, allows users to input multiple lines + * If present, allows users to input multiple lines. */ private Multiline multiline; @@ -59,19 +65,21 @@ public class TextInput extends DialogInput this.multiline = multiline; } + /** + * Configuration data for a multiline input. + */ @Data @Accessors(fluent = true) - @ToString(callSuper = true) - @EqualsAndHashCode(callSuper = false) public static class Multiline { + /** - * The maximum length of input, or null to disable any limits + * The maximum length of input, or null to disable any limits. */ @SerializedName("max_lines") private Integer maxLines; /** - * The height of this input, default value is 32 + * The height of this input (default: 32, minimum: 1, maximum: 512). */ private Integer height = 32; } diff --git a/dialog/src/main/java/net/md_5/bungee/api/dialog/input/package-info.java b/dialog/src/main/java/net/md_5/bungee/api/dialog/input/package-info.java new file mode 100644 index 00000000..235b307c --- /dev/null +++ b/dialog/src/main/java/net/md_5/bungee/api/dialog/input/package-info.java @@ -0,0 +1,4 @@ +/** + * Represents the various input controls which may be present on form dialogs. + */ +package net.md_5.bungee.api.dialog.input; diff --git a/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/CommandTemplateSubmission.java b/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/CommandTemplateSubmission.java index 9ba076fc..1f05cd92 100644 --- a/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/CommandTemplateSubmission.java +++ b/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/CommandTemplateSubmission.java @@ -5,6 +5,10 @@ import lombok.EqualsAndHashCode; import lombok.ToString; import lombok.experimental.Accessors; +/** + * Executes a command on form submission. If the command requires a permission + * higher than 0, a confirmation dialog will be shown by the client. + */ @Data @Accessors(fluent = true) @ToString(callSuper = true) @@ -12,6 +16,14 @@ import lombok.experimental.Accessors; public class CommandTemplateSubmission extends DialogSubmission { + /** + * The template to be applied, where variables of the form + * $(key) will be replaced by their + * {@link net.md_5.bungee.api.dialog.input.DialogInput#key} value. + *
+ * The action key is special and will be replaced with the + * {@link net.md_5.bungee.api.dialog.action.DialogSubmitAction#id}. + */ private String template; public CommandTemplateSubmission(String template) diff --git a/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/CustomFormSubmission.java b/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/CustomFormSubmission.java index fa0fd2ce..0e0e4505 100644 --- a/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/CustomFormSubmission.java +++ b/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/CustomFormSubmission.java @@ -5,6 +5,9 @@ import lombok.EqualsAndHashCode; import lombok.ToString; import lombok.experimental.Accessors; +/** + * Submits the form with the given ID and all values as a payload. + */ @Data @Accessors(fluent = true) @ToString(callSuper = true) @@ -12,6 +15,9 @@ import lombok.experimental.Accessors; public class CustomFormSubmission extends DialogSubmission { + /** + * The namespaced key of the submission. + */ private String id; public CustomFormSubmission(String id) diff --git a/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/CustomTemplateSubmission.java b/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/CustomTemplateSubmission.java index 3013825c..4f9a5dd7 100644 --- a/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/CustomTemplateSubmission.java +++ b/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/CustomTemplateSubmission.java @@ -5,6 +5,10 @@ import lombok.EqualsAndHashCode; import lombok.ToString; import lombok.experimental.Accessors; +/** + * Submits the form with the given ID and a single payload specified by the + * template. + */ @Data @Accessors(fluent = true) @ToString(callSuper = true) @@ -12,7 +16,18 @@ import lombok.experimental.Accessors; public class CustomTemplateSubmission extends DialogSubmission { + /** + * The namespaced key of the submission. + */ private String id; + /** + * The template to be applied, where variables of the form + * $(key) will be replaced by their + * {@link net.md_5.bungee.api.dialog.input.DialogInput#key} value. + *
+ * The action key is special and will be replaced with the + * {@link net.md_5.bungee.api.dialog.action.DialogSubmitAction#id}. + */ private String template; public CustomTemplateSubmission(String id, String template) diff --git a/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/DialogSubmission.java b/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/DialogSubmission.java index 81cbb6c3..056faacd 100644 --- a/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/DialogSubmission.java +++ b/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/DialogSubmission.java @@ -2,11 +2,19 @@ package net.md_5.bungee.api.dialog.submit; import lombok.Data; import lombok.experimental.Accessors; +import org.jetbrains.annotations.ApiStatus; +/** + * Represents an action which may be taken on form dialog submission. + */ @Data @Accessors(fluent = true) public class DialogSubmission { + /** + * The internal submissions type. + */ + @ApiStatus.Internal private final String type; } diff --git a/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/package-info.java b/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/package-info.java new file mode 100644 index 00000000..4ec5cb6d --- /dev/null +++ b/dialog/src/main/java/net/md_5/bungee/api/dialog/submit/package-info.java @@ -0,0 +1,4 @@ +/** + * Represents the various submissions actions of form dialogs. + */ +package net.md_5.bungee.api.dialog.submit;