Class SpiGUI

java.lang.Object
com.samjakob.spigui.SpiGUI
public class SpiGUI extends Object
The core class for the SpiGUI library.
One instance of the SpiGUI class is registered for each plugin using it.
The expected usage of SpiGUI is that you register a SpiGUI instance for your plugin with new SpiGUI(this); in your class that extends JavaPlugin. You can then use the instance you've created throughout your project to create GUIs that use SpiGUI.

  • Field Details

    • plugin

      private final org.bukkit.plugin.java.JavaPlugin plugin
      The plugin that owns this instance of SpiGUI.

    • blockDefaultInteractions

      private boolean blockDefaultInteractions
      Whether to cancel inventory click actions by default.
      This is typically set to true so events needn't be manually cancelled every time an item is clicked in the inventory as that is the behavior most typically used with an inventory GUI.
      With this set to true, you can of course use event.setCancelled(false); (or event.setResult(Event.Result.DEFAULT);) in your button listeners to allow the default behavior of the inventory to take place.

    • enableAutomaticPagination

      private boolean enableAutomaticPagination
      Whether automatic pagination should be enabled.
      This is set to true by default, and it means if you set an inventory slot greater than the highest slot on the inventory, a row will automatically be added containing pagination items that allow a user to scroll between different 'pages' to access all the assigned slots in the inventory.
      This concept is based on an improved version of the approach taken with my SpigotPaginatedGUI library.

    • defaultToolbarBuilder

      private SGToolbarBuilder defaultToolbarBuilder
      The defaultToolbarBuilder is the plugin-wide SGToolbarBuilder called when building pagination buttons for inventory GUIs.
      This can be overridden per-inventory, as well as per-plugin using the appropriate methods on either the inventory class (SGMenu) or your plugin's instance of SpiGUI.

  • Constructor Details

    • SpiGUI

      public SpiGUI(org.bukkit.plugin.java.JavaPlugin plugin)
      Creates an instance of the SpiGUI library associated with a given plugin.

      This is intended to be stored as a static field in your plugin with a public static getter (or a public static field - dealer's choice) and you create inventories through this class by calling create(String, int) on the static SpiGUI field.
      A lengthy justification of this is provided below, should you care to read it.

      Note:

      The association with a plugin is an important design decision that was overlooked in this library's predecessor, SpigotPaginatedGUI.

      This library is not designed to act as a standalone plugin because that is inconvenient for both developers and server administrators for such a relatively insignificant task - the library is more just a small convenience measure. However, this library still needs to register a listener under a given plugin, which is where the issue arises; which plugin should the library use to register events with. Previously, it was whichever plugin made the call to PaginatedGUI.prepare first, however this obviously causes problems if that particular plugin is unloaded - as any other plugins using the library no longer have the listener that was registered.

      This approach was therefore considered a viable compromise - each plugin registers its own listener, however the downside of this is that each inventory and the listener must now also be registered with the plugin too.

      Thus, the design whereby this class is registered as a static field on a JavaPlugin instance and serves as a proxy for creating (SGMenu) inventories and an instance of the SGMenuListener registered with that plugin seemed like a good way to try and minimize the inconvenience of the approach.
      Parameters:
      plugin - The plugin using SpiGUI.

  • Method Details

    • create

      public SGMenu create(String name, int rows)
      An alias for create(String, int, String) with the tag set to null. Use this method if you don't need the tag, or you don't know what it's for.
      The rows parameter is used in place of the size parameter of the Bukkit/Spigot inventory API. So, if you wanted an inventory of size 27, you would supply 3 as the value of the rows parameter.

      The name parameter supports the following 'placeholders':
      • {currentPage}: the current page the inventory is on.
      • {maxPage}: the final page of the inventory.
      Parameters:
      name - The display name of the inventory.
      rows - The number of rows the inventory should have per page.
      Returns:
      The created inventory.

    • create

      public SGMenu create(String name, int rows, String tag)
      Creates an inventory with a given name, tag and number of rows. The display name is color code translated.

      The name parameter supports the following 'placeholders':
      • {currentPage}: the current page the inventory is on.
      • {maxPage}: the final page of the inventory.


      The rows parameter is used in place of the size parameter of the Bukkit/Spigot inventory API. So, if you wanted an inventory of size 27, you would supply 3 as the value of the rows parameter.

      The tag is used when getting all open inventories (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.

      You might give the permissions GUI a tag of 'myPermissionsGUI', then refreshing all the open instances of the GUI would be as simple as getting all open inventories with the aforementioned tag using findOpenWithTag(String) and calling refresh on each GUI in the list.

      Parameters:
      name - The display name of the inventory.
      rows - The number of rows the inventory should have per page.
      tag - The inventory's tag.
      Returns:
      The created inventory.

    • setBlockDefaultInteractions

      public void setBlockDefaultInteractions(boolean blockDefaultInteractions)
      Whether default inventory interactions should be cancelled.
      Parameters:
      blockDefaultInteractions - Whether default inventory interactions should be cancelled.
      See Also:

    • areDefaultInteractionsBlocked

      public boolean areDefaultInteractionsBlocked()
      Returns the value of blockDefaultInteractions for this plugin.
      Returns:
      Whether default inventory interactions should be cancelled.

    • setEnableAutomaticPagination

      public void setEnableAutomaticPagination(boolean enableAutomaticPagination)
      Whether automatic pagination should be enabled.
      Parameters:
      enableAutomaticPagination - Whether automatic pagination should be enabled.
      See Also:

    • isAutomaticPaginationEnabled

      public boolean isAutomaticPaginationEnabled()
      Returns the value of enableAutomaticPagination for this plugin.
      Returns:
      Whether automatic pagination is enabled.

    • setDefaultToolbarBuilder

      public void setDefaultToolbarBuilder(SGToolbarBuilder defaultToolbarBuilder)
      The default toolbar builder used for GUIs.
      Parameters:
      defaultToolbarBuilder - The default toolbar builder used for GUIs.
      See Also:

    • getDefaultToolbarBuilder

      public SGToolbarBuilder getDefaultToolbarBuilder()
      The default toolbar builder used for GUIs.
      Returns:
      The default toolbar builder used for GUIs.
      See Also:

    • findOpenWithTag

      public List<SGOpenMenu> findOpenWithTag(String tag)
      Finds a list of all open inventories with a given tag along with the player who has that inventory open.
      This returns a list of SGOpenMenu which simply stores the opened inventory along with the player viewing the open inventory.
      Supplying null as the tag value will get all untagged inventories.
      Parameters:
      tag - The tag to search for.
      Returns:
      A list of SGOpenMenu whose inventories have the specified tag.