am 11b319c2: Merge "docs: Updated L Preview Highlights." into klp-modular-dev

  <li><a href="#Enterprise">Enterprise</a>

    <ol>

      <li><a href="#ManagedProvisioning">Managed provisioning</a></li>

      <li><a href="#LockToAppMode">Lock-to-App mode</a></li>

      <li><a href="#TaskLocking">Task locking</a></li>

    </ol>

  </li>

  <li><a href="#Printing">Printing Framework</a>

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:220px">

<div class="figure" style="width:320px">

  <img src="images/hun-example.png"

    srcset="images/hun-example@2x.png 2x"

    alt="" width="220" height="372" id="figure1" />

    alt="" width="320" height="541" id="figure1" />

  <p class="img-caption">

    <strong>Figure 1.</strong> Fullscreen activity showing a heads-up notification

  </p>

<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 <a href="#DoNotDisturb">Do Not Disturb</a> mode. Instead, use the {@link android.app.Notification.Builder} methods instead to add sounds and vibration.</p>

the system can present notifications correctly in <a href="#DoNotDisturb">Do

Not Disturb</a> 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

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>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>

{@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>

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),

<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>

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>

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>

<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>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

<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>

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="DoNotDisturb">Do Not Disturb mode</h3>

<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

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">&lt;activity&gt;</a>

attribute {@code documentLaunchMode="intoExisting"} or {@code ="always"} in your

manifest.</p>

been updated to incorporate 36.0.0.0 as the version number.</p>

<p>Additionally, this release brings support for the

<a href="https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html">WebAudio</a>, <a href="https://www.khronos.org/webgl/">WebGL</a>, and

<a href="https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html">WebAudio</a>,

<a href="https://www.khronos.org/webgl/">WebGL</a>, and

<a href="http://www.webrtc.org/">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">WebView for Android</a>.</p>

<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 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 &lt;uses-feature&gt;}</a> tag and the {@code android:glEsVversion} attribute. For example:</p>

<p>The Java interface for OpenGL ES 3.1 on Android is provided with 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 &lt;uses-feature&gt;}</a>

tag and the {@code android:glEsVversion} attribute. For example:</p>

<pre>

<manifest>

</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>

<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>

<h2 id="Multimedia">Multimedia</h2>

<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

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>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="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, rather than individual files, to

give your app read/write access to media files. When a directory is selected,

your app also has access to all its child directories and content.</p>

<p>To get the absolute paths to directories on external storage devices where

applications can store media files, call the new

{@code android.content.Context.getExternalMediaDirs()} method. No

additional

permissions are needed by your app to read or write to the returned paths.

In this context, "external storage devices" are those devices which the system

considers to be a

permanent part of the device, and includes emulated external storage and

physical media slots such as SD cards in battery compartments.</p>

<p>You can bring up a system UI to allow the user to pick a directory subtree.

To do so, send  {@code android.intent.action.OPEN_DOCUMENT_TREE} in an

{@link android.content.Intent}. If the call is successful, the system displays

the {@link android.provider.DocumentsProvider} instances installed on the

device for the user to select. When the user selects a directory from this UI,

the system returns a URI representing the selected directory tree.</p>

<p>If you want to access a document in an existing directory, call the

{@code android.provider.DocumentsContract.buildDocumentViaUri()} method.

Pass the method a URI representing the path to the parent directory, and the

target document

ID. The method returns a new {@link android.net.Uri} which your app can

use to write media content with {@code DocumentsContract.createDocument()}.

<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 &amp; Connectivity</h2>

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>

<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

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.

<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>

<img src="images/battery_historian.png"

     srcset="images/battery_historian@2x.png 2x"

    alt="" width="440" height="240"

    alt="" width="760" height="462"

    id="figure2" />

<p class="img-caption">

  <strong>Figure 2.</strong>HTML visualization generated by the Battery

<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="572" id="figure3" />

    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)

</div>

<p>The L Developer Preview provides new functionality for running apps within

an enterprise environment:</p>

<ul>

<li><strong>Create managed user profiles</strong>. A device administrator can

initiate a managed provisioning process to add a co-present but separate managed

profile to a device with an existing personal account. The administrator has

control over the managed profile.</li>

<li><strong>Set device owner</strong>. Device administrators can also initiate a

managed provisioning process to automatically provision a

currently-unprovisioned device such that they have full control over the

device.</li>

</ul>

an enterprise environment. A device administrator can

initiate a managed provisioning process to add a co-present but separate <em>managed

profile</em> to a device with an existing personal account. The administrator has

control over the managed profile.</p>

<p>To start the managed provisioning process, send {@code

ACTION_PROVISION_MANAGED_PROFILE} in an {@link android.content.Intent}. If the

the managed apps visually prominent by appending a “work” badge to the icon

drawable with {@code android.os.UserManager.getBadgeDrawableForUser()}.</p>

<h3 id="LockToAppMode">Lock-to-App mode</h3>

<p>The L Developer Preview introduces a new <em>Lock-to-App</em> mode that

<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. 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

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, the device on which you want to activate

this mode must have managed profiles or must be fully controlled by a device administrator (see <a href="#ManagedProvisioning">Managed Provisioning</a> for more information). Furthermore, the device or managed profile owner must

authorize apps to use this mode by calling {@code android.app.admin.DevicePolicyManager.setLockTaskComponents()}.</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>Before activating this mode in your app, verify that your activity is authorized by calling {@code DevicePolicyManager.isLockTaskPermitted()}.</p>

<p>To set up a device owner, follow these steps:</p>

<ol>

<li>Attach a device running an <a href="https://source.android.com/source/building-running.html">Android {@code userdebug} build</a> 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>To activate <em>Lock-to-App</em> mode, call

<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 <em>Lock-to-App</em> mode is active, the following behavior takes

effect:</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 button is hidden.</li>

<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>

<p>The device will remain in this mode until an authorized activity calls

{@code Activity.stopLockTask()}.

<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">tiled rendering</a> in order to zoom in on the document).</p>

{@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">tiled rendering</a> in

order to zoom in on the document).</p>

<h2 id="TestingA11y">Testing &amp; Accessibility </h2>

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

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}.

<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 &lt;uses-feature&gt;}</a> element, so you

can ensure that your app is installed only on devices that provide the features

<p>The following values are now supported in the

<a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code &lt;uses-feature&gt;}</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:

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" />

</ul>

<h3 id="ManifestPermissions">User permissions</h3>

<p>The following values are now supported in the <a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">{@code &lt;uses-permission&gt;}</a> to declare the

<p>The following values are now supported in the

<a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">{@code

  &lt;uses-permission&gt;}</a> to declare the

permissions your app requires in order to access certain APIs.

<ul>