Merge "Revised some text while reading up on traceview. this is what's left of this older CL that was left for dead: I5528b476d8110df51d45aaf690d878f72bc75c9f" into klp-docs
diff --git a/core/java/android/provider/Settings.java b/core/java/android/provider/Settings.java
index 7f24539..04f3f0a 100644
--- a/core/java/android/provider/Settings.java
+++ b/core/java/android/provider/Settings.java
@@ -3252,9 +3252,14 @@
/**
* A 64-bit number (as a hex string) that is randomly
- * generated on the device's first boot and should remain
- * constant for the lifetime of the device. (The value may
- * change if a factory reset is performed on the device.)
+ * generated when the user first sets up the device and should remain
+ * constant for the lifetime of the user's device. The value may
+ * change if a factory reset is performed on the device.
+ * <p class="note"><strong>Note:</strong> When a device has <a
+ * href="{@docRoot}about/versions/android-4.2.html#MultipleUsers">multiple users</a>
+ * (available on certain devices running Android 4.2 or higher), each user appears as a
+ * completely separate device, so the {@code ANDROID_ID} value is unique to each
+ * user.</p>
*/
public static final String ANDROID_ID = "android_id";
diff --git a/docs/downloads/training/BitmapFun.zip b/docs/downloads/training/BitmapFun.zip
index 8668897..d3dd02a 100644
--- a/docs/downloads/training/BitmapFun.zip
+++ b/docs/downloads/training/BitmapFun.zip
Binary files differ
diff --git a/docs/html/about/versions/jelly-bean.jd b/docs/html/about/versions/jelly-bean.jd
index c7d1941..c6702b0 100644
--- a/docs/html/about/versions/jelly-bean.jd
+++ b/docs/html/about/versions/jelly-bean.jd
@@ -438,9 +438,9 @@
<p>Android 4.3 also includes new utilities and APIs for creating better RTL
strings and testing your localized UIs. A new <strong>BidiFormatter</strong>
-provides a set of simple APIs for wrapping Unicode strings so that you can
-fine-tune your text rendering in RTL scripts. To let you use this utility more
-broadly in your apps, the BidiFormatter APIs are also now available for earlier
+class provides a simple API for wrapping Unicode strings, so that RTL-script
+data is displayed as intended in LTR-locale messages and vice-versa. To let you use this utility more
+broadly in your apps, the BidiFormatter API is also now available for earlier
platform versions through the Support Package in the Android SDK. </p>
<p>To assist you with managing date formatting across locales, Android 4.3
diff --git a/docs/html/about/versions/kitkat.jd b/docs/html/about/versions/kitkat.jd
index bf28a4f..5e442ec 100644
--- a/docs/html/about/versions/kitkat.jd
+++ b/docs/html/about/versions/kitkat.jd
@@ -1006,15 +1006,16 @@
<h4 id="44-pseudolocale-rtl">Force RTL Layout</h4>
<p>
- To make it easier to test and debug your layouts, Android includes a new
- developer option to force RTL layout direction in all apps.
+ To make it easier to test and debug layout mirroring issues without switching
+ to an RTL language, Android includes a new developer option to force RTL layout
+ direction in all apps.
</p>
<p>
The Force RTL layout option switches the device to RTL layout for all locales and
displays text in your current language. This can help you find layout issues
across your app, without having to display the app in an RTL language. You
- can access the RTL pseudo-localed as in <strong>Settings > Developer
+ can access the option in <strong>Settings > Developer
options > Force RTL layout direction</strong>.
</p>
diff --git a/docs/html/design/building-blocks/buttons.jd b/docs/html/design/building-blocks/buttons.jd
index 7957ef8..1f7e25d 100644
--- a/docs/html/design/building-blocks/buttons.jd
+++ b/docs/html/design/building-blocks/buttons.jd
@@ -9,39 +9,83 @@
</div>
</a>
-<p>A button consists of text and/or an image that clearly communicates what action will occur when the
-user touches it. Android supports two different types of buttons: <em>basic buttons</em> and <em>borderless
-buttons</em>. Both can contain text labels and/or images.</p>
+<p>A button consists of text and/or an image that clearly communicates what action
+ will occur when the user touches it. A button can have an image, text, or both.
+</p>
-<img src="{@docRoot}design/media/buttons_basic.png">
-
-<h2 id="basic">Basic Buttons</h2>
-
-<p>Basic buttons are traditional buttons with borders and background. Android supports two styles for
-basic buttons: default and small. Default buttons have slightly larger font size and are optimized
-for display outside of form content. Small buttons are intended for display alongside other content.
-They have a smaller font and smaller minimum height. Use small buttons in forms where they need to
-align with other UI elements.</p>
-
-<img src="{@docRoot}design/media/buttons_default_small.png">
-<div class="layout-content-row">
- <div class="layout-content-col span-6">
- <div class="figure-caption">
- Default buttons in Holo Dark & Light.
- </div>
+<div class="layout-content-row" style="margin-top:22px">
+ <div class="layout-content-col span-3">
+ <img src="{@docRoot}design/media/icon_magnifying_glass.png" style="height:64px;padding:20px 0 0 40px;">
</div>
- <div class="layout-content-col span-6">
- <div class="figure-caption">
- Small buttons in Holo Dark & Light.
- </div>
+ <div class="layout-content-col span-3">
+ <img src="{@docRoot}design/media/buttons_text.png" style="height:94px;">
+ </div>
+ <div class="layout-content-col span-7">
+ <img src="{@docRoot}design/media/buttons_image_and_text.png" style="height:94px;">
</div>
</div>
-<h2 id="borderless">Borderless Buttons</h2>
+<div class="layout-content-row" style="margin-top:0;">
+ <div class="layout-content-col span-3">
+ <p>An image alone works best when the action can be represented by a symbol that's well understood.</p>
+ </div>
+ <div class="layout-content-col span-3">
+ <p>Text alone is most appropriate for actions that would be difficult to
+ represent visually, or are critical to convey in words to avoid any ambiguity.</p>
+ </div>
+ <div class="layout-content-col span-7">
+ <p>
+ Both an icon and text is most appropriate when they complement each other:
+ each carrying its own bit of information, but together making a larger whole.
+ </p>
-<p>Borderless buttons resemble basic buttons except that they have no borders or background. You can
-use borderless buttons with both icons and text. Borderless buttons are visually more lightweight
-than basic buttons and integrate nicely with other content.</p>
+ <p>
+ For example, in a birthday reminder card in Google Now, the button's text
+ describes the action while its image indicates that the action will be done
+ in Google+.
+ </p>
+ </div>
+</div>
-<img src="{@docRoot}design/media/buttons_borderless.png">
+<h3>What about button backgrounds?</h3>
+
+<div class="layout-content-row">
+ <div class="layout-content-col span-6">
+ <p>For <strong>image-only</strong> buttons, a background isn't necessary because
+ users are accustomed to interacting with objects.</p>
+
+ <div class="layout-content-row" style="margin-left:72px">
+ <div class="layout-content-col span-2">
+ <div class="do-dont-label bad emulate-content-left-padding" style="width:30px">Don't</div>
+ <img src="{@docRoot}design/media/buttons_image_bg_dont.png" style="padding-left:14px;">
+ </div>
+ <div class="layout-content-col span-2" style="width:29px;margin-left:10px;">
+ <div class="do-dont-label good"><strong>Do</strong></div>
+ <img src="{@docRoot}design/media/icon_alarm.png" style="width:31px;padding-top:7px;">
+ </div>
+ </div>
+ </div>
+
+<div class="layout-content-col span-7">
+<p>
+ For buttons <strong>with text</strong>, a background is also usually
+ unnecessary. To invite users to touch, phrase it as a clear action (e.g.
+ "Start", "Sign in") and use different color and formatting than the screen's
+ usual body text.
+</p>
+
+<p>
+ Use buttons with backgrounds sparingly. Because they have a heavy appearance,
+ they work best when there's only one or two of them on the screen. They're
+ most appropriate for:
+</p>
+
+<ul>
+ <li>A call to action you really want users to pursue (e.g. "Sign up")</li>
+ <li>A key decision point (e.g. "Accept" / "Decline")</li>
+ <li>When the user is about to commit a significant action (e.g. "Erase
+ everything", "Buy now")</li>
+</ul>
+</div>
+</div>
diff --git a/docs/html/design/downloads/index.jd b/docs/html/design/downloads/index.jd
index d514c14..16f5509 100644
--- a/docs/html/design/downloads/index.jd
+++ b/docs/html/design/downloads/index.jd
@@ -1,4 +1,5 @@
page.title=Downloads
+page tags="Icons", "stencils", "color swatches"
@jd:body
<div class="layout-content-row">
@@ -15,7 +16,7 @@
<p>
<a class="download-button" onClick="_gaq.push(['_trackEvent', 'Design', 'Download', 'All Design Assets']);"
- href="{@docRoot}downloads/design/Android_Design_Downloads_20130814.zip">Download All</a>
+ href="{@docRoot}downloads/design/Android_Design_Downloads_20131106.zip">Download All</a>
</p>
</div>
@@ -26,8 +27,8 @@
<div class="layout-content-row">
<div class="layout-content-col span-5">
-<p>Drag and drop your way to beautifully designed Ice Cream Sandwich apps. The stencils feature the
-rich typography, colors, interactive controls, and icons found throughout Android 4.0, along with
+<p>Drag and drop your way to beautifully designed Android apps. The stencils feature the
+rich typography, colors, interactive controls, and icons found throughout Android, along with
phone and tablet outlines to frame your creations. Source files for icons and controls are also
available.</p>
@@ -40,14 +41,14 @@
<div class="layout-content-col span-4">
<p>
- <a class="download-button" onClick="_gaq.push(['_trackEvent', 'Design', 'Download', 'Fireworks Stencil']);"
+ <!--<a class="download-button" onClick="_gaq.push(['_trackEvent', 'Design', 'Download', 'Fireworks Stencil']);"
href="{@docRoot}downloads/design/Android_Design_Fireworks_Stencil_20120814.png">Adobe® Fireworks® PNG Stencil</a>
<a class="download-button" onClick="_gaq.push(['_trackEvent', 'Design', 'Download', 'Illustrator Stencil']);"
href="{@docRoot}downloads/design/Android_Design_Illustrator_Vectors_20120814.ai">Adobe® Illustrator® Stencil</a>
<a class="download-button" onClick="_gaq.push(['_trackEvent', 'Design', 'Download', 'OmniGraffle Stencil']);"
- href="{@docRoot}downloads/design/Android_Design_OmniGraffle_Stencil_20120814.graffle">Omni® OmniGraffle® Stencil</a>
+ href="{@docRoot}downloads/design/Android_Design_OmniGraffle_Stencil_20120814.graffle">Omni® OmniGraffle® Stencil</a>-->
<a class="download-button" onClick="_gaq.push(['_trackEvent', 'Design', 'Download', 'Photoshop Sources']);"
- href="{@docRoot}downloads/design/Android_Design_Holo_Widgets_20120814.zip">Adobe® Photoshop® Sources</a>
+ href="{@docRoot}downloads/design/Android_Design_Stencils_Sources_20131106.zip">Adobe® Photoshop® Stencils and Sources</a>
</p>
</div>
@@ -74,7 +75,7 @@
<p>
<a class="download-button" onClick="_gaq.push(['_trackEvent', 'Design', 'Download', 'Action Bar Icons']);"
- href="{@docRoot}downloads/design/Android_Design_Icons_20130926.zip">Action Bar Icon Pack</a>
+ href="{@docRoot}downloads/design/Android_Design_Icons_20131106.zip">Action Bar Icon Pack</a>
</p>
</div>
@@ -114,7 +115,7 @@
<div class="layout-content-col span-5">
<h4>Color</h4>
-<p>Blue is the standard accent color in Android's color palette. Each color has a corresponding darker
+<p>In Android's color palette, each color has a corresponding darker
shade that can be used as a complement when needed.</p>
<p><a href="{@docRoot}design/style/color.html">More on Color</a></p>
diff --git a/docs/html/design/media/buttons_image_and_text.png b/docs/html/design/media/buttons_image_and_text.png
new file mode 100644
index 0000000..b7ffccb
--- /dev/null
+++ b/docs/html/design/media/buttons_image_and_text.png
Binary files differ
diff --git a/docs/html/design/media/buttons_image_bg_dont.png b/docs/html/design/media/buttons_image_bg_dont.png
new file mode 100644
index 0000000..651d3ce
--- /dev/null
+++ b/docs/html/design/media/buttons_image_bg_dont.png
Binary files differ
diff --git a/docs/html/design/media/buttons_text.png b/docs/html/design/media/buttons_text.png
new file mode 100644
index 0000000..54d3dd3
--- /dev/null
+++ b/docs/html/design/media/buttons_text.png
Binary files differ
diff --git a/docs/html/design/media/calendar.mp4 b/docs/html/design/media/calendar.mp4
deleted file mode 100644
index cdd72d2..0000000
--- a/docs/html/design/media/calendar.mp4
+++ /dev/null
Binary files differ
diff --git a/docs/html/design/media/calendar.ogv b/docs/html/design/media/calendar.ogv
deleted file mode 100644
index efb23d2..0000000
--- a/docs/html/design/media/calendar.ogv
+++ /dev/null
Binary files differ
diff --git a/docs/html/design/media/calendar.webm b/docs/html/design/media/calendar.webm
deleted file mode 100644
index 9d7d9f2..0000000
--- a/docs/html/design/media/calendar.webm
+++ /dev/null
Binary files differ
diff --git a/docs/html/design/media/dialogs_popups_example.png b/docs/html/design/media/dialogs_popups_example.png
index 6c98b1fc..a8ebacd 100644
--- a/docs/html/design/media/dialogs_popups_example.png
+++ b/docs/html/design/media/dialogs_popups_example.png
Binary files differ
diff --git a/docs/html/design/media/icon_alarm.png b/docs/html/design/media/icon_alarm.png
new file mode 100644
index 0000000..36ce643a
--- /dev/null
+++ b/docs/html/design/media/icon_alarm.png
Binary files differ
diff --git a/docs/html/design/media/icon_magnifying_glass.png b/docs/html/design/media/icon_magnifying_glass.png
new file mode 100644
index 0000000..d443a85
--- /dev/null
+++ b/docs/html/design/media/icon_magnifying_glass.png
Binary files differ
diff --git a/docs/html/design/media/multipane_view_tablet.png b/docs/html/design/media/multipane_view_tablet.png
index d59308a..a7135915 100644
--- a/docs/html/design/media/multipane_view_tablet.png
+++ b/docs/html/design/media/multipane_view_tablet.png
Binary files differ
diff --git a/docs/html/design/media/navigation_between_apps_back.png b/docs/html/design/media/navigation_between_apps_back.png
index a817374..d0c12cf 100644
--- a/docs/html/design/media/navigation_between_apps_back.png
+++ b/docs/html/design/media/navigation_between_apps_back.png
Binary files differ
diff --git a/docs/html/design/media/navigation_between_apps_inward.png b/docs/html/design/media/navigation_between_apps_inward.png
index 321d0da..75e7fc6 100644
--- a/docs/html/design/media/navigation_between_apps_inward.png
+++ b/docs/html/design/media/navigation_between_apps_inward.png
Binary files differ
diff --git a/docs/html/design/media/navigation_between_apps_up.png b/docs/html/design/media/navigation_between_apps_up.png
index 42d0d8f..67ebb77 100644
--- a/docs/html/design/media/navigation_between_apps_up.png
+++ b/docs/html/design/media/navigation_between_apps_up.png
Binary files differ
diff --git a/docs/html/design/media/navigation_from_outside_back.png b/docs/html/design/media/navigation_from_outside_back.png
index 0e1aa04..9153b08 100644
--- a/docs/html/design/media/navigation_from_outside_back.png
+++ b/docs/html/design/media/navigation_from_outside_back.png
Binary files differ
diff --git a/docs/html/design/media/navigation_up_vs_back_gmail.png b/docs/html/design/media/navigation_up_vs_back_gmail.png
index d5eaa18..7cc295e 100644
--- a/docs/html/design/media/navigation_up_vs_back_gmail.png
+++ b/docs/html/design/media/navigation_up_vs_back_gmail.png
Binary files differ
diff --git a/docs/html/design/media/touch_feedback.mp4 b/docs/html/design/media/touch_feedback.mp4
new file mode 100644
index 0000000..b91dc4b
--- /dev/null
+++ b/docs/html/design/media/touch_feedback.mp4
Binary files differ
diff --git a/docs/html/design/media/touch_feedback.ogv b/docs/html/design/media/touch_feedback.ogv
new file mode 100644
index 0000000..22c9f97
--- /dev/null
+++ b/docs/html/design/media/touch_feedback.ogv
Binary files differ
diff --git a/docs/html/design/media/touch_feedback.webm b/docs/html/design/media/touch_feedback.webm
new file mode 100644
index 0000000..a65c142
--- /dev/null
+++ b/docs/html/design/media/touch_feedback.webm
Binary files differ
diff --git a/docs/html/design/media/touch_feedback_thumb.png b/docs/html/design/media/touch_feedback_thumb.png
new file mode 100644
index 0000000..49af69f
--- /dev/null
+++ b/docs/html/design/media/touch_feedback_thumb.png
Binary files differ
diff --git a/docs/html/design/media/widgets_gestures.png b/docs/html/design/media/widgets_gestures.png
index 5e1268d..bbce87d 100644
--- a/docs/html/design/media/widgets_gestures.png
+++ b/docs/html/design/media/widgets_gestures.png
Binary files differ
diff --git a/docs/html/design/patterns/actionbar.jd b/docs/html/design/patterns/actionbar.jd
index 939370c..b6e3a16 100644
--- a/docs/html/design/patterns/actionbar.jd
+++ b/docs/html/design/patterns/actionbar.jd
@@ -182,7 +182,7 @@
<p>
<a onClick="_gaq.push(['_trackEvent', 'Design', 'Download', 'Action Bar Icons (@actionbar page)']);"
- href="{@docRoot}downloads/design/Android_Design_Icons_20130926.zip">Download the Action Bar Icon Pack</a>
+ href="{@docRoot}downloads/design/Android_Design_Icons_20131106.zip">Download the Action Bar Icon Pack</a>
</p>
diff --git a/docs/html/design/patterns/buttons.jd b/docs/html/design/patterns/buttons.jd
new file mode 100644
index 0000000..46e41c8
--- /dev/null
+++ b/docs/html/design/patterns/buttons.jd
@@ -0,0 +1,151 @@
+page.title=Buttons
+page.tags="buttons"
+@jd:body
+
+<p>
+ Some content is best experienced full screen, like videos, games, image
+ galleries, books, and slides in a presentation. You can engage users more
+ deeply with content in full screen by minimizing visual distraction from app
+ controls and protecting users from escaping the app accidentally.
+</p>
+
+<div style="margin:auto;padding:auto;text-align:center;">
+ <img src="{@docRoot}design/media/fullscreen_landing.png" style="margin:1em auto 2em auto;">
+</div>
+<p>
+ In version 4.4, Android offers two approaches for making your app go full
+ screen: Lean Back and Immersive. In both approaches, all persistent system
+ bars are hidden. The difference between them is how the user brings the bars
+ back into view.
+</p>
+
+<div class="layout-content-row">
+ <div class="layout-content-col span-6">
+ <h4>Lean Back</h4>
+ <p>Touch the screen anywhere to bring back system bars. </p>
+ <img src="{@docRoot}design/media/fullscreen_leanback.png" style="width:311px;">
+ </div>
+ <div class="layout-content-col span-6">
+ <h4>Immersive</h4>
+ <p>Swipe from the any edge of the screen with a hidden bar to bring back system bars. </p>
+ <img src="{@docRoot}design/media/fullscreen_immersive_swipe_bottom.png" style="width:160px;float:right">
+ <img src="{@docRoot}design/media/fullscreen_immersive_swipe_top.png" style="width:160px">
+ </div>
+</div>
+
+<h2 id="leanback">
+ Lean Back
+</h2>
+
+<p>
+ The Lean Back approach is for full-screen experiences in which users won't be
+ interacting heavily with the screen while consuming content, like while
+ watching a video.
+</p>
+
+<p>
+ In this type of experience, users are leaning back and watching the screen.
+ Then, when they need to bring back the bars, they simply touch anywhere. This
+ gesture is easy and intuitive.
+</p>
+
+ <img src="{@docRoot}design/media/fullscreen_leanback.png" style="width:311px;">
+
+<h2 id="immersive">
+ Immersive
+</h2>
+
+<p>
+ The Immersive approach is mainly intended for apps in which the user will be
+ heavily interacting with the full screen as part of the primary experience.
+ Examples are games, viewing images in a gallery, or reading paginated
+ content, like a book or slides in a presentation.
+</p>
+
+<p>
+ In this type of experience, when users need to bring back the system bars,
+ they swipe from any edge where a system bar is hidden. By requiring this more
+ deliberate gesture, the user's deep engagement with your app won't be
+ interrupted by accidental touches and swipes.
+</p>
+
+<div class="layout-content-row">
+ <div class="layout-content-col span-6">
+ <img src="{@docRoot}design/media/fullscreen_immersive_swipe_bottom.png" style="width:160px;float:right">
+ <img src="{@docRoot}design/media/fullscreen_immersive_swipe_top.png" style="width:160px">
+ </div>
+</div>
+
+<p>
+ The user learns about the gesture to bring back the system bars through a
+ message that appears the first time the app goes full screen.
+</p>
+
+<p>
+ If your app has its own controls that aren't needed when a user is immersed
+ in content, make them disappear and reappear in sync with the system bars.
+ This rule also applies to any app-specific gestures you might have for hiding
+ and showing app controls. For example, if touching anywhere on the screen
+ toggles the appearance of an action bar or a palette, then it must also
+ toggle the appearance of system bars.
+</p>
+
+<p>
+ You might be tempted to use this approach just to maximize screen real
+ estate. But be mindful of how often users jump in and out of apps to check
+ notifications, do impromptu searches, and more. This approach will cause
+ users to lose easy access to system navigation, so a little extra space
+ should not be the only benefit they're getting in return.
+</p>
+
+<h2 id="variation_using_edges">
+ Variation: Swiping from edges with bars also affects the app
+</h2>
+
+<p>
+ In the Immersive approach, any time a user swipes from an edge with a system
+ bar, the Android framework takes care of revealing the system bars. Your app
+ won't even be aware that this gesture occurred.
+</p>
+
+<p>
+ But in some apps, the user might occasionally need to swipe from the edge as
+ <strong>part of the primary app experience</strong>. Examples are games and
+ drawing applications.
+</p>
+
+<p>
+ For apps with this requirement, you can use a variation on the Immersive
+ approach: when a user swipes from an edge with a system bar, system bars are
+ shown and the gesture is passed to the app so the app can respond to the
+ gesture.
+</p>
+
+<p>
+ For example, in a drawing app that uses this approach, if a user wants to
+ draw a line that begins at the very edge of the screen, swiping from the edge
+ would reveal the system bars and also start drawing a line that begins at the
+ very edge.
+</p>
+
+<p>
+ In this approach, to minimize disruption while a user is deeply engaged in
+ the app, the system bars are semi-transparent. The bars automatically
+ disappear after a few seconds of no interaction or as soon as the user
+ touches or gestures anywhere outside the system bars.
+</p>
+
+<h2 id="lightsout">What About Lights Out Mode?</h2>
+
+<p>
+ Before Android 4.4, the design guideline was to use Lights Out mode, a mode
+ in which the Action Bar and Status Bar fades away and becomes unavailable
+ after a few seconds of inactivity. The Navigation Bar is still available and
+ responds to touches but appears dimmed.
+</p>
+
+<p>
+ Replace previous implementations of Lights Out mode with the Lean Back or
+ Immersive approaches. Continue to use Lights Out mode for implementations of
+ your app targeted for earlier releases.
+</p>
\ No newline at end of file
diff --git a/docs/html/design/patterns/fullscreen.jd b/docs/html/design/patterns/fullscreen.jd
index 191ca40..de016fe 100644
--- a/docs/html/design/patterns/fullscreen.jd
+++ b/docs/html/design/patterns/fullscreen.jd
@@ -9,8 +9,9 @@
controls and protecting users from escaping the app accidentally.
</p>
+<div style="margin:auto;padding:auto;text-align:center;">
<img src="{@docRoot}design/media/fullscreen_landing.png" style="margin:1em auto 2em auto;">
-
+</div>
<p>
In version 4.4, Android offers two approaches for making your app go full
screen: Lean Back and Immersive. In both approaches, all persistent system
diff --git a/docs/html/design/patterns/gestures.jd b/docs/html/design/patterns/gestures.jd
index 837a6dd..213902f 100644
--- a/docs/html/design/patterns/gestures.jd
+++ b/docs/html/design/patterns/gestures.jd
@@ -65,8 +65,9 @@
<div class="layout-content-col span-4">
<img src="{@docRoot}design/media/gesture_doubletouch.png">
<h4>Double touch </h4>
- <p>Scales up the smallest targetable view, if available, or scales a standard amount
- around the gesture. Also used as a secondary gesture for text selection.</p>
+ <p> Scales up a standard amount around the target with each repeated gesture until reaching
+ maximum scale. For nested views, scales up the smallest targetable view, or returns it to
+ its original scale. Also used as a secondary gesture for text selection.</p>
<ul>
<li class="no-bullet with-icon action">
<h4>Action</h4>
diff --git a/docs/html/design/style/branding.jd b/docs/html/design/style/branding.jd
index 9ef934d..2ea4d47 100644
--- a/docs/html/design/style/branding.jd
+++ b/docs/html/design/style/branding.jd
@@ -49,16 +49,16 @@
<div class="vspace size-1"> </div>
<div class="layout-content-row">
- <div class="layout-content-col span-6">
- <img src="{@docRoot}design/media/yourbranding_icon.png" style="width:60px;float:left;padding-right:1em;">
- <div class="figure-caption" style="widdth:220px;margin-left:20px;">
- The HowzAbout app uses a launcher icon that is a shortened version of its full logo.
+ <div class="layout-content-col span-6" style="padding-top:24px;">
+ <img src="{@docRoot}design/media/branding_launcher_icon.png" style="width:60px;float:left;padding-right:1em;">
+ <div class="figure-caption" style="width:290px;margin-left:20px;">
+ Google+ reinforces its brand by carrying its launcher icon through to the action bar.
</div>
-
+ <img src="{@docRoot}design/media/branding_logo_icon_action_bar.png" style="width:320px;float:left;padding-right:1em;">
</div>
<div class="layout-content-col span-6">
- <img src="{@docRoot}design/media/yourbranding_app.png" style="width:94%">
- <div class="figure-caption">
+ <img src="{@docRoot}design/media/yourbranding_app.png" style="width:320px;">
+ <div class="figure-caption" style="width:320px;">
Example of a the logo in the action bar. This works well in cases where the brand's logo matches the name of the app.
</div>
</div>
@@ -77,7 +77,7 @@
</div>
<div class="layout-content-col span-6">
- <img src="{@docRoot}design/media/yourbranding_in-app-icons.png" style="width:300px;margin:12px 48px 0 16px;"">
+ <img src="{@docRoot}design/media/yourbranding_in-app-icons.png" style="width:300px;margin:12px 48px 0 16px;">
</div>
</div>
</div>
@@ -100,9 +100,9 @@
<div style="margin-bottom:1em;">
<span class="do-dont-label bad" style="margin-left:12px">Don't</span>
- <span style="margin-left: 44px;" class="do-dont-label good"><strong>Do</strong></span>
+ <span style="margin-left: 64px;" class="do-dont-label good"><strong>Do</strong></span>
</div>
- <img src="{@docRoot}design/media/yourbranding_sharing.png" style="width:200px;">
+ <img src="{@docRoot}design/media/yourbranding_sharing.png" style="width:180px;">
</div>
</div>
diff --git a/docs/html/design/style/iconography.jd b/docs/html/design/style/iconography.jd
index b0a3439..fe4a3f9 100644
--- a/docs/html/design/style/iconography.jd
+++ b/docs/html/design/style/iconography.jd
@@ -139,7 +139,7 @@
</p>
<p>
<a onClick="_gaq.push(['_trackEvent', 'Design', 'Download', 'Action Bar Icons (@iconography page)']);"
- href="{@docRoot}downloads/design/Android_Design_Icons_20130926.zip">Download the Action Bar Icon Pack</a>
+ href="{@docRoot}downloads/design/Android_Design_Icons_20131106.zip">Download the Action Bar Icon Pack</a>
</p>
<div class="layout-content-row">
diff --git a/docs/html/design/style/touch-feedback.jd b/docs/html/design/style/touch-feedback.jd
index a5bf7b3..2d15166 100644
--- a/docs/html/design/style/touch-feedback.jd
+++ b/docs/html/design/style/touch-feedback.jd
@@ -7,8 +7,6 @@
<p>Use illumination and dimming to respond to touches, reinforce the resulting behaviors
of gestures, and indicate what actions are enabled and disabled.</p>
-<p>Whenever a user touches an actionable area in your app, provide a subtle visual response.
-This lets the user know which object was touched and that your app is "listening".</p>
<p><strong>Be responsive to touches in a gentle way</strong>. Whenever a user touches an
actionable area in your app, let them know the app is "listening" by providing a visual
@@ -22,27 +20,16 @@
easier because the default touch feedback works with whatever hue you choose.</li>
</ul>
- </div>
+</div>
- <div class="layout-content-col span-6" style="float:right;">
-
- <!-- <div class="framed-nexus5-port-span-5">
- <video class="play-on-hover" autoplay>
- <source src="{@docRoot}design/media/calendar.mp4" type="video/mp4">
- <source src="{@docRoot}design/media/calendar.webm" type="video/webm">
- <source src="{@docRoot}design/media/calendar.ogv" type="video/ogg">
- </video>
- </div>
- <div class="figure-caption" style="margin-top:0">
- <div class="video-instructions"> </div>
- </div>
- </div> -->
-
-
- <div class="layout-content-col span-6">
-
- <img src="{@docRoot}design/media/touch_feedback_reaction_response.png">
-
+<div class="layout-content-col span-6" style="float:right;">
+ <video poster="{@docRoot}design/media/touch_feedback_thumb.png" class="play-on-hover" width="270" autoplay style="border:1px solid #ddd;">
+ <source src="{@docRoot}design/media/touch_feedback.mp4" type="video/mp4">
+ <source src="{@docRoot}design/media/touch_feedback.webm" type="video/webm">
+ <source src="{@docRoot}design/media/touch_feedback.ogv" type="video/ogg">
+ </video>
+ <div class="figure-caption">
+ <div style="color:#a3a3a3;margin-left:130px;"><em>Click image to replay...</em></div>
</div>
</div>
diff --git a/docs/html/distribute/distribute_toc.cs b/docs/html/distribute/distribute_toc.cs
index ecdf2a8..b9a0eec 100644
--- a/docs/html/distribute/distribute_toc.cs
+++ b/docs/html/distribute/distribute_toc.cs
@@ -81,6 +81,7 @@
<ul>
<li><a href="<?cs var:toroot ?>distribute/googleplay/spotlight/tablets.html">Tablet Stories</a></li>
<li><a href="<?cs var:toroot ?>distribute/googleplay/spotlight/games.html">Game Stories</a></li>
+ <li><a href="<?cs var:toroot ?>distribute/googleplay/spotlight/localization.html">Localization Stories</a></li>
</ul>
</li>
diff --git a/docs/html/distribute/googleplay/publish/localizing.jd b/docs/html/distribute/googleplay/publish/localizing.jd
index 7788ce1..1a5f3c1 100644
--- a/docs/html/distribute/googleplay/publish/localizing.jd
+++ b/docs/html/distribute/googleplay/publish/localizing.jd
@@ -372,24 +372,24 @@
<p>After the translations are merged back into your app, start <a
href="#testing">testing the localized app</a>.</p>
+<h4 id="gp-trans">Purchase professional translations through Google Play
+<br />App Translation Service</h4>
+
<div class="sidebox-wrapper">
<div class="sidebox">
-<h2>Join the translation pilot</h2>
-<p>Google Play is offering translation services as part of a pilot
-program. If you're interested, sign up on the APK page in your
-Developer Console.</p>
+<h2>App Translations in Google Play</h2>
-<p>If you join, also try the <a
+<p>Hear from developers who have used the Google Play App Translation Service in <a
+href="{@docRoot}distribute/googleplay/spotlight/localization.html">Developer
+Stories: Localization in Google Play</a>.</p>
+
+<p>To make it easy to export your app's strings and import
+the finished translations into your project, try the <a
href="{@docRoot}sdk/installing/installing-adt.html#tmgr">
-ADT Translation Manager Plugin</a>, which makes it easy to upload
-your strings to the Developer Console and download translations
-right into your project. </div>
+ADT Translation Manager Plugin</a>.</div>
</div>
-<h4 id="gp-trans">Purchase professional translations through the
-Developer Console</h4>
-
-<p>Google Play can help you quickly find and purchase translations of your app.
+<p>Google Play App Translation Service can help you quickly find and purchase translations of your app.
In the Developer Console, you can browse a list of third-party vendors who are
pre-qualified by Google to offer high-quality translation at competitive prices.
You can upload the strings you want translated, select the languages you want to
diff --git a/docs/html/distribute/googleplay/spotlight/localization.jd b/docs/html/distribute/googleplay/spotlight/localization.jd
new file mode 100644
index 0000000..ae5993d
--- /dev/null
+++ b/docs/html/distribute/googleplay/spotlight/localization.jd
@@ -0,0 +1,328 @@
+page.title=Developer Stories: Localization in Google Play
+walkthru=0
+header.hide=0
+
+@jd:body
+
+<p>
+ As you build your app and distribute it across the world through Google Play,
+ localization becomes an increasingly important tool to reach more users.
+ Localization involves a <a href=
+ "{@docRoot}distribute/googleplay/publish/localizing.html">variety of tasks</a>, but
+ most important is creating quality translations of your app's UI strings and
+ marketing materials.
+</p>
+
+<p>
+ Managing the translation process across multiple languages can be a
+ challenge, especially if you need to locate translators on your own. That’s
+ why Google Play offers the App Translation Service right from the Developer
+ Console. It's a single place where you can go to source professional
+ translators, get cost estimates, and then send your strings and other
+ materials for translation.
+</p>
+
+<p>
+ Here are some stories from developers who have used Google Play's App Translation
+ Service to localize their apps and the results they've seen as they've
+ expand their offerings beyond a single language.
+</p>
+
+<!-- START STORY -->
+
+<div style="margin-bottom:2em;padding-top:10px;" id="zombieragdoll">
+
+<h3 style="line-height:1.25em">Zombie Ragdoll: Improved user engagement<br /> with localized versions</h3>
+
+ <img alt="" class="screenshot thumbnail" style="-webkit-border-radius: 5px;
+ -moz-border-radius: 5px;
+ border-radius: 5px height:78px;
+ width: 78px;
+ float: left;
+ margin: 12px 20px 9px 20px;" src=
+ "https://lh4.ggpht.com/m-Ew8c8C_nGctbP6PSPGOaVNnGFryReOE2yHXJ9Z6Prk1nsDyx5w5TmWfg-P5N3HypA=w124">
+
+ <div style="list-style: none;height:100%;
+ float: right;
+ border-top: 1px solid #9C0;
+ width: 220px;
+ margin: 4px 20px;padding: .5em;">
+
+ <h5>About the app</h5>
+
+ <ul>
+ <li><a href="https://play.google.com/store/apps/details?id=com.rvappstudios.zombieragdoll">Zombie Ragdoll</a></li>
+ <li>A fun zombie-based physics game</li>
+ </ul>
+
+ <h5>Localization Results</h5>
+
+ <ul>
+ <li>Increased engagement because of appeal of the localized version</li>
+ <li>80% of installs came from users of non-English languages</li>
+ </ul>
+
+ <div style="padding:.5em 0 0 1em;">
+ <a href="https://play.google.com/store/apps/details?id=com.rvappstudios.zombieragdoll">
+ <img alt="Android app on Google Play"
+ src="//developer.android.com/images/brand/en_generic_rgb_wo_45.png" />
+ </a>
+
+ </div>
+ </div>
+
+ <div style="line-height:1.4em;">
+
+<p>
+ The 2013 Google I/O talks about <a href=
+ "https://developers.google.com/events/io/sessions/326345917">Building Android
+ Apps for a Global Audience</a> and <a href=
+ "https://developers.google.com/events/io/sessions/326455375">What’s New for
+ Developers in Google Play</a> inspired developers at RV AppStudios to go global
+ from very beginning for their new game, Zombie Ragdoll. They launched Zombie
+ Ragdoll in August 2013, localized into 20 languages.
+</p>
+
+<p>
+ They quickly saw the impact of their decision to ship simultaneously in
+ multiple languages through increased non-English installs and improved
+ engagement with users worldwide. In addition, they started getting
+ significant usage in countries where their apps had not been as popular
+ before. They are seeing great traction in countries like Vietnam, Russia,
+ Philippines and Thailand.
+</p>
+
+<p>
+ Vivek Dave, founder of RV AppStudios, credits the success of Zombie Ragdoll
+ to localization:
+</p>
+
+<p>
+ "The value of localization is clear, it helps discoverability and helps
+ connect with the users in other countries. So when the localization
+ opportunity arose, we immediately jumped on it. Android is worldwide, and we
+ would be severely limiting ourselves if we focused on English as the only
+ language.
+</p>
+
+<p>
+ "The App Translation Service offered in the Google Play Developer Console is
+ extremely easy to use and the pricing is very attractive. Developers with
+ limited localization experience can easily create, upload, and translate
+ their app."
+</p>
+
+
+<p>
+ RV AppStudios not only localizes the text within the game, but also localizes
+ the game assets to a specific country/culture. Dave says, “Users want a
+ personalized experience, and by offering a localized game with translation of
+ text and graphic assets, we believe users will connect at a much deeper level
+ with the game.”
+</p>
+
+
+ <div style="margin-top:8px;float:left;margin-right:24px;">
+ <img src="{@docRoot}images/distribute/zombie-ragdoll-n5-land.jpg" style="width:470px;">
+ </div>
+
+
+ <div style="margin-top:128px;">
+ <p class="img-caption"><strong>Hindi version of Zombie Ragdoll</strong>:
+ Localized screenshots and videos in the app's Google Play listing go a
+ long way toward increasing the number of installs.</p>
+ </div>
+
+ </div>
+
+</div> <!-- END STORY -->
+
+<!-- START STORY -->
+
+<div style="margin-bottom:2em;padding-top:18px;clear:both;" id="sayhichat">
+
+<h3>SayHi Chat: Install growth and user engagement<br />
+ from professional translations</h3>
+
+ <img alt="" class="screenshot thumbnail" style="-webkit-border-radius: 5px;
+ -moz-border-radius: 5px;
+ border-radius: 5px height:78px;
+ width: 78px;
+ float: left;
+ margin: 12px 20px 9px 20px;" src=
+ "https://lh5.ggpht.com/qiL6CF1Hktz618T3mbGrxvm_OoeheQ78FgG7zr90C2MCRiz4IDQsbKuHT4xQGiWEU8o=w124">
+
+ <div style="list-style: none;height:100%;
+ float: right;
+ border-top: 1px solid #9C0;
+ width: 220px;
+ margin: 4px 20px;padding: .5em;">
+
+ <h5>About the app</h5>
+
+ <ul>
+ <li><a href="https://play.google.com/store/apps/details?id=com.unearby.sayhi">SayHi Chat,
+ Love, Meet, Dating</a></li>
+ <li>A social app to help you find people nearby</li>
+ </ul>
+
+ <h5>Localization Results</h5>
+
+ <ul>
+ <li>120% growth in language installs for new languages added</li>
+ <li>~20% increase in revenue and ~50% increase in User Reviews in the new
+ languages</li>
+ </ul>
+
+ <div style="padding:.5em 0 0 1em;">
+ <a href="https://play.google.com/store/apps/details?id=com.unearby.sayhi">
+ <img alt="Android app on Google Play"
+ src="//developer.android.com/images/brand/en_generic_rgb_wo_45.png" />
+ </a>
+
+ </div>
+ </div>
+
+ <div style="line-height:1.4em;">
+
+<p>
+ The SayHi Chat app started out only in Japanese, Chinese and English. It soon
+ became one of the most popular apps in Japan, Hong Kong, and Taiwan. The
+ SayHi team realized it was time to launch in more languages, as the language
+ barrier was restricting how fast SayHi could grow globally. </p>
+
+ <p>Yan Shi, senior
+ developer at SayHi, says: "We checked Google Analytics for our DAU and user
+ growth numbers in each country, we also looked at total Android and iOS users
+ in those markets before finalizing our next set of languages.
+</p>
+
+ <div style="margin-top:8px;float:left;width:270px;">
+ <img src="{@docRoot}images/distribute/hichat-n5-port.jpg" style="width:240px;margin-right:48px;">
+ </div>
+
+<p>
+ SayHi used the App Translation Service to launch in 13 additional languages
+ in August 2013 and immediately saw 120% increase in install rates. In
+ addition, they are seeing their app ranked in Top 10 apps in countries like
+ Poland and Italy.
+</p>
+
+<p>Notably, they saw steady growth in Spain after replacing their previous
+ non-professional Spanish translation with a professional one produced through
+ the App Translation Service.</p>
+
+<p>
+ Yan Shi adds, “The App Translation Service is really easy to use and
+ the completion time for translation requests is very good.”
+</p>
+
+ <div style="width:600px;margin-top:98px;padding:0;">
+ <p class="img-caption"><strong>Arabic version of SayHi Chat</strong>:
+ User engagement increased significantly with
+ the localized version.</p>
+ </div>
+
+ </div>
+</div> <!-- END STORY -->
+
+
+<div style="margin-bottom:2em;clear:both;padding-top:18px;" id="g4a"><!-- START STORY -->
+
+<h3 style="line-spacing:1.25em;">G4A Indian Rummy: Benefitting from ease-of-use and<br /> fast turnaround time</h3>
+
+ <img alt="" class="screenshot thumbnail" style="-webkit-border-radius: 5px;
+ -moz-border-radius: 5px;
+ border-radius: 5px height:78px;
+ width: 78px;
+ float: left;
+ margin: 12px 20px 9px 20px;" src=
+ "https://lh4.ggpht.com/IxSyQgO0LWzPRoLfCrER06-0kr6aMAa2azF7eNYB30EBZAGOLYJUZulknPockbTlDYU=w124">
+
+ <div style="list-style: none;height:100%;
+ float: right;
+ border-top: 1px solid #9C0;
+ width: 220px;
+ margin: 4px 20px;padding: .5em;">
+
+ <h5>About the app</h5>
+
+ <ul>
+ <li><a href="https://play.google.com/store/apps/details?id=org.games4all.android.games.indianrummy.prod">G4A Indian Rummy</a></li>
+ <li>A card game in which the players try to form sets and sequences of cards</li>
+ </ul>
+
+ <h5>Localization Results</h5>
+
+ <ul>
+ <li>Double the number of users in French and German languages</li>
+ <li>300% increase in user engagement with localized version</li>
+ </ul>
+
+ <div style="padding:.5em 0 0 1em;">
+ <a href="https://play.google.com/store/apps/details?id=com.rvappstudios.zombieragdoll">
+ <img alt="Android app on Google Play"
+ src="//developer.android.com/images/brand/en_generic_rgb_wo_45.png" />
+ </a>
+ </div>
+ </div>
+
+ <div style="line-height:1.4em;">
+
+<p>
+ Games4All (G4A) is the developer of Indian Rummy and a variety of games that
+ they distribute broadly to users around the world. After noticing that
+ certain apps had become especially popular in specific countries, they
+ decided to localize those apps. Initially they used a local agency to do
+ the translation and got great results — the number of users in
+ that language increased tremendously when they released the localized
+ version.
+</p>
+
+<p>
+ Building on that success, G4A expanded their localization goals but
+ found that translation quality varied across their vendors and costs limited the
+ language/game combinations they could try. That's when G4A decided to try the
+ App Translation Service.
+</p>
+
+<p>
+ Founder Pieter Olivier says, "When we heard that the App Translation
+ Service was available in the Developer Console, we jumped at the opportunity.
+ We've now been using the App Translation Service for several months and found
+ that the cost per translation is much lower than with local companies and the
+ process is much easier."
+</p>
+
+<p>So far, G4A has translated the game Indian Rummy into five languages through
+ the App Translation Service.</p>
+
+<p>
+ Olivier continues, "The first thing we did was convert all of our texts into
+ the strings.xml format. After that using the service was extremely easy and
+ straightforward. In contrast, our previous experiences with translation
+ agencies were much more difficult: files often required extensive conversion
+ operations to make them usable, and turnaround times varied wildly.
+</p>
+
+<p>
+ "With the App Translation Service, the turnaround time is usually measured in
+ days instead of weeks that we were used to with traditional translation
+ agencies."
+</p>
+
+ <div style="margin-top:14px;float:left;margin-right:24px;">
+ <img src="{@docRoot}images/distribute/indian-rummy-n4-land.jpg" style="width:470px;">
+ </div>
+
+ <div style="margin-top:158px;">
+ <p class="img-caption"><strong>Dutch
+ version of Indian Rummy</strong>: Making slight changes to games rules based on
+ local nuances was key to success of the game.</p>
+ </div>
+
+ </div>
+
+
+
+</div> <!-- END STORY -->
\ No newline at end of file
diff --git a/docs/html/google/play-services/setup.jd b/docs/html/google/play-services/setup.jd
index 6553c18..fb656b7 100644
--- a/docs/html/google/play-services/setup.jd
+++ b/docs/html/google/play-services/setup.jd
@@ -1,6 +1,24 @@
page.title=Set Up Google Play Services SDK
@jd:body
+
+
+<div id="qv-wrapper">
+<div id="qv">
+
+<h2>In this document</h2>
+<ol>
+ <li><a href="#Install">Install the Google Play Services SDK</a></li>
+ <li><a href="#Setup">Set Up a Project that Uses Google Play Services</a></li>
+ <li><a href="#Proguard">Create a Proguard Exception</a></li>
+ <li><a href="#ensure">Ensure Devices Have the Google Play services APK</a></li>
+</ol>
+
+
+</div>
+</div>
+
+
<p>To develop an app using the <a href="{@docRoot}reference/gms-packages.html">Google
Play services APIs</a>, you must download the Google Play services SDK
@@ -10,7 +28,7 @@
<p>To test your app when using the Google Play services SDK, you must use either:</p>
<ul>
<li>A compatible Android
- device that runs Android 2.2 or higher and includes Google Play Store.</li>
+ device that runs Android 2.3 or higher and includes Google Play Store.</li>
<li>The Android emulator with an <a href="{@docRoot}tools/devices/index.html">AVD</a>
that runs the Google APIs platform based on Android 4.2.2 or higher.</li>
</ul>
@@ -24,9 +42,12 @@
<p>To install the Google Play services SDK for development:</p>
<ol>
- <li>Launch the SDK Manager.
+ <li>Launch the SDK Manager in one of the following ways:
<ul>
- <li>From Eclipse (with <a href="{@docRoot}tools/help/adt.html">ADT</a>),
+ <li>In Android Studio, click <strong>SDK Manager</strong>
+<img src="{@docRoot}images/tools/sdk-manager-studio.png" style="vertical-align:bottom;margin:0;height:19px" />
+in the toolbar.</li>
+ <li>In Eclipse (with <a href="{@docRoot}tools/help/adt.html">ADT</a>),
select <strong>Window</strong> > <strong>Android SDK Manager</strong>.</li>
<li>On Windows, double-click the <code>SDK Manager.exe</code> file at the root of the Android
SDK directory.</li>
@@ -36,19 +57,25 @@
</li>
<li>Install the Google Play services SDK.
<p>Scroll to the bottom of the package list, expand <b>Extras</b>, select
- <b>Google Play services</b>, and install it.</p>
+ <b>Google Play services</b>, and install it. If you're using Android Studio, also install
+ <b>Google Repository</b> (it provides the Maven repository used for Gradle builds).</p>
<p>The Google Play services SDK is saved in your Android SDK environment at
<code><android-sdk>/extras/google/google_play_services/</code>.</p>
+
+<p class="note"><strong>Note:</strong> Google Play services 4.0.30 (released
+November 2013) and newer versions require Android 2.3 or higher. If your app supports Android 2.2,
+you can continue development with the Google Play services SDK, but must instead install
+<b>Google Play services for Froyo</b> from the SDK Manager.</p>
+
</li>
<li>Install a compatible version of the Google APIs platform.
<p>If you want to test your app on the emulator, expand the directory for <b>Android 4.2.2
(API 17)</b> or a higher version, select <b>Google APIs</b>, and install it. Then create a
new <a href="{@docRoot}tools/devices/index.html">AVD</a> with Google APIs as
the platform target.</p>
- <p class="note"><strong>Note:</strong> Only Android 4.2.2 and higher versions of the
- Google APIs platform include Google Play services.</p>
</li>
<li>Make a copy of the Google Play services library project.
+ <p class="note"><strong>Note:</strong> If you are using Android Studio, skip this step.</p>
<p>Copy the library project at
<code><android-sdk>/extras/google/google_play_services/libproject/google-play-services_lib/</code>
to the location where you maintain your Android app projects.
@@ -60,23 +87,59 @@
-<h2 id="Setup">Set Up a Project with the Library</h2>
+<h2 id="Setup">Set Up a Project that Uses Google Play Services</h2>
-<p>To set up a project to use the Google Play services SDK:</p>
+<p><b>Using Android Studio:</b></p>
<ol>
- <li>Reference the library project in your Android project.
- <p>See the
- <a href="{@docRoot}tools/projects/projects-eclipse.html#ReferencingLibraryProject">Referencing a Library Project for Eclipse</a>
- or <a href="{@docRoot}tools/projects/projects-cmdline.html#ReferencingLibraryProject">Referencing a Library Project on the Command Line</a>
- for more information on how to do this.</p>
- <p class="note"><strong>Note:</strong>
- You should be referencing a copy of the library that you copied to your development
- workspace—you should not reference the library directly from the Android SDK directory.</p>
+ <li>Open the <code>build.gradle</code> file inside your application directory.</li>
+ <li>Add a new build rule under <code>dependencies</code> for the latest version of
+<code>play-services</code>. For example:
+<pre class="no-pretty-print">
+apply plugin: 'android'
+...
+
+dependencies {
+ compile 'com.android.support:appcompat-v7:+'
+ <strong>compile 'com.google.android.gms:play-services:4.0.30'</strong>
+}
+</pre>
+<p>Be sure you update this version number each time Google Play services is updated.</p>
</li>
- <li>If you are using <a href="{@docRoot}tools/help/proguard.html">ProGuard</a>, add the following
- lines in the <code><project_directory>/proguard-project.txt</code> file
- to prevent ProGuard from stripping away required classes:
+ <li>Save the changes and click <strong>Sync Project with Gradle Files</strong>
+<img src="{@docRoot}images/tools/sync-project.png" style="vertical-align:bottom;margin:0;height:19px" />
+in the toolbar.
+ </li>
+</ol>
+
+<p>You can now begin developing features with the
+<a href="{@docRoot}reference/gms-packages.html">Google Play services APIs</a>.</p>
+
+
+<p><b>Using Eclipse or another IDE:</b></p>
+
+<p>To make the Google Play services APIs available to your app, you must reference the library
+project you created in step 4 of the <a href="#Install">installation instructions</a>.</p>
+<p>See the <a href="{@docRoot}tools/projects/projects-eclipse.html#ReferencingLibraryProject"
+>Referencing a Library Project for Eclipse</a> or <a
+href="{@docRoot}tools/projects/projects-cmdline.html#ReferencingLibraryProject">Referencing a
+Library Project on the Command Line</a> for more information on how to do this.</p>
+
+<p class="note"><strong>Note:</strong>
+You should be referencing a copy of the library that you copied to your development
+workspace—you should not reference the library directly from the Android SDK directory.</p>
+
+<p>Once you've set up your project to reference the library project,
+you can begin developing features with the
+<a href="{@docRoot}reference/gms-packages.html">Google Play services APIs</a>.</p>
+
+
+
+<h2 id="Proguard">Create a Proguard Exception</h2>
+
+<p>To prevent <a href="{@docRoot}tools/help/proguard.html">ProGuard</a> from stripping away
+required classes, add the following lines in the
+<code><project_directory>/proguard-project.txt</code> file:
<pre>
-keep class * extends java.util.ListResourceBundle {
protected Object[][] getContents();
@@ -95,11 +158,13 @@
public static final ** CREATOR;
}
</pre>
+
+<p class="note"><strong>Note:</strong> When using Android Studio, you must add Proguard
+to your <code>gradle.build</code> file's build types. For more information, see the
+<a href="http://tools.android.com/tech-docs/new-build-system/user-guide#TOC-Running-ProGuard"
+>Gradle Plugin User Guide</a>.
</ol>
-<p>Once you have the Google Play services library project added to your app project,
-you can begin developing features with the
-<a href="{@docRoot}reference/gms-packages.html">Google Play services APIs</a>.</p>
@@ -191,4 +256,4 @@
to display an error message to the user, which allows the user to download the APK
from the Google Play Store or enable it in the device's system settings.
</li>
-</ol>
\ No newline at end of file
+</ol>
diff --git a/docs/html/guide/topics/connectivity/nfc/hce.jd b/docs/html/guide/topics/connectivity/nfc/hce.jd
index 3e6468f..4ef6859 100644
--- a/docs/html/guide/topics/connectivity/nfc/hce.jd
+++ b/docs/html/guide/topics/connectivity/nfc/hce.jd
@@ -70,7 +70,7 @@
works.</p>
<img src="{@docRoot}images/nfc/host-based-card.png" />
-<p class="img-caption"><strong>Figure 2.</strong> NFC card emulation with a secure element.</p>
+<p class="img-caption"><strong>Figure 2.</strong> NFC card emulation without a secure element.</p>
<h2 id="SupportedProtocols">Supported NFC Cards and Protocols</h2>
@@ -288,12 +288,12 @@
<pre>
<service android:name=".MyHostApduService" android:exported="true"
- android:permission="android.permission.BIND_NFC_SERVICE">
+ android:permission="android.permission.BIND_NFC_SERVICE">
<intent-filter>
<action android:name="android.nfc.cardemulation.action.HOST_APDU_SERVICE"/>
</intent-filter>
<meta-data android:name="android.nfc.cardemulation.host_apdu_service"
- android:resource="@xml/apduservice"/>
+ android:resource="@xml/apduservice"/>
</service>
</pre>
@@ -306,7 +306,7 @@
android:description="@string/servicedesc"
android:requireDeviceUnlock="false">
<aid-group android:description="@string/aiddescription"
- android:category="other">
+ android:category="other">
<aid-filter android:name="F0010203040506"/>
<aid-filter android:name="F0394148148100"/>
</aid-group>
@@ -381,14 +381,14 @@
<pre>
<host-apdu-service xmlns:android="http://schemas.android.com/apk/res/android"
- android:description="@string/servicedesc"
- android:requireDeviceUnlock="false"
- android:apduServiceBanner="@drawable/my_banner">
- <aid-group android:description="@string/aiddescription"
- android:category="payment">
- <aid-filter android:name="F0010203040506"/>
- <aid-filter android:name="F0394148148100"/>
- </aid-group>
+ android:description="@string/servicedesc"
+ android:requireDeviceUnlock="false"
+ android:apduServiceBanner="@drawable/my_banner">
+ <aid-group android:description="@string/aiddescription"
+ android:category="payment">
+ <aid-filter android:name="F0010203040506"/>
+ <aid-filter android:name="F0394148148100"/>
+ </aid-group>
</host-apdu-service>
</pre>
@@ -478,12 +478,12 @@
<pre>
<service android:name=".MyOffHostApduService" android:exported="true"
- android:permission="android.permission.BIND_NFC_SERVICE">
+ android:permission="android.permission.BIND_NFC_SERVICE">
<intent-filter>
<action android:name="android.nfc.cardemulation.action.OFF_HOST_APDU_SERVICE"/>
</intent-filter>
<meta-data android:name="android.nfc.cardemulation.off_host_apdu_ervice"
- android:resource="@xml/apduservice"/>
+ android:resource="@xml/apduservice"/>
</service>
</pre>
</li>
diff --git a/docs/html/guide/topics/manifest/uses-permission-element.jd b/docs/html/guide/topics/manifest/uses-permission-element.jd
index 8e9e795..bd7091e 100644
--- a/docs/html/guide/topics/manifest/uses-permission-element.jd
+++ b/docs/html/guide/topics/manifest/uses-permission-element.jd
@@ -35,7 +35,8 @@
</div>
<dt>syntax:</dt>
-<dd><pre class="stx"><uses-permission android:<a href="#nm">name</a>="<i>string</i>" /></pre></dd>
+<dd><pre class="stx"><uses-permission android:<a href="#nm">name</a>="<i>string</i>"
+ android:<a href="#maxSdk">maxSdkVersion</a>="<i>integer</i>" /></pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd>
@@ -63,6 +64,25 @@
or "{@code android.permission.READ_CONTACTS}". As these examples show,
a permission name typically includes the package name as a prefix.</dd>
+<dt><a name="maxSdk"></a>{@code android:maxSdkVersion}</dt>
+<dd>The highest API level at which this permission should be granted to your app.
+Setting this attribute is useful if the permission your app requires is no longer needed beginning
+at a certain API level.
+<p>For example, beginning with Android 4.4 (API level 19), it's no longer necessary for your app
+to request the {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} permission when your
+app wants to write to its own application-specific directories on external storage (the directories
+provided by {@link android.content.Context#getExternalFilesDir getExternalFilesDir()}). However,
+the permission <em>is required</em> for API level 18 and lower. So you can declare that this
+permission is needed only up to API level 18 with a declaration such as this:
+<pre>
+<uses-permission
+ android:name="android.permission.WRITE_EXTERNAL_STORAGE"
+ android:maxSdkVersion="18" />
+</pre>
+<p>This way, beginning with API level 19, the system will no longer grant your app the
+{@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} permission.</p>
+</dd>
+
</dl></dd>
<!-- ##api level indication## -->
diff --git a/docs/html/guide/topics/resources/localization.jd b/docs/html/guide/topics/resources/localization.jd
index 55c8dc42..7288aeb 100644
--- a/docs/html/guide/topics/resources/localization.jd
+++ b/docs/html/guide/topics/resources/localization.jd
@@ -19,7 +19,7 @@
<ol>
<li><a href="#resource-switching">Overview: Resource-Switching in Android</a></li>
<li><a href="#using-framework">Using Resources for Localization</a></li>
-<li><a href="#strategies">Localization Strategies</a></li>
+<li><a href="#strategies">Localization Tips</a></li>
<li><a href="#testing">Testing Localized Applications</a></li>
</ol>
@@ -304,7 +304,13 @@
For more about this, see <a
href="{@docRoot}guide/topics/resources/accessing-resources.html">Accessing Resources</a>.</p>
-<h2 id="strategies">Localization Strategies</h2>
+<h2 id="checklist">Localization Checklist</h2>
+
+<p>For a complete overview of the process of localizing and distributing an Android application,
+see the <a href="{@docRoot}distribute/googleplay/publish/localizing.html">Localization
+Checklist</a> document.</p>
+
+<h2 id="strategies">Localization Tips</h2>
<h4 id="failing2">Design your application to work in any locale</h4>
@@ -478,6 +484,4 @@
portrait orientation and see if the application will run.
-<h2 id="checklist">Localization Checklist</h2>
-<p>For an overview of the process of localizing an Android application, see the <a href="{@docRoot}distribute/googleplay/publish/localizing.html">Localization Checklist</a>.</p>
diff --git a/docs/html/images/distribute/hichat-n5-port.jpg b/docs/html/images/distribute/hichat-n5-port.jpg
new file mode 100644
index 0000000..b93e983
--- /dev/null
+++ b/docs/html/images/distribute/hichat-n5-port.jpg
Binary files differ
diff --git a/docs/html/images/distribute/indian-rummy-n4-land.jpg b/docs/html/images/distribute/indian-rummy-n4-land.jpg
new file mode 100644
index 0000000..61943fc
--- /dev/null
+++ b/docs/html/images/distribute/indian-rummy-n4-land.jpg
Binary files differ
diff --git a/docs/html/images/distribute/zombie-ragdoll-n5-land.jpg b/docs/html/images/distribute/zombie-ragdoll-n5-land.jpg
new file mode 100644
index 0000000..e2bf6b5
--- /dev/null
+++ b/docs/html/images/distribute/zombie-ragdoll-n5-land.jpg
Binary files differ
diff --git a/docs/html/images/tools/sync-project.png b/docs/html/images/tools/sync-project.png
new file mode 100644
index 0000000..09e1835
--- /dev/null
+++ b/docs/html/images/tools/sync-project.png
Binary files differ
diff --git a/docs/html/index.jd b/docs/html/index.jd
index 5c805f8..3e59068 100644
--- a/docs/html/index.jd
+++ b/docs/html/index.jd
@@ -14,78 +14,62 @@
<a href="" class="slideshow-next">Next</a>
<div class="frame">
<ul>
+ <!-- set explicit widths as needed to prevent overflow issues -->
<li class="item carousel-home">
- <div class="content-left col-7">
- <a href="/about/versions/kitkat.html"><img src="/images/home/kk-hero.jpg" style="width:242px;padding-top:72px;"></a>
- </div>
- <div class="content-right col-6">
+ <div class="content-left col-7" style="width:400px;">
+ <a href="{@docRoot}about/versions/kitkat.html">
+ <img src="{@docRoot}images/home/kk-hero.jpg" width="242" style="padding-top:72px;">
+ </a>
+ </div>
+ <div class="content-right col-4" style="width:340px;">
<h1>Android 4.4 KitKat!</h1>
<p>A new version of Android is here, with great new features, APIs, and tools for developers.</p>
<p>Android 4.4 is built to run on more devices than ever before, and gives you more ways to showcase your content and create beautiful, useful, and innovative apps.</p>
<p>Learn about what's new in the Platform Highlights and see the API Overview for details.</p>
- <p><a href="/about/versions/kitkat.html" class="button">Check out the highlights</a></p>
- </div>
+ <p><a href="{@docRoot}about/versions/kitkat.html" class="button">Check out the highlights</a></p>
+ </div>
</li>
<li class="item carousel-home">
- <div class="content-left col-11" style="padding-top:65px;">
- <a href="https://www.youtube.com/watch?v=sONcojECWXs&list=PLWz5rJ2EKKc-2quE-o0enpILZF3nBZg_K&index=1">
- <img src="/images/title-devbytes-kk.jpg" style="margin-top:22px;width:600px;">
- </a>
- </div>
-
- <div class="content-right col-4">
+ <div class="content-left col-11" style="padding-top:65px;">
+ <a href="https://www.youtube.com/watch?v=sONcojECWXs&list=PLWz5rJ2EKKc-2quE-o0enpILZF3nBZg_K&index=1">
+ <img src="{@docRoot}images/title-devbytes-kk.jpg" style="margin-top:0px;width:600px;">
+ </a>
+ </div>
+ <div class="content-right col-4">
<h1 style="white-space:nowrap;line-height:1.2em;">DevBytes: <br />Android 4.4</h1>
<p>Join the DevBytes team for a look at what's new in Android 4.4 KitKat — new ways to make your apps beautiful, printing, storage access framework, and more.</p>
<p><a href="https://www.youtube.com/watch?v=sONcojECWXs&list=PLWz5rJ2EKKc-2quE-o0enpILZF3nBZg_K&index=1" class="button">Watch the video </a></p>
- </div>
+ </div>
</li>
-
<li class="item carousel-home">
- <div class="content-left col-10"><a href="/design/patterns/new.html">
- <img src="/design/media/design_elements_landing.png" style="margin-top:30px">
- </a>
- </div>
- <div class="content-right col-5">
+ <div class="content-left col-19" style="width:580px;">
+ <a href="{@docRoot}design/patterns/new.html">
+ <img src="{@docRoot}design/media/design_elements_landing.png" style="margin-top:30px">
+ </a>
+ </div>
+ <div class="content-right col-4" style="width:280px;">
<h1>Design for Android KitKat</h1>
<p>Android KitKat brings a refreshed UI with updated styles, patterns, and gestures to use in your apps. </p>
<p>We've updated the Android Design guidelines and added new pages on branding, fullscreen, and more. </p>
- <p><a href="/design/patterns/new.html" class="button">See what's new</a></p>
- </div>
+ <p><a href="{@docRoot}design/patterns/new.html" class="button">See what's new</a></p>
+ </div>
</li>
- <!--<li class="item carousel-home">
- <div class="content-left col-11" style="padding-top:65px;">
- <a href="http://www.youtube.com/watch?v=6QHkv-bSlds&list=PLWz5rJ2EKKc8j2B95zGMb8muZvrIy-wcF&index=1">
- <img src="/images/title-adia-kk.png" style="margin-top:22px;width:600px;">
- </a>
- </div>
-
- <div class="content-right col-4">
+ <li class="item carousel-home">
+ <div class="content-left col-11" style="padding-top:65px;">
+ <a href="http://www.youtube.com/watch?v=6QHkv-bSlds&list=PLWz5rJ2EKKc8j2B95zGMb8muZvrIy-wcF&index=1">
+ <img src="{@docRoot}images/title-adia-kk.png" style="margin-top:0px;width:600px;">
+ </a>
+ </div>
+ <div class="content-right col-4">
<h1 style="white-space:nowrap;line-height:1.2em;">ADIA: <br />Android 4.4</h1>
</p>Join the Android Design in Action team for a walkthrough of new developer features, UX changes, and updates to design guidelines in Android 4.4.</p>
<p><a href="http://www.youtube.com/watch?v=6QHkv-bSlds&list=PLWz5rJ2EKKc8j2B95zGMb8muZvrIy-wcF&index=1" class="button">Watch the video </a></p>
- </div>
- </li> -->
- <!-- <li class="item carousel-home">
- <div class="content-left col-11" style="padding-top:10px;">
- <a href="/channels/io2013.html">
- <img src="/images/home/io-videos-2013.png" style="margin:60px 0 0;
- box-shadow: 3px 10px 18px 1px #999;">
- </a>
- </div>
- <div class="content-right col-4">
- <h1>Hands-on with New KitKat Features</h1>
- <p>If you weren't able to attend Google I/O in person or couldn't make it
- to all the talks, you can catch up on the action
- with all the recordings, brought to you by
- <a href="http://developers.google.com/live">Google Developers Live</a>.</p>
- <p><a href="/channels/io2013.html" class="button"
- >See the Android talks</a></p>
- </div>
- </li> -->
+ </div>
+ </li>
</ul>
</div>
</div>
diff --git a/docs/html/sdk/installing/installing-adt.jd b/docs/html/sdk/installing/installing-adt.jd
index 88fd7df..66c3034 100644
--- a/docs/html/sdk/installing/installing-adt.jd
+++ b/docs/html/sdk/installing/installing-adt.jd
@@ -74,12 +74,14 @@
<div class="sidebox-wrapper">
<div class="sidebox">
-<h2>Join the translation pilot</h2>
-<p>Google Play is offering <a
-href="{@docRoot}distribute/googleplay/publish/localizing.html#gp-trans">
-translation services</a> as part of a pilot program. If you are interested,
-sign up for the pilot program on the APK page in your Developer Console.</p>
-</div></div>
+<h2>App Translations in Google Play</h2>
+<p>Google Play <a href="{@docRoot}distribute/googleplay/publish/localizing.html#gp-trans">App
+Translation Service</a> is available in the Developer Console to help you
+localize your app for a global user base. You can browse qualified vendors, get
+estimates, upload strings for translation, and then import the translations directly
+into your app.</p>
+</div>
+</div>
<p>ADT Translation Manager Plugin is an Android SDK Tools plugin that helps
you work with strings that you are localizing. It's designed to work
@@ -97,7 +99,8 @@
localization works instantly.</p>
<p>For more information about translation services in Google Play, see <a
-href="{@docRoot}distribute/googleplay/publish/localizing.html#gp-trans">Purchase professional translations through the Developer Console</a>.</p>
+href="{@docRoot}distribute/googleplay/publish/localizing.html#gp-trans">Purchase
+professional translations through the Developer Console</a>.</p>
<p>To install the ADT Translation Manager Plugin follow these steps:</p>
diff --git a/docs/html/tools/debugging/debugging-memory.jd b/docs/html/tools/debugging/debugging-memory.jd
index 0454293..a7f443c 100644
--- a/docs/html/tools/debugging/debugging-memory.jd
+++ b/docs/html/tools/debugging/debugging-memory.jd
@@ -181,11 +181,18 @@
<h2 id="ViewingAllocations">Viewing Overall Memory Allocations</h2>
-<p>For further analysis, you may want to observe how that your app's memory is
-divided between different categories, which you can do with the <code>adb meminfo</code> data.</p>
+<p>For further analysis, you may want to observe how your app's memory is
+divided between different types of RAM allocation with the
+following <a href="{@docRoot}tools/help/adb.html">adb</a> command:</p>
-<p>When talking about how much RAM your app is using with this data, the key metrics
-discussed below are:</p>
+<pre class="no-pretty-print">
+adb shell dumpsys meminfo <package_name>
+</pre>
+
+<p>The output lists all of your app's current allocations, measured in kilobytes.</p>
+
+<p>When inspecting this information, you should be familiar with the
+following types of allocation:</p>
<dl>
<dt>Private (Clean and Dirty) RAM</dt>
@@ -210,15 +217,9 @@
actual RAM weight of a process and for comparison against the RAM use of other processes and the
total available RAM.</p>
-<p>You can look at the memory use of your app (measured in kilobytes) with the
-following adb command:</p>
-
-<pre class="no-pretty-print">
-adb shell dumpsys meminfo <package_name>
-</pre>
<p>For example, below is the the output for Gmail’s process on a tablet device. There is a lot of
-information here, but key points for discussion are highlighted in different colors.</p>
+information here, but key points for discussion are listed below.</p>
<p class="note"><strong>Note:</strong> The information you see may vary slightly from what is shown
here, as some details of the output differ across platform versions.</p>
diff --git a/docs/html/tools/help/proguard.jd b/docs/html/tools/help/proguard.jd
index be0b8dc..3ba7db2 100644
--- a/docs/html/tools/help/proguard.jd
+++ b/docs/html/tools/help/proguard.jd
@@ -61,6 +61,12 @@
<p>To enable ProGuard so that it runs as part of an Ant or Eclipse build, set the
<code>proguard.config</code> property in the <code><project_root>/project.properties</code>
file. The path can be an absolute path or a path relative to the project's root.</p>
+
+<p class="note"><strong>Note:</strong> When using Android Studio, you must add Proguard
+to your <code>gradle.build</code> file's build types. For more information, see the
+<a href="http://tools.android.com/tech-docs/new-build-system/user-guide#TOC-Running-ProGuard"
+>Gradle Plugin User Guide</a>.
+
<p>If you left the <code>proguard.cfg</code> file in its default location (the project's root directory),
you can specify its location like this:</p>
<pre class="no-pretty-print">
diff --git a/docs/html/training/displaying-bitmaps/manage-memory.jd b/docs/html/training/displaying-bitmaps/manage-memory.jd
index 0e1279e..7f2b4c5 100644
--- a/docs/html/training/displaying-bitmaps/manage-memory.jd
+++ b/docs/html/training/displaying-bitmaps/manage-memory.jd
@@ -160,13 +160,14 @@
in a {@link java.util.HashSet}, for possible reuse later with
{@link android.graphics.BitmapFactory.Options#inBitmap}:
-<pre>HashSet<SoftReference<Bitmap>> mReusableBitmaps;
+<pre>Set<SoftReference<Bitmap>> mReusableBitmaps;
private LruCache<String, BitmapDrawable> mMemoryCache;
-// If you're running on Honeycomb or newer, create
-// a HashSet of references to reusable bitmaps.
+// If you're running on Honeycomb or newer, create a
+// synchronized HashSet of references to reusable bitmaps.
if (Utils.hasHoneycomb()) {
- mReusableBitmaps = new HashSet<SoftReference<Bitmap>>();
+ mReusableBitmaps =
+ Collections.synchronizedSet(new HashSet<SoftReference<Bitmap>>());
}
mMemoryCache = new LruCache<String, BitmapDrawable>(mCacheParams.memCacheSize) {
@@ -243,25 +244,27 @@
Bitmap bitmap = null;
if (mReusableBitmaps != null && !mReusableBitmaps.isEmpty()) {
- final Iterator<SoftReference<Bitmap>> iterator
- = mReusableBitmaps.iterator();
- Bitmap item;
+ synchronized (mReusableBitmaps) {
+ final Iterator<SoftReference<Bitmap>> iterator
+ = mReusableBitmaps.iterator();
+ Bitmap item;
- while (iterator.hasNext()) {
- item = iterator.next().get();
+ while (iterator.hasNext()) {
+ item = iterator.next().get();
- if (null != item && item.isMutable()) {
- // Check to see it the item can be used for inBitmap.
- if (canUseForInBitmap(item, options)) {
- bitmap = item;
+ if (null != item && item.isMutable()) {
+ // Check to see it the item can be used for inBitmap.
+ if (canUseForInBitmap(item, options)) {
+ bitmap = item;
- // Remove from reusable set so it can't be used again.
+ // Remove from reusable set so it can't be used again.
+ iterator.remove();
+ break;
+ }
+ } else {
+ // Remove from the set if the reference has been cleared.
iterator.remove();
- break;
}
- } else {
- // Remove from the set if the reference has been cleared.
- iterator.remove();
}
}
}
diff --git a/graphics/java/android/graphics/BitmapFactory.java b/graphics/java/android/graphics/BitmapFactory.java
index 6fd1763..429be49 100644
--- a/graphics/java/android/graphics/BitmapFactory.java
+++ b/graphics/java/android/graphics/BitmapFactory.java
@@ -259,14 +259,26 @@
* (e.g. the bitmap is drawn, getPixels() is called), they will be
* automatically re-decoded.
*
- * For the re-decode to happen, the bitmap must have access to the
+ * <p>For the re-decode to happen, the bitmap must have access to the
* encoded data, either by sharing a reference to the input
* or by making a copy of it. This distinction is controlled by
* inInputShareable. If this is true, then the bitmap may keep a shallow
* reference to the input. If this is false, then the bitmap will
* explicitly make a copy of the input data, and keep that. Even if
* sharing is allowed, the implementation may still decide to make a
- * deep copy of the input data.
+ * deep copy of the input data.</p>
+ *
+ * <p>While inPurgeable can help avoid big Dalvik heap allocations (from
+ * API level 11 onward), it sacrifices performance predictability since any
+ * image that the view system tries to draw may incur a decode delay which
+ * can lead to dropped frames. Therefore, most apps should avoid using
+ * inPurgeable to allow for a fast and fluid UI. To minimize Dalvik heap
+ * allocations use the {@link #inBitmap} flag instead.</p>
+ *
+ * <p class="note"><strong>Note:</strong> This flag is ignored when used
+ * with {@link #decodeResource(Resources, int,
+ * android.graphics.BitmapFactory.Options)} or {@link #decodeFile(String,
+ * android.graphics.BitmapFactory.Options)}.</p>
*/
public boolean inPurgeable;
