Docs

Appearance

The X Keyboard Extension:

Library Specification

Amber J. Benson

Gary Aitken

Erik Fortune

Silicon Graphics, Inc

Donna Converse

X Consortium, Inc

George Sachs

Hewlett-Packard Company

Will Walker

Digital Equipment Corporation

X Version 11, Release 7.7

Copyright © 1995, 1996 X Consortium Inc., Silicon Graphics Inc., Hewlett-Packard Company, Digital Equipment Corporation

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this notice, the names of the X Consortium, Silicon Graphics Inc., Hewlett-Packard Company, and Digital Equipment Corporation shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization.

Table of Contents

Acknowledgement
1. Overview
Core X Protocol Support for Keyboards
Xkb Keyboard Extension Support for Keyboards
Xkb Extension Components
Groups and Shift Levels
Radio Groups
Client Types
Compatibility With the Core Protocol
Additional Protocol Errors
Extension Library Functions
Error Indications
2. Initialization and General Programming Information
Extension Header Files
Extension Name
Determining Library Compatibility
Initializing the Keyboard Extension
Disabling the Keyboard Extension
Protocol Errors
Display and Device Specifications in Function Calls
3. Data Structures
Allocating Xkb Data Structures
Adding Data and Editing Data Structures
Making Changes to the Server’s Keyboard Description
Tracking Keyboard Changes in the Server
Freeing Data Structures
4. Xkb Events
Xkb Event Types
Xkb Event Data Structures
Selecting Xkb Events
Event Masks
Unified Xkb Event Type
5. Keyboard State
Keyboard State Description
Changing the Keyboard State
Changing Modifiers
Changing Groups
Determining Keyboard State
Tracking Keyboard State
6. Complete Keyboard Description
The XkbDescRec Structure
Obtaining a Keyboard Description from the Server
Tracking Changes to the Keyboard Description in the Server
Allocating and Freeing a Keyboard Description
7. Virtual Modifiers
Virtual Modifier Names and Masks
Modifier Definitions
Binding Virtual Modifiers to Real Modifiers
Virtual Modifier Key Mapping
Inactive Modifier Sets
Conventions
Example
8. Indicators
Indicator Names
Indicator Data Structures
XkbIndicatorRec
XkbIndicatorMapRec
Getting Information About Indicators
Getting Indicator State
Getting Indicator Information by Index
Getting Indicator Information by Name
Changing Indicator Maps and State
Effects of Explicit Changes on Indicators
Changing Indicator Maps by Index
Changing Indicator Maps by Name
The XkbIndicatorChangesRec Structure
Tracking Changes to Indicator State or Map
Allocating and Freeing Indicator Maps
9. Bells
Bell Names
Audible Bells
Bell Functions
Generating Named Bells
Generating Named Bell Events
Forcing a Server-Generated Bell
Detecting Bells
10. Keyboard Controls
Controls that Enable and Disable Other Controls
The EnabledControls Control
The AutoReset Control
Control for Bell Behavior
The AudibleBell Control
Controls for Repeat Key Behavior
The PerKeyRepeat Control
The RepeatKeys Control
The DetectableAutorepeat Control
Controls for Keyboard Overlays (Overlay1 and Overlay2 Controls)
Controls for Using the Mouse from the Keyboard
The MouseKeys Control
The MouseKeysAccel Control
Controls for Better Keyboard Access by Physically Impaired Persons
The AccessXKeys Control
The AccessXTimeout Control
The AccessXFeedback Control
AccessXNotify Events
StickyKeys, RepeatKeys, and MouseKeys Events
The SlowKeys Control
The BounceKeys Control
The StickyKeys Control
Controls for General Keyboard Mapping
The GroupsWrap Control
The IgnoreLockMods Control
The IgnoreGroupLock Control
The InternalMods Control
The XkbControlsRec Structure
Querying Controls
Changing Controls
The XkbControlsChangesRec Structure
Tracking Changes to Keyboard Controls
Allocating and Freeing an XkbControlsRec
The Miscellaneous Per-client Controls
11. X Library Controls
Controls Affecting Keycode-to-String Translation
ForceLatin1Lookup
ConsumeLookupMods
AlwaysConsumeShiftAndLock
Controls Affecting Compose Processing
ConsumeKeysOnComposeFail
ComposeLED
BeepOnComposeFail
Controls Effecting Event Delivery
IgnoreNewKeyboards
Manipulating the Library Controls
Determining Which Library Controls are Implemented
Determining the State of the Library Controls
Changing the State of the Library Controls
12. Interpreting Key Events
Effects of Xkb on the Core X Library
Effects of Xkb on Event State
Effects of Xkb on MappingNotify Events
X Library Functions Affected by Xkb
Xkb Event and Keymap Functions
13. Keyboard Geometry
Shapes and Outlines
Sections
Rows and Keys
Doodads
Overlay Rows and Overlay Keys
Drawing a Keyboard Representation
Geometry Data Structures
DoodadRec Structures
Getting Keyboard Geometry From the Server
Using Keyboard Geometry
Adding Elements to a Keyboard Geometry
Allocating and Freeing Geometry Components
14. Xkb Keyboard Mapping
Notation and Terminology
Core Implementation
Xkb Implementation
Getting Map Components from the Server
Changing Map Components in the Server
The XkbMapChangesRec Structure
Tracking Changes to Map Components
Allocating and Freeing Client and Server Maps
Allocating an Empty Client Map
Freeing a Client Map
Allocating an Empty Server Map
Freeing a Server Map
15. Xkb Client Keyboard Mapping
The XkbClientMapRec Structure
Key Types
The Canonical Key Types
Getting Key Types from the Server
Changing the Number of Levels in a Key Type
Copying Key Types
Key Symbol Map
Per-Key Key Type Indices
Per-Key Group Information
Key Width
Offset in to the Symbol Map
Getting the Symbol Map for Keys from the Server
Changing the Number of Groups and Types Bound to a Key
Changing the Number of Symbols Bound to a Key
The Per-Key Modifier Map
Getting the Per-Key Modifier Map from the Server
16. Xkb Server Keyboard Mapping
Key Actions
The XkbAction Structure
The XkbAnyAction Structure
Actions for Changing Modifiers’ State
Actions for Changing Group State
Actions for Moving the Pointer
Actions for Simulating Pointer Button Press and Release
Actions for Changing the Pointer Button Simulated
Actions for Locking Modifiers and Group
Actions for Changing the Active Screen
Actions for Changing Boolean Controls State
Actions for Generating Messages
Actions for Generating a Different Keycode
Actions for Generating DeviceButtonPress and DeviceButtonRelease
Actions for Simulating Events from Device Valuators
Obtaining Key Actions for Keys from the Server
Changing the Number of Actions Bound to a Key
Key Behavior
Radio Groups
The XkbBehavior Structure
Obtaining Key Behaviors for Keys from the Server
Explicit Components—Avoiding Automatic Remapping by the Server
Obtaining Explicit Components for Keys from the Server
Virtual Modifier Mapping
Obtaining Virtual Modifier Bindings from the Server
Obtaining Per-Key Virtual Modifier Mappings from the Server
17. The Xkb Compatibility Map
The XkbCompatMap Structure
Xkb State to Core Protocol State Transformation
Core Keyboard Mapping to Xkb Keyboard Mapping Transformation
Xkb Keyboard Mapping to Core Keyboard Mapping Transformations
Getting Compatibility Map Components From the Server
Using the Compatibility Map
Changing the Server’s Compatibility Map
Tracking Changes to the Compatibility Map
Allocating and Freeing the Compatibility Map
18. Symbolic Names
The XkbNamesRec Structure
Symbolic Names Masks
Getting Symbolic Names From the Server
Changing Symbolic Names on the Server
Tracking Name Changes
Allocating and Freeing Symbolic Names
19. Replacing a Keyboard "On the Fly"
20. Server Database of Keyboard Components
Component Names
Listing the Known Keyboard Components
Component Hints
Building a Keyboard Description Using the Server Database
21. Attaching Xkb Actions to X Input Extension Devices
XkbDeviceInfoRec
Querying Xkb Features for Non-KeyClass Input Extension Devices
Allocating, Initializing, and Freeing the XkbDeviceInfoRec Structure
Setting Xkb Features for Non-KeyClass Input Extension Devices
XkbExtensionDeviceNotify Event
Tracking Changes to Extension Devices
22. Debugging Aids
Glossary

List of Tables

1.1. Function Error Returns Due to Extension Problems
2.1. Xkb Protocol Errors
2.2. BadKeyboard Protocol Error resource_id Values
4.1. Xkb Event Types
4.2. XkbSelectEvents Mask Constants
5.1. Real Modifier Masks
5.2. Symbolic Group Names
5.3. XkbStateNotify Event Detail Masks
6.1. XkbDescRec Component References
6.2. Mask Bits for XkbDescRec
8.1. XkbIndicatorMapRec flags Field
8.2. XkbIndicatorMapRec which_groups and groups, Keyboard Drives Indicator
8.3. XkbIndicatorMapRec which_groups and groups, Indicator Drives Keyboard
8.4. XkbIndicatorMapRec which_mods and mods, Keyboard Drives Indicator
8.5. XkbIndicatorMapRec which_mods and mods, Indicator Drives Keyboard
9.1. Predefined Bells
9.2. Bell Sounding and Bell Event Generating
10.1. Xkb Keyboard Controls
10.2. MouseKeysAccel Fields
10.3. AccessXFeedback Masks
10.4. AccessXNotify Events
10.5. AccessXNotify Event Details
10.6. Xkb Controls
10.7. Controls Mask Bits
10.8. GroupsWrap options (groups_wrap field)
10.9. Access X Enable/Disable Bits (ax_options field)
11.1. Library Control Masks
13.1. Doodad Types
14.1. Xkb Mapping Component Masks and Convenience Functions
14.2. XkbMapChangesRec Masks
14.3. XkbAllocClientMap Masks
14.4. XkbAllocServerMap Masks
15.1. Example Key Type
15.2. group_info Range Normalization
15.3. Group Index Constants
16.1. Action Types
16.2. Modifier Action Types
16.3. Modifier Action Flags
16.4. Group Action Types
16.5. Group Action Flags
16.6. Pointer Action Types
16.7. Pointer Button Action Types
16.8. Pointer Button Action Flags
16.9. Pointer Default Flags
16.10. ISO Action Flags when XkbSA_ISODfltIsGroup is Set
16.11. ISO Action Flags when XkbSA_ISODfltIsGroup is Not Set
16.12. ISO Action Affect Field Values
16.13. Switch Screen Action Flags
16.14. Controls Action Types
16.15. Control Action Flags
16.16. Message Action Flags
16.17. Device Button Action Types
16.18. Device Button Action Flags
16.19. Device Valuator v<n>_what High Bits Values
16.20. Key Behaviors
16.21. Explicit Component Masks
17.1. Symbol Interpretation Match Criteria
17.2. Compatibility Map Component Masks
18.1. Symbolic Names Masks
18.2. XkbNameChanges Fields
19.1. XkbNewKeyboardNotifyEvent Details
20.1. Server Database Keyboard Components
20.2. XkbComponentNameRec Flags Bits
20.3. Want and Need Mask Bits and Required Names Components
20.4. XkbDescRec Components Returned for Values of Want & Needs
21.1. XkbDeviceInfoRec Mask Bits
22.1. Debug Control Masks