** Introduction ** When using [bind] to handle keyboard events, Modifier keys can change the effect of a keystroke. This is described on the manual page [http://www.purl.org/tcl/home/man/tcl8.5/TkCmd/bind.htm%|%bind(n)%|%]. The present page describes the effects of Modifier keys on different platforms. This information has been obtained by experimentation with Tcl/Tk 8.5.8. Some results might depend on the specific hardware used: if you get different results, please document this. If you use a different platform or keyboard (e.g. Sun, Space Cadet [http://en.wikipedia.org/wiki/Space-cadet_keyboard]), please add a section to this page. ** PC running Linux ** A standard PC keyboard on Linux never applies the Modifiers Extended Meta, M Mod3, M3 The PC keyboard's Modifier keys on Linux are: %|Key|KeyPress %K|KeyRelease %K|Binding Modifier|PE [[1]]|AR [[2]]|%A [[3]]|Notes|% &||||Extended||||Not used in Linux.|& &|Num Lock|Num_Lock|Num_Lock|Option, Mod2, M2|Y||M||& &|Scroll Lock|Scroll_Lock|Scroll_Lock||Y|||NOT a Modifier key in Linux.|& &|Caps Lock|Caps_Lock|Caps_Lock|Lock|Y||M||& &|Shift (Left)|Shift_L|Shift_L|Shift|||M||& &|Shift (Right)|Shift_R|Shift_R|Shift|||M||& &|Control (Left)|Control_L|Control_L|Control|||-|Exceptions to '''[[3]''' include: for the numerals 0, 1, or 9 with the Control Modifier, %A is the unmodified numeral.|& &|Control (Right)|Control_R|Control_R|Control||Y|-|Exceptions to '''[[3]''': as for Control (Left).|& &|"Windows" (Left)|Super_L|Super_L|Mod4, M4||Y|U||& &|"Windows" (Right)|Super_R|Super_R|Mod4, M4||Y|U||& &|Alt (Left)|Alt_L|Alt_L|Alt|||U|A binding with Modifier Alt is overridden by a binding with Modifier Command, Mod1, or M1.|& &|Alt Gr '''[[4]]'''|ISO_Level3_Shift|??|Mod5, M5||Y|M|The event KeyRelease-ISO_Level3_Shift is not recognised: it is reported as KeyRelease-??.|& '''[[1]]''' Column '''PE''' means "Persistent". If marked "Y", the key is pressed and released to activate the Modifier; the Modifier is applied to subsequent keystrokes until the Modifier key is pressed and released again. If not marked "Y", the key must be held down to activate its Modifier; the Modifier is applied to subsequent keystrokes until the Modifier key is released.<
> '''[[2]]''' Column '''AR''' means "Autorepeat". If marked "Y", the key has autorepeat enabled.<
> '''[[3]]''' Column '''%A''' indicates the value supplied as the binding value %A. * If marked "U", the same value is supplied as for the unmodified event. * If marked "M", a modified value is supplied: ** for "Caps Lock" or "Shift" or (Mac only) both, a change of case; but (Linux, Windows only) no change if both Modifiers are present ** for "Num Lock", a numerical value instead of {} when a numerical keypad key is pressed; otherwise unmodified ** for "Alt Gr", a different character (or none) ** for "Command" (Mac only), many characters are unmodified; some characters are modified; some events are intercepted by the operating system. * If marked "-", the value supplied as %A is either the string "{}", or an unprintable symbol, or in a few cases (different for each platform) an exception to this rule - example exceptions are listed in the "Notes" column of the Table. In the text widget, these complications are suppressed by a binding to that prevents the symbol %A from being inserted into the widget. '''[[4]]''' The "Right Alt" or "Alt Gr" key is used in combination with certain other keys for composing characters that are not otherwise available on the keyboard. This functionality is provided by the operating system, without use of the Mod5/M5 Modifier (Linux) or the Control-Alt Modifier (Windows), to generate the value supplied as %A; that value is not necessarily the same for Windows and Linux, or the same as the value produced by the Option key on the Mac. ** PC running Windows ** A standard PC keyboard on Windows never applies the Modifiers Meta, M Mod4, M4 Mod5, M5 The PC keyboard's Modifier keys on Windows are: %|Key|KeyPress %K|KeyRelease %K|Binding Modifier|PE [[1]]|AR [[2]]|%A [[3]]|Notes|% &||||Extended|||U|In Windows, this Modifier is automatically applied to certain keys of the "Extended" keyboard. See [http://www.purl.org/tcl/home/man/tcl8.5/TkCmd/bind.htm%|%bind(n)%|%] for details.|& &|Num Lock|Num_Lock|Num_Lock|Command, Mod1, or M1|Y|Y|M||& &|Scroll Lock|Scroll_Lock|Scroll_Lock|Mod3, or M3|Y|Y|U||& &|Caps Lock|Caps_Lock|Caps_Lock|Lock|Y|Y|M||& &|Shift (Left)|Shift_L|Shift_L|Shift||Y|M||& &|Shift (Right)|Shift_R|Shift_L|Shift||Y|M||& &|Control (Left)|Control_L|Control_L|Control||Y|-|Exceptions to '''[[3]''' include: emits a newline as %A.|& &|Control (Right)|Control_R|Control_L|Control||Y|-|Exceptions to '''[[3]''': as for Control (Left).|& &|"Windows" (Left)|Win_L|Win_L|||Y||NOT a Modifier key in Windows.|& &|"Windows" (Right)|Win_R|Win_R|||Y||NOT a Modifier key in Windows.|& &|Alt (Left)|Alt_L|Alt_L|Alt||Y|U|A binding with Modifier Alt is overridden by a binding with Modifier Option, Mod2, or M2.|& &|Alt Gr '''[[4]]'''|Control_L, Alt_R|Control_L, Alt_L|Control-Alt||Y|M|A binding with Modifier Alt is overridden by a binding with Modifier Option, Mod2, or M2. When the Modifier key is pressed, two KeyPress events occur: the first with keysym Control_L, the second with keysym Alt_R.<
>If the operating system supplies a replacement character, the Tk KeyPress event does not have the Control or Alt Modifiers: it is an unmodified KeyPress event, e.g. . A binding to will ''not'' capture such events - instead it captures events on keys where the operating system does ''not'' supply a replacement character. This mechanism is unique to Windows - keyboard events with "Alt Gr" (in Linux) and "Option" (in MacOS X) Modifier keys always carry the expected binding Modifiers.|& '''[[1]], [[2]], [[3]], [[4]]''' Same as footnotes on Linux table (above). ** Mac running MacOS X ** A Mac keyboard does not use the Modifiers Alt Extended Meta, M Mod3, M3 Mod4, M4 Mod5, M5 The Mac keyboard's Modifier keys on Mac OS X are: %|Key|KeyPress %K|KeyRelease %K|Binding Modifier|PE [[1]]|AR [[2]]|%A [[3]]|Notes|% &|Caps Lock|Caps_Lock|Caps_Lock|Lock|Y||M||& &|Shift (Left or Right)|Shift_L|Shift_L|Shift|||M|The left and right keys emit the same %K.|& &|Control (Left or Right)|Control_L|Control_L|Control|||-|Control (ctrl) keys.<
>The left and right keys emit the same %K.<
>Exceptions to '''[[3]''' include: for any numeral with the Control Modifier, %A is the unmodified numeral.|& &|Command (Left or Right)|Meta_L|Meta_L|Command, Mod1, M1|||M|Command (Apple or ⌘) keys.<
>The left and right keys emit the same %K.|& &|Alt (Left or Right) '''[[4]]'''|Alt_L|Alt_L|Option, Mod2, M2|||M|Option (Alt or alt) keys.<
>The left and right keys emit the same %K.|& '''[[1]], [[2]], [[3]]''' Same as footnotes on Linux table (above).<
> '''[[4]]''' The "Alt" or "Option" key is used in combination with other keys for composing characters that are not otherwise available on the keyboard. This functionality is provided by the operating system, without use of the Option/Mod2/M2 Modifier, to generate the value supplied as %A; that value is not necessarily the same as the value produced by the "Right Alt" or "Alt Gr" key of a PC keyboard on Windows or Linux. The Binding Modifier "Alt" is not recognized on the Mac, even though some Mac keyboards label the "Option" key "alt". '''Using a PC Keyboard on the Mac'''<
> The PC keyboard behaves very much like the Mac keyboard described above. The "Windows" Modifier key takes the role of the Command/Apple/⌘ key. The Left-Alt and Right-Alt keys are interchangeable, as on a Mac keyboard. The "Num Lock" and "Scroll Lock" keys are not recognized as Modifiers: "Num Lock" behaves as "Clear", the Mac key in the same position; pressing or releasing the "Scroll Lock" key does not trigger an event. ** Cross-Platform Development ** The following suggestions attempt to follow the style expected for an application on each platform, while keeping code simple, and avoiding conflicts between different platforms. * Don't define event bindings with the Command or Option Modifiers, except on the Mac platform. ** ''On other platforms, these bindings will fire under inappropriate conditions: when an Alt key is pressed (overriding the corresponding binding that uses the Alt Modifier); or when "Num Lock" has been pressed.'' * On the Mac platform, it is not usually necessary to define bindings with the Control modifier. If this is done, ensure that the bindings are not defined on other platforms unless this is appropriate. * Don't use the "Windows" Modifier keys (the Mod4 binding Modifier) on Linux: use the Alt and Control keys only. ** ''The "Windows" keys have no counterpart on platforms other than Linux: they do not function as Modifier keys on Windows; and although they correspond to the "Command" keys on the Mac, Mac style typically requires that the "Command" keys perform the same role as the "Control" keys on Windows or Linux.'' * Unicode characters supplied by the operating system (when using the "Alt Gr" or "Option" keys) do not need special bindings - they trigger the binding without Modifiers. ** ''Because (for Windows) such an event does not have the Modifier(s) normally associated with the "Alt Gr" key; or (for Linux, MacOS X) the Modifiers do not precisely match the bindings provided by default, so the event triggers the less specific binding.'' * Don't use bindings to the Shift or Lock modifiers to distinguish upper-case and lower-case characters: use the value of %A, which is simple and correct, but platform-dependent. ** ''For the value of %A, the "Shift" key cancels the "Caps Lock" key in Linux and Windows, but not in Mac OS X. This conforms with the style of each platform.'' * The value of %A for a event is rarely useful, and should usually be suppressed by a suitable binding. The same technique can be used to prevent other modified keystrokes from being interpreted as simple (unmodified) keystrokes. ** ''Cf. the text widget: in the Text binding tag, the binding does nothing, but its existence prevents an event with a Control Modifier key from binding to the binding, and thereby having its %A written to the widget. The same technique is used in the Text binding tag to suppress keystrokes with the modifiers Alt, Meta, and (MacOS X only) Command (see file lib/tk8.x/text.tcl).'' ** Discussion ** There are clearly many differences between different platforms. In some cases, there is a reason: e.g. * On the Mac, the "Shift" key does not cancel the effect of "Caps Lock" '''[[3]'''. This makes Tcl/Tk applications behave in the same way as other Mac applications. Other differences might have a good reason (if so, please add it to the list immediately above). However, some features may exist for historical reasons that are no longer valid. While these features must be retained in the Tcl/Tk 8.x series in order to preserve compatibility, it might be desirable to rationalise the keyboard Modifiers in Tcl/Tk 9.0, in order to simplify cross-platform development. See [Tk 9.0 WishList]. <>Characters|Hardware|Platform Issues