1 page.title=Android 3.0 APIs 2 sdk.platform.version=3.0 3 sdk.platform.apiLevel=11 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 18 href="{@docRoot}sdk/api_diff/11/changes.html">API 19 Differences 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 downloadable 29 component for the Android SDK. The downloadable platform includes an Android library and system 30 image, as well as a set of emulator skins and more. The downloadable platform includes no external 31 libraries.</p> 32 33 <p>For developers, the Android {@sdkPlatformVersion} platform is available as a 34 downloadable component for the Android SDK. The downloadable platform includes 35 an Android library and system image, as well as a set of emulator skins and 36 more. To get started developing or testing against Android {@sdkPlatformVersion}, 37 use the Android SDK Manager to download the platform into your SDK.</p> 38 39 40 41 42 43 44 <h2 id="#api">API Overview</h2> 45 46 <p>The sections below provide a technical overview of what's new for developers in Android 3.0, 47 including new features and changes in the framework API since the previous version.</p> 48 49 50 51 52 53 <h3>Fragments</h3> 54 55 <p>A fragment is a new framework component that allows you to separate distinct elements of an 56 activity into self-contained modules that define their own UI and lifecycle. To create a 57 fragment, you must extend the {@link android.app.Fragment} class and implement several lifecycle 58 callback methods, similar to an {@link android.app.Activity}. You can then combine multiple 59 fragments in a single activity to build a multi-pane UI in which each 60 pane manages its own lifecycle and user inputs.</p> 61 62 <p>You can also use a fragment without providing a UI and instead use the fragment as a worker 63 for the activity, such as to manage the progress of a download that occurs only while the 64 activity is running.</p> 65 66 <p>Additionally:</p> 67 68 <ul> 69 <li>Fragments are self-contained and you can reuse them in multiple activities</li> 70 <li>You can add, remove, replace and animate fragments inside the activity</li> 71 <li>You can add fragments to a back stack managed by the activity, preserving the state of 72 fragments as they are changed and allowing the user to navigate backward through the different 73 states</li> 74 <li>By <a 75 href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">providing 76 alternative layouts</a>, you can mix and match fragments, based 77 on the screen size and orientation</li> 78 <li>Fragments have direct access to their container activity and can contribute items to the 79 activity's Action Bar (discussed next)</li> 80 </ul> 81 82 <p>To manage the fragments in your activity, you must use the {@link 83 android.app.FragmentManager}, which provides several APIs for interacting with fragments, such 84 as finding fragments in the activity and popping fragments off the back stack to restore their 85 previous state.</p> 86 87 <p>To perform a transaction, such as add or remove a fragment, you must create a {@link 88 android.app.FragmentTransaction}. You can then call methods such as {@link 89 android.app.FragmentTransaction#add add()} {@link android.app.FragmentTransaction#remove 90 remove()}, or {@link android.app.FragmentTransaction#replace replace()}. Once you've applied all 91 the changes you want to perform for the transaction, you must call {@link 92 android.app.FragmentTransaction#commit commit()} and the system applies the fragment transaction to 93 the activity.</p> 94 95 <p>For more information about using fragments, read the <a 96 href="{@docRoot}guide/components/fragments.html">Fragments</a> documentation. Several 97 samples are also available in the <a 98 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#Fragment"> 99 API Demos</a> application.</p> 100 101 102 103 104 <h3>Action Bar</h3> 105 106 <p>The Action Bar is a replacement for the traditional title bar at the top of the activity window. 107 It includes the application logo in the left corner and provides a new interface for items in the 108 <a href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options Menu</a>. Additionally, the 109 Action Bar allows you to:</p> 110 111 <ul> 112 <li>Add menu items directly in the Action Bar—as "action items." 113 <p>In your XML declaration for the menu item, include the {@code 114 android:showAsAction} attribute with a value of {@code "ifRoom"}. When there's enough room, the menu 115 item appears directly in the Action Bar. Otherwise, the item is placed in the 116 overflow menu, revealed by the menu icon on the right side of the Action Bar.</p></li> 117 118 <li>Replace an action item with a widget (such as a search box)—creating an 119 "action view." 120 <p>In the XML declaration for the menu item, add the {@code android:actionViewLayout} attribute 121 with a layout resource or the {@code android:actionViewClass} attribute with the class name of a 122 widget. (You must also declare the {@code android:showAsAction} attribute so that the item appears 123 in the Action Bar.) If there's not enough room in the Action Bar and the item appears in the 124 overflow menu, it behaves like a regular menu item and does not show the widget.</p></li> 125 126 <li>Add an action to the application logo and replace it with a custom logo 127 <p>The application logo is automatically assigned the {@code android.R.id.home} ID, 128 which the system delivers to your activity's {@link android.app.Activity#onOptionsItemSelected 129 onOptionsItemSelected()} callback when touched. Simply respond to this ID in your callback 130 method to perform an action such as go to your application's "home" activity.</p> 131 <p>To replace the icon with a logo, specify your application logo in the manifest file with the 132 <a href="{@docRoot}guide/topics/manifest/application-element.html#logo">{@code android:logo}</a> 133 attribute, then call {@link android.app.ActionBar#setDisplayUseLogoEnabled 134 setDisplayUseLogoEnabled(true)} in your activity.</p></li> 135 136 <li>Add breadcrumbs to navigate backward through the back stack of fragments</li> 137 <li>Add tabs or a drop-down list to navigate through fragments</li> 138 <li>Customize the Action Bar with themes and backgrounds</li> 139 </ul> 140 141 <p>The Action Bar is standard for all applications that use the new holographic theme, which is 142 also standard when you set either the <a 143 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code 144 android:minSdkVersion}</a> or <a 145 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code 146 android:targetSdkVersion}</a> to {@code "11"}.</p> 147 148 <p>For more information about the Action Bar, read the <a 149 href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> documentation. Several 150 samples are also available in the <a 151 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#ActionBar"> 152 API Demos</a> application.</p> 153 154 155 156 157 <h3>System clipboard</h3> 158 159 <p>Applications can now copy and paste data (beyond mere text) to and from the system-wide 160 clipboard. Clipped data can be plain text, a URI, or an intent.</p> 161 162 <p>By providing the system access to the data you want the user to copy, through a content provider, 163 the user can copy complex content (such as an image or data structure) from your application and 164 paste it into another application that supports that type of content.</p> 165 166 <p>To start using the clipboard, get the global {@link android.content.ClipboardManager} object 167 by calling {@link android.content.Context#getSystemService getSystemService(CLIPBOARD_SERVICE)}.</p> 168 169 <p>To copy an item to the clipboard, you need to create a new {@link 170 android.content.ClipData} object, which holds one or more {@link android.content.ClipData.Item} 171 objects, each describing a single entity. To create a {@link android.content.ClipData} object 172 containing just one {@link android.content.ClipData.Item}, you can use one of the helper methods, 173 such as {@link android.content.ClipData#newPlainText newPlainText()}, {@link 174 android.content.ClipData#newUri newUri()}, and {@link android.content.ClipData#newIntent 175 newIntent()}, which each return a {@link android.content.ClipData} object pre-loaded with the 176 {@link android.content.ClipData.Item} you provide.</p> 177 178 <p>To add the {@link android.content.ClipData} to the clipboard, pass it to {@link 179 android.content.ClipboardManager#setPrimaryClip setPrimaryClip()} for your instance of {@link 180 android.content.ClipboardManager}.</p> 181 182 <p>You can then read a file from the clipboard (in order to paste it) by calling {@link 183 android.content.ClipboardManager#getPrimaryClip()} on the {@link 184 android.content.ClipboardManager}. Handling the {@link android.content.ClipData} you receive can 185 be complicated and you need to be sure you can actually handle the data type in the clipboard 186 before attempting to paste it.</p> 187 188 <p>The clipboard holds only one piece of clipped data (a {@link android.content.ClipData} 189 object) at a time, but one {@link android.content.ClipData} can contain multiple {@link 190 android.content.ClipData.Item}s.</p> 191 192 <p>For more information, read the <a href="{@docRoot}guide/topics/text/copy-paste.html">Copy 193 and Paste</a> documentation. You can also see a simple implementation of copy and paste in the API Demos 194 sample and a more complete implementation in the Note Pad sample.</p> 195 196 197 198 199 <h3>Drag and drop</h3> 200 201 <p>New APIs simplify drag and drop operations in your application's user interface. A drag 202 operation is the transfer of some kind of data—carried in a {@link android.content.ClipData} 203 object—from one place to another. The start and end point for the drag operation is a {@link 204 android.view.View}, so the APIs that directly handle the drag and drop operations are 205 in the {@link android.view.View} class.</p> 206 207 <p>A drag and drop operation has a lifecycle that's defined by several drag actions—each 208 defined by a {@link android.view.DragEvent} object—such as {@link 209 android.view.DragEvent#ACTION_DRAG_STARTED}, {@link android.view.DragEvent#ACTION_DRAG_ENTERED}, and 210 {@link android.view.DragEvent#ACTION_DROP}. Each view that wants to participate in a drag 211 operation can listen for these actions.</p> 212 213 <p>To begin dragging content in your activity, call {@link android.view.View#startDrag startDrag()} 214 on a {@link android.view.View}, providing a {@link android.content.ClipData} object that represents 215 the data to drag, a {@link android.view.View.DragShadowBuilder} to facilitate the "shadow" 216 that users see under their fingers while dragging, and an {@link java.lang.Object} that can share 217 information about the drag object with views that may receive the object.</p> 218 219 <p>To accept a drag object in a {@link android.view.View} (receive the "drop"), register the view 220 with an {@link android.view.View.OnDragListener OnDragListener} by calling {@link 221 android.view.View#setOnDragListener setOnDragListener()}. When a drag event occurs on the view, the 222 system calls {@link android.view.View.OnDragListener#onDrag onDrag()} for the {@link 223 android.view.View.OnDragListener OnDragListener}, which receives a {@link android.view.DragEvent} 224 describing the type of drag action has occurred (such as {@link 225 android.view.DragEvent#ACTION_DRAG_STARTED}, {@link android.view.DragEvent#ACTION_DRAG_ENTERED}, and 226 {@link android.view.DragEvent#ACTION_DROP}). During a drag, the system repeatedly calls {@link 227 android.view.View.OnDragListener#onDrag onDrag()} for the view underneath the drag, to deliver a 228 stream of drag events. The receiving view can inquire the event type delivered to {@link 229 android.view.View#onDragEvent onDragEvent()} by calling {@link android.view.DragEvent#getAction 230 getAction()} on the {@link android.view.DragEvent}.</p> 231 232 <p class="note"><strong>Note:</strong> Although a drag event may carry a {@link 233 android.content.ClipData} object, this is not related to the system clipboard. A drag and drop 234 operation should never put the dragged data in the system clipboard.</p> 235 236 <p>For more information, read the <a href="{@docRoot}guide/topics/ui/drag-drop.html">Dragging and 237 Dropping</a> documentation. You can also see an implementation of drag and drop in the <a 238 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/DragAndDropDemo.html"> 239 API Demos</a> application and the <a 240 href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a> 241 application.</p> 242 243 244 245 <h3>App widgets</h3> 246 247 <p>Android 3.0 supports several new widget classes for more interactive app widgets on the users 248 Home screen, including: {@link android.widget.GridView}, {@link android.widget.ListView}, {@link 249 android.widget.StackView}, {@link android.widget.ViewFlipper}, and {@link 250 android.widget.AdapterViewFlipper}.</p> 251 252 <p>More importantly, you can use the new {@link android.widget.RemoteViewsService} to create app 253 widgets with collections, using widgets such as {@link android.widget.GridView}, {@link 254 android.widget.ListView}, and {@link android.widget.StackView} that are backed by remote data, 255 such as from a content provider.</p> 256 257 <p>The {@link android.appwidget.AppWidgetProviderInfo} class (defined in XML with an {@code 258 <appwidget-provider>} element) also supports two new fields: {@link 259 android.appwidget.AppWidgetProviderInfo#autoAdvanceViewId} and {@link 260 android.appwidget.AppWidgetProviderInfo#previewImage}. The {@link 261 android.appwidget.AppWidgetProviderInfo#autoAdvanceViewId} field lets you specify the view ID of the 262 app widget subview that should be auto-advanced by the app widgets host. The 263 {@link android.appwidget.AppWidgetProviderInfo#previewImage} field specifies a preview of what the 264 app widget looks like and is shown to the user from the widget picker. If this field is not 265 supplied, the app widget's icon is used for the preview.</p> 266 267 <p>To help create a preview image for your app widget (to specify in the {@link 268 android.appwidget.AppWidgetProviderInfo#previewImage} field), the Android emulator includes an 269 application called "Widget Preview." To create a preview image, launch this application, select the 270 app widget for your application and set it up how you'd like your preview image to appear, then save 271 it and place it in your application's drawable resources.</p> 272 273 <p>You can see an implementation of the new app widget features in the <a 274 href="{@docRoot}resources/samples/StackWidget/index.html">StackView App Widget</a> and <a 275 href="{@docRoot}resources/samples/WeatherListWidget/index.html">Weather List Widget</a> 276 applications.</p> 277 278 279 280 <h3>Status bar notifications</h3> 281 282 <p>The {@link android.app.Notification} APIs have been extended to support more content-rich status 283 bar notifications, plus a new {@link android.app.Notification.Builder} class allows you to easily 284 create {@link android.app.Notification} objects.</p> 285 <p>New features include:</p> 286 <ul> 287 <li>Support for a large icon in the notification, using {@link 288 android.app.Notification.Builder#setLargeIcon setLargeIcon()}. This is usually for 289 social applications to show the contact photo of the person who is the source of the 290 notification or for media apps to show an album thumbnail.</li> 291 <li>Support for custom layouts in the status bar ticker, using {@link 292 android.app.Notification.Builder#setTicker(CharSequence,RemoteViews) setTicker()}.</li> 293 <li>Support for custom notification layouts to include buttons with {@link 294 android.app.PendingIntent}s, for more interactive notification widgets. For example, a 295 notification can control music playback without starting an activity.</li> 296 </ul> 297 298 299 300 <h3>Content loaders</h3> 301 302 <p>New framework APIs facilitate asynchronous loading of data using the {@link 303 android.content.Loader} class. You can use it in combination with UI components such as views and 304 fragments to dynamically load data from worker threads. The {@link 305 android.content.CursorLoader} subclass is specially designed to help you do so for data backed by 306 a {@link android.content.ContentProvider}.</p> 307 308 <p>All you need to do is implement the {@link android.app.LoaderManager.LoaderCallbacks 309 LoaderCallbacks} interface to receive callbacks when a new loader is requested or the data has 310 changed, then call {@link android.app.LoaderManager#initLoader initLoader()} to initialize the 311 loader for your activity or fragment.</p> 312 313 <p>For more information, read the <a 314 href="{@docRoot}guide/components/loaders.html">Loaders</a> documentation. You can also see 315 example code using loaders in the <a 316 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderCursor.html">LoaderCursor</a> 317 and <a 318 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html"> 319 LoaderThrottle</a> samples.</p> 320 321 322 323 <h3>Bluetooth A2DP and headset APIs</h3> 324 325 <p>Android now includes APIs for applications to verify the state of connected Bluetooth A2DP and 326 headset profile devices. For example, applications can identify when a Bluetooth headset is 327 connected for listening to music and notify the user as appropriate. Applications can also receive 328 broadcasts for vendor specific AT commands and notify the user about the state of the connected 329 device, such as when the connected device's battery is low.</p> 330 331 <p>You can initialize the respective {@link android.bluetooth.BluetoothProfile} by calling {@link 332 android.bluetooth.BluetoothAdapter#getProfileProxy getProfileProxy()} with either the {@link 333 android.bluetooth.BluetoothProfile#A2DP} or {@link android.bluetooth.BluetoothProfile#HEADSET} 334 profile constant and a {@link android.bluetooth.BluetoothProfile.ServiceListener} to receive 335 callbacks when the Bluetooth client is connected or disconnected.</p> 336 337 338 339 340 <h3 id="animation">Animation framework</h3> 341 342 <p>An all new flexible animation framework allows you to animate arbitrary properties of any object 343 (View, Drawable, Fragment, Object, or anything else). It allows you to define several aspects of an 344 animation, such as:</p> 345 <ul> 346 <li>Duration</li> 347 <li>Repeat amount and behavior</li> 348 <li>Type of time interpolation</li> 349 <li>Animator sets to play animations together, sequentially, or after specified delays</li> 350 <li>Frame refresh delay</li> 351 </ul> 352 353 <p>You can define these animation aspects, and others, for an object's int, float, and hexadecimal 354 color values, by default. That is, when an object has a property field for one of these types, you 355 can change its value over time to affect an animation. To animate any other type of value, you tell 356 the system how to calculate the values for that given type, by implementing the {@link 357 android.animation.TypeEvaluator} interface.</p> 358 359 <p>There are two animators you can use to animate the values of a property: {@link 360 android.animation.ValueAnimator} and {@link android.animation.ObjectAnimator}. The {@link 361 android.animation.ValueAnimator} computes the animation values, but is not aware of the specific 362 object or property that is animated as a result. It simply performs the calculations, and you must 363 listen for the updates and process the data with your own logic. The {@link 364 android.animation.ObjectAnimator} is a subclass of {@link android.animation.ValueAnimator} and 365 allows you to set the object and property to animate, and it handles all animation work. 366 That is, you give the {@link android.animation.ObjectAnimator} the object to animate, the 367 property of the object to change over time, and a set of values to apply to the property over 368 time, then start the animation.</p> 369 370 <p>Additionally, the {@link android.animation.LayoutTransition} class enables automatic transition 371 animations for changes you make to your activity layout. To enable transitions for part of the 372 layout, create a {@link android.animation.LayoutTransition} object and set it on 373 any {@link android.view.ViewGroup} by calling {@link 374 android.view.ViewGroup#setLayoutTransition setLayoutTransition()}. This causes default 375 animations to run whenever items are added to or removed from the group. To specify custom 376 animations, call {@link android.animation.LayoutTransition#setAnimator setAnimator()} on the {@link 377 android.animation.LayoutTransition} and provide a custom {@link android.animation.Animator}, 378 such as a {@link android.animation.ValueAnimator} or {@link android.animation.ObjectAnimator} 379 discussed above.</p> 380 381 <p>For more information, see the <a 382 href="{@docRoot}guide/topics/graphics/prop-animation.html">Property Animation</a> documentation. You can 383 also see several samples using the animation APIs in the <a 384 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/index.html">API 385 Demos</a> application.</p> 386 387 388 389 390 <h3>Extended UI framework</h3> 391 392 <ul> 393 394 <li><b>Multiple-choice selection for ListView and GridView</b> 395 396 <p>New {@link android.widget.AbsListView#CHOICE_MODE_MULTIPLE_MODAL} mode for {@link 397 android.widget.AbsListView#setChoiceMode setChoiceMode()} allows users to select multiple items 398 from a {@link android.widget.ListView} or {@link android.widget.GridView}. When used in 399 conjunction with the Action Bar, users can select multiple items and then select the action to 400 perform from a list of options in the Action Bar (which has transformed into a Multi-choice 401 Action Mode).</p> 402 403 <p>To enable multiple-choice selection, call {@link 404 android.widget.AbsListView#setChoiceMode setChoiceMode(CHOICE_MODE_MULTIPLE_MODAL)} and register a 405 {@link android.widget.AbsListView.MultiChoiceModeListener MultiChoiceModeListener} with {@link 406 android.widget.AbsListView#setMultiChoiceModeListener setMultiChoiceModeListener()}.</p> 407 408 <p>When the user performs a long-press on an item, the Action Bar switches to the Multi-choice 409 Action Mode. The system notifies the {@link android.widget.AbsListView.MultiChoiceModeListener 410 MultiChoiceModeListener} when items are selected by calling {@link 411 android.widget.AbsListView.MultiChoiceModeListener#onItemCheckedStateChanged 412 onItemCheckedStateChanged()}.</p> 413 414 <p>For an example of multiple-choice selection, see the <a 415 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List15.html">List15. 416 java</a> 417 class in the API Demos sample application.</p> 418 </li> 419 420 421 <li><b>New APIs to transform views</b> 422 423 <p>New APIs allow you to easily apply 2D and 3D transformations to views in your activity 424 layout. New transformations are made possible with a set of object properties that define the view's 425 layout position, orientation, transparency and more.</p> 426 <p>New methods to set the view properties include: {@link android.view.View#setAlpha 427 setAlpha()}, {@link 428 android.view.View#setBottom setBottom()}, {@link android.view.View#setLeft setLeft()}, {@link 429 android.view.View#setRight setRight()}, {@link android.view.View#setBottom setBottom()}, {@link 430 android.view.View#setPivotX setPivotX()}, {@link android.view.View#setPivotY setPivotY()}, {@link 431 android.view.View#setRotationX setRotationX()}, {@link android.view.View#setRotationY 432 setRotationY()}, {@link android.view.View#setScaleX setScaleX()}, {@link android.view.View#setScaleY 433 setScaleY()}, {@link android.view.View#setAlpha setAlpha()}, and others.</p> 434 435 <p>Some methods also have a corresponding XML attribute that you can specify in your layout 436 file, to apply a default transformation. Available attributes include: {@code translationX}, {@code 437 translationY}, {@code rotation}, 438 {@code rotationX}, {@code rotationY}, {@code scaleX}, {@code scaleY}, {@code transformPivotX}, 439 {@code transformPivotY}, and {@code alpha}.</p> 440 441 <p>Using some of these new view properties in combination with the new <a 442 href="#animation">animation framework</a> (discussed 443 above), you can easily apply some fancy animations to your views. For example, to rotate a 444 view on its y-axis, supply {@link android.animation.ObjectAnimator} with the {@link 445 android.view.View}, the "rotationY" property, and the start and end values:</p> 446 <pre> 447 ObjectAnimator animator = ObjectAnimator.ofFloat(myView, "rotationY", 0, 360); 448 animator.setDuration(2000); 449 animator.start(); 450 </pre> 451 </li> 452 453 454 <li><b>New holographic themes</b> 455 456 <p>The standard system widgets and overall look have been redesigned and incorporate a new 457 "holographic" user interface theme. The system applies the new theme 458 using the standard <a href="{@docRoot}guide/topics/ui/themes.html">style and theme</a> system.</p> 459 460 <p>Any application that targets the Android 3.0 platform—by setting either the <a 461 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> 462 or <a 463 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code 464 android:targetSdkVersion}</a> value to {@code "11"}—inherits the holographic theme by default. 465 However, if your application also applies its own theme, then your theme will override the 466 holographic theme, unless you update your styles to inherit the holographic theme.</p> 467 468 <p>To apply the holographic theme to individual activities or to inherit them in your own theme 469 definitions, use one of several new {@link android.R.style#Theme_Holo Theme.Holo} 470 themes. If your application is compatible with version of Android lower than 3.0 and applies 471 custom themes, then you should <a 472 href="{@docRoot}guide/topics/ui/themes.html#SelectATheme">select a theme based on platform 473 version</a>.</p> 474 475 </li> 476 477 478 <li><b>New widgets</b> 479 480 <ul> 481 <li>{@link android.widget.AdapterViewAnimator} 482 <p>Base class for an {@link android.widget.AdapterView} that performs animations when switching 483 between its views.</p></li> 484 485 <li>{@link android.widget.AdapterViewFlipper} 486 <p>Simple {@link android.widget.ViewAnimator} that animates between two or more views that have 487 been added to it. Only one child is shown at a time. If requested, it can automatically flip 488 between 489 each child at a regular interval.</p></li> 490 491 <li>{@link android.widget.CalendarView} 492 <p>Allows users to select dates from a calendar by touching the date and can scroll or fling the 493 calendar to a desired date. You can configure the range of dates available in the widget.</p></li> 494 495 <li>{@link android.widget.ListPopupWindow} 496 <p>Anchors itself to a host view and displays a list of choices, such as for a list of 497 suggestions when typing into an {@link android.widget.EditText} view.</p></li> 498 499 <li>{@link android.widget.NumberPicker} 500 <p>Enables the user to select a number from a predefined range. The widget presents an input 501 field and up and down buttons for selecting a number. Touching the input field allows the user to 502 scroll through values or touch again to directly edit the current value. It also allows you to map 503 positions to strings, so that the corresponding string is displayed instead of the index 504 position.</p></li> 505 506 <li>{@link android.widget.PopupMenu} 507 <p>Displays a {@link android.view.Menu} in a modal popup window that's anchored to a view. The 508 popup appears below the anchor view if there is room, or above it if there is not. If the IME (soft 509 keyboard) is visible, the popup does not overlap the IME it until the user touches the 510 menu.</p></li> 511 512 <li>{@link android.widget.SearchView} 513 <p>Provides a search box that you can configure to deliver search queries to a specified 514 activity and display search suggestions (in the same manner as the traditional search dialog). This 515 widget is particularly useful for offering a search widget in the Action Bar. For more information, 516 see <a href="{@docRoot}guide/topics/search/search-dialog.html">Creating a Search Interface.</p></li> 517 518 <li>{@link android.widget.StackView} 519 <p>A view that displays its children in a 3D stack and allows users to swipe through 520 views like a rolodex.</p></li> 521 522 </ul> 523 </li> 524 525 </ul> 526 527 528 529 <h3>Graphics</h3> 530 531 <ul> 532 <li><b>Hardware accelerated 2D graphics</b> 533 534 <p>You can now enable the OpenGL renderer for your application by setting {@code 535 android:hardwareAccelerated="true"} in your manifest element's <a 536 href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> 537 element or for individual <a 538 href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> 539 elements.</p> 540 541 <p>This flag helps applications by making them draw faster. This results in smoother animations, 542 smoother scrolling, and overall better performance and response to user interaction.</p></li> 543 544 545 <li><b>View support for hardware and software layers</b> 546 547 <p>By default, a {@link android.view.View} has no layer specified. You can specify that the 548 view be backed by either a hardware or software layer, specified by values {@link 549 android.view.View#LAYER_TYPE_HARDWARE} and {@link android.view.View#LAYER_TYPE_SOFTWARE}, using 550 {@link android.view.View#setLayerType setLayerType()} or the <a 551 href="{@docRoot}reference/android/view/View.html#attr_android:layerType">{@code layerType}</a> 552 attribute.</p> 553 <p>A hardware layer is backed by a hardware specific texture (generally Frame Buffer Objects or 554 FBO on OpenGL hardware) and causes the view to be rendered using Android's hardware rendering 555 pipeline, but only if hardware acceleration is turned on for the view hierarchy. When hardware 556 acceleration is turned off, hardware layers behave exactly as software layers.</p> 557 <p>A software layer is backed by a bitmap and causes the view to be rendered using Android's 558 software rendering pipeline, even if hardware acceleration is enabled. Software layers should be 559 avoided when the affected view tree updates often. Every update will require to re-render the 560 software layer, which can potentially be slow.</p> 561 <p>For more information, see the {@link android.view.View#LAYER_TYPE_HARDWARE} and {@link 562 android.view.View#LAYER_TYPE_SOFTWARE} documentation.</p> 563 </li> 564 565 566 <li><b>Renderscript 3D graphics engine</b> 567 568 <p>Renderscript is a runtime 3D framework that provides both an API for building 3D scenes as well 569 as a special, platform-independent shader language for maximum performance. Using Renderscript, you 570 can accelerate graphics operations and data processing. Renderscript is an ideal way to create 571 high-performance 3D effects for applications, wallpapers, carousels, and more.</p> 572 <p>For more information, see the <a 573 href="{@docRoot}guide/topics/graphics/renderscript.html">3D Rendering and Computation with 574 Renderscript</a> documentation.</p></li> 575 </ul> 576 577 578 579 580 <h3>Media</h3> 581 582 583 <ul> 584 585 <li><b>Time lapse video</b> 586 587 <p>Camcorder APIs now support the ability to record time lapse video. The {@link 588 android.media.MediaRecorder#setCaptureRate setCaptureRate()} sets the rate at which frames 589 should be captured.</p></li> 590 591 <li><b>Texture support for image streams</b> 592 593 <p>New {@link android.graphics.SurfaceTexture} allows you to capture an image stream as an OpenGL ES 594 texture. By calling {@link android.hardware.Camera#setPreviewTexture setPreviewTexture()} for your 595 {@link android.hardware.Camera} instance, you can specify the {@link 596 android.graphics.SurfaceTexture} upon which to draw video playback or preview frames from the 597 camera.</p></li> 598 599 <li><b>HTTP Live streaming</b> 600 601 <p>Applications can now pass an M3U playlist URL to the media framework to begin an HTTP Live 602 streaming session. The media framework supports most of the HTTP Live streaming specification, 603 including adaptive bit rate. See the <a 604 href="{@docRoot}guide/appendix/media-formats.html">Supported Media Formats</a> document for 605 more information.</p></li> 606 607 <li><b>EXIF data</b> 608 609 <p>The {@link android.media.ExifInterface} includes new fields for photo aperture, ISO, and exposure 610 time.</p></li> 611 612 <li><b>Camcorder profiles</b> 613 614 <p>New {@link android.media.CamcorderProfile#hasProfile hasProfile()} method and several video 615 quality profiles (such as {@link android.media.CamcorderProfile#QUALITY_1080P}, {@link 616 android.media.CamcorderProfile#QUALITY_720P}, {@link 617 android.media.CamcorderProfile#QUALITY_CIF}, and others) allow you to determine camcorder 618 quality options.</p></li> 619 620 <li><b>Digital media file transfer</b> 621 622 <p>The platform includes built-in support for Media/Picture Transfer Protocol (MTP/PTP) over USB, 623 which lets users easily transfer any type of media files between devices and to a host computer. 624 Developers can build on this support, creating applications that let users create or manage rich 625 media files that they may want to transfer or share across devices. </p></li> 626 627 <li><b>Digital rights management (DRM)</b> 628 629 <p>New extensible digital rights management (DRM) framework for checking and enforcing digital 630 rights. It's implemented in two architectural layers:</p> 631 <ul> 632 <li>A DRM framework API, which is exposed to applications and runs through the Dalvik VM for 633 standard applications.</li> 634 <li>A native code DRM manager that implements the framework API and exposes an interface for DRM 635 plug-ins to handle rights management and decryption for various DRM schemes.</li> 636 </ul> 637 638 <p>For application developers, the framework offers an abstract, unified API that simplifies the 639 management of protected content. The API hides the complexity of DRM operations and allows a 640 consistent operation mode for both protected and unprotected content, and across a variety of DRM 641 schemes.</p> 642 643 <p>For device manufacturers, content owners, and Internet digital media providers the DRM 644 framework?s plugin API provides a means of adding support for a DRM scheme of choice into the 645 Android system, for secure enforcement of content protection.</p> 646 647 <p>The preview release does not provide any native DRM plug-ins for checking and enforcing digital 648 rights. However, device manufacturers may ship DRM plug-ins with their devices.</p> 649 650 <p>You can find all of the DRM APIs in the {@link android.drm} package.</p></li> 651 652 </ul> 653 654 655 656 <h3>Keyboard support</h3> 657 658 <ul> 659 <li>Support for Control, Meta, Caps Lock, Num Lock and Scroll Lock modifiers. For more information, 660 see {@link android.view.KeyEvent#META_CTRL_ON} and related fields.</li> 661 662 <li>Support for full desktop-style keyboards, including support for keys such as Escape, Home, End, 663 Delete and others. You can determine whether key events are coming from a full keyboard by 664 querying {@link android.view.KeyCharacterMap#getKeyboardType()} and checking for {@link 665 android.view.KeyCharacterMap#FULL KeyCharacterMap.FULL}</li> 666 667 <li>{@link android.widget.TextView} now supports keyboard-based cut, copy, paste, and select-all, 668 using the key combinations Ctrl+X, Ctrl+C, Ctrl+V, and Ctrl+A. It also supports PageUp/PageDown, 669 Home/End, and keyboard-based text selection.</li> 670 671 <li>{@link android.view.KeyEvent} adds several new methods to make it easier to check the key 672 modifier state correctly and consistently. See {@link android.view.KeyEvent#hasModifiers(int)}, 673 {@link android.view.KeyEvent#hasNoModifiers()}, 674 {@link android.view.KeyEvent#metaStateHasModifiers(int,int) metaStateHasModifiers()}, 675 {@link android.view.KeyEvent#metaStateHasNoModifiers(int) metaStateHasNoModifiers()}.</li> 676 677 <li>Applications can implement custom keyboard shortcuts by subclassing {@link 678 android.app.Activity}, {@link android.app.Dialog}, or {@link android.view.View} and implementing 679 {@link android.app.Activity#onKeyShortcut onKeyShortcut()}. The framework calls this method 680 whenever a key is combined with Ctrl key. When creating an <a 681 href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options Menu</a>, you can register keyboard 682 shortcuts by setting either the {@code android:alphabeticShortcut} or {@code 683 android:numericShortcut} attribute for each <a 684 href="{@docRoot}guide/topics/resources/menu-resource.html#item-element">{@code <item>}</a> 685 element (or with {@link android.view.MenuItem#setShortcut setShortcut()}).</li> 686 687 <li>Android 3.0 includes a new "virtual keyboard" device with the id {@link 688 android.view.KeyCharacterMap#VIRTUAL_KEYBOARD KeyCharacterMap.VIRTUAL_KEYBOARD}. The virtual 689 keyboard has a desktop-style US key map which is useful for synthesizing key events for testing 690 input.</li> 691 692 </ul> 693 694 695 696 697 <h3>Split touch events</h3> 698 699 <p>Previously, only a single view could accept touch events at one time. Android 3.0 700 adds support for splitting touch events across views and even windows, so different views can accept 701 simultaneous touch events.</p> 702 703 <p>Split touch events is enabled by default when an application targets 704 Android 3.0. That is, when the application has set either the <a 705 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> 706 or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code 707 android:targetSdkVersion}</a> attribute's value to {@code "11"}.</p> 708 709 <p>However, the following properties allow you to disable split touch events across views inside 710 specific view groups and across windows.</p> 711 712 <ul> 713 <li>The {@link android.R.attr#splitMotionEvents android:splitMotionEvents} attribute for view groups 714 allows you to disable split touch events that occur between child views in a layout. For example: 715 <pre> 716 <LinearLayout android:splitMotionEvents="false" ... > 717 ... 718 </LinearLayout> 719 </pre> 720 <p>This way, child views in the linear layout cannot split touch events—only one view can 721 receive touch events at a time.</p> 722 </li> 723 724 <li>The {@link android.R.attr#windowEnableSplitTouch android:windowEnableSplitTouch} style property 725 allows you to disable split touch events across windows, by applying it to a theme for the activity 726 or entire application. For example: 727 <pre> 728 <style name="NoSplitMotionEvents" parent="android:Theme.Holo"> 729 <item name="android:windowEnableSplitTouch">false</item> 730 ... 731 </style> 732 </pre> 733 <p>When this theme is applied to an <a 734 href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> or <a 735 href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a>, 736 only touch events within the current activity window are accepted. For example, by disabling split 737 touch events across windows, the system bar cannot receive touch events at the same time as the 738 activity. This does <em>not</em> affect whether views inside the activity can split touch 739 events—by default, the activity can still split touch events across views.</p> 740 741 <p>For more information about creating a theme, read <a 742 href="{@docRoot}guide/topics/ui/themes.html">Applying Styles and Themes</a>.</p> 743 </li> 744 </ul> 745 746 747 748 <h3>WebKit</h3> 749 750 <ul> 751 <li>New {@link android.webkit.WebViewFragment} class to create a fragment composed of a 752 {@link android.webkit.WebView}.</li> 753 <li>New {@link android.webkit.WebSettings} methods: 754 <ul> 755 <li>{@link 756 android.webkit.WebSettings#setDisplayZoomControls setDisplayZoomControls()} allows you to hide 757 the on-screen zoom controls while still allowing the user to zoom with finger gestures ({@link 758 android.webkit.WebSettings#setBuiltInZoomControls setBuiltInZoomControls()} must be set 759 {@code true}).</li> 760 <li>New {@link android.webkit.WebSettings} method, {@link 761 android.webkit.WebSettings#setEnableSmoothTransition setEnableSmoothTransition()}, allows you 762 to enable smooth transitions when panning and zooming. When enabled, WebView will choose a solution 763 to maximize the performance (for example, the WebView's content may not update during the 764 transition).</li> 765 </ul> 766 <li>New {@link android.webkit.WebView} methods: 767 <ul> 768 <li>{@link android.webkit.WebView#onPause onPause()} callback, to pause any processing 769 associated with the WebView when it becomes hidden. This is useful to reduce unnecessary CPU or 770 network traffic when the WebView is not in the foreground.</li> 771 <li>{@link android.webkit.WebView#onResume onResume()} callback, to resume processing 772 associated with the WebView, which was paused during {@link android.webkit.WebView#onPause 773 onPause()}.</li> 774 <li>{@link android.webkit.WebView#saveWebArchive saveWebArchive()} allows you to save the 775 current view as a web archive on the device.</li> 776 <li>{@link android.webkit.WebView#showFindDialog showFindDialog()} initiates a text search in 777 the current view.</li> 778 </ul> 779 </li> 780 </ul> 781 782 783 784 <h3>Browser</h3> 785 786 <p>The Browser application adds the following features to support web applications:</p> 787 788 <ul> 789 <li><b>Media capture</b> 790 <p>As defined by the <a href="http://dev.w3.org/2009/dap/camera/">HTML Media Capture</a> 791 specification, the Browser allows web applications to access audio, image and video capture 792 capabilities of the device. For example, the following HTML provides an input for the user to 793 capture a photo to upload:</p> 794 <pre> 795 <input type="file" accept="image/*;capture=camera" /> 796 </pre> 797 <p>Or by excluding the {@code capture=camera} parameter, the user can choose to either capture a 798 new image with the camera or select one from the device (such as from the Gallery application).</p> 799 </li> 800 801 <li><b>Device Orientation</b> 802 <p>As defined by the <a 803 href="http://dev.w3.org/geo/api/spec-source-orientation.html">Device Orientation Event</a> 804 specification, the Browser allows web applications to listen to DOM events that provide information 805 about the physical orientation and motion of the device.</p> 806 <p>The device orientation is expressed with the x, y, and z axes, in degrees and motion is 807 expressed with acceleration and rotation rate data. A web page can register for orientation 808 events by calling {@code window.addEventListener} with event type {@code "deviceorientation"} 809 and register for motion events by registering the {@code "devicemotion"} event type.</p> 810 </li> 811 812 <li><b>CSS 3D Transforms</b> 813 <p>As defined by the <a href="http://www.w3.org/TR/css3-3d-transforms/">CSS 3D Transform 814 Module</a> specification, the Browser allows elements rendered by CSS to be transformed in three 815 dimensions.</p> 816 </li> 817 </ul> 818 819 820 821 <h3>JSON utilities</h3> 822 823 <p>New classes, {@link android.util.JsonReader} and {@link android.util.JsonWriter}, help you 824 read and write JSON streams. The new APIs complement the {@link org.json} classes, which manipulate 825 a document in memory.</p> 826 827 <p>You can create an instance of {@link android.util.JsonReader} by calling 828 its constructor method and passing the {@link java.io.InputStreamReader} that feeds the JSON string. 829 Then begin reading an object by calling {@link android.util.JsonReader#beginObject()}, read a 830 key name with {@link android.util.JsonReader#nextName()}, read the value using methods 831 respective to the type, such as {@link android.util.JsonReader#nextString()} and {@link 832 android.util.JsonReader#nextInt()}, and continue doing so while {@link 833 android.util.JsonReader#hasNext()} is true.</p> 834 835 <p>You can create an instance of {@link android.util.JsonWriter} by calling its constructor and 836 passing the appropriate {@link java.io.OutputStreamWriter}. Then write the JSON data in a manner 837 similar to the reader, using {@link android.util.JsonWriter#name name()} to add a property name 838 and an appropriate {@link android.util.JsonWriter#value value()} method to add the respective 839 value.</p> 840 841 <p>These classes are strict by default. The {@link android.util.JsonReader#setLenient setLenient()} 842 method in each class configures them to be more liberal in what they accept. This lenient 843 parse mode is also compatible with the {@link org.json}'s default parser.</p> 844 845 846 847 848 <h3>New feature constants</h3> 849 850 <p>The <a 851 href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> 852 manfest element should be used to inform external entities (such as Google Play) of the set of 853 hardware and software features on which your application depends. In this release, Android adds the 854 following new constants that applications can declare with this element:</p> 855 856 <ul> 857 <li>{@link android.content.pm.PackageManager#FEATURE_FAKETOUCH "android.hardware.faketouch"} 858 <p>When declared, this indicates that the application is compatible with a device that offers an 859 emulated touchscreen (or better). A device that offers an emulated touchscreen provides a user input 860 system that can emulate a subset of touchscreen 861 capabilities. An example of such an input system is a mouse or remote control that drives an 862 on-screen cursor. Such input systems support basic touch events like click down, click up, and drag. 863 However, more complicated input types (such as gestures, flings, etc.) may be more difficult or 864 impossible on faketouch devices (and multitouch gestures are definitely not possible).</p> 865 <p>If your application does <em>not</em> require complicated gestures and you do 866 <em>not</em> want your application filtered from devices with an emulated touchscreen, you 867 should declare {@link 868 android.content.pm.PackageManager#FEATURE_FAKETOUCH "android.hardware.faketouch"} with a <a 869 href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> 870 element. This way, your application will be available to the greatest number of device types, 871 including those that provide only an emulated touchscreen input.</p> 872 <p>All devices that include a touchscreen also support {@link 873 android.content.pm.PackageManager#FEATURE_FAKETOUCH "android.hardware.faketouch"}, because 874 touchscreen capabilities are a superset of faketouch capabilities. Thus, unless you actually require 875 a touchscreen, you should add a <a 876 href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> 877 element for faketouch.</p> 878 </li> 879 </ul> 880 881 882 883 884 <h3>New permissions</h3> 885 886 <ul> 887 <li>{@link android.Manifest.permission#BIND_REMOTEVIEWS 888 "android.permission.BIND_REMOTEVIEWS"} 889 <p>This must be declared as a required permission in the <a 890 href="{@docRoot}guide/topics/manifest/service-element.html">{@code <service>}</a> manifest 891 element for an implementation of {@link android.widget.RemoteViewsService}. For example, when 892 creating an App Widget that uses {@link android.widget.RemoteViewsService} to populate a 893 collection view, the manifest entry may look like this:</p> 894 <pre> 895 <service android:name=".widget.WidgetService" 896 android:exported="false" 897 android:permission="android.permission.BIND_REMOTEVIEWS" /> 898 </pre> 899 </ul> 900 901 902 903 <h3>New platform technologies</h3> 904 905 <ul> 906 <li><strong>Storage</strong> 907 <ul> 908 <li>ext4 file system support to enable onboard eMMC storage.</li> 909 <li>FUSE file system to support MTP devices.</li> 910 <li>USB host mode support to support keyboards and USB hubs.</li> 911 <li>Support for MTP/PTP </li> 912 </ul> 913 </li> 914 915 <li><strong>Linux Kernel</strong> 916 <ul> 917 <li>Upgraded to 2.6.36</li> 918 </ul> 919 </li> 920 921 <li><strong>Dalvik VM</strong> 922 <ul> 923 <li>New code to support and optimize for SMP</li> 924 <li>Various improvements to the JIT infrastructure</li> 925 <li>Garbage collector improvements: 926 <ul> 927 <li>Tuned for SMP</li> 928 <li>Support for larger heap sizes</li> 929 <li>Unified handling for bitmaps and byte buffers</li> 930 </ul> 931 </li> 932 </ul> 933 </li> 934 935 <li><strong>Dalvik Core Libraries</strong> 936 <ul> 937 <li>New, much faster implementation of NIO (modern I/O library)</li> 938 <li>Improved exception messages</li> 939 <li>Correctness and performance fixes throughout</li> 940 </ul> 941 </li> 942 </ul> 943 944 945 946 <h3 id="api-diff">API differences report</h3> 947 948 <p>For a detailed view of all API changes in Android {@sdkPlatformVersion} (API Level 949 {@sdkPlatformApiLevel}), see the <a 950 href="{@docRoot}sdk/api_diff/{@sdkPlatformApiLevel}/changes.html">API Differences Report</a>.</p> 951 952 953 954 955 956 <h2 id="api-level">API Level</h2> 957 958 <p>The Android {@sdkPlatformVersion} platform delivers an updated version of 959 the framework API. The Android {@sdkPlatformVersion} API 960 is assigned an integer identifier — 961 <strong>{@sdkPlatformApiLevel}</strong> — that is 962 stored in the system itself. This identifier, called the "API Level", allows the 963 system to correctly determine whether an application is compatible with 964 the system, prior to installing the application. </p> 965 966 <p>To use APIs introduced in Android {@sdkPlatformVersion} in your application, 967 you need compile the application against the Android library that is provided in 968 the Android {@sdkPlatformVersion} SDK platform. Depending on your needs, you might 969 also need to add an <code>android:minSdkVersion="{@sdkPlatformApiLevel}"</code> 970 attribute to the <code><uses-sdk></code> element in the application's 971 manifest. If your application is designed to run only on Android 2.3 and higher, 972 declaring the attribute prevents the application from being installed on earlier 973 versions of the platform.</p> 974 975 <p>For more information, read <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">What is API 976 Level?</a></p> 977
