Template:Keystroke/doc

From MozillaWiki
Jump to: navigation, search
Edit-copy green.svg
This is a documentation subpage for Template:Keystroke.
It contains usage information, categories and other content that is not part of the original template page.
Ambox info soft.png
  Note: In spite of what the error message above may suggest, the template works. Scroll down to see it in action in the template's documentation.

The {{keystroke}} template is designed to illustrate keys and keystrokes on a computer keyboard, and is a slight modification of the template Key press in Wikipedia (en). It is especially useful when creating help pages or documentation.

{{keystroke}} works similar to {{kbd}}, but have some additional options:

  • Multiple key name input, giving one template call for up to ten keys in a single combination.
  • Unicode symbols for keys that always or at least sometimes lack textual identification, for different OSs.
  • Wikilinking to the articles on the keys in Wikipedia (en).
  • Japanese and Korean language input keys.

Parameters

There is 1 required parameter, and 9 optional ones, all unnamed. The syntax for {{keystroke}} is:

{{keystroke|key1 |key2 |key3 |key4 |key5 |…|key10 }}

Required parameter

1 (unnamed)

Key name

Entering at least one parameter is required for the template to work.

If this parameter is left out, the template will break and display an error message.

Example
key1 }} key1
Usage

{{keystroke|1}}

Optional parameters

2–10 (unnamed)

Additional key names

To create a keystroke combination, use the first parameter with the parameters 2 through 10. The displayed keys will be separated by plus signs.

The template can take up to 10 key name parameters to display keystroke combinations. If you enter 11 or more key names, it will display an error message.

Example
key1 |key2 }} key1+key2
Usage

{{keystroke|1|2|3|4|5|…|10}}

Letters and other case-dependant characters

For clarity, you should always use the same case on your virtual key, as the equivalent character on your keyboard. That usually means using uppercase letters, even when describing input of lowercase letters.

Example

To describe how to type the lowercase letter a:

A}} A

Hence, to describe how to enter an uppercase letter, you should combine the letter with the appropriate modifier key (usually ⇧ Shift).

Example

Describing how to type the uppercase letter A:

shift|A}} ⇧ Shift+A

Wiki markup characters

Some wiki markup characters, like the pipe symbol (|), the semicolon (;) and the equals sign (=), need to be entered using templates, HTML entities, or the character aliases that have been created for this template (see the table under Available values below). It's recommended to use the aliases in order to make the wikicode easier to read.

However, if the characters are marked as wikilinks, they can be entered as such.

Example
[[;]]}} ;

Unicode symbols and wikilinking

Some keys have an option of being displayed with just text, with a symbol & text, with wikilinked text, or with a symbol & wikilinked text.

Unicode symbols

For keys that can be optionally fitted with a symbol, the symbol is inserted by appending "-uc" to the end of the value string.

Keys that more often than not have a symbol instead of text, e.g. the Windows key (Win), will always show with both the symbol and text. And keys such as arrow keys, punctuation characters, etc. only show the symbol. There are no characters for the Windows key (due to copyrights) and the Menu key. Instead, this template shows approximate characters for them.

Examples
space}} Space bar
space-uc}} ␣ Space bar
win}} ⊞ Win
Unicode symbols in the template
Modifier keys Alphanumeric keys Lock keys
Key Unicode
symbol
Key Unicode
symbol
Key Unicode
symbol
Alt
Backspace
Caps Lock
Command (Cmd)
Enter
Number Lock
Compose
Enter (Mac)
Scroll Lock
Control (Ctrl)
Spacebar
Meta
Tabulator (Tab)
Option (Opt)
Shift
Win
Cursor keys System command keys Miscellaneous
Key Unicode
symbol
Key Unicode
symbol
Key Unicode
symbol
Up
Escape (Esc)
Korean Won
Down
Menu
Left
Print Screen
Right

Wikilinks

Some keys can be wikilinked to make them link to the character's/key's English Wikipedia article. That is acheived by enclosing the value string in double brackets, i.e. by wikilinking them.

Example
[[space]]}} Space bar
Both symbol and wikilink

You can of course combine the two features described above.

Examples
[[space-uc]]}} ␣ Space bar
[[win]]}} ⊞ Win

Available values

Alphanumeric keys

Group Key Value Notes
Text Link Symbol + text Symbol + link
Letters A–Z
A–Z
a–z
a–z
Avoid lowercase, if possible
Other letters
(as above)
Digits 0–9
0–9
Other digits
(as above)
Punctuation Colon
colon
[[colon]]
Semicolon
semicolon
[[semicolon]]
Spacebar
space
[[space]]
space-uc
[[space-uc]]

Cursor keys

Group Key Value Notes
Text Link Symbol + text Symbol + link
Deletion Backspace
backspace
[[backspace]]
Delete
del
[[del]]
Short name
delete
[[delete]]
Long name
Insert
insert
[[insert]]
Locking Caps Lock
caps
[[caps]]
caps-uc
[[caps-uc]]
Num Lock
num
[[num]]
num-uc
[[num-uc]]
Scroll Lock
scroll
[[scroll]]
scroll-uc
[[scroll-uc]]
Navigation Arrows Down
down
[[down]]
No text
Left
left
[[left]]
No text
Right
right
[[right]]
No text
Up
up
[[up]]
No text
End
end
[[end]]
Home
home
[[home]]
Page Down
pgdn
[[pgdn]]
Page Up
pgup
[[pgup]]
Tabulator
tab
[[tab]]
Short name
tabulator
[[tabulator]]
Long name

Modifier keys and letters

Modifier keys
Key Value Notes
Text Link Text + symbol Link + symbol
Alt
alt
[[alt]]
alt-uc
[[alt-uc]]
Alt Gr
altgr
[[altgr]]
Command
(Cmd)
command
[[command]]
Long name
cmd
[[cmd]]
Short name
Compose
compose
[[compose]]
compose-uc
[[compose-uc]]
Control
(Ctrl)
control
[[control]]
control-uc
[[control-uc]]
Long name
ctrl
[[ctrl]]
ctrl-uc
[[ctrl-uc]]
Short name
Enter
enter
[[enter]]
entermac
[[entermac]]
Some Mac keyboards
Fn
fn
[[fn]]
Meta
meta
[[meta]]
meta-uc
[[meta-uc]]
Option
(Opt)
option
[[option]]
Long name
opt
[[opt]]
Short name
Shift
shift
[[shift]]
Windows
(Win)
windows
[[windows]]}} Long name
win
[[win]]}} Short name
Modifier letters (dead keys)

Modifier letters, or dead keys, are the keys on your keyboard, that are used to combine, for example, diacritic marks (umlaut, accents, circumflex, etc.) with matching letters. When such a key is pressed, nothing seems to happen, hence the term "dead key". Diacritics are used in many languages, and most localized keyboard layouts have a set of the commonmost ones for the locale and the nearby regions, together with special, precomposed letters.

Producing a diacritic letter is done by first pressing the letter modifier with the diacritic you want, and then the letter onto which the diacritic should be inserted.

Examples
^+E ê
^+⇧ Shift+E Ê

If you want to type only the diacritic, you press its key and then press the spacebar.

Example
^+␣ Space bar ^

Characters, letters or diacritic marks that aren't featured on your keyboard have to be entered using HTML entities or, if you have a numeric keypad, Alt codes.

Examples
© (decimal HTML character entity) ©
Alt+0169 (unicode value) ©
Alt+Num+00A9 (hexadecimal unicode value) ©

NB! Alt codes can usually only be entered via the numeric keypad, i.e. not by using the row of digits above the letter keys.

System command keys

Key Value Notes
Text Link Text + symbol Link + symbol
Break
break
[[break]]
Also called Pause (see below)
Escape
(Esc)
escape
[[escape]]
escape-uc
[[escape-uc]]
Long name
esc
[[esc]]
esc-uc
[[esc-uc]]
Short name
Menu
menu
[[menu]]
Pause
pause
[[pause]]
Also called Break (see above)
Print screen
(Prt Sc)
printscreen
[[printscreen]]
printscreen-uc
[[printscreen-uc]]
Long name
prtsc
[[prtsc]]
prtsc-uc
[[prtsc-uc]]
Short name
System Request
(SysRq)
systemrequest
[[systemrequest]]
Long name
sysrq
[[sysrq]]
Short name

Language input keys

Japanese
Key Value Notes
Text Link Text + symbol Link + symbol
Conversion
(henkan)
henkan
Same output
conversion
Non-Conversion
(muhenkan)
muhenkan
Same output
nonconversion
Half-width
(hankaku)
hankaku
Same output
half
Full-width
(zenkaku)
zenkaku
Same output
full
Kanji
kanji
Half-width/Full-width
(hankaku/zenkaku)
haze
Same output
halffull
Half-width/Full-width/Kanji
(hankaku/zenkaku/kanji)
hazeka
Katakana
kata
Hiragana
hira
Rōmaji
roma
Katakana/hiragana
kahi
Katakana/hiragana/rōmaji
kahiro
Alphanumeric
(eisū)
eisu
Same output
alphanumeric
Korean
Key Value Notes
Text Link Text + symbol Link + symbol
Hangul
hangul
Yeong
yeong
Hangul/yeong
ha/ye
With forward slash
haye
Without forward slash
Hanja
hanja
Korean text
hanjach
Chinese text
Won
wonsign
Only the symbol, no text
wonen
English text
wonko
Korean text

Markup character substitutes for this template

Character Code
Name Char MozillaWiki
template
HTML
entity
Template
alias
Asterisk
*
* asterisk
Colon
:
: colon
Equals sign
=
{{=}}
= equals
Number sign
#
# hash
Pipe symbol
|
}} | pipe
Semicolon
;
{{;}}
&#59; semicolon

Examples

Correct use

Single keys

Case What you type What you see Notes
Letter a A}} A Use uppercase for your virtual keys
Letter A shift|A}} ⇧ Shift+A If case is important, uppercase is denoted
by including the appropriate modifier key
Letter ä Ä}} Ä Direct input (e.g. on a Swedish keyboard)
Ä}} Ä Using the umlaut letter modifier
Ä}} Ä Using the HTML entity
Symbol ↑ up}}
Symbol ₩ + korean text wonko}} ₩ 원
Key name, long option}} ⌥ Option
Key name, short opt}} ⌥ Opt

Keystroke combinations

Case What you type What you see Notes
Two keys alt|P}} Alt+P
Three keys ctrl|alt|del}} Ctrl+Alt+Del
Line wrapping

When you feed several key names to this template, it adds a "+" with no spaces around. This means it won't line wrap. If you need the combinations to line wrap, e.g. in tables, build them one by one with spaces around the "+", or manipulate the chain template key, so they can line wrap. To insert blank characters, you have to use HTML entities; e.g. the standard space character is  .

Case What you type What you see Notes
One by one ctrl}} + {{keystroke|alt}} + {{keystroke|del}} Ctrl + Alt + Del
Change chain ctrl|alt|del|chain= + }} Ctrl + Alt + Del For advanced users
Alt codes

To illustrate Windows Alt codes, you might want to use separate templates with no intervening punctuation or space. Do that by combining the Alt with the first character (often 0) in the first template, and then creating separate templates for the last digits.

Case What you type What you see Notes
First part alt|0}} Alt+0 Provides the plus sign
Parts 2-4 1}} 1
7}} 7
7}} 7
Resulting Alt code alt|0}}{{keystroke|1}}{{keystroke|7}}{{keystroke|7}} Alt+0177

Japanese combined language input keys

Some of the Japanese language input keys combine several functions. In this template, they are fitted next to each other, making these keys wider than usual.

Case What you type What you see Notes
Hankaku/zenkaku haze}} 半角 • 全角
Hankaku/zenkaku/kanji hazeka}} 半角 • 全角 • 漢字
Katakana/hiragana kahi}} カタカナ • ひらがな
Katakana/hiragana/rōmaji kahiro}} カタカナ • ひらがな • ローマ字

Using wikilinks

Case What you type What you see Notes
Long name {{keystroke|[[control]]}} Control The choice of name length doesn't affect
the link, it points to the same target
Short name {{keystroke|[[ctrl]]}} Ctrl
Just text {{keystroke|[[scroll]]}} Scroll Lock For keys with an option to show the symbol
or not, see Available values above
With symbol {{keystroke|[[scroll-uc]]}} ⇳ Scroll Lock

Incorrect use

Wikilinking non-linked keys

Case What you type What you see Notes
Any non-linked key {{keystroke|[[A]]}} A Keys that aren't fitted with links in
{{keystroke/core}} will link to a page with
that name inside MozillaWiki, if it exists
External links {{keystroke|[http://en.wikipedia.org/wiki/A A]}} A External links will show the symbol
used by MediaWiki for such links;
not recommended, due to cluttering

Input errors

Template-breaking errors
Case What you type What you see Notes
No parameter {{keystroke}} Error in {{keystroke}}: No parameter specified. You have to enter at least one key name. The 1st parameter is required; without it, the template will break
Empty 1st parameter {{keystroke|}} Error in {{keystroke}}: No parameter specified. You have to enter at least one key name.
{{keystroke||2|3|4}} Error in {{keystroke}}: No parameter specified. You have to enter at least one key name.
10 key names {{keystroke|1|2|3|4|5|6|7|8|9|10}} 1+2+3+4+5+6+7+8+9+10 As noted above, ten entries works fine, but …
≥ 11 key names {{keystroke|1|2|3|4|5|6|7|8|9|10|11}} Error in {{keystroke}}: Too many keys. The template can't handle combinations of more than 10 keys. … eleven or more entries will cause an error
Fallbacks
Case What you type What you see Notes
Empty 2nd–11th parameter {{keystroke|1|2||4|5}} 1+2+4+5 You can leave a parameter empty if it is …

a) surrounded by other parameters, or
b) an empty last parameter

The template will fall back to displaying
the correctly entered parameter values
{{keystroke|1|2|3|4|}} 1+2+3+4
{{keystroke|1|2|3|4||}} 1+2+3+4
{{keystroke|1|2|3|4|5|6|7|8|9|10|}} 1+2+3+4+5+6+7+8+9+10
{{keystroke|1|2|3|4|5|6|7|8|9|10||}} 1+2+3+4+5+6+7+8+9+10

Technical details

This template calls {{keystroke/core}}, which holds the code that otherwise would be repeated several times in {{keystroke}}, thus simplifying the code.

See also

  • {{kbd}} – Produces a different visual effect, without unicode symbols