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