Merge "docs: Material L Preview engineering review fixes" into klp-modular-dev

  <li><a href="#reveal">Reveal Effect</a></li>

  <li><a href="#transitions">Activity Transitions</a></li>

  <li><a href="#curvedmotion">Curved Motion</a></li>

  <li><a href="#viewstate">View State Changes</a></li>

  <li><a href="#viewstate">Animating View State Changes</a></li>

  <li><a href="#drawabletint">Drawable Tinting</a></li>

  <li><a href="#colorextract">Extracting Colors from an Image</a></li>

</ol>

</div>

</div>

<h2 id="touch">Touch Feedback</h2>

<p>In the Android L Developer Preview the default touch feedback animations for buttons use the new

<p>The default touch feedback animations for buttons use the new

<code>RippleDrawable</code> class, which transitions between different states with a ripple

effect.</p>

<p>To use this functionality in your custom views, create a <code>RippleDrawable</code> and set

it as the background of your view. You can define a <code>RippleDrawable</code> as an XML resource

using the <code>ripple</code> element.</p>

<p>In most cases, this functionality should be applied in your view XML by specifying the

background as <code>?android:attr/selectableItemBackground</code> for a bounded ripple or

<code>?android:attr/selectableItemBackgroundBorderless</code> for a ripple that extends beyond

the view bounds. You can also create a <code>RippleDrawable</code> and set

it as the background of your view. Alternatively, you can define a <code>RippleDrawable</code>

as an XML resource using the <code>ripple</code> element. The

Android L Developer Preview animates the selection color with a ripple effect.</p>

<p>You can assign a color to <code>RippleDrawable</code> objects. To change the default touch

feedback color, use the theme's <code>android:colorControlHighlight</code> attribute.</p>

<h2 id="reveal">Reveal Effect</h2>

<p>The <code>View.createRevealAnimator</code> method enables you to animate a clipping circle

to reveal or hide a view.</p>

<p>The <code>ViewAnimationUtils.createCircularReveal</code> method enables you to animate a

clipping circle to reveal or hide a view.</p>

<p>To reveal a previously invisible view using this effect:</p>

// create and start the animator for this view

// (the start radius is zero)

ValueAnimator anim = myView.createRevealAnimator(cx, cy, 0, finalRadius);

ValueAnimator anim =

    ViewAnimationUtils.createCircularReveal(myView, cx, cy, 0, finalRadius);

anim.start();

</pre>

int initialRadius = myView.getWidth();

// create the animation (the final radius is zero)

ValueAnimator anim = myView.createRevealAnimator(cx, cy, initialRadius, 0);

ValueAnimator anim =

    ViewAnimationUtils.createCircularReveal(myView, cx, cy, initialRadius, 0);

// make the view invisible when the animation is done

anim.addListener(new AnimatorListenerAdapter() {

<h2 id="transitions">Activity Transitions</h2>

<p>The Android L Developer Preview enables your app to customize the default animations for

activity transitions. You can specify custom animations for enter and exit transitions and for

<p>You can specify custom animations for enter and exit transitions and for

transitions of shared elements between activities.</p>

<ul>

<li>An <strong>enter</strong> transition determines how views in an activity enter the scene.

  For example, in the <em>explode</em> enter transition the views enter the scene from outside

For example, in the <em>explode</em> enter transition, the views enter the scene from the outside

and fly in towards the center of the screen.</li>

<li>An <strong>exit</strong> transition determines how views in an activity exit the scene. For

  example, in the <em>explode</em> exit transition the views exit the scene away from the

  example, in the <em>explode</em> exit transition, the views exit the scene away from the

center.</li>

<li>A <strong>shared elements</strong> transition determines how views that are shared between

translates and scales the image smoothly between these activities.</li>

</ul>

<p>The Android L Developer Preview supports these enter and exit transitions:</p>

<ul>

<li><em>explode</em> - Moves views in or out from the center of the scene.</li>

<li><em>slide</em> - Moves views in or out from one of the edges of the scene.</li>

<li><em>fade</em> - Mades views in or out of the scene.</li>

</ul>

<p>Any transition that extends the <code>android.transition.Visibility</code> class is supported

as an enter or exit transition. For more information, see the API reference for the

<code>android.transition.Transition</code> class.</p>

<p>The Android L Developer Preview also supports these shared elements transitions:</p>

<ul>

<li><em>changeBounds</em> - Animates the changes in layout bounds of target views.</li>

<li><em>changeClipBounds</em> - Animates the changes in clip bounds of target views.</li>

<li><em>changeTransform</em> - Animates the changes in scale and rotation of target views.</li>

<li><em>moveImage</em> - Animates changes in size and scale type for an image view.</li>

</ul>

<p>When you enable activity transitions in your app, the default cross-fading transition is

activated between the entering and exiting activities.</p>

<img src="/preview/material/images/SceneTransition.png" alt=""

     id="figure1" style="width:600px;margin-top:20px"/>

<p class="img-caption">

<h3>Specify custom transitions</h3>

<p>First, enable window content transitions with the <code>android:windowContentTransitions</code>

attribute when you define a style that inherits from the material theme:</p>

attribute when you define a style that inherits from the material theme. You can also specify

enter, exit, and shared element transitions in your style definition:</p>

<pre>

<style name="BaseAppTheme" parent="android:Theme.Material">

</style>

</pre>

<p>You can also specify enter, exit, and shared element transitions in your style definition.

The <code>move_image</code> transition in this example is defined as follows:</p>

<p>The <code>move_image</code> transition in this example is defined as follows:</p>

<pre>

<!-- res/transition/move_image.xml -->

<!-- (see also Shared Transitions below) -->

<transitionSet xmlns:android="http://schemas.android.com/apk/res/android">

  <moveImage>

    <targets>

      <!-- shared view in the first activity -->

      <target android:targetId="@id/image_small" />

      <!-- shared view in the second activity -->

      <target android:targetId="@id/image_big" />

    </targets>

  </moveImage>

  <moveImage/>

</transitionSet>

</pre>

<code>Window.requestFeature</code> method:</p>

<pre>

// inside your activity

// inside your activity (if you did not enable transitions in your theme)

getWindow().requestFeature(Window.FEATURE_CONTENT_TRANSITIONS);

// set an exit transition

  <li><code>Window.setSharedElementExitTransition</code></li>

</ul>

<p>The <code>setExitTransition</code> and <code>setSharedElementExitTransition</code> methods

define the exit transition for the calling activity. The <code>setEnterTransition</code> and

<code>setSharedElementEnterTransition</code> methods define the enter transition for the called

activity.</p>

<p>To get the full effect of a transition, you must enable window content transitions on both the

calling and called activities. Otherwise, the calling activity will start the exit transition,

but then you'll see a window transition (like scale or fade).</p>

<p>To start an enter transition as soon as possible, use the

<code>Window.setAllowEnterTransitionOverlap</code> method on the called activity. This lets you

have more dramatic enter transitions. The same applies for the calling activity and exit

transitions with the <code>Window.setAllowExitTransitionOverlap</code> method.</p>

<h3>Start an activity using transitions</h3>

<p>If you enable transitions and set an exit transition for an activity, the transition is activated

<ol>

<li>Enable window content transitions in your style.</li>

<li>Specify a shared elements transition in your style.</li>

<li>Define your transition as an XML resource specifying the IDs of the target views.</li>

<li>Define your transition as an XML resource.</li>

<li>Assign a common name to the shared elements in both layouts with the

    <code>android:viewName</code> attribute.</li>

<li>Use the <code>ActivityOptions.makeSceneTransitionAnimation</code> method.</li>

final View imgContainerView = findViewById(R.id.img_container);

// get the common element for the transition in this activity

final View androidRobotView = findViewById(R.id.android_robot_img);

final View androidRobotView = findViewById(R.id.image_small);

// define a click listener

imgContainerView.setOnClickListener(new View.OnClickListener() {

<p>For shared dynamic views that you generate in your code, use the <code>View.setViewName</code>

method to specify a common element name in both activities.</p>

<p>To reverse the scene transition animation when you finish the second activity, call the

<code>Activity.finishAfterTransition</code> method instead of <code>Activity.finish</code>.</p>

<h3>Multiple shared elements</h3>

<p>To make a scene transition animation between two activities that have more than one shared

<pre>

ActivityOptions options = ActivityOptions.makeSceneTransitionAnimation(this,

    new Pair[] {

        Pair.create(view1, "agreedName1"),

        Pair.create(view2, "agreedName2"),

        ...

    }

);

        Pair.create(view2, "agreedName2"));

</pre>

</ul>

<p>You can pass a <code>PathInterpolator</code> object to the

<code>Animation.setInterpolation</code> method.</p>

<code>Animator.setInterpolation</code> method.</p>

<p>The <code>ObjectAnimator</code> class has new constructors that enable you to animate

coordinates along a path using two or more properties at once. For example, the following animator

</pre>

<h2 id="viewstate">View State Changes</h2>

<h2 id="viewstate">Animating View State Changes</h2>

<p>The new <code>StateListAnimator</code> class lets you define animators that run when the state

of a view changes. The following example shows how to define an <code>StateListAnimator</code> as

an XML resource:</p>

<pre>

<!-- animate the elevation property of a view when pressed -->

<!-- animate the translationZ property of a view when pressed -->

<selector xmlns:android="http://schemas.android.com/apk/res/android">

  <item android:state_pressed="true">

    <set>

      <objectAnimator android:propertyName="elevation"

      <objectAnimator android:propertyName="translationZ"

        android:duration="100"

        android:valueTo="60"

        android:valueTo="2"

        android:valueType="floatType"/>

        <!-- you could have other objectAnimator elements

             here for "x" and "y", or other properties -->

    android:state_pressed="false"

    android:state_focused="true">

    <set>

      <objectAnimator android:propertyName="elevation"

      <objectAnimator android:propertyName="translationZ"

        android:duration="100"

        android:valueTo="10"

        android:valueTo="2"

        android:valueType="floatType"/>

    </set>

  </item>

</selector>

</pre>

<p class="note"><strong>Note:</strong> There is a known issue in the L Developer Preview release

that requires valueFrom values to be provided in StateListAnimator animations to get the correct

behavior.</p>

<p>The new <code>AnimatedStateListDrawable</code> class lets you create drawables that show

animations between state changes of the associated view. Some of the system widgets in the

Android L Developer Preview use these animations by default. The following example shows how

    <!-- provide a different drawable for each state-->

    <item android:id="@+id/pressed" android:drawable="@drawable/drawableP"

        android:state-pressed="true"/>

        android:state_pressed="true"/>

    <item android:id="@+id/focused" android:drawable="@drawable/drawableF"

        android:state-focused="true"/>

        android:state_focused="true"/>

    <item android:id="@id/default"

        android:drawable="@drawable/drawableD"/>

<h2 id="drawabletint">Drawable Tinting</h2>

<p>The Android L Developer Preview enables you to define bitmaps as an alpha mask and to tint

them using a color resource or a theme attribute that resolves to a color resource. You can

create these assets only once and color them automatically to match your theme.</p>

<p>The Android L Developer Preview enables you to define bitmaps or nine-patches as alpha masks and

to tint them using a color resource or a theme attribute that resolves to a color resource (for

example, <code>?android:attr/colorPrimary</code>). You can create these assets only once and color them

automatically to match your theme.</p>

<p>To apply a tint to a bitmap in your code, use the <code>setTint</code> method in these

classes:</p>

<p>To apply a tint to a bitmap, use the <code>setTint</code> method or the <code>android:tint</code>

attribute for <code>BitmapDrawable</code> and <code>NinePatchDrawable</code>.</p>

<p>The <code>setTint</code> method also lets you set the Porter-Duff mode used to blend the

tint color for <code>NinePatchDrawable</code> and <code>BitmapDrawable</code> objects in your code.

To set the tint mode in your layouts, use the <code>android:tintMode</code> attribute.</p>

<h2 id="colorextract">Extracting Prominent Colors from an Image</h2>

<p>The Android L Developer Preview Support Library includes the <code>Palette</code> class,

which lets you extract prominent colors from an image. This class extracts the following

prominent colors:</p>

<ul>

<li><code>PaintDrawable</code></li>

<li><code>NinePatchDrawable</code></li>

<li><code>RippleDrawable</code></li>

<li>Vibrant</li>

<li>Vibrant dark</li>

<li>Vibrant light</li>

<li>Muted</li>

<li>Muted dark</li>

<li>Muted light</li>

</ul>

<p>In your layouts, use the <code>android:tint</code> attribute instead.</p>

<p>To extract these colors, pass a <code>Bitmap</code> object to the

<code>Palette.generate</code> static method in the background thread where you load your images.

If you can't use that thread, call the <code>Palette.generateAsync</code> method instead and

provide a listener.</p>

<p>To retrieve the prominent colors from the image, use the getter methods in the

<code>Palette</code> class, such as <code>Palette.getVibrantColor</code>.</p>

<p>The <code>setTint</code> method also lets you set the tint blending mode for

<code>NinePatchDrawable</code> and <code>RippleDrawable</code> objects in your code. To set the

tint mode in your layouts, use the <code>android:tintMode</code> attribute.</p>

<p>For more information, see the API reference for the

<code>android.support.v7.graphics.Palette</code> class.</p>

 No newline at end of file

</div>

</div>

<p>The new material design features (like the material theme and custom animations) are only

<p>The new material design features (like the material theme and activity transitions) are only

available in the Android L Developer Preview. However, you can design your apps to make use of

these features when running on devices with the Android L Developer Preview and still be

compatible with previous releases of Android.</p>

and your alternative layout files for earlier versions of Android inside <code>res/layout/</code>.

Alternative layouts have the same file name.</p>

<p>To avoid duplication of code, define your styles inside <code>res/values/</code> and modify the

styles in <code>res/values-v21/</code> for the new APIs.</p>

<h2 id="widgets">UI Widgets</h2>

<p>The <code>RecyclerView</code> and <code>CardView</code> widgets are included in the Android L

Developer Preview Support Library, so they are available in earlier versions of Android.</p>

Developer Preview Support Library, so they are available in earlier versions of Android with

these limitations:</p>

<ul>

<li><code>CardView</code> falls back to a programmatic shadow implementation using additional padding.</li>

<li><code>CardView</code> does not clip its children views that intersect with rounded corners.</li>

</ul>

<p>These limitations do not apply to the Android L Developer Preview.</p>

<h2 id="animation">Animation APIs</h2>

<p>The new APIs for custom animations are only available in the Android L Developer Preview. To

preserve compatibility with earlier verisons of Android, check the system version at runtime before

you invoke these APIs.</p>

 No newline at end of file

<p>The following new APIs are only available in the Android L Developer Preview:</p>

<ul>

<li>Activity transitions</li>

<li>Touch feedback</li>

<li>Reveal animations</li>

<li>Path-based animations</li>

</ul>

<p>To preserve compatibility with earlier verisons of Android, check the system version at

runtime before you invoke these APIs.</p>

 No newline at end of file

<ol>

  <li><a href="#applytheme">Apply the Material Theme</a></li>

  <li><a href="#layouts">Design Your Layouts</a></li>

  <li><a href="#depth">Specify Depth in Your Views</a></li>

  <li><a href="#depth">Specify Elevation in Your Views</a></li>

  <li><a href="#widgets">Use the New UI Widgets</a></li>

  <li><a href="#apis">Use the New APIs</a></li>

  <li><a href="#animations">Customize Your Animations</a></li>

</ol>

</div>

</div>

<ol>

  <li style="margin-bottom:10px">

    Take a look at the <a href="">material design specification</a>.</li>

    Take a look at the <a href="http://www.google.com/design/spec">material design

    specification</a>.</li>

  <li style="margin-bottom:10px">

    Apply the material <strong>theme</strong> to your app.</li>

  <li style="margin-bottom:10px">

  <li style="margin-bottom:10px">

    Create your <strong>layouts</strong> following material design guidelines.</li>

  <li style="margin-bottom:10px">

    Specify the <strong>depth</strong> for views to cast appropriate shadows.</li>

    Specify the <strong>elevation</strong> of your views to cast appropriate shadows.</li>

  <li style="margin-bottom:10px">

    Use the new <strong>widgets</strong> for complex views, such as lists and cards.</li>

  <li style="margin-bottom:10px">

    Use the new <strong>APIs</strong> to customize the animations in your app.</li>

    Use the new APIs to customize the <strong>animations</strong> in your app.</li>

</ol>

<h3>Update Your App for the Android L Developer Preview</h3>

<h3>Create New Apps for the Android L Developer Preview</h3>

<p>If you are creating a new app for the Android L Developer Preview, the material design

guidelines provide you with a solid design framework for your app. Follow these guidelines and

<p>If you are creating a new app for the Android L Developer Preview, the <a

href="http://www.google.com/design/spec">material design guidelines</a> provide you with a

cohesive design framework for your app. Follow these guidelines and

use the new functionality in the Android framework to design and develop your app.</p>

<h2 id="applytheme">Apply the Material Theme</h2>

<p>To apply the material theme in your app, specify a style that inherits from

<code>android:theme.Material</code>:</p>

<code>android:Theme.Material</code>:</p>

<pre>

<!-- res/values/styles.xml -->

<h2 id="layouts">Design Your Layouts</h2>

<p>In addition to applying and customizing the material theme, your layouts should conform to

the material design guidelines. When you design your layouts, pay special attention to the

following:</p>

the <a href="http://www.google.com/design/spec">material design guidelines</a>. When you design

your layouts, pay special attention to the following:</p>

<ul>

<li>Baseline grids</li>

<li>Layout structure</li>

</ul>

<p>You still define layouts inside XML files using the standard tools from the Android framework.

For details on the material design guidelines, see the <a href="">material design

specification</a>.</p>

<h2 id="depth">Specify Elevation in Your Views</h2>

<h2 id="depth">Specify Depth in Your Views</h2>

<p>In the Android L Developer Preview, views can cast shadows. The elevation value of a view

determines the size of its shadow. To set the elevation of a view, use the

<p>Views can cast shadows, and the elevation value of a view

determines the size of its shadow and its drawing order. To set the elevation of a view, use the

<code>android:elevation</code> attribute in your layouts:</p>

<pre>

<Button

    android:id="@+id/my_button"

<TextView

    android:id="@+id/my_textview"

    android:layout_width="wrap_content"

    android:layout_height="wrap_content"

    android:text="@string/next"

    <strong>android:elevation</strong>="10dp" />

    android:background="@color/white"

    <strong>android:elevation</strong>="5dp" />

</pre>

<p>The new <code>translationZ</code> property lets you create animations that reflect temporary

changes in the elevation of a view. For example, this is useful to respond to touch gestures.</p>

<p>For more details, see <a href="{@docRoot}preview/material/views-shadows.html">Views and

Shadows</a>.</p>

<h2 id="widgets">Use the New UI Widgets</h2>

<p>The Android L Developer Preview includes two new UI widgets for complex views,

<code>RecyclerView</code> and <code>CardView</code>. <code>RecyclerView</code> is a more advanced

version of <code>ListView</code> that provides performance improvements and is easier to use.

<code>CardView</code> lets you show pieces of information inside cards with a consistent look

across apps. To include a <code>CardView</code> in your layout:</p>

<p><code>RecyclerView</code> is a more advanced version of <code>ListView</code> that provides

performance improvements and is easier to use. <code>CardView</code> lets you show pieces of

information inside cards with a consistent look across apps. To include a <code>CardView</code>

in your layout:</p>

<pre>

<android.support.v7.widget.CardView

<p>For more information, see <a href="{@docRoot}preview/material/ui-widgets.html">UI Widgets</a>.</p>

<h2 id="apis">Use the APIs to Customize Your Animations</h2>

<h2 id="animations">Customize Your Animations</h2>

<p>The Android L Developer Preview includes new APIs to create custom animations in your app.

For example, you can enable activity transitions and define an exit transition inside an