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

324 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="Placeholder Pages" href="placeholders.html" /><link rel="prev" title="Spinners" href="spinners.html" />
<meta name="generator" content="sphinx-4.3.0, furo 2021.07.05.beta38"/>
<title>Dialogs - 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"><a class="reference internal" href="progress-bars.html">Progress Bars</a></li>
<li class="toctree-l3"><a class="reference internal" href="spinners.html">Spinners</a></li>
<li class="toctree-l3 current current-page"><a class="current reference internal" href="#">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="dialogs">
<h1>Dialogs<a class="headerlink" href="#dialogs" title="Permalink to this headline"></a></h1>
<p>Dialog windows present options, choices or information to users, which they must respond to in order to continue. There are two types of dialog in GNOME: message dialogs and action dialogs.</p>
<section id="message-dialogs">
<span id="id1"></span><h2>Message Dialogs<a class="headerlink" href="#message-dialogs" title="Permalink to this headline"></a></h2>
<img alt="../../_images/message-dialog.png" class="light" src="../../_images/message-dialog.png"/>
<img alt="../../_images/message-dialog-dark.png" class="dark" src="../../_images/message-dialog-dark.png"/>
<p>Message dialogs present a message or question, along with between one and three buttons with which to respond. Message dialogs are an appropriate choice when it is essential that the user sees and responds to a message. However, they are also disruptive and alternatives should therefore be considered.</p>
<section id="confirmation-dialogs">
<h3>Confirmation Dialogs<a class="headerlink" href="#confirmation-dialogs" title="Permalink to this headline"></a></h3>
<p>Confirmation dialogs are a standard type of message dialog which check — or confirm — that the user wants to carry out an action before carrying it out. They have two buttons: one to confirm that the action should be carried out and one to cancel the action.</p>
<p>Destructive actions should always be accompanied by either a confirmation dialog or an offer to undo the action (typically using a <a class="reference internal" href="toasts.html"><span class="doc">toast</span></a>). Since users will often habitually click through confirmation dialogs without fully reading or considering them, undo is typically a better option than a confirmation dialog. Undo also avoids interrupting the user, allows users to recover from errors, and gives them more time to change their mind.</p>
<p>However, in cases where it is not possible to offer an undo feature, a confirmation dialog is still recommended, to alert the user to the risk, to clarify which action will be taken, and to give them the opportunity to cancel.</p>
</section>
<section id="error-dialogs">
<h3>Error Dialogs<a class="headerlink" href="#error-dialogs" title="Permalink to this headline"></a></h3>
<p>Error dialogs are another type of message dialog. These present an error message to the user and often include just a single button to close the dialog.</p>
<p>Error dialogs should be avoided where possible, since they are disruptive. For simple non-critical errors, <a class="reference internal" href="toasts.html"><span class="doc">toasts</span></a> can be a good alternative.</p>
</section>
</section>
<section id="action-dialogs">
<span id="id2"></span><h2>Action Dialogs<a class="headerlink" href="#action-dialogs" title="Permalink to this headline"></a></h2>
<img alt="../../_images/action-dialog.png" class="light" src="../../_images/action-dialog.png"/>
<img alt="../../_images/action-dialog-dark.png" class="dark" src="../../_images/action-dialog-dark.png"/>
<p>Action dialogs present options and/or information about an action, before it is carried out. <em>Print</em> and <em>Save</em> dialogs are classic examples of action dialogs.</p>
<p>Since action dialogs obscure the parent window and require a context switch on the part of a user, inline controls or actions are often preferable. In an email app, for example, email composition is generally better in the primary window, as opposed to an action dialog.</p>
<ul class="simple">
<li><p>Action dialogs have a header bar, a heading which describes the action, and two primary buttons — one which carries out the action and one which cancels it.</p></li>
<li><p>Label the affirmative button with a specific imperative verb, for example: <em>Save</em> or <em>Print</em>. This is clearer than a generic label like <em>OK</em> or <em>Done</em>.</p></li>
<li><p>Sometimes, the user may be required to choose options before an action can be carried out. In these cases, the affirmative dialog button should be insensitive until the required options have been selected.</p></li>
</ul>
</section>
<section id="general-guidelines">
<h2>General Guidelines<a class="headerlink" href="#general-guidelines" title="Permalink to this headline"></a></h2>
<p>General guidelines for all types of dialogs:</p>
<ul class="simple">
<li><p>Never pop up a dialog window unexpectedly. They should only ever be displayed in immediate response to a deliberate user action.</p></li>
<li><p>Dialogs should always have a parent window, to which they are modal.</p></li>
<li><p>When opening a dialog, provide initial keyboard focus to the component that you expect users to operate first. This focus is especially important for users who must use a keyboard to navigate.</p></li>
</ul>
<p>Guidelines on dialog buttons:</p>
<ul class="simple">
<li><p>Always ensure that the cancel button appears first, before the affirmative button. In left-to-right locales, this is on the left. This button order ensures that users become aware of, and are reminded of, the ability to cancel prior to encountering the affirmative button.</p></li>
<li><p>Assign the return key to activate the affirmative button. However, this should not be done if its action is irreversible, destructive or otherwise inconvenient to the user. If there is no appropriate button to designate as the default button, do not set one.</p></li>
<li><p>Ensure that the Esc key activates the cancel button, if there is one. Message dialogs with a single button can have both escape and return bound to the same button.</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.MessageDialog.html">GTK 4: GtkMessageDialog</a></p></li>
<li><p><a class="reference external" href="https://docs.gtk.org/gtk3/class.MessageDialog.html">GTK 3: GtkMessageDialog</a></p></li>
</ul>
</section>
</section>
</article>
<footer>
<div class="related-pages">
<a class="next-page" href="placeholders.html">
<div class="page-info">
<div class="context">
<span>Next</span>
</div>
<div class="title">Placeholder Pages</div>
</div>
<svg><use href="#svg-arrow-right"></use></svg>
</a>
<a class="prev-page" href="spinners.html">
<svg><use href="#svg-arrow-right"></use></svg>
<div class="page-info">
<div class="context">
<span>Previous</span>
</div>
<div class="title">Spinners</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="#">Dialogs</a><ul>
<li><a class="reference internal" href="#message-dialogs">Message Dialogs</a><ul>
<li><a class="reference internal" href="#confirmation-dialogs">Confirmation Dialogs</a></li>
<li><a class="reference internal" href="#error-dialogs">Error Dialogs</a></li>
</ul>
</li>
<li><a class="reference internal" href="#action-dialogs">Action Dialogs</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>