Package io.github.toberocat.guiengine

Class GuiEngineApi

java.lang.Object
io.github.toberocat.guiengine.GuiEngineApi
public final class GuiEngineApi extends Object
The `GuiEngineApi` class provides an API to manage and interact with graphical user interfaces (GUIs). It allows you to register and manage various GUI components, load XML-based GUI definitions, and display GUIs to players in the game.

This class is licensed under the GNU General Public License.

Since:
05/02/2023
Author:
Tobias Madlberger (Tobias)

  • Field Details

    • APIS

      public static final Map<String,GuiEngineApi> APIS

    • LOADED_CONTEXTS

      @NotNull public static final @NotNull Map<UUID,GuiContext> LOADED_CONTEXTS

    • DEFAULT_GUI_FILTER

      @NotNull public static final @NotNull FileFilter DEFAULT_GUI_FILTER

    • SHARED_MODULES

      public static final List<com.fasterxml.jackson.databind.module.SimpleModule> SHARED_MODULES

    • GUI_ID_REGEX

      public static final Pattern GUI_ID_REGEX

    • SHARED_COMPONENT_ID_MAPS

      public static final Map<String,Class<? extends GuiComponent>> SHARED_COMPONENT_ID_MAPS

  • Constructor Details

    • GuiEngineApi

      public GuiEngineApi(@NotNull @NotNull String id, @NotNull @NotNull File guiFolder)
      Constructs a new `GuiEngineApi` instance with the specified ID and GUI folder.
      Parameters:
      id - The ID for this `GuiEngineApi` instance.
      guiFolder - The folder where GUI files are stored.

    • GuiEngineApi

      public GuiEngineApi(@NotNull @NotNull org.bukkit.plugin.java.JavaPlugin plugin) throws IOException, URISyntaxException
      Constructs a new `GuiEngineApi` instance for the specified plugin. The ID will be automatically set to the plugin's name, and the gui folder will be the data-folder/guis

      This has the advantage that GuiEngine automatically copies the guis folder from the resources

      Parameters:
      plugin - The plugin this API owns to
      Throws:
      IOException
      URISyntaxException

    • GuiEngineApi

      public GuiEngineApi(@NotNull @NotNull String id, @NotNull @NotNull File guiFolder, @NotNull @NotNull FileFilter guiFilter)
      Constructs a new `GuiEngineApi` instance with the specified ID, GUI folder, and GUI filter.
      Parameters:
      id - The ID for this `GuiEngineApi` instance.
      guiFolder - The folder where GUI files are stored.
      guiFilter - The filter used to determine which files are considered GUI files.

  • Method Details

    • registerSharedFactory

      public static <T extends GuiComponent, B extends GuiComponentBuilder> void registerSharedFactory(@NotNull @NotNull String id, @NotNull @NotNull Class<T> clazz, @NotNull @NotNull Class<B> builderClazz)
      Registers a shared GUI component factory with the given ID, class, and builder class. Shared factories can be used across different instances of `GuiEngineApi`.
      Type Parameters:
      T - The type of the GUI component.
      B - The type of the GUI component builder.
      Parameters:
      id - The ID of the shared GUI component factory.
      clazz - The class representing the GUI component.
      builderClazz - The class representing the GUI component builder.

    • registerFactory

      public <T extends GuiComponent, B extends GuiComponentBuilder> void registerFactory(@NotNull @NotNull String id, @NotNull @NotNull Class<T> clazz, @NotNull @NotNull Class<B> builderClazz)
      Registers a GUI component factory with the given ID, class, and builder class.
      Type Parameters:
      T - The type of the GUI component.
      B - The type of the GUI component builder.
      Parameters:
      id - The ID of the GUI component factory.
      clazz - The class representing the GUI component.
      builderClazz - The class representing the GUI component builder.

    • reload

      public void reload() throws GuiIORuntimeException
      Reloads the available GUIs from the GUI folder.
      Throws:
      GuiIORuntimeException - If there is an I/O error while loading or validating GUIs.

    • openGui

      @NotNull public @NotNull GuiContext openGui(@NotNull @NotNull org.bukkit.entity.Player player, @NotNull @NotNull String guiId) throws GuiNotFoundRuntimeException, GuiIORuntimeException
      Opens a GUI with the specified ID for the given player, using the default placeholders.
      Parameters:
      player - The player to whom the GUI should be displayed.
      guiId - The ID of the GUI to open.
      Returns:
      The `GuiContext` representing the opened GUI.
      Throws:
      GuiNotFoundRuntimeException - If the specified GUI ID does not correspond to an existing GUI.
      GuiIORuntimeException - If there is an I/O error while loading or rendering the GUI.

    • openGui

      @NotNull public @NotNull GuiContext openGui(@NotNull @NotNull org.bukkit.entity.Player player, @NotNull @NotNull String guiId, @NotNull @NotNull Map<String,String> placeholders) throws GuiNotFoundRuntimeException, GuiIORuntimeException
      Opens a GUI with the specified ID for the given player, using the provided placeholders.
      Parameters:
      player - The player to whom the GUI should be displayed.
      guiId - The ID of the GUI to open.
      placeholders - The map of placeholders to be substituted in the GUI content.
      Returns:
      The `GuiContext` representing the opened GUI.
      Throws:
      GuiNotFoundRuntimeException - If the specified GUI ID does not correspond to an existing GUI.
      GuiIORuntimeException - If there is an I/O error while loading or rendering the GUI.

    • loadXmlGui

      @NotNull public @NotNull XmlGui loadXmlGui(@NotNull @NotNull Map<String,String> placeholders, @NotNull @NotNull String guiId) throws GuiNotFoundRuntimeException, GuiIORuntimeException
      Loads and returns the XML-based GUI definition with the specified ID, substituting the placeholders.
      Parameters:
      placeholders - The map of placeholders to be substituted in the GUI content.
      guiId - The ID of the GUI to load.
      Returns:
      The loaded `XmlGui` instance representing the GUI.
      Throws:
      GuiNotFoundRuntimeException - If the specified GUI ID does not correspond to an existing GUI.
      GuiIORuntimeException - If there is an I/O error while loading the GUI.

    • guiIdFromFile

      @NotNull public @NotNull String guiIdFromFile(@NotNull @NotNull File file)
      Converts a file into it's guiId. This takes the extension away and returns the part before
      Parameters:
      file - The input file
      Returns:
      The guiId of this file

    • getAvailableGuis

      @NotNull public @NotNull Set<String> getAvailableGuis()
      Returns the set of available GUI IDs within the GUI folder.
      Returns:
      The set of available GUI IDs.

    • getInterpreterManager

      @NotNull public @NotNull InterpreterManager getInterpreterManager()
      Returns the `InterpreterManager` instance associated with this `GuiEngineApi`.
      Returns:
      The `InterpreterManager` instance.

    • getGuiViewManager

      @NotNull public @NotNull DefaultGuiViewManager getGuiViewManager()
      Returns the `DefaultGuiViewManager` instance associated with this `GuiEngineApi`.
      Returns:
      The `DefaultGuiViewManager` instance.

    • getXmlMapper

      @NotNull public @NotNull com.fasterxml.jackson.databind.ObjectMapper getXmlMapper()
      Returns the `ObjectMapper` used for XML serialization/deserialization of GUI components.
      Returns:
      The `ObjectMapper` instance for XML handling.

    • getGuiFilter

      @NotNull public @NotNull FileFilter getGuiFilter()
      Returns the GUI filter used to determine which files are considered GUI files.
      Returns:
      The `FileFilter` instance representing the GUI filter.

    • getComponentIdMap

      @NotNull public @NotNull Map<String,Class<? extends GuiComponent>> getComponentIdMap()
      Returns the map of GUI component IDs and their associated classes for this `GuiEngineApi`.
      Returns:
      The map of GUI component IDs and their associated classes.

    • getId

      @NotNull public @NotNull String getId()
      Returns the ID of this `GuiEngineApi` instance.
      Returns:
      The ID of this `GuiEngineApi` instance.