Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
library:inventorygui [2020/09/14 23:15] phoenix616library:inventorygui [Unknown date] (current) – removed - external edit (Unknown date) 127.0.0.1
Line 1: Line 1:
-# InventoryGui 
-A library that simplifies the creation of chest GUIs for Bukkit/Spigot plugins and  
-allows assigning of the GUI to a specific InventoryHolder. If you are in need of a GUI for text inputs then take a look at [WesJD](https://github.com/WesJD)'s [AnvilGUI](https://github.com/WesJD/AnvilGUI) library. 
  
-Requires Java 8. 
- 
-[GitHub repository](https://github.com/Phoenix616/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/). 
- 
-### Defining the GUI setup 
-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. 
-```xml 
-<repositories> 
-    <repository> 
-        <id>minebench-repo</id> 
-        <url>https://repo.minebench.de/</url> 
-    </repository> 
-</repositories> 
-``` 
-```xml 
-<dependencies> 
-    <dependency> 
-        <groupId>de.themoep</groupId> 
-        <artifactId>inventorygui</artifactId> 
-        <!--The following version may not be the latest. Check it before using.--> 
-        <version>1.4.2-SNAPSHOT</version> 
-        <scope>compile</scope> 
-    </dependency> 
-</dependencies> 
-``` 
-As this is not a stadalone plugin you have to shade it into your plugin! 
-E.g. with the maven-shade-plugin [like this](https://github.com/Minebench/Pipes/blob/048337e7594684353e7360411b1ef6ba8e7223c4/pom.xml#L63-L82). 
- 
-You can also get development builds directly from the [Minebench Jenkins ci server](https://ci.minebench.de/job/InventoryGui/) 
-if you want to manually add it to your project but I strongly advise using a dependency management tool like maven or gradle! 
- 
-## License 
-InventoryGui is licensed under the following, MIT license: 
- 
-``` 
-Copyright 2017 Max Lee (https://github.com/Phoenix616) 
- 
-Permission is hereby granted, free of charge, to any person obtaining a copy 
-of this software and associated documentation files (the "Software"), to deal 
-in the Software without restriction, including without limitation the rights 
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
-copies of the Software, and to permit persons to whom the Software is 
-furnished to do so, subject to the following conditions: 
- 
-The above copyright notice and this permission notice shall be included in all 
-copies or substantial portions of the Software. 
- 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
-SOFTWARE. 
-```