diff options
Diffstat (limited to 'docs/html/preview/api-overview.jd')
| -rw-r--r-- | docs/html/preview/api-overview.jd | 907 |
1 files changed, 907 insertions, 0 deletions
diff --git a/docs/html/preview/api-overview.jd b/docs/html/preview/api-overview.jd new file mode 100644 index 0000000..f992bf9 --- /dev/null +++ b/docs/html/preview/api-overview.jd @@ -0,0 +1,907 @@ +page.title=API Overview +excludeFromSuggestions=true +sdk.platform.apiLevel=20 +@jd:body + + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>In this document + <a href="#" onclick="hideNestedItems('#toc44',this);return false;" class="header-toggle"> + <span class="more">show more</span> + <span class="less" style="display:none">show less</span></a></h2> + +<ol id="toc44" class="hide-nested"> + <li><a href="#Behaviors">Important Behavior Changes</a> + <ol> + <li><a href="#ART">New Android Runtime (ART)</a></li> + <li><a href="#BehaviorNotifications">If your app implements notifications...</a></li> + <li><a href="#BehaviorMediaControl">If your app uses RemoteControlClient...</a></li> +<li><a href="#BehaviorGetRecentTasks">If your app uses ActivityManager.getRecentTasks()...</a></li> + </ol> + </li> + <li><a href="#UI">User Interface</a> + <ol> + <li><a href="#MaterialDesign">Material design support</a></li> + <li><a href="#LockscreenNotifications">Lockscreen notifications</a></li> + <li><a href="#NotificationsMetadata">Notifications metadata</a></li> + <li><a href="#Recents">Concurrent documents and activities in the Recents screen</a></li> + <li><a href="#WebView">WebView updates</a></li> + </ol> + </li> + <li><a href="#Graphics">Graphics</a> + <ol> + <li><a href="#OpenGLES-3-1">Support for OpenGL ES 3.1</a></li> + <li><a href="#AndroidExtensionPack">Android Extension Pack</a></li> + </ol> + </li> + <li><a href="#Multimedia">Multimedia</a> + <ol> + <li><a href="#Camera-v2">Camera API for advanced camera capabilities</a></li> + <li><a href="#AudioPlayback">Audio playback</a></li> + <li><a href="#MediaPlaybackControl">Media playback control</a></li> + </ol> + </li> + <li><a href="#Storage">Storage</a> + <ol> + <li><a href="#DirectorySelection">Directory selection</a></li> + </ol> + </li> + <li><a href="#Wireless">Wireless and Connectivity</a> + <ol> + <li><a href="#Multinetwork">Multiple network connections</a></li> + <li><a href="#BluetoothBroadcasting">Bluetooth broadcasting</a></li> + <li><a href="#NFCEnhancements">NFC enhancements</a></li> + </ol> + </li> + <li><a href="#Power">Power Efficiency</a> + <ol> + <li><a href="#JobScheduler">Scheduling Jobs</a></li> + <li><a href="#PowerMeasurementTools">Developer tools for power measurement</a> + </ol> + </li> + <li><a href="#Enterprise">Enterprise</a> + <ol> + <li><a href="#ManagedProvisioning">Managed provisioning</a></li> + <li><a href="#TaskLocking">Task locking</a></li> + </ol> + </li> + <li><a href="#Printing">Printing Framework</a> + <ol> + <li><a href="#PDFRender">Render PDF as bitmap</a></li> + </ol> + </li> + <li><a href="#TestingA11y">Testing & Accessibility</a> + <ol> + <li><a href="#TestingA11yImprovements">Testing and accessibility improvements</a></li> + </ol> + </li> + <li><a href="#IME">IME</a> + <ol> + <li><a href="#Switching">Easier switching between input languages</a></li> + </ol> + </li> + <li><a href="#Manifest">Manifest Declarations</a> + <ol> + <li><a href="#ManifestFeatures">Declarable required features</a></li> + </ol> + </li> +</ol> + +</div> +</div> + +<p>The L Developer Preview gives you an advance look at the upcoming release +for the Android platform, which offers new features for users and app +developers. This document provides an introduction to the most notable APIs.</p> + +<p>The L Developer Preview is intended for <strong>developer early +adopters</strong> and <strong>testers</strong>. If you are interested in +influencing the direction of the Android framework, +<a href="{@docRoot}preview/setup-sdk.html">give the L Developer Preview a +try</a> and send us your feedback!</p> + +<p class="caution"><strong>Caution:</strong> Do not not publish apps +that use the L Developer Preview to the Google Play store.</p> + +<p class="note"><strong>Note:</strong> This document often refers to classes and +methods that do not yet have reference material available on <a +href="{@docRoot}">developer.android.com</a>. These API elements are +formatted in {@code code style} in this document (without hyperlinks). For the +preliminary API documentation for these elements, download the <a +href="{@docRoot}preview/l-developer-preview-reference.zip">preview +reference</a>.</p> + +<h2 id="Behaviors">Important Behavior Changes</h2> + +<p>If you have previously published an app for Android, be aware that your app + might be affected by changes in the upcoming release.</p> + +<h3 id="ART">New Android Runtime (ART)</h3> + +<p>The 4.4 release introduced a new, experimental Android runtime, ART. Under +4.4, ART was optional, and the default runtime remained Dalvik. With the L +Developer Preview, ART is now the default runtime.</p> + +<p>For an overview of ART's new features, see +<a href="https://source.android.com/devices/tech/dalvik/art.html">Introducing +ART</a>. Some of the major new features are:</p> + +<ul> + <li>Ahead-of-Time (AOT) compilation</li> + <li>Improved garbage collection (GC)</li> + <li>Improved debugging support</li> +</ul> + +<p>Most Android apps should just work without change under ART. However, some +techniques that work on Dalvik do not work on ART. For information about the +most important issues, see +<a href="{@docRoot}guide/practices/verifying-apps-art.html">Verifying App +Behavior on the Android Runtime (ART)</a>. Pay particular attention if:</p> + +<ul> + <li>Your app uses Java Native Interface (JNI) to run C/C++ code.</li> + <li>You use development tools that generate non-standard code (such as some + obfuscators).</li> + <li>You use techniques that are incompatible with compacting garbage + collection. (ART does not currently implement compacting GC, but + compacting GC is under development in the Android Open-Source + Project.)</li> +</ul> + +<h3 id="BehaviorNotifications">If your app implements notifications...</h3> + +<p>Notifications are drawn with dark text atop white (or very light) +backgrounds to match the new material design widgets. Make sure that all your +notifications look right with the new color scheme:</p> + +<div class="figure" style="width:320px"> + <img src="images/hun-example.png" + srcset="images/hun-example@2x.png 2x" + alt="" width="320" height="541" id="figure1" /> + <p class="img-caption"> + <strong>Figure 1.</strong> Fullscreen activity showing a heads-up notification + </p> +</div> + +<ul> + + <li>Update or remove assets that involve color.</li> + + <li>The system automatically inverts action icons in notifications. Use + {@code android.app.Notification. Builder.setColor()} to set an accent color + in a circle behind your {@link android.app.Notification#icon} image.</li> + + <li>The system ignores all non-alpha channels in action icons and the main + notification icon. You should assume that these icons are alpha-only.</li> + +</ul> + +<p>If you are currently adding sounds and vibrations to your notifications by +using the {@link android.media.Ringtone}, {@link android.media.MediaPlayer}, +or {@link android.os.Vibrator} classes, remove this code so that +the system can present notifications correctly in Do +not Disturb mode. Instead, use the {@link android.app.Notification.Builder} +methods instead to add sounds and vibration.</p> + +<p>Notifications now appear in a small floating window +(also called a <em>heads-up notification</em>) when the device is active +(that is, the device is unlocked and its screen is on). These notifications +appear similar to the compact form of your notification, except that the +heads-up notification also shows action buttons. Users can act on, or dismiss, +a heads-up notification without leaving the current app.</p> + +<p>Examples of conditions that may trigger heads-up notifications include:</p> + +<ul> + <li>The user's activity is in fullscreen mode (the app uses +{@link android.app.Notification#fullScreenIntent}), or</li> + <li>The notification has high priority and uses ringtones or + vibrations</li> +</ul> + +<p>If your app implements notifications under those scenarios, make sure that +heads-up notifications are presented correctly.</p> + +<h3 id="BehaviorMediaControl">If your app uses RemoteControlClient...</h3> + +<p>Lockscreens in the L Developer Preview do not show transport controls for +your {@link android.media.RemoteControlClient}. Instead, your app can provide +media playback control from the lockscreen through a notification. This +gives your app more control over the presentation of media buttons, while +providing a consistent experience for users across the lockscreen and +unlocked device.</p> + +<p>The L Developer Preview introduces a new +{@code android.app.Notification.MediaStyle} template which is recommended for +this purpose. {@code MediaStyle} converts notification actions that you added +with +{@link android.app.Notification.Builder#addAction(int, java.lang.CharSequence, + android.app.PendingIntent) +Notification.Builder.addAction()} into compact buttons embedded in your app's +media playback notifications.</p> + +<p>If you are using the new +{@code android.media.session.MediaSession} class +(see <a href="#MediaPlaybackControl">Media Playback Control</a> below), attach +your session token with {@code Notification.MediaStyle.setMediaToken()} to +inform the system that this notification controls an ongoing media session.</p> + +<p>Call {@code +Notification.Builder.setVisibility(Notification.VISIBILITY_PUBLIC)} to mark a +notification as safe to show atop any lockscreen (secure or otherwise). For more +information, see <a href="#LockscreenNotifications">Lockscreen Notifications</a>.</p> + +<h3 id="BehaviorGetRecentTasks">If your app uses ActivityManager.getRecentTasks()...</h3> + +<p>With the introduction of the new <em>concurrent documents and activities +tasks</em> feature in the upcoming release (see <a href="#Recents">Concurrent +documents and activities in Recents screen</a> below), +the {@link android.app.ActivityManager#getRecentTasks +ActivityManager.getRecentTasks()} method is now deprecated to improve user +privacy. For backward compatibility, this method still returns a small subset of +its data, including the calling application’s own tasks and possibly some other +non-sensitive tasks (such as Home). If your app is using this method to retrieve +its own tasks, use {@code android.app.ActivityManager.getAppTasks()} instead to +retrieve that information.</p> + +<h2 id="UI">User Interface</h2> + +<h3 id="MaterialDesign">Material design support</h3> + +<p>The upcoming release adds support for Android's new <em>material</em> design +style. You can create apps with material design that are visually dynamic and +have UI element transitions that feel natural to users. This support includes:</p> + +<ul> + + <li>The material theme</li> + <li>View shadows</li> + <li>The {@code RecyclerView} widget</li> + <li>Drawable animation and styling effects</li> + <li>Material design animation and activity transition effects</li> + <li>Animators for view properties based on the state of a view</li> + <li>Customizable UI widgets and app bars with color palettes that you control</li> +</ul> + +<p>To learn more about adding material design functionality to your app, see +<a href="{@docRoot}preview/material/index.html">Material Design</a>.</p> + +<h3 id="LockscreenNotifications">Lockscreen notifications</h3> +<p>Lockscreens in the L Developer Preview have the ability to present +notifications. Users can choose via <em>Settings</em> whether to allow +sensitive notification content to be shown over a secure lockscreen.</p> + +<p>Your app can control the level of detail visible when its notifications are +displayed over the secure lockscreen. To control the visibility level, call +{@code android.app.Notification.Builder.setVisibility()} and specify one of these +values:</p> + +<ul> +<li>{@code VISIBILITY_PRIVATE}. Shows basic information, such as the +notification’s icon, but hides the notification’s full content.</li> +<li>{@code VISIBILITY_PUBLIC}. Shows the notification’s full content.</li> +<li>{@code VISIBILITY_SECRET}. Shows nothing, excluding even the +notification’s icon.</li> +</ul> + +<p>When {@code VISIBILITY_PRIVATE} is set, you can also provide a redacted +version of the notification content that hides personal details. For example, +an SMS app might display a notification that shows "You have 3 new text messages." +but hides the message content and senders. To provide this alternative +notification, first create the replacement notification using +{@link android.app.Notification.Builder}. When you create the private +notification object, attach the replacement notification to it through the +{@code Notification.Builder.setPublicVersion()} method.</p> + +<h3 id="NotificationsMetadata">Notifications metadata</h3> +<p>The L Developer Preview uses metadata associated with your app notifications +to sort the notifications more intelligently. To set the metadata, call the +following methods in {@code android.app.Notification.Builder} when you +construct the notification:</p> + +<ul> +<li>{@code setCategory()}. Depending on the message category, this tells +the system how to handle your app notifications when the device is +in <em>Do not Disturb</em> mode (for example, if your notification represents an +incoming call, instant message, or alarm). +<li>{@code setPriority()}. Notifications with the priority field set to +{@code PRIORITY_MAX} or {@code PRIORITY_HIGH} will appear in a small floating +window if the notification also has sound or vibration.</li> +<li>{@code addPerson()}. Allows you to add a list of people to a notification. +Your app can use this to signal to the system that it should group together +notifications from the specified people, or rank notifications from these +people as being more important.</li> +</ul> + +<h3 id="Recents">Concurrent documents and activities in the Recents screen</h3> + +<p>In previous releases, the +<a href="{@docRoot}design/get-started/ui-overview.html">Recents screen</a> +could only display a single task for each app that the user interacted with +most recently. Now your app can open more tasks as +needed for additional concurrent activities for documents. +This feature facilitates multitasking by letting users quickly switch between +individual activities and documents from the Recents screen, with a consistent +switching experience across all apps. +Examples of such concurrent tasks might include open tabs in a web +browser app, documents in a productivity app, concurrent matches in +a game, or chats in a messaging app. Your app can manage its tasks +through the {@code android.app.ActivityManager.AppTask} class.</p> + +<p>To insert a logical break so that the system treats your activity as a new +task, use {@code android.content.Intent.FLAG_ACTIVITY_NEW_DOCUMENT} when +launching the activity with {@link android.app.Activity#startActivity(android.content.Intent) +startActivity()}. You can also get this behavior by declaring the +<a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a> +attribute {@code documentLaunchMode="intoExisting"} or {@code ="always"} in your +manifest.</p> + +<p>You can also mark that a task should be removed from the Recents screen +when all its activities are closed. To do this, use {@code +android.content.Intent.FLAG_ACTIVITY_AUTO_REMOVE_FROM_RECENTS} when starting the +root activity for +the task. You can also set this behavior for an activity by declaring the +<a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a> +attribute {@code autoRemoveFromRecents=“true”} in your manifest.</p> + +<p>To avoid cluttering the Recents screen, you can set the maximum number of +tasks from your app that can appear in that screen. To do this, set the +<a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a> +attribute {@code android:maxRecent}. The current maximum that can be specified +is 100 tasks per user.</a></p> + +<h3 id="WebView">WebView updates</h3> +<p>The L Developer Preview updates the {@link android.webkit.WebView} +implementation to Chromium M36, bringing security and stability enhancements, +as well as bug fixes. The default user-agent string for a +{@link android.webkit.WebView} running on the L Developer Preview has +been updated to incorporate 36.0.0.0 as the version number.</p> + +<p>Additionally, this release brings support for the +<a href="http://webaudio.github.io/web-audio-api/" class="external-link">WebAudio</a>, +<a href="https://www.khronos.org/webgl/" class="external-link">WebGL</a>, and +<a href="http://www.webrtc.org/" class="external-link">WebRTC</a> open standards. To learn more about +the new features included in this release, see <a href="https://developer.chrome.com/multidevice/webview/overview" class="external-link">WebView for Android</a>.</p> + +<h2 id="Graphics">Graphics</h2> + +<h3 id="OpenGLES-3-1">Support for OpenGL ES 3.1</h3> +<p>The L Developer Preview adds Java interfaces and native support for OpenGL +ES 3.1. Key new functionality provided in OpenGL ES 3.1 includes:</p> + +<ul> +<li>Compute shaders +<li>Separate shader objects +<li>Indirect draw commands +<li>Multisample and stencil textures +<li>Shading language improvements +<li>Extensions for advanced blend modes and debugging +<li>Backward compatibility with OpenGL ES 2.0 and 3.0 +</ul> + +<p>The Java interface for OpenGL ES 3.1 on Android is provided with {@code GLES31}. When +using OpenGL ES 3.1, be sure that you declare it in your manifest file with the +<a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> +tag and the {@code android:glEsVversion} attribute. For example:</p> + +<pre> +<manifest> + <uses-feature android:glEsVersion="0x00030001" /> + ... +</manifest> +</pre> + +<p>For more information about using OpenGL ES, including how to check the +device’s supported OpenGL ES version at runtime, see the +<a href="{@docRoot}guide/topics/graphics/opengl.html">OpenGL ES API guide</a>.</p> + +<h3 id="AndroidExtensionPack">Android Extension Pack</h3> + +<p>In addition to OpenGL ES 3.1, this release provides an extension pack with Java interfaces and +native support for advanced graphics functionality. These extensions are treated as a single +package by Android. (If the {@code ANDROID_extension_pack_es31} extension is present, your app can +assume all extensions in the package are present and enable the shading language features with +a single {@code #extension} statement.</p> +<p>The extension pack supports:</p> +<ul> +<li>Guaranteed fragment shader support for shader storage buffers, images, and + atomics (fragment shader support is optional in OpenGL ES 3.1.)</li> +<li>Tessellation and geometry shaders</li> +<li>ASTC (LDR) texture compression format</li> +<li>Per-sample interpolation and shading</li> +<li>Different blend modes for each color attachment in a frame buffer</li> +</ul> + +<p>The Java interface for the extension pack is provided with {@code GLES31Ext}. +In your app manifest, you can declare that support for the extension pack is +required, with the +<a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> +tag, but the precise syntax is not finalized in the L Developer Preview.</p> + +<h2 id="Multimedia">Multimedia</h2> + +<h3 id="Camera-v2">Camera API for advanced camera capabilities</h3> + +<p>The L Developer Preview introduces the new {@code android.hardware.camera2} +API to facilitate fine-grain photo capture and image processing. You can now +programmatically access the camera devices available to the system with {@code +CameraManager.getCameraIdList()} and connect to a specific device with {@code +CameraManager.openCamera()}. To start capturing images, create a {@code +CameraCaptureSession} and specify the {@link android.view.Surface} objects for +the captured images. The {@code CameraCaptureSession} can be configured to take +single shots or multiple images in a burst.</p> + +<p>To be notified when new images are captured, implement the +{@code CameraCaptureSession.CaptureListener()} interface and set it in your +capture request. Now when the system completes the image capture request, your +{@code CameraCaptureSession.CaptureListener()} receives a call to +{@code onCaptureCompleted()}, providing you with the image capture metadata in a +{@code CaptureResult}.</p> + +<p>To see an example of how to use the updated Camera API, refer to the {@code Camera2Basic} +and {@code Camera2Video} implementation samples in this release.</p> + +<h3 id="AudioPlayback">Audio playback</h3> +<p>This release includes the following changes to + {@link android.media.AudioTrack}:</p> +<ul> + <li>Your app can now supply audio data in floating-point format +({@code android.media.AudioFormat.ENCODING_PCM_FLOAT}). This permits greater +dynamic range, more consistent precision, and greater headroom. Floating-point +arithmetic is especially useful during intermediate calculations. Playback +end-points use integer format for audio data, and with lower bit-depth. (In the +L Developer Preview, portions of the internal pipeline are not yet +floating-point.) + <li>Your app can now supply audio data as a {@link java.nio.ByteBuffer}, in +the same format as provided by {@link android.media.MediaCodec}. + <li>The {@code WRITE_NON_BLOCKING} option can simplify buffering and + multithreading for some apps. +</ul> + +<h3 id="MediaPlaybackControl">Media playback control</h3> +<p>You can now build your own media controller app with the new +{@code android.media.session.MediaController} class, which provides +simplified transport controls APIs that replace those in +{@link android.media.RemoteControlClient}. The {@code MediaController} class +allows thread-safe control of playback from a non-UI process, making it easier +to control your media playback service from your app’s user interface. + +<p>You can also create multiple controllers to send playback commands, +media keys, and other events to the same ongoing +{@code android.media.session.MediaSession}. When you add a controller, you must +call {@code MediaSession.getSessionToken()} to request an access +token in order for your app to interact with the session.</p> + +<p>You can now send transport commands such as "play", "stop", "skip", and +"set rating" by using {@code MediaController.TransportControls}. To handle +in-bound media transport commands from controllers attached to the session, +override the callback methods in +{@code MediaSession.TransportControlsCallback}.</p> + +<p>You can also create rich notifications that allow playback control tied to a +media session with the new {@code android.app.Notification.MediaStyle} class. By +using the new notification and media APIs, you will ensure that the System UI +knows about your playback and can extract and show album art.</p> + +<h2 id="Storage">Storage</h2> + +<h3 id="DirectorySelection">Directory selection</h3> + +<p>The L Developer Preview extends the <a href="{@docRoot}guide/topics/providers/document-provider.html">Storage Access Framework</a> to let users select an entire directory subtree, +giving apps read/write access to all contained documents without requiring user +confirmation for each item.</p> + +<p>To select a directory subtree, build and send an +{@code android.intent.action.OPEN_DOCUMENT_TREE} {@link android.content.Intent}. +The system displays all +{@link android.provider.DocumentsProvider} instances that support subtree selection, +letting the user browse and select a directory. The returned URI represents access to the selected +subtree. You can then use {@code DocumentsContract.buildChildDocumentsUriUsingTree()} +and {@code DocumentsContract.buildDocumentUriUsingTree()} along with +{@code ContentResolver.query()} to explore the subtree.</p> + +<p>The new {@code DocumentsContract.createDocument()} method lets you create +new documents or directories anywhere under the subtree. To manage +existing documents, use {@code DocumentsContract.renameDocument()} and +{@code DocumentsContract.deleteDocument()}. Check {@code DocumentsContract.Document.COLUMN_FLAGS} +to verify provider support for these calls before issuing them.</p> + +<p>If you're implementing a {@link android.provider.DocumentsProvider} and want +to support subtree selection, implement {@code DocumentsProvider.isChildDocument()} +and include {@code Documents.Contract.FLAG_SUPPORTS_IS_CHILD} in your +{@code Root.COLUMN_FLAGS}.</p> + +<p>The L Developer Preview also introduces new package-specific directories on +shared storage where your app can place media files for inclusion in +{@link android.provider.MediaStore}. The new +{@code android.content.Context.getExternalMediaDirs()} returns paths to these +directories on all shared storage devices. Similarly to +{@link android.content.Context#getExternalFilesDir(java.lang.String) Context.getExternalFilesDir()}, +no additional permissions are needed by your app to access the returned paths. The +platform periodically scans for new media in these directories, but you can also +use {@link android.media.MediaScannerConnection} to explicitly scan for new +content.</p> + +<h2 id="Wireless">Wireless & Connectivity</h2> + +<h3 id="Multinetwork">Multiple network connections</h3> +<p>The L Developer Preview provides new multi-networking APIs. These let your app +dynamically scan for available networks with specific capabilities, and +establish a connection to them. This is useful when your app requires a +specialized network, such as an SUPL, MMS, or carrier-billing network, or if +you want to send data using a particular type of transport protocol.</p> + +<p>To select and connect to a network dynamically from your app follow these +steps:</p> + +<ol> + <li>Create a {@link android.net.ConnectivityManager}.</li> + <li>Create a + {@code android.net.NetworkRequest} to specify the network features and transport + type your app is interested in.</li> + <li>To scan for suitable networks, call + {@code ConnectivityManager.requestNetwork()} or + {@code ConnectivityManager.registerNetworkCallback()}, and pass in the + {@code NetworkRequest} object and an implementation of + {@code ConnectivityManager.NetworkCallbackListener}.</li> + +</ol> + +<p>When the system detects a suitable network, it connects to the network and +invokes the {@code NetworkCallbackListener.onAvailable()} callback. You can use +the {@code android.net.Network} object from the callback to get additional +information about the network, or to direct traffic to use the selected +network.</p> + +<h3 id="BluetoothBroadcasting">Bluetooth broadcasting</h3> +<p>Android 4.3 introduced platform support for + <a href="{@docRoot}guide/topics/connectivity/bluetooth-le.html">Bluetooth Low Energy</a> +(BLE) in the central role. In the L Developer Preview, an Android device can now +act as a Bluetooth LE <em>peripheral device</em>. Apps can use this capability +to make their presence known to +nearby devices. For instance, you can build apps that allow a device to +function as a pedometer or health monitor and communicate its data with another +BLE device.</p> + +<p>The new {@code android.bluetooth.le} APIs enable your apps to broadcast +advertisements, scan for responses, and form connections with nearby BLE devices. +You must add the {@code android.permission.BLUETOOTH_ADMIN} permission in your +manifest in order for your app to use the new advertising and scanning features.</a> + +<p>To begin Bluetooth LE advertising so that other devices can discover +your app, call {@code android.bluetooth.le.BluetoothAdvertiser.startAdvisertising()} +and pass in an implementation of the +{@code android.bluetooth.le.AdvertiseCallback} class. The callback object +receives a report of the success or failure of the advertising operation.</p> + +<p> The L Developer Preview introduces the {@code +android.bluetooth.le.ScanFilter} class so that your app can scan for only the +specific types of devices it is interested in. To begin scanning for Bluetooth +LE devices, call {@code android.bluetooth.le.BluetoothLeScanner.startScan()} and +pass in a list of filters. In the method call, you must also provide an +implementation of {@code android.bluetooth.le.ScanCallback} to report if a +Bluetooth LE advertisement is found. </p> + +<h3 id="NFCEnhancements">NFC enhancements</h3> +<p>The L Developer Preview adds these enhancements to enable wider and more +flexible use of NFC:</p> + +<ul> +<li>Android Beam is now available in the share menu. +<li>Your app can invoke the Android Beam on the user’s device to share data by +calling {@code android.nfc.NfcAdapter.invokeBeam()}. This avoids the need for +the user to manually tap the device against another NFC-capable device to +complete the data transfer. +<li>You can use the new {@code android.nfc.NdefRecord.createTextRecord()} method +to create an NDEF record containing UTF-8 text data. +<li>If you are developing a payment app, you now have the ability to +register an NFC application ID (AID) dynamically by calling +{@code android.nfc.cardemulation.CardEmulation.registerAidsForService()}. +You can also use {@code android.nfc.cardemulation.CardEmulation.setPreferredService()} +to set the preferred card emulation service that should be used when a specific +activity is in the foreground. +</ul> + +<h2 id="Power">Power Efficiency</h2> + +<h3 id="JobScheduler">Scheduling jobs</h3> +<p>The L Developer Preview provides a new {@code android.app.job.JobScheduler} +API that lets you optimize battery life by defining jobs for the system to run +asynchronously at a later time or under specified conditions (such as when the +device is charging). This is useful in such situations as:</p> +<ul> + <li>The app has non-user-facing work that you can defer.</li> + <li>The app has work you'd prefer to do when the unit is plugged in.</li> + <li>The app has a task that requires network access (or requires a Wi-Fi + connection).</li> + <li>The app has a number of tasks that you want to run as a batch on a regular + schedule.</li> + +</ul> + +<p>A unit of work is encapsulated by a {@code android.app.job.JobInfo} object. +This object provides an exact description of the criteria to be used for +scheduling.</p> + +<p>Use the {@code android.app.job.JobInfo.Builder} to configure how the +scheduled task should run. You can schedule the task to run under specific +conditions, such as:</p> + +<ul> + <li>The device is charging</li> + <li>The device is connected to an unmetered network</li> + <li>The system deems the device to be idle</li> + <li>Completion with a minimum delay or within a specific deadline.</li> +</ul> + +<p>For example, you can add code like this to run your task on an +unmetered network:</p> + +<pre> +JobInfo uploadTask = new JobInfo.Builder(mJobId, mServiceComponent) + .setRequiredNetworkCapabilities(JobInfo.NetworkType.UNMETERED) + .build(); + +JobScheduler jobScheduler = + (JobScheduler) context.getSystemService(Context.JOB_SCHEDULER_SERVICE) +jobScheduler.schedule(uploadTask); +</pre> + +<p>To see an example of how to use the {@code JobScheduler} API, refer to the +{@code JobSchedulerSample} implementation sample in this release.</p> + +<h3 id="PowerMeasurementTools">Developer tools for power measurement</h3> +<p>The L Developer Preview provides several new developer tools and APIs to help +you better measure and understand your app's power usage.</p> + +<dl> +<dt><strong>batterystats</strong></dt> +<dd> +<p>The {@code dumpsys batterystats} command allows you to generate interesting +statistical data about battery usage on a device, organized by unique user ID +(UID). The statistics generated by the tool include:</p> + +<ul> +<li>History of battery related events +<li>Global statistics for the device +<li>Approximated power use per UID and system component +<li>Per-app mobile ms per packet +<li>System UID aggregated statistics +<li>App UID aggregated statistics +</ul> + +<p>Use the {@code --help} option to learn about the various options for +tailoring the output. For example, to print battery usage +statistics for a given app package since the device was last charged, run this +command: +<pre> +$ adb shell dumpsys batterystats --charged <package-name> +</pre> +</dd> + +<dt><strong>Battery Historian</strong></dt> +<dd> +<p>The Battery Historian tool ({@code historian.par}) analyzes Android +bug reports from the L Developer Preview and creates an HTML visualization of +power-related events. It can +also visualize power consumption data from a power monitor, and attempts to +map power usage to the wake locks seen. You can find the Battery Historian tool +in {@code <sdk>/tools}.</p> + +<img src="images/battery_historian.png" + srcset="images/battery_historian@2x.png 2x" + alt="" width="760" height="462" + id="figure2" /> +<p class="img-caption"> + <strong>Figure 2.</strong>HTML visualization generated by the Battery + Historian tool. +</p> + +<p>For best results, you should first enable full wake lock reporting, to allow +the Battery Historian tool to monitor uninterrupted over an extended period of +time:</p> +<pre> +$ adb shell dumpsys batterystats --enable full-wake-history +</pre> + +<p>You should also reset battery statistics at the beginning of a +measurement:</p> +<pre> +$ adb shell dumpsys batterystats --reset +</pre> + +<p>To generate an HTML visualization:</p> +<pre> +$ historian.par [-p powerfile] bugreport.txt > out.html +</pre> +</dd> + +</dl> + +<h2 id="Enterprise">Enterprise</h2> +<h3 id="ManagedProvisioning">Managed provisioning</h3> + +<div class="figure" style="width:360px"> + <img src="images/managed_apps_launcher.png" + srcset="images/managed_apps_launcher@2x.png 2x" + alt="" width="360" height="609" id="figure3" /> + <p class="img-caption"> + <strong>Figure 3.</strong> Launcher screen showing managed apps (marked with + a lock badge) + </p> +</div> + +<p>The L Developer Preview provides new functionality for running apps within +an enterprise environment. A +<a href="{@docRoot}guide/topics/admin/device-admin.html">device administrator</a> can +initiate a managed provisioning process to add a co-present but separate <em>managed profile</em> to a device, if the user has an existing personal account. +Apps that are associated with managed profiles will appear alongside +non-managed apps in the user’s Launcher, Recent apps screen, and notifications.</p> + +<p>To start the managed provisioning process, send {@code +ACTION_PROVISION_MANAGED_PROFILE} in an {@link android.content.Intent}. If the +call is successful, the system triggers the {@code +android.app.admin.DeviceAdminReceiver. onProfileProvisioningComplete()} callback. +You can then call {@code app.admin.DevicePolicyManager. setProfileEnabled()} to +enable this managed profile.</p> + +<p>If you are developing a Launcher app, you can use the new {@code +android.content.pm.LauncherApps} class to get a list of launchable activities +for the current user and any associated managed profiles. Your Launcher can make +the managed apps visually prominent by appending a “work” badge to the icon +drawable with {@code android.os.UserManager. getBadgeDrawableForUser()}.</p> + +<p>To see an example of how to use the new functionality, refer to the +{@code BasicManagedProfile} implementation sample in this release.</p> + +<h3 id="TaskLocking">Task locking</h3> +<p>The L Developer Preview introduces a new task locking API that +lets you temporarily restrict users from leaving your app or being interrupted +by notifications. This could be used, for example, if you are developing an +education app to support high stakes assessment requirements on Android. +Once your app activates this mode, users will not be able to see +notifications, access other apps, or return to the Home screen, until your +app exits the mode.</p> + +<p>To prevent unauthorized usage, only authorized apps can activate task locking. +Furthermore, task locking authorization must be granted by a +specially-configured <em>device owner</em> app, through the {@code android.app.admin.DevicePolicyManager.setLockTaskComponents()} method.</p> + +<p>To set up a device owner, follow these steps:</p> +<ol> +<li>Attach a device running an Android <a href="https://source.android.com/source/building-running.html" class="external-link">{@code userdebug}</a> build to your development machine.</li> +<li>Install your device owner app.</li> +<li>Create a {@code device_owner.xml} file and save it to the {@code /data/system} +directory on the device. +<pre> +$ adb root +$ adb shell stop +$ rm /tmp/device_owner.xml +$ echo "<?xml version='1.0' encoding='utf-8' standalone='yes' ?>" +>> /tmp/device_owner.xml +$ echo "&device-owner package=\"<your_device_owner_package>\" +name=\"*<your_organization_name>\" />" >> /tmp/device_owner.xml +$ adb push /tmp/device_owner.xml /data/system/device_owner.xml +$ adb reboot +</pre> +</li> +</ol> + +<p>Before using the task locking API in your app, verify that your activity is +authorized by calling {@code DevicePolicyManager.isLockTaskPermitted()}.</p> + +<p>To activate task locking, call +{@code android.app.Activity.startLockTask()} from your authorized activity.</p> + +<p>When task locking is active, the following behavior takes effect:</p> + +<ul> +<li>The status bar is blank, and user notifications and status information is +hidden.</li> +<li>The Home and Recent Apps buttons are hidden.</li> +<li>Other apps may not launch new activities.</li> +<li>The current app may start new activities, as long as doing so does not +create new tasks.</li> +<li>The user remains locked on your app until an authorized activity calls +{@code Activity.stopLockTask()}.</li> +</ul> + +<h2 id="Printing">Printing Framework</h2> + +<h3 id="PDFRender">Render PDF as bitmap</h3> +<p>You can now render PDF document pages into bitmap images for printing by +using the new {@code android.graphics.pdf.PdfRenderer} class. You must specify a +{@link android.os.ParcelFileDescriptor} that is seekable (that is, the content +can be randomly accessed) on which the system writes the the printable content. +Your app can obtain a page for rendering with {@code openPage()}, then call +{@code render()} to turn the opened {@code PdfRenderer.Page} into a bitmap. You +can also set additional parameters if you only want to convert a portion of the +document into a bitmap image (for example, to implement +<a href="http://en.wikipedia.org/wiki/Tiled_rendering" class="external-link">tiled rendering</a> in +order to zoom in on the document).</p> + +<h2 id="TestingA11y">Testing & Accessibility </h2> + +<h3 id="TestingA11yImprovements">Testing and accessibility improvements</h3> +<p>The L Developer Preview adds the following support for testing and +accessibility:</p> + +<ul> +<li>You can use the new {@code android.app.UiAutomation.getWindowAnimationFrameStats()} +and {@code android.app.UiAutomation.getWindowContentFrameStats()} methods to +capture frame statistics for window animations and content. This lets you +write instrumentation tests to evaluate if the app under test is rendering +frames at a sufficient refresh frequency to provide a smooth user experience. + +<li>You can execute shell commands from your instrumentation test with the new +{@code android.app.UiAutomation.executeShellCommand()}. The command execution +is similar to running {@code adb shell} from a host connected to the device. This +allows you to use shell based tools such as {@code dumpsys}, {@code am}, +{@code content}, and {@code pm}. + +<li>Accessibility services and test tools that use the accessibility APIs +(such as <a href="{@docRoot}tools/help/uiautomator/index.html">uiautomator</a>) +can now retrieve detailed information about the properties of windows on the +screen that sighted users can interact with. To retrieve a list of +{@code android.view.accessibility.AccessibilityWindowInfo} objects +representing the windows information, call the new +{@code android.accessibilityservice.AccessibilityService.getWindows()} method. +<li>You can use the new {@code android.view.accessibility.AccessibilityNodeInfo.AccessibilityAction} to define standard or customized +actions to perform on an {@link android.view.accessibility.AccessibilityNodeInfo}. +The new {@code AccessibilityAction} class replaces the actions-related APIs +previously found in {@code AccessibilityNodeInfo}. +</ul> + +<h2 id="IME">IME</h2> + +<h3 id="Switching">Easier switching between input languages</h3> + +<p>Beginning in the L Developer Preview, users can more easily switch between +all <a href="{@docRoot}guide/topics/text/creating-input-method.html">input +method editors (IME)</a> supported by the platform. Performing the designated +switching action (usually touching a Globe icon on the soft keyboard) will cycle +among all such IMEs. This change takes place in +{@link android.view.inputmethod.InputMethodManager#shouldOfferSwitchingToNextInputMethod +InputMethodManager.shouldOfferSwitchingToNextInputMethod()}.</p> + +<p>In addition, the framework now checks whether the next IME includes a +switching mechanism at all (and, thus, whether that IME supports switching to +the IME after it). An +IME with a switching mechanism will not cycle to an IME without one. This +change takes place in +{@link android.view.inputmethod.InputMethodManager#switchToNextInputMethod +InputMethodManager.switchToNextInputMethod}. + +<p>To see an example of how to use the updated IME-switching APIs, refer to the +updated soft-keyboard implementation sample in this release.</p> + +<h2 id="Manifest">Manifest Declarations</h2> + +<h3 id="ManifestFeatures">Declarable required features</h3> +<p>The following values are now supported in the +<a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> +element, so you can ensure that your app is installed only on devices that provide the features +your app needs.</p> + +<ul> +<li>{@code FEATURE_LEANBACK}. Declares that your app must be installed only on +devices that support the +<a href="{@docRoot}training/tv/index.html">Android TV</a> user interface. +Example: +<pre> +<uses-feature android:name="android.software.leanback" + android:required="true" /> +</pre> + +<li>{@code FEATURE_WEBVIEW}. Declares that your app must only be installed on +devices that fully implement the {@code android.webkit.*} APIs. Example: +<pre> +<uses-feature android:name="android.software.webview" + android:required="true" /> +</pre> +</ul> + +<p class="note">For a detailed view of all API changes in the L Developer Preview, see the +<a href="{@docRoot}preview/reference.html">API Differences Report</a>.</p> |