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.

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.

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

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)

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.

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)
});

An element that can have certain states that trigger some code when changed to. and automatically changes the ItemStack icon.

snippet.java

GuiStateElement element = 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"
        )
);
 
# Set the current state
if (player.isFlying()) {
    element.setState("flyingEnabled");
} else {
    element.setState("flyingDisabled");
}
 
gui.addElement(element);

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) before you show the GUI or re-draw it.

You can also dynamically load elements each time the GUI is re-drawn and for each viewing player individually. E.g. when you want to cache GUIs but not the text of some buttons, display different elements per player 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.

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);

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%)"));

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.