Button - landonjw/GooeyLibs GitHub Wiki

A button represents an item on the page, and can have behavior that will be invoked when the button is clicked. These can be reused several times on several different pages, and is encouraged to do so.

Creating a Button

The default implementation of a Button in GooeyLibs is GooeyButton. These buttons allow you to specify methods that are invoked when the button is clicked, and how the button should appear on the interface.

An example of creating a GooeyButton is:

Button button = GooeyButton.builder()
        .display(new ItemStack(Items.DIAMOND)) // Makes the item take on the appearance of a diamond
        .title("Hello") // Makes the title of the button "Hello"
        .lore(Arrays.asList("Line 1", "Line 2")) // Specifies the lore lines of the item.
        .onClick(() -> doStuff()) // Makes the button invoke doStuff when it is clicked.
        .build();

Button Actions

A ButtonAction object is instantiated any time a button is clicked in a Gooey interface, and is passed to the onClick method, providing context on who interacted with the button, where it was interacted with, and how it was interacted.

An example use of ButtonAction is:

Button button = GooeyButton.builder()
        .display(new ItemStack(Items.DIAMOND))
        .onClick((action) -> {
            EntityPlayerMP player = action.getPlayer(); // The player who clicked the button
            ClickType clickType = action.getClickType(); // The type of click on the button
            Button button = action.getButton(); // The button instance
            Page page = action.getPage(); // The page the button was on when clicked
            // Do Stuff
        })
        .build();

Rate Limiting

A RateLimitedButton is a special button that decorates another Button implementation. This allows for wrapping the button and specifying a rate limit. When this limit is exceeded, it will no longer invoke the onClick methods provided.

If a RateLimitedButton instance is shared among several templates, it's rate limit will also be shared. For example, if Player 1 clicks a RateLimitedButton with a limit of 3 clicks per 10 seconds, Player 2 will only be able to click twice in that time frame.

An example of using a RateLimitedButton is:

Button base = GooeyButton.builder()
    .display(new ItemStack(Items.DIAMOND))
    .onClick(() -> System.out.println("Hello world"))
    .build();

// Creates a rate limited button that can only be invoked 3 times every 10 seconds.
RateLimitedButton button = RateLimitedButton.builder()
    .button(base)
    .limit(3)
    .interval(10, TimeUnit.SECONDS)
    .build();

In this example, when the rate limited button is clicked it will print "Hello world". This button will only allow for "Hello" to be printed 3 times every 10 seconds. If it is pressed more than 3 times, it will not execute the code.

Placeholder Buttons

A PlaceholderButton is a special Button used for LinkedPages. It is not recommended to use this outside of that purpose. This button functions as a button to be substituted by another button for pagination. For example, you want to fill pages with a large amount of items. You would define the area you want those items to population with PlaceholderButtons, and use the LinkedPageHelper to replace those buttons.

You can specify a certain Button for the Placeholder to represent, in the case it is not replaced, or have it represented as an empty slot.

An example of creating a PlaceholderButton is:

PlaceholderButton placeholder1 = new PlaceholderButton();

GooeyButton base = GooeyButton.builder()
    .display(new ItemStack(Items.DIAMOND))
    .title("Hello")
    .onClick(() -> System.out.println("Hello"))
    .build();

PlaceholderButton placeholder2 = new PlaceholderButton(base);

The PlaceholderButton named placeholder1 will default to an empty slot with no functionality when it is not replaced.

The PlaceholderButton named placeholder2 will default to a diamond that prints "Hello" when clicked, when it is not replaced.

Player Inventory Listeners

An InventoryListenerButton is a Button that is used to interact with the player's inventory while a Page is open. This should only be used in the InventoryTemplate. This will take on the display of the current inventory item but will allow for adding extra functionality on slot click. An example of creating and using a InventoryListenerButton is:

InventoryListenerButton button = new InventoryListenerButton(() -> {
    System.out.println("Hello world!");
});
InventoryTemplate template = InventoryTemplate.builder()
    .set(0, button)
    .build();

In this example, the first slot in the player's inventory will display whatever is in the player's actual inventory, but when clicked, will print out "Hello".

Updating a Button

You can invoke update on a ButtonBase in order to have it update any changes to all players viewing the button. In default implementations, invoking the setDisplay method will automatically update the button for all viewers.

An example of forcefully calling an update is

GooeyButton button = GooeyButton.builder()
    .display(new ItemStack(Items.DIAMOND))
    .build();

// Create page and send to player1 and player2

button.update(); // This will send a call to update the button for player1 and player2.

Custom Buttons

You are able to implement custom buttons through the use of ButtonBase or implementing Button. This allows for storing any additional state and behaviour on the button itself and prevents any complex cases with the functional use of the API. An example of implementing this class is:

public class ExampleButton extends ButtonBase {

    private boolean active;

    protected ExampleButton() {
        super(new ItemStack(Items.DIAMOND));
    }

    @Override
    public void onClick(@Nonnull ButtonAction action) {
        if(active) {
            setDisplay(new ItemStack(Items.DIAMOND));
        }
        else{
            setDisplay(new ItemStack(Items.EMERALD));
        }
        active = !active;
    }

}

In this example, the button will change items depending on internal state, whenever it is clicked. This button can then be added to templates of any type.