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