diff options
Diffstat (limited to 'docs/html/guide/developing/debugging/debugging-ui.jd')
| -rw-r--r-- | docs/html/guide/developing/debugging/debugging-ui.jd | 202 |
1 files changed, 202 insertions, 0 deletions
diff --git a/docs/html/guide/developing/debugging/debugging-ui.jd b/docs/html/guide/developing/debugging/debugging-ui.jd new file mode 100644 index 0000000..9b02d34 --- /dev/null +++ b/docs/html/guide/developing/debugging/debugging-ui.jd @@ -0,0 +1,202 @@ +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><sdk>/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><Focused Window></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 <resources></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 <FrameLayout/> can be replaced with <merge/> + 11:21 This LinearLayout layout or its FrameLayout parent is useless +samples/simple.xml + 7:7 The root-level <FrameLayout/> can be replaced with <merge/> +samples/too_deep.xml + -1:-1 This layout has too many nested layouts: 13 levels, it should have <= 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 <FrameLayout/> can be replaced with <merge/> + -1:-1 This layout has too many views: 81 views, it should have <= 80! +samples/useless.xml + 7:19 The root-level <FrameLayout/> can be replaced with <merge/> + 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> + + + + + + + + |