317 lines
19 KiB
HTML
317 lines
19 KiB
HTML
|
<!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="Controls" href="../controls.html" /><link rel="prev" title="Sidebars" href="sidebars.html" />
|
||
|
|
|
||
|
|
<meta name="generator" content="sphinx-4.3.0, furo 2021.07.05.beta38"/>
|
||
|
|
<title>Search - 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 & 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 & 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 & 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 & Column Views</a></li>
|
||
|
|
<li class="toctree-l3"><a class="reference internal" href="../containers/selection-mode.html">Selection & Edit Modes</a></li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
<li class="toctree-l2 current has-children"><a class="reference internal" href="../nav.html">Navigation</a><input checked="" 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 class="current">
|
||
|
|
<li class="toctree-l3"><a class="reference internal" href="browsing.html">Browsing</a></li>
|
||
|
|
<li class="toctree-l3"><a class="reference internal" href="view-switchers.html">View Switchers</a></li>
|
||
|
|
<li class="toctree-l3"><a class="reference internal" href="tabs.html">Tabs</a></li>
|
||
|
|
<li class="toctree-l3"><a class="reference internal" href="sidebars.html">Sidebars</a></li>
|
||
|
|
<li class="toctree-l3 current current-page"><a class="current reference internal" href="#">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 has-children"><a class="reference internal" href="../feedback.html">Feedback</a><input 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>
|
||
|
|
<li class="toctree-l3"><a class="reference internal" href="../feedback/notifications.html">Notifications</a></li>
|
||
|
|
<li class="toctree-l3"><a class="reference internal" href="../feedback/toasts.html">Toasts</a></li>
|
||
|
|
<li class="toctree-l3"><a class="reference internal" href="../feedback/info-bars.html">Info Bars</a></li>
|
||
|
|
<li class="toctree-l3"><a class="reference internal" href="../feedback/progress-bars.html">Progress Bars</a></li>
|
||
|
|
<li class="toctree-l3"><a class="reference internal" href="../feedback/spinners.html">Spinners</a></li>
|
||
|
|
<li class="toctree-l3"><a class="reference internal" href="../feedback/dialogs.html">Dialogs</a></li>
|
||
|
|
<li class="toctree-l3"><a class="reference internal" href="../feedback/placeholders.html">Placeholder Pages</a></li>
|
||
|
|
<li class="toctree-l3"><a class="reference internal" href="../feedback/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="search">
|
||
|
|
<h1>Search<a class="headerlink" href="#search" title="Permalink to this headline">¶</a></h1>
|
||
|
|
<img alt="../../_images/search.png" class="light" src="../../_images/search.png"/>
|
||
|
|
<img alt="../../_images/search-dark.png" class="dark" src="../../_images/search-dark.png"/>
|
||
|
|
<p>Search allows content items to be located by filtering available content. It is distinct from find, which involves moving to and highlighting the content that is being searched for, rather than filtering.</p>
|
||
|
|
<p>Examples of search can be found in the <em>Search Entry</em> and <em>Type to Search</em> demos in the GTK 4 demo app.</p>
|
||
|
|
<section id="when-to-use">
|
||
|
|
<h2>When to Use<a class="headerlink" href="#when-to-use" title="Permalink to this headline">¶</a></h2>
|
||
|
|
<p>Provide search whenever there are more content items than can be easily displayed, and those content items have a textual component. Examples include a collection of documents, a list of recently used files, or selecting a country for a location.</p>
|
||
|
|
<p>Search is a great way to make it easy for users to find what it is they are looking for, and its consistent availability means that users can rely on and expect it to be present.</p>
|
||
|
|
<p>However, while search can be highly effective, and some users will use it, others will not. Therefore, it should not be relied on exclusively, and thought should be put into how users will find items without search.</p>
|
||
|
|
</section>
|
||
|
|
<section id="the-search-bar">
|
||
|
|
<h2>The Search Bar<a class="headerlink" href="#the-search-bar" title="Permalink to this headline">¶</a></h2>
|
||
|
|
<p>The standard pattern for search in GNOME utilizes a search bar which slides down from beneath the header bar. In primary windows, the search bar is typically hidden until it is activated by the user. There are three common ways to activate search in this context:</p>
|
||
|
|
<ol class="arabic simple">
|
||
|
|
<li><p>Typing, even when the search field is not focused (this is called “type to search”).</p></li>
|
||
|
|
<li><p>Ctrl+F: the keyboard shortcut for search.</p></li>
|
||
|
|
<li><p>The search button in the header bar, which should toggle.</p></li>
|
||
|
|
</ol>
|
||
|
|
<p>However, if search is particularly important to your app, the search entry can be located elsewhere and made to be permanently visible.</p>
|
||
|
|
</section>
|
||
|
|
<section id="search-results">
|
||
|
|
<h2>Search Results<a class="headerlink" href="#search-results" title="Permalink to this headline">¶</a></h2>
|
||
|
|
<p>Guidelines on presenting search results:</p>
|
||
|
|
<ul class="simple">
|
||
|
|
<li><p>Search should be “live” wherever possible — the content view should update to display search results as they are entered.</p></li>
|
||
|
|
<li><p>In order to be effective, it is important that search results are quickly returned.</p></li>
|
||
|
|
<li><p>If a search term does not return any results, ensure that feedback is given in the content view. Often a simple “No results” label is sufficient.</p></li>
|
||
|
|
<li><p>It is better to show results incrementally, as they are collected, as opposed to waiting for all results to be returned before displaying them.</p></li>
|
||
|
|
</ul>
|
||
|
|
</section>
|
||
|
|
<section id="additional-guidance">
|
||
|
|
<h2>Additional Guidance<a class="headerlink" href="#additional-guidance" title="Permalink to this headline">¶</a></h2>
|
||
|
|
<ul class="simple">
|
||
|
|
<li><p>Search should be global and return results from all views, as opposed to just returning results from the current view. This makes search more predictable and minimizes user error as a result.</p></li>
|
||
|
|
<li><p>Be tolerant of mistakes in search terms. Approximate/fuzzy string matching is one way to do this. Presenting suggestions for similar matches or related content is another.</p></li>
|
||
|
|
<li><p>Permit a broad range of matching search terms. This helps people who are unsure of the exact term they require but who do know characteristics associated with the item they want to find. A list of cities could return matches for country or region, for example.</p></li>
|
||
|
|
<li><p>Results should be ordered in a way that ensures that the most relevant items are displayed first.</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.SearchBar.html">GTK 4: GtkSearchBar</a></p></li>
|
||
|
|
<li><p><a class="reference external" href="https://docs.gtk.org/gtk4/class.SearchEntry.html">GTK 4: GtkSearchEntry</a></p></li>
|
||
|
|
<li><p><a class="reference external" href="https://docs.gtk.org/gtk3/class.SearchBar.html">GTK 3: GtkSearchBar</a></p></li>
|
||
|
|
<li><p><a class="reference external" href="https://docs.gtk.org/gtk3/class.SearchEntry.html">GTK 3: GtkSearchEntry</a></p></li>
|
||
|
|
</ul>
|
||
|
|
</section>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
</article>
|
||
|
|
<footer>
|
||
|
|
|
||
|
|
<div class="related-pages">
|
||
|
|
<a class="next-page" href="../controls.html">
|
||
|
|
<div class="page-info">
|
||
|
|
<div class="context">
|
||
|
|
<span>Next</span>
|
||
|
|
</div>
|
||
|
|
<div class="title">Controls</div>
|
||
|
|
</div>
|
||
|
|
<svg><use href="#svg-arrow-right"></use></svg>
|
||
|
|
</a>
|
||
|
|
<a class="prev-page" href="sidebars.html">
|
||
|
|
<svg><use href="#svg-arrow-right"></use></svg>
|
||
|
|
<div class="page-info">
|
||
|
|
<div class="context">
|
||
|
|
<span>Previous</span>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<div class="title">Sidebars</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="#">Search</a><ul>
|
||
|
|
<li><a class="reference internal" href="#when-to-use">When to Use</a></li>
|
||
|
|
<li><a class="reference internal" href="#the-search-bar">The Search Bar</a></li>
|
||
|
|
<li><a class="reference internal" href="#search-results">Search Results</a></li>
|
||
|
|
<li><a class="reference internal" href="#additional-guidance">Additional Guidance</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>
|