xmlns:itst="http://itstool.org/extensions/"

      type="topic"

      id="keyboard-input">

  <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>

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

    <desc>Keyboard navigation, access and shortcut keys.</desc>  

  </info>

<title>Keyboard input</title>

Keyboards are a common way to interact with user interfaces. They provide a convenient and effective means to use applications in a variety of situations, and can be faster and more efficient than other input devices. Keyboards are also vital for visually-impaired people or those with mobility impairments.

You should ensure that all the functionality provided by your application can be accessed using a keyboard. Trying to use your application with only a keyboard is a great way to test this.

Keyboard interaction has three aspects in GNOME and GTK+: navigation, access keys, and shortcut keys. <link xref="search">Search</link> is another, additional aspect.

<section id="keyboard-navigation">

<title>Keyboard navigation</title>

Make sure that it is possible to move around and interact with every part of your user interface using the keyboard, by following these guidelines.

<list>

<item>
Follow the standard GNOME keys for navigation. <key>Tab</key> is the standard key for moving around an interface with GTK+ and GNOME.
</item>

<item>
Use a logical keyboard navigation order. When navigating around a window with <key>Tab</key>, keyboard focus should move between controls in a predictable order. In Western locales, this is normally left to right and top to bottom.
</item>

<item>
In addition to navigation using <key>Tab</key>, make an effort to allow movement using the arrow keys, both within user interface elements (such as lists, icon grids or sidebars), and between them.
</item>

</list>

<note>
If activating a control enables other controls, do not automatically give focus to the first dependent control when it is activated, but instead leave focus in place.
</note>

<section id="navigation-keys">

<title>Standard navigation keys</title>

Shortcut

Function

<key>Tab</key> and <keyseq><key>Shift</key><key>Tab</key></keyseq>

Moves keyboard focus to the next/previous control

<keyseq><key>Ctrl</key><key>Tab</key></keyseq> and <keyseq><key>Shift</key><key>Ctrl</key><key>Tab</key></keyseq>

Moves keyboard focus out of the enclosing widget to the next/previous control, in those situations where Tab alone has another function

<keyseq><key>Ctrl</key><key>Tab</key></keyseq> and <keyseq><key>Shift</key><key>Ctrl</key><key>Tab</key></keyseq>

Moves keyboard focus to the next/previous group of controls

<keyseq><key>Ctrl</key><key>F1</key></keyseq>

Shows a tooltip for the the currently-focused window or control

<keyseq><key>Shift</key><key>F1</key></keyseq>

Show context-sensitive help for the currently-focused window or control

<key>F6</key> and <keyseq><key>Shift</key><key>F6</key></keyseq>

Give focus to the next/previous pane in a GtkPaned window

<key>F8</key>

Give focus to the splitter bar in a paned window

<key>F10</key>

Give focus to the menu bar or open header bar menu

<key>Space</key>

Toggle the state of a focused check box, radio button, or toggle button

<key>Return</key>

Activate focused button, menu item, etc

<key>Return</key> and <key>End</key>

Select/move to the first item in a selected widget

<key>PageUp</key>, <keyseq><key>Ctrl</key><key>PageUp</key></keyseq>, <key>PageDown</key> and <keyseq><key>Ctrl</key><key>PageDown</key></keyseq>

Scroll the selected view by one page up/left/down/right

<key>Escape</key>

Close or exit the current context, if it is transient. This should be consistently used for menus, popovers or <link xref="dialogs#default-action-and-escape">dialogs</link>, or any other temporary mode or UI element.

</section>

</section>

<section id="access-keys">

<title>Access keys</title>

Access keys allow someone to operate labelled controls by using <key>Alt</key>. They are indicated by an underlined letter within each control label (this is displayed when <key>Alt</key> is held down).

<list>

<item>
Where possible, all labelled components should have an access key.
</item>

<item>
Choose access keys that are easy to remember. Normally this means using the first letter of the label. If the label has more than one word, the first letter of one of its other words can also be used. Additionally, if another letter provides a better association (for example: “x” in “Extra Large”) , consider using that letter instead.
</item>

<item>
Avoid assigning access keys to “thin” letters (such as lowercase i or l), or letters with descenders (such as lowercase g or y), unless it is unavoidable. The underline is sometimes not as clear with these characters.
</item>

<item>
If the choice of access keys is difficult, assign access keys to the most frequently-used controls first. If the first letter is not available, choose an easy to remember consonant from the label, for example, “p” in “Replace”. Only assign vowels once no consonants are available.
</item>

<item>
Be aware that access keys have to be translated together with the strings that they are taken from, so even if there are no conflicts in your native language, they may occur in translations.
</item>

</list>

</section>

<section id="shortcut-keys">

<title>Shortcut keys</title>

Shortcut keys provide convenient access to common operations. They can be either single keys or combinations of several key presses (typically a modifier in combination with a regular key)

<list>

<item>
Do not assign system-level shortcut keys for use in your application. See below for details on these.
</item>

<item>
Use the standard GNOME shortcut keys (see below) if your application supports those functions. This ensures consistency between GNOME applications and aids discoverability.
</item>

<item>
Assign shortcut keys to the most commonly-used actions in your application. However, do not try to assign a keyboard shortcut to everything.
</item>

<item>
Try to use <key>Ctrl</key> in combination with a letter for your own shortcuts. <keyseq><key>Shift</key><key>Ctrl</key></keyseq> and a letter is the recommended pattern for shortcuts that reverse or extend another function. For example, <keyseq><key>Ctrl</key><key>Z</key></keyseq> and <keyseq><key>Shift</key><key>Ctrl</key><key>Z</key></keyseq> for <gui>Undo</gui> and <gui>Redo</gui>.
</item>

<item>
New shortcut keys should be as mnemonic as possible, as these will be easier to learn and remember. For example, <keyseq><key>Ctrl</key><key>E</key></keyseq> would be a good shortcut for a menu item called <gui>Edit Page</gui>.
</item>

<item>
Shortcuts that can be easily used with one hand are preferable for common operations.
</item>

<item>
Do not use <key>Alt</key> for shortcut keys, as this may conflict with access keys.
</item>

</list>

</section>

<section id="system-shortcuts">

<title>System reserved shortcuts</title>

The following system shortcuts should not be overridden by applications.

GNOME 3 makes exclusive use of <key>Super</key>, often known as the windows key, for system shortcuts.  <key>Super</key> should not be used by applications, therefore.

Function

Shortcut

Legacy Shortcut

Description

Activities Overview

<key>Super</key>

None

Opens and closes the Activities Overview

Applications View

<keyseq><key>Super</key><key>A</key></keyseq>

None

Opens and closes the applications view of the Activities Overview

Message Tray

<keyseq><key>Super</key><key>M</key></keyseq>

None

Toggles the visibility of the Message Tray.

Lock

<keyseq><key>Super</key><key>L</key></keyseq>

None

Locks the system by blanking the screen and requiring a password to unlock, if one has been set.

Switch application

<keyseq><key>Super</key><key>Tab</key></keyseq> and <keyseq><key>Shift</key><key>Super</key><key>Tab</key></keyseq>

<keyseq><key>Alt</key><key>Tab</key></keyseq> and <keyseq><key>Shift</key><key>Alt</key><key>Tab</key></keyseq>

Switches focus to the next/previous application

Switch windows

<keyseq><key>Super</key><key>`</key></keyseq> and <keyseq><key>Shift</key><key>Super</key><key>`</key></keyseq>

<keyseq><key>Alt</key><key>F6</key></keyseq> and <keyseq><key>Shift</key><key>Alt</key><key>F6</key></keyseq>

Switch focus to the next or previous secondary window associated with the application

<gui>Maximize</gui>

<keyseq><key>Super</key><key>↑</key></keyseq>

<keyseq><key>Alt</key><key>F10</key></keyseq>

Maximize the focused window

<gui>Restore</gui>

<keyseq><key>Super</key><key>↓</key></keyseq>

<keyseq><key>Alt</key><key>F5</key></keyseq>

Restores the focused window to its previous state

<gui>Hide</gui>

<keyseq><key>Super</key><key>H</key></keyseq>

<keyseq><key>Alt</key><key>F9</key></keyseq>

Hide the focused window

Switch system area

None

<keyseq><key>Ctrl</key><key>Alt</key><key>Tab</key></keyseq> and <keyseq><key>Shift</key><key>Ctrl</key><key>Alt</key><key>Tab</key></keyseq>

Switches focus to the primary areas of the system: windows, top bar, message tray

Power Off

None

<keyseq><key>Ctrl</key><key>Alt</key><key>Delete</key></keyseq>

Prompts the user to power off the system. This shortcut is typically disabled by default.

Window menu

<keyseq><key>Alt</key><key>Space</key></keyseq>

None

Opens the window menu for the current window

<gui>Close</gui>

None

<keyseq><key>Alt</key><key>F4</key></keyseq>

Closes the focused window

<gui>Move</gui>

None

<keyseq><key>Alt</key><key>F7</key></keyseq>

Move the focused window

<gui>Resize</gui>

None

<keyseq><key>Alt</key><key>F8</key></keyseq>

Resize the focused window

In addition, the shortcuts for Unicode character entry should also be avoided. This includes <keyseq><key>Shift</key><key>Ctrl</key><key>A</key></keyseq> through to <keyseq><key>Shift</key><key>Ctrl</key><key>F</key></keyseq>, or <keyseq><key>Shift</key><key>Ctrl</key><key>0</key></keyseq> through to <keyseq><key>Shift</key><key>Ctrl</key><key>9</key></keyseq>.

</section>

<section id="application-shortcuts">

<title>Standard application shortcuts</title>

This section details common application keyboard shortcuts. With the exception of application shortcuts, these shortcuts only need to be followed when the corresponding action is included in your application. Standard shortcuts can be assigned to other actions if the standard action is not available.

This section also provides guidance on standard menu items in a <link xref="menu-bars">menu bar</link>, should one be used.

<section id="application">

<title>Application</title>

Standard application keyboard shortcuts and menu items. These application shortcuts should not be reassigned to other actions, even when the corresponding action is not provided by your application.

Label

Shortcut

Description

<gui>Help</gui>

<key>F1</key>

Opens the default help browser on the contents page for the application.

<gui>About</gui>

None

Opens the About dialog for the application. Use the standard GNOME 3 dialog for this.

<gui>Quit</gui>

<keyseq><key>Ctrl</key><key>Q</key></keyseq>

Closes the application, including all application windows.

</section>

<section id="file">

<title>File</title>

Standard file keyboard shortcuts and menu items.

Label

Shortcut

Description

<gui>New</gui>

<keyseq><key>Ctrl</key><key>N</key></keyseq>

Creates a new content item, often (but not always) in a new primary window or tab. If your application can create a number of different types of document, you can make the <gui>New</gui> item a submenu, containing a menu item for each type. Label these items <gui>New</gui> document type, make the first entry in the submenu the most commonly used document type, and give it the <keyseq><key>Ctrl</key><key>N</key></keyseq> shortcut.

<gui>Open…</gui>

<keyseq><key>Ctrl</key><key>O</key></keyseq>

Opens an existing content item, often by presenting the user with a standard <gui>Open File</gui> dialog. If the chosen file is already open in the application, raise that window instead of opening a new one.

<gui>Open Recent</gui>

None

A submenu which contains a list of no more than six recently used files, ordered according to most recently used.

<gui>Save</gui>

<keyseq><key>Ctrl</key><key>S</key></keyseq>

Saves the current content item. If the document already has a filename associated with it, save the document immediately without any further interaction from the user. If there are any additional options involved in saving a file, prompt for these first time the document is saved, but subsequently use the same values each time until the user changes them. If the document has no current filename or is read-only, selecting this item should be the same as selecting <gui>Save As</gui>.

<gui>Save As…</gui>

<keyseq><key>Shift</key><key>Ctrl</key><key>S</key></keyseq>

Saves the content item with a new filename. Present the user with the standard <gui>Save As</gui> dialog, and save the file with the chosen file name.

<gui>Save a Copy…</gui>

None

Prompts the user to enter a filename, with which a copy of the document is then saved. Do not alter either the view or the filename of the original document. All subsequent changes are still made to the original document until the user specifies otherwise, for example by choosing the <gui>Save As</gui> command.

Like the <gui>Save As</gui> dialog, the <gui>Save a Copy</gui> dialog may present different ways to save the data. For example, an image may be saved in a native format or as a PNG.

<gui>Page Setup</gui>

None

Allows the user to control print-related settings. Present the user with a dialog allowing the user to set such options as portrait or landscape format, margins, and so on.

<gui>Print Preview</gui>

<keyseq><key>Shift</key><key>Ctrl</key><key>P</key></keyseq>

Shows the user what the printed document will look like. Present a new window containing an accurate representation of the appearance of the document as it would be printed.

<gui>Print…</gui>

<keyseq><key>Ctrl</key><key>P</key></keyseq>

Prints the current document. Present the user with a dialog allowing them to set options like the page range to be printed, the printer to be used, and so on. The dialog must contain a button labelled <gui>Print</gui> that starts printing and closes the dialog.

<gui>Send To…</gui>

<keyseq><key>Ctrl</key><key>M</key></keyseq>

Provides the user a means to attach or send the current document as an email or email attachment, depending on its format. You may provide more than one <gui>Send</gui> item depending on which options are available. If there are more than two such items, move them into a submenu. For example, if only <gui>Send by Email</gui> and <gui>Send by Bluetooth</gui> are available, leave them on the top-level menu. If there is a third option, such as <gui>Send by FTP</gui>, place all the options in a Send submenu.

<gui>Properties…</gui>

<keyseq><key>Alt</key><key>Return</key></keyseq>

Opens the document’s <gui>Properties</gui> window. This may contain editable information, such as the document author’s name, or read-only information, such as the number of words in the document, or a combination of both. The <keyseq><key>Alt</key><key>Return</key></keyseq> shortcut should not be provided where <key>Return</key> is most frequently used to insert a new line.

<gui>Close</gui>

<keyseq><key>Ctrl</key><key>W</key></keyseq>

Closes the current tab or window. If the window uses tabs and there is only one open, the shortcut should close the window.

</section>

<section id="edit">

<title itst:context="menu">Edit</title>

Standard edit keyboard shortcuts and menu items.

Label

Shortcut

Description

<gui>Undo action</gui>

<keyseq><key>Ctrl</key><key>Z</key></keyseq>

Reverts the effect of the previous action.

<gui>Redo action</gui>

<keyseq><key>Shift</key><key>Ctrl</key><key>Z</key></keyseq>

Performs the next action in the undo history list, after the user has moved backwards through the list with the <gui>Undo</gui> command.

<gui>Cut</gui>

<keyseq><key>Ctrl</key><key>X</key></keyseq>

Removes the selected content and places it onto the clipboard. Visually, remove the content from the document in the same manner as <gui>Delete</gui>.

<gui>Copy</gui>

<keyseq><key>Ctrl</key><key>C</key></keyseq>

Copies the selected content onto the clipboard.

<gui>Paste</gui>

<keyseq><key>Ctrl</key><key>V</key></keyseq>

Inserts the contents of the clipboard into the content item. When editing text, if there is no current selection, use the caret as the insertion point. If there is a current selection, replace it with the clipboard contents.

<gui>Paste Special…</gui>

<keyseq><key>Shift</key><key>Ctrl</key><key>V</key></keyseq>

Inserts a non-default representation of the clipboard contents. Open a dialog presenting a list of the available formats from which the user can select. For example, if the clipboard contains a PNG file copied from a file manager, the image may be embedded in the document, or a link to the file inserted so that changes to the image on disk are always reflected in the document.

<gui>Duplicate</gui>

<keyseq><key>Ctrl</key><key>U</key></keyseq>

Creates a duplicate copy of the selected object.

<gui>Delete</gui>

<key>Delete</key>

Removes the selected content without placing it on the clipboard.

<gui>Select All</gui>

<keyseq><key>Ctrl</key><key>A</key></keyseq>

Selects all content in the current document.

<gui>Deselect All</gui>

<keyseq><key>Shift</key><key>Ctrl</key><key>A</key></keyseq>

Deselects all content in the current document. Only provide this item in situations when no other method of undoing selection is possible or apparent to the user. For example, in complex graphics applications where selection and deselection is not usually possible simply by using the cursor keys. Note: Do not provide <gui>Deselect All</gui> in text entry fields, as <keyseq><key>Shift</key><key>Ctrl</key><key>hex</key></keyseq> digit is used to enter Unicode characters so its shortcut will not work.

<gui>Find…</gui>

<keyseq><key>Ctrl</key><key>F</key></keyseq>

Displays a user interface for allowing the user to search for specific content in the current content item or page.

<gui>Find Next</gui>

<keyseq><key>Ctrl</key><key>G</key></keyseq>

Selects the next instance of the last Find term in the current document.

<gui>Find Previous</gui>

<keyseq><key>Shift</key><key>Ctrl</key><key>G</key></keyseq>

Selects the previous instance of the last <gui>Find</gui> term in the current document.

<gui>Replace…</gui>

<keyseq><key>Ctrl</key><key>H</key></keyseq>

Displays a user interface allowing the user to find specific content and replace each occurrence.

</section>

<section id="view">

<title>View</title>

View keyboard shortcuts and menu items.

Label

Shortcut

Description

<gui>Icons</gui>

None

Shows content as a grid of icons. This is a radio button menu item.

<gui>List</gui>

None

Shows content as a list. This is a radio button menu item.

<gui>Sort By…</gui>

None

Specifies the criteria by which content should be sorted. Can open a preference dialog, popover, or sub-menu.

<gui>Filter…</gui>

None

Allows content to be filtered, by opening a popover, drop down, or dialog.

<gui>Zoom In</gui>

<keyseq><key>Ctrl</key><key>+</key></keyseq>

Zooms in, making content appear larger.

<gui>Zoom Out</gui>

<keyseq><key>Ctrl</key><key>-</key></keyseq>

Zooms out, making content appear smaller.

<gui>Normal Size</gui>

<keyseq><key>Ctrl</key><key>0</key></keyseq>

Resets the zoom level back to the default value.

<gui>Best Fit</gui>

None

Makes the document fill the window.

<gui>Reload</gui>

<keyseq><key>Ctrl</key><key>R</key></keyseq>

Redraws the current view of the document, checking the data source for changes first. For example, checks the web server for updates to the page before redrawing it.

</section>

<section id="format">

<title>Format</title>

Standard format keyboard shortcuts and menu items.

Label

Shortcut

Description

<gui>Style…</gui>

None

Sets the style attributes of the selected text or objects either individually or to a named, predefined style.

<gui>Font…</gui>

None

Sets the font properties of the selected text or objects.

<gui>Paragraph…</gui>

None

Sets the properties of the selected paragraph.

<gui>Bold</gui>

<keyseq><key>Ctrl</key><key>B</key></keyseq>

Toggles the boldness of the current text selection. If some of the selection is currently bold and some is not, this command should bolden the selected text.

<gui>Italic</gui>

<keyseq><key>Ctrl</key><key>I</key></keyseq>

Toggles the italicisation of the current text selection on or off. If some of the selection is currently italicized and some is not, this command should italicise the selected text.

<gui>Underline</gui>

<keyseq><key>Ctrl</key><key>U</key></keyseq>

Toggles underlining of the current text selection. If some of the selection is currently underlined and some is not, this command should underline the selected text.

<gui>Cells…</gui>

None

Sets the properties of the selected table cells.

<gui>List…</gui>

None

Sets the properties of the selected list, or turns the selected paragraphs into a list if they are not already formatted as such.

<gui>Layer…</gui>

None

Sets the properties of all or selected layers of a multi-layered document.

<gui>Page…</gui>

None

Sets the properties of all or selected pages of the document.

</section>

<section id="bookmarks">

<title>Bookmarks</title>

Standard bookmark keyboard shortcuts and menu items.

Label

Shortcut

Description

<gui>Add Bookmark</gui>

<keyseq><key>Ctrl</key><key>D</key></keyseq>

Adds a bookmark for the current location. Do not pop up a dialog asking for a title or location for the bookmark, instead choose sensible defaults (such as the document’s title or filename as the bookmark name) and allow the user to change them later using the <gui>Edit Bookmarks</gui> feature.

<gui>Edit Bookmarks</gui>

<keyseq><key>Ctrl</key><key>B</key></keyseq>

Allows the user to edit their bookmarks.

Bookmark List

None

Displays the user’s bookmarks.

</section>

<section id="go">

<title>Go</title>

Standard navigation keyboard shortcuts and <gui>Go</gui> menu items.

Label

Shortcut

Description

<gui>Back</gui>

<keyseq><key>Alt</key><key>Left</key></keyseq>

Navigates to the previous location.

<gui>Forward</gui>

<keyseq><key>Alt</key><key>Right</key></keyseq>

Navigates to the next location in the navigation history.

<gui>Up</gui>

<keyseq><key>Alt</key><key>Up</key></keyseq>

Navigates to the parent content item, document, page or section.

<gui>Home</gui>

<keyseq><key>Alt</key><key>Home</key></keyseq>

Navigates to a starting page defined by the user or the application.

<gui>Location…</gui>

<keyseq><key>Ctrl</key><key>L</key></keyseq>

Allows the user to specify a URI to navigate to.

<gui>Previous Page</gui>

<key>PageUp</key>

Navigates to the previous page in the document.

<gui>Next Page</gui>

<key>PageDown</key>

Navigates to the next page in the document.

<gui>Go to Page…</gui>

None

Allows the user to specify a page number to be navigated to. Text-based applications may also include a <gui>Go to Line…</gui> menu item, which allows the user to jump to a specified line number.

<gui>First Page</gui>

<keyseq><key>Ctrl</key><key>Home</key></keyseq>

Navigates to the first page in the document.

<gui>Last Page</gui>

<keyseq><key>Ctrl</key><key>End</key></keyseq>

Navigates to the last page in the document.

</section>

<section id="windows">

<title>Windows</title>

Standard <gui>Windows</gui> menu items.

Label

Shortcut

Description

<gui>Save All</gui>

None

Saves all open documents. If any documents have no current filename, prompt for a filename for each one in turn using the standard <gui>Save</gui> dialog.

<gui>Close All</gui>

None

Closes all open documents. If there are any unsaved changes in any documents, post a confirmation alert for each one in turn.

List of windows

None

Each menu item raises the corresponding window to the top of the window stack.

</section>

</section>

</page>