GNOME Goal: Shortcut Windows

$/!\$ Warning:
This page is deprecated and no goals should be added/modified here. Please visit https://gitlab.gnome.org/GNOME/Initiatives for more information. Thanks!

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