docs/html/guide/developing/debugging/debugging-ui.jd

page.title=Debugging and Profiling User Interfaces
@jd:body

 <div id="qv-wrapper">
    <div id="qv">
      <h2>In this document</h2>

      <ol>
        <li>
          <a href="#hierarchyViewer">Debugging and Optimizing User Interfaces with Hierarchy
          Viewer</a>
          <ol>
            <li><a href="#layoutview">Layout View</a></li>
            <li><a href="#pixelperfect">Pixel Perfect View</a></li>
          </ol>       
        </li>

        <li><a href="#layoutopt">Optimizing Layouts with <code>layoutopt</code></a></li>
      </ol>
    </div>
  </div>

  <p>Sometimes your application's layout can slow down your application. 
  To help debug issues in your layout, the Android SDK provides the Hierarchy Viewer and 
  <code>layoutopt</code> tools.
  </p>
  
  <p>The Hierarchy Viewer application allows you to debug and optimize your user interface. It
  provides a visual representation of the layout's View hierarchy (the Layout View) and a magnified
  inspector of the display (the Pixel Perfect View).</p>

  <p><code>layoutopt</code> is a command-line tool that helps you optimize the layouts and layout
  hierarchies of your applications. You can run it against your layout files or resource
  directories to quickly check for inefficiencies or other types of problems that could be
  affecting the performance of your application.</p>

  <h2 id="hierarchyViewer">Debugging and Optimizing User Interfaces with Hierarchy Viewer</h2>

  <p>To get the Hierarchy Viewer started:</p>

  <ol>
    <li>Connect your device or launch an emulator.</li>

    <li>From a terminal, launch <code>hierarchyviewer</code> from the <code>&lt;sdk&gt;/tools/</code>
    directory.</li>

    <li>In the window that opens, you'll see a list of <strong>Devices</strong>. When a device is
    selected, a list of currently active <strong>Windows</strong> is displayed on the right. The
    <em>&lt;Focused Window&gt;</em> is the window currently in the foreground, and also the default
    window loaded if you do not select another.</li>

    <li>Select the window that you'd like to inspect and click <strong>Load View
    Hierarchy</strong>. The Layout View will be loaded. You can then load the Pixel Perfect View by
    clicking the second icon at the bottom-left of the window.</li>
  </ol>

  <p>If you've navigated to a different window on the device, press <strong>Refresh
  Windows</strong> to refresh the list of available windows on the right.</p>


  <h3 id="layoutview">Layout View</h3>

  <p>The Layout View offers a look at the View layout and properties. It has three views:</p>

  <ul>
    <li>Tree View: a hierarchy diagram of the Views, on the left.</li>

    <li>Properties View: a list of the selected View's properties, on the top-right.</li>

    <li>Wire-frame View: a wire-frame drawing of the layout, on the bottom-right.</li>
  </ul><br />
  <img src="{@docRoot}images/hierarchyviewer-layout.png"
        alt=""
        height="509"
        width="700" />
  <p class="img-caption"><strong>Figure 1.</strong> Screenshot of Hierarchy Viewer</p>

  <p>Select a node in the Tree View to display the properties of that element in the Properties
  View. When a node is selected, the Wire-frame View also indicates the bounds of the element with
  a red rectangle. Double click a node in the tree (or select it, and click <strong>Display
  View</strong>) to open a new window with a rendering of that element.</p>

  <p>The Layout View includes a couple other helpful features for debugging your layout:
  <strong>Invalidate</strong> and <strong>Request Layout</strong>. These buttons execute the
  respective View calls, {@link android.view.View#invalidate()} and {@link
  android.view.View#requestLayout()}, on the View element currently selected in the tree. Calling
  these methods on any View can be very useful when simultaneously running a debugger on your
  application.</p>

  <p>The Tree View can be resized by adjusting the zoom slider, below the diagram. The number of
  View elements in the window is also given here. You should look for ways to minimize the number
  of Views. The fewer View elements there are in a window, the faster it will perform.</p>

  <p>If you interact with the device and change the focused View, the diagram will not
  automatically refresh. You must reload the Layout View by clicking <strong>Load View
  Hierarchy</strong>.</p>

  <h3 id="pixelperfect">Pixel Perfect View</h3>

  <p>The Pixel Perfect View provides a magnified look at the current device window. It helps you
  design your UI better by giving you a closer look at your UI's image quality, alignment, and other
  aesthetic qualities. It has three views:</p>

  <ul>
    <li>Explorer View: shows the View hierarchy as a list, on the left.</li>

    <li>Normal View: a normal view of the device window, in the middle.</li>

    <li>Loupe View: a magnified, pixel-grid view of the device window, on the right.</li>
  </ul><br />
  <img src="{@docRoot}images/hierarchyviewer-pixelperfect.png"
        alt=""
        height="509"
        width="700" />

  <p>Click on an element in the Explorer View and a "layout box" will be drawn in the Normal View
  to indicate the layout position of that element. The layout box uses multiple rectangles, to
  indicate the normal bounds, the padding and the margin (as needed). The purple or green rectangle
  indicates the normal bounds of the element (the height and width). The inner white or black
  rectangle indicates the content bounds, when padding is present. A black or white rectangle
  outside the normal purple/green rectangle indicates any present margins. (There are two colors
  for each rectangle, in order to provide the best contrast based on the colors currently in the
  background.)</p>

  <p>A very handy feature for designing your UI is the ability to overlay an image in the Normal
  and Loupe Views. For example, you might have a mock-up image of how you'd like to layout your
  interface. By selecting <strong>Load...</strong> from the controls in the Normal View, you can
  choose the image from your computer and it will be placed atop the preview. Your chosen image
  will anchor at the bottom left corner of the screen. You can then adjust the opacity of the
  overlay and begin fine-tuning your layout to match the mock-up.</p>

  <p>The Normal View and Loupe View refresh at regular intervals (5 seconds by default), but the
  Explorer View does not. If you navigate away and focus on a different View, then you should
  refresh the Explorer's hierarchy by clicking <strong>Load View Hierarchy</strong>. This is even
  true when you're working in a window that holds multiple Views that are not always visible. If
  you do not, although the previews will refresh, clicking a View in the Explorer will not provide
  the proper layout box in the Normal View, because the hierarchy believes you are still focused on
  the prior View.</p>

  <p>Optional controls include:</p>

  <ul>
    <li><strong>Overlay</strong>: Load an overlay image onto the view and adjust its opacity.</li>

    <li><strong>Refresh Rate</strong>: Adjust how often the Normal and Loupe View refresh their
    display.</li>

    <li><strong>Zoom</strong>: Adjust the zoom level of the Loupe View.</li>
  </ul>

  <h2 id="layoutopt">Optimizing layouts with layoutopt</h2>
  <p>The <code>layoutopt</code> tool lets you analyze the XML files that represent your application's layout
  and finds ineffiencies in the view hierarchy.</p>
  
  <p>To run the tool, open a terminal and launch <code>layoutopt &lt;resources&gt;</code> from your
  SDK <code>tools/</code> directory. In the command, supply a list of uncompiled resource xml files
  or directories that you want to analyze.</p>

  <p>When run, the tool loads the specified XML files and analyzes their layout structures and
  hierarchies according to a set of predefined rules. If it detects issues, it outputs information
  about the issues, giving filename, line numbers, description of issue, and for some types of
  issues a suggested resolution.</p>

  <p>Here's an example of the output:</p>
  <pre>
$ layoutopt samples/
samples/compound.xml
   7:23 The root-level &lt;FrameLayout/&gt; can be replaced with &lt;merge/&gt;
   11:21 This LinearLayout layout or its FrameLayout parent is useless
samples/simple.xml
   7:7 The root-level &lt;FrameLayout/&gt; can be replaced with &lt;merge/&gt;
samples/too_deep.xml
   -1:-1 This layout has too many nested layouts: 13 levels, it should have &lt;= 10!
   20:81 This LinearLayout layout or its LinearLayout parent is useless
   24:79 This LinearLayout layout or its LinearLayout parent is useless
   28:77 This LinearLayout layout or its LinearLayout parent is useless
   32:75 This LinearLayout layout or its LinearLayout parent is useless
   36:73 This LinearLayout layout or its LinearLayout parent is useless
   40:71 This LinearLayout layout or its LinearLayout parent is useless
   44:69 This LinearLayout layout or its LinearLayout parent is useless
   48:67 This LinearLayout layout or its LinearLayout parent is useless
   52:65 This LinearLayout layout or its LinearLayout parent is useless
   56:63 This LinearLayout layout or its LinearLayout parent is useless
samples/too_many.xml
   7:413 The root-level &lt;FrameLayout/&gt; can be replaced with &lt;merge/&gt;
   -1:-1 This layout has too many views: 81 views, it should have &lt;= 80!
samples/useless.xml
   7:19 The root-level &lt;FrameLayout/&gt; can be replaced with &lt;merge/&gt;
   11:17 This LinearLayout layout or its FrameLayout parent is useless
</pre>

<p>
For more information on running the tool, see the
<a href="${@docRoot}guide/developing/debugging/debugging-ui.html#layoutopt">layoutopt</a> reference.</p>