xmlns:uix="http://projectmallard.org/experimental/ui/"

      type="topic"

      id="progress-bars">

  <info>

    <credit type="author">

      <name>Allan Day</name>

      <email>aday@gnome.org</email>

    </credit>

    <credit>

      <name>Calum Benson</name>

    </credit>

    <credit>

      <name>Adam Elman</name>

    </credit>

    <credit>

      <name>Seth Nickell</name>

    </credit>

    <credit>

      <name>Colin Robertson</name>

    </credit>

    <link type="guide" xref="ui-elements"/>

    <uix:thumb mime="image/svg" src="figures/ui-elements/progress-bars.svg"/>

    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>

  </info>

<title>Progress bars</title>

Progress bars indicate that a task is being carried out, along with how much progress has been made through the task.

<media type="image" mime="image/svg" src="figures/ui-elements/progress-bars.svg"/>

<section id="when-to-use">

<title>When to use</title>

It is usually necessary to indicate that progress is taking place whenever an operation takes more than around three seconds. This ensures that users understand that they have to wait, and that an error has not occurred.

When indicating progress, the primary choice is between a progress bar or a <link xref="progress-spinners">progress spinner</link>. Progress bars indicate how much of a task has been completed. They are therefore useful for tasks that take a long time. As a rule of thumb, only use a progress bar for tasks that take over 30 seconds. For tasks that have shorter periods, <link xref="progress-spinners">progress spinners</link> are often a better choice.

</section>

<section id="types">

<title>Types</title>

There are three types of progress bar:

<list>

<item>
Time-remaining: these indicate how much time remains in an operation.
</item>

<item>
Typical-time: these indicate how much time remains, based on an estimate of the expected duration.
</item>

<item>
Indeterminate: these only indicate that an operation is ongoing, not how long it will take.
</item>

</list>

Accuracy is preferable for progress bars. Where possible, use a time-remaining progress bar, followed by typical-time. Try to avoid using indeterminate progress bars.

</section>

<section id="progress-text">

<title>Progress text</title>

Each progress bar can include a text description. This text should provide an idea of how much of the task has been completed. When deciding on progress text:

<list>

<item>
Always consider what is most relevant and interesting for the user.
</item>

<item>
It is often better to provide specific information rather than a unitless percentage. For example, <gui>13 of 19 images rotated</gui> or <gui>12.1 of 30 MB downloaded</gui> rather than <gui>13% complete</gui>.
</item>

<item>
For long-running tasks, it can be desirable to show an estimate of the time remaining in the progress bar text. If other relevant information isn't available, this can be shown on its own. Alternatively, it can appear alongside text about task progress; however, be careful not to overwhelm the user with too much information when doing this, and use <link xref="typography">typographic conventions</link> to differentiate the most useful information.
</item>

<item>
If the time remaining is an estimate, use the word <gui>about</gui>. For example: <gui>About 3 minutes left</gui>.
</item>

</list>

</section>

<section id="task-stages">

<title>Task stages</title>

Some tasks can be made up of a sequential series of stages, each of which have different options for time estimation. It might be possible to estimate the time remaining for part of a task, but not another part, for example. In these situations:

<list>

<item>
Only communicate the different stages in a task when they are relevant to a user. Generally speaking, this will not be required, and it is not necessary or desirable to communicate separate stages in a task.
</item>

<item>
If a task includes time-remaining and typical-time stages, try to create a single composite typical-time progress bar.
</item>

<item>
If a task includes an indeterminate progress stage, the progress bar can show indeterminate progress for part of the task. However, you should avoid showing indeterminate progress bars for long periods of time, and should attempt to keep the number of progress bar mode changes to an absolute minimum. Avoid indeterminate progress wherever possible.
</item>

</list>

</section>

<section id="sub-tasks">

<title>Sub-tasks</title>

If a task is comprised of multiple sub-tasks (such as downloading several files simultaneously), it is generally advisable to show a single progress bar which indicates composite progress for the overall task. However, there are some situations where this might not be the case:

<list>

<item>
If it is genuinely useful for the user to know progress within each individual sub-task. (As an alternative, completion of each sub-task can be indicated with progress text.)
</item>

<item>
If it might be necessary to pause or stop a sub-task (see the <link xref="#general-guidelines">general guidelines</link> on this, below).
</item>

<item>
If sub-tasks are already indicated in your application's user interface. In this case, it can be less disruptive to show a progress for each item inline.
</item>

</list>

When showing progress bars for sub-tasks:

<list>

<item>
Each sub-task should conform to the usage guidelines for progress bars (see <link xref="#when-to-use">when to use</link>, above).
</item>

<item>
Generally speaking, it is not necessary to show a progress bar for overall progress through the set of tasks.
</item>

</list>

</section>

<section id="progress-windows">

<title>Progress windows</title>

In the past, progress windows were a popular way to present progress bars. These secondary windows would appear for the duration of a task, and would contain one or more progress bars. In general, progress windows are not recommended, since the consequence of closing the window can be unclear and they can obscure useful controls and content.

Where possible, progress bars should be displayed inline, and should have a close visual relationship with the content items or controls which represent the ongoing task.

</section>

<section id="general-guidelines">

<title>General guidelines</title>

<list>

<item>
If the operation in progress is potentially destructive or resource intensive, consider placing a pause and/or cancel button close to the progress bar.
</item>

<item>
Ensure that time-remaining and typical-time progress bars measure an operation’s total time or total work, not just that of a single step.
</item>

<item>
Update time-remaining progress bars when changes occur that will cause the operation to finish more quickly or more slowly.
</item>

<item>
When using a typical-time progress bar, if your application overestimates the completed amount of work, the length of the bar can indicate <gui>almost complete</gui> until the operation is complete. If your application underestimates how much work is complete, fill the remaining portion of the bar when the operation is complete.
</item>

</list>

</section>

<section id="api-reference">

<title>API reference</title>

<list>

<item>
<link href="https://developer.gnome.org/gtk3/stable/GtkProgressBar.html">GtkProgressBar</link>
</item>

</list>

</section>

</page>