Difference between revisions of "GUI Guidelines"
m (→Mnemonics and Accelerators: recode HTML to wiki tags) |
m (→Mnemonics and Accelerators: 1 level down) |
||
Line 24: | Line 24: | ||
;Ellipses: If a label ''specifies an action'', but further user interaction is required before, the label should have a trailing horizontal ellipse <tt>…</tt> (<code>altGr</code>+<code>.</code>), but not for dialogs like <tt>Properties</tt>, <tt>Preferences</tt>… See details at the bottom of https://developer.gnome.org/hig/stable/writing-style.html | ;Ellipses: If a label ''specifies an action'', but further user interaction is required before, the label should have a trailing horizontal ellipse <tt>…</tt> (<code>altGr</code>+<code>.</code>), but not for dialogs like <tt>Properties</tt>, <tt>Preferences</tt>… See details at the bottom of https://developer.gnome.org/hig/stable/writing-style.html | ||
− | == Mnemonics and Accelerators == | + | === Mnemonics and Accelerators === |
Gtk+ provides two means of creating "hot-keys" for keyboard operation of menu items and controls: [https://developer.gnome.org/gtk3/unstable/gtk3-Keyboard-Accelerators.html Accelerators] and special labels called '''mnemonics'''. | Gtk+ provides two means of creating "hot-keys" for keyboard operation of menu items and controls: [https://developer.gnome.org/gtk3/unstable/gtk3-Keyboard-Accelerators.html Accelerators] and special labels called '''mnemonics'''. | ||
− | === Accelerators === | + | ==== Accelerators ==== |
Accelerators are normally assigned only to menu items, but they can be assigned to any control using a [https://developer.gnome.org/gtk3/unstable/GtkAccelLabel.html GtkAccelLabel]. ''"Can" does '''not''' mean "should"!'' Pressing the character together with the configured modifiers calls whatever function is linked to the control. Accelerators can be over-ridden by users using [https://developer.gnome.org/gtk3/unstable/gtk3-Accelerator-Maps.html an accelerator map]. Accelerators can be set in GtkBuilder/Glade files using the <tt>accelerator</tt> element. | Accelerators are normally assigned only to menu items, but they can be assigned to any control using a [https://developer.gnome.org/gtk3/unstable/GtkAccelLabel.html GtkAccelLabel]. ''"Can" does '''not''' mean "should"!'' Pressing the character together with the configured modifiers calls whatever function is linked to the control. Accelerators can be over-ridden by users using [https://developer.gnome.org/gtk3/unstable/gtk3-Accelerator-Maps.html an accelerator map]. Accelerators can be set in GtkBuilder/Glade files using the <tt>accelerator</tt> element. | ||
Line 36: | Line 36: | ||
::Gtk+-3.18 for GnuCash 4.x, so don't implement it now. | ::Gtk+-3.18 for GnuCash 4.x, so don't implement it now. | ||
− | === Mnemonics === | + | ==== Mnemonics ==== |
Mnemonics can be set on [https://developer.gnome.org/gtk3/unstable/GtkMenuItem.html#gtk-menu-item-new-with-mnemonic menu items] as well as [https://developer.gnome.org/gtk3/unstable/GtkButton.html#gtk-button-new-with-mnemonic buttons] or indeed any control by [https://developer.gnome.org/gtk3/unstable/GtkLabel.html#gtk-label-set-mnemonic-widget attaching] it to the [https://developer.gnome.org/gtk3/unstable/GtkLabel.html#gtk-label-new-with-mnemonic relevant label]. ''However'' one should be aware that menu-item mnemonics work quite differently: Mnemonics on controls operate like accelerators: Holding <code>alt</code> will reveal underlines on the mnemonic characters for the focused window or dialog and pressing an underlined character will operate the respective control. If the focused window has a menu bar associated with it the menu bar will be revealed if it's hidden and the mnemonics will be shown; pressing the mnemonic for a menu bar item will open that menu. At this point the <code>alt</code> can be released and the menu navigated by pressing the mnemonic keys alone. In addition to the linked functions, mnemonics can be set in GtkBuilder/Glade files with the <tt>use_underline</tt> and (on GtkLabels, not needed for GtkButtons) <tt>mnemonic_widget</tt> properties. | Mnemonics can be set on [https://developer.gnome.org/gtk3/unstable/GtkMenuItem.html#gtk-menu-item-new-with-mnemonic menu items] as well as [https://developer.gnome.org/gtk3/unstable/GtkButton.html#gtk-button-new-with-mnemonic buttons] or indeed any control by [https://developer.gnome.org/gtk3/unstable/GtkLabel.html#gtk-label-set-mnemonic-widget attaching] it to the [https://developer.gnome.org/gtk3/unstable/GtkLabel.html#gtk-label-new-with-mnemonic relevant label]. ''However'' one should be aware that menu-item mnemonics work quite differently: Mnemonics on controls operate like accelerators: Holding <code>alt</code> will reveal underlines on the mnemonic characters for the focused window or dialog and pressing an underlined character will operate the respective control. If the focused window has a menu bar associated with it the menu bar will be revealed if it's hidden and the mnemonics will be shown; pressing the mnemonic for a menu bar item will open that menu. At this point the <code>alt</code> can be released and the menu navigated by pressing the mnemonic keys alone. In addition to the linked functions, mnemonics can be set in GtkBuilder/Glade files with the <tt>use_underline</tt> and (on GtkLabels, not needed for GtkButtons) <tt>mnemonic_widget</tt> properties. | ||
Revision as of 20:57, 31 October 2020
This page collects rules for the GUI. You should mind them while coding or preparing translation (I18N).
GUI Resolution
The maximum size of all GUI elements restricts users to have at least the same resolution on their device to run GnuCash flawless. Bug 797857 - Edit->Preferences: Help/Close buttons unreachable remembered us about this restriction. For
- GnuCash 3 and up
- the limit is 1024x768. In the
- GnuCash 2.x series
- it was 800x600.
GUI Elements
Buttons and Icons
For GTK+ 3.10 Stock Items Deprecation announced on gtk-devel-list/2013-July and the Replacement Table watch the current discussion starting with gnucash-devel/2019-May.
Standard icons are now specified in the XDG Icon Naming Specification. This will allow each theme to use its own set.
Toolbars
Keep often used actions like Report options at the beginning of the list.
Menus
Menu elements should have a
- Ellipses
- If a label specifies an action, but further user interaction is required before, the label should have a trailing horizontal ellipse … (
altGr
+.
), but not for dialogs like Properties, Preferences… See details at the bottom of https://developer.gnome.org/hig/stable/writing-style.html
Mnemonics and Accelerators
Gtk+ provides two means of creating "hot-keys" for keyboard operation of menu items and controls: Accelerators and special labels called mnemonics.
Accelerators
Accelerators are normally assigned only to menu items, but they can be assigned to any control using a GtkAccelLabel. "Can" does not mean "should"! Pressing the character together with the configured modifiers calls whatever function is linked to the control. Accelerators can be over-ridden by users using an accelerator map. Accelerators can be set in GtkBuilder/Glade files using the accelerator element.
- macOS Note
- In most cases macOS prefers the
command
key to thecontrol
key as a modifier. Gtk provides a macro GDK_MODIFIER_INTENT_PRIMARY_ACCELERATOR that selects the correct modifier depending on OS. It should be used in most cases rather than GDK_CONTROL_MASK. As noted below under Mnemonics macOS uses thealt
modifier key to extend the keyboard, so it should be used only with another not-shift
modifier key in accelerators. Note that on macOS GDK_MOD2_MASK is thecommand
key while on X11 it'snumlock
so either one must conditionally set accelerator modifiers (not possible in Glade), rely on an accelerator map to get a useable accelerator set, or restrict the modifiers tocontrol
+alt
and GDK_MODIFIER_INTENT_PRIMARY_ACCELERATOR. Unfortunately Glade does not support GdkModifierIntent and Gtk+ has supported it in GtkBuilder files only since 3.20 so it can be used only in accelerators defined in code.
- GtkShortcuts
- The GtkShortcutsWindow is a convenient way to display all of GnuCash's accelerators to the user. Unfortunately it wasn't introduced until Gtk+-3.20.0 and we want to support
- Gtk+-3.10 for GnuCash 3.x and
- Gtk+-3.18 for GnuCash 4.x, so don't implement it now.
Mnemonics
Mnemonics can be set on menu items as well as buttons or indeed any control by attaching it to the relevant label. However one should be aware that menu-item mnemonics work quite differently: Mnemonics on controls operate like accelerators: Holding alt
will reveal underlines on the mnemonic characters for the focused window or dialog and pressing an underlined character will operate the respective control. If the focused window has a menu bar associated with it the menu bar will be revealed if it's hidden and the mnemonics will be shown; pressing the mnemonic for a menu bar item will open that menu. At this point the alt
can be released and the menu navigated by pressing the mnemonic keys alone. In addition to the linked functions, mnemonics can be set in GtkBuilder/Glade files with the use_underline and (on GtkLabels, not needed for GtkButtons) mnemonic_widget properties.
- Mnemonics have two problems on Macs
- First, they don't work on the menu. Keyboard menu navigation is accomplished by pressing
ctrl
+F2
(don't forget to also pressfn
on keyboards that use one unless you've flipped thefn
key behavior in Keyboard Preferences) to activate the menubar and then navigating with the cursor keys. - Second, macOS used the
alt
key to extend the keyboard; for example on a US keyboard one would typealt
+e
to get é oralt
+o
to get ø. Setting a mnemonic will grab the event before the text control gets it and prevent that character from being typed.
Note that when one creates a mnemonic with an underscore the underscore becomes part of the label string that is a msgid for translation, so the same label with different mnemonics will result in multiple strings for translation. This is a good thing because it allows translators to select appropriate mnemonics for their languages.
Textual content
Menu Entry Descriptions
Sometimes you need to describe menu entries in other texts like tool tips, tip of the day, ...
In that case use "->" without spaces as separator of the levels.
- Example
- "File->Open…"
Avoid "->" for other contexts like
- range
- "1 … 10, A … Z" or
- conversion
- "commodity -> currency" or "number to string".
Quoting in Strings
To get a unique appearance, the current team prefers ASCII double quotes "
over single quotes '
or non-ASCII characters.
- So developers should use in C etc.
-
Msg= "Prefix \"Quotation\" Suffix."
- In XML it is more complex
-
- Glade
-
<tag>Prefix "Quotation" Suffix.</tag>
- DocBook
- For attributes:
<sometag someattribute="value">Text</sometag>
- In text:
<p>Prefix <quote>Quotation</quote> Suffix.</p>
- Note
- Depending on the semantic context there are more appropriate markups like <citation>, <guilabel>, <keycap>, ...
- HTML has several, depending on the context
-
<p>Inline: normal <q>Quotation</q>, <code>Computer code</code> and <kbd>Keyboard input</kbd>. <em>Emphasis</em> and <strong>Strong</strong> should be preferred over <i>idiomatic</i> and <b>Bold</b>.</p> <blockquote>A text over several lines </blockquote>
Translation teams are free to choose their locale common symbols as shown in Quotation mark.
- Tip
- Best practice is to note the convention in a comment in the header of the .po file.
Tooltips and Descriptions of Preferences
Tooltips should contain at least one full sentence.
- Purpose
-
- Describe the impact of the GUI element,
- give the user a clue about the "normal" state.
The separator between menu elements is "->" like "Menu->SubMenu->MenuItem".
- Tooltips of preferences
- have usually 3 occurences:
- glade: Edit->Preferences->...
<property name="tooltip_text" translatable="yes">your text</property>
- gschema (xml), displayed in RegEdit, dconf-editor, ...:
<description>your text</description>
- gnucash-help/custom-gnucash... (docbook xml):
<listitem> <para><guilabel>Include grand total</guilabel>: If checked, show in the <emphasis>Summarybar</emphasis> a grand total of all accounts converted to the default currency.</para> </listitem>
You are in a maze of twisty little passages, all alike.
You are in a maze of twisty little passages, all different.
You are in a little maze of twisty passages, all different.
You are in a little maze of twisting passages, all different.
:
Reference
Human Interface Guidelines
As long as we use GTK, GNOMEs HIG is the primary source. But sometimes the comparision with other HIGs, can be useful: