Merge pull request #10 from mutualmobile/development

Tushar-Acharya · Tushar-Acharya · commit 9260c5ea007e · 2016-02-14T20:43:28.000+05:30
Added JavaDoc #3
diff --git a/cardstack/src/main/java/com/mutualmobile/cardstack/CardStackAdapter.java b/cardstack/src/main/java/com/mutualmobile/cardstack/CardStackAdapter.java
@@ -16,12 +16,25 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * This class acts as an adapter for the {@link CardStackLayout} view. This adapter is intentionally
+ * made an abstract class with following abstract methods -
+ * <p/>
+ * <p/>
+ * {@link #getCount()} - Decides the number of views present in the view
+ * <p/>
+ * {@link #createView(int, ViewGroup)} - Creates the view for all positions in range [0, {@link #getCount()})
+ * <p/>
+ * Contains the logic for touch events in {@link #onTouch(View, MotionEvent)}
+ */
 public abstract class CardStackAdapter implements View.OnTouchListener, View.OnClickListener {
 
 
     public static final int ANIM_DURATION = 600;
     public static final int DECELERATION_FACTOR = 2;
 
+    public static final int INVALID_CARD_POSITION = -1;
+
     // Settings for the adapter from layout
     private float mCardGapBottom;
     private float mCardGap;
@@ -43,25 +56,39 @@ public abstract class CardStackAdapter implements View.OnTouchListener, View.OnC
     private float mTouchFirstY = -1;
     private float mTouchPrevY = -1;
     private float mTouchDistance = 0;
-    private int mSelectedCardPosition = -1;
+    private int mSelectedCardPosition = INVALID_CARD_POSITION;
     private float scaleFactorForElasticEffect;
     private int mParentPaddingTop = 0;
     private int mCardPaddingInternal = 0;
 
-    public View getCardView(int position) {
-        if (mCardViews == null) return null;
-
-        return mCardViews[position];
-    }
-
+    /**
+     * Defines and initializes the view to be shown in the {@link CardStackLayout}
+     * Provides two parameters to the sub-class namely -
+     *
+     * @param position
+     * @param container
+     *
+     * @return View corresponding to the position and parent container
+     */
     public abstract View createView(int position, ViewGroup container);
 
+    /**
+     * Defines the number of cards that are present in the {@link CardStackLayout}
+     *
+     * @return cardCount - Number of views in the related {@link CardStackLayout}
+     */
     public abstract int getCount();
 
-    public void setScreenTouchable(boolean screenTouchable) {
+    private void setScreenTouchable(boolean screenTouchable) {
         this.mScreenTouchable = screenTouchable;
     }
 
+    /**
+     * Returns true if no animation is in progress currently. Can be used to disable any events
+     * if they are not allowed during an animation. Returns false if an animation is in progress.
+     *
+     * @return - true if animation in progress, false otherwise
+     */
     public boolean isScreenTouchable() {
         return mScreenTouchable;
     }
@@ -78,7 +105,7 @@ public CardStackAdapter(Context context) {
         mCardViews = new View[getCount()];
     }
 
-    public void addView(final int position) {
+    void addView(final int position) {
         View root = createView(position, mParent);
         root.setOnTouchListener(this);
         root.setTag(R.id.cardstack_internal_position_tag, position);
@@ -101,14 +128,19 @@ public void addView(final int position) {
         mParent.addView(root);
     }
 
-    public float getCardFinalY(int position) {
+    private float getCardFinalY(int position) {
         return mScreenHeight - dp30 - ((getCount() - position) * mCardGapBottom) - mCardPaddingInternal;
     }
 
     private float getCardOriginalY(int position) {
         return mParentPaddingTop + mCardGap * position;
     }
 
+    /**
+     * Resets all cards in {@link CardStackLayout} to their initial positions
+     *
+     * @param r Execute r.run() once the reset animation is done
+     */
     public void resetCards(Runnable r) {
         List<Animator> animations = new ArrayList<>(getCount());
         for (int i = 0; i < getCount(); i++) {
@@ -118,6 +150,13 @@ public void resetCards(Runnable r) {
         startAnimations(animations, r, true);
     }
 
+    /**
+     * Plays together all animations passed in as parameter. Once animation is completed, r.run() is
+     * executed. If parameter isReset is set to true, {@link #mSelectedCardPosition} is set to {@link #INVALID_CARD_POSITION}
+     * @param animations
+     * @param r
+     * @param isReset
+     */
     private void startAnimations(List<Animator> animations, final Runnable r, final boolean isReset) {
         AnimatorSet animatorSet = new AnimatorSet();
         animatorSet.playTogether(animations);
@@ -129,7 +168,7 @@ public void onAnimationEnd(Animator animation) {
                 if (r != null) r.run();
                 setScreenTouchable(true);
                 if (isReset)
-                    mSelectedCardPosition = -1;
+                    mSelectedCardPosition = INVALID_CARD_POSITION;
             }
         });
         animatorSet.start();
@@ -153,13 +192,13 @@ public boolean onTouch(View v, MotionEvent event) {
                 mTouchDistance = 0;
                 break;
             case MotionEvent.ACTION_MOVE:
-                if (mSelectedCardPosition == -1)
+                if (mSelectedCardPosition == INVALID_CARD_POSITION)
                     moveCards(positionOfCardToMove, y - mTouchFirstY);
                 mTouchDistance += Math.abs(y - mTouchPrevY);
                 break;
             case MotionEvent.ACTION_CANCEL:
             case MotionEvent.ACTION_UP:
-                if (mTouchDistance < dp8 && Math.abs(y - mTouchFirstY) < dp8 && mSelectedCardPosition == -1) {
+                if (mTouchDistance < dp8 && Math.abs(y - mTouchFirstY) < dp8 && mSelectedCardPosition == INVALID_CARD_POSITION) {
                     onClick(v);
                 } else {
                     resetCards();
@@ -178,7 +217,7 @@ public void onClick(final View v) {
             return;
         }
         setScreenTouchable(false);
-        if (mSelectedCardPosition == -1) {
+        if (mSelectedCardPosition == INVALID_CARD_POSITION) {
             mSelectedCardPosition = (int) v.getTag(R.id.cardstack_internal_position_tag);
 
             List<Animator> animations = new ArrayList<>(getCount());
@@ -203,7 +242,7 @@ public void run() {
         }
     }
 
-    public void moveCards(int positionOfCardToMove, float diff) {
+    private void moveCards(int positionOfCardToMove, float diff) {
         if (diff < 0 || positionOfCardToMove < 0 || positionOfCardToMove >= getCount()) return;
         for (int i = positionOfCardToMove; i < getCount(); i++) {
             final View child = mCardViews[i];
@@ -220,7 +259,12 @@ public void moveCards(int positionOfCardToMove, float diff) {
         }
     }
 
-    public void setAdapterParams(CardStackLayout cardStackLayout) {
+    /**
+     * Provides an API to {@link CardStackLayout} to set the parameters provided to it in its XML
+     *
+     * @param cardStackLayout Parent of all cards
+     */
+    void setAdapterParams(CardStackLayout cardStackLayout) {
         mParent = cardStackLayout;
         mCardGapBottom = cardStackLayout.getCardGapBottom();
         mCardGap = cardStackLayout.getCardGap();
@@ -233,11 +277,43 @@ public void setAdapterParams(CardStackLayout cardStackLayout) {
         fullCardHeight = (int) (mScreenHeight - dp30 - dp8 - getCount() * mCardGapBottom);
     }
 
+    /**
+     * Resets all cards in {@link CardStackLayout} to their initial positions
+     */
     public void resetCards() {
         resetCards(null);
     }
 
+    /**
+     * Returns false if all the cards are in their initial position i.e. no card is selected
+     *
+     * Returns true if the {@link CardStackLayout} has a card selected and all other cards are
+     * at the bottom of the screen.
+     *
+     * @return true if any card is selected, false otherwise
+     */
     public boolean isCardSelected() {
-        return mSelectedCardPosition != -1;
+        return mSelectedCardPosition != INVALID_CARD_POSITION;
+    }
+
+    /**
+     * Returns the position of selected card. If no card
+     * is selected, returns {@link #INVALID_CARD_POSITION}
+     */
+    public int getSelectedCardPosition() {
+        return mSelectedCardPosition;
+    }
+
+    /**
+     * Since there is no view recycling in {@link CardStackLayout}, we maintain an instance of every
+     * view that is set for every position. This method returns a view at the requested position.
+     *
+     * @param position Position of card in {@link CardStackLayout}
+     * @return View at requested position
+     */
+    public View getCardView(int position) {
+        if (mCardViews == null) return null;
+
+        return mCardViews[position];
     }
-}
+}
diff --git a/cardstack/src/main/java/com/mutualmobile/cardstack/CardStackLayout.java b/cardstack/src/main/java/com/mutualmobile/cardstack/CardStackLayout.java
@@ -8,6 +8,19 @@
 import android.view.View;
 import android.widget.FrameLayout;
 
+/**
+ * Displays a list of cards as a stack on the screen.
+ * <p/>
+ * <b>XML attributes</b>
+ * <p/>
+ * See {@link R.styleable#CardStackLayout CardStackLayout Attributes}
+ *
+ * {@link R.styleable#CardStackLayout_showInitAnimation}
+ * {@link R.styleable#CardStackLayout_card_gap}
+ * {@link R.styleable#CardStackLayout_card_gap_bottom}
+ * {@link R.styleable#CardStackLayout_parallax_enabled}
+ * {@link R.styleable#CardStackLayout_parallax_scale}
+ */
 public class CardStackLayout extends FrameLayout {
     public static final boolean PARALLAX_ENABLED_DEFAULT = false;
     public static final boolean SHOW_INIT_ANIMATION_DEFAULT = true;
@@ -26,11 +39,20 @@ public CardStackLayout(Context context) {
         resetDefaults();
     }
 
-    public OnCardSelected getOnCardSelectedListener() {
+    /**
+     * package restricted
+     */
+    OnCardSelected getOnCardSelectedListener() {
         return mOnCardSelectedListener;
     }
 
-    public void setOnCardSelected(OnCardSelected onCardSelectedListener) {
+    /**
+     * Listen on card selection events for {@link CardStackLayout}. Sends clicked view and it's
+     * corresponding position in the callback.
+     *
+     * @param onCardSelectedListener listener
+     */
+    public void setOnCardSelectedListener(OnCardSelected onCardSelectedListener) {
         this.mOnCardSelectedListener = onCardSelectedListener;
     }
 
@@ -67,10 +89,17 @@ private void handleArgs(Context context, AttributeSet attrs, int defStyleAttr, i
         a.recycle();
     }
 
+    /**
+     * @return adapter of type {@link CardStackAdapter} that is set for this view.
+     */
     public CardStackAdapter getAdapter() {
         return mAdapter;
     }
 
+    /**
+     * Set the adapter for this {@link CardStackLayout}
+     * @param adapter Should extend {@link CardStackAdapter}
+     */
     public void setAdapter(CardStackAdapter adapter) {
         this.mAdapter = adapter;
         mAdapter.setAdapterParams(this);
@@ -88,10 +117,17 @@ public void run() {
         }
     }
 
+    /**
+     * @return currently set parallax scale value.
+     */
     public int getParallaxScale() {
         return mParallaxScale;
     }
 
+    /**
+     * Sets the value of parallax scale. Parallax scale is the factor which decides how much
+     * distance a card will scroll when the user drags it down.
+     */
     public void setParallaxScale(int mParallaxScale) {
         this.mParallaxScale = mParallaxScale;
     }
@@ -112,14 +148,23 @@ public void setShowInitAnimation(boolean mShowInitAnimation) {
         this.mShowInitAnimation = mShowInitAnimation;
     }
 
+    /**
+     * @return the gap (in pixels) between two consecutive cards
+     */
     public float getCardGap() {
         return mCardGap;
     }
 
+    /**
+     * Set the gap (in pixels) between two consecutive cards
+     */
     public void setCardGap(float mCardGap) {
         this.mCardGap = mCardGap;
     }
 
+    /**
+     * @return gap between the two consecutive cards when collapsed to the bottom of the screen
+     */
     public float getCardGapBottom() {
         return mCardGapBottom;
     }
@@ -128,21 +173,33 @@ public void setCardGapBottom(float mCardGapBottom) {
         this.mCardGapBottom = mCardGapBottom;
     }
 
+    /**
+     * @return true if a card is selected, false otherwise
+     */
     public boolean isCardSelected() {
         return mAdapter.isCardSelected();
     }
 
+    /**
+     * Removes the adapter that was previously set using {@link #setAdapter(CardStackAdapter)}
+     */
     public void removeAdapter() {
         if (getChildCount() > 0)
             removeAllViews();
         mAdapter = null;
         mOnCardSelectedListener = null;
     }
 
+    /**
+     * Animates the cards to their initial position in the layout.
+     */
     public void restoreCards() {
         mAdapter.resetCards();
     }
 
+    /**
+     * Intimates the implementing class about the selection of a card
+     */
     public interface OnCardSelected {
         void onCardSelected(View v, int position);
     }
