diff --git a/src/main/java/fr/moribus/imageonmap/gui/core/AbstractGui.java b/src/main/java/fr/moribus/imageonmap/gui/core/AbstractGui.java
index 0573468..f05f0b9 100644
--- a/src/main/java/fr/moribus/imageonmap/gui/core/AbstractGui.java
+++ b/src/main/java/fr/moribus/imageonmap/gui/core/AbstractGui.java
@@ -34,63 +34,228 @@ public abstract class AbstractGui {
protected TreeMap<Integer, String> actions = new TreeMap<>();
protected Inventory inventory;
+ /**
+ * This method is called when the inventory is open through the
+ * {@link GuiManager}. Use this to populate the GUI.
+ *
+ * You will have to store the inventory inside the {@link AbstractGui#inventory} protected attribute,
+ * as this attribute will be used by all other methods.
+ *
+ * @param player The player this GUI will be displayed to.
+ */
public abstract void display(Player player);
- public void update(Player player) {}
+ /**
+ * A standard way to update the GUI when it is not closed. This method is
+ * never called automatically, you have to call it when needed.
+ *
+ * @param player The player this GUI is displayed to.
+ */
+ public void update(Player player)
+ {
- public void onClose(Player player) {}
+ }
+ /**
+ * Call this to open the GUI. The GUI is not automatically open, allowing you
+ * to open it at the best moment (before or after populating it, as example).
+ *
+ * @param player The player this GUI will be displayed to.
+ */
+ public void open(Player player)
+ {
+ player.openInventory(inventory);
+ }
+
+ /**
+ * This method will be called when the GUI is closed.
+ *
+ * @param player The player this GUI was displayed to.
+ */
+ public void onClose(Player player)
+ {
+
+ }
+
+ /**
+ * This method will be called when the player clicks on the GUI.
+ *
+ * @param player The player who clicked on the GUI.
+ * @param stack The clicked {@link ItemStack}.
+ * @param action The action associated with this slot using {@link AbstractGui#setSlotData(ItemStack, int, String)}
+ * or other similar methods.
+ * @param clickType The click.
+ * @param invAction The inventory action.
+ * @param event The full {@link InventoryClickEvent} triggered by the player.
+ */
public void onClick(Player player, ItemStack stack, String action, ClickType clickType, InventoryAction invAction, InventoryClickEvent event)
{
this.onClick(player, stack, action, clickType, invAction);
}
+ /**
+ * This method will be called when the player clicks on the GUI.
+ *
+ * @param player The player who clicked on the GUI.
+ * @param stack The clicked {@link ItemStack}.
+ * @param action The action associated with this slot using {@link AbstractGui#setSlotData(ItemStack, int, String)}
+ * or other similar methods.
+ * @param clickType The click.
+ * @param invAction The inventory action.
+ */
public void onClick(Player player, ItemStack stack, String action, ClickType clickType, InventoryAction invAction)
{
this.onClick(player, stack, action, clickType);
}
+ /**
+ * This method will be called when the player clicks on the GUI.
+ *
+ * @param player The player who clicked on the GUI.
+ * @param stack The clicked {@link ItemStack}.
+ * @param action The action associated with this slot using {@link AbstractGui#setSlotData(ItemStack, int, String)}
+ * or other similar methods.
+ * @param clickType The click.
+ */
public void onClick(Player player, ItemStack stack, String action, ClickType clickType)
{
this.onClick(player, stack, action);
}
+ /**
+ * This method will be called when the player clicks on the GUI.
+ *
+ * @param player The player who clicked on the GUI.
+ * @param stack The clicked {@link ItemStack}.
+ * @param action The action associated with this slot using {@link AbstractGui#setSlotData(ItemStack, int, String)}
+ * or other similar methods.
+ */
public void onClick(Player player, ItemStack stack, String action) {}
+ /**
+ * This method will be called when the user places an item in the GUI, either by shift-click or directly.
+ *
+ * Use the {@link InventoryAction} to distinguish these cases.
+ *
+ * @param player The played who moved the stack to the GUI.
+ * @param stack The moved {@link ItemStack}.
+ * @param clickType The click.
+ * @param invAction The inventory action.
+ * @param event The full {@link InventoryClickEvent} triggered by the player.
+ */
public void onItemDeposit(Player player, ItemStack stack, ClickType clickType, InventoryAction invAction, InventoryClickEvent event)
{
onItemDeposit(player, stack, clickType, invAction);
}
+ /**
+ * This method will be called when the user places an item in the GUI, either by shift-click or directly.
+ *
+ * Use the {@link InventoryAction} to distinguish these cases.
+ *
+ * @param player The played who moved the stack to the GUI.
+ * @param stack The moved {@link ItemStack}.
+ * @param clickType The click.
+ * @param invAction The inventory action.
+ */
public void onItemDeposit(Player player, ItemStack stack, ClickType clickType, InventoryAction invAction)
{
onItemDeposit(player, stack, clickType);
}
+ /**
+ * This method will be called when the user places an item in the GUI, either by shift-click or directly.
+ *
+ * Use the {@link InventoryAction} to distinguish these cases.
+ *
+ * @param player The played who moved the stack to the GUI.
+ * @param stack The moved {@link ItemStack}.
+ * @param clickType The click.
+ */
public void onItemDeposit(Player player, ItemStack stack, ClickType clickType)
{
onItemDeposit(player, stack);
}
- public void onItemDeposit(Player player, ItemStack stack) {}
+ /**
+ * This method will be called when the user places an item in the GUI, either by shift-click or directly.
+ *
+ * Use the {@link InventoryAction} to distinguish these cases.
+ *
+ * @param player The played who moved the stack to the GUI.
+ * @param stack The moved {@link ItemStack}.
+ */
+ public void onItemDeposit(Player player, ItemStack stack)
+ {
+ }
+ /**
+ * Registers a slot as a managed one.
+ *
+ * When such a slot is clicked by the player, the {@link #onClick(Player, ItemStack, String, ClickType, InventoryAction, InventoryClickEvent)}
+ * method is called (and all methods with the same name and less arguments).
+ *
+ * @param inv The inventory the item will be added to.
+ * @param name The display name of the item.
+ * @param material The material of this item.
+ * @param slot The slot this item will be added to.
+ * @param description The description (lore) of the item (one line per {@link String} in the array).
+ * @param action The action associated with this slot, retrieved with the {@link #onClick(Player, ItemStack, String)] methods.
+ */
public void setSlotData(Inventory inv, String name, Material material, int slot, String[] description, String action)
{
this.setSlotData(inv, name, new ItemStack(material, 1), slot, description, action);
}
+ /**
+ * Registers a slot as a managed one, using the default inventory.
+ *
+ * When such a slot is clicked by the player, the {@link #onClick(Player, ItemStack, String, ClickType, InventoryAction, InventoryClickEvent)}
+ * method is called (and all methods with the same name and less arguments).
+ *
+ * @param name The display name of the item.
+ * @param material The material of this item.
+ * @param slot The slot this item will be added to.
+ * @param description The description (lore) of the item (one line per {@link String} in the array).
+ * @param action The action associated with this slot, retrieved with the {@link #onClick(Player, ItemStack, String)] methods.
+ */
public void setSlotData(String name, Material material, int slot, String[] description, String action)
{
this.setSlotData(this.inventory, name, new ItemStack(material, 1), slot, description, action);
}
+ /**
+ * Registers a slot as a managed one, using the default inventory.
+ *
+ * When such a slot is clicked by the player, the {@link #onClick(Player, ItemStack, String, ClickType, InventoryAction, InventoryClickEvent)}
+ * method is called (and all methods with the same name and less arguments).
+ *
+ * @param name The display name of the item.
+ * @param item The {@link ItemStack} displayed in this slot.
+ * @param slot The slot this item will be added to.
+ * @param description The description (lore) of the item (one line per {@link String} in the array).
+ * @param action The action associated with this slot, retrieved with the {@link #onClick(Player, ItemStack, String)] methods.
+ */
public void setSlotData(String name, ItemStack item, int slot, String[] description, String action)
{
this.setSlotData(this.inventory, name, item, slot, description, action);
}
+ /**
+ * Registers a slot as a managed one.
+ *
+ * When such a slot is clicked by the player, the {@link #onClick(Player, ItemStack, String, ClickType, InventoryAction, InventoryClickEvent)}
+ * method is called (and all methods with the same name and less arguments).
+ *
+ * @param inv The inventory the item will be added to.
+ * @param name The display name of the item.
+ * @param item The {@link ItemStack} displayed in this slot.
+ * @param slot The slot this item will be added to.
+ * @param description The description (lore) of the item (one line per {@link String} in the array).
+ * @param action The action associated with this slot, retrieved with the {@link #onClick(Player, ItemStack, String)] methods.
+ */
public void setSlotData(Inventory inv, String name, ItemStack item, int slot, String[] description, String action)
{
this.actions.put(slot, action);
@@ -105,17 +270,45 @@ public abstract class AbstractGui {
inv.setItem(slot, item);
}
+ /**
+ * Registers a slot as a managed one.
+ *
+ * When such a slot is clicked by the player, the {@link #onClick(Player, ItemStack, String, ClickType, InventoryAction, InventoryClickEvent)}
+ * method is called (and all methods with the same name and less arguments).
+ *
+ * @param inv The inventory the item will be added to.
+ * @param item The {@link ItemStack} displayed in this slot.
+ * @param slot The slot this item will be added to.
+ * @param action The action associated with this slot, retrieved with the {@link #onClick(Player, ItemStack, String)] methods.
+ */
public void setSlotData(Inventory inv, ItemStack item, int slot, String action)
{
this.actions.put(slot, action);
inv.setItem(slot, item);
}
+ /**
+ * Registers a slot as a managed one, using the default inventory.
+ *
+ * When such a slot is clicked by the player, the {@link #onClick(Player, ItemStack, String, ClickType, InventoryAction, InventoryClickEvent)}
+ * method is called (and all methods with the same name and less arguments).
+ *
+ * @param item The {@link ItemStack} displayed in this slot.
+ * @param slot The slot this item will be added to.
+ * @param action The action associated with this slot, retrieved with the {@link #onClick(Player, ItemStack, String)] methods.
+ */
public void setSlotData(ItemStack item, int slot, String action)
{
setSlotData(this.inventory, item, slot, action);
}
+ /**
+ * Returns the registered action associated with the given slot.
+ *
+ * @param slot The slot.
+ *
+ * @return The action; {@code null} if there isn't any action registered to this slot.
+ */
public String getAction(int slot)
{
if (!this.actions.containsKey(slot))
@@ -124,15 +317,27 @@ public abstract class AbstractGui {
return this.actions.get(slot);
}
+ /**
+ * Returns the slot registered to the given action.
+ *
+ * @param action The action.
+ *
+ * @return The slot; {@code -1} if this action is not registered.
+ */
public int getSlot(String action)
{
for (int slot : this.actions.keySet())
if (this.actions.get(slot).equals(action))
return slot;
- return 0;
+ return -1;
}
+ /**
+ * Returns the default inventory.
+ *
+ * @return The inventory.
+ */
public Inventory getInventory()
{
return this.inventory;
diff --git a/src/main/java/fr/moribus/imageonmap/gui/core/GuiListener.java b/src/main/java/fr/moribus/imageonmap/gui/core/GuiListener.java
index 2201cb8..5018408 100644
--- a/src/main/java/fr/moribus/imageonmap/gui/core/GuiListener.java
+++ b/src/main/java/fr/moribus/imageonmap/gui/core/GuiListener.java
@@ -18,12 +18,15 @@
package fr.moribus.imageonmap.gui.core;
-import fr.moribus.imageonmap.*;
-import org.bukkit.*;
-import org.bukkit.entity.*;
-import org.bukkit.event.*;
-import org.bukkit.event.inventory.*;
-import org.bukkit.inventory.*;
+import org.bukkit.Material;
+import org.bukkit.entity.Player;
+import org.bukkit.event.EventHandler;
+import org.bukkit.event.Listener;
+import org.bukkit.event.inventory.InventoryClickEvent;
+import org.bukkit.event.inventory.InventoryCloseEvent;
+import org.bukkit.event.inventory.InventoryDragEvent;
+import org.bukkit.inventory.PlayerInventory;
+import org.bukkit.plugin.Plugin;
/**
@@ -33,7 +36,7 @@ import org.bukkit.inventory.*;
*/
public class GuiListener implements Listener {
- public static void init(ImageOnMap plugin)
+ public static void init(Plugin plugin)
{
plugin.getServer().getPluginManager().registerEvents(new GuiListener(), plugin);
}
@@ -65,7 +68,7 @@ public class GuiListener implements Listener {
}
- /* *** Click on the “chest” *** */
+ /* *** Click on the GUI inventory *** */
if(event.getCursor() != null && event.getCursor().getType() != Material.AIR)
{
diff --git a/src/main/java/fr/moribus/imageonmap/gui/core/GuiManager.java b/src/main/java/fr/moribus/imageonmap/gui/core/GuiManager.java
index 7427b3c..4b2ae1a 100644
--- a/src/main/java/fr/moribus/imageonmap/gui/core/GuiManager.java
+++ b/src/main/java/fr/moribus/imageonmap/gui/core/GuiManager.java
@@ -18,29 +18,44 @@
package fr.moribus.imageonmap.gui.core;
-import fr.moribus.imageonmap.*;
-import org.bukkit.entity.*;
+import org.bukkit.entity.HumanEntity;
+import org.bukkit.entity.Player;
+import org.bukkit.plugin.Plugin;
-import java.util.*;
-import java.util.concurrent.*;
+import java.util.Map;
+import java.util.UUID;
+import java.util.concurrent.ConcurrentHashMap;
/**
- * @author IamBlueSlime (thanks c:)
+ * A tool to easily manage GUIs.
*
- * Changes by Amaury Carrade to use statics (beh, code style, these things).
+ * @author IamBlueSlime and Amaury Carrade.
*/
public class GuiManager {
protected static Map<UUID, AbstractGui> currentGUIs;
- public static void init(ImageOnMap plugin)
+ /**
+ * Call this when the plugin is enabled.
+ *
+ * @param plugin The plugin using this.
+ */
+ public static void init(Plugin plugin)
{
currentGUIs = new ConcurrentHashMap<>();
GuiListener.init(plugin);
}
+ /**
+ * Opens a GUI for the given player.
+ *
+ * Closes any GUI already open for this player.
+ *
+ * @param player The player this GUI will be open to.
+ * @param gui The GUI to open.
+ */
public static void openGui(Player player, AbstractGui gui)
{
if (currentGUIs.containsKey(player.getUniqueId()))
@@ -50,21 +65,41 @@ public class GuiManager {
gui.display(player);
}
+ /**
+ * Closes the currently open GUI of this player, if it exists.
+ *
+ * Without any open GUI for this player, does nothing.
+ *
+ * @param player The player.
+ */
public static void closeGui(Player player)
{
player.closeInventory();
removeClosedGui(player);
}
+ /**
+ * Calls the {@link AbstractGui#onClose(Player)} method of the currently open GUI of the
+ * given {@link Player} and unregisters it as open.
+ *
+ * @param player The player
+ */
public static void removeClosedGui(Player player)
{
if (currentGUIs.containsKey(player.getUniqueId()))
{
+ //noinspection ConstantConditions
getPlayerGui(player).onClose(player);
currentGUIs.remove(player.getUniqueId());
}
}
+ /**
+ * Returns the currently open {@link AbstractGui} of the given {@link HumanEntity}.
+ *
+ * @param player The HumanEntity.
+ * @return The open GUI, or {@code null} if no GUI are open.
+ */
public static AbstractGui getPlayerGui(HumanEntity player)
{
if (currentGUIs.containsKey(player.getUniqueId()))
@@ -73,6 +108,11 @@ public class GuiManager {
return null;
}
+ /**
+ * Returns all open GUIs.
+ *
+ * @return The GUI (map: player's {@link UUID} → {@link AbstractGui}).
+ */
public static Map<UUID, AbstractGui> getPlayersGui()
{
return currentGUIs;
diff --git a/src/main/java/fr/moribus/imageonmap/gui/core/GuiUtils.java b/src/main/java/fr/moribus/imageonmap/gui/core/GuiUtils.java
index 1453585..95d7c23 100644
--- a/src/main/java/fr/moribus/imageonmap/gui/core/GuiUtils.java
+++ b/src/main/java/fr/moribus/imageonmap/gui/core/GuiUtils.java
@@ -48,6 +48,12 @@ public class GuiUtils {
}
}
+ /**
+ * Removes the vanilla informations displayed on the tooltips of the given item,
+ * like enchantments, map infos, etc.
+ *
+ * @param stack The item.
+ */
public static void removeVanillaInfos(ItemStack stack)
{
ItemMeta meta = stack.getItemMeta();
@@ -55,6 +61,12 @@ public class GuiUtils {
stack.setItemMeta(meta);
}
+ /**
+ * Removes the vanilla informations displayed on the tooltips of the given item,
+ * like enchantments, map infos, etc.
+ *
+ * @param meta The item's metadata.
+ */
public static void removeVanillaInfos(ItemMeta meta)
{
if(!supported) return;