Adds README.md

Changes the launcher icon for the demo app.

Change-Id: I96a8c32001a4ab2e05090af7f362e9bd33556bd0

README.md

+# FlexboxLayout
+FlexboxLayout is a library project which brings the similar capabilities of
+[CSS Flexible Box Layout Module](https://www.w3.org/TR/css-flexbox-1) to Android.
+
+## Installation
+You have two options to install the library. You can choose either of:
+
+(1) Add the following dependency to your `build.gradle` file
+(At this moment not available from jcenter)
+TODO(thagikura): Upload the library to jCenter
+
+(2) Use the GitHub source and include that as a module dependency by following steps
+* Clone this library, parallel to your own application project:
+```
+git clone https://github.com/google/FlexboxLayout
+```
+
+* In the root of your application's project, edit the `settings.gradle` and add the following lines:
+```
+include ':FlexboxLayout'
+project(':FlexboxLayout').projectDir = new File('../FlexboxLayout/')
+```
+
+* In your application's main module, edit your `build.gradle` to add a new dependency:
+```
+dependencies {
+    ...
+    compile project(':FlexboxLayout')
+ }
+```
+
+## Usage
+FlexboxLayout extends the ViewGroup like LinearLayout and RelativeLayout.
+You can specify the attributes from a layout XML like:
+```xml
+<com.google.android.libraries.flexbox.FlexboxLayout
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:app="http://schemas.android.com/apk/res-auto"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    app:flexWrap="wrap"
+    app:alignItems="stretch"
+    app:alignContent="stretch" >
+
+    <TextView
+        android:id="@+id/textview1"
+        android:layout_width="120dp"
+        android:layout_height="80dp"
+        app:layout_flexBasisPercent="50%"
+        />
+
+    <TextView
+        android:id="@+id/textview2"
+        android:layout_width="80dp"
+        android:layout_height="80dp"
+        app:layout_alignSelf="center"
+        />
+
+    <TextView
+        android:id="@+id/textview3"
+        android:layout_width="160dp"
+        android:layout_height="80dp"
+        app:layout_alignSelf="flex_end"
+        />
+</com.google.android.libraries.flexbox.FlexboxLayout>
+```
+
+Or from code like:
+```java
+FlexboxLayout flexboxLayout = (FlexboxLayout) findViewById(R.id.flexbox_layout);
+flexboxLayout.setFlexDirection(FlexboxLayout.FLEX_DIRECTION_COLUMN);
+
+View view = flexboxLayout.getChildAt(0);
+FlexboxLayout.LayoutParams lp = (FlexboxLayout.LayoutParams) view.getLayoutParams();
+lp.order = -1;
+lp.flexGrow = 2;
+view.setLayoutParams(lp);
+```
+
+## Supported attributes
+You can specify following attributes for the FlexboxLayout.
+* flexDirection
+  * The direction children items are placed inside the Flexbox layout, it determines the
+  direction of the main axis (and the cross axis, perpendicular to the main axis).
+  Possible values are:
+    * row (default)
+    * row_reverse
+    * column
+    * column_reverse
+
+    ![Flex Direction explanation](/assets/flex-direction.gif)
+
+* flexWrap
+  * This attribute controls whether the flex container is single-line or multi-line, and the
+  direction of the cross axis. Poissble values are:
+    * nowrap (default)
+    * wrap
+    * wrap_reverse
+
+    ![Flex Wrap explanation](/assets/flex-wrap.gif)
+
+* justifyContent
+  * This attribute controls the alignment along the main axis. Possible values are:
+    * flex_start (default)
+    * flex_end
+    * center
+    * space_between
+    * space_around
+
+    ![Justify Content explanation](/assets/justify-content.gif)
+
+* alignItems
+  * This attribute controls the alignment along the cross axis. Possible values are:
+    * stretch (default)
+    * flex_start
+    * flex_end
+    * center
+    * baseline
+
+    ![Align Items explanation](/assets/align-items.gif)
+
+* alignContent
+  * This attribute controls the alignment of the flex lines in the flex container. Possible values
+  are:
+    * stretch (default)
+    * flex_start
+    * flex_end
+    * center
+    * space_between
+    * space_around
+
+    ![Align Content explanation](/assets/align-content.gif)
+
+Also you can specify following attributes for the children of a FlexboxLayout
+
+* layout_order
+  * This attribute can change the ordering of the children views are laid out.
+  By default, children are displayed and laid out in the same order as they appear in the
+  layout XML. If not specified, `1` is set as a default value.
+
+* layout_flexGrow
+  * This attribute determines how much this child will grow if positive free space is
+  distributed relative to the rest of other flex items included in the same flex line.
+  If not specified, `0` is set as a default value.
+
+* layout_flexShrink
+  * This attributes determines how much this child will shrink is negative free space is
+  distributed relative to the rest of other flex items included in the same flex line.
+  If not specified, `1` is set as a default value.
+
+* layout_alignSelf
+  * This attributes determines the alignment along the cross axis (perpendicular to the
+  main axis). The alignment in the same direction can be determined by the
+  `alignItems` in the parent, but if this is set to other than
+  `auto`, the cross axis alignment is overridden for this child. Possible values are:
+    * auto (default)
+    * flex_start
+    * flex_end
+    * center
+    * baseline
+    * stretch
+
+* layout_flexBasisPercent
+  * The initial flex item length in a fraction format relative to its parent.
+  The initial main size of this child View is trying to be expanded as the specified
+  fraction against the parent main size.
+  If this value is set, the length specified from `layout_width`
+  (or `layout_height`) is overridden by the calculated value from this attribute.
+  This attribute is only effective when the parent's length is definite (MeasureSpec mode is
+  `MeasureSpec.EXACTLY`). The default value is `-1`, which means not set.
+
+## Known differences from the original CSS specification
+This library tries to achieve the same capabilities of the original
+[Flexible specification](https://www.w3.org/TR/css-flexbox-1) as much as possible,
+but due to some reasons such as the way specifying attributes can't be the same between
+CSS and Android XML, there are some known differences from the original specification.
+
+(1) There is no [flex-flow](https://www.w3.org/TR/css-flexbox-1/#flex-flow-property)
+equivalent attribute
+  * Because `flex-flow` is a shorthand for setting the `flex-direction` and `flex-wrap` properties,
+  specifying two attributes from a single attribute is not practical in Android.
+
+(2) There is no [flex](https://www.w3.org/TR/css-flexbox-1/#flex-property) equivalent attribute
+  * Likewise `flex` is a shorthand for setting the `flex-grow`, `flex-shrink` and `flex-basis`,
+  specifying those attributes from a single attribute is not practical.
+
+(3) `layout_flexBasisPercent` is introduced instead of
+  [flexBasis](https://www.w3.org/TR/css-flexbox-1/#flex-basis-property)
+  * Both `layout_flexBasisPercent` in this library and `flex-basis` property in the CSS are used to
+  determine the initial length of an individual flex item. The `flex-basis` property accepts width
+  values such as `1em`, `10px` and the `content` as string as well as percentage values such as
+  `10%`, `30%` whereas `layout_flexBasisPercent` only accepts percentage values.
+  But specifying initial fixed width values can be done by specifying width (or height) values in
+  layout_width (or layout_height, varies depending on the `flexDirection`). Also the same
+  effect can be done by specifying "wrap_contnet" in layout_width (or layout_height) if
+  developers want to achieve the same effect as 'content'. Thus, `layout_flexBasisProperty` only
+  accepts percentage values, which can't be done through layout_width (or layout_height) for
+  simplicity.
+
+(4) min-width and min-height can't be specified
+  * Which isn't just implemented yet.
+
+## How to make contributions
+Please read and follow the steps in CONTRIBUTING.md
+
+## License
+Please see License

app/proguard-rules.pro

@@ -16,7 +16,7 @@
 
 # Add project specific ProGuard rules here.
 # By default, the flags in this file are appended to flags specified
-# in /usr/local/google/home/thagikura/android-sdk_2635021_linux-x86/tools/proguard/proguard-android.txt
+# in ${sdk.dir}/tools/proguard/proguard-android.txt
 # You can edit the include path and order by changing the proguardFiles
 # directive in build.gradle.
 #

build.gradle

@@ -21,7 +21,7 @@ buildscript {
         jcenter()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:2.1.0-beta3'
+        classpath 'com.android.tools.build:gradle:2.1.0-rc1'
 
         // NOTE: Do not place your application dependencies here; they belong
         // in the individual module build.gradle files

library/proguard-rules.pro

@@ -16,7 +16,7 @@
 
 # Add project specific ProGuard rules here.
 # By default, the flags in this file are appended to flags specified
-# in /usr/local/google/home/thagikura/android-sdk/tools/proguard/proguard-android.txt
+# in ${sdk.dir}/tools/proguard/proguard-android.txt
 # You can edit the include path and order by changing the proguardFiles
 # directive in build.gradle.
 #

library/src/main/java/com/google/android/libraries/flexbox/FlexboxLayout.java

@@ -24,6 +24,8 @@ import android.support.v4.view.ViewCompat;
 import android.util.AttributeSet;
 import android.view.View;
 import android.view.ViewGroup;
+import android.widget.LinearLayout;
+import android.widget.RelativeLayout;
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
@@ -35,6 +37,8 @@ import java.util.TreeSet;
 /**
  * A layout that arranges its children in a way its attributes can be specified like the
  * CSS Flexible Box Layout Module.
+ * This class extends the {@link ViewGroup} like other layout classes such as {@link LinearLayout}
+ * or {@link RelativeLayout}, the attributes can be specified from a layout XML or from code.
  *
  * The supported attributes that you can use are:
  * <ul>
@@ -265,8 +269,14 @@ public class FlexboxLayout extends ViewGroup {
      * Sub method for {@link #onMeasure(int, int)}, when the main axis direction is horizontal
      * (either left to right or right to left).
      *
-     * @param widthMeasureSpec the measure spec for the width
-     * @param heightMeasureSpec the measure spec for the height
+     * @param widthMeasureSpec horizontal space requirements as imposed by the parent
+     * @param heightMeasureSpec vertical space requirements as imposed by the parent
+     *
+     * @see #onMeasure(int, int)
+     * @see #setFlexDirection(int)
+     * @see #setFlexWrap(int)
+     * @see #setAlignItems(int)
+     * @see #setAlignContent(int)
      */
     private void measureHorizontal(int widthMeasureSpec, int heightMeasureSpec) {
         int widthMode = MeasureSpec.getMode(widthMeasureSpec);
@@ -399,8 +409,14 @@ public class FlexboxLayout extends ViewGroup {
      * Sub method for {@link #onMeasure(int, int)} when the main axis direction is vertical
      * (either from top to bottom or bottom to top).
      *
-     * @param widthMeasureSpec the measure spec for the width
-     * @param heightMeasureSpec the measure spec for the height
+     * @param widthMeasureSpec horizontal space requirements as imposed by the parent
+     * @param heightMeasureSpec vertical space requirements as imposed by the parent
+     *
+     * @see #onMeasure(int, int)
+     * @see #setFlexDirection(int)
+     * @see #setFlexWrap(int)
+     * @see #setAlignItems(int)
+     * @see #setAlignContent(int)
      */
     private void measureVertical(int widthMeasureSpec, int heightMeasureSpec) {
         int heightMode = MeasureSpec.getMode(heightMeasureSpec);
@@ -493,8 +509,11 @@ public class FlexboxLayout extends ViewGroup {
      * space is negative) properties are set to non-zero.
      *
      * @param flexDirection the value of the flex direction
-     * @param widthMeasureSpec the width measure spec value
-     * @param heightMeasureSpec the height measure spec value
+     * @param widthMeasureSpec horizontal space requirements as imposed by the parent
+     * @param heightMeasureSpec vertical space requirements as imposed by the parent
+     *
+     * @see #setFlexDirection(int)
+     * @see #getFlexDirection()
      */
     private void determineMainSize(@FlexDirection int flexDirection, int widthMeasureSpec,
             int heightMeasureSpec) {
@@ -550,6 +569,10 @@ public class FlexboxLayout extends ViewGroup {
      *                   be an absolute index in the flex container (FlexboxLayout),
      *                   not the relative index in the flex line.
      * @return the next index, the next flex line's first flex item starts from the returned index
+     *
+     * @see #getFlexDirection()
+     * @see #setFlexDirection(int)
+     * @see LayoutParams#flexGrow
      */
     private int expandFlexItems(FlexLine flexLine, @FlexDirection int flexDirection,
             int maxMainSize, int paddingAlongMainAxis, int startIndex) {
@@ -598,6 +621,10 @@ public class FlexboxLayout extends ViewGroup {
      *                   be an absolute index in the flex container (FlexboxLayout),
      *                   not the relative index in the flex line.
      * @return the next index, the next flex line's first flex item starts from the returned index
+     *
+     * @see #getFlexDirection()
+     * @see #setFlexDirection(int)
+     * @see LayoutParams#flexShrink
      */
     private int shrinkFlexItems(FlexLine flexLine, @FlexDirection int flexDirection,
             int maxMainSize, int paddingAlongMainAxis, int startIndex) {
@@ -664,8 +691,13 @@ public class FlexboxLayout extends ViewGroup {
      * use the sum of cross sizes of all flex lines.
      *
      * @param flexDirection the flex direction attribute
-     * @param widthMeasureSpec the measure spec parameter for width
-     * @param heightMeasureSpec the measure spec parameter for height
+     * @param widthMeasureSpec horizontal space requirements as imposed by the parent
+     * @param heightMeasureSpec vertical space requirements as imposed by the parent
+     *
+     * @see #getFlexDirection()
+     * @see #setFlexDirection(int)
+     * @see #getAlignContent()
+     * @see #setAlignContent(int)
      */
     private void determineCrossSize(int flexDirection, int widthMeasureSpec, int heightMeasureSpec) {
         // The MeasureSpec mode along the cross axis
@@ -773,6 +805,12 @@ public class FlexboxLayout extends ViewGroup {
      *
      * @param flexDirection the flex direction attribute
      * @param alignItems the align items attribute
+     *
+     * @see #getFlexDirection()
+     * @see #setFlexDirection(int)
+     * @see #getAlignItems()
+     * @see #setAlignItems(int)
+     * @see LayoutParams#alignSelf
      */
     private void stretchViews(int flexDirection, int alignItems) {
         if (alignItems == ALIGN_ITEMS_STRETCH) {
@@ -855,9 +893,12 @@ public class FlexboxLayout extends ViewGroup {
      * cross axis.
      *
      * @param flexDirection the value of the flex direction
-     * @param widthMeasureSpec the widthMeasureSpec of this FlexboxLayout
-     * @param heightMeasureSpec the heightMeasureSpec of this FlexboxLayout
+     * @param widthMeasureSpec horizontal space requirements as imposed by the parent
+     * @param heightMeasureSpec vertical space requirements as imposed by the parent
      * @param childState the child state of the View
+     *
+     * @see #getFlexDirection()
+     * @see #setFlexDirection(int)
      */
     private void setMeasuredDimensionForFlex(@FlexDirection int flexDirection, int widthMeasureSpec,
             int heightMeasureSpec, int childState) {
@@ -950,6 +991,9 @@ public class FlexboxLayout extends ViewGroup {
      * @param currentLength the accumulated current length
      * @param childLength the length of a child view which is to be collected to the flex line
      * @return {@code true} if a wrap is required, {@code false} otherwise
+     *
+     * @see #getFlexWrap()
+     * @see #setFlexWrap(int)
      */
     private boolean isWrapRequired(int flexWrap, int mode, int maxSize,
             int currentLength, int childLength) {
@@ -1027,6 +1071,14 @@ public class FlexboxLayout extends ViewGroup {
      * @param top the top position of this View
      * @param right the right position of this View
      * @param bottom the bottom position of this View
+     *
+     * @see #getFlexWrap()
+     * @see #setFlexWrap(int)
+     * @see #getJustifyContent()
+     * @see #setJustifyContent(int)
+     * @see #getAlignItems()
+     * @see #setAlignItems(int)
+     * @see LayoutParams#alignSelf
      */
     private void layoutHorizontal(boolean isRtl, int left, int top, int right, int bottom) {
         int paddingLeft = getPaddingLeft();
@@ -1136,6 +1188,10 @@ public class FlexboxLayout extends ViewGroup {
      * @param bottom the bottom position of the flex line where the View belongs to. The actual
      *               View's bottom position is shifted depending on the flexWrap and alignItems
      *               attributes
+     *
+     * @see #getAlignItems()
+     * @see #setAlignItems(int)
+     * @see LayoutParams#alignSelf
      */
     private void layoutSingleChildHorizontal(View view, FlexLine flexLine, @FlexWrap int flexWrap,
             int alignItems, int left, int top, int right, int bottom) {
@@ -1207,6 +1263,14 @@ public class FlexboxLayout extends ViewGroup {
      * @param top the top position of this View
      * @param right the right position of this View
      * @param bottom the bottom position of this View
+     *
+     * @see #getFlexWrap()
+     * @see #setFlexWrap(int)
+     * @see #getJustifyContent()
+     * @see #setJustifyContent(int)
+     * @see #getAlignItems()
+     * @see #setAlignItems(int)
+     * @see LayoutParams#alignSelf
      */
     private void layoutVertical(boolean isRtl, boolean fromBottomToTop, int left, int top,
             int right, int bottom) {
@@ -1316,6 +1380,10 @@ public class FlexboxLayout extends ViewGroup {
      *              right position is shifted depending on the isRtl and alignItems attributes
      * @param bottom the bottom position of the View, which the View's margin is already taken into
      *               account
+     *
+     * @see #getAlignItems()
+     * @see #setAlignItems(int)
+     * @see LayoutParams#alignSelf
      */
     private void layoutSingleChildVertical(View view, FlexLine flexLine, boolean isRtl,
             int alignItems, int left, int top, int right, int bottom) {
@@ -1496,7 +1564,8 @@ public class FlexboxLayout extends ViewGroup {
          * If this value is set, the length specified from layout_width
          * (or layout_height) is overridden by the calculated value from this attribute.
          * This attribute is only effective when the parent's MeasureSpec mode is
-         * MeasureSpec.EXACTLY.
+         * MeasureSpec.EXACTLY. The default value is {@link #FLEX_BASIS_PERCENT_DEFAULT}, which
+         * means not set.
          */
         public float flexBasisPercent = FLEX_BASIS_PERCENT_DEFAULT;