Merge "docs: Fixing the remaining issues with the Auto page" into klp-modular-dev
diff --git a/docs/html/preview/tv/adt-1/index.jd b/docs/html/preview/tv/adt-1/index.jd
index 47bab23..062968e 100644
--- a/docs/html/preview/tv/adt-1/index.jd
+++ b/docs/html/preview/tv/adt-1/index.jd
@@ -3,17 +3,317 @@
@jd:body
-<p>Information about the ADT-1 developer kit, including:</p>
+<div id="qv-wrapper">
+<div id="qv">
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#faq">ADT-1 Frequently Asked Questions</a></li>
+ <li><a href="#regulatory">Regulatory Disclosures</a></li>
+ <li><a href="#safety">Important Safety Instructions</a></li>
+ </ol>
+</div>
+</div>
+
+<p class="note">
+ <strong>!FIX: FOR REVIEW ONLY:</strong> link to <a href="request.html">ADT-1 Request</a> page.
+</p>
+
+
+<p>The ADT-1 Developer Kit is streaming media player and game controller designed for running
+and testing app built for Android TV. The kit is provided to a limited number of 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-Preview SDK 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>
+ <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>How do I perform a hard reset of ADT-1?</strong>
+</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 will boot. Note: this is
+ a factory data reset, thus all downloaded apps, system and app data, and account settings will be
+ lost.</p>
+
+<p>
+ <strong>How do I do a soft reset?</strong>
+</p>
+<p>Go to Settings - Device - Factory data reset, and select ‘Reset device’. Note: this is a
+ factory data reset, thus all downloaded apps, system and app data, and account settings will be
+ lost.</p>
+
+<p>
+ <strong>How do I turn my device on?</strong>
+</p>
+<p>Plug in the included power cable into the back of ADT-1. There is no on/off switch.</p>
+
+<p>
+ <strong>How do I completely turn my device off? </strong>
+</p>
+<p>Unplug in the included power cable from the back of ADT-1. There is no on/off switch.
+ However, ADT-1 will begin sleeping (daydream) based on user settings in Display -> Daydream.</p>
+
+<p>
+ <strong>How do I connect to the network?</strong>
+</p>
+<p>ADT-1 has both Wi-Fi and Ethernet for connecting to your network. To change your Wi-Fi
+ network, go to Settings -> Wi-Fi. To use an Ethernet network connection, simply plug in 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>
+
+<p>
+ <strong>Is there an app for phone and tablet that I can use to control ADT-1?</strong>
+</p>
+<p>Yes, you can download the remote control app from Android phones and tablets here.</p>
+
+<p>
+ <strong>Can I connect a USB keyboard/mouse to ADT-1?</strong>
+</p>
+<p>Yes, you can connect a USB keyboard/mouse to the USB port on the back of ADT-1. Note: not all
+ manufacturers/models are guaranteed to work.</p>
+<hr />
+<p>
+ 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. To pair Bluetooth
+ devices to ADT-1 from the UI, go to <strong>Settings > Remote & Accessories >
+ Add accessory</strong>.
+</p>
+
+
+
+<h2 id="regulatory">Regulatory Disclosures</h2>
+
+
+<p>Model: W2</p>
+<p>FCC ID: A4R-W2</p>
+<p>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>
+
+
+<h2 id="safety">Important Safety Instructions</h2>
+
+<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>General description and FAQ</li>
- <li>Emote info and deep link to Play Store</li>
- <li>Regulatory Notifications (FCC and Industry Canada)</li>
+ <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>To be included, but not listed on page:</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><a href="request.html">ADT-1 Request Page</a></li>
-</ul>
\ No newline at end of file
+ <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/adt-1/request.jd b/docs/html/preview/tv/adt-1/request.jd
index dc13de0..69e3e4e 100644
--- a/docs/html/preview/tv/adt-1/request.jd
+++ b/docs/html/preview/tv/adt-1/request.jd
@@ -2,4 +2,46 @@
@jd:body
-<p>Request form for the ADT-1 developer kit</p>
\ No newline at end of file
+
+<p>The ADT-1 Developer Kit is streaming media player and game controller designed for running
+and testing app built for Android TV. The kit is offered to developers who are interested in
+building new apps or extending their existing apps to run on the Android TV platform before
+the commercial release of Android TV devices. Supplies of the ADT-1 kit are limited and
+requesting one not guarantee it will be delivered to you.</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-Preview SDK 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.
+ For more information about the ADT-1 kit, see the
+ <a href="{@docRoot}preview/tv/adt-1/index.html">ADT-1 Developer Kit</a> information page.
+</p>
+
+<div class="sdk-terms" style="width:678px" onfocus="this.blur()">
+<div class="sdk-terms-padding">
+Android ADT-1 Developer Kit Request Agreement.
+
+1. These are the terms.
+
+2. You must agree to the terms.
+
+3. Otherwise you have not agreed to the terms.
+
+4. And then we don't want to talk to you.
+</div>
+</div>
+
+
+<p class="caution">
+ <strong>Important:</strong> The email address your provide in this form is used to verify
+ you as an Android developer. Please provide a Google account email address that is associated
+ with the Google Play app you enter. We may also use your email address to provide you with
+ updates about the ADT-1 Developer Kit and Android TV.
+</p>
+
+<iframe src="https://docs.google.com/a/google.com/forms/d/1MLhC39rf3aAJw-KhZw9cyjT1dWuz_k3_iC5QXpC4Cbw/viewform?embedded=true"
+ width="100%" height="540" frameborder="0" marginheight="0" marginwidth="0"
+ id="signupform">Loading...</iframe>
+
diff --git a/docs/html/preview/tv/games/index.jd b/docs/html/preview/tv/games/index.jd
index 9471df0..b9de3a4 100644
--- a/docs/html/preview/tv/games/index.jd
+++ b/docs/html/preview/tv/games/index.jd
@@ -3,8 +3,9 @@
@jd:body
-<p>This document complements the larger best-practice guidelines for [Design for TV](TODO, use formal name of referenced doc, and add link). It assumes that you have read those guidelines, and seeks to minimize repetition.</p>
-<h3>Overview</h3>
+<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>
@@ -13,54 +14,57 @@
<li>Google Play Game Services</li>
<li>Web</li>
</ul>
-<h3>Display</h3>
-<h4>A shared display</h4>
-<p>A living-room TV presents design challenges for multiplayer games, in that all of the 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>
+<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>In a turn-based game, like a word or card game, one player at a time might view the display. On finishing her move, the game allows the player to cover the screen with a “blinder”. When the next player takes his turn, he opens the blinder to reveal the information he’s allowed to be seeing.</li>
-<li>Using a second screen, such as a phone or tablet, 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>
+<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>
-<h4>No touch interface</h4>
+<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 Control 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>
-<h4>Landscape display</h4>
+<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>
-<h3>Control</h3>
-<h4>D-pad</h4>
+<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. A widely accepted standard has the A button serving to <code>Accept</code>, and the B button serving to <code>Cancel</code>. You can also offer flexibility in the form of remappability. For more information on button mapping, <a href="http://developer.android.com/training/game-controllers/controller-input.html">Handling Controller Actions</a>.</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>
-<h4>Back-button behavior</h4>
+<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, the back button may leave an in-game menu (opened by a different button) to return to gameplay.</p>
-<h4>Handling multiple controllers</h4>
+<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>
-<h4>Handling disconnects</h4>
+<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>
-<h3>Manifest</h3>
-<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>. </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><h3>Google Play Game Services</h3>
+</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>
-<h4>Achievements</h4>
+<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>
-<h4>Sign-on</h4>
+<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>
-<h4>Saving</h4>
-<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 her phone or her tablet, the game should be able to pull the same game-save information from her account.</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>
-<h4>Multiplayer experience</h4>
+<h3>Multiplayer experience</h3>
<p>A game offering a multiplayer experience must allow at least two players to enter a room.</p>
-<h3>Web</h3>
+<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/start/hardware-features.jd b/docs/html/preview/tv/start/hardware-features.jd
index 3c1cd78..f3b51bb 100644
--- a/docs/html/preview/tv/start/hardware-features.jd
+++ b/docs/html/preview/tv/start/hardware-features.jd
@@ -7,25 +7,35 @@
<div id="qv">
<h2>In this document</h2>
<ol>
- <li><a href="#WorkaroundUnsupportedFeatures">Handle Unsupported Features</a></li>
- <li><a href="#CheckAvailableFeatures">Check Available Features</a></li>
+ <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 are much different from other Android-powered devices:
-</p>
-<ul>
- <li>They're not mobile.</li>
- <li>Out of habit, people use them for watching media with little or no interaction.</li>
- <li>People interact with them from a distance.</li>
-</ul>
+<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>
-Because TVs have a different purpose from other devices, they usually don't 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:
+<p>This guide discusses the hardware features not available on TV devices and shows you how to
+work around those limitations in your app.</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>
@@ -58,93 +68,107 @@
</table>
</p>
-<p>
-This lesson shows you how to work around features that are not available on TV by:
-<ul>
- <li>Providing work arounds for some non-supported features.</li>
- <li>Checking for available features at runtime and conditionally activating/deactivating certain code
- paths based on availability of those features.</li>
-</ul>
-</p>
+<h2 id="check-features">Checking Available Features</h2>
-<h2 id="WorkaroundUnsupportedFeatures">Handle Unsupported 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>
-Android doesn't support touchscreen interaction for TV devices, most TVs don't have touch screens,
-and interacting with a TV using a touchscreen is not consistent with the 10 foot environment. For
-these reasons, users interact with Android-powered TVs using a remote. In consideration of this,
-ensure that every control in your app can be accessed with the D-pad. Refer back to the previous two lessons
-<a href="{@docRoot}training/tv/optimizing-layouts-tv.html">Optimizing Layouts for TV</a> and
-<a href="{@docRoot}training/tv/optimizing-navigation-tv.html">Optimize Navigation for TV</a> for
-more details
-on this topic. The Android system assumes that a device has a touchscreen, so if you want your application
-to run on a TV, you must <strong>explicitly</strong> disable the touchscreen requirement in your manifest file:
+<p>The following code example demonstrates how to detect the availability of a hardware features
+ at runtime:</p>
+
<pre>
-<uses-feature android:name="android.hardware.touchscreen" android:required="false"/>
+// 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>
-<p>
-Although a TV doesn't 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. The next section talks about how to
-deactivate or activate specific functions in the application based on runtime device type detection.
-</p>
-<p>
-Because TVs are stationary, indoor devices, they don't have built-in GPS. If your application uses location
-information, allow users to search for a location or use a "static" location provider to get
-a location from the zip code configured during the TV setup.
+<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 workaround 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 workaround 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>
-LocationManager locationManager = (LocationManager) this.getSystemService(Context.LOCATION_SERVICE);
+<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 make 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);
+ 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>
-</p>
-<p>
-TVs usually don't support microphones, but if you have an application that uses voice control,
-you can create a mobile device app that takes voice input and then acts as a remote control for a TV.
-</p>
-
-<h2 id="CheckAvailableFeatures">Check 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 argument : a string corresponding to the
-feature you want to check. For example, to check for touchscreen, use
-{@link android.content.pm.PackageManager#hasSystemFeature(String)} with the argument
-{@link android.content.pm.PackageManager#FEATURE_TOUCHSCREEN}.
-</p>
-
-<p>
-The following code snippet demonstrates how to detect device type at runtime based on supported features:
-
-<pre>
-// Check if android.hardware.telephony 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 telphony but have a touchscreen.");
-} else {
- Log.d("TV Test", "Running on a TV!");
-}
-</pre>
-</p>
-
-<p>
-This is just one example of using runtime checks to deactivate app functionality that depends on features
-that aren't available on TVs.
-</p>
\ No newline at end of file
diff --git a/docs/html/preview/tv/ui/browse.jd b/docs/html/preview/tv/ui/browse.jd
index b74c209..9d878b0 100644
--- a/docs/html/preview/tv/ui/browse.jd
+++ b/docs/html/preview/tv/ui/browse.jd
@@ -20,8 +20,9 @@
</div>
</div>
-<p>The Leanback support library provides several APIs for displaying and browsing media catalogs
- on the TV devices. This lesson discusses how to use the classes provided by this library to
+<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>
diff --git a/docs/html/preview/tv/ui/details.jd b/docs/html/preview/tv/ui/details.jd
index 86688d5..7da3b5d 100644
--- a/docs/html/preview/tv/ui/details.jd
+++ b/docs/html/preview/tv/ui/details.jd
@@ -23,11 +23,14 @@
</div>
</div>
-<p>The media browsing interface classes provided by the leanback support library include classes
- for displaying additional information about a media item, such as a description or reviews, and
- 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>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 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
@@ -49,7 +52,8 @@
the following code sample:</p>
<pre>
-public class DetailsDescriptionPresenter extends AbstractDetailsDescriptionPresenter {
+public class DetailsDescriptionPresenter
+ extends AbstractDetailsDescriptionPresenter {
@Override
protected void onBindDescription(ViewHolder viewHolder, Object itemData) {
diff --git a/docs/html/preview/tv/ui/layouts.jd b/docs/html/preview/tv/ui/layouts.jd
index 0c2448e..5655152 100644
--- a/docs/html/preview/tv/ui/layouts.jd
+++ b/docs/html/preview/tv/ui/layouts.jd
@@ -12,162 +12,217 @@
<div id="qv">
<h2>In this document</h2>
<ol>
- <li><a href="#DesignLandscapeLayouts">Design Landscape Layouts</a></li>
- <li><a href="#MakeTextControlsEasyToSee">Make Text and Controls Easy to See</a></li>
- <li><a href="#DesignForLargeScreens">Design for High-Density Large Screens</a></li>
- <li><a href="#HandleLargeBitmaps">Design to Handle Large Bitmaps</a></li>
+ <li><a href="#themes">Themes</a>
+ <ol>
+ <li><a href="#leanback-theme">Leanback 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>
-When your application is running on a television set, you should assume that the user is sitting about
-ten feet away from the screen. This user environment is referred to as the
-<a href="http://en.wikipedia.org/wiki/10-foot_user_interface">10-foot UI</a>. To provide your
-users with a usable and enjoyable experience, you should style and lay out your UI accordingly..
-</p>
-<p>
-This lesson shows you how to optimize layouts for TV by:
-</p>
-<ul>
- <li>Providing appropriate layout resources for landscape mode.</li>
- <li>Ensuring that text and controls are large enough to be visible from a distance.</li>
- <li>Providing high resolution bitmaps and icons for HD TV screens.</li>
-</ul>
+ 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>
-<h2 id="DesignLandscapeLayouts">Design Landscape Layouts</h2>
+<p>This guide provides guidance and implementation details for building effective layouts for
+ TV apps.</p>
-<p>
-TV screens are always in landscape orientation. Follow these tips to build landscape layouts optimized for TV screens:
+
+<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 apps. On TV devices, you should use a theme to suppress the title bar from
+ your app activities that are meant for TV. The title bar is a standard user interface element
+ for Android apps on phones and tablets, but it is not appropriate for TV apps. The following
+ code example from TV app manifest demonstrates how to apply this theme:
</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>
+
+
+<h3 id="leanback-theme">Leanback Theme</h3>
+
+<p>The Android framework 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. 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="@android:style/Theme.Leanback"</strong>>
+</pre>
+
+
+<h2 id="structure">Layout Structure</h2>
+
+<p>Layouts for TV devices should follow some basic guidelines to ensure they are useable and
+ effective on large screens. Follow these tips to build landscape layouts optimized for TV screens:
+</p>
+
<ul>
- <li>Put on-screen navigational 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, by 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 allows the Android system to adjust the position of the views to the size, alignment,
- aspect ratio, and pixel density of the TV screen.</li>
+ <li>Build layouts with a landscape orientation. TV screens are always displayed in this
+ orientation.</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>
-<p>
-For example, the following layout is optimized for TV:
-</p>
-<img src="{@docRoot}images/training/panoramio-grid.png" />
+<h3 id="overscan">Overscan</h3>
-<p>
-In this layout, the controls are on the lefthand side. The UI is displayed within a
-{@link android.widget.GridView}, which is well-suited to landscape orientation.
-In this layout both GridView and Fragment have the width and height set
-dynamically, so they can adjust to the screen resolution. Controls are added to the left side Fragment programatically at runtime.
-The layout file for this UI is {@code res/layout-land-large/photogrid_tv.xml}.
-(This layout file is placed in {@code layout-land-large} because TVs have large screens with landscape orientation. For details refer to
-<a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.)</p>
+<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 a that the entire display is filled.
+ This behavior is generally referred to as Overscan.</p>
-res/layout-land-large/photogrid_tv.xml
-<pre>
-<RelativeLayout
- android:layout_width="fill_parent"
- android:layout_height="fill_parent" >
-
- <fragment
- android:id="@+id/leftsidecontrols"
- android:layout_width="0dip"
- android:layout_marginLeft="5dip"
- android:layout_height="match_parent" />
-
- <GridView
- android:id="@+id/gridview"
- android:layout_width="wrap_content"
- android:layout_height="wrap_content" />
-
-</RelativeLayout>
-</pre>
-
-<p>
-To set up action bar items on the left side of the screen, you can also include the <a
-href="http://code.google.com/p/googletv-android-samples/source/browse/#git%2FLeftNavBarLibrary">
-Left navigation bar library</a> in your application to set up action items on the left side
-of the screen, instead of creating a custom Fragment to add controls:
+<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>
-LeftNavBar bar = (LeftNavBarService.instance()).getLeftNavBar(this);
+<?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>
-When you have an activity in which the content scrolls vertically, always use a left navigation bar;
-otherwise, your users have to scroll to the top of the content to switch between the content view and
-the ActionBar. Look at the
-<a href="http://code.google.com/p/googletv-android-samples/source/browse/#git%2FLeftNavBarDemo">
-Left navigation bar sample app</a> to see how to simple it is to include the left navigation bar in your app.
+<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="MakeTextControlsEasyToSee">Make Text and Controls Easy to See</h2>
+
+<h2 id="visibility">Text and Controls Visibility</h2>
+
<p>
-The text and controls in a TV application's UI should be easily visible and navigable from a distance.
+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 use anti-aliasing to increase readability.</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.
+<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>
-<p>
-</p>
-<h2 id="DesignForLargeScreens">Design for High-Density Large Screens</h2>
+<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>
-The common HDTV display resolutions are 720p, 1080i, and 1080p. Design your UI for 1080p, and then
-allow the Android system to downscale your UI to 720p if necessary. In general, downscaling (removing pixels)
-does not degrade the UI (Notice that the converse is not true; you should avoid upscaling because it degrades
-UI quality).
+ 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>
-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.
+ 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>
-<p>
-For more information on optimizing apps for large screens see <a href="{@docRoot}training/multiscreen/index.html">
-Designing for multiple screens</a>.
+
+<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>
-<h2 id="HandleLargeBitmaps">Design to Handle Large Bitmaps</h2>
+<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
+ antion 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>
-<p>
-The Android system has a limited amount of memory, so downloading and storing high-resolution images can often
-cause out-of-memory errors in your app. To avoid this, follow these tips:
-</p>
+</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-resolutions 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
@@ -186,10 +241,10 @@
to fetch them and store them on the SD card for faster access.
Never do network transactions on the application's UI thread.
</li>
- <li>Scale down really large images to a more appropriate size as you download them; otherwise, downloading the image
- itself may cause an "Out of Memory" exception. Here is sample code that scales down images while downloading:
-
- <pre>
+ <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.
@@ -204,7 +259,8 @@
if(desiredWidth > srcWidth)
desiredWidth = srcWidth;
- // Calculate the correct inSampleSize/scale value. This helps reduce memory use. It should be a power of 2.
+ // 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;
@@ -236,65 +292,7 @@
FileOutputStream out = new FileOutputStream(LOCAL_PATH_TO_STORE_IMAGE);
scaledBitmap.compress(Bitmap.CompressFormat.JPEG, 100, out);
scaledBitmap = null;
- </pre>
- </li> </ul>
-
-
-<h2>Themes and Layouts</h2>
-
-<p>
- In general, layouts shown in the context of TV devices must be built to be simpler and less
- demanding of the user. The <a href="{@docRoot}design/tv/index.html">TV Style Guide</a> provides
- more guidance on how to design an effective app for TV use.
-</p>
-
-<p>Here are some common Android user interface elements that you should specifically NOT use for
- a TV interface:</p>
-
-<ul>
- <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
- ActionBar 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>
+</pre>
+ </li>
</ul>
-
-<h2>Leanback Theme</h2>
-
-<p>The Android framework provides a standard Leanback theme for TV activities, which establishes
- a consistent visual style for TV apps. Use of this theme is recommended for most apps. 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="@android:style/Theme.Leanback"</strong>>
-</pre>
-
-<p>
- <strong>Note:</strong> If you do not using the Leanback theme for your TV activities, apply
- Theme.NoTitleBar to your TV activities to suppress display of an app title bar.
-</p>
-
-
-<h2>Overscan and Layouts</h2>
-
-<p>Application layouts for TV have some unique requirements due to the evolution of TV
- standards. In short, items placed on the edge of a layout may be cut short or not displayed at all
- due to TV manufacturers implementation of overscan.</p>
-
-<p>
- In order to 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. For more information on designing for TV overscan, see the
- <a href="{@docRoot}design/tv/index.html">TV Style Guide</a>.
-</p>
-
-<p class="caution">
- <strong>Caution:</strong> Do not apply overscan margins to your layout if you are using the
- leanback BrowseFragment or other leanback Fragment widgets, as those layouts already incorporate
- overscan-safe margins.
-</p>
diff --git a/docs/html/preview/tv/ui/navigation.jd b/docs/html/preview/tv/ui/navigation.jd
index f91ae38..3041e58 100644
--- a/docs/html/preview/tv/ui/navigation.jd
+++ b/docs/html/preview/tv/ui/navigation.jd
@@ -14,37 +14,30 @@
<div id="qv">
<h2>In this document</h2>
<ol>
- <li><a href="#HandleDpadNavigation">D-pad Navigation</a></li>
- <li><a href="#HandleFocusSelection">Visual Indications for Focus and Selection</a></li>
- <li><a href="#DesignForEasyNavigation">Easy Navigation</a></li>
+ <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>An important aspect of the user experience when operating a TV is the direct human interface:
- a remote control. As you optimize your Android application for TVs, you should pay special
- attention to how the user actually navigates around your application when using a remote control
- instead of a touch screen.</p>
+<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 application for TVs,
+ you should pay special attention to how the user actually navigates around your application
+ when using remote control buttons instead of a touch screen.</p>
-<p>This lesson shows you how to optimize navigation for TV by:</p>
-
-<ul>
- <li>Ensuring all layout controls are D-pad navigable</li>
- <li>Providing clear feedback for UI navigation</li>
- <li>Placing layout controls for easy access</li>
-</ul>
+<p>This guide shows you how to build an effective navigation scheme for your TV app.</p>
-<h2 id="HandleDpadNavigation">D-pad Navigation</h2>
+<h2 id="d-pad-navigation">D-pad Navigation</h2>
-<p>On a TV, users navigate with controls on a TV remote, using either a D-pad or arrow keys.
- This limits movement to up, down, left, and right. To build a great TV-optimized app, you must
- provide a navigation scheme in which the user can quickly learn how to navigate your app using the
- remote.</p>
+<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>
-When you design navigation for D-pad, follow these guidelines:
+<p>Follow these guidelines to build navigation system that works well with a D-pad on a TV device:
</p>
<ul>
@@ -55,18 +48,21 @@
<li>Ensure that movement between controls is straightforward and predictable.</li>
</ul>
-<p>Android usually handles navigation order between layout elements automatically, so you don't
- need to do anything extra. If the screen layout makes navigation difficult, or if you want users
- to move through the layout in a specific way, you can set up explicit navigation for your
- controls. For example, for an {@code android.widget.EditText}, to define the next control to
- receive focus, use:</p>
+<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>
-<EditText android:id="@+id/LastNameField"
- android:nextFocusDown="@+id/FirstNameField"\>
+<TextView android:id="@+id/Category1"
+ android:nextFocusDown="@+id/Category2"\>
</pre>
-<p>The following table lists all of the available navigation attributes:</p>
+<p>The following table lists all of the available navigation attributes for Android user interface
+widgets:</p>
<table>
<tr>
@@ -91,7 +87,7 @@
</tr>
</table>
-<p>To use one of these explicit navigation attributes, set the value to the ID (android:id
+<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>
@@ -101,19 +97,26 @@
</p>
-<h2 id="HandleFocusSelection">Visual Indications for Focus and Selection</h2>
+<h2 id="focus-selection">Focus and Selection</h2>
-<p>Use appropriate color highlights for all navigable and selectable elements in the UI. This makes
- it easy for users to know whether the control is currently focused or selected when they navigate
- with a D-pad. Also, use uniform highlight scheme across your application.</p>
+<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>
-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. For example:
+<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 apply selection indication for a button object:
</p>
-res/drawable/button.xml:
<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"
@@ -136,62 +139,6 @@
android:background="@drawable/button" />
</pre>
-<p>Provide sufficient padding within the focusable and selectable controls so that the
- highlights around them are clearly visible.</p>
-
-
-<h2 id="DesignForEasyNavigation">Design for Easy Navigation</h2>
-
-<p>Users should be able to navigate to any UI control with a couple of D-pad clicks. Navigation
- should be easy and intuitive to understand. For any non-intuitive actions, provide users with
- written help, using a dialog triggered by a help button or action bar icon.</p>
-
-<p>Predict the next screen that the user will want to navigate to and provide one click
- navigation to it. If the current screen UI is very sparse, consider making it a multi pane screen.
- Use fragments for making multi-pane screens. For example, consider the multi-pane UI below with
- continent names on the left and list of cool places in each continent on the right.</p>
-
-<img src="{@docRoot}images/training/cool-places.png" alt="" />
-
-<p>The above UI consists of three fragments - <code>left_side_action_controls</code>,
- <code>continents</code>, and <code>places</code> - as shown in its layout xml file below.
- Such multi-pane UIs make D-pad navigation easier and make good use of the horizontal screen
- space for TVs.
-</p>
-
-<pre>
-<!-- res/layout/cool_places.xml -->
-
-<LinearLayout
- android:layout_width="match_parent"
- android:layout_height="match_parent"
- android:orientation="horizontal"
- >
- <fragment
- android:id="@+id/left_side_action_controls"
- android:layout_width="0px"
- android:layout_height="match_parent"
- android:layout_marginLeft="10dip"
- android:layout_weight="0.2"/>
- <fragment
- android:id="@+id/continents"
- android:layout_width="0px"
- android:layout_height="match_parent"
- android:layout_marginLeft="10dip"
- android:layout_weight="0.2"/>
-
- <fragment
- android:id="@+id/places"
- android:layout_width="0px"
- android:layout_height="match_parent"
- android:layout_marginLeft="10dip"
- android:layout_weight="0.6"/>
-
-</LinearLayout>
-</pre>
-
-<p>Also, notice in the UI layout above action controls are on the left hand side of a vertically
- scrolling list to make them easily accessible using D-pad. In general, for layouts with
- horizontally scrolling components, place action controls on left or right hand side and vice versa
- for vertically scrolling components.</p>
+<p>Make sure to provide sufficient padding within the focusable and selectable controls so that
+ the highlights around them are clearly visible.</p>