From 136edddc1f70e3c196a4f8aa7d2cb193c777b210 Mon Sep 17 00:00:00 2001 From: alexcrea Date: Thu, 14 Mar 2024 02:03:54 +0100 Subject: [PATCH] Add javadoc & refactor of utils class related to config. --- .../gui/config/EnchantCostConfigGui.java | 6 +- .../gui/config/EnchantLimitConfigGui.java | 4 +- .../settings/EnchantCostSettingsGui.java | 2 +- .../cuanvil/gui/util/GuiGlobalActions.java | 49 +++++- .../cuanvil/gui/util/GuiGlobalItems.java | 155 +++++++++++++++--- .../{StringUtil.java => CasedStringUtil.java} | 14 +- 6 files changed, 200 insertions(+), 30 deletions(-) rename src/main/java/xyz/alexcrea/cuanvil/util/{StringUtil.java => CasedStringUtil.java} (54%) diff --git a/src/main/java/xyz/alexcrea/cuanvil/gui/config/EnchantCostConfigGui.java b/src/main/java/xyz/alexcrea/cuanvil/gui/config/EnchantCostConfigGui.java index 5104c63..b5a2a50 100644 --- a/src/main/java/xyz/alexcrea/cuanvil/gui/config/EnchantCostConfigGui.java +++ b/src/main/java/xyz/alexcrea/cuanvil/gui/config/EnchantCostConfigGui.java @@ -10,7 +10,7 @@ import xyz.alexcrea.cuanvil.enchant.EnchantmentProperties; import xyz.alexcrea.cuanvil.enchant.EnchantmentRarity; import xyz.alexcrea.cuanvil.gui.config.settings.EnchantCostSettingsGui; import xyz.alexcrea.cuanvil.gui.util.GuiGlobalItems; -import xyz.alexcrea.cuanvil.util.StringUtil; +import xyz.alexcrea.cuanvil.util.CasedStringUtil; import java.util.Arrays; import java.util.Locale; @@ -39,7 +39,7 @@ public class EnchantCostConfigGui extends AbstractEnchantConfigGui stayInPlace = (event) -> event.setCancelled(true); - + /** + * Create a consumer to create and open a new GUI. + * Used with InventoryClickEvent as the consumer argument as it is planned to be used on click on an GuiItem. + * @param clazz The class of the gui to open. + * It is assumed this class contain a constructor requiring arguments of argClass in the same order as argClass array. + * @param argClass Classes of the argument that will be passed to the constructor of the GUI class. + * @param args Arguments for the constructor the GUI class. + * @return A consumer to create a new gui and open it. + */ public static @NotNull Consumer openGuiAction( @NotNull Class clazz, @NotNull Class[] argClass, @@ -44,11 +59,24 @@ public class GuiGlobalActions { }; } + /** + * Create a consumer to create and open a new GUI. + * Used with InventoryClickEvent as the consumer argument as it is planned to be used on click on an GuiItem. + * @param clazz The class of the gui to open. + * It is assumed this class contain a constructor with no argument. + * @return A consumer to create a new gui and open it. + */ public static @NotNull Consumer openGuiAction( @NotNull Class clazz){ return openGuiAction(clazz, new Class[0]); } + /** + * Create a consumer to open a setting gui from a setting GUI factory. + * Used with InventoryClickEvent as the consumer argument as it is planned to be used on click on an GuiItem. + * @param factory The setting gui factory. + * @return A consumer to create and open a new setting GUI. + */ public static @NotNull Consumer openSettingGuiAction(AbstractSettingGui.SettingGuiFactory factory){ return event -> { event.setCancelled(true); @@ -57,6 +85,12 @@ public class GuiGlobalActions { }; } + /** + * Create a consumer to open a global GUI. + * Used with InventoryClickEvent as the consumer argument as it is planned to be used on click on an GuiItem. + * @param goal The gui to open when consumer is run. + * @return A consumer to open a global GUI. + */ public static @NotNull Consumer openGuiAction(@NotNull Gui goal) { return event -> { HumanEntity player = event.getWhoClicked(); @@ -71,6 +105,14 @@ public class GuiGlobalActions { }; } + /** + * Create a consumer to update and open an updatable GUI. + * Used with InventoryClickEvent as the consumer argument as it is planned to be used on click on an GuiItem. + * This consumer check if the player who interacted with the item have the permission to save before saving. + * @param setting The gui that contain the modified setting. + * @param goal The gui to update and open when consumer is run. + * @return A consumer to open a global GUI. + */ public static @NotNull Consumer saveSettingAction( @NotNull AbstractSettingGui setting, @NotNull ValueUpdatableGui goal) { @@ -86,12 +128,13 @@ public class GuiGlobalActions { // Save setting if(!setting.onSave()){ - player.sendMessage("\u00A7cSomething wrong happen while saving the change of value."); + player.sendMessage("\u00A7cSomething went wrong while saving the change of value."); } - // Update gui for the one who have it open + // Update gui for those who have it open. goal.updateGuiValues(); // Then show goal.show(player); }; } + } diff --git a/src/main/java/xyz/alexcrea/cuanvil/gui/util/GuiGlobalItems.java b/src/main/java/xyz/alexcrea/cuanvil/gui/util/GuiGlobalItems.java index 68df6df..bc959fb 100644 --- a/src/main/java/xyz/alexcrea/cuanvil/gui/util/GuiGlobalItems.java +++ b/src/main/java/xyz/alexcrea/cuanvil/gui/util/GuiGlobalItems.java @@ -12,36 +12,63 @@ import xyz.alexcrea.cuanvil.gui.ValueUpdatableGui; import xyz.alexcrea.cuanvil.gui.config.settings.AbstractSettingGui; import xyz.alexcrea.cuanvil.gui.config.settings.BoolSettingsGui; import xyz.alexcrea.cuanvil.gui.config.settings.IntSettingsGui; -import xyz.alexcrea.cuanvil.util.StringUtil; +import xyz.alexcrea.cuanvil.util.CasedStringUtil; import java.util.Collections; -// maybe use builder patern ? +/** + * A utility class to store function that create generic GUI item. + */ public class GuiGlobalItems { - // return - public static GuiItem goToGuiItem(@NotNull ItemStack item, @NotNull Gui goal){ - return new GuiItem(item, GuiGlobalActions.openGuiAction(goal), CustomAnvil.instance); - } - - // statically create back itemstack - private static final ItemStack BACK_ITEM = new ItemStack(Material.BARRIER); + // statically create default back itemstack + private static final ItemStack BACK_ITEM; static { - // todo add what I need to add to the back item + BACK_ITEM = new ItemStack(Material.BARRIER); ItemMeta meta = BACK_ITEM.getItemMeta(); meta.setDisplayName("\u00A7cBack"); BACK_ITEM.setItemMeta(meta); } + + /** + * Create a GuiItem that open the given GUi. + * @param item The item to display in the GUI. + * @param goal The GUI to open on click. + * @return An GuiItem that open goal on click. + */ + public static GuiItem goToGuiItem(@NotNull ItemStack item, @NotNull Gui goal){ + return new GuiItem(item, GuiGlobalActions.openGuiAction(goal), CustomAnvil.instance); + } + + /** + * Create back button item from default back GuiItem. + * The back item will open the goal inventory when clicked. + * @param goal The GUI to go back to. + * @return An GuiItem that go back to goal on click. + */ public static GuiItem backItem(@NotNull Gui goal){ - // simple go back item return goToGuiItem(BACK_ITEM, goal); } + + /** + * Add default back item to a GUI pattern with the reserved character key B. + * The back item will open the target inventory when clicked. + * @param target The pattern to add the back item. + * @param goal The GUI to go back to. + */ public static void addBackItem(@NotNull PatternPane target, @NotNull Gui goal){ target.bindItem('B', backItem(goal)); } private static final Material DEFAULT_BACKGROUND_MAT = Material.LIGHT_GRAY_STAINED_GLASS_PANE; + + /** + * Get a background item with backgroundMat as the displayed material. + * A background item is a GuiItem that do nothing when interacted with and have an empty name. + * @param backgroundMat The material to which the background item should be made of. + * @return A background item with backgroundMat as material. + */ public static GuiItem backgroundItem(Material backgroundMat){ ItemStack item = new ItemStack(backgroundMat); ItemMeta meta = item.getItemMeta(); @@ -49,19 +76,46 @@ public class GuiGlobalItems { item.setItemMeta(meta); return new GuiItem(item, GuiGlobalActions.stayInPlace, CustomAnvil.instance); } + /** + * Get default background GuiItem. + * A background item is a GuiItem that do nothing when interacted with and have an empty name. + * @return A new instance of the default background item. + */ public static GuiItem backgroundItem(){ return backgroundItem(DEFAULT_BACKGROUND_MAT); } + + /** + * Add default background item to a GUI pattern with the reserved character key 0. + * A background item is a GuiItem that do nothing when interacted with and have an empty name. + * @param target The pattern to add the background item. + * @param backgroundMat The material of the background item. + */ public static void addBackgroundItem(@NotNull PatternPane target, - @NotNull Material backgroundMat){ + @NotNull Material backgroundMat){ target.bindItem('0', backgroundItem(backgroundMat)); } + + /** + * Add default background item to a GUI pattern with the reserved character key 0. + * A background item is a GuiItem that do nothing when interacted with and have an empty name. + * @param target The pattern to add the background item. + */ public static void addBackgroundItem(@NotNull PatternPane target){ addBackgroundItem(target, DEFAULT_BACKGROUND_MAT); } private static final Material DEFAULT_SAVE_ITEM = Material.LIME_DYE; private static final Material DEFAULT_NO_CHANGE_ITEM = Material.GRAY_DYE; + + /** + * Create a new save setting GuiItem. + * A save setting item is a GuiItem that save a changed setting when clicked. + * This item also check if the player who interacted with the item have the permission to save before saving. + * @param setting The setting to change. + * @param goal Parent GUI of this setting GUI. as setting will be change the display of goal GUI will be updated. + * @return A save setting item. + */ public static GuiItem saveItem( @NotNull AbstractSettingGui setting, @NotNull ValueUpdatableGui goal){ @@ -75,6 +129,7 @@ public class GuiGlobalItems { CustomAnvil.instance); } + // Create static non change item private static final GuiItem NO_CHANGE_ITEM; static { ItemStack item = new ItemStack(DEFAULT_NO_CHANGE_ITEM); @@ -84,10 +139,22 @@ public class GuiGlobalItems { NO_CHANGE_ITEM = new GuiItem(item,GuiGlobalActions.stayInPlace, CustomAnvil.instance); } + /** + * Get the global "no change" GuiItem. + * The no change item do nothing when interacted, only the title is change to show there is no change. + * @return The global "no change" item. + */ public static GuiItem noChangeItem(){ return NO_CHANGE_ITEM; } + /** + * Create a new "create and go to the setting GUI" GuiItem. + * This item will create and open a setting GUI from the factory. + * @param item The item that will be displayed. + * @param factory The setting's GUI factory. + * @return A formatted GuiItem that will create and open a GUI for the setting. + */ public static GuiItem openSettingGuiItem( @NotNull ItemStack item, @NotNull AbstractSettingGui.SettingGuiFactory factory @@ -95,8 +162,17 @@ public class GuiGlobalItems { return new GuiItem(item, GuiGlobalActions.openSettingGuiAction(factory), CustomAnvil.instance); } + // Prefix of the one line lore that will be added to setting's item. public static final String SETTING_ITEM_LORE_PREFIX = "\u00A77value: "; + /** + * Create a new Boolean setting GuiItem. + * This item will create and open a boolean setting GUI from the factory. + * The item will have its value written in the lore part of the item. + * @param factory The setting's GUI factory. + * @param name Name of the item. + * @return A formatted GuiItem that will create and open a GUI for the boolean setting. + */ public static GuiItem boolSettingGuiItem( @NotNull BoolSettingsGui.BoolSettingFactory factory, @NotNull String name @@ -118,14 +194,30 @@ public class GuiGlobalItems { return createGuiItemFromProperties(factory, itemMat, itemName, value); } + /** + * Create a new boolean setting GuiItem. + * This item will create and open a boolean setting GUI from the factory. + * The item will have its value written in the lore part of the item. + * Item's name will be the factory set title. + * @param factory The setting's GUI factory. + * @return A formatted GuiItem that will create and open a GUI for the boolean setting. + */ public static GuiItem boolSettingGuiItem( @NotNull BoolSettingsGui.BoolSettingFactory factory ){ String configPath = getConfigNameFromPath(factory.getConfigPath()); - return boolSettingGuiItem(factory, StringUtil.snakeToUpperSpacedCase(configPath)); + return boolSettingGuiItem(factory, CasedStringUtil.snakeToUpperSpacedCase(configPath)); } - + /** + * Create a new int setting GuiItem. + * This item will create and open an int setting GUI from the factory. + * The item will have its value written in the lore part of the item. + * @param factory The setting's GUI factory. + * @param itemMat Displayed material of the item. + * @param name Name of the item. + * @return A formatted GuiItem that will create and open a GUI for the int setting. + */ public static GuiItem intSettingGuiItem( @NotNull IntSettingsGui.IntSettingFactory factory, @NotNull Material itemMat, @@ -138,21 +230,39 @@ public class GuiGlobalItems { return createGuiItemFromProperties(factory, itemMat, itemName, value); } - + /** + * Create a new int setting GuiItem. + * This item will create and open an int setting GUI from the factory. + * The item will have its value written in the lore part of the item. + * Item's name will be the factory set title. + * @param factory The setting's GUI factory. + * @param itemMat Displayed material of the item. + * @return A formatted GuiItem that will create and open a GUI for the int setting. + */ public static GuiItem intSettingGuiItem( @NotNull IntSettingsGui.IntSettingFactory factory, @NotNull Material itemMat ){ String configPath = getConfigNameFromPath(factory.getConfigPath()); - return intSettingGuiItem(factory, itemMat, StringUtil.snakeToUpperSpacedCase(configPath)); + return intSettingGuiItem(factory, itemMat, CasedStringUtil.snakeToUpperSpacedCase(configPath)); } + + /** + * Create an arbitrary GuiItem from a unique setting and item's property. + * @param factory The setting's GUI factory. + * @param itemMat Displayed material of the item. + * @param itemName Name of the item. + * @param value Value of the setting when the item is created. + * Will not update automatically, if the setting's value change, the item need to be created again. + * @return A formatted GuiItem that will create and open a GUI for the setting. + */ private static GuiItem createGuiItemFromProperties( @NotNull AbstractSettingGui.SettingGuiFactory factory, @NotNull Material itemMat, @NotNull StringBuilder itemName, @NotNull Object value ){ - // Create item + // Create & initialise item ItemStack item = new ItemStack(itemMat); ItemMeta itemMeta = item.getItemMeta(); @@ -160,13 +270,20 @@ public class GuiGlobalItems { itemMeta.setLore(Collections.singletonList(SETTING_ITEM_LORE_PREFIX+value)); item.setItemMeta(itemMeta); + // Create GuiItem return openSettingGuiItem(item, factory); } + /** + * Get the setting name from the setting path. + * For example: "gui.command.name" will return "name". + * @param path The setting's path. + * @return The setting's name. + */ public static String getConfigNameFromPath(String path){ + // Get index of first dot int indexOfDot = path.indexOf("."); - //if(indexOfDot == -1) return path; - // indexOfDot == -1 (not fond) imply indexOfDot+1 = 0. substring will keep the full path as expected + // when indexOfDot == -1 (not fond), it is implied that indexOfDot+1 = 0. substring will keep the full path as expected return path.substring(indexOfDot+1); } diff --git a/src/main/java/xyz/alexcrea/cuanvil/util/StringUtil.java b/src/main/java/xyz/alexcrea/cuanvil/util/CasedStringUtil.java similarity index 54% rename from src/main/java/xyz/alexcrea/cuanvil/util/StringUtil.java rename to src/main/java/xyz/alexcrea/cuanvil/util/CasedStringUtil.java index 9a36bdb..28525f8 100644 --- a/src/main/java/xyz/alexcrea/cuanvil/util/StringUtil.java +++ b/src/main/java/xyz/alexcrea/cuanvil/util/CasedStringUtil.java @@ -1,8 +1,18 @@ package xyz.alexcrea.cuanvil.util; -public class StringUtil { +/** + * An incomplete cased string util + */ +public class CasedStringUtil { - //we assume snake_cased_string is in snake case + /** + * Transform a snake cased string to an upper-cased spaced string. + *

+ * for example: if we use "hello_world" as an input this function will return "Hello World". + * @param snake_cased_string The input string. + * This argument NEED to be a snake cased string, or it will not work + * @return The input as an upper-cased string with space separator. + */ public static String snakeToUpperSpacedCase(String snake_cased_string){ if(snake_cased_string.contentEquals("")) return ""; StringBuilder result = new StringBuilder();