#1036: Add API for InventoryView derivatives

By: Miles Holder <mwholder2005@gmail.com>

paper-api/src/main/java/org/bukkit/entity/HumanEntity.java

@@ -64,7 +64,9 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @param prop The property.
      * @param value The value to set the property to.
      * @return True if the property was successfully set.
+     * @deprecated use {@link InventoryView} and its children.
      */
+    @Deprecated(forRemoval = true, since = "1.21")
     public boolean setWindowProperty(@NotNull InventoryView.Property prop, int value);
 
     /**

paper-api/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java

@@ -6,8 +6,8 @@ import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 import org.bukkit.event.inventory.InventoryEvent;
-import org.bukkit.inventory.InventoryView;
 import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.view.EnchantmentView;
 import org.jetbrains.annotations.NotNull;
 
 /**
@@ -23,7 +23,7 @@ public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellab
     private boolean cancelled;
     private final Player enchanter;
 
-    public PrepareItemEnchantEvent(@NotNull final Player enchanter, @NotNull InventoryView view, @NotNull final Block table, @NotNull final ItemStack item, @NotNull final EnchantmentOffer[] offers, final int bonus) {
+    public PrepareItemEnchantEvent(@NotNull final Player enchanter, @NotNull EnchantmentView view, @NotNull final Block table, @NotNull final ItemStack item, @NotNull final EnchantmentOffer[] offers, final int bonus) {
         super(view);
         this.enchanter = enchanter;
         this.table = table;
@@ -100,6 +100,12 @@ public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellab
         return bonus;
     }
 
+    @NotNull
+    @Override
+    public EnchantmentView getView() {
+        return (EnchantmentView) super.getView();
+    }
+
     @Override
     public boolean isCancelled() {
         return cancelled;

paper-api/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java

@@ -2,8 +2,8 @@ package org.bukkit.event.inventory;
 
 import org.bukkit.event.HandlerList;
 import org.bukkit.inventory.AnvilInventory;
-import org.bukkit.inventory.InventoryView;
 import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.view.AnvilView;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -14,7 +14,7 @@ public class PrepareAnvilEvent extends PrepareInventoryResultEvent {
 
     private static final HandlerList handlers = new HandlerList();
 
-    public PrepareAnvilEvent(@NotNull InventoryView inventory, @Nullable ItemStack result) {
+    public PrepareAnvilEvent(@NotNull AnvilView inventory, @Nullable ItemStack result) {
         super(inventory, result);
     }
 
@@ -24,6 +24,12 @@ public class PrepareAnvilEvent extends PrepareInventoryResultEvent {
         return (AnvilInventory) super.getInventory();
     }
 
+    @NotNull
+    @Override
+    public AnvilView getView() {
+        return (AnvilView) super.getView();
+    }
+
     @NotNull
     @Override
     public HandlerList getHandlers() {

paper-api/src/main/java/org/bukkit/event/inventory/TradeSelectEvent.java

@@ -1,9 +1,9 @@
 package org.bukkit.event.inventory;
 
 import org.bukkit.event.HandlerList;
-import org.bukkit.inventory.InventoryView;
 import org.bukkit.inventory.Merchant;
 import org.bukkit.inventory.MerchantInventory;
+import org.bukkit.inventory.view.MerchantView;
 import org.jetbrains.annotations.NotNull;
 
 /**
@@ -19,7 +19,7 @@ public class TradeSelectEvent extends InventoryInteractEvent {
     //
     private final int index;
 
-    public TradeSelectEvent(@NotNull InventoryView transaction, int newIndex) {
+    public TradeSelectEvent(@NotNull MerchantView transaction, int newIndex) {
         super(transaction);
         this.index = newIndex;
     }
@@ -49,6 +49,12 @@ public class TradeSelectEvent extends InventoryInteractEvent {
         return getInventory().getMerchant();
     }
 
+    @NotNull
+    @Override
+    public MerchantView getView() {
+        return (MerchantView) super.getView();
+    }
+
     @NotNull
     @Override
     public HandlerList getHandlers() {

paper-api/src/main/java/org/bukkit/inventory/AnvilInventory.java

@@ -1,5 +1,6 @@
 package org.bukkit.inventory;
 
+import org.bukkit.inventory.view.AnvilView;
 import org.jetbrains.annotations.Nullable;
 
 /**
@@ -12,7 +13,9 @@ public interface AnvilInventory extends Inventory {
      * the default item name.
      *
      * @return the rename text
+     * @deprecated use {@link AnvilView#getRenameText()}.
      */
+    @Deprecated(forRemoval = true, since = "1.21")
     @Nullable
     String getRenameText();
 
@@ -20,28 +23,36 @@ public interface AnvilInventory extends Inventory {
      * Get the item cost (in amount) to complete the current repair.
      *
      * @return the amount
+     * @deprecated use {@link AnvilView#getRepairItemCost()}.
      */
+    @Deprecated(forRemoval = true, since = "1.21")
     int getRepairCostAmount();
 
     /**
      * Set the item cost (in amount) to complete the current repair.
      *
      * @param amount the amount
+     * @deprecated use {@link AnvilView#setRepairItemCost(int)}.
      */
+    @Deprecated(forRemoval = true, since = "1.21")
     void setRepairCostAmount(int amount);
 
     /**
      * Get the experience cost (in levels) to complete the current repair.
      *
      * @return the experience cost
+     * @deprecated use {@link AnvilView#getRepairCost()}.
      */
+    @Deprecated(forRemoval = true, since = "1.21")
     int getRepairCost();
 
     /**
      * Set the experience cost (in levels) to complete the current repair.
      *
      * @param levels the experience cost
+     * @deprecated use {@link AnvilView#setRepairCost(int)}.
      */
+    @Deprecated(forRemoval = true, since = "1.21")
     void setRepairCost(int levels);
 
     /**
@@ -53,7 +64,9 @@ public interface AnvilInventory extends Inventory {
      * maximum repair cost.
      *
      * @return the maximum experience cost
+     * @deprecated use {@link AnvilView#getMaximumRepairCost()}.
      */
+    @Deprecated(forRemoval = true, since = "1.21")
     int getMaximumRepairCost();
 
     /**
@@ -61,6 +74,8 @@ public interface AnvilInventory extends Inventory {
      * repair. The default value set by vanilla Minecraft is 40.
      *
      * @param levels the maximum experience cost
+     * @deprecated use {@link AnvilView#setMaximumRepairCost(int)}.
      */
+    @Deprecated(forRemoval = true, since = "1.21")
     void setMaximumRepairCost(int levels);
 }

paper-api/src/main/java/org/bukkit/inventory/InventoryView.java

@@ -13,7 +13,9 @@ public interface InventoryView {
     public static final int OUTSIDE = -999;
     /**
      * Represents various extra properties of certain inventory windows.
+     * @deprecated use {@link InventoryView} and its children
      */
+    @Deprecated(forRemoval = true, since = "1.21")
     public enum Property {
         /**
          * The progress of the down-pointing arrow in a brewing inventory.

paper-api/src/main/java/org/bukkit/inventory/view/AnvilView.java

@@ -0,0 +1,62 @@
+package org.bukkit.inventory.view;
+
+import org.bukkit.inventory.InventoryView;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * An instance of {@link InventoryView} which provides extra methods related to
+ * anvil view data.
+ */
+public interface AnvilView extends InventoryView {
+
+    /**
+     * Gets the rename text specified within the anvil's text field.
+     *
+     * @return The text within the anvil's text field if an item is present
+     * otherwise null
+     */
+    @Nullable
+    String getRenameText();
+
+    /**
+     * Gets the amount of items needed to repair.
+     *
+     * @return The amount of materials required to repair the item
+     */
+    int getRepairItemCountCost();
+
+    /**
+     * Gets the experience cost needed to repair.
+     *
+     * @return The repair cost in experience
+     */
+    int getRepairCost();
+
+    /**
+     * Gets the maximum repair cost needed to repair.
+     *
+     * @return The maximum repair cost in experience
+     */
+    int getMaximumRepairCost();
+
+    /**
+     * Sets the amount of repair materials required to repair the item.
+     *
+     * @param amount the amount of repair materials
+     */
+    void setRepairItemCountCost(int amount);
+
+    /**
+     * Sets the repair cost in experience.
+     *
+     * @param cost the experience cost to repair
+     */
+    void setRepairCost(int cost);
+
+    /**
+     * Sets maximum repair cost in experience.
+     *
+     * @param levels the levels to set
+     */
+    void setMaximumRepairCost(int levels);
+}

paper-api/src/main/java/org/bukkit/inventory/view/BeaconView.java

@@ -0,0 +1,84 @@
+package org.bukkit.inventory.view;
+
+import org.bukkit.inventory.InventoryView;
+import org.bukkit.potion.PotionEffectType;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * An instance of {@link InventoryView} which provides extra methods related to
+ * beacon view data.
+ */
+public interface BeaconView extends InventoryView {
+
+    /**
+     * Gets the tier of the beacon
+     * <p>
+     * Beacon tier is deduced by the height of the pyramid the beacon is
+     * standing on. The level of the beacon is 0 unless the beacon is activated.
+     *
+     * @return The tier of the beacon
+     */
+    int getTier();
+
+    /**
+     * Gets the primary effect of the beacon.
+     * <p>
+     * If the beacon level is high enough where the primary effect can be
+     * upgraded to level two, e.g. Speed 2. Instead of
+     * {@link #getSecondaryEffect()} being null it {@link #getSecondaryEffect()}
+     * returns the same {@link PotionEffectType} as this method.
+     *
+     * @return The primary effect enabled on the beacon
+     */
+    @Nullable
+    PotionEffectType getPrimaryEffect();
+
+    /**
+     * Gets the secondary effect of the beacon.
+     * <p>
+     * If the beacon level is high enough where the primary effect can be
+     * upgraded to level two, e.g. Speed 2. The secondary effect will return the
+     * same effect as {@link #getPrimaryEffect()}.
+     *
+     * @return The secondary effect enabled on the beacon
+     */
+    @Nullable
+    PotionEffectType getSecondaryEffect();
+
+    /**
+     * Sets the primary effect of the beacon, or null to clear
+     * <p>
+     * The {@link PotionEffectType} provided must be one that is already within
+     * the beacon as a valid option.
+     * <ol>
+     * <li>{@link PotionEffectType#SPEED}
+     * <li>{@link PotionEffectType#HASTE}
+     * <li>{@link PotionEffectType#RESISTANCE}
+     * <li>{@link PotionEffectType#JUMP_BOOST}
+     * <li>{@link PotionEffectType#STRENGTH}
+     * <li>{@link PotionEffectType#REGENERATION}
+     * </ol>
+     *
+     * @param effect desired primary effect
+     */
+    void setPrimaryEffect(@Nullable final PotionEffectType effect);
+
+    /**
+     * Sets the secondary effect on this beacon, or null to clear. Note that
+     * tier must be &gt;= 4 for this effect to be active.
+     * <p>
+     * The {@link PotionEffectType} provided must be one that is already within
+     * the beacon as a valid option.
+     * <ol>
+     * <li>{@link PotionEffectType#SPEED}
+     * <li>{@link PotionEffectType#HASTE}
+     * <li>{@link PotionEffectType#RESISTANCE}
+     * <li>{@link PotionEffectType#JUMP_BOOST}
+     * <li>{@link PotionEffectType#STRENGTH}
+     * <li>{@link PotionEffectType#REGENERATION}
+     * </ol>
+     *
+     * @param effect the desired secondary effect
+     */
+    void setSecondaryEffect(@Nullable final PotionEffectType effect);
+}

paper-api/src/main/java/org/bukkit/inventory/view/BrewingStandView.java

@@ -0,0 +1,42 @@
+package org.bukkit.inventory.view;
+
+import org.bukkit.inventory.InventoryView;
+
+/**
+ * An instance of {@link InventoryView} which provides extra methods related to
+ * brewing stand view data.
+ */
+public interface BrewingStandView extends InventoryView {
+
+    /**
+     * Gets the fuel level of this brewing stand.
+     * <p>
+     * The default maximum fuel level in minecraft is 20.
+     *
+     * @return The amount of fuel level left
+     */
+    int getFuelLevel();
+
+    /**
+     * Gets the amount of brewing ticks left.
+     *
+     * @return The amount of ticks left for the brewing task
+     */
+    int getBrewingTicks();
+
+    /**
+     * Sets the fuel level left.
+     *
+     * @param level the level of the fuel, which is no less than 0
+     * @throws IllegalArgumentException if the level is less than 0
+     */
+    void setFuelLevel(final int level) throws IllegalArgumentException;
+
+    /**
+     * Sets the brewing ticks left.
+     *
+     * @param ticks the ticks left, which is no less than 0
+     * @throws IllegalArgumentException if the ticks are less than 0
+     */
+    void setBrewingTicks(final int ticks) throws IllegalArgumentException;
+}

paper-api/src/main/java/org/bukkit/inventory/view/CrafterView.java

@@ -0,0 +1,33 @@
+package org.bukkit.inventory.view;
+
+import org.bukkit.inventory.InventoryView;
+
+/**
+ * An instance of {@link InventoryView} which provides extra methods related to
+ * crafter view data.
+ */
+public interface CrafterView extends InventoryView {
+
+    /**
+     * Checks if the given crafter slot is disabled.
+     *
+     * @param slot the slot to check
+     * @return true if the slot is disabled otherwise false
+     */
+    boolean isSlotDisabled(int slot);
+
+    /**
+     * Checks whether or not this crafter view is powered.
+     *
+     * @return true if the crafter is powered
+     */
+    boolean isPowered();
+
+    /**
+     * Sets the status of the crafter slot.
+     *
+     * @param slot the slot to set the status of
+     * @param disabled true if the slot should be disabled otherwise false
+     */
+    void setSlotDisabled(int slot, boolean disabled);
+}

paper-api/src/main/java/org/bukkit/inventory/view/EnchantmentView.java

@@ -0,0 +1,35 @@
+package org.bukkit.inventory.view;
+
+import org.bukkit.enchantments.EnchantmentOffer;
+import org.bukkit.inventory.InventoryView;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * An instance of {@link InventoryView} which provides extra methods related to
+ * enchantment table view data.
+ */
+public interface EnchantmentView extends InventoryView {
+
+    /**
+     * Gets the random enchantment seed used in this view
+     *
+     * @return The random seed used
+     */
+    int getEnchantmentSeed();
+
+    /**
+     * Gets the offers of this EnchantmentView
+     *
+     * @return The enchantment offers that are provided
+     */
+    @NotNull
+    EnchantmentOffer[] getOffers();
+
+    /**
+     * Sets the offers to provide to the player.
+     *
+     * @param offers The offers to provide
+     * @throws IllegalArgumentException if the array length isn't 3
+     */
+    void setOffers(@NotNull EnchantmentOffer[] offers) throws IllegalArgumentException;
+}

paper-api/src/main/java/org/bukkit/inventory/view/FurnaceView.java

@@ -0,0 +1,64 @@
+package org.bukkit.inventory.view;
+
+import org.bukkit.block.Furnace;
+import org.bukkit.inventory.InventoryView;
+
+/**
+ * An instance of {@link InventoryView} which provides extra methods related to
+ * furnace view data.
+ */
+public interface FurnaceView extends InventoryView {
+
+    /**
+     * The cook time for this view.
+     * <p>
+     * See {@link Furnace#getCookTime()} for more information.
+     *
+     * @return a number between 0 and 1
+     */
+    float getCookTime();
+
+    /**
+     * The total burn time for this view.
+     * <p>
+     * See {@link Furnace#getBurnTime()} for more information.
+     *
+     * @return a number between 0 and 1
+     */
+    float getBurnTime();
+
+    /**
+     * Checks whether or not the furnace is burning
+     *
+     * @return true given that the furnace is burning
+     */
+    boolean isBurning();
+
+    /**
+     * Sets the cook time
+     * <p>
+     * Setting cook time requires manipulation of both cookProgress and
+     * cookDuration. This method does a simple division to get total progress
+     * within the furnaces visual duration bar. For a clear visual effect
+     * (cookProgress / cookDuration) should return a number between 0 and 1
+     * inclusively.
+     *
+     * @param cookProgress the current of the cooking
+     * @param cookDuration the total cook time
+     */
+    void setCookTime(int cookProgress, int cookDuration);
+
+    /**
+     * Sets the burn time
+     * <p>
+     * Setting burn time requires manipulation of both burnProgress and
+     * burnDuration. This method does a simple division to get total progress
+     * within the furnaces visual burning bar. For a clear visual effect
+     * (burnProgress / burnDuration) should return a number between 0 and 1
+     * inclusively.
+     *
+     * @param burnProgress the progress towards the burnDuration
+     * @param burnDuration the total duration the view should be lit
+     */
+    void setBurnTime(int burnProgress, int burnDuration);
+}

paper-api/src/main/java/org/bukkit/inventory/view/LecternView.java

@@ -0,0 +1,24 @@
+package org.bukkit.inventory.view;
+
+import org.bukkit.inventory.InventoryView;
+
+/**
+ * An instance of {@link InventoryView} which provides extra methods related to
+ * lectern view data.
+ */
+public interface LecternView extends InventoryView {
+
+    /**
+     * Gets the page that the LecternView is on.
+     *
+     * @return The page the book is on
+     */
+    int getPage();
+
+    /**
+     * Sets the page of the lectern book.
+     *
+     * @param page the lectern book page
+     */
+    void setPage(final int page);
+}

paper-api/src/main/java/org/bukkit/inventory/view/LoomView.java

@@ -0,0 +1,29 @@
+package org.bukkit.inventory.view;
+
+import java.util.List;
+import org.bukkit.block.banner.PatternType;
+import org.bukkit.inventory.InventoryView;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * An instance of {@link InventoryView} which provides extra methods related to
+ * loom view data.
+ */
+public interface LoomView extends InventoryView {
+
+    /**
+     * Gets a list of all selectable to the player.
+     *
+     * @return A copy of the {@link PatternType}'s currently selectable by the
+     * player
+     */
+    @NotNull
+    List<PatternType> getSelectablePatterns();
+
+    /**
+     * Gets an index of the selected pattern.
+     *
+     * @return Index of the selected pattern
+     */
+    int getSelectedPatternIndex();
+}

paper-api/src/main/java/org/bukkit/inventory/view/MerchantView.java

@@ -0,0 +1,20 @@
+package org.bukkit.inventory.view;
+
+import org.bukkit.inventory.InventoryView;
+import org.bukkit.inventory.Merchant;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * An instance of {@link InventoryView} which provides extra methods related to
+ * merchant view data.
+ */
+public interface MerchantView extends InventoryView {
+
+    /**
+     * Gets the merchant that this view is for.
+     *
+     * @return The merchant that this view uses
+     */
+    @NotNull
+    Merchant getMerchant();
+}

paper-api/src/main/java/org/bukkit/inventory/view/StonecutterView.java

@@ -0,0 +1,36 @@
+package org.bukkit.inventory.view;
+
+import java.util.List;
+import org.bukkit.inventory.InventoryView;
+import org.bukkit.inventory.StonecuttingRecipe;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * An instance of {@link InventoryView} which provides extra methods related to
+ * stonecutter view data.
+ */
+public interface StonecutterView extends InventoryView {
+
+    /**
+     * Gets the current index of the selected recipe.
+     *
+     * @return The index of the selected recipe in the stonecutter or -1 if null
+     */
+    int getSelectedRecipeIndex();
+
+    /**
+     * Gets a copy of all recipes currently available to the player.
+     *
+     * @return A copy of the {@link StonecuttingRecipe}'s currently available
+     * for the player
+     */
+    @NotNull
+    List<StonecuttingRecipe> getRecipes();
+
+    /**
+     * Gets the amount of recipes currently available.
+     *
+     * @return The amount of recipes currently available for the player
+     */
+    int getRecipeAmount();
+}

paper-api/src/main/java/org/bukkit/inventory/view/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Package for {@link org.bukkit.inventory.InventoryView} child interfaces that
+ * house further usability for {@link org.bukkit.inventory.InventoryView}.
+ */
+@org.jetbrains.annotations.ApiStatus.Experimental
+package org.bukkit.inventory.view;