GNOME Goal: Shortcut Windows

GTK+ 3.19.x includes a new widget called GtkShortcutsWindow. This is a dialog window that shows an overview of shortcuts (keyboard shortcuts and touch gestures) for an application. They are particularly useful when an application doesn't include a menubar (since these were the primary way to learn shortcuts in the past).

Shortcuts windows will be far more effective if GNOME applications consistently provide them. This goal aims to make sure that every GNOME application without a menu bar has one.

Guidelines

If an application has more than a few shortcuts, and doesn't have a menu bar, it should include a shortcuts window.

GTK+ 3 Demo provides examples of different shortcuts windows. Guidance and screenshots can also be found in the documentation and in the GtkApplication documentation.

Which shortcuts to include

  • Include all application-specific shortcuts and gestures.
  • Include system-wide gestures that are defined by either the system or the application, such as F1 for help and Ctrl+N for new.
  • It isn't necessary to describe generic keyboard controls such as Esc to close dialogs or Tab to move focus.
  • Don't forget to include the shortcuts for raising the shortcuts window: Ctrl+? and Ctrl+F1.

Organizing the shortcuts

Group the shortcuts in order to make them easy to read and find.

  • When grouping shortcuts, avoid small and large groups. As a rule of thumb, groups should be 3 - 8 items in size.
  • Often it is necessary to include a General group, containing shortcuts such as Ctrl+N, Ctrl+W, and F1. If included, this should be the first group.
  • Order items within groups so that similar items are adjacent to one another.
  • Each group should be listed in order of importance/frequency of use.
  • You might find it helpful to think of groups in terms of common menu bar titles: Edit, View, Go and Tabs, for example.
  • Use header capitalization for group headings.

There are two other ways that you can organize the shortcuts in a Shortcuts Window:

  • If your application provides a series of fixed views (like Clocks or Software), and each view has different shortcuts associated with them, organize the shortcuts into different views.
  • If the application has several modes, each of which have a large number of shortcuts associated with them (this is only found in large and complex applications, like Evolution), they can be divided into sections.

Gestures

Note that the GTK+ API for shortcuts and gestures has changed slightly after 3.19.2: The GtkShortcutsShortcut widget can now be used to display both keyboard shortcuts and gestures, and it has a list of predefined gestures for which GTK+ provides both an icon and a subtitle. The GtkShortcutsGesture widget should not be used anymore; it will be removed before 3.20.

General guidelines

  • Try to be consistent with other applications in the naming of shortcuts.
  • Try to avoid awkward layouts with large spaces, by adjusting the window height and tweaking the order of the shortcut groups.
  • A Keyboard Shortcuts entry should be added to the application menu for it, above the Help entry. GTK+ automatically creates and action with name win.show-help-overlay that can be used for this.

/!\ Note: every translatable string in the Shortcuts Window (usually the help-overlay.ui file) should have the context="shortcut window" attribute set to disambiguate the strings from other strings in the app in order to help translators.

Comments before approval

Add your comments to this goal proposal here

Status of this goal

Tip: If you choose to work on a module, create the bug report on the GNOME bugzilla for the relevant module, and link to it from this page. This way people will know someone already works on it, and won't duplicate the work you're doing.

Patch Status

Markup

to do

<: #ff8080 > to do

patch

<: #ffcc50> [[GnomeBug:xxxxx|patch]]

done

<: #80ff80> [[GnomeBug:xxxxx|done]]

not needed

<: #80ff80> not needed

Above are the states and corresponding markup to update the modules state table below.

Tarball

Status

core

adwaita-icon-theme

not needed

at-spi2-core

not needed

at-spi2-atk

not needed

dconf

not needed

evolution-data-server

not needed

glib-networking

not needed

gnome-bluetooth

not needed

gnome-online-accounts

not needed

gnome-control-center

done

gnome-desktop

not needed

gnome-keyring

not needed

gnome-menus

not needed

gnome-packagekit

not needed

gnome-power-manager

not needed

gnome-screensaver

not needed

gnome-session

not needed

gnome-settings-daemon

not needed

gnome-shell

to do

gnome-themes-standard

not needed

gsettings-desktop-schemas

not needed

gvfs

not needed

mousetweaks

not needed

mutter

not needed

network-manager-applet

not needed

pulseaudio

not needed

telepathy-mission-control

not needed

core-utilities

baobab

to do

brasero

to do

empathy

to do

eog

done

epiphany

to do

evince

done

gnome-calculator

done

gnome-contacts

to do

gnome-dictionary

to do

gnome-disk-utility

to do

gnome-font-viewer

to do

gnome-logs

done

gnome-screenshot

not needed

gnome-search-tool

not needed

gnome-system-log

not needed

gnome-system-monitor

to do

gnome-terminal

to do

gucharmap

not needed

nautilus

done

sushi

not needed

yelp

to do

core-extras

gnome-backgrounds

not needed

gnome-user-share

not needed

vino

not needed

gnome-user-docs

not needed

core-fallback

GConf

not needed

gnome-panel

not needed

metacity

not needed

notification-daemon

not needed

core-os-services

accountservice

not needed

avahi

not needed

ConsoleKit

not needed

dbus

not needed

gdm

not needed

NetworkManager

not needed

PackageKit

not needed

polkit

not needed

upower

not needed

core-deps

atk

not needed

atkmm

not needed

cairo

not needed

cairomm

not needed

cantarell-fonts

not needed

caribou

not needed

clutter

not needed

clutter-gtk

not needed

clutter-gst

not needed

cogl

not needed

dbus-glib

not needed

dbus-python

not needed

desktop-file-utils

not needed

enchant

not needed

expat

not needed

farsight2

not needed

folks

not needed

fontconfig

not needed

gamin

not needed

gnome-js-common

not needed

gtksourceview

not needed

gdk-pixbuf

not needed

gjs

not needed

glib

not needed

glibmm

not needed

gmime

not needed

gnome-doc-utils

not needed

gnome-video-effects

not needed

gnutls

not needed

gobject-introspection

not needed

gst-plugins-base

not needed

gst-plugins-good

not needed

gst-plugins-farsight

not needed

gstreamer

not needed

gtk+

not needed

gtk-doc

not needed

gtkmm

not needed

gudev

not needed

hicolor-icon-theme

not needed

icon-naming-utils

not needed

iso-codes

not needed

itstool

not needed

intltool

not needed

java-gnome

not needed

js185

not needed

json-glib

not needed

libatasmart

not needed

libcanberra

not needed

libchamplain

not needed

libcroco

not needed

libdaemon

not needed

libdiscid

not needed

libgpg-error

not needed

libgcrypt

not needed

libgee

not needed

libgdata

not needed

libgnome-keyring

not needed

libgnomekbd

not needed

libgsf

not needed

libgtop

not needed

libgweather

not needed

libical

not needed

libmusicbrainz

not needed

libnice

not needed

libnotify

not needed

liboauth

not needed

libpeas

not needed

libproxy

not needed

librest

not needed

librsvg

not needed

libsigc++2

not needed

libsndfile

not needed

libsoup

not needed

libtasn1

not needed

libwnck

not needed

libxklavier

not needed

libxml2

not needed

libxslt

not needed

mm-common

not needed

nspr

not needed

nss

not needed

p11-kit

not needed

pango

not needed

pangomm

not needed

pixman

not needed

polkit-gnome

not needed

poppler

not needed

py2cairo

not needed

pygobject

not needed

rarian

not needed

seed

not needed

shared-mime-info

not needed

sound-theme-freedesktop

not needed

speex

not needed

sqlite3

not needed

startup-notification

not needed

telepathy-glib

not needed

telepathy-logger

not needed

telepathy-farsight

not needed

totem-pl-parser

not needed

tracker

not needed

vala

not needed

vte

not needed

webkit

not needed

yelp-tools

not needed

yelp-xsl

not needed

zenity

not needed

libnl

not needed

lcms2

not needed

colord

not needed

apps

accerciser

not needed

aislerot

to do

anjuta

not needed

banshee

to do

bijiben

to do

cheese

to do

d-feet

to do

dconf-editor

done

devhelp

done

evolution

to do

file-roller

to do

five-or-more

not needed

four-in-a-row

not needed

frogr

not needed

gedit

done

ghex

not needed

gitg

done

glade

to do

gnome-boxes

done

gnome-calendar

done

gnome-characters

to do

gnome-chess

not needed

gnome-clocks

done

gnome-color-manager

not needed

gnome-devel-docs

not needed

gnome-documents

done

gnome-klotski

not needed

gnome-mahjongg

not needed

gnome-maps

done

gnome-mines

not needed

gnome-music

to do

gnome-nettool

not needed

gnome-nibbles

not needed

gnome-photos

done

gnome-robots

not needed

gnome-sudoku

not needed

gnome-tetravex

not needed

gnome-tweak-tool

not needed

gnome-weather

to do

gtranslator

not needed

iagno

not needed

lightsoff

not needed

nautilus-sendto

not needed

nemiver

not needed

orca

not needed

polari

done

quadrapassel

not needed

rhythmbox

to do

rygel

not needed

seahorse

to do

simple-scan

to do

swell-foop

not needed

tali

not needed

totem

done

vinagre

to do

gnome-builder

done

Initiatives/GnomeGoals/ShortcutWindows (last edited 2016-10-20 06:50:11 by RobertRoth)