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