1 files changed, 113 insertions, 20 deletions
diff --git a/src/main/java/me/shedaniel/rei/api/AutoTransferHandler.java b/src/main/java/me/shedaniel/rei/api/AutoTransferHandler.java
index aff7a5e2b..45341c88e 100644
--- a/src/main/java/me/shedaniel/rei/api/AutoTransferHandler.java
+++ b/src/main/java/me/shedaniel/rei/api/AutoTransferHandler.java
@@ -25,13 +25,17 @@ package me.shedaniel.rei.api;
 
 import it.unimi.dsi.fastutil.ints.IntArrayList;
 import it.unimi.dsi.fastutil.ints.IntList;
+import net.fabricmc.api.EnvType;
+import net.fabricmc.api.Environment;
 import net.minecraft.client.MinecraftClient;
 import net.minecraft.client.gui.screen.ingame.ContainerScreen;
 import net.minecraft.container.Container;
 import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
 
 import java.util.function.Supplier;
 
+@Environment(EnvType.CLIENT)
 public interface AutoTransferHandler {
     
     /**
@@ -41,51 +45,127 @@ public interface AutoTransferHandler {
         return 0d;
     }
     
-    Result handle(Context context);
+    @NotNull
+    Result handle(@NotNull Context context);
     
     interface Result {
+        /**
+         * Creates a successful result, no further handlers will be called.
+         */
         static Result createSuccessful() {
             return new ResultImpl();
         }
-
+        
+        /**
+         * Creates a successful result, no further handlers will be called.
+         * Will return to the previous screen rather than staying open.
+         *
+         * @deprecated use {@link #blocksFurtherHandling(boolean)}
+         */
+        @Deprecated
         static Result createSuccessfulReturningToScreen() {
-            return new ResultImpl(true, true, true);
+            return createSuccessful().blocksFurtherHandling(true);
         }
-
+        
+        /**
+         * Creates a passing result, further handlers will be called.
+         * This will also mark the handler as not applicable.
+         */
         static Result createNotApplicable() {
             return new ResultImpl(false);
         }
         
+        /**
+         * Creates a passing result, further handlers will be called.
+         *
+         * @param errorKey The error itself
+         */
         static Result createFailed(String errorKey) {
             return new ResultImpl(errorKey, new IntArrayList(), 1744764928);
         }
         
+        /**
+         * Creates a passing result, further handlers will be called.
+         * The special color will be applied if this is the last handler.
+         *
+         * @param errorKey The error itself
+         * @param color    A special color for the button
+         */
         static Result createFailedCustomButtonColor(String errorKey, int color) {
             return new ResultImpl(errorKey, new IntArrayList(), color);
         }
         
+        /**
+         * Creates a passing result, further handlers will be called.
+         *
+         * @param errorKey The error itself
+         * @param redSlots A list of slots to be marked as red. Will be passed to {@link TransferRecipeCategory}.
+         */
         static Result createFailed(String errorKey, IntList redSlots) {
             return new ResultImpl(errorKey, redSlots, 1744764928);
         }
         
+        /**
+         * Creates a passing result, further handlers will be called.
+         * The special color will be applied if this is the last handler.
+         *
+         * @param errorKey The error itself
+         * @param color    A special color for the button
+         * @param redSlots A list of slots to be marked as red. Will be passed to {@link TransferRecipeCategory}.
+         */
         static Result createFailedCustomButtonColor(String errorKey, IntList redSlots, int color) {
             return new ResultImpl(errorKey, redSlots, color);
         }
         
+        /**
+         * Forces this handler to be the last handler, no further handlers will be called.
+         */
+        default Result blocksFurtherHandling() {
+            return blocksFurtherHandling(true);
+        }
+        
+        /**
+         * Forces this handler to be the last handler, no further handlers will be called.
+         */
+        Result blocksFurtherHandling(boolean returnsToScreen);
+        
+        /**
+         * @return the color in which the button should be displayed in.
+         */
         int getColor();
         
+        /**
+         * @return whether this handler has successfully handled the transfer.
+         */
         boolean isSuccessful();
-
+        
+        /**
+         * @return whether this handler should be the last handler.
+         */
+        boolean isBlocking();
+        
         /**
-         * Applicable if {@link #isSuccessful()} is true. Will return
-         * to the previous screen rather than staying open.
+         * Applicable if {@link #isSuccessful()} is true.
+         *
+         * @return whether to return to the previous screen rather than staying open
          */
         boolean isReturningToScreen();
         
+        /**
+         * @return whether the handler is applicable.
+         */
         boolean isApplicable();
         
+        /**
+         * Applicable if {@link #isSuccessful()} is false.
+         *
+         * @return the error message
+         */
         String getErrorKey();
         
+        /**
+         * @return a list of slots to be marked as red. Will be passed to {@link TransferRecipeCategory}.
+         */
         IntList getIntegers();
     }
     
@@ -103,6 +183,7 @@ public interface AutoTransferHandler {
         ContainerScreen<?> getContainerScreen();
         
         @Deprecated
+        @ApiStatus.ScheduledForRemoval
         default ContainerScreen<?> getHandledScreen() {
             return getContainerScreen();
         }
@@ -110,6 +191,7 @@ public interface AutoTransferHandler {
         RecipeDisplay getRecipe();
         
         @Deprecated
+        @ApiStatus.ScheduledForRemoval
         default Container getScreenHandler() {
             return getContainer();
         }
@@ -121,25 +203,24 @@ public interface AutoTransferHandler {
     
     @ApiStatus.Internal
     final class ResultImpl implements Result {
-        private boolean successful, applicable, returningToScreen;
+        private boolean successful, applicable, returningToScreen, blocking;
         private String errorKey;
         private IntList integers = new IntArrayList();
         private int color;
         
         private ResultImpl() {
-            this(true, true, false);
+            this(true, true);
         }
         
         public ResultImpl(boolean applicable) {
-            this(false, applicable, false);
+            this(false, applicable);
         }
-
-        public ResultImpl(boolean successful, boolean applicable, boolean returningToScreen) {
+        
+        public ResultImpl(boolean successful, boolean applicable) {
             this.successful = successful;
             this.applicable = applicable;
-            this.returningToScreen = returningToScreen;
         }
-
+        
         public ResultImpl(String errorKey, IntList integers, int color) {
             this.successful = false;
             this.applicable = true;
@@ -150,6 +231,13 @@ public interface AutoTransferHandler {
         }
         
         @Override
+        public Result blocksFurtherHandling(boolean returningToScreen) {
+            this.blocking = true;
+            this.returningToScreen = returningToScreen;
+            return this;
+        }
+        
+        @Override
         public int getColor() {
             return color;
         }
@@ -158,17 +246,22 @@ public interface AutoTransferHandler {
         public boolean isSuccessful() {
             return successful;
         }
-
+        
+        @Override
+        public boolean isBlocking() {
+            return successful || blocking;
+        }
+        
         @Override
         public boolean isApplicable() {
             return applicable;
         }
-
+        
         @Override
         public boolean isReturningToScreen() {
             return returningToScreen;
         }
-
+        
         @Override
         public String getErrorKey() {
             return errorKey;
@@ -182,9 +275,9 @@ public interface AutoTransferHandler {
     
     @ApiStatus.Internal
     final class ContextImpl implements Context {
-        boolean actuallyCrafting;
-        ContainerScreen<?> containerScreen;
-        Supplier<RecipeDisplay> recipeDisplaySupplier;
+        private boolean actuallyCrafting;
+        private ContainerScreen<?> containerScreen;
+        private Supplier<RecipeDisplay> recipeDisplaySupplier;
         
         private ContextImpl(boolean actuallyCrafting, ContainerScreen<?> containerScreen, Supplier<RecipeDisplay> recipeDisplaySupplier) {
             this.actuallyCrafting = actuallyCrafting;