diff --git a/guide/docs/gui/compounds.md b/guide/docs/gui/compounds.md new file mode 100644 index 00000000..12996b06 --- /dev/null +++ b/guide/docs/gui/compounds.md @@ -0,0 +1,95 @@ +## Create a new compound + +In this example, let's create a simple gui which lists all existing materials. Also, we want to display the name of the material when the user clicks on the icon. + +You can create a compound inside a page builder scope. The recommended way of doing so is to use the `createRectCompound`. + +```kotlin +page(1) { + val compound = createRectCompound( + Slots.RowOneSlotOne, Slots.RowSixSlotEight, + iconGenerator = { + ItemStack(it) + }, + onClick = { clickEvent, element -> + clickEvent.player.sendMessage("You clicked on: ${element.name}") + } + ) +} +``` + +Notice that the generic type of the compound is `Material`. The compound type defines the type of the elements which can be added to the compound. + +The `iconGenerator` defines how each compound element should be displayed. You will get the element passed as `it` and you have to return an `ItemStack`, which will be used for the icon. + +???+ info + In our example, it is very easy to create the icon, as we can easily create an `ItemStack` from a `Material`. In your scenarios, don't be scared of putting more complex logic inside the `iconGenerator`. + +## Modify the content of a compound + +The compound from above will be empty at first, you have to add content to it. This can be done using the `compound.addContent` function. + +The content you add has to be of the type you defined earlier (in our case this is `Material`). + +```kotlin +compound.addContent(Material.values().toList()) +``` + +In order to remove content, call the `compound.removeContent` function. Let's remove air from our example compound. + +```kotlin +compound.removeContent(Material.AIR) +``` + +## Sort the compound + +You can use the `compound.sortContentBy` function to define in which order the elements of a compound should be displayed. + +In our example, we could sort by the name of the material like this: + +```kotlin +compound.sortContentBy { it.name } +``` + +## Add scroll buttons + +If the content of the compound won't fit in on one page of the GUI, **do not** create multiple pages, even if this is what you might think of at first. + +Instead, add scroll buttons to the same page! + +### Smooth scrolling + +To implement smooth scrolling, create scroll buttons like this: + +```kotlin +compoundScroll( + Slots.RowOneSlotNine, + ItemStack(Material.PAPER), compound, scrollTimes = 6 +) +compoundScroll( + Slots.RowSixSlotNine, + ItemStack(Material.PAPER), compound, scrollTimes = 6, reverse = true +) +``` + +Notice that you have to pass the `compound` as a parameter. Also, be careful to set `scrollTimes` to the height of your compound (in our example this is 6, because the inventory is 6 slots high, and we use the full height). + +You can use the `reverse` parameter and set it to true to create a button that scrolls backwards. + +### Instant (hard) scrolling + +Instant (or hard) scrollinng means that no scrolling animation will be displayed. + +To implement instant scrolling, leave `scrollTimes` at its default value (1) and instead modify the `scrollDistance` value. + +Set the `scrollDistance` value to **`compound.compoundWidth * amountOfLines`**, where `amountOfLines` represents how many lines you want to instantly scroll when pressing the scroll button. + +In our example, we could create the following button to scroll "page by page" instantly (without any scrolling animation): + +```kotlin +compoundScroll( + Slots.RowOneSlotNine, + ItemStack(Material.PAPER), compound, + scrollDistance = compound.compoundWidth * 6 +) +``` diff --git a/guide/mkdocs.yml b/guide/mkdocs.yml index 555a56e3..803476d5 100644 --- a/guide/mkdocs.yml +++ b/guide/mkdocs.yml @@ -38,3 +38,5 @@ nav: - Event listener: extensions/listener.md - Tasks: extensions/tasks.md - Item builder: extensions/itembuilder.md + - Gui: + - Compounds: gui/compounds.md