[Bleeding] Inventory framework and events. Addresses BUKKIT-856

New events:
- InventoryOpenEvent
- InventoryClickEvent - detects any clicks on a slot or outside the window
  - In the creative inventory view, only clicks on the quickbar are detected
- InventoryCloseEvent
- BrewEvent - when a potion finishes brewing
- CraftItemEvent (a subevent of InventoryClickEvent) - fired when taking the crafted item
- PrepareItemCraftEvent - fired just before updating the result slot
Changes to existing events:
- EnchantItemEvent extends InventoryEvent and also has a new whichButton() method
- PrepareItemEnchantEvent also extends InventoryEvent
- FurnaceBurnEvent and FurnaceSmeltEvent now extend BlockEvent (as does BrewEvent)
- PlayerInventoryEvent is deprecated (though it never did anything anyway)
New subclasses of Inventory:
- BrewerInventory
- CraftingInventory
- DoubleChestInventory
- EnchantingInventory
- FurnaceInventory
New methods in Inventory:
- getViewers()
- getTitle()
- getType()
- getHolder()
- iterator() - Yes, inventories are now iterable!
  - The iterator is a ListIterator that does not support add or remove
New methods in Player:
- getOpenInventory()
- openInventory()
- openWorkbench()
- openEnchanting()
- closeInventory()
- setWindowProperty()
- getItemOnCursor()
- setItemOnCursor()
Other changes:
- createInventory() methods in Server to make inventories not linked to an object
- ContainerBlock is deprecated in favour of InventoryHolder
- New InventoryView class gives direct access to an inventory window!
- Removed the Slot class which did nothing and was used nowhere

Some small credit goes to Afforess (initial conception of openInventory() methods) and Drakia (initial conception of InventoryOpenEvent and InventoryCloseEvent).

By: Celtic Minstrel <celtic.minstrel.ca@some.place>

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

@@ -7,14 +7,15 @@ import org.bukkit.block.Block;
 import org.bukkit.enchantments.Enchantment;
 import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
-import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
+import org.bukkit.event.inventory.InventoryEvent;
+import org.bukkit.inventory.InventoryView;
 import org.bukkit.inventory.ItemStack;
 
 /**
  * Called when an ItemStack is successfully enchanted (currently at enchantment table)
  */
-public class EnchantItemEvent extends Event implements Cancellable {
+public class EnchantItemEvent extends InventoryEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
     private final Block table;
     private final ItemStack item;
@@ -22,14 +23,17 @@ public class EnchantItemEvent extends Event implements Cancellable {
     private boolean cancelled;
     private final Map<Enchantment,Integer> enchants;
     private final Player enchanter;
+    private int button;
 
-    public EnchantItemEvent(final Player enchanter, final Block table, final ItemStack item, final int level, final Map<Enchantment, Integer> enchants) {
+    public EnchantItemEvent(final Player enchanter, final InventoryView view, final Block table, final ItemStack item, final int level, final Map<Enchantment, Integer> enchants, final int i) {
+        super(view);
         this.enchanter = enchanter;
         this.table = table;
         this.item = item;
         this.level = level;
         this.enchants = new HashMap<Enchantment, Integer>(enchants);
         this.cancelled = false;
+        this.button = i;
     }
 
     /**
@@ -85,6 +89,14 @@ public class EnchantItemEvent extends Event implements Cancellable {
         return enchants;
     }
 
+    /**
+     * Which button was pressed to initiate the enchanting.
+     * @return The button index (0, 1, or 2).
+     */
+    public int whichButton() {
+        return button;
+    }
+
     public boolean isCancelled() {
         return cancelled;
     }

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

@@ -3,14 +3,15 @@ package org.bukkit.event.enchantment;
 import org.bukkit.block.Block;
 import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
-import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
+import org.bukkit.event.inventory.InventoryEvent;
+import org.bukkit.inventory.InventoryView;
 import org.bukkit.inventory.ItemStack;
 
 /**
  * Called when an ItemStack is inserted in an enchantment table - can be called multiple times
  */
-public class PrepareItemEnchantEvent extends Event implements Cancellable {
+public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
     private final Block table;
     private final ItemStack item;
@@ -19,7 +20,8 @@ public class PrepareItemEnchantEvent extends Event implements Cancellable {
     private boolean cancelled;
     private final Player enchanter;
 
-    public PrepareItemEnchantEvent(final Player enchanter, final Block table, final ItemStack item, final int[] levelsOffered, final int bonus) {
+    public PrepareItemEnchantEvent(final Player enchanter, InventoryView view, final Block table, final ItemStack item, final int[] levelsOffered, final int bonus) {
+        super(view);
         this.enchanter = enchanter;
         this.table = table;
         this.item = item;

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

@@ -0,0 +1,39 @@
+package org.bukkit.event.inventory;
+
+import org.bukkit.block.Block;
+import org.bukkit.event.Cancellable;
+import org.bukkit.event.HandlerList;
+import org.bukkit.event.block.BlockEvent;
+import org.bukkit.inventory.BrewerInventory;
+
+public class BrewEvent extends BlockEvent implements Cancellable {
+    private static final HandlerList handlers = new HandlerList();
+    private BrewerInventory contents;
+    private boolean cancelled;
+
+    public BrewEvent(Block brewer, BrewerInventory contents) {
+        super(brewer);
+        this.contents = contents;
+    }
+
+    public BrewerInventory getContents() {
+        return contents;
+    }
+
+    public boolean isCancelled() {
+        return cancelled;
+    }
+
+    public void setCancelled(boolean cancel) {
+        cancelled = cancel;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+}

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

@@ -0,0 +1,21 @@
+package org.bukkit.event.inventory;
+
+import org.bukkit.event.inventory.InventoryType.SlotType;
+import org.bukkit.inventory.InventoryView;
+import org.bukkit.inventory.Recipe;
+
+public class CraftItemEvent extends InventoryClickEvent {
+    private Recipe recipe;
+
+    public CraftItemEvent(Recipe recipe, InventoryView what, SlotType type, int slot, boolean right, boolean shift) {
+        super(what, type, slot, right, shift);
+        this.recipe = recipe;
+    }
+
+    /**
+     * @return A copy of the current recipe on the crafting matrix.
+     */
+    public Recipe getRecipe() {
+        return recipe;
+    }
+}

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

@@ -2,23 +2,22 @@ package org.bukkit.event.inventory;
 
 import org.bukkit.block.Block;
 import org.bukkit.event.Cancellable;
-import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
+import org.bukkit.event.block.BlockEvent;
 import org.bukkit.inventory.ItemStack;
 
 /**
  * Called when an ItemStack is successfully burned as fuel in a furnace.
  */
-public class FurnaceBurnEvent extends Event implements Cancellable {
+public class FurnaceBurnEvent extends BlockEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
-    private final Block furnace;
     private final ItemStack fuel;
     private int burnTime;
     private boolean cancelled;
     private boolean burning;
 
     public FurnaceBurnEvent(final Block furnace, final ItemStack fuel, final int burnTime) {
-        this.furnace = furnace;
+        super(furnace);
         this.fuel = fuel;
         this.burnTime = burnTime;
         this.cancelled = false;
@@ -29,9 +28,11 @@ public class FurnaceBurnEvent extends Event implements Cancellable {
      * Gets the block for the furnace involved in this event
      *
      * @return the block of the furnace
+     * @deprecated In favour of {@link #getBlock()}.
      */
+    @Deprecated
     public Block getFurnace() {
-        return furnace;
+        return getBlock();
     }
 
     /**

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

@@ -2,22 +2,21 @@ package org.bukkit.event.inventory;
 
 import org.bukkit.block.Block;
 import org.bukkit.event.Cancellable;
-import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
+import org.bukkit.event.block.BlockEvent;
 import org.bukkit.inventory.ItemStack;
 
 /**
  * Called when an ItemStack is successfully smelted in a furnace.
  */
-public class FurnaceSmeltEvent extends Event implements Cancellable {
+public class FurnaceSmeltEvent extends BlockEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
-    private final Block furnace;
     private final ItemStack source;
     private ItemStack result;
     private boolean cancelled;
 
     public FurnaceSmeltEvent(final Block furnace, final ItemStack source, final ItemStack result) {
-        this.furnace = furnace;
+        super(furnace);
         this.source = source;
         this.result = result;
         this.cancelled = false;
@@ -27,9 +26,11 @@ public class FurnaceSmeltEvent extends Event implements Cancellable {
      * Gets the block for the furnace involved in this event
      *
      * @return the block of the furnace
+     * @deprecated In favour of {@link #getBlock()}.
      */
+    @Deprecated
     public Block getFurnace() {
-        return furnace;
+        return getBlock();
     }
 
     /**

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

@@ -0,0 +1,143 @@
+package org.bukkit.event.inventory;
+
+import org.bukkit.inventory.Inventory;
+import org.bukkit.inventory.InventoryView;
+import org.bukkit.entity.HumanEntity;
+import org.bukkit.event.Cancellable;
+import org.bukkit.event.HandlerList;
+import org.bukkit.event.inventory.InventoryType.SlotType;
+import org.bukkit.inventory.ItemStack;
+
+public class InventoryClickEvent extends InventoryEvent implements Cancellable {
+    private static final HandlerList handlers = new HandlerList();
+    private SlotType slot_type;
+    private boolean rightClick, shiftClick;
+    private Result result;
+    private int whichSlot;
+    private int rawSlot;
+    private ItemStack current = null;
+
+    public InventoryClickEvent(InventoryView what, SlotType type, int slot, boolean right, boolean shift) {
+        super(what);
+        this.slot_type = type;
+        this.rightClick = right;
+        this.shiftClick = shift;
+        this.result = Result.DEFAULT;
+        this.rawSlot = slot;
+        this.whichSlot = what.convertSlot(slot);
+    }
+
+    /**
+     * Get the type of slot that was clicked.
+     * @return The slot type.
+     */
+    public SlotType getSlotType() {
+        return slot_type;
+    }
+
+    /**
+     * Get the current item on the cursor.
+     * @return The cursor item
+     */
+    public ItemStack getCursor() {
+        return getView().getCursor();
+    }
+
+    /**
+     * Get the current item in the clicked slot.
+     * @return The slot item.
+     */
+    public ItemStack getCurrentItem() {
+        if(slot_type == SlotType.OUTSIDE) return current;
+        return getView().getItem(rawSlot);
+    }
+
+    /**
+     * @return True if the click is a right-click.
+     */
+    public boolean isRightClick() {
+        return rightClick;
+    }
+
+    /**
+     * @return True if the click is a left-click.
+     */
+    public boolean isLeftClick() {
+        return !rightClick;
+    }
+
+    /**
+     * Shift can be combined with right-click or left-click as a modifier.
+     * @return True if the click is a shift-click.
+     */
+    public boolean isShiftClick() {
+        return shiftClick;
+    }
+
+    public void setResult(Result newResult) {
+        result = newResult;
+    }
+
+    public Result getResult() {
+        return result;
+    }
+
+    /**
+     * Get the player who performed the click.
+     * @return The clicking player.
+     */
+    public HumanEntity getWhoClicked() {
+        return getView().getPlayer();
+    }
+
+    /**
+     * Set the item on the cursor.
+     * @param what The new cursor item.
+     */
+    public void setCursor(ItemStack what) {
+        getView().setCursor(what);
+    }
+
+    /**
+     * Set the current item in the slot.
+     * @param what The new slot item.
+     */
+    public void setCurrentItem(ItemStack what) {
+        if(slot_type == SlotType.OUTSIDE) current = what;
+        else getView().setItem(rawSlot, what);
+    }
+
+    public boolean isCancelled() {
+        return result == Result.DENY;
+    }
+
+    public void setCancelled(boolean toCancel) {
+        result = toCancel ? Result.DENY : Result.ALLOW;
+    }
+
+    /**
+     * The slot number that was clicked, ready for passing to {@link Inventory#getItem(int)}. Note
+     * that there may be two slots with the same slot number, since a view links two different inventories.
+     * @return The slot number.
+     */
+    public int getSlot() {
+        return whichSlot;
+    }
+
+    /**
+     * The raw slot number, which is unique for the view.
+     * @return The slot number.
+     */
+    public int getRawSlot() {
+        return rawSlot;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+}

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

@@ -0,0 +1,34 @@
+
+package org.bukkit.event.inventory;
+
+import org.bukkit.entity.HumanEntity;
+import org.bukkit.event.HandlerList;
+import org.bukkit.inventory.InventoryView;
+
+/**
+ * Represents a player related inventory event
+ */
+public class InventoryCloseEvent extends InventoryEvent {
+    private static final HandlerList handlers = new HandlerList();
+
+    public InventoryCloseEvent(InventoryView transaction) {
+        super(transaction);
+    }
+
+    /**
+     * Returns the player involved in this event
+     * @return Player who is involved in this event
+     */
+    public final HumanEntity getPlayer() {
+        return transaction.getPlayer();
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+}

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

@@ -0,0 +1,58 @@
+
+package org.bukkit.event.inventory;
+
+import java.util.List;
+
+import org.bukkit.event.HandlerList;
+import org.bukkit.entity.HumanEntity;
+import org.bukkit.event.Event;
+import org.bukkit.inventory.Inventory;
+import org.bukkit.inventory.InventoryView;
+
+/**
+ * Represents a player related inventory event
+ */
+public class InventoryEvent extends Event {
+    private static final HandlerList handlers = new HandlerList();
+    protected InventoryView transaction;
+
+    public InventoryEvent(InventoryView transaction) {
+        this.transaction = transaction;
+    }
+
+    /**
+     * Gets the primary Inventory involved in this transaction
+     *
+     * @return The upper inventory.
+     */
+    public Inventory getInventory() {
+        return transaction.getTopInventory();
+    }
+
+    /**
+     * Gets the list of players viewing the primary (upper) inventory involved in this event
+     *
+     * @return A list of people viewing.
+     */
+    public List<HumanEntity> getViewers() {
+        return transaction.getTopInventory().getViewers();
+    }
+
+    /**
+     * Gets the view object itself
+     *
+     * @return InventoryView
+     */
+    public InventoryView getView() {
+        return transaction;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+}

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

@@ -0,0 +1,61 @@
+
+package org.bukkit.event.inventory;
+
+import org.bukkit.inventory.InventoryView;
+import org.bukkit.entity.HumanEntity;
+import org.bukkit.event.Cancellable;
+import org.bukkit.event.HandlerList;
+
+/**
+ * Represents a player related inventory event
+ */
+public class InventoryOpenEvent extends InventoryEvent implements Cancellable {
+    private static final HandlerList handlers = new HandlerList();
+    private boolean cancelled;
+
+    public InventoryOpenEvent(InventoryView transaction) {
+        super(transaction);
+        this.cancelled = false;
+    }
+
+    /**
+     * Returns the player involved in this event
+     * @return Player who is involved in this event
+     */
+    public final HumanEntity getPlayer() {
+        return transaction.getPlayer();
+    }
+
+    /**
+     * Gets the cancellation state of this event. A cancelled event will not
+     * be executed in the server, but will still pass to other plugins
+     *
+     * If an inventory open event is cancelled, the inventory screen will not show.
+     *
+     * @return true if this event is cancelled
+     */
+    public boolean isCancelled() {
+        return cancelled;
+    }
+
+    /**
+     * Sets the cancellation state of this event. A cancelled event will not
+     * be executed in the server, but will still pass to other plugins
+     *
+     * If an inventory open event is cancelled, the inventory screen will not show.
+     *
+     * @param cancel true if you wish to cancel this event
+     */
+    public void setCancelled(boolean cancel) {
+        cancelled = cancel;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+}

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

@@ -0,0 +1,91 @@
+package org.bukkit.event.inventory;
+
+public enum InventoryType {
+    /**
+     * A chest inventory, with 0, 9, 18, 27, 36, 45, or 54 slots of type CONTAINER.
+     */
+    CHEST(27,"Chest"),
+    /**
+     * A dispenser inventory, with 9 slots of type CONTAINER.
+     */
+    DISPENSER(9,"Dispenser"),
+    /**
+     * A furnace inventory, with a RESULT slot, a CRAFTING slot, and a FUEL slot.
+     */
+    FURNACE(3,"Furnace"),
+    /**
+     * A workbench inventory, with 9 CRAFTING slots and a RESULT slot.
+     */
+    WORKBENCH(10,"Crafting"),
+    /**
+     * A player's crafting inventory, with 4 CRAFTING slots and a RESULT slot. Also implies that the
+     * 4 ARMOR slots are accessible.
+     */
+    CRAFTING(5,"Crafting"),
+    /**
+     * An enchantment table inventory, with one CRAFTING slot and three enchanting buttons.
+     */
+    ENCHANTING(1,"Enchanting"),
+    /**
+     * A brewing stand inventory, with one FUEL slot and three CRAFTING slots.
+     */
+    BREWING(4,"Brewing"),
+    /**
+     * A player's inventory, with 9 QUICKBAR slots, 27 CONTAINER slots, and 4 ARMOR slots. The
+     * ARMOUR slots may not be visible to the player, though.
+     */
+    PLAYER(36,"Player"),
+    /**
+     * The creative mode inventory, with only 9 QUICKBAR slots and nothing else. (The actual
+     * creative interface with the items is client-side and cannot be altered by the server.)
+     */
+    CREATIVE(9,"Creative");
+    private final int size;
+    private final String title;
+
+    private InventoryType(int defaultSize, String defaultTitle) {
+        size = defaultSize;
+        title = defaultTitle;
+    }
+
+    public int getDefaultSize() {
+        return size;
+    }
+
+    public String getDefaultTitle() {
+        return title;
+    }
+
+    public enum SlotType {
+        /**
+         * A result slot in a furnace or crafting inventory.
+         */
+        RESULT,
+        /**
+         * A slot in the crafting matrix, or the input slot in a furnace inventory,
+         * the potion slot in the brewing stand, or the enchanting slot.
+         */
+        CRAFTING,
+        /**
+         * An armour slot in the player's inventory.
+         */
+        ARMOR,
+        /**
+         * A regular slot in the container or the player's inventory; anything not covered
+         * by the other enum values.
+         */
+        CONTAINER,
+        /**
+         * A slot in the bottom row or quickbar.
+         */
+        QUICKBAR,
+        /**
+         * A pseudo-slot representing the area outside the inventory window.
+         */
+        OUTSIDE,
+        /**
+         * The fuel slot in a furnace inventory, or the ingredient slot in a brewing stand inventory.
+         */
+        FUEL;
+    }
+}

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

@@ -0,0 +1,52 @@
+package org.bukkit.event.inventory;
+
+import org.bukkit.event.HandlerList;
+import org.bukkit.inventory.CraftingInventory;
+import org.bukkit.inventory.InventoryView;
+import org.bukkit.inventory.Recipe;
+
+public class PrepareItemCraftEvent extends InventoryEvent {
+    private static final HandlerList handlers = new HandlerList();
+    private boolean repair;
+    private CraftingInventory matrix;
+
+    public PrepareItemCraftEvent(CraftingInventory what, InventoryView view, boolean isRepair) {
+        super(view);
+        this.matrix = what;
+        this.repair = isRepair;
+    }
+
+    /**
+     * Get the recipe that has been formed. If this event was triggered by a tool repair, this
+     * will be a temporary shapeless recipe representing the repair.
+     * @return The recipe being crafted.
+     */
+    public Recipe getRecipe() {
+        return matrix.getRecipe();
+    }
+
+    /**
+     * @return The crafting inventory on which the recipe was formed.
+     */
+    @Override
+    public CraftingInventory getInventory() {
+        return matrix;
+    }
+
+    /**
+     * Check if this event was triggered by a tool repair operation rather than a crafting recipe.
+     * @return True if this is a repair.
+     */
+    public boolean isRepair() {
+        return repair;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+}

paper-api/src/main/java/org/bukkit/event/player/PlayerInventoryEvent.java

@@ -2,11 +2,16 @@ package org.bukkit.event.player;
 
 import org.bukkit.entity.Player;
 import org.bukkit.event.HandlerList;
+import org.bukkit.event.inventory.InventoryClickEvent;
+import org.bukkit.event.inventory.InventoryOpenEvent;
 import org.bukkit.inventory.Inventory;
 
 /**
- * Represents a player related inventory event
+ * Represents a player related inventory event; note that this event never actually did anything
+ * @deprecated Use {@link InventoryClickEvent} or {@link InventoryOpenEvent} instead, or one of
+ * the other inventory events in {@link org.bukkit.event.inventory}.
  */
+@Deprecated
 public class PlayerInventoryEvent extends PlayerEvent {
     private static final HandlerList handlers = new HandlerList();
     protected Inventory inventory;