Merge "Update Widget Design guidelines for ICS"

Author: romannurik

docs/html/guide/guide_toc.cs

@@ -717,7 +717,7 @@ localized titles are added in the language order specified below.
             </ul>
           </li>
           <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/widget_design.html">
-                <span class="en">App Widget Design</span>
+                <span class="en">App Widget Design <span class="new">updated</span></span>
               </a></li>
           <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/activity_task_design.html">
                 <span class="en">Activity and Task Design</span>

docs/html/guide/practices/ui_guidelines/widget_design.jd

@@ -327,6 +327,49 @@ following layout classes:</p>
 <p>Descendants of these classes are not supported.</p>
 
 
+<h3 id="AddingMargins">Adding margins to App Widgets</h3>
+
+<p>Widgets should not generally extend to screen edges and should not visually be flush with other widgets, so you should add margins on all sides around your widget frame.</p>
+
+<p>As of Android 4.0, app widgets are automatically given padding 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>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:</p>
+
+<ol>
+  <li>Set your application's <code>targetSdkVersion</code> to 14 or greater.</li>
+  <li>Create a layout such as the one below, that references a <a href="{@docRoot}guide/topics/resources/more-resources.html#Dimension">dimension resource</a> for its margins:
+
+<pre>
+&lt;FrameLayout
+  android:layout_width="match_parent"
+  android:layout_height="match_parent"
+  <strong>android:layout_margin="@dimen/widget_margin"&gt;</strong>
+
+  &lt;LinearLayout
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    android:orientation="horizontal"
+    android:background="@drawable/my_widget_background"&gt;
+    &hellip;
+  &lt;/LinearLayout&gt;
+
+&lt;/FrameLayout&gt;
+</pre>
+
+  </li>
+  <li>Create two dimensions resources, one in <code>res/values/</code> to provide the pre-Android 4.0 custom margins, and one in <code>res/values-v14/</code> to provide no extra padding for Android 4.0 widgets:
+
+    <p><strong>res/values/dimens.xml</strong>:<br>
+    <pre>&lt;dimen name="widget_margin"&gt;15dp&lt;/dimen&gt;</pre></p>
+
+    <p><strong>res/values-v14/dimens.xml</strong>:<br>
+    <pre>&lt;dimen name="widget_margin"&gt;0dp&lt;/dimen&gt;</pre></p>
+  </li>
+</ol>
+
+<p>Another option is to simply build extra margins into your <a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">nine-patch</a> background assets by default, and provide different nine-patches with no margins for API level 14 or later.</p>
+
+
 <h2 id="AppWidgetProvider">Using the AppWidgetProvider Class</h2>
 
 <div class="sidebox-wrapper">