Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
library:inventorygui:start [2020/09/21 18:16]
external edit
library:inventorygui:start [2021/01/20 14:02] (current)
phoenix616 [Maven Information]
Line 8: Line 8:
  
 ## Using InventoryGui ## Using InventoryGui
-Take a look at the examples below to learn how to create a GUI with this library or use the [InventoryGui Javadocs](https://docs.phoenix616.dev/inventorygui/).+Take a look at [the examples](/library:inventorygui:usage) to learn how to create a GUI with this library or use the [InventoryGui Javadocs](https://docs.phoenix616.dev/inventorygui/).
  
-### Defining the GUI setup +## Maven Information
-Every line in the array define the line in the inventory chest interface.  +
- +
-The characters are getting assigned to certain elements laters, similar to how recipes are defined. +
-Any empty slot will be filled with a filler character that you can also define yourself. +
- +
-```java +
-String[] guiSetup = { +
-    "  s i z  ", +
-    "  ggggg  ", +
-    "  fpdnl  " +
-}; +
-``` +
- +
-The GUI supports 3\*3, 5\*1 and 9\*x inventory sizes. +
-Sizes that do not match these are getting expanded to the next bigger one. +
- +
-### Creating the GUI +
-You create GUIs assigned to an InventoryHolder like a Container or a LivingEntity.  +
- +
-If the holder is `null` then you are not able to retrieve the GUI by the holder via `InventoryGui.get(holder)`. +
- +
-```java +
-InventoryGui gui = new InventoryGui(yourPlugin, theInventoryHolder, guiTitle, guiSetup); +
-gui.setFiller(new ItemStack(Material.GRAY_STAINED_GLASS, 1)); // fill the empty slots with this +
-``` +
- +
-### Adding to the GUI +
-You can add certain GUI elements to the GUI which will be assigned to a certain character from the setup. +
-With these elements you define the actions that should happen when the player interacts with the element. +
-E.g. you can run some code when the player clicks it. Some elements (like the state one) have predefined +
-actions that happen when they are clicked. (e.g. toggling between the possible states) +
- +
-#### Static Element +
-A simple, static element that runs some action when it is clicked. +
-```java +
-gui.addElement(new StaticGuiElement('s', +
-        new ItemStack(Material.REDSTONE), +
-        42, // Display a number as the item count +
-        click -> { +
-            if (click.getEvent().getWhoClicked().getName().equals("Redstone") { +
-                click.getEvent().getWhoClicked().sendMessage(ChatColor.RED + "I am Redstone!"); +
-                return true; // returning true will cancel the click event and stop taking the item +
-            } +
-            return false; // returning false will not cancel the initial click event to the gui +
-        }, +
-        "You can add lines describing this element here!", +
-        "The first line is displayed as the displayname,", +
-        "any additional ones as the lore!", +
-        "Any text the ItemStack had will be overwritten." +
-));  +
-``` +
-All of these arguments (besides the ItemStack) are optional. +
-See the docs for more details on the available convenience constructors.  +
- +
-#### Storage Element +
-An Element that directly accesses the holder inventory. +
-This can be used to handle placing and retrieving items from parts of a GUI as if that part +
-was a normal inventory. You can even back the element by a virtual Bukkit inventory instead +
-of a real one! +
- +
-If the element is displayed only in one slot it will show the first item in the inventory. +
-In two slots the first two and so on. +
-```java +
-// With an existing holder (e.g. block or entity) +
-gui.addElement(new GuiStorageElement('i', theInventoryHolder.getInventory())); +
- +
-// With a virtual inventory to access items later on +
-Inventory inv = Bukkit.createInventory(null, InventoryType.CHEST); +
-gui.addElement(new GuiStorageElement('i', inv)); +
-gui.setCloseAction(close -> { +
-    saveInv(inv); // Save inventory content or process it in some other way +
-    return false; // Don't go back to the previous GUI (true would automatically go back to the previously opened one) +
-}); +
-``` +
-#### State Element +
-An element that can have certain states that trigger some code when changed to. +
-and automatically changes the ItemStack icon. +
-```java +
-gui.addElement(new GuiStateElement('z',  +
-        new GuiStateElement.State( +
-                change -> { +
-                    change.getEvent().getWhoClicked().setFlying(true); +
-                    change.getEvent().getWhoClicked().sendMessage("You are now flying!"); +
-                }, +
-                new ItemStack(Material.WOOL, 1, 5), // the item to display as an icon +
-                "flyingEnabled", // a key to identify this state by +
-                ChatColor.GREEN + "Enable flying!", // explanation text what this element does +
-                "By clicking here you will start flying" +
-        ), +
-        new GuiStateElement.State( +
-                change -> { +
-                    change.getEvent().getWhoClicked().setFlying(false); +
-                    change.getEvent().getWhoClicked().sendMessage("You are no longer flying!"); +
-                }, +
-                new ItemStack(Material.WOOL, 1, 14), +
-                "flyingDisabled", +
-                ChatColor.RED + "Disable flying!", +
-                "By clicking here you will stop flying" +
-        ) +
-)); +
-``` +
-... you can define as many states as you want, they will cycle through on each click +
-you can also set the state directly via `GuiStateElement#setState(String key)` +
- +
-#### Dynamic Element +
-You can also dynamically load elements each time the GUI is re-drawn. E.g. when you want to cache GUIs but not the  +
-text of some buttons or dynamically change them while they are open without closing and reopening them. +
- +
-Dynamic elements just return one of the other elements that should be displayed each time `InventoryGui#draw` is called. +
-The slot character for the returned element doesn't really play a role, it is recommended to set it to +
-the DynamicGuiElement's slot character though. +
-```java +
-gui.addElement(new DynamicGuiElement('d', () -> { +
-    return new StaticGuiElement('d', new ItemStack (Material.CLOCK),  +
-        click -> { +
-            click.getGui().draw(); // Update the GUI +
-            return true; +
-        },  +
-        "Update time: " + new SimpleDateFormat("HH:mm:ss").format(new Date())); +
-})); +
-``` +
-As you can see you can change the content of a DynamicGuiElement after a player click on it by calling `InventoryGui#draw` in the action of the supplied element. +
- +
-#### Element Group +
-A group can contain multiple different elements and if there are more elements in the group than display slot you can use the GuiPageElement to switch between pages. +
- +
-```java +
-GuiElementGroup group = new GuiElementGroup('g'); +
-for (String text : texts) { +
-    // Add an element to the group +
-    // Elements are in the order they got added to the group and don't need to have the same type. +
-    group.addElement((new StaticGuiElement('e', new ItemStack(Material.DIRT), text); +
-+
-gui.addElement(group); +
-``` +
-##### Pagination +
-It will automatically detect GuiElementGroup elements with more elements in them than available slots with that character in the GUI and go to the according page on click. (depending on type) +
-There are also some pagination specific placeholders available for the element descriptions. +
- +
-```java +
-// First page +
-gui.addElement(new GuiPageElement('f', new ItemStack(Material.ARROW), PageAction.FIRST, "Go to first page (current: %page%)")); +
- +
-// Previous page +
-gui.addElement(new GuiPageElement('p', new ItemStack(Material.SIGN), PageAction.PREVIOUS, "Go to previous page (%prevpage%)")); +
- +
-// Next page +
-gui.addElement(new GuiPageElement('n', new ItemStack(Material.SIGN), PageAction.NEXT, "Go to next page (%nextpage%)")); +
- +
-// Last page +
-gui.addElement(new GuiPageElement('l', new ItemStack(Material.ARROW), PageAction.LAST, "Go to last page (%pages%)")); +
-``` +
- +
-### Retrieving and showing the GUI +
-After you have created the GUI you can retrieve it with the original holder and show it to a player. +
-```java +
-InventoryGui gui = InventoryGui.get(InventoryHolder holder); +
-gui.show(player); +
-``` +
-Obviously you can also show the GUI directly after creating it. +
- +
-## Depending on InventoryGui with maven+
 You can easily depend on the library with maven. You can easily depend on the library with maven.
 ```xml ```xml
Line 188: Line 26:
         <artifactId>inventorygui</artifactId>         <artifactId>inventorygui</artifactId>
         <!--The following version may not be the latest. Check it before using.-->         <!--The following version may not be the latest. Check it before using.-->
-        <version>1.4.2-SNAPSHOT</version>+        <version>1.4.3-SNAPSHOT</version>
         <scope>compile</scope>         <scope>compile</scope>
     </dependency>     </dependency>
 </dependencies> </dependencies>
 ``` ```
-As this is not a stadalone plugin you have to shade it into your plugin!+As this is not a standalone plugin you have to shade it into your plugin and relocate it into your own package to avoid conflicts! 
 E.g. with the maven-shade-plugin [like this](https://github.com/Minebench/Pipes/blob/048337e7594684353e7360411b1ef6ba8e7223c4/pom.xml#L63-L82). E.g. with the maven-shade-plugin [like this](https://github.com/Minebench/Pipes/blob/048337e7594684353e7360411b1ef6ba8e7223c4/pom.xml#L63-L82).