ChestSort/HOW_TO_USE_API.md

140 lines
4.7 KiB
Markdown
Raw Normal View History

2018-11-07 23:59:42 +01:00
# API Usage
2018-11-08 00:33:30 +01:00
2021-07-07 09:30:58 +02:00
If you want to use ChestSort's advanced sorting features for your own plugin, or if ChestSort causes trouble with your own plugin, you can use the ChestSortAPI. It provides
- the methods `sortInventory(Inventory inv)` and `sortInventory(Inventory inv, int startSlot, int endSlot)`to sort any given inventory, following the rules you have specified in your ChestSort's config.yml and the corresponding category files
- a cancellable event called `ChestSortEvent` that is fired whenever ChestSort is about to sort an inventory, that can also be used to change the sorting results
- the methods `setSortable(Inventory inv)` and `setUnsortable(Inventory inv)` to tell ChestSort whether your custom inventories should be sortable by ChestSort
2021-05-29 18:27:06 +02:00
2021-07-07 09:33:25 +02:00
and more, see the Javadocs at the bottom of this page. There's also a link to an example plugin.
2018-11-08 00:33:30 +01:00
2020-06-10 18:21:41 +02:00
## Maven repository
You can use maven to add ChestSort as a dependency to your Spigot-/Bukkit-Plugin:
2018-11-07 23:59:42 +01:00
2020-07-12 02:51:51 +02:00
```xml
2020-06-10 18:21:41 +02:00
<repositories>
<repository>
2021-10-23 22:53:13 +02:00
<id>jeff-media-public</id>
<url>https://hub.jeff-media.com/nexus/repository/jeff-media-public/</url>
2020-06-10 18:21:41 +02:00
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>de.jeff_media</groupId>
2020-07-12 02:51:51 +02:00
<artifactId>ChestSortAPI</artifactId>
2022-02-05 10:02:48 +01:00
<version>13.0.0-SNAPSHOT</version>
2021-07-07 09:38:45 +02:00
<scope>provided</scope>
2020-06-10 18:21:41 +02:00
</dependency>
</dependencies>
```
2021-07-07 09:38:19 +02:00
You must also add `ChestSort` (NOT `ChestSortAPI`) to the `depend` or `softdepend` section of your `plugin.yml`.
2021-07-07 09:28:42 +02:00
Note: it is no longer required **nor allowed** to shade the ChestSortAPI into your plugin.
2020-06-10 18:21:41 +02:00
## Accessing the API
2021-07-07 09:28:42 +02:00
### As `depend`
If you depend on ChestSort, you can easily access the API methods directly:
```java
import de.jeff_media.chestsort.api.ChestSortAPI;
...
ChestSortAPI.sortInventory(player.getInventory());
```
### As `softdepend`
2022-07-23 13:58:09 +02:00
If you only softdepend on ChestSort, you have to check whether ChestSort is installed:
2021-07-07 09:28:42 +02:00
```java
if(Bukkit.getPluginManager().getPlugin("ChestSort") != null) {
de.jeff_media.chestsort.api.ChestSortAPI.sortInventory(player.getInventory());
}
```
2018-11-07 23:59:42 +01:00
2021-07-07 09:28:42 +02:00
Your Listener has to import the ChestSortEvent class, so only register it when ChestSort is installed:
2020-07-12 03:03:31 +02:00
```java
2021-07-07 09:28:42 +02:00
if(Bukkit.getPluginManager().getPlugin("ChestSort") != null) {
Bukkit.getPluginManager().registerEvents(new MyListener(), yourPlugin);
2018-11-08 00:00:24 +01:00
}
2018-11-07 23:59:42 +01:00
```
2020-06-10 18:21:41 +02:00
### Sorting inventories
2018-11-07 23:59:42 +01:00
Now, you can sort any Inventory! Just like this:
2020-07-12 02:51:51 +02:00
```java
2021-07-07 09:28:42 +02:00
ChestSortAPI.sortInventory(Inventory inventory);
2018-11-08 00:00:24 +01:00
```
2018-11-08 16:41:02 +01:00
2019-01-12 15:51:21 +01:00
To sort only specific slots, you can pass slot numbers where to start and end sorting. ChestSort will not modify the inventory outside the given slot range.
2018-11-08 16:41:02 +01:00
2020-07-12 02:51:51 +02:00
```java
2021-07-07 09:28:42 +02:00
ChestSortAPI.sortInventory(Inventory inventory, int startSlot, int endSlot);
2019-01-12 15:51:21 +01:00
```
You can also check if a player has automatic sorting enabled or disabled:
2020-07-12 02:51:51 +02:00
```java
2021-07-07 09:28:42 +02:00
boolean sortingEnabled = ChestSortAPI.hasSortingEnabled(Player player);
2020-06-10 18:21:41 +02:00
```
### Custom ChestSort event
If you want to prevent ChestSort from sorting a certain inventory, you can listen to the ChestSortEvent event.
2020-07-12 02:51:51 +02:00
```java
2020-06-10 18:21:41 +02:00
@EventHandler
public void onChestSortEvent(ChestSortEvent event) {
if(event.getInventory() == whatever) {
event.setCancelled(true);
}
}
```
2021-01-02 21:43:33 +01:00
You can also exempt certain slots / ItemStacks from being sorted using the following methods:
2021-01-02 21:42:34 +01:00
```java
public void setUnmovable(int slot)
public void setUnmovable(ItemStack itemStack)
public void removeUnmovable(int slot)
public void removeUnmovable(ItemStack itemStack)
public boolean isUnmovable(int slot)
public boolean isUnmovable(ItemStack itemStack)
```
For example, to avoid the first item in the player's hotbar from being sorted:
```java
@EventHandler
public void onChestSortEvent(ChestSortEvent event) {
event.setUnmovable(0);
}
```
2021-07-07 09:28:42 +02:00
### Making custom inventories sortable / unsortable
2020-07-12 02:51:51 +02:00
2021-07-07 09:28:42 +02:00
If you create a new Inventory inside your plugin, you can tell ChestSort whether that inventory should be sortable by ChestSort:
2020-07-12 02:51:51 +02:00
```java
2021-07-07 09:28:42 +02:00
// Make it sortable
ChestSortAPI.setSortable(myInventory);
2020-07-12 03:02:07 +02:00
2021-07-07 09:28:42 +02:00
// or make it not sortable
ChestSortAPI.setUnsortable(myInventory);
2020-07-12 02:51:51 +02:00
```
2021-07-07 09:35:22 +02:00
## Javadocs, Source code, Example plugin & Discord
2021-07-07 09:28:42 +02:00
There are more methods you can use, just have a look at the Javadocs.
2022-02-05 10:02:48 +01:00
- [ChestSortAPI Javadocs](https://hub.jeff-media.de/javadocs/chestsortapi).
2021-02-20 17:43:20 +01:00
- [ChestSortAPI source code](https://github.com/JEFF-Media-GbR/Spigot-ChestSortAPI).
2021-07-07 09:33:25 +02:00
Here is a complete example plugin that shows to add and use the ChestSort API: [LINK](https://github.com/JEFF-Media-GbR/ChestSortAPIExample)
If you need help using the API, feel free to join my Discord server:
2022-07-23 13:58:09 +02:00
[![Join my Discord](https://api.jeff-media.de/img/discord1.png)](https://discord.jeff-media.de)