315 lines
19 KiB
HTML
315 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="Checkboxes" href="checkboxes.html" /><link rel="prev" title="Switches" href="switches.html" />
|
|
|
|
<meta name="generator" content="sphinx-4.3.0, furo 2021.07.05.beta38"/>
|
|
<title>Text Fields - 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 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 current has-children"><a class="reference internal" href="../controls.html">Controls</a><input checked="" 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 class="current">
|
|
<li class="toctree-l3"><a class="reference internal" href="buttons.html">Buttons</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="menus.html">Menus</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="switches.html">Switches</a></li>
|
|
<li class="toctree-l3 current current-page"><a class="current reference internal" href="#">Text Fields</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="checkboxes.html">Checkboxes</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="radio-buttons.html">Radio Buttons</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="drop-downs.html">Drop-Down Lists</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="sliders.html">Sliders</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="spin-buttons.html">Spin Buttons</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="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="text-fields">
|
|
<h1>Text Fields<a class="headerlink" href="#text-fields" title="Permalink to this headline">¶</a></h1>
|
|
<img alt="../../_images/text-fields.png" class="light" src="../../_images/text-fields.png"/>
|
|
<img alt="../../_images/text-fields-dark.png" class="dark" src="../../_images/text-fields-dark.png"/>
|
|
<p>Text fields are used for single line text entry and editing.</p>
|
|
<section id="guidelines">
|
|
<h2>Guidelines<a class="headerlink" href="#guidelines" title="Permalink to this headline">¶</a></h2>
|
|
<p>General guidelines for text fields:</p>
|
|
<ul class="simple">
|
|
<li><p>Give text fields a label using <a class="reference internal" href="../../guidelines/writing-style.html#header-capitalization"><span class="std std-ref">header capitalization</span></a>, and assign an access key to the label, to allow people to focus the control using a keyboard.</p></li>
|
|
<li><p>If there is a little available space, or a label would disrupt the overall visual layout, placeholder text can be shown inside the field instead of using a label.</p></li>
|
|
<li><p>Size text fields according to the likely size of the content they will contain. This gives a useful visual cue to the amount of expected input.</p></li>
|
|
<li><p>When a text field contains a property or setting, apply any changes when Return is pressed or when the field loses focus.</p></li>
|
|
<li><p>Buttons and icons can be embedded inside text fields. This can be helpful to provide feedback (for example, a spinner to indicate progress) or common actions (for example, a clear button). Embedded buttons and icons should use the <a class="reference internal" href="../../guidelines/ui-icons.html"><span class="doc">symbolic style</span></a>.</p></li>
|
|
</ul>
|
|
</section>
|
|
<section id="text-validation">
|
|
<h2>Text Validation<a class="headerlink" href="#text-validation" title="Permalink to this headline">¶</a></h2>
|
|
<p>Text fields can often require their content to have a particular format, such as in the case of a URL or hex color value. In these cases, it is important to provide effective feedback.</p>
|
|
<p>When doing this, it is generally better to show positive feedback when the content is valid, as opposed to showing negative feedback while it is invalid. This avoids distracting and confusing users while they are in the process of editing the field.</p>
|
|
<p>It is often better to show feedback in real time as the field is edited, as opposed to waiting until the field loses focus.</p>
|
|
</section>
|
|
<section id="password-fields">
|
|
<h2>Password Fields<a class="headerlink" href="#password-fields" title="Permalink to this headline">¶</a></h2>
|
|
<p>Password fields are a special type of text field for which GNOME provides <a class="reference external" href="https://docs.gtk.org/gtk4/class.PasswordEntry.html">a dedicated control</a>. This hides entered text, which can be revealed with a button, and can be used for any potentially sensitive text.</p>
|
|
<p>A password field example can be found in the <em>Entry → Password Entry</em> demo in the GTK 4 demo app.</p>
|
|
</section>
|
|
<section id="automatic-suggestions">
|
|
<h2>Automatic Suggestions<a class="headerlink" href="#automatic-suggestions" title="Permalink to this headline">¶</a></h2>
|
|
<p>It is often helpful to suggest potential text to be entered as the user types into a text field. For example, an address field can show previous locations as the user types. This reduces the amount of work for users and reduces errors.</p>
|
|
<p>An example of automatic suggestions can be found in the <em>Entry → Completion</em> example in the GTK 4 demo app.</p>
|
|
</section>
|
|
<section id="tags">
|
|
<h2>Tags<a class="headerlink" href="#tags" title="Permalink to this headline">¶</a></h2>
|
|
<p>Tags or tokens are a typical convention for some types of text field. For example, the <em>To</em> field in an email app will often display each recipient as a tag. This aids readability and makes it easy to remove each item from the field.</p>
|
|
<p>Currently, entry tags require a custom implementation. However, the GTK 4 demo application does include an example under <em>Entry → Tagged Entry</em>.</p>
|
|
</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.Entry.html">GTK 4: GtkEntry</a></p></li>
|
|
<li><p><a class="reference external" href="https://docs.gtk.org/gtk4/class.TextView.html">GTK 4: GtkTextView</a></p></li>
|
|
<li><p><a class="reference external" href="https://docs.gtk.org/gtk4/class.PasswordEntry.html">GTK 4: GtkPasswordEntry</a></p></li>
|
|
<li><p><a class="reference external" href="https://docs.gtk.org/gtk3/class.Entry.html">GTK 3: GtkEntry</a></p></li>
|
|
<li><p><a class="reference external" href="https://docs.gtk.org/gtk3/class.TextView.html">GTK 3: GtkTextView</a></p></li>
|
|
</ul>
|
|
</section>
|
|
</section>
|
|
|
|
</article>
|
|
<footer>
|
|
|
|
<div class="related-pages">
|
|
<a class="next-page" href="checkboxes.html">
|
|
<div class="page-info">
|
|
<div class="context">
|
|
<span>Next</span>
|
|
</div>
|
|
<div class="title">Checkboxes</div>
|
|
</div>
|
|
<svg><use href="#svg-arrow-right"></use></svg>
|
|
</a>
|
|
<a class="prev-page" href="switches.html">
|
|
<svg><use href="#svg-arrow-right"></use></svg>
|
|
<div class="page-info">
|
|
<div class="context">
|
|
<span>Previous</span>
|
|
</div>
|
|
|
|
<div class="title">Switches</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="#">Text Fields</a><ul>
|
|
<li><a class="reference internal" href="#guidelines">Guidelines</a></li>
|
|
<li><a class="reference internal" href="#text-validation">Text Validation</a></li>
|
|
<li><a class="reference internal" href="#password-fields">Password Fields</a></li>
|
|
<li><a class="reference internal" href="#automatic-suggestions">Automatic Suggestions</a></li>
|
|
<li><a class="reference internal" href="#tags">Tags</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> |