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