1page.title=App Widget Design Guidelines 2parent.title=UI Guidelines 3parent.link=index.html 4@jd:body 5 6<div id="qv-wrapper"> 7<div id="qv"> 8 9<h2>Quickview</h2> 10 11<ul> 12 <li>App Widget layouts should be flexible, resizing to fit their parent container</li> 13 <li>As of Android 3.0, app widgets can depict collections of items and provide a representative 14 preview image for the widget gallery</li> 15 <li>As of Android 3.1, app widgets can be resizable horizontally and/or vertically</li> 16 <li>As of Android 4.0, app widgets have margins automatically applied</li> 17</ul> 18 19<h2>In this document</h2> 20 21<ol> 22<li><a href="#anatomy">Standard Widget Anatomy</a></li> 23<li><a href="#design">Designing Widget Layouts and Background Graphics</a></li> 24<li><a href="#templates">Using the App Widget Templates Pack</a></li> 25</ol> 26 27<h2>Downloads</h2> 28 29<ol> 30<li><a href="{@docRoot}shareables/app_widget_templates-v4.0.zip">App Widget Templates Pack, 31 v4.0 »</a></li> 32</ol> 33 34<h2>See also</h2> 35 36<ol> 37<li><a href="{@docRoot}guide/topics/appwidgets/index.html">App Widgets</a></li> 38<li> 39 <a href="http://android-developers.blogspot.com/2009/04/introducing-home-screen-widgets-and.html"> 40 AppWidgets blog post</a></li> 41</ol> 42 43</div> 44</div> 45 46 47<p>App widgets (sometimes just "widgets") are a feature introduced in Android 1.5 and vastly 48improved in Android 3.0 and 3.1. A widget can display an application's most timely or otherwise 49relevant information at a glance, on a user's Home screen. The standard Android system image 50includes several widgets, including a widget for the Analog Clock, Music, and other 51applications.</p> 52 53 54<img src="{@docRoot}images/widget_design/widget_examples.png" 55 alt="Example app widgets in Android 4.0" id="widget_examples"> 56 57<p class="img-caption"><strong>Figure 1.</strong> Example app widgets in Android 4.0.</p> 58 59 60<p>This document describes how to design a widget so that it fits graphically with other widgets and 61with the other elements of the Android Home screen such as launcher icons and shortcuts. It also 62describes some standards for widget artwork and some widget graphics tips and tricks.<p> 63 64<p>For information about developing widgets, see the <a 65href="{@docRoot}guide/topics/appwidgets/index.html">App Widgets</a> section of the <em>Developer's 66Guide</em>.</p> 67 68 69<h2 id="anatomy">Standard Widget Anatomy</h2> 70 71<p>Typical Android app widgets have three main components: A bounding box, a frame, and the widget's 72graphical controls and other elements. App widgets can contain a subset of the View widgets in 73Android; supported controls include text labels, buttons, and images. For a full list of available 74Views, see the <a href="{@docRoot}guide/topics/appwidgets/index.html#CreatingLayout">Creating the 75App Widget Layout</a> section in the <em>Developer's Guide</em>. Well-designed widgets leave some 76margins between the edges of the bounding box and the frame, and padding between the inner edges of 77the frame and the widget's controls.</p> 78 79 80<img src="{@docRoot}images/widget_design/widget_terms.png" 81 alt="Widgets generally have margins and padding between bounding box, frame, and controls" 82 id="widget_terms"> 83 84<p class="img-caption"><strong>Figure 2.</strong> Widgets generally have margins between the 85bounding box and frame, and padding between the frame and widget controls.</p> 86 87 88<p class="note"><strong>Note: </strong> As of Android 4.0, app widgets are automatically given 89margins between the widget frame and the app widget's bounding box to provide better alignment with 90other widgets and icons on the user's home screen. To take advantage of this strongly recommended 91behavior, set your application's <a 92href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">targetSdkVersion</a> to 14 or 93greater.</p> 94 95<p>Widgets designed to fit visually with other widgets on the Home screen take cues from the other 96elements on the Home screen for alignment; they also use standard shading effects. All of these 97details are described in this document.</p> 98 99 100<h3 id="anatomy_determining_size">Determining a size for your widget</h3> 101 102<p>Each widget must define a <code>minWidth</code> and <code>minHeight</code>, indicating the 103minimum amount of space it should consume by default. When users add a widget to their Home screen, 104it will generally occupy more than the minimum width and height you specify. Android Home screens 105offer users a grid of available spaces into which they can place widgets and icons. This grid can 106vary by device; for example, many handsets offer a 4x4 grid, and tablets can offer a larger, 8x7 107grid. <strong>When your widget is added, it will be stretched to occupy the minimum number of cells, 108horizontally and vertically, required to satisfy its <code>minWidth</code> and 109<code>minHeight</code> constraints.</strong> As we discuss in <a href="#design">Designing Widget 110Layouts and Background Graphics</a> below, using nine-patch backgrounds and flexible layouts for app 111widgets will allow your widget to gracefully adapt to the device's Home screen grid and remain 112usable and aesthetically awesome.</p> 113 114<p>While the width and height of a cell—as well as the amount of automatic margins applied to 115widgets—may vary across devices, you can use the table below to roughly estimate your widget's 116minimum dimensions, given the desired number of occupied grid cells:</p> 117 118<table id="cellstable"> 119 <thead> 120 <tr> 121 <th># of Cells<br><small style="font-weight:normal">(Columns or Rows)</small></th> 122 <th>Available Size (dp)<br><small style="font-weight:normal">(<code>minWidth</code> or 123 <code>minHeight</code>)</small></th> 124 </tr> 125 </thead> 126 <tbody> 127 <tr> 128 <td>1</td> 129 <td>40dp</td> 130 </tr> 131 <tr> 132 <td>2</td> 133 <td>110dp</td> 134 </tr> 135 <tr> 136 <td>3</td> 137 <td>180dp</td> 138 </tr> 139 <tr> 140 <td>4</td> 141 <td>250dp</td> 142 </tr> 143 <tr> 144 <td>…</td> 145 <td>…</td> 146 </tr> 147 <tr> 148 <td><em>n</em></td> 149 <td>70 × <em>n</em> − 30</td> 150 </tr> 151 </tbody> 152</table> 153 154<p>It is a good practice to be conservative with <code>minWidth</code> and <code>minHeight</code>, 155specifying the minimum size that renders the widget in a good default state. For an example of how 156to provide a <code>minWidth</code> and <code>minHeight</code>, suppose you have a music player 157widget that shows the currently playing song artist and title (vertically stacked), a 158<strong>Play</strong> button, and a <strong>Next</strong> button:</p> 159 160 161<img src="{@docRoot}images/widget_design/music_example.png" 162 alt="An example music player widget" id="music_example"> 163 164<p class="img-caption"><strong>Figure 3.</strong> An example music player widget.</p> 165 166 167<p>Your minimum height should be the height of your two TextViews for the artist and title, plus 168some text margins. Your minimum width should be the minimum usable widths of the 169<strong>Play</strong> and <strong>Next</strong> buttons, plus the minimum text width (say, the width 170of 10 characters), plus any horizontal text margins.</p> 171 172 173<img src="{@docRoot}images/widget_design/music_example_redline.png" 174alt="Example sizes and margins for minimum width/height calculations" id="music_example_redline"> 175 176<p class="img-caption"><strong>Figure 4.</strong> Example sizes and margins for 177<code>minWidth</code>/<code>minHeight</code> calculations. We chose 144dp as an example good minimum 178width for the text labels.</p> 179 180 181<p>Example calculations are below:</p> 182 183<ul> 184 <li><code>minWidth</code> = 144dp + (2 × 8dp) + (2 × 56dp) = 185 <strong>272dp</strong></li> 186 <li><code>minHeight</code> = 48dp + (2 × 4dp) = <strong>56dp</strong></li> 187</ul> 188 189<p>If there is any inherent content padding in your widget background nine-patch, you should add to 190<code>minWidth</code> and <code>minHeight</code> accordingly.</p> 191 192 193<h3 id="anatomy_resizable_widgets">Resizable widgets</h3> 194 195<p>Widgets can be resized horizontally and/or vertically as of Android 3.1, meaning that 196<code>minWidth</code> and <code>minHeight</code> effectively become the <em>default</em> size for 197the widget. You can specify the minimum widget size using <code>minResizeWidth</code> and 198<code>minResizeHeight</code>; these values should specify the size below which the widget would be 199illegible or otherwise unusable.</p> 200 201<p>This is generally a preferred feature for collection widgets such as those based on {@link 202android.widget.ListView} or {@link android.widget.GridView}.</p> 203 204 205<h3 id="anatomy_adding_margins">Adding margins to your app widget</h3> 206 207<p>As previously mentioned, Android 4.0 will automatically add small, standard margins to each edge 208of widgets on the Home screen, for applications that specify a <code>targetSdkVersion</code> of 14 209or greater. This helps to visually balance the Home screen, and thus <strong>we recommend that you 210do not add any extra margins outside of your app widget's background shape in Android 2114.0</strong>.</p> 212 213<p>It's easy to write a single layout that has custom margins applied for earlier versions of the 214platform, and has no extra margins for Android 4.0 and greater. See <a 215href="{@docRoot}guide/topics/appwidgets/index.html#AddingMargins">Adding Margins to App Widgets</a> 216in the <em>Developer's Guide</em> for information on how to achieve this with layout XML.</p> 217 218 219<h2 id="design">Designing Widget Layouts and Background Graphics</h2> 220 221<p>Most widgets will have a solid background rectangle or rounded rectangle shape. It is a best 222practice to define this shape using nine patches; one for each screen density (see <a 223href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> for details). 224Nine-patches can be created with the <a 225href="{@docRoot}guide/developing/tools/draw9patch.html">draw9patch</a> tool, or simply with a 226graphics editing program such as Adobe® Photoshop. This will allow the widget background shape 227to take up the entire available space. The nine-patch should be edge-to-edge with no transparent 228pixels providing extra margins, save for perhaps a few border pixels for <strong>subtle</strong> 229drop shadows or other subtle effects.</p> 230 231<p class="note"><strong>Note: </strong> Just like with controls in activities, you should ensure 232that interactive controls have distinct visual focused and pressed states using <a 233href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">state list 234drawables</a>.</p> 235 236 237<img src="{@docRoot}images/ninepatch_raw.png" alt="Nine-patch border pixels" id="ninepatch_raw"> 238 239<p class="img-caption"><strong>Figure 5.</strong> Nine-patch border pixels indicating stretchable 240regions and content padding.</p> 241 242 243<p>Some app widgets, such as those using a {@link android.widget.StackView}, have a transparent 244background. For this case, each individual item in the StackView should use a nine-patch background 245that is edge-to-edge with little or no border transparent pixels for margins.</p> 246 247<p>For the contents of the widget, you should use flexible layouts such as {@link 248android.widget.RelativeLayout}, {@link android.widget.LinearLayout}, or {@link 249android.widget.FrameLayout}. Just as your activity layouts must adapt to different physical screen 250sizes, widget layouts must adapt to different Home screen grid cell sizes.</p> 251 252<p>Below is an example layout that a music widget showing text information and two buttons can use. 253It builds upon the previous discussion of adding margins depending on OS version.</p> 254 255<pre> 256<FrameLayout 257 android:layout_width="match_parent" 258 android:layout_height="match_parent" 259 android:layout_margin="@dimen/widget_margin"> 260 261 <LinearLayout 262 android:layout_width="match_parent" 263 android:layout_height="match_parent" 264 android:orientation="horizontal" 265 android:background="@drawable/my_widget_background"> 266 267 <TextView 268 android:id="@+id/song_info" 269 android:layout_width="0dp" 270 android:layout_height="match_parent" 271 android:layout_weight="1" /> 272 273 <Button 274 android:id="@+id/play_button" 275 android:layout_width="@dimen/my_button_width" 276 android:layout_height="match_parent" /> 277 278 <Button 279 android:id="@+id/skip_button" 280 android:layout_width="@dimen/my_button_width" 281 android:layout_height="match_parent" /> 282 </LinearLayout> 283</FrameLayout> 284</pre> 285 286<p>If you now take a look at the example music widget from the previous section, you can begin to 287use flexible layouts attributes like so:</p> 288 289 290<img src="{@docRoot}images/widget_design/music_example_layouts.png" 291 alt="Excerpt flexible layouts and attributes for an example music widget" 292 id="music_example_layouts"> 293 294<p class="img-caption"><strong>Figure 6.</strong> Excerpt flexible layouts and attributes.</p> 295 296 297<p>When a user adds the widget to their home screen, on an example Android 4.0 device where each 298grid cell is 80dp × 100dp in size and 16dp of margins are automatically applied on all sizes, 299the widget will be stretched, like so:</p> 300 301 302<img src="{@docRoot}images/widget_design/music_example_stretched.png" 303 alt="Music widget sitting on an example 80dp x 100dp grid with 16dp of automatic margins 304 added by the system" id="music_example_stretched"> 305 306<p class="img-caption"><strong>Figure 7.</strong> Music widget sitting on an example 80dp x 100dp 307grid with 16dp of automatic margins added by the system.</p> 308 309 310<h2 id="templates">Using the App Widget Templates Pack</h2> 311 312<p>When starting to design a new widget, or updating an existing widget, it's a good idea to first 313look at the widget design templates below. The downloadable package below includes nine-patch 314background graphics, XML, and source Adobe® Photoshop files for multiple screen densities, OS 315version widget styles, and widget colors. The template package also contains graphics useful for 316making your entire widget or parts of your widget (e.g. buttons) interactive.</p> 317 318 319<img src="{@docRoot}images/widget_design/widget_template_excerpts.png" 320 alt="Widget template excerpts" id="widget_template_excerpts"> 321 322<p class="img-caption"><strong>Figure 8.</strong> Excerpts from the App Widget Templates Pack 323(medium-density, dark, Android 4.0/previous styles, default/focused/pressed states).</p> 324 325 326<p>You can obtain the latest App Widget Templates Pack archive using the link below:</p> 327 328<p style="margin-left:2em"><a href="{@docRoot}shareables/app_widget_templates-v4.0.zip"> 329 Download the App Widget Templates Pack for Android 4.0 »</a></p> 330 331