diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/info/mds.texinfo | 531 | ||||
| -rw-r--r-- | doc/protocols | 326 |
2 files changed, 528 insertions, 329 deletions
diff --git a/doc/info/mds.texinfo b/doc/info/mds.texinfo index 7394aac..9e26e9f 100644 --- a/doc/info/mds.texinfo +++ b/doc/info/mds.texinfo @@ -1721,6 +1721,7 @@ simple, reference implementation of a, status icon tray. @menu * Infrastructure protocols:: Infrastructure protocols. * Virtual terminal protocols:: Virtual terminal protocols. +* Keyboard protocols:: Keyboard protocols. @end menu @@ -1985,7 +1986,7 @@ VT such that they can use ioctl and similar calls on that TTY. Required. @item Reference implementation: -@code{vt} +@code{mds-vt} @end table @@ -2042,7 +2043,7 @@ VT such that they can use ioctl and similar calls on that TTY. Required. @item Reference implementation: -@code{vt} +@code{mds-vt} @end table @@ -2098,7 +2099,531 @@ active again. Required. @item Reference implementation: -@code{vt} and @code{kkbd} +@code{mds-vt} and @code{mds-kkbd} +@end table + + + +@node Keyboard protocols +@section Keyboard protocols + +@menu +* key-sent:: Announce a keyboard input event. +* enumerate-keyboards:: List available keyboards. +* keyboard-enumeration:: Response to @code{Command: enumerate-keyboards}. +* set-keyboard-leds:: Activate and deactivate LED:s on a keyboard. +* get-keyboard-leds:: List exisiting LED:s on a keyboard and their state. +* keycode-map:: Remap keyboard keycodes and query current mapping. +* new-keyboard:: Announce the existance of a new keyboard. +* old-keyboard:: Announce the removal of an old keyboard. +@end menu + + + +@node key-sent +@subsection key-sent + +@table @asis +@item Identifying header: +@command{Command: key-sent} + +@item Action: +Announce a keyboard input event. + +@item Required header: @code{Keyboard} +Any string that uniquely identifies the keyboard. +@table @asis +@item Purpose: +Enable multi-keyboard aware programs and give at +least on keyboard per seat in a multi-seat environment. +@item Note: +mds-kkbd uses @code{kernel} to indicate that it uses +the kernel and thus lumps together all keyboards. +@end table + +@item Required header: @code{Released} +@table @code +@item yes +The value of the header @code{Released} will +be @code{yes} if the key was released. +@item no +The value of the header @code{Released} will be +@code{no} otherwise, that is, held down or pressed. +@end table +Note: pause/break is automatically released directly after +it has been pressed. This is feature built into keyboards +and servers should not try to circumvent this. + +@item Required header: @code{Keycode} +An unsigned 14-bit integer identifying the key, may be remapped. + +@item Optional header: @code{Scancode} +Either an unsigned 7-bit integer or a single blank space +separated trio of unsigned 7-bit integers, identifying the key. +This is the scancode sent from the keyboard and optionally +unified by the keyboard driver, however with the typed/released +bit zeroed out. This may not be remapped. + +@item Optional header: @code{Modifiers} +Single blank space separated list of active modifiers: +@table @code +@item shift +Shift (level 2) +@item ctrl +Control +@item alt +Alternative/Option +@item altgr +Alternative Graphic (level 3) +@item lvl* +@code{*} may be any @math{2^n + 1} integer with +@math{1 < n < 20}. +@item super +Super +@item hyper +Hyper +@item ultra +Ultra +@item caps +Caps (usually a lock key) +@item num +Num (usually a lock key) +@item scrl +Scroll (usually a lock key) +@item top +Top (historical) +@item front +Front (historical) +@item greek +Greek (historical) +@item compose +Compose (rare, it is usally a dead key) +@end table +Any key that has been locked should be prefix with +@code{+}, if the key has been locked by nullified +with non-lock modifier it should be prefixed with +a @code{-}. If no modifier is active or has been +nullified, @code{none} should be used. + +@item Optional header: @code{Key} +A textual representation of the key that has been typed or +released, as mapped by the keyboard layout. +@table @code +@item esc +Escape +@item f* +F@code{*} where @code{*} is any integer. +@item sysrq +System Request/Print Screen +@item scrl +Scroll (lock) +@item break +Break/Pause +@item backspace +Backspace +@item tab +Tab +@item return +Return/Enter +@item space +Blank Space +@item menu +Application Menu +@item ins +Insert +@item home +Home +@item pgup +Page Up +@item del +Delete +@item end +End +@item pgdown +Page Down +@item up +Up Arrow +@item left +Left Arrow +@item down +Down Arrow +@item right +Right Arrow +@item shift +Shift (level 2) +@item begin +Begin (keypad 5 in nagivation mode) +@item ctrl +Control +@item alt +Alternative/Option +@item altgr +Alternative Graphic (level 3) +@item lvl* +@code{*} may be any @math{2^n + 1} integer +@math{with 1 < n < 20}. +@item super +Super +@item hyper +Hyper +@item ultra +Ultra +@item caps +Caps (usually a lock key) +@item num +Num (usually a lock key) +@item scrl +Scroll (usually a lock key) +@item top +Top (historical) +@item front +Front (historical) +@item greek +Greek (historical) +@item compose +Compose (usally a dead key) +@item hexcompose +Hex-Compose (usally a dead key) +(Use to create aribitrary characters.) +@item longhexcompose +Long Hex-Compose (usally a dead key) +(Variant of hexcompose for longer codepoints.) +@item modelock +Mode Lock +@item letter * +@code{*} may be any UTF-8 encoded letter. +@end table +Keys that lock/unlock a modifer should be suffixed with a +blank space and a @code{lock}. If the key is a dead key +(even the compose key) should use @code{dead} instead. A +position, either @code{left}, @code{right}, @code{keypad} +or an index, followed by a blank space, should prefix any +key that occurs on multiple position on the keyboard, +unless it only appears on the keypad once and once not on +the keypad. Keys without any meaning should be identified +as @code{unknown}. Modifiers and dead keys should not +affect the value. + +@item Optional header: @code{Characters} +UTF-8 encoded string that has been written. + +@item Purpose: +Enable the user to use a keyboard, physical or on-screen. + +@item Purpose: +Enable programs to send keys as part of a +script or a reply of a recorded session. + +@item Compulsivity: +Highly-recommended, a computer is as good +as useless without a keyboard. + +@item Reference implementation: +@command{mds-kkbd}, @command{mds-kbd} and @command{mds-keytrans} +@end table + + + +@node enumerate-keyboards +@subsection enumerate-keyboards + +@table @asis +@item Identifying header: +@command{Command: enumerate-keyboards} + +@item Action: +List available keyboards. + +@item Required header: @code{Client ID} +Your ID, provided by the @code{ID assignment} header +in response to a @code{Command: assign-id} header. + +@item Instructions: +This message must be consumed by the first server that +receives it and implements support for it, and then send +out a @code{Command: keyboard-enumeration} populated with +the keyboard it provide as named in the @code{Keyboard} +header for protocols such as @code{Command: key-sent}. + +@item Purpose: +Make it possible for clients to list all available +keyboards so that can be configured individually. + +@item Compulsivity: +Optional. + +@item Reference implementation: +@command{mds-kkbd} and @command{mds-kbd} +@end table + + + +@node keyboard-enumeration +@subsection keyboard-enumeration + +@table @asis +@item Identifying header: +@command{Command: keyboard-enumeration} + +@item Action: +Response to @code{Command: enumerate-keyboards}. + +@item Required header: @code{To} +The ID received under @code{Client ID} header in +the @code{Command: enumerate-keyboards} message +that triggered this message to be broadcasted + +@item Required header: @code{In response to} +The ID received under the @code{Message ID} header +in the @code{Command: enumerate-keyboards} message +that triggered this message to be broadcasted. + +@item Required header: @code{Length} +Length of the message. + +@item Message: +New line separated list of available keyboards. + +@item Instructions: +All keyboard servers should listen for this message +and append all keyboards it implement to the message +once recieved. + +@item Purpose: +Make it possible for clients to list all available +keyboards so that can be configured individually + +@item Compulsivity: +Required if you implement @command{Command: enumerate-keyboards}. + +@item Reference implementation: +@command{mds-kkbd} and @command{mds-kbd} +@end table + + + +@node set-keyboard-leds +@subsection set-keyboard-leds + +@table @asis +@item Identifying header: +@command{Command: set-keyboard-leds} + +@item Action: +Activate and deactivate LED:s on a keyboard. + +@item Required header: @code{Active} +LED:s that should be turned on. If a LED is listed here +but not in @code{Mask} that LED should be turned on if +it is off, and turned off if it is on. + +The value is a single blank space separated list of LED:s: +@table @code +@item num +Num lock +@item caps +Caps lock +@item scroll +Scroll lock +@item compose +Compose +@end table +Unsupported LED:s should be silently ignored. + +@item Required header: @code{Mask} +LED:s listed here that do not appear in @code{Active} +should be turned off. The value of this header follows +the same rules as for @code{Active}. + +@item Optional header: @code{Keyboard} +A string that identifies the keyboard that should be +affected. If omitted all keyboard are affected. + +@item Purpose: +Enable keyboard layout servers to activate and deactive +LED:s on the keyboard to indicate active locks. + +@item Compulsivity: +Optional. + +@item Reference implementation: +@command{mds-kkbd}, @command{mds-kbd} and @command{mds-keytrans} +@end table + + + +@node get-keyboard-leds +@subsection get-keyboard-leds + +@table @asis +@item Identifying header: +@command{Command: get-keyboard-leds} + +@item Action: +List exisiting LED:s on a keyboard and their state. + +@item Required header: @code{Client ID} +Your ID, provided by the @code{ID assignment} header +in response to a @code{Command: assign-id} header. + +@item Required header: @code{Keyboard} +A string that identifies the keyboard that +should be affected. + +@item Response: +The server implementing support for +@code{Command: get-keyboard-leds} for the keyboard +indicated by @code{Keyboard} should send a message +back to the client indicated by rge @code{Client ID} +header (using the @code{To} header) with the headers: +@table @code +@item Active +List of currently turned on LED:s. +@item Present +List of LED:s that the server believes +to be present on the keyboards. +@end table +Both of these headers followes the rules of the +@code{Active} header under @code{Command: set-keyboard-leds}. + +@item Purpose: +Enable keyboard layout servers to automatically +set active locks when the server starts based on +currently active LED:s + +@item Compulsivity: +Recommended. Required if you implement support for +@code{Command: set-keyboard-leds}. If you do not +support this protocol servers and clients and stall +when they try to get the active LED:s + +@item Reference implementation: +@command{mds-kkbd}, @command{mds-kbd} and @command{mds-keytrans} +@end table + + + +@node keycode-map +@subsection keycode-map + +@table @asis +@item Identifying header: +@command{Command: keycode-map} + +@item Action: +Remap keyboard keycodes and query current mapping. + +@item Required header: @code{Action} +@table @code +@item remap +Remap keys if the value of the header @code{Action} +is @code{remap}. +@item reset +Reset all mappings to identity mapping if the value +of the header @code{Action} is @code{reset}. +@item query +Query mapping if the value of the header @code{Action} +is @code{query}. +@end table +Each affected server will send a message format +like that of @code{Action: remap} with current +mapping that are not identity mappings. + +@item Optional header: @code{Keyboard} +A string that identifies the keyboard that should be +affected. If omitted all keyboard are affected. + +@item Conditionally required header: @code{Client ID} +Your ID, provided by the @code{ID assignment} header +in response to a @code{Command: assign-id} header. +Required if @code{Action: query} is included in the headers. + +@item Conditionally optional header: @code{Length} +The length of the message. +Available and optional if @code{Action: remap} +is included in the headers. + +@item Message: +Each line contains contains two single space delimited numbers, +the first number is the keycode as determined by the scancode, +the second number is keycode that scancode should generate. +For example, @code{1 1} resets Escape to be mapped to Escape, +and @code{1 59} remaps Escape to F1, while +@example +1 59 +59 1 +@end example +swaps Escape and F1. + +@item Purpose: +Enable the user to swap or replace keys on the keyboard. + +@item Purpose: +Enable the user manually correct an incorrectly mapped keyboard. + +@item Compulsivity: +Optional. + +@item Reference implementation: +@command{mds-kbd} and @command{mds-kkbd} +@end table + + + +@node new-keyboard +@subsection new-keyboard + +@table @asis +@item Identifying header: +@command{Command: new-keyboard} + +@item Action: +Announce the existance of a new keyboard. + +@item Required header: @code{Length} +The length of the message. + +@item Message: +List of strings that identifies the keyboards +that have been added. + +@item Purpose: +Enable servers and clients to detect new keyboards. + +@item Compulsivity: +Recommended. + +@item Reference implementation: +@command{mds-kbd} and @command{mds-kkbd} +@end table + + + +@node old-keyboard +@subsection old-keyboard + +@table @asis +@item Identifying header: +@command{Command: old-keyboard} + +@item Action: +Announce the removal of an old keyboard. + +@item Required header: @command{Length} +The length of the message. + +@item Message: +List of strings that identifies the keyboards +that have been removed. + +@item Purpose: +Enable servers and clients to detect removal of keyboards. + +@item Compulsivity: +Recommended. + +@item Reference implementation: +@command{mds-kbd} @end table diff --git a/doc/protocols b/doc/protocols index 6270456..0e3936f 100644 --- a/doc/protocols +++ b/doc/protocols @@ -285,329 +285,3 @@ Compulsivity: required if supporting `Command: add-tray-icon` --------------------------------------------------------------------- -Command: key-sent - Announce a keyboard input event - -Required header: Keyboard - Any string that uniquely identifies the keyboard - Purpose: Enable multi-keyboard aware programs and give at - least on keyboard per seat in a multi-seat environment - Note: mds-kkbd uses `kernel` to indicate that it uses the kernel - and thus lumps together all keyboards. - -Required header: Released - `yes` if the key was released - `no` otherwise, that is, held down or pressed - Note: pause/break is automatically released directly after it - has been pressed. This is feature built into keyboards - and servers should not try to circumvent this - -Required header: Keycode - An unsigned 14-bit integer identifying the key, may be remapped - -Optional header: Scancode - Either an unsigned 7-bit integer or a single blank space - separated trio of unsigned 7-bit integers, identifying the key. - This is the scancode sent from the keyboard and optionally - unified by the keyboard driver, however with the typed/released - bit zeroed out. This may not be remapped. - -Optional header: Modifiers - Single blank space separated list of active modifiers: - shift) Shift (level 2) - ctrl) Control - alt) Alternative/Option - altgr) Alternative Graphic (level 3) - lvl*) * may be any 2ⁿ + 1 integer with 1 < n < 20 - super) Super - hyper) Hyper - ultra) Ultra - caps) Caps (usually a lock key) - num) Num (usually a lock key) - scrl) Scroll (usually a lock key) - top) Top (historical) - front) Front (historical) - greek) Greek (historical) - compose) Compose (rare, it is usally a dead key) - Any key that has been locked should be prefix with `+`, - if the key has been locked by nullified with non-lock - modifier it should be prefixed with a `-`. - If no modifier is active or has been nullified, `none` - should be used. - -Optional header: Key - A textual representation of the key that has been typed or - released, as mapped by the keyboard layout. - esc) Escape - f*) F* where * is any integer - sysrq) System Request/Print Screen - scrl) Scroll (lock) - break) Break/Pause - backspace) Backspace - tab) Tab - return) Return/Enter - space) Blank Space - menu) Application Menu - ins) Insert - home) Home - pgup) Page Up - del) Delete - end) End - pgdown) Page Down - up) Up Arrow - left) Left Arrow - down) Down Arrow - right) Right Arrow - shift) Shift (level 2) - begin) Begin (keypad 5 in nagivation mode) - ctrl) Control - alt) Alternative/Option - altgr) Alternative Graphic (level 3) - lvl*) * may be any 2ⁿ + 1 integer with 1 < n < 20 - super) Super - hyper) Hyper - ultra) Ultra - caps) Caps (usually a lock key) - num) Num (usually a lock key) - scrl) Scroll (usually a lock key) - top) Top (historical) - front) Front (historical) - greek) Greek (historical) - compose) Compose (usally a dead key) - hexcompose) Hex-Compose (usally a dead key) - (use to create aribitrary characters) - longhexcompose) Long Hex-Compose (usally a dead key) - (variant of hexcompose for longer codepoints) - modelock) Mode Lock - letter *) * may be any UTF-8 encoded letter - Keys that lock/unlock a modifer should be suffixed with a - blank space and a `lock`. If the key is a dead key (even - the compose key) should use `dead` instead. A position, - either `left`, `right`, `keypad` or an index, followed by a - blank space, should prefix any key that occurs on multiple - position on the keyboard, unless it only appears on the - keypad once and once not on the keypad. Keys without any - meaning should be identified as `unknown`. Modifiers and - dead keys should not affect the value. - -Optional header: Characters - UTF-8 encoded string that has been written - -Purpose: Enable the user to use a keyboard, physical or on-screen -Purpose: Enable programs to send keys as part of a script or - a reply of a recorded session - -Compulsivity: highly-recommended, a computer is as good as useless - without a keyboard - -Reference implementation: kkbd -Reference implementation: kbd -Reference implementation: keytrans - ---------------------------------------------------------------------- - -Command: enumerate-keyboards - List available keyboards - -Required header: Client ID - Your ID, provided by `ID assignment` - in response to `Command: assign-id` - -Instructions: This message must be consumed by the first server - that receives it and implements support for it, - and then send out a `Command: keyboard-enumeration` - populated with the keyboard it provide as named - in the `Keyboard` header for protocols such as - `Command: key-sent` - -Purpose: Make it possible for clients to list all available keyboards - so that can be configured individually - -Compulsivity: optional - -Reference implementation: kkbd -Reference implementation: kbd - ---------------------------------------------------------------------- - -Command: keyboard-enumeration - Response to `enumerate-keyboards` - -Required header: To - The ID received under `Client ID` in the - `Command: enumerate-keyboards` message that triggered this - message to be broadcasted - -Required header: In response to - The ID received under `Message ID` in the - `Command: enumerate-keyboards` message that triggered this - message to be broadcasted - -Required header: Length - Length of the message - -Message: New line separated list of available keyboards - -Instructions: All keyboard servers should listen for this message - and append all keyboards it implement to the message - once recieved - -Purpose: Make it possible for clients to list all available keyboards - so that can be configured individually - -Compulsivity: required if you implement `Command: enumerate-keyboards` - -Reference implementation: kkbd -Reference implementation: kbd - ---------------------------------------------------------------------- - -Command: set-keyboard-leds - Activate and deactivate LED:s on a keyboard - -Required header: Active - LED:s that should be turned on. - If a LED is listed here but not in `Mask` that LED - should be turned on if it is off, and turned off - if it is on. - The value is a single blank space separated list of LED:s: - num) Num lock - caps) Caps lock - scroll) Scroll lock - compose) Compose - Unsupported LED:s should be silently ignored. - -Required header: Mask - LED:s listed here that do not appear in `Active` - should be turned off. - The value of this header follows the same rules - as for `Active`. - -Optional header: Keyboard - A string that identifies the keyboard that should be - affected. If omitted all keyboard are affected. - -Purpose: Enable keyboard layout servers to activate and deactive - LED:s on the keyboard to indicate active locks - -Compulsivity: optional - -Reference implementation: kkbd -Reference implementation: kbd -Reference implementation: kbdtrans - ---------------------------------------------------------------------- - -Command: get-keyboard-leds - List exisiting LED:s on a keyboard and their state - -Required header: Client ID - Your ID, provided by `ID assignment` - in response to `Command: assign-id` - -Required header: Keyboard - A string that identifies the keyboard that should be - affected - -Response: The server implementing support for - `Command: get-keyboard-leds` for the keyboard indicated - by `Keyboard` should send a message back to the client - indicated by `Client ID` (using the `To` header) with - the headers: - Active: list of currently turned on LED:s - Present: list of LED:s that the server believes - to be present on the keyboards - Both of these headers followes the rules of the - `Active` header under `Command: set-keyboard-leds` - -Purpose: Enable keyboard layout servers to automatically - set active locks when the server starts based on - currently active LED:s - -Compulsivity: recommended, required if you implement support for - `Command: set-keyboard-leds`. If you do not support - this protocol servers and clients and stall when - they try to get the active LED:s - -Reference implementation: kkbd -Reference implementation: kbd -Reference implementation: kbdtrans - ---------------------------------------------------------------------- - -Command: keycode-map - Remap keyboard keycodes and query current mapping - -Required header: Action - remap) Remap keys - reset) Reset all mappings to identity mapping - query) Query mapping - Each affected server will send a message format - like that of `Action: remap` with current mapping - that are not identity mappings - -Optional header: Keyboard - A string that identifies the keyboard that should be - affected. If omitted all keyboard are affected. - -Conditionally required header: Client ID - Required if: `Action: query` - Your ID, provided by `ID assignment` - in response to `Command: assign-id` - -Conditionally optional header: Length - Available and optional if: `Action: remap` - The length of the message - -Message: Each line contains contains two single space delimited numbers, - the first number is the keycode as determined by the scancode, - the second number is keycode that scancode should generate. - For example, `1 1` resets Escape to be mapped to Escape, - and `1 59` remaps Escape to F1, while `1 59\n59 1`, where - `\n` is a new lone, swaps Escape and F1. - -Purpose: Enable the user to swap or replace keys on the keyboard -Purpose: Enable the user manually correct an incorrectly mapped keyboard - -Compulsivity: optional - -Reference implementation: kkbd -Reference implementation: kbd - ---------------------------------------------------------------------- - -Command: new-keyboard - Announce the existance of a new keyboard - -Required header: Length - The length of the message - -Message: List of strings that identifies the keyboards - that have been added. - -Purpose: Enable servers and clients to detect new keyboards - -Compulsivity: recommended - -Reference implementation: kkbd -Reference implementation: kbd - ---------------------------------------------------------------------- - -Command: old-keyboard - Announce the removal of an old keyboard - -Required header: Length - The length of the message - -Message: List of strings that identifies the keyboards - that have been removed. - -Purpose: Enable servers and clients to detect removal of keyboards - -Compulsivity: recommended - -Reference implementation: kbd - ---------------------------------------------------------------------- - |