DInventory API

For a full list of wiki pages, see the Home page.

DInventory API

The DInventory class is a powerful custom inventory implementation that provides a wrapper around Bukkit's Inventory. It simplifies the creation and management of complex GUIs, offering features like multi-page support, persistent item storage, and custom event handling.

Creating a DInventory

You can create a DInventory with several constructor options.

// Simple, single-page inventory
DInventory inv = new DInventory("My GUI", 27, plugin);

// Multi-page inventory with default page tools
DInventory pagedInv = new DInventory("My Paged GUI", 54, true, true, plugin);

Constructors

• DInventory(String title, int size, DPlugin plugin): Creates a basic, single-page inventory.
• DInventory(String title, int size, boolean usePage, DPlugin plugin): Creates an inventory that can support pages. If the size is 18 or more, page tools are enabled.
• DInventory(String title, int size, boolean usePage, boolean useDefaultPageTools, DPlugin plugin): Creates a paged inventory and automatically adds default "Next" and "Previous" page items if useDefaultPageTools is true.

Working with Items

DInventory implements InventoryHolder and delegates many methods to the underlying Inventory, so you can use familiar methods like setItem(), addItem(), and getContents().

// Set an item in the current view
inv.setItem(0, new ItemStack(Material.DIAMOND));

// For paged inventories, set an item on a specific page and slot
pagedInv.setPageItem(0, 4, new ItemStack(Material.GOLD_INGOT)); // Page 0, Slot 4

Multi-Page Inventories

The key feature of DInventory is its robust support for multiple pages.

Adding Items and Pages

DPP-Core automatically handles page creation when you add items.

List<ItemStack> items = getLotsOfItems(); // A list of more than 54 items

// Add a list of items. DInventory will automatically create
// as many pages as needed to fit them all.
pagedInv.addPageItems(items);

Navigating Pages

• nextPage(): Moves to the next page.
• prevPage(): Moves to the previous page.
• goToPage(int page): Jumps to a specific page.

These methods are automatically handled by the default page tools, but you can also call them programmatically.

Page Tools

Page tools are special items, typically placed in the last row of a paged inventory, that control navigation. You can define your own tools or use the defaults.

// Create a custom 'next page' item
ItemStack next = ItemStackBuilder.of(Material.ARROW).name("&aNext Page").build();
NBT.setStringTag(next, "dppc_nextpage", "true"); // Special NBT tag

// Set the custom tool
pagedInv.setPageTool(8, next); // Last slot of the tool row
pagedInv.updatePageTools();

Special NBT Tags for Page Tools:

• dppc_nextpage: Marks an item as the "next page" button.
• dppc_prevpage: Marks an item as the "previous page" button.
• dppc_clickcancel: Makes an item un-clickable (cancels the click event).

DInventory Events

To handle interactions with your DInventory, you should listen for custom events instead of the standard Bukkit InventoryClickEvent.

• DInventoryClickEvent: Fired when a player clicks inside a DInventory.
• DInventoryOpenEvent: Fired when a player opens a DInventory.
• DInventoryCloseEvent: Fired when a player closes a DInventory.
• DInventoryNextPageEvent: Fired when the page is changed to the next one.
• DInventoryPreviousPageEvent: Fired when the page is changed to the previous one.

Example: Handling a Click

@EventHandler
public void onDInventoryClick(DInventoryClickEvent event) {
    // Check if this is the inventory you want to handle
    if (!event.getView().getTitle().equals("My GUI")) return;

    // Prevent players from taking items
    event.setCancelled(true);

    Player player = (Player) event.getWhoClicked();
    ItemStack clickedItem = event.getCurrentItem();

    if (clickedItem != null && clickedItem.getType() == Material.DIAMOND) {
        player.sendMessage("You clicked a diamond!");
        player.closeInventory();
    }
}

Serialization and Persistence

DInventory instances can be serialized to and from a YamlConfiguration, allowing you to save and load complex GUI layouts.

// Serialize the inventory to a YamlConfiguration
YamlConfiguration data = myInventory.serialize(new YamlConfiguration());

// Save it to a file
ConfigUtils.saveCustomData(plugin, data, "my_gui_layout", "guis");

// Load it back
YamlConfiguration loadedData = ConfigUtils.loadCustomData(plugin, "my_gui_layout", "guis");
if (loadedData != null) {
    DInventory loadedInv = new DInventory("My GUI", 54, plugin).deserialize(loadedData);
}