Home | History | Annotate | Download | only in versions
      1 page.title=Android 4.1 APIs
      2 excludeFromSuggestions=true
      3 sdk.platform.version=4.1
      4 sdk.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
     88 href="{@docRoot}sdk/api_diff/16/changes.html">API
     89 Differences 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})
     99 is a progression of the platform that offers improved
    100 performance and enhanced user experience. It adds new features for users and app
    101 developers. This document provides an introduction to the most notable and
    102 useful 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
    112 href="{@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,
    114 test it, then publish an update with this change.</p>
    115 
    116 <p>You
    117 can use APIs in Android {@sdkPlatformVersion} while also supporting older versions by adding
    118 conditions to your code that check for the system API level before executing
    119 APIs not supported by your <a
    120 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a>. 
    121 To learn more about
    122 maintaining backward-compatibility, read <a
    123 href="{@docRoot}training/backward-compatible-ui/index.html">Creating Backward-Compatible
    124 UIs</a>.</p>
    125 
    126 <p>More information about how API levels work is available in <a
    127 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">What is API
    128 Level?</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
    137 run in the Android emulator and an SDK platform against which you can build your app. You should
    138 download the system image and platform as soon as possible to build and test your
    139 app 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 &lt;service>}</a> tag, your {@link android.app.Service} will run under
    153 its 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 
    159 android.content.ComponentCallbacks2#TRIM_MEMORY_RUNNING_LOW} and {@link 
    160 android.content.ComponentCallbacks2#TRIM_MEMORY_RUNNING_CRITICAL} provide foreground
    161 processes more information about
    162 memory state before the system calls {@link android.app.Activity#onLowMemory()}.</p>
    163 
    164 <p>New {@link android.app.ActivityManager#getMyMemoryState} method allows you to
    165 retrieve 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
    171 acquireUnstableContentProviderClient()}, allows you to access a {@link
    172 android.content.ContentProviderClient} that may be "unstable" such that your app will not crash if
    173 the content provider does. It's useful when you are interacting with content providers in a separate
    174 app.</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 
    182 your 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
    187 that specifies your live wallpaper {@link android.content.ComponentName} as a string in {@link
    188 android.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.
    196 All you need to do is add the <a
    197 href="{@docRoot}guide/topics/manifest/activity-element.html#parent">{@code
    198 android:parentActivityName}</a> to each <a
    199 href="{@docRoot}guide/topics/manifest/activity-element.html">{@code &lt;activity>}</a> element in
    200 your manifest file. The system uses this information to open the appropriate activity when the user
    201 presses the Up button in the action bar (while also finishing the current activity). So if you
    202 declare the <a href="{@docRoot}guide/topics/manifest/activity-element.html#parent">{@code
    203 android:parentActivityName}</a> for each activity, you don't need the {@link
    204 android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method to handle click
    205 events on the action bar's app icon&mdash;the system now handles that event and resumes or
    206 creates the appropriate activity.</p>
    207 
    208 <p>This is particularly powerful for scenarios in which the user enters one of your app's activities
    209 through a "deep dive" intent such as from a notification or an intent from
    210 different app (as described in the design guide for <a 
    211 href="{@docRoot}design/patterns/navigation.html#between-apps">Navigating Between Apps</a>). When
    212 the user enters your activity this way, your app may not naturally have a back stack of
    213 activities that can be resumed as the user navigates up. However, when you supply the <a
    214 href="{@docRoot}guide/topics/manifest/activity-element.html#parent">{@code
    215 android: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
    217 a 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
    227 through
    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
    230 user
    231   navigates back through the stack. For example, if the user is viewing an album
    232 in a music app, navigating up might bring them to an activity that lists all albums in a chosen
    233 music genre. In this case, if the stack must be created, it's necessary that you inform the parent
    234 activity what genre the current album belongs to so that the parent can display the proper list as
    235 if the user actually came from that activity. To deliver such information to a synthetic parent
    236 activity, you must override the {@link
    237 android.app.Activity#onPrepareNavigateUpTaskStack onPrepareNavigateUpTaskStack()} method. This
    238 provides you with a {@link android.app.TaskStackBuilder} object that the system created in order to
    239 synthesize the parent activities. The {@link android.app.TaskStackBuilder} contains {@link
    240 android.content.Intent} objects that the system uses to create each parent activity. In your
    241 implementation of {@link android.app.Activity#onPrepareNavigateUpTaskStack
    242 onPrepareNavigateUpTaskStack()}, you can modify the appropriate {@link android.content.Intent} to
    243 add extra data that the parent activity can use to determine the appropriate context and display
    244 the appropriate UI.</p>
    245 
    246 <p>When the system creates the {@link android.app.TaskStackBuilder}, it adds the {@link
    247 android.content.Intent} objects that are used to create the parent activities in their logical
    248 order beginning from the top of the activity tree. So, the last {@link
    249 android.content.Intent} added to the internal array is the direct parent of the current activity. If
    250 you want to modify the {@link android.content.Intent} for the activity's parent, first determine
    251 the length of the array with {@link android.app.TaskStackBuilder#getIntentCount()} and pass that
    252 value 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
    281 onPrepareNavigateUpTaskStack()}</dd>
    282 </dl>
    283 
    284 <p>However, most apps don't need to use these APIs or implement {@link
    285 android.app.Activity#onPrepareNavigateUpTaskStack
    286 onPrepareNavigateUpTaskStack()}, but can can achieve the correct behavior simply by
    287 adding <a
    288 href="{@docRoot}guide/topics/manifest/activity-element.html#parent">{@code
    289 android:parentActivityName}</a> to each <a
    290 href="{@docRoot}guide/topics/manifest/activity-element.html">{@code &lt;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
    307 and decoding your media. You can instantiate a {@link android.media.MediaCodec} by calling {@link
    308 android.media.MediaCodec#createEncoderByType createEncoderByType()} to encode media or call {@link
    309 android.media.MediaCodec#createDecoderByType createDecoderByType()} to decode media. Each of these
    310 methods 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
    314 android.media.MediaCodec#configure configure()} to specify properties such as the media format or
    315 whether 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
    318 create the {@link android.media.MediaCodec}. First call {@link
    319 android.media.MediaCodec#getInputBuffers()} to get an array of input {@link java.nio.ByteBuffer}
    320 objects and {@link android.media.MediaCodec#getOutputBuffers()} to get an array of output {@link
    321 java.nio.ByteBuffer} objects.</p>
    322 
    323 <p>When you're ready to encode or decode, call {@link android.media.MediaCodec#dequeueInputBuffer
    324 dequeueInputBuffer()} to get the index position of the {@link
    325 java.nio.ByteBuffer} (from the array of input buffers) that you should use to to feed in your source
    326 media. After you fill the {@link java.nio.ByteBuffer} with your source media, release ownership
    327 of 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
    330 dequeueOutputBuffer()} to get the index position of the {@link java.nio.ByteBuffer}
    331 where you'll receive the results. After you read the output from the {@link java.nio.ByteBuffer},
    332 release ownership by calling {@link android.media.MediaCodec#releaseOutputBuffer
    333 releaseOutputBuffer()}.</p>
    334 
    335 <p>You can handle encrypted media data in the codecs by calling {@link
    336 android.media.MediaCodec#queueSecureInputBuffer queueSecureInputBuffer()} in conjunction with
    337   the {@link android.media.MediaCrypto} APIs, instead of the normal {@link
    338 android.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
    347 can acquire an instance of {@link android.media.MediaRouter} by calling {@link
    348 android.content.Context#getSystemService getSystemService(}{@link
    349 android.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
    356 you to begin audio recording based on a cue defined by a {@link android.media.MediaSyncEvent}.
    357 The {@link android.media.MediaSyncEvent} specifies an audio session 
    358 (such as one defined by {@link android.media.MediaPlayer}), which when complete, triggers
    359 the audio recorder to begin recording. For example, you can use this functionality to
    360 play an audio tone that indicates the beginning of a recording session and recording
    361 automatically begins so you don't have to manually synchronize the tone and the beginning
    362 of 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.
    368 In-band text tracks come as a text track within an MP4 or 3GPP media source. Out-of-band text
    369 tracks can be added as an external text source via {@link
    370 android.media.MediaPlayer#addTimedTextSource addTimedTextSource()} method. After all external text
    371 track sources are added, {@link android.media.MediaPlayer#getTrackInfo()} should be called to get
    372 the 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
    375 call {@link android.media.MediaPlayer#selectTrack selectTrack()}, using the index
    376 position 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
    380 it 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
    397 android.media.AudioRecord} using one of the {@link android.media.audiofx.AudioEffect}
    398 subclasses.</p>
    399 
    400 <p class="note"><strong>Note:</strong> It's not guaranteed that all devices support these
    401 effects, so you should always first check availability by calling {@link
    402 android.media.audiofx.AcousticEchoCanceler#isAvailable isAvailable()} on the corresponding
    403 audio 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,
    410 call {@link android.media.MediaPlayer#setNextMediaPlayer setNextMediaPlayer()} and Android
    411 attempts to start the second player the moment that the first one stops.</p>
    412 
    413 
    414 Media router. The new APIs MediaRouter, MediaRouteActionProvider, and MediaRouteButton provide
    415 standard 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
    423 for changes to the auto focus movement. You can register your interface with {@link
    424 android.hardware.Camera#setAutoFocusMoveCallback setAutoFocusMoveCallback()}. Then when the camera
    425 is in a continuous autofocus mode ({@link
    426 android.hardware.Camera.Parameters#FOCUS_MODE_CONTINUOUS_VIDEO} or 
    427 {@link android.hardware.Camera.Parameters#FOCUS_MODE_CONTINUOUS_PICTURE}), you'll receive a call
    428 to {@link android.hardware.Camera.AutoFocusMoveCallback#onAutoFocusMoving onAutoFocusMoving()},
    429 which 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
    434 standard sounds made by the camera or other media actions. You should use these APIs to play
    435 the 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
    439 appropriate 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
    449 to transfer with either the new {@link android.nfc.NfcAdapter#setBeamPushUris setBeamPushUris()}
    450 method or the new callback interface {@link android.nfc.NfcAdapter.CreateBeamUrisCallback}, Android
    451 hands off the data transfer to Bluetooth or another alternate transport to
    452 achieve faster transfer speeds. This is especially useful for large payloads such as image and
    453 audio files and requires no visible pairing between the devices. No additional work is required by
    454 your 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.
    458 Alternatively, you can implement the {@link android.nfc.NfcAdapter.CreateBeamUrisCallback}
    459 interface, which you can specify for your activity by calling {@link
    460 android.nfc.NfcAdapter#setBeamPushUrisCallback setBeamPushUrisCallback()}.</p>
    461 
    462 <p>When using the
    463 callback interface, the system calls the interface's {@link
    464 android.nfc.NfcAdapter.CreateBeamUrisCallback#createBeamUris createBeamUris()} method when the
    465 user executes a share with Android Beam so that you can define the URIs to share at share-time.
    466 This is useful if the URIs to share might vary depending on the user context within the
    467 activity, whereas calling {@link android.nfc.NfcAdapter#setBeamPushUris setBeamPushUris()} is
    468 useful 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
    477 find and connect to services offered by peer devices over Wi-Fi, such as mobile devices,
    478 printers, 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
    481 broadcast your services on the local network, discover local devices on the network, and
    482 connect 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}
    492 and pass it to {@link android.net.nsd.NsdManager#registerService registerService()}
    493 with 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
    501 found, you need to resolve the service by calling 
    502 {@link android.net.nsd.NsdManager#resolveService resolveService()}, passing it an
    503 implementation of {@link android.net.nsd.NsdManager.ResolveListener} that receives
    504 an {@link android.net.nsd.NsdServiceInfo} object that contains information about the
    505 discovered 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
    512 the {@link android.net.wifi.p2p.WifiP2pManager}. This allows you to discover and filter nearby
    513 devices by services using Wi-Fi P2P before connecting to one, while Network Service
    514 Discovery allows you to discover a service on an existing connected network (such as a local Wi-Fi
    515 network).</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
    528 successful callback, you can then begin discovering services on local devices by calling {@link
    529 android.net.wifi.p2p.WifiP2pManager#discoverServices discoverServices()}.</p>
    530 
    531 <p>When local services are discovered, you'll receive a callback to either the {@link
    532 android.net.wifi.p2p.WifiP2pManager.DnsSdServiceResponseListener} or {@link
    533 android.net.wifi.p2p.WifiP2pManager.UpnpServiceResponseListener}, depending on whether you
    534 registered 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
    543 check whether the device is currently connected to a metered network. By checking this state
    544 before performing intensive network transactions, you can help manage the data usage that may cost your users money and make
    545 informed decisions about whether to perform the transactions now or later (such as when the
    546 device 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
    557 allows you to build services that monitor and respond to more input events, such as complex gestures
    558 using {@link android.accessibilityservice.AccessibilityService#onGesture onGesture()} and other
    559 input events through additions to the {@link android.view.accessibility.AccessibilityEvent}, {@link
    560 android.view.accessibility.AccessibilityNodeInfo} and {@link
    561 android.view.accessibility.AccessibilityRecord} classes.</p>
    562 
    563 <p>Accessibility services can also perform actions on behalf of the user, including clicking,
    564 scrolling and stepping through text using {@link
    565 android.view.accessibility.AccessibilityNodeInfo#performAction performAction} and {@link
    566 android.view.accessibility.AccessibilityNodeInfo#setMovementGranularities
    567 setMovementGranularities}. The {@link
    568 android.accessibilityservice.AccessibilityService#performGlobalAction performGlobalAction()} method
    569 also allows services to perform actions such as Back, Home, and open Recent
    570 Apps 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
    576 elements and input widgets using {@link
    577 android.view.accessibility.AccessibilityNodeInfo#findFocus findFocus()} and {@link
    578 android.view.accessibility.AccessibilityNodeInfo#focusSearch focusSearch()}, and set focus
    579 using {@link android.view.accessibility.AccessibilityNodeInfo#setAccessibilityFocused
    580 setAccessibilityFocused()}.</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
    586 surface complex custom views to accessibility services so they can present the information in a
    587 more accessible way. The {@code android.view.accessibility.AccessibilityNodeProvider} allows a user
    588 widget with advanced content, such as a calendar grid, to present a logical semantic structure for
    589 accessibility services that is completely separate from the widgets layout structure. This semantic
    590 structure allows accessibility services to present a more useful interaction model for users who are
    591 visually 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
    600 android.content.Intent} using the {@link android.content.Intent#setClipData setClipData()} method.
    601 This is especially useful when using an intent to transfer multiple {@code content:} URIs to another
    602 application, such as when sharing multiple documents.  The {@code content:} URIs supplied
    603 this way will also respect the intent's flags to offer read or write access, allowing you to grant
    604 access to multiple URIs in an the intent. When starting an {@link
    605 android.content.Intent#ACTION_SEND} or {@link
    606 android.content.Intent#ACTION_SEND_MULTIPLE} intent, the URIs supplied in the intent are now
    607 automatically propagated to the {@link android.content.ClipData} so that the receiver can have
    608 access 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
    614 Android <a
    615 href="{@docRoot}guide/topics/resources/string-resource.html#FormattingAndStyling">styled
    616 strings</a>). You can add HTML styled text to the {@link android.content.ClipData} with {@link
    617 android.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
    634 compute Renderscripts. This lets you enable NEON like operations such as fast vector math operations
    635 on the CPU path that wouldnt 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
    638 deprecated.</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
    647 your own custom animations. To specify the animation you want, use the {@link 
    648 android.app.ActivityOptions} APIs to build a {@link android.os.Bundle} that you can
    649 then pass to any of the
    650 methods that start an activity, such as {@link
    651 android.app.Activity#startActivity(Intent,Bundle) startActivity()}.</p>
    652 
    653 <p>The {@link android.app.ActivityOptions} class includes a different method for each
    654 type 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
    695 specify the style for your large content region, pass {@link 
    696 android.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
    721 the priority with {@link android.app.Notification.Builder#setPriority setPriority()}. You
    722 can pass this one of five different priority levels defined by {@code PRIORITY_*} constants
    723 in the {@link android.app.Notification} class. The default is {@link 
    724 android.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,
    727 such as a new instant message, text message, or impending event reminder. Low priority
    728 notifications 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
    733 elements, such as to dim the appearance of the system bar or make it disappear completely on handsets.
    734 Android 4.1 adds a few more flags that allow you to further control the appearance of system
    735 UI elements and your activity layout in relation to them by calling {@link
    736 android.view.View#setSystemUiVisibility setSystemUiVisibility()}
    737 and 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
    792 condensed 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
    821 android: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
    837 set of input devices current connected and register to be notified when a new device
    838 is added, changed, or removed. This is particularly useful if you're building a game
    839 that supports multiple players and you want to detect how many controllers are connected
    840 and 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
    844 an 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
    846 an {@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,
    849 implement the {@link android.hardware.input.InputManager.InputDeviceListener} interface and
    850 register it with {@link android.hardware.input.InputManager#registerInputDeviceListener
    851 registerInputDeviceListener()}.</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
    856 the vibration of those devices using the existing {@link android.os.Vibrator} APIs simply
    857 by 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
    869 access.  This will be changed in a future release to require that applications explicitly request
    870 read access using this permission.  If your application already requests write access, it will
    871 automatically get read access as well.  There is a new developer option to turn on read access
    872 restriction, for developers to test their applications against how Android will behave in the
    873 future.</dd>
    874   <dt>{@link android.Manifest.permission#READ_USER_DICTIONARY}</dt>
    875     <dd>Allows an application to read the user dictionary. This should only be required by an
    876 IME, 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>{@link 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
    890 to displaying the user interface on a television screen: {@link
    891 android.content.pm.PackageManager#FEATURE_TELEVISION}. To declare that your app requires
    892 a television interface, declare this feature in your manifest file with the <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code &lt;uses-feature>}</a> element:</p>
    893 <pre>
    894 &lt;manifest ... >
    895     &lt;uses-feature android:name="android.hardware.type.television"
    896                   android:required="true" />
    897     ...
    898 &lt;/manifest>
    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