| page.title=App Widget Design Guidelines |
| parent.title=UI Guidelines |
| parent.link=index.html |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| |
| <h2>Quickview</h2> |
| |
| <ul> |
| <li>App Widget layouts should be flexible, resizing to fit their parent container</li> |
| <li>As of Android 3.0, app widgets can depict collections of items and provide a representative |
| preview image for the widget gallery</li> |
| <li>As of Android 3.1, app widgets can be resizable horizontally and/or vertically</li> |
| <li>As of Android 4.0, app widgets have margins automatically applied</li> |
| </ul> |
| |
| <h2>In this document</h2> |
| |
| <ol> |
| <li><a href="#anatomy">Standard Widget Anatomy</a></li> |
| <li><a href="#design">Designing Widget Layouts and Background Graphics</a></li> |
| <li><a href="#templates">Using the App Widget Templates Pack</a></li> |
| </ol> |
| |
| <h2>Downloads</h2> |
| |
| <ol> |
| <li><a href="{@docRoot}shareables/app_widget_templates-v4.0.zip">App Widget Templates Pack, |
| v4.0 »</a></li> |
| </ol> |
| |
| <h2>See also</h2> |
| |
| <ol> |
| <li><a href="{@docRoot}guide/topics/appwidgets/index.html">App Widgets</a></li> |
| <li> |
| <a href="http://android-developers.blogspot.com/2009/04/introducing-home-screen-widgets-and.html"> |
| AppWidgets blog post</a></li> |
| </ol> |
| |
| </div> |
| </div> |
| |
| |
| <p>App widgets (sometimes just "widgets") are a feature introduced in Android 1.5 and vastly |
| improved in Android 3.0 and 3.1. A widget can display an application's most timely or otherwise |
| relevant information at a glance, on a user's Home screen. The standard Android system image |
| includes several widgets, including a widget for the Analog Clock, Music, and other |
| applications.</p> |
| |
| |
| <img src="{@docRoot}images/widget_design/widget_examples.png" |
| alt="Example app widgets in Android 4.0" id="widget_examples"> |
| |
| <p class="img-caption"><strong>Figure 1.</strong> Example app widgets in Android 4.0.</p> |
| |
| |
| <p>This document describes how to design a widget so that it fits graphically with other widgets and |
| with the other elements of the Android Home screen such as launcher icons and shortcuts. It also |
| describes some standards for widget artwork and some widget graphics tips and tricks.<p> |
| |
| <p>For information about developing widgets, see the <a |
| href="{@docRoot}guide/topics/appwidgets/index.html">App Widgets</a> section of the <em>Developer's |
| Guide</em>.</p> |
| |
| |
| <h2 id="anatomy">Standard Widget Anatomy</h2> |
| |
| <p>Typical Android app widgets have three main components: A bounding box, a frame, and the widget's |
| graphical controls and other elements. App widgets can contain a subset of the View widgets in |
| Android; supported controls include text labels, buttons, and images. For a full list of available |
| Views, see the <a href="{@docRoot}guide/topics/appwidgets/index.html#CreatingLayout">Creating the |
| App Widget Layout</a> section in the <em>Developer's Guide</em>. Well-designed widgets leave some |
| margins between the edges of the bounding box and the frame, and padding between the inner edges of |
| the frame and the widget's controls.</p> |
| |
| |
| <img src="{@docRoot}images/widget_design/widget_terms.png" |
| alt="Widgets generally have margins and padding between bounding box, frame, and controls" |
| id="widget_terms"> |
| |
| <p class="img-caption"><strong>Figure 2.</strong> Widgets generally have margins between the |
| bounding box and frame, and padding between the frame and widget controls.</p> |
| |
| |
| <p class="note"><strong>Note: </strong> As of Android 4.0, app widgets are automatically given |
| margins between the widget frame and the app widget's bounding box to provide better alignment with |
| other widgets and icons on the user's home screen. To take advantage of this strongly recommended |
| behavior, set your application's <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">targetSdkVersion</a> to 14 or |
| greater.</p> |
| |
| <p>Widgets designed to fit visually with other widgets on the Home screen take cues from the other |
| elements on the Home screen for alignment; they also use standard shading effects. All of these |
| details are described in this document.</p> |
| |
| |
| <h3 id="anatomy_determining_size">Determining a size for your widget</h3> |
| |
| <p>Each widget must define a <code>minWidth</code> and <code>minHeight</code>, indicating the |
| minimum amount of space it should consume by default. When users add a widget to their Home screen, |
| it will generally occupy more than the minimum width and height you specify. Android Home screens |
| offer users a grid of available spaces into which they can place widgets and icons. This grid can |
| vary by device; for example, many handsets offer a 4x4 grid, and tablets can offer a larger, 8x7 |
| grid. <strong>When your widget is added, it will be stretched to occupy the minimum number of cells, |
| horizontally and vertically, required to satisfy its <code>minWidth</code> and |
| <code>minHeight</code> constraints.</strong> As we discuss in <a href="#design">Designing Widget |
| Layouts and Background Graphics</a> below, using nine-patch backgrounds and flexible layouts for app |
| widgets will allow your widget to gracefully adapt to the device's Home screen grid and remain |
| usable and aesthetically awesome.</p> |
| |
| <p>While the width and height of a cell—as well as the amount of automatic margins applied to |
| widgets—may vary across devices, you can use the table below to roughly estimate your widget's |
| minimum dimensions, given the desired number of occupied grid cells:</p> |
| |
| <table id="cellstable"> |
| <thead> |
| <tr> |
| <th># of Cells<br><small style="font-weight:normal">(Columns or Rows)</small></th> |
| <th>Available Size (dp)<br><small style="font-weight:normal">(<code>minWidth</code> or |
| <code>minHeight</code>)</small></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>1</td> |
| <td>40dp</td> |
| </tr> |
| <tr> |
| <td>2</td> |
| <td>110dp</td> |
| </tr> |
| <tr> |
| <td>3</td> |
| <td>180dp</td> |
| </tr> |
| <tr> |
| <td>4</td> |
| <td>250dp</td> |
| </tr> |
| <tr> |
| <td>…</td> |
| <td>…</td> |
| </tr> |
| <tr> |
| <td><em>n</em></td> |
| <td>70 × <em>n</em> − 30</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <p>It is a good practice to be conservative with <code>minWidth</code> and <code>minHeight</code>, |
| specifying the minimum size that renders the widget in a good default state. For an example of how |
| to provide a <code>minWidth</code> and <code>minHeight</code>, suppose you have a music player |
| widget that shows the currently playing song artist and title (vertically stacked), a |
| <strong>Play</strong> button, and a <strong>Next</strong> button:</p> |
| |
| |
| <img src="{@docRoot}images/widget_design/music_example.png" |
| alt="An example music player widget" id="music_example"> |
| |
| <p class="img-caption"><strong>Figure 3.</strong> An example music player widget.</p> |
| |
| |
| <p>Your minimum height should be the height of your two TextViews for the artist and title, plus |
| some text margins. Your minimum width should be the minimum usable widths of the |
| <strong>Play</strong> and <strong>Next</strong> buttons, plus the minimum text width (say, the width |
| of 10 characters), plus any horizontal text margins.</p> |
| |
| |
| <img src="{@docRoot}images/widget_design/music_example_redline.png" |
| alt="Example sizes and margins for minimum width/height calculations" id="music_example_redline"> |
| |
| <p class="img-caption"><strong>Figure 4.</strong> Example sizes and margins for |
| <code>minWidth</code>/<code>minHeight</code> calculations. We chose 144dp as an example good minimum |
| width for the text labels.</p> |
| |
| |
| <p>Example calculations are below:</p> |
| |
| <ul> |
| <li><code>minWidth</code> = 144dp + (2 × 8dp) + (2 × 56dp) = |
| <strong>272dp</strong></li> |
| <li><code>minHeight</code> = 48dp + (2 × 4dp) = <strong>56dp</strong></li> |
| </ul> |
| |
| <p>If there is any inherent content padding in your widget background nine-patch, you should add to |
| <code>minWidth</code> and <code>minHeight</code> accordingly.</p> |
| |
| |
| <h3 id="anatomy_resizable_widgets">Resizable widgets</h3> |
| |
| <p>Widgets can be resized horizontally and/or vertically as of Android 3.1, meaning that |
| <code>minWidth</code> and <code>minHeight</code> effectively become the <em>default</em> size for |
| the widget. You can specify the minimum widget size using <code>minResizeWidth</code> and |
| <code>minResizeHeight</code>; these values should specify the size below which the widget would be |
| illegible or otherwise unusable.</p> |
| |
| <p>This is generally a preferred feature for collection widgets such as those based on {@link |
| android.widget.ListView} or {@link android.widget.GridView}.</p> |
| |
| |
| <h3 id="anatomy_adding_margins">Adding margins to your app widget</h3> |
| |
| <p>As previously mentioned, Android 4.0 will automatically add small, standard margins to each edge |
| of widgets on the Home screen, for applications that specify a <code>targetSdkVersion</code> of 14 |
| or greater. This helps to visually balance the Home screen, and thus <strong>we recommend that you |
| do not add any extra margins outside of your app widget's background shape in Android |
| 4.0</strong>.</p> |
| |
| <p>It's easy to write a single layout that has custom margins applied for earlier versions of the |
| platform, and has no extra margins for Android 4.0 and greater. See <a |
| href="{@docRoot}guide/topics/appwidgets/index.html#AddingMargins">Adding Margins to App Widgets</a> |
| in the <em>Developer's Guide</em> for information on how to achieve this with layout XML.</p> |
| |
| |
| <h2 id="design">Designing Widget Layouts and Background Graphics</h2> |
| |
| <p>Most widgets will have a solid background rectangle or rounded rectangle shape. It is a best |
| practice to define this shape using nine patches; one for each screen density (see <a |
| href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> for details). |
| Nine-patches can be created with the <a |
| href="{@docRoot}guide/developing/tools/draw9patch.html">draw9patch</a> tool, or simply with a |
| graphics editing program such as Adobe® Photoshop. This will allow the widget background shape |
| to take up the entire available space. The nine-patch should be edge-to-edge with no transparent |
| pixels providing extra margins, save for perhaps a few border pixels for <strong>subtle</strong> |
| drop shadows or other subtle effects.</p> |
| |
| <p class="note"><strong>Note: </strong> Just like with controls in activities, you should ensure |
| that interactive controls have distinct visual focused and pressed states using <a |
| href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">state list |
| drawables</a>.</p> |
| |
| |
| <img src="{@docRoot}images/ninepatch_raw.png" alt="Nine-patch border pixels" id="ninepatch_raw"> |
| |
| <p class="img-caption"><strong>Figure 5.</strong> Nine-patch border pixels indicating stretchable |
| regions and content padding.</p> |
| |
| |
| <p>Some app widgets, such as those using a {@link android.widget.StackView}, have a transparent |
| background. For this case, each individual item in the StackView should use a nine-patch background |
| that is edge-to-edge with little or no border transparent pixels for margins.</p> |
| |
| <p>For the contents of the widget, you should use flexible layouts such as {@link |
| android.widget.RelativeLayout}, {@link android.widget.LinearLayout}, or {@link |
| android.widget.FrameLayout}. Just as your activity layouts must adapt to different physical screen |
| sizes, widget layouts must adapt to different Home screen grid cell sizes.</p> |
| |
| <p>Below is an example layout that a music widget showing text information and two buttons can use. |
| It builds upon the previous discussion of adding margins depending on OS version. Note that the |
| most robust and resilient way to add margins to the widget is to wrap the widget frame and contents |
| in a padded {@link android.widget.FrameLayout}.</p> |
| |
| <pre> |
| <FrameLayout |
| android:layout_width="match_parent" |
| android:layout_height="match_parent" |
| android:padding="@dimen/widget_margin"> |
| |
| <LinearLayout |
| android:layout_width="match_parent" |
| android:layout_height="match_parent" |
| android:orientation="horizontal" |
| android:background="@drawable/my_widget_background"> |
| |
| <TextView |
| android:id="@+id/song_info" |
| android:layout_width="0dp" |
| android:layout_height="match_parent" |
| android:layout_weight="1" /> |
| |
| <Button |
| android:id="@+id/play_button" |
| android:layout_width="@dimen/my_button_width" |
| android:layout_height="match_parent" /> |
| |
| <Button |
| android:id="@+id/skip_button" |
| android:layout_width="@dimen/my_button_width" |
| android:layout_height="match_parent" /> |
| </LinearLayout> |
| </FrameLayout> |
| </pre> |
| |
| <p>If you now take a look at the example music widget from the previous section, you can begin to |
| use flexible layouts attributes like so:</p> |
| |
| |
| <img src="{@docRoot}images/widget_design/music_example_layouts.png" |
| alt="Excerpt flexible layouts and attributes for an example music widget" |
| id="music_example_layouts"> |
| |
| <p class="img-caption"><strong>Figure 6.</strong> Excerpt flexible layouts and attributes.</p> |
| |
| |
| <p>When a user adds the widget to their home screen, on an example Android 4.0 device where each |
| grid cell is 80dp × 100dp in size and 8dp of margins are automatically applied on all sizes, |
| the widget will be stretched, like so:</p> |
| |
| |
| <img src="{@docRoot}images/widget_design/music_example_stretched.png" |
| alt="Music widget sitting on an example 80dp x 100dp grid with 8dp of automatic margins |
| added by the system" id="music_example_stretched"> |
| |
| <p class="img-caption"><strong>Figure 7.</strong> Music widget sitting on an example 80dp x 100dp |
| grid with 8dp of automatic margins added by the system.</p> |
| |
| |
| <h2 id="templates">Using the App Widget Templates Pack</h2> |
| |
| <p>When starting to design a new widget, or updating an existing widget, it's a good idea to first |
| look at the widget design templates below. The downloadable package below includes nine-patch |
| background graphics, XML, and source Adobe® Photoshop files for multiple screen densities, OS |
| version widget styles, and widget colors. The template package also contains graphics useful for |
| making your entire widget or parts of your widget (e.g. buttons) interactive.</p> |
| |
| |
| <img src="{@docRoot}images/widget_design/widget_template_excerpts.png" |
| alt="Widget template excerpts" id="widget_template_excerpts"> |
| |
| <p class="img-caption"><strong>Figure 8.</strong> Excerpts from the App Widget Templates Pack |
| (medium-density, dark, Android 4.0/previous styles, default/focused/pressed states).</p> |
| |
| |
| <p>You can obtain the latest App Widget Templates Pack archive using the link below:</p> |
| |
| <p style="margin-left:2em"><a href="{@docRoot}shareables/app_widget_templates-v4.0.zip"> |
| Download the App Widget Templates Pack for Android 4.0 »</a></p> |
| |