**This is an old revision of the document!**

How to use it

Take a look at the examples below to learn how to create a GUI with this library or use the InventoryGui Javadocs.

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.

snippet.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).

snippet.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.

snippet.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.

snippet.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.

snippet.java
gui.addElement(new GuiStateElement('z', 
        new GuiStateElement.State(
                change -> {
                    change.getEvent().getWhoClicked().setFlying(true);
                    change.getEvent().getWhoClicked().sendMessage("You are now flying!");
                },
                "flyingEnabled", // a key to identify this state by
                new ItemStack(Material.WOOL, 1, 5), // the item to display as an icon
                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!");
                },
                "flyingDisabled",
                new ItemStack(Material.WOOL, 1, 14),
                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.

snippet.java
gui.addElement(new DynamicGuiElement('d', (viewer) -> {
    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.

snippet.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.

snippet.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.

snippet.java
InventoryGui gui = InventoryGui.get(InventoryHolder holder);
gui.show(player);

Obviously you can also show the GUI directly after creating it.