ChestSort/HOW_TO_USE_API.md

140 lines
4.8 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>
<id>jeff-media-repo</id>
<url>https://repo.jeff-media.de/maven2</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>de.jeff_media</groupId>
2020-07-12 02:51:51 +02:00
<artifactId>ChestSortAPI</artifactId>
<version>11.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`
If you only softdepend on ChestSort, you have to check whether ChestSort is installed. To avoid exceptions, do not import the ChestSortAPI class
in classes that you instantiate regardless of whether ChestSort is installed, but use qualified method calls instead:
```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.
- [ChestSortAPI Javadocs](https://repo.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:
[![Join my Discord](https://api.jeff-media.de/img/discord1.png)](https://discord.jeff-media.de)