1 page.title=Android 4.1 APIs 2 sdk.platform.version=4.1 3 sdk.platform.apiLevel=16 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="#AppComponents">App Components</a></li> 12 <li><a href="#Multimedia">Multimedia</a></li> 13 <li><a href="#Camera">Camera</a></li> 14 <li><a href="#Connectivity">Connectivity</a></li> 15 <li><a href="#A11y">Accessibility</a></li> 16 <li><a href="#CopyPaste">Copy and Paste</a></li> 17 <li><a href="#Renderscript">Renderscript</a></li> 18 <li><a href="#Animation">Animation</a></li> 19 <li><a href="#UI">User Interface</a></li> 20 <li><a href="#Input">Input Framework</a></li> 21 <li><a href="#Permissions">Permissions</a></li> 22 <li><a href="#DeviceFeatures">Device Features</a></li> 23 </ol> 24 25 <h2>See also</h2> 26 <ol> 27 <li><a 28 href="{@docRoot}sdk/api_diff/16/changes.html">API 29 Differences Report »</a> </li> 30 </ol> 31 32 </div> 33 </div> 34 35 36 <p>API Level: 16</p> 37 38 <p>Android 4.1 (Jelly Bean) is a progression of the platform that offers improved 39 performance and enhanced user experience. It adds new features for users and app 40 developers. This document provides an introduction to the most notable and 41 useful new APIs for app developers.</p> 42 43 44 <div class="sidebox-wrapper"> 45 <div class="sidebox"> 46 47 <h3 id="ApiLevel">Declare your app API Level</h3> 48 49 <p>To better optimize your app for devices running Android {@sdkPlatformVersion}, 50 you should set your <a 51 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to 52 <code>"{@sdkPlatformApiLevel}"</code>, install it on an Android {@sdkPlatformVersion} system image, 53 test it, then publish an update with this change.</p> 54 55 <p>You 56 can use APIs in Android {@sdkPlatformVersion} while also supporting older versions by adding 57 conditions to your code that check for the system API level before executing 58 APIs not supported by your <a 59 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a>. 60 To learn more about 61 maintaining backward-compatibility, read <a 62 href="{@docRoot}training/backward-compatible-ui/index.html">Creating Backward-Compatible 63 UIs</a>.</p> 64 65 <p>More information about how API levels work is available in <a 66 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">What is API 67 Level?</a></p> 68 69 </div> 70 </div> 71 72 73 <p>As an app developer, Android 4.1 is available to you with an SDK platform you can use to build 74 your app against Android 4.1 and with a system image you can run in the Android emulator. You 75 should download download the platform and system image as soon as possible to build and test your 76 app on Android 4.1. To get started developing and testing against Android 77 4.1, use the Android SDK Manager to download the platform into your SDK.</p> 78 79 80 81 82 83 <h2 id="AppComponents">App Components</h2> 84 85 86 87 <h3 id="Isolated">Isolated services</h3> 88 89 <p>By specifying <a href="{@docRoot}guide/topics/manifest/service-element.html#isolated">{@code android:isolatedProcess="true"}</a> in the 90 <a href="{@docRoot}guide/topics/manifest/service-element.html">{@code <service>}</a> tag, your {@link android.app.Service} will run under 91 its own isolated user ID process that has no permissions of its own.</p> 92 93 94 <h3 id="Memory">Memory management</h3> 95 96 <p>New {@link android.content.ComponentCallbacks2} constants such as {@link 97 android.content.ComponentCallbacks2#TRIM_MEMORY_RUNNING_LOW} and {@link 98 android.content.ComponentCallbacks2#TRIM_MEMORY_RUNNING_CRITICAL} provide foreground 99 processes more information about 100 memory state before the system calls {@link android.app.Activity#onLowMemory()}.</p> 101 102 <p>New {@link android.app.ActivityManager#getMyMemoryState} method allows you to 103 retrieve the general memory state.</p> 104 105 106 <h3 id="ContentProvider">Content providers</h3> 107 108 <p>A new method, {@link android.content.ContentResolver#acquireUnstableContentProviderClient 109 acquireUnstableContentProviderClient()}, allows you to access a {@link 110 android.content.ContentProviderClient} that may be "unstable" such that your app will not crash if 111 the content provider does. It's useful when you are interacting with content providers in a separate 112 app.</p> 113 114 115 116 <h3 id="LiveWallpapers">Live Wallpapers</h3> 117 118 <p>New intent protocol to directly launch the live wallpaper preview activity so you can help 119 users easily select your live wallpaper without forcing them to leave 120 your app and navigate through the Home wallpaper picker.</p> 121 122 <p>To launch the live wallpaper picker, call {@link android.content.Context#startActivity 123 startActivity()} with an {@link android.content.Intent} using 124 {@link android.app.WallpaperManager#ACTION_CHANGE_LIVE_WALLPAPER} and an extra 125 that specifies your live wallpaper {@link android.content.ComponentName} as a string in {@link 126 android.app.WallpaperManager#EXTRA_LIVE_WALLPAPER_COMPONENT}.</p> 127 128 129 130 131 <h3 id="StackNav">App stack navigation</h3> 132 133 <p>Android 4.1 makes it much easier to implement the proper design patterns for Up navigation. 134 All you need to do is add the <a 135 href="{@docRoot}guide/topics/manifest/activity-element.html#parent">{@code 136 android:parentActivityName}</a> to each <a 137 href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> element in 138 your manifest file. The system uses this information to open the appropriate activity when the user 139 presses the Up button in the action bar (while also finishing the current activity). So if you 140 declare the <a href="{@docRoot}guide/topics/manifest/activity-element.html#parent">{@code 141 android:parentActivityName}</a> for each activity, you don't need the {@link 142 android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method to handle click 143 events on the action bar's app icon—the system now handles that event and resumes or 144 creates the appropriate activity.</p> 145 146 <p>This is particularly powerful for scenarios in which the user enters one of your app's activities 147 through a "deep dive" intent such as from a notification or an intent from 148 different app (as described in the design guide for <a 149 href="{@docRoot}design/patterns/navigation.html#between-apps">Navigating Between Apps</a>). When 150 the user enters your activity this way, your app may not naturally have a back stack of 151 activities that can be resumed as the user navigates up. However, when you supply the <a 152 href="{@docRoot}guide/topics/manifest/activity-element.html#parent">{@code 153 android:parentActivityName}</a> attribute for your activities, the system recognizes 154 whether or not your app already contains a back stack of parent activities and, if not, constructs 155 a synthetic back stack that contains all parent activities.</p> 156 157 <p class="note"><strong>Note:</strong> When the user enters a deep activity in your app and 158 it creates a new task for your app, the system actually inserts the stack of parent activities 159 into the task. As such, pressing the Back button also navigates back through the stack of parent 160 activities.</p> 161 162 <p>When the system creates a synthetic back stack for your app, it builds a basic {@link 163 android.content.Intent} to create a new instance of each parent activity. So there's no 164 saved state for the parent activities the way you'd expect had the user naturally navigated 165 through 166 each activity. If any of the parent activities normally show a UI that's dependent on 167 the user's context, that context information will be missing and you should deliver it when the 168 user 169 navigates back through the stack. For example, if the user is viewing an album 170 in a music app, navigating up might bring them to an activity that lists all albums in a chosen 171 music genre. In this case, if the stack must be created, it's necessary that you inform the parent 172 activity what genre the current album belongs to so that the parent can display the proper list as 173 if the user actually came from that activity. To deliver such information to a synthetic parent 174 activity, you must override the {@link 175 android.app.Activity#onPrepareNavigateUpTaskStack onPrepareNavigateUpTaskStack()} method. This 176 provides you with a {@link android.app.TaskStackBuilder} object that the system created in order to 177 synthesize the parent activities. The {@link android.app.TaskStackBuilder} contains {@link 178 android.content.Intent} objects that the system uses to create each parent activity. In your 179 implementation of {@link android.app.Activity#onPrepareNavigateUpTaskStack 180 onPrepareNavigateUpTaskStack()}, you can modify the appropriate {@link android.content.Intent} to 181 add extra data that the parent activity can use to determine the appropriate context and display 182 the appropriate UI.</p> 183 184 <p>When the system creates the {@link android.app.TaskStackBuilder}, it adds the {@link 185 android.content.Intent} objects that are used to create the parent activities in their logical 186 order beginning from the top of the activity tree. So, the last {@link 187 android.content.Intent} added to the internal array is the direct parent of the current activity. If 188 you want to modify the {@link android.content.Intent} for the activity's parent, first determine 189 the length of the array with {@link android.app.TaskStackBuilder#getIntentCount()} and pass that 190 value to {@link android.app.TaskStackBuilder#editIntentAt editIntentAt()}.</p> 191 192 <p>If your app structure is more complex, there are several other APIs 193 available that allow you to handle the behavior of Up navigation and 194 fully customize the synthetic back stack. Some of the APIs that give you additional 195 control include:</p> 196 <dl> 197 <dt>{@link android.app.Activity#onNavigateUp}</dt> 198 <dd>Override this to perform a custom action when the user presses the Up button.</dd> 199 <dt>{@link android.app.Activity#navigateUpTo}</dt> 200 <dd>Call this to finish the current activity and go to the activity indicated by the 201 supplied {@link android.content.Intent}. If the activity exists in the back stack, but 202 is not the closest parent, then all other activities between the current activity and the 203 activity specified with the intent are finished as well.</dd> 204 <dt>{@link android.app.Activity#getParentActivityIntent}</dt> 205 <dd>Call this to get the {@link android.content.Intent} that will start the logical 206 parent for the current activity.</dd> 207 <dt>{@link android.app.Activity#shouldUpRecreateTask}</dt> 208 <dd>Call this to query whether a synthetic back stack must be created in order to navigate 209 up. Returns true if a synthetic stack must be created, false if the appropropriate stack 210 already exists.</dd> 211 <dt>{@link android.app.Activity#finishAffinity}</dt> 212 <dd>Call this to finish the current activity and all parent activities with the same 213 task affinity that are chained to the current activity. 214 If you override the default behaviors such as 215 {@link android.app.Activity#onNavigateUp}, you should call this method when you 216 create a synthetic back stack upon Up navigation.</dd> 217 <dt>{@link android.app.Activity#onCreateNavigateUpTaskStack onCreateNavigateUpTaskStack}</dt> 218 <dd>Override this if you need to fully control how the synthetic task stack is created. If you want to simply add some extra data to the intents for your back stack, you should instead override {@link android.app.Activity#onPrepareNavigateUpTaskStack 219 onPrepareNavigateUpTaskStack()}</dd> 220 </dl> 221 222 <p>However, most apps don't need to use these APIs or implement {@link 223 android.app.Activity#onPrepareNavigateUpTaskStack 224 onPrepareNavigateUpTaskStack()}, but can can achieve the correct behavior simply by 225 adding <a 226 href="{@docRoot}guide/topics/manifest/activity-element.html#parent">{@code 227 android:parentActivityName}</a> to each <a 228 href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> element.</p> 229 230 231 232 233 234 235 236 237 238 239 240 <h2 id="Multimedia">Multimedia</h2> 241 242 <h3 id="Codecs">Media codecs</h3> 243 244 <p>The {@link android.media.MediaCodec} class provides access to low-level media codecs for encoding 245 and decoding your media. You can instantiate a {@link android.media.MediaCodec} by calling {@link 246 android.media.MediaCodec#createEncoderByType createEncoderByType()} to encode media or call {@link 247 android.media.MediaCodec#createDecoderByType createDecoderByType()} to decode media. Each of these 248 methods take a MIME type for the type of media you want to encode or decode, such as {@code 249 "video/3gpp"} or {@code "audio/vorbis"}. </p> 250 251 <p>With an instance of {@link android.media.MediaCodec} created, you can then call {@link 252 android.media.MediaCodec#configure configure()} to specify properties such as the media format or 253 whether or not the content is encrypted.</p> 254 255 <p>Whether you're encoding or decoding your media, the rest of the process is the same after you 256 create the {@link android.media.MediaCodec}. First call {@link 257 android.media.MediaCodec#getInputBuffers()} to get an array of input {@link java.nio.ByteBuffer} 258 objects and {@link android.media.MediaCodec#getOutputBuffers()} to get an array of output {@link 259 java.nio.ByteBuffer} objects.</p> 260 261 <p>When you're ready to encode or decode, call {@link android.media.MediaCodec#dequeueInputBuffer 262 dequeueInputBuffer()} to get the index position of the {@link 263 java.nio.ByteBuffer} (from the array of input buffers) that you should use to to feed in your source 264 media. After you fill the {@link java.nio.ByteBuffer} with your source media, release ownership 265 of the buffer by calling {@link android.media.MediaCodec#queueInputBuffer queueInputBuffer()}.</p> 266 267 <p>Likewise for the output buffer, call {@link android.media.MediaCodec#dequeueOutputBuffer 268 dequeueOutputBuffer()} to get the index position of the {@link java.nio.ByteBuffer} 269 where you'll receive the results. After you read the output from the {@link java.nio.ByteBuffer}, 270 release ownership by calling {@link android.media.MediaCodec#releaseOutputBuffer 271 releaseOutputBuffer()}.</p> 272 273 <p>You can handle encrypted media data in the codecs by calling {@link 274 android.media.MediaCodec#queueSecureInputBuffer queueSecureInputBuffer()} in conjunction with 275 the {@link android.media.MediaCrypto} APIs, instead of the normal {@link 276 android.media.MediaCodec#queueInputBuffer queueInputBuffer()}.</p> 277 278 <p>For more information about how to use codecs, see the {@link android.media.MediaCodec} documentation.</p> 279 280 <!-- 281 <h3 id="Routing">Media routing</h3> 282 283 <p>The new {@link android.media.MediaRouter} class allows you to route media channels and 284 streams from the current device to external speakers and other devices. You 285 can acquire an instance of {@link android.media.MediaRouter} by calling {@link 286 android.content.Context#getSystemService getSystemService(}{@link 287 android.content.Context#MEDIA_ROUTER_SERVICE MEDIA_ROUTER_SERVICE)}.</p> 288 --> 289 290 291 <h3 id="AudioCue">Record audio on cue</h3> 292 293 <p>New method {@link android.media.AudioRecord#startRecording startRecording()} allows 294 you to begin audio recording based on a cue defined by a {@link android.media.MediaSyncEvent}. 295 The {@link android.media.MediaSyncEvent} specifies an audio session 296 (such as one defined by {@link android.media.MediaPlayer}), which when complete, triggers 297 the audio recorder to begin recording. For example, you can use this functionality to 298 play an audio tone that indicates the beginning of a recording session and recording 299 automatically begins so you don't have to manually synchronize the tone and the beginning 300 of recording.</p> 301 302 303 <h3 id="TextTracks">Timed text tracks</h3> 304 305 <p>The {@link android.media.MediaPlayer} now handles both in-band and out-of-band text tracks. 306 In-band text tracks come as a text track within an MP4 or 3GPP media source. Out-of-band text 307 tracks can be added as an external text source via {@link 308 android.media.MediaPlayer#addTimedTextSource addTimedTextSource()} method. After all external text 309 track sources are added, {@link android.media.MediaPlayer#getTrackInfo()} should be called to get 310 the refreshed list of all available tracks in a data source.</p> 311 312 <p>To set the track to use with the {@link android.media.MediaPlayer}, you must 313 call {@link android.media.MediaPlayer#selectTrack selectTrack()}, using the index 314 position for the track you want to use.</p> 315 316 <p>To be notified when the text track is ready to play, implement the 317 {@link android.media.MediaPlayer.OnTimedTextListener} interface and pass 318 it to {@link android.media.MediaPlayer#setOnTimedTextListener setOnTimedTextListener()}.</p> 319 320 321 <h3 id="AudioEffects">Audio effects</h3> 322 323 <p>The {@link android.media.audiofx.AudioEffect} class now supports additional audio 324 pre-processing types when capturing audio:</p> 325 <ul> 326 <li>Acoustic Echo Canceler (AEC) with {@link android.media.audiofx.AcousticEchoCanceler} 327 removes the contribution of the signal received from the remote party from the captured audio signal.</li> 328 <li>Automatic Gain Control (AGC) with {@link android.media.audiofx.AutomaticGainControl} 329 automatically normalizes the output of the captured signal.</li> 330 <li>Noise Suppressor (NS) with {@link android.media.audiofx.NoiseSuppressor} 331 removes background noise from the captured signal.</li> 332 </ul> 333 334 <p>You can apply these pre-processor effects on audio captured with an {@link 335 android.media.AudioRecord} using one of the {@link android.media.audiofx.AudioEffect} 336 subclasses.</p> 337 338 <p class="note"><strong>Note:</strong> It's not guaranteed that all devices support these 339 effects, so you should always first check availability by calling {@link 340 android.media.audiofx.AcousticEchoCanceler#isAvailable isAvailable()} on the corresponding 341 audio effect class.</p> 342 343 344 <h3 id="Gapless">Gapless playback</h3> 345 346 <p>You can now perform gapless playback between two separate 347 {@link android.media.MediaPlayer} objects. At any time before your first {@link android.media.MediaPlayer} finishes, 348 call {@link android.media.MediaPlayer#setNextMediaPlayer setNextMediaPlayer()} and Android 349 attempts to start the second player the moment that the first one stops.</p> 350 351 352 Media router. The new APIs MediaRouter, MediaRouteActionProvider, and MediaRouteButton provide 353 standard mechanisms and UI for choosing where to play media. 354 355 356 <h2 id="Camera">Camera</h2> 357 358 <h3 id="AutoFocus">Auto focus movement</h3> 359 360 <p>The new interface {@link android.hardware.Camera.AutoFocusMoveCallback} allows you to listen 361 for changes to the auto focus movement. You can register your interface with {@link 362 android.hardware.Camera#setAutoFocusMoveCallback setAutoFocusMoveCallback()}. Then when the camera 363 is in a continuous autofocus mode ({@link 364 android.hardware.Camera.Parameters#FOCUS_MODE_CONTINUOUS_VIDEO} or 365 {@link android.hardware.Camera.Parameters#FOCUS_MODE_CONTINUOUS_PICTURE}), you'll receive a call 366 to {@link android.hardware.Camera.AutoFocusMoveCallback#onAutoFocusMoving onAutoFocusMoving()}, 367 which tells you whether auto focus has started moving or has stopped moving.</p> 368 369 <h3 id="CameraSounds">Camera sounds</h3> 370 371 <p>The {@link android.media.MediaActionSound} class provides a simple set of APIs to produce 372 standard sounds made by the camera or other media actions. You should use these APIs to play 373 the appropriate sound when building a custom still or video camera.</p> 374 375 <p>To play a sound, simply instantiate a {@link android.media.MediaActionSound} object, call 376 {@link android.media.MediaActionSound#load load()} to pre-load the desired sound, then at the 377 appropriate time, call {@link android.media.MediaActionSound#play play()}.</p> 378 379 380 381 <h2 id="Connectivity">Connectivity</h2> 382 383 384 <h3 id="AndroidBeam">Android Beam</h3> 385 386 <p>Android Beam™ now supports large payload transfers over Bluetooth. When you define the data 387 to transfer with either the new {@link android.nfc.NfcAdapter#setBeamPushUris setBeamPushUris()} 388 method or the new callback interface {@link android.nfc.NfcAdapter.CreateBeamUrisCallback}, Android 389 hands off the data transfer to Bluetooth or another alternate transport to 390 achieve faster transfer speeds. This is especially useful for large payloads such as image and 391 audio files and requires no visible pairing between the devices. No additional work is required by 392 your app to take advantage of transfers over Bluetooth.</p> 393 394 <p>The {@link android.nfc.NfcAdapter#setBeamPushUris setBeamPushUris()} method takes an array of 395 {@link android.net.Uri} objects that specify the data you want to transfer from your app. 396 Alternatively, you can implement the {@link android.nfc.NfcAdapter.CreateBeamUrisCallback} 397 interface, which you can specify for your activity by calling {@link 398 android.nfc.NfcAdapter#setBeamPushUrisCallback setBeamPushUrisCallback()}.</p> 399 400 <p>When using the 401 callback interface, the system calls the interface's {@link 402 android.nfc.NfcAdapter.CreateBeamUrisCallback#createBeamUris createBeamUris()} method when the 403 user executes a share with Android Beam so that you can define the URIs to share at share-time. 404 This is useful if the URIs to share might vary depending on the user context within the 405 activity, whereas calling {@link android.nfc.NfcAdapter#setBeamPushUris setBeamPushUris()} is 406 useful when the URIs to share are unchanging and you can safely define them ahead of time.</p> 407 408 409 410 411 412 <h3 id="LocalNsd">Network service discovery</h3> 413 414 <p>Android 4.1 adds support for multicast DNS-based service discovery, which allows you to 415 find and connect to services offered by peer devices over Wi-Fi, such as mobile devices, 416 printers, cameras, media players, and others that are registered on the local network.</p> 417 418 <p>The new package {@link android.net.nsd} contains the new APIs that allow you to 419 broadcast your services on the local network, discover local devices on the network, and 420 connect to devices.</p> 421 422 <p>To register your service, you must first create an {@link android.net.nsd.NsdServiceInfo} 423 object and define the various properties of your service with methods such as 424 {@link android.net.nsd.NsdServiceInfo#setServiceName setServiceName()}, 425 {@link android.net.nsd.NsdServiceInfo#setServiceType setServiceType()}, and 426 {@link android.net.nsd.NsdServiceInfo#setPort setPort()}. 427 </p> 428 429 <p>Then you need to implement {@link android.net.nsd.NsdManager.RegistrationListener} 430 and pass it to {@link android.net.nsd.NsdManager#registerService registerService()} 431 with your {@link android.net.nsd.NsdServiceInfo}.</p> 432 433 <p>To discover services on the network, implement {@link 434 android.net.nsd.NsdManager.DiscoveryListener} and pass it to {@link 435 android.net.nsd.NsdManager#discoverServices discoverServices()}.</p> 436 437 <p>When your {@link 438 android.net.nsd.NsdManager.DiscoveryListener} receives callbacks about services 439 found, you need to resolve the service by calling 440 {@link android.net.nsd.NsdManager#resolveService resolveService()}, passing it an 441 implementation of {@link android.net.nsd.NsdManager.ResolveListener} that receives 442 an {@link android.net.nsd.NsdServiceInfo} object that contains information about the 443 discovered service, allowing you to initiate the connection.</p> 444 445 446 447 <h3 id="WiFiNsd">Wi-Fi Direct service discovery</h3> 448 449 <p>The Wi-Fi Direct APIs are enhanced in Android 4.1 to support pre-association service discovery in 450 the {@link android.net.wifi.p2p.WifiP2pManager}. This allows you to discover and filter nearby 451 devices by services using Wi-Fi Direct before connecting to one, while Network Service 452 Discovery allows you to discover a service on an existing connected network (such as a local Wi-Fi 453 network).</p> 454 455 <p>To broadcast your app as a service over Wi-Fi so that other devices can discover 456 your app and connect to it, call {@link 457 android.net.wifi.p2p.WifiP2pManager#addLocalService addLocalService()} with a 458 {@link android.net.wifi.p2p.nsd.WifiP2pServiceInfo} object that describes your app services.</p> 459 460 <p>To initiate discover of nearby devices over Wi-Fi, you need to first decide whether you'll 461 communicate using Bonjour or Upnp. To use Bonjour, first set up some callback listeners with 462 {@link android.net.wifi.p2p.WifiP2pManager#setDnsSdResponseListeners setDnsSdResponseListeners()}, which takes both a {@link android.net.wifi.p2p.WifiP2pManager.DnsSdServiceResponseListener} and {@link android.net.wifi.p2p.WifiP2pManager.DnsSdTxtRecordListener}. To use Upnp, call 463 {@link android.net.wifi.p2p.WifiP2pManager#setUpnpServiceResponseListener setUpnpServiceResponseListener()}, which takes a {@link android.net.wifi.p2p.WifiP2pManager.UpnpServiceResponseListener}.</p> 464 465 <p>Before you can start discovering services on local devices, you also need to call {@link android.net.wifi.p2p.WifiP2pManager#addServiceRequest addServiceRequest()}. When the {@link android.net.wifi.p2p.WifiP2pManager.ActionListener} you pass to this method receives a 466 successful callback, you can then begin discovering services on local devices by calling {@link 467 android.net.wifi.p2p.WifiP2pManager#discoverServices discoverServices()}.</p> 468 469 <p>When local services are discovered, you'll receive a callback to either the {@link 470 android.net.wifi.p2p.WifiP2pManager.DnsSdServiceResponseListener} or {@link 471 android.net.wifi.p2p.WifiP2pManager.UpnpServiceResponseListener}, depending on whether you 472 registered to use Bonjour or Upnp. The callback received in either case contains a 473 {@link android.net.wifi.p2p.WifiP2pDevice} object representing the peer device.</p> 474 475 476 477 478 <h3 id="NetworkUsage">Network usage</h3> 479 480 <p>The new method {@link android.net.ConnectivityManager#isActiveNetworkMetered} allows you to 481 check whether the device is currently connected to a metered network. By checking this state 482 before performing intensive network transactions, you can help manage the data usage that may cost your users money and make 483 informed decisions about whether to perform the transactions now or later (such as when the 484 device becomes connected to Wi-Fi).</p> 485 486 487 488 489 490 <h2 id="A11y">Accessibility</h2> 491 492 <h3 id="">Accessibility service APIs</h3> 493 494 <p>The reach of accessibility service APIs has been significantly increased in Android 4.1. It now 495 allows you to build services that monitor and respond to more input events, such as complex gestures 496 using {@link android.accessibilityservice.AccessibilityService#onGesture onGesture()} and other 497 input events through additions to the {@link android.view.accessibility.AccessibilityEvent}, {@link 498 android.view.accessibility.AccessibilityNodeInfo} and {@link 499 android.view.accessibility.AccessibilityRecord} classes.</p> 500 501 <p>Accessibility services can also perform actions on behalf of the user, including clicking, 502 scrolling and stepping through text using {@link 503 android.view.accessibility.AccessibilityNodeInfo#performAction performAction} and {@link 504 android.view.accessibility.AccessibilityNodeInfo#setMovementGranularities 505 setMovementGranularities}. The {@link 506 android.accessibilityservice.AccessibilityService#performGlobalAction performGlobalAction()} method 507 also allows services to perform actions such as Back, Home, and open Recent 508 Apps and Notifications.</p> 509 510 511 <h3 id="A11yCustomNav">Customizable app navigation</h3> 512 513 <p>When building an Android app, you can now customize navigation schemes by finding focusable 514 elements and input widgets using {@link 515 android.view.accessibility.AccessibilityNodeInfo#findFocus findFocus()} and {@link 516 android.view.accessibility.AccessibilityNodeInfo#focusSearch focusSearch()}, and set focus 517 using {@link android.view.accessibility.AccessibilityNodeInfo#setAccessibilityFocused 518 setAccessibilityFocused()}.</p> 519 520 521 <h3 id="A11yStructure">More accessible widgets</h3> 522 523 <p>The new {@code android.view.accessibility.AccessibilityNodeProvider} class allows you to 524 surface complex custom views to accessibility services so they can present the information in a 525 more accessible way. The {@code android.view.accessibility.AccessibilityNodeProvider} allows a user 526 widget with advanced content, such as a calendar grid, to present a logical semantic structure for 527 accessibility services that is completely separate from the widgets layout structure. This semantic 528 structure allows accessibility services to present a more useful interaction model for users who are 529 visually impaired.</p> 530 531 532 533 <h2 id="CopyPaste">Copy and Paste</h2> 534 535 <h3 id="CopyIntent">Copy and paste with intents</h3> 536 537 <p>You can now associate a {@link android.content.ClipData} object with an {@link 538 android.content.Intent} using the {@link android.content.Intent#setClipData setClipData()} method. 539 This is especially useful when using an intent to transfer multiple {@code content:} URIs to another 540 application, such as when sharing multiple documents. The {@code content:} URIs supplied 541 this way will also respect the intent's flags to offer read or write access, allowing you to grant 542 access to multiple URIs in an the intent. When starting an {@link 543 android.content.Intent#ACTION_SEND} or {@link 544 android.content.Intent#ACTION_SEND_MULTIPLE} intent, the URIs supplied in the intent are now 545 automatically propagated to the {@link android.content.ClipData} so that the receiver can have 546 access granted to them.</p> 547 548 549 <h5>Support for HTML and string styles</h5> 550 551 <p>The {@link android.content.ClipData} class now supports styled text (either as HTML or 552 Android <a 553 href="{@docRoot}guide/topics/resources/string-resource.html#FormattingAndStyling">styled 554 strings</a>). You can add HTML styled text to the {@link android.content.ClipData} with {@link 555 android.content.ClipData#newHtmlText newHtmlText()}.</p> 556 557 558 559 <h2 id="Renderscript">Renderscript</h2> 560 561 <p>Renderscript computation functionality has been enhanced with the following features:</p> 562 <ul> 563 <li>Support for multiple kernels within one script.</li> 564 <li>Support for reading from allocation with filtered samplers from compute in a new script API 565 {@code rsSample}.</li> 566 <li>Support for different levels of FP precision in {@code #pragma}.</li> 567 <li>Support for querying additional information from RS objects from a compute script.</li> 568 <li>Numerous performance improvements.</li> 569 </ul> 570 571 <p>New pragmas are also available to define the floating point precision required by your 572 compute Renderscripts. This lets you enable NEON like operations such as fast vector math operations 573 on the CPU path that wouldnt otherwise be possible with full IEEE 754-2008 standard.</p> 574 575 <p class="note"><strong>Note:</strong> The experimental Renderscript graphics engine is now 576 deprecated.</p> 577 578 579 580 <h2 id="Animation">Animation</h2> 581 582 <h3 id="ActivityOptions">Activity launch animations</h3> 583 584 <p>You can now launch an {@link android.app.Activity} using zoom animations or 585 your own custom animations. To specify the animation you want, use the {@link 586 android.app.ActivityOptions} APIs to build a {@link android.os.Bundle} that you can 587 then pass to any of the 588 methods that start an activity, such as {@link 589 android.app.Activity#startActivity(Intent,Bundle) startActivity()}.</p> 590 591 <p>The {@link android.app.ActivityOptions} class includes a different method for each 592 type of animation you may want to show as your activity opens:</p> 593 <dl> 594 <dt>{@link android.app.ActivityOptions#makeScaleUpAnimation makeScaleUpAnimation()}</dt> 595 <dd>Creates an animation that scales up the activity window from a specified starting 596 position on the screen and a specified starting size. For example, the home screen in 597 Android 4.1 uses this when opening an app.</dd> 598 <dt>{@link android.app.ActivityOptions#makeThumbnailScaleUpAnimation 599 makeThumbnailScaleUpAnimation()}</dt> 600 <dd>Creates an animation that scales up the activity window starting from a specified 601 position and a provided thumbnail image. For example, the Recent Apps window in 602 Android 4.1 uses this when returning to an app.</dd> 603 <dt>{@link android.app.ActivityOptions#makeCustomAnimation 604 makeCustomAnimation()}</dt> 605 <dd>Creates an animation defined by your own resources: one that defines the animation for 606 the activity opening and another for the activity being stopped.</dd> 607 </dl> 608 609 610 611 <h3 id="TimeAnimator">Time animator</h3> 612 613 <p>The new {@link android.animation.TimeAnimator} provides a simple callback 614 mechanism with the {@link android.animation.TimeAnimator.TimeListener} that notifies 615 you upon every frame of the animation. There is no duration, interpolation, or object value-setting with this Animator. The listener's callback receives information for each frame including 616 total elapsed time and the elapsed time since the previous animation frame.</p> 617 618 619 620 621 <h2 id="UI">User Interface</h2> 622 623 624 <h3 id="Notifications">Notifications</h3> 625 626 <p>In Android 4.1, you can create notifications with larger content regions, big image previews, 627 multiple action buttons, and configurable priority.</p> 628 629 <h5>Notification styles</h5> 630 631 <p>The new method {@link android.app.Notification.Builder#setStyle setStyle()} allows you to specify 632 one of three new styles for your notification that each offer a larger content region. To 633 specify the style for your large content region, pass {@link 634 android.app.Notification.Builder#setStyle setStyle()} one of the following objects:</p> 635 <dl> 636 <dt>{@link android.app.Notification.BigPictureStyle}</dt> 637 <dd>For notifications that includes a large image attachment.</dd> 638 <dt>{@link android.app.Notification.BigTextStyle}</dt> 639 <dd>For notifications that includes a lot of text, such as a single email.</dd> 640 <dt>{@link android.app.Notification.InboxStyle}</dt> 641 <dd>For notifications that include a list of strings, such as snippets from multiple emails.</dd> 642 </dl> 643 644 <h5>Notification actions</h5> 645 646 <p>There's now support for up to two action buttons that appear at the bottom of the 647 notification message, whether your notification uses the normal or larger style.</p> 648 649 <p>To add an action button, call {@link android.app.Notification.Builder#addAction 650 addAction()}. This method takes three arguments: a drawable resource for an icon, 651 text for the button, and a {@link android.app.PendingIntent} that defines the action 652 to perfrom.</p> 653 654 655 <h5>Priorities</h5> 656 657 <p>You can now hint to the system how important your notification is to affect the 658 order of your notification in the list by setting 659 the priority with {@link android.app.Notification.Builder#setPriority setPriority()}. You 660 can pass this one of five different priority levels defined by {@code PRIORITY_*} constants 661 in the {@link android.app.Notification} class. The default is {@link 662 android.app.Notification#PRIORITY_DEFAULT}, and there's two levels higher and two levels lower.</p> 663 664 <p>High priority notifications are things that users generally want to respond to quickly, 665 such as a new instant message, text message, or impending event reminder. Low priority 666 notifications are things like expired calendar events or app promotions.</p> 667 668 <h3 id="SystemUI">Controls for system UI</h3> 669 670 <p>Android 4.0 (Ice Cream Sandwich) added new flags to control the visibility of the system UI 671 elements, such as to dim the appearance of the system bar or make it disappear completely on handsets. 672 Android 4.1 adds a few more flags that allow you to further control the appearance of system 673 UI elements and your activity layout in relation to them by calling {@link 674 android.view.View#setSystemUiVisibility setSystemUiVisibility()} 675 and passing the following flags:</p> 676 677 <dl> 678 <dt>{@link android.view.View#SYSTEM_UI_FLAG_FULLSCREEN}</dt> 679 <dd>Hides non-critical system UI (such as the status bar). 680 If your activity uses the action bar in overlay mode (by 681 enabling <a href="{@docRoot}reference/android/R.attr.html#windowActionBarOverlay">{@code 682 android:windowActionBarOverlay}</a>), then this flag also hides the action bar and does 683 so with a coordinated animation when both hiding and showing the two.</dd> 684 685 <dt>{@link android.view.View#SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN}</dt> 686 <dd>Sets your activity layout to use the same screen area that's available when you've 687 enabled {@link android.view.View#SYSTEM_UI_FLAG_FULLSCREEN} even if the system UI elements 688 are still visible. Although parts of your layout will be overlayed by the 689 system UI, this is useful if your app often hides and shows the system UI with 690 {@link android.view.View#SYSTEM_UI_FLAG_FULLSCREEN}, because it avoids your layout from 691 adjusting to the new layout bounds each time the system UI hides or appears.</dd> 692 693 <dt>{@link android.view.View#SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION}</dt> 694 <dd>Sets your activity layout to use the same screen area that's available when you've 695 enabled {@link android.view.View#SYSTEM_UI_FLAG_HIDE_NAVIGATION} (added in Android 4.0) 696 even if the system UI elements are still visible. Although parts of your layout will be 697 overlayed by the 698 navigation bar, this is useful if your app often hides and shows the navigation bar 699 with {@link android.view.View#SYSTEM_UI_FLAG_HIDE_NAVIGATION}, because it avoids your layout from 700 adjusting to the new layout bounds each time the navigation bar hides or appears.</dd> 701 702 <dt>{@link android.view.View#SYSTEM_UI_FLAG_LAYOUT_STABLE}</dt> 703 <dd>You might want to add this flag if you're using {@link 704 android.view.View#SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN} and/or {@link 705 android.view.View#SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION} to ensure that when you call 706 {@link android.view.View#fitSystemWindows fitSystemWindows()} on a view that the 707 bounds defined remain consistent with regard to the available screen space. 708 That is, with this flag set, {@link android.view.View#fitSystemWindows 709 fitSystemWindows()} will behave as if the visibility of system UI elements is unchanged 710 even after you hide all system UI.</dd> 711 <dd></dd> 712 </dl> 713 714 <p>For more discussion about the other related system UI flags, read about 715 those added in <a href="{@docRoot}about/versions/android-4.0.html#SystemUI">Android 4.0</a>.</p> 716 717 718 <h3 id="RemoteViews">Remote views</h3> 719 720 <p>{@link android.widget.GridLayout} and {@link android.view.ViewStub} 721 are now remotable views so you can use them in layouts for your 722 app widgets and notification custom layouts.</p> 723 724 725 726 <h3 id="Fonts">Font families</h3> 727 728 <p>Android 4.1 adds several more variants of the Roboto font style for a total of 10 variants, 729 and they're all usable by apps. Your apps now have access to the full set of both light and 730 condensed variants.</p> 731 732 <p>The complete set of Roboto font variants available is:</p> 733 734 <ul> 735 <li>Regular</li> 736 <li>Italic</li> 737 <li>Bold</li> 738 <li>Bold-italic</li> 739 <li>Light</li> 740 <li>Light-italic</li> 741 <li>Condensed regular</li> 742 <li>Condensed italic</li> 743 <li>Condensed bold</li> 744 <li>Condensed bold-italic</li> 745 </ul> 746 747 <p>You can apply any one of these with the new {@link android.R.attr#fontFamily} 748 attribute in combination with the {@link android.R.attr#textStyle} attribute.</p> 749 750 <p>Supported values for {@link android.R.attr#fontFamily} are:</p> 751 <ul> 752 <li>{@code "sans-serif"} for regular Roboto</li> 753 <li>{@code "sans-serif-light"} for Roboto Light</li> 754 <li>{@code "sans-serif-condensed"} for Roboto Condensed</li> 755 </ul> 756 757 <p>You can then apply bold and/or italic with {@link android.R.attr#textStyle} values 758 {@code "bold"} and {@code "italic"}. You can apply both like so: {@code 759 android:textStyle="bold|italic"}.</p> 760 761 <p>You can also use {@link android.graphics.Typeface#create Typeface.create()}. 762 For example, {@code Typeface.create("sans-serif-light", Typeface.NORMAL)}.</p> 763 764 765 766 767 768 769 <h2 id="Input">Input Framework</h2> 770 771 772 <h3 id="InputDevice">Multiple input devices</h3> 773 774 <p>The new {@link android.hardware.input.InputManager} class allows you to query the 775 set of input devices current connected and register to be notified when a new device 776 is added, changed, or removed. This is particularly useful if you're building a game 777 that supports multiple players and you want to detect how many controllers are connected 778 and when there are changes to the number of controllers.</p> 779 780 <p>You can query all input devices connected by calling 781 {@link android.hardware.input.InputManager#getInputDeviceIds()}. This returns 782 an array of integers, each of which is an ID for a different input device. You can then call 783 {@link android.hardware.input.InputManager#getInputDevice getInputDevice()} to acquire 784 an {@link android.view.InputDevice} for a specified input device ID.</p> 785 786 <p>If you want to be informed when new input devices are connected, changed, or disconnected, 787 implement the {@link android.hardware.input.InputManager.InputDeviceListener} interface and 788 register it with {@link android.hardware.input.InputManager#registerInputDeviceListener 789 registerInputDeviceListener()}.</p> 790 791 <h3 id="Vibrate">Vibrate for input controllers</h3> 792 793 <p>If connected input devices have their own vibrate capabilities, you can now control 794 the vibration of those devices using the existing {@link android.os.Vibrator} APIs simply 795 by calling {@link android.view.InputDevice#getVibrator()} on the {@link android.view.InputDevice}.</p> 796 797 798 799 <h2 id="Permissions">Permissions</h2> 800 801 <p>The following are new permissions:</p> 802 803 <dl> 804 <dt>{@link android.Manifest.permission#READ_EXTERNAL_STORAGE}</dt> 805 <dd>Provides protected read access to external storage. In Android 4.1 by 806 default all applications still have read 807 access. This will be changed in a future release to require that applications explicitly request 808 read access using this permission. If your application already requests write access, it will 809 automatically get read access as well. There is a new developer option to turn on read access 810 restriction, for developers to test their applications against how Android will behave in the 811 future.</dd> 812 <dt>{@link android.Manifest.permission#READ_USER_DICTIONARY}</dt> 813 <dd>Allows an application to read the user dictionary. This should only be required by an 814 IME, or a dictionary editor like the Settings app.</dd> 815 <dt>{@link android.Manifest.permission#READ_CALL_LOG}</dt> 816 <dd>Allows an application to read the system's call log that contains information about 817 incoming and outgoing calls.</dd> 818 <dt>{@link android.Manifest.permission#WRITE_CALL_LOG}</dt> 819 <dd>Allows an application to modify the system's call log stored on your phone</dd> 820 <dt>{@link android.Manifest.permission#WRITE_USER_DICTIONARY}</dt> 821 <dd>Allows an application to write to the user's word dictionary.</dd> 822 </dl> 823 824 825 <h2 id="DeviceFeatures">Device Features</h2> 826 827 <p>Android 4.1 includes a new feature declaration for devices that are dedicated 828 to displaying the user interface on a television screen: {@link 829 android.content.pm.PackageManager#FEATURE_TELEVISION}. To declare that your app requires 830 a television interface, declare this feature in your manifest file with the <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> element:</p> 831 <pre> 832 <manifest ... > 833 <uses-feature android:name="android.hardware.type.television" 834 android:required="true" /> 835 ... 836 </manifest> 837 </pre> 838 839 <p>This feature defines "television" to be a typical living room television experience: 840 displayed on a big screen, where the user is sitting far away and the dominant form of 841 input is be something like a d-pad, and generally not through touch or a 842 mouse/pointer-device.</p> 843 844 845 846 847 848 849 850 851
