Merge "Doc update: clarify best practices." into klp-docs
diff --git a/docs/html/distribute/googleplay/spotlight/index.jd b/docs/html/distribute/googleplay/spotlight/index.jd
index b501f20..6f92c78b 100644
--- a/docs/html/distribute/googleplay/spotlight/index.jd
+++ b/docs/html/distribute/googleplay/spotlight/index.jd
@@ -7,6 +7,34 @@
<p>Android developers, their apps, and their successes with Android and Google Play. </p>
+<div id="Kiwi" style="background: #F0F0F0;
+ border-top: 1px solid #DDD;
+ padding: 0px 0 24px 0;
+ overflow: auto;
+ clear:both;
+ margin-bottom:40px;
+ margin-top:30px;">
+ <div style="padding:0 0 0 29px;">
+ <h4>Developer Story: Kiwi, Inc.</h4>
+ <img alt="" class="screenshot thumbnail" style="-webkit-border-radius: 5px;
+ -moz-border-radius: 5px;
+ border-radius: 5px height:78px;
+ width: 78px;
+ float: left;
+ margin: 17px 20px 9px 0;"
+ src="//lh4.ggpht.com/qUI-8MJy70l4qoVBR_sx-56ckR_m0R_ZXcJ1DiTYUR3R_owWzsCFTYkAk4p5DMnaSdY3=w124" >
+ <div style="width:700px;">
+ <p style="margin-top:26px;
+ margin-bottom:12px;">
+ Android-first developer <a href="//play.google.com/store/apps/developer?id=Kiwi,+Inc." target="_android">Kiwi, Inc.</a> has five of the top 25 grossing games on Google Play, including <a href="https://play.google.com/store/apps/details?id=com.kiwi.shipwrecked" target="_android">Shipwrecked: Lost Island</a>, <a href="https://play.google.com/store/apps/details?id=com.kiwi.monsterpark" target="_android">Monsterama Park</a>, and <a href="https://play.google.com/store/apps/details?id=com.kiwi.mysteryestate" target="_android">Hidden Object: Mystery Estate</a>. Hear how Google Play helped them double revenue every six months with features like instant updates, staged rollouts, and more.</p>
+ </div>
+ <iframe style="float:left;
+ margin-right:24px;
+ margin-top:14px;" width="700" height="394" src=
+ "http://www.youtube.com/embed/WWArLD6nqrk?HD=1;rel=0;origin=developer.android.com;" frameborder="0" allowfullscreen>
+ </iframe>
+ </div>
+</div>
<div style="background: #F0F0F0;
border-top: 1px solid #DDD;
padding: 0px 0 24px 0;
diff --git a/docs/html/google/gcm/client.jd b/docs/html/google/gcm/client.jd
index ee764ef..42cebfc 100644
--- a/docs/html/google/gcm/client.jd
+++ b/docs/html/google/gcm/client.jd
@@ -75,7 +75,7 @@
{@code dependency} section of your application's {@code build.gradle} file:</p>
<pre>dependencies {
- compile: "com.google.android.gms:play-services:3.1.+"
+ compile "com.google.android.gms:play-services:3.1.+"
}
</pre>
diff --git a/docs/html/google/gcm/gs.jd b/docs/html/google/gcm/gs.jd
index 8bc1936..d937955 100644
--- a/docs/html/google/gcm/gs.jd
+++ b/docs/html/google/gcm/gs.jd
@@ -64,14 +64,10 @@
<li>Under <strong>Public API access</strong>, click <strong>Create new key</strong>.</li>
-<li>In the <strong>Create a new key</strong> dialog, click <strong>Android key</strong>.</li>
+<li>In the <strong>Create a new key</strong> dialog, click <strong>Server key</strong>.</li>
-<li>In the resulting configuration dialog, supply one SHA1 fingerprint and
-the package name for your app, separated by a semicolon. For example,
-{@code 45:B5:E4:6F:36:AD:0A:98:94:B4:02:66:2B:12:17:F2:56:26:A0:E0;com.myexample}.
-<p>To get the value for the SHA1 fingerprint, follow the instructions in the
-<a href="http://developers.google.com/console/help/new/#installedapplications">console
-help</a>.</p></li>
+<li>In the resulting configuration dialog, supply your server's IP address. For testing
+purposes, you can use {@code 0.0.0.0/0}.</p></li>
<li>Click <strong>Create</strong>.</li>
<li>In the refreshed page, copy the
@@ -102,4 +98,3 @@
<li>Write your client app. This is the GCM-enabled Android application that runs
on a device. See <a href="client.html">Implementing GCM Client</a> for more information.</li>
</ol>
-
diff --git a/docs/html/google/gcm/server.jd b/docs/html/google/gcm/server.jd
index 7ba1bd5..ccd1267 100644
--- a/docs/html/google/gcm/server.jd
+++ b/docs/html/google/gcm/server.jd
@@ -120,7 +120,6 @@
<li>Able to store the API key and client registration IDs. The
API key is included in the header of POST requests that send
messages.</li>
- <li>Able to store the API key and client registration IDs.</li>
<li>Able to generate message IDs to uniquely identify each message it sends.</li>
</ul>
diff --git a/docs/html/guide/topics/resources/runtime-changes.jd b/docs/html/guide/topics/resources/runtime-changes.jd
index 45a548a..d074873 100644
--- a/docs/html/guide/topics/resources/runtime-changes.jd
+++ b/docs/html/guide/topics/resources/runtime-changes.jd
@@ -53,7 +53,7 @@
<ol type="a">
<li><a href="#RetainingAnObject">Retain an object during a configuration change</a>
<p>Allow your activity to restart when a configuration changes, but carry a stateful
-{@link java.lang.Object} to the new instance of your activity.</p>
+object to the new instance of your activity.</p>
</li>
<li><a href="#HandlingTheChange">Handle the configuration change yourself</a>
@@ -73,40 +73,53 @@
android.app.Activity#onSaveInstanceState(Bundle) onSaveInstanceState()} callback—it is not
designed to carry large objects (such as bitmaps) and the data within it must be serialized then
deserialized, which can consume a lot of memory and make the configuration change slow. In such a
-situation, you can alleviate the burden of reinitializing your activity by retaining a stateful
-{@link java.lang.Object} when your activity is restarted due to a configuration change.</p>
+situation, you can alleviate the burden of reinitializing your activity by retaining a {@link
+android.app.Fragment} when your activity is restarted due to a configuration change. This fragment
+can contain references to stateful objects that you want to retain.</p>
-<p>To retain an object during a runtime configuration change:</p>
+<p>When the Android system shuts down your activity due to a configuration change, the fragments
+of your activity that you have marked to retain are not destroyed. You can add such fragments to
+your activity to preserve stateful objects.</p>
+
+<p>To retain stateful objects in a fragment during a runtime configuration change:</p>
+
<ol>
- <li>Override the {@link android.app.Activity#onRetainNonConfigurationInstance()} method to return
-the object you would like to retain.</li>
- <li>When your activity is created again, call {@link
-android.app.Activity#getLastNonConfigurationInstance()} to recover your object.</li>
+ <li>Extend the {@link android.app.Fragment} class and declare references to your stateful
+ objects.</li>
+ <li>Call {@link android.app.Fragment#setRetainInstance(boolean)} when the fragment is created.
+ </li>
+ <li>Add the fragment to your activity.</li>
+ <li>Use {@link android.app.FragmentManager} to retrieve the fragment when the activity is
+ restarted.</li>
</ol>
-<p>When the Android system shuts down your activity due to a configuration change, it calls {@link
-android.app.Activity#onRetainNonConfigurationInstance()} between the {@link
-android.app.Activity#onStop()} and {@link android.app.Activity#onDestroy()} callbacks. In your
-implementation of {@link android.app.Activity#onRetainNonConfigurationInstance()}, you can return
-any {@link java.lang.Object} that you need in order to efficiently restore your state after the
-configuration change.</p>
-
-<p>A scenario in which this can be valuable is if your application loads a lot of data from the
-web. If the user changes the orientation of the device and the activity restarts, your application
-must re-fetch the data, which could be slow. What you can do instead is implement
-{@link android.app.Activity#onRetainNonConfigurationInstance()} to return an object carrying your
-data and then retrieve the data when your activity starts again with {@link
-android.app.Activity#getLastNonConfigurationInstance()}. For example:</p>
+<p>For example, define your fragment as follows:</p>
<pre>
-@Override
-public Object onRetainNonConfigurationInstance() {
- final MyDataObject data = collectMyLoadedData();
- return data;
+public class RetainedFragment extends Fragment {
+
+ // data object we want to retain
+ private MyDataObject data;
+
+ // this method is only called once for this fragment
+ @Override
+ public void onCreate(Bundle savedInstanceState) {
+ super.onCreate(savedInstanceState);
+ // retain this fragment
+ setRetainInstance(true);
+ }
+
+ public void setData(MyDataObject data) {
+ this.data = data;
+ }
+
+ public MyDataObject getData() {
+ return data;
+ }
}
</pre>
-<p class="caution"><strong>Caution:</strong> While you can return any object, you
+<p class="caution"><strong>Caution:</strong> While you can store any object, you
should never pass an object that is tied to the {@link android.app.Activity}, such as a {@link
android.graphics.drawable.Drawable}, an {@link android.widget.Adapter}, a {@link android.view.View}
or any other object that's associated with a {@link android.content.Context}. If you do, it will
@@ -114,26 +127,51 @@
means that your application maintains a hold on them and they cannot be garbage-collected, so
lots of memory can be lost.)</p>
-<p>Then retrieve the data when your activity starts again:</p>
+<p>Then use {@link android.app.FragmentManager} to add the fragment to the activity.
+You can obtain the data object from the fragment when the activity starts again during runtime
+configuration changes. For example, define your activity as follows:</p>
<pre>
-@Override
-public void onCreate(Bundle savedInstanceState) {
- super.onCreate(savedInstanceState);
- setContentView(R.layout.main);
+public class MyActivity extends Activity {
- final MyDataObject data = (MyDataObject) getLastNonConfigurationInstance();
- if (data == null) {
- data = loadMyData();
+ private RetainedFragment dataFragment;
+
+ @Override
+ public void onCreate(Bundle savedInstanceState) {
+ super.onCreate(savedInstanceState);
+ setContentView(R.layout.main);
+
+ // find the retained fragment on activity restarts
+ FragmentManager fm = getFragmentManager();
+ dataFragment = (DataFragment) fm.findFragmentByTag(“data”);
+
+ // create the fragment and data the first time
+ if (dataFragment == null) {
+ // add the fragment
+ dataFragment = new DataFragment();
+ fm.beginTransaction().add(dataFragment, “data”).commit();
+ // load the data from the web
+ dataFragment.setData(loadMyData());
+ }
+
+ // the data is available in dataFragment.getData()
+ ...
}
- ...
+
+ @Override
+ public void onDestroy() {
+ super.onDestroy();
+ // store the data in the fragment
+ dataFragment.setData(collectMyLoadedData());
+ }
}
</pre>
-<p>In this case, {@link android.app.Activity#getLastNonConfigurationInstance()} returns the data
-saved by {@link android.app.Activity#onRetainNonConfigurationInstance()}. If {@code data} is null
-(which happens when the activity starts due to any reason other than a configuration change) then
-this code loads the data object from the original source.</p>
+<p>In this example, {@link android.app.Activity#onCreate(Bundle) onCreate()} adds a fragment
+or restores a reference to it. {@link android.app.Activity#onCreate(Bundle) onCreate()} also
+stores the stateful object inside the fragment instance.
+{@link android.app.Activity#onDestroy() onDestroy()} updates the stateful object inside the
+retained fragment instance.</p>
diff --git a/docs/html/images/video-kiwi.jpg b/docs/html/images/video-kiwi.jpg
new file mode 100644
index 0000000..1c1146c
--- /dev/null
+++ b/docs/html/images/video-kiwi.jpg
Binary files differ
diff --git a/docs/html/index.jd b/docs/html/index.jd
index 191e0fb..d976c1e 100644
--- a/docs/html/index.jd
+++ b/docs/html/index.jd
@@ -18,6 +18,52 @@
<!-- set explicit widths as needed to prevent overflow issues -->
<li class="item carousel-home">
+ <div class="content-left col-11" style="padding-top:65px;">
+ <script src="//ajax.googleapis.com/ajax/libs/swfobject/2.2/swfobject.js"></script>
+ <div style="box-shadow: 3px 10px 18px 1px #999;width:600px;height:336px">
+ <div id="ytapiplayer">
+ <a href="http://www.youtube.com/watch?v=WWArLD6nqrk"><img width=600 src="{@docRoot}images/video-kiwi.jpg"></a><!--You need Flash player 8+ and JavaScript enabled to view this video. -->
+ </div>
+ <script type="text/javascript">
+ var params = { allowScriptAccess: "always" };
+ var atts = { id: "ytapiplayer" };
+ swfobject.embedSWF("//www.youtube.com/v/WWArLD6nqrk?enablejsapi=1&playerapiid=ytplayer&version=3&HD=1;rel=0;showinfo=0;modestbranding;origin=developer.android.com;autohide=1",
+ "ytapiplayer", "600", "336", "8", null, null, params, atts);
+
+ // Callback used to pause/resume carousel based on video state
+ function onytplayerStateChange(newState) {
+ var isPaused = $("#pauseButton").hasClass("paused");
+ if ((newState == 1) || (newState == 3)) {
+ // if playing or buffering, pause the carousel
+ if (!isPaused) {
+ $("#pauseButton").click();
+ }
+ } else {
+ // otherwise, make sure carousel is running
+ if (isPaused) {
+ $("#pauseButton").click();
+ }
+ }
+ }
+
+ // Callback received when YouTube player loads to setup callback (above)
+ function onYouTubePlayerReady(playerId) {
+ var ytplayer = document.getElementById("ytapiplayer");
+ ytplayer.addEventListener("onStateChange", "onytplayerStateChange");
+ }
+
+ </script>
+ </div>
+ </div>
+ <div class="content-right col-4">
+ <h1 style="white-space:nowrap;line-height:1.2em;">Developer Story: <br />Kiwi, Inc.</h1>
+ <p>Game developer Kiwi has five of the top 25 grossing titles on Google Play. Hear how Google Play
+ has helped them double revenue every six months.</p>
+ <p><a href="{@docRoot}distribute/googleplay/spotlight/index.html" class="button">Watch more videos </a></p>
+ </div>
+ </li>
+
+ <li class="item carousel-home">
<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;">
diff --git a/docs/html/tools/help/proguard.jd b/docs/html/tools/help/proguard.jd
index 3ba7db2..aa9a0bc 100644
--- a/docs/html/tools/help/proguard.jd
+++ b/docs/html/tools/help/proguard.jd
@@ -25,11 +25,14 @@
<h2>See also</h2>
<ol>
- <li><a href="http://proguard.sourceforge.net/manual/introduction.html">ProGuard
- Manual »</a></li>
-
- <li><a href="http://proguard.sourceforge.net/manual/retrace/introduction.html">ProGuard
- ReTrace Manual »</a></li>
+ <li>
+ <a href="http://stuff.mit.edu/afs/sipb/project/android/sdk/android-sdk-linux/tools/proguard/docs/index.html#manual/introduction.html">ProGuard
+ Manual »</a>
+ </li>
+ <li>
+ <a href="http://stuff.mit.edu/afs/sipb/project/android/sdk/android-sdk-linux/tools/proguard/docs/index.html#manual/retrace/introduction.html">ProGuard
+ ReTrace Manual »</a>
+ </li>
</ol>
</div>
</div>
@@ -146,14 +149,14 @@
</pre>
<p>There are many options and considerations when using the <code>-keep</code> option, so it is
- highly recommended that you read the <a href="http://proguard.sourceforge.net/manual/introduction.html">ProGuard
- Manual</a> for more information about customizing your configuration file. The <a href=
- "http://proguard.sourceforge.net/manual/usage.html#keepoverview">Overview of Keep options</a> and
- <a href="http://proguard.sourceforge.net/index.html#/manual/examples.html">Examples section</a>
- are particularly helpful. The <a href=
- "http://proguard.sourceforge.net/manual/troubleshooting.html">Troubleshooting</a> section of the
- ProGuard Manual outlines other common problems you might encounter when your code gets stripped
- away.</p>
+ highly recommended that you read the
+ <a href="http://stuff.mit.edu/afs/sipb/project/android/sdk/android-sdk-linux/tools/proguard/docs/index.html#manual/introduction.html">ProGuard
+ Manual</a> for more information about customizing your configuration file. The
+ <em>Overview of Keep options</em> and <em>Examples</em> sections are particularly helpful.
+ The <a href=
+ "http://stuff.mit.edu/afs/sipb/project/android/sdk/android-sdk-linux/tools/proguard/docs/index.html#manual/troubleshooting.html">Troubleshooting
+ </a> section of the ProGuard Manual outlines other common problems you might encounter
+ when your code gets stripped away.</p>
<h2 id="decoding">Decoding Obfuscated Stack Traces</h2>
@@ -192,4 +195,4 @@
<p>How you save the <code>mapping.txt</code> file is your decision. For example, you can rename them to
include a version or build number, or you can version control them along with your source
- code.</p>
\ No newline at end of file
+ code.</p>
diff --git a/docs/html/training/animation/screen-slide.jd b/docs/html/training/animation/screen-slide.jd
index 07d779f..a68d475 100644
--- a/docs/html/training/animation/screen-slide.jd
+++ b/docs/html/training/animation/screen-slide.jd
@@ -63,22 +63,23 @@
contains a text view to display some text:
<pre>
-<com.example.android.animationsdemo.ScrollView
- xmlns:android="http://schemas.android.com/apk/res/android"
- android:id="@+id/content"
+<!-- fragment_screen_slide_page.xml -->
+<ScrollView xmlns:android="http://schemas.android.com/apk/res/android"
+ android:id="@+id/content"
android:layout_width="match_parent"
- android:layout_height="match_parent">
+ android:layout_height="match_parent" >
- <TextView style="?android:textAppearanceMedium"
- android:padding="16dp"
- android:lineSpacingMultiplier="1.2"
- android:layout_width="match_parent"
- android:layout_height="wrap_content"
- android:text="@string/lorem_ipsum" />
-
-</com.example.android.animationsdemo.ScrollView>
+ <TextView style="?android:textAppearanceMedium"
+ android:padding="16dp"
+ android:lineSpacingMultiplier="1.2"
+ android:layout_width="match_parent"
+ android:layout_height="wrap_content"
+ android:text="@string/lorem_ipsum" />
+</ScrollView>
</pre>
+ <p>Define also a string for the contents of the fragment.</p>
+
<h2 id="fragment">Create the Fragment</h2>
<p>Create a {@link android.support.v4.app.Fragment} class that returns the layout
that you just created in the {@link android.app.Fragment#onCreateView onCreateView()}
@@ -87,6 +88,8 @@
<pre>
+import android.support.v4.app.Fragment;
+...
public class ScreenSlidePageFragment extends Fragment {
@Override
@@ -111,6 +114,7 @@
<p>To begin, create a layout that contains a {@link android.support.v4.view.ViewPager}:</p>
<pre>
+<!-- activity_screen_slide.xml -->
<android.support.v4.view.ViewPager
xmlns:android="http://schemas.android.com/apk/res/android"
android:id="@+id/pager"
@@ -133,6 +137,9 @@
</ul>
<pre>
+import android.support.v4.app.Fragment;
+import android.support.v4.app.FragmentManager;
+...
public class ScreenSlidePagerActivity extends FragmentActivity {
/**
* The number of pages (wizard steps) to show in this demo.
@@ -153,11 +160,11 @@
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
- setContentView(R.layout.activity_screen_slide_pager);
+ setContentView(R.layout.activity_screen_slide);
// Instantiate a ViewPager and a PagerAdapter.
mPager = (ViewPager) findViewById(R.id.pager);
- mPagerAdapter = new ScreenSlidePagerAdapter(getFragmentManager());
+ mPagerAdapter = new ScreenSlidePagerAdapter(getSupportFragmentManager());
mPager.setAdapter(mPagerAdapter);
}
@@ -224,9 +231,9 @@
<code>ZoomOutPageTransformer</code>, you can set your custom animations
like this:</p>
<pre>
-ViewPager pager = (ViewPager) findViewById(R.id.pager);
+ViewPager mPager = (ViewPager) findViewById(R.id.pager);
...
-pager.setPageTransformer(true, new ZoomOutPageTransformer());
+mPager.setPageTransformer(true, new ZoomOutPageTransformer());
</pre>
@@ -257,8 +264,8 @@
<pre>
public class ZoomOutPageTransformer implements ViewPager.PageTransformer {
- private static float MIN_SCALE = 0.85f;
- private static float MIN_ALPHA = 0.5f;
+ private static final float MIN_SCALE = 0.85f;
+ private static final float MIN_ALPHA = 0.5f;
public void transformPage(View view, float position) {
int pageWidth = view.getWidth();
@@ -332,7 +339,7 @@
<pre>
public class DepthPageTransformer implements ViewPager.PageTransformer {
- private static float MIN_SCALE = 0.75f;
+ private static final float MIN_SCALE = 0.75f;
public void transformPage(View view, float position) {
int pageWidth = view.getWidth();
