View source for UI Style Guide Keyboard

[[Category:User Interface Style Guide]]
== The Keyboard ==

Your application should make gadget and menu items selectable with the keyboard as well as with the mouse. Often these keyboard equivalents ("hotkeys") will provide shortcuts and a smoother workflow that is appreciated by the user. Also, allowing the choice conforms to the Amiga credo: "Power to the User".

The set of conventions you should follow to implement this style rule are presented in this section.

== Keyboard Conventions ==

The arrangement of the Amiga's keyboard varies from model to model, but in general there are always three sets of keys:
* the standard keyboard
* special keys
* modifier keys

=== The Standard Keyboard ===

The standard keys consist of the familiar alphanumeric keys found on any standard typewriter. (In English, this is referred to as the QWERTY keyboard, but in German, since the standard keys are arranged differently, it's known as the QWERTZ keyboard. It's called other names in other languages.)

The actual arrangement of the standard keys can vary. To handle this, AmigaOS uses a special facility known as a keymap that allows the user to change the way the keyboard input is mapped so it will correspond to his country's keyboard layout and characters. For example, to access all the standard German ASCII characters the user can type "SetKeyboard d" in the Shell. Then German characters such as ü and ß will have the same key designations as they do on a standard German keyboard.

Use the keymap facility to handle key assignments on the standard keyboard.

=== Special Keys ===

The special keys include the function keys on the top row of your computer's keyboard, the Help key, the cursor (arrow) keys, the Del key, the backspace key and the Esc key.

=== Modifier Keys ===

The modifier keys are the Ctrl, Shift, Alt and Amiga keys found on either side of the space bar. Modifier keys don't do anything by themselves; they alter the meaning of a key that is pressed at the same time. They are also used to modify the meaning of a mouse selection. For example, holding down the Shift key while clicking with the mouse is used for multiple object selection.

==== Dead Keys ====

A "dead" key is a key, or combination, that does nothing immediately but modifies the output of the next key. For example, on an American keyboard, Alt-H will superimpose a caret (^) symbol over the next appropriate character.

Although relatively unimportant on the American keyboard, dead keys are important in many languages. Keep in mind that you need to work these in manually if you're doing your own raw key mapping.

== System Keyboard Shortcuts ==

To provide mouse functions from the keyboard, only three features a needed: a way to press the left mouse button, a way to press the right mouse button, and a way to move the mouse pointer. These are provided by the system. They are listed here so you are aware of them and can avoid using these key combinations for any other purpose.

{| class="wikitable"
! Keyboard Shortcut
! Equivalent Mouse Activity
|-
| Either Amiga + Left-Alt
| Same as clicking left mouse button
|-
| Either Amiga + Right-Alt
| Same as clicking right mouse button
|-
| Either Amiga + Cursor Key
| Moves mouse pointer
|-
| Either Amiga + Shift + Cursor Key
| Moves mouse pointer in larger steps
|}

Five additional Amiga system functions have keyboard shortcuts:

{| class="wikitable"
! Default Keyboard Shortcut
! Equivalent System Function
|-
| Left-Amiga + N
| Workbench screen to front
|-
| Left-Amiga + M
| Front screen to back
|-
| Left-Amiga + B
| Requester OK (leftmost gadget)
|-
| Left-Amiga + V
| Requester Cancel (rightmost gadget)
|-
| Left-Amiga + selection button
| Drags screen whether the pointer is on the title bar or not
|}

The first four functions listed above always use Left-Amiga in combination with another key. The second key in the combination can be changed by the user with the IControl preferences editor in your AmigaOS Prefs drawer. For the screen dragging shortcut, the user can change the modifier or combination of modifiers (Ctrl, Amiga, Shift, Alt) that need to be combined with the selection button.

===  The Left-Amiga Key ===

Keep in mind that the Left-Amiga key is reserved at all times for system operations and should never be used as a qualifier for an application keyboard shortcut!

== Application Keyboard Shortcuts ==

Your application should provide a way for the user to bind an application function or ARexx macro to a key or combination of keys. Keyboard access to program features and common functions can speed up workflow significantly.

On the other hand, it’s not necessary to provide hotkeys for every single function in your program: the user wouldn’t be able to remember them anyway. Plus, keyboard shortcuts work best if they are mnemonic and logical: S for Save, P for Print, etc. Therefore, save handy mnemonics for common and really important functions, don't waste them on secondary features.

Prefer common character keys for shortcuts: if possible, avoid punctuation characters like brackets, quotation marks, the exclamation mark, the slash, the apostrophe, the tilde etc. While easily accessible with the English keymap, in certain languages the keymap will bind these characters with a qualifier key, making them more difficult to access. This is especially true of the [[#Menus|menu shortcuts]] where the Right Amiga key is also required: the user would then have to press two qualifiers plus the respective character key. If your application implements many functions and you need to resort to using punctuation-based shortcuts, make sure you assign them to less commonly used functions.

If you provide a hotkey for an operation that can be dangerous (such as format disk or delete-type operations), make sure the user will get the opportunity to confirm or cancel the action should he/she make an inadvertent key press. The general rule of application design is: never put the user's data at stake!

=== Gadgets ===

Place an underscore under the letter in the gadget label that activates the gadget. (Note: although the letter is capitalized on the label, the
default action should react to the lower-case letter. Some Intuition gadgets have a different action for the shifted version of the letter. See the list in the table below.)

The following three rules should apply:

* All action should occur on the down press of the key.
* The same visual feedback should be given for keyboard activation as is given for mouse activation.
* Avoid assigning the Enter key to a gadget.

'''Feedback from Keystroke-Activated Gadgets'''

{| class="wikitable"
| Action button
| On the down press of the key, the gadget should appear to be pressed in. On release of the key, the gadget should come back out. (Note: at the time this manual was published, GadTools did not support this function.)
|-
| Check box
| Toggle the state of the check mark.
|-
| Scrolling list
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Radio button
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Cycle gadget
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Selection gadget
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Scroll gadget
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Slider
| Unshifted would increase the level by one unit. Shifted would decrease the level by one unit.
|-
| Text box
| Activate the gadget for entry.
|-
| Numeric entry
| Activate the gadget for entry.
|}

=== Menus ===

Use a Right-Amiga combination as the default keyboard shortcut for a menu item. Here is a list of recommended hotkeys for common functions found in an application's menus:

 Project Menu
  Right-Amiga + N  New
  Right-Amiga + O  Open...
  Right-Amiga + S  Save
  Right-Amiga + A  Save As...
  Right-Amiga + P  Print
  Right-Amiga + ?  About...
  Right-Amiga + Q  Quit Program

 Edit Menu
  Right-Amiga + X  Cut
  Right-Amiga + C  Copy
  Right-Amiga + V  Paste
  Right-Amiga + Z  Undo

Some of these (namely: N for New, O for Open, S for Save, P for Print, and the four Edit Menu shortcuts) are de facto cross-platform standards, and should therefore be respected as such. On the other hand, the choice of suitable keys is limited so a particular “standard” shortcut may certainly be reused if the application does not implement the respective function. For example, an application that does not print or cannot create new projects (such as a music player) can use the Right-Amiga+N and Right-Amiga+P combination for something else.

The original User Interface Style Guide suggested in this section that menu shortcuts should be [[Locale_Library|localized]] to reflect the user's preferred language as set in the system. This recommendation has turned out to be rather short-sighted and impractical: certain hotkeys like the ones listed above are so common, universal and "dyed in the wool" that changing them based on the currently selected locale would only be confusing. Also remember that unlike in gadgets, where the user can see the actual shortcut (it is underscored in the gadget label), you get no direct visual cue when using menu hotkeys because they are hidden in the menu. Thus, a menu hotkey could potentially be dangerous if the user pressed a known key combination that has suddenly changed meaning due to locale change.

=== Requesters ===

Hotkeys for requester buttons should also be provided. Requesters require user interaction: they "get in the way" and can slow down workflow. The user would therefore appreciate requester buttons having keyboard shortcuts (unless there’s a good reason not to provide them, such as safety of operation).

== Use of the Special Keys ==

As stated previously, the special keys are the function keys, the Del key, the Help key, the cursor (arrow) keys and the Esc key.

=== Cursor Keys ===

Cursor keys are a convenient way to control the movement of the cursor inside an application. Here are some standard ways to use them:

==== Unmodified Cursor ====

Move a small amount in the specified direction. Often this is one unit such as a character in a word processor or a pixel in a paint package, but it could be several pixels in an application where navigation is more important than fine control.

==== Shift + Cursor ====

Move to the appropriate extreme of the window, or shift the view by one window full if you're already at that extreme.

In applications such as a word processor where the two directions are not symmetrical, shifted cursor keys could take on different meanings. Shifted up and down cursors would page through windowfuls while the shifted left and right cursors would show more on the left and right if there is more to show. Of course it is often the case that the width of the document fits in the window, so the shifted left and right cursors could act as beginning-and end-of-line commands (or edge of window if the cursor isn't constrained to the form of the text).

==== Alt-Cursor ====

This is used for application-specific functions. It's usually semantic units such as words in a text processor or fields in a spreadsheet.

==== Ctrl-Cursor ====

Move to the appropriate extreme of the project (beginning, end, extreme left, extreme right).

In the word processor example, the up and down cursor keys would take the cursor to the beginning and end of the file, respectively. But again, if the file fits within the width of the window, the left and right cursor keys combined with Alt would act like their shifted cousins.

==== Function Keys ====

Function keys should generally be reserved for the user to define. If your application does make use of them, then it should at least allow the user to redefine or modify them.

==== Help Key ====

If your application has built-in help, use the Help key to trigger it from the keyboard. Avoid giving the user that helpless feeling he gets when he presses the Help key and nothing happens.

Note that PC keyboards connected to an AmigaOS-compatible computer will not feature the Help key. On such keyboards the Help key will be mapped to the ScrollLock key.