1 page.title=Optimizing Your UI 2 parent.title=Debugging 3 parent.link=index.html 4 @jd:body 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 <h2>In this document</h2> 9 10 <ol> 11 <li> 12 <a href="#HierarchyViewer"> 13 Using Hierarchy Viewer 14 </a> 15 <ol> 16 <li><a href="#runhv">Running Hierarchy Viewer and choosing a window</a></li> 17 <li><a href="#viewhierarchy">About the View Hierarchy window</a></li> 18 <li><a href="#indiView">Working with an individual View in Tree View</a></li> 19 <li><a href="#hvdebugging">Debugging with View Hierarchy</a></li> 20 <li><a href="#hvoptimize">Optimizing with View Hierarchy</a></li> 21 </ol> 22 </li> 23 <li> 24 <a href="#pixelperfect"> 25 Using Pixel Perfect 26 </a> 27 <ol> 28 <li><a href="#aboutpixelperfect">About the Pixel Perfect window</a></li> 29 <li><a href="#overlays">Working with Pixel Perfect overlays</a></li> 30 </ol> 31 </li> 32 <li><a href="#lint">Using lint to optimize your UI</a></li> 33 </ol> 34 <h2>Related videos</h2> 35 <ol> 36 <li> 37 <iframe title="Hierarchyviewer" 38 width="210" height="160" 39 src="//www.youtube.com/embed/PAgE7saQUUY?rel=0&hd=1" 40 frameborder="0" allowfullscreen> 41 </iframe> 42 </li> 43 <li> 44 <iframe title="Pixel Perfect" 45 width="210" height="160" 46 src="//www.youtube.com/embed/C45bMZGdN7Y?rel=0&hd=1" 47 frameborder="0" 48 allowfullscreen> 49 </iframe> 50 </li> 51 </ol> 52 </div> 53 </div> 54 55 <p> 56 Sometimes your application's layout can slow down your application. 57 To help debug issues in your layout, the Android SDK provides the Hierarchy Viewer and 58 <code>lint</code> tools. 59 </p> 60 61 <p>The Hierarchy Viewer application allows you to debug and optimize your user interface. It 62 provides a visual representation of the layout's View hierarchy (the View Hierarchy window) 63 with performance information for each node in the layout, 64 and a magnified view of the display (the Pixel Perfect window) to closely examine the pixels 65 in your layout.</p> 66 67 <p>Android <code>lint</code> is a static code scanning tool that helps you optimize the layouts and layout 68 hierarchies of your applications, as well as detect other common coding problems. You can run it against your layout files or resource 69 directories to quickly check for inefficiencies or other types of problems that could be 70 affecting the performance of your application.</p> 71 72 <h2 id="HierarchyViewer">Using Hierarchy Viewer</h2> 73 74 <h3 id="runhv">Running Hierarchy Viewer and choosing a window</h3> 75 <p> 76 To run Hierarchy Viewer, follow these steps:</p> 77 <ol> 78 <li> 79 Connect your device or launch an emulator. 80 <p> 81 To preserve security, Hierarchy Viewer can only connect to devices running a 82 developer version of the Android system. 83 </p> 84 </li> 85 <li> 86 If you have not done so already, install the application you want to work with. 87 </li> 88 <li> 89 Run the application, and ensure that its UI is visible. 90 </li> 91 <li> 92 From a terminal, launch <code>hierarchyviewer</code> from the 93 <code><sdk>/tools/</code> 94 directory. 95 </li> 96 <li> 97 The first window you see displays a list of devices and emulators. To expand the list 98 of Activity objects for a device or emulator, click the arrow on the left. This displays a 99 list of the Activity objects whose UI is currently visible on the device or emulator. The 100 objects are listed by their Android component name. The list includes both your application 101 Activity and system Activity objects. A screenshot of this window appears in 102 figure 1. 103 </li> 104 <li> 105 Select the name of your Activity from the list. You can now look at its view 106 hierarchy using the View Hierarchy window, or look at a magnified image of the UI using 107 the Pixel Perfect window. 108 </li> 109 </ol> 110 <p> 111 To learn how to use the View Hierarchy window, go to 112 <a href="#viewhierarchy">About the View Hierarchy window</a>. To learn how to use the 113 Pixel Perfect window, go to <a href="#pixelperfect">About the Pixel Perfect window</a>. 114 </p> 115 <img id="Fig1" src="{@docRoot}images/developing/hv_device_window.png" alt="" height="600"/> 116 <p class="img-caption"><strong>Figure 1.</strong> Hierarchy Viewer device window</p> 117 <h3 id="viewhierarchy">About the View Hierarchy window</h3> 118 <p> 119 The View Hierarchy window displays the View objects that form the UI of the 120 Activity that is running on your device or emulator. You use it to look at individual 121 View objects within the context of the entire View tree. For each View object, the View 122 Hierarchy window also displays rendering performance data. 123 </p> 124 <p> 125 To see the View Hierarchy window, run Hierarchy Viewer as described in 126 the section <a href="#runhv">Running Hierarchy Viewer and choosing a window</a>. Next, click 127 <strong>View Hierarchy</strong> at the top of the device window. 128 </p> 129 <p> 130 You should see four panes: 131 </p> 132 <ul> 133 <li> 134 <strong>Tree View</strong>: The left-hand pane displays the Tree View, 135 a diagram of the Activity object's hierarchy of views. Use Tree View to examine individual 136 View objects and see the relationships between View objects in your UI. 137 <p> 138 To zoom in on the pane, use the slider at the bottom of the pane, or use your mouse 139 scroll wheel. To move around in the pane or reveal View objects that are not currently 140 visible, click and drag the pane. 141 </p> 142 <p> 143 To highlight the nodes in the tree whose class or ID match a search string, enter the 144 string in the <strong>Filter by class or id:</strong> edit box at the bottom of the 145 window. The background of nodes that match the search string will change from gray to 146 bright blue. 147 </p> 148 <p> 149 To save a screenshot of Tree View to a PNG file, click <strong>Save As PNG</strong> at 150 the top of the View Hierarchy window. This displays a dialog in which you can choose 151 a directory and file name. 152 </p> 153 <p> 154 To save a layered screenshot of your device or emulator to an Adobe Photoshop (PSD) 155 file, click <strong>Capture Layers</strong> at the top of the View Hierarchy window. 156 This displays a dialog in which you can choose a directory or file name. 157 Each View in the UI is saved as a separate Photoshop layer. 158 </p> 159 <p> 160 In Photoshop (or similar program that accepts .psd files), you can hide, show or edit a 161 layer independently of others. When you save a layered screenshot, you can examine and 162 modify the image of an individual View object. This helps you experiment with design 163 changes. 164 </p> 165 </li> 166 <li> 167 The upper right-hand pane displays the <strong>Tree Overview</strong>, a smaller map 168 representation of the entire Tree View window. Use Tree Overview to identify the part of the 169 view tree that is being displayed in Tree View. 170 <p> 171 You can also use Tree Overview to move around in the Tree View pane. Click and drag 172 the shaded rectangle over an area to reveal it in Tree View. 173 </p> 174 </li> 175 <li> 176 The middle right-hand pane displays the <strong>Properties View</strong>, 177 a list of the properties for a selected View object. With Properties View, you can 178 examine all the properties without having to look at your application source. 179 <p> 180 The properties are organized by category. To find an individual property, expand 181 a category name by clicking the arrow on its left. This reveals all the properties 182 in that category. 183 </p> 184 </li> 185 <li> 186 The lower right-hand pane displays the <strong>Layout View</strong>, 187 a block representation of the UI. Layout View is another way to navigate through your UI. 188 When you click on a View object in Tree View, its position in the UI is highlighted. 189 Conversely, when you click in an area of Layout View, the View object for that area is 190 highlighted in Tree View. 191 <p> 192 The outline colors of blocks in Layout View provide additional information: 193 </p> 194 <ul> 195 <li> 196 Bold red: The block represents the the View that is currently selected in 197 Tree View. 198 </li> 199 <li> 200 Light red: The block represents the parent of the block outlined in bold red. 201 </li> 202 <li> 203 White: The block represents a visible View that is not a parent or child of the 204 View that is currently selected in Tree View. 205 </li> 206 </ul> 207 </li> 208 </ul> 209 <p> 210 When the UI of the current Activity changes, the View Hierarchy window is not automatically 211 updated. To update it, click <strong>Load View Hierarchy</strong> at the top of the window. 212 </p> 213 <p> 214 Also, the window is not updated if you switch to a new Activity. To update it, start by 215 clicking the window selection icon in the bottom left-hand corner of the window. This 216 navigates back to the Window Selection window. From this window, click the Android 217 component name of the new Activity and then click <strong>Load View Hierarchy</strong> 218 at the top of the window. 219 </p> 220 <p> 221 A screenshot of the View Hierarchy window appears in figure 2. 222 </p> 223 <img id="Fig2" src="{@docRoot}images/developing/hv_view_hierarchy_window.png" alt="" height="600"/> 224 <p class="img-caption"><strong>Figure 2.</strong> The View Hierarchy window</p> 225 <h3 id="indiView">Working with an individual View in Tree View</h3> 226 <p> 227 Each node in Tree View represents a single View. Some information is always visible. Starting 228 at the top of the node, you see the following: 229 </p> 230 <ol> 231 <li> 232 View class: The View object's class. 233 </li> 234 <li> 235 View object address: A pointer to View object. 236 </li> 237 <li> 238 View object ID: The value of the 239 <code><a href="{@docRoot}guide/topics/resources/layout-resource.html#idvalue">android:id</a> 240 </code> attribute. 241 </li> 242 <li> 243 Performance indicators: A set of three colored dots that indicate the rendering 244 speed of this View relative to other View objects in the tree. The three dots 245 represent (from left to right) the measure, layout, and draw times of the rendering. 246 <p> 247 The colors indicate the following relative performance: 248 </p> 249 <ul> 250 <li> 251 Green: For this part of the render time, this View is in the faster 50% of all 252 the View objects in the tree. For example, a green dot for the measure time means 253 that this View has a faster measure time than 50% of the View objects in the tree. 254 </li> 255 <li> 256 Yellow: For this part of the render time, this View is in the slower 50% of all 257 the View objects in the tree. For example, a yellow dot for the layout time means 258 that this View has a slower layout time than 50% of the View objects in the tree. 259 </li> 260 <li> 261 Red: For this part of the render time, this View is the slowest one in the tree. 262 For example, a red dot for the draw time means that this View takes the most 263 time to draw of all the View objects in the tree. 264 </li> 265 </ul> 266 </li> 267 <li> 268 View index: The zero-based index of the View in its parent View. If it is the only child, 269 this is 0. 270 </li> 271 </ol> 272 <p> 273 When you select a node, additional information for the View appears in a small window above 274 the node. When you click one of the nodes, you see the following: 275 </p> 276 <ul> 277 <li> 278 Image: The actual image of the View, as it would appear in the emulator. If the View has 279 children, these are also displayed. 280 </li> 281 <li> 282 View count: The number of View objects represented by this node. This includes the View 283 itself and a count of its children. For example, this value is 4 for a View that has 3 284 children. 285 </li> 286 <li> 287 Render times: The actual measure, layout, and draw times for the View rendering, in 288 milliseconds. These represent the same values as the performance indicators mentioned in 289 the preceding section. 290 </li> 291 </ul> 292 <p> 293 An annotated screenshot of an individual node in the Tree View window appears in figure 3. 294 </p> 295 <img id="Fig3" src="{@docRoot}images/developing/hv_treeview_screenshot.png" alt="" height="600"/> 296 <p class="img-caption"><strong>Figure 3.</strong> An annotated node in Tree View</p> 297 <h3 id="hvdebugging">Debugging with View Hierarchy</h3> 298 <p> 299 The View Hierarchy window helps you debug an application by providing a static display 300 of the UI. The display starts with your application's opening screen. As you step through 301 your application, the display remains unchanged until you redraw it by invalidating and 302 then requesting layout for a View. 303 </p> 304 <p> 305 To redraw a View in the display: 306 </p> 307 <ul> 308 <li> 309 Select a View in Tree View. As you move up towards the root of the tree (to the 310 left in the Tree View), you see the highest-level View objects. Redrawing a high-level 311 object usually forces the lower-level objects to redraw as well. 312 </li> 313 <li> 314 Click <strong>Invalidate</strong> at the top of the window. This marks the View as 315 invalid, and schedules it for a redraw at the next point that a layout is requested. 316 </li> 317 <li> 318 Click <strong>Request Layout</strong> to request a layout. The View and its children 319 are redrawn, as well as any other View objects that need to be redrawn. 320 </li> 321 </ul> 322 <p> 323 Manually redrawing a View allows you to watch the View object tree and examine the properties of 324 individual View objects one step at a time as you go through breakpoints in your code. 325 </p> 326 <h3 id="hvoptimize">Optimizing with View Hierarchy</h3> 327 <p> 328 View Hierarchy also helps you identify slow render performance. You start by looking at the 329 View nodes with red or yellow performance indicators to identify the slower View objects. As you 330 step through your application, you can judge if a View is consistently slow or slow only in 331 certain circumstances. 332 </p> 333 <p> 334 Remember that slow performance is not necessarily evidence of a problem, especially for 335 ViewGroup objects. View objects that have more children and more complex View objects render 336 more slowly. 337 </p> 338 <p> 339 The View Hierarchy window also helps you find performance issues. Just by looking at the 340 performance indicators (the dots) for each View node, you can see which View objects are the 341 slowest to measure, layout, and draw. From that, you can quickly identify the problems you 342 should look at first. 343 </p> 344 <h2 id="pixelperfect">Using Pixel Perfect</h2> 345 <p> 346 Pixel Perfect is a tool for examining pixel properties and laying out UIs from a design drawing. 347 </p> 348 <h3 id="aboutpixelperfect">About the Pixel Perfect window</h3> 349 <p> 350 The Pixel Perfect window displays a magnified image of the screen that is currently 351 visible on the emulator or device. In it, you can examine the properties 352 of individual pixels in the screen image. You can also use the Pixel Perfect window 353 to help you lay out your application UI based on a bitmap design. 354 </p> 355 <p> 356 To see the Pixel Perfect window, run Hierarchy Viewer, as described in 357 the section <a href="#runhv">Running Hierarchy Viewer and choosing a window</a>. Next, click 358 <strong>Inspect Screenshot</strong> at the top of the device window. The Pixel Perfect window 359 appears. 360 </p> 361 <p> 362 In it, you see three panes: 363 </p> 364 <ul> 365 <li> 366 View Object pane: This is a hierarchical list of the View objects that are currently 367 visible on the device or emulator screen, including both the ones in your application and 368 the ones generated by the system. The objects are listed by their View class. 369 To see the class names of a View object's children, expand the View by clicking the 370 arrow to its left. When you click a View, its position is highlighted in the Pixel Perfect 371 pane on the right. 372 </li> 373 <li> 374 Pixel Perfect Loupe pane: This is the magnified screen image. It is overlaid by a grid in 375 which each square represents one pixel. To look at the information for a pixel, click in its 376 square. Its color and X,Y coordinates appear at the bottom of the pane. 377 <p> 378 The magenta crosshair in the pane corresponds to the positioning 379 crosshair in the next pane. It only moves when you move the crosshair in the next pane. 380 </p> 381 <p> 382 To zoom in or out on the image, use the <strong>Zoom</strong> slider at the bottom of 383 the pane, or use your mouse's scroll wheel. 384 </p> 385 <p> 386 When you select a pixel in the Loupe pane, you see the following information at the 387 bottom of the pane: 388 </p> 389 <ul> 390 <li> 391 Pixel swatch: A rectangle filled with the same color as the pixel. 392 </li> 393 <li> 394 HTML color code: The hexadecimal RGB code corresponding to the pixel color 395 </li> 396 <li> 397 RGB color values: A list of the (R), green (G), and blue (B) color values of the 398 pixel color. Each value is in the range 0-255. 399 </li> 400 <li> 401 X and Y coordinates: The pixel's coordinates, in device-specific pixel units. 402 The values are 0-based, with X=0 at the left of the screen and Y=0 at the top. 403 </li> 404 </ul> 405 </li> 406 <li> 407 Pixel Perfect pane: This displays the currently visible screen as it would appear in the 408 emulator. 409 <p> 410 You use the cyan crosshair to do coarse positioning. Drag the crosshair in the image, 411 and the Loupe crosshair will move accordingly. You can also click on a point in the 412 Pixel Perfect pane, and the crosshair will move to that point. 413 </p> 414 <p> 415 The image corresponding to the View object selected in the View Object pane is 416 outlined in a box that indicates the View object's position on the screen. For the 417 selected object, the box is bold red. Sibling and parent View objects have a light 418 red box. View objects that are neither parents nor siblings are in white. 419 </p> 420 <p> 421 The layout box may have other rectangles either inside or outside it, each of which 422 indicates part of the View. A purple or green rectangle indicates the View bounding box. 423 A white or black box inside the layout box represents the <strong>padding</strong>, the 424 defined distance between the View object's content and its bounding box. An outer white 425 or black rectangle represents the <strong>margins</strong>, the distance between the 426 View bounding box and adjacent View objects. The padding and margin boxes are white if 427 the layout background is black, and vice versa. 428 </p> 429 <p> 430 You can save the screen image being displayed in the Pixel Perfect pane as a PNG file. 431 This produces a screenshot of the current screen. To do this, click 432 <strong>Save as PNG</strong> at the top of the window. This displays a dialog, 433 in which you can choose a directory and filename for the file. 434 </p> 435 </li> 436 </ul> 437 <p> 438 The panes are not automatically refreshed when you change one of the View objects or go to 439 another Activity. To refresh the Pixel Perfect pane and the Loupe pane, click 440 <strong>Refresh Screenshot</strong> at the top of the window. This will change the panes 441 to reflect the current screen image. You still may need to refresh the View Object pane; 442 to do this, click <strong>Refresh Tree</strong> at the top of the window. 443 </p> 444 <p> 445 To automatically refresh the panes while you are debugging, set 446 <strong>Auto Refresh</strong> at the top of the window, and then set a refresh rate 447 with the <strong>Refresh Rate</strong> slider at the bottom of the Loupe pane. 448 </p> 449 <h3 id="overlays">Working with Pixel Perfect overlays</h3> 450 <p> 451 You often construct a UI based on a design done as a bitmap image. The Pixel Perfect window 452 helps you match up your View layout to a bitmap image by allowing you to load the bitmap as an 453 <strong>overlay</strong> on the screen image. 454 </p> 455 <p> 456 To use a bitmap image as an overlay: 457 </p> 458 <ul> 459 <li> 460 Start your application in a device or emulator and navigate to the Activity whose UI you 461 want to work with. 462 </li> 463 <li> 464 Start Hierarchy Viewer and navigate to the Pixel Perfect window. 465 </li> 466 <li> 467 At the top of the window, click <strong>Load Overlay</strong>. A dialog opens, prompting 468 for the image file to load. Load the image file. 469 </li> 470 <li> 471 Pixel Perfect displays the overlay over the screen image in the Pixel Perfect pane. The 472 lower left corner of the bitmap image (X=0, Y=<em>max value</em>) is anchored on the lower 473 leftmost pixel (X=0, Y=<em>max screen</em>) of the screen. 474 <p> 475 By default, the overlay has a 50% transparency, which allows you to see the screen 476 image underneath. You can adjust this with the <strong>Overlay:</strong> slider at the 477 bottom of the Loupe pane. 478 </p> 479 <p> 480 Also by default, the overlay is not displayed in the Loupe pane. To display it, 481 set <strong>Show in Loupe</strong> at the top of the window. 482 </p> 483 </li> 484 </ul> 485 <p> 486 The overlay is not saved as part of the screenshot when you save the screen image as a PNG 487 file. 488 </p> 489 <p> 490 A screenshot of the Pixel Perfect window appears in figure 4. 491 </p> 492 <img id="Fig4" src="{@docRoot}images/developing/hv_pixelperfect.png" 493 alt="" 494 height="600"/> 495 <p class="img-caption"><strong>Figure 4.</strong> The Pixel Perfect window</p> 496 <h2 id="lint">Using lint to Optimize Your UI</h2> 497 <p>The Android {@code lint} tool lets you analyze the XML files that define your application's UI to find inefficiencies in the view hierarchy.</p> 498 <p class="note"><strong>Note: </strong>The Android <code>layoutopt</code> tool has been replaced by the {@code lint} tool beginning in ADT and SDK Tools revision 16. The {@code lint} tool reports UI layout performance issues in a similar way as <code>layoutopt</code>, and detects additional problems.</p> 499 <p>For more information about using {@code lint}, see <a href="{@docRoot}tools/debugging/improving-w-lint.html">Improving Your Code with lint</a> and the <a href="{@docRoot}tools/help/lint.html">lint reference documentation</a>.</p> 500
