gem-graph-client/docs/GTK-docs/gnome-dev-guidelines/developer.gnome.org/hig/patterns/feedback/progress-bars.html

318 lines
20 KiB
HTML
Raw Normal View History

<!doctype html>
<html class="no-js">
<head><meta charset="utf-8"/>
<meta name="viewport" content="width=device-width,initial-scale=1"/>
<meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" /><link rel="next" title="Spinners" href="spinners.html" /><link rel="prev" title="Info Bars" href="info-bars.html" />
<meta name="generator" content="sphinx-4.3.0, furo 2021.07.05.beta38"/>
<title>Progress Bars - GNOME Human Interface Guidelines documentation</title>
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css" />
<link rel="stylesheet" type="text/css" href="../../_static/styles/furo-extensions.css" />
<link rel="stylesheet" type="text/css" href="../../_static/gnome.css" />
<style>
:root {
--color-code-background: #f8f8f8;
--color-code-foreground: black;
--color-brand-primary: #4a86cf;
--color-brand-content: #4a86cf;
}
@media (prefers-color-scheme: dark) {
:root {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
}
}
/* For allowing end-user-specific overrides */
.override-light {
--color-code-background: #f8f8f8;
--color-code-foreground: black;
--color-brand-primary: #4a86cf;
--color-brand-content: #4a86cf;
}
.override-dark {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
}
</style><link media="(prefers-color-scheme: dark)" rel="stylesheet" href="../../_static/pygments_dark.css"></head>
<body dir="">
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
<symbol id="svg-toc" viewBox="0 0 24 24">
<title>Contents</title>
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none"
stroke-width="1.5" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round">
<path stroke="none" d="M0 0h24v24H0z"/>
<line x1="4" y1="6" x2="20" y2="6" />
<line x1="10" y1="12" x2="20" y2="12" />
<line x1="6" y1="18" x2="20" y2="18" />
</svg>
</symbol>
<symbol id="svg-menu" viewBox="0 0 24 24">
<title>Menu</title>
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none"
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
class="feather feather-menu">
<line x1="3" y1="12" x2="21" y2="12"></line>
<line x1="3" y1="6" x2="21" y2="6"></line>
<line x1="3" y1="18" x2="21" y2="18"></line>
</svg>
</symbol>
<symbol id="svg-arrow-right" viewBox="0 0 24 24">
<title>Expand</title>
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none"
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
class="feather feather-chevron-right">
<polyline points="9 18 15 12 9 6"></polyline>
</svg>
</symbol>
</svg>
<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
<label class="overlay sidebar-overlay" for="__navigation"></label>
<label class="overlay toc-overlay" for="__toc"></label>
<div class="page">
<header class="mobile-header">
<div class="header-left">
<label class="nav-overlay-icon" for="__navigation">
<i class="icon"><svg><use href="#svg-menu"></use></svg></i>
</label>
</div>
<div class="header-center">
<a href="../../index.html"><div class="brand">GNOME Human Interface Guidelines</div></a>
</div>
<div class="header-right">
<label class="toc-overlay-icon toc-header-icon" for="__toc">
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
</label>
</div>
</header>
<aside class="sidebar-drawer">
<div class="sidebar-container">
<div class="sidebar-sticky"><a class="sidebar-brand centered" href="../../index.html">
<div class="sidebar-logo-container">
<img class="sidebar-logo" src="../../_static/logo.svg" alt="Logo"/>
</div>
<span class="sidebar-brand-text">GNOME Human Interface Guidelines</span>
</a><form class="sidebar-search-container" method="get" action="../../search.html">
<input class="sidebar-search" placeholder=Search name="q">
<input type="hidden" name="check_keywords" value="yes">
<input type="hidden" name="area" value="default">
</form><div class="sidebar-scroll"><div class="sidebar-tree">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../principles.html">Design Principles</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../resources.html">Tools &amp; Resources</a></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="../../guidelines.html">Guidelines</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label for="toctree-checkbox-1"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l2"><a class="reference internal" href="../../guidelines/app-naming.html">App Naming</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../guidelines/app-icons.html">App Icons</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../guidelines/pointer-touch.html">Pointer &amp; Touch</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../guidelines/keyboard.html">Keyboard</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../guidelines/ui-icons.html">UI Icons</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../guidelines/ui-styling.html">UI Styling</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../guidelines/writing-style.html">Writing Style</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../guidelines/typography.html">Typography</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../guidelines/navigation.html">Navigation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../guidelines/adaptive.html">Scaling &amp; Adaptiveness</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../guidelines/accessibility.html">Accessibility</a></li>
</ul>
</li>
<li class="toctree-l1 current has-children"><a class="reference internal" href="../../patterns.html">Patterns</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" type="checkbox"/><label for="toctree-checkbox-2"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul class="current">
<li class="toctree-l2 has-children"><a class="reference internal" href="../containers.html">Containers</a><input class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" type="checkbox"/><label for="toctree-checkbox-3"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../containers/windows.html">Windows</a></li>
<li class="toctree-l3"><a class="reference internal" href="../containers/header-bars.html">Header Bars</a></li>
<li class="toctree-l3"><a class="reference internal" href="../containers/popovers.html">Popovers</a></li>
<li class="toctree-l3"><a class="reference internal" href="../containers/utility-panes.html">Utility Panes</a></li>
<li class="toctree-l3"><a class="reference internal" href="../containers/boxed-lists.html">Boxed Lists</a></li>
<li class="toctree-l3"><a class="reference internal" href="../containers/grid-views.html">Grid Views</a></li>
<li class="toctree-l3"><a class="reference internal" href="../containers/list-column-views.html">List &amp; Column Views</a></li>
<li class="toctree-l3"><a class="reference internal" href="../containers/selection-mode.html">Selection &amp; Edit Modes</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../nav.html">Navigation</a><input class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" type="checkbox"/><label for="toctree-checkbox-4"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../nav/browsing.html">Browsing</a></li>
<li class="toctree-l3"><a class="reference internal" href="../nav/view-switchers.html">View Switchers</a></li>
<li class="toctree-l3"><a class="reference internal" href="../nav/tabs.html">Tabs</a></li>
<li class="toctree-l3"><a class="reference internal" href="../nav/sidebars.html">Sidebars</a></li>
<li class="toctree-l3"><a class="reference internal" href="../nav/search.html">Search</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../controls.html">Controls</a><input class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" type="checkbox"/><label for="toctree-checkbox-5"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../controls/buttons.html">Buttons</a></li>
<li class="toctree-l3"><a class="reference internal" href="../controls/menus.html">Menus</a></li>
<li class="toctree-l3"><a class="reference internal" href="../controls/switches.html">Switches</a></li>
<li class="toctree-l3"><a class="reference internal" href="../controls/text-fields.html">Text Fields</a></li>
<li class="toctree-l3"><a class="reference internal" href="../controls/checkboxes.html">Checkboxes</a></li>
<li class="toctree-l3"><a class="reference internal" href="../controls/radio-buttons.html">Radio Buttons</a></li>
<li class="toctree-l3"><a class="reference internal" href="../controls/drop-downs.html">Drop-Down Lists</a></li>
<li class="toctree-l3"><a class="reference internal" href="../controls/sliders.html">Sliders</a></li>
<li class="toctree-l3"><a class="reference internal" href="../controls/spin-buttons.html">Spin Buttons</a></li>
<li class="toctree-l3"><a class="reference internal" href="../controls/overlaid.html">Overlaid Controls</a></li>
</ul>
</li>
<li class="toctree-l2 current has-children"><a class="reference internal" href="../feedback.html">Feedback</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-6" name="toctree-checkbox-6" type="checkbox"/><label for="toctree-checkbox-6"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="notifications.html">Notifications</a></li>
<li class="toctree-l3"><a class="reference internal" href="toasts.html">Toasts</a></li>
<li class="toctree-l3"><a class="reference internal" href="info-bars.html">Info Bars</a></li>
<li class="toctree-l3 current current-page"><a class="current reference internal" href="#">Progress Bars</a></li>
<li class="toctree-l3"><a class="reference internal" href="spinners.html">Spinners</a></li>
<li class="toctree-l3"><a class="reference internal" href="dialogs.html">Dialogs</a></li>
<li class="toctree-l3"><a class="reference internal" href="placeholders.html">Placeholder Pages</a></li>
<li class="toctree-l3"><a class="reference internal" href="tooltips.html">Tooltips</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1 has-children"><a class="reference internal" href="../../reference.html">Reference</a><input class="toctree-checkbox" id="toctree-checkbox-7" name="toctree-checkbox-7" type="checkbox"/><label for="toctree-checkbox-7"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l2"><a class="reference internal" href="../../reference/keyboard.html">Standard Keyboard Shortcuts</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../reference/palette.html">Palette</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../reference/backgrounds.html">Backgrounds</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</div>
</aside>
<main class="main">
<div class="content">
<article role="main">
<label class="toc-overlay-icon toc-content-icon" for="__toc">
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
</label>
<section id="progress-bars">
<h1>Progress Bars<a class="headerlink" href="#progress-bars" title="Permalink to this headline"></a></h1>
<img alt="../../_images/progress-bar.png" class="light" src="../../_images/progress-bar.png"/>
<img alt="../../_images/progress-bar-dark.png" class="dark" src="../../_images/progress-bar-dark.png"/>
<p>Progress bars indicate progress on a task. Unlike <a class="reference internal" href="spinners.html"><span class="doc">spinners</span></a>, they typically indicate the proportion of the task that has been completed.</p>
<p>Progress bars are most appropriate for indicating the progress of tasks that take a relatively long time (as a rule of thumb, tasks that take over 30 seconds). For tasks that have shorter periods, spinners are often a better choice.</p>
<section id="the-bar">
<h2>The Bar<a class="headerlink" href="#the-bar" title="Permalink to this headline"></a></h2>
<p>The bar of a progress bar should indicate the amount of time remaining to complete the task.</p>
<p>Ideally, the remaining time should be calculated accurately. However, if this is not possible, then the remaining time can be estimated. Here, overestimation can be handled by having progress pause at 100%, and showing explanatory text such as “Almost done”. Underestimation can be handled by having progress skip ahead as necessary.</p>
<p>If it is impossible to estimate the remaining time, then the progress bar can be set to activity mode, which causes it to move back and forth without indicating progress. Activity mode should be avoided wherever possible, particularly for long periods of time.</p>
</section>
<section id="progress-text">
<h2>Progress Text<a class="headerlink" href="#progress-text" title="Permalink to this headline"></a></h2>
<p>Progress bars should have a text label that describes how much of the task has been completed. For shorter tasks, this can be expressed using units which are appropriate to the task. For example, “13 of 19 images rotated” or “12.1 of 30 MB downloaded”.</p>
<p>For long-running tasks, it can be desirable to show an estimate of the time remaining, either on its own, or with supplementary progress information. If the time remaining is an estimate, use the word “about“. For example, “About 3 minutes left”.</p>
</section>
<section id="task-stages">
<h2>Task Stages<a class="headerlink" href="#task-stages" title="Permalink to this headline"></a></h2>
<p>Some tasks can be made up of a series of stages, each of which has a separate time estimation. In these situations, try to create a single composite calculation of the remaining time for the entire task. Only communicate the different stages in a task when it is relevant to users.</p>
<p>In some cases, it is possible to calculate or estimate the time remaining for part of a task, but not another part. In this situation, a progress bar can enter activity mode for part of the task. However, it is best not to show activity mode for long periods of time, and the number of progress bar mode changes should be kept to an absolute minimum.</p>
</section>
<section id="subtasks">
<h2>Subtasks<a class="headerlink" href="#subtasks" title="Permalink to this headline"></a></h2>
<p>Some tasks are comprised of multiple simultaneous subtasks (such as downloading several files at the same time). Here, it is generally advisable to show a single progress bar that indicates combined progress for all tasks.</p>
<p>In rare cases, it might be desirable to show a progress bar for each individual subtask. However, only do this if it is genuinely useful for the user to know progress for each subtask, or if it might be necessary to pause or stop a subtask.</p>
</section>
<section id="thin-progress-bars">
<h2>Thin Progress Bars<a class="headerlink" href="#thin-progress-bars" title="Permalink to this headline"></a></h2>
<img alt="../../_images/osd-progress-bar.png" class="light" src="../../_images/osd-progress-bar.png"/>
<img alt="../../_images/osd-progress-bar-dark.png" class="dark" src="../../_images/osd-progress-bar-dark.png"/>
<p>For situations where task progress happens in the background, and accompanying text isnt as important, a thin progress bar can be used. These are smaller than regular progress bars, dont show accompanying status text, and are attached to the bottom of the header bar.</p>
<p>See the <a class="reference external" href="https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/style-classes.html#progress-bars">style class documentation</a> for details.</p>
</section>
<section id="general-guidelines">
<h2>General Guidelines<a class="headerlink" href="#general-guidelines" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p>If an operation is potentially destructive or resource-intensive, consider adding pause and/or cancel buttons to the progress bar.</p></li>
<li><p>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.</p></li>
<li><p>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.</p></li>
</ul>
</section>
<section id="api-reference">
<h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference external" href="https://docs.gtk.org/gtk4/class.ProgressBar.html">GTK 4: GtkProgressBar</a></p></li>
<li><p><a class="reference external" href="https://docs.gtk.org/gtk3/class.ProgressBar.html">GTK 3: GtkProgressBar</a></p></li>
</ul>
</section>
</section>
</article>
<footer>
<div class="related-pages">
<a class="next-page" href="spinners.html">
<div class="page-info">
<div class="context">
<span>Next</span>
</div>
<div class="title">Spinners</div>
</div>
<svg><use href="#svg-arrow-right"></use></svg>
</a>
<a class="prev-page" href="info-bars.html">
<svg><use href="#svg-arrow-right"></use></svg>
<div class="page-info">
<div class="context">
<span>Previous</span>
</div>
<div class="title">Info Bars</div>
</div>
</a>
</div>
</footer>
</div>
<aside class="toc-drawer">
<div class="toc-sticky toc-scroll">
<div class="toc-title-container">
<span class="toc-title">
Contents
</span>
</div>
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">Progress Bars</a><ul>
<li><a class="reference internal" href="#the-bar">The Bar</a></li>
<li><a class="reference internal" href="#progress-text">Progress Text</a></li>
<li><a class="reference internal" href="#task-stages">Task Stages</a></li>
<li><a class="reference internal" href="#subtasks">Subtasks</a></li>
<li><a class="reference internal" href="#thin-progress-bars">Thin Progress Bars</a></li>
<li><a class="reference internal" href="#general-guidelines">General Guidelines</a></li>
<li><a class="reference internal" href="#api-reference">API Reference</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</aside>
</main>
</div><script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
<script src="../../_static/jquery.js"></script>
<script src="../../_static/underscore.js"></script>
<script src="../../_static/doctools.js"></script>
<script src="../../_static/scripts/main.js"></script>
</body>
</html>