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