1/*! 2\page keyboard Keyboard 3 4This page details how Haiku reads keys from the keyboard including modifier 5key and special characters, and how you can read and process these encoded 6characters in your application. 7 8\section unicode Haiku and UTF-8 9 10Haiku encodes all characters using UTF-8. UTF-8 allows Haiku to represent 11characters from all over the world while still maintaining backwards 12compatibility with 7-bit ASCII codes. This means that the most commonly 13used characters are encoded in just one byte while less common characters 14can be encoded by extending the character encoding to use two, three, or, 15rarely, four bytes. 16 17\section keycodes Key Codes 18 19Each key on the keyboard is assigned a numeric code to identify it to the 20operating system. Most of the time you should not have to access these 21codes directly, instead use one of the constants defined in InterfaceDefs.h 22such \c B_BACKSPACE or \c B_ENTER or read the character from the \c key_map 23struct. 24 25The following diagram shows the key codes as they appear on a US 104-key 26keyboard. 27 28\image html US_PC_keyboard_keycodes.png 29 30In addition to the keys listed in the picture above, some more keys are defined: 31 32International keyboards each differ a bit but generally share an extra key 33located in-between the left shift key and Z with the key code 0x69. 34 35Japanese keyboards also have a second extra key, either at the left of or under backspace. 36This second extra key gets the code 0x6b. 37 38Mac keyboards have an equal sign in the keypad with key code 0x6a. Some 39other keys produce the same key code but appear in different locations than their PC counterparts. 40 41BeOS used to allocate 0x6b to the power button on ADB keyboards. This is not the case in Haiku, 42instead, see the "multimedia" keys information below for the power button handling. 43 44Some keyboards provide additional "multimedia" keys. These are reported based on their USB HID 45keycodes. Note that these codes are larger than 127, and therefore cannot be mapped in the keymap. 46These keys can only be handled using B_UNMAPPED_KEY_DOWN messages and are never associated with a 47character. 48 49Here is a list of the commonly available key codes not visible in the keyboard picture above: 50 51<table> 52<tr><th>Key code</th><th>Description</th></tr> 53<tr><td>0x69</td><td>First extra international key</td></tr> 54<tr><td>0x6a</td><td>Numpad =</td></tr> 55<tr><td>0x6b</td><td>Second extra international key</td></tr> 56<tr><td>0x6c</td><td>Muhenkan (left of space bar on Japanese keyboards)</td></tr> 57<tr><td>0x6d</td><td>Henkan (first key right of spacebar on Japanese keyboards)</td></tr> 58<tr><td>0x6e</td><td>Katakana/Hiragana (second key right of spacebar on Japanese keyboards)</td></tr> 59<tr><td>0xf0</td><td>Hangul key (for Korean keyboards)</td></tr> 60<tr><td>0xf1</td><td>Hangul hanja key (for Korean keyboards)</td></tr> 61<tr><td>0x00010081</td><td>Power off</td></tr> 62<tr><td>0x00010082</td><td>Sleep</td></tr> 63<tr><td>0x00010083</td><td>Wake up</td></tr> 64<tr><td>0x000C00B0</td><td>Play media</td></tr> 65<tr><td>0x000C00B5</td><td>Scan next track</td></tr> 66<tr><td>0x000C00B6</td><td>Scan previous track</td></tr> 67<tr><td>0x000C00B7</td><td>Stop media</td></tr> 68<tr><td>0x000C00E2</td><td>Mute sound</td></tr> 69<tr><td>0x000C00E9</td><td>Increase sound volume</td></tr> 70<tr><td>0x000C00EA</td><td>Decrease sound volume</td></tr> 71<tr><td>0x000C0183</td><td>Launch control configuration application</td></tr> 72<tr><td>0x000C018A</td><td>Launch e-mail application</td></tr> 73<tr><td>0x000C0192</td><td>Launch calculator application</td></tr> 74<tr><td>0x000C0194</td><td>Launch file manager application</td></tr> 75<tr><td>0x000C0221</td><td>Search</td></tr> 76<tr><td>0x000C0223</td><td>Go to home page</td></tr> 77<tr><td>0x000C0224</td><td>Previous page</td></tr> 78<tr><td>0x000C0225</td><td>Next page</td></tr> 79<tr><td>0x000C0226</td><td>Stop</td></tr> 80<tr><td>0x000C0227</td><td>Refresh</td></tr> 81<tr><td>0x000C022A</td><td>Bookmarks</td></tr> 82</table> 83 84\section modifiers Modifier Keys 85 86Modifier keys are keys which have no effect on their own but when combined with 87another key modify the usual behavior of that key. 88 89The following modifier keys are defined in InterfaceDefs.h 90 91<table> 92 <tr> 93 <td>\c B_SHIFT_KEY</td> 94 <td> 95 Transforms lowercase case characters into uppercase characters 96 or chooses alternative punctuation characters. The shift key 97 is also used in combination with \c B_COMMAND_KEY to produce 98 keyboard shortcuts. 99 </td> 100 </tr> 101 <tr> 102 <td>\c B_COMMAND_KEY</td> 103 <td> 104 Produces keyboard shortcuts for common operations such as 105 cut, copy, paste, print, and find. 106 </td> 107 </tr> 108 <tr> 109 <td>\c B_CONTROL_KEY</td> 110 <td> 111 Outputs control characters in terminal. The control key is 112 sometimes also used as an alternative to \c B_COMMAND_KEY 113 to produce keyboard shortcuts in applications. 114 </td> 115 </tr> 116 <tr> 117 <td>\c B_OPTION_KEY</td> 118 <td> 119 Used to in combination with other keys to output special 120 characters such as accented letters and symbols. Because 121 \c B_OPTION_KEY is not found on all keyboards it should not 122 be used for essential functions. 123 </td> 124 </tr> 125 <tr> 126 <td>\c B_MENU_KEY</td> 127 <td> 128 The Menu key is used to produce contextual menus. Like 129 \c B_OPTION_KEY, the Menu key should not be used for essential 130 functions since it is not available on all keyboards. 131 </td> 132 </tr> 133</table> 134 135In addition you can access the left and right modifier keys individually with 136the following constants: 137<table> 138 <tr> 139 <td>\c B_LEFT_SHIFT_KEY</td> 140 <td>\c B_RIGHT_SHIFT_KEY</td> 141 <td>\c B_LEFT_COMMAND_KEY</td> 142 <td>\c B_RIGHT_COMMAND_KEY</td> 143 </tr> 144 <tr> 145 <td>\c B_LEFT_CONTROL_KEY</td> 146 <td>\c B_RIGHT_CONTROL_KEY</td> 147 <td>\c B_LEFT_OPTION_KEY</td> 148 <td>\c B_RIGHT_OPTION_KEY</td> 149 </tr> 150</table> 151 152Scroll lock, num lock, and caps lock alter other keys pressed after they are 153released. They are defined by the following constants: 154 155<table> 156 <tr> 157 <td>\c B_CAPS_LOCK</td> 158 <td> 159 Produces uppercase characters. Reverses the effect of 160 \c B_SHIFT_KEY for letters. 161 </td> 162 </tr> 163 <tr> 164 <td>\c B_SCROLL_LOCK</td> 165 <td> 166 Prevents the terminal from scrolling. 167 </td> 168 </tr> 169 <tr> 170 <td>\c B_NUM_LOCK</td> 171 <td> 172 Informs the numeric keypad to output numbers when on. Reverses 173 the function of \c B_SHIFT_KEY for keys on the numeric keypad. 174 </td> 175 </tr> 176</table> 177 178To get the currently active modifiers use the modifiers() function defined 179in InterfaceDefs.h. This function returns a bitmap containing the currently 180active modifier keys. You can create a bit mask of the above constants to 181determine which modifiers are active. 182 183 184\section other_constants Other Constants 185 186The Interface Kit also defines constants for keys that are aren't represented by 187a symbol, these include: 188 189<table> 190 <tr> 191 <td>\c B_BACKSPACE</td> 192 <td>\c B_RETURN</td> 193 <td>\c B_ENTER</td> 194 <td>\c B_SPACE</td> 195 <td>\c B_TAB</td> 196 <td>\c B_ESCAPE</td> 197 </tr> 198 <tr> 199 <td>\c B_SUBSTITUTE</td> 200 <td>\c B_LEFT_ARROW</td> 201 <td>\c B_RIGHT_ARROW</td> 202 <td>\c B_UP_ARROW</td> 203 <td>\c B_DOWN_ARROW</td> 204 <td>\c B_INSERT</td> 205 </tr> 206 <tr> 207 <td>\c B_DELETE</td> 208 <td>\c B_HOME</td> 209 <td>\c B_END</td> 210 <td>\c B_PAGE_UP</td> 211 <td>\c B_PAGE_DOWN</td> 212 <td>\c B_FUNCTION_KEY</td> 213 </tr> 214</table> 215 216The \c B_FUNCTION_KEY constant can further be broken down into the following 217constants: 218<table> 219 <tr> 220 <td>\c B_F1_KEY</td> 221 <td>\c B_F4_KEY</td> 222 <td>\c B_F7_KEY</td> 223 <td>\c B_F10_KEY</td> 224 <td>\c B_PRINT_KEY (Print Screen)</td> 225 </tr> 226 <tr> 227 <td>\c B_F2_KEY</td> 228 <td>\c B_F5_KEY</td> 229 <td>\c B_F8_KEY</td> 230 <td>\c B_F11_KEY</td> 231 <td>\c B_SCROLL_KEY (Scroll Lock)</td> 232 </tr> 233 <tr> 234 <td>\c B_F3_KEY</td> 235 <td>\c B_F6_KEY</td> 236 <td>\c B_F9_KEY</td> 237 <td>\c B_F12_KEY</td> 238 <td>\c B_PAUSE_KEY (Pause/Break)</td> 239 </tr> 240</table> 241 242For Japanese keyboard two more constants are defined: 243 - \c B_KATAKANA_HIRAGANA 244 - \c B_HANKAKU_ZENKAKU 245 246 247\section keymap The Keymap 248 249The characters produced by each of the key codes is determined by the keymap. 250The usual way for the user to choose and modify their keymap is the 251Keymap preference application. A number of alternative keymaps such as dvorak 252and keymaps for different locales are available. 253 254\image html keymap.png 255 256A full description of the Keymap preflet can be found in the 257<a href="http://haiku-os.org/docs/userguide/en/preferences/keymap.html">User Guide</a>. 258 259The keymap is a map of the characters produced by each key on the keyboard 260including the characters produced when combined with the modifier constants 261described above. The keymap also contains the codes of the modifier keys 262and tables for dead keys. 263 264To get the current system keymap create a pointer to a \c key_map struct and 265\c char array and pass their addresses to the get_key_map() function. The 266\c key_map struct will be filled out with the current system keymap and the 267\c char array will be filled out with the UTF-8 character encodings. 268 269The \c key_map struct contains a number of fields. Each field is described 270in several sections below. 271 272The first section contains a version number and the code assigned to each of 273the modifier keys. 274 275<table> 276 <tr> 277 <td>\c version</td> 278 <td>The version number of the keymap</td> 279 </tr> 280 <tr> 281 <td> 282 \c caps_key<br> 283 \c scroll_key<br> 284 \c num_key 285 </td> 286 <td>Lock key codes</td> 287 </tr> 288 <tr> 289 <td> 290 \c left_shift_key<br> 291 \c right_shift_key 292 </td> 293 <td>Left and right shift key codes</td> 294 </tr> 295 <tr> 296 <td> 297 \c left_command_key<br> 298 \c right_command_key 299 </td> 300 <td>Left and right command key codes</td> 301 </tr> 302 <tr> 303 <td> 304 \c left_control_key<br> 305 \c right_control_key 306 </td> 307 <td>Left and right control key codes</td> 308 </tr> 309 <tr> 310 <td> 311 \c left_option_key<br> 312 \c right_option_key 313 </td> 314 <td>Left and right option key codes</td> 315 </tr> 316 <tr> 317 <td>\c menu_key</td> 318 <td>Menu key code</td> 319 </tr> 320 <tr> 321 <td>\c lock_settings</td> 322 <td>A bitmap containing the default state of the lock keys</td> 323 </tr> 324</table> 325 326To programmatically set a modifier key in the system keymap use the 327set_modifier_key() function. You can also programmatically set the 328state of the num lock, caps lock, and scroll lock keys by calling the 329set_keyboard_locks() function. 330 331\section character_maps Character Maps 332 333The next section of the \c key_map struct contains maps of offsets 334into the array of UTF-8 character encodings filled out in the second 335parameter of get_key_map(). Since the character maps are filled with UTF-8 336characters they may be 1, 2, 3, or rarely 4 bytes long. The characters are 337contained in non-\c NUL terminated Pascal strings. The first byte of the 338string indicates how many bytes the character is made up of. For example the 339string for a horizontal ellipses (...) character looks like this: 340 341\code 342x03xE2x80xA6 343\endcode 344 345The first byte is 03 meaning that the character is 3 bytes long. The 346remaining bytes E2 80 A6 are the UTF-8 byte representation of the horizontal 347ellipses character. Recall that there is no terminating \c NUL character for 348these strings. 349 350Not every key is mapped to a character. If a key is unmapped the character 351array contains a 0-byte string. Unmapped keys do not produce \c B_KEY_DOWN 352messages. 353 354Modifier keys should not be mapped into the character array. 355 356The following character maps are defined: 357<table> 358 <tr> 359 <td>\c control_map</td> 360 <td>Map of characters when the control key is pressed</td> 361 </tr> 362 <tr> 363 <td>\c option_caps_shift_map</td> 364 <td> 365 Map of characters when caps lock is turned on and both the 366 option key and shift keys are pressed. 367 </td> 368 </tr> 369 <tr> 370 <td>\c option_caps_map</td> 371 <td> 372 Map of characters when caps lock is turned on and the option key 373 is pressed 374 </td> 375 </tr> 376 <tr> 377 <td>\c option_shift_map</td> 378 <td>Map of characters when both shift and option keys are pressed</td> 379 </tr> 380 <tr> 381 <td>\c option_map</td> 382 <td>Map of characters when the option key is pressed</td> 383 </tr> 384 <tr> 385 <td>\c caps_shift_map</td> 386 <td> 387 Map of characters when caps lock is on and the shift key is 388 pressed 389 </td> 390 </tr> 391 <tr> 392 <td>\c caps_map</td> 393 <td>Map of characters when caps lock is turned on</td> 394 </tr> 395 <tr> 396 <td>\c shift_map</td> 397 <td>Map of characters when shift is pressed</td> 398 </tr> 399 <tr> 400 <td>\c normal_map</td> 401 <td>Map of characters when no modifiers keys are pressed</td> 402 </tr> 403</table> 404 405\section dead_keys Dead Keys 406 407Dead keys are keys that do not produce a character until they are combined 408with another key. Because these keys do not produce a character on their own 409they are considered "dead" until they are "brought to life" by being combined 410with another key. Dead keys are generally used to produce accented 411characters. 412 413Each of the fields below is a 32-byte array of dead key characters. The dead 414keys are organized into pairs in the array. Each dead key array can contain 415up to 16 pairs of dead key characters. The first pair in the array should 416contain \c B_SPACE followed by and the accent character in the second offset. 417This serves to identify which accent character is contained in the array 418and serves to define a space followed by accent pair to represent the unadorned 419accent character. 420 421The rest of the array is filled with pairs containing an unaccented character 422followed by the accent character. 423 424<table> 425 <tr> 426 <td>\c acute_dead_key</td> 427 <td>Acute dead keys array</td> 428 </tr> 429 <tr> 430 <td>\c grave_dead_key</td> 431 <td>Grave dead keys array</td> 432 </tr> 433 <tr> 434 <td>\c circumflex_dead_key</td> 435 <td>Circumflex dead keys array</td> 436 </tr> 437 <tr> 438 <td>\c dieresis_dead_key</td> 439 <td>Dieresis dead keys array</td> 440 </tr> 441 <tr> 442 <td>\c tilde_dead_key</td> 443 <td>Tilde dead keys array</td> 444 </tr> 445</table> 446 447The final section contains bitmaps that indicate which character table is 448used for each of the above dead keys. The bitmap can contain any of the 449following constants: 450 - \c B_CONTROL_TABLE 451 - \c B_CAPS_SHIFT_TABLE 452 - \c B_OPTION_CAPS_SHIFT_TABLE 453 - \c B_CAPS_TABLE 454 - \c B_OPTION_CAPS_TABLE 455 - \c B_SHIFT_TABLE 456 - \c B_OPTION_SHIFT_TABLE 457 - \c B_NORMAL_TABLE 458 - \c B_OPTION_TABLE 459 460The bitmaps often contain \c B_OPTION_TABLE because accent characters are 461generally produced by combining a letter with \c B_OPTION_KEY. 462 463<table> 464 <tr> 465 <td>\c acute_tables</td> 466 <td>Acute dead keys table bitmap</td> 467 </tr> 468 <tr> 469 <td>\c grave_tables</td> 470 <td>Grave dead keys table bitmap</td> 471 </tr> 472 <tr> 473 <td>\c circumflex_tables</td> 474 <td>Circumflex dead keys table bitmap</td> 475 </tr> 476 <tr> 477 <td>\c dieresis_tables</td> 478 <td>Dieresis dead keys table bitmap</td> 479 </tr> 480 <tr> 481 <td>\c tilde_tables</td> 482 <td>Tilde dead keys table bitmap</td> 483 </tr> 484</table> 485 486*/ 487
