The X Keyboard Extension: Library Specification
Total Page:16
File Type:pdf, Size:1020Kb
The X Keyboard Extension: Library Specification Library Version 1.0 / Document Revision 1.1 X Consortium Standard X Version 11, Release 6.4 Amber J. Benson and Gary Aitken Erik Fortune Silicon Graphics, Inc. Donna Converse X Consortium Inc. George Sachs Hewlett-Packard Company Will Walker Digital Equipment Corporation Copyright © 1995, 1996 X Consortium Inc. Copyright © 1995, 1996 Silicon Graphics Inc. Copyright © 1995, 1996 Hewlett-Packard Company Copyright © 1995, 1996 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 NONINFRINGE- MENT. 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 authori- zation. Acknowledgments This document is the result of a great deal of hard work by a great many people. Without Erik For- tune’s work as Architect of the X Keyboard Extension and the longtime support of Silicon Graph- ics Inc. there would not be a keyboard extension. We gratefully thank Will Walker and George Sachs for their help and expertise in providing some of the content for this document, and Digital Equipment Corporation and Hewlett-Packard for allowing them to participate in this project, and we are deeply indebted to IBM for providing the funding to complete this library specification. Most of all, we thank Gary Aitken and Amber J. Benson for their long hours and late nights as ultimate authors of this specification, and for serving as authors, document editors, and XKB pro- tocol and implementation reviewers. Their commitment to accuracy and completeness, their attention to detail, their keen insight, and their good natures when working under tremendous pressure are in some measure responsible not only for the quality of this document, but for the quality of the Keyboard extension itself. Matt Landau Manager, X Window System X Consortium Inc. 5 February 1996 The X Keyboard Extension The following table shows the font conventions used in this document: Usage Font example Key Labels Num_Lock New terms SlowKeys acceptance delay Function definitions XkbColorPtr XkbAddGeomColor(geom,spec,pixel) Function references XkbAddGeomColor Parameters or arguments geom Structure definitions XkbGeometryRec Structure references XkbGeometryRec References to fields in a data structure key_aliases References to masks, modifiers, controls IgnoreGroupLock November 10, 1997 Library Version 1.0/Document Revision 1.1 The X Keyboard Extension 1 Overview..................................................................................................................1 1.1 Core X Protocol Support for Keyboards ............................................................................. 1 1.2 Xkb Keyboard Extension Support for Keyboards............................................................... 1 1.3 Xkb Extension Components................................................................................................ 1 1.3.1 Groups and Shift Levels........................................................................................ 3 1.3.2 Radio Groups ........................................................................................................ 3 1.4 Client Types......................................................................................................................... 3 1.5 Compatibility With the Core Protocol................................................................................. 4 1.6 Additional Protocol Errors .................................................................................................. 4 1.7 Extension Library Functions ............................................................................................... 4 1.7.1 Error Indications ................................................................................................... 4 2 Initialization and General Programming Information..............................................6 2.1 Extension Header Files........................................................................................................ 6 2.2 Extension Name .................................................................................................................. 6 2.3 Determining Library Compatibility .................................................................................... 6 2.4 Initializing the Keyboard Extension.................................................................................... 7 2.5 Disabling the Keyboard Extension...................................................................................... 8 2.6 Protocol Errors .................................................................................................................... 9 2.7 Display and Device Specifications in Function Calls ......................................................... 9 3 Data Structures.......................................................................................................11 3.1 Allocating Xkb Data Structures ........................................................................................ 11 3.2 Adding Data and Editing Data Structures ......................................................................... 11 3.3 Making Changes to the Server’s Keyboard Description ................................................... 12 3.4 Tracking Keyboard Changes in the Server........................................................................ 12 3.5 Freeing Data Structures..................................................................................................... 13 4 Xkb Events.............................................................................................................14 4.1 Xkb Event Types ............................................................................................................... 14 4.2 Xkb Event Data Structures................................................................................................ 15 4.3 Selecting Xkb Events ........................................................................................................ 15 4.3.1 Event Masks........................................................................................................ 17 4.4 Unified Xkb Event Type.................................................................................................... 18 5 Keyboard State.......................................................................................................19 5.1 Keyboard State Description............................................................................................... 19 5.2 Changing the Keyboard State............................................................................................ 22 5.2.1 Changing Modifiers ............................................................................................ 22 5.2.2 Changing Groups ................................................................................................ 23 5.3 Determining Keyboard State ............................................................................................. 23 5.4 Tracking Keyboard State................................................................................................... 24 6 Complete Keyboard Description............................................................................27 6.1 The XkbDescRec Structure............................................................................................... 27 6.2 Obtaining a Keyboard Description from the Server.......................................................... 28 6.3 Tracking Changes to the Keyboard Description in the Server .......................................... 28 6.4 Allocating and Freeing a Keyboard Description............................................................... 28 7 Virtual Modifiers....................................................................................................30 7.1 Virtual Modifier Names and Masks .................................................................................. 30 November 10, 1997 Library Version 1.0/Document Revision 1.1 TOC-1 The X Keyboard Extension 7.2 Modifier Definitions .......................................................................................................... 30 7.3 Binding Virtual Modifiers to Real Modifiers .................................................................... 31 7.4 Virtual Modifier Key Mapping.........................................................................................