Version 2.0 - ParzivalExe/guiapi GitHub Wiki

Version 2.0 of GuiAPI has a completely new way to create all your Guis: Through XML!

This process makes creating a Gui even easier, testing them even more convenient and makes code way more readable because Logic and UI are now separated into different files.

In addition to this, the whole GuiAPI-Code has been rewritten in Kotlin, removing many of the edges that previously could lead to unwanted results. Through Kotlin itself, the code is now much more modern and compact BUT compatibility with Java has of course been kept for all the developers who have already and/or will in the future still use this API for their Java-Code

XML-Code

You can now use only XML for defining a GUI and must then only use two functions to open it for the player: Gui.createGuiFromProjectFile(…).openGui(player)

All the XML-Code for Guis is stored in files of the type *.mgui which stands for MinecraftGui. This file can be stored inside the project itself or outside in any other file. You can even change the FileType if you really want to. If you want to learn how to write Guis based on XML, here is explained how to create a Gui and populate it with all available components only using XML. You can even transform your own components to support XML within a few minutes and without changing any significant code by following this tutorial.

Once you have learned how to create Guis based on XML and have converted your own components to support XML you can enjoy many advantages:

  1. It is simply easier to write Guis in XML because you can already imagine how the final Gui will look like by just looking at the code
  2. Your code is much more organized. Now your code for the UI is inside a separate file from your Logic-Code
  3. The XML files are loaded every time you want to open the Gui making it much easier to see changes straight away. As long as the .mgui-File is located outside your project (the GuiAPI already provides a folder for simple testing), you can simply save the file after changes and these changes will automatically apply to the Gui the next time it is loaded. NO recompiling of the plugin, NO Server-Reloads

As you can see, there are lots of benefits for chaining your Gui-Creation to XML. The only scenario in which Guis based on XML-Code doesn't work is for Guis that are dynamically created based on runtime-data as there is no option yet to fill runtime-data into properties defined in XML. It is however possible to create the basic Gui in XML first and then edit it in code later. If everything in your Gui is based on RuntimeData it is of course also possible to create your Gui entirely in Java or Kotlin-Code as it was before.

Code-Overhaul

The Code-Overhaul has changed most of the critical systems behind the GuiAPI to be much more thought-out and fool-prove. The most noticable improvements are in:

  1. Changes to Component- and Gui-Tracking making it much more reliable. This helps with ensuring that no Component is finalized before it should be because after finalizing a component, it will not work but behave like an ordinary item again. At the same time, it also helps with preventing an input of one player to trigger the components of another player and finalizing Components the moment they aren't needed anymore, saving precious memory
  2. Changes to Events by introduction the methods isGuiOpenedInClass(Class<?> clazz) {…} and isGuiOpenedInThisClass() {…} which helps by filtering out calls from ComponentClickEvents which shouldn't be handled by the specific EventMethod. More on that in the chapter Event-Logic.
  3. Changes to Component-Placement, making it possible to change components of a Gui while it is opened and overall better positioning of Components with and without defined place.

How to update Code

This is such a new version of GuiAPI, that NO code from 1.x-Version has been used in v2.0 (already seen in the fact that it is now written in an entirely different programming-language). Therefore updating to v2.0 could seem impossible at first, needing completely new code. However this might not be the case as many variables and functions needed for final usage have been kept the same, though there are still mayor differences that everybody has to deal with BUT, even if you are not considering using any of the new features it is still adviced to use the new version since there are so many changes to the backend-code that could all have a positive impact on stability and eliminate many potential bugs in the older versions (or in other words: since I wrote this API in 2017, I have learned a lot 😉)

So, here are the most significant changes I could find that should be kept in mind when updating to 2.0:

Package

This is by far the biggest change since at first it would seem that every class you used is not findable anymore, but don't panic, most of the classes are still there, they are just based in another package now. Instead of the old com.bluebird.api.gui they are now located in io.github.parzivalExe.guiApi. Overall, this change in packages is mostly a rebranding and nothing more. Even the sub-packages after that are mostly the same.

Gui

In the Gui-Class there are several minor renaming's and one more prominent change. Let's start with the renaming's:

  1. int size is now called int forcedSize and boolean useSize has been removed. As long as forcedSize <= 0 (for example -1) it will act like useSize = false (which is also the default). The moment you set forcedSize > 0 (for example 9), it will act like useSize = true
  2. getComponents() is now changed to getAllComponents()
  3. While Gui.closeGui(player) still works, it is now also possible, to simply close a specific Gui-Instance by calling gui.closeGui() which is now the recommended function to use since you can be shure that you closed the correct Gui and not a different Gui the Player had already opened

Component

  1. It isn't possible anymore to use the variable look to get the ItemStack this Component will show when opened in a Gui. Instead you now need to call the function getGuiItem() which will then build you the right ItemStack
  2. The Component-ID id is now an int id and not long id
  3. To add a ClickAction you now have to call the method addClickListener(ComponentClickListener) {…} and not set the field clickAction because Components now support multiple ClickListeners at the same time. You might have also already noticed that the Interface for the ClickAction is now ComponentClickListener and not Runnable which is a custom Interface designed to be used for ClickActions
  4. FINALIZE_ACTION (not written yet)
  5. the finalize() {…}-Method is now called finalizeComponent() {…}
  6. getGuiComponentMeta() {…} is now called getMeta() {…} and setGuiComponentMeta() {…} is now called setMeta() {…}
  7. abstract Component setGuiComponent() {…} and abstract String setGuiComponentType() {…} are now not needed anymore for creating your own Components

ComponentMeta

  1. String name is now called String title
  2. void addDescription(String) {...} to add a line to the description is now called addDescriptionLine(String) {...}

OptionOpen

  1. OptionOpen is now called OpenOption
  2. underInventory is now called UNDER_INVENTORY
  3. newInventory is now called NEW_INVENTORY

Settings

  1. SettingOption[] option is now called ArrayList<SettingOption> options and an ArrayList and not an Array

YesNoOption

  1. yesNoOptionTitle is now called newInvTitle
  2. set/getYesOptionMeta is now called set/getYesMeta
  3. set/getNoOptionMeta is now called set/getNoMeta
  4. reloadYes/NoOption is not needed anymore

YesNoSetting(s)

  1. option1String and option1Item are now both combined in yesSettingMeta (like this: new ComponentMeta(option1String, option1Item)). To set yesSettingMeta call setYesSettingMeta(ComponentMeta) {...}
  2. option2String and option2Item are now both combined in noSettingMeta (like this: new ComponentMeta(option2String, option2Item)). To set noSettingMeta call setNoSettingMeta(ComponentMeta) {...}

Events

  1. NoOptionClickEvent -> NoOptionClickedEvent
  2. YesOptionClickEvent -> YesOptionClickedEvent
  3. YesNoSettingClickedEvent & YesSettingChooseEvent & NoSettingChooseEvent -> YesNoSettingChosenEvent

And this concludes all the mayor outward-facing changes I could find. If you have more, I would be more than happy for you to post it as an issue so that I can add it to this list and potentially even help you solve the compatibility-issue if you can't find a solution by yourself 😉

Now you know everything there is to know about GuiAPI v2.0 and you can start looking at the more specific tutorials or start updating your current implementation to v2.0. If you find any more issues with v2.0 you can of course also post these as an issue or you can simply give feedback over the Plugin-Comments.

I HOPE YOU CAN REALIZE EVERYTHING YOU WANT TO WITH GUIAPI v2.0 🎉🎊

⚠️ **GitHub.com Fallback** ⚠️