Add Slot#getRawItem(Player) and Slot#setRawItem(Player, ItemStack) me…

…thods to get raw inventory items. Resolves IPVP-MC#1

src/main/java/org/ipvp/canvas/slot/DefaultSlot.java

@@ -32,6 +32,7 @@
 import org.ipvp.canvas.template.ItemStackTemplate;
 import org.ipvp.canvas.template.StaticItemTemplate;
 import org.ipvp.canvas.type.AbstractMenu;
+import org.ipvp.canvas.type.MenuHolder;
 
 /**
  * A slot defined for default use by all Menus defined by this library.
@@ -103,6 +104,26 @@ public void setItemTemplate(ItemStackTemplate item) {
         });
     }
 
+    @Override
+    public ItemStack getRawItem(Player viewer) {
+        Optional<MenuHolder> menu = handle.getViewers().stream()
+                .filter(v -> v.getViewer().equals(viewer)).findFirst();
+        if (!menu.isPresent()) {
+            throw new IllegalStateException("Player not viewing parent menu");
+        }
+        return menu.get().getInventory().getItem(getIndex());
+    }
+
+    @Override
+    public void setRawItem(Player viewer, ItemStack item) {
+        Optional<MenuHolder> menu = handle.getViewers().stream()
+                .filter(v -> v.getViewer().equals(viewer)).findFirst();
+        if (!menu.isPresent()) {
+            throw new IllegalStateException("Player not viewing parent menu");
+        }
+        menu.get().getInventory().setItem(getIndex(), item);
+    }
+
     @Override
     public Optional<ClickHandler> getClickHandler() {
         return Optional.ofNullable(handler);

src/main/java/org/ipvp/canvas/slot/Slot.java

@@ -23,13 +23,13 @@
 
 package org.ipvp.canvas.slot;
 
-import java.util.Optional;
-
 import org.bukkit.entity.Player;
 import org.bukkit.inventory.ItemStack;
 import org.ipvp.canvas.ClickInformation;
 import org.ipvp.canvas.template.ItemStackTemplate;
 
+import java.util.Optional;
+
 /**
  * A slot is a position held by an Inventory that can be interacted with by users.
  * <p>
@@ -60,17 +60,17 @@ public interface Slot {
     void setClickOptions(ClickOptions options);
 
     /**
-     * Returns the item currently present in the slot. Return value
-     * has undefined behavior when the stack is of type AIR.
+     * Returns the item generated by the template for this slot.
      *
-     * @return The item in the slot
+     * @return the templated item
      * @deprecated superseded by {@link #getItem(Player)}
+     * @throws UnsupportedOperationException if the template is not {@link org.ipvp.canvas.template.StaticItemTemplate}.
      */
     @Deprecated
     ItemStack getItem();
 
     /**
-     * Returns the item currently present in the slot, rendered
+     * Returns the item generated by the template for this slot, rendered
      * for a specific player.
      *
      * @param viewer player viewing the menu/slot
@@ -79,7 +79,7 @@ public interface Slot {
     ItemStack getItem(Player viewer);
 
     /**
-     * Sets the item currently in the slot.
+     * Sets a static item template for the slot.
      *
      * @param item The new item in the slot
      */
@@ -92,6 +92,34 @@ public interface Slot {
      */
     void setItemTemplate(ItemStackTemplate item);
 
+    /**
+     * Gets the raw item currently in the opened menu inventory a {@link Player}
+     * has open.
+     *
+     * <p>This method differs from {@link #getItem()} or {@link #getItem(Player)}
+     * because it does not return a templated or generated item. As an example,
+     * this method can be used to retrieve items that a player may have inserted
+     * into a Menu themselves (which would not be templates).
+     *
+     * @param viewer the player with open menu containing this slot
+     * @return raw item
+     * @throws IllegalStateException if player is not viewing the menu
+     */
+    ItemStack getRawItem(Player viewer);
+
+    /**
+     * Sets the raw item in the menu inventory a {@link Player} has open.
+     *
+     * <p>Note: when the menu is updated via {@link org.ipvp.canvas.Menu#update(Player)} or
+     * is reopened, the raw item set by this method will be overriden to whatever
+     * is currently templated in the slot.
+     *
+     * @param viewer player with open menu containing this slot
+     * @param item item to set
+     * @throws IllegalStateException if player is not viewing the menu
+     */
+    void setRawItem(Player viewer, ItemStack item);
+
     /**
      * Returns a user-defined handler for when a Player clicks the slot.
      *