diff options
Diffstat (limited to 'docs/html/guide/topics/ui')
| -rw-r--r-- | docs/html/guide/topics/ui/actionbar.jd | 593 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/declaring-layout.jd | 10 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/dialogs.jd | 39 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/menus.jd | 96 |
4 files changed, 684 insertions, 54 deletions
diff --git a/docs/html/guide/topics/ui/actionbar.jd b/docs/html/guide/topics/ui/actionbar.jd new file mode 100644 index 0000000..376bf6a --- /dev/null +++ b/docs/html/guide/topics/ui/actionbar.jd @@ -0,0 +1,593 @@ +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 that includes the application icon and activity title</li> + <li>Provides action items from the Options Menu and modes of navigating around the +application</li> + <li>Supports custom views, including an embedded search box</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="#ActionView">Adding an Action View</a></li> + <li><a href="#Tabs">Adding Tabs</a></li> + <li><a href="#Dropdown">Adding Drop-down Navigation</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 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. (Menu items not appearing as action +items are placed in the Overflow Menu, revealed by a drop-down in the Action Bar.)</li> + <li>Provide tabs for navigating between <a +href="{@docRoot}guide/topics/fundamentals/fragments.html">fragments</a>.</li> + <li>Provide drop-down navigation items.</li> + <li>Provide interactive "action views" in place of action items.</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 activities, simply target your application for HONEYCOMB or later, +using the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code +<uses-sdk>}</a> element. That is, by setting either the {@code android:minSdkVersion} or +{@code android:targetSdkVersion} to HONEYCOMB or later, each activity in your application will +include the Action Bar when running on devices with HONEYCOMB or later. For example:</p> + +<pre> +<manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.example.helloworld" + android:versionCode="1" + android:versionName="1.0"> + <b><uses-sdk android:minSdkVersion="Froyo" /></b> + <application ... > + ... + </application> +</manifest> +</pre> + +<p>This also enables the "Holographic" theme for all your activities, which is the new default +application theme for HONEYCOMB and later.</p> + +<p class="note"><strong>Note:</strong> In order for the Holographic theme to be applied based on +the target platform version, the <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> +element must appear <em>before</em> the <a +href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> +element.</p> + +<h3>Hide the Action Bar</h3> + +<p>If you want to hide the Action Bar for a particular activity, set the activity theme to +{@code android:style/Theme.NoTitleBar}. For example:</p> + +<pre> +<activity android:theme="@android:style/Theme.NoTitleBar"> +</pre> + + +<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.</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—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 Overflow Menu (revealed by the menu 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> Menu items that appear in the Overflow Menu (not as action +items) also show an icon, so it's best if you provide an icon for every menu item.</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="ActionView">Adding an Action View</h2> + +<div class="figure" style="width:281px"> + <img src="{@docRoot}images/ui/actionbar-actionview.png" alt="" /> + <p class="img-caption"><strong>Figure 4.</strong> An action view with a search widget.</p> +</div> + +<p>An action view is a customized view you can specify for an item in your Options Menu, to +display in the Action Bar when the item is included as an action item. For example, you can +include a menu item for "Search", which appears and behaves as a normal menu item in the Overflow +Menu, but, when set as an action item, it provides an action view that is a {@link +android.widget.SearchView}, so the user can initiate a search directly from the Action Bar. +Figure 4 shows an example of this, in which a menu item for search provides an action view +using the {@link android.widget.SearchView} widget.</p> + +<p>The best way to declare an action view for an item is in your <a +href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>, using the {@code +android:actionLayout} or {@code android:actionViewClass} attribute.</p> + +<ul> + <li>The value for {@code android:actionLayout} must be a resource pointer to a layout file. +For example: +<pre> +<item android:id="@+id/menu_search" + android:title="Search" + android:icon="@drawable/ic_menu_search" + android:showAsAction="ifRoom" + <b>android:actionLayout="@layout/searchview"</b> /> +</pre></li> + <li>The value for {@code android:actionViewClass} must be a fully-qualified class name for +the {@link android.view.View} you want to use. For example: +<pre> +<item android:id="@+id/menu_search" + android:title="Search" + android:icon="@drawable/ic_menu_search" + android:showAsAction="ifRoom" + <b>android:actionViewClass="android.widget.SearchView"</b> /> +</pre></li> +</ul> + +<p>Now, when the menu item is displayed as an action item, it's action view appears instead of +the item's traditional icon and/or text. Yet, if for some reason the item does not appear in the +Action Bar, then it behaves like a normal menu item in the Overflow Menu and you must respond +accordingly when the user taps it, from the {@link android.app.Activity#onOptionsItemSelected +onOptionsItemSelected()} callback.</p> + +<p>When the activity first starts, the system populates the Action Bar and Overflow Menu by calling +{@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()}. +After you've inflated your menu in this method, you can acquire elements in an action view +(perhaps in order to attach listeners) by calling {@link android.view.Menu#findItem +findItem()} with the ID of the menu item, then {@link android.view.MenuItem#getActionView} on +the returned {@link android.view.MenuItem}. For example, the search widget from the above samples is +acquired like this:</p> + +<pre> +@Override +public boolean onCreateOptionsMenu(Menu menu) { + getMenuInflater().inflate(R.menu.options, menu); + SearchView searchView = (SearchView) menu.findItem(R.id.menu_search).getActionView(); + // Set appropriate listeners for searchView + ... + return super.onCreateOptionsMenu(menu); +} +</pre> + +<p>For more information about enabling search in the Action Bar, see the <a +href="{@docRoot}guide/topics/search/index.html">Search</a> developer guide.</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> + +<!-- +<div class="figure" style="width:300px"> + <img src="{@docRoot}images/ui/actionbar-tabs.png" alt="" /> + <p class="img-caption"><strong>Figure 5.</strong> Screenshot of tabs in the +Action Bar.</p> +</div> +--> + +<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}.<> +</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 + actionBar.addTab(actionBar.newTab().setText(R.string.tab_artists) + .setTabListener(new TabListener(artistsFragment))); + + Fragment albumsFragment = new AlbumsFragment(); + actionBar.addTab(actionBar.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#getSelectedNavigationIndex()}. 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/fundamentals/fragments.html">Fragments</a> developer guide.</p> + + + +<h2 id="Dropdown">Adding Drop-down Navigation</h2> + +<p>As another mode of navigation within your activity, you can provide a drop-down list in the +Action Bar. For example, the drop-down list can provide alternative modes for sorting the content in +the activity or switching the user's account.</p> + +<!-- +<div class="figure" style="width:135px"> + <img src="{@docRoot}images/ui/actionbar-dropdown.png" alt="" /> + <p class="img-caption"><strong>Figure 5.</strong> Screenshot of a drop-down navigation list in the +Action Bar.</p> +</div> +--> + +<p>Here's a quick list of what you must do to enable drop-down navigation:</p> + +<ol> + <li>Create a {@link android.widget.SpinnerAdapter} that provides the +list of selectable items for the list and the layout to use when drawing each item in the list.</li> + <li>Implement {@link android.app.ActionBar.OnNavigationListener} to define the behavior when the +user selects an item from the list.</li> + <li>Turn on navigation mode for the Action Bar with {@link +android.app.ActionBar#setNavigationMode setNavigationMode()}. For example: +<pre> +ActionBar actionBar = getActionBar(); +actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_LIST); +</pre> + <p>You should perform this during your activity's {@link android.app.Activity#onCreate +onCreate()} method.</p> + </li> + <li>Following that, set the callback for your drop-down list with {@link +android.app.ActionBar#setListNavigationCallbacks setListNavigationCallbacks()}. For example: +<pre> +actionBar.setListNavigationCallbacks(mSpinnerAdapter, mNavigationCallback); +</pre> +<p>This method takes your {@link android.widget.SpinnerAdapter} and {@link +android.app.ActionBar.OnNavigationListener}. More about these next.</p> +</li> +</ol> + +<p>That's the basic setup. The {@link android.widget.SpinnerAdapter} and {@link +android.app.ActionBar.OnNavigationListener} is where most of the work is done. There are many ways +you can implement these to define the functionality for your drop-down navigation. Implementing +various types of {@link android.widget.SpinnerAdapter} is beyond the scope of this +document—you should refer to the class refrence for more information about implementing it or +extending an existing implementation. However, below is a simple example for a {@link +android.widget.SpinnerAdapter} and {@link android.app.ActionBar.OnNavigationListener} to get you +started.</p> + + +<h3 id="Spinner">Example: simple SpinnerAdapter</h3> + +<p>{@link android.widget.SpinnerAdapter} is an interface that you can implement to provide +content for the list and is where your implementation for the drop-down list can be heavily +customized. Android includes some useful implementations that you can extend, such as {@link +android.widget.ArrayAdapter} and {@link +android.widget.SimpleCursorAdapter}. For example, here's an easy way to create a {@link +android.widget.SpinnerAdapter} with {@link android.widget.ArrayAdapter}, using a string array +from resources:</p> + +<pre> +SpinnerAdapter mSpinnerAdapter = ArrayAdapter.createFromResource(this, R.array.action_list, + android.R.layout.simple_spinner_dropdown_item); +</pre> + +<p>This is now ready to be given to {@link +android.app.ActionBar#setListNavigationCallbacks setListNavigationCallbacks()}, in step 4 from +above.</p> + +<p>A <a href="{@docRoot}guide/topics/resources/string-resource.html#StringArray">string array</a> +defined as a resource looks like this:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <string-array name="action_list"> + <item>Mercury</item> + <item>Venus</item> + <item>Earth</item> + </string-array> +</pre> +</pre> + + +<h3 id="OnNavigationListener">Example: simple OnNavigationListener</h3> + +<p>Your implementation of {@link android.app.ActionBar.OnNavigationListener} is where you handle +fragment changes or other modifications to your activity when the user selects an item from the +drop-down list. There's only one callback method to implement: {@link +android.app.ActionBar.OnNavigationListener#onNavigationItemSelected onNavigationItemSelected()}.</p> + +<p>The {@link +android.app.ActionBar.OnNavigationListener#onNavigationItemSelected onNavigationItemSelected()} +method receives the position of the item in the list and an item ID provided by the {@link +android.widget.SpinnerAdapter}.</p> + +<p>Here's an example that instantiates an anonymous implementation of {@link +android.app.ActionBar.OnNavigationListener}, which inserts a {@link android.app.Fragment} into the +layout container identified by {@code R.id.fragment_container}:</p> + +<pre> +mOnNavigationListener = new OnNavigationListener() { + // Get the same strings provided for the drop-down's ArrayAdapter + String[] strings = getResources().getStringArray(R.array.action_list); + + @Override + public boolean onNavigationItemSelected(int position, long itemId) { + // Create new fragment from our own Fragment class + ListContentFragment newFragment = new ListContentFragment(); + FragmentTransaction ft = openFragmentTransaction(); + // Replace whatever is in the fragment container with this fragment + // and give the fragment a tag name equal to the string at the position selected + ft.replace(R.id.fragment_container, newFragment, strings[position]); + // Apply changes + ft.commit(); + return true; + } +}; +</pre> + +<p>This instance of {@link android.app.ActionBar.OnNavigationListener} can be given to {@link +android.app.ActionBar#setListNavigationCallbacks setListNavigationCallbacks()}, in step 4 from +above.</p> + +<p>In this example, the fragment added is given a tag that can uniquely identify the fragment. +For this example, the {@code ListContentFragment} class used uses this tag as +the text for a {@link android.widget.TextView} in the fragment's layout. Here's how it's done:</p> + +<pre> +public class ListContentFragment extends Fragment { + private String mText; + + @Override + public void onAttach(Activity activity) { + // This is the first callback received; here we can set the text for + // the fragment as defined by the tag specified during the fragment transaction + super.onAttach(activity); + mText = getTag(); + } + + @Override + public View onCreateView(LayoutInflater inflater, ViewGroup container, + Bundle savedInstanceState) { + // This is called to define the layout for the fragment; + // we just create a TextView and set its text to be the fragment tag + TextView text = new TextView(getActivity()); + text.setText(mText); + return text; + } +} +</pre> + + + + diff --git a/docs/html/guide/topics/ui/declaring-layout.jd b/docs/html/guide/topics/ui/declaring-layout.jd index f95a89b..c348767 100644 --- a/docs/html/guide/topics/ui/declaring-layout.jd +++ b/docs/html/guide/topics/ui/declaring-layout.jd @@ -47,11 +47,11 @@ application can create View and ViewGroup objects (and manipulate their properti Plugin for Eclipse</a> offers a layout preview of your XML — with the XML file opened, select the <strong>Layout</strong> tab.</li> <li>You should also try the - <a href="{@docRoot}guide/developing/tools/hierarchy-viewer.html">Hierarchy Viewer</a> tool, + <a href="{@docRoot}guide/developing/debugging/debugging-ui.html#hierarchyViewer">Hierarchy Viewer</a> tool, for debugging layouts — it reveals layout property values, draws wireframes with padding/margin indicators, and full rendered views while you debug on the emulator or device.</li> - <li>The <a href="{@docRoot}guide/developing/tools/layoutopt.html">layoutopt</a> tool lets + <li>The <a href="{@docRoot}guide/developing/debugging/debugging-ui.html#layoutopt">layoutopt</a> tool lets you quickly analyze your layouts and hierarchies for inefficiencies or other problems.</li> </div> </div> @@ -119,7 +119,7 @@ for your Activity like so:</p> <pre> public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); - setContentView.(R.layout.main_layout); + setContentView(R.layout.main_layout); } </pre> @@ -190,10 +190,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 42790b6..d1c0ff8 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) |