diff options
Diffstat (limited to 'docs')
18 files changed, 292 insertions, 341 deletions
diff --git a/docs/html/images/systrace/display-rhythm.png b/docs/html/images/systrace/display-rhythm.png Binary files differdeleted file mode 100644 index a249161..0000000 --- a/docs/html/images/systrace/display-rhythm.png +++ /dev/null diff --git a/docs/html/images/systrace/frame-selected-alert-tab.png b/docs/html/images/systrace/frame-selected-alert-tab.png Binary files differnew file mode 100644 index 0000000..e4b666c --- /dev/null +++ b/docs/html/images/systrace/frame-selected-alert-tab.png diff --git a/docs/html/images/systrace/frame-selected.png b/docs/html/images/systrace/frame-selected.png Binary files differnew file mode 100644 index 0000000..ee8e11f --- /dev/null +++ b/docs/html/images/systrace/frame-selected.png diff --git a/docs/html/images/systrace/frame-unselected.png b/docs/html/images/systrace/frame-unselected.png Binary files differnew file mode 100644 index 0000000..abc93d4 --- /dev/null +++ b/docs/html/images/systrace/frame-unselected.png diff --git a/docs/html/images/systrace/overview.png b/docs/html/images/systrace/overview.png Binary files differnew file mode 100644 index 0000000..bd7f549 --- /dev/null +++ b/docs/html/images/systrace/overview.png diff --git a/docs/html/images/systrace/process-rhythm.png b/docs/html/images/systrace/process-rhythm.png Binary files differdeleted file mode 100644 index 7498cc7..0000000 --- a/docs/html/images/systrace/process-rhythm.png +++ /dev/null diff --git a/docs/html/images/systrace/report.png b/docs/html/images/systrace/report.png Binary files differdeleted file mode 100644 index a642960..0000000 --- a/docs/html/images/systrace/report.png +++ /dev/null diff --git a/docs/html/preview/testing/performance.jd b/docs/html/preview/testing/performance.jd index 003b619..abb41c4 100644 --- a/docs/html/preview/testing/performance.jd +++ b/docs/html/preview/testing/performance.jd @@ -158,6 +158,15 @@ Number Slow draw: 23342 </ul> </li> + <li>INTENDED_VSYNC + <ul> + <li>The intended start point for the frame. If this value is different from VSYNC, there + was work occurring on the UI thread that prevented it from responding to the vsync signal + in a timely fashion. + </li> + </ul> + </li> + <li>VSYNC <ul> <li>The time value that was used in all the vsync listeners and drawing for the frame @@ -172,16 +181,6 @@ Number Slow draw: 23342 </ul> </li> - - <li>INTENDED_VSYNC - <ul> - <li>The intended start point for the frame. If this value is different from VSYNC, there - was work occurring on the UI thread that prevented it from responding to the vsync signal - in a timely fashion. - </li> - </ul> - </li> - <li>OLDEST_INPUT_EVENT <ul> <li>The timestamp of the oldest input event in the input queue, or Long.MAX_VALUE if diff --git a/docs/html/tools/data-binding/guide.jd b/docs/html/tools/data-binding/guide.jd index ec16c6b..7c4c15a 100644 --- a/docs/html/tools/data-binding/guide.jd +++ b/docs/html/tools/data-binding/guide.jd @@ -141,7 +141,8 @@ page.tags="databinding", "layouts" — it's a support library, so you can use it with all Android platform versions back to <strong>Android 2.1</strong> (API level 7+).</p> -<p>Android Studio <strong>1.3.0-beta1</strong> or higher is required.</p> +<p>To use data binding, Android Plugin for Gradle <strong>1.3.0-beta1</strong> +or higher is required.</p> <h4>Beta release</h4> @@ -156,7 +157,7 @@ versions back to <strong>Android 2.1</strong> (API level 7+).</p> so use it at your own risk. That said, we do want your feedback! Please let us know what is or isn’t working for you using the <a href="https://code.google.com/p/android-developer-preview/">issue - tracker</a>. + tracker</a>. </li> <li> The Data Binding library beta release is subject to significant changes, @@ -174,7 +175,7 @@ versions back to <strong>Android 2.1</strong> (API level 7+).</p> Further Android Studio support will come in the future. </li> <li> - By using the Data Binding library beta release, you acknowledge these + By using the Data Binding library beta release, you acknowledge these caveats.</li> </ul> </div> @@ -186,16 +187,13 @@ versions back to <strong>Android 2.1</strong> (API level 7+).</p> <p>To get started with Data Binding, download the library from the Support repository in the Android SDK manager. </p> -<p>Make sure you are using a compatible version of Android Studio. -The Data Binding plugin for Android Studio requires Android Studio <strong>1.3.0-beta1 -or higher</strong>.</p> -<h2 id="build_environment"> - Build Environment -</h2> - -<p>To get started with Data Binding, download the library from the Support repository in the Android SDK manager. </p> +<p>The Data Binding plugin requires Android Plugin for Gradle <strong>1.3.0-beta1 +or higher</strong>, so update your build dependencies (in +<code>build.gradle</code>) as needed.</p> -<p>Make sure you are using a <strong>compatible version of Android Studio</strong>. The Data Binding plugin for Android Studio requires <strong>Android 1.3.0-beta1 or higher</strong>.</p> +<p>Also, make sure you are using a compatible version of Android Studio. +<strong>Android Studio 1.3</strong> adds the code-completion and layout-preview +support for data binding.</p> <p> <strong>Setting Up Work Environment:</strong> @@ -203,12 +201,12 @@ or higher</strong>.</p> <p> To set up your application to use data binding, add data binding to the class - path of your build gradle file, right below "android". + path of your <code>build.gradle</code> file, right below "android". </p> <pre> dependencies { - classpath <strong>"com.android.tools.build:gradle:1.2.3" + classpath <strong>"com.android.tools.build:gradle:1.3.0-beta1" </strong>classpath <strong>"com.android.databinding:dataBinder:</strong>1.0-rc0" } } diff --git a/docs/html/tools/debugging/systrace.jd b/docs/html/tools/debugging/systrace.jd index 6472152..5d2cd89 100644 --- a/docs/html/tools/debugging/systrace.jd +++ b/docs/html/tools/debugging/systrace.jd @@ -1,4 +1,4 @@ -page.title=Analyzing Display and Performance +page.title=Analyzing UI Performance with Systrace page.tags=systrace,speed parent.title=Debugging parent.link=index.html @@ -8,22 +8,15 @@ parent.link=index.html <div id="qv"> <h2>In this document</h2> <ol> - <li><a href="#overview">Overview</a> - </li> - <li><a href="#generate">Generating Traces</a> + <li><a href="#overview">Overview</a></li> + <li><a href="#generate">Generating a Trace</a></li> + <li><a href="#analysis">Analyzing a Trace</a> <ol> - <li><a href="#limit-trace">Limiting trace data</a></li> - <li><a href="#running-4.3">Tracing on Android 4.3 and higher</a> - <li><a href="#running-4.2">Tracing on Android 4.2 and lower</a></li> + <li><a href="#frames">Inspecting Frames</a></li> + <li><a href="#alerts">Investigating Alerts</a></li> </ol> </li> <li><a href="#app-trace">Tracing Application Code</a></li> - <li><a href="#analysis">Analyzing Traces</a> - <ol> - <li><a href="#long-processes">Long running processes</a></li> - <li><a href="#display-interupts">Interruptions in display execution</a></li> - </ol> - </li> </ol> <h2>See also</h2> <ol> @@ -32,72 +25,55 @@ parent.link=index.html </div> </div> -<p>After building features, eliminating bugs, and cleaning up your code, you should spend some - time looking at the performance of your application. The speed and smoothness with which your - application draws pixels and performs operations has an significant impact on your users' - experience.</p> - -<p>Android applications operate within a shared resource environment, and the performance of - your application can be impacted by how efficiently it interacts with those resources in - the larger system. Applications also operate in a multithreaded environment, competing with other - threaded processes for resources, which can cause performance problems that are hard to diagnose. -</p> - -<p>The Systrace tool allows you to collect and review code execution data for your - application and the Android system. You can use this data to diagnose execution problems and - improve the performance of your application.</p> +<p>While developing your application, you should check that user interactions are buttery smooth, +running at a consistent 60 frames per second. If something goes wrong, and a frame gets dropped, the +first step in fixing the problem is understanding what the system is doing.</p> +<p>The Systrace tool allows you to collect and inspect timing information across an entire Android +device, which is called a <em>trace</em>. It shows where time and CPU cycles are being spent, +displaying what each thread and process is doing at any given time. It also inpects the captured +tracing information to highlight problems that it observes, from list item recycling to rendering +content, and provide recommendations about how to fix them. This document explains how to navigate +the trace files produced by the tool, and use them to analyze the performance of an application's +user interface (UI).</p> <h2 id="overview">Overview</h2> -<p>Systrace helps you analyze how the execution of your application fits into the larger - Android environment, letting you see system and applications process execution on a common - timeline. The tool allows you to generate highly detailed, interactive reports from devices - running Android 4.1 and higher, such as the report in figure 1.</p> +<p>Systrace helps you analyze how the execution of your application fits into the many running +systems on an Android device. It puts together system and application thread execution on a common +timeline. In order to analyze your app with Systrace, you first collect a trace log of your app, and +the system activity. The generated trace allows you to view highly detailed, interactive reports +showing everything happening the system for the traced duration.</p> -<img src="{@docRoot}images/systrace/report.png" alt="Systrace example report" id="figure1" /> +<img src="{@docRoot}images/systrace/overview.png" alt="Systrace example overview" id="figure1" /> <p class="img-caption"> - <strong>Figure 1.</strong> An example Systrace report on 5 seconds of process execution - for a running application and related Android system processes. + <strong>Figure 1.</strong> An example Systrace, showing 5 seconds of scrolling an app when it + is not performing well. </p> +<p>Figure 1. shows a trace captured while scrolling an app that is not rendering smoothly. By +default, a zoomed out view of the traced duration is shown. The horizontal axis is time, and trace +events are grouped by process, and then by thread on the vertical axis.</p> -<h2 id="generate">Generating Traces</h2> +<p>The groupings are in the order Kernel, SurfaceFlinger (the android compositor process), followed +by apps, each labeled by package name. Each app process contains all of the tracing signals from +each thread it contains, including a hierarchy of high level tracing events based on the enabled +tracing categories.</p> -<p>In order to create a trace of your application, you must perform a few setup steps. First, you - must have a device running Android 4.1 or higher. Set up the device for - <a href="{@docRoot}tools/device.html#setting-up">debugging</a>, connect it to your development - system, and install your application. Some types of trace information, specifically disk activity - and kernel work queues, require that you have root access to the device. However, most Systrace - log data only requires that the device be enabled for developer debugging.</p> -<p>Systrace traces can be run either from a - <a href="{@docRoot}tools/help/systrace.html#options">command line</a> or from a - <a href="{@docRoot}tools/help/systrace.html#gui">graphical user interface</a>. This guide - focuses on using the command line options.</p> +<h2 id="generate">Generating a Trace</h2> +<p>In order to create a trace of your application, you must perform a few setup steps. First, you +must have a device running Android 4.1 (API 16) or higher. Set up the device +for <a href="{@docRoot}tools/device.html#setting-up">debugging</a>, connect it to your development +system, and install your application. Some types of trace information, specifically disk activity +and kernel work queues, require that you have root access to the device. However, most Systrace log +data only requires that the device be enabled for developer debugging.</p> -<h3 id="limit-trace">Limiting trace data</h3> - -<p>The Systrace tool can generate a potentially huge amount of data from applications - and system sources. To limit the amount of data the tool collects and make the data more relevant - to your analysis, use the following options:</p> - -<ul> - <li>Limit the amount of time covered by the trace with the {@code -t, --time} option. The default - length of a trace is 5 seconds.</li> - <li>Limit the size of the data collected by the trace with the {@code -b, --buf-size} option.</li> - <li>Specify what types of processes are traced. The types of processes that can be traced depends - on the version of Android you are running: - <ul> - <li>Android 4.2 and lower devices: Use the {@code --set-tags} option and the {@code --disk}, - {@code --cpu-freq}, {@code --cpu-idle}, {@code --cpu-load} options.</li> - <li>Android 4.3 and higher devices: Use the {@code --list-categories} option to see what - categories are available on your test device.</li> - </ul> - </li> -</ul> - +<p>Systrace traces can be run either from +a <a href="{@docRoot}tools/help/systrace.html#options">command line</a> or from a +<a href="{@docRoot}tools/help/systrace.html#gui">graphical user interface</a>. This guide focuses on +using the command line options.</p> <h3 id="running-4.3">Tracing on Android 4.3 and higher</h3> @@ -116,7 +92,7 @@ $ python systrace.py --time=10 -o mynewtrace.html sched gfx view wm </ol> <p>For more information on the available options for running Systrace, see the -<a href="{@docRoot}tools/help/systrace.html#options-4.3">Systrace</a> help page.</p> +<a href="#options-4.3">Systrace</a> help page.</p> <h3 id="running-4.2">Tracing on Android 4.2 and lower</h3> @@ -127,9 +103,9 @@ $ python systrace.py --time=10 -o mynewtrace.html sched gfx view wm <ul> <li>General system processes such as graphics, audio and input processes (selected using trace - <a href="{@docRoot}tools/help/systrace.html#tags">category tags</a>).</li> + <a href="#tags">category tags</a>).</li> <li>Low level system information such as CPU, kernel and disk activity (selected using - <a href="{@docRoot}tools/help/systrace.html#options">options</a>).</li> + <a href="#options">options</a>).</li> </ul> <p>To set trace tags for Systrace using the command-line:</p> @@ -178,14 +154,85 @@ $ python systrace.py --cpu-freq --cpu-load --time=10 -o mytracefile.html </ol> <p>For more information on the available options for running Systrace, see the -<a href="{@docRoot}tools/help/systrace.html#options-pre-4.3">Systrace</a> help page.</p> +<a href="#options-pre-4.3">Systrace</a> help page.</p> + + +<h2 id="analysis">Analyzing a Trace</h2> + +<p>After you have generated a trace, open the output html file using a web browser. This section +explains how to analyze and interpret the information that the tool produces to find and fix UI +performance problems.</p> + +<h3 id="frames">Inspecting Frames</h3> + +<p>Each app that is rendering frames shows a row of frame circles, which are typically colored +green. Circles that are colored yellow or red, exceeding the 16.6 millisecond run time limit +required to maintain a stable 60 frames per second. Zoom in using the 'w' key to see the frames of +your application, and look for long-running frames getting in the way of smoothness.</p> + +<p class="note"> + <strong>Note:</strong> Hit the '?' key, or the button in the top right for help navigating the + trace. +</p> + +<img src="{@docRoot}images/systrace/frame-unselected.png" alt="Zoomed in view of a frame" id="figure2" /> +<p class="img-caption"> + <strong>Figure 2.</strong> Systrace display after zooming in on a long-running frame. +</p> + +<p>Clicking on one such frame highlights it, focusing only on the work done by the system for that +frame. On devices running Android 5.0 (API level 21) or higher, this work is split between the UI +Thread and RenderThread. On prior versions, all work in creating a frame is done on the UI +Thread.</p> + +<p>Click on individual components of the frame to see how long they took to run. Some events, such +as <em>performTraversals</em>, describe what the system is doing in that method when you select +it. Selecting a frame displays any alerts present in that frame.</p> + +<h3 id="alerts">Investigating Alerts</h3> + +<p>Systrace does automatic analysis of the events in the trace, and highlights many performance +problems as alerts, suggesting what to do next.</p> + +<img src="{@docRoot}images/systrace/frame-selected.png" alt="Problematic frame selected" id="figure3" /> +<p class="img-caption"> + <strong>Figure 3.</strong> Selecting the problematic frame, an alert is shown identifying a problem. +</p> + +<p>After you select a slow frame such as the one shown in Figure 3, an alert may be displayed. In +the case above, it calls out that the primary problem with the frame is too much work being done +inside {@link android.widget.ListView} recycling and rebinding. There are links to the relevant +events in the trace, which can be followed to explain more about what the system is doing during +this time.</p> + +<p>If you see too much work being done on the UI thread, as in this case with this +{@link android.widget.ListView} work, you can +use <a href="{@docRoot}tools/debugging/debugging-tracing.html">Traceview</a>, the app code profiling +tool, to investigate exactly what is taking so much time.</p> + +<p>Note that you can also find about every alert in the trace by clicking the <em>Alerts</em> tab to +the far right of the window. Doing so expands the Alerts panel, where you can see every alert that +the tool discovered in your trace, along with an occurrence count.</p> + +<img src="{@docRoot}images/systrace/frame-selected-alert-tab.png" alt="Alert tab shown" id="figure4" /> +<p class="img-caption"> + <strong>Figure 4.</strong> Clicking the Alert button to the right reveals the alert tab. +</p> + +<p>The Alerts panel helps you see which problems occur in the trace, and how often they contribute +to jank. Think of the alerts panel as a list of bugs to be fixed, often a tiny change or improvement +in one area can eliminate an entire class of alerts from your application!</p> <h2 id="app-trace">Tracing Application Code</h2> -<p>The Systrace tool can trace the execution of code within your application. In Android -4.3 (API level 18) and higher, you can use the methods of the {@link android.os.Trace} class to -add instrumentation to your application code and see the results in a Systrace report.</p> +<p>The tracing signals defined by the framework do not have visibility into everything your +application is doing, so you may want to add your own. In Android 4.3 (API level 18) and higher, you +can use the methods of the {@link android.os.Trace} class to add signals to your code. This +technique can help you see what work your application's threads are doing at any given time. Tracing +begin and end events do add overhead while a trace is being captured, a few microseconds each, but +sprinkling in a few per frame, or per worker thread task can go a long way to adding context to a +trace of your app.</p> <p>The following code example shows how to use the {@link android.os.Trace} class to track execution of an application method, including two nested code blocks within that method.</p> @@ -212,6 +259,8 @@ public void ProcessPeople() { } } </pre> + +<!-- todo: move these two Notes to the android.os.Trace class --> <p class="note"> <strong>Note:</strong> When you nest trace calls within each other, the {@link android.os.Trace#endSection} method ends the most recently called @@ -229,99 +278,10 @@ public void ProcessPeople() { <p>When using application-level tracing with Systrace, you must specify the package name of your application in the user interface or specify the {@code -a} or {@code --app=} options on the command line. For more information, see the -<a href="{@docRoot}tools/help/systrace.html">Systrace</a> help page.</p> - -<!-- todo: add ndk coverage --> - - -<h2 id="analysis">Analyzing Traces</h2> +<a href="{@docRoot}tools/help/systrace.html">Systrace usage guide</a>.</p> -<p>After you have generated a trace using Systrace, it lists the location of the output - file and you can open the report using a web browser. - How you use the trace data depends on the performance issues you are investigating. However, - this section provides some general instructions on how to analyze a trace.</p> - -<p>The reports generated by Systrace are interactive, allowing you to zoom into and out of - the process execution details. Use the <em>W</em> key to zoom in, the <em>S</em> - key to zoom out, the <em>A</em> key to pan left and the <em>D</em> key to pan - right. Select a task in timeline using your mouse to get more information about the task. - For more information about the using the keyboard navigation shortcuts and navigation, see the - <a href="{@docRoot}tools/help/systrace.html#viewing-options">Systrace</a> reference - documentation.</p> - -<h3 id="long-processes">Long running processes</h3> - -<p>A well-behaved application executes many small operations quickly and with a regular rhythm, - with individual operations completing within few milliseconds, depending on the device - and the processes being performed, as shown in figure 2:</p> - -<img src="{@docRoot}images/systrace/process-rhythm.png" alt="Systrace exerpt of app processing" -id="figure2" /> -<p class="img-caption"> - <strong>Figure 2.</strong> Excerpt from a trace of a smoothly running application with a regular - execution rhythm. -</p> - -<p>The trace excerpt in figure 2 shows a well-behaved application with - a regular process rhythm (1). The lower section of figure 2 shows a magnified section of - the trace indicated by the dotted outline, which reveals some irregularity in the process - execution. In particular, one of the wider task bars, indicated by (2), is taking slightly - longer (14 milliseconds) than other, similar tasks on this thread, which are averaging between - 9 and 12 milliseconds to complete. This particular task execution length is likely not noticeable - to a user, unless it impacts another process with specific timing, such as a screen update.</p> - -<p>Long running processes show up as thicker than usual execution bars in a trace. These thicker - bars can indicate a problem in your application performance. When they show up in your - trace, zoom in on the process using the - <a href="{@docRoot}tools/help/systrace.html#viewing-options">keyboard navigation</a> shortcuts to - identify the task causing the problem, and click on the task to get more information. You should - also look at other processes running at the same time, looking for a thread in one process that is - being blocked by another process.</p> - - -<h3 id="display-interupts">Interruptions in display execution</h3> - -<p>The Systrace tool is particularly useful in analyzing application display slowness, - or pauses in animations, because it shows you the execution of your application across multiple - system processes. With display execution, drawing screen frames with a regular rhythm is essential - for good performance. Having a regular rhythm for display ensures that animations and motion are - smooth on screen. If an application drops out of this rhythm, the display can become jerky or slow - from the users perspective.</p> - -<p>If you are analyzing an application for this type of problem, examine the - <strong>SurfaceFlinger</strong> process in the Systrace report where your application is - also executing to look for places where it drops out of its regular rhythm.</p> - -<img src="{@docRoot}images/systrace/display-rhythm.png" alt="Systrace exerpt of display processing" -id="figure3" /> -<p class="img-caption"> - <strong>Figure 3.</strong> Excerpt from a trace of an application showing interruptions in - display processing. -</p> - -<p>The trace excerpt in figure 3 shows an section of a trace that indicates an interruption in the - device display. The section of the <strong>SurfaceFlinger</strong> process in top excerpt, - indicated by (1), shows that display frames are being missed. These - dropped frames are potentially causing the display to stutter or halt. Zooming into this problem - area in the lower trace, shows that a memory operation (image buffer dequeuing and allocation) in - the <strong>surfaceflinger</strong> secondary thread is taking a long time (2). This delay - causes the application to miss the display update window, indicated by the dotted - line. As the developer of this application, you should investigate other threads in your - application that may also be trying to allocate memory at the same time or otherwise blocking - memory allocation with another request or task.</p> - -<p>Regular, rhythmic execution of the <strong>SurfaceFlinger</strong> process is essential to smooth - display of screen content, particularly for animations and motion. Interruptions in the regular - execution pattern of this thread is not always an indication of a display problem with your - application. Further testing is required to determine if this is actually a performance problem - from a user perspective. Being able to identify display execution patterns like the example above - can help you detect display problems and build a smooth-running, high-performance application. -</p> - -<p class="note"> - <strong>Note:</strong> When using Systrace to analyze display problems, make sure - you activate the tracing tags for <strong>Graphics</strong> and <strong>Views</strong>. -</p> +<p>You should enable app level tracing when profiling your app, even if you have not added signals +yourself. Library code can include very useful tracing signals when you enable application-level +tracing. The {@link android.support.v7.widget.RecyclerView} class is a great example of this, +providing information about several important stages of work it executes.</p> -<p>For more information on the command line options and keyboard controls for Systrace, -see the <a href="{@docRoot}tools/help/systrace.html">Systrace</a> help page.</p>
\ No newline at end of file diff --git a/docs/html/tools/help/systrace.jd b/docs/html/tools/help/systrace.jd index 4461da9..2a8e86f 100644 --- a/docs/html/tools/help/systrace.jd +++ b/docs/html/tools/help/systrace.jd @@ -13,9 +13,7 @@ parent.link=index.html <p>The Systrace tool is particularly useful in diagnosing display problems where an application is slow to draw or stutters while displaying motion or animation. For more information on how to use Systrace, see <a href="{@docRoot}tools/debugging/systrace.html">Analyzing - Display and Performance</a>.</p> - - + UI Performance with Systrace</a>.</p> <h2 id="requirements">Requirements</h2> @@ -37,7 +35,7 @@ of these methods.</p> <a href="{@docRoot}sdk/installing/studio.html">Android Studio</a>, or the Android <a href="{@docRoot}tools/help/monitor.html">Device Monitor</a>. -<p>To run the Systrace user interface:</p> +<p>To run the Systrace capture user interface:</p> <div class="toggle-content closed"> <p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)"> @@ -100,7 +98,6 @@ or the Android <a href="{@docRoot}tools/help/monitor.html">Device Monitor</a>. </div> - <h2 id="options">Command Line Usage</h2> <p>The Systrace tool has different command line options for devices running Android 4.3 (API @@ -118,9 +115,9 @@ $ python systrace.py [options] [category1] [category2] ... [categoryN] <h3 id="options-4.3">Android 4.3 and higher options</h3> -<p>When you use Systrace on devices running Android 4.3 and higher, you must specify at least one -trace category tag. Here is an example execution run that sets trace tags and generates a trace -from a connected device.</p> +<p>When you use Systrace on devices running Android 4.3 and higher, you can omit trace category tags +to get the defaults, or you may manually specify tags for inclusion. Here is an example execution +run that sets trace tags and generates a trace from a connected device.</p> <pre> $ cd <em>android-sdk</em>/platform-tools/systrace @@ -220,19 +217,10 @@ $ python systrace.py --time=10 -o mynewtrace.html sched gfx view wm <a href="{@docRoot}guide/topics/manifest/manifest-element.html#package">package names</a>. The apps must contain tracing instrumentation calls from the {@link android.os.Trace} class. For more information, see <a href="{@docRoot}tools/debugging/systrace.html#app-trace">Analyzing - Display and Performance</a>. + UI Performance with Systrace</a>. </td> </tr> - - - <tr> - <td><code>--link-assets</code></td> - - <td>Link to the original CSS or JavaScript resources instead of embedding them in the HTML - trace report.</td> - </tr> - <tr> <td><code>--from-file=<<em>FROM_FILE</em>></code></td> @@ -240,13 +228,6 @@ $ python systrace.py --time=10 -o mynewtrace.html sched gfx view wm </tr> <tr> - <td><code>--asset-dir=<<em>ASSET_DIR</em>></code></td> - - <td>Specify a directory for the trace report assets. This option is useful for maintaining a - single set of assets for multiple Systrace reports.</td> - </tr> - - <tr> <td style="white-space:nowrap"> <code>-e <<em>DEVICE_SERIAL</em>><br> --serial=<<em>DEVICE_SERIAL</em>></code></td> @@ -375,13 +356,6 @@ $ python systrace.py --disk --time=10 -o mynewtrace.html </td> </tr> - <tr> - <td><code>--link-assets</code></td> - - <td>Link to the original CSS or JS resources instead of embedding them in the HTML trace - report.</td> - </tr> - </table> <p>You can set the trace <a href="#tags">tags</a> for Systrace on @@ -455,16 +429,4 @@ trace HTML report.</p> <td>Select the previous event on the currently selected timeline.</td> </tr> - <tr> - <td><strong>Double Click</strong></td> - - <td>Zoom into the trace timeline.</td> - </tr> - - <tr> - <td><strong>Shift+Double Click</strong></td> - - <td>Zoom out of the trace timeline.</td> - </tr> - </table> diff --git a/docs/html/tools/studio/index.jd b/docs/html/tools/studio/index.jd index e7de000..0113347 100644 --- a/docs/html/tools/studio/index.jd +++ b/docs/html/tools/studio/index.jd @@ -83,11 +83,11 @@ The <em>Android</em> project view:</p> <img src="{@docRoot}images/tools/projectview01.png" /> <p class="img-caption"><strong>Figure 1.</strong> Show the Android project view.</p> <img src="{@docRoot}images/tools/studio-projectview_scripts.png" /> - <p class="img-caption"><strong>Figure 2.</strong> Show project build Files.</p> + <p class="img-caption"><strong>Figure 2.</strong> Show project build files.</p> <p>The <em>Android</em> project view shows all the build files at the top level of the project hierarchy under <strong>Gradle Scripts</strong>. Each project module appears as a folder at the -top level of the project hierarchy and contains these three elements at the top level:</p> +top level of the project hierarchy and contains these four elements at the top level:</p> <ul> <li><code>java/</code> - Source files for the module.</li> @@ -109,10 +109,10 @@ from the <strong>Project</strong> drop-down. </p> should notice that the project structure appears different than you may be used to in Eclipse. Each instance of Android Studio contains a project with one or more application modules. Each application module folder contains the complete source sets for that module, including -{@code src/main} and {@code src/androidTest} directories, resources, build +{@code src/main/} and {@code src/androidTest/} directories, resources, build file and the Android manifest. For the most part, you will need to modify the files under each -module's {@code src/main} directory for source code updates, the gradle.build file for build -specification and the files under {@code src/androidTest} directory for test case creation. +module's {@code src/main/} directory for source code updates, the gradle.build file for build +specification and the files under {@code src/androidTest/} directory for test case creation. <p> <img src="{@docRoot}images/tools/studio-project-layout.png" alt="" /></p> <p> <class="img-caption"><strong>Figure 3.</strong> View Android Studio <em>Project</em> @@ -131,7 +131,7 @@ development: </p> </ul> <p>For example, selecting the <strong>Problems</strong> view of your project displays links to the -source files containing any recognized coding and syntax errors, such as missing a XML element +source files containing any recognized coding and syntax errors, such as missing an XML element closing tag in a layout file.<p> <p>For more information, see @@ -199,7 +199,7 @@ uniquely identify application packages for publishing. The application ID is set </pre> <p class="note"><strong>Note:</strong> The <em>applicationId</em> is specified only in your -build.gradle file, and not in the AndroidManifest.xml file.</p> +{@code build.gradle} file, and not in the AndroidManifest.xml file.</p> <p>When using build variants, the build system enables you to uniquely identify different packages for each product flavors and build types. The application ID in the build type is added as @@ -643,7 +643,7 @@ When running the Android Plugin from the command line or on machines where Andro installed, set the Android Plugin for Gradle proxy settings in the Gradle build file.</p> <p>For application-specific HTTP proxy settings, set the proxy settings in the -<strong>build.gradle</strong> file as required for each application module.</p> +{@code build.gradle} file as required for each application module.</p> <pre> apply plugin: 'com.android.application' diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs index 9951330..82515d4 100644 --- a/docs/html/tools/tools_toc.cs +++ b/docs/html/tools/tools_toc.cs @@ -130,7 +130,7 @@ <li><a href="<?cs var:toroot ?>tools/debugging/debugging-ui.html"><span class="en">Optimizing your UI</span></a></li> <li><a href="<?cs var:toroot ?>tools/debugging/debugging-tracing.html"><span class="en">Profiling with Traceview and dmtracedump</span></a></li> <li><a href="<?cs var:toroot ?>tools/debugging/annotations.html"><span class="en">Improving Code Inspection with Annotations</span></a></li> - <li><a href="<?cs var:toroot ?>tools/debugging/systrace.html"><span class="en">Analyzing Display and Performance</span></a></li> + <li><a href="<?cs var:toroot ?>tools/debugging/systrace.html"><span class="en">Analyzing UI Performance</span></a></li> <li><a href="<?cs var:toroot ?>tools/debugging/debugging-memory.html">Investigating Your RAM Usage</a></li> <li><a href="<?cs var:toroot ?>tools/debugging/debugging-devtools.html"><span class="en">Using the Dev Tools App</span></a></li> </ul> diff --git a/docs/html/training/articles/keystore.jd b/docs/html/training/articles/keystore.jd index 20963f5..fca958e 100644 --- a/docs/html/training/articles/keystore.jd +++ b/docs/html/training/articles/keystore.jd @@ -197,7 +197,7 @@ of the two modes: reset (e.g. by a Device Admin).</li> <li>User authentication is required for every use of the key. In this mode, a specific operation involving a specific key is authorized by the user. Currently, the only means of such - authorization is fingerprint authentication: {@link android.hardware.fingerprint.FingerprintManager#authenticate(CryptoObject, CancellationSignal, AuthenticationCallback, int) FingerprintManager.authenticate}. + authorization is fingerprint authentication: {@link android.hardware.fingerprint.FingerprintManager#authenticate(CryptoObject, CancellationSignal, int, AuthenticationCallback, Handler) FingerprintManager.authenticate}. Such keys can only be generated or imported if at least one fingerprint is enrolled (see {@link android.hardware.fingerprint.FingerprintManager#hasEnrolledFingerprints() FingerprintManager.hasEnrolledFingerprints}). These keys become permanently invalidated once all fingerprints are unenrolled.</li> </ul> diff --git a/docs/html/training/articles/perf-tips.jd b/docs/html/training/articles/perf-tips.jd index e9df51b..4a3184c 100644 --- a/docs/html/training/articles/perf-tips.jd +++ b/docs/html/training/articles/perf-tips.jd @@ -427,7 +427,7 @@ Traceview.</p> <ul> <li><a href="{@docRoot}tools/debugging/debugging-tracing.html">Profiling with Traceview and dmtracedump</a></li> - <li><a href="{@docRoot}tools/debugging/systrace.html">Analysing Display and Performance + <li><a href="{@docRoot}tools/debugging/systrace.html">Analyzing UI Performance with Systrace</a></li> </ul> diff --git a/docs/html/training/wearables/apps/always-on.jd b/docs/html/training/wearables/apps/always-on.jd index 5bb6064..d384974 100644 --- a/docs/html/training/wearables/apps/always-on.jd +++ b/docs/html/training/wearables/apps/always-on.jd @@ -30,6 +30,11 @@ list as they shop at the market. Making an app constantly visible has an impact so you should carefully consider that impact when adding this feature to your app. </p> +<div class="video-wrapper-left"> +<iframe src="https://www.youtube.com/embed/7m6Z9d0fDaM" frameborder="0" +allowfullscreen></iframe> +</div> + <p>Android Wear devices running Android version 5.1 or higher allow apps to remain in the foreground while saving battery power. Android Wear apps can control what’s displayed on the wearable device screen while the device is in a low-power ambient mode. Wear apps that run in both diff --git a/docs/html/training/wearables/watch-faces/drawing.jd b/docs/html/training/wearables/watch-faces/drawing.jd index 60da5d5..8b6de76 100644 --- a/docs/html/training/wearables/watch-faces/drawing.jd +++ b/docs/html/training/wearables/watch-faces/drawing.jd @@ -16,17 +16,20 @@ page.title=Drawing Watch Faces <ul> <li><a href="{@docRoot}design/wear/watchfaces.html">Watch Faces for Android Wear</a></li> </ul> +<h2>Related Samples</h2> + <ul> + <li><a href="{@docRoot}samples/WatchFace/index.html">WatchFace</a></li> + </ul> </div> </div> <p>After you have configured your project and added a class that implements the watch face service, you can start writing code to initialize and draw your custom watch face.</p> -<p>This lesson explains how the system invokes the methods in the -watch face service using examples from the <em>WatchFace</em> sample -included in the Android SDK. This sample is located in the -<code>android-sdk/samples/android-21/wearable/WatchFace</code> directory. Many aspects of the -service implementations described here (such as initialization and detecting device features) +<p>This lesson includes examples from the +<a href="{@docRoot}samples/WatchFace/index.html">WatchFace</a> sample to show how the system uses +the watch face service. Many aspects of the +service implementations described here (such as initialization and device features detection) apply to any watch face, so you can reuse some of the code in your own watch faces.</p> @@ -36,7 +39,8 @@ apply to any watch face, so you can reuse some of the code in your own watch fac width="180" height="180" alt="" style="margin-left:25px;margin-top:12px"/> <p class="img-caption"> <strong>Figure 1.</strong> The analog and digital watch faces in -the <em>WatchFace</em> sample.</p> +the +<a href="{@docRoot}samples/WatchFace/index.html">WatchFace</a> sample.</p> <h2 id="Initialize">Initialize Your Watch Face</h2> @@ -51,8 +55,12 @@ of your watch face and makes it easier to maintain your code.</p> <ol> <li>Declare variables for a custom timer, graphic objects, and other elements.</li> -<li>Initialize the watch face elements in the <code>Engine.onCreate()</code> method.</li> -<li>Initialize the custom timer in the <code>Engine.onVisibilityChanged()</code> method.</li> +<li>Initialize the watch face elements in the +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html#onCreate(android.view.SurfaceHolder)"><code>Engine.onCreate()</code></a> +method.</li> +<li>Initialize the custom timer in the +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html#onVisibilityChanged(boolean)"><code>Engine.onVisibilityChanged()</code></a> +method.</li> </ol> <p>The following sections describe these steps in detail.</p> @@ -61,7 +69,8 @@ of your watch face and makes it easier to maintain your code.</p> <p>The resources that you intialize when the system loads your service need to be accessible at different points throughout your implementation, so you can reuse them. You achieve this -by declaring member variables for these resources in your <code>WatchFaceService.Engine</code> +by declaring member variables for these resources in your +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html"><code>WatchFaceService.Engine</code></a> implementation.</p> <p>Declare variables for the following elements:</p> @@ -83,31 +92,25 @@ Your service implementation must register a broadcast receiver that is notified zone changes and update the time accordingly.</dd> </dl> -<p>The <code>AnalogWatchFaceService.Engine</code> class in the <em>WatchFace</em> sample defines -these variables as shown in the snippet below. The custom timer is implemented as a -{@link android.os.Handler} instance that sends and processes delayed messages using the thread's -message queue. For this particular watch face, the custom timer ticks once every second. When the -timer ticks, the handler calls the <code>invalidate()</code> method and the system then calls -the <code>onDraw()</code> method to redraw the watch face.</p> +<p>The following snippet shows how to define these variables:</p> <pre> private class Engine extends CanvasWatchFaceService.Engine { static final int MSG_UPDATE_TIME = 0; - /* a time object */ - Time mTime; + Calendar mCalendar; - /* device features */ + // device features boolean mLowBitAmbient; - /* graphic objects */ + // graphic objects Bitmap mBackgroundBitmap; Bitmap mBackgroundScaledBitmap; Paint mHourPaint; Paint mMinutePaint; ... - /* handler to update the time once a second in interactive mode */ + // handler to update the time once a second in interactive mode final Handler mUpdateTimeHandler = new Handler() { @Override public void handleMessage(Message message) { @@ -126,53 +129,63 @@ private class Engine extends CanvasWatchFaceService.Engine { } }; - /* receiver to update the time zone */ + // receiver to update the time zone final BroadcastReceiver mTimeZoneReceiver = new BroadcastReceiver() { @Override public void onReceive(Context context, Intent intent) { - mTime.clear(intent.getStringExtra("time-zone")); - mTime.setToNow(); + mCalendar.setTimeZone(TimeZone.getDefault()); + invalidate(); } }; - /* service methods (see other sections) */ + // service methods (see other sections) ... } </pre> +<p>In the example above, the custom timer is implemented as a +{@link android.os.Handler} instance that sends and processes delayed messages using the thread's +message queue. For this particular watch face, the custom timer ticks once every second. When the +timer ticks, the handler calls the +<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#invalidate()"><code>invalidate()</code></a> +method and the system then calls the +<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#onDraw(android.graphics.Canvas, android.graphics.Rect)"<code>onDraw()</code></a> +method to redraw the watch face.</p> + <h3 id="InitializeElements">Initialize watch face elements</h3> -<p>After you have declared member variables for bitmap resources, paint styles, and other -elements that you reuse every time your redraw your watch face, initialize them when the system +<p>After declaring member variables for bitmap resources, paint styles, and other +elements that you reuse every time you redraw your watch face, initialize them when the system loads your service. Initializing these elements only once and reusing them improves performance and battery life.</p> -<p>In the <code>Engine.onCreate()</code> method, initialize the following elements:</p> +<p>In the +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html#onCreate(android.view.SurfaceHolder)"><code>Engine.onCreate()</code></a> +method, initialize the following elements:</p> <ul> <li>Load the background image.</li> <li>Create styles and colors to draw graphic objects.</li> -<li>Allocate an object to hold the time.</li> +<li>Allocate an object to calculate the time.</li> <li>Configure the system UI.</li> </ul> -<p>The <code>Engine.onCreate()</code> method in the <code>AnalogWatchFaceService</code> class -initializes these elements as follows:</p> +<p>The following snippet shows how to initialize these elements:</p> <pre> @Override public void onCreate(SurfaceHolder holder) { super.onCreate(holder); - /* configure the system UI (see next section) */ + // configure the system UI (see next section) ... - /* load the background image */ + // load the background image Resources resources = AnalogWatchFaceService.this.getResources(); - Drawable backgroundDrawable = resources.getDrawable(R.drawable.bg); + Drawable backgroundDrawable = resources.getDrawable(R.drawable.bg, null); mBackgroundBitmap = ((BitmapDrawable) backgroundDrawable).getBitmap(); - /* create graphic styles */ + // create graphic styles mHourPaint = new Paint(); mHourPaint.setARGB(255, 200, 200, 200); mHourPaint.setStrokeWidth(5.0f); @@ -180,15 +193,16 @@ public void onCreate(SurfaceHolder holder) { mHourPaint.setStrokeCap(Paint.Cap.ROUND); ... - /* allocate an object to hold the time */ - mTime = new Time(); + // allocate a Calendar to calculate local time using the UTC time and time zone + mCalendar = Calendar.getInstance(); } </pre> <p>The background bitmap is loaded only once when the system initializes the watch face. The -graphic styles are instances of the {@link android.graphics.Paint} class. You later use these -styles to draw the elements of your watch face inside the <code>Engine.onDraw()</code> method, -as described in <a href="#Drawing">Drawing Your Watch Face</a>.</p> +graphic styles are instances of the {@link android.graphics.Paint} class. Use these +styles to draw the elements of your watch face inside the +<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#onDraw(android.graphics.Canvas, android.graphics.Rect)"><code>Engine.onDraw()</code></a> +method, as described in <a href="#Drawing">Drawing Your Watch Face</a>.</p> <h3 id="Timer">Initialize the custom timer</h3> @@ -203,8 +217,8 @@ face in ambient mode</a>.</p> <p>An example timer definition from the <code>AnalogWatchFaceService</code> class that ticks once every second is shown in <a href="#Variables">Declare variables</a>. In the -<code>Engine.onVisibilityChanged()</code> method, start the custom timer if these two -conditions apply:</p> +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html#onVisibilityChanged(boolean)"><code>Engine.onVisibilityChanged()</code></a> +method, start the custom timer if these two conditions apply:</p> <ul> <li>The watch face is visible.</li> @@ -230,8 +244,10 @@ private boolean shouldTimerBeRunning() { <p>This custom timer ticks once every second, as described in <a href="#Variables">Declare variables</a>.</p> -<p>In the <code>Engine.onVisibilityChanged()</code> method, start the timer if required and -and register the receiver for time zone changes as follows:</p> +<p>In the +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html#onVisibilityChanged(boolean)"><code>onVisibilityChanged()</code></a> +method, start the timer if required and register the receiver for time zone changes as follows: +</p> <pre> @Override @@ -242,23 +258,24 @@ public void onVisibilityChanged(boolean visible) { registerReceiver(); // Update time zone in case it changed while we weren't visible. - mTime.clear(TimeZone.getDefault().getID()); - mTime.setToNow(); + mCalendar.setTimeZone(TimeZone.getDefault()); } else { unregisterReceiver(); } // Whether the timer should be running depends on whether we're visible and - // whether we're in ambient mode), so we may need to start or stop the timer + // whether we're in ambient mode, so we may need to start or stop the timer updateTimer(); } </pre> -<p>When the watch face is visible, the <code>onVisibilityChanged()</code> method registers -the receiver for time zone changes and starts the custom timer if the device is in interactive -mode. When the watch face is not visible, this method stops the custom timer and unregisters -the receiver for time zone changes. The <code>registerReceiver()</code> and -<code>unregisterReceiver()</code> methods are implemented as follows:</p> +<p>When the watch face is visible, the +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html#onVisibilityChanged(boolean)"><code>onVisibilityChanged()</code></a> +method registers the receiver for time zone changes. If the device is in interactive mode, this +method also starts the custom timer. When the watch face is not visible, this +method stops the custom timer and unregisters the receiver for time zone changes. +The <code>registerReceiver()</code> and <code>unregisterReceiver()</code> methods are implemented as +follows:</p> <pre> private void registerReceiver() { @@ -283,13 +300,16 @@ private void unregisterReceiver() { <h3 id="TimeTick">Update the watch face in ambient mode</h3> -<p>In ambient mode, the system calls the <code>Engine.onTimeTick()</code> method every minute. -It is usually sufficient to update your watch face once per minute in this mode. To update your -watch face while in interactive mode, you must provide a custom timer as described in -<a href="#Timer">Initialize the custom timer</a>.</p> +<p>In ambient mode, the system calls the +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html#onTimeTick()"><code>Engine.onTimeTick()</code></a> +method every minute. It is usually sufficient to update your watch face once per minute in this +mode. To update your watch face while in interactive mode, you must provide a custom timer as +described in <a href="#Timer">Initialize the custom timer</a>.</p> <p>In ambient mode, most watch face implementations simply invalidate the canvas to redraw the watch -face in the <code>Engine.onTimeTick()</code> method:</p> +face in the +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html#onTimeTick()"<code>Engine.onTimeTick()</code></a> +method:</p> <pre> @Override @@ -320,8 +340,11 @@ face is active:</p> <li>Specify the positioning of the system indicators.</li> </ul> -<p>To configure these aspects of the system UI, create a <code>WatchFaceStyle</code> instance -and pass it to the <code>Engine.setWatchFaceStyle()</code> method.</p> +<p>To configure these aspects of the system UI, create a +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceStyle.html"><code>WatchFaceStyle</code></a> +instance and pass it to the +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html#setWatchFaceStyle(android.support.wearable.watchface.WatchFaceStyle)"><code>Engine.setWatchFaceStyle()</code></a> +method.</p> <p>The <code>AnalogWatchFaceService</code> class configures the system UI as follows:</p> @@ -330,7 +353,7 @@ and pass it to the <code>Engine.setWatchFaceStyle()</code> method.</p> public void onCreate(SurfaceHolder holder) { super.onCreate(holder); - /* configure the system UI */ + // configure the system UI setWatchFaceStyle(new WatchFaceStyle.Builder(AnalogWatchFaceService.this) .setCardPeekMode(WatchFaceStyle.PEEK_MODE_SHORT) .setBackgroundVisibility(WatchFaceStyle @@ -350,16 +373,16 @@ For example, if the user selects a white background, you can add background prot system indicators.</p> <p>For more details about configuring the system UI, see the -<a href="{@docRoot}shareables/training/wearable-support-docs.zip">API reference</a> for the -<code>WatchFaceStyle</code> class.</p> - +<a href="{@docRoot}reference/packages-wearable-support.html">Wear API reference documentation</a>. +</p> <h2 id="Screen">Obtain Information About the Device Screen</h2> -<p>The system calls the <code>Engine.onPropertiesChanged()</code> method when it determines -the properties of the device screen, such as whether the device uses low-bit ambient mode and -whether the screen requires burn-in protection.</p> +<p>The system calls the +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html#onPropertiesChanged(android.os.Bundle)"><code>Engine.onPropertiesChanged()</code></a> +method when it determines the properties of the device screen, such as whether the device uses +low-bit ambient mode and whether the screen requires burn-in protection.</p> <p>The following code snippet shows how to obtain these properties:</p> @@ -394,12 +417,13 @@ Filtering</a>.</p> <h2 id="Modes">Respond to Changes Between Modes</h2> <p>When the device switches between ambient and interactive modes, the system calls the -<code>Engine.onAmbientModeChanged()</code> method. Your service implementation should make -any necessary adjustments to switch between modes and then call the <code>invalidate()</code> +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html#onAmbientModeChanged(boolean)"><code>Engine.onAmbientModeChanged()</code></a> +method. Your service implementation should make any necessary adjustments to switch between modes +and then call the +<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#invalidate()"><code>invalidate()</code></a> method for the system to redraw the watch face.</p> -<p>The following snippet shows how this method is implemented in the -<code>AnalogWatchFaceService</code> class inside the <em>WatchFace</em> sample:</p> +<p>The following snippet shows how to implement this method:</p> <pre> @Override @@ -426,28 +450,34 @@ system can redraw the watch face.</p> <h2 id="Drawing">Draw Your Watch Face</h2> -<p>To draw a custom watch face, the system calls the <code>Engine.onDraw()</code> method with a -{@link android.graphics.Canvas} instance and the bounds in which you should draw your watch face. -The bounds account for any inset areas, such as the "chin" on the bottom of some round devices. -You can use this canvas to draw your watch face directly as follows:</p> +<p>To draw a custom watch face, the system calls the +<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#onDraw(android.graphics.Canvas, android.graphics.Rect)"><code>Engine.onDraw()</code></a> +method with a {@link android.graphics.Canvas} instance and the bounds in which you should draw your +watch face. The bounds take into account any inset areas, such as the "chin" on the bottom of some +round devices. You can use this canvas to draw your watch face directly as follows:</p> <ol> -<li>If this is the first invocation of the <code>onDraw()</code> method, scale your background -to fit.</li> +<li>If this is the first invocation of the +<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#onDraw(android.graphics.Canvas, android.graphics.Rect)"><code>onDraw()</code></a> +method, scale your background to fit.</li> <li>Check whether the device is in ambient mode or interactive mode.</li> <li>Perform any required graphic computations.</li> <li>Draw your background bitmap on the canvas.</li> <li>Use the methods in the {@link android.graphics.Canvas} class to draw your watch face.</li> </ol> -<p>The <code>AnalogWatchFaceService</code> class in the <em>WatchFace</em> sample follows these -steps to implement the <code>onDraw()</code> method as follows:</p> +<p>The following snippet shows how to implement the +<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#onDraw(android.graphics.Canvas, android.graphics.Rect)"><code>onDraw()</code></a> +method:</p> <pre> @Override public void onDraw(Canvas canvas, Rect bounds) { // Update the time - mTime.setToNow(); + mCalendar.setTimeInMillis(System.currentTimeMillis()); + + // Constant to help calculate clock hand rotations + final float TWO_PI = (float) Math.PI * 2f; int width = bounds.width(); int height = bounds.height(); @@ -457,7 +487,7 @@ public void onDraw(Canvas canvas, Rect bounds) { || mBackgroundScaledBitmap.getWidth() != width || mBackgroundScaledBitmap.getHeight() != height) { mBackgroundScaledBitmap = Bitmap.createScaledBitmap(mBackgroundBitmap, - width, height, true /* filter */); + width, height, true); } canvas.drawBitmap(mBackgroundScaledBitmap, 0, 0, null); @@ -468,10 +498,13 @@ public void onDraw(Canvas canvas, Rect bounds) { float centerY = height / 2f; // Compute rotations and lengths for the clock hands. - float secRot = mTime.second / 30f * (float) Math.PI; - int minutes = mTime.minute; - float minRot = minutes / 30f * (float) Math.PI; - float hrRot = ((mTime.hour + (minutes / 60f)) / 6f ) * (float) Math.PI; + float seconds = mCalendar.get(Calendar.SECOND) + + mCalendar.get(Calendar.MILLISECOND) / 1000f; + float secRot = seconds / 60f * TWO_PI; + float minutes = mCalendar.get(Calendar.MINUTE) + seconds / 60f; + float minRot = minutes / 60f * TWO_PI; + float hours = mCalendar.get(Calendar.HOUR) + minutes / 60f; + float hrRot = hours / 12f * TWO_PI; float secLength = centerX - 20; float minLength = centerX - 40; @@ -499,11 +532,13 @@ public void onDraw(Canvas canvas, Rect bounds) { <p>This method computes the required positions for the clock hands based on the current time and draws them on top of the background bitmap using the graphic styles initialized in the -<code>onCreate()</code> method. The second hand is only drawn in interactive mode, not in -ambient mode.</p> +<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html#onCreate(android.view.SurfaceHolder)"><code>onCreate()</code></a> +method. The second hand is only drawn in interactive mode, not in ambient mode.</p> <p>For more information about drawing on a Canvas instance, see <a href="{@docRoot}guide/topics/graphics/2d-graphics.html">Canvas and Drawables</a>.</p> -<p>The <em>WatchFace</em> sample in the Android SDK includes additional watch faces that you -can refer to as examples of how to implement the <code>onDraw()</code> method.</p> +<p>The <a href="{@docRoot}samples/WatchFace/index.html">WatchFace</a> sample includes additional +watch faces that you can refer to as examples of how to implement the +<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#onDraw(android.graphics.Canvas, android.graphics.Rect)"><code>onDraw()</code></a> +method.</p> diff --git a/docs/html/tv/adt-1/index.jd b/docs/html/tv/adt-1/index.jd index 82760ed..4f62796 100644 --- a/docs/html/tv/adt-1/index.jd +++ b/docs/html/tv/adt-1/index.jd @@ -274,14 +274,6 @@ $ adb connect <ip-address-for-adt-1>:4321 starts the multi-color cycle, release the small, round button, and ADT-1 boots up. If you release the button while the LED is flashing red, the device will be in Fastboot mode.</p> -<p> - <strong>There is a hardware problem with my ADT-1. How do I return it?</strong> -</p> -<p>You can request a return of the device using the - <a href="https://support.google.com/googleplay/android-developer/contact/adt_rma">return - merchandise authorization form</a>. -</p> - <h2 id="emote">Android TV Remote Control App</h2> |
