Merge pull request #8 from AdamMc331/master

Documentation!

build.gradle

@@ -5,7 +5,7 @@ buildscript {
         jcenter()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:1.2.3'
+        classpath 'com.android.tools.build:gradle:2.0.0'
         classpath 'com.jfrog.bintray.gradle:gradle-bintray-plugin:1.2'
         classpath 'com.github.dcendents:android-maven-plugin:1.2'
         // NOTE: Do not place your application dependencies here; they belong

example/src/main/java/terranovaproductions/newcomicreader/sample/DemoCircleMenuFragment.java

@@ -9,7 +9,7 @@ import android.view.View;
 import android.view.ViewGroup;
 import android.widget.Toast;
 
-import com.novaapps.floatingactionmenu;
+import com.novaapps.floatingactionmenu.FloatingActionMenu;
 
 /**
  * Created by renqinghe on 15-11-4.

example/src/main/java/terranovaproductions/newcomicreader/sample/DemoLineMenuFragment.java

@@ -7,7 +7,7 @@ import android.view.LayoutInflater;
 import android.view.View;
 import android.view.ViewGroup;
 
-import com.novaapps.floatingactionmenu;
+import com.novaapps.floatingactionmenu.FloatingActionMenu;
 
 /**
  * Created by renqinghe on 15-11-4.

example/src/main/res/layout/fragment_circle_menu.xml

@@ -5,12 +5,13 @@
     android:layout_height="match_parent"
     android:background="@android:color/white">
 
-    <com.novaapps.floatingactionmenu
+    <com.novaapps.floatingactionmenu.FloatingActionMenu
         android:id="@+id/fab_menu_circle"
         android:layout_width="match_parent"
         android:layout_height="match_parent"
         android:layout_marginBottom="16dp"
-        android:layout_marginRight="16dp">
+        android:layout_marginRight="16dp"
+        android:layout_marginEnd="16dp">
 
         <!--First button as menu button-->
         <android.support.design.widget.FloatingActionButton
@@ -47,6 +48,6 @@
             fab:fabSize="mini"
             fab:backgroundTint="@color/material_orange"/>
 
-    </com.novaapps.floatingactionmenu>
+    </com.novaapps.floatingactionmenu.FloatingActionMenu>
 
 </LinearLayout>

example/src/main/res/layout/fragment_line_menu.xml

@@ -5,12 +5,13 @@
     android:layout_height="match_parent"
     android:background="@android:color/holo_green_light">
 
-    <com.novaapps.floatingactionmenu
+    <com.novaapps.floatingactionmenu.FloatingActionMenu
         android:id="@+id/fab_menu_line"
         android:layout_width="match_parent"
         android:layout_height="match_parent"
         android:layout_marginBottom="16dp"
-        android:layout_marginRight="16dp">
+        android:layout_marginRight="16dp"
+        android:layout_marginEnd="16dp">
 
         <!--First button as menu button-->
         <android.support.design.widget.FloatingActionButton
@@ -47,6 +48,6 @@
             fab:fabSize="mini"
             fab:backgroundTint="@android:color/holo_red_light"/>
 
-    </com.novaapps.floatingactionmenu>
+    </com.novaapps.floatingactionmenu.FloatingActionMenu>
 
 </LinearLayout>

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
-#Thu Oct 22 00:08:36 IST 2015
+#Tue Apr 19 19:32:29 EDT 2016
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-2.4-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-2.10-all.zip

library/src/main/java/com/novaapps/floatingactionmenu/FloatingActionMenu.java

@@ -1,4 +1,4 @@
-package com.novaapps;
+package com.novaapps.floatingactionmenu;
 
 import android.animation.Animator;
 import android.animation.AnimatorSet;
@@ -27,32 +27,112 @@ import android.widget.TextView;
 import java.util.ArrayList;
 
 /**
+ * Component for a FloatingActionMenu.
+ *
  * Created by charry on 2015/6/11. https://gist.github.com/douo/dfde289778a9b3b6918f and modified by Tristan Wiley
  */
 public class FloatingActionMenu extends ViewGroup {
 
+    //-- Properties --//
+
+    /**
+     * Defines the rate of change for the open animation.
+     */
     static final TimeInterpolator DEFAULT_OPEN_INTERPOLATOR = new OvershootInterpolator();
+
+    /**
+     * Defines the rate of change for the close animation.
+     */
     static final TimeInterpolator DEFAULT_CLOSE_INTERPOLATOR = new AnticipateInterpolator();
 
+    /**
+     * The main menu button that is always visible. Clicking this will open/close the menu.
+     */
     private FloatingActionButton mMenuButton;
+
+    /**
+     * The list of menu items to appear when the menu opens.
+     */
     private ArrayList<FloatingActionButton> mMenuItems;
+
+    /**
+     * The list of labels to appear next to the menu items.
+     */
     private ArrayList<TextView> mMenuItemLabels;
+
+    /**
+     * Animators to animate the appearance/disappearance of the menu items.
+     */
     private ArrayList<ItemAnimator> mMenuItemAnimators;
+
+    /**
+     * The set of animations to occur when the menu opens.
+     */
     private AnimatorSet mOpenAnimatorSet = new AnimatorSet();
+
+    /**
+     * The set of animations to occur when the menu closes.
+     */
     private AnimatorSet mCloseAnimatorSet = new AnimatorSet();
+
+    /**
+     * The image that will appear inside the main menu item.
+     */
     private ImageView mIcon;
 
+    /**
+     * A flag representing the open state of the menu.
+     */
     private boolean mOpen;
+
+    /**
+     * A flag representing the current animation stte of the menu.
+     */
     private boolean animating;
+
+    /**
+     * A flag representing whether or not the menu should close if the user touches outside of the menu items.
+     */
     private boolean mIsSetClosedOnTouchOutside = true;
+
+    /**
+     * The duration of the open/close animations.
+     */
     private long duration = 300;
+
+    /**
+     * A flag representing whether or not the menu appearance is a circle (true) or linear menu (false).
+     */
     private boolean isCircle = false;
+
+    /**
+     * The radius of the circular menu (if application).
+     */
     private int mRadius = 256;
+
+    /**
+     * If the radius of the circle is a multiple of the FB width, this is what that ratio is.
+     */
     private float multipleOfFB = 0;
+
+    /**
+     * The gap between menu items.
+     */
     private int mItemGap = 0;
 
+    /**
+     * A click listener for the main menu item.
+     */
     private OnMenuItemClickListener onMenuItemClickListener;
+
+    /**
+     * A listener for when the menu toggles between open and closed.
+     */
     private OnMenuToggleListener onMenuToggleListener;
+
+    /**
+     * A GestureDetector that looks for gestures outside the FAM and closes it if necessary.
+     */
     GestureDetector mGestureDetector = new GestureDetector(getContext(),
             new GestureDetector.SimpleOnGestureListener() {
 
@@ -66,10 +146,18 @@ public class FloatingActionMenu extends ViewGroup {
                     close();
                     return true;
                 }
-            });
+            }
+    );
+
+    /**
+     * An OnItemClickListener that handles clicks on a menu item or one of its labels.
+     */
     private OnClickListener mOnItemClickListener = new OnClickListener() {
         @Override
         public void onClick(View v) {
+            // If we click a menu item, call our MenuItemClickListener.
+            // Else - we are clicking a label, call our MenuItemClickListener.
+            // This is split into an if/else since we access different arrays for each.
             if (v instanceof FloatingActionButton) {
                 int i = mMenuItems.indexOf(v);
                 if (onMenuItemClickListener != null) {
@@ -86,6 +174,7 @@ public class FloatingActionMenu extends ViewGroup {
         }
     };
 
+    //-- Constructors --//
 
     public FloatingActionMenu(Context context) {
         this(context, null, 0);
@@ -97,12 +186,16 @@ public class FloatingActionMenu extends ViewGroup {
 
     public FloatingActionMenu(Context context, AttributeSet attrs, int defStyleAttr) {
         super(context, attrs, defStyleAttr);
+
+        // Default all lists to 5 items.
         mMenuItems = new ArrayList<>(5);
         mMenuItemAnimators = new ArrayList<>(5);
         mMenuItemLabels = new ArrayList<>(5);
         mIcon = new ImageView(context);
     }
 
+    //-- Overriden methods --//
+
     @Override
     protected void onFinishInflate() {
         bringChildToFront(mMenuButton);
@@ -113,6 +206,9 @@ public class FloatingActionMenu extends ViewGroup {
     @Override
     public void addView(@NonNull View child, int index, LayoutParams params) {
         super.addView(child, index, params);
+
+        // If the child count is greater than one, we are adding menu items.
+        // If the child count is not greater than one, we are adding the initial menu item.
         if (getChildCount() > 1) {
             if (child instanceof FloatingActionButton) {
                 addMenuItem((FloatingActionButton) child);
@@ -132,70 +228,9 @@ public class FloatingActionMenu extends ViewGroup {
         }
     }
 
-    public void toggle() {
-        if (!mOpen) {
-            open();
-        } else {
-            close();
-        }
-    }
-
-    public void open() {
-        d("open");
-        startOpenAnimator();
-        mOpen = true;
-        if (onMenuToggleListener != null) {
-            onMenuToggleListener.onMenuToggle(true);
-        }
-    }
-
-    public void close() {
-        startCloseAnimator();
-        mOpen = false;
-        if (onMenuToggleListener != null) {
-            onMenuToggleListener.onMenuToggle(true);
-        }
-    }
-
-    protected void startCloseAnimator() {
-        mCloseAnimatorSet.start();
-        for (ItemAnimator anim : mMenuItemAnimators) {
-            anim.startCloseAnimator();
-        }
-    }
-
-    protected void startOpenAnimator() {
-        mOpenAnimatorSet.start();
-        for (ItemAnimator anim : mMenuItemAnimators) {
-            anim.startOpenAnimator();
-        }
-    }
-
-    public void addMenuItem(FloatingActionButton item) {
-        mMenuItems.add(item);
-        mMenuItemAnimators.add(new ItemAnimator(item));
-
-        TextView button = new TextView(getContext());
-
-        LayoutParams params = new LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT);
-        button.setLayoutParams(params);
-
-        button.setBackgroundResource(R.drawable.rounded_corners);
-
-        button.setTextColor(Color.WHITE);
-        button.setText(item.getContentDescription());
-
-        Integer paddingSize = (int)button.getTextSize() / 3;
-
-        button.setPadding(paddingSize, paddingSize, paddingSize, paddingSize);
-
-        addView(button);
-        mMenuItemLabels.add(button);
-        item.setTag(button);
-        item.setOnClickListener(mOnItemClickListener);
-        button.setOnClickListener(mOnItemClickListener);
-    }
-
+    /**
+     * Handles the measuring of the FAM, and sets the size according to the number of children.
+     */
     @Override
     protected void onMeasure(int widthMeasureSpec, int heightMeasureSpec) {
         int widthSize = MeasureSpec.getSize(widthMeasureSpec);
@@ -240,6 +275,9 @@ public class FloatingActionMenu extends ViewGroup {
                 resolveSize(height, heightMeasureSpec));
     }
 
+    /**
+     * Handles a touch event in the ViewGroup and closes the FAM if necessary.
+     */
     @Override
     public boolean onTouchEvent(@NonNull MotionEvent event) {
         if (mIsSetClosedOnTouchOutside) {
@@ -249,7 +287,9 @@ public class FloatingActionMenu extends ViewGroup {
         }
     }
 
-
+    /**
+     * Sets the layout of the ViewGroup dependent on the number of menu items as well as menu direction.
+     */
     @Override
     protected void onLayout(boolean changed, int l, int t, int r, int b) {
         System.out.println("onLayout:" + changed);
@@ -335,6 +375,143 @@ public class FloatingActionMenu extends ViewGroup {
         }
     }
 
+    /**
+     * Saves the state of the menu item as open or close to be able to handle device rotations.
+     */
+    @Override
+    public Parcelable onSaveInstanceState() {
+        d("onSaveInstanceState");
+        Bundle bundle = new Bundle();
+        bundle.putParcelable("instanceState", super.onSaveInstanceState());
+        bundle.putBoolean("mOpen", mOpen);
+        // ... save everything
+        return bundle;
+    }
+
+    /**
+     * Restores the state of the FAM after a rotation.
+     */
+    @Override
+    public void onRestoreInstanceState(Parcelable state) {
+        d("onRestoreInstanceState");
+        if (state instanceof Bundle) {
+            Bundle bundle = (Bundle) state;
+            mOpen = bundle.getBoolean("mOpen");
+            // ... load everything
+            state = bundle.getParcelable("instanceState");
+        }
+        super.onRestoreInstanceState(state);
+    }
+
+    @Override
+    protected void onDetachedFromWindow() {
+        d("onDetachedFromWindow");
+        //getBackground().setAlpha(bgAlpha);//reset default alpha
+        super.onDetachedFromWindow();
+    }
+
+    @Override
+    public void setBackground(Drawable background) {
+        if (background instanceof ColorDrawable) {
+            // after activity finish and relaucher , background drawable state still remain?
+            int bgAlpha = Color.alpha(((ColorDrawable) background).getColor());
+            d("bg:" + Integer.toHexString(bgAlpha));
+            super.setBackground(background);
+        } else {
+            throw new IllegalArgumentException("floating only support color background");
+        }
+    }
+
+    //-- Open and close methods methods --//
+
+    /**
+     * Toggles the menu between open and closed, depending on its current state.
+     */
+    public void toggle() {
+        if (!mOpen) {
+            open();
+        } else {
+            close();
+        }
+    }
+
+    /**
+     * Opens the FloatingActionMenu.
+     */
+    public void open() {
+        d("open");
+        startOpenAnimator();
+        mOpen = true;
+        if (onMenuToggleListener != null) {
+            onMenuToggleListener.onMenuToggle(true);
+        }
+    }
+
+    /**
+     * Closes the FloatingActionMenu.
+     */
+    public void close() {
+        startCloseAnimator();
+        mOpen = false;
+        if (onMenuToggleListener != null) {
+            onMenuToggleListener.onMenuToggle(true);
+        }
+    }
+
+    //-- Animation methods. --//
+
+    /**
+     * Initiates all of the closing animations.
+     */
+    protected void startCloseAnimator() {
+        mCloseAnimatorSet.start();
+        for (ItemAnimator anim : mMenuItemAnimators) {
+            anim.startCloseAnimator();
+        }
+    }
+
+    /**
+     * Initiating all of the opening animations.
+     */
+    protected void startOpenAnimator() {
+        mOpenAnimatorSet.start();
+        for (ItemAnimator anim : mMenuItemAnimators) {
+            anim.startOpenAnimator();
+        }
+    }
+
+    /**
+     * Adds a new menu item to the FloatingActionMenu.
+     * @param item The FloatingActionButton to add to the menu.
+     */
+    public void addMenuItem(FloatingActionButton item) {
+        mMenuItems.add(item);
+        mMenuItemAnimators.add(new ItemAnimator(item));
+
+        TextView button = new TextView(getContext());
+
+        LayoutParams params = new LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT);
+        button.setLayoutParams(params);
+
+        button.setBackgroundResource(R.drawable.rounded_corners);
+
+        button.setTextColor(Color.WHITE);
+        button.setText(item.getContentDescription());
+
+        Integer paddingSize = (int)button.getTextSize() / 3;
+
+        button.setPadding(paddingSize, paddingSize, paddingSize, paddingSize);
+
+        addView(button);
+        mMenuItemLabels.add(button);
+        item.setTag(button);
+        item.setOnClickListener(mOnItemClickListener);
+        button.setOnClickListener(mOnItemClickListener);
+    }
+
+    /**
+     * Sets the default animation for the FAM icon, which is simply rotation.
+     */
     private void createDefaultIconAnimation() {
         Animator.AnimatorListener listener = new Animator.AnimatorListener() {
             @Override
@@ -411,80 +588,106 @@ public class FloatingActionMenu extends ViewGroup {
         mCloseAnimatorSet.addListener(listener);
     }
 
+    //-- Accessors --//
+
+    /**
+     * Determines whether or not the menu is open.
+     * @return True if the menu is open, false otherwise.
+     */
     public boolean isOpened() {
         return mOpen;
     }
 
-    @Override
-    public Parcelable onSaveInstanceState() {
-        d("onSaveInstanceState");
-        Bundle bundle = new Bundle();
-        bundle.putParcelable("instanceState", super.onSaveInstanceState());
-        bundle.putBoolean("mOpen", mOpen);
-        // ... save everything
-        return bundle;
+    /**
+     * Retrieves the OnMenuToggleListener that is applied to the FloatingActionMenu.
+     */
+    public OnMenuToggleListener getOnMenuToggleListener() {
+        return onMenuToggleListener;
     }
 
-    @Override
-    public void onRestoreInstanceState(Parcelable state) {
-        d("onRestoreInstanceState");
-        if (state instanceof Bundle) {
-            Bundle bundle = (Bundle) state;
-            mOpen = bundle.getBoolean("mOpen");
-            // ... load everything
-            state = bundle.getParcelable("instanceState");
-        }
-        super.onRestoreInstanceState(state);
+    /**
+     * Retrieves the OnMenuItemClickListener that is applied to the FloatingActionMenu.
+     */
+    public OnMenuItemClickListener getOnMenuItemClickListener() {
+        return onMenuItemClickListener;
     }
 
-    @Override
-    protected void onDetachedFromWindow() {
-        d("onDetachedFromWindow");
-        //getBackground().setAlpha(bgAlpha);//reset default alpha
-        super.onDetachedFromWindow();
+    //-- Mutators --//
+
+    /**
+     * Assigns an OnMenuToggleListener to the FloatingActionMenu.
+     */
+    public void setOnMenuToggleListener(OnMenuToggleListener onMenuToggleListener) {
+        this.onMenuToggleListener = onMenuToggleListener;
     }
 
-    @Override
-    public void setBackground(Drawable background) {
-        if (background instanceof ColorDrawable) {
-            // after activity finish and relaucher , background drawable state still remain?
-            int bgAlpha = Color.alpha(((ColorDrawable) background).getColor());
-            d("bg:" + Integer.toHexString(bgAlpha));
-            super.setBackground(background);
-        } else {
-            throw new IllegalArgumentException("floating only support color background");
-        }
+    /**
+     * Assigns an OnMenuItemClickListener to the FloatingActionMenu.
+     */
+    public void setOnMenuItemClickListener(OnMenuItemClickListener onMenuItemClickListener) {
+        this.onMenuItemClickListener = onMenuItemClickListener;
     }
 
-    public OnMenuToggleListener getOnMenuToggleListener() {
-        return onMenuToggleListener;
+    /**
+     * Set as circle(default) or line pattern
+     */
+    public void setIsCircle(boolean isCircle) {
+        this.isCircle = isCircle;
     }
 
-    public void setOnMenuToggleListener(OnMenuToggleListener onMenuToggleListener) {
-        this.onMenuToggleListener = onMenuToggleListener;
+    /**
+     * Set the radius of menu, default 256
+     */
+    public void setmRadius(int mRadius) {
+        this.mRadius = mRadius;
     }
 
-    public OnMenuItemClickListener getOnMenuItemClickListener() {
-        return onMenuItemClickListener;
+    /**
+     * Set radius as multiple of width of floating action button
+     */
+    public void setMultipleOfFB(float multipleOfFB) {
+        this.multipleOfFB = multipleOfFB;
     }
 
-    public void setOnMenuItemClickListener(OnMenuItemClickListener onMenuItemClickListener) {
-        this.onMenuItemClickListener = onMenuItemClickListener;
+    /**
+     * Duration of anim, default 300
+     */
+    public void setDuration(long duration) {
+        this.duration = duration;
+    }
+
+    /**
+     * Only usefully in Line pattern - sets the gap between menu items.
+     */
+    public void setmItemGap(int mItemGap) {
+        this.mItemGap = mItemGap;
     }
 
+    //-- Misc/Helper methods --//
+
     protected void d(String msg) {
         Log.d("FAM", msg == null ? null : msg);
     }
 
+    //-- Interfaces --//
+
+    /**
+     * Interface that handles a change in the open/close state of the FloatingActionMenu.
+     */
     public interface OnMenuToggleListener {
         void onMenuToggle(boolean opened);
     }
 
-
+    /**
+     * Interface that handles the click action of a MenuItem.
+     */
     public interface OnMenuItemClickListener {
         void onMenuItemClick(FloatingActionMenu fam, int index, FloatingActionButton item);
     }
 
+    /**
+     * Animator that controls the open/close animation of menu items.
+     */
     private class ItemAnimator implements Animator.AnimatorListener {
         private View mView;
         private boolean playingOpenAnimator;
@@ -549,44 +752,4 @@ public class FloatingActionMenu extends ViewGroup {
         public void onAnimationRepeat(Animator animation) {
         }
     }
-
-    /**
-     * set as circle(default) or line pattern
-     * @param isCircle
-     */
-    public void setIsCircle(boolean isCircle) {
-        this.isCircle = isCircle;
-    }
-
-    /**
-     * set the radius of menu, default 256
-     * @param mRadius
-     */
-    public void setmRadius(int mRadius) {
-        this.mRadius = mRadius;
-    }
-
-    /**
-     * set radius as multiple of width of floating action button
-     * @param multipleOfFB
-     */
-    public void setMultipleOfFB(float multipleOfFB) {
-        this.multipleOfFB = multipleOfFB;
-    }
-
-    /**
-     * duration of anim, default 300
-     * @param duration
-     */
-    public void setDuration(long duration) {
-        this.duration = duration;
-    }
-
-    /**
-     * Only usefully in Line pattern
-     * @param mItemGap
-     */
-    public void setmItemGap(int mItemGap) {
-        this.mItemGap = mItemGap;
-    }
 }