add option to intercept BACK button action for Blocking Steps (issue #25) (#27)

* - added onBackClicked option for BlockingStep
* - updated library version to 1.1.1
* - added onBackClicked option for BlockingStep
* - updated JavaDoc description

Author: fabiozo

README.md

@@ -11,7 +11,7 @@ Quoting the [documentation](https://www.google.com/design/spec/components/steppe
 
 ## Download (from JCenter)
 ```groovy
-compile 'com.stepstone.stepper:material-stepper:1.1.0'
+compile 'com.stepstone.stepper:material-stepper:1.1.1'
 ```
 
 ## Supported steppers
@@ -206,6 +206,7 @@ In order to set that color:
 ### Make an IO operation before going to the next step (optional)
 If the user wants to e.g. save something in the database or make a network call on a separate Thread after clicking on the Next button
 he can perform these operations and then invoke the `goToNextStep()` method of the `StepperLayout.OnNextClickedCallback` in the current Step.
+While operations are performed, and the user would like to go back you can cancel them and then invoke `onBackClicked()` method of the `StepperLayout.OnBackClickedCallback`.
 <p><img src ="./gifs/delayed-transition.gif" width="360" height="640"/></p>
 The fragment must implement `BlockingStep` instead of `Step`.
 Also, make sure that `goToNextStep()` gets called on the main thread.
@@ -227,6 +228,13 @@ public class DelayedTransitionStepFragmentSample extends Fragment implements Blo
         }, 2000L);
     }
 
+    @Override
+    @UiThread
+    public void onBackClicked(StepperLayout.OnBackClickedCallback callback) {
+        Toast.makeText(this.getContext(), "Your custom back action. Here you should cancel currently running operations", Toast.LENGTH_SHORT).show();
+        callback.goToPrevStep();
+     }
+
 }
 ```
 

gradle.properties

@@ -19,4 +19,4 @@
 
 POM_GROUP_ID=com.stepstone.stepper
 POM_ARTIFACT_ID=material-stepper
-POM_VERSION=1.1.0
+POM_VERSION=1.1.1

material-stepper/src/main/java/com/stepstone/stepper/BlockingStep.java

@@ -32,9 +32,20 @@ public interface BlockingStep extends Step {
      * and the user can go to the next step. This is so that the current step might perform
      * some last minute operations e.g. a network call before switching to the next step.
      * {@link StepperLayout.OnNextClickedCallback#goToNextStep()} must be called once these operations finish.
+     *
      * @param callback callback to call once the user wishes to finally switch to the next step
      */
     @UiThread
     void onNextClicked(StepperLayout.OnNextClickedCallback callback);
 
+    /**
+     * Notifies this step that the previous button/tab was clicked. This is so that the current step might perform
+     * some last minute operations e.g. a network call before switching to previous step.
+     * {@link StepperLayout.OnBackClickedCallback#goToPrevStep()} must be called once these operations finish.
+     *
+     * @param callback callback to call once the user wishes to finally switch to the previous step
+     */
+    @UiThread
+    void onBackClicked(StepperLayout.OnBackClickedCallback callback);
+
 }

material-stepper/src/main/java/com/stepstone/stepper/StepperLayout.java

@@ -69,18 +69,21 @@ public interface StepperListener {
 
         /**
          * Called when all of the steps were completed successfully
+         *
          * @param completeButton the complete button that was clicked to complete the flow
          */
         void onCompleted(View completeButton);
 
         /**
          * Called when a verification error occurs for one of the steps
+         *
          * @param verificationError verification error
          */
         void onError(VerificationError verificationError);
 
         /**
          * Called when the current step position changes
+         *
          * @param newStepPosition new step position
          */
         void onStepSelected(int newStepPosition);
@@ -125,6 +128,23 @@ public final void goToNextStep() {
         }
 
     }
+
+    public final class OnBackClickedCallback {
+
+        @UiThread
+        public final void goToPrevStep() {
+            if (mCurrentStepPosition <= 0) {
+                if (mShowBackButtonOnFirstStep) {
+                    mListener.onReturn();
+                }
+                return;
+            }
+            mCurrentStepPosition--;
+            onUpdate(mCurrentStepPosition);
+        }
+
+    }
+
     private ViewPager mPager;
 
     private Button mBackNavigationButton;
@@ -143,9 +163,9 @@ public final void goToNextStep() {
 
     private ColorStateList mBackButtonColor;
 
-    private ColorStateList  mNextButtonColor;
+    private ColorStateList mNextButtonColor;
 
-    private ColorStateList  mCompleteButtonColor;
+    private ColorStateList mCompleteButtonColor;
 
     @ColorInt
     private int mUnselectedColor;
@@ -226,6 +246,7 @@ public void setListener(@NonNull StepperListener listener) {
 
     /**
      * Sets the new step adapter and updates the stepper layout based on the new adapter.
+     *
      * @param stepAdapter step adapter
      */
     public void setAdapter(@NonNull AbstractStepAdapter stepAdapter) {
@@ -246,7 +267,8 @@ public void run() {
 
     /**
      * Sets the new step adapter and updates the stepper layout based on the new adapter.
-     * @param stepAdapter step adapter
+     *
+     * @param stepAdapter         step adapter
      * @param currentStepPosition the initial step position, must be in the range of the adapter item count
      */
     public void setAdapter(@NonNull AbstractStepAdapter stepAdapter, @IntRange(from = 0) int currentStepPosition) {
@@ -256,6 +278,7 @@ public void setAdapter(@NonNull AbstractStepAdapter stepAdapter, @IntRange(from
 
     /**
      * Overrides the default page transformer used in the underlying {@link ViewPager}
+     *
      * @param pageTransformer new page transformer
      */
     public void setPageTransformer(@Nullable ViewPager.PageTransformer pageTransformer) {
@@ -277,9 +300,9 @@ public int getTabStepDividerWidth() {
     @Override
     @UiThread
     public void onTabClicked(int position) {
-        if (position > mCurrentStepPosition){
+        if (position > mCurrentStepPosition) {
             onNext();
-        } else if (position < mCurrentStepPosition){
+        } else if (position < mCurrentStepPosition) {
             setCurrentStepPosition(position);
         }
     }
@@ -455,14 +478,14 @@ private Step findCurrentStep() {
     }
 
     private void onPrevious() {
-        if (mCurrentStepPosition <= 0) {
-            if (mShowBackButtonOnFirstStep) {
-                mListener.onReturn();
-            }
-            return;
+        Step step = findCurrentStep();
+
+        OnBackClickedCallback onBackClickedCallback = new OnBackClickedCallback();
+        if (step instanceof BlockingStep) {
+            ((BlockingStep) step).onBackClicked(onBackClickedCallback);
+        } else {
+            onBackClickedCallback.goToPrevStep();
         }
-        mCurrentStepPosition--;
-        onUpdate(mCurrentStepPosition);
     }
 
     @UiThread
@@ -474,7 +497,7 @@ private void onNext() {
         }
         OnNextClickedCallback onNextClickedCallback = new OnNextClickedCallback();
         if (step instanceof BlockingStep) {
-            ((BlockingStep)step).onNextClicked(onNextClickedCallback);
+            ((BlockingStep) step).onNextClicked(onNextClickedCallback);
         } else {
             onNextClickedCallback.goToNextStep();
         }

sample/src/main/java/com/stepstone/stepper/sample/step/DelayedTransitionStepFragmentSample.java

@@ -29,6 +29,7 @@
 import android.view.View;
 import android.view.ViewGroup;
 import android.widget.Button;
+import android.widget.Toast;
 
 import com.stepstone.stepper.BlockingStep;
 import com.stepstone.stepper.StepperLayout;
@@ -116,6 +117,13 @@ public void run() {
         }, 2000L);
     }
 
+    @Override
+    @UiThread
+    public void onBackClicked(StepperLayout.OnBackClickedCallback callback) {
+        Toast.makeText(this.getContext(), "Your custom back action. Here you should cancel currently running operations", Toast.LENGTH_SHORT).show();
+        callback.goToPrevStep();
+    }
+
     @Override
     public void onSaveInstanceState(Bundle outState) {
         outState.putInt(CLICKS_KEY, i);