/usr/share/doc/libx11-dev/XKB/xkblib.html

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The X Keyboard Extension:</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><style xmlns="" type="text/css">/*
 * Copyright (c) 2011 Gaetan Nadon
 * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
 *
 * 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 (including the next
 * paragraph) 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 AUTHORS OR COPYRIGHT HOLDERS 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.
 */

/*
 * Shared stylesheet for X.Org documentation translated to HTML format
 * http://www.sagehill.net/docbookxsl/UsingCSS.html
 * http://www.w3schools.com/css/default.asp
 * https://addons.mozilla.org/en-US/firefox/addon/web-developer/developers
 * https://addons.mozilla.org/en-US/firefox/addon/font-finder/
 */

/*
 * The sans-serif fonts are considered more legible on a computer screen
 * http://dry.sailingissues.com/linux-equivalents-verdana-arial.html
 *
 */
body {
  font-family: "Bitstream Vera Sans", "DejaVu Sans", Tahoma, Geneva, Arial, Sans-serif;
  /* In support of using "em" font size unit, the w3c recommended method */
  font-size: 100%;
}

/*
 * Selection: all elements requiring mono spaced fonts.
 *
 * The family names attempt to match the proportionally spaced font
 * family names such that the same font name is used for both.
 * We'd like to use Bitstream, for example, in both proportionally and
 * mono spaced font text.
 */
.command,
.errorcode,
.errorname,
.errortype,
.filename,
.funcsynopsis,
.function,
.parameter,
.programlisting,
.property,
.screen,
.structname,
.symbol,
.synopsis,
.type
{
  font-family:  "Bitstream Vera Sans Mono", "DejaVu Sans Mono", Courier, "Liberation Mono", Monospace;
}

/*
 * Books have a title page, a preface, some chapters and appendices,
 * a glossary, an index and a bibliography, in that order.
 *
 * An Article has no preface and no chapters. It has sections, appendices,
 * a glossary, an index and a bibliography.
 */

/*
 * Selection: book main title and subtitle
 */
div.book>div.titlepage h1.title,
div.book>div.titlepage h2.subtitle {
  text-align: center;
}

/*
 * Selection: article main title and subtitle
 */
div.article>div.titlepage h2.title,
div.article>div.titlepage h3.subtitle,
div.article>div.sect1>div.titlepage h2.title,
div.article>div.section>div.titlepage h2.title {
  text-align: center;
}

/*
 * Selection: various types of authors and collaborators, individuals or corporate
 *
 * These authors are not always contained inside an authorgroup.
 * They can be contained inside a lot of different parent types where they might
 * not be centered.
 * Reducing the margin at the bottom makes a visual separation between authors
 * We specify here the ones on the title page, others may be added based on merit.
 */
div.titlepage .authorgroup,
div.titlepage .author,
div.titlepage .collab,
div.titlepage .corpauthor,
div.titlepage .corpcredit,
div.titlepage .editor,
div.titlepage .othercredit {
  text-align: center;
  margin-bottom: 0.25em;
}

/*
 * Selection: the affiliation of various types of authors and collaborators,
 * individuals or corporate.
 */
div.titlepage .affiliation {
  text-align: center;
}

/*
 * Selection: product release information (X Version 11, Release 7)
 *
 * The releaseinfo element can be contained inside a lot of different parent
 * types where it might not be centered.
 * We specify here the one on the title page, others may be added based on merit.
 */
div.titlepage p.releaseinfo {
  font-weight: bold;
  text-align: center;
}

/*
 * Selection: publishing date
 */
div.titlepage .pubdate {
  text-align: center;
}

/*
 * The legal notices are displayed in smaller sized fonts
 * Justification is only supported in IE and therefore not requested.
 *
 */
.legalnotice {
  font-size: small;
  font-style: italic;
}

/*
 * For documentation having multiple licenses, the copyright and legalnotice
 * elements sequence cannot instantiated multiple times.
 * The copyright notice and license text are therefore coded inside a legalnotice
 * element. The role attribute on the paragraph is used to allow styling of the
 * copyright notice text which should not be italicized.
 */
p.multiLicensing {
  font-style: normal;
  font-size: medium;
}

/*
 * Selection: book or article main ToC title
 * A paragraph is generated for the title rather than a level 2 heading.
 * We do not want to select chapters sub table of contents, only the main one
 */
div.book>div.toc>p,
div.article>div.toc>p {
  font-size: 1.5em;
  text-align: center;
}

/*
 * Selection: major sections of a book or an article
 *
 * Unlike books, articles do not have a titlepage element for appendix.
 * Using the selector "div.titlepage h2.title" would be too general.
 */
div.book>div.preface>div.titlepage h2.title,
div.book>div.chapter>div.titlepage h2.title,
div.article>div.sect1>div.titlepage h2.title,
div.article>div.section>div.titlepage h2.title,
div.book>div.appendix>div.titlepage h2.title,
div.article>div.appendix h2.title,
div.glossary>div.titlepage h2.title,
div.index>div.titlepage h2.title,
div.bibliography>div.titlepage h2.title {
   /* Add a border top over the major parts, just like printed books */
   /* The Gray color is already used for the ruler over the main ToC. */
  border-top-style: solid;
  border-top-width: 2px;
  border-top-color: Gray;
  /* Put some space between the border and the title */
  padding-top: 0.2em;
  text-align: center;
}

/*
 * A Screen is a verbatim environment for displaying text that the user might
 * see on a computer terminal. It is often used to display the results of a command.
 *
 * http://www.css3.info/preview/rounded-border/
 */
.screen {
  background: #e0ffff;
  border-width: 1px;
  border-style: solid;
  border-color: #B0C4DE;
  border-radius: 1.0em;
  /* Browser's vendor properties prior to CSS 3 */
  -moz-border-radius: 1.0em;
  -webkit-border-radius: 1.0em;
  -khtml-border-radius: 1.0em;
  margin-left: 1.0em;
  margin-right: 1.0em;
  padding: 0.5em;
}

/*
 * Emphasis program listings with a light shade of gray similar to what
 * DocBook XSL guide does: http://www.sagehill.net/docbookxsl/ProgramListings.html
 * Found many C API docs on the web using like shades of gray.
 */
.programlisting {
  background: #F4F4F4;
  border-width: 1px;
  border-style: solid;
  border-color: Gray;
  padding: 0.5em;
}

/*
 * Emphasis functions synopsis using a darker shade of gray.
 * Add a border such that it stands out more.
 * Set the padding so the text does not touch the border.
 */
.funcsynopsis, .synopsis {
  background: #e6e6fa;
  border-width: 1px;
  border-style: solid;
  border-color: Gray;
  clear: both;
  margin: 0.5em;
  padding: 0.25em;
}

/*
 * Selection: paragraphs inside synopsis
 *
 * Removes the default browser margin, let the container set the padding.
 * Paragraphs are not always used in synopsis
 */
.funcsynopsis p,
.synopsis p {
  margin: 0;
  padding: 0;
}

/*
 * Selection: variable lists, informal tables and tables
 *
 * Note the parameter name "variablelist.as.table" in xorg-xhtml.xsl
 * A table with rows and columns is constructed inside div.variablelist
 *
 * Set the left margin so it is indented to the right
 * Display informal tables with single line borders
 */
table {
  margin-left: 0.5em;
  border-collapse: collapse;
}

/*
 * Selection: paragraphs inside tables
 *
 * Removes the default browser margin, let the container set the padding.
 * Paragraphs are not always used in tables
 */
td p {
  margin: 0;
  padding: 0;
}

/*
 * Add some space between the left and right column.
 * The vertical alignment helps the reader associate a term
 * with a multi-line definition.
 */
td, th {
  padding-left: 1.0em;
  padding-right: 1.0em;
  vertical-align: top;
}

.warning {
  border: 1px solid red;
  background: #FFFF66;
  padding-left: 0.5em;
}
</style></head><body><div class="book"><div class="titlepage"><div><div><h1 class="title"><a id="xkblib"></a>The X Keyboard Extension:</h1></div><div><h2 class="subtitle">Library Specification</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Amber</span> <span class="othername">J.</span> <span class="surname">Benson</span></h3></div><div class="author"><h3 class="author"><span class="firstname">Gary</span> <span class="surname">Aitken</span></h3></div><div class="author"><h3 class="author"><span class="firstname">Erik</span> <span class="surname">Fortune</span></h3><div class="affiliation"><span class="orgname">Silicon Graphics, Inc<br /></span></div></div><div class="author"><h3 class="author"><span class="firstname">Donna</span> <span class="surname">Converse</span></h3><div class="affiliation"><span class="orgname">X Consortium, Inc<br /></span></div></div><div class="author"><h3 class="author"><span class="firstname">George</span> <span class="surname">Sachs</span></h3><div class="affiliation"><span class="orgname">Hewlett-Packard Company<br /></span></div></div><div class="author"><h3 class="author"><span class="firstname">Will</span> <span class="surname">Walker</span></h3><div class="affiliation"><span class="orgname">Digital Equipment Corporation<br /></span></div></div></div></div><div><p class="releaseinfo">X Version 11, Release 7.7</p></div><div><p class="copyright">Copyright © 1995, 1996 X Consortium Inc., Silicon Graphics Inc., Hewlett-Packard Company, Digital Equipment Corporation</p></div><div><div class="legalnotice"><a id="idp61206332"></a><p>
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:
</p><p>
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
</p><p>
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.
</p><p>
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.
</p></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="preface"><a href="#acknowledgement">Acknowledgement</a></span></dt><dt><span class="chapter"><a href="#Overview">1. Overview</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Core_X_Protocol_Support_for_Keyboards">Core X Protocol Support for Keyboards</a></span></dt><dt><span class="sect1"><a href="#Xkb_Keyboard_Extension_Support_for_Keyboards">Xkb Keyboard Extension Support for Keyboards</a></span></dt><dt><span class="sect1"><a href="#Xkb_Extension_Components">Xkb Extension Components</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Groups_and_Shift_Levels">Groups and Shift Levels</a></span></dt><dt><span class="sect2"><a href="#Radio_Groups">Radio Groups</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Client_Types">Client Types</a></span></dt><dt><span class="sect1"><a href="#Compatibility_With_the_Core_Protocol">Compatibility With the Core Protocol</a></span></dt><dt><span class="sect1"><a href="#Additional_Protocol_Errors">Additional Protocol Errors</a></span></dt><dt><span class="sect1"><a href="#Extension_Library_Functions">Extension Library Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Error_Indications">Error Indications</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Initialization_and_General_Programming_Information">2. Initialization and General Programming Information</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Extension_Header_Files">Extension Header Files</a></span></dt><dt><span class="sect1"><a href="#Extension_Name">Extension Name</a></span></dt><dt><span class="sect1"><a href="#Determining_Library_Compatibility">Determining Library Compatibility</a></span></dt><dt><span class="sect1"><a href="#Initializing_the_Keyboard_Extension">Initializing the Keyboard Extension</a></span></dt><dt><span class="sect1"><a href="#Disabling_the_Keyboard_Extension">Disabling the Keyboard Extension</a></span></dt><dt><span class="sect1"><a href="#Protocol_Errors">Protocol Errors</a></span></dt><dt><span class="sect1"><a href="#Display_and_Device_Specifications_in_Function_Calls">Display and Device Specifications in Function Calls</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Data_Structures">3. Data Structures</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Allocating_Xkb_Data_Structures">Allocating Xkb Data Structures</a></span></dt><dt><span class="sect1"><a href="#Adding_Data_and_Editing_Data_Structures">Adding Data and Editing Data Structures</a></span></dt><dt><span class="sect1"><a href="#Making_Changes_to_the_Servers_Keyboard_Description">Making Changes to the Server’s Keyboard Description</a></span></dt><dt><span class="sect1"><a href="#Tracking_Keyboard_Changes_in_the_Server">Tracking Keyboard Changes in the Server</a></span></dt><dt><span class="sect1"><a href="#Freeing_Data_Structures">Freeing Data Structures</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Xkb_Events">4. Xkb Events</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Xkb_Event_Types">Xkb Event Types</a></span></dt><dt><span class="sect1"><a href="#Xkb_Event_Data_Structures">Xkb Event Data Structures</a></span></dt><dt><span class="sect1"><a href="#Selecting_Xkb_Events">Selecting Xkb Events</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Event_Masks">Event Masks</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Unified_Xkb_Event_Type">Unified Xkb Event Type</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Keyboard_State">5. Keyboard State</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Keyboard_State_Description">Keyboard State Description</a></span></dt><dt><span class="sect1"><a href="#Changing_the_Keyboard_State">Changing the Keyboard State</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Changing_Modifiers">Changing Modifiers</a></span></dt><dt><span class="sect2"><a href="#Changing_Groups">Changing Groups</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Determining_Keyboard_State">Determining Keyboard State</a></span></dt><dt><span class="sect1"><a href="#Tracking_Keyboard_State">Tracking Keyboard State</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Complete_Keyboard_Description">6. Complete Keyboard Description</a></span></dt><dd><dl><dt><span class="sect1"><a href="#The_XkbDescRec_Structure">The XkbDescRec Structure</a></span></dt><dt><span class="sect1"><a href="#Obtaining_a_Keyboard_Description_from_the_Server">Obtaining a Keyboard Description from the Server</a></span></dt><dt><span class="sect1"><a href="#Tracking_Changes_to_the_Keyboard_Description_in_the_Server">Tracking Changes to the Keyboard Description in the Server</a></span></dt><dt><span class="sect1"><a href="#Allocating_and_Freeing_a_Keyboard_Description">Allocating and Freeing a Keyboard Description</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Virtual_Modifiers">7. Virtual Modifiers</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Virtual_Modifier_Names_and_Masks">Virtual Modifier Names and Masks</a></span></dt><dt><span class="sect1"><a href="#Modifier_Definitions">Modifier Definitions</a></span></dt><dt><span class="sect1"><a href="#Binding_Virtual_Modifiers_to_Real_Modifiers">Binding Virtual Modifiers to Real Modifiers</a></span></dt><dt><span class="sect1"><a href="#Virtual_Modifier_Key_Mapping">Virtual Modifier Key Mapping</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Inactive_Modifier_Sets">Inactive Modifier Sets</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Conventions">Conventions</a></span></dt><dt><span class="sect1"><a href="#Example">Example</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Indicators">8. Indicators</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Indicator_Names">Indicator Names</a></span></dt><dt><span class="sect1"><a href="#Indicator_Data_Structures">Indicator Data Structures</a></span></dt><dd><dl><dt><span class="sect2"><a href="#XkbIndicatorRec">XkbIndicatorRec</a></span></dt><dt><span class="sect2"><a href="#XkbIndicatorMapRec">XkbIndicatorMapRec</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Getting_Information_About_Indicators">Getting Information About Indicators</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Getting_Indicator_State">Getting Indicator State</a></span></dt><dt><span class="sect2"><a href="#Getting_Indicator_Information_by_Index">Getting Indicator Information by Index</a></span></dt><dt><span class="sect2"><a href="#Getting_Indicator_Information_by_Name">Getting Indicator Information by Name</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Changing_Indicator_Maps_and_State">Changing Indicator Maps and State</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Effects_of_Explicit_Changes_on_Indicators">Effects of Explicit Changes on Indicators</a></span></dt><dt><span class="sect2"><a href="#Changing_Indicator_Maps_by_Index">Changing Indicator Maps by Index</a></span></dt><dt><span class="sect2"><a href="#Changing_Indicator_Maps_by_Name">Changing Indicator Maps by Name</a></span></dt><dt><span class="sect2"><a href="#The_XkbIndicatorChangesRec_Structure">The XkbIndicatorChangesRec Structure</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Tracking_Changes_to_Indicator_State_or_Map">Tracking Changes to Indicator State or Map</a></span></dt><dt><span class="sect1"><a href="#Allocating_and_Freeing_Indicator_Maps">Allocating and Freeing Indicator Maps</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Bells">9. Bells</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Bell_Names">Bell Names</a></span></dt><dt><span class="sect1"><a href="#Audible_Bells">Audible Bells</a></span></dt><dt><span class="sect1"><a href="#Bell_Functions">Bell Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Generating_Named_Bells">Generating Named Bells</a></span></dt><dt><span class="sect2"><a href="#Generating_Named_Bell_Events">Generating Named Bell Events</a></span></dt><dt><span class="sect2"><a href="#Forcing_a_Server_Generated_Bell">Forcing a Server-Generated Bell</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Detecting_Bells">Detecting Bells</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Keyboard_Controls">10. Keyboard Controls</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Controls_that_Enable_and_Disable_Other_Controls">Controls that Enable and Disable Other Controls</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_EnabledControls_Control">The EnabledControls Control</a></span></dt><dt><span class="sect2"><a href="#The_AutoReset_Control">The AutoReset Control</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Control_for_Bell_Behavior">Control for Bell Behavior</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_AudibleBell_Control">The AudibleBell Control</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Controls_for_Repeat_Key_Behavior">Controls for Repeat Key Behavior</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_PerKeyRepeat_Control">The PerKeyRepeat Control</a></span></dt><dt><span class="sect2"><a href="#The_RepeatKeys_Control">The RepeatKeys Control</a></span></dt><dt><span class="sect2"><a href="#The_DetectableAutorepeat_Control">The DetectableAutorepeat Control</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Controls_for_Keyboard_Overlays_Overlay1_and_Overlay2_Controls">Controls for Keyboard Overlays (Overlay1 and Overlay2 Controls)</a></span></dt><dt><span class="sect1"><a href="#Controls_for_Using_the_Mouse_from_the_Keyboard">Controls for Using the Mouse from the Keyboard</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_MouseKeys_Control">The MouseKeys Control</a></span></dt><dt><span class="sect2"><a href="#The_MouseKeysAccel_Control">The MouseKeysAccel Control</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Controls_for_Better_Keyboard_Access_by_Physically_ImpairedPersons">Controls for Better Keyboard Access by Physically Impaired
Persons</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_AccessXKeys_Control">The AccessXKeys Control</a></span></dt><dt><span class="sect2"><a href="#The_AccessXTimeout_Control">The AccessXTimeout Control</a></span></dt><dt><span class="sect2"><a href="#The_AccessXFeedback_Control">The AccessXFeedback Control</a></span></dt><dt><span class="sect2"><a href="#AccessXNotify_Events">AccessXNotify Events</a></span></dt><dt><span class="sect2"><a href="#StickyKeys_RepeatKeys_and_MouseKeys_Events">StickyKeys, RepeatKeys, and MouseKeys Events</a></span></dt><dt><span class="sect2"><a href="#The_SlowKeys_Control">The SlowKeys Control</a></span></dt><dt><span class="sect2"><a href="#The_BounceKeys_Control">The BounceKeys Control</a></span></dt><dt><span class="sect2"><a href="#The_StickyKeys_Control">The StickyKeys Control</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Controls_for_General_Keyboard_Mapping">Controls for General Keyboard Mapping</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_GroupsWrap_Control">The GroupsWrap Control</a></span></dt><dt><span class="sect2"><a href="#The_IgnoreLockMods_Control">The IgnoreLockMods Control</a></span></dt><dt><span class="sect2"><a href="#The_IgnoreGroupLock_Control">The IgnoreGroupLock Control</a></span></dt><dt><span class="sect2"><a href="#The_InternalMods_Control">The InternalMods Control</a></span></dt></dl></dd><dt><span class="sect1"><a href="#The_XkbControlsRec_Structure">The XkbControlsRec Structure</a></span></dt><dd><dl><dt><span class="sect2"><a href="#idp66132284"></a></span></dt></dl></dd><dt><span class="sect1"><a href="#Querying_Controls">Querying Controls</a></span></dt><dt><span class="sect1"><a href="#Changing_Controls">Changing Controls</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_XkbControlsChangesRec_Structure">The XkbControlsChangesRec Structure</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Tracking_Changes_to_Keyboard_Controls">Tracking Changes to Keyboard Controls</a></span></dt><dt><span class="sect1"><a href="#Allocating_and_Freeing_an_XkbControlsRec">Allocating and Freeing an XkbControlsRec</a></span></dt><dt><span class="sect1"><a href="#The_Miscellaneous_Per_client_Controls">The Miscellaneous Per-client Controls</a></span></dt></dl></dd><dt><span class="chapter"><a href="#X_Library_Controls">11. X Library Controls</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Controls_Affecting_Keycode_to_String_Translation">Controls Affecting Keycode-to-String Translation</a></span></dt><dd><dl><dt><span class="sect2"><a href="#ForceLatin1Lookup">ForceLatin1Lookup</a></span></dt><dt><span class="sect2"><a href="#ConsumeLookupMods">ConsumeLookupMods</a></span></dt><dt><span class="sect2"><a href="#AlwaysConsumeShiftAndLock">AlwaysConsumeShiftAndLock</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Controls_Affecting_Compose_Processing">Controls Affecting Compose Processing</a></span></dt><dd><dl><dt><span class="sect2"><a href="#ConsumeKeysOnComposeFail">ConsumeKeysOnComposeFail</a></span></dt><dt><span class="sect2"><a href="#ComposeLED">ComposeLED</a></span></dt><dt><span class="sect2"><a href="#BeepOnComposeFail">BeepOnComposeFail</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Controls_Effecting_Event_Delivery">Controls Effecting Event Delivery</a></span></dt><dd><dl><dt><span class="sect2"><a href="#IgnoreNewKeyboards">IgnoreNewKeyboards</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Manipulating_the_Library_Controls">Manipulating the Library Controls</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Determining_Which_Library_Controls_are_Implemented">Determining Which Library Controls are Implemented</a></span></dt><dt><span class="sect2"><a href="#Determining_the_State_of_the_Library_Controls">Determining the State of the Library Controls</a></span></dt><dt><span class="sect2"><a href="#Changing_the_State_of_the_Library_Controls">Changing the State of the Library Controls</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Interpreting_Key_Events">12. Interpreting Key Events</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Effects_of_Xkb_on_the_Core_X_Library">Effects of Xkb on the Core X Library</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Effects_of_Xkb_on_Event_State">Effects of Xkb on Event State</a></span></dt><dt><span class="sect2"><a href="#Effects_of_Xkb_on_MappingNotify_Events">Effects of Xkb on MappingNotify Events</a></span></dt><dt><span class="sect2"><a href="#X_Library_Functions_Affected_by_Xkb">X Library Functions Affected by Xkb</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Xkb_Event_and_Keymap_Functions">Xkb Event and Keymap Functions</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Keyboard_Geometry">13. Keyboard Geometry</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Shapes_and_Outlines">Shapes and Outlines</a></span></dt><dt><span class="sect1"><a href="#Sections">Sections</a></span></dt><dt><span class="sect1"><a href="#Rows_and_Keys">Rows and Keys</a></span></dt><dt><span class="sect1"><a href="#Doodads">Doodads</a></span></dt><dt><span class="sect1"><a href="#Overlay_Rows_and_Overlay_Keys">Overlay Rows and Overlay Keys</a></span></dt><dt><span class="sect1"><a href="#Drawing_a_Keyboard_Representation">Drawing a Keyboard Representation</a></span></dt><dt><span class="sect1"><a href="#Geometry_Data_Structures">Geometry Data Structures</a></span></dt><dd><dl><dt><span class="sect2"><a href="#DoodadRec_Structures">DoodadRec Structures</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Getting_Keyboard_Geometry_From_the_Server">Getting Keyboard Geometry From the Server</a></span></dt><dt><span class="sect1"><a href="#Using_Keyboard_Geometry">Using Keyboard Geometry</a></span></dt><dt><span class="sect1"><a href="#Adding_Elements_to_a_Keyboard_Geometry">Adding Elements to a Keyboard Geometry</a></span></dt><dt><span class="sect1"><a href="#Allocating_and_Freeing_Geometry_Components">Allocating and Freeing Geometry Components</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Xkb_Keyboard_Mapping">14. Xkb Keyboard Mapping</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Notation_and_Terminology">Notation and Terminology</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Core_Implementation">Core Implementation</a></span></dt><dt><span class="sect2"><a href="#Xkb_Implementation">Xkb Implementation</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Getting_Map_Components_from_the_Server">Getting Map Components from the Server</a></span></dt><dt><span class="sect1"><a href="#Changing_Map_Components_in_the_Server">Changing Map Components in the Server</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_XkbMapChangesRec_Structure">The XkbMapChangesRec Structure</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Tracking_Changes_to_Map_Components">Tracking Changes to Map Components</a></span></dt><dt><span class="sect1"><a href="#Allocating_and_Freeing_Client_and_Server_Maps">Allocating and Freeing Client and Server Maps</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Allocating_an_Empty_Client_Map">Allocating an Empty Client Map</a></span></dt><dt><span class="sect2"><a href="#Freeing_a_Client_Map">Freeing a Client Map</a></span></dt><dt><span class="sect2"><a href="#Allocating_an_Empty_Server_Map">Allocating an Empty Server Map</a></span></dt><dt><span class="sect2"><a href="#Freeing_a_Server_Map">Freeing a Server Map</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Xkb_Client_Keyboard_Mapping">15. Xkb Client Keyboard Mapping</a></span></dt><dd><dl><dt><span class="sect1"><a href="#The_XkbClientMapRec_Structure">The XkbClientMapRec Structure</a></span></dt><dt><span class="sect1"><a href="#Key_Types">Key Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_Canonical_Key_Types">The Canonical Key Types</a></span></dt><dt><span class="sect2"><a href="#Getting_Key_Types_from_the_Server">Getting Key Types from the Server</a></span></dt><dt><span class="sect2"><a href="#Changing_the_Number_of_Levels_in_a_Key_Type">Changing the Number of Levels in a Key Type</a></span></dt><dt><span class="sect2"><a href="#Copying_Key_Types">Copying Key Types</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Key_Symbol_Map">Key Symbol Map</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Per_Key_Key_Type_Indices">Per-Key Key Type Indices</a></span></dt><dt><span class="sect2"><a href="#Per_Key_Group_Information">Per-Key Group Information</a></span></dt><dt><span class="sect2"><a href="#Key_Width">Key Width</a></span></dt><dt><span class="sect2"><a href="#Offset_in_to_the_Symbol_Map">Offset in to the Symbol Map</a></span></dt><dt><span class="sect2"><a href="#Getting_the_Symbol_Map_for_Keys_from_the_Server">Getting the Symbol Map for Keys from the Server</a></span></dt><dt><span class="sect2"><a href="#Changing_the_Number_of_Groups_and_Types_Bound_to_a_Key">Changing the Number of Groups and Types Bound to a Key</a></span></dt><dt><span class="sect2"><a href="#Changing_the_Number_of_Symbols_Bound_to_a_Key">Changing the Number of Symbols Bound to a Key</a></span></dt></dl></dd><dt><span class="sect1"><a href="#The_Per_Key_Modifier_Map">The Per-Key Modifier Map</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Getting_the_Per_Key_Modifier_Map_from_the_Server">Getting the Per-Key Modifier Map from the Server</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Xkb_Server_Keyboard_Mapping">16. Xkb Server Keyboard Mapping</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Key_Actions">Key Actions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_XkbAction_Structure">The XkbAction Structure</a></span></dt><dt><span class="sect2"><a href="#The_XkbAnyAction_Structure">The XkbAnyAction Structure</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Changing_Modifiers_State">Actions for Changing Modifiers’ State</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Changing_Group_State">Actions for Changing Group State</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Moving_the_Pointer">Actions for Moving the Pointer</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Simulating_Pointer_Button_Press_and_Release">Actions for Simulating Pointer Button Press and Release</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Changing_the_Pointer_Button_Simulated">Actions for Changing the Pointer Button Simulated</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Locking_Modifiers_and_Group">Actions for Locking Modifiers and Group</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Changing_the_Active_Screen">Actions for Changing the Active Screen</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Changing_Boolean_Controls_State">Actions for Changing Boolean Controls State</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Generating_Messages">Actions for Generating Messages</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Generating_a_Different_Keycode">Actions for Generating a Different Keycode</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Generating_DeviceButtonPress_and_DeviceButtonRelease">Actions for Generating DeviceButtonPress and DeviceButtonRelease</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Simulating_Events_from_Device_Valuators">Actions for Simulating Events from Device Valuators</a></span></dt><dt><span class="sect2"><a href="#Obtaining_Key_Actions_for_Keys_from_the_Server">Obtaining Key Actions for Keys from the Server</a></span></dt><dt><span class="sect2"><a href="#Changing_the_Number_of_Actions_Bound_to_a_Key">Changing the Number of Actions Bound to a Key</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Key_Behavior">Key Behavior</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Radio_Groups_2">Radio Groups</a></span></dt><dt><span class="sect2"><a href="#The_XkbBehavior_Structure">The XkbBehavior Structure</a></span></dt><dt><span class="sect2"><a href="#Obtaining_Key_Behaviors_for_Keys_from_the_Server">Obtaining Key Behaviors for Keys from the Server</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Explicit_ComponentsAvoiding_Automatic_Remapping_by_the_Server">Explicit Components—Avoiding Automatic Remapping by the Server</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Obtaining_Explicit_Components_for_Keys_from_the_Server">Obtaining Explicit Components for Keys from the Server</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Virtual_Modifier_Mapping">Virtual Modifier Mapping</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Obtaining_Virtual_Modifier_Bindings_from_the_Server">Obtaining Virtual Modifier Bindings from the Server</a></span></dt><dt><span class="sect2"><a href="#Obtaining_Per_Key_Virtual_Modifier_Mappings_from_the_Server">Obtaining Per-Key Virtual Modifier Mappings from the Server</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#The_Xkb_Compatibility_Map">17. The Xkb Compatibility Map</a></span></dt><dd><dl><dt><span class="sect1"><a href="#The_XkbCompatMap_Structure">The XkbCompatMap Structure</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Xkb_State_to_Core_Protocol_State_Transformation">Xkb State to Core Protocol State Transformation</a></span></dt><dt><span class="sect2"><a href="#Core_Keyboard_Mapping_to_Xkb_Keyboard_Mapping_Transformation">Core Keyboard Mapping to Xkb Keyboard Mapping Transformation</a></span></dt><dt><span class="sect2"><a href="#Xkb_Keyboard_Mapping_to_Core_Keyboard_Mapping_Transformations">Xkb Keyboard Mapping to Core Keyboard Mapping Transformations</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Getting_Compatibility_Map_Components_From_the_Server">Getting Compatibility Map Components From the Server</a></span></dt><dt><span class="sect1"><a href="#Using_the_Compatibility_Map">Using the Compatibility Map</a></span></dt><dt><span class="sect1"><a href="#Changing_the_Servers_Compatibility_Map">Changing the Server’s Compatibility Map</a></span></dt><dt><span class="sect1"><a href="#Tracking_Changes_to_the_Compatibility_Map">Tracking Changes to the Compatibility Map</a></span></dt><dt><span class="sect1"><a href="#Allocating_and_Freeing_the_Compatibility_Map">Allocating and Freeing the Compatibility Map</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Symbolic_Names">18. Symbolic Names</a></span></dt><dd><dl><dt><span class="sect1"><a href="#The_XkbNamesRec_Structure">The XkbNamesRec Structure</a></span></dt><dt><span class="sect1"><a href="#Symbolic_Names_Masks">Symbolic Names Masks</a></span></dt><dt><span class="sect1"><a href="#Getting_Symbolic_Names_From_the_Server">Getting Symbolic Names From the Server</a></span></dt><dt><span class="sect1"><a href="#Changing_Symbolic_Names_on_the_Server">Changing Symbolic Names on the Server</a></span></dt><dd><dl><dt><span class="sect2"><a href="#idp67328372"></a></span></dt></dl></dd><dt><span class="sect1"><a href="#Tracking_Name_Changes">Tracking Name Changes</a></span></dt><dt><span class="sect1"><a href="#Allocating_and_Freeing_Symbolic_Names">Allocating and Freeing Symbolic Names</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Replacing_a_Keyboard_On_the_Fly">19. Replacing a Keyboard "On the Fly"</a></span></dt><dt><span class="chapter"><a href="#Server_Database_of_Keyboard_Components">20. Server Database of Keyboard Components</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Component_Names">Component Names</a></span></dt><dt><span class="sect1"><a href="#Listing_the_Known_Keyboard_Components">Listing the Known Keyboard Components</a></span></dt><dt><span class="sect1"><a href="#Component_Hints">Component Hints</a></span></dt><dt><span class="sect1"><a href="#Building_a_Keyboard_Description_Using_the_Server_Database">Building a Keyboard Description Using the Server Database</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Attaching_Xkb_Actions_to_X_Input_Extension_Devices">21. Attaching Xkb Actions to X Input Extension Devices</a></span></dt><dd><dl><dt><span class="sect1"><a href="#XkbDeviceInfoRec">XkbDeviceInfoRec</a></span></dt><dt><span class="sect1"><a href="#Querying_Xkb_Features_for_Non_KeyClass_Input_Extension_Devices">Querying Xkb Features for Non-KeyClass Input Extension Devices</a></span></dt><dt><span class="sect1"><a href="#Allocating_Initializing_and_Freeing_the_XkbDeviceInfoRecStructure">Allocating, Initializing, and Freeing the XkbDeviceInfoRec
Structure</a></span></dt><dt><span class="sect1"><a href="#Setting_Xkb_Features_for_Non_KeyClass_Input_Extension_Devices">Setting Xkb Features for Non-KeyClass Input Extension Devices</a></span></dt><dt><span class="sect1"><a href="#XkbExtensionDeviceNotify_Event">XkbExtensionDeviceNotify Event</a></span></dt><dt><span class="sect1"><a href="#Tracking_Changes_to_Extension_Devices">Tracking Changes to Extension Devices</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Debugging_Aids">22. Debugging Aids</a></span></dt><dt><span class="glossary"><a href="#glossary">Glossary</a></span></dt></dl></div><div class="list-of-tables"><p><strong>List of Tables</strong></p><dl><dt>1.1. <a href="#idp61147284">Function Error Returns Due to Extension Problems</a></dt><dt>2.1. <a href="#idp62936900">Xkb Protocol Errors</a></dt><dt>2.2. <a href="#idp62950324">BadKeyboard Protocol Error resource_id Values</a></dt><dt>4.1. <a href="#idp62860884">Xkb Event Types</a></dt><dt>4.2. <a href="#idp64530804">XkbSelectEvents Mask Constants</a></dt><dt>5.1. <a href="#idp64445828">Real Modifier Masks</a></dt><dt>5.2. <a href="#idp64627956">Symbolic Group Names</a></dt><dt>5.3. <a href="#idp64657620">XkbStateNotify Event Detail Masks</a></dt><dt>6.1. <a href="#idp64607076">XkbDescRec Component References</a></dt><dt>6.2. <a href="#idp64591540">Mask Bits for XkbDescRec</a></dt><dt>8.1. <a href="#idp64731580">XkbIndicatorMapRec flags Field</a></dt><dt>8.2. <a href="#idp64750140">XkbIndicatorMapRec which_groups and groups, Keyboard Drives
Indicator</a></dt><dt>8.3. <a href="#idp64943092">XkbIndicatorMapRec which_groups and groups, Indicator Drives
Keyboard</a></dt><dt>8.4. <a href="#idp64962644">XkbIndicatorMapRec which_mods and mods, Keyboard Drives Indicator</a></dt><dt>8.5. <a href="#idp64975396">XkbIndicatorMapRec which_mods and mods, Indicator Drives Keyboard</a></dt><dt>9.1. <a href="#idp64762276">Predefined Bells</a></dt><dt>9.2. <a href="#idp64784092">Bell Sounding and Bell Event Generating</a></dt><dt>10.1. <a href="#idp64865236">Xkb Keyboard Controls</a></dt><dt>10.2. <a href="#idp65792732">MouseKeysAccel Fields</a></dt><dt>10.3. <a href="#idp65866748">AccessXFeedback Masks</a></dt><dt>10.4. <a href="#idp65890924">AccessXNotify Events</a></dt><dt>10.5. <a href="#idp65905684">AccessXNotify Event Details</a></dt><dt>10.6. <a href="#idp66066828">Xkb Controls</a></dt><dt>10.7. <a href="#idp66103916">Controls Mask Bits</a></dt><dt>10.8. <a href="#idp66138292">GroupsWrap options (groups_wrap field)</a></dt><dt>10.9. <a href="#idp66163204">Access X Enable/Disable Bits (ax_options field)</a></dt><dt>11.1. <a href="#idp64831356">Library Control Masks</a></dt><dt>13.1. <a href="#idp66374572">Doodad Types</a></dt><dt>14.1. <a href="#idp65601540">Xkb Mapping Component Masks and Convenience Functions</a></dt><dt>14.2. <a href="#idp65661396">XkbMapChangesRec Masks</a></dt><dt>14.3. <a href="#idp65181356">XkbAllocClientMap Masks</a></dt><dt>14.4. <a href="#idp65216964">XkbAllocServerMap Masks</a></dt><dt>15.1. <a href="#idp65261028">Example Key Type</a></dt><dt>15.2. <a href="#idp67011620">group_info Range Normalization</a></dt><dt>15.3. <a href="#idp67115348">Group Index Constants</a></dt><dt>16.1. <a href="#idp67495148">Action Types</a></dt><dt>16.2. <a href="#idp67526092">Modifier Action Types</a></dt><dt>16.3. <a href="#idp67541380">Modifier Action Flags</a></dt><dt>16.4. <a href="#idp67571580">Group Action Types</a></dt><dt>16.5. <a href="#idp67588068">Group Action Flags</a></dt><dt>16.6. <a href="#idp67614196">Pointer Action Types</a></dt><dt>16.7. <a href="#idp67649420">Pointer Button Action Types</a></dt><dt>16.8. <a href="#idp67666404">Pointer Button Action Flags</a></dt><dt>16.9. <a href="#idp67679764">Pointer Default Flags</a></dt><dt>16.10. <a href="#idp67709020">ISO Action Flags when XkbSA_ISODfltIsGroup is Set</a></dt><dt>16.11. <a href="#idp67723956">ISO Action Flags when XkbSA_ISODfltIsGroup is Not Set</a></dt><dt>16.12. <a href="#idp67744524">ISO Action Affect Field Values</a></dt><dt>16.13. <a href="#idp67759996">Switch Screen Action Flags</a></dt><dt>16.14. <a href="#idp67783372">Controls Action Types</a></dt><dt>16.15. <a href="#idp67794708">Control Action Flags</a></dt><dt>16.16. <a href="#idp67818572">Message Action Flags</a></dt><dt>16.17. <a href="#idp67879292">Device Button Action Types</a></dt><dt>16.18. <a href="#idp67894324">Device Button Action Flags</a></dt><dt>16.19. <a href="#idp67906396">Device Valuator v&lt;n&gt;_what High Bits Values</a></dt><dt>16.20. <a href="#idp67957940">Key Behaviors</a></dt><dt>16.21. <a href="#idp67987444">Explicit Component Masks</a></dt><dt>17.1. <a href="#idp66869580">Symbol Interpretation Match Criteria</a></dt><dt>17.2. <a href="#idp67184468">Compatibility Map Component Masks</a></dt><dt>18.1. <a href="#idp66828924">Symbolic Names Masks</a></dt><dt>18.2. <a href="#idp67332660">XkbNameChanges Fields</a></dt><dt>19.1. <a href="#idp65470660">XkbNewKeyboardNotifyEvent Details</a></dt><dt>20.1. <a href="#idp62892988">Server Database Keyboard Components</a></dt><dt>20.2. <a href="#idp68062900">XkbComponentNameRec Flags Bits</a></dt><dt>20.3. <a href="#idp68115804">Want and Need Mask Bits and Required Names Components</a></dt><dt>20.4. <a href="#idp68137884">XkbDescRec Components Returned for Values of Want &amp; Needs</a></dt><dt>21.1. <a href="#idp67459228">XkbDeviceInfoRec Mask Bits</a></dt><dt>22.1. <a href="#idp65339596">Debug Control Masks</a></dt></dl></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a id="acknowledgement"></a>Acknowledgement</h1></div></div></div><p>
This document is the result of a great deal of hard work by a great
many people. Without Erik Fortune’s work as Architect of the X
Keyboard Extension and the longtime support of Silicon Graphics
Inc. there would not be a keyboard extension.
</p><p>
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.
</p><p>
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 protocol 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.
</p><p>
</p><div class="literallayout"><p><br />
Matt Landau<br />
Manager, X Window System<br />
X Consortium Inc.<br />
</p></div><p>
</p><div class="simplesect"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idp63933604"></a>X Version 11, Release 7 addendum</h2></div></div></div><p>
This document is made available to you in modern formats such as HTML and PDF
thanks to the efforts of Matt Dew, who converted the original troff sources to
DocBook/XML and edited them into shape; Fernando Carrijo, who converted the
images to SVG format; and Gaetan Nadon, who set up the formatting machinery in
the libX11 builds and performed further editing of the DocBook markup.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Overview"></a>Chapter 1. Overview</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Core_X_Protocol_Support_for_Keyboards">Core X Protocol Support for Keyboards</a></span></dt><dt><span class="sect1"><a href="#Xkb_Keyboard_Extension_Support_for_Keyboards">Xkb Keyboard Extension Support for Keyboards</a></span></dt><dt><span class="sect1"><a href="#Xkb_Extension_Components">Xkb Extension Components</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Groups_and_Shift_Levels">Groups and Shift Levels</a></span></dt><dt><span class="sect2"><a href="#Radio_Groups">Radio Groups</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Client_Types">Client Types</a></span></dt><dt><span class="sect1"><a href="#Compatibility_With_the_Core_Protocol">Compatibility With the Core Protocol</a></span></dt><dt><span class="sect1"><a href="#Additional_Protocol_Errors">Additional Protocol Errors</a></span></dt><dt><span class="sect1"><a href="#Extension_Library_Functions">Extension Library Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Error_Indications">Error Indications</a></span></dt></dl></dd></dl></div><p>
The X Keyboard Extension provides capabilities that are lacking or are
cumbersome in the core X protocol.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Core_X_Protocol_Support_for_Keyboards"></a>Core X Protocol Support for Keyboards</h2></div></div></div><p>
The core X protocol specifies the ways that the
<span class="emphasis"><em>Shift</em></span>,
<span class="emphasis"><em>Control</em></span>, and
<span class="emphasis"><em>Lock</em></span>
modifiers and the modifiers bound to the
<span class="emphasis"><em>Mode_switch</em></span> or
<span class="emphasis"><em>Num_Lock</em></span>
keysyms interact to generate keysyms and characters. The core protocol also
allows users to specify that a key affects one or more modifiers. This behavior
is simple and fairly flexible, but it has a number of limitations that make it
difficult or impossible to properly support many common varieties of keyboard
behavior. The limitations of core protocol support for keyboards include:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Use of a single, uniform, four-symbol mapping for all keyboard keys makes it
difficult to properly support keyboard overlays, PC-style break keys, or
keyboards that comply with ISO9995, or a host of other national and
international standards.
    </p></li><li class="listitem"><p>
A second keyboard group may be specified using a modifier, but this has side
effects that wreak havoc with client grabs and X toolkit translations.
Furthermore, this approach limits the number of keyboard groups to two.
    </p></li><li class="listitem"><p>
Poorly specified locking key behavior requires X servers to look for a few
"magic" keysyms to determine that keys should lock when pressed. This leads to
incompatibilities between X servers with no way for clients to detect
implementation differences.
    </p></li><li class="listitem"><p>
Poorly specified capitalization and control behavior requires modifications to
X library source code to support new character sets or locales and can lead to
incompatibilities between system wide and X library capitalization behavior.
    </p></li><li class="listitem"><p>
Limited interactions between modifiers specified by the core protocol make many
common keyboard behaviors difficult or impossible to implement. For example,
there is no reliable way to indicate whether or not the shift modifier should
"cancel" the lock modifier.
    </p></li><li class="listitem"><p>
The lack of any explicit descriptions for indicators, most modifiers, and other
aspects of the keyboard appearance requires clients that wish to clearly
describe the keyboard to a user to resort to a mish-mash of prior knowledge and
heuristics.
    </p></li></ul></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Xkb_Keyboard_Extension_Support_for_Keyboards"></a>Xkb Keyboard Extension Support for Keyboards</h2></div></div></div><p>
The X Keyboard Extension makes it possible to clearly and explicitly specify
most aspects of keyboard behavior on a per-key basis. It adds the notion of a
keyboard group to the global keyboard state and provides mechanisms to more
closely track the logical and physical state of the keyboard. For
keyboard-control clients, Xkb provides descriptions and symbolic names for many
aspects of keyboard appearance and behavior.
</p><p>
In addition, the X Keyboard Extension includes additional keyboard controls
designed to make keyboards more accessible to people with movement impairments.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Xkb_Extension_Components"></a>Xkb Extension Components</h2></div></div></div><p>
The Xkb extension is composed of two parts: a server extension, and a
client-side X library extension. These consist of a loadable module that may be
activated when an X server is started and a modified version of Xlib. Both
server and Xlib versions must be at least X11 R6.
</p><p>
Figure 1.1 shows the overall structure of the Xkb extension:
</p><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-1.svg"></object><div class="caption">Overall Xkb Structure</div></div><p>
The server portion of the Xkb extension encompasses a database of named
keyboard components, in unspecified format, that may be used to configure a
keyboard. Internally, the server maintains a <span class="emphasis"><em>
keyboard description</em></span>
 that includes the keyboard state and configuration (mapping). By "keyboard" we
mean the logical keyboard device, which includes not only the physical keys,
but also potentially a set of up to 32 indicators (usually LEDs) and bells.
</p><p>
The keyboard description is a composite of several different data structures,
each of which may be manipulated separately. When manipulating the server
components, the design allows partial components to be transmitted between the
server and a client. The individual components are shown in Figure 1.1.
</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">Client Map</span></p></td><td><p>
The key mapping information needed to convert arbitrary keycodes to symbols.
      </p></td></tr><tr><td><p><span class="term">Server Map</span></p></td><td><p>
The key mapping information categorizing keys by functionality (which keys are
modifiers, how keys behave, and so on).
      </p></td></tr><tr><td><p><span class="term">Controls</span></p></td><td><p>
Client configurable quantities effecting how the keyboard behaves, such as
repeat behavior and modifications for people with movement impairments.
      </p></td></tr><tr><td><p><span class="term">Indicators</span></p></td><td><p>
The mapping of behavior to indicators.
      </p></td></tr><tr><td><p><span class="term">Geometry</span></p></td><td><p>
A complete description of the physical keyboard layout, sufficient to draw a
representation of the keyboard.
      </p></td></tr><tr><td><p><span class="term">Names</span></p></td><td><p>
A mapping of names to various aspects of the keyboard such as individual
virtual modifiers, indicators, and bells.
      </p></td></tr><tr><td><p><span class="term">Compatibility Map</span></p></td><td><p>
The definition of how to map core protocol keyboard state to Xkb keyboard state.
      </p></td></tr></tbody></table></div><p>
A client application interrogates and manipulates the keyboard by reading and
writing portions of the server description for the keyboard. In a typical
sequence a client would fetch the current information it is interested in,
modify it, and write it back. If a client wishes to track some portion of the
keyboard state, it typically maintains a local copy of the portion of the
server keyboard description dealing with the items of interest and updates this
local copy from events describing state transitions that are sent by the server.
</p><p>
A client may request the server to reconfigure the keyboard either by sending
explicit reconfiguration instructions to it, or by telling it to load a new
configuration from its database of named components. Partial reconfiguration
and incremental reconfiguration are both supported.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Groups_and_Shift_Levels"></a>Groups and Shift Levels</h3></div></div></div><p>
The graphic characters or control functions that may be accessed by one key are
logically arranged in groups and levels. See section 14.1for a complete
description of groups and levels.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Radio_Groups"></a>Radio Groups</h3></div></div></div><p>
A radio group is a set of keys whose behavior simulates a set of radio buttons.
Once a key in a radio group is pressed, it stays logically depressed until
another key in the group is pressed, at which point the previously depressed
key is logically released. Consequently, at most one key in a radio group can
be logically depressed at one time. A radio group is defined by a radio group
index, an optional name, and by assigning each key in the radio group <span class="emphasis"><em>
XkbKB_RadioGroup</em></span>
 behavior and the radio group index.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Client_Types"></a>Client Types</h2></div></div></div><p>
This specification differentiates between three different classes of client
applications:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Xkb-aware applications
    </p><p>
These applications make specific use of Xkb functionality and APIs not present
in the core protocol.
    </p></li><li class="listitem"><p>
Xkb-capable applications
    </p><p>
These applications make no use of Xkb extended functionality and Application
Programming Interfaces (APIs) directly. However, they are linked with a version
of Xlib that includes Xkb and indirectly benefit from some of Xkb’s
features.
    </p></li><li class="listitem"><p>
Xkb-unaware applications
    </p><p>
These applications make no use of Xkb extended functionality or APIs and
require Xkb’s functionality to be mapped to core Xlib functionality to
operate properly.
    </p></li></ul></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Compatibility_With_the_Core_Protocol"></a>Compatibility With the Core Protocol</h2></div></div></div><p>
Because the Xkb extension allows a keyboard to be configured in ways not
foreseen by the core protocol, and because Xkb-unaware clients are allowed to
connect to a server using the Xkb extension, there must be a means of
converting between the Xkb domain and the core protocol. The Xkb server
extension maintains a compatibility map as part of its keyboard description;
this map controls the conversion of Xkb generated events to core protocol
events and the results of core protocol requests to appropriate Xkb state and
configuration.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Additional_Protocol_Errors"></a>Additional Protocol Errors</h2></div></div></div><p>
The Xkb extension adds a single protocol error, <span class="emphasis"><em>
BadKeyboard</em></span>
, to the core protocol error set. See section 2.6 for a discussion of the  
<span class="emphasis"><em>
BadKeyboard</em></span>
 protocol error.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Extension_Library_Functions"></a>Extension Library Functions</h2></div></div></div><p>
The X Keyboard Extension replaces the core protocol definition of a keyboard
with a more comprehensive one. The X Keyboard Extension library interfaces are
included in Xlib.<a href="#ftn.idp61143988" class="footnote" id="idp61143988"><sup class="footnote">[1]</sup></a>
</p><p>
Xlib detects the presence of the X Keyboard server extension and uses Xkb
protocol to replace some standard X library functions related to the keyboard.
If an application uses only standard X library functions to examine the
keyboard or process key events, it should not need to be modified when linked
with an X library containing the X keyboard extension. All of the
keyboard-related X library functions have been modified to automatically use
Xkb protocol when the server extension is present.
</p><p>
The Xkb extension adds library interfaces to allow a client application to
directly manipulate the new capabilities.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Error_Indications"></a>Error Indications</h3></div></div></div><p>
Xkb functions that communicate with the X server check to be sure the Xkb
extension has been properly initialized prior to doing any other operations. If
the extension has not been properly initialized or the application, library,
and server versions are incompatible, these functions return an error
indication as shown in Table 1.1. Because of this test, <span class="emphasis"><em>
BadAccess</em></span>
 and <span class="emphasis"><em>
BadMatch</em></span>
 (due to incompatible versions) protocol errors should normally not be
generated.
</p><div class="table"><a id="idp61147284"></a><p class="title"><strong>Table 1.1. Function Error Returns Due to Extension Problems</strong></p><div class="table-contents"><table summary="Function Error Returns Due to Extension Problems" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Functions return type</th><th align="left">Return value</th></tr></thead><tbody><tr><td align="left">pointer to a structure</td><td align="left">NULL</td></tr><tr><td align="left">Bool</td><td align="left">False</td></tr><tr><td align="left">Status</td><td align="left">BadAccess</td></tr></tbody></table></div></div><br class="table-break" /><p>
Many Xkb functions do not actually communicate with the X server; they only
require processing in the client-side portion of the library. Furthermore, some
applications may never actually need to communicate with the server; they
simply use the Xkb library capabilities. The functions that do not communicate
with the server return either a pointer to a structure, a Bool, or a Status.
These functions check that the application has queried the Xkb library version
and return the values shown in Table 1.1 if it has not.
</p></div></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idp61143988" class="footnote"><p><a href="#idp61143988" class="para"><sup class="para">[1] </sup></a>
X11R6.1 is the first release by the X Consortium, Inc.,that includes the X
Keyboard Extension in Xlib. X11R6 included work in progress on this extension
as nonstandard additions to the library.
</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Initialization_and_General_Programming_Information"></a>Chapter 2. Initialization and General Programming Information</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Extension_Header_Files">Extension Header Files</a></span></dt><dt><span class="sect1"><a href="#Extension_Name">Extension Name</a></span></dt><dt><span class="sect1"><a href="#Determining_Library_Compatibility">Determining Library Compatibility</a></span></dt><dt><span class="sect1"><a href="#Initializing_the_Keyboard_Extension">Initializing the Keyboard Extension</a></span></dt><dt><span class="sect1"><a href="#Disabling_the_Keyboard_Extension">Disabling the Keyboard Extension</a></span></dt><dt><span class="sect1"><a href="#Protocol_Errors">Protocol Errors</a></span></dt><dt><span class="sect1"><a href="#Display_and_Device_Specifications_in_Function_Calls">Display and Device Specifications in Function Calls</a></span></dt></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Extension_Header_Files"></a>Extension Header Files</h2></div></div></div><p>
The following include files are part of the Xkb standard:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="emphasis"><em>&lt;X11/XKBlib.h&gt;</em></span>
    </p><p><span class="emphasis"><em>XKBlib.h</em></span>
is the main header file for Xkb; it declares constants, types, and
functions.
    </p></li><li class="listitem"><p>
<span class="emphasis"><em>&lt;X11/extensions/XKBstr.h&gt;</em></span>
    </p><p>
<span class="emphasis"><em>XKBstr.h</em></span> declares types and
constants for Xkb. It is included automatically from
<span class="emphasis"><em>&lt;X11/XKBlib.h&gt;</em></span>
; you should never need to reference it directly in your application code.
    </p></li><li class="listitem"><p>
<span class="emphasis"><em>&lt;X11/extensions/XKB.h&gt;</em></span>
    </p><p>
<span class="emphasis"><em>XKB.h</em></span>
defines constants for Xkb. It is included automatically from <span class="emphasis"><em>
&lt;X11/XKBstr.h&gt;</em></span>
; you should never need to reference it directly in your application code.
    </p></li><li class="listitem"><p>
<span class="emphasis"><em>&lt;X11/extensions/XKBgeom.h&gt;</em></span>
   </p><p><span class="emphasis"><em>XKBgeom.h</em></span>
declares types, symbolic constants, and functions for manipulating
keyboard geometry descriptions.
    </p></li></ul></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Extension_Name"></a>Extension Name</h2></div></div></div><p>
The name of the Xkb extension is given in <span class="emphasis"><em>
&lt;X11/extensions/Xkb.h&gt;:</em></span>
</p><p>
<span class="emphasis"><em>
#define XkbName "XKEYBOARD"</em></span>
</p><p>
Most extensions to the X protocol are initialized by calling <span class="emphasis"><em>
XInitExtension</em></span>
 and passing the extension name. However, as explained in section 2.4, Xkb
requires a more complex initialization sequence, and a client program should
not call <span class="emphasis"><em>
XInitExtension</em></span>
 directly.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Determining_Library_Compatibility"></a>Determining Library Compatibility</h2></div></div></div><p>
If an application is dynamically linked, both the X server and the client-side
X library must contain the Xkb extension in order for the client to use the Xkb
extension capabilities. Therefore a dynamically linked application must check
both the library and the server for compatibility before using Xkb function
calls. A properly written program must check for compatibility between the
version of the Xkb library that is dynamically loaded and the one used when the
application was built. It must then check the server version for compatibility
with the version of Xkb in the library.
</p><p>
If your application is statically linked, you must still check for server
compatibility and may check library compatibility. (It is possible to compile
against one set of header files and link against a different, incompatible,
version of the library, although this should not normally occur.)
</p><p>
To determine the compatibility of a library at runtime, call <span class="emphasis"><em>
XkbLibraryVersion</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbLibraryVersion</em></span>
(<span class="emphasis"><em>
lib_major_in_out</em></span>
, <span class="emphasis"><em>
lib_minor_in_out</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
int *      <span class="emphasis"><em>
lib_major_in_out;</em></span>
                  /* specifies and returns the major Xkb library version. */
    </td></tr><tr><td class="functionargdecl" align="left">
int *      <span class="emphasis"><em>
lib_minor_in_out;</em></span>
                  /* specifies and returns the minor Xkb library version. */
    </td></tr></tbody></table></div><p>
Pass the symbolic value <span class="emphasis"><em>
XkbMajorVersion</em></span>
 in <span class="emphasis"><em>
lib_major_in_out</em></span>
 and <span class="emphasis"><em>
XkbMinorVersion</em></span>
 in <span class="emphasis"><em>
lib_minor_in_out</em></span>
. These arguments represent the version of the library used at compile time.
The <span class="emphasis"><em>
XkbLibraryVersion </em></span>
function backfills the major and minor version numbers of the library used at
run time in <span class="emphasis"><em>
lib_major_in_out</em></span>
 and <span class="emphasis"><em>
lib_minor_in_out</em></span>
. If the versions of the compile time and run time libraries are compatible,
<span class="emphasis"><em>
XkbLibraryVersion </em></span>
returns <span class="emphasis"><em>
True</em></span>
, otherwise, it returns <span class="emphasis"><em>
False.</em></span>
</p><p>
In addition, in order to use the Xkb extension, you must ensure that the
extension is present in the server and that the server supports the version of
the extension expected by the client. Use <span class="emphasis"><em>
XkbQueryExtension</em></span>
 to do this, as described in the next section.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Initializing_the_Keyboard_Extension"></a>Initializing the Keyboard Extension</h2></div></div></div><p>
Call <span class="emphasis"><em>
XkbQueryExtension</em></span>
 to check for the presence and compatibility of the extension in the server and
to initialize the extension. Because of potential version mismatches, you
cannot use the generic extension mechanism functions (<span class="emphasis"><em>
XQueryExtension </em></span>
and<span class="emphasis"><em>
 XInitExtension</em></span>
) for checking for the presence of, and initializing the Xkb extension.
</p><p>
You must call <span class="emphasis"><em>
XkbQueryExtension</em></span>
 or <span class="emphasis"><em>
XkbOpenDisplay</em></span>
 before using any other Xkb library interfaces, unless such usage is explicitly
allowed in the interface description in this document. The exceptions are:
<span class="emphasis"><em>
XkbIgnoreExtension</em></span>
, <span class="emphasis"><em>
XkbLibraryVersion</em></span>
, and a handful of audible-bell functions. You should not use any other Xkb
functions if the extension is not present or is uninitialized. In general,
calls to Xkb library functions made prior to initializing the Xkb extension
cause <span class="emphasis"><em>
BadAccess</em></span>
 protocol errors.
</p><p>
<span class="emphasis"><em>
XkbQueryExtension</em></span>
 both determines whether a compatible Xkb extension is present in the X server
and initializes the extension when it is present.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbQueryExtension</em></span>
(<span class="emphasis"><em>
dpy, opcode_rtrn, event_rtrn, error_rtrn, major_in_out, minor_in_out</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
dpy;      </em></span>
      /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
int *      <span class="emphasis"><em>
opcode_rtrn</em></span>
;            /* backfilled with the major extension opcode */
    </td></tr><tr><td class="functionargdecl" align="left">
int *      <span class="emphasis"><em>
event_rtrn</em></span>
;            /* backfilled with the extension base event code */
    </td></tr><tr><td class="functionargdecl" align="left">
int *      <span class="emphasis"><em>
error_rtrn</em></span>
;            /* backfilled with the extension base error code */
    </td></tr><tr><td class="functionargdecl" align="left">
int *      <span class="emphasis"><em>
major_in_out</em></span>
;            /* compile time lib major version in, server major version out */
    </td></tr><tr><td class="functionargdecl" align="left">
int *      <span class="emphasis"><em>
minor_in_out;      </em></span>
      /* compile time lib min version in, server minor version out */
    </td></tr></tbody></table></div><p>
The <span class="emphasis"><em>
XkbQueryExtension</em></span>
 function determines whether a compatible version of the X Keyboard Extension
is present in the server. If a compatible extension is present, <span class="emphasis"><em>
XkbQueryExtension</em></span>
 returns <span class="emphasis"><em>
True</em></span>
; otherwise, it returns <span class="emphasis"><em>
False</em></span>
.
</p><p>
If a compatible version of Xkb is present, <span class="emphasis"><em>
XkbQueryExtension</em></span>
 initializes the extension. It backfills the major opcode for the keyboard
extension in <span class="emphasis"><em>
opcode_rtrn</em></span>
, the base event code in <span class="emphasis"><em>
event_rtrn</em></span>
<span class="emphasis"><em>
, the base error code</em></span>
 in <span class="emphasis"><em>
error_rtrn</em></span>
, and the major and minor version numbers of the extension in <span class="emphasis"><em>
major_in_out</em></span>
 and <span class="emphasis"><em>
minor_in_out</em></span>
. The major opcode is reported in the <span class="emphasis"><em>
req_major</em></span>
 fields of some Xkb events. For a discussion of the base event code, see
section 4.1. 
</p><p>
As a convenience, you can use the function <span class="emphasis"><em>
XkbOpenDisplay</em></span>
 to perform these three tasks at once: open a connection to an X server, check
for a compatible version of the Xkb extension in both the library and the
server, and initialize the extension for use.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Display *<span class="emphasis"><em>
XkbOpenDisplay</em></span>
(<span class="emphasis"><em>
display_name, event_rtrn, error_rtrn, major_in_out, minor_in_out,
reason_rtrn)</em></span>
    </td></tr><tr><td class="functionargdecl" align="left">
char *      <span class="emphasis"><em>
display_name</em></span>
;      /* hardware display name, which determines the display and
communications domain to be used */
    </td></tr><tr><td class="functionargdecl" align="left">
int *      <span class="emphasis"><em>
event_rtrn</em></span>
;      /* backfilled with the extension base event code */
    </td></tr><tr><td class="functionargdecl" align="left">
int *      <span class="emphasis"><em>
error_rtrn</em></span>
;      /* backfilled with the extension base error code */
    </td></tr><tr><td class="functionargdecl" align="left">
int *      <span class="emphasis"><em>
major_in_out</em></span>
;      /* compile time lib major version in, server major version out */
    </td></tr><tr><td class="functionargdecl" align="left">
int *      <span class="emphasis"><em>
minor_in_out</em></span>
;      /* compile time lib minor version in, server minor version out */
    </td></tr><tr><td class="functionargdecl" align="left">
int *      <span class="emphasis"><em>
reason_rtrn</em></span>
;      /* backfilled with a status code */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbOpenDisplay </em></span>
is a convenience function that opens an X display connection and initializes
the X keyboard extension. In all cases, upon return <span class="emphasis"><em>
reason_rtrn</em></span>
 contains a status value indicating success or the type of failure. If
<span class="emphasis"><em>
major_in_out</em></span>
 and <span class="emphasis"><em>
minor_in_out</em></span>
 are not <span class="emphasis"><em>
NULL</em></span>
, <span class="emphasis"><em>
XkbOpenDisplay</em></span>
 first calls <span class="emphasis"><em>
XkbLibraryVersion</em></span>
 to determine whether the client library is compatible, passing it the values
pointed to by <span class="emphasis"><em>
major_in_out</em></span>
 and <span class="emphasis"><em>
minor_in_out</em></span>
. If the library is incompatible, <span class="emphasis"><em>
XkbOpenDisplay</em></span>
 backfills <span class="emphasis"><em>
major_in_out</em></span>
 and <span class="emphasis"><em>
minor_in_out</em></span>
 with the major and minor extension versions of the library being used and
returns <span class="emphasis"><em>
NULL</em></span>
. If the library is compatible,<span class="emphasis"><em>
 XkbOpenDisplay </em></span>
next calls <span class="emphasis"><em>
XOpenDisplay</em></span>
 with the <span class="emphasis"><em>
display_name</em></span>
. If this fails, the function returns <span class="emphasis"><em>
NULL</em></span>
. If successful, <span class="emphasis"><em>
XkbOpenDisplay </em></span>
calls <span class="emphasis"><em>
XkbQueryExtension</em></span>
 and<span class="emphasis"><em>
 </em></span>
backfills the major and minor Xkb server extension version numbers in <span class="emphasis"><em>
major_in_out</em></span>
 and <span class="emphasis"><em>
minor_in_out</em></span>
.<span class="emphasis"><em>
 </em></span>
If the server extension version is not compatible with the library extension
version or if the server extension is not present, <span class="emphasis"><em>
XkbOpenDisplay </em></span>
closes the display and returns <span class="emphasis"><em>
NULL</em></span>
. When successful, the function returns the display connection<span class="emphasis"><em>
.</em></span>
</p><p>
The possible values for <span class="emphasis"><em>
reason_rtrn</em></span> are:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="emphasis"><em>
XkbOD_BadLibraryVersion</em></span>
 indicates <span class="emphasis"><em>
XkbLibraryVersion </em></span>
returned <span class="emphasis"><em>
False</em></span>.
  </p></li><li class="listitem"><p>
<span class="emphasis"><em>
XkbOD_ConnectionRefused</em></span>
 indicates the display could not be opened.
  </p></li><li class="listitem"><p>
<span class="emphasis"><em>
XkbOD_BadServerVersion</em></span>
 indicates the library and the server have incompatible extension versions.
  </p></li><li class="listitem"><p>
<span class="emphasis"><em>
XkbOD_NonXkbServer</em></span>
 indicates the extension is not present in the X server.
  </p></li><li class="listitem"><p>
<span class="emphasis"><em>
XkbOD_Success</em></span>
 indicates that the function succeeded.
  </p></li></ul></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Disabling_the_Keyboard_Extension"></a>Disabling the Keyboard Extension</h2></div></div></div><p>
If a server supports the Xkb extension, the X library normally implements
preXkb keyboard functions using the Xkb keyboard description and state. The
server Xkb keyboard state may differ from the preXkb keyboard state. This
difference does not affect most clients, but there are exceptions. To allow
these clients to work properly, you may instruct the extension not to use Xkb
functionality.
</p><p>
Call <span class="emphasis"><em>
XkbIgnoreExtension</em></span>
 to prevent core X library keyboard functions from using the X Keyboard
Extension. You must call <span class="emphasis"><em>
XkbIgnoreExtension</em></span>
 before you open a server connection; Xkb does not provide a way to enable or
disable use of the extension once a connection is established.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool<span class="emphasis"><em>
 XkbIgnoreExtension</em></span>
(<span class="emphasis"><em>
ignore</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
ignore</em></span>
;      /* <span class="emphasis"><em>
True</em></span>
 means ignore the extension */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbIgnoreExtension</em></span>
 tells the X library whether to use the X Keyboard Extension on any
subsequently opened X display connections. If ignore is <span class="emphasis"><em>
True</em></span>
, the library does not initialize the Xkb extension when it opens a new
display. This forces the X server to use compatibility mode and communicate
with the client using only core protocol requests and events. If ignore is
<span class="emphasis"><em>
False</em></span>
, the library treats subsequent calls to <span class="emphasis"><em>
XOpenDisplay</em></span>
 normally and uses Xkb extension requests, events, and state. Do not explicitly
use Xkb on a connection for which it is disabled.<span class="emphasis"><em>
 XkbIgnoreExtension</em></span>
 returns <span class="emphasis"><em>
False</em></span>
 if it was unable to apply the ignore request.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Protocol_Errors"></a>Protocol Errors</h2></div></div></div><p>
Many of the Xkb extension library functions described in this document can
cause the X server to report an error, referred to in this document as a
<span class="emphasis"><em>
BadXxx</em></span>
 protocol error, where <span class="emphasis"><em>
Xxx</em></span>
 is some name. These errors are fielded in the normal manner, by the default
Xlib error handler or one replacing it. Note that X protocol errors are not
necessarily reported immediately because of the buffering of X protocol
requests in Xlib and the server.
</p><p>
Table 2.1 lists the protocol errors that can be generated, and their causes. 
</p><div class="table"><a id="idp62936900"></a><p class="title"><strong>Table 2.1. Xkb Protocol Errors</strong></p><div class="table-contents"><table summary="Xkb Protocol Errors" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Error</th><th align="left">Cause</th></tr></thead><tbody><tr><td align="left">BadAccess</td><td align="left">
<p>
The Xkb extension has not been properly initialized
</p>
    </td></tr><tr><td align="left">BadKeyboard</td><td align="left">
<p>
The device specified was not a valid core or input extension device
</p>
    </td></tr><tr><td align="left">BadImplementation</td><td align="left">
<p>
Invalid reply from server
</p>
    </td></tr><tr><td align="left">BadAlloc</td><td align="left">
<p>
Unable to allocate storage
</p>
    </td></tr><tr><td align="left">BadMatch</td><td align="left">
<p>
A compatible version of Xkb was not available in the server or an argument has
correct type and range, but is otherwise invalid
</p>
    </td></tr><tr><td align="left">BadValue</td><td align="left">
<p>
An argument is out of range
</p>
    </td></tr><tr><td align="left">BadAtom</td><td align="left">
<p>
A name is neither a valid Atom or <span class="emphasis"><em>
None</em></span>
</p>
    </td></tr><tr><td align="left">BadDevice</td><td align="left">
<p>
Device, Feedback Class, or Feedback ID invalid
</p>
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
The Xkb extension adds a single protocol error, <span class="emphasis"><em>
BadKeyboard</em></span>
, to the core protocol error set. This error code will be reported as the
<span class="emphasis"><em>
error_rtrn</em></span>
 when <span class="emphasis"><em>
XkbQueryExtension</em></span>
 is called. When a <span class="emphasis"><em>
BadKeyboard</em></span>
 error is reported in an <span class="emphasis"><em>
XErrorEvent</em></span>
, additional information is reported in the <span class="emphasis"><em>
resource_id</em></span>
 field. The most significant byte of the <span class="emphasis"><em>
resource_id</em></span>
 is a further refinement of the error cause, as defined in Table 2.2. The least
significant byte will contain the device, class, or feedback ID as indicated in
the table.
</p><div class="table"><a id="idp62950324"></a><p class="title"><strong>Table 2.2. BadKeyboard Protocol Error resource_id Values</strong></p><div class="table-contents"><table summary="BadKeyboard Protocol Error resource_id Values" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">high-order byte</th><th align="left">value</th><th align="left">meaning</th><th align="left">low-order byte</th></tr></thead><tbody><tr><td align="left">XkbErr_BadDevice</td><td align="left">0xff</td><td align="left">
<p>
device not found
</p>
    </td><td align="left">device ID</td></tr><tr><td align="left">XkbErr_BadClass</td><td align="left">0xfe</td><td align="left">
<p>
device found, but it is of the wrong class
</p>
    </td><td align="left">class ID</td></tr><tr><td align="left">XkbErr_BadId</td><td align="left">0xfd</td><td align="left">
<p>
device found, class ok, but device does not contain a feedback with the
indicated ID
</p>
    </td><td align="left">feedback ID</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Display_and_Device_Specifications_in_Function_Calls"></a>Display and Device Specifications in Function Calls</h2></div></div></div><p>
Where a connection to the server is passed as an argument (Display*) and an
<span class="emphasis"><em>
XkbDescPtr</em></span>
 is also passed as an argument, the Display* argument must match the <span class="emphasis"><em>
dpy</em></span>
 field of the <span class="emphasis"><em>
XkbDescRec</em></span>
 pointed to by the <span class="emphasis"><em>
XkbDescPtr</em></span>
 argument, or else the <span class="emphasis"><em>
dpy</em></span>
 field of the <span class="emphasis"><em>
XkbDescRec</em></span>
 must be <span class="emphasis"><em>
NULL</em></span>
. If they don’t match or the <span class="emphasis"><em>
dpy</em></span>
 field is not <span class="emphasis"><em>
NULL</em></span>
, a <span class="emphasis"><em>
BadMatch</em></span>
 error is returned (either in the return value or a backfilled <span class="emphasis"><em>
Status</em></span>
 variable). Upon successful return, the <span class="emphasis"><em>
dpy</em></span>
 field of the <span class="emphasis"><em>
XkbDescRec</em></span>
 always contains the Display* value passed in.
</p><p>
The Xkb extension can communicate with the X input extension if it is present.
Consequently, there can potentially be more than one input device connected to
the server. Most Xkb library calls that require communicating with the server
involve both a server connection (Display * <span class="emphasis"><em>
dpy</em></span>
) and a device identifier (unsigned int <span class="emphasis"><em>
device_spec</em></span>
). In some cases, the device identifier is implicit and is taken as the
<span class="emphasis"><em>
device_spec</em></span>
 field of an <span class="emphasis"><em>
XkbDescRec</em></span>
 structure passed as an argument.
</p><p>
The device identifier can specify any X input extension device with a <span class="emphasis"><em>
KeyClass</em></span>
 component, or it can specify the constant, <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
. The use of <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 allows applications to indicate the core keyboard without having to determine
its device identifier.
</p><p>
Where an Xkb device identifier is passed as an argument and an <span class="emphasis"><em>
XkbDescPtr</em></span>
 is also passed as an argument, if either the argument or the <span class="emphasis"><em>
XkbDescRec</em></span>
 <span class="emphasis"><em>
device_spec</em></span>
 field is <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
, and if the function returns successfully, the <span class="emphasis"><em>
XkbDescPtr</em></span>
 <span class="emphasis"><em>
device_spec</em></span>
 field will have been converted from <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 to a real Xkb device ID. If the function does not complete successfully, the
<span class="emphasis"><em>
device_spec</em></span>
 field remains unchanged. Subsequently, the device id argument must match the
<span class="emphasis"><em>
device_spec</em></span>
 field of the <span class="emphasis"><em>
XkbDescPtr</em></span>
 argument. If they don’t match, a <span class="emphasis"><em>
BadMatch</em></span>
 error is returned (either in the return value or a backfilled <span class="emphasis"><em>
Status</em></span>
 variable).
</p><p>
When the Xkb extension in the server hands an application a device identifier
to use for the keyboard, that ID is the input extension identifier for the
device if the server supports the X Input Extension. If the server does not
support the input extension, the meaning of the identifier is undefined — the
only guarantee is that when you use <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
, <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 will work and the identifier returned by the server will refer to the core
keyboard device.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Data_Structures"></a>Chapter 3. Data Structures</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Allocating_Xkb_Data_Structures">Allocating Xkb Data Structures</a></span></dt><dt><span class="sect1"><a href="#Adding_Data_and_Editing_Data_Structures">Adding Data and Editing Data Structures</a></span></dt><dt><span class="sect1"><a href="#Making_Changes_to_the_Servers_Keyboard_Description">Making Changes to the Server’s Keyboard Description</a></span></dt><dt><span class="sect1"><a href="#Tracking_Keyboard_Changes_in_the_Server">Tracking Keyboard Changes in the Server</a></span></dt><dt><span class="sect1"><a href="#Freeing_Data_Structures">Freeing Data Structures</a></span></dt></dl></div><p>
An Xkb keyboard description consists of a variety of data structures, each of
which describes some aspect of the keyboard. Although each data structure has
its own peculiarities, there are a number of features common to nearly all Xkb
structures. This chapter describes these common features and techniques for
manipulating them.
</p><p>
Many Xkb data structures are interdependent; changing a field in one might
require changes to others. As an additional complication, some Xkb library
functions allocate related components as a group to reduce fragmentation and
allocator overhead. In these cases, simply allocating and freeing fields of Xkb
structures might corrupt program memory. Creating and destroying such
structures or keeping them properly synchronized during editing is complicated
and error prone.
</p><p>
Xkb provides functions and macros to allocate and free all major data
structures. You should use them instead of allocating and freeing the
structures yourself.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Allocating_Xkb_Data_Structures"></a>Allocating Xkb Data Structures</h2></div></div></div><p>
Xkb provides functions, known as allocators, to create and initialize Xkb data
structures. In most situations, the Xkb functions that read a keyboard
description from the server call these allocators automatically. As a result,
you will seldom have to directly allocate or initialize Xkb data structures.
</p><p>
However, if you need to enlarge an existing structure or construct a keyboard
definition from scratch, you may need to allocate and initialize Xkb data
structures directly. Each major Xkb data structure has its own unique
allocator. The allocator functions share common features: allocator functions
for structures with optional components take as an input argument a mask of
subcomponents to be allocated. Allocators for data structures containing
variable-length data take an argument specifying the initial length of the data.
</p><p>
You may call an allocator to change the size of the space allocated for
variable-length data. When you call an allocator with an existing data
structure as a parameter, the allocator does not change the data in any of the
fields, with one exception: variable-length data might be moved. The allocator
resizes the allocated memory if the current size is too small. This normally
involves allocating new memory, copying existing data to the newly allocated
memory, and freeing the original memory. This possible reallocation is
important to note because local variables pointing into Xkb data structures
might be invalidated by calls to allocator functions.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Adding_Data_and_Editing_Data_Structures"></a>Adding Data and Editing Data Structures</h2></div></div></div><p>
You should edit most data structures via the Xkb-supplied helper functions and
macros, although a few data structures can be edited directly. The helper
functions and macros make sure everything is initialized and interdependent
values are properly updated for those Xkb structures that have
interdependencies. As a general rule, if there is a helper function or macro to
edit the data structure, use it. For example, increasing the width of a type
requires you to resize every key that uses that type. This is complicated and
ugly, which is why there’s an <span class="emphasis"><em>
XkbResizeKeyType</em></span>
 function.
</p><p>
Many Xkb data structures have arrays whose size is reported by two fields. The
first field, whose name is usually prefixed by <span class="emphasis"><em>
sz_</em></span>
, represents the total number of elements that can be stored in the array. The
second field, whose name is usually prefixed by <span class="emphasis"><em>
num_</em></span>
, specifies the number of elements currently stored there. These arrays
typically represent data whose total size cannot always be determined when the
array is created. In these instances, the usual way to allocate space and add
data is as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Call the allocator function with some arbitrary size, as a hint.
    </p></li><li class="listitem"><p>
For those arrays that have an <span class="emphasis"><em>
Xkb...Add...</em></span>
 function, call it each time you want to add new data to the array. The
function expands the array if necessary.
    </p></li></ul></div><p>
For example, call:
</p><p>
XkbAllocGeomShapes(geom,4)
</p><p>
to say "I’ll need space for four new shapes in this geometry." This makes
sure that <span class="emphasis"><em>
sz_shapes</em></span>
 - <span class="emphasis"><em>
num_shapes</em></span>
 &gt;= 4, and resizes the shapes array if it isn’t. If this function
succeeds, you are guaranteed to have space for the number of shapes you need.
</p><p>
When you call an editing function for a structure, you do not need to check for
space, because the function automatically checks the <span class="emphasis"><em>
sz_</em></span>
 and <span class="emphasis"><em>
num_</em></span>
 fields of the array, resizes the array if necessary, adds the entry to the
array, and then updates the <span class="emphasis"><em>
num_</em></span>
 field.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Making_Changes_to_the_Servers_Keyboard_Description"></a>Making Changes to the Server’s Keyboard Description</h2></div></div></div><p>
In Xkb, as in the core protocol, the client and server have independent copies
of the data structures that describe the keyboard. The recommended way to
change some aspect of the keyboard mapping in the X server is to edit a local
copy of the Xkb keyboard description and then send only the changes to the X
server. This method helps eliminate the need to transfer the entire keyboard
description or even an entire data structure for only minor changes.
</p><p>
To help you keep track of the changes you make to a local copy of the keyboard
description, Xkb provides separate special <span class="emphasis"><em>
changes</em></span>
 data structures for each major Xkb data structure. These data structures do
not contain the actual changed values: they only indicate the changes that have
been made to the structures that actually describe the keyboard.
</p><p>
When you wish to change the keyboard description in the server, you first
modify a local copy of the keyboard description and then flag the modifications
in an appropriate changes data structure. When you finish editing the local
copy of the keyboard description, you pass your modified version of the
keyboard description and the modified changes data structure to an Xkb
function. This function uses the modified keyboard description and changes
structure to pass only the changed information to the server. Note that
modifying the keyboard description but not setting the appropriate flags in the
changes data structure causes indeterminate behavior.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Tracking_Keyboard_Changes_in_the_Server"></a>Tracking Keyboard Changes in the Server</h2></div></div></div><p>
The server reports all changes in its keyboard description to any interested
clients via special Xkb events. Just as clients use special changes data
structures to change the keyboard description in the server, the server uses
special changes data structures to tell a client what changed in the server’s
keyboard description.
</p><p>
Unlike clients, however, the server does not always pass the new values when it
reports changes to its copy of the keyboard description. Instead, the server
only passes a changes data structure when it reports changes to its keyboard
description. This is done for efficiency reasons — some clients do not always
need to update their copy of the keyboard description with every report from
the server.
</p><p>
When your client application receives a report from the server indicating the
keyboard description has changed, you can determine the set of changes by
passing the event to an Xkb function that "notes" event information in the
corresponding changes data structure. These "note changes" functions are
defined for all major Xkb components, and their names have the form <span class="emphasis"><em>
XkbNote{Component}Changes</em></span>
, where <span class="emphasis"><em>
Component</em></span>
 is the name of a major Xkb component such as <span class="emphasis"><em>
Map</em></span>
 or <span class="emphasis"><em>
Names</em></span>
. When you want to copy these changes from the server into a local copy of the
keyboard description, use the corresponding <span class="emphasis"><em>
XkbGet{Component}Changes</em></span>
 function<span class="emphasis"><em>
, </em></span>
passing it the changes structure. The function then retrieves only the changed
structures from the server and copies the modified pieces into the local
keyboard description.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Freeing_Data_Structures"></a>Freeing Data Structures</h2></div></div></div><p>
For the same reasons you should not directly use <span class="emphasis"><em>
malloc</em></span>
 to allocate Xkb data structures, you should not free Xkb data structures or
components directly using <span class="emphasis"><em>
free</em></span>
 or <span class="emphasis"><em>
Xfree</em></span>
. Xkb provides functions to free the various data structures and their
components. Always use the free functions supplied by Xkb. There is no
guarantee that any particular field can be safely freed by <span class="emphasis"><em>
free</em></span>
 or <span class="emphasis"><em>
Xfree</em></span>
.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Xkb_Events"></a>Chapter 4. Xkb Events</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Xkb_Event_Types">Xkb Event Types</a></span></dt><dt><span class="sect1"><a href="#Xkb_Event_Data_Structures">Xkb Event Data Structures</a></span></dt><dt><span class="sect1"><a href="#Selecting_Xkb_Events">Selecting Xkb Events</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Event_Masks">Event Masks</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Unified_Xkb_Event_Type">Unified Xkb Event Type</a></span></dt></dl></div><p>
The primary way the X server communicates with clients is by sending X events
to them. Some events are sent to all clients, while others are sent only to
clients that have requested them. Some of the events that can be requested are
associated with a particular window and are only sent to those clients who have
both requested the event and specified the window in which the event occurred.
</p><p>
The Xkb extension uses events to communicate the keyboard status to interested
clients. These events are not associated with a particular window. Instead, all
Xkb keyboard status events are reported to all interested clients, regardless
of which window currently has the keyboard focus and regardless of the grab
state of the keyboard.<a href="#ftn.idp62855532" class="footnote" id="idp62855532"><sup class="footnote">[2]</sup></a> 
</p><p>
The X server reports the events defined by the Xkb extension to your client
application only if you have requested them. You may request Xkb events by
calling either <span class="emphasis"><em>
XkbSelectEvents</em></span>
 or <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
. <span class="emphasis"><em>
XkbSelectEvents</em></span>
 requests Xkb events by their event type and causes them to be reported to your
client application under all circumstances. You can specify a finer granularity
for event reporting by using <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
; in this case events are reported only when the specific detail conditions you
specify have been met.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Xkb_Event_Types"></a>Xkb Event Types</h2></div></div></div><p>
The Xkb Extension adds new event types to the X protocol definition. An Xkb
event type is defined by two fields in the X event data structure. One is the
<span class="emphasis"><em>
type</em></span>
 field, containing the <span class="emphasis"><em>
base event code.</em></span>
 This base event code is a value the X server assigns to each X extension at
runtime and thatidentifies the extension that generated the event; thus, the
event code in the <span class="emphasis"><em>
type</em></span>
 field identifies the event as an Xkb extension event, rather than an event
from another extension or a core X protocol event. You can obtain the base
event code via a call to <span class="emphasis"><em>
XkbQueryExtension</em></span>
 or <span class="emphasis"><em>
XkbOpenDisplay</em></span>
. The second field is the Xkb event type, which contains a value uniquely
identifying each different Xkb event type. Possible values are defined by
constants declared in the header file &lt;X11/extensions/Xkb.h&gt;.
</p><p>
Table 4.1 lists the categories of events defined by Xkb and their associated
event types, as defined in <span class="emphasis"><em>
Xkb.h</em></span>
. Each event is described in more detail in the section referenced for that
event.
</p><div class="table"><a id="idp62860884"></a><p class="title"><strong>Table 4.1. Xkb Event Types</strong></p><div class="table-contents"><table summary="Xkb Event Types" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Event Type</th><th align="left">Conditions Generating Event</th><th align="left">Section</th><th align="left">Page</th></tr></thead><tbody><tr><td align="left">
    <p><span class="emphasis"><em>XkbNewKeyboardNotify</em></span></p>
  </td><td align="left">
    <p>Keyboard geometry; keycode range change</p>
  </td><td align="left">
    <p>19</p>
  </td><td align="left">
    <p>187</p>
  </td></tr><tr><td align="left">
    <p>
    <span class="emphasis"><em>XkbMapNotify</em></span>
    </p>
  </td><td align="left">
    <p>Keyboard mapping change</p>
  </td><td align="left">
    <p>14.4</p>
  </td><td align="left">
    <p>122</p>
  </td></tr><tr><td align="left">
    <p><span class="emphasis"><em>XkbStateNotify</em></span></p>
  </td><td align="left">
    <p>Keyboard state change</p>
  </td><td align="left">
    <p>5.4</p>
  </td><td align="left">
    <p>25</p>
  </td></tr><tr><td align="left">
    <p><span class="emphasis"><em>XkbControlsNotify</em></span></p>
  </td><td align="left">
    <p>Keyboard controls state change</p>
  </td><td align="left">
    <p>10.11</p>
  </td><td align="left">
    <p>79</p>
  </td></tr><tr><td align="left">
    <p><span class="emphasis"><em>XkbIndicatorStateNotify</em></span></p>
  </td><td align="left">
    <p>Keyboard indicators state change</p>
  </td><td align="left">
    <p>8.5</p>
  </td><td align="left">
    <p>45</p>
  </td></tr><tr><td align="left">
    <p><span class="emphasis"><em>XkbIndicatorMapNotify</em></span></p>
  </td><td align="left">
    <p>Keyboard indicators map change</p>
  </td><td align="left">
    <p>8.5</p>
  </td><td align="left">
    <p>45</p>
  </td></tr><tr><td align="left">
    <p><span class="emphasis"><em>XkbNamesNotify</em></span></p>
  </td><td align="left">
    <p>Keyboard name change</p>
  </td><td align="left">
    <p>18.5</p>
  </td><td align="left">
    <p>185</p>
  </td></tr><tr><td align="left">
    <p><span class="emphasis"><em>XkbCompatMapNotify</em></span></p>
  </td><td align="left">
    <p>Keyboard compatibility map change</p>
  </td><td align="left">
    <p>17.5</p>
  </td><td align="left">
    <p>178</p>
  </td></tr><tr><td align="left">
    <p><span class="emphasis"><em>XkbBellNotify</em></span></p>
  </td><td align="left">
    <p>Keyboard bell generated</p>
  </td><td align="left">
    <p>9.4</p>
  </td><td align="left">
    <p>52</p>
  </td></tr><tr><td align="left">
    <p><span class="emphasis"><em>XkbActionMessage</em></span></p>
  </td><td align="left">
    <p>Keyboard action message</p>
  </td><td align="left">
    <p>16.1.11</p>
  </td><td align="left">
    <p>155</p>
  </td></tr><tr><td align="left">
    <p><span class="emphasis"><em>XkbAccessXNotify</em></span></p>
  </td><td align="left">
    <p>AccessX state change</p>
  </td><td align="left">
    <p>10.6.4</p>
  </td><td align="left">
    <p>65</p>
  </td></tr><tr><td align="left">
    <p><span class="emphasis"><em>XkbExtensionDeviceNotify</em></span></p>
  </td><td align="left">
    <p>Extension device change</p>
  </td><td align="left">
    <p>21.6</p>
  </td><td align="left">
    <p>207</p>
  </td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Xkb_Event_Data_Structures"></a>Xkb Event Data Structures</h2></div></div></div><p>
Xkb reports each event it generates in a unique structure holding the data
values needed to describe the conditions the event is reporting. However, all
Xkb events have certain things in common. These common features are contained
in the same fields at the beginning of all Xkb event structures and are
described in the <span class="emphasis"><em>
XkbAnyEvent</em></span>
 structure:
</p><pre class="programlisting">
typedef struct {
      int                type;        /* Xkb extension base event code */
      unsigned long      serial;      /* X server serial number for event */
      Bool               send_event;  /* <span class="emphasis"><em> True</em></span> =&gt; synthetically generated */
      Display *          display;     /* server connection where event
generated */
      Time               time;        /* server time when event generated */
      int                xkb_type;    /* Xkb minor event code */
      unsigned int       device;      /* Xkb device ID, will not be
                                         <span class="emphasis"><em>XkbUseCoreKbd</em></span> */
} <span class="emphasis"><em>XkbAnyEvent</em></span>
;
</pre><p>
For any Xkb event, the <span class="emphasis"><em>
type</em></span>
 field is set to the base event code for the Xkb extension, assigned by the
server to all Xkb extension events. The <span class="emphasis"><em>
serial</em></span>
, <span class="emphasis"><em>
send_event</em></span>
, and <span class="emphasis"><em>
display</em></span>
 fields are as described for all X11 events. The <span class="emphasis"><em>
time</em></span>
 field is set to the time when the event was generated and is expressed in
milliseconds. The <span class="emphasis"><em>
xkb_type</em></span>
 field contains the minor extension event code, which is the extension event
type, and is one of the values listed in Table 4.1. The <span class="emphasis"><em>
device</em></span>
 field contains the keyboard device identifier associated with the event. This
is never <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
, even if the request that generated the event specified a device of <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
. If the request that generated the event specified <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
, <span class="emphasis"><em>
device</em></span>
 contains a value assigned by the server to specify the core keyboard. If the
request that generated the event specified an X input extension device,
<span class="emphasis"><em>
device</em></span>
 contains that same identifier.
</p><p>
Other data fields specific to individual Xkb events are described in subsequent
chapters where the events are described.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Selecting_Xkb_Events"></a>Selecting Xkb Events</h2></div></div></div><p>
Xkb events are selected using an event mask, much the same as normal core X
events are selected. However, unlike selecting core X events, where you must
specify the selection status (on or off) for all possible event types whenever
you wish to change the selection criteria for any one event, Xkb allows you to
restrict the specification to only the event types you wish to change. This
means that you do not need to remember the event selection values for all
possible types each time you want to change one of them.
</p><p>
Many Xkb event types are generated under several different circumstances. When
selecting to receive an Xkb event, you may specify either that you want it
delivered under all circumstances, or that you want it delivered only for a
subset of the possible circumstances.
</p><p>
You can also deselect an event type that was previously selected for, using the
same granularity.
</p><p>
Xkb provides two functions to select and deselect delivery of Xkb events.
<span class="emphasis"><em>
XkbSelectEvents</em></span>
 allows you to select or deselect delivery of more than one Xkb event type at
once. Events selected using <span class="emphasis"><em>
XkbSelectEvents</em></span>
 are delivered to your program under all circumstances that generate the
events. To restrict delivery of an event to a subset of the conditions under
which it occurs, use <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
. <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
 only allows you to change the selection conditions for a single event at a
time, but it provides a means of fine-tuning the conditions under which the
event is delivered.
</p><p>
To select and / or deselect for delivery of one or more Xkb events and have
them delivered under all conditions, use <span class="emphasis"><em>
XkbSelectEvents</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSelectEvents</em></span>
(<span class="emphasis"><em>
display, device_spec, bits_to_change, values_for_bits</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
display</em></span>
;      /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
device_spec</em></span>
;      /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned long int      <span class="emphasis"><em>
bits_to_change;      </em></span>
/* determines events to be selected / deselected */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned long int      <span class="emphasis"><em>
values_for_bits</em></span>
;      /* 1=&gt;select, 0-&gt;deselect; for events in <span class="emphasis"><em>
bits_to_change</em></span>
 */
    </td></tr></tbody></table></div><p>
This request changes the Xkb event selection mask for the keyboard specified by
<span class="emphasis"><em>
device_spec</em></span>
.
</p><p>
Each Xkb event that can be selected is represented by a bit in the <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits</em></span>
 masks. Only the event selection bits specified by the <span class="emphasis"><em>
bits_to_change</em></span>
 parameter are affected; any unspecified bits are left unchanged. To turn on
event selection for an event, set the bit for the event in the <span class="emphasis"><em>
bits_to_change</em></span>
 parameter and set the corresponding bit in the <span class="emphasis"><em>
values_for_bits</em></span>
 parameter. To turn off event selection for an event, set the bit for the event
in the <span class="emphasis"><em>
bits_to_change</em></span>
 parameter and do not set the corresponding bit in the <span class="emphasis"><em>
values_for_bits</em></span>
 parameter. The valid values for both of these parameters are an inclusive
bitwise OR of the masks shown in Table 4.2. There is no interface to return
your client’s current event selection mask. Clients cannot set other
clients’ event selection masks.
</p><p>
If a bit is not set in the <span class="emphasis"><em>
bits_to_change</em></span>
 parameter, but the corresponding bit is set in the <span class="emphasis"><em>
values_for_bits</em></span>
 parameter, a <span class="emphasis"><em>
BadMatch</em></span>
 protocol error results. If an undefined bit is set in either the <span class="emphasis"><em>
bits_to_change</em></span>
 or the <span class="emphasis"><em>
values_for_bits</em></span>
 parameter, a <span class="emphasis"><em>
BadValue</em></span>
 protocol error results.
</p><p>
All event selection bits are initially zero for clients using the Xkb
extension. Once you set some bits, they remain set for your client until you
clear them via another call to <span class="emphasis"><em>
XkbSelectEvents</em></span>
.
</p><p>
<span class="emphasis"><em>
XkbSelectEvents</em></span>
 returns <span class="emphasis"><em>
False</em></span>
 if the Xkb extension has not been initilialized and <span class="emphasis"><em>
True</em></span>
 otherwise.
</p><p>
To select or deselect for a specific Xkb event and optionally place conditions
on when events of that type are reported to your client, use <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
. This allows you to exercise a finer granularity of control over delivery of
Xkb events with <span class="emphasis"><em>
XkbSelectEvents</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
(<span class="emphasis"><em>
display, device_spec, event_type, bits_to_change</em></span>
, <span class="emphasis"><em>
values_for_bits</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
display</em></span>
;      /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
device_spec</em></span>
;      /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
event_type</em></span>
;      /* Xkb event type of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned long int      <span class="emphasis"><em>
bits_to_change</em></span>
;      /* event selection details */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned long int      <span class="emphasis"><em>
values_for_bits</em></span>
;      /* values for bits selected by <span class="emphasis"><em>
bits_to_change</em></span>
 */
    </td></tr></tbody></table></div><p>
While <span class="emphasis"><em>
XkbSelectEvents</em></span>
 allows multiple events to be selected, <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
 changes the selection criteria for a single type of Xkb event. The
interpretation of the <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits</em></span>
 masks depends on the event type in question.
</p><p>
<span class="emphasis"><em>
XkbSelectEventDetails</em></span>
 changes the Xkb event selection mask for the keyboard specified by <span class="emphasis"><em>
device_spec</em></span>
 and the Xkb event specified by <span class="emphasis"><em>
event_type</em></span>
. To turn on event selection for an event detail, set the bit for the detail in
the <span class="emphasis"><em>
bits_to_change</em></span>
 parameter and set the corresponding bit in the <span class="emphasis"><em>
values_for_bits</em></span>
 parameter. To turn off event detail selection for a detail, set the bit for
the detail in the <span class="emphasis"><em>
bits_to_change</em></span>
 parameter and do not set the corresponding bit in the <span class="emphasis"><em>
values_for_bits</em></span>
 parameter.
</p><p>
If an invalid event type is specified, a <span class="emphasis"><em>
BadValue</em></span>
 protocol error results. If a bit is not set in the <span class="emphasis"><em>
bits_to_change</em></span>
 parameter, but the corresponding bit is set in the <span class="emphasis"><em>
values_for_bits</em></span>
 parameter, a <span class="emphasis"><em>
BadMatch</em></span>
 protocol error results. If an undefined bit is set in either the <span class="emphasis"><em>
bits_to_change</em></span>
 or the <span class="emphasis"><em>
values_for_bits</em></span>
 parameter, a <span class="emphasis"><em>
BadValue</em></span>
 protocol error results.
</p><p>
For each type of Xkb event, the legal event details that you can specify in the
<span class="emphasis"><em>
XkbSelectEventDetails</em></span>
 request are listed in the chapters that describe each event in detail.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Event_Masks"></a>Event Masks</h3></div></div></div><p>
The X server reports the events defined by Xkb to your client application only
if you have requested them via a call to <span class="emphasis"><em>
XkbSelectEvents</em></span>
 or <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
. Specify the event types in which you are interested in a mask, as described
in section 4.3.
</p><p>
Table 4.2 lists the event mask constants that can be specified with the  
<span class="emphasis"><em>
XkbSelectEvents</em></span>
 request and the circumstances in which the mask should be specified.
</p><div class="table"><a id="idp64530804"></a><p class="title"><strong>Table 4.2. XkbSelectEvents Mask Constants</strong></p><div class="table-contents"><table summary="XkbSelectEvents Mask Constants" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">Event Mask</th><th align="left">Value</th><th align="left">Notification Wanted</th></tr></thead><tbody><tr><td align="left">
<span class="emphasis"><em>XkbNewKeyboardNotifyMask</em></span>
    </td><td align="left">(1L&lt;&lt;0)</td><td align="left">Keyboard geometry change</td></tr><tr><td align="left">
      <span class="emphasis"><em>XkbMapNotifyMask</em></span>
    </td><td align="left">(1L&lt;&lt;1)</td><td align="left">Keyboard mapping change</td></tr><tr><td align="left">
<p><span class="emphasis"><em>XkbStateNotifyMask</em></span></p>
    </td><td align="left">(1L&lt;&lt;2)</td><td align="left"><p>Keyboard state change</p></td></tr><tr><td align="left">
<p><span class="emphasis"><em>XkbControlsNotifyMask</em></span></p>
    </td><td align="left">(1L&lt;&lt;3)</td><td align="left">Keyboard control change</td></tr><tr><td align="left">
<span class="emphasis"><em>XkbIndicatorStateNotifyMask</em></span>
    </td><td align="left">(1L&lt;&lt;4)</td><td align="left">Keyboard indicator state change</td></tr><tr><td align="left">
<span class="emphasis"><em>XkbIndicatorMapNotifyMask</em></span>
    </td><td align="left">(1L&lt;&lt;5)</td><td align="left">Keyboard indicator map change</td></tr><tr><td align="left">
<span class="emphasis"><em>XkbNamesNotifyMask</em></span>
    </td><td align="left">(1L&lt;&lt;6)</td><td align="left">Keyboard name change</td></tr><tr><td align="left">
<span class="emphasis"><em>XkbCompatMapNotifyMask</em></span>
    </td><td align="left">(1L&lt;&lt;7)</td><td align="left">Keyboard compat map change</td></tr><tr><td align="left">
<span class="emphasis"><em>XkbBellNotifyMask</em></span>
    </td><td align="left">(1L&lt;&lt;8)</td><td align="left">Bell</td></tr><tr><td align="left">
<span class="emphasis"><em>XkbActionMessageMask</em></span>
    </td><td align="left">(1L&lt;&lt;9)</td><td align="left">Action message</td></tr><tr><td align="left">
<span class="emphasis"><em>XkbAccessXNotifyMask</em></span>
    </td><td align="left">(1L&lt;&lt;10)</td><td align="left">AccessX features</td></tr><tr><td align="left">
<span class="emphasis"><em>XkbExtensionDeviceNotifyMask</em></span>
    </td><td align="left">(1L&lt;&lt;11)</td><td align="left">Extension device</td></tr><tr><td align="left">
<span class="emphasis"><em>XkbAllEventsMask</em></span>
    </td><td align="left">(0xFFF)</td><td align="left">All Xkb events</td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Unified_Xkb_Event_Type"></a>Unified Xkb Event Type</h2></div></div></div><p>
The <span class="emphasis"><em>
XkbEvent</em></span>
 structure is a union of the individual structures declared for each Xkb event
type and for the core protocol <span class="emphasis"><em>
XEvent</em></span>
 type. Given an <span class="emphasis"><em>
XkbEvent</em></span>
 structure, you may use the <span class="emphasis"><em>
type</em></span>
 field to determine if the event is an Xkb event (<span class="emphasis"><em>
type</em></span>
 equals the Xkb base event code; see section 2.4). If the event is an Xkb
event, you may then use the <span class="emphasis"><em>
any.xkb_type</em></span>
 field to determine the type of Xkb event and thereafter access the
event-dependent components using the union member corresponding to the
particular Xkb event type.
</p><pre class="programlisting">
typedef union _XkbEvent {
      int                            type;
      XkbAnyEvent                    any;
      XkbStateNotifyEvent            state;
      XkbMapNotifyEvent              map;
      XkbControlsNotifyEvent         ctrls;
      XkbIndicatorNotifyEvent        indicators;
      XkbBellNotifyEvent             bell;
      XkbAccessXNotifyEvent          accessx;
      XkbNamesNotifyEvent            names;
      XkbCompatMapNotifyEvent        compat;
      XkbActionMessageEvent          message;
      XkbExtensionDeviceNotifyEvent  device;
      XkbNewKeyboardNotifyEvent      new_kbd;
      XEvent                         core;
} <span class="emphasis"><em>XkbEvent</em></span>;
</pre><p>
This unified Xkb event type includes a normal <span class="emphasis"><em>
XEvent</em></span>
 as used by the core protocol, so it is straightforward for applications that
use Xkb events to call the X library event functions without having to cast
every reference. For example, to get the next event, you can simply declare a
variable of type <span class="emphasis"><em>
XkbEvent</em></span>
 and call:
</p><p>XNextEvent(dpy,&amp;xkbev.core);</p></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idp62855532" class="footnote"><p><a href="#idp62855532" class="para"><sup class="para">[2] </sup></a>The one exception to this rule is the
XkbExtensionDeviceNotify event report that is sent when a client attempts to
use an unsupported feature of an X Input Extension device (see section 21.4).
</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Keyboard_State"></a>Chapter 5. Keyboard State</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Keyboard_State_Description">Keyboard State Description</a></span></dt><dt><span class="sect1"><a href="#Changing_the_Keyboard_State">Changing the Keyboard State</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Changing_Modifiers">Changing Modifiers</a></span></dt><dt><span class="sect2"><a href="#Changing_Groups">Changing Groups</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Determining_Keyboard_State">Determining Keyboard State</a></span></dt><dt><span class="sect1"><a href="#Tracking_Keyboard_State">Tracking Keyboard State</a></span></dt></dl></div><p>
Keyboard state encompasses all of the transitory information necessary to map a physical key press or release to an appropriate event. The Xkb keyboard state consists of primitive components and additional derived components that are maintained for efficiency reasons. Figure 5.1 shows the components of Xkb keyboard state and their relationships.
</p><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-2.svg"></object><div class="caption">Xkb State</div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Keyboard_State_Description"></a>Keyboard State Description</h2></div></div></div><p>
The Xkb keyboard state is comprised of the state of all keyboard modifiers, the keyboard group, and the state of the pointer buttons. These are grouped into the following components:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The locked group and locked modifiers
  </p></li><li class="listitem"><p>
The latched group and latched modifiers
  </p></li><li class="listitem"><p>
The base group and base modifiers
  </p></li><li class="listitem"><p>
The effective group and effective modifiers
  </p></li><li class="listitem"><p>
The state of the core pointer buttons
  </p></li></ul></div><p>
The <span class="emphasis"><em>
modifiers</em></span>
 are <span class="emphasis"><em>
Shift</em></span>
, <span class="emphasis"><em>
Lock</em></span>
, <span class="emphasis"><em>
Control</em></span>
, and <span class="emphasis"><em>
Mod1</em></span>
-<span class="emphasis"><em>
Mod5</em></span>
, as defined by the core protocol. A modifier can be thought of as a toggle that is either set or unset. All modifiers are initially unset. When a modifier is locked, it is set and remains set for all future key events, until it is explicitly unset. A latched modifier is set, but automatically unsets after the next key event that does not change the keyboard state. Locked and latched modifier state can be changed by keyboard activity or via Xkb extension library functions.
</p><p>
The Xkb extension provides support for <span class="emphasis"><em>
keysym</em></span>
 <span class="emphasis"><em>
groups</em></span>
, as defined by ISO9995:
</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">Group</span></p></td><td><p>
A logical state of a keyboard providing access to a collection of characters.
A group usually contains a set of characters that logically belong together
and that may be arranged on several shift levels within that group.
      </p></td></tr></tbody></table></div><p>
The Xkb extension supports up to four keysym groups. Groups are named beginning with one and indexed beginning with zero. All group states are indicated using the group index. At any point in time, there is zero or one locked group, zero or one latched group, and one base group. When a group is locked, it supersedes any previous locked group and remains the locked group for all future key events, until a new group is locked. A latched group applies only to the next key event that does not change the keyboard state. The locked and latched group can be changed by keyboard activity or via Xkb extension library functions.
</p><p>
Changing to a different group changes the keyboard state to produce characters from a different group. Groups are typically used to switch between keysyms of different languages and locales.
</p><p>
The <span class="emphasis"><em>
pointer buttons</em></span>
 are <span class="emphasis"><em>
Button1</em></span>
 - <span class="emphasis"><em>
Button5</em></span>
, as defined by the core protocol.
</p><p>
The <span class="emphasis"><em>
base group</em></span>
 and <span class="emphasis"><em>
base modifiers</em></span>
 represent keys that are physically or logically down. These
and the pointer buttons can be changed by keyboard activity and
not by Xkb requests. It is possible for a key to be logically
down, but not physically down, and neither latched nor locked.
<a href="#ftn.idp64461948" class="footnote" id="idp64461948"><sup class="footnote">[3]</sup></a>

</p><p>
The <span class="emphasis"><em>
effective modifiers</em></span>
 are the bitwise union of the locked, latched, and the base modifiers.
</p><p>
The <span class="emphasis"><em>
effective group</em></span>
 is the arithmetic sum of the group indices of the latched group, locked group, and base group, which is then normalized by some function. The result is a meaningful group index.
</p><table border="0" summary="Simple list" class="simplelist"><tr><td>
n = number of keyboard groups, 1&lt;= n &lt;= 4
</td></tr><tr><td>
0 &lt;= any of locked, latched, or base group &lt; n
</td></tr><tr><td>
effective group = f(locked group + latched group + base group)
</td></tr></table><p>
The function f ensures that the effective group is within range. The precise function is specified for the keyboard and can be retrieved through the keyboard description. It may wrap around, clamp down, or default. Few applications will actually examine the effective group, and far fewer still will examine the locked, latched, and base groups.
</p><p>
There are two circumstances under which groups are normalized:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
The global locked or effective group changes. In this case, the changed group is normalized into range according to the settings of the <span class="emphasis"><em>
groups_wrap</em></span>
 field of the <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure for the keyboard (see section 10.7.1). 
  </p></li><li class="listitem"><p>

The Xkb library is interpreting an event with an effective group that is legal for the keyboard as a whole, but not for the key in question. In this case, the group to use for this event only is determined using the <span class="emphasis"><em>
group_info</em></span>
 field of the key symbol mapping (<span class="emphasis"><em>
XkbSymMapRec</em></span>
) for the event key.
  </p></li></ol></div><p>
Each nonmodifier key on a keyboard has zero or more symbols, or keysyms, associated with it. These are the logical symbols that the key can generate when it is pressed. The set of all possible keysyms for a keyboard is divided into groups. Each key is associated with zero or more groups; each group contains one or more symbols. When a key is pressed, the determination of which symbol for the key is selected is based on the effective group and the shift level, which is determined by which modifiers are set.
</p><p>
A client that does not explicitly call Xkb functions, but that otherwise makes use of an X library containing the Xkb extension, will have keyboard state represented in bits 0 - 14 of the state field of events that report modifier and button state. Such a client is said to be <span class="emphasis"><em>
Xkb-capable</em></span>
. A client that does explicitly call Xkb functions is an <span class="emphasis"><em>
Xkb-aware</em></span>
 client. The Xkb keyboard state includes information derived from the effective state and from two server parameters that can be set through the keyboard extension. The following components of keyboard state pertain to Xkb-capable and Xkb-aware clients:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
lookup state: lookup group and lookup modifiers
  </p></li><li class="listitem"><p>
grab state: grab group and grab modifiers
  </p></li></ul></div><p>
The <span class="emphasis"><em>
lookup modifiers</em></span>
 and <span class="emphasis"><em>
lookup group</em></span>
 are represented in the state field of core X events. The modifier state and keycode of a key event are used to determine the symbols associated with the event. For <span class="emphasis"><em>
KeyPress</em></span>
 and <span class="emphasis"><em>
KeyRelease</em></span>
 events, the lookup modifiers are computed as:
</p><div class="literallayout"><p><br />
   ((base | latched | locked) &amp; ~<span class="emphasis"><em> server_internal_modifiers</em></span>)<br />
</p></div><p>
Otherwise the lookup modifiers are computed as:
</p><div class="literallayout"><p><br />
(((base | latched | (locked &amp; ~<span class="emphasis"><em> ignore_locks</em></span>)) &amp; ~<span class="emphasis"><em> server_internal_modifiers</em></span>)<br />
</p></div><p>
The lookup group is the same as the effective group.
</p><p>
When an Xkb-capable or Xkb-aware client wishes to map a keycode to a keysym, it should use the <span class="emphasis"><em>
lookup state</em></span>
 — the lookup group and the lookup modifiers.
</p><p>
The <span class="emphasis"><em>
grab state</em></span>
 is the state used when matching events to passive grabs. If the event activates a grab, the <span class="emphasis"><em>
grab modifiers</em></span>
 and <span class="emphasis"><em>
grab group</em></span>
 are represented in the state field of core X events; otherwise, the lookup state is used. The grab modifiers are computed as:
</p><div class="literallayout"><p><br />
(((base | latched | (locked &amp; ~ignore_locks)) &amp; ~server_internal_modifiers)<br />
</p></div><p>
If the server’s <span class="emphasis"><em>
IgnoreGroupLock</em></span>
 control (see section 10.7.3) is not set, the grab group is the same as the effective group. Otherwise, the grab group is computed from the base group and latched group, ignoring the locked group.
</p><p>
The final three components of Xkb state are applicable to clients that are not linked with an Xlib containing the X keyboard extension library and therefore are not aware of the keyboard extension (<span class="emphasis"><em>
Xkb-unaware </em></span>
clients):
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The compatibility modifier state
  </p></li><li class="listitem"><p>
The compatibility lookup modifier state
  </p></li><li class="listitem"><p>
The compatibility grab modifier state
  </p></li></ul></div><p>
The X11 protocol interpretation of modifiers does not include direct support for multiple groups. When an Xkb-extended X server connects to an Xkb-unaware client, the compatibility states remap the keyboard group into a core modifier whenever possible. The compatibility state corresponds to the effective modifier and effective group state, with the group remapped to a modifier. The compatibility lookup and grab states correspond to the lookup and grab states, respectively, with the group remapped to a modifier. The compatibility lookup state is reported in events that do not trigger passive grabs; otherwise, the compatibility grab state is reported.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Changing_the_Keyboard_State"></a>Changing the Keyboard State</h2></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Changing_Modifiers"></a>Changing Modifiers</h3></div></div></div><p>
The functions in this section that change the use of modifiers use a mask in the parameter <span class="emphasis"><em>
affect</em></span>
. It is a bitwise inclusive OR of the legal modifier masks:
</p><div class="table"><a id="idp64445828"></a><p class="title"><strong>Table 5.1. Real Modifier Masks</strong></p><div class="table-contents"><table summary="Real Modifier Masks" border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td align="left">Mask</td></tr><tr><td align="left">ShiftMask</td></tr><tr><td align="left">LockMask</td></tr><tr><td align="left">ControlMask</td></tr><tr><td align="left">Mod1Mask</td></tr><tr><td align="left">Mod2Mask</td></tr><tr><td align="left">Mod3Mask</td></tr><tr><td align="left">Mod4Mask</td></tr><tr><td align="left">Mod5Mask</td></tr></tbody></table></div></div><br class="table-break" /><p>
To lock and unlock any of the eight real keyboard modifiers, use <span class="emphasis"><em>
XkbLockModifiers:</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em> XkbLockModifiers</em></span>
(<span class="emphasis"><em>
display, device_spec, affect, values</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
display</em></span>
;            /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
device_spec</em></span>
;            /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      affect</em></span>
;            /* mask of real modifiers whose lock state is to change */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
values</em></span>
;            /* 1 =&gt; lock, 0 =&gt; unlock; only for modifiers selected by <span class="emphasis"><em>
affect</em></span>
 */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbLockModifiers</em></span>
 sends a request to the server to lock the real modifiers selected by both <span class="emphasis"><em>
affect</em></span>
 and <span class="emphasis"><em>
values</em></span>
 and to unlock the real modifiers selected by <span class="emphasis"><em>
affect</em></span>
 but not selected by <span class="emphasis"><em>
values</em></span>
. <span class="emphasis"><em>
XkbLockModifiers</em></span>
 does not wait for a reply from the server. It returns <span class="emphasis"><em>
True</em></span>
 if the request was sent, and <span class="emphasis"><em>
False</em></span>
 otherwise.
</p><p>
To latch and unlatch any of the eight real keyboard modifiers, use <span class="emphasis"><em>
XkbLatchModifiers:</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbLatchModifiers</em></span>
(d<span class="emphasis"><em>
isplay, device_spec, affect, values</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
display</em></span>
;            /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
device_spec</em></span>
;            /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      affect</em></span>
;            /* mask of modifiers whose latch state is to change */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int <span class="emphasis"><em>values</em></span>;
/* 1 =&gt; latch, 0 =&gt; unlatch; only for mods selected by <span class="emphasis"><em>
affect</em></span>
 */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbLatchModifiers</em></span>
 sends a request to the server to latch the real modifiers selected by both <span class="emphasis"><em>
affect</em></span>
 and <span class="emphasis"><em>
values</em></span>
 and to unlatch the real modifiers selected by <span class="emphasis"><em>
affect</em></span>
 but not selected by <span class="emphasis"><em>
values</em></span>
. <span class="emphasis"><em>
XkbLatchModifiers</em></span>
 does not wait for a reply from the server. It returns <span class="emphasis"><em>
True</em></span>
 if the request was sent, and <span class="emphasis"><em>
False</em></span>
 otherwise.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Changing_Groups"></a>Changing Groups</h3></div></div></div><p>
Reference the keysym group indices with these symbolic constants:
</p><div class="table"><a id="idp64627956"></a><p class="title"><strong>Table 5.2. Symbolic Group Names</strong></p><div class="table-contents"><table summary="Symbolic Group Names" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left">Symbolic Name</td><td align="left">Value</td></tr><tr><td align="left">XkbGroup1Index</td><td align="left">0</td></tr><tr><td align="left">XkbGroup2Index</td><td align="left">1</td></tr><tr><td align="left">XkbGroup3Index</td><td align="left">2</td></tr><tr><td align="left">XkbGroup4Index</td><td align="left">3</td></tr></tbody></table></div></div><br class="table-break" /><p>
To lock the keysym group, use <span class="emphasis"><em>
XkbLockGroup. </em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbLockGroup</em></span>
(<span class="emphasis"><em>
display, device_spec, group</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
display</em></span>
;            /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
device_spec</em></span>
;            /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
group</em></span>
;            /* index of the keysym group to lock */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbLockGroup</em></span>
 sends a request to the server to lock the specified <span class="emphasis"><em>
group </em></span>
and does not wait for a reply. It returns <span class="emphasis"><em>
True</em></span>
 if the request was sent and <span class="emphasis"><em>
False</em></span>
 otherwise.
</p><p>
To latch the keysym group, use <span class="emphasis"><em>
XkbLatchGroup.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbLatchGroup</em></span>
(<span class="emphasis"><em>
display, device_spec, group</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
display</em></span>
;            /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      device_spec</em></span>
;            /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      group</em></span>
;            /* index of the keysym group to latch */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbLatchGroup</em></span>
 sends a request to the server to latch the specified group and does not wait for a reply. It returns <span class="emphasis"><em>
True</em></span>
 if the request was sent and <span class="emphasis"><em>
False</em></span>
 otherwise.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Determining_Keyboard_State"></a>Determining Keyboard State</h2></div></div></div><p>
Xkb keyboard state may be represented in an <span class="emphasis"><em>
XkbStateRec</em></span>
 structure:
</p><pre class="programlisting">
typedef struct {
      unsigned char            group;                /* effective group index */
      unsigned char            base_group;           /* base group index */
      unsigned char            latched_group;        /* latched group index */
      unsigned char            locked_group;         /* locked group index */
      unsigned char            mods;                 /* effective modifiers */
      unsigned char            base_mods;            /* base modifiers */
      unsigned char            latched_mods;         /* latched modifiers */
      unsigned char            locked_mods;          /* locked modifiers */
      unsigned char            compat_state;         /* effective group =&gt; modifiers */
      unsigned char            grab_mods;            /* modifiers used for grabs */
      unsigned char            compat_grab_mods;     /* mods used for compatibility mode grabs */
      unsigned char            lookup_mods;          /* modifiers used to lookup symbols */
      unsigned char            compat_lookup_mods;   /* mods used for compatibility lookup */
      unsigned short            ptr_buttons;         /* 1 bit =&gt; corresponding pointer btn is down */
} <span class="emphasis"><em>
XkbStateRec</em></span>
,*XkbStatePtr;
</pre><p>
To obtain the keyboard state, use <span class="emphasis"><em>
XkbGetState.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetState</em></span>
(<span class="emphasis"><em>
display</em></span>
, <span class="emphasis"><em>
device_spec</em></span>
, <span class="emphasis"><em>
state_return</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            <span class="emphasis"><em>
display</em></span>
;            /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
device_spec</em></span>
;            /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbStatePtr            <span class="emphasis"><em>
state_return</em></span>
;            /* backfilled with Xkb state */
    </td></tr></tbody></table></div><p>
The <span class="emphasis"><em>
XkbGetState </em></span>
function queries the server for the current keyboard state, waits for a reply, and then backfills <span class="emphasis"><em>
state_return</em></span>
 with the results.
</p><p>
All group values are expressed as group indices in the range [0..3]. Modifiers and the compatibility modifier state values are expressed as the bitwise union of the core X11 modifier masks. The pointer button state is reported as in the core X11 protocol.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Tracking_Keyboard_State"></a>Tracking Keyboard State</h2></div></div></div><p>
The Xkb extension reports <span class="emphasis"><em>
XkbStateNotify </em></span>
events to clients wanting notification whenever the Xkb state changes. The changes reported include changes to any aspect of the keyboard state: when a modifier is set or unset, when the current group changes, or when a pointer button is pressed or released. As with all Xkb events, <span class="emphasis"><em>
XkbStateNotify</em></span>
 events are reported to all interested clients without regard to the current keyboard input focus or grab state.
</p><p>
There are many different types of Xkb state changes. Xkb defines an event detail mask corresponding to each type of change. The event detail masks are listed in Table 5.3.
</p><div class="table"><a id="idp64657620"></a><p class="title"><strong>Table 5.3. XkbStateNotify Event Detail Masks</strong></p><div class="table-contents"><table summary="XkbStateNotify Event Detail Masks" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Mask</th><th align="left">Value</th></tr></thead><tbody><tr><td align="left">XkbModifierStateMask</td><td align="left">(1L &lt;&lt; 0)</td></tr><tr><td align="left">XkbModifierBaseMask</td><td align="left">(1L &lt;&lt; 1)</td></tr><tr><td align="left">XkbModifierLatchMask</td><td align="left">(1L &lt;&lt; 2)</td></tr><tr><td align="left">XkbModifierLockMask</td><td align="left">(1L &lt;&lt; 3)</td></tr><tr><td align="left">XkbGroupStateMask</td><td align="left">(1L &lt;&lt; 4)</td></tr><tr><td align="left">XkbGroupBaseMask</td><td align="left">(1L &lt;&lt; 5)</td></tr><tr><td align="left">XkbGroupLatchMask</td><td align="left">(1L &lt;&lt; 6)</td></tr><tr><td align="left">XkbGroupLockMask</td><td align="left">(1L &lt;&lt; 7)</td></tr><tr><td align="left">XkbCompatStateMask</td><td align="left">(1L &lt;&lt; 8)</td></tr><tr><td align="left">XkbGrabModsMask</td><td align="left">(1L &lt;&lt; 9)</td></tr><tr><td align="left">XkbCompatGrabModsMask</td><td align="left">(1L &lt;&lt; 10)</td></tr><tr><td align="left">XkbLookupModsMask</td><td align="left">(1L &lt;&lt; 11)</td></tr><tr><td align="left">XkbCompatLookupModsMask</td><td align="left">(1L &lt;&lt; 12)</td></tr><tr><td align="left">XkbPointerButtonMask</td><td align="left">(1L &lt;&lt; 13)</td></tr><tr><td align="left">XkbAllStateComponentsMask</td><td align="left">(0x3fff)</td></tr></tbody></table></div></div><br class="table-break" /><p>
To track changes in the keyboard state for a particular device, select to receive <span class="emphasis"><em>
XkbStateNotify</em></span>
 events by calling either <span class="emphasis"><em>
XkbSelectEvents</em></span>
 or <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
 (see section 4.3). 
</p><p>
To receive <span class="emphasis"><em>
XkbStateNotify</em></span>
 events under all possible conditions, use <span class="emphasis"><em>
XkbSelectEvents</em></span>
 and pass <span class="emphasis"><em>
XkbStateNotifyMask</em></span>
 in both <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits</em></span>
.
</p><p>
To receive <span class="emphasis"><em>
XkbStateNotify</em></span>
 events only under certain conditions, use <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
 using <span class="emphasis"><em>
XkbStateNotify</em></span>
 as the <span class="emphasis"><em>
event_type</em></span>
 and specifying the desired state changes in <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits</em></span>
 using mask bits from Table 5.3. 
</p><p>
The structure for <span class="emphasis"><em>
XkbStateNotify</em></span>
 events is:
</p><pre class="programlisting">
typedef struct {
      int            type;            /* Xkb extension base event code */
      unsigned long  serial;          /* X server serial number for event */
      Bool           send_event;      /* <span class="emphasis"><em> True</em></span> =&gt; synthetically generated */
      Display *      display;         /* server connection where event generated */
      Time           time;            /* server time when event generated */
      int            xkb_type;        /* <span class="emphasis"><em> XkbStateNotify</em></span> */
      int            device;          /* Xkb device ID, will not be <span class="emphasis"><em> XkbUseCoreKbd</em></span> */
      unsigned int   changed;         /* bits indicating what has changed */
      int            group;           /* group index of effective group */
      int            base_group;      /* group index of base group */
      int            latched_group;   /* group index of latched group */
      int            locked_group;    /* group index of locked group */
      unsigned int   mods;            /* effective modifiers */
      unsigned int   base_mods;       /* base modifiers */
      unsigned int   latched_mods;    /* latched modifiers */
      unsigned int   locked_mods;     /* locked modifiers */
      int            compat_state;    /* computed compatibility state */
      unsigned char  grab_mods;       /* modifiers used for grabs */
      unsigned char  compat_grab_mods;  /* modifiers used for compatibility grabs */
      unsigned char  lookup_mods;     /* modifiers used to lookup symbols */
      unsigned char  compat_lookup_mods;                  /* mods used for compatibility look up */
      int            ptr_buttons;     /* core pointer buttons */
      KeyCode        keycode;         /* keycode causing event, 0 if programmatic */
      char           event_type;      /* core event if <span class="emphasis"><em> req_major</em></span> or
                                         <span class="emphasis"><em> req_minor</em></span> non zero */
      char           req_major;       /* major request code if program trigger, else 0 */
      char           req_minor;       /* minor request code if program trigger, else 0 */
} <span class="emphasis"><em>XkbStateNotifyEvent</em></span>
;
</pre><p>
When you receive an <span class="emphasis"><em>
XkbStateNotify</em></span>
 event, the <span class="emphasis"><em>
changed</em></span>
 field indicates which elements of keyboard state have changed.
This will be the bitwise inclusive OR of one or more of the <span class="emphasis"><em>
XkbStateNotify</em></span>
 event detail masks shown in Table 5.3. All fields reported in  
the event are valid, but only those indicated in <span class="emphasis"><em>
changed</em></span>
 have changed values.
</p><p>
The <span class="emphasis"><em>
group</em></span>
 field is the group index of the effective keysym group. The <span class="emphasis"><em>
base_group</em></span>
, <span class="emphasis"><em>
latched_group</em></span>
, and <span class="emphasis"><em>
locked_group</em></span>
 fields are set to a group index value representing the base group,
the latched group, and the locked group, respectively. The X
server can set the modifier and compatibility state fields to
a union of the core modifier mask bits; this union represents the
corresponding modifier states. The <span class="emphasis"><em>ptr_button</em></span>
 field gives the state of the core pointer buttons as a
mask composed of an inclusive OR of zero or more of the
core pointer button masks.
</p><p>
Xkb state changes can occur either in response to keyboard
activity or under application control. If a key event
caused the state change, the <span class="emphasis"><em>
keycode</em></span>
 field gives the keycode of the key event, and the <span class="emphasis"><em>
event_type</em></span>
 field is set to either <span class="emphasis"><em>KeyPress</em></span>
 or <span class="emphasis"><em>
KeyRelease</em></span>
. If a pointer button event caused the state change, the <span class="emphasis"><em>
keycode</em></span>
 field is zero, and the <span class="emphasis"><em>event_type</em></span>
 field is set to either <span class="emphasis"><em>ButtonPress</em></span>
 or <span class="emphasis"><em>ButtonRelease</em></span>
. Otherwise, the major and minor codes of the request that caused the
state change are given in the <span class="emphasis"><em>
req_major</em></span>
 and <span class="emphasis"><em>
req_minor</em></span>
 fields, and the <span class="emphasis"><em>
keycode</em></span>
 field is zero. The <span class="emphasis"><em>
req_major</em></span>
 value is the same as the major extension opcode.
</p></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idp64461948" class="footnote"><p><a href="#idp64461948" class="para"><sup class="para">[3] </sup></a>
Keys may be logically down when they are physically up because
of their electrical properties or because of the keyboard extension
in the X server having filtered the key release, for esoteric reasons.
</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Complete_Keyboard_Description"></a>Chapter 6. Complete Keyboard Description</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#The_XkbDescRec_Structure">The XkbDescRec Structure</a></span></dt><dt><span class="sect1"><a href="#Obtaining_a_Keyboard_Description_from_the_Server">Obtaining a Keyboard Description from the Server</a></span></dt><dt><span class="sect1"><a href="#Tracking_Changes_to_the_Keyboard_Description_in_the_Server">Tracking Changes to the Keyboard Description in the Server</a></span></dt><dt><span class="sect1"><a href="#Allocating_and_Freeing_a_Keyboard_Description">Allocating and Freeing a Keyboard Description</a></span></dt></dl></div><p>
The complete Xkb description for a keyboard device is accessed using a single
structure containing pointers to major Xkb components. This chapter describes
this single structure and provides references to other sections of this
document that discuss the major Xkb components in detail.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="The_XkbDescRec_Structure"></a>The XkbDescRec Structure</h2></div></div></div><p>
The complete description of an Xkb keyboard is given by an <span class="emphasis"><em>
XkbDescRec</em></span>
. The component structures in the <span class="emphasis"><em>
XkbDescRec</em></span>
 represent the major Xkb components outlined in Figure 1.1. 
</p><pre class="programlisting">
typedef struct {
      struct _XDisplay *                  display;            /* connection to
X server */
      unsigned short                  flags;            /* private to Xkb, do
not modify */
      unsigned short                  device_spec;            /* device of
interest */
      KeyCode                  min_key_code;            /* minimum keycode for
device */
      KeyCode                  max_key_code;            /* maximum keycode for
device */
      XkbControlsPtr                  ctrls;            /* controls */
      XkbServerMapPtr                  server;            /* server keymap */
      XkbClientMapPtr                  map;            /* client keymap */
      XkbIndicatorPtr                  indicators;            /* indicator map
*/
      XkbNamesPtr                  names;            /* names for all
components */
      XkbCompatMapPtr                  compat;            /* compatibility map
*/
      XkbGeometryPtr                  geom;            /* physical geometry of
keyboard */
} <span class="emphasis"><em>
XkbDescRec</em></span>
, *XkbDescPtr;
</pre><p>
The <span class="emphasis"><em>
display</em></span>
 field points to an X display structure. The <span class="emphasis"><em>
flags</em></span>
 field is private to the library: modifying <span class="emphasis"><em>
flags</em></span>
 may yield unpredictable results. The <span class="emphasis"><em>
device_spec</em></span>
 field specifies the device identifier of the keyboard input device, or
<span class="emphasis"><em>
XkbUseCoreKeyboard</em></span>
, which specifies the core keyboard device. The <span class="emphasis"><em>
min_key_code</em></span>
 and <span class="emphasis"><em>
max_key_code</em></span>
 fields specify the least and greatest keycode that can be returned by the
keyboard.
</p><p>
The other fields specify structure components of the keyboard description and
are described in detail in other sections of this document. Table 6.1
identifies the subsequent sections of this document that discuss the individual
components of the <span class="emphasis"><em>
XkbDescRec</em></span>
.
</p><div class="table"><a id="idp64607076"></a><p class="title"><strong>Table 6.1. XkbDescRec Component References</strong></p><div class="table-contents"><table summary="XkbDescRec Component References" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">XkbDescRec Field</th><th align="left">For more info</th></tr></thead><tbody><tr><td align="left">ctrls</td><td align="left">Chapter 10</td></tr><tr><td align="left">server</td><td align="left">Chapter 16</td></tr><tr><td align="left">map</td><td align="left">Chapter 15</td></tr><tr><td align="left">indicators</td><td align="left">Chapter 8</td></tr><tr><td align="left">names</td><td align="left">Chapter 18</td></tr><tr><td align="left">compat</td><td align="left">Chapter 17</td></tr><tr><td align="left">geom</td><td align="left">Chapter 13</td></tr></tbody></table></div></div><br class="table-break" /><p>
Each structure component has a corresponding mask bit that is used in function
calls to indicate that the structure should be manipulated in some manner, such
as allocating it or freeing it. These masks and their relationships to the
fields in the <span class="emphasis"><em>
XkbDescRec</em></span>
 are shown in Table 6.2. 
</p><div class="table"><a id="idp64591540"></a><p class="title"><strong>Table 6.2. Mask Bits for XkbDescRec</strong></p><div class="table-contents"><table summary="Mask Bits for XkbDescRec" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">Mask Bit</th><th align="left">XkbDescRec Field</th><th align="left">Value</th></tr></thead><tbody><tr><td align="left">XkbControlsMask</td><td align="left">ctrls</td><td align="left">(1L&lt;&lt;0)</td></tr><tr><td align="left">XkbServerMapMask</td><td align="left">server</td><td align="left">(1L&lt;&lt;1)</td></tr><tr><td align="left">XkbIClientMapMask</td><td align="left">map</td><td align="left">(1L&lt;&lt;2)</td></tr><tr><td align="left">XkbIndicatorMapMask</td><td align="left">indicators</td><td align="left">(1L&lt;&lt;3)</td></tr><tr><td align="left">XkbNamesMask</td><td align="left">names</td><td align="left">(1L&lt;&lt;4)</td></tr><tr><td align="left">XkbCompatMapMask</td><td align="left">compat</td><td align="left">(1L&lt;&lt;5)</td></tr><tr><td align="left">XkbGeometryMask</td><td align="left">geom</td><td align="left">(1L&lt;&lt;6)</td></tr><tr><td align="left">XkbAllComponentsMask</td><td align="left">All Fields</td><td align="left">(0x7f)</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Obtaining_a_Keyboard_Description_from_the_Server"></a>Obtaining a Keyboard Description from the Server</h2></div></div></div><p>
To retrieve one or more components of a keyboard device description, use
<span class="emphasis"><em>
XkbGetKeyboard</em></span>
 (see also <span class="emphasis"><em>
XkbGetKeyboardbyName</em></span>
).
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbDescPtr <span class="emphasis"><em>
XkbGetKeyboard</em></span>
(<span class="emphasis"><em>
display, which, device_spec</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display * <span class="emphasis"><em>
      display</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
which</em></span>
;            /* mask indicating components to return */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      device_spec</em></span>
;            /* device for which to fetch description, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetKeyboard </em></span>
allocates and returns a pointer to a keyboard description. It queries the
server for those components specified in the <span class="emphasis"><em>
which</em></span>
 parameter for device <span class="emphasis"><em>
device_spec</em></span>
 and copies the results to the <span class="emphasis"><em>
XkbDescRec</em></span>
 it allocated. The remaining fields in the keyboard description are set to
<span class="emphasis"><em>
NULL</em></span>
. The valid masks for <span class="emphasis"><em>
which</em></span>
 are those listed in Table 6.2. 
</p><p>
<span class="emphasis"><em>
XkbGetKeyboard</em></span>
 can generate <span class="emphasis"><em>
BadAlloc</em></span>
 protocol errors.
</p><p>
To free the returned keyboard description, use <span class="emphasis"><em>
XkbFreeKeyboard</em></span>
 (see section 6.4). 
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Tracking_Changes_to_the_Keyboard_Description_in_the_Server"></a>Tracking Changes to the Keyboard Description in the Server</h2></div></div></div><p>
The server can generate events whenever its copy of the keyboard description
for a device changes. Refer to section 14.4 for detailed information on  
tracking changes to the keyboard description.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Allocating_and_Freeing_a_Keyboard_Description"></a>Allocating and Freeing a Keyboard Description</h2></div></div></div><p>
Applications seldom need to directly allocate a keyboard description; calling
<span class="emphasis"><em>
XkbGetKeyboard</em></span>
 usually suffices. In the event you need to create a keyboard description from
scratch, however, use <span class="emphasis"><em>
XkbAllocKeyboard</em></span>
 rather than directly calling <span class="emphasis"><em>
malloc </em></span>
or <span class="emphasis"><em>
Xmalloc</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbDescRec * <span class="emphasis"><em>
XkbAllocKeyboard</em></span>
(void)
    </td></tr></tbody></table></div><p>
If <span class="emphasis"><em>
XkbAllocKeyboard</em></span>
 fails to allocate the keyboard description, it returns <span class="emphasis"><em>
NULL</em></span>
. Otherwise, it returns a pointer to an empty keyboard description structure.
The <span class="emphasis"><em>
device_spec</em></span>
 field will have been initialized to <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
. You may then either fill in the structure components or use Xkb functions to
obtain values for the structure components from a keyboard device.
</p><p>
To destroy either an entire an <span class="emphasis"><em>
XkbDescRec</em></span>
 or just some of its members, use <span class="emphasis"><em>
XkbFreeKeyboard.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeKeyboard</em></span>
<span class="emphasis"><em>
(xkb, which, free_all</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr <span class="emphasis"><em>
            xkb</em></span>
;            /* keyboard description with components to free */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
      which</em></span>
;            /* mask selecting components to free */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool <span class="emphasis"><em>
            free_all</em></span>
;            /* <span class="emphasis"><em>
True</em></span>
 =&gt; free all components and <span class="emphasis"><em>
xkb</em></span>
 */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbFreeKeyboard</em></span>
 frees the components of <span class="emphasis"><em>
xkb</em></span>
 specified by <span class="emphasis"><em>
which</em></span>
 and sets the corresponding values to <span class="emphasis"><em>
NULL</em></span>
. If <span class="emphasis"><em>
free_all</em></span>
 is <span class="emphasis"><em>
True</em></span>
, <span class="emphasis"><em>
XkbFreeKeyboard</em></span>
 frees every non-<span class="emphasis"><em>
NULL</em></span>
 component of <span class="emphasis"><em>
xkb</em></span>
 and then frees the <span class="emphasis"><em>
xkb</em></span>
 structure itself.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Virtual_Modifiers"></a>Chapter 7. Virtual Modifiers</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Virtual_Modifier_Names_and_Masks">Virtual Modifier Names and Masks</a></span></dt><dt><span class="sect1"><a href="#Modifier_Definitions">Modifier Definitions</a></span></dt><dt><span class="sect1"><a href="#Binding_Virtual_Modifiers_to_Real_Modifiers">Binding Virtual Modifiers to Real Modifiers</a></span></dt><dt><span class="sect1"><a href="#Virtual_Modifier_Key_Mapping">Virtual Modifier Key Mapping</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Inactive_Modifier_Sets">Inactive Modifier Sets</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Conventions">Conventions</a></span></dt><dt><span class="sect1"><a href="#Example">Example</a></span></dt></dl></div><p>
The core protocol specifies that certain keysyms, when bound to modifiers,
affect the rules of keycode to keysym interpretation for all keys; for example,
when the <span class="emphasis"><em>
Num_Lock</em></span>
 keysym is bound to some modifier, that modifier is used to select between
shifted and unshifted state for the numeric keypad keys. The core protocol does
not provide a convenient way to determine the mapping of modifier bits (in
particular <span class="emphasis"><em>
Mod1</em></span>
 through <span class="emphasis"><em>
Mod5</em></span>
) to keysyms such as <span class="emphasis"><em>
Num_Lock</em></span>
 and <span class="emphasis"><em>
Mode_switch</em></span>
. Using the core protocol only, a client application must retrieve and search
the modifier map to determine the keycodes bound to each modifier, and then
retrieve and search the keyboard mapping to determine the keysyms bound to the
keycodes. It must repeat this process for all modifiers whenever any part of
the modifier mapping is changed.
</p><p>
Xkb alleviates these problems by defining virtual modifiers. In addition to the
eight core modifiers, referred to as the <span class="emphasis"><em>
real modifiers</em></span>
, Xkb provides a set of sixteen named <span class="emphasis"><em>
virtual modifiers</em></span>
. Each virtual modifier can be bound to any set of the real modifiers
(<span class="emphasis"><em>
Shift</em></span>
, <span class="emphasis"><em>
Lock</em></span>
, <span class="emphasis"><em>
Control,</em></span>
 and <span class="emphasis"><em>
Mod1</em></span>
-<span class="emphasis"><em>
Mod5</em></span>
).
</p><p>
The separation of function from physical modifier bindings makes it easier to
specify more clearly the intent of a binding. X servers do not all assign
modifiers the same way — for example, <span class="emphasis"><em>
Num_Lock</em></span>
 might be bound to <span class="emphasis"><em>
Mod2</em></span>
 for one vendor and to <span class="emphasis"><em>
Mod4</em></span>
 for another. This makes it cumbersome to automatically remap the keyboard to a
desired configuration without some kind of prior knowledge about the keyboard
layout and bindings. With XKB, applications can use virtual modifiers to
specify the desired behavior, without regard for the actual physical bindings
in effect.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Virtual_Modifier_Names_and_Masks"></a>Virtual Modifier Names and Masks</h2></div></div></div><p>
Virtual modifiers are named by converting their string name to an X <span class="emphasis"><em>
Atom</em></span>
 and storing the Atom in the <span class="emphasis"><em>
names.vmods</em></span>
 array in an <span class="emphasis"><em>
XkbDescRec</em></span>
 structure (see section 6.1). The position of a name Atom in the <span class="emphasis"><em>
names.vmods</em></span>
 array defines the bit position used to represent the virtual modifier and also
the index used when accessing virtual modifier information in arrays: the name
in the i-th (0 relative) entry of <span class="emphasis"><em>
names.vmods</em></span>
 is the i-th virtual modifier, represented by the mask (1&lt;&lt;i). Throughout
Xkb, various functions have a parameter that is a mask representing virtual
modifier choices. In each case, the i-th bit (0 relative) of the mask
represents the i-th virtual modifier.
</p><p>
To set the name of a virtual modifier, use <span class="emphasis"><em>
XkbSetNames</em></span>
, using <span class="emphasis"><em>
XkbVirtualModNamesMask</em></span>
 in <span class="emphasis"><em>
which</em></span>
 and the name in the <span class="emphasis"><em>
xkb</em></span>
 argument; to retrieve indicator names, use <span class="emphasis"><em>
XkbGetNames</em></span>
. These functions are discussed in Chapter 18.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Modifier_Definitions"></a>Modifier Definitions</h2></div></div></div><p>
An Xkb<span class="emphasis"><em>
 modifier definition</em></span>
 enumerates a collection of real and virtual modifiers but does not in itself
bind those modifiers to any particular key or to each other. Modifier
definitions are included in a number of structures in the keyboard description
to define the collection of modifiers that affect or are affected by some other
entity. A modifier definition is relevant only in the context of some other
entity such as an indicator map, a control, or a key type. (See sections 8.2.2,
10.8, and 15.2.) 
</p><pre class="programlisting">
typedef struct _XkbMods {
      unsigned char            mask;            /* real_mods | vmods mapped to
real modifiers */
      unsigned char            real_mods;            /* real modifier bits */
      unsigned short             vmods;            /* virtual modifier bits */
} <span class="emphasis"><em>
XkbModsRec</em></span>
,*XkbModsPtr;
</pre><p>
An Xkb modifier definition consists of a set of bit masks corresponding to the
eight real modifiers (<span class="emphasis"><em>
real_mods</em></span>
); a similar set of bitmasks corresponding to the 16 named virtual modifiers
(<span class="emphasis"><em>
vmods</em></span>
); and an effective mask (<span class="emphasis"><em>
mask</em></span>
). The effective mask represents the set of all real modifiers that can
logically be set either by setting any of the real modifiers or by setting any
of the virtual modifiers in the definition. <span class="emphasis"><em>
mask</em></span>
 is derived from the real and virtual modifiers and should never be explicitly
changed — it contains all of the real modifiers specified in the definition
(<span class="emphasis"><em>
real_mods</em></span>
)<span class="emphasis"><em>
 plus</em></span>
 any real modifiers that are bound to the virtual modifiers specified in the
definition (<span class="emphasis"><em>
vmods</em></span>
). The binding of the virtual modifiers to real modifiers is exterior to the
modifier definition. Xkb automatically recomputes the mask field of modifier
definitions as necessary. Whenever you access a modifier definition that has
been retrieved using an Xkb library function, the mask field will be correct
for the keyboard mapping of interest.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Binding_Virtual_Modifiers_to_Real_Modifiers"></a>Binding Virtual Modifiers to Real Modifiers</h2></div></div></div><p>
The binding of virtual modifiers to real modifiers is defined by the <span class="emphasis"><em>
server.vmods</em></span>
 array in an <span class="emphasis"><em>
XkbDescRec</em></span>
 structure. Each entry contains the real modifier bits that are bound to the
virtual modifier corresponding to the entry. The overall relationship of fields
dealing with virtual modifiers in the server keyboard description are shown in
Figure 16.2. 
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Virtual_Modifier_Key_Mapping"></a>Virtual Modifier Key Mapping</h2></div></div></div><p>
Xkb maintains a <span class="emphasis"><em>
virtual modifier mapping</em></span>
, which lists the virtual modifiers associated with, or bound to, each key. The
real modifiers bound to a virtual modifier always include all of the modifiers
bound to any of the keys that specify that virtual modifier in their virtual
modifier mapping. The <span class="emphasis"><em>
server.vmodmap</em></span>
 array indicates which virtual modifiers are bound to each key; each entry is a
bitmask for the virtual modifier bits. The <span class="emphasis"><em>
server.vmodmap</em></span>
 array is indexed by keycode.
</p><p>
The <span class="emphasis"><em>
vmodmap</em></span>
 and <span class="emphasis"><em>
vmods</em></span>
 members of the server map are the "master" virtual modifier definitions. Xkb
automatically propagates any changes to these fields to all other fields that
use virtual modifier mappings (see section 16.4).
</p><p>
For example, if <span class="emphasis"><em>
Mod3</em></span>
 is bound to the <span class="emphasis"><em>
Num_Lock</em></span>
 key by the core protocol modifier mapping, and the <span class="emphasis"><em>
NumLock</em></span>
 virtual modifier is bound to they <span class="emphasis"><em>
Num_Lock</em></span>
 key by the virtual modifier mapping, <span class="emphasis"><em>
Mod3</em></span>
 is added to the set of modifiers associated with <span class="emphasis"><em>
NumLock</em></span>
.
</p><p>
The virtual modifier mapping is normally updated whenever actions are
automatically applied to symbols (see section 16.4 for details), and few
applications should need to change the virtual modifier mapping explicitly.
</p><p>
Use <span class="emphasis"><em>
XkbGetMap </em></span>
(see section 14.2) to get the virtual modifiers from the server or use  
<span class="emphasis"><em>
XkbGetVirtualMods</em></span>
 (see section 16.4.1) to update a local copy of the virtual modifiers bindings  
from the server. To set the binding of a virtual modifier to a real modifier,
use <span class="emphasis"><em>
XkbSetMap</em></span>
 (see<span class="emphasis"><em>
 </em></span>
section 14.3<span class="emphasis"><em> 
).</em></span>
</p><p>
To determine the mapping of virtual modifiers to core X protocol modifiers, use
<span class="emphasis"><em>
XkbVirtualModsToReal</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbVirtualModsToReal</em></span>
(<span class="emphasis"><em>
xkb, virtual_mask, mask_rtrn</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr <span class="emphasis"><em>
            xkb</em></span>
;            /* keyboard description for input device */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
            virtual_mask</em></span>
;            /* virtual modifier mask to translate */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int *             <span class="emphasis"><em>
mask_rtrn</em></span>
;            /* backfilled with real modifiers */
    </td></tr></tbody></table></div><p>
If the keyboard description defined by <span class="emphasis"><em>
xkb</em></span>
 includes bindings for virtual modifiers, <span class="emphasis"><em>
XkbVirtualModsToReal</em></span>
 uses those bindings to determine the set of real modifiers that correspond to
the set of virtual modifiers specified in <span class="emphasis"><em>
virtual_mask</em></span>
. The <span class="emphasis"><em>
virtual_mask</em></span>
 parameter is a mask specifying the virtual modifiers to translate; the i-th
bit (0 relative) of the mask represents the i-th virtual modifier. If <span class="emphasis"><em>
mask_rtrn</em></span>
 is non-<span class="emphasis"><em>
NULL</em></span>
, <span class="emphasis"><em>
XkbVirtualModsToReal</em></span>
 backfills it with the resulting real modifier mask. If the keyboard
description in <span class="emphasis"><em>
xkb</em></span>
 does not include virtual modifier bindings, <span class="emphasis"><em>
XkbVirtualModsToReal</em></span>
 returns <span class="emphasis"><em>
False</em></span>
; otherwise, it returns <span class="emphasis"><em>
True</em></span>
.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>It is possible for a local (client-side) keyboard description (the
<span class="emphasis"><em>
xkb</em></span>
 parameter) to not contain any virtual modifier information (simply because the
client has not requested it) while the server’s corresponding definition may
contain virtual modifier information. </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Inactive_Modifier_Sets"></a>Inactive Modifier Sets</h3></div></div></div><p>
An unbound virtual modifier is one that is not bound to any real modifier
(<span class="emphasis"><em>
server</em></span>
-&gt;<span class="emphasis"><em>
vmods</em></span>
[virtual_modifier_index] is zero).
</p><p>
Some Xkb operations ignore modifier definitions in which the virtual modifiers
are unbound. Consider this example:
</p><div class="literallayout"><p><br />
if (state matches {Shift}) Do OneThing;<br />
if (state matches {Shift+NumLock}) Do Another;<br />
</p></div><p>
If the <span class="emphasis"><em>
NumLock</em></span>
 virtual modifier is not bound to any real modifiers, the effective masks for
these two cases are identical (that is, contain only <span class="emphasis"><em>
Shift</em></span>
). When it is essential to distinguish between <span class="emphasis"><em>
OneThing</em></span>
 and Another, Xkb considers only those modifier definitions for which all
virtual modifiers are bound.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Conventions"></a>Conventions</h2></div></div></div><p>
The Xkb extension does not require any specific virtual modifier names.
However, everyone benefits if the same names are used for common modifiers. The
following names are suggested:
</p><pre class="literallayout">
     <span class="emphasis"><em>
     NumLock
     ScrollLock
     Alt
     Meta
     AltGr
     LevelThree</em></span>
</pre></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Example"></a>Example</h2></div></div></div><p>
If the second (0-relative) entry in <span class="emphasis"><em>
names.vmods</em></span>
 contains the Atom for "NumLock", then 0x4 (1&lt;&lt;2) is the virtual modifier
bit for the <span class="emphasis"><em>
NumLock</em></span>
 virtual modifier. If <span class="emphasis"><em>
server.vmods</em></span>
[2] contains <span class="emphasis"><em>
Mod3Mask</em></span>
, then the <span class="emphasis"><em>
NumLock</em></span>
 virtual modifier is bound to the <span class="emphasis"><em>
Mod3</em></span>
 real modifier.
</p><p>
A virtual modifier definition for this example would have:
</p><pre class="literallayout">
     real_mods = 0
     vmods = 0x4 (NumLock named virtual modifier)
     mask = 0x20 (Mod3Mask)
</pre><p>
Continuing the example, if the keyboard has a <span class="emphasis"><em>
Num_Lock</em></span>
 keysym bound to the key with keycode 14, and the <span class="emphasis"><em>
NumLock</em></span>
 virtual modifier is bound to this key, <span class="emphasis"><em>
server.vmodmap</em></span>
[14] contains 0x4.
</p><p>
Finally, if the keyboard also used the real <span class="emphasis"><em>
Mod1</em></span>
 modifier for numeric lock operations, the modifier definition below would
represent the situation where either the key bound to <span class="emphasis"><em>
Mod1</em></span>
 or the <span class="emphasis"><em>
NumLock</em></span>
 virtual modifier could be used for this purpose:
</p><pre class="literallayout">
     real_mods = 0x8 (Mod1Mask)
     vmods = 0x4 (NumLock named virtual modifier)
     mask = 0x28 (Mod1Mask | Mod3Mask)
</pre></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Indicators"></a>Chapter 8. Indicators</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Indicator_Names">Indicator Names</a></span></dt><dt><span class="sect1"><a href="#Indicator_Data_Structures">Indicator Data Structures</a></span></dt><dd><dl><dt><span class="sect2"><a href="#XkbIndicatorRec">XkbIndicatorRec</a></span></dt><dt><span class="sect2"><a href="#XkbIndicatorMapRec">XkbIndicatorMapRec</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Getting_Information_About_Indicators">Getting Information About Indicators</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Getting_Indicator_State">Getting Indicator State</a></span></dt><dt><span class="sect2"><a href="#Getting_Indicator_Information_by_Index">Getting Indicator Information by Index</a></span></dt><dt><span class="sect2"><a href="#Getting_Indicator_Information_by_Name">Getting Indicator Information by Name</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Changing_Indicator_Maps_and_State">Changing Indicator Maps and State</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Effects_of_Explicit_Changes_on_Indicators">Effects of Explicit Changes on Indicators</a></span></dt><dt><span class="sect2"><a href="#Changing_Indicator_Maps_by_Index">Changing Indicator Maps by Index</a></span></dt><dt><span class="sect2"><a href="#Changing_Indicator_Maps_by_Name">Changing Indicator Maps by Name</a></span></dt><dt><span class="sect2"><a href="#The_XkbIndicatorChangesRec_Structure">The XkbIndicatorChangesRec Structure</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Tracking_Changes_to_Indicator_State_or_Map">Tracking Changes to Indicator State or Map</a></span></dt><dt><span class="sect1"><a href="#Allocating_and_Freeing_Indicator_Maps">Allocating and Freeing Indicator Maps</a></span></dt></dl></div><p>
Although the core X implementation supports up to 32 LEDs on an input device,
it does not provide any linkage between the state of the LEDs and the logical
state of the input device. For example, most keyboards have a <span class="emphasis"><em>
CapsLock</em></span>
 LED, but X does not provide a mechanism to make the LED automatically follow
the logical state of the <span class="emphasis"><em>
CapsLock</em></span>
 key.
</p><p>
Furthermore, the core X implementation does not provide clients with the
ability to determine what bits in the <span class="emphasis"><em>
led_mask</em></span>
 field of the <span class="emphasis"><em>
XKeyboardState</em></span>
 map to the particular LEDs on the keyboard. For example, X does not provide a
method for a client to determine what bit to set in the <span class="emphasis"><em>
led_mask</em></span>
 field to turn on the <span class="emphasis"><em>
Scroll Lock </em></span>
LED or whether the keyboard even has a <span class="emphasis"><em>
Scroll Lock</em></span>
 LED.
</p><p>
Xkb provides indicator names and programmable indicators to help solve these
problems. Using Xkb, clients can determine the names of the various indicators,
determine and control the way that the individual indicators should be updated
to reflect keyboard changes, and determine which of the 32 keyboard indicators
reported by the protocol are actually present on the keyboard. Clients may also
request immediate notification of changes to the state of any subset of the
keyboard indicators, which makes it straightforward to provide an on-screen
"virtual" LED panel. This chapter describes Xkb indicators and the functions
used for manipulating them.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Indicator_Names"></a>Indicator Names</h2></div></div></div><p>
Xkb provides the capability of symbolically naming indicators. Xkb itself
doesn’t use these symbolic names for anything; they are there only to help
make the keyboard description comprehensible to humans. To set the names of
specific indicators, use <span class="emphasis"><em>
XkbSetNames</em></span>
 as discussed in Chapter 18. Then set the map using <span class="emphasis"><em> 
XkbSetMap</em></span>
 (see section 14.3) or <span class="emphasis"><em> 
XkbSetNamedIndicator</em></span>
 (below). To retrieve indicator names, use <span class="emphasis"><em>
XkbGetNames</em></span>
 (Chapter 18). 
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Indicator_Data_Structures"></a>Indicator Data Structures</h2></div></div></div><p>
Use the indicator description record, <span class="emphasis"><em>
XkbIndicatorRec</em></span>
, and its indicator map, <span class="emphasis"><em>
XkbIndicatorMapRec</em></span>
, to inquire about and control most indicator properties and behaviors.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="XkbIndicatorRec"></a>XkbIndicatorRec</h3></div></div></div><p>
The description for all the Xkb indicators is held in the <span class="emphasis"><em>
indicators</em></span>
 field of the complete keyboard description (see Chapter 6), which is defined  
as follows:
</p><pre class="programlisting">
#define      XkbNumIndicators      32
</pre><pre class="programlisting">
typedef struct {
      unsigned long                   phys_indicators;        /* LEDs existence */
      XkbIndicatorMapRec              maps[XkbNumIndicators]; /* indicator maps */
} <span class="emphasis"><em>XkbIndicatorRec</em></span>,*XkbIndicatorPtr;
</pre><p>
This structure contains the <span class="emphasis"><em>
phys_indicators</em></span>
 field, which relates some information about the correspondence between
indicators and physical LEDs on the keyboard, and an array of indicator
<span class="emphasis"><em>
maps</em></span>
, one map per indicator.
</p><p>
The <span class="emphasis"><em>
phys_indicators</em></span>
 field indicates which indicators are bound to physical LEDs on the keyboard;
if a bit is set in <span class="emphasis"><em>
phys_indicators</em></span>
, then the associated indicator has a physical LED associated with it. This
field is necessary because some indicators may not have corresponding physical
LEDs on the keyboard. For example, most keyboards have an LED for indicating
the state of <span class="emphasis"><em>
CapsLock</em></span>
, but most keyboards do not have an LED that indicates the current group.
Because <span class="emphasis"><em>
phys_indicators</em></span>
 describes a physical characteristic of the keyboard, you cannot directly
change it under program control. However, if a client program loads a
completely new keyboard description via <span class="emphasis"><em>
XkbGetKeyboardByName</em></span>
, or if a new keyboard is attached and the X implementation notices, <span class="emphasis"><em>
phys_indicators</em></span>
 changes if the indicators for the new keyboard are different.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="XkbIndicatorMapRec"></a>XkbIndicatorMapRec</h3></div></div></div><p>
Each indicator has its own set of attributes that specify whether clients can
explicitly set its state and whether it tracks the keyboard state. The
attributes of each indicator are held in the <span class="emphasis"><em>
maps</em></span>
 array, which is an array of <span class="emphasis"><em>
XkbIndicatorRec</em></span>
 structures:
</p><pre class="programlisting">
typedef struct {
      unsigned char    flags;         /* how the indicator can be changed */
      unsigned char    which_groups;  /* match criteria for groups */
      unsigned char    groups;        /* which keyboard groups the indicator watches */
      unsigned char    which_mods;    /* match criteria for modifiers */
      XkbModsRec       mods;          /* which modifiers the indicator watches */
      unsigned int     ctrls;         /* which controls the indicator watches */
} <span class="emphasis"><em>XkbIndicatorMapRec</em></span>, *XkbIndicatorMapPtr;
</pre><p>
This indicator map specifies for each indicator:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The conditions under which the keyboard modifier state affects the indicator
  </p></li><li class="listitem"><p>
The conditions under which the keyboard group state affects the indicator
  </p></li><li class="listitem"><p>
The conditions under which the state of the boolean controls affects the
indicator
  </p></li><li class="listitem"><p>
The effect (if any) of attempts to explicitly change the state of the indicator
using the functions <span class="emphasis"><em>
XkbSetControls</em></span>
 or <span class="emphasis"><em>
XChangeKeyboardControl</em></span>

  </p></li></ul></div><p>
For more information on the effects of explicit changes to indicators and the
relationship to the indicator map, see section 8.4.1. 
</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="XkbIndicatorMapRec_flags_field"></a>XkbIndicatorMapRec flags field</h4></div></div></div><p>
The <span class="emphasis"><em>
flags</em></span>
 field specifies the conditions under which the indicator can be changed and
the effects of changing the indicator. The valid values for <span class="emphasis"><em>
flags</em></span>
 and their effects are shown in Table 8.1. 
</p><div class="table"><a id="idp64731580"></a><p class="title"><strong>Table 8.1. XkbIndicatorMapRec flags Field</strong></p><div class="table-contents"><table summary="XkbIndicatorMapRec flags Field" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">Value</th><th align="left"> </th><th align="left">Effect</th></tr></thead><tbody><tr><td align="left">XkbIM_NoExplicit</td><td align="left">(1L&lt;&lt;7)</td><td align="left">Client applications cannot change the state of the indicator.</td></tr><tr><td align="left">XkbIM_NoAutomatic</td><td align="left">(1L&lt;&lt;6)</td><td align="left">Xkb does not automatically change the value of the indicator based
upon a change in the keyboard state, regardless of the values for the other
fields of the indicator map.</td></tr><tr><td align="left">XkbIM_LEDDrivesKB</td><td align="left">(1L&lt;&lt;5)</td><td align="left">A client application changing the state of the indicator causes the
state of the keyboard to change.</td></tr></tbody></table></div></div><br class="table-break" /><p>
Note that if <span class="emphasis"><em>
XkbIM_NoAutomatic</em></span>
 is not set, by default the indicator follows the keyboard state.
</p><p>
If <span class="emphasis"><em>
XkbIM_LEDDrivesKB</em></span>
 is set and <span class="emphasis"><em>
XkbIM_NoExplicit</em></span>
 is not, and if you call a function which updates the server’s image of the
indicator map (such as <span class="emphasis"><em>
XkbSetIndicatorMap</em></span>
 or <span class="emphasis"><em>
XkbSetNamedIndicator</em></span>
), Xkb changes the keyboard state and controls to reflect the other fields of
the indicator map, as described in the remainder of this section. If you
attempt to explicitly change the value of an indicator for which <span class="emphasis"><em>
XkbIM_LEDDrivesKB</em></span>
 is absent or for which <span class="emphasis"><em>
XkbIM_NoExplicit</em></span>
 is present, keyboard state or controls are unaffected.
</p><p>
For example, a keyboard designer may want to make the <span class="emphasis"><em>
CapsLock</em></span>
 LED controllable only by the server, but allow the <span class="emphasis"><em>
Scroll Lock</em></span>
 LED to be controlled by client applications. To do so, the keyboard designer
could set the <span class="emphasis"><em>
XkbIM_NoExplicit</em></span>
 flag for the <span class="emphasis"><em>
CapsLock</em></span>
<span class="emphasis"><em>
 </em></span>
LED, but not set it for the <span class="emphasis"><em>
Scroll Lock</em></span>
 LED. Or the keyboard designer may wish to allow the <span class="emphasis"><em>
CapsLock</em></span>
 LED to be controlled by both the server and client applications and also have
the server to automatically change the <span class="emphasis"><em>
CapsLock</em></span>
<span class="emphasis"><em>
 </em></span>
modifier state whenever a client application changes the <span class="emphasis"><em>
CapsLock</em></span>
 LED. To do so, the keyboard designer would not set the <span class="emphasis"><em>
XkbIM_NoExplicit</em></span>
 flag, but would instead set the <span class="emphasis"><em>
XkbIM_LEDDrivesKB</em></span>
 flag.
</p><p>
The remaining fields in the indicator map specify the conditions under which
Xkb automatically turns an indicator on or off (only if <span class="emphasis"><em>
XkbIM_NoAutomatic</em></span>
 is not set). If these conditions match the keyboard state, Xkb turns the
indicator on. If the conditions do not match, Xkb turns the indicator off.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="XkbIndicatorMapRec_which_groups_and_groups_fields"></a>XkbIndicatorMapRec which_groups and groups fields</h4></div></div></div><p>
The <span class="emphasis"><em>
which_groups</em></span>
 and the <span class="emphasis"><em>
groups</em></span>
 fields of an indicator map determine how the keyboard group state affects the
corresponding indicator. The <span class="emphasis"><em>
which_groups</em></span>
 field controls the interpretation of <span class="emphasis"><em>
groups</em></span>
 and may contain any one of the following values:
</p><pre class="programlisting">
#define XkbIM_UseNone             0
#define XkbIM_UseBase             (1L &lt;&lt; 0)
#define XkbIM_UseLatched          (1L &lt;&lt; 1)
#define XkbIM_UseLocked           (1L &lt;&lt; 2)
#define XkbIM_UseEffective        (1L &lt;&lt; 3)
#define XkbIM_UseAnyGroup         XkbIM_UseLatched | XkbIM_UseLocked |
                                  XkbIM_UseEffective
</pre><p>
The <span class="emphasis"><em>
groups </em></span>
field specifies what keyboard groups an indicator watches and is the bitwise
inclusive OR of the following valid values:
</p><pre class="programlisting">
#define XkbGroup1Mask            (1&lt;&lt;0)
#define XkbGroup2Mask            (1&lt;&lt;1)
#define XkbGroup3Mask            (1&lt;&lt;2)
#define XkbGroup4Mask            (1&lt;&lt;3)
#define XkbAnyGroupMask          (1&lt;&lt;7)
#define XkbAllGroupsMask         (0xf)
</pre><p>
If <span class="emphasis"><em>
XkbIM_NoAutomatic</em></span>
 is not set (the keyboard drives the indicator), the effect of <span class="emphasis"><em>
which_groups</em></span>
 and <span class="emphasis"><em>
groups</em></span>
 is shown in Table 8.2. 
</p><div class="table"><a id="idp64750140"></a><p class="title"><strong>Table 8.2. XkbIndicatorMapRec which_groups and groups, Keyboard Drives
Indicator</strong></p><div class="table-contents"><table summary="XkbIndicatorMapRec which_groups and groups, Keyboard Drives&#10;Indicator" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">which_groups</th><th align="left">Effect</th></tr></thead><tbody><tr><td align="left">XkbIM_UseNone</td><td align="left">
The <span class="emphasis"><em>
groups</em></span>
 field and the current keyboard group state are ignored.
    </td></tr><tr><td align="left">XkbIM_UseBase</td><td align="left">
If <span class="emphasis"><em>
groups</em></span>
 is nonzero, the indicator is lit whenever the base keyboard group is nonzero.
If <span class="emphasis"><em>
groups</em></span>
 is zero, the indicator is lit whenever the base keyboard group is zero.
    </td></tr><tr><td align="left">XkbIM_UseLatched</td><td align="left">
If <span class="emphasis"><em>
groups</em></span>
 is nonzero, the indicator is lit whenever the latched keyboard group is
nonzero. If <span class="emphasis"><em>
groups</em></span>
 is zero, the indicator is lit whenever the latched keyboard group is zero.
    </td></tr><tr><td align="left">XkbIM_UseLocked</td><td align="left">
The <span class="emphasis"><em>
groups</em></span>
 field is interpreted as a mask. The indicator is lit when the current locked
keyboard group matches one of the bits that are set in <span class="emphasis"><em>
groups</em></span>.
    </td></tr><tr><td align="left">XkbIM_UseEffective</td><td align="left">
The <span class="emphasis"><em>
groups</em></span>
 field is interpreted as a mask. The indicator is lit when the current
effective keyboard group matches one of the bits that are set in <span class="emphasis"><em>
groups</em></span>
.
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
The effect of <span class="emphasis"><em>
which_groups</em></span>
 and <span class="emphasis"><em>
groups</em></span>
 when you change an indicator for which <span class="emphasis"><em>
XkbIM_LEDDrivesKB</em></span>
 is set (the indicator drives the keyboard) is shown in Table 8.3. The "New
State" column refers to the new state to which you set the indicator.
</p><div class="table"><a id="idp64943092"></a><p class="title"><strong>Table 8.3. XkbIndicatorMapRec which_groups and groups, Indicator Drives
Keyboard</strong></p><div class="table-contents"><table summary="XkbIndicatorMapRec which_groups and groups, Indicator Drives&#10;Keyboard" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">which_groups</th><th align="left">New State</th><th align="left">Effect on Keyboard Group State</th></tr></thead><tbody><tr><td align="left">XkbIM_UseNone </td><td align="left">On or Off</td><td align="left">No effect</td></tr><tr><td align="left">XkbIM_UseBase</td><td align="left">On or Off</td><td align="left">No effect</td></tr><tr><td align="left">XkbIM_UseLatched</td><td align="left">On</td><td align="left">
The <span class="emphasis"><em>
groups</em></span>
 field is treated as a group mask. The keyboard group latch is changed to the
lowest numbered group specified in <span class="emphasis"><em>
groups</em></span>
; if <span class="emphasis"><em>
groups</em></span>
 is empty, the keyboard group latch is changed to zero.
    </td></tr><tr><td align="left">XkbIM_UseLatched</td><td align="left">Off</td><td align="left">
The <span class="emphasis"><em>
groups</em></span>
 field is treated as a group mask. If the indicator is explicitly extinguished,
keyboard group latch is changed to the lowest numbered group not specified in
<span class="emphasis"><em>
groups</em></span>
; if <span class="emphasis"><em>
groups</em></span>
 is zero, the keyboard group latch is set to the index of the highest legal
keyboard group.
    </td></tr><tr><td align="left">XkbIM_UseLocked or XkbIM_UseEffective</td><td align="left">On</td><td align="left">
If the <span class="emphasis"><em>
groups</em></span>
 mask is empty, group is not changed; otherwise, the locked keyboard group is
changed to the lowest numbered group specified in <span class="emphasis"><em>
groups</em></span>.
    </td></tr><tr><td align="left">XkbIM_UseLocked or XkbIM_UseEffective</td><td align="left">Off</td><td align="left">
Locked keyboard group is changed to the lowest numbered group that is not
specified in the <span class="emphasis"><em>
groups</em></span>
 mask, or to <span class="emphasis"><em>
Group1</em></span>
 if the <span class="emphasis"><em>
groups</em></span>
 mask contains all keyboard groups.
    </td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="XkbIndicatorMapRec_which_mods_and_mods_fields"></a>XkbIndicatorMapRec which_mods and mods fields</h4></div></div></div><p>
The <span class="emphasis"><em>
mods </em></span>
field specifies what modifiers an indicator watches. The <span class="emphasis"><em>
mods</em></span>
 field is an Xkb modifier definition, <span class="emphasis"><em>
XkbModsRec</em></span>
, as described in section 7.2, which can specify both real and virtual  
modifiers. The <span class="emphasis"><em>
mods</em></span>
 field takes effect even if some or all of the virtual indicators specified in
<span class="emphasis"><em>
mods</em></span>
 are unbound. To specify the mods field, in general, assign the modifiers of
interest to <span class="emphasis"><em>
mods.real_mods</em></span>
 and the virtual modifiers of interest to <span class="emphasis"><em>
mods.vmods</em></span>
. You can disregard the <span class="emphasis"><em>
mods.mask</em></span>
 field unless your application needs to interpret the indicator map directly
(that is, to simulate automatic indicator behavior on its own). Relatively few
applications need to do so, but if you find it necessary, you can either read
the indicator map back from the server after you update it (the server
automatically updates the mask field whenever any of the real or virtual
modifiers are changed in the modifier definition) or you can use <span class="emphasis"><em>
XkbVirtualModsToReal</em></span>
 to determine the proper contents for the mask field, assuming that the
<span class="emphasis"><em>
XkbDescRec</em></span>
 contains the virtual modifier definitions.
</p><p>
<span class="emphasis"><em>
which_mods</em></span>
 specifies what criteria Xkb uses to determine a match with the corresponding
<span class="emphasis"><em>
mods</em></span>
 field by specifying one or more components of the Xkb keyboard state. If
<span class="emphasis"><em>
XkbIM_NoAutomatic</em></span>
 is not set (the keyboard drives the indicator), the indicator is lit whenever
any of the modifiers specified in the <span class="emphasis"><em>
mask</em></span>
 field of the<span class="emphasis"><em>
 mods</em></span>
 modifier definition are also set in any of the current keyboard state
components specified by <span class="emphasis"><em>
which_mods</em></span>
. Remember that the <span class="emphasis"><em>
mask</em></span>
 field is comprised of all of the real modifiers specified in the definition
plus any real modifiers that are bound to the virtual modifiers specified in
the definition. (See Chapter 5 for more information on the keyboard state and  
Chapter 7 for more information on virtual modifiers.) Use a bitwise inclusive
OR of the following values to compose a value for <span class="emphasis"><em>
which_mods</em></span>:
</p><pre class="programlisting">
#define XkbIM_UseNone             0
#define XkbIM_UseBase             (1L &lt;&lt; 0)
#define XkbIM_UseLatched          (1L &lt;&lt; 1)
#define XkbIM_UseLocked           (1L &lt;&lt; 2)
#define XkbIM_UseEffective        (1L &lt;&lt; 3)
#define XkbIM_UseCompat           (1L &lt;&lt; 4)
#define XkbIM_UseAnyMods          XkbIM_UseBase | XkbIM_UseLatched |
                                  XkbIM_UseLocked | XkbIM_UseEffective |
                                  XkbIM_UseCompat
</pre><p>
If <span class="emphasis"><em>
XkbIM_NoAutomatic</em></span>
 is not set (the keyboard drives the indicator), the effect of <span class="emphasis"><em>
which_mods</em></span>
 and <span class="emphasis"><em>
mods</em></span>
 is shown in Table 8.4 
</p><div class="table"><a id="idp64962644"></a><p class="title"><strong>Table 8.4. XkbIndicatorMapRec which_mods and mods, Keyboard Drives Indicator</strong></p><div class="table-contents"><table summary="XkbIndicatorMapRec which_mods and mods, Keyboard Drives Indicator" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">which_mods</th><th align="left">Effect on Keyboard Modifiers</th></tr></thead><tbody><tr><td align="left">XkbIM_UseNone</td><td align="left">The mods field and the current keyboard modifier state are
ignored.</td></tr><tr><td align="left">XkbIM_UseBase</td><td align="left">
The indicator is lit when any of the modifiers specified in the <span class="emphasis"><em>
mask</em></span>
 field of <span class="emphasis"><em>
mods</em></span>
 are on in the keyboard base state. If both <span class="emphasis"><em>
mods.real_mods</em></span>
 and <span class="emphasis"><em>
mods.vmods</em></span>
 are zero, the indicator is lit when the base keyboard state contains no
modifiers.
    </td></tr><tr><td align="left">XkbIM_UseLatched</td><td align="left">
The indicator is lit when any of the modifiers specified in the <span class="emphasis"><em>
mask</em></span>
 field of <span class="emphasis"><em>
mods</em></span>
 are latched. If both <span class="emphasis"><em>
mods.real_mods</em></span>
 and <span class="emphasis"><em>
mods.vmods</em></span>
 are zero, the indicator is lit when none of the modifier keys are latched.
    </td></tr><tr><td align="left">XkbIM_UseLocked</td><td align="left">
The indicator is lit when any of the modifiers specified in the <span class="emphasis"><em>
mask</em></span>
 field of <span class="emphasis"><em>
mods</em></span>
 are locked. If both <span class="emphasis"><em>
mods.real_mods</em></span>
 and <span class="emphasis"><em>
mods.vmods</em></span>
 are zero, the indicator is lit when none of the modifier keys are locked.
    </td></tr><tr><td align="left">XkbIM_UseEffective</td><td align="left">
The indicator is lit when any of the modifiers specified in the <span class="emphasis"><em>
mask</em></span>
 field of <span class="emphasis"><em>
mods</em></span>
 are in the effective keyboard state. If both <span class="emphasis"><em>
mods.real_mods</em></span>
 and <span class="emphasis"><em>
mods.vmods</em></span>
 are zero, the indicator is lit when the effective keyboard state contains no
modifiers.
    </td></tr><tr><td align="left">XkbIM_UseCompat</td><td align="left">
The indicator is lit when any of the modifiers specified in the <span class="emphasis"><em>
mask</em></span>
 field of <span class="emphasis"><em>
mods</em></span>
 are in the keyboard compatibility state. If both <span class="emphasis"><em>
mods.real_mods</em></span>
 and <span class="emphasis"><em>
mods.vmods</em></span>
 are zero, the indicator is lit when the keyboard compatibility state contains
no modifiers.
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
The effect on the keyboard modifiers of <span class="emphasis"><em>
which_mods</em></span>
 and <span class="emphasis"><em>
mods</em></span>
 when you change an indicator for which <span class="emphasis"><em>
XkbIM_LEDDrivesKB</em></span>
 is set (the indicator drives the keyboard) is shown in Table 8.5. The "New
State" column refers to the new state to which you set the indicator.
</p><div class="table"><a id="idp64975396"></a><p class="title"><strong>Table 8.5. XkbIndicatorMapRec which_mods and mods, Indicator Drives Keyboard</strong></p><div class="table-contents"><table summary="XkbIndicatorMapRec which_mods and mods, Indicator Drives Keyboard" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">which_mods</th><th align="left">New State</th><th align="left">Effect on Keyboard Modifiers</th></tr></thead><tbody><tr><td align="left">XkbIM_UseNone or XkbIM_UseBase</td><td align="left">On or Off</td><td align="left">No Effect</td></tr><tr><td align="left">XkbIM_UseLatched</td><td align="left">On</td><td align="left">
Any modifiers specified in the <span class="emphasis"><em>
mask</em></span>
 field of <span class="emphasis"><em>
mods</em></span>
 are added to the latched modifiers.
    </td></tr><tr><td align="left">XkbIM_UseLatched</td><td align="left">Off</td><td align="left">
Any modifiers specified in the <span class="emphasis"><em>
mask</em></span>
 field of <span class="emphasis"><em>
mods</em></span>
 are removed from the latched modifiers.
    </td></tr><tr><td align="left">XkbIM_UseLocked, XkbIM_UseCompat, or XkbIM_UseEffective</td><td align="left">On</td><td align="left">
Any modifiers specified in the <span class="emphasis"><em>
mask</em></span>
 field of <span class="emphasis"><em>
mods</em></span>
 are added to the locked modifiers.
    </td></tr><tr><td align="left">XkbIM_UseLocked</td><td align="left">Off</td><td align="left">
Any modifiers specified in the <span class="emphasis"><em>
mask</em></span>
 field of <span class="emphasis"><em>
mods</em></span>
 are removed from the locked modifiers.
    </td></tr><tr><td align="left">XkbIM_UseCompat or XkbIM_UseEffective</td><td align="left">Off</td><td align="left">
Any modifiers specified in the <span class="emphasis"><em>
mask</em></span>
 field of <span class="emphasis"><em>
mods</em></span>
 are removed from both the locked and latched modifiers.
    </td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="XkbIndicatorMapRec_ctrls_field"></a>XkbIndicatorMapRec ctrls field</h4></div></div></div><p>
The <span class="emphasis"><em>
ctrls</em></span>
 field specifies what controls (see Chapter 10) the indicator watches and is
composed using the bitwise inclusive OR of the following values:
</p><pre class="programlisting">
#define XkbRepeatKeysMask           (1L &lt;&lt; 0)
#define XkbSlowKeysMask             (1L &lt;&lt; 1)
#define XkbBounceKeysMask           (1L &lt;&lt; 2)
#define XkbStickyKeysMask           (1L &lt;&lt; 3)
#define XkbMouseKeysMask            (1L &lt;&lt; 4)
#define XkbMouseKeysAccelMask       (1L &lt;&lt; 5)
#define XkbAccessXKeysMask          (1L &lt;&lt; 6)
#define XkbAccessXTimeoutMask       (1L &lt;&lt; 7)
#define XkbAccessXFeedbackMask      (1L &lt;&lt; 8)
#define XkbAudibleBellMask          (1L &lt;&lt; 9)
#define XkbOverlay1Mask             (1L &lt;&lt; 10)
#define XkbOverlay2Mask             (1L &lt;&lt; 11)
#define XkbAllBooleanCtrlsMask      (0x00001FFF)
</pre><p>
Xkb lights the indicator whenever any of the boolean controls specified in
<span class="emphasis"><em>
ctrls</em></span>
 is enabled.
</p></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Getting_Information_About_Indicators"></a>Getting Information About Indicators</h2></div></div></div><p>
Xkb allows applications to obtain information about indicators using two
different methods. The first method, which is similar to the core X
implementation, uses a mask to specify the indicators. The second method, which
is more suitable for applications concerned with interoperability, uses
indicator names. The correspondence between the indicator name and the bit
position in masks is as follows: one of the parameters returned from <span class="emphasis"><em>
XkbGetNamedIndicators</em></span>
 is an index that is the bit position to use in any function call that requires
a mask of indicator bits, as well as the indicator’s index into the <span class="emphasis"><em>
XkbIndicatorRec</em></span>
 array of indicator maps.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Getting_Indicator_State"></a>Getting Indicator State</h3></div></div></div><p>
Because the state of the indicators is relatively volatile, the keyboard
description does not hold the current state of the indicators. To obtain the
current state of the keyboard indicators, use <span class="emphasis"><em>
XkbGetIndicatorState</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetIndicatorState</em></span>
(<span class="emphasis"><em>
display</em></span>
, <span class="emphasis"><em>
device_spec</em></span>
, <span class="emphasis"><em>
state_return</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
display</em></span>
;            /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
device_spec</em></span>
;            /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int *      <span class="emphasis"><em>
state_return</em></span>
;            /* backfilled with a mask of the indicator state */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetIndicatorState</em></span>
 queries the <span class="emphasis"><em>
display</em></span>
 for the state of the indicators on the device specified by the <span class="emphasis"><em>
device_spec</em></span>
. For each indicator that is "turned on" on the device, the associated bit is
set in <span class="emphasis"><em>
state_return</em></span>
. If a compatible version of the Xkb extension is not available in the server,
<span class="emphasis"><em>
XkbGetIndicatorState</em></span>
 returns a <span class="emphasis"><em>
BadMatch</em></span>
 error. Otherwise, it sends the request to the X server, places the state of
the indicators into <span class="emphasis"><em>
state_return,</em></span>
 and returns <span class="emphasis"><em>
Success</em></span>
. Thus the value reported by <span class="emphasis"><em>
XkbGetIndicatorState</em></span>
 is identical to the value reported by the core protocol.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Getting_Indicator_Information_by_Index"></a>Getting Indicator Information by Index</h3></div></div></div><p>
To get the map for one or more indicators, using a mask to specify the
indicators, use <span class="emphasis"><em>
XkbGetIndicatorMap</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetIndicatorMap</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 which</em></span>
,<span class="emphasis"><em>
 desc</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
dpy</em></span>
;      /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
which</em></span>
;      /* mask of indicators for which maps should be returned */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr      <span class="emphasis"><em>
desc</em></span>
;      /* keyboard description to be updated */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetIndicatorMap</em></span>
 obtains the maps from the server for only those indicators specified by the
<span class="emphasis"><em>
which</em></span>
 mask and copies the values into the keyboard description specified by
<span class="emphasis"><em>
desc</em></span>
. If the <span class="emphasis"><em>
indicators</em></span>
 field of the <span class="emphasis"><em>
desc</em></span>
 parameter is <span class="emphasis"><em>
NULL</em></span>
, <span class="emphasis"><em>
XkbGetIndicatorMap</em></span>
 allocates and initializes it.
</p><p>
<span class="emphasis"><em>
XkbGetIndicatorMap</em></span>
 can generate <span class="emphasis"><em>
BadAlloc</em></span>
, <span class="emphasis"><em>
BadLength</em></span>
, <span class="emphasis"><em>
BadMatch</em></span>
, and <span class="emphasis"><em>
BadImplementation</em></span>
 errors.
</p><p>
To free the indicator maps, use <span class="emphasis"><em>
XkbFreeIndicatorMaps</em></span>
 (see section 8.6).
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Getting_Indicator_Information_by_Name"></a>Getting Indicator Information by Name</h3></div></div></div><p>
Xkb also allows applications to refer to indicators by name. Use <span class="emphasis"><em>
XkbGetNames</em></span>
 to get the indicator names (see Chapter 18). Using names eliminates the need
for hard-coding bitmask values for particular keyboards. For example, instead
of using vendor-specific constants such as <span class="emphasis"><em>
WSKBLed_ScrollLock</em></span>
 mask on Digital workstations or <span class="emphasis"><em>
XLED_SCROLL_LOCK</em></span>
 on Sun workstations, you can instead use <span class="emphasis"><em>
XkbGetNamedIndicator</em></span>
 to look up information on the indicator named "Scroll Lock."
</p><p>
Use <span class="emphasis"><em>
XkbGetNamedIndicator</em></span>
 to look up the indicator map and other information for an indicator by name.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbGetNamedIndicator</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 dev_spec</em></span>
,<span class="emphasis"><em>
 name</em></span>
,<span class="emphasis"><em>
 ndx_rtrn</em></span>
,<span class="emphasis"><em>
 state_rtrn</em></span>
,<span class="emphasis"><em>
 map_rtrn</em></span>
, <span class="emphasis"><em>
real_rtrn</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            <span class="emphasis"><em>
dpy</em></span>
;            /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
      device_spec</em></span>
;            /* keyboard device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
Atom      <span class="emphasis"><em>
      name</em></span>
;            /* name of the indicator to be retrieved */
    </td></tr><tr><td class="functionargdecl" align="left">
int *            <span class="emphasis"><em>
ndx_rtrn</em></span>
;            /* backfilled with the index of the retrieved indicator */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool *            <span class="emphasis"><em>
state_rtrn</em></span>
;            /* backfilled with the current state of the retrieved indicator */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbIndicatorMapPtr      <span class="emphasis"><em>
      map_rtrn</em></span>
;            /* backfilled with the mapping for the retrieved indicator */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool *            <span class="emphasis"><em>
real_rtrn</em></span>
;            /* backfilled with <span class="emphasis"><em>
True</em></span>
 if the named indicator is real (physical) */
    </td></tr></tbody></table></div><p>
If the device specified by <span class="emphasis"><em>
device_spec</em></span>
 has an indicator named <span class="emphasis"><em>
name</em></span>
,<span class="emphasis"><em>
 XkbGetNamedIndicator</em></span>
 returns <span class="emphasis"><em>
True</em></span>
 and populates the rest of the parameters with information about the indicator.
Otherwise, <span class="emphasis"><em>
XkbGetNamedIndicator</em></span>
 returns <span class="emphasis"><em>
False</em></span>
.
</p><p>
The <span class="emphasis"><em>
ndx_rtrn</em></span>
 field returns the zero-based index of the named indicator. This index is the
bit position to use in any function call that requires a mask of indicator
bits, as well as the indicator’s index into the <span class="emphasis"><em>
XkbIndicatorRec</em></span>
 array of indicator maps. <span class="emphasis"><em>
state_rtrn</em></span>
 returns the current state of the named indicator (<span class="emphasis"><em>
True</em></span>
 = on, <span class="emphasis"><em>
False</em></span>
 = off). <span class="emphasis"><em>
map_rtrn</em></span>
 returns the indicator map for the named indicator. In addition, if the
indicator is mapped to a physical LED, the <span class="emphasis"><em>
real_rtrn</em></span>
 parameter is set to <span class="emphasis"><em>
True</em></span>
.
</p><p>
Each of the "<span class="emphasis"><em>
_rtrn</em></span>
" arguments is optional; you can pass <span class="emphasis"><em>
NULL</em></span>
 for any unneeded "<span class="emphasis"><em>
_rtrn</em></span>
" arguments.
</p><p>
<span class="emphasis"><em>
XkbGetNamedIndicator</em></span>
 can generate <span class="emphasis"><em>
BadAtom</em></span>
 and <span class="emphasis"><em>
BadImplementation</em></span>
 errors.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Changing_Indicator_Maps_and_State"></a>Changing Indicator Maps and State</h2></div></div></div><p>
Just as you can get the indicator map using a mask or using an indicator name,
so you can change it using a mask or a name.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>You cannot change the <span class="emphasis"><em>
phys_indicators</em></span>
 field of the indicators structure. The only way to change the <span class="emphasis"><em>
phys_indicators</em></span>
 field is to change the keyboard map.</p></div><p>
There are two ways to make changes to indicator maps and state: either change a
local copy of the indicator maps and use <span class="emphasis"><em>
XkbSetIndicatorMap</em></span>
 or <span class="emphasis"><em>
XkbSetNamedIndicator</em></span>
, or, to reduce network traffic, use an<span class="emphasis"><em>
 XkbIndicatorChangesRec</em></span>
 structure and use <span class="emphasis"><em>
XkbChangeIndicators</em></span>.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Effects_of_Explicit_Changes_on_Indicators"></a>Effects of Explicit Changes on Indicators</h3></div></div></div><p>
This section discusses the effects of explicitly changing indicators depending
upon different settings in the indicator map. See Tables 8.3 and Table 8.5 for
information on the effects of the indicator map fields when explicit changes
are made.
</p><p>
If <span class="emphasis"><em>
XkbIM_LEDDrivesKB</em></span>
 is set and <span class="emphasis"><em>
XkbIM_NoExplicit</em></span>
 is not, and if you call a function that updates the server’s image of the
indicator map (such as <span class="emphasis"><em>
XkbSetIndicatorMap</em></span>
 or <span class="emphasis"><em>
XkbSetNamedIndicator</em></span>
), Xkb changes the keyboard state and controls to reflect the other fields of
the indicator map. If you attempt to explicitly change the value of an
indicator for which <span class="emphasis"><em>
XkbIM_LEDDrivesKB</em></span>
 is absent or for which <span class="emphasis"><em>
XkbIM_NoExplicit</em></span>
 is present, keyboard state or controls are unaffected.
</p><p>
If neither <span class="emphasis"><em>
XkbIM_NoAutomatic</em></span>
 nor <span class="emphasis"><em>
XkbIM_NoExplicit</em></span>
 is set in an indicator map, Xkb honors any request to change the state of the
indicator, but the new state might be immediately superseded by automatic
changes to the indicator state if the keyboard state or controls change.
</p><p>
The effects of changing an indicator that drives the keyboard are cumulative;
it is possible for a single change to affect keyboard group, modifiers, and
controls simultaneously.
</p><p>
If you change an indicator for which both the <span class="emphasis"><em>
XkbIM_LEDDrivesKB</em></span>
 and <span class="emphasis"><em>
XkbIM_NoAutomatic</em></span>
 flags are specified, Xkb applies the keyboard changes specified in the other
indicator map fields and changes the indicator to reflect the state that was
explicitly requested. The indicator remains in the new state until it is
explicitly changed again.
</p><p>
If the <span class="emphasis"><em>
XkbIM_NoAutomatic</em></span>
 flag is not set and <span class="emphasis"><em>
XkbIM_LEDDrivesKB</em></span>
 is set, Xkb applies the changes specified in the other indicator map fields
and sets the state of the indicator to the values specified by the indicator
map. Note that it is possible in this case for the indicator to end up in a
different state than the one that was explicitly requested. For example, Xkb
does not extinguish an indicator with <span class="emphasis"><em>
which_mods</em></span>
 of <span class="emphasis"><em>
XkbIM_UseBase</em></span>
 and <span class="emphasis"><em>
mods</em></span>
 of <span class="emphasis"><em>
Shift</em></span>
 if, at the time Xkb processes the request to extinguish the indicator, one of
the <span class="emphasis"><em>
Shift</em></span>
 keys is physically depressed.
</p><p>
If you explicitly light an indicator for which <span class="emphasis"><em>
XkbIM_LEDDrivesKB</em></span>
 is set, Xkb enables all of the boolean controls specified in the <span class="emphasis"><em>
ctrls</em></span>
 field of its indicator map. Explicitly extinguishing such an indicator causes
Xkb to disable all of the boolean controls specified in <span class="emphasis"><em>
ctrls</em></span>
.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Changing_Indicator_Maps_by_Index"></a>Changing Indicator Maps by Index</h3></div></div></div><p>
To update the maps for one or more indicators, first modify a local copy of the
keyboard description, then use <span class="emphasis"><em>
XkbSetIndicatorMap</em></span>
 to download the changes to the server:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool<span class="emphasis"><em>
 XkbSetIndicatorMap</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 which</em></span>
,<span class="emphasis"><em>
 desc</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
dpy</em></span>
;      /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
which</em></span>
;      /* mask of indicators to change */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr      <span class="emphasis"><em>
desc</em></span>
;      /* keyboard description from which the maps are taken */
    </td></tr></tbody></table></div><p>
For each<span class="emphasis"><em>
 </em></span>
bit set in the <span class="emphasis"><em>
which </em></span>
parameter,<span class="emphasis"><em>
 XkbSetIndicatorMap</em></span>
 sends the corresponding indicator map from the <span class="emphasis"><em>
desc</em></span>
 parameter to the server.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Changing_Indicator_Maps_by_Name"></a>Changing Indicator Maps by Name</h3></div></div></div><p>
<span class="emphasis"><em>
XkbSetNamedIndicator</em></span>
 can do several related things:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Name an indicator if it is not already named
  </p></li><li class="listitem"><p>
Toggle the state of the indicator
  </p></li><li class="listitem"><p>
Set the indicator to a specified state
  </p></li><li class="listitem"><p>
Set the indicator map for the indicator
  </p></li></ul></div><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool<span class="emphasis"><em>
 XkbSetNamedIndicator</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 device_spec</em></span>
,<span class="emphasis"><em>
 name</em></span>
,<span class="emphasis"><em>
 change_state, state</em></span>
,<span class="emphasis"><em>
 create_new</em></span>
,<span class="emphasis"><em>
 map</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
      dpy</em></span>
;            /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
      device_spec</em></span>
;            /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
Atom      <span class="emphasis"><em>
      name</em></span>
;            /* name of the indicator to change */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
      change_state</em></span>
;            /* whether to change the indicator state or not */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
      state</em></span>
;            /* desired new state for the indicator */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool            <span class="emphasis"><em>
create_new</em></span>
;            /* whether a new indicator with the specified name should be
created when necessary */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbIndicatorMapPtr            <span class="emphasis"><em>
map</em></span>
;            /* new map for the indicator */
    </td></tr></tbody></table></div><p>
If a compatible version of the Xkb extension is not available in the server,
<span class="emphasis"><em>
XkbSetNamedIndicator</em></span>
 returns <span class="emphasis"><em>
False</em></span>
. Otherwise, it sends a request to the X server to change the indicator
specified by <span class="emphasis"><em>
name</em></span>
 and returns <span class="emphasis"><em>
True</em></span>.
</p><p>
If <span class="emphasis"><em>
change_state</em></span>
 is <span class="emphasis"><em>
True</em></span>
, and the optional parameter, <span class="emphasis"><em>
state</em></span>
, is not <span class="emphasis"><em>
NULL</em></span>
, <span class="emphasis"><em>
XkbSetNamedIndicator</em></span>
 tells the server to change the state of the named indicator to the value
specified by <span class="emphasis"><em>
state</em></span>.
</p><p>
If an indicator with the name specified by <span class="emphasis"><em>
name</em></span>
 does not already exist, the <span class="emphasis"><em>
create_new</em></span>
 parameter tells the server whether it should create a new named indicator. If
<span class="emphasis"><em>
create_new</em></span>
 is <span class="emphasis"><em>
True</em></span>
, the server finds the first indicator that doesn’t have a name and gives it
the name specified by <span class="emphasis"><em>
name</em></span>.
</p><p>
If the optional parameter, <span class="emphasis"><em>
map</em></span>
, is not <span class="emphasis"><em>
NULL</em></span>
, <span class="emphasis"><em>
XkbSetNamedIndicator</em></span>
 tells the server to change the indicator’s map to the values specified
in <span class="emphasis"><em>map</em></span>.
</p><p>
<span class="emphasis"><em>
XkbSetNamedIndicator</em></span>
 can generate <span class="emphasis"><em>
BadAtom</em></span>
 and <span class="emphasis"><em>
BadImplementation</em></span>
 errors. In addition, it can also generate <span class="emphasis"><em>
XkbIndicatorStateNotify</em></span>
 (see section 8.5), <span class="emphasis"><em> 
XkbIndicatorMapNotify</em></span>
, and <span class="emphasis"><em>
XkbNamesNotify</em></span>
 events (see section 18.5). 
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_XkbIndicatorChangesRec_Structure"></a>The XkbIndicatorChangesRec Structure</h3></div></div></div><p>
The <span class="emphasis"><em>
XkbIndicatorChangesRec</em></span>
 identifies small modifications to the indicator map. Use it with the function
<span class="emphasis"><em>
XkbChangeIndicators</em></span>
 to reduce the amount of traffic sent to the server.
</p><pre class="programlisting">
typedef struct _XkbIndicatorChanges {
      unsigned int             state_changes;
      unsigned int             map_changes;
}<span class="emphasis"><em>
XkbIndicatorChangesRec</em></span>,*XkbIndicatorChangesPtr;
</pre><p>
The <span class="emphasis"><em>
state_changes</em></span>
 field is a mask that specifies the indicators that have changed state, and
<span class="emphasis"><em>
map_changes</em></span>
 is a mask that specifies the indicators whose maps have changed.
</p><p>
To change indicator maps or state without passing the entire keyboard
description, use <span class="emphasis"><em>
XkbChangeIndicators</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbChangeIndicators</em></span>
(<span class="emphasis"><em>
dpy, xkb, changes, state</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *                  <span class="emphasis"><em>
dpy</em></span>
;      /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr                  <span class="emphasis"><em>
xkb</em></span>
;      /* keyboard description from which names are to be
    </td></tr><tr><td class="functionargdecl" align="left">
                        taken. */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbIndicatorChangesPtr                  <span class="emphasis"><em>
changes</em></span>
;      /* indicators to be updated on the server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int                  <span class="emphasis"><em>
state</em></span>
;      /* new state of indicators listed in
    </td></tr><tr><td class="functionargdecl" align="left">
<span class="emphasis"><em>
                        changes</em></span>
-&gt;<span class="emphasis"><em>
state_changes</em></span>
 */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbChangeIndicators</em></span>
 copies any maps specified by <span class="emphasis"><em>
changes</em></span>
 from the keyboard description, <span class="emphasis"><em>
xkb</em></span>
, to the server specified by <span class="emphasis"><em>
dpy</em></span>
. If any bits are set in the <span class="emphasis"><em>
state_changes</em></span>
 field of <span class="emphasis"><em>
changes</em></span>
, <span class="emphasis"><em>
XkbChangeIndicators</em></span>
 also sets the state of those indicators to the values specified in the
<span class="emphasis"><em>
state</em></span>
 mask. A 1 bit in <span class="emphasis"><em>
state</em></span>
 turns the corresponding indicator on, a 0 bit turns it off.
</p><p>
<span class="emphasis"><em>
XkbChangeIndicator</em></span>
s can generate <span class="emphasis"><em>
BadAtom</em></span>
 and <span class="emphasis"><em>
BadImplementation</em></span>
 errors. In addition, it can also generate <span class="emphasis"><em>
XkbIndicatorStateNotify</em></span>
 and <span class="emphasis"><em>
XkbIndicatorMapNotify</em></span>
 events (see section 8.5). 
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Tracking_Changes_to_Indicator_State_or_Map"></a>Tracking Changes to Indicator State or Map</h2></div></div></div><p>
Whenever an indicator changes state, the server sends <span class="emphasis"><em>
XkbIndicatorStateNotify</em></span>
 events to all interested clients. Similarly, whenever an indicator’s map
changes, the server sends <span class="emphasis"><em>
XkbIndicatorMapNotify</em></span>
 events to all interested clients.
</p><p>
To receive <span class="emphasis"><em>
XkbIndicatorStateNotify</em></span>
 events, use <span class="emphasis"><em>
XkbSelectEvents</em></span>
 (see section 4.3) with both the <span class="emphasis"><em> 
bits_to_change </em></span>
and<span class="emphasis"><em>
 values_for_bits</em></span>
 parameters containing <span class="emphasis"><em>
XkbIndicatorStateNotifyMask</em></span>
. To receive <span class="emphasis"><em>
XkbIndicatorMapNotify</em></span>
 events, use <span class="emphasis"><em>
XkbSelectEvents</em></span>
 with <span class="emphasis"><em>
XkbIndicatorMapNotifyMask</em></span>
.
</p><p>
To receive events for only specific indicators, use <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
. Set the <span class="emphasis"><em>
event_type</em></span>
 parameter<span class="emphasis"><em>
 to XkbIndicatorStateNotify</em></span>
 or <span class="emphasis"><em>
XkbIndicatorMapNotify</em></span>
, and set both the <span class="emphasis"><em>
bits_to_change </em></span>
and<span class="emphasis"><em>
 values_for_bits</em></span>
 detail parameters to a mask where each bit specifies one indicator, turning on
those bits that specify the indicators for which you want to receive events.
</p><p>
Both types of indicator events use the same structure:
</p><pre class="programlisting">
typedef struct _XkbIndicatorNotify {
      int            type;        /* Xkb extension base event code */
      unsigned long  serial;      /* X server serial number for event */
      Bool           send_event;  /* <span class="emphasis"><em> True</em></span> =&gt; synthetically generated */
      Display *      display;     /* server connection where event generated */
      Time           time;        /* server time when event generated */
      int            xkb_type;    /* specifies state or map notify */
      int            device;      /* Xkb device ID, will not be <span class="emphasis"><em> XkbUseCoreKbd</em></span> */
      unsigned int   changed;     /* mask of indicators with new state or map */
      unsigned int   state;       /* current state of all indicators */
} <span class="emphasis"><em>XkbIndicatorNotifyEvent</em></span>;
</pre><p>
<span class="emphasis"><em>
xkb_type</em></span>
 is either <span class="emphasis"><em>
XkbIndicatorStateNotify</em></span>
 or <span class="emphasis"><em>
XkbIndicatorMapNotify</em></span>
, depending on whether the event is a <span class="emphasis"><em>
kbIndicatorStateNotify</em></span>
 event or <span class="emphasis"><em>
kbIndicatorMapNotify</em></span>
 event.
</p><p>
The <span class="emphasis"><em>
changed</em></span>
 parameter is a mask that is the bitwise inclusive OR of the indicators that
have changed. If the event is of type <span class="emphasis"><em>
XkbIndicatorMapNotify</em></span>
, <span class="emphasis"><em>
changed</em></span>
 reports the maps that changed. If the event is of type <span class="emphasis"><em>
XkbIndicatorStateNotify</em></span>
, <span class="emphasis"><em>
changed</em></span>
 reports the indicators that have changed state. <span class="emphasis"><em>
state</em></span>
 is a mask that specifies the current state of all indicators, whether they
have changed or not, for both <span class="emphasis"><em>
XkbIndicatorStateNotify</em></span>
 and <span class="emphasis"><em>IndicatorMapNotify</em></span> events.
</p><p>
When your client application receives either a <span class="emphasis"><em>
XkbIndicatorStateNotify</em></span>
 event or <span class="emphasis"><em>
XkbIndicatorMapNotify</em></span>
 event, you can note the changes in a changes structure by calling <span class="emphasis"><em>
XkbNoteIndicatorChanges</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbNoteIndicatorChanges</em></span>
(<span class="emphasis"><em>
old</em></span>
,<span class="emphasis"><em>
 new</em></span>
,<span class="emphasis"><em>
 wanted</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbIndicatorChangesPtr            <span class="emphasis"><em>
      old</em></span>
;      /* XkbIndicatorChanges structure to be updated */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbIndicatorNotifyEvent *                  <span class="emphasis"><em>
new</em></span>
;      /* event from which changes are to be copied */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
      wanted</em></span>
;      /* which changes are to be noted */
    </td></tr></tbody></table></div><p>
The <span class="emphasis"><em>
wanted</em></span>
 parameter is the bitwise inclusive OR of <span class="emphasis"><em>
XkbIndicatorMapMask</em></span>
 and <span class="emphasis"><em>
XkbIndicatorStateMask</em></span>
. <span class="emphasis"><em>
XkbNoteIndicatorChanges</em></span>
 copies any changes reported in <span class="emphasis"><em>
new</em></span>
 and specified in <span class="emphasis"><em>
wanted</em></span>
 into the changes record specified by <span class="emphasis"><em>
old</em></span>.
</p><p>
To update a local copy of the keyboard description with the actual values, pass
the results of one or more calls to <span class="emphasis"><em>
XkbNoteIndicatorChanges</em></span>
 to <span class="emphasis"><em>
XkbGetIndicatorChanges</em></span>:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetIndicatorChanges</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 xkb</em></span>
,<span class="emphasis"><em>
 changes</em></span>
,<span class="emphasis"><em>
 state</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            <span class="emphasis"><em>
dpy</em></span>
;            /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;            /* keyboard description to hold the new values */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbIndicatorChangesPtr            <span class="emphasis"><em>
changes</em></span>
;            /* indicator maps/state to be obtained from the server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int *            <span class="emphasis"><em>
state</em></span>
;            /* backfilled with the state of the indicators */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetIndicatorChanges</em></span>
 examines the <span class="emphasis"><em>
changes</em></span>
 parameter, pulls over the necessary information from the server, and copies
the results into the <span class="emphasis"><em>
xkb</em></span>
 keyboard description. If any bits are set in the <span class="emphasis"><em>
state_changes</em></span>
 field of <span class="emphasis"><em>
changes</em></span>
, <span class="emphasis"><em>
XkbGetIndicatorChanges</em></span>
 also places the state of those indicators in <span class="emphasis"><em>
state</em></span>
. If the <span class="emphasis"><em>
indicators</em></span>
 field of <span class="emphasis"><em>
xkb</em></span>
 is <span class="emphasis"><em>
NULL</em></span>
, <span class="emphasis"><em>
XkbGetIndicatorChanges</em></span>
 allocates and initializes it. To free the <span class="emphasis"><em>
indicators</em></span>
 field, use <span class="emphasis"><em>
XkbFreeIndicators</em></span>
 (see section 8.6). 
</p><p>
<span class="emphasis"><em>
XkbGetIndicatorChanges</em></span>
 can generate <span class="emphasis"><em>
BadAlloc</em></span>
, <span class="emphasis"><em>
BadImplementation,</em></span>
 and <span class="emphasis"><em>
BadMatch</em></span>
 errors.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Allocating_and_Freeing_Indicator_Maps"></a>Allocating and Freeing Indicator Maps</h2></div></div></div><p>
Most applications do not need to directly allocate the <span class="emphasis"><em>
indicators</em></span>
 member of the keyboard description record (the keyboard description record is
described in Chapter 6). If the need arises, however, use <span class="emphasis"><em>
XkbAllocIndicatorMaps.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocIndicatorMaps</em></span>
(<span class="emphasis"><em>
xkb</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr      <span class="emphasis"><em>
xkb</em></span>
;      /* keyboard description structure */
    </td></tr></tbody></table></div><p>
The <span class="emphasis"><em>
xkb</em></span>
 parameter must point to a valid keyboard description. If it doesn’t,
<span class="emphasis"><em>
XkbAllocIndicatorMaps</em></span>
 returns a <span class="emphasis"><em>
BadMatch</em></span>
 error. Otherwise, <span class="emphasis"><em>
XkbAllocIndicatorMaps</em></span>
 allocates and initializes the <span class="emphasis"><em>
indicators</em></span>
 member of the keyboard description record and returns <span class="emphasis"><em>
Success</em></span>
. If <span class="emphasis"><em>
XkbAllocIndicatorMaps</em></span>
 was unable to allocate the indicators record, it reports a Bad<span class="emphasis"><em>
Alloc</em></span>
 error.
</p><p>
To free memory used by the <span class="emphasis"><em>
indicators</em></span>
 member of an <span class="emphasis"><em>
XkbDescRec</em></span>
 structure, use <span class="emphasis"><em>
XkbFreeIndicatorMaps.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeIndicatorMaps</em></span>
(<span class="emphasis"><em>
xkb</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr      <span class="emphasis"><em>
xkb</em></span>
;      /* keyboard description structure */
    </td></tr></tbody></table></div><p>
If the <span class="emphasis"><em>indicators</em></span>
 member of the keyboard description record
pointed to by <span class="emphasis"><em>xkb</em></span>
is not <span class="emphasis"><em>NULL</em></span>
, <span class="emphasis"><em>XkbFreeIndicatorMaps</em></span>
frees the memory associated with
the <span class="emphasis"><em>indicators</em></span>
member of <span class="emphasis"><em>xkb</em></span>.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Bells"></a>Chapter 9. Bells</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Bell_Names">Bell Names</a></span></dt><dt><span class="sect1"><a href="#Audible_Bells">Audible Bells</a></span></dt><dt><span class="sect1"><a href="#Bell_Functions">Bell Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Generating_Named_Bells">Generating Named Bells</a></span></dt><dt><span class="sect2"><a href="#Generating_Named_Bell_Events">Generating Named Bell Events</a></span></dt><dt><span class="sect2"><a href="#Forcing_a_Server_Generated_Bell">Forcing a Server-Generated Bell</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Detecting_Bells">Detecting Bells</a></span></dt></dl></div><p>
The core X protocol allows only applications to explicitly sound the system
bell with a given duration, pitch, and volume. Xkb extends this capability by
allowing clients to attach symbolic names to bells, disable audible bells, and
receive an event whenever the keyboard bell is rung. For the purposes of this
document, the <span class="emphasis"><em>
audible</em></span>
 bell is defined to be the system bell, or the default keyboard bell, as
opposed to any other audible sound generated elsewhere in the system.
</p><p>
You can ask to receive <span class="emphasis"><em>
XkbBellNotify</em></span>
 events (see section 9.4) when any client rings any one of the following: 
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The default bell
  </p></li><li class="listitem"><p>
Any bell on an input device that can be specified by a <span class="emphasis"><em>
bell_class</em></span>
 and <span class="emphasis"><em>
bell_id</em></span>
 pair
  </p></li><li class="listitem"><p>
Any bell specified only by an arbitrary name. (This is, from the server’s
point of view, merely a name, and not connected with any physical
sound-generating device. Some client application must generate the sound, or
visual feedback, if any, that is associated with the name.)
  </p></li></ul></div><p>
You can also ask to receive <span class="emphasis"><em>
XkbBellNotify</em></span>
 events when the server rings the default bell or if any client has requested
events only (without the bell sounding) for any of the bell types previously
listed.
</p><p>
You can disable audible bells on a global basis (to set the <span class="emphasis"><em>
AudibleBell</em></span>
 control, see Chapter 10). For example, a client that replaces the keyboard
bell with some other audible cue might want to turn off the <span class="emphasis"><em>
AudibleBell</em></span>
 control to prevent the server from also generating a sound and avoid
cacophony. If you disable audible bells and request to receive <span class="emphasis"><em>
XkbBellNotify</em></span>
 events, you can generate feedback different from the default bell.
</p><p>
You can, however, override the <span class="emphasis"><em>
AudibleBell</em></span>
 control by calling one of the functions that force the ringing of a bell in
spite of the setting of the <span class="emphasis"><em>
AudibleBell</em></span>
 control — <span class="emphasis"><em>
XkbForceDeviceBell</em></span>
 or <span class="emphasis"><em>
XkbForceBell</em></span>
 (see section 9.3.3). In this case the server does not generate a bell event. 
</p><p>
Just as some keyboards can produce keyclicks to indicate when a key is pressed
or repeating, Xkb can provide feedback for the controls by using special beep
codes. The <span class="emphasis"><em>
AccessXFeedback</em></span>
 control is used to configure the specific types of operations that generate
feedback. See section 10.6.3 for a discussion on <span class="emphasis"><em> 
AccessXFeedback</em></span>
 control.
</p><p>
This chapter describes bell names, the functions used to generate named bells,
and the events the server generates for bells.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Bell_Names"></a>Bell Names</h2></div></div></div><p>
You can associate a name to an act of ringing a bell by converting the name to
an Atom and then using this name when you call the functions listed in this
chapter. If an event is generated as a result, the name is then passed to all
other clients interested in receiving <span class="emphasis"><em>
XkbBellNotify</em></span>
 events. Note that these are arbitrary names and that there is no binding to
any sounds. Any sounds or other effects (such as visual bells on the screen)
must be generated by a client application upon receipt of the bell event
containing the name. There is no default name for the default keyboard bell.
The server does generate some predefined bells for the AccessX controls (see
section 10.6.3). These named bells are shown in Table 9.1; the name is included
in any bell event sent to clients that have requested to receive <span class="emphasis"><em>
XkbBellNotify</em></span>
 events.
</p><div class="table"><a id="idp64762276"></a><p class="title"><strong>Table 9.1. Predefined Bells</strong></p><div class="table-contents"><table summary="Predefined Bells" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Action</th><th align="left">Named Bell</th></tr></thead><tbody><tr><td align="left">Indicator turned on</td><td align="left">AX_IndicatorOn</td></tr><tr><td align="left">Indicator turned off</td><td align="left">AX_IndicatorOff</td></tr><tr><td align="left">More than one indicator changed state</td><td align="left">AX_IndicatorChange</td></tr><tr><td align="left">Control turned on</td><td align="left">AX_FeatureOn</td></tr><tr><td align="left">Control turned off</td><td align="left">AX_FeatureOff</td></tr><tr><td align="left">More than one control changed state</td><td align="left">AX_FeatureChange</td></tr><tr><td align="left">SlowKeys and BounceKeys about to be turned on or off</td><td align="left">AX_SlowKeysWarning</td></tr><tr><td align="left">SlowKeys key pressed</td><td align="left">AX_SlowKeyPress</td></tr><tr><td align="left">SlowKeys key accepted</td><td align="left">AX_SlowKeyAccept</td></tr><tr><td align="left">SlowKeys key rejected</td><td align="left">AX_SlowKeyReject</td></tr><tr><td align="left">Accepted SlowKeys key released</td><td align="left">AX_SlowKeyRelease</td></tr><tr><td align="left">BounceKeys key rejected</td><td align="left">AX_BounceKeyReject</td></tr><tr><td align="left">StickyKeys key latched</td><td align="left">AX_StickyLatch</td></tr><tr><td align="left">StickyKeys key locked</td><td align="left">AX_StickyLock</td></tr><tr><td align="left">StickyKeys key unlocked</td><td align="left">AX_StickyUnlock</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Audible_Bells"></a>Audible Bells</h2></div></div></div><p>
Using Xkb you can generate bell events that do not necessarily ring the system
bell. This is useful if you need to use an audio server instead of the system
beep. For example, when an audio client starts, it could disable the audible
bell (the system bell) and then listen for <span class="emphasis"><em>
XkbBellNotify</em></span>
 events (see section 9.4). When it receives a <span class="emphasis"><em> 
XkbBellNotify</em></span>
 event, the audio client could then send a request to an audio server to play a
sound.
</p><p>
You can control the audible bells feature by passing the <span class="emphasis"><em>
XkbAudibleBellMask</em></span>
 to <span class="emphasis"><em>
XkbChangeEnabledControls</em></span>
 (see section 10.1.1). If you set <span class="emphasis"><em> 
XkbAudibleBellMask</em></span>
 on, the server rings the system bell when a bell event occurs. This is the
default. If you set <span class="emphasis"><em>
XkbAudibleBellMask</em></span>
 off and a bell event occurs, the server does not ring the system bell unless
you call <span class="emphasis"><em>
XkbForceDeviceBell</em></span>
 or <span class="emphasis"><em>
XkbForceBell</em></span>
 (see section 9.3.3). 
</p><p>
Audible bells are also part of the per-client auto-reset controls. For more
information on auto-reset controls, see section 10.1.2. 
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Bell_Functions"></a>Bell Functions</h2></div></div></div><p>
Use the functions described in this section to ring bells and to generate bell
events.
</p><p>
The input extension has two types of feedbacks that can generate bells — bell
feedback and keyboard feedback. Some of the functions in this section have
<span class="emphasis"><em>
bell_class</em></span>
 and <span class="emphasis"><em>
bell_id</em></span>
 parameters; set them as follows: Set <span class="emphasis"><em>
bell_class</em></span>
 to <span class="emphasis"><em>
BellFeedbackClass</em></span>
 or <span class="emphasis"><em>
KbdFeedbackClass</em></span>
. A device can have more than one feedback of each type; set <span class="emphasis"><em>
bell_id</em></span>
 to the particular bell feedback of <span class="emphasis"><em>
bell_class</em></span>
 type.
</p><p>
Table 9.2 shows the conditions that cause a bell to sound or an <span class="emphasis"><em> 
XkbBellNotifyEvent</em></span>
 to be generated when a bell function is called.
</p><div class="table"><a id="idp64784092"></a><p class="title"><strong>Table 9.2. Bell Sounding and Bell Event Generating</strong></p><div class="table-contents"><table summary="Bell Sounding and Bell Event Generating" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Function called</th><th align="left">AudibleBell</th><th align="left">Server sounds a bell</th><th align="left">Server sends an XkbBellNotifyEvent</th></tr></thead><tbody><tr><td align="left">XkbDeviceBell</td><td align="left">On</td><td align="left">Yes</td><td align="left">Yes</td></tr><tr><td align="left">XkbDeviceBell</td><td align="left">Off</td><td align="left">No</td><td align="left">Yes</td></tr><tr><td align="left">XkbBell</td><td align="left">On</td><td align="left">Yes</td><td align="left">Yes</td></tr><tr><td align="left">XkbBell</td><td align="left">Off</td><td align="left">No</td><td align="left">Yes</td></tr><tr><td align="left">XkbDeviceBellEvent</td><td align="left">On or Off</td><td align="left">No</td><td align="left">Yes</td></tr><tr><td align="left">XkbBellEvent</td><td align="left">On or Off</td><td align="left">No</td><td align="left">Yes</td></tr><tr><td align="left">XkbDeviceForceBell</td><td align="left">On or Off</td><td align="left">Yes</td><td align="left">No</td></tr><tr><td align="left">XkbForceBell</td><td align="left">On or Off</td><td align="left">Yes</td><td align="left">No</td></tr></tbody></table></div></div><br class="table-break" /><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Generating_Named_Bells"></a>Generating Named Bells</h3></div></div></div><p>
To ring the bell on an X input extension device or the default keyboard, use
<span class="emphasis"><em>
XkbDeviceBell.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbDeviceBell</em></span>
(<span class="emphasis"><em>
display, window, device_id, bell_class, bell_id, percent, name</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
      display</em></span>
;            /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
Window<span class="emphasis"><em>
      window</em></span>
;            /* window for which the bell is generated, or None */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
device_spec</em></span>
;            /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
bell_class</em></span>
;            /* X input extension bell class of the bell to be rung */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
bell_id</em></span>
;            /* X input extension bell ID of the bell to be rung */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
percent</em></span>
;            /* bell volume, from -100 to 100 inclusive */
    </td></tr><tr><td class="functionargdecl" align="left">
Atom      <span class="emphasis"><em>
name</em></span>
;            /* a name for the bell, or <span class="emphasis"><em>
NULL</em></span>
 */
    </td></tr></tbody></table></div><p>
Set <span class="emphasis"><em>
percent</em></span>
 to be the volume relative to the base volume for the keyboard as described for
<span class="emphasis"><em>
XBell</em></span>.
</p><p>
Note that <span class="emphasis"><em>
bell_class</em></span>
 and <span class="emphasis"><em>
bell_id</em></span>
 indicate the bell to physically ring. <span class="emphasis"><em>
name</em></span>
 is simply an arbitrary moniker for the client application’s use.
</p><p>
To determine the current feedback settings of an extension input device, use
<span class="emphasis"><em>
XGetFeedbackControl</em></span>
. See the X input extension documentation for more information on <span class="emphasis"><em>
XGetFeedbackControl</em></span>
 and related data structures.
</p><p>
If a compatible keyboard extension is not present in the X server, <span class="emphasis"><em>
XkbDeviceBell</em></span>
 immediately returns <span class="emphasis"><em>
False</em></span>
. Otherwise, <span class="emphasis"><em>
XkbDeviceBell </em></span>
rings the bell as specified for the display and keyboard device and returns
<span class="emphasis"><em>
True</em></span>
. If you have disabled the audible bell, the server does not ring the system
bell, although it does generate a <span class="emphasis"><em>
XkbBellNotify</em></span>
 event.
</p><p>
You can call <span class="emphasis"><em>
XkbDeviceBell</em></span>
 without first initializing the keyboard extension.
</p><p>
As a convenience function, Xkb provides a function to ring the bell on the
default keyboard: <span class="emphasis"><em>
XkbBell.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbBell</em></span>
(<span class="emphasis"><em>
display, window, percent, name</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
display</em></span>
;            /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
Window<span class="emphasis"><em>
      window</em></span>
;            /* event window, or None*/
    </td></tr><tr><td class="functionargdecl" align="left">
int<span class="emphasis"><em>
      percent</em></span>
;            /* relative volume, which can range from -100 to 100 inclusive */
    </td></tr><tr><td class="functionargdecl" align="left">
Atom<span class="emphasis"><em>
      name</em></span>
;            /* a bell name, or <span class="emphasis"><em>
NULL</em></span>
 */
    </td></tr></tbody></table></div><p>
If a compatible keyboard extension isn’t present in the X server, <span class="emphasis"><em>
XkbBell</em></span>
 calls <span class="emphasis"><em>
XBell </em></span>
with the specified <span class="emphasis"><em>
display</em></span>
 and <span class="emphasis"><em>
percent</em></span>
, and returns <span class="emphasis"><em>
False</em></span>
. Otherwise, <span class="emphasis"><em>
XkbBell </em></span>
calls <span class="emphasis"><em>
XkbDeviceBell</em></span>
 with the specified <span class="emphasis"><em>
display, window, percent, </em></span>
and <span class="emphasis"><em>
name</em></span>
, a <span class="emphasis"><em>
device_spec</em></span>
 of <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
, a <span class="emphasis"><em>
bell_class </em></span>
of <span class="emphasis"><em>
XkbDfltXIClass</em></span>
, and a <span class="emphasis"><em>
bell_id </em></span>
of <span class="emphasis"><em>
XkbDfltXIId,</em></span>
 and returns <span class="emphasis"><em>
True</em></span>.
</p><p>
If you have disabled the audible bell, the server does not ring the system
bell, although it does generate a <span class="emphasis"><em>
XkbBellNotify</em></span>
 event.
</p><p>
You can call <span class="emphasis"><em>
XkbBell</em></span>
 without first initializing the keyboard extension.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Generating_Named_Bell_Events"></a>Generating Named Bell Events</h3></div></div></div><p>
Using Xkb, you can also generate a named bell event that does not ring any
bell. This allows you to do things such as generate events when your
application starts.
</p><p>
For example, if an audio client listens for these types of bells, it can
produce a "whoosh" sound when it receives a named bell event to indicate a
client just started. In this manner, applications can generate start-up
feedback and not worry about producing annoying beeps if an audio server is not
running.
</p><p>
To cause a bell event for an X input extension device or for the keyboard,
without ringing the corresponding bell, use <span class="emphasis"><em>
XkbDeviceBellEvent.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbDeviceBellEvent</em></span>
(<span class="emphasis"><em>
display, window, device_spec, bell_class, bell_id, percent, name</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
display</em></span>
;      /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
Window      <span class="emphasis"><em>
window</em></span>
;      /* event window, or None*/
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
device_spec</em></span>
;      /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
bell_class;</em></span>
      /* input extension bell class for the event */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
bell_id</em></span>
;      /* input extension bell ID for the event */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
percent</em></span>
;      /* volume for the bell, which can range from -100 to 100 inclusive */
    </td></tr><tr><td class="functionargdecl" align="left">
Atom      <span class="emphasis"><em>
name</em></span>
;      /* a bell name, or <span class="emphasis"><em>
NULL</em></span>
 */
    </td></tr></tbody></table></div><p>
If a compatible keyboard extension isn’t present in the X server, <span class="emphasis"><em>
XkbDeviceBellEvent</em></span>
 immediately returns <span class="emphasis"><em>
False</em></span>
. Otherwise, <span class="emphasis"><em>
XkbDeviceBellEvent</em></span>
 causes an <span class="emphasis"><em>
XkbBellNotify</em></span>
 event to be sent to all interested clients and returns <span class="emphasis"><em>
True</em></span>
. Set <span class="emphasis"><em>
percent</em></span>
 to be the volume relative to the base volume for the keyboard as described for
<span class="emphasis"><em>XBell</em></span>.
</p><p>
In addition, <span class="emphasis"><em>
XkbDeviceBellEvent</em></span>
 may generate <span class="emphasis"><em>
Atom</em></span>
 protocol errors as well as <span class="emphasis"><em>
XkbBellNotify</em></span>
 events. You can call <span class="emphasis"><em>
XkbBell</em></span>
 without first initializing the keyboard extension.
</p><p>
As a convenience function, Xkb provides a function to cause a bell event for
the keyboard without ringing the bell: <span class="emphasis"><em>
XkbBellEvent.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbBellEvent</em></span>
(<span class="emphasis"><em>
display, window, percent, name</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
display</em></span>
;            /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
Window      <span class="emphasis"><em>
window</em></span>
;            /* the event window, or None */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
percent</em></span>
;            /* relative volume, which can range from -100 to 100 inclusive */
    </td></tr><tr><td class="functionargdecl" align="left">
Atom      <span class="emphasis"><em>
name</em></span>
;            /* a bell name, or <span class="emphasis"><em>
NULL</em></span>
 */
    </td></tr></tbody></table></div><p>
If a compatible keyboard extension isn’t present in the X server, <span class="emphasis"><em>
XkbBellEvent</em></span>
 immediately returns <span class="emphasis"><em>
False</em></span>
. Otherwise, <span class="emphasis"><em>
XkbBellEvent </em></span>
calls<span class="emphasis"><em>
 XkbDeviceBellEvent</em></span>
 with the specified <span class="emphasis"><em>
display, window, percent, </em></span>
and <span class="emphasis"><em>
name</em></span>
, a <span class="emphasis"><em>
device_spec</em></span>
 of <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
, a <span class="emphasis"><em>
bell_class </em></span>
of <span class="emphasis"><em>
XkbDfltXIClass</em></span>
, and a <span class="emphasis"><em>
bell_id </em></span>
of <span class="emphasis"><em>
XkbDfltXIId,</em></span>
 and returns what <span class="emphasis"><em>
XkbDeviceBellEvent</em></span>
 returns.
</p><p>
<span class="emphasis"><em>XkbBellEvent</em></span>
generates a <span class="emphasis"><em>XkbBellNotify</em></span>
event.
</p><p>
You can call <span class="emphasis"><em>
XkbBellEvent</em></span>
without first initializing the keyboard extension.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Forcing_a_Server_Generated_Bell"></a>Forcing a Server-Generated Bell</h3></div></div></div><p>
To ring the bell on any keyboard, overriding user preference settings for
audible bells, use <span class="emphasis"><em>XkbForceDeviceBell</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbForceDeviceBell</em></span>
(<span class="emphasis"><em>
display, window, device_spec, bell_class, bell_id, percent</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
display</em></span>
;            /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
Window      <span class="emphasis"><em>
window</em></span>
;            /* event window, or None */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
device_spec</em></span>
;            /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
bell_class</em></span>
;            /* input extension class of the bell to be rung */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
bell_id</em></span>
;            /* input extension ID of the bell to be rung */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
percent</em></span>
;            /* relative volume, which can range from -100 to 100 inclusive */
    </td></tr></tbody></table></div><p>
If a compatible keyboard extension isn’t present in the X server, <span class="emphasis"><em>
XkbForceDeviceBell</em></span>
 immediately returns <span class="emphasis"><em>
False</em></span>
. Otherwise, <span class="emphasis"><em>
XkbForceDeviceBell </em></span>
rings the bell as specified for the display and keyboard device and returns
<span class="emphasis"><em>
True</em></span>
. Set <span class="emphasis"><em>
percent</em></span>
 to be the volume relative to the base volume for the keyboard as described for
<span class="emphasis"><em>
XBell</em></span>
. There is no <span class="emphasis"><em>
name</em></span>
 parameter because <span class="emphasis"><em>
XkbForceDeviceBell </em></span>
does not cause an <span class="emphasis"><em>
XkbBellNotify</em></span>
 event.
</p><p>
You can call <span class="emphasis"><em>
XkbBell</em></span>
 without first initializing the keyboard extension.
</p><p>
To ring the bell on the default keyboard, overriding user preference settings
for audible bells, use <span class="emphasis"><em>
XkbForceBell</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbForceBell</em></span>
(<span class="emphasis"><em>
display, percent)</em></span>
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
display</em></span>
;      /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
percent</em></span>
;      /* volume for the bell, which can range from -100 to 100 inclusive */
    </td></tr></tbody></table></div><p>
If a compatible keyboard extension isn’t present in the X server, <span class="emphasis"><em>
XkbForceBell</em></span>
 calls <span class="emphasis"><em>
XBell </em></span>
with the specified <span class="emphasis"><em>
display</em></span>
 and <span class="emphasis"><em>
percent</em></span>
 and returns <span class="emphasis"><em>
False</em></span>
. Otherwise, <span class="emphasis"><em>
XkbForceBell </em></span>
calls <span class="emphasis"><em>
XkbForceDeviceBell</em></span>
 with the specified <span class="emphasis"><em>
display </em></span>
and<span class="emphasis"><em>
 percent</em></span>
, <span class="emphasis"><em>
device_spec</em></span>
 =<span class="emphasis"><em>
XkbUseCoreKbd</em></span>
, <span class="emphasis"><em>
bell_class </em></span>
= <span class="emphasis"><em>
XkbDfltXIClass</em></span>
, <span class="emphasis"><em>
bell_id </em></span>
= <span class="emphasis"><em>
XkbDfltXIId,</em></span>
 <span class="emphasis"><em>
window</em></span>
 = None, and <span class="emphasis"><em>
name</em></span>
 = <span class="emphasis"><em>
NULL</em></span>
, and returns what<span class="emphasis"><em>
 XkbForceDeviceBell</em></span>
 returns.
</p><p>
<span class="emphasis"><em>
XkbForceBell </em></span>
does not cause an <span class="emphasis"><em>
XkbBellNotify</em></span>
 event.
</p><p>
You can call <span class="emphasis"><em>
XkbBell</em></span>
 without first initializing the keyboard extension.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Detecting_Bells"></a>Detecting Bells</h2></div></div></div><p>
Xkb generates <span class="emphasis"><em>
XkbBellNotify</em></span>
 events for all bells except for those resulting from calls to <span class="emphasis"><em>
XkbForceDeviceBell</em></span>
 and <span class="emphasis"><em>
XkbForceBell</em></span>
. To receive <span class="emphasis"><em>
XkbBellNotify</em></span>
 events under all possible conditions, pass <span class="emphasis"><em>
XkbBellNotifyMask</em></span>
 in both the <span class="emphasis"><em>
bits_to_change </em></span>
and<span class="emphasis"><em>
 values_for_bits</em></span>
 parameters to <span class="emphasis"><em>
XkbSelectEvents</em></span>
 (see section 4.3). 
</p><p>
The <span class="emphasis"><em>
XkbBellNotify</em></span>
 event has no event details. It is either selected or it is not. However, you
can call <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
 using <span class="emphasis"><em>
XkbBellNotify</em></span>
 as the <span class="emphasis"><em>
event_type</em></span>
 and specifying <span class="emphasis"><em>
XkbAllBellNotifyMask</em></span>
 in <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits.</em></span>
 This has the same effect as a call to <span class="emphasis"><em>
XkbSelectEvents</em></span>.
</p><p>
The structure for the <span class="emphasis"><em>
XkbBellNotify</em></span>
 event type contains:
</p><pre class="programlisting">
typedef struct _XkbBellNotify {
      int             type;        /* Xkb extension base event code */
      unsigned long   serial;      /* X server serial number for event */
      Bool            send_event;  /* <span class="emphasis"><em> True</em></span> =&gt; synthetically generated */
      Display *       display;     /* server connection where event generated */
      Time            time;        /* server time when event generated */
      int             xkb_type;    /* <span class="emphasis"><em> XkbBellNotify</em></span> */
      unsigned int    device;      /* Xkb device ID, will not be <span class="emphasis"><em> XkbUseCoreKbd</em></span> */
      int             percent;     /* requested volume as % of max */
      int             pitch;       /* requested pitch in Hz */
      int             duration;    /* requested duration in microseconds */
      unsigned int    bell_class;  /* X input extension feedback class */
      unsigned int    bell_id;     /* X input extension feedback ID */
      Atom            name;        /* "name" of requested bell */
      Window          window;      /* window associated with event */
      Bool            event_only;  /* <span class="emphasis"><em> False</em></span> -&gt; the server did not produce a beep */
} <span class="emphasis"><em>XkbBellNotifyEvent</em></span>;
</pre><p>
If your application needs to generate visual bell feedback on the screen when
it receives a bell event, use the window ID in the <span class="emphasis"><em>
XkbBellNotifyEvent</em></span>
, if present.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Keyboard_Controls"></a>Chapter 10. Keyboard Controls</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Controls_that_Enable_and_Disable_Other_Controls">Controls that Enable and Disable Other Controls</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_EnabledControls_Control">The EnabledControls Control</a></span></dt><dt><span class="sect2"><a href="#The_AutoReset_Control">The AutoReset Control</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Control_for_Bell_Behavior">Control for Bell Behavior</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_AudibleBell_Control">The AudibleBell Control</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Controls_for_Repeat_Key_Behavior">Controls for Repeat Key Behavior</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_PerKeyRepeat_Control">The PerKeyRepeat Control</a></span></dt><dt><span class="sect2"><a href="#The_RepeatKeys_Control">The RepeatKeys Control</a></span></dt><dt><span class="sect2"><a href="#The_DetectableAutorepeat_Control">The DetectableAutorepeat Control</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Controls_for_Keyboard_Overlays_Overlay1_and_Overlay2_Controls">Controls for Keyboard Overlays (Overlay1 and Overlay2 Controls)</a></span></dt><dt><span class="sect1"><a href="#Controls_for_Using_the_Mouse_from_the_Keyboard">Controls for Using the Mouse from the Keyboard</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_MouseKeys_Control">The MouseKeys Control</a></span></dt><dt><span class="sect2"><a href="#The_MouseKeysAccel_Control">The MouseKeysAccel Control</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Controls_for_Better_Keyboard_Access_by_Physically_ImpairedPersons">Controls for Better Keyboard Access by Physically Impaired
Persons</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_AccessXKeys_Control">The AccessXKeys Control</a></span></dt><dt><span class="sect2"><a href="#The_AccessXTimeout_Control">The AccessXTimeout Control</a></span></dt><dt><span class="sect2"><a href="#The_AccessXFeedback_Control">The AccessXFeedback Control</a></span></dt><dt><span class="sect2"><a href="#AccessXNotify_Events">AccessXNotify Events</a></span></dt><dt><span class="sect2"><a href="#StickyKeys_RepeatKeys_and_MouseKeys_Events">StickyKeys, RepeatKeys, and MouseKeys Events</a></span></dt><dt><span class="sect2"><a href="#The_SlowKeys_Control">The SlowKeys Control</a></span></dt><dt><span class="sect2"><a href="#The_BounceKeys_Control">The BounceKeys Control</a></span></dt><dt><span class="sect2"><a href="#The_StickyKeys_Control">The StickyKeys Control</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Controls_for_General_Keyboard_Mapping">Controls for General Keyboard Mapping</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_GroupsWrap_Control">The GroupsWrap Control</a></span></dt><dt><span class="sect2"><a href="#The_IgnoreLockMods_Control">The IgnoreLockMods Control</a></span></dt><dt><span class="sect2"><a href="#The_IgnoreGroupLock_Control">The IgnoreGroupLock Control</a></span></dt><dt><span class="sect2"><a href="#The_InternalMods_Control">The InternalMods Control</a></span></dt></dl></dd><dt><span class="sect1"><a href="#The_XkbControlsRec_Structure">The XkbControlsRec Structure</a></span></dt><dd><dl><dt><span class="sect2"><a href="#idp66132284"></a></span></dt></dl></dd><dt><span class="sect1"><a href="#Querying_Controls">Querying Controls</a></span></dt><dt><span class="sect1"><a href="#Changing_Controls">Changing Controls</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_XkbControlsChangesRec_Structure">The XkbControlsChangesRec Structure</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Tracking_Changes_to_Keyboard_Controls">Tracking Changes to Keyboard Controls</a></span></dt><dt><span class="sect1"><a href="#Allocating_and_Freeing_an_XkbControlsRec">Allocating and Freeing an XkbControlsRec</a></span></dt><dt><span class="sect1"><a href="#The_Miscellaneous_Per_client_Controls">The Miscellaneous Per-client Controls</a></span></dt></dl></div><p>
The Xkb extension is composed of two parts: a server extension, and a
client-side X library extension. This chapter discusses functions used to
modify controls effecting the behavior of the server portion of the Xkb
extension. Chapter 11 discusses functions used to modify controls that affect
only the behavior of the client portion of the extension; those controls are
known as Library Controls.
</p><p>
Xkb contains control features that affect the entire keyboard, known as global
keyboard controls. Some of the controls may be selectively enabled and
disabled; these controls are known as the <span class="emphasis"><em>
Boolean Controls</em></span>
. Boolean Controls can be turned on or off under program control and can also
be automatically set to an on or off condition when a client program exits. The
remaining controls, known as the <span class="emphasis"><em>
Non-Boolean Controls</em></span>
, are always active. The<span class="emphasis"><em>
 XkbControlsRec</em></span>
 structure describes the current state of most of the global controls and the
attributes effecting the behavior of each of these Xkb features. This chapter
describes the Xkb controls and how to manipulate them.
</p><p>
There are two possible components for each of the Boolean Controls: attributes
describing how the control should work, and a state describing whether the
behavior as a whole is enabled or disabled. The attributes and state for most
of these controls are held in the <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure (see section 10.8).
</p><p>
You can manipulate the Xkb controls individually, via convenience functions, or
as a whole. To treat them as a group, modify an <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure to describe all of the changes to be made, and then pass that
structure and appropriate flags to an Xkb library function, or use a <span class="emphasis"><em>
XkbControlsChangesRec</em></span>
 (see section 10.10.1) to reduce network traffic. When using a convenience
function to manipulate one control individually, you do not use an <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure directly.
</p><p>
The Xkb controls are grouped as shown in Table 10.1. 
</p><div class="table"><a id="idp64865236"></a><p class="title"><strong>Table 10.1. Xkb Keyboard Controls</strong></p><div class="table-contents"><table summary="Xkb Keyboard Controls" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">Type of Control</th><th align="left">Control Name</th><th align="left">Boolean Control?</th></tr></thead><tbody><tr><td align="left">Controls for enabling and disabling other controls</td><td align="left">EnabledControls</td><td align="left">No</td></tr><tr><td align="left"> </td><td align="left">AutoReset</td><td align="left">No</td></tr><tr><td align="left">Control for bell behavior</td><td align="left">AudibleBell</td><td align="left">Boolean</td></tr><tr><td align="left">Controls for repeat key behavior</td><td align="left">PerKeyRepeat</td><td align="left">No</td></tr><tr><td align="left"> </td><td align="left">RepeatKeys</td><td align="left">Boolean</td></tr><tr><td align="left"> </td><td align="left">DetectableAutorepeat</td><td align="left">Boolean</td></tr><tr><td align="left">Controls for keyboard overlays</td><td align="left">Overlay1</td><td align="left">Boolean</td></tr><tr><td align="left"> </td><td align="left">Overlay2</td><td align="left">Boolean</td></tr><tr><td align="left">Controls for using the mouse from the keyboard</td><td align="left">MouseKeys</td><td align="left">Boolean</td></tr><tr><td align="left"> </td><td align="left">MouseKeysAccel</td><td align="left">Boolean</td></tr><tr><td align="left">Controls for better keyboard access by </td><td align="left">AccessXFeedback</td><td align="left">Boolean</td></tr><tr><td align="left">physically impaired persons</td><td align="left">AccessXKeys</td><td align="left">Boolean</td></tr><tr><td align="left"> </td><td align="left">AccessXTimeout</td><td align="left">Boolean</td></tr><tr><td align="left"> </td><td align="left">BounceKeys</td><td align="left">Boolean</td></tr><tr><td align="left"> </td><td align="left">SlowKeys</td><td align="left">Boolean</td></tr><tr><td align="left"> </td><td align="left">StickyKeys</td><td align="left">Boolean</td></tr><tr><td align="left">Controls for general keyboard mapping</td><td align="left">GroupsWrap</td><td align="left">No</td></tr><tr><td align="left"> </td><td align="left">IgnoreGroupLock</td><td align="left">Boolean</td></tr><tr><td align="left"> </td><td align="left">IgnoreLockMods</td><td align="left">No</td></tr><tr><td align="left"> </td><td align="left">InternalMods</td><td align="left">No</td></tr><tr><td align="left">Miscellaneous per-client controls</td><td align="left">GrabsUseXKBState</td><td align="left">Boolean</td></tr><tr><td align="left"> </td><td align="left">LookupStateWhenGrabbed</td><td align="left">Boolean</td></tr><tr><td align="left"> </td><td align="left">SendEventUsesXKBState</td><td align="left">Boolean</td></tr></tbody></table></div></div><br class="table-break" /><p>
The individual categories and controls are described first, together with
functions for manipulating them. A description of the <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure and the general functions for dealing with all of the controls at
once follow at the end of the chapter.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Controls_that_Enable_and_Disable_Other_Controls"></a>Controls that Enable and Disable Other Controls</h2></div></div></div><p>
Enable and disable the boolean controls under program control by using the
<span class="emphasis"><em>
EnabledControls</em></span>
 control; enable and disable them upon program exit by configuring the
<span class="emphasis"><em>
AutoReset</em></span>
 control.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_EnabledControls_Control"></a>The EnabledControls Control</h3></div></div></div><p>
The <span class="emphasis"><em>
EnabledControls</em></span>
 control is a bit mask where each bit that is turned on means the corresponding
control is enabled, and when turned off, disabled. It corresponds to the
<span class="emphasis"><em>
enabled_ctrls</em></span>
 field of an <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure (see section 10.8). The bits describing which controls are turned on
or off are defined in Table 10.7. 
</p><p>
Use <span class="emphasis"><em>
XkbChangeEnabledControls</em></span>
 to manipulate the <span class="emphasis"><em>
EnabledControls</em></span>
 control.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbChangeEnabledControls</em></span>
(<span class="emphasis"><em>
dpy</em></span>
, <span class="emphasis"><em>
device_spec</em></span>
, <span class="emphasis"><em>
mask</em></span>
,<span class="emphasis"><em>
 values</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
device_spec</em></span>
;            /* keyboard device to modify */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
mask</em></span>
;            /* 1 bit -&gt; controls to enable / disable */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
values</em></span>
;            /* 1 bit =&gt; enable, 0 bit =&gt; disable */
    </td></tr></tbody></table></div><p>
The <span class="emphasis"><em>
mask</em></span>
 parameter specifies the boolean controls to be enabled or disabled, and the
<span class="emphasis"><em>
values</em></span>
 mask specifies the new state for those controls. Valid values for both of
these masks are composed of a bitwise inclusive OR of bits taken from the set
of mask bits in Table 10.7, using only those masks with "ok" in the <span class="emphasis"><em>
enabled_ctrls</em></span>
 column.
</p><p>
If the X server does not support a compatible version of Xkb or the Xkb
extension has not been properly initialized, <span class="emphasis"><em>
XkbChangeEnabledControls</em></span>
 returns <span class="emphasis"><em>
False</em></span>
; otherwise, it sends the request to the X server and returns <span class="emphasis"><em>
True</em></span>
.
</p><p>
Note that the <span class="emphasis"><em>
EnabledControls</em></span>
 control only enables and disables controls; it does not configure them. Some
controls, such as the <span class="emphasis"><em>
AudibleBell</em></span>
 control, have no configuration attributes and are therefore manipulated solely
by enabling and disabling them. Others, however, have additional attributes to
configure their behavior. For example, the <span class="emphasis"><em>
RepeatControl</em></span>
 control uses <span class="emphasis"><em>
repeat_delay</em></span>
 and <span class="emphasis"><em>
repeat_interval</em></span>
 fields to describe the timing behavior of keys that repeat. The <span class="emphasis"><em>
RepeatControl</em></span>
 behavior is turned on or off depending on the value of the <span class="emphasis"><em>
XkbRepeatKeysMask</em></span>
 bit, but you must use other means, as described in this chapter, to configure
its behavior in detail.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_AutoReset_Control"></a>The AutoReset Control</h3></div></div></div><p>
You can configure the boolean controls to automatically be enabled or disabled
when a program exits. This capability is controlled via two masks maintained in
the X server on a per-client basis. There is no client-side Xkb data structure
corresponding to these masks. Whenever the client exits for any reason, any
boolean controls specified in the <span class="emphasis"><em>
auto-reset mask</em></span>
 are set to the corresponding value from the <span class="emphasis"><em>
auto-reset values</em></span>
 mask. This makes it possible for clients to "clean up after themselves"
automatically, even if abnormally terminated. The bits used in the masks
correspond to the <span class="emphasis"><em>
EnabledControls</em></span>
 control bits.
</p><p>
For example, a client that replaces the keyboard bell with some other audible
cue might want to turn off the <span class="emphasis"><em>
AudibleBell</em></span>
 control to prevent the server from also generating a sound and avoid
cacophony. If the client were to exit without resetting the <span class="emphasis"><em>
AudibleBell </em></span>
control, the user would be left without any feedback at all. Setting <span class="emphasis"><em>
AudibleBell</em></span>
 in both the auto-reset mask and auto-reset values guarantees that the audible
bell will be turned back on when the client exits.
</p><p>
To get the current values of the auto-reset controls, use <span class="emphasis"><em>
XkbGetAutoResetControls</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbGetAutoResetControls</em></span>
(<span class="emphasis"><em>
dpy</em></span>
, <span class="emphasis"><em>
auto_ctrls</em></span>
, <span class="emphasis"><em>
auto_values</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            <span class="emphasis"><em>
dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int *            <span class="emphasis"><em>
auto_ctrls</em></span>
;            /* specifies which bits in <span class="emphasis"><em>
auto_values</em></span>
 are relevant */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int *            <span class="emphasis"><em>
auto_values</em></span>
;            /* 1 bit =&gt; corresponding control has auto-reset on */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetAutoResetControls</em></span>
 backfills <span class="emphasis"><em>
auto_ctrls</em></span>
 and <span class="emphasis"><em>
auto_values</em></span>
 with the <span class="emphasis"><em>
AutoReset</em></span>
 control attributes for this particular client. It returns <span class="emphasis"><em>
True</em></span>
 if successful, and <span class="emphasis"><em>
False</em></span>
 otherwise.
</p><p>
To change the current values of the <span class="emphasis"><em>
AutoReset</em></span>
 control attributes, use <span class="emphasis"><em>
XkbSetAutoResetControls.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSetAutoResetControls</em></span>
(<span class="emphasis"><em>
dpy</em></span>
, <span class="emphasis"><em>
changes</em></span>
,<span class="emphasis"><em>
 auto_ctrls</em></span>
, <span class="emphasis"><em>
auto_values</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            <span class="emphasis"><em>
dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
changes</em></span>
;            /* controls for which to change auto-reset values */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int *            <span class="emphasis"><em>
auto_ctrls</em></span>
;            /* controls from changes that should auto reset */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int *            <span class="emphasis"><em>
auto_values</em></span>
;            /* 1 bit =&gt; auto-reset on */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSetAutoResetControls changes the auto-reset status and associated auto-reset
values for the controls selected by </em></span>
<span class="emphasis"><em>
changes</em></span>
<span class="emphasis"><em>
. For any control selected by </em></span>
<span class="emphasis"><em>
changes</em></span>
<span class="emphasis"><em>
, if the corresponding bit is set in </em></span>
<span class="emphasis"><em>
auto_ctrls</em></span>
<span class="emphasis"><em>
, the control is configured to auto-reset when the client exits. If the
corresponding bit in </em></span>
<span class="emphasis"><em>
auto_values</em></span>
<span class="emphasis"><em>
 is on, the control is turned on when the client exits; if zero, the control is
turned off when the client exits.</em></span>
 For any control selected by <span class="emphasis"><em>
changes</em></span>
, if the corresponding bit is not set in <span class="emphasis"><em>
auto_ctrls</em></span>
, the control is configured to not reset when the client exits. For example:
</p><p>
<span class="emphasis"><em>
To leave the auto-reset controls for </em></span>
<span class="emphasis"><em>
StickyKeys</em></span>
<span class="emphasis"><em>
 the way they are:</em></span>
</p><pre class="programlisting">
ok = XkbSetAutoResetControls(dpy, 0, 0, 0);
</pre><p>
<span class="emphasis"><em>
To change the auto-reset controls so that </em></span>
<span class="emphasis"><em>
StickyKeys</em></span>
<span class="emphasis"><em>
 are unaffected when the client exits:</em></span>
</p><pre class="programlisting">
ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, 0, 0);
</pre><p>
<span class="emphasis"><em>
To change the auto-reset controls so that </em></span>
<span class="emphasis"><em>
StickyKeys</em></span>
<span class="emphasis"><em>
 are turned off when the client exits:</em></span>
</p><pre class="programlisting">
ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask, 0);
</pre><p>
<span class="emphasis"><em>
To change the auto-reset controls so that </em></span>
<span class="emphasis"><em>
StickyKeys</em></span>
<span class="emphasis"><em>
 are turned on when the client exits:</em></span>
</p><pre class="programlisting">
ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask,
XkbStickyKeysMask);
</pre><p>
<span class="emphasis"><em>
XkbSetAutoResetControls</em></span>
 backfills <span class="emphasis"><em>
auto_ctrls</em></span>
 and <span class="emphasis"><em>
auto_values</em></span>
 with the auto-reset controls for this particular client. Note that all of the
bits are valid in the returned values, not just the ones selected in the
<span class="emphasis"><em>
changes</em></span>
 mask.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Control_for_Bell_Behavior"></a>Control for Bell Behavior</h2></div></div></div><p>
The X server’s generation of sounds is controlled by the <span class="emphasis"><em>
AudibleBell</em></span>
 control. Configuration of different bell sounds is discussed in Chapter 9.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_AudibleBell_Control"></a>The AudibleBell Control</h3></div></div></div><p>
The <span class="emphasis"><em>
AudibleBell</em></span>
 control is a boolean control that has no attributes. As such, you may enable
and disable it using either the <span class="emphasis"><em>
EnabledControls</em></span>
 control or the <span class="emphasis"><em>
AutoReset</em></span>
 control discussed in section 10.1.1. When enabled, protocol requests to  
generate a sound result in the X server actually producing a real sound; when
disabled, requests to the server to generate a sound are ignored unless the
sound is forced. See section 9.2. 
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Controls_for_Repeat_Key_Behavior"></a>Controls for Repeat Key Behavior</h2></div></div></div><p>
The repeating behavior of keyboard keys is governed by three controls, the
<span class="emphasis"><em>
PerKeyRepeat</em></span>
 control, which is always active, and the <span class="emphasis"><em>
RepeatKeys</em></span>
 and <span class="emphasis"><em>
DetectableAutorepeat</em></span>
 controls, which are boolean controls that may be enabled and disabled.
<span class="emphasis"><em>
PerKeyRepeat</em></span>
 determines which keys are allowed to repeat. <span class="emphasis"><em>
RepeatKeys</em></span>
 governs the behavior of an individual key when it is repeating. <span class="emphasis"><em>
DetectableAutorepeat</em></span>
 allows a client to detect when a key is repeating as a result of being held
down.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_PerKeyRepeat_Control"></a>The PerKeyRepeat Control</h3></div></div></div><p>
The <span class="emphasis"><em>
PerKeyRepeat</em></span>
 control is a bitmask long enough to contain a bit for each key on the device;
it determines which individual keys are allowed to repeat. The Xkb <span class="emphasis"><em>
PerKeyRepeat</em></span>
 control provides no functionality different from that available via the core X
protocol. There are no convenience functions in Xkb for manipulating this
control. The <span class="emphasis"><em>
PerKeyRepeat</em></span>
 control settings are carried in the <span class="emphasis"><em>
per_key_repeat</em></span>
 field of an <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure, discussed in section 10.8. 
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_RepeatKeys_Control"></a>The RepeatKeys Control</h3></div></div></div><p>
The core protocol allows only control over whether or not the entire keyboard
or individual keys should auto-repeat when held down. <span class="emphasis"><em>
RepeatKeys</em></span>
 is a boolean control that extends this capability by adding control over the
delay until a key begins to repeat and the rate at which it repeats. <span class="emphasis"><em>
RepeatKeys</em></span>
 is coupled with the core auto-repeat control: when <span class="emphasis"><em>
RepeatKeys</em></span>
 is enabled or disabled, the core auto-repeat is enabled or disabled and vice
versa.
</p><p>
Auto-repeating keys are controlled by two attributes. The first, <span class="emphasis"><em>
timeout</em></span>
, is the delay after the initial press of an auto-repeating key and the first
generated repeat event. The second, <span class="emphasis"><em>
interval</em></span>
, is the delay between all subsequent generated repeat events. As with all
boolean controls, configuring the attributes that determine how the control
operates does not automatically enable the control as a whole; see section 10.1.
</p><p>
To get the current attributes of the <span class="emphasis"><em>
RepeatKeys</em></span>
 control for a keyboard device, use <span class="emphasis"><em>
XkbGetAutoRepeatRate</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbGetAutoRepeatRate</em></span>
(<span class="emphasis"><em>
display, device_spec, timeout_rtrn, interval_rtrn</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            display</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
      device_spec</em></span>
;            /* desired device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int <span class="emphasis"><em>
*            timeout_rtrn</em></span>
;            /* backfilled with initial repeat delay, ms */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int <span class="emphasis"><em>
*            interval_rtrn</em></span>
;            /* backfilled with subsequent repeat delay, ms */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetAutoRepeatRate</em></span>
 queries the server for the current values of the <span class="emphasis"><em>
RepeatControls</em></span>
 control attributes, backfills <span class="emphasis"><em>
timeout_rtrn</em></span>
 and <span class="emphasis"><em>
interval_rtrn</em></span>
 with them, and returns <span class="emphasis"><em>
True</em></span>
. If a compatible version of the Xkb extension is not available in the server
<span class="emphasis"><em>
XkbGetAutoRepeatRate</em></span>
 returns <span class="emphasis"><em>
False</em></span>
.
</p><p>
To set the attributes of the RepeatKeys control for a keyboard device, use
<span class="emphasis"><em>
XkbSetAutoRepeatRate</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSetAutoRepeatRate</em></span>
(<span class="emphasis"><em>
display, device_spec, timeout, interval</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            display</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
device_spec</em></span>
;            /* device to configure, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
            timeout</em></span>
;            /* initial delay, ms */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
      interval</em></span>
;            /* delay between repeats, ms */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSetAutoRepeatRate</em></span>
 sends a request to the X server to configure the <span class="emphasis"><em>
AutoRepeat</em></span>
 control attributes to the values specified in <span class="emphasis"><em>
timeout</em></span>
 and <span class="emphasis"><em>
interval</em></span>
.
</p><p>
<span class="emphasis"><em>
XkbSetAutoRepeatRate</em></span>
 does not wait for a reply; it normally returns <span class="emphasis"><em>
True</em></span>
. Specifying a zero value for either <span class="emphasis"><em>
timeout</em></span>
 or <span class="emphasis"><em>
interval</em></span>
 causes the server to generate a <span class="emphasis"><em>
BadValue</em></span>
 protocol error. If a compatible version of the Xkb extension is not available
in the server, <span class="emphasis"><em>
XkbSetAutoRepeatRate</em></span>
 returns <span class="emphasis"><em>
False</em></span>
.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_DetectableAutorepeat_Control"></a>The DetectableAutorepeat Control</h3></div></div></div><p>
Auto-repeat is the generation of multiple key events by a keyboard when the
user presses a key and holds it down. Keyboard hardware and device-dependent X
server software often implement auto-repeat by generating multiple <span class="emphasis"><em>
KeyPress</em></span>
 events with no intervening <span class="emphasis"><em>
KeyRelease</em></span>
 event. The standard behavior of the X server is to generate a <span class="emphasis"><em>
KeyRelease</em></span>
 event for every <span class="emphasis"><em>
KeyPress</em></span>
 event. If the keyboard hardware and device-dependent software of the X server
implement auto-repeat by generating multiple <span class="emphasis"><em>
KeyPress</em></span>
 events, the device-independent part of the X server by default synthetically
generates a <span class="emphasis"><em>
KeyRelease</em></span>
 event after each <span class="emphasis"><em>
KeyPress</em></span>
 event. This provides predictable behavior for X clients, but does not allow
those clients to detect the fact that a key is auto-repeating.
</p><p>
Xkb allows clients to request <span class="emphasis"><em>
detectable auto-repeat</em></span>
. If a client requests and the server supports <span class="emphasis"><em>
DetectableAutorepeat</em></span>
, Xkb generates <span class="emphasis"><em>
KeyRelease</em></span>
 events only when the key is physically released. If <span class="emphasis"><em>
DetectableAutorepeat</em></span>
 is not supported or has not been requested, the server synthesizes a <span class="emphasis"><em>
KeyRelease</em></span>
 event for each repeating <span class="emphasis"><em>
KeyPress</em></span>
 event it generates.
</p><p>
<span class="emphasis"><em>
DetectableAutorepeat</em></span>
, unlike the other controls in this chapter, is not contained in the <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure, nor can it be enabled or disabled via the <span class="emphasis"><em>
EnabledControls</em></span>
 control. Instead, query and set <span class="emphasis"><em>
DetectableAutorepeat</em></span>
 using <span class="emphasis"><em>
XkbGetDetectableAutorepeat</em></span>
 and <span class="emphasis"><em>
XkbSetDetectableAutorepeat</em></span>
.
</p><p>
<span class="emphasis"><em>
DetectableAutorepeat</em></span>
 is a condition that applies to all keyboard devices for a client’s
connection to a given X server; it cannot be selectively set for some devices
and not for others. For this reason, none of the Xkb library functions
involving <span class="emphasis"><em>
DetectableAutorepeat</em></span>
 involve a device specifier.
</p><p>
To determine whether or not the server supports <span class="emphasis"><em>
DetectableAutorepeat</em></span>
, use <span class="emphasis"><em>
XkbGetDetectableAutorepeat</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbGetDetectableAutorepeat</em></span>
(<span class="emphasis"><em>
display, supported_rtrn</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
      display</em></span>
;                  /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool *<span class="emphasis"><em>
      supported_rtrn</em></span>
;                   /* backfilled <span class="emphasis"><em>
True</em></span>
 if <span class="emphasis"><em>
DetectableAutorepeat</em></span>
 supported */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetDetectableAutorepeat</em></span>
 queries the server for the current state of <span class="emphasis"><em>
DetectableAutorepeat</em></span>
 and waits for a reply. If <span class="emphasis"><em>
supported_rtrn</em></span>
 is not <span class="emphasis"><em>
NULL</em></span>
, it backfills supported_rtrn with <span class="emphasis"><em>
True</em></span>
 if the server supports <span class="emphasis"><em>
DetectableAutorepeat</em></span>
, and <span class="emphasis"><em>
False</em></span>
 otherwise. <span class="emphasis"><em>
XkbGetDetectableAutorepeat</em></span>
 returns the current state of <span class="emphasis"><em>
DetectableAutorepeat</em></span>
 for the requesting client: <span class="emphasis"><em>
True</em></span>
 if <span class="emphasis"><em>
DetectableAutorepeat</em></span>
 is set, and <span class="emphasis"><em>
False</em></span>
 otherwise.
</p><p>
To set <span class="emphasis"><em>
DetectableAutorepeat</em></span>
, use <span class="emphasis"><em>
XkbSetDetectableAutorepeat</em></span>
. This request affects all keyboard activity for the requesting client only;
other clients still see the expected nondetectable auto-repeat behavior, unless
they have requested otherwise.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSetDetectableAutorepeat</em></span>
(<span class="emphasis"><em>
display, detectable, supported_rtrn</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
      display</em></span>
;                  /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool<span class="emphasis"><em>
      detectable</em></span>
;                  /* <span class="emphasis"><em>
True</em></span>
 =&gt; set <span class="emphasis"><em>
DetectableAutorepeat</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool *<span class="emphasis"><em>
      supported_rtrn</em></span>
;                   /* backfilled <span class="emphasis"><em>
True</em></span>
 if <span class="emphasis"><em>
DetectableAutorepeat</em></span>
 supported */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSetDetectableAutorepeat</em></span>
 sends a request to the server to set <span class="emphasis"><em>
DetectableAutorepeat</em></span>
 on for the current client if <span class="emphasis"><em>
detectable</em></span>
 is <span class="emphasis"><em>
True</em></span>
, and off it <span class="emphasis"><em>
detectable</em></span>
 is <span class="emphasis"><em>
False</em></span>
; it then waits for a reply. If <span class="emphasis"><em>
supported_rtrn</em></span>
 is not <span class="emphasis"><em>
NULL</em></span>
, <span class="emphasis"><em>
XkbSetDetectableAutorepeat</em></span>
 backfills <span class="emphasis"><em>
supported_rtrn</em></span>
 with <span class="emphasis"><em>
True</em></span>
 if the server supports <span class="emphasis"><em>
DetectableAutorepeat</em></span>
, and <span class="emphasis"><em>
False</em></span>
 if it does not. <span class="emphasis"><em>
XkbSetDetectableAutorepeat</em></span>
 returns the current state of <span class="emphasis"><em>
DetectableAutorepeat</em></span>
 for the requesting client: <span class="emphasis"><em>
True</em></span>
 if <span class="emphasis"><em>
DetectableAutorepeat</em></span>
 is set, and <span class="emphasis"><em>
False</em></span>
 otherwise.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Controls_for_Keyboard_Overlays_Overlay1_and_Overlay2_Controls"></a>Controls for Keyboard Overlays (Overlay1 and Overlay2 Controls)</h2></div></div></div><p>
A keyboard overlay allows some subset of the keyboard to report alternate
keycodes when the overlay is enabled. For example, a keyboard overlay can be
used to simulate a numeric or editing keypad on a keyboard that does not
actually have one by reusing some portion of the keyboard as an overlay. This
technique is very common on portable computers and embedded systems with small
keyboards.
</p><p>
Xkb includes direct support for two keyboard overlays, using the <span class="emphasis"><em>
Overlay1</em></span>
 and <span class="emphasis"><em>
Overlay2</em></span>
 controls. When <span class="emphasis"><em>
Overlay1</em></span>
 is enabled, all of the keys that are members of the first keyboard overlay
generate an alternate keycode. When <span class="emphasis"><em>
Overlay2</em></span>
 is enabled, all of the keys that are members of the second keyboard overlay
generate an alternate keycode. The two overlays are mutually exclusive; any
particular key may be in at most one overlay. <span class="emphasis"><em>
Overlay1</em></span>
 and <span class="emphasis"><em>
Overlay2</em></span>
 are boolean controls. As such, you may enable and disable them using either
the <span class="emphasis"><em>
EnabledControls</em></span>
 control or the <span class="emphasis"><em>
AutoReset</em></span>
 control discussed in section 10.1.1.  
</p><p>
To specify the overlay to which a key belongs and the alternate keycode it
should generate when that overlay is enabled, assign it either the <span class="emphasis"><em>
XkbKB_Overlay1</em></span>
 or <span class="emphasis"><em>
XkbKB_Overlay2</em></span>
 key behaviors, as described in section 16.2. 
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Controls_for_Using_the_Mouse_from_the_Keyboard"></a>Controls for Using the Mouse from the Keyboard</h2></div></div></div><p>
Using Xkb, it is possible to configure the keyboard to allow simulation of the
X pointer device. This simulation includes both movement of the pointer itself
and press and release events associated with the buttons on the pointer. Two
controls affect this behavior: the <span class="emphasis"><em>
MouseKeys</em></span>
 control determines whether or not simulation of the pointer device is active,
as well as configuring the default button; the <span class="emphasis"><em>
MouseKeysAccel</em></span>
 control determines the movement characteristics of the pointer when simulated
via the keyboard. Both of them are boolean controls; as such, you may enable
and disable them using either the <span class="emphasis"><em>
EnabledControls</em></span>
 control or the <span class="emphasis"><em>
AutoReset</em></span>
 control discussed in section 10.1.1. The individual keys that simulate  
different aspects of the pointer device are determined by the keyboard mapping,
discussed in Chapter 16. 
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_MouseKeys_Control"></a>The MouseKeys Control</h3></div></div></div><p>
The <span class="emphasis"><em>
MouseKeys</em></span>
 control allows a user to control all the mouse functions from the keyboard.
When <span class="emphasis"><em>
MouseKeys</em></span>
 are enabled, all keys with <span class="emphasis"><em>
MouseKeys</em></span>
 actions bound to them generate core pointer events instead of normal <span class="emphasis"><em>
KeyPress</em></span>
 and <span class="emphasis"><em>
KeyRelease</em></span>
 events.
</p><p>
The <span class="emphasis"><em>
MouseKeys</em></span>
 control has a single attribute, <span class="emphasis"><em>
mk_dflt_btn</em></span>
 that specifies the core button number to be used by mouse keys actions that do
not explicitly specify a button. There is no convenience function for getting
or setting the attribute; instead use <span class="emphasis"><em>
XkbGetControls</em></span>
 and <span class="emphasis"><em>
XkbSetControls</em></span>
 (see sections 10.9 and 10.10). 
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p><span class="emphasis"><em>
MouseKeys</em></span>
 can also be turned on and off by pressing the key combination necessary to
produce an <span class="emphasis"><em>
XK_Pointer_EnableKeys</em></span>
 keysym. The de facto default standard for this is <span class="emphasis"><em>
Shift+Alt+NumLock</em></span>
, but this may vary depending on the keymap.</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_MouseKeysAccel_Control"></a>The MouseKeysAccel Control</h3></div></div></div><p>
When the <span class="emphasis"><em>
MouseKeysAccel</em></span>
 control is enabled, the effect of a key-activated pointer motion action
changes as a key is held down. If the control is disabled, pressing a
mouse-pointer key yields one mouse event. When <span class="emphasis"><em>
MouseKeysAccel</em></span>
 is enabled, mouse movement is defined by an initial distance specified in the
<span class="emphasis"><em>
XkbSA_MovePtr</em></span>
 action and the following fields in the <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure (see section 10.8). 
</p><div class="table"><a id="idp65792732"></a><p class="title"><strong>Table 10.2. MouseKeysAccel Fields</strong></p><div class="table-contents"><table summary="MouseKeysAccel Fields" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Field</th><th align="left">Function</th></tr></thead><tbody><tr><td align="left">mk_delay</td><td align="left">Time (ms) between the initial key press and the first repeated
motion event</td></tr><tr><td align="left">mk_interval</td><td align="left">Time (ms) between repeated motion events</td></tr><tr><td align="left">mk_time_to_max</td><td align="left">Number of events (count) before the pointer reaches maximum
speed</td></tr><tr><td align="left">mk_max_speed</td><td align="left">The maximum speed (in pixels per event) the pointer reaches</td></tr><tr><td align="left">mk_curve</td><td align="left">The ramp used to reach maximum pointer speed</td></tr></tbody></table></div></div><br class="table-break" /><p>
There are no convenience functions to query or change the attributes of the
<span class="emphasis"><em>
MouseKeysAccel</em></span>
 control; instead use <span class="emphasis"><em>
XkbGetControls</em></span>
 and <span class="emphasis"><em>
XkbSetControls</em></span>
 (see sections 10.9 and 10.10). 
</p><p>
The effects of the attributes of the <span class="emphasis"><em>
MouseKeysAccel</em></span>
 control depend on whether the <span class="emphasis"><em>
XkbSA_MovePtr</em></span>
 action (see section 16.1) specifies relative or absolute pointer motion. 
</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Absolute_Pointer_Motion"></a>Absolute Pointer Motion</h4></div></div></div><p>
If an <span class="emphasis"><em>
XkbSA_MovePtr</em></span>
 action specifies an absolute position for one of the coordinates but still
allows acceleration, all repeated events contain any absolute coordinates
specified in the action. For example, if the <span class="emphasis"><em>
XkbSA_MovePtr</em></span>
 action specifies an absolute position for the X direction, but a relative
motion for the Y direction, the pointer accelerates in the Y direction, but
stays at the same X position.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Relative_Pointer_Motion"></a>Relative Pointer Motion</h4></div></div></div><p>
If the <span class="emphasis"><em>
XkbSA_MovePtr</em></span>
 action specifies relative motion, the initial event always moves the cursor
the distance specified in the action. After <span class="emphasis"><em>
mk_delay</em></span>
 milliseconds, a second motion event is generated, and another occurs every
<span class="emphasis"><em>
mk_interval</em></span>
 milliseconds until the user releases the key.
</p><p>
Between the time of the second motion event and <span class="emphasis"><em>
mk_time_to_max</em></span>
 intervals, the change in pointer distance per interval increases with each
interval. After <span class="emphasis"><em>
mk_time_to_max</em></span>
 intervals have elapsed, the change in pointer distance per interval remains
the same and is calculated by multiplying the original distance specified in
the action by <span class="emphasis"><em>
mk_max_speed</em></span>
.
</p><p>
For example, if the <span class="emphasis"><em>
XkbSA_MovePtr</em></span>
 action specifies a relative motion in the X direction of 5, <span class="emphasis"><em>
mk_delay</em></span>
=160, <span class="emphasis"><em>
mk_interval</em></span>
=40, <span class="emphasis"><em>
mk_time_to_max</em></span>
=30, and <span class="emphasis"><em>
mk_max_speed</em></span>
=30, the following happens when the user presses the key:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The pointer immediately moves 5 pixels in the X direction when the key is
pressed.
  </p></li><li class="listitem"><p>
After 160 milliseconds (<span class="emphasis"><em>
mk_delay</em></span>
), and every 40 milliseconds thereafter (<span class="emphasis"><em>
mk_interval</em></span>
), the pointer moves in the X direction.
  </p></li><li class="listitem"><p>
The distance in the X direction increases with each interval until 30 intervals
(<span class="emphasis"><em>
mk_time_to_max</em></span>
) have elapsed.
  </p></li><li class="listitem"><p>
After 30 intervals, the pointer stops accelerating, and moves 150 pixels
(<span class="emphasis"><em>
mk_max_speed</em></span>
 * the original distance) every interval thereafter, until the key is released.
  </p></li></ul></div><p>
The increase in pointer difference for each interval is a function of<span class="emphasis"><em>
 mk_curve.</em></span>
 Events after the first but before maximum acceleration has been achieved are
accelerated according to the formula:
</p><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-3.svg"></object></div><p>
Where <span class="emphasis"><em>
action_delta</em></span>
 is the relative motion specified by the <span class="emphasis"><em>
XkbSA_MovePtr</em></span>
 action, <span class="emphasis"><em>
mk_max_speed </em></span>
and <span class="emphasis"><em>
mk_time_to_max</em></span>
 are parameters to the <span class="emphasis"><em>
MouseKeysAccel</em></span>
 control, and the curveFactor is computed using the <span class="emphasis"><em>
MouseKeysAccel</em></span>
 <span class="emphasis"><em>
mk_curve</em></span>
 parameter as follows:
</p><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-4.svg"></object></div><p>
With the result that a <span class="emphasis"><em>
mk_curve</em></span>
 of zero causes the distance moved to increase linearly from <span class="emphasis"><em>
action_delta</em></span>
 to </p><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-5.svg"></object></div><p>

. A negative <span class="emphasis"><em>
mk_curve</em></span>
 causes an initial sharp increase in acceleration that tapers off, and a
positive curve yields a slower initial increase in acceleration followed by a
sharp increase as the number of pointer events generated by the action
approaches <span class="emphasis"><em>
mk_time_to_max</em></span>
. The legal values for <span class="emphasis"><em>
mk_curve</em></span>
 are between -1000 and 1000.
</p><p>
A distance vs. time graph of the pointer motion is shown in Figure 10.1. 
</p><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-6.svg"></object><div class="caption">MouseKeys Acceleration</div></div></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Controls_for_Better_Keyboard_Access_by_Physically_ImpairedPersons"></a>Controls for Better Keyboard Access by Physically Impaired
Persons</h2></div></div></div><p>
The Xkb extension includes several controls specifically aimed at making
keyboard use more effective for physically impaired people. All of these
controls are boolean controls and may be individually enabled and disabled, as
well as configured to tune their specific behavior. The behavior of these
controls is based on the AccessDOS package
<a href="#ftn.idp65821500" class="footnote" id="idp65821500"><sup class="footnote">[4]</sup></a>.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_AccessXKeys_Control"></a>The AccessXKeys Control</h3></div></div></div><p>
Enabling or disabling the keyboard controls through a graphical user interface
may be impossible for people who need to use the controls. For example, a user
who needs <span class="emphasis"><em>
SlowKeys</em></span>
 (see section 10.6.6) may not even be able to start the graphical application,  
let alone use it, if <span class="emphasis"><em>
SlowKeys</em></span>
 is not enabled. To allow easier access to some of the controls, the <span class="emphasis"><em>
AccessXKeys</em></span>
 control provides a set of special key sequences similar to those available in
AccessDOS.
</p><p>
When the <span class="emphasis"><em>
AccessXKeys</em></span>
 control is enabled, the user can turn controls on or off from the keyboard by
entering the following standard key sequences:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Holding down a shift key by itself for eight seconds toggles the <span class="emphasis"><em>
SlowKeys</em></span>
 control.
  </p></li><li class="listitem"><p>
Pressing and releasing the left or right <span class="emphasis"><em>
Shift</em></span>
 key five times in a row, without any intervening key events and with less than
30 seconds delay between consecutive presses, toggles the state of the
<span class="emphasis"><em>
StickyKeys</em></span>
 control.
  </p></li><li class="listitem"><p>
Simultaneously operating two or more modifier keys deactivates the <span class="emphasis"><em>
StickyKeys</em></span>
 control.
  </p></li></ul></div><p>
When the <span class="emphasis"><em>
AccessXKeys</em></span>
 control is disabled, Xkb does not look for the above special key sequences.
</p><p>
Some of these key sequences optionally generate audible feedback of the change
in state, as described in section 10.6.3, or  
<span class="emphasis"><em>XkbControlsNotify</em></span>
 events, described in section 10.11. 
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_AccessXTimeout_Control"></a>The AccessXTimeout Control</h3></div></div></div><p>
In environments where computers are shared, features such as <span class="emphasis"><em>
SlowKeys</em></span>
 present a problem: if <span class="emphasis"><em>
SlowKeys</em></span>
 is on, the keyboard can appear to be unresponsive because keys are not
accepted until they are held for a certain period of time. To help solve this
problem, Xkb provides an <span class="emphasis"><em>
AccessXTimeout</em></span>
 control to automatically change the enabled/disabled state of any boolean
controls and to change the value of the <span class="emphasis"><em>
AccessXKeys</em></span>
 and <span class="emphasis"><em>
AccessXFeedback</em></span>
 control attributes if the keyboard is idle for a specified period of time.
</p><p>
When a timeout as specified by <span class="emphasis"><em>
AccessXTimeout</em></span>
 occurs and a control is consequently modified, Xkb generates an <span class="emphasis"><em>
XkbControlsNotify</em></span>
 event. For more information on <span class="emphasis"><em>
XkbControlsNotify</em></span>
 events, refer to section 10.11. 
</p><p>
Use <span class="emphasis"><em>
XkbGetAccessXTimeout</em></span>
 to query the current <span class="emphasis"><em>
AccessXTimeout</em></span>
 options for a keyboard device.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbGetAccessXTimeout</em></span>
(<span class="emphasis"><em>
display</em></span>
,<span class="emphasis"><em>
 device_spec</em></span>
,<span class="emphasis"><em>
 timeout_rtrn</em></span>
,<span class="emphasis"><em>
 ctrls_mask_rtrn</em></span>
,<span class="emphasis"><em>
 ctrls_values_rtrn</em></span>
,<span class="emphasis"><em>
 options_mask_rtrn, options_values_rtrn</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
      display</em></span>
;                  /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
device_spec</em></span>
;                  /* device to query, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned short *      <span class="emphasis"><em>
timeout_rtrn</em></span>
;                  /* delay until AccessXTimeout, seconds */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int *<span class="emphasis"><em>
      ctrls_mask_rtrn</em></span>
;                  /* backfilled with controls to modify */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int *      <span class="emphasis"><em>
ctrls_values_rtrn</em></span>
;                  /* backfilled with on/off status for controls */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned short *      <span class="emphasis"><em>
opts_mask_rtrn</em></span>
;                  /* backfilled with <span class="emphasis"><em>
ax_options</em></span>
 to modify */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned short *      <span class="emphasis"><em>
opts_values_rtrn</em></span>
;                  /* backfilled with values for <span class="emphasis"><em>
ax_options</em></span>
 */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetAccessXTimeout</em></span>
 sends a request to the X server to obtain the current values for the <span class="emphasis"><em>
AccessXTimeout</em></span>
 attributes, waits for a reply, and backfills the values into the appropriate
arguments.<span class="emphasis"><em>
 </em></span>
The parameters <span class="emphasis"><em>
opts_mask_rtrn</em></span>
 and <span class="emphasis"><em>
opts_values_rtrn</em></span>
 are backfilled with the options to modify and the values for <span class="emphasis"><em>
ax_options</em></span>
, which is a field in the
<span class="emphasis"><em>XkbControlsRec</em></span>
 structure (see section 10.8).  
<span class="emphasis"><em>
XkbGetAccessXTimeout </em></span>
returns<span class="emphasis"><em>
 </em></span>
<span class="emphasis"><em>
True</em></span>
 if successful; if a compatible version of the Xkb extension is not available
in the server, <span class="emphasis"><em>
XkbGetAccessXTimeout</em></span>
 returns <span class="emphasis"><em>
False</em></span>
.
</p><p>
To configure the <span class="emphasis"><em>
AccessXTimeout</em></span>
 options for a keyboard device, use <span class="emphasis"><em>
XkbSetAccessXTimeout</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSetAccessXTimeout</em></span>
(<span class="emphasis"><em>
display</em></span>
,<span class="emphasis"><em>
 device_spec, timeout, ctrls_mask, ctrls_values, opts_mask,
opts_values</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
      display</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      device_spec</em></span>
;            /* device to configure, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned short      <span class="emphasis"><em>
timeout</em></span>
;            /* seconds idle until AccessXTimeout occurs */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      ctrls_mask</em></span>
;            /* boolean controls to modify */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      ctrls_values</em></span>
;            /* new bits for controls selected by <span class="emphasis"><em>
ctrls_mask</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned short      <span class="emphasis"><em>
opts_mask</em></span>
;            /* <span class="emphasis"><em>
ax_options</em></span>
 to change */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned short      <span class="emphasis"><em>
opts_values</em></span>
;            /* new bits for <span class="emphasis"><em>
ax_options</em></span>
 selected by <span class="emphasis"><em>
opts_mask</em></span>
 */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
timeout</em></span>
 specifies the number of seconds the keyboard must be idle before the controls
are modified. <span class="emphasis"><em>
ctrls_mask</em></span>
 specifies what controls are to be enabled or disabled, and <span class="emphasis"><em>
ctrls_values</em></span>
 specifies whether those controls are to be enabled or disabled. The bit values
correspond to those for enabling and disabling boolean controls (see section
10.1.1). The <span class="emphasis"><em>
opts_mask</em></span>
 field specifies which attributes of the <span class="emphasis"><em>
AccessXKeys</em></span>
 and <span class="emphasis"><em>
AccessXFeedback</em></span>
 controls are to be changed, and <span class="emphasis"><em>
opts_values</em></span>
 specifies the new values for those options. The bit values correspond to those
for the <span class="emphasis"><em>
ax_options</em></span>
 field of an <span class="emphasis"><em>
XkbDescRec</em></span>
 (see section 10.8). 
</p><p>
<span class="emphasis"><em>
XkbSetAccessXTimeout</em></span>
 sends a request to configure the <span class="emphasis"><em>
AccessXTimeout</em></span>
 control to the server.<span class="emphasis"><em>
 </em></span>
It does not wait for a reply, and normally returns <span class="emphasis"><em>
True</em></span>
. If a compatible version of the Xkb extension is not available in the server,
<span class="emphasis"><em>
XkbSetAccessXTimeout</em></span>
 returns <span class="emphasis"><em>
False</em></span>
.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_AccessXFeedback_Control"></a>The AccessXFeedback Control</h3></div></div></div><p>
Just as some keyboards can produce keyclicks to indicate when a key is pressed
or repeating, Xkb can provide feedback for the controls by using special beep
codes. Use the <span class="emphasis"><em>
AccessXFeedback</em></span>
 control to configure the specific types of operations that generate feedback.
</p><p>
There is no convenience function for modifying the <span class="emphasis"><em>
AccessXFeedback</em></span>
 control, although the feedback as a whole can be enabled or disabled just as
other boolean controls are (see section 10.1). Individual beep codes are turned
on or off by modifying the following bits in the <span class="emphasis"><em>
ax_options</em></span>
 field of an <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure and using <span class="emphasis"><em>
XkbSetControls</em></span>
 (see section 10.10): 
</p><div class="table"><a id="idp65866748"></a><p class="title"><strong>Table 10.3. AccessXFeedback Masks</strong></p><div class="table-contents"><table summary="AccessXFeedback Masks" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">Action</th><th align="left">Beep Code</th><th align="left">ax_options bit</th></tr></thead><tbody><tr><td align="left">LED turned on</td><td align="left">High-pitched beep</td><td align="left">XkbAX_IndicatorFBMask</td></tr><tr><td align="left">LED turned off</td><td align="left">Low-pitched beep</td><td align="left">XkbAX_IndicatorFBMask</td></tr><tr><td align="left">More than one LED changed state</td><td align="left">Two high-pitched beeps</td><td align="left">XkbAX_IndicatorFBMask</td></tr><tr><td align="left">Control turned on</td><td align="left">Rising tone</td><td align="left">XkbAX_FeatureFBMask</td></tr><tr><td align="left">Control turned off</td><td align="left">Falling tone</td><td align="left">XkbAX_FeatureFBMask</td></tr><tr><td align="left">More than one control changed state</td><td align="left">Two high-pitched beeps</td><td align="left">XkbAX_FeatureFBMask</td></tr><tr><td align="left">SlowKeys and BounceKeys about to be turned on or off</td><td align="left">Three high-pitched beeps</td><td align="left">XkbAX_SlowWarnFBMask</td></tr><tr><td align="left">SlowKeys key pressed</td><td align="left">Medium-pitched beep</td><td align="left">XkbAX_SKPressFBMask</td></tr><tr><td align="left">SlowKeys key accepted</td><td align="left">Medium-pitched beep</td><td align="left">XkbAX_SKAcceptFBMask</td></tr><tr><td align="left">SlowKeys key rejected</td><td align="left">Low-pitched beep</td><td align="left">XkbAX_SKRejectFBMask</td></tr><tr><td align="left">Accepted SlowKeys key released</td><td align="left">Medium-pitched beep</td><td align="left">XkbAX_SKReleaseFBMask</td></tr><tr><td align="left">BounceKeys key rejected</td><td align="left">Low-pitched beep</td><td align="left">XkbAX_BKRejectFBMask</td></tr><tr><td align="left">StickyKeys key latched</td><td align="left">Low-pitched beep followed by high-pitched beep</td><td align="left">XkbAX_StickyKeysFBMask</td></tr><tr><td align="left">StickyKeys key locked</td><td align="left">High-pitched beep</td><td align="left">XkbAX_StickyKeysFBMask</td></tr><tr><td align="left">StickyKeys key unlocked</td><td align="left">Low-pitched beep</td><td align="left">XkbAX_StickyKeysFBMask</td></tr></tbody></table></div></div><br class="table-break" /><p>
Implementations that cannot generate continuous tones may generate multiple
beeps instead of falling and rising tones; for example, they can generate a
high-pitched beep followed by a low-pitched beep instead of a continuous
falling tone. Other implementations can only ring the bell with one fixed
pitch. In these cases, use the <span class="emphasis"><em>
XkbAX_DumbBellFBMask</em></span>
 bit of <span class="emphasis"><em>
ax_options</em></span>
 to indicate that the bell can only ring with a fixed pitch.
</p><p>
When any of the above feedbacks occur, Xkb may generate a <span class="emphasis"><em>
XkbBellNotify</em></span>
 event (see section 9.4). 
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="AccessXNotify_Events"></a>AccessXNotify Events</h3></div></div></div><p>
The server can generate <span class="emphasis"><em>
XkbAccessXNotify</em></span>
 events for some of the global keyboard controls. The structure for the
<span class="emphasis"><em>
XkbAccessXNotify</em></span>
 event type is as follows:
</p><pre class="programlisting">
typedef struct {
      int             type;            /* Xkb extension base event code */
      unsigned long   serial;          /* X server serial number for event */
      Bool            send_event;      /* <span class="emphasis"><em> True</em></span> =&gt; synthetically generated */
      Display *       display;         /* server connection where event generated */
      Time            time;            /* server time when event generated */
      int             xkb_type;        /* <span class="emphasis"><em> XkbAccessXNotify</em></span> */
      int             device;          /* Xkb device ID, will not be <span class="emphasis"><em> XkbUseCoreKbd</em></span> */
      int             detail;          /* XkbAXN_* */
      KeyCode         keycode;         /* key of event */
      int             slowKeysDelay;   /* current SlowKeys delay */
      int             debounceDelay;   /* current debounce delay */
} <span class="emphasis"><em>XkbAccessXNotifyEvent</em></span>;
</pre><p>
The <span class="emphasis"><em>
detail</em></span>
 field describes what AccessX event just occurred and can be any of the values
in Table 10.4. 
</p><div class="table"><a id="idp65890924"></a><p class="title"><strong>Table 10.4. AccessXNotify Events</strong></p><div class="table-contents"><table summary="AccessXNotify Events" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">detail</th><th align="left">Reason</th></tr></thead><tbody><tr><td align="left">XkbAXN_SKPress</td><td align="left">A key was pressed when SlowKeys was enabled.</td></tr><tr><td align="left">XkbAXN_SKAccept</td><td align="left">A key was accepted (held longer than the SlowKeys delay).</td></tr><tr><td align="left">XkbAXN_SKRelease</td><td align="left">An accepted SlowKeys key was released.</td></tr><tr><td align="left">XkbAXN_SKReject</td><td align="left">A key was rejected (released before the SlowKeys delay
expired).</td></tr><tr><td align="left">XkbAXN_BKAccept</td><td align="left">A key was accepted by BounceKeys.</td></tr><tr><td align="left">XkbAXN_BKReject</td><td align="left">A key was rejected (pressed before the BounceKeys delay
expired).</td></tr><tr><td align="left">XkbAXN_AXKWarning</td><td align="left">AccessXKeys is about to turn on/off StickyKeys or BounceKeys.</td></tr></tbody></table></div></div><br class="table-break" /><p>
The <span class="emphasis"><em>
keycode</em></span>
 field reports the keycode of the key for which the event occurred. If the
action is related to <span class="emphasis"><em>
SlowKeys</em></span>
, the <span class="emphasis"><em>
slowKeysDelay</em></span>
 field contains the current <span class="emphasis"><em>
SlowKeys</em></span>
 acceptance delay. If the action is related to <span class="emphasis"><em>
BounceKeys</em></span>
, the <span class="emphasis"><em>
debounceDelay</em></span>
 field contains the current <span class="emphasis"><em>
BounceKeys</em></span>
 debounce delay.
</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Selecting_for_AccessX_Events"></a>Selecting for AccessX Events</h4></div></div></div><p>
To receive <span class="emphasis"><em>
XkbAccessXNotify</em></span>
 events under all possible conditions, use <span class="emphasis"><em>
XkbSelectEvents</em></span>
 (see section 4.3) and pass <span class="emphasis"><em> 
XkbAccesXNotifyMask</em></span>
 in both <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits</em></span>
.
</p><p>
To receive <span class="emphasis"><em>
XkbStateNotify</em></span>
 events only under certain conditions, use <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
 using <span class="emphasis"><em>
XkbAccessXNotify</em></span>
 as the <span class="emphasis"><em>
event_type</em></span>
 and specifying the desired state changes in <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits</em></span>
 using mask bits from Table 10.5. 
</p><div class="table"><a id="idp65905684"></a><p class="title"><strong>Table 10.5. AccessXNotify Event Details</strong></p><div class="table-contents"><table summary="AccessXNotify Event Details" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">XkbAccessXNotify Event Details</th><th align="left">Value</th><th align="left">Circumstances</th></tr></thead><tbody><tr><td align="left">XkbAXN_SKPressMask</td><td align="left">(1&lt;&lt;0)</td><td align="left">Slow key press notification wanted</td></tr><tr><td align="left">XkbAXN_SKAcceptMask</td><td align="left">(1&lt;&lt;1)</td><td align="left">Slow key accept notification wanted</td></tr><tr><td align="left">XkbAXN_SKRejectMask</td><td align="left">(1&lt;&lt;2)</td><td align="left">Slow key reject notification wanted</td></tr><tr><td align="left">XkbAXN_SKReleaseMask</td><td align="left">(1&lt;&lt;3)</td><td align="left">Slow key release notification wanted</td></tr><tr><td align="left">XkbAXN_BKAcceptMask</td><td align="left">(1&lt;&lt;4)</td><td align="left">Bounce key accept notification wanted</td></tr><tr><td align="left">XkbAXN_BKRejectMask</td><td align="left">(1&lt;&lt;5)</td><td align="left">Bounce key reject notification wanted</td></tr><tr><td align="left">XkbAXN_AXKWarningMask</td><td align="left">(1&lt;&lt;6)</td><td align="left">AccessX warning notification wanted</td></tr><tr><td align="left">XkbAXN_AllEventsMask</td><td align="left">(0x7f)</td><td align="left">All AccessX features notifications wanted</td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="StickyKeys_RepeatKeys_and_MouseKeys_Events"></a>StickyKeys, RepeatKeys, and MouseKeys Events</h3></div></div></div><p>
The <span class="emphasis"><em>
StickyKeys</em></span>
, <span class="emphasis"><em>
RepeatKeys</em></span>
, and <span class="emphasis"><em>
MouseKeys</em></span>
 controls do not generate specific events. Instead, the latching, unlatching,
locking, or unlocking of modifiers using <span class="emphasis"><em>
StickyKeys</em></span>
 generates <span class="emphasis"><em>
XkbStateNotify</em></span>
 events as described in section 5.4. Repeating keys generate normal <span class="emphasis"><em> 
KeyPress</em></span>
 and <span class="emphasis"><em>
KeyRelease</em></span>
 events, though the auto-repeat can be detected using <span class="emphasis"><em>
DetectableAutorepeat</em></span>
 (see section 10.3.3). Finally, <span class="emphasis"><em> 
MouseKeys</em></span>
 generates pointer events identical to those of the core pointer device.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_SlowKeys_Control"></a>The SlowKeys Control</h3></div></div></div><p>
Some users may accidentally bump keys while moving a hand or typing stick
toward the key they want. Usually, the keys that are accidentally bumped are
just hit for a very short period of time. The <span class="emphasis"><em>
SlowKeys</em></span>
 control helps filter these accidental bumps by telling the server to wait a
specified period, called the <span class="emphasis"><em>
SlowKeys acceptance delay</em></span>
, before delivering key events. If the key is released before this period
elapses, no key events are generated. Users can then bump any number of keys on
their way to the one they want without accidentally getting those characters.
Once they have reached the key they want, they can then hold the desired key
long enough for the computer to accept it. <span class="emphasis"><em>
SlowKeys</em></span>
 is a boolean control with one configurable attribute.
</p><p>
When the <span class="emphasis"><em>
SlowKeys</em></span>
 control is active, the server reports the initial key press, subsequent
acceptance or rejection, and release of any key to interested clients by
sending an appropriate <span class="emphasis"><em>
AccessXNotify</em></span>
 event (see section 10.6.4). 
</p><p>
To get the <span class="emphasis"><em>
SlowKeys</em></span>
 acceptance delay for a keyboard device, use <span class="emphasis"><em>
XkbGetSlowKeysDelay</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbGetSlowKeysDelay</em></span>
(<span class="emphasis"><em>
display</em></span>
,<span class="emphasis"><em>
 device_spec</em></span>
,<span class="emphasis"><em>
 delay_rtrn</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            display</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
device_spec</em></span>
;            /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int *      <span class="emphasis"><em>
delay_rtrn</em></span>
;            /* backfilled with <span class="emphasis"><em>
SlowKeys</em></span>
 delay, ms */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetSlowKeysDelay </em></span>
requests the attributes of the <span class="emphasis"><em>
SlowKeys</em></span>
 control from the server, waits for a reply and backfills <span class="emphasis"><em>
delay_rtrn </em></span>
with the <span class="emphasis"><em>
SlowKeys</em></span>
 delay attribute. <span class="emphasis"><em>
XkbGetSlowKeysDelay </em></span>
returns <span class="emphasis"><em>
True</em></span>
 if successful; if a compatible version of the Xkb extension is not available
in the server, <span class="emphasis"><em>
XkbGetSlowKeysDelay</em></span>
 returns <span class="emphasis"><em>
False</em></span>
.
</p><p>
To set the <span class="emphasis"><em>
SlowKeys</em></span>
 acceptance delay for a keyboard device, use <span class="emphasis"><em>
XkbSetSlowKeysDelay</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSetSlowKeysDelay</em></span>
(<span class="emphasis"><em>
display</em></span>
,<span class="emphasis"><em>
 device_spec</em></span>
,<span class="emphasis"><em>
 delay</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
      display</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
device_spec</em></span>
;            /* device to configure, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
delay</em></span>
;            /* <span class="emphasis"><em>
SlowKeys</em></span>
 delay, ms */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSetSlowKeysDelay</em></span>
 sends a request to configure the <span class="emphasis"><em>
SlowKeys</em></span>
 control to the server.<span class="emphasis"><em>
 </em></span>
It does not wait for a reply, and normally returns <span class="emphasis"><em>
True</em></span>
. Specifying a value of <span class="emphasis"><em>
0</em></span>
 for the <span class="emphasis"><em>
delay </em></span>
parameter causes <span class="emphasis"><em>
XkbSetSlowKeys</em></span>
 to generate a <span class="emphasis"><em>
BadValue</em></span>
 protocol error. If a compatible version of the Xkb extension is not available
in the server <span class="emphasis"><em>
XkbSetSlowKeysDelay</em></span>
 returns <span class="emphasis"><em>
False</em></span>
.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_BounceKeys_Control"></a>The BounceKeys Control</h3></div></div></div><p>
Some users may accidentally "bounce" on a key when they release it. They press
it once, then accidentally press it again after they release it. The <span class="emphasis"><em>
BounceKeys</em></span>
 control temporarily disables a key after it has been pressed, effectively
"debouncing" the keyboard. The period of time the key is disabled after it is
released is known as the <span class="emphasis"><em>
BounceKeys delay</em></span>
. <span class="emphasis"><em>
BounceKeys</em></span>
 is a boolean control.
</p><p>
When the <span class="emphasis"><em>
BounceKeys</em></span>
 control is active, the server reports acceptance or rejection of any key to
interested clients by sending an appropriate <span class="emphasis"><em>
AccessXNotify</em></span>
 event (see section 10.6.4). 
</p><p>
Use <span class="emphasis"><em>
XkbGetBounceKeysDelay</em></span>
 to query the current <span class="emphasis"><em>
BounceKeys</em></span>
 delay for a keyboard device.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbGetBounceKeysDelay</em></span>
(<span class="emphasis"><em>
display</em></span>
,<span class="emphasis"><em>
 device_spec</em></span>
,<span class="emphasis"><em>
 delay_rtrn</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
      display</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
device_spec</em></span>
;            /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int *      <span class="emphasis"><em>
delay_rtrn</em></span>
;            /* backfilled with bounce keys delay, ms */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetBounceKeysDelay </em></span>
requests the attributes of the <span class="emphasis"><em>
BounceKeys</em></span>
 control from the server, waits for a reply, and backfills <span class="emphasis"><em>
delay_rtrn </em></span>
with the <span class="emphasis"><em>
BounceKeys</em></span>
 delay attribute. <span class="emphasis"><em>
XkbGetBounceKeysDelay </em></span>
returns<span class="emphasis"><em>
 </em></span>
<span class="emphasis"><em>
True</em></span>
 if successful; if a compatible version of the Xkb extension is not available
in the server <span class="emphasis"><em>
XkbGetSlowKeysDelay</em></span>
 returns <span class="emphasis"><em>
False</em></span>
.
</p><p>
To set the <span class="emphasis"><em>
BounceKeys</em></span>
 delay for a keyboard device, use <span class="emphasis"><em>
XkbSetBounceKeysDelay</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSetBounceKeysDelay</em></span>
(<span class="emphasis"><em>
display</em></span>
,<span class="emphasis"><em>
 device_spec</em></span>
,<span class="emphasis"><em>
 delay</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
      display</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      device_spec</em></span>
;            /* device to configure, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
delay</em></span>
;            /* bounce keys delay, ms */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSetBounceKeysDelay</em></span>
 sends a request to configure the <span class="emphasis"><em>
BounceKeys</em></span>
 control to the server.<span class="emphasis"><em>
 </em></span>
It does not wait for a reply and normally returns <span class="emphasis"><em>
True</em></span>
. Specifying a value of <span class="emphasis"><em>
zero </em></span>
for the <span class="emphasis"><em>
delay </em></span>
parameter causes <span class="emphasis"><em>
XkbSetBounceKeysDelay</em></span>
 to generate a <span class="emphasis"><em>
BadValue</em></span>
 protocol error. If a compatible version of the Xkb extension is not available
in the server, <span class="emphasis"><em>
XkbSetBounceKeysDelay</em></span>
 returns <span class="emphasis"><em>
False</em></span>
.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_StickyKeys_Control"></a>The StickyKeys Control</h3></div></div></div><p>
Some people find it difficult or even impossible to press two keys at once. For
example, a one-fingered typist or someone using a mouth stick cannot press the
<span class="emphasis"><em>
Shift</em></span>
 and <span class="emphasis"><em>
1</em></span>
 keys at the same time. The <span class="emphasis"><em>
StickyKeys</em></span>
 control solves this problem by changing the behavior of the modifier keys.
With <span class="emphasis"><em>
StickyKeys</em></span>
, the user can first press a modifier, release it, then press another key. For
example, to get an exclamation point on a PC-style keyboard, the user can press
the <span class="emphasis"><em>
Shift</em></span>
 key, release it, and then press the <span class="emphasis"><em>
1</em></span>
 key.
</p><p>
<span class="emphasis"><em>
StickyKeys</em></span>
 also allows users to lock modifier keys without requiring special locking
keys. When <span class="emphasis"><em>
StickyKeys</em></span>
 is enabled, a modifier is latched when the user presses it just once. The user
can press a modifier twice in a row to lock it, and then unlock it by pressing
it one more time.
</p><p>
When a modifier is latched, it becomes unlatched when the user presses a
nonmodifier key or a pointer button. For instance, to enter the sequence
<span class="emphasis"><em>
Shift</em></span>
+<span class="emphasis"><em>
Control</em></span>
+<span class="emphasis"><em>
Z</em></span>
 the user could press and release the <span class="emphasis"><em>
Shift</em></span>
 key to latch it, then press and release the <span class="emphasis"><em>
Control</em></span>
 key to latch it, and finally press and release the Z key. Because the
<span class="emphasis"><em>
Control</em></span>
 key is a modifier key, pressing it does not unlatch the <span class="emphasis"><em>
Shift</em></span>
 key. Thus, after the user presses the <span class="emphasis"><em>
Control</em></span>
 key, both the <span class="emphasis"><em>
Shift</em></span>
 and <span class="emphasis"><em>
Control</em></span>
 modifiers are latched. When the user presses the <span class="emphasis"><em>
Z</em></span>
 key, the effect is as though the user had pressed <span class="emphasis"><em>
Shift</em></span>
+<span class="emphasis"><em>
Control</em></span>
+<span class="emphasis"><em>
Z</em></span>
. In addition, because the <span class="emphasis"><em>
Z</em></span>
 key is not a modifier key, the <span class="emphasis"><em>
Shift</em></span>
 and <span class="emphasis"><em>
Control</em></span>
 modifiers are unlatched.
</p><p>
Locking a modifier key means that the modifier affects any key or pointer
button the user presses until the user unlocks it or it is unlocked
programmatically. For example, to enter the sequence ("XKB") on a keyboard
where ‘(’ is a shifted ‘9’, ‘)’ is a shifted ‘0’, and ‘"’
is a shifted single quote, the user could press and release the <span class="emphasis"><em>
Shift</em></span>
 key twice to lock the <span class="emphasis"><em>
Shift</em></span>
 modifier. Then, when the user presses the <span class="emphasis"><em>
9</em></span>
, <span class="emphasis"><em>
‘</em></span>
, <span class="emphasis"><em>
x</em></span>
, <span class="emphasis"><em>
k</em></span>
, <span class="emphasis"><em>
b</em></span>
, <span class="emphasis"><em>
‘</em></span>
, and <span class="emphasis"><em>
0</em></span>
 keys in sequence, it generates ("XKB"). To unlock the <span class="emphasis"><em>
Shift</em></span>
 modifier, the user can press and release the <span class="emphasis"><em>
Shift</em></span>
 key.
</p><p>
<span class="emphasis"><em>StickyKeys</em></span>
 is a boolean control with two separate attributes that may be individually
configured: one to automatically disable it, and one to control the latching
behavior of modifier keys.
</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="StickyKeys_Options"></a>StickyKeys Options</h4></div></div></div><p>
The <span class="emphasis"><em>
StickyKeys</em></span>
 control has two options that can be accessed via the <span class="emphasis"><em>
ax_options</em></span>
 of an <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure (see section 10.8). The first option, <span class="emphasis"><em>
TwoKeys</em></span>
, specifies whether <span class="emphasis"><em>
StickyKeys</em></span>
 should automatically turn off when two keys are pressed at the same time. This
feature is useful for shared computers so people who do not want them do not
need to turn <span class="emphasis"><em>
StickyKeys</em></span>
 off if a previous user left <span class="emphasis"><em>
StickyKeys</em></span>
 on. The second option, <span class="emphasis"><em>
LatchToLock</em></span>
, specifies whether or not <span class="emphasis"><em>
StickyKeys</em></span>
 locks a modifier when pressed twice in a row.
</p><p>
Use <span class="emphasis"><em>
XkbGetStickyKeysOptions</em></span>
 to query the current <span class="emphasis"><em>
StickyKeys</em></span>
 attributes for a keyboard device.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbGetStickyKeysOptions</em></span>
(<span class="emphasis"><em>
display</em></span>
,<span class="emphasis"><em>
 device_spec</em></span>
,<span class="emphasis"><em>
 options_rtrn</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
      display</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
device_spec</em></span>
;            /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int *      <span class="emphasis"><em>
options_rtrn</em></span>
;            /* backfilled with StickyKeys option mask */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetStickyKeysOptions </em></span>
requests the attributes of the <span class="emphasis"><em>
StickyKeys</em></span>
 control from the server, waits for a reply, and backfills <span class="emphasis"><em>
options_rtrn </em></span>
with a mask indicating whether the individual <span class="emphasis"><em>
StickyKeys</em></span>
 options are on or off. Valid bits in <span class="emphasis"><em>
options_rtrn</em></span>
 are:
</p><p>
</p><pre class="programlisting">
     <span class="emphasis"><em>XkbAX_TwoKeysMask</em></span>
     <span class="emphasis"><em>XkbAX_LatchToLockMask</em></span>
</pre><p>
</p><p>
<span class="emphasis"><em>
XkbGetStickyKeysOptions </em></span>
returns <span class="emphasis"><em>
True</em></span>
 if successful; if a compatible version of the Xkb extension is not available
in the server <span class="emphasis"><em>
XkbGetStickyKeysOptions</em></span>
 returns <span class="emphasis"><em>
False</em></span>
.
</p><p>
To set the <span class="emphasis"><em>
StickyKeys</em></span>
 attributes for a keyboard device, use <span class="emphasis"><em>
XkbSetStickyKeysOptions</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSetStickyKeysOptions</em></span>
(<span class="emphasis"><em>
display</em></span>
,<span class="emphasis"><em>
 device_spec, mask, values</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
      display</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
device_spec</em></span>
;            /* device to configure, or XkbUseCoreKbd */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
mask</em></span>
;            /* selects StickyKeys attributes to modify */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
values;</em></span>
            /* values for selected attributes */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSetStickyKeysOptions</em></span>
 sends a request to configure the <span class="emphasis"><em>
StickyKeys</em></span>
 control to the server.<span class="emphasis"><em>
 </em></span>
It does not wait for a reply and normally returns <span class="emphasis"><em>
True</em></span>
. The valid bits to use for both the <span class="emphasis"><em>
mask</em></span>
 and <span class="emphasis"><em>
values</em></span>
 parameters are:
</p><p>
</p><pre class="programlisting">
     <span class="emphasis"><em>XkbAX_TwoKeysMask</em></span>
     <span class="emphasis"><em>XkbAX_LatchToLockMask</em></span>
</pre><p>
</p><p>
 If a compatible version of the Xkb extension is not available in the server,
<span class="emphasis"><em>
XkbSetStickyKeysOptions</em></span>
 returns <span class="emphasis"><em>
False</em></span>
.
</p></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Controls_for_General_Keyboard_Mapping"></a>Controls for General Keyboard Mapping</h2></div></div></div><p>
There are several controls that apply to the keyboard mapping in general. They
control handling of out-of-range group indices and how modifiers are processed
and consumed in the server. These are:
</p><p>
</p><pre class="programlisting">
     <span class="emphasis"><em>GroupsWrap</em></span>
     <span class="emphasis"><em>IgnoreGroupLock</em></span>
     <span class="emphasis"><em>IgnoreLockMods</em></span>
     <span class="emphasis"><em>InternalMods </em></span>
</pre><p>
</p><p>
<span class="emphasis"><em>
IgnoreGroupLock</em></span>
 is a boolean control; the rest are always active.
</p><p>
Without the modifier processing options provided by Xkb, passive grabs set via
translations in a client (for example, <span class="emphasis"><em>
Alt&lt;KeyPress&gt;space</em></span>
) do not trigger if any modifiers other than those specified by the translation
are set. This results in problems in the user interface when either <span class="emphasis"><em>
NumLock</em></span>
 or a secondary keyboard group is active. The <span class="emphasis"><em>
IgnoreLockMods</em></span>
 and <span class="emphasis"><em>
IgnoreGroupLock</em></span>
 controls make it possible to avoid this behavior without exhaustively
specifying a grab for every possible modifier combination.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_GroupsWrap_Control"></a>The GroupsWrap Control</h3></div></div></div><p>
The <span class="emphasis"><em>
GroupsWrap</em></span>
 control determines how illegal groups are handled on a global basis. There are
a number of valid keyboard sequences that can cause the effective group number
to go out of range. When this happens, the group must be normalized back to a
valid number. The <span class="emphasis"><em>
GroupsWrap</em></span>
 control specifies how this is done.
</p><p>
When dealing with group numbers, all computations are done using the group
index, which is the group number minus one. There are three different
algorithms; the <span class="emphasis"><em>
GroupsWrap</em></span>
 control specifies which one is used:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>XkbRedirectIntoRange</p><p>
All invalid group numbers are converted to a valid group number by taking the
last four bits of the <span class="emphasis"><em>
GroupsWrap</em></span>
 control and using them as the group index. If the result is still out of
range, Group one is used.
  </p></li><li class="listitem"><p>
XkbClampIntoRange
  </p><p>
All invalid group numbers are converted to the nearest valid group number.
Group numbers larger than the highest supported group number are mapped to the
highest supported group; those less than one are mapped to group one.
  </p></li><li class="listitem"><p>XkbWrapIntoRange</p><p>
All invalid group numbers are converted to a valid group number using integer
modulus applied to the group index.
  </p></li></ul></div><p>
There are no convenience functions for manipulating the <span class="emphasis"><em>
GroupsWrap</em></span>
 control. Manipulate the <span class="emphasis"><em>
GroupsWrap</em></span>
 control via the <span class="emphasis"><em>
groups_wrap</em></span>
 field in the <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure, then use <span class="emphasis"><em>
XkbSetControls</em></span>
 and <span class="emphasis"><em>
XkbGetControls</em></span>
 (see section 10.9 and section 10.10) to query and change this control. 
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>See also section 15.3.2 or a discussion of the related field,  
<span class="emphasis"><em>
group_info</em></span>
, which also normalizes a group under certain circumstances.</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_IgnoreLockMods_Control"></a>The IgnoreLockMods Control</h3></div></div></div><p>
The core protocol does not provide a way to exclude specific modifiers from
grab calculations, with the result that locking modifiers sometimes have
unanticipated side effects.
</p><p>
The <span class="emphasis"><em>
IgnoreLockMods</em></span>
 control specifies modifiers that should be excluded from grab calculations.
These modifiers are also not reported in any core events except <span class="emphasis"><em>
KeyPress</em></span>
 and <span class="emphasis"><em>
KeyRelease</em></span>
 events that do not activate a passive grab and that do not occur while a grab
is active.
</p><p>
Manipulate the <span class="emphasis"><em>
IgnoreLockMods</em></span>
 control via the <span class="emphasis"><em>
ignore_lock</em></span>
 field in the <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure, then use <span class="emphasis"><em>
XkbSetControls</em></span>
 and <span class="emphasis"><em>
XkbGetControls</em></span>
 (see sections 10.9 and 10.10) to query and change this control. Alternatively,  
use <span class="emphasis"><em>
XkbSetIgnoreLockMods</em></span>
.
</p><p>
To set the modifiers that, if locked, are not to be reported in matching events
to passive grabs, use <span class="emphasis"><em>
XkbSetIgnoreLockMods.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSetIgnoreLockMods</em></span>
(<span class="emphasis"><em>
display, device_spec, affect_real, real_values, affect_virtual,
virtual_values</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
display</em></span>
;            /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
device_spec</em></span>
;            /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      affect_real</em></span>
;            /* mask of real modifiers affected by this call */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      real_values</em></span>
;            /* values for affected real modifiers (1=&gt;set, 0=&gt;unset) */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      affect_virtual</em></span>
;            /* mask of virtual modifiers affected by this call */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      virtual_values</em></span>
;            /* values for affected virtual modifiers (1=&gt;set, 0=&gt;unset)
*/
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSetIgnoreLockMods</em></span>
 sends a request to the server to change the server’s <span class="emphasis"><em>
IgnoreLockMods</em></span>
 control. <span class="emphasis"><em>
affect_real</em></span>
 and <span class="emphasis"><em>
real_values</em></span>
 are masks of real modifier bits indicating which real modifiers are to be
added and removed from the server’s <span class="emphasis"><em>
IgnoreLockMods</em></span>
 control. Modifiers selected by both <span class="emphasis"><em>
affect_real</em></span>
 and <span class="emphasis"><em>
real_values</em></span>
 are added to the server’s <span class="emphasis"><em>
IgnoreLockMods</em></span>
 control; those selected by <span class="emphasis"><em>
affect_real</em></span>
 but not by <span class="emphasis"><em>
real_values</em></span>
 are removed from the server’s <span class="emphasis"><em>
IgnoreLockMods</em></span>
 control. Valid values for <span class="emphasis"><em>
affect_real</em></span>
 and <span class="emphasis"><em>
real_values</em></span>
 consist of any combination of the eight core modifier bits: <span class="emphasis"><em>
ShiftMask</em></span>
, <span class="emphasis"><em>
LockMask</em></span>
, <span class="emphasis"><em>
ControlMask</em></span>
, <span class="emphasis"><em>
Mod1Mask</em></span>
 - <span class="emphasis"><em>
Mod5Mask</em></span>
. <span class="emphasis"><em>
affect_virtual</em></span>
 and <span class="emphasis"><em>
virtual_values</em></span>
 are masks of virtual modifier bits indicating which virtual modifiers are to
be added and removed from the server’s <span class="emphasis"><em>
IgnoreLockMods</em></span>
 control. Modifiers selected by both <span class="emphasis"><em>
affect_virtual</em></span>
 and <span class="emphasis"><em>
virtual_values</em></span>
 are added to the server’s <span class="emphasis"><em>
IgnoreLockMods</em></span>
 control; those selected by <span class="emphasis"><em>
affect_virtual</em></span>
 but not by <span class="emphasis"><em>
virtual_values</em></span>
 are removed from the server’s <span class="emphasis"><em>
IgnoreLockMods</em></span>
 control.<span class="emphasis"><em>
 </em></span>
See section 7.1 for a discussion of virtual modifier masks to use in <span class="emphasis"><em> 
affect_virtual</em></span>
 and <span class="emphasis"><em>
virtual_values</em></span>
. <span class="emphasis"><em>
XkbSetIgnoreLockMods</em></span>
 does not wait for a reply from the server. It returns <span class="emphasis"><em>
True</em></span>
 if the request was sent, and <span class="emphasis"><em>
False</em></span>
 otherwise.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_IgnoreGroupLock_Control"></a>The IgnoreGroupLock Control</h3></div></div></div><p>
The <span class="emphasis"><em>
IgnoreGroupLock</em></span>
 control is a boolean control with no attributes. If enabled, it specifies that
the locked state of the keyboard group should not be considered when activating
passive grabs.
</p><p>
Because <span class="emphasis"><em>
IgnoreGroupLock</em></span>
 is a boolean control with no attributes, use the general boolean controls
functions (see section 10.1) to change its state. 
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_InternalMods_Control"></a>The InternalMods Control</h3></div></div></div><p>
The core protocol does not provide any means to prevent a modifier from being
reported in events sent to clients; Xkb, however makes this possible via the
<span class="emphasis"><em>
InternalMods</em></span>
 control. It specifies modifiers that should be consumed by the server and not
reported to clients. When a key is pressed and a modifier that has its bit set
in the <span class="emphasis"><em>
InternalMods</em></span>
 control is reported to the server, the server uses the modifier when
determining the actions to apply for the key. The server then clears the bit,
so it is not actually reported to the client. In addition, modifiers specified
in the <span class="emphasis"><em>
InternalMods</em></span>
 control are not used to determine grabs and are not used to calculate core
protocol compatibility state.
</p><p>
Manipulate the <span class="emphasis"><em>
InternalMods</em></span>
 control via the <span class="emphasis"><em>
internal</em></span>
 field in the <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure, using <span class="emphasis"><em>
XkbSetControls</em></span>
 and <span class="emphasis"><em>
XkbGetControls</em></span>
 (see sections10.9 and 10.10). Alternatively, use <span class="emphasis"><em> 
XkbSetServerInternalMods</em></span>
.
</p><p>
To set the modifiers that are consumed by the server before events are
delivered to the client, use <span class="emphasis"><em>
XkbSetServerInternalMods.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSetServerInternalMods</em></span>
(<span class="emphasis"><em>
display, device_spec, affect_real, real_values, affect_virtual,
virtual_values</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
display</em></span>
;            /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
device_spec</em></span>
;‘            /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      affect_real</em></span>
;            /* mask of real modifiers affected by this call */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      real_values</em></span>
;            /* values for affected real modifiers (1=&gt;set, 0=&gt;unset) */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      affect_virtual</em></span>
;            /* mask of virtual modifiers affected by this call */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      virtual_values</em></span>
;            /* values for affected virtual modifiers (1=&gt;set, 0=&gt;unset)
*/
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSetServerInternalMods</em></span>
 sends a request to the server to change the internal modifiers consumed by the
server. <span class="emphasis"><em>
affect_real</em></span>
 and <span class="emphasis"><em>
real_values</em></span>
 are masks of real modifier bits indicating which real modifiers are to be
added and removed from the server’s internal modifiers control. Modifiers
selected by both <span class="emphasis"><em>
affect_real</em></span>
 and <span class="emphasis"><em>
real_values</em></span>
 are added to the server’s internal modifiers control; those selected by
<span class="emphasis"><em>
affect_real</em></span>
 but not by <span class="emphasis"><em>
real_values</em></span>
 are removed from the server’s internal modifiers mask. Valid values for
<span class="emphasis"><em>
affect_real</em></span>
 and <span class="emphasis"><em>
real_values</em></span>
 consist of any combination of the eight core modifier bits: <span class="emphasis"><em>
ShiftMask</em></span>
, <span class="emphasis"><em>
LockMask</em></span>
, <span class="emphasis"><em>
ControlMask</em></span>
, <span class="emphasis"><em>
Mod1Mask</em></span>
 - <span class="emphasis"><em>
Mod5Mask</em></span>
.<span class="emphasis"><em>
 affect_virtual</em></span>
 and <span class="emphasis"><em>
virtual_values</em></span>
 are masks of virtual modifier bits indicating which virtual modifiers are to
be added and removed from the server’s internal modifiers control. Modifiers
selected by both <span class="emphasis"><em>
affect_virtual</em></span>
 and <span class="emphasis"><em>
virtual_values</em></span>
 are added to the server’s internal modifiers control; those selected by
<span class="emphasis"><em>
affect_virtual</em></span>
 but not by <span class="emphasis"><em>
virtual_values</em></span>
 are removed from the server’s internal modifiers control.<span class="emphasis"><em>
 </em></span>
See section 7.1 for a discussion of virtual modifier masks to use in <span class="emphasis"><em> 
affect_virtual</em></span>
 and <span class="emphasis"><em>
virtual_values</em></span>
.<span class="emphasis"><em>
 XkbSetServerInternalMods</em></span>
 does not wait for a reply from the server. It returns <span class="emphasis"><em>
True</em></span>
 if the request was sent and <span class="emphasis"><em>
False</em></span>
 otherwise.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="The_XkbControlsRec_Structure"></a>The XkbControlsRec Structure</h2></div></div></div><p>
Many of the individual controls described in sections 10.1 through 10.7 may be
manipulated via convenience functions discussed in those sections. Some of
them, however, have no convenience functions. The <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure allows the manipulation of one or more of the controls in a single
operation and to track changes to any of them in conjunction with the <span class="emphasis"><em>
XkbGetControls</em></span>
 and <span class="emphasis"><em>
XkbSetControls</em></span>
 functions. This is the only way to manipulate those controls that have no
convenience functions.
</p><p>
The <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure is defined as follows:
</p><p>
</p><pre class="programlisting">
#define      XkbMaxLegalKeyCode       255
#define      XkbPerKeyBitArraySize    ((XkbMaxLegalKeyCode+1)/8)
</pre><p>
</p><p>
</p><pre class="programlisting">
typedef struct {
      unsigned char        mk_dflt_btn;       /* default button for keyboard driven mouse */
      unsigned char        num_groups;        /* number of keyboard groups */
      unsigned char        groups_wrap;       /* how to wrap out-of-bounds groups */
      XkbModsRec           internal;          /* defines server internal modifiers */
      XkbModsRec           ignore_lock;       /* modifiers to ignore when checking for grab */
      unsigned int         enabled_ctrls;     /* 1 bit =&gt; corresponding boolean control enabled */
      unsigned short       repeat_delay;      /* ms delay until first repeat */
      unsigned short       repeat_interval;   /* ms delay between repeats */
      unsigned short       slow_keys_delay;   /* ms minimum time key must be down to be ok */
      unsigned short       debounce_delay;    /* ms delay before key reactivated */
      unsigned short       mk_delay;          /* ms delay to second mouse motion event */
      unsigned short       mk_interval;       /* ms delay between repeat mouse events */
      unsigned short       mk_time_to_max;    /* # intervals until constant mouse move */
      unsigned short       mk_max_speed;      /* multiplier for maximum mouse speed */
      short                mk_curve;          /* determines mouse move curve type */
      unsigned short       ax_options;        /* 1 bit =&gt; Access X option enabled */
      unsigned short       ax_timeout;        /* seconds until Access X disabled */
      unsigned short       axt_opts_mask;     /* 1 bit =&gt; options to reset on Access X timeout */
      unsigned short       axt_opts_values;   /* 1 bit =&gt; turn option on, 0=&gt; off */
      unsigned int         axt_ctrls_mask;    /* which bits in <span class="emphasis"><em> enabled_ctrls</em></span> to modify */
      unsigned int         axt_ctrls_values;  /* values for new bits in <span class="emphasis"><em> enabled_ctrls</em></span> */
      unsigned char        per_key_repeat[XkbPerKeyBitArraySize];           /* per key auto repeat */
} <span class="emphasis"><em>XkbControlsRec</em></span>, *XkbControlsPtr;
</pre><p>
</p><p>
The general-purpose functions that work with the <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure use a mask to specify which controls are to be manipulated. Table
10.6 lists these controls, the masks used to select them in the general
function calls (<span class="emphasis"><em>
which</em></span>
 parameter), and the data fields in the <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure that comprise each of the individual controls. Also listed are the
bit used to turn boolean controls on and off and the section where each control
is described in more detail.
</p><div class="table"><a id="idp66066828"></a><p class="title"><strong>Table 10.6. Xkb Controls</strong></p><div class="table-contents"><table summary="Xkb Controls" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /><col align="left" class="c5" /></colgroup><thead><tr><th align="left">Control</th><th align="left">Control Selection Mask (which parameter)</th><th align="left">Relevant XkbControlsRec Data Fields</th><th align="left">Boolean Control enabled_ctrls bit</th><th align="left">Section</th></tr></thead><tbody><tr><td align="left">AccessXFeedback</td><td align="left">XkbAccessXFeedbackMask</td><td align="left">ax_options:      XkbAX_*FBMask</td><td align="left">XkbAccessXFeedbackMask</td><td align="left">10.6.3</td></tr><tr><td align="left">AccessXKeys</td><td align="left"> </td><td align="left"> </td><td align="left">XkbAccessXKeysMask</td><td align="left">10.6.1</td></tr><tr><td align="left">AccessXTimeout</td><td align="left">XkbAccessXTimeoutMask</td><td align="left">
      <p>ax_timeout</p>
      <p>axt_opts_mask</p>
      <p>axt_opts_values</p>
      <p>axt_ctrls_mask</p>
      <p>axt_ctrls_values</p>
    </td><td align="left">XkbAccessXTimeoutMask</td><td align="left">10.6.2</td></tr><tr><td align="left">AudibleBell</td><td align="left"> </td><td align="left"> </td><td align="left">XkbAudibleBellMask</td><td align="left">9.2</td></tr><tr><td align="left">AutoReset</td><td align="left"> </td><td align="left"> </td><td align="left"> </td><td align="left">10.1.2</td></tr><tr><td align="left">BounceKeys</td><td align="left">XkbBounceKeysMask</td><td align="left">debounce_delay</td><td align="left">XkbBounceKeysMask</td><td align="left">10.6.7</td></tr><tr><td align="left">Detectable-Autorepeat</td><td align="left"> </td><td align="left"> </td><td align="left"> </td><td align="left">10.3.3</td></tr><tr><td align="left">EnabledControls</td><td align="left">XkbControlsEnabledMask</td><td align="left">enabled_ctrls</td><td align="left"><span class="emphasis"><em>Non-Boolean Control</em></span></td><td align="left">10.1.1</td></tr><tr><td align="left">GroupsWrap</td><td align="left">XkbGroupsWrapMask</td><td align="left">groups_wrap</td><td align="left"><span class="emphasis"><em>Non-Boolean Control</em></span></td><td align="left">10.7.1</td></tr><tr><td align="left">IgnoreGroupLock</td><td align="left"> </td><td align="left"> </td><td align="left">XkbIgnoreGroupLockMask</td><td align="left">10.7.3</td></tr><tr><td align="left">IgnoreLockMods</td><td align="left">XkbIgnoreLockModsMask</td><td align="left">ignore_lock</td><td align="left"><span class="emphasis"><em>Non-Boolean Control</em></span></td><td align="left">5.1</td></tr><tr><td align="left">InternalMods</td><td align="left">XkbInternalModsMask</td><td align="left">internal</td><td align="left"><span class="emphasis"><em>Non-Boolean Control</em></span></td><td align="left">5.1</td></tr><tr><td align="left">MouseKeys</td><td align="left">XkbMouseKeysMask</td><td align="left">mk_dflt_btn</td><td align="left">XkbMouseKeysMask</td><td align="left">10.5.1</td></tr><tr><td align="left">MouseKeysAccel</td><td align="left">XkbMouseKeysAccelMask</td><td align="left">
      <p>mk_delay</p>
      <p>mk_interval</p>
      <p>mk_time_to_max</p>
      <p>mk_max_speed</p>
      <p>mk_curve</p>
    </td><td align="left">XkbMouseKeysAccelMask</td><td align="left">10.5.2</td></tr><tr><td align="left">Overlay1</td><td align="left"> </td><td align="left"> </td><td align="left">XkbOverlay1Mask</td><td align="left">10.4</td></tr><tr><td align="left">Overlay2</td><td align="left"> </td><td align="left"> </td><td align="left">XkbOverlay2Mask</td><td align="left">10.4</td></tr><tr><td align="left">PerKeyRepeat</td><td align="left">XkbPerKeyRepeatMask</td><td align="left">per_key_repeat</td><td align="left"><span class="emphasis"><em>Non-Boolean Control</em></span></td><td align="left">10.3.1</td></tr><tr><td align="left">RepeatKeys</td><td align="left">XkbRepeatKeysMask</td><td align="left">
      <p>repeat_delay</p>
      <p>repeat_interval</p>
    </td><td align="left">XkbRepeatKeysMask</td><td align="left">10.3</td></tr><tr><td align="left">SlowKeys</td><td align="left">XkbSlowKeysMask</td><td align="left">slow_keys_delay</td><td align="left">XkbSlowKeysMask</td><td align="left">10.6.6</td></tr><tr><td align="left">StickyKeys</td><td align="left">XkbStickyKeysMask</td><td align="left">
      <p>ax_options:</p>
      <p>XkbAX_TwoKeysMask</p>
      <p>XkbAX_LatchToLockMask</p>
    </td><td align="left">XkbStickyKeysMask</td><td align="left">10.6.8</td></tr></tbody></table></div></div><br class="table-break" /><p>
Table 10.7 shows the actual values for the individual mask bits used to select  
controls for modification and to enable and disable the control. Note that the
same mask bit is used to specify general modifications to the parameters used
to configure the control (<span class="emphasis"><em>
which</em></span>
), and to enable and disable the control (<span class="emphasis"><em>
enabled_ctrls</em></span>
). The anomalies in the table (no "ok" in column) are for controls that have no
configurable attributes; and for controls that are not boolean controls and
therefore cannot be enabled or disabled.
</p><div class="table"><a id="idp66103916"></a><p class="title"><strong>Table 10.7. Controls Mask Bits</strong></p><div class="table-contents"><table summary="Controls Mask Bits" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Mask Bit</th><th align="left">which or changed_ctrls</th><th align="left">enabled_ctrls</th><th align="left">Value</th></tr></thead><tbody><tr><td align="left">XkbRepeatKeysMask</td><td align="left">ok</td><td align="left">ok</td><td align="left">(1L&lt;&lt;0)</td></tr><tr><td align="left">XkbSlowKeysMask</td><td align="left">ok</td><td align="left">ok</td><td align="left">(1L&lt;&lt;1)</td></tr><tr><td align="left">XkbBounceKeysMask</td><td align="left">ok</td><td align="left">ok</td><td align="left">(1L&lt;&lt;2)</td></tr><tr><td align="left">XkbStickyKeysMask</td><td align="left">ok</td><td align="left">ok</td><td align="left">(1L&lt;&lt;3)</td></tr><tr><td align="left">XkbMouseKeysMask</td><td align="left">ok</td><td align="left">ok</td><td align="left">(1L&lt;&lt;4)</td></tr><tr><td align="left">XkbMouseKeysAccelMask</td><td align="left">ok</td><td align="left">ok</td><td align="left">(1L&lt;&lt;5)</td></tr><tr><td align="left">XkbAccessXKeysMask</td><td align="left">ok</td><td align="left">ok</td><td align="left">(1L&lt;&lt;6)</td></tr><tr><td align="left">XkbAccessXTimeoutMask</td><td align="left">ok</td><td align="left">ok</td><td align="left">(1L&lt;&lt;7)</td></tr><tr><td align="left">XkbAccessXFeedbackMask</td><td align="left">ok</td><td align="left">ok</td><td align="left">(1L&lt;&lt;8)</td></tr><tr><td align="left">XkbAudibleBellMask</td><td align="left"> </td><td align="left">ok</td><td align="left">(1L&lt;&lt;9)</td></tr><tr><td align="left">XkbOverlay1Mask</td><td align="left"> </td><td align="left">ok</td><td align="left">(1L&lt;&lt;10)</td></tr><tr><td align="left">XkbOverlay2Mask</td><td align="left"> </td><td align="left">ok</td><td align="left">(1L&lt;&lt;11)</td></tr><tr><td align="left">XkbIgnoreGroupLockMask</td><td align="left"> </td><td align="left">ok</td><td align="left">(1L&lt;&lt;12)</td></tr><tr><td align="left">XkbGroupsWrapMask</td><td align="left">ok</td><td align="left"> </td><td align="left">(1L&lt;&lt;27)</td></tr><tr><td align="left">XkbInternalModsMask</td><td align="left">ok</td><td align="left"> </td><td align="left">(1L&lt;&lt;28)</td></tr><tr><td align="left">XkbIgnoreLockModsMask</td><td align="left">ok</td><td align="left"> </td><td align="left">(1L&lt;&lt;29)</td></tr><tr><td align="left">XkbPerKeyRepeatMask</td><td align="left">ok</td><td align="left"> </td><td align="left">(1L&lt;&lt;30)</td></tr><tr><td align="left">XkbControlsEnabledMask</td><td align="left">ok</td><td align="left"> </td><td align="left">(1L&lt;&lt;31)</td></tr><tr><td align="left">XkbAccessXOptionsMask</td><td align="left">ok</td><td align="left">ok</td><td align="left">(XkbStickyKeysMask | XkbAccessXFeedbackMask)</td></tr><tr><td align="left">XkbAllBooleanCtrlsMask</td><td align="left"> </td><td align="left">ok</td><td align="left">(0x00001FFF) </td></tr><tr><td align="left">XkbAllControlsMask</td><td align="left">ok</td><td align="left"> </td><td align="left">(0xF8001FFF)</td></tr></tbody></table></div></div><br class="table-break" /><p>
The individual fields of the <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure are defined as follows.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idp66132284"></a></h3></div></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="mk_dflt_btn"></a>mk_dflt_btn</h4></div></div></div><p>
<span class="emphasis"><em>
mk_dflt_btn is an attribute of the </em></span>
<span class="emphasis"><em>
MouseKeys</em></span>
<span class="emphasis"><em>
 control</em></span>
 (see section 10.5<span class="emphasis"><em> 
). It</em></span>
 specifies the mouse button number to use for keyboard simulated mouse button
operations. Its value should be one of the core symbols <span class="emphasis"><em>
Button1</em></span>
 - <span class="emphasis"><em>
Button5</em></span>
.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="num_groups"></a>num_groups</h4></div></div></div><p>
<span class="emphasis"><em>
num_groups</em></span>
 is not a part of any control, but is reported in the <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure whenever any of its components are fetched from the server. It
reports the number of groups the particular keyboard configuration uses and is
computed automatically by the server whenever the keyboard mapping changes.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="groups_wrap"></a>groups_wrap</h4></div></div></div><p>
<span class="emphasis"><em>
groups_wrap</em></span>
 is an attribute of the <span class="emphasis"><em>
GroupsWrap</em></span>
 control (see section 10.7.1). It specifies the handling of illegal groups on a  
global basis. Valid values for <span class="emphasis"><em>
groups_wrap</em></span>
 are shown in Table 10.8.
</p><div class="table"><a id="idp66138292"></a><p class="title"><strong>Table 10.8. GroupsWrap options (groups_wrap field)</strong></p><div class="table-contents"><table summary="GroupsWrap options (groups_wrap field)" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">groups_wrap symbolic name</th><th align="left">value</th></tr></thead><tbody><tr><td align="left">XkbWrapIntoRange</td><td align="left">(0x00)</td></tr><tr><td align="left">XkbClampIntoRange</td><td align="left">(0x40)</td></tr><tr><td align="left">XkbRedirectIntoRange</td><td align="left">(0x80)</td></tr></tbody></table></div></div><br class="table-break" /><p>
When <span class="emphasis"><em>
groups_wrap</em></span>
 is set to <span class="emphasis"><em>
XkbRedirectIntoRange</em></span>
, its four low-order bits specify the index of the group to use.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="internal"></a>internal</h4></div></div></div><p>
<span class="emphasis"><em>
internal</em></span>
 is an attribute of the <span class="emphasis"><em>
InternalMods</em></span>
 control (see section 10.7.4). It specifies modifiers to be consumed in the  
server and not passed on to clients when events are reported. Valid values
consist of any combination of the eight core modifier bits: <span class="emphasis"><em>
ShiftMask</em></span>
, <span class="emphasis"><em>
LockMask</em></span>
, <span class="emphasis"><em>
ControlMask</em></span>
, <span class="emphasis"><em>
Mod1Mask</em></span>
 - <span class="emphasis"><em>
Mod5Mask</em></span>
.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="ignore_lock"></a>ignore_lock</h4></div></div></div><p>
<span class="emphasis"><em>
ignore_lock</em></span>
 is an attribute of the <span class="emphasis"><em>
IgnoreLockMods</em></span>
 control (see section 10.7.2). It specifies modifiers to be ignored in grab  
calculations. Valid values consist of any combination of the eight core
modifier bits: <span class="emphasis"><em>
ShiftMask</em></span>
, <span class="emphasis"><em>
LockMask</em></span>
, <span class="emphasis"><em>
ControlMask</em></span>
, <span class="emphasis"><em>
Mod1Mask</em></span>
 - <span class="emphasis"><em>
Mod5Mask</em></span>
.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="enabled_ctrls"></a>enabled_ctrls</h4></div></div></div><p>
<span class="emphasis"><em>
enabled_ctrls</em></span>
 is an attribute of the <span class="emphasis"><em>
EnabledControls</em></span>
 control (see section 10.1.1). It contains one bit per boolean control. Each  
bit determines whether the corresponding control is enabled or disabled; a one
bit means the control is enabled. The mask bits used to enable these controls
are listed in Table 10.7, using only those masks with "ok" in the <span class="emphasis"><em>
enabled_ctrls</em></span>
 column.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="repeat_delay_and_repeat_interval"></a>repeat_delay and repeat_interval</h4></div></div></div><p>
<span class="emphasis"><em>
repeat_delay</em></span>
 and <span class="emphasis"><em>
repeat_interval</em></span>
 are attributes of the <span class="emphasis"><em>
RepeatKeys</em></span>
 control (see section 10.3.2). <span class="emphasis"><em> 
repeat_delay</em></span>
 is the initial delay before a key begins repeating, in milliseconds; <span class="emphasis"><em>
repeat_interval</em></span>
 is the delay between subsequent key events, in milliseconds.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="slow_keys_delay"></a>slow_keys_delay</h4></div></div></div><p>
<span class="emphasis"><em>
slow_keys_delay</em></span>
 is an attribute of the <span class="emphasis"><em>
SlowKeys</em></span>
 control (see section 10.6.6). Its value specifies the <span class="emphasis"><em> 
SlowKeys</em></span>
 acceptance delay period in milliseconds before a key press is accepted by the
server.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="debounce_delay"></a>debounce_delay</h4></div></div></div><p>
<span class="emphasis"><em>
debounce_delay</em></span>
 is an attribute of the <span class="emphasis"><em>
BounceKeys</em></span>
 control (see section 10.6.7). Its value specifies the <span class="emphasis"><em> 
BounceKeys</em></span>
 delay period in milliseconds for which the key is disabled after having been
pressed before another press of the same key is accepted by the server.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="mk_delay_mk_interval_mk_time_to_max_mk_max_speed_and_mk_curve"></a>mk_delay, mk_interval, mk_time_to_max, mk_max_speed, and mk_curve</h4></div></div></div><p>
<span class="emphasis"><em>
mk_delay</em></span>
, <span class="emphasis"><em>
mk_interval</em></span>
, <span class="emphasis"><em>
mk_time_to_max</em></span>
, <span class="emphasis"><em>
mk_max_speed</em></span>
, and <span class="emphasis"><em>
mk_curve</em></span>
 are attributes of the <span class="emphasis"><em>
MouseKeysAccel</em></span>
 control. Refer to section 10.5.2 for a description of these fields and the  
units involved.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="ax_options"></a>ax_options</h4></div></div></div><p>
The <span class="emphasis"><em>
ax_options</em></span>
 field contains attributes used to configure two different controls, the
<span class="emphasis"><em>
StickyKeys</em></span>
 control (see section 10.6.8) and the <span class="emphasis"><em> 
AccessXFeedback</em></span>
 control (see section 10.6.3). The <span class="emphasis"><em> 
ax_options</em></span>
 field is a bitmask and may include any combination of the bits defined in
Table 10.9.  
</p><div class="table"><a id="idp66163204"></a><p class="title"><strong>Table 10.9. Access X Enable/Disable Bits (ax_options field)</strong></p><div class="table-contents"><table summary="Access X Enable/Disable Bits (ax_options field)" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">Access X Control</th><th align="left">ax_options bit</th><th align="left">value</th></tr></thead><tbody><tr><td align="left">AccessXFeedback</td><td align="left">XkbAX_SKPressFBMask</td><td align="left">(1L&lt;&lt;0)</td></tr><tr><td align="left"> </td><td align="left">XkbAX_SKAcceptFBMask</td><td align="left">(1L &lt;&lt; 1)</td></tr><tr><td align="left"> </td><td align="left">XkbAX_FeatureFBMask</td><td align="left">(1L &lt;&lt; 2)</td></tr><tr><td align="left"> </td><td align="left">XkbAX_SlowWarnFBMask</td><td align="left">(1L &lt;&lt; 3)</td></tr><tr><td align="left"> </td><td align="left">XkbAX_IndicatorFBMask</td><td align="left">(1L &lt;&lt; 4)</td></tr><tr><td align="left"> </td><td align="left">XkbAX_StickyKeysFBMask</td><td align="left">(1L &lt;&lt; 5)</td></tr><tr><td align="left"> </td><td align="left">XkbAX_SKReleaseFBMask</td><td align="left">(1L &lt;&lt; 8)</td></tr><tr><td align="left"> </td><td align="left">XkbAX_SKRejectFBMask</td><td align="left">(1L &lt;&lt; 9)</td></tr><tr><td align="left"> </td><td align="left">XkbAX_BKRejectFBMask</td><td align="left">(1L &lt;&lt; 10)</td></tr><tr><td align="left"> </td><td align="left">XkbAX_DumbBellFBMask</td><td align="left">(1L &lt;&lt; 11)</td></tr><tr><td align="left">StickyKeys</td><td align="left">XkbAX_TwoKeysMask</td><td align="left">(1L &lt;&lt; 6)</td></tr><tr><td align="left"> </td><td align="left">XkbAX_LatchToLockMask</td><td align="left">(1L &lt;&lt; 7)</td></tr><tr><td align="left"> </td><td align="left">XkbAX_AllOptionsMask</td><td align="left">(0xFFF)</td></tr></tbody></table></div></div><br class="table-break" /><p>
The fields pertaining to each control are relevant only when the control is
enabled (<span class="emphasis"><em>
XkbAccessXFeedbackMask</em></span>
 or <span class="emphasis"><em>
XkbStickyKeysMask</em></span>
 bit is turned on in the <span class="emphasis"><em>
enabled_cntrls</em></span>
 field).
</p><p>
Xkb provides a set of convenience macros for working with the <span class="emphasis"><em>
ax_options</em></span>
 field of an <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure:
</p><pre class="programlisting">
#define      <span class="emphasis"><em>XkbAX_NeedOption</em></span>
(c,w)      ((c)-&gt;ax_options&amp;(w))
</pre><p>
The <span class="emphasis"><em>
XkbAX_NeedOption</em></span>
 macro is useful for determining whether a particular AccessX option is enabled
or not. It accepts a pointer to an <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure and a valid mask bit from Table 10.9. If the specified mask bit in
the <span class="emphasis"><em>
ax_options</em></span>
 field of the controls structure is set, the macro returns the mask bit.
Otherwise, it returns zero. Thus,
</p><p>
XkbAX_NeedOption(ctlrec, XkbAX_LatchToLockMask)
</p><p>
is nonzero if the latch to lock transition for latching keys is enabled, and
zero if it is disabled. Note that <span class="emphasis"><em>
XkbAX_NeedOption</em></span>
 only determines whether or not the particular capability is configured to
operate; the <span class="emphasis"><em>
XkbAccessXFeedbackMask</em></span>
 bit must also be turned on in <span class="emphasis"><em>
enabled_ctrls</em></span>
 for the capability to actually be functioning.
</p><pre class="programlisting">
#define      <span class="emphasis"><em>XkbAX_AnyFeedback</em></span>
(c)      ((c)-&gt;enabled_ctrls&amp;XkbAccessXFeedbackMask)
</pre><p>
The <span class="emphasis"><em>
XkbAX_AnyFeeback</em></span>
 macro accepts a pointer to an <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure and tells whether the <span class="emphasis"><em>
AccessXFeedback</em></span>
 control is enabled or not. If the <span class="emphasis"><em>
AccessXFeedback</em></span>
 control is enabled, the macro returns <span class="emphasis"><em>
XkbAccessXFeedbackMask</em></span>
. Otherwise, it returns zero.
</p><pre class="programlisting">
#define      <span class="emphasis"><em>XkbAX_NeedFeedback</em></span>
(c,w)      (XkbAX_AnyFeedback(c)&amp;&amp;XkbAX_NeedOption(c,w))
</pre><p>
The <span class="emphasis"><em>
XkbAX_NeedFeedback</em></span>
 macro is useful for determining if both the <span class="emphasis"><em>
AccessXFeedback</em></span>
 control and a particular AccessX feedback option are enabled. The macro
accepts a pointer to an <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure and a feedback option from the table above. If both the <span class="emphasis"><em>
AccessXFeedback</em></span>
 control and the specified feedback option are enabled, the macro returns
<span class="emphasis"><em>
True</em></span>
. Otherwise it returns <span class="emphasis"><em>
False</em></span>
.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="ax_timeout_axt_opts_mask_axt_opts_values_axt_ctrls_mask_and_axt_ctrls_values"></a>ax_timeout, axt_opts_mask, axt_opts_values, axt_ctrls_mask, and axt_ctrls_values</h4></div></div></div><p>
<span class="emphasis"><em>
ax_timeout</em></span>
, <span class="emphasis"><em>
act_opts_mask</em></span>
, <span class="emphasis"><em>
axt_opts_values</em></span>
, <span class="emphasis"><em>
axt_ctrls_mask</em></span>
, and <span class="emphasis"><em>
axt_ctrls_values</em></span>
 are attributes of the <span class="emphasis"><em>
AccessXTimeout</em></span>
 control. Refer to section 10.6.2 for a description of these fields and the  
units involved.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="per_key_repeat"></a>per_key_repeat</h4></div></div></div><p>
The <span class="emphasis"><em>
per_key_repeat</em></span>
 field mirrors the <span class="emphasis"><em>
auto_repeats</em></span>
 field of the core protocol <span class="emphasis"><em>
XKeyboardState</em></span>
 structure: changing the <span class="emphasis"><em>
auto_repeats</em></span>
 field automatically changes <span class="emphasis"><em>
per_key_repeat</em></span>
 and vice versa. It is provided for convenience and to reduce protocol traffic.
For example, to obtain the individual repeat key behavior as well as the repeat
delay and rate, use <span class="emphasis"><em>
XkbGetControls</em></span>
. If the <span class="emphasis"><em>
per_key_repeat</em></span>
 were not in this structure, you would have to call both <span class="emphasis"><em>
XGetKeyboardControl</em></span>
 and <span class="emphasis"><em>
XkbGetControls</em></span>
 to get this information. The bits correspond to keycodes. The first seven keys
(keycodes 1-7) are indicated in <span class="emphasis"><em>
per_key_repeat</em></span>
[0], with bit position 0 (low order) corresponding to the fictitious keycode 0.
Following array elements correspond to 8 keycodes per element. A 1 bit
indicates that the key is a repeating key.
</p></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Querying_Controls"></a>Querying Controls</h2></div></div></div><p>
Use <span class="emphasis"><em>
XkbGetControls</em></span>
 to find the current state of Xkb server controls.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetControls</em></span>
(<span class="emphasis"><em>
display, which, xkb)</em></span>
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            display</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned long<span class="emphasis"><em>
            which</em></span>
;            /* mask of controls requested */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr<span class="emphasis"><em>
            xkb</em></span>
;            /* keyboard description for controls information*/
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetControls</em></span>
 queries the server for the requested control information, waits for a reply,
and then copies the server’s values for the requested information into the
<span class="emphasis"><em>
ctrls</em></span>
 structure of the <span class="emphasis"><em>
xkb</em></span>
 argument. Only those components specified by the <span class="emphasis"><em>
which</em></span>
 parameter are copied. Valid values for <span class="emphasis"><em>
which</em></span>
 are any combination of the masks listed in Table 10.7 that have "ok" in the
<span class="emphasis"><em>
which</em></span>
 column.
</p><p>
If <span class="emphasis"><em>
xkb</em></span>
-&gt;<span class="emphasis"><em>
ctrls </em></span>
is <span class="emphasis"><em>
NULL</em></span>
, <span class="emphasis"><em>
XkbGetControls</em></span>
 allocates and initializes it before obtaining the values specified by
<span class="emphasis"><em>
which</em></span>
. If <span class="emphasis"><em>
xkb</em></span>
-&gt;<span class="emphasis"><em>
ctrls</em></span>
 is not <span class="emphasis"><em>
NULL</em></span>
, <span class="emphasis"><em>
XkbGetControls</em></span>
 modifies only those portions of <span class="emphasis"><em>
xkb</em></span>
-&gt;<span class="emphasis"><em>
ctrls</em></span>
 corresponding to the values specified by <span class="emphasis"><em>
which</em></span>
.
</p><p>
<span class="emphasis"><em>
XkbGetControls</em></span>
 returns <span class="emphasis"><em>
Success</em></span>
 if successful; otherwise, it returns <span class="emphasis"><em>
BadAlloc</em></span>
 if it cannot obtain sufficient storage, <span class="emphasis"><em>
BadMatch</em></span>
 if <span class="emphasis"><em>
xkb</em></span>
 is <span class="emphasis"><em>
NULL</em></span>
 or <span class="emphasis"><em>
which</em></span>
 is empty, or <span class="emphasis"><em>
BadImplementation</em></span>
.
</p><p>
To free the <span class="emphasis"><em>
ctrls</em></span>
 member of a keyboard description, use <span class="emphasis"><em>
XkbFreeControls</em></span>
 (see section 10.12)
</p><p>
The <span class="emphasis"><em>
num_groups</em></span>
 field in the <span class="emphasis"><em>
ctrls</em></span>
 structure is always filled in by <span class="emphasis"><em>
XkbGetControls</em></span>
, regardless of which bits are selected by <span class="emphasis"><em>
which</em></span>
.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Changing_Controls"></a>Changing Controls</h2></div></div></div><p>
There are two ways to make changes to controls: either change a local copy
keyboard description and call <span class="emphasis"><em>
XkbSetControls</em></span>
, or, to reduce network traffic, use an<span class="emphasis"><em>
 XkbControlsChangesRec</em></span>
 structure and call <span class="emphasis"><em>
XkbChangeControls</em></span>
.
</p><p>
To change the state of one or more controls, first modify the <span class="emphasis"><em>
ctrls</em></span>
 structure in a local copy of the keyboard description and then use <span class="emphasis"><em>
XkbSetControls</em></span>
 to copy those changes to the X server.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSetControls</em></span>
(<span class="emphasis"><em>
display, which, xkb)</em></span>
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            display</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned long      <span class="emphasis"><em>
      which      </em></span>
;      /* mask of controls to change */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;            /* <span class="emphasis"><em>
ctrls</em></span>
 field contains new values to be set */
    </td></tr></tbody></table></div><p>
For each bit that is set in the <span class="emphasis"><em>
which</em></span>
 parameter, <span class="emphasis"><em>
XkbSetControls</em></span>
 sends the corresponding values from the <span class="emphasis"><em>
xkb</em></span>
-&gt;<span class="emphasis"><em>
ctrls</em></span>
 field to the server. Valid values for <span class="emphasis"><em>
which</em></span>
 are any combination of the masks listed in Table 10.7 that have "ok" in the
<span class="emphasis"><em>
which</em></span>
 column.
</p><p>
If <span class="emphasis"><em>
xkb</em></span>
-&gt;<span class="emphasis"><em>
ctrls</em></span>
 is <span class="emphasis"><em>
NULL</em></span>
, the server does not support a compatible version of Xkb, or the Xkb extension
has not been properly initialized, <span class="emphasis"><em>
XkbSetControls</em></span>
 returns <span class="emphasis"><em>
False</em></span>
. Otherwise, it sends the request to the X server and returns <span class="emphasis"><em>
True</em></span>
.
</p><p>
Note that changes to attributes of controls in the <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure are apparent only when the associated control is enabled, although
the corresponding values are still updated in the X server. For example, the
<span class="emphasis"><em>
repeat_delay</em></span>
 and <span class="emphasis"><em>
repeat_interval</em></span>
 fields are ignored unless the <span class="emphasis"><em>
RepeatKeys</em></span>
 control is enabled (that is, the X server’s equivalent of <span class="emphasis"><em>
xkb-&gt;ctrls</em></span>
 has <span class="emphasis"><em>
XkbRepeatKeyMask</em></span>
 set in <span class="emphasis"><em>
enabled_ctrls</em></span>
). It is permissible to modify the attributes of a control in one call to
XkbSetControls and enable the control in a subsequent call. See section 10.1.1  
for more information on enabling and disabling controls.
</p><p>
Note that the <span class="emphasis"><em>
enabled_ctrls</em></span>
 field is itself a control — the <span class="emphasis"><em>
EnabledControls</em></span>
 control. As such, to set a specific configuration of enabled and disabled
boolean controls, you must set <span class="emphasis"><em>
enabled_ctrls</em></span>
 to the appropriate bits to enable only the controls you want and disable all
others, then specify the <span class="emphasis"><em>
XkbControlsEnabledMask</em></span>
 in a call to <span class="emphasis"><em>
XkbSetControls</em></span>
. Because this is somewhat awkward if all you want to do is enable and disable
controls, and not modify any of their attributes, a convenience function is
also provided for this purpose (<span class="emphasis"><em>
XkbChangeEnabledControls</em></span>
, section 10.1.1). 
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_XkbControlsChangesRec_Structure"></a>The XkbControlsChangesRec Structure</h3></div></div></div><p>
The <span class="emphasis"><em>
XkbControlsChangesRec</em></span>
 structure allows applications to track modifications to an <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure and thereby reduce the amount of traffic sent to the server. The
same <span class="emphasis"><em>
XkbControlsChangesRec</em></span>
 structure may be used in several successive modifications to the same
<span class="emphasis"><em>
XkbControlsRec</em></span>
 structure, then subsequently used to cause all of the changes, and only the
changes, to be propagated to the server. The <span class="emphasis"><em>
XkbControlsChangesRec</em></span>
 structure is defined as follows:
</p><pre class="programlisting">
typedef struct _XkbControlsChanges {
      unsigned int changed_ctrls;          /* bits indicating changed control data */
      unsigned int enabled_ctrls_changes;  /* bits indicating enabled/disabled controls */
      Bool         num_groups_changed;     /* <span class="emphasis"><em> True</em></span> if
                                              number of keyboard groups changed */
} <span class="emphasis"><em>XkbControlsChangesRec</em></span>,*XkbControlsChangesPtr;
</pre><p>
The <span class="emphasis"><em>
changed_ctrls</em></span>
 field is a mask specifying which logical sets of data in the controls
structure have been modified. In this context, modified means <span class="emphasis"><em>
set</em></span>
, that is, if a value is set to the same value it previously contained, it has
still been modified, and is noted as changed. Valid values for <span class="emphasis"><em>
changed_ctrls</em></span>
 are any combination of the masks listed in Table 10.7 that have "ok" in the
<span class="emphasis"><em>
changed_ctrls</em></span>
 column. Setting a bit implies the corresponding data fields from the "Relevant
XkbControlsRec Data Fields" column in Table 10.6 have been modified. The
<span class="emphasis"><em>
enabled_ctrls_changes</em></span>
 field specifies which bits in the <span class="emphasis"><em>
enabled_ctrls</em></span>
 field have changed. If the number of keyboard groups has changed, the
<span class="emphasis"><em>num_groups_changed</em></span>
 field is set to <span class="emphasis"><em>True</em></span>.
</p><p>
If you have an Xkb description with controls that have been modified and an
<span class="emphasis"><em>
XkbControlsChangesRec</em></span>
 that describes the changes that have been made, the <span class="emphasis"><em>
XkbChangeControls</em></span>
 function provides a flexible method for updating the controls in a server to
match those in the changed keyboard description.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbChangeControls</em></span>
(<span class="emphasis"><em>
dpy, xkb, changes</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *                  <span class="emphasis"><em>
dpy</em></span>
;      /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr                  <span class="emphasis"><em>
xkb</em></span>
;      /* keyboard description with changed <span class="emphasis"><em>
xkb-&gt;ctrls</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbControlsChangesPtr                  <span class="emphasis"><em>
changes</em></span>
;      /* which parts of <span class="emphasis"><em>
xkb-&gt;ctrls</em></span>
 have changed */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbChangeControls</em></span>
 copies any controls fields specified by <span class="emphasis"><em>
changes</em></span>
 from the keyboard description controls structure, <span class="emphasis"><em>
xkb</em></span>
-&gt;<span class="emphasis"><em>
ctrls</em></span>
, to the server specified by <span class="emphasis"><em>
dpy</em></span>
.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Tracking_Changes_to_Keyboard_Controls"></a>Tracking Changes to Keyboard Controls</h2></div></div></div><p>
Whenever a field in the controls structure changes in the server’s keyboard
description, the server sends an <span class="emphasis"><em>
XkbControlsNotify</em></span>
 event to all interested clients.To receive <span class="emphasis"><em>
XkbControlsNotify</em></span>
 events under all possible conditions, use <span class="emphasis"><em>
XkbSelectEvents</em></span>
 (see section 4.3) and pass <span class="emphasis"><em>
XkbControlsNotifyMask</em></span>
 in both <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits</em></span>
.
</p><p>
To receive <span class="emphasis"><em>
XkbControlsNotify</em></span>
 events only under certain conditions, use <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
 using <span class="emphasis"><em>
XkbControlsNotify</em></span>
 as the <span class="emphasis"><em>
event_type</em></span>
 and specifying the desired state changes in <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits</em></span>
 using mask bits from Table 10.7. 
</p><p>
The structure for the <span class="emphasis"><em>
XkbControlsNotify</em></span>
 event is defined as follows:
</p><pre class="programlisting">
typedef struct {
      int            type;            /* Xkb extension base event code */
      unsigned long  serial;          /* X server serial number for event */
      Bool           send_event;      /* <span class="emphasis"><em> True</em></span> =&gt; synthetically generated */
      Display *      display;         /* server connection where event generated */
      Time           time;            /* server time when event generated */
      int            xkb_type;        /* <span class="emphasis"><em> XkbCompatMapNotify</em></span> */
      int            device;          /* Xkb device ID, will not be <span class="emphasis"><em> XkbUseCoreKbd</em></span> */
      unsigned int   changed_ctrls;   /* bits indicating which controls data have changed*/
      unsigned int   enabled_ctrls;   /* controls currently enabled in server */
      unsigned int   enabled_ctrl_changes;  /* bits indicating enabled/disabled controls */
      int            num_groups;      /* current number of keyboard groups */
      KeyCode        keycode;         /* != 0 =&gt; keycode of key causing change */
      char           event_type;      /* Type of event causing change */
      char           req_major;       /* major event code of event causing change */
      char           req_minor;       /* minor event code of event causing change */
} <span class="emphasis"><em>XkbControlsNotifyEvent</em></span>;
</pre><p>
The <span class="emphasis"><em>
changed_ctrls</em></span>
 field specifies the controls components that have changed and consists of bits
taken from the masks defined in Table 10.7 with "ok" in the <span class="emphasis"><em>
changed_ctrls</em></span>
 column.
</p><p>
The controls currently enabled in the server are reported in the <span class="emphasis"><em>
enabled_ctrls</em></span>
 field. If any controls were just enabled or disabled (that is, the contents of
the <span class="emphasis"><em>
enabled_ctrls</em></span>
 field changed), they are flagged in the <span class="emphasis"><em>
enabled_ctrl_changes</em></span>
 field. The valid bits for these fields are the masks listed in Table 10.7 with
"ok" in the <span class="emphasis"><em>
enabled_ctrls</em></span>
 column. The <span class="emphasis"><em>
num_groups</em></span>
 field reports the number of groups bound to the key belonging to the most
number of groups and is automatically updated when the keyboard mapping changes.
</p><p>
If the change was caused by a request from a client, the <span class="emphasis"><em>
keycode</em></span>
 and <span class="emphasis"><em>
event_type</em></span>
 fields are set to <span class="emphasis"><em>
zero </em></span>
and the <span class="emphasis"><em>
req_major</em></span>
 and <span class="emphasis"><em>
req_minor</em></span>
 fields identify the request. The <span class="emphasis"><em>
req_major</em></span>
 value is the same as the major extension opcode. Otherwise, <span class="emphasis"><em>
event_type</em></span>
 is set to the type of event that caused the change (one of <span class="emphasis"><em>
KeyPress</em></span>
, <span class="emphasis"><em>
KeyRelease</em></span>
, <span class="emphasis"><em>
DeviceKeyPress</em></span>
, <span class="emphasis"><em>
DeviceKeyRelease</em></span>
, <span class="emphasis"><em>
ButtonPress</em></span>
 or <span class="emphasis"><em>
ButtonRelease</em></span>
), and <span class="emphasis"><em>
req_major</em></span>
 and <span class="emphasis"><em>
req_minor</em></span>
 are undefined. If <span class="emphasis"><em>
event_type</em></span>
 is <span class="emphasis"><em>
KeyPress</em></span>
, <span class="emphasis"><em>
KeyRelease</em></span>
, <span class="emphasis"><em>
DeviceKeyPress</em></span>
, or <span class="emphasis"><em>
DeviceKeyRelease</em></span>
, the <span class="emphasis"><em>
keycode</em></span>
 field is set to the key that caused the change. If <span class="emphasis"><em>
event_type</em></span>
 is <span class="emphasis"><em>
ButtonPress</em></span>
 or <span class="emphasis"><em>
ButtonRelease</em></span>
, <span class="emphasis"><em>
keycode</em></span>
 contains the button number.
</p><p>
When a client receives an <span class="emphasis"><em>
XkbControlsNotify</em></span>
 event, it can note the changes in a changes structure using <span class="emphasis"><em>
XkbNoteControlsChanges</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbNoteControlsChanges</em></span>
(<span class="emphasis"><em>
changes</em></span>
,<span class="emphasis"><em>
 new</em></span>
,<span class="emphasis"><em>
 wanted</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbControlsChangesPtr            <span class="emphasis"><em>
      changes</em></span>
;      /* records changes indicated by new */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbControlsNotifyEvent *            <span class="emphasis"><em>
      new</em></span>
;      /* tells which things have changed */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
      wanted</em></span>
;      /* tells which parts of new to record in changes */
    </td></tr></tbody></table></div><p>
The <span class="emphasis"><em>
wanted</em></span>
 parameter is a bitwise inclusive OR of bits taken from the set of masks
specified in Table 10.7 with "ok" in the <span class="emphasis"><em>
changed_ctrls</em></span>
 column. <span class="emphasis"><em>
XkbNoteControlsChanges</em></span>
 copies any changes reported in <span class="emphasis"><em>
new</em></span>
 and specified in <span class="emphasis"><em>
wanted</em></span>
 into the changes record specified by <span class="emphasis"><em>
old</em></span>
.
</p><p>
Use <span class="emphasis"><em>
XkbGetControlsChanges</em></span>
 to update a local copy of a keyboard description with the changes previously
noted by one or more calls to <span class="emphasis"><em>
XkbNoteControlsChanges.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetControlsChanges</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 xkb</em></span>
,<span class="emphasis"><em>
 changes</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            <span class="emphasis"><em>
dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;            /* <span class="emphasis"><em>
xkb-&gt;ctrls</em></span>
 will be updated */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbNameChangesPtr            <span class="emphasis"><em>
changes</em></span>
;            /* indicates which parts of <span class="emphasis"><em>
xkb-&gt;ctrls</em></span>
 to update */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetControlsChanges</em></span>
 examines the <span class="emphasis"><em>
changes</em></span>
 parameter, queries the server for the necessary information, and copies the
results into the <span class="emphasis"><em>
xkb</em></span>
-&gt;<span class="emphasis"><em>
ctrls</em></span>
 keyboard description. If the <span class="emphasis"><em>
ctrls</em></span>
 field of <span class="emphasis"><em>
xkb</em></span>
 is <span class="emphasis"><em>
NULL</em></span>
, <span class="emphasis"><em>
XkbGetControlsChanges</em></span>
 allocates and initializes it. To free the <span class="emphasis"><em>
ctrls</em></span>
 field, use <span class="emphasis"><em>
XkbFreeControls</em></span>
 (see section 10.12). 
</p><p>
<span class="emphasis"><em>
XkbGetControlsChanges</em></span>
 returns <span class="emphasis"><em>
Success</em></span>
 if successful and can generate <span class="emphasis"><em>
BadAlloc</em></span>
, <span class="emphasis"><em>
BadImplementation,</em></span>
 and <span class="emphasis"><em>
BadMatch</em></span>
 errors.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Allocating_and_Freeing_an_XkbControlsRec"></a>Allocating and Freeing an XkbControlsRec</h2></div></div></div><p>
The need to allocate an <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure seldom arises; Xkb creates one when an application calls <span class="emphasis"><em>
XkbGetControls</em></span>
 or a related function. For those situations where there is not an <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure allocated in the <span class="emphasis"><em>
XkbDescRec</em></span>
, allocate one by calling <span class="emphasis"><em>
XkbAllocControls</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocControls</em></span>
(<span class="emphasis"><em>
xkb, which</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr <span class="emphasis"><em>
            xkb</em></span>
;            /* Xkb description in which to allocate ctrls rec */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
            which</em></span>
;            /* mask of components of <span class="emphasis"><em>
ctrls</em></span>
 to allocate */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocControls</em></span>
 allocates the <span class="emphasis"><em>
ctrls</em></span>
 field of the <span class="emphasis"><em>
xkb</em></span>
 parameter, initializes all fields to zero, and returns <span class="emphasis"><em>
Success</em></span>
. If the <span class="emphasis"><em>
ctrls</em></span>
 field is not <span class="emphasis"><em>
NULL</em></span>
, <span class="emphasis"><em>
XkbAllocControls</em></span>
 simply returns <span class="emphasis"><em>
Success</em></span>
. If <span class="emphasis"><em>
xkb</em></span>
 is <span class="emphasis"><em>
NULL</em></span>
, <span class="emphasis"><em>
XkbAllocControls</em></span>
 reports a <span class="emphasis"><em>
BadMatch</em></span>
 error. If the <span class="emphasis"><em>
ctrls</em></span>
 field could not be allocated, it reports a <span class="emphasis"><em>
BadAlloc</em></span>
 error.
</p><p>
The <span class="emphasis"><em>
which</em></span>
 mask specifies the individual fields of the <span class="emphasis"><em>
ctrls</em></span>
 structure to be allocated and can contain any of the valid masks defined in
Table 10.7. Because none of the currently existing controls have any structures
associated with them, which is currently of little practical value in this call.
</p><p>
To free memory used by the <span class="emphasis"><em>
ctrls</em></span>
 member of an <span class="emphasis"><em>
XkbDescRec </em></span>
structure, use <span class="emphasis"><em>
XkbFreeControls:</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeControls</em></span>
(<span class="emphasis"><em>
xkb, which, free_all</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr<span class="emphasis"><em>
      xkb</em></span>
;            /* Xkb description in which to free controls components */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
which</em></span>
;            /* mask of components of <span class="emphasis"><em>
ctrls</em></span>
 to free */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
free_all</em></span>
;            /* <span class="emphasis"><em>
True</em></span>
 =&gt; free everything + ctrls itself */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbFreeControls</em></span>
 frees the specified components of the <span class="emphasis"><em>
ctrls</em></span>
 field in the <span class="emphasis"><em>
xkb</em></span>
 keyboard description and sets the corresponding structure component values to
<span class="emphasis"><em>
NULL</em></span>
 or <span class="emphasis"><em>
zero</em></span>
. The <span class="emphasis"><em>
which</em></span>
 mask specifies the fields of <span class="emphasis"><em>
ctrls</em></span>
 to be freed and can contain any of the controls components specified in Table
10.7.
</p><p>
If <span class="emphasis"><em>
free_all</em></span>
 is <span class="emphasis"><em>
True</em></span>
, <span class="emphasis"><em>
XkbFreeControls</em></span>
 frees every non-<span class="emphasis"><em>
NULL</em></span>
 structure component in the controls, frees the <span class="emphasis"><em>
XkbControlsRec</em></span>
 structure referenced by the <span class="emphasis"><em>
ctrls</em></span>
 member of <span class="emphasis"><em>
xkb</em></span>
, and sets <span class="emphasis"><em>
ctrls</em></span>
 to <span class="emphasis"><em>
NULL.</em></span>
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="The_Miscellaneous_Per_client_Controls"></a>The Miscellaneous Per-client Controls</h2></div></div></div><p>
You can configure the boolean per-client controls which affect the state
reported in button and key events. See section 12.1.1, 12.3, 12.5, and 16.3.11  
of the XKB Protocol specification for more details.
</p><p>
To get the current values of the <span class="emphasis"><em>
per-client</em></span>
 controls, use <span class="emphasis"><em>
XkbGetPerClientControls</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbGetPerClientControls</em></span>
(<span class="emphasis"><em>
dpy</em></span>
, <span class="emphasis"><em>
ctrls</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            <span class="emphasis"><em>
dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int *            <span class="emphasis"><em>
ctrls</em></span>
;            /* 1 bit =&gt; corresponding control is on */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetPerClientControls</em></span>
 backfills <span class="emphasis"><em>
ctrls</em></span>
 with the <span class="emphasis"><em>
per-client </em></span>
control attributes for this particular client. It returns <span class="emphasis"><em>
True</em></span>
 if successful, and <span class="emphasis"><em>
False</em></span>
 otherwise.
</p><p>
To change the current values of the <span class="emphasis"><em>
per-client</em></span>
 control attributes, use <span class="emphasis"><em>
XkbSetPerClientControls.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSetPerClientControls</em></span>
(<span class="emphasis"><em>
dpy</em></span>
, <span class="emphasis"><em>
ctrls</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            <span class="emphasis"><em>
dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
change</em></span>
;            /* 1 bit =&gt; change control */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int *            <span class="emphasis"><em>
value</em></span>
;            /* 1 bit =&gt; control on */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSetPerClientControls changes the per-client values for the controls selected
by </em></span>
<span class="emphasis"><em>
change to the corresponding value in value. Legal values for change and value
are: XkbPCF_GrabsUseXKBStateMask, XkbPCF_LookupStateWhenGrabbed, and
XkbPCF_SendEventUsesXKBState. More than one control may be changed at one time
by OR-ing the values together. XkbSetPerClientControls backfills value with the
</em></span>
<span class="emphasis"><em>
per-client </em></span>
<span class="emphasis"><em>
control attributes for this particular client. </em></span>
It returns <span class="emphasis"><em>
True</em></span>
 if successful, and <span class="emphasis"><em>
False</em></span>
 otherwise.
</p></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idp65821500" class="footnote"><p><a href="#idp65821500" class="para"><sup class="para">[4] </sup></a>
AccessDOS provides access to the DOS operating system for people with physical
impairments and was developed by the Trace R&amp;D Center at the University of
Wisconsin. For more information on AccessDOS, contact the Trace R&amp;D Center,
Waisman Center and Department of Industrial Engineering, University of
Wisconsin-Madison WI 53705-2280. Phone: 608-262-6966. e-mail: info@trace.wisc.edu.
</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="X_Library_Controls"></a>Chapter 11. X Library Controls</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Controls_Affecting_Keycode_to_String_Translation">Controls Affecting Keycode-to-String Translation</a></span></dt><dd><dl><dt><span class="sect2"><a href="#ForceLatin1Lookup">ForceLatin1Lookup</a></span></dt><dt><span class="sect2"><a href="#ConsumeLookupMods">ConsumeLookupMods</a></span></dt><dt><span class="sect2"><a href="#AlwaysConsumeShiftAndLock">AlwaysConsumeShiftAndLock</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Controls_Affecting_Compose_Processing">Controls Affecting Compose Processing</a></span></dt><dd><dl><dt><span class="sect2"><a href="#ConsumeKeysOnComposeFail">ConsumeKeysOnComposeFail</a></span></dt><dt><span class="sect2"><a href="#ComposeLED">ComposeLED</a></span></dt><dt><span class="sect2"><a href="#BeepOnComposeFail">BeepOnComposeFail</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Controls_Effecting_Event_Delivery">Controls Effecting Event Delivery</a></span></dt><dd><dl><dt><span class="sect2"><a href="#IgnoreNewKeyboards">IgnoreNewKeyboards</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Manipulating_the_Library_Controls">Manipulating the Library Controls</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Determining_Which_Library_Controls_are_Implemented">Determining Which Library Controls are Implemented</a></span></dt><dt><span class="sect2"><a href="#Determining_the_State_of_the_Library_Controls">Determining the State of the Library Controls</a></span></dt><dt><span class="sect2"><a href="#Changing_the_State_of_the_Library_Controls">Changing the State of the Library Controls</a></span></dt></dl></dd></dl></div><p>
The Xkb extension is composed of two parts: a server extension, and a
client-side X library extension. Chapter 10 discusses functions used to modify
controls affecting the behavior of the server portion of the Xkb extension.
This chapter discusses functions used to modify controls that affect only the
behavior of the client portion of the extension; these controls are known as
Library Controls.
</p><p>
All of the Library Controls are boolean flags that may be enabled and disabled.
The controls can be divided into several categories:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Controls affecting general string lookups
  </p></li><li class="listitem"><p>
Controls affecting compose processing
  </p></li><li class="listitem"><p>
Controls affecting event delivery
  </p></li></ul></div><p>
There are two types of string lookups performed by <span class="emphasis"><em>
XLookupString</em></span>
. The first type involves translating a single keycode into a string; the
controls in the first category affect this type of lookup. The second type
involves translating a series of keysyms into a string; the controls in the
second category affect this type of lookup.
</p><p>
An Xkb implementation is required to support the programming interface for all
of the controls. However, an implementation may choose not to support the
semantics associated with the controls that deal with compose processing. In
this case, a program that accesses these controls should still function
normally; however, the feedback that would normally occur with the controls
enabled may be missing.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Controls_Affecting_Keycode_to_String_Translation"></a>Controls Affecting Keycode-to-String Translation</h2></div></div></div><p>
The first type of string lookups, which are here called <span class="emphasis"><em>
simple string lookups</em></span>
, involves translating a single keycode into a string. Because these simple
lookups involve only a single keycode, all of the information needed to do the
translation is contained in the keyboard state in a single event. The controls
affecting simple string lookups are:
</p><pre class="programlisting">
     <span class="emphasis"><em>ForceLatin1Lookup</em></span>
     <span class="emphasis"><em>ConsumeLookupMods</em></span>
     <span class="emphasis"><em>LevelOneUsesShiftAndLock</em></span>
</pre><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="ForceLatin1Lookup"></a>ForceLatin1Lookup</h3></div></div></div><p>
If the <span class="emphasis"><em>
ForceLatin1Lookup</em></span>
 control is enabled, <span class="emphasis"><em>
XLookupString</em></span>
 only returns strings using the Latin1 character set. If <span class="emphasis"><em>
ForceLatin1Lookup</em></span>
 is not enabled, <span class="emphasis"><em>
XLookupString</em></span>
 can return characters that are not in the Latin1 set. By default, this control
is disabled, allowing characters outside of the Latin1 set to be returned.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="ConsumeLookupMods"></a>ConsumeLookupMods</h3></div></div></div><p>
Simple string lookups in <span class="emphasis"><em>
XLookupString</em></span>
 involve two different translation phases. The first phase translates raw
device keycodes to individual keysyms. The second phase attempts to map the
resulting keysym into a string of one or more characters. In the first phase,
some of the modifiers are normally used to determine the appropriate shift
level for a key.
</p><p>
The <span class="emphasis"><em>
ConsumeLookupMods</em></span>
 control determines whether or not <span class="emphasis"><em>
XLookupString</em></span>
 <span class="emphasis"><em>
consumes</em></span>
 the modifiers it uses during the first phase of processing (mapping a keycode
to a keysym). When a modifier is consumed, it is effectively removed from the
working copy of the keyboard state information <span class="emphasis"><em>
XLookupString</em></span>
 is using and appears to be unset for the remainder of the processing.
</p><p>
If the <span class="emphasis"><em>
ConsumeLookupMods</em></span>
 control is enabled, <span class="emphasis"><em>
XLookupString</em></span>
 does not use the modifiers used to translate the keycode of the event to a
keysym when it is determining the string associated with a keysym. For example,
assume the keymap for the ‘A’ key only contains the shift modifier and the
<span class="emphasis"><em>
ConsumeLookupMods</em></span>
 control is enabled. If a user presses the <span class="emphasis"><em>
Shift</em></span>
 key and the <span class="emphasis"><em>
A</em></span>
 key while the <span class="emphasis"><em>
Num_Lock</em></span>
 key is locked, <span class="emphasis"><em>
XLookupString</em></span>
 uses the <span class="emphasis"><em>
Shift</em></span>
 modifier when mapping the keycode for the ‘a’ key to the keysym for
‘A’; subsequently, it only uses the <span class="emphasis"><em>
NumLock</em></span>
 modifier when determining the string associated with the keysym ‘A’.
</p><p>
If the <span class="emphasis"><em>
ConsumeLookupMods</em></span>
 control is not enabled, <span class="emphasis"><em>
XLookupString</em></span>
 uses all of the event modifiers to determine the string associated with a
keysym. This behavior mirrors the behavior of <span class="emphasis"><em>
XLookupString</em></span>
 in the core implementation.
</p><p>
The <span class="emphasis"><em>
ConsumeLookupMods</em></span>
 control is unset by default. For more information on modifier consumption,
refer to Chapter 12.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="AlwaysConsumeShiftAndLock"></a>AlwaysConsumeShiftAndLock</h3></div></div></div><p>
The <span class="emphasis"><em>
AlwaysConsumeShiftAndLock</em></span>
 control, if enabled, forces <span class="emphasis"><em>
XLookupString</em></span>
 to consume the <span class="emphasis"><em>
Shift</em></span>
 and <span class="emphasis"><em>
Lock</em></span>
 modifiers when processing all keys, even if the definition for the key type
does not specify these modifiers. The <span class="emphasis"><em>
AlwaysConsumeShiftAndLock</em></span>
 control is unset by default. See section 15.2 for a discussion of key types.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Controls_Affecting_Compose_Processing"></a>Controls Affecting Compose Processing</h2></div></div></div><p>
The second type of string lookup performed by <span class="emphasis"><em>
XLookupString</em></span>
 involves translating a series of keysyms into a string. Because these lookups
can involve more than one key event, they require <span class="emphasis"><em>
XLookupString</em></span>
 to retain some state information between successive calls. The process of
mapping a series of keysyms to a string is known as <span class="emphasis"><em>
compose processing</em></span>
. The controls affecting compose processing are:
</p><pre class="programlisting">
<span class="emphasis"><em>ConsumeKeysOnComposeFail</em></span>
<span class="emphasis"><em>ComposeLED</em></span>
<span class="emphasis"><em>BeepOnComposeFail</em></span>
</pre><p>
Because different vendors have historically used different algorithms to
implement compose processing, and these algorithms may be incompatible with the
semantics required by the Xkb compose processing controls, implementation of
the compose processing controls is optional in an Xkb implementation.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="ConsumeKeysOnComposeFail"></a>ConsumeKeysOnComposeFail</h3></div></div></div><p>
Some compose processing algorithms signal the start of a compose sequence by a
key event meaning "start compose".
<a href="#ftn.idp65462196" class="footnote" id="idp65462196"><sup class="footnote">[5]</sup></a>
The subsequent key events should normally result in a valid composition yielding a
valid translation to a string. If the subsequent key events do not have a valid
translation, some decision must be made about what to do with the key events
that were processed while attempting the compose. The <span class="emphasis"><em>
ConsumeKeysOnComposeFail</em></span>
 control allows a client to specify what happens with the key events <span class="emphasis"><em>
XLookupString</em></span>
 has been considering when it reaches a dead end in a compose sequence.
</p><p>
If the <span class="emphasis"><em>
ConsumeKeysOnComposeFail</em></span>
 control is set, all keys associated with a failed compose sequence should be
consumed (discarded). If the <span class="emphasis"><em>
ConsumeKeysOnComposeFail</em></span>
 control is not set, the key events associated with a failed compose sequence
should be processed as a normal sequence of key events.
</p><p>
The <span class="emphasis"><em>
ConsumeKeysOnComposeFail</em></span>
 control is disabled by default.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="ComposeLED"></a>ComposeLED</h3></div></div></div><p>
The <span class="emphasis"><em>
ComposeLED</em></span>
 control allows a client to specify whether or not an indicator should be set
and cleared to provide feedback when compose processing is in progress. The
control does not specify which indicator should be used; the mapping for this
is up to the individual implementation. If the <span class="emphasis"><em>
ComposeLED</em></span>
 control is enabled, it specifies that an indicator should be set when a
compose sequence is in progress and cleared when one is not in progress. The
<span class="emphasis"><em>
ComposeLED</em></span>
 control is disabled by default.
</p><p>
While the Xkb extension does not specify the type of type of indicator to be
used when the <span class="emphasis"><em>
ComposeLED</em></span>
 control is implemented, a consistent convention between implementations is to
everyone’s benefit. If a named indicator is used for this purpose, the
recommended name is "<span class="emphasis"><em>
Compose</em></span>
". Note that some implementations may use an unnamed, custom hardware LED for
this purpose.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="BeepOnComposeFail"></a>BeepOnComposeFail</h3></div></div></div><p>
The <span class="emphasis"><em>
BeepOnComposeFail</em></span>
 control allows a client to specify whether or not a bell should be activated
to provide feedback when a compose sequence fails. The control does not specify
the type of bell that should be used; the mapping for this is up to the
individual implementation. If the <span class="emphasis"><em>
BeepOnComposeFail</em></span>
 control is enabled, it specifies that a bell should be activated when a
compose sequence fails. The <span class="emphasis"><em>
BeepOnComposeFail</em></span>
 control is disabled by default. If implemented, the bell should be activated
using <span class="emphasis"><em>
XkbBell</em></span>
 or <span class="emphasis"><em>
XkbDeviceBell</em></span>
.
</p><p>
While the Xkb extension does not specify the type of bell to be used when the
<span class="emphasis"><em>
BeepOnComposeFail</em></span>
 control is implemented, a consistent convention between implementations is to
everyone’s benefit. If a named bell is used for this purpose, the recommended
name is "<span class="emphasis"><em>
ComposeFail</em></span>
".
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Controls_Effecting_Event_Delivery"></a>Controls Effecting Event Delivery</h2></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="IgnoreNewKeyboards"></a>IgnoreNewKeyboards</h3></div></div></div><p>
When Xkb is initialized, it implicitly forces requests for <span class="emphasis"><em>
NewKeyboardNotify</em></span>
 events. These events may be used by the Xkb library extension internally; they
are normally translated into core protocol <span class="emphasis"><em>
MappingNotify</em></span>
 events before being passed to the client. While delivering the event to the
client is appropriate in most cases, it is not appropriate for some clients
that maintain per-key data structures. This is because once the server has sent
a <span class="emphasis"><em>
NewKeyboardNotify</em></span>
 event, it is free to send the client events for all keys in the new range and
that range may be outside of the per-key data structures the client is
maintaining.
</p><p>
The <span class="emphasis"><em>
IgnoreNewKeyboards</em></span>
 control, if enabled, prevents Xkb from mapping <span class="emphasis"><em>
NewKeyboardNotify</em></span>
 events to core <span class="emphasis"><em>
MappingNotify</em></span>
 events and passing them to the client. The control is initially disabled.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Manipulating_the_Library_Controls"></a>Manipulating the Library Controls</h2></div></div></div><p>
The Library Controls are manipulated using functions that deal with bitmasks to
indicate which controls to manipulate. The controls are identified by the masks
defined in Table 11.1. 
</p><div class="table"><a id="idp64831356"></a><p class="title"><strong>Table 11.1. Library Control Masks</strong></p><div class="table-contents"><table summary="Library Control Masks" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Library Control Mask</th><th align="left">Value</th></tr></thead><tbody><tr><td align="left">XkbLC_ForceLatin1Lookup</td><td align="left">(1 &lt;&lt; 0)</td></tr><tr><td align="left">XkbLC_ConsumeLookupMods</td><td align="left">(1 &lt;&lt; 1)</td></tr><tr><td align="left">XkbLC_AlwaysConsumeShiftAndLock</td><td align="left">(1 &lt;&lt; 2)</td></tr><tr><td align="left">XkbLC_IgnoreNewKeyboards</td><td align="left">(1 &lt;&lt; 3)</td></tr><tr><td align="left">XkbLC_ConsumeKeysOnComposeFail</td><td align="left">(1 &lt;&lt; 29)</td></tr><tr><td align="left">XkbLC_ComposeLED</td><td align="left">(1 &lt;&lt; 30)</td></tr><tr><td align="left">XkbLC_BeepOnComposeFail</td><td align="left">(1 &lt;&lt; 31)</td></tr><tr><td align="left">XkbLC_AllControls</td><td align="left">(0xc0000007)</td></tr></tbody></table></div></div><br class="table-break" /><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Determining_Which_Library_Controls_are_Implemented"></a>Determining Which Library Controls are Implemented</h3></div></div></div><p>
To determine which Library Controls are actually
implemented, use <span class="emphasis"><em>XkbXlibControlsImplemented</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
unsigned int <span class="emphasis"><em>
XkbXlibControlsImplemented</em></span>
(<span class="emphasis"><em>
display</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            display</em></span>
;                  /* connection to X server */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbXlibControlsImplemented</em></span>
 returns a bitmask indicating the controls actually implemented in the Xkb
library and is composed of an inclusive OR of bits from Table 11.1.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Determining_the_State_of_the_Library_Controls"></a>Determining the State of the Library Controls</h3></div></div></div><p>
To determine the current state of the Library Controls, use <span class="emphasis"><em>
XkbGetXlibControls</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
unsigned int <span class="emphasis"><em>
XkbGetXlibControls</em></span>
(<span class="emphasis"><em>
display</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            display</em></span>
;                  /* connection to X server */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetXlibControls</em></span>
 returns the current state of the Library Controls as a bit mask that is an
inclusive OR of the control masks from Table 11.1 for the controls that are
enabled. For the optional compose processing controls, the fact that a control
is enabled does not imply that it is actually implemented.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Changing_the_State_of_the_Library_Controls"></a>Changing the State of the Library Controls</h3></div></div></div><p>
To change the state of the Library Controls, use
<span class="emphasis"><em>XkbSetXlibControls</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSetXlibControls</em></span>
(<span class="emphasis"><em>
display, bits_to_change, values_for_bits</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            display</em></span>
;                  /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned long            <span class="emphasis"><em>
bits_to_change</em></span>
;                  /* selects controls to be modified */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned long            <span class="emphasis"><em>
values_for_bits</em></span>
;                  /* turns selected controls on (1) or off (0) */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSetXlibControls</em></span>
 modifies the state of the controls selected by <span class="emphasis"><em>
bits_to_change</em></span>
; only the controls selected by <span class="emphasis"><em>
bits_to_change</em></span>
 are modified. If the bit corresponding to a control is on in <span class="emphasis"><em>
bits_to_change</em></span>
 and also on in values_for_bits, the control is enabled. If the bit
corresponding to a control is on in <span class="emphasis"><em>
bits_to_change</em></span>
 but off in <span class="emphasis"><em>
values_for_bits</em></span>
, the control is disabled. <span class="emphasis"><em>
bits_to_change</em></span>
 should be an inclusive OR of bits from Table 11.1.
</p></div></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idp65462196" class="footnote"><p><a href="#idp65462196" class="para"><sup class="para">[5] </sup></a>
Another possibility is to have the compose processing simply be the result of a finite state acceptor; a compose sequence would never fail for a properly written finite state acceptor.
</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Interpreting_Key_Events"></a>Chapter 12. Interpreting Key Events</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Effects_of_Xkb_on_the_Core_X_Library">Effects of Xkb on the Core X Library</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Effects_of_Xkb_on_Event_State">Effects of Xkb on Event State</a></span></dt><dt><span class="sect2"><a href="#Effects_of_Xkb_on_MappingNotify_Events">Effects of Xkb on MappingNotify Events</a></span></dt><dt><span class="sect2"><a href="#X_Library_Functions_Affected_by_Xkb">X Library Functions Affected by Xkb</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Xkb_Event_and_Keymap_Functions">Xkb Event and Keymap Functions</a></span></dt></dl></div><p>
Xkb provides functions to help developers interpret key events without having
to directly interpret Xkb data structures. Xkb also modifies the behavior of
several core X library functions.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Effects_of_Xkb_on_the_Core_X_Library"></a>Effects of Xkb on the Core X Library</h2></div></div></div><p>
When support for Xkb is built into the X library, the <span class="emphasis"><em>
XOpenDisplay</em></span>
 function looks for a compatible version of Xkb on the server. If it finds a
compatible version, it initializes the extension and enables <span class="emphasis"><em>
implicit support</em></span>
 for Xkb in a number of X library functions. This makes it possible for clients
to take advantage of nearly all Xkb features without having to be rewritten or
even recompiled, if they are built with shared libraries. This implicit support
is invisible to most clients, but it can have side effects, so the extension
includes ways to control or disable it.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Effects_of_Xkb_on_Event_State"></a>Effects of Xkb on Event State</h3></div></div></div><p>
Because <span class="emphasis"><em>
XOpenDisplay</em></span>
 initializes Xkb, some events contain an Xkb description of the keyboard state
instead of that normally used by the core protocol. See section 17.1.1 for more
information about the differences between Xkb keyboard state and that reported
by the core protocol.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Effects_of_Xkb_on_MappingNotify_Events"></a>Effects of Xkb on MappingNotify Events</h3></div></div></div><p>
When Xkb is missing or disabled, the X library tracks changes to the keyboard
mapping using <span class="emphasis"><em>
MappingNotify</em></span>
 events. Whenever the keyboard mapping is changed, the server sends all clients
a <span class="emphasis"><em>
MappingNotify</em></span>
 event to report the change. When a client receives a <span class="emphasis"><em>
MappingNotify</em></span>
 event, it is supposed to call <span class="emphasis"><em>
XRefreshKeyboardMapping</em></span>
 to update the keyboard description used internally by the X library.
</p><p>
The X Keyboard Extension uses <span class="emphasis"><em>
XkbMapNotify</em></span>
 and <span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
 events to track changes to the keyboard mapping. When an Xkb-aware client
receives either event, it should call <span class="emphasis"><em>
XkbRefreshKeyboardMapping</em></span>
 to update the keyboard description used internally by the X library. To avoid
duplicate events, the X server does not send core protocol <span class="emphasis"><em>
MappingNotify</em></span>
 events to a client that has selected for <span class="emphasis"><em>
XkbMapNotify</em></span>
 events.
</p><p>
The implicit support for Xkb selects for <span class="emphasis"><em>
XkbMapNotify</em></span>
 events. This means that clients that do not explicitly use Xkb but that are
using a version of the X library that has implicit support for Xkb do not
receive <span class="emphasis"><em>
MappingNotify</em></span>
 events over the wire. Clients that were not written with Xkb in mind do not
recognize or properly handle the new Xkb events, so the implicit support
converts them to <span class="emphasis"><em>
MappingNotify</em></span>
 events that report approximately the same information, unless the client has
explicitly selected for the Xkb version of the event.
</p><p>
An Xkb-capable X server does not send events from keys that fall outside the
legal range of keycodes expected by that client. Once the server sends a client
an <span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
 event, it reports events from all keys because it assumes that any client that
has receieved an <span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
 event expects key events from the new range of keycodes. The implicit support
for Xkb asks for <span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
 events, so the range of keycodes reported to the client might vary without the
client’s knowledge. Most clients don’t really care about the range of legal
keycodes, but some clients maintain information about each key and might have
problems with events that come from unexpected keys. Such clients can set the
<span class="emphasis"><em>
XkbLC_IgnoreNewKeyboards</em></span>
 library control (see section 11.3.1) to prevent the implicit support from
requesting notification of changes to the legal range of keycodes.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="X_Library_Functions_Affected_by_Xkb"></a>X Library Functions Affected by Xkb</h3></div></div></div><p>
The following X library functions are modified by Xkb:
</p><pre class="programlisting">
     <span class="emphasis"><em>XKeycodeToKeysym</em></span>
     <span class="emphasis"><em>XKeysymToKeycode</em></span>
     <span class="emphasis"><em>XLookupKeysym</em></span>
     <span class="emphasis"><em>XLookupString</em></span>
     <span class="emphasis"><em>XRefreshKeyboardMapping</em></span>
     <span class="emphasis"><em>XRebindKeysym</em></span>
</pre><p>
The implicit support for Xkb replaces a number of X library functions with
versions that understand and use the X Keyboard Extension. In most cases, the
semantics of the new versions are identical to those of the old, but there are
occasional visible differences. This section lists all of the functions that
are affected and the differences in behavior, if any, that are visible to
clients.
</p><p>
The <span class="emphasis"><em>
XKeycodeToKeysym</em></span>
 function reports the keysym associated with a particular index for a single
key. The index specifies a column of symbols in the core keyboard mapping (that
is, as reported by the core protocol <span class="emphasis"><em>
GetKeyboardMapping</em></span>
 request). The order of the symbols in the core mapping does not necessarily
correspond to the order of the symbols used by Xkb; section 17.1.3 describes
the differences.
</p><p>
The <span class="emphasis"><em>
XKeysymToKeycode</em></span>
 function reports a keycode to which a particular keysym is bound. When Xkb is
missing or disabled, this function looks in each column of the core keyboard
mapping in turn and returns the lowest numbered key that matches in the lowest
numbered group. When Xkb is present, this function uses the Xkb ordering for
symbols instead.
</p><p>
The <span class="emphasis"><em>
XLookupKeysym</em></span>
 function reports the symbol in a specific column of the key associated with an
event. Whether or not Xkb is present, the column specifies an index into the
core symbol mapping.
</p><p>
The <span class="emphasis"><em>
XLookupString</em></span>
 function reports the symbol and string associated with a key event, taking
into account the keycode and keyboard state as reported in the event. When Xkb
is disabled or missing, <span class="emphasis"><em>
XLookupString</em></span>
 uses the rules specified by the core protocol and reports only ISO Latin-1
characters. When Xkb is present, <span class="emphasis"><em>
XLookupString</em></span>
 uses the explicit keyboard group, key types, and rules specified by Xkb. When
Xkb is present, <span class="emphasis"><em>
XLookupString</em></span>
 is allowed, but not required, to return strings in character sets other than
ISO Latin-1, depending on the current locale. If any key bindings are defined,
<span class="emphasis"><em>
XLookupString</em></span>
 does not use any consumed modifiers (see sections 11.1.2 and 15.2) to
determine matching bindings.
</p><p>
The <span class="emphasis"><em>
XRefreshKeyboardMapping</em></span>
 function updates the X library’s internal representation of the keyboard to
reflect changes reported via <span class="emphasis"><em>
MappingNotify</em></span>
 events. When Xkb is missing or disabled, this function reloads the entire
modifier map or keyboard mapping. When Xkb is present, the implicit Xkb support
keeps track of the changed components reported by each <span class="emphasis"><em>
XkbMapNotify</em></span>
 event and updates only those pieces of the keyboard description that have
changed. If the implicit support has not noted any keyboard mapping changes,
<span class="emphasis"><em>
XRefreshKeyboardMapping</em></span>
 updates the entire keyboard description.
</p><p>
The <span class="emphasis"><em>
XRebindKeysym</em></span>
 function associates a string with a keysym and a set of modifiers. Xkb does
not directly change this function, but it does affect the way that the state
reported in the event is compared to the state specified to <span class="emphasis"><em>
XRebindKeysym</em></span>
. When Xkb is missing or disabled, <span class="emphasis"><em>
XLookupString</em></span>
 returns the specified string if the modifiers in the event exactly match the
modifiers from this call. When Xkb is present, any modifiers used to determine
the keysym are consumed and are not used to look up the string.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Xkb_Event_and_Keymap_Functions"></a>Xkb Event and Keymap Functions</h2></div></div></div><p>
To find the keysym bound to a particular key at a specified group and shift
level, use <span class="emphasis"><em>XkbKeycodeToKeysym</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
KeySym <span class="emphasis"><em>
XkbKeycodeToKeysym</em></span>
(<span class="emphasis"><em>
dpy, kc, group, level</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            dpy;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode            kc;            /* key of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            group;            /* group of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            level;            /* shift level of interest */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbKeycodeToKeysym</em></span>
 returns the keysym bound to a particular group and shift level for a
particular key on the core keyboard. If <span class="emphasis"><em>
kc</em></span>
 is not a legal keycode for the core keyboard, or if <span class="emphasis"><em>
group</em></span>
 or <span class="emphasis"><em>
level</em></span>
 are out of range for the specified key, <span class="emphasis"><em>
XkbKeycodeToKeysym</em></span>
 returns <span class="emphasis"><em>
NoSymbol</em></span>
.
</p><p>
To find the set of modifiers bound to a particular keysym on the core keyboard,
use <span class="emphasis"><em>
XkbKeysymToModifiers</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
unsigned<span class="emphasis"><em>
 </em></span>
int <span class="emphasis"><em>
XkbKeysymToModifiers</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 ks</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
KeySym <span class="emphasis"><em>
            ks</em></span>
;            /* keysym of interest */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbKeysymToModifiers</em></span>
 finds the set of modifiers currently bound to the keysym <span class="emphasis"><em>
ks</em></span>
 on the core keyboard. The value returned is the mask of modifiers bound to the
keysym <span class="emphasis"><em>
ks</em></span>
. If no modifiers are bound to the keysym, <span class="emphasis"><em>
XkbKeysymToModifiers</em></span>
 returns zero; otherwise, it returns the inclusive OR of zero or more of the
following: <span class="emphasis"><em>
ShiftMask</em></span>
, <span class="emphasis"><em>
ControlMask</em></span>
, <span class="emphasis"><em>
LockMask</em></span>
, <span class="emphasis"><em>
Mod1Mask</em></span>
, <span class="emphasis"><em>
Mod2Mask</em></span>
, <span class="emphasis"><em>
Mod3Mask</em></span>
, <span class="emphasis"><em>
Mod4Mask,</em></span>
 and <span class="emphasis"><em>
Mod5Mask</em></span>
.
</p><p>
Use <span class="emphasis"><em>
XkbLookupKeySym</em></span>
 to find the symbol associated with a key for a particular state.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbLookupKeySym</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 key</em></span>
,<span class="emphasis"><em>
 state</em></span>
,<span class="emphasis"><em>
 mods_rtrn</em></span>
,<span class="emphasis"><em>
 sym_rtrn</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display * <span class="emphasis"><em>
            dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode <span class="emphasis"><em>
            key</em></span>
;            /* key for which symbols are to be found */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int <span class="emphasis"><em>
            state</em></span>
;            /* state for which symbol should be found */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int * <span class="emphasis"><em>
            mods_rtrn</em></span>
;            /* backfilled with unconsumed modifiers */
    </td></tr><tr><td class="functionargdecl" align="left">
KeySym *<span class="emphasis"><em>
            sym_rtrn</em></span>
;            /* backfilled with symbol associated with key + state */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbLookupKeySym</em></span>
 is the equivalent of the core <span class="emphasis"><em>
XLookupKeySym</em></span>
 function. For the core keyboard, given a keycode <span class="emphasis"><em>
key</em></span>
 and an Xkb state <span class="emphasis"><em>
state</em></span>
, <span class="emphasis"><em>
XkbLookupKeySym</em></span>
 returns the symbol associated with the key  in <span class="emphasis"><em>
sym_rtrn</em></span>
 and the list of modifiers that should still be applied in <span class="emphasis"><em>
mods_rtrn</em></span>
. The <span class="emphasis"><em>
state</em></span>
 parameter is the state from a <span class="emphasis"><em>
KeyPress</em></span>
 or <span class="emphasis"><em>
KeyRelease</em></span>
 event. <span class="emphasis"><em>
XkbLookupKeySym</em></span>
 returns <span class="emphasis"><em>
True</em></span>
 if it succeeds.
</p><p>
Use <span class="emphasis"><em>
XkbLookupKeyBinding</em></span>
 to find the string bound to a key by <span class="emphasis"><em>
XRebindKeySym</em></span>
. <span class="emphasis"><em>
XkbLookupKeyBinding</em></span>
 is the equivalent of the core <span class="emphasis"><em>
XLookupString</em></span>
 function.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
int <span class="emphasis"><em>
XkbLookupKeyBinding</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 sym</em></span>
,<span class="emphasis"><em>
 state</em></span>
,<span class="emphasis"><em>
 buf</em></span>
,<span class="emphasis"><em>
 nbytes</em></span>
,<span class="emphasis"><em>
 extra_rtrn</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display * <span class="emphasis"><em>
            dpy</em></span>
;            /* connection to server */
    </td></tr><tr><td class="functionargdecl" align="left">
KeySym<span class="emphasis"><em>
            sym</em></span>
;            /* symbol to be looked up */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
state</em></span>
;            /* state for which string is to be looked up */
    </td></tr><tr><td class="functionargdecl" align="left">
char * <span class="emphasis"><em>
            buf</em></span>
;            /* buffer into which returned string is written */
    </td></tr><tr><td class="functionargdecl" align="left">
int <span class="emphasis"><em>
            nbytes</em></span>
;            /* size of buffer in bytes */
    </td></tr><tr><td class="functionargdecl" align="left">
int * <span class="emphasis"><em>
            extra_rtrn</em></span>
;            /* backfilled with number bytes overflow */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XRebindKeysym</em></span>
 binds an ASCII string to a specified keysym, so that the string and keysym are
returned when the key is pressed and a specified list of modifiers are also
being held down. <span class="emphasis"><em>
XkbLookupKeyBinding</em></span>
 returns in <span class="emphasis"><em>
buf</em></span>
 the string associated with the keysym <span class="emphasis"><em>
sym</em></span>
 and modifier state <span class="emphasis"><em>
state</em></span>
. <span class="emphasis"><em>
buf</em></span>
 is <span class="emphasis"><em>
NULL</em></span>
 terminated unless there’s an overflow. If the string returned is larger than
<span class="emphasis"><em>
nbytes</em></span>
, a count of bytes that does not fit into the buffer is returned in extra_rtrn.
<span class="emphasis"><em>
XkbTranslateKeySym</em></span>
 returns the number of bytes that it placed into <span class="emphasis"><em>
buf</em></span>
.
</p><p>
To find the string and symbol associated with a keysym for a given keyboard
state, use <span class="emphasis"><em>
XkbTranslateKeySym</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
int <span class="emphasis"><em>
XkbTranslateKeySym</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 sym_inout</em></span>
,<span class="emphasis"><em>
 mods</em></span>
,<span class="emphasis"><em>
 buf</em></span>
,<span class="emphasis"><em>
 nbytes</em></span>
, <span class="emphasis"><em>
extra_rtrn</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display * <span class="emphasis"><em>
            dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
KeySym * <span class="emphasis"><em>
            sym_inout</em></span>
;            /* symbol to be translated; result of translation */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int <span class="emphasis"><em>
            mods</em></span>
;            /* modifiers to apply to <span class="emphasis"><em>
sym_inout</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
char * <span class="emphasis"><em>
            buf</em></span>
;            /* buffer into which returned string is written */
    </td></tr><tr><td class="functionargdecl" align="left">
int <span class="emphasis"><em>
            nbytes</em></span>
;            /* size of buffer in bytes */
    </td></tr><tr><td class="functionargdecl" align="left">
int *<span class="emphasis"><em>
            extra_rtrn</em></span>
;            /* number of bytes overflow*/
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbTranslateKeySym</em></span>
 applies the transformations specified in <span class="emphasis"><em>
mods</em></span>
 to the symbol specified by <span class="emphasis"><em>
sym_inout</em></span>
. It returns in <span class="emphasis"><em>
buf</em></span>
 the string, if any, associated with the keysym for the current locale. If the
transformations in <span class="emphasis"><em>
mods</em></span>
 changes the keysym, <span class="emphasis"><em>
sym_inout</em></span>
 is updated accordingly. If the string returned is larger than <span class="emphasis"><em>
nbytes</em></span>
, a count of bytes that does not fit into the buffer is returned in extra_rtrn.
<span class="emphasis"><em>
XkbTranslateKeySym</em></span>
 returns the number of bytes it placed into <span class="emphasis"><em>
buf</em></span>
.
</p><p>
To update the keyboard description that is internal to the X library, use
<span class="emphasis"><em>
XkbRefreshKeyboardMapping</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbRefreshKeyboardMapping</em></span>
(<span class="emphasis"><em>
event)</em></span>
    </td></tr><tr><td class="functionargdecl" align="left">
XkbMapNotifyEvent * <span class="emphasis"><em>
            event</em></span>
;            /* event initiating remapping */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbRefreshKeyboardMapping</em></span>
 is the Xkb equivalent of the core <span class="emphasis"><em>
XRefreshKeyboardMapping</em></span>
 function. It requests that the X server send the current key mapping
information to this client. A client usually invokes <span class="emphasis"><em>
XkbRefreshKeyboardMapping</em></span>
 after receiving an <span class="emphasis"><em>
XkbMapNotify</em></span>
 event. <span class="emphasis"><em>
XkbRefreshKeyboardMapping</em></span>
 returns <span class="emphasis"><em>
Success</em></span>
 if it succeeds and <span class="emphasis"><em>
BadMatch</em></span>
 if the event is not an Xkb event.
</p><p>
The <span class="emphasis"><em>
XkbMapNotify</em></span>
 event can be generated when some client calls <span class="emphasis"><em>
XkbSetMap</em></span>
, <span class="emphasis"><em>
XkbChangeMap</em></span>
, <span class="emphasis"><em>
XkbGetKeyboardByName</em></span>
, or any of the standard X library functions that change the keyboard mapping
or modifier mapping.
</p><p>
To translate a keycode to a key symbol and modifiers, use <span class="emphasis"><em>
XkbTranslateKeyCode</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Booll <span class="emphasis"><em>
XkbTranslateKeyCode</em></span>
(<span class="emphasis"><em>
xkb, key, mods, mods_rtrn, keysym_rtrn)</em></span>
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;            /* keyboard description to use for translation */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode            <span class="emphasis"><em>
key</em></span>
;            /* keycode to translate */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
mods</em></span>
;            /* modifiers to apply when translating <span class="emphasis"><em>
key</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int *            <span class="emphasis"><em>
mods_rtrn</em></span>
;            /* backfilled with unconsumed modifiers */
    </td></tr><tr><td class="functionargdecl" align="left">
KeySym *            <span class="emphasis"><em>
keysym_rtrn</em></span>
;            /* keysym resulting from translation */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
mods_rtrn</em></span>
 is backfilled with the modifiers consumed by the translation process.
<span class="emphasis"><em>
mods</em></span>
 is a bitwise inclusive OR of the legal modifier masks: <span class="emphasis"><em>
ShiftMask</em></span>
, <span class="emphasis"><em>
LockMask</em></span>
, <span class="emphasis"><em>
ControlMask</em></span>
, <span class="emphasis"><em>
Mod1Mask</em></span>
, <span class="emphasis"><em>
Mod2Mask</em></span>
, <span class="emphasis"><em>
Mod3Mask</em></span>
, <span class="emphasis"><em>
Mod4Mask</em></span>
, <span class="emphasis"><em>
Mod5Mask</em></span>
.The <span class="emphasis"><em>
AlwaysConsumeShiftAndLock</em></span>
 library control (see section 11.1.3), if enabled, causes <span class="emphasis"><em>
XkbTranslateKeyCode</em></span>
 to consume shift and lock.<span class="emphasis"><em>
 XkbTranslateKeyCode</em></span>
 returns <span class="emphasis"><em>
True</em></span>
 if the translation resulted in a keysym, and <span class="emphasis"><em>
False</em></span>
 if it resulted in <span class="emphasis"><em>
NoSymbol</em></span>
.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Keyboard_Geometry"></a>Chapter 13. Keyboard Geometry</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Shapes_and_Outlines">Shapes and Outlines</a></span></dt><dt><span class="sect1"><a href="#Sections">Sections</a></span></dt><dt><span class="sect1"><a href="#Rows_and_Keys">Rows and Keys</a></span></dt><dt><span class="sect1"><a href="#Doodads">Doodads</a></span></dt><dt><span class="sect1"><a href="#Overlay_Rows_and_Overlay_Keys">Overlay Rows and Overlay Keys</a></span></dt><dt><span class="sect1"><a href="#Drawing_a_Keyboard_Representation">Drawing a Keyboard Representation</a></span></dt><dt><span class="sect1"><a href="#Geometry_Data_Structures">Geometry Data Structures</a></span></dt><dd><dl><dt><span class="sect2"><a href="#DoodadRec_Structures">DoodadRec Structures</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Getting_Keyboard_Geometry_From_the_Server">Getting Keyboard Geometry From the Server</a></span></dt><dt><span class="sect1"><a href="#Using_Keyboard_Geometry">Using Keyboard Geometry</a></span></dt><dt><span class="sect1"><a href="#Adding_Elements_to_a_Keyboard_Geometry">Adding Elements to a Keyboard Geometry</a></span></dt><dt><span class="sect1"><a href="#Allocating_and_Freeing_Geometry_Components">Allocating and Freeing Geometry Components</a></span></dt></dl></div><p>
The Xkb description of a keyboard includes an optional keyboard geometry that
describes the physical appearance of the keyboard. Keyboard geometry describes
the shape, location, and color of all keyboard keys or other visible keyboard
components such as indicators. The information contained in a keyboard geometry
is sufficient to allow a client program to draw an accurate two-dimensional
image of the keyboard.
</p><p>
You can retrieve a keyboard geometry from an X server that supports Xkb, or you
can allocate it from scratch and initialize it in a client program. The
keyboard geometry need not have any correspondence with the physical keyboard
that is connected to the X server.
</p><p>
Geometry measurements are specified in mm/10 units. The origin (0,0) is in the
top left corner of the keyboard image. A component’s own origin is also its
upper left corner. In some cases a component needs to be drawn rotated. For
example, a special keyboard may have a section of keys arranged in rows in a
rectangular area, but the entire rectangle may not be in alignment with the
rest of the keyboard, and instead, it is rotated from horizontal by 30<span class="emphasis"><em>
o</em></span>
. Rotation for a geometry object is specified in 1/10 o increments about its
origin. An example of a keyboard with rotated sections is shown in Figure 13.1.
</p><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-7.svg"></object><div class="caption">Rotated Keyboard Sections</div></div><p>
Some geometry components include a <span class="emphasis"><em>
priority</em></span>
, which indicates the order in which overlapping objects should be drawn.
Objects should be drawn in order from highest priority (0) to lowest (255).
</p><p>
The keyboard geometry’s top-level description is stored in a <span class="emphasis"><em>
XkbGeometryRec</em></span>
 structure. This structure contains three types of information:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Lists of items, not used to draw the basic keyboard, but indexed by the
geometry descriptions that comprise the entire keyboard geometry (colors,
geometry properties, key aliases, shapes)
    </p></li><li class="listitem"><p>
A number of singleton items that describe the keyboard as a whole (keyboard
name, width and height, a color for the keyboard as a whole, and a color for
keyboard key labels)
    </p></li><li class="listitem"><p>
A list of the keyboard’s sections and nonkey doodads
    </p></li></ol></div><p>
The top-level geometry is described in more detail in the following.
</p><p>
The lists of items used by components of the keyboard geometry description is
as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The top-level keyboard geometry description includes a list of up to <span class="emphasis"><em>
MaxColors</em></span>
 (32) <span class="emphasis"><em>
color names</em></span>
. A color name is a string whose interpretation is not specified by Xkb. The
<span class="emphasis"><em>
XkbColorRec</em></span>
 structure provides a field for this name as well as a pixel field. The pixel
field is a convenient place for an application to store a pixel value or color
definition, if it needs to. All other geometry data structures refer to colors
using their indices in this global list.
  </p></li><li class="listitem"><p>
The top-level keyboard geometry description includes a list of <span class="emphasis"><em>
geometry properties</em></span>
. A geometry property associates an arbitrary string with an equally arbitrary
name. Geometry properties can be used to provide hints to programs that display
images of keyboards, but they are not interpreted by Xkb. No other geometry
structures refer to geometry properties. As an example of a possible use of
<span class="emphasis"><em>
properties</em></span>
, consider the pause/break key on most PC keyboards: the "break" symbol is
usually on the front of the key and is often a different color. A program might
set a property to:
  </p><p>
LBL_PAUS = "{Pause/top/black,Break/front/red}"
  </p><p>
and use the property information to draw the key with a front label as well as
a top label.
  </p></li><li class="listitem"><p>
The top-level keyboard geometry description includes a list of <span class="emphasis"><em>
key aliases</em></span>
 (see Chapter 18). Key aliases allow the keyboard layout designer to assign
multiple key names to a single key.
  </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Key aliases defined in the geometry component of a keyboard mapping
override those defined in the keycodes component of the server database, which
are stored in the <span class="emphasis"><em>
XkbNamesRec</em></span>
 (<span class="emphasis"><em>
xkb-&gt;names</em></span>
). Therefore, consider the key aliases defined by the geometry before
considering key aliases supplied by the keycodes.</p></div></li><li class="listitem"><p>
The top-level keyboard geometry description includes a list of <span class="emphasis"><em>
shapes</em></span>
; other keyboard components refer to shapes by their index in this list. A
shape consists of an arbitrary name of type Atom and one or more closed-polygon
<span class="emphasis"><em>
outlines</em></span>
. All points in an outline are specified relative to the origin of its
enclosing shape, that is, whichever shape that contains this outline in its
list of outlines. One outline is the primary outline. The primary outline is by
default the first outline, or it can be optionally specified by the <span class="emphasis"><em>
primary</em></span>
 field in the <span class="emphasis"><em>
XkbShapeRec</em></span>
 structure. A keyboard display application can generate a simpler but still
accurate keyboard image by displaying only the primary outlines for each shape.
Nonrectangular keys must include a rectangular <span class="emphasis"><em>
approximation</em></span>
 as one of the outlines associated with the shape. The approximation is not
normally displayed but can be used by very simple keyboard display applications
to generate a recognizable but degraded image of the keyboard.
  </p></li></ul></div><p>
The <span class="emphasis"><em>
XkbGeometryRec</em></span>
 top-level geometry description contains the following information that
pertains to the keyboard as a whole:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A <span class="emphasis"><em>
keyboard symbolic name</em></span>
 of type Atom to help users identify the keyboard.
  </p></li><li class="listitem"><p>
The <span class="emphasis"><em>
width</em></span>
 and <span class="emphasis"><em>
height</em></span>
 of the keyboard, in mm/10. For nonrectangular keyboards, the width and height
describe the smallest bounding box that encloses the outline of the keyboard.
  </p></li><li class="listitem"><p>
The<span class="emphasis"><em>
 base color</em></span>
 of the keyboard is the predominant color on the keyboard and is used as the
default color for any components whose color is not explicitly specified.
  </p></li><li class="listitem"><p>
The <span class="emphasis"><em>
label color</em></span>
 is the color used to draw the labels on most of the keyboard keys.
  </p></li><li class="listitem"><p>
The <span class="emphasis"><em>
label font</em></span>
 is a string that describes the font used to draw labels on most keys; label
fonts are arbitrary strings, because Xkb does not specify the format or name
space for font names.
  </p></li></ul></div><p>
The keyboard is subdivided into named <span class="emphasis"><em>
sections</em></span>
 of related keys and doodads. The sections and doodads on the keyboard are
listed in the <span class="emphasis"><em>
XkbGeometryRec</em></span>
 top-level keyboard geometry description. A section is composed of keys that
are physically together and logically related. Figure 13.2 shows a keyboard
that is divided into four sections. A <span class="emphasis"><em>
doodad</em></span>
 describes some visible aspect of the keyboard that is not a key and is not a
section.
</p><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-8.svg"></object><div class="caption">Keyboard with Four Sections</div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Shapes_and_Outlines"></a>Shapes and Outlines</h2></div></div></div><p>
A <span class="emphasis"><em>
shape</em></span>
, used to draw keyboard components and stored in a <span class="emphasis"><em>
XkbShapeRec</em></span>
 structure, has:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
An arbitrary name of type Atom.
  </p></li><li class="listitem"><p>
Bounds (two x and y coordinates) that describe the corners of a rectangle
containing the shape’s top surface outline.
  </p></li><li class="listitem"><p>
A list of one or more outlines (described below).
  </p></li><li class="listitem"><p>
Optional pointers to a primary and an approximation outline (described below).
If either of these pointers is <span class="emphasis"><em>
NULL</em></span>
, the default primary/approximation outline is the first one in the list of
outlines for the shape.
  </p></li></ul></div><p>
An <span class="emphasis"><em>
outline</em></span>
, stored in a <span class="emphasis"><em>
XkbOutlineRec</em></span>
 structure, is a list of one or more points that describes a single
closed-polygon, as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A list with a single point describes a rectangle with one corner at the origin
of the shape (0,0) and the opposite corner at the specified point.
  </p></li><li class="listitem"><p>
A list of two points describes a rectangle with one corner at the position
specified by the first point and the opposite corner at the position specified
by the second point.
  </p></li><li class="listitem"><p>
A list of three or more points describes an arbitrary polygon. If necessary,
the polygon is automatically closed by connecting the last point in the list
with the first.
  </p></li><li class="listitem"><p>
A nonzero value for the <span class="emphasis"><em>
corner_radius</em></span>
 field specifies that the corners of the polygon should be drawn as circles
with the specified radius.
  </p></li></ul></div><p>
All points in an outline are specified relative to the origin of the enclosing
shape. Points in an outline may have negative values for the X and Y coordinate.
</p><p>
One outline is the primary outline; a keyboard display application can generate
a simple but still accurate keyboard image by displaying only the primary
outlines for each shape. The default primary outline is the first in a
shape’s list of outlines. If the <span class="emphasis"><em>
primary</em></span>
 field of the <span class="emphasis"><em>
XkbShapeRec</em></span>
 structure is not <span class="emphasis"><em>
NULL</em></span>
, it points to the primary outline. A rectangular <span class="emphasis"><em>
approximation</em></span>
 must be included for nonrectangular keys as one of the outlines associated
with the shape; the approximation is not normally displayed but can be used by
very simple keyboard display applications to generate a recognizable but
degraded image of the keyboard.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Sections"></a>Sections</h2></div></div></div><p>
As previously noted, a keyboard is subdivided into <span class="emphasis"><em>
sections</em></span>
 of related keys. Each section has its own coordinate system — if a section
is rotated, the coordinates of any components within the section are
interpreted relative to the edges that were on the top and left before
rotation. The components that make up a section, stored in a <span class="emphasis"><em>
XkbSectionRec</em></span>
, include:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
An arbitrary name of type Atom.
  </p></li><li class="listitem"><p>
A priority, to indicate drawing order. 0 is the highest priority, 255 the
lowest.
  </p></li><li class="listitem"><p>
Origin of the section, relative to the origin of the keyboard.
  </p></li><li class="listitem"><p>
The width and height and the angle of rotation.
  </p></li><li class="listitem"><p>
A list of <span class="emphasis"><em>
rows</em></span>
. A row is a list of horizontally or vertically adjacent keys. Horizontal rows
parallel the (prerotation) top of the section, and vertical rows parallel the
(prerotation) left of the section. All keys in a horizontal row share a common
top coordinate; all keys in a vertical row share a left coordinate. Figure 13.3
shows the alpha section from the keyboard shown in Figure 13.2, divided into
rows. Rows and keys are defined below.
  </p></li></ul></div><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-9.svg"></object><div class="caption">Rows in a Section</div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
An optional list of <span class="emphasis"><em>
doodads</em></span>
; any type of doodad can be enclosed within a section. Position and angle of
rotation are relative to the origin and angle of rotation of the sections that
contain them. Priority for doodads in a section is relative to the other
components of the section, not to the keyboard as a whole.
  </p></li><li class="listitem"><p>
An optional <span class="emphasis"><em>
overlay</em></span>
 with a name of type Atom and a list of overlay rows (described below).
  </p></li><li class="listitem"><p>
Bounds (two x and y coordinates) that describe the corners of a rectangle
containing the entire section.
  </p></li></ul></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Rows_and_Keys"></a>Rows and Keys</h2></div></div></div><p>
A row description (<span class="emphasis"><em>
XkbRowRec</em></span>
) consists of the coordinates of its origin relative to its enclosing section,
a flag indicating whether the row is horizontal or vertical, and a list of keys
in the row.
</p><p>
A key description (<span class="emphasis"><em>
XkbKeyRec</em></span>
) consists of a key name, a shape, a key color, and a gap. The key name should
correspond to one of the keys named in the keyboard names description, the
shape specifies the appearance of the key, and the key color specifies the
color of the key (not the label on the key; the label color is stored in the
<span class="emphasis"><em>
XkbGeometryRec</em></span>
). Keys are normally drawn immediately adjacent to one another from left to
right (or top to bottom) within a row. The gap field specifies the distance
between a key and its predecessor.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Doodads"></a>Doodads</h2></div></div></div><p>
Doodads can be global to the keyboard or part of a section. Doodads have
symbolic names of arbitrary length. The only doodad name whose interpretation
is specified by Xkb is "Edges", which, if present, describes the outline of the
entire keyboard.
</p><p>
Each doodad’s origin is stored in fields named <span class="emphasis"><em>
left</em></span>
 and <span class="emphasis"><em>
top</em></span>
, which are the coordinates of the doodad’s origin relative to its enclosing
object, whether it be a section or the top-level keyboard. The priority for
doodads that are listed in the top-level geometry is relative to the other
doodads listed in the top-level geometry and the sections listed in the
top-level geometry. The priority for doodads listed in a section are relative
to the other components of the section. Each doodad is stored in a structure
with a <span class="emphasis"><em>
type</em></span>
 field, which specifies the type of doodad.
</p><p>
Xkb supports five types of doodads:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
An <span class="emphasis"><em>
indicator doodad</em></span>
 describes one of the physical keyboard indicators. Indicator doodads specify
the shape of the indicator, the indicator color when it is lit (<span class="emphasis"><em>
on_color</em></span>
) and the indicator color when it is dark (<span class="emphasis"><em>
off_color</em></span>
).
  </p></li><li class="listitem"><p>
An <span class="emphasis"><em>
outline doodad</em></span>
 describes some aspect of the keyboard to be drawn as one or more hollow,
closed polygons. Outline doodads specify the shape, color, and angle of
rotation about the doodad origin at which they should be drawn.
  </p></li><li class="listitem"><p>
A <span class="emphasis"><em>
solid doodad</em></span>
 describes some aspect of the keyboard to be drawn as one or more filled
polygons. Solid doodads specify the shape, color, and angle of rotation about
the doodad origin at which they should be drawn.
  </p></li><li class="listitem"><p>
A <span class="emphasis"><em>
text doodad</em></span>
 describes a text label somewhere on the keyboard. Text doodads specify the
label string, the font and color to use when drawing the label, and the angle
of rotation of the doodad about its origin.
  </p></li><li class="listitem"><p>
A <span class="emphasis"><em>
logo doodad </em></span>
is a catch-all, which describes some other visible element of the keyboard. A
logo doodad is essentially an outline doodad with an additional symbolic name
that describes the element to be drawn. If a keyboard display program
recognizes the symbolic name, it can draw something appropriate within the
bounding region of the shape specified in the doodad. If the symbolic name does
not describe a recognizable image, it should draw an outline using the
specified shape, outline, and angle of rotation. The Xkb extension does not
specify the interpretation of logo names.
  </p></li></ul></div><p>
The structures these doodads are stored in and the values of the <span class="emphasis"><em>
type</em></span>
 fields are shown in Table 13.1.
</p><div class="table"><a id="idp66374572"></a><p class="title"><strong>Table 13.1. Doodad Types</strong></p><div class="table-contents"><table summary="Doodad Types" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">Doodad</th><th align="left">Structure</th><th align="left">Type</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>
indicator doodad</em></span>
</td><td align="left"><span class="emphasis"><em>
XkbIndicatorDoodadRec</em></span>
</td><td align="left"><span class="emphasis"><em>
XkbIndicatorDoodad</em></span>
</td></tr><tr><td align="left"><span class="emphasis"><em>
outline doodad</em></span>
</td><td align="left"><span class="emphasis"><em>
XkbShapeDoodadRec</em></span>
</td><td align="left"><span class="emphasis"><em>
XkbOutlineDoodad</em></span>
</td></tr><tr><td align="left"><span class="emphasis"><em>
solid doodad</em></span>
</td><td align="left"><span class="emphasis"><em>
XkbShapeDoodadRec</em></span>
</td><td align="left"><span class="emphasis"><em>
XkbSolidDoodad</em></span>
</td></tr><tr><td align="left"><span class="emphasis"><em>
text doodad</em></span>
</td><td align="left"><span class="emphasis"><em>
XkbTextDoodadRec</em></span>
</td><td align="left"><span class="emphasis"><em>
XkbTextDoodad</em></span>
</td></tr><tr><td align="left"><span class="emphasis"><em>
logo doodad</em></span>
</td><td align="left"><span class="emphasis"><em>
XkbLogoDoodadRec</em></span>
</td><td align="left"><span class="emphasis"><em>
XkbLogoDoodad</em></span>
</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Overlay_Rows_and_Overlay_Keys"></a>Overlay Rows and Overlay Keys</h2></div></div></div><p>
An <span class="emphasis"><em>
overlay row</em></span>
 (<span class="emphasis"><em>
XkbOverlayRowRec</em></span>
) contains a pointer to the row it overlays and a list of <span class="emphasis"><em>
overlay keys</em></span>
.
</p><p>
Each overlay key definition (<span class="emphasis"><em>
XkbOverlayKeyRec</em></span>
) indicates a key that can yield multiple keycodes and consists of a field
named <span class="emphasis"><em>
under</em></span>
, which specifies the primary name of the key and a field named <span class="emphasis"><em>
over</em></span>
, which specifies the name for the key when the overlay keycode is selected.
The key specified in <span class="emphasis"><em>
under</em></span>
 must be a member of the section that contains the overlay key definition,
while the key specified in over must not be.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Drawing_a_Keyboard_Representation"></a>Drawing a Keyboard Representation</h2></div></div></div><p>
To draw a representation of the keyboard, draw in the following order:
</p><pre class="programlisting">
     Draw the top-level keyboard as a rectangle, using its width and height.
     For each component (section or doodad) of the top-level geometry, in priority order:
        If component is a section
           For each row, in the order it appears in the section
              Draw keys in the order they appear in the row
           Draw doodads within the section in priority order.
        Else draw doodad
</pre></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Geometry_Data_Structures"></a>Geometry Data Structures</h2></div></div></div><p>
In the following figures, a solid arrow denotes a pointer to an array of
structures or a singleton structure. A dotted arrow denotes an index or a
pointer into the array.
</p><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-10.svg"></object><div class="caption">Xkb Geometry Data Structures</div></div><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-11.svg"></object><div class="caption">Xkb Geometry Data Structures (Doodads)</div></div><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-12.svg"></object><div class="caption">Xkb Geometry Data Structures (Overlays)</div></div><pre class="programlisting">
typedef struct _XkbGeometry {              /* top-level keyboard geometry structure */
      Atom                name;            /* keyboard name */
      unsigned short      width_mm;        /* keyboard width in <span class="emphasis"><em> mm</em></span> /<span class="emphasis"><em> 10</em></span> */
      unsigned short      height_mm;       /* keyboard height in <span class="emphasis"><em> mm</em></span> /<span class="emphasis"><em> 10</em></span> */
      char *              label_font;      /* font for key labels */
      XkbColorPtr         label_color;     /* color for key labels - pointer into colors array */
      XkbColorPtr         base_color;      /* color for basic keyboard - pointer into colors array */
      unsigned short      sz_properties;   /* size of properties array */
      unsigned short      sz_colors;       /* size of colors array */
      unsigned short      sz_shapes;       /* size of shapes array */
      unsigned short      sz_sections;     /* size of sections array */
      unsigned short      sz_doodads;      /* size of doodads array */
      unsigned short      sz_key_aliases;  /* size of key aliases array */
      unsigned short      num_properties;  /* number of properties in the properties array */
      unsigned short      num_colors;      /* number of colors in the colors array */
      unsigned short      num_shapes;      /* number of shapes in the shapes array */
      unsigned short      num_sections;    /* number of sections in the sections array */
      unsigned short      num_doodads;     /* number of doodads in the doodads array */
      unsigned short      num_key_aliases; /* number of key aliases in the key */
      XkbPropertyPtr      properties;      /* properties array */
      XkbColorPtr         colors;          /* colors array */
      XkbShapePtr         shapes;          /* shapes array */
      XkbSectionPtr       sections;        /* sections array */
      XkbDoodadPtr        doodads;         /* doodads array */
      XkbKeyAliasPtr      key_aliases;     /* key aliases array */
} <span class="emphasis"><em>XkbGeometryRec</em></span>*XkbGeometryPtr;
</pre><p>
The <span class="emphasis"><em>
doodads</em></span>
 array is only for doodads not contained in any of the <span class="emphasis"><em>
sections</em></span>
 that has its own <span class="emphasis"><em>
doodads</em></span>
. The key aliases contained in the <span class="emphasis"><em>
key_aliases</em></span>
 array take precedence over any defined in the keycodes component of the
keyboard description.
</p><pre class="programlisting">
typedef struct _XkbProperty {
      char *      name;            /* property name */
      char *      value;           /* property value */
} <span class="emphasis"><em>XkbPropertyRec</em></span>,*XkbPropertyPtr;
</pre><pre class="programlisting">
typedef struct _XkbColor {
      unsigned int      pixel;     /* color */
      char *            spec;      /* color name */
} <span class="emphasis"><em>XkbColorRec</em></span>,*XkbColorPtr;
</pre><pre class="programlisting">
typedef struct _XkbKeyAliasRec {
      char      real[XkbKeyNameLength];   /* real name of the key */
      char      alias[XkbKeyNameLength];  /* alias for the key */
} <span class="emphasis"><em>XkbKeyAliasRec</em></span>,*XkbKeyAliasPtr;
</pre><pre class="programlisting">
typedef struct _XkbPoint {                /* x,y coordinates */
      short      x;
      short      y;
} <span class="emphasis"><em>XkbPointRec</em></span>, *XkbPointPtr;
</pre><pre class="programlisting">
typedef struct _XkbOutline {
      unsigned short      num_points;     /* number of points in the outline */
      unsigned short      sz_points;      /* size of the points array */
      unsigned short      corner_radius;  /* draw corners as circles with this radius */
      XkbPointPtr         points;         /* array of points defining the outline */
} <span class="emphasis"><em>XkbOutlineRec</em></span>, *XkbOutlinePtr;
</pre><pre class="programlisting">
typedef struct _XkbBounds {
      short      x1,y1;            /* upper left corner of the bounds,
                                      in <span class="emphasis"><em>mm</em></span>/<span class="emphasis"><em>10</em></span> */
       short      x2,y2;            /* lower right corner of the bounds, in
                                      <span class="emphasis"><em>mm</em></span>/<span class="emphasis"><em>10</em></span> */
} <span class="emphasis"><em>XkbBoundsRec</em></span>, *XkbBoundsPtr;
</pre><pre class="programlisting">
typedef struct _XkbShape {
      Atom              name;           /* shape’s name */
      unsigned short    num_outlines;   /* number of outlines for the shape */
      unsigned short    sz_outlines;    /* size of the outlines array */
      XkbOutlinePtr     outlines;       /* array of outlines for the shape */
      XkbOutlinePtr     approx;         /* pointer into the array to the approximating outline */
      XkbOutlinePtr     primary;        /* pointer into the array to the primary outline */
      XkbBoundsRec      bounds;         /* bounding box for the shape; encompasses all outlines */
} <span class="emphasis"><em>XkbShapeRec</em></span>, *XkbShapePtr;
</pre><p>
If <span class="emphasis"><em>
approx</em></span>
 and/or <span class="emphasis"><em>
primary</em></span>
 is <span class="emphasis"><em>
NULL</em></span>
, the default value is used. The default primary outline is the first element
in the outlines array, as is the default approximating outline.
</p><pre class="programlisting">
typedef struct _XkbKey {         /* key in a row */
      XkbKeyNameRec    name;     /* key name */
      short            gap;      /* gap in <span class="emphasis"><em>mm</em></span>/<span class="emphasis"><em>10</em></span> from previous key in row */
      unsigned char    shape_ndx;      /* index of shape for key */
      unsigned char    color_ndx;      /* index of color for key body */
} <span class="emphasis"><em>XkbKeyRec</em></span>, *XkbKeyPtr;
</pre><pre class="programlisting">
typedef struct _XkbRow {             /* row in a section */
      short               top;       /* top coordinate of row origin, relative to section’s origin */
      short               left;      /* left coordinate of row origin, relative to section’s origin */
      unsigned short      num_keys;  /* number of keys in the keys array */
      unsigned short      sz_keys;   /* size of the keys array */
      int                 vertical;  /* <span class="emphasis"><em>True</em></span> =&gt;vertical row,
                                        <span class="emphasis"><em> False</em></span> =&gt;horizontal row */
      XkbKeyPtr           keys;      /* array of keys in the row*/
      XkbBoundsRec        bounds;    /* bounding box for the row */
} <span class="emphasis"><em>XkbRowRec</em></span>, *XkbRowPtr;
</pre><p>
<span class="emphasis"><em>
top</em></span>
 and <span class="emphasis"><em>
left</em></span>
 are in <span class="emphasis"><em>
mm</em></span>
/<span class="emphasis"><em>
10</em></span>
.
</p><pre class="programlisting">
typedef struct _XkbOverlayRec {
      Atom              name;           /* overlay name */
      XkbSectionPtr     section_under;  /* the section under this overlay */
      unsigned short    num_rows;       /* number of rows in the rows array */
      unsigned short    sz_rows;        /* size of the rows array */
      XkbOverlayRowPtr  rows;           /* array of rows in the overlay */
      XkbBoundsPtr      bounds;         /* bounding box for the overlay */
} <span class="emphasis"><em>XkbOverlayRec</em></span>,*XkbOverlayPtr;
</pre><pre class="programlisting">
typedef struct _XkbOverlayRow {
      unsigned short      row_under;     /* index into the row under this overlay row */
      unsigned short      num_keys;      /* number of keys in the keys array */
      unsigned short      sz_keys;       /* size of the keys array */
      XkbOverlayKeyPtr    keys;          /* array of keys in the overlay row */
} <span class="emphasis"><em>XkbOverlayRowRec</em></span>,*XkbOverlayRowPtr;
</pre><p>
<span class="emphasis"><em>
row_under</em></span>
 is an index into the array of <span class="emphasis"><em>
rows</em></span>
 in the section under this overlay. The section under this overlay row is the
one pointed to by <span class="emphasis"><em>
section_under</em></span>
 in this overlay row’s <span class="emphasis"><em>
XkbOverlayRec</em></span>
.
</p><pre class="programlisting">
typedef struct _XkbOverlayKey {
      XkbKeyNameRec      over;      /* name of this overlay key */
      XkbKeyNameRec      under;     /* name of the key under this overlay key */
} <span class="emphasis"><em>XkbOverlayKeyRec</em></span>,*XkbOverlayKeyPtr;
</pre><pre class="programlisting">
typedef struct _XkbSection {
      Atom            name;          /* section name */
      unsigned char   priority;      /* drawing priority, 0=&gt;highest, 255=&gt;lowest */
      short           top;           /* top coordinate of section origin */
      short           left;          /* left coordinate of row origin */
      unsigned short  width;         /* section width, in <span class="emphasis"><em>mm</em></span>/<span class="emphasis"><em>10</em></span> */
      unsigned short  height;        /* section height, in <span class="emphasis"><em>mm</em></span>/<span class="emphasis"><em>10</em></span> */
      short           angle;         /* angle of section rotation, counterclockwise */
      unsigned short  num_rows;      /* number of rows in the rows array */
      unsigned short  num_doodads;   /* number of doodads in the doodads array */
      unsigned short  num_overlays;  /* number of overlays in the overlays array */
      unsigned short  sz_rows;       /* size of the rows array */
      unsigned short  sz_doodads;    /* size of the doodads array */
      unsigned short  sz_overlays;   /* size of the overlays array */
      XkbRowPtr       rows;          /* section rows array */
      XkbDoodadPtr    doodads;       /* section doodads array */
      XkbBoundsRec    bounds;        /* bounding box for the section, before rotation*/
      XkbOverlayPtr   overlays;      /* section overlays array */
} <span class="emphasis"><em>XkbSectionRec</em></span>, *XkbSectionPtr;
</pre><p>
<span class="emphasis"><em>
top</em></span>
 and <span class="emphasis"><em>
left</em></span>
 are the origin of the section, relative to the origin of the keyboard, in
<span class="emphasis"><em>
mm</em></span>
/<span class="emphasis"><em>
10</em></span>
. <span class="emphasis"><em>
angle</em></span>
 is in <span class="emphasis"><em>
1</em></span>
/<span class="emphasis"><em>
10</em></span>
 degrees.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="DoodadRec_Structures"></a>DoodadRec Structures</h3></div></div></div><p>
The doodad arrays in the <span class="emphasis"><em>
XkbGeometryRec</em></span>
 and the <span class="emphasis"><em>
XkbSectionRec</em></span>
 may contain any of the doodad structures and types shown in Table 13.1.
</p><p>
The doodad structures form a union:
</p><pre class="programlisting">
typedef union _XkbDoodad {
        XkbAnyDoodadRec        any;
        XkbShapeDoodadRec      shape;
        XkbTextDoodadRec       text;
        XkbIndicatorDoodadRec  indicator;
        XkbLogoDoodadRec       logo;
} <span class="emphasis"><em>XkbDoodadRec</em></span>, *XkbDoodadPtr;
</pre><p>
The <span class="emphasis"><em>
top</em></span>
 and <span class="emphasis"><em>
left</em></span>
 coordinates of each doodad are the coordinates of the origin of the doodad
relative to the keyboard’s origin if the doodad is in the <span class="emphasis"><em>
XkbGeometryRec</em></span>
 doodad array, and with respect to the section’s origin if the doodad is in a
<span class="emphasis"><em>
XkbSectionRec</em></span>
 doodad array. The <span class="emphasis"><em>
color_ndx</em></span>
 or <span class="emphasis"><em>
on_color_ndx</em></span>
 and <span class="emphasis"><em>
off_color_ndx</em></span>
 fields are color indices into the <span class="emphasis"><em>
XkbGeometryRec</em></span>
’s color array and are the colors to draw the doodads with. Similarly, the
<span class="emphasis"><em>
shape_ndx</em></span>
 fields are indices into the <span class="emphasis"><em>
XkbGeometryRec</em></span>
’s shape array.
</p><pre class="programlisting">
typedef struct _XkbShapeDoodad {
      Atom       name;                /* doodad name */
      unsigned char      type;        /* <span class="emphasis"><em>XkbOutlineDoodad</em></span>
                                         or <span class="emphasis"><em>XkbSolidDoodad</em></span> */
      unsigned char      priority;    /* drawing priority,
                                         0=&gt;highest, 255=&gt;lowest */
      short      top;                 /* top coordinate, in <span class="emphasis"><em>mm</em></span>/<span class="emphasis"><em>10</em></span> */
      short      left;                /* left coordinate, in <span class="emphasis"><em>mm</em></span>/<span class="emphasis"><em>10</em></span> */
      short      angle;               /* angle of rotation, clockwise, in <span class="emphasis"><em>1</em></span>/<span class="emphasis"><em>10</em></span> degrees */
      unsigned short      color_ndx;  /* doodad color */
      unsigned short      shape_ndx;  /* doodad shape */
} <span class="emphasis"><em>XkbShapeDoodadRec</em></span>, *XkbShapeDoodadPtr;
</pre><pre class="programlisting">
typedef struct _XkbTextDoodad {
      Atom            name;         /* doodad name */
      unsigned char   type;         /* <span class="emphasis"><em> XkbTextDoodad</em></span> */
      unsigned char   priority;     /* drawing priority,
                                       0=&gt;highest, 255=&gt;lowest */
      short           top;          /* top coordinate, in <span class="emphasis"><em>mm</em></span>/<span class="emphasis"><em>10</em></span> */
      short           left;         /* left coordinate, in <span class="emphasis"><em>mm</em></span>/<span class="emphasis"><em>10</em></span> */
      short           angle;        /* angle of rotation, clockwise, in <span class="emphasis"><em>1</em></span>/<span class="emphasis"><em>10</em></span> degrees */
      short           width;        /* width in <span class="emphasis"><em>mm</em></span>/<span class="emphasis"><em>10</em></span> */
      short           height;       /* height in <span class="emphasis"><em>mm</em></span>/<span class="emphasis"><em>10</em></span> */
      unsigned short  color_ndx;    /* doodad color */
      char *           text;        /* doodad text */
      char *           font;        /* arbitrary font name for doodad text */
} <span class="emphasis"><em>XkbTextDoodadRec</em></span>, *XkbTextDoodadPtr;
</pre><pre class="programlisting">
typedef struct _XkbIndicatorDoodad {
      Atom           name;          /* doodad name */
      unsigned char  type;          /* <span class="emphasis"><em>XkbIndicatorDoodad</em></span> */
      unsigned char  priority;      /* drawing priority, 0=&gt;highest, 255=&gt;lowest */
      short          top;           /* top coordinate, in <span class="emphasis"><em>mm</em></span>/<span class="emphasis"><em>10</em></span> */
      short          left;          /* left coordinate, in <span class="emphasis"><em>mm</em></span>/<span class="emphasis"><em>10</em></span> */
      short          angle;         /* angle of rotation, clockwise, in <span class="emphasis"><em>1</em></span>/<span class="emphasis"><em>10</em></span> degrees */
      unsigned short shape_ndx;     /* doodad shape */
      unsigned short on_color_ndx;  /* color for doodad if indicator is on */
      unsigned short off_color_ndx; /* color for doodad if indicator is off */
} <span class="emphasis"><em>XkbIndicatorDoodadRec</em></span>, *XkbIndicatorDoodadPtr;
</pre><pre class="programlisting">
typedef struct _XkbLogoDoodad {
      Atom               name;        /* doodad name */
      unsigned char      type;        /* <span class="emphasis"><em> XkbLogoDoodad</em></span> */
      unsigned char      priority;    /* drawing priority, 0=&gt;highest, 255=&gt;lowest */
      short              top;         /* top coordinate, in <span class="emphasis"><em>mm</em></span>/<span class="emphasis"><em>10</em></span> */
      short              left;        /* left coordinate, in <span class="emphasis"><em>mm</em></span>/<span class="emphasis"><em>10</em></span> */
      short              angle;       /* angle of rotation, clockwise, in <span class="emphasis"><em>1</em></span>/<span class="emphasis"><em>10</em></span> degrees */
      unsigned short      color_ndx;  /* doodad color */
      unsigned short      shape_ndx;  /* doodad shape */
      char *      logo_name;          /* text for logo */
} <span class="emphasis"><em>XkbLogoDoodadRec</em></span>, *XkbLogoDoodadPtr
</pre></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Getting_Keyboard_Geometry_From_the_Server"></a>Getting Keyboard Geometry From the Server</h2></div></div></div><p>
You can load a keyboard geometry as part of the keyboard description returned
by <span class="emphasis"><em>
XkbGetKeyboard</em></span>
. However, if a keyboard description has been previously loaded, you can
instead obtain the geometry by calling the <span class="emphasis"><em>
XkbGetGeometry</em></span>
. In this case, the geometry returned is the one associated with the keyboard
whose device ID is contained in the keyboard description.
</p><p>
To load a keyboard geometry if you already have the keyboard description, use
<span class="emphasis"><em>XkbGetGeometry</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetGeometry</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 xkb</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            <span class="emphasis"><em>
dpy</em></span>
;      /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr      <span class="emphasis"><em>
      xkb</em></span>
;      /* keyboard description that contains the ID for the keyboard and into
which the geometry should be loaded */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetGeometry</em></span>
 can return <span class="emphasis"><em>
BadValue</em></span>
, <span class="emphasis"><em>
BadImplementation</em></span>
, <span class="emphasis"><em>
BadName</em></span>
, <span class="emphasis"><em>
BadAlloc,</em></span>
 or <span class="emphasis"><em>
BadLength</em></span>
 errors or <span class="emphasis"><em>
Success</em></span>
 if it succeeds.
</p><p>
It is also possible to load a keyboard geometry by name. The X server maintains
a database of keyboard components (see Chapter 20). To load a keyboard geometry
description from this database by name, use <span class="emphasis"><em>
XkbGetNamedGeometry</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetNamedGeometry</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 xkb</em></span>
,<span class="emphasis"><em>
 name</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
dpy</em></span>
;      /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr      <span class="emphasis"><em>
xkb</em></span>
;      /* keyboard description into which the geometry should be loaded */
    </td></tr><tr><td class="functionargdecl" align="left">
Atom      <span class="emphasis"><em>
name</em></span>
;      /* name of the geometry to be loaded */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetNamedGeometry</em></span>
 can return <span class="emphasis"><em>
BadName</em></span>
 if the <span class="emphasis"><em>
name</em></span>
 cannot be found.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Using_Keyboard_Geometry"></a>Using Keyboard Geometry</h2></div></div></div><p>
Xkb provides a number of convenience functions to help use a keyboard geometry.
These include functions to return the bounding box of a shape’s top surface
and to update the bounding box of a shape row or section.
</p><p>
A shape is made up of a number of outlines. Each outline is a polygon made up
of a number of points. The bounding box of a shape is a rectangle that contains
all the outlines of that shape.
</p><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-13.svg"></object><div class="caption">Key Surface, Shape Outlines, and Bounding Box</div></div><p>
To determine the bounding box of the top surface of a shape, use <span class="emphasis"><em>
XkbComputeShapeTop</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbComputeShapeTop</em></span>
(<span class="emphasis"><em>
shape</em></span>
,<span class="emphasis"><em>
 bounds_rtrn</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbShapePtr      <span class="emphasis"><em>
      shape</em></span>
;      /* shape to be examined */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbBoundsPtr      <span class="emphasis"><em>
      bounds_rtrn</em></span>
      /* backfilled with the bounding box for the shape */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbComputeShapeTop</em></span>
 returns a <span class="emphasis"><em>
BoundsRec</em></span>
 that contains two x and y coordinates. These coordinates describe the corners
of a rectangle that contains the outline that describes the top surface of the
shape. The top surface is defined to be the approximating outline if the
<span class="emphasis"><em>
approx</em></span>
 field of <span class="emphasis"><em>
shape</em></span>
 is not <span class="emphasis"><em>
NULL</em></span>
. If <span class="emphasis"><em>
approx</em></span>
 is <span class="emphasis"><em>
NULL</em></span>
, the top surface is defined as the last outline in the <span class="emphasis"><em>
shape</em></span>
’s array of outlines. <span class="emphasis"><em>
XkbComputeShapeTop</em></span>
 returns <span class="emphasis"><em>
False</em></span>
 if <span class="emphasis"><em>
shape</em></span>
 is <span class="emphasis"><em>
NULL</em></span>
 or if there are no outlines for the shape; otherwise, it returns
<span class="emphasis"><em>True</em></span>.
</p><p>
A <span class="emphasis"><em>
ShapeRec</em></span>
 contains a <span class="emphasis"><em>
BoundsRec</em></span>
 that describes the bounds of the shape. If you add or delete an outline to or
from a shape, the bounding box must be updated. To update the bounding box of a
shape, use <span class="emphasis"><em>XkbComputeShapeBounds</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbComputeShapeBounds</em></span>
(<span class="emphasis"><em>
shape</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbShapePtr      <span class="emphasis"><em>
      shape</em></span>
;            /* shape to be examined */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbComputeShapeBounds</em></span>
 updates the <span class="emphasis"><em>
BoundsRec</em></span>
 contained in the <span class="emphasis"><em>
shape</em></span>
 by examining all the outlines of the shape and setting the <span class="emphasis"><em>
BoundsRec</em></span>
 to the minimum x and minimum y, and maximum x and maximum y values found in
those outlines. <span class="emphasis"><em>
XkbComputeShapeBounds</em></span>
 returns <span class="emphasis"><em>
False</em></span>
 if <span class="emphasis"><em>
shape</em></span>
 is <span class="emphasis"><em>
NULL</em></span>
 or if there are no outlines for the shape; otherwise, it returns <span class="emphasis"><em>
True</em></span>
.
</p><p>
 If you add or delete a key to or from a row, or if you update the shape of one
of the keys in that row, you may need to update the bounding box of that row.
To update the bounding box of a row, use <span class="emphasis"><em>XkbComputeRowBounds</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbComputeRowBounds</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 section</em></span>
,<span class="emphasis"><em>
 row</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry that contains the <span class="emphasis"><em>
section</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbSectionPtr      <span class="emphasis"><em>
      section</em></span>
;      /* section that contains the row */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbRowPtr            <span class="emphasis"><em>
row</em></span>
;      /* row to be examined and updated */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbComputeRowBounds</em></span>
 checks the bounds of all keys in the <span class="emphasis"><em>
row </em></span>
and updates the bounding box of the row if necessary. <span class="emphasis"><em>
XkbComputeRowBounds</em></span>
 returns <span class="emphasis"><em>
False</em></span>
 if any of the arguments is <span class="emphasis"><em>
NULL</em></span>
; otherwise, it returns <span class="emphasis"><em>
True</em></span>
.
</p><p>
 If you add or delete a row to or from a section, or if you change the geometry
of any of the rows in that section, you may need to update the bounding box for
that section. To update the bounding box of a section, use
<span class="emphasis"><em>XkbComputeSectionBounds</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbComputeSectionBounds</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 section</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry that contains the <span class="emphasis"><em>
section</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbSectionPtr      <span class="emphasis"><em>
      section</em></span>
;      /* section to be examined and updated */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbComputeSectionBounds</em></span>
 examines all the rows of the <span class="emphasis"><em>
section</em></span>
 and updates the bounding box of that section so that it contains all rows.
<span class="emphasis"><em>
XkbComputeSectionBounds</em></span>
 returns <span class="emphasis"><em>
False</em></span>
 if any of the arguments is <span class="emphasis"><em>
NULL</em></span>
; otherwise, it returns <span class="emphasis"><em>
True</em></span>
.
</p><p>
Keys that can generate multiple keycodes may be associated with multiple names.
Such keys have a primary name and an alternate name. To find the alternate name
by using the primary name for a key that is part of an overlay, use <span class="emphasis"><em>
XkbFindOverlayForKey</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
char * <span class="emphasis"><em>
XkbFindOverlayForKey</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 section</em></span>
,<span class="emphasis"><em>
 under</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry that contains the <span class="emphasis"><em>
section</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbSectionPtr      <span class="emphasis"><em>
      section</em></span>
;      /* section to be searched for matching keys */
    </td></tr><tr><td class="functionargdecl" align="left">
char *      <span class="emphasis"><em>
      under</em></span>
.      /* primary name of the key to be considered */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbFindOverlayForKey</em></span>
 uses the primary name of the key, <span class="emphasis"><em>
under</em></span>
, to look up the alternate name, which it returns.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Adding_Elements_to_a_Keyboard_Geometry"></a>Adding Elements to a Keyboard Geometry</h2></div></div></div><p>
Xkb provides functions to add a single new element to the top-level keyboard
geometry. In each case the <span class="emphasis"><em>
num_ </em></span>
<span class="emphasis"><em>
*</em></span>
 fields of the corresponding structure is incremented by 1. These functions do
not change <span class="emphasis"><em>
sz_</em></span>
<span class="emphasis"><em>
*</em></span>
 unless there is no more room in the array. Some of these functions fill in the
values of the element’s structure from the arguments. For other functions,
you must explicitly write code to fill the structure’s elements.
</p><p>
The top-level geometry description includes a list of <span class="emphasis"><em>
geometry properties</em></span>
. A geometry property associates an arbitrary string with an equally arbitrary
name. Programs that display images of keyboards can use geometry properties as
hints, but they are not interpreted by Xkb. No other geometry structures refer
to geometry properties.
</p><p>
To add one property to an existing keyboard geometry description, use <span class="emphasis"><em>
XkbAddGeomProperty</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbPropertyPtr <span class="emphasis"><em>
XkbAddGeomProperty</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 name</em></span>
,<span class="emphasis"><em>
 value</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry to be updated */
    </td></tr><tr><td class="functionargdecl" align="left">
char *      <span class="emphasis"><em>
      name</em></span>
;      /* name of the new property */
    </td></tr><tr><td class="functionargdecl" align="left">
char *      <span class="emphasis"><em>
      value</em></span>
;      /* value for the new property */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAddGeomProperty</em></span>
 adds one property with the specified <span class="emphasis"><em>
name</em></span>
 and <span class="emphasis"><em>
value</em></span>
 to the keyboard geometry specified by geom.<span class="emphasis"><em>
 </em></span>
<span class="emphasis"><em>
XkbAddGeomProperty</em></span>
 returns <span class="emphasis"><em>
NULL</em></span>
 if any of the parameters is empty or if it was not able to allocate space for
the property. To allocate space for an arbitrary number of properties, use the
XkbAllocGeomProps function.
</p><p>
To add one key alias to an existing keyboard geometry description, use
<span class="emphasis"><em>
XkbAddGeomKeyAlias</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbKeyAliasPtr <span class="emphasis"><em>
XkbAddGeomKeyAlias</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 alias, real</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry to be updated */
    </td></tr><tr><td class="functionargdecl" align="left">
char *      <span class="emphasis"><em>
      alias</em></span>
;      /* alias to be added */
    </td></tr><tr><td class="functionargdecl" align="left">
char *      <span class="emphasis"><em>
      real</em></span>
;      /* real name to be bound to the new alias */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAddGeomKeyAlias</em></span>
 adds one key alias with the value alias to the geometry geom, and associates
it with the key whose real name is real. <span class="emphasis"><em>
XkbAddGeomKeyAlias</em></span>
 returns <span class="emphasis"><em>
NULL</em></span>
 if any of the parameters is empty or if it was not able to allocate space for
the alias. To allocate space for an arbitrary number of aliases, use the
XkbAllocGeomKeyAliases function.
</p><p>
To add one color name to an existing keyboard geometry description, use
<span class="emphasis"><em>
XkbAddGeomColor</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbColorPtr <span class="emphasis"><em>
XkbAddGeomColor</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 spec</em></span>
,<span class="emphasis"><em>
 pixel</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry to be updated */
    </td></tr><tr><td class="functionargdecl" align="left">
char *      <span class="emphasis"><em>
      spec</em></span>
;      /* color to be added */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
      pixel</em></span>
;      /* color to be added */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAddGeomColor</em></span>
 adds the specified color <span class="emphasis"><em>
name</em></span>
 and <span class="emphasis"><em>
pixel</em></span>
 to the specified geometry <span class="emphasis"><em>
geom</em></span>
. The top-level geometry description includes a list of up to <span class="emphasis"><em>
MaxColors</em></span>
 (32) <span class="emphasis"><em>
color names</em></span>
. A color <span class="emphasis"><em>
name</em></span>
 is a string whose interpretation is not specified by Xkb and neither is the
<span class="emphasis"><em>
pixel</em></span>
 value’s interpretation. All other geometry data structures refer to colors
using their indices in this global list or pointers to colors in this list.
<span class="emphasis"><em>
XkbAddGeomColor</em></span>
 returns <span class="emphasis"><em>
NULL</em></span>
 if any of the parameters is empty or if it was not able to allocate space for
the color. To allocate space for an arbitrary number of colors to a geometry,
use the <span class="emphasis"><em>
XkbAllocGeomColors</em></span>
 function.
</p><p>
To add one outline to an existing shape, use <span class="emphasis"><em>
XkbAddGeomOutline</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbOutlinePtr <span class="emphasis"><em>
XkbAddGeomOutline</em></span>
(<span class="emphasis"><em>
shape</em></span>
,<span class="emphasis"><em>
 sz_points</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbShapePtr      <span class="emphasis"><em>
      shape</em></span>
;      /* shape to be updated */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      sz_points</em></span>
;      /* number of points to be reserved */
    </td></tr></tbody></table></div><p>
An outline consists of an arbitrary number of points. <span class="emphasis"><em>
XkbAddGeomOutline</em></span>
 adds an outline to the specified <span class="emphasis"><em>
shape</em></span>
 by reserving <span class="emphasis"><em>
sz_points</em></span>
 points for it. The new outline is allocated and zeroed. <span class="emphasis"><em>
XkbAddGeomOutline</em></span>
 returns <span class="emphasis"><em>
NULL</em></span>
 if any of the parameters is empty or if it was not able to allocate space. To
allocate space for an arbitrary number of outlines to a shape, use
XkbAllocGeomOutlines.
</p><p>
To add a shape to a keyboard geometry, use <span class="emphasis"><em>
XkbAddGeomShape</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbShapePtr <span class="emphasis"><em>
XkbAddGeomShape</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 name</em></span>
,<span class="emphasis"><em>
 sz_outlines</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry to be updated */
    </td></tr><tr><td class="functionargdecl" align="left">
Atom      <span class="emphasis"><em>
      name</em></span>
;      /* name of the new shape */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      sz_outlines</em></span>
;      /* number of outlines to be reserved */
    </td></tr></tbody></table></div><p>
A geometry contains an arbitrary number of shapes, each of which is made up of
an arbitrary number of outlines. <span class="emphasis"><em>
XkbAddGeomShape</em></span>
 adds a shape to a geometry <span class="emphasis"><em>
geom</em></span>
 by allocating space for <span class="emphasis"><em>
sz_outlines</em></span>
 outlines for it and giving it the name specified by name. If a shape with name
<span class="emphasis"><em>
name</em></span>
 already exists in the geometry, a pointer to the existing shape is returned.
<span class="emphasis"><em>
XkbAddGeomShape</em></span>
 returns <span class="emphasis"><em>
NULL</em></span>
 if any of the parameters is empty or if it was not able to allocate space. To
allocate space for an arbitrary number of geometry shapes, use <span class="emphasis"><em>
XkbAllocGeomShapes</em></span>
.
</p><p>
To add one key at the end of an existing row of keys, use <span class="emphasis"><em>
XkbAddGeomKey</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbKeyPtr <span class="emphasis"><em>
XkbAddGeomKey</em></span>
(<span class="emphasis"><em>
row</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbRowPtr      <span class="emphasis"><em>
      row</em></span>
;      /* row to be updated */
    </td></tr></tbody></table></div><p>
Keys are grouped into rows. <span class="emphasis"><em>
XkbAddGeomKey</em></span>
 adds one key to the end of the specified <span class="emphasis"><em>
row</em></span>
. The key is allocated and zeroed. <span class="emphasis"><em>
XkbAddGeomKey</em></span>
 returns <span class="emphasis"><em>
NULL</em></span>
 if <span class="emphasis"><em>
row</em></span>
 is empty or if it was not able to allocate space for the key. To allocate
space for an arbitrary number of keys to a row, use XkbAllocGeomKeys.
</p><p>
To add one section to an existing keyboard geometry, use <span class="emphasis"><em>
XkbAddGeomSection</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbSectionPtr <span class="emphasis"><em>
XkbAddGeomSection</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 name</em></span>
,<span class="emphasis"><em>
 sz_rows</em></span>
,<span class="emphasis"><em>
 sz_doodads</em></span>
,<span class="emphasis"><em>
 sz_overlays</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry to be updated */
    </td></tr><tr><td class="functionargdecl" align="left">
Atom      <span class="emphasis"><em>
      name</em></span>
;      /* name of the new section */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      sz_rows</em></span>
;      /* number of rows to reserve in the section */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      sz_doodads</em></span>
;      /* number of doodads to reserve in the section */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      sz_overlays</em></span>
;      /* number of overlays to reserve in the section */
    </td></tr></tbody></table></div><p>
A keyboard geometry contains an arbitrary number of sections. <span class="emphasis"><em>
XkbAddGeomSection</em></span>
 adds one section to an existing keyboard geometry <span class="emphasis"><em>
geom</em></span>
. The new section contains space for the number of rows, doodads, and overlays
specified by <span class="emphasis"><em>
sz_rows</em></span>
, <span class="emphasis"><em>
sz_doodads</em></span>
, and <span class="emphasis"><em>
sz_overlays</em></span>
. The new section is allocated and zeroed and given the name specified by
<span class="emphasis"><em>
name</em></span>
. If a section with name <span class="emphasis"><em>
name</em></span>
 already exists in the geometry, a pointer to the existing section is
returned.<span class="emphasis"><em>
 XkbAddGeomSection</em></span>
 returns <span class="emphasis"><em>
NULL</em></span>
 if any of the parameters is empty or if it was not able to allocate space for
the section. To allocate space for an arbitrary number of sections to a
geometry, use XkbAllocGeomSections.
</p><p>
To add a row to a section, use <span class="emphasis"><em>
XkbAddGeomRow</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbRowPtr <span class="emphasis"><em>
XkbAddGeomRow</em></span>
(<span class="emphasis"><em>
section</em></span>
,<span class="emphasis"><em>
 sz_keys</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbSectionPtr      <span class="emphasis"><em>
      section</em></span>
;      /* section to be updated */
    </td></tr><tr><td class="functionargdecl" align="left">
int            <span class="emphasis"><em>
sz_keys</em></span>
;      /* number of keys to be reserved */
    </td></tr></tbody></table></div><p>
One of the components of a keyboard geometry section is one or more rows of
keys. <span class="emphasis"><em>
XkbAddGeomRow</em></span>
 adds one row to the specified <span class="emphasis"><em>
section</em></span>
. The newly created row contains space for the number of keys specified in
<span class="emphasis"><em>
sz_keys</em></span>
. They are allocated and zeroed, but otherwise uninitialized. <span class="emphasis"><em>
XkbAddGeomRow</em></span>
 returns <span class="emphasis"><em>
NULL</em></span>
 if any of the parameters is empty or if it was not able to allocate space for
the row. To allocate space for an arbitrary number of rows to a section, use
the XkbAllocGeomRows function.
</p><p>
To add one doodad to a section of a keyboard geometry or to the top-level
geometry, use <span class="emphasis"><em>
XkbAddGeomDoodad</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbDoodadPtr <span class="emphasis"><em>
XkbAddGeomDoodad</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 section</em></span>
,<span class="emphasis"><em>
 name</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry to which the doodad is added */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbSectionPtr      <span class="emphasis"><em>
      section</em></span>
;      /* section, if any, to which the doodad is added */
    </td></tr><tr><td class="functionargdecl" align="left">
Atom      <span class="emphasis"><em>
      name</em></span>
;      /* name of the new doodad */
    </td></tr></tbody></table></div><p>
A <span class="emphasis"><em>
doodad</em></span>
 describes some visible aspect of the keyboard that is not a key and is not a
section. <span class="emphasis"><em>
XkbAddGeomDoodad</em></span>
 adds a doodad with name specified by name to the geometry <span class="emphasis"><em>
geom</em></span>
 if section is <span class="emphasis"><em>
NULL</em></span>
 or to the section of the geometry specified by section if <span class="emphasis"><em>
section</em></span>
 is not <span class="emphasis"><em>
NULL</em></span>
. <span class="emphasis"><em>
XkbAddGeomDoodad</em></span>
 returns <span class="emphasis"><em>
NULL</em></span>
 if any of the parameters is empty or if it was not able to allocate space for
the doodad. If there is already a doodad with the name <span class="emphasis"><em>
name</em></span>
 in the doodad array for the geometry (if <span class="emphasis"><em>
section</em></span>
 is <span class="emphasis"><em>
NULL</em></span>
) or the section (if <span class="emphasis"><em>
section</em></span>
 is non-<span class="emphasis"><em>
NULL</em></span>
), a pointer to that doodad is returned. To allocate space for an arbitrary
number of doodads to a section, use the XkbAllocGeomSectionDoodads function. To
allocate space for an arbitrary number of doodads to a keyboard geometry, use
the XkbAllocGeomDoodads function.
</p><p>
To add one overlay to a section, use <span class="emphasis"><em>
XkbAddGeomOverlay</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbOverlayPtr <span class="emphasis"><em>
XkbAddGeomOverlay</em></span>
(<span class="emphasis"><em>
section</em></span>
,<span class="emphasis"><em>
 name</em></span>
,<span class="emphasis"><em>
 sz_rows</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbSectionPtr      <span class="emphasis"><em>
      section</em></span>
;      /* section to which an overlay will be added */
    </td></tr><tr><td class="functionargdecl" align="left">
Atom      <span class="emphasis"><em>
      name</em></span>
;      /* name of the overlay */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      sz_rows</em></span>
;      /* number of rows to reserve in the overlay */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAddGeomOverlay</em></span>
 adds an overlay with the specified name to the specified <span class="emphasis"><em>
section</em></span>
. The new overlay is created with space allocated for sz_rows rows. If an
overlay with name <span class="emphasis"><em>
name</em></span>
 already exists in the section, a pointer to the existing overlay is
returned.<span class="emphasis"><em>
 XkbAddGeomOverlay</em></span>
 returns <span class="emphasis"><em>
NULL</em></span>
 if any of the parameters is empty or if it was not able to allocate space for
the overlay. To allocate space for an arbitrary number of overlays to a
section, use the XkbAllocGeomOverlay function.
</p><p>
To add a row to an existing overlay, use <span class="emphasis"><em>
XkbAddGeomOverlayRow</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbOverlayRowPtr <span class="emphasis"><em>
XkbAddGeomOverlayRow</em></span>
(<span class="emphasis"><em>
overlay</em></span>
,<span class="emphasis"><em>
 row_under, sz_keys</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbOverlayPtr      <span class="emphasis"><em>
      overlay</em></span>
;      /* overlay to be updated */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbRowPtr      <span class="emphasis"><em>
      row_under</em></span>
;      /* row to be overlayed in the section <span class="emphasis"><em>
overlay</em></span>
 overlays */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      sz_keys</em></span>
;      /* number of keys to reserve in the row */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAddGeomOverlayRow</em></span>
 adds one row to the <span class="emphasis"><em>
overlay</em></span>
. The new row contains space for <span class="emphasis"><em>
sz_keys</em></span>
 keys. If <span class="emphasis"><em>
row_under</em></span>
 specifies a row that doesn’t exist on the underlying section, <span class="emphasis"><em>
XkbAddGeomOverlayRow</em></span>
 returns <span class="emphasis"><em>
NULL</em></span>
 and doesn’t change the overlay.<span class="emphasis"><em>
 XkbAddGeomOverlayRow</em></span>
 returns <span class="emphasis"><em>
NULL</em></span>
 if any of the parameters is empty or if it was not able to allocate space for
the overlay.
</p><p>
To add a key to an existing overlay row, use <span class="emphasis"><em>
XkbAddGeomOverlayKey</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbOverlayKeyPtr <span class="emphasis"><em>
XkbAddGeomOverlayKey</em></span>
(<span class="emphasis"><em>
overlay</em></span>
,<span class="emphasis"><em>
 row, under</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbOverlayPtr      <span class="emphasis"><em>
      overlay</em></span>
;      /* overlay to be updated */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbRowPtr      <span class="emphasis"><em>
      row</em></span>
;      /* row in overlay to be updated */
    </td></tr><tr><td class="functionargdecl" align="left">
char *      <span class="emphasis"><em>
      under</em></span>
;      /* primary name of the key to be considered */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAddGeomOverlayKey</em></span>
 adds one key to the <span class="emphasis"><em>
row</em></span>
 in the <span class="emphasis"><em>
overlay</em></span>
. If there is no key named <span class="emphasis"><em>
under</em></span>
 in the row of the underlying section, <span class="emphasis"><em>
XkbAddGeomOverlayKey</em></span>
 returns <span class="emphasis"><em>
NULL</em></span>
.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Allocating_and_Freeing_Geometry_Components"></a>Allocating and Freeing Geometry Components</h2></div></div></div><p>
Xkb provides a number of functions to allocate and free subcomponents of a
keyboard geometry. Use these functions to create or modify keyboard geometries.
Note that these functions merely allocate space for the new element(s), and it
is up to you to fill in the values explicitly in your code. These allocation
functions increase <span class="emphasis"><em>
sz_</em></span>
<span class="emphasis"><em>
*</em></span>
 but never touch <span class="emphasis"><em>
num_</em></span>
<span class="emphasis"><em>
*</em></span>
 (unless there is an allocation failure, in which case they reset both
<span class="emphasis"><em>
sz_</em></span>
<span class="emphasis"><em>
*</em></span>
 and <span class="emphasis"><em>
num_</em></span>
<span class="emphasis"><em>
*</em></span>
 to zero). These functions return <span class="emphasis"><em>
Success</em></span>
 if they succeed, <span class="emphasis"><em>
BadAlloc</em></span>
 if they are not able to allocate space, or <span class="emphasis"><em>
BadValue</em></span>
 if a parameter is not as expected.
</p><p>
To allocate space for an arbitrary number of outlines to a shape, use
XkbAllocGeomOutlines.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocGeomOutlines</em></span>
(<span class="emphasis"><em>
shape</em></span>
,<span class="emphasis"><em>
 num_needed</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbShapePtr            <span class="emphasis"><em>
shape</em></span>
;      /* shape for which outlines should be allocated */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      num_needed</em></span>
;      /* number of new outlines required */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocGeomOutlines</em></span>
 allocates space for <span class="emphasis"><em>
num_needed</em></span>
 outlines in the specified <span class="emphasis"><em>
shape</em></span>
. The outlines are not initialized.
</p><p>
To free geometry outlines, use <span class="emphasis"><em>
XkbFreeGeomOutlines</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeGeomOutlines</em></span>
(<span class="emphasis"><em>
shape</em></span>
,<span class="emphasis"><em>
 first</em></span>
,<span class="emphasis"><em>
 count</em></span>
,<span class="emphasis"><em>
 free_all</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbShapePtr      <span class="emphasis"><em>
      shape</em></span>
;      /* shape in which outlines should be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      first</em></span>
;      /* first outline to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      count</em></span>
;      /* number of outlines to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
      free_all;</em></span>
      /* <span class="emphasis"><em>
True</em></span>
 =&gt; all outlines are freed */
    </td></tr></tbody></table></div><p>
If free_all is <span class="emphasis"><em>
True</em></span>
, all outlines are freed regardless of the value of first or count. Otherwise,
count outlines are freed beginning with the one specified by first.
</p><p>
To allocate space for an arbitrary number of keys to a row, use
XkbAllocGeomKeys.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocGeomKeys</em></span>
(<span class="emphasis"><em>
row</em></span>
,<span class="emphasis"><em>
 num_needed</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbRowPtr      <span class="emphasis"><em>
      row</em></span>
;      /* row to which keys should be allocated */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      num_needed</em></span>
;      /* number of new keys required */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocGeomKeys</em></span>
 allocates num_needed keys and adds them to the row. No initialization of the
keys is done.
</p><p>
To free geometry keys, use <span class="emphasis"><em>
XkbFreeGeomKeys</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeGeomKeys</em></span>
(<span class="emphasis"><em>
row</em></span>
,<span class="emphasis"><em>
 first</em></span>
,<span class="emphasis"><em>
 count</em></span>
,<span class="emphasis"><em>
 free_all</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbRowPtr      <span class="emphasis"><em>
      row</em></span>
;      /* row in which keys should be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      first</em></span>
;      /* first key to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      count</em></span>
;      /* number of keys to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
      free_all;</em></span>
      /* <span class="emphasis"><em>
True</em></span>
 =&gt; all keys are freed */
    </td></tr></tbody></table></div><p>
If free_all is <span class="emphasis"><em>
True</em></span>
, all keys are freed regardless of the value of first or count. Otherwise,
count keys are freed beginning with the one specified by first.
</p><p>
To allocate geometry properties, use <span class="emphasis"><em>
XkbAllocGeomProps</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocGeomProps</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 num_needed</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry for which properties should be allocated */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      num_needed</em></span>
;      /* number of new properties required */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocGeomProps</em></span>
 allocates space for num_needed properties and adds them to the specified
geometry <span class="emphasis"><em>
geom</em></span>
. No initialization of the properties is done. A geometry property associates
an arbitrary string with an equally arbitrary name. Geometry properties can be
used to provide hints to programs that display images of keyboards, but they
are not interpreted by Xkb. No other geometry structures refer to geometry
properties.
</p><p>
To free geometry properties, use <span class="emphasis"><em>
XkbFreeGeomProperties</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeGeomProperties</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 first</em></span>
,<span class="emphasis"><em>
 count</em></span>
,<span class="emphasis"><em>
 free_all</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry in which properties should be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      first</em></span>
;      /* first property to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      count</em></span>
;      /* number of properties to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
      free_all;</em></span>
      /* <span class="emphasis"><em>
True</em></span>
 =&gt; all properties are freed */
    </td></tr></tbody></table></div><p>
If free_all is <span class="emphasis"><em>
True</em></span>
, all properties are freed regardless of the value of first or count.
Otherwise, count properties are freed beginning with the one specified by first.
</p><p>
To allocate geometry key aliases, use <span class="emphasis"><em>
XkbAllocGeomKeyAliases</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocGeomKeyAliases</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 num_needed</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry for which key aliases should be allocated */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      num_needed</em></span>
;      /* number of new key aliases required */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocGeomKeyAliases</em></span>
 allocates space for num_needed key aliases and adds them to the specified
geometry <span class="emphasis"><em>
geom</em></span>
. A key alias is a pair of strings that associates an alternate name for a key
with the real name for that key.
</p><p>
To free geometry key aliases, use <span class="emphasis"><em>
XkbFreeGeomKeyAliases</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeGeomKeyAliases</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 first</em></span>
, <span class="emphasis"><em>
count</em></span>
, <span class="emphasis"><em>
free_all</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry in which key aliases should be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      first</em></span>
;      /* first key alias to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      count</em></span>
;      /* number of key aliases to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
      free_all;</em></span>
      /* <span class="emphasis"><em>
True</em></span>
 =&gt; all key aliases are freed */
    </td></tr></tbody></table></div><p>
If free_all is <span class="emphasis"><em>
True</em></span>
, all aliases in the top level of the specified geometry <span class="emphasis"><em>
geom</em></span>
 are freed regardless of the value of first or count. Otherwise, count aliases
in <span class="emphasis"><em>
geom</em></span>
 are freed beginning with the one specified by first.
</p><p>
To allocate geometry colors, use <span class="emphasis"><em>
XkbAllocGeomColors</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocGeomColors</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 num_needed</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry for which colors should be allocated */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      num_needed</em></span>
;      /* number of new colors required. */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocGeomColors</em></span>
 allocates space for num_needed colors and adds them to the specified geometry
<span class="emphasis"><em>
geom</em></span>
. A color name is a string whose interpretation is not specified by Xkb. All
other geometry data structures refer to colors using their indices in this
global list or pointers to colors in this list.
</p><p>
To free geometry colors, use <span class="emphasis"><em>
XkbFreeGeomColors</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeGeomColors</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 first</em></span>
,<span class="emphasis"><em>
 count</em></span>
,<span class="emphasis"><em>
 free_all</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry in which colors should be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      first</em></span>
;      /* first color to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      count</em></span>
;      /* number of colors to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
      free_all;</em></span>
      /* <span class="emphasis"><em>
True</em></span>
 =&gt; all colors are freed */
    </td></tr></tbody></table></div><p>
If free_all is <span class="emphasis"><em>
True</em></span>
, all colors are freed regardless of the value of first or count. Otherwise,
count colors are freed beginning with the one specified by first.
</p><p>
To allocate points in an outline, use <span class="emphasis"><em>
XkbAllocGeomPoints</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocGeomPoints</em></span>
(<span class="emphasis"><em>
outline</em></span>
,<span class="emphasis"><em>
 num_needed</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbOutlinePtr      <span class="emphasis"><em>
      outline</em></span>
;      /* outline for which points should be allocated */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      num_needed</em></span>
;      /* number of new points required */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocGeomPoints</em></span>
 allocates space for <span class="emphasis"><em>
num_needed</em></span>
 points in the specified <span class="emphasis"><em>
outline</em></span>
. The points are not initialized.
</p><p>
To free points in a outline, use <span class="emphasis"><em>
XkbFreeGeomPoints</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeGeomPoints</em></span>
(<span class="emphasis"><em>
outline</em></span>
,<span class="emphasis"><em>
 first</em></span>
,<span class="emphasis"><em>
 count</em></span>
,<span class="emphasis"><em>
 free_all</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbOutlinePtr      <span class="emphasis"><em>
      outline</em></span>
;      /* outline in which points should be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      first</em></span>
;      /* first point to be freed. */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      count</em></span>
;      /* number of points to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
      free_all;</em></span>
      /* <span class="emphasis"><em>
True</em></span>
 =&gt; all points are freed */
    </td></tr></tbody></table></div><p>
If free_all is <span class="emphasis"><em>
True</em></span>
, all points are freed regardless of the value of first and count. Otherwise,
the number of points specified by count are freed, beginning with the point
specified by first in the specified outline.
</p><p>
To allocate space for an arbitrary number of geometry shapes, use <span class="emphasis"><em>
XkbAllocGeomShapes</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocGeomShapes</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 num_needed</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry for which shapes should be allocated */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      num_needed</em></span>
;      /* number of new shapes required */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocGeomShapes</em></span>
 allocates space for <span class="emphasis"><em>
num_needed</em></span>
 shapes in the specified geometry <span class="emphasis"><em>
geom</em></span>
. The shapes are not initialized.
</p><p>
To free geometry shapes, use <span class="emphasis"><em>
XkbFreeGeomShapes</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeGeomShapes</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 first</em></span>
,<span class="emphasis"><em>
 count</em></span>
,<span class="emphasis"><em>
 f ree_all</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry in which shapes should be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      first</em></span>
;      /* first shape to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      count</em></span>
;      /* number of shapes to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
      free_all;</em></span>
      /* <span class="emphasis"><em>
True</em></span>
 =&gt; all shapes are freed */
    </td></tr></tbody></table></div><p>
If free_all is <span class="emphasis"><em>
True</em></span>
, all shapes in the geometry are freed regardless of the values of first and
count. Otherwise, count shapes are freed, beginning with the shape specified by
first.
</p><p>
To allocate geometry sections, use <span class="emphasis"><em>
XkbAllocGeomSections</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocGeomSections</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 num_needed</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /*geometry for which sections should be allocated */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      num_needed</em></span>
;      /* number of new sections required */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocGeomSections</em></span>
 allocates num_needed sections and adds them to the geometry geom. No
initialization of the sections is done.
</p><p>
To free geometry sections, use <span class="emphasis"><em>
XkbFreeGeomSections</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeGeomSections</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 first</em></span>
,<span class="emphasis"><em>
 count</em></span>
,<span class="emphasis"><em>
 free_all</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry in which sections should be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      first</em></span>
;      /* first section to be freed. */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      count</em></span>
;      /* number of sections to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
      free_all;</em></span>
      /* <span class="emphasis"><em>
True</em></span>
 =&gt; all sections are freed */
    </td></tr></tbody></table></div><p>
If free_all is <span class="emphasis"><em>
True</em></span>
, all sections are freed regardless of the value of first and count. Otherwise,
the number of sections specified by count are freed, beginning with the section
specified by first in the specified geometry.
</p><p>
To allocate rows in a section, use <span class="emphasis"><em>
XkbAllocGeomRows</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocGeomRows</em></span>
(<span class="emphasis"><em>
section</em></span>
,<span class="emphasis"><em>
 num_needed</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbSectionPtr            <span class="emphasis"><em>
section</em></span>
;      /* section for which rows should be allocated */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      num_needed</em></span>
;      /* number of new rows required */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocGeomRows</em></span>
 allocates num_needed rows and adds them to the section. No initialization of
the rows is done.
</p><p>
To free rows in a section, use <span class="emphasis"><em>
XkbFreeGeomRows</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeGeomRows</em></span>
(<span class="emphasis"><em>
section</em></span>
,<span class="emphasis"><em>
 first</em></span>
,<span class="emphasis"><em>
 count</em></span>
,<span class="emphasis"><em>
 free_all</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbSectionPtr      <span class="emphasis"><em>
      section</em></span>
;      /* section in which rows should be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      first</em></span>
;      /* first row to be freed. */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      count</em></span>
;      /* number of rows to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
      free_all;</em></span>
      /* <span class="emphasis"><em>
True</em></span>
 =&gt; all rows are freed */
    </td></tr></tbody></table></div><p>
If free_all is <span class="emphasis"><em>
True</em></span>
, all rows are freed regardless of the value of first and count. Otherwise, the
number of rows specified by count are freed, beginning with the row specified
by first in the specified section.
</p><p>
To allocate overlays in a section, use <span class="emphasis"><em>
XkbAllocGeomOverlays</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocGeomOverlays</em></span>
(<span class="emphasis"><em>
section</em></span>
,<span class="emphasis"><em>
 num_needed</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbSectionPtr            <span class="emphasis"><em>
section</em></span>
;      /* section for which overlays should be allocated */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      num_needed</em></span>
;      /* number of new overlays required */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocGeomRows</em></span>
 allocates num_needed overlays and adds them to the section. No initialization
of the overlays is done.
</p><p>
To free rows in an section, use <span class="emphasis"><em>
XkbFreeGeomOverlays</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeGeomOverlays</em></span>
(<span class="emphasis"><em>
section</em></span>
,<span class="emphasis"><em>
 first</em></span>
,<span class="emphasis"><em>
 count</em></span>
,<span class="emphasis"><em>
 free_all</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbSectionPtr      <span class="emphasis"><em>
      section</em></span>
;      /* section in which overlays should be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      first</em></span>
;      /* first overlay to be freed. */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      count</em></span>
;      /* number of overlays to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
      free_all;</em></span>
      /* <span class="emphasis"><em>
True</em></span>
 =&gt; all overlays are freed */
    </td></tr></tbody></table></div><p>
If free_all is <span class="emphasis"><em>
True</em></span>
, all overlays are freed regardless of the value of first and count. Otherwise,
the number of overlays specified by count are freed, beginning with the overlay
specified by first in the specified section.
</p><p>
To allocate rows in a overlay, use <span class="emphasis"><em>
XkbAllocGeomOverlayRows</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocGeomOverlayRows</em></span>
(<span class="emphasis"><em>
overlay</em></span>
,<span class="emphasis"><em>
 num_needed</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbSectionPtr            <span class="emphasis"><em>
overlay</em></span>
;      /* section for which rows should be allocated */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      num_needed</em></span>
;      /* number of new rows required */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocGeomOverlayRows</em></span>
 allocates num_needed rows and adds them to the overlay. No initialization of
the rows is done.
</p><p>
To free rows in an overlay, use <span class="emphasis"><em>
XkbFreeGeomOverlayRows</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeGeomOverlayRows</em></span>
(<span class="emphasis"><em>
overlay</em></span>
,<span class="emphasis"><em>
 first</em></span>
,<span class="emphasis"><em>
 count</em></span>
,<span class="emphasis"><em>
 free_all</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbSectionPtr      <span class="emphasis"><em>
      overlay</em></span>
;      /* section in which rows should be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      first</em></span>
;      /* first row to be freed. */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      count</em></span>
;      /* number of rows to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
      free_all;</em></span>
      /* <span class="emphasis"><em>
True</em></span>
 =&gt; all rows are freed */
    </td></tr></tbody></table></div><p>
If free_all is <span class="emphasis"><em>
True</em></span>
, all rows are freed regardless of the value of first and count. Otherwise, the
number of rows specified by count are freed, beginning with the row specified
by first in the specified overlay.
</p><p>
To allocate keys in an overlay row, use <span class="emphasis"><em>
XkbAllocGeomOverlayKeys</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocGeomOverlayKeys</em></span>
(<span class="emphasis"><em>
row</em></span>
,<span class="emphasis"><em>
 num_needed</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbRowPtr            <span class="emphasis"><em>
row</em></span>
;      /* section for which rows should be allocated */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      num_needed</em></span>
;      /* number of new rows required */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocGeomOverlayKeys</em></span>
 allocates num_needed keys and adds them to the row. No initialization of the
keys is done.
</p><p>
To free keys in an overlay row, use <span class="emphasis"><em>
XkbFreeGeomOverlayKeys</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeGeomOverlayKeys</em></span>
(<span class="emphasis"><em>
row</em></span>
,<span class="emphasis"><em>
 first</em></span>
,<span class="emphasis"><em>
 count</em></span>
,<span class="emphasis"><em>
 free_all</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbRowPtr      <span class="emphasis"><em>
      row</em></span>
;      /* row in which keys should be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      first</em></span>
;      /* first key to be freed. */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      count</em></span>
;      /* number of keys to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
      free_all;</em></span>
      /* <span class="emphasis"><em>
True</em></span>
 =&gt; all keys are freed */
    </td></tr></tbody></table></div><p>
If free_all is <span class="emphasis"><em>
True</em></span>
, all keys are freed regardless of the value of first and count. Otherwise, the
number of keys specified by count are freed, beginning with the key specified
by first in the specified row.
</p><p>
To allocate doodads that are global to a keyboard geometry, use <span class="emphasis"><em>
XkbAllocGeomDoodads</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocGeomDoodads</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 num_needed</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry for which doodads should be allocated */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      num_needed</em></span>
;      /* number of new doodads required */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocGeomDoodads</em></span>
 allocates num_needed doodads and adds them to the specified geometry <span class="emphasis"><em>
geom</em></span>
. No initialization of the doodads is done.
</p><p>
To allocate doodads that are specific to a section, use <span class="emphasis"><em>
XkbAllocGeomSectionDoodads</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocGeomSectionDoodads</em></span>
(<span class="emphasis"><em>
section</em></span>
,<span class="emphasis"><em>
 num_needed</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbSectionPtr      <span class="emphasis"><em>
      section</em></span>
;      /* section for which doodads should be allocated */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      num_needed</em></span>
;      /* number of new doodads required */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocGeomSectionDoodads</em></span>
 allocates num_needed doodads and adds them to the specified <span class="emphasis"><em>
section</em></span>
. No initialization of the doodads is done.
</p><p>
To free geometry doodads, use <span class="emphasis"><em>
XkbFreeGeomDoodads</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeGeomDoodads</em></span>
(<span class="emphasis"><em>
doodads</em></span>
,<span class="emphasis"><em>
 count</em></span>
,<span class="emphasis"><em>
 free_all</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDoodadPtr      <span class="emphasis"><em>
      doodads</em></span>
;      /* doodads to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
      count</em></span>
;      /* number of doodads to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
      free_all;</em></span>
      /* <span class="emphasis"><em>
True</em></span>
 =&gt; all doodads are freed */
    </td></tr></tbody></table></div><p>
If <span class="emphasis"><em>
free_all</em></span>
 is <span class="emphasis"><em>
True</em></span>
, all doodads in the array are freed, regardless of the value of count.
Otherwise, count doodads are freed.
</p><p>
To allocate an entire geometry, use <span class="emphasis"><em>
XkbAllocGeometry</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocGeometry</em></span>
(<span class="emphasis"><em>
xkb</em></span>
,<span class="emphasis"><em>
 sizes</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr      <span class="emphasis"><em>
      xkb</em></span>
;      /* keyboard description for which geometry is to be allocated */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometrySizesPtr<span class="emphasis"><em>
            sizes</em></span>
;      /* initial sizes for all geometry components */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocGeometry</em></span>
 allocates a keyboard geometry and adds it to the keyboard description
specified by xkb. The keyboard description should be obtained via the
XkbGetKeyboard or XkbAllockeyboard functions. The sizes parameter specifies the
number of elements to be reserved for the subcomponents of the keyboard
geometry and can be zero or more. These subcomponents include the properties,
colors, shapes, sections, and doodads.
</p><p>
To free an entire geometry, use <span class="emphasis"><em>
XkbFreeGeometry</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeGeometry</em></span>
(<span class="emphasis"><em>
geom</em></span>
,<span class="emphasis"><em>
 which</em></span>
,<span class="emphasis"><em>
 free_all</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbGeometryPtr      <span class="emphasis"><em>
      geom</em></span>
;      /* geometry to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
      which</em></span>
;      /* mask of geometry components to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
      free_all;</em></span>
      /* <span class="emphasis"><em>
True</em></span>
 =&gt; the entire geometry is freed. */
    </td></tr></tbody></table></div><p>
The values of which and free_all determine how much of the specified geometry
is freed. The valid values for which are:
</p><pre class="programlisting">
#define      XkbGeomPropertiesMask  (1&lt;&lt;0)
#define      XkbGeomColorsMask      (1&lt;&lt;1)
#define      XkbGeomShapesMask      (1&lt;&lt;2)
#define      XkbGeomSectionsMask    (1&lt;&lt;3)
#define      XkbGeomDoodadsMask     (1&lt;&lt;4)
#define      XkbGeomAllMask         (0x1f)
</pre><p>
If free_all is <span class="emphasis"><em>
True</em></span>
, the entire geometry is freed regardless of the value of which. Otherwise, the
portions of the geometry specified by which are freed.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Xkb_Keyboard_Mapping"></a>Chapter 14. Xkb Keyboard Mapping</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Notation_and_Terminology">Notation and Terminology</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Core_Implementation">Core Implementation</a></span></dt><dt><span class="sect2"><a href="#Xkb_Implementation">Xkb Implementation</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Getting_Map_Components_from_the_Server">Getting Map Components from the Server</a></span></dt><dt><span class="sect1"><a href="#Changing_Map_Components_in_the_Server">Changing Map Components in the Server</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_XkbMapChangesRec_Structure">The XkbMapChangesRec Structure</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Tracking_Changes_to_Map_Components">Tracking Changes to Map Components</a></span></dt><dt><span class="sect1"><a href="#Allocating_and_Freeing_Client_and_Server_Maps">Allocating and Freeing Client and Server Maps</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Allocating_an_Empty_Client_Map">Allocating an Empty Client Map</a></span></dt><dt><span class="sect2"><a href="#Freeing_a_Client_Map">Freeing a Client Map</a></span></dt><dt><span class="sect2"><a href="#Allocating_an_Empty_Server_Map">Allocating an Empty Server Map</a></span></dt><dt><span class="sect2"><a href="#Freeing_a_Server_Map">Freeing a Server Map</a></span></dt></dl></dd></dl></div><p>
The Xkb keyboard mapping contains all the information the server and clients
need to interpret key events. This chapter provides an overview of the
terminology used to describe an Xkb keyboard mapping and introduces common
utilities for manipulating the keyboard mapping.
</p><p>
The mapping consists of two components, a server map and a client map. The
<span class="emphasis"><em>
client</em></span>
 map is the collection of information a client needs to interpret key events
from the keyboard. It contains a global list of key types and an array of key
symbol maps, each of which describes the symbols bound to a key and the rules
to be used to interpret those symbols. The <span class="emphasis"><em>
server</em></span>
 map contains the information the server needs to interpret key events. This
includes actions and behaviors for each key, explicit components for a key, and
the virtual modifiers and the per-key virtual modifier mapping.
</p><p>
For detailed information on particular components of the keyboard map, refer to
Chapter 15, "Xkb Client Keyboard Mapping" and Chapter 16, "Xkb Server Keyboard
Mapping."
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Notation_and_Terminology"></a>Notation and Terminology</h2></div></div></div><p>
The graphic characters or control functions that may be accessed by one key are
logically arranged in groups and levels, where <span class="emphasis"><em>
group</em></span>
 and <span class="emphasis"><em>
level</em></span>
 are defined as in the ISO9995 standard:
</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">Group:</span></p></td><td><p>
A logical state of a keyboard providing access to a collection of
graphic characters. Usually these graphic characters logically belong together
and may be arranged on several levels within a group.
      </p></td></tr><tr><td><p><span class="term">Level:</span></p></td><td><p>
One of several states (normally 2 or 3) governing which graphic
character is produced when a graphic key is actuated. In certain cases the
level may also affect function keys.
      </p></td></tr></tbody></table></div><p>
These definitions, taken from the ISO standard, refer to graphic keys and
characters. In the context of Xkb, Group and Level are not constrained to
graphic keys and characters; they may be used with any key to access any
character the key is capable of generating.
</p><p>
Level is often referred to as "Shift Level". Levels are numbered sequentially
starting at one.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Shift level is derived from the modifier state, but not necessarily
in the same way for all keys. For example, the <span class="emphasis"><em>
Shift</em></span>
 modifier selects shift level 2 on most keys, but for keypad keys the modifier
bound to <span class="emphasis"><em>
Num_Lock</em></span>
 (that is, the <span class="emphasis"><em>
NumLock</em></span>
 virtual modifier) also selects shift level 2.</p></div><p>
For example, consider the following key (the gray characters indicate symbols
that are implied or expected but are not actually engraved on the key):
</p><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-14.svg"></object><div class="caption">Shift Levels and Groups</div></div><p>
This key has two groups, indicated by the columns, and each group has two shift
levels. For the first group (Group1), the symbol shift level one is <span class="emphasis"><em>
a</em></span>
, and the symbol for shift level two is <span class="emphasis"><em>
A</em></span>
. For the second group, the symbol for shift level one is <span class="emphasis"><em>
æ</em></span>
, and the symbol for shift level two is <span class="emphasis"><em>
Æ</em></span>
.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Core_Implementation"></a>Core Implementation</h3></div></div></div><p>
The standard interpretation rules for the core X keymap only allow clients to
access keys such as the one shown in Figure 14.1. That is, clients using the
standard interpretation rules can only access one of four keysyms for any given
<span class="emphasis"><em>
KeyPress</em></span>
 event — two different symbols in two different groups.
</p><p>
In general, the <span class="emphasis"><em>
Shift</em></span>
 modifier, the <span class="emphasis"><em>
Lock</em></span>
 modifier, and the modifier bound to the <span class="emphasis"><em>
Num_Lock</em></span>
 key are used to change between shift level 1 and shift level 2. To switch
between groups, the core implementation uses the modifier bound to the
<span class="emphasis"><em>
Mode_switch</em></span>
 key. When the <span class="emphasis"><em>
Mode_switch</em></span>
 modifier is set, the keyboard is logically in Group 2. When the <span class="emphasis"><em>
Mode_switch</em></span>
 modifier is not set, the keyboard is logically in Group 1.
</p><p>
The core implementation does not clearly specify the behavior of keys. For
example, the locking behavior of the <span class="emphasis"><em>
CapsLock</em></span>
 and <span class="emphasis"><em>
Num_Lock</em></span>
 keys depends on the vendor.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Xkb_Implementation"></a>Xkb Implementation</h3></div></div></div><p>
Xkb extends the core implementation by providing access to up to four keyboard
groups with up to 63 shift levels per key
<a href="#ftn.idp65582436" class="footnote" id="idp65582436"><sup class="footnote">[6]</sup></a>. In
addition, Xkb provides precise specifications regarding the behavior of keys.
In Xkb, modifier state and the current group are independent (with the
exception of compatibility mapping, discussed in Chapter 17).
</p><p>
Xkb handles switching between groups via key actions, independent of any
modifier state information. Key actions are in the server map component and are
described in detail in section 16.1.4.
</p><p>
Xkb handles shift levels by associating a key type with each group on each key.
Each key type defines the shift levels available for the groups on keys of its
type and specifies the modifier combinations necessary to access each level.
</p><p>
For example, Xkb allows key types where the <span class="emphasis"><em>
Control</em></span>
 modifier can be used to access the shift level two of a key. Key types are in
the client map component and are described in detail in section 15.2. 
</p><p>
Xkb provides precise specification of the behavior of a key using key
behaviors. Key behaviors are in the server map component and are described in
detail in section 16.2. 
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Getting_Map_Components_from_the_Server"></a>Getting Map Components from the Server</h2></div></div></div><p>
Xkb provides two functions to obtain the keyboard mapping components from the
server. The first function, <span class="emphasis"><em>
XkbGetMap</em></span>
, allocates an <span class="emphasis"><em>
XkbDescRec</em></span>
 structure, retrieves mapping components from the server, and stores them in
the <span class="emphasis"><em>
XkbDescRec</em></span>
 structure it just allocated. The second function, <span class="emphasis"><em>
XkbGetUpdatedMap</em></span>
, retrieves mapping components from the server and stores them in an <span class="emphasis"><em>
XkbDescRec</em></span>
 structure that has previously been allocated.
</p><p>
To allocate an <span class="emphasis"><em>
XkbDescRec</em></span>
 structure and populate it with the server’s keyboard client map and server
map, use <span class="emphasis"><em>
XkbGetMap. XkbGetMap </em></span>
is similar to <span class="emphasis"><em>
XkbGetKeyboard</em></span>
 (see section 6.2), but is used only for obtaining the address of an <span class="emphasis"><em>
XkbDescRec</em></span>
 structure that is populated with keyboard mapping components. It allows finer
control over which substructures of the keyboard mapping components are to be
populated. <span class="emphasis"><em>
XkbGetKeyboard</em></span>
 always returns fully populated components, while <span class="emphasis"><em>
XkbGetMap</em></span>
 can be instructed to return a partially populated component.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbDescPtr <span class="emphasis"><em>
XkbGetMap</em></span>
(<span class="emphasis"><em>
display, which, device_spec</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *       <span class="emphasis"><em>
      display</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
      which</em></span>
;            /* mask selecting subcomponents to populate */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
      device_spec</em></span>
;            /* device_id, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr></tbody></table></div><p>
The <span class="emphasis"><em>
which</em></span>
 mask is a bitwise inclusive OR of the masks defined in Table 14.1. Only those
portions of the keyboard server map and the keyboard client maps that are
specified in <span class="emphasis"><em>
which</em></span>
 are allocated and populated.
</p><p>
In addition to allocating and obtaining the server map and the client map,
<span class="emphasis"><em>
XkbGetMap</em></span>
 also sets the <span class="emphasis"><em>
device_spec</em></span>
, the <span class="emphasis"><em>
min_key_code</em></span>
<span class="emphasis"><em>
, </em></span>
and <span class="emphasis"><em>
max_key_code</em></span>
 fields of the keyboard description.
</p><p>
<span class="emphasis"><em>
XkbGetMap</em></span>
 is synchronous; it queries the server for the desired information, waits for a
reply, and then returns. If successful<span class="emphasis"><em>
, XkbGetMap</em></span>
 returns a pointer to the <span class="emphasis"><em>
XkbDescRec</em></span>
 structure it allocated. If unsuccessful, <span class="emphasis"><em>
XkbGetMap</em></span>
 returns <span class="emphasis"><em>
NULL</em></span>
. When unsuccessful, one of the following protocol errors is also generated:
<span class="emphasis"><em>
BadAlloc</em></span>
 (unable to allocate the <span class="emphasis"><em>
XkbDescRec</em></span>
 structure), <span class="emphasis"><em>
BadValue</em></span>
 (some mask bits in <span class="emphasis"><em>
which</em></span>
 are undefined)<span class="emphasis"><em>
,</em></span>
 or <span class="emphasis"><em>
BadImplementation</em></span>
 (a compatible version of the Xkb extension is not available in the server). To
free the returned data, use <span class="emphasis"><em>
XkbFreeClientMap</em></span>
.
</p><p>
Xkb also provides convenience functions to get partial component definitions
from the server. These functions are specified in the "convenience functions"
column in Table 14.1. Refer to the sections listed in the table for more
information on these functions.
</p><div class="table"><a id="idp65601540"></a><p class="title"><strong>Table 14.1. Xkb Mapping Component Masks and Convenience Functions</strong></p><div class="table-contents"><table summary="Xkb Mapping Component Masks and Convenience Functions" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /><col align="left" class="c5" /><col align="left" class="c6" /></colgroup><thead><tr><th align="left">Mask</th><th align="left">Value</th><th align="left">Map</th><th align="left">Fields</th><th align="left">Convenience Functions</th><th align="left">Section</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbKeyTypesMask</em></span></td><td align="left">(1&lt;&lt;0)</td><td align="left">client</td><td align="left">
      <p><span class="emphasis"><em>types</em></span></p>
      <p><span class="emphasis"><em>size_types</em></span></p>
      <p><span class="emphasis"><em>num_types</em></span></p>
    </td><td align="left">
      <p><span class="emphasis"><em>XkbGetKeyTypes</em></span></p>
      <p><span class="emphasis"><em>XkbResizeKeyType</em></span></p>
      <p><span class="emphasis"><em>XkbCopyKeyType</em></span></p>
      <p><span class="emphasis"><em>XkbCopyKeyTypes</em></span></p>
    </td><td align="left">15.2</td></tr><tr><td align="left"><span class="emphasis"><em>XkbKeySymsMask</em></span></td><td align="left">(1&lt;&lt;1)</td><td align="left">client</td><td align="left">
      <p><span class="emphasis"><em>syms</em></span></p>
      <p><span class="emphasis"><em>size_syms</em></span></p>
      <p><span class="emphasis"><em>num_syms</em></span></p>
      <p><span class="emphasis"><em>key_sym_map</em></span></p>
    </td><td align="left">
      <p><span class="emphasis"><em>XkbGetKeySyms</em></span></p>
      <p><span class="emphasis"><em>XkbResizeKeySyms</em></span></p>
      <p><span class="emphasis"><em>XkbChangeTypesOfKey</em></span></p>
    </td><td align="left">15.3</td></tr><tr><td align="left"><span class="emphasis"><em>XkbModifierMapMask</em></span></td><td align="left">(1&lt;&lt;2)</td><td align="left">client</td><td align="left"><span class="emphasis"><em>modmap</em></span></td><td align="left"><span class="emphasis"><em>XkbGetKeyModifierMap</em></span></td><td align="left">15.4</td></tr><tr><td align="left"><span class="emphasis"><em>XkbExplicitComponentsMask</em></span></td><td align="left">(1&lt;&lt;3)</td><td align="left">server</td><td align="left"><span class="emphasis"><em>explicit</em></span></td><td align="left"><span class="emphasis"><em>XkbGetKeyExplicitComponents</em></span></td><td align="left">16.3</td></tr><tr><td align="left"><span class="emphasis"><em>XkbKeyActionsMask</em></span></td><td align="left">(1&lt;&lt;4)</td><td align="left">server</td><td align="left">
      <p><span class="emphasis"><em>key_acts</em></span></p>
      <p><span class="emphasis"><em>acts</em></span></p>
      <p><span class="emphasis"><em>num_acts</em></span></p>
      <p><span class="emphasis"><em>size_acts</em></span></p>
    </td><td align="left">
      <p><span class="emphasis"><em>XkbGetKeyActions</em></span></p>
      <p><span class="emphasis"><em>XkbResizeKeyActions</em></span></p>
    </td><td align="left">16.1</td></tr><tr><td align="left"><span class="emphasis"><em>XkbKeyBehaviorsMask</em></span></td><td align="left">(1&lt;&lt;5)</td><td align="left">server</td><td align="left"><span class="emphasis"><em>behaviors</em></span></td><td align="left"><span class="emphasis"><em>XkbGetKeyBehaviors</em></span></td><td align="left">16.2</td></tr><tr><td align="left"><span class="emphasis"><em>XkbVirtualModsMask</em></span></td><td align="left">(1&lt;&lt;6)</td><td align="left">server</td><td align="left"><span class="emphasis"><em>vmods</em></span></td><td align="left"><span class="emphasis"><em>XkbGetVirtualMods</em></span></td><td align="left">16.4</td></tr><tr><td align="left"><span class="emphasis"><em>XkbVirtualModMapMask</em></span></td><td align="left">(1&lt;&lt;7)</td><td align="left">server</td><td align="left"><span class="emphasis"><em>vmodmap</em></span></td><td align="left"><span class="emphasis"><em>XkbGetVirtualModMap</em></span></td><td align="left">16.4</td></tr></tbody></table></div></div><br class="table-break" /><p>
Xkb defines combinations of these masks for convenience:
</p><pre class="programlisting">
#define  XkbResizableInfoMask      (XkbKeyTypesMask)
#define  XkbAllClientInfoMask      (XkbKeyTypesMask | XkbKeySymsMask |
                                    XkbModifierMapMask)
#define  XkbAllServerInfoMask      (XkbExplicitComponentsMask |
                                    XkbKeyActionsMask| XkbKeyBehaviorsMask |
                                    XkbVirtualModsMask | XkbVirtualModMapMask)
#define  XkbAllMapComponentsMask   (XkbAllClientInfoMask|XkbAllServerInfoMask)
</pre><p>
Key types, symbol maps, and actions are all interrelated: changes in one
require changes in the others. The convenience functions make it easier to edit
these components and handle the interdependencies.
</p><p>
To update the client or server map information in an existing keyboard
description, use <span class="emphasis"><em>XkbGetUpdatedMap</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetUpdatedMap</em></span>
(<span class="emphasis"><em>
display, which, xkb</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display * <span class="emphasis"><em>
            display</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
            which</em></span>
;            /* mask selecting subcomponents to populate */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;            /* keyboard description to be updated */
    </td></tr></tbody></table></div><p>
The <span class="emphasis"><em>
which</em></span>
 parameter is a bitwise inclusive OR of the masks in Table 14.1. If the needed
components of the <span class="emphasis"><em>
xkb</em></span>
 structure are not already allocated, <span class="emphasis"><em>
XkbGetUpdatedMap</em></span>
 allocates them. <span class="emphasis"><em>
XkbGetUpdatedMap</em></span>
 fetches the requested information for the device specified in the <span class="emphasis"><em>
XkbDescRec</em></span>
 passed in the <span class="emphasis"><em>
xkb</em></span>
 parameter.
</p><p>
<span class="emphasis"><em>
XkbGetUpdatedMap</em></span>
 is synchronous; it queries the server for the desired information, waits for a
reply, and then returns. If successful<span class="emphasis"><em>
, XkbGetUpdatedMap</em></span>
 returns <span class="emphasis"><em>
Success</em></span>
. If unsuccessful, <span class="emphasis"><em>
XkbGetUpdatedMap</em></span>
 returns one of the following: <span class="emphasis"><em>
BadAlloc</em></span>
 (unable to allocate a component in the <span class="emphasis"><em>
XkbDescRec</em></span>
 structure), <span class="emphasis"><em>
BadValue</em></span>
 (some mask bits in <span class="emphasis"><em>
which</em></span>
 are undefined), <span class="emphasis"><em>
BadImplementation</em></span>
 (a compatible version of the Xkb extension is not available in the server or
the reply from the server was invalid).
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Changing_Map_Components_in_the_Server"></a>Changing Map Components in the Server</h2></div></div></div><p>
There are two ways to make changes to map components: either change a local
copy of the keyboard map and call <span class="emphasis"><em>
XkbSetMap</em></span>
 to send the modified map to the server, or, to reduce network traffic, use
an<span class="emphasis"><em>
 XkbMapChangesRec</em></span>
 structure and call <span class="emphasis"><em>XkbChangeMap</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSetMap</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 which</em></span>
,<span class="emphasis"><em>
 xkb</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
            which</em></span>
;            /* mask selecting subcomponents to update */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr <span class="emphasis"><em>
            xkb</em></span>
;            /* description from which new values are taken */
    </td></tr></tbody></table></div><p>
Use <span class="emphasis"><em>
XkbSetMap</em></span>
 to send a complete new set of values for entire components (for example, all
symbols, all actions, and so on) to the server. The <span class="emphasis"><em>
which</em></span>
 parameter specifies the components to be sent to the server, and is a bitwise
inclusive OR of the masks listed in Table 14.1. The <span class="emphasis"><em>
xkb</em></span>
 parameter is a pointer to an <span class="emphasis"><em>
XkbDescRec</em></span>
 structure and contains the information to be copied to the server. For each
bit set in the <span class="emphasis"><em>
which</em></span>
 parameter, <span class="emphasis"><em>
XkbSetMap</em></span>
 takes the corresponding structure values from the <span class="emphasis"><em>
xkb</em></span>
 parameter and sends it to the server specified by <span class="emphasis"><em>
dpy</em></span>.
</p><p>
If any components specified by <span class="emphasis"><em>
which</em></span>
 are not present in the <span class="emphasis"><em>
xkb</em></span>
 parameter, <span class="emphasis"><em>
XkbSetMap</em></span>
 returns <span class="emphasis"><em>
False</em></span>
. Otherwise, it sends the update request to the server and returns <span class="emphasis"><em>
True</em></span>
. <span class="emphasis"><em>
XkbSetMap</em></span>
 can generate <span class="emphasis"><em>
BadAlloc</em></span>
, <span class="emphasis"><em>
BadLength</em></span>
, and <span class="emphasis"><em>
BadValue</em></span>
 protocol errors.
</p><p>
Key types, symbol maps, and actions are all interrelated; changes in one
require changes in the others. Xkb provides functions to make it easier to edit
these components and handle the interdependencies. Table 14.1 lists these
helper functions and provides a pointer to where they are defined.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_XkbMapChangesRec_Structure"></a>The XkbMapChangesRec Structure</h3></div></div></div><p>
Use the <span class="emphasis"><em>
XkbMapChangesRec</em></span>
 structure to identify and track partial modifications to the mapping
components and to reduce the amount of traffic between the server and clients.
</p><pre class="programlisting">
typedef struct _XkbMapChanges {
      unsigned short    changed;              /* identifies valid components
                                                 in structure */
      KeyCode           min_key_code;         /* lowest numbered keycode for
                                                 device */
      KeyCode           max_key_code;         /* highest numbered keycode for
                                                 device */
      unsigned char     first_type;           /* index of first key <span class="emphasis"><em>type</em></span>
                                                 modified */
      unsigned char     num_types;            /* # types modified */
      KeyCode           first_key_sym;        /* first key whose <span class="emphasis"><em>key_sym_map</em></span>
                                                 changed */
      unsigned char     num_key_syms;         /* # <span class="emphasis"><em>key_sym_map</em></span>
                                                 entries changed */
      KeyCode           first_key_act;        /* first key whose <span class="emphasis"><em>key_acts</em></span>
                                                 entry changed */
      unsigned char     num_key_acts;         /* # <span class="emphasis"><em>key_acts</em></span>
                                                 entries changed */
      KeyCode           first_key_behavior;   /* first key whose <span class="emphasis"><em>behaviors</em></span>
                                                 changed */
      unsigned char     num_key_behaviors;    /* # <span class="emphasis"><em>behaviors</em></span>
                                                 entries changed */
      KeyCode           first_key_explicit;   /* first key whose <span class="emphasis"><em>explicit</em></span>
                                                 entry changed */
      unsigned char     num_key_explicit;     /* # <span class="emphasis"><em> explicit</em></span>
                                                 entries changed */
      KeyCode           first_modmap_key;     /* first key whose <span class="emphasis"><em>modmap</em></span>
                                                 entry changed */
      unsigned char     num_modmap_keys;      /* # <span class="emphasis"><em>modmap</em></span>
                                                 entries changed */
      KeyCode           first_vmodmap_key;    /* first key whose <span class="emphasis"><em>vmodmap</em></span>
                                                 changed */
      unsigned char     num_vmodmap_keys;     /* # <span class="emphasis"><em> vmodmap</em></span>
                                                 entries changed */
      unsigned char     pad1;                 /* reserved */
      unsigned short    vmods;                /* mask indicating which <span class="emphasis"><em>vmods</em></span>
                                                 changed */
} <span class="emphasis"><em>XkbMapChangesRec</em></span>,*XkbMapChangesPtr;
</pre><p>
The <span class="emphasis"><em>
changed</em></span>
 field identifies the map components that have changed in an <span class="emphasis"><em>
XkbDescRec</em></span>
 structure and may contain any of the bits in Table 14.1, which are also shown
in Table 14.2. Every 1 bit in <span class="emphasis"><em>
changed</em></span>
 also identifies which other fields in the <span class="emphasis"><em>
XkbMapChangesRec</em></span>
 structure contain valid values, as indicated in Table 14.2. The <span class="emphasis"><em>
min_key_code</em></span>
 and <span class="emphasis"><em>
max_key_code</em></span>
 fields are for reference only; they are ignored on any requests sent to the
server and are always updated by the server whenever it returns the data for an
<span class="emphasis"><em>
XkbMapChangesRec</em></span>
.
</p><div class="table"><a id="idp65661396"></a><p class="title"><strong>Table 14.2. XkbMapChangesRec Masks</strong></p><div class="table-contents"><table summary="XkbMapChangesRec Masks" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">Mask</th><th align="left">Valid XkbMapChangesRec Fields</th><th align="left">XkbDescRec Field Containing Changed Data</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbKeyTypesMask</em></span></td><td align="left">
<p>first_type</p>,
<p>num_types</p>
    </td><td align="left">
<p>map-&gt;type[first_type] ..</p>
<p>map-&gt;type[first_type + num_types - 1]</p>
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbKeySymsMask</em></span></td><td align="left">
<p>first_key_sym</p>,
<p>num_key_syms</p>
    </td><td align="left">
<p>map-&gt;key_sym_map[first_key_sym] ..</p>
<p>map-&gt;key_sym_map[first_key_sym + num_key_syms - 1]</p>
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbModifierMapMask</em></span></td><td align="left">
<p>first_modmap_key</p>,
<p>num_modmap_keys</p>
    </td><td align="left">
<p>map-&gt;modmap[first_modmap_key] ..</p>
<p>map-&gt;modmap[first_modmap_key + num_modmap_keys-1]</p>
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbExplicitComponentsMask</em></span></td><td align="left">
<p>first_key_explicit</p>,
<p>num_key_explicit</p>
    </td><td align="left">
<p>server-&gt;explicit[first_key_explicit] ..</p>
<p>server-&gt;explicit[first_key_explicit + num_key_explicit - 1]</p>
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbKeyActionsMask</em></span></td><td align="left">
<p>first_key_act,</p>
<p>num_key_acts</p>
    </td><td align="left">
<p>server-&gt;key_acts[first_key_act] ..</p>
<p>server-&gt;key_acts[first_key_act + num_key_acts - 1]</p>
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbKeyBehaviorsMask</em></span></td><td align="left">
<p>first_key_behavior,</p>
<p>num_key_behaviors</p>
    </td><td align="left">
<p>server-&gt;behaviors[first_key_behavior] ..</p>
<p>server-&gt;behaviors[first_key_behavior + num_key_behaviors - 1]</p>
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbVirtuawModsMask</em></span></td><td align="left">vmods</td><td align="left">server-&gt;vmods[*]</td></tr><tr><td align="left"><span class="emphasis"><em>XkbVirtualModMapMask</em></span></td><td align="left">
<p>first_vmodmap_key,</p>
<p>num_vmodmap_keys</p>
    </td><td align="left">
<p>server-&gt;vmodmap[first_vmodmap_key] ..</p>
<p>server-&gt;vmodmap[first_vmodmap_key + num_vmodmap_keys - 1]</p>
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
To update only partial components of a keyboard description, modify the
appropriate fields in the server and map components of a local copy of the
keyboard description, then call <span class="emphasis"><em>
XkbChangeMap</em></span>
 with an <span class="emphasis"><em>
XkbMapChangesRec</em></span>
 structure indicating which components have changed.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbChangeMap</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 xkb</em></span>
,<span class="emphasis"><em>
 changes</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr <span class="emphasis"><em>
            xkb</em></span>
;            /* description from which new values are taken */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbMapChangesPtr <span class="emphasis"><em>
            changes</em></span>
;            /*identifies component parts to update */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbChangeMap</em></span>
 copies any components specified by the <span class="emphasis"><em>
changes</em></span>
 structure from the keyboard description, <span class="emphasis"><em>
xkb</em></span>
, to the X server specified by <span class="emphasis"><em>
dpy</em></span>
.
</p><p>
If any components specified by <span class="emphasis"><em>
changes</em></span>
 are not present in the <span class="emphasis"><em>
xkb</em></span>
 parameter, <span class="emphasis"><em>
XkbChangeMap</em></span>
 returns <span class="emphasis"><em>
False</em></span>
. Otherwise, it sends a request to the server and returns <span class="emphasis"><em>
True</em></span>
.
</p><p>
<span class="emphasis"><em>
XkbChangeMap</em></span>
 can generate <span class="emphasis"><em>
BadAlloc</em></span>
, <span class="emphasis"><em>
BadLength</em></span>
, and <span class="emphasis"><em>
BadValue</em></span>
 protocol errors.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Tracking_Changes_to_Map_Components"></a>Tracking Changes to Map Components</h2></div></div></div><p>
The Xkb extension reports <span class="emphasis"><em>
XkbMapNotify</em></span>
 events to clients wanting notification whenever a map component of the Xkb
description for a device changes. There are many different types of Xkb
keyboard map changes. Xkb uses an event detail mask to identify each type of
change. The event detail masks are identical to the masks listed in Table 14.1.
</p><p>
To receive <span class="emphasis"><em>
XkbMapNotify</em></span>
 events under all possible conditions, use <span class="emphasis"><em>
XkbSelectEvents</em></span>
 (see section 4.3) and pass <span class="emphasis"><em>
XkbMapNotifyMask</em></span>
 in both <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits</em></span>
.
</p><p>
To receive <span class="emphasis"><em>
XkbMapNotify</em></span>
 events only under certain conditions, use <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
 using <span class="emphasis"><em>
XkbMapNotify</em></span>
 as the <span class="emphasis"><em>
event_type</em></span>
 and specifying the desired map changes in <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits</em></span>
 using mask bits from Table 14.1.
</p><p>
The structure for <span class="emphasis"><em>
XkbMapNotify</em></span>
 events is:
</p><pre class="programlisting">
typedef struct {
      int            type;         /* Xkb extension base event code */
      unsigned long  serial;       /* X server serial number for event */
      Bool           send_event;   /* <span class="emphasis"><em>True</em></span> =&gt; synthetically generated */
      Display *      display;      /* server connection where event generated */
      Time           time;         /* server time when event generated */
      int            xkb_type;     /* <span class="emphasis"><em> XkbMapNotify</em></span> */
      int            device;       /* Xkb device ID, will not be <span class="emphasis"><em>XkbUseCoreKbd</em></span> */
      unsigned int   changed;      /* identifies valid fields in rest of event */
      unsigned int   resized;      /* reserved */
      int            first_type;   /* index of first key <span class="emphasis"><em> type</em></span> modified */
      int            num_types     /* # types modified */
      KeyCode        min_key_code; /* minimum keycode for device */
      KeyCode        max_key_code; /* maximum keycode for device */
      KeyCode        first_key_sym; /* first key whose <span class="emphasis"><em>key_sym_map</em></span> changed */
      KeyCode        first_key_act; /* first key whose <span class="emphasis"><em> key_acts</em></span> entry changed */
      KeyCode        first_key_behavior; /* first key whose <span class="emphasis"><em> behaviors</em></span> changed */
      KeyCode        first_key_explicit; /* first key whose <span class="emphasis"><em> explicit </em></span> entry changed */
      KeyCode        first_modmap_key;   /* first key whose <span class="emphasis"><em> modmap</em></span> entry changed */
      KeyCode        first_vmodmap_key;  /* # <span class="emphasis"><em> modmap</em></span> entries changed */
      int            num_key_syms;       /* # <span class="emphasis"><em>key_sym_map</em></span> entries changed */
      int            num_key_acts;       /* # <span class="emphasis"><em> key_acts</em></span> entries changed */
      int            num_key_behaviors;  /* # <span class="emphasis"><em> behaviors</em></span> entries changed */
      int            num_key_explicit;   /* # <span class="emphasis"><em> explicit</em></span> entries changed */
      int            num_modmap_keys;    /* # <span class="emphasis"><em> modmap</em></span> entries changed */
      int            num_vmodmap_keys;   /* # <span class="emphasis"><em> vmodmap</em></span> entries changed */
      unsigned in      t      vmods;     /* mask indicating which <span class="emphasis"><em> vmods</em></span> changed */
} <span class="emphasis"><em>XkbMapNotifyEvent</em></span>;
</pre><p>
The <span class="emphasis"><em>
changed</em></span>
 field specifies the map components that have changed and is the bitwise
inclusive OR of the mask bits defined in Table 14.1. The other fields in this
event are interpreted as the like-named fields in an <span class="emphasis"><em>
XkbMapChangesRec</em></span>
 (see section 14.3.1). The <span class="emphasis"><em>
XkbMapNotifyEvent</em></span>
 structure also has an additional <span class="emphasis"><em>
resized</em></span>
 field that is reserved for future use.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Allocating_and_Freeing_Client_and_Server_Maps"></a>Allocating and Freeing Client and Server Maps</h2></div></div></div><p>
Calling <span class="emphasis"><em>
XkbGetMap</em></span>
 (see section 14.2) should be sufficient for most applications to get client
and server maps. As a result, most applications do not need to directly
allocate client and server maps.
</p><p>
If you change the number of key types or construct map components without
loading the necessary components from the X server, do not allocate any map
components directly using <span class="emphasis"><em>
malloc</em></span>
 or <span class="emphasis"><em>
Xmalloc</em></span>
. Instead, use the Xkb allocators, <span class="emphasis"><em>
XkbAllocClientMap,</em></span>
 and <span class="emphasis"><em>
XkbAllocServerMap</em></span>
.
</p><p>
Similarly, use the Xkb destructors, <span class="emphasis"><em>
XkbFreeClientMap,</em></span>
 and <span class="emphasis"><em>
XkbFreeServerMap</em></span>
 instead of <span class="emphasis"><em>
free</em></span>
 or <span class="emphasis"><em>
Xfree</em></span>
.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Allocating_an_Empty_Client_Map"></a>Allocating an Empty Client Map</h3></div></div></div><p>
To allocate and initialize an empty client map description record, use
<span class="emphasis"><em>
XkbAllocClientMap.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocClientMap</em></span>
(<span class="emphasis"><em>
xkb, which, type_count</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr <span class="emphasis"><em>
            xkb</em></span>
;            /* keyboard description in which to allocate client map */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
            which</em></span>
;            /* mask selecting map components to allocate */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
            type_count</em></span>
;            /* value of <span class="emphasis"><em>
num_types</em></span>
 field in map to be allocated */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocClientMap</em></span>
 allocates and initializes an empty client map in the <span class="emphasis"><em>
map</em></span>
 field of the keyboard description specified by <span class="emphasis"><em>
xkb</em></span>
. The <span class="emphasis"><em>
which</em></span>
 parameter specifies the particular components of the client map structure to
allocate and is a mask composed by a bitwise inclusive OR of one or more of the
masks shown in Table 14.3.
</p><div class="table"><a id="idp65181356"></a><p class="title"><strong>Table 14.3. XkbAllocClientMap Masks</strong></p><div class="table-contents"><table summary="XkbAllocClientMap Masks" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Mask</th><th align="left">Effect</th></tr></thead><tbody><tr><td align="left">XkbKeyTypesMask</td><td align="left">
The <span class="emphasis"><em>
type_count </em></span>
field specifies the number of entries to preallocate for the <span class="emphasis"><em>
types</em></span>
 field of the client map. If the <span class="emphasis"><em>
type_count </em></span>
field is less than <span class="emphasis"><em>
XkbNumRequiredTypes</em></span>
 (see section 15.2.1), returns <span class="emphasis"><em>
BadValue</em></span>.
</td></tr><tr><td align="left">XkbKeySymsMask</td><td align="left">
The <span class="emphasis"><em>
min_key_code</em></span>
 and <span class="emphasis"><em>
max_key_code</em></span>
 fields of the <span class="emphasis"><em>
xkb</em></span>
 parameter are used to allocate the <span class="emphasis"><em>
syms</em></span>
 and <span class="emphasis"><em>
key_sym_map</em></span>
 fields of the client map. The fields are allocated to contain the maximum
number of entries necessary for <span class="emphasis"><em>
max_key_code</em></span>
 - <span class="emphasis"><em>
min_key_code</em></span>
 + 1 keys.
</td></tr><tr><td align="left">XkbModifierMapMask</td><td align="left">
The <span class="emphasis"><em>
min_key_code</em></span>
 and <span class="emphasis"><em>
max_key_code</em></span>
 fields of the <span class="emphasis"><em>
xkb</em></span>
 parameter are used to allocate the <span class="emphasis"><em>
modmap</em></span>
 field of the client map. The field is allocated to contain the maximum number
of entries necessary for <span class="emphasis"><em>
max_key_code</em></span>
 - <span class="emphasis"><em>
min_key_code</em></span>
 + 1 keys.
</td></tr></tbody></table></div></div><br class="table-break" /><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The <span class="emphasis"><em>
min_key_code</em></span>
 and <span class="emphasis"><em>
max_key_code</em></span>
 fields of the <span class="emphasis"><em>
xkb</em></span>
 parameter must be legal values if the <span class="emphasis"><em>
XkbKeySymsMask</em></span>
 or <span class="emphasis"><em>
XkbModifierMapMask</em></span>
 masks are set in the <span class="emphasis"><em>
which</em></span>
 parameter. If they are not valid, <span class="emphasis"><em>
XkbAllocClientMap</em></span>
 returns <span class="emphasis"><em>
BadValue</em></span>
. </p></div><p>
If the client map of the keyboard description is not <span class="emphasis"><em>
NULL</em></span>
, and any fields are already allocated in the client map, <span class="emphasis"><em>
XkbAllocClientMap</em></span>
 does not overwrite the existing values; it simply ignores that part of the
request. The only exception is the <span class="emphasis"><em>
types</em></span>
 array. If <span class="emphasis"><em>
type_count</em></span>
 is greater than the current <span class="emphasis"><em>
num_types</em></span>
 field of the client map, <span class="emphasis"><em>
XkbAllocClientMap</em></span>
 resizes the <span class="emphasis"><em>
types</em></span>
 array and resets the <span class="emphasis"><em>
num_types</em></span>
 field accordingly.
</p><p>
If <span class="emphasis"><em>
XkbAllocClientMap</em></span>
 is successful, it returns <span class="emphasis"><em>
Success</em></span>
. Otherwise, it can return either <span class="emphasis"><em>
BadMatch</em></span>
, <span class="emphasis"><em>
BadAlloc</em></span>
, or <span class="emphasis"><em>
BadValue</em></span>
 errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Freeing_a_Client_Map"></a>Freeing a Client Map</h3></div></div></div><p>
To free memory used by the client map member of an <span class="emphasis"><em>
XkbDescRec</em></span>
 structure, use <span class="emphasis"><em>
XkbFreeClientMap.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeClientMap</em></span>
(<span class="emphasis"><em>
xkb, which, free_all</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr <span class="emphasis"><em>
      xkb</em></span>
;            /* keyboard description containing client map to free */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      which</em></span>
;            /* mask identifying components of map to free */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool <span class="emphasis"><em>
      free_all</em></span>
;            /* <span class="emphasis"><em>
True</em></span>
 =&gt; free all client components and map itself */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbFreeClientMap</em></span>
 frees the components of client map specified by <span class="emphasis"><em>
which</em></span>
 in the <span class="emphasis"><em>
XkbDescRec</em></span>
 structure specified by the <span class="emphasis"><em>
xkb</em></span>
 parameter and sets the corresponding structure component values to <span class="emphasis"><em>
NULL</em></span>
. The <span class="emphasis"><em>
which</em></span>
 parameter specifies a combination of the client map masks shown in Table 14.3.
</p><p>
If <span class="emphasis"><em>
free_all</em></span>
 is <span class="emphasis"><em>
True</em></span>
, <span class="emphasis"><em>
which</em></span>
 is ignored; <span class="emphasis"><em>
XkbFreeClientMap</em></span>
 frees every non-<span class="emphasis"><em>
NULL</em></span>
 structure component in the client map, frees the <span class="emphasis"><em>
XkbClientMapRec</em></span>
 structure referenced by the <span class="emphasis"><em>
map</em></span>
 member of the <span class="emphasis"><em>
xkb</em></span>
 parameter, and sets the <span class="emphasis"><em>
map</em></span>
 member to <span class="emphasis"><em>
NULL.</em></span>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Allocating_an_Empty_Server_Map"></a>Allocating an Empty Server Map</h3></div></div></div><p>
To allocate and initialize an empty server map description record, use
<span class="emphasis"><em>
XkbAllocServerMap.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocServerMap</em></span>
(<span class="emphasis"><em>
xkb, which, count_acts</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr <span class="emphasis"><em>
            xkb</em></span>
;            /* keyboard description in which to allocate server map */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
            which</em></span>
;            /* mask selecting map components to allocate */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
            count_acts</em></span>
;            /* value of <span class="emphasis"><em>
num_acts</em></span>
 field in map to be allocated */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocServerMap</em></span>
 allocates and initializes an empty server map in the <span class="emphasis"><em>
server</em></span>
 field of the keyboard description specified by <span class="emphasis"><em>
xkb</em></span>
. The <span class="emphasis"><em>
which</em></span>
 parameter specifies the particular components of the server map structure to
allocate, as specified in Table 14.4.
</p><div class="table"><a id="idp65216964"></a><p class="title"><strong>Table 14.4. XkbAllocServerMap Masks</strong></p><div class="table-contents"><table summary="XkbAllocServerMap Masks" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Mask</th><th align="left">Effect</th></tr></thead><tbody><tr><td align="left">XkbExplicitComponentsMask</td><td align="left">
The <span class="emphasis"><em>
min_key_code</em></span>
 and <span class="emphasis"><em>
max_key_code</em></span>
 fields of the <span class="emphasis"><em>
xkb</em></span>
 parameter are used to allocate the <span class="emphasis"><em>
explicit </em></span>
field of the server map.
    </td></tr><tr><td align="left">XkbKeyActionsMask</td><td align="left">
The <span class="emphasis"><em>
min_key_code</em></span>
 and <span class="emphasis"><em>
max_key_code</em></span>
 fields of the <span class="emphasis"><em>
xkb</em></span>
 parameter are used to allocate the <span class="emphasis"><em>
key_acts </em></span>
field of the server map. The <span class="emphasis"><em>
count_acts</em></span>
 parameter is used to allocate the <span class="emphasis"><em>
acts</em></span>
 field of the server map.
    </td></tr><tr><td align="left">XkbKeyBehaviorsMask</td><td align="left">
The <span class="emphasis"><em>
min_key_code</em></span>
 and <span class="emphasis"><em>
max_key_code</em></span>
 fields of the <span class="emphasis"><em>
xkb</em></span>
 parameter are used to allocate the <span class="emphasis"><em>
behaviors </em></span>
field of the server map.
    </td></tr><tr><td align="left">XkbVirtualModMapMask</td><td align="left">
The <span class="emphasis"><em>
min_key_code</em></span>
 and <span class="emphasis"><em>
max_key_code</em></span>
 fields of the <span class="emphasis"><em>
xkb </em></span>
parameter are used to allocate the <span class="emphasis"><em>
vmodmap </em></span>
field of the server map.
    </td></tr></tbody></table></div></div><br class="table-break" /><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The <span class="emphasis"><em>
min_key_code</em></span>
 and <span class="emphasis"><em>
max_key_code</em></span>
 fields of the <span class="emphasis"><em>
xkb</em></span>
 parameter must be legal values. If they are not valid, <span class="emphasis"><em>
XkbAllocServerMap</em></span>
 returns <span class="emphasis"><em>
BadValue</em></span>
. </p></div><p>
If the server map of the keyboard description is not <span class="emphasis"><em>
NULL</em></span>
 and any fields are already allocated in the server map, <span class="emphasis"><em>
XkbAllocServerMap</em></span>
 does not overwrite the existing values. The only exception is with the
<span class="emphasis"><em>
acts </em></span>
array. If the <span class="emphasis"><em>
count_acts </em></span>
parameter is greater than the current <span class="emphasis"><em>
num_acts </em></span>
field of the server map, <span class="emphasis"><em>
XkbAllocServerMap</em></span>
 resizes the <span class="emphasis"><em>
acts </em></span>
array and resets the <span class="emphasis"><em>
num_acts </em></span>
field accordingly.
</p><p>
If <span class="emphasis"><em>
XkbAllocServerMap</em></span>
 is successful, it returns <span class="emphasis"><em>
Success</em></span>
. Otherwise, it can return either <span class="emphasis"><em>
BadMatch</em></span>
 or <span class="emphasis"><em>
BadAlloc</em></span>
 errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Freeing_a_Server_Map"></a>Freeing a Server Map</h3></div></div></div><p>
To free memory used by the server member of an <span class="emphasis"><em>
XkbDescRec</em></span>
 structure, use <span class="emphasis"><em>
XkbFreeServerMap.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeServerMap</em></span>
(<span class="emphasis"><em>
xkb, which, free_all</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr <span class="emphasis"><em>
      xkb</em></span>
;            /* keyboard description containing server map to free */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      which</em></span>
;            /* mask identifying components of map to free */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool <span class="emphasis"><em>
      free_all</em></span>
;            /* <span class="emphasis"><em>
True</em></span>
 =&gt; free all server map components and server itself */
    </td></tr></tbody></table></div><p>
The <span class="emphasis"><em>
XkbFreeServerMap</em></span>
 function frees the specified components of server map in the <span class="emphasis"><em>
XkbDescRec</em></span>
 structure specified by the <span class="emphasis"><em>
xkb</em></span>
 parameter and sets the corresponding structure component values to <span class="emphasis"><em>
NULL</em></span>
. The <span class="emphasis"><em>
which</em></span>
 parameter specifies a combination of the server map masks and is a bitwise
inclusive OR of the masks listed in Table 14.4. If <span class="emphasis"><em>
free_all</em></span>
 is <span class="emphasis"><em>
True</em></span>
, <span class="emphasis"><em>
which</em></span>
 is ignored and <span class="emphasis"><em>
XkbFreeServerMap</em></span>
 frees every non-<span class="emphasis"><em>
NULL</em></span>
 structure component in the server map, frees the <span class="emphasis"><em>
XkbServerMapRec</em></span>
 structure referenced by the <span class="emphasis"><em>
server</em></span>
 member of the <span class="emphasis"><em>
xkb</em></span>
 parameter, and sets the <span class="emphasis"><em>
server</em></span>
 member to <span class="emphasis"><em>
NULL.</em></span>
</p></div></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idp65582436" class="footnote"><p><a href="#idp65582436" class="para"><sup class="para">[6] </sup></a>
The core implementation restricts the number of symbols per key to 255.
With four groups, this allows for up to 63 symbols (or shift levels) per
group. Most keys will only have a few shift levels.
</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Xkb_Client_Keyboard_Mapping"></a>Chapter 15. Xkb Client Keyboard Mapping</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#The_XkbClientMapRec_Structure">The XkbClientMapRec Structure</a></span></dt><dt><span class="sect1"><a href="#Key_Types">Key Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_Canonical_Key_Types">The Canonical Key Types</a></span></dt><dt><span class="sect2"><a href="#Getting_Key_Types_from_the_Server">Getting Key Types from the Server</a></span></dt><dt><span class="sect2"><a href="#Changing_the_Number_of_Levels_in_a_Key_Type">Changing the Number of Levels in a Key Type</a></span></dt><dt><span class="sect2"><a href="#Copying_Key_Types">Copying Key Types</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Key_Symbol_Map">Key Symbol Map</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Per_Key_Key_Type_Indices">Per-Key Key Type Indices</a></span></dt><dt><span class="sect2"><a href="#Per_Key_Group_Information">Per-Key Group Information</a></span></dt><dt><span class="sect2"><a href="#Key_Width">Key Width</a></span></dt><dt><span class="sect2"><a href="#Offset_in_to_the_Symbol_Map">Offset in to the Symbol Map</a></span></dt><dt><span class="sect2"><a href="#Getting_the_Symbol_Map_for_Keys_from_the_Server">Getting the Symbol Map for Keys from the Server</a></span></dt><dt><span class="sect2"><a href="#Changing_the_Number_of_Groups_and_Types_Bound_to_a_Key">Changing the Number of Groups and Types Bound to a Key</a></span></dt><dt><span class="sect2"><a href="#Changing_the_Number_of_Symbols_Bound_to_a_Key">Changing the Number of Symbols Bound to a Key</a></span></dt></dl></dd><dt><span class="sect1"><a href="#The_Per_Key_Modifier_Map">The Per-Key Modifier Map</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Getting_the_Per_Key_Modifier_Map_from_the_Server">Getting the Per-Key Modifier Map from the Server</a></span></dt></dl></dd></dl></div><p>
The Xkb client map for a keyboard is the collection of information a client
needs to interpret key events from the keyboard. It contains a global list of
key types and an array of key symbol maps, each of which describes the symbols
bound to a key and the rules to be used to interpret those symbols.
</p><p>
Figure 15.1 shows the relationships between elements in the client map:
</p><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-15.svg"></object><div class="caption">Xkb Client Map</div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="The_XkbClientMapRec_Structure"></a>The XkbClientMapRec Structure</h2></div></div></div><p>
The <span class="emphasis"><em>
map </em></span>
field of the complete Xkb keyboard description (see section 6.1) is a pointer
to the Xkb client map, which is of type <span class="emphasis"><em>
XkbClientMapRec</em></span>
:
</p><pre class="programlisting">
typedef struct {                        /* Client Map */
      unsigned char      size_types;    /* # occupied entries in <span class="emphasis"><em> types</em></span> */
      unsigned char      num_types;     /* # entries in <span class="emphasis"><em>types</em></span> */
      XkbKeyTypePtr      types;         /* vector of key types used by this keymap */
      unsigned short     size_syms;     /* length of the <span class="emphasis"><em>syms</em></span> array */
      unsigned short     num_syms;      /* # entries in <span class="emphasis"><em>syms</em></span> */
      KeySym *           syms;          /* linear 2d tables of keysyms, 1 per key */
      XkbSymMapPtr       key_sym_map;   /* 1 per keycode, maps keycode to <span class="emphasis"><em>syms</em></span> */
      unsigned char *    modmap;        /* 1 per keycode, real mods bound to key */
} <span class="emphasis"><em>XkbClientMapRec</em></span>, *XkbClientMapPtr;
</pre><p>
The following sections describe each of the elements of the <span class="emphasis"><em>
XkbClientMapRec</em></span>
 structure in more detail.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Key_Types"></a>Key Types</h2></div></div></div><p>
Key types are used to determine the shift level of a key given the current
state of the keyboard. The set of all possible key types for the Xkb keyboard
description are held in the <span class="emphasis"><em>
types</em></span>
 field of the client map, whose total size is stored in <span class="emphasis"><em>
size_types</em></span>
, and whose total number of valid entries is stored in <span class="emphasis"><em>
num_types</em></span>
. Key types are defined using the following structures:
</p><pre class="programlisting">
typedef struct {                       /* Key Type */
      XkbModsRec        mods;          /* modifiers used to compute shift
                                          level */
      unsigned char     num_levels;    /* total # shift levels, do not
                                          modify directly */
      unsigned char     map_count;     /* # entries in <span class="emphasis"><em>map</em></span>,
                                          <span class="emphasis"><em> preserve</em></span>
                                          (if non-<span class="emphasis"><em> NULL</em></span>) */
      XkbKTMapEntryPtr  map;           /* vector of modifiers for each
                                          shift level */
      XkbModsPtr        preserve;      /* mods to preserve for corresponding
                                          <span class="emphasis"><em>map</em></span> entry */
      Atom              name;          /* name of key type */
      Atom *            level_names;   /* array of names of each shift level */
} <span class="emphasis"><em>XkbKeyTypeRec</em></span>, *XkbKeyTypePtr;
</pre><pre class="programlisting">
typedef struct {                   /* Modifiers for a key type */
      Bool            active;      /* <span class="emphasis"><em> True</em></span> =&gt; entry
                                      active when determining shift level */
      unsigned char   level;       /* shift level if modifiers match <span class="emphasis"><em> mods</em></span> */
      XkbModsRec      mods;        /* mods needed for this level to be
                                      selected */
} <span class="emphasis"><em>XkbKTMapEntryRec</em></span>,*XkbKTMapEntryPtr;
</pre><p>
The <span class="emphasis"><em>
mods</em></span>
 field of a key type is an <span class="emphasis"><em>
XkbModsRec</em></span>
 (see section 7.2) specifying the modifiers the key type uses when calculating
the shift level, and can be composed of both the core modifiers and virtual
modifiers. To set the modifiers associated with a key type, modify the
<span class="emphasis"><em>
real_mods</em></span>
 and <span class="emphasis"><em>
vmods</em></span>
 fields of the <span class="emphasis"><em>
mods</em></span>
 <span class="emphasis"><em>
XkbModsRec</em></span>
 accordingly. The <span class="emphasis"><em>
mask</em></span>
 field of the <span class="emphasis"><em>
XkbModsRec</em></span>
 is reserved for use by Xkb and is calculated from the <span class="emphasis"><em>
real_mods</em></span>
 and <span class="emphasis"><em>
vmods</em></span>
 fields.
</p><p>
The <span class="emphasis"><em>
num_levels</em></span>
 field holds the total number of shift levels for the key type. Xkb uses
<span class="emphasis"><em>
num_levels</em></span>
 to ensure the array of symbols bound to a key is large enough. Do not modify
<span class="emphasis"><em>
num_levels</em></span>
 directly to change the number if shift levels for a key type. Instead, use
<span class="emphasis"><em>
XkbResizeKeyType</em></span>
 (see section 15.2.3).
</p><p>
The <span class="emphasis"><em>
map</em></span>
 field is a vector of <span class="emphasis"><em>
XkbKTMapEntryRec</em></span>
 structures, with <span class="emphasis"><em>
map_count</em></span>
 entries, that specify the modifier combinations for each possible shift level.
Each map entry contains an <span class="emphasis"><em>
active</em></span>
 field, a <span class="emphasis"><em>
mods</em></span>
 field, and a <span class="emphasis"><em>
level</em></span>
 field. The <span class="emphasis"><em>
active</em></span>
 field determines whether the modifier combination listed in the <span class="emphasis"><em>
mods</em></span>
 field should be considered when determining shift level. If <span class="emphasis"><em>
active</em></span>
 is <span class="emphasis"><em>
False</em></span>
, this <span class="emphasis"><em>
map</em></span>
 entry is ignored. If <span class="emphasis"><em>
active</em></span>
 is <span class="emphasis"><em>
True</em></span>
, the <span class="emphasis"><em>
level</em></span>
 field of the <span class="emphasis"><em>
map </em></span>
entry specifies the shift level to use when the current modifier combination
matches the combination specified in the <span class="emphasis"><em>
mods</em></span>
 field of the <span class="emphasis"><em>
map</em></span>
 entry.
</p><p>
Any combination of modifiers not explicitly listed somewhere in the <span class="emphasis"><em>
map</em></span>
 yields shift level one. In addition, <span class="emphasis"><em>
map</em></span>
 entries specifying unbound virtual modifiers are not considered.
</p><p>
Any modifiers specified in <span class="emphasis"><em>
mods</em></span>
 are normally <span class="emphasis"><em>
consumed</em></span>
 by <span class="emphasis"><em>
XkbTranslateKeyCode</em></span>
 (see section 12.1.3). For those rare occasions a modifier <span class="emphasis"><em>
should</em></span>
 be considered despite having been used to look up a symbol, key types include
an optional <span class="emphasis"><em>
preserve</em></span>
 field. If a <span class="emphasis"><em>
preserve</em></span>
 member of a key type is not <span class="emphasis"><em>
NULL</em></span>
, it represents a list of modifiers where each entry corresponds directly to
one of the key type’s <span class="emphasis"><em>
map</em></span>
. Each entry lists the modifiers that should <span class="emphasis"><em>
not</em></span>
 be consumed if the matching map entry is used to determine shift level.
</p><p>
Each shift level has a name and these names are held in the <span class="emphasis"><em>
level_names</em></span>
 array, whose length is <span class="emphasis"><em>
num_levels</em></span>
. The type itself also has a name, which is held in the <span class="emphasis"><em>
name</em></span>
 field.
</p><p>
For example, consider how the server handles the following possible symbolic
description of a possible key type (note that the format used to specify
keyboard mappings in the server database is not specified by the Xkb extension,
although this format is one possible example):
</p><div class="table"><a id="idp65261028"></a><p class="title"><strong>Table 15.1. Example Key Type</strong></p><div class="table-contents"><table summary="Example Key Type" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Symbolic Description</th><th align="left">Key Type Data Structure</th></tr></thead><tbody><tr><td align="left">type "ALPHATHREE" {</td><td align="left">Xkb-&gt;map-&gt;types[i].name</td></tr><tr><td align="left">modifiers = Shift+Lock+LevelThree;</td><td align="left">Xkb-&gt;map-&gt;types[i].mods</td></tr><tr><td align="left"><span class="emphasis"><em>map[None]= Level1;</em></span></td><td align="left">Xkb-&gt;map-&gt;types[i].map[0]</td></tr><tr><td align="left"><span class="emphasis"><em>map[Lock]= Level1;</em></span></td><td align="left">Xkb-&gt;map-&gt;types[i].map[1]</td></tr><tr><td align="left">map[Shift]= Level2;</td><td align="left">Xkb-&gt;map-&gt;types[i].map[2]</td></tr><tr><td align="left">map[LevelThree]= Level3;</td><td align="left">Xkb-&gt;map-&gt;types[i].map[3]</td></tr><tr><td align="left">map[Shift+LevelThree]= Level3;</td><td align="left">Xkb-&gt;map-&gt;types[i].map[4]</td></tr><tr><td align="left"><span class="emphasis"><em>preserve[None]= None;</em></span></td><td align="left">Xkb-&gt;map-&gt;types[i].perserve[0]</td></tr><tr><td align="left">preserve[Lock]= Lock;</td><td align="left">Xkb-&gt;map-&gt;types[i].preserve[1]</td></tr><tr><td align="left"><span class="emphasis"><em>preserve[Shift]= None;</em></span></td><td align="left">Xkb-&gt;map-&gt;types[i].preserve[2]</td></tr><tr><td align="left"><span class="emphasis"><em>preserve[LevelThree]= None;</em></span></td><td align="left">Xkb-&gt;map-&gt;types[i].preserve[3]</td></tr><tr><td align="left"><span class="emphasis"><em>preserve[Shift+Level3]= None;</em></span> </td><td align="left">Xkb-&gt;map-&gt;types[i].preserve[4]</td></tr><tr><td align="left">level_name[Level1]= "Base";</td><td align="left">Xkb-&gt;map-&gt;types[i].level_names[0]</td></tr><tr><td align="left">level_name[Level2]= "Caps";</td><td align="left">Xkb-&gt;map-&gt;types[i].level_names[1]</td></tr><tr><td align="left">level_name[Level3]= "Level3";</td><td align="left">Xkb-&gt;map-&gt;types[i].level_names[2]</td></tr><tr><td align="left">};</td><td align="left"> </td></tr></tbody></table></div></div><br class="table-break" /><p>
The <span class="emphasis"><em>
name</em></span>
 of the example key type is "ALPHATHREE," and the modifiers it pays attention
to are <span class="emphasis"><em>
Shift</em></span>
, <span class="emphasis"><em>
Lock</em></span>
, and the virtual modifier <span class="emphasis"><em>
LevelThree</em></span>
. There are three shift levels. The name of shift level one is "Base," the name
of shift level two is "Caps," and the name of shift level three is "Level3."
</p><p>
Given the combination of the <span class="emphasis"><em>
map</em></span>
 and <span class="emphasis"><em>
preserve</em></span>
 specifications, there are five <span class="emphasis"><em>
map</em></span>
 entries. The first map entry specifies that shift level one is to be used if
no modifiers are set. The second entry specifies the <span class="emphasis"><em>
Lock</em></span>
 modifier alone also yields shift level one. The third entry specifies the
<span class="emphasis"><em>
Shift</em></span>
 modifier alone yields shift level two. The fourth and fifth entries specify
that the virtual <span class="emphasis"><em>
LevelThree</em></span>
 modifier alone, or in combination with the <span class="emphasis"><em>
Shift</em></span>
 modifier, yields shift level three.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Shift level three can be reached only if the virtual modifier
<span class="emphasis"><em>
LevelThree</em></span>
 is bound to a real modifier (see section 16.4). If <span class="emphasis"><em>
LevelThree</em></span>
 is not bound to a real modifier, the <span class="emphasis"><em>
map</em></span>
 entries associated with it are ignored.</p></div><p>
Because the <span class="emphasis"><em>
Lock</em></span>
 modifier is to be preserved for further event processing, the <span class="emphasis"><em>
preserve</em></span>
 list is not <span class="emphasis"><em>
NULL</em></span>
 and parallels the <span class="emphasis"><em>
map</em></span>
 list. All <span class="emphasis"><em>
preserve</em></span>
 entries, except for the one corresponding to the <span class="emphasis"><em>
map</em></span>
 entry that specifies the <span class="emphasis"><em>
Lock </em></span>
modifier, do not list any modifiers. For the <span class="emphasis"><em>
map</em></span>
 entry that specifies the <span class="emphasis"><em>
Lock</em></span>
 modifier, the corresponding <span class="emphasis"><em>
preserve</em></span>
 list entry lists the <span class="emphasis"><em>
Lock</em></span>
 modifier, meaning do not consume the <span class="emphasis"><em>
Lock</em></span>
 modifier. In this particular case, the preserved modifier is passed to Xlib
translation functions and causes them to notice that the <span class="emphasis"><em>
Lock</em></span>
 modifier is set; consequently, the Xlib functions apply the appropriate
capitalization rules to the symbol. Because this preserve entry is set only for
a modifier that yields shift level one, the capitalization occurs only for
level-one symbols.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_Canonical_Key_Types"></a>The Canonical Key Types</h3></div></div></div><p>
Xkb allows up to <span class="emphasis"><em>
XkbMaxKeyTypes</em></span>
 (255) key types to be defined, but requires at least <span class="emphasis"><em>
XkbNumRequiredTypes</em></span>
 (4) predefined types to be in a key map. These predefined key types are
referred to as the canonical key types and describe the types of keys available
on most keyboards. The definitions for the canonical key types are held in the
first <span class="emphasis"><em>
XkbNumRequiredTypes</em></span>
 entries of the <span class="emphasis"><em>
types</em></span>
 field of the client map and are indexed using the following constants:
</p><pre class="programlisting">
     <span class="emphasis"><em>XkbOneLevelIndex</em></span>
     <span class="emphasis"><em>XkbTwoLevelIndex</em></span>
     <span class="emphasis"><em>XkbAlphabeticIndex</em></span>
     <span class="emphasis"><em>XkbKeypadIndex</em></span>
</pre><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="ONE_LEVEL"></a>ONE_LEVEL</h4></div></div></div><p>
The ONE_LEVEL key type describes groups that have only one symbol. The default
ONE_LEVEL key type has no map entries and does not pay attention to any
modifiers. A symbolic representation of this key type could look like the
following:
</p><div class="literallayout"><p><br />
type "ONE_LEVEL" {<br />
      modifiers = None;<br />
      map[None]= Level1;<br />
      level_name[Level1]= "Any";<br />
};<br />
</p></div><p>
The description of the ONE_LEVEL key type is stored in the <span class="emphasis"><em>
types</em></span>
[<span class="emphasis"><em>
XkbOneLevelIndex</em></span>
] entry of the client key map.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="TWO_LEVEL"></a>TWO_LEVEL</h4></div></div></div><p>
The TWO_LEVEL key type describes groups that consist of two symbols but are
neither alphabetic nor numeric keypad keys. The default TWO_LEVEL type uses
only the <span class="emphasis"><em>
Shift</em></span>
 modifier. It returns shift level two if <span class="emphasis"><em>
Shift</em></span>
 is set, and level one if it is not. A symbolic representation of this key type
could look like the following:
</p><div class="literallayout"><p><br />
type "TWO_LEVEL" {<br />
      modifiers = Shift;<br />
      map[Shift]= Level2;<br />
      level_name[Level1]= "Base";<br />
      level_name[Level2]= "Shift";<br />
};<br />
</p></div><p>
The description of the TWO_LEVEL key type is stored in the <span class="emphasis"><em>
types</em></span>
[<span class="emphasis"><em>
XkbTwoLevelIndex</em></span>
] entry of the client key map.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="ALPHABETIC"></a>ALPHABETIC</h4></div></div></div><p>
The ALPHABETIC key type describes groups consisting of two symbols: the
lowercase form of a symbol followed by the uppercase form of the same symbol.
The default ALPHABETIC type implements locale-sensitive "Shift cancels
CapsLock" behavior using both the <span class="emphasis"><em>
Shift</em></span>
 and <span class="emphasis"><em>
Lock</em></span>
 modifiers as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If <span class="emphasis"><em>
Shift</em></span>
 and <span class="emphasis"><em>
Lock</em></span>
 are both set, the default ALPHABETIC type yields level one.
  </p></li><li class="listitem"><p>
If <span class="emphasis"><em>
Shift</em></span>
 alone is set, it yields level two.
  </p></li><li class="listitem"><p>
If <span class="emphasis"><em>
Lock</em></span>
 alone is set, it yields level one, but preserves the <span class="emphasis"><em>
Lock</em></span>
 modifier so Xlib notices and applies the appropriate capitalization rules. The
Xlib functions are locale-sensitive and apply different capitalization rules
for different locales.
  </p></li><li class="listitem"><p>
If neither <span class="emphasis"><em>
Shift</em></span>
 nor <span class="emphasis"><em>
Lock</em></span>
 is set, it yields level one.
  </p></li></ul></div><p>
A symbolic representation of this key type could look like the following:
</p><div class="literallayout"><p><br />
type "ALPHABETIC" {<br />
      modifiers = Shift+Lock;<br />
      map[Shift]= Level2;<br />
      preserve[Lock]= Lock;<br />
      level_name[Level1]= "Base";<br />
      level_name[Level2]= "Caps";<br />
};<br />
</p></div><p>
The description of the ALPHABETIC key type is stored in the <span class="emphasis"><em>
types</em></span>
[<span class="emphasis"><em>
XkbAlphabeticIndex</em></span>
] entry of the client key map.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="KEYPAD"></a>KEYPAD</h4></div></div></div><p>
The KEYPAD key type describes groups that consist of two symbols, at least one
of which is a numeric keypad symbol. The numeric keypad symbol is assumed to
reside at level two. The default KEYPAD key type implements "Shift cancels
NumLock" behavior using the Shift modifier and the real modifier bound to the
virtual modifier named "NumLock," known as the <span class="emphasis"><em>
NumLock</em></span>
 modifier, as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If <span class="emphasis"><em>
Shift</em></span>
 and <span class="emphasis"><em>
NumLock</em></span>
 are both set, the default KEYPAD type yields level one.
  </p></li><li class="listitem"><p>
If <span class="emphasis"><em>
Shift</em></span>
 alone is set, it yields level two.
  </p></li><li class="listitem"><p>
If <span class="emphasis"><em>
NumLock</em></span>
 alone is set, it yields level two.
  </p></li><li class="listitem"><p>
If neither <span class="emphasis"><em>
Shift</em></span>
 nor <span class="emphasis"><em>
NumLock</em></span>
 is set, it yields level one.
  </p></li></ul></div><p>
A symbolic representation of this key type could look like the following:
</p><div class="literallayout"><p><br />
type "KEYPAD" {<br />
      modifiers = Shift+NumLock;<br />
      map[None]= Level1;<br />
      map[Shift]= Level2;<br />
      map[NumLock]= Level2;<br />
      map[Shift+NumLock]= Level1;<br />
      level_name[Level1]= "Base";<br />
      level_name[Level2]= "Caps";<br />
};<br />
</p></div><p>
The description of the KEYPAD key type is stored in the <span class="emphasis"><em>
types</em></span>
[<span class="emphasis"><em>
XkbKeypadIndex</em></span>
] entry of the client key map.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Initializing_the_Canonical_Key_Types_in_a_New_Client_Map"></a>Initializing the Canonical Key Types in a New Client Map</h4></div></div></div><p>
To set the definitions of the canonical key types in a client map to their
default values, use <span class="emphasis"><em>
XkbInitCanonicalKeyTypes.</em></span>
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbInitCanonicalKeyTypes</em></span>
(<span class="emphasis"><em>
xkb, which, keypadVMod</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;            /* keyboard description containing client map to initialize */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
which</em></span>
;            /* mask of types to initialize */
    </td></tr><tr><td class="functionargdecl" align="left">
int            <span class="emphasis"><em>
keypadVMod</em></span>
;            /* index of NumLock virtual modifier */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbInitCanonicalKeyTypes</em></span>
 initializes the first <span class="emphasis"><em>
XkbNumRequiredTypes</em></span>
 key types of the keyboard specified by the <span class="emphasis"><em>
xkb</em></span>
 parameter to their default values. The <span class="emphasis"><em>
which</em></span>
 parameter specifies what canonical key types to initialize and is a bitwise
inclusive OR of the following masks: <span class="emphasis"><em>
XkbOneLevelMask</em></span>
, <span class="emphasis"><em>
XkbTwoLevelMask</em></span>
, <span class="emphasis"><em>
XkbAlphabeticMask</em></span>
, and <span class="emphasis"><em>
XkbKeypadMask</em></span>
. Only those canonical types specified by the <span class="emphasis"><em>
which</em></span>
 mask are initialized.
</p><p>
If <span class="emphasis"><em>
XkbKeypadMask</em></span>
 is set in the <span class="emphasis"><em>
which</em></span>
 parameter, <span class="emphasis"><em>
XkbInitCanonicalKeyTypes</em></span>
 looks up the <span class="emphasis"><em>
NumLock</em></span>
 named virtual modifier to determine which virtual modifier to use when
initializing the KEYPAD key type. If the <span class="emphasis"><em>
NumLock</em></span>
 virtual modifier does not exist, <span class="emphasis"><em>
XkbInitCanonicalKeyTypes</em></span>
 creates it.
</p><p>
<span class="emphasis"><em>
XkbInitCanonicalKeyTypes</em></span>
 normally returns Success. It returns <span class="emphasis"><em>
BadAccess</em></span>
 if the Xkb extension has not been properly initialized, and <span class="emphasis"><em>
BadAccess</em></span>
 if the <span class="emphasis"><em>
xkb</em></span>
 parameter is not valid.
</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Getting_Key_Types_from_the_Server"></a>Getting Key Types from the Server</h3></div></div></div><p>
To obtain the list of available key types in the server’s keyboard mapping,
use <span class="emphasis"><em>
XkbGetKeyTypes</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetKeyTypes</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 first</em></span>
,<span class="emphasis"><em>
 num</em></span>
,<span class="emphasis"><em>
 xkb</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
            first</em></span>
;            /* index to first type to get, 0 =&gt; 1st type */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
num</em></span>
;            /* number of key types to be returned */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr             <span class="emphasis"><em>
xkb</em></span>
;            /* keyboard description containing client map to update */
    </td></tr></tbody></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p><span class="emphasis"><em>
XkbGetKeyTypes</em></span>
 is used to obtain descriptions of the key types themselves, not the key types
bound to individual keys. To obtain the key types bound to an individual key,
refer to the <span class="emphasis"><em>
key_sym_map</em></span>
 field of the client map (see section 15.3.1).</p></div><p>
<span class="emphasis"><em>
XkbGetKeyTypes</em></span>
 queries the server for the desired types, waits for a reply, and returns the
desired types in the <span class="emphasis"><em>
xkb-&gt;map-&gt;types</em></span>
. If successful, it returns Success.
</p><p>
<span class="emphasis"><em>
XkbGetKeyTypes</em></span>
 returns <span class="emphasis"><em>
BadAccess</em></span>
 if the Xkb extension has not been properly initialized and <span class="emphasis"><em>
BadValue</em></span>
 if the combination of <span class="emphasis"><em>
first</em></span>
 and <span class="emphasis"><em>
num</em></span>
 results in numbers out of valid range.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Changing_the_Number_of_Levels_in_a_Key_Type"></a>Changing the Number of Levels in a Key Type</h3></div></div></div><p>
To change the number of levels in a key type, use <span class="emphasis"><em>
XkbResizeKeyType</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbResizeKeyType</em></span>
(<span class="emphasis"><em>
xkb</em></span>
,<span class="emphasis"><em>
 type_ndx</em></span>
,<span class="emphasis"><em>
 map_count</em></span>
,<span class="emphasis"><em>
 want_preserve</em></span>
,<span class="emphasis"><em>
 new_num_lvls</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr<span class="emphasis"><em>
            xkb</em></span>
;            /* keyboard description containing client map to update */
    </td></tr><tr><td class="functionargdecl" align="left">
int <span class="emphasis"><em>
            type_ndx</em></span>
;            /* index in xkb-&gt;map-&gt;types of type to change */
    </td></tr><tr><td class="functionargdecl" align="left">
int             <span class="emphasis"><em>
map_count</em></span>
;            /* total # of map entries needed for the type */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool             <span class="emphasis"><em>
want_preserve</em></span>
;            /* <span class="emphasis"><em>
True</em></span>
 =&gt; list of preserved modifiers is necessary */
    </td></tr><tr><td class="functionargdecl" align="left">
int <span class="emphasis"><em>
            new_num_lvls</em></span>
;            /* new max # of levels for type */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbResizeKeyType</em></span>
 changes the type specified by <span class="emphasis"><em>
xkb</em></span>
-&gt;<span class="emphasis"><em>
map-&gt;types</em></span>
[<span class="emphasis"><em>
type_ndx</em></span>
], and reallocates the symbols and actions bound to all keys that use the type,
if necessary. <span class="emphasis"><em>
XkbResizeKeyType</em></span>
 updates only the local copy of the types in <span class="emphasis"><em>
xkb</em></span>
; to update the server’s copy for the physical device, use <span class="emphasis"><em>
XkbSetMap</em></span>
 or <span class="emphasis"><em>
XkbChangeMap</em></span>
 after calling <span class="emphasis"><em>
XkbResizeKeyType</em></span>
.
</p><p>
The <span class="emphasis"><em>
map_count</em></span>
 parameter specifies the total number of map entries needed for the type, and
can be zero or greater. If <span class="emphasis"><em>
map_count</em></span>
 is zero, <span class="emphasis"><em>
XkbResizeKeyType</em></span>
 frees the existing <span class="emphasis"><em>
map</em></span>
 and <span class="emphasis"><em>
preserve</em></span>
 entries for the type if they exist and sets them to <span class="emphasis"><em>
NULL</em></span>
.
</p><p>
The <span class="emphasis"><em>
want_preserve</em></span>
 parameter specifies whether a <span class="emphasis"><em>
preserve</em></span>
 list for the key should be created. If <span class="emphasis"><em>
want_preserve</em></span>
 is <span class="emphasis"><em>
True</em></span>
, the <span class="emphasis"><em>
preserve</em></span>
 list with <span class="emphasis"><em>
map_count</em></span>
 entries is allocated or reallocated if it already exists. Otherwise, if
<span class="emphasis"><em>
want_preserve</em></span>
 is <span class="emphasis"><em>
False</em></span>
, the <span class="emphasis"><em>
preserve</em></span>
 field is freed if necessary and set to <span class="emphasis"><em>
NULL</em></span>
.
</p><p>
The <span class="emphasis"><em>
new_num_lvls</em></span>
 parameter specifies the new maximum number of shift levels for the type and is
used to calculate and resize the symbols and actions bound to all keys that use
the type.
</p><p>
If <span class="emphasis"><em>
type_ndx</em></span>
 does not specify a legal type, <span class="emphasis"><em>
new_num_lvls</em></span>
 is less than 1, or the <span class="emphasis"><em>
map_count</em></span>
 is less than zero, <span class="emphasis"><em>
XkbResizeKeyType</em></span>
 returns <span class="emphasis"><em>
BadValue</em></span>
. If <span class="emphasis"><em>
XkbResizeKeyType</em></span>
 encounters any problems with allocation, it returns <span class="emphasis"><em>
BadAlloc</em></span>
. Otherwise, it returns <span class="emphasis"><em>
Success</em></span>
.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Copying_Key_Types"></a>Copying Key Types</h3></div></div></div><p>
Use <span class="emphasis"><em>
XkbCopyKeyType</em></span>
 and <span class="emphasis"><em>
XkbCopyKeyTypes</em></span>
 to copy one or more <span class="emphasis"><em>
XkbKeyTypeRec</em></span>
 structures.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbCopyKeyType</em></span>
(<span class="emphasis"><em>
from</em></span>
,<span class="emphasis"><em>
 into</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbKeyTypePtr <span class="emphasis"><em>
            from</em></span>
;            /* pointer to XkbKeyTypeRec to be copied */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbKeyTypePtr <span class="emphasis"><em>
            into</em></span>
;            /* pointer to XkbKeyTypeRec to be changed */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbCopyKeyType</em></span>
 copies the key type specified by <span class="emphasis"><em>
from</em></span>
 to the key type specified by <span class="emphasis"><em>
into</em></span>
. Both must point to legal <span class="emphasis"><em>
XkbKeyTypeRec</em></span>
 structures. Xkb assumes <span class="emphasis"><em>
from</em></span>
 and <span class="emphasis"><em>
into</em></span>
 point to different places. As a result, overlaps can be fatal. <span class="emphasis"><em>
XkbCopyKeyType</em></span>
 frees any existing <span class="emphasis"><em>
map</em></span>
, <span class="emphasis"><em>
preserve</em></span>
, and <span class="emphasis"><em>
level_names</em></span>
 in <span class="emphasis"><em>
into</em></span>
 prior to copying. If any allocation errors occur while copying <span class="emphasis"><em>
from</em></span>
 to <span class="emphasis"><em>
into</em></span>
, <span class="emphasis"><em>
XkbCopyKeyType</em></span>
 returns <span class="emphasis"><em>
BadAlloc</em></span>
. Otherwise, <span class="emphasis"><em>
XkbCopyKeyType</em></span>
 copies <span class="emphasis"><em>
from</em></span>
 to <span class="emphasis"><em>
into</em></span>
 and returns <span class="emphasis"><em>
Success</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbCopyKeyTypes</em></span>
(<span class="emphasis"><em>
from</em></span>
,<span class="emphasis"><em>
 into</em></span>
, <span class="emphasis"><em>
num_types</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbKeyTypePtr <span class="emphasis"><em>
            from</em></span>
;            /* pointer to array of XkbKeyTypeRecs to copy */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbKeyTypePtr <span class="emphasis"><em>
            into</em></span>
;            /* pointer to array of XkbKeyTypeRecs to change */
    </td></tr><tr><td class="functionargdecl" align="left">
int <span class="emphasis"><em>
            num_types</em></span>
;            /* number of types to copy */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbCopyKeyTypes</em></span>
 copies <span class="emphasis"><em>
num_types</em></span>
 <span class="emphasis"><em>
XkbKeyTypeRec</em></span>
 structures from the array specified by <span class="emphasis"><em>
from</em></span>
 into the array specified by <span class="emphasis"><em>
into</em></span>
. It is intended for copying between, rather than within, keyboard
descriptions, so it doesn’t check for overlaps. The same rules that apply to
the <span class="emphasis"><em>
from</em></span>
 and <span class="emphasis"><em>
into</em></span>
 parameters in <span class="emphasis"><em>
XkbCopyKeyType</em></span>
 apply to each entry of the <span class="emphasis"><em>
from</em></span>
 and <span class="emphasis"><em>
into</em></span>
 arrays of <span class="emphasis"><em>
XkbCopyKeyTypes</em></span>
. If any allocation errors occur while copying <span class="emphasis"><em>
from</em></span>
 to <span class="emphasis"><em>
into</em></span>
, <span class="emphasis"><em>
XkbCopyKeyTypes</em></span>
 returns <span class="emphasis"><em>
BadAlloc</em></span>
. Otherwise, <span class="emphasis"><em>
XkbCopyKeyTypes</em></span>
 copies <span class="emphasis"><em>
from</em></span>
 to <span class="emphasis"><em>
into</em></span>
 and returns <span class="emphasis"><em>
Success</em></span>
.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Key_Symbol_Map"></a>Key Symbol Map</h2></div></div></div><p>
The entire list of key symbols for the keyboard mapping is held in the
<span class="emphasis"><em>
syms</em></span>
 field of the client map. Whereas the core keyboard mapping is a
two-dimensional array of <span class="emphasis"><em>
KeySyms</em></span>
 whose rows are indexed by keycode, the <span class="emphasis"><em>
syms</em></span>
 field of Xkb is a linear list of <span class="emphasis"><em>
KeySyms</em></span>
 that needs to be indexed uniquely for each key. This section describes the key
symbol map and the methods for determining the symbols bound to a key.
</p><p>
The reason the <span class="emphasis"><em>
syms</em></span>
 field is a linear list of <span class="emphasis"><em>
KeySyms</em></span>
 is to reduce the memory consumption associated with a keymap; because Xkb
allows individual keys to have multiple shift levels and a different number of
groups per key, a single two-dimensional array of <span class="emphasis"><em>
KeySyms</em></span>
 would potentially be very large and sparse. Instead, Xkb provides a small
two-dimensional array of <span class="emphasis"><em>
KeySyms</em></span>
 for each key. To store all of these individual arrays, Xkb concatenates each
array together in the <span class="emphasis"><em>
syms</em></span>
 field of the client map.
</p><p>
In order to determine which <span class="emphasis"><em>
KeySyms</em></span>
 in the <span class="emphasis"><em>
syms</em></span>
 field are associated with each keycode, the client map contains an array of
key symbol mappings, held in the <span class="emphasis"><em>
key_sym_map</em></span>
 field. The <span class="emphasis"><em>
key_sym_map</em></span>
 field is an array of <span class="emphasis"><em>
XkbSymMapRec</em></span>
 structures indexed by keycode. The <span class="emphasis"><em>
key_sym_map</em></span>
 array has <span class="emphasis"><em>
min_key_code</em></span>
 unused entries at the start to allow direct indexing using a keycode. All
keycodes falling between the minimum and maximum legal keycodes, inclusive,
have <span class="emphasis"><em>
key_sym_map</em></span>
 arrays, whether or not any key actually yields that code. The <span class="emphasis"><em>
KeySymMapRec</em></span>
 structure is defined as follows:
</p><pre class="programlisting">
#define XkbNumKbdGroups            4
#define XkbMaxKbdGroup            (XkbNumKbdGroups-1)
</pre><pre class="programlisting">
typedef struct {                                   /* map to keysyms for a single keycode */
      unsigned char     kt_index[XkbNumKbdGroups]; /* key type index for each group */
      unsigned char     group_info;                /* # of groups and out of range group handling */
      unsigned char     width;                     /* max # of shift levels for key */
      unsigned short    offset;                    /* index to keysym table in <span class="emphasis"><em> syms</em></span> array */
} <span class="emphasis"><em>XkbSymMapRec</em></span>, *XkbSymMapPtr;
</pre><p>
These fields are described in detail in the following sections.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Per_Key_Key_Type_Indices"></a>Per-Key Key Type Indices</h3></div></div></div><p>
The <span class="emphasis"><em>
kt_index</em></span>
 array of the <span class="emphasis"><em>
XkbSymMapRec</em></span>
 structure contains the indices of the key types (see section 15.2) for each
possible group of symbols associated with the key. To obtain the index of a key
type or the pointer to a key type, Xkb provides the following macros, to access
the key types:
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The array of key types is of fixed width and is large enough to
hold key types for the maximum legal number of groups (<span class="emphasis"><em>
XkbNumKbdGroups</em></span>
, currently four); if a key has fewer than <span class="emphasis"><em>
XkbNumKbdGroups</em></span>
 groups, the extra key types are reported but ignored.</p></div><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
int <span class="emphasis"><em>
XkbKeyTypeIndex</em></span>
(<span class="emphasis"><em>
xkb, keycode, group</em></span>
)                              /* macro*/
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;                  /* Xkb description of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode            <span class="emphasis"><em>
keycode</em></span>
;                  /* keycode of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
int            <span class="emphasis"><em>
group</em></span>
;                  /* group index */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbKeyTypeIndex</em></span>
 computes an index into the <span class="emphasis"><em>
types</em></span>
 vector of the client map in <span class="emphasis"><em>
xkb</em></span>
 from the given <span class="emphasis"><em>
keycode</em></span>
 and <span class="emphasis"><em>
group</em></span>
 index.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbKeyTypePtr <span class="emphasis"><em>
XkbKeyType</em></span>
(<span class="emphasis"><em>
xkb, keycode, group</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;                  /* Xkb description of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode            <span class="emphasis"><em>
keycode</em></span>
;                  /* keycode of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
int            <span class="emphasis"><em>
group</em></span>
;                  /* group index */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbKeyType</em></span>
 returns a pointer to the key type in the <span class="emphasis"><em>
types</em></span>
 vector of the client map in <span class="emphasis"><em>
xkb</em></span>
 corresponding to the given <span class="emphasis"><em>
keycode</em></span>
 and <span class="emphasis"><em>
group</em></span>
 index.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Per_Key_Group_Information"></a>Per-Key Group Information</h3></div></div></div><p>
The <span class="emphasis"><em>
group_info</em></span>
 field of an <span class="emphasis"><em>
XkbSymMapRec</em></span>
 is an encoded value containing the number of groups of symbols bound to the
key as well as the specification of the treatment of out-of-range groups. It is
legal for a key to have zero groups, in which case it also has zero symbols and
all events from that key yield <span class="emphasis"><em>
NoSymbol</em></span>
. To obtain the number of groups of symbols bound to the key, use <span class="emphasis"><em>
XkbKeyNumGroups</em></span>
. To change the number of groups bound to a key, use <span class="emphasis"><em>
XkbChangeTypesOfKey</em></span>
 (see section 15.3.6). To obtain a mask that determines the treatment of
out-of-range groups, use <span class="emphasis"><em>
XkbKeyGroupInfo</em></span>
 and <span class="emphasis"><em>
XkbOutOfRangeGroupInfo</em></span>
.
</p><p>
The keyboard controls (see Chapter 10) contain a <span class="emphasis"><em>
groups_wrap</em></span>
 field specifying the handling of illegal groups on a global basis. That is,
when the user performs an action causing the effective group to go out of the
legal range, the <span class="emphasis"><em>
groups_wrap</em></span>
 field specifies how to normalize the effective keyboard group to a group that
is legal for the keyboard as a whole, but there is no guarantee that the
normalized group will be within the range of legal groups for any individual
key. The per-key <span class="emphasis"><em>
group_info</em></span>
 field specifies how a key treats a legal effective group if the key does not
have a type specified for the group of concern. For example, the <span class="emphasis"><em>
Enter</em></span>
 key usually has just one group defined. If the user performs an action causing
the global keyboard group to change to <span class="emphasis"><em>
Group2</em></span>
, the <span class="emphasis"><em>
group_info</em></span>
 field for the <span class="emphasis"><em>
Enter</em></span>
 key describes how to handle this situation.
</p><p>
Out-of-range groups for individual keys are mapped to a legal group using the
same options as are used for the overall keyboard group. The particular type of
mapping used is controlled by the bits set in the <span class="emphasis"><em>
group_info</em></span>
 flag, as shown in Table 15.2. See section 10.7.1 for more details on the
normalization methods in this table.
</p><div class="table"><a id="idp67011620"></a><p class="title"><strong>Table 15.2. group_info Range Normalization</strong></p><div class="table-contents"><table summary="group_info Range Normalization" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Bits set in group_info</th><th align="left">Normalization method</th></tr></thead><tbody><tr><td align="left">XkbRedirectIntoRange</td><td align="left">XkbRedirectIntoRange</td></tr><tr><td align="left">XkbClampIntoRange</td><td align="left">XkbClampIntoRange</td></tr><tr><td align="left">none of the above</td><td align="left">XkbWrapIntoRange</td></tr></tbody></table></div></div><br class="table-break" /><p>
Xkb provides the following macros to access group information:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
int <span class="emphasis"><em>
XkbKeyNumGroups</em></span>
(<span class="emphasis"><em>
xkb, keycode</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;                  /* Xkb description of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode            <span class="emphasis"><em>
keycode</em></span>
;                  /* keycode of interest */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbKeyNumGroups</em></span>
 returns the number of groups of symbols bound to the key corresponding to
<span class="emphasis"><em>
keycode</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
unsigned char <span class="emphasis"><em>
XkbKeyGroupInfo</em></span>
(<span class="emphasis"><em>
xkb, keycode</em></span>
)                              /*macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;                  /* Xkb description of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode            <span class="emphasis"><em>
keycode</em></span>
;                  /* keycode of interest */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbKeyGroupInfo</em></span>
 returns the <span class="emphasis"><em>
group_info</em></span>
 field from the <span class="emphasis"><em>
XkbSymMapRec</em></span>
 structure associated with the key corresponding to <span class="emphasis"><em>
keycode</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
unsigned char <span class="emphasis"><em>
XkbOutOfRangeGroupInfo</em></span>
(<span class="emphasis"><em>
grp_inf</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned char            <span class="emphasis"><em>
grp_inf</em></span>
;                  /* group_info field of <span class="emphasis"><em>
XkbSymMapRec</em></span>
 */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbOutOfRangeGroupInfo</em></span>
 returns only the out-of-range processing information from the <span class="emphasis"><em>
group_info</em></span>
 field of an <span class="emphasis"><em>
XkbSymMapRec</em></span>
 structure.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
unsigned char <span class="emphasis"><em>
XkbOutOfRangeGroupNumber</em></span>
(<span class="emphasis"><em>
grp_inf</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned char            <span class="emphasis"><em>
grp_inf</em></span>
;                  /* group_info field of <span class="emphasis"><em>
XkbSymMapRec</em></span>
 */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbOutOfRangeGroupNumber</em></span>
 returns the out-of-range group number, represented as a group index, from the
<span class="emphasis"><em>
group_info</em></span>
 field of an <span class="emphasis"><em>
XkbSymMapRec</em></span>
 structure.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Key_Width"></a>Key Width</h3></div></div></div><p>
The maximum number of shift levels for a type is also referred to as the width
of a key type. The <span class="emphasis"><em>
width</em></span>
 field of the <span class="emphasis"><em>
key_sym_map</em></span>
 entry for a key contains the width of the widest type associated with the key.
The <span class="emphasis"><em>
width </em></span>
field cannot be explicitly changed; it is updated automatically whenever the
symbols or set of types bound to a key are changed.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Offset_in_to_the_Symbol_Map"></a>Offset in to the Symbol Map</h3></div></div></div><p>
The key width and number of groups associated with a key are used to form a
small two-dimensional array of <span class="emphasis"><em>
KeySyms</em></span>
 for a key. This array may be different sizes for different keys. The array for
a single key is stored as a linear list, in row-major order. The arrays for all
of the keys are stored in the <span class="emphasis"><em>
syms</em></span>
 field of the client map. There is one row for each group associated with a key
and one column for each level. The index corresponding to a given group and
shift level is computed as:
</p><div class="literallayout"><p><br />
     idx = group_index * key_width + shift_level<br />
</p></div><p>
The <span class="emphasis"><em>
offset</em></span>
 field of the <span class="emphasis"><em>
key_sym_map</em></span>
 entry for a key is used to access the beginning of the array.
</p><p>
Xkb provides the following macros for accessing the <span class="emphasis"><em>
width</em></span>
 and <span class="emphasis"><em>
offset</em></span>
 for individual keys, as well as macros for accessing the two-dimensional array
of symbols bound to the key:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
int <span class="emphasis"><em>
XkbKeyGroupsWidth</em></span>
(<span class="emphasis"><em>
xkb, keycode</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;                  /* Xkb description of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode            <span class="emphasis"><em>
keycode</em></span>
;                  /* keycode of interest */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbKeyGroupsWidth</em></span>
 computes the maximum width associated with the key corresponding to <span class="emphasis"><em>
keycode</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
int <span class="emphasis"><em>
XkbKeyGroupWidth</em></span>
(<span class="emphasis"><em>
xkb, keycode, grp</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;                  /* Xkb description of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode            <span class="emphasis"><em>
keycode</em></span>
;                  /* keycode of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
int            <span class="emphasis"><em>
grp</em></span>
;                  /* group of interest */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbKeyGroupWidth</em></span>
 computes the width of the type associated with the group <span class="emphasis"><em>
grp</em></span>
 for the key corresponding to <span class="emphasis"><em>
keycode</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
int <span class="emphasis"><em>
XkbKeySymsOffset</em></span>
(<span class="emphasis"><em>
xkb, keycode</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;                  /* Xkb description of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode            <span class="emphasis"><em>
keycode</em></span>
;                  /* keycode of interest */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbKeySymsOffset</em></span>
 returns the offset of the two-dimensional array of keysyms for the key
corresponding to <span class="emphasis"><em>
keycode</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
int <span class="emphasis"><em>
XkbKeyNumSyms</em></span>
(<span class="emphasis"><em>
xkb, keycode</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;                  /* Xkb description of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode            <span class="emphasis"><em>
keycode</em></span>
;                  /* keycode of interest */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbKeyNumSyms</em></span>
 returns the total number of keysyms for the key corresponding to <span class="emphasis"><em>
keycode</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
KeySym * <span class="emphasis"><em>
XkbKeySymsPtr</em></span>
(<span class="emphasis"><em>
xkb, keycode</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;                  /* Xkb description of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode            <span class="emphasis"><em>
keycode</em></span>
;                  /* keycode of interest */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbKeySymsPtr</em></span>
 returns the pointer to the two-dimensional array of keysyms for the key
corresponding to <span class="emphasis"><em>
keycode</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
KeySym <span class="emphasis"><em>
XkbKeySymEntry</em></span>
(<span class="emphasis"><em>
xkb, keycode, shift, grp</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;                  /* Xkb description of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode            <span class="emphasis"><em>
keycode</em></span>
;                  /* keycode of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
int            <span class="emphasis"><em>
shift</em></span>
;                  /* shift level of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
int            <span class="emphasis"><em>
grp</em></span>
;                  /* group of interest */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbKeySymEntry</em></span>
 returns the <span class="emphasis"><em>
keysym</em></span>
 corresponding to shift level <span class="emphasis"><em>
shift</em></span>
 and group <span class="emphasis"><em>
grp</em></span>
 from the two-dimensional array of keysyms for the key corresponding to
<span class="emphasis"><em>
keycode</em></span>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Getting_the_Symbol_Map_for_Keys_from_the_Server"></a>Getting the Symbol Map for Keys from the Server</h3></div></div></div><p>
To obtain the symbols for a subset of the keys in a keyboard description, use
<span class="emphasis"><em>
XkbGetKeySyms</em></span>
:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetKeySyms</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 first</em></span>
, <span class="emphasis"><em>
num</em></span>
,<span class="emphasis"><em>
 xkb</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
            first</em></span>
;            /* keycode of first key to get */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
      num</em></span>
;            /* number of keycodes for which syms desired */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr             <span class="emphasis"><em>
xkb</em></span>
;            /* Xkb description to be updated */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetKeySyms</em></span>
 sends a request to the server to obtain the set of keysyms bound to <span class="emphasis"><em>
num</em></span>
 keys starting with the key whose keycode is <span class="emphasis"><em>
first</em></span>
. It waits for a reply and returns the keysyms in the <span class="emphasis"><em>
map.syms</em></span>
 field of <span class="emphasis"><em>
xkb</em></span>
. If successful, <span class="emphasis"><em>
XkbGetKeySyms</em></span>
 returns <span class="emphasis"><em>
Success</em></span>
. The <span class="emphasis"><em>
xkb</em></span>
 parameter must be a pointer to a valid Xkb keyboard description.
</p><p>
If the client <span class="emphasis"><em>
map</em></span>
 in the <span class="emphasis"><em>
xkb</em></span>
 parameter has not been allocated, <span class="emphasis"><em>
XkbGetKeySyms</em></span>
 allocates and initializes it before obtaining the symbols.
</p><p>
If a compatible version of Xkb is not available in the server or the Xkb
extension has not been properly initialized, <span class="emphasis"><em>
XkbGetKeySyms</em></span>
 returns <span class="emphasis"><em>
BadAccess</em></span>
. If <span class="emphasis"><em>
num</em></span>
 is less than 1 or greater than <span class="emphasis"><em>
XkbMaxKeyCount</em></span>
, <span class="emphasis"><em>
XkbGetKeySyms</em></span>
 returns <span class="emphasis"><em>
BadValue</em></span>
. If any allocation errors occur, <span class="emphasis"><em>
XkbGetKeySyms</em></span>
 returns <span class="emphasis"><em>
BadAlloc</em></span>
.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Changing_the_Number_of_Groups_and_Types_Bound_to_a_Key"></a>Changing the Number of Groups and Types Bound to a Key</h3></div></div></div><p>
To change the number of groups and the types bound to a key, use <span class="emphasis"><em>
XkbChangeTypesOfKey</em></span>
.
</p><p>
Status <span class="emphasis"><em>
XkbChangeTypesOfKey</em></span>
(<span class="emphasis"><em>
xkb</em></span>
,<span class="emphasis"><em>
 key</em></span>
,<span class="emphasis"><em>
 n_groups</em></span>
,<span class="emphasis"><em>
 groups</em></span>
,<span class="emphasis"><em>
 new_types_in</em></span>
,<span class="emphasis"><em>
 p_changes</em></span>
)
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functionargdecl" align="left">
XkbDescPtr <span class="emphasis"><em>
            xkb</em></span>
;            /* keyboard description to be changed */
    </td></tr><tr><td class="functionargdecl" align="left">
int <span class="emphasis"><em>
            key</em></span>
;            /* keycode for key of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
int <span class="emphasis"><em>
            n_groups</em></span>
;            /* new number of groups for key */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
groups</em></span>
;            /* mask indicating groups to change */
    </td></tr><tr><td class="functionargdecl" align="left">
int *            <span class="emphasis"><em>
new_types_in</em></span>
;            /* indices for new groups specified in <span class="emphasis"><em>
groups</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbMapChangesPtr            <span class="emphasis"><em>
p_changes</em></span>
;            /* notes changes made to <span class="emphasis"><em>
xkb</em></span>
 */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbChangeTypesOfKey</em></span>
 reallocates the symbols and actions bound to the key, if necessary, and
initializes any new symbols or actions to <span class="emphasis"><em>
NoSymbol</em></span>
 or <span class="emphasis"><em>
NoAction</em></span>
, as appropriate. If the <span class="emphasis"><em>
p_changes</em></span>
 parameter is not <span class="emphasis"><em>
NULL</em></span>
, <span class="emphasis"><em>
XkbChangeTypesOfKey</em></span>
 adds the <span class="emphasis"><em>
XkbKeySymsMask</em></span>
 to the <span class="emphasis"><em>
changes</em></span>
 field of <span class="emphasis"><em>
p_changes</em></span>
 and modifies the <span class="emphasis"><em>
first_key_sym</em></span>
 and <span class="emphasis"><em>
num_key_syms</em></span>
 fields of <span class="emphasis"><em>
p_changes</em></span>
 to include the <span class="emphasis"><em>
key</em></span>
 that was changed. See section 14.3.1 for more information on the <span class="emphasis"><em>
XkbMapChangesPtr</em></span>
 structure. If successful, <span class="emphasis"><em>
XkbChangeTypesOfKey</em></span>
 returns <span class="emphasis"><em>
Success</em></span>
.
</p><p>
The <span class="emphasis"><em>
n_groups</em></span>
 parameter specifies the new number of groups for the key. The <span class="emphasis"><em>
groups</em></span>
 parameter is a mask specifying the groups for which new types are supplied and
is a bitwise inclusive OR of the following masks: <span class="emphasis"><em>
XkbGroup1Mask</em></span>
, <span class="emphasis"><em>
XkbGroup2Mask</em></span>
, <span class="emphasis"><em>
XkbGroup3Mask</em></span>
, and <span class="emphasis"><em>
XkbGroup4Mask</em></span>
.
</p><p>
The <span class="emphasis"><em>
new_types_in</em></span>
 parameter is an integer array of length <span class="emphasis"><em>
n_groups</em></span>
. Each entry represents the type to use for the associated group and is an
index into <span class="emphasis"><em>
xkb</em></span>
-&gt;<span class="emphasis"><em>
map-&gt;types</em></span>
. The <span class="emphasis"><em>
new_types_in</em></span>
 array is indexed by group index; if <span class="emphasis"><em>
n_groups</em></span>
 is four and <span class="emphasis"><em>
groups</em></span>
 only has <span class="emphasis"><em>
Group1Mask</em></span>
 and <span class="emphasis"><em>
Group3Mask</em></span>
 set, <span class="emphasis"><em>
new_types_in</em></span>
 looks like this:
</p><div class="literallayout"><p><br />
     new_types_in[0] = type for Group1<br />
     new_types_in[1] = ignored<br />
     new_types_in[2] = type for Group3<br />
     new_types_in[3] = ignored<br />
</p></div><p>
For convenience, Xkb provides the following constants to use as indices to the
groups:
</p><div class="table"><a id="idp67115348"></a><p class="title"><strong>Table 15.3. Group Index Constants</strong></p><div class="table-contents"><table summary="Group Index Constants" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Constant Name</th><th align="left">Value</th></tr></thead><tbody><tr><td align="left">XkbGroup1Index</td><td align="left">0</td></tr><tr><td align="left">XkbGroup2Index</td><td align="left">1</td></tr><tr><td align="left">XkbGroup3Index</td><td align="left">2</td></tr><tr><td align="left">XkbGroup4Index</td><td align="left">3</td></tr></tbody></table></div></div><br class="table-break" /><p>
If the Xkb extension has not been properly initialized, <span class="emphasis"><em>
XkbChangeTypesOfKey</em></span>
 returns <span class="emphasis"><em>
BadAccess</em></span>
. If the <span class="emphasis"><em>
xkb</em></span>
 parameter it not valid (that is, it is <span class="emphasis"><em>
NULL</em></span>
 or it does not contain a valid client map), <span class="emphasis"><em>
XkbChangeTypesOfKey</em></span>
 returns <span class="emphasis"><em>
Bad</em></span>
Match. If the <span class="emphasis"><em>
key</em></span>
 is not a valid keycode, <span class="emphasis"><em>
n_groups</em></span>
 is greater than <span class="emphasis"><em>
XkbNumKbdGroups</em></span>
, or the <span class="emphasis"><em>
groups</em></span>
 mask does not contain any of the valid group mask bits, <span class="emphasis"><em>
XkbChangeTypesOfKey</em></span>
 returns <span class="emphasis"><em>
BadValue</em></span>
. If it is necessary to resize the key symbols or key actions arrays and any
allocation errors occur, <span class="emphasis"><em>
XkbChangeTypesOfKey</em></span>
 returns <span class="emphasis"><em>
BadAlloc</em></span>
.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Changing_the_Number_of_Symbols_Bound_to_a_Key"></a>Changing the Number of Symbols Bound to a Key</h3></div></div></div><p>
To change the number of symbols bound to a key, use <span class="emphasis"><em>
XkbResizeKeySyms</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
KeySym *<span class="emphasis"><em>
XkbResizeKeySyms</em></span>
(<span class="emphasis"><em>
xkb</em></span>
,<span class="emphasis"><em>
 key</em></span>
,<span class="emphasis"><em>
 needed</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescRec *<span class="emphasis"><em>
            xkb</em></span>
;            /* keyboard description to be changed */
    </td></tr><tr><td class="functionargdecl" align="left">
int <span class="emphasis"><em>
            key</em></span>
;            /* keycode for key to modify */
    </td></tr><tr><td class="functionargdecl" align="left">
int <span class="emphasis"><em>
            needed</em></span>
;            /* new number of keysyms required for key */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbResizeKeySyms</em></span>
 reserves the space needed for <span class="emphasis"><em>
needed</em></span>
 keysyms and returns a pointer to the beginning of the new array that holds the
keysyms. It adjusts the <span class="emphasis"><em>
offset</em></span>
 field of the <span class="emphasis"><em>
key_sym_map</em></span>
 entry for the key if necessary and can also change the <span class="emphasis"><em>
syms</em></span>
, <span class="emphasis"><em>
num_syms</em></span>
, and <span class="emphasis"><em>
size_syms</em></span>
 fields of <span class="emphasis"><em>
xkb</em></span>
-<span class="emphasis"><em>
&gt;map</em></span>
 if it is necessary to reallocate the <span class="emphasis"><em>
syms</em></span>
 array. <span class="emphasis"><em>
XkbResizeKeySyms</em></span>
 does not modify either the width or number of groups associated with the key.
</p><p>
If <span class="emphasis"><em>
needed</em></span>
 is greater than the current number of keysyms for the key, <span class="emphasis"><em>
XkbResizeKeySyms</em></span>
 initializes all new keysyms in the array to <span class="emphasis"><em>
NoSymbol</em></span>
.
</p><p>
Because the number of symbols needed by a key is normally computed as width *
number of groups, and <span class="emphasis"><em>
XkbResizeKeySyms</em></span>
 does not modify either the width or number of groups for the key, a
discrepancy exists upon return from <span class="emphasis"><em>
XkbResizeKeySyms</em></span>
 between the space allocated for the keysyms and the number required. The
unused entries in the list of symbols returned by <span class="emphasis"><em>
XkbResizeKeySyms</em></span>
 are not preserved across future calls to any of the map editing functions, so
you must update the key symbol mapping (which updates the width and number of
groups for the key) before calling another allocator function. A call to
<span class="emphasis"><em>
XkbChangeTypesOfKey</em></span>
 will update the mapping.
</p><p>
If any allocation errors occur while resizing the number of symbols bound to
the key, <span class="emphasis"><em>
XkbResizeKeySyms</em></span>
 returns <span class="emphasis"><em>
NULL</em></span>
.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>A change to the number of symbols bound to a key should be
accompanied by a change in the number of actions bound to a key. Refer to
section 16.1.16 for more information on changing the number of actions bound to
a key.</p></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="The_Per_Key_Modifier_Map"></a>The Per-Key Modifier Map</h2></div></div></div><p>
The <span class="emphasis"><em>
modmap</em></span>
 entry of the client map is an array, indexed by keycode, specifying the real
modifiers bound to a key. Each entry is a mask composed of a bitwise inclusive
OR of the legal real modifiers: <span class="emphasis"><em>
ShiftMask</em></span>
, <span class="emphasis"><em>
LockMask</em></span>
, <span class="emphasis"><em>
ControlMask</em></span>
, <span class="emphasis"><em>
Mod1Mask</em></span>
, <span class="emphasis"><em>
Mod2Mask</em></span>
, <span class="emphasis"><em>
Mod3Mask</em></span>
, <span class="emphasis"><em>
Mod4Mask</em></span>
, and <span class="emphasis"><em>
Mod5Mask</em></span>
. If a bit is set in a <span class="emphasis"><em>
modmap</em></span>
 entry, the corresponding key is bound to that modifier.
</p><p>
Pressing or releasing the key bound to a modifier changes the modifier set and
unset state. The particular manner in which the modifier set and unset state
changes is determined by the behavior and actions assigned to the key (see
Chapter 16).
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Getting_the_Per_Key_Modifier_Map_from_the_Server"></a>Getting the Per-Key Modifier Map from the Server</h3></div></div></div><p>
To update the modifier map for one or more of the keys in a keyboard
description, use <span class="emphasis"><em>
XkbGetKeyModifierMap</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetKeyModifierMap</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 first</em></span>
,<span class="emphasis"><em>
 num</em></span>
,<span class="emphasis"><em>
 xkb</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
first</em></span>
;            /* keycode of first key to get */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
num</em></span>
;            /* number of keys for which information is desired */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr             <span class="emphasis"><em>
xkb</em></span>
;            /* keyboard description to update */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetKeyModifierMap</em></span>
 sends a request to the server for the modifier mappings for <span class="emphasis"><em>
num</em></span>
 keys starting with the key whose keycode is <span class="emphasis"><em>
first</em></span>
. It waits for a reply and places the results in the <span class="emphasis"><em>
xkb</em></span>
-&gt;map-&gt;modmap array. If successful, <span class="emphasis"><em>
XkbGetKeyModifier</em></span>
 returns <span class="emphasis"><em>
Success</em></span>
.
</p><p>
If the map component of the <span class="emphasis"><em>
xkb</em></span>
 parameter has not been allocated, <span class="emphasis"><em>
XkbGetKeyModifierMap</em></span>
 allocates and initializes it.
</p><p>
If a compatible version of Xkb is not available in the server or the Xkb
extension has not been properly initialized, <span class="emphasis"><em>
XkbGetKeySyms</em></span>
 returns <span class="emphasis"><em>
BadAccess</em></span>
. If any allocation errors occur while obtaining the modifier map, <span class="emphasis"><em>
XkbGetKeyModifierMap</em></span>
 returns <span class="emphasis"><em>
BadAlloc</em></span>
.
</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Xkb_Server_Keyboard_Mapping"></a>Chapter 16. Xkb Server Keyboard Mapping</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Key_Actions">Key Actions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#The_XkbAction_Structure">The XkbAction Structure</a></span></dt><dt><span class="sect2"><a href="#The_XkbAnyAction_Structure">The XkbAnyAction Structure</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Changing_Modifiers_State">Actions for Changing Modifiers’ State</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Changing_Group_State">Actions for Changing Group State</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Moving_the_Pointer">Actions for Moving the Pointer</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Simulating_Pointer_Button_Press_and_Release">Actions for Simulating Pointer Button Press and Release</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Changing_the_Pointer_Button_Simulated">Actions for Changing the Pointer Button Simulated</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Locking_Modifiers_and_Group">Actions for Locking Modifiers and Group</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Changing_the_Active_Screen">Actions for Changing the Active Screen</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Changing_Boolean_Controls_State">Actions for Changing Boolean Controls State</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Generating_Messages">Actions for Generating Messages</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Generating_a_Different_Keycode">Actions for Generating a Different Keycode</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Generating_DeviceButtonPress_and_DeviceButtonRelease">Actions for Generating DeviceButtonPress and DeviceButtonRelease</a></span></dt><dt><span class="sect2"><a href="#Actions_for_Simulating_Events_from_Device_Valuators">Actions for Simulating Events from Device Valuators</a></span></dt><dt><span class="sect2"><a href="#Obtaining_Key_Actions_for_Keys_from_the_Server">Obtaining Key Actions for Keys from the Server</a></span></dt><dt><span class="sect2"><a href="#Changing_the_Number_of_Actions_Bound_to_a_Key">Changing the Number of Actions Bound to a Key</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Key_Behavior">Key Behavior</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Radio_Groups_2">Radio Groups</a></span></dt><dt><span class="sect2"><a href="#The_XkbBehavior_Structure">The XkbBehavior Structure</a></span></dt><dt><span class="sect2"><a href="#Obtaining_Key_Behaviors_for_Keys_from_the_Server">Obtaining Key Behaviors for Keys from the Server</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Explicit_ComponentsAvoiding_Automatic_Remapping_by_the_Server">Explicit Components—Avoiding Automatic Remapping by the Server</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Obtaining_Explicit_Components_for_Keys_from_the_Server">Obtaining Explicit Components for Keys from the Server</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Virtual_Modifier_Mapping">Virtual Modifier Mapping</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Obtaining_Virtual_Modifier_Bindings_from_the_Server">Obtaining Virtual Modifier Bindings from the Server</a></span></dt><dt><span class="sect2"><a href="#Obtaining_Per_Key_Virtual_Modifier_Mappings_from_the_Server">Obtaining Per-Key Virtual Modifier Mappings from the Server</a></span></dt></dl></dd></dl></div><p>
The <span class="emphasis"><em>
server</em></span>
 field of the complete Xkb keyboard description (see section 6.1) is a pointer
to the Xkb server map.
</p><p>
Figure 16.1 shows the relationships between elements in the server map:
</p><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-16.svg"></object><div class="caption">Server Map Relationships</div></div><p>
The Xkb server map contains the information the server needs to interpret key
events and is of type <span class="emphasis"><em>
XkbServerMapRec</em></span>
:
</p><pre class="programlisting">
#define XkbNumVirtualMods            16
</pre><pre class="programlisting">
typedef struct {                         /* Server Map */
      unsigned short     num_acts;       /* # of occupied entries in <span class="emphasis"><em> acts</em></span> */
      unsigned short     size_acts;      /* # of entries in <span class="emphasis"><em> acts</em></span> */
      XkbAction *        acts;           /* linear 2d tables of key actions, 1 per keycode */
      XkbBehavior *      behaviors;      /* key behaviors,1 per keycode */
      unsigned short *   key_acts;       /* index into <span class="emphasis"><em> acts</em></span> , 1 per keycode */
      unsigned char *    explicit;       /* explicit overrides of core remapping, 1 per key */
      unsigned char      vmods[XkbNumVirtualMods];  /* real mods bound to virtual mods */
      unsigned short *   vmodmap;        /* virtual mods bound to key, 1 per keycode*/
} <span class="emphasis"><em>XkbServerMapRec</em></span>, *XkbServerMapPtr;
</pre><p>
The <span class="emphasis"><em>
num_acts</em></span>
, <span class="emphasis"><em>
size_acts</em></span>
, <span class="emphasis"><em>
acts</em></span>
, and <span class="emphasis"><em>
key_acts</em></span>
 fields specify the key actions, defined in section 16.1. The <span class="emphasis"><em>
behaviors</em></span>
 field describes the behavior for each key and is defined in section 16.2. The
<span class="emphasis"><em>
explicit</em></span>
 field describes the explicit components for a key and is defined in section
16.3. The <span class="emphasis"><em>
vmods</em></span>
 and the <span class="emphasis"><em>
vmodmap</em></span>
 fields describe the virtual modifiers and the per-key virtual modifier mapping
and are defined in section 16.4.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Key_Actions"></a>Key Actions</h2></div></div></div><p>
A key action defines the effect key presses and releases have on the internal
state of the server. For example, the expected key action associated with
pressing the <span class="emphasis"><em>
Shift</em></span>
 key is to set the <span class="emphasis"><em>
Shift</em></span>
 modifier. There is zero or one key action associated with each keysym bound to
each key.
</p><p>
Just as the entire list of key symbols for the keyboard mapping is held in the
<span class="emphasis"><em>
syms</em></span>
 field of the client map, the entire list of key actions for the keyboard
mapping is held in the <span class="emphasis"><em>
acts</em></span>
 array of the server map. The total size of <span class="emphasis"><em>
acts</em></span>
 is specified by <span class="emphasis"><em>
size_acts</em></span>
, and the number of entries is specified by <span class="emphasis"><em>
num_acts</em></span>.
</p><p>
The <span class="emphasis"><em>
key_acts</em></span>
 array, indexed by keycode, describes the actions associated with a key. The
<span class="emphasis"><em>
key_acts</em></span>
 array has <span class="emphasis"><em>
min_key_code</em></span>
 unused entries at the start to allow direct indexing using a keycode. If a
<span class="emphasis"><em>
key_acts</em></span>
 entry is <span class="emphasis"><em>
zero</em></span>
, it means the key does not have any actions associated with it. If an entry is
not <span class="emphasis"><em>
zero</em></span>
, the entry represents an index into the <span class="emphasis"><em>
acts</em></span>
 field of the server map, much as the <span class="emphasis"><em>
offset</em></span>
 field of a <span class="emphasis"><em>
KeySymMapRec</em></span>
 structure is an index into the <span class="emphasis"><em>
syms</em></span>
 field of the client map.
</p><p>
The reason the <span class="emphasis"><em>
acts</em></span>
 field is a linear list of <span class="emphasis"><em>
XkbAction</em></span>
s is to reduce the memory consumption associated with a keymap. Because Xkb
allows individual keys to have multiple shift levels and a different number of
groups per key, a single two-dimensional array of <span class="emphasis"><em>
KeySyms</em></span>
 would potentially be very large and sparse. Instead, Xkb provides a small
two-dimensional array of <span class="emphasis"><em>
XkbAction</em></span>
s for each key. To store all of these individual arrays, Xkb concatenates each
array together in the <span class="emphasis"><em>
acts</em></span>
 field of the server map.
</p><p>
The key action structures consist only of fields of type char or unsigned char.
This is done to optimize data transfer when the server sends bytes over the
wire. If the fields are anything but bytes, the server has to sift through all
of the actions and swap any nonbyte fields. Because they consist of nothing but
bytes, it can just copy them out.
</p><p>
Xkb provides the following macros, to simplify accessing information pertaining
to key actions:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbKeyHasActions</em></span>
(<span class="emphasis"><em>
xkb, keycode</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;                  /* Xkb description of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode            <span class="emphasis"><em>
keycode</em></span>
;                  /* keycode of interest */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbKeyHasActions</em></span>
 returns <span class="emphasis"><em>
True</em></span>
 if the key corresponding to <span class="emphasis"><em>
keycode</em></span>
 has any actions associated with it; otherwise, it returns <span class="emphasis"><em>
False</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
int <span class="emphasis"><em>
XkbKeyNumActions</em></span>
(<span class="emphasis"><em>
xkb, keycode</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;                  /* Xkb description of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode            <span class="emphasis"><em>
keycode</em></span>
;                  /* keycode of interest */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbKeyNumActions</em></span>
 computes the number of actions associated with the key corresponding to
<span class="emphasis"><em>
keycode</em></span>
. This should be the same value as the result of <span class="emphasis"><em>
XkbKeyNumSyms</em></span>
 (see section 15.3.3).
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbKeyActionPtr <span class="emphasis"><em>
XkbKeyActionsPtr</em></span>
(<span class="emphasis"><em>
xkb, keycode</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;                  /* Xkb description of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode            <span class="emphasis"><em>
keycode</em></span>
;                  /* keycode of interest */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbKeyActionsPtr</em></span>
 returns a pointer to the two-dimensional array of key actions associated with
the key corresponding to <span class="emphasis"><em>
keycode</em></span>
. Use<span class="emphasis"><em>
 XkbKeyActionsPtr</em></span>
 only if the key actually has some actions associated with it, that is,
<span class="emphasis"><em>
XkbKeyNumActions</em></span>
(xkb, keycode) returns something greater than zero.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbAction <span class="emphasis"><em>
XkbKeyAction</em></span>
(<span class="emphasis"><em>
xkb, keycode, idx</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;                  /* Xkb description of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode            <span class="emphasis"><em>
keycode</em></span>
;                  /* keycode of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
int            <span class="emphasis"><em>
idx</em></span>
;                  /* index for group and shift level */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbKeyAction</em></span>
 returns the key action indexed by <span class="emphasis"><em>
idx</em></span>
 in the two-dimensional array of key actions associated with the key
corresponding to <span class="emphasis"><em>
keycode</em></span>
. <span class="emphasis"><em>
idx</em></span>
 may be computed from the group and shift level of interest as follows:
</p><div class="literallayout"><p><br />
     idx = group_index * key_width + shift_level<br />
</p></div><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbAction <span class="emphasis"><em>
XkbKeyActionEntry</em></span>
(<span class="emphasis"><em>
xkb, keycode, shift, grp</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;                  /* Xkb description of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode            <span class="emphasis"><em>
keycode</em></span>
;                  /* keycode of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
int            <span class="emphasis"><em>
shift</em></span>
;                  /* shift level within group */
    </td></tr><tr><td class="functionargdecl" align="left">
int            <span class="emphasis"><em>
grp</em></span>
;                  /* group index for group of interest */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbKeyActionEntry</em></span>
 returns the key action corresponding to group <span class="emphasis"><em>
grp</em></span>
 and shift level <span class="emphasis"><em>
lvl</em></span>
 from the two-dimensional table of key actions associated with the key
corresponding to <span class="emphasis"><em>
keycode</em></span>
.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_XkbAction_Structure"></a>The XkbAction Structure</h3></div></div></div><p>
The description for an action is held in an <span class="emphasis"><em>
XkbAction</em></span>
 structure, which is a union of all possible Xkb action types:
</p><pre class="programlisting">
typedef union _XkbAction {
      XkbAnyAction              any;
      XkbModAction              mods;
      XkbGroupAction            group;
      XkbISOAction              iso;
      XkbPtrAction              ptr;
      XkbPtrBtnAction           btn;
      XkbPtrDfltAction          dflt;
      XkbSwitchScreenAction     screen;
      XkbCtrlsAction            ctrls;
      XkbMessageAction          msg;
      XkbRedirectKeyAction      redirect;
      XkbDeviceBtnAction        devbtn;
      XkbDeviceValuatorAction   devval;
      unsigned char             type;
} <span class="emphasis"><em>XkbAction</em></span>;
</pre><p>
The <span class="emphasis"><em>
type</em></span>
 field is provided for convenience and is the same as the type field in the
individual structures. The following sections describe the individual
structures for each action in detail.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_XkbAnyAction_Structure"></a>The XkbAnyAction Structure</h3></div></div></div><p>
The <span class="emphasis"><em>
XkbAnyAction</em></span>
 structure is a convenience structure that refers to any of the actions:
</p><pre class="programlisting">
#define      XkbAnyActionDataSize       7
</pre><pre class="programlisting">
typedef struct _XkbAnyAction {
   unsigned char    type;            /* type of action; determines interpretation for data */
   unsigned char    data[XkbAnyActionDataSize];
} <span class="emphasis"><em>XkbAnyAction</em></span>;
</pre><p>
The <span class="emphasis"><em>
data</em></span>
 field represents a structure for an action, and its interpretation depends on
the <span class="emphasis"><em>
type</em></span>
 field. The valid values for the <span class="emphasis"><em>
type</em></span>
 field, and the data structures associated with them are shown in Table 16.1:
</p><div class="table"><a id="idp67495148"></a><p class="title"><strong>Table 16.1. Action Types</strong></p><div class="table-contents"><table summary="Action Types" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Type</th><th align="left">Structure for Data</th><th align="left">XkbAction Union Member</th><th align="left">Section</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_NoAction</em></span></td><td align="left">
<span class="emphasis"><em>XkbSA_NoAction</em></span>
 means the server does not perform an action for the key; this action does not
have an associated data structure.
    </td><td align="left">any</td><td align="left"> </td></tr><tr><td align="left">
<p><span class="emphasis"><em>XkbSA_SetMods</em></span></p>
<p><span class="emphasis"><em>XkbSA_LatchMods</em></span></p>
<p><span class="emphasis"><em>XkbSA_LockMods</em></span></p>
    </td><td align="left"><p><span class="emphasis"><em>XkbModAction</em></span></p></td><td align="left">mods</td><td align="left">16.1.3</td></tr><tr><td align="left">
<p><span class="emphasis"><em>XkbSA_SetGroup</em></span></p>
<p><span class="emphasis"><em>XkbSA_LatchGroup</em></span></p>
<p><span class="emphasis"><em>XkbSA_LockGroup</em></span></p>
    </td><td align="left"><span class="emphasis"><em>XkbGroupAction</em></span></td><td align="left">group</td><td align="left">16.1.4</td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_MovePtr</em></span></td><td align="left"><span class="emphasis"><em>XkbPtrAction</em></span></td><td align="left">ptr</td><td align="left">16.1.5</td></tr><tr><td align="left">
<p><span class="emphasis"><em>XKbSA_PtrBtn</em></span></p>
<p><span class="emphasis"><em>XkbSA_LockPtrBtn</em></span></p>
    </td><td align="left"><span class="emphasis"><em>XkbPtrBtnAction</em></span></td><td align="left">btn</td><td align="left">16.1.6</td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_SetPtrDflt</em></span></td><td align="left"><span class="emphasis"><em>XkbPtrDfltAction</em></span></td><td align="left">dflt</td><td align="left">16.1.7</td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_ISOLock</em></span></td><td align="left"><span class="emphasis"><em>XkbISOAction</em></span></td><td align="left">iso</td><td align="left">16.1.8</td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_SwitchScreen</em></span></td><td align="left"><span class="emphasis"><em>XkbSwitchScreenAction</em></span></td><td align="left">screen</td><td align="left">16.1.9</td></tr><tr><td align="left">
<p><span class="emphasis"><em>XkbSA_SetControls</em></span></p>
<p><span class="emphasis"><em>XkbSA_LockControls</em></span></p>
    </td><td align="left"><span class="emphasis"><em>XkbCtrlsAction</em></span></td><td align="left">ctrls</td><td align="left">16.1.10</td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_ActionMessage</em></span></td><td align="left"><span class="emphasis"><em>XkbMessgeAction</em></span></td><td align="left">msg</td><td align="left">16.1.11</td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_RedirectKey</em></span></td><td align="left"><span class="emphasis"><em>XkbRedirectKeyAction</em></span></td><td align="left">redirect</td><td align="left">16.1.12</td></tr><tr><td align="left">
<p><span class="emphasis"><em>XkbSA_DeviceBtn</em></span></p>
<p><span class="emphasis"><em>XKbSA_LockDeviceBtn</em></span></p>
    </td><td align="left"><span class="emphasis"><em>XkbDeviceBtnAction</em></span></td><td align="left">devbtn</td><td align="left">16.1.13</td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_DeviceValuator</em></span></td><td align="left"><span class="emphasis"><em>XkbDeviceValuatorAction</em></span></td><td align="left">devval</td><td align="left">16.1.14</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Actions_for_Changing_Modifiers_State"></a>Actions for Changing Modifiers’ State</h3></div></div></div><p>
Actions associated with the <span class="emphasis"><em>
XkbModAction</em></span>
 structure change the state of the modifiers when keys are pressed and released
(see Chapter 7 for a discussion of modifiers):
</p><pre class="programlisting">
typedef struct _XkbModAction {
      unsigned char     type;         /* <span class="emphasis"><em> XkbSA_{Set|Latch|Lock}Mods</em></span> */
      unsigned char     flags;        /* with <span class="emphasis"><em> type</em></span> , controls the effect on modifiers */
      unsigned char     mask;         /* same as <span class="emphasis"><em> mask</em></span> field of a modifier description */
      unsigned char     real_mods;    /* same as <span class="emphasis"><em> real_mods</em></span> field of a modifier description */
      unsigned char     vmods1;       /* derived from <span class="emphasis"><em> vmods</em></span> field of a modifier description */
      unsigned char     vmods2;       /* derived from <span class="emphasis"><em> vmods</em></span> field of a modifier description */
} <span class="emphasis"><em>XkbModAction</em></span>;
</pre><p>
In the following description, the term <span class="emphasis"><em>
action modifiers</em></span>
 means the real modifier bits associated with this action. Depending on the
value of <span class="emphasis"><em>
flags</em></span>
 (see Table 16.3), these are designated either in the <span class="emphasis"><em>
mask</em></span>
 field of the <span class="emphasis"><em>
XkbModAction</em></span>
 structure itself or the real modifiers bound to the key for which the action
is being used. In the latter case, this is the client <span class="emphasis"><em>
map</em></span>
-&gt;<span class="emphasis"><em>
modmap</em></span>
[<span class="emphasis"><em>
keycode</em></span>
] field.
</p><p>
The <span class="emphasis"><em>
type</em></span>
 field can have any of the values shown in Table 16.2.
</p><div class="table"><a id="idp67526092"></a><p class="title"><strong>Table 16.2. Modifier Action Types</strong></p><div class="table-contents"><table summary="Modifier Action Types" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Type</th><th align="left">Effect</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_SetMods</em></span></td><td align="left">
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A key press adds any action modifiers to the keyboard’s base modifiers.
    </p></li><li class="listitem"><p>
A key release clears any action modifiers in the keyboard’s base modifiers,
provided no other key affecting the same modifiers is logically down.
    </p></li><li class="listitem"><p>
If no other keys are physically depressed when this key is released, and
<span class="emphasis"><em>
XkbSA_ClearLocks</em></span>
 is set in the <span class="emphasis"><em>
flags</em></span>
 field, the key release unlocks any action modifiers.
    </p></li></ul></div>
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_LatchMods</em></span></td><td align="left">
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Key press and key release events have the same effect as for <span class="emphasis"><em>
XkbSA_SetMods</em></span>
; if no keys are physically depressed when this key is released, key release
events have the following additional effects:
    </p></li><li class="listitem"><p>
Modifiers unlocked due to <span class="emphasis"><em>
XkbSA_ClearLocks</em></span>
 have no further effect.
    </p></li><li class="listitem"><p>
If <span class="emphasis"><em>
XkbSA_LatchToLock</em></span>
 is set in the <span class="emphasis"><em>
flags</em></span>
 field, a key release locks and then unlatches any remaining action modifiers
that are already latched.
    </p></li><li class="listitem"><p>
A key release latches any action modifiers not used by the <span class="emphasis"><em>
XkbSA_ClearLocks</em></span>
 and <span class="emphasis"><em>
XkbSA_LatchToLock</em></span>
 flags.
    </p></li></ul></div>
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_LockMods</em></span></td><td align="left">
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A key press sets the base state of any action modifiers. If <span class="emphasis"><em>
XkbSA_LockNoLock</em></span>
 is set in the <span class="emphasis"><em>
flags</em></span>
 field, a key press also sets the locked state of any action modifiers.
    </p></li><li class="listitem"><p>
A key release clears any action modifiers in the keyboard’s base modifiers,
provided no other key that affects the same modifiers is down. If <span class="emphasis"><em>
XkbSA_LockNoUnlock</em></span>
 is not set in the <span class="emphasis"><em>
flags</em></span>
 field, and any of the action modifiers were locked before the corresponding
key press occurred, a key release unlocks them.
    </p></li></ul></div>
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
The <span class="emphasis"><em>
flags</em></span>
 field is composed of the bitwise inclusive OR of the masks shown in Table
16.3. A general meaning is given in the table, but the exact meaning depends on
the action <span class="emphasis"><em>type</em></span>.
</p><div class="table"><a id="idp67541380"></a><p class="title"><strong>Table 16.3. Modifier Action Flags</strong></p><div class="table-contents"><table summary="Modifier Action Flags" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Flag</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_UseModMapMods</em></span></td><td align="left">
If set, the action modifiers are determined by the modifiers bound by the
modifier mapping of the key. Otherwise, the action modifiers are set to the
modifiers specified by the <span class="emphasis"><em>
mask</em></span>
, <span class="emphasis"><em>
real_mods</em></span>
, <span class="emphasis"><em>
vmod1</em></span>
, and <span class="emphasis"><em>
vmod2</em></span>
 fields.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_ClearLocks</em></span></td><td align="left">
If set and no keys are physically depressed when this key transition
occurs, the server unlocks any action modifiers.
   </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_LatchToLock</em></span></td><td align="left">
If set, and the action type is <span class="emphasis"><em>
XkbSA_LatchMods</em></span>
, the server locks the action modifiers if they are already latched.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_LockNoLock</em></span></td><td align="left">
If set, and the action type is <span class="emphasis"><em>
XkbSA_LockMods</em></span>
, the server only unlocks the action modifiers.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_LockNoUnlock</em></span></td><td align="left">
If set, and the action is <span class="emphasis"><em>
XkbSA_LockMods</em></span>
, the server only locks the action modifiers.
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
If <span class="emphasis"><em>
XkbSA_UseModMapMods</em></span>
 is not set in the <span class="emphasis"><em>
flags</em></span>
 field, the <span class="emphasis"><em>
mask</em></span>
, <span class="emphasis"><em>
real_mods</em></span>
, <span class="emphasis"><em>
vmods1</em></span>
, and <span class="emphasis"><em>
vmods2 </em></span>
fields are used to determine the action modifiers. Otherwise they are ignored
and the modifiers bound to the key (client <span class="emphasis"><em>
map</em></span>
-&gt;<span class="emphasis"><em>
modmap</em></span>
[<span class="emphasis"><em>
keycode</em></span>
]) are used instead.
</p><p>
The <span class="emphasis"><em>
mask</em></span>
, <span class="emphasis"><em>
real_mods</em></span>
, <span class="emphasis"><em>
vmods1</em></span>
, and <span class="emphasis"><em>
vmods2</em></span>
 fields represent the components of an Xkb modifier description (see section
7.2). While the <span class="emphasis"><em>
mask</em></span>
 and <span class="emphasis"><em>
real_mods</em></span>
 fields correspond directly to the <span class="emphasis"><em>
mask</em></span>
 and <span class="emphasis"><em>
real_mods</em></span>
 fields of an Xkb modifier description, the <span class="emphasis"><em>
vmods1</em></span>
 and <span class="emphasis"><em>
vmods2</em></span>
 fields are combined to correspond to the <span class="emphasis"><em>
vmods</em></span>
 field of an Xkb modifier description. Xkb provides the following macros, to
convert between the two formats:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
unsigned short <span class="emphasis"><em>
XkbModActionVMods</em></span>
(<span class="emphasis"><em>
act</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbAction            <span class="emphasis"><em>
act</em></span>
;                  /* action from which to extract virtual mods */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbModActionVMods</em></span>
 returns the <span class="emphasis"><em>
vmods1</em></span>
 and <span class="emphasis"><em>
vmods2</em></span>
 fields of <span class="emphasis"><em>
act</em></span>
 converted to the <span class="emphasis"><em>
vmods</em></span>
 format of an Xkb modifier description.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbSetModActionVMods</em></span>
(<span class="emphasis"><em>
act, vmods</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbAction            <span class="emphasis"><em>
act</em></span>
;                  /* action in which to set vmods */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned short            <span class="emphasis"><em>
vmods</em></span>
;                  /* virtual mods to set */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSetModActionVMods</em></span>
 sets the <span class="emphasis"><em>
vmods1</em></span>
 and <span class="emphasis"><em>
vmods2</em></span>
 fields of <span class="emphasis"><em>
act</em></span>
 using the <span class="emphasis"><em>
vmods</em></span>
 format of an Xkb modifier description.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Despite the fact that the first parameter of these two macros is of
type XkbAction, these macros may be used only with Actions of type <span class="emphasis"><em>
XkbModAction</em></span>
 and <span class="emphasis"><em>
XkbISOAction</em></span>
.</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Actions_for_Changing_Group_State"></a>Actions for Changing Group State</h3></div></div></div><p>
Actions associated with the <span class="emphasis"><em>
XkbGroupAction</em></span>
 structure change the current group state when keys are pressed and released
(see Chapter 5 for a description of groups and keyboard state):
</p><pre class="programlisting">
typedef struct _XkbGroupAction {
      unsigned char   type;       /* <span class="emphasis"><em> XkbSA_{Set|Latch|Lock}Group</em></span> */
      unsigned char   flags;      /* with <span class="emphasis"><em> type</em></span> , controls the effect on groups */
      char            group_XXX;  /* represents a group index or delta */
} <span class="emphasis"><em>XkbGroupAction</em></span>;
</pre><p>
The <span class="emphasis"><em>
type</em></span>
 field can have any of the following values:
</p><div class="table"><a id="idp67571580"></a><p class="title"><strong>Table 16.4. Group Action Types</strong></p><div class="table-contents"><table summary="Group Action Types" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Type</th><th align="left">Effect</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_SetGroup</em></span></td><td align="left">
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If the <span class="emphasis"><em>
XkbSA_GroupAbsolute</em></span>
 bit is set in the <span class="emphasis"><em>
flags</em></span>
 field, key press events change the base keyboard group to the group specified
by the <span class="emphasis"><em>
group_XXX</em></span>
 field. Otherwise, key press events change the base keyboard group by adding
the <span class="emphasis"><em>
group_XXX</em></span>
 field to the base keyboard group. In either case, the resulting effective
keyboard group is brought back into range depending on the value of the
<span class="emphasis"><em>
groups_wrap</em></span>
 field of the controls structure (see section 10.7.1).
    </p></li><li class="listitem"><p>
If a key with an <span class="emphasis"><em>
XkbSA_ISOLock</em></span>
 action (see section 16.1.8) is pressed while this key is down, the key release
of this key has no effect. Otherwise, the key release cancels the effects of
the key press.
    </p></li><li class="listitem"><p>
If the <span class="emphasis"><em>
XkbSA_ClearLocks</em></span>
 bit is set in the flags field, and no keys are physically depressed when this
key is released, the key release also sets the locked keyboard group to
<span class="emphasis"><em>
Group1</em></span>
.
    </p></li></ul></div>
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_LatchGroup</em></span></td><td align="left">
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Key press and key release events have the same effect as for <span class="emphasis"><em>
XkbSA_SetGroup</em></span>
; if no keys are physically depressed when this key is released, key release
events have the following additional effects.
    </p></li><li class="listitem"><p>
If the <span class="emphasis"><em>
XkbSA_LatchToLock</em></span>
 bit is set in the <span class="emphasis"><em>
flags</em></span>
 field and the latched keyboard group index is nonzero, the key release adds
the delta applied by the corresponding key press to the locked keyboard group
and subtracts it from the latched keyboard group. The locked and effective
keyboard group are brought back into range according to the value of the
<span class="emphasis"><em>
groups_wrap</em></span>
 field of the controls structure.
    </p></li><li class="listitem"><p>
Otherwise, the key press adds the key press delta to the latched keyboard group.
    </p></li></ul></div>
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_LockGroup</em></span></td><td align="left">
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If the <span class="emphasis"><em>
XkbSA_GroupAbsolute</em></span>
 is set in the <span class="emphasis"><em>
flags</em></span>
 field, key press events set the locked keyboard group to the group specified
by the <span class="emphasis"><em>
group_XXX</em></span>
 field. Otherwise, key press events add the group specified by the <span class="emphasis"><em>
group_XXX</em></span>
 field to the locked keyboard group. In either case, the resulting locked and
effective keyboard groups are brought back into range depending on the value of
the <span class="emphasis"><em>
groups_wrap</em></span>
 field of the controls structure.
    </p></li><li class="listitem"><p>
A key release has no effect.
    </p></li></ul></div>
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
The <span class="emphasis"><em>
flags</em></span>
 field is composed of the bitwise inclusive OR of the masks shown in Table
16.5. A general meaning is given in the table, but the exact meaning depends on
the action <span class="emphasis"><em>
type</em></span>
.
</p><div class="table"><a id="idp67588068"></a><p class="title"><strong>Table 16.5. Group Action Flags</strong></p><div class="table-contents"><table summary="Group Action Flags" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Flag</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_ClearLocks</em></span></td><td align="left">
If set and no keys are physically depressed when this key transition occurs,
the server sets the locked keyboard group to <span class="emphasis"><em>
Group1</em></span>
 on a key release.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_LatchToLock</em></span></td><td align="left">
If set, and the action type is <span class="emphasis"><em>
SA_LatchGroup</em></span>
, the server locks the action group if it is already latched.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_GroupAbsolute</em></span></td><td align="left">
If set, the <span class="emphasis"><em>
group_XXX</em></span>
 field represents an absolute group number. Otherwise, it represents a group
delta to be added to the current group to determine the new group number.
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
The <span class="emphasis"><em>
group_XXX</em></span>
 field represents a signed character. Xkb provides the following macros to
convert between a signed integer value and a signed character:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
int <span class="emphasis"><em>
XkbSAGroup</em></span>
(<span class="emphasis"><em>
act</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbAction            <span class="emphasis"><em>
act</em></span>
;                  /* action from which to extract group */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSAGroup</em></span>
 returns the <span class="emphasis"><em>
group_XXX</em></span>
 field of <span class="emphasis"><em>
act</em></span>
 converted to a signed int.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbSASetGroup</em></span>
(<span class="emphasis"><em>
act, grp</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbAction            <span class="emphasis"><em>
act</em></span>
;                  /* action from which to set group */
    </td></tr><tr><td class="functionargdecl" align="left">
int            <span class="emphasis"><em>
grp</em></span>
;                  /* group index to set in <span class="emphasis"><em>
group_XXX</em></span>
 */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSASetGroup</em></span>
 sets the <span class="emphasis"><em>
group_XXX</em></span>
 field of <span class="emphasis"><em>
act</em></span>
 from the group index <span class="emphasis"><em>
grp</em></span>
.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Despite the fact that the first parameter of these two macros is of
type XkbAction, these macros may only be used with Actions of type <span class="emphasis"><em>
XkbGroupAction</em></span>
 and <span class="emphasis"><em>
XkbISOAction</em></span>
.</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Actions_for_Moving_the_Pointer"></a>Actions for Moving the Pointer</h3></div></div></div><p>
Actions associated with the <span class="emphasis"><em>
XkbPtrAction</em></span>
 structure move the pointer when keys are pressed and released:
</p><pre class="programlisting">
typedef struct _XkbPtrAction {
      unsigned char      type;      /* <span class="emphasis"><em> XkbSA_MovePtr</em></span> */
      unsigned char      flags;     /* determines type of pointer motion */
      unsigned char      high_XXX;  /* x coordinate, high bits*/
      unsigned char      low_XXX;   /* y coordinate, low bits */
      unsigned char      high_YYY;  /* x coordinate, high bits */
      unsigned char      low_YYY;   /* y coordinate, low bits */
} <span class="emphasis"><em>XkbPtrAction</em></span>;
</pre><p>
If the <span class="emphasis"><em>
MouseKeys</em></span>
 control is not enabled (see section 10.5.1), <span class="emphasis"><em>
KeyPress</em></span>
 and <span class="emphasis"><em>
KeyRelease</em></span>
 events are treated as though the action is <span class="emphasis"><em>
XkbSA_NoAction</em></span>.
</p><p>
If the <span class="emphasis"><em>
MouseKeys</em></span>
 control is enabled, a server action of type <span class="emphasis"><em>
XkbSA_MovePtr</em></span>
 instructs the server to generate core pointer <span class="emphasis"><em>
MotionNotify</em></span>
 events rather than the usual <span class="emphasis"><em>
KeyPress</em></span>
 event, and the corresponding <span class="emphasis"><em>
KeyRelease</em></span>
 event disables any mouse keys timers that were created as a result of handling
the <span class="emphasis"><em>
XkbSA_MovePtr</em></span>
 action.
</p><p>
The <span class="emphasis"><em>
type</em></span>
 field of the <span class="emphasis"><em>
XkbPtrAction</em></span>
 structure is always <span class="emphasis"><em>
XkbSA_MovePtr</em></span>
.
</p><p>
The <span class="emphasis"><em>
flags</em></span>
 field is a bitwise inclusive OR of the masks shown in Table 16.6.
</p><div class="table"><a id="idp67614196"></a><p class="title"><strong>Table 16.6. Pointer Action Types</strong></p><div class="table-contents"><table summary="Pointer Action Types" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Action Type</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_NoAcceleration</em></span></td><td align="left">
If not set, and the <span class="emphasis"><em>
MouseKeysAccel</em></span>
 control is enabled (see section 10.5.2), the <span class="emphasis"><em>
KeyPress</em></span>
 initiates a mouse keys timer for this key; every time the timer expires, the
cursor moves.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_MoveAbsoluteX</em></span></td><td align="left">If set, the X portion of the structure specifies the new pointer X
coordinate. Otherwise, the X portion is added to the current pointer X
coordinate to determine the new pointer X coordinate.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_MoveAbsoluteY</em></span></td><td align="left">
If set, the Y portion of the structure specifies the new
pointer Y coordinate. Otherwise, the Y portion is added
to the current pointer Y coordinate to determine the new pointer Y coordinate.
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
Each of the X and Y coordinantes of the <span class="emphasis"><em>
XkbPtrAction</em></span>
 structure is composed of two signed 16-bit values, that is, the X coordinate
is composed of <span class="emphasis"><em>
high_XXX</em></span>
 and <span class="emphasis"><em>
low_XXX</em></span>
, and similarly for the Y coordinate. Xkb provides the following macros, to
convert between a signed integer and two signed 16-bit values in <span class="emphasis"><em>
XkbPtrAction</em></span>
 structures:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
int <span class="emphasis"><em>
XkbPtrActionX</em></span>
(<span class="emphasis"><em>
act</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbPtrAction            <span class="emphasis"><em>
act</em></span>
;                  /* action from which to extract X */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbPtrActionX</em></span>
 returns the <span class="emphasis"><em>
high_XXX</em></span>
 and <span class="emphasis"><em>
low_XXX</em></span>
 fields of <span class="emphasis"><em>
act</em></span>
 converted to a signed int.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
int <span class="emphasis"><em>
XkbPtrActionY</em></span>
(<span class="emphasis"><em>
act</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbPtrAction            <span class="emphasis"><em>
act</em></span>
;                  /* action from which to extract Y */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbPtrActionY</em></span>
 returns the <span class="emphasis"><em>
high_YYY</em></span>
 and <span class="emphasis"><em>
low_YYY</em></span>
 fields of <span class="emphasis"><em>
act</em></span>
 converted to a signed int.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbSetPtrActionX</em></span>
(<span class="emphasis"><em>
act</em></span>
, <span class="emphasis"><em>
x</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbPtrAction            <span class="emphasis"><em>
act</em></span>
;                  /* action in which to set X */
    </td></tr><tr><td class="functionargdecl" align="left">
int            <span class="emphasis"><em>
x;      </em></span>
            /* new value to set */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSetPtrActionX</em></span>
 sets the <span class="emphasis"><em>
high_XXX</em></span>
 and <span class="emphasis"><em>
low_XXX</em></span>
 fields of <span class="emphasis"><em>
act</em></span>
 from the signed integer value <span class="emphasis"><em>
x</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbSetPtrActionY</em></span>
(<span class="emphasis"><em>
act, y</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbPtrAction            <span class="emphasis"><em>
act</em></span>
;                  /* action in which to set Y */
    </td></tr><tr><td class="functionargdecl" align="left">
int            <span class="emphasis"><em>
y</em></span>
;                  /* new value to set */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSetPtrActionX</em></span>
 sets the <span class="emphasis"><em>
high_YYY</em></span>
 and <span class="emphasis"><em>
low_YYY</em></span>
 fields of <span class="emphasis"><em>
act</em></span>
 from the signed integer value <span class="emphasis"><em>
y</em></span>
.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Actions_for_Simulating_Pointer_Button_Press_and_Release"></a>Actions for Simulating Pointer Button Press and Release</h3></div></div></div><p>
Actions associated with the <span class="emphasis"><em>
XkbPtrBtnAction</em></span>
 structure simulate the press and release of pointer buttons when keys are
pressed and released:
</p><pre class="programlisting">
typedef struct _XkbPtrBtnAction {
      unsigned char   type;     /*<span class="emphasis"><em> XkbSA_PtrBtn, XkbSA_LockPtrBtn</em></span> */
      unsigned char   flags;    /* with <span class="emphasis"><em> type</em></span> , controls the effect on pointer buttons*/
      unsigned char   count;    /* controls number of ButtonPress and ButtonRelease events */
      unsigned char   button;   /* pointer button to simulate */
} <span class="emphasis"><em>XkbPtrBtnAction</em></span>;
</pre><p>
If the <span class="emphasis"><em>
MouseKeys</em></span>
 (see section 10.5.1) control is not enabled, <span class="emphasis"><em>
KeyPress</em></span>
 and <span class="emphasis"><em>
KeyRelease</em></span>
 events are treated as though the action is <span class="emphasis"><em>
XkbSA_NoAction</em></span>
.
</p><p>
The <span class="emphasis"><em>
type</em></span>
 field can have any one of the values shown in Table 16.7.
</p><div class="table"><a id="idp67649420"></a><p class="title"><strong>Table 16.7. Pointer Button Action Types</strong></p><div class="table-contents"><table summary="Pointer Button Action Types" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Type</th><th align="left">Effect</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_PtrBtn</em></span></td><td align="left">
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If<span class="emphasis"><em>
 XkbSA_UseDfltButton</em></span>
 is set in the <span class="emphasis"><em>
flags</em></span>
 field, the event is generated for the pointer button specified by the
<span class="emphasis"><em>
mk_dflt_btn</em></span>
 attribute of the <span class="emphasis"><em>
MouseKeys</em></span>
 control (see section 10.5.1). Otherwise, the event is generated for the button
specified by the <span class="emphasis"><em>
button</em></span>
 field.
    </p></li><li class="listitem"><p>
If the mouse button specified for this action is logically down, the key press
and corresponding key release are ignored and have no effect. Otherwise, a key
press causes one or more core pointer button events instead of the usual
<span class="emphasis"><em>
KeyPress</em></span>
 event. If <span class="emphasis"><em>
count</em></span>
 is <span class="emphasis"><em>
zero</em></span>
, a key press generates a single <span class="emphasis"><em>
ButtonPress</em></span>
 event; if <span class="emphasis"><em>
count</em></span>
 is greater than <span class="emphasis"><em>
zero</em></span>
, a key press generates <span class="emphasis"><em>
count</em></span>
 pairs of <span class="emphasis"><em>
ButtonPress</em></span>
 and <span class="emphasis"><em>
ButtonRelease</em></span>
 events.
    </p></li><li class="listitem"><p>
If <span class="emphasis"><em>
count</em></span>
 is <span class="emphasis"><em>
zero</em></span>
, a key release generates a core pointer <span class="emphasis"><em>
ButtonRelease</em></span>
 that matches the event generated by the corresponding <span class="emphasis"><em>
KeyPress</em></span>
; if <span class="emphasis"><em>
count</em></span>
 is nonzero, a key release does not cause a <span class="emphasis"><em>
ButtonRelease</em></span>
 event. A key release never generates a key <span class="emphasis"><em>
KeyRelease</em></span>
 event.
    </p></li></ul></div>
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_LockPtrBtn</em></span></td><td align="left">
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If the button specified by the <span class="emphasis"><em>
MouseKeys</em></span>
 default button<span class="emphasis"><em>
 </em></span>
or <span class="emphasis"><em>
button</em></span>
 is not locked, a key press causes a <span class="emphasis"><em>
ButtonPress</em></span>
 event instead of a <span class="emphasis"><em>
KeyPress</em></span>
 event and locks the button. If the button is already locked or if <span class="emphasis"><em>
XkbSA_LockNoUnlock</em></span>
 is set in the <span class="emphasis"><em>
flags</em></span>
 field, a key press is ignored and has no effect.
    </p></li><li class="listitem"><p>
If the corresponding key press was ignored, and if <span class="emphasis"><em>
XkbSA_LockNoLock</em></span>
 is not set in the <span class="emphasis"><em>
flags</em></span>
 field, a key release generates a <span class="emphasis"><em>
ButtonRelease</em></span>
 event instead of a <span class="emphasis"><em>
KeyRelease</em></span>
 event and unlocks the specified button. If the corresponding key press locked
a button, the key release is ignored and has no effect.
    </p></li></ul></div>
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
The <span class="emphasis"><em>
flags</em></span>
 field is composed of the bitwise inclusive OR of the masks shown in Table
16.8. A general meaning is given in the table, but the exact meaning depends on
the action <span class="emphasis"><em>
type.</em></span>
:
</p><div class="table"><a id="idp67666404"></a><p class="title"><strong>Table 16.8. Pointer Button Action Flags</strong></p><div class="table-contents"><table summary="Pointer Button Action Flags" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Flag</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_UseDfltButton</em></span></td><td align="left">
If set, the action uses the pointer button specified by the <span class="emphasis"><em>
mk_dflt_btn</em></span>
 attribute of the <span class="emphasis"><em>
MouseKeys</em></span>
 control (see section 10.5.1). Otherwise, the action uses the pointer button
specified by the<span class="emphasis"><em>
 button </em></span>
field.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_LockNoLock</em></span></td><td align="left">
If set, and the action type is <span class="emphasis"><em>
XkbSA_LockPtrBtn</em></span>
, the server only unlocks the pointer button.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_LockNoUnlock</em></span></td><td align="left">
If set, and the action type is <span class="emphasis"><em>
XkbSA_LockPtrBtn</em></span>
, the server only locks the pointer button.
    </td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Actions_for_Changing_the_Pointer_Button_Simulated"></a>Actions for Changing the Pointer Button Simulated</h3></div></div></div><p>
Actions associated with the <span class="emphasis"><em>
XkbPtrDfltAction</em></span>
 structure change the <span class="emphasis"><em>
mk_dflt_btn</em></span>
 attribute of the <span class="emphasis"><em>
MouseKeys</em></span>
 control (see section 10.5.1):
</p><pre class="programlisting">
typedef struct _XkbPtrDfltAction {
      unsigned char   type;      /* <span class="emphasis"><em> XkbSA_SetPtrDflt</em></span> */
      unsigned char   flags;     /* controls the pointer button number */
      unsigned char   affect;    /* <span class="emphasis"><em> XkbSA_AffectDfltBtn</em></span> */
      char            valueXXX;  /* new default button member */
} <span class="emphasis"><em>XkbPtrDfltAction</em></span>;
</pre><p>
If the <span class="emphasis"><em>
MouseKeys</em></span>
 control is not enabled, <span class="emphasis"><em>
KeyPress</em></span>
 and <span class="emphasis"><em>
KeyRelease</em></span>
 events are treated as though the action is <span class="emphasis"><em>
XkbSA_NoAction</em></span>
. Otherwise, this action changes the <span class="emphasis"><em>
mk_dflt_btn</em></span>
 attribute of the <span class="emphasis"><em>
MouseKeys</em></span>
 control.
</p><p>
The <span class="emphasis"><em>
type</em></span>
 field of the <span class="emphasis"><em>
XkbPtrDfltAction</em></span>
 structure should always be <span class="emphasis"><em>
XkbSA_SetPtrDflt</em></span>
.
</p><p>
The <span class="emphasis"><em>
flags</em></span>
 field is composed of the bitwise inclusive OR of the values shown in Table
16.9 (currently there is only one value defined).
</p><div class="table"><a id="idp67679764"></a><p class="title"><strong>Table 16.9. Pointer Default Flags</strong></p><div class="table-contents"><table summary="Pointer Default Flags" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Flag</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_DfltBtnAbsolute</em></span></td><td align="left">
If set, the <span class="emphasis"><em>
value</em></span>
 field represents an absolute pointer button. Otherwise, the <span class="emphasis"><em>
value</em></span>
 field represents the amount to be added to the current default button.
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
The <span class="emphasis"><em>
affect</em></span>
 field specifies what changes as a result of this action. The only valid value
for the <span class="emphasis"><em>
affect</em></span>
 field is <span class="emphasis"><em>XkbSA_AffectDfltBtn</em></span>.
</p><p>
The <span class="emphasis"><em>
valueXXX</em></span>
 field is a signed character that represents the new button value for the
<span class="emphasis"><em>
mk_dflt_btn</em></span>
 attribute of the <span class="emphasis"><em>
MouseKeys</em></span>
 control (see section 10.5.1). If <span class="emphasis"><em>
XkbSA_DfltBtnAbsolute</em></span>
 is set in <span class="emphasis"><em>
flags</em></span>
, <span class="emphasis"><em>
valueXXX</em></span>
 specifies the button to be used; otherwise, <span class="emphasis"><em>
valueXXX</em></span>
 specifies the amount to be added to the current default button. In either
case, illegal button choices are wrapped back around into range. Xkb provides
the following macros, to convert between the integer and signed character
values in <span class="emphasis"><em>
XkbPtrDfltAction</em></span>
 structures:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
int <span class="emphasis"><em>
XkbSAPtrDfltValue</em></span>
(<span class="emphasis"><em>
act</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbAction            <span class="emphasis"><em>
act</em></span>
;                  /* action from which to extract group */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSAPtrDfltValue</em></span>
 returns the <span class="emphasis"><em>
valueXXX</em></span>
 field of <span class="emphasis"><em>
act</em></span>
 converted to a signed int.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbSASetPtrDfltValue</em></span>
(<span class="emphasis"><em>
act, val</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbPtrDfltAction            <span class="emphasis"><em>
act</em></span>
;                  /* action in which to set <span class="emphasis"><em>
valueXXX</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
int            <span class="emphasis"><em>
val</em></span>
;                  /* value to set in <span class="emphasis"><em>
valueXXX</em></span>
 */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSASetPtrDfltValue</em></span>
 sets the <span class="emphasis"><em>
valueXXX</em></span>
 field of <span class="emphasis"><em>
act</em></span>
 from <span class="emphasis"><em>
val</em></span>
.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Actions_for_Locking_Modifiers_and_Group"></a>Actions for Locking Modifiers and Group</h3></div></div></div><p>
Actions associated with the <span class="emphasis"><em>
XkbISOAction</em></span>
 structure lock modifiers and the group according to the ISO9995 specification.
</p><p>
Operated by itself, the <span class="emphasis"><em>
XkbISOAction</em></span>
 is just a caps lock. Operated simultaneously with another modifier key, it
transforms the other key into a locking key. For example, press <span class="emphasis"><em>
ISO_Lock</em></span>
, press and release <span class="emphasis"><em>
Control_L</em></span>
, release <span class="emphasis"><em>
ISO_Lock</em></span>
 ends up locking the <span class="emphasis"><em>
Control</em></span>
 modifier.
</p><p>
The default behavior is to convert:
</p><div class="literallayout"><p><br />
     {Set,Latch}Mods to: LockMods<br />
     {Set,Latch}Group to: LockGroup<br />
     SetPtrBtn to: LockPtrBtn<br />
     SetControls to: LockControls<br />
</p></div><p>
The <span class="emphasis"><em>
affects</em></span>
 field allows you to turn those effects on or off individually. Set <span class="emphasis"><em>
XkbSA_ISONoAffectMods</em></span>
 to disable the first, <span class="emphasis"><em>
XkbSA_ISONoAffectGroup</em></span>
 to disable the second, and so forth.
</p><pre class="programlisting">
typedef struct _XkbISOAction {
      unsigned char   type;        /* <span class="emphasis"><em>XkbSA_ISOLock</em></span> */
      unsigned char   flags;       /* controls changes to group or modifier state */
      unsigned char   mask;        /* same as <span class="emphasis"><em>mask</em></span> field of a modifier description */
      unsigned char   real_mods;   /* same as <span class="emphasis"><em>real_mods</em></span> field of a modifier description */
      char            group_XXX;   /* group index or delta group */
      unsigned char   affect;      /* specifies whether to affect mods, group, ptrbtn, or controls*/
      unsigned char   vmods1;      /* derived from <span class="emphasis"><em>vmods</em></span> field of a modifier description */
      unsigned char   vmods2;      /* derived from <span class="emphasis"><em>vmods</em></span> field of a modifier description */
} <span class="emphasis"><em>XkbISOAction</em></span>;
</pre><p>
The <span class="emphasis"><em>
type</em></span>
 field of the <span class="emphasis"><em>
XkbISOAction</em></span>
 structure should always be <span class="emphasis"><em>
XkbSA_ISOLock</em></span>
.
</p><p>
The interpretation of the <span class="emphasis"><em>
flags</em></span>
 field depends on whether the <span class="emphasis"><em>
XkbSA_ISODfltIsGroup</em></span>
 is set in the <span class="emphasis"><em>
flags</em></span>
 field or not.
</p><p>
If the <span class="emphasis"><em>
XkbSA_ISODfltIsGroup</em></span>
 is set in the <span class="emphasis"><em>
flags</em></span>
 field, the action is used to change the group state. The remaining valid bits
of the <span class="emphasis"><em>
flags</em></span>
 field are composed of a bitwise inclusive OR using the masks shown in Table
16.10.
</p><div class="table"><a id="idp67709020"></a><p class="title"><strong>Table 16.10. ISO Action Flags when XkbSA_ISODfltIsGroup is Set</strong></p><div class="table-contents"><table summary="ISO Action Flags when XkbSA_ISODfltIsGroup is Set" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Flag</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_ISODfltIsGroup</em></span></td><td align="left">
      <p>
If set, the action is used to change the base group state. Must be set for the
remaining bits in this table to carry their interpretations.
      </p>
      <p>
A key press sets the base group as specified by the <span class="emphasis"><em>
group_XXX</em></span>
 field and the <span class="emphasis"><em>
XkbSA_GroupAbsolute</em></span>
 bit of the <span class="emphasis"><em>
flags</em></span>
 field (see section Note). If no other actions are transformed by the <span class="emphasis"><em>
XkbISO_Lock</em></span>
 action, a key release locks the group. Otherwise, a key release clears group
set by the key press.
      </p>
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_GroupAbsolute</em></span></td><td align="left">
If set, the <span class="emphasis"><em>
group_XXX</em></span>
 field represents an absolute group number. Otherwise, it represents a group
delta to be added to the current group to determine the new group number.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_ISONoAffectMods</em></span></td><td align="left">
If not set, any <span class="emphasis"><em>
XkbSA_SetMods</em></span>
 or <span class="emphasis"><em>
XkbSA_LatchMods</em></span>
 actions that occur simultaneously with the <span class="emphasis"><em>
XkbSA_ISOLock</em></span>
 action are treated as <span class="emphasis"><em>
XkbSA_LockMod</em></span>
 actions instead.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_ISONoAffectGroup</em></span></td><td align="left">
If not set, any <span class="emphasis"><em>
XkbSA_SetGroup</em></span>
 or <span class="emphasis"><em>
XkbSA_LatchGroup</em></span>
 actions that occur simultaneously with the <span class="emphasis"><em>
XkbSA_ISOLock</em></span>
 action are treated as <span class="emphasis"><em>
XkbSA_LockGroup</em></span>
 actions instead.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_ISONoAffectPtr</em></span></td><td align="left">
If not set, any <span class="emphasis"><em>
XkbSA_PtrBtn</em></span>
 actions that occur simultaneously with the <span class="emphasis"><em>
XkbSA_ISOLock</em></span>
 action are treated as <span class="emphasis"><em>
XkbSA_LockPtrBtn</em></span>
 actions instead.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_ISONoAffectCtrls</em></span></td><td align="left">
If not set, any <span class="emphasis"><em>
XkbSA_SetControls</em></span>
 actions that occur simultaneously with the <span class="emphasis"><em>
XkbSA_ISOLock</em></span>
 action are treated as <span class="emphasis"><em>
XkbSA_LockControls</em></span>
 actions instead.
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
If the <span class="emphasis"><em>
XkbSA_ISODfltIsGroup</em></span>
 is not set in the <span class="emphasis"><em>
flags</em></span>
 field, the action is used to change the modifier state and the remaining valid
bits of the <span class="emphasis"><em>
flags</em></span>
 field are composed of a bitwise inclusive OR using the masks shown in Table
16.11.
</p><div class="table"><a id="idp67723956"></a><p class="title"><strong>Table 16.11. ISO Action Flags when XkbSA_ISODfltIsGroup is Not Set</strong></p><div class="table-contents"><table summary="ISO Action Flags when XkbSA_ISODfltIsGroup is Not Set" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Flag</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_ISODfltIsGroup</em></span> </td><td align="left">
      <p>
If not set, action is used to change the base modifier state. Must not be set
for the remaining bits in this table to carry their interpretations.
      </p>
      <p>
A key press sets the action modifiers in the keyboard’s base modifiers using
the <span class="emphasis"><em>
mask</em></span>
, <span class="emphasis"><em>
real_mods</em></span>
, <span class="emphasis"><em>
vmods1</em></span>
, and <span class="emphasis"><em>
vmods2 </em></span>
fields (see section 16.1.3). If no other actions are transformed by the
<span class="emphasis"><em>
XkbISO_Lock</em></span>
 action, a key release locks the action modifiers. Otherwise, a key release
clears the base modifiers set by the key press.
      </p>
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_UseModMapMods</em></span></td><td align="left">
If set, the action modifiers are determined by the modifiers bound by the
modifier mapping of the key. Otherwise, the action modifiers are set to the
modifiers specified by the <span class="emphasis"><em>
mask</em></span>
, <span class="emphasis"><em>
real_mods</em></span>
, <span class="emphasis"><em>
vmod1</em></span>
, and <span class="emphasis"><em>
vmod2</em></span>
 fields.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_LockNoLock</em></span></td><td align="left">If set, the server only unlocks the action modifiers.</td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_LockNoUnlock</em></span></td><td align="left">If set, the server only locks the action modifiers. </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_ISONoAffectMods</em></span></td><td align="left">
If not set, any <span class="emphasis"><em>
XkbSA_SetMods</em></span>
 or <span class="emphasis"><em>
XkbSA_LatchMods</em></span>
 actions that occur simultaneously with the <span class="emphasis"><em>
XkbSA_ISOLock</em></span>
 action are treated as <span class="emphasis"><em>
XkbSA_LockMod</em></span>
 actions instead.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_ISONoAffectGroup</em></span></td><td align="left">
If not set, any <span class="emphasis"><em>
XkbSA_SetGroup</em></span>
 or <span class="emphasis"><em>
XkbSA_LatchGroup</em></span>
 actions that occur simultaneously with the <span class="emphasis"><em>
XkbSA_ISOLock</em></span>
 action are treated as <span class="emphasis"><em>
XkbSA_LockGroup</em></span>
 actions instead.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_ISONoAffectPtr</em></span></td><td align="left">
If not set, any <span class="emphasis"><em>
XkbSA_PtrBtn</em></span>
 actions that occur simultaneously with the <span class="emphasis"><em>
XkbSA_ISOLock</em></span>
 action are treated as <span class="emphasis"><em>
XkbSA_LockPtrBtn</em></span>
 actions instead.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_ISONoAffectCtrls</em></span></td><td align="left">
If not set, any <span class="emphasis"><em>
XkbSA_SetControls</em></span>
 actions that occur simultaneously with the <span class="emphasis"><em>
XkbSA_ISOLock</em></span>
 action are treated as <span class="emphasis"><em>
XkbSA_LockControls</em></span>
 actions instead.
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
The <span class="emphasis"><em>
group_XXX</em></span>
 field represents a signed character. Xkb provides macros to convert between a
signed integer value and a signed character as shown in section Note.
</p><p>
The <span class="emphasis"><em>
mask</em></span>
, <span class="emphasis"><em>
real_mods</em></span>
, <span class="emphasis"><em>
vmods1</em></span>
, and <span class="emphasis"><em>
vmods2</em></span>
 fields represent the components of an Xkb modifier description (see section
7.2). While the <span class="emphasis"><em>
mask</em></span>
 and <span class="emphasis"><em>
real_mods</em></span>
 fields correspond directly to the <span class="emphasis"><em>
mask</em></span>
 and <span class="emphasis"><em>
real_mods</em></span>
 fields of an Xkb modifier description, the <span class="emphasis"><em>
vmods1</em></span>
 and <span class="emphasis"><em>
vmods2</em></span>
 fields are combined to correspond to the <span class="emphasis"><em>
vmods</em></span>
 field of an Xkb modifier description. Xkb provides macros to convert between
the two formats as shown in section 16.1.3.
</p><p>
The <span class="emphasis"><em>
affect</em></span>
 field is composed of a bitwise inclusive OR using the masks shown in Table
16.11.
</p><div class="table"><a id="idp67744524"></a><p class="title"><strong>Table 16.12. ISO Action Affect Field Values</strong></p><div class="table-contents"><table summary="ISO Action Affect Field Values" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Affect</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_ISODNoAffectMods</em></span></td><td align="left">
If <span class="emphasis"><em>
XkbSA_ISONoAffectMods</em></span>
 is not set, any <span class="emphasis"><em>
SA_SetMods</em></span>
 or <span class="emphasis"><em>
SA_LatchMods</em></span>
 actions occurring simultaneously with the <span class="emphasis"><em>
XkbISOAction</em></span>
 are treated as <span class="emphasis"><em>
SA_LockMods</em></span>
 instead.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_ISONoAffectGroup</em></span></td><td align="left">
If <span class="emphasis"><em>
XkbSA_ISONoAffectGroup</em></span>
 is not set, any <span class="emphasis"><em>
SA_SetGroup</em></span>
 or <span class="emphasis"><em>
SA_LatchGroup</em></span>
 actions occurring simultaneously with the <span class="emphasis"><em>
XkbISOAction</em></span>
 are treated as <span class="emphasis"><em>
SA_LockGroup</em></span>
 instead.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_ISONoAffectPtr</em></span></td><td align="left">
If <span class="emphasis"><em>
XkbSA_ISONoAffectPtr</em></span>
 is not set, any <span class="emphasis"><em>
SA_PtrBtn</em></span>
 actions occurring simultaneously with the <span class="emphasis"><em>
XkbISOAction</em></span>
 are treated as <span class="emphasis"><em>
SA_LockPtrBtn</em></span>
 instead.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_ISONoAffectCtrls</em></span></td><td align="left">
If <span class="emphasis"><em>
XkbSA_ISONoAffectCtrls</em></span>
 is not set, any <span class="emphasis"><em>
SA_SetControls</em></span>
 actions occurring simultaneously with the <span class="emphasis"><em>
XkbISOAction</em></span>
 are treated as <span class="emphasis"><em>
SA_LockControls</em></span>
 instead.
    </td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Actions_for_Changing_the_Active_Screen"></a>Actions for Changing the Active Screen</h3></div></div></div><p>
Actions associated with the <span class="emphasis"><em>
XkbSwitchScreen</em></span>
 action structure change the active screen on a multiscreen display:
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This action is optional. Servers are free to ignore the action or
any of its flags if they do not support the requested behavior. If the action
is ignored, it behaves like <span class="emphasis"><em>
XkbSA_NoAction</em></span>
. Otherwise, key press and key release events do not generate an event.
</p></div><pre class="programlisting">
typedef struct _XkbSwitchScreenAction {
      unsigned char   type;        /* <span class="emphasis"><em> XkbSA_SwitchScreen</em></span> */
      unsigned char   flags;       /* controls screen switching */
      char            screenXXX;   /* screen number or delta */
} <span class="emphasis"><em>XkbSwitchScreenAction</em></span>;
</pre><p>
The <span class="emphasis"><em>
type</em></span>
 field of the <span class="emphasis"><em>
XkbSwitchScreenAction</em></span>
 structure should always be <span class="emphasis"><em>
XkbSA_SwitchScreen</em></span>.
</p><p>
The <span class="emphasis"><em>
flags</em></span>
 field is composed of the bitwise inclusive OR of the masks shown in Table
16.13.
</p><div class="table"><a id="idp67759996"></a><p class="title"><strong>Table 16.13. Switch Screen Action Flags</strong></p><div class="table-contents"><table summary="Switch Screen Action Flags" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Flag</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_SwitchAbsolute</em></span></td><td align="left">
If set, the <span class="emphasis"><em>
screenXXX</em></span>
 field represents the index of the new screen. Otherwise, it represents an
offset from the current screen to the new screen.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_SwitchApplication</em></span></td><td align="left">
If not set, the action should switch to another screen on the same
server. Otherwise, it should switch to another X server or application that
shares the same physical display.
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
The <span class="emphasis"><em>
screenXXX</em></span>
 field is a signed character value that represents either the relative or
absolute screen index, depending on the state of the <span class="emphasis"><em>
XkbSA_SwitchAbsolute</em></span>
 bit in the <span class="emphasis"><em>
flags</em></span>
 field. Xkb provides the following macros to convert between the integer and
signed character value for screen numbers in <span class="emphasis"><em>
XkbSwitchScreenAction</em></span>
 structures:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
int <span class="emphasis"><em>
XkbSAScreen</em></span>
(<span class="emphasis"><em>
act</em></span>
)                        /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbSwitchScreenAction                  <span class="emphasis"><em>
act</em></span>
;      /* action from which to extract screen */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSAScreen</em></span>
 returns the <span class="emphasis"><em>
screenXXX</em></span>
 field of <span class="emphasis"><em>
act</em></span>
 converted to a signed int.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbSASetScreen</em></span>
(<span class="emphasis"><em>
act, s</em></span>
)                        /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbSwitchScreenAction                  <span class="emphasis"><em>
act</em></span>
;      /* action in which to set <span class="emphasis"><em>
screenXXX</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
int                  <span class="emphasis"><em>
s</em></span>
;      /* value to set in <span class="emphasis"><em>
screenXXX</em></span>
 */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSASetScreen</em></span>
 sets the <span class="emphasis"><em>
screenXXX</em></span>
 field of <span class="emphasis"><em>
act</em></span>
 from <span class="emphasis"><em>
s</em></span>
.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Actions_for_Changing_Boolean_Controls_State"></a>Actions for Changing Boolean Controls State</h3></div></div></div><p>
Actions associated with the <span class="emphasis"><em>
XkbCtrlsAction</em></span>
 structure change the state of the boolean controls (see section 10.1):
</p><pre class="programlisting">
typedef struct _XkbCtrlsAction {
      unsigned char     type;        /* <span class="emphasis"><em> XkbSA_SetControls,
                                        XkbSA_LockControls</em></span> */
      unsigned char     flags;       /* with <span class="emphasis"><em> type</em></span>,
                                        controls enabling and disabling of controls */
      unsigned char     ctrls3;      /* <span class="emphasis"><em>ctrls0</em></span> through
                                        <span class="emphasis"><em> ctrls3</em></span> represent the boolean controls */
      unsigned char     ctrls2;      /* <span class="emphasis"><em>ctrls0</em></span> through
                                        <span class="emphasis"><em> ctrls3</em></span> represent the boolean controls */
      unsigned char     ctrls1;      /* <span class="emphasis"><em>ctrls0</em></span> through
                                        <span class="emphasis"><em> ctrls3</em></span> represent the boolean controls */
      unsigned char     ctrls0;      /* <span class="emphasis"><em>ctrls0</em></span> through
                                        <span class="emphasis"><em> ctrls3</em></span> represent the boolean controls */
} <span class="emphasis"><em>XkbCtrlsAction</em></span>;
</pre><p>
The <span class="emphasis"><em>
type</em></span>
 field can have any one of the values shown in Table 16.14.
</p><div class="table"><a id="idp67783372"></a><p class="title"><strong>Table 16.14. Controls Action Types</strong></p><div class="table-contents"><table summary="Controls Action Types" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Type</th><th align="left">Effect</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_SetControls</em></span></td><td align="left">
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A key press enables any boolean controls specified in the <span class="emphasis"><em>
ctrls</em></span>
 fields that were not already enabled at the time of the key press.
    </p></li><li class="listitem"><p>
A key release disables any controls enabled by the key press.
    </p></li><li class="listitem"><p>
This action can cause <span class="emphasis"><em>
XkbControlsNotify</em></span>
 events (see section 10.1).
    </p></li></ul></div>
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_LockControls</em></span></td><td align="left">
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If the <span class="emphasis"><em>
XkbSA_LockNoLock</em></span>
 bit is not set in the <span class="emphasis"><em>
flags</em></span>
 field, a key press enables any controls specified in the <span class="emphasis"><em>
ctrls</em></span>
 fields that were not already enabled at the time of the key press.
    </p></li><li class="listitem"><p>
If the <span class="emphasis"><em>
XkbSA_LockNoUnlock</em></span>
 bit is not set in the <span class="emphasis"><em>
flags</em></span>
 field, a key release disables any controls specified in the <span class="emphasis"><em>
ctrls</em></span>
 fields that were not already disabled at the time of the key press.
    </p></li><li class="listitem"><p>
This action can cause <span class="emphasis"><em>
XkbControlsNotify</em></span>
 events (see section 10.1).
    </p></li></ul></div>
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
The <span class="emphasis"><em>
flags</em></span>
 field is composed of the bitwise inclusive OR of the masks shown in Table
16.15.
</p><div class="table"><a id="idp67794708"></a><p class="title"><strong>Table 16.15. Control Action Flags</strong></p><div class="table-contents"><table summary="Control Action Flags" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Flag</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_LockNoLock</em></span></td><td align="left">
If set, and the action type is <span class="emphasis"><em>
XkbSA_LockControls</em></span>
, the server only disables controls.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_LockNoUnlock</em></span></td><td align="left">
If set, and the action type is <span class="emphasis"><em>
XkbSA_LockControls</em></span>
, the server only enables controls.
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
The <span class="emphasis"><em>
XkbSA_SetControls</em></span>
 action implements a key that enables a boolean control when pressed and
disables it when released. The <span class="emphasis"><em>
XkbSA_LockControls</em></span>
 action is used to implement a key that toggles the state of a boolean control
each time it is pressed and released. The <span class="emphasis"><em>
XkbSA_LockNoLock</em></span>
 and <span class="emphasis"><em>
XkbSA_LockNoUnlock</em></span>
 flags allow modifying the toggling behavior to only unlock or only lock the
boolean control.
</p><p>
The <span class="emphasis"><em>
ctrls0</em></span>
, <span class="emphasis"><em>
ctrls1</em></span>
, <span class="emphasis"><em>
ctrls2</em></span>
, and <span class="emphasis"><em>
ctrls3</em></span>
 fields represent the boolean controls in the <span class="emphasis"><em>
enabled_ctrls</em></span>
 field of the controls structure (see section 10.1). Xkb provides the following
macros, to convert between the two formats:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
unsigned int <span class="emphasis"><em>
XkbActionCtrls</em></span>
(<span class="emphasis"><em>
act</em></span>
)                        /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbCtrlsAction            <span class="emphasis"><em>
act</em></span>
;            /* action from which to extract controls */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbActionCtrls</em></span>
 returns the <span class="emphasis"><em>
ctrls</em></span>
 fields of <span class="emphasis"><em>
act</em></span>
 converted to an unsigned int.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbSAActionSetCtrls</em></span>
(<span class="emphasis"><em>
act, ctrls</em></span>
)                        /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbCtrlsAction                  <span class="emphasis"><em>
act</em></span>
;      /* action in which to set ctrls0-ctrls3 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int                  <span class="emphasis"><em>
ctrls</em></span>
;      /* value to set in ctrls0-ctrls3 */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSAActionSetCtrls</em></span>
 sets the <span class="emphasis"><em>
ctrls0</em></span>
 through <span class="emphasis"><em>
ctrls3</em></span>
 fields of <span class="emphasis"><em>
act</em></span>
 from <span class="emphasis"><em>
ctrls</em></span>
.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Actions_for_Generating_Messages"></a>Actions for Generating Messages</h3></div></div></div><p>
Actions associated with the <span class="emphasis"><em>
XkbMessageAction</em></span>
 structure generate <span class="emphasis"><em>
XkbActionMessage</em></span>
 events:
</p><pre class="programlisting">
#define            XkbActionMessageLength                  6
</pre><pre class="programlisting">
typedef struct _XkbMessageAction {
      unsigned char   type;             /* <span class="emphasis"><em> XkbSA_ActionMessage</em></span> */
      unsigned char   flags;            /* controls event generation via key presses and releases */
      unsigned char   message[XkbActionMessageLength];    /* message */
} <span class="emphasis"><em>XkbMessageAction</em></span>;
</pre><p>
The <span class="emphasis"><em>
type</em></span>
 field of the <span class="emphasis"><em>
XkbMessageAction</em></span>
 structure should always be <span class="emphasis"><em>
XkbSA_ActionMessage</em></span>
.
</p><p>
The <span class="emphasis"><em>
flags</em></span>
 field is composed of the bitwise inclusive OR of the masks shown in Table
16.16.
</p><div class="table"><a id="idp67818572"></a><p class="title"><strong>Table 16.16. Message Action Flags</strong></p><div class="table-contents"><table summary="Message Action Flags" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Flag</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_MessageOnPress</em></span></td><td align="left">
If set, key press events generate an <span class="emphasis"><em>
XkbActionMessage</em></span>
 event that reports the keycode, event type, and contents of the <span class="emphasis"><em>
message</em></span>
 field.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_MessageOnRelease</em></span></td><td align="left">
If set, key release events generate an <span class="emphasis"><em>
XkbActionMessage</em></span>
 event that reports the keycode, event type, and contents of the <span class="emphasis"><em>
message</em></span>
 field.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_MessageGenKeyEvent</em></span></td><td align="left">
If set, key press and key release events generate <span class="emphasis"><em>
KeyPress</em></span>
 and <span class="emphasis"><em>
KeyRelease</em></span>
 events, regardless of whether they generate <span class="emphasis"><em>
XkbActionMessage</em></span>
 events.
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
The <span class="emphasis"><em>
message</em></span>
 field is an array of <span class="emphasis"><em>
XkbActionMessageLength</em></span>
 unsigned characters and may be set to anything the keymap designer wishes.
</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Detecting_Key_Action_Messages"></a>Detecting Key Action Messages</h4></div></div></div><p>
To receive <span class="emphasis"><em>
XkbActionMessage</em></span>
 events by calling either <span class="emphasis"><em>
XkbSelectEvents</em></span>
 or <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
 (see section 4.3).
</p><p>
To receive <span class="emphasis"><em>
XkbActionMessage</em></span>
 events under all possible conditions, use <span class="emphasis"><em>
XkbSelectEvents</em></span>
 and pass <span class="emphasis"><em>
XkbActionMessageMask</em></span>
 in both <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits</em></span>
.
</p><p>
The <span class="emphasis"><em>
XkbActionMessage</em></span>
 event has no event details. However, you can call <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
 using <span class="emphasis"><em>
XkbActionMessage</em></span>
 as the <span class="emphasis"><em>
event_type</em></span>
 and specifying <span class="emphasis"><em>
XkbAllActionMessageMask</em></span>
 in <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits.</em></span>
 This has the same effect as a call to <span class="emphasis"><em>
XkbSelectEvents</em></span>.
</p><p>
The structure for the <span class="emphasis"><em>
XkbActionMessage</em></span>
 event is defined as follows:
</p><pre class="programlisting">
typedef struct _XkbActionMessage {
      int            type;            /* Xkb extension base event code */
      unsigned long  serial;          /* X server serial number for event */
      Bool           send_event;      /* <span class="emphasis"><em>True</em></span> =&gt; synthetically generated */
      Display *      display;         /* server connection where event generated */
      Time           time;            /* server time when event generated */
      int            xkb_type;        /* <span class="emphasis"><em>XkbActionMessage</em></span> */
      int            device;          /* Xkb device ID, will not be <span class="emphasis"><em> XkbUseCoreKbd</em></span> */
      KeyCode        keycode;         /* keycode of key triggering event */
      Bool           press;           /* <span class="emphasis"><em>True</em></span> =&gt; key press,
                                         <span class="emphasis"><em>False</em></span> =&gt; release */
      Bool           key_event_follows; /* <span class="emphasis"><em>True</em></span> =&gt; KeyPress/KeyRelease follows */
      char           message[XkbActionMessageLength+1];                       /* message text */
} <span class="emphasis"><em>XkbActionMessageEvent</em></span>;
</pre><p>
The <span class="emphasis"><em>
keycode</em></span>
 is the keycode of the key that was pressed or released. The <span class="emphasis"><em>
press</em></span>
 field specifies whether the event was the result of a key press or key
release.
</p><p>
The <span class="emphasis"><em>
key_event_follows</em></span>
 specifies whether a <span class="emphasis"><em>
KeyPress</em></span>
 (if <span class="emphasis"><em>
press</em></span>
 is <span class="emphasis"><em>
True</em></span>
) or <span class="emphasis"><em>
KeyRelease</em></span>
 (if <span class="emphasis"><em>
press</em></span>
 is <span class="emphasis"><em>
False</em></span>
) event is also sent to the client. As with all other Xkb events, <span class="emphasis"><em>
XkbActionMessageEvent</em></span>
s are delivered to all clients requesting them, regardless of the current
keyboard focus. However, the <span class="emphasis"><em>
KeyPress</em></span>
 or <span class="emphasis"><em>
KeyRelease</em></span>
 event that conditionally follows an <span class="emphasis"><em>
XkbActionMessageEvent</em></span>
 is sent only to the client selected by the current keyboard focus. <span class="emphasis"><em>
key_event_follows</em></span>
 is <span class="emphasis"><em>
True</em></span>
 only for the client that is actually sent the following <span class="emphasis"><em>
KeyPress</em></span>
 or <span class="emphasis"><em>
KeyRelease</em></span>
 event.
</p><p>
The <span class="emphasis"><em>
message</em></span>
 field is set to the message specified in the action and is guaranteed to be
<span class="emphasis"><em>
NULL</em></span>
-terminated; the Xkb extension forces a <span class="emphasis"><em>
NULL</em></span>
 into <span class="emphasis"><em>
message</em></span>
[<span class="emphasis"><em>
XkbActionMessageLength</em></span>
].
</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Actions_for_Generating_a_Different_Keycode"></a>Actions for Generating a Different Keycode</h3></div></div></div><p>
Actions associated with the <span class="emphasis"><em>
XkbRedirectKeyAction</em></span>
 structure generate <span class="emphasis"><em>
KeyPress</em></span>
 and <span class="emphasis"><em>
KeyRelease</em></span>
 events containing a keycode different from the key that was pressed or
released:
</p><pre class="programlisting">
typedef struct      _XkbRedirectKeyAction {
      unsigned char      type;          /* <span class="emphasis"><em> XkbSA_RedirectKey</em></span> */
      unsigned char      new_key;       /* keycode to be put in event */
      unsigned char      mods_mask;     /* mask of real mods to be reset */
      unsigned char      mods;          /* mask of real mods to take values from */
      unsigned char      vmods_mask0;   /* first half of mask of virtual mods to be reset */
      unsigned char      vmods_mask1;   /* other half of mask of virtual mods to be reset */
      unsigned char      vmods0;        /* first half of mask of virtual mods to take values from */
      unsigned char      vmods1;        /* other half of mask of virtual mods to take values from */
} <span class="emphasis"><em>XkbRedirectKeyAction</em></span>;
</pre><p>
The <span class="emphasis"><em>
type</em></span>
 field for the <span class="emphasis"><em>
XkbRedirectKeyAction</em></span>
 structure should always be <span class="emphasis"><em>
XkbSA_RedirectKey</em></span>
.
</p><p>
Key presses cause a <span class="emphasis"><em>
KeyPress</em></span>
 event for the key specified by the <span class="emphasis"><em>
new_key</em></span>
 field instead of the actual key. The state reported in this event reports the
current effective modifiers changed as follows: any real modifiers selected by
the <span class="emphasis"><em>
mods_mask</em></span>
 field are set to corresponding values from the <span class="emphasis"><em>
mods</em></span>
 field. Any real modifiers bound to the virtual modifiers specified by the
<span class="emphasis"><em>
vmods_mask0</em></span>
 and <span class="emphasis"><em>
vmods_mask1</em></span>
 fields are either set or cleared, depending on the corresponding values in the
<span class="emphasis"><em>
vmods0</em></span>
 and <span class="emphasis"><em>
vmods1</em></span>
 fields. If the real and virtual modifier definitions specify conflicting
values for a single modifier, the real modifier definition has priority.
</p><p>
Key releases cause a <span class="emphasis"><em>
KeyRelease</em></span>
 event for the key specified by the <span class="emphasis"><em>
new_key</em></span>
 field instead of the actual key. The state for this event consists of the
effective keyboard modifiers at the time of the release, changed as described
previously.
</p><p>
The <span class="emphasis"><em>
XkbSA_RedirectKey</em></span>
 action normally redirects to another key on the same device as the key that
caused the event, unless that device does not belong to the input extension
<span class="emphasis"><em>
KeyClass</em></span>
, in which case this action causes an event on the core keyboard device. (The
input extension categorizes devices by breaking them into classes. Keyboards,
and other input devices with keys, are classified as KeyClass devices by the
input extension.)
</p><p>
The <span class="emphasis"><em>
vmods_mask0</em></span>
 and <span class="emphasis"><em>
vmods_mask1</em></span>
 fields actually represent one <span class="emphasis"><em>
vmods_mask</em></span>
 value, as described in Chapter 7. Xkb provides the following macros, to
convert between the two formats:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
unsigned int <span class="emphasis"><em>
XkbSARedirectVModsMask</em></span>
(<span class="emphasis"><em>
act</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbRedirectKeyAction                  <span class="emphasis"><em>
act</em></span>
;            /* action from which to extract vmods */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSARedirectVModsMask</em></span>
 returns the <span class="emphasis"><em>
vmods_mask0</em></span>
 and <span class="emphasis"><em>
vmods_mask1</em></span>
 fields of <span class="emphasis"><em>
act</em></span>
 converted to an unsigned int.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbSARedirectSetVModsMask</em></span>
(<span class="emphasis"><em>
act, vm</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbRedirectKeyAction                  <span class="emphasis"><em>
act</em></span>
;            /* action in which to set vmods */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int                  <span class="emphasis"><em>
vm</em></span>
;            /* new value for virtual modifier mask */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSARedirectSetVModsMask</em></span>
 sets the <span class="emphasis"><em>
vmods_mask0</em></span>
 and <span class="emphasis"><em>
vmods_mask1</em></span>
 fields of <span class="emphasis"><em>
act</em></span>
 from <span class="emphasis"><em>
vm</em></span>
.
</p><p>
Similarly, the <span class="emphasis"><em>
vmods0</em></span>
 and <span class="emphasis"><em>
vmods1</em></span>
 fields actually represent one <span class="emphasis"><em>
vmods </em></span>
value, as described in Chapter 7. To convert between the two formats, Xkb
provides the following convenience macros:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
unsigned int <span class="emphasis"><em>
XkbSARedirectVMods</em></span>
(<span class="emphasis"><em>
act</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbRedirectKeyAction                  <span class="emphasis"><em>
act</em></span>
;            /* action from which to extract vmods */
    </td></tr></tbody></table></div><div class="literallayout"><p><br />
     <span class="emphasis"><em>XkbSARedirectVModsMask</em></span> returns the <span class="emphasis"><em>vmods0</em></span><br />
     and <span class="emphasis"><em>vmods1</em></span> fields of <span class="emphasis"><em>act</em></span><br />
     converted to an unsigned int.<br />
</p></div><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbSARedirectSetVMods</em></span>
(<span class="emphasis"><em>
act, vm</em></span>
)                              /* macro */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbRedirectKeyAction                  <span class="emphasis"><em>
act</em></span>
;            /* action in which to set vmods */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int                  <span class="emphasis"><em>
v</em></span>
;            /* new value for virtual modifiers */
    </td></tr></tbody></table></div><div class="literallayout"><p><br />
     <span class="emphasis"><em> XkbSARedirectSetVModsMask</em></span> sets the <span class="emphasis"><em>vmods0</em></span><br />
     and <span class="emphasis"><em>vmods1</em></span> of <span class="emphasis"><em>act</em></span> from <span class="emphasis"><em>v</em></span>.<br />
</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Actions_for_Generating_DeviceButtonPress_and_DeviceButtonRelease"></a>Actions for Generating DeviceButtonPress and DeviceButtonRelease</h3></div></div></div><p>
Actions associated with <span class="emphasis"><em>
XkbDeviceBtnAction</em></span>
 structures generate <span class="emphasis"><em>
DeviceButtonPress</em></span>
 and <span class="emphasis"><em>
DeviceButtonRelease</em></span>
 events instead of normal <span class="emphasis"><em>
KeyPress</em></span>
 and <span class="emphasis"><em>
KeyRelease</em></span>
 events:
</p><pre class="programlisting">
typedef struct _XkbDeviceBtnAction {
      unsigned char    type;      /* <span class="emphasis"><em> XkbSA_DeviceBtn, XkbSA_LockDeviceBtn</em></span> */
      unsigned char    flags;     /* with <span class="emphasis"><em> type</em></span> , specifies locking or unlocking */
      unsigned char    count;     /* controls number of DeviceButtonPress and Release events */
      unsigned char    button;    /* index of button on <span class="emphasis"><em> device</em></span> */
      unsigned char    device;    /* device ID of an X input extension device */
} <span class="emphasis"><em>XkbDeviceBtnAction</em></span>;
</pre><p>
The <span class="emphasis"><em>
type</em></span>
 field can have any one of the values shown in Table 16.17.
</p><div class="table"><a id="idp67879292"></a><p class="title"><strong>Table 16.17. Device Button Action Types</strong></p><div class="table-contents"><table summary="Device Button Action Types" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Type</th><th align="left">Effect</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_DeviceBtn</em></span></td><td align="left">
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If the button specified by this action is logically down, the key press and
corresponding release are ignored and have no effect. If the device or button
specified by this action are illegal, this action behaves like <span class="emphasis"><em>
XkbSA_NoAction</em></span>.
    </p></li><li class="listitem"><p>
Otherwise, key presses cause one or more input extension device events instead
of the usual key press event. If the <span class="emphasis"><em>
count</em></span>
 field is zero, a key press generates a single <span class="emphasis"><em>
DeviceButtonPress</em></span>
 event. If count is greater than zero, a key press event generates <span class="emphasis"><em>
count</em></span>
 pairs of <span class="emphasis"><em>
DeviceButtonPress</em></span>
 and <span class="emphasis"><em>
DeviceButtonRelease</em></span>
 events.
    </p></li><li class="listitem"><p>
If <span class="emphasis"><em>
count</em></span>
 is zero, a key release generates an input extension <span class="emphasis"><em>
DeviceButtonRelease</em></span>
 event that matches the event generated by the corresponding key press. If
<span class="emphasis"><em>
count</em></span>
 is nonzero, a key release does not cause a <span class="emphasis"><em>
DeviceButtonRelease</em></span>
 event. Key releases never cause <span class="emphasis"><em>
KeyRelease</em></span>
 events.
    </p></li></ul></div>
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_LockDeviceBtn</em></span></td><td align="left">
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If the device or button specified by this action are illegal, this action
behaves like <span class="emphasis"><em>XkbSA_NoAction</em></span>.
    </p></li><li class="listitem"><p>
Otherwise, if the specified button is not locked and the <span class="emphasis"><em>
XkbSA_LockNoLock</em></span>
 bit is not set in the <span class="emphasis"><em>
flags</em></span>
 field, a key press generates an input extension <span class="emphasis"><em>
DeviceButtonPress</em></span>
 event instead of a <span class="emphasis"><em>
KeyPress</em></span>
 event and locks the button. If the button is already locked or if <span class="emphasis"><em>
XkbSA_LockNoLock</em></span>
 bit is set in the <span class="emphasis"><em>
flags</em></span>
 field, the key press is ignored and has no effect.
    </p></li><li class="listitem"><p>
If the corresponding key press was ignored, and if the <span class="emphasis"><em>
XkbSA_LockNoUnlock</em></span>
 bit is not set in the <span class="emphasis"><em>
flags</em></span>
 field, a key release generates an input extension <span class="emphasis"><em>
DeviceButtonRelease</em></span>
 event instead of a <span class="emphasis"><em>
KeyRelease</em></span>
 event and unlocks the button. If the corresponding key press locked a button,
the key release is ignored and has no effect.
    </p></li></ul></div>
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
The <span class="emphasis"><em>
flags</em></span>
 field is composed of the bitwise inclusive OR of the masks shown in Table
16.18.
</p><div class="table"><a id="idp67894324"></a><p class="title"><strong>Table 16.18. Device Button Action Flags</strong></p><div class="table-contents"><table summary="Device Button Action Flags" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Flag</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_LockNoLock</em></span></td><td align="left">
If set, and the action type is <span class="emphasis"><em>
XkbSA_LockDeviceBtn</em></span>
, the server only unlocks the button.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_LockNoUnlock</em></span></td><td align="left">
If set, and the action type is <span class="emphasis"><em>
XkbSA_LockDeviceBtn</em></span>
, the server only locks the button.
    </td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Actions_for_Simulating_Events_from_Device_Valuators"></a>Actions for Simulating Events from Device Valuators</h3></div></div></div><p>
A <span class="emphasis"><em>
valuator</em></span>
 manipulates a range of values for some entity, like a mouse axis, a slider or
a dial. Actions associated with <span class="emphasis"><em>
XkbDeviceValuatorAction</em></span>
 structures are used to simulate events from one or two input extension device
valuators.
</p><pre class="programlisting">
typedef struct _XkbDeviceValuatorAction {
      unsigned char    type;        /*<span class="emphasis"><em> XkbSA_DeviceValuator</em></span> */
      unsigned char    device;      /* device ID */
      unsigned char    v1_what;     /* determines how valuator is to behave for valuator 1 */
      unsigned char    v1_ndx;      /* specifies a real valuator */
      unsigned char    v1_value;    /* the value for valuator 1 */
      unsigned char    v2_what;     /* determines how valuator is to behave for valuator 2 */
      unsigned char    v2_ndx;      /* specifies a real valuator */
      unsigned char    v2_value;    /* the value for valuator 1 */
} <span class="emphasis"><em>XkbDeviceValuatorAction</em></span>;
</pre><p>
If <span class="emphasis"><em>
device</em></span>
 is illegal or if neither <span class="emphasis"><em>
v1_ndx</em></span>
 nor <span class="emphasis"><em>
v2_ndx</em></span>
 specifies a legal valuator, this action behaves like <span class="emphasis"><em>
XkbSA_NoAction</em></span>.
</p><p>
The low four bits of <span class="emphasis"><em>
v1_what</em></span>
 and <span class="emphasis"><em>
v2_what</em></span>
 specify the corresponding scale value (denoted <span class="emphasis"><em>
val&lt;n&gt;Scale</em></span>
 in Table 16.17), if needed. The high four bits of <span class="emphasis"><em>
v1_what</em></span>
 and <span class="emphasis"><em>
v2_what</em></span>
 specify the operation to perform to set the values. The high four bits of
<span class="emphasis"><em>
v1_what</em></span>
 and <span class="emphasis"><em>
v2_what</em></span>
 can have the values shown in Table 16.17; the use of <span class="emphasis"><em>
val&lt;n&gt;Scale</em></span>
 is shown in that table also.
</p><div class="table"><a id="idp67906396"></a><p class="title"><strong>Table 16.19. Device Valuator v&lt;n&gt;_what High Bits Values</strong></p><div class="table-contents"><table summary="Device Valuator v&lt;n&gt;_what High Bits Values" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Value of high bits</th><th align="left">Effect</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSA_IgnoreVal</em></span></td><td align="left">No action</td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_SetValMin</em></span></td><td align="left">
<span class="emphasis"><em>v&lt;n&gt;_value</em></span> is set to its minimum legal value.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_SetValCenter</em></span></td><td align="left">
<span class="emphasis"><em>v&lt;n&gt;_value</em></span>is centered (to (max-min)/2).
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_SetValMax</em></span></td><td align="left">
<span class="emphasis"><em>v&lt;n&gt;_value</em></span> is set to its maximum legal value.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_SetValRelative</em></span></td><td align="left">
<span class="emphasis"><em>v&lt;n&gt;_value</em></span> * (2
<span class="emphasis"><em>val&lt;n&gt;Scale</em></span>) is added to
<span class="emphasis"><em>v&lt;n&gt;_value</em></span>.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSA_SetValAbsolute</em></span></td><td align="left">
<span class="emphasis"><em>v&lt;n&gt;_value</em></span>
 is set to (2 <span class="emphasis"><em>val&lt;n&gt;Scale</em></span>).
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
Illegal values for <span class="emphasis"><em>
XkbSA_SetValRelative</em></span>
 or <span class="emphasis"><em>
XkbSA_SetValAbsolute</em></span>
 are clamped into range. Note that all of these possibilities are legal for
absolute valuators. For relative valuators, only <span class="emphasis"><em>
XkbSA_SetValRelative</em></span>
 is permitted. Part of the input extension description of a device is the range
of legal values for all absolute valuators, whence the maximum and minimum
legal values shown in Table 16.17.
</p><p>
The following two masks are provided as a convenience to select either portion
of <span class="emphasis"><em>
v1_what</em></span>
 or <span class="emphasis"><em>
v2_what</em></span>
:
</p><div class="literallayout"><p><br />
      #define XkbSA_ValOpMask      (0x70)<br />
      #define XkbSA_ValScaleMask      (0x07)<br />
</p></div><p>
<span class="emphasis"><em>
v1_ndx</em></span>
 and <span class="emphasis"><em>
v2_ndx</em></span>
 specify valuators that actually exists. For example, most mice have two
valuators (x and y axes) so the only legal values for a mouse would be 0 and 1.
For a dial box with eight dials, any value in the range 0..7 would be correct.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Obtaining_Key_Actions_for_Keys_from_the_Server"></a>Obtaining Key Actions for Keys from the Server</h3></div></div></div><p>
To update the actions (the <span class="emphasis"><em>
key_acts</em></span>
 array) for a subset of the keys in a keyboard description, use <span class="emphasis"><em>
XkbGetKeyActions</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetKeyActions</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 first</em></span>
, <span class="emphasis"><em>
num</em></span>
,<span class="emphasis"><em>
 xkb</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
first</em></span>
;            /* keycode of first key of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
num</em></span>
;            /* number of keys desired */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr             <span class="emphasis"><em>
xkb</em></span>
;            /* pointer to keyboard description where result is stored */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetKeyActions</em></span>
 sends a request to the server to obtain the actions for <span class="emphasis"><em>
num</em></span>
 keys on the keyboard starting with key <span class="emphasis"><em>
first</em></span>
. It waits for a reply and returns the actions in the <span class="emphasis"><em>
server</em></span>
-&gt;<span class="emphasis"><em>
key_acts</em></span>
 field of <span class="emphasis"><em>
xkb</em></span>
. If successful, <span class="emphasis"><em>
XkbGetKeyActions</em></span>
 returns <span class="emphasis"><em>
Success</em></span>
. The <span class="emphasis"><em>
xkb</em></span>
 parameter must be a pointer to a valid Xkb keyboard description.
</p><p>
If the <span class="emphasis"><em>
server</em></span>
 map in the <span class="emphasis"><em>
xkb</em></span>
 parameter has not been allocated, <span class="emphasis"><em>
XkbGetKeyActions</em></span>
 allocates and initializes it before obtaining the actions.
</p><p>
If the server does not have a compatible version of Xkb, or the Xkb extension
has not been properly initialized, <span class="emphasis"><em>
XkbGetKeyActions</em></span>
 returns <span class="emphasis"><em>
BadAccess</em></span>
. If <span class="emphasis"><em>
num</em></span>
 is less than 1 or greater than <span class="emphasis"><em>
XkbMaxKeyCount</em></span>
, <span class="emphasis"><em>
XkbGetKeyActions</em></span>
 returns <span class="emphasis"><em>
BadValue</em></span>
. If any allocation errors occur, <span class="emphasis"><em>
XkbGetKeyActions</em></span>
 returns <span class="emphasis"><em>
BadAlloc</em></span>
.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Changing_the_Number_of_Actions_Bound_to_a_Key"></a>Changing the Number of Actions Bound to a Key</h3></div></div></div><p>
To change the number of actions bound to a key, use <span class="emphasis"><em>
XkbResizeKeyAction</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbAction *<span class="emphasis"><em>
XkbResizeKeyActions</em></span>
(<span class="emphasis"><em>
xkb</em></span>
,<span class="emphasis"><em>
 key</em></span>
,<span class="emphasis"><em>
 needed</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescRec *<span class="emphasis"><em>
            xkb</em></span>
;            /* keyboard description to change */
    </td></tr><tr><td class="functionargdecl" align="left">
int <span class="emphasis"><em>
            key</em></span>
;            /* keycode of key to change */
    </td></tr><tr><td class="functionargdecl" align="left">
int <span class="emphasis"><em>
            needed</em></span>
;            /* new number of actions required */
    </td></tr></tbody></table></div><p>
The <span class="emphasis"><em>
xkb</em></span>
 parameter points to the keyboard description containing the <span class="emphasis"><em>
key</em></span>
 whose number of actions is to be changed. The <span class="emphasis"><em>
key</em></span>
 parameter is the keycode of the key to change, and <span class="emphasis"><em>
needed</em></span>
 specifies the new number of actions required for the key.
</p><p>
<span class="emphasis"><em>
XkbResizeKeyActions</em></span>
 reserves the space needed for the actions and returns a pointer to the
beginning of the new array that holds the actions. It can change the <span class="emphasis"><em>
acts</em></span>
, <span class="emphasis"><em>
num_acts</em></span>
, and <span class="emphasis"><em>
size_acts</em></span>
 fields of <span class="emphasis"><em>
xkb</em></span>
-&gt;<span class="emphasis"><em>
server</em></span>
 if it is necessary to reallocate the <span class="emphasis"><em>
acts </em></span>
array.
</p><p>
If <span class="emphasis"><em>
needed</em></span>
 is greater than the current number of keysyms for the key, <span class="emphasis"><em>
XkbResizeKeyActions</em></span>
 initializes all new actions in the array to <span class="emphasis"><em>
NoAction</em></span>
.
</p><p>
Because the number of actions needed by a key is normally computed as width *
number of groups, and <span class="emphasis"><em>
XkbResizeKeyActions</em></span>
 does not modify either the width or number of groups for the key, a
discrepancy exists on return from <span class="emphasis"><em>
XkbResizeKeyActions</em></span>
 between the space allocated for the actions and the number required. The
unused entries in the list of actions returned by <span class="emphasis"><em>
XkbResizeKeyActions</em></span>
 are not preserved across future calls to any of the map editing functions, so
you must update the key actions (which updates the width and number of groups
for the key) before calling another allocator function. A call to <span class="emphasis"><em>
XkbChangeTypesOfKey</em></span>
 updates these.
</p><p>
If any allocation errors occur while resizing the number of actions bound to
the key, <span class="emphasis"><em>
XkbResizeKeyActions</em></span>
 returns <span class="emphasis"><em>
NULL</em></span>
.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>A change to the number of actions bound to a key should be
accompanied by a change in the number of symbols bound to a key. Refer to
section 15.3.7 for more information on changing the number of symbols bound to
a key.</p></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Key_Behavior"></a>Key Behavior</h2></div></div></div><p>
Key behavior refers to the demeanor of a key. For example, the expected
behavior of the <span class="emphasis"><em>
CapsLock</em></span>
 key is that it logically locks when pressed, and then logically unlocks when
pressed again.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Radio_Groups_2"></a>Radio Groups</h3></div></div></div><p>
Keys that belong to the same radio group have the <span class="emphasis"><em>
XkbKB_RadioGroup</em></span>
 type in the <span class="emphasis"><em>
type</em></span>
 field and the radio group index specified in the <span class="emphasis"><em>
data</em></span>
 field in the <span class="emphasis"><em>
XkbBehavior</em></span>
 structure. If the radio group has a name in the <span class="emphasis"><em>
XkbNamesRec</em></span>
 structure, the radio group index is the index into the <span class="emphasis"><em>
radio_group</em></span>
 array in the <span class="emphasis"><em>
XkbNamesRec</em></span>
 structure. A radio group key when pressed stays logically down until another
key in the radio group is pressed, when the first key becomes logically up and
the new key becomes logically down. Setting the <span class="emphasis"><em>
XkbKB_RGAllowNone</em></span>
 bit in the behavior for all of the keys of the radio group means that pressing
the logically down member of the radio group causes it to logically release, in
which case none of the keys of the radio group would be logically down. If
<span class="emphasis"><em>
XkbKB_RGAllowNone</em></span>
 is not set, there is no way to release the logically down member of the group.
</p><p>
The low five bits of the <span class="emphasis"><em>
data</em></span>
 field of the <span class="emphasis"><em>
XkbBehavior</em></span>
 structure are the group number, the high three bits are flags. The only flag
currently defined is:
</p><pre class="programlisting">
#define      XkbRG_AllowNone      0x80
</pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="The_XkbBehavior_Structure"></a>The XkbBehavior Structure</h3></div></div></div><p>
The <span class="emphasis"><em>
behaviors</em></span>
 field of the server map is an array of <span class="emphasis"><em>
XkbBehavior</em></span>
 structures, indexed by keycode, and contains the behavior for each key. The
<span class="emphasis"><em>
XkbBehavior</em></span>
 structure is defined as follows:
</p><pre class="programlisting">
typedef struct _XkbBehavior {
      unsigned char  type;                  /* behavior type + optional
                                               <span class="emphasis"><em> XkbKB_Permanent</em></span> bit */
      unsigned char  data;
} <span class="emphasis"><em>XkbBehavior</em></span>;
</pre><p>
The <span class="emphasis"><em>
type</em></span>
 field specifies the Xkb behavior, and the value of the <span class="emphasis"><em>
data</em></span>
 field depends on the <span class="emphasis"><em>
type</em></span>
. Xkb supports the key behaviors shown in Table 16.20.
</p><div class="table"><a id="idp67957940"></a><p class="title"><strong>Table 16.20. Key Behaviors</strong></p><div class="table-contents"><table summary="Key Behaviors" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Type</th><th align="left">Effect</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbKB_Default</em></span></td><td align="left">
Press and release events are processed normally. The <span class="emphasis"><em>
data</em></span>
 field is unused.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbKB_Lock</em></span></td><td align="left">
If a key is logically up (that is, the corresponding bit of the core key map is
cleared) when it is pressed, the key press is processed normally and the
corresponding release is ignored. If the key is logically down when pressed,
the key press is ignored but the corresponding release is processed normally.
The <span class="emphasis"><em>
data</em></span>
 field is unused.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbKB_RadioGroup</em></span></td><td align="left">
      <p>
If another member of the radio group is logically down (all members of the
radio group have the same index, specified in <span class="emphasis"><em>
data</em></span>
) when a key is pressed, the server synthesizes a key release for the member
that is logically down and then processes the new key press event normally.
      </p>
      <p>
If the key itself is logically down when pressed, the key press event is
ignored, but the processing of the corresponding key release depends on the
value of the <span class="emphasis"><em>
Xkb_RGAllowNone</em></span>
 bit in <span class="emphasis"><em>
flags</em></span>
. If it is set, the key release is processed normally; otherwise, the key
release is also ignored.
      </p>
      <p>
All other key release events are ignored.
      </p>
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbKB_Overlay1</em></span></td><td align="left">
If the <span class="emphasis"><em>
Overlay1</em></span>
 control is enabled (see section 10.4), <span class="emphasis"><em>
data</em></span>
 is interpreted as a keycode, and events from this key are reported as if they
came from <span class="emphasis"><em>
data</em></span>
’s keycode. Otherwise, press and release events are processed normally.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbKB_Overlay2</em></span></td><td align="left">
If the <span class="emphasis"><em>
Overlay2</em></span>
 control is enabled (see section 10.4), <span class="emphasis"><em>
data</em></span>
 is interpreted as a keycode, and events from this key are reported as if they
came from <span class="emphasis"><em>
data</em></span>
’s keycode. Otherwise, press and release events are processed normally.
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
Xkb also provides the mask, <span class="emphasis"><em>
XkbKB_Permanent</em></span>
 to specify whether the key behavior type should be simulated by Xkb or whether
the key behavior describes an unalterable physical, electrical, or software
aspect of the keyboard. If the <span class="emphasis"><em>
XkbKB_Permanent</em></span>
 bit is not set in the <span class="emphasis"><em>
type</em></span>
 field, Xkb simulates the behavior in software. Otherwise, Xkb relies upon the
keyboard to implement the behavior.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Obtaining_Key_Behaviors_for_Keys_from_the_Server"></a>Obtaining Key Behaviors for Keys from the Server</h3></div></div></div><p>
To obtain the behaviors (the <span class="emphasis"><em>
behaviors</em></span>
 array) for a subset of the keys in a keyboard description from the server, use
<span class="emphasis"><em>
XkbGetKeyBehaviors</em></span>
:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetKeyBehaviors</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 first</em></span>
,<span class="emphasis"><em>
 num</em></span>
,<span class="emphasis"><em>
 xkb</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            dpy</em></span>
;            /* connection to server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
first</em></span>
;            /* keycode of first key to get */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
num</em></span>
;            /* number of keys for which behaviors are desired */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr             <span class="emphasis"><em>
xkb</em></span>
;            /* Xkb description to contain the result */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetKeyBehaviors</em></span>
 sends a request to the server to obtain the behaviors for <span class="emphasis"><em>
num</em></span>
 keys on the keyboard starting with the key whose keycode is <span class="emphasis"><em>
first</em></span>
. It waits for a reply and returns the behaviors in the <span class="emphasis"><em>
server</em></span>
-&gt;<span class="emphasis"><em>
behaviors</em></span>
 field of <span class="emphasis"><em>
xkb</em></span>
. If successful, <span class="emphasis"><em>
XkbGetKeyBehaviors</em></span>
 returns <span class="emphasis"><em>
Success</em></span>
.
</p><p>
If the <span class="emphasis"><em>
server</em></span>
 map in the <span class="emphasis"><em>
xkb</em></span>
 parameter has not been allocated, <span class="emphasis"><em>
XkbGetKeyBehaviors</em></span>
 allocates and initializes it before obtaining the actions.
</p><p>
If the server does not have a compatible version of Xkb, or the Xkb extension
has not been properly initialized, <span class="emphasis"><em>
XkbGetKeyBehaviors</em></span>
 returns <span class="emphasis"><em>
BadAccess</em></span>
. If <span class="emphasis"><em>
num</em></span>
 is less than 1 or greater than <span class="emphasis"><em>
XkbMaxKeyCount</em></span>
, <span class="emphasis"><em>
XkbGetKeyBehaviors</em></span>
 returns <span class="emphasis"><em>
BadValue</em></span>
. If any allocation errors occur, <span class="emphasis"><em>
XkbGetKeyBehaviors</em></span>
 returns <span class="emphasis"><em>
BadAlloc</em></span>
.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Explicit_ComponentsAvoiding_Automatic_Remapping_by_the_Server"></a>Explicit Components—Avoiding Automatic Remapping by the Server</h2></div></div></div><p>
Whenever a client remaps the keyboard using core protocol requests, Xkb
examines the map to determine likely default values for the components that
cannot be specified using the core protocol (see section 17.1.2 for more
information on how Xkb chooses the default values).
</p><p>
This automatic remapping might replace definitions explicitly requested by an
application, so the Xkb keyboard description defines an explicit components
mask for each key. Any aspects of the automatic remapping listed in the
explicit components mask for a key are not changed by the automatic keyboard
mapping.
</p><p>
The explicit components masks are held in the <span class="emphasis"><em>
explicit</em></span>
 field of the server map, which is an array indexed by keycode. Each entry in
this array is a mask that is a bitwise inclusive OR of the values shown in
Table 16.21.
</p><div class="table"><a id="idp67987444"></a><p class="title"><strong>Table 16.21. Explicit Component Masks</strong></p><div class="table-contents"><table summary="Explicit Component Masks" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">Bit in Explicit Mask</th><th align="left">Value</th><th align="left">Protects Against</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>ExplicitKeyType1</em></span></td><td align="left">(1&lt;&lt;0)</td><td align="left">
Automatic determination of the key type associated with <span class="emphasis"><em>
Group1.</em></span>
    </td></tr><tr><td align="left"><span class="emphasis"><em>ExplicitKeyType2</em></span></td><td align="left">(1&lt;&lt;1)</td><td align="left">
Automatic determination of the key type associated with <span class="emphasis"><em>
Group2.</em></span>
    </td></tr><tr><td align="left"><span class="emphasis"><em>ExplicitKeyType3</em></span></td><td align="left">(1&lt;&lt;2)</td><td align="left">
Automatic determination of the key type associated with <span class="emphasis"><em>
Group3.</em></span>
    </td></tr><tr><td align="left"><span class="emphasis"><em>ExplicitKeyType4</em></span></td><td align="left">(1&lt;&lt;3)</td><td align="left">
Automatic determination of the key type associated with <span class="emphasis"><em>
Group4.</em></span>
    </td></tr><tr><td align="left"><span class="emphasis"><em>ExplicitInterpret</em></span></td><td align="left">(1&lt;&lt;4)</td><td align="left">
Application of any of the fields of a symbol interpretation to the
key in question.
    </td></tr><tr><td align="left"><span class="emphasis"><em>ExplicitAutoRepeat</em></span></td><td align="left">(1&lt;&lt;5)</td><td align="left">Automatic determination of auto-repeat status for the key, as
specified in a symbol interpretation.</td></tr><tr><td align="left"><span class="emphasis"><em>ExplicitBehavior</em></span></td><td align="left">(1&lt;&lt;6)</td><td align="left">
Automatic assignment of the <span class="emphasis"><em>
XkbKB_Lock</em></span>
 behavior to the key, if the <span class="emphasis"><em>
XkbSI_LockingKey</em></span>
 flag is set in a symbol interpretation.
    </td></tr><tr><td align="left"><span class="emphasis"><em>ExplicitVModMap</em></span></td><td align="left">(1&lt;&lt;7)</td><td align="left">
Automatic determination of the virtual modifier map for the key
based on the actions assigned to the key and the symbol interpretations that
match the key.
    </td></tr></tbody></table></div></div><br class="table-break" /><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Obtaining_Explicit_Components_for_Keys_from_the_Server"></a>Obtaining Explicit Components for Keys from the Server</h3></div></div></div><p>
To obtain the explicit components (the <span class="emphasis"><em>
explicit</em></span>
 array) for a subset of the keys in a keyboard description, use <span class="emphasis"><em>
XkbGetKeyExplicitComponents</em></span>.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetKeyExplicitComponents</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 first</em></span>
,<span class="emphasis"><em>
 num</em></span>
,<span class="emphasis"><em>
 xkb</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            dpy</em></span>
;            /* connection to server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
first</em></span>
;            /* keycode of first key to fetch */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
num</em></span>
;            /* number of keys for which to get explicit info */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr             <span class="emphasis"><em>
xkb</em></span>
;            /* Xkb description in which to put results */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetKeyExplicitComponents</em></span>
 sends a request to the server to obtain the explicit components for <span class="emphasis"><em>
num</em></span>
 keys on the keyboard starting with key <span class="emphasis"><em>
first</em></span>
. It waits for a reply and returns the explicit components in the <span class="emphasis"><em>
server</em></span>
-&gt;<span class="emphasis"><em>
explicit</em></span>
 array of <span class="emphasis"><em>
xkb</em></span>
. If successful, <span class="emphasis"><em>
XkbGetKeyExplicitComponents</em></span>
 returns <span class="emphasis"><em>
Success</em></span>
. The <span class="emphasis"><em>
xkb</em></span>
 parameter must be a pointer to a valid Xkb keyboard description.
</p><p>
If the <span class="emphasis"><em>
server</em></span>
 map in the <span class="emphasis"><em>
xkb</em></span>
 parameter has not been allocated, <span class="emphasis"><em>
XkbGetKeyExplicitComponents</em></span>
 allocates and initializes it before obtaining the actions.
</p><p>
If the server does not have a compatible version of Xkb, or the Xkb extension
has not been properly initialized, <span class="emphasis"><em>
XkbGetKeyExplicitComponents</em></span>
 returns <span class="emphasis"><em>
BadMatch</em></span>
. If <span class="emphasis"><em>
num</em></span>
 is less than 1 or greater than <span class="emphasis"><em>
XkbMaxKeyCount</em></span>
, <span class="emphasis"><em>
XkbGetKeyExplicitComponents</em></span>
 returns <span class="emphasis"><em>
BadValue</em></span>
. If any allocation errors occur, <span class="emphasis"><em>
XkbGetKeyExplicitComponents</em></span>
 returns <span class="emphasis"><em>
BadAlloc</em></span>
.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Virtual_Modifier_Mapping"></a>Virtual Modifier Mapping</h2></div></div></div><p>
The <span class="emphasis"><em>
vmods</em></span>
 member of the server map is a fixed-length array containing <span class="emphasis"><em>
XkbNumVirtualMods</em></span>
 entries. Each entry corresponds to a virtual modifier and provides the binding
of the virtual modifier to the real modifier bits. Each entry in the <span class="emphasis"><em>
vmods</em></span>
 array is a bitwise inclusive OR of the legal modifier masks:
</p><div class="literallayout"><p><br />
     <span class="emphasis"><em>ShiftMask</em></span><br />
     <span class="emphasis"><em>LockMask</em></span><br />
     <span class="emphasis"><em>ControlMask</em></span><br />
     <span class="emphasis"><em>Mod1Mask</em></span><br />
     <span class="emphasis"><em>Mod2Mask</em></span><br />
     <span class="emphasis"><em>Mod3Mask</em></span><br />
     <span class="emphasis"><em>Mod4Mask</em></span><br />
     <span class="emphasis"><em>Mod5Mask</em></span><br />
</p></div><p>
The <span class="emphasis"><em>
vmodmap</em></span>
 member of the server map is similar to the <span class="emphasis"><em>
modmap</em></span>
 array of the client map (see section 15.4), but is used to define the virtual
modifier mapping for each key. Like the <span class="emphasis"><em>
modmap</em></span>
 member, it is indexed by keycode, and each entry is a mask representing the
virtual modifiers bound to the corresponding key:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Each of the bits in a <span class="emphasis"><em>
vmodmap</em></span>
 entry represents an index into the <span class="emphasis"><em>
vmods</em></span>
 member. That is, bit 0 of a <span class="emphasis"><em>
vmodmap</em></span>
 entry refers to index 0 of the <span class="emphasis"><em>
vmods</em></span>
 array, bit 1 refers to index 1, and so on.
    </p></li><li class="listitem"><p>
If a bit is set in the <span class="emphasis"><em>
vmodmap</em></span>
 entry for a key, that key is bound to the corresponding virtual modifier in
the <span class="emphasis"><em>
vmods</em></span>
 array.
    </p></li></ul></div><p>
The <span class="emphasis"><em>
vmodmap</em></span>
 and <span class="emphasis"><em>
vmods</em></span>
 members of the server map are the "master" virtual modifier definitions. Xkb
automatically propagates any changes to these fields to all other fields that
use virtual modifier mappings.
</p><p>
The overall relationship of fields dealing with virtual modifiers in an Xkb
keyboard description are shown in Figure 16.2.
</p><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-17.svg"></object><div class="caption">Virtual Modifier Relationships</div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Obtaining_Virtual_Modifier_Bindings_from_the_Server"></a>Obtaining Virtual Modifier Bindings from the Server</h3></div></div></div><p>
To obtain a subset of the virtual modifier bindings (the <span class="emphasis"><em>
vmods</em></span>
 array) in a keyboard description, use <span class="emphasis"><em>
XkbGetVirtualMods</em></span>
:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetVirtualMods</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 which</em></span>
,<span class="emphasis"><em>
 xkb</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            dpy</em></span>
;            /* connection to server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
which</em></span>
;            /* mask indicating virtual modifier bindings to get */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;            /* Xkb description where results will be placed */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetVirtualMods</em></span>
 sends a request to the server to obtain the <span class="emphasis"><em>
vmods</em></span>
 entries for the virtual modifiers specified in the mask, <span class="emphasis"><em>
which</em></span>
, and waits for a reply. See section 7.1 for a description of how to determine
the virtual modifier mask. For each bit set in <span class="emphasis"><em>
which</em></span>
, <span class="emphasis"><em>
XkbGetVirtualMods</em></span>
 updates the corresponding virtual modifier definition in the <span class="emphasis"><em>
server-&gt;vmods</em></span>
 array of <span class="emphasis"><em>
xkb</em></span>
. The <span class="emphasis"><em>
xkb</em></span>
 parameter must be a pointer to a valid Xkb keyboard description. If
successful, <span class="emphasis"><em>
XkbGetVirtualMods</em></span>
 returns <span class="emphasis"><em>
Success</em></span>
.
</p><p>
If the <span class="emphasis"><em>
server</em></span>
 map has not been allocated in the <span class="emphasis"><em>
xkb</em></span>
 parameter, <span class="emphasis"><em>
XkbGetVirtualMods</em></span>
 allocates and initializes it before obtaining the virtual modifier bindings.
</p><p>
If the server does not have a compatible version of Xkb, or the Xkb extension
has not been properly initialized, <span class="emphasis"><em>
XkbGetVirtualMods</em></span>
 returns <span class="emphasis"><em>
BadMatch</em></span>
. Any errors in allocation cause <span class="emphasis"><em>
XkbGetVirtualMods </em></span>
to return <span class="emphasis"><em>
BadAlloc</em></span>.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Obtaining_Per_Key_Virtual_Modifier_Mappings_from_the_Server"></a>Obtaining Per-Key Virtual Modifier Mappings from the Server</h3></div></div></div><p>
To obtain the virtual modifier map (the <span class="emphasis"><em>
vmodmap</em></span>
 array) for a subset of the keys in a keyboard description, use <span class="emphasis"><em>
XkbGetKeyVirtualModMap</em></span>
:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetKeyVirtualModMap</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 first</em></span>
,<span class="emphasis"><em>
 num</em></span>
,<span class="emphasis"><em>
 xkb</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *<span class="emphasis"><em>
            dpy</em></span>
;            /* connection to server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
first</em></span>
;            /* keycode of first key to fetch */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
num</em></span>
;            /* # keys for which virtual mod maps are desired */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr             <span class="emphasis"><em>
xkb</em></span>
;            /* Xkb description where results will be placed */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetKeyVirutalModmap </em></span>
sends a request to the server to obtain the virtual modifier mappings for
<span class="emphasis"><em>
num</em></span>
 keys on the keyboard starting with key <span class="emphasis"><em>
first</em></span>
. It waits for a reply and returns the virtual modifier mappings in the
<span class="emphasis"><em>
server</em></span>
-&gt;<span class="emphasis"><em>
vmodmap</em></span>
 array of <span class="emphasis"><em>
xkb</em></span>
. If successful, <span class="emphasis"><em>
XkbGetKeyVirtualModMap</em></span>
 returns <span class="emphasis"><em>
Success</em></span>
. The <span class="emphasis"><em>
xkb</em></span>
 parameter must be a pointer to a valid Xkb keyboard description
</p><p>
If the <span class="emphasis"><em>
server</em></span>
 map in the <span class="emphasis"><em>
xkb</em></span>
 parameter has not been allocated, <span class="emphasis"><em>
XkbGetKeyVirtualModMap</em></span>
 allocates and initializes it before obtaining the virtual modifier mappings.
</p><p>
If the server does not have a compatible version of Xkb, or the Xkb extension
has not been properly initialized, <span class="emphasis"><em>
XkbGetKeyVirtualModMap</em></span>
 returns <span class="emphasis"><em>
BadMatch</em></span>
. If <span class="emphasis"><em>
num</em></span>
 is less than 1 or greater than <span class="emphasis"><em>
XkbMaxKeyCount</em></span>
, <span class="emphasis"><em>
XkbGetKeyVirtualModMap</em></span>
 returns <span class="emphasis"><em>
BadValue</em></span>
. If any allocation errors occur, <span class="emphasis"><em>
XkbGetKeyVirtualModMap</em></span>
 returns <span class="emphasis"><em>
BadAlloc</em></span>
.
</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="The_Xkb_Compatibility_Map"></a>Chapter 17. The Xkb Compatibility Map</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#The_XkbCompatMap_Structure">The XkbCompatMap Structure</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Xkb_State_to_Core_Protocol_State_Transformation">Xkb State to Core Protocol State Transformation</a></span></dt><dt><span class="sect2"><a href="#Core_Keyboard_Mapping_to_Xkb_Keyboard_Mapping_Transformation">Core Keyboard Mapping to Xkb Keyboard Mapping Transformation</a></span></dt><dt><span class="sect2"><a href="#Xkb_Keyboard_Mapping_to_Core_Keyboard_Mapping_Transformations">Xkb Keyboard Mapping to Core Keyboard Mapping Transformations</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Getting_Compatibility_Map_Components_From_the_Server">Getting Compatibility Map Components From the Server</a></span></dt><dt><span class="sect1"><a href="#Using_the_Compatibility_Map">Using the Compatibility Map</a></span></dt><dt><span class="sect1"><a href="#Changing_the_Servers_Compatibility_Map">Changing the Server’s Compatibility Map</a></span></dt><dt><span class="sect1"><a href="#Tracking_Changes_to_the_Compatibility_Map">Tracking Changes to the Compatibility Map</a></span></dt><dt><span class="sect1"><a href="#Allocating_and_Freeing_the_Compatibility_Map">Allocating and Freeing the Compatibility Map</a></span></dt></dl></div><p>
As shown in Figure 17.1, the X server is normally dealing with more than one
client, each of which may be receiving events from the keyboard, and each of
which may issue requests to modify the keyboard in some manner. Each client may
be either Xkb-unaware, Xkb-capable, or Xkb-aware. The server itself may be
either Xkb-aware or Xkb-unaware. If the server is Xkb-unaware, Xkb state and
keyboard mappings are not involved in any manner, and Xkb-aware clients may not
issue Xkb requests to the server. If the server is Xkb-aware, the server must
be able to deliver events and accept requests in which the keyboard state and
mapping are compatible with the mode in which the client is operating.
Consequently, for some situations, conversions must be made between Xkb state /
keyboard mappings and core protocol state / keyboard mappings, and vice versa.
</p><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-18.svg"></object><div class="caption">Server Interaction with Types of Clients</div></div><p>
In addition to these situations involving a single server, there are cases
where a client that deals with multiple servers may need to configure keyboards
on different servers to be similar and the different servers may not all be
Xkb-aware. Finally, a client may be dealing with descriptions of keyboards
(files, and so on) that are based on core protocol and therefore may need to be
able to map these descriptions to Xkb descriptions.
</p><p>
An Xkb-aware server maintains keyboard state and mapping as an Xkb keyboard
state and an Xkb keyboard mapping plus a compatibility map used to convert from
Xkb components to core components and vice versa. In addition, the server also
maintains a core keyboard mapping that approximates the Xkb keyboard mapping.
The core keyboard mapping may be updated piecemeal, on a per-key basis. When
the server receives a core protocol <span class="emphasis"><em>
ChangeKeyboardMapping</em></span>
 or <span class="emphasis"><em>
SetModifierMapping</em></span>
 request, it updates its core keyboard mapping, then uses the compatibility map
to update its Xkb keyboard mapping. When the server receives an <span class="emphasis"><em>
XkbSetMap</em></span>
 request, it updates those portions of its Xkb keyboard mapping specified by
the request, then uses its compatibility map to update the corresponding parts
of its core keyboard map. Consequently, the server’s Xkb keyboard map and
also its core keyboard map may contain components that were set directly and
others that were computed. Figure 17.2 illustrates these relationships.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The core keyboard map is contained only in the server, not in any
client-side data structures.</p></div><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-19.svg"></object><div class="caption">Server Derivation of State and Keyboard Mapping Components</div></div><p>
There are three kinds of compatibility transformations made by the server:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="bold"><strong>Xkb State to Core State</strong></span></p><p>
Keyboard state information reported to a client in the state field of various
core events may be translated from the Xkb keyboard state maintained by the
server, which includes a group number, to core protocol state, which does
not.
    </p><p>
In addition, whenever the Xkb state is retrieved, the <span class="emphasis"><em>
compat_state</em></span>
, <span class="emphasis"><em>
compat_grab_mods</em></span>
, and <span class="emphasis"><em>
compat_lookup_mods</em></span>
 fields of the <span class="emphasis"><em>
XkbStateRec</em></span>
 returned indicate the result of applying the compatibility map to the current
Xkb state in the server.
    </p></li><li class="listitem"><p><span class="bold"><strong>Core Keyboard Mapping to Xkb Keyboard Mapping</strong></span></p><p>
After core protocol requests received by the server to change the keyboard
mapping (<span class="emphasis"><em>
ChangeKeyboardMapping</em></span>
 and <span class="emphasis"><em>
SetModifierMapping</em></span>
) have been applied to the server’s core keyboard map, the results must be
transformed to achieve an equivalent change of the Xkb keyboard mapping
maintained by the server.
    </p></li><li class="listitem"><p><span class="bold"><strong>Xkb Keyboard Mapping to Core Keyboard Mapping</strong></span></p><p>
After Xkb protocol requests received by the server to change the keyboard
mapping (<span class="emphasis"><em>
XkbSetMap</em></span>
) have been applied to the server’s Xkb keyboard map, the results are
transformed to achieve an approximately equivalent change to the core keyboard
mapping maintained by the server.
    </p></li></ol></div><p>
This chapter discusses how a client may modify the compatibility map so that
subsequent transformations have a particular result.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="The_XkbCompatMap_Structure"></a>The XkbCompatMap Structure</h2></div></div></div><p>
All configurable aspects of mapping Xkb state and configuration to and from
core protocol state and configuration are defined by a compatibility map,
contained in an <span class="emphasis"><em>
XkbCompatMap</em></span>
 structure; plus a set of explicit override controls used to prevent particular
components of type 2 (core-to-Xkb keyboard mapping) transformations from
automatically occurring. These explicit override controls are maintained in a
separate data structure discussed in section 16.3. 
</p><p>
The <span class="emphasis"><em>
compat</em></span>
 member of an Xkb keyboard description (<span class="emphasis"><em>
XkbDescRec</em></span>
) points to the<span class="emphasis"><em>
 XkbCompatMap</em></span>
 structure:
</p><pre class="programlisting">
typedef struct _XkbCompatMapRec {
      XkbSymInterpretPtr   sym_interpret;            /* symbol based key semantics*/
      XkbModsRec           groups[XkbNumKbdGroups];  /* group =&gt; modifier map */
      unsigned short       num_si;                   /* # structures used in
                                                        <span class="emphasis"><em>sym_interpret</em></span> */
      unsigned short       size_si;                  /* # structures allocated in
                                                        <span class="emphasis"><em>sym_interpret</em></span> */
} <span class="emphasis"><em>XkbCompatMapRec</em></span>, *XkbCompatMapPtr;
</pre><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-20.svg"></object><div class="caption">Xkb Compatibility Data Structures</div></div><p>
The subsections that follow discuss how the compatibility map and explicit
override controls are used in each of the three cases where compatibility
transformations are made.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Xkb_State_to_Core_Protocol_State_Transformation"></a>Xkb State to Core Protocol State Transformation</h3></div></div></div><p>
As shown in Figure 17.3, there are four <span class="emphasis"><em>
group compatibility maps</em></span>
 (contained in <span class="emphasis"><em>
groups</em></span>
 [0..3]) in the <span class="emphasis"><em>
XkbCompatMapRec</em></span>
 structure, one per possible Xkb group. Each group compatibility map is a
modifier definition (see section 7.2 for a description of modifier
definitions). The <span class="emphasis"><em>
mask</em></span>
 component of the definition specifies which real modifiers should be set in
the core protocol state field when the corresponding group is active. Because
only one group is active at any one time, only one of the four possible
transformations is ever applied at any one point in time. If the device
described by the <span class="emphasis"><em>
XkbDescRec</em></span>
 does not support four groups, the extra groups fields are present, but
undefined.
</p><p>
Normally, the Xkb-aware server reports keyboard state in the <span class="emphasis"><em>
state</em></span>
 member of events such as a <span class="emphasis"><em>
KeyPress</em></span>
 event and <span class="emphasis"><em>
ButtonPress</em></span>
 event, encoded as follows:
</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c1" /></colgroup><thead><tr><th align="left">bits</th><th align="left">meaning</th></tr></thead><tbody><tr><td align="left">15</td><td align="left">0</td></tr><tr><td align="left">13-14</td><td align="left">Group index</td></tr><tr><td align="left">8-12</td><td align="left">Pointer Buttons</td></tr><tr><td align="left">0-7</td><td align="left">Modifiers</td></tr></tbody></table></div><p>
For Xkb-unaware clients, only core protocol keyboard information may be
reported. Because core protocol does not define the group index, the group
index is mapped to modifier bits as specified by the <span class="emphasis"><em>
groups</em></span>
[group index] field of the compatibility map (the bits set in the compatibility
map are ORed into bits 0-7 of the state), and bits 13-14 are reported in the
event as zero.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Core_Keyboard_Mapping_to_Xkb_Keyboard_Mapping_Transformation"></a>Core Keyboard Mapping to Xkb Keyboard Mapping Transformation</h3></div></div></div><p>
When a core protocol keyboard mapping request is received by the server, the
server’s core keyboard map is updated, and then the Xkb map maintained by the
server is updated. Because a client may have explicitly configured some of the
Xkb keyboard mapping in the server, this automatic regeneration of the Xkb
keyboard mapping from the core protocol keyboard mapping should not modify any
components of the Xkb keyboard mapping that were explicitly set by a client.
The client must set explicit override controls to prevent this from happening
(see section 16.3). The core-to-Xkb mapping is done as follows:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Map the symbols from the keys in the core keyboard map to groups and symbols on
keys in the Xkb keyboard map. The core keyboard mapping is of fixed width, so
each key in the core mapping has the same number of symbols associated with it.
The Xkb mapping allows a different number of symbols to be associated with each
key; those symbols may be divided into a different number of groups (1-4) for
each key. For each key, this process therefore involves partitioning the fixed
number of symbols from the core mapping into a set of variable-length groups
with a variable number of symbols in each group. For example, if the core
protocol map is of width five, the partition for one key might result in one
group with two symbols and another with three symbols. A different key might
result in two groups with two symbols plus a third group with one symbol. The
core protocol map requires at least two symbols in each of the first two
groups.
    </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>
For each changed key, determine the number of groups represented in the new
core keyboard map. This results in a tentative group count for each key in the
Xkb map.
        </p></li><li class="listitem"><p>
For each changed key, determine the number of symbols in each of the groups
found in step 1a. There is one explicit override control associated with each
of the four possible groups for each Xkb key, <span class="emphasis"><em>
ExplicitKeyType1</em></span>
 through <span class="emphasis"><em>
ExplicitKeyType4</em></span>
. If no explicit override control is set for a group, the number of symbols
used for that group from the core map is two.  If the explicit override control
is set for a group on the key, the number of symbols used for that Xkb group
from the core map is the width of the Xkb group with one exception: because of
the core protocol requirement for at least two symbols in each of groups one
and two, the number of symbols used for groups one and two is the maximum of 2
or the width of the Xkb group.
        </p></li><li class="listitem"><p>
For each changed key, assign the symbols in the core map to the appropriate
group on the key. If the total number of symbols required by the Xkb map for a
particular key needs more symbols than the core protocol map contains, the
additional symbols are taken to be <span class="emphasis"><em>
NoSymbol</em></span>
 keysyms appended to the end of the core set. If the core map contains more
symbols than are needed by the Xkb map, trailing symbols in the core map are
discarded. In the absence of an explicit override for group one or two, symbols
are assigned in order by group; the first symbols in the core map are assigned
to group one, in order, followed by group two, and so on. For example, if the
core map contained eight symbols per key, and a particular Xkb map contained 2
symbols for G1 and G2 and three for G3, the symbols would be assigned as (G is
group, L is shift level):
        </p><div class="literallayout"><p><br />
          G1L1 G1L2 G2L1 G2L2 G3L1 G3L2 G3L3<br />
</p></div><p>
If an explicit override control is set for group one or two, the symbols are
taken from the core set in a somewhat different order. The first four symbols
from the core set are assigned to G1L1, G1L2, G2L1, G2L2, respectively. If
group one requires more symbols, they are taken next, and then any additional
symbols needed by group two. Group three and four symbols are taken in complete
sequence after group two. For example, a key with four groups and three symbols
in each group would take symbols from the core set in the following order:
        </p><div class="literallayout"><p><br />
G1L1 G1L2 G2L1 G2L2 G1L3 G2L3 G3L1 G3L2 G3L3 G4L1 G4L2 G4L3<br />
</p></div><p>
As previously noted, the core protocol map requires at lease two symbols in
groups one and two. Because of this, if an explicit override control for an Xkb
key is set and group one and / or group two is of width one, it is not possible
to generate the symbols taken from the core protocol set and assigned to
position G1L2 and / or G2L2.
        </p></li><li class="listitem"><p>
For each group on each changed key, assign a key type appropriate for the
symbols in the group.
        </p></li><li class="listitem"><p>
For each changed key, remove any empty or redundant groups.
        </p></li></ol></div></li><li class="listitem"><p>
At this point, the groups and their associated symbols have been assigned to
the corresponding key definitions in the Xkb map.
    </p></li><li class="listitem"><p>
Apply symbol interpretations to modify key operation. This phase is completely
skipped if the  <span class="emphasis"><em>
ExplicitInterpret</em></span>
 override control bit is set in the explicit controls mask for the Xkb key (see
section 16.3).
    </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>
For each symbol on each changed key, attempt to match the symbol and modifiers
from the Xkb map to a symbol interpretation describing how to generate the
symbol.
        </p></li><li class="listitem"><p>
When a match is found in step 2a, apply the symbol interpretation to change the
semantics associated with the symbol in the Xkb key map. If no match is found,
apply a default interpretation.
        </p></li></ol></div></li></ol></div><p>
The symbol interpretations used in step 2 are configurable and may be specified
using <span class="emphasis"><em>
XkbSymInterpretRec</em></span>
 structures referenced by the <span class="emphasis"><em>
sym_interpret</em></span>
 field of an <span class="emphasis"><em>
XkbCompatMapRec</em></span>
 (see Figure 17.3).
</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Symbol_Interpretations__the_XkbSymInterpretRec_Structure"></a>Symbol Interpretations — the XkbSymInterpretRec Structure</h4></div></div></div><p>
Symbol interpretations are used to guide the X server when it modifies the Xkb
keymap in step 2. An initial set of symbol interpretations is loaded by the
server when it starts. A client may add new ones using <span class="emphasis"><em>
XkbSetCompatMap</em></span>
 (see section 17.4).
</p><p>
Symbol interpretations result in key semantics being set. When a symbol
interpretation is applied, the following components of server key event
processing may be modified for the particular key involved:
</p><div class="literallayout"><p><br />
      Virtual modifier map<br />
      Auto repeat<br />
      Key behavior (may be set to <span class="emphasis"><em>XkbKB_Lock</em></span>)<br />
      Key action (see section 16.1)<br />
</p></div><p>
The <span class="emphasis"><em>XkbSymInterpretRec</em></span>
structure specifies a symbol interpretation:
</p><pre class="programlisting">
typedef struct {
      KeySym          sym;          /* keysym of interest or <span class="emphasis"><em>NULL</em></span> */
      unsigned char   flags;        /* <span class="emphasis"><em>XkbSI_AutoRepeat, XkbSI_LockingKey</em></span> */
      unsigned char   match;        /* specifies how mods is interpreted */
      unsigned char   mods;         /* modifier bits, correspond to eight real modifiers */
      unsigned char   virtual_mod;  /* 1 modifier to add to key virtual mod map */
      XkbAnyAction    act;          /* action to bind to symbol position on key */
} <span class="emphasis"><em>XkbSymInterpretRec</em></span>,*XkbSymInterpretPtr;
</pre><p>
If <span class="emphasis"><em>
sym</em></span>
 is not <span class="emphasis"><em>
NULL</em></span>
, it limits the symbol interpretation to keys on which that particular keysym
is selected by the modifiers matching the criteria specified by <span class="emphasis"><em>
mods</em></span>
 and <span class="emphasis"><em>
match</em></span>
. If <span class="emphasis"><em>
sym</em></span>
 is <span class="emphasis"><em>
NULL</em></span>
, the interpretation may be applied to any symbol selected on a key when the
modifiers match the criteria specified by <span class="emphasis"><em>
mods</em></span>
 and <span class="emphasis"><em>
match</em></span>
.
</p><p>
<span class="emphasis"><em>match</em></span>
must be one of the values shown in Table 17.1 and specifies how the real
modifiers specified in <span class="emphasis"><em>mods</em></span>
are to be interpreted.
</p><div class="table"><a id="idp66869580"></a><p class="title"><strong>Table 17.1. Symbol Interpretation Match Criteria</strong></p><div class="table-contents"><table summary="Symbol Interpretation Match Criteria" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">Match Criteria</th><th align="left">Value</th><th align="left">Effect</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSI_NoneOf</em></span></td><td align="left">(0)</td><td align="left">
None of the bits that are on in <span class="emphasis"><em>mods</em></span>
 can be set, but other bits can be.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSI_AnyOfOrNone</em></span></td><td align="left">(1)</td><td align="left">
Zero or more of the bits that are on in <span class="emphasis"><em>
mods</em></span>
 can be set, as well as others.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSI_AnyOf</em></span></td><td align="left">(2)</td><td align="left">
One or more of the bits that are on in <span class="emphasis"><em>
mods</em></span>
 can be set, as well as any others.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSI_AllOf</em></span></td><td align="left">(3)</td><td align="left">
All of the bits that are on in <span class="emphasis"><em>
mods</em></span>
 must be set, but others may be set as well.
    </td></tr><tr><td align="left"><span class="emphasis"><em>XkbSI_Exactly</em></span></td><td align="left">(4)</td><td align="left">
All of the bits that are on in <span class="emphasis"><em>
mods</em></span>
 must be set, and no other bits may be set.
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
In addition to the above bits, <span class="emphasis"><em>
match</em></span>
 may contain the <span class="emphasis"><em>
XkbSI_LevelOneOnly</em></span>
 bit, in which case the modifier match criteria specified by <span class="emphasis"><em>
mods</em></span>
 and <span class="emphasis"><em>
match</em></span>
 applies only if <span class="emphasis"><em>
sym</em></span>
 is in level one of its group; otherwise, <span class="emphasis"><em>
mods</em></span>
 and <span class="emphasis"><em>
match</em></span>
 are ignored and the symbol matches a condition where no modifiers are set.
</p><pre class="programlisting">
#define XkbSI_LevelOneOnly  (0x80)
/* use mods + match only if sym is level 1 */
</pre><p>
If no matching symbol interpretation is found, the server uses a default
interpretation where:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c1" /></colgroup><tbody><tr><td align="left"><span class="emphasis"><em>sym</em></span> =</td><td align="left">0</td></tr><tr><td align="left"><span class="emphasis"><em>flags</em></span> =</td><td align="left"><span class="emphasis"><em>XkbSI_AutoRepeat</em></span></td></tr><tr><td align="left"><span class="emphasis"><em>match</em></span> =</td><td align="left"><span class="emphasis"><em>XkbSI_AnyOfOrNone</em></span></td></tr><tr><td align="left"><span class="emphasis"><em>mods</em></span> =</td><td align="left">0</td></tr><tr><td align="left"><span class="emphasis"><em>virtual_mod</em></span> =</td><td align="left"><span class="emphasis"><em>XkbNoModifier</em></span></td></tr><tr><td align="left"><span class="emphasis"><em>act</em></span> =</td><td align="left"><span class="emphasis"><em>SA_NoAction</em></span></td></tr></tbody></table></div><p>
When a matching symbol interpretation is found in step 2a, the interpretation
is applied to modify the Xkb map as follows.
</p><p>
The <span class="emphasis"><em>
act</em></span>
 field specifies a single action to be bound to the symbol position; any key
event that selects the symbol causes the action to be taken. Valid actions are
defined in section 16.1.
</p><p>
If the Xkb keyboard map for the key does not have its <span class="emphasis"><em>
ExplicitVModMap</em></span>
 control set, the <span class="emphasis"><em>
XkbSI_LevelOneOnly</em></span>
 bit and symbol position are examined. If the <span class="emphasis"><em>
XkbSI_LevelOneOnly</em></span>
 bit is not set in <span class="emphasis"><em>
match</em></span>
 or the symbol is in position G1L1, the <span class="emphasis"><em>
virtual_mod</em></span>
 field is examined. If <span class="emphasis"><em>
virtual_mod</em></span>
 is not <span class="emphasis"><em>
XkbNoModifier</em></span>
, <span class="emphasis"><em>
virtual_mod</em></span>
 specifies a single virtual modifier to be added to the virtual modifier map
for the key.<span class="emphasis"><em>
 virtual_mod</em></span>
 is specified as an index in the range [0..15].
</p><p>
If the matching symbol is in position G1L1 of the key, two bits in the flags
field potentially specify additional behavior modifications:
</p><pre class="programlisting">
#define      XkbSI_AutoRepeat    (1&lt;&lt;0)
                                 /* key repeats if sym is in position G1L1 */
#define      XkbSI_LockingKey    (1&lt;&lt;1)
                                 /* set <span class="emphasis"><em> KB_Lock</em></span>
                                    behavior if sym is in psn G1L1 */
</pre><p>
If the Xkb keyboard map for the key does not have its <span class="emphasis"><em>
ExplicitAutoRepeat</em></span>
 control set, its auto repeat behavior is set based on the value of the
<span class="emphasis"><em>
XkbSI_AutoRepeat</em></span>
 bit. If the <span class="emphasis"><em>
XkbSI_AutoRepeat</em></span>
 bit is set, the auto-repeat behavior of the key is turned on; otherwise, it is
turned off.
</p><p>
If the Xkb keyboard map for the key does not have its <span class="emphasis"><em>
ExplicitBehavior</em></span>
 control set, its locking behavior is set based on the value of the <span class="emphasis"><em>
XkbSI_LockingKey</em></span>
 bit. If <span class="emphasis"><em>
XkbSI_LockingKey</em></span>
 is set, the key behavior is set to <span class="emphasis"><em>
KB_Lock</em></span>
; otherwise, it is turned off (see section 16.3).
</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Xkb_Keyboard_Mapping_to_Core_Keyboard_Mapping_Transformations"></a>Xkb Keyboard Mapping to Core Keyboard Mapping Transformations</h3></div></div></div><p>
Whenever the server processes Xkb requests to change the keyboard mapping, it
discards the affected portion of its core keyboard mapping and regenerates it
based on the new Xkb mapping.
</p><p>
When the Xkb mapping for a key is transformed to a core protocol mapping, the
symbols for the core map are taken in the following order from the Xkb map:
</p><p>
G1L1 G1L2 G2L1 G2L2 G1L3-n G2L3-n G3L1-n G4L1-n
</p><p>
If group one is of width one in the Xkb map, G1L2 is taken to be NoSymbol;
similarly, if group two is of width one in the Xkb map, G2L2 is taken to be
NoSymbol.
</p><p>
If the Xkb key map for a particular key has fewer groups than the core
keyboard, the symbols for group one are repeated to fill in the missing core
components. For example, an Xkb key with a single width-three group would be
mapped to a core mapping counting three groups as:
</p><p>
G1L1 G1L2 G1L1 G1L2 G1L3 G1L3 G1L1 G1L2 G1L3
</p><p>
When a core keyboard map entry is generated from an Xkb keyboard map entry, a
modifier mapping is generated as well. The modifier mapping contains all of the
modifiers affected by any of the actions associated with the key combined with
all of the real modifiers associated with any of the virtual modifiers bound to
the key. In addition, if any of the actions associated with the key affect any
component of the keyboard group, all of the modifiers in the <span class="emphasis"><em>
mask</em></span>
 field of all of the group compatibility maps are added to the modifier mapping
as well. While an <span class="emphasis"><em>
XkbSA_ISOLock</em></span>
 action can theoretically affect any modifier, if the Xkb mapping for a key
specifies an <span class="emphasis"><em>
XkbSA_ISOLock</em></span>
 action, only the modifiers or group that are set by default are added to the
modifier mapping.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Getting_Compatibility_Map_Components_From_the_Server"></a>Getting Compatibility Map Components From the Server</h2></div></div></div><p>
Use <span class="emphasis"><em>
XkbGetCompatMap</em></span>
 to fetch any combination of the current compatibility map components from the
server. When another client modifies the compatibility map, you are notified if
you have selected for <span class="emphasis"><em>
XkbCompatMapNotify</em></span>
 events (see section 17.5). <span class="emphasis"><em>
XkbGetCompatMap</em></span>
 is particularly useful when you receive an event of this type, as it allows
you to update your program’s version of the compatibility map to match the
modified version now in the server. If your program is dealing with multiple
servers and needs to configure them all in a similar manner, the updated
compatibility map may be used to reconfigure other servers.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>To make a complete matching configuration you must also update the
explicit override components of the server state.</p></div><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetCompatMap</em></span>
(<span class="emphasis"><em>
display, which, xkb</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display * <span class="emphasis"><em>
            display</em></span>
;            /* connection to server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
            which</em></span>
;            /* mask of compatibility map components to fetch */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescRec * <span class="emphasis"><em>
            xkb</em></span>
;            /* keyboard description where results placed */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetCompatMap</em></span>
 fetches the components of the compatibility map specified in <span class="emphasis"><em>
which</em></span>
 from the server specified by <span class="emphasis"><em>
display</em></span>
 and places them in the <span class="emphasis"><em>
compat</em></span>
 structure of the keyboard description <span class="emphasis"><em>
xkb</em></span>
. Valid values for <span class="emphasis"><em>
which</em></span>
 are an inclusive OR of the values shown in Table 17.2.
</p><div class="table"><a id="idp67184468"></a><p class="title"><strong>Table 17.2. Compatibility Map Component Masks</strong></p><div class="table-contents"><table summary="Compatibility Map Component Masks" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">Mask</th><th align="left">Value</th><th align="left">Affecting</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbSymInterpMask</em></span></td><td align="left">(1&lt;&lt;0)</td><td align="left">Symbol interpretations</td></tr><tr><td align="left"><span class="emphasis"><em>XkbGroupCompatMask</em></span></td><td align="left">(1&lt;&lt;1)</td><td align="left">Group maps</td></tr><tr><td align="left"><span class="emphasis"><em>XkbAllCompatMask</em></span></td><td align="left">(0x3)</td><td align="left">All compatibility map components</td></tr></tbody></table></div></div><br class="table-break" /><p>
If no compatibility map structure is allocated in <span class="emphasis"><em>
xkb</em></span>
 upon entry, <span class="emphasis"><em>
XkbGetCompatMap</em></span>
 allocates one. If one already exists, its contents are overwritten with the
returned results.
</p><p>
<span class="emphasis"><em>
XkbGetCompatMap</em></span>
 fetches compatibility map information for the device specified by the
<span class="emphasis"><em>
device_spec</em></span>
 field of <span class="emphasis"><em>
xkb</em></span>
. Unless you have specifically modified this field, it is the default keyboard
device. <span class="emphasis"><em>
XkbGetCompatMap</em></span>
 returns <span class="emphasis"><em>
Success</em></span>
 if successful, <span class="emphasis"><em>
BadAlloc</em></span>
 if it is unable to obtain necessary storage for either the return values or
work space, <span class="emphasis"><em>
BadMatch</em></span>
 if the <span class="emphasis"><em>
dpy</em></span>
 field of the <span class="emphasis"><em>
xkb</em></span>
 argument is non-<span class="emphasis"><em>
NULL</em></span>
 and does not match the <span class="emphasis"><em>
display</em></span>
 argument, and <span class="emphasis"><em>
BadLength</em></span>
 under certain conditions caused by server or Xkb implementation errors.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Using_the_Compatibility_Map"></a>Using the Compatibility Map</h2></div></div></div><p>
Xkb provides several functions that make it easier to apply the compatibility
map to configure a client-side Xkb keyboard mapping, given a core protocol
representation of part or all of a keyboard mapping. Obtain a core protocol
representation of a keyboard mapping from an actual server (by using <span class="emphasis"><em>
XGetKeyboardMapping</em></span>
, for example), a data file, or some other source.
</p><p>
To update a local Xkb keyboard map to reflect the mapping expressed by a core
format mapping by calling the function <span class="emphasis"><em>
XkbUpdateMapFromCore</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbUpdateMapFromCore</em></span>
(<span class="emphasis"><em>
xkb</em></span>
,<span class="emphasis"><em>
 first_key</em></span>
,<span class="emphasis"><em>
 num_keys</em></span>
,<span class="emphasis"><em>
 map_width</em></span>
,<span class="emphasis"><em>
 core_keysyms</em></span>
,<span class="emphasis"><em>
 changes</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr <span class="emphasis"><em>
            xkb</em></span>
;            /* keyboard description to update */
    </td></tr><tr><td class="functionargdecl" align="left">
KeyCode <span class="emphasis"><em>
            first_key</em></span>
;            /* keycode of first key description to update */
    </td></tr><tr><td class="functionargdecl" align="left">
int <span class="emphasis"><em>
            num_keys</em></span>
;            /* number of key descriptions to update */
    </td></tr><tr><td class="functionargdecl" align="left">
int <span class="emphasis"><em>
            map_width</em></span>
;            /* width of core protocol keymap */
    </td></tr><tr><td class="functionargdecl" align="left">
KeySym *<span class="emphasis"><em>
            core_keysyms</em></span>
;            /* symbols in core protocol keymap */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbChangesPtr       <span class="emphasis"><em>
      changes</em></span>
;            /* backfilled with changes made to Xkb */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbUpdateMapFromCore</em></span>
 interprets input argument information representing a keyboard map in core
format to update the Xkb keyboard description passed in <span class="emphasis"><em>
xkb</em></span>
. Only a portion of the Xkb map is updated — the portion corresponding to
keys with keycodes in the range <span class="emphasis"><em>
first_key</em></span>
 through <span class="emphasis"><em>
first_key</em></span>
 + <span class="emphasis"><em>
num_keys</em></span>
 - 1. If <span class="emphasis"><em>
XkbUpdateMapFromCore</em></span>
 is being called in response to a<span class="emphasis"><em>
 </em></span>
<span class="emphasis"><em>
MappingNotify</em></span>
<span class="emphasis"><em>
 </em></span>
event<span class="emphasis"><em>
, first_key</em></span>
 and <span class="emphasis"><em>
num_keys</em></span>
 are reported in the <span class="emphasis"><em>
MappingNotify</em></span>
 event. <span class="emphasis"><em>
core_keysyms</em></span>
 contains the keysyms corresponding to the keycode range being updated, in core
keyboard description order. <span class="emphasis"><em>
map_width</em></span>
 is the number of keysyms per key in <span class="emphasis"><em>
core_keysyms</em></span>
. Thus, the first <span class="emphasis"><em>
map_width</em></span>
 entries in <span class="emphasis"><em>
core_keysyms</em></span>
 are for the key with keycode <span class="emphasis"><em>
first_key</em></span>
, the next <span class="emphasis"><em>
map_width</em></span>
 entries are for key <span class="emphasis"><em>
first_key</em></span>
 + 1, and so on.
</p><p>
In addition to modifying the Xkb keyboard mapping in <span class="emphasis"><em>
xkb</em></span>
, <span class="emphasis"><em>
XkbUpdateMapFromCore</em></span>
 backfills the changes structure whose address is passed in <span class="emphasis"><em>
changes</em></span>
 to indicate the modifications that were made. You may then use <span class="emphasis"><em>
changes</em></span>
 in subsequent calls such as <span class="emphasis"><em>
XkbSetMap</em></span>
, to propagate the local modifications to a server.
</p><p>
When dealing with core keyboard mappings or descriptions, it is sometimes
necessary to determine the Xkb key types appropriate for the symbols bound to a
key in a core keyboard mapping. Use <span class="emphasis"><em>
XkbKeyTypesForCoreSymbols</em></span>
 for this purpose:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
int <span class="emphasis"><em>
XkbKeyTypesForCoreSymbols</em></span>
(<span class="emphasis"><em>
map_width</em></span>
,<span class="emphasis"><em>
 core_syms</em></span>
,<span class="emphasis"><em>
 protected, types_inout, xkb_syms_rtrn</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr<span class="emphasis"><em>
      xkb</em></span>
;            /* keyboard description in which to place symbols*/
    </td></tr><tr><td class="functionargdecl" align="left">
int<span class="emphasis"><em>
      map_width</em></span>
;            /* width of core protocol keymap in <span class="emphasis"><em>
xkb_syms_rtrn</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
KeySym *<span class="emphasis"><em>
      core_syms</em></span>
;            /* core protocol format array of KeySyms */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int       <span class="emphasis"><em>
protected</em></span>
;            /* explicit key types */
    </td></tr><tr><td class="functionargdecl" align="left">
int *<span class="emphasis"><em>
      types_inout;</em></span>
            /* backfilled with the canonical types bound to groups one and two
for the key */
    </td></tr><tr><td class="functionargdecl" align="left">
KeySym *      <span class="emphasis"><em>
xkb_syms_rtrn</em></span>
      ;      /* backfilled with symbols bound to the key in the Xkb mapping */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbKeyTypesForCoreSymbols</em></span>
 expands the symbols in <span class="emphasis"><em>
core_syms</em></span>
 and types in <span class="emphasis"><em>
types_inout</em></span>
 according to the rules specified in section 12 of the core protocol, then
chooses canonical key types (canonical key types are defined in section 15.2.1)
for groups 1 and 2 using the rules specified by the Xkb protocol and places
them in <span class="emphasis"><em>
xkb_syms_rtrn</em></span>
, which will be non-<span class="emphasis"><em>
NULL</em></span>
.
</p><p>
A core keymap is a two-dimensional array of keysyms. It has <span class="emphasis"><em>
map_width</em></span>
 columns and <span class="emphasis"><em>
max_key_code</em></span>
 rows. <span class="emphasis"><em>
XkbKeyTypesForCoreSymbols</em></span>
 takes a single row from a core keymap, determines the number of groups
associated with it, the type of each group, and the symbols bound to each
group. The return value is the number of groups, <span class="emphasis"><em>
types_inout</em></span>
 has the types for each group, and <span class="emphasis"><em>
xkb_syms_rtrn</em></span>
 has the symbols in Xkb order (that is, groups are contiguous, regardless of
size).
</p><p>
<span class="emphasis"><em>
protected</em></span>
 contains the explicitly protected key types. There is one  explicit override
control associated with each of the four possible groups for each Xkb key,
<span class="emphasis"><em>
ExplicitKeyType1</em></span>
 through <span class="emphasis"><em>
ExplicitKeyType4</em></span>
<span class="emphasis"><em>
; protected </em></span>
is an inclusive OR of these controls. <span class="emphasis"><em>
map_width</em></span>
 is the width of the core keymap and is not dependent on any Xkb definitions.
<span class="emphasis"><em>
types_inout</em></span>
 is an array of four type indices. On input, <span class="emphasis"><em>
types_inout</em></span>
 contains the indices of any types already assigned to the key, in case they
are explicitly protected from change.
</p><p>
Upon return, <span class="emphasis"><em>
types_inout</em></span>
 contains any automatically selected (that is, canonical) types plus any
protected types. Canonical types are assigned to all four groups if there are
enough symbols to do so. The four entries in <span class="emphasis"><em>
types_inout</em></span>
 correspond to the four groups for the key in question.
</p><p>
If the groups mapping does not change, but the symbols assigned to an Xkb
keyboard compatibility map do change, the semantics of the key may be modified.
To apply the new compatibility mapping to an individual key to get its
semantics updated, use <span class="emphasis"><em>
XkbApplyCompatMapToKey</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbApplyCompatMapToKey</em></span>
(<span class="emphasis"><em>
xkb</em></span>
,<span class="emphasis"><em>
 key</em></span>
,<span class="emphasis"><em>
 changes</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
  XkbDescPtr<span class="emphasis"><em>
            xkb;            </em></span>
/* keyboard description to be updated */
    </td></tr><tr><td class="functionargdecl" align="left">
  KeyCode<span class="emphasis"><em>
            key</em></span>
;            /* key to be updated */
    </td></tr><tr><td class="functionargdecl" align="left">
  XkbChangesPtr<span class="emphasis"><em>
            changes</em></span>
;            /* notes changes to the Xkb keyboard description */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbApplyCompatMapToKey</em></span>
 essentially performs the operation described in section 17.1.2 to a specific
key. This updates the behavior, actions, repeat status, and virtual modifier
bindings of the key.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Changing_the_Servers_Compatibility_Map"></a>Changing the Server’s Compatibility Map</h2></div></div></div><p>
To modify the server’s compatibility map, first modify a local copy of the
Xkb compatibility map, then call <span class="emphasis"><em>
XkbSetCompatMap</em></span>
. You may allocate a new compatibility map for this purpose using <span class="emphasis"><em>
XkbAllocCompatMap</em></span>
 (see section 17.6). You may also use a compatibility map from another server,
although you need to adjust the <span class="emphasis"><em>
device_spec</em></span>
 field in the <span class="emphasis"><em>
XkbDescRec</em></span>
 accordingly. Note that symbol interpretations in a compatibility map
(<span class="emphasis"><em>
sym_interpret</em></span>
, the vector of <span class="emphasis"><em>
XkbSymInterpretRec</em></span>
 structures) are also allocated using this same function.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSetCompatMap</em></span>
(<span class="emphasis"><em>
display, which, xkb, update_actions</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display * <span class="emphasis"><em>
            display</em></span>
;            /* connection to server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
            which</em></span>
;            /* mask of compat map components to set */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr <span class="emphasis"><em>
            xkb</em></span>
;            /* source for compat map components */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool <span class="emphasis"><em>
            update_actions</em></span>
;            /* <span class="emphasis"><em>
True</em></span>
 =&gt; apply to server’s keyboard map */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSetCompatMap</em></span>
 copies compatibility map information from the keyboard description in
<span class="emphasis"><em>
xkb</em></span>
 to the server specified in <span class="emphasis"><em>
display</em></span>
’s compatibility map for the device specified by the <span class="emphasis"><em>
device_spec</em></span>
 field of <span class="emphasis"><em>
xkb</em></span>
. Unless you have specifically modified this field, it is the default keyboard
device.<span class="emphasis"><em>
 which</em></span>
 specifies the compatibility map components to be set, and is an inclusive OR
of the bits shown in Table 17.2.
</p><p>
After updating its compatibility map for the specified device, if <span class="emphasis"><em>
update_actions</em></span>
 is <span class="emphasis"><em>
True,</em></span>
 the server applies the new compatibility map to its entire keyboard for the
device to generate a new set of key semantics, compatibility state, and a new
core keyboard map. If <span class="emphasis"><em>
update_actions</em></span>
 is <span class="emphasis"><em>
False</em></span>
, the new compatibility map is not used to generate any modifications to the
current device semantics, state, or core keyboard map. One reason for not
applying the compatibility map immediately would be if one server was being
configured to match another on a piecemeal basis; the map should not be applied
until everything is updated. To force an update at a later time, use <span class="emphasis"><em>
XkbSetCompatMap</em></span>
 specifying <span class="emphasis"><em>
which</em></span>
 as zero and <span class="emphasis"><em>
update_actions</em></span>
 as <span class="emphasis"><em>
True</em></span>
.
</p><p>
<span class="emphasis"><em>
XkbSetCompatMap</em></span>
 returns <span class="emphasis"><em>
True</em></span>
 if successful and <span class="emphasis"><em>
False</em></span>
 if unsuccessful. The server may report problems it encounters when processing
the request subsequently via protocol errors.
</p><p>
To add a symbol interpretation to the list of symbol interpretations in an
<span class="emphasis"><em>
XkbCompatRec</em></span>
, use <span class="emphasis"><em>
XkbAddSymInterpret</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbSymInterpretPtr <span class="emphasis"><em>
XkbAddSymInterpret</em></span>
(<span class="emphasis"><em>
xkb, si, updateMap, changes</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr<span class="emphasis"><em>
            xkb</em></span>
;            /* keyboard description to be updated */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbSymInterpretPtr<span class="emphasis"><em>
            si</em></span>
;            /* symbol interpretation to be added */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool<span class="emphasis"><em>
            updateMap</em></span>
;            /* <span class="emphasis"><em>
True</em></span>
=&gt;apply compatibility map to keys */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbChangesPtr<span class="emphasis"><em>
            changes</em></span>
;            /* changes are put here */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAddSymInterpret</em></span>
 adds <span class="emphasis"><em>
si</em></span>
 to the list of symbol interpretations in <span class="emphasis"><em>
xkb</em></span>
. If <span class="emphasis"><em>
updateMap</em></span>
 is <span class="emphasis"><em>
True</em></span>
, it (re)applies the compatibility map to all of the keys on the keyboard. If
<span class="emphasis"><em>
changes</em></span>
 is non-<span class="emphasis"><em>
NULL</em></span>
, it reports the parts of the keyboard that were affected (unless <span class="emphasis"><em>
updateMap</em></span>
 is <span class="emphasis"><em>
True</em></span>
, not much changes). <span class="emphasis"><em>
XkbAddSymInterpret</em></span>
 returns a pointer to the actual new symbol interpretation in the list or
<span class="emphasis"><em>
NULL</em></span>
 if it failed.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Tracking_Changes_to_the_Compatibility_Map"></a>Tracking Changes to the Compatibility Map</h2></div></div></div><p>
The server automatically generates <span class="emphasis"><em>
MappingNotify</em></span>
 events when the keyboard mapping changes. If you wish to be notified of
changes to the compatibility map, you should select for <span class="emphasis"><em>
XkbCompatMapNotify</em></span>
 events. If you select for <span class="emphasis"><em>
XkbMapNotify</em></span>
 events, you no longer receive the automatically generated <span class="emphasis"><em>
MappingNotify</em></span>
 events. If you subsequently deselect <span class="emphasis"><em>
XkbMapNotifyEvent</em></span>
 delivery, you again receive <span class="emphasis"><em>
MappingNotify</em></span>
 events.
</p><p>
To receive <span class="emphasis"><em>
XkbCompatMapNotify</em></span>
 events under all possible conditions, use <span class="emphasis"><em>
XkbSelectEvents</em></span>
 (see section 4.3) and pass <span class="emphasis"><em>
XkbCompatMapNotifyMask</em></span>
 in both <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits</em></span>
.
</p><p>
To receive <span class="emphasis"><em>
XkbCompatMapNotify</em></span>
 events only under certain conditions, use <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
 using <span class="emphasis"><em>
XkbCompatMapNotify</em></span>
 as the <span class="emphasis"><em>
event_type</em></span>
 and specifying the desired map changes in <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits</em></span>
 using mask bits from Table 17.2.
</p><p>
Note that you are notified of changes you make yourself, as well as changes
made by other clients.
</p><p>
The structure for the <span class="emphasis"><em>
XkbCompatMapNotifyEvent</em></span>
 is:
</p><pre class="programlisting">
typedef struct {
      int            type;          /* Xkb extension base event code */
      unsigned long  serial;        /* X server serial number for event */
      Bool           send_event;    /* <span class="emphasis"><em>True</em></span> =&gt;
                                       synthetically generated */
      Display *      display;       /* server connection where event generated */
      Time           time;          /* server time when event generated */
      int            xkb_type;      /* <span class="emphasis"><em>XkbCompatMapNotify</em></span> */
      int            device;        /* Xkb device ID, will not be
                                       <span class="emphasis"><em>XkbUseCoreKbd</em></span> */
      unsigned int   changed_groups;/* number of group maps changed */
      int            first_si;      /* index to 1st changed symbol
                                       interpretation */
      int            num_si;        /* number of changed symbol
                                       interpretations */
      int            num_total_si;  /* total number of valid symbol
                                       interpretations */
} <span class="emphasis"><em>XkbCompatMapNotifyEvent</em></span>;
</pre><p>
<span class="emphasis"><em>
changed_groups</em></span>
 is the number of group compatibility maps that have changed. If you are
maintaining a corresponding copy of the compatibility map, or get a fresh copy
from the server using <span class="emphasis"><em>
XkbGetCompatMap</em></span>
, <span class="emphasis"><em>
changed_groups</em></span>
 references <span class="emphasis"><em>
groups</em></span>
[0..<span class="emphasis"><em>
changed_groups</em></span>
-1] in the <span class="emphasis"><em>
XkbCompatMapRec</em></span>
 structure.
</p><p>
<span class="emphasis"><em>
first_si</em></span>
 is the index of the first changed symbol interpretation, <span class="emphasis"><em>
num_si</em></span>
 is the number of changed symbol interpretations, and <span class="emphasis"><em>
num_total_si</em></span>
 is the total number of valid symbol interpretations. If you are maintaining a
corresponding copy of the compatibility map, or get a fresh copy from the
server using <span class="emphasis"><em>
XkbGetCompatMap</em></span>
, <span class="emphasis"><em>
first_si</em></span>
, <span class="emphasis"><em>
num_si</em></span>
, and <span class="emphasis"><em>
num_total_si</em></span>
 are appropriate for use with the <span class="emphasis"><em>
compat.sym_interpret</em></span>
 vector in this structure.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Allocating_and_Freeing_the_Compatibility_Map"></a>Allocating and Freeing the Compatibility Map</h2></div></div></div><p>
If you are modifying the compatibility map, you need to allocate a new
compatibility map if you do not already have one available. To do so, use
<span class="emphasis"><em>
XkbAllocCompatMap</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocCompatMap</em></span>
(<span class="emphasis"><em>
xkb, which, num_si</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr <span class="emphasis"><em>
      xkb</em></span>
;            /* keyboard description in which to allocate compat map */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      which</em></span>
;            /* mask of compatibility map components to allocate */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      num_si</em></span>
;            /* number of symbol interpretations to allocate */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
xkb</em></span>
 specifies the keyboard description for which compatibility maps are to be
allocated. The compatibility map is the <span class="emphasis"><em>
compat</em></span>
 field in this structure.
</p><p>
<span class="emphasis"><em>
which</em></span>
 specifies the compatibility map components to be allocated (see <span class="emphasis"><em>
XkbGetCompatMap</em></span>
, in section 17.2). <span class="emphasis"><em>
which</em></span>
 is an inclusive OR of the bits shown in Table 17.2.
</p><p>
<span class="emphasis"><em>
num_si</em></span>
 specifies the total number of entries to allocate in the symbol interpretation
vector (<span class="emphasis"><em>
xkb.compat.sym_interpret</em></span>
).
</p><p>
Note that symbol interpretations in a compatibility map (the <span class="emphasis"><em>
sym_interpret</em></span>
 vector of <span class="emphasis"><em>
XkbSymInterpretRec</em></span>
 structures) are also allocated using this same function. To ensure that there
is sufficient space in the symbol interpretation vector for entries to be
added, use <span class="emphasis"><em>
XkbAllocCompatMap</em></span>
 specifying <span class="emphasis"><em>
which</em></span>
 as <span class="emphasis"><em>
XkbSymInterpretMask</em></span>
 and the number of free symbol interpretations needed in <span class="emphasis"><em>
num_si</em></span>
.
</p><p>
<span class="emphasis"><em>
XkbAllocCompatMap</em></span>
 returns <span class="emphasis"><em>
Success</em></span>
 if successful, <span class="emphasis"><em>
BadMatch</em></span>
 if <span class="emphasis"><em>
xkb</em></span>
 is <span class="emphasis"><em>
NULL</em></span>
, or <span class="emphasis"><em>
BadAlloc</em></span>
 if errors are encountered when attempting to allocate storage.
</p><p>
To free an entire compatibility map or selected portions of one, use <span class="emphasis"><em>
XkbFreeCompatMap</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeCompatMap</em></span>
(<span class="emphasis"><em>
xkb, which, free_map</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr <span class="emphasis"><em>
      xkb</em></span>
;            /* Xkb description in which to free compatibility map */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
      which</em></span>
;            /* mask of compatibility map components to free */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool <span class="emphasis"><em>
      free_map</em></span>
;            /* <span class="emphasis"><em>
True</em></span>
 =&gt; free <span class="emphasis"><em>
XkbCompatMap</em></span>
 structure itself */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
which</em></span>
 specifies the compatibility map components to be freed (see <span class="emphasis"><em>
XkbGetCompatMap</em></span>
, in section 17.2). <span class="emphasis"><em>
which</em></span>
 is an inclusive OR of the bits shown in Table 17.2
</p><p>
<span class="emphasis"><em>
free_map</em></span>
 indicates whether the <span class="emphasis"><em>
XkbCompatMap</em></span>
 structure itself should be freed. If <span class="emphasis"><em>
free_map</em></span>
 is <span class="emphasis"><em>
True</em></span>
, <span class="emphasis"><em>
which</em></span>
 is ignored, all non-<span class="emphasis"><em>
NULL</em></span>
 compatibility map components are freed, and the <span class="emphasis"><em>
compat</em></span>
 field in the <span class="emphasis"><em>
XkbDescRec</em></span>
 referenced by <span class="emphasis"><em>
xkb</em></span>
 is set to <span class="emphasis"><em>
NULL</em></span>
.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Symbolic_Names"></a>Chapter 18. Symbolic Names</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#The_XkbNamesRec_Structure">The XkbNamesRec Structure</a></span></dt><dt><span class="sect1"><a href="#Symbolic_Names_Masks">Symbolic Names Masks</a></span></dt><dt><span class="sect1"><a href="#Getting_Symbolic_Names_From_the_Server">Getting Symbolic Names From the Server</a></span></dt><dt><span class="sect1"><a href="#Changing_Symbolic_Names_on_the_Server">Changing Symbolic Names on the Server</a></span></dt><dd><dl><dt><span class="sect2"><a href="#idp67328372"></a></span></dt></dl></dd><dt><span class="sect1"><a href="#Tracking_Name_Changes">Tracking Name Changes</a></span></dt><dt><span class="sect1"><a href="#Allocating_and_Freeing_Symbolic_Names">Allocating and Freeing Symbolic Names</a></span></dt></dl></div><p>
The core protocol does not provide any information to clients other than that
actually used to interpret events. This makes it difficult to write an
application that presents the keyboard to a user in an easy-to-understand way.
Such applications have to examine the vendor string and keycodes to determine
the type of keyboard connected to the server and then examine keysyms and
modifier mappings to determine the effects of most modifiers (the <span class="emphasis"><em>
Shift</em></span>
, <span class="emphasis"><em>
Lock</em></span>
 and <span class="emphasis"><em>
Control</em></span>
 modifiers are defined by the core protocol but no semantics are implied for
any other modifiers).
</p><p>
To make it easier for applications to present a keyboard to the user, Xkb
supports symbolic names for most components of the keyboard extension. Most of
these symbolic names are grouped into the <span class="emphasis"><em>
names</em></span>
 component of the keyboard description.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="The_XkbNamesRec_Structure"></a>The XkbNamesRec Structure</h2></div></div></div><p>
The names component of the keyboard description is defined as follows:
</p><pre class="programlisting">
#define      XkbKeyNameLength      4
#define      XkbKeyNumVirtualMods  16
#define      XkbKeyNumIndicators   32
#define      XkbKeyNumKbdGroups    4
#define      XkbMaxRadioGroups     32
</pre><pre class="programlisting">
typedef struct {
      char      name[XkbKeyNameLength];      /* symbolic key names */
} <span class="emphasis"><em>XkbKeyNameRec</em></span>,*XkbKeyNamePtr;
</pre><pre class="programlisting">
typedef struct {
      char      real[XkbKeyNameLength];
                /* this key name must be in the keys array */
      char      alias[XkbKeyNameLength];
                /* symbolic key name as alias for the key */
} <span class="emphasis"><em>XkbKeyAliasRec</em></span>,*XkbKeyAliasPtr;
</pre><pre class="programlisting">
typedef struct _XkbNamesRec {
      Atom      keycodes;      /* identifies range and meaning of keycodes */
      Atom      geometry;      /* identifies physical location, size, and shape of keys */
      Atom      symbols;       /* identifies the symbols logically bound to the keys */
      Atom      types;         /* identifies the set of key types */
      Atom      compat;        /* identifies actions for keys using core protocol */
      Atom      vmods[XkbNumVirtualMods]; /* symbolic names for virtual modifiers */
      Atom      indicators[XkbNumIndicators];   /* symbolic names for indicators */
      Atom      groups[XkbNumKbdGroups]; /* symbolic names for keyboard groups */
      XkbKeyNamePtr      keys;         /* symbolic key name array */
      XkbKeyAliasPtr     key_aliases;  /* real/alias symbolic name pairs array */
      Atom *    radio_groups;      /* radio group name array */
      Atom      phys_symbols;      /* identifies the symbols engraved on the keyboard */
      unsigned char      num_keys; /* number of keys in the <span class="emphasis"><em> keys</em></span> array */
      unsigned char      num_key_aliases;  /* number of keys in the
                                              <span class="emphasis"><em> key_aliases</em></span> array */
      unsigned short     num_rg;      /* number of radio groups */
} <span class="emphasis"><em>XkbNamesRec</em></span>,*XkbNamesPtr;      /*
</pre><p>
The <span class="emphasis"><em>
keycodes</em></span>
 name identifies the range and meaning of the keycodes returned by the keyboard
in question. The <span class="emphasis"><em>
geometry</em></span>
 name, on the other hand, identifies the physical location, size and shape of
the various keys on the keyboard. As an example to distinguish between these
two names, consider function keys on PC-compatible keyboards. Function keys are
sometimes above the main keyboard and sometimes to the left of the main
keyboard, but the same keycode is used for the key that is logically F1
regardless of physical position. Thus, all PC-compatible keyboards share a
similar keycodes name but may have different geometry names.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The keycodes name is intended to be a very general description of
the keycodes returned by a keyboard; a single keycodes name might cover
keyboards with differing numbers of keys provided all keys have the same
semantics when present. For example, 101 and 102 key PC keyboards might use the
same name. In these cases, applications can use the keyboard <span class="emphasis"><em>
geometry</em></span>
 name to determine which subset of the named keycodes is in use.</p></div><p>
The <span class="emphasis"><em>
symbols</em></span>
 name identifies the symbols logically bound to the keys. The symbols name is a
human or application-readable description of the intended locale or usage of
the keyboard with these symbols. The <span class="emphasis"><em>
phys_symbols</em></span>
 name, on the other hand, identifies the symbols actually engraved on the
keyboard. Given this, the <span class="emphasis"><em>
symbols</em></span>
 name and <span class="emphasis"><em>
phys_symbols</em></span>
 names might be different. For example, the description for a keyboard that has
English US engravings, but that is using Swiss German symbols might have a
<span class="emphasis"><em>
phys_symbols</em></span>
 name of "en_US" and a <span class="emphasis"><em>
symbols</em></span>
 name of "de_CH."
</p><p>
The <span class="emphasis"><em>
types</em></span>
 name provides some information about the set of key types (see section 15.2)
that can be associated with the keyboard. In addition, each key type can have a
name, and each shift level of a type can have a name. Although these names are
stored in the map description with each of the types, they are accessed using
the same methods as the other symbolic names.
</p><p>
The <span class="emphasis"><em>
compat</em></span>
 name provides some information about the rules used to bind actions to keys
that are changed using core protocol requests.
</p><p>
Xkb provides symbolic names for each of the 4 keyboard groups, 16 virtual
modifiers, 32 keyboard indicators, and 4 keyboard groups. These names are held
in the <span class="emphasis"><em>
vmods</em></span>
, <span class="emphasis"><em>
indicators</em></span>
, and <span class="emphasis"><em>
groups</em></span>
 fixed-length arrays.
</p><p>
Each key has a four-byte symbolic name. All of the symbolic key names are held
in the <span class="emphasis"><em>
keys</em></span>
 array, and <span class="emphasis"><em>
num_keys</em></span>
 reports the number of entries that are in the keys array. For each key, the
key name links keys with similar functions or in similar positions on keyboards
that report different keycodes. For example, the <span class="emphasis"><em>
F1</em></span>
 key may emit keycode 23 on one keyboard and keycode 86 on another. By naming
this key "FK01" on both keyboards, the keyboard layout designer can reuse parts
of keyboard descriptions for different keyboards.
</p><p>
Key aliases allow the keyboard layout designer to assign multiple key names to
a single key. This allows the keyboard layout designer to refer to keys using
either their position or their "function." For example, a keyboard layout
designer may wish to refer to the left arrow key on a PC keyboard using the
ISO9995-5 positional specification of A31 or using the functional specification
of LEFT. The <span class="emphasis"><em>
key_aliases</em></span>
 field holds a variable-length array of real and alias key name pairs, and the
total number of entries in the <span class="emphasis"><em>
key_aliases</em></span>
 array is held in <span class="emphasis"><em>
num_key_aliases</em></span>
. For each real and alias key name pair, the <span class="emphasis"><em>
real</em></span>
 field refers to the a name in the keys array, and the <span class="emphasis"><em>
alias</em></span>
 field refers to the alias for that key. Using the previous example, the
keyboard designer may use the name A31 in the keys array, but also define the
name LEFT as an alias for A31 in the <span class="emphasis"><em>
key_aliases</em></span>
 array.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Key aliases defined in the geometry component of a keyboard mapping
(see Chapter 13) override those defined in the keycodes component of the server
database, which are stored in the <span class="emphasis"><em>
XkbNamesRec</em></span>
 (<span class="emphasis"><em>
xkb-&gt;names</em></span>
). Therefore, consider the key aliases defined by the geometry before
considering key aliases supplied by the <span class="emphasis"><em>
XkbNamesRec</em></span>
.</p></div><p>
A radio group is a set of keys whose behavior simulates a set of radio buttons.
Once a key in a radio group is pressed, it stays logically depressed until
another key in the group is pressed, at which point the previously depressed
key is logically released. Consequently, at most one key in a radio group can
be logically depressed at one time.
</p><p>
Each radio group in the keyboard description can have a name. These names are
held in the variable-length array <span class="emphasis"><em>
radio_groups</em></span>
, and <span class="emphasis"><em>
num_rg</em></span>
 tells how many elements are in the <span class="emphasis"><em>
radio_groups</em></span>
 array.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Symbolic_Names_Masks"></a>Symbolic Names Masks</h2></div></div></div><p>
Xkb provides several functions that work with symbolic names. Each of these
functions uses a mask to specify individual fields of the structures described
above. These masks and their relationships to the fields in a keyboard
description are shown in Table 18.1.
</p><div class="table"><a id="idp66828924"></a><p class="title"><strong>Table 18.1. Symbolic Names Masks</strong></p><div class="table-contents"><table summary="Symbolic Names Masks" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Mask Bit</th><th align="left">Value</th><th align="left">Keyboard Component</th><th align="left">Field</th></tr></thead><tbody><tr><td align="left">XkbKeycodesNameMask</td><td align="left">(1&lt;&lt;0)</td><td align="left">Xkb-&gt;names</td><td align="left">keycodes</td></tr><tr><td align="left">XkbGeometryNameMask</td><td align="left">(1&lt;&lt;1)</td><td align="left">Xkb-&gt;names</td><td align="left">geometry</td></tr><tr><td align="left">XkbSymbolsNameMask</td><td align="left">(1&lt;&lt;2)</td><td align="left">Xkb-&gt;names</td><td align="left">symbols</td></tr><tr><td align="left">XkbPhysSymbolsNameMask</td><td align="left">(1&lt;&lt;3)</td><td align="left">Xkb-&gt;names</td><td align="left">phys_symbols</td></tr><tr><td align="left">XkbTypesNameMask</td><td align="left">(1&lt;&lt;4)</td><td align="left">Xkb-&gt;names</td><td align="left">type</td></tr><tr><td align="left">XkbCompatNameMask</td><td align="left">(1&lt;&lt;5)</td><td align="left">Xkb-&gt;names</td><td align="left">compat</td></tr><tr><td align="left">XkbKeyTypeNamesMask</td><td align="left">(1&lt;&lt;6)</td><td align="left">Xkb-&gt;map</td><td align="left">type[*].name</td></tr><tr><td align="left">XkbKTLevelNamesMask</td><td align="left">(1&lt;&lt;7)</td><td align="left">Xkb-&gt;map</td><td align="left">type[*].lvl_names[*]</td></tr><tr><td align="left">XkbIndicatorNamesMask</td><td align="left">(1&lt;&lt;8)</td><td align="left">Xkb-&gt;names</td><td align="left">indicators[*]</td></tr><tr><td align="left">XkbKeyNamesMask</td><td align="left">(1&lt;&lt;9)</td><td align="left">Xkb-&gt;names</td><td align="left">keys[*], num_keys</td></tr><tr><td align="left">XkbKeyAliasesMask</td><td align="left">(1&lt;&lt;10)</td><td align="left">Xkb-&gt;names</td><td align="left">key_aliases[*], num_key_aliases</td></tr><tr><td align="left">XkbVirtualModNamesMask</td><td align="left">(1&lt;&lt;11)</td><td align="left">Xkb-&gt;names</td><td align="left">vmods[*]</td></tr><tr><td align="left">XkbGroupNamesMask</td><td align="left">(1&lt;&lt;12)</td><td align="left">Xkb-&gt;names</td><td align="left">groups[*]</td></tr><tr><td align="left">XkbRGNamesMask</td><td align="left">(1&lt;&lt;13)</td><td align="left">Xkb-&gt;names</td><td align="left">radio_groups[*], num_rg</td></tr><tr><td align="left">XkbComponentNamesMask</td><td align="left">(0x3f)</td><td align="left">Xkb-&gt;names</td><td align="left">
<p>keycodes,</p>
<p>geometry,</p>
<p>symbols,</p>
<p>physical symbols,</p>
<p>types, and</p>
<p>compatibility map</p>
    </td></tr><tr><td align="left">XkbAllNamesMask</td><td align="left">(0x3fff)</td><td align="left">Xkb-&gt;names</td><td align="left">all name components</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Getting_Symbolic_Names_From_the_Server"></a>Getting Symbolic Names From the Server</h2></div></div></div><p>
To obtain symbolic names from the server, use <span class="emphasis"><em>
XkbGetNames</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetNames</em></span>
(<span class="emphasis"><em>
dpy, which, Xkb</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
dpy</em></span>
;      /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
which</em></span>
;      /* mask of names or map components to be updated */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr      <span class="emphasis"><em>
xkb</em></span>
      /* keyboard description to be updated */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetNames</em></span>
 retrieves symbolic names for the components of the keyboard extension from the
X server. The <span class="emphasis"><em>
which</em></span>
 parameter specifies the name components to be updated in the <span class="emphasis"><em>
xkb</em></span>
 parameter, and is the bitwise inclusive OR of the valid names mask bits
defined in Table 18.1.
</p><p>
If the <span class="emphasis"><em>
names</em></span>
 field of the keyboard description <span class="emphasis"><em>
xkb</em></span>
 is <span class="emphasis"><em>
NULL</em></span>
, <span class="emphasis"><em>
XkbGetNames</em></span>
 allocates and initializes the <span class="emphasis"><em>
names</em></span>
 component of the keyboard description before obtaining the values specified by
<span class="emphasis"><em>
which</em></span>
. If the <span class="emphasis"><em>
names</em></span>
 field of <span class="emphasis"><em>
xkb</em></span>
 is not <span class="emphasis"><em>
NULL</em></span>
, <span class="emphasis"><em>
XkbGetNames</em></span>
 obtains the values specified by <span class="emphasis"><em>
which</em></span>
 and copies them into the keyboard description <span class="emphasis"><em>
Xkb</em></span>
.
</p><p>
If the <span class="emphasis"><em>
map</em></span>
 component of the <span class="emphasis"><em>
xkb</em></span>
 parameter is <span class="emphasis"><em>
NULL</em></span>
, <span class="emphasis"><em>
XkbGetNames</em></span>
 does not retrieve type or shift level names, even if <span class="emphasis"><em>
XkbKeyTypeNamesMask</em></span>
 or <span class="emphasis"><em>
XkbKTLevelNamesMask</em></span>
 are set in <span class="emphasis"><em>
which</em></span>
.
</p><p>
<span class="emphasis"><em>
XkbGetNames</em></span>
 can return <span class="emphasis"><em>
Success</em></span>
, or <span class="emphasis"><em>
BadAlloc</em></span>
, <span class="emphasis"><em>
BadLength</em></span>
, <span class="emphasis"><em>
BadMatch</em></span>
, and <span class="emphasis"><em>
BadImplementation</em></span>
 errors.
</p><p>
To free symbolic names, use <span class="emphasis"><em>
XkbFreeNames</em></span>
 (see section 18.6)
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Changing_Symbolic_Names_on_the_Server"></a>Changing Symbolic Names on the Server</h2></div></div></div><p>
To change the symbolic names in the server, first modify a local copy of the
keyboard description and then use either <span class="emphasis"><em>
XkbSetNames,</em></span>
 or, to save network traffic, use a <span class="emphasis"><em>
XkbNameChangesRec</em></span>
structure and call <span class="emphasis"><em>
XkbChangeNames</em></span>
 to download the changes to the server. <span class="emphasis"><em>
XkbSetNames</em></span>
 and <span class="emphasis"><em>
XkbChangeNames</em></span>
 can generate <span class="emphasis"><em>
BadAlloc</em></span>
, <span class="emphasis"><em>
BadAtom</em></span>
, <span class="emphasis"><em>
BadLength</em></span>
, <span class="emphasis"><em>
BadMatch,</em></span>
 and <span class="emphasis"><em>
BadImplementation</em></span>
 errors.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSetNames</em></span>
(<span class="emphasis"><em>
dpy, which, first_type, num_types, xkb</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
dpy</em></span>
;            /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
which</em></span>
;            /* mask of names or map components to be changed */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
first_type</em></span>
      ;      /* first type whose name is to be changed */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
num_types</em></span>
;            /* number of types for which names are to be changed */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr      <span class="emphasis"><em>
xkb</em></span>
;            /* keyboard description from which names are to be taken */
    </td></tr></tbody></table></div><p>
Use<span class="emphasis"><em>
 XkbSetNames</em></span>
 to change many names at the same time. For each bit set in <span class="emphasis"><em>
which</em></span>
, <span class="emphasis"><em>
XkbSetNames</em></span>
 takes the corresponding value (or values in the case of arrays) from the
keyboard description <span class="emphasis"><em>
xkb</em></span>
 and sends it to the server.
</p><p>
The <span class="emphasis"><em>
first_type</em></span>
 and <span class="emphasis"><em>
num_types</em></span>
 arguments are used only if <span class="emphasis"><em>
XkbKeyTypeNamesMask</em></span>
 or <span class="emphasis"><em>
XkbKTLevelNamesMask</em></span>
 is set in <span class="emphasis"><em>
which</em></span>
 and specify a subset of the types for which the corresponding names are to be
changed. If either or both of these mask bits are set but the specified types
are illegal, <span class="emphasis"><em>
XkbSetNames</em></span>
 returns <span class="emphasis"><em>
False</em></span>
 and does not update any of the names specified in <span class="emphasis"><em>
which</em></span>
. The specified types are illegal if <span class="emphasis"><em>
xkb</em></span>
 does not include a map component or if <span class="emphasis"><em>
first_type</em></span>
 and <span class="emphasis"><em>
num_types</em></span>
 specify types that are not defined in the keyboard description.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idp67328372"></a></h3></div></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="The_XkbNameChangesRec_Structure"></a>The XkbNameChangesRec Structure</h4></div></div></div><p>
The <span class="emphasis"><em>
XkbNameChangesRec</em></span>
 allows applications to identify small modifications to the symbolic names and
effectively reduces the amount of traffic sent to the server:
</p><pre class="programlisting">
typedef struct _XkbNameChanges {
      unsigned int      changed;            /* name components that have
                                               changed */
      unsigned char      first_type;        /* first key type with a new
                                               name */
      unsigned char      num_types;         /* number of types with new
                                               names */
      unsigned char      first_lvl;         /* first key type with new level
                                               names */
      unsigned char      num_lvls;          /* number of key types with new
                                               level names */
      unsigned char      num_aliases;       /* if key aliases changed,
                                               total number of key aliases */
      unsigned char      num_rg;            /* if radio groups changed, total
                                               number of radio groups */
      unsigned char      first_key;         /* first key with a new name */
      unsigned char      num_keys;          /* number of keys with new names
                                               */
      unsigned short      changed_vmods;    /* mask of virtual
                                               modifiers for which names have changed */
      unsigned long      changed_indicators;  /* mask of indicators
                                                 for which names were changed */
      unsigned char       changed_groups;   /* mask of groups for
                                               which names were changed */
} <span class="emphasis"><em>XkbNameChangesRec</em></span>, *XkbNameChangesPtr
</pre><p>
The <span class="emphasis"><em>
changed</em></span>
 field specifies the name components that have changed and is the bitwise
inclusive OR of the valid names mask bits defined in Table 18.1. The rest of
the fields in the structure specify the ranges that have changed for the
various kinds of symbolic names, as shown in Table 18.2.
</p><div class="table"><a id="idp67332660"></a><p class="title"><strong>Table 18.2. XkbNameChanges Fields</strong></p><div class="table-contents"><table summary="XkbNameChanges Fields" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Mask</th><th align="left">Fields</th><th align="left">Component</th><th align="left">Field</th></tr></thead><tbody><tr><td align="left">XkbKeyTypeNamesMask</td><td align="left">
<p>first_type,</p>
<p>num_types</p>
    </td><td align="left">Xkb-&gt;map</td><td align="left">type[*].name</td></tr><tr><td align="left">XkbKTLevelNamesMask</td><td align="left">
<p>first_lvl,</p>
<p>num_lvls</p>
    </td><td align="left">Xkb-&gt;map</td><td align="left">type[*].lvl_names[*]</td></tr><tr><td align="left">XkbKeyAliasesMask</td><td align="left">num_aliases</td><td align="left">Xkb-&gt;names</td><td align="left">key_aliases[*]</td></tr><tr><td align="left">XkbRGNamesMask</td><td align="left">num_rg</td><td align="left">Xkb-&gt;names</td><td align="left">radio_groups[*]</td></tr><tr><td align="left">XkbKeyNamesMask</td><td align="left">
<p>first_key,</p>
<p>num_keys</p>
    </td><td align="left">Xkb-&gt;names</td><td align="left">keys[*]</td></tr><tr><td align="left">XkbVirtualModNamesMask</td><td align="left">changed_vmods</td><td align="left">Xkb-&gt;names</td><td align="left">vmods[*]</td></tr><tr><td align="left">XkbIndicatorNamesMask</td><td align="left">changed_indicators</td><td align="left">Xkb-&gt;names</td><td align="left">indicators[*]</td></tr><tr><td align="left">XkbGroupNamesMask</td><td align="left">changed_groups</td><td align="left">Xkb-&gt;names</td><td align="left">groups[*]</td></tr></tbody></table></div></div><br class="table-break" /><p>
<span class="emphasis"><em>
XkbChangeNames</em></span>
 provides a more flexible method for changing symbolic names than <span class="emphasis"><em>
XkbSetNames</em></span>
 and requires the use of an <span class="emphasis"><em>
XkbNameChangesRec</em></span>
 structure.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbChangeNames</em></span>
(<span class="emphasis"><em>
dpy, xkb, changes</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            <span class="emphasis"><em>
dpy</em></span>
;            /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr      <span class="emphasis"><em>
      xkb</em></span>
;            /* keyboard description from which names are to be taken */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbNameChangesPtr      <span class="emphasis"><em>
      changes</em></span>
;            /* names map components to be updated on the server */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbChangeNames</em></span>
 copies any names specified by <span class="emphasis"><em>
changes</em></span>
 from the keyboard description, <span class="emphasis"><em>
xkb</em></span>
, to the X server specified by <span class="emphasis"><em>
dpy</em></span>
.<span class="emphasis"><em>
 XkbChangeNames</em></span>
 aborts and returns <span class="emphasis"><em>
False</em></span>
 if any illegal type names or type shift level names are specified by <span class="emphasis"><em>
changes</em></span>
.
</p></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Tracking_Name_Changes"></a>Tracking Name Changes</h2></div></div></div><p>
Whenever a symbolic name changes in the server’s keyboard description, the
server sends a <span class="emphasis"><em>
XkbNamesNotify</em></span>
 event to all interested clients. To receive name notify events, use <span class="emphasis"><em>
XkbSelectEvents</em></span>
 (see section 4.3) with <span class="emphasis"><em>
XkbNamesNotifyMask</em></span>
 in both the <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits</em></span>
 parameters.
</p><p>
To receive events for only specific names, use <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
. Set the <span class="emphasis"><em>
event_type</em></span>
 parameter to <span class="emphasis"><em>
XkbNamesNotify</em></span>
, and set both the <span class="emphasis"><em>
bits_to_change </em></span>
and<span class="emphasis"><em>
 values_for_bits</em></span>
 detail parameter to a mask composed of a bitwise OR of masks in Table 18.1.
</p><p>
The structure for the <span class="emphasis"><em>
XkbNamesNotify</em></span>
 event is defined as follows:
</p><pre class="programlisting">
typedef struct {
      int      type;                  /* Xkb extension base event code */
      unsigned long      serial;      /* X server serial number for
                                         event */
      Bool      send_event;           /* <span class="emphasis"><em>True</em></span>
                                         =&gt; synthetically generated */
      Display *      display;         /* server connection where event
                                         generated */
      Time      time;                 /* server time when event generated */
      int      xkb_type;              /* <span class="emphasis"><em>XkbNamesNotify</em></span> */
      int      device;                /* Xkb device ID, will not be
                                         <span class="emphasis"><em>XkbUseCoreKbd</em></span> */
      unsigned int      changed;      /* mask of name components
that have changed */
      int      first_type;            /* first key type with a new name */
      int      num_types;             /* number of types with new names */
      int      first_lvl;             /* first key type with new level names */
      int      num_lvls;              /* number of key types with new level names */
      int      num_aliases;           /* if key aliases changed, total number
                                         of key aliases */
      int      num_radio_groups;      /* if radio groups changed,
                                         total number of radio groups */
      unsigned int      changed_vmods;  /* mask of virtual modifiers for
                                           which names have changed */
      unsigned int      changed_groups; /* mask of groups for
                                           which names were changed */
      unsigned int      changed_indicators;  /* mask of indicators for which
                                                names were changed */
      int      first_key;             /* first key with a new name */
      int      num_keys;              /* number of keys with new names */
} <span class="emphasis"><em>XkbNamesNotifyEvent</em></span>;
</pre><p>
The <span class="emphasis"><em>
changed</em></span>
 field specifies the name components that have changed and is the bitwise
inclusive OR of the valid names mask bits defined in Table 18.1. The other
fields in this event are interpreted as the like-named fields in an <span class="emphasis"><em>
XkbNameChangesRec</em></span> , as previously defined.
</p><p>
When your application receives a X<span class="emphasis"><em>
kbNamesNotify</em></span>
 event, you can note the changed names in a changes structure using <span class="emphasis"><em>
XkbNoteNameChanges</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbNoteNameChanges</em></span>
(<span class="emphasis"><em>
old</em></span>
,<span class="emphasis"><em>
 new</em></span>
,<span class="emphasis"><em>
 wanted</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbNameChangesPtr            <span class="emphasis"><em>
old</em></span>
;            /* <span class="emphasis"><em>
XkbNameChanges</em></span>
 structure to be updated */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbNamesNotifyEvent *            <span class="emphasis"><em>
new</em></span>
;            /* event from which changes are to be copied */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
wanted</em></span>
;            /* types of names for which changes are to be noted */
    </td></tr></tbody></table></div><p>
The <span class="emphasis"><em>
wanted</em></span>
 parameter is the bitwise inclusive OR of the valid names mask bits shown in
Table 18.1. <span class="emphasis"><em>
XkbNoteNameChanges</em></span>
 copies any changes that are reported in <span class="emphasis"><em>
new</em></span>
 and specified in <span class="emphasis"><em>
wanted</em></span>
 into the changes record specified by <span class="emphasis"><em>
old</em></span>
.
</p><p>
To update the local copy of the keyboard description with the actual values,
pass to <span class="emphasis"><em>
XkbGetNameChanges</em></span>
 the results of one or more calls to <span class="emphasis"><em>
XkbNoteNameChanges</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetNameChanges</em></span>
(<span class="emphasis"><em>
dpy</em></span>
,<span class="emphasis"><em>
 xkb</em></span>
,<span class="emphasis"><em>
 changes</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            <span class="emphasis"><em>
dpy</em></span>
;            /* connection to the X server */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr            <span class="emphasis"><em>
xkb</em></span>
;            /* keyboard description to which names are copied */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbNameChangesPtr            <span class="emphasis"><em>
changes</em></span>
;            /* names components to be obtained from the server */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetNameChanges</em></span>
 examines the <span class="emphasis"><em>
changes</em></span>
 parameter, retrieves the necessary information from the server, and places the
results into the <span class="emphasis"><em>
xkb</em></span>
 keyboard description.
</p><p>
<span class="emphasis"><em>
XkbGetNamesChanges</em></span>
 can generate <span class="emphasis"><em>
BadAlloc</em></span>
, <span class="emphasis"><em>
BadImplementation,</em></span>
 and <span class="emphasis"><em>
BadMatch</em></span>
 errors.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Allocating_and_Freeing_Symbolic_Names"></a>Allocating and Freeing Symbolic Names</h2></div></div></div><p>
Most applications do not need to directly allocate symbolic names structures.
Do not allocate a names structure directly using <span class="emphasis"><em>
malloc</em></span>
 or <span class="emphasis"><em>
Xmalloc</em></span>
 if your application changes the number of key aliases or radio groups or
constructs a symbolic names structure without loading the necessary components
from the X server. Instead use <span class="emphasis"><em>
XkbAllocNames</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocNames</em></span>
(<span class="emphasis"><em>
xkb, which, num_rg, num_key_aliases)</em></span>
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr      <span class="emphasis"><em>
xkb;</em></span>
      /* keyboard description for which names are to be allocated */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
which;</em></span>
      /* mask of names to be allocated */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
num_rg;</em></span>
      /* total number of radio group names needed */
    </td></tr><tr><td class="functionargdecl" align="left">
int      <span class="emphasis"><em>
num_key_aliases;</em></span>
      /* total number of key aliases needed */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocNames</em></span>
 can return <span class="emphasis"><em>
BadAlloc</em></span>
, <span class="emphasis"><em>
BadMatch,</em></span>
 and <span class="emphasis"><em>
BadValue</em></span>
 errors.<span class="emphasis"><em>
 </em></span>
The <span class="emphasis"><em>
which</em></span>
 parameter is the bitwise inclusive OR of the valid names mask bits defined in
Table 18.1.
</p><p>
Do not free symbolic names structures directly using <span class="emphasis"><em>
free</em></span>
 or <span class="emphasis"><em>
XFree</em></span>
. Use <span class="emphasis"><em>
XkbFreeNames</em></span>
 instead.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeNames</em></span>
(<span class="emphasis"><em>
xkb, which, free_map)</em></span>
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDescPtr      <span class="emphasis"><em>
xkb</em></span>
;      /* keyboard description for which names are to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
which</em></span>
;      /* mask of names components to be freed */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool      <span class="emphasis"><em>
free_map</em></span>
;      /* <span class="emphasis"><em>
True</em></span>
 =&gt; XkbNamesRec structure itself should be freed */
    </td></tr></tbody></table></div><p>
The <span class="emphasis"><em>
which</em></span>
 parameter is the bitwise inclusive OR of the valid names mask bits defined in
Table 18.1.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Replacing_a_Keyboard_On_the_Fly"></a>Chapter 19. Replacing a Keyboard "On the Fly"</h1></div></div></div><p>
Some operating system and X server implementations allow "hot plugging" of
input devices. When using these implementations, input devices can be unplugged
and new ones plugged in without restarting the software that is using those
devices. There is no provision in the standard X server for notification of
client programs if input devices are unplugged and/or new ones plugged in. In
the case of the X keyboard, this could result in the X server having a keymap
that does not match the new keyboard.
</p><p>
If the X server implementation supports the X input device extension, a client
program may also change the X keyboard programmatically. The
XChangeKeyboardDevice input extension request allows a client to designate an
input extension keyboard device as the X keyboard, in which case the old X
keyboard device becomes inaccessible except via the input device extension. In
this case, core protocol <span class="emphasis"><em>
XMappingNotify</em></span>
 and input extension <span class="emphasis"><em>
XChangeDeviceNotify</em></span>
 events are generated to notify all clients that a new keyboard with a new
keymap has been designated.
</p><p>
When a client opens a connection to the X server, the server reports the
minimum and maximum keycodes. The server keeps track of the minimum and maximum
keycodes last reported to each client. When delivering events to a particular
client, the server filters out any events that fall outside of the valid range
for the client.
</p><p>
Xkb provides an <span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
 event that reports a change in keyboard geometry and/or the range of supported
keycodes. The server can generate an <span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
 event when it detects a new keyboard or in response to an <span class="emphasis"><em>
XkbGetKeyboardByName</em></span>
 request that loads a new keyboard description. Selecting for <span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
 events allows Xkb-aware clients to be notified whenever a keyboard change
occurs that may affect the keymap.
</p><p>
When a client requests <span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
 events, the server compares the range of keycodes for the current keyboard to
the range of keycodes that are valid for the client. If they are not the same,
the server immediately sends the client an <span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
 event. Even if the "new" keyboard is not new to the server, it is new to this
particular client.
</p><p>
When the server sends an <span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
 event to a client to inform it of a new keycode range, it resets the stored
range of legal keycodes for the client to the keycode range reported in the
event; it does not reset this range for the client if it does not sent an
<span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
 event to a client. Because Xkb-unaware clients and Xkb-aware clients that do
not request <span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
 events are never sent these events, the server’s notion of the legal keycode
range never changes, and these clients never receive events from keys that fall
outside of their notion of the legal keycode range.
</p><p>
Clients that have not selected to receive <span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
 events do, however, receive the <span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
 event when a keyboard change occurs. Clients that have not selected to receive
this event also receive numerous other events detailing the individual changes
that occur when a keyboard change occurs.
</p><p>
Clients wishing to track changes in <span class="emphasis"><em>
min_key_code</em></span>
 and <span class="emphasis"><em>
max_key_code</em></span>
 must watch for both <span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
 and <span class="emphasis"><em>
XkbMapNotify</em></span>
 events, because a simple mapping change causes an <span class="emphasis"><em>
XkbMapNotify</em></span>
 event and may change the range of valid keycodes, but does not cause an
<span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
 event. If a client does not select for <span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
 events, the server restricts the range of keycodes reported to the client.
</p><p>
In addition to filtering out-of-range key events, Xkb:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Adjusts core protocol <span class="emphasis"><em>
MappingNotify</em></span>
 events to refer only to keys that match the stored legal range.
  </p></li><li class="listitem"><p>
Reports keyboard mappings for keys that match the stored legal range to clients
that issue a core protocol <span class="emphasis"><em>
GetKeyboardMapping</em></span>
 request.
  </p></li><li class="listitem"><p>
Reports modifier mappings only for keys that match the stored legal range to
clients that issue a core protocol <span class="emphasis"><em>
GetModifierMapping</em></span>
 request.
  </p></li><li class="listitem"><p>
Restricts the core protocol <span class="emphasis"><em>
ChangeKeyboardMapping</em></span>
 and <span class="emphasis"><em>
SetModifierMapping</em></span>
 requests to keys that fall inside the stored legal range.
  </p></li></ul></div><p>
In short, Xkb does everything possible to hide from Xkb-unaware clients the
fact that the range of legal keycodes has changed, because such clients cannot
be expected to deal with them. Xkb events and requests are not modified in this
manner; all Xkb events report the full range of legal keycodes. No requested
Xkb events are discarded, and no Xkb requests have their keycode range clamped.
</p><p>
The structure for the <span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
 event is defined as follows:
</p><pre class="programlisting">
typedef struct _XkbNewKeyboardNotify {
      int            type;         /* Xkb extension base event code */
      unsigned long  serial;       /* X server serial number for event*/
      Bool           send_event;   /* <span class="emphasis"><em>True</em></span>
                                      =&gt; synthetically generated */
      Display *      display;      /* server connection where event generated */
      Time           time;         /* server time when event generated */
      int            xkb_type;  /* <span class="emphasis"><em>XkbNewKeyboardNotify</em></span> */
      int            device;       /* device ID of new keyboard */
      int            old_device;   /* device ID of old keyboard */
      int            min_key_code; /* min keycode of new keyboard */
      int            max_key_code; /* max keycode of new keyboard */
      int            old_min_key_code; /* min keycode of old keyboard */
      int            old_max_key_code; /* max keycode of old keyboard */
      unsigned int            changed; /* changed aspects - see masks below */
      char            req_major;   /* major request that caused change */
      char            req_minor;   /* minor request that caused change */
} <span class="emphasis"><em>XkbNewKeyboardNotifyEvent</em></span>;
</pre><p>
To receive name notify events, use <span class="emphasis"><em>
XkbSelectEvents</em></span>
 (see section 4.3) with <span class="emphasis"><em>
XkbNewKeyboardNotifyMask</em></span>
 in both the <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits</em></span>
 parameters. To receive events for only specific names, use <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
. Set the <span class="emphasis"><em>
event_type</em></span>
 parameter to <span class="emphasis"><em>
XkbNewKeyboardNotify</em></span>
, and set both the <span class="emphasis"><em>
bits_to_change </em></span>
and<span class="emphasis"><em>
 values_for_bits</em></span>
 detail parameter to a mask composed of a bitwise OR of masks in Table 19.1.
</p><div class="table"><a id="idp65470660"></a><p class="title"><strong>Table 19.1. XkbNewKeyboardNotifyEvent Details</strong></p><div class="table-contents"><table summary="XkbNewKeyboardNotifyEvent Details" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">XkbNewKeyboardNotify Event Details</th><th align="left">Value</th><th align="left">Circumstances</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>XkbNKN_KeycodesMask</em></span></td><td align="left">(1L&lt;&lt;0)</td><td align="left">Notification of keycode range changes wanted</td></tr><tr><td align="left"><span class="emphasis"><em>XkbNKN_GeometryMask</em></span></td><td align="left">(1L&lt;&lt;1)</td><td align="left">Notification of geometry changes wanted</td></tr><tr><td align="left">XkbNKN_DeviceIDMask</td><td align="left">(1L&lt;&lt;2)</td><td align="left">Notification of device ID changes wanted</td></tr><tr><td align="left"><span class="emphasis"><em>XkbNKN_AllChangesMask</em></span></td><td align="left">(0x7)</td><td align="left">Includes all of the above masks</td></tr></tbody></table></div></div><br class="table-break" /><p>
The <span class="emphasis"><em>
req_major</em></span>
 and <span class="emphasis"><em>
req_minor</em></span>
 fields indicate what type of keyboard change has occurred.
</p><p>
If <span class="emphasis"><em>
req_major</em></span>
 and <span class="emphasis"><em>
req_minor</em></span>
 are zero, the device change was not caused by a software request to the server
— a spontaneous change has occurred, such as hot-plugging a new device. In
this case, <span class="emphasis"><em>
device</em></span>
 is the device identifier for the new, current X keyboard device, but no
implementation-independent guarantee can be made about <span class="emphasis"><em>
old_device</em></span>
. <span class="emphasis"><em>
old_device</em></span>
 may be identical to <span class="emphasis"><em>
device</em></span>
 (an implementor is permitted to reuse the device specifier when the device
changes); or it may be different. Note that <span class="emphasis"><em>
req_major</em></span>
 and <span class="emphasis"><em>
req_minor</em></span>
 being zero do not necessarily mean that the physical keyboard device has
changed; rather, they only imply a spontaneous change outside of software
control (some systems have keyboards that can change personality at the press
of a key).
</p><p>
If the keyboard change is the result of an X Input Extension <span class="emphasis"><em>
ChangeKeyboardDevice</em></span>
 request, <span class="emphasis"><em>
req_major</em></span>
 contains the input extension major opcode, and <span class="emphasis"><em>
req_minor</em></span>
 contains the input extension request number for <span class="emphasis"><em>
X_ChangeKeyboardDevice</em></span>
. In this case, <span class="emphasis"><em>
device</em></span>
 and <span class="emphasis"><em>
old_device</em></span>
 are different, with <span class="emphasis"><em>
device</em></span>
 being the identifier for the new, current X keyboard device, and <span class="emphasis"><em>
old_device</em></span>
 being the identifier for the former device.
</p><p>
If the keyboard change is the result of an <span class="emphasis"><em>
XkbGetKeyboardByName</em></span>
 function call, which generates an <span class="emphasis"><em>
X_kbGetKbdByName</em></span>
 request, <span class="emphasis"><em>
req_major</em></span>
 contains the Xkb extension base event code (see section 2.4), and <span class="emphasis"><em>
req_minor</em></span>
 contains the event code for the Xkb extension request <span class="emphasis"><em>
X_kbGetKbdByName</em></span>
. <span class="emphasis"><em>
device</em></span>
 contains the device identifier for the new device, but nothing definitive can
be said for <span class="emphasis"><em>
old_device</em></span>
; it may be identical to <span class="emphasis"><em>
device</em></span>
, or it may be different, depending on the implementation.
</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Server_Database_of_Keyboard_Components"></a>Chapter 20. Server Database of Keyboard Components</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Component_Names">Component Names</a></span></dt><dt><span class="sect1"><a href="#Listing_the_Known_Keyboard_Components">Listing the Known Keyboard Components</a></span></dt><dt><span class="sect1"><a href="#Component_Hints">Component Hints</a></span></dt><dt><span class="sect1"><a href="#Building_a_Keyboard_Description_Using_the_Server_Database">Building a Keyboard Description Using the Server Database</a></span></dt></dl></div><p>
The X server maintains a database of keyboard components, identified by
component type. The database contains all the information necessary to build a
complete keyboard description for a particular device, as well as to assemble
partial descriptions. Table 20.1 identifies the component types and the type of
information they contain.
</p><div class="table"><a id="idp62892988"></a><p class="title"><strong>Table 20.1. Server Database Keyboard Components</strong></p><div class="table-contents"><table summary="Server Database Keyboard Components" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">Component Type</th><th align="left">Component Primary Contents</th><th align="left">May also contain</th></tr></thead><tbody><tr><td align="left">Keymap</td><td align="left">
<p>Complete keyboard description</p>
<p>Normally assembled using a complete component from each of the other types</p>
    </td><td align="left"> </td></tr><tr><td align="left">Keycodes</td><td align="left">
<p>Symbolic name for each key</p>
<p>Minimum and maximum legal keycodes</p>
    </td><td align="left">
<p>Aliases for some keys</p>
<p>Symbolic names for indicators</p>
<p>Description of indicators physically present</p>
    </td></tr><tr><td align="left">Types</td><td align="left">Key types</td><td align="left">
Real modifier bindings and symbolic names for some virtual modifiers
    </td></tr><tr><td align="left">Compatibility</td><td align="left">Rules used to assign actions to keysyms</td><td align="left">
<p>Maps for some indicators</p>
<p>Real modifier bindings and symbolic names for some virtual modifiers</p>
    </td></tr><tr><td align="left">Symbols</td><td align="left">
<p>Symbol mapping for keyboard keys</p>
<p>Modifier mapping</p>
<p>Symbolic names for groups</p>
    </td><td align="left">
<p>Explicit actions and behaviors for some keys</p>
<p>Real modifier bindings and symbolic names for some virtual modifiers</p>
    </td></tr><tr><td align="left">Geometry</td><td align="left">Layout of the keyboard</td><td align="left">
<p>Aliases for some keys; overrides keycodes component aliases</p>
<p>Symbolic names for some indicators</p>
<p>Description of indicators physically present</p>
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
While a keymap is a database entry for a complete keyboard description, and
therefore logically different from the individual component database entries,
the rules for processing keymap entries are identical to those for the
individual components. In the discussion that follows, the term component is
used to refer to either individual components or a keymap.
</p><p>
There may be multiple entries for each of the component types. An entry may be
either <span class="emphasis"><em>
complete</em></span>
 or <span class="emphasis"><em>
partial</em></span>
. Partial entries describe only a piece of the corresponding keyboard component
and are designed to be combined with other entries of the same type to form a
complete entry.
</p><p>
For example, a partial symbols map might describe the differences between a
common ASCII keyboard and some national layout. Such a partial map is not
useful on its own because it does not include those symbols that are the same
on both the ASCII and national layouts (such as function keys). On the other
hand, this partial map can be used to configure <span class="emphasis"><em>
any</em></span>
 ASCII keyboard to use a national layout.
</p><p>
When a keyboard description is built, the components are processed in the order
in which they appear in Table 20.1; later definitions override earlier ones.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Component_Names"></a>Component Names</h2></div></div></div><p>
Component names have the form "<span class="emphasis"><em>
class(member)</em></span>
" where <span class="emphasis"><em>
class</em></span>
 describes a subset of the available components for a particular type and the
optional <span class="emphasis"><em>
member</em></span>
 identifies a specific component from that subset. For example, the name
"atlantis(acme)" for a symbols component might specify the symbols used for the
atlantis national keyboard layout by the vendor "acme." Each class has an
optional <span class="emphasis"><em>
default</em></span>
 member — references that specify a class but not a member refer to the
default member of the class, if one exists. Xkb places no constraints on the
interpretation of the class and member names used in component names.
</p><p>
The <span class="emphasis"><em>
class</em></span>
 and <span class="emphasis"><em>
member</em></span>
 names are both specified using characters from the Latin-1 character set. Xkb
implementations must accept all alphanumeric characters, minus (‘-’) and
underscore (‘_’) in class or member names, and must not accept parentheses,
plus, vertical bar, percent sign, asterisk, question mark, or white space. The
use of other characters is implementation-dependent.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Listing_the_Known_Keyboard_Components"></a>Listing the Known Keyboard Components</h2></div></div></div><p>
You may ask the server for a list of components for one or more component
types. The request takes the form of a set of patterns, one pattern for each of
the component types, including a pattern for the complete keyboard description.
To obtain this list, use <span class="emphasis"><em>
XkbListComponents</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbComponentListPtr<span class="emphasis"><em>
 XkbListComponents</em></span>
(<span class="emphasis"><em>
dpy</em></span>
, <span class="emphasis"><em>
device_spec</em></span>
, <span class="emphasis"><em>
ptrns</em></span>
, <span class="emphasis"><em>
max_inout</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
            dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int                  <span class="emphasis"><em>
device_spec</em></span>
;            /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbComponentNamesPtr                  <span class="emphasis"><em>
ptrns</em></span>
;            /* namelist for components of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
int *                  <span class="emphasis"><em>
max_inout</em></span>
;            /* max # returned names, # left over */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbListComponents</em></span>
 queries the server for a list of component names matching the patterns
specified in <span class="emphasis"><em>
ptrns</em></span>
. It waits for a reply and returns the matching component names in an <span class="emphasis"><em>
XkbComponentListRec</em></span>
 structure. When you are done using the structure, you should free it using
<span class="emphasis"><em>
XkbFreeComponentList</em></span>
. <span class="emphasis"><em>
device_spec</em></span>
 indicates a particular device in which the caller is interested. A server is
allowed (but not required) to restrict its reply to portions of the database
that are relevant for that particular device.
</p><p>
<span class="emphasis"><em>
ptrns</em></span>
 is a pointer to an <span class="emphasis"><em>
XkbComponentNamesRec</em></span>
, described below. Each of the fields in <span class="emphasis"><em>
ptrns</em></span>
 contains a pattern naming the components of interest. Each of the patterns is
composed of characters from the ISO <span class="emphasis"><em>
Latin1</em></span>
 encoding, but can contain only parentheses, the wildcard characters
‘<span class="emphasis"><em>
?</em></span>
’ and ‘<span class="emphasis"><em>
*</em></span>
’, and characters permitted in a component class or member name (see section
20.1). A pattern may be <span class="emphasis"><em>
NULL</em></span>
, in which case no components for that type is returned. Pattern matches with
component names are case sensitive. The ‘<span class="emphasis"><em>
?</em></span>
’ wildcard matches any single character, except a left or right parenthesis;
the ‘<span class="emphasis"><em>
*</em></span>
’ wildcard matches any number of characters, except a left or right
parenthesis. If an implementation allows additional characters in a component
class or member name other than those required by the Xkb extension (see
section 20.1), the result of comparing one of the additional characters to
either of the wildcard characters is implementation-dependent.
</p><p>
If a pattern contains illegal characters, the illegal characters are ignored.
The matching process is carried out as if the illegal characters were omitted
from the pattern.
</p><p>
<span class="emphasis"><em>
max_inout</em></span>
 is used to throttle the amount of data passed to and from the server. On
input, it specifies the maximum number of names to be returned (the total
number of names in all component categories). Upon return from <span class="emphasis"><em>
XkbListComponents</em></span>
, <span class="emphasis"><em>
max_inout</em></span>
 contains the number of names that matched the request but were not returned
because of the limit.
</p><p>
The component name patterns used to describe the request are passed to
<span class="emphasis"><em>
XkbListComponents</em></span>
 using an <span class="emphasis"><em>
XkbComponentNamesRec</em></span>
 structure. This structure has no special allocation constraints or
interrelationships with other structures; allocate and free this structure
using standard <span class="emphasis"><em>
malloc</em></span>
 and <span class="emphasis"><em>
free</em></span>
 calls or their equivalent:
</p><pre class="programlisting">
typedef struct _XkbComponentNames {
      char *       keymap;    /* keymap names */
      char *       keycodes;  /* keycode names */
      char *       types;     /* type names */
      char *       compat;    /* compatibility map names */
      char *       symbols;   /* symbol names */
      char *       geometry;  /* geometry names */
} <span class="emphasis"><em>XkbComponentNamesRec</em></span>, *XkbComponentNamesPtr;
</pre><p>
<span class="emphasis"><em>
XkbListComponents</em></span>
 returns a pointer to an <span class="emphasis"><em>
XkbComponentListRec</em></span>
:
</p><pre class="programlisting">
typedef struct _XkbComponentList {
      int                  num_keymaps;     /* number of entries in keymap */
      int                  num_keycodes;    /* number of entries in keycodes */
      int                  num_types;       /* number of entries in types */
      int                  num_compat;      /* number of entries in compat */
      int                  num_symbols;     /* number of entries in symbols */
      int                  num_geometry;    /* number of entries in geometry;
      XkbComponentNamePtr  keymap;          /* keymap names */
      XkbComponentNamePtr  keycodes;        /* keycode names */
      XkbComponentNamePtr  types;           /* type names */
      XkbComponentNamePtr  compat;          /* compatibility map names */
      XkbComponentNamePtr  symbols;         /* symbol names */
      XkbComponentNamePtr  geometry;        /* geometry names */
} <span class="emphasis"><em>XkbComponentListRec</em></span>, *XkbComponentListPtr;
</pre><pre class="programlisting">
typedef struct _XkbComponentName {
      unsigned short         flags;     /* hints regarding component name */
      char *                 name;      /* name of component */
} <span class="emphasis"><em>XkbComponentNameRec</em></span>, *XkbComponentNamePtr;
</pre><p>
Note that the structure used to specify patterns on input is an <span class="emphasis"><em>
XkbComponentNamesRec</em></span>
, and that used to hold the individual component names upon return is an
<span class="emphasis"><em>
XkbComponentNameRec</em></span>
 (no trailing ‘s’ in Name).
</p><p>
When you are done using the structure returned by <span class="emphasis"><em>
XkbListComponents</em></span>
, free it using <span class="emphasis"><em>
XkbFreeComponentList</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeComponentList</em></span>
(list)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbComponentListPtr                   list;      /* pointer to <span class="emphasis"><em>
XkbComponentListRec</em></span>
 to free */
    </td></tr></tbody></table></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Component_Hints"></a>Component Hints</h2></div></div></div><p>
A set of flags is associated with each component; these flags provide
additional hints about the component’s use. These hints are designated by bit
masks in the flags field of the <span class="emphasis"><em>
XkbComponentNameRec</em></span>
 structures contained in the <span class="emphasis"><em>
XkbComponentListRec</em></span>
 returned from <span class="emphasis"><em>
XkbListComponents</em></span>
. The least significant byte of the flags field has the same meaning for all
types of keyboard components; the interpretation of the most significant byte
is dependent on the type of component. The flags bits are defined in Table
20.2. The symbols hints in Table 20.2 apply only to partial symbols components
(those with <span class="emphasis"><em>
XkbLC_Partial</em></span>
 also set); full symbols components are assumed to specify all of the pieces.
</p><p>
The alphanumeric, modifier, keypad or function keys symbols hints should
describe the primary intent of the component designer and should not be simply
an exhaustive list of the kinds of keys that are affected. For example,
national keyboard layouts affect primarily alphanumeric keys, but many affect a
few modifier keys as well; such mappings should set only the <span class="emphasis"><em>
XkbLC_AlphanumericKeys</em></span>
 hint. In general, symbols components should set only one of the four flags
(<span class="emphasis"><em>
XkbLC_AlternateGroup</em></span>
 may be combined with any of the other flags).
</p><div class="table"><a id="idp68062900"></a><p class="title"><strong>Table 20.2. XkbComponentNameRec Flags Bits</strong></p><div class="table-contents"><table summary="XkbComponentNameRec Flags Bits" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Component Type</th><th align="left">Component Hints (flags)</th><th align="left">Meaning</th><th align="left">Value</th></tr></thead><tbody><tr><td align="left">All Components</td><td align="left"><p><span class="emphasis"><em>XkbLC_Hidden</em></span></p></td><td align="left">Do not present to user</td><td align="left">(1L&lt;&lt;0)</td></tr><tr><td align="left"> </td><td align="left"><span class="emphasis"><em>XkbLC_Default</em></span></td><td align="left">Default member of class</td><td align="left">(1L&lt;&lt;1)</td></tr><tr><td align="left"> </td><td align="left"><span class="emphasis"><em>XkbLC_Partial</em></span></td><td align="left">Partial component</td><td align="left">(1L&lt;&lt;2)</td></tr><tr><td align="left">Keymap</td><td align="left">none</td><td align="left"> </td><td align="left"> </td></tr><tr><td align="left">Keycodes</td><td align="left">none</td><td align="left"> </td><td align="left"> </td></tr><tr><td align="left">Types</td><td align="left">none</td><td align="left"> </td><td align="left"> </td></tr><tr><td align="left">Compatibility</td><td align="left">none</td><td align="left"> </td><td align="left"> </td></tr><tr><td align="left">Symbols</td><td align="left"><span class="emphasis"><em>XkbLC_AlphanumericKeys</em></span></td><td align="left">Bindings primarily for alphanumeric keyboard section</td><td align="left">(1L&lt;&lt;8)</td></tr><tr><td align="left"> </td><td align="left"><span class="emphasis"><em>XkbLC_ModifierKeys</em></span></td><td align="left">Bindings primarily for modifier keys</td><td align="left">(1L&lt;&lt;9)</td></tr><tr><td align="left"> </td><td align="left"><span class="emphasis"><em>XkbLC_KeypadKeys</em></span></td><td align="left">Bindings primarily for numeric keypad keys</td><td align="left">(1L&lt;&lt;10)</td></tr><tr><td align="left"> </td><td align="left"><span class="emphasis"><em>XkbLC_FunctionKeys</em></span></td><td align="left">Bindings primarily for function keys</td><td align="left">(1L&lt;&lt;11)</td></tr><tr><td align="left"> </td><td align="left"><span class="emphasis"><em>XkbLC_AlternateGroup</em></span></td><td align="left">Bindings for an alternate group</td><td align="left">(1L&lt;&lt;12)</td></tr><tr><td align="left">Geometry</td><td align="left">none</td><td align="left"> </td><td align="left"> </td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Building_a_Keyboard_Description_Using_the_Server_Database"></a>Building a Keyboard Description Using the Server Database</h2></div></div></div><p>
A client may request that the server fetch one or more components from its
database and use those components to build a new server keyboard description.
The new keyboard description may be built from scratch, or it may be built
starting with the current keyboard description for a particular device. Once
the keyboard description is built, all or part of it may be returned to the
client. The parts returned to the client need not include all of the parts used
to build the description. At the time it requests the server to build a new
keyboard description, a client may also request that the server use the new
description internally to replace the current keyboard description for a
specific device, in which case the behavior of the device changes accordingly.
</p><p>
To build a new keyboard description from a set of named components, and to
optionally have the server use the resulting description to replace an active
one, use <span class="emphasis"><em>
XkbGetKeyboardByName</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbDescPtr <span class="emphasis"><em>
XkbGetKeyboardByName</em></span>
(<span class="emphasis"><em>
dpy</em></span>
, <span class="emphasis"><em>
device_spec</em></span>
, <span class="emphasis"><em>
names</em></span>
, <span class="emphasis"><em>
want</em></span>
, <span class="emphasis"><em>
need</em></span>
, <span class="emphasis"><em>
load</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
            dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int                  <span class="emphasis"><em>
device_spec</em></span>
;            /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbComponentNamesPtr                  <span class="emphasis"><em>
names</em></span>
;            /* names of components to fetch */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int                  <span class="emphasis"><em>
want</em></span>
;            /* desired structures in returned record */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int                  <span class="emphasis"><em>
need</em></span>
;            /* mandatory structures in returned record */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool                  <span class="emphasis"><em>
load</em></span>
;            /* <span class="emphasis"><em>
True</em></span>
 =&gt; load into <span class="emphasis"><em>
device_spec</em></span>
 */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
names</em></span>
 contains a set of expressions describing the keyboard components the server
should use to build the new keyboard description. <span class="emphasis"><em>
want</em></span>
 and <span class="emphasis"><em>
need</em></span>
 are bit fields describing the parts of the resulting keyboard description that
should be present in the returned <span class="emphasis"><em>
XkbDescRec</em></span>
.
</p><p>
The individual fields in <span class="emphasis"><em>
names</em></span>
 are <span class="emphasis"><em>
component expressions</em></span>
 composed of keyboard component names (no wildcarding as may be used in
<span class="emphasis"><em>
XkbListComponents</em></span>
), the special component name symbol ‘%’, and the special operator
characters ‘<span class="emphasis"><em>
+</em></span>
’ and ‘<span class="emphasis"><em>
|</em></span>
’. A component expression is parsed left to right, as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The special component name "<span class="emphasis"><em>
computed</em></span>
" may be used in <span class="emphasis"><em>
keycodes</em></span>
 component expressions and refers to a component consisting of a set of
keycodes computed automatically by the server as needed.
  </p></li><li class="listitem"><p>
The special component name "<span class="emphasis"><em>
canonical</em></span>
" may be used in <span class="emphasis"><em>
types</em></span>
 component expressions and refers to a partial component defining the four
standard key types: <span class="emphasis"><em>
ALPHABETIC</em></span>
, <span class="emphasis"><em>
ONE_LEVEL</em></span>
, <span class="emphasis"><em>
TWO_LEVEL</em></span>
, and <span class="emphasis"><em>
KEYPAD</em></span>
.
  </p></li><li class="listitem"><p>
The special component name ‘<span class="emphasis"><em>
%</em></span>
’ refers to the keyboard description for the device specified in <span class="emphasis"><em>
device_spec</em></span>
 or the keymap names component. If a keymap names component is specified that
does not begin with ‘+’ or ‘|’ and does not contain ‘<span class="emphasis"><em>
%</em></span>
’, then ‘<span class="emphasis"><em>
%</em></span>
’ refers to the description generated by the keymap names component.
Otherwise, it refers to the keyboard description for <span class="emphasis"><em>
device_spec</em></span>
.
  </p></li><li class="listitem"><p>
The ‘<span class="emphasis"><em>
+</em></span>
’ operator specifies that the following component should <span class="emphasis"><em>
override</em></span>
 the currently assembled description; any definitions that are present in both
components are taken from the second.
  </p></li><li class="listitem"><p>
The ‘<span class="emphasis"><em>
|</em></span>
’ operator specifies that the next specified component should <span class="emphasis"><em>
augment</em></span>
 the currently assembled description; any definitions that are present in both
components are taken from the first.
  </p></li><li class="listitem"><p>
If the component expression begins with an operator, a leading ‘<span class="emphasis"><em>
%</em></span>
’ is implied.
  </p></li><li class="listitem"><p>
If any unknown or illegal characters appear anywhere in the expression, the
entire expression is invalid and is ignored.
  </p></li></ul></div><p>
For example, if <span class="emphasis"><em>
names-&gt;symbols</em></span>
 contained the expression "+de", it specifies that the default member of the
"de" class of symbols should be applied to the current keyboard mapping,
overriding any existing definitions (it could also be written "+de(default)").
</p><p>
Here is a slightly more involved example: the expression
"acme(ascii)+de(basic)|iso9995-3" constructs a German (de) mapping for the
ASCII keyboard supplied by the "acme" vendor. The new definition begins with
the symbols for the ASCII keyboard for Acme (<span class="emphasis"><em>
acme(ascii)</em></span>
), overrides them with definitions for the basic German keyboard (<span class="emphasis"><em>
de(basic)</em></span>
), and then applies the definitions from the default iso9995-3 keyboard
(<span class="emphasis"><em>
iso9995-3</em></span>
) to any undefined keys or groups of keys (part three of the iso9995 standard
defines a common set of bindings for the secondary group, but allows national
layouts to override those definitions where necessary).
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The interpretation of the above expression components (acme, ascii,
de, basic, iso9995-3) is not defined by Xkb; only the operations and their
ordering are.</p></div><p>
Note that the presence of a keymap <span class="emphasis"><em>
names</em></span>
 component that does not contain ‘<span class="emphasis"><em>
%</em></span>
’ (either explicit or implied by virtue of an expression starting with an
operator) indicates a description that is independent of the keyboard
description for the device specified in <span class="emphasis"><em>
device_spec</em></span>
. The same is true of requests in which the keymap names component is empty and
all five other names components contain expressions void of references to
‘<span class="emphasis"><em>
%</em></span>
’. Requests of this form allow you to deal with keyboard definitions
independent of any actual device.
</p><p>
The server parses all non-<span class="emphasis"><em>
NULL</em></span>
 fields in <span class="emphasis"><em>
names</em></span>
 and uses them to build a keyboard description. However, before parsing the
expressions in <span class="emphasis"><em>
names</em></span>
, the server ORs the bits in <span class="emphasis"><em>
want</em></span>
 and <span class="emphasis"><em>
need</em></span>
 together and examines the result in relationship to the expressions in
<span class="emphasis"><em>
names</em></span>
. Table 20.3 identifies the components that are required for each of the
possible bits in <span class="emphasis"><em>
want</em></span>
 or <span class="emphasis"><em>
need</em></span>
. If a required component has not been specified in the <span class="emphasis"><em>
names</em></span>
 structure (the corresponding field is <span class="emphasis"><em>
NULL</em></span>
), the server substitutes the expression "<span class="emphasis"><em>
%</em></span>
", resulting in the component values being taken from <span class="emphasis"><em>
device_spec</em></span>
. In addition, if <span class="emphasis"><em>
load</em></span>
 is <span class="emphasis"><em>
True</em></span>
, the server modifies <span class="emphasis"><em>
names</em></span>
 if necessary (again using a "<span class="emphasis"><em>
%</em></span>
" entry) to ensure all of the following fields are non-<span class="emphasis"><em>
NULL</em></span>
: <span class="emphasis"><em>
types</em></span>
, <span class="emphasis"><em>
keycodes</em></span>
, <span class="emphasis"><em>
symbols</em></span>
, and <span class="emphasis"><em>
compat</em></span>
.<span class="emphasis"><em>
</em></span>
</p><div class="table"><a id="idp68115804"></a><p class="title"><strong>Table 20.3. Want and Need Mask Bits and Required Names Components</strong></p><div class="table-contents"><table summary="Want and Need Mask Bits and Required Names Components" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">want or need mask bit</th><th align="left">Required names Components</th><th align="left">value</th></tr></thead><tbody><tr><td align="left">XkbGBN_TypesMask</td><td align="left">Types</td><td align="left">(1L&lt;&lt;0)</td></tr><tr><td align="left">XkbGBN_CompatMapMask</td><td align="left">Compat</td><td align="left">(1L&lt;&lt;1)</td></tr><tr><td align="left">XkbGBN_ClientSymbolsMask</td><td align="left">Types + Symbols + Keycodes</td><td align="left">(1L&lt;&lt;2)</td></tr><tr><td align="left">XkbGBN_ServerSymbolsMask</td><td align="left">Types + Symbols + Keycodes</td><td align="left">(1L&lt;&lt;3)</td></tr><tr><td align="left">XkbGBN_SymbolsMask</td><td align="left">Symbols</td><td align="left">(1L&lt;&lt;1)</td></tr><tr><td align="left">XkbGBN_IndicatorMapMask</td><td align="left">Compat</td><td align="left">(1L&lt;&lt;4)</td></tr><tr><td align="left">XkbGBN_KeyNamesMask</td><td align="left">Keycodes</td><td align="left">(1L&lt;&lt;5)</td></tr><tr><td align="left">XkbGBN_GeometryMask</td><td align="left">Geometry</td><td align="left">(1L&lt;&lt;6)</td></tr><tr><td align="left">XkbGBN_OtherNamesMask</td><td align="left">Types + Symbols + Keycodes + Compat + Geometry</td><td align="left">(1L&lt;&lt;7)</td></tr><tr><td align="left">XkbGBN_AllComponentsMask</td><td align="left"> </td><td align="left">(0xff)</td></tr></tbody></table></div></div><br class="table-break" /><p>
<span class="emphasis"><em>
need</em></span>
 specifies a set of keyboard components that the server must be able to resolve
in order for <span class="emphasis"><em>
XkbGetKeyboardByName</em></span>
 to succeed; if any of the components specified in <span class="emphasis"><em>
need</em></span>
 cannot be successfully resolved, <span class="emphasis"><em>
XkbGetKeyboardByName</em></span>
 fails.
</p><p>
<span class="emphasis"><em>
want</em></span>
 specifies a set of keyboard components that the server should attempt to
resolve, but that are not mandatory. If the server is unable to resolve any of
these components, <span class="emphasis"><em>
XkbGetKeyboardByName</em></span>
 still succeeds. Bits specified in <span class="emphasis"><em>
want</em></span>
 that are also specified in <span class="emphasis"><em>
need</em></span>
 have no effect in the context of <span class="emphasis"><em>
want</em></span>
.
</p><p>
If <span class="emphasis"><em>
load</em></span>
 is <span class="emphasis"><em>
True</em></span>
, the server updates its keyboard description for <span class="emphasis"><em>
device_spec</em></span>
 to match the result of the keyboard description just built. If load is
<span class="emphasis"><em>
False</em></span>
, the server’s description for device <span class="emphasis"><em>
device_spec</em></span>
 is not updated. In all cases, the parts specified by <span class="emphasis"><em>
want</em></span>
 and <span class="emphasis"><em>
need</em></span>
 from the just-built keyboard description are returned.
</p><p>
The <span class="emphasis"><em>
names</em></span>
 structure in an <span class="emphasis"><em>
XkbDescRec</em></span>
 keyboard description record (see Chapter 18) contains one field for each of
the five component types used to build a keyboard description. When a keyboard
description is built from a set of database components, the corresponding
fields in this <span class="emphasis"><em>
names</em></span>
 structure are set to match the expressions used to build the component.
</p><p>
The entire process of building a new keyboard description from the server
database of components and returning all or part of it is diagrammed in Figure
20.1:
</p><div class="mediaobject"><object type="image/svg+xml" data="XKBlib-21.svg"></object><div class="caption">Building a New Keyboard Description from the Server Database</div></div><p>
The information returned to the client in the <span class="emphasis"><em>
XkbDescRec</em></span>
 is essentially the result of a series of calls to extract information from a
fictitious device whose description matches the one just built. The calls
corresponding to each of the mask bits are summarized in Table 20.4, together
with the <span class="emphasis"><em>
XkbDescRec</em></span>
 components that are filled in.
</p><div class="table"><a id="idp68137884"></a><p class="title"><strong>Table 20.4. XkbDescRec Components Returned for Values of Want &amp; Needs</strong></p><div class="table-contents"><table summary="XkbDescRec Components Returned for Values of Want &amp; Needs" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">Request (want+need)</th><th align="left">Fills in Xkb components</th><th align="left">Equivalent Function Call</th></tr></thead><tbody><tr><td align="left">XkbGBN_TypesMask</td><td align="left">map.types</td><td align="left">XkbGetUpdatedMap(dpy, XkbTypesMask, Xkb)</td></tr><tr><td align="left">XkbGBN_ServerSymbolsMask</td><td align="left">server</td><td align="left">XkbGetUpdatedMap(dpy, XkbAllClientInfoMask, Xkb)</td></tr><tr><td align="left">XkbGBN_ClientSymbolsMask</td><td align="left">map, including map.types</td><td align="left">XkbGetUpdatedMap(dpy, XkbAllServerInfoMask, Xkb)</td></tr><tr><td align="left">XkbGBN_IndicatorMaps</td><td align="left">indicators</td><td align="left">XkbGetIndicatorMap(dpy, XkbAllIndicators, Xkb)</td></tr><tr><td align="left">XkbGBN_CompatMapMask</td><td align="left">compat</td><td align="left">XkbGetCompatMap(dpy, XkbAllCompatMask, Xkb)</td></tr><tr><td align="left">XkbGBN_GeometryMask</td><td align="left">geom</td><td align="left">XkbGetGeometry(dpy, Xkb)</td></tr><tr><td align="left">XkbGBN_KeyNamesMask</td><td align="left">
<p>names.keys</p>
<p>names.key_aliases</p>
    </td><td align="left">
XkbGetNames(dpy, XkbKeyNamesMask | XkbKeyAliasesMask, Xkb)
    </td></tr><tr><td align="left">XkbGBN_OtherNamesMask</td><td align="left">
<p>names.keycodes</p>
<p>names.geometry</p>
<p>names.symbols</p>
<p>names.types</p>
<p>map.types[*].lvl_names[*]</p>
<p>names.compat</p>
<p>names.vmods</p>
<p>names.indicators</p>
<p>names.groups</p>
<p>names.radio_groups</p>
<p>names.phys_symbols</p>
    </td><td align="left">
<p>XkbGetNames(dpy, XkbAllNamesMask &amp;</p>
<p>~(XkbKeyNamesMask | XkbKeyAliasesMask),</p>
<p>Xkb)</p>
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
There is no way to determine which components specified in <span class="emphasis"><em>
want</em></span>
 (but not in <span class="emphasis"><em>
need</em></span>
) were actually fetched, other than breaking the call into successive calls to
<span class="emphasis"><em>
XkbGetKeyboardByName</em></span>
 and specifying individual components.
</p><p>
<span class="emphasis"><em>
XkbGetKeyboardByName</em></span>
 always sets <span class="emphasis"><em>
min_key_code</em></span>
 and <span class="emphasis"><em>
max_key_code</em></span>
 in the returned <span class="emphasis"><em>
XkbDescRec</em></span>
 structure.
</p><p>
<span class="emphasis"><em>XkbGetKeyboardByName</em></span>
is synchronous; it sends the request to the server to build a new keyboard
description and waits for the reply. If successful, the return value is
non-<span class="emphasis"><em>NULL</em></span>.
<span class="emphasis"><em>XkbGetKeyboardByName</em></span>
generates a <span class="emphasis"><em>BadMatch</em></span>
protocol error if errors are encountered when building the keyboard
description.
</p><p>
If you simply want to obtain information about the current keyboard device,
rather than generating a new keyboard description from elements in the server
database, use <span class="emphasis"><em>
XkbGetKeyboard</em></span>
 (see section 6.2).
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbDescPtr <span class="emphasis"><em>
XkbGetKeyboard</em></span>
(<span class="emphasis"><em>
dpy</em></span>
, <span class="emphasis"><em>
which</em></span>
, <span class="emphasis"><em>
device_spec</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *      <span class="emphasis"><em>
      dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int<span class="emphasis"><em>
            which</em></span>
;            /* mask of components of <span class="emphasis"><em>
XkbDescRec</em></span>
 of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int      <span class="emphasis"><em>
      device_spec</em></span>
;            /* device ID */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetKeyboard</em></span>
 is used to read the current description for one or more components of a
keyboard device. It calls <span class="emphasis"><em>
XkbGetKeyboardByName</em></span>
 as follows:
</p><p>
<span class="emphasis"><em>
XkbGetKeyboardByName</em></span>
(<span class="emphasis"><em>
dpy</em></span>
, <span class="emphasis"><em>
device_spec</em></span>
, <span class="emphasis"><em>
NULL</em></span>
, <span class="emphasis"><em>
which</em></span>
, <span class="emphasis"><em>
which</em></span>
, <span class="emphasis"><em>
False</em></span>
).
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Attaching_Xkb_Actions_to_X_Input_Extension_Devices"></a>Chapter 21. Attaching Xkb Actions to X Input Extension Devices</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#XkbDeviceInfoRec">XkbDeviceInfoRec</a></span></dt><dt><span class="sect1"><a href="#Querying_Xkb_Features_for_Non_KeyClass_Input_Extension_Devices">Querying Xkb Features for Non-KeyClass Input Extension Devices</a></span></dt><dt><span class="sect1"><a href="#Allocating_Initializing_and_Freeing_the_XkbDeviceInfoRecStructure">Allocating, Initializing, and Freeing the XkbDeviceInfoRec
Structure</a></span></dt><dt><span class="sect1"><a href="#Setting_Xkb_Features_for_Non_KeyClass_Input_Extension_Devices">Setting Xkb Features for Non-KeyClass Input Extension Devices</a></span></dt><dt><span class="sect1"><a href="#XkbExtensionDeviceNotify_Event">XkbExtensionDeviceNotify Event</a></span></dt><dt><span class="sect1"><a href="#Tracking_Changes_to_Extension_Devices">Tracking Changes to Extension Devices</a></span></dt></dl></div><p>
The X input extension allows an X server to support multiple keyboards, as well
as other input devices, in addition to the core X keyboard and pointer. The
input extension categorizes devices by grouping them into classes. Keyboards
and other input devices with keys are classified as KeyClass devices by the
input extension. Other types of devices supported by the input extension
include, but are not limited to: mice, tablets, touchscreens, barcode readers,
button boxes, trackballs, identifier devices, data gloves, and eye trackers.
Xkb provides additional control over all X input extension devices, whether
they are <span class="emphasis"><em>KeyClass</em></span>
 devices or not, as well as the core keyboard and pointer.
</p><p>
If an X server implements support for both the input extension and Xkb, the
server implementor determines whether interaction between Xkb and the input
extension is allowed. Implementors are free to restrict the effects of Xkb to
only the core X keyboard device or allow interaction between Xkb and the input
extension.
</p><p>
Several types of interaction between Xkb and the input extension are defined by
Xkb. Some or all may be allowed by the X server implementation.
</p><p>
Regardless of whether the server allows interaction between Xkb and the input
extension, the following access is provided:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Xkb functionality for the core X keyboard device and its mapping is accessed
via the functions described in the other chapters of this specification.
  </p></li><li class="listitem"><p>
Xkb functionality for the core X pointer device is accessed via the
XkbGetDeviceInfo and XkbSetDeviceInfo functions described in this chapter.
  </p></li></ul></div><p>
If all types of interaction are allowed between Xkb and the input extension,
the following additional access is provided:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If allowed, Xkb functionality for additional <span class="emphasis"><em>
KeyClass</em></span>
 devices supported by the input extension is accessed via those same functions.
  </p></li><li class="listitem"><p>
If allowed, Xkb functionality for non-<span class="emphasis"><em>
KeyClass</em></span>
 devices supported by the input extension is also accessed via the
XkbGetDeviceInfo and XkbSetDeviceInfo functions described in this chapter.
  </p></li></ul></div><p>
Each device has an X Input Extension device ID. Each device may have several
classes of feedback. For example, there are two types of feedbacks that can
generate bells: bell feedback and keyboard feedback (<span class="emphasis"><em>
BellFeedbackClass</em></span>
 and <span class="emphasis"><em>
KbdFeedbackClass</em></span>
). A device can have more than one feedback of each type; the feedback ID
identifies the particular feedback within its class.
</p><p>
A keyboard feedback has:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Auto-repeat status (global and per key)
  </p></li><li class="listitem"><p>
32 LEDs
  </p></li><li class="listitem"><p>
A bell
  </p></li></ul></div><p>
An indicator feedback has:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Up to 32 LEDs
  </p></li></ul></div><p>
If the input extension is present and the server allows interaction between the
input extension and Xkb, then the core keyboard, the core keyboard indicators,
and the core keyboard bells may each be addressed using an appropriate device
spec, class, and ID. The constant <span class="emphasis"><em>
XkbXIDfltID</em></span>
 may be used as the device ID to specify the core keyboard indicators for the
core indicator feedback. The particular device ID corresponding to the core
keyboard feedback and the core indicator feedback may be obtained by calling
<span class="emphasis"><em>
XkbGetDeviceInfo</em></span>
 and specifying <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 as the <span class="emphasis"><em>
device_spec</em></span>
; the values will be returned in <span class="emphasis"><em>
dflt_kbd_id</em></span>
 and <span class="emphasis"><em>
dflt_led_id</em></span>
.
</p><p>
If the server does not allow Xkb access to input extension <span class="emphasis"><em>
KeyClass</em></span>
 devices, attempts to use Xkb requests with those devices fail with a
Bad<span class="emphasis"><em>
Keyboard</em></span>
 error. Attempts to access non-<span class="emphasis"><em>
KeyClass</em></span>
 input extension devices via XkbGetDeviceInfo and XkbSetDeviceInfo fail
silently if Xkb access to those devices is not supported by the X server.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="XkbDeviceInfoRec"></a>XkbDeviceInfoRec</h2></div></div></div><p>
Information about X Input Extension devices is transferred between a client
program and the Xkb extension in an <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
 structure:
</p><pre class="programlisting">
typedef struct {
      char *          name;          /* name for device */
      Atom            type;          /* name for class of devices */
      unsigned short  device_spec;   /* device of interest */
      Bool            has_own_state; /* <span class="emphasis"><em> True</em></span> =&gt;this
                                        device has its own state */
      unsigned short  supported;     /* bits indicating supported capabilities */
      unsigned short  unsupported;   /* bits indicating unsupported capabilities */
      unsigned short  num_btns;      /* number of entries in <span class="emphasis"><em> btn_acts</em></span> */
      XkbAction *     btn_acts;      /* button actions */
      unsigned short  sz_leds;       /* total number of entries in LEDs vector */
      unsigned short  num_leds;      /* number of valid entries in LEDs vector */
      unsigned short  dflt_kbd_fb;   /* input extension ID of default (core kbd) indicator */
      unsigned short  dflt_led_fb;   /* input extension ID of default indicator feedback */
      XkbDeviceLedInfoPtr  leds;     /* LED descriptions */
} <span class="emphasis"><em>XkbDeviceInfoRec</em></span>, *XkbDeviceInfoPtr;
</pre><pre class="programlisting">
typedef struct {
      unsigned short   led_class;         /* class for this LED device*/
      unsigned short   led_id;            /* ID for this LED device */
      unsigned int     phys_indicators;   /* bits for which LEDs physically
                                             present */
      unsigned int     maps_present;      /* bits for which LEDs have maps in
                                             <span class="emphasis"><em>maps</em></span> */
      unsigned int     names_present;     /* bits for which LEDs are in
                                             <span class="emphasis"><em> names</em></span> */
      unsigned int     state;            /* 1 bit =&gt; corresponding LED is on */
      Atom             names[XkbNumIndicators];  /* names for LEDs */
      XkbIndicatorMapRec  maps;          /* indicator maps for each LED */
} <span class="emphasis"><em>XkbDeviceLedInfoRec</em></span>, *XkbDeviceLedInfoPtr;
</pre><p>
The <span class="emphasis"><em>
type</em></span>
 field is a registered symbolic name for a class of devices (for example,
"TABLET"). If a device is a keyboard (that is, is a member of <span class="emphasis"><em>
KeyClass</em></span>
), it has its own state, and <span class="emphasis"><em>
has_own_state</em></span>
 is <span class="emphasis"><em>
True</em></span>
. If <span class="emphasis"><em>
has_own_state</em></span>
 is <span class="emphasis"><em>
False</em></span>
, the state of the core keyboard is used. The <span class="emphasis"><em>
supported</em></span>
 and <span class="emphasis"><em>
unsupported</em></span>
 fields are masks where each bit indicates a capability. The meaning of the
mask bits is listed in Table 21.1, together with the fields in the <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
 structure that are associated with the capability represented by each bit. The
same bits are used to indicate the specific information desired in many of the
functions described subsequently in this section.
</p><div class="table"><a id="idp67459228"></a><p class="title"><strong>Table 21.1. XkbDeviceInfoRec Mask Bits</strong></p><div class="table-contents"><table summary="XkbDeviceInfoRec Mask Bits" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Name</th><th align="left">XkbDeviceInfoRec Fields Effected</th><th align="left">Value</th><th align="left">Capability If Set</th></tr></thead><tbody><tr><td align="left">XkbXI_KeyboardsMask</td><td align="left"> </td><td align="left">(1L &lt;&lt; 0)</td><td align="left">
Clients can use all Xkb requests and events with
<span class="emphasis"><em>KeyClass</em></span>
devices supported by the input device extension.
    </td></tr><tr><td align="left">XkbXI_ButtonActionsMask</td><td align="left">
<p>num_btns</p>
<p>btn_acts</p>
    </td><td align="left">(1L &lt;&lt;1)</td><td align="left">
Clients can assign key actions to buttons on non-<span class="emphasis"><em>
KeyClass</em></span>
input extension devices.
    </td></tr><tr><td align="left">XkbXI_IndicatorNamesMask</td><td align="left">leds-&gt;names</td><td align="left">(1L &lt;&lt;2)</td><td align="left">
Clients can assign names to indicators on non-<span class="emphasis"><em>
KeyClass</em></span>
 input extension devices.
    </td></tr><tr><td align="left">XkbXI_IndicatorMapsMask</td><td align="left">leds-&gt;maps</td><td align="left">(1L &lt;&lt;3)</td><td align="left">
Clients can assign indicator maps to indicators on non-<span class="emphasis"><em>
KeyClass</em></span>
 input extension devices.
    </td></tr><tr><td align="left">XkbXI_IndicatorStateMask</td><td align="left">leds-&gt;state</td><td align="left">(1L &lt;&lt;4)</td><td align="left">
Clients can request the status of indicators on non-<span class="emphasis"><em>
KeyClass</em></span>
 input extension devices.
    </td></tr><tr><td align="left">XkbXI_IndicatorsMask</td><td align="left">
<p>sz_leds</p>
<p>num_leds</p>
<p>leds-&gt;*</p>
    </td><td align="left">(0x1c)</td><td align="left">
<p>XkbXI_IndicatorNamesMask |</p>
<p>XkbXI_IndicatorMapsMask |</p>
<p>XkbXI_IndicatorStateMask</p>
    </td></tr><tr><td align="left">XkbXI_UnsupportedFeaturesMask</td><td align="left">unsupported</td><td align="left">(1L &lt;&lt;15)</td><td align="left"> </td></tr><tr><td align="left">XkbXI_AllDeviceFeaturesMask</td><td align="left">Those selected by Value column masks</td><td align="left">(0x1e)</td><td align="left">
<p>XkbXI_IndicatorsMask | </p>
<p>XkbSI_ButtonActionsMask</p>
    </td></tr><tr><td align="left">XkbXI_AllFeaturesMask</td><td align="left">Those selected by Value column masks</td><td align="left">(0x1f)</td><td align="left">
<p>XkbSI_AllDeviceFeaturesMask |</p>
<p>XkbSI_KeyboardsMask</p>
    </td></tr><tr><td align="left">XkbXI_AllDetailsMask</td><td align="left">Those selected by Value column masks</td><td align="left">(0x801f)</td><td align="left">
<p>XkbXI_AllFeaturesMask | </p>
<p>XkbXI_UnsupportedFeaturesMask</p>
    </td></tr></tbody></table></div></div><br class="table-break" /><p>
The <span class="emphasis"><em>
name</em></span>
, <span class="emphasis"><em>
type</em></span>
, <span class="emphasis"><em>
has_own_state</em></span>
, <span class="emphasis"><em>
supported</em></span>
, and <span class="emphasis"><em>
unsupported</em></span>
 fields are always filled in when a valid reply is returned from the server
involving an <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
. All of the other fields are modified only if the particular function asks for
them.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Querying_Xkb_Features_for_Non_KeyClass_Input_Extension_Devices"></a>Querying Xkb Features for Non-KeyClass Input Extension Devices</h2></div></div></div><p>
To determine whether the X server allows Xkb access to particular capabilities
of input devices other than the core X keyboard, or to determine the status of
indicator maps, indicator names or button actions on a non-<span class="emphasis"><em>
KeyClass</em></span>
 extension device, use XkbGetDeviceInfo.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbDeviceInfoPtr <span class="emphasis"><em>
XkbGetDeviceInfo</em></span>
(<span class="emphasis"><em>
dpy</em></span>
, which, device_spec, ind_class, ind_id)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            <span class="emphasis"><em>
dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            which;            /* mask indicating information to
return */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
device_spec</em></span>
;            /* device ID, or <span class="emphasis"><em>
XkbUseCoreKbd</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
ind_class</em></span>
;            /* feedback class for indicator requests */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
ind_id</em></span>
;            /* feedback ID for indicator requests */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetDeviceInfo</em></span>
 returns information about the input device specified by <span class="emphasis"><em>
device_spec</em></span>
. Unlike the <span class="emphasis"><em>
device_spec</em></span>
 parameter of most Xkb functions, <span class="emphasis"><em>
device_spec</em></span>
 does not need to be a keyboard device. It must, however, indicate either the
core keyboard or a valid X Input Extension device.
</p><p>
The <span class="emphasis"><em>
which </em></span>
parameter<span class="emphasis"><em>
 </em></span>
is a mask specifying optional information to be returned. It is an inclusive OR
of one or more of the values from Table 21.1 and causes the returned <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
 to contain values for the corresponding fields specified in the table.
</p><p>
The <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
 returned by <span class="emphasis"><em>
XkbGetDeviceInfo</em></span>
 always has values for <span class="emphasis"><em>
name</em></span>
 (may be a null string, ""), <span class="emphasis"><em>
type</em></span>
, <span class="emphasis"><em>
supported</em></span>
, <span class="emphasis"><em>
unsupported</em></span>
, <span class="emphasis"><em>
has_own_state</em></span>
, <span class="emphasis"><em>
dflt_kbd_fd</em></span>
, and <span class="emphasis"><em>
dflt_kbd_fb</em></span>
. Other fields are filled in as specified by <span class="emphasis"><em>
which</em></span>
.
</p><p>
Upon return, the <span class="emphasis"><em>
supported</em></span>
 field will be set to the inclusive OR of zero or more bits from Table 21.1;
each bit set indicates an optional Xkb extension device feature supported by
the server implementation, and a client may modify the associated behavior.
</p><p>
If the <span class="emphasis"><em>
XkbButtonActionsMask</em></span>
 bit is set in <span class="emphasis"><em>
which</em></span>
, the <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
 returned will have the button actions (<span class="emphasis"><em>
btn_acts</em></span>
 field) filled in for all buttons.
</p><p>
If <span class="emphasis"><em>
which</em></span>
 includes one of the bits in XkbXI_IndicatorsMask, the feedback class of the
indicators must be specified in ind_class, and the feedback ID of the
indicators must be specified in ind_id. If the request does not include any of
the bits in XkbXI_IndicatorsMask, the ind_class and ind_id parameters are
ignored. The class and ID can be obtained via the input device extension
XListInputDevices request.
</p><p>
If any of the <span class="emphasis"><em>
XkbXI_IndicatorsMask</em></span>
 bits are set in <span class="emphasis"><em>
which</em></span>
, the <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
 returned will have filled in the portions of the <span class="emphasis"><em>
leds</em></span>
 structure corresponding to the indicator feedback identified by <span class="emphasis"><em>
ind_class</em></span>
 and <span class="emphasis"><em>
ind_id</em></span>
. The <span class="emphasis"><em>
leds</em></span>
 vector of the <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
 is allocated if necessary and <span class="emphasis"><em>
sz_leds</em></span>
 and <span class="emphasis"><em>
num_leds</em></span>
 filled in. The <span class="emphasis"><em>
led_class</em></span>
, <span class="emphasis"><em>
led_id</em></span>
 and <span class="emphasis"><em>
phys_indicators</em></span>
 fields of the <span class="emphasis"><em>
leds</em></span>
 entry corresponding to <span class="emphasis"><em>
ind_class</em></span>
 and <span class="emphasis"><em>
ind_id</em></span>
 are always filled in. If <span class="emphasis"><em>
which</em></span>
 contains <span class="emphasis"><em>
XkbXI_IndicatorNamesMask</em></span>
, the <span class="emphasis"><em>
names_present</em></span>
 and <span class="emphasis"><em>
names</em></span>
 fields of the <span class="emphasis"><em>
leds</em></span>
 structure corresponding to <span class="emphasis"><em>
ind_class</em></span>
 and <span class="emphasis"><em>
ind_id</em></span>
 are returned.<span class="emphasis"><em>
 </em></span>
If <span class="emphasis"><em>
which</em></span>
 contains <span class="emphasis"><em>
XkbXI_IndicatorStateMask</em></span>
<span class="emphasis"><em>
,</em></span>
 the corresponding <span class="emphasis"><em>
state</em></span>
 field is updated. If <span class="emphasis"><em>
which</em></span>
 contains <span class="emphasis"><em>
XkbXI_IndicatorMapsMask</em></span>
, the <span class="emphasis"><em>
maps_present</em></span>
 and <span class="emphasis"><em>
maps</em></span>
 fields are updated.
</p><p>
Xkb provides convenience functions to request subsets of the information
available via <span class="emphasis"><em>
XkbGetDeviceInfo</em></span>
. These convenience functions mirror some of the mask bits. The functions all
take an <span class="emphasis"><em>
XkbDeviceInfoPtr</em></span>
 as an input argument and operate on the X Input Extension device specified by
the <span class="emphasis"><em>
device_spec</em></span>
 field of the structure. Only the parts of the structure indicated in the
function description are updated. The <span class="emphasis"><em>
XkbDeviceInfo</em></span>
Rec structure used in the function call can be obtained by calling
XkbGetDeviceInfo or can be allocated by calling XkbAllocDeviceInfo (see section
21.3).
</p><p>
These convenience functions are described as follows.
</p><p>
To query the button actions associated with an X Input Extension device, use
XkbGetDeviceButtonActions.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetDeviceButtonActions</em></span>
(<span class="emphasis"><em>
dpy, device_info, all_buttons, first_button, num_buttons</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            <span class="emphasis"><em>
dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDeviceInfoPtr            device_info;            /* structure to update with
results */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool            <span class="emphasis"><em>
all_buttons</em></span>
;            /* <span class="emphasis"><em>
True</em></span>
 =&gt; get information for all buttons */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            first_button;            /* number of first button for
which info is desired */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            num_buttons;            /* number of buttons for which
info is desired */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetDeviceButtonActions</em></span>
 queries the server for the desired button information for the device indicated
by the <span class="emphasis"><em>
device_spec</em></span>
 field of <span class="emphasis"><em>
device_info</em></span>
 and waits for a reply. If successful,<span class="emphasis"><em>
 XkbGetDeviceButtonActions</em></span>
 backfills the button actions (<span class="emphasis"><em>
btn_acts</em></span>
 field of <span class="emphasis"><em>
device_info</em></span>
) for only the requested buttons, updates the <span class="emphasis"><em>
name</em></span>
, <span class="emphasis"><em>
type</em></span>
, <span class="emphasis"><em>
supported</em></span>
, and <span class="emphasis"><em>
unsupported</em></span>
 fields, and returns <span class="emphasis"><em>
Success</em></span>
.
</p><p>
<span class="emphasis"><em>
all_buttons</em></span>
, <span class="emphasis"><em>
first_button</em></span>
 and <span class="emphasis"><em>
num_buttons</em></span>
 specify the device buttons for which actions should be returned. Setting
<span class="emphasis"><em>
all_buttons</em></span>
 to <span class="emphasis"><em>
True</em></span>
 requests actions for all device buttons; if <span class="emphasis"><em>
all_buttons</em></span>
 is <span class="emphasis"><em>
False</em></span>
, <span class="emphasis"><em>
first_button</em></span>
 and <span class="emphasis"><em>
num_buttons</em></span>
 specify a range of buttons for which actions are requested.
</p><p>
If a compatible version of Xkb is not available in the server or the Xkb
extension has not been properly initialized, XkbGetDeviceButtonActions returns
<span class="emphasis"><em>
BadAccess</em></span>
. If allocation errors occur, a <span class="emphasis"><em>
BadAlloc</em></span>
 status is returned. If the specified device (<span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
device_spec</em></span>
) is invalid, a BadKeyboard status is returned. If the device has no buttons, a
Bad<span class="emphasis"><em>
Match</em></span>
 status is returned. If <span class="emphasis"><em>
first_button</em></span>
 and <span class="emphasis"><em>
num_buttons</em></span>
 specify illegal buttons, a Bad<span class="emphasis"><em>
Value</em></span>
 status is returned.
</p><p>
To query the indicator names, maps, and state associated with an LED feedback
of an input extension device, use XkbGetDeviceLedInfo.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetDeviceLedInfo</em></span>
(<span class="emphasis"><em>
dpy, device_i</em></span>
nfo, led_class, led_id, which)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            <span class="emphasis"><em>
dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDeviceInfoPtr            device_info;            /* structure to update with
results */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
led_class</em></span>
;            /* LED feedback class assigned by input extension */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            led_id;            /* LED feedback ID assigned by input
extension */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            which;            /* mask indicating desired
information */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbGetDeviceLedInfo</em></span>
 queries the server for the desired LED information for the feedback specified
by <span class="emphasis"><em>
led_class</em></span>
 and <span class="emphasis"><em>
led_id</em></span>
 for the X input extension device indicated by <span class="emphasis"><em>
device_spec</em></span>
-&gt;<span class="emphasis"><em>
device_info</em></span>
 and waits for a reply. If successful, <span class="emphasis"><em>
XkbGetDeviceLedInfo</em></span>
 backfills the relevant fields of <span class="emphasis"><em>
device_info</em></span>
 as determined by <span class="emphasis"><em>
which</em></span>
 with the results and returns <span class="emphasis"><em>
Success</em></span>
. Valid values for <span class="emphasis"><em>
which</em></span>
 are the inclusive OR of any of <span class="emphasis"><em>
XkbXI_IndicatorNamesMask</em></span>
, <span class="emphasis"><em>
XkbXI_IndicatorMapsMask</em></span>
, and <span class="emphasis"><em>
XkbXI_IndicatorStateMask</em></span>
.
</p><p>
The fields of <span class="emphasis"><em>
device_info</em></span>
 that are filled in when this request succeeds are <span class="emphasis"><em>
name, type, supported</em></span>
, and <span class="emphasis"><em>
unsupported</em></span>
, and portions of the <span class="emphasis"><em>
leds</em></span>
 structure corresponding to <span class="emphasis"><em>
led_class</em></span>
 and <span class="emphasis"><em>
led_id</em></span>
 as indicated by the bits set in <span class="emphasis"><em>
which</em></span>
. The <span class="emphasis"><em>
device_info-&gt;leds</em></span>
 vector is allocated if necessary and <span class="emphasis"><em>
sz_leds</em></span>
 and <span class="emphasis"><em>
num_leds</em></span>
 filled in. The <span class="emphasis"><em>
led_class</em></span>
, <span class="emphasis"><em>
led_id</em></span>
 and <span class="emphasis"><em>
phys_indicators</em></span>
 fields of the <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
leds</em></span>
 entry corresponding to <span class="emphasis"><em>
led_class</em></span>
 and <span class="emphasis"><em>
led_id</em></span>
 are always filled in.
</p><p>
If <span class="emphasis"><em>
which</em></span>
 contains <span class="emphasis"><em>
XkbXI_IndicatorNamesMask</em></span>
, the <span class="emphasis"><em>
names_present</em></span>
 and <span class="emphasis"><em>
names</em></span>
 fields of the <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
leds</em></span>
 structure corresponding to <span class="emphasis"><em>
led_class</em></span>
 and <span class="emphasis"><em>
led_id</em></span>
 are updated, if <span class="emphasis"><em>
which</em></span>
 contains <span class="emphasis"><em>
XkbXI_IndicatorStateMask</em></span>
<span class="emphasis"><em>
,</em></span>
 the corresponding <span class="emphasis"><em>
state</em></span>
 field is updated, and if <span class="emphasis"><em>
which</em></span>
 contains <span class="emphasis"><em>
XkbXI_IndicatorMapsMask</em></span>
, the <span class="emphasis"><em>
maps_present</em></span>
 and <span class="emphasis"><em>
maps</em></span>
 fields are updated.
</p><p>
If a compatible version of Xkb is not available in the server or the Xkb
extension has not been properly initialized, <span class="emphasis"><em>
XkbGetDeviceLedInfo</em></span>
 returns <span class="emphasis"><em>
BadAccess</em></span>
. If allocation errors occur, a BadAlloc status is returned. If the device has
no indicators, a BadMatch error is returned. If <span class="emphasis"><em>
ledClass</em></span>
 or <span class="emphasis"><em>
ledID</em></span>
 have illegal values, a Bad<span class="emphasis"><em>
Value</em></span>
 error is returned. If they have legal values but do not specify a feedback
that contains LEDs and is associated with the specified device, a Bad<span class="emphasis"><em>
Match</em></span>
 error is returned.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Allocating_Initializing_and_Freeing_the_XkbDeviceInfoRecStructure"></a>Allocating, Initializing, and Freeing the XkbDeviceInfoRec
Structure</h2></div></div></div><p>
To obtain an <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
 structure, use XkbGetDeviceInfo or XkbAllocDeviceInfo.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbDeviceInfoPtr <span class="emphasis"><em>
XkbAllocDeviceInfo</em></span>
(device_spec, n_buttons, sz_leds)
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            device_spec;            /* device ID with which
structure will be used */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
n_buttons</em></span>
;            /* number of button actions to allocate space for*/
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
sz_leds</em></span>
;            /* number of LED feedbacks to allocate space for */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocDeviceInfo</em></span>
 allocates space for an <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
 structure and initializes that structure’s <span class="emphasis"><em>
device_spec</em></span>
 field with the device ID specified by device_spec. If <span class="emphasis"><em>
n_buttons</em></span>
 is nonzero, <span class="emphasis"><em>
n_buttons</em></span>
 <span class="emphasis"><em>
XkbActions</em></span>
 are linked into the <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
 structure and initialized to zero. If sz_leds is nonzero, <span class="emphasis"><em>
sz_leds</em></span>
 <span class="emphasis"><em>
XkbDeviceLedInfoRec</em></span>
 structures are also allocated and linked into the <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
 structure. If you request <span class="emphasis"><em>
XkbDeviceLedInfoRec</em></span>
 structures be allocated using this request, you must initialize them
explicitly.
</p><p>
To obtain an <span class="emphasis"><em>
XkbDeviceLedInfoRec</em></span>
 structure, use XkbAllocDeviceLedInfo.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbAllocDeviceLedInfo</em></span>
(devi, num_needed)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDeviceInfoPtr            <span class="emphasis"><em>
device_info</em></span>
;            /* structure in which to allocate LED space */
    </td></tr><tr><td class="functionargdecl" align="left">
int            <span class="emphasis"><em>
num_needed</em></span>
;            /* number of indicators to allocate space for */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAllocDeviceLedInfo</em></span>
 allocates space for an <span class="emphasis"><em>
XkbDeviceLedInfoRec</em></span>
 and places it in <span class="emphasis"><em>
device_info</em></span>
. If num_needed is nonzero, <span class="emphasis"><em>
num_needed</em></span>
 <span class="emphasis"><em>
XkbIndicatorMapRec</em></span>
 structures are also allocated and linked into the <span class="emphasis"><em>
XkbDeviceLedInfoRec</em></span>
 structure. If you request <span class="emphasis"><em>
XkbIndicatorMapRec</em></span>
 structures be allocated using this request, you must initialize them
explicitly. All other fields are initialized to zero.
</p><p>
To initialize an <span class="emphasis"><em>
XkbDeviceLedInfoRec</em></span>
 structure, use XkbAddDeviceLedInfo.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
XkbDeviceLedInfoPtr <span class="emphasis"><em>
XkbAddDeviceLedInfo</em></span>
(device_info, led_class, led_id)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDeviceInfoPtr            device_info;            /* structure in which to
add LED info */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
led_class</em></span>
;            /* input extension class for LED device of interest */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
led_id</em></span>
;            /* input extension ID for LED device of interest */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbAddDeviceLedInfo</em></span>
 first checks to see whether an entry matching <span class="emphasis"><em>
led_class</em></span>
 and <span class="emphasis"><em>
led_id</em></span>
 already exists in the <span class="emphasis"><em>
device_info-&gt;leds</em></span>
 array. If it finds a matching entry, it returns a pointer to that entry.
Otherwise, it checks to be sure there is at least one empty entry in <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
leds</em></span>
 and extends it if there is not enough room. It then increments <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
num_leds</em></span>
 and fills in the next available entry in <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
leds</em></span>
 with <span class="emphasis"><em>
led_class</em></span>
 and <span class="emphasis"><em>
led_id</em></span>
.
</p><p>
If successful, <span class="emphasis"><em>
XkbAddDeviceLedInfo</em></span>
 returns a pointer to the <span class="emphasis"><em>
XkbDeviceLedInfoRec</em></span>
 structure that was initialized. If unable to allocate sufficient storage, or
if <span class="emphasis"><em>
device_info</em></span>
 points to an invalid <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
 structure, or if <span class="emphasis"><em>
led_class</em></span>
 or <span class="emphasis"><em>
led_id</em></span>
 are inappropriate, <span class="emphasis"><em>
XkbAddDeviceLedInfo</em></span>
 returns <span class="emphasis"><em>
NULL</em></span>
.
</p><p>
To allocate additional space for button actions in an <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
 structure, use XkbResizeDeviceButtonActions.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbResizeDeviceButtonActions</em></span>
(device_info, new_total)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDeviceInfoPtr            device_info;            /* structure in which to
allocate button actions */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
new_total</em></span>
;            /* new total number of button actions needed */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbResizeDeviceButton</em></span>
 reallocates space, if necessary, to make sure there is room for a total of
<span class="emphasis"><em>
new_total</em></span>
 button actions in the <span class="emphasis"><em>
device_info</em></span>
 structure. Any new entries allocated are zeroed. If successful, <span class="emphasis"><em>
XkbResizeDeviceButton</em></span>
 returns Success. If new_total is zero, all button actions are deleted,
<span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
num_btns</em></span>
 is set to zero, and <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
btn_acts</em></span>
 is set to <span class="emphasis"><em>
NULL</em></span>
. If device_info is invalid or new_total is greater than 255, BadValue is
returned. If a memory allocation failure occurs, a <span class="emphasis"><em>
BadAlloc</em></span>
 is returned.
</p><p>
To free an <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
 structure, use XkbFreeDeviceInfo.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbFreeDeviceInfo</em></span>
(device_info, which, free_all)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDeviceInfoPtr            device_info;            /* pointer to <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
 in which to free items */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
which</em></span>
;            /* mask of components of <span class="emphasis"><em>
device_info</em></span>
 to free */
    </td></tr><tr><td class="functionargdecl" align="left">
Bool            <span class="emphasis"><em>
free_all</em></span>
;            /* <span class="emphasis"><em>
True</em></span>
 =&gt; free everything, including device_info */
    </td></tr></tbody></table></div><p>
If free_all is <span class="emphasis"><em>
True</em></span>
, the <span class="emphasis"><em>
XkbFreeDeviceInfo</em></span>
 frees all components of <span class="emphasis"><em>
device_info</em></span>
 and the <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
 structure pointed to by <span class="emphasis"><em>
device_info</em></span>
 itself. If free_all is <span class="emphasis"><em>
False</em></span>
, the value of which determines which subcomponents are freed. <span class="emphasis"><em>
which </em></span>
is an inclusive OR of one or more of the values from Table 21.1. If which
contains XkbXI_ButtonActionsMask, all button actions associated with <span class="emphasis"><em>
device_info</em></span>
 are freed, <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
btn_acts</em></span>
 is set to <span class="emphasis"><em>
NULL</em></span>
, and <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
num_btns</em></span>
 is set to zero. If which contains all bits in XkbXI_IndicatorsMask, all
<span class="emphasis"><em>
XkbDeviceLedInfoRec</em></span>
 structures associated with <span class="emphasis"><em>
device_info</em></span>
 are freed, <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
leds</em></span>
 is set to <span class="emphasis"><em>
NULL</em></span>
, and <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
sz_leds</em></span>
 and <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
num_leds</em></span>
 are set to zero. If which contains XkbXI_IndicatorMapsMask, all indicator maps
associated with <span class="emphasis"><em>
device_info</em></span>
 are cleared, but the number of LEDs and the leds structures themselves are
preserved. If which contains XkbXI_IndicatorNamesMask, all indicator names
associated with device_info are cleared, but the number of LEDs and the leds
structures themselves are preserved. If which contains
XkbXI_IndicatorStateMask, the indicator state associated with the <span class="emphasis"><em>
device_info</em></span>
 leds are set to zeros but the number of LEDs and the leds structures
themselves are preserved.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Setting_Xkb_Features_for_Non_KeyClass_Input_Extension_Devices"></a>Setting Xkb Features for Non-KeyClass Input Extension Devices</h2></div></div></div><p>
The Xkb extension allows clients to assign any key action to either core
pointer or input extension device buttons. This makes it possible to control
the keyboard or generate keyboard key events from extension devices or from the
core pointer.
</p><p>
Key actions assigned to core X pointer buttons or input extension device
buttons cause key events to be generated as if they had originated from the
core X keyboard.
</p><p>
Xkb implementations are required to support key actions for the buttons of the
core pointer device, but support for actions on extension devices is optional.
Implementations that do not support button actions for extension devices must
not set the <span class="emphasis"><em>
XkbXI_ButtonActionsMask</em></span>
 bit in the <span class="emphasis"><em>
supported</em></span>
 field of an <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
 structure.
</p><p>
If a client attempts to modify valid characteristics of a device using an
implementation that does not support modification of those characteristics, no
protocol error is generated. Instead, the server reports a failure for the
request; it also sends an <span class="emphasis"><em>
XkbExtensionDeviceNotify</em></span>
 event to the client that issued the request if the client has selected to
receive these events.
</p><p>
To change characteristics of an X Input Extension device in the server, first
modify a local copy of the device structure and then use either <span class="emphasis"><em>
XkbSetDeviceInfo,</em></span>
 or, to save network traffic, use an <span class="emphasis"><em>
XkbDeviceChangesRec</em></span>
 structure (see section 21.6) and call <span class="emphasis"><em>
XkbChangeDeviceInfo</em></span>
 to download the changes to the server.
</p><p>
To modify some or all of the characteristics of an X Input Extension device,
use XkbSetDeviceInfo.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSetDeviceInfo</em></span>
(<span class="emphasis"><em>
dpy</em></span>
, which, device_info)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            <span class="emphasis"><em>
dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
which</em></span>
;            /* mask indicating characteristics to modify */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDeviceInfoPtr            device_info;            /* structure defining the
device and modifications */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSetDeviceInfo</em></span>
 sends a request to the server to modify the characteristics of the device
specified in the <span class="emphasis"><em>
device_info</em></span>
 structure. The particular characteristics modified are identified by the bits
set in <span class="emphasis"><em>
which</em></span>
 and take their values from the relevant fields in <span class="emphasis"><em>
device_info</em></span>
 (see Table 21.1). <span class="emphasis"><em>
XkbSetDeviceInfo</em></span>
 returns <span class="emphasis"><em>
True</em></span>
 if the request was successfully sent to the server. If the X server
implementation does not allow interaction between the X input extension and the
Xkb Extension, the function does nothing and returns <span class="emphasis"><em>
False</em></span>
.
</p><p>
The <span class="emphasis"><em>
which</em></span>
 parameter specifies which aspects of the device should be changed and is a
bitmask composed of an inclusive OR or one or more of the following bits:
<span class="emphasis"><em>
XkbXI_ButtonActionsMask</em></span>
, <span class="emphasis"><em>
XkbXI_IndicatorNamesMask</em></span>
, <span class="emphasis"><em>
XkbXI_IndicatorMapsMask</em></span>
. If the features requested to be manipulated in <span class="emphasis"><em>
which</em></span>
 are valid for the device, but the server does not support assignment of one or
more of them, that particular portion of the request is ignored.
</p><p>
If the device specified in <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
device_spec</em></span>
 does not contain buttons and a request affecting buttons is made, or the
device does not contain indicators and a request affecting indicators is made,
a <span class="emphasis"><em>
BadMatch</em></span>
 protocol error results.
</p><p>
If the <span class="emphasis"><em>
XkbXI_ButtonActionsMask</em></span>
 bit is set in the supported mask returned by XkbGetDeviceInfo, the Xkb
extension allows applications to assign key actions to buttons on input
extension devices other than the core keyboard device. If the <span class="emphasis"><em>
XkbXI_ButtonActionsMask</em></span>
 is set in <span class="emphasis"><em>
which</em></span>
, the actions for all buttons specified in device_info are set to the <span class="emphasis"><em>
XkbAction</em></span>
s specified in <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
btn_acts</em></span>
. If the number of buttons requested to be updated is not valid for the device,
<span class="emphasis"><em>
XkbSetDeviceInfo</em></span>
 returns <span class="emphasis"><em>
False</em></span>
 and a <span class="emphasis"><em>
BadValue</em></span>
 protocol error results.
</p><p>
If the <span class="emphasis"><em>
XkbXI_IndicatorMaps</em></span>
 and / or <span class="emphasis"><em>
XkbXI_IndicatorNamesMask</em></span>
 bit is set in the supported mask returned by XkbGetDeviceInfo, the Xkb
extension allows applications to assign maps and / or names to the indicators
of nonkeyboard extension devices. If supported, maps and / or names can be
assigned to all extension device indicators, whether they are part of a
keyboard feedback or part of an indicator feedback.
</p><p>
If the <span class="emphasis"><em>
XkbXI_IndicatorMapsMask</em></span>
 and / or <span class="emphasis"><em>
XkbXI_IndicatorNamesMask</em></span>
 flag is set in <span class="emphasis"><em>
which</em></span>
, the indicator maps and / or names for all <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
num_leds</em></span>
 indicator devices specified in <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
leds</em></span>
 are set to the maps and / or names specified in <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
leds</em></span>
. <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
leds</em></span>
-&gt;<span class="emphasis"><em>
led_class</em></span>
 and <span class="emphasis"><em>
led_id</em></span>
 specify the input extension class and device ID for each indicator device to
modify; if they have invalid values, a <span class="emphasis"><em>
BadValue</em></span>
 protocol error results and <span class="emphasis"><em>
XkbSetDeviceInfo</em></span>
 returns <span class="emphasis"><em>
False</em></span>
. If they have legal values but do not specify a keyboard or indicator class
feedback for the device in question, a <span class="emphasis"><em>
BadMatch</em></span>
 error results. If any of the values in <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
leds</em></span>
<span class="emphasis"><em>
-&gt;</em></span>
<span class="emphasis"><em>
names</em></span>
 are not a valid Atom or <span class="emphasis"><em>
None</em></span>
, a <span class="emphasis"><em>
BadAtom</em></span>
 protocol error results.
</p><p>
Xkb provides convenience functions to modify subsets of the information
accessible via <span class="emphasis"><em>
XkbSetDeviceInfo</em></span>
. Only the parts of the structure indicated in the function description are
modified. These convenience functions are described as follows.
</p><p>
To change only the button actions for an input extension device, use
XkbSetDeviceButtonActions.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSetDeviceButtonActions</em></span>
(<span class="emphasis"><em>
dpy</em></span>
, device, first_button, num_buttons, actions)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            <span class="emphasis"><em>
dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDeviceInfoPtr            device_info;            /* structure defining the
device and modifications */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            first_button;            /* number of first button to
update, 0 relative */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            num_buttons;            /* number of buttons to update
*/
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSetDeviceButtonActions</em></span>
 assigns actions to the buttons of the device specified in
device_info-&gt;<span class="emphasis"><em>
device_spec</em></span>
. Actions are assigned to <span class="emphasis"><em>
num_buttons</em></span>
 buttons beginning with <span class="emphasis"><em>
first_button</em></span>
 and are taken from the actions specified in <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
btn_acts</em></span>
.
</p><p>
If the server does not support assignment of Xkb actions to extension device
buttons, <span class="emphasis"><em>
XkbSetDeviceButtonActions</em></span>
 has no effect and returns <span class="emphasis"><em>
False</em></span>
. If the device has no buttons or if <span class="emphasis"><em>
first_button</em></span>
 or <span class="emphasis"><em>
num_buttons</em></span>
 specify buttons outside of the valid range as determined by <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
num_btns</em></span>
, the function has no effect and returns <span class="emphasis"><em>
False</em></span>
. Otherwise, <span class="emphasis"><em>
XkbSetDeviceButtonActions</em></span>
 sends a request to the server to change the actions for the specified buttons
and returns <span class="emphasis"><em>
True</em></span>
.
</p><p>
If the actual request sent to the server involved illegal button numbers, a
<span class="emphasis"><em>
BadValue</em></span>
 protocol error is generated. If an invalid device identifier is specified in
device_info-&gt;<span class="emphasis"><em>
device_spec</em></span>
, a BadKeyboard protocol error results. If the actual device specified in
<span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
device_spec</em></span>
 does not contain buttons and a request affecting buttons is made, a <span class="emphasis"><em>
BadMatch</em></span>
 protocol error is generated.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="XkbExtensionDeviceNotify_Event"></a>XkbExtensionDeviceNotify Event</h2></div></div></div><p>
The Xkb extension generates <span class="emphasis"><em>
XkbExtensionDeviceNotify</em></span>
 events when the status of an input extension device changes or when an attempt
is made to use an Xkb feature that is not supported by a particular device.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Events indicating an attempt to use an unsupported feature are
delivered only to the client requesting the event.</p></div><p>
To track changes to the status of input extension devices or attempts to use
unsupported features of a device, select to receive <span class="emphasis"><em>
XkbExtensionDeviceNotify</em></span>
 events by calling either <span class="emphasis"><em>
XkbSelectEvents</em></span>
 or <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
 (see section 4.3).
</p><p>
To receive <span class="emphasis"><em>
XkbExtensionDeviceNotify</em></span>
 events under all possible conditions, call <span class="emphasis"><em>
XkbSelectEvents</em></span>
 and pass <span class="emphasis"><em>
XkbExtensionDeviceNotifyMask</em></span>
 in both <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits</em></span>
.
</p><p>
The <span class="emphasis"><em>
XkbExtensionDeviceNotify</em></span>
 event has no event details. However, you can call <span class="emphasis"><em>
XkbSelectEventDetails</em></span>
 using <span class="emphasis"><em>
XkbExtensionDeviceNotify</em></span>
 as the <span class="emphasis"><em>
event_type</em></span>
 and specifying <span class="emphasis"><em>
XkbAllExtensionDeviceMask</em></span>
 in <span class="emphasis"><em>
bits_to_change</em></span>
 and <span class="emphasis"><em>
values_for_bits.</em></span>
 This has the same effect as a call to <span class="emphasis"><em>
XkbSelectEvents</em></span>
.
</p><p>
The structure for <span class="emphasis"><em>
XkbExtensionDeviceNotify</em></span>
 events is:
</p><pre class="programlisting">
typedef struct {
      int      type;           /* Xkb extension base event code */
      unsigned long  serial;   /* X server serial number for event */
      Bool     send_event;     /* <span class="emphasis"><em>True</em></span>
                                  =&gt; synthetically generated*/
      Display *      display;  /* server connection where event generated */
      Time     time;           /* server time when event generated */
      int      xkb_type;  /* <span class="emphasis"><em>XkbExtensionDeviceNotifyEvent</em></span> */
      int      device;         /* Xkb device ID, will not be
                                  <span class="emphasis"><em>XkbUseCoreKbd</em></span> */
      unsigned int   reason;   /* reason for the event */
      unsigned int   supported;  /* mask of supported features */
      unsigned int   unsupported;  /* unsupported features this client
                                      attempted to use */
      int      first_btn;      /* first button that changed */
      int      num_btns;       /* number of buttons that changed */
      unsigned int   leds_defined;  /* indicators with names or maps */
      unsigned int       led_state; /* current state of the indicators */
      int       led_class;          /* feedback class for LED changes */
      int       led_id;             /* feedback ID for LED changes */
} <span class="emphasis"><em>XkbExtensionDeviceNotifyEvent</em></span>;
</pre><p>
The <span class="emphasis"><em>
XkbExtensionDeviceNotify</em></span>
 event has fields enabling it to report changes in the state (on/off) of all of
the buttons for a device, but only for one LED feedback associated with a
device. You will get multiple events when more than one LED feedback changes
state or configuration.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Tracking_Changes_to_Extension_Devices"></a>Tracking Changes to Extension Devices</h2></div></div></div><p>
Changes to an Xkb extension device may be tracked by listening to <span class="emphasis"><em>
XkbDeviceExtensionNotify</em></span>
 events and accumulating the changes in an <span class="emphasis"><em>
XkbDeviceChangesRec</em></span>
 structure. The changes noted in the structure may then be used in subsequent
operations to update either a server configuration or a local copy of an Xkb
extension device configuration. The changes structure is defined as follows:
</p><pre class="programlisting">
typedef struct _XkbDeviceChanges {
      unsigned int    changed;   /* bits indicating what has changed */
      unsigned short  first_btn; /* number of first button which changed,
                                    if any */
      unsigned short  num_btns;  /* number of buttons that have changed */
      XkbDeviceLedChangesRec leds;
} <span class="emphasis"><em>XkbDeviceChangesRec</em></span>,*XkbDeviceChangesPtr;
</pre><pre class="programlisting">
typedef struct _XkbDeviceLedChanges {
      unsigned short  led_class; /* class of this indicator feedback bundle */
      unsigned short  led_id;    /* ID of this indicator feedback bundle */
      unsigned int    names;     /* bits indicating which names have changed */
      unsigned int    maps;      /* bits indicating which maps have changed */
      struct _XkbDeviceLedChanges *next; /* link to indicator change record
                                            for next set */
} <span class="emphasis"><em>XkbDeviceLedChangesRec</em></span>,*XkbDeviceLedChangesPtr;
</pre><p>
A local description of the configuration and state of a device may be kept in
an <span class="emphasis"><em>
XkbDeviceInfoRec</em></span>
 structure. The actual state or configuration of the device may change because
of XkbSetDeviceInfo and XkbSetButtonActions requests made by clients or by user
interaction with the device. The X server sends an XkbExtensionDeviceNotify
event to all interested clients when the state of any buttons or indicators or
the configuration of the buttons or indicators on the core keyboard or any
input extension device changes. The event reports the state of indicators for a
single indicator feedback, and the state of up to 128 buttons. If more than 128
buttons or more than one indicator feedback are changed, the additional buttons
and indicator feedbacks are reported in subsequent events. Xkb provides
functions with which you can track changes to input extension devices by noting
the changes that were made and then requesting the changed information from the
server.
</p><p>
To note device changes reported in an <span class="emphasis"><em>
XkbExtensionDeviceNotify</em></span>
 event, use XkbNoteDeviceChanges.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
void <span class="emphasis"><em>
XkbNoteDeviceChanges</em></span>
 (<span class="emphasis"><em>
old, new, wanted</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDeviceChangesPtr                        <span class="emphasis"><em>
old</em></span>
;            /* structure tracking state changes */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbExtensionDeviceNotifyEvent             *            <span class="emphasis"><em>
new</em></span>
;            /* event indicating state changes */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int                        <span class="emphasis"><em>
wanted</em></span>
;            /* mask indicating changes to note */
    </td></tr></tbody></table></div><p>
The wanted field specifies the changes that should be noted in <span class="emphasis"><em>
old</em></span>
, and is composed of the bitwise inclusive OR of one or more of the masks from
Table 21.1<span class="emphasis"><em>
.</em></span>
 The <span class="emphasis"><em>
reason</em></span>
 field of the event in <span class="emphasis"><em>
new</em></span>
 indicates the types of changes the event is reporting. <span class="emphasis"><em>
XkbNoteDeviceChanges</em></span>
 updates the <span class="emphasis"><em>
XkbDeviceChangesRec</em></span>
 specified by <span class="emphasis"><em>
old</em></span>
 with the changes that are both specified in <span class="emphasis"><em>
wanted</em></span>
 and contained in <span class="emphasis"><em>
new</em></span>
-&gt;<span class="emphasis"><em>
reason</em></span>
.
</p><p>
To update a local copy of the state and configuration of an X input extension
device with the changes previously noted in an <span class="emphasis"><em>
XkbDeviceChangesRec</em></span>
 structure, use XkbGetDeviceInfoChanges.
</p><p>
To query the changes that have occurred in the button actions or indicator
names and indicator maps associated with an input extension device, use
XkbGetDeviceInfoChanges.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Status <span class="emphasis"><em>
XkbGetDeviceInfoChanges</em></span>
(<span class="emphasis"><em>
dpy</em></span>
, <span class="emphasis"><em>
device_info</em></span>
, changes)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            <span class="emphasis"><em>
dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDeviceInfoPtr            device_info;            /* structure to update with
results */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDeviceChangesPtr            <span class="emphasis"><em>
changes</em></span>
;            /* contains notes of changes that have occurred */
    </td></tr></tbody></table></div><p>
The changes-&gt;changed field indicates which attributes of the device
specified in <span class="emphasis"><em>
changes</em></span>
-&gt;<span class="emphasis"><em>
device</em></span>
 have changed. The parameters describing the changes are contained in the other
fields of <span class="emphasis"><em>
changes</em></span>
. <span class="emphasis"><em>
XkbGetDeviceInfoChanges</em></span>
 uses that information to call XkbGetDeviceInfo to obtain the current status of
those attributes that have changed. It then updates the local description of
the device in <span class="emphasis"><em>
device_info</em></span>
 with the new information.
</p><p>
To update the server’s description of a device with the changes noted in an
XkbDeviceChangesRec, use XkbChangeDeviceInfo.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbChangeDeviceInfo</em></span>
 (<span class="emphasis"><em>
dpy, device_info, changes</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display *            <span class="emphasis"><em>
dpy</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDeviceInfoPtr            <span class="emphasis"><em>
device_info</em></span>
;            /* local copy of device state and configuration */
    </td></tr><tr><td class="functionargdecl" align="left">
XkbDeviceChangesPtr            <span class="emphasis"><em>
changes</em></span>
;            /* note specifying changes in <span class="emphasis"><em>
device_info</em></span>
 */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbChangeDeviceInfo</em></span>
 updates the server’s description of the device specified in <span class="emphasis"><em>
device_info</em></span>
-&gt;<span class="emphasis"><em>
device_spec</em></span>
 with the changes specified in <span class="emphasis"><em>
changes</em></span>
 and contained in <span class="emphasis"><em>
device_info</em></span>
. The update is made by an XkbSetDeviceInfo request.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Debugging_Aids"></a>Chapter 22. Debugging Aids</h1></div></div></div><p>
The debugging aids are intended for use primarily by Xkb implementors and are
optional in any implementation.
</p><p>
There are two bitmasks that may be used to control debugging. One bitmask
controls the output of debugging information, and the other controls behavior.
Both bitmasks are initially all zeros.
</p><p>
To change the values of any of the debug controls, use <span class="emphasis"><em>
XkbSetDebuggingFlags</em></span>
.
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /></colgroup><tbody><tr><td class="functiondecl" align="left">
Bool <span class="emphasis"><em>
XkbSetDebuggingFlags</em></span>
(<span class="emphasis"><em>
display, mask, flags, msg, ctrls_mask, ctrls, ret_flags, ret_ctrls</em></span>
)
    </td></tr><tr><td class="functionargdecl" align="left">
Display * <span class="emphasis"><em>
            display</em></span>
;            /* connection to X server */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int <span class="emphasis"><em>
            mask</em></span>
;            /* mask selecting debug output flags to change */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int <span class="emphasis"><em>
            flags</em></span>
;            /* values for debug output flags selected by <span class="emphasis"><em>
mask</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
char * <span class="emphasis"><em>
            msg</em></span>
;            /* message to print right now */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
ctrls_mask</em></span>
;            /* mask selecting debug controls to change */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int            <span class="emphasis"><em>
ctrls</em></span>
;            /* values for debug controls selected by <span class="emphasis"><em>
ctrls_mask</em></span>
 */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int * <span class="emphasis"><em>
            ret_flags</em></span>
;            /* resulting state of all debug output flags */
    </td></tr><tr><td class="functionargdecl" align="left">
unsigned int *            <span class="emphasis"><em>
ret_ctrls</em></span>
;            /* resulting state of all debug controls */
    </td></tr></tbody></table></div><p>
<span class="emphasis"><em>
XkbSetDebuggingFlags</em></span>
 modifies the debug output flags as specified by <span class="emphasis"><em>
mask</em></span>
 and <span class="emphasis"><em>
flags</em></span>
, modifies the debug controls flags as specified by <span class="emphasis"><em>
ctrls_mask</em></span>
 and <span class="emphasis"><em>
ctrls</em></span>
, prints the message <span class="emphasis"><em>
msg</em></span>
, and backfills <span class="emphasis"><em>
ret_flags</em></span>
 and <span class="emphasis"><em>
ret_ctrls</em></span>
 with the resulting debug output and debug controls flags.
</p><p>
When bits are set in the debug output masks, <span class="emphasis"><em>
mask</em></span>
 and <span class="emphasis"><em>
flags</em></span>
, Xkb prints debug information corresponding to each bit at appropriate points
during its processing. The device to which the output is written is
implementation-dependent, but is normally the same device to which X server
error messages are directed; thus the bits that can be set in <span class="emphasis"><em>
mask</em></span>
 and <span class="emphasis"><em>
flags</em></span>
 is implementation-specific. To turn on a debug output selection, set the bit
for the output in the <span class="emphasis"><em>
mask</em></span>
 parameter and set the corresponding bit in the <span class="emphasis"><em>
flags</em></span>
 parameter. To turn off event selection for an event, set the bit for the
output in the <span class="emphasis"><em>
mask</em></span>
 parameter and do not set the corresponding bit in the <span class="emphasis"><em>
flags</em></span>
 parameter.
</p><p>
When bits are set in the debug controls masks, <span class="emphasis"><em>
ctrls_mask</em></span>
 and <span class="emphasis"><em>
ctrls</em></span>
, Xkb modifies its behavior according to each controls bit. <span class="emphasis"><em>
ctrls_mask</em></span>
 and <span class="emphasis"><em>
ctrls</em></span>
 are related in the same way that <span class="emphasis"><em>
mask</em></span>
 and <span class="emphasis"><em>
flags</em></span>
 are. The valid controls bits are defined in Table 22.1.
</p><div class="table"><a id="idp65339596"></a><p class="title"><strong>Table 22.1. Debug Control Masks</strong></p><div class="table-contents"><table summary="Debug Control Masks" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">Debug Control Mask</th><th align="left">Value</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left">XkbDF_DisableLocks</td><td align="left">(1 &lt;&lt; 0)</td><td align="left">Disable actions that lock modifiers</td></tr></tbody></table></div></div><br class="table-break" /><p>
<span class="emphasis"><em>
XkbSetDebuggingFlags</em></span>
 returns <span class="emphasis"><em>
True</em></span>
 if successful and <span class="emphasis"><em>
False</em></span>
 otherwise. The only protocol error it may generate is <span class="emphasis"><em>
BadAlloc</em></span>
, if for some reason it is unable to allocate storage.
</p><p>
<span class="emphasis"><em>
XkbSetDebuggingFlags</em></span>
 is intended for developer use and may be disabled in production X servers. If
it is disabled, <span class="emphasis"><em>
XkbSetDebuggingFlags</em></span>
 has no effect and does not generate any protocol errors.
</p><p>
The message in <span class="emphasis"><em>
msg</em></span>
 is written immediately. The device to which it is written is implementation
dependent but is normally the same device where X server error messages are
directed.
</p></div><div class="glossary"><div class="titlepage"><div><div><h1 class="title"><a id="glossary"></a>Glossary</h1></div></div></div><dl><dt><span class="glossterm">Allocator</span></dt><dd class="glossdef"><p>
Xkb provides functions, known as allocators, to create and initialize Xkb data
structures.
    </p></dd><dt><span class="glossterm">Audible Bell</span></dt><dd class="glossdef"><p>
An audible bell is the sound generated by whatever bell is associated with the
keyboard or input extension device, as opposed to any other audible sound
generated elsewhere in the system.
    </p></dd><dt><span class="glossterm">Autoreset Controls</span></dt><dd class="glossdef"><p>
The autoreset controls configure the boolean controls to automatically be
enabled or disabled at the time a program exits.
    </p></dd><dt><span class="glossterm">Base Group</span></dt><dd class="glossdef"><p>
The group in effect as a result of all actions other than a previous lock or
latch request; the base group is transient. For example, the user pressing and
holding a group shift key that shifts to Group2 would result in the base group
being group 2 at that point in time. Initially, base group is always Group1.
    </p></dd><dt><span class="glossterm">Base Modifiers</span></dt><dd class="glossdef"><p>
Modifiers that are turned on as a result of some actions other than previous
lock or latch requests; base modifiers are transient. For example, the user
pressing and holding a key bound to the Shift modifier would result in Shift
being a base modifier at that point in time.
    </p></dd><dt><span class="glossterm">Base Event Code</span></dt><dd class="glossdef"><p>
A number assigned by the X server at run time that is assigned to the extension
to identify events from that extension.
    </p></dd><dt><span class="glossterm">Base State</span></dt><dd class="glossdef"><p>
The base group and base modifiers represent keys that are physically or
logically down; these constitute the base state.
    </p></dd><dt><span class="glossterm">Boolean Controls</span></dt><dd class="glossdef"><p>
Global keyboard controls that may be selectively enabled and disabled under
program control and that may be automatically set to an on or off condition
upon client program exit.
    </p></dd><dt><span class="glossterm">Canonical Key Types</span></dt><dd class="glossdef"><p>
The canonical key types are predefined key types that describe the types of
keys available on most keyboards. The definitions for the canonical key types
are held in the first <span class="emphasis"><em>
XkbNumRequiredTypes</em></span>
 entries of the <span class="emphasis"><em>
types</em></span>
 field of the client map and are indexed using the following constants:
    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="emphasis"><em>XkbOneLevelIndex</em></span>
        </p></li><li class="listitem"><p>
<span class="emphasis"><em>XkbTwoLevelIndex</em></span>
        </p></li><li class="listitem"><p>
<span class="emphasis"><em>XkbAlphabeticIndex</em></span>
        </p></li><li class="listitem"><p>
<span class="emphasis"><em>XkbKeypadIndex</em></span>
        </p></li></ul></div></dd><dt><span class="glossterm">Client Map</span></dt><dd class="glossdef"><p>
The key mapping information needed to convert arbitrary keycodes to symbols.
    </p></dd><dt><span class="glossterm">Compat Name</span></dt><dd class="glossdef"><p>
The <span class="emphasis"><em>
compat</em></span>
 name is a string that provides some information about the rules used to bind
actions to keys that are changed using core protocol requests.
    </p></dd><dt><span class="glossterm">Compatibility State</span></dt><dd class="glossdef"><p>
When an Xkb-extended X server connects to an Xkb-unaware client, the
compatibility state remaps the keyboard group into a core modifier whenever
possible.
    </p></dd><dt><span class="glossterm">Compatibility Grab State</span></dt><dd class="glossdef"><p>
The grab state that results from applying the compatibility map to the Xkb grab
state.
    </p></dd><dt><span class="glossterm">Compatibility Map</span></dt><dd class="glossdef"><p>
The definition of how to map core protocol keyboard state to Xkb keyboard state.
    </p></dd><dt><span class="glossterm">Component Expression</span></dt><dd class="glossdef"><p>
An expression used to describe server keyboard database components to be
loaded. It describes the order in which the components should be loaded and the
rules by which duplicate attributes should be resolved.
    </p></dd><dt><span class="glossterm">Compose Processing</span></dt><dd class="glossdef"><p>
The process of mapping a series of keysyms to a string is known as compose
processing.
    </p></dd><dt><span class="glossterm">Consumed Modifier</span></dt><dd class="glossdef"><p>
Xkb normally consumes modifiers in determining the appropriate symbol for an
event, that is, the modifiers are not considered during any of the later stages
of event processing. For those rare occasions when a modifier <span class="emphasis"><em>
should</em></span>
 be considered despite having been used to look up a symbol, key types include
an optional <span class="emphasis"><em>
preserve</em></span>
 field.
    </p></dd><dt><span class="glossterm">Core Event</span></dt><dd class="glossdef"><p>
An event created from the core X server.
    </p></dd><dt><span class="glossterm">Detectable Auto-Repeat</span></dt><dd class="glossdef"><p>
Detectable auto-repeat allows a client to detect an auto-repeating key. If a
client requests and the server supports detectable auto-repeat, Xkb generates
<span class="emphasis"><em>
KeyRelease</em></span>
 events only when the key is physically released. Thus the client receives a
number of <span class="emphasis"><em>
KeyPress</em></span>
 events for that key without intervening <span class="emphasis"><em>
KeyRelease</em></span>
 events until the key is finally released, when a <span class="emphasis"><em>
KeyRelease</em></span>
 event is received.
    </p></dd><dt><span class="glossterm">Effective Group</span></dt><dd class="glossdef"><p>
The effective group is the arithmetic sum of the locked, latched, and base
groups. The effective keyboard group is always brought back into range
depending on the value of the <span class="emphasis"><em>
GroupsWrap</em></span>
 control for the keyboard. If an event occurs with an effective group that is
legal for the keyboard as a whole, but not for the key in question, the group
<span class="emphasis"><em>
for that event only</em></span>
 is normalized using the algorithm specified by the <span class="emphasis"><em>
group_info</em></span>
 member of the key symbol map (<span class="emphasis"><em>
XkbSymMapRec</em></span>
).
    </p></dd><dt><span class="glossterm">Effective Mask</span></dt><dd class="glossdef"><p>
An Xkb modifier definition consists of a set of bit masks corresponding to the
eight real modifiers; a similar set of bitmasks corresponding to the 16 named
virtual modifiers; and an effective mask. The effective mask represents the set
of all real modifiers that can logically be set either by setting any of the
real modifiers or by setting any of the virtual modifiers in the definition.
    </p></dd><dt><span class="glossterm">Effective Modifier</span></dt><dd class="glossdef"><p>
The effective modifiers are the bitwise union of the base, latched and locked
modifiers.
    </p></dd><dt><span class="glossterm">Extension Device</span></dt><dd class="glossdef"><p>
Any keyboard or other input device recognized by the X input extension.
    </p></dd><dt><span class="glossterm">Global Keyboard Controls</span></dt><dd class="glossdef"><p>
Controls that affect the way Xkb generates key events. The controls affect all
keys, as opposed to per-key controls that are for a single key. Global controls
include
    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>RepeatKeys Control</p></li><li class="listitem"><p>DetectableAuto-repeat</p></li><li class="listitem"><p>SlowKeys</p></li><li class="listitem"><p>BounceKeys</p></li><li class="listitem"><p>StickyKeys</p></li><li class="listitem"><p>MouseKeys</p></li><li class="listitem"><p>MouseKeysAccel</p></li><li class="listitem"><p>AccessXKeys</p></li><li class="listitem"><p>AccessXTimeout</p></li><li class="listitem"><p>AccessXFeedback</p></li><li class="listitem"><p>Overlay1</p></li><li class="listitem"><p>Overlay2</p></li><li class="listitem"><p>EnabledControls</p></li></ul></div></dd><dt><span class="glossterm">Grab State</span></dt><dd class="glossdef"><p>
The grab state is the state used when matching events to passive grabs. It
consists of the grab group and the grab modifiers.
    </p></dd><dt><span class="glossterm">Group</span></dt><dd class="glossdef"><p>See Keysym Group</p></dd><dt><span class="glossterm">Group Index</span></dt><dd class="glossdef"><p>
A number used as the internal representation for a group number. Group1 through
Group 4 have indices of 0 through 3.
    </p></dd><dt><span class="glossterm">Groups Wrap Control</span></dt><dd class="glossdef"><p>
If a group index exceeds the maximum number of groups permitted for the
specified keyboard, it is wrapped or truncated back into range as specified by
the global <span class="emphasis"><em>GroupsWrap</em></span> control. <span class="emphasis"><em>
GroupsWrap</em></span> can have the following values:
    </p><div class="literallayout"><p><br />
          <span class="emphasis"><em>WrapIntoRange</em></span><br />
          <span class="emphasis"><em>ClampIntoRange</em></span><br />
          <span class="emphasis"><em>RedirectIntoRange</em></span><br />
    </p></div></dd><dt><span class="glossterm">Key Type</span></dt><dd class="glossdef"><p>
An attribute of a key that identifies which modifiers affect the shift level of
a key and the number of groups on the key.
    </p></dd><dt><span class="glossterm">Key Width</span></dt><dd class="glossdef"><p>
The maximum number of shift levels in any group for the key type associated
with a key.
    </p></dd><dt><span class="glossterm">Keysym Group</span></dt><dd class="glossdef"><p>
A keysym group is a logical state of the keyboard providing access to a
collection of characters. A group usually contains a set of characters that
logically belong together and that may be arranged on several shift levels
within that group. For example, Group1 could be the English alphabet, and
Group2 could be Greek. Xkb supports up to four different groups for an input
device or keyboard. Groups are in the range 1-4 (Group1 - Group4), and are
often referred to as G1 - G4 and indexed as 0 - 3.
    </p></dd><dt><span class="glossterm">Indicator</span></dt><dd class="glossdef"><p>
An indicator is a feedback mechanism such as an LED on an input device. Using
Xkb, a client application can determine the names of the various indicators,
determine and control the way that the individual indicators should be updated
to reflect keyboard changes, and determine which of the 32 keyboard indicators
reported by the protocol are actually present on the keyboard.
    </p></dd><dt><span class="glossterm">Indicator Feedback</span></dt><dd class="glossdef"><p>
An indicator feedback describes the state of a bank of up to 32 lights. It has
a mask where each bit corresponds to a light and an associated value mask that
specifies which lights are on or off.
    </p></dd><dt><span class="glossterm">Indicator Map</span></dt><dd class="glossdef"><p>
An indicator has its own set of attributes that specify whether clients can
explicitly set its state and whether it tracks the keyboard state. The
indicator map is the collection of these attributes for each indicator and is
held in the <span class="emphasis"><em>
maps</em></span>
 array, which is an array of <span class="emphasis"><em>
XkbIndicatorRec</em></span>
 structures.
    </p></dd><dt><span class="glossterm">Input Extension</span></dt><dd class="glossdef"><p>
An extension to the core X protocol that allows an X server to support multiple
keyboards, as well as other input devices, in addition to the core X keyboard
and pointer. Other types of devices supported by the input extension include,
but are not limited to: mice, tablets, touchscreens, barcode readers, button
boxes, trackballs, identifier devices, data gloves, and eye trackers.
    </p></dd><dt><span class="glossterm">Key Action</span></dt><dd class="glossdef"><p>
A key action consists of an operator and some optional data. Once the server
has applied the global controls and per-key behavior and has decided to process
a key event, it applies key actions to determine the effects of the key on the
internal state of the server. Xkb supports actions that do the following:
    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Change base, latched, or locked modifiers or group
      </p></li><li class="listitem"><p>
Move the core pointer or simulate core pointer button events
      </p></li><li class="listitem"><p>
Change most aspects of keyboard behavior
      </p></li><li class="listitem"><p>
Terminate or suspend the server
      </p></li><li class="listitem"><p>
Send a message to interested clients
      </p></li><li class="listitem"><p>
Simulate events on other keys
      </p></li></ul></div></dd><dt><span class="glossterm">Key Alias</span></dt><dd class="glossdef"><p>
A key alias is a symbolic name for a specific physical key. Key aliases allow
the keyboard layout designer to assign multiple key names to a single key. This
allows the keyboard layout designer to refer to keys using either their
position or their "function." Key aliases can be specified both in the symbolic
names component and in the keyboard geometry. Both sets of aliases are always
valid, but key alias definitions in the keyboard geometry have priority; if
both symbolic names and geometry include aliases, you should consider the
definitions from the geometry before considering the definitions from the
symbolic names section.
    </p></dd><dt><span class="glossterm">Key Behavior</span></dt><dd class="glossdef"><p>
The <span class="emphasis"><em>
behaviors</em></span>
 field of the server map is an array of <span class="emphasis"><em>
XkbBehavior</em></span>
, indexed by keycode, and contains the behavior for each key. The X server uses
key behavior to determine whether to process or filter out any given key event;
key behavior is independent of keyboard modifier or group state. Each key has
exactly one behavior.
    </p><p>Key behaviors include:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>XkbKB_Default</p></li><li class="listitem"><p>XkbKB_Lock</p></li><li class="listitem"><p>XkbKB_RadioGroup</p></li><li class="listitem"><p>XkbKB_Overlay1</p></li><li class="listitem"><p>XkbKB_Overlay2</p></li></ul></div></dd><dt><span class="glossterm">Key Symbol Map</span></dt><dd class="glossdef"><p>
A key symbol map describes the symbols bound to a key and the rules to be used
to interpret those symbols. It is an array of <span class="emphasis"><em>
XkbSymMapRec</em></span>
 structures indexed by keycode.
    </p></dd><dt><span class="glossterm">Key Type</span></dt><dd class="glossdef"><p>
Key types are used to determine the shift level of a key given the current
state of the keyboard. There is one key type for each group for a key. Key
types are defined using the <span class="emphasis"><em>
XkbKeyTypeRec</em></span>
 and <span class="emphasis"><em>
XkbKTMapEntryRec</em></span>
 structures. Xkb allows up to <span class="emphasis"><em>
XkbMaxKeyTypes</em></span>
 (255) key types to be defined, but requires at least <span class="emphasis"><em>
XkbNumRequiredTypes</em></span>
 (4) predefined types to be in a key map.
    </p></dd><dt><span class="glossterm">Keyboard Bells</span></dt><dd class="glossdef"><p>
The sound the default bell makes when rung is the system bell or the default
keyboard bell. Some input devices may have more than one bell, identified by
<span class="emphasis"><em>bell_class</em></span> and <span class="emphasis"><em>bell_id</em></span>.
    </p></dd><dt><span class="glossterm">Keyboard Components</span></dt><dd class="glossdef"><p>
There are five types of components stored in the X server database of keyboard
components. They correspond to the <span class="emphasis"><em>
symbols, geometry, keycodes, compat, </em></span>
and<span class="emphasis"><em>
 types</em></span>
 symbolic names associated with a keyboard.
    </p></dd><dt><span class="glossterm">Keyboard Feedback</span></dt><dd class="glossdef"><p>
A keyboard feedback includes the following:
    </p><div class="literallayout"><p><br />
      Keyclick volume<br />
      Bell volume<br />
      Bell pitch<br />
      Bell duration<br />
      Global auto-repeat<br />
      Per key auto-repeat<br />
      32 LEDs<br />
</p></div></dd><dt><span class="glossterm">Key Width, Key Type Width</span></dt><dd class="glossdef"><p>
The maximum number of shift levels for a type is referred to as the width of a
key type.
    </p></dd><dt><span class="glossterm">Keyboard Geometry</span></dt><dd class="glossdef"><p>
Keyboard geometry describes the physical appearance of the keyboard, including
the shape, location, and color of all keyboard keys or other visible keyboard
components such as indicators and is stored in a <span class="emphasis"><em>
XkbGeometryRec</em></span>
 structure. The information contained in a keyboard geometry is sufficient to
allow a client program to draw an accurate two-dimensional image of the
keyboard.
    </p></dd><dt><span class="glossterm">Keyboard Geometry Name</span></dt><dd class="glossdef"><p>
The keyboard geometry name describes the physical location, size, and shape of
the various keys on the keyboard and is part of the <span class="emphasis"><em>
XkbNamesRec</em></span>
 structure.
    </p></dd><dt><span class="glossterm">Keyboard State</span></dt><dd class="glossdef"><p>
Keyboard state encompasses all of the transitory information necessary to map a
physical key press or release to an appropriate event.
    </p></dd><dt><span class="glossterm">Keycode</span></dt><dd class="glossdef"><p>
A numeric value returned to the X server when a key on a keyboard is pressed or
released, indicating which key is being modulated. Keycode numbers are in the
range 1 &lt;= keycode &lt;= max, where max is the number of physical keys on
the device.
    </p></dd><dt><span class="glossterm">Keycode Name</span></dt><dd class="glossdef"><p>
The keycode name describes the range and meaning of the keycodes returned by
the keyboard and is part of the <span class="emphasis"><em>
XkbNamesRec</em></span>
 structure.
    </p></dd><dt><span class="glossterm">Latched Group</span></dt><dd class="glossdef"><p>
A latched group is a group index that is combined with the base and locked
group to form the effective group. It applies only to the next key event that
does not change the keyboard state. The latched group can be changed by
keyboard activity or via Xkb extension library functions.
    </p></dd><dt><span class="glossterm">Latched Modifier</span></dt><dd class="glossdef"><p>
Latched modifiers are the set of modifiers that are combined with the base
modifiers and the locked modifiers to form the effective modifiers. It applies
only to the next key event that does not change the keyboard state.
    </p></dd><dt><span class="glossterm">LED</span></dt><dd class="glossdef"><p>
A light emitting diode. However, for the purposes of the X keyboard extension
specification, a LED is any form of visual two-state indicator that is either
on or off.
    </p></dd><dt><span class="glossterm">Locked Group</span></dt><dd class="glossdef"><p>
A locked group is a group index that is combined with the base and latched
group to form the effective group. When a group is locked, it supersedes any
previous locked group and remains the locked group for all future key events,
until a new group is locked. The locked group can be changed by keyboard
activity or via Xkb extension library functions.
    </p></dd><dt><span class="glossterm">Locked Modifiers</span></dt><dd class="glossdef"><p>
Locked modifiers are the set of modifiers that are combined with the base
modifiers and the latched modifiers to form the effective modifiers. A locked
modifier applies to all future key events until it is explicitly unlocked.
    </p></dd><dt><span class="glossterm">Lookup State      </span></dt><dd class="glossdef"><p>
The lookup state is composed of the lookup group and the lookup modifiers, and
it is the state an Xkb-capable or Xkb-aware client should use to map a keycode
to a keysym.
    </p></dd><dt><span class="glossterm">Modifier</span></dt><dd class="glossdef"><p>
A modifier is a logical condition that is either set or unset. The modifiers
control the Shift Level selected when a key event occurs. Xkb supports the core
protocol eight modifiers (<span class="emphasis"><em>
Shift</em></span>
, <span class="emphasis"><em>
Lock</em></span>
, <span class="emphasis"><em>
Control</em></span>
, and <span class="emphasis"><em>
Mod1</em></span>
 through <span class="emphasis"><em>
Mod5</em></span>
), called the <span class="emphasis"><em>
real</em></span>
 modifiers. In addition, Xkb extends modifier flexibility by providing a set of
sixteen named virtual modifiers, each of which can be bound to any set of the
eight real modifiers.
    </p></dd><dt><span class="glossterm">Modifier Key</span></dt><dd class="glossdef"><p>
A modifier key is a key whose operation has no immediate effect, but that, for
as long as it is held down, modifies the effect of other keys. A modifier key
may be, for example, a shift key or a control key.
    </p></dd><dt><span class="glossterm">Modifier Definition</span></dt><dd class="glossdef"><p>
An Xkb modifier definition, held in an <span class="emphasis"><em>
XkbModsRec</em></span>
, consists of a set of real modifiers, a set of virtual modifiers, and an
effective mask. The mask is the union of the real modifiers and the set of real
modifiers to which the virtual modifiers map; the mask cannot be explicitly
changed.
    </p></dd><dt><span class="glossterm">Nonkeyboard Extension Device      </span></dt><dd class="glossdef"><p>
An input extension device that is not a keyboard. Other types of devices
supported by the input extension include, but are not limited to: mice,
tablets, touchscreens, barcode readers, button boxes, trackballs, identifier
devices, data gloves, and eye trackers.
    </p></dd><dt><span class="glossterm">Outlines</span></dt><dd class="glossdef"><p>
An outline is a list of one or more points that describes a single closed
polygon, used in the geometry specification for a keyboard.
    </p></dd><dt><span class="glossterm">Physical Indicator Mask</span></dt><dd class="glossdef"><p>
The physical indicator mask is a field in the <span class="emphasis"><em>
XkbIndicatorRec</em></span>
 that indicates which indicators are bound to physical LEDs on the keyboard; if
a bit is set in <span class="emphasis"><em>
phys_indicators</em></span>
, then the associated indicator has a physical LED associated with it. This
field is necessary because some indicators may not have corresponding physical
LEDs on the keyboard.
    </p></dd><dt><span class="glossterm">Physical Symbol Keyboard Name</span></dt><dd class="glossdef"><p>
The <span class="emphasis"><em>
symbols</em></span>
 keyboard name identifies the symbols logically bound to the keys. The symbols
name is a human or application-readable description of the intended locale or
usage of the keyboard with these symbols. The <span class="emphasis"><em>
phys_symbols</em></span>
 keyboard name, on the other hand, identifies the symbols actually engraved on
the keyboard.
    </p></dd><dt><span class="glossterm">Preserved Modifier</span></dt><dd class="glossdef"><p>
Xkb normally consumes modifiers in determining the appropriate symbol for an
event, that is, the modifiers are not considered during any of the later stages
of event processing. For those rare occasions when a modifier <span class="emphasis"><em>
should</em></span>
 be considered despite having been used to look up a symbol, key types include
an optional <span class="emphasis"><em>
preserve</em></span>
 field. If a modifier is present in the <span class="emphasis"><em>
preserve</em></span>
 list, it is a preserved modifier.
    </p></dd><dt><span class="glossterm">Radio Group</span></dt><dd class="glossdef"><p>
A radio group is a set of keys whose behavior simulates a set of radio buttons.
Once a key in a radio group is pressed, it stays logically depressed until
another key in the group is pressed, at which point the previously depressed
key is logically released. Consequently, at most one key in a radio group can
be logically depressed at one time.
    </p></dd><dt><span class="glossterm">Real Modifier</span></dt><dd class="glossdef"><p>
Xkb supports the eight core protocol modifiers (<span class="emphasis"><em>
Shift</em></span>
, <span class="emphasis"><em>
Lock</em></span>
, <span class="emphasis"><em>
Control</em></span>
, and <span class="emphasis"><em>
Mod1</em></span>
 through <span class="emphasis"><em>
Mod5</em></span>
); these are called the <span class="emphasis"><em>
real</em></span>
 modifiers, as opposed to the set of sixteen named virtual modifiers that can
be bound to any set of the eight real modifiers.
    </p></dd><dt><span class="glossterm">Server Internal Modifiers</span></dt><dd class="glossdef"><p>
Modifiers that the server uses to determine the appropriate symbol for an
event; internal modifiers are normally consumed by the server.
    </p></dd><dt><span class="glossterm">Shift Level</span></dt><dd class="glossdef"><p>
One of several states (normally 2 or 3) governing which graphic character is
produced when a key is actuated.
    </p></dd><dt><span class="glossterm">Symbol Keyboard Name</span></dt><dd class="glossdef"><p>
The <span class="emphasis"><em>
symbols</em></span>
 keyboard name identifies the symbols logically bound to the keys. The symbols
name is a human or application-readable description of the intended locale or
usage of the keyboard with these symbols. The <span class="emphasis"><em>
phys_symbols</em></span>
 keyboard name, on the other hand, identifies the symbols actually engraved on
the keyboard.
    </p></dd><dt><span class="glossterm">Symbolic Name</span></dt><dd class="glossdef"><p>
Xkb supports symbolic names for most components of the keyboard extension. Most
of these symbolic names are grouped into the <span class="emphasis"><em>
names</em></span>
 component of the keyboard description.
    </p></dd><dt><span class="glossterm">State Field</span></dt><dd class="glossdef"><p>
The portion of a client-side core protocol event that holds the modifier,
group, and button state information pertaining to the event.
    </p></dd><dt><span class="glossterm">Types Name</span></dt><dd class="glossdef"><p>
The <span class="emphasis"><em>
types</em></span>
 name provides some information about the set of key types that can be
associated with the keyboard. In addition, each key type can have a name, and
each shift level of a type can have a name.
    </p></dd><dt><span class="glossterm">Valuator</span></dt><dd class="glossdef"><p>
A valuator reports a range of values for some entity, like a mouse axis, a
slider, or a dial.
    </p></dd><dt><span class="glossterm">Virtual Modifier</span></dt><dd class="glossdef"><p>
Xkb provides a set of sixteen named virtual modifiers that can be bound to any
set of the eight real modifiers. Each virtual modifier can be bound to any set
of the real modifiers (<span class="emphasis"><em>
Shift</em></span>
, <span class="emphasis"><em>
Lock</em></span>
, <span class="emphasis"><em>
Control,</em></span>
 and <span class="emphasis"><em>
Mod1</em></span>
-<span class="emphasis"><em>
Mod5</em></span>
).
    </p></dd><dt><span class="glossterm">Virtual Modifier Mapping</span></dt><dd class="glossdef"><p>
Xkb maintains a virtual modifier mapping, which lists the virtual modifiers
associated with each key.
    </p></dd><dt><span class="glossterm">Xkb-aware Client</span></dt><dd class="glossdef"><p>
A client application that initializes Xkb extension and is consequently bound
to an Xlib that includes the Xkb extension.
    </p></dd><dt><span class="glossterm">Xkb-capable Client</span></dt><dd class="glossdef"><p>
A client application that makes no Xkb extension Xlib calls but is bound to an
Xlib that includes the Xkb extension.
    </p></dd><dt><span class="glossterm">Xkb-unaware Client</span></dt><dd class="glossdef"><p>
A client application that makes no Xkb extension Xlib calls and is bound to an
Xlib that does not include the Xkb extension.
    </p></dd></dl></div></div></body></html>
libx11-doc 2:1.6.2-1ubuntu2.1 / usr / share / doc / libx11-dev / XKB / xkblib.html
