ButtonStates

Each Button consists of at least one ButtonState.
These states describe the state a Button can be in. Their task is to:

• To store all the necessary data to render it (id, GuiCluster, ItemStack), and
• to call Button Functions to run custom code.

Most of the Buttons provide a constructor without the need to create a new ButtonState object manually.
Buttons like Toggle- and MultipleChoiceButtons require you to create new instances of the ButtonState.

Sometimes however it can be useful for other Buttons too, for example, if you want to use the language key of another ButtonState (To prevent duplicate language keys).

Button Functions

ButtonStates can contain specific functions that are called when they are interacted with, rendered, etc.

• ButtonAction: Called when affected by InventoryInteractEvent
• ButtonPostAction: Called 1 tick after ButtonAction. But only if ButtonAction was actually called!
• ButtonPreRender: Called before the Button is rendered, with inventory from the previous render.
• ButtonRender: Called whenever the Button is rendered.

ButtonAction

They execute code when affected by the InventoryInteractionEvent and return a boolean to cancel or allow the event.

/**
 * @param <C> The type of the {@link CustomCache}
 */
public interface ButtonAction<C extends CustomCache> {

    /**
     * @param cache      The current cache of the GuiHandler.
     * @param guiHandler The current GuiHandler.
     * @param player     The current Player.
     * @param inventory  The original/previous inventory. No changes to this inventory will be applied on render!
     * @param slot       The slot in which the button is rendered.
     * @param event      The previous event of the click that caused the update. Can be a InventoryClickEvent or InventoryDragEvent
     * @return a boolean indicating whether the interaction should be cancelled. If true the interaction is cancelled.
     * @throws IOException if an error occurs on the execution.
     */
    boolean run(C cache, GuiHandler<C> guiHandler, Player player, GUIInventory<C> inventory, int slot, InventoryInteractEvent event) throws IOException;
}

ButtonPostAction

This interface is identical to the ButtonAction, however, the behavior is different as it is similar to ButtonPreRender.
It is called 1 tick after the execution, right before the ButtonPreRender, and only if the button was clicked!
It can be used for caching or other code that needs to be executed just before render, but only after execution happened, to prepare data for the next render.
For example it can be used for setting items into cache for something like item input see ItemInputButton

/**
 * @param <C> The type of the {@link CustomCache}
 */
public interface ButtonPostAction<C extends CustomCache> {

    /**
     * @param cache      The current cache of the GuiHandler.
     * @param guiHandler The current GuiHandler.
     * @param player     The current Player.
     * @param inventory  The original/previous inventory. No changes to this inventory will be applied on render!
     * @param slot       The slot in which the button is rendered.
     * @param event      The previous event of the click that caused the update. Can be a InventoryClickEvent or InventoryDragEvent
     * @throws IOException if an error occurs on the execution.
     */
    void run(C cache, GuiHandler<C> guiHandler, Player player, GUIInventory<C> inventory, ItemStack itemStack, int slot, InventoryInteractEvent event) throws IOException;

}

ButtonPreRender

They are called before the ButtonRender method, but it provides the previous Inventory with the items of last render.

/**
 * @param <C> The type of the {@link CustomCache}
 */
public interface ButtonPreRender<C extends CustomCache> {

    /**
     * This method is run before the render method and provides the previous inventory, which includes all the items of last render.
     * <br>
     * It can be used for caching or other code that needs to be executed just before render, requires items from last render or needs to prepare data for the next render.
     * <br>
     * For example it can be used for setting items into cache for something like item input see {@link ItemInputButton}
     * <br>
     * .
     *
     * @param cache       The current cache of the GuiHandler
     * @param guiHandler  The current GuiHandler.
     * @param player      The current Player.
     * @param inventory   The original/previous inventory. No changes to this inventory will be applied on render!
     * @param itemStack   The original/previous item stack. No changes to this item stack will be applied on render!
     * @param slot        The slot in which the button is rendered.
     * @param helpEnabled Returns true if help is enabled.
     */
    void prepare(C cache, GuiHandler<C> guiHandler, Player player, GUIInventory<C> inventory, ItemStack itemStack, int slot, boolean helpEnabled);
}

ButtonRender

Are called whenever the Button is rendered into the Inventory. They allow to manipulate the items and replace placeholders for example.

/**
 * @param <C> The type of the {@link CustomCache}
 */
public interface ButtonRender<C extends CustomCache> {

    /**
     * Run when the button is rendered into the GUI.
     * The returned ItemStack will be set into the slot of the button.
     * Using the values HashMap you can replace specific Strings in the item names (e.g. replace placeholder from language file) with custom values.
     *
     * @param values       The HashMap, which contains the Strings, that will be replaced with it's value.
     * @param cache        The current cache of the GuiHandler
     * @param guiHandler   The current GuiHandler.
     * @param player       The current Player.
     * @param guiInventory The GUIInventory in which this render was called from.
     * @param itemStack    The current itemsStack of the button.
     * @param slot         The slot in which the button is rendered.
     * @param helpEnabled  Returns true if help is enabled.
     * @return The itemStack that should be set into the GUI.
     */
    ItemStack render(HashMap<String, Object> values, C cache, GuiHandler<C> guiHandler, Player player, GUIInventory<C> guiInventory, ItemStack itemStack, int slot, boolean helpEnabled);
}