Merge pull request #186 from stepstone-tech/feature/issue-160

Tab subtitles and error message

Author: zawadz88

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [Unversioned]
+### Added
+- An option to show a subtitle in each tab
+- An option to display an error message below step title in tabbed stepper
+
 ## [4.0.0]
 ### Added
 - `setEndButtonVisible` and `setBackButtonVisible` methods in `StepViewModel.Builder` for toggling button visibility (issue #104)
@@ -18,4 +23,5 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - **Breaking change:** Changed `setNextButtonLabel` methods in `StepViewModel.Builder` to `setEndButtonLabel` so that it works for both Next and Complete buttons (issue #107)
 - **Breaking change:** Split `content` stepper feedback type into `content_progress` and `content_fade`.
 
-[4.0.0]: https://github.com/stepstone-tech/android-material-stepper/compare/v3.3.0...4.0.0
+[Unversioned]: https://github.com/stepstone-tech/android-material-stepper/compare/v4.0.0...develop
+[4.0.0]: https://github.com/stepstone-tech/android-material-stepper/compare/v3.3.0...v4.0.0

README.md

@@ -20,6 +20,7 @@ Moreover, you can find there other examples, e.g. how to persist state on rotati
 - [Advanced usage](#advanced-usage)
   - [Making extra operations before going to the next step](#making-extra-operations-before-going-to-the-next-step)
   - [Changing button labels & compound drawables per step](#changing-button-labels--compound-drawables-per-step)
+  - [Subtitles in tabs](#subtitles-in-tabs)
   - [Custom styling](#custom-styling)
   - [Using same stepper styling across the application](#using-same-stepper-styling-across-the-application)
   - [Showing a Back button on first step](#showing-a-back-button-on-first-step)
@@ -300,6 +301,11 @@ It is also possible to hide Back/Next/Complete buttons on each step if needed.
 To do so you need to call `setBackButtonVisible(false)` and/or `setEndButtonVisible(false)` on
 `StepViewModel.Builder` in your adapter.
 
+### Subtitles in tabs
+You can set a subtitle for each step in stepper with tabs, e.g. to mark a step as optional.
+To do so you need to set the subtitle by calling `StepViewModel.Builder#setSubtitle(int)` or `StepViewModel.Builder#setSubtitle(CharSequence)`
+in your adapter's `getViewModel` method.
+
 ### Custom styling
 Basic styling can be done by choosing the active and inactive step colors. 
 There are some additional properties which can be changed directly from StepperLayout's attributes e.g. the background of bottom navigation buttons (see [StepperLayout attributes](#stepperlayout-attributes))
@@ -352,6 +358,7 @@ To show an error in the tabbed stepper if step verification fails you need to se
 <p><img src ="./gifs/error-on-tabs.gif" width="640" /></p>
 
 If you want to keep the error displayed when going back to the previous step you need to also set `ms_showErrorStateOnBackEnabled` to `true`.
+If you want display an error message below the step title you need to set `ms_showErrorMessageEnabled` to `true`. The message set in `VerificationError` will be then displayed.
 
 ### Stepper feedback
 It is possible to show stepper feedback for ongoing operations (see [Stepper feedback](https://material.io/guidelines/components/steppers.html#steppers-types-of-steppers)).
@@ -510,6 +517,7 @@ A list of `ms_stepperLayoutTheme` attributes responsible for styling of StepperL
 | *ms_stepTabDoneIndicatorStyle*    | Used by ms_stepDoneIndicator in layout/ms_step_tab            |
 | *ms_stepTabIconBackgroundStyle*   | Used by ms_stepIconBackground in layout/ms_step_tab           |
 | *ms_stepTabTitleStyle*            | Used by ms_stepTitle in layout/ms_step_tab                    |
+| *ms_stepTabSubtitleStyle*         | Used by ms_stepSubtitle in layout/ms_step_tab                    |
 | *ms_stepTabDividerStyle*          | Used by ms_stepDivider in layout/ms_step_tab                  |
 
 ## Changelog

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

@@ -17,6 +17,7 @@
 package com.stepstone.stepper;
 
 import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
 
 /**
  * A base step interface which all {@link StepperLayout} steps must implement.
@@ -30,7 +31,7 @@ public interface Step {
      * he should handle this in {@link #onError(VerificationError)}.
      * @return the cause of the validation failure or <i>null</i> if step was validated successfully
      */
-    VerificationError verifyStep();
+    @Nullable VerificationError verifyStep();
 
     /**
      * Called when this step gets selected in the the stepper layout.

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

@@ -250,6 +250,8 @@ public void goToPrevStep() {
 
     private boolean mShowErrorStateOnBackEnabled;
 
+    private boolean mShowErrorMessageEnabled;
+
     private boolean mTabNavigationEnabled;
 
     private boolean mInProgress;
@@ -551,6 +553,21 @@ public boolean isShowErrorStateOnBackEnabled() {
         return mShowErrorStateOnBackEnabled;
     }
 
+    /**
+     * Set whether an error message below step title should appear when an error occurs
+     * @param showErrorMessageEnabled true if an error message below step title should appear when an error occurs
+     */
+    public void setShowErrorMessageEnabled(boolean showErrorMessageEnabled) {
+        this.mShowErrorMessageEnabled = showErrorMessageEnabled;
+    }
+
+    /**
+     * @return true if an error message below step title should appear when an error occurs
+     */
+    public boolean isShowErrorMessageEnabled() {
+        return mShowErrorMessageEnabled;
+    }
+
     /**
      * @return true if step navigation is possible by clicking on the tabs directly, false otherwise
      */
@@ -570,11 +587,11 @@ public void setTabNavigationEnabled(boolean tabNavigationEnabled) {
      * Updates the error state in the UI.
      * It does nothing if showing error state is disabled.
      * This is used internally to show the error on tabs.
-     * @param hasError true if error should be shown, false otherwise
+     * @param error not null if error should be shown, null otherwise
      * @see #setShowErrorStateEnabled(boolean)
      */
-    public void updateErrorState(boolean hasError) {
-        updateErrorFlag(hasError);
+    public void updateErrorState(@Nullable VerificationError error) {
+        updateError(error);
         if (mShowErrorStateEnabled) {
             invalidateCurrentPosition();
         }
@@ -592,10 +609,6 @@ public void setOffscreenPageLimit(int limit) {
         mPager.setOffscreenPageLimit(limit);
     }
 
-    public void updateErrorFlag(boolean hasError) {
-        mStepperType.setErrorFlag(mCurrentStepPosition, hasError);
-    }
-
     /**
      * Shows a progress indicator if not already shown. This does not have to be a progress bar and it depends on chosen stepper feedback types.
      * @param progressMessage optional progress message if supported by the selected types
@@ -827,6 +840,8 @@ private void extractValuesFromAttributes(AttributeSet attrs, @AttrRes int defSty
             mShowErrorStateOnBackEnabled = a.getBoolean(R.styleable.StepperLayout_ms_showErrorStateOnBack, false);
             mShowErrorStateOnBackEnabled = a.getBoolean(R.styleable.StepperLayout_ms_showErrorStateOnBackEnabled, mShowErrorStateOnBackEnabled);
 
+            mShowErrorMessageEnabled = a.getBoolean(R.styleable.StepperLayout_ms_showErrorMessageEnabled, false);
+
             mTabNavigationEnabled = a.getBoolean(R.styleable.StepperLayout_ms_tabNavigationEnabled, true);
 
             mStepperLayoutTheme = a.getResourceId(R.styleable.StepperLayout_ms_stepperLayoutTheme, R.style.MSDefaultStepperLayoutTheme);
@@ -855,7 +870,7 @@ private Step findCurrentStep() {
     }
 
     private void updateErrorFlagWhenGoingBack() {
-        updateErrorFlag(mShowErrorStateOnBackEnabled && mStepperType.getErrorAtPosition(mCurrentStepPosition));
+        updateError(mShowErrorStateOnBackEnabled ? mStepperType.getErrorAtPosition(mCurrentStepPosition) : null);
     }
 
     @UiThread
@@ -887,10 +902,14 @@ private boolean verifyCurrentStep(Step step) {
             result = true;
         }
 
-        updateErrorFlag(result);
+        updateError(verificationError);
         return result;
     }
 
+    private void updateError(@Nullable VerificationError error) {
+        mStepperType.setError(mCurrentStepPosition, error);
+    }
+
     private void onError(@NonNull VerificationError verificationError) {
         Step step = findCurrentStep();
         if (step != null) {

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

@@ -25,7 +25,7 @@ public class VerificationError {
     /**
      * A message explaining the cause of the error.
      */
-    private String mErrorMessage;
+    private final String mErrorMessage;
 
     public VerificationError(String errorMessage) {
         this.mErrorMessage = errorMessage;

material-stepper/src/main/java/com/stepstone/stepper/internal/type/AbstractStepperType.java

@@ -19,10 +19,12 @@
 import android.support.annotation.CallSuper;
 import android.support.annotation.ColorInt;
 import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
 import android.support.annotation.RestrictTo;
-import android.util.SparseBooleanArray;
+import android.util.SparseArray;
 
 import com.stepstone.stepper.StepperLayout;
+import com.stepstone.stepper.VerificationError;
 import com.stepstone.stepper.adapter.StepAdapter;
 
 import static android.support.annotation.RestrictTo.Scope.LIBRARY;
@@ -55,7 +57,7 @@ public abstract class AbstractStepperType {
 
     final StepperLayout mStepperLayout;
 
-    final SparseBooleanArray mStepErrors = new SparseBooleanArray();
+    final SparseArray<VerificationError> mStepErrors = new SparseArray<>();
 
     public AbstractStepperType(StepperLayout stepperLayout) {
         this.mStepperLayout = stepperLayout;
@@ -71,19 +73,20 @@ public AbstractStepperType(StepperLayout stepperLayout) {
     /**
      * Called to set whether the stepPosition has an error or not, changing it's appearance.
      * @param stepPosition the step to set the error
-     * @param hasError whether it has error or not
+     * @param error error instance or null if no error
      */
-    public void setErrorFlag(int stepPosition, boolean hasError) {
-        mStepErrors.put(stepPosition, hasError);
+    public void setError(int stepPosition, @Nullable VerificationError error) {
+        mStepErrors.put(stepPosition, error);
     }
 
     /**
      * Checks if there's an error for the step.
      *
      * @param stepPosition the step to check for error
-     * @return true if there's an error for this step
+     * @return an error for this step or null if no error
      */
-    public boolean getErrorAtPosition(int stepPosition) {
+    @Nullable
+    public VerificationError getErrorAtPosition(int stepPosition) {
         return mStepErrors.get(stepPosition);
     }
 

material-stepper/src/main/java/com/stepstone/stepper/internal/type/TabsStepperType.java

@@ -16,13 +16,15 @@
 
 package com.stepstone.stepper.internal.type;
 
+import android.content.Context;
 import android.support.annotation.NonNull;
 import android.support.annotation.RestrictTo;
-import android.util.SparseBooleanArray;
+import android.util.SparseArray;
 import android.view.View;
 
 import com.stepstone.stepper.R;
 import com.stepstone.stepper.StepperLayout;
+import com.stepstone.stepper.VerificationError;
 import com.stepstone.stepper.adapter.StepAdapter;
 import com.stepstone.stepper.internal.widget.TabsContainer;
 import com.stepstone.stepper.viewmodel.StepViewModel;
@@ -39,8 +41,6 @@
 @RestrictTo(LIBRARY)
 public class TabsStepperType extends AbstractStepperType {
 
-    private static final List<CharSequence> EDIT_MODE_STEP_TITLES = Arrays.<CharSequence>asList("Step 1", "Step 2");
-
     private final TabsContainer mTabsContainer;
 
     public TabsStepperType(StepperLayout stepperLayout) {
@@ -53,8 +53,12 @@ public TabsStepperType(StepperLayout stepperLayout) {
         mTabsContainer.setListener(stepperLayout);
 
         if (stepperLayout.isInEditMode()) {
-            mTabsContainer.setSteps(EDIT_MODE_STEP_TITLES);
-            mTabsContainer.updateSteps(0, new SparseBooleanArray());
+            Context context = stepperLayout.getContext();
+            mTabsContainer.setSteps(Arrays.asList(
+                    new StepViewModel.Builder(context).setTitle("Step 1").create(),
+                    new StepViewModel.Builder(context).setTitle("Step 2").setSubtitle("Optional").create())
+            );
+            mTabsContainer.updateSteps(0, new SparseArray<VerificationError>(), false);
             mTabsContainer.setVisibility(View.VISIBLE);
         }
     }
@@ -67,7 +71,8 @@ public void onStepSelected(int newStepPosition, boolean userTriggeredChange) {
         if (!mStepperLayout.isShowErrorStateEnabled()) {
             mStepErrors.clear();
         }
-        mTabsContainer.updateSteps(newStepPosition, mStepErrors);
+
+        mTabsContainer.updateSteps(newStepPosition, mStepErrors, mStepperLayout.isShowErrorMessageEnabled());
     }
 
     /**
@@ -76,13 +81,12 @@ public void onStepSelected(int newStepPosition, boolean userTriggeredChange) {
     @Override
     public void onNewAdapter(@NonNull StepAdapter stepAdapter) {
         super.onNewAdapter(stepAdapter);
-        List<CharSequence> titles = new ArrayList<>();
+        List<StepViewModel> stepViewModels = new ArrayList<>();
         final int stepCount = stepAdapter.getCount();
         for (int i = 0; i < stepCount; i++) {
-            final StepViewModel stepViewModel = stepAdapter.getViewModel(i);
-            titles.add(stepViewModel.getTitle());
+            stepViewModels.add(stepAdapter.getViewModel(i));
         }
-        mTabsContainer.setSteps(titles);
+        mTabsContainer.setSteps(stepViewModels);
         mTabsContainer.setVisibility(stepCount > 1 ? View.VISIBLE : View.GONE);
     }
 }

material-stepper/src/main/java/com/stepstone/stepper/internal/util/ObjectsCompat.java

@@ -0,0 +1,37 @@
+package com.stepstone.stepper.internal.util;
+
+import android.support.annotation.Nullable;
+
+/**
+ * This class consists of {@code static} utility methods for operating
+ * on objects.
+ *
+ * This backports {@link java.util.Objects} which is available since API 19.
+ *
+ * @author Piotr Zawadzki
+ */
+public final class ObjectsCompat {
+
+    private ObjectsCompat() {
+    }
+
+    /**
+     * Returns {@code true} if the arguments are equal to each other
+     * and {@code false} otherwise.
+     * Consequently, if both arguments are {@code null}, {@code true}
+     * is returned and if exactly one argument is {@code null}, {@code
+     * false} is returned.  Otherwise, equality is determined by using
+     * the {@link Object#equals equals} method of the first
+     * argument.
+     *
+     * @param a an object
+     * @param b an object to be compared with {@code a} for equality
+     * @return {@code true} if the arguments are equal to each other
+     * and {@code false} otherwise
+     * @see Object#equals(Object)
+     */
+    @SuppressWarnings("PMD.SuspiciousEqualsMethodName")
+    public static boolean equals(@Nullable Object a, @Nullable Object b) {
+        return (a == b) || (a != null && a.equals(b));
+    }
+}

material-stepper/src/main/java/com/stepstone/stepper/internal/widget/ColorableProgressBar.java

@@ -18,7 +18,6 @@
 
 import android.animation.ObjectAnimator;
 import android.content.Context;
-import android.content.res.TypedArray;
 import android.graphics.drawable.Drawable;
 import android.graphics.drawable.LayerDrawable;
 import android.support.annotation.ColorInt;
@@ -76,20 +75,6 @@ public ColorableProgressBar(Context context, AttributeSet attrs, int defStyleAtt
         mProgressColor = ContextCompat.getColor(context, R.color.ms_selectedColor);
         mProgressBackgroundColor = ContextCompat.getColor(context, R.color.ms_unselectedColor);
         super.setProgressDrawable(ContextCompat.getDrawable(context, R.drawable.ms_colorable_progress_bar));
-
-        if (attrs != null) {
-            final TypedArray a = getContext().obtainStyledAttributes(
-                    attrs, R.styleable.ColorableProgressBar, defStyleAttr, 0);
-
-            if (a.hasValue(R.styleable.ColorableProgressBar_ms_progressPrimaryColor)) {
-                mProgressColor = a.getColor(R.styleable.ColorableProgressBar_ms_progressPrimaryColor, mProgressColor);
-            }
-            if (a.hasValue(R.styleable.ColorableProgressBar_ms_progressBackgroundColor)) {
-                mProgressBackgroundColor = a.getColor(R.styleable.ColorableProgressBar_ms_progressBackgroundColor, mProgressBackgroundColor);
-            }
-
-            a.recycle();
-        }
         updateProgressDrawable();
     }
 

material-stepper/src/main/java/com/stepstone/stepper/internal/widget/DottedProgressBar.java

@@ -17,7 +17,6 @@
 package com.stepstone.stepper.internal.widget;
 
 import android.content.Context;
-import android.content.res.TypedArray;
 import android.graphics.drawable.Drawable;
 import android.support.annotation.ColorInt;
 import android.support.annotation.RestrictTo;
@@ -68,19 +67,6 @@ public DottedProgressBar(Context context, AttributeSet attrs, int defStyleAttr)
         super(context, attrs, defStyleAttr);
         mSelectedColor = ContextCompat.getColor(context, R.color.ms_selectedColor);
         mUnselectedColor = ContextCompat.getColor(context, R.color.ms_unselectedColor);
-        if (attrs != null) {
-            final TypedArray a = getContext().obtainStyledAttributes(
-                    attrs, R.styleable.DottedProgressBar, defStyleAttr, 0);
-
-            if (a.hasValue(R.styleable.DottedProgressBar_ms_activeDotColor)) {
-                mSelectedColor = a.getColor(R.styleable.DottedProgressBar_ms_activeDotColor, mSelectedColor);
-            }
-            if (a.hasValue(R.styleable.DottedProgressBar_ms_inactiveDotColor)) {
-                mUnselectedColor = a.getColor(R.styleable.DottedProgressBar_ms_inactiveDotColor, mUnselectedColor);
-            }
-
-            a.recycle();
-        }
     }
 
     public void setUnselectedColor(@ColorInt int unselectedColor) {