docs/html/design/building-blocks/progress.jd

page.title=Progress & Activity
page.tags=progressbar,download,network
@jd:body

<p>Progress bars and activity indicators signal to users that something is happening that will take a moment.</p>
<h2 id="progress">Progress bars</h2>

<p>Progress bars are for situations where the percentage completed can be determined. They give users a quick sense of how much longer an operation will take.</p>

<img src="{@docRoot}design/media/progress_download.png">

<p>A progress bar should always fill from 0% to 100% and never move backwards to a lower value. If multiple operations are happening in sequence, use the progress bar to represent the delay as a whole, so that when the bar reaches 100%, it doesn't return back to 0%.</p>

<div class="vspace size-2">&nbsp;</div>

<img src="{@docRoot}design/media/progress_themes.png">
<div class="figure-caption">
  Progress bar in Holo Dark and Holo Light.
</div>

<h2 id="activity">Activity indicators</h2>

<p>Activity indicators are for operations of an indeterminate length. They ask users to wait a moment while something finishes up, without getting into specifics about what's happening behind the scenes.</p>

<p>Two styles are available: a bar and a circle. Each is offered in a variety of sizes, in both Holo Light and Holo Dark themes. Choose the appropriate style and size for the surrounding context. For example, the largest activity circle works well when displayed in a blank content area, but not in a smaller dialog box. Each operation should only be represented by one activity indicator.</p>

<div class="layout-content-row">
  <div class="layout-content-col span-6">

    <img src="{@docRoot}design/media/progress_activity.png">

  </div>
  <div class="layout-content-col span-7 with-callouts">

    <ol>
      <li class="value-1"><h4>Activity bar</h4>
        <p>In this example, an activity bar (in Holo Dark) appears when a user first requests a download. There's an unknown period of time when the download has not yet started. As soon as the download starts, this activity bar transforms into a progress bar.</p>
      </li>
    </ol>

  </div>
</div>

<div class="layout-content-row">
  <div class="layout-content-col span-6">

    <img src="{@docRoot}design/media/progress_activity2.png">

  </div>
  <div class="layout-content-col span-7 with-callouts">

    <ol>
      <li class="value-2"><h4>Activity circle</h4>
        <p>In this example, an activity circle (in Holo Light) is used in the Gmail application when a message is being loaded because it's not possible to determine how long it will take to download the email.</p>
        <p>When displaying an activity circle, do not include text to communicate what the app is doing. The moving circle alone provides sufficient feedback about the delay, and does so in an understated way that minimizes the impact.</p>
        <p>
        <div style="margin-left:0;margin-top:1em;">
          <img src="{@docRoot}design/media/progress_activity_do_dont.png">
        </div>
        </p>
      </li>
    </ol>

  </div>
</div>

<h2 id="custom-indicators">Custom indicators</h2>
<p>The standard progress bar and activity indicators work well for most situations and should be used whenever possible to provide a consistent experience across Android. However, some situations may call for something more custom.</p>

<p>Here's an example:<br>
In all of the Google Play apps (Music, Books, Movies, Magazines), we wanted the current download state of each item to be visible at all times at the top-level screen. These states are:
  <ul>
    <li>Not downloaded</li>
    <li>Temporarily downloaded (automatically cached by the app)</li>
    <li>Permanently downloaded on the device at the user's request</li>
  </ul>
</p>
<p>We also needed to indicate progress from one download state to another, because downloading is not instantaneous.</p>
<p>This presented a challenge, because the Google Play apps use a variety of different layouts, and some of them are highly space-constrained. We didn't want this information to clutter the top-level screens, or compete too much with the cover art.</p>
<p>So we designed a custom indicator that could show all of the information in a tiny footprint, with the flexibility to appear on top of content if necessary.</p>

<img src="{@docRoot}design/media/progress_activity_custom.png">

<p>The color indicates whether it's downloaded (blue) or not (gray). The appearance of the pin indicates whether the download is permanent (white, upright) or temporary (gray, diagonal). And when state is in the process of changing, progress is indicated by a moving pie chart.</p>

<div class="layout-content-row">
  <div class="layout-content-col span-9">
    <img src="{@docRoot}design/media/progress_activity_custom_app.png">
  </div>
  <div class="layout-content-col span-4">
    <div class="figure-caption">
      Across Google Play apps with different layouts, the same custom indicator appears with each item. It communicates download state as well as progress, in a compact package that can be incorporated into any screen design.
    </div>
  </div>
</div>

<p>If you find that the standard indicators aren't meeting your needs (due to space constraints, state complexities), by all means design your own. Make it feel like part of the Android family by injecting some of the visual characteristics of the standard indicators. In this example, we carried over the circular shape, the same shade of blue, and the flat and simple style.</p>