diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/html/guide/developing/debug-tasks.jd | 36 | ||||
| -rw-r--r-- | docs/html/guide/developing/device.jd | 151 | ||||
| -rw-r--r-- | docs/html/guide/guide_toc.cs | 3 | ||||
| -rw-r--r-- | docs/html/guide/topics/resources/available-resources.jd | 188 | ||||
| -rw-r--r-- | docs/html/guide/topics/views/menus.jd | 516 |
5 files changed, 836 insertions, 58 deletions
diff --git a/docs/html/guide/developing/debug-tasks.jd b/docs/html/guide/developing/debug-tasks.jd index 10fb66f..a604df2 100644 --- a/docs/html/guide/developing/debug-tasks.jd +++ b/docs/html/guide/developing/debug-tasks.jd @@ -1,7 +1,23 @@ -page.title=Debugging +page.title=Debugging Tasks @jd:body -<p>Android has a fairly extensive set of tools to help you debug your programs: </p> +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#tools">Tools</a></li> + <li><a href="#additionaldebugging">Debug and Test Settings</a></li> + <li><a href="#toptips">Top Debugging Tips</a></li> + <li><a href="#ide-debug-port">Configuring Your IDE to Attach to the Debugging Port</a></li> + </ol> +</div> +</div> + +<p>This document offers some helpful guidance to debugging applications on Android. + + +<h2 id="tools">Tools</h2> +<p>The Android SDK includes a fairly extensive set of tools to help you debug your programs: </p> <ul> <li><a href="{@docRoot}guide/developing/tools/ddms.html"><strong>DDMS</strong></a> - A graphical program that supports port forwarding (so you can set up breakpoints in your code in your @@ -48,13 +64,12 @@ D/ActivityManager( 763): Stopping: HistoryRecord{409dbb20 com.android.home.AllAp of the doc to figure out why your application isn't appearing on the emulator, or why it's not starting. </p> -<a name="additionaldebugging" id="additionaldebugging"></a> -<h2>Debug and Test Settings on the Device</h2> +<h2 id="additionaldebugging">Debug and Test Settings</h2> -<p>Android lets you set a number of settings that will make it easier to test - and debug your applications. To get to the development settings page on the emulator, - go to <strong>Dev Tools </strong>> <strong>Development Settings</strong>. +<p>With the <strong>Dev Tools</strong> application, you can turn on a number of settings that will make it easier to test + and debug your applications. To get to the development settings page on the emulator, launch the + <strong>Dev Tools</strong> application and open <strong>Development Settings</strong>. This will open the development settings page with the following options (among others):</p> <ul> @@ -97,10 +112,7 @@ D/ActivityManager( 763): Stopping: HistoryRecord{409dbb20 com.android.home.AllAp </ul> <p>These settings will be remembered across emulator restarts. </p> -<a name="toptips" id="toptips"></a> - - -<h2>Top Debugging Tips</h2> +<h2 id="toptips">Top Debugging Tips</h2> <!-- <ul> <li><a href="#stackdump">Quick stack dump</a></li> @@ -177,7 +189,7 @@ shell on the emulator. See <a href="{@docRoot}guide/developing/tools/adb.html">U util.Log} and {@link android.os.Debug} for your convenience. </dd> </dl> -<h2 id="ide-debug-port">Configuring your IDE to attach to the debugging port</h2> +<h2 id="ide-debug-port">Configuring Your IDE to Attach to the Debugging Port</h2> <p>DDMS will assign a specific debugging port to every virtual machine that it finds on the emulator. You must either attach your IDE to that diff --git a/docs/html/guide/developing/device.jd b/docs/html/guide/developing/device.jd new file mode 100644 index 0000000..b723797 --- /dev/null +++ b/docs/html/guide/developing/device.jd @@ -0,0 +1,151 @@ +page.title=Developing on a Device +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#devices">Available Devices</a> + <ol> + <li><a href="g1">T-Mobile G1</a></li> + <li><a href="dev-phone-1">Android Dev Phone 1</a></li> + </ol> + </li> + <li><a href="#setting-up">Setting up a Device for Development</a></li> + </ol> +</div> +</div> + +<p>When building mobile applications, it's vital to test them on real +devices prior to releasing them to users. This page covers what you need to know, +including the types of devices that you can use, and how to set one up for +developing and debugging.</p> + + +<h2 id="devices">Available Devices</h2> +<p>While developers can use regular +consumer devices purchased at retail to test and use their apps, some developers +may choose not to use a retail device, preferring an unlocked or no-contract +device. Here are some options for obtaining devices capable of testing your applications.</p> + + +<h3 id="g1">T-Mobile G1</h3> + +<p>The T-Mobile G1 device makes an excellent development device. You can write +applications in the SDK and install them on the G1, then run them as users +would, using the same hardware, system, and network.</p> + +<p>For more information about obtaining a G1, visit the <a +href="http://www.t-mobileg1.com">T-Mobile G1 site</a>. </p> + + +<h3 id="dev-phone-1">Android Dev Phone 1</h3> + +<div class="sidebox"> +<p>Selected specs for Android Dev Phone 1: </p> +<ul> +<li>Touch screen</li> +<li>Trackball</li> +<li>3.2 megapixel camera with autofocus</li> +<li>Wi-Fi</li> +<li>GPS-enabled</li> +<li>Bluetooth v2.0 + <ul><li>Handsfree profile v1.5</li> + <li>Headset profile v1.0</li></ul></li> +<li>3G WCDMA (1700/2100 MHz)</li> +<li>Quad-band GSM (850/900/1800/1900 MHz)</li> +<li>QWERTY slider keyboard</li> +<li>Includes 1GB MicroSD card (can be replaced with up to 16GB card)</li> +</ul> +</div> + +<p>The Android Dev Phone 1 is a SIM-unlocked and hardware-unlocked device that +is designed for advanced developers. The device ships with a system image that +is fully compatible with Android 1.0, so you can rely on it when developing your +applications. You can use any SIM in the device and can flash custom Android +builds that will work with the unlocked bootloader. Unlike the bootloader on +retail devices, the bootloader on the Android Dev Phone 1 does not enforce +signed system images. The Android Dev Phone 1 should also appeal to developers +who live outside of T-Mobile geographies. </p> + +<p>To purchase an Android Dev Phone 1 device, you must first register as an +Android developer on the Android Market site, if you haven't done so already. +Once you've logged into your developer account on Android Market, you can +purchase the device by clicking the "Purchase" link. To accommodate demand, +there is a limit of 1 device per developer account, for now.</p> + +<p>The device currently costs $399 (USD) (including free shipping in the US), +and will be available for purchase in 18 international markets, including the +US, UK, Germany, Japan, India, Canada, France, Taiwan, Spain, Australia, +Singapore, Switzerland, Netherlands, Austria, Sweden, Finland, Poland, and +Hungary. We will continue to expand this program into new geographies over +time. Check this page for updated information.</p> + +<p>Note that Android Dev Phone 1 devices are <em>not</em> intended for +non-developer end users. Since the devices can be configured with system +software not provided by or supported by Google or any other company, end users +operate these devices at their own risk.</p> + +<p>For full device specs and more information about obtaining an Android Dev +Phone 1 device, see the <a href="http://market.android.com/publish">Android +Market</a> site.</p> + + +<h2 id="setting-up">Setting up a Device for Development</h2> + +<p>With a T-mobile G1 or Android Dev Phone 1, you can develop and debug your Android applications just as you +would on the emulator. There are just a few things to do before you can start.</p> +<ol> + <li>Declare your application as "debuggable" in your Android Manifest. + <p>In Eclipse, you can do this from the <b>Application</b> tab when viewing the Manifest + (on the right side, set <b>Debuggable</b> to <em>true</em>). Otherwise, in the <code>AndroidManifest.xml</code> + + file, add <code>android:debuggable="true"</code> to the <code><application></code> element.</p> + </li> + <li>Turn on "USB Debugging" on your device. + <p>On the device, go to the home screen, press <b>MENU</b>, select <b>Applications</b> > <b>Development</b>, + then enable <b>USB debugging</b>.</p> + + </li> + <li>Setup your system to detect your device. + <ul> + <li>If you're developing on Windows (32-bit only), you need to install the USB driver for adb: + <ol> + <li>Download the driver ZIP file + (<a href="http://dl.google.com/android/android_usb_windows.zip">android_usb_windows.zip</a>) + and unzip it.</li> + <li>Connect your Android device via USB. When the <em>Found New Hardware Wizard</em> appears, you'll be asked if you'd like Windows Update to search for software, select <em>No, not this time</em> and click <b>Next</b>.</li> + + <li>Select <em>Install from a list or specified location</em> and click <b>Next</b>.</li> + <li>Select <em>Search for the best driver in these locations</em>. Browse and select the unzipped file.</li> + <li>Click <b>Finish</b>. You're all set.</li> + + </ol> + </li> + <li>If you're developing on Mac OS X, it just works. Skip this step.</li> + <li>If you're developing on Ubuntu Linux, you need to add a rules file: + <ol> + <li>Login as root and create this file: <code>/etc/udev/rules.d/50-android.rules</code>. + <p>For Gusty/Hardy, edit the file to read: <br/> + <code>SUBSYSTEM=="usb", SYSFS{idVendor}=="0bb4", MODE="0666"</code></p> + + <p>For Dapper, edit the file to read: <br/> + <code>SUBSYSTEM=="usb_device", SYSFS{idVendor}=="0bb4", MODE="0666"</code></p> + </li> + <li>Now execute:<br/> + <code>chmod a+rx /etc/udev/rules.d/50-android.rules</code> + </li> + </ol> + + </li> + </ul> + </li> +</ol> +<p>You can verify that your device is connected by executing <code>adb devices</code> from your +SDK tools/ directory. If connected, you'll see the device name listed as a "device."</p> +<p>If using Eclipse, select run or debug as usual. You will be presented +with a <b>Device Chooser</b> dialog that lists the available emulator(s) and connected device(s). +Select the device to install and run the application there.</p> + +<p>If using the <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (adb), +you can issue commands with the <code>-d</code> flag to target your connected device.</p> diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 577641c..3e01172 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -44,7 +44,7 @@ </ul> <ul> <li class="toggle-list"> - <div><a href="<?cs var:toroot ?>guide/topics/graphics/index.html">2D and 3D Graphics</a></div> + <div><a href="<?cs var:toroot ?>guide/topics/graphics/index.html">Graphics</a></div> <ul> <li><a href="<?cs var:toroot ?>guide/topics/graphics/2d-graphics.html">2D Graphics</a></li> <li><a href="<?cs var:toroot ?>guide/topics/graphics/opengl.html">3D with OpenGL</a></li> @@ -78,6 +78,7 @@ <li><a href="<?cs var:toroot ?>guide/developing/eclipse-adt.html">In Eclipse, with ADT</a></li> <li><a href="<?cs var:toroot ?>guide/developing/other-ide.html">In Other IDEs</a></li> + <li><a href="<?cs var:toroot ?>guide/developing/device.html">On a Device</a></li> <li><a href="<?cs var:toroot ?>guide/developing/debug-tasks.html">Debugging Tasks</a></li> <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/developing/tools/index.html">Tools</a></div> diff --git a/docs/html/guide/topics/resources/available-resources.jd b/docs/html/guide/topics/resources/available-resources.jd index c59d3a8..7ba9e52 100644 --- a/docs/html/guide/topics/resources/available-resources.jd +++ b/docs/html/guide/topics/resources/available-resources.jd @@ -29,6 +29,7 @@ parent.link=index.html </ol> </li> <li><a href="#animation">Animation</a></li> + <li><a href="#menus">Menus</a></li> <li><a href="#layoutresources">Layout</a> <ol> <li><a href="#customresources">Custom Layout Resources</a> @@ -95,10 +96,10 @@ XML files such as <a href="#layoutresources">layouts</a>.</p> </p> <ul> <li> - <strong>Java</strong> <code>R.color.<em>some_name</em></code> + <strong>Java:</strong> <code>R.color.<em>some_name</em></code> </li> <li> - <strong>XML</strong> <code>@[<em>package</em>:]color/some_name</code> (where <em>some_name</em> is the <em>name</em> of a specific color) + <strong>XML:</strong> <code>@[<em>package</em>:]color/some_name</code> (where <em>some_name</em> is the <em>name</em> of a specific color) </li> </ul> <p> @@ -192,10 +193,10 @@ tags. </p> <ul> <li> - <strong>Java</strong> <code>R.string.<em>some_name</em></code> + <strong>Java:</strong> <code>R.string.<em>some_name</em></code> </li> <li> - <strong>XML</strong> <code>@[<em>package</em>:]string/some_name</code> (where <em>some_name</em> is the <em>name</em> of a specific string) + <strong>XML:</strong> <code>@[<em>package</em>:]string/some_name</code> (where <em>some_name</em> is the <em>name</em> of a specific string) </li> </ul> <p> @@ -347,10 +348,10 @@ dimension.</p> </p> <ul> <li> - <strong>Java</strong> <code>R.dimen.<em>some_name</em></code> + <strong>Java:</strong> <code>R.dimen.<em>some_name</em></code> </li> <li> - <strong>XML</strong> <code>@[<em>package</em>:]dimen/<em>some_name</em></code> (where <em>some_name</em> is the <em>name</em> of a specific <code><dimen></code> element) + <strong>XML:</strong> <code>@[<em>package</em>:]dimen/<em>some_name</em></code> (where <em>some_name</em> is the <em>name</em> of a specific <code><dimen></code> element) </li> </ul> <p> @@ -433,10 +434,10 @@ res/drawable/my_picture.png would be referenced as R.drawable.my_picture).</p> </p> <ul> <li> - <strong>Java</strong> <code>R.drawable.<em>some_file</em></code> + <strong>Java:</strong> <code>R.drawable.<em>some_file</em></code> </li> <li> - <strong>XML</strong> <code>@[<em>package</em>:]drawable/<em>some_file</em></code> + <strong>XML:</strong> <code>@[<em>package</em>:]drawable/<em>some_file</em></code> </li> </ul> @@ -462,10 +463,10 @@ version="1.0" encoding="utf-8"?></code> declaration, and a root </p> <ul> <li> - <strong>Java</strong> <code>R.drawable.<em>some_name</em></code> + <strong>Java:</strong> <code>R.drawable.<em>some_name</em></code> </li> <li> - <strong>XML</strong> <code>@[<em>package</em>:]drawable/<em>some_name</em></code> (where <em>some_name</em> is the name of a specific resource) + <strong>XML:</strong> <code>@[<em>package</em>:]drawable/<em>some_name</em></code> (where <em>some_name</em> is the name of a specific resource) </li> </ul> <p> @@ -549,10 +550,10 @@ tv.setBackground(redDrawable); </p> <ul> <li> - <strong>Java</strong> <code>R.drawable.<em>some_file</em></code> + <strong>Java:</strong> <code>R.drawable.<em>some_file</em></code> </li> <li> - <strong>XML</strong> <code>@[<em>package</em>:]drawable.<em>some_file</em></code> + <strong>XML:</strong> <code>@[<em>package</em>:]drawable.<em>some_file</em></code> </li> </ul> @@ -582,10 +583,10 @@ in <a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">2D Grap </p> <ul> <li> - <strong>Java</strong> <code>R.anim.<em>some_file</em></code> + <strong>Java:</strong> <code>R.anim.<em>some_file</em></code> </li> <li> - <strong>XML</strong> <code>@[<em>package</em>:]anim/<em>some_file</em></code> + <strong>XML:</strong> <code>@[<em>package</em>:]anim/<em>some_file</em></code> </li> </ul> <p> @@ -624,7 +625,10 @@ in <a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">2D Grap <set> </dt> <dd> - The outermost tag, which can recursively hold itself or other animations. You can include as many child elements of the same or different types as you like. Supports the following attribute: + A container that can recursively hold itself or other animations. + Represents an {@link android.view.animation.AnimationSet}. + You can include as many child elements of the same or different types as you like. + Supports the following attribute: <ul> <li> <em>shareInterpolator</em> - Whether to share the same Interpolator among all immediate child elements. @@ -635,7 +639,8 @@ in <a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">2D Grap <alpha> </dt> <dd> - A fading animation, compiled to {@link android.view.animation.AlphaAnimation}. Supports the following attributes: + A fading animation. Represents an {@link android.view.animation.AlphaAnimation}. + Supports the following attributes: <ul> <li> <em>fromAlpha</em> - 0.0 to 1.0, where 0.0 is transparent. @@ -649,7 +654,8 @@ in <a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">2D Grap <scale> </dt> <dd> - A resizing animation, compiled to {@link android.view.animation.ScaleAnimation}. You can specify what is the center point of the image (the pinned center), from which it grows outward (or inward), by specifying pivotX and pivotY. So, for example, if these were 0, 0 (top left corner), all growth would be down and to the right. <code>scale</code> supports the following attributes: + A resizing animation. Represents a {@link android.view.animation.ScaleAnimation}. + You can specify what is the center point of the image (the pinned center), from which it grows outward (or inward), by specifying pivotX and pivotY. So, for example, if these were 0, 0 (top left corner), all growth would be down and to the right. <code>scale</code> supports the following attributes: <ul> <li> <em>fromXScale</em> - Starting X size, where 1.0 is no change. @@ -675,7 +681,8 @@ in <a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">2D Grap <translate> </dt> <dd> - A motion animation that moves a visual element within its parent element. It is equivalent to {@link android.view.animation.TranslateAnimation}. + A vertical/horizontal motion animation. + Represents a {@link android.view.animation.TranslateAnimation}. Supports the following attributes in any of the following three formats: values from -100 to 100, ending with "%", indicating a percentage relative to itself; values from -100 to 100, ending in "%p", indicating a percentage relative to its parent; a float with no suffix, indicating an absolute value. <ul> <li> @@ -696,7 +703,8 @@ Supports the following attributes in any of the following three formats: values <rotate> </dt> <dd> - A rotation animation, compiled to {@link android.view.animation.RotateAnimation}. Supports the following attributes: + A rotation animation. Represents a {@link android.view.animation.RotateAnimation}. + Supports the following attributes: <ul> <li> <em>fromDegrees</em> - Starting rotation, in degrees. @@ -720,43 +728,133 @@ Supports the following attributes in any of the following three formats: values </dd> </dl> <p> - Note that alpha, scale, rotate, translate all support the following attributes from the base animation class, BaseAnimation: +In addition to the attributes defined for each element above, the elements +<code><alpha></code>, <code><scale></code>, <code><translate></code>, +<code><rotate></code>, and <code><set></code> all support the following attributes (inherited +from the {@link android.view.animation.Animation} class): </p> <dl> - <dt> - <em>duration</em> - </dt> + <dt><em>{@link android.R.attr#duration duration}</em></dt> <dd> - Duration, in milliseconds, for this effect. + Duration, in milliseconds, for this effect. </dd> - <dt> - <em>startOffset</em> - </dt> + <dt><em>{@link android.R.attr#startOffset startOffset}</em></dt> <dd> - Offset start time for this effect, in milliseconds. + Offset start time for this effect, in milliseconds. </dd> - <dt> - <em>fillBefore</em> - </dt> + <dt><em>{@link android.R.attr#fillBefore fillBefore}</em></dt> <dd> - Equivalent to {@link android.view.animation.Animation#setFillBefore animation.Animation.setFillBefore()}. + When set true, the animation transformation is applied before the animation begins. </dd> - <dt> - <em>fillAfter</em> - </dt> + <dt><em>{@link android.R.attr#fillAfter fillAfter}</em></dt> <dd> - Equivalent to {@link android.view.animation.Animation#setFillAfter animation.Animation.setFillAfter()}. + When set true, the animation transformation is applied after the animation ends. </dd> - <dt> - <em>interpolator</em> - </dt> + <dt><em>{@link android.R.attr#repeatCount repeatCount}</em></dt> + <dd> + Defines the number of times the animation should repeat. + </dd> + <dt><em>{@link android.R.attr#repeatMode repeatMode}</em></dt> + <dd> + Defines the animation behavior when it reaches the end and the repeat count is greater than 0. + Options are to either restart or reverse the animation. + </dd> + <dt><em>{@link android.R.attr#zAdjustment zAdjustment}</em></dt> + <dd> + Defines the z-axis ordering mode to use when running the animation (normal, top, or bottom). + </dd> + <dt><em>{@link android.R.attr#interpolator interpolator}</em></dt> <dd> You can optionally set an interpolator for each element to determine how quickly or slowly it performs its effect over time. For example, slow at the beginning and faster at the end for EaseInInterpolator, and the reverse for EaseOutInterpolator. A list of interpolators is given in {@link android.R.anim}. To specify these, use the syntax @android:anim/<em>interpolatorName</em>. </dd> </dl> -<p>For animation code samples, see the discussion in the -<a href="{@docRoot}guide/topics/graphics/2d-graphics.html">2D Graphics</a> topic.</p> +<p>For more discussion and animation code samples, see the discussion in the +<a href="{@docRoot}guide/topics/graphics/2d-graphics.html#tween-animation">2D Graphics</a> document.</p> + + + +<h2 id="menus">Menus</h2> +<p>Application menus (Options Menu, Context Menu, or Sub Menu) can be defined as +XML resources and inflated by your application using {@link android.view.MenuInflater}.</p> + +<p><strong>Source file format:</strong> XML file, one resource per file, one root tag, +<code><?xml></code> declaration not required.</p> +<p><strong>Resource file location:</strong> res/menu/<em>some_file</em>.xml</p> +<p><strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.view.Menu} (or subclass) resource.</p> +<p><strong>Resource reference name:</strong> </p> +<ul><li><strong>Java:</strong> <code>R.menu.<em>some_file</em></code></li></ul> + +<h3>Syntax</h3> +<p>The file must have a single root element: a <code><menu></code> element. In all, +there are three valid elements: <code><menu></code>, <code><group></code> and <code><item></code>. The +<code><item></code> and <code><group></code> elements must be the children of a <code><menu></code>, but <code><item></code> +elements can also be the children of a <code><group></code>, and another <code><menu></code> element may be the child +of an <code><item></code> (to create a Sub Menu).</p> +<pre> +<menu xmlns:android="http://schemas.android.com/apk/res/android"> + + <item android:id="@+id/<em>example_item</em> + android:title="<em>Example Item</em>" + android:icon="<em>@drawable/example_item_icon</em>" /> + + <group android:id="@+id/<em>example_group</em>"> + <item android:id="@+id/<em>example_item2</em> + android:title="<em>Example Item 2</em>" + android:icon="<em>@drawable/example_item2_icon</em>" /> + </group> + + <item android:id="@+id/<em>example_submenu</em> + android:title="<em>Example Sub Menu</em>" > + <menu> + <item android:id="@+id/<em>example_submenu_item</em> + android:title="<em>Example Sub Menu Item</em>" /> + </menu> + </item> + +</menu> +</pre> + +<h3>Elements and Attributes</h3> +<p>All attributes must be defined with the <em>android</em> namespace (e.g., <em>android:icon="@drawable/icon"</em>).</p> +<dl> + <dt><menu></dt> + <dd>The root of a menu. Contains <code><item></code> and <code><group></code> nodes. No attributes.</dd> + <dt><group></dt> + <dd>A menu group. Contains <code><item></code> elements. Valid attributes: + <ul> + <li><em>id</em> - A unique integer ID for the group.</li> + <li><em>menuCategory</em> - Value corresponding to Menu CATEGORY_* constants — defines the priority of the group. Valid values: + <em>container</em>, <em>system</em>, <em>secondary</em>, and <em>alternative</em>.</li> + <li><em>orderInCategory</em> - An integer that defines the default order of the items within the category.</li> + <li><em>checkableBehavior</em> - Whether the items are checkable. Valid values: + <em>none</em>, <em>all</em> (exclusive / radio buttons), <em>single</em> (non-exclusive / checkboxes)</li> + <li><em>visible</em> - Whether the group is visible. <em>true</em> or <em>false</em>.</li> + <li><em>enabled</em> - Whether the group is enabled. <em>true</em> or <em>false</em>.</li> + </ul> + </dd> + <dt><item></dt> + <dd>A menu item. May contain a <code><menu></code> element (for a Sub Menu). Valid attributes: + <ul> + <li><em>id</em> - A unique resource ID for the item.</li> + <li><em>menuCategory</em> - Used to define the menu category.</li> + <li><em>orderInCategory</em> - Used to define the order of the item, within a group.</li> + <li><em>title</em> - A string for the menu title.</li> + <li><em>titleCondensed</em> - A condensed string title, for situations in which the normal title is too long.</li> + <li><em>icon</em> - A resource identifier for a drawable icon.</li> + <li><em>alphabeticShortcut</em> - A character for the alphabetic shortcut key.</li> + <li><em>numericShortcut</em> - A number for the numeric shortcut key.</li> + <li><em>checkable</em> - Whether the item is checkable. <em>true</em> or <em>false</em>.</li> + <li><em>checked</em> - Whether the item is checked by default. <em>true</em> or <em>false</em>.</li> + <li><em>visible</em> - Whether the item is visible by default. <em>true</em> or <em>false</em>.</li> + <li><em>enabled</em> - Whether the item is enabled by default. <em>true</em> or <em>false</em>.</li> + </ul> + </dd> +</dl> + +<p>For more discussion on how to create menus in XML and inflate them in your application, +read <a href="{@docRoot}guide/topics/views/menus.html">Creating Menus</a>.</p> + <h2 id="layoutresources">Layout</h2> @@ -797,10 +895,10 @@ res/layout/<em>some_file</em>.xml.</p> </p> <ul> <li> - <strong>Java</strong> <code>R.drawable.<em>some_file</em></code> + <strong>Java:</strong> <code>R.layout.<em>some_file</em></code> </li> <li> - <strong>XML</strong> <code>@[<em>package</em>:]layout/<em>some_file</em></code> + <strong>XML:</strong> <code>@[<em>package</em>:]layout/<em>some_file</em></code> </li> </ul> <p> @@ -996,10 +1094,10 @@ setContentView(R.layout.main_screen); </p> <ul> <li> - <strong>Java</strong> <code>R.style.<em>styleID</em></code> for the whole style, <code>R.style.<em>styleID</em>.<em>itemID</em></code> for an individual setting + <strong>Java:</strong> <code>R.style.<em>styleID</em></code> for the whole style, <code>R.style.<em>styleID</em>.<em>itemID</em></code> for an individual setting </li> <li> - <strong>XML</strong> <code>@[<em>package</em>:]style/<em>styleID</em></code> for a whole style, <code>@[<em>package</em>:]style/<em>styleID</em>/<em>itemID</em></code> for an individual item. <strong>Note</strong>: to refer to a value in the <em>currently</em> applied theme, use "?" instead of "@" as described below (XML). + <strong>XML:</strong> <code>@[<em>package</em>:]style/<em>styleID</em></code> for a whole style, <code>@[<em>package</em>:]style/<em>styleID</em>/<em>itemID</em></code> for an individual item. <strong>Note</strong>: to refer to a value in the <em>currently</em> applied theme, use "?" instead of "@" as described below (XML). </li> </ul> <p> diff --git a/docs/html/guide/topics/views/menus.jd b/docs/html/guide/topics/views/menus.jd new file mode 100644 index 0000000..489cd07 --- /dev/null +++ b/docs/html/guide/topics/views/menus.jd @@ -0,0 +1,516 @@ +page.title=Creating Menus +parent.title=User Interface +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#options-menu">Options Menu</a></li> + <li><a href="#context-menu">Context Menu</a></li> + <li><a href="#sub-menu">Sub Menu</a></li> + <li><a href="#xml">Define Menus in XML</a></li> + <li><a href="#features">Menu Features</a> + <ol> + <li><a href="#groups">Menu groups</a></li> + <li><a href="#checkable">Checkable menu items</a></li> + <li><a href="#shortcuts">Shortcut keys</a></li> + <li><a href="#intents">Menu item intents</a></li> + </ol> + </li> + </ol> +</div> +</div> + +<p>Menus are an important part of any application. They provide familiar interfaces +that reveal application functions and settings. Android offers an easy programming interface +for developers to provide standardized application menus for various situations.</p> + +<p>Android offers three fundamental types of application menus:</p> +<dl> + <dt><strong>Options Menu</strong></dt> + <dd>This is the primary set of menu items for an Activity. It is revealed by pressing + the device MENU key. Within the Options Menu are two groups of menu items: + <dl style="margin-top:1em"> + <dt><em>Icon Menu</em></dt> + <dd>This is the collection of items initially 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>This is a vertical list of items exposed by the "More" menu item from the Icon Menu. + It exists only when the Icon Menu becomes over-loaded and is comprised of the sixth + Option Menu item and the rest.</dd> + </dl> + </dd> + <dt><strong>Context Menu</strong></dt> + <dd>This is a floating list of menu items that may appear when you perform a long-press on a View + (such as a list item). </dd> + <dt><strong>Sub Menu</strong></dt> + <dd>This is a floating list of menu items that is revealed by an item in the Options Menu + or a Context Menu. A Sub Menu item cannot support nested Sub Menus. </dd> +</dl> + + +<h2 id="options-menu">Options Menu</h2> +<img align="right" src="{@docRoot}images/options_menu.png" /> +<p>The Options Menu is opened by pressing the device MENU key. +When opened, the Icon Menu is displayed, which holds the first six menu items. +If more than six items are added to the Options Menu, then those that can't fit +in the Icon Menu are revealed in the Expanded Menu, via the "More" menu item. The Expanded Menu +is automatically added when there are more than six items.</p> + +<p>The Options Menu is where you should include basic application functions +and any necessary navigation items (e.g., to a home screen or application settings). +You can also add <a href="#sub-menu">Sub Menus</a> for organizing topics +and including extra menu functionality.</p> + +<p>When this menu is opened for the first time, +the Android system will call the Activity <code>{@link android.app.Activity#onCreateOptionsMenu(Menu) +onCreateOptionsMenu()}</code> callback method. Override this method in your Activity +and populate the {@link android.view.Menu} object given to you. You can populate the menu by +inflating a menu resource that was <a href="#xml">defined in XML</a>, or by calling +<code>{@link android.view.Menu#add(CharSequence) add()}</code> +for each item you'd like in the menu. This method adds a {@link android.view.MenuItem}, and returns the +newly created object to you. You can use the returned MenuItem to set additional properties like +an icon, a keyboard shortcut, an intent, and other settings for the item.</p> + +<p>There are multiple <code>{@link android.view.Menu#add(CharSequence) add()}</code> methods. +Usually, you'll want to use one that accepts an <var>itemId</var> argument. +This is a unique integer that allows you to identify the item during a callback.</p> + +<p>When a menu item is selected from the Options Menu, you will recieve a callback to the +<code>{@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}</code> +method of your Activity. This callback passes you the +<code>MenuItem</code> that has been selected. You can identify the item by requesting the +<var>itemId</var>, with <code>{@link android.view.MenuItem#getItemId() getItemId()}</code>, +which returns the integer that was assigned with the <code>add()</code> method. Once you identify +the menu item, you can take the appropriate action.</p> + +<p>Here's an example of this procedure, inside an Activity, wherein we create an +Options Menu and handle item selections:</p> + +<pre> +/* Creates the menu items */ +public boolean onCreateOptionsMenu(Menu menu) { + menu.add(0, MENU_NEW_GAME, 0, "New Game"); + menu.add(0, MENU_QUIT, 0, "Quit"); + return true; +} + +/* Handles item selections */ +public boolean onOptionsItemSelected(MenuItem item) { + switch (item.getItemId()) { + case MENU_NEW_GAME: + newGame(); + return true; + case MENU_QUIT: + quit(); + return true; + } + return false; +} +</pre> + +<p>The <code>add()</code> method used in this sample takes four arguments: +<var>groupId</var>, <var>itemId</var>, <var>order</var>, and <var>title</var>. +The <var>groupId</var> allows you to associate this menu item with a group of other items +(more about <a href="#groups">Menu groups</a>, below) — in +this example, we ignore it. <var>itemId</var> is a unique integer that we give the +MenuItem so that can identify it in the next callback. <var>order</var> allows us to +define the display order of the item — by default, they are displayed by the +order in which we add them. <var>title</var> is, of course, the name that goes on the +menu item (this can also be a +<a href="{@docRoot}guide/topics/resources/available-resources.html#stringresources">string resource</a>, +and we recommend you do it that way for easier localization).</p> + +<p class="note"><strong>Tip:</strong> +If you have several menu items that can be grouped together with a title, +consider organizing them into a <a href="#sub-menu">Sub Menu</a>.</p> + +<h3>Adding icons</h3> +<p>Icons can also be added to items that appears in the Icon Menu with +<code>{@link android.view.MenuItem#setIcon(Drawable) setIcon()}</code>. For example:</p> +<pre> +menu.add(0, MENU_QUIT, 0, "Quit") + .setIcon(R.drawable.menu_quit_icon);</pre> + +<h3>Modifying the options menu</h3> +<p>If you want to sometimes re-write the options menu as it is opened, override the +<code>{@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()}</code> method, which is +called each time the menu is opened. This will pass you the Menu object, just like the +<code>onCreateOptionsMenu()</code> callback. This is useful if you'd like to add or remove +menu options depending on the current state of an application or game.</p> + +<p class="note"><strong>Note:</strong> +When changing items in the menu, it's bad practice to do so based on the currently selected item. +Keep in mind that, when in touch mode, there will not be a selected (or focused) item. Instead, you +should use a <a href="#context-menu">Context Menu</a> for such behaviors, when you want to provide +functionality based on a particular item in the UI.</p> + + +<h2 id="context-menu">Context Menu</h2> +<p>The Android context menu is similar, in concept, to the menu revealed with a "right-click" on a PC. +When a view is registered to a context menu, +performing a "long-press" (press and hold for about two seconds) on the object +will reveal a floating menu that provides functions relating to that item. +Context menus can be registered to any View object, +however, they are most often used for items in a +{@link android.widget.ListView}, which helpfully indicates the presence of the context menu +by transforming the background color of the ListView item when pressed. +(The items in the phone's contact list offer an example of this feature.) +</p> + +<p class="note"><strong>Note:</strong> Context menu items do not support icons or shortcut keys.</p> + +<p>To create a context menu, you must override the Activity's context menu callback methods: +<code>{@link android.app.Activity#onCreateContextMenu(ContextMenu,View,ContextMenuInfo) onCreateContextMenu()}</code> and +<code>{@link android.app.Activity#onContextItemSelected(MenuItem) onContextItemSelected()}</code>. +Inside the <code>onCreateContextMenu()</code> callback method, you can add menu items using one of the +<code>{@link android.view.Menu#add(CharSequence) add()}</code> methods, or by +inflating a menu resource that was <a href="#xml">defined in XML</a>. +Then, register a {@link android.view.ContextMenu} for the View, with +<code>{@link android.app.Activity#registerForContextMenu(View) registerForContextMenu()}</code>.</p> + +<p>For example, here is some code that can be used with the +<a href="{@docRoot}guide/tutorials/notepad/index.html">Notepad application</a> +to add a context menu for each note in the list:</p> +<pre> +public void onCreateContextMenu(ContextMenu menu, View v, + ContextMenuInfo menuInfo) { + super.onCreateContextMenu(menu, v, menuInfo); + menu.add(0, EDIT_ID, 0, "Edit"); + menu.add(0, DELETE_ID, 0, "Delete"); +} + +public boolean onContextItemSelected(MenuItem item) { + AdapterContextMenuInfo info = (AdapterContextMenuInfo) item.getMenuInfo(); + switch (item.getItemId()) { + case EDIT_ID: + editNote(info.id); + return true; + case DELETE_ID: + deleteNote(info.id); + return true; + default: + return super.onContextItemSelected(item); + } +} +</pre> + +<p>In <code>onCreateContextMenu()</code>, we are given not only the ContextMenu to +which we will add {@link android.view.MenuItem}s, but also the {@link android.view.View} +that was selected and a {@link android.view.ContextMenu.ContextMenuInfo ContextMenuInfo} object, +which provides additional information about the object that was selected. +In this example, nothing special is done in <code>onCreateContextMenu()</code> — just +a couple items are added as usual. In the <code>onContextItemSelected()</code> +callback, we request the {@link android.widget.AdapterView.AdapterContextMenuInfo AdapterContextMenuInfo} +from the {@code MenuItem}, which provides information about the currently selected item. +All we need from +this is the list ID for the selected item, so whether editing a note or deleting it, +we find the ID with the {@code AdapterContextMenuInfo.info} field of the object. This ID +is passed to the <code>editNote()</code> and <code>deleteNote()</code> methods to perfrom +the respective action.</p> + +<p>Now, to register this context menu for all the items in a {@link android.widget.ListView}, +we pass the entire {@code ListView} to the +<code>{@link android.app.Activity#registerForContextMenu(View)}</code> method:</p> + +<pre>registerForContextMenu(getListView());</pre> +<p>Remember, you can pass any View object to register a context menu. Here, +<code>{@link android.app.ListActivity#getListView()}</code> returns the ListView +object used in the Notepad application's {@link android.app.ListActivity}. As such, each item +in the list is registered to this context menu.</p> + + + +<h2 id="sub-menu">Sub Menus</h2> +<p>A sub menu can be added within any menu, except another sub menu. +These are very useful when your application has a lot of functions that may be +organized in topics, like the items in a PC application's menu bar (File, Edit, View, etc.).</p> + +<p>A sub menu is created by adding it to an existing {@link android.view.Menu} +with <code>{@link android.view.Menu#addSubMenu(CharSequence) addSubMenu()}</code>. +This returns a {@link android.view.SubMenu} object (an extension of {@link android.view.Menu}). +You can then add additional items to this menu, with the normal routine, using +the <code>{@link android.view.Menu#add(CharSequence) add()}</code> methods. For example:</p> + +<pre> +public boolean onCreateOptionsMenu(Menu menu) { + boolean result = super.onCreateOptionsMenu(menu); + + SubMenu fileMenu = menu.addSubMenu("File"); + SubMenu editMenu = menu.addSubMenu("Edit"); + fileMenu.add("new"); + fileMenu.add("open"); + fileMenu.add("save"); + editMenu.add("undo"); + editMenu.add("redo"); + + return result; +} +</pre> +<p>Callbacks for items selected in a sub menu are made to the parent menu's callback method. +For the example above, selections in the sub menu will be handled by the +<code>onOptionsItemSelected()</code> callback.</p> +<p>You can also add Sub Menus when you <a href="#xml">define the parent menu in XML</a>.</p> + + +<h2 id="xml">Define Menus in XML</h2> +<p>Just like Android UI layouts, you can define application menus in XML, then inflate them +in your menu's <code>onCreate...()</code> callback method. This makes your application code cleaner and +separates more interface design into XML, which is easier to visualize.</p> + +<p>To start, create a new folder in your project <code>res/</code> directory called <code>menu</code>. +This is where you should keep all XML files that define your application menus.</p> + +<p>In a menu XML layout, there are +three valid elements: <code><menu></code>, <code><group></code> and <code><item></code>. The +<code>item</code> and <code>group</code> elements must be children of a <code>menu</code>, but <code>item</code> +elements may also be the children of a <code>group</code>, and another <code>menu</code> element may be the child +of an <code>item</code> (to create a Sub Menu). Of course, the root node of any file +must be a <code>menu</code> element.</p> + +<p>As an example, we'll define the same menu created in the <a href="#options-menu">Options Menu</a> section, +above. We start with an XML file named <code>options_menu.xml</code> inside the <code>res/menu/</code> folder:</p> +<pre> +<menu xmlns:android="http://schemas.android.com/apk/res/android"> + <item android:id="@+id/new_game" + android:title="New Game" /> + <item android:id="@+id/quit" + android:title="Quit" /> +</menu> +</pre> + +<p>Then, in the <code>onCreateOptionsMenu()</code> method, we inflate this resource using +<code>{@link android.view.MenuInflater#inflate(int,Menu) MenuInflater.inflate()}</code>:</p> +<pre> +public boolean onCreateOptionsMenu(Menu menu) { + MenuInflater inflater = getMenuInflater(); + inflater.inflate(R.menu.options_menu, menu); + return true; +} +</pre> + +<p>The <code>{@link android.app.Activity#getMenuInflater()}</code> method returns the {@link android.view.MenuInflater} +for our activity's context. We then call <code>{@link android.view.MenuInflater#inflate(int,Menu) inflate()}</code>, +passing it a pointer to our menu resource and the Menu object given by the callback.</code></p> + +<p>While this small sample may seem like more effort, compared to creating the menu items in the +<code>onCreateOptionsMenu()</code> method, this will save a lot of trouble when dealing with more items +and it keeps your application code clean.</p> + +<p>You can define <a href="#groups">menu groups</a> by wrapping <code>item</code> elements in a <code>group</code> +element, and create Sub Menus by nesting another <code>menu</code> inside an <code>item</code>. +Each element also supports all the necessary attributes to control features like shortcut keys, +checkboxes, icons, and more. To learn about these attributes and more about the XML syntax, see the Menus +topic in the <a href="{@docRoot}guide/topics/resources/available-resources.html#menus">Available +Resource Types</a> document.</p> + +<h2 id="features">Menu Features</h2> +<p>Here are some other features that can be applied to most menu items.</p> + +<h3 id="groups">Menu groups</h3> +<p>When adding new items to a menu, you can optionally include each item in a group. +A menu group is a collection of menu items that can share certain traits, like +whether they are visible, enabled, or checkable.</p> + +<p>A group is defined by an integer (or a resource id, in XML). A menu item is added to the group when it is +added to the menu, using one of the <code>add()</code> methods that accepts a <var>groupId</var> +as an argument, such as <code>{@link android.view.Menu#add(int,int,int,int)}</code>.</p> + +<p>You can show or hide the entire group with +<code>{@link android.view.Menu#setGroupVisible(int,boolean) setGroupVisible()}</code>; +enable or disable the group with +<code>{@link android.view.Menu#setGroupEnabled(int,boolean) setGroupEnabled()}</code>; +and set whether the items can be checkable with +<code>{@link android.view.Menu#setGroupCheckable(int,boolean,boolean) setGroupCheckable()}</code>. +</p> + +<h3 id="checkable">Checkable menu items</h3> +<img align="right" src="{@docRoot}images/radio_buttons.png" alt="" /> +<p>Any menu item can be used as an interface for turning options on and off. This can +be indicated with a checkbox for stand-alone options, or radio buttons for groups of +mutually exlusive options (see the screenshot, to the right).</p> + +<p class="note"><strong>Note:</strong> Menu items in the Icon Menu cannot +display a checkbox or radio button. If you choose to make items in the Icon Menu checkable, +then you must personally indicate the state by swapping the icon and/or text +each time the state changes between on and off.</p> + +<p>To make a single item checkable, use the <code>{@link android.view.MenuItem#setCheckable(boolean) +setCheckable()}</code> method, like so:</p> +<pre> +menu.add(0, VIBRATE_SETTING_ID, 0, "Vibrate") + .setCheckable(true); +</pre> +<p>This will display a checkbox with the menu item (unless it's in the Icon Menu). When the item +is selected, the <code>onOptionsItemSelected()</code> callback is called as usual. It is here that +you must set the state of the checkbox. You can query the current state of the item with +<code>{@link android.view.MenuItem#isChecked()}</code> and set the checked state with +<code>{@link android.view.MenuItem#setChecked(boolean) setChecked()}</code>. +Here's what this looks like inside the +<code>onOptionsItemSelected()</code> callback:</p> +<pre> +switch (item.getItemId()) { +case VIBRATE_SETTING_ID: + if (item.isChecked()) item.setChecked(false); + else item.setChecked(true); + return true; +... +} +</pre> + +<p>To make a group of mutually exclusive radio button items, simply +assign the same group ID to each menu item +and call <code>{@link android.view.Menu#setGroupCheckable(int,boolean,boolean) +setGroupCheckable()}</code>. In this case, you don't need to call <code>setCheckable()</code> +on each menu items, because the group as a whole is set checkable. Here's an example of +two mutually exclusive options in a sub-menu:</p> +<pre> +SubMenu subMenu = menu.addSubMenu("Color"); +subMenu.add(COLOR_MENU_GROUP, COLOR_RED_ID, 0, "Red"); +subMenu.add(COLOR_MENU_GROUP, COLOR_BLUE_ID, 0, "Blue"); +subMenu.setGroupCheckable(COLOR_MENU_GROUP, true, true); +</pre> +<p>In the <code>setGroupCheckable()</code> method, the first argument is the group ID +that we want to set checkable. The second argument is whether we want the group items +to be checkable. The last one is whether we want each item to be exclusively checkable +(if we set this <em>false</em>, then all the items will be checkboxes instead of radio buttons). +When the group is set to be exclusive (radio buttons), each time a new item is selected, +all other are automatically de-selected.</p> +<p> + +<p class="note"><strong>Note:</strong> +Checkable menu items are intended to be used only on a per-session basis and not saved to the device +(e.g., the <em>Map mode</em> setting in the Maps application is not saved — screenshot above). +If there are application settings that you would like to save for the user, +then you should store the data using <a href="#{@docRoot}guide/topics/data/data-storage.html#pref">Preferences</a>, +and manage them with a {@link android.preference.PreferenceActivity}.</p> + + +<h3 id="shortcuts">Shortcut keys</h3> +<p>Quick access shortcut keys using letters and/or numbers can be added to menu items with +<code>setAlphabeticShortcut(char)</code> (to set char shortcut), <code>setNumericShortcut(int)</code> +(to set numeric shortcut), +or <code>setShortcut(char,int)</code> (to set both)</code>. Case is <em>not</em> sensitive. + +For example:</p> +<pre> +menu.add(0, MENU_QUIT, 0, "Quit") + .setAlphabeticShortcut('q'); +</pre> +<p>Now, when the menu is open (or while holding the MENU key), pressing the "q" key will +select this item.</p> +<p>This shortcut key will be displayed as a tip in the menu item, below the menu item name +(except for items in the Icon Menu).</p> +<p class="note"><strong>Note:</strong> Shortcuts cannot be added to items in a Context Menu.</p> + + +<h3 id="intents">Menu item intents</h3> +<p>If you've read the <a href="{@docRoot}guide/topics/fundamentals.html">Application +Fundamentals</a>, then you're at least a little familiar +with Android Intents. These allow applications to bind with each other, share information, +and perform user tasks cooperatively. Just like your application might fire an Intent to launch a web browser, +an email client, or another Activity in your application, +you can perform such actions from within a menu. +There are two ways to do this: define an Intent and assign it to a single menu item, or +define an Intent and allow Android to search the device for activities and dynamically add a +menu item for each one that meets the Intent criteria.</p> + +<p>For more information on creating Intents and providing your application's services to other applications, +read the <a href="/guide/topics/intents/intents-filters.html">Intents +and Intent Filters</a> document.</p> + +<h4>Set an intent for a single menu item</h4> +<p>If you want to offer a specific menu item that launches a new Activity, then you +can specifically define an Intent for the menu item with the +<code>{@link android.view.MenuItem#setIntent(Intent) +setIntent()}</code> method.</p> + +<p>For example, inside the <code>{@link android.app.Activity#onCreateOptionsMenu(Menu) +onCreateOptionsMenu()}</code> method, you can define a new menu item with an Intent like this:</p> +<pre> +MenuItem menuItem = menu.add(0, PHOTO_PICKER_ID, 0, "Select Photo"); +menuItem.setIntent(new Intent(this, PhotoPicker.class)); +</pre> +<p>Android will automatically launch the Activity when the item is selected.</p> + +<p class="note"><strong>Note:</strong> This will not return a result to your Activity. +If you wish to be returned a result, then do not use <code>setIntent()</code>. +Instead, handle the selection as usual in the <code>onOptionsMenuItemSelected()</code> +or <code>onContextMenuItemSelected()</code> callback and call +<code>{@link android.app.Activity#startActivityForResult(Intent,int) startActivityForResult()}</code>. +</p> + +<h4>Dynamically add intents</h4> + +<p>If there are potentially multiple activities that are relevant to your current +Activity or selected item, then the application can dynamically add menu items that execute other +services.</p> +<p>During menu creation, define an Intent with the category <var>Intent.ALTERNATIVE_CATEGORY</var> and/or +<var>Intent.SELECTED_ALTERNATIVE</var>, the MIME type currently selected (if any), and any other +requirements, the same way as you would satisfy an intent filter to open a new +Activity. Then call +<code>{@link android.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[]) +addIntentOptions()}</code> to have Android search for any services meeting those requirements +and add them to the menu for you. If there are no applications installed +that satisfy the Intent, then no additional menu items are added.</p> + +<p class="note"><strong>Note:</strong> +<var>SELECTED_ALTERNATIVE</var> is used to handle the currently selected element on the +screen. So, it should only be used when creating a Menu in <code>onCreateContextMenu()</code> or +<code>onPrepareOptionsMenu()</code>, which is called every time the Options Menu is opened.</p> + +<p>Here's an example demonstrating how an application would search for +additional services to display on its menu.</p> + +<pre> +public boolean onCreateOptionsMenu(Menu menu){ + super.onCreateOptionsMenu(menu); + + // Create an Intent that describes the requirements to fulfill, to be included + // in our menu. The offering app must include a category value of Intent.CATEGORY_ALTERNATIVE. + Intent intent = new Intent(null, getIntent().getData()); + intent.addCategory(Intent.CATEGORY_ALTERNATIVE); + + // Search for, and populate the menu with, acceptable offering applications. + menu.addIntentOptions( + thisClass.INTENT_OPTIONS, // Menu group + 0, // Unique item ID (none) + 0, // Order for the items (none) + this.getComponentName(), // The current Activity name + null, // Specific items to place first (none) + intent, // Intent created above that describes our requirements + 0, // Additional flags to control items (none) + null); // Array of MenuItems that corrolate to specific items (none) + + return true; +}</pre> + +<p>For each Activity found that provides an Intent Filter matching the Intent defined, a menu +item will be added, using the <var>android:label</var> value of the intent filter as the text +for the menu item. +The <code>{@link android.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[]) addIntentOptions()}</code> method will also return the number of menu items added.</p> +<p>Also be aware that, when <code>addIntentOptions()</code> is called, it will override any and all +menu items in the menu group specified in the first argument.</p> + +<p>If you wish to offer the services of your Activity to other application menus, then you +only need to define an intent filter as usual. Just be sure to include the <var>ALTERNATIVE</var> and/or +<var>SELECTED_ALTERNATIVE</var> values in the <var>name</var> attribute of +a <code><category></code> element in the intent filter. For example:</p> +<pre> +<intent-filter label="Resize Image"> + ... + <category android:name="android.intent.category.ALTERNATIVE" /> + <category android:name="android.intent.category.SELECTED_ALTERNATIVE" /> + ... +</intent-filter> +</pre> +<p>read more about writing intent filters in the +<a href="/guide/topics/intents/intents-filters.html">Intents and Intent Filters</a> document.</p> + +<p>For a sample application using this technique, see the +<a href="{@docRoot}guide/samples/NotePad/index.html">Note Pad</a> +sample code.</p> |