diff options
Diffstat (limited to 'docs/html/preview')
76 files changed, 5814 insertions, 0 deletions
diff --git a/docs/html/preview/api-overview.jd b/docs/html/preview/api-overview.jd new file mode 100644 index 0000000..f992bf9 --- /dev/null +++ b/docs/html/preview/api-overview.jd @@ -0,0 +1,907 @@ +page.title=API Overview +excludeFromSuggestions=true +sdk.platform.apiLevel=20 +@jd:body + + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>In this document + <a href="#" onclick="hideNestedItems('#toc44',this);return false;" class="header-toggle"> + <span class="more">show more</span> + <span class="less" style="display:none">show less</span></a></h2> + +<ol id="toc44" class="hide-nested"> + <li><a href="#Behaviors">Important Behavior Changes</a> + <ol> + <li><a href="#ART">New Android Runtime (ART)</a></li> + <li><a href="#BehaviorNotifications">If your app implements notifications...</a></li> + <li><a href="#BehaviorMediaControl">If your app uses RemoteControlClient...</a></li> +<li><a href="#BehaviorGetRecentTasks">If your app uses ActivityManager.getRecentTasks()...</a></li> + </ol> + </li> + <li><a href="#UI">User Interface</a> + <ol> + <li><a href="#MaterialDesign">Material design support</a></li> + <li><a href="#LockscreenNotifications">Lockscreen notifications</a></li> + <li><a href="#NotificationsMetadata">Notifications metadata</a></li> + <li><a href="#Recents">Concurrent documents and activities in the Recents screen</a></li> + <li><a href="#WebView">WebView updates</a></li> + </ol> + </li> + <li><a href="#Graphics">Graphics</a> + <ol> + <li><a href="#OpenGLES-3-1">Support for OpenGL ES 3.1</a></li> + <li><a href="#AndroidExtensionPack">Android Extension Pack</a></li> + </ol> + </li> + <li><a href="#Multimedia">Multimedia</a> + <ol> + <li><a href="#Camera-v2">Camera API for advanced camera capabilities</a></li> + <li><a href="#AudioPlayback">Audio playback</a></li> + <li><a href="#MediaPlaybackControl">Media playback control</a></li> + </ol> + </li> + <li><a href="#Storage">Storage</a> + <ol> + <li><a href="#DirectorySelection">Directory selection</a></li> + </ol> + </li> + <li><a href="#Wireless">Wireless and Connectivity</a> + <ol> + <li><a href="#Multinetwork">Multiple network connections</a></li> + <li><a href="#BluetoothBroadcasting">Bluetooth broadcasting</a></li> + <li><a href="#NFCEnhancements">NFC enhancements</a></li> + </ol> + </li> + <li><a href="#Power">Power Efficiency</a> + <ol> + <li><a href="#JobScheduler">Scheduling Jobs</a></li> + <li><a href="#PowerMeasurementTools">Developer tools for power measurement</a> + </ol> + </li> + <li><a href="#Enterprise">Enterprise</a> + <ol> + <li><a href="#ManagedProvisioning">Managed provisioning</a></li> + <li><a href="#TaskLocking">Task locking</a></li> + </ol> + </li> + <li><a href="#Printing">Printing Framework</a> + <ol> + <li><a href="#PDFRender">Render PDF as bitmap</a></li> + </ol> + </li> + <li><a href="#TestingA11y">Testing & Accessibility</a> + <ol> + <li><a href="#TestingA11yImprovements">Testing and accessibility improvements</a></li> + </ol> + </li> + <li><a href="#IME">IME</a> + <ol> + <li><a href="#Switching">Easier switching between input languages</a></li> + </ol> + </li> + <li><a href="#Manifest">Manifest Declarations</a> + <ol> + <li><a href="#ManifestFeatures">Declarable required features</a></li> + </ol> + </li> +</ol> + +</div> +</div> + +<p>The L Developer Preview gives you an advance look at the upcoming release +for the Android platform, which offers new features for users and app +developers. This document provides an introduction to the most notable APIs.</p> + +<p>The L Developer Preview is intended for <strong>developer early +adopters</strong> and <strong>testers</strong>. If you are interested in +influencing the direction of the Android framework, +<a href="{@docRoot}preview/setup-sdk.html">give the L Developer Preview a +try</a> and send us your feedback!</p> + +<p class="caution"><strong>Caution:</strong> Do not not publish apps +that use the L Developer Preview to the Google Play store.</p> + +<p class="note"><strong>Note:</strong> This document often refers to classes and +methods that do not yet have reference material available on <a +href="{@docRoot}">developer.android.com</a>. These API elements are +formatted in {@code code style} in this document (without hyperlinks). For the +preliminary API documentation for these elements, download the <a +href="{@docRoot}preview/l-developer-preview-reference.zip">preview +reference</a>.</p> + +<h2 id="Behaviors">Important Behavior Changes</h2> + +<p>If you have previously published an app for Android, be aware that your app + might be affected by changes in the upcoming release.</p> + +<h3 id="ART">New Android Runtime (ART)</h3> + +<p>The 4.4 release introduced a new, experimental Android runtime, ART. Under +4.4, ART was optional, and the default runtime remained Dalvik. With the L +Developer Preview, ART is now the default runtime.</p> + +<p>For an overview of ART's new features, see +<a href="https://source.android.com/devices/tech/dalvik/art.html">Introducing +ART</a>. Some of the major new features are:</p> + +<ul> + <li>Ahead-of-Time (AOT) compilation</li> + <li>Improved garbage collection (GC)</li> + <li>Improved debugging support</li> +</ul> + +<p>Most Android apps should just work without change under ART. However, some +techniques that work on Dalvik do not work on ART. For information about the +most important issues, see +<a href="{@docRoot}guide/practices/verifying-apps-art.html">Verifying App +Behavior on the Android Runtime (ART)</a>. Pay particular attention if:</p> + +<ul> + <li>Your app uses Java Native Interface (JNI) to run C/C++ code.</li> + <li>You use development tools that generate non-standard code (such as some + obfuscators).</li> + <li>You use techniques that are incompatible with compacting garbage + collection. (ART does not currently implement compacting GC, but + compacting GC is under development in the Android Open-Source + Project.)</li> +</ul> + +<h3 id="BehaviorNotifications">If your app implements notifications...</h3> + +<p>Notifications are drawn with dark text atop white (or very light) +backgrounds to match the new material design widgets. Make sure that all your +notifications look right with the new color scheme:</p> + +<div class="figure" style="width:320px"> + <img src="images/hun-example.png" + srcset="images/hun-example@2x.png 2x" + alt="" width="320" height="541" id="figure1" /> + <p class="img-caption"> + <strong>Figure 1.</strong> Fullscreen activity showing a heads-up notification + </p> +</div> + +<ul> + + <li>Update or remove assets that involve color.</li> + + <li>The system automatically inverts action icons in notifications. Use + {@code android.app.Notification. Builder.setColor()} to set an accent color + in a circle behind your {@link android.app.Notification#icon} image.</li> + + <li>The system ignores all non-alpha channels in action icons and the main + notification icon. You should assume that these icons are alpha-only.</li> + +</ul> + +<p>If you are currently adding sounds and vibrations to your notifications by +using the {@link android.media.Ringtone}, {@link android.media.MediaPlayer}, +or {@link android.os.Vibrator} classes, remove this code so that +the system can present notifications correctly in Do +not Disturb mode. Instead, use the {@link android.app.Notification.Builder} +methods instead to add sounds and vibration.</p> + +<p>Notifications now appear in a small floating window +(also called a <em>heads-up notification</em>) when the device is active +(that is, the device is unlocked and its screen is on). These notifications +appear similar to the compact form of your notification, except that the +heads-up notification also shows action buttons. Users can act on, or dismiss, +a heads-up notification without leaving the current app.</p> + +<p>Examples of conditions that may trigger heads-up notifications include:</p> + +<ul> + <li>The user's activity is in fullscreen mode (the app uses +{@link android.app.Notification#fullScreenIntent}), or</li> + <li>The notification has high priority and uses ringtones or + vibrations</li> +</ul> + +<p>If your app implements notifications under those scenarios, make sure that +heads-up notifications are presented correctly.</p> + +<h3 id="BehaviorMediaControl">If your app uses RemoteControlClient...</h3> + +<p>Lockscreens in the L Developer Preview do not show transport controls for +your {@link android.media.RemoteControlClient}. Instead, your app can provide +media playback control from the lockscreen through a notification. This +gives your app more control over the presentation of media buttons, while +providing a consistent experience for users across the lockscreen and +unlocked device.</p> + +<p>The L Developer Preview introduces a new +{@code android.app.Notification.MediaStyle} template which is recommended for +this purpose. {@code MediaStyle} converts notification actions that you added +with +{@link android.app.Notification.Builder#addAction(int, java.lang.CharSequence, + android.app.PendingIntent) +Notification.Builder.addAction()} into compact buttons embedded in your app's +media playback notifications.</p> + +<p>If you are using the new +{@code android.media.session.MediaSession} class +(see <a href="#MediaPlaybackControl">Media Playback Control</a> below), attach +your session token with {@code Notification.MediaStyle.setMediaToken()} to +inform the system that this notification controls an ongoing media session.</p> + +<p>Call {@code +Notification.Builder.setVisibility(Notification.VISIBILITY_PUBLIC)} to mark a +notification as safe to show atop any lockscreen (secure or otherwise). For more +information, see <a href="#LockscreenNotifications">Lockscreen Notifications</a>.</p> + +<h3 id="BehaviorGetRecentTasks">If your app uses ActivityManager.getRecentTasks()...</h3> + +<p>With the introduction of the new <em>concurrent documents and activities +tasks</em> feature in the upcoming release (see <a href="#Recents">Concurrent +documents and activities in Recents screen</a> below), +the {@link android.app.ActivityManager#getRecentTasks +ActivityManager.getRecentTasks()} method is now deprecated to improve user +privacy. For backward compatibility, this method still returns a small subset of +its data, including the calling application’s own tasks and possibly some other +non-sensitive tasks (such as Home). If your app is using this method to retrieve +its own tasks, use {@code android.app.ActivityManager.getAppTasks()} instead to +retrieve that information.</p> + +<h2 id="UI">User Interface</h2> + +<h3 id="MaterialDesign">Material design support</h3> + +<p>The upcoming release adds support for Android's new <em>material</em> design +style. You can create apps with material design that are visually dynamic and +have UI element transitions that feel natural to users. This support includes:</p> + +<ul> + + <li>The material theme</li> + <li>View shadows</li> + <li>The {@code RecyclerView} widget</li> + <li>Drawable animation and styling effects</li> + <li>Material design animation and activity transition effects</li> + <li>Animators for view properties based on the state of a view</li> + <li>Customizable UI widgets and app bars with color palettes that you control</li> +</ul> + +<p>To learn more about adding material design functionality to your app, see +<a href="{@docRoot}preview/material/index.html">Material Design</a>.</p> + +<h3 id="LockscreenNotifications">Lockscreen notifications</h3> +<p>Lockscreens in the L Developer Preview have the ability to present +notifications. Users can choose via <em>Settings</em> whether to allow +sensitive notification content to be shown over a secure lockscreen.</p> + +<p>Your app can control the level of detail visible when its notifications are +displayed over the secure lockscreen. To control the visibility level, call +{@code android.app.Notification.Builder.setVisibility()} and specify one of these +values:</p> + +<ul> +<li>{@code VISIBILITY_PRIVATE}. Shows basic information, such as the +notification’s icon, but hides the notification’s full content.</li> +<li>{@code VISIBILITY_PUBLIC}. Shows the notification’s full content.</li> +<li>{@code VISIBILITY_SECRET}. Shows nothing, excluding even the +notification’s icon.</li> +</ul> + +<p>When {@code VISIBILITY_PRIVATE} is set, you can also provide a redacted +version of the notification content that hides personal details. For example, +an SMS app might display a notification that shows "You have 3 new text messages." +but hides the message content and senders. To provide this alternative +notification, first create the replacement notification using +{@link android.app.Notification.Builder}. When you create the private +notification object, attach the replacement notification to it through the +{@code Notification.Builder.setPublicVersion()} method.</p> + +<h3 id="NotificationsMetadata">Notifications metadata</h3> +<p>The L Developer Preview uses metadata associated with your app notifications +to sort the notifications more intelligently. To set the metadata, call the +following methods in {@code android.app.Notification.Builder} when you +construct the notification:</p> + +<ul> +<li>{@code setCategory()}. Depending on the message category, this tells +the system how to handle your app notifications when the device is +in <em>Do not Disturb</em> mode (for example, if your notification represents an +incoming call, instant message, or alarm). +<li>{@code setPriority()}. Notifications with the priority field set to +{@code PRIORITY_MAX} or {@code PRIORITY_HIGH} will appear in a small floating +window if the notification also has sound or vibration.</li> +<li>{@code addPerson()}. Allows you to add a list of people to a notification. +Your app can use this to signal to the system that it should group together +notifications from the specified people, or rank notifications from these +people as being more important.</li> +</ul> + +<h3 id="Recents">Concurrent documents and activities in the Recents screen</h3> + +<p>In previous releases, the +<a href="{@docRoot}design/get-started/ui-overview.html">Recents screen</a> +could only display a single task for each app that the user interacted with +most recently. Now your app can open more tasks as +needed for additional concurrent activities for documents. +This feature facilitates multitasking by letting users quickly switch between +individual activities and documents from the Recents screen, with a consistent +switching experience across all apps. +Examples of such concurrent tasks might include open tabs in a web +browser app, documents in a productivity app, concurrent matches in +a game, or chats in a messaging app. Your app can manage its tasks +through the {@code android.app.ActivityManager.AppTask} class.</p> + +<p>To insert a logical break so that the system treats your activity as a new +task, use {@code android.content.Intent.FLAG_ACTIVITY_NEW_DOCUMENT} when +launching the activity with {@link android.app.Activity#startActivity(android.content.Intent) +startActivity()}. You can also get this behavior by declaring the +<a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a> +attribute {@code documentLaunchMode="intoExisting"} or {@code ="always"} in your +manifest.</p> + +<p>You can also mark that a task should be removed from the Recents screen +when all its activities are closed. To do this, use {@code +android.content.Intent.FLAG_ACTIVITY_AUTO_REMOVE_FROM_RECENTS} when starting the +root activity for +the task. You can also set this behavior for an activity by declaring the +<a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a> +attribute {@code autoRemoveFromRecents=“true”} in your manifest.</p> + +<p>To avoid cluttering the Recents screen, you can set the maximum number of +tasks from your app that can appear in that screen. To do this, set the +<a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a> +attribute {@code android:maxRecent}. The current maximum that can be specified +is 100 tasks per user.</a></p> + +<h3 id="WebView">WebView updates</h3> +<p>The L Developer Preview updates the {@link android.webkit.WebView} +implementation to Chromium M36, bringing security and stability enhancements, +as well as bug fixes. The default user-agent string for a +{@link android.webkit.WebView} running on the L Developer Preview has +been updated to incorporate 36.0.0.0 as the version number.</p> + +<p>Additionally, this release brings support for the +<a href="http://webaudio.github.io/web-audio-api/" class="external-link">WebAudio</a>, +<a href="https://www.khronos.org/webgl/" class="external-link">WebGL</a>, and +<a href="http://www.webrtc.org/" class="external-link">WebRTC</a> open standards. To learn more about +the new features included in this release, see <a href="https://developer.chrome.com/multidevice/webview/overview" class="external-link">WebView for Android</a>.</p> + +<h2 id="Graphics">Graphics</h2> + +<h3 id="OpenGLES-3-1">Support for OpenGL ES 3.1</h3> +<p>The L Developer Preview adds Java interfaces and native support for OpenGL +ES 3.1. Key new functionality provided in OpenGL ES 3.1 includes:</p> + +<ul> +<li>Compute shaders +<li>Separate shader objects +<li>Indirect draw commands +<li>Multisample and stencil textures +<li>Shading language improvements +<li>Extensions for advanced blend modes and debugging +<li>Backward compatibility with OpenGL ES 2.0 and 3.0 +</ul> + +<p>The Java interface for OpenGL ES 3.1 on Android is provided with {@code GLES31}. When +using OpenGL ES 3.1, be sure that you declare it in your manifest file with the +<a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> +tag and the {@code android:glEsVversion} attribute. For example:</p> + +<pre> +<manifest> + <uses-feature android:glEsVersion="0x00030001" /> + ... +</manifest> +</pre> + +<p>For more information about using OpenGL ES, including how to check the +device’s supported OpenGL ES version at runtime, see the +<a href="{@docRoot}guide/topics/graphics/opengl.html">OpenGL ES API guide</a>.</p> + +<h3 id="AndroidExtensionPack">Android Extension Pack</h3> + +<p>In addition to OpenGL ES 3.1, this release provides an extension pack with Java interfaces and +native support for advanced graphics functionality. These extensions are treated as a single +package by Android. (If the {@code ANDROID_extension_pack_es31} extension is present, your app can +assume all extensions in the package are present and enable the shading language features with +a single {@code #extension} statement.</p> +<p>The extension pack supports:</p> +<ul> +<li>Guaranteed fragment shader support for shader storage buffers, images, and + atomics (fragment shader support is optional in OpenGL ES 3.1.)</li> +<li>Tessellation and geometry shaders</li> +<li>ASTC (LDR) texture compression format</li> +<li>Per-sample interpolation and shading</li> +<li>Different blend modes for each color attachment in a frame buffer</li> +</ul> + +<p>The Java interface for the extension pack is provided with {@code GLES31Ext}. +In your app manifest, you can declare that support for the extension pack is +required, with the +<a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> +tag, but the precise syntax is not finalized in the L Developer Preview.</p> + +<h2 id="Multimedia">Multimedia</h2> + +<h3 id="Camera-v2">Camera API for advanced camera capabilities</h3> + +<p>The L Developer Preview introduces the new {@code android.hardware.camera2} +API to facilitate fine-grain photo capture and image processing. You can now +programmatically access the camera devices available to the system with {@code +CameraManager.getCameraIdList()} and connect to a specific device with {@code +CameraManager.openCamera()}. To start capturing images, create a {@code +CameraCaptureSession} and specify the {@link android.view.Surface} objects for +the captured images. The {@code CameraCaptureSession} can be configured to take +single shots or multiple images in a burst.</p> + +<p>To be notified when new images are captured, implement the +{@code CameraCaptureSession.CaptureListener()} interface and set it in your +capture request. Now when the system completes the image capture request, your +{@code CameraCaptureSession.CaptureListener()} receives a call to +{@code onCaptureCompleted()}, providing you with the image capture metadata in a +{@code CaptureResult}.</p> + +<p>To see an example of how to use the updated Camera API, refer to the {@code Camera2Basic} +and {@code Camera2Video} implementation samples in this release.</p> + +<h3 id="AudioPlayback">Audio playback</h3> +<p>This release includes the following changes to + {@link android.media.AudioTrack}:</p> +<ul> + <li>Your app can now supply audio data in floating-point format +({@code android.media.AudioFormat.ENCODING_PCM_FLOAT}). This permits greater +dynamic range, more consistent precision, and greater headroom. Floating-point +arithmetic is especially useful during intermediate calculations. Playback +end-points use integer format for audio data, and with lower bit-depth. (In the +L Developer Preview, portions of the internal pipeline are not yet +floating-point.) + <li>Your app can now supply audio data as a {@link java.nio.ByteBuffer}, in +the same format as provided by {@link android.media.MediaCodec}. + <li>The {@code WRITE_NON_BLOCKING} option can simplify buffering and + multithreading for some apps. +</ul> + +<h3 id="MediaPlaybackControl">Media playback control</h3> +<p>You can now build your own media controller app with the new +{@code android.media.session.MediaController} class, which provides +simplified transport controls APIs that replace those in +{@link android.media.RemoteControlClient}. The {@code MediaController} class +allows thread-safe control of playback from a non-UI process, making it easier +to control your media playback service from your app’s user interface. + +<p>You can also create multiple controllers to send playback commands, +media keys, and other events to the same ongoing +{@code android.media.session.MediaSession}. When you add a controller, you must +call {@code MediaSession.getSessionToken()} to request an access +token in order for your app to interact with the session.</p> + +<p>You can now send transport commands such as "play", "stop", "skip", and +"set rating" by using {@code MediaController.TransportControls}. To handle +in-bound media transport commands from controllers attached to the session, +override the callback methods in +{@code MediaSession.TransportControlsCallback}.</p> + +<p>You can also create rich notifications that allow playback control tied to a +media session with the new {@code android.app.Notification.MediaStyle} class. By +using the new notification and media APIs, you will ensure that the System UI +knows about your playback and can extract and show album art.</p> + +<h2 id="Storage">Storage</h2> + +<h3 id="DirectorySelection">Directory selection</h3> + +<p>The L Developer Preview extends the <a href="{@docRoot}guide/topics/providers/document-provider.html">Storage Access Framework</a> to let users select an entire directory subtree, +giving apps read/write access to all contained documents without requiring user +confirmation for each item.</p> + +<p>To select a directory subtree, build and send an +{@code android.intent.action.OPEN_DOCUMENT_TREE} {@link android.content.Intent}. +The system displays all +{@link android.provider.DocumentsProvider} instances that support subtree selection, +letting the user browse and select a directory. The returned URI represents access to the selected +subtree. You can then use {@code DocumentsContract.buildChildDocumentsUriUsingTree()} +and {@code DocumentsContract.buildDocumentUriUsingTree()} along with +{@code ContentResolver.query()} to explore the subtree.</p> + +<p>The new {@code DocumentsContract.createDocument()} method lets you create +new documents or directories anywhere under the subtree. To manage +existing documents, use {@code DocumentsContract.renameDocument()} and +{@code DocumentsContract.deleteDocument()}. Check {@code DocumentsContract.Document.COLUMN_FLAGS} +to verify provider support for these calls before issuing them.</p> + +<p>If you're implementing a {@link android.provider.DocumentsProvider} and want +to support subtree selection, implement {@code DocumentsProvider.isChildDocument()} +and include {@code Documents.Contract.FLAG_SUPPORTS_IS_CHILD} in your +{@code Root.COLUMN_FLAGS}.</p> + +<p>The L Developer Preview also introduces new package-specific directories on +shared storage where your app can place media files for inclusion in +{@link android.provider.MediaStore}. The new +{@code android.content.Context.getExternalMediaDirs()} returns paths to these +directories on all shared storage devices. Similarly to +{@link android.content.Context#getExternalFilesDir(java.lang.String) Context.getExternalFilesDir()}, +no additional permissions are needed by your app to access the returned paths. The +platform periodically scans for new media in these directories, but you can also +use {@link android.media.MediaScannerConnection} to explicitly scan for new +content.</p> + +<h2 id="Wireless">Wireless & Connectivity</h2> + +<h3 id="Multinetwork">Multiple network connections</h3> +<p>The L Developer Preview provides new multi-networking APIs. These let your app +dynamically scan for available networks with specific capabilities, and +establish a connection to them. This is useful when your app requires a +specialized network, such as an SUPL, MMS, or carrier-billing network, or if +you want to send data using a particular type of transport protocol.</p> + +<p>To select and connect to a network dynamically from your app follow these +steps:</p> + +<ol> + <li>Create a {@link android.net.ConnectivityManager}.</li> + <li>Create a + {@code android.net.NetworkRequest} to specify the network features and transport + type your app is interested in.</li> + <li>To scan for suitable networks, call + {@code ConnectivityManager.requestNetwork()} or + {@code ConnectivityManager.registerNetworkCallback()}, and pass in the + {@code NetworkRequest} object and an implementation of + {@code ConnectivityManager.NetworkCallbackListener}.</li> + +</ol> + +<p>When the system detects a suitable network, it connects to the network and +invokes the {@code NetworkCallbackListener.onAvailable()} callback. You can use +the {@code android.net.Network} object from the callback to get additional +information about the network, or to direct traffic to use the selected +network.</p> + +<h3 id="BluetoothBroadcasting">Bluetooth broadcasting</h3> +<p>Android 4.3 introduced platform support for + <a href="{@docRoot}guide/topics/connectivity/bluetooth-le.html">Bluetooth Low Energy</a> +(BLE) in the central role. In the L Developer Preview, an Android device can now +act as a Bluetooth LE <em>peripheral device</em>. Apps can use this capability +to make their presence known to +nearby devices. For instance, you can build apps that allow a device to +function as a pedometer or health monitor and communicate its data with another +BLE device.</p> + +<p>The new {@code android.bluetooth.le} APIs enable your apps to broadcast +advertisements, scan for responses, and form connections with nearby BLE devices. +You must add the {@code android.permission.BLUETOOTH_ADMIN} permission in your +manifest in order for your app to use the new advertising and scanning features.</a> + +<p>To begin Bluetooth LE advertising so that other devices can discover +your app, call {@code android.bluetooth.le.BluetoothAdvertiser.startAdvisertising()} +and pass in an implementation of the +{@code android.bluetooth.le.AdvertiseCallback} class. The callback object +receives a report of the success or failure of the advertising operation.</p> + +<p> The L Developer Preview introduces the {@code +android.bluetooth.le.ScanFilter} class so that your app can scan for only the +specific types of devices it is interested in. To begin scanning for Bluetooth +LE devices, call {@code android.bluetooth.le.BluetoothLeScanner.startScan()} and +pass in a list of filters. In the method call, you must also provide an +implementation of {@code android.bluetooth.le.ScanCallback} to report if a +Bluetooth LE advertisement is found. </p> + +<h3 id="NFCEnhancements">NFC enhancements</h3> +<p>The L Developer Preview adds these enhancements to enable wider and more +flexible use of NFC:</p> + +<ul> +<li>Android Beam is now available in the share menu. +<li>Your app can invoke the Android Beam on the user’s device to share data by +calling {@code android.nfc.NfcAdapter.invokeBeam()}. This avoids the need for +the user to manually tap the device against another NFC-capable device to +complete the data transfer. +<li>You can use the new {@code android.nfc.NdefRecord.createTextRecord()} method +to create an NDEF record containing UTF-8 text data. +<li>If you are developing a payment app, you now have the ability to +register an NFC application ID (AID) dynamically by calling +{@code android.nfc.cardemulation.CardEmulation.registerAidsForService()}. +You can also use {@code android.nfc.cardemulation.CardEmulation.setPreferredService()} +to set the preferred card emulation service that should be used when a specific +activity is in the foreground. +</ul> + +<h2 id="Power">Power Efficiency</h2> + +<h3 id="JobScheduler">Scheduling jobs</h3> +<p>The L Developer Preview provides a new {@code android.app.job.JobScheduler} +API that lets you optimize battery life by defining jobs for the system to run +asynchronously at a later time or under specified conditions (such as when the +device is charging). This is useful in such situations as:</p> +<ul> + <li>The app has non-user-facing work that you can defer.</li> + <li>The app has work you'd prefer to do when the unit is plugged in.</li> + <li>The app has a task that requires network access (or requires a Wi-Fi + connection).</li> + <li>The app has a number of tasks that you want to run as a batch on a regular + schedule.</li> + +</ul> + +<p>A unit of work is encapsulated by a {@code android.app.job.JobInfo} object. +This object provides an exact description of the criteria to be used for +scheduling.</p> + +<p>Use the {@code android.app.job.JobInfo.Builder} to configure how the +scheduled task should run. You can schedule the task to run under specific +conditions, such as:</p> + +<ul> + <li>The device is charging</li> + <li>The device is connected to an unmetered network</li> + <li>The system deems the device to be idle</li> + <li>Completion with a minimum delay or within a specific deadline.</li> +</ul> + +<p>For example, you can add code like this to run your task on an +unmetered network:</p> + +<pre> +JobInfo uploadTask = new JobInfo.Builder(mJobId, mServiceComponent) + .setRequiredNetworkCapabilities(JobInfo.NetworkType.UNMETERED) + .build(); + +JobScheduler jobScheduler = + (JobScheduler) context.getSystemService(Context.JOB_SCHEDULER_SERVICE) +jobScheduler.schedule(uploadTask); +</pre> + +<p>To see an example of how to use the {@code JobScheduler} API, refer to the +{@code JobSchedulerSample} implementation sample in this release.</p> + +<h3 id="PowerMeasurementTools">Developer tools for power measurement</h3> +<p>The L Developer Preview provides several new developer tools and APIs to help +you better measure and understand your app's power usage.</p> + +<dl> +<dt><strong>batterystats</strong></dt> +<dd> +<p>The {@code dumpsys batterystats} command allows you to generate interesting +statistical data about battery usage on a device, organized by unique user ID +(UID). The statistics generated by the tool include:</p> + +<ul> +<li>History of battery related events +<li>Global statistics for the device +<li>Approximated power use per UID and system component +<li>Per-app mobile ms per packet +<li>System UID aggregated statistics +<li>App UID aggregated statistics +</ul> + +<p>Use the {@code --help} option to learn about the various options for +tailoring the output. For example, to print battery usage +statistics for a given app package since the device was last charged, run this +command: +<pre> +$ adb shell dumpsys batterystats --charged <package-name> +</pre> +</dd> + +<dt><strong>Battery Historian</strong></dt> +<dd> +<p>The Battery Historian tool ({@code historian.par}) analyzes Android +bug reports from the L Developer Preview and creates an HTML visualization of +power-related events. It can +also visualize power consumption data from a power monitor, and attempts to +map power usage to the wake locks seen. You can find the Battery Historian tool +in {@code <sdk>/tools}.</p> + +<img src="images/battery_historian.png" + srcset="images/battery_historian@2x.png 2x" + alt="" width="760" height="462" + id="figure2" /> +<p class="img-caption"> + <strong>Figure 2.</strong>HTML visualization generated by the Battery + Historian tool. +</p> + +<p>For best results, you should first enable full wake lock reporting, to allow +the Battery Historian tool to monitor uninterrupted over an extended period of +time:</p> +<pre> +$ adb shell dumpsys batterystats --enable full-wake-history +</pre> + +<p>You should also reset battery statistics at the beginning of a +measurement:</p> +<pre> +$ adb shell dumpsys batterystats --reset +</pre> + +<p>To generate an HTML visualization:</p> +<pre> +$ historian.par [-p powerfile] bugreport.txt > out.html +</pre> +</dd> + +</dl> + +<h2 id="Enterprise">Enterprise</h2> +<h3 id="ManagedProvisioning">Managed provisioning</h3> + +<div class="figure" style="width:360px"> + <img src="images/managed_apps_launcher.png" + srcset="images/managed_apps_launcher@2x.png 2x" + alt="" width="360" height="609" id="figure3" /> + <p class="img-caption"> + <strong>Figure 3.</strong> Launcher screen showing managed apps (marked with + a lock badge) + </p> +</div> + +<p>The L Developer Preview provides new functionality for running apps within +an enterprise environment. A +<a href="{@docRoot}guide/topics/admin/device-admin.html">device administrator</a> can +initiate a managed provisioning process to add a co-present but separate <em>managed profile</em> to a device, if the user has an existing personal account. +Apps that are associated with managed profiles will appear alongside +non-managed apps in the user’s Launcher, Recent apps screen, and notifications.</p> + +<p>To start the managed provisioning process, send {@code +ACTION_PROVISION_MANAGED_PROFILE} in an {@link android.content.Intent}. If the +call is successful, the system triggers the {@code +android.app.admin.DeviceAdminReceiver. onProfileProvisioningComplete()} callback. +You can then call {@code app.admin.DevicePolicyManager. setProfileEnabled()} to +enable this managed profile.</p> + +<p>If you are developing a Launcher app, you can use the new {@code +android.content.pm.LauncherApps} class to get a list of launchable activities +for the current user and any associated managed profiles. Your Launcher can make +the managed apps visually prominent by appending a “work” badge to the icon +drawable with {@code android.os.UserManager. getBadgeDrawableForUser()}.</p> + +<p>To see an example of how to use the new functionality, refer to the +{@code BasicManagedProfile} implementation sample in this release.</p> + +<h3 id="TaskLocking">Task locking</h3> +<p>The L Developer Preview introduces a new task locking API that +lets you temporarily restrict users from leaving your app or being interrupted +by notifications. This could be used, for example, if you are developing an +education app to support high stakes assessment requirements on Android. +Once your app activates this mode, users will not be able to see +notifications, access other apps, or return to the Home screen, until your +app exits the mode.</p> + +<p>To prevent unauthorized usage, only authorized apps can activate task locking. +Furthermore, task locking authorization must be granted by a +specially-configured <em>device owner</em> app, through the {@code android.app.admin.DevicePolicyManager.setLockTaskComponents()} method.</p> + +<p>To set up a device owner, follow these steps:</p> +<ol> +<li>Attach a device running an Android <a href="https://source.android.com/source/building-running.html" class="external-link">{@code userdebug}</a> build to your development machine.</li> +<li>Install your device owner app.</li> +<li>Create a {@code device_owner.xml} file and save it to the {@code /data/system} +directory on the device. +<pre> +$ adb root +$ adb shell stop +$ rm /tmp/device_owner.xml +$ echo "<?xml version='1.0' encoding='utf-8' standalone='yes' ?>" +>> /tmp/device_owner.xml +$ echo "&device-owner package=\"<your_device_owner_package>\" +name=\"*<your_organization_name>\" />" >> /tmp/device_owner.xml +$ adb push /tmp/device_owner.xml /data/system/device_owner.xml +$ adb reboot +</pre> +</li> +</ol> + +<p>Before using the task locking API in your app, verify that your activity is +authorized by calling {@code DevicePolicyManager.isLockTaskPermitted()}.</p> + +<p>To activate task locking, call +{@code android.app.Activity.startLockTask()} from your authorized activity.</p> + +<p>When task locking is active, the following behavior takes effect:</p> + +<ul> +<li>The status bar is blank, and user notifications and status information is +hidden.</li> +<li>The Home and Recent Apps buttons are hidden.</li> +<li>Other apps may not launch new activities.</li> +<li>The current app may start new activities, as long as doing so does not +create new tasks.</li> +<li>The user remains locked on your app until an authorized activity calls +{@code Activity.stopLockTask()}.</li> +</ul> + +<h2 id="Printing">Printing Framework</h2> + +<h3 id="PDFRender">Render PDF as bitmap</h3> +<p>You can now render PDF document pages into bitmap images for printing by +using the new {@code android.graphics.pdf.PdfRenderer} class. You must specify a +{@link android.os.ParcelFileDescriptor} that is seekable (that is, the content +can be randomly accessed) on which the system writes the the printable content. +Your app can obtain a page for rendering with {@code openPage()}, then call +{@code render()} to turn the opened {@code PdfRenderer.Page} into a bitmap. You +can also set additional parameters if you only want to convert a portion of the +document into a bitmap image (for example, to implement +<a href="http://en.wikipedia.org/wiki/Tiled_rendering" class="external-link">tiled rendering</a> in +order to zoom in on the document).</p> + +<h2 id="TestingA11y">Testing & Accessibility </h2> + +<h3 id="TestingA11yImprovements">Testing and accessibility improvements</h3> +<p>The L Developer Preview adds the following support for testing and +accessibility:</p> + +<ul> +<li>You can use the new {@code android.app.UiAutomation.getWindowAnimationFrameStats()} +and {@code android.app.UiAutomation.getWindowContentFrameStats()} methods to +capture frame statistics for window animations and content. This lets you +write instrumentation tests to evaluate if the app under test is rendering +frames at a sufficient refresh frequency to provide a smooth user experience. + +<li>You can execute shell commands from your instrumentation test with the new +{@code android.app.UiAutomation.executeShellCommand()}. The command execution +is similar to running {@code adb shell} from a host connected to the device. This +allows you to use shell based tools such as {@code dumpsys}, {@code am}, +{@code content}, and {@code pm}. + +<li>Accessibility services and test tools that use the accessibility APIs +(such as <a href="{@docRoot}tools/help/uiautomator/index.html">uiautomator</a>) +can now retrieve detailed information about the properties of windows on the +screen that sighted users can interact with. To retrieve a list of +{@code android.view.accessibility.AccessibilityWindowInfo} objects +representing the windows information, call the new +{@code android.accessibilityservice.AccessibilityService.getWindows()} method. +<li>You can use the new {@code android.view.accessibility.AccessibilityNodeInfo.AccessibilityAction} to define standard or customized +actions to perform on an {@link android.view.accessibility.AccessibilityNodeInfo}. +The new {@code AccessibilityAction} class replaces the actions-related APIs +previously found in {@code AccessibilityNodeInfo}. +</ul> + +<h2 id="IME">IME</h2> + +<h3 id="Switching">Easier switching between input languages</h3> + +<p>Beginning in the L Developer Preview, users can more easily switch between +all <a href="{@docRoot}guide/topics/text/creating-input-method.html">input +method editors (IME)</a> supported by the platform. Performing the designated +switching action (usually touching a Globe icon on the soft keyboard) will cycle +among all such IMEs. This change takes place in +{@link android.view.inputmethod.InputMethodManager#shouldOfferSwitchingToNextInputMethod +InputMethodManager.shouldOfferSwitchingToNextInputMethod()}.</p> + +<p>In addition, the framework now checks whether the next IME includes a +switching mechanism at all (and, thus, whether that IME supports switching to +the IME after it). An +IME with a switching mechanism will not cycle to an IME without one. This +change takes place in +{@link android.view.inputmethod.InputMethodManager#switchToNextInputMethod +InputMethodManager.switchToNextInputMethod}. + +<p>To see an example of how to use the updated IME-switching APIs, refer to the +updated soft-keyboard implementation sample in this release.</p> + +<h2 id="Manifest">Manifest Declarations</h2> + +<h3 id="ManifestFeatures">Declarable required features</h3> +<p>The following values are now supported in the +<a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> +element, so you can ensure that your app is installed only on devices that provide the features +your app needs.</p> + +<ul> +<li>{@code FEATURE_LEANBACK}. Declares that your app must be installed only on +devices that support the +<a href="{@docRoot}training/tv/index.html">Android TV</a> user interface. +Example: +<pre> +<uses-feature android:name="android.software.leanback" + android:required="true" /> +</pre> + +<li>{@code FEATURE_WEBVIEW}. Declares that your app must only be installed on +devices that fully implement the {@code android.webkit.*} APIs. Example: +<pre> +<uses-feature android:name="android.software.webview" + android:required="true" /> +</pre> +</ul> + +<p class="note">For a detailed view of all API changes in the L Developer Preview, see the +<a href="{@docRoot}preview/reference.html">API Differences Report</a>.</p> diff --git a/docs/html/preview/google-play-services-wear.html b/docs/html/preview/google-play-services-wear.html new file mode 100644 index 0000000..ad8891f --- /dev/null +++ b/docs/html/preview/google-play-services-wear.html @@ -0,0 +1,95 @@ +<html><head> + + +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<meta name="viewport" content="width=device-width"> + +<meta name="Description" content="Google Play services will fully roll out to the hundreds of millions of Android devices in early July. Because of this, we usually wait to release the Google Play services SDK until all users receive the most updated Google Play services on their devices…"> +<link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> +<title>Google Play services Preview for Wear | Android Developers</title> + +<!-- STYLESHEETS --> +<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Roboto:light,regular,medium,thin,italic,mediumitalic,bold" title="roboto"> +<link href="/assets/css/default.css" rel="stylesheet" type="text/css"> +</head> +<body> +<div class="col-12" id="doc-col"> + +<h1 itemprop="name">Google Play services Preview for Wear</h1> + + + + + + + <div id="jd-content"> + <div class="jd-descr" itemprop="articleBody"> +<p>The Google Play services app is currently being rolled out to the hundreds of millions of +Android devices and will complete in early July. Because of this, we usually wait to release the Google Play +services SDK until all users receive the app. This guarantees that your newly-updated apps can +run on the most devices as possible.</p> + +<p>However, if want to develop for Android Wear now, complete the following steps +to get special access to all the things you need to start developing, without waiting +for the rollout to complete. </p> + +<p class="warning"><b>Warning</b>: Do not publish any apps that use the new Google Play services +APIs until the rollout is complete. Your apps will break on most user devices, which will +degrade your user rating.</b> +</p> + +<h2 style="margin-bottom: 0px;">1. Get Whitelisted for the Preview</h2><hr> + +<p>If you attended Google I/O, your registered Gmail account is automatically whitelisted for these +preview resources. If you didn't attend Google I/O, sign up below to get access:</p> + +<a href="https://groups.google.com/forum/?hl=en#!forum/io14androidweardev">Get Whitelisted</a> + +<h2 style="margin-bottom: 0px;">2. Download Required Apps</h2><hr> +<p>You'll need the following apps to get the most out of Android Wear:</p> + + +<p>Here's a list of the apps you need:</p> +<ul> +<li><a href="https://play.google.com/apps/testing/com.google.android.gms">Google Play services</a>: Allows your Wear device to properly communicate with your handheld device. This is +required to use the Android Wear Companion App.</li> + <li><a href="https://play.google.com/apps/testing/com.google.android.wearable.app">Android Wear + Companion</a>: The main user app to pair a handheld to a wearable and to provide syncing + of notifications and data.</li> + <li><a href="https://play.google.com/apps/testing/com.google.android.googlequicksearchbox">Google + Search</a>: A preview release of the Google Search handheld app that Wear communicates with + to carry out searches.</li> + <li><a href="https://play.google.com/apps/testing/com.google.android.keep">Google Keep</a>: To enable the "Take a note" command</li> + <li><a href="https://play.google.com/apps/testing/com.google.samples.apps.iosched">Google I/O 2014</a></li> + </ul> + +<p>To enable the preview versions of the apps, click each app link above and follow these +instructions:</p> + +<ol> + <li>Click the <b>Become a Tester</b> button to opt-in to the preview version of the app. The page + confirms that you're a tester after clicking.</li> + <li>Click the <b>Download <app name> from the Play Store</b> link to go to Google Play + Store download page to get the app. The + following screenshot shows how the opt-in process looks like: +<img style="margin-top:40px" src="/preview/images/opt-in.png"></li> + <li>When Google Play services is rolled out to all devices, go back to the app links provided + to opt-out of the preview versions of the apps. Check back here in a week for the status of + the rollout.</li> +</ol> + + + +<h2 style="margin-bottom: 0px;">3. Start Building</h2><hr> +<p>Check out the <a href="/training/building-wearables">Building Apps for Wearables</a> +training classes for information on how to build for Wear.</p> + </div> + + + + + </div> <!-- end jd-content --> +</div><!-- end doc-content --> +</div> <!-- end body-content --> +</body> +</html>
\ No newline at end of file diff --git a/docs/html/preview/images/ActivitySceneTransitionBasic.png b/docs/html/preview/images/ActivitySceneTransitionBasic.png Binary files differnew file mode 100644 index 0000000..ea58641 --- /dev/null +++ b/docs/html/preview/images/ActivitySceneTransitionBasic.png diff --git a/docs/html/preview/images/ActivitySceneTransitionBasic@2x.png b/docs/html/preview/images/ActivitySceneTransitionBasic@2x.png Binary files differnew file mode 100644 index 0000000..cd28ade --- /dev/null +++ b/docs/html/preview/images/ActivitySceneTransitionBasic@2x.png diff --git a/docs/html/preview/images/BasicManagedProfile.png b/docs/html/preview/images/BasicManagedProfile.png Binary files differnew file mode 100644 index 0000000..7354842 --- /dev/null +++ b/docs/html/preview/images/BasicManagedProfile.png diff --git a/docs/html/preview/images/BasicManagedProfile@2x.png b/docs/html/preview/images/BasicManagedProfile@2x.png Binary files differnew file mode 100644 index 0000000..c232809 --- /dev/null +++ b/docs/html/preview/images/BasicManagedProfile@2x.png diff --git a/docs/html/preview/images/JobSchedulerSample.png b/docs/html/preview/images/JobSchedulerSample.png Binary files differnew file mode 100644 index 0000000..ee57bdb --- /dev/null +++ b/docs/html/preview/images/JobSchedulerSample.png diff --git a/docs/html/preview/images/JobSchedulerSample@2x.png b/docs/html/preview/images/JobSchedulerSample@2x.png Binary files differnew file mode 100644 index 0000000..3d543db --- /dev/null +++ b/docs/html/preview/images/JobSchedulerSample@2x.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/battery_historian.png b/docs/html/preview/images/battery_historian.png Binary files differnew file mode 100644 index 0000000..f1d4e40 --- /dev/null +++ b/docs/html/preview/images/battery_historian.png diff --git a/docs/html/preview/images/battery_historian@2x.png b/docs/html/preview/images/battery_historian@2x.png Binary files differnew file mode 100644 index 0000000..8c8a87f --- /dev/null +++ b/docs/html/preview/images/battery_historian@2x.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/hun-example.png b/docs/html/preview/images/hun-example.png Binary files differnew file mode 100644 index 0000000..251b938 --- /dev/null +++ b/docs/html/preview/images/hun-example.png diff --git a/docs/html/preview/images/hun-example@2x.png b/docs/html/preview/images/hun-example@2x.png Binary files differnew file mode 100644 index 0000000..5b98a36 --- /dev/null +++ b/docs/html/preview/images/hun-example@2x.png diff --git a/docs/html/preview/images/l-dev-prev.png b/docs/html/preview/images/l-dev-prev.png Binary files differnew file mode 100644 index 0000000..eae6ede --- /dev/null +++ b/docs/html/preview/images/l-dev-prev.png diff --git a/docs/html/preview/images/managed_apps_launcher.png b/docs/html/preview/images/managed_apps_launcher.png Binary files differnew file mode 100644 index 0000000..b5ef407 --- /dev/null +++ b/docs/html/preview/images/managed_apps_launcher.png diff --git a/docs/html/preview/images/managed_apps_launcher@2x.png b/docs/html/preview/images/managed_apps_launcher@2x.png Binary files differnew file mode 100644 index 0000000..90d7d51 --- /dev/null +++ b/docs/html/preview/images/managed_apps_launcher@2x.png 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/opt-in.png b/docs/html/preview/images/opt-in.png Binary files differnew file mode 100644 index 0000000..51754af --- /dev/null +++ b/docs/html/preview/images/opt-in.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.html b/docs/html/preview/index.html new file mode 100644 index 0000000..4f3f150 --- /dev/null +++ b/docs/html/preview/index.html @@ -0,0 +1,361 @@ +<!DOCTYPE html> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +<html> +<head> + + +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="viewport" content="width=970" /> + +<meta name="Description" content="Test and build your apps against the next version of Android to ensure they're ready when the platform officially launches."> +<link rel="shortcut icon" type="image/x-icon" href="/favicon.ico" /> +<title>Android L Developer Preview | Android Developers</title> + +<!-- STYLESHEETS --> +<link rel="stylesheet" +href="//fonts.googleapis.com/css?family=Roboto+Condensed"> +<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Roboto:light,regular,medium,thin,italic,mediumitalic,bold" + title="roboto"> +<link href="/assets/css/default.css" rel="stylesheet" type="text/css"> + + + +<!-- JAVASCRIPT --> +<script src="//www.google.com/jsapi" type="text/javascript"></script> +<script src="/assets/js/android_3p-bundle.js" type="text/javascript"></script> +<script type="text/javascript"> + var toRoot = "/"; + var metaTags = []; + var devsite = false; +</script> +<script src="/assets/js/docs.js" type="text/javascript"></script> + +<script> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + + ga('create', 'UA-5831155-1', 'android.com'); + ga('create', 'UA-49880327-2', 'android.com', {'name': 'universal'}); // New tracker); + ga('send', 'pageview'); + ga('universal.send', 'pageview'); // Send page view for new tracker. +</script> + +</head> + +<body class="gc-documentation + +" itemscope itemtype="http://schema.org/Article"> + + +<a name="top"></a> +<div id="body-content"> +<div class="fullpage" > +<div id="jd-content"> + <div class="jd-descr" itemprop="articleBody"> + <style> +.fullpage>#footer, +#jd-content>.content-footer.wrap { + display:none; +} +</style> + +<style> +#footer { + display: none; +} +.content-footer { + display: none; +} +</style> + + <div class="landing-rest-of-page"> + <div class="landing-section" style="padding-top:30px"> + <div class="wrap"> + <div class="landing-section-header"> + <div class="landing-h1">Android L Developer Preview</div> + <div class="landing-subhead"> + Get an early look at the next release and get your apps ready when the + platform officially launches. + </div> + + <img src="/preview/images/l-dev-prev.png" style=" margin:0px 0 0 40px" width="860px"/> + <div class="col-6" style="margin-left:660px; margin-top:-105px"> + <a href="/preview/setup-sdk.html" class="landing-button landing-primary" style="position:absolute;z-index:100;float:right;margin-top: 0px;">Get Started</a><!-- + <p>Set up your environment and check out all the docs to get up and running.</p>--> + + + </div> + </div> + </div> <!-- end .wrap --> + </div> <!-- end .landing-section --> + + + +<div class="landing-section landing-gray-background" style="margin-top:-135px; padding-bottom:20px"> + <div class="wrap"> + <div class="cols"> +<div class="landing-body" style="margin-top:-80px" > + + <div class="landing-breakout cols"> + <div class="col-4"> + <p>A New UI Design</p> + <p class="landing-small"> + Create a consistent experience across mobile and the web with + <b>material design</b>, 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"> + <p>A New 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"> + <p style="width:230px">Enhanced Notifications</p> + <p class="landing-small"> + Get control over where notifications appear, + how they look, and how they sync to non-handheld devices. + </p> + <p class="landing-small"> + <a href="/preview/api-overview.html#UI">Learn about notifications</a> + </p> + </div> + <div class="col-4"> + <p>Increased Efficiency</p> + <p class="landing-small"> + <b>Project Volta</b> is our effort to make the platform energy efficient and + to give you more control over resource usage. + </p> + <p class="landing-small"> + <a href="/preview/api-overview.html#Power">Learn about Project Volta</a> + </p> + </div> + </div> + <p style="margin-left:20px">See the <a href="/preview/api-overview.html">API overview</a> for more information + on the rest of the new and updated features.</p> + </div> + </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="https://code.google.com/p/android-developer-preview/"> + <img class="landing-social-image" src="/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 href="https://code.google.com/p/android-developer-preview/"> + 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 href="https://plus.google.com/communities/113159138894928487684"> + Discuss on Google+</a> + </p> + </div> + </div> + <div class="col-3-wide"> + <a target="_blank" href="/preview/support.html"> + <img class="landing-social-image" src="/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 href="/preview/support.html">Get Support</a> + </p> + </div> + </div> + </div> + </div> + </div> + </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> + </div> + + <div class="content-footer wrap" + itemscope itemtype="http://schema.org/SiteNavigationElement"> + + <div class="paging-links layout-content-col col-10"> + + </div> + <div class="layout-content-col plus-container col-2" > + <style>#___plusone_0 {float:right !important;}</style> + <div class="g-plusone" data-size="medium"></div> + + </div> + + </div> + + + + + </div> <!-- end jd-content --> + +<div id="footer" class="wrap" style="width:940px"> + + + <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> <!-- end footer --> +</div><!-- end doc-content --> + +</div> <!-- end body-content --> + + + + + + <script src="https://developer.android.com/ytblogger_lists_unified.js" type="text/javascript"></script> + <script src="/jd_lists_unified.js" type="text/javascript"></script> + <script src="/jd_extras.js" type="text/javascript"></script> + <script src="/jd_collections.js" type="text/javascript"></script> + <script src="/jd_tag_helpers.js" type="text/javascript"></script> + +</body> +</html> diff --git a/docs/html/preview/license.jd b/docs/html/preview/license.jd new file mode 100644 index 0000000..5ff52ba --- /dev/null +++ b/docs/html/preview/license.jd @@ -0,0 +1,143 @@ +page.title=License Agreement + +@jd:body + +<p> +To get started with the Android SDK Preview, you must agree to the following terms and conditions. +As described below, please note that this is a preview version of the Android SDK, subject to change, that you use at your own risk. The Android SDK Preview is not a stable release, and may contain errors and defects that can result in serious damage to your computer systems, devices and data. +</p> + +<p> +This is the Android SDK Preview License Agreement (the “License Agreement”). +</p> +<div class="sdk-terms" style="height:auto;border:0;padding:0;width:700px"> +1. Introduction + +1.1 The Android SDK Preview (referred to in the License Agreement as the “Preview” and specifically including the Android system files, packaged APIs, and Preview library files, if and when they are made available) is licensed to you subject to the terms of the License Agreement. The License Agreement forms a legally binding contract between you and Google in relation to your use of the Preview. + +1.2 "Android" means the Android software stack for devices, as made available under the Android Open Source Project, which is located at the following URL: http://source.android.com/, as updated from time to time. + +1.3 "Google" means Google Inc., a Delaware corporation with principal place of business at 1600 Amphitheatre Parkway, Mountain View, CA 94043, United States. + +2. Accepting the License Agreement + +2.1 In order to use the Preview, you must first agree to the License Agreement. You may not use the Preview if you do not accept the License Agreement. + +2.2 By clicking to accept and/or using the Preview, you hereby agree to the terms of the License Agreement. + +2.3 You may not use the Preview and may not accept the License Agreement if you are a person barred from receiving the Preview under the laws of the United States or other countries including the country in which you are resident or from which you use the Preview. + +2.4 If you will use the Preview internally within your company or organization you agree to be bound by the License Agreement on behalf of your employer or other entity, and you represent and warrant that you have full legal authority to bind your employer or such entity to the License Agreement. If you do not have the requisite authority, you may not accept the License Agreement or use the Preview on behalf of your employer or other entity. + +3. Preview License from Google + +3.1 Subject to the terms of the License Agreement, Google grants you a royalty-free, non-assignable, non-exclusive, non-sublicensable, limited, revocable license to use the Preview, personally or internally within your company or organization, solely to develop applications to run on the Android platform. + +3.2 You agree that Google or third parties owns all legal right, title and interest in and to the Preview, including any Intellectual Property Rights that subsist in the Preview. "Intellectual Property Rights" means any and all rights under patent law, copyright law, trade secret law, trademark law, and any and all other proprietary rights. Google reserves all rights not expressly granted to you. + +3.3 You may not use the Preview for any purpose not expressly permitted by the License Agreement. Except to the extent required by applicable third party licenses, you may not: (a) copy (except for backup purposes), modify, adapt, redistribute, decompile, reverse engineer, disassemble, or create derivative works of the Preview or any part of the Preview; or (b) load any part of the Preview onto a mobile handset or any other hardware device except a personal computer, combine any part of the Preview with other software, or distribute any software or device incorporating a part of the Preview. + +3.4 You agree that you will not take any actions that may cause or result in the fragmentation of Android, including but not limited to distributing, participating in the creation of, or promoting in any way a software development kit derived from the Preview. + +3.5 Use, reproduction and distribution of components of the Preview licensed under an open source software license are governed solely by the terms of that open source software license and not the License Agreement. You agree to remain a licensee in good standing in regard to such open source software licenses under all the rights granted and to refrain from any actions that may terminate, suspend, or breach such rights. + +3.6 You agree that the form and nature of the Preview that Google provides may change without prior notice to you and that future versions of the Preview may be incompatible with applications developed on previous versions of the Preview. You agree that Google may stop (permanently or temporarily) providing the Preview (or any features within the Preview) to you or to users generally at Google's sole discretion, without prior notice to you. + +3.7 Nothing in the License Agreement gives you a right to use any of Google's trade names, trademarks, service marks, logos, domain names, or other distinctive brand features. + +3.8 You agree that you will not remove, obscure, or alter any proprietary rights notices (including copyright and trademark notices) that may be affixed to or contained within the Preview. + +4. Use of the Preview by You + +4.1 Google agrees that nothing in the License Agreement gives Google any right, title or interest from you (or your licensors) under the License Agreement in or to any software applications that you develop using the Preview, including any intellectual property rights that subsist in those applications. + +4.2 You agree to use the Preview and write applications only for purposes that are permitted by (a) the License Agreement, and (b) any applicable law, regulation or generally accepted practices or guidelines in the relevant jurisdictions (including any laws regarding the export of data or software to and from the United States or other relevant countries). + +4.3 You agree that if you use the Preview to develop applications, you will protect the privacy and legal rights of users. If users provide you with user names, passwords, or other login information or personal information, you must make the users aware that the information will be available to your application, and you must provide legally adequate privacy notice and protection for those users. If your application stores personal or sensitive information provided by users, it must do so securely. If users provide you with Google Account information, your application may only use that information to access the user's Google Account when, and for the limited purposes for which, each user has given you permission to do so. + +4.4 You agree that you will not engage in any activity with the Preview, including the development or distribution of an application, that interferes with, disrupts, damages, or accesses in an unauthorized manner the servers, networks, or other properties or services of Google or any third party. + +4.5 You agree that you are solely responsible for (and that Google has no responsibility to you or to any third party for) any data, content, or resources that you create, transmit or display through Android and/or applications for Android, and for the consequences of your actions (including any loss or damage which Google may suffer) by doing so. + +4.6 You agree that you are solely responsible for (and that Google has no responsibility to you or to any third party for) any breach of your obligations under the License Agreement, any applicable third party contract or Terms of Service, or any applicable law or regulation, and for the consequences (including any loss or damage which Google or any third party may suffer) of any such breach. + +4.7 The Preview is in development, and your testing and feedback are an important part of the development process. By using the Preview, you acknowledge that implementation of some features are still under development and that you should not rely on the Preview having the full functionality of a stable release. You agree not to publicly distribute or ship any application using this Preview as this Preview will no longer be supported after the official Android SDK is released. + +5. Your Developer Credentials + +5.1 You agree that you are responsible for maintaining the confidentiality of any developer credentials that may be issued to you by Google or which you may choose yourself and that you will be solely responsible for all applications that are developed under your developer credentials. + +6. Privacy and Information + +6.1 In order to continually innovate and improve the Preview, Google may collect certain usage statistics from the software including but not limited to a unique identifier, associated IP address, version number of the software, and information on which tools and/or services in the Preview are being used and how they are being used. Before any of this information is collected, the Preview will notify you and seek your consent. If you withhold consent, the information will not be collected. + +6.2 The data collected is examined in the aggregate to improve the Preview and is maintained in accordance with Google's Privacy Policy located at http://www.google.com/policies/privacy/. + +7. Third Party Applications + +7.1 If you use the Preview to run applications developed by a third party or that access data, content or resources provided by a third party, you agree that Google is not responsible for those applications, data, content, or resources. You understand that all data, content or resources which you may access through such third party applications are the sole responsibility of the person from which they originated and that Google is not liable for any loss or damage that you may experience as a result of the use or access of any of those third party applications, data, content, or resources. + +7.2 You should be aware the data, content, and resources presented to you through such a third party application may be protected by intellectual property rights which are owned by the providers (or by other persons or companies on their behalf). You may not modify, rent, lease, loan, sell, distribute or create derivative works based on these data, content, or resources (either in whole or in part) unless you have been specifically given permission to do so by the relevant owners. + +7.3 You acknowledge that your use of such third party applications, data, content, or resources may be subject to separate terms between you and the relevant third party. + +8. Using Google APIs + +8.1 Google APIs + +8.1.1 If you use any API to retrieve data from Google, you acknowledge that the data may be protected by intellectual property rights which are owned by Google or those parties that provide the data (or by other persons or companies on their behalf). Your use of any such API may be subject to additional Terms of Service. You may not modify, rent, lease, loan, sell, distribute or create derivative works based on this data (either in whole or in part) unless allowed by the relevant Terms of Service. + +8.1.2 If you use any API to retrieve a user's data from Google, you acknowledge and agree that you shall retrieve data only with the user's explicit consent and only when, and for the limited purposes for which, the user has given you permission to do so. + +9. Terminating the License Agreement + +9.1 the License Agreement will continue to apply until terminated by either you or Google as set out below. + +9.2 If you want to terminate the License Agreement, you may do so by ceasing your use of the Preview and any relevant developer credentials. + +9.3 Google may at any time, terminate the License Agreement, with or without cause, upon notice to you. + +9.4 The License Agreement will automatically terminate without notice or other action upon the earlier of: +(A) when Google ceases to provide the Preview or certain parts of the Preview to users in the country in which you are resident or from which you use the service; and +(B) Google issues a final release version of the Android SDK. + +9.5 When the License Agreement is terminated, the license granted to you in the License Agreement will terminate, you will immediately cease all use of the Preview, and the provisions of paragraphs 10, 11, 12 and 14 shall survive indefinitely. + +10. DISCLAIMERS + +10.1 YOU EXPRESSLY UNDERSTAND AND AGREE THAT YOUR USE OF THE PREVIEW IS AT YOUR SOLE RISK AND THAT THE PREVIEW IS PROVIDED "AS IS" AND "AS AVAILABLE" WITHOUT WARRANTY OF ANY KIND FROM GOOGLE. + +10.2 YOUR USE OF THE PREVIEW AND ANY MATERIAL DOWNLOADED OR OTHERWISE OBTAINED THROUGH THE USE OF THE PREVIEW IS AT YOUR OWN DISCRETION AND RISK AND YOU ARE SOLELY RESPONSIBLE FOR ANY DAMAGE TO YOUR COMPUTER SYSTEM OR OTHER DEVICE OR LOSS OF DATA THAT RESULTS FROM SUCH USE. WITHOUT LIMITING THE FOREGOING, YOU UNDERSTAND THAT THE PREVIEW IS NOT A STABLE RELEASE AND MAY CONTAIN ERRORS, DEFECTS AND SECURITY VULNERABILITIES THAT CAN RESULT IN SIGNIFICANT DAMAGE, INCLUDING THE COMPLETE, IRRECOVERABLE LOSS OF USE OF YOUR COMPUTER SYSTEM OR OTHER DEVICE. + +10.3 GOOGLE FURTHER EXPRESSLY DISCLAIMS ALL WARRANTIES AND CONDITIONS OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. + +11. LIMITATION OF LIABILITY + +11.1 YOU EXPRESSLY UNDERSTAND AND AGREE THAT GOOGLE, ITS SUBSIDIARIES AND AFFILIATES, AND ITS LICENSORS SHALL NOT BE LIABLE TO YOU UNDER ANY THEORY OF LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR EXEMPLARY DAMAGES THAT MAY BE INCURRED BY YOU, INCLUDING ANY LOSS OF DATA, WHETHER OR NOT GOOGLE OR ITS REPRESENTATIVES HAVE BEEN ADVISED OF OR SHOULD HAVE BEEN AWARE OF THE POSSIBILITY OF ANY SUCH LOSSES ARISING. + +12. Indemnification + +12.1 To the maximum extent permitted by law, you agree to defend, indemnify and hold harmless Google, its affiliates and their respective directors, officers, employees and agents from and against any and all claims, actions, suits or proceedings, as well as any and all losses, liabilities, damages, costs and expenses (including reasonable attorneys’ fees) arising out of or accruing from (a) your use of the Preview, (b) any application you develop on the Preview that infringes any Intellectual Property Rights of any person or defames any person or violates their rights of publicity or privacy, and (c) any non-compliance by you of the License Agreement. + +13. Changes to the License Agreement + +13.1 Google may make changes to the License Agreement as it distributes new versions of the Preview. When these changes are made, Google will make a new version of the License Agreement available on the website where the Preview is made available. + +14. General Legal Terms + +14.1 the License Agreement constitutes the whole legal agreement between you and Google and governs your use of the Preview (excluding any services which Google may provide to you under a separate written agreement), and completely replaces any prior agreements between you and Google in relation to the Preview. + +14.2 You agree that if Google does not exercise or enforce any legal right or remedy which is contained in the License Agreement (or which Google has the benefit of under any applicable law), this will not be taken to be a formal waiver of Google's rights and that those rights or remedies will still be available to Google. + +14.3 If any court of law, having the jurisdiction to decide on this matter, rules that any provision of the License Agreement is invalid, then that provision will be removed from the License Agreement without affecting the rest of the License Agreement. The remaining provisions of the License Agreement will continue to be valid and enforceable. + +14.4 You acknowledge and agree that each member of the group of companies of which Google is the parent shall be third party beneficiaries to the License Agreement and that such other companies shall be entitled to directly enforce, and rely upon, any provision of the License Agreement that confers a benefit on (or rights in favor of) them. Other than this, no other person or company shall be third party beneficiaries to the License Agreement. + +14.5 EXPORT RESTRICTIONS. THE PREVIEW IS SUBJECT TO UNITED STATES EXPORT LAWS AND REGULATIONS. YOU MUST COMPLY WITH ALL DOMESTIC AND INTERNATIONAL EXPORT LAWS AND REGULATIONS THAT APPLY TO THE PREVIEW. THESE LAWS INCLUDE RESTRICTIONS ON DESTINATIONS, END USERS AND END USE. + +14.6 The License Agreement may not be assigned or transferred by you without the prior written approval of Google, and any attempted assignment without such approval will be void. You shall not delegate your responsibilities or obligations under the License Agreement without the prior written approval of Google. + +14.7 The License Agreement, and your relationship with Google under the License Agreement, shall be governed by the laws of the State of California without regard to its conflict of laws provisions. You and Google agree to submit to the exclusive jurisdiction of the courts located within the county of Santa Clara, California to resolve any legal matter arising from the License Agreement. Notwithstanding this, you agree that Google shall still be allowed to apply for injunctive remedies (or an equivalent type of urgent legal relief) in any jurisdiction. + + +</div>
\ 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..b8d063b --- /dev/null +++ b/docs/html/preview/material/animations.jd @@ -0,0 +1,441 @@ +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">Animating View State Changes</a></li> + <li><a href="#drawabletint">Drawable Tinting</a></li> + <li><a href="#colorextract">Extracting Colors from an Image</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>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>In most cases, this functionality should be applied in your view XML by specifying the +background as <code>?android:attr/selectableItemBackground</code> for a bounded ripple or +<code>?android:attr/selectableItemBackgroundBorderless</code> for a ripple that extends beyond +the view bounds. You can also create a <code>RippleDrawable</code> and set +it as the background of your view. Alternatively, you can define a <code>RippleDrawable</code> +as an XML resource using the <code>ripple</code> element. The +Android L Developer Preview animates the selection color with a ripple effect.</p> + +<p>You can assign a color to <code>RippleDrawable</code> objects. To change the default touch +feedback color, use the theme's <code>android:colorControlHighlight</code> attribute.</p> + + +<h2 id="reveal">Reveal Effect</h2> + +<p>The <code>ViewAnimationUtils.createCircularReveal</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 = + ViewAnimationUtils.createCircularReveal(myView, 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 = + ViewAnimationUtils.createCircularReveal(myView, 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>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 the 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> + +<p>The Android L Developer Preview supports these enter and exit transitions:</p> + +<ul> +<li><em>explode</em> - Moves views in or out from the center of the scene.</li> +<li><em>slide</em> - Moves views in or out from one of the edges of the scene.</li> +<li><em>fade</em> - Mades views in or out of the scene.</li> +</ul> + +<p>Any transition that extends the <code>android.transition.Visibility</code> class is supported +as an enter or exit transition. For more information, see the API reference for the +<code>android.transition.Transition</code> class.</p> + +<p>The Android L Developer Preview also supports these shared elements transitions:</p> + +<ul> +<li><em>changeBounds</em> - Animates the changes in layout bounds of target views.</li> +<li><em>changeClipBounds</em> - Animates the changes in clip bounds of target views.</li> +<li><em>changeTransform</em> - Animates the changes in scale and rotation of target views.</li> +<li><em>moveImage</em> - Animates changes in size and scale type for an image view.</li> +</ul> + +<p>When you enable activity transitions in your app, the default cross-fading transition is +activated between the entering and exiting activities.</p> + +<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. You can also specify +enter, exit, and shared element transitions in your style definition:</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>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/> +</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 (if you did not enable transitions in your theme) +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> + +<p>The <code>setExitTransition</code> and <code>setSharedElementExitTransition</code> methods +define the exit transition for the calling activity. The <code>setEnterTransition</code> and +<code>setSharedElementEnterTransition</code> methods define the enter transition for the called +activity.</p> + +<p>To get the full effect of a transition, you must enable window content transitions on both the +calling and called activities. Otherwise, the calling activity will start the exit transition, +but then you'll see a window transition (like scale or fade).</p> + +<p>To start an enter transition as soon as possible, use the +<code>Window.setAllowEnterTransitionOverlap</code> method on the called activity. This lets you +have more dramatic enter transitions. The same applies for the calling activity and exit +transitions with the <code>Window.setAllowExitTransitionOverlap</code> method.</p> + +<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.</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.image_small); + +// 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> + +<p>To reverse the scene transition animation when you finish the second activity, call the +<code>Activity.finishAfterTransition</code> method instead of <code>Activity.finish</code>.</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, + 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>Animator.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">Animating 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 translationZ 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="translationZ" + android:duration="100" + android:valueTo="2" + 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="translationZ" + android:duration="100" + android:valueTo="2" + android:valueType="floatType"/> + </set> + </item> +</selector> +</pre> + +<p class="note"><strong>Note:</strong> There is a known issue in the L Developer Preview release +that requires valueFrom values to be provided in StateListAnimator animations to get the correct +behavior.</p> + +<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 or nine-patches as alpha masks and +to tint them using a color resource or a theme attribute that resolves to a color resource (for +example, <code>?android:attr/colorPrimary</code>). You can create these assets only once and color them +automatically to match your theme.</p> + +<p>To apply a tint to a bitmap, use the <code>setTint</code> method or the <code>android:tint</code> +attribute for <code>BitmapDrawable</code> and <code>NinePatchDrawable</code>.</p> + +<p>The <code>setTint</code> method also lets you set the Porter-Duff mode used to blend the +tint color for <code>NinePatchDrawable</code> and <code>BitmapDrawable</code> objects in your code. +To set the tint mode in your layouts, use the <code>android:tintMode</code> attribute.</p> + + +<h2 id="colorextract">Extracting Prominent Colors from an Image</h2> + +<p>The Android L Developer Preview Support Library includes the <code>Palette</code> class, +which lets you extract prominent colors from an image. This class extracts the following +prominent colors:</p> + +<ul> +<li>Vibrant</li> +<li>Vibrant dark</li> +<li>Vibrant light</li> +<li>Muted</li> +<li>Muted dark</li> +<li>Muted light</li> +</ul> + +<p>To extract these colors, pass a <code>Bitmap</code> object to the +<code>Palette.generate</code> static method in the background thread where you load your images. +If you can't use that thread, call the <code>Palette.generateAsync</code> method instead and +provide a listener.</p> + +<p>To retrieve the prominent colors from the image, use the getter methods in the +<code>Palette</code> class, such as <code>Palette.getVibrantColor</code>.</p> + +<p>For more information, see the API reference for the +<code>android.support.v7.graphics.Palette</code> class.</p>
\ No newline at end of file diff --git a/docs/html/preview/material/compatibility.jd b/docs/html/preview/material/compatibility.jd new file mode 100644 index 0000000..fb97112 --- /dev/null +++ b/docs/html/preview/material/compatibility.jd @@ -0,0 +1,82 @@ +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 activity transitions) 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> + +<p>To avoid duplication of code, define your styles inside <code>res/values/</code> and modify the +styles in <code>res/values-v21/</code> for the new APIs.</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 with +these limitations:</p> + +<ul> +<li><code>CardView</code> falls back to a programmatic shadow implementation using additional padding.</li> +<li><code>CardView</code> does not clip its children views that intersect with rounded corners.</li> +</ul> + +<p>These limitations do not apply to the Android L Developer Preview.</p> + + +<h2 id="animation">Animation APIs</h2> + +<p>The following new APIs are only available in the Android L Developer Preview:</p> + +<ul> +<li>Activity transitions</li> +<li>Touch feedback</li> +<li>Reveal animations</li> +<li>Path-based animations</li> +</ul> + +<p>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..7d0625e --- /dev/null +++ b/docs/html/preview/material/get-started.jd @@ -0,0 +1,147 @@ +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 Elevation in Your Views</a></li> + <li><a href="#widgets">Use the New UI Widgets</a></li> + <li><a href="#animations">Customize Your Animations</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="http://www.google.com/design/spec">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>elevation</strong> of your 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 APIs to customize the <strong>animations</strong> 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 <a +href="http://www.google.com/design/spec">material design guidelines</a> provide you with a +cohesive 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 <a href="http://www.google.com/design/spec">material design guidelines</a>. 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> + + +<h2 id="depth">Specify Elevation in Your Views</h2> + +<p>Views can cast shadows, and the elevation value of a view +determines the size of its shadow and its drawing order. To set the elevation of a view, use the +<code>android:elevation</code> attribute in your layouts:</p> + +<pre> +<TextView + android:id="@+id/my_textview" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/next" + android:background="@color/white" + <strong>android:elevation</strong>="5dp" /> +</pre> + +<p>The new <code>translationZ</code> property lets you create animations that reflect temporary +changes in the elevation of a view. For example, this is useful to respond to touch gestures.</p> + +<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><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="animations">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..f1018af --- /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..4ed7d5c --- /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..19752a8 --- /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..bd107ff --- /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..d9a276f --- /dev/null +++ b/docs/html/preview/material/index.jd @@ -0,0 +1,128 @@ +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="http://www.google.com/design/spec">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" width="500" height="238"/> + <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" width="500" height="238"/> + <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" width="500" height="426"/> + <p>The new <code>RecyclerView</code> widget is a more advanced version of <code>ListView</code> + that 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" width="500" height="426"/> + <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 properties, views in the Android L Developer Preview have a Z +property. This new property represents the elevation of a view, which determines:</p> + +<ul> +<li>The size of the shadow - Views with higher Z values cast bigger shadows.</li> +<li>The drawing order - Views with higher Z values appear on top of other views.</li> +</ul> + +<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 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 more natural animations 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> + +<p>Touch feedback animations are built into several standard views, such as buttons. The new APIs +let you customize these animations and add animations to your custom views.</p> + + +<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 create these assets only +once and color each instance to match your theme. Drawables also now support specifying most XML +properties as <strong>theme attributes</strong>.</p> + +<p>The Android L Developer Preview Support Library includes a <strong>color extraction</strong> +library that lets you automatically extract prominent colors from a bitmap image.</p>
\ No newline at end of file diff --git a/docs/html/preview/material/theme.jd b/docs/html/preview/material/theme.jd new file mode 100644 index 0000000..740bf56 --- /dev/null +++ b/docs/html/preview/material/theme.jd @@ -0,0 +1,102 @@ +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 Individual Views</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>You can customize the look of the material theme +according to your brand identity with a color palette you control. You can tint the action bar and +the status bar using theme attributes, as shown in Figure 1.</p> + +<div style="float:right;margin-left:25px;margin-top:-50px"> +<img src="{@docRoot}preview/material/images/ThemeColors.png" style="width:250px"/> +<p class="img-caption" style="margin-bottom:0px"> +<strong>Figure 1.</strong> Customizing the material theme.</p> +</div> + +<p>The system widgets have a new design and touch feedback animations. 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.style</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 style="margin-bottom:30px">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 status bar, contextual app bars) --> + <item name="android:colorPrimaryDark">@color/primary_dark</item> + <!-- theme UI controls like checkboxes and text fields --> + <item name="android:colorAccent">@color/accent</item> + </style> +</resources> +</pre> + + +<h2 id="statusbar">Customize the Status and Navigation Bar</h2> + +<p>The material theme lets you easily customize the status bar, so you can specify a +color that 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. By default, <code>android:statusBarColor</code> inherits the +value of <code>android:colorPrimaryDark</code>.</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> and adjust the window flags as required. 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> + +<p>When customizing the navigation and status bars, make them both transparent or modify only +the status bar. The navigation bar should remain black in all other cases.</p> + + +<h2 id="inheritance">Theme Individual Views</h3> + +<p>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..31604d6 --- /dev/null +++ b/docs/html/preview/material/ui-widgets.jd @@ -0,0 +1,198 @@ +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 style by default.</p> + + +<h2 id="recyclerview">RecyclerView</h2> + +<p><code>RecyclerView</code> is a more advanced and flexible 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 layout manager 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. 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. For more +information, see the <a href="#rvexamples">examples</a> 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 <code>LinearLayoutManager</code>, which shows the items in a +vertical or horizontal scrolling list. To create a custom layout, you extend the +<code>RecyclerView.LayoutManager</code> class.</p> + +<h3>Animations</h3> + +<p>Animations for adding and removing items are enabled by default in <code>RecyclerView</code>. +To customize these animations, extend the <code>RecyclerView.ItemAnimator</code> class and use +the <code>RecyclerView.setItemAnimator</code> method.</p> + +<h3 id="rvexamples">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 Activity { + 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 you know that changes in content + // do not change the size of the RecyclerView + 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 = LayoutInflater.from(parent.getContext()) + .inflate(R.layout.my_text_view, null); + // 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 cards that have a consistent look on any app. <code>CardView</code> widgets can have +shadows and rounded corners.</p> + +<p>To create a card with a shadow, use the <code>android:elevation</code> attribute. +<code>CardView</code> uses real elevation and dynamic shadows +and falls back to a programmatic shadow implementation on earlier versions. For more information, +see <a href="{@docRoot}preview/material/compatibility.html">Compatibility</a>.</p> + +<p>Here's how to specify properties of <code>CardView</code>:</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> + <li>To set the background color of a card, use the <code>android:cardBackgroundColor</code> +attribute.</li> +</ul> + +<p>To include a <code>CardView</code> in your layout:</p> + +<pre> +<!-- A CardView that contains a TextView --> +<android.support.v7.widget.CardView + xmlns:card_view="http://schemas.android.com/apk/res-auto" + 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..f7682f5 --- /dev/null +++ b/docs/html/preview/material/views-shadows.jd @@ -0,0 +1,95 @@ +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>The elevation 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> + +<p>Elevation is also useful to create animations where widgets temporarily rise above the +view plane when performing some action.</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 new <code>ViewPropertyAnimator.z</code> and <code>ViewPropertyAnimator.translationZ</code> +methods enable you to easily animate the elevation of views. For more information, see +the API reference for <code>ViewPropertyAnimator</code> and the <a +href="{@docRoot}guide/topics/graphics/prop-animation.html#object-animator">Property Animation</a> +developer guide.</p> + +<p>The Z values are measured in the same units as the X and Y values.</p> + + +<h2 id="shadows">Shadows and Outlines</h2> + +<p>The bounds of a view's background drawable determine the default shape of its shadow. +<strong>Outlines</strong> represent the outer shape of a graphics object and define the ripple +area for touch feedback.</p> + +<p>For example, if you define a view with a background drawable:</p> + +<pre> +<TextView + android:id="@+id/myview" + ... + android:elevation="2dp" + android:background="@drawable/myrect" /> +</pre> + +<p>where the background drawable is defined as a rectangle with rounded corners:</p> + +<pre> +<!-- res/drawable/myrect.xml --> +<shape xmlns:android="http://schemas.android.com/apk/res/android" + android:shape="rectangle"> + <solid android:color="#42000000" /> + <corners android:radius="5dp" /> +</shape> +</pre> + +<p>Then this view and drawable cast the appropiate shadow.</p> + +<p>You can also create outlines in your code using the methods in the <code>Outline</code> class, +and you can assign them to views with the <code>View.setOutline</code> method.</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>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 clip a view to the shape of a drawable, set the drawable as the background of the view +(as shown above) and call the <code>View.setClipToOutline</code> method.</p> + +<p>Because clipping views is an expensive operation, don't animate the shape you use to +clip a view. To achieve this effect, use a <a +href="{@docRoot}preview/material/animations.html#reveal">Reveal Effect</a> animation.</p>
\ 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..a292146 --- /dev/null +++ b/docs/html/preview/preview_toc.cs @@ -0,0 +1,101 @@ +<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 SDK + </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/design/index.html"> + Design</a></div> + <ul> + <li><a href="<?cs var:toroot ?>preview/tv/design/principles.html"> + Creative Vision</a></li> + <li><a href="<?cs var:toroot ?>preview/tv/design/patterns.html"> + UI Patterns</a></li> + <li><a href="<?cs var:toroot ?>preview/tv/design/style.html"> + Style</a></li> + </ul> + </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/reference.html">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/license.html">License Agreement</a> + </div> + </li> + <li class="nav-section" style="margin: 20px 0 0 3px;"> + <div class="nav-section-header paging-links empty"> + <a href="<?cs var:toroot ?>index.html" class="prev-page-link">Developer Home</a> + </div> + </li> +</ul> diff --git a/docs/html/preview/reference.jd b/docs/html/preview/reference.jd new file mode 100644 index 0000000..f70f7a2 --- /dev/null +++ b/docs/html/preview/reference.jd @@ -0,0 +1,13 @@ +page.title=Reference + +@jd:body + +<p>The reference documentation and API difference report are available as downloadable packages. +</p> + +<ul> + <li><a href="{@docRoot}preview/l-developer-preview-reference.zip">L + Developer Preview reference</a></li> + <li><a href="{@docRoot}preview/l-developer-preview-api-diff.zip">L + Developer Preview difference report</a></li> +</ul>
\ No newline at end of file diff --git a/docs/html/preview/samples.jd b/docs/html/preview/samples.jd new file mode 100644 index 0000000..635f49e --- /dev/null +++ b/docs/html/preview/samples.jd @@ -0,0 +1,248 @@ +page.title=Samples + +@jd:body + +<p>The following code samples are provided for the L Developer Preview. You can +download them with the Android SDK Manager.</p> + +<p>To import a downloaded project:<p> + +<div class="toggle-content closed"> +<p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" + />Using Android Studio</a></p> + + <div class="toggle-content-toggleme"> + + <ol> + <li>Unpack the downloaded project package.</li> + <li>In <a href="{@docRoot}sdk/installing/studio.html">Android Studio</a>, chose + <strong>File > Import Project</strong> and select the root folder of + the unpacked project. + <p>Android Studio may ask you to choose the type of project you are + importing. If it does, make sure to choose <strong>Import project from + external model</strong> and select the <strong>Gradle</strong> option. + </p> + </li> + </ol> + + </div> +</div> + +<p class="note"> + <strong>Note:</strong> At this time, the downloadable projects are designed + for use with Gradle and Android Studio. +</p> + + + + +<h3 id="BasicManagedProfile">BasicManagedProfile</h3> +<div class="figure" style="width:220px"> + <img src="{@docRoot}preview/images/BasicManagedProfile.png" + srcset="{@docRoot}preview/images/hun-BasicManagedProfile@2x.png 2x" + alt="" height="375" /> + <p class="img-caption"> + <strong>Figure 1.</strong> The BasicManagedProfile sample app. + </p> +</div> + +<p>This sample demonstrates how to create a managed profile. You can also:</p> +<ul> + <li>Enable or disable other apps, and set restrictions on them.</li> + <li>Configure intents to be forwarded between the primary account and the + managed profile.</li> + <li>Wipe all the data associated with the managed profile.</li> +</ul> + +<p class="note"><strong>Note:</strong> There can be only one managed profile on + a device at a time.</p> + +<h3 id="Camera2Basic">Camera2Basic</h3> + +<!-- +<div class="figure" style="width:220px"> + <img src="" srcset="@2x.png 2x" alt="" height="375" /> + <p class="img-caption"> + <strong>Figure n.</strong> Single sentence summarizing the figure. + </p> +</div> +--> + +<p>This sample demonstrates the basic use of the Camera2 API. The sample code +demonstrates how you can display camera preview and take pictures.</p> + + + +<h3 id="Camera2Video">Camera2Video</h3> +<!-- +<div class="figure" style="width:220px"> +<img src="" srcset="@2x.png 2x" alt="" height="375" /> + <p class="img-caption"> + <strong>Figure n.</strong> Single sentence summarizing the figure. + </p> +</div> +--> +<p>This sample demonstrates how to record video using the Camera2 API.</p> + + +<h3 id="ActivitySceneTransitionBasic">ActivitySceneTransitionBasic</h3> +<div class="figure" style="width:220px"> + <img src="{@docRoot}preview/images/ActivitySceneTransitionBasic.png" + srcset="{@docRoot}preview/images/ActivitySceneTransitionBasic@2x.png 2x" + alt="" height="375" /> + <p class="img-caption"> + <strong>Figure 2.</strong> The ActivitySceneTransitionBasic sample app. + </p> + </div> + +<p> This sample demonstrates how to the use {@link android.app.Activity} scene +transitions when transitioning from one activity to another. Uses a combination +of <code>moveImage</code> and <code>changeBounds</code> to nicely transition +from a grid of images to an activity with a large image and detail text. </p> + + +<h3 id="ElevationBasic">ElevationBasic</h3> +<!-- +<div class="figure" style="width:220px"> +<img src="" srcset="@2x.png 2x" alt="" height="375" /> + <p class="img-caption"> + <strong>Figure n.</strong> Single sentence summarizing the figure. + </p> +</div> +--> +<p> +This sample demonstrates two alternative ways to move a view in the z-axis:</p> + +<ul> + <li>With a fixed elevation, using XML.</li> + <li>Raising the elevation when the user taps on it, using + <code>setTranslationZ()</code>.</li> +</ul> + + + +<h3 id="ElevationDrag">ElevationDrag</h3> +<!-- +<div class="figure" style="width:220px"> + <img src="" srcset="@2x.png 2x" alt="" height="375" /> + <p class="img-caption"> + <strong>Figure n.</strong> Single sentence summarizing the figure. + </p> +</div> +--> + +<p>This sample demonstrates a drag and drop action on different shapes. +Elevation and z-translation are used to render the shadows. The views are +clipped using different outlines.</p> + + + +<h3 id="ClippingBasic">ClippingBasic</h3> +<!-- +<div class="figure" style="width:220px"> + <img src="" srcset="@2x.png 2x" alt="" height="375" /> + <p class="img-caption"> + <strong>Figure n.</strong> Single sentence summarizing the figure. + </p> +</div> +--> +<p> +This sample demonstrates clipping on a {@link android.view.View}. +</p> + + + +<h3 id="GameControllerSample">GameControllerSample</h3> +<!-- +<div class="figure" style="width:220px"> + <img src="" srcset="@2x.png 2x" alt="" height="375" /> + <p class="img-caption"> + <strong>Figure n.</strong> Single sentence summarizing the figure. + </p> +</div> +--> +<p> +This sample implements a multi-player game, demonstrating game controller input +handling. +</p> + + + +<h3 id="Visual-Game-Controller">Visual-Game-Controller</h3> +<!-- +<div class="figure" style="width:220px"> + <img src="" srcset="@2x.png 2x" alt="" height="375" /> + <p class="img-caption"> + <strong>Figure n.</strong> Single sentence summarizing the figure. + </p> +</div> +--> +<p> +This sample displays events received from a game controller shown on the screen. +</p> + + + +<h3 id="AndroidTVLeanbackSample">AndroidTVLeanbackSample</h3> +<!-- +<div class="figure" style="width:220px"> + <img src="" srcset="@2x.png 2x" alt="" height="375" /> + <p class="img-caption"> + <strong>Figure n.</strong> Single sentence summarizing the figure. + </p> +</div> +--> +<p> +This sample demonstrates use of the Android TV Leanback Support Library. +</p> + + + +<h3 id="JobSchedulerSample">JobSchedulerSample</h3> + +<div class="figure" style="width:220px"> + <img src="{@docRoot}preview/images/JobSchedulerSample.png" + srcset="{@docRoot}preview/images/JobSchedulerSample@2x.png 2x" + alt="" height="375" /> + <p class="img-caption"> + <strong>Figure 3.</strong> The JobSchedulerSample sample app. + </p> +</div> + +<p> +This sample app allows the user to schedule jobs through the UI, and shows +visual cues when the jobs are executed. +</p> + + + +<h3 id="NavigationDrawerSample">NavigationDrawerSample</h3> +<!-- +<div class="figure" style="width:220px"> + <img src="" srcset="@2x.png 2x" alt="" height="375" /> + <p class="img-caption"> + <strong>Figure n.</strong> Single sentence summarizing the figure. + </p> +</div> +--> +<p> +This sample illustrates a common usage of the Android support library's +{@link android.support.v4.widget.DrawerLayout} widget. +</p> + + +<!-- +<h3 id="">SampleName</h3> + +<div class="figure" style="width:220px"> + <img src="" srcset="@2x.png 2x" alt="" height="375" /> + <p class="img-caption"> + <strong>Figure n.</strong> Single sentence summarizing the figure. + </p> +</div> + +<p> +**description** +</p> +--> diff --git a/docs/html/preview/setup-sdk.jd b/docs/html/preview/setup-sdk.jd new file mode 100644 index 0000000..876b348 --- /dev/null +++ b/docs/html/preview/setup-sdk.jd @@ -0,0 +1,144 @@ +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 id="downloadSdk">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> + +<p class="note"><strong>Note:</strong> The Eclipse ADT plug-in requires Java 7 +if your compilation target is the L developer preview.</p> + +<h2 id="setupHardware">Set Up Hardware and AVDs</h2> + +<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> + +<h3 id="installImage">Install the L Preview System Image</h3> + +<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 uncompress the Android Developer Preview package. + <p class="table-caption" id="table1"> + <strong>Table 1.</strong> L Developer Preview system images.</p> + <table> + <tr> + <th scope="col">Device</th> + <th scope="col">Download</th> + <th scope="col">MD5 Checksum</th> + <th scope="col">SHA-1 Checksum</th> + </tr> + <tr id="hammerhead"> + <td>Nexus 5 (GSM/LTE) "hammerhead"</td> + <td><!-- TODO --></td> + <td><code>5a6ae77217978cb7b958a240c2e80b57</code></td> + <td><code>ac1d8a8e4f4a1dca5864dc733caa940bffc28616</code></td> + </tr> + <tr id="razor"> + <td>Nexus 7 (Wifi) "razor"</td> + <td><!-- TODO --></td> + <td><code>b293a5d3a4e07beabebcc0be85ad68a2</code></td> + <td><code>d0ddf8ce733ba2a34279cdff8827fd604762c2342d</code></td> + </tr> + </table> + </li> + + <li>Follow the instructions at + <a href="https://developers.google.com/android/nexus/images#instructions">developers.google.com/android</a> + to flash the image onto your device.</li> +</ol> + +<h3 id="revertDevice">Revert 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> + +<h3 id="setupAVD">Set up an AVD</h3> + +<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> + +<h2 id="createProject">Create a Project</h2> + +<p>Android Studio makes it easy to create a project for the L Developer Preview. Follow +the steps described in <a href="{@docRoot}sdk/installing/create-project.html">Creating a +Project</a>. In the <strong>Form Factors</strong> screen:</p> + +<ul> + <li>Check <strong>Phone and Tablet</strong>.</li> + <li>Select <strong>API 20+: Android L (Preview)</strong> in <strong>Minimum SDK</strong>.</li> +</ul> + +<p>On the development environment, open the <code>build.gradle</code> file for your module +and make sure that:</p> + +<ul> + <li><code>compileSdkVersion</code> is set to <code>'android-L'</code></li> + <li><code>minSdkVersion</code> is set to <code>'L'</code></li> + <li><code>targetSdkVersion</code> is set to <code>'L'</code></li> +</ul> + +<p>To use the material theme, open the <code>values/styles.xml</code> in your project and make +sure that you theme extends the material theme:</p> + +<pre> +<resources> + <style name="AppTheme" parent="android:Theme.Material"> + <!-- Customize your theme here --> + </style> +</resources> +</pre> diff --git a/docs/html/preview/support.jd b/docs/html/preview/support.jd new file mode 100644 index 0000000..8efc4bc --- /dev/null +++ b/docs/html/preview/support.jd @@ -0,0 +1,108 @@ +page.title=Support + +@jd:body + +<p>If you've encountered bugs or have feedback about the L Developer Preview, +<a href="https://code.google.com/p/android-developer-preview/">create an issue</a> on +our issue tracker.</p> + +<p>For more support, +<a href="https://plus.google.com/communities/113159138894928487684">join +the L Developer Preview Google+ community</a> to discuss your development experiences. + + +<h2 id="ReleaseNotes">Release Notes</h2> +<p>June 25, 2014 - Initial Release of the L Developer Preview</p> + +<h3 id="UserInterface">User interface</h3> +<ul> +<li>If your app launches an activity with +{@link android.app.Activity#startActivity startActivity()} +and an {@link android.content.Intent} set to +{@link android.content.Intent#FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET}, the +activity shows up as a separate task in the Recent apps screen. This is the +same behavior as though your app used {@code Intent.FLAG_ACTIVITY_NEW_DOCUMENT} +(see <a href="{@docRoot}preview/api-overview.html#Recents">Concurrent +documents and activities in the Recents screen</a>). If you want your activity +to remain in the same task that launched it, use +{@link android.app.Activity#startActivityForResult +startActivityForResult()} instead.</li> +<li>System-rendered shadows for user interface (UI) elements in views may +appear with visible spiky edges. To avoid this visual artifact, use a higher +<a href="{@docRoot}preview/material/views-shadows.html#elevation">view +elevation</a>.</li> +<li>On very tall or wide views, view shadows may appear with additional rough +visual artifacts around the view edges. To minimize this, avoid using view +shadows with very narrow views.</li> +<li>The {@code android.graphics.drawable.RippleDrawable} class does not +respond to pointer location changes, except when the drawable is set as a +{@link android.view.View} background.</li> +</ul> + +<h3 id="Multimedia">Multimedia</h3> +<ul> +<li>The {@code android.hardware.camera2} APIs are supported only on Nexus 5 +devices.</li> +<li>Saving a DNG file with the new {@code android.hardware.camera2.DngCreator} +API fails if lens shading compensation map generation is not enabled. To +capture images to DNG files, add the following code when creating your capture +requests: +<pre> +CaptureRequest.Builder stillCaptureRequest = + mCameraDevice.createCaptureRequest(CameraDevice.TEMPLATE_STILL_CAPTURE); + +stillCaptureRequest.set(CaptureRequest.STATISTICS_LENS_SHADING_MAP_MODE, + CaptureRequest.STATISTICS_LENS_SHADING_MAP_MODE_ON); +</pre></li> +<li>The {@code android.media.AudioTrack.write(float[], int, int, int)} method +currently does not work. Use the +{@link android.media.AudioTrack#write(short[], int, int) +AudioTrack.write(short[], int, int)} method instead.</li> +<li>Lockscreen security is currently not enforced when users start a Android +mirroring session from the Quick Settings shade.</li> +</ul> + +<h3 id="UserInput">User input</h3> +<ul><li>The System UI may crash unexpectedly while the device is charging, if + the locale is set to {@code fr} (FRENCH).</li></ul> + +<h3 id="Wireless">Wireless and Connectivity</h3> +<ul> +<li>The {@code android.bluetooth.le} APIs are supported only on Nexus 5 +devices.</li> +<li>You might encounter these issues while using Bluetooth LE scanning: + <ul> + <li><em>Settings</em> does not show all Bluetooth LE devices when a scan + filter is set.</li> + <li>System returns non-intuitive error messages during a Bluetooth LE scan, + when Bluetooth is off.</li> + <li>The {@code BluetoothLeScanner.startScan()} method starts failing after + six concurrent scans with different callbacks.</li> + </ul> +</li> +<li>You might encounter these issues while using Bluetooth LE advertising: + <ul> + <li>The device MAC address does not change for multiple advertising + when the application processor is asleep.</li> + <li>The TX Power Level is always 0 in advertising packets.</li> + </ul> +</li> +</ul> + +<h3 id="Enterprise">Enterprise</h3> +<ul> +<li>The device may crash unexpectedly in these situations when using +Android work functionality: +<ul> +<li>The user attempts to share a web page (via <strong>Menu > Share</strong>) +from a non-Android work Chrome app to a Android work profile Gmail app.</li> +<li>The user attempts to share a web page via Bluetooth from a +Android work profile +Chrome app.</li> +<li>The user attempts to share a web page via Android Beam from a +Android work profile Chrome app.</li> +</ul> +</li> +<li>Deleting a Android work profile may take several minutes to complete. You +cannot create a new Android work profile until the deletion operation is over.</li> +</ul> diff --git a/docs/html/preview/tv/adt-1/index.jd b/docs/html/preview/tv/adt-1/index.jd new file mode 100644 index 0000000..d83dd11 --- /dev/null +++ b/docs/html/preview/tv/adt-1/index.jd @@ -0,0 +1,282 @@ +page.title=ADT-1 Developer Kit +page.tags="emote","e-mote","adt" + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#faq">Frequently Asked Questions</a> + <ol> + <li><a href="#setup">Device Setup</a></li> + <li><a href="#input">User Input</a></li> + <li><a href="#cast">Google Cast</a></li> + <li><a href="#trouble">Troubleshooting</a></li> + </ol> + </li> + <li><a href="#emote">Android TV Remote Control App</a></li> + <li><a href="#reg-safety">Regulatory Disclosures and Safety</a></li> + </ol> +</div> +</div> + +<p>The ADT-1 Developer Kit is a streaming media player and game controller designed for running +and testing apps built for Android TV. Supplies of ADT-1 are limited and it is intended for +developers who are interested in building new apps or extending their existing apps to run on the +Android TV platform.</p> + +<p class="note"> + <strong>Note:</strong> The ADT-1 kit <em>is not required</em> for building and testing apps + for Android TV. You can build apps for TV and test them using an emulator for TV devices. The + L Developer Preview includes all the software needed to build TV apps and an emulator for running + and testing them. For more information, see the + <a href="{@docRoot}preview/tv/start/index.html">Get Started</a> guide for TV apps. +</p> + +<h2 id="faq">ADT-1 Frequently Asked Questions</h2> + +<p>The following information is provided to help set up and use the ADT-1 device.</p> + + +<h3 id="setup">Device Setup</h3> + +<p> + <strong>How do I turn my device on?</strong> +</p> +<p>Plug the included power cable into the back of ADT-1. The device does not have an on/off + switch.</p> + +<p> + <strong>How do I completely turn my device off? </strong> +</p> +<p>Unplug the included power cable from the back of ADT-1. The device does not have an on/off + switch. However, ADT-1 will begin sleeping (daydream) based on user settings in + <strong>Settings > Display > Daydream</strong>. + </p> + +<p> + <strong>How do I connect to the network?</strong> +</p> +<p>ADT-1 has both wireless and Ethernet for connecting to your network. To change your wireless + network, go to <strong>Settings -> Wi-Fi</strong>. To use an Ethernet network connection, + simply plug an Ethernet cable (that is connected to your network) into the port on the back of + ADT-1.</p> + +<p> + <strong>How do I use the developer cable?</strong> +</p> +<p>The developer cable has three connectors: a small, male power connector that plugs into the + power port on the back of ADT-1, a standard male USB-A connector that connects your PC, and a + small, female power connector that the included power supply plugs into.</p> + + + +<h3 id="input">User Input</h3> + +<p> + <strong>How do I put the gamepad that came with my ADT-1 into pairing mode?</strong> +</p> +<p>Press and hold the Back and Home buttons together for about three seconds, until all four + blue LEDs flash together. When the LEDs are flashing, the gamepad is in pairing mode.</p> + +<p> + <strong>How do I use the gamepad with the on-screen keyboard?</strong> +</p> +<p>Use the D-pad or left joystick to move the cursor, and press A to select. Press X to delete a + character, and press Y to insert a space. Also, you can press the right joystick to toggle caps + lock, and press the left joystick to show additional symbols.</p> + +<p> + <strong>Can I control ADT-1 with my phone or tablet?</strong> +</p> +<p>Yes. In order to control the ADT-1 with Android phones or tablets, you can download a remote + control app from the Google Play store. For more information, see <a href="#emote">Android TV + Remote Control App</a>. + </p> + +<p> + <strong>Can I connect a USB keyboard or mouse to ADT-1?</strong> +</p> +<p>Yes, you can connect a USB keyboard or mouse to the USB port on the back of ADT-1. + +<p class="note"> + <strong>Note:</strong> The ADT-1 device is not compatible with all manufacturers and models of + these devices. If a particular keyboard or mouse does not work, try a different model. +</p> + +<p> + <strong>How do I connect a Bluetooth device without an input device already attached?</strong> +</p> +<p>You can put ADT-1 into Bluetooth pairing mode using a hardware button. Press the small, round + button on the back of ADT-1 to make it search for Bluetooth devices in pairing mode. If multiple + accessories are found, press the small, round button to select the device you want to pair. + Pairing will happen automatically after a few seconds. +</p> + +<p> + <strong>How do I connect additional Bluetooth accessories?</strong> +<p> +<p>To pair Bluetooth devices to ADT-1 from the user interface, go to <strong>Settings > + Remote & Accessories > Add accessory</strong> + + +<h3 id="cast">Google Cast</h3> + +<p> + <strong>Can I cast to an ADT-1 device?</strong> +<p> +<p>Yes. The ADT-1 includes Google Cast receiver functionality, similar to Chromecast. Since the + ADT-1 is a developer device running a development software release, the Google Cast receiver is + open only to a limited number of apps.</p> + +<p> + <strong>Which Cast apps are supported on ADT-1?</strong> +<p> +<p>As a developer device, the ADT-1 supports casting from only the following apps/websites:</p> + +<ul> + <li>YouTube</li> + <li>Netflix</li> + <li>Google+ Photos</li> + <li>Google Play Movies and TV (Android only)</li> +</ul> + +<p>Coming soon:</p> + +<ul> + <li>Google Play Music</li> + <li>Google Play Movies and TV (iOS and Chrome)</li> + <li>Mirror you Android device screen to ADT-1</li> +</ul> + +<p class="note"> + <strong>Note:</strong> When casting from a Chrome browser, you must use Chrome V.36 or higher. + Chrome V.36 is available in beta-channel and is planned to be released soon. +</p> + +<p> + <strong>How do I cast to ADT-1?</strong> +<p> +<p>You cast to an ADT-1 device the same way you do with a Chromecast device. Open the supported + Cast apps or webpages, press the <strong>Cast</strong> button and you should see the ADT-1 as a + Cast target. For more infomation about on how to cast, see + <a href="http://www.google.com/intl/en/chrome/devices/chromecast/learn.html">Learn How to + Cast</a>. + </p> + +<p> + <strong>Will my Google Cast sender apps work on ADT-1 just like Chromecast?</strong> +<p> +<p>Yes. Your Cast app works on ADT-1 and Android TV products without additional work.<p> + +<p class="note"> + <strong>Note:</strong> Your iOS sender app requires the Google Cast iOS API version 2.2.1 + or later to work with the ADT-1 device. +</p> + +<p> + <strong>How do I register my ADT-1 in order to run my apps?</strong> +</p> +<ol> + <li>Go to <strong>Settings > Google Cast</strong> and turn on developer support, allowing the + ADT-1 device to send its serial number to Google.</li> + <li>Register your ADT-1 device in the Google Cast Developer Console, using the 12 character + serial number engraved on the back of the ADT-1.</li> +</ol> + +<p>For more Google Cast developer information, see the + <a href="https://developers.google.com/cast/">Cast developer site</a>. Please use the Google Cast + SDK <a href="https://code.google.com/p/google-cast-sdk/issues/list">issue tracker</a> for filing + issues related to Cast. Make sure you mention the ADT-1 device when filing an issue. +</p> + +<p> + <strong>How do I debug my Cast app on ADT-1?</strong> +</p> +<p>Connect your development platform using the power/USB cable, and using a Chrome browser, + navigate to <code>chrome://inspect/#devices</code> to debug the webview.</p> + + +<h3 id="trouble">Troubleshooting</h3> + +<p> + <strong>Why doesn't the on-screen keyboard come up?</strong> +</p> +<p>Enable the keyboard in the device Settings. Go to <strong>Settings > Keyboard > Current + keyboard</strong> and choose <strong>Leanback keyboard</strong>. + +<p> + <strong>How do I perform a hardware reboot?</strong> +</p> +<p>Locked it up, huh? No worries. We've done that a few times ourselves. Unplug and replug the + included power cable from the back of ADT-1 to reboot it. +</p> + +<p> + <strong>How do I perform a factory reset?</strong> +</p> +<p class="warning"> + <strong>Warning:</strong> This procedure removes all data from the device, including system + data, downloaded apps, app data, and account settings. +</p> + +<p>From the home screen, go to <strong>Settings > Device > Factory data reset</strong>, and + select <strong>Reset device</strong>. +</p> + +<p> + <strong>How do I perform a hardware reset?</strong> +</p> +<p class="warning"> + <strong>Warning:</strong> This procedure performs a factory data reset, removing all data from + the device, including system data, downloaded apps, app data, and account settings. +</p> + +<p>Unplug the power cable from the back of ADT-1. Press and hold the small, round button on the + back of ADT-1 as you re-insert the power cable, and continue to hold the small round button. The + LED will begin flashing red for a few seconds, then change to multi-color cycle. When the LED + starts the multi-color cycle, release the small, round button, and ADT-1 boots up. If you release + the button while the LED is flashing red, the device will be in Fastboot mode.</p> + +<p> + <strong>There is a hardware problem with my ADT-1. How do I return it?</strong> +</p> +<p>You can request a return of the device using the + <a href="https://support.google.com/googleplay/android-developer/contact/adt_rma">return + merchandise authorization form</a>. +</p> + + +<h2 id="emote">Android TV Remote Control App</h2> + +<div class="figure" style="width:250px;margin-top:0"> +<img src="/preview/tv/images/android-tv-remote.png" alt="Android TV Remote Screenshots"> +</div> + +<p>A remote control app is available for Android phones and tablets that allows you to interact + with the ADT-1 device. This app allows you to switch between D-pad input mode or touchpad mode + to navigate content and play games on a Android TV device. You can also tap the mic button to + start a voice search, or use the keyboard to input text using this app.</p> + +<p>You download the remote control app from the Google Play store using + <a href="https://play.google.com/store/apps/details?id=com.google.android.tv.remote">this + link</a>. +</p> + +<p class="note"> + <strong>Note:</strong> your Android phone or tablet must be connected to the same local network + as ADT-1. +</p> + + +<h2 id="reg-safety">Regulatory Disclosures and Safety Information</h2> + +<p>The ADT-1 device comes with important regulatory disclosures and safety information. Please +read this information before using the device:</p> + +<ul> + <li><a href="regulatory.html">Regulatory Disclosures</a></li> + <li><a href="safety.html">Important Safety Information</a></li> +</ul> + diff --git a/docs/html/preview/tv/adt-1/regulatory.jd b/docs/html/preview/tv/adt-1/regulatory.jd new file mode 100644 index 0000000..2f5bf7e --- /dev/null +++ b/docs/html/preview/tv/adt-1/regulatory.jd @@ -0,0 +1,79 @@ +page.title=Regulatory Disclosures for ADT-1 +parent.title=ADT-1 Developer Kit +parent.link=index.html + +@jd:body + +<p>Disclosures for the <a href="index.html">ADT-1</a> device.</p> + +<p> + Model: W2<br> + FCC ID: A4R-W2<br> + IC: 10395A-W2 +</p> + +<p>U.S. Federal Communications Commission Notices</p> +<p>To satisfy FCC and IC exposure requirements, a separation distance of at least 20 cm should + be maintained between the antenna of this device and persons during device operation. Operations + at closer than this distance are not recommended.</p> +<p>The antenna used for this transmitter must not be co-located in conjunction with any other + antenna or transmitter.</p> +<p>This equipment has been tested and found to comply with the limits for a Class B digital + device, pursuant to part 15 of the FCC Rules. These limits are designed to provide reasonable + protection against harmful interference in a residential installation. This equipment generates, + uses and can radiate radio frequency energy and, if not installed and used in accordance with the + instructions, may cause harmful interference to radio communications. However, there is no + guarantee that interference will not occur in a particular installation. If this equipment does + cause harmful interference to radio or television reception, which can be determined by turning + the equipment off and on, the user is encouraged to try to correct the interference by one or more + of the following measures:</p> +<p>—Reorient or relocate the receiving antenna.</p> +<p>—Increase the separation between the equipment and receiver.</p> +<p>—Connect the equipment into an outlet on a circuit different from that to which the receiver + is connected.</p> +<p>—Consult the dealer or an experienced radio/ TV technician for help.</p> +<p>This device complies with part 15 of the FCC Rules. Operation is subject to the following two + conditions: (1) This device may not cause harmful interference, and (2) this device must accept + any interference received, including interference that may cause undesired operation.</p> +<p>Changes or modifications not expressly approved by Google Inc. could void the user's + authority to operate the equipment.</p> +<p>Industry Canada Notices</p> +<p>This device complies with Industry Canada licence-exempt RSS standard(s). Operation is + subject to the following two conditions: (1) this device may not cause interference, and (2) this + device must accept any interference, including interference that may cause undesired operation of + the device.</p> +<p>Under Industry Canada regulations, this radio transmitter may only operate using an antenna + of a type and maximum (or lesser) gain approved for the transmitter by Industry Canada. To reduce + potential radio interference to other users, the antenna type and its gain should be so chosen + that the equivalent isotropically radiated power (e.i.r.p.) is not more than that necessary for + successful communication.</p> +<p>The radiated output power of the Wireless Device is below the Industry Canada (IC) radio + frequency exposure limits. The Wireless Device should be used in such a manner such that the + potential for human contact during normal operation is minimized.</p> + +<hr /> + +<p>CAN ICES-3 (B)/NMB-3(B)</p> +<p> + <u>Avis d’<em>Industrie Canada</em></u> +</p> +<p> + Le présent appareil est conforme aux <em>CNR</em> d'Industrie Canada applicables aux appareils + radio exempts de licence. L'exploitation est autorisée aux deux conditions suivantes : (1) + l'appareil ne doit pas produire de brouillage, et (2) l'appareil doit accepter tout brouillage + radioélectrique subi, même si le brouillage est susceptible d'en compromettre le fonctionnement. +</p> +<p> + En vertu de la règlementation d’<em>Industrie Canada</em>, cet émetteur radio peut + fonctionner avec une antenne d'un type et d'un gain maximal (ou inférieur) approuvé pour + l'émetteur par <em>Industrie Canada</em>. Dans le but de réduire les risques de brouillage + radioélectrique à l'intention des autres utilisateurs, il faut choisir le type d'antenne et son + gain de sorte que la puissance isotrope rayonnée équivalente (p.i.r.e.) ne dépasse pas l'intensité + nécessaire à l'établissement d'une communication satisfaisante. +</p> +<p> + La puissance rayonnée en sortie de l'appareil sans fil est inférieure aux limites fixées par + <em>Industrie Canada</em> en matière d'exposition aux radiofréquences. L'appareil sans fil + doit être utilisé de sorte que la possibilité d'un contact humain pendant le fonctionnement + normal soit limitée. +</p> diff --git a/docs/html/preview/tv/adt-1/safety.jd b/docs/html/preview/tv/adt-1/safety.jd new file mode 100644 index 0000000..1984853 --- /dev/null +++ b/docs/html/preview/tv/adt-1/safety.jd @@ -0,0 +1,140 @@ +page.title=Important Safety Instructions for ADT-1 +parent.title=ADT-1 Developer Kit +parent.link=index.html + +@jd:body + +<p>Safety information for the <a href="index.html">ADT-1</a> device.</p> + +<p> + <strong>WARNING:</strong> Read all safety information below before using this device to avoid + injury. +</p> +<ul> + <li><p>Do not install near heat sources, such as heaters and other devices.</p></li> + <li><p>Use in a well-ventilated area and plug power adapter into an easily accessible + outlet. Only use this device with the provided power adapter.</p></li> + <li><p>The device has no on/off switch. To disconnect from power, you must unplug the + power adapter.</p></li> + <li><p>Only use indoors and do not expose to rain, liquid, moisture, excessive heat, or + naked flame.</p></li> + <li><p>Clean only with a dry cloth.</p></li> +</ul> +<p> + <strong>WARNING:</strong> Playing video games has been linked to injuries in some + users. Read all safety and health information below before using the gamepad to avoid possible + injury. +</p> + +<p><u>Photosensitive Seizures</u></p> + +<p> + A very small percentage of people may experience a seizure when exposed to certain visual images, + including flashing lights or patterns that may appear in some video games, even people who have no + history of seizures or epilepsy. These seizures have a variety of symptoms, including + lightheadedness, altered vision, disorientation, loss of awareness, involuntary movements, loss of + consciousness, or convulsions. If you experience any of these symptoms, <u>stop gaming + immediately and consult your doctor</u>. +</p> + +<p><u>Ergonomics</u></p> + +<p>Long periods of repetitive motion using incorrect body positioning may be associated with + physical discomfort and injuries to nerves, tendons, and muscles. If during or after gaming you + feel pain, numbness, weakness, swelling, burning, cramping, or stiffness, <u>stop gaming + and consult your doctor</u>. + +<p> + <strong>Healthy Gaming</strong> +</p> + +<p>To reduce risk of seizures or injury, take the following precautions:</p> + +<ul> + <li><p>Sit as far away from the TV screen as possible.</p></li> + <li><p>Play in a well-lit room.</p></li> + <li><p>Do not play when you are drowsy or fatigued.</p></li> + <li><p>Take 10-15 minute breaks every hour if playing video games and avoid prolonged + gaming.</p></li> +</ul> + +<p> + <strong>Do Not Attempt Repairs Yourself</strong> +</p> + +<p>There are no user-serviceable parts inside. Do not attempt to open or disassemble.</p> + +<p>Failure to follow these safety instructions could result in fire, electric shock, damage to + the device or other property, or personal injury.</p> + +<hr /> + +<p> + <strong>Importantes instructions concernant la sécurité</strong> +</p> + +<p> + <strong>ATTENTION:</strong> Veuillez lire toutes les informations de sécurité énoncées ci-bas + avant d’utiliser l’appareil pour éviter des blessures. +</p> + +<ul> + <li><p>Ne pas installer à proximité d’une source de chaleur telle une chaufferette ou un + autre appareil similaire.</p></li> + <li><p>Utiliser dans un endroit bien aéré et brancher l’adaptateur électrique dans une + prise de courant facilement accessible.</p></li> + <li><p>L’appareil ne possède aucun interrupteur marché/arrêt. Pour mettre l’appareil hors + tension, il faut débrancher l’appareil de la prise de courant.</p></li> + <li><p>Utiliser l’appareil uniquement à l’intérieur et ne pas l’exposer à la pluie, à des + substances liquides, à l’humidité, à la chaleur excessive ou à une flamme.</p></li> + <li><p>Nettoyer uniquement avec un linge sec.</p></li> +</ul> + +<p> + <strong>ATTENTION:</strong> Le fait de jouer à des jeux vidéo a été relié à des blessures chez certains + utilisateurs. Afin d’éviter de possibles blessures, veuillez lire toutes les informations + concernant la sécurité et la santé énoncées ci-bas avant d’utiliser la tablette de jeu. +</p> + +<p><u>Épilepsie photosensible</u></p> + +<p>L’exposition à certaines images visuelles, incluant les lumières ou motifs clignotants qui + peuvent apparaître dans certains jeux vidéo, peut provoquer chez un très faible pourcentage de + personnes une crise d’épilepsie, et ce, même si ces personnes n’ont aucun historique de crises ou + d’épilepsie. Ces crises comportent divers symptômes tels que des étourdissements, une vision + altérée, un sentiment de désorientation, la perte de conscience, des mouvements involontaires, la + perte de connaissance ou de conscience ou des convulsions. Si vous ressentez quelconque de ces + symptômes, <u>cessez de jouer immédiatement et consultez votre médecin</u>.</p> + +<p><u>Ergonomie</u></p> + +<p>Les longues périodes de mouvements répétitifs effectués dans une position corporelle + inadéquate peuvent mener à un inconfort physique et à des blessures aux nerfs, tendons et muscles. + Si durant ou après avoir joué à des jeux vidéo, vous ressentez de la douleur, de + l’engourdissement, une faiblesse, de l’inflammation, une sensation de brûlure, des crampes ou de + la rigidité, <u>cessez de jouer immédiatement et consultez votre médecin</u>.</p> + +<p> + <strong>Le jeu sécuritaire</strong> +</p> + +<p>Afin de réduire les risques de crises d’épilepsie ou de blessures, veuillez prendre les + précautions suivantes :</p> + +<ul> + <li>Asseyez-vous aussi loin de l’écran de télévision que possible.</li> + <li>Jouez dans une pièce munie d’un éclairage adéquat.</li> + <li>Ne jouez pas lorsque vous êtes étourdi ou fatigué.</li> + <li>Prenez 10 à 15 minutes de pause après chaque heure de jeu et évitez les périodes de jeu + prolongées.</li> +</ul> + +<p> + <strong>Ne pas tenter d’effectuer des réparations par vous-même</strong> +</p> + +<p>L’Appareil ne contient aucune pièce pouvant être réparée par l’utilisateur. Ne pas tenter + d’ouvrir ou de désassembler l’Appareil.</p> + +<p>Le défaut de suivre ces instructions de sécurité pourrait provoquer un feu, un choc + électrique, un dommage à l’Appareil ou à d’autres objets ou des lésions corporelles.</p> diff --git a/docs/html/preview/tv/design/images/apps-games-rows.jpg b/docs/html/preview/tv/design/images/apps-games-rows.jpg Binary files differnew file mode 100644 index 0000000..5023655 --- /dev/null +++ b/docs/html/preview/tv/design/images/apps-games-rows.jpg diff --git a/docs/html/preview/tv/design/images/atv-framed-med.png b/docs/html/preview/tv/design/images/atv-framed-med.png Binary files differnew file mode 100644 index 0000000..e06f6e7 --- /dev/null +++ b/docs/html/preview/tv/design/images/atv-framed-med.png diff --git a/docs/html/preview/tv/design/images/atv-home.jpg b/docs/html/preview/tv/design/images/atv-home.jpg Binary files differnew file mode 100644 index 0000000..4b25bab --- /dev/null +++ b/docs/html/preview/tv/design/images/atv-home.jpg diff --git a/docs/html/preview/tv/design/images/focus.png b/docs/html/preview/tv/design/images/focus.png Binary files differnew file mode 100644 index 0000000..df61f4d --- /dev/null +++ b/docs/html/preview/tv/design/images/focus.png diff --git a/docs/html/preview/tv/design/images/icon.png b/docs/html/preview/tv/design/images/icon.png Binary files differnew file mode 100644 index 0000000..ae34e18 --- /dev/null +++ b/docs/html/preview/tv/design/images/icon.png diff --git a/docs/html/preview/tv/design/images/overscan.png b/docs/html/preview/tv/design/images/overscan.png Binary files differnew file mode 100644 index 0000000..fb7e4bc --- /dev/null +++ b/docs/html/preview/tv/design/images/overscan.png diff --git a/docs/html/preview/tv/design/images/recommendations.png b/docs/html/preview/tv/design/images/recommendations.png Binary files differnew file mode 100644 index 0000000..942cd10 --- /dev/null +++ b/docs/html/preview/tv/design/images/recommendations.png diff --git a/docs/html/preview/tv/design/images/search.jpg b/docs/html/preview/tv/design/images/search.jpg Binary files differnew file mode 100644 index 0000000..c034939 --- /dev/null +++ b/docs/html/preview/tv/design/images/search.jpg diff --git a/docs/html/preview/tv/design/images/settings.jpg b/docs/html/preview/tv/design/images/settings.jpg Binary files differnew file mode 100644 index 0000000..1c5bf31 --- /dev/null +++ b/docs/html/preview/tv/design/images/settings.jpg diff --git a/docs/html/preview/tv/design/index.jd b/docs/html/preview/tv/design/index.jd new file mode 100644 index 0000000..b924a5c --- /dev/null +++ b/docs/html/preview/tv/design/index.jd @@ -0,0 +1,65 @@ +page.title=Design for TV +header.justLinks=1 +footer.hide=1 +@jd:body + + +<p>The Android TV platform user interface provides the launch pad for your app's big screen + experience. It's important to understand how your app is presented in the main user interface and + how your app can help users get to the content they want quickly.</p> + + +<h2>Home Screen</h2> + +<p>The Home Screen is the start of the user experience, providing search, content + recommendations, and access to apps and settings. This screen provides a rich and cinematic + overview of apps and content.</p> + +<img src="{@docRoot}preview/tv/design/images/atv-home.jpg" alt="TV Home screen" /> + + +<h2>Search</h2> + +<p>By bringing the power of Google search to the big screen, Android TV makes new, dynamic + connections between content. A favorite movie may lead to the discovery of a new music artist, + planning a trip to Paris might surface new YouTube content and photos.</p> + +<img src="{@docRoot}preview/tv/design/images/search.jpg" alt="Recommendations Row" /> + +<p>To learn more about searching within your app, see + <a href="{@docRoot}preview/tv/ui/in-app-search.html">Searching in TV Apps</a>. + +<h2>Recommendations</h2> + +<p>The recommendations row on Android TV is a central feature of the Home Screen that allows + users quick access to dynamic and relevant content for their media-consumption activities. The + row is optimized for quick browsing of personalized content and activity resumption (on the + device and across devices), while also providing a way for users to act on meaningful new + content.</p> + +<img src="{@docRoot}preview/tv/design/images/recommendations.png" alt="Recommendations Row" /> + +<p> + Recommendations are based on the user’s recent and frequent usage behaviors, as well as + expressed content preferences. They appear as cards that represent a system or app action, + notification, activity, or piece of actionable media. Your app can provide suggestions for the + recommendations row to help get your content noticed. To learn more, see + <a href="{@docRoot}preview/tv/ui/recommendations.html">Recommendations</a>. +</p> + + +<h2>Apps and Games</h2> + +<p>Apps and Games rows both have special areas on the Home Screen. Within their respective + areas, Apps and Games titles are ordered to reflect the user’s recent usage.</p> + +<img src="{@docRoot}preview/tv/design/images/apps-games-rows.jpg" alt="Apps and Games Rows" /> + + +<h2>Settings</h2> + +<p>Access to Settings is found at the bottom of the Home Screen. From here, the user can access + Android and device-specific settings. +</p> + +<img src="{@docRoot}preview/tv/design/images/settings.jpg" alt="Settings Row" /> diff --git a/docs/html/preview/tv/design/patterns.jd b/docs/html/preview/tv/design/patterns.jd new file mode 100644 index 0000000..cdba74c --- /dev/null +++ b/docs/html/preview/tv/design/patterns.jd @@ -0,0 +1,86 @@ +page.title=Patterns for TV +page.tags="design" +@jd:body + +<p>As a developer of apps for TV, you should follow certain patterns to enable users to + quickly understand and operate your app. This section describes recommended design patterns + for TV apps.</p> + +<h2>Navigation, Focus and Selection</h2> + +<p>Users typically navigate TV devices using a directional pad (D-Pad). This type of controller + limits movement to up, down, left, and right. As you design your app for TV, make sure your + user interface has clear paths for two-axis navigation by aligning objects in lists and + grids.</p> + +<img src="{@docRoot}preview/tv/design/images/focus.png" alt="TV navigation and focus diagram" /> + +<p>A key aspect of making your application work well with a D-Pad controller is to make sure + that there is always an object that is obviously in focus. Your app must clearly indicate + what object is focused, so users can easily see what action they can take. Use scale, shadow + brightness, opacity, animation or a combination of these attributes to help users see a focused + object.</p> + + +<h2>Icons</h2> + +<p>Apps on TV devices require some additional icon images for presentation in the system + user interface, including home screen launcher images (banners) and recommendation icons. + The visual specifications for these icons are shown below.</p> + + +<h3>Banners</h3> + +<p>App Banners represent your app on the home screen of TV devices and serve and as a way for + users to launch your app. Here are specific requirements for a banner image: +</p> + +<ul> + <li>Size: 320 x 180 px, xhdpi resource</li> + <li>Text should be included in the image. If your app is available in more than one + language, you must provide versions of the banner image for each supported language.</li> +</ul> + + +<h3>Recommendation Icons</h3> + +<p>Recommendation cards include a small icon that is imposed over a colored background. + An example and specifications for the this icon are shown below:</p> + +<img src="{@docRoot}preview/tv/design/images/icon.png" alt="Recommendation icon examples" /> + +<p>Here are the requirements for recommendation icons:</p> + +<ul> + <li>Monocolor: size 16x16dp, white (#fff) icon with transparent background, PNG format</li> + <li>Graphics should be centered within the icon image</li> +</ul> + +<p class="note"> + <strong>Note:</strong> Your app icon image may be desaturated and blended for some card + displays. +</p> + + +<h2>Background Images</h2> + +<p>Background images are displayed in the background of your app to provide additional visual + interest, information, or branding. The BrowseFragment and DetailsFragment classes in the Leanback + support library provide specific support for background images and for updating them as items gain + and lose focus. Here are the specific requirements for background images:</p> + +<ul> + <li>Full color, 1920 x 1080 pixels</li> +</ul> + +<p class="note"> + <strong>Note:</strong> If the image does not meet this requirement, it is scaled to fit. +</p> + +<h2>Audio Feedback</h2> + +<p>Sounds on Android TV bring a cinematic quality to the interaction experience. You should + consider adding sounds for user actions or to provide feedback when a user is only partially + visually engaged with the screen (e.g., because they are distracted or multitasking). + You should also consider using sounds as alternatives to visual messages, for example to indicate + that a user has reached the end of a list or is trying to navigate to an undefined location.</p> diff --git a/docs/html/preview/tv/design/principles.jd b/docs/html/preview/tv/design/principles.jd new file mode 100644 index 0000000..106fa96 --- /dev/null +++ b/docs/html/preview/tv/design/principles.jd @@ -0,0 +1,33 @@ +page.title=Creative Vision for TV +@jd:body + +<p>Users bring a specific set of expectations when watching TV, versus + interacting with a phone or tablet. These guidelines have been developed by the Android User + Experience Team to guide creation of the Android TV platform and the apps that run on it.</p> + +<h2>Casual Consumption</h2> + +<p>The TV is an entertainment interface, not a computer or mobile device. Optimize for + activities that put content at the center: from the casual posture of movie-watching, to + immersive gameplay, to hanging out with friends in a living room.</p> + +<p>Users expect immediate access to content when they turn on a TV. Get users into the action + fast, be it the big game, their favorite show, or a game with friends. The next piece of content + to watch or play should only be a click or two away.</p> + + +<h2>Cinematic Experience</h2> + +<p>Create immersive experiences for the user. Design for as little user interface and as much + content as possible on each screen. Use visual imagery, movement, and sound to inform and delight + users. Avoid using on-screen text to convey information and purpose. Tell your story with pictures + and sound.</p> + + +<h2>Simplicity</h2> + +<p>Android TV is simple and magical. It’s all about finding and enjoying content and + apps with the least amount of friction. Minimize the number of navigation steps required to + perform actions. Build apps with the fewest screens possible between app entry and content + immersion. Avoid making users enter text whenever possible, and use voice interfaces when you + require text input.</p> diff --git a/docs/html/preview/tv/design/style.jd b/docs/html/preview/tv/design/style.jd new file mode 100644 index 0000000..67a7096 --- /dev/null +++ b/docs/html/preview/tv/design/style.jd @@ -0,0 +1,101 @@ +page.title=Style for TV +page.tags="design" +@jd:body + + +<p>Follow these style guidelines to create beautiful, functional apps for TV.</p> + + +<h2>Layouts</h2> + +<p>The difference between a TV experience that feels right and one that does not greatly depends + on the number, spacing, and size of on-screen elements. Although TV sizes and resolutions have + steadily increased over time, users expect TV experiences to be relatively simple and + uncluttered.</p> + +<p>The additional resolution and screen area afforded by modern displays is best used to display + things at better quality, rather than greater quantity. For example, use your layouts to show + large, beautiful pieces of content, or to resize type for both easy reading and generous spacing. +</p> + +<p>If you are creating an app for browsing and playing content, use the prebuilt fragments in the + Leanback support library. These layouts have been built specifically for use on TV devices with + the guidance of the Android User Experience team. For more information on using these classes, + see the <a href="{@docRoot}preview/tv/build-ui/index.html">User Interfaces</a> guide. +</p> + +<p>Here are some additional recommendations for creating functional and attractive layouts for TV + apps:</p> + +<ul> + <li>Design layouts for landscape orientation. TV screens always use this + orientation.</li> + <li>Design your artwork assets for best viewing at HD resolution (1920 x 1080 pixels).</li> + <li>Put on-screen navigational controls on the left or right side of the screen, and + save the vertical space for content.</li> + <li>Use Fragments to create UIs that are divided into sections, and use view groups + like GridView instead of ListView to make better use of the horizontal screen space.</li> + <li>Avoid a cluttered interface by adding sufficient margins between layout controls.</li> +</ul> + + +<h3>Overscan</h3> + +<p>During the evolution of TV technology, overscan originally described an area of TV content + outside of a safe zone that most TVs could reliably display. Even on some of today’s HDTV flat + screens, areas outside that zone may not be visible.</p> + +<img src="{@docRoot}preview/tv/design/images/overscan.png" alt="Overscan borders for TV" /> + +<p>Build a 10% margin into your TV screen designs to account for overscan area the TV may not + display correctly. On a 1920 x 1080 pixel screen, this margin should be a minimum of 27px from the + top and bottom edges and a minimum of 48px from the right and left edges of the picture.</p> + + +<h2>Color</h2> + +<p>Color rendering on televisions can be imprecise compared to computer monitors or mobile + devices. LCD and Plasma TVs often apply smoothing and sharpening filters, and color rendering may + not match what you see on a computer screen.</p> + +<p>Subtle hue or brightness differences between elements may disappear or be over-emphasized on + TV screens. Some color gradient combinations will show bands. You should avoid pure whites on + large areas of the screen. For highly saturated colors (especially reds, greens and blues) you + should review them when used to fill significant areas of the screen. You + should also avoid using very dark or muddy colors, as TV settings may display these colors with + exaggerated contrast, causing them to be indistinguishable.</p> + + +<h2>Typography</h2> + +<p>The text and controls in a TV application's UI should be easily visible and navigable from a + distance. The minimum recommended font size for TV is 12sp. The default text size setting should + be 18sp. We recommend the following guidelines for TV apps:</p> + +<ul> + <li><strong>Card Titles:</strong> Roboto Condensed 16sp</li> + <li><strong>Card Subtext:</strong> Roboto Condensed 12sp</li> + <li><strong>Browse Screen Title:</strong> Roboto Regular 44sp</li> + <li><strong>Browse Category Title:</strong> Roboto Condensed 20sp</li> + <li><strong>Details Content Titles:</strong> Roboto Regular 34sp</li> + <li><strong>Details Subtext:</strong> Roboto Regular 14sp</li> +</ul> + +<p>Some TVs have strong sharpness and contrast settings as their defaults. These picture + settings make thin and light typefaces look jagged and make the text difficult for people to read. + Therefore you should avoid thin or light typefaces on TV.</p> + +<h2>Text</h2> + +<p>Use text in TV apps sparingly. The position of users relative to a TV screen + (typically about 10 feet away) makes it harder for users to read text. Users also don't expect to + read much in a TV environment. Follow these tips for the best handling of text in your app:</p> + +<ul> + <li>Break text into small chunks that users can quickly scan.</li> + <li>Use light text on a dark background. This style is easier to read on a TV.</li> + <li>Avoid lightweight fonts or fonts that have both very narrow and very broad + strokes. Use simple sans-serif fonts and anti-aliasing to increase readability.</li> + <li>Use layout-relative sizing rather than absolute sizing, and density-independent + pixel units instead of absolute pixel units.</li> +</ul> diff --git a/docs/html/preview/tv/games/index.jd b/docs/html/preview/tv/games/index.jd new file mode 100644 index 0000000..b9de3a4 --- /dev/null +++ b/docs/html/preview/tv/games/index.jd @@ -0,0 +1,70 @@ +page.title=Games on TV +page.tags="controller" + +@jd:body + +<p>This section complements the [larger best-practices guidance for designing for Android TV](TODO, use formal name of referenced doc, and add link). It assumes that you have read that guidance, and seeks to minimize repetition.</p> + +<h2>Overview</h2> +<p>Because of factors including its large size, its control scheme, and its nature as a shared display, the television screen presents a number of considerations that may be new to mobile developers. This document breaks these considerations down into five sections:</p> +<ul> +<li>Display</li> +<li>Control</li> +<li>Manifest</li> +<li>Google Play Game Services</li> +<li>Web</li> +</ul> +<h2>Display</h2> +<p>Large and centrally situated, the television screen imposes limitations, but also opens up new opportunities for immersive gameplay.</p> +<h3>A shared display</h3> +<p>A living-room TV poses design challenges for multiplayer games, in that all players can see everything. This issue is especially germane to games (such as card games or strategy games) that rely on each player’s possession of hidden information.</p> +<p>Some mechanisms you can implement to address the problem of one player’s “eavesdropping” on another’s information are:</p> +<ul> +<li>A player might place a "blinder" on the screen to help conceal information. For example, in a turn-based game like a word or card game, one player at a time might view the display. When the player finishes a move, the game allows him or her to cover the screen with a “blinder” that blocks anyone from viewing secret information. When the next player begins a turn, the blinder opens to reveal his or her own information.</li> +<li>A second screen, such as a handset or larger device, can enable a player to conceal information. For information on implementing second-screen support, see <a href="http://developer.android.com/reference/android/app/Presentation.html">Presentation</a> on the Android developer site.</li> +</ul> +<h3>No touch interface</h3> +<p>A television does not have a touch interface. Your game design, therefore, need not take into account the possibility that a player’s controlling fingers might block the on-screen action. You can assume constant visibility of the entire viewing area.</p> +<p>See the <a href=#control>Control</a> section in this document and in [Design for TV](TODO, use formal name of referenced doc, and add link) for more implications of the lack of touch interface.</p> +<h3>Landscape display</h3> +<p>In mobile-device terms, a TV is always “sideways.” You can’t turn it, and there is no portrait orientation. You should always be designing your TV games to be displayed in landscape mode.</p> +<a id=control><h2>Control</h2> +<p>Without a touch interface, it's even more important than usual to get your controls right, so that players find them intuitive and fun to use. The separation of controller from device also introduces some other issues to pay attention to, like keeping track of multiple players' controllers, and handling disconnects gracefully.</p> +<h3>D-pad</h3> +<p>Because of the lack of touch interface, you should be planning your control scheme based on a D-pad. Some key points to keep in mind include:</p> +<p>The player needs to use the gamepad in all aspects of the game–not just controlling core gameplay, but also navigating menus and ads. For this reason, you should also ensure that your Android TV game does not refer to a touch interface: for example, an Android TV game cannot tell a player to "Tap to skip".</p> +<p>You can avoid unhappy surprises (and resulting low ratings) by using your Play Store description to communicate to the player any expectations about controllers. If a game is better suited to a gamepad with a joystick than one with only a D-pad, you should make this clear. A player who uses an ill-suited controller for a game is likely to have a subpar experience–and penalize your game in the ratings.</p> +<p>You can also help ensure a good player experience by ensuring that button mapping is intuitive and flexible. For example, you can adhere to accepted custom by using the A button to <code>Accept</code>, and the B button to <code>Cancel</code>. You can also offer flexibility in the form of remappability. For more information on button mapping, see <a href="http://developer.android.com/training/game-controllers/controller-input.html">Handling Controller Actions</a>.</p> +<p>Your game can also contribute to a good match between controller and game by querying the controller about its capabilities. For example, you may intend for a player to steer an object by waving the controller in the air. If a player's controller lacks accelerometer and gyroscope hardware, however, waving will not work. But when your game queries the controller and discovers that motion detection is not supported, it can switch over to an alternative, available control scheme.</p> +<p>For more information on querying controller capabilities, see <a href="http://developer.android.com/training/game-controllers/compatibility.html">Supporting Controllers Across Android Versions</a>.</p> +<h3>Back-button behavior</h3> +<p>The Back button should never act as a toggle. For example, do not use it to both open and close a menu. Its behavior should only be linear. For example: Game play > Game pause screen > Game main screen > Android home screen.</p> +<p>With this principle of "linear navigation" in mind, you <b>may</b> use the back button to leave an in-game menu (opened by a different button) and return to gameplay.</p> +<h3>Handling multiple controllers</h3> +<p>When multiple players are playing a game, each with his or her own controller, it is important to map each player-controller pair. For information on how to implement controller-number identification, see <a href="http://developer.android.com/reference/android/view/InputDevice.html#getControllerNumber(">Input Devices</a>) on the Android developer site.</p> +<h3>Handling disconnects</h3> +<p>When a controller is disconnected in the middle of gameplay, the game should pause, and a dialog should appear prompting the disconnected player to reconnect his or her controller.</p> +<p>The dialog should also offer troubleshooting tips (e.g., "Check your Bluetooth connection").</p> +<h2>Manifest</h2> +<p>Games are displayed in a separate row from regular apps in the launcher. Android TV uses the <code>android:isGame</code> flag to differentiate games from non-game apps. You can assign it a value of either <code>true</code> or <code>false</code>. For example:</p> +<pre class="fragment"><application> + . . . + <meta-data android:name="isGame" android:value=["true" | "false"]/> +android:isGame=["true" | "false"] > + . . . +</application> +</pre><h2>Google Play Game Services</h2> +<p>If your game integrates Google Play Game Services, you should keep in mind a number of considerations pertaining to achievements, sign-on, saving games, and multiplayer play.</p> +<h3>Achievements</h3> +<p>Your game should include at least five (earnable) achievements. Only a user controlling gameplay from a supported input device should be able to earn achievements.</p> +<h3>Sign-on</h3> +<p>Your game should attempt to sign the user in on launch. If the player declines sign-in several times in a row, your game should stop asking.</p> +<h3>Saving</h3> +<p>We highly recommend using Play Services cloud save to store your game save. Your game should bind game saves to a specific Google account, so as to be uniquely identifiable even across devices: Whether the player is using a handset or a TV, the game should be able to pull the same game-save information from his or her account.</p> +<p>You should also provide an option in your game's UI to prompt the player to destroy save data. You might put the option in the game's <code>Settings</code> screen.</p> +<h3>Multiplayer experience</h3> +<p>A game offering a multiplayer experience must allow at least two players to enter a room.</p> +<h2>Web</h2> +<p>Android TV games do not support a full web browser. You should therefore avoid using generic URLs in your game.</p> +<p>Webviews will work for logins to services like Google+ and Facebook. </p> + diff --git a/docs/html/preview/tv/images/android-tv-remote.png b/docs/html/preview/tv/images/android-tv-remote.png Binary files differnew file mode 100644 index 0000000..d15fbc5 --- /dev/null +++ b/docs/html/preview/tv/images/android-tv-remote.png diff --git a/docs/html/preview/tv/images/home-recommendations.png b/docs/html/preview/tv/images/home-recommendations.png Binary files differnew file mode 100644 index 0000000..ef97145 --- /dev/null +++ b/docs/html/preview/tv/images/home-recommendations.png diff --git a/docs/html/preview/tv/index.jd b/docs/html/preview/tv/index.jd new file mode 100644 index 0000000..dd35908 --- /dev/null +++ b/docs/html/preview/tv/index.jd @@ -0,0 +1,22 @@ +page.title=Android TV Apps + +@jd:body + +<p>Android offers a rich user experience that's optimized for apps running on large screen + devices, such as high-definition televisions. Apps on TV offer new opportunities to + delight your users from the comfort of their couch.</p> + +<p>This guide helps you build apps for TV devices, including:</p> + +<ul> + <li>How to set up your development environment</li> + <li>How to build user interfaces for TV</li> + <li>Guidelines for building games for TV</li> +</ul> + +<p>Prepare your app for its big screen debut!</p> + +<p> + <strong><a href="{@docRoot}preview/tv/start/index.html">Get Started ></a></strong> +</p> + diff --git a/docs/html/preview/tv/start/hardware-features.jd b/docs/html/preview/tv/start/hardware-features.jd new file mode 100644 index 0000000..ddec496 --- /dev/null +++ b/docs/html/preview/tv/start/hardware-features.jd @@ -0,0 +1,183 @@ +page.title=Hardware Features on TV +page.tags="unsupported" + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#unsupported-features">Unsupported Hardware Features</a></li> + <li><a href="#workaround-features">Handling Unsupported Features</a></li> + <li><a href="#check-features">Checking Available Features</a> + <ol> + <li><a href="#no-touchscreen">Touch screen</a></li> + <li><a href="#no-camera">Camera</a></li> + <li><a href="#no-gps">GPS</a></li> + </ol> + + </li> + </ol> +</div> +</div> + +<p>TVs do not have some of the hardware features found on other Android devices. +Touch screens, cameras, and GPS receivers are some of the most commonly used hardware features +which are typically not available on a TV. When you build an app for TV, you must carefully +consider if your app can handle not having these features and, if necessary, work around them.</p> + +<p>This guide discusses the hardware features not available on TV devices and shows you how to +work around those limitations in your app. For more information on filtering and declaring +features in the manifest, see the +<a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">uses-feature</a> guide.</p> + + +<h2 id="unsupported-features">Unsupported Hardware Features</h2> + +<p>TVs have a different purpose from other devices, and so they do not have hardware +features that other Android-powered devices often have. For this reason, the Android system +does not support the following features for a TV device: + +<table> +<tr> +<th>Hardware</th> +<th>Android feature descriptor</th> +</tr> +<tr> +<td>Camera</td> +<td>android.hardware.camera</td> +</tr> +<tr> +<td>GPS</td> +<td>android.hardware.location.gps</td> +</tr> +<tr> +<td>Microphone</td> +<td>android.hardware.microphone</td> +</tr> +<tr> +<td>Near Field Communications (NFC)</td> +<td>android.hardware.nfc</td> +</tr> +<tr> +<td>Telephony</td> +<td>android.hardware.telephony</td> +</tr> +<tr> +<td>Touchscreen</td> +<td>android.hardware.touchscreen</td> +</tr> +</table> +</p> + + +<h2 id="check-features">Checking Available Features</h2> + +<p>To check if a feature is available at runtime, call {@link + android.content.pm.PackageManager#hasSystemFeature(String)}. This method takes a single string + argument that specifies the feature you want to check. For example, to check for a touch screen, + use {@link android.content.pm.PackageManager#hasSystemFeature(String)} with the argument + {@link android.content.pm.PackageManager#FEATURE_TOUCHSCREEN}.</p> + +<p>The following code example demonstrates how to detect the availability of a hardware features + at runtime:</p> + +<pre> +// Check if the telephony hardware feature is available. +if (getPackageManager().hasSystemFeature("android.hardware.telephony")) { + Log.d("Mobile Test", "Running on phone"); +// Check if android.hardware.touchscreen feature is available. +} else if (getPackageManager().hasSystemFeature("android.hardware.touchscreen")) { + Log.d("Tablet Test", "Running on devices that don't support telephony but "+ + "do have a touch screen."); +} else { + Log.d("TV Test", "Running on a TV!"); +} +</pre> + +<p class="note"> + <strong>Note:</strong> You can also use the {@link android.app.UiModeManager#getCurrentModeType + UiModeManager.getCurrentModeType()} method to detect the current platform type. For TV devices, + this method returns a value of {@link android.content.res.Configuration#UI_MODE_TYPE_TELEVISION + Configuration.UI_MODE_TYPE_TELEVISION}. +</p> + + +<h2 id="workaround-features">Handling Unsupported Features</h2> + +<p>Depending on the design and functionality of your app, you may be able to work around certain + hardware features being unavailable. This section discusses how to work around specific hardware + features.</p> + + +<h3 id="no-touchscreen">Touch screen</h3> + +<p>Android doesn't support touch screen interaction for TV devices, since most TVs don't have touch + screens, and using a touch screen is not consistent with a viewing environment where the user is + seated 10 feet away from the display.</p> + +<p>On TV devices, you should work around this limitation by supporting navigation using a directional + pad (D-pad) on TV remote control. For more information on properly supporting navigation using + TV-friendly controls, see <a href="{@docRoot}preview/tv/ui/navigation.html">Navigation for + TV</a>.</p> + +<p>You can explicitly declare if your application requires (or does not require) a touch screen + by including the following entry in your manifest:</p> + +<pre> +<uses-feature android:name="android.hardware.touchscreen" + android:required="false"/> +</pre> + + +<h3 id="no-camera">Camera</h3> + +<p>Although a TV typically does not have a camera, you can still provide a photography-related + application on a TV. For example, if you have an app that takes, views and edits photos, you can + disable its picture-taking functionality for TVs and still allow users to view and even edit + photos. If you decide that you want to enable your camera-related application to work on a + TV device without a camera, you can add an attribute to your app manifest declaring that + a camera is not required by your app:</p> + +<pre> +<uses-feature android:name="android.hardware.camera" android:required="false" /> +</pre> + +<p>If you enable your application to run without a camera, you should add code to your application +that detects if the camera feature is available and makes adjustments to the operation of your app. +The following code example demonstrates how to detect the presence of a camera:</p> + +<pre> +// Check if the camera hardware feature is available. +if (getPackageManager().hasSystemFeature("android.hardware.camera")) { + Log.d("Camera test", "Camera available!"); +} else { + Log.d("Camera test", "No camera available. View and edit features only."); +} +</pre> + + +<h3 id="no-gps">GPS</h3> + +<p>TVs are stationary, indoor devices, and do not have built-in global positioning system (GPS) + receivers. If your application uses location information, you can still allow users to search + for a location, or use a static location provider such as a zip code configured during the + TV device setup.</p> + +<pre> +LocationManager locationManager = (LocationManager) this.getSystemService( + Context.LOCATION_SERVICE); +Location location = locationManager.getLastKnownLocation("static"); +Geocoder geocoder = new Geocoder(this); +Address address = null; + +try { + address = geocoder.getFromLocation(location.getLatitude(), + location.getLongitude(), 1).get(0); + Log.d("Zip code", address.getPostalCode()); + +} catch (IOException e) { + Log.e(TAG, "Geocoder error", e); +} +</pre> + diff --git a/docs/html/preview/tv/start/index.jd b/docs/html/preview/tv/start/index.jd new file mode 100644 index 0000000..11d6ad3 --- /dev/null +++ b/docs/html/preview/tv/start/index.jd @@ -0,0 +1,233 @@ +page.title=Get Started with TV Apps +page.tags="leanback","recyclerview","launcher" + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#prerequisites">Prerequisites</a></li> + <li><a href="#dev-project">Setup a TV Project</a> + <ul> + <li><a href="#tv-activity">Create a TV Activity</a></li> + <li><a href="#tv-libraries">Add TV Support Libraries</a></li> + </ul> + </li> + <li><a href="#build-it">Build TV Apps</a></li> + <li><a href="#run">Run TV Apps</a></li> + + </ol> +</div> +</div> + +<p>This guide describes how to prepare your development environment and projects for building + TV apps, including updating your existing app to run on TV devices.</p> + + +<h2 id="prerequisites">Prerequisites</h2> + +<p>Before you begin setting up to build apps for TV, you must:</p> + +<ul> + <li><strong><a href="{@docRoot}preview/setup-sdk.html"> + Set up the Preview SDK</a></strong> + <br> + The preview SDK provides the developer tools needed to build and test apps for TV. + </li> + <li><strong><a href="{@docRoot}preview/setup-sdk.html#project"> + Create a Preview SDK Project</a></strong> + <br> + In order to access new APIs for TV devices, you must create a project that targets the preview + release level or modify an existing project to target the preview release. + </li> +</ul> + + +<h2 id="dev-project">Set up a TV Project</h2> + +<p>TV apps use the same structure as those for phones and tablets. This means you can modify + your existing apps to also run on TV devices or create new apps based on what you already know + about building apps for Android. This section discusses how to modify an existing app, or create a + new one, to run on TV devices.</p> + +<p>These are the main steps to creating an app that runs on TV devices. Only the first + is required:</p> + +<ul> + <li><strong>Activity for TV</strong> - (Required) In your application manifest, you must + declare an activity that is intended to run on TV devices.</li> + <li><strong>TV Support Libraries</strong> - (Optional) There are several Support Libraries + available for TV devices that provide widgets for building user interfaces.</li> +</ul> + + +<h3 id="tv-activity">Create a TV Activity</h3> + +<p>An application intended to run on TV devices must declare a launcher activity for TV + in its manifest using a {@code android.intent.category.LEANBACK_LAUNCHER} intent filter. + This filter identifies your app as being built for TV, enabling it to be displayed in the + Google Play store app running on TV devices. Declaring this intent also identifies which activity + in your app should be launched when a user selects its icon on the TV home screen.</p> + +<p class="caution"> + <strong>Caution:</strong> If you do not include the {@code LEANBACK_LAUNCHER} intent filter in + your app, it is not visible to users running the Google Play store on TV devices. Also, if your + app does not have this filter when you load it onto a TV device using developer tools, the app + does not appear in the TV user interface. +</p> + +<p>The following code snippet shows how to include this intent filter in your manifest:</p> + +<pre> +<application> + ... + <activity + android:name="com.example.android.MainActivity" + android:label="@string/app_name" > + + <intent-filter> + <action android:name="android.intent.action.MAIN" /> + <category android:name="android.intent.category.LAUNCHER" /> + </intent-filter> + </activity> + + <activity + android:name="com.example.android.<strong>TvActivity</strong>" + android:label="@string/app_name" + android:theme="@android:style/Theme.Leanback"> + + <intent-filter> + <action android:name="android.intent.action.MAIN" /> + <category android:name="<strong>android.intent.category.LEANBACK_LAUNCHER</strong>" /> + </intent-filter> + + </activity> +</application> +</pre> + +<p>The second activity manifest entry in the example above specifies that activity as + the main one when your app launches on an TV device.</p> + +<p>If you have an existing app that you are modifying for TV use, your app should not use the same + activity layout for TV that it does for phones and tablets. The user interface of your TV app (or + TV portion of your existing app) should provide a simpler interface that can be easily navigated + using a remote control from a couch. For guidelines on designing an app for TV, see the + <a href="{@docRoot}design/tv/index.html">TV Design</a> guide. For more instructions on + developing a user interface appropriate to TV, see the + <a href="{@docRoot}preview/tv/ui/index.html">TV User Interface</a> guide. +</p> + + +<h3 id="tv-libraries">Add TV Support Libraries</h3> + +<p>The Preview SDK includes support libraries that are intended for use with TV apps. These + libraries provide APIs and user interface widgets for use on TV devices. The libraries are + located in the {@code <sdk>/extras/android/support/} directory where you installed the + Preview SDK. Here is a list of the libraries and their general purpose:</p> + +<ul> + <li><strong>v17 leanback library</strong> - Provides user interface widgets for TV, including + {@code BrowseFragment}, {@code DetailsFragment}, and {@code SearchFragment}. + <ul> + <li>SDK location: {@code <sdk>/extras/android/support/v17/leanback}</li> + <li>Gradle dependency: {@code com.android.support:leanback-v17:20.0.+}</li> + <li>Contains resources: Yes</li> + </ul> + </li> + <li><strong>v7 recyclerview library</strong> - Provides classes for managing display of long + lists in a memory efficient manner. Several classes in the v17 leanback library depend on the + classes in this library. + <ul> + <li>SDK location: {@code <sdk>/extras/android/support/v7/recyclerview}</li> + <li>Gradle dependency: {@code com.android.support:recyclerview-v7:20.0.+}</li> + <li>Contains resources: No</li> + </ul> + </li> +</ul> + +<p class="note"> + <strong>Note:</strong> You are not required to use these support libraries for your TV app. + However, we strongly recommend using them, particularly for apps that provide a media catalog + browsing interface. +</p> + +<p>If you decide to use the v17 leanback library for your app, you should note that it is + dependent on the <a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7 + appcompat library</a>, which is, in turn, dependent on the + <a href="{@docRoot}tools/support-library/features.html#v4">v4 support library</a>. This means + that apps that use the leanback support library should include all of these support + libraries:</p> + +<ul> + <li>v17 leanback support library</li> + <li>v7 recyclerview support library</li> + <li>v7 appcompat support library</li> + <li>v4 support library</li> +</ul> + +<p>Two of these libraries (v17 leanback and v7 appcompat) contain resources, which require + you to take specific steps to include them in app projects. For instructions on + importing a support library with resources, see + <a href="http://developer.android.com/tools/support-library/setup.html#libs-with-res"> + Support Library Setup</a>. +</p> + + +<h2 id="build-it">Build TV Apps</h2> + +<p>After you have completed the steps described above, it's time to start building apps for + the big screen! Check out these additional topics to help you build your app for TV: + +<ul> + <li><a href="{@docRoot}preview/tv/ui/index.html">User Interface</a> - The user interface of + TV devices is different from those of other Android devices. See this topic to find out how + to build TV user interfaces and to learn about the widgets provided to simplify that task. + </li> + <li><a href="{@docRoot}preview/tv/games/index.html">Games for TV</a> - TV devices are great + platforms for games. See this topic for information on building great game experiences for + TV.</li> + <li><a href="{@docRoot}preview/tv/start/hardware-features.html">Hardware features</a> - TV + devices do not contain hardware features normally found on other Android devices. See this + topic for information on unsupported hardware features and what to do about them. + </li> +</ul> + + +<h2 id="run">Run TV Apps</h2> + +<p>Running your app is an important part of the development process. The AVD Manager in the + Android SDK provides the device definitions that allows you to create virtual TV devices for + running and testing your applications.</p> + +<p>To create an virtual TV device:</p> + +<ol> + <li>Start the AVD Manager. For more information, see the + <a href="{@docRoot}tools/help/avd-manager.html">AVD Manager</a> help.</li> + <li>In the AVD Manager dialog, click the <strong>Device Definitions</strong> tab.</li> + <li>Select one of the Android TV device definitions, such as + <strong>Large Android TV</strong>, and click <strong>Create AVD</strong>.</li> + <li>Select the emulator options and click <strong>OK</strong> to create the AVD. + <p class="note"> + <strong>Note:</strong> For best performance of the TV emulator device, enable the <strong>Use + Host GPU</strong> option and CPU platform image that supports hardware acceleration. For + more information on hardware acceleration of the emulator, see + <a href="{@docRoot}tools/devices/emulator.html#acceleration">Using the Emulator</a>. + </p> + </li> +</ol> + +<p>To test your application on the virtual TV device:</p> + +<ol> + <li>Compile your TV application in your development environment.</li> + <li>Run the application from your development environment and choose the TV virtual device as + the target.</li> +</ol> + +<p>For more information about using emulators see, <a href="{@docRoot}tools/devices/emulator.html"> +Using the Emulator</a>. For more information about deploying apps to emulators from +Eclipse with ADT, see <a href="{@docRoot}http://developer.android.com/tools/building/building-eclipse.html"> +Building and Running from Eclipse with ADT</a>.</p> + diff --git a/docs/html/preview/tv/ui/browse.jd b/docs/html/preview/tv/ui/browse.jd new file mode 100644 index 0000000..d7a1fb6 --- /dev/null +++ b/docs/html/preview/tv/ui/browse.jd @@ -0,0 +1,199 @@ +page.title=BrowseFragment + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#layout">Media Browse Layout</a></li> + <li><a href="#lists">Displaying Media Lists</a></li> + <li><a href="#background">Updating the Background</a></li> + </ol> + +</div> +</div> + +<p>The <a href="{@docRoot}preview/tv/start/index.html#tv-libraries">Leanback support library</a> + provides several APIs for displaying and browsing media catalogs + on the TV devices. This guide discusses how to use the classes provided by this library to + implement a user interface for browsing music or videos from your app's media catalog.</p> + + +<h2 id="layout">Media Browse Layout</h2> + +<p>The {@code BrowseFragment} class in the Leanback support library allows you to create a primary + layout for browsing categories and rows of media items with a minimum of code. The following + example shows how to create a layout that contains a {@code BrowseFragment}:</p> + +<pre> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="match_parent" + android:layout_height="match_parent" + android:orientation="vertical" + > + + <fragment + <strong>android:name="android.support.v17.leanback.app.BrowseFragment"</strong> + android:id="@+id/browse_fragment" + android:layout_width="match_parent" + android:layout_height="match_parent" + /> +</LinearLayout> +</pre> + +<p>In order to work with this layout in an activity, retrieve the {@code BrowseFragment} element + from the layout. Use the methods in {@code BrowseFragment} to set display parameters such as the + icon, title and whether category headers are enabled. The following code sample demonstrates how + to set the layout parameters for a {@code BrowseFragment} in a layout:</p> + +<pre> +public class BrowseMediaActivity extends Activity { + + public static final String TAG ="BrowseActivity"; + + protected BrowseFragment mBrowseFragment; + + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.browse_fragment); + + final FragmentManager fragmentManager = getFragmentManager(); + <strong>mBrowseFragment = (BrowseFragment) fragmentManager.findFragmentById( + R.id.browse_fragment);</strong> + + // Set display parameters for the BrowseFragment + mBrowseFragment.setHeadersState(BrowseFragment.HEADERS_ENABLED); + mBrowseFragment.setTitle(getString(R.string.app_name)); + mBrowseFragment.setBadgeDrawable(getResources().getDrawable(R.drawable.ic_launcher)); + mBrowseFragment.setBrowseParams(params); + + } +} +</pre> + + +<h2 id="lists">Displaying Media Lists</h2> + +<p>The {@code BrowseFragment} allows you to define and display browsable media content categories and + media items from a media catalog using adapters and presenters. Adapters enable you to connect to + local or online data sources that contain your media catalog information. Presenter classes hold + data about media items and provide layout information for displaying an item on screen.</p> + +<p>The following example code shows an implementation of a presenter for displaying string + data:</p> + +<pre> +public class StringPresenter extends Presenter { + private static final String TAG = "StringPresenter"; + + public ViewHolder onCreateViewHolder(ViewGroup parent) { + TextView textView = new TextView(parent.getContext()); + textView.setFocusable(true); + textView.setFocusableInTouchMode(true); + textView.setBackground( + parent.getContext().getResources().getDrawable(R.drawable.text_bg)); + return new ViewHolder(textView); + } + + public void onBindViewHolder(ViewHolder viewHolder, Object item) { + ((TextView) viewHolder.view).setText(item.toString()); + } + + public void onUnbindViewHolder(ViewHolder viewHolder) { + // no op + } +} +</pre> + +<p>Once you have constructed a presenter class for your media items, you can build and attach an + adapter to the {@code BrowseFragment} to display those items on screen for browsing by the user. The + following example code demonstrates how to construct an adapter to display categories and items + in those categories using the StringPresenter class shown in the previous code example:</p> + +<pre> +private ArrayObjectAdapter mRowsAdapter; +private static final int NUM_ROWS = 4; + +@Override +protected void onCreate(Bundle savedInstanceState) { + ... + + buildRowsAdapter(); +} + +private void buildRowsAdapter() { + mRowsAdapter = new ArrayObjectAdapter(new ListRowPresenter()); + + for (int i = 0; i < NUM_ROWS; ++i) { + ArrayObjectAdapter listRowAdapter = new ArrayObjectAdapter( + new StringPresenter()); + listRowAdapter.add("Media Item 1"); + listRowAdapter.add("Media Item 2"); + listRowAdapter.add("Media Item 3"); + HeaderItem header = new HeaderItem(i, "Category " + i, null); + mRowsAdapter.add(new ListRow(header, listRowAdapter)); + } + + mBrowseFragment.setAdapter(mRowsAdapter); +} +</pre> + +<p>This example shows a static implementation of the adapters. A typical media browsing + application uses data from an online database or web service. For an example of a browsing + application that uses data retrieved from the web, see the + <a href="http://github.com/googlesamples/androidtv-leanback">Android TV</a> sample app.</p> + + +<h2 id="background">Updating the Background</h2> + +<p>In order to add visual interest to a media-browsing app on TV, you can update the background + image as users browse through content. This technique can make interaction with your app feel more + cinematic and enjoyable for users.</p> + +<p>The Leanback support library provides a {@link + android.support.v17.leanback.app.BackgroundManager} class for changing the background of your TV + app activity. The following example shows how to create a simple method for updating the + background within your TV app activity:</p> + +<pre> +protected void updateBackground(Drawable drawable) { + BackgroundManager.getInstance(this).setDrawable(drawable); +} +</pre> + +<p>Many of the existing media-browse apps automatically update the background as the user + navigates through media listings. In order to do this, you can set up a selection listener to + automatically update the background based on the user's current selection. The following example + shows you how to set up an {@link android.support.v17.leanback.widget.OnItemSelectedListener} + class to catch selection events and update the background:</p> + +<pre> +protected void clearBackground() { + BackgroundManager.getInstance(this).setDrawable(mDefaultBackground); +} + +protected OnItemSelectedListener getDefaultItemSelectedListener() { + return new OnItemSelectedListener() { + @Override + public void onItemSelected(Object item, Row row) { + if (item instanceof Movie ) { + URI uri = ((Movie)item).getBackdropURI(); + updateBackground(uri); + } else { + clearBackground(); + } + } + }; +} +</pre> + +<p class="note"> + <strong>Note:</strong> The implementation above is a simple example shown for purposes of + illustration. When creating this function in your own app, you should consider running the + background update action in a separate thread for better performance. In addition, if you are + planning on updating the background in response to users scrolling through items, consider adding + a time to delay a background image update until the user settles on an item. This technique avoids + excessive background image updates. +</p> diff --git a/docs/html/preview/tv/ui/details.jd b/docs/html/preview/tv/ui/details.jd new file mode 100644 index 0000000..8b8fa8b5 --- /dev/null +++ b/docs/html/preview/tv/ui/details.jd @@ -0,0 +1,214 @@ +page.title=DetailFragment + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#details-presenter">Build a Details Presenter</a></li> + <li><a href="#details-fragment">Extend the Details Fragment</a> + <li><a href="#activity">Creating a Details Activity</a></li> + <li><a href="#item-listener">Listener for Clicked Items</a></li> + </li> + </ol> +</div> +</div> + +<p>The media browsing interface classes provided by the + <a href="{@docRoot}preview/tv/start/index.html#tv-libraries">Leanback support library</a> + include classes for displaying additional information about a media item, such as a description + or reviews, and for taking action on that item, such as purchasing it or playing its content. This + section discusses how to create a presenter class for media item details and extend the + {@code DetailsFragment} class to implement a details view for a media item when it + is selected by a user. +</p> + +<p class="note"> + <strong>Note:</strong> The implementation example shown here uses an additional activity to + contain the {@code DetailsFragment}. However, it is possible to avoid creating a second activity + by replacing the current {@code BrowseFragment} with a {@code DetailsFragment} within the <em>same</em> + activity using fragment transactions. For more information on using fragment transactions, see the + <a href="{@docRoot}training/basics/fragments/fragment-ui.html#Replace">Building a Dynamic + UI with Fragments</a> training. +</p> + + +<h2 id="details-presenter">Build a Details Presenter</h2> + +<p>In the media browsing framework provided for by the leanback support library, you use + presenter objects to control the display of data on screen, including media item details. The + framework provides the {@code AbstractDetailsDescriptionPresenter} class for this purpose, which + is a nearly complete implementation of the presenter for media item details. All you have to do is + implement the {@code onBindDescription()} method to bind the view fields to your data objects, as shown in + the following code sample:</p> + +<pre> +public class DetailsDescriptionPresenter + extends AbstractDetailsDescriptionPresenter { + + @Override + protected void onBindDescription(ViewHolder viewHolder, Object itemData) { + MyMediaItemDetails details = (MyMediaItemDetails) itemData; + // In a production app, the itemData object contains the information + // needed to display details for the media item: + // viewHolder.getTitle().setText(details.getShortTitle()); + + // Here we provide static data for testing purposes: + viewHolder.getTitle().setText(itemData.toString()); + viewHolder.getSubtitle().setText("2014 Drama TV-14"); + viewHolder.getBody().setText("Lorem ipsum dolor sit amet, consectetur " + + "adipisicing elit, sed do eiusmod tempor incididunt ut labore " + + " et dolore magna aliqua. Ut enim ad minim veniam, quis " + + "nostrud exercitation ullamco laboris nisi ut aliquip ex ea " + + "commodo consequat."); + } +} +</pre> + + +<h2 id="details-fragment">Extend the Details Fragment</h2> + +<p>When you use the {@code DetailsFragment} class for displaying your media item details, you + extend that class to provide additional content such as a preview image and actions for the media + item. You can also provide additional content, such as a list of related media items.</p> + +<p>The following example code demonstrates how to use the presenter class you created in the + previous section, add a preview image and actions for the media item being viewed. This example + also shows the addition of a related media items row, which appears below the details listing.</p> + +<pre> +public class MediaItemDetailsFragment extends DetailsFragment { + private static final String TAG = "MediaItemDetailsFragment"; + private ArrayObjectAdapter mRowsAdapter; + + @Override + public void onCreate(Bundle savedInstanceState) { + Log.i(TAG, "onCreate"); + super.onCreate(savedInstanceState); + + buildDetails(); + } + + private void buildDetails() { + ClassPresenterSelector selector = new ClassPresenterSelector(); + // Attach your media item details presenter to the row presenter: + DetailsOverviewRowPresenter rowPresenter = + new DetailsOverviewRowPresenter(new DetailsDescriptionPresenter()); + + selector.addClassPresenter(DetailsOverviewRow.class, rowPresenter); + selector.addClassPresenter(ListRow.class, + new ListRowPresenter()); + mRowsAdapter = new ArrayObjectAdapter(selector); + + Resources res = getActivity().getResources(); + DetailsOverviewRow detailsOverview = new DetailsOverviewRow( + "Media Item Details"); + + // Add images and action buttons to the details view + detailsOverview.setImageDrawable(res.getDrawable(R.drawable.jelly_beans)); + detailsOverview.addAction(new Action(1, "Buy $9.99")); + detailsOverview.addAction(new Action(2, "Rent $2.99")); + mRowsAdapter.add(detailsOverview); + + // Add a Related items row + ArrayObjectAdapter listRowAdapter = new ArrayObjectAdapter( + new StringPresenter()); + listRowAdapter.add("Media Item 1"); + listRowAdapter.add("Media Item 2"); + listRowAdapter.add("Media Item 3"); + HeaderItem header = new HeaderItem(0, "Related Items", null); + mRowsAdapter.add(new ListRow(header, listRowAdapter)); + + setAdapter(mRowsAdapter); + } +} +</pre> + + +<h3 id="activity">Creating a Details Activity</h3> + +<p>Fragments such as the {@code DetailsFragment} must be contained within an activity in order + to be used for display. Creating an activity for your details view, separate from the browse + activity, enables you to invoke your details view using an Intent. This section explains how to + build an activity to contain your implementation of the detail view for your media items.</p> + +<p>Start creating the details activity by building a layout that references your implementation + of the {@code DetailsFragment}:</p> + +<pre> +<!-- file: res/layout/details.xml --> + +<fragment xmlns:android="http://schemas.android.com/apk/res/android" + <strong>android:name="com.example.android.mediabrowser.MediaItemDetailsFragment"</strong> + android:id="@+id/details_fragment" + android:layout_width="match_parent" + android:layout_height="match_parent" +/> +</pre> + +<p>Next, create an activity class that uses the layout shown in the previous code example:</p> + +<pre> +public class DetailsActivity extends Activity +{ + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + <strong>setContentView(R.layout.details);</strong> + } +} +</pre> + +<p>Finally, add this new activity to the manifest. Remember to apply the Leanback theme to + ensure that the user interface is consistent with the media browse activity:</p> + +<pre> +<application> + ... + + <activity android:name=".DetailsActivity" + android:exported="true" + <strong>android:theme="@style/Theme.Leanback"/></strong> + +</application> +</pre> + + +<h3 id="item-listener">Listener for Clicked Items</h3> + +<p>After you have implemented the {@code DetailsFragment}, you must modify your main media + browsing view to move to your details view when a user clicks on a media item. In order to enable + this behavior, add an {@code OnItemClickedListener} object to the BrowseFragment that fires an + intent to start the item details activity.</p> + +<p>The following example shows how to implement a listener to start the details view when a user + clicks a media item in the main media browsing activity:</p> + +<pre> +public class BrowseMediaActivity extends Activity { + ... + + @Override + protected void onCreate(Bundle savedInstanceState) { + ... + + // create the media item rows + buildRowsAdapter(); + + // add a listener for selected items + mBrowseFragment.setOnItemClickedListener( + new OnItemClickedListener() { + @Override + public void onItemClicked(Object item, Row row) { + System.out.println("Media Item clicked: " + item.toString()); + Intent intent = new Intent(BrowseMediaActivity.this, + DetailsActivity.class); + // pass the item information + intent.getExtras().putLong("id", item.getId()); + startActivity(intent); + } + }); + } +} +</pre> diff --git a/docs/html/preview/tv/ui/in-app-search.jd b/docs/html/preview/tv/ui/in-app-search.jd new file mode 100644 index 0000000..3dbfcd2 --- /dev/null +++ b/docs/html/preview/tv/ui/in-app-search.jd @@ -0,0 +1,111 @@ +page.title=Adding Search to TV Apps + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#add-search-ui">Add Search User Interface</a></li> + </ol> + +</div> +</div> + + +<p>Users frequently have specific content in mind when using a media app. A search interface can + help your users get to the content they want faster than browsing. The Leanback library provides a + set of classes to enable a standard search interface within your app that is consistent with other + search functions on TV and provides features such as voice input.</p> + +<h2 id="add-search-ui">Add Search User Interface</h2> +<p>When you use the BrowseFragment class for your media browsing interface, you can enable the + search icon by setting an OnClickListener to the BrowseFragment object. The following sample code + demonstrates this technique.</p> + +<pre> +@Override +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.browse_activity); + + mBrowseFragment = (BrowseFragment) + getFragmentManager().findFragmentById(R.id.browse_fragment); + + ... + + mBrowseFragment.setOnSearchClickedListener(new View.OnClickListener() { + @Override + public void onClick(View view) { + Intent intent = new Intent(BrowseActivity.this, SearchActivity.class); + startActivity(intent); + } + }); + + mBrowseFragment.setAdapter(buildAdapter()); +} +</pre> + +<p class="note"> + <strong>Note:</strong> You can set the color of the search icon using the + {@code setSearchAffordanceColor()} method of {@code BrowseFragment}. +</p> + +<p>When a user selects the search icon, the system invokes a search activity via the defined + Intent. Your search activity should use a linear layout containing a SearchFragment. This fragment + must also implement the SearchFragment.SearchResultProvider interface in order to display the + results of a search. The following code sample shows how to extend the SearchFragment class to + provide a search interface and results:</p> + +<pre> +public class MySearchFragment extends SearchFragment + implements SearchFragment.SearchResultProvider { + + private static final int SEARCH_DELAY_MS = 300; + private ArrayObjectAdapter mRowsAdapter; + private Handler mHandler = new Handler(); + private SearchRunnable mDelayedLoad; + + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + + mRowsAdapter = new ArrayObjectAdapter(new ListRowPresenter()); + setSearchResultProvider(this); + setOnItemClickedListener(getDefaultItemClickedListener()); + mDelayedLoad = new SearchRunnable(); + } + + @Override + public ObjectAdapter getResultsAdapter() { + return mRowsAdapter; + } + + @Override + public boolean onQueryTextChange(String newQuery) { + mRowsAdapter.clear(); + if (!TextUtils.isEmpty(newQuery)) { + mDelayedLoad.setSearchQuery(newQuery); + mHandler.removeCallbacks(mDelayedLoad); + mHandler.postDelayed(mDelayedLoad, SEARCH_DELAY_MS); + } + return true; + } + + @Override + public boolean onQueryTextSubmit(String query) { + mRowsAdapter.clear(); + if (!TextUtils.isEmpty(query)) { + mDelayedLoad.setSearchQuery(query); + mHandler.removeCallbacks(mDelayedLoad); + mHandler.postDelayed(mDelayedLoad, SEARCH_DELAY_MS); + } + return true; + } +} +</pre> + +<p>This example code shown above is meant to be used with a separate {@code SearchRunnable} + class that runs the search query on a separate thread. This technique keeps potentially + slow-running queries from blocking the main user interface thread.</p> + diff --git a/docs/html/preview/tv/ui/index.jd b/docs/html/preview/tv/ui/index.jd new file mode 100644 index 0000000..c861ec2 --- /dev/null +++ b/docs/html/preview/tv/ui/index.jd @@ -0,0 +1,40 @@ +page.title=User Interfaces for TV + +@jd:body + + +<p> + Building an effective and engaging user interface for TV devices requires a firm understanding of what works well + in the context of a living room. Imagine a large screen that can be seen by many people at the + same time, controlled with a few buttons by users with limited attention, and you start to see the + challenges and opportunities of building an app for TV. Building apps for this environment + requires a different approach and different tools.</p> + +<p>This section discusses how to build a living room experience with your app, including + implementation instructions and creating user interface widgets built for TV. Also check out + <a href="{@docRoot}design/tv/index.html">Design for TV</a> for information and inspiration + on creating engaging user interfaces for TV devices.</p> + +<h2>Topics</h2> + +<dl> + <dt><b><a href="layouts.html">Layouts</a></b></dt> + <dd>Learn how to build app layouts for TV screens.</dd> + + <dt><b><a href="navigation.html">Navigation</a></b></dt> + <dd>Learn how to build navigation for TV devices.</dd> + + <dt><b><a href="browse.html">BrowseFragment</a></b></dt> + <dd>Learn how to use this fragment to build a browsing interface for media catalogs.</dd> + + <dt><b><a href="details.html">DetailsFragment</a></b></dt> + <dd>Learn how to use this fragment to build a details page for media items.</dd> + + <dt><b><a href="in-app-search.html">In-App Search</a></b></dt> + <dd>Learn how to use a built-for-TV user interface for searching within your app.</dd> + + <dt><b><a href="recommendations.html">Recommendations</a></b></dt> + <dd>Learn how your app can contribute to the list of recommendations appearing on the home + screen and get your content noticed by users.</dd> +</dl> + diff --git a/docs/html/preview/tv/ui/layouts.jd b/docs/html/preview/tv/ui/layouts.jd new file mode 100644 index 0000000..0659826 --- /dev/null +++ b/docs/html/preview/tv/ui/layouts.jd @@ -0,0 +1,298 @@ +page.title=Layouts for TV + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#themes">Themes</a> + <ol> + <li><a href="#leanback-theme">Leanback Theme</a></li> + <li><a href="#notitle-theme">NoTitleBar Theme</a></li> + </ol> + </li> + <li><a href="#structure">Layout Structure</a> + <ol> + <li><a href="#overscan">Overscan</a></li> + </ol> + </li> + <li><a href="#visibility">Text and Controls Visibility</a></li> + <li><a href="#density-resources">Screen Density and Image Resources</a></li> + <li><a href="#anti-patterns">Layout Anti-Patterns</a></li> + <li><a href="#large-bitmaps">Handling Large Bitmaps</a></li> + </ol> + +</div> +</div> + +<p> + A TV screen is typically viewed from about 10 feet away, and while it is much larger than most + other Android device displays, this type of screen does not provide the same level of precise + detail and color as a smaller device. These factors require that you create app layouts with + TV devices in mind in order to create a useful and enjoyable user experience.</p> + +<p>This guide provides direction and implementation details for building effective layouts inN + TV apps.</p> + + +<h2 id="themes">Themes</h2> + +<p>Android <a href="{@docRoot}guide/topics/ui/themes.html">Themes</a> can provide a basis for + layouts in your TV apps. You should use a theme to modify the display of your app activities + that are meant to run on a TV device. This section explains which themes you should use.</p> + + +<h3 id="leanback-theme">Leanback Theme</h3> + +<p>The Leanback library provides a standard theme for TV activities, called {@code + Leanback.Theme}, which establishes a consistent visual style for TV apps. Use of this theme is + recommended for most apps. This theme is recommended for any TV app that uses the Leanback + library classes. The following code sample shows how to apply this theme to a given + activity within an app:</p> + +<pre> +<activity + android:name="com.example.android.TvActivity" + android:label="@string/app_name" + <strong>android:theme="@style/Theme.Leanback"</strong>> +</pre> + + +<h3 id="notitle-theme">NoTitleBar Theme</h3> + +<p>The title bar is a standard user interface element for Android apps on phones and tablets, + but it is not appropriate for TV apps. If you are not using the Leanback library classes, + you should apply this theme to your TV activities. The following code example from a TV app + manifest demonstrates how to apply this theme to remove the display of a title bar: +</p> + +<pre> +<application> + ... + + <activity + android:name="com.example.android.TvActivity" + android:label="@string/app_name" + <strong>android:theme="@android:style/Theme.NoTitleBar"</strong>> + ... + + </activity> +</application> +</pre> + + +<h2 id="structure">Layout Structure</h2> + +<p>Layouts for TV devices should follow some basic guidelines to ensure they are usable and + effective on large screens. Follow these tips to build landscape layouts optimized for TV screens: +</p> + +<ul> + <li>Build layouts with a landscape orientation. TV screens always display in landscape.</li> + <li>Put on-screen navigation controls on the left or right side of the screen and save the + vertical space for content.</li> + <li>Create UIs that are divided into sections, using <a + href="{@docRoot}guide/components/fragments.html" + >Fragments</a>, and use view groups like {@link android.widget.GridView} instead of {@link + android.widget.ListView} to make better use of the horizontal screen space. + </li> + <li>Use view groups such as {@link android.widget.RelativeLayout} or {@link + android.widget.LinearLayout} to arrange views. This approach allows the system to adjust the + position of the views to the size, alignment, aspect ratio, and pixel density of a TV screen.</li> + <li>Add sufficient margins between layout controls to avoid a cluttered UI.</li> +</ul> + + +<h3 id="overscan">Overscan</h3> + +<p>Layouts for TV have some unique requirements due to the evolution of TV standards and the + desire to always present a full screen picture to viewers. For this reason, TV devices may + clip the outside edge of an app layout in order to ensure that the entire display is filled. + This behavior is generally referred to as Overscan.</p> + +<p>In order to account for the impact of overscan and make sure that all the user interface + elements you place in a layout are actually shown on screen, you should incorporate a 10% margin + on all sides of your layout. This translates into a 27dp margin on the left and right edges and + a 48dp margin on the top and bottom of your base layouts for activities. The following + example layout demonstrates how to set these margins in the root layout for a TV app: +</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:id="@+id/base_layout" + android:layout_width="match_parent" + android:layout_height="match_parent" + android:orientation="vertical" + android:layout_marginTop="27dp" + android:layout_marginLeft="48dp" + android:layout_marginRight="48dp" + android:layout_marginBottom="27dp" > +</LinearLayout> +</pre> + +<p class="caution"> + <strong>Caution:</strong> Do not apply overscan margins to your layout if you are using the + Leanback Support Library {@code BrowseFragment} or related widgets, as those layouts already + incorporate overscan-safe margins. +</p> + + +<h2 id="visibility">Text and Controls Visibility</h2> + +<p> +The text and controls in a TV app layout should be easily visible and navigable from a distance. +Follow these tips to make them easier to see from a distance : +</p> + +<ul> + <li>Break text into small chunks that users can quickly scan.</li> + <li>Use light text on a dark background. This style is easier to read on a TV.</li> + <li>Avoid lightweight fonts or fonts that have both very narrow and very broad strokes. + Use simple sans-serif fonts and anti-aliasing to increase readability.</li> + <li>Use Android's standard font sizes: +<pre> +<TextView + android:id="@+id/atext" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:gravity="center_vertical" + android:singleLine="true" + android:textAppearance="?android:attr/textAppearanceMedium"/> +</pre> + </li> + <li>Ensure that all your view widgets are large enough to be clearly visible to someone + sitting 10 feet away from the screen (this distance is greater for very large screens). The + best way to do this is to use layout-relative sizing rather than absolute sizing, and + density-independent pixel units instead of absolute pixel units. For example, to set the + width of a widget, use wrap_content instead of a pixel measurement, and to set the margin + for a widget, use dip instead of px values.</li> +</ul> + + +<h2 id="density-resources">Screen Density and Image Resources</h2> + +<p>The common high-definition TV display resolutions are 720p, 1080i, and 1080p. + Your TV layout should target a screen size of 1920 x 1080 pixels, and then allow the Android + system to downscale your layout elements to 720p if necessary. In general, downscaling + (removing pixels) does not degrade your layout presentation quality. However, upscaling can + cause display artifacts that degrade the quality of your layout and have a negative impact on + the user experience of your app.</p> + +<p> + To get the best scaling results for images, provide them as + <a href="{@docRoot}tools/help/draw9patch.html">9-patch image</a> elements if possible. If you + provide low quality or small images in your layouts, they will appear pixelated, fuzzy, or + grainy. This is not a good experience for the user. Instead, use high-quality images. +</p> + +<p> + For more information on optimizing layouts and resources for large screens see + <a href="{@docRoot}training/multiscreen/index.html">Designing for multiple screens</a>. +</p> + + +<h2 id="anti-patterns">Layout Anti-Patterns</h2> + +<p>There are a few approaches to building layouts for TV that you should avoid because they do not +work well and lead to bad user experiences. Here are some user interface approaches you +should specifically <em>not</em> use when developing a layout for TV. +</p> + +<ul> + <li><strong>Re-using phone or tablet layouts</strong> - Do not reuse layouts from a phone or + tablet app without modification. Layouts built for other Android device form factors are not + well suited for TV devices and should be simplified for operation on a TV.</li> + <li><strong>ActionBar</strong> - While this user interface convention is recommended for use + on phones and tablets, it is not appropriate for a TV interface. In particular, using an + action bar options menu (or any pull-down menu for that matter) is strongly discouraged, due + to the difficulty in navigating such a menu with a remote control.</li> + <li><strong>ViewPager</strong> - Sliding between screens can work great on a phone or tablet, + but don't try this on a TV!</li> + +</ul> + +<p>For more information on designing layouts that are appropriate to TV, see the + <a href="{@docRoot}design/tv/index.html">TV Design</a> guide.</p> + + +<h2 id="large-bitmaps">Handling Large Bitmaps</h2> + +<p>TV devices, like any other Android device, have a limited amount of memory. If you build your + app layout with very high-resolution images or use many high-resolution images in the operation + of your app, it can quickly run into memory limits and cause out of memory errors. + To avoid these types of problems, follow these tips:</p> + +<ul> + <li>Load images only when they're displayed on the screen. For example, when displaying multiple images in + a {@link android.widget.GridView} or + {@link android.widget.Gallery}, only load an image when + {@link android.widget.Adapter#getView(int, View, ViewGroup) getView()} + is called on the View's {@link android.widget.Adapter}. + </li> + <li>Call {@link android.graphics.Bitmap#recycle()} on + {@link android.graphics.Bitmap} views that are no longer needed. + </li> + <li>Use {@link java.lang.ref.WeakReference} for storing references + to {@link android.graphics.Bitmap} objects in an in-memory + {@link java.util.Collection}.</li> + <li>If you fetch images from the network, use {@link android.os.AsyncTask} + to fetch and store them on the device for faster access. + Never do network transactions on the application's UI thread. + </li> + <li>Scale down large images to a more appropriate size as you download them; + otherwise, downloading the image itself may cause an out of memory exception. + The following sample code demonstrates how to scale down images while downloading: +<pre> + // Get the source image's dimensions + BitmapFactory.Options options = new BitmapFactory.Options(); + // This does not download the actual image, just downloads headers. + options.inJustDecodeBounds = true; + BitmapFactory.decodeFile(IMAGE_FILE_URL, options); + // The actual width of the image. + int srcWidth = options.outWidth; + // The actual height of the image. + int srcHeight = options.outHeight; + + // Only scale if the source is bigger than the width of the destination view. + if(desiredWidth > srcWidth) + desiredWidth = srcWidth; + + // Calculate the correct inSampleSize/scale value. This approach helps reduce + // memory use. This value should be a power of 2. + int inSampleSize = 1; + while(srcWidth / 2 > desiredWidth){ + srcWidth /= 2; + srcHeight /= 2; + inSampleSize *= 2; + } + + float desiredScale = (float) desiredWidth / srcWidth; + + // Decode with inSampleSize + options.inJustDecodeBounds = false; + options.inDither = false; + options.inSampleSize = inSampleSize; + options.inScaled = false; + // Ensures the image stays as a 32-bit ARGB_8888 image. + // This preserves image quality. + options.inPreferredConfig = Bitmap.Config.ARGB_8888; + + Bitmap sampledSrcBitmap = BitmapFactory.decodeFile(IMAGE_FILE_URL, options); + + // Resize + Matrix matrix = new Matrix(); + matrix.postScale(desiredScale, desiredScale); + Bitmap scaledBitmap = Bitmap.createBitmap(sampledSrcBitmap, 0, 0, + sampledSrcBitmap.getWidth(), sampledSrcBitmap.getHeight(), matrix, true); + sampledSrcBitmap = null; + + // Save + FileOutputStream out = new FileOutputStream(LOCAL_PATH_TO_STORE_IMAGE); + scaledBitmap.compress(Bitmap.CompressFormat.JPEG, 100, out); + scaledBitmap = null; +</pre> + </li> +</ul> + diff --git a/docs/html/preview/tv/ui/navigation.jd b/docs/html/preview/tv/ui/navigation.jd new file mode 100644 index 0000000..92b34cf --- /dev/null +++ b/docs/html/preview/tv/ui/navigation.jd @@ -0,0 +1,136 @@ +page.title=Navigation for TV + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#d-pad-navigation">D-pad Navigation</a></li> + <li><a href="#focus-selection">Focus and Selection</a></li> + </ol> + +</div> +</div> + +<p>TV devices provide a limited set of navigation controls for apps. Creating an effective + navigation scheme for your TV app depends on understanding these limited controls and the limits + of users' perception while operating your app. As you build your Android app for TVs, + you should pay special attention to how the user actually navigates around your app + when using remote control buttons instead of a touch screen.</p> + +<p>This guide shows you how to build an effective navigation scheme for your TV app.</p> + + +<h2 id="d-pad-navigation">D-pad Navigation</h2> + +<p>On a TV device, users navigate with controls on a remote control device, using either a + directional pad (D-pad) or arrow keys. This type of control limits movement to up, down, left, + and right. To build a great TV-optimized app, you must provide a navigation scheme where + the user can quickly learn how to navigate your app using these limited controls.</p> + +<p>Follow these guidelines to build a navigation system that works well with a D-pad on a TV device: +</p> + +<ul> + <li>Ensure that the D-pad can navigate to all the visible controls on the screen.</li> + <li>For scrolling lists with focus, D-pad up/down keys scroll the list, and the Enter key selects + an item in the list. Ensure that users can select an element in the list and that the list still + scrolls when an element is selected.</li> + <li>Ensure that movement between controls is straightforward and predictable.</li> +</ul> + +<p>The Android framework handles directional navigation between layout elements automatically, so + you typically do not need to do anything extra for your app. However, you should thoroughly test + navigation with a D-pad control to discover any navigation problems. If you discover that your + screen layout makes navigation difficult, or if you want users to move through the layout in a + specific way, you can set up explicit directional navigation for your controls. The following + code sample shows how to define the next control to receive focus for a + {@link android.widget.TextView} layout object:</p> + +<pre> +<TextView android:id="@+id/Category1" + android:nextFocusDown="@+id/Category2"\> +</pre> + +<p>The following table lists all of the available navigation attributes for Android user interface +widgets:</p> + +<table> + <tr> + <th>Attribute</th> + <th>Function</th> + </tr> + <tr> + <td>{@link android.R.attr#nextFocusDown}</td> + <td>Defines the next view to receive focus when the user navigates down.</td> + </tr> + <tr> + <td>{@link android.R.attr#nextFocusLeft}</td> + <td>Defines the next view to receive focus when the user navigates left.</td> + </tr> + <tr> + <td>{@link android.R.attr#nextFocusRight}</td> + <td>Defines the next view to receive focus when the user navigates right.</td> + </tr> + <tr> + <td>{@link android.R.attr#nextFocusUp}</td> + <td>Defines the next view to receive focus when the user navigates up.</td> + </tr> +</table> + +<p>To use one of these explicit navigation attributes, set the value to the ID ({@code android:id} + value) of another widget in the layout. You should set up the navigation order as a loop, so that + the last control directs focus back to the first one.</p> + +<p class="note"> + <strong>Note:</strong> You should only use these attributes to modify the navigation order if the + default order that the system applies does not work well. +</p> + + +<h2 id="focus-selection">Focus and Selection</h2> + +<p>The success of a navigation scheme on TV devices is strongly dependent on how easy it is for a + user to determine what user interface element is in focus on screen. If you do not provide clear + indications of what is in focus on screen (and therefore what item they can take action on), + users can quickly become frustrated and exit your app. By the same token, it is important + to always have an item in focus that a user can take action on immediately after your app starts, + and any time your app is not playing content.</p> + +<p>Your app layout and implementation should use color, size, animation, or a combination of + these attributes to help users easily determine what actions they can take next. Use a uniform + scheme for indicating focus across your application.</p> + +<p>Android provides <a href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList"> +Drawable State List Resources</a> to implement highlights for selected and focused controls. The +following code example demonstates how to indicate selection of a button object: +</p> + +<pre> +<!-- res/drawable/button.xml --> +<?xml version="1.0" encoding="utf-8"?> +<selector xmlns:android="http://schemas.android.com/apk/res/android"> + <item android:state_pressed="true" + android:drawable="@drawable/button_pressed" /> <!-- pressed --> + <item android:state_focused="true" + android:drawable="@drawable/button_focused" /> <!-- focused --> + <item android:state_hovered="true" + android:drawable="@drawable/button_focused" /> <!-- hovered --> + <item android:drawable="@drawable/button_normal" /> <!-- default --> +</selector> +</pre> + +<p> +This layout XML applies the above state list drawable to a {@link android.widget.Button}: +</p> +<pre> +<Button + android:layout_height="wrap_content" + android:layout_width="wrap_content" + android:background="@drawable/button" /> +</pre> + +<p>Make sure to provide sufficient padding within the focusable and selectable controls so that + the highlights around them are clearly visible.</p> + diff --git a/docs/html/preview/tv/ui/recommendations.jd b/docs/html/preview/tv/ui/recommendations.jd new file mode 100644 index 0000000..2c78064 --- /dev/null +++ b/docs/html/preview/tv/ui/recommendations.jd @@ -0,0 +1,209 @@ +page.title=Making Recommendations + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#service">Create a Recommendations Service</a></li> + <li><a href="#build">Build Recommendations</a></li> + <li><a href="#run-service">Run Recommendations Service</a></li> + <li><a href="#DesignLandscapeLayouts">Design Landscape Layouts</a></li> + </ol> + +</div> +</div> + + +<p>Content recommendations appear as the first row of the TV launch screen after the first use + of the device. This row is intended to help users quickly find content they enjoy. Contributing + recommendations from your apps content catalog can help bring users back to your app.</p> + + +<img src="{@docRoot}preview/tv/images/home-recommendations.png" alt="" id="figure1" /> +<p class="img-caption"> + <strong>Figure 1.</strong> An example of the recommendations row. +</p> + + +<h2 id="service">Create a Recommendations Service</h2> + +<p>Content recommendations are created with background processing. In order for your application + to contribute to recommendations, you create a service that periodically adds listings from your + app's catalog to the system list of recommendations.</p> + +<p>The following code example illustrates how to extend the {@link android.app.IntentService} to + create a recommendation service for your application.</p> + +<pre> +public class RecommendationsService extends IntentService { + private static final int MAX_RECOMMENDATIONS = 3; + + public RecommendationsService() { + super("RecommendationService"); + } + + @Override + protected void onHandleIntent(Intent intent) { + MovieDatabase database = MovieDatabase.instance(getApplicationContext()); + List<Movie> recommendations = database.recommendations(); + + int count = 0; + + try { + for (Movie movie : recommendations) { + // build the individual content recommendations + buildRecommendation(getApplicationContext(), movie); + + if (++count >= MAX_RECOMMENDATIONS) { + break; + } + } + } catch (IOException e) { + Log.e(TAG, "Unable to update recommendation", e); + } + } +} +</pre> + +<p>In order for this class to be recognized and run as a service, you must register this service + using your app manifest. The following code snippet illustrates how to add this class as a + service:</p> + +<pre> +<manifest ... > + <application ... > + ... + + <service android:name=".RecommendationsService" + android:enabled="true" android:exported="true"/> + </application> +</manifest> +</pre> + +<h2 id="build">Build Recommendations</h2> + +<p>Once it starts running, your service must create recommendations and pass them to the Android + framework. The framework receives the recommendations as {@link android.app.Notification} objects + that use a specific style and are marked with a specific category.</p> + +<p>The following code example demonstrates how to get an instance of the {@link + android.app.NotificationManager}, build a recommendation, and post it to the manager:</p> + +<pre> +public class RecommendationsService extends IntentService { + + ... + + public Notification buildRecommendation(Context context, Movie movie) + throws IOException { + + if (mNotificationManager == null) { + mNotificationManager = (NotificationManager) + mContext.getSystemService(Context.NOTIFICATION_SERVICE); + } + + Bundle extras = new Bundle(); + if (mBackgroundUri != movie.getBackgroundUri()) { + extras.putString(EXTRA_BACKGROUND_IMAGE_URL, movie.getBackgroundUri()); + } + + // build the recommendation as a Notification object + Notification notification = new NotificationCompat.BigPictureStyle( + new NotificationCompat.Builder(context) + .setContentTitle(movie.getTitle()) + .setContentText(movie.getDescription()) + .setPriority(movie.getPriority()) + .setOngoing(true) + .setCategory("recommendation") + .setLargeIcon(movie.getImage()) + .setSmallIcon(movie.getSmallIcon()) + .setContentIntent(buildPendingIntent(movie.getId())) + .setExtras(extras)) + .build(); + + // post the recommendation to the NotificationManager + mNotificationManager.notify(movie.getId(), notification); + mNotificationManager = null; + return notification; + } + + private PendingIntent buildPendingIntent(long id) { + Intent detailsIntent = new Intent(this, DetailsActivity.class); + detailsIntent.putExtra("id", id); + + TaskStackBuilder stackBuilder = TaskStackBuilder.create(this); + stackBuilder.addParentStack(DetailsActivity.class); + stackBuilder.addNextIntent(detailsIntent); + // Ensure each PendingIntent is unique + detailsIntent.setAction(Long.toString(id)); + + PendingIntent intent = stackBuilder.getPendingIntent( + 0, PendingIntent.FLAG_UPDATE_CURRENT); + return intent; + } +} +</pre> + + +<h3 id="run-service">Run Recommendations Service</h3> + +<p>Your app's recommendation service must run periodically in order to create current + recommendations. In order to run your service, you should create a class that runs a timer and + invokes it at regular intervals. The following code example extends the {@link + android.content.BroadcastReceiver} class to start periodic execution of a recommendation service + every 12 hours:</p> + +<pre> +public class BootupReceiver extends BroadcastReceiver { + private static final String TAG = "BootupActivity"; + + private static final long INITIAL_DELAY = 5000; + + @Override + public void onReceive(Context context, Intent intent) { + if (intent.getAction().endsWith(Intent.ACTION_BOOT_COMPLETED)) { + scheduleRecommendationUpdate(context); + } + } + + private void scheduleRecommendationUpdate(Context context) { + AlarmManager alarmManager = (AlarmManager)context.getSystemService( + Context.ALARM_SERVICE); + Intent recommendationIntent = new Intent(context, + UpdateRecommendationsService.class); + PendingIntent alarmIntent = PendingIntent.getService(context, 0, + recommendationIntent, 0); + + alarmManager.setInexactRepeating(AlarmManager.ELAPSED_REALTIME_WAKEUP, + INITIAL_DELAY, + AlarmManager.INTERVAL_HALF_DAY, + alarmIntent); + } +} +</pre> + +<p>In order for the {@link android.content.BroadcastReceiver} class to execute after a TV + device starts up, you must register this class in your app manifest and attach an intent filter + in order for the device boot process to complete. This sample code demonstrates how to add this + configuration to the manifest:</p> + +<pre> +<manifest ... > + <application ... > + <receiver android:name=".BootupReceiver" android:enabled="true" + android:exported="false"> + <intent-filter> + <action android:name="android.intent.action.BOOT_COMPLETED"/> + </intent-filter> + </receiver> + </application> +</manifest> +</pre> + +<p class="important"> + <strong>Important:</strong> Receiving a boot completed notification requires that your app + request the {@link android.Manifest.permission#RECEIVE_BOOT_COMPLETED} permission. + For more information, see {@link android.content.Intent#ACTION_BOOT_COMPLETED}. +</p> |
