1 page.title=Building Layouts for TV 2 trainingnavtop=true 3 4 @jd:body 5 6 <div id="tb-wrapper"> 7 <div id="tb"> 8 <h2>This lesson teaches you how to</h2> 9 <ol> 10 <li><a href="#themes">Use Layout Themes for TV</a></li> 11 <li><a href="#structure">Build Basic TV Layouts</a></li> 12 <li><a href="#visibility">Build Useable Text and Controls</a></li> 13 <li><a href="#density-resources">Manage Layout Resources for TV</a></li> 14 <li><a href="#anti-patterns">Avoid Layout Anti-Patterns</a></li> 15 <li><a href="#large-bitmaps">Handle Large Bitmaps</a></li> 16 </ol> 17 <h2>You should also read</h2> 18 <ol> 19 <li><a href="{@docRoot}design/tv/index.html">Android TV Design</a></li> 20 </ol> 21 </div> 22 </div> 23 24 <p> 25 A TV screen is typically viewed from about 10 feet away, and while it is much larger than most 26 other Android device displays, this type of screen does not provide the same level of precise 27 detail and color as a smaller device. These factors require you to create app layouts with TV 28 devices in mind in order to create a useful and enjoyable user experience. 29 </p> 30 31 <p> 32 This lesson describes the minimum requirements and implementation details for building effective 33 layouts in TV apps. 34 </p> 35 36 <h2 id="themes">Use Layout Themes for TV</h2> 37 38 <p> 39 Android <a href="{@docRoot}guide/topics/ui/themes.html">Themes</a> can provide a basis for 40 layouts in your TV apps. You should use a theme to modify the display of your app activities that 41 are meant to run on a TV device. This section explains which themes you should use. 42 </p> 43 44 <h3 id="leanback-theme">Leanback theme</h3> 45 46 <p> 47 A support library for TV user interfaces called the <a href= 48 "{@docRoot}tools/support-library/features.html#v17-leanback">v17 leanback library</a> provides a 49 standard theme for TV activities, called {@code Theme.Leanback}. This theme establishes a 50 consistent visual style for TV apps. Use of this theme is recommended for most TV apps. This 51 theme is strongly recommended for any TV app that uses v17 leanback classes. The following code 52 sample shows how to apply this theme to a given activity within an app: 53 </p> 54 55 <pre> 56 <activity 57 android:name="com.example.android.TvActivity" 58 android:label="@string/app_name" 59 <strong>android:theme="@style/Theme.Leanback"</strong>> 60 </pre> 61 62 63 <h3 id="notitle-theme">NoTitleBar theme</h3> 64 65 <p> 66 The title bar is a standard user interface element for Android apps on phones and tablets, but it 67 is not appropriate for TV apps. If you are not using v17 leanback classes, you should apply this 68 theme to your TV activities to suppress the display of a title bar. The following code example 69 from a TV app manifest demonstrates how to apply this theme to remove the display of a title bar: 70 </p> 71 72 <pre> 73 <application> 74 ... 75 76 <activity 77 android:name="com.example.android.TvActivity" 78 android:label="@string/app_name" 79 <strong>android:theme="@android:style/Theme.NoTitleBar"</strong>> 80 ... 81 82 </activity> 83 </application> 84 </pre> 85 86 87 <h2 id="structure">Build Basic TV Layouts</h2> 88 89 <p>Layouts for TV devices should follow some basic guidelines to ensure they are usable and 90 effective on large screens. Follow these tips to build landscape layouts optimized for TV screens: 91 </p> 92 93 <ul> 94 <li>Build layouts with a landscape orientation. TV screens always display in landscape mode.</li> 95 <li>Put on-screen navigation controls on the left or right side of the screen and save the 96 vertical space for content.</li> 97 <li>Create UIs that are divided into sections, using <a href="{@docRoot}guide/components/fragments.html" 98 >Fragments</a>, and use view groups like {@link android.widget.GridView} instead of {@link 99 android.widget.ListView} to make better use of the horizontal screen space. 100 </li> 101 <li>Use view groups such as {@link android.widget.RelativeLayout} or {@link 102 android.widget.LinearLayout} to arrange views. This approach allows the system to adjust the 103 position of the views to the size, alignment, aspect ratio, and pixel density of a TV screen.</li> 104 <li>Add sufficient margins between layout controls to avoid a cluttered UI.</li> 105 </ul> 106 107 108 <h3 id="overscan">Overscan</h3> 109 110 <p>Layouts for TV have some unique requirements due to the evolution of TV standards and the 111 desire to always present a full screen picture to viewers. For this reason, TV devices may 112 clip the outside edge of an app layout in order to ensure that the entire display is filled. 113 This behavior is generally referred to as <em>overscan</em>. 114 </p> 115 116 <p> 117 Avoid screen elements being clipped due to overscan and by incorporating a 10% margin 118 on all sides of your layout. This translates into a 27dp margin on the left and right edges and 119 a 48dp margin on the top and bottom of your base layouts for activities. The following 120 example layout demonstrates how to set these margins in the root layout for a TV app: 121 </p> 122 123 <pre> 124 <?xml version="1.0" encoding="utf-8"?> 125 <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" 126 android:id="@+id/base_layout" 127 android:layout_width="match_parent" 128 android:layout_height="match_parent" 129 android:orientation="vertical" 130 android:layout_marginTop="27dp" 131 android:layout_marginLeft="48dp" 132 android:layout_marginRight="48dp" 133 android:layout_marginBottom="27dp" > 134 </LinearLayout> 135 </pre> 136 137 <p class="caution"> 138 <strong>Caution:</strong> Do not apply overscan margins to your layout if you are using the 139 v17 leanback classes, such as {@link android.support.v17.leanback.app.BrowseFragment} or related 140 widgets, as those layouts already incorporate overscan-safe margins. 141 </p> 142 143 <h2 id="visibility">Build Useable Text and Controls</h2> 144 145 <p> 146 The text and controls in a TV app layout should be easily visible and navigable from a distance. 147 Follow these tips to make your user interface elements easier to see from a distance: 148 </p> 149 150 <ul> 151 <li>Break text into small chunks that users can quickly scan.</li> 152 <li>Use light text on a dark background. This style is easier to read on a TV.</li> 153 <li>Avoid lightweight fonts or fonts that have both very narrow and very broad strokes. 154 Use simple sans-serif fonts and anti-aliasing to increase readability.</li> 155 <li>Use Android's standard font sizes: 156 <pre> 157 <TextView 158 android:id="@+id/atext" 159 android:layout_width="wrap_content" 160 android:layout_height="wrap_content" 161 android:gravity="center_vertical" 162 android:singleLine="true" 163 <strong>android:textAppearance="?android:attr/textAppearanceMedium"/></strong> 164 </pre> 165 </li> 166 <li>Ensure that all your view widgets are large enough to be clearly visible to someone 167 sitting 10 feet away from the screen (this distance is greater for very large screens). The 168 best way to do this is to use layout-relative sizing rather than absolute sizing, and 169 density-independent pixel (dip) units instead of absolute pixel units. For example, to set the 170 width of a widget, use {@code wrap_content} instead of a pixel measurement, and to set the 171 margin for a widget, use dip values instead of px values.</li> 172 </ul> 173 174 <p> 175 For more information about density-independent pixels and building layouts to handle larger 176 screen sizes, see <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple 177 Screens</a>. 178 </p> 179 180 <h2 id="density-resources">Manage Layout Resources for TV</h2> 181 182 <p>The common high-definition TV display resolutions are 720p, 1080i, and 1080p. 183 Your TV layout should target a screen size of 1920 x 1080 pixels, and then allow the Android 184 system to downscale your layout elements to 720p if necessary. In general, downscaling 185 (removing pixels) does not degrade your layout presentation quality. However, upscaling can 186 cause display artifacts that degrade the quality of your layout and have a negative impact on 187 the user experience of your app.</p> 188 189 <p> 190 To get the best scaling results for images, provide them as 191 <a href="{@docRoot}tools/help/draw9patch.html">9-patch image</a> elements if possible. If you 192 provide low quality or small images in your layouts, they will appear pixelated, fuzzy, or 193 grainy, which is not a good experience for the user. Use high-quality images instead. 194 </p> 195 196 <p> 197 For more information on optimizing layouts and resources for large screens see 198 <a href="{@docRoot}training/multiscreen/index.html">Designing for multiple screens</a>. 199 </p> 200 201 202 <h2 id="anti-patterns">Avoid Layout Anti-Patterns</h2> 203 204 <p> 205 There are a few approaches to building layouts that you should avoid because they do not work 206 well on TV devices and lead to bad user experiences. Here are some user interface approaches you 207 should specifically <em>not</em> use when developing a layout for TV. 208 </p> 209 210 <ul> 211 <li><strong>Re-using phone or tablet layouts</strong> - Do not reuse layouts from a phone or 212 tablet app without modification. Layouts built for other Android device form factors are not 213 well suited for TV devices and should be simplified for operation on a TV.</li> 214 <li><strong>ActionBar</strong> - While this user interface convention is recommended for use 215 on phones and tablets, it is not appropriate for a TV interface. In particular, using an 216 action bar options menu (or any pull-down menu for that matter) is strongly discouraged, due 217 to the difficulty in navigating such a menu with a remote control.</li> 218 <li><strong>ViewPager</strong> - Sliding between screens can work great on a phone or tablet, 219 but don't try this on a TV!</li> 220 </ul> 221 222 <p>For more information on designing layouts that are appropriate to TV, see the 223 <a href="{@docRoot}design/tv/index.html">TV Design</a> guide.</p> 224 225 226 <h2 id="large-bitmaps">Handle Large Bitmaps</h2> 227 228 <p>TV devices, like any other Android device, have a limited amount of memory. If you build your 229 app layout with very high-resolution images or use many high-resolution images in the operation 230 of your app, it can quickly run into memory limits and cause out of memory errors. 231 To avoid these types of problems, follow these tips:</p> 232 233 <ul> 234 <li>Load images only when they are displayed on the screen. For example, when displaying multiple 235 images in a {@link android.widget.GridView} or {@link android.widget.Gallery}, only load an image 236 when {@link android.widget.Adapter#getView getView()} is called on the 237 view's {@link android.widget.Adapter}. 238 </li> 239 <li>Call {@link android.graphics.Bitmap#recycle()} on {@link android.graphics.Bitmap} views that 240 are no longer needed. 241 </li> 242 <li>Use {@link java.lang.ref.WeakReference} for storing references to {@link 243 android.graphics.Bitmap} objects in an in-memory {@link java.util.Collection}. 244 </li> 245 <li>If you fetch images from the network, use {@link android.os.AsyncTask} to fetch and store 246 them on the device for faster access. Never do network transactions on the application's main 247 user interface thread. 248 </li> 249 <li>Scale down large images to a more appropriate size as you download them; otherwise, 250 downloading the image itself may cause an out of memory exception. 251 </li> 252 </ul> 253 254 <p> 255 For more information on getting the best performance when working with images, see 256 <a href="{@docRoot}training/displaying-bitmaps/index.html">Displaying Bitmaps Efficiently</a>. 257 </p> 258