diff --git a/docs/html/preview/api-overview.jd b/docs/html/preview/api-overview.jd index 8ec24708511d0..0ada5f7c22b80 100644 --- a/docs/html/preview/api-overview.jd +++ b/docs/html/preview/api-overview.jd @@ -18,7 +18,7 @@ sdk.platform.apiLevel=20
  • New Android Runtime (ART)
  • If your app implements notifications...
  • If your app uses RemoteControlClient...
    • -
  • If your app uses ActivityManager.getRecentTasks()...
    • +
  • If your app uses ActivityManager.getRecentTasks()...
  • User Interface @@ -69,7 +69,7 @@ sdk.platform.apiLevel=20
  • Enterprise
    1. Managed provisioning
      2. -
    2. Lock-to-App mode
      3. +
    3. Task locking
  • Printing Framework @@ -163,10 +163,10 @@ Behavior on the Android Runtime (ART). Pay particular attention if:

    backgrounds to match the new material design widgets. Make sure that all your notifications look right with the new color scheme:

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

    Figure 1. Fullscreen activity showing a heads-up notification

    @@ -177,7 +177,7 @@ notifications look right with the new color scheme:

  • Update or remove assets that involve color.
  • The system automatically inverts action icons in notifications. Use - {@code android.app.Notification.Builder.setColor()} to set an accent color + {@code android.app.Notification. Builder.setColor()} to set an accent color in a circle behind your {@link android.app.Notification#icon} image.
  • The system ignores all non-alpha channels in action icons and the main @@ -188,7 +188,9 @@ notifications look right with the new color scheme:

    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.

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

    Notifications now appear in a small floating window (also called a heads-up notification) when the device is active @@ -218,40 +220,46 @@ gives your app more control over the presentation of media buttons, while providing a consistent experience for users across the lockscreen and unlocked device.

    -

    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.

    +

    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.

    If you are using the new -{@code android.media.session.MediaSession} class (see Media Playback Control below), attach your session -token with {@code Notification.MediaStyle.setMediaToken()} to inform the -system that this notification controls an ongoing media session.

    +{@code android.media.session.MediaSession} class +(see Media Playback Control below), attach +your session token with {@code Notification.MediaStyle.setMediaToken()} to +inform the system that this notification controls an ongoing media session.

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

    +notification as safe to show atop any lockscreen (secure or otherwise). For more +information, see Lockscreen Notifications.

    If your app uses ActivityManager.getRecentTasks()...

    -

    With the introduction of the new concurrent documents and activities tasks feature in the upcoming -release (see Concurrent documents and activities in Recents -screen below), +

    With the introduction of the new concurrent documents and activities +tasks feature in the upcoming release (see Concurrent +documents and activities in Recents screen 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.

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

    User Interface

    Material design support

    The upcoming release adds support for Android's new material 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:

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

    -

    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 -{@code <uses-feature>} tag and the {@code android:glEsVversion} attribute. For example:

    +

    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 +{@code <uses-feature>} +tag and the {@code android:glEsVversion} attribute. For example:

     <manifest>
@@ -434,7 +450,9 @@ ES 3.1. Key new functionality provided in OpenGL ES 3.1 includes:
    
 </manifest>
    -

    For more information about using OpenGL ES, including how to check the device’s supported OpenGL ES version at runtime, see the OpenGL ES API guide.

    +

    For more information about using OpenGL ES, including how to check the +device’s supported OpenGL ES version at runtime, see the +OpenGL ES API guide.

    Multimedia

    @@ -462,12 +480,13 @@ capture request. Now when the system completes the image capture request, your @@ -501,33 +520,40 @@ knows about your playback and can extract and show album art.

    Directory selection

    -

    The L Developer Preview extends the Storage Access Framework 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.

    +

    The L Developer Preview extends the Storage Access Framework to let users select an entire directory subtree, +giving apps read/write access to all contained documents without requiring user +confirmation for each item.

    -

    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.

    +

    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.

    -

    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.

    +

    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.

    -

    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()}. +

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

    + +

    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.

    Wireless & Connectivity

    @@ -561,7 +587,8 @@ information about the network, or to direct traffic to use the selected network.

    Bluetooth broadcasting

    -

    Android 4.3 introduced platform support for Bluetooth Low Energy +

    Android 4.3 introduced platform support for + Bluetooth Low Energy (BLE) in the central role. In the L Developer Preview, an Android device can now act as a Bluetooth LE peripheral device. Apps can use this capability to make their presence known to @@ -569,7 +596,8 @@ 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.

    -

    The new {@code android.bluetooth.le} APIs enable your apps to broadcast advertisements, scan for responses, and form connections with nearby BLE devices. +

    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. @@ -692,7 +720,7 @@ in {@code <sdk>/tools}.

    Figure 2.HTML visualization generated by the Battery @@ -726,7 +754,7 @@ $ historian.par [-p powerfile] bugreport.txt > out.html

    + alt="" width="360" height="609" id="figure3" />

    Figure 3. Launcher screen showing managed apps (marked with a lock badge) @@ -734,17 +762,10 @@ $ historian.par [-p powerfile] bugreport.txt > out.html

    The L Developer Preview provides new functionality for running apps within -an enterprise environment:

    - +an enterprise environment. 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.

    To start the managed provisioning process, send {@code ACTION_PROVISION_MANAGED_PROFILE} in an {@link android.content.Intent}. If the @@ -767,47 +788,71 @@ 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()}.

    -

    Lock-to-App mode

    -

    The L Developer Preview introduces a new Lock-to-App mode that +

    Task locking

    +

    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.

    -

    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 Managed Provisioning 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()}.

    +

    To prevent unauthorized usage, only authorized apps can activate task locking. +Furthermore, task locking authorization must be granted by a +specially-configured device owner app, through the {@code android.app.admin.DevicePolicyManager.setLockTaskComponents()} method.

    -

    Before activating this mode in your app, verify that your activity is authorized by calling {@code DevicePolicyManager.isLockTaskPermitted()}.

    +

    To set up a device owner, follow these steps:

    +
      +
    1. Attach a device running an Android {@code userdebug} build to your development machine.
      2. +
    2. Install your device owner app.
      3. +
    3. Create a {@code device_owner.xml} file and save it to the {@code /data/system} +directory on the device. +
      +$ 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
+
      +
      4. +
    -

    To activate Lock-to-App mode, call +

    Before using the task locking API in your app, verify that your activity is +authorized by calling {@code DevicePolicyManager.isLockTaskPermitted()}.

    + +

    To activate task locking, call {@code android.app.Activity.startLockTask()} from your authorized activity.

    -

    When Lock-to-App mode is active, the following behavior takes -effect:

    +

    When task locking is active, the following behavior takes effect:

    -

    The device will remain in this mode until an authorized activity calls -{@code Activity.stopLockTask()}. -

    Printing Framework

    Render PDF as bitmap

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

    +{@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 +tiled rendering in +order to zoom in on the document).

    Testing & Accessibility

    @@ -833,8 +878,7 @@ allows you to use shell based tools such as {@code dumpsys}, {@code am}, 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.
  • 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}. @@ -845,13 +889,16 @@ previously found in {@code AccessibilityNodeInfo}.

    Manifest Declarations

    Declarable required features

    -

    The following values are now supported in the {@code <uses-feature>} element, so you -can ensure that your app is installed only on devices that provide the features +

    The following values are now supported in the +{@code <uses-feature>} +element, so you can ensure that your app is installed only on devices that provide the features your app needs.

    User permissions

    -

    The following values are now supported in the {@code <uses-permission>} to declare the +

    The following values are now supported in the +{@code + <uses-permission>} to declare the permissions your app requires in order to access certain APIs.