diff options
Diffstat (limited to 'docs')
36 files changed, 3502 insertions, 401 deletions
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 545807e..2548128 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -71,6 +71,9 @@ <li><a href="<?cs var:toroot ?>guide/topics/ui/menus.html"> <span class="en">Creating Menus</span> </a></li> + <li><a href="<?cs var:toroot ?>guide/topics/ui/actionbar.html"> + <span class="en">Using the Action Bar</span> + </a> <span class="new">new!</span></li> <li><a href="<?cs var:toroot ?>guide/topics/ui/dialogs.html"> <span class="en">Creating Dialogs</span> </a></li> @@ -196,6 +199,9 @@ </li> </ul> <ul> + <li><a href="<?cs var:toroot ?>guide/topics/fragments/index.html"> + <span class="en">Fragments</span> + </a> <span class="new">new!</span></li> <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/topics/graphics/index.html"> <span class="en">Graphics</span> diff --git a/docs/html/guide/topics/fragments/index.jd b/docs/html/guide/topics/fragments/index.jd new file mode 100644 index 0000000..766146e --- /dev/null +++ b/docs/html/guide/topics/fragments/index.jd @@ -0,0 +1,648 @@ +page.title=Fragments +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Quickview</h2> + <ul> + <li>Decompose application functionality and UI into reusable modules</li> + <li>Add multiple fragments to a screen to avoid switching activities</li> + <li>Fragments have their own lifecycle, state, and back stack</li> + <li>Fragments require API Level HONEYCOMB or greater</li> + </ul> + + <h2>In this document</h2> + <ol> + <li><a href="#Creating">Creating fragments</a></li> + <li><a href="#Adding">Adding a fragment to an activity</a></li> + <li><a href="#Managing">Managing fragments</a></li> + <li><a href="#Lifecycle">Handling the lifecycle</a></li> + <li><a href="#Integrating">Integrating with the activity</a></li> + <li><a href="#Menus">Adding menus</a></li> + </ol> + + <h2>Key classes</h2> + <ol> + <li>{@link android.app.Fragment}</li> + <li>{@link android.app.FragmentManager}</li> + <li>{@link android.app.FragmentTransaction}</li> + </ol> + + <!-- + <h2>Related samples</h2> + <ol> + <li><a +href="{@docRoot}resources/samples/NotePad/index.html">NotePad</a></li> + </ol> + --> +</div> +</div> + + +<p>An {@link android.app.Activity} is always the window in which users interact with your +application, but a {@link android.app.Fragment} can be responsible for distinct operations and UI +that's embedded in an activity. So, when using fragments, your activity becomes more like a +container for fragments that define the activity's behavior and UI.</p> + +<p>Fragments have their own +set of lifecylce callback methods and recieve their own user input events. A fragment must always be +embedded in an activity and the fragment's lifecycle is directly affected by the activity's +lifecycle. For example, when the activity is stopped, so are all fragments in it, and when +the activity is destroyed, so are all fragments. However, while an activity +is active (in the "resumed" lifecycle stage), you can manipulate the lifecycle of each fragment +independently. For example, you can add and remove fragments while the activity is active and you +can add each fragment to a back stack within the activity—each back stack entry in the +activity is actually a record of a "transaction" that occurred with the activity's fragments, so +that the user can reverse the transaction with the BACK key (this is discussed more later).</p> + +<div class="figure" style="width:314px"> +<img src="{@docRoot}images/fragment_lifecycle.png" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> The lifecycle of a fragment (while its +activity is running).</p> +</div> + +<p>Android introduced fragments in Android X.X (API Level HONEYCOMB), with the primary intention to +support more dynamic and flexible UI designs on large screen devices, such as tablets. Because a +tablet has a much larger screen than a mobile phone, there's more room to interchange UI +elements. Fragments allow that without the need for you to start a new activity or manage complex +changes to the view hierarchy. By dividing the layout of an activity into fragments, the code +that defines your activity becomes more modular and interchangable, allowing you to modify the +activity's appearance at runtime and for different types of screens.</p> + +<p>For example, a news application can use one fragment to show a list of articles on the +left and another fragment to display an article on the right—both fragments appear in one +activity, side by side, and each fragment has its own set of lifecycle callback methods and handle +their own user input events. Thus, instead using one activity to select an article and another +activity to read the article, the user can select an article and read it all within the same +activity.</p> + +<!-- ** TODO: Save this for later or move it down in the doc so the intro isn't overwhelming ** + +<p>A fragment can be a modular and reusable component in your application. That is, because +the fragment defines its own behavior using its own set of lifecycle callbacks, you can +include one fragment in multiple activities. This also enables you to create one version of your +application for multiple screen sizes. For instance, on an extra large screen (<em>xlarge</em> +screen configuration), you can embed two or more fragments in one activity, but on a normal-sized +screen (<em>normal</em> screen configuration), you can embed just one fragment in an activity and +then start other activities in order to display the other fragments.</p> +--> + +<p>When you use a fragment as a part of your layout, it technically lives within a {@link +android.view.View} of the activity's layout and defines its own layout of views. You can insert a +fragment into your activity layout by declaring the fragment in the activity's XML layout file, as +a {@code <fragment>} element, or from your application code by adding it to an existing {@link +android.view.View}. However, a fragment is not required to be a part of the activity +layout—you might use a fragment as an invisible worker for the activity (more about that +later).</p> + +<p>The rest of this document describes how to build your application to use fragments, including +how fragments can contribute to the activity options menu and action bar, create context menus, +maintain their state when added to the activity's back stack, and more.</p> + + + +<h2 id="Creating">Creating a Fragment</h2> + +<p>An implementation of the {@link android.app.Fragment} class contains code that looks a lot like +the code in an {@link android.app.Activity}. In fact, if you're +converting an existing Android application to use fragments, you'll move code +from your {@link android.app.Activity} implementation into your {@link android.app.Fragment} class +implementation, and into some of the same callback methods. A fragment contains callback methods +similar to an activity, such as {@link android.app.Fragment#onCreate onCreate()}, {@link +android.app.Fragment#onStart onStart()}, {@link android.app.Fragment#onPause onPause()}, and {@link +android.app.Fragment#onStop onStop()}.</p> + +<p>If you're creating a fragment to be a modular piece of an activity UI, then your +implementation of {@link android.app.Fragment} should include most of the same lifecycle +callback methods traditionally implemented by the activity to initialize elements of the UI and +save and restore state information. Usually, you'll want to implement the following methods:</p> + +<dl> + <dt>{@link android.app.Fragment#onCreate onCreate()}</dt> + <dd>The system calls this when creating the fragment. Within your implementation, you should +initialize the essential components of the fragment that should be retained when the fragment is +paused or stopped.</dd> + <dt>{@link android.app.Fragment#onCreateView onCreateView()}</dt> + <dd>The system calls this when it's time for the fragment to draw its user interface for the +first time. To draw a UI for your fragment, you must return a {@link android.view.View} from this +method that is the root of your fragment's layout. You can return null if the fragment does not +provide a UI.</dd> + <dt>{@link android.app.Activity#onPause onPause()}</dt> + <dd>The system calls this method as the first indication that the user is leaving the +fragment (though it does not always mean the fragment is being destroyed). This is usually where you +should commit any changes that should be persisted beyond the current user session (because +the user might not come back).</dd> +</dl> + +<p>Most applications should implement at least these three methods for each fragment, but there are +several other lifecycle callback methods that you should also use in order to provide the best +user experience when switching fragments and when the activity is paused or stopped. All of the +lifecycle callback methods are discussed more later, in +the section about <a href="#Lifecycle">Handling the Lifecycle</a>.</p> + + +<p>There are also a few different subclasses of {@link android.app.Fragment} that you might want +to use:</p> + +<dl> + <dt>{@link android.app.DialogFragment}</dt> + <dd>Displays a floating dialog. Using this class to create a dialog is a good alternative to using +the dialog helper methods in the {@link android.app.Activity} class, because the dialog can be +incorporated into the fragment back stack managed by the activity.</dd> + + <dt>{@link android.app.ListFragment}</dt> + <dd>Displays a list of items that are managed by an adapter (such as a {@link +android.widget.SimpleCursorAdapter}), similar to {@link android.app.ListActivity}. Provides methods +for managing a list, such as the {@link +android.app.ListFragment#onListItemClick(ListView,View,int,long) onListItemClick()} callback to +handle click events on list items.</dd> + + <dt>{@link android.preference.PreferenceFragment}</dt> + <dd>Displays a hierarchy of {@link android.preference.Preference} objects as a list, similar to +{@link android.preference.PreferenceActivity}. </dd> +</dl> + +<p>However, subclassing the standard {@link android.app.Fragment} class is most common, if +you're not creating a dialog, a list, or displaying preferences.</p> + + +<h3 id="UI">Providing a user interface</h3> + +<p>To provide a UI layout for a fragment, you must implement +the {@link android.app.Fragment#onCreateView onCreateView()} +callback method in your {@link android.app.Fragment} (unless your fragment is a subclass of +{@link android.app.ListFragment}, which returns a {@link android.widget.ListView} from this method +by default). The Android system calls {@link android.app.Fragment#onCreateView onCreateView()} when +it's time for the fragment to draw its layout. Your implementation of this method must return a +{@link android.view.View} that is the root of your fragment's layout.</p> + +<p>The easiest way to provide your layout is to inflate it from a <a +href="{@docRoot}guide/topics/resources/layout-resource.html">layout resource</a>. To help you +inflate a layout, the {@link android.app.Fragment#onCreateView onCreateView()} method passes a +{@link android.view.LayoutInflater} that you can use to get your layout. For example, here's a +simple subclass of {@link android.app.Fragment} that contains an implementation of {@link +android.app.Fragment#onCreateView onCreateView()} that loads the fragment's layout from a +resource:</p> + +<pre> +public static class SimpleFragment extends Fragment { + @Override + public View onCreateView(LayoutInflater inflater, ViewGroup container, + Bundle savedInstanceState) { + // Inflate the layout for this fragment + return inflater.inflate(R.layout.simple_fragment, container, false); + } +} +</pre> + +<p>The {@link android.view.LayoutInflater#inflate(int,ViewGroup,boolean) inflate()} method takes +three arguments:</p> +<ul> + <li>The resource ID of the layout you want to inflate</li> + <li>The {@link android.view.ViewGroup} to be the parent of the +inflated layout (supplying this is important in order to apply layout parameters from the parent +view)</li> + <li>And a boolean indicating whether the inflated layout should be attached to the {@link +android.view.ViewGroup} (from the second parameter) during inflation (in this case, this +is false because the system is already going to insert the layout into the appropriate parent +view—doing otherwise would create a redundant view group in the final layout)</li> +</ul> + +<p>The {@code container} parameter passed to {@link android.app.Fragment#onCreateView +onCreateView()} provides the parent {@link android.view.ViewGroup} in which your fragment layout +will be inserted, which you can use to generate layout parameters for your +fragment layout. The {@code savedInstanceState} parameter is a {@link android.os.Bundle} that +provides data about the previous instance of the fragment, if the fragment is being resumed +(restoring state is discussed more in the section about <a href="#Lifecycle">Handling the +Lifecycle</a>.</p> + + +<h3 id="Adding">Adding a Fragment to an Activity</h3> + +<p>Each fragment is embedded into the layout of its container activity as a part of the overall view +hierarchy, whether or not it actually provides a UI. If a fragment is not embedded into the activity +layout, then it is never created (it does not receive any lifecycle callbacks). There are two ways +you can add a fragment to the activity layout:</p> + +<ul> + <li><b>Declare the fragment inside the activity's layout XML file.</b> +<p>In this case, you can +specify layout properties for the fragment as if it were a view itself and the fragment's layout +fills that space. For example:</p> +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:orientation="horizontal" + android:layout_width="match_parent" + android:layout_height="match_parent"> + <fragment android:name="com.example.news.ArticleListFragment" + android:id="@+id/list" + android:layout_weight="1" + android:layout_width="0dp" + android:layout_height="match_parent" /> + <fragment android:name="com.example.news.ArticleReaderFragment" + android:id="@+id/viewer" + android:layout_weight="2" + android:layout_width="0dp" + android:layout_height="match_parent" /> +</LinearLayout> +</pre> + <p>The {@code <fragment>} element uses the {@code android:name} attribute to specify the +{@link android.app.Fragment} class to instantiate and insert into the layout. When the activity +layout is created, the system instantiates each fragment in the layout and calls its {@link +android.app.Fragment#onCreateView onCreateView()} method in order to retrieve the fragment's +layout. The {@link android.view.View} object returned by {@link +android.app.Fragment#onCreateView onCreateView()} is then +placed directly in the activity layout in place of the {@code <fragment>} element.</p> + +<div class="note"> + <p><strong>Note:</strong> Each fragment requires a unique identifier that +the system can use to restore the fragment if the activity is restarted (and which you can use to +perform fragment transactions). There are three ways to identify a fragment:</p> + <ul> + <li>Supply the {@code android:id} attribute with a unique ID, in the {@code +<fragment>}</li> + <li>Supply the {@code android:tag} attribute with a unique string ID, in the {@code + <fragment>}</li> + <li>If neither of the previous two are provided, the system uses the ID of the container + view.</li> + </ul> +</div> + </li> + + <li><b>Or, programmatically add the fragment to an existing {@link android.view.ViewGroup}.</b> +<p>At any time while your activity is running (in the "resumed" state), you can add (and remove) +fragments to your activity layout. You simply need to specify a {@link android.view.ViewGroup} in +which to place the fragment.</p> + <p>To make any fragment transactions in your activity (such as add, remove, or replace a +fragment), you must use APIs from {@link android.app.FragmentTransaction}. You can get an instance +of {@link android.app.FragmentTransaction} from your {@link android.app.Activity} using {@link +android.app.Activity#openFragmentTransaction()}. You can then add a fragment using the {@link +android.app.FragmentTransaction#add add()} method, specifying the fragment to add and the view in +which to insert it. For example:</p> +<pre> +MyFragment fragment = new MyFragment(); +openFragmentTransaction().add(R.id.fragment_container, fragment).commit(); +</pre> + <p>The first argument passed to {@link android.app.FragmentTransaction#add add()} +is the {@link android.view.ViewGroup} in which the fragment should be placed, specified by +resource ID, and the second parameter is the fragment object.</p> + <p>Once you've made your changes using +{@link android.app.FragmentTransaction}, you must +call {@link android.app.FragmentTransaction#commit} in order for the changes to take effect.</p> + </li> +</ul> + + +<h3 id="Example1">Example: simple fragments</h3> + +<p>In the last couple sections, you saw how to declare layout for a fragment and add it to an +activity. What follows is some code that brings it all together, like a "Hello World" for +fragments.</p> + +<p>First, here's a layout file for a fragment:</p> +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:orientation="vertical" + android:layout_width="match_parent" + android:layout_height="match_parent" > +<TextView + android:layout_width="match_parent" + android:layout_height="wrap_content" + android:text="@string/hello" /> +<TextView + android:layout_width="match_parent" + android:layout_height="wrap_content" + android:text="@string/hello" /> +</LinearLayout> +</pre> + +<p>With that file saved at {@code res/layout/simple_fragment.xml}, the following {@link +android.app.Fragment} uses it for its layout:</p> + +<pre> +public static class SimpleFragment extends Fragment { + @Override + public View onCreateView(LayoutInflater inflater, ViewGroup container, + Bundle savedInstanceState) { + // Inflate the layout for this fragment + return inflater.inflate(R.layout.simple_fragment, null); + } +} +</pre> + +<p>And the following layout for an activity applies the fragment twice, side by side:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:orientation="horizontal" + android:layout_width="match_parent" + android:layout_height="match_parent"> + <fragment android:name="com.example.SimpleFragment" + android:id="@+id/list" + android:layout_weight="1" + android:layout_width="0dp" + android:layout_height="match_parent" /> + <fragment android:name="com.example.SimpleFragment" + android:id="@+id/viewer" + android:layout_weight="1" + android:layout_width="0dp" + android:layout_height="match_parent" /> +</LinearLayout> +</pre> + +<p>That's it. When an activity applies the previous layout as its content, the {@code +SimpleFragment} class is instantiated for each occurence in the layout, applying the fragment +layout when it receives the call to {@link android.app.Fragment#onCreateView onCreateView()}.</p> + +<p>Although the fragment in this example implements only the {@link +android.app.Fragment#onCreateView onCreateView()} callback, there are several other lifecycle +callback methods that you should implement in your application. For example, {@link +android.app.Fragment#onCreate onCreate()}, {@link android.app.Fragment#onPause onPause()}, {@link +android.app.Fragment#onStop onStop()} and others that coincide with the fragment's lifecycle.</p> + + + +<h2 id="Managing">Managing Fragments</h2> + +<p>A useful feature of fragments is the ability to add, remove, replace, and perform other +operations on a fragment as the user interacts with the activity, alowing for more rich user +experiences without changing activities. In order to perform these operations, you must use {@link +android.app.FragmentTransaction} to perform fragment "transactions." You can acquire {@link +android.app.FragmentTransaction} from your activity with {@link +android.app.Activity#openFragmentTransaction}.</p> + +<p>Common transactions you can perform with fragments include:</p> + +<dl> + <dt>{@link android.app.FragmentTransaction#add add()}</dt> + <dd>Add a {@link android.app.Fragment} to the {@link android.app.Activity} layout.</dd> + <dt>{@link android.app.FragmentTransaction#remove remove()}</dt> + <dd>Remove a {@link android.app.Fragment} from the {@link android.app.Activity} layout.</dd> + <dt>{@link android.app.FragmentTransaction#replace replace()}</dt> + <dd>Replace an existing {@link android.app.Fragment} with another one.</dd> +</dl> + +<p>For every transaction (or set of transactions) you perform, you must call {@link +android.app.FragmentTransaction#commit} in order for the transactions made with {@link +android.app.FragmentTransaction} to be applied. Before you do, however, you can call {@link +android.app.FragmentTransaction#addToBackStack} to add the current fragment state to the +activity's back stack, so that the user can return to the previous fragment state with the BACK key. +For example, here's how a new fragment can replace another one, but keep the previous fragment +in the back stack:</p> + +<pre> +// Create new fragment +Fragment newFragment = new MyFragment(); +FragmentTransaction ft = openFragmentTransaction(); +// Replace and add to back stack +ft.replace(R.id.myfragment, newFragment); +ft.addToBackStack(null); +// Apply changes +ft.commit(); +</pre> + +<p>In this example, {@code newFragment} replaces whatever fragment is currently in the +layout container identified by the {@code R.id.myfragment} ID. By calling {@link +android.app.FragmentTransaction#addToBackStack addToBackStack()}, this transaction (the replace) is +saved to the activity's back stack so that the user can reverse this change and bring back the +previous fragment by pressing the BACK key.</p> + +<p>If you perform multiple transactions and call {@link +android.app.FragmentTransaction#addToBackStack addToBackStack()}, then all transactions performed +before {@link android.app.FragmentTransaction#commit} are added to the activity's back stack as a +single event and the BACK key will reverse them all together.</p> + + + +<h2 id="Lifecycle">Handling the Lifecycle</h2> + +<p>A fragment has a lifecycle that corresponds to the lifecycle of the activity in which it +resides. For example, a fragment has callback methods {@link +android.app.Fragment#onCreate onCreate()}, {@link android.app.Fragment#onStart onStart()}, {@link +android.app.Fragment#onPause onPause()}, {@link android.app.Fragment#onStop onStop()}, and more.</p> + +<p>The lifecycle of the activity directly affects the lifecycle of the fragment, such that each +lifecycle callback for the activity results in a similar callback for each fragment (for +example, when the activity receives {@link android.app.Activity#onPause}, each fragment receives +{@link android.app.Fragment#onPause}). However, the +fragment's lifecycle can also change independently—but only while the activity is +resumed (while it is in the foreground)—because you can dynamically +add, remove, and replace fragments without any change to the lifecycle of the activity.</p> + +<p>To accomodate backward navigation with the +BACK key, you can optionally maintain a back stack of fragment transactions, as described in the +previous section. So, if you +replace one fragment with another, the user can press the BACK key and view the previous +fragment. Additionally, each fragment can maintain its own state, such that +when the user navigates back to a previous fragment, the state of that fragment can be restored in +the same manner as the state of an activity is restored when it is stopped and restarted.</p> + +<p>Managing the lifecycle of a fragment is a lot like managing the lifecycle of an activity. A +fragment and an activity both have an "resumed," "paused," and "stopped" state, and they can both +retain their state using a {@link android.os.Bundle}. The only significant difference is that an +activity is placed into a the task's back stack by default (so that the user can navigate to +the previous activity with the BACK key), but a fragment is placed into the activity's back stack +only when you explicitly call {@link android.app.FragmentTransaction#addToBackStack(String) +addToBackStack()} before you {@link android.app.FragmentTransaction#commit()} a fragment +transaction.</p> + +<p>The order in which you perform transactions with {@link android.app.FragmentTransaction} doesn't +matter, except:</p> +<ul> + <li>You must call {@link android.app.FragmentTransaction#commit()} last</li> + <li>If you're adding multiple fragments to the same container, then the order in which +you add them determines the order they appear</li> +</ul> +<p>If you do not call {@link android.app.FragmentTransaction#addToBackStack(String) +addToBackStack()} when you perform a transaction that removes a fragment, then that fragment is +destroyed when the transaction is committed.</p> + + +<h3 id="CoordinatingWithTheActivity">Coordinating with the activity lifecycle</h3> + +<p>The lifecycle of an activity directly affects the lifecycle of a {@link android.app.Fragment} +embedded in that activity. The {@link android.app.Fragment} class has lifecycle callback +methods that match those in the {@link android.app.Activity} class.</p> + +<p>Fragments have a few extra lifecycle callbacks, however, that handle unique interaction with the +activity in order to perform actions such as build and destroy the fragment's UI. These additional +callback methods are:</p> + +<dl> + <dt>{@link android.app.Fragment#onAttach onAttach()}</dt> + <dd>Called when the fragment has been associated with the activity (the {@link +android.app.Activity} is passed in here).</dd> + <dt>{@link android.app.Fragment#onCreateView onCreateView()}</dt> + <dd>Called to create the view hierarchy associated with the fragment.</dd> + <dt>{@link android.app.Fragment#onActivityCreated onActivityCreated()}</dt> + <dd>Called when the activity's own {@link android.app.Activity#onCreate +onCreate()} has finished.</dd> + <dt>{@link android.app.Fragment#onDestroyView onDestroyView()}</dt> + <dd>Called when the view hierarchy associated with the fragment is being removed.</dd> + <dt>{@link android.app.Fragment#onDetach onDetach()}</dt> + <dd>Called when the fragment is being disassociated from the activity.</dd> +</dl> + +<p>The flow of a fragment's lifecycle, as it is affected by its container activity, is illustrated +by figure 3. In this figure, you can see how each successive state of the activity determines which +callback methods the fragment may receive. For example, when the activity has received +its {@link android.app.Activity#onCreate onCreate()} callback, the fragment receives no more +than the {@link android.app.Fragment#onActivityCreated onActivityCreated()} callback. However, +once the activity reaches the resumed state, you can freely add and remove fragments to the +activity, so the fragment lifecycle is no longer inhibitted by the state of the activity. Yet, +when the activity leaves the resumed state, the fragment again is pushed through its lifecycle by +the activity (unless you explicitly destroy the fragment sooner).</p> + + +<img src="{@docRoot}images/activity_fragment_lifecycle.png" alt=""/> +<p class="img-caption"><strong>Figure 3.</strong> The activity lifecycle's affect on the lifecycle +of a fragment.</p> + + +<h3 id="Integrating">Integrating with the Activity</h3> + +<p>Although a {@link android.app.Fragment} is implemented separate from an {@link +android.app.Activity} and can be used inside multiple activities, a fragment is directly tied to its +container activity and can access the Activity instance with {@link +android.app.Fragment#getActivity()}. So, a fragment can +easily perform tasks such as find a view in the activity:</p> + +<pre> +View listView = {@link android.app.Fragment#getActivity()}.{@link android.app.Activity#findViewById findViewById}(R.id.list); +</pre> + +<p>This makes it easy for your fragment to call public methods in the activity.</p> + +<p>Likewise, your activity can call public methods in the fragment when you have a reference to the +{@link android.app.Fragment}. You can acquire a reference to the fragment with {@link +android.app.Activity#findFragmentById findFragmentById()} and cast it to your implementation of +{@link android.app.Fragment}. For example:</p> + +<pre> +MyFragment fragment = (MyFragment) findFragmentById(R.id.myfragment); +fragment.refreshList(); +</pre> + + +<h4 id="Callbacks">Creating event callbacks to the activity</h4> + +<p>In some cases, you might need a fragment to share events with the activity. A good way to do that +is to define a callback interface inside the fragment and require that the host activity implement +it. When the activity receives a callback, it can share the information with other fragments in the layout as +necessary.</p> + +<p>For example, if a news application has two fragments in an activity—one to show a list of +articles (fragment A) and another to display an article (fragment B)—then fragment A must tell +the activity when a list item is selected so that it can tell fragment B to display the article. In +this case, the following interface is defined inside fragment A:</p> + +<pre> +public static class FragmentA extends ListFragment { + ... + // Container Activity must implement this interface + public interface SelectedCallback { + public void onArticleSelected(Uri articleUri); + } + ... +} +</pre> + +<p>Then the activity that hosts the fragment implements the {@code SelectedCallback} interface and +overrides {@code onArticleSelected()} to notify fragment B of the event from fragment A. To ensure +that the host activity implements this interface, fragment A's {@link +android.app.Fragment#onAttach onAttach()} callback method (called when +the fragment is added to the activity) instantiates an instance of {@code SelectedCallback} by +casting the {@link android.app.Activity} that is passed into {@link android.app.Fragment#onAttach +onAttach()}:</p> + +<pre> +public static class FragmentA extends ListFragment { + ... + @Override + public void onAttach(Activity activity) { + super.onAttach(activity); + try { + mCallback = (SelectedCallback) activity; + } catch (ClassCastException e) { + activity.finish(); + throw new ClassCastException(activity.toString() + " must implement SelectedCallback"); + } + } + ... +} +</pre> + +<p>If the activity has not implemented the interface, then a {@link java.lang.ClassCastException} is +thrown and the activity is shut down. On success, the {@code mCallback} member holds a reference to +the {@link android.app.Activity}, so that fragment A can share events with the activity by calling +methods defined by the {@code SelectedCallback} interface. For example, if fragment A is an +extension of {@link android.app.ListFragment}, each time +the user clicks a list item, the system calls {@link android.app.ListFragment#onListItemClick +onListItemClick()} in the fragment, which then calls {@code onArticleSelected()} to share +the event with the activity:</p> + +<pre> +public static class FragmentA extends ListFragment { + ... + @Override + public void onListItemClick(ListView l, View v, int position, long id) { + // Append the clicked item's row ID with the content provider Uri + Uri noteUri = ContentUris.{@link android.content.ContentUris#withAppendedId withAppendedId}(ArticleColumns.CONTENT_URI, id); + // Send the event and Uri to the host activity + mCallback.onArticleSelected(noteUri); + } + ... +} +</pre> + +<p>The {@code id} parameter passed to {@link +android.app.ListFragment#onListItemClick onListItemClick()} is the row ID of the clicked item, +which the activity (or other fragment) uses to fetch the article from the application's {@link +android.content.ContentProvider}.</p> + +<p><!--To see a complete implementation of this kind of callback interface, see the <a +href="{@docRoot}resources/samples/NotePad/index.html">NotePad sample</a>. -->More information about +using a content provider is available in the <a +href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> document.</p> + + + + + + +<h2 id="Menus">Adding Action Items to the Activity</h2> + +<p>Your fragments can contribute action items to the activity's <a +href="{@docRoot}guide/topics/ui/actionbar.html">action bar</a> (and menu items to the options menu) +using the callback methods +{@link android.app.Fragment#onCreateOptionsMenu(Menu,MenuInflater) onCreateOptionsMenu()}. In order +for this method to receive calls, however, you must call {@link +android.app.Fragment#setHasOptionsMenu(boolean) setHasOptionsMenu()} during the {@link +android.app.Fragment#onCreate(Bundle) onCreate()} callback in order to indicate that the fragment +would like to receive a call to {@link android.app.Fragment#onCreateOptionsMenu(Menu,MenuInflater) +onCreateOptionsMenu()}. Any action or menu items that you add from the fragment are appended to the +existing +items for the options menu (including those added by other fragments in the activity). The +fragment also receives item-selected events with the {@link +android.app.Fragment#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} callback method.</p> + +<p>The {@link android.app.Fragment} class also contains methods to handle context menus. You can +register a view to provide a context menu with {@link +android.app.Fragment#registerForContextMenu(View) registerForContextMenu()}. When the user opens +the context menu, the fragment receives a call to {@link +android.app.Fragment#onCreateContextMenu(ContextMenu,View,ContextMenu.ContextMenuInfo) +onCreateContextMenu()}. When the user selects an item, the fragment receives a call to {@link +android.app.Fragment#onContextItemSelected(MenuItem) onContextItemSelected()}.</p> + +<p>For more information, see <a href="{@docRoot}guide/topics/ui/menus.html">Creating +Menus</a> and <a href="{@docRoot}guide/topics/ui/actionbar.html">Using the Action Bar</a>.</p> + + + + + + diff --git a/docs/html/guide/topics/fundamentals.jd b/docs/html/guide/topics/fundamentals.jd index a095087..fffc1cd 100644 --- a/docs/html/guide/topics/fundamentals.jd +++ b/docs/html/guide/topics/fundamentals.jd @@ -19,6 +19,7 @@ page.title=Application Fundamentals <li><a href="#lmodes">Launch modes</a></li> <li><a href="#clearstack">Clearing the stack</a></li> <li><a href="#starttask">Starting tasks</a></li> + <li><a href="#commonpatterns">Common patterns</a></li> </ol></li> <li><a href="#procthread">Processes and Threads</a> <ol> @@ -294,8 +295,8 @@ onActivityResult()}</code> method. <li><p>A service is started (or new instructions are given to an ongoing service) by passing an Intent object to <code>{@link android.content.Context#startService Context.startService()}</code>. -Android calls the service's <code>{@link android.app.Service#onStart -onStart()}</code> method and passes it the Intent object.</p> +Android calls the service's <code>{@link android.app.Service#onStartCommand +onStartCommand()}</code> method and passes it the Intent object.</p> <p> Similarly, an intent can be passed to <code>{@link @@ -892,6 +893,60 @@ See <a href="#clearstack">Clearing the stack</a>, earlier. </p> +<h3 id="commonpatterns">Common patterns</h3> + +<p> +In most cases an application won't use any flags or special features. +This gives the standard interaction the user expects: launching the application +brings any existing task to the foreground, or starts the main activity in +a new task if there isn't one. +</p> + +<p> +If an application posts notifications, it needs to decide how the user's +selection of a notification should impact any currently running task. The +current suggested behavior is that any current tasks be completely removed, +replaced with a new task containing a stack of activities representing where +the user is jumping in to the app. This can be accomplished with a combination +of the {@link android.app.PendingIntent#getActivities PendingIntent.getActivities()} +method and {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TASK Intent.FLAG_ACTIVITY_CLEAR_TASK}. +</p> + +<p> +For example, here is sample code to build an array of Intents to launch an +application into an activity three levels deep. The first Intent is always +the main Intent of the application as started by the launcher. The exact +details of the Intent data will of course depend on your application. +</p> + +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/StatusBarNotifications.java + intent_array} + +<p> +In some cases an application may not want to directly launch its application +from a notification, but instead go to a intermediate summary activity. To +accomplish this, the summary activity should be given a task affinity that +is different from the main application (one will typically give it no affinity, +that is "") so that it does not get launched into any existing application task. +</p> + +{@sample development/samples/ApiDemos/AndroidManifest.xml no_task_affinity} + +<p> +The PendingIntent to launch this then does not need to supply anything special: +</p> + +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/IncomingMessage.java + pending_intent} + +<p> +If an application implements an app widget, it should generally use the same +approach as the first one for notifications: when the user taps on the app +widget it should throw away any current task of the application and start a +new task with potentially multiple activities representing the state the +user is jumping in to. +</p> + <h2 id="procthread">Processes and Threads</h2> <p> @@ -1510,9 +1565,9 @@ a music playback service could create the thread where the music will be played in {@code onCreate()}, and then stop the thread in {@code onDestroy()}.</li> <li><p>The <b>active lifetime</b> of a service begins with a call to -<code>{@link android.app.Service#onStart onStart()}</code>. This method +<code>{@link android.app.Service#onStartCommand onStartCommand()}</code>. This method is handed the Intent object that was passed to {@code startService()}. -The music service would open the Intent to discover which music to +The music service would open the Intent to discover which music to play, and begin the playback.</p> <p> @@ -1527,7 +1582,7 @@ services, whether they're started by <code>{@link android.content.Context#startService Context.startService()}</code> or <code>{@link android.content.Context#bindService Context.bindService()}</code>. -However, {@code onStart()} is called only for services started by {@code +However, {@code onStartCommand()} is called only for services started by {@code startService()}. </p> @@ -1631,7 +1686,7 @@ to the activity that the user is interacting with.</p></li> <li><p>It has a {@link android.app.Service} object that's executing one of its lifecycle callbacks (<code>{@link android.app.Service#onCreate -onCreate()}</code>, <code>{@link android.app.Service#onStart onStart()}</code>, +onCreate()}</code>, <code>{@link android.app.Service#onStartCommand onStartCommand()}</code>, or <code>{@link android.app.Service#onDestroy onDestroy()}</code>).</p></li> <li><p>It has a {@link android.content.BroadcastReceiver} object that's diff --git a/docs/html/guide/topics/fundamentals/activities.jd b/docs/html/guide/topics/fundamentals/activities.jd new file mode 100644 index 0000000..b616ab8 --- /dev/null +++ b/docs/html/guide/topics/fundamentals/activities.jd @@ -0,0 +1,762 @@ +page.title=Activities +parent.title=Application Fundamentals +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>Quickview</h2> +<ul> + <li>An activity provides a user interface for a single screen in your application</li> + <li>Activities can move into the background and then be resumed with their state restored</li> +</ul> + +<h2>In this document</h2> +<ol> + <li><a href="#Creating">Creating an Activity</a> + <ol> + <li><a href="#UI">Implementing a user interface</a></li> + <li><a href="#Declaring">Declaring the activity in the manifest</a></li> + </ol> + </li> + <li><a href="#StartingAnActivity">Starting an Activity</a> + <ol> + <li><a href="#StartingAnActivityForResult">Starting an Activity for a Result</a></li> + </ol> + </li> + <li><a href="#Lifecycle">Managing the Activity Lifecycle</a> + <ol> + <li><a href="#ImplementingLifecycleCallbacks">Implementing the lifecycle callbacks</a></li> + <li><a href="#SavingActivityState">Saving activity state</a></li> + <li><a href="#ConfigurationChanges">Handling configuration changes</a></li> + <li><a href="#CoordinatingActivities">Coordinating activities</a></li> + </ol> + </li> +</ol> + +<h2>Key classes</h2> +<ol> + <li>{@link android.app.Activity}</li> +</ol> + +<h2>See also</h2> +<ol> + <li><a href="{@docRoot}resources/tutorials/hello-world.html">Hello World Tutorial</a></li> + <li><a href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack">Tasks and Back +Stack</a></li> +</ol> + +</div> +</div> + + + +<p>An {@link android.app.Activity} is an application component that provides a screen with which +users can interact in order to do something, such as dial the phone, take a photo, send an email, or +view a map. Each activity is given a window in which to draw its user interface. The window +typically fills the screen, but may be smaller than the screen and float on top of other +windows.</p> + +<p> An application usually consists of multiple activities that are loosely bound +to each other. Typically, one activity in an application is specified as the "main" activity, which +is presented to the user when launching the application for the first time. Each +activity can then start another activity in order to perform different actions. Each time a new +activity starts, the previous activity is stopped, but the system preserves the activity +in a stack (the "back stack"). When a new activity starts, it is pushed onto the back stack and +takes user focus. The back stack abides to the basic "last in, first out" queue mechanism, +so, when the user is done with the current activity and presses the BACK key, it +is popped from the stack (and destroyed) and the previous activity resumes. (The back stack is +discussed more in the <a href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks +and Back Stack</a> document.)</p> + +<p>When an activity is stopped because a new activity starts, it is notified of this change in state +through the activity's lifecycle callback methods. +There are several callback methods that an activity might receive, due to a change in its +state—whether the system is creating it, stopping it, resuming it, or destroying it—and +each callback provides you the opportunity to perform specific work that's +appropriate to that state change. For instance, when stopped, your activity should release any +large objects, such as network or database connections. When the activity resumes, you can +reacquire the necessary resources and resume actions that were interrupted. These state transitions +are all part of the activity lifecycle.</p> + +<p>The rest of this document discusses the basics of how to build and use an activity, +including a complete discussion of how the activity lifecycle works, so you can properly manage +the transition between various activity states.</p> + + + +<h2 id="Creating">Creating an Activity</h2> + +<p>To create an activity, you must create a subclass of {@link android.app.Activity} (or +an existing subclass of it). In your subclass, you need to implement callback methods that the +system calls when the activity transitions between various states of its lifecycle, such as when +the activity is being created, stopped, resumed, or destroyed. The two most important callback +methods are:</p> + +<dl> + <dt>{@link android.app.Activity#onCreate onCreate()}</dt> + <dd>You must implement this method. The system calls this when creating your + activity. Within your implementation, you should initialize the essential components of your +activity. + Most importantly, this is where you must call {@link android.app.Activity#setContentView + setContentView()} to define the layout for the activity's user interface.</dd> + <dt>{@link android.app.Activity#onPause onPause()}</dt> + <dd>The system calls this method as the first indication that the user is leaving your +activity (though it does not always mean the activity is being destroyed). This is usually where you +should commit any changes that should be persisted beyond the current user session (because +the user might not come back).</dd> +</dl> + +<p>There are several other lifecycle callback methods that you should use in order to provide a +fluid user experience between activities and handle unexpected interuptions that cause your activity +to be stopped and even destroyed. All of the lifecycle callback methods are discussed later, in +the section about <a href="#Lifecycle">Managing the Activity Lifecycle</a>.</p> + + + +<h3 id="UI">Implementing a user interface</h3> + +<p> The user interface for an activity is provided by a hierarchy of views—objects derived +from the {@link android.view.View} class. Each view controls a particular rectangular space +within the activity's window and can respond to user interaction. For example, a view might be a +button that initiates an action when the user touches it.</p> + +<p>Android provides a number of ready-made views that you can use to design and organize your +layout. "Widgets" are views that provide a visual (and interactive) elements for the screen, such +as a button, text field, checkbox, or just an image. "Layouts" are views derived from {@link +android.view.ViewGroup} that provide a unique layout model for its child views, such as a linear +layout, a grid layout, or relative layout. You can also subclass the {@link android.view.View} and +{@link android.view.ViewGroup} classes (or existing subclasses) to create your own widgets and +layouts and apply them to your activity layout.</p> + +<p>The most common way to define a layout using views is with an XML layout file saved in your +application resources. This way, you can maintain the design of your user interface separately from +the source code that defines the activity's behavior. You can set the layout as the UI for your +activity with {@link android.app.Activity#setContentView(int) setContentView()}, passing the +resource ID for the layout. However, you can also create new {@link android.view.View}s in your +activity code and build a view hierarchy by inserting new {@link +android.view.View}s into a {@link android.view.ViewGroup}, then use that layout by passing the root +{@link android.view.ViewGroup} to {@link android.app.Activity#setContentView(View) +setContentView()}.</p> + +<p>For information about creating a user interface, see the <a +href="{@docRoot}guide/topics/ui/index.html">User Interface</a> documentation.</p> + + + +<h3 id="Declaring">Declaring the activity in the manifest</h3> + +<p>You must declare your activity in the manifest file in order for it to +be accessible to the system. To decalare your activity, open your manifest file and add an <a +href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> element +as a child of the <a +href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> +element. For example:</p> + +<pre> +<manifest ... > + <application ... > + <activity android:name=".ExampleActivity" /> + ... + </application ... > + ... +</manifest > +</pre> + +<p>There are several other attributes that you can include in this element, to define properties +such as the label for the activity, an icon for the activity, or a theme to style the activity's +UI. See the <a +href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> element +reference for more information about available attributes.</p> + + +<h4>Using intent filters</h4> + +<p>An <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code +<activity>}</a> element can also specify various intent filters—using the <a +href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code +<intent-filter>}</a> element—in order to declare how other application components may +activate it.</p> + +<p>When you create a new application using the Android SDK tools, the stub activity +that's created for you automatically includes an intent filter that declares the activity +responds to the "main" action and should be placed in the "launcher" category. The intent filter +looks like this:</p> + +<pre> +<activity android:name=".ExampleActivity" android:icon="@drawable/app_icon"> + <intent-filter> + <action android:name="android.intent.action.MAIN" /> + <category android:name="android.intent.category.LAUNCHER" /> + </intent-filter> +</activity> +</pre> + +<p>The <a href="{@docRoot}guide/topics/manifest/action-element.html">{@code +<action>}</a> element specifies that this is the "main" entry point to the application. The <a +href="{@docRoot}guide/topics/manifest/category-element.html">{@code +<category>}</a> element specifies that this activity should be listed in the +system's application launcher (to allow users to launch this activity).</p> + +<p>If you intend for your application to be self-contained and not allow other applications to +activate its activities, then you don't need any other intent filters. Only one activity should +have the "main" action and "launcher" category, as in the previous example. Activities that +you don't want to make available to other applications should have no intent filters and you can +start them yourself using explicit intents (as discussed in the following section).</p> + +<p>However, if you want your activity to respond to implicit intents that are delivered from +other applications (and your own), then you must define additional intent filters for your +activity. For each type of intent to which you want to respond, you must include an <a +href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code +<intent-filter>}</a> that includes an +<a href="{@docRoot}guide/topics/manifest/action-element.html">{@code +<action>}</a> element and, optionally, a <a +href="{@docRoot}guide/topics/manifest/category-element.html">{@code +<category>}</a> element and/or a <a +href="{@docRoot}guide/topics/manifest/data-element.html">{@code +<data>}</a> element. These elements specify the type of intent to which your activity can +respond.</p> + +<p>For more information about how your activities can respond to intents, see the <a +href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Filters</a> +document.</p> + + + +<h2 id="StartingAnActivity">Starting an Activity</h2> + +<p>You can start another activity by calling {@link android.app.Activity#startActivity + startActivity()}, passing it an {@link android.content.Intent} that describes the activity you + want to start. The intent specifies either the exact activity you want to start or describes the + type of action you want to perform (and the system selects the appropriate activity for you, +which + can even be from a different application). An intent can also carry small amounts of data to be + used by the activity that is started.</p> + +<p>When working within your own application, you'll often need to simply launch a known activity. + You can do so by creating an intent that explicitly defines the activity you want to start, +using the class name. For example, here's how one activity starts another activity named {@code +SignInActivity}:</p> + +<pre> +Intent intent = new Intent(this, SignInActivity.class); +startActivity(intent); +</pre> + +<p>However, your application might also want to perform some action, such as send an email, text + message, or status update, using data from your activity. In this case, your application might + not have its own activities to perform such actions, so you can instead leverage the activities + provided by other applications on the device, which can perform the actions for you. This is where +intents are really valuable—you can create an intent that describes an action you want to +perform and the system + launches the appropriate activity from another application. If there are + multiple activities that can handle the intent, then the user can select which one to use. For + example, if you want to allow the user to send an email message, you can create the + following intent:</p> + +<pre> +Intent intent = new Intent(Intent.ACTION_SEND); +intent.putExtra(Intent.EXTRA_EMAIL, recipientArray); +startActivity(intent); +</pre> + +<p>The {@link android.content.Intent#EXTRA_EMAIL} extra added to the intent is a string array of + email addresses to which the email should be sent. When an email application responds to this + intent, it reads the string array provided in the extra and places them in the "to" field of the + email composition form. In this situation, the email application's activity starts and when the + user is done, your activity resumes.</p> + + + + +<h3 id="StartingAnActivityForResult">Starting an activity for a result</h3> + +<p>Sometimes, you might want to receive a result from the activity that you start. In that case, + start the activity by calling {@link android.app.Activity#startActivityForResult + startActivityForResult()} (instead of {@link android.app.Activity#startActivity + startActivity()}). To then receive the result from the subsequent +activity, implement the {@link android.app.Activity#onActivityResult onActivityResult()} callback + method. When the subsequent activity is done, it returns a result in an {@link +android.content.Intent} to your {@link android.app.Activity#onActivityResult onActivityResult()} +method.</p> + +<p>For example, perhaps you want the user to pick one of their contacts, so your activity can +do something with the information in that contact. Here's how you can create such an intent and +handle the result:</p> + +<pre> +private void pickContact() { + // Create an intent to "pick" a contact, as defined by the content provider URI + Intent intent = new Intent(Intent.ACTION_PICK, Contacts.CONTENT_URI); + startActivityForResult(intent, PICK_CONTACT_REQUEST); +} + +@Override +protected void onActivityResult(int requestCode, int resultCode, Intent data) { + // If the request went well (OK) and the request was PICK_CONTACT_REQUEST + if (resultCode == Activity.RESULT_OK && requestCode == PICK_CONTACT_REQUEST) { + // Perform a query to the contact's content provider for the contact's name + Cursor cursor = getContentResolver().query(data.getData(), + new String[] {Contacts.DISPLAY_NAME}, null, null, null); + if (cursor.moveToFirst()) { // True if the cursor is not empty + int columnIndex = cursor.getColumnIndex(Contacts.DISPLAY_NAME); + String name = cursor.getString(columnIndex); + // Do something with the selected contact's name... + } + } +} +</pre> + +<p>This example shows the basic logic you should use in your {@link +android.app.Activity#onActivityResult onActivityResult()} method in order to handle an +activity result. The first condition checks whether the request was successful—if it was, then +the {@code resultCode} will be {@link android.app.Activity#RESULT_OK}—and whether the request +to which this result is responding is known—in this case, the {@code requestCode} matches the +second parameter sent with {@link android.app.Activity#startActivityForResult +startActivityForResult()}. From there, the code handles the activity result by querying the +data returned in an {@link android.content.Intent} (the {@code data} parameter).</p> + +<p>What happens is, a {@link +android.content.ContentResolver} performs a query against a content provider, which returns a +{@link android.database.Cursor} that allows the queried data to be read. For more information, see +the <a +href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> document.</p> + +<p>For more information about using intents, see the <a +href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent +Filters</a> document.</p> + + +<h2 id="ShuttingDown">Shutting Down an Activity</h2> + +<p>You can shut down an activity by calling its {@link android.app.Activity#finish +finish()} method. You can also shut down a separate activity that you previously started by calling +{@link android.app.Activity#finishActivity finishActivity()}.</p> + +<p class="note"><strong>Note:</strong> In most cases, you should not explicitly finish an activity +using these methods. As discussed in the following section about the activity lifecycle, the +Android system manages the life of an activity for you, so you do not need to finish your own +activities. Calling these methods could adversely affect the expected user +experience and should only be used when you absolutely do not want the user to return to this +instance of the activity.</p> + + +<h2 id="Lifecycle">Managing the Activity Lifecycle</h2> + +<p>Managing the lifecycle of your activities by implementing callback methods is +crucial to developing a strong +and flexible application. The lifecycle of an activity is directly affected by its association with +other activities, its task and back stack.</p> + +<p>An activity can exist in essentially three states:</p> + +<dl> + <dt><i>Resumed</i></dt> + <dd>The activity is in the foreground of the screen and has user focus. (This state is +also sometimes referred to as "running".)</dd> + + <dt><i>Paused</i></dt> + <dd>Another activity is in the foreground and has focus, but this one is still visible. That is, +another activity is visible on top of this one and that activity is partially transparent or doesn't +cover the entire screen. A paused activity is completely alive (the {@link android.app.Activity} +object is retained in memory, it maintains all state and member information, and remains attached to +the window manager), but can be killed by the system in extremely low memory situations.</dd> + + <dt><i>Stopped</i></dt> + <dd>The activity is completely obscured by another activity (the activity is now in the +"background"). A stopped activity is also still alive (the {@link android.app.Activity} +object is retained in memory, it maintains all state and member information, but is <em>not</em> +attached to the window manager). However, it is no longer visible to the user and it +can be killed by the system when memory is needed elsewhere.</dd> +</dl> + +<p>If an activity is paused or stopped, the system can drop it from memory either by asking it to +finish (calling its {@link android.app.Activity#finish finish()} method), or simply killing its +process. When the activity is opened again (after being finished or killed), it must be created all +over.</p> + + + +<h3 id="ImplementingLifecycleCallbacks">Implementing the lifecycle callbacks</h3> + +<p>When an activity transitions into and out of the different states described above, it is notified +through various callback methods. All of the callback methods are hooks that you +can override to do appropriate work when the state of your activity changes. The following skeleton +activity includes each of the fundamental lifecycle methods:</p> + + +<pre> +public class ExampleActivity extends Activity { + @Override + public void {@link android.app.Activity#onCreate onCreate}(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + // The activity is being created. + } + @Override + protected void {@link android.app.Activity#onStart onStart()} { + super.onStart(); + // The activity is about to become visible. + } + @Override + protected void {@link android.app.Activity#onResume onResume()} { + super.onResume(); + // The activity has become visible (it is now "resumed"). + } + @Override + protected void {@link android.app.Activity#onPause onPause()} { + super.onPause(); + // Another activity is taking focus (this activity is about to be "paused"). + } + @Override + protected void {@link android.app.Activity#onStop onStop()} { + super.onStop(); + // The activity is no longer visible (it is now "stopped") + } + @Override + protected void {@link android.app.Activity#onDestroy onDestroy()} { + super.onDestroy(); + // The activity is about to be destroyed. + } +} +</pre> + +<p class="note"><strong>Note:</strong> Your implementation of these lifecycle methods must +always call the superclass implementation before doing any work, as shown in the examples above.</p> + +<p>Taken together, these methods define the entire lifecycle of an activity. By implementing these +methods, you can monitor three nested loops in the activity lifecycle: </p> + +<ul> +<li>The <b>entire lifetime</b> of an activity happens between the call to {@link +android.app.Activity#onCreate onCreate()} and the call to {@link +android.app.Activity#onDestroy}. Your activity should perform setup of +"global" state (such as defining layout) in {@link android.app.Activity#onCreate onCreate()}, and +release all remaining resources in {@link android.app.Activity#onDestroy}. For example, if your +activity has a thread running in the background to download data from the network, it might create +that thread in {@link android.app.Activity#onCreate onCreate()} and then stop the thread in {@link +android.app.Activity#onDestroy}.</li> + +<li><p>The <b>visible lifetime</b> of an activity happens between the call to {@link +android.app.Activity#onStart onStart()} and the call to {@link +android.app.Activity#onStop onStop()}. During this time, the user can see the activity +on-screen and interact with it. For example, {@link android.app.Activity#onStop onStop()} is called +when a new activity starts and this one is no longer visible. Between these two methods, you can +maintain resources that are needed to show the activity to the user. For example, you can register a +{@link android.content.BroadcastReceiver} in {@link +android.app.Activity#onStart onStart()} to monitor changes that impact your UI, and unregister +it in {@link android.app.Activity#onStop onStop()} when the user can no longer see what you are +displaying. The system might call {@link android.app.Activity#onStart onStart()} and {@link +android.app.Activity#onStop onStop()} multiple times during the entire lifetime of the activity, as +the activity alternates between being visible and hidden to the user.</p></li> + +<li><p>The <b>foreground lifetime</b> of an activity happens between the call to {@link +android.app.Activity#onResume onResume()} and the call to {@link android.app.Activity#onPause +onPause()}. During this time, the activity is in front of all other activities on screen and has +user input focus. An activity can frequently transition in and out of the foreground—for +example, {@link android.app.Activity#onPause onPause()} is called when the device goes to sleep or +when a dialog appears. Because this state can transition often, the code in these two methods should +be fairly lightweight in order to avoid slow transitions that make the user wait.</p></li> +</ul> + +<p>Figure 1 illustrates these loops and the paths an activity might take between states. +The rectangles represent the callback methods you can implement to perform operations when +the activity transitions between states. <p> + +<img src="{@docRoot}images/activity_lifecycle.png" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> The activity lifecycle.</p> + +<p>The same lifecycle callback methods are listed in table 1, which describes each of the callback +methods in more detail and locates each one within the +activity's overall lifecycle, including whether the system can kill the activity after the +callback method completes.</p> + +<p class="table-caption"><strong>Table 1.</strong> A summary of the activity lifecycle's +callback methods.</p> + +<table border="2" width="85%" frame="hsides" rules="rows"> +<colgroup align="left" span="3"></colgroup> +<colgroup align="left"></colgroup> +<colgroup align="center"></colgroup> +<colgroup align="center"></colgroup> + +<thead> +<tr><th colspan="3">Method</th> <th>Description</th> <th>Killable after?</th> <th>Next</th></tr> +</thead> + +<tbody> +<tr> + <td colspan="3" align="left"><code>{@link android.app.Activity#onCreate onCreate()}</code></td> + <td>Called when the activity is first created. + This is where you should do all of your normal static set up — + create views, bind data to lists, and so on. This method is passed + a Bundle object containing the activity's previous state, if that + state was captured (see <a href="#actstate">Saving Activity State</a>, + later). + <p>Always followed by {@code onStart()}.</p></td> + <td align="center">No</td> + <td align="center">{@code onStart()}</td> +</tr> + +<tr> + <td rowspan="5" style="border-left: none; border-right: none;"> </td> + <td colspan="2" align="left"><code>{@link android.app.Activity#onRestart +onRestart()}</code></td> + <td>Called after the activity has been stopped, just prior to it being + started again. + <p>Always followed by {@code onStart()}</p></td> + <td align="center">No</td> + <td align="center">{@code onStart()}</td> +</tr> + +<tr> + <td colspan="2" align="left"><code>{@link android.app.Activity#onStart onStart()}</code></td> + <td>Called just before the activity becomes visible to the user. + <p>Followed by {@code onResume()} if the activity comes + to the foreground, or {@code onStop()} if it becomes hidden.</p></td> + <td align="center">No</td> + <td align="center">{@code onResume()} <br/>or<br/> {@code onStop()}</td> +</tr> + +<tr> + <td rowspan="2" style="border-left: none;"> </td> + <td align="left"><code>{@link android.app.Activity#onResume onResume()}</code></td> + <td>Called just before the activity starts + interacting with the user. At this point the activity is at + the top of the activity stack, with user input going to it. + <p>Always followed by {@code onPause()}.</p></td> + <td align="center">No</td> + <td align="center">{@code onPause()}</td> +</tr> + +<tr> + <td align="left"><code>{@link android.app.Activity#onPause onPause()}</code></td> + <td>Called when the system is about to start resuming another + activity. This method is typically used to commit unsaved changes to + persistent data, stop animations and other things that may be consuming + CPU, and so on. It should do whatever it does very quickly, because + the next activity will not be resumed until it returns. + <p>Followed either by {@code onResume()} if the activity + returns back to the front, or by {@code onStop()} if it becomes + invisible to the user.</td> + <td align="center"><strong style="color:#800000">Yes</strong></td> + <td align="center">{@code onResume()} <br/>or<br/> {@code onStop()}</td> +</tr> + +<tr> + <td colspan="2" align="left"><code>{@link android.app.Activity#onStop onStop()}</code></td> + <td>Called when the activity is no longer visible to the user. This + may happen because it is being destroyed, or because another activity + (either an existing one or a new one) has been resumed and is covering it. + <p>Followed either by {@code onRestart()} if + the activity is coming back to interact with the user, or by + {@code onDestroy()} if this activity is going away.</p></td> + <td align="center"><strong style="color:#800000">Yes</strong></td> + <td align="center">{@code onRestart()} <br/>or<br/> {@code onDestroy()}</td> +</tr> + +<tr> + <td colspan="3" align="left"><code>{@link android.app.Activity#onDestroy +onDestroy()}</code></td> + <td>Called before the activity is destroyed. This is the final call + that the activity will receive. It could be called either because the + activity is finishing (someone called <code>{@link android.app.Activity#finish + finish()}</code> on it), or because the system is temporarily destroying this + instance of the activity to save space. You can distinguish + between these two scenarios with the <code>{@link + android.app.Activity#isFinishing isFinishing()}</code> method.</td> + <td align="center"><strong style="color:#800000">Yes</strong></td> + <td align="center"><em>nothing</em></td> +</tr> +</tbody> +</table> + +<p>The column labeled "Killable after?" indicates whether or not the system can +kill the process hosting the activity at any time <em>after the method returns</em>, without +executing another line of the activity's code. Three methods are marked "yes": ({@link +android.app.Activity#onPause +onPause()}, {@link android.app.Activity#onStop onStop()}, and {@link android.app.Activity#onDestroy +onDestroy()}). Because {@link android.app.Activity#onPause onPause()} is the first +of the three, once the activity is created, {@link android.app.Activity#onPause onPause()} is the +last method that's guaranteed to be called before the process <em>can</em> be killed—if +the system must recover memory in an emergency, then {@link +android.app.Activity#onStop onStop()} and {@link android.app.Activity#onDestroy onDestroy()} might +not be called. Therefore, you should use {@link android.app.Activity#onPause onPause()} to write +crucial persistent data (such as user edits) to storage. However, you should be selective about +what information must be retained during {@link android.app.Activity#onPause onPause()}, because any +blocking procedures in this method block the transition to the next activity and slow the user +experience.</p> + +<p> Methods that are marked "No" in the <b>Killable</b> column protect the process hosting the +activity from being killed from the moment they are called. Thus, an activity is killable +from the time {@link android.app.Activity#onPause onPause()} returns to the time +{@link android.app.Activity#onResume onResume()} is called. It will not again be killable until +{@link android.app.Activity#onPause onPause()} is again called and returns. </p> + +<p class="note"><strong>Note:</strong> An activity that's not technically "killable" by this +definition in table 1 might still be killed by the system—but that would happen only in +extreme circumstances when there is no other recourse. When an activity might be killed is +discussed more in the <a +href="{@docRoot}guide/topics/fundamentals/processes-and-threading.html">Processes and +Threading</a> document.</p> + + +<h3 id="SavingActivityState">Saving activity state</h3> + +<p>The introduction to <a href="Lifecycle">Managing the Activity Lifecycle</a> briefly mentions that +when an activity is paused or stopped, the state of the activity is retained. This is true because +the {@link android.app.Activity} object is still held in memory when it is paused or +stopped—all information about its members and current state is still alive. Thus, any changes +the user made within the activity are retained in memory, so that when the activity returns to the +foreground (when it "resumes"), those changes are still there.</p> + +<div class="figure" style="width:615px"> +<img src="{@docRoot}images/fundamentals/restore_instance.png" alt="" /> +<p class="img-caption"><strong>Figure 2.</strong> The two ways in which an activity returns to user +focus with its state intact: either the activity is stopped, then resumed and the activity state +remains intact (left), or the activity is destroyed, then recreated and the activity must restore +the previous activity state (right).</p> +</div> + +<p>However, when the system destroys an activity in order to recover memory, the {@link +android.app.Activity} object is destroyed, so the system cannot simply resume it with its state +intact. Instead, the system must recreate the {@link android.app.Activity} object if the user +navigates back to it. Yet, the user is unaware +that the system destroyed the activity and recreated it and, thus, probably +expects the activity to be exactly as it was. In this situation, you can ensure that +important information about the activity state is preserved by implementing an additional +callback method that allows you to save information about the state of your activity and then +restore it when the the system recreates the activity.</p> + +<p>The callback method in which you can save information about the current state of your activity is +{@link android.app.Activity#onSaveInstanceState onSaveInstanceState()}. The system calls this method +before making the activity vulnerable to being destroyed and passes it +a {@link android.os.Bundle} object. The {@link android.os.Bundle} is where you can store +state information about the activity as name-value pairs, using methods such as {@link +android.os.Bundle#putString putString()}. Then, if the system kills your activity's +process and the user navigates back to your activity, the system passes the {@link +android.os.Bundle} to {@link android.app.Activity#onCreate onCreate()} so you can restore the +activity state you saved during {@link android.app.Activity#onSaveInstanceState +onSaveInstanceState()}. If there is no state information to restore, then the {@link +android.os.Bundle} passed to {@link android.app.Activity#onCreate onCreate()} is null.</p> + +<p class="note"><strong>Note:</strong> There's no guarantee that {@link +android.app.Activity#onSaveInstanceState onSaveInstanceState()} will be called before your +activity is destroyed, because there are cases in which it won't be necessary to save the state +(such as when the user leaves your activity using the BACK key, because the user is explicitly +closing the activity). If the method is called, it is always called before {@link +android.app.Activity#onStop onStop()} and possibly before {@link android.app.Activity#onPause +onPause()}.</p> + +<p>However, even if you do nothing and do not implement {@link +android.app.Activity#onSaveInstanceState onSaveInstanceState()}, some of the activity state is +restored by the {@link android.app.Activity} class's default implementation of {@link +android.app.Activity#onSaveInstanceState onSaveInstanceState()}. Specifically, the default +implementation calls {@link +android.view.View#onSaveInstanceState onSaveInstanceState()} for every {@link android.view.View} +in the layout, which allows each view to provide information about itself +that should be saved. Almost every widget in the Android framework implements this method as +appropriate, such that any visible changes to the UI are automatically saved and restored when your +activity is recreated. For example, the {@link android.widget.EditText} widget saves any text +entered by the user and the {@link android.widget.CheckBox} widget saves whether it's checked or +not. The only work required by you is to provide a unique ID (with the <a +href="{@docRoot}guide/topics/resources/layout-resource.html#idvalue">{@code android:id}</a> +attribute) for each widget you want to save its state. If a widget does not have an ID, then it +cannot save its state.</p> + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<p>You can also explicitly stop a view in your layout from saving its state by setting the +{@link android.R.attr#saveEnabled android:saveEnabled} attribute to {@code "false"} or by calling +the {@link android.view.View#setSaveEnabled setSaveEnabled()} method. Usually, you should not +disable this, but you might if you want to restore the state of the activity UI differently.</p> +</div> +</div> + +<p>Although the default implementation of {@link +android.app.Activity#onSaveInstanceState onSaveInstanceState()} saves useful information about +your activity's UI, you still might need to override it to save additional information. +For example, you might need to save member values that changed during the activity's life (which +might correlate to values restored in the UI, but the members that hold those UI values are not +restored, by default).</p> + +<p>Because the default implementation of {@link +android.app.Activity#onSaveInstanceState onSaveInstanceState()} helps save the state of the UI, if +you override the method in order to save additional state information, you should always call the +superclass implementation of {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} +before doing any work.</p> + +<p class="note"><strong>Note:</strong> Because {@link android.app.Activity#onSaveInstanceState +onSaveInstanceState()} is not guaranteed +to be called, you should use it only to record the transient state of the activity (the state of +the UI)—you should never use it to store persistent data. Instead, you should use {@link +android.app.Activity#onPause onPause()} to store persistent data (such as data that should be saved +to a database) when the user leaves the activity.</p> + +<p>A good way to test your application's ability to restore its state is to simply rotate the +device so that the screen orientation changes. When the screen orientation changes, the system +destroys and recreates the activity in order to apply alternative resources that might be available +for the new orientation. For this reason alone, it's very important that your activity +completely restores its state when it is recreated, because users regularly rotate the screen while +using applications.</p> + + +<h3 id="ConfigurationChanges">Handling configuration changes</h3> + +<p>Some device configurations can change during runtime (such as screen orientation, keyboard +availability, and language). When such a change occurs, Android restarts the running Activity +({@link android.app.Activity#onDestroy} is called, followed immediately by {@link +android.app.Activity#onCreate onCreate()}). The restart behavior is +designed to help your application adapt to new configurations by automatically reloading your +application with alternative resources that you've provided. If you design your activity to +properly handle this event, it will be more resilient to unexpected events in the activity +lifecycle.</p> + +<p>The best way to handle a configuration change, such as a change in the screen orientation, is + to simply preserve the state of your application using {@link + android.app.Activity#onSaveInstanceState onSaveInstanceState()} and {@link +android.app.Activity#onRestoreInstanceState onRestoreInstanceState()} (or {@link +android.app.Activity#onCreate onCreate()}), as discussed in the previous section.</p> + +<p>For a detailed discussion about configuration changes that happen at runtime and how you should +handle them, read <a href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling +Runtime Changes</a>.</p> + + + +<h3 id="CoordinatingActivities">Coordinating activities</h3> + + <p>When one activity starts another, they both experience lifecycle transitions. The first activity +pauses and stops (though, it won't stop if it's still visible in the background), while the other +activity is created. In case these activities share data saved to disc or elsewhere, it's important +to understand that the first activity is not completely stopped before the second one is created. +Rather, the process of starting the second one overlaps with the process of stopping the first +one.</p> + +<p>The order of lifecycle callbacks is well defined, particularly when the two activities are in the +same process and one is starting the other. Here's the order of operations that occur when Activity +A starts Acivity B: </p> + +<ol> +<li>Activity A's {@link android.app.Activity#onPause onPause()} method executes.</li> + +<li>Activity B's {@link android.app.Activity#onCreate onCreate()}, {@link +android.app.Activity#onStart onStart()}, and {@link android.app.Activity#onResume onResume()} +methods execute in sequence. (Activity B now has user focus.)</li> + +<li>Then, if Activity A is no longer visible on screen, its {@link +android.app.Activity#onStop onStop()} method executes.</li> +</ol> + + <p>This predictable sequence of lifecycle callbacks allows you to manage the transition of +information from one activity to another. For example, if you must write to a database when the +first activity stops so that the following activity can read it, then you should write to the +database during {@link android.app.Activity#onPause onPause()} instead of during {@link +android.app.Activity#onStop onStop()}.</p> + + +<h2>Beginner's Path</h2> + +<p>For more information about how Android maintains a history of activities and +enables user multitasking, continue with the <b><a +href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back +Stack</a></b> document.</p> diff --git a/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd b/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd new file mode 100644 index 0000000..47dc547 --- /dev/null +++ b/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd @@ -0,0 +1,568 @@ +page.title=Tasks and Back Stack +parent.title=Application Fundamentals +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>Quickview</h2> +<ul> + <li>All activities belong to a task</li> + <li>A task contains a collection of activities in the order in which the user interacts with +them</li> + <li>Tasks can move to the background and retain the state of each activity in order for the user +to perform other tasks without loosing their work</li> +</ul> + +<h2>In this document</h2> +<ol> +<li><a href="#ActivityState">Saving Activity State</a></li></li> +<li><a href="#ManagingTasks">Managing Tasks</a> + <ol> + <li><a href="#TaskLaunchModes">Defining launch modes</a></li> + <li><a href="#Affinities">Handling affinities</a></li> + <li><a href="#Clearing">Clearing the back stack</a></li> + <li><a href="#Starting">Starting a task</a></li> + </ol> +</li> +</ol> + +<h2>See also</h2> +<ol> + <li><a><a href="{@docRoot}videos/index.html#v=fL6gSd4ugSI">Application Lifecycle video</a></li> + <li><a +href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>} manifest +element</a></li> +</ol> +</div> +</div> + + +<p>An application usually contains multiple <a +href="{@docRoot}guide/topics/fundamentals/activities.html">activities</a>. Each activity +should be designed around a specific kind of action the user can perform and can start other +activities. For example, an email application might have one activity to show a list of new email. +When the user selects an email, a new activity opens to view that email.</p> + +<p>An activity can even start activities that exist in other applications on the device. For +example, if your application wants to send an email, you can define an intent to perform a "send" +action and include some data, such as an email address and a message. An activity from another +application that declares itself to handle this kind of intent then opens. In this case, the intent +is to send an email, so an email application's "compose" activity starts (if multiple activities +support the same intent, then the system lets the user select which one to use). When the email is +sent, your activity resumes and it seems as if the email activity was part of your application. Even +though the activities may be from different applications, Android maintains this seamless user +experience by keeping both activities in the same <em>task</em>.</p> + +<p>A task is a collection of activities that users interact with +when performing a certain job. The activities are arranged in a stack (the "back stack"), in the +order in which each activity is opened.</p> + +<!-- SAVE FOR WHEN THE FRAGMENT DOC IS ADDED +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h3>Adding fragments to a task's back stack</h3> + +<p>Your activity can also include {@link android.app.Fragment}s to the back stack. For example, +suppose you have a two-pane layout using fragments, one of which is a list view (fragment A) and the +other being a layout to display an item from the list (fragment B). When the user selects an item +from the list, fragment B is replaced by a new fragment (fragment C). In this case, it might be +desireable for the user to navigate back to reveal fragment B, using the BACK key.</p> +<p>In order to add fragment B to the back stack so that this is possible, you must call {@link +android.app.FragmentTransaction#addToBackStack addToBackStack()} before you {@link +android.app.FragmentTransaction#commit()} the transaction that replaces fragment B with fragment +C.</p> +<p>For more information about using fragments and adding them to the back stack, see the {@link +android.app.Fragment} class documentation.</p> + +</div> +</div> +--> + +<p>The device Home screen is the starting place for most tasks. When the user touches an icon in the +application +launcher (or a shortcut on the Home screen), that application's task comes to the foreground. If no +task exists for the application (the application has not been used recently), then a new task +is created and the "main" activity for that application opens as the root activity in the stack.</p> + +<p>When the current activity starts another, the new activity is pushed on the top of the stack and +takes focus. The previous activity remains in the stack, but is stopped. When an activity +stops, the system retains the current state of its user interface. When the user presses the BACK +key, the current activity is popped from the top of the stack (the activity is destroyed) and the +previous activity resumes (the previous state of its UI is restored). Activities in the stack are +never rearranged, only pushed and popped from the stack—pushed onto the stack when started by +the current activity and popped off when the user leaves it using the BACK key. As such, the back +stack operates as a "last in, first out" object structure. Figure 1 visualizes +this behavior with a timeline showing the progress between activities along with the current back +stack at each point in time.</p> + +<img src="{@docRoot}images/fundamentals/diagram_backstack.png" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> A representation of how each new activity in a +task adds an item to the back stack. When the user presses the BACK key, the current activity is +destroyed and the previous activity resumes.</p> + + +<p>If the user continues to press BACK, then each activity in the stack is popped off to reveal the +previous one, until the user returns to the Home screen (or to whichever activity was running when +the task began). When all activities are removed from the stack, the task no longer exists.</p> + +<div class="figure" style="width:369px"> +<img src="{@docRoot}images/fundamentals/diagram_multitasking.png" alt="" /> <p +class="img-caption"><strong>Figure 2.</strong> Two tasks: Task A is in the background, waiting +to be resumed, while Task B receives user interaction in the foreground.</p> +</div> +<div class="figure" style="width:178px"> + <img src="{@docRoot}images/fundamentals/diagram_multiple_instances.png" alt="" /> <p +class="img-caption"><strong>Figure 3.</strong> A single activity is instantiated multiple times.</p> +</div> + +<p>A task is a cohesive unit that can move to the "background" when users begin a new task or go +to the Home screen, via the HOME key. While in the background, all the activities in the task are +stopped, but the back stack for the task remains intact—the task has simply lost focus while +another task takes place, as shown in figure 2. A task can then return to the "foreground" so users +can pick up where they left off. Suppose, for example, that the current task (Task A) has three +activities in its stack—two under the current activity. The user presses the HOME key, then +starts a new application from the application launcher. When the Home screen appears, Task A goes +into the background. When the new application starts, the system starts a task for that application +(Task B) with its own stack of activities. After interacting with +that application, the user returns Home again and selects the application that originally +started Task A. Now, Task A comes to the +foreground—all three activities in its stack are intact and the activity at the top of the +stack resumes. At +this point, the user can also switch back to Task B by going Home and selecting the application icon +that started that task (or by touching and holding the HOME key to reveal recent tasks and selecting +one). This is an example of multitasking on Android.</p> + +<p class="note"><strong>Note:</strong> Multiple tasks can be held in the background at once. +However, if the user is running many background tasks at the same time, the system might begin +destroying background activities in order to recover memory, causing the activity states to be lost. +See the following section about <a href="#ActivityState">Activity state</a>.</p> + +<p>Because the activities in the back stack are never rearranged, if your application allows +users to start a particular activity from more than one activity, a new instance of +that activity is created and popped onto the stack (rather than bringing any previous instance of +the activity to the top). As such, one activity in your application might be instantiated multiple +times (even from different tasks), as shown in figure 3. As such, if the user navigates backward +using the BACK key, each instance of the activity is revealed in the order they were opened (each +with their own UI state). However, you can modify this behavior if you do not want an activity to be +instantiated more than once. How to do so is discussed in the later section about <a +href="#ManagingTasks">Managing Tasks</a>.</p> + + +<p>To summarize the default behavior for activities and tasks:</p> + +<ul> + <li>When Activity A starts Activity B, Activity A is stopped, but the system retains its state +(such as scroll position and text entered into forms). +If the user presses the BACK key while in Activity B, Activity A resumes with its state +restored.</li> + <li>When the user leaves a task by pressing the HOME key, the current activity is stopped and +its task goes into the background. The system retains the state of every activity in the task. If +the user later resumes the task by selecting the launcher icon that began the task, the task comes +to the foreground and resumes the activity at the top of the stack.</li> + <li>If the user presses the BACK key, the current activity is popped from the stack and +destroyed. The previous activity in the stack is resumed. When an activity is destroyed, the system +<em>does not</em> retain the activity's state.</li> + <li>Activities can be instantiated multiple times, even from other tasks.</li> +</ul> + + +<h2 id="ActivityState">Saving Activity State</h2> + +<p>As discussed above, the system's default behavior preserves the state of an activity when it is +stopped. This way, when users navigate back to a previous activity, its user interface appears +the way they left it. However, you can—and <strong>should</strong>—proactively retain +the state of your activities using callback methods, in case the activity is destroyed and must +be recreated.</p> + +<p>When the system stops one of your activities (such as when a new activity starts or the task +moves to the background), the system might destroy that activity completely if it needs to recover +system memory. When this happens, information about the activity state is lost. If this happens, the +system still +knows that the activity has a place in the back stack, but when the activity is brought to the +top of the stack the system must recreate it (rather than resume it). In order to +avoid loosing the user's work, you should proactively retain it by implementing the {@link +android.app.Activity#onSaveInstanceState onSaveInstanceState()} callback +methods in your activity.</p> + +<p>For more information about how to save your activity state, see the <a +href="{@docRoot}guide/topics/fundamentals/activities.html#SavingActivityState">Activities</a> +document.</p> + + + +<h2 id="ManagingTasks">Managing Tasks</h2> + +<p>The way Android manages tasks and the back stack, as described above—by placing all +activities started in succession in the same task and in a "last in, first out" stack—works +great for most applications and you shouldn't have to worry about how your activities are associated +with tasks or how they exist in the back stack. However, you might decide that you want to interrupt +the normal behavior. Perhaps you want an activity in your application to begin a new task when it is +started (instead of being placed within the current task); or, when you start an activity, you want +to bring forward an existing instance of it (instead of creating a new +instance on top of the back stack); or, you want your back stack to be cleared of all +activitiesstart an activity except for the root activity when the user leaves the task.</p> + +<p>You can do these things and more, with attributes in the +<a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code +<activity>}</a> manifest element and with flags in the intent that you pass to {@link +android.app.Activity#startActivity startActivity()}.</p> + +<p>In this regard, the the principal <a +href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> +attributes you can use are:</p> + +<ul class="nolist"> + <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">{@code +taskAffinity}</a></li> + <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code +launchMode}</a></li> + <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">{@code +allowTaskReparenting}</a></li> + <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#clear">{@code +clearTaskOnLaunch}</a></li> + <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#always">{@code +alwaysRetainTaskState}</a></li> + <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#finish">{@code +finishOnTaskLaunch}</a></li> +</ul> + +<p>And the principal intent flags you can use are:</p> + +<ul class="nolist"> + <li>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</li> + <li>{@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}</li> + <li>{@link android.content.Intent#FLAG_ACTIVITY_SINGLE_TOP}</li> +</ul> + +<p>In the following sections, you'll see how you can use these manifest attributes and intent +flags to define how activities are associated with tasks and how the behave in the back stack.</p> + + +<p class="caution"><strong>Caution:</strong> Most applications should not interrupt the default +behavior for activities and tasks. If you determine that it's necessary for your activity to modify +the default behaviors, use caution and be sure to test the usability of the activity during +launch and when navigating back to it from other activities and tasks with the BACK key. Be sure +to test for navigation behaviors that might conflict with the user's expected behavior.</p> + + +<h3 id="TaskLaunchModes">Defining launch modes</h3> + +<p>Launch modes allow you to define how a new instance of an activity is associated with the +current task. You can define different launch modes in two ways:</p> +<ul class="nolist"> + <li><a href="#ManifestForTasks">Using the manifest file</a> + <p>When you declare an activity in your manifest file, you can specify how the activity +should associate with tasks when it starts.</li> + <li><a href="#IntentFlagsForTasks">Using Intent flags</a> + <p>When you call {@link android.app.Activity#startActivity startActivity()}, +you can include a flag in the {@link android.content.Intent} that declares how (or +whether) the new activity should associate with the current task.</p></li> +</ul> + +<p>As such, if Activity A starts Activity B, Activity B can define in its manifest how it +should associate with the current task (if at all) and Activity A can also request how Activity +B should associate with current task. If both activities define how Activity B +should associate with a task, then Activity A's request (as defined in the intent) is honored +over Activity B's request (as defined in its manifest).</p> + +<p class="note"><strong>Note:</strong> Some the launch modes available in the manifest +are not available as flags for an intent and, likewise, some launch modes available as flags +for an intent cannot be defined in the manifest.</p> + + +<h4 id="ManifestForTasks">Using the manifest file</h4> + +<p>When declaring an activity in your manifest file, you can specify how the activity should +associate with a task using the <a +href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> +element's <a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code +launchMode}</a> attribute.</p> + +<p>The <a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code +launchMode}</a> attribute specifies an instruction on how the activity should be launched into a +task. There are four different launch modes you can assign to the +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">launchMode</a></code> +attribute:</p> + +<dl> +<dt>{@code "standard"} (the default mode)</dt> + <dd>Default. The system creates a new instance of the activity in the task from +which it was started and routes the intent to it. The activity can be instantiated multiple times, +each instance can belong to different tasks, and one task can have multiple instances.</dd> +<dt>{@code "singleTop"}</dt> + <dd>If an instance of the activity already exists at the top of the current task, the system +routes the intent to that instance through a call to its {@link +android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a new instance of the +activity. The activity can be instantiated multiple times, each instance can +belong to different tasks, and one task can have multiple instances (but only if the the +activity at the top of the back stack is <em>not</em> an existing instance of the activity). + <p>For example, suppose a task's back stack consists of root activity A with activities B, C, +and D on top (the stack is A-B-C-D; D is on top). An intent arrives for an activity of type D. +If D has the default {@code "standard"} launch mode, a new instance of the class is launched and the +stack becomes A-B-C-D-D. However, if D's launch mode is {@code "singleTop"}, the existing instance +of D is deliverd the intent through {@link +android.app.Activity#onNewIntent onNewIntent()}, because it's at the top of the stack—the +stack remains A-B-C-D. However, if an intent arrives for an activity of type B, then a new +instance of B is added to the stack, even if its launch mode is {@code "singleTop"}.</p> + <p class="note"><strong>Note:</strong> When a new instance of an activity is created, +the user can press the BACK key to return to the previous activity. But when an existing instance of +an activity handles a new intent, the user cannot press the BACK key to return to the state of +the activity before the new intent arrived in {@link android.app.Activity#onNewIntent +onNewIntent()}.</p> +</dd> + +<dt>{@code "singleTask"}</dt> + <dd>The system creates a new task and instantiates the activity at the root of the new task. +However, if an instance of the activity already exists in a separate task, the system routes the +intent to the existing instance through a call to its {@link +android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a new instance. Only +one instance of the activity can exist at a time. + <p class="note"><strong>Note:</strong> Although the activity starts in a new task, the +BACK key still returns the user to the previous activity.</p></dd> +<dt>{@code "singleInstance"}.</dt> + <dd>Same as {@code "singleTask"}, except that the system doesn't launch any other activities into +the task holding the instance. The activity is always the single and only member of its task; +any activities started by this one open in a separate task.</dd> +</dl> + + +<p>As another example, the Android Browser application declares that the web browser activity should +always open in its own task—by specifying the {@code singleTask} launch mode in the <a +href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> element. +This means that if your application issues an +intent to open the Android Browser, its activity is <em>not</em> placed in the same +task as your application. Instead, either a new task starts for the Browser or, if the Browser +already has a task running in the background, that task is brought forward to handle the new +intent.</p> + +<p>Regardless of whether an activity starts in a new task or in the same task as the activity that +started it, the BACK key always takes the user to the previous activity. However, if you +start an activity from your task (Task A) that specifies the {@code singleTask} launch mode, then +that activity might have an instance in the background that belongs to a task with its own back +stack (Task B). In this +case, when Task B is brought forward to handle a new intent, the BACK key first navigates +backward through the activities in Task B before returning to +the top-most activity in Task A. Figure 4 visualizes this type of scenario.</p> + +<img src="{@docRoot}images/fundamentals/diagram_backstack_singletask_multiactivity.png" alt="" /> +<p class="img-caption"><strong>Figure 4.</strong> A representation of how an activity with +launch mode "singleTask" is added to the back stack. If the activity is already a part of a +background task with its own back stack (Task B), then the entire back stack also comes +forward, on top of the current task (Task A).</p> + +<p>For more information about using launch modes in the manifest file, see the +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> +element documentation, where the {@code launchMode} attribute and the accepted values are +discussed more.</p> + +<p class="note"><strong>Note:</strong> The behaviors that you specify for your activity with the <a +href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code launchMode}</a> attribute +can be overriden by flags included with the intent that start your activity, as discussed in the +next section.</p> + + + +<h4 id="#IntentFlagsForTasks">Using Intent flags</h4> + +<p>When starting an activity, you can modify the default association of an activity to its task +by including flags in the intent that you deliver to {@link +android.app.Activity#startActivity startActivity()}. The flags you can use to modify the +default behavior are:</p> + +<p> + <dt>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</dt> + <dd>Start the activity in a new task. If a task is already running for the activity you are now +starting, that task is brought to the foreground with its last state restored and the activity +receives the new intent in {@link android.app.Activity#onNewIntent onNewIntent()}. + <p>This produces the same behavior as the {@code "singleTask"} <a +href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code launchMode}</a> value, +discussed in the previous section.</p></dd> + <dt>{@link android.content.Intent#FLAG_ACTIVITY_SINGLE_TOP}</dt> + <dd>If the activity being started is the current activity (at the top of the back stack), then +the existing instance receives a call to {@link android.app.Activity#onNewIntent onNewIntent()}, +instead of creating a new instance of the activity. + <p>This produces the same behavior as the {@code "singleTop"} <a +href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code launchMode}</a> value, +discussed in the previous section.</p></dd> + <dt>{@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}</dt> + <dd>If the activity being started is already running in the current task, then instead +of launching a new instance of that activity, all of the other activities on top of it are +destroyed and this intent is delivered to the resumed instance of the activity (now on top), +through {@link android.app.Activity#onNewIntent onNewIntent()}). + <p>There is no value for the <a +href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code launchMode}</a> +attribute that produces this behavior.</p> + <p>{@code FLAG_ACTIVITY_CLEAR_TOP} is most often used in conjunction with {@code +FLAG_ACTIVITY_NEW_TASK}. When used together, these flags are a way of locating an existing activity +in another task and putting it in a position where it can respond to the intent. </p> + <p class="note"><strong>Note:</strong> If the launch mode of the designated activity is {@code +"standard"}, it too is removed from the stack and a new instance is launched in its place to handle +the incoming intent. That's because a new instance is always created for a new intent when the +launch mode is {@code "standard"}. </p> +</dd> +</dl> + + + + + +<h3 id="Affinities">Handling affinities</h3> + +<p>The <em>affinity</em> indicates which task an activity prefers to belong to. By default, all the +activities from the same application have an affinity for each other. So, by default, all +activities in the same application prefer to be in the same task. However, you can modify +the default affinity for an activity. Activities defined in +different applications can share an affinity, or activities defined in the same application can be +assigned different task affinities.</p> + +<p>You can modify the affinity for any given activity with the <a +href="{@docRoot}guide/topics/manifest/activity-element.html#aff">{@code taskAffinity}</a> attribute +of the <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> +element.</p> + +<p>The <a +href="{@docRoot}guide/topics/manifest/activity-element.html#aff">{@code taskAffinity}</a> +attribute takes a string value, which must be unique from the default package name +declared in the <a href="{@docRoot}guide/topics/manifest/manifest-element.html">{@code +<manifest>}</a> element, because the system uses that name to identify the default task +affinity for the application.</p> + +<p>The affinity comes into play in two circumstances:</p> +<ul> + <li>When the intent that launches an activity contains the {@link +android.content.Intent#FLAG_ACTIVITY_NEW_TASK} flag. + +<p>A new activity is, by default, launched into the task of the activity +that called {@link android.app.Activity#startActivity startActivity()}. It's pushed onto the same +back stack as the caller. However, if the intent passed to {@link +android.app.Activity#startActivity startActivity()} contains the {@link +android.content.Intent#FLAG_ACTIVITY_NEW_TASK} +flag, the system looks for a different task to house the new activity. Often, it's a new task. +However, it doesn't have to be. If there's already an existing task with the same affinity as the +new activity, the activity is launched into that task. If not, it begins a new task.</p> + +<p>If this flag causes an activity to begin a new task and the user presses the HOME key to leave +it, there must be some way for the user to navigate back to the task. Some entities (such as the +notification manager) always start activities in an external task, never as part of their own, so +they always put {@code FLAG_ACTIVITY_NEW_TASK} in the intents they pass to {@link +android.app.Activity#startActivity startActivity()}. If you have an activity that can be invoked by +an external entity that might use this flag, take care that the user has a independent way to get +back to the task that's started, such as with a launcher icon (the root activity of the task +has a {@link android.content.Intent#CATEGORY_LAUNCHER} intent filter; see the <a +href="#Starting">Starting a task</a> section below).</p> +</li> + + <li>When an activity has its <a +href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">{@code +allowTaskReparenting}</a> attribute set to {@code "true"}. + <p>In this case, the activity can move from the task it starts to the task it has an affinity +for, when that task comes to the foreground.</p> + <p>For example, suppose that an activity that reports weather conditions in selected cities is +defined as part of a travel application. It has the same affinity as other activities in the same +application (the default application affinity) and it allows re-parenting with this attribute. +When one of your activities starts the weather reporter activity, it initially belongs to the same +task as your activity. However, when the travel application's task comes to the foreground, the +weather reporter activity is reassigned to that task and displayed within it.</p> +</li> +</ul> + +<p class="note"><strong>Tip:</strong> If an {@code .apk} file contains more than one "application" +from the user's point of view, you probably want to use the <a +href="{@docRoot}guide/topics/manifest/activity-element.html#aff">{@code taskAffinity}</a> +attribute to assign different affinities to the activities associated with each "application".</p> + + + +<h3 id="Clearing">Clearing the back stack</h3> + +<p>If the user leaves a task for a long time, the system clears the task of all activities except +the root activity. When the user returns to the task again, only the root activity is restored. +The system behaves this way, because, after an extended amount of time, users likely have abandoned +what they were doing before and are returning to the task to begin something new. </p> + +<p>There are some activity attributes that you can use to modify this behavior: </p> + +<dl> +<dt><code><a +href="{@docRoot}guide/topics/manifest/activity-element.html#always">alwaysRetainTaskState</a></code> +</dt> +<dd>If this attribute is set to {@code "true"} in the root activity of a task, +the default behavior just described does not happen. +The task retains all activities in its stack even after a long period.</dd> + +<dt><code><a +href="{@docRoot}guide/topics/manifest/activity-element.html#clear">clearTaskOnLaunch</a></code></dt> +<dd>If this attribute is set to {@code "true"} in the root activity of a task, +the stack is cleared down to the root activity whenever the user leaves the task +and returns to it. In other words, it's the opposite of <a +href="{@docRoot}guide/topics/manifest/activity-element.html#always">{@code +alwaysRetainTaskState}</a>. The user always returns to the task in its +initial state, even after a leaving the task for only a moment.</dd> + +<dt><code><a +href="{@docRoot}guide/topics/manifest/activity-element.html#finish">finishOnTaskLaunch</a></code> +</dt> +<dd>This attribute is like <a +href="{@docRoot}guide/topics/manifest/activity-element.html#clear">{@code clearTaskOnLaunch}</a>, +but it operates on a +single activity, not an entire task. It can also cause any activity to go +away, including the root activity. When it's set to {@code "true"}, the +activity remains part of the task only for the current session. If the user +leaves and then returns to the task, it is no longer present.</dd> +</dl> + + + + +<h3 id="Starting">Starting a task</h3> + +<p>You can set up an activity as the entry point for a task by giving it an intent filter with +{@code "android.intent.action.MAIN"} as the specified action and {@code +"android.intent.category.LAUNCHER"} as the specified category. For example:</p> + +<pre> +<activity ... > + <intent-filter ... > + <action android:name="android.intent.action.MAIN" /> + <category android:name="android.intent.category.LAUNCHER" /> + </intent-filter> + ... +</activity> +</pre> + +<p>An intent filter of this kind causes an icon and label for the +activity to be displayed in the application launcher, giving users a way to launch the activity and +to return to the task that it creates any time after it has been launched. +</p> + +<p>This second ability is important: Users must be able to leave a task and then come back to it +later using this activity launcher. For this reason, the two <a href="#LaunchModes">launch +modes</a> that mark activities as always initiating a task, {@code "singleTask"} and "{@code +"singleInstance"}, should be used only when the activity has an {@link +android.content.Intent#ACTION_MAIN} +and a {@link android.content.Intent#CATEGORY_LAUNCHER} +filter. Imagine, for example, what could happen if the filter is missing: An intent launches a +{@code "singleTask"} activity, initiating a new task, and the user spends some time working in +that task. The user then presses the HOME key. The task is now sent to the background and not +visible. Because it is not represented in the application launcher, the user has no way to return to +the task. +</p> + +<p>For those cases where you don't want the user to be able to return to an activity, set the + <code><a +href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element's +<a href="{@docRoot}guide/topics/manifest/activity-element.html#finish">{@code +finishOnTaskLaunch}</a> to {@code "true"} (see <a +href="#Clearing">Clearing the stack</a>).</p> + + + + +<h2>Beginner's Path</h2> + +<p>For more information about how to use intents to +activate other application components and publish the intents to which your components +respond, continue with the <b><a +href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent +Filters</a></b> document.</p> diff --git a/docs/html/guide/topics/graphics/2d-graphics.jd b/docs/html/guide/topics/graphics/2d-graphics.jd index e46dbb4..acb6f9f2 100644 --- a/docs/html/guide/topics/graphics/2d-graphics.jd +++ b/docs/html/guide/topics/graphics/2d-graphics.jd @@ -257,9 +257,9 @@ and saved into the <code>res/drawable/</code> directory of your project. <p> The border is used to define the stretchable and static areas of the image. You indicate a stretchable section by drawing one (or more) 1-pixel-wide - black line(s) in the left and top part of the border. (You can have as - many stretchable sections as you want.) The relative size of the stretchable - sections stays the same, so the largest sections always remain the largest. + black line(s) in the left and top part of the border (the other border pixels should + be fully transparent or white). You can have as many stretchable sections as you want: + their relative size stays the same, so the largest sections always remain the largest. </p> <p> You can also define an optional drawable section of the image (effectively, diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd index e030a4c..2648cb7 100644 --- a/docs/html/guide/topics/manifest/activity-element.jd +++ b/docs/html/guide/topics/manifest/activity-element.jd @@ -290,7 +290,8 @@ activity is ignored. The activity is not re-parented, but destroyed. <dd>An icon representing the activity. The icon is displayed to users when a representation of the activity is required on-screen. For example, icons for activities that initiate tasks are displayed in the launcher window. -The icon is often accompanied by a label (see the {@code label} attribute). +The icon is often accompanied by a label (see the <a href="#label">{@code +android:label}</a> attribute). </p> <p> diff --git a/docs/html/guide/topics/manifest/application-element.jd b/docs/html/guide/topics/manifest/application-element.jd index 9ac07fd..1fadc6e 100644 --- a/docs/html/guide/topics/manifest/application-element.jd +++ b/docs/html/guide/topics/manifest/application-element.jd @@ -12,6 +12,7 @@ page.title=<application> android:<a href="#icon">icon</a>="<i>drawable resource</i>" android:<a href="#killrst">killAfterRestore</a>=["true" | "false"] android:<a href="#label">label</a>="<i>string resource</i>" + android:<a href="#logo">logo</a>="<i>drawable resource</i>" android:<a href="#space">manageSpaceActivity</a>="<i>string</i>" android:<a href="#nm">name</a>="<i>string</i>" android:<a href="#prmsn">permission</a>="<i>string</i>" @@ -121,7 +122,7 @@ each of the application's components. See the individual <p> This attribute must be set as a reference to a drawable resource containing -the image definition. There is no default icon. +the image (for example {@code "@drawable/icon"}). There is no default icon. </p></dd> <dt><a name="killrst"></a>{@code android:killAfterRestore}</dt> @@ -154,6 +155,11 @@ However, as a convenience while you're developing the application, it can also be set as a raw string. </p></dd> +<dt><a name="logo"></a>{@code android:logo}</dt> +<dd>A logo for the application as whole, and the default logo for activities. +<p>This attribute must be set as a reference to a drawable resource containing +the image (for example {@code "@drawable/logo"}). There is no default logo.</p></dd> + <dt><a name="space"></a>{@code android:manageSpaceActivity}</dt> <dd>The fully qualified name of an Activity subclass that the system can launch to let users manage the memory occupied by the application diff --git a/docs/html/guide/topics/resources/menu-resource.jd b/docs/html/guide/topics/resources/menu-resource.jd index cde72bd..7bcd78a 100644 --- a/docs/html/guide/topics/resources/menu-resource.jd +++ b/docs/html/guide/topics/resources/menu-resource.jd @@ -36,22 +36,23 @@ In XML: <code>@[<em>package</em>:]menu.<em>filename</em></code> <?xml version="1.0" encoding="utf-8"?> <<a href="#menu-element">menu</a> xmlns:android="http://schemas.android.com/apk/res/android"> <<a href="#item-element">item</a> android:id="@[+][<em>package</em>:]id/<em>resource_name</em>" - android:menuCategory=["container" | "system" | "secondary" | "alternative"] - android:orderInCategory="<em>integer</em>" android:title="<em>string</em>" android:titleCondensed="<em>string</em>" android:icon="@[package:]drawable/<em>drawable_resource_name</em>" + android:showAsAction=["ifRoom" | "never" | "withText" | "always"] android:alphabeticShortcut="<em>string</em>" android:numericShortcut="<em>string</em>" android:checkable=["true" | "false"] android:visible=["visible" | "invisible" | "gone"] - android:enabled=["enabled" | "disabled"] /> + android:enabled=["enabled" | "disabled"] + android:menuCategory=["container" | "system" | "secondary" | "alternative"] + android:orderInCategory="<em>integer</em>" /> <<a href="#group-element">group</a> android:id="@[+][<em>package</em>:]id/<em>resource name</em>" - android:menuCategory=["container" | "system" | "secondary" | "alternative"] - android:orderInCategory="<em>integer</em>" android:checkableBehavior=["none" | "all" | "single"] android:visible=["visible" | "invisible" | "gone"] - android:enabled=["enabled" | "disabled"] > + android:enabled=["enabled" | "disabled"] + android:menuCategory=["container" | "system" | "secondary" | "alternative"] + android:orderInCategory="<em>integer</em>" > <<a href="#item-element">item</a> /> </group> <<a href="#item-element">item</a> > @@ -77,91 +78,120 @@ In XML: <code>@[<em>package</em>:]menu.<em>filename</em></code> <code>"http://schemas.android.com/apk/res/android"</code>. </dl> </dd> - <dt id="group-element"><code><group></code></dt> - <dd>A menu group (to create a collection of items that share traits, such as whether they are -visible, enabled, or checkable). Contains one or more <code><item></code> elements. Must be a -child of a <code><menu></code> element. + + <dt id="item-element"><code><item></code></dt> + <dd>A menu item. May contain a <code><menu></code> element (for a Sub + Menu). Must be a child of a <code><menu></code> or <code><group></code> element. <p class="caps">attributes:</p> <dl class="atn-list"> <dt><code>android:id</code></dt> <dd><em>Resource ID</em>. A unique resource ID. To create a new resource ID for this item, use the form: -<code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new ID.</dd> +<code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new +ID.</dd> + <dt><code>android:title</code></dt> + <dd><em>String</em>. The menu title.</dd> + <dt><code>android:titleCondensed</code></dt> + <dd><em>String</em>. A condensed title, for situations in which the normal title is +too long.</dd> + <dt><code>android:icon</code></dt> + <dd><em>Drawable resource</em>. An image to be used as the menu item icon.</dd> + + <dt><code>android:showAsAction</code></dt> + <dd><em>Keyword</em>. When and how this item should appear as an action item in the Action +Bar. A menu item can appear as an action item only when the activity includes an {@link +android.app.ActionBar} (introduced in API Level HONEYCOMB). Valid values: + <table> + <tr><th>Value</th><th>Description</th></tr> + <tr><td><code>ifRoom</code></td><td>Only place this item in the Action Bar if +there is room for it.</td></tr> + <tr><td><code>withText</code></td><td>Also include the title text (defined +by {@code android:title}) with the action item. You can include this value along with one +of the others as a flag set, by separating them with a pipe {@code |}.</td></tr> + <tr><td><code>never</code></td><td>Never place this item in the Action Bar.</td></tr> + <tr><td><code>always</code></td><td>Always place this item in the Action Bar. +Avoid using this unless it's critical that the item always appear in the action +bar. Setting multiple items to always appear as action items can result in them overlapping +with other UI in the action bar.</td></tr> + </table> + <p>See <a href="{@docRoot}guide/topics/ui/actionbar.html">Using the Action Bar</a> for +more information.</p> + <p>Introduced in API Level HONEYCOMB.</p> + </dd> + + <dt><code>android:alphabeticShortcut</code></dt> + <dd><em>Char</em>. A character for the alphabetic shortcut key.</dd> + <dt><code>android:numericShortcut</code></dt> + <dd><em>Integer</em>. A number for the numeric shortcut key.</dd> + <dt><code>android:checkable</code></dt> + <dd><em>Boolean</em>. "true" if the item is checkable.</dd> + <dt><code>android:checked</code></dt> + <dd><em>Boolean</em>. "true" if the item is checked by default.</dd> + <dt><code>android:visible</code></dt> + <dd><em>Boolean</em>. "true" if the item is visible by default.</dd> + <dt><code>android:enabled</code></dt> + <dd><em>Boolean</em>. "true" if the item is enabled by default.</dd> <dt><code>android:menuCategory</code></dt> <dd><em>Keyword</em>. Value corresponding to {@link android.view.Menu} {@code CATEGORY_*} - constants, which define the group's priority. Valid values: + constants, which define the item's priority. Valid values: <table> <tr><th>Value</th><th>Description</th></tr> - <tr><td><code>container</code></td><td>For groups that are part of a + <tr><td><code>container</code></td><td>For items that are part of a container.</td></tr> - <tr><td><code>system</code></td><td>For groups that are provided by the + <tr><td><code>system</code></td><td>For items that are provided by the system.</td></tr> - <tr><td><code>secondary</code></td><td>For groups that are user-supplied secondary + <tr><td><code>secondary</code></td><td>For items that are user-supplied secondary (infrequently used) options.</td></tr> - <tr><td><code>alternative</code></td><td>For groups that are alternative actions + <tr><td><code>alternative</code></td><td>For items that are alternative actions on the data that is currently displayed.</td></tr> </table> </dd> <dt><code>android:orderInCategory</code></dt> - <dd><em>Integer</em>. The default order of the items within the category.</dd> + <dd><em>Integer</em>. The order of "importance" of the item, within a group.</dd> + </dl> + </dd> + + <dt id="group-element"><code><group></code></dt> + <dd>A menu group (to create a collection of items that share traits, such as whether they are +visible, enabled, or checkable). Contains one or more <code><item></code> elements. Must be a +child of a <code><menu></code> element. + <p class="caps">attributes:</p> + <dl class="atn-list"> + <dt><code>android:id</code></dt> + <dd><em>Resource ID</em>. A unique resource ID. To create a new resource ID for this item, +use the form: +<code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new +ID.</dd> <dt><code>android:checkableBehavior</code></dt> <dd><em>Keyword</em>. The type of checkable behavior for the group. Valid values: <table> <tr><th>Value</th><th>Description</th></tr> <tr><td><code>none</code></td><td>Not checkable</td></tr> <tr><td><code>all</code></td><td>All items can be checked (use checkboxes)</td></tr> - <tr><td><code>single</code></td><td>Only one item can be checked (use radio buttons)</td></tr> + <tr><td><code>single</code></td><td>Only one item can be checked (use radio +buttons)</td></tr> </table> </dd> <dt><code>android:visible</code></dt> <dd><em>Boolean</em>. "true" if the group is visible.</dd> <dt><code>android:enabled</code></dt> <dd><em>Boolean</em>. "true" if the group is enabled.</dd> - </dl> - </dd> - <dt id="item-element"><code><item></code></dt> - <dd>A menu item. May contain a <code><menu></code> element (for a Sub - Menu). Must be a child of a <code><menu></code> or <code><group></code> element. - <p class="caps">attributes:</p> - <dl class="atn-list"> - <dt><code>android:id</code></dt> - <dd><em>Resource ID</em>. A unique resource ID. To create a new resource ID for this item, use the form: -<code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new ID.</dd> <dt><code>android:menuCategory</code></dt> <dd><em>Keyword</em>. Value corresponding to {@link android.view.Menu} {@code CATEGORY_*} - constants, which define the item's priority. Valid values: + constants, which define the group's priority. Valid values: <table> <tr><th>Value</th><th>Description</th></tr> - <tr><td><code>container</code></td><td>For items that are part of a + <tr><td><code>container</code></td><td>For groups that are part of a container.</td></tr> - <tr><td><code>system</code></td><td>For items that are provided by the + <tr><td><code>system</code></td><td>For groups that are provided by the system.</td></tr> - <tr><td><code>secondary</code></td><td>For items that are user-supplied secondary + <tr><td><code>secondary</code></td><td>For groups that are user-supplied secondary (infrequently used) options.</td></tr> - <tr><td><code>alternative</code></td><td>For items that are alternative actions + <tr><td><code>alternative</code></td><td>For groups that are alternative actions on the data that is currently displayed.</td></tr> </table> </dd> <dt><code>android:orderInCategory</code></dt> - <dd><em>Integer</em>. The order of "importance" of the item, within a group.</dd> - <dt><code>android:title</code></dt> - <dd><em>String</em>. The menu title.</dd> - <dt><code>android:titleCondensed</code></dt> - <dd><em>String</em>. A condensed title, for situations in which the normal title is -too long.</dd> - <dt><code>android:icon</code></dt> - <dd><em>Drawable resource</em>. An image to be used as the menu item icon.</dd> - <dt><code>android:alphabeticShortcut</code></dt> - <dd><em>Char</em>. A character for the alphabetic shortcut key.</dd> - <dt><code>android:numericShortcut</code></dt> - <dd><em>Integer</em>. A number for the numeric shortcut key.</dd> - <dt><code>android:checkable</code></dt> - <dd><em>Boolean</em>. "true" if the item is checkable.</dd> - <dt><code>android:checked</code></dt> - <dd><em>Boolean</em>. "true" if the item is checked by default.</dd> - <dt><code>android:visible</code></dt> - <dd><em>Boolean</em>. "true" if the item is visible by default.</dd> - <dt><code>android:enabled</code></dt> - <dd><em>Boolean</em>. "true" if the item is enabled by default.</dd> + <dd><em>Integer</em>. The default order of the items within the category.</dd> </dl> </dd> </dl> @@ -174,7 +204,8 @@ too long.</dd> <menu xmlns:android="http://schemas.android.com/apk/res/android"> <item android:id="@+id/item1" android:title="@string/item1" - android:icon="@drawable/group_item1_icon" /> + android:icon="@drawable/group_item1_icon" + android:showAsAction="ifRoom|withText"/> <group android:id="@+id/group"> <item android:id="@+id/group_item1" android:title="@string/group_item1" @@ -184,7 +215,8 @@ too long.</dd> android:icon="@drawable/group_item2_icon" /> </group> <item android:id="@+id/submenu" - android:title="@string/submenu_title" > + android:title="@string/submenu_title" + android:showAsAction="ifRoom|withText" > <menu> <item android:id="@+id/submenu_item1" android:title="@string/submenu_item1" /> @@ -201,6 +233,8 @@ public boolean onCreateOptionsMenu(Menu menu) { return true; } </pre> +<p class="note"><strong>Note:</strong> The {@code android:showAsAction} attribute is +available only on Android X.X (API Level HONEYCOMB) and greater.</p> </dd> <!-- end example --> diff --git a/docs/html/guide/topics/resources/string-resource.jd b/docs/html/guide/topics/resources/string-resource.jd index 81c5d55..2db38f1 100644 --- a/docs/html/guide/topics/resources/string-resource.jd +++ b/docs/html/guide/topics/resources/string-resource.jd @@ -12,8 +12,8 @@ your application with strings:</p> <dd>XML resource that provides a single string.</dd> <dt><a href="#StringArray">String Array</a></dt> <dd>XML resource that provides an array of strings.</dd> - <dt><a href="#Plurals">Plurals</a></dt> - <dd>XML resource that carries different strings for different pluralizations + <dt><a href="#Plurals">Quantity Strings (Plurals)</a></dt> + <dd>XML resource that carries different strings for different quantities of the same word or phrase.</dd> </dl> @@ -218,13 +218,30 @@ getStringArray}(R.array.planets_array); -<h2 id="Plurals">Plurals</h2> +<h2 id="Plurals">Quantity Strings (Plurals)</h2> -<p>A pair of strings that each provide a different plural form of the same word or phrase, -which you can collectively reference from the application. When you request the plurals -resource using a method such as {@link android.content.res.Resources#getQuantityString(int,int) -getQuantityString()}, you must pass a "count", which will determine the plural form you -require and return that string to you.</p> +<p>Different languages have different rules for grammatical agreement with quantity. In English, +for example, the quantity 1 is a special case. We write "1 book", but for any other quantity we'd +write "<i>n</i> books". This distinction between singular and plural is very common, but other +languages make finer distinctions. The full set supported by Android is <code>zero</code>, +<code>one</code>, <code>two</code>, <code>few</code>, <code>many</code>, and <code>other</code>. + +<p>The rules for deciding which case to use for a given language and quantity can be very complex, +so Android provides you with methods such as +{@link android.content.res.Resources#getQuantityString(int,int) getQuantityString()} to select +the appropriate resource for you. + +<p>Note that the selection is made based on grammatical necessity. A string for <code>zero</code> +in English will be ignored even if the quantity is 0, because 0 isn't grammatically different +from 2, or any other number except 1 ("zero books", "one book", "two books", et cetera). +Don't be misled either by the fact that, say, <code>two</code> sounds like it could only apply to +the quantity 2: a language may require that 2, 12, 102 (et cetera) are all treated like one +another but differently to other quantities. Rely on your translator to know what distinctions +their language actually insists upon. + +<p>It's often possible to avoid quantity strings by using quantity-neutral formulations such as +"Books: 1". This will make your life and your translators' lives easier, if it's a style that's +in keeping with your application. <p class="note"><strong>Note:</strong> A plurals collection is a simple resource that is referenced using the value provided in the {@code name} attribute (not the name of the XML @@ -251,7 +268,7 @@ In Java: <code>R.plurals.<em>plural_name</em></code> <<a href="#plurals-element">plurals</a> name="<em>plural_name</em>"> <<a href="#plurals-item-element">item</a> - quantity=["one" | "other"] + quantity=["zero" | "one" | "two" | "few" | "many" | "other"] ><em>text_string</em></item> </plurals> </resources> @@ -285,16 +302,27 @@ Styling</a>, below, for information about to properly style and format your stri <p class="caps">attributes:</p> <dl class="atn-list"> <dt><code>quantity</code></dt> - <dd><em>Keyword</em>. A value indicating the case in which this string should be used. Valid -values: + <dd><em>Keyword</em>. A value indicating when this string should be used. Valid +values, with non-exhaustive examples in parentheses: <table> <tr><th>Value</th><th>Description</th></tr> <tr> - <td>{@code one}</td><td>When there is one (a singular string).</td> + <td>{@code zero}</td><td>When the language requires special treatment of the number 0 (as in Arabic).</td> + </tr> + <tr> + <td>{@code one}</td><td>When the language requires special treatment of numbers like one (as with the number 1 in English and most other languages; in Russian, any number ending in 1 but not ending in 11 is in this class).</td> + </tr> + <tr> + <td>{@code two}</td><td>When the language requires special treatment of numbers like two (as in Welsh).</td> + </tr> + <tr> + <td>{@code few}</td><td>When the language requires special treatment of "small" numbers (as with 2, 3, and 4 in Czech; or numbers ending 2, 3, or 4 but not 12, 13, or 14 in Polish).</td> </tr> <tr> - <td>{@code other}</td><td>When the quantity is anything other than one (a plural -string, but also used when the count is zero).</td> + <td>{@code many}</td><td>When the language requires special treatment of "large" numbers (as with numbers ending 11-99 in Maltese).</td> + </tr> + <tr> + <td>{@code other}</td><td>When the language does not require special treatment of the given quantity.</td> </tr> </table> </dd> @@ -315,6 +343,17 @@ string, but also used when the count is zero).</td> </plurals> </resources> </pre> + <p>XML file saved at {@code res/values-pl/strings.xml}:</p> +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <plurals name="numberOfSongsAvailable"> + <item quantity="one">Znaleziono jedną piosenkę.</item> + <item quantity="few">Znaleziono %d piosenki.</item> + <item quantity="other">Znaleziono %d piosenek.</item> + </plurals> +</resources> +</pre> <p>Java code:</p> <pre> int count = getNumberOfsongsAvailable(); diff --git a/docs/html/guide/topics/ui/actionbar.jd b/docs/html/guide/topics/ui/actionbar.jd new file mode 100644 index 0000000..2b942e7 --- /dev/null +++ b/docs/html/guide/topics/ui/actionbar.jd @@ -0,0 +1,332 @@ +page.title=Using the Action Bar +parent.title=User Interface +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Quickview</h2> + <ul> + <li>A replacement for the title bar for displaying global actions for the activity</li> + <li>Provides toolbar actions and modes of navigating around the application</li> + <li>Switches to contextual menu options when one or more items are selected</li> + <li>Requires API Level HONEYCOMB</li> + </ul> + + <h2>In this document</h2> + <ol> + <li><a href="#Adding">Adding the Action Bar</a></li> + <li><a href="#ActionItems">Adding Action Items</a> + <ol> + <li><a href="#Home">Using the application icon as an action item</a></li> + </ol> + </li> + <li><a href="#Tabs">Adding Tabs</a></li> + <li><a href="#Dropdown">Adding Drop-down Navigation</a></li> + <li><a href="#Search">Adding Search</a></li> + </ol> + + <h2>Key classes</h2> + <ol> + <li>{@link android.app.ActionBar}</li> + <li>{@link android.view.Menu}</li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}guide/topics/ui/menus.html">Creating Menus</a></li> + </ol> +</div> +</div> + +<p>The action bar is a widget for activities that replaces the traditional title bar at +the top of an activity. By default, the action bar includes the application logo on the left side, +followed by the activity title. The action bar offers several useful features for +applications—especially those targeted to tablet devices. The action bar features include +the ability to:</p> + +<ul> + <li>Display menu items from the <a +href="{@docRoot}guide/topics/ui/menus.html#OptionsMenu">options menu</a> as "action +items"—providing instant access to key user actions.</li> + <li>Provide tabs for navigating between <a +href="{@docRoot}guide/topics/fragments/index.html">fragments</a>.</li> + <li>Provide drop-down navigation items.</li> + <li>Embed a {@link android.widget.SearchView} for instant searching.</li> + <li>Use the application logo as a "return home" or "up" navigation action.</li> +</ul> + +<img src="{@docRoot}images/ui/actionbar.png" height="36" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> A screenshot of the action bar in the NotePad +sample application, containing action items to save and delete the note.</p> + + +<h2 id="Adding">Adding the Action Bar</h2> + +<p>To add the Action Bar to your activity, apply the holographic theme—{@code +Theme.Holo}—or the action bar theme—{@code Theme.WithActionBar}—in your manifest +file. For example:</p> + +<pre> +<activity android:theme="@android:style/Theme.Holo" > +</pre> + +<p>The activity now appears with the action bar in place of the traditional title bar.</p> + + +<h2 id="ActionItems">Adding Action Items</h2> + +<p>For each action item you want to add to the action bar, you must add a menu item to the +activity's <a href="{@docRoot}guide/topics/ui/menus.html#OptionsMenu">options menu</a> and declare +that the item be shown as an action, using the {@code android:showAsAction} attribute in the menu +XML or with {@link android.view.MenuItem#setShowAsAction setShowAsAction()} on the {@link +android.view.MenuItem}.</p> + +<div class="figure" style="width:359px"> + <img src="{@docRoot}images/ui/actionbar-item-withtext.png" height="57" alt="" /> + <p class="img-caption"><strong>Figure 2.</strong> A screenshot from an action bar with two +action items.</p> +</div> + +<p>You can specify a menu item to appear as an action item in the action bar—if there is room +for it—from the <a href="{@docRoot}guide/topics/resources/menu-resource.html">menu +resource</a> by declaring {@code +android:showAsAction="ifRoom"} for the {@code <item>} element. This way, the item will display +in the action bar for quick access only if there is room available for it—if there's not +enough room, the item is placed the options menu (revealed by the drop-down icon on the right side +of the action bar). From your application code, you can specify the item to appear as an action item +by calling {@link android.view.MenuItem#setShowAsAction setShowAsAction()} on the {@link +android.view.MenuItem} and passing {@link android.view.MenuItem#SHOW_AS_ACTION_IF_ROOM}.</p> + +<p>If your item supplies both a title and an icon, then the action item shows only +the icon by defult. If you want to include the text with the action item, add the <em>with text</em> +flag—in XML, add {@code withText} to the {@code android:showAsAction} attribute or, in +your application code, use the {@link android.view.MenuItem#SHOW_AS_ACTION_WITH_TEXT} flag when +calling {@link android.view.MenuItem#setShowAsAction setShowAsAction()}. Figure 2 shows a screenshot +of an action bar with two action items that include text.</p> + +<p>Here's an example of how you can declare a menu item as an action item in a <a +href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a> file:</p> +<pre> +<?xml version="1.0" encoding="utf-8"?> +<menu xmlns:android="http://schemas.android.com/apk/res/android"> + <item android:id="@+id/menu_add" + android:icon="@drawable/ic_menu_save" + android:title="@string/menu_save" + <b>android:showAsAction="ifRoom|withText"</b> /> +</menu> +</pre> + +<p>In this case, both the {@code ifRoom} and {@code withText} flags are set, so that when this +item appears as an action item, it includes the title text along with the icon.</p> + +<p>A menu item placed in the action bar triggers the same callback methods as other items in the +options menu. When the user selects an item in the action bar, your activity receives a call to +{@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}, passing the +item ID. (If you added the item from a fragment, then the respective {@link +android.app.Fragment#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} method is called +for that fragment.)</p> + +<p class="note"><strong>Note:</strong> Even menu items that are contained in the options menu +(and not shown as action items) will show an icon, so when using the action bar, you should +provide an icon for every item in the options menu.</p> + +<p>You can also declare an item to <em>always</em> appear as an action item, but you should avoid +doing so. Most of the time, there will be enough room for several action items and they will appear +in the order you declare them. If you set items to always appear as action +items (instead of <em>if room</em>), then they are added without discrimination and there is a risk +that they will collide with other elements in the action bar, such as tabs or custom views.</p> + +<p>For more information about menus, see the <a +href="{@docRoot}guide/topics/ui/menus.html#options-menu">Creating Menus</a> developer guide.</p> + + +<h3 id="Home">Using the application icon as an action item</h3> + +<p>By default, the application icon appears in the action bar on the left side, but does nothing +when tapped. To use the application icon as an action item when tapped, you simply need to add a +condition to your {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method +that performs an action when the {@link android.view.MenuItem} ID is {@code android.R.id.home}. +This ID is delivered every time the user taps the application icon.</p> + +<p>For example, here's an implementation of {@link android.app.Activity#onOptionsItemSelected +onOptionsItemSelected()} that returns to the application's "home" activity:</p> + +<pre> +@Override +public boolean onOptionsItemSelected(MenuItem item) { + switch (item.getItemId()) { + case android.R.id.home: + // app icon in action bar clicked; go home + Intent intent = new Intent(this, HomeActivity.class); + startActivity(intent); + break; + } + return super.onOptionsItemSelected(item); +} +</pre> + +<div class="figure" style="width:144px"> + <img src="{@docRoot}images/ui/actionbar-logo.png" height="140" alt="" /> + <p class="img-caption"><strong>Figure 3.</strong> The standard icon for the Email application +(top) and the "up navigation" icon (bottom).</p> +</div> + +<p>You can also use the application icon to provide "up" navigation. The way you handle the event +when a user taps the icon is the same, but if the user experience for the event is to <em>navigate +up to the parent activity</em>, then you should indicate this behavior by setting the +action bar to "show home as up." You can do so by calling {@link +android.app.ActionBar#setDisplayOptions setDisplayOptions()} on your activity's {@link +android.app.ActionBar}, and passing the {@link +android.app.ActionBar#DISPLAY_HOME_AS_UP} display option.</p> + +<p>To get the {@link android.app.ActionBar}, call {@link android.app.Activity#getActionBar} from +your {@link android.app.Activity} during {@link android.app.Activity#onCreate onCreate()} (but be +sure you do so <em>after</em> you've called {@link android.app.Activity#setContentView +setContentView()}).</p> + +<p>For example, here's how you can change the action bar display mode to show the application +icon as an "up" action:</p> + +<pre> +@Override +protected void onStart() { + super.onStart(); + ActionBar actionBar = this.getActionBar(); + actionBar.setDisplayOptions(ActionBar.DISPLAY_HOME_AS_UP, ActionBar.DISPLAY_HOME_AS_UP); +} +</pre> + +<p class="caution"><strong>Caution:</strong> If your activity does not have an action bar (if you +did not set the theme of your activity or application to the holographic or action bar theme), then +{@link android.app.Activity#getActionBar} returns null.</p> + + +<h2 id="Tabs">Adding Tabs</h2> + +<p>The action bar can display tabs that allow the user navigate between different fragments in the +activity. Each tab can include a title and/or an icon.</p> + +<p>To begin, your layout must include a {@link android.view.View} in which each {@link +android.app.Fragment} associated with a tab is displayed. Be sure the view has an ID that you +can use to reference it from your code.</p> + +<p>To add tabs to the action bar:</p> +<ol> + <li>Create an implementation of {@link android.app.ActionBar.TabListener} to handle the +interaction events on the action bar tabs. You must implement all methods: {@link +android.app.ActionBar.TabListener#onTabSelected onTabSelected()}, {@link +android.app.ActionBar.TabListener#onTabUnselected onTabUnselected()}, and {@link +android.app.ActionBar.TabListener#onTabReselected onTabReselected()}. + <p>Each callback method passes the {@link android.app.ActionBar.Tab} that received the +event and a {@link android.app.FragmentTransaction} for you to perform the fragment +transactions (add or remove fragments).</p> + <p>For example:</p> +<pre> +private class MyTabListener implements ActionBar.TabListener { + private TabContentFragment mFragment; + + // Called to create an instance of the listener when adding a new tab + public TabListener(TabContentFragment fragment) { + mFragment = fragment; + } + + @Override + public void onTabSelected(Tab tab, FragmentTransaction ft) { + ft.add(R.id.fragment_content, mFragment, null); + } + + @Override + public void onTabUnselected(Tab tab, FragmentTransaction ft) { + ft.remove(mFragment); + } + + @Override + public void onTabReselected(Tab tab, FragmentTransaction ft) { + // do nothing + } + +} +</pre> + <p>This implementation of {@link android.app.ActionBar.TabListener} adds a constructor +that saves the {@link android.app.Fragment} associated with a tab so that each callback +can add or remove that fragment.</p> + </li> + <li>Get the {@link android.app.ActionBar} for your activity by calling {@link +android.app.Activity#getActionBar} from your {@link android.app.Activity}, during {@link +android.app.Activity#onCreate onCreate()} (but be sure you do so <em>after</em> you've called +{@link android.app.Activity#setContentView setContentView()}).</li> + <li>Call {@link android.app.ActionBar#setNavigationMode(int) +setNavigationMode(NAVIGATION_MODE_TABS)} to enable tab mode for the {@link +android.app.ActionBar}.</li> + <li>Create each tab for the action bar: + <ol> + <li>Create a new {@link android.app.ActionBar.Tab} by calling {@link +android.app.ActionBar#newTab()} on the {@link android.app.ActionBar}.</li> + <li>Add title text and/or an icon for the tab by calling {@link +android.app.ActionBar.Tab#setText setText()} and/or {@link android.app.ActionBar.Tab#setIcon +setIcon()}. + <p class="note"><strong>Tip:</strong> These methods return the same {@link +android.app.ActionBar.Tab} instance, so you can chain the calls together.</p></li> + <li>Declare the {@link android.app.ActionBar.TabListener} to use for the tab by passing an +instance of your implementation to {@link android.app.ActionBar.Tab#setTabListener +setTabListener()}. + </ol> + </li> + <li>Add each {@link android.app.ActionBar.Tab} to the action bar by calling {@link +android.app.ActionBar#addTab addTab()} on the {@link android.app.ActionBar} and passing the +{@link android.app.ActionBar.Tab}.</li> +</ol> +<p>For example, the following code combines steps 2 - 5 to create two tabs and add them to +the action bar:</p> +<pre> +@Override +protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + + // setup action bar for tabs + final ActionBar actionBar = getActionBar(); + actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_TABS); + // remove the activity title to make space for tabs + actionBar.setDisplayOptions(0, ActionBar.DISPLAY_SHOW_TITLE); + + // instantiate fragment for the tab + Fragment artistsFragment = new ArtistsFragment(); + // add a new tab and set its title text and tab listener + bar.addTab(bar.newTab().setText(R.string.tab_artists) + .setTabListener(new TabListener(artistsFragment))); + + Fragment albumsFragment = new AlbumsFragment(); + bar.addTab(bar.newTab().setText(R.string.tab_albums) + .setTabListener(new TabListener(albumsFragment))); +} +</pre> + +<p>All the behaviors that occur when a tab is selected must be defined by your {@link +android.app.ActionBar.TabListener} callback methods. When a tab is selected, it receives a call to +{@link android.app.ActionBar.TabListener#onTabSelected onTabSelected()} and that's where you should +add the appropriate fragment to the designated view in your layout, using {@link +android.app.FragmentTransaction#add add()} with the provided {@link +android.app.FragmentTransaction}. Likewise, when a tab is deselected (because another tab becomes +selected), you should remove that fragment from the layout, using {@link +android.app.FragmentTransaction#remove remove()}.</p> + +<p class="note"><strong>Note:</strong> You <strong>do not</strong> need +to call {@link android.app.FragmentTransaction#commit} for these transactions. You also +<strong>cannot</strong> add these fragment transactions to the back stack.</p> + +<p>If your activity is stopped, you should retain the currently selected tab with the saved state so +that when the user returns to your application, you can open the tab. When it's time to save the +state, you can query the currently selected tab with {@link +android.app.ActionBar#getSelectedNavigationItem()}. This returns the index position of the selected +tab.</p> + +<p class="caution"><strong>Caution:</strong> It's important that you save +the state of each fragment as necessary, so when the user switches fragments with the tabs, +then returns to a previous fragment, it appears the way they left. For information about saving +the state of your fragment, see the <a +href="{@docRoot}guide/topics/fragments/index.html">Fragments</a> developer guide.</p> + + diff --git a/docs/html/guide/topics/ui/declaring-layout.jd b/docs/html/guide/topics/ui/declaring-layout.jd index fe641a2..4d71d28 100644 --- a/docs/html/guide/topics/ui/declaring-layout.jd +++ b/docs/html/guide/topics/ui/declaring-layout.jd @@ -191,10 +191,12 @@ layout parameters for the View that are appropriate for the ViewGroup in which i <p>Every ViewGroup class implements a nested class that extends {@link android.view.ViewGroup.LayoutParams}. This subclass contains property types that define the size and position for each child view, as -appropriate for the view group. As you can see in the figure below, the parent +appropriate for the view group. As you can see in figure 1, the parent view group defines layout parameters for each child view (including the child view group).</p> <img src="{@docRoot}images/layoutparams.png" alt="" height="300" align="center"/> +<p class="img-caption"><strong>Figure 1.</strong> Visualization of a view hierarchy with layout +parameters associated with each view.</p> <p>Note that every LayoutParams subclass has its own syntax for setting values. Each child element must define LayoutParams that are appropriate for its parent, diff --git a/docs/html/guide/topics/ui/dialogs.jd b/docs/html/guide/topics/ui/dialogs.jd index 1a997f9..d50e1cb 100644 --- a/docs/html/guide/topics/ui/dialogs.jd +++ b/docs/html/guide/topics/ui/dialogs.jd @@ -22,20 +22,32 @@ parent.link=index.html </li> <li><a href="#CustomDialog">Creating a Custom Dialog</a></li> </ol> - + <h2>Key classes</h2> <ol> <li>{@link android.app.Dialog}</li> + <li>{@link android.app.AlertDialog}</li> + <li>{@link android.app.DialogFragment}</li> + </ol> + + <h2>Related tutorials</h2> + <ol> + <li><a href="{@docRoot}resources/tutorials/views/hello-datepicker.html">Hello +DatePicker</a></li> + <li><a href="{@docRoot}resources/tutorials/views/hello-timepicker.html">Hello +TimePicker</a></li> </ol> </div> </div> <p>A dialog is usually a small window that appears in front of the current Activity. -The underlying Activity loses focus and the dialog accepts all user interaction. -Dialogs are normally used -for notifications and short activities that directly relate to the application in progress.</p> +The underlying Activity loses focus and the dialog accepts all user interaction. Dialogs are +normally used for notifications that should interupt the user and to perform short tasks that +directly relate to the application in progress (such as a progress bar or a login prompt).</p> -<p>The Android API supports the following types of {@link android.app.Dialog} objects:</p> +<p>The {@link android.app.Dialog} class is the base class for creating dialogs. However, you +typically should not instantiate a {@link android.app.Dialog} directly. Instead, you should use one +of the following subclasses:</p> <dl> <dt>{@link android.app.AlertDialog}</dt> <dd>A dialog that can manage zero, one, two, or three buttons, and/or a list of @@ -473,18 +485,25 @@ public class NotificationTest extends Activity { progressDialog = new ProgressDialog(NotificationTest.this); progressDialog.setProgressStyle(ProgressDialog.STYLE_HORIZONTAL); progressDialog.setMessage("Loading..."); - progressThread = new ProgressThread(handler); - progressThread.start(); return progressDialog; default: return null; } } + @Override + protected void onPrepareDialog(int id, Dialog dialog) { + switch(id) { + case PROGRESS_DIALOG: + progressDialog.setProgress(0); + progressThread = new ProgressThread(handler); + progressThread.start(); + } + // Define the Handler that receives messages from the thread and update the progress final Handler handler = new Handler() { public void handleMessage(Message msg) { - int total = msg.getData().getInt("total"); + int total = msg.arg1; progressDialog.setProgress(total); if (total >= 100){ dismissDialog(PROGRESS_DIALOG); @@ -515,9 +534,7 @@ public class NotificationTest extends Activity { Log.e("ERROR", "Thread Interrupted"); } Message msg = mHandler.obtainMessage(); - Bundle b = new Bundle(); - b.putInt("total", total); - msg.setData(b); + msg.arg1 = total; mHandler.sendMessage(msg); total++; } diff --git a/docs/html/guide/topics/ui/menus.jd b/docs/html/guide/topics/ui/menus.jd index b4e467c..ce25b9f 100644 --- a/docs/html/guide/topics/ui/menus.jd +++ b/docs/html/guide/topics/ui/menus.jd @@ -36,6 +36,7 @@ parent.link=index.html <h2>See also</h2> <ol> + <li><a href="{@docRoot}guide/topics/ui/actionbar.html">Using the Action Bar</a></li> <li><a href="{@docRoot}guide/topics/resources/menu-resource.html">Menu Resource</a></li> </ol> </div> @@ -48,20 +49,9 @@ for you to provide application menus in your application.</p> <p>Android provides three types of application menus:</p> <dl> <dt><strong>Options Menu</strong></dt> - <dd>The primary menu for an Activity, which appears when the user presses - the device MENU key. Within the Options Menu are two groups: - <dl style="margin-top:1em"> - <dt><em>Icon Menu</em></dt> - <dd>The menu items visible at the bottom of the screen - at the press of the MENU key. It supports a maximum of six menu items. - These are the only menu items that support icons and the only menu items that <em>do not</em> support - checkboxes or radio buttons.</dd> - <dt><em>Expanded Menu</em></dt> - <dd>The vertical list of menu items exposed by the "More" menu item in the Icon Menu. - When the Icon Menu is full, the expanded menu is comprised of the sixth - menu item and the rest.</dd> - </dl> - </dd> + <dd>The primary collection of menu items for an Activity that is associated with the device MENU +key. To provide instant access to select menu items, you can place some items in the <a +href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>, if available.</dd> <dt><strong>Context Menu</strong></dt> <dd>A floating list of menu items that appears when the user performs a long-press on a View. </dd> @@ -74,7 +64,7 @@ Menu or a context menu. A submenu item cannot support a nested submenu. </dd> <h2 id="xml">Defining Menus</h2> -<p>Instead of instantiating {@link android.view.Menu} objects in your application code, you should +<p>Instead of instantiating a {@link android.view.Menu} in your application code, you should define a menu and all its items in an XML <a href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>, then inflate the menu resource (load it as a programmable object) in your application code. Defining your menus in XML is @@ -104,9 +94,9 @@ href="#groups">Menu groups</a>.</dd> <item android:id="@+id/new_game" android:icon="@drawable/ic_new_game" android:title="@string/new_game" /> - <item android:id="@+id/quit" - android:icon="@drawable/ic_quit" - android:title="@string/quit" /> + <item android:id="@+id/help" + android:icon="@drawable/ic_help" + android:title="@string/help" /> </menu> </pre> @@ -161,36 +151,64 @@ creating an option menu is discussed more in the next section.)</p> </div> -<p>The Options Menu is where you should include basic application functions -and necessary navigation items (for example, a button -to open application settings). The user -can open the Options Menu with the device MENU key. -Figure 1 shows a screenshot of an Options Menu.</p> +<p>The Options Menu is where you should include basic application functions and necessary navigation +items (for example, a button to open the application settings). Items in the Options Menu are +accessible in two distinct ways: in the Action Bar and in the menu revealed by the MENU +key.</p> + +<p>The Action Bar is an optional widget that appears at the top of the activity in place of the +title bar. It can display several menu items that you choose from the Options Menu, but items in +the Action Bar display only an icon (no title text). Users can reveal the other menu items in the +Options Menu with the MENU key.</p> -<p>When opened, the first visible portion of the Options Menu is called the Icon Menu. It -holds the first six menu items. -If you add more than six items to the Options Menu, Android places the sixth item and those after it -into the Expanded Menu, which the user can open with the "More" menu item.</p> +<p>If you include the Action Bar in your activity, the menu items that are not placed in the Action +Bar can appear in two different styles:</p> +<dl> + <dt>Action Bar Menu</dt> + <dd>If the device has an extra-large screen ({@code xlarge}), then all items in the Options Menu +that are not placed in the Action Bar are placed into a drop-down list at the right side of the +Action Bar, with icons and title text. The user can reveal the drop-down list by pressing the +drop-down icon in the Action Bar or the MENU key.</dd> + <dt>Standard Options Menu</dt> + <dd>If the device <em>does not</em> have an extra-large screen, then all items in the Options +Menu that are not placed in the Action Bar are placed into the Standard Options Menu at the bottom +of the activity. The user can reveal the standard Options Menu by pressing the MENU key. + <p>The first visible portion of the Standard Options Menu is called the Icon Menu. +It holds the first six menu items (excluding any added to the Action Bar), with icons and title +text. If there are more than six items, Android adds a "More" item as the sixth menu item and places +the remaining items into the Expanded Menu, which the user can open by selecting "More". The +Expanded Menu displays menu items only by their title text (no icon)</p> + </dd> +</dl> <p>When the user opens the Options Menu for the first time, Android calls your Activity's {@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} method. Override this method in your Activity and populate the {@link android.view.Menu} that is passed into the method. Populate the {@link android.view.Menu} by inflating a menu resource as described in <a -href="#Inflating">Inflating a Menu Resource</a>. (You can -also populate the menu in code, using {@link android.view.Menu#add(int,int,int,int) -add()} to add menu items.)</p> +href="#Inflating">Inflating a Menu Resource</a>. For example:</p> -<p>When the user selects a menu item from the Options Menu, the system calls your Activity's +<pre> +@Override +public boolean onCreateOptionsMenu(Menu menu) { + MenuInflater inflater = getMenuInflater(); + inflater.inflate(R.menu.game_menu, menu); + return true; +} +</pre> + +<p>(You can also populate the menu in code, using {@link android.view.Menu#add(int,int,int,int) +add()} to add items to the {@link android.view.Menu}.)</p> + +<p>When the user selects a menu item from the Options Menu (including items selected from the +Action Bar), the system calls your Activity's {@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} method. This method passes the {@link android.view.MenuItem} that the user selected. You can identify the menu item by calling {@link android.view.MenuItem#getItemId()}, which returns the unique ID for the menu item (defined by the {@code android:id} attribute in the menu resource or with an integer passed to the {@link android.view.Menu#add(int,int,int,int) add()} method). You can match this ID -against known menu items and perform the appropriate action.</p> - -<p>For example:</p> +against known menu items and perform the appropriate action. For example:</p> <pre> @Override @@ -200,8 +218,8 @@ public boolean onOptionsItemSelected(MenuItem item) { case R.id.new_game: newGame(); return true; - case R.id.quit: - quit(); + case R.id.help: + showHelp(); return true; default: return super.onOptionsItemSelected(item); @@ -224,8 +242,8 @@ an Activity that implements nothing except the {@link android.app.Activity#onCre onCreateOptionsMenu()} and {@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} methods. Then extend this class for each Activity that should share the same Options Menu. This way, you have to manage only one set of code for handling menu -actions and each decendent class inherits the menu behaviors.<br/><br/> -If you want to add menu items to one of your decendent activities, +actions and each descendant class inherits the menu behaviors.<br/><br/> +If you want to add menu items to one of your descendant activities, override {@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} in that Activity. Call {@code super.onCreateOptionsMenu(menu)} so the original menu items are created, then add new menu items with {@link @@ -542,7 +560,7 @@ hardware keyboard. Shortcuts cannot be added to items in a Context Menu.</p> <h3 id="intents">Intents for menu items</h3> <p>Sometimes you'll want a menu item to launch an Activity using an Intent (whether it's an -Actvitity in your application or another application). When you know the Intent you want to use and +Activity in your application or another application). When you know the Intent you want to use and have a specific menu item that should initiate the Intent, you can execute the Intent with {@link android.app.Activity#startActivity(Intent) startActivity()} during the appropriate on-item-selected callback method (such as the {@link android.app.Activity#onOptionsItemSelected(MenuItem) diff --git a/docs/html/guide/tutorials/notepad/notepad-ex2.jd b/docs/html/guide/tutorials/notepad/notepad-ex2.jd index a945a62..854731f 100644 --- a/docs/html/guide/tutorials/notepad/notepad-ex2.jd +++ b/docs/html/guide/tutorials/notepad/notepad-ex2.jd @@ -87,8 +87,8 @@ Open the Notepadv2 class.</p> menu callback used for the options menu. Here, we add just one line, which will add a menu item to delete a note. Call <code>menu.add()</code> like so: <pre> -public boolean onCreateContextMenu(Menu menu, View v - ContextMenuInfo menuInfo) { +public void onCreateContextMenu(Menu menu, View v, + ContextMenu.ContextMenuInfo menuInfo) { super.onCreateContextMenu(menu, v, menuInfo); menu.add(0, DELETE_ID, 0, R.string.menu_delete); }</pre> diff --git a/docs/html/images/activity_fragment_lifecycle.png b/docs/html/images/activity_fragment_lifecycle.png Binary files differnew file mode 100644 index 0000000..156aa40 --- /dev/null +++ b/docs/html/images/activity_fragment_lifecycle.png diff --git a/docs/html/images/fragment_lifecycle.png b/docs/html/images/fragment_lifecycle.png Binary files differnew file mode 100644 index 0000000..ce9d395 --- /dev/null +++ b/docs/html/images/fragment_lifecycle.png diff --git a/docs/html/images/fundamentals/diagram_backstack.png b/docs/html/images/fundamentals/diagram_backstack.png Binary files differnew file mode 100644 index 0000000..2c6e33f --- /dev/null +++ b/docs/html/images/fundamentals/diagram_backstack.png diff --git a/docs/html/images/fundamentals/diagram_backstack_singletask_multiactivity.png b/docs/html/images/fundamentals/diagram_backstack_singletask_multiactivity.png Binary files differnew file mode 100644 index 0000000..d6a21d7 --- /dev/null +++ b/docs/html/images/fundamentals/diagram_backstack_singletask_multiactivity.png diff --git a/docs/html/images/fundamentals/diagram_multiple_instances.png b/docs/html/images/fundamentals/diagram_multiple_instances.png Binary files differnew file mode 100644 index 0000000..380e7788 --- /dev/null +++ b/docs/html/images/fundamentals/diagram_multiple_instances.png diff --git a/docs/html/images/fundamentals/diagram_multitasking.png b/docs/html/images/fundamentals/diagram_multitasking.png Binary files differnew file mode 100644 index 0000000..b8c7b45 --- /dev/null +++ b/docs/html/images/fundamentals/diagram_multitasking.png diff --git a/docs/html/images/fundamentals/restore_instance.png b/docs/html/images/fundamentals/restore_instance.png Binary files differnew file mode 100644 index 0000000..fa428a7 --- /dev/null +++ b/docs/html/images/fundamentals/restore_instance.png diff --git a/docs/html/images/ui/actionbar-item-withtext.png b/docs/html/images/ui/actionbar-item-withtext.png Binary files differnew file mode 100644 index 0000000..98b5f84 --- /dev/null +++ b/docs/html/images/ui/actionbar-item-withtext.png diff --git a/docs/html/images/ui/actionbar-logo.png b/docs/html/images/ui/actionbar-logo.png Binary files differnew file mode 100644 index 0000000..481ed2c --- /dev/null +++ b/docs/html/images/ui/actionbar-logo.png diff --git a/docs/html/images/ui/actionbar.png b/docs/html/images/ui/actionbar.png Binary files differnew file mode 100644 index 0000000..4fc871c --- /dev/null +++ b/docs/html/images/ui/actionbar.png diff --git a/docs/html/resources/browser.jd b/docs/html/resources/browser.jd new file mode 100644 index 0000000..8a08769 --- /dev/null +++ b/docs/html/resources/browser.jd @@ -0,0 +1,49 @@ +page.title=Technical Resources +@jd:body + +<style type="text/css"> + {@literal @import} "{@docRoot}assets/android-developer-resource-browser.css"; +</style> + +<script type="text/javascript" src="{@docRoot}assets/android-developer-resource-browser.js"></script> +<script type="text/javascript" src="{@docRoot}assets/microtemplate.js"></script> + +<div> + <p style="display: none; float: right">Filter: <input id="resource-browser-keyword-filter"/></p> + <p id="resource-browser-search-params">Showing all technical resources:</p> +</div> + +<noscript> + <p class="note"><strong>Error:</strong> + You must have JavaScript enabled to view this page. Resources are also + available offline in the SDK. + </p> +</noscript> + +<div id="resource-browser-results"> + <div class="no-results">No results.</div> +</div> + +<script type="text/html" id="tmpl_resource_browser_result"> +<div class="result"> + <h3> + <% if ('external' in tagsHash) { %><strong>External: </strong> <% } %> + <a href="<%= path %>"><%= title.en %></a> + <% if ('new' in tagsHash) { %><span class="new">new!</span> <% } %> + </h3> + <p class="resource-meta"><% + var __g = ['', '']; + if ('article' in tagsHash) { + __g = ['Article', 'about']; + } else if ('tutorial' in tagsHash) { + __g = ['Tutorial', 'on']; + } else if ('sample' in tagsHash) { + __g = ['Sample', 'for']; + } else if ('video' in tagsHash) { + __g = ['Video', 'about']; + } + %> + <%= __g[0] %><% if (topicsHtml) { %> <%= __g[1] %><% } %> <%= topicsHtml %></p> + <p><%= description.en %></p> +</div> +</script> diff --git a/docs/html/resources/index.jd b/docs/html/resources/index.jd index 1668721..9055868 100644 --- a/docs/html/resources/index.jd +++ b/docs/html/resources/index.jd @@ -1,38 +1,90 @@ page.title=Developer Resources @jd:body +<style type="text/css"> + #resource-list-table td { + border: 0; + padding: 0 24px; + width: 33%; + max-width: 250px; + border-right: 1px solid #ddd; + } + + #resource-list-table td.last { + border-right: 0; + padding-right: 0; + } +</style> + <p> -This section provides technical articles, tutorials, sample code, and other +This section provides articles, tutorials, sample code, and other information to help you quickly implement the features you want in your -application. +application. To return to this page later, just click the "Resources" +tab while any Resources page is loaded. </p> -<dl> -<dt><b>Technical Articles</b></dt> -<dd>Focused discussions about Android development subjects, including -optimizations, tips, interesting implementations, -and so on. Most of the articles provide "how-to" instructions for adding -features or functionality to your app. The articles are drawn from posts to the -Android Developers Blog. -</dd> - -<dt><b>Tutorials</b></dt> -<dd>Step-by-step instructions demonstrating how to build an Android application -that has the specific features you want. </dd> - -<dt><b>Sample Code</b></dt> -<dd>Fully-functioning sample applications that you can look at or build and run, -to learn about how Android works. Feel free to reuse any of the code or -techniques that you find in the samples!</dd> +<h2>Technical Resources</h2> + +<table id="resource-list-table"> +<tr> + <td> + <a href="{@docRoot}resources/browser.html?tag=sample"> + <img src="{@docRoot}assets/images/resource-big-sample.png"/> + </a> + <h3><a href="{@docRoot}resources/browser.html?tag=sample"> + Sample Code + </a></h3> + <p>Fully-functioning sample applications that you can build and run + to learn about how Android works. Feel free to reuse any of the code or + techniques in the samples.</p> + </td> + <td> + <a href="{@docRoot}resources/browser.html?tag=article"> + <img src="{@docRoot}assets/images/resource-big-article.png"/> + </a> + <h3><a href="{@docRoot}resources/browser.html?tag=article"> + Articles + </a></h3> + <p>Focused discussions about Android development subjects, including + optimizations, tips, interesting implementations, "how-tos", + and so on.</p> + </td> + <td> + <a href="{@docRoot}resources/browser.html?tag=tutorial"> + <img src="{@docRoot}assets/images/resource-big-tutorial.png"/> + </a> + <h3><a href="{@docRoot}resources/browser.html?tag=tutorial"> + Tutorials + </a></h3> + <p>Step-by-step instructions demonstrating how to build an Android application + that has the specific features you want.</p> + </td> + <!-- <td class="last"> + <a href="{@docRoot}resources/browser.html?tag=video"> + <img src="{@docRoot}assets/images/resource-big-video.png"/> + </a> + <h3><a href="{@docRoot}resources/browser.html?tag=video"> + Videos & Screencasts + </a></h3> + <p>Videos and presentation slides from developer events, along with + screencasts to walk you through common Android development + workflows.</p> + </td> --> +</tr> +</table> +<h2>Other Resources</h2> + +<dl> <dt><b>Community</b></dt> <dd>Links to the Android discussion groups and information about other ways to collaborate with other developers. </dd> +<dt><b>Device Dashboard</b></dt> +<dd>Device distribution data, grouped by various dimensions such as screen size +and Android platform version. </dd> + <dt><b>More</b></dt> <dd>Quick development tips, troubleshooting information, and frequently asked questions (FAQs). </dd> </dl> - -<p>To return to this page later, just click the "Resources" tab while any -Resources page is loaded. </p>
\ No newline at end of file diff --git a/docs/html/resources/resources-data.js b/docs/html/resources/resources-data.js new file mode 100644 index 0000000..221406c --- /dev/null +++ b/docs/html/resources/resources-data.js @@ -0,0 +1,632 @@ +var ANDROID_TAGS = { + type: { + 'article': 'Article', + 'tutorial': 'Tutorial', + 'sample': 'Sample', + 'video': 'Video', + 'library': 'Code Library' + }, + topic: { + 'accessibility': 'Accessibility', + 'accountsync': 'Accounts & Sync', + 'bestpractice': 'Best Practices', + 'communication': 'Communication', + 'compatibility': 'Compatibility', + 'data': 'Data Access', + 'drawing': 'Canvas Drawing', + 'gamedev': 'Game Development', + 'gl': 'OpenGL ES', + 'input': 'Input Methods', + 'intent': 'Intents', + 'layout': 'Layouts/Views', + 'media': 'Multimedia', + 'newfeature': 'New Features', + 'performance': 'Performance', + 'search': 'Search', + 'testing': 'Testing', + 'ui': 'User Interface', + 'web': 'Web Content' + }, + misc: { + 'external': 'External', + 'new': 'New' + } +}; + +var ANDROID_RESOURCES = [ + +////////////////////////// +/// TECHNICAL ARTICLES /// +////////////////////////// + + { + tags: ['article', 'performance', 'bestpractice'], + path: 'articles/avoiding-memory-leaks.html', + title: { + en: 'Avoiding Memory Leaks' + }, + description: { + en: 'Mobile devices often have limited memory, and memory leaks can cause your application to waste this valuable resource without your knowledge. This article provides tips to help you avoid common causes of memory leaks on the Android platform.' + } + }, + { + tags: ['article', 'compatibility'], + path: 'articles/backward-compatibility.html', + title: { + en: 'Backward Compatibility' + }, + description: { + en: 'The Android platform strives to ensure backwards compatibility. However, sometimes you want to use new features which aren\'t supported on older platforms. This article discusses strategies for selectively using these features based on availability, allowing you to keep your applications portable across a wide range of devices.' + } + }, + { + tags: ['article', 'intent'], + path: 'articles/can-i-use-this-intent.html', + title: { + en: 'Can I Use this Intent?' + }, + description: { + en: 'Android offers a very powerful and yet easy-to-use message type called an intent. You can use intents to turn applications into high-level libraries and make code modular and reusable. While it is nice to be able to make use of a loosely coupled API, there is no guarantee that the intent you send will be received by another application. This article describes a technique you can use to find out whether the system contains any application capable of responding to the intent you want to use.' + } + }, + { + tags: ['article', 'input'], + path: 'articles/creating-input-method.html', + title: { + en: 'Creating an Input Method' + }, + description: { + en: 'Input Method Editors (IMEs) provide the mechanism for entering text into text fields and other Views. Android devices come bundled with at least one IME, but users can install additional IMEs. This article covers the basics of developing an IME for the Android platform.' + } + }, + { + tags: ['article', 'drawing', 'ui'], + path: 'articles/drawable-mutations.html', + title: { + en: 'Drawable Mutations' + }, + description: { + en: 'Drawables are pluggable drawing containers that allow applications to display graphics. This article explains some common pitfalls when trying to modify the properties of multiple Drawables.' + } + }, + { + tags: ['article', 'bestpractice', 'ui'], + path: 'articles/faster-screen-orientation-change.html', + title: { + en: 'Faster Screen Orientation Change' + }, + description: { + en: 'When an Android device changes its orientation, the default behavior is to automatically restart the current activity with a new configuration. However, this can become a bottleneck in applications that access a large amount of external data. This article discusses how to gracefully handle this situation without resorting to manually processing configuration changes.' + } + }, + { + tags: ['article', 'compatibility'], + path: 'articles/future-proofing.html', + title: { + en: 'Future-Proofing Your Apps' + }, + description: { + en: 'A collection of common sense advice to help you ensure that your applications don\'t break when new versions of the Android platform are released.' + } + }, + { + tags: ['article', 'input'], + path: 'articles/gestures.html', + title: { + en: 'Gestures' + }, + description: { + en: 'Touch screens allow users to perform gestures, such as tapping, dragging, flinging, or sliding, to perform various actions. The gestures API enables your application to recognize even complicated gestures with ease. This article explains how to integrate this API into an application.' + } + }, + { + tags: ['article', 'gamedev', 'gl'], + path: 'articles/glsurfaceview.html', + title: { + en: 'Introducing GLSurfaceView' + }, + description: { + en: 'This article provides an overview of GLSurfaceView, a class that makes it easy to implement 2D or 3D OpenGL rendering inside of an Android application.' + } + }, + { + tags: ['article', 'ui', 'layout'], + path: 'articles/layout-tricks-reuse.html', + title: { + en: 'Layout Tricks: Creating Reusable UI Components' + }, + description: { + en: 'Learn how to combine multiple standard UI widgets into a single high-level component, which can be reused throughout your application.' + } + }, + { + tags: ['article', 'layout', 'ui', 'performance', 'bestpractice'], + path: 'articles/layout-tricks-efficiency.html', + title: { + en: 'Layout Tricks: Creating Efficient Layouts' + }, + description: { + en: 'Learn how to optimize application layouts as this article walks you through converting a LinearLayout into a RelativeLayout, and analyzes the resulting implications on performance.' + } + }, + { + tags: ['article', 'layout', 'ui', 'performance', 'bestpractice'], + path: 'articles/layout-tricks-stubs.html', + title: { + en: 'Layout Tricks: Using ViewStubs' + }, + description: { + en: 'Learn about using ViewStubs inside an application\'s layout in order to inflate rarely used UI elements, without the performance implications which would otherwise be caused by using the <code><include></code> tag.' + } + }, + { + tags: ['article', 'layout', 'ui', 'performance', 'bestpractice'], + path: 'articles/layout-tricks-merge.html', + title: { + en: 'Layout Tricks: Merging Layouts' + }, + description: { + en: 'Learn how to use the <code><merge></code> tag in your XML layouts in order to avoid unnecessary levels of hierarchy within an application\'s view tree.' + } + }, + { + tags: ['article', 'ui', 'performance'], + path: 'articles/listview-backgrounds.html', + title: { + en: 'ListView Backgrounds: An Optimization' + }, + description: { + en: 'ListViews are very popular widgets within the Android framework. This article describes some of the optimizations used by the ListView widget, and how to avoid some common issues that this causes when trying to use a custom background.' + } + }, + { + tags: ['article', 'ui', 'newfeature'], + path: 'articles/live-folders.html', + title: { + en: 'Live Folders' + }, + description: { + en: 'Live Folders allow users to display any source of data on their home screen without launching an application. This article discusses how to export an application\'s data in a format suitable for display inside of a live folder.' + } + }, + { + tags: ['article', 'ui', 'newfeature'], + path: 'articles/live-wallpapers.html', + title: { + en: 'Live Wallpapers' + }, + description: { + en: 'Live wallpapers are richer, animated, interactive backgrounds that users can display in their home screens. Learn how to create a live wallpaper and bundle it in an application that users can install on their devices.' + } + }, + { + tags: ['article', 'input'], + path: 'articles/on-screen-inputs.html', + title: { + en: 'Onscreen Input Methods' + }, + description: { + en: 'The Input Method Framework (IMF) allows users to take advantage of on-screen input methods, such as software keyboards. This article provides an overview of Input Method Editors (IMEs) and how applications interact with them.' + } + }, + { + tags: ['article', 'performance', 'bestpractice'], + path: 'articles/painless-threading.html', + title: { + en: 'Painless Threading' + }, + description: { + en: 'This article discusses the threading model used by Android applications and how applications can ensure best UI performance by spawning worker threads to handle long-running operations, rather than handling them in the main thread. The article also explains the API that your application can use to interact with Android UI toolkit components running on the main thread and spawn managed worker threads.' + } + }, + { + tags: ['article', 'ui', 'search'], + path: 'articles/qsb.html', + title: { + en: 'Quick Search Box' + }, + description: { + en: 'Quick Search Box (QSB) is a powerful, system-wide search framework. QSB makes it possible for users to quickly and easily find what they\'re looking for, both on their devices and on the web. This article discusses how to work with the QSB framework to add new search results for an installed application.' + } + }, + { + tags: ['article', 'ui'], + path: 'articles/touch-mode.html', + title: { + en: 'Touch Mode' + }, + description: { + en: 'This article explains the touch mode, one of the most important principles of Android\'s UI toolkit. Whenever a user interacts with a device\'s touch screen, the system enters touch mode. While simple in concept, there are important implications touch mode that are often overlooked.' + } + }, + { + tags: ['article', 'performance', 'bestpractice'], + path: 'articles/track-mem.html', + title: { + en: 'Tracking Memory Allocations' + }, + description: { + en: 'This article discusses how to use the Allocation Tracker tool to observe memory allocations and avoid performance problems that would otherwise be caused by ignoring the effect of Dalvik\'s garbage collector.' + } + }, + { + tags: ['article', 'newfeature'], + path: 'articles/ui-1.5.html', + title: { + en: 'UI Framework Changes in Android 1.5' + }, + description: { + en: 'Explore the UI changes that were introduced in Android 1.5, compared with the UI provided in Android 1.0 and 1.1.' + } + }, + { + tags: ['article', 'newfeature'], + path: 'articles/ui-1.6.html', + title: { + en: 'UI Framework Changes in Android 1.6' + }, + description: { + en: 'Explore the UI changes that were introduced in Android 1.6, compared with the UI provided in Android 1.5. In particular, this article discusses changes to RelativeLayouts and click listeners.' + } + }, + { + tags: ['article', 'ui', 'bestpractice'], + path: 'articles/timed-ui-updates.html', + title: { + en: 'Updating the UI from a Timer' + }, + description: { + en: 'Learn about how to use Handlers as a more efficient replacement for java.util.Timer on the Android platform.' + } + }, + { + tags: ['article', 'ui', 'accessibility'], + path: 'articles/tts.html', + title: { + en: 'Using Text-to-Speech' + }, + description: { + en: 'The text-to-speech API lets your application "speak" to users, in any of several languages. This article provides an overview of the TTS API and how you use to add speech capabilities to your application.' + } + }, + { + tags: ['article', 'ui', 'web'], + path: 'articles/using-webviews.html', + title: { + en: 'Using WebViews' + }, + description: { + en: 'WebViews allow an application to dynamically display HTML and execute JavaScript, without relinquishing control to a separate browser application. This article introduces the WebView classes and provides a sample application that demonstrates its use.' + } + }, + { + tags: ['article', 'ui'], + path: 'articles/wikinotes-linkify.html', + title: { + en: 'WikiNotes: Linkify your Text!' + }, + description: { + en: 'This article introduces WikiNotes for Android, part of the Apps for Android project. It covers the use of Linkify to turn ordinary text views into richer, link-oriented content that causes Android intents to fire when a link is selected.' + } + }, + { + tags: ['article', 'intent'], + path: 'articles/wikinotes-intents.html', + title: { + en: 'WikiNotes: Routing Intents' + }, + description: { + en: 'This article illustrates how an application, in this case the WikiNotes sample app, can use intents to route various types of linked text to the application that handles that type of data. For example, an app can use intents to route a linked telephone number to a dialer app and a web URL to a browser.' + } + }, + { + tags: ['article', 'ui', 'performance'], + path: 'articles/window-bg-speed.html', + title: { + en: 'Window Backgrounds & UI Speed' + }, + description: { + en: 'Some Android applications need to squeeze every bit of performance out of the UI toolkit and there are many ways to do so. In this article, you will discover how to speed up the drawing and the perceived startup time of your activities. Both of these techniques rely on a single feature, the window\'s background drawable.' + } + }, + { + tags: ['article', 'performance', 'bestpractice'], + path: 'articles/zipalign.html', + title: { + en: 'Zipalign: an Easy Optimization' + }, + description: { + en: 'The Android SDK includes a tool called zipalign that optimizes the way an application is packaged. Running zipalign against your application enables Android to interact with it more efficiently at run time and thus has the potential to make it and the overall system run faster. This article provides a high-level overview of the zipalign tool and its use.' + } + }, + +/////////////////// +/// SAMPLE CODE /// +/////////////////// + + { + tags: ['sample', 'layout', 'ui'], + path: 'samples/ApiDemos/index.html', + title: { + en: 'API Demos' + }, + description: { + en: 'A variety of small applications that demonstrate an extensive collection of framework topics.' + } + }, + { + tags: ['sample', 'data', 'newfeature', 'accountsync', 'new'], + path: 'samples/BackupRestore/index.html', + title: { + en: 'Backup and Restore' + }, + description: { + en: 'Illustrates a few different approaches that an application developer can take when integrating with the Android Backup Manager using the BackupAgent API introduced in Android 2.2.' + } + }, + { + tags: ['sample', 'communication'], + path: 'samples/BluetoothChat/index.html', + title: { + en: 'Bluetooth Chat' + }, + description: { + en: 'An application for two-way text messaging over Bluetooth.' + } + }, + { + tags: ['sample', 'accountsync'], + path: 'samples/BusinessCard/index.html', + title: { + en: 'BusinessCard' + }, + description: { + en: 'An application that demonstrates how to launch the built-in contact picker from within an activity. This sample also uses reflection to ensure that the correct version of the contacts API is used, depending on which API level the application is running under.' + } + }, + { + tags: ['sample', 'accountsync'], + path: 'samples/ContactManager/index.html', + title: { + en: 'Contact Manager' + }, + description: { + en: 'An application that demonstrates how to query the system contacts provider using the <code>ContactsContract</code> API, as well as insert contacts into a specific account.' + } + }, + { + tags: ['sample'], + path: 'samples/Home/index.html', + title: { + en: 'Home' + }, + description: { + en: 'A home screen replacement application.' + } + }, + { + tags: ['sample', 'gamedev', 'media'], + path: 'samples/JetBoy/index.html', + title: { + en: 'JetBoy' + }, + description: { + en: 'A game that demonstrates the SONiVOX JET interactive music technology, with <code><a href="/reference/android/media/JetPlayer.html">JetPlayer</a></code>.' + } + }, + { + tags: ['sample', 'ui', 'newfeature'], + path: 'samples/CubeLiveWallpaper/index.html', + title: { + en: 'Live Wallpaper' + }, + description: { + en: 'An application that demonstrates how to create a live wallpaper and bundle it in an application that users can install on their devices.' + } + }, + { + tags: ['sample', 'gamedev', 'media'], + path: 'samples/LunarLander/index.html', + title: { + en: 'Lunar Lander' + }, + description: { + en: 'A classic Lunar Lander game.' + } + }, + { + tags: ['sample', 'ui', 'bestpractice', 'layout'], + path: 'samples/MultiResolution/index.html', + title: { + en: 'Multiple Resolutions' + }, + description: { + en: 'A sample application that shows how to use resource directory qualifiers to provide different resources for different screen configurations.' + } + }, + { + tags: ['sample', 'data'], + path: 'samples/NotePad/index.html', + title: { + en: 'Note Pad' + }, + description: { + en: 'An application for saving notes. Similar (but not identical) to the <a href="/resources/tutorials/notepad/index.html">Notepad tutorial</a>.' + } + }, + { + tags: ['sample', 'accountsync'], + path: 'samples/SampleSyncAdapter/index.html', + title: { + en: 'SampleSyncAdapter' + }, + description: { + en: 'Demonstrates how an application can communicate with a cloud-based service and synchronize its data with data stored locally in a content provider. The sample uses two related parts of the Android framework — the account manager and the synchronization manager (through a sync adapter).' + } + }, + { + tags: ['sample', 'ui', 'search'], + path: 'samples/SearchableDictionary/index.html', + title: { + en: 'Searchable Dictionary v2' + }, + description: { + en: 'A sample application that demonstrates Android\'s search framework, including how to provide search suggestions for Quick Search Box.' + } + }, + { + tags: ['sample', 'layout', 'ui'], + path: 'samples/Snake/index.html', + title: { + en: 'Snake' + }, + description: { + en: 'An implementation of the classic game "Snake."' + } + }, + { + tags: ['sample', 'testing'], + path: 'samples/Spinner/index.html', + title: { + en: 'Spinner' + }, + description: { + en: 'A simple application that serves as an application under test for the SpinnerTest example.' + } + }, + { + tags: ['sample', 'testing'], + path: 'samples/SpinnerTest/index.html', + title: { + en: 'SpinnerTest' + }, + description: { + en: 'The test application for the Activity Testing tutorial. It tests the Spinner example application.' + } + }, + { + tags: ['sample', 'newfeature'], + path: 'samples/TicTacToeLib/index.html', + title: { + en: 'TicTacToeLib' + }, + description: { + en: 'An example of an Android library project, a type of project that lets you store and manage shared code and resources in one place, then make them available to your other Android applications.' + } + }, + { + tags: ['sample', 'newfeature',], + path: 'samples/TicTacToeMain/index.html', + title: { + en: 'TicTacToeMain' + }, + description: { + en: 'Demonstrates how an application can make use of shared code and resources stored in an Android library project.' + } + }, + { + tags: ['sample', 'input'], + path: 'samples/SoftKeyboard/index.html', + title: { + en: 'Soft Keyboard' + }, + description: { + en: 'An example of writing an input method for a software keyboard.' + } + }, + { + tags: ['sample', 'ui'], + path: 'samples/Wiktionary/index.html', + title: { + en: 'Wiktionary' + }, + description: { + en: 'An example of creating interactive widgets for display on the Android home screen.' + } + }, + { + tags: ['sample', 'ui'], + path: 'samples/WiktionarySimple/index.html', + title: { + en: 'Wiktionary (Simplified)' + }, + description: { + en: 'A simple Android home screen widgets example.' + } + }, + { + tags: ['sample', 'layout', 'new'], + path: 'samples/XmlAdapters/index.html', + title: { + en: 'XML Adapters' + }, + description: { + en: 'Binding data to views using XML Adapters examples.' + } + }, + +///////////////// +/// TUTORIALS /// +///////////////// + + { + tags: ['tutorial'], + path: 'tutorials/hello-world.html', + title: { + en: 'Hello World' + }, + description: { + en: 'Beginning basic application development with the Android SDK.' + } + }, + { + tags: ['tutorial', 'ui', 'layout'], + path: 'tutorials/views/index.html', + title: { + en: 'Hello Views' + }, + description: { + en: 'A walk-through of the various types of layouts and views available in the Android SDK.' + } + }, + { + tags: ['tutorial', 'ui', 'bestpractice'], + path: 'tutorials/localization/index.html', + title: { + en: 'Hello Localization' + }, + description: { + en: 'The basics of localizing your applications for multiple languages and locales.' + } + }, + { + tags: ['tutorial', 'data'], + path: 'tutorials/notepad/index.html', + title: { + en: 'Notepad Tutorial' + }, + description: { + en: 'A multi-part tutorial discussing intermediate-level concepts such as data access.' + } + }, + { + tags: ['tutorial', 'testing'], + path: 'tutorials/testing/helloandroid_test.html', + title: { + en: 'Hello Testing' + }, + description: { + en: 'A basic introduction to the Android testing framework.' + } + }, + { + tags: ['tutorial', 'testing'], + path: 'tutorials/testing/activity_test.html', + title: { + en: 'Activity Testing' + }, + description: { + en: 'A more advanced demonstration of the Android testing framework and tools.' + } + } +]; diff --git a/docs/html/resources/resources_toc.cs b/docs/html/resources/resources_toc.cs index ed23c7c..1c1ece9 100644 --- a/docs/html/resources/resources_toc.cs +++ b/docs/html/resources/resources_toc.cs @@ -1,5 +1,56 @@ <ul> <li> + <h2><span class="en">Technical Resources</span> + </h2> + <ul> + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>resources/browser.html?tag=sample"> + <span class="en">Sample Code</span> + <span class="de" style="display:none">Beispielcode</span> + <span class="es" style="display:none">Código de ejemplo</span> + <span class="fr" style="display:none">Exemple de code</span> + <span class="it" style="display:none">Codice di esempio</span> + <span class="ja" style="display:none">サンプル コード</span> + <span class="zh-CN" style="display:none"></span> + <span class="zh-TW" style="display:none"></span> + </a></div> + <ul id="devdoc-nav-sample-list"> + <li><a href="<?cs var:toroot ?>resources/samples/get.html"> + <span class="en">Getting the Samples</span> + </a></li> + </ul> + </li> + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>resources/browser.html?tag=article"> + <span class="en">Articles</span> + </a></div> + <ul id="devdoc-nav-article-list"> + </ul> + </li> + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>resources/browser.html?tag=tutorial"> + <span class="en">Tutorials</span> + <span class="de" style="display:none">Lernprogramme</span> + <span class="es" style="display:none">Tutoriales</span> + <span class="fr" style="display:none">Didacticiels</span> + <span class="it" style="display:none">Esercitazioni</span> + <span class="ja" style="display:none">チュートリアル</span> + <span class="zh-CN" style="display:none"></span> + <span class="zh-TW" style="display:none"></span> + </a></div> + <ul id="devdoc-nav-tutorial-list"> + </ul> + </li> + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>resources/topics.html"> + <span class="en">Topics</span> + </a></div> + <ul id="devdoc-nav-topic-list"> + </ul> + </li> + </ul> + </li> + <li> <h2><span class="en">Community</span> <span style="display:none" class="de"></span> <span style="display:none" class="es">Comunidad</span> @@ -36,245 +87,7 @@ ?> <li> - <h2><span class="en">Technical Articles</span> - </h2> - <ul> - <li class="toggle-list"> - <div><a href="<?cs var:toroot ?>resources/articles/index.html"> - <span class="en">List of Articles</span> - </a></div> - <ul> - <li><a href="<?cs var:toroot ?>resources/articles/avoiding-memory-leaks.html"> - <span class="en">Avoiding Memory Leaks</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/backward-compatibility.html"> - <span class="en">Backward Compatibility</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/can-i-use-this-intent.html"> - <span class="en">Can I Use this Intent?</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/creating-input-method.html"> - <span class="en">Creating an Input Method</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/drawable-mutations.html"> - <span class="en">Drawable Mutations</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/faster-screen-orientation-change.html"> - <span class="en">Faster Screen Orientation Change</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/future-proofing.html"> - <span class="en">Future-Proofing Your Apps</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/gestures.html"> - <span class="en">Gestures</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/glsurfaceview.html"> - <span class="en">Introducing GLSurfaceView</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/layout-tricks-reuse.html"> - <span class="en">Layout Tricks: Reusing </span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/layout-tricks-efficiency.html"> - <span class="en">Layout Tricks: Efficiency</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/layout-tricks-stubs.html"> - <span class="en">Layout Tricks: ViewStubs </span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/layout-tricks-merge.html"> - <span class="en">Layout Tricks: Merging </span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/listview-backgrounds.html"> - <span class="en">ListView Backgrounds</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/live-folders.html"> - <span class="en">Live Folders</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/live-wallpapers.html"> - <span class="en">Live Wallpapers</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/on-screen-inputs.html"> - <span class="en">Onscreen Input Methods</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/painless-threading.html"> - <span class="en">Painless Threading</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/qsb.html"> - <span class="en">Quick Search Box</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/speech-input.html"> - <span class="en">Speech Input</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/touch-mode.html"> - <span class="en">Touch Mode</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/track-mem.html"> - <span class="en">Tracking Memory Allocations</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/ui-1.5.html"> - <span class="en">UI Framework Changes in Android 1.5</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/ui-1.6.html"> - <span class="en">UI Framework Changes in Android 1.6</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/timed-ui-updates.html"> - <span class="en">Updating the UI from a Timer</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/tts.html"> - <span class="en">Using Text-to-Speech</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/contacts.html"> - <span class="en">Using the Contacts API</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/using-webviews.html"> - <span class="en">Using WebViews</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/wikinotes-linkify.html"> - <span class="en">WikiNotes: Linkify your Text!</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/wikinotes-intents.html"> - <span class="en">WikiNotes: Routing Intents</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/window-bg-speed.html"> - <span class="en">Window Backgrounds & UI Speed</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/articles/zipalign.html"> - <span class="en">Zipalign: An Easy Optimization</span> - </a></li> - </ul> - </li> - </ul> - </li> - - <li> - <h2><span class="en">Tutorials</span> - <span class="de" style="display:none">Lernprogramme</span> - <span class="es" style="display:none">Tutoriales</span> - <span class="fr" style="display:none">Didacticiels</span> - <span class="it" style="display:none">Esercitazioni</span> - <span class="ja" style="display:none">チュートリアル</span> - <span class="zh-CN" style="display:none"></span> - <span class="zh-TW" style="display:none"></span> - </h2> - <ul> - <li><a href="<?cs var:toroot ?>resources/tutorials/hello-world.html"> - <span class="en">Hello World</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/tutorials/views/index.html"> - <span class="en">Hello Views</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/tutorials/localization/index.html"> - <span class="en">Hello Localization</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/tutorials/testing/helloandroid_test.html"> - <span class="en">Hello Testing</span></a> - </li> - <li><a href="<?cs var:toroot ?>resources/tutorials/notepad/index.html"> - <span class="en">Notepad Tutorial</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/tutorials/testing/activity_test.html"> - <span class="en">Activity Testing</span></a> - </li> - </ul> - </li> - - - <li> - <h2><span class="en">Sample Code</span> - <span class="de" style="display:none">Beispielcode</span> - <span class="es" style="display:none">Código de ejemplo</span> - <span class="fr" style="display:none">Exemple de code</span> - <span class="it" style="display:none">Codice di esempio</span> - <span class="ja" style="display:none">サンプル コード</span> - <span class="zh-CN" style="display:none"></span> - <span class="zh-TW" style="display:none"></span> - </h2> - <ul> - <li><a href="<?cs var:toroot ?>resources/samples/get.html"> - <span class="en">Getting the Samples</span> - </a></li> - <li class="toggle-list"> - <div><a href="<?cs var:toroot ?>resources/samples/index.html"> - <span class="en">List of Samples</span> - </a></div> - <ul> - <li><a href="<?cs var:toroot ?>resources/samples/ApiDemos/index.html"> - <span class="en">API Demos</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/BackupRestore/index.html"> - <span class="en">Backup and Restore</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/BluetoothChat/index.html"> - <span class="en">Bluetooth Chat</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/BusinessCard/index.html"> - <span class="en">Business Card</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/ContactManager/index.html"> - <span class="en">Contact Manager</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/Home/index.html"> - <span class="en">Home</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/JetBoy/index.html"> - <span class="en">JetBoy</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/CubeLiveWallpaper/index.html"> - <span class="en">Live Wallpaper</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/LunarLander/index.html"> - <span class="en">Lunar Lander</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/MultiResolution/index.html"> - <span class="en">Multiple Resolutions</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/NFCDemo/index.html"> - <span class="en">NFCDemo</span> - </a> <span class="new">new!</span></li> - <li><a href="<?cs var:toroot ?>resources/samples/NotePad/index.html"> - <span class="en">Note Pad</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/SampleSyncAdapter/index.html"> - <span class="en">Sample Sync Adapter</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/SearchableDictionary/index.html"> - <span class="en">Searchable Dictionary v2</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/SipDemo/index.html"> - <span class="en">SIP Demo</span> - </a> <span class="new">new!</span></li> - <li><a href="<?cs var:toroot ?>resources/samples/Snake/index.html"> - <span class="en">Snake</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/SoftKeyboard/index.html"> - <span class="en">Soft Keyboard</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/Spinner/index.html"> - <span class="en">Spinner</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/SpinnerTest/index.html"> - <span class="en">SpinnerTest</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/TicTacToeLib/index.html"> - <span class="en">TicTacToeLib</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/TicTacToeMain/index.html"> - <span class="en">TicTacToeMain</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/Wiktionary/index.html"> - <span class="en">Wiktionary</span> - </a></li> - <li><a href="<?cs var:toroot ?>resources/samples/WiktionarySimple/index.html"> - <span class="en">Wiktionary (Simplified)</span> - </a></li> - </ul> - </li> - </ul> - </li> - - - - <li> - <h2><span class="en">More</span> + <h2><span class="en">More</span> </h2> <ul> <li><a href="<?cs var:toroot ?>resources/faq/commontasks.html"> @@ -301,8 +114,6 @@ </li> </ul> </li> - - </ul> <script type="text/javascript"> diff --git a/docs/html/resources/samples/images/NfcDemo.png b/docs/html/resources/samples/images/NfcDemo.png Binary files differdeleted file mode 100644 index c175d12..0000000 --- a/docs/html/resources/samples/images/NfcDemo.png +++ /dev/null diff --git a/docs/html/resources/samples/images/XmlPhotosAdapter.png b/docs/html/resources/samples/images/XmlPhotosAdapter.png Binary files differnew file mode 100644 index 0000000..c018d54 --- /dev/null +++ b/docs/html/resources/samples/images/XmlPhotosAdapter.png diff --git a/docs/html/resources/samples/images/XmlRssReader.png b/docs/html/resources/samples/images/XmlRssReader.png Binary files differnew file mode 100644 index 0000000..00f841b --- /dev/null +++ b/docs/html/resources/samples/images/XmlRssReader.png diff --git a/docs/html/resources/samples/images/sample_notepadtest_junit.png b/docs/html/resources/samples/images/sample_notepadtest_junit.png Binary files differnew file mode 100644 index 0000000..4cda54e --- /dev/null +++ b/docs/html/resources/samples/images/sample_notepadtest_junit.png diff --git a/docs/html/resources/samples/index.jd b/docs/html/resources/samples/index.jd index 5749728..cbe6ca3 100644 --- a/docs/html/resources/samples/index.jd +++ b/docs/html/resources/samples/index.jd @@ -58,9 +58,6 @@ href="{@docRoot}resources/samples/get.html">Getting the Samples</a>.</p> <dd>A sample application that shows how to use resource directory qualifiers to provide different resources for different screen configurations.</dd> - <dt><a href="NFCDemo/index.html">NFCDemo</a></dt> - <dd>An application for reading NFC Forum Type 2 Tags using platform NFC apis.</a>.</dd> - <dt><a href="NotePad/index.html">Note Pad</a></dt> <dd>An application for saving notes. Similar (but not identical) to the <a href="{@docRoot}resources/tutorials/notepad/index.html">Notepad tutorial</a>.</dd> diff --git a/docs/html/resources/topics.jd b/docs/html/resources/topics.jd new file mode 100644 index 0000000..b5960ff --- /dev/null +++ b/docs/html/resources/topics.jd @@ -0,0 +1,72 @@ +page.title=Technical Resource Topics +@jd:body + +<style type="text/css"> + #resource-topic-table td { + border: 0; + padding: 0; + margin: 0; + padding-left: 1em; + width: 18em; + } + + #resource-topic-table ul { + padding: 0; + margin: 0; + } + + #resource-topic-table li { + list-style: none; + margin: 0; + padding: 0; + } +</style> + +<p> +You can browse the list of technical resources by topic by clicking on the +links below. Over time, as more topics are added, they will be added to the +list below. +</p> + +<noscript> + <p class="note"><strong>Error:</strong> + You must have JavaScript enabled to view this page. Resources are also + available offline in the SDK. + </p> +</noscript> + +<table id="resource-topic-table"> + <tr></tr> +</table> + +<script type="text/javascript"> +<!-- +(function() { + var topics = []; + for (var topic in ANDROID_TAGS['topic']) { + topics.push({name:topic,title:ANDROID_TAGS['topic'][topic]}); + } + topics.sort(function(x,y){ return (x.title < y.title) ? -1 : 1; }); + var topicParent = null; + for (var i = 0; i < topics.length; i++) { + if (topicParent == null || i % 10 == 0) { + // create a new column + topicParent = $('ul', $('<td><ul>').appendTo('#resource-topic-table tr')); + } + + topicParent.append( + $('<li>').append( + $('<h3>').append( + $('<a>') + .attr('href', toRoot + "resources/browser.html?tag=" + topics[i].name) + .append($('<span>') + .addClass('en') + .html(topics[i].title) + ) + ) + ) + ); + } +})(); +//--> +</script>
\ No newline at end of file diff --git a/docs/html/resources/tutorials/notepad/notepad-ex2.jd b/docs/html/resources/tutorials/notepad/notepad-ex2.jd index 289b5fe..499b796 100644 --- a/docs/html/resources/tutorials/notepad/notepad-ex2.jd +++ b/docs/html/resources/tutorials/notepad/notepad-ex2.jd @@ -87,8 +87,8 @@ Open the Notepadv2 class.</p> menu callback used for the options menu. Here, we add just one line, which will add a menu item to delete a note. Call <code>menu.add()</code> like so: <pre> -public boolean onCreateContextMenu(Menu menu, View v - ContextMenuInfo menuInfo) { +public void onCreateContextMenu(Menu menu, View v, + ContextMenu.ContextMenuInfo menuInfo) { super.onCreateContextMenu(menu, v, menuInfo); menu.add(0, DELETE_ID, 0, R.string.menu_delete); }</pre> |
