diff options
Diffstat (limited to 'docs/html/preview')
33 files changed, 2281 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..40618a3 --- /dev/null +++ b/docs/html/preview/api-overview.jd @@ -0,0 +1,698 @@ +page.title=L Developer Preview APIs +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="#BehaviorNotifications">If your app implements notifications...</a></li> + <li><a href="#BehaviorFullscreen">If your app uses fullScreenIntent...</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 Recents screen</a></li> + <li><a href="#WebView">WebView updates</a></li> + </ol> + </li> + <li><a href="#UserInput">User Input</a> + <ol> + <li><a href="#IME">IME bug fixes and improvements</a></li> + </ol> + </li> + <li><a href="#Animations">Animation & Graphics</a> + <ol> + <li><a href="#OpenGLES-3-1">Support for OpenGL ES 3.1</a></li> + </ol> + </li> + <li><a href="#Multimedia">Multimedia</a> + <ol> + <li><a href="#Camera-v2">Camera V2</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">Dynamic network selection and seamless handoff</a></li> + <li><a href="#BluetoothBroadcasting">Bluetooth broadcasting</a></li> + <li><a href="#NFCEnhancements">NFC enhancements for payments</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 and APIs for power measurement</a> + </ol> + </li> + <li><a href="#Enterprise">Enterprise</a> + <ol> + <li><a href="#ManagedProvisioning">Managed provisioning</a></li> + </ol> + </li> + <li><a href="#Printing">Printing Framework</a> + <ol> + <li><a href="#PDFRender">PDF rendering</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="#Manifest">Manifest Declarations</a> + <ol> + <li><a href="#ManifestFeatures">Declarable required features</a></li> + <li><a href="#ManifestPermissions">User permissions</a></li> + </ol> + </li> +</ol> + +<h2>See also</h2> +<ol> +<li><a href="{@docRoot}sdk/api_diff/20/changes.html">API +Differences Report »</a> </li> +</ol> + +</div> +</div> + +<p>L is an upcoming release for the Android platform +that offers new features for users and app developers. This document provides +an introduction to the most notable new APIs.</p> + +<p>L is currently available as a <strong>developer preview</strong> intended +for early adopters and testers. 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>You should not publish apps +using L Developer Preview to the Google Play store.</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 L.</p> + +<h3 id="BehaviorNotifications">If your app implements notifications...</h3> + +<p>Notifications will be 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. You should remove or update +assets and text styles that involve color. The system will automatically invert +action icons in notifications. Use +{@code android.app.Notification.Builder.setColor()} to set an accent color +in a circle behind your {@code Notification.icon} image.</p> + +<p>The system will ignore all non-alpha channels in action icons and the main +notification icon, so you should assume that these icons will be alpha-only. +</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, make sure to remove this code so that +the system can present notifications correctly in Do not disturb mode. You +should use the {@link android.app.Notification.Builder} methods instead to add +sounds and vibration. +</p> + +<h3 id="BehaviorMediaControl">If your app uses RemoteControlClient...</h3> + +<p>Lockscreens in L will not show transport controls for your +{@link android.media.RemoteControlClient}. Instead, your app can provide +media playback control from the lockscreen through a media 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>You must call {@code Notification.Builder.setVisibility(Notification.VISIBILITY_PUBLIC)} to mark your media notification as safe to reveal, even when the lockscreen is secured +with a PIN, pattern, or password.</p> + +<h3 id="BehaviorFullscreen">If your app uses fullScreenIntent...</h3> + +<p>Notifications now appear in a small floating window if all these conditions +are met: the user’s activity is in fullscreen mode, the screen is on, and the +device is unlocked. If your app implements fullscreen activities, make sure that +these heads-up notifications are presented correctly.</p> + +<h3 id="BehaviorGetRecentTasks">If your app uses ActivityManager.getRecentTasks()...</h3> + +<p>With the introduction of the new document tasks feature in L (see below), +the {@code android.app.ActivityManager.getRecentTasks()} method is now +deprecated to improve user privacy. For backwards +compatibility, it will still return 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 L Developer Preview adds support for the material design style. You can create +material design apps that are visually dynamic and have UI element transitions +which feel natural and delightful 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 on Android</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. If you want to +provide a redacted public version of your notification for the system to display +on a secure lockscreen, set the public notification object in the <code>publicVersion</code> +field.</li> +<li>{@code VISIBILITY_PUBLIC}. Shows the notification’s full content. This is + the system default if visibility is left unspecified.</li> +<li>{@code VISIBILITY_SECRET}. Shows only the most minimal information, +excluding even the notification’s icon.</li> +</ul> + +<h3 id="NotificationsMetadata">Notifications metadata</h3> +<p>The L Developer Preview uses metadata associated with your app notifications +to more intelligently sort your notifications. The metadata you set also +controls how the system presents your app notifications when the user is in <em>Do +not disturb</em> mode. When constructing your notification, you can call the +following methods in {@code android.app.Notification.Builder}:</p> + +<ul> +<li>{@code setCategory()}. Allows the system to handle your app notifications +in <em>Do not disturb mode</em> (for example, if your notification represents an +incoming call, instant message, or alarm).</li> +<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. The L Developer Preview allows your app to open additional tasks +for concurrent activities or documents. This feature facilitates multitasking +by letting users quickly switch between individual activities and documents +from the Recents screen. Examples of such concurrent tasks might include web +pages in a 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 +document, 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 by using {@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 the Recents screen through 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="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> + +<h2 id="UserInput">User Input</h2> + +<h3 id="IME">IME bug fixes and improvements</h3> + +<p>Beginning in the L Developer Preview, users can more easily switch between +all input method editors (IME) <a href="{@docRoot}guide/topics/text/creating-input-method.html">supported by the platform</a>. 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 +{@code android.view.inputmethod.InputMethodManager.shouldOfferSwitchingToNextInputMethod()}.</p> + +<p>In addition, the framework will now check whether the next IME includes a +switching mechanism at all, thus supporting 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 +{@code android.view.inputmethod.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="Animations">Animation & 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>Enhanced texturing functionality +<li>Shading language improvements +<li>Optional extensions for per-sample shading, advanced blending modes, and more +<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 <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> + +<h2 id="Multimedia">Multimedia</h2> + +<h3 id="Camera=v2">Camera v2 API</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, you +need to create a {@code CameraCaptureSession} and specify the +{@link android.view.Surface} objects to send 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> + +<h3 id="AudioPlayback">Audio playback</h3> +<p>This release includes the following changes for + {@code 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 L +Developer Preview, portions of the internal pipeline are not yet floating-point. + <li>Your app can now supply audio data as a {@code ByteBuffer}, in the same +format as provided by {@code 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 +{@code 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>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, you +should 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.</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, 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 +{@code android.content.Context.getExternalMediaDirs()} method. No additional +permissions are needed by your app to read or write to the returned paths. +External storage devices here are those considered by the system 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>If you want to access a document in an existing directory, call the +{@code android.provider.DocumentsContract.buildDocumentViaUri()} method and pass +in a Uri representing the path to the parent directory and the target document +ID. The method returns a new {@link android.net.Uri} with which your app can +use to write media content with {@code DocumentsContract.createDocument()}. + +<h2 id="Wireless">Wireless & Connectivity</h2> + +<h3 id="Multinetwork">Dynamic network selection and seamless handoff</h3> +<p>The L Developer Preview provides new multi-networking APIs for your app to +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, first +instantiate a {@code android.net.ConnectivityManager}. Next, create a +{@code android.net.NetworkRequest} to specify the network features and transport +type your app is interested in. To start scanning 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}.</p> + +<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 establish a socket connection.</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> and make its 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 the +device running your app, call {@code android.bluetooth.le.BluetoothAdvertiser.startAdvisertising()} and pass in an implementation of the +{@code android.bluetooth.le.AdvertiseCallback} class to report the success +or failure of the advertising operation.</p> + +<p>Conversely, if you want to scan for Bluetooth LE devices nearby, call +{@code android.bluetooth.le.BluetoothLeScanner.startScan()} and pass in an +implementation of {@code android.bluetooth.le.ScanCallback} to report if a +Bluetooth LE advertisement is found. Optionally, you can pass in filters to scan +for a specific type of device.</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>Support for the <a href="http://www.wi-fi.org/discover-wi-fi/wi-fi-direct">Wi-fi Direct standard</a>. +<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>Use the new {@code android.nfc.NdefRecord.createTextRecord()} method if + you want 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, such as when the device is charging. This is +useful when you want to defer non user-facing units of work, have application +code that accesses the network, or want to run a number of tasks as a batch on +a regular schedule.</p> + +<p>A {@code android.app.job.JobInfo} object encapsulates such a unit of work, +and provides an exact description of the criteria you are 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 only while the device is charging, when connected to an +unmetered network, or when the system deems the device is idle.</p> + +<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> + +<h3 id="PowerMeasurementTools">Developer tools and APIs 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 run the tool to print battery usage +statistics since the device was last charged for a given app package, 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 L-based Android +bug reports and creates an HTML visualization of power-related events. It can +also visualize power consumption data from a power monitor, and will attempt to +map power usage to the wakelocks seen. You can find the Battery Historian tool +in {@code <sdk>/tools}.</p> + +<p>For best results, you should first enable full wakelock 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> + +<dt><strong>On-device power management</strong></dt> +<dd> +<p>You can use the {@code android.os.BatteryManager} API to obtain power +consumption information based on the battery fuel gauge included in Android +phones and tablets. This is useful in cases when it is not convenient to +connect external measurement equipment to the Android device.</p> +<p>To retrieve the battery properties, call {@code BatteryManager.getIntProperty()} +or {@code BatteryManager.getLongProperty()}. The properties available, the +exact resolution of the values of each, and other characteristics such as +update frequency depend on the particular device being tested.</p> + +<p>The following properties can be inspected on all Android devices:</p> + +<table> + <tr> + <th>Property</th> + <th>Description</th> + </tr> + <tr> + <td>{@code BatteryManager.BATTERY_PROPERTY_CHARGE_COUNTER}</td> + <td>Remaining battery capacity in microampere-hours.</td> + </tr> + <tr> + <td>{@code BatteryManager.BATTERY_PROPERTY_CURRENT_NOW}</td> + <td>Instantaneous battery current in microamperes.</td> + </tr> + <tr> + <td>{@code BatteryManager.BATTERY_PROPERTY_CURRENT_AVERAGE}</td> + <td>Average battery current in microamperes</td> + </tr> + <tr> + <td>{@code BatteryManager.BATTERY_PROPERTY_CAPACITY}</td> + <td>Remaining battery capacity as an integer percentage.</td> + </tr> + <tr> + <td>{@code BatteryManager.BATTERY_PROPERTY_ENERGY_COUNTER}</td> + <td>Remaining energy in nanowatt-hours.</td> + </tr> +</table> +<dd> +</dl> + +<h2 id="Enterprise">Enterprise</h2> +<h3 id="ManagedProvisioning">Managed provisioning</h3> + +<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 enroll a user device with an +existing personal account into a co-present but separate managed profile that +the administrator controls. +<li><strong>Set device owner scope</strong>. Device administrators can also +apply managed provisioning to configure a device that has no previous user +accounts installed, so that they have full control over the device. +</ul> + +<p>To start the manged provisioning process, send +{@code ACTION_PROVISION_MANAGED_PROFILE} in an {@link android.content.Intent}. A +user may be associated with more than one managed profile. To get a list of the +managed profiles associated with the user, call +{@code android.os.UserManager.getUserProfiles()}.</p> + +<p>Once a managed profile is created for a user, apps that are managed by the +device administrator will appear alongside non-managed apps in the user’s +Launcher, Recent apps screen, and notifications. A device policy management app +can make the managed apps visually prominent by appending a “work” badge to the +icon drawable with {@code android.os.UserManager.getBadgeDrawableForUser()}.</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.</p> + +<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 +{@code ParcelFileDescriptor} that is seekable (that is, the file 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 wan to convert a portion of the document into +a bitmap image (for example, to implement <a href="http://en.wikipedia.org/wiki/Tiled_rendering">tile rendering</a> in order to zoom in on the document).</p> + +<h2 id="TestingA11y">Testing & Accessibility </h2> + +<h3 id="Testing A11yImprovements">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 '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} 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 {@code android.view.accessibility.AccessibilityNodeInfo}. +The new {@code AccessibilityAction} class replaces the actions-related APIs +previously found in {@code AccessibilityNodeInfo}. +</ul> + +<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}tv}">Android TV</a> user interface. Example: +<pre> +<uses-feature android:name="android.software.leanback" + android:required="true" /> +</pre> + +<li>{@code FEATURE_MANAGEDPROFILES}. Declares that your app must only be installed on devices that support managed profiles for enterprise users. Example: +<pre> +<uses-feature android:name="android.software.managedprofiles" + android:required="true" /> +</pre> +<li>{@code FEATURE_WEBVIEW}. Declares that your app must only be installed on devices that fully implement the android.webkit.* APIs. Example: +<pre> +<uses-feature android:name="android.software.webview" + android:required="true" /> +</pre> +</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 <uses-permission>}</a> to declare the +permissions your app requires in order to access certain APIs. + +<ul> +<li>{@code SIM_COMMUNICATION}. Required to communicate with a SIM card using + logical channels. +</ul> diff --git a/docs/html/preview/images/android.png b/docs/html/preview/images/android.png Binary files differnew file mode 100644 index 0000000..3aeaa98 --- /dev/null +++ b/docs/html/preview/images/android.png diff --git a/docs/html/preview/images/art.png b/docs/html/preview/images/art.png Binary files differnew file mode 100644 index 0000000..c48f039 --- /dev/null +++ b/docs/html/preview/images/art.png diff --git a/docs/html/preview/images/bugs.png b/docs/html/preview/images/bugs.png Binary files differnew file mode 100644 index 0000000..46adf05 --- /dev/null +++ b/docs/html/preview/images/bugs.png diff --git a/docs/html/preview/images/hero.jpg b/docs/html/preview/images/hero.jpg Binary files differnew file mode 100644 index 0000000..1c52989 --- /dev/null +++ b/docs/html/preview/images/hero.jpg diff --git a/docs/html/preview/images/material.png b/docs/html/preview/images/material.png Binary files differnew file mode 100644 index 0000000..2d807d4 --- /dev/null +++ b/docs/html/preview/images/material.png diff --git a/docs/html/preview/images/notifications.png b/docs/html/preview/images/notifications.png Binary files differnew file mode 100644 index 0000000..2fb2fea --- /dev/null +++ b/docs/html/preview/images/notifications.png diff --git a/docs/html/preview/images/updates.png b/docs/html/preview/images/updates.png Binary files differnew file mode 100644 index 0000000..f165c5a --- /dev/null +++ b/docs/html/preview/images/updates.png diff --git a/docs/html/preview/images/volta.png b/docs/html/preview/images/volta.png Binary files differnew file mode 100644 index 0000000..9125081 --- /dev/null +++ b/docs/html/preview/images/volta.png diff --git a/docs/html/preview/index.jd b/docs/html/preview/index.jd new file mode 100644 index 0000000..e44e9f3 --- /dev/null +++ b/docs/html/preview/index.jd @@ -0,0 +1,236 @@ +page.title=Android L Developer Preview +page.viewport_width=970 +fullpage=true +no_footer_links=true +page.type=about +page.metaDescription=Test and build your apps against the next version of Android to ensure they're ready when the platform officially launches. +page.image={@docRoot}preview/images/hero.jpg +@jd:body + +<style> +.fullpage>#footer, +#jd-content>.content-footer.wrap { + display:none; +} +</style> + +<style> +#footer { + display: none; +} +.content-footer { + display: none; +} +</style> + +<div class="landing-body-content"> + <div class="landing-hero-container"> + <div class="landing-section preview-hero"> + <div class="landing-hero-scrim"></div> + <div class="landing-hero-wrap"> + <div class="vertical-center-outer"> + <div class="vertical-center-inner"> + + <div class="col-12"> + <div class="landing-section-header"> + + <div class="landing-h1 hero">L Developer Preview</div> + <div class="landing-subhead hero"> + <p>An early look at the next release</p> + </div> + <div class="landing-hero-description"> + <p>Test and build your apps against the next<br /> + version of Android to ensure they're ready<br/> + when the platform officially launches.</p> + </div> + + <div class="landing-body"> + <a href="/preview/setup-sdk.html" class="landing-button landing-primary" style="margin-top: 40px;"> + Get Started + </a> + </div> + </div> + + </div> + </div> + </div> <!-- end .wrap --> + <div class="landing-scroll-down-affordance"> + <a class="landing-down-arrow" href="#extending-android-to-landingables"> + <img src="/wear/images/carrot.png" alt="Scroll down to read more"> + </a> + </div> + </div> <!-- end .landing-section .landing-hero --> + </div> <!-- end .landing-hero-container --> + + + <div class="landing-rest-of-page"> + <div class="landing-section" id="extending-android-to-landingables"> + <div class="wrap"> + <div class="landing-section-header"> + <div class="landing-h1">See What's New</div> + <div class="landing-subhead"> + Take advantage of all the new capabilities, which are focused on design and performance. + </div> + </div> + + <div class="landing-body"> + + <div class="landing-breakout cols"> + <div class="col-4"> + <img src="/preview/images/material.png" style="opacity:.6" alt=""> + <p>A New UI Design</p> + <p class="landing-small"> + Create a consistent experience across mobile and the web with + material design, the new Google-wide standard. + </p> + <p class="landing-small"> + <a href="/preview/material/index.html">Learn about material</a> + </p> + </div> + <div class="col-4"> + <img src="/preview/images/art.png" alt=""> + <p>A Rehauled Runtime</p> + <p class="landing-small"> + Test your apps and get them ready for <b>ART</b> (<b>A</b>ndroid <b>R</b>un<b>t</b>ime), + the default runtime in the next release. + + </p> + <p class="landing-small"> + <a href="/preview/api-overview.html#ART">Learn about ART</a> + </p> + </div> + <div class="col-4"> + <img src="/preview/images/notifications.png" alt=""> + <p style="width:230px">Enhanced Notifications</p> + <p class="landing-small"> + Get more control over where notifications appear, + how they look, and automatic syncing to non-handheld devices. + </p> + <p class="landing-small"> + <a href="/preview/api-overview.html#UI">Learn more</a> + </p> + </div> + <div class="col-4"> + <img src="/preview/images/volta.png" alt=""> + <p>Project Volta</p> + <p class="landing-small"> + We've tuned the platform to be more energy efficient and + to give you more control over resource usage. + </p> + <p class="landing-small"> + <a href="/preview/api-overview.html#Power">Learn more</a> + </p> + </div> + </div> + <p>See the <a href="{@docRoot}preview/api-overview.html">API overview</a> for more information + on the rest of the new and updated features.</p> + </div> + </div> <!-- end .wrap --> + </div> <!-- end .landing-section --> + + + + <div class="landing-section landing-gray-background"> + <div class="wrap"> + <div class="landing-section-header"> + <div class="landing-h1">Get Your Apps Ready</div> + <div class="landing-subhead"> + <p>We're giving you an early look at the SDK, so you can test your apps and build in new features.</p> + </div> + </div> + <div class="landing-body"> + <p>You'll get the system images for the Nexus 5, Nexus 7 (v2), + and the emulator to take the new platform for a spin. In addition, you'll have + access to all the APIs with a preview build of the SDK. + </p> + + <p>Check out the getting started, developer guides, and reference documentation + for all the information you need to get up and running.</p> + + <a href="/preview/setup-sdk.html" class="landing-button landing-secondary" style="margin-top: 20px;"> + Get Started + </a> + </div> + </div> + </div> + <div class="landing-section"> + <div class="wrap"> + <div class="cols"> + <div class="landing-body"> + <div class="col-3-wide"> + <a target="_blank" href="http://submit-bugs!"> + <img class="landing-social-image" src="{@docRoot}preview/images/bugs.png" alt=""> + </a> + <div class="landing-social-copy"> + <p>Issue Tracker</p> + <p class="landing-small"> + Let us know when you encounter problems, so we can fix them and make + the platform better for you and your users. + </p><p class="landing-small"> + <a target="_blank" href="http://submit-bugs!"> + Report Issues</a> + </p> + <p></p> + </div> + </div> + <div class="col-3-wide"> + <a target="_blank" href="http://plus.google.com"> + <img class="landing-social-image" src="//www.google.com/images/icons/product/gplus-128.png" alt=""> + </a> + <div class="landing-social-copy"> + <p>Google+ </p> + <p class="landing-small"> + Join the community of Android developers testing out the L Developer Preview and + share your thoughts and experiences. + </p><p class="landing-small"> + <a target="_blank" href="http://plus.google.com"> + Discuss on Google+</a> + </p> + </div> + </div> + <div class="col-3-wide"> + <a target="_blank" href="{@docRoot}preview/release-notes.html"> + <img class="landing-social-image" src="{@docRoot}preview/images/updates.png" alt=""> + </a> + <div class="landing-social-copy"> + <p>Support and Updates</p> + <p class="landing-small"> + Updates to the L Developer Preview are delivered + in the Android SDK Manager. Check back periodically + for news about the changes. + </p> + <p class="landing-small"> + <a target="_blank" href="{@docRoot}preview/support.html">Get Support</a> + </p> + </div> + </div> + </div> + </div> + </div> <!-- end .wrap --> + </div> + + <div class="content-footer wrap" itemscope="" itemtype="http://schema.org/SiteNavigationElement"> + <div class="layout-content-col col-16" style="padding-top:4px"> + <style>#___plusone_0 {float:right !important;}</style> + <div class="g-plusone" data-size="medium"></div> + </div> + </div> + <div id="footer" class="wrap" style="width:940px;position:relative;top:-35px;z-index:-1"> + <div id="copyright"> + Except as noted, this content is + licensed under <a href="http://creativecommons.org/licenses/by/2.5/"> + Creative Commons Attribution 2.5</a>. For details and + restrictions, see the <a href="/license.html">Content + License</a>. + </div> + </div> + </div> <!-- end landing-body-content --> + + <script> + $("a.landing-down-arrow").on("click", function(e) { + $("body").animate({ + scrollTop: $(".preview-hero").height() + 76 + }, 1000, "easeOutQuint"); + e.preventDefault(); + }); + </script>
\ No newline at end of file diff --git a/docs/html/preview/material/animations.jd b/docs/html/preview/material/animations.jd new file mode 100644 index 0000000..cee782a --- /dev/null +++ b/docs/html/preview/material/animations.jd @@ -0,0 +1,378 @@ +page.title=Animations + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> +<ol> + <li><a href="#touch">Touch Feedback</a></li> + <li><a href="#reveal">Reveal Effect</a></li> + <li><a href="#transitions">Activity Transitions</a></li> + <li><a href="#curvedmotion">Curved Motion</a></li> + <li><a href="#viewstate">View State Changes</a></li> + <li><a href="#drawabletint">Drawable Tinting</a></li> +</ol> +</div> +</div> + +<p>Animations in material design give users feedback on their actions and provide visual +continuity as users interact with your app. The material theme provides some default animations +for buttons and activity transitions, and the Android L Developer Preview provides additional +APIs that let you customize these animations and create new ones:</p> + +<ul> +<li>Touch feedback</li> +<li>Reveal effect</li> +<li>Activity transitions</li> +<li>Curved motion</li> +<li>View state changes</li> +</ul> + + +<h2 id="touch">Touch Feedback</h2> + +<p>In the Android L Developer Preview the default touch feedback animations for buttons use the new +<code>RippleDrawable</code> class, which transitions between different states with a ripple +effect.</p> + +<p>To use this functionality in your custom views, create a <code>RippleDrawable</code> and set +it as the background of your view. You can define a <code>RippleDrawable</code> as an XML resource +using the <code>ripple</code> element.</p> + + +<h2 id="reveal">Reveal Effect</h2> + +<p>The <code>View.createRevealAnimator</code> method enables you to animate a clipping circle +to reveal or hide a view.</p> + +<p>To reveal a previously invisible view using this effect:</p> + +<pre> +// previously invisible view +View myView = findViewById(R.id.my_view); + +// get the center for the clipping circle +int cx = (myView.getLeft() + myView.getRight()) / 2; +int cy = (myView.getTop() + myView.getBottom()) / 2; + +// get the final radius for the clipping circle +int finalRadius = myView.getWidth(); + +// create and start the animator for this view +// (the start radius is zero) +ValueAnimator anim = myView.createRevealAnimator(cx, cy, 0, finalRadius); +anim.start(); +</pre> + +<p>To hide a previously visible view using this effect:</p> + +<pre> +// previously visible view +final View myView = findViewById(R.id.my_view); + +// get the center for the clipping circle +int cx = (myView.getLeft() + myView.getRight()) / 2; +int cy = (myView.getTop() + myView.getBottom()) / 2; + +// get the initial radius for the clipping circle +int initialRadius = myView.getWidth(); + +// create the animation (the final radius is zero) +ValueAnimator anim = myView.createRevealAnimator(cx, cy, initialRadius, 0); + +// make the view invisible when the animation is done +anim.addListener(new AnimatorListenerAdapter() { + @Override + public void onAnimationEnd(Animator animation) { + super.onAnimationEnd(animation); + myView.setVisibility(View.INVISIBLE); + } +}); + +// start the animation +anim.start(); +</pre> + + +<h2 id="transitions">Activity Transitions</h2> + +<p>The Android L Developer Preview enables your app to customize the default animations for +activity transitions. You can specify custom animations for enter and exit transitions and for +transitions of shared elements between activities.</p> + +<ul> + <li>An <strong>enter</strong> transition determines how views in an activity enter the scene. + For example, in the <em>explode</em> enter transition the views enter the scene from outside + and fly in towards the center of the screen.</li> + + <li>An <strong>exit</strong> transition determines how views in an activity exit the scene. For + example, in the <em>explode</em> exit transition the views exit the scene away from the + center.</li> + + <li>A <strong>shared elements</strong> transition determines how views that are shared between + two activities transition between these activities. For example, if two activities have the same + image in different positions and sizes, the <em>moveImage</em> shared element transition + translates and scales the image smoothly between these activities.</li> +</ul> + +<img src="/preview/material/images/SceneTransition.png" alt="" + id="figure1" style="width:600px;margin-top:20px"/> +<p class="img-caption"> + <strong>Figure 1</strong> - A scene transition with one shared element. +</p> + +<h3>Specify custom transitions</h3> + +<p>First, enable window content transitions with the <code>android:windowContentTransitions</code> +attribute when you define a style that inherits from the material theme:</p> + +<pre> +<style name="BaseAppTheme" parent="android:Theme.Material"> + <!-- enable window content transitions --> + <item name="android:windowContentTransitions">true</item> + + <!-- specify enter and exit transitions --> + <item name="android:windowEnterTransition">@transition/explode</item> + <item name="android:windowExitTransition">@transition/explode</item> + + <!-- specify shared element transitions --> + <item name="android:windowSharedElementEnterTransition"> + @transition/move_image</item> + <item name="android:windowSharedElementExitTransition"> + @transition/move_image</item> +</style> +</pre> + +<p>You can also specify enter, exit, and shared element transitions in your style definition. +The <code>move_image</code> transition in this example is defined as follows:</p> + +<pre> +<!-- res/transition/move_image.xml --> +<!-- (see also Shared Transitions below) --> +<transitionSet xmlns:android="http://schemas.android.com/apk/res/android"> + <moveImage> + <targets> + <!-- shared view in the first activity --> + <target android:targetId="@id/image_small" /> + <!-- shared view in the second activity --> + <target android:targetId="@id/image_big" /> + </targets> + </moveImage> +</transitionSet> +</pre> + +<p>The <code>moveImage</code> element corresponds to the <code>android.transition.MoveImage</code> +class. For more information, see the API reference for <code>android.transition.Transition</code>. +</p> + +<p>To enable window content transitions in your code instead, call the +<code>Window.requestFeature</code> method:</p> + +<pre> +// inside your activity +getWindow().requestFeature(Window.FEATURE_CONTENT_TRANSITIONS); + +// set an exit transition +getWindow().setExitTransition(new Explode()); +</pre> + +<p>To specify transitions in your code, call these methods with a <code>Transition</code> +object:</p> + +<ul> + <li><code>Window.setEnterTransition</code></li> + <li><code>Window.setExitTransition</code></li> + <li><code>Window.setSharedElementEnterTransition</code></li> + <li><code>Window.setSharedElementExitTransition</code></li> +</ul> + +<h3>Start an activity using transitions</h3> + +<p>If you enable transitions and set an exit transition for an activity, the transition is activated +when you launch another activity with the <code>startActivity</code> method. If you have set an +enter transition for the second activity, the transition is also activated when the activity +starts.</p> + +<h3>Shared elements transitions</h3> + +<p>To make a screne transition animation between two activities that have a shared element:</p> + +<ol> +<li>Enable window content transitions in your style.</li> +<li>Specify a shared elements transition in your style.</li> +<li>Define your transition as an XML resource specifying the IDs of the target views.</li> +<li>Assign a common name to the shared elements in both layouts with the + <code>android:viewName</code> attribute.</li> +<li>Use the <code>ActivityOptions.makeSceneTransitionAnimation</code> method.</li> +</ol> + +<pre> +// get the element that receives the click event +final View imgContainerView = findViewById(R.id.img_container); + +// get the common element for the transition in this activity +final View androidRobotView = findViewById(R.id.android_robot_img); + +// define a click listener +imgContainerView.setOnClickListener(new View.OnClickListener() { + @Override + public void onClick(View view) { + Intent intent = new Intent(this, Activity2.class); + // create the transition animation - the images in the layouts + // of both activities are defined with android:viewName="robot" + ActivityOptions options = ActivityOptions + .makeSceneTransitionAnimation(this, androidRobotView, "robot"); + // start the new activity + startActivity(intent, options.toBundle()); + } +}); +</pre> + +<p>For shared dynamic views that you generate in your code, use the <code>View.setViewName</code> +method to specify a common element name in both activities.</p> + +<h3>Multiple shared elements</h3> + +<p>To make a scene transition animation between two activities that have more than one shared +element, define the shared elements in both layouts with the <code>android:viewName</code> +attribute (or use the <code>View.setViewName</code> in both activities), and create an +<code>ActivityOptions</code> object as follows:</p> + +<pre> +ActivityOptions options = ActivityOptions.makeSceneTransitionAnimation(this, + new Pair[] { + Pair.create(view1, "agreedName1"), + Pair.create(view2, "agreedName2"), + ... + } +); +</pre> + + +<h2 id="curvedmotion">Curved Motion</h2> + +<p>Animations in material design rely on curves for time interpolation and spatial movement +patterns. The Android L Developer Preview provides new APIs that enable you to define custom +timing curves and curved motion patterns for animations.</p> + +<p>The <code>PathInterpolator</code> class is a new interpolator based on a Bézier curve or a +<code>Path</code> object. This interpolator specifies a motion curve in a 1x1 square, with anchor +points at (0,0) and (1,1) and control points as specified using the constructor arguments. You can +also define a <code>PathInterpolator</code> as an XML resource:</p> + +<pre> +<pathInterpolator xmlns:android="http://schemas.android.com/apk/res/android" + android:controlX1="0.4" + android:controlY1="0" + android:controlX2="1" + android:controlY2="1"/> +</pre> + +<p>The Android L Developer Preview provides XML resources for the three basic curves in the +material design specification:</p> + +<ul> + <li><code>@interpolator/fast_out_linear_in.xml</code></li> + <li><code>@interpolator/fast_out_slow_in.xml</code></li> + <li><code>@interpolator/linear_out_slow_in.xml</code></li> +</ul> + +<p>You can pass a <code>PathInterpolator</code> object to the +<code>Animation.setInterpolation</code> method.</p> + +<p>The <code>ObjectAnimator</code> class has new constructors that enable you to animate +coordinates along a path using two or more properties at once. For example, the following animator +uses a <code>Path</code> object to animate the X and Y properties of a view:</p> + +<pre> +ObjectAnimator mAnimator; +mAnimator = ObjectAnimator.ofFloat(view, View.X, View.Y, path); +... +mAnimator.start(); +</pre> + + +<h2 id="viewstate">View State Changes</h2> + +<p>The new <code>StateListAnimator</code> class lets you define animators that run when the state +of a view changes. The following example shows how to define an <code>StateListAnimator</code> as +an XML resource:</p> + +<pre> +<!-- animate the elevation property of a view when pressed --> +<selector xmlns:android="http://schemas.android.com/apk/res/android"> + <item android:state_pressed="true"> + <set> + <objectAnimator android:propertyName="elevation" + android:duration="100" + android:valueTo="60" + android:valueType="floatType"/> + <!-- you could have other objectAnimator elements + here for "x" and "y", or other properties --> + </set> + </item> + <item android:state_enabled="true" + android:state_pressed="false" + android:state_focused="true"> + <set> + <objectAnimator android:propertyName="elevation" + android:duration="100" + android:valueTo="10" + android:valueType="floatType"/> + </set> + </item> +</selector> +</pre> + +<p>The new <code>AnimatedStateListDrawable</code> class lets you create drawables that show +animations between state changes of the associated view. Some of the system widgets in the +Android L Developer Preview use these animations by default. The following example shows how +to define an <code>AnimatedStateListDrawable</code> as an XML resource:</p> + +<pre> +<!-- res/drawable/myanimstatedrawable.xml --> +<animated-selector + xmlns:android="http://schemas.android.com/apk/res/android"> + + <!-- provide a different drawable for each state--> + <item android:id="@+id/pressed" android:drawable="@drawable/drawableP" + android:state-pressed="true"/> + <item android:id="@+id/focused" android:drawable="@drawable/drawableF" + android:state-focused="true"/> + <item android:id="@id/default" + android:drawable="@drawable/drawableD"/> + + <!-- specify a transition --> + <transition android:fromId="@+id/default" android:toId="@+id/pressed"> + <animation-list> + <item android:duration="15" android:drawable="@drawable/dt1"/> + <item android:duration="15" android:drawable="@drawable/dt2"/> + ... + </animation-list> + </transition> + ... +</animated-selector> +</pre> + + +<h2 id="drawabletint">Drawable Tinting</h2> + +<p>The Android L Developer Preview enables you to define bitmaps as an alpha mask and to tint +them using a color resource or a theme attribute that resolves to a color resource. You can +create these assets only once and color them automatically to match your theme.</p> + +<p>To apply a tint to a bitmap in your code, use the <code>setTint</code> method in these +classes:</p> + +<ul> +<li><code>PaintDrawable</code></li> +<li><code>NinePatchDrawable</code></li> +<li><code>RippleDrawable</code></li> +</ul> + +<p>In your layouts, use the <code>android:tint</code> attribute instead.</p> + +<p>The <code>setTint</code> method also lets you set the tint blending mode for +<code>NinePatchDrawable</code> and <code>RippleDrawable</code> objects in your code. To set the +tint mode in your layouts, use the <code>android:tintMode</code> attribute.</p> diff --git a/docs/html/preview/material/compatibility.jd b/docs/html/preview/material/compatibility.jd new file mode 100644 index 0000000..ce04e9e --- /dev/null +++ b/docs/html/preview/material/compatibility.jd @@ -0,0 +1,63 @@ +page.title=Compatibility + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> +<ol> + <li><a href="#materialtheme">Material Theme</a></li> + <li><a href="#layouts">Layouts</a></li> + <li><a href="#widgets">UI Widgets</a></li> + <li><a href="#animation">Animation APIs</a></li> +</ol> +</div> +</div> + +<p>The new material design features (like the material theme and custom animations) are only +available in the Android L Developer Preview. However, you can design your apps to make use of +these features when running on devices with the Android L Developer Preview and still be +compatible with previous releases of Android.</p> + + +<h2 id="materialtheme">Material Theme</h2> + +<p>The material theme is only available in the Android L Developer Preview. To configure your +app to use the material theme on devices running the Android L Developer Preview and an older +theme on devices running earlier versions of Android:</p> + +<ol> +<li>Define a theme that inherits from an older theme (like Holo) in +<code>res/values/styles.xml</code>.</li> +<li>Define a theme with the same name that inherits from the material theme in +<code>res/values-v21/styles.xml</code>.</li> +<li>Set this theme as your app's theme in the manifest file.</li> +</ol> + +<p class="note"><strong>Note:</strong> If you do not provide an alternative theme in this manner, +your app will not run on earlier versions of Android.</p> + + +<h2 id="layouts">Layouts</h2> + +<p>If the layouts that you design according to the material design guidelines do not use any +of the new XML attributes from the Android L Developer Preview, they will work on previous +versions of Android. Otherwise, you can provide alternative layouts. You can also provide +alternative layouts to customize how your app looks on earlier versions of Android.</p> + +<p>Create your layout files for the Android L Developer Preview inside <code>res/layout-v21/</code> +and your alternative layout files for earlier versions of Android inside <code>res/layout/</code>. +Alternative layouts have the same file name.</p> + + +<h2 id="widgets">UI Widgets</h2> + +<p>The <code>RecyclerView</code> and <code>CardView</code> widgets are included in the Android L +Developer Preview Support Library, so they are available in earlier versions of Android.</p> + + +<h2 id="animation">Animation APIs</h2> + +<p>The new APIs for custom animations are only available in the Android L Developer Preview. To +preserve compatibility with earlier verisons of Android, check the system version at runtime before +you invoke these APIs.</p>
\ No newline at end of file diff --git a/docs/html/preview/material/get-started.jd b/docs/html/preview/material/get-started.jd new file mode 100644 index 0000000..9c0e55d --- /dev/null +++ b/docs/html/preview/material/get-started.jd @@ -0,0 +1,146 @@ +page.title=Get Started + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> +<ol> + <li><a href="#applytheme">Apply the Material Theme</a></li> + <li><a href="#layouts">Design Your Layouts</a></li> + <li><a href="#depth">Specify Depth in Your Views</a></li> + <li><a href="#widgets">Use the New UI Widgets</a></li> + <li><a href="#apis">Use the New APIs</a></li> +</ol> +</div> +</div> + +<p>To create apps with material design:</p> + +<ol> + <li style="margin-bottom:10px"> + Take a look at the <a href="">material design specification</a>.</li> + <li style="margin-bottom:10px"> + Apply the material <strong>theme</strong> to your app.</li> + <li style="margin-bottom:10px"> + Define additional <strong>styles</strong> to customize the material theme.</li> + <li style="margin-bottom:10px"> + Create your <strong>layouts</strong> following material design guidelines.</li> + <li style="margin-bottom:10px"> + Specify the <strong>depth</strong> for views to cast appropriate shadows.</li> + <li style="margin-bottom:10px"> + Use the new <strong>widgets</strong> for complex views, such as lists and cards.</li> + <li style="margin-bottom:10px"> + Use the new <strong>APIs</strong> to customize the animations in your app.</li> +</ol> + +<h3>Update Your App for the Android L Developer Preview</h3> + +<p>To update an existing app for the Android L Developer Preview, design new layouts following +material design guidelines and consider how you can improve the user experience for your app by +incorporating depth, touch feedback and animations in your UI.</p> + +<h3>Create New Apps for the Android L Developer Preview</h3> + +<p>If you are creating a new app for the Android L Developer Preview, the material design +guidelines provide you with a solid design framework for your app. Follow these guidelines and +use the new functionality in the Android framework to design and develop your app.</p> + + +<h2 id="applytheme">Apply the Material Theme</h2> + +<p>To apply the material theme in your app, specify a style that inherits from +<code>android:theme.Material</code>:</p> + +<pre> +<!-- res/values/styles.xml --> +<resources> + <!-- your app's theme inherits from the Material theme --> + <style name="AppTheme" parent="android:Theme.Material"> + <!-- theme customizations --> + </style> +</resources> +</pre> + +<p>The material theme provides new system widgets that let you set their color palette and default +animations for touch feedback and activity transitions. For more details, see +<a href="{@docRoot}preview/material/theme.html">Material Theme</a>.</p> + + +<h2 id="layouts">Design Your Layouts</h2> + +<p>In addition to applying and customizing the material theme, your layouts should conform to +the material design guidelines. When you design your layouts, pay special attention to the +following:</p> + +<ul> +<li>Baseline grids</li> +<li>Keylines</li> +<li>Spacing</li> +<li>Touch target size</li> +<li>Layout structure</li> +</ul> + +<p>You still define layouts inside XML files using the standard tools from the Android framework. +For details on the material design guidelines, see the <a href="">material design +specification</a>.</p> + + +<h2 id="depth">Specify Depth in Your Views</h2> + +<p>In the Android L Developer Preview, views can cast shadows. The elevation value of a view +determines the size of its shadow. To set the elevation of a view, use the +<code>android:elevation</code> attribute in your layouts:</p> + +<pre> +<Button + android:id="@+id/my_button" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/next" + <strong>android:elevation</strong>="10dp" /> +</pre> + +<p>For more details, see <a href="{@docRoot}preview/material/views-shadows.html">Views and +Shadows</a>.</p> + + +<h2 id="widgets">Use the New UI Widgets</h2> + +<p>The Android L Developer Preview includes two new UI widgets for complex views, +<code>RecyclerView</code> and <code>CardView</code>. <code>RecyclerView</code> is a more advanced +version of <code>ListView</code> that provides performance improvements and is easier to use. +<code>CardView</code> lets you show pieces of information inside cards with a consistent look +across apps. To include a <code>CardView</code> in your layout:</p> + +<pre> +<android.support.v7.widget.CardView + android:id="@+id/card_view" + android:layout_width="200dp" + android:layout_height="200dp" + card_view:cardCornerRadius="3dp"> + ... +</android.support.v7.widget.CardView> +</pre> + +<p>For more information, see <a href="{@docRoot}preview/material/ui-widgets.html">UI Widgets</a>.</p> + + +<h2 id="apis">Use the APIs to Customize Your Animations</h2> + +<p>The Android L Developer Preview includes new APIs to create custom animations in your app. +For example, you can enable activity transitions and define an exit transition inside an +activity:</p> + +<pre> +// inside your activity +getWindow().requestFeature(Window.FEATURE_CONTENT_TRANSITIONS); + +// set an exit transition +getWindow().setExitTransition(new Explode()); +</pre> + +<p>When you start another activity from this activity, the exit transition is activated.</p> + +<p>To learn about all the features in the new APIs, see <a +href="{@docRoot}preview/material/animations.html">Animations</a>.</p>
\ No newline at end of file diff --git a/docs/html/preview/material/images/MaterialDark.png b/docs/html/preview/material/images/MaterialDark.png Binary files differnew file mode 100644 index 0000000..6a72280 --- /dev/null +++ b/docs/html/preview/material/images/MaterialDark.png diff --git a/docs/html/preview/material/images/MaterialLight.png b/docs/html/preview/material/images/MaterialLight.png Binary files differnew file mode 100644 index 0000000..0e85528 --- /dev/null +++ b/docs/html/preview/material/images/MaterialLight.png diff --git a/docs/html/preview/material/images/RecyclerView.png b/docs/html/preview/material/images/RecyclerView.png Binary files differnew file mode 100644 index 0000000..364951d --- /dev/null +++ b/docs/html/preview/material/images/RecyclerView.png diff --git a/docs/html/preview/material/images/SceneTransition.png b/docs/html/preview/material/images/SceneTransition.png Binary files differnew file mode 100644 index 0000000..ecaf472 --- /dev/null +++ b/docs/html/preview/material/images/SceneTransition.png diff --git a/docs/html/preview/material/images/ThemeColors.png b/docs/html/preview/material/images/ThemeColors.png Binary files differnew file mode 100644 index 0000000..bbcecf2 --- /dev/null +++ b/docs/html/preview/material/images/ThemeColors.png diff --git a/docs/html/preview/material/images/card_travel.png b/docs/html/preview/material/images/card_travel.png Binary files differnew file mode 100644 index 0000000..a804ca0 --- /dev/null +++ b/docs/html/preview/material/images/card_travel.png diff --git a/docs/html/preview/material/images/list_mail.png b/docs/html/preview/material/images/list_mail.png Binary files differnew file mode 100644 index 0000000..ca53ee1 --- /dev/null +++ b/docs/html/preview/material/images/list_mail.png diff --git a/docs/html/preview/material/index.jd b/docs/html/preview/material/index.jd new file mode 100644 index 0000000..b7abcb4 --- /dev/null +++ b/docs/html/preview/material/index.jd @@ -0,0 +1,117 @@ +page.title=Material Design +page.type=design + +@jd:body + +<p itemprop="description">The Android L Developer Preview includes support for material design apps. Material design +is a comprehensive guide for visual, motion, and interaction design across platforms and devices. +To use material design in your Android apps, follow the guidelines defined in the +<a href="">material design specification</a> and use the new components and functionality +available in the Android L Developer Preview.</p> + +<p>The Android L Developer Preview provides the following elements for you to build material +design apps:</p> + +<ul> + <li>A new theme</li> + <li>New widgets for complex views</li> + <li>New APIs for custom shadows and animations</li> +</ul> + + +<h3>Material Theme</h3> + +<p>The material theme provides a new style for your app, system widgets that let you set +their color palette, and default animations for touch feedback and activity transitions.</p> + +<!-- two columns --> +<div style="width:700px;margin-top:25px;margin-bottom:20px"> +<div style="float:left;width:250px;margin-left:40px;margin-right:60px;"> + <img src="{@docRoot}preview/material/images/MaterialDark.png" style="width:250px;"/> + <div style="width:140px;margin:0 auto"> + <p style="margin-top:8px">Dark Material theme</p> + </div> +</div> +<div style="float:left;width:250px;margin-right:0px;"> + <img src="{@docRoot}preview/material/images/MaterialLight.png" style="width:250px;"/> + <div style="width:140px;margin:0 auto"> + <p style="margin-top:8px">Light Material theme</p> + </div> +</div> +<br style="clear:left"/> +</div> + + +<h3>New Widgets</h3> + +<p>The Android L Developer Preview includes two new widgets for displaying complex views:</p> + +<!-- two columns --> +<div style="width:700px;margin-top:25px;margin-bottom:20px"> +<div style="float:left;width:250px;margin-left:40px;margin-right:60px;"> + <img src="{@docRoot}preview/material/images/list_mail.png" style="width:250px;"/> + <p>The new <code>RecyclerView</code> widget is a more advanced version of <code>ListView</code> + provides performance improvements for dynamic views and is easier to use.</p> +</div> +<div style="float:left;width:250px;margin-right:0px;"> + <img src="{@docRoot}preview/material/images/card_travel.png" style="width:250px;"/> + <p>The new <code>CardView</code> widget lets you display important pieces of information inside + cards that have a consistent look and feel.</p> +</div> +<br style="clear:left"/> +</div> + + +<h3>View Shadows</h3> + +<p>In addition to the X and Y components, views in the Android L Developer Preview have a Z +component. This new component represents the elevation of a view, which determines the size of +its shadow: views with higher Z values cast bigger shadows.</p> + +<div style="width:290px;margin-left:35px;float:right"> + <div class="framed-nexus5-port-span-5"> + <video class="play-on-hover" autoplay> + <source src="/preview/material/videos/ContactsAnim.mp4"/> + <source src="/preview/material/videos/ContactsAnim.webm"/> + <source src="/preview/material/videos/ContactsAnim.ogv"/> + </video> + </div> + <div style="font-size:10pt;margin-left:20px;margin-bottom:30px"> + <em>Click on the device screen to replay the movie</em> + </div> +</div> + +<h3>Animations</h3> + +<p>The Android L Developer Preview provides new APIs that let you create custom animations for +touch feedback in UI controls, view state changes, and activity transitions.</p> + +<p>The new animation APIs in the Android L Developer Preview let you:</p> + +<ul> +<li style="margin-bottom:15px"> +Respond to touch events in your views with <strong>touch feedback</strong> animations. +</li> +<li style="margin-bottom:15px"> +Hide and show views with <strong>reveal effect</strong> animations. +</li> +<li style="margin-bottom:15px"> +Switch between activities with custom <strong>activity transition</strong> animations. +</li> +<li style="margin-bottom:15px"> +Create custom animation patterns with <strong>curved motion</strong>. +</li> +<li style="margin-bottom:15px"> +Animate changes in one or more view properties with <strong>view state change</strong> animations. +</li> +<li style="margin-bottom:15px"> +Show animations in <strong>state list drawables</strong> between view state changes. +</li> +</ul> + + +<h3>New Capabilities for Drawables</h3> + +<p>The Android L Developer Preview supports <strong>drawable tinting</strong>: you can define +bitmaps as an alpha mask and tint them using a color resource. You can create these assets only +once and color each instance to match your theme.</p> diff --git a/docs/html/preview/material/theme.jd b/docs/html/preview/material/theme.jd new file mode 100644 index 0000000..b954960 --- /dev/null +++ b/docs/html/preview/material/theme.jd @@ -0,0 +1,100 @@ +page.title=Material Theme + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> +<ol> + <li><a href="#colorpalette">Customize the Colot Palette</a></li> + <li><a href="#statusbar">Customize the Status Bar</a></li> + <li><a href="#inheritance">Theme Inheritance</a></li> +</ol> +</div> +</div> + +<p>The new material theme provides:</p> + +<ul> + <li>System widgets that let you set their color palette</li> + <li>Touch feedback animations for the system widgets</li> + <li>Activity transition animations</li> +</ul> + +<p>The Android L Developer Preview lets you easily customize the look of the material theme +according to your brand identity with a color palette you control. You can tint the app bar and +the status bar using theme attributes, as shown in Figure 1.</p> + +<div style="float:right;margin-left:25px;margin-top:-25px"> +<img src="{@docRoot}preview/material/images/ThemeColors.png" style="width:250px"/> +<p class="img-caption"><strong>Figure 1.</strong> Customizing the material theme.</p> +</div> + +<p>The system widgets have a new design and touch feedback animations. Activity transitions help +users navigate your app by providing visual continuity. You can customize the color palette, +the touch feedback animations, and the activity transitions for your app.</p> + +<p>The material theme is defined as:</p> + +<ul> + <li><code>@android:style/Theme.Material</code> (dark version)</li> + <li><code>@android:style/Theme.Material.Light</code> (light version)</li> + <li><code>@android:style/Theme.Material.Light.DarkActionBar</code></li> +</ul> + +<p>For a list of material styles that you can use, see the API reference for +<code>android.R.styles</code>.</p> + +<p class="note"> +<strong>Note:</strong> The material theme is only available in the Android L Developer Preview. +For more information, see <a href="{@docRoot}preview/material/compatibility.html">Compatibility</a>. +</p> + + +<h2 id="colorpalette">Customize the Color Palette</h2> + +<p>To customize the theme's base colors to fit your brand, define your custom colors using +theme attributes when you inherit from the material theme:</p> + +<pre> +<resources> + <!-- inherit from the material theme --> + <style name="AppTheme" parent="android:Theme.Material"> + <!-- Main theme colors --> + <!-- your app's branding color (for the app bar) --> + <item name="android:colorPrimary">@color/primary</item> + <!-- darker variant of colorPrimary (for contextual app bars) --> + <item name="android:colorPrimaryDark">@color/primary_dark</item> + + <!-- other theme colors --> + <item name="android:colorButtonNormal">@color/button_normal</item> + <item name="android:windowBackground">@color/wbackground</item> + </style> +</resources> +</pre> + + +<h2 id="statusbar">Customize the Status Bar</h2> + +<p>The material theme lets you easily customize the status bar, so you can specify a +color which fits your brand and provides enough contrast to show the white status icons. To +set a custom color for the status bar, use the <code>android:statusBarColor</code> attribute when +you extend the material theme.</p> + +<p>To handle the color of the status bar yourself (for example, by adding a gradient in the +background), set the <code>android:statusBarColor</code> attribute to +<code>@android:color/transparent</code>. You can also use the +<code>Window.setStatusBarColor</code> method for animations or fading.</p> + +<p class="note"><strong>Note:</strong> +The status bar should almost always have a clear delineation from the primary toolbar, except for +full-bleed imagery cases and when you use a gradient as a protection. +</p> + + +<h2 id="inheritance">Theme Inheritance</h3> + +<p>In the Android L Developer Preview, elements in XML layout definitions can specify the +<code>android:theme</code> attribute, which references a theme resource. This attribute modifies +the theme for the element and any elements inflated below it, which is useful to alter theme +color palettes in a specific portion of an interface.</p>
\ No newline at end of file diff --git a/docs/html/preview/material/ui-widgets.jd b/docs/html/preview/material/ui-widgets.jd new file mode 100644 index 0000000..f18bff9 --- /dev/null +++ b/docs/html/preview/material/ui-widgets.jd @@ -0,0 +1,197 @@ +page.title=UI Widgets + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> +<ol> + <li><a href="#recyclerview">RecyclerView</a></li> + <li><a href="#cardview">CardView</a></li> +</ol> +</div> +</div> + +<p>The support library in the Android L Developer Preview contains two new widgets, +<code>RecyclerView</code> and <code>CardView</code>. Use these widgets to show complex lists +and cards in your app. These widgets have material design styles and animations by default.</p> + + +<h2 id="recyclerview">RecyclerView</h2> + +<p><code>RecyclerView</code> is a more advanced version of <code>ListView</code>. This widget is +a container for large sets of views that can be recycled and scrolled very efficiently. Use the +<code>RecyclerView</code> widget when you have lists with elements that change dynamically.</p> + +<p><code>RecyclerView</code> is easy to use, because it provides:</p> + +<ul> + <li>A set of layout managers for positioning items</li> + <li>Default animations for common item operations</li> +</ul> + +<p>You also have the flexibility to define custom layout managers and animations for this +widget.</p> + +<p>To use the <code>RecyclerView</code> widget, you have to specify an adapter and a layout +manager. An <strong>adapter</strong> provides a binding from a dataset to views that are displayed +within a <code>RecyclerView</code>. For example, if your dataset is an array of strings displayed +as <code>TextView</code> items, the layout manager asks the adapter to: +</p> + +<ul> + <li>Set the text of an existing <code>TextView</code> to one of the strings in the dataset</li> + <li>Create new <code>TextView</code> objects</li> + <li>Determine the size of the dataset</li> +</ul> + +<p>To create an adapter, you extend the <code>RecyclerView.Adapter</code> class. The details of +the implementation depend on the specifics of your dataset and the type of views. Fore more +information, see the examples below.</p> + +<img src="/preview/material/images/RecyclerView.png" alt="" id="figure1" style="width:550px"/> +<p class="img-caption"> + <strong>Figure 1</strong> - The <code>RecyclerView</code> widget. +</p> + +<p>A <strong>layout manager</strong> positions item views inside a <code>RecyclerView</code> and +determines when to reuse item views that are no longer visible to the user. To reuse (or +<em>recycle</em>) a view, a layout manager may ask the adapter to replace the content of the +view with a different element from the dataset. Recycling views in this manner improves +performance by avoiding the creation of unnecessary views or performing expensive +<code>findViewById</code> lookups. +</p> + +<p><code>RecyclerView</code> provides two layout managers you can use:</p> + +<ul> + <li><code>LinearLayoutManager</code> shows the items in a vertically scrolling list.</li> + <li><code>GridLayoutManager</code> shows the items in a rectangular grid.</li> +</ul> + +<p>To create a custom layout, you extend the <code>RecyclerView.LayoutManager</code> class.</p> + +<h3>Examples</h3> + +<p>To include a <code>RecyclerView</code> in your layout:</p> + +<pre> +<!-- A RecyclerView with some commonly used attributes --> +<android.support.v7.widget.RecyclerView + android:id="@+id/my_recycler_view" + android:scrollbars="vertical" + android:layout_width="match_parent" + android:layout_height="match_parent"/> +</pre> + +<p>To get the <code>RecyclerView</code> object in your activity:</p> + +<pre> +public class MyActivity extends ActionBarActivity { + private RecyclerView mRecyclerView; + private RecyclerView.Adapter mAdapter; + private RecyclerView.LayoutManager mLayoutManager; + + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.my_activity); + mRecyclerView = (RecyclerView) findViewById(R.id.my_recycler_view); + + // improve performance if the size is fixed + mRecyclerView.setHasFixedSize(true); + + // use a linear layout manager + mLayoutManager = new LinearLayoutManager(this); + mRecyclerView.setLayoutManager(mLayoutManager); + + // specify an adapter (see also next example) + mAdapter = new MyAdapter(myDataset); + mRecyclerView.setAdapter(mAdapter); + } + ... +} +</pre> + +<p>To create a simple adapter:</p> + +<pre> +public class MyAdapter extends RecyclerView.Adapter<MyAdapter.ViewHolder> { + private String[] mDataset; + + // Provide a reference to the type of views that you are using + // (custom viewholder) + public static class ViewHolder extends RecyclerView.ViewHolder { + public TextView mTextView; + public ViewHolder(TextView v) { + super(v); + mTextView = v; + } + } + + // Provide a suitable constructor (depends on the kind of dataset) + public MyAdapter(String[] myDataset) { + mDataset = myDataset; + } + + // Create new views (invoked by the layout manager) + @Override + public MyAdapter.ViewHolder onCreateViewHolder(ViewGroup parent, + int viewType) { + // create a new view + View v = new TextView(parent.getContext()); + // set the view's size, margins, paddings and layout parameters + ... + ViewHolder vh = new ViewHolder(v); + return vh; + } + + // Replace the contents of a view (invoked by the layout manager) + @Override + public void onBindViewHolder(ViewHolder holder, int position) { + // - get element from your dataset at this position + // - replace the contents of the view with that element + holder.mTextView.setText(mDataset[position]); + + } + + // Return the size of your dataset (invoked by the layout manager) + @Override + public int getItemCount() { + return mDataset.length; + } +} +</pre> + + +<h2 id="cardview">CardView</h2> + +<p><code>CardView</code> extends the <code>FrameLayout</code> class and lets you show information +inside a card with optional rounded corners:</p> + +<ul> + <li>To set the corner radius in your layouts, use the <code>android:cardCornerRadius</code> + attribute.</li> + <li>To set the corner radius in your code, use the <code>CardView.setRadius</code> method.</li> +</ul> + +<p>To set the background color of a card, use the <code>android:cardBackgroundColor</code> +attribute.</p> + +<p>To include a <code>CardView</code> in your layout:</p> + +<pre> +<!-- A CardView that contains a TextView --> +<android.support.v7.widget.CardView + android:id="@+id/card_view" + android:layout_gravity="center" + android:layout_width="200dp" + android:layout_height="200dp" + card_view:cardCornerRadius="4dp"> + + <TextView + android:id="@+id/info_text" + android:layout_width="match_parent" + android:layout_height="match_parent" /> +</android.support.v7.widget.CardView> +</pre>
\ No newline at end of file diff --git a/docs/html/preview/material/videos/ContactsAnim.mp4 b/docs/html/preview/material/videos/ContactsAnim.mp4 Binary files differnew file mode 100644 index 0000000..073f9dc --- /dev/null +++ b/docs/html/preview/material/videos/ContactsAnim.mp4 diff --git a/docs/html/preview/material/videos/ContactsAnim.ogv b/docs/html/preview/material/videos/ContactsAnim.ogv Binary files differnew file mode 100644 index 0000000..c5e751b --- /dev/null +++ b/docs/html/preview/material/videos/ContactsAnim.ogv diff --git a/docs/html/preview/material/videos/ContactsAnim.webm b/docs/html/preview/material/videos/ContactsAnim.webm Binary files differnew file mode 100644 index 0000000..2a15ff5 --- /dev/null +++ b/docs/html/preview/material/videos/ContactsAnim.webm diff --git a/docs/html/preview/material/views-shadows.jd b/docs/html/preview/material/views-shadows.jd new file mode 100644 index 0000000..c5884d6 --- /dev/null +++ b/docs/html/preview/material/views-shadows.jd @@ -0,0 +1,86 @@ +page.title=Views and Shadows + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> +<ol> + <li><a href="#elevation">View Elevation</a></li> + <li><a href="#shadows">Shadows and Outlines</a></li> + <li><a href="#clip">Clipping Views</a></li> +</ol> +</div> +</div> + +<p>In apps with material design, depth has meaning. You should assign higher elevation values to more +important UI elements in your app. The elevation value of a view determines the size of its +shadow: views with higher Z values cast bigger shadows. Views only cast shadows on the Z=0 plane +under an orthographic projection (the views do not scale for different values of Z).</p> + + +<h2 id="elevation">View Elevation</h2> + +<p>The Z value for a view has two components, elevation and translation. The elevation is the +static component, and the translation is used for animations:</p> + +<p><code>Z = elevation + translationZ</code></p> + +<p>To set the elevation of a view:</p> + +<ul> + <li>In a layout definition, use the <code>android:elevation</code> attribute.</li> + <li>In the code of an activity, use the <code>View.setElevation</code> method.</li> +</ul> + +<p>To set the translation of a view, use the <code>View.setTranslationZ</code> method.</p> + +<p>The Z values are measured in the same units as the X and Y values (like <code>dp</code> or +<code>px</code>).</p> + + +<h2 id="shadows">Shadows and Outlines</h2> + +<p>The bounds of a view's background drawable determine the default shape of its shadow. To define +a custom shape for a shadow, such as an oval, use the <code>View.setOutline</code> method:</p> + +<pre> +View v = findViewById(R.id.my_view); + +// add 10px to the static elevation +v.setTranslationZ(10); + +// set an oval shadow +Outline outline = new Outline(); +outline.setOval(v.getLeft(), v.getTop(), v.getRight(), v.getBottom()); +myView.setOutline(outline); +</pre> + +<p>An <code>Outline</code> represents the outer shape of a graphics object. You can create +<code>Outline</code> objects as in this example, or you can obtain the outline from a +<code>Drawable</code> object with the <code>getOutline</code> method.</p> + +<p>The outline of a view also defines the ripple area for touch feedback.</p> + +<p>To prevent a view from casting a shadow, set its outline to <code>null</code>.</p> + + +<h2 id="clip">Clipping Views</h2> + +<p>The Android L Developer Preview lets you clip a view to its outline area using the +<code>View.setClipToOutline</code> method. Only rectangle, circle, and round rectangle outlines +support clipping, as determined by the <code>Outline.canClip</code> method.</p> + +<p>To determine if a view has been clipped, use the <code>View.getClipToOutline</code> method.</p> + +<pre> +// clip a view to an oval +View v = findViewById(R.id.my_view); +outline.setOval(v.getLeft(), v.getTop(), v.getRight(), v.getBottom()); +myView.setOutline(outline); + +// if the view is not already clipped +if (v.getClipToOutline() == false) { + v.setClipToOutline(true); +} +</pre>
\ No newline at end of file diff --git a/docs/html/preview/preview_toc.cs b/docs/html/preview/preview_toc.cs new file mode 100644 index 0000000..5920ecc --- /dev/null +++ b/docs/html/preview/preview_toc.cs @@ -0,0 +1,87 @@ +<ul id="nav"> + + + <li class="nav-section"> + <div class="nav-section-header empty"><a href="<?cs var:toroot ?>preview/setup-sdk.html">Set up the Preview SDK + </a></div> + </li> + <li class="nav-section"> + <div class="nav-section-header empty"><a href="<?cs var:toroot ?>preview/setup-devices.html">Set Up Hardware and AVDs + </a></div> + </li> + <li class="nav-section"> + <div class="nav-section-header empty"><a href="<?cs var:toroot ?>preview/api-overview.html">API Overview + </a></div> + </li> + <li class="nav-section"> + + <div class="nav-section-header"><a href="<?cs var:toroot ?>preview/material/index.html">Material Design + </a></div> + <ul> + <li><a href="<?cs var:toroot ?>preview/material/get-started.html">Get Started</a></li> + <li><a href="<?cs var:toroot ?>preview/material/theme.html">Material Theme</a></li> + <li><a href="<?cs var:toroot ?>preview/material/ui-widgets.html">UI Widgets</a></li> + <li><a href="<?cs var:toroot ?>preview/material/views-shadows.html">Views and Shadows</a></li> + <li><a href="<?cs var:toroot ?>preview/material/animations.html">Animations</a></li> + <li><a href="<?cs var:toroot ?>preview/material/compatibility.html">Compatibility</a></li> + </ul> + </li> + + <li class="nav-section"> + <div class="nav-section-header"> + <a href="<?cs var:toroot ?>preview/tv/index.html">TV</a> + </div> + <ul> + <li><a href="<?cs var:toroot ?>preview/tv/start/index.html"> + Get Started</a></li> + <li class="nav-section"> + <div class="nav-section-header"> + <a href="<?cs var:toroot ?>preview/tv/ui/index.html"> + User Interface</a></div> + <ul> + <li><a href="<?cs var:toroot ?>preview/tv/ui/layouts.html"> + Layouts</a></li> + <li><a href="<?cs var:toroot ?>preview/tv/ui/navigation.html"> + Navigation</a></li> + <li><a href="<?cs var:toroot ?>preview/tv/ui/browse.html"> + BrowseFragment</a></li> + <li><a href="<?cs var:toroot ?>preview/tv/ui/details.html"> + DetailsFragment</a></li> + <li><a href="<?cs var:toroot ?>preview/tv/ui/in-app-search.html"> + In-App Search</a></li> + <li><a href="<?cs var:toroot ?>preview/tv/ui/recommendations.html"> + Recommendations</a></li> + </ul> + </li> + <li><a href="<?cs var:toroot ?>preview/tv/games/index.html"> + Games on TV</a></li> + <li><a href="<?cs var:toroot ?>preview/tv/start/hardware-features.html"> + Hardware Features</a></li> + <li><a href="<?cs var:toroot ?>preview/tv/adt-1/index.html"> + ADT-1</a></li> + </ul> + </li> + + <li class="nav-section"> + <div class="nav-section-header empty"> + <a href="<?cs var:toroot ?>preview/samples.html">Samples</a> + </div> + </li> + <li class="nav-section"> + <div class="nav-section-header empty"> + + <a href="<?cs var:toroot ?>preview/l-developer-preview-reference.zip">Reference</a> + + </div> + </li> + <li class="nav-section"> + <div class="nav-section-header empty"> + <a href="<?cs var:toroot ?>preview/support.html">Support</a> + </div> + </li> + <li class="nav-section"> + <div class="nav-section-header empty"> + <a href="<?cs var:toroot ?>preview/tos.html">Terms of Service</a> + </div> + </li> +</ul> diff --git a/docs/html/preview/samples.jd b/docs/html/preview/samples.jd new file mode 100644 index 0000000..67404b6 --- /dev/null +++ b/docs/html/preview/samples.jd @@ -0,0 +1,16 @@ +page.title=Samples + +@jd:body + +<p>The code samples for the L Developer Preview are available in the Android SDK Manager under the +L Preview section. Here is a summary of everything that is available:</p> + +<ul> + <li></li> + <li></li> + <li></li> + <li></li> + <li></li> + <li></li> + <li></li> + </ul> diff --git a/docs/html/preview/setup-devices.jd b/docs/html/preview/setup-devices.jd new file mode 100644 index 0000000..86e4845 --- /dev/null +++ b/docs/html/preview/setup-devices.jd @@ -0,0 +1,90 @@ +page.title=Setting Up Hardware and AVDs +@jd:body + +<p>The Android L developer preview provides you with 32-bit system images +to flash the following devices: +</p> + +<ul> + <li>Nexus 5</li> + <li>Nexus 7 Wi-Fi (version 2, released in 2013)</li> +</ul> + +<p>In addition, you also get the emulator system images, which includes +experimental 64-bit system images along with standard 32-bit system images. +</p> + +<h2>Installing the L Preview System Image</h2> + +<!-- Will we get an official warning text from the lawyercats? Is this it? --> +<p class="warning"><b>Warning</b>: This is a preview version of the Android +system image, and is subject to change. Your use of this system image is +governed by the Android SDK Preview License Agreement. The Android preview +system image is not a stable release, and may contain errors and defects that +can result in damage to your computer systems, devices, and data. The preview +Android system image is not subject to the same testing as the factory OS and +can cause your phone and installed services and applications to stop working. +</p> + + +<ol> + <li>Download and extract the Android Developer Preview package to a directory + (which we'll call <code><l_download_dir></code> in these + instructions).</li> + <li>Connect your powered-off Android device to your development machine. Put + the device in fastboot mode by pressing and holding the following buttons: + <ul> + <li><strong>Nexus 5:</strong> <i>volume down</i> + <i>volume up</i> + + <i>power</i></li> + <li><strong>Nexus 7:</strong> <i>volume down</i> + <i>power</i> </li> + </ul> + <p class="note">Alternatively, you can enter fastboot mode by booting up + the device and running <code>adb reboot bootloader</code> with USB debugging + turned on.</p> + </li> + <li>Follow the instructions at + <a href="https://developers.google.com/android/nexus/images#instructions">developers.google.com/android</a> + to set up your system for flashing devices.</li> + <li>Run the <code><l_download_dir>/flash-all</code> script + corresponding to your platform. This script flashes all of the system data + onto the phone.</li> <!-- Confirm names of flash scripts --> + <li>(Optional) After flashing is complete, lock your device's bootloader by + putting it in fastboot mode and running <code>fastboot oem lock</code>. + (This does not wipe your device.) Once you do this, you will not be able to + flash your device until you run run <code>fastboot oem unlock</code>, + which unlocks the bootloader and wipes your device. We recommend you leave the + bootloader unlocked until you are done with flashing the device.</li> +</ol> + +<h3>Reverting a Device to Factory Specifications</h3> + + <p>If you want to uninstall the L Preview and revert the device to factory +specifications, go to <a href="http://developers.google.com/android +/nexus/images">developers.google.com/android</a> and download the image you want +to flash to for your device. Follow the instructions on that page to flash the +image to your device.</p> + + +<h2>Setting up an AVD</h2> + +<p>You can set up <a href="{@docRoot}tools/devices/">Android Virtual Devices +(AVD)</a> and use the emulator to build and test apps with the L Preview.</p> + +<p>To create an AVD with the AVD Manager:</p> + +<ol> + <li>Install the L Preview SDK in your development environment, as described + in <a href="{@docRoot}preview/setup-sdk.html">Setting Up the Preview + SDK.</a></li> + <li>Follow the steps in + <a href="{@docRoot}tools/devices/managing-avds.html">Managing AVDs with AVD + Manager</a>. Use the following settings: + <ul> + <li><b>Device:</b> Either Nexus 5 or Nexus 7</li> + <li><b>Target:</b> <!-- Confirm exact text when we have final distro --> + Android L (Preview) - API Level L</li> + </ul> + <!-- Confirm this works when you can download image through SDK manager! --> + </li> +</ol> + diff --git a/docs/html/preview/setup-sdk.jd b/docs/html/preview/setup-sdk.jd new file mode 100644 index 0000000..32a33b6 --- /dev/null +++ b/docs/html/preview/setup-sdk.jd @@ -0,0 +1,36 @@ +page.title=Setting Up the Preview SDK +@jd:body + +<p>The Preview SDK is available from the Android SDK Manager. <!-- Not yet! --> +This document assumes that you are familiar with Android app development, such +as using the Android SDK Manager and creating projects. If you're new to +Android, see <a href="/training/basics/firstapp/index.html">Building Your First +App</a> training lesson first.</a></p> + +<h2>Download the SDK</h2> + +<ol> + <li>Start the Android SDK Manager.</li> + <li>In the <b>Tools</b> section, select the latest Android <b>SDK Tools</b>, + <b>Platform-tools</b>, and <b>Build-tools</b>.</li> + <!-- Android L not yet showing up in Android SDK Manager... --> + <li>Select everything under the <b>Android L Developer Preview</b> section and + click <b>Install packages...</b></li> + <li>Accept the Licensing Agreement for all of the packages and click + <b>Install</b>.</li> +</ol> + +<h2>Set up your environment</h2> + +<ol> + <li>Create a new Android project with the following properties: + <ul> + <li>Minimum SDK Version: L</li> + <li>Target SDK Version: L</li> + <li>Build Target: L</li> + </ul> + </li> + <li>Choose the theme <code>Theme.Material</code> + <!-- put in name as it appears in Eclipse menu? --> + +</ol> diff --git a/docs/html/preview/support.jd b/docs/html/preview/support.jd new file mode 100644 index 0000000..23ce6ff --- /dev/null +++ b/docs/html/preview/support.jd @@ -0,0 +1,22 @@ +page.title=Support + +@jd:body + +<p>If you've encountered bugs or have feedback about the L Developer Preview, create +an issue on our bug tracker</p> + +<p>Go to the Bug Tracker</p> + +<h2>Release Notes</h2> + +<p>June 25, 2014 - Initial Release of the L Developer Preview</p> + +<ul> + <li></li> + <li></li> + <li></li> + <li></li> + <li></li> + <li></li> + <li></li> + </ul> diff --git a/docs/html/preview/tos.jd b/docs/html/preview/tos.jd new file mode 100644 index 0000000..602439f --- /dev/null +++ b/docs/html/preview/tos.jd @@ -0,0 +1,9 @@ +page.title=License Agreement + +@jd:body + +<p><!-- Will this link change before we publish (to a clean version of the doc)? + Or will we scrub the doc's comments & revision history? --> +<a href="https://docs.google.com/a/google.com/document/d/1OixnM1Q890ExOzDB3Z-FDD6Sb2kF4uZQiMxsYVII8F0/edit?usp=sharing">L +Preview Terms of Service</a> +</p>
\ No newline at end of file |
