1 page.title=Defining Shadows and Clipping Views 2 3 @jd:body 4 5 <div id="tb-wrapper"> 6 <div id="tb"> 7 <h2>This lesson teaches you to</h2> 8 <ol> 9 <li><a href="#Elevation">Assign Elevation to Your Views</a></li> 10 <li><a href="#Shadows">Customize View Shadows and Outlines</a></li> 11 <li><a href="#Clip">Clip Views</a></li> 12 </ol> 13 <h2>You should also read</h2> 14 <ul> 15 <li><a href="http://www.google.com/design/spec">Material design specification</a></li> 16 <li><a href="{@docRoot}design/material/index.html">Material design on Android</a></li> 17 </ul> 18 </div> 19 </div> 20 21 <p>Material design introduces depth for UI elements. Depth helps users understand the relative 22 importance of each element and focus their attention to the task at hand.</p> 23 24 <p>The elevation of a view, represented by the Z property, determines the size of its shadow: 25 views with higher Z values cast bigger shadows. Views only cast shadows on the Z=0 plane; they 26 don't cast shadows on other views placed below them and above the Z=0 plane.</p> 27 28 <p>Views with higher Z values occlude views with lower Z values. However, the Z value of a view 29 does not affect the view's size.</p> 30 31 <p>Elevation is also useful to create animations where widgets temporarily rise above the 32 view plane when performing some action.</p> 33 34 35 <h2 id="Elevation">Assign Elevation to Your Views</h2> 36 37 <p>The Z value for a view has two components, elevation and translation. The elevation is the 38 static component, and the translation is used for animations:</p> 39 40 <p><code>Z = elevation + translationZ</code></p> 41 42 <img src="{@docRoot}training/material/images/shadows-depth.png" width="680" height="177" alt=""/> 43 <p class="img-caption"><strong>Figure 1</strong> - Shadows for different view elevations.</p> 44 45 <p>To set the elevation of a view in a layout definition, use the <code>android:elevation</code> 46 attribute. To set the elevation of a view in the code of an activity, use the 47 {@link android.view.View#setElevation View.setElevation()} method.</p> 48 49 <p>To set the translation of a view, use the {@link android.view.View#setTranslationZ 50 View.setTranslationZ()} method.</p> 51 52 <p>The new {@link android.view.ViewPropertyAnimator#z ViewPropertyAnimator.z()} and {@link 53 android.view.ViewPropertyAnimator#translationZ ViewPropertyAnimator.translationZ()} methods enable 54 you to easily animate the elevation of views. For more information, see the API reference for 55 {@link android.view.ViewPropertyAnimator} and the <a 56 href="{@docRoot}guide/topics/graphics/prop-animation.html">Property Animation</a> developer 57 guide.</p> 58 59 <p>You can also use a {@link android.animation.StateListAnimator} to 60 specify these animations in a declarative way. This is especially useful for cases where state 61 changes trigger animations, like when a user presses a button. For more information, see 62 <a href="{@docRoot}training/material/animations.html#ViewState">Animate View State Changes</a></p>. 63 64 <p>The Z values are measured in the same units as the X and Y values.</p> 65 66 67 <h2 id="Shadows">Customize View Shadows and Outlines</h2> 68 69 <p>The bounds of a view's background drawable determine the default shape of its shadow. 70 <strong>Outlines</strong> represent the outer shape of a graphics object and define the ripple 71 area for touch feedback.</p> 72 73 <p>Consider this view, defined with a background drawable:</p> 74 75 <pre> 76 <TextView 77 android:id="@+id/myview" 78 ... 79 android:elevation="2dp" 80 android:background="@drawable/myrect" /> 81 </pre> 82 83 <p>The background drawable is defined as a rectangle with rounded corners:</p> 84 85 <pre> 86 <!-- res/drawable/myrect.xml --> 87 <shape xmlns:android="http://schemas.android.com/apk/res/android" 88 android:shape="rectangle"> 89 <solid android:color="#42000000" /> 90 <corners android:radius="5dp" /> 91 </shape> 92 </pre> 93 94 <p>The view casts a shadow with rounded corners, since the background drawable defines the 95 view's outline. Providing a custom outline overrides the default shape of a view's shadow.</p> 96 97 <p>To define a custom outline for a view in your code:<p> 98 99 <ol> 100 <li>Extend the {@link android.view.ViewOutlineProvider} class.</li> 101 <li>Override the {@link android.view.ViewOutlineProvider#getOutline getOutline()} method.</li> 102 <li>Assign the new outline provider to your view with the {@link 103 android.view.View#setOutlineProvider View.setOutlineProvider()} method.</li> 104 </ol> 105 106 <p>You can create oval and rectangular outlines with rounded corners using the methods in the 107 {@link android.graphics.Outline} class. The default outline provider for views obtains the outline 108 from the view's background. To prevent a view from casting a shadow, set its outline provider 109 to <code>null</code>.</p> 110 111 112 <h2 id="Clip">Clip Views</h2> 113 114 <p>Clipping views enables you to easily change the shape of a view. You can clip views for 115 consistency with other design elements or to change the shape of a view in response to user input. 116 You can clip a view to its outline area using the {@link android.view.View#setClipToOutline 117 View.setClipToOutline()} method or the <code>android:clipToOutline</code> attribute. Only 118 rectangle, circle, and round rectangle outlines support clipping, as determined by the 119 {@link android.graphics.Outline#canClip Outline.canClip()} method.</p> 120 121 <p>To clip a view to the shape of a drawable, set the drawable as the background of the view 122 (as shown above) and call the {@link android.view.View#setClipToOutline View.setClipToOutline()} 123 method.</p> 124 125 <p>Clipping views is an expensive operation, so don't animate the shape you use to 126 clip a view. To achieve this effect, use the <a 127 href="{@docRoot}training/material/animations.html#Reveal">Reveal Effect</a> animation.</p> 128
