android-3.1.jd revision 50e990c64fa23ce94efa76b9e72df7f8ec3cee6a
1page.title=Android 3.1 Platform 2sdk.platform.version=3.1 3sdk.platform.apiLevel=12 4@jd:body 5 6<div id="qv-wrapper"> 7<div id="qv"> 8 9<h2>In this document</h2> 10<ol> 11 <li><a href="#api">API Overview</a></li> 12 <li><a href="#api-level">API Level</a></li> 13</ol> 14 15<h2>Reference</h2> 16<ol> 17<li><a 18href="{@docRoot}sdk/api_diff/12/changes.html">API 19Differences Report »</a> </li> 20</ol> 21 22</div> 23</div> 24 25 26<p><em>API Level:</em> <strong>{@sdkPlatformApiLevel}</strong></p> 27 28<p>For developers, the Android {@sdkPlatformVersion} platform is available as a 29downloadable component for the Android SDK. The downloadable platform includes 30an Android library and system image, as well as a set of emulator skins and 31more. The downloadable platform includes no external libraries.</p> 32 33<p>For developers, the Android {@sdkPlatformVersion} platform is available as a 34downloadable component for the Android SDK. The downloadable platform includes 35an Android library and system image, as well as a set of emulator skins and 36more. To get started developing or testing against Android {@sdkPlatformVersion}, 37use the Android SDK Manager to download the platform into your SDK.</p> 38 39 40 41<h2 id="#api" style="margin-top:1.5em;">API Overview</h2> 42 43<p>The sections below provide a technical overview of what's new for developers 44in Android 3.1, including new features and changes in the framework API since 45the previous version.</p> 46 47<h3 id="usb">USB APIs</h3> 48 49<p>Android 3.1 introduces powerful new APIs for 50integrating connected peripherals with applications running on the platform. 51The APIs are based on a USB (Universal Serial Bus) stack and services that are 52built into the platform, including support for both USB host and device 53interactions. Using the APIs, developers can create applications that are able to 54discover, communicate with, and manage a variety of device types connected over 55USB. </p> 56 57<p>The stack and APIs distinguish two basic types of USB hardware, based on 58whether the Android-powered device is acting as host or the external hardware 59is acting as host: </p> 60 61<ul> 62<li>A <em>USB device</em> is a piece of connected hardware that depends on the 63Android-powered device to serve as host. For example, most input devices, mice, 64and joysticks are USB devices, as are many cameras, hubs, and so on.</li> 65<li>A <em>USB accessory</em> is a piece of connected hardware that has a USB 66host controller, provides power, and is designed to communicate with 67Android-powered devices over USB, A variety of peripherals can connect as 68accessories, from robotics controllers to musical equipment, exercise bicycles, 69and more.</li> 70</ul> 71 72<p>For both types — USB devices and USB accessories — the 73platform's USB APIs support discovery by intent broadcast when attached or 74detached, as well as standard interfaces, endpoints, and transfer modes 75(control, bulk, and interrupt).</p> 76 77<p>The USB APIs are available in the package {@link android.hardware.usb}. The 78central class is {@link android.hardware.usb.UsbManager}, which provides 79helper methods for identifying and communicating with 80both USB devices and USB accessories. Applications can acquire an instance of 81{@link android.hardware.usb.UsbManager} and then query for the list of attached 82devices or accessories and then communicate with or manage them. 83{@link android.hardware.usb.UsbManager} also declares intent actions that the 84system broadcasts, to announce when a USB device or accessory is attached or 85detached.</p> 86 87<p>Other classes include:</p> 88 89<ul> 90<li>{@link android.hardware.usb.UsbDevice}, a class representing external 91hardware connected as a USB device (with the Android-powered device acting as 92host).</li> 93<li>{@link android.hardware.usb.UsbAccessory}, representing external hardware 94connected as the USB host (with the Android-powered device acting as a USB 95device).</li> 96<li>{@link android.hardware.usb.UsbInterface} and {@link 97android.hardware.usb.UsbEndpoint}, which provide access to standard USB 98interfaces and endpoints for a device.</li> 99<li>{@link android.hardware.usb.UsbDeviceConnection} and {@link 100android.hardware.usb.UsbRequest}, for sending and receiving data and control 101messages to or from a USB device, sychronously and asynchronously. 102<li>{@link android.hardware.usb.UsbConstants}, which provides constants for 103declaring endpoint types, device classes, and so on.</li> 104</ul> 105 106<p>Note that although the USB stack is built into the platform, actual support 107for USB host and open accessory modes on specific devices is determined by 108their manufacturers. In particular, host mode relies on appropriate USB 109controller hardware in the Android-powered device. </p> 110 111<p>Additionally, developers can request filtering on Google Play, such that 112their applications are not availabe to users whose devices do not provide the 113appropriate USB support. To request filtering, add one or both of the elements 114below to the application manifest, as appropriate: </p> 115 116<ul> 117<li>If the application should only be visible to devices that support USB 118host mode (connection of USB devices), declare this element: 119 <p style="margin-left:1.5em;"><code><uses-feature 120 android:name="android.hardware.usb.host" 121 android:required="true"></code></p> 122</li> 123<li>If the application should only be visible to devices that support USB 124accessories (connection of USB hosts), declare this element: 125 <p style="margin-left:1.5em;"><code><uses-feature 126 android:name="android.hardware.usb.accessory" 127 android:required="true"></code></p> 128</li> 129</ul> 130 131<p>For complete information about how to develop applications that interact with 132USB accessories, please see the 133<a href="{@docRoot}guide/topics/connectivity/usb/index.html">developer documentation</a>.</p> 134 135<p class="note">To look at sample applications that use the USB host API, see <a 136href="{@docRoot}resources/samples/USB/AdbTest/index.html">ADB Test</a> and <a 137href="{@docRoot}resources/samples/USB/MissileLauncher/index.html">Missile 138Launcher</a></p> 139 140<h3>MTP/PTP API</h3> 141 142<p>Android 3.1 exposes a new MTP API that lets applications interact directly 143with connected cameras and other PTP devices. The new API makes it easy for an 144application to receive notifications when devices are attached and removed, 145manage files and storage on those devices, and transfer files and metadata to 146and from them. The MTP API implements the PTP (Picture Transfer Protocol) subset 147of the MTP (Media Transfer Protocol) specification.</p> 148 149<p>The MTP API is available in the {@link android.mtp} package and provides 150these classes: </p> 151 152<ul> 153 <li>The {@link android.mtp.MtpDevice} encapsulates an MTP device that is 154connected over the USB host bus. An application can instantiate an object of 155this type and then use its methods to get information about the device and 156objects stored on it, as well as opening the connection and transferring data. 157Some of the methods include: 158 <ul> 159 <li>{@link android.mtp.MtpDevice#getObjectHandles(int, int, int) 160getObjectHandles()} returns a list of handles for all objects on the device that 161match a specified format and parent. To get information about an object, an 162application can pass a handle to {@link android.mtp.MtpDevice#getObjectInfo(int) 163getObjectInfo()}.</li> 164 <li>{@link android.mtp.MtpDevice#importFile(int, java.lang.String) 165importFile()} lets an application copy data for an object to a file in external 166storage. This call may block for an arbitrary amount of time depending on the 167size of the data and speed of the devices, so should be made from a spearate 168thread.</li> 169 <li>{@link 170android.mtp.MtpDevice#open(android.hardware.usb.UsbDeviceConnection) open()} 171lets an application open a connected MTP/PTP device. </li> 172 <li>{@link android.mtp.MtpDevice#getThumbnail(int) getThumbnail()} returns 173the thumbnail of the object as a byte array. </li> 174 </ul> 175 </li> 176 <li>{@link android.mtp.MtpStorageInfo} holds information about about a storage 177unit on an MTP device, corresponding to the StorageInfo Dataset described in 178section 5.2.2 of the MTP specification. Methods in the class let an application 179get a storage unit’s description string, free space, maximum storage capacity, 180storage ID, and volume identifier.</li> 181 <li>{@link android.mtp.MtpDeviceInfo} holds information about an MTP device 182corresponding to the DeviceInfo Dataset described in section 5.1.1 of the MTP 183specification. Methods in the class let applications get a device’s 184manufacturer, model, serial number, and version.</li> 185 <li>{@link android.mtp.MtpObjectInfo} holds information about an object stored 186on an MTP device, corresponding to the ObjectInfo Dataset described in section 1875.3.1 of the MTP specification. Methods in the class let applications get an 188object’s size, data format, association type, creation date, and thumbnail 189information.</li> 190 <li>{@link android.mtp.MtpConstants} provides constants for declaring MTP file 191format codes, association type, and protection status.</li> 192</ul> 193 194<h3 id="motionevents">Support for new input devices and motion events</h3> 195 196<p>Android 3.1 extends the input subsystem to support new input devices and new 197types of motion events, across all views and windows. Developers can build on 198these capabilities to let users interact with their applications using mice, 199trackballs, joysticks, gamepads, and other devices, in addition to keyboards and 200touchscreens. </p> 201 202<p>For handling mouse, scrollwheel, and trackball input, the platform supports 203two new motion event actions:</p> 204<ul> 205<li>{@link android.view.MotionEvent#ACTION_SCROLL}, which describes the pointer 206location at which a non-touch scroll motion, such as from a mouse scroll wheel, 207took place. In the MotionEvent, the value of the {@link 208android.view.MotionEvent#AXIS_HSCROLL} and {@link 209android.view.MotionEvent#AXIS_VSCROLL} axes specify the relative scroll 210movement. </li> 211<li>{@link android.view.MotionEvent#ACTION_HOVER_MOVE}, reports the current 212position of the mouse when no buttons are pressed, as well as any intermediate 213points since the last <code>HOVER_MOVE</code> event. Hover enter and exit 214notifications are not yet supported.</li> 215</ul> 216 217<p>To support joysticks and gamepads, the {@link android.view.InputDevice} class 218includes these new input device sources:</p> 219<ul> 220<li>{@link android.view.InputDevice#SOURCE_CLASS_JOYSTICK} — the source 221device has joystick axes.</li> 222<li>{@link android.view.InputDevice#SOURCE_CLASS_BUTTON} — the source 223device has buttons or keys.</li> 224<li>{@link android.view.InputDevice#SOURCE_GAMEPAD} — the source device 225has gamepad buttons such as {@link android.view.KeyEvent#KEYCODE_BUTTON_A} 226or {@link android.view.KeyEvent#KEYCODE_BUTTON_B}. Implies 227{@link android.view.InputDevice#SOURCE_CLASS_BUTTON}</li> 228<li>{@link android.view.InputDevice#SOURCE_JOYSTICK} — the source device 229has joystick axes. Implies SOURCE_CLASS_JOYSTICK.</li> 230</ul> 231 232<p>To describe motion events from these new sources, as well as those from mice 233and trackballs, the platform now defines axis codes on {@link 234android.view.MotionEvent}, similar to how it defines key codes on {@link 235android.view.KeyEvent}. New axis codes for joysticks 236and game controllers include 237{@link android.view.MotionEvent#AXIS_HAT_X}, {@link 238android.view.MotionEvent#AXIS_HAT_Y}, {@link 239android.view.MotionEvent#AXIS_RTRIGGER}, {@link 240android.view.MotionEvent#AXIS_ORIENTATION}, {@link 241android.view.MotionEvent#AXIS_THROTTLE}, and many others. 242Existing {@link android.view.MotionEvent} axes are represented by {@link 243android.view.MotionEvent#AXIS_X}, {@link android.view.MotionEvent#AXIS_Y}, 244{@link android.view.MotionEvent#AXIS_PRESSURE}, {@link 245android.view.MotionEvent#AXIS_SIZE}, {@link 246android.view.MotionEvent#AXIS_TOUCH_MAJOR}, {@link 247android.view.MotionEvent#AXIS_TOUCH_MINOR}, {@link 248android.view.MotionEvent#AXIS_TOOL_MAJOR}, {@link 249android.view.MotionEvent#AXIS_TOOL_MINOR}, and {@link 250android.view.MotionEvent#AXIS_ORIENTATION}.</p> 251 252<p>Additionally, {@link android.view.MotionEvent} defines a number of generic 253axis codes that are used when the framework does not know how to map a 254particular axis. Specific devices can use the generic axis codes to pass custom 255motion data to applications. For a full list of axes and their intended 256interpretations, see the {@link android.view.MotionEvent} class documentation. 257</p> 258 259<p>The platform provides motion events to applications in batches, so a single 260event may contain a current position and multiple so-called historical movements. 261Applications should use {@link android.view.MotionEvent#getHistorySize()} to get 262the number of historical samples, then retrieve and process all historical 263samples in order using {@link 264android.view.MotionEvent#getHistoricalAxisValue(int, int, int) 265getHistoricalAxisValue()}. After that, applications should process the current 266sample using {@link android.view.MotionEvent#getAxisValue(int) getAxisValue()}. 267</p> 268 269<p>Some axes can be retrieved using special accessor methods. For example, 270instead of calling {@link android.view.MotionEvent#getAxisValue(int) 271getAxisValue()}, applications can call {@link android.view.MotionEvent#getX(int) 272getX()}. Axes that have built-in accessors include {@link 273android.view.MotionEvent#AXIS_X}, {@link android.view.MotionEvent#AXIS_Y}, 274{@link android.view.MotionEvent#AXIS_PRESSURE}, {@link 275android.view.MotionEvent#AXIS_SIZE}, {@link 276android.view.MotionEvent#AXIS_TOUCH_MAJOR}, {@link 277android.view.MotionEvent#AXIS_TOUCH_MINOR}, {@link 278android.view.MotionEvent#AXIS_TOOL_MAJOR}, {@link 279android.view.MotionEvent#AXIS_TOOL_MINOR}, and {@link 280android.view.MotionEvent#AXIS_ORIENTATION}.</p> 281 282<p>Each input device has a unique, system-assigned ID and may also provide 283multiple sources. When a device provides multiple sources, more than one source 284can provide axis data using the same axis. For example, a touch event coming 285from the touch source uses the X axis for screen position data, while a joystick 286event coming from the joystick source will use the X axis for the stick position 287instead. For this reason, it's important for applications to interpret axis 288values according to the source from which they originate. When handling a motion 289event, applications should use methods on the {@link android.view.InputDevice} 290class to determine the axes supported by a device or source. Specifically, 291applications can use {@link android.view.InputDevice#getMotionRanges() 292getMotionRanges()} to query for all axes of a device or all axes of a given 293source of the device. In both cases, the range information for axes returned in 294the {@link android.view.InputDevice.MotionRange} object specifies the source for 295each axis value.</p> 296 297<p>Finally, since the motion events from joysticks, gamepads, mice, and 298trackballs are not touch events, the platform adds a new callback method for 299passing them to a {@link android.view.View} as "generic" motion events. 300Specifically, it reports the non-touch motion events to 301{@link android.view.View}s through a call to {@link 302android.view.View#onGenericMotionEvent(android.view.MotionEvent) 303onGenericMotionEvent()}, rather than to {@link 304android.view.View#onTouchEvent(android.view.MotionEvent) 305onTouchEvent()}.</p> 306 307<p>The platform dispatches generic motion events differently, depending on the 308event source class. {@link android.view.InputDevice#SOURCE_CLASS_POINTER} events 309go to the {@link android.view.View} under the pointer, similar to how touch 310events work. All others go to the currently focused {@link android.view.View}. 311For example, this means a {@link android.view.View} must take focus in order to 312receive joystick events. If needed, applications can handle these events at the 313level of Activity or Dialog by implementing {@link 314android.view.View#onGenericMotionEvent(android.view.MotionEvent) 315onGenericMotionEvent()} there instead.</p> 316 317<p class="note">To look at a sample application that uses joystick motion 318events, see <a 319href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/GameControllerInput.html">GameControllerInput</a> 320and <a 321href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/GameView.html">GameView</a>.</p> 322 323<h3>RTP API</h3> 324 325<p>Android 3.1 exposes an API to its built-in RTP (Real-time Transport Protocol) 326stack, which applications can use to manage on-demand or interactive data 327streaming. In particular, apps that provide VOIP, push-to-talk, conferencing, 328and audio streaming can use the API to initiate sessions and transmit or receive 329data streams over any available network.</p> 330 331<p>The RTP API is available in the {@link android.net.rtp} package. Classes 332include: </p> 333<ul> 334<li>{@link android.net.rtp.RtpStream}, the base class of streams that send and 335receive network packets with media payloads over RTP.</li> 336<li>{@link android.net.rtp.AudioStream}, a subclass of {@link 337android.net.rtp.RtpStream} that carries audio payloads over RTP.</li> 338<li>{@link android.net.rtp.AudioGroup}, a local audio hub for managing and 339mixing the device speaker, microphone, and {@link android.net.rtp.AudioStream}.</li> 340<li>{@link android.net.rtp.AudioCodec}, which holds a collection of codecs that 341you define for an {@link android.net.rtp.AudioStream}.</li> 342</ul> 343 344<p>To support audio conferencing and similar usages, an application instantiates 345two classes as endpoints for the stream:</p> 346 347<ul> 348<li>{@link android.net.rtp.AudioStream} specifies a remote endpoint and consists 349of network mapping and a configured {@link android.net.rtp.AudioCodec}.</li> 350<li>{@link android.net.rtp.AudioGroup} represents the local endpoint for one 351or more {@link android.net.rtp.AudioStream}s. The {@link android.net.rtp.AudioGroup} mixes 352all the {@link android.net.rtp.AudioStream}s and optionally interacts with the device 353speaker and the microphone at the same time.</li> 354</ul> 355 356<p>The simplest usage involves a single remote endpoint and local endpoint. 357For more complex usages, please refer to the limitations described for 358{@link android.net.rtp.AudioGroup}.</p> 359 360<p>To use the RTP API, applications must request permission from the user by 361declaring <code><uses-permission 362android:name="android.permission.INTERNET"></code> 363in their manifest files. To acquire the device microphone, the <code><uses-permission 364android:name="android.permission.RECORD_AUDIO"></code> permission is also required.</p> 365 366<h3 id="resizewidgets">Resizable app widgets</h3> 367 368<p>Starting in Android 3.1, developers can make their homescreen widgets 369resizeable — horizontally, vertically, or on both axes. Users touch-hold a 370widget to show its resize handles, then drag the horizontal and/or vertical 371handles to change the size on the layout grid. </p> 372 373<p>Developers can make any Home screen widget resizeable by defining a 374<code>resizeMode</code> attribute in the widget's {@link 375android.appwidget.AppWidgetProviderInfo} metadata. Values for the 376<code>resizeMode</code> attribute include "horizontal", "vertical", and "none". 377To declare a widget as resizeable horizontally and vertically, supply the value 378"horizontal|vertical". 379 380<p>Here's an example: </p> 381 382<pre><appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android" 383 android:minWidth="294dp" 384 android:minHeight="72dp" 385 android:updatePeriodMillis="86400000" 386 android:previewImage="@drawable/preview" 387 android:initialLayout="@layout/example_appwidget" 388 android:configure="com.example.android.ExampleAppWidgetConfigure" 389 android:resizeMode="horizontal|vertical" > 390</appwidget-provider></pre> 391 392<p>For more information about Home screen widgets, see the <a 393href="{@docRoot}guide/topics/appwidgets/index.html">App Widgets</a> 394documentation.</p> 395 396<h3 id="animation" style="margin-top:1.25em;">Animation framework</h3> 397 398<ul> 399<li>New ViewPropertyAnimator class 400 <ul> 401 <li>A new {@link android.view.ViewPropertyAnimator} class provides a 402convenient 403way for developers to animate select properties on {@link android.view.View} objects. The class 404automaties and optimizes the animation of the properties and makes it easier to 405manage multiple simulataneous animations on a {@link android.view.View} object. 406<p>Using the {@link android.view.ViewPropertyAnimator} is straightforward. To animate properties for 407a {@link android.view.View}, call {@link android.view.View#animate()} to 408construct a {@link android.view.ViewPropertyAnimator} object for that {@link android.view.View}. Use the 409methods on the {@link android.view.ViewPropertyAnimator} to specify what property to 410animate and how to animate it. For example, to fade the {@link android.view.View} to transparent, 411call <code>alpha(0);</code>. The {@link android.view.ViewPropertyAnimator} object 412handles the details of configuring the underlying {@link 413android.animation.Animator} class and starting it, then rendering the 414animation.</p></li> 415 </ul> 416</li> 417<li>Animation background color 418 <ul> 419 <li>New {@link android.view.animation.Animation#getBackgroundColor()} and 420 {@link android.view.animation.Animation#setBackgroundColor(int)} methods let 421 you get/set the background color behind animations, for window animations 422only. Currently the background must be black, with any desired alpha level.</li> 423 </ul> 424</li> 425<li>Getting animated fraction from <code>ViewAnimator</code> 426 <ul> 427 <li>A new {@link android.animation.ValueAnimator#getAnimatedFraction()} 428method 429lets you get the current animation fraction — the elapsed/interpolated 430fraction used in the most recent frame update — from a {@link 431android.animation.ValueAnimator}.</li> 432 </ul> 433</li> 434</ul> 435 436<h3 "ui">UI framework</h3> 437<ul> 438<li>Forced rendering of a layer 439 <ul> 440 <li>A new {@link android.view.View#buildLayer()} method lets an application 441force a View's layer to be created and the View rendered into it immediately. 442For example, an application could use this method to render a View into its 443layer before starting an animation. If the View is complex, rendering it into 444the layer before starting the animation will avoid skipping frames.</li> 445 </ul> 446</li> 447<li>Camera distance 448 <ul> 449 <li>Applications can use a new method 450{@link android.view.View#setCameraDistance(float)} to set the distance from the 451camera 452to a View. This gives applications improved control over 3D transformations of 453the View, such as rotations. </li> 454 </ul> 455</li> 456<li>Getting a calendar view from a DatePicker 457 <ul> 458 <li>A new {@link android.widget.DatePicker#getCalendarView()} method 459 lets you get a {@link android.widget.CalendarView} from a {@link 460android.widget.DatePicker} 461 instance.</li> 462 </ul> 463</li> 464<li>Getting callbacks when views are detached 465 <ul> 466 <li>A new {@link android.view.View.OnAttachStateChangeListener} lets you 467receive 468callbacks when a View is attached or detached from its window. Use {@link 469android.view.View#addOnAttachStateChangeListener(android.view.View.OnAttachStateChangeListener) addOnAttachStateChangeListener()} 470to add a listener and {@link 471android.view.View#removeOnAttachStateChangeListener(android.view.View.OnAttachStateChangeListener) addOnAttachStateChangeListener()} to remove it.</li> 472 </ul> 473</li> 474<li>Fragment breadcrumb listener, new onInflate() signature 475 <ul> 476 <li>A new method, {@link 477android.app.FragmentBreadCrumbs#setOnBreadCrumbClickListener(android.app.FragmentBreadCrumbs.OnBreadCrumbClickListener) setOnBreadCrumbClickListener()}, 478provides a hook to let 479applications intercept fragment-breadcrumb clicks and take any action needed 480before going to the backstack entry or fragment that was clicked. </li> 481 <li>In the {@link android.app.Fragment} class, {@link 482android.app.Fragment#onInflate(android.util.AttributeSet, android.os.Bundle) 483onInflate(attrs, savedInstanceState)} is deprecated. Please use {@link 484android.app.Fragment#onInflate(android.app.Activity, android.util.AttributeSet, 485android.os.Bundle) onInflate(activity, attrs, savedInstanceState)} instead.</li> 486 </ul> 487</li> 488<li>Display search result in new tab 489 <ul> 490 <li>An {@link android.app.SearchManager#EXTRA_NEW_SEARCH} data key for {@link 491android.content.Intent#ACTION_WEB_SEARCH} intents lets you open a search in a 492new browser tab, rather than in an existing one.</li> 493 </ul> 494</li> 495 496<li>Drawable text cursor 497 <ul> 498<li>You can now specify a drawable to use as the text cursor using the new 499resource attribute {@link android.R.attr#textCursorDrawable}.</li> 500 </ul> 501</li> 502<li>Setting displayed child in remote views 503 <ul> 504 <li>A new convenience method, {@link 505android.widget.RemoteViews#setDisplayedChild(int, int) setDisplayedChild(viewId, 506childIndex)}, is available in {@link android.widget.RemoteViews} subclasses, to 507let you set the child displayed in {@link android.widget.ViewAnimator} and 508{@link android.widget.AdapterViewAnimator} subclasses such as {@link 509android.widget.AdapterViewFlipper}, {@link android.widget.StackView}, {@link 510android.widget.ViewFlipper}, and {@link android.widget.ViewSwitcher}.</li> 511 </ul> 512</li> 513<li>Generic keys for gamepads and other input devices 514 <ul> 515 <li>{@link android.view.KeyEvent} adds a range of generic keycodes to 516 accommodate gamepad buttons. The class also adds 517 {@link android.view.KeyEvent#isGamepadButton(int)} and several other 518 helper methods for working with keycodes.</li> 519 </ul> 520</li> 521</ul> 522 523<h3 id="graphics" style="margin-top:1.3em;">Graphics</h3> 524 525<ul> 526<li>Helpers for managing bitmaps 527 <ul> 528 <li>{@link android.graphics.Bitmap#setHasAlpha(boolean)} lets an app indicate that 529all of the pixels in a Bitmap are known to be opaque (false) or that some of the 530pixels may contain non-opaque alpha values (true). Note, for some configs (such 531as RGB_565) this call is ignored, since it does not support per-pixel alpha 532values. This is meant as a drawing hint, as in some cases a bitmap that is known 533to be opaque can take a faster drawing case than one that may have non-opaque 534per-pixel alpha values. </li> 535 <li>{@link android.graphics.Bitmap#getByteCount()} gets a Bitmap's size in 536bytes.</li> 537 <li>{@link android.graphics.Bitmap#getGenerationId()} lets an application find 538out whether a Bitmap has been modified, such as for caching.</li> 539 <li>{@link android.graphics.Bitmap#sameAs(android.graphics.Bitmap)} determines 540whether a given Bitmap differs from the current Bitmap, in dimension, 541configuration, or pixel data. </li> 542 </ul> 543</li> 544<li>Setting camera location and rotation 545 <ul> 546 <li>{@link android.graphics.Camera} adds two new methods {@link 547android.graphics.Camera#rotate(float, float, float) rotate()} and {@link 548android.graphics.Camera#setLocation(float, float, float) setLocation()} for 549control of the 550camera's location, for 3D transformations.</li> 551</ul> 552</li> 553</ul> 554 555<h3 id="network" style="margin-top:1.25em;">Network</h3> 556 557<ul> 558<li>High-performance Wi-Fi lock 559 <ul> 560 <li>A new high-performance Wi-Fi lock lets applications maintain 561high-performance Wi-Fi connections even when the device screen is off. 562Applications that stream music, video, or voice for long periods can acquire the 563high-performance Wi-Fi lock to ensure streaming performance even when the screen 564is off. Because it uses more power, applications should acquire the 565high-performance Wi-Fi when there is a need for a long-running active 566connection. 567<p>To create a high-performance lock, pass {@link 568android.net.wifi.WifiManager#WIFI_MODE_FULL_HIGH_PERF} as the lock mode in a 569call to {@link android.net.wifi.WifiManager#createWifiLock(int, 570java.lang.String) createWifiLock()}.</p></li> 571 </ul> 572</li> 573<li>More traffic stats 574 <ul> 575 <li>Applications can now access statistics about more types of network usage 576using new methods in {@link android.net.TrafficStats}. Applications can use the 577methods to get UDP stats, packet count, TCP transmit/receive payload bytes and 578segments for a given UID.</li> 579 </ul> 580</li> 581<li>SIP auth username 582 <ul> 583 <li>Applications can now get and set the SIP auth username for a profile 584using 585the new methods {@link android.net.sip.SipProfile#getAuthUserName() 586getAuthUserName()} and {@link 587android.net.sip.SipProfile.Builder#setAuthUserName(java.lang.String) 588setAuthUserName()}.</li> 589 </ul> 590</li> 591</ul> 592 593 594<h3 id="download" style="margin-top:1.25em;">Download Manager</h3> 595<ul> 596<li>Handling of completed downloads 597 <ul> 598 <li>Applications can now initiate downloads that notify users only on 599completion. To initiate this type of download, applications pass {@link 600android.app.DownloadManager.Request#VISIBILITY_VISIBLE_NOTIFY_ONLY_COMPLETION} 601in the {@link 602android.app.DownloadManager.Request#setNotificationVisibility(int) 603setNotificationVisibility()} method of 604the a request object.</li> 605 <li>A new method, {@link 606android.app.DownloadManager#addCompletedDownload(java.lang.String, 607java.lang.String, boolean, java.lang.String, java.lang.String, long, boolean) 608addCompletedDownload()}, lets an application add a file to the 609downloads database, so that it can be managed by the Downloads application.</li> 610 </ul> 611</li> 612<li>Show downloads sorted by size 613 <ul> 614 <li>Applications can start the Downloads application in sort-by-size mode by 615adding the new extra {@link 616android.app.DownloadManager#INTENT_EXTRAS_SORT_BY_SIZE} to an {@link 617android.app.DownloadManager#ACTION_VIEW_DOWNLOADS} intent.</li> 618 </ul> 619</li> 620</ul> 621 622<h3 id="ime" style="margin-top:1.25em;">IME framework</h3> 623 624<ul> 625<li>Getting an input method's extra value key 626 <ul><li>The {@link android.view.inputmethod.InputMethodSubtype} adds the 627method 628{@link 629android.view.inputmethod.InputMethodSubtype#containsExtraValueKey(java.lang.String) containsExtraValueKey()} to check whether an ExtraValue string is stored 630for the subtype and 631the method {@link 632android.view.inputmethod.InputMethodSubtype#getExtraValueOf(java.lang.String) 633getExtraValueOf()} to extract a specific key value from the ExtraValue hashmap. 634</li> 635 </ul> 636</li> 637</ul> 638 639<h3 id="media" style="margin-top:1.25em;">Media</h3> 640 641<ul> 642<li>New streaming audio formats 643 <ul> 644 <li>The media framework adds built-in support for raw ADTS AAC content, for 645improved streaming audio, as well as support for FLAC audio, for highest quality 646(lossless) compressed audio content. See the <a 647href="{@docRoot}guide/appendix/media-formats.html">Supported Media Formats</a> 648document for more information.</p></li> 649 </ul> 650</li> 651</ul> 652 653<h3 id="launchcontrols" style="margin-top:1.25em;">Launch controls on stopped 654applications</h3> 655 656<p>Starting from Android 3.1, the system's package manager keeps track of 657applications that are in a stopped state and provides a means of controlling 658their launch from background processes and other applications.</p> 659 660<p>Note that an application's stopped state is not the same as an Activity's 661stopped state. The system manages those two stopped states separately.</p> 662 663<p>The platform defines two new intent flags that let a sender specify 664whether the Intent should be allowed to activate components in stopped 665application.</p> 666 667<ul> 668<li>{@link android.content.Intent#FLAG_INCLUDE_STOPPED_PACKAGES} — 669Include intent filters of stopped applications in the list of potential targets 670to resolve against. </li> 671<li>{@link android.content.Intent#FLAG_EXCLUDE_STOPPED_PACKAGES} — 672Exclude intent filters of stopped applications from the list of potential 673targets.</li> 674</ul> 675 676<p>When neither or both of these flags is defined in an intent, the default 677behavior is to include filters of stopped applications in the list of 678potential targets.</p> 679 680<p>Note that the system adds {@link 681android.content.Intent#FLAG_EXCLUDE_STOPPED_PACKAGES} <em>to all broadcast 682intents</em>. It does this to prevent broadcasts from background services from 683inadvertently or unnecessarily launching components of stoppped applications. 684A background service or application can override this behavior by adding the 685{@link android.content.Intent#FLAG_INCLUDE_STOPPED_PACKAGES} flag to broadcast 686intents that should be allowed to activate stopped applications.</p> 687 688<p>Applications are in a stopped state when they are first installed but are not 689yet launched and when they are manually stopped by the user (in Manage 690Applications).</p> 691 692<h3 id="installnotification">Notification of application first launch and upgrade</h3> 693 694<p>The platform adds improved notification of application first launch and 695upgrades through two new intent actions:</p> 696 697<ul> 698<li>{@link android.content.Intent#ACTION_PACKAGE_FIRST_LAUNCH} — Sent to 699the installer package of an application when that application is first launched 700(that is, the first time it is moved out of a stopped state). The data 701contains the name of the package. </li> 702 703<li>{@link android.content.Intent#ACTION_MY_PACKAGE_REPLACED} — Notifies 704an application that it was updated, with a new version was installed over 705an existing version. This is only sent to the application that was replaced. It 706does not contain any additional data. To receive it, declare an intent filter 707for this action. You can use the intent to trigger code that helps get your 708application back in proper running shape after an upgrade. 709 710<p>This intent is sent directly to the application, but only if the application 711was upgraded while it was in started state (not in a stopped state).</p></li> 712 713</ul> 714 715<h3 id="other">Core utilities</h3> 716 717<ul> 718<li>LRU cache 719 <ul> 720 <li>A new {@link android.util.LruCache} class lets your applications benefit 721from efficient caching. Applications can use the class to reduce the time spent 722computing or downloading data from the network, while maintaining a sensible 723memory footprint for the cached data.{@link android.util.LruCache} is a cache 724that holds strong references to a limited number of values. Each time a value is 725accessed, it is moved to the head of a queue. When a value is added to a full 726cache, the value at the end of that queue is evicted and may become eligible for 727garbage collection.</li> 728 </ul> 729</li> 730<li>File descriptor as <code>int</code> 731 <ul> 732 <li>You can now get the native file descriptor int for a {@link 733android.os.ParcelFileDescriptor} using either of the new methods {@link 734android.os.ParcelFileDescriptor#getFd()} or {@link 735android.os.ParcelFileDescriptor#detachFd()}. </li> 736 </ul> 737</li> 738</ul> 739 740 741 742 743 744 745<h3 id="webkit" style="margin-top:1.25em;">WebKit</h3> 746 747<ul> 748 749<li>File scheme cookies 750 <ul> 751 <li>The {@link android.webkit.CookieManager} now supports cookies that use 752the 753<code>file:</code> URI scheme. You can use {@link 754android.webkit.CookieManager#setAcceptFileSchemeCookies(boolean) 755setAcceptFileSchemeCookies()} to 756enable/disable support for file scheme cookies, before constructing an instance 757of <code>WebView</code> or <code>CookieManager</code>. In a 758<code>CookieManager</code> instance, you can check whether file scheme cookies 759is enabled by calling {@link 760android.webkit.CookieManager#allowFileSchemeCookies()}.</li> 761 </ul> 762</li> 763<li>Notification of login request 764 <ul> 765 <li>To support the browser autologin features introduced in Android 3.0, the 766new 767method {@link 768android.webkit.WebViewClient#onReceivedLoginRequest(android.webkit.WebView,java.lang.String, java.lang.String, java.lang.String) onReceivedLoginRequest()} 769notifies the host 770application that an autologin request for the user was processed. </li> 771 </ul> 772</li> 773<li>Removed classes and interfaces 774 <ul> 775 <li>Several classes and interfaces were removed from the public API, after 776previously being in deprecated state. See the <a 777href="{@docRoot}sdk/api_diff/{@sdkPlatformApiLevel}/changes.html">API 778Differences Report</a> for more information.</p></li> 779 </ul> 780 </li> 781</ul> 782 783 784 785<h3 id="browser" style="margin-top:1.25em;">Browser</h3> 786 787<p>The Browser application adds the following features to support web 788applications:</p> 789 790<ul> 791<li>Support for inline playback of video embedded in HTML5 792<code><video></code> tag. Playback is hardware-accelerated where possible. 793</li> 794<li>Layer support for fixed position elements for all sites (mobile and 795desktop).</li> 796</ul> 797 798 799 800 801 802<h3 id="features">New feature constants</h3> 803 804<p>The platform adds new hardware feature constants that developers can declare 805in their application manifests, to inform external entities such as Google 806Play of the application's requirement for new hardware capabilities supported 807in this version of the platform. Developers declare these and other feature 808constants in <a 809href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code 810<uses-feature>}</a> manifest elements. 811 812<ul> 813 <li>{@link android.content.pm.PackageManager#FEATURE_USB_ACCESSORY 814android.hardware.usb.accessory} — The application uses the <a href="#usb">USB 815API</a> to communicate with external hardware devices connected over USB and 816function as hosts.</li> 817 <li>{@link android.content.pm.PackageManager#FEATURE_USB_HOST 818android.hardware.usb.host} — The application uses the <a href="#usb">USB API</a> 819to communicate with external hardware devices connected over USB and function as 820devices.</li> 821</ul> 822 823<p>Google Play filters applications based on features declared in <a 824href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code 825<uses-feature>}</a> manifest elements. For more information about 826declaring features in an application manifest, read <a 827href="{@docRoot}guide/google/play/filters.html">Google Play 828Filters</a>.</p> 829 830 831 832<h3 id="api-diff">API Differences Report</h3> 833 834<p>For a detailed view of all API changes in Android {@sdkPlatformVersion} (API 835Level 836{@sdkPlatformApiLevel}), see the <a 837href="{@docRoot}sdk/api_diff/{@sdkPlatformApiLevel}/changes.html">API 838Differences Report</a>.</p> 839 840 841 842 843 844<h2 id="api-level">API Level</h2> 845 846<p>The Android {@sdkPlatformVersion} platform delivers an updated version of 847the framework API. The Android {@sdkPlatformVersion} API 848is assigned an integer identifier — 849<strong>{@sdkPlatformApiLevel}</strong> — that is 850stored in the system itself. This identifier, called the "API Level", allows the 851system to correctly determine whether an application is compatible with 852the system, prior to installing the application. </p> 853 854<p>To use APIs introduced in Android {@sdkPlatformVersion} in your application, 855you need compile the application against the Android library that is provided in 856the Android {@sdkPlatformVersion} SDK platform. Depending on your needs, you 857might 858also need to add an <code>android:minSdkVersion="{@sdkPlatformApiLevel}"</code> 859attribute to the <code><uses-sdk></code> element in the application's 860manifest.</p> 861 862<p>For more information, read <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">What is API 863Level?</a></p> 864