diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/Configurable.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/Configurable.java
index a55ed87..125a3d9 100644
--- a/flare/core/src/main/java/space/maxus/flare/ui/compose/Configurable.java
+++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/Configurable.java
@@ -2,15 +2,30 @@
import org.jetbrains.annotations.NotNull;
+/**
+ * Represents a composable that can be further configured after creation
+ * @param <S> The type of the object being configured
+ */
public interface Configurable<S> {
+ /**
+ * Configures this composable element.
+ * @param configurator Configurator to be applied
+ * @return The configured object
+ */
S configure(Configurator<S> configurator);
+ /**
+ * Configures this composable element with a certain subtype of the object.
+ * @param configurator Configurator to be applied
+ * @return The configured objecc
+ * @param <V> The subtype of the object
+ */
@SuppressWarnings("unchecked")
default <V extends S> V configureTyped(@NotNull Configurator<V> configurator) {
configurator.configure((V) this);
return (V) this;
}
-
+
interface Configurator<S> {
void configure(S self);
}
diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/ContainerSlot.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/ContainerSlot.java
index 6af367e..b1326a4 100644
--- a/flare/core/src/main/java/space/maxus/flare/ui/compose/ContainerSlot.java
+++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/ContainerSlot.java
@@ -13,7 +13,18 @@
import space.maxus.flare.ui.Composable;
import space.maxus.flare.ui.ComposableLike;
+/**
+ * ContainerSlot is a component that can have an item placed in it.
+ * <br />
+ * See more in Flare docs: <a href="https://flare.maxus.space/ui/composable#containerslot">Container Slot</a>
+ */
public interface ContainerSlot extends Configurable<ContainerSlot>, Composable, Disable {
+ /**
+ * Returns item builder for empty container slot item
+ * @param name Extra message in item name
+ * @param description Extra description
+ * @return Item builder for empty container slot item
+ */
static ItemStackBuilder emptyBuilder(@Nullable String name, @Nullable String description) {
return Items.builder(Material.LIGHT_GRAY_STAINED_GLASS_PANE)
.hideAllFlags()
@@ -23,44 +34,114 @@ static ItemStackBuilder emptyBuilder(@Nullable String name, @Nullable String des
.addLoreLine("<dark_gray>Click with item to put it here");
}
+ /**
+ * Returns item provider for empty container slot item
+ * @param name Extra message in item name
+ * @param description Extra description
+ * @return Item provider for empty container slot item
+ */
@Contract("_, _ -> new")
static @NotNull ItemProvider emptyItem(@Nullable String name, @Nullable String description) {
return ItemProvider.still(emptyBuilder(name, description).build());
}
+ /**
+ * Constructs a new container slot with handlers
+ * @param onPut Put handler
+ * @param onTake Take handler
+ * @return New container slot with handlers
+ */
static @NotNull ContainerSlot of(@NotNull ContainerEvent onPut, @NotNull ContainerEvent onTake) {
return new ContainerSlotImpl(null, emptyItem(null, null), false, (a, b) -> true, (a, b) -> true, onPut, onTake);
}
+ /**
+ * Constructs a new container slot builder
+ * @return New container slot builder
+ */
static @NotNull Builder builder() {
return new ContainerSlotImpl.Builder();
}
+ /**
+ * Returns the reactive state of an item inside this container
+ * @return Reactive state of an item inside this container
+ */
ReactiveState<ItemStack> itemState();
+ /**
+ * Gets the item inside this container
+ * @return Item inside this container
+ */
default @Nullable ItemStack getItem() {
return itemState().get();
}
+ /**
+ * Sets the item inside this container
+ * @param stack Item inside this container
+ */
default void setItem(@Nullable ItemStack stack) {
itemState().set(stack);
}
+ /**
+ * Builder for ContainerSlot
+ */
interface Builder extends ComposableLike {
+ /**
+ * Makes the container disabled
+ * @param disabled Disabled state
+ * @return This builder
+ */
Builder disabled(boolean disabled);
+ /**
+ * Sets the empty item provider for this container
+ * @param provider The empty item provider
+ * @return This builder
+ */
Builder empty(@Nullable ItemProvider provider);
+ /**
+ * Sets the item inside this container
+ * @param item The item to be set
+ * @return This builder
+ */
Builder item(@Nullable ItemStack item);
+ /**
+ * Sets the put handler for this container
+ * @param put Put handler
+ * @return This builder
+ */
Builder onPut(ContainerEvent put);
+ /**
+ * Sets the take handler for this container
+ * @param take Take handler
+ * @return This builder
+ */
Builder onTake(ContainerEvent take);
+ /**
+ * Sets the put filter for this container
+ * @param put Put filter
+ * @return This builder
+ */
Builder filterPut(ContainerPredicate put);
+ /**
+ * Sets the take filter for this container
+ * @param take Take filter
+ * @return This builder
+ */
Builder filterTake(ContainerPredicate take);
+ /**
+ * Builds this container
+ * @return Built container slot
+ */
ContainerSlot build();
@Override
diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/GoBackButton.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/GoBackButton.java
index b3282b8..13f3421 100644
--- a/flare/core/src/main/java/space/maxus/flare/ui/compose/GoBackButton.java
+++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/GoBackButton.java
@@ -14,7 +14,17 @@
import java.util.Objects;
+/**
+ * A button that takes player to previously opened frame. Only renders if it exists.
+ * <br />
+ * See more in Flare docs: <a href="https://flare.maxus.space/ui/composable#gobackbutton">Go Back Button</a>
+ */
public interface GoBackButton extends Disable, Composable, Configurable<GoBackButton> {
+ /**
+ * Returns the default builder for go back button
+ * @param frame The previous frame
+ * @return The default builder for go back button
+ */
static ItemStackBuilder goBackItemBuilder(@Nullable Frame frame) {
return Items.builder(Material.ARROW)
.name("<gray>Go Back <dark_gray>[◀]")
@@ -25,11 +35,20 @@ static ItemStackBuilder goBackItemBuilder(@Nullable Frame frame) {
.hideAllFlags();
}
+ /**
+ * Returns a default go back item
+ * @param player Player for whom to build this button
+ * @return Default go back button
+ */
@Contract(pure = true)
static @NotNull ItemProvider goBackItem(HumanEntity player) {
return () -> goBackItemBuilder(PlayerFrameStateManager.peekPrevious(player)).build();
}
+ /**
+ * Returns a default go back item
+ * @return Default go back item
+ */
@Contract(" -> new")
static @NotNull GoBackButton create() {
return new GoBackButtonImpl(null, false);
diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/Placeholder.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/Placeholder.java
index c79f834..6deb7f2 100644
--- a/flare/core/src/main/java/space/maxus/flare/ui/compose/Placeholder.java
+++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/Placeholder.java
@@ -5,12 +5,27 @@
import org.jetbrains.annotations.NotNull;
import space.maxus.flare.item.ItemProvider;
+/**
+ * A placeholder is a slot that can not be interacted with.
+ * <br />
+ * See more in Flare docs: <a href="https://flare.maxus.space/ui/composable#placeholder">Placeholder</a>
+ */
public interface Placeholder extends ProviderRendered {
+ /**
+ * Constructs a new placeholder for an item provider
+ * @param provider The item provider
+ * @return A new placeholder with item provider
+ */
@Contract("_ -> new")
static @NotNull Placeholder of(ItemProvider provider) {
return new PlaceholderImpl(provider);
}
+ /**
+ * Constructs a new placeholder with a still item provider of this item
+ * @param still Item to be used
+ * @return A new placeholder with item
+ */
@Contract("_ -> new")
static @NotNull Placeholder of(ItemStack still) {
return new PlaceholderImpl(ItemProvider.still(still));
diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/ProgressBar.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/ProgressBar.java
index e3dfd46..46b04d2 100644
--- a/flare/core/src/main/java/space/maxus/flare/ui/compose/ProgressBar.java
+++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/ProgressBar.java
@@ -2,6 +2,7 @@
import org.bukkit.Material;
import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Range;
import space.maxus.flare.item.ItemProvider;
import space.maxus.flare.item.ItemStackBuilder;
import space.maxus.flare.item.Items;
@@ -12,7 +13,20 @@
import java.util.Objects;
+/**
+ * A progress bar is a dynamic component that renders progress inside itself.
+ * <br />
+ * See more in Flare docs: <a href="https://flare.maxus.space/ui/composable#progressbar">Progress Bar</a>
+ */
public interface ProgressBar extends Composable, Configurable<ProgressBar> {
+ /**
+ * Returns an item builder for a full progress bar part
+ * @param material Base material
+ * @param progress Bar progress
+ * @param dotted Whether the display should be dotted.
+ * @return An item builder for a full progress bar part
+ * @see FlareUtil#renderBarText(float, int, boolean)
+ */
static ItemStackBuilder fullBuilder(Material material, float progress, boolean dotted) {
return Items.builder(material)
.name("<gray>Progress: <green>%s%% <dark_gray>[%%]".formatted(Math.round(progress * 100f)))
@@ -20,6 +34,14 @@ static ItemStackBuilder fullBuilder(Material material, float progress, boolean d
.hideAllFlags();
}
+ /**
+ * Returns an item builder for an empty progress bar part
+ * @param material Base material
+ * @param progress Bar progress
+ * @param dotted Whether the display should be dotted.
+ * @return An item builder for an empty progress bar part
+ * @see FlareUtil#renderBarText(float, int, boolean)
+ */
static ItemStackBuilder emptyBuilder(Material material, float progress, boolean dotted) {
return Items.builder(material)
.name("<gray>Progress: <red>%s%% <dark_gray>[%%]".formatted(Math.round(progress * 100f)))
@@ -27,29 +49,70 @@ static ItemStackBuilder emptyBuilder(Material material, float progress, boolean
.hideAllFlags();
}
+ /**
+ * Returns an item builder for a full progress bar part
+ * @param material Base material
+ * @param state The bar progress reactive state
+ * @param dotted Whether the display should be dotted.
+ * @return An item builder for a full progress bar part
+ * @see FlareUtil#renderBarText(float, int, boolean)
+ */
static @NotNull ItemProvider fullProvider(ReactiveState<Float> state, Material material, boolean dotted) {
return Reactive.item(state, progress -> fullBuilder(material, Objects.requireNonNullElse(progress, .0f), dotted).build());
}
+ /**
+ * Returns an item builder for an empty progress bar part
+ * @param material Base material
+ * @param state The bar progress reactive state
+ * @param dotted Whether the display should be dotted.
+ * @return An item builder for an empty progress bar part
+ * @see FlareUtil#renderBarText(float, int, boolean)
+ */
static @NotNull ItemProvider emptyProvider(ReactiveState<Float> state, Material material, boolean dotted) {
return Reactive.item(state, progress -> emptyBuilder(material, Objects.requireNonNullElse(progress, .0f), dotted).build());
}
+ /**
+ * Constructs a progress bar with full and empty item providers
+ * @param full Item provider for filled part
+ * @param empty Item provider for empty part
+ * @return A progress bar with full and empty item providers
+ */
static @NotNull ProgressBar of(ItemProvider full, ItemProvider empty) {
return of(full, empty, 0f);
}
- static @NotNull ProgressBar of(ItemProvider full, ItemProvider empty, float progress) {
+ /**
+ * Constructs a progress bar with full and empty item providers and base progress
+ * @param full Item provider for filled part
+ * @param empty Item provider for empty part
+ * @param progress Starting progress of the bar.
+ * @return A progress bar with full and empty item providers
+ */
+ static @NotNull ProgressBar of(ItemProvider full, ItemProvider empty, @Range(from = 0, to = 1) float progress) {
return new ProgressBarImpl(progress, full, empty);
}
+ /**
+ * Returns the current progress state
+ * @return Current progress state.
+ */
ReactiveState<Float> progressState();
- default float getProgress() {
+ /**
+ * Gets current bar progress
+ * @return Current bar progress
+ */
+ default @Range(from = 0, to = 1) float getProgress() {
return progressState().get();
}
- default float setProgress(float newProgress) {
- return progressState().get();
+ /**
+ * Sets the bar progress
+ * @param newProgress New progress
+ */
+ default void setProgress(@Range(from = 0, to = 1) float newProgress) {
+ progressState().set(newProgress);
}
}
diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/ProviderRendered.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/ProviderRendered.java
index c6b7e14..5b4809a 100644
--- a/flare/core/src/main/java/space/maxus/flare/ui/compose/ProviderRendered.java
+++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/ProviderRendered.java
@@ -6,7 +6,14 @@
import space.maxus.flare.ui.Composable;
import space.maxus.flare.ui.space.Slot;
+/**
+ * An interface for components that are implicitly rendered by an item provider
+ */
public interface ProviderRendered extends Composable {
+ /**
+ * Gets the provider for rendering
+ * @return The provider for rendering
+ */
@NotNull ItemProvider getProvider();
@Override
diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/RootReferencing.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/RootReferencing.java
index 9e8b87f..433d7f6 100644
--- a/flare/core/src/main/java/space/maxus/flare/ui/compose/RootReferencing.java
+++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/RootReferencing.java
@@ -9,7 +9,13 @@
import java.util.concurrent.atomic.AtomicReference;
+/**
+ * An abstract class for component implementations that automatically handles root frame injection
+ */
public abstract class RootReferencing implements Composable {
+ /**
+ * The root frame
+ */
protected final AtomicReference<Frame> root = new AtomicReference<>(null);
private @Nullable ComposableSpace attachedSpace;
diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/Selection.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/Selection.java
index 51c902e..b2de476 100644
--- a/flare/core/src/main/java/space/maxus/flare/ui/compose/Selection.java
+++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/Selection.java
@@ -22,7 +22,21 @@
import java.util.List;
+/**
+ * A selection is a component that houses a list of values. Only one list value can be selected.
+ * <br />
+ * See more in Flare docs: <a href="https://flare.maxus.space/ui/composable#selection">Selection</a>
+ * @param <E> The type of selection value
+ */
public interface Selection<E> extends Disable, ProviderRendered, Configurable<Selection<E>> {
+ /**
+ * Builds lore list for a selection
+ * @param enumeration The enumeration of values
+ * @param selected Currently selected value
+ * @param mapper Mapper function that converts values to display strings
+ * @return List of lore components
+ * @param <E> The type of selection value
+ */
static <E> List<Component> selectorLore(@NotNull List<E> enumeration, E selected, Computable<E, String> mapper) {
return enumeration
.stream()
@@ -45,6 +59,16 @@ static <E> List<Component> selectorLore(@NotNull List<E> enumeration, E selected
.toList();
}
+ /**
+ * Returns a reactive selector item provider with certain settings
+ * @param name Extra message in the item name
+ * @param description Extra description in the lore
+ * @param enumeration Enumeration of selection values
+ * @param selector The selection reactive state
+ * @param mapper Mapper function that converts values to display strings
+ * @return A reactive selector item provider with certain settings
+ * @param <E> The type of selection value
+ */
static <E> @NotNull ItemProvider selector(String name, String description, List<E> enumeration, ReactiveState<E> selector, Computable<E, String> mapper) {
return Reactive.item(selector, value -> Items
.builder(Material.PLAYER_HEAD)
@@ -60,6 +84,16 @@ static <E> List<Component> selectorLore(@NotNull List<E> enumeration, E selected
);
}
+ /**
+ * Returns a selector item builder with certain settings
+ * @param name Extra message in the item name
+ * @param description Extra description in the lore
+ * @param enumeration Enumeration of selection values
+ * @param mapper Mapper function that converts values to display strings
+ * @param value Currently selected value
+ * @return A selector item builder with certain settings
+ * @param <E> The type of selection value
+ */
static <E> @NotNull ItemStackBuilder selectorBuilder(String name, String description, List<E> enumeration, E value, Computable<E, String> mapper) {
return Items
.builder(Material.PLAYER_HEAD)
@@ -72,6 +106,17 @@ static <E> List<Component> selectorLore(@NotNull List<E> enumeration, E selected
.hideAllFlags();
}
+ /**
+ * Returns a selector item builder with certain settings
+ * @param name Extra message in the item name
+ * @param description Extra description in the lore
+ * @param enumeration Enumeration of selection values
+ * @param mapper Mapper function that converts values to display strings
+ * @param player Player for selection
+ * @param value Currently selected value
+ * @return A selector item builder with certain settings
+ * @param <E> The type of selection value
+ */
static <E> @NotNull ItemStackBuilder selectorBuilder(String name, String description, List<E> enumeration, E value, Computable<E, String> mapper, @Nullable Player player) {
return Items
.builder(Material.PLAYER_HEAD, player)
@@ -84,49 +129,137 @@ static <E> List<Component> selectorLore(@NotNull List<E> enumeration, E selected
.hideAllFlags();
}
-
+ /**
+ * Constructs a new selection
+ * @param enumeration Enumeration of all possible values
+ * @param provider The item provider
+ * @return A new selection
+ * @param <E> The type of selection value
+ */
static <E> @NotNull Selection<E> of(Collection<E> enumeration, ItemProvider provider) {
return new SelectionImpl<>(provider, enumeration, 0, false, null);
}
+ /**
+ * Constructs a new selection
+ * @param enumeration Enumeration of all possible values
+ * @param provider The item provider
+ * @param selected Zero-based index of the selected item
+ * @return A new selection
+ * @param <E> The type of selection value
+ */
static <E> @NotNull Selection<E> of(Collection<E> enumeration, ItemProvider provider, int selected) {
return new SelectionImpl<>(provider, enumeration, selected, false, null);
}
+ /**
+ * Constructs a new selection
+ * @param enumeration Enumeration of all possible values
+ * @param provider The item provider
+ * @param selected The selected value
+ * @return A new selection
+ * @param <E> The type of selection value
+ */
@Contract("_, _, _ -> new")
static <E> @NotNull Selection<E> of(@NotNull Collection<E> enumeration, ItemProvider provider, E selected) {
return new SelectionImpl<>(provider, enumeration, enumeration.stream().toList().indexOf(selected), false, null);
}
+ /**
+ * Constructs a new selection
+ * @param enumeration Enumeration of all possible values
+ * @param formatter The formatter function that takes selection value and turns it to a display string
+ * @return A new selection
+ * @param <E> The type of selection value
+ */
static <E> @NotNull Selection<E> of(Collection<E> enumeration, Computable<E, String> formatter) {
return new SelectionImpl<>(null, enumeration, 0, false, formatter);
}
+ /**
+ * Constructs a new selection builder
+ * @param enumeration Enumeration of all possible values
+ * @return A new selection builder
+ * @param <E> The type of selection values
+ */
static <E> @NotNull Builder<E> builder(Collection<E> enumeration) {
return new SelectionImpl.Builder<>(new ArrayList<>(enumeration));
}
+ /**
+ * Lists all possible values in this selection
+ * @return All possible values
+ */
List<E> enumeration();
+ /**
+ * Returns the selected value
+ * @return The selected value
+ */
@NotNull E getSelected();
+ /**
+ * Sets the selected value
+ * @param index Index of the selected value
+ */
void setSelected(int index);
+ /**
+ * Sets the selected value
+ * @param value The new selected value
+ */
void setSelected(E value);
+ /**
+ * Returns the selected value reactive state
+ * @return The selected value reactive state
+ */
@NotNull ReactiveState<E> selectedState();
+ /**
+ * The selection builder
+ * @param <E> The type of selected value
+ */
interface Builder<E> extends ComposableLike {
+ /**
+ * Sets the item provider. Either item provider or {@link #formatter} should be set.
+ * @param provider The item provider to use
+ * @return This builder
+ */
Builder<E> item(ItemProvider provider);
+ /**
+ * Sets the currently selected item index
+ * @param index The currently selected item index
+ * @return This builder
+ */
Builder<E> selected(int index);
+ /**
+ * Sets the currently selected item
+ * @param item The currently selected item
+ * @return This builder
+ */
Builder<E> selectedItem(E item);
+ /**
+ * Sets the disabled state of selection
+ * @param isDisabled The disabled state
+ * @return This builder
+ */
Builder<E> isDisabled(boolean isDisabled);
+ /**
+ * Sets the formatter. Either formatter or {@link #item} should be set.
+ * @param mapper The formatter function
+ * @return This builder
+ */
Builder<E> formatter(Computable<E, String> mapper);
+ /**
+ * Builds this selection
+ * @return The selection
+ */
Selection<E> build();
@Override
diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/Slideshow.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/Slideshow.java
index 52d70b1..e461e71 100644
--- a/flare/core/src/main/java/space/maxus/flare/ui/compose/Slideshow.java
+++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/Slideshow.java
@@ -7,18 +7,48 @@
import java.util.List;
+/**
+ * A slideshow is a periodically changing component.
+ * <br />
+ * See more in Flare docs: <a href="https://flare.maxus.space/ui/composable#slideshow">Slideshow</a>
+ */
public interface Slideshow extends Disable, Composable, Configurable<Slideshow> {
+ /**
+ * Constructs a new slideshow out of a list of items
+ * @param items Items to be used
+ * @param period Period between switching in ticks
+ * @return A new slideshow
+ */
static @NotNull Slideshow of(List<ItemProvider> items, int period) {
return new SlideshowImpl(items, period, false);
}
+ /**
+ * Constructs a new slideshow out of a list of items
+ * @param items Items to be used
+ * @param period Period between switching in ticks
+ * @param disabled Whether the slideshow should be disabled
+ * @return A new slideshow
+ */
static @NotNull Slideshow of(List<ItemProvider> items, int period, boolean disabled) {
return new SlideshowImpl(items, period, disabled);
}
+ /**
+ * Returns all possible slides on this slideshow
+ * @return All possible slides on this slideshow
+ */
List<ItemProvider> getSlides();
+ /**
+ * Returns the reactive state of the currently selected item provider
+ * @return The reactive state of the currently selected item provider
+ */
ReactiveState<ItemProvider> itemState();
+ /**
+ * Returns the period between the slides switching
+ * @return The period between the slides switching
+ */
int getPeriod();
}
diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/TextInput.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/TextInput.java
index 72c1a76..dceb34b 100644
--- a/flare/core/src/main/java/space/maxus/flare/ui/compose/TextInput.java
+++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/TextInput.java
@@ -24,7 +24,19 @@
import space.maxus.flare.util.ValidatingInvBoundPrompt;
import space.maxus.flare.util.Validator;
+/**
+ * A text input is a component that can handle user input.
+ * <br />
+ * See more in Flare docs: <a href="https://flare.maxus.space/ui/composable#textinput">Text Input</a>
+ */
public interface TextInput extends Disable, ProviderRendered, Configurable<TextInput> {
+ /**
+ * Returns an item builder for a text input
+ * @param currentText Current text value
+ * @param name Extra message in item name
+ * @param description Description in item lore
+ * @return An item builder for a text input
+ */
static @NotNull ItemStackBuilder inputItemBuilder(@NotNull String currentText, String name, String description) {
return Items.builder(Material.PLAYER_HEAD)
.headSkin(
@@ -43,52 +55,113 @@ public interface TextInput extends Disable, ProviderRendered, Configurable<TextI
;
}
+ /**
+ * Returns an item provider for a text input
+ * @param text Reactive state of the text value
+ * @param name Extra message in item name
+ * @param description Description in item lore
+ * @return An item builder for a text input
+ */
static @NotNull ItemProvider inputItem(@NotNull ReactiveState<String> text, String name, String description) {
return Reactive.item(text, newText -> inputItemBuilder(newText == null ? "" : newText, name, description).build());
}
+ /**
+ * Constructs a new text input with an item provider
+ * @param provider The item provider to use
+ * @return A new text input
+ */
@Contract("_ -> new")
static @NotNull TextInput of(ItemProvider provider) {
return new TextInputImpl(provider, false);
}
+ /**
+ * Constructs a new text input with an item provider
+ * @param provider The item provider to use
+ * @param disabled Whether the text input should be disabled
+ * @return A new text input
+ */
@Contract("_, _ -> new")
static @NotNull TextInput of(ItemProvider provider, boolean disabled) {
return new TextInputImpl(provider, disabled);
}
+ /**
+ * Constructs a new text input builder
+ * @param provider Item provider to use
+ * @return A new text input builder
+ */
static @NotNull Builder builder(@Nullable ItemProvider provider) {
return new TextInputImpl.Builder(provider, null, null);
}
+ /**
+ * Constructs a new text input builder
+ * @param name Extra message in item name
+ * @param description Extra message in item lore
+ * @return A new text input builder
+ */
static @NotNull Builder builder(@Nullable String name, @Nullable String description) {
return new TextInputImpl.Builder(null, name, description);
}
+ /**
+ * Constructs a new text input builder
+ * @return A new text input builder
+ */
static @NotNull Builder builder() {
return new TextInputImpl.Builder(null, "Text Input", "");
}
+ /**
+ * Returns current text value
+ * @return Current text value
+ */
default @NotNull String getText() {
- return onTextChange().get();
+ return textState().get();
}
+ /**
+ * Sets current text
+ * @param text Text to be set
+ */
default void setText(@NotNull String text) {
- onTextChange().set(text);
+ textState().set(text);
}
+ /**
+ * Returns the default prompt
+ * @return The default prompt
+ */
default @NotNull String getPrompt() {
return promptState().get();
}
+ /**
+ * Sets the default prompt
+ * @param prompt The prompt to set
+ */
default void setPrompt(String prompt) {
promptState().set(prompt);
}
- ReactiveState<String> onTextChange();
+ /**
+ * Returns the input text reactive state
+ * @return The input text reactive state
+ */
+ ReactiveState<String> textState();
+ /**
+ * Returns the prompt reactive state
+ * @return The input text reactive state
+ */
ReactiveState<String> promptState();
+ /**
+ * Returns the input validator
+ * @return The input validator
+ */
@Nullable Validator getValidator();
@Override
@@ -97,8 +170,12 @@ default TextInput configure(@NotNull Configurator<TextInput> configurator) {
return this;
}
+ /**
+ * Adds a handler to text change
+ * @param change Handler for the text change
+ */
default void onTextChange(ReactiveSubscriber<@NotNull String> change) {
- this.onTextChange().subscribe(change);
+ this.textState().subscribe(change);
}
@Override
@@ -106,7 +183,7 @@ default void click(@NotNull InventoryClickEvent e) {
if (isDisabled())
return;
Inventory current = e.getInventory();
- Prompt prompt = getValidator() == null ? new SimpleInvBoundPrompt(getPrompt(), onTextChange(), current) : new ValidatingInvBoundPrompt(getValidator(), getPrompt(), onTextChange(), current);
+ Prompt prompt = getValidator() == null ? new SimpleInvBoundPrompt(getPrompt(), textState(), current) : new ValidatingInvBoundPrompt(getValidator(), getPrompt(), textState(), current);
Player conversible = (Player) e.getWhoClicked();
conversible.closeInventory(InventoryCloseEvent.Reason.TELEPORT);
Conversation conv =
@@ -117,15 +194,44 @@ default void click(@NotNull InventoryClickEvent e) {
conv.begin();
}
+ /**
+ * The builder for text input
+ */
interface Builder extends ComposableLike {
+ /**
+ * Builds this text input
+ * @return This text input
+ */
TextInput build();
+ /**
+ * Sets the disabled state
+ * @param disabled The disabled state
+ * @return This builder
+ */
Builder disabled(boolean disabled);
+ /**
+ * Sets the default prompt
+ * @param prompt Prompt to be set
+ * @return This builder
+ */
Builder prompt(String prompt);
+ /**
+ * Sets the initial text value (defaults to empty string)
+ * @param initialText The initial text value
+ * @return This builder
+ */
Builder initialText(String initialText);
+ /**
+ * Adds a validator for text input
+ * @param validator Validator to be added
+ * @return This builder
+ * @see Validator
+ * @see space.maxus.flare.util.Validators
+ */
Builder validate(Validator validator);
@Override
diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/TextInputImpl.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/TextInputImpl.java
index 451919e..fbf8cae 100644
--- a/flare/core/src/main/java/space/maxus/flare/ui/compose/TextInputImpl.java
+++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/TextInputImpl.java
@@ -36,7 +36,7 @@ final class TextInputImpl extends RootReferencing implements TextInput {
}
@Override
- public ReactiveState<String> onTextChange() {
+ public ReactiveState<String> textState() {
return textState;
}