Add a section to the Haiku Book with a very special topic, the keyboard.

This started off as just being a page to detail the key codes since I find
myself constantly referencing the BeBook page on the subject and it is
horribly broken. However, the page has grown to detail many of the keyboard
related methods and constants defined in InterfaceDefs.h as well. A very
long and detailed explanation of the key_map structure is included.

git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@43230 a95241bf-73f2-0310-859d-f6bbb57e9c96

docs/user/Doxyfile

@@ -602,6 +602,7 @@ INPUT                  = . \
                          app \
                          drivers \
                          interface \
+                         keyboard \
                          locale \
                          media \
                          midi \
@@ -701,6 +702,7 @@ EXAMPLE_RECURSIVE      = NO
 
 IMAGE_PATH             = . \
                          interface \
+                         keyboard \
                          midi2
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should

docs/user/book.css

@@ -77,6 +77,8 @@ table {
 td, th {
 	vertical-align: top;
 	text-align: left;
+	padding: 4px;
+	font-size: 14.4px;
 }
 
 caption {

docs/user/book.dox

@@ -54,6 +54,7 @@
 	\section special_topics Special Topics
 
 	- \ref drivers
+	- \ref keyboard
 */
 
 ///// Define main kits /////
@@ -96,9 +97,6 @@
 		- BRoster
 
 
-	\defgroup drivers Device Drivers
-
-
 	\defgroup interface Interface Kit
 	\brief API for displaying a graphical user interface.
 
@@ -553,3 +551,9 @@ snooze_until(time - Latency(), B_SYSTEM_TIMEBASE);
 	\defgroup layout Layout classes in the Interface Kit
 	\ingroup interface
 */
+
+
+///// Special Topics /////
+
+\defgroup drivers Device Drivers
+\defgroup keyboard Keyboard

docs/user/interface/InterfaceDefs.dox

@@ -3,11 +3,14 @@
  * Distributed under the terms of the MIT License.
  */
 
-/*!	\file InterfaceDefs.h
+/*!
+	\file InterfaceDefs.h
 	\brief Defines standard interface definitions for controls.
 */
 
-/*!	\enum border_style
+
+/*!
+	\enum border_style
 	Collection of flags that determine the border style drawn around a BBox.
 */
 
@@ -32,12 +35,15 @@
 	No border.
 */
 
-/*!	\enum orientation
+
+/*!
+	\enum orientation
 Orientation flag sets the layout to either horizontal or vertical
 	alignment.
 */
 
-/*!	\var orientation B_HORIZONTAL
+/*!
+	\var orientation B_HORIZONTAL
 	Horizontal alignment
 */
 
@@ -45,21 +51,132 @@ Orientation flag sets the layout to either horizontal or vertical
 	Vertical alignment
 */
 
-/*!	\enum button_width
+
+/*!
+	\enum button_width
 	Collection of flags that determine how wide to draw the buttons in a
 	BAlert dialog.
 */
 
-/*!	\var button_width B_WIDTH_AS_USUAL
+/*!
+	\var button_width B_WIDTH_AS_USUAL
 	Set the width of each button based on the standard width.
 */
 
-/*!	\var button_width B_WIDTH_FROM_WIDEST
+/*!
+	\var button_width B_WIDTH_FROM_WIDEST
 	Set the width of each button based on the width of the widest button.
 */
 
-/*!	\var button_width B_WIDTH_FROM_LABEL
+/*!
+	\var button_width B_WIDTH_FROM_LABEL
 	Set the width of each button to accomidate the width of the button's
 	label.
 */
 
+
+///// Keyboard related functions
+
+
+/*!
+	\fn uint32 modifiers()
+	\brief Gets a bitmap of each modifier key pressed down and each active
+		keyboard lock.
+
+	Test the bitmap returned using a bit mask composed of the following
+	modifier key constants:
+		- \c B_CAPS_LOCK
+		- \c B_COMMAND_KEY
+		- \c B_CONTROL_KEY
+		- \c B_MENU_KEY
+		- \c B_NUM_LOCK
+		- \c B_OPTION_KEY
+		- \c B_SCROLL_LOCK
+		- \c B_SHIFT_KEY
+
+	You may use a bit mask of 0 to test that no modifier keys are pressed.
+	If it is important to know if the left or right modifier key is pressed
+	down you can use the following additional constants:
+		- \c B_LEFT_SHIFT_KEY
+		- \c B_RIGHT_SHIFT_KEY
+		- \c B_LEFT_CONTROL_KEY
+		- \c B_RIGHT_CONTROL_KEY
+		- \c B_LEFT_OPTION_KEY
+		- \c B_RIGHT_OPTION_KEY
+		- \c B_LEFT_COMMAND_KEY
+		- \c B_RIGHT_COMMAND_KEY
+
+	\returns A bitmap containing each active modifier keys and locks.
+*/
+
+
+/*!
+	\fn status_t get_key_info(key_info* info)
+	\brief Fills out the key_info struct with the current state of the
+		keyboard.
+
+	\param info The key_info struct to fill out.
+
+	\retval B_OK Everything went fine.
+	\retval B_ERROR There was an error retrieving the key_info struct.
+*/
+
+
+/*!
+	\fn void get_key_map(key_map** _map, char** _keyBuffer)
+	\brief Provides a copy of the system keymap.
+
+	\attention You must free \a _map and \a _keyBuffer when you are done
+		with them.
+
+	\param _map A pointer to the system keymap structure.
+	\param _keyBuffer A pointer containing the UTF-8 character encodings.
+*/
+
+
+/*!
+	\fn status_t get_keyboard_id(uint16* _id)
+	\brief Fills out \a _id with the id of the currently attached keyboard.
+
+	\retval B_OK Everything went fine.
+	\retval B_ERROR There was an error retrieving the keyboard id.
+*/
+
+
+/*!
+	\fn status_t get_modifier_key(uint32 modifier, uint32 *key)
+	\brief Gets the code of the requested \a modifier key from the
+		system keymap.
+
+	\param modifier The modifier key to get from the system keymap.
+	\param key A pointer to an int32 to store the key code.
+
+	\retval B_OK Everything went fine.
+	\retval B_ERROR There was an error retrieving the modifier key.
+*/
+
+
+/*!
+	\fn void set_modifier_key(uint32 modifier, uint32 key)
+	\brief Set the \a modifier \a key to the specified code in the
+		system keymap.
+
+	\param modifier The modifier key to set in the system keymap.
+	\param key The key code to set the modifier key to.
+*/
+
+
+/*!
+	\fn void set_keyboard_locks(uint32 modifiers)
+	\brief Set the keyboard locks.
+
+	Pass in a bit mask containing the following constants:
+		- \c B_CAPS_LOCK
+		- \c B_NUM_LOCK
+		- \c B_SCROLL_LOCK
+
+	The constants present in the bit mask will turn the lock on, those
+	absent will turn the lock off. Pass 0 in to turn off all locks.
+
+	\param modifiers A bitmap of lock keys to set.
+*/

docs/user/keyboard/keyboard.dox

@@ -0,0 +1,437 @@
+/*!
+\page keyboard Keyboard
+
+This page details how Haiku reads keys from the keyboard including modifier
+key and special characters, and how you can read and process these encoded
+characters in your application.
+
+\section unicode Haiku and UTF-8
+
+Haiku encodes all characters using UTF-8. UTF-8 allows Haiku to represent
+characters from all over the world while still maintaining backwards
+compatibility with 7-bit ASCII codes. This means that the most commonly
+used characters are encoded in just one byte while less common characters
+can  be encoded by extending the character encoding to use two, three, or,
+rarely, four bytes.
+
+\section keycodes Key Codes
+
+Each key on the keyboard is assigned a numeric code to identify it to the
+operating system. Most of the time you should not have to access these
+codes directly, instead use one of the constants defined in InterfaceDefs.h
+such \c B_BACKSPACE or \c B_ENTER or read the character  from the \c key_map
+struct.
+
+The following diagram shows the key codes as they appear on a US 104-key
+keyboard.
+
+\image html US_PC_keyboard_keycodes.png
+
+International keyboards each differ a bit but generally share an extra key
+located in-between the left shift key and Z with the key code 0x69.
+
+Mac keyboards have an equal sign in the keypad with key code 0x6a and some
+other differences. Often times the keys produce the same key code but appear in
+different locations.
+
+
+\section modifiers Modifier Keys
+
+Modifier keys are keys that have no effect on their own but when combined with
+another key they modify the usual behavior of that key.
+
+The following modifier keys are defined in InterfaceDefs.h
+
+<table>
+	<tr>
+		<td>\c B_SHIFT_KEY</td>
+		<td>
+			Transforms lowercase case characters into uppercase characters
+			or chooses an alternative punctuation character. The shift key
+			is also used in combination with \c B_COMMAND_KEY to produce
+			keyboard shortcuts.
+		</td>
+	</tr>
+	<tr>
+		<td>\c B_COMMAND_KEY</td>
+		<td>
+			Produces keyboard shortcuts for common operations such as
+			cut, copy, paste, print, and find.
+		</td>
+	</tr>
+	<tr>
+		<td>\c B_CONTROL_KEY</td>
+		<td>
+			Outputs control characters in terminal. The control key is
+			sometimes also used as an alternative to \c B_COMMAND_KEY
+			to produce keyboard shortcuts in applications.
+		</td>
+	</tr>
+	<tr>
+		<td>\c B_OPTION_KEY</td>
+		<td>
+			Used to in combination with other keys to output special
+			characters such as accented letters and symbols. Because
+			\c B_OPTION_KEY is not found on all keyboards it should not
+			be used for essential functions.
+		</td>
+	</tr>
+	<tr>
+		<td>\c B_MENU_KEY</td>
+		<td>
+			The Menu key is used to produce contextual menus. Like
+			\c B_OPTION_KEY, the Menu key should not be used for essential
+			functions since it is not available on all keyboards.
+		</td>
+	</tr>
+</table>
+
+In addition you can access the left and right modifier keys individually with
+the following constants:
+<table>
+	<tr>
+		<td>\c B_LEFT_SHIFT_KEY</td>
+		<td>\c B_RIGHT_SHIFT_KEY</td>
+		<td>\c B_LEFT_COMMAND_KEY</td>
+		<td>\c B_RIGHT_COMMAND_KEY</td>
+	</tr>
+	<tr>
+		<td>\c B_LEFT_CONTROL_KEY</td>
+		<td>\c B_RIGHT_CONTROL_KEY</td>
+		<td>\c B_LEFT_OPTION_KEY</td>
+		<td>\c B_RIGHT_OPTION_KEY</td>
+	</tr>
+</table>
+
+Scroll lock, num lock, and caps lock alter other keys pressed after they are
+released. They are defined by the following constants:
+
+<table>
+	<tr>
+		<td>\c B_CAPS_LOCK</td>
+		<td>
+			Produces uppercase characters. Reverses the effect of
+			\c B_SHIFT_KEY for letters.
+		</td>
+	</tr>
+	<tr>
+		<td>\c B_SCROLL_LOCK</td>
+		<td>
+			Prevents the terminal from scrolling.
+		</td>
+	</tr>
+	<tr>
+		<td>\c B_NUM_LOCK</td>
+		<td>
+			Informs the numeric keypad to output numbers when on. Reverses
+			the function of \c B_SHIFT_KEY for keys on the numeric keypad.
+		</td>
+	</tr>
+</table>
+
+To get the currently active modifiers use the modifiers() function defined
+in InterfaceDefs.h. This function returns a bitmap containing the currently
+active modifier keys. You can create a bit mask of the above constants to
+determine if the keys you are interested in are active.
+
+
+\section other_constants Other Constants
+
+The Interface Kit also defines constants for keys that are aren't represented by
+a symbol, these include:
+
+<table>
+	<tr>
+		<td>\c B_BACKSPACE</td>
+		<td>\c B_RETURN</td>
+		<td>\c B_ENTER</td>
+		<td>\c B_SPACE</td>
+		<td>\c B_TAB</td>
+		<td>\c B_ESCAPE</td>
+	</tr>
+	<tr>
+		<td>\c B_SUBSTITUTE</td>
+		<td>\c B_LEFT_ARROW</td>
+		<td>\c B_RIGHT_ARROW</td>
+		<td>\c B_UP_ARROW</td>
+		<td>\c B_DOWN_ARROW</td>
+		<td>\c B_INSERT</td>
+	</tr>
+	<tr>
+		<td>\c B_DELETE</td>
+		<td>\c B_HOME</td>
+		<td>\c B_END</td>
+		<td>\c B_PAGE_UP</td>
+		<td>\c B_PAGE_DOWN</td>
+		<td>\c B_FUNCTION_KEY</td>
+	</tr>
+</table>
+
+The \c B_FUNCTION_KEY constant can further be broken down into the following
+constants:
+<table>
+	<tr>
+		<td>\c B_F1_KEY</td>
+		<td>\c B_F4_KEY</td>
+		<td>\c B_F7_KEY</td>
+		<td>\c B_F10_KEY</td>
+		<td>\c B_PRINT_KEY (Print Screen)</td>
+	</tr>
+	<tr>
+		<td>\c B_F2_KEY</td>
+		<td>\c B_F5_KEY</td>
+		<td>\c B_F8_KEY</td>
+		<td>\c B_F11_KEY</td>
+		<td>\c B_SCROLL_KEY (Scroll Lock)</td>
+	</tr>
+	<tr>
+		<td>\c B_F3_KEY</td>
+		<td>\c B_F6_KEY</td>
+		<td>\c B_F9_KEY</td>
+		<td>\c B_F12_KEY</td>
+		<td>\c B_PAUSE_KEY (Pause/Break)</td>
+	</tr>
+</table>
+
+For Japanese keyboard two more constants are defined:
+	- \c B_KATAKANA_HIRAGANA
+	- \c B_HANKAKU_ZENKAKU
+
+
+\section keymap The Keymap
+
+The characters produced by each of the key codes is determined by the keymap.
+The usual way to for the user to choose and modify their keymap is the
+Keymap preference application. A number of alternative keymaps such as dvorak
+as well as keymaps for different locales are available.
+
+\image html keymap.png
+
+A full description of the Keymap preflet can be found in the 
+<a href="http://haiku-os.org/docs/userguide/en/preferences/keymap.html">User Guide</a>.
+
+The keymap is a map of the characters produced by each key on the keyboard
+including the characters produced when combined with the modifier constants
+described above. The keymap also contains the codes of the modifier keys
+and tables for dead keys.
+
+To get the current system keymap create a pointer to a \c key_map struct and
+\c char array and pass their addresses to the get_key_map() function. The
+\c key_map struct will be filled out with the current system keymap and the
+\c char array will be filled out with the UTF-8 character encodings.
+
+The \c key_map struct contains a number of fields. These fields are described
+in several sections below.
+
+The first section contains a version number and the codes assigned to each of
+the modifier keys.
+
+<table>
+	<tr>
+		<td>\c version</td>
+		<td>The version number of the keymap</td>
+	</tr>
+	<tr>
+		<td>
+			\c caps_key<br>
+			\c scroll_key<br>
+			\c num_key
+		</td>
+		<td>Lock key codes</td>
+	</tr>
+	<tr>
+		<td>
+			\c left_shift_key<br>
+			\c right_shift_key
+		</td>
+		<td>Left and right shift key codes</td>
+	</tr>
+	<tr>
+		<td>
+			\c left_command_key<br>
+			\c right_command_key
+		</td>
+		<td>Left and right command key codes</td>
+	</tr>
+	<tr>
+		<td>
+			\c left_control_key<br>
+			\c right_control_key
+		</td>
+		<td>Left and right control key codes</td>
+	</tr>
+	<tr>
+		<td>
+			\c left_option_key<br>
+			\c right_option_key
+		</td>
+		<td>Left and right option key codes</td>
+	</tr>
+	<tr>
+		<td>\c menu_key</td>
+		<td>Menu key code</td>
+	</tr>
+	<tr>
+		<td>\c lock_settings</td>
+		<td>A bitmap containing the default state of the lock keys</td>
+	</tr>
+</table>
+
+To programmatically set a modifier key in the system keymap use the
+set_modifier_key() function. You can also programmatically set the
+state of the num lock, caps lock, and scroll lock keys by calling the
+set_keyboard_locks() function.
+
+\section character_maps Character Maps
+
+The next section of the \c key_map struct contains maps of offsets
+into the array of UTF-8 character encodings filled out in the second
+parameter by get_key_map(). Since the character maps are filled with UTF-8
+characters they may be 1, 2, 3, or rarely 4 bytes long. The characters are
+contained in non-\c NUL terminated Pascal strings. The first byte of the
+string indicates how many bytes the character is made up of. For example the
+string for a horizontal ellipses (...) character looks like this:
+
+\code
+x03xE2x80xA6
+\endcode
+
+The first byte is 03 meaning that the character is 3 bytes long. The bytes
+E2 80 A6 is the UTF-8 byte representation of the horizontal ellipses character.
+Recall that there is no terminating \c NUL character for these strings.
+
+Not every key is mapped to a character. If a key is unmapped the character
+array contains a 0-byte string. Unmapped keys do not produce \c B_KEY_DOWN
+messages. Modifier keys should not be mapped into the character array.
+
+The following character maps are defined:
+<table>
+	<tr>
+		<td>\c control_map</td>
+		<td>Map of characters when the control key is pressed</td>
+	</tr>
+	<tr>
+		<td>\c option_caps_shift_map</td>
+		<td>
+			Map of characters when caps lock is turned on and both the
+			option key and shift keys are pressed.
+		</td>
+	</tr>
+	<tr>
+		<td>\c option_caps_map</td>
+		<td>
+			Map of characters when caps lock is turned on and the option key
+			is pressed
+		</td>
+	</tr>
+	<tr>
+		<td>\c option_shift_map</td>
+		<td>Map of characters when both shift and option keys are pressed</td>
+	</tr>
+	<tr>
+		<td>\c option_map</td>
+		<td>Map of characters when the option key is pressed</td>
+	</tr>
+	<tr>
+		<td>\c caps_shift_map</td>
+		<td>
+			Map of characters when caps lock is on and the shift key is
+			pressed
+		</td>
+	</tr>
+	<tr>
+		<td>\c caps_map</td>
+		<td>Map of characters when caps lock is turned on</td>
+	</tr>
+	<tr>
+		<td>\c shift_map</td>
+		<td>Map of characters when shift is pressed</td>
+	</tr>
+	<tr>
+		<td>\c normal_map</td>
+		<td>Map of characters when no modifiers keys are pressed</td>
+	</tr>
+</table>
+
+\section dead_keys Dead Keys
+
+Dead keys are keys that do not produce a character until they are combined
+with another key. Because the key does not produce a character on their own
+they are considered "dead" until they are brought to life by being combined
+with another key. These dead keys are generally used to produce accented
+characters.
+
+Each of the fields below is a 32-byte array of dead key characters. The dead
+keys are organized into pairs in the array so each dead key array can contain
+up to 16 pairs of dead key characters. The first pair in the array should
+contain \c B_SPACE followed by and the accent character in the second offset.
+This serves to identify what accent character is contained in the array
+and serves to define a space followed by accent pair to represent the unadorned
+accent character.
+
+The rest of the array is filled with pairs containing an unaccented character
+followed by the accent character.
+
+<table>
+	<tr>
+		<td>\c acute_dead_key</td>
+		<td>Acute dead keys array</td>
+	</tr>
+	<tr>
+		<td>\c grave_dead_key</td>
+		<td>Grave dead keys array</td>
+	</tr>
+	<tr>
+		<td>\c circumflex_dead_key</td>
+		<td>Circumflex dead keys array</td>
+	</tr>
+	<tr>
+		<td>\c dieresis_dead_key</td>
+		<td>Dieresis dead keys array</td>
+	</tr>
+	<tr>
+		<td>\c tilde_dead_key</td>
+		<td>Tilde dead keys array</td>
+	</tr>
+</table>
+
+The final section contains a bitmap that indicate which character table is
+used for each of the above dead keys. The bitmap can contain any of the
+following constants:
+	- \c B_CONTROL_TABLE
+	- \c B_CAPS_SHIFT_TABLE
+	- \c B_OPTION_CAPS_SHIFT_TABLE
+	- \c B_CAPS_TABLE
+	- \c B_OPTION_CAPS_TABLE
+	- \c B_SHIFT_TABLE
+	- \c B_OPTION_SHIFT_TABLE
+	- \c B_NORMAL_TABLE
+	- \c B_OPTION_TABLE
+
+The bitmap often contains \c B_OPTION_TABLE because accent characters are
+typically produced in combination with the \c B_OPTION_KEY.
+
+<table>
+	<tr>
+		<td>\c acute_tables</td>
+		<td>Acute dead keys array</td>
+	</tr>
+	<tr>
+		<td>\c grave_tables</td>
+		<td>Grave dead keys array</td>
+	</tr>
+	<tr>
+		<td>\c circumflex_tables</td>
+		<td>Circumflex dead keys array</td>
+	</tr>
+	<tr>
+		<td>\c dieresis_tables</td>
+		<td>Deeresis dead keys array</td>
+	</tr>
+	<tr>
+		<td>\c tilde_tables</td>
+		<td>Tilde dead keys array</td>
+	</tr>
+</table>
+
+*/