Class SGMenu

java.lang.Object
com.samjakob.spigui.menu.SGMenu
All Implemented Interfaces:
org.bukkit.inventory.InventoryHolder
public class SGMenu extends Object implements org.bukkit.inventory.InventoryHolder
SGMenu is used to implement the library's GUIs.

This is a Minecraft 'inventory' that contains items which can have programmable actions performed when they are clicked. Additionally, it automatically adds 'pagination' items if the menu overflows.

You do not instantiate this class when you need it - as you would have done with the older version of the library - rather you make a call to SpiGUI.create(String, int) or SpiGUI.create(String, int, String) from your plugin's SpiGUI instance.

This creates an inventory that is already associated with your plugin. The reason for this is explained in the SpiGUI(JavaPlugin) class constructor implementation notes.

  • Field Details

    • owner

      private final org.bukkit.plugin.java.JavaPlugin owner
      The plugin (owner of the SpiGUI instance) that created this inventory.

    • spiGUI

      private final SpiGUI spiGUI
      The SpiGUI instance that created this inventory.

    • name

      private String name
      The title of the inventory.

    • tag

      private String tag
      A tag that may be used to identify the type of inventory.

    • rowsPerPage

      private int rowsPerPage
      The number of rows to display per page.

    • items

      private final Map<Integer,SGButton> items
      The map of items in the inventory.

    • stickiedSlots

      private final HashSet<Integer> stickiedSlots
      The set of sticky slots (that should remain when the page is changed).

    • currentPage

      private int currentPage
      The currently selected page of the inventory.

    • blockDefaultInteractions

      private boolean blockDefaultInteractions
      Whether the "default" behaviors and interactions should be permitted or blocked. (True prevents default behaviors such as moving items in the inventory, false allows them).

    • enableAutomaticPagination

      private boolean enableAutomaticPagination
      Whether the pagination functionality should be enabled. (True adds pagination buttons when they're needed, false does not).

    • toolbarBuilder

      private SGToolbarBuilder toolbarBuilder
      The toolbar builder used to render this GUI's toolbar.

    • onClose

      private Consumer<SGMenu> onClose
      The action to be performed on close.

    • onPageChange

      private Consumer<SGMenu> onPageChange
      The action to be performed on page change.

    • permittedMenuClickTypes

      private HashSet<org.bukkit.event.inventory.ClickType> permittedMenuClickTypes
      Any click types not in this array will be immediately prevented in this menu without further processing (i.e., the button's listener will not be called).

    • blockedMenuActions

      private HashSet<org.bukkit.event.inventory.InventoryAction> blockedMenuActions
      Any actions in this list will be blocked immediately without further processing if they occur in a SpiGUI menu.

    • blockedAdjacentActions

      private HashSet<org.bukkit.event.inventory.InventoryAction> blockedAdjacentActions
      Any actions in this list will be blocked if they occur in the adjacent inventory to an SGMenu.

    • DEFAULT_PERMITTED_MENU_CLICK_TYPES

      private static final org.bukkit.event.inventory.ClickType[] DEFAULT_PERMITTED_MENU_CLICK_TYPES
      The default set of actions that are permitted if they occur in an SGMenu.

    • DEFAULT_BLOCKED_MENU_ACTIONS

      private static final org.bukkit.event.inventory.InventoryAction[] DEFAULT_BLOCKED_MENU_ACTIONS
      The default set of actions that are blocked if they occur in an SGMenu.

    • DEFAULT_BLOCKED_ADJACENT_ACTIONS

      private static final org.bukkit.event.inventory.InventoryAction[] DEFAULT_BLOCKED_ADJACENT_ACTIONS
      The default set of actions that are blocked if they occur in the adjacent inventory to an SGMenu.

  • Constructor Details

    • SGMenu

      public SGMenu(org.bukkit.plugin.java.JavaPlugin owner, SpiGUI spiGUI, String name, int rowsPerPage, String tag, org.bukkit.event.inventory.ClickType... clickTypes)
      Intended for internal use only. Use SpiGUI.create(String, int) or SpiGUI.create(String, int, String)!
      Used by the library internally to construct an SGMenu.
      The name parameter is color code translated.
      Parameters:
      owner - The JavaPlugin that owns this menu.
      spiGUI - The SpiGUI instance associated with this menu.
      name - The name of the menu.
      rowsPerPage - The number of rows per page in the menu.
      tag - The tag associated with this menu.
      clickTypes - The set of permitted click types.

  • Method Details

    • setBlockDefaultInteractions

      public void setBlockDefaultInteractions(boolean blockDefaultInteractions)
      This is a per-inventory version of SpiGUI.setBlockDefaultInteractions(boolean).
      Parameters:
      blockDefaultInteractions - Whether the default behavior of click events should be cancelled.
      See Also:

    • areDefaultInteractionsBlocked

      public Boolean areDefaultInteractionsBlocked()
      This is a per-inventory version of SpiGUI.areDefaultInteractionsBlocked().
      Returns:
      Whether the default behavior of click events should be cancelled.
      See Also:

    • setAutomaticPaginationEnabled

      public void setAutomaticPaginationEnabled(boolean enableAutomaticPagination)
      This is a per-inventory version of SpiGUI.setEnableAutomaticPagination(boolean). If this value is set, it overrides the per-plugin option set in SpiGUI.
      Parameters:
      enableAutomaticPagination - Whether pagination buttons should be automatically added.
      See Also:

    • isAutomaticPaginationEnabled

      public Boolean isAutomaticPaginationEnabled()
      This is a per-inventory version of SpiGUI.isAutomaticPaginationEnabled().
      Returns:
      Whether pagination buttons should be automatically added.
      See Also:

    • setToolbarBuilder

      public void setToolbarBuilder(SGToolbarBuilder toolbarBuilder)
      This is a per-inventory version of (SpiGUI.setDefaultToolbarBuilder(SGToolbarBuilder)).
      Parameters:
      toolbarBuilder - The default toolbar builder used for GUIs.
      See Also:

    • getToolbarBuilder

      public SGToolbarBuilder getToolbarBuilder()
      This is a per-inventory version of (SpiGUI.getDefaultToolbarBuilder()).
      Returns:
      The default toolbar builder used for GUIs.
      See Also:

    • getOwner

      public org.bukkit.plugin.java.JavaPlugin getOwner()
      Returns the plugin that the inventory is associated with. As this field is final, this would be the plugin that created the inventory.
      Returns:
      The plugin the inventory is associated with.

    • getRowsPerPage

      public int getRowsPerPage()
      Returns the number of rows (of 9 columns) per page of the inventory. If you want the total number of slots on a page, you should use getPageSize() instead.
      Returns:
      The number of rows per page.

    • getPageSize

      public int getPageSize()
      Returns the number of slots per page of the inventory. This would be associated with the Bukkit/Spigot APIs inventory 'size' parameter.
      So for example if getRowsPerPage() was 3, this would be 27, as Minecraft Chest inventories have rows of 9 columns.
      Returns:
      The number of inventory slots per page.

    • setRowsPerPage

      public void setRowsPerPage(int rowsPerPage)
      Sets the number of rows per page of the inventory.
      There is no way to set the number of slots per page directly, so if you need to do that, you'll need to divide the number of slots by 9 and supply the result to this parameter to achieve that.
      Parameters:
      rowsPerPage - The number of rows per page.

    • getTag

      public String getTag()
      This returns the GUI's tag.

      The tag is used when getting all open inventories (SpiGUI.findOpenWithTag(String)) with your chosen tag. An example of where this might be useful is with a permission GUI - when the permissions are updated by one user in the GUI, it would be desirable to refresh the state of the permissions GUI for all users observing the GUI.
      Returns:
      The GUI's tag.

    • setTag

      public void setTag(String tag)
      This sets the GUI's tag.
      Parameters:
      tag - The GUI's tag.
      See Also:

    • setName

      public void setName(String name)
      This sets the inventory's display name.

      The name parameter is color code translated before the value is set. If you want to avoid this behavior, you should use setRawName(String) which sets the inventory's name directly.
      Parameters:
      name - The display name to set. (and to be color code translated)

    • setRawName

      public void setRawName(String name)
      This sets the inventory's display name without first translating color codes.
      Parameters:
      name - The display name to set.

    • getName

      public String getName()
      This returns the inventory's display name.

      Note that if you used setName(String), this will have been color code translated already.
      Returns:
      The inventory's display name.

    • addButton

      public void addButton(SGButton button)
      Adds the provided SGButton.
      Parameters:
      button - The button to add.

    • addButtons

      public void addButtons(SGButton... buttons)
      Adds the specified SGButtons consecutively.
      Parameters:
      buttons - The buttons to add.

    • setButton

      public void setButton(int slot, SGButton button)
      Adds the provided SGButton at the position denoted by the supplied slot parameter.
      If you specify a value larger than the value of the first page, pagination will be automatically applied when the inventory is rendered. An alternative to this is to use setButton(int, int, SGButton).
      Parameters:
      slot - The desired location of the button.
      button - The button to add.
      See Also:

    • setButton

      public void setButton(int page, int slot, SGButton button)
      Adds the provided SGButton at the position denoted by the supplied slot parameter on the page denoted by the supplied page parameter.
      This is an alias for setButton(int, SGButton), however one where the slot value is mapped to the specified page. So if page is 2 (the third page) and the inventory row count was 3 (so a size of 27), a supplied slot value of 3 would actually map to a slot value of (2 * 27) + 3 = 54. The mathematical formula for this is (page * pageSize) + slot.
      If the slot value is out of the bounds of the specified page, this function will do nothing.
      Parameters:
      page - The page to which the button should be added.
      slot - The position on that page the button should be added at.
      button - The button to add.
      See Also:

    • removeButton

      public void removeButton(int slot)
      Removes a button from the specified slot.
      Parameters:
      slot - The slot containing the button you wish to remove.

    • removeButton

      public void removeButton(int page, int slot)
      An alias for removeButton(int) to remove a button from the specified slot on the specified page.
      If the slot value is out of the bounds of the specified page, this function will do nothing.
      Parameters:
      page - The page containing the button you wish to remove.
      slot - The slot, of that page, containing the button you wish to remove.

    • getButton

      public SGButton getButton(int slot)
      Returns the SGButton in the specified slot.
      If you attempt to get a slot less than 0 or greater than the slot containing the button at the greatest slot value, this will return null.
      Parameters:
      slot - The slot containing the button you wish to get.
      Returns:
      The SGButton that was in that slot or null if the slot was invalid or if there was no button that slot.

    • getButton

      public SGButton getButton(int page, int slot)
      This is an alias for getButton(int) that allows you to get a button contained by a slot on a given page.
      Parameters:
      page - The page containing the button.
      slot - The slot, on that page, containing the button.
      Returns:
      The SGButton that was in that slot or null if the slot was invalid or if there was no button that slot.

    • getCurrentPage

      public int getCurrentPage()
      Returns the current page of the inventory. This is the page that will be displayed when the inventory is opened and displayed to a player (i.e. rendered).
      Returns:
      The current page of the inventory.

    • setCurrentPage

      public void setCurrentPage(int page)
      Sets the page of the inventory that will be displayed when the inventory is opened and displayed to a player (i.e. rendered).
      Parameters:
      page - The new current page of the inventory.

    • getMaxPage

      public int getMaxPage()
      Gets the page number of the final page of the GUI.
      Returns:
      The highest page number that can be viewed.

    • getHighestFilledSlot

      public int getHighestFilledSlot()
      Returns the slot number of the highest filled slot. This is mainly used to calculate the number of pages there needs to be to display the GUI's contents in the rendered inventory.
      Returns:
      The highest filled slot's number.

    • nextPage

      public boolean nextPage(org.bukkit.entity.HumanEntity viewer)
      Increments the current page. This will automatically refresh the inventory by calling refreshInventory(HumanEntity) if the page was changed.
      Parameters:
      viewer - The HumanEntity viewing the inventory.
      Returns:
      Whether the page could be changed (false means the max page is currently open).

    • previousPage

      public boolean previousPage(org.bukkit.entity.HumanEntity viewer)
      Decrements the current page. This will automatically refresh the inventory by calling refreshInventory(HumanEntity) if the page was changed.
      Parameters:
      viewer - The HumanEntity viewing the inventory.
      Returns:
      Whether the page could be changed (false means the first page is currently open).

    • stickSlot

      public void stickSlot(int slot)
      Marks a slot as 'sticky', so that when the page is changed, the slot will always display the value on the first page.
      This is useful for implementing things like 'toolbars', where you have a set of common items on every page.
      If the slot is out of the bounds of the first page (i.e. less than 0 or greater than getPageSize() - 1) this method will do nothing.
      Parameters:
      slot - The slot to mark as 'sticky'.

    • unstickSlot

      public void unstickSlot(int slot)
      Un-marks a slot as sticky - thereby meaning that slot will display whatever its value on the current page is.
      Parameters:
      slot - The slot to un-mark as 'sticky'.
      See Also:

    • clearStickiedSlots

      public void clearStickiedSlots()
      This clears all the 'stuck' slots - essentially un-marking all stuck slots.
      See Also:

    • isStickiedSlot

      public boolean isStickiedSlot(int slot)
      This checks whether a given slot is sticky. If the slot is out of bounds of the first page (as defined by the same parameters as stickSlot(int)), this will return false.
      Parameters:
      slot - The slot to check.
      Returns:
      True if the slot is sticky, false if it isn't or the slot was out of bounds.
      See Also:

    • clearAllButStickiedSlots

      public void clearAllButStickiedSlots()
      This clears all slots in the inventory, except those which have been marked as 'sticky'.
      See Also:

    • getOnClose

      public Consumer<SGMenu> getOnClose()
      The action to be performed on close.
      Returns:
      The action to be performed on close.
      See Also:

    • setOnClose

      public void setOnClose(Consumer<SGMenu> onClose)
      Used to set an action to be performed on inventory close without registering an InventoryCloseEvent specifically for this inventory.
      Parameters:
      onClose - The action to be performed on close.

    • getOnPageChange

      public Consumer<SGMenu> getOnPageChange()
      The action to be performed on page change.
      Returns:
      The action to be performed on page change.
      See Also:

    • setOnPageChange

      public void setOnPageChange(Consumer<SGMenu> onPageChange)
      Used to set an action to be performed on inventory page change.
      Parameters:
      onPageChange - The action to be performed on page change.

    • getPermittedMenuClickTypes

      public HashSet<org.bukkit.event.inventory.ClickType> getPermittedMenuClickTypes()
      Returns the permitted menu click types.
      Returns:
      A hashSet of permitted menu click types

    • getBlockedMenuActions

      public HashSet<org.bukkit.event.inventory.InventoryAction> getBlockedMenuActions()
      Returns an array of blocked menu actions for the current Inventory.
      Returns:
      A hashSet of blocked menu actions

    • getBlockedAdjacentActions

      public HashSet<org.bukkit.event.inventory.InventoryAction> getBlockedAdjacentActions()
      Returns the blocked adjacent actions for this object.
      Returns:
      A hashSet of InventoryAction objects representing the blocked adjacent actions.

    • setPermittedMenuClickTypes

      public void setPermittedMenuClickTypes(org.bukkit.event.inventory.ClickType... clickTypes)
      Sets the permitted menu click types.
      Parameters:
      clickTypes - One or more click types you want to allow for this menu.

    • setBlockedMenuActions

      public void setBlockedMenuActions(org.bukkit.event.inventory.InventoryAction... actions)
      Sets the blocked menu actions for the inventory.
      Parameters:
      actions - the menu actions to be blocked

    • setBlockedAdjacentActions

      public void setBlockedAdjacentActions(org.bukkit.event.inventory.InventoryAction... actions)
      Sets the blocked adjacent actions for this object.
      Parameters:
      actions - The actions to be blocked.

    • addPermittedClickType

      public void addPermittedClickType(org.bukkit.event.inventory.ClickType clickType)
      Adds a permitted click type to the menu.
      Parameters:
      clickType - the click type to be added

    • addBlockedMenuAction

      public void addBlockedMenuAction(org.bukkit.event.inventory.InventoryAction action)
      Adds the given InventoryAction to the list of blocked menu actions. Blocked menu actions are actions that are not allowed to be performed on the inventory menu.
      Parameters:
      action - The InventoryAction to be added to the blocked menu actions list.

    • addBlockedAdjacentAction

      public void addBlockedAdjacentAction(org.bukkit.event.inventory.InventoryAction action)
      Adds a blocked adjacent action to the list of blocked adjacent actions.
      Parameters:
      action - The inventory action to be added as blocked adjacent action.

    • removePermittedClickType

      public void removePermittedClickType(org.bukkit.event.inventory.ClickType clickType)
      Removes a permitted click type from the list of permitted menu click types.
      Parameters:
      clickType - the click type to be removed

    • removeBlockedMenuAction

      public void removeBlockedMenuAction(org.bukkit.event.inventory.InventoryAction action)
      Removes the specified InventoryAction from the list of blocked menu actions.
      Parameters:
      action - the InventoryAction to be removed

    • removeBlockedAdjacentAction

      public void removeBlockedAdjacentAction(org.bukkit.event.inventory.InventoryAction action)
      Removes the given action from the list of blocked adjacent actions.
      Parameters:
      action - The action to be removed

    • refreshInventory

      public void refreshInventory(org.bukkit.entity.HumanEntity viewer)
      Refresh an inventory that is currently open for a given viewer.
      This method checks if the specified viewer is looking at an SGMenu and, if they are, it refreshes the inventory for them.
      Parameters:
      viewer - The viewer of the open inventory.

    • getInventory

      public org.bukkit.inventory.Inventory getInventory()
      Returns the Bukkit/Spigot Inventory that represents the GUI. This is shown to a player using HumanEntity.openInventory(Inventory).
      Specified by:
      getInventory in interface org.bukkit.inventory.InventoryHolder
      Returns:
      The created inventory used to display the GUI.