Package com.ultikits.ultitools.abstracts.gui.declarative.engine

Class DeclarativeGui

java.lang.Object
mc.obliviate.inventory.Gui
com.ultikits.ultitools.abstracts.gui.declarative.engine.DeclarativeGui
All Implemented Interfaces:
org.bukkit.inventory.InventoryHolder
Direct Known Subclasses:
StatefulDeclarativeGui
public abstract class DeclarativeGui extends mc.obliviate.inventory.Gui
DeclarativeGui is the base class of the declarative GUI framework.

It extends obliviate-invs' Gui, layering declarative UI capability on top. A subclass only needs to implement build(BuildContext), returning a Widget tree.

Usage example: 


 public class ShopPage extends DeclarativeGui {
     private final List<ItemStack> items;

     public ShopPage(Player player, List<ItemStack> items) {
         super(player, "shop", "Shop", 6);
         this.items = items;
     }

     @Override
     public Widget build(BuildContext context) {
         return Column.builder()
             .children(
                 // Title row
                 Center.builder()
                     .child(TextDisplay.title("Item Shop"))
                     .build(),

                 // Item grid
                 GridView.builder()
                     .items(items)
                     .itemBuilder(item -> ItemButton.builder()
                         .item(item)
                         .onClick(() -> buyItem(item))
                         .build())
                     .build(),

                 // Pagination controls
                 Row.builder()
                     .children(
                         PrevPageButton.builder().build(),
                         PageIndicator.builder().build(),
                         NextPageButton.builder().build()
                     )
                     .build()
             )
             .build();
     }

     private void buyItem(ItemStack item) {
         // Purchase logic
         player.sendMessage("Bought " + item.getType());
     }
 }
Since:
6.2.0
Version:
1.0.0
Author:
UltiTools Team

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final @NotNull String
    id
     
    private boolean
    initialized
     
    private final GuiRenderer
    renderer
     

    Fields inherited from class mc.obliviate.inventory.Gui

    player

  • Constructor Summary

    Constructors
    Constructor
    Description
    DeclarativeGui(@NotNull org.bukkit.entity.Player player, @NotNull String id, @NotNull String title, int rows)
    Creates a DeclarativeGui.
    DeclarativeGui(@NotNull org.bukkit.entity.Player player, @NotNull String id, @NotNull String title, @NotNull org.bukkit.event.inventory.InventoryType inventoryType)
    Creates a DeclarativeGui.
    DeclarativeGui(@NotNull org.bukkit.entity.Player player, @NotNull String id, @NotNull net.kyori.adventure.text.Component title, int rows)
    Creates a DeclarativeGui with a Component title.
    DeclarativeGui(@NotNull org.bukkit.entity.Player player, @NotNull String id, @NotNull net.kyori.adventure.text.Component title, @NotNull org.bukkit.event.inventory.InventoryType inventoryType)
    Creates a DeclarativeGui with a Component title.

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract @NotNull Widget
    build(@NotNull BuildContext context)
    Builds the Widget tree.
    @NotNull org.bukkit.entity.Player
    getPlayer()
    Gets the player.
    protected @NotNull GuiRenderer
    getRenderer()
    Gets the renderer.
    boolean
    isInitialized()
    Checks whether this has been initialized.
    protected void
    markNeedsBuild()
    Marks that a rebuild is needed.
    final boolean
    onClick(@NotNull org.bukkit.event.inventory.InventoryClickEvent event)
    This is the framework's own bounds-check site (D-09 item 4), not a post-filter hook.
    final void
    onClose(@NotNull org.bukkit.event.inventory.InventoryCloseEvent event)
     
    protected boolean
    onGuiClick(@NotNull org.bukkit.event.inventory.InventoryClickEvent event)
    Hook method called on a GUI click.
    protected void
    onGuiClose(@NotNull org.bukkit.event.inventory.InventoryCloseEvent event)
    Hook method called when the GUI closes.
    protected void
    onGuiOpen(@NotNull org.bukkit.event.inventory.InventoryOpenEvent event)
    Hook method called when the GUI opens.
    final void
    onOpen(@NotNull org.bukkit.event.inventory.InventoryOpenEvent event)
     
    protected void
    setState(@NotNull Runnable action)
    Sets state and triggers a rebuild.

    Methods inherited from class mc.obliviate.inventory.Gui

    addItem, addItem, addItem, addItem, addItem, addItem, addItem, addItem, createInventory, createInventory, fillColumn, fillGui, fillGui, fillGui, fillGui, fillRow, getId, getInventory, getItems, getLastSlot, getPlugin, getSize, getTaskList, getTitle, isClosed, onDrag, open, runTaskLater, sendSizeUpdate, sendTitleUpdate, setClosed, setInventory, setSize, setTitle, stopAllTasks, stopTask, updateTask

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • id

      @NotNull protected final @NotNull String id

    • renderer

      private final GuiRenderer renderer

    • initialized

      private boolean initialized

  • Constructor Details

    • DeclarativeGui

      public DeclarativeGui(@NotNull @NotNull org.bukkit.entity.Player player, @NotNull @NotNull String id, @NotNull @NotNull String title, int rows)
      Creates a DeclarativeGui.
      Parameters:
      player - the player
      id - the GUI ID
      title - the title
      rows - the row count

    • DeclarativeGui

      public DeclarativeGui(@NotNull @NotNull org.bukkit.entity.Player player, @NotNull @NotNull String id, @NotNull @NotNull String title, @NotNull @NotNull org.bukkit.event.inventory.InventoryType inventoryType)
      Creates a DeclarativeGui.
      Parameters:
      player - the player
      id - the GUI ID
      title - the title
      inventoryType - the inventory type

    • DeclarativeGui

      public DeclarativeGui(@NotNull @NotNull org.bukkit.entity.Player player, @NotNull @NotNull String id, @NotNull @NotNull net.kyori.adventure.text.Component title, int rows)
      Creates a DeclarativeGui with a Component title.
      Parameters:
      player - the player
      id - the GUI ID
      title - the title (Component)
      rows - the row count

    • DeclarativeGui

      public DeclarativeGui(@NotNull @NotNull org.bukkit.entity.Player player, @NotNull @NotNull String id, @NotNull @NotNull net.kyori.adventure.text.Component title, @NotNull @NotNull org.bukkit.event.inventory.InventoryType inventoryType)
      Creates a DeclarativeGui with a Component title.
      Parameters:
      player - the player
      id - the GUI ID
      title - the title (Component)
      inventoryType - the inventory type

  • Method Details

    • build

      @NotNull public abstract @NotNull Widget build(@NotNull @NotNull BuildContext context)
      Builds the Widget tree.

      Subclasses must implement this method, returning the Widget tree describing the UI. This method is called again every time the state changes.

      Parameters:
      context - the build context, carrying the player, GUI configuration, and similar info
      Returns:
      the Widget tree

    • onOpen

      public final void onOpen(@NotNull @NotNull org.bukkit.event.inventory.InventoryOpenEvent event)
      Overrides:
      onOpen in class mc.obliviate.inventory.Gui

    • onClose

      public final void onClose(@NotNull @NotNull org.bukkit.event.inventory.InventoryCloseEvent event)
      Overrides:
      onClose in class mc.obliviate.inventory.Gui

    • onClick

      public final boolean onClick(@NotNull @NotNull org.bukkit.event.inventory.InventoryClickEvent event)
      This is the framework's own bounds-check site (D-09 item 4), not a post-filter hook. A subclass overriding this method needs to know that obliviate-invs' InvListener calls this method unconditionally, BEFORE it applies any bounds check of its own — so every click reaches here, including a click in the player's own inventory. The actual check happens one call down, in GuiRenderer.handleClick(org.bukkit.event.inventory.InventoryClickEvent): it rejects (returns without dispatching) any click whose raw slot falls outside the GUI's own inventory, so a click on the player's own inventory can never reach a GUI handler here.
      Overrides:
      onClick in class mc.obliviate.inventory.Gui
      Parameters:
      event - the click event
      Returns:
      see onGuiClick(InventoryClickEvent)

    • markNeedsBuild

      protected void markNeedsBuild()
      Marks that a rebuild is needed.

      Typically called in a subclass to trigger a UI update when data changes.

    • setState

      protected void setState(@NotNull @NotNull Runnable action)
      Sets state and triggers a rebuild.

      This is the Flutter-style approach to state management. Modify state inside the callback, and the framework automatically triggers a rebuild.

      Usage example: 

      
 setState(() -> {
     counter++;          // modify state
     selectedItem = item;
 });
      Parameters:
      action - the state-modifying operation

    • onGuiOpen

      protected void onGuiOpen(@NotNull @NotNull org.bukkit.event.inventory.InventoryOpenEvent event)
      Hook method called when the GUI opens.

      Subclasses may override this to perform extra initialization work.

      Parameters:
      event - the open event

    • onGuiClose

      protected void onGuiClose(@NotNull @NotNull org.bukkit.event.inventory.InventoryCloseEvent event)
      Hook method called when the GUI closes.

      Subclasses may override this to perform cleanup work.

      Parameters:
      event - the close event

    • onGuiClick

      protected boolean onGuiClick(@NotNull @NotNull org.bukkit.event.inventory.InventoryClickEvent event)
      Hook method called on a GUI click.

      Note: the click event is handled by the declarative framework first, before this method is called.

      The return value reads backwards, so read it carefully: returning false keeps the event cancelled and the player cannot take the clicked item; returning true lets the click through and the item can be taken. The semantics come from obliviate-invs, whose InvListener calls setCancelled(false) when Gui.onClick returns true and setCancelled(true) when it returns false. The default of false matches the library base class and is the safe side.

      Parameters:
      event - the click event
      Returns:
      false keeps the event cancelled (default, item cannot be taken); true lets it through

    • getRenderer

      @NotNull protected @NotNull GuiRenderer getRenderer()
      Gets the renderer.
      Returns:
      the GuiRenderer

    • isInitialized

      public boolean isInitialized()
      Checks whether this has been initialized.
      Returns:
      true if initialized

    • getPlayer

      @NotNull public @NotNull org.bukkit.entity.Player getPlayer()
      Gets the player.
      Returns:
      the player