diff options
| -rw-r--r-- | Makefile.am | 2 | ||||
| -rw-r--r-- | configure.ac | 11 | ||||
| -rw-r--r-- | specs/.gitignore | 4 | ||||
| -rw-r--r-- | specs/Makefile.am | 86 | ||||
| -rwxr-xr-x | specs/XKBproto-1.gif | bin | 0 -> 1778 bytes | |||
| -rwxr-xr-x | specs/XKBproto-10.gif | bin | 0 -> 920 bytes | |||
| -rwxr-xr-x | specs/XKBproto-11.gif | bin | 0 -> 2886 bytes | |||
| -rwxr-xr-x | specs/XKBproto-2.gif | bin | 0 -> 1435 bytes | |||
| -rwxr-xr-x | specs/XKBproto-3.gif | bin | 0 -> 1194 bytes | |||
| -rwxr-xr-x | specs/XKBproto-4.gif | bin | 0 -> 1077 bytes | |||
| -rwxr-xr-x | specs/XKBproto-5.gif | bin | 0 -> 1077 bytes | |||
| -rwxr-xr-x | specs/XKBproto-6.gif | bin | 0 -> 4078 bytes | |||
| -rwxr-xr-x | specs/XKBproto-7.gif | bin | 0 -> 3886 bytes | |||
| -rwxr-xr-x | specs/XKBproto-8.gif | bin | 0 -> 946 bytes | |||
| -rwxr-xr-x | specs/XKBproto-9.gif | bin | 0 -> 946 bytes | |||
| -rw-r--r-- | specs/acknowledgements.xml | 41 | ||||
| -rw-r--r-- | specs/appA.xml | 909 | ||||
| -rw-r--r-- | specs/appB.xml | 129 | ||||
| -rw-r--r-- | specs/appC.xml | 710 | ||||
| -rw-r--r-- | specs/appD.xml | 2096 | ||||
| -rw-r--r-- | specs/ch01.xml | 101 | ||||
| -rw-r--r-- | specs/ch02.xml | 443 | ||||
| -rw-r--r-- | specs/ch03.xml | 220 | ||||
| -rw-r--r-- | specs/ch04.xml | 867 | ||||
| -rw-r--r-- | specs/ch05.xml | 88 | ||||
| -rw-r--r-- | specs/ch06.xml | 1765 | ||||
| -rw-r--r-- | specs/ch07.xml | 685 | ||||
| -rw-r--r-- | specs/ch08.xml | 156 | ||||
| -rw-r--r-- | specs/ch09.xml | 604 | ||||
| -rw-r--r-- | specs/ch10.xml | 174 | ||||
| -rw-r--r-- | specs/ch11.xml | 414 | ||||
| -rw-r--r-- | specs/ch12.xml | 1025 | ||||
| -rw-r--r-- | specs/ch13.xml | 440 | ||||
| -rw-r--r-- | specs/ch14.xml | 94 | ||||
| -rw-r--r-- | specs/ch15.xml | 232 | ||||
| -rw-r--r-- | specs/ch16.xml | 9378 | ||||
| -rw-r--r-- | specs/xkbproto.xml | 84 |
37 files changed, 20755 insertions, 3 deletions
diff --git a/Makefile.am b/Makefile.am index bbe8a1e..4358857 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,3 +1,5 @@ +SUBDIRS = specs + kbdir = $(includedir)/X11/extensions kb_HEADERS = \ XKBgeom.h \ diff --git a/configure.ac b/configure.ac index 1a7ab4a..d7d2088 100644 --- a/configure.ac +++ b/configure.ac @@ -3,11 +3,16 @@ AC_INIT([KBProto], [1.0.5], [https://bugs.freedesktop.org/enter_bug.cgi?product= AM_INIT_AUTOMAKE([foreign dist-bzip2]) AM_MAINTAINER_MODE -# Require xorg-macros: XORG_DEFAULT_OPTIONS +# Require xorg-macros minimum of 1.10 for DocBook XML documentation m4_ifndef([XORG_MACROS_VERSION], - [m4_fatal([must install xorg-macros 1.3 or later before running autoconf/autogen])]) -XORG_MACROS_VERSION(1.3) + [m4_fatal([must install xorg-macros 1.10 or later before running autoconf/autogen])]) +XORG_MACROS_VERSION(1.10) XORG_DEFAULT_OPTIONS +XORG_ENABLE_SPECS +XORG_WITH_XMLTO(0.0.20) +XORG_WITH_FOP +XORG_CHECK_SGML_DOCTOOLS(1.5) AC_OUTPUT([Makefile + specs/Makefile kbproto.pc]) diff --git a/specs/.gitignore b/specs/.gitignore new file mode 100644 index 0000000..6fa5c31 --- /dev/null +++ b/specs/.gitignore @@ -0,0 +1,4 @@ +*.html +*.ps +*.pdf +*.txt diff --git a/specs/Makefile.am b/specs/Makefile.am new file mode 100644 index 0000000..d421927 --- /dev/null +++ b/specs/Makefile.am @@ -0,0 +1,86 @@ +# +# Copyright 2009 Sun Microsystems, Inc. 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. +# + +if ENABLE_SPECS + +doc_sources = xkbproto.xml +dist_doc_DATA = \ + $(doc_sources) \ + acknowledgements.xml \ + appA.xml \ + appB.xml \ + appC.xml \ + appD.xml \ + ch01.xml \ + ch02.xml \ + ch03.xml \ + ch04.xml \ + ch05.xml \ + ch06.xml \ + ch07.xml \ + ch08.xml \ + ch09.xml \ + ch10.xml \ + ch11.xml \ + ch12.xml \ + ch13.xml \ + ch14.xml \ + ch15.xml \ + ch16.xml + +if HAVE_XMLTO +doc_DATA = $(doc_sources:.xml=.html) + +if HAVE_FOP +doc_DATA += $(doc_sources:.xml=.ps) $(doc_sources:.xml=.pdf) +endif + +if HAVE_XMLTO_TEXT +doc_DATA += $(doc_sources:.xml=.txt) +endif + +if HAVE_STYLESHEETS +XMLTO_FLAGS = \ + -m $(XSL_STYLESHEET) \ + --stringparam img.src.path=$(abs_builddir)/ \ + --stringparam html.stylesheet=$(STYLESHEET_SRCDIR)/xorg.css +endif + +CLEANFILES = $(doc_DATA) + +SUFFIXES = .xml .ps .pdf .txt .html + +%.txt: %.xml $(dist_doc_DATA) + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) txt $< + +%.html: %.xml $(dist_doc_DATA) + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) xhtml-nochunks $< + +%.pdf: %.xml $(dist_doc_DATA) + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop pdf $< + +%.ps: %.xml $(dist_doc_DATA) + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop ps $< + +endif HAVE_XMLTO +endif ENABLE_SPECS diff --git a/specs/XKBproto-1.gif b/specs/XKBproto-1.gif Binary files differnew file mode 100755 index 0000000..437f8f8 --- /dev/null +++ b/specs/XKBproto-1.gif diff --git a/specs/XKBproto-10.gif b/specs/XKBproto-10.gif Binary files differnew file mode 100755 index 0000000..4fd531d --- /dev/null +++ b/specs/XKBproto-10.gif diff --git a/specs/XKBproto-11.gif b/specs/XKBproto-11.gif Binary files differnew file mode 100755 index 0000000..62dee73 --- /dev/null +++ b/specs/XKBproto-11.gif diff --git a/specs/XKBproto-2.gif b/specs/XKBproto-2.gif Binary files differnew file mode 100755 index 0000000..43728a3 --- /dev/null +++ b/specs/XKBproto-2.gif diff --git a/specs/XKBproto-3.gif b/specs/XKBproto-3.gif Binary files differnew file mode 100755 index 0000000..1d7114a --- /dev/null +++ b/specs/XKBproto-3.gif diff --git a/specs/XKBproto-4.gif b/specs/XKBproto-4.gif Binary files differnew file mode 100755 index 0000000..739ab95 --- /dev/null +++ b/specs/XKBproto-4.gif diff --git a/specs/XKBproto-5.gif b/specs/XKBproto-5.gif Binary files differnew file mode 100755 index 0000000..739ab95 --- /dev/null +++ b/specs/XKBproto-5.gif diff --git a/specs/XKBproto-6.gif b/specs/XKBproto-6.gif Binary files differnew file mode 100755 index 0000000..58ea4e8 --- /dev/null +++ b/specs/XKBproto-6.gif diff --git a/specs/XKBproto-7.gif b/specs/XKBproto-7.gif Binary files differnew file mode 100755 index 0000000..5620419 --- /dev/null +++ b/specs/XKBproto-7.gif diff --git a/specs/XKBproto-8.gif b/specs/XKBproto-8.gif Binary files differnew file mode 100755 index 0000000..4281b4e --- /dev/null +++ b/specs/XKBproto-8.gif diff --git a/specs/XKBproto-9.gif b/specs/XKBproto-9.gif Binary files differnew file mode 100755 index 0000000..4281b4e --- /dev/null +++ b/specs/XKBproto-9.gif diff --git a/specs/acknowledgements.xml b/specs/acknowledgements.xml new file mode 100644 index 0000000..95b9521 --- /dev/null +++ b/specs/acknowledgements.xml @@ -0,0 +1,41 @@ +<preface> +<title>Acknowledgments</title> + +<para> +I am grateful for all of the comments and suggestions I have received over the years. I could not possibly list everyone who has helped, but a few people have gone well above and beyond the call of duty and simply must be listed here. +</para> + +<para> +My managers here at SGI, Tom Paquin (now at Netscape) and Gianni Mariani were wonderful. Rather than insisting on some relatively quick, specialized proprietary solution to the keyboard problems we were having, both Tom and Gianni understood the importance of solving them in a general way and for the community as a whole. That was a difficult position to take and it was even harder to maintain when the scope of the project expanded beyond anything we imagined was possible. Gianni and Tom were unflagging in their support and their desire to “do the right thing” despite the schedule and budget pressure that intervened from time to time. +</para> + +<para> +Will Walker, at Digital Equipment Corporation, has been a longtime supporter of XKB. His help and input was essential to ensure that the extension as a whole fits and works together well. His focus was AccessX but the entire extension has benefited from his input and hard work. Without his unflagging good cheer and willingness to lend a hand, XKB would not be where it is today. +</para> + +<para> +Matt Landau, at the X Consortium, stood behind XKB during some tough spots in the release and standardization process. Without Matt’s support, XKB would likely not be a standard for a long time to come. When it became clear that we had too much to do for the amount of time we had remaining, Matt did a fantastic job of finding people to help finish the work needed for standardization. +</para> + +<para> +One of those people was George Sachs, at Hewlett-Packard, who jumped in to help out. His help was essential in getting the extension into this release. Another was Donna Converse, who helped figure out how to explain all of this stuff to someone who hadn’t had their head buried in it for years. +</para> + +<para> +Amber Benson and Gary Aitken were simply phenomenal. They jumped into a huge and complicated project with good cheer and unbelievable energy. They were “up to speed” and contributing within days. I stand in awe of the amount that they managed to achieve in such a short time. Thanks to Gary and Amber, the XKB library specification is a work of art and a thousand times easier to use and more useful than it would otherwise be. +</para> + +<para> +I truly cannot express my gratitude to all of you, without whom this would not have been possible. +</para> + +<para> +Erik Fortune +</para> +<para> +Silicon Graphics, Inc. +</para> +<para> +5 February 1996 +</para> +</preface> diff --git a/specs/appA.xml b/specs/appA.xml new file mode 100644 index 0000000..fa85a67 --- /dev/null +++ b/specs/appA.xml @@ -0,0 +1,909 @@ +<appendix id='default_symbol_transformations'> +<title>Default Symbol Transformations</title> + +<sect1 id='interpreting_the_control_modifier'> +<title>Interpreting the Control Modifier</title> + +<para> +If the <emphasis> +Control</emphasis> + modifier is not consumed by the symbol lookup process, routines that determine +the symbol and string that correspond to an event should convert the symbol to +a string as defined in the table below. Only the string to be returned is +affected by the <emphasis> +Control</emphasis> + modifier; the symbol is not changed. +</para> + + +<para> +This table lists the decimal value of the standard control characters that +correspond to some keysyms for ASCII characters. Control characters for symbols +not listed in this table are application-specific. +</para> + +<informaltable frame='none'> +<tgroup cols='8'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Keysyms</entry> + <entry>Value</entry> + <entry>Keysyms</entry> + <entry>Value</entry> + <entry>Keysyms</entry> + <entry>Value</entry> + <entry>Keysyms</entry> + <entry>Value</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>atsign</entry> + <entry>0</entry> + <entry>h, H</entry> + <entry>8</entry> + <entry>p, P</entry> + <entry>16</entry> + <entry>x, X</entry> + <entry>24</entry> + </row> + <row rowsep='0'> + <entry>a, A</entry> + <entry>1</entry> + <entry>i, I</entry> + <entry>9</entry> + <entry>q, Q</entry> + <entry>17</entry> + <entry>y, Y</entry> + <entry>25</entry> + </row> + <row rowsep='0'> + <entry>b, B</entry> + <entry>2</entry> + <entry>j, J</entry> + <entry>10</entry> + <entry>r, R</entry> + <entry>18</entry> + <entry>z, Z</entry> + <entry>26</entry> + </row> + <row rowsep='0'> + <entry>c, C</entry> + <entry>3</entry> + <entry>k, K</entry> + <entry>11</entry> + <entry>s, S</entry> + <entry>19</entry> + <entry>left_bracket</entry> + <entry>27</entry> + </row> + <row rowsep='0'> + <entry>d, D</entry> + <entry>4</entry> + <entry>l, L</entry> + <entry>12</entry> + <entry>t, T</entry> + <entry>20</entry> + <entry>backslash</entry> + <entry>28</entry> + </row> + <row rowsep='0'> + <entry>e, E</entry> + <entry>5</entry> + <entry>m, M</entry> + <entry>13</entry> + <entry>u, U</entry> + <entry>21</entry> + <entry>right_bracket</entry> + <entry>29</entry> + </row> + <row rowsep='0'> + <entry>f, F</entry> + <entry>6</entry> + <entry>n, N</entry> + <entry>14</entry> + <entry>v, V</entry> + <entry>22</entry> + <entry>asciicircum</entry> + <entry>30</entry> + </row> + <row rowsep='0'> + <entry>g, G</entry> + <entry>8</entry> + <entry>o, O</entry> + <entry>15</entry> + <entry>w, W</entry> + <entry>23</entry> + <entry>underbar</entry> + <entry>31</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +</sect1> +<sect1 id='interpreting_the_lock_modifier'> +<title>Interpreting the Lock Modifier</title> + +<para> +If the <emphasis> +Lock</emphasis> + modifier is not consumed by the symbol lookup process, routines that determine +the symbol and string that correspond to an event should capitalize the result. +Unlike the transformation for <emphasis> +Control</emphasis> +, the capitalization transformation changes both the symbol and the string +returned by the event. +</para> + +<sect2 id='locale_sensitive_capitalization'> +<title>Locale-Sensitive Capitalization</title> + +<para> +If <emphasis> +Lock</emphasis> + is set in an event and not consumed, applications should capitalize the string +and symbols that result from an event according to the capitalization rules in +effect for the system on which the application is running, taking the current +state of the user environment (e.g. locale) into account. +</para> + + +</sect2> +<sect2 id='locale_insensitive_capitalization'> +<title>Locale-Insensitive Capitalization</title> + +<para> +XKB recommends but does not require locale-sensitive capitalization. In cases +where the locale is unknown or where locale-sensitive capitalization is +prohibitively expensive, applications can capitalize according to the rules +defined in this extension. +</para> + + +<para> +The following tables list all of the keysyms for which XKB defines +capitalization behavior. Any keysyms not explicitly listed in these tables are +not capitalized by XKB when locale-insensitive capitalization is in effect and +are not automatically assigned the <emphasis> +ALPHABETIC</emphasis> + type as described in <ulink url="protocol.htm#35661"></ulink>. +</para> + + +<sect3 id='capitalization_rules_for_latin_1_keysyms'> +<title>Capitalization Rules for Latin-1 Keysyms </title> + +<para> +This table lists the Latin-11 keysyms for which XKB defines upper and lower +case: +</para> + +<informaltable frame='none'> +<tgroup cols='8'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Lower Case</entry> + <entry>Upper Case</entry> + <entry>Lower Case</entry> + <entry>Upper Case</entry> + <entry>Lower Case</entry> + <entry>Upper Case</entry> + <entry>Lower Case</entry> + <entry>Upper Case</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>a</entry> + <entry>A</entry> + <entry>o</entry> + <entry>O</entry> + <entry>acircumflex</entry> + <entry>Acircumflex</entry> + <entry>eth</entry> + <entry>ETH</entry> + </row> + <row rowsep='0'> + <entry>b</entry> + <entry>B</entry> + <entry>p</entry> + <entry>P</entry> + <entry>adiaeresis</entry> + <entry>Adiaeresis</entry> + <entry>ntilde</entry> + <entry>Ntilde</entry> + </row> + <row rowsep='0'> + <entry>c</entry> + <entry>C</entry> + <entry>q</entry> + <entry>Q</entry> + <entry>atilde</entry> + <entry>Atilde</entry> + <entry>ograve</entry> + <entry>Ograve</entry> + </row> + <row rowsep='0'> + <entry>d</entry> + <entry>D</entry> + <entry>r</entry> + <entry>R</entry> + <entry>aring</entry> + <entry>Aring</entry> + <entry>oacute</entry> + <entry>Oacute</entry> + </row> + <row rowsep='0'> + <entry>e</entry> + <entry>E</entry> + <entry>s</entry> + <entry>S</entry> + <entry>ae</entry> + <entry>AE</entry> + <entry>ocircumflex</entry> + <entry>Ocircumflex</entry> + </row> + <row rowsep='0'> + <entry>f</entry> + <entry>F</entry> + <entry>t</entry> + <entry>T</entry> + <entry>ccedilla</entry> + <entry>Ccedilla</entry> + <entry>otilde</entry> + <entry>Otilde</entry> + </row> + <row rowsep='0'> + <entry>g</entry> + <entry>G</entry> + <entry>u</entry> + <entry>U</entry> + <entry>egrave</entry> + <entry>Egrave</entry> + <entry>odiaeresis</entry> + <entry>Odiaeresis</entry> + </row> + <row rowsep='0'> + <entry>h</entry> + <entry>H</entry> + <entry>v</entry> + <entry>V</entry> + <entry>eacute</entry> + <entry>Eacute</entry> + <entry>oslash</entry> + <entry>Ooblique</entry> + </row> + <row rowsep='0'> + <entry>i</entry> + <entry>I</entry> + <entry>w</entry> + <entry>W</entry> + <entry>ecircumflex</entry> + <entry>Ecircumflex</entry> + <entry>ugrave</entry> + <entry>Ugrave</entry> + </row> + <row rowsep='0'> + <entry>j</entry> + <entry>J</entry> + <entry>x</entry> + <entry>X</entry> + <entry>ediaeresis</entry> + <entry>Ediaeresis</entry> + <entry>uacute</entry> + <entry>Uacute</entry> + </row> + <row rowsep='0'> + <entry>k</entry> + <entry>K</entry> + <entry>y</entry> + <entry>Y</entry> + <entry>igrave</entry> + <entry>Igrave</entry> + <entry>ucircumflex</entry> + <entry>Ucircumflex</entry> + </row> + <row rowsep='0'> + <entry>l</entry> + <entry>L</entry> + <entry>z</entry> + <entry>Z</entry> + <entry>iacute</entry> + <entry>Iacute</entry> + <entry>udiaeresis</entry> + <entry>Udiaeresis</entry> + </row> + <row rowsep='0'> + <entry>m</entry> + <entry>M</entry> + <entry>agrave</entry> + <entry>Agrave</entry> + <entry>icircumflex</entry> + <entry>Icircumflex</entry> + <entry>yacute</entry> + <entry>Yacute</entry> + </row> + <row rowsep='0'> + <entry>n</entry> + <entry>N</entry> + <entry>aacute</entry> + <entry>Aacute</entry> + <entry>idiaeresis</entry> + <entry>Idiaeresis</entry> + <entry>thorn</entry> + <entry>THORN</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +</sect3> +<sect3 id='capitalization_rules_for_latin_2_keysyms'> +<title>Capitalization Rules for Latin-2 Keysyms</title> + +<para> +This table lists the Latin-2 keysyms for which XKB defines upper and lower case: +</para> + +<informaltable frame='none'> +<tgroup cols='6'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Lower Case</entry> + <entry>Upper Case</entry> + <entry>Lower Case</entry> + <entry>Upper Case</entry> + <entry>Lower Case</entry> + <entry>Upper Case</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>aogonek</entry> + <entry>Aogonek</entry> + <entry>zabovedot</entry> + <entry>Zabovedot</entry> + <entry>dstroke</entry> + <entry>Dstroke</entry> + </row> + <row rowsep='0'> + <entry>lstroke</entry> + <entry>Lstroke</entry> + <entry>racute</entry> + <entry>Racute</entry> + <entry>nacute</entry> + <entry>Nacute</entry> + </row> + <row rowsep='0'> + <entry>lcaron</entry> + <entry>Lcaron</entry> + <entry>abreve</entry> + <entry>Abreve</entry> + <entry>ncaron</entry> + <entry>Ncaron</entry> + </row> + <row rowsep='0'> + <entry>sacute</entry> + <entry>Sacute</entry> + <entry>lacute</entry> + <entry>Lacute</entry> + <entry>odoubleacute</entry> + <entry>Odoubleacute</entry> + </row> + <row rowsep='0'> + <entry>scaron</entry> + <entry>Scaron</entry> + <entry>cacute</entry> + <entry>Cacute</entry> + <entry>rcaron</entry> + <entry>Rcaron</entry> + </row> + <row rowsep='0'> + <entry>scedilla</entry> + <entry>Scedilla</entry> + <entry>ccaron</entry> + <entry>Ccaron</entry> + <entry>uabovering</entry> + <entry>Uabovering</entry> + </row> + <row rowsep='0'> + <entry>tcaron</entry> + <entry>Tcaron</entry> + <entry>eogonek</entry> + <entry>Eogonek</entry> + <entry>udoubleacute</entry> + <entry>Udoubleacute</entry> + </row> + <row rowsep='0'> + <entry>zacute</entry> + <entry>Zacute</entry> + <entry>ecaron</entry> + <entry>Ecaron</entry> + <entry>tcedilla</entry> + <entry>Tcedilla</entry> + </row> + <row rowsep='0'> + <entry>zcaron</entry> + <entry>Zcaron</entry> + <entry>dcaron</entry> + <entry>Dcaron</entry> + <entry> </entry> + <entry> </entry> + </row> +</tbody> +</tgroup> +</informaltable> + +</sect3> +<sect3 id='capitalization_rules_for_latin_3_keysyms'> +<title>Capitalization Rules for Latin-3 Keysyms</title> + +<para> +This table lists the Latin-3 keysyms for which XKB defines upper and lower case: +</para> + +<informaltable frame='none'> +<tgroup cols='6'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Lower Case</entry> + <entry>Upper Case</entry> + <entry>Lower Case</entry> + <entry>Upper Case</entry> + <entry>Lower Case</entry> + <entry>Upper Case</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>hstroke</entry> + <entry>Hstroke</entry> + <entry>jcircumflex</entry> + <entry>Jcircumflex</entry> + <entry>gcircumflex</entry> + <entry>Gcircumflex</entry> + </row> + <row rowsep='0'> + <entry>hcircumflex</entry> + <entry>Hcircumflex</entry> + <entry>cabovedot</entry> + <entry>Cabovedot</entry> + <entry>ubreve</entry> + <entry>Ubreve</entry> + </row> + <row rowsep='0'> + <entry>idotless</entry> + <entry>Iabovedot</entry> + <entry>ccircumflex</entry> + <entry>Ccircumflex</entry> + <entry>scircumflex</entry> + <entry>Scircumflex</entry> + </row> + <row rowsep='0'> + <entry>gbreve</entry> + <entry>Gbreve</entry> + <entry>gabovedot</entry> + <entry>Gabovedot</entry> + <entry> </entry> + <entry> </entry> + </row> +</tbody> +</tgroup> +</informaltable> + +</sect3> +<sect3 id='capitalization_rules_for_latin_4_keysyms'> +<title>Capitalization Rules for Latin-4 Keysyms</title> + +<para> +This table lists the Latin-4 keysyms for which XKB defines upper and lower case: +</para> + +<informaltable frame='none'> +<tgroup cols='6'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Lower Case</entry> + <entry>Upper Case</entry> + <entry>Lower Case</entry> + <entry>Upper Case</entry> + <entry>Lower Case</entry> + <entry>Upper Case</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>rcedilla</entry> + <entry>Rcedilla</entry> + <entry>eng</entry> + <entry>ENG</entry> + <entry>omacron</entry> + <entry>Omacron</entry> + </row> + <row rowsep='0'> + <entry>itilde</entry> + <entry>Itilde</entry> + <entry>amacron</entry> + <entry>Amacron</entry> + <entry>kcedilla</entry> + <entry>Kcedilla</entry> + </row> + <row rowsep='0'> + <entry>lcedilla</entry> + <entry>Lcedilla</entry> + <entry>iogonek</entry> + <entry>Iogonek</entry> + <entry>uogonek</entry> + <entry>Uogonek</entry> + </row> + <row rowsep='0'> + <entry>emacron</entry> + <entry>Emacron</entry> + <entry>eabovedot</entry> + <entry>eabovedot</entry> + <entry>utilde</entry> + <entry>Utilde</entry> + </row> + <row rowsep='0'> + <entry>gcedilla</entry> + <entry>Gcedilla</entry> + <entry>imacron</entry> + <entry>Imacron</entry> + <entry>umacron</entry> + <entry>Umacron</entry> + </row> + <row rowsep='0'> + <entry>tslash</entry> + <entry>Tslash</entry> + <entry>ncedilla</entry> + <entry>Ncedilla</entry> + <entry> </entry> + <entry> </entry> + </row> +</tbody> +</tgroup> +</informaltable> + +</sect3> +<sect3 id='capitalization_rules_for_cyrillic_keysyms'> +<title>Capitalization Rules for Cyrillic Keysyms</title> + +<para> +This table lists the Cyrillic keysyms for which XKB defines upper and lower +case: +</para> + +<informaltable frame='none'> +<tgroup cols='4'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Lower Case</entry> + <entry>Upper Case</entry> + <entry>Lower Case</entry> + <entry>Upper Case</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>Serbian_dje</entry> + <entry>Serbian_DJE</entry> + <entry>Cyrillic_i</entry> + <entry>Cyrillic_I</entry> + </row> + <row rowsep='0'> + <entry>Macedonia_gje</entry> + <entry>Macedonia_GJE</entry> + <entry>Cyrillic_shorti</entry> + <entry>Cyrillic_SHORTI</entry> + </row> + <row rowsep='0'> + <entry>Cyrillic_io</entry> + <entry>Cyrillic_IO</entry> + <entry>Cyrillic_ka</entry> + <entry>Cyrillic_KA</entry> + </row> + <row rowsep='0'> + <entry>Ukrainian_ie</entry> + <entry>Ukrainian_IE</entry> + <entry>Cyrillic_el</entry> + <entry>Cyrillic_EL</entry> + </row> + <row rowsep='0'> + <entry>Macedonia_dse</entry> + <entry>Macedonia_DSE</entry> + <entry>Cyrillic_em</entry> + <entry>Cyrillic_EM</entry> + </row> + <row rowsep='0'> + <entry>Ukrainian_i</entry> + <entry>Ukrainian_I</entry> + <entry>Cyrillic_en</entry> + <entry>Cyrillic_EN</entry> + </row> + <row rowsep='0'> + <entry>Ukrainian_yi</entry> + <entry>Ukrainian_YI</entry> + <entry>Cyrillic_o</entry> + <entry>Cyrillic_O</entry> + </row> + <row rowsep='0'> + <entry>Cyrillic_je</entry> + <entry>Cyrillic_JE</entry> + <entry>Cyrillic_pe</entry> + <entry>Cyrillic_PE</entry> + </row> + <row rowsep='0'> + <entry>Cyrillic_lje</entry> + <entry>Cyrillic_LJE</entry> + <entry>Cyrillic_ya</entry> + <entry>Cyrillic_YA</entry> + </row> + <row rowsep='0'> + <entry>Cyrillic_nje</entry> + <entry>Cyrillic_NJE</entry> + <entry>Cyrillic_er</entry> + <entry>Cyrillic_ER</entry> + </row> + <row rowsep='0'> + <entry>Serbian_tshe</entry> + <entry>Serbian_TSHE</entry> + <entry>Cyrillic_es</entry> + <entry>Cyrillic_ES</entry> + </row> + <row rowsep='0'> + <entry>Macedonia_kje</entry> + <entry>Macedonia_KJE</entry> + <entry>Cyrillic_te</entry> + <entry>Cyrillic_TE</entry> + </row> + <row rowsep='0'> + <entry>Byelorussian_shortu</entry> + <entry>Byelorussian_SHORTU</entry> + <entry>Cyrillic_u</entry> + <entry>Cyrillic_U</entry> + </row> + <row rowsep='0'> + <entry>Cyrillic_dzhe</entry> + <entry>Cyrillic_DZHE</entry> + <entry>Cyrillic_zhe</entry> + <entry>Cyrillic_ZHE</entry> + </row> + <row rowsep='0'> + <entry>Cyrillic_yu</entry> + <entry>Cyrillic_YU</entry> + <entry>Cyrillic_ve</entry> + <entry>Cyrillic_VE</entry> + </row> + <row rowsep='0'> + <entry>Cyrillic_a</entry> + <entry>Cyrillic_A</entry> + <entry>Cyrillic_softsign</entry> + <entry>Cyrillic_SOFTSIGN</entry> + </row> + <row rowsep='0'> + <entry>Cyrillic_be</entry> + <entry>Cyrillic_BE</entry> + <entry>Cyrillic_yeru</entry> + <entry>Cyrillic_YERU</entry> + </row> + <row rowsep='0'> + <entry>Cyrillic_tse</entry> + <entry>Cyrillic_TSE</entry> + <entry>Cyrillic_ze</entry> + <entry>Cyrillic_ZE</entry> + </row> + <row rowsep='0'> + <entry>Cyrillic_de</entry> + <entry>Cyrillic_DE</entry> + <entry>Cyrillic_sha</entry> + <entry>Cyrillic_SHA</entry> + </row> + <row rowsep='0'> + <entry>Cyrillic_ie</entry> + <entry>Cyrillic_IE</entry> + <entry>Cyrillic_e</entry> + <entry>Cyrillic_E</entry> + </row> + <row rowsep='0'> + <entry>Cyrillic_ef</entry> + <entry>Cyrillic_EF</entry> + <entry>Cyrillic_shcha</entry> + <entry>Cyrillic_SHCHA</entry> + </row> + <row rowsep='0'> + <entry>Cyrillic_ghe</entry> + <entry>Cyrillic_GHE</entry> + <entry>Cyrillic_che</entry> + <entry>Cyrillic_CHE</entry> + </row> + <row rowsep='0'> + <entry>Cyrillic_ha</entry> + <entry>Cyrillic_HA</entry> + <entry>Cyrillic_hardsign</entry> + <entry>Cyrillic_HARDSIGN</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +</sect3> +<sect3 id='capitalization_rules_for_greek_keysyms'> +<title>Capitalization Rules for Greek Keysyms</title> + +<para> +This table lists the Greek keysyms for which XKB defines upper and lower case: +</para> + +<informaltable frame='none'> +<tgroup cols='4'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Lower Case</entry> + <entry>Upper Case</entry> + <entry>Lower Case</entry> + <entry>Upper Case</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>Greek_omegaaccent</entry> + <entry>Greek_OMEGAACCENT</entry> + <entry>Greek_iota</entry> + <entry>Greek_IOTA</entry> + </row> + <row rowsep='0'> + <entry>Greek_alphaaccent</entry> + <entry>Greek_ALPHAACCENT</entry> + <entry>Greek_kappa</entry> + <entry>Greek_KAPPA</entry> + </row> + <row rowsep='0'> + <entry>Greek_epsilonaccent</entry> + <entry>Greek_EPSILONACCENT</entry> + <entry>Greek_lamda</entry> + <entry>Greek_LAMDA</entry> + </row> + <row rowsep='0'> + <entry>Greek_etaaccent</entry> + <entry>Greek_ETAACCENT</entry> + <entry>Greek_lambda</entry> + <entry>Greek_LAMBDA</entry> + </row> + <row rowsep='0'> + <entry>Greek_iotaaccent</entry> + <entry>Greek_IOTAACCENT</entry> + <entry>Greek_mu</entry> + <entry>Greek_MU</entry> + </row> + <row rowsep='0'> + <entry>Greek_iotadieresis</entry> + <entry>Greek_IOTADIERESIS</entry> + <entry>Greek_nu</entry> + <entry>Greek_NU</entry> + </row> + <row rowsep='0'> + <entry>Greek_omicronaccent</entry> + <entry>Greek_OMICRONACCENT</entry> + <entry>Greek_xi</entry> + <entry>Greek_XI</entry> + </row> + <row rowsep='0'> + <entry>Greek_upsilonaccent</entry> + <entry>Greek_UPSILONACCENT</entry> + <entry>Greek_omicron</entry> + <entry>Greek_OMICRON</entry> + </row> + <row rowsep='0'> + <entry>Greek_upsilondieresis</entry> + <entry>Greek_UPSILONDIERESIS</entry> + <entry>Greek_pi</entry> + <entry>Greek_PI</entry> + </row> + <row rowsep='0'> + <entry>Greek_alpha</entry> + <entry>Greek_ALPHA</entry> + <entry>Greek_rho</entry> + <entry>Greek_RHO</entry> + </row> + <row rowsep='0'> + <entry>Greek_beta</entry> + <entry>Greek_BETA</entry> + <entry>Greek_sigma</entry> + <entry>Greek_SIGMA</entry> + </row> + <row rowsep='0'> + <entry>Greek_gamma</entry> + <entry>Greek_GAMMA</entry> + <entry>Greek_tau</entry> + <entry>Greek_TAU</entry> + </row> + <row rowsep='0'> + <entry>Greek_delta</entry> + <entry>Greek_DELTA</entry> + <entry>Greek_upsilon</entry> + <entry>Greek_UPSILON</entry> + </row> + <row rowsep='0'> + <entry>Greek_epsilon</entry> + <entry>Greek_EPSILON</entry> + <entry>Greek_phi</entry> + <entry>Greek_PHI</entry> + </row> + <row rowsep='0'> + <entry>Greek_zeta</entry> + <entry>Greek_ZETA</entry> + <entry>Greek_chi</entry> + <entry>Greek_CHI</entry> + </row> + <row rowsep='0'> + <entry>Greek_eta</entry> + <entry>Greek_ETA</entry> + <entry>Greek_psi</entry> + <entry>Greek_PSI</entry> + </row> + <row rowsep='0'> + <entry>Greek_theta</entry> + <entry>Greek_THETA</entry> + <entry>Greek_omega</entry> + <entry>Greek_OMEGA</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +</sect3> +<sect3 id='capitalization_rules_for_other_keysyms'> +<title>Capitalization Rules for Other Keysyms</title> + +<para> +XKB defines no capitalization rules for symbols in any other set of keysyms +provided by the consortium. Applications are free to apply additional rules for +private keysyms or for other keysyms not covered by XKB. +</para> +</sect3> +</sect2> +</sect1> +</appendix> diff --git a/specs/appB.xml b/specs/appB.xml new file mode 100644 index 0000000..beac787 --- /dev/null +++ b/specs/appB.xml @@ -0,0 +1,129 @@ +<appendix id='canonical_key_types'> +<title>Canonical Key Types</title> + +<sect1 id='canonical_key_types2'> +<title>Canonical Key Types</title> +<sect2 id='the_one_level_key_type'> +<title>The ONE_LEVEL Key Type</title> + +<para> +The <emphasis> +ONE_LEVEL</emphasis> + key type describes groups that have only one symbol. The default <emphasis> +ONE_LEVEL</emphasis> + type has no map entries and does not pay attention to any modifiers. +</para> + +</sect2> +<sect2 id='the_two_level_key_type'> +<title>The TWO_LEVEL Key Type</title> + +<para> +The <emphasis> +TWO_LEVEL</emphasis> + key type describes groups that have two symbols but are neither alphabetic nor +numeric keypad keys. The default <emphasis> +TWO_LEVEL</emphasis> + type uses only the <emphasis> +Shift</emphasis> + modifier. It returns level two if <emphasis> +Shift</emphasis> + is set, level one if it is not. +</para> + + +</sect2> +<sect2 id='the_alphabetic_key_type'> +<title>The ALPHABETIC Key Type</title> + +<para> +The <emphasis> +ALPHABETIC</emphasis> + key type describes groups that consist of two symbols — the lowercase form +of a symbol followed by the uppercase form of the same symbol. The default +<emphasis> +ALPHABETIC</emphasis> + type implements locale-sensitive "shift cancels caps lock" behavior using both +the <emphasis> +Shift</emphasis> + and <emphasis> +Lock</emphasis> + modifiers as follows: +</para> + +<itemizedlist> +<listitem> + <para>If <emphasis> +Shift</emphasis> + and <emphasis> +Lock</emphasis> + are both set, the default <emphasis> +ALPHABETIC</emphasis> + type yields level one. + </para> +</listitem> +<listitem> + <para>If <emphasis> +Shift</emphasis> + alone is set, it yields level two. + </para> +</listitem> +<listitem> + <para>If <emphasis> +Lock</emphasis> + alone is set, it yields level one but preserves the <emphasis> +Lock</emphasis> + modifier. + </para> +</listitem> +<listitem> + <para>If neither <emphasis> +Shift</emphasis> + nor <emphasis> +Lock</emphasis> + are set, it yields level one. + </para> +</listitem> +</itemizedlist> + +</sect2> +<sect2 id='the_keypad_key_type'> +<title>The KEYPAD Key Type</title> + +<para> +The <emphasis> +KEYPAD</emphasis> + key type describes that consist of two symbols, at least one of which is a +numeric keypad symbol. The default <emphasis> +KEYPAD</emphasis> + type implements "shift cancels numeric lock" behavior using the <emphasis> +Shift</emphasis> + modifier and the real modifier bound to the virtual modifier named "NumLock" +(the "NumLock" modifier) as follows: +</para> + +<itemizedlist> +<listitem> + <para>If <emphasis> +Shift</emphasis> + and the "NumLock" modifier are both set, the default <emphasis> +KEYPAD </emphasis> +type yields level one. + </para> +</listitem> +<listitem> + <para>If either <emphasis> +Shift</emphasis> + or the "NumLock" modifier alone are set, it yields level two. + </para> +</listitem> +</itemizedlist> + +<para> +If neither <emphasis> +Shift</emphasis> + nor the "NumLock" modifier are set, it yields level one. +</para> +</sect2> +</sect1> +</appendix> diff --git a/specs/appC.xml b/specs/appC.xml new file mode 100644 index 0000000..d34c9a6 --- /dev/null +++ b/specs/appC.xml @@ -0,0 +1,710 @@ +<appendix id='new_keysyms'> +<title>New KeySyms</title> + +<sect1 id='new_keysymsb'> +<title>New KeySyms</title> +<sect2 id='keysyms_used_by_the_iso9995_standard'> +<title>KeySyms Used by the ISO9995 Standard</title> +<informaltable frame='none'> +<tgroup cols='4'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Byte 3</entry> + <entry>Byte 4</entry> + <entry>Character</entry> + <entry>Name</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>254</entry> + <entry>1</entry> + <entry> </entry> + <entry>ISO LOCK</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>2</entry> + <entry> </entry> + <entry>ISO LATCHING LEVEL TWO SHIFT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>3</entry> + <entry> </entry> + <entry>ISO LEVEL THREE SHIFT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>4</entry> + <entry> </entry> + <entry>ISO LATCHING LEVEL THREE SHIFT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>5</entry> + <entry> </entry> + <entry>ISO LEVEL THREE SHIFT LOCK</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>6</entry> + <entry> </entry> + <entry>ISO LATCHING GROUP SHIFT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>7</entry> + <entry> </entry> + <entry>ISO GROUP SHIFT LOCK</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>8</entry> + <entry> </entry> + <entry>ISO NEXT GROUP</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>9</entry> + <entry> </entry> + <entry>ISO LOCK NEXT GROUP</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>10</entry> + <entry> </entry> + <entry>ISO PREVIOUS GROUP</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>11</entry> + <entry> </entry> + <entry>ISO LOCK PREVIOUS GROUP</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>12</entry> + <entry> </entry> + <entry>ISO FIRST GROUP</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>13</entry> + <entry> </entry> + <entry>ISO LOCK FIRST GROUP</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>14</entry> + <entry> </entry> + <entry>ISO LAST GROUP</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>15</entry> + <entry> </entry> + <entry>ISO LOCK LAST GROUP</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>32</entry> + <entry> </entry> + <entry>LEFT TAB</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>33</entry> + <entry> </entry> + <entry>MOVE LINE UP</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>34</entry> + <entry> </entry> + <entry>MOVE LINE DOWN</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>35</entry> + <entry> </entry> + <entry>PARTIAL LINE UP</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>36</entry> + <entry> </entry> + <entry>PARTIAL LINE DOWN</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>37</entry> + <entry> </entry> + <entry>PARTIAL SPACE LEFT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>38</entry> + <entry> </entry> + <entry>PARTIAL SPACE RIGHT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>39</entry> + <entry> </entry> + <entry>SET MARGIN LEFT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>40</entry> + <entry> </entry> + <entry>SET MARGIN RIGHT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>41</entry> + <entry> </entry> + <entry>RELEASE MARGIN LEFT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>42</entry> + <entry> </entry> + <entry>RELEASE MARGIN RIGHT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>43</entry> + <entry> </entry> + <entry>RELEASE MARGIN LEFT AND RIGHT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>44</entry> + <entry> </entry> + <entry>FAST CURSOR LEFT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>45</entry> + <entry> </entry> + <entry>FAST CURSOR RIGHT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>46</entry> + <entry> </entry> + <entry>FAST CURSOR UP</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>47</entry> + <entry> </entry> + <entry>FAST CURSOR DOWN</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>48</entry> + <entry> </entry> + <entry>CONTINUOUS UNDERLINE</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>49</entry> + <entry> </entry> + <entry>DISCONTINUOUS UNDERLINE</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>50</entry> + <entry> </entry> + <entry>EMPHASIZE</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>51</entry> + <entry> </entry> + <entry>CENTER OBJECT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>52</entry> + <entry> </entry> + <entry>ISO_ENTER</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +</sect2> +<sect2 id='keysyms_used_to_control_the_core_pointer'> +<title>KeySyms Used to Control The Core Pointer</title> +<informaltable frame='none'> +<tgroup cols='4'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Byte 3</entry> + <entry>Byte 4</entry> + <entry>Character</entry> + <entry>Name</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>254</entry> + <entry>224</entry> + <entry> </entry> + <entry>POINTER LEFT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>225</entry> + <entry> </entry> + <entry>POINTER RIGHT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>226</entry> + <entry> </entry> + <entry>POINTER UP</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>227</entry> + <entry> </entry> + <entry>POINTER DOWN</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>228</entry> + <entry> </entry> + <entry>POINTER UP AND LEFT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>229</entry> + <entry> </entry> + <entry>POINTER UP AND RIGHT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>230</entry> + <entry> </entry> + <entry>POINTER DOWN AND LEFT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>231</entry> + <entry> </entry> + <entry>POINTER DOWN AND RIGHT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>232</entry> + <entry> </entry> + <entry>DEFAULT POINTER BUTTON</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>233</entry> + <entry> </entry> + <entry>POINTER BUTTON ONE</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>234</entry> + <entry> </entry> + <entry>POINTER BUTTON TWO</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>235</entry> + <entry> </entry> + <entry>POINTER BUTTON THREE</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>236</entry> + <entry> </entry> + <entry>POINTER BUTTON FOUR</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>237</entry> + <entry> </entry> + <entry>POINTER BUTTON FIVE</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>238</entry> + <entry> </entry> + <entry>DEFAULT POINTER BUTTON DOUBLE CLICK</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>239</entry> + <entry> </entry> + <entry>POINTER BUTTON ONE DOUBLE CLICK</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>240</entry> + <entry> </entry> + <entry>POINTER BUTTON TWO DOUBLE CLICK</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>241</entry> + <entry> </entry> + <entry>POINTER BUTTON THREE DOUBLE CLICK</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>242</entry> + <entry> </entry> + <entry>POINTER BUTTON FOUR DOUBLE CLICK</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>243</entry> + <entry> </entry> + <entry>POINTER BUTTON FIVE DOUBLE CLICK</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>244</entry> + <entry> </entry> + <entry>DRAG DEFAULT POINTER BUTTON</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>245</entry> + <entry> </entry> + <entry>DRAG POINTER BUTTON ONE</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>246</entry> + <entry> </entry> + <entry>DRAG POINTER BUTTON TWO</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>247</entry> + <entry> </entry> + <entry>DRAG POINTER BUTTON THREE</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>248</entry> + <entry> </entry> + <entry>DRAG POINTER BUTTON FOUR</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>249</entry> + <entry> </entry> + <entry>ENABLE POINTER FROM KEYBOARD</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>250</entry> + <entry> </entry> + <entry>ENABLE KEYBOARD POINTER ACCEL</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>251</entry> + <entry> </entry> + <entry>SET DEFAULT POINTER BUTTON NEXT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>252</entry> + <entry> </entry> + <entry>SET DEFAULT POINTER BUTTON PREVIOUS</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>253</entry> + <entry> </entry> + <entry>DRAG POINTER BUTTON FIVE</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +</sect2> +<sect2 id='keysyms_used_to_change_keyboard_controls'> +<title>KeySyms Used to Change Keyboard Controls</title> +<informaltable frame='none'> +<tgroup cols='4'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Byte 3</entry> + <entry>Byte 4</entry> + <entry>Character</entry> + <entry>Name</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>254</entry> + <entry>112</entry> + <entry> </entry> + <entry>ENABLE ACCESSX KEYS</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>113</entry> + <entry> </entry> + <entry>ENABLE ACCESSX FEEDBACK</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>114</entry> + <entry> </entry> + <entry>TOGGLE REPEAT KEYS</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>115</entry> + <entry> </entry> + <entry>TOGGLE SLOW KEYS</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>116</entry> + <entry> </entry> + <entry>ENABLE BOUNCE KEYS</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>117</entry> + <entry> </entry> + <entry>ENABLE STICKY KEYS</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>118</entry> + <entry> </entry> + <entry>ENABLE MOUSE KEYS</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>119</entry> + <entry> </entry> + <entry>ENABLE MOUSE KEYS ACCELERATION</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>120</entry> + <entry> </entry> + <entry>ENABLE OVERLAY1</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>121</entry> + <entry> </entry> + <entry>ENABLE OVERLAY2</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>122</entry> + <entry> </entry> + <entry>ENABLE AUDIBLE BELL</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +</sect2> +<sect2 id='keysyms_used_to_control_the_server'> +<title>KeySyms Used To Control The Server</title> +<informaltable frame='none'> +<tgroup cols='4'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Byte</entry> + <entry>Byte</entry> + <entry>Character</entry> + <entry>Name</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>254</entry> + <entry>208</entry> + <entry> </entry> + <entry>FIRST SCREEN</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>209</entry> + <entry> </entry> + <entry>PREVIOUS SCREEN</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>210</entry> + <entry> </entry> + <entry>NEXT SCREEN</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>211</entry> + <entry> </entry> + <entry>LAST SCREEN</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>212</entry> + <entry> </entry> + <entry>TERMINATE SERVER</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +</sect2> +<sect2 id='keysyms_for_non_spacing_diacritical_keys'> +<title>KeySyms for Non-Spacing Diacritical Keys</title> +<informaltable frame='none'> +<tgroup cols='4'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Byte</entry> + <entry>Byte</entry> + <entry>Character</entry> + <entry>Name</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>254</entry> + <entry>80</entry> + <entry> </entry> + <entry>DEAD GRAVE ACCENT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>81</entry> + <entry> </entry> + <entry>DEAD ACUTE ACCENT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>82</entry> + <entry> </entry> + <entry>DEAD CIRCUMFLEX</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>83</entry> + <entry> </entry> + <entry>DEAD TILDE</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>84</entry> + <entry> </entry> + <entry>DEAD MACRON</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>85</entry> + <entry> </entry> + <entry>DEAD BREVE</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>86</entry> + <entry> </entry> + <entry>DEAD DOT ABOVE</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>87</entry> + <entry> </entry> + <entry>DEAD DIAERESIS</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>88</entry> + <entry> </entry> + <entry>DEAD RING ABOVE</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>89</entry> + <entry> </entry> + <entry>DEAD DOUBLE ACUTE ACCENT</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>90</entry> + <entry> </entry> + <entry>DEAD CARON</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>91</entry> + <entry> </entry> + <entry>DEAD CEDILLA</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>92</entry> + <entry> </entry> + <entry>DEAD OGONEK</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>93</entry> + <entry> </entry> + <entry>DEAD IOTA</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>94</entry> + <entry> </entry> + <entry>DEAD VOICED SOUND</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>95</entry> + <entry> </entry> + <entry>DEAD SEMI VOICED SOUND</entry> + </row> + <row rowsep='0'> + <entry>254</entry> + <entry>96</entry> + <entry> </entry> + <entry>DEAD DOT BELOW</entry> + </row> +</tbody> +</tgroup> +</informaltable> +</sect2> +</sect1> +</appendix> diff --git a/specs/appD.xml b/specs/appD.xml new file mode 100644 index 0000000..abda53c --- /dev/null +++ b/specs/appD.xml @@ -0,0 +1,2096 @@ +<appendix id='protocol_encoding'> +<title>Protocol Encoding</title> + +<sect1 id='syntactic_conventions'> +<title>Syntactic Conventions</title> + +<para> +This document uses the same syntactic conventions as the encoding of the core X +protocol, with the following additions: +</para> + +<para> +A LISTofITEMs contains zero or more items of variable type and size. The encode +form for a LISTofITEMs is: +</para> + +<literallayout class='monospaced'> +v LISTofITEMs NAME + + TYPE MASK-EXPRESSION + value1 corresponding field(s) + ... + valuen corresponding field(s) +</literallayout> + +<para> +The MASK-EXPRESSION is an expression using C-style boolean operators and fields +of the request which specifies the bitmask used to determine whether or not a +mem ber of the LISTofITEMs is present. If present, TYPE specifies the +interpretation of the resulting bitmask and the values are listed using the +symbolic names of the members of the set. If TYPE is blank, the values are +numeric constants. +</para> + + +<para> +It is possible for a single bit in the MASK-EXPRESSION to control more than one +ITEM — if the bit is set, all listed ITEMs are present. It is also possible +for multiple bits in the MASK-EXPRESSION to control a single ITEM — if any of +the bits associated with an ITEM are set, it is present in the LISTofITEMs. +</para> + + +<para> +The size of a LISTofITEMS is derived from the items that are present in the +list, so it is always given as a variable in the request description, and the +request is followed by a section of the form: +</para> + +<literallayout class='monospaced'> +ITEMs +encode-form +... +encode-form +</literallayout> + +<para> +listing an encode-form for each ITEM. The NAME in each encode-form keys to the +fields listed as corresponding to each bit in the MASK-EXPRESSION. Items are +not necessarily the same size, and the size specified in the encoding form is +the size that the item occupies if it is present. +</para> + + +<para> +Some types are of variable size. The encode-form for a list of items of a +single type but variable size is: +</para> + +<literallayout class='monospaced'> +S0+..Ss LISTofTYPE name +</literallayout> + +<para> +Which indicates that the list has <emphasis> +s</emphasis> + elements of variable size and that the size of the list is the sum of the +sizes of all of the elements that make up the list. The notation Sn refers to +the size of the <emphasis> +n</emphasis> +th element of the list and the notation S* refers to the size of the list as a +whole. +</para> + + +<para> +The definition of a type of variable size includes an expression which +specifies the size. The size is specified as a constant plus a variable +expression; the constant specifies the size of the fields that are always +present and the variables which make up the variable expression are defined in +the constant portion of the structure. For example, the following definition +specifies a counted string with a two-byte length field preceding the string: +</para> + + +<literallayout class='monospaced'> +TYPE 2+n+p +2 n length +n STRING8 string +p unused,p=pad(n) +</literallayout> + +<para> +Some fields are optional. The size of an optional field has the form: +"[<emphasis> +expr</emphasis> +]" where expr specifies the size of the field if it is present. An explanation +of the conditions under which the field is present follows the name in the +encode form: +</para> + +<literallayout class='monospaced'> +1 BOOL more +3 unused +[4] CARD32 optData, if more==TRUE +</literallayout> + +<para> +This portion of the structure is four bytes long if more is FALSE or eight +bytes long if more is TRUE. This notation can also be used in size expressions; +for example, the size of the previous structure is written as "4+[4]" bytes. +</para> + + +</sect1> +<sect1 id='common_types2'> +<title>Common Types</title> +<literallayout class='monospaced'> +SETofKB_EVENTTYPE + #x0001 XkbNewKeyboardNotify + #x0002 XkbMapNotify + #x0004 XkbStateNotify + #x0008 XkbControlsNotify + #x0010 XkbIndicatorStateNotify + #x0020 XkbIndicatorMapNotify + #x0040 XkbNamesNotify + #x0080 XkbCompatMapNotify + #x0100 XkbBellNotify + #x0200 XkbActionMessage + #x0400 XkbAccessXNotify + #x0800 XkbExtensionDeviceNotify +</literallayout> + +<literallayout class='monospaced'>SETofKB_NKNDETAIL + #x01 XkbNKN_Keycodes + #x02 XkbNKN_Geometry + #x04 XkbNKN_DeviceID +</literallayout> + +<literallayout class='monospaced'>SETofKB_AXNDETAIL + #x01 XkbAXN_SKPress + #x02 XkbAXN_SKAccept + #x04 XkbAXN_SKReject + #x08 XkbAXN_SKRelease + #x10 XkbAXN_BKAccept + #x20 XkbAXN_BKReject + #x40 XkbAXN_AXKWarning +</literallayout> + +<literallayout class='monospaced'>SETofKB_MAPPART + #x0001 XkbKeyTypes + #x0002 XkbKeySyms + #x0004 XkbModifierMap + #x0008 XkbExplicitComponents + #x0010 XkbKeyActions + #x0020 XkbKeyBehaviors + #x0040 XkbVirtualMods + #x0080 XkbVirtualModMap +</literallayout> + +<literallayout class='monospaced'>SETofKB_STATEPART + #x0001 XkbModifierState + #x0002 XkbModifierBase + #x0004 XkbModifierLatch + #x0008 XkbModifierLock + #x0010 XkbGroupState + #x0020 XkbGroupBase + #x0040 XkbGroupLatch + #x0080 XkbGroupLock + #x0100 XkbCompatState + #x0200 XkbGrabMods + #x0400 XkbCompatGrabMods + #x0800 XkbLookupMods + #x1000 XkbCompatLookupMods + #x2000 XkbPointerButtons +</literallayout> + +<literallayout class='monospaced'>SETofKB_BOOLCTRL + #x00000001 XkbRepeatKeys + #x00000002 XkbSlowKeys + #x00000004 XkbBounceKeys + #x00000008 XkbStickyKeys + #x00000010 XkbMouseKeys + #x00000020 XkbMouseKeysAccel + #x00000040 XkbAccessXKeys + #x00000080 XkbAccessXTimeoutMask + #x00000100 XkbAccessXFeedbackMask + #x00000200 XkbAudibleBellMask + #x00000400 XkbOverlay1Mask + #x00000800 XkbOverlay2Mask + #x00001000 XkbIgnoreGroupLockMask +</literallayout> + +<literallayout class='monospaced'>SETofKB_CONTROL + Encodings are the same as for SETofKB_BOOLCTRL, with the addition of: + #x080000000 XkbGroupsWrap + #x100000000 XkbInternalMods + #x200000000 XkbIgnoreLockMods + #x400000000 XkbPerKeyRepeat + #x800000000 XkbControlsEnabled +</literallayout> + +<literallayout class='monospaced'>SETofKB_AXFBOPT + #x0001 XkbAX_SKPressFB + #x0002 XkbAX_SKAcceptFB + #x0004 XkbAX_FeatureFB + #x0008 XkbAX_SlowWarnFB + #x0010 XkbAX_IndicatorFB + #x0020 XkbAX_StickyKeysFB + #x0100 XkbAX_SKReleaseFB + #x0200 XkbAX_SKRejectFB + #x0400 XkbAX_BKRejectFB + #x0800 XkbAX_DumbBell +</literallayout> + +<literallayout class='monospaced'>SETofKB_AXSKOPT + #x0040 XkbAX_TwoKeys + #x0080 XkbAX_LatchToLock +</literallayout> + +<literallayout class='monospaced'>SETofKB_AXOPTION + Encoding same as the bitwise union of : + SETofKB_AXFBOPT + SETofKB_AXSKOPT +</literallayout> + +<literallayout class='monospaced'>KB_DEVICESPEC + 0..255 input extension device id + #x100 XkbUseCoreKbd + #x200 XkbUseCorePtr +</literallayout> + +<literallayout class='monospaced'>KB_LEDCLASSRESULT + 0 KbdFeedbackClass + 4 LedFeedbackClass +</literallayout> + +<literallayout class='monospaced'>KB_LEDCLASSSPEC + Encoding same as KB_LEDCLASSRESULT, with the addition of: + #x0300 XkbDfltXIClass + #x0500 XkbAllXIClasses +</literallayout> + +<literallayout class='monospaced'>KB_BELLCLASSRESULT + 0 KbdFeedbackClass + 5 BellFeedbackClass +</literallayout> + +<literallayout class='monospaced'>KB_BELLCLASSSPEC + Encoding same as KB_BELLCLASSRESULT, with the addition of: + #x0300 XkbDfltXIClass +</literallayout> + +<literallayout class='monospaced'>KB_IDSPEC + 0..255 input extension feedback id + #x0400 XkbDfltXIId +</literallayout> + +<literallayout class='monospaced'>KB_IDRESULT + Encoding same as KB_IDSPEC, with the addition of: + #xff00 XkbXINone +</literallayout> + +<literallayout class='monospaced'>KB_MULTIIDSPEC + encodings same as KB_IDSPEC, with the addition of: + #x0500 XkbAllXIIds +</literallayout> + +<literallayout class='monospaced'>KB_GROUP + 0 XkbGroup1 + 1 XkbGroup2 + 2 XkbGroup3 + 3 XkbGroup4 +</literallayout> + +<literallayout class='monospaced'>KB_GROUPS + Encoding same as KB_GROUP, with the addition of: + 254 XkbAnyGroup + 255 XkbAllGroups +</literallayout> + +<literallayout class='monospaced'>SETofKB_GROUP + #x01 XkbGroup1 + #x02 XkbGroup2 + #x04 XkbGroup3 + #x08 XkbGroup4 +</literallayout> + +<literallayout class='monospaced'>SETofKB_GROUPS + Encoding same as SETofKB_GROUP, with the addition of: + #x80 XkbAnyGroup +</literallayout> + +<literallayout class='monospaced'>KB_GROUPSWRAP + #x00 XkbWrapIntoRange + #x40 XkbClampIntoRange + #x80 XkbRedirectIntoRange +</literallayout> + +<literallayout class='monospaced'>SETofKB_VMODSHIGH + #x80 virtual modifier 15 + #x40 virtual modifier 14 + #x20 virtual modifier 13 + #x10 virtual modifier 12 + #x08 virtual modifier 11 + #x04 virtual modifier 10 + #x02 virtual modifier 9 + #x01 virtual modifier 8 +</literallayout> + +<literallayout class='monospaced'>SETofKB_VMODSLOW + #x80 virtual modifier 7 + #x40 virtual modifier 6 + #x20 virtual modifier 5 + #x10 virtual modifier 4 + #x08 virtual modifier 3 + #x04 virtual modifier 2 + #x02 virtual modifier 1 + #x01 virtual modifier 0 +</literallayout> + +<literallayout class='monospaced'>SETofKB_VMOD + #x8000 virtual modifier 15 + #x4000 virtual modifier 14 + #x2000 virtual modifier 13 + #x1000 virtual modifier 12 + #x0800 virtual modifier 11 + #x0400 virtual modifier 10 + #x0200 virtual modifier 9 + #x0100 virtual modifier 8 + #x0080 virtual modifier 7 + #x0040 virtual modifier 6 + #x0020 virtual modifier 5 + #x0010 virtual modifier 4 + #x0008 virtual modifier 3 + #x0004 virtual modifier 2 + #x0002 virtual modifier 1 + #x0001 virtual modifier 0 +</literallayout> + +<literallayout class='monospaced'>SETofKB_EXPLICIT + #x80 XkbExplicitVModMap + #x40 XkbExplicitBehavior + #x20 XkbExplicitAutoRepeat + #x10 XkbExplicitInterpret + #x08 XkbExplicitKeyType4 + #x04 XkbExplicitKeyType3 + #x02 XkbExplicitKeyType2 + #x01 XkbExplicitKeyType1 +</literallayout> + +<literallayout class='monospaced'>KB_SYMINTERPMATCH + #x80 XkbSI_LevelOneOnly + #x7f operation, one of the following: + 0 XkbSI_NoneOf + 1 XkbSI_AnyOfOrNone + 2 XkbSI_AnyOf + 3 XkbSI_AllOf + 4 XkbSI_Exactly +</literallayout> + +<literallayout class='monospaced'>SETofKB_IMFLAG + #x80 XkbIM_NoExplicit + #x40 XkbIM_NoAutomatic + #x20 XkbIM_LEDDrivesKB +</literallayout> + +<literallayout class='monospaced'>SETofKB_IMMODSWHICH + #x10 XkbIM_UseCompat + #x08 XkbIM_UseEffective + #x04 XkbIM_UseLocked + #x02 XkbIM_UseLatched + #x01 XkbIM_UseBase +</literallayout> + +<literallayout class='monospaced'>SETofKB_IMGROUPSWHICH + #x10 XkbIM_UseCompat + #x08 XkbIM_UseEffective + #x04 XkbIM_UseLocked + #x02 XkbIM_UseLatched + #x01 XkbIM_UseBase +</literallayout> + +<literallayout class='monospaced'>KB_INDICATORMAP +1 SETofKB_IMFLAGS flags +1 SETofKB_IMGROUPSWHICH whichGroups +1 SETofKB_GROUP groups +1 SETofKB_IMMODSWHICH whichMods +1 SETofKEYMASK mods +1 SETofKEYMASK realMods +2 SETofKB_VMOD vmods +4 SETofKB_BOOLCTRL ctrls +</literallayout> + +<literallayout class='monospaced'>SETofKB_CMDETAIL + #x01 XkbSymInterp + #x02 XkbGroupCompat +</literallayout> + +<literallayout class='monospaced'>SETofKB_NAMEDETAIL + #x0001 XkbKeycodesName + #x0002 XkbGeometryName + #x0004 XkbSymbolsName + #x0008 XkbPhysSymbolsName + #x0010 XkbTypesName + #x0020 XkbCompatName + #x0040 XkbKeyTypeNames + #x0080 XkbKTLevelNames + #x0100 XkbIndicatorNames + #x0200 XkbKeyNames + #x0400 XkbKeyAliases + #x0800 XkbVirtualModNames + #x1000 XkbGroupNames + #x2000 XkbRGNames +</literallayout> + +<literallayout class='monospaced'>SETofKB_GBNDETAIL + #x01 XkbGBN_Types + #x02 XkbGBN_CompatMap + #x04 XkbGBN_ClientSymbols + #x08 XkbGBN_ServerSymbols + #x10 XkbGBN_IndicatorMaps + #x20 XkbGBN_KeyNames + #x40 XkbGBN_Geometry + #x80 XkbGBN_OtherNames +</literallayout> + +<literallayout class='monospaced'>SETofKB_XIEXTDEVFEATURE + #x02 XkbXI_ButtonActions + #x04 XkbXI_IndicatorNames + #x08 XkbXI_IndicatorMaps + #x10 XkbXI_IndicatorState +</literallayout> + +<literallayout class='monospaced'>SETofKB_XIFEATURE + Encoding same as SETofKB_XIEXTDEVFEATURE, with the addition of: + #x01 XkbXI_Keyboards +</literallayout> + +<literallayout class='monospaced'>SETofKB_XIDETAIL + Encoding same as SETofKB_XIFEATURE, with the addition of: + #x8000 XkbXI_UnsupportedFeature +</literallayout> + +<literallayout class='monospaced'>SETofKB_PERCLIENTFLAG + #x01 XkbDetectableAutorepeat + #x02 XkbGrabsUseXKBState + #x04 XkbAutoResetControls + #x08 XkbLookupStateWhenGrabbed + #x10 XkbSendEventUsesXKBState +</literallayout> + +<literallayout class='monospaced'>KB_MODDEF +1 SETofKEYMASK mask +1 SETofKEYMASK realMods +2 SETofVMOD vmods +</literallayout> + +<literallayout class='monospaced'>KB_COUNTED_STRING8 +1 l length +l STRING8 string +</literallayout> + +<literallayout class='monospaced'>KB_COUNTED_STRING16 +2 l length +l STRING8 string +</literallayout> + +<literallayout class='monospaced'>KB_COUNTED_STRING16 +p unused,p=pad(2+l) +</literallayout> + +</sect1> +<sect1 id='errors2'> +<title>Errors</title> + +<literallayout class='monospaced'>1 0 Error +2 ?? code +2 CARD16 sequence +4 CARD32 error value + most significant 8 bits of error value have the meaning: + 0xff XkbErrBadDevice + 0xfe XkbErrBadClass + 0xfd XkbErrBadId + the least significant 8 bits of the error value contain the device id, +class, or feedback + id which failed. +2 CARD16 minor opcode +1 CARD8 major opcode +21 unused +</literallayout> + +</sect1> +<sect1 id='key_actions2'> +<title>Key Actions</title> + +<literallayout class='monospaced'>1 0 type +7 unused +</literallayout> + +<literallayout class='monospaced'>1 1 type +1 BITMASK flags + #x01 XkbSA_ClearLocks + #x02 XkbSA_LatchToLock + #x04 XkbSA_UseModMapMods +1 SETofKEYMASK mask +1 SETofKEYMASK real modifiers +1 SETofKB_VMODSHIGH virtual modifiers high +1 SETofKB_VMODSLOW virtual modifiers low +2 unused +</literallayout> + +<literallayout class='monospaced'>1 2 type +1 BITMASK flags + #x01 XkbSA_ClearLocks + #x02 XkbSA_LatchToLock + #x04 XkbSA_UseModMapMods +1 SETofKEYMASK mask +1 SETofKEYMASK real modifiers +1 SETofKB_VMODSHIGH virtual modifiers high +1 SETofKB_VMODSLOW virtual modifiers low +2 unused +</literallayout> + +<literallayout class='monospaced'>1 3 type +1 BITMASK flags + #x01 XkbSA_LockNoLock + #x02 XkbSA_LockNoUnlock + #x04 XkbSA_UseModMapMods +1 SETofKEYMASK mask +1 SETofKEYMASK real modifiers +1 SETofKB_VMODSHIGH virtual modifiers high +1 SETofKB_VMODSLOW virtual modifiers low +2 unused +</literallayout> + +<literallayout class='monospaced'>1 4 type +1 BITMASK flags + #x01 XkbSA_ClearLocks + #x02 XkbSA_LatchToLock + #x04 XkbSA_GroupAbsolute +1 INT8 group +5 unused +</literallayout> + +<literallayout class='monospaced'>1 5 type +1 BITMASK flags + #x01 XkbSA_ClearLocks + #x02 XkbSA_LatchToLock + #x04 XkbSA_GroupAbsolute +1 INT8 group +5 unused +</literallayout> + +<literallayout class='monospaced'>1 6 type +1 BITMASK flags + #x01 XkbSA_LockNoLock + #x02 XkbSA_LockNoUnlock + #x04 XkbSA_GroupAbsolute +1 INT8 group +5 unused +</literallayout> + +<literallayout class='monospaced'>1 7 type +1 BITMASK flags + #x01 XkbSA_NoAcceleration + #x02 XkbSA_MoveAbsoluteX + #x04 XkbSA_MoveAbsoluteY +1 INT8 x high +1 CARD8 x low +1 INT8 y high +1 CARD8 y low +2 unused +</literallayout> + +<literallayout class='monospaced'>1 8 type +1 BITMASK flags +1 CARD8 count +1 CARD8 button +4 unused +</literallayout> + +<literallayout class='monospaced'>1 9 type +1 BITMASK flags +1 unused +1 CARD8 button +4 unused +</literallayout> + +<literallayout class='monospaced'>1 10 type +1 BITMASK flags + #x02 XkbSA_DfltBtnAbsolute +1 BITMASK affect + #x01 XkbSA_AffectDfltBtn +1 INT8 value +4 unused +</literallayout> + +<literallayout class='monospaced'>1 11 type +1 BITMASK flags + #x01 XkbSA_LockNoLock + #x02 XkbSA_LockNoUnlock + #x04 XkbSA_UseModMapMods (if SA_ISODfltIsGroup is 0) + #x04 XkbSA_GroupAbsolute (if SA_ISODfltIsGroup is 1) + #x80 XkbSA_ISODfltIsGroup +1 SETofKEYMASK mask +1 SETofKEYMASK real modifiers +1 INT8 group +1 BITMASK affect + #x08 XkbSA_ISONoAffectCtrls + #x10 XkbSA_ISONoAffectPtr + #x20 XkbSA_ISONoAffectGroup + #x40 XkbSA_ISONoAffectMods +1 SETofKB_VMODSHIGH virtual modifiers high +1 SETofKB_VMODSLOW virtual modifiers low +</literallayout> + +<literallayout class='monospaced'>1 12 type +7 unused +</literallayout> + +<literallayout class='monospaced'>1 13 type +1 BITMASK flags + #x01 XkbSA_SwitchApplication + #x04 XkbSA_SwitchAbsolute +1 INT8 new screen +5 unused (must be 0) +</literallayout> + +<literallayout class='monospaced'>1 14 type +3 unused (must be 0) +1 BITMASK boolean controls high + #x01 XkbAccessXFeedbackMask + #x02 XkbAudibleBellMask + #x04 XkbOverlay1Mask + #x08 XkbOverlay2Mask + #x10 XkbIgnoreGroupLockMask +1 BITMASK boolean controls low + #x01 XkbRepeatKeys + #x02 XkbSlowKeys + #x04 XkbBounceKeys + #x08 XkbStickyKeys + #x10 XkbMouseKeys + #x20 XkbMouseKeysAccel + #x40 XkbAccessXKeys + #x80 XkbAccessXTimeoutMask +2 unused (must be 0) +</literallayout> + +<literallayout class='monospaced'>1 15 type +3 unused (must be 0) +1 BITMASK boolean controls high + #x01 XkbAccessXFeedbackMask + #x02 XkbAudibleBellMask + #x04 XkbOverlay1Mask + #x08 XkbOverlay2Mask + #x10 XkbIgnoreGroupLockMask +1 BITMASK boolean controls low + #x01 XkbRepeatKeys + #x02 XkbSlowKeys + #x04 XkbBounceKeys + #x08 XkbStickyKeys + #x10 XkbMouseKeys + #x20 XkbMouseKeysAccel + #x40 XkbAccessXKeys + #x80 XkbAccessXTimeoutMask +</literallayout> + +<literallayout class='monospaced'>1 16 type +2 unused (must be 0) +</literallayout> + +<literallayout class='monospaced'>1 16 type +1 BITMASK flags + #x01 XkbSA_MessageOnPress + #x02 XkbSA_MessageOnRelease + #x04 XkbSA_MessageGenKeyEvent +6 STRING message +</literallayout> + +<literallayout class='monospaced'>1 17 type +1 KEYCODE new key +1 SETofKEYMASK mask +1 SETofKEYMASK real modifiers +1 SETofKB_VMODSHIGH virtual modfiiers mask high +1 SETofKB_VMODSLOW virtual modifiers mask low +1 SETofKB_VMODSHIGH virtual modifiers high +1 SETofKB_VMODSLOW virtual modfiers low +</literallayout> + +<literallayout class='monospaced'>1 18 type +1 0 flags +1 CARD8 count +1 CARD8 button +1 CARD8 device +3 unused (must be 0) +</literallayout> + +<literallayout class='monospaced'>1 19 type +1 BITMASK flags + #x01 XkbSA_LockNoLock + #x02 XkbSA_LockNoUnlock +1 unused +1 CARD8 button +1 CARD8 device +</literallayout> + +<literallayout class='monospaced'>1 20 type +1 CARD8 device +1 KB_SA_VALWHAT valuator 1 what + #x00 XkbSA_IgnoreVal + #x01 XkbSA_SetValMin + #x02 XkbSA_SetValCenter + #x03 XkbSA_SetValMax + #x04 XkbSA_SetValRelative + #x05 XkbSA_SetValAbsolute +1 CARD8 valuator 1 index +1 CARD8 valuator 1 value +1 KB_SA_VALWHAT valuator 2 what + Encodings as for "valuator 1 what" above +1 CARD8 valuator 2 index +1 CARD8 valuator 2 value +</literallayout> + +</sect1> +<sect1 id='key_behaviors'> +<title>Key Behaviors</title> + +<literallayout class='monospaced'>1 #x00 type +1 unused +</literallayout> + +<literallayout class='monospaced'>1 #x01 type +1 unused +</literallayout> + +<literallayout class='monospaced'>1 #x02 type +1 0..31 group +</literallayout> + +<literallayout class='monospaced'>1 #x03 type +1 KEYCODE key +</literallayout> + +<literallayout class='monospaced'>1 #x04 type +1 CARD8 key +</literallayout> + +<literallayout class='monospaced'>1 #x81 type +1 unused +</literallayout> + +<literallayout class='monospaced'>1 #x82 type +1 0..31 group +</literallayout> + +<literallayout class='monospaced'>1 #x83 type +1 KEYCODE key +</literallayout> + +<literallayout class='monospaced'>1 #x84 type +1 KEYCODE key +</literallayout> + +</sect1> +<sect1 id='requests2'> +<title>Requests</title> + +<literallayout class='monospaced'>1 ?? opcode +1 0 xkb-opcode +2 2 request-length +2 CARD16 wantedMajor +2 CARD16 wantedMinor +</literallayout> + +<literallayout class='monospaced'>1 1 Reply +1 BOOL supported +2 CARD16 sequence number +4 0 reply length +2 1 serverMajor +2 0 serverMinor +20 unused +</literallayout> + + +<literallayout class='monospaced'>1 ?? opcode +1 1 xkb-opcode +2 4+(V+p)/4 request-length +2 KB_DEVICESPEC deviceSpec +2 SETofKB_EVENTTYPE affectWhich +2 SETofKB_EVENTTYPE clear +2 SETofKB_EVENTTYPE selectAll +2 SETofKB_MAPDETAILS affectMap +2 SETofKB_MAPDETAILS map +V LISTofITEMs details + SETofKB_EVENTTYPE +(affectWhich&(~clear)&(~selectAll)) + XkbNewKeyboardNotify affectNewKeyboard, newKeyboardDetails + XkbStateNotify affectState, stateDetails + XkbControlsNotify affectCtrls, ctrlDetails + XkbIndicatorStateNotify affectIndicatorState, indicatorStateDetails + XkbIndicatorMapNotify affectIndicatorMap, indicatorMapDetails + XkbNamesNotify affectNames, namesDetails + XkbCompatMapNotify affectCompat, compatDetails + XkbBellNotify affectBell, bellDetails + XkbActionMessage affectMsgDetails, msgDetails + XkbExtensionDeviceNotify affectExtDev, extdevDetails +</literallayout> + +<literallayout class='monospaced'>ITEMs +p unused, p=pad(V) +</literallayout> + +<literallayout class='monospaced'>ITEMs +2 SETofKB_NKNDETAIL affectNewKeyboard +2 SETofKB_NKNDETAIL newKeyboardDetails +2 SETofKB_STATEPART affectState +2 SETofKB_STATEPART stateDetails +4 SETofKB_CONTROL affectCtrls +4 SETofKB_CONTROL ctrlDetails +4 SETofKB_INDICATOR affectIndicatorState +4 SETofKB_INDICATOR indicatorStateDetails +4 SETofKB_INDICATOR affectIndicatorMaps +4 SETofKB_INDICATOR indicatorMapDetails +2 SETofKB_NAME_DETAIL affectNames +2 SETofKB_NAME_DETAIL namesDetails +1 SETofKB_CMDETAIL affectCompat +1 SETofKB_CMDETAIL compatDetails +1 SETofKB_BELLDETAIL affectBell +1 SETofKB_BELLDETAIL bellDetails +1 SETofKB_MSGDETAIL affectMsgDetails +1 SETofKB_MSGDETAIL msgDetails +2 SETofKB_AXNDETAIL affectAccessX +2 SETofKB_AXNDETAIL accessXDetails +2 SETofKB_XIDETAIL affectExtDev +2 SETofKB_XIDETAIL extdevDetails +</literallayout> + + +<literallayout class='monospaced'>1 ?? opcode +1 3 xkb-opcode +2 7 request-length +2 KB_DEVICESPEC deviceSpec +2 KB_BELLCLASSSPEC bellClass +2 KB_IDSPEC bellID +1 INT8 percent +1 BOOL forceSound +1 BOOL eventOnly +1 unused +2 INT16 pitch +2 INT16 duration +2 unused +4 ATOM name +4 WINDOW window +</literallayout> + +<literallayout class='monospaced'>1 ?? opcode +1 4 xkb-opcode +2 2 request-length +2 KB_DEVICESPEC deviceSpec +2 unused +</literallayout> + +<literallayout class='monospaced'>1 1 Reply +1 CARD8 deviceID +2 CARD16 sequence number +4 0 length +1 SETofKEYMASK mods +1 SETofKEYMASK baseMods +1 SETofKEYMASK latchedMods +1 SETofKEYMASK lockedMods +1 KP_GROUP group +1 KP_GROUP lockedGroup +2 INT16 baseGroup +2 INT16 latchedGroup +1 SETofKEYMASK compatState +1 SETofKEYMASK grabMods +1 SETofKEYMASK compatGrabMods +1 SETofKEYMASK lookupMods +1 SETofKEYMASK compatLookupMods +1 unused +2 SETofBUTMASK ptrBtnState +6 unused +</literallayout> + + +<literallayout class='monospaced'>1 ?? opcode +1 5 xkb-opcode +2 4 request-length +2 KB_DEVICESPEC deviceSpec +1 SETofKEYMASK affectModLocks +1 SETofKEYMASK modLocks +1 BOOL lockGroup +1 KB_GROUP groupLock +1 SETofKEYMASK affectModLatches +1 SETofKEYMASK modLatches +1 unused +1 BOOL latchGroup +2 INT16 groupLatch +</literallayout> + +<literallayout class='monospaced'>1 ?? opcode +1 6 xkb-opcode +2 2 request-length +2 KB_DEVICESPEC deviceSpec +2 unused +</literallayout> + +<literallayout class='monospaced'>1 1 Reply +1 CARD8 deviceID +2 CARD16 sequence number +4 15 length +1 CARD8 mouseKeysDfltBtn +1 CARD8 numGroups +1 CARD8 groupsWrap +1 SETofKEYMASK internalMods.mask +1 SETofKEYMASK ignoreLockMods.mask +1 SETofKEYMASK internalMods.realMods +1 SETofKEYMASK ignoreLockMods.realMods +1 unused +2 SETofKB_VMOD internalMods.vmods +2 SETofKB_VMOD ignoreLockMods.vmods +2 CARD16 repeatDelay +2 CARD16 repeatInterval +2 CARD16 slowKeysDelay +2 CARD16 debounceDelay +2 CARD16 mouseKeysDelay +2 CARD16 mouseKeysInterval +2 CARD16 mouseKeysTimeToMax +2 CARD16 mouseKeysMaxSpeed +2 INT16 mouseKeysCurve +2 SETofKB_AXOPTION accessXOptions +2 CARD16 accessXTimeout +2 SETofKB_AXOPTION accessXTimeoutOptionsMask +2 SETofKB_AXOPTION accessXTimeoutOptionValues +2 unused +4 SETofKB_BOOLCTRL accessXTimeoutMask +4 SETofKB_BOOLCTRL accessXTimeoutValues +4 SETofKB_BOOLCTRL enabledControls +32 LISTofCARD8 perKeyRepeat +</literallayout> + + +<literallayout class='monospaced'>1 ?? opcode +1 7 xkb-opcode +2 25 request-length +2 KB_DEVICESPEC deviceSpec +1 SETofKEYMASK affectInternalRealMods +1 SETofKEYMASK internalRealMods +1 SETofKEYMASK affectIgnoreLockRealMods +1 SETofKEYMASK ignoreLockRealMods +2 SETofKB_VMOD affectInternalVirtualMods +2 SETofKB_VMOD internalVirtualMods +2 SETofKB_VMOD affectIgnoreLockVirtualMods +2 SETofKB_VMOD ignoreLockVirtualMods +1 CARD8 mouseKeysDfltBtn +1 CARD8 groupsWrap +2 SETofKB_AXOPTION accessXOptions +2 unused +4 SETofKB_BOOLCTRL affectEnabledControls +4 SETofKB_BOOLCTRL enabledControls +4 SETofKB_CONTROL changeControls +2 CARD16 repeatDelay +2 CARD16 repeatInterval +2 CARD16 slowKeysDelay +2 CARD16 debounceDelay +2 CARD16 mouseKeysDelay +2 CARD16 mouseKeysInterval +2 CARD16 mouseKeysTimeToMax +2 CARD16 mouseKeysMaxSpeed +2 INT16 mouseKeysCurve +2 CARD16 accessXTimeout +4 SETofKB_BOOLCTRL accessXTimeoutMask +4 SETofKB_BOOLCTRL accessXTimeoutValues +2 SETofKB_AXOPTION accessXTimeoutOptionsMask +2 SETofKB_AXOPTION accessXTimeoutOptionsValues +32 LISTofCARD8 perKeyRepeat +</literallayout> + +<literallayout class='monospaced'>1 CARD8 opcode +1 8 xkb-opcode +2 7 request-length +2 KB_DEVICESPEC deviceSpec +2 SETofKB_MAPPART full +2 SETofKB_MAPPART partial +1 CARD8 firstType +1 CARD8 nTypes +1 KEYCODE firstKeySym +1 CARD8 nKeySyms +1 KEYCODE firstKeyAction +1 CARD8 nKeyActions +1 KEYCODE firstKeyBehavior +1 CARD8 nKeyBehaviors +2 SETofKB_VMOD virtualMods +1 KEYCODE firstKeyExplicit +1 CARD8 nKeyExplicit +1 KEYCODE firstModMapKey +1 CARD8 nModMapKeys +1 KEYCODE firstVModMapKey +1 CARD8 nVModMapKeys +2 unused +</literallayout> + +<literallayout class='monospaced'>1 1 Reply +1 CARD8 deviceID +2 CARD16 sequence number +4 2+(I/4) length +2 unused +1 KEYCODE minKeyCode +1 KEYCODE maxKeyCode +2 SETofKB_MAPPART present +1 CARD8 firstType +1 t nTypes +1 CARD8 totalTypes +1 KEYCODE firstKeySym +2 S totalSyms +1 s nKeySyms +1 KEYCODE firstKeyAction +2 A totalActions +1 a nKeyActions +1 KEYCODE firstKeyBehavior +1 b nKeyBehaviors +1 B totalKeyBehaviors +1 KEYCODE firstKeyExplicit +1 e nKeyExplicit +1 E totalKeyExplicit +1 KEYCODE firstModMapKey +1 m nModMapKeys +1 M totalModMapKeys +1 KEYCODE firstVModMapKey +1 0 nVModMapKeys +1 V totalVModMapKeys +1 unused +2 SETofKB_VMOD virtualMods (has v bits set to 1) +I LISTofITEMs map + SETofKB_MAPPART (present) + XkbKeyTypes typesRtrn + XkbKeySyms symsRtrn + XkbKeyActions actsRtrn.count, actsRtrn.acts + XkbKeyBehaviors behaviorsRtrn + XkbVirtualMods vmodsRtrn + XkbExplicitComponents explicitRtrn + XkbModifierMap modmapRtrn + XkbVirtualModMap vmodMapRtrn +</literallayout> + +<literallayout class='monospaced'>ITEMs +T1+..Tt LISTofKB_KEYTYPE typesRtrn +8s+4S LISTofKB_KEYSYMMAP symsRtrn +a LISTofCARD8 actsRtrn.count +p unused,p=pad(a) +8A LISTofKB_ACTION actsRtrn.acts +4B LISTofKB_SETBEHAVIOR behaviorsRtrn +v LISTofSETofKEYMASK vmodsRtrn +p unused, p=pad(v) +2E LISTofKB_SETEXPLICIT explicitRtrn +p unused,p=pad(2E) +2M LISTofKB_KEYMODMAP modmapRtrn +p unused, p=pad(2M) +4V LISTofKB_KEYVMODMAP vmodMapRtrn +</literallayout> + +<literallayout class='monospaced'>KB_KEYTYPE 8+8m+[4m] +1 SETofKEYMASK mods.mask +1 SETofKEYMASK mods.mods +2 SETofKB_VMOD mods.vmods +1 CARD8 numLevels +1 m nMapEntries +1 BOOL hasPreserve +1 unused +8m LISTofKB_KTMAPENTRY map +[4m] LISTofKB_MODDEF preserve +</literallayout> + +<literallayout class='monospaced'>KB_KTMAPENTRY +1 BOOL active +1 SETofKEYMASK mods.mask +1 CARD8 level +1 SETofKEYMASK mods.mods +2 SETofKB_VMOD mods.vmods +2 unused +</literallayout> + +<literallayout class='monospaced'>KB_KEYSYMMAP 8+4n +4 LISTofCARD8 ktIndex +1 CARD8 groupInfo +1 CARD8 width +2 n nSyms +4n LISTofKEYSYM syms +</literallayout> + +<literallayout class='monospaced'>KB_SETBEHAVIOR +1 KEYCODE keycode +2 KB_BEHAVIOR behavior +1 unused +</literallayout> + +<literallayout class='monospaced'>KB_SETEXPLICIT +1 KEYCODE keycode +1 SETofKB_EXPLICIT explicit +</literallayout> + +<literallayout class='monospaced'>KB_KEYMODMAP +1 KEYCODE keycode +1 SETofKB_KEYMASK mods +</literallayout> + +<literallayout class='monospaced'>KB_KEYVMODMAP +1 KEYCODE keycode +1 unused +2 SETofKB_VMOD vmods +</literallayout> + + +<literallayout class='monospaced'>1 CARD8 opcode +1 9 xkb-opcode +2 9+(I/4) request-length +2 KB_DEVICESPEC deviceSpec +2 SETofKB_MAPPART present +2 SETofKB_SETMAPFLAGS flags + #0001 SetMapResizeTypes + #0002 SetMapRecomputeActions +1 KEYCODE minKeyCode +1 KEYCODE maxKeyCode +1 CARD8 firstType +1 t nTypes +1 KEYCODE firstKeySym +1 s nKeySyms +2 S totalSyms +1 KEYCODE firstKeyAction +1 a nKeyActions +2 A totalActions +1 KEYCODE firstKeyBehavior +1 b nKeyBehaviors +1 B totalKeyBehaviors +1 KEYCODE firstKeyExplicit +1 e nKeyExplicit +1 E totalKeyExplicit +1 KEYCODE firstModMapKey +1 m nModMapKeys +1 M totalModMapKeys +1 KEYCODE firstVModMapKey +1 v nVModMapKeys +1 V totalVModMapKeys +2 SETofKB_VMOD virtualMods (has n bits set to 1) +I LISTofITEMs values + SETofKB_MAPPART (present) + XkbKeyTypes types + XkbKeySymbols syms + XkbKeyActions actions.count,actions.actions + XkbKeyBehaviors behaviors + XkbVirtualMods vmods + XkbExplicitComponents explicit + XkbModifierMap modmap + XkbVirtualModMap vmodmap +</literallayout> + +<literallayout class='monospaced'>ITEMs +T0+..Tt LISTofKB_SETKEYTYPE types +8s+4S LISTofKB_KEYSYMMAP syms +a LISTofCARD8 actions.count +p unused,p=pad(a) +8A LISTofKB_ACTION actions.actions +4B LISTofKB_SETBEHAVIOR behaviors +v LISTofSETofKEYMASK vmods +p unused, p=pad(v) +2E LISTofKB_SETEXPLICIT explicit +p unused,p=pad(2E) +2M LISTofKB_KEYMODMAP modmap +P unused, p=pad(2M) +4V LISTofKB_KEYVMODMAP vmodmap +</literallayout> + +<literallayout class='monospaced'>KB_SETKEYTYPE 8+4m+[4m] +1 SETofKEYMASK mask +1 SETofKEYMASK realMods +2 SETofKB_VMOD virtualMods +1 CARD8 numLevels +1 m nMapEntries +1 BOOL preserve +1 unused +4m LISTofKB_KTSETMAPENTRY entries +[4m] LISTofKB_MODDEF preserveEntries (if preserve==TRUE) +</literallayout> + +<literallayout class='monospaced'>KB_KTSETMAPENTRY +1 CARD8 level +1 SETofKEYMASK realMods +2 SETofKB_VMOD virtualMods +</literallayout> + + +<literallayout class='monospaced'>1 ?? opcode +1 10 xkb-opcode +2 3 request-length +2 KB_DEVICESPEC deviceSpec +1 SETofKB_GROUP groups +1 BOOL getAllSI +2 CARD16 firstSI +2 CARD16 nSI +</literallayout> + +<literallayout class='monospaced'>1 1 Reply +1 CARD8 deviceID +2 CARD16 sequence number +4 (16n+4g)/4 length +1 SETofKB_GROUP groupsRtrn (has g bits set to 1) +1 unused +2 CARD16 firstSIRtrn +2 n nSIRtrn +2 CARD16 nTotalSI +16 unused +16n LISTofKB_SYMINTERPRET siRtrn +4g LISTofKB_MODDEF groupRtrn +</literallayout> + + +<literallayout class='monospaced'>1 ?? opcode +1 11 xkb-opcode +2 4+(16n+4g) request-length +2 KB_DEVICESPEC deviceSpec +1 unused +1 BOOL recomputeActions +1 BOOL truncateSI +1 SETofKB_GROUP groups (has g bits set to 1) +2 CARD16 firstSI +2 n nSI +2 unused +16n LISTofKB_SYMINTERPRET si +4g LISTofKB_MODDEF groupMaps +</literallayout> + +<literallayout class='monospaced'>1 ?? opcode +1 12 xkb-opcode +2 2 request-length +2 KB_DEVICESPEC deviceSpec +</literallayout> + +<literallayout class='monospaced'>ITEMs +2 unused +</literallayout> + +<literallayout class='monospaced'>1 1 Reply +1 CARD8 deviceID +2 CARD16 sequence number +4 0 length +4 SETofKB_INDICATOR state +20 unused +</literallayout> + + +<literallayout class='monospaced'>1 ?? opcode +1 13 xkb-opcode +2 3 request-length +2 KB_DEVICESPEC deviceSpec +2 unused +4 SETofKB_INDICATOR which +</literallayout> + +<literallayout class='monospaced'>1 1 Reply +1 CARD8 deviceID +2 CARD16 sequence number +4 12n/4 length +4 SETofKB_INDICATOR which (has n bits set to 1) +4 SETofKB_INDICATOR realIndicators +1 n nIndicators +15 unused +12n LISTofKB_INDICATORMAP maps +</literallayout> + + +<literallayout class='monospaced'>1 ?? opcode +1 14 xkb-opcode +2 3+3n request-length +2 KB_DEVICESPEC deviceSpec +2 unused +4 SETofKB_INDICATOR which (has n bits set to 1) +12n LISTofKB_INDICATORMAP maps +</literallayout> + +<literallayout class='monospaced'>1 CARD8 opcode +1 15 xkb-opcode +2 4 request-length +2 KB_DEVICESPEC deviceSpec +2 KB_LEDCLASSSPEC ledClass +2 KB_IDSPEC ledID +2 unused +4 ATOM indicator +</literallayout> + +<literallayout class='monospaced'>1 1 Reply +1 CARD8 deviceID +2 CARD16 sequence number +4 0 length +4 ATOM indicator +1 BOOL found +1 BOOL on +1 BOOL realIndicator +1 KB_INDICATOR ndx +1 SETofKB_IMFLAGS map.flags +1 SETofKB_IMGROUPSWHICH map.whichGroups +1 SETofKB_GROUPS map.groups +1 SETofKB_IMMODSWHICH map.whichMods +1 SETofKEYMASK map.mods +1 SETofKEYMASK map.realMods +2 SETofKB_VMOD map.vmods +4 SETofKB_BOOLCTRL map.ctrls +1 BOOL supported +3 unused +</literallayout> + + +<literallayout class='monospaced'>1 ?? opcode +1 16 xkb-opcode +2 8 request-length +2 KB_DEVICESPEC deviceSpec +2 KB_LEDCLASSSPEC ledClass +2 KB_IDSPEC ledID +2 unused +4 ATOM indicator +1 BOOL setState +1 BOOL on +1 BOOL setMap +1 BOOL createMap +1 unused +1 SETofKB_IMFLAGS map.flags +1 SETofKB_IMGROUPSWHICH map.whichGroups +1 SETofKB_GROUP map.groups +1 SETofKB_IMMODSWHICH map.whichMods +1 SETofKEYMASK map.realMods +2 SETofKB_VMOD map.vmods +4 SETofKB_BOOLCTRL map.ctrls +</literallayout> + +<literallayout class='monospaced'>1 CARD8 opcode +1 17 xkb-opcode +2 3 request-length +2 KB_DEVICESPEC deviceSpec +2 unused +4 SETofKB_NAMEDETAIL which +</literallayout> + +<literallayout class='monospaced'>1 1 Reply +1 CARD8 deviceID +2 CARD16 sequence number +4 V/4 length +4 SETofKB_NAMEDETAIL which +1 KEYCODE minKeyCode +1 KEYCODE maxKeyCode +1 t nTypes +1 SETofKB_GROUP groupNames (has g bits set to 1) +2 SETofKB_VMOD virtualMods (has v bits set to 1) +1 KEYCODE firstKey +1 k nKeys +4 SETofKB_INDICATOR indicators (has i bits set to 1) +1 r nRadioGroups +1 a nKeyAliases +2 l nKTLevels +4 unused +V LISTofITEMs valueList + SETofKB_NAMEDETAIL (which) + XkbKeycodesName keycodesName + XkbGeometryName geometryName + XkbSymbolsName symbolsName + XkbPhySymbolsName physSymbolsName + XkbTypesName typesName + XkbCompatName compatName + XkbKeyTypeNames typeNames + XkbKTLevelNames nLevelsPerType, ktLevelNames + XkbIndicatorNames indicatorNames + XkbVirtualModNames virtualModNames + XkbGroupNames groupNames + XkbKeyNames keyNames + XkbKeyAliases keyAliases + XkbRGNames radioGroupNames +</literallayout> + +<literallayout class='monospaced'>ITEMs +4 ATOM keycodesName +4 ATOM geometryName +4 ATOM symbolsName +4 ATOM physSymbolsName +4 ATOM typesName +4 ATOM compatName +4t LISTofATOM typeNames +l LISTofCARD8 nLevelsPerType, sum of all elements=L +p unused, p=pad(l) +4L LISTofATOM ktLevelNames +4i LISTofATOM indicatorNames +4v LISTofATOM virtualModNames +4g LISTofATOM groupNames +4k LISTofKB_KEYNAME keyNames +8a LISTofKB_KEYALIAS keyAliases +4r LISTofATOM radioGroupNames +</literallayout> + + +<literallayout class='monospaced'>1 CARD8 opcode +1 18 xkb-opcode +2 7+(V/4) request-length +2 KB_DEVICESPEC deviceSpec +2 SETofKB_VMOD virtualMods +4 SETofKB_NAMEDETAIL which +1 CARD8 firstType +1 t nTypes +1 CARD8 firstKTLevel +1 l nKTLevels +4 SETofKB_INDICATOR indicators (has i bits set to 1) +1 SETofKB_GROUP groupNames (has g bits set to 1) +1 r nRadioGroups +1 KEYCODE firstKey +1 k nKeys +1 a nKeyAliases +1 unused +2 L totalKTLevelNames +V LISTofITEMs values + SETofKB_NAMEDETAIL (which) + XkbKeycodesName keycodesName + XkbGeometryName geometryName + XkbSymbolsName symbolsName + XkbPhySymbolsName physSymbolsName + XkbTypesName typesName + XkbCompatName compatName + XkbKeyTypeNames typeNames + XkbKTLevelNames nLevelsPerType, ktLevelNames + XkbIndicatorNames indicatorNames + XkbVirtualModNames virtualModNames + XkbGroupNames groupNames + XkbKeyNames keyNames + XkbKeyAliases keyAliases + XkbRGNames radioGroupNames +</literallayout> + +<literallayout class='monospaced'>ITEMs +4 ATOM keycodesName +4 ATOM geometryName +4 ATOM symbolsName +4 ATOM physSymbolsName +4 ATOM typesName +4 ATOM compatName +4t LISTofATOM typeNames +l LISTofCARD8 nLevelsPerType +p unused, p=pad(l) +4L LISTofATOM ktLevelNames +4i LISTofATOM indicatorNames +4v LISTofATOM virtualModNames +4g LISTofATOM groupNames +4k LISTofKB_KEYNAME keyNames +8a LISTofKB_KEYALIAS keyAliases +4r LISTofATOM radioGroupNames +</literallayout> + + +<literallayout class='monospaced'>1 CARD8 opcode +1 19 xkb-opcode +2 3 request-length +2 KB_DEVICESPEC deviceSpec +2 unused +4 ATOM name +</literallayout> + +<literallayout class='monospaced'>1 1 Reply +1 CARD8 deviceID +2 CARD16 sequence number +4 (f+8p+C*+H*+S*+D*+A*)/4 length +4 ATOM name +1 BOOL found +1 unused +2 CARD16 widthMM +2 CARD16 heightMM +2 p nProperties +2 c nColors +2 h nShapes +2 s nSections +2 d nDoodads +2 a nKeyAliases +1 CARD8 baseColorNdx +1 CARD8 labelColorNdx +f KB_COUNTED_STRING16 labelFont +8p LISTofKB_PROPERTY properties +C0+..Cc LISTofKB_COUNTED_STRING16 colors +H0+..Hh LISTofKB_SHAPE shapes +S0+..Ss LISTofKB_SECTION sections +D0+..Dd LISTofKB_DOODAD doodads +A0+..Aa LISTofKB_KEYALIAS keyAliases +</literallayout> + +<literallayout class='monospaced'>KB_PROPERTY 4+n+v +2 n nameLength +n STRING8 name +2 v valueLength +v STRING8 value +</literallayout> + +<literallayout class='monospaced'>KB_SHAPE 8+O* +4 ATOM name +1 o nOutlines +1 CARD8 primaryNdx +1 CARD8 approxNdx +1 unused +O0+..Oo LISTofKB_OUTLINE outlines +</literallayout> + +<literallayout class='monospaced'>KB_OUTLINE 4+4p +1 p nPoints +1 CARD8 cornerRadius +2 unused +4p LISTofKB_POINT points +</literallayout> + +<literallayout class='monospaced'>KB_POINT +2 INT16 x +2 INT16 y +</literallayout> + +<literallayout class='monospaced'>KB_SECTION 20+R*+D*+O* +4 ATOM name +2 INT16 top +2 INT16 left +2 CARD16 width +2 CARD16 height +2 INT16 angle +1 CARD8 priority +1 r nRows +1 d nDoodads +1 o nOverlays +2 unused +R0+..Rr LISTofKB_ROW rows +D0+..Dd LISTofKB_DOODAD doodads +O0+..Oo LISTofKB_OVERLAY overlays +</literallayout> + +<literallayout class='monospaced'>KB_ROW 8+8k +2 INT16 top +2 INT16 left +1 k nKeys +1 BOOL vertical +2 unused +8k LISTofKB_KEY keys +</literallayout> + +<literallayout class='monospaced'>KB_KEY +4 STRING8 name +2 INT16 gap +1 CARD8 shapeNdx +1 CARD8 colorNdx +</literallayout> + +<literallayout class='monospaced'>KB_OVERLAY 8+R* +4 ATOM name +1 r nRows +3 unused +R0+..Rr LISTofKB_OVERLAYROW rows +</literallayout> + +<literallayout class='monospaced'>KB_OVERLAYROW 4+8k +1 CARD8 rowUnder +1 k nKeys +2 unused +8k LISTofKB_OVERLAYKEY keys +</literallayout> + +<literallayout class='monospaced'>KB_OVERLAYKEY +4 STRING8 over +4 STRING8 under +</literallayout> + +<literallayout class='monospaced'>KB_SHAPEDOODAD +4 ATOM name +1 CARD8 type +</literallayout> + +<literallayout class='monospaced'>KB_SHAPEDOODAD + #1 XkbOutlineDoodad + #2 XkbSolidDoodad +1 CARD8 priority +2 INT16 top +2 INT16 left +2 INT16 angle +1 CARD8 colorNdx +1 CARD8 shapeNdx +6 unused +</literallayout> + +<literallayout class='monospaced'>KB_TEXTDOODAD 20+t+f +4 ATOM name +1 CARD8 type + #3 XkbTextDoodad +1 CARD8 priority +2 INT16 top +2 INT16 left +2 INT16 angle +2 CARD16 width +2 CARD16 height +1 CARD8 colorNdx +3 unused +t KB_COUNTED_STRING16 text +f KB_COUNTED_STRING16 font +</literallayout> + +<literallayout class='monospaced'>KB_INDICATORDOODAD +4 ATOM name +1 CARD8 type + #4 XkbIndicatorDoodad +1 CARD8 priority +2 INT16 top +2 INT16 left +2 INT16 angle +1 CARD8 shapeNdx +1 CARD8 onColorNdx +1 CARD8 offColorNdx +5 unused +</literallayout> + +<literallayout class='monospaced'>KB_LOGODOODAD 20+n +4 ATOM name +1 CARD8 type + #5 XkbLogoDoodad +1 CARD8 priority +2 INT16 top +2 INT16 left +2 INT16 angle +1 CARD8 colorNdx +1 CARD8 shapeNdx +6 unused +n KB_COUNTED_STRING16 logoName +</literallayout> + +<literallayout class='monospaced'>KB_DOODAD: + KB_SHAPEDOODAD, or KB_TEXTDOODAD, or + KB_INDICATORDOODAD, or KB_LOGODOODAD +</literallayout> + + +<literallayout class='monospaced'>1 CARD8 opcode +1 20 xkb-opcode +2 7+(f+8p+C*+H*+S*+D*+A*)/4 request-length +2 KB_DEVICESPEC deviceSpec +1 h nShapes +1 s nSections +4 ATOM name +2 CARD16 widthMM +2 CARD16 heightMM +2 p nProperties +2 c nColors +2 d nDoodads +2 a nKeyAliases +1 CARD8 baseColorNdx +1 CARD8 labelColorNdx +2 unused +f KB_COUNTED_STRING16 labelFont +8p LISTofKB_PROPERTY properties +C0+..Cc LISTofKB_COUNTED_STRING16 colors +H0+..Hh LISTofKB_SHAPE shapes +S0+..Ss LISTofKB_SECTION sections +D0+..Dd LISTofKB_DOODAD doodads +A0+..Aa LISTofKB_KEYALIAS keyAliases +</literallayout> + +<literallayout class='monospaced'>1 CARD8 opcode +1 21 xkb-opcode +2 7 request-length +2 KB_DEVICESPEC deviceSpec +2 unused +4 SETofKB_PERCLIENTFLAG change +4 SETofKB_PERCLIENTFLAG value +4 SETofKB_BOOLCTRL ctrlsToChange +4 SETofKB_BOOLCTRL autoCtrls +4 SETofKB_BOOLCTRL autoCtrlValues +</literallayout> + +<literallayout class='monospaced'>1 1 Reply +1 CARD8 deviceID +2 CARD16 sequence number +4 0 length +4 SETofKB_PERCLIENTFLAG supported +4 SETofKB_PERCLIENTFLAG value +4 SETofKB_BOOLCTRL autoCtrls +4 SETofKB_BOOLCTRL autoCtrlValues +8 unused +</literallayout> + + +<literallayout class='monospaced'>1 CARD8 opcode +1 22 xkb-opcode +2 2+(6+m+k+t+c+s+g+p)/4 request-length +2 KB_DEVICESPEC deviceSpec +2 CARD16 maxNames +1 m keymapsSpecLen +m STRING keymapsSpec +1 k keycodesSpecLen +k STRING keycodesSpec +1 t typesSpecLen +t STRING typesSpec +1 c compatMapSpecLen +c STRING compatMapSpec +1 s symbolsSpecLen +s STRING symbolsSpec +1 g geometrySpecLen +g STRING geometrySpec +p unused,p=pad(6+m+k+t+c+s+g) +</literallayout> + +<literallayout class='monospaced'>1 1 Reply +1 CARD8 deviceID +2 CARD16 sequence number +4 (M*+K*+T*+C*+S*+G*+p)/4 length +2 m nKeymaps +2 k nKeycodes +2 t nTypes +2 c nCompatMaps +2 s nSymbols +2 g nGeometries +2 CARD16 extra +10 unused +M0+..Mm LISTofKB_LISTING keymaps +K0+..Kk LISTofKB_LISTING keycodes +T0+..Tt LISTofKB_LISTING types +C0+..Cc LISTofKB_LISTING compatMaps +S0+..Ss LISTofKB_LISTING symbols +G0+..Gg LISTofKB_LISTING geometries +p unused,p=pad(M*+K*+T*+C*+S*+G*) +</literallayout> + +<literallayout class='monospaced'>KB_LISTING 4+n+p +2 CARD16 flags +2 n length +n STRING8 string +p unused,p=pad(n) to a 2-byte boundary +</literallayout> + + +<literallayout class='monospaced'>1 CARD8 opcode +1 23 xkb-opcode +2 3+(6+m+k+t+c+s+g+p)/4 request-length +2 KB_DEVICESPEC deviceSpec +2 SETofKB_GBNDETAILMASK need +2 SETofKB_GBNDETAILMASK want +1 BOOL load +1 unused +1 m keymapsSpecLen +m STRING8 keymapsSpec +1 k keycodesSpecLen +k STRING8 keycodesSpec +1 t typesSpecLen +t STRING8 typesSpec +1 c compatMapSpecLen +c STRING8 compatMapSpec +1 s symbolsSpecLen +s STRING8 symbolsSpec +1 g geometrySpecLen +g STRING8 geometrySpec +p unused,p=pad(6+m+k+t+c+s+g) +</literallayout> + +<literallayout class='monospaced'>1 1 Reply +1 CARD8 deviceID +2 CARD16 sequence number +4 V/4 length +1 KEYCODE minKeyCode +1 KEYCODE maxKeyCode +1 BOOL loaded +1 BOOL newKeyboard +2 SETofKB_GBNDETAILMASK found +2 SETofKB_GBNDETAILMASK reported +16 unused +V LISTofITEMs replies + SETofKB_GBNDETAILMASK (reported) + XkbGBN_Types map + XkbGBN_CompatMap compat + XkbGBN_ClientSymbols map + XkbGBN_ServerSymbols map + XkbGBN_IndicatorMap indicators + XkbGBN_KeyNames names + XkbGBN_OtherNames names + XkbGBN_Geometry geometry +</literallayout> + +<literallayout class='monospaced'>ITEMs +M XkbGetMap reply map +C XkbGetCompatMap reply compat +I XkbGetIndicatorMap reply indicators +N XkbGetNames reply names +G XkbGetGeometry reply geometry +</literallayout> + + +<literallayout class='monospaced'>1 CARD8 opcode +1 24 xkb-opcode +2 4 request-length +2 KB_DEVICESPEC deviceSpec +2 SETofKB_DEVFEATURE wanted +1 BOOL allButtons +1 CARD8 firstButton +1 CARD8 nButtons +1 unused +2 KB_LEDCLASSSPEC ledClass +2 KB_IDSPEC ledID +</literallayout> + +<literallayout class='monospaced'>1 1 Reply +1 CARD8 deviceID +2 CARD16 sequence number +4 (2+n+p+8b+L*)/4 length +2 SETofKB_DEVFEATURE present +2 SETofKB_FEATURE supported +2 SETofKB_FEATURE unsupported +2 l nDeviceLedFBs +1 CARD8 firstBtnWanted +1 CARD8 nBtnsWanted +1 CARD8 firstBtnRtrn +1 b nBtnsRtrn +1 CARD8 totalBtns +1 BOOL hasOwnState +2 SETofKB_IDRESULT dfltKbdFB +2 SETofKB_IDRESULT dfltLedFB +2 unused +4 ATOM devType +2 n nameLen +n STRING8 name +p unused,p=pad(2+n) +8b LISTofKB_ACTION btnActions +L0+..Ll LISTofKB_DEVICELEDINFO leds +</literallayout> + +<literallayout class='monospaced'>KB_DEVICELEDINFO 20+4n+12m +2 KB_LEDCLASSSPEC ledClass +2 KB_IDSPEC ledID +4 SETofKB_INDICATOR namesPresent (has n bits set to 1) +4 SETofKB_INDICATOR mapsPresent (has m bits set to 1) +4 SETofKB_INDICATOR physIndicators +4 SETofKB_INDICATOR state +4n LISTofATOM names +12m LISTofKB_INDICATORMAP maps +</literallayout> + + +<literallayout class='monospaced'>1 ?? opcode +1 25 xkb-opcode +2 3+(8b+L*)/4 request-length +2 KB_DEVICESPEC deviceSpec +1 CARD8 firstBtn +1 b nBtns +2 SETofKB_DEVFEATURE change +2 l nDeviceLedFBs +8b LISTofKB_ACTION btnActions +L0+..Ll LISTofKB_DEVICELEDINFO leds + Encoding of KB_DEVICELEDINFO is as for XkbGetDeviceInfo +</literallayout> + +<literallayout class='monospaced'>1 ?? opcode +1 101 xkb-opcode +2 6+(n+p)/4 request-length +2 n msgLength +2 unused +4 CARD32 affectFlags +4 CARD32 flags +4 CARD32 affectCtrls +4 CARD32 ctrls +n STRING8 message +p unused, p=pad(n) +</literallayout> + +<literallayout class='monospaced'>1 1 Reply +1 unused +2 CARD16 sequence number +4 0 length +4 CARD32 currentFlags +4 CARD32 currentCtrls +4 CARD32 supportedFlags +4 CARD32 supportedCtrls +8 unused +</literallayout> + + +</sect1> +<sect1 id='events2'> +<title>Events</title> + +<literallayout class='monospaced'>1 ?? code +1 0 xkb code +2 CARD16 sequence number +4 TIMESTAMP time +1 CARD8 deviceID +1 CARD8 oldDeviceID +1 KEYCODE minKeyCode +1 KEYCODE maxKeyCode +1 KEYCODE oldMinKeyCode +1 KEYCODE oldMaxKeyCode +1 CARD8 requestMajor +1 CARD8 requestMinor +2 SETofKB_NKNDETAIL changed +14 unused +</literallayout> + +<literallayout class='monospaced'>1 ?? code +1 1 xkb code +2 CARD16 sequence number +4 TIMESTAMP time +1 CARD8 deviceID +1 SETofBUTMASK ptrBtnActions +2 SETofKB_MAPPART changed +1 KEYCODE minKeyCode +1 KEYCODE maxKeyCode +1 CARD8 firstType +1 CARD8 nTypes +1 KEYCODE firstKeySym +1 CARD8 nKeySyms +1 KEYCODE firstKeyAct +1 CARD8 nKeyActs +1 KEYCODE firstKeyBehavior +1 CARD8 nKeyBehavior +1 KEYCODE firstKeyExplicit +1 CARD8 nKeyExplicit +1 KEYCODE firstModMapKey +1 CARD8 nModMapKeys +1 KEYCODE firstVModMapKey +1 CARD8 nVModMapKeys +2 SETofKB_VMOD virtualMods +2 unused +</literallayout> + +<literallayout class='monospaced'>1 ?? code +1 2 xkb code +2 CARD16 sequence number +4 TIMESTAMP time +1 CARD8 deviceID +1 SETofKEYMASK mods +1 SETofKEYMASK baseMods +1 SETofKEYMASK latchedMods +1 SETofKEYMASK lockedMods +1 KB_GROUP group +2 INT16 baseGroup +2 INT16 latchedGroup +1 KB_GROUP lockedGroup +1 SETofKEYMASK compatState +1 SETofKEYMASK grabMods +1 SETofKEYMASK compatGrabMods +1 SETofKEYMASK lookupMods +1 SETofKEYMASK compatLookupMods +2 SETofBUTMASK ptrBtnState +2 SETofKB_STATEPART changed +1 KEYCODE keycode +1 CARD8 eventType +1 CARD8 requestMajor +1 CARD8 requestMinor +</literallayout> + +<literallayout class='monospaced'>1 ?? code +1 3 xkb code +2 CARD16 sequence number +4 TIMESTAMP time +1 CARD8 deviceID +1 CARD8 numGroups +2 unused +4 SETofKB_CONTROL changedControls +4 SETofKB_BOOLCTRL enabledControls +4 SETofKB_BOOLCTRL enabledControlChanges +1 KEYCODE keycode +1 CARD8 eventType +1 CARD8 requestMajor +1 CARD8 requestMinor +4 unused +</literallayout> + +<literallayout class='monospaced'>1 ?? code +1 4 xkb code +2 CARD16 sequence number +4 TIMESTAMP time +1 CARD8 deviceID +3 unused +4 SETofKB_INDICATOR state +4 SETofKB_INDICATOR stateChanged +12 unused +</literallayout> + +<literallayout class='monospaced'>1 ?? code +1 5 xkb code +2 CARD16 sequence number +4 TIMESTAMP time +1 CARD8 deviceID +3 unused +4 SETofKB_INDICATOR state +4 SETofKB_INDICATOR mapChanged +12 unused +</literallayout> + +<literallayout class='monospaced'>1 ?? code +1 6 xkb code +2 CARD16 sequence number +4 TIMESTAMP time +1 CARD8 deviceID +1 unused +2 SETofKB_NAMEDETAIL changed +1 CARD8 firstType +1 CARD8 nTypes +1 CARD8 firstLevelName +1 CARD8 nLevelNames +1 unused +1 CARD8 nRadioGroups +1 CARD8 nKeyAliases +1 SETofKB_GROUP changedGroupNames +2 SETofKB_VMOD changedVirtualMods +1 KEYCODE firstKey +1 CARD8 nKeys +4 SETofKB_INDICATOR changedIndicators +4 unused +</literallayout> + +<literallayout class='monospaced'>1 ?? code +1 7 xkb code +2 CARD16 sequence number +4 TIMESTAMP time +1 CARD8 deviceID +1 SETofKB_GROUP changedGroups +2 CARD16 firstSI +2 CARD16 nSI +2 CARD16 nTotalSI +16 unused +</literallayout> + +<literallayout class='monospaced'>1 ?? code +1 8 xkb code +2 CARD16 sequence number +4 TIMESTAMP time +1 CARD8 deviceID +1 KB_BELLCLASSRESULT bellClass +1 CARD8 bellID +1 CARD8 percent +2 CARD16 pitch +2 CARD16 duration +4 ATOM name +4 WINDOW window +1 BOOL eventOnly +7 unused +</literallayout> + +<literallayout class='monospaced'>1 ?? code +1 9 xkb code +2 CARD16 sequence number +4 TIMESTAMP time +1 CARD8 deviceID +1 KEYCODE keycode +1 BOOL press +1 BOOL keyEventFollows +1 SETofKEYMASK mods +1 KB_GROUP group +8 STRING8 message +10 unused +</literallayout> + +<literallayout class='monospaced'>1 ?? code +1 10 xkb code +2 CARD16 sequence number +4 TIMESTAMP time +1 CARD8 deviceID +1 KEYCODE keycode +2 SETofKB_AXNDETAIL detail +2 CARD16 slowKeysDelay +2 CARD16 debounceDelay +</literallayout> + +<literallayout class='monospaced'>1 ?? code +16 unused +</literallayout> + +<literallayout class='monospaced'>1 ?? code +1 11 xkb code +2 CARD16 sequence number +4 TIMESTAMP time +1 CARD8 deviceID +1 unused +2 SETofKB_XIDETAIL reason +2 KB_LEDCLASSRESULT ledClass +2 CARD8 ledID +4 SETofKB_INDICATOR ledsDefined +4 SETofKB_INDICATOR ledState +1 CARD8 firstButton +1 CARD8 nButtons +2 SETofKB_XIFEATURE supported +2 SETofKB_XIFEATURE unsupported +2 unused +</literallayout> + +</sect1> +</appendix> diff --git a/specs/ch01.xml b/specs/ch01.xml new file mode 100644 index 0000000..7bf0ef4 --- /dev/null +++ b/specs/ch01.xml @@ -0,0 +1,101 @@ +<chapter id='overview'> +<title>Overview</title> +<para> +This extension provides a number of new capabilities and controls for +text keyboards. +</para> + +<para> +The core X protocol specifies the ways that the <emphasis> +Shift</emphasis> +, <emphasis> +Control</emphasis> + and <emphasis> +Lock</emphasis> + modifiers and the modifiers bound to the <emphasis> +Mode_switch</emphasis> + or <emphasis> +Num_Lock</emphasis> + 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: +</para> + +<itemizedlist> +<listitem> + <para>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. + </para> +</listitem> +<listitem> + <para>Use of a modifier to specify a second keyboard group has side-effects +that wreak havoc with client grabs and X toolkit translations and limit us to +two keyboard groups. + </para> +</listitem> +<listitem> + <para>Poorly specified locking key behavior requires X servers to look for a +few "magic" keysyms to determine which keys should lock when pressed. This +leads to incompatibilities between X servers with no way for clients to detect +implementation differences. + </para> +</listitem> +<listitem> + <para>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. + </para> +</listitem> +<listitem> + <para>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 using shift should +"cancel" the lock modifier. + </para> +</listitem> +<listitem> + <para>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 mishmash of prior +knowledge and heuristics. + </para> +</listitem> +</itemizedlist> + +<para> +This 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 numeric +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, this extension provides descriptions and symbolic names for +many aspects of keyboard appearance and behavior. It also includes a number of +keyboard controls designed to make keyboards more accessible to people with +movement impairments. +</para> + + +<para> +The X Keyboard Extension essentially replaces the core protocol definition of a +keyboard. The following sections describe the new capabilities of the extension +and the effect of the extension on core protocol requests, events and errors. +</para> + +<sect1 id='conventions_and_assumptions'> +<title>Conventions and Assumptions</title> +<para> +This document uses the syntactic +conventions, common types, and errors defined in sections two through four of +the specification of the X Window System Protocol. This document assumes +familiarity with the fundamental concepts of X, especially those related to the +way that X handles keyboards. Readers who are not familiar with the meaning or +use of keycodes, keysyms or modifiers should consult (at least) the first five +chapters of the protocol specification of the X Window System before +continuing. +</para> +</sect1> +</chapter> diff --git a/specs/ch02.xml b/specs/ch02.xml new file mode 100644 index 0000000..27a566a --- /dev/null +++ b/specs/ch02.xml @@ -0,0 +1,443 @@ +<chapter id='keyboard_state'> +<title>Keyboard State</title> +<para> +The core protocol description of +keyboard state consists of eight <emphasis> +modifiers</emphasis> +(<emphasis> +Shift</emphasis> +, <emphasis> +Lock</emphasis> +, <emphasis> +Control</emphasis> +, and <emphasis> +Mod1</emphasis> +-<emphasis> +Mod5</emphasis> +). A modifier reports the state of one or modifier keys, which are similar to +qualifier keys as defined by the ISO9995 standard: +</para> + +<variablelist> + <varlistentry> + <term>Qualifier key</term> + <listitem> + <para> +A key whose operation +has no immediate effect, but which, for as long as it is held down, modifies +the effect of other keys. A qualifier key may be, for example, a shift key or a +control key. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +Whenever a modifier key is physically or logically depressed, the modifier it +controls is set in the keyboard state. The protocol implies that certain +modifier keys lock (i.e. affect modifier state after they have been physically +released) but does not explicitly discuss locking keys or their behavior. The +current modifier state is reported to clients in a number of core protocol +events and can be determined using the <emphasis> +QueryPointer</emphasis> + request. +</para> + +<para> +The XKB extension retains the eight "real" modifiers defined by the core +protocol but extends the core protocol notion of <emphasis> +keyboard state</emphasis> + to include up to four <emphasis> +keysym groups</emphasis> +, as defined by the ISO9995 standard: +</para> + + +<variablelist> + <varlistentry> + <term>Group:</term> + <listitem> + <para> +A logical state of a keyboard providing +access to a collection of characters. A group usually contains a set of +characters which logically belong together and which may be arranged on several +shift levels within that group. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +For example, keyboard group can be used to select between multiple alphabets on +a single keyboard, or to access less-commonly used symbols within a character +set. +</para> + +<sect1 id='locking_and_latching_modifiers_and_groups'> +<title>Locking and Latching Modifiers and Groups</title> +<para> +With the core protocol, there is no way to +tell whether a modifier is set due to a lock or because the user is actually +holding down a key; this can make for a clumsy user-interface as locked +modifiers or group state interfere with accelerators and translations. +</para> +<para> +XKB adds explicit support for locking +and latching modifiers and groups. Locked modifiers or groups apply to all +future key events until they are explicitly changed. Latched modifiers or +groups apply only to the next key event that does not change keyboard state. +</para> + +</sect1> +<sect1 id="fundamental_components_of_xkb_keyboard_state"> +<title>Fundamental Components of XKB Keyboard State</title> +<para> +The fundamental components of XKB keyboard state include: +</para> + +<itemizedlist> +<listitem> + <para>The locked modifiers and group</para> +</listitem> +<listitem> + <para>The latched modifiers and group</para> +</listitem> +<listitem> + <para>The base modifiers and group (for which keys are physically or +logically down) + </para> +</listitem> +<listitem> + <para>The effective modifiers and group (the cumulative effect of the base, +locked and latched modifier and group states). + </para> +</listitem> +<listitem> + <para>State of the core pointer buttons.</para> +</listitem> +</itemizedlist> + +<para> +The latched and locked state of modifiers and groups can be changed in response +to keyboard activity or under application control using the <emphasis> +XkbLatchLockState</emphasis> + request. The base modifier, base group +and pointer button states always reflect the logical state of the keyboard and +pointer and change <emphasis> +only</emphasis> + in response to keyboard or pointer activity. +</para> + +<sect2 id='computing_effective_modifier_and_group'> +<title>Computing Effective Modifier and Group</title> +<para> +The effective modifiers and group +report the cumulative effects of the base, latched and locked modifiers and +group respectively, and cannot be directly changed. Note that the effective +modifiers and effective group are computed differently. +</para> + +<para> +The effective modifiers are simply the bitwise union of the base, latched and +locked modifiers. +</para> + + +<para> +The effective group is the arithmetic sum of the base, latched and locked +groups. The locked and effective keyboard group must fall in the range +<emphasis> +Group1</emphasis> +-<emphasis> +Group4</emphasis> +, so they are adjusted into range as specified by the global <emphasis> +GroupsWrap </emphasis> +control as follows: +</para> + +<itemizedlist> + <listitem> + <para> +If the <emphasis> +RedirectIntoRange</emphasis> + flag is set, the four least significant +bits of the groups wrap control specify the index of a group to which all +illegal groups correspond. If the specified group is also out of range, all +illegal groups map to <emphasis> +Group1</emphasis>. + </para> + </listitem> + <listitem> + <para> +If the <emphasis> +ClampIntoRange</emphasis> + flag is set, out-of-range groups +correspond to the nearest legal group. Effective groups larger than the highest +supported group are mapped to the highest supported group; effective groups +less than <emphasis> +Group1</emphasis> + are mapped to <emphasis> +Group1</emphasis> +. For example, a key with two groups of symbols uses <emphasis> +Group2</emphasis> + type and symbols if the global effective group is either <emphasis> +Group3</emphasis> + or <emphasis> +Group4</emphasis>. + </para> + </listitem> + <listitem> + <para> +If neither flag is set, group is +wrapped into range using integer modulus. For example, a key with two groups of +symbols for which groups wrap uses <emphasis> +Group1</emphasis> + symbols if the global effective group is <emphasis> +Group3</emphasis> + or <emphasis> +Group2</emphasis> + symbols if the global effective group is <emphasis> +Group4</emphasis>. + </para> + </listitem> +</itemizedlist> + +<para> +The base and latched keyboard groups are unrestricted eight-bit integer values +and are not affected by the <emphasis> +GroupsWrap</emphasis> + control. +</para> + +</sect2> + +<sect2 id='computing_a_state_field_from_an_xkb_state'> +<title>Computing A State Field from an XKB State</title> +<para> +Many events report the keyboard state +in a single <emphasis> +state</emphasis> + field. Using XKB, a state field combines modifiers, group and the pointer +button state into a single sixteen bit value as follows: +</para> + +<itemizedlist> +<listitem> + <para>Bits 0 through 7 (the least significant eight bits) of the effective +state comprise a mask of type KEYMASK which reports the state modifiers. + </para> +</listitem> +<listitem> + <para>Bits 8 through 12 comprise a mask of type BUTMASK which reports pointer +button state. + </para> +</listitem> +<listitem> + <para>Bits 13 and 14 are interpreted as a two-bit unsigned numeric value and +report the state keyboard group. + </para> +</listitem> +<listitem> + <para>Bit 15 (the most significant bit) is reserved and must be zero. + </para> +</listitem> +</itemizedlist> + +<para> +It is possible to assemble a state field from any of the components of the XKB +keyboard state. For example, the effective keyboard state would be assembled as +described above using the effective keyboard group, the effective keyboard +modifiers and the pointer button state. +</para> + +</sect2> +</sect1> + +<sect1 id='derived_components_of_xkb_keyboard_state'> +<title>Derived Components of XKB Keyboard State</title> +<para> +In addition to the fundamental state +components, XKB keeps track of and reports a number of state components which +are derived from the fundamental components but stored and reported separately +to make it easier to track changes in the keyboard state. These derived +components are updated automatically whenever any of the fundamental components +change but cannot be changed directly. +</para> + +<para> +The first pair of derived state components control the way that passive grabs +are activated and the way that modifiers are reported in core protocol events +that report state. The server uses the <emphasis> +ServerInternalModifiers</emphasis> +, <emphasis> +IgnoreLocksModifiers</emphasis> + and <emphasis> +IgnoreGroupLock</emphasis> + controls, described in <ulink url="XKBproto.htm#50332257_45660">See Server +Internal Modifiers and Ignore Locks Behavior</ulink>, to derive these two +states as follows: +</para> + +<itemizedlist> +<listitem> + <para>The lookup state is the state used to determine the symbols associated +with a key event and consists of the effective state minus any server internal +modifiers. + </para> +</listitem> +<listitem> + <para>The grab state is the state used to decide whether a particular event +triggers a passive grab and consists of the lookup state minus any members of +the ignore locks modifiers that are not either latched or logically depressed. +If the ignore group locks control is set, the grab state does not include the +effects of any locked groups. + </para> +</listitem> +</itemizedlist> + +<sect2 id='server_internal_modifiers_and_ignore_locks_behavior'> +<title>Server Internal Modifiers and Ignore Locks Behavior</title> +<para> +The core protocol does not provide any +way to exclude certain modifiers from client events, so there is no way to set +up a modifier which affects only the server. +</para> + +<para> +The modifiers specified in the mask of the <emphasis> +InternalMods</emphasis> + control are not reported in any core +protocol events, are not used to determine grabs and are not used to calculate +compatibility state for XKB-unaware clients. Server internal modifiers affect +only the action applied when a key is pressed. +</para> + + +<para> +The core protocol does not provide any way to exclude certain modifiers from +grab calculations, so locking modifiers often have unanticipated and +unfortunate side-effects. XKB provides another mask which can help avoid some +of these problems. +</para> + + +<para> +The locked state of the modifiers specified in mask of the <emphasis> +IgnoreLockMods</emphasis> + control is not reported in most core +protocol events and is not used to activate grabs. The only core events which +include the locked state of the modifiers in the ignore locks mask are key +press and release events that do not activate a passive grab and which do not +occur while a grab is active. If the <emphasis> +IgnoreGroupLock</emphasis> + control is set, the locked state of the +keyboard group is not considered when activating passive grabs. +</para> + + +<para> +Without XKB, the passive grab set by a translation (e.g. <emphasis> +Alt<KeyPress>space</emphasis> +) does not trigger if any modifiers other than those specified by the +translation are set, with the result that many user interface components do not +react when either Num Lock or when the secondary keyboard group are active. The +ignore locks mask and the ignore group locks control make it possible to avoid +this behavior without exhaustively grabbing every possible modifier combination. +</para> + + +</sect2> +</sect1> +<sect1 id='compatibility_components_of_keyboard_state'> +<title>Compatibility Components of Keyboard State</title> +<para> +The core protocol interpretation of +keyboard modifiers does not include direct support for multiple groups, so XKB +reports the effective keyboard group to XKB-aware clients using some of the +reserved bits in the state field of some core protocol events, as described in +<ulink url="XKBproto.htm#50332257_90933">See Computing A State Field from an +XKB State</ulink>. +</para> + +<para> +This modified state field would not be interpreted correctly by XKB-unaware +clients, so XKB provides a <emphasis> +group compatibility mapping</emphasis> +(see <ulink +url="XKBproto.htm#50332257_40656">See Group Compatibility Map</ulink>) which +remaps the keyboard group into a core modifier mask that has similar effects, +when possible. XKB maintains three compatibility state components that are used +to make non-XKB clients work as well as possible: +</para> + +<itemizedlist> + <listitem> + <para> +The <emphasis> +compatibility state</emphasis> + corresponds to the effective modifier +and effective group state. + </para> + </listitem> + <listitem> + <para> +The <emphasis> +compatibility lookup state</emphasis> + is the core-protocol equivalent of the +lookup state. + </para> + </listitem> + <listitem> + <para> +The <emphasis> +compatibility grab state</emphasis> + is the nearest core-protocol equivalent +of the grab state. + </para> + </listitem> +</itemizedlist> + +<para> +Compatibility states are essentially the corresponding XKB state, but with +keyboard group possibly encoded as one or more modifiers; <ulink +url="XKBproto.htm#50332257_40656">See Group Compatibility Map</ulink> describes +the group compatibility map, which specifies the modifier(s) that correspond to +each keyboard group. +</para> + + +<para> +The compatibility state reported to XKB-unaware + clients for any given core protocol event +is computed from the modifier state that XKB-capable clients would see for that +same event. For example, if the ignore group locks control is set and group 2 +is locked, the modifier bound to <emphasis> +Mode_switch</emphasis> + is not reported in any event except (Device)KeyPress and (Device)KeyRelease +events that do not trigger a passive grab. +</para> + +<note> +<para> +Referring to clients as "XKB-capable + is somewhat misleading in this context. +The sample implementation of XKB invisibly extends the X library to use the +keyboard extension if it is present. This means that most clients can take +advantage of all of XKB without modification, but it also means that the XKB +state can be reported to clients that have not explicitly requested the +keyboard extension. Clients that <emphasis> +directly</emphasis> + interpret the state field of core protocol events or that interpret the keymap +directly may be affected by some of the XKB differences; clients that use +library or toolkit routines to interpret keyboard events automatically use all +of the XKB features. +</para> +</note> + +<para> +XKB-aware clients can query the keyboard state at any time or request immediate +notification of a change to any of the fundamental or derived components of the +keyboard state. +</para> +</sect1> +</chapter> diff --git a/specs/ch03.xml b/specs/ch03.xml new file mode 100644 index 0000000..1181172 --- /dev/null +++ b/specs/ch03.xml @@ -0,0 +1,220 @@ +<chapter id='virtual_modifiers'> +<title>Virtual Modifiers</title> +<para> +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 <emphasis> +Num_Lock</emphasis> + is bound to some modifier, that modifier is used to choose shifted or +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 +<emphasis> +Mod1</emphasis> + through <emphasis> +Mod5</emphasis> +, to keysyms such as <emphasis> +Num_Lock</emphasis> + and <emphasis> +Mode_switch</emphasis> +. Clients 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. They must repeat this process for +all modifiers whenever any part of the modifier mapping is changed. +</para> + +<para> +XKB provides a set of sixteen named virtual modifiers, each of which can be +bound to any set of the eight "real" modifiers (<emphasis> +Shift</emphasis> +, <emphasis> +Lock</emphasis> +, <emphasis> +Control</emphasis> + and <emphasis> +Mod1</emphasis> +-<emphasis> +Mod5</emphasis> + as reported in the keyboard state). This makes it easier for applications and +keyboard layout designers to specify to the function a modifier key or data +structure should fulfill without having to worry about which modifier is bound +to a particular keysym. +</para> + + +<para> +The use of a single, server-driven mechanism for reporting changes to all data +structures makes it easier for clients to stay synchronized. For example, the +core protocol specifies a special interpretation for the modifier bound to the +<emphasis> +Num_Lock</emphasis> + key. Whenever any keys or modifiers are rebound, every application has to +check the keyboard mapping to make sure that the binding for <emphasis> +Num_Lock</emphasis> + has not changed. If <emphasis> +Num_Lock</emphasis> + is remapped when XKB is in use, the keyboard description is automatically +updated to reflect the new binding, and clients are notified immediately and +explicitly if there is a change they need to consider. +</para> + + +<para> +The separation of function from physical modifier bindings also makes it easier +to specify more clearly the intent of a binding. X servers do not all assign +modifiers the same way — for example, <emphasis> +Num_Lock</emphasis> + might be bound to <emphasis> +Mod2</emphasis> + for one vendor and to <emphasis> +Mod4</emphasis> + 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 simply use virtual modifiers to +specify the behavior they want, without regard for the actual physical bindings +in effect. +</para> + + +<para> +XKB puts most aspects of the keyboard under user or program control, so it is +even more important to clearly and uniformly refer to modifiers by function. +</para> + +<sect1 id='modifier_definitions'> +<title>Modifier Definitions</title> +<para> +Use an <emphasis> +XKB modifier definition</emphasis> + to specify the modifiers affected by any XKB control or data structure. An XKB +modifier definition consists of a set of real modifiers, a set of virtual +modifiers, and an effective mask. The mask is derived from the real and virtual +modifiers and cannot be explicitly changed — it contains all of the real +modifiers specified in the definition <emphasis> +plus</emphasis> + any real modifiers that are bound to the virtual modifiers specified in the +definition. For example, this modifier definition specifies the numeric lock +modifier if the <emphasis> +Num_Lock</emphasis> + keysym is not bound to any real modifier: +</para> +<literallayout class='monospaced'> +{ real_mods= None, virtual_mods= NumLock, mask= None } +</literallayout> + +<para> +If we assign <emphasis> +Mod2</emphasis> + to the <emphasis> +Num_Lock</emphasis> + key, the definition changes to: +</para> + +<literallayout class='monospaced'> +{ real_mods= None, virtual_mods= NumLock, mask= Mod2 } +</literallayout> + +<para> +Using this kind of modifier definition makes it easy to specify the desired +behavior in such a way that XKB can automatically update all of the data +structures that make up a keymap to reflect user or application specified +changes in any one aspect of the keymap. +</para> + + +<para> +The use of modifier definitions also makes it possible to unambiguously specify +the reason that a modifier is of interest. On a system for which the <emphasis> +Alt</emphasis> + and <emphasis> +Meta</emphasis> + keysyms are bound to the same modifier, the following definitions behave +identically: +</para> + +<literallayout class='monospaced'> +{ real_mods= None, virtual_mods= Alt, mask= Mod1 } +{ real_mods= None, virtual_mods= Meta, mask= Mod1 } +</literallayout> + +<para> +If we rebind one of the modifiers, the modifier definitions automatically +reflect the change: +</para> + +<literallayout class='monospaced'> +{ real_mods= None, virtual_mods= Alt, mask= Mod1 } +{ real_mods= None, virtual_mods= Meta, mask= Mod4 } +</literallayout> + +<para> +Without the level of indirection provided by virtual modifier maps and modifier +definitions, we would have no way to tell which of the two definitions is +concerned with <emphasis> +Alt</emphasis> + and which is concerned with <emphasis> +Meta</emphasis>. +</para> + + +<sect2 id='inactive_modifier_definitions'> +<title>Inactive Modifier Definitions</title> +<para> +Some XKB structures ignore modifier +definitions in which the virtual modifiers are unbound. Consider this +example: +</para> +<literallayout class='monospaced'> +if ( state matches { Shift } ) Do OneThing; +if ( state matches { Shift+NumLock } ) Do Another; +</literallayout> + +<para> +If the <emphasis> +NumLock</emphasis> + virtual modifier is not bound to any real modifiers, these effective masks for +these two cases are identical (i.e. they contain only <emphasis> +Shift</emphasis> +). When it is essential to distinguish between <emphasis> +OneThing</emphasis> + and Another, XKB considers only those modifier definitions for which all +virtual modifiers are bound. +</para> +</sect2> +</sect1> + +<sect1 id='virtual_modifier_mapping'> +<title>Virtual Modifier Mapping</title> +<para> +XKB maintains a <emphasis> +virtual modifier mapping</emphasis> +, which lists the virtual modifiers associated with 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. +</para> + +<para> +For example, if <emphasis> +Mod3</emphasis> + is bound to the <emphasis> +Num_Lock</emphasis> + key by the core protocol modifier mapping, and the <emphasis> +NumLock</emphasis> + virtual modifier is bound to they <emphasis> +Num_Lock</emphasis> + key by the virtual modifier mapping, <emphasis> +Mod3</emphasis> + is added to the set of modifiers associated with the <emphasis> +NumLock</emphasis> + virtual modifier. +</para> + + +<para> +The virtual modifier mapping is normally updated automatically whenever actions +are assigned to keys (see <ulink url="XKBproto.htm#50332257_84091">See Changing +the Keyboard Mapping Using the Core Protocol</ulink> for details) and few +applications should need to change the virtual modifier mapping explicitly. +</para> +</sect1> +</chapter> diff --git a/specs/ch04.xml b/specs/ch04.xml new file mode 100644 index 0000000..4ea8e92 --- /dev/null +++ b/specs/ch04.xml @@ -0,0 +1,867 @@ +<chapter id='global_keyboard_controls'> +<title>Global Keyboard Controls</title> + +<para> +The X Keyboard Extension supports a number of <emphasis> +global key controls</emphasis> +, which affect the way that XKB handles the keyboard as a whole. Many of these +controls make the keyboard more accessible to the physically impaired and are +based on the AccessDOS package<footnote><para> +AccessDOS provides access to the DOS operating system for people with physical +impairments and was developed by the Trace R&D Center at the University of +Wisconsin. For more information on AccessDOS, contact the Trace R&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.</para></footnote>. +</para> + +<sect1 id='the_repeatkeys_control'> +<title>The RepeatKeys Control</title> + +<para> +The core protocol only allows control over whether or not the entire keyboard +or individual keys should autorepeat when held down. The <emphasis> +RepeatKeys</emphasis> + control extends this capability by adding control over the delay until a key +begins to repeat and the rate at which it repeats. <emphasis> +RepeatKeys</emphasis> + is also coupled with the core autorepeat control; changes to one are always +reflected in the other. +</para> + + +<para> +The <emphasis> +RepeatKeys</emphasis> + control has two parameters. The <emphasis> +autorepeat delay</emphasis> + specifies the delay between the initial press of an autorepeating key and the +first generated repeat event in milliseconds. The <emphasis> +autorepeat interval</emphasis> + specifies the delay between all subsequent generated repeat events in +milliseconds. +</para> + + +<sect2 id='the_perkeyrepeat_control'> +<title>The PerKeyRepeat Control</title> + +<para> +When <emphasis> +RepeatKeys</emphasis> + are active, the <emphasis> +PerKeyRepeat</emphasis> + control specifies whether or not individual keys should autorepeat when held +down. XKB provides the <emphasis> +PerKeyRepeat</emphasis> + for convenience only, and it always parallels the <emphasis> +auto-repeats</emphasis> + field of the core protocol <emphasis> +GetKeyboardControl</emphasis> + request — changes to one are always reflected in the other. +</para> + + +</sect2> +<sect2 id='detectable_autorepeat'> +<title>Detectable Autorepeat</title> + +<para> +The X server usually generates both press and release events whenever an +autorepeating key is held down. If an XKB-aware client enables the <emphasis> +DetectableAutorepeat</emphasis> + per-client option for a keyboard, the server sends that client a key release +event only when the key is <emphasis> +physically</emphasis> + released. For example, holding down a key to generate three characters without +detectable autorepeat yields: +</para> + +<literallayout class='monospaced'> +Press <emphasis>-></emphasis> Release <emphasis>-></emphasis> Press <emphasis>-></emphasis> Release <emphasis>-></emphasis> Press <emphasis>-></emphasis> Release +</literallayout> + +<para> +If detectable autorepeat is enabled, the client instead receives: +</para> + +<literallayout class='monospaced'> +Press<emphasis>-></emphasis> Press <emphasis>-></emphasis> Press <emphasis>-></emphasis> Release +</literallayout> + +<para> +Note that only clients that request detectable autorepeat are affected; other +clients continue to receive both press and release events for autorepeating +keys. Also note that support for detectable autorepeat is optional; servers are +not required to support detectable autorepeat, but they must correctly report +whether or not it is supported. +</para> + + +<para> +<ulink url="XKBproto.htm#50332257_24503">See Querying and Changing Per-Client +Flags</ulink> describes the <emphasis> +XkbPerClientFlags</emphasis> + request, which reports or changes values for all of the per-client flags, and +which lists the per-client flags that are supported. +</para> + + +</sect2> +</sect1> +<sect1 id='the_slowkeys_control'> +<title>The SlowKeys Control</title> + +<para> +Some users often bump keys accidentally while moving their hand or typing stick +toward the key they want. Usually, the keys that are bumped accidentally are +hit only for a very short period of time. The <emphasis> +SlowKeys</emphasis> + control helps filter these accidental bumps by telling the server to wait a +specified period, called the <emphasis> +SlowKeys acceptance delay</emphasis> +, before delivering key events. If the key is released before this period +elapses, no key events are generated. The user can then bump any number of keys +on their way to the one they want without generating unwanted characters. Once +they have reached the key they want, they can then hold it long enough for +<emphasis> +SlowKeys</emphasis> + to accept it. +</para> + + +<para> +The <emphasis> +SlowKeys</emphasis> + control has one parameter; the <emphasis> +slow keys delay</emphasis> + specifies the length of time, in milliseconds, that a key must be held down +before it is accepted. +</para> + + +<para> +When <emphasis> +SlowKeys</emphasis> + are active, the X Keyboard Extension reports the initial press, acceptance, +rejection or release of any key to interested clients using <emphasis> +AccessXNotify</emphasis> + events. The <emphasis> +AccessXNotify</emphasis> + event is described in more detail in <ulink +url="XKBproto.htm#50332257_22322">See Events</ulink>. +</para> + +</sect1> +<sect1 id='the_bouncekeys_control'> +<title>The BounceKeys Control</title> + +<para> +Some people with physical impairments accidentally "bounce" on a key when they +press it. That is, they press it once, then accidentally press it again +immediately. The <emphasis> +BounceKeys</emphasis> + control temporarily disables a key after it has been pressed, effectively +"debouncing" the keyboard. +</para> + + +<para> +The <emphasis> +BounceKeys</emphasis> + has a single parameter. The <emphasis> +BounceKeys delay</emphasis> + specifies the period of time, in milliseconds, that the key is disabled after +it is pressed. +</para> + + +<para> +When <emphasis> +BounceKeys</emphasis> + are active, the server reports the acceptance or rejection of any key to +interested clients by sending an <emphasis> +AccessXNotify</emphasis> + event. The <emphasis> +AccessXNotify</emphasis> + event is described in more detail in <ulink +url="XKBproto.htm#50332257_22322">See Events</ulink>. +</para> + +</sect1> +<sect1 id='the_stickykeys_control'> +<title>The StickyKeys Control</title> + +<para> +Some people find it difficult or impossible to press two keys at once. The +<emphasis> +StickyKeys</emphasis> + control makes it easier for them to type by changing the behavior of the +modifier keys. When <emphasis> +StickyKeys</emphasis> + are enabled, a modifier is latched when the user presses it just once, so 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 <emphasis> +Shift</emphasis> + key, release it, then press the <emphasis> +1</emphasis> + key. +</para> + + +<para> +By default, <emphasis> +StickyKeys</emphasis> + also allows users to lock modifier keys without requiring special locking +keys. The user can press a modifier twice in a row to lock it, and then unlock +it by pressing it one more time. +</para> + + +<para> +Modifiers are automatically unlatched when the user presses a non-modifier key. +For instance, to enter the sequence <emphasis> +Shift</emphasis> ++<emphasis> +Ctrl</emphasis> ++<emphasis> +Z</emphasis> + the user could press and release the <emphasis> +Shift</emphasis> + key to latch the <emphasis> +Shift</emphasis> + modifier, then press and release the <emphasis> +Ctrl</emphasis> + key to latch the <emphasis> +Control</emphasis> + modifier — the <emphasis> +Ctrl</emphasis> + key is a modifier key, so pressing it does not unlatch the <emphasis> +Shift</emphasis> + modifier, but leaves both the <emphasis> +Shift</emphasis> + and <emphasis> +Control</emphasis> + modifiers latched, instead. When the user presses the <emphasis> +Z</emphasis> + key, it will be as though the user pressed <emphasis> +Shift</emphasis> ++<emphasis> +Ctrl</emphasis> ++<emphasis> +Z</emphasis> + simultaneously. The <emphasis> +Z</emphasis> + key is not a modifier key, so the <emphasis> +Shift</emphasis> + and <emphasis> +Control</emphasis> + modifiers are unlatched after the event is generated. +</para> + + +<para> +A locked a modifier remains in effect until the user unlocks it. For example, +to enter the sequence ("XKB") on a PC-style keyboard with a typical US/ASCII +layout, the user could press and release the <emphasis> +Shift</emphasis> + key twice to lock the <emphasis> +Shift</emphasis> + modifier. Then, when the user presses the <emphasis> +9</emphasis> +, <emphasis> +‘</emphasis> +, <emphasis> +x</emphasis> +, <emphasis> +k</emphasis> +, <emphasis> +b</emphasis> +, <emphasis> +‘</emphasis> +, and <emphasis> +0</emphasis> + keys in sequence, it will generate ("XKB"). To unlock the <emphasis> +Shift</emphasis> + modifier, the user can press and release the <emphasis> +Shift</emphasis> + key. +</para> + + +<para> +Two option flags modify the behavior of the <emphasis> +StickyKeys</emphasis> + control: +</para> + +<itemizedlist> +<listitem> + <para>If the <emphasis> +XkbAX_TwoKeys</emphasis> + flag is set, XKB automatically turns <emphasis> +StickyKeys</emphasis> + off if the user presses two or more keys at once. This serves to automatically +disable StickyKeys when a user who does not require sticky keys is using the +keyboard. + </para> +</listitem> +<listitem> + <para>The <emphasis> +XkbAX_LatchToLock</emphasis> + controls the locking behavior of <emphasis> +StickyKeys</emphasis> +; the <emphasis> +StickyKeys</emphasis> + control only locks modifiers as described above if the <emphasis> +XkbAX_LatchToLock</emphasis> + flag is set. + </para> +</listitem> +</itemizedlist> + +</sect1> +<sect1 id='the_mousekeys_control'> +<title>The MouseKeys Control</title> + +<para> +The <emphasis> +MouseKeys</emphasis> + control lets a user control all the mouse functions from the keyboard. When +<emphasis> +MouseKeys</emphasis> + are enabled, all keys with <emphasis> +MouseKeys</emphasis> + actions bound to them generate core pointer events instead of normal key press +and release events. +</para> + + +<para> +The <emphasis> +MouseKeys</emphasis> + control has a single parameter, the <emphasis> +mouse keys default button</emphasis> +, which specifies the core pointer button to be used by mouse keys actions that +do not explicitly specify a button. +</para> + + +</sect1> +<sect1 id='the_mousekeysaccel_control'> +<title>The MouseKeysAccel Control</title> + +<para> +If the <emphasis> +MouseKeysAccel</emphasis> + control is enabled, the effect of a pointer motion action changes as a key is +held down. The <emphasis> +mouse keys delay</emphasis> + specifies the amount of time between the initial key press and the first +repeated motion event. The <emphasis> +mouse keys interval</emphasis> + specifies the amount of time between repeated mouse keys events. The <emphasis> +steps to maximum acceleration</emphasis> + field specifies the total number of events before the key is travelling at +maximum speed. The <emphasis> +maximum acceleration</emphasis> + field specifies the maximum acceleration. The <emphasis> +curve</emphasis> + parameter controls the ramp used to reach maximum acceleration. +</para> + + +<para> +When <emphasis> +MouseKeys</emphasis> + are active and a <emphasis> +SA_MovePtr</emphasis> + key action (see <ulink url="XKBproto.htm#50332257_15763">See Key +Actions</ulink>) is activated, a pointer motion event is generated immediately. +If <emphasis> +MouseKeysAccel</emphasis> + is enabled and if acceleration is enabled for the key in question, a second +event is generated after <emphasis> +mouse keys delay </emphasis> +milliseconds, and additional events are generated every <emphasis> +mouse keys interval</emphasis> + milliseconds for as long as the key is held down. +</para> + + +<sect2 id='relative_pointer_motion'> +<title>Relative Pointer Motion</title> + +<para> +If the <emphasis> +SA_MovePtr</emphasis> + action specifies relative motion, events are generated as follows: The initial +event always moves the cursor the distance specified in the action; after +<emphasis> +steps to maximum acceleration</emphasis> + events have been generated, all subsequent events move the pointer the +distance specified in the action times the <emphasis> +maximum acceleration.</emphasis> + Events after the first but before maximum acceleration has been achieved are +accelerated according to the formula: +</para> + +<mediaobject> + <imageobject> + <imagedata fileref="XKBproto-1.gif" format='GIF'/> + </imageobject> +</mediaobject> + + +<para> +Where <emphasis> +action_delta</emphasis> + is the offset specified by the mouse keys action, <emphasis> +max_accel </emphasis> +and <emphasis> +steps_to_max</emphasis> + are parameters to the <emphasis> +MouseKeysAccel</emphasis> + ctrl, and the curveFactor is computed using the <emphasis> +MouseKeysAccel</emphasis> + <emphasis> +curve</emphasis> + parameter as follows: +</para> + +<mediaobject> + <imageobject> <imagedata fileref="XKBproto-2.gif"/> + </imageobject> + </mediaobject> + + +<para> +With the result that a <emphasis> +curve</emphasis> + of <emphasis> +0</emphasis> + causes the distance moved to increase linearly from <emphasis> +action_delta</emphasis> + to <mediaobject> + <imageobject> <imagedata fileref="XKBproto-3.gif"/> + </imageobject> + </mediaobject> + +, and the minimum legal <emphasis> +curve</emphasis> + of -<emphasis> +1000</emphasis> + causes all events after the first move at <emphasis> +max_accel</emphasis> +. A negative <emphasis> +curve</emphasis> + causes an initial sharp increase in acceleration which tapers off, while 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 <emphasis> +steps_to_max</emphasis> +. +</para> + + +</sect2> +<sect2 id='absolute_pointer_motion'> +<title>Absolute Pointer Motion</title> + +<para> +If an <emphasis> +SA_MovePtr</emphasis> + 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. +</para> + + +</sect2> +</sect1> +<sect1 id='the_accessxkeys_control'> +<title>The AccessXKeys Control</title> + +<para> +If <emphasis> +AccessXKeys</emphasis> + is enabled many controls can also be turned on or off from the keyboard by +entering the following standard key sequences: +</para> + +<itemizedlist> +<listitem> + <para>Holding down a shift key by itself for eight seconds toggles the +<emphasis> +SlowKeys</emphasis> + control. + </para> +</listitem> +<listitem> + <para>Pressing and releasing a shift 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 <emphasis> +StickyKeys</emphasis> + control. + </para> +</listitem> +<listitem> + <para>Simultaneously operating two or more modifier keys deactivates the +<emphasis> +StickyKeys</emphasis> + control. + </para> +</listitem> +</itemizedlist> + +<para> +Some of these key sequences optionally generate audible feedback of the change +in state, as described in <ulink url="XKBproto.htm#50332257_21748">See The +AccessXFeedback Control</ulink>, or cause <emphasis> +XkbAccessXNotify</emphasis> + events as described in <ulink url="XKBproto.htm#50332257_22322">See +Events</ulink>. +</para> + + +</sect1> +<sect1 id='the_accessxtimeout_control'> +<title>The AccessXTimeout Control</title> + +<para> +In environments where computers are shared, features such as <emphasis> +SlowKeys</emphasis> + present a problem: if <emphasis> +SlowKeys</emphasis> + is on, the keyboard can appear to be unresponsive because keys have no effect +unless they are held for a certain period of time. To help address this +problem, XKB provides an <emphasis> +AccessXTimeout</emphasis> + control to automatically change the value of any global controls or AccessX +options if the keyboard is idle for a specified period of time. +</para> + + +<para> +The AccessXTimeout control has a number of parameters which affect the duration +of the timeout and the features changed when the timeout expires. +</para> + + +<para> +The <emphasis> +AccessX Timeout</emphasis> + field specifies the number of seconds the keyboard must be idle before the +global controls and AccessX options are modified. The <emphasis> +AccessX Options Mask</emphasis> + field specifies which values in the <emphasis> +AccessX Options</emphasis> + field are to be changed, and the <emphasis> +AccessX Options Values</emphasis> + field specifies the new values for those options. The <emphasis> +AccessX Controls Mask</emphasis> + field specifies which controls are to be changed in the global set of +<emphasis> +enabled controls</emphasis> +, and the <emphasis> +AccessX Controls Values</emphasis> + field specifies the new values for those controls. +</para> + + +</sect1> +<sect1 id='the_accessxfeedback_control'> +<title>The AccessXFeedback Control</title> + +<para> +If <emphasis> +AccessXFeedback</emphasis> + is enabled, special beep-codes indicate changes in keyboard controls (or some +key events when <emphasis> +SlowKeys</emphasis> + or <emphasis> +StickyKeys</emphasis> + are active). Many beep codes sound as multiple tones, but XKB reports a single +<emphasis> +XkbBellNotify</emphasis> + event for the entire sequence of tones. +</para> + + +<para> +All feedback tones are governed by the <emphasis> +AudibleBell</emphasis> + control. Individual feedback tones can be explicitly enabled or disabled using +the <emphasis> +accessX options mask</emphasis> + or set to deactivate after an idle period using the <emphasis> +accessX timeout options mask</emphasis> +. XKB defines the following feedback tones: +</para> + +<informaltable frame='none'> +<tgroup cols='4'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Feedback Name</entry> + <entry>Bell Name</entry> + <entry>Default Sound</entry> + <entry>Indicates</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>FeatureFB</entry> + <entry>AX_FeatureOn</entry> + <entry>rising tone</entry> + <entry>Keyboard control enabled</entry> + </row> + <row rowsep='0'> + <entry> </entry> + <entry>AX_FeatureOff</entry> + <entry>falling tone</entry> + <entry>Keyboard control disabled</entry> + </row> + <row rowsep='0'> + <entry> </entry> + <entry>AX_FeatureChange</entry> + <entry>two tones</entry> + <entry>Several controls changed state</entry> + </row> + <row rowsep='0'> + <entry>IndicatorFB</entry> + <entry>AX_IndicatorOn</entry> + <entry>high tone</entry> + <entry>Indicator Lit</entry> + </row> + <row rowsep='0'> + <entry> </entry> + <entry>AX_IndicatorOff</entry> + <entry>low tone</entry> + <entry>Indicator Extinguished</entry> + </row> + <row rowsep='0'> + <entry> </entry> + <entry>AX_IndicatorChange</entry> + <entry>two high tones</entry> + <entry>Several indicators changed state</entry> + </row> + <row rowsep='0'> + <entry>SlowWarnFB</entry> + <entry>AX_SlowKeysWarning</entry> + <entry>three high tones</entry> + <entry>Shift key held for four seconds</entry> + </row> + <row rowsep='0'> + <entry>SKPressFB</entry> + <entry>AX_SlowKeyPress</entry> + <entry>single tone</entry> + <entry>Key press while <emphasis> +SlowKeys</emphasis> + are on</entry> + </row> + <row rowsep='0'> + <entry>SKReleaseFB</entry> + <entry>AX_SlowKeyRelease</entry> + <entry>single tone</entry> + <entry>Key release while <emphasis> +SlowKeys</emphasis> + are on</entry> + </row> + <row rowsep='0'> + <entry>SKAcceptFB</entry> + <entry>AX_SlowKeyAccept</entry> + <entry>single tone</entry> + <entry>Key event accepted by <emphasis> +SlowKeys</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry>SKRejectFB</entry> + <entry>AX_SlowKeyReject</entry> + <entry>low tone</entry> + <entry>Key event rejected by <emphasis> +SlowKeys</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry>StickyKeysFB</entry> + <entry>AX_StickyLatch</entry> + <entry>low tone then high tone</entry> + <entry>Modifier latched by <emphasis> +StickyKeys</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry> </entry> + <entry>AX_StickyLock</entry> + <entry>high tone</entry> + <entry>Modifier locked by <emphasis> +StickyKeys</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry> </entry> + <entry>AX_StickyUnlock</entry> + <entry>low tone</entry> + <entry>Modifier unlocked by <emphasis> +StickyKeys</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry>BKRejectFB</entry> + <entry>AX_BounceKeysReject</entry> + <entry>low tone</entry> + <entry>Key event rejected by <emphasis> +BounceKeys</emphasis> +</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +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. +</para> + + +<para> +If the physical keyboard bell is not very capable, attempts to simulate a +continuous tone with multiple bells can sound horrible. Set the <emphasis> +DumbBellFB</emphasis> + AccessX option to inform the server that the keyboard bell is not very capable +and that XKB should use only simple bell combinations. Keyboard capabilities +vary wildly, so the sounds generated for the individual bells when the +<emphasis> +DumbBellFB</emphasis> + option is set are implementation specific. +</para> + + +</sect1> +<sect1 id='the_overlay1_and_overlay2_controls'> +<title>The Overlay1 and Overlay2 Controls</title> + +<para> +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 keyboard that does not actually +have one by generating alternate of keycodes for some keys when the overlay is +enabled. This technique is very common on portable computers and embedded +systems with small keyboards. +</para> + + +<para> +XKB includes direct support for two keyboard overlays, using the <emphasis> +Overlay1</emphasis> + and <emphasis> +Overlay2</emphasis> + controls. When <emphasis> +Overlay1</emphasis> + is enabled, all of the keys that are members of the first keyboard overlay +generate an alternate keycode. When <emphasis> +Overlay2</emphasis> + is enabled, all of the keys that are members of the second keyboard overlay +generate an alternate keycode. +</para> + + +<para> +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 <emphasis> +KB_Overlay1</emphasis> + or <emphasis> +KB_Overlay2</emphasis> + key behaviors, as described in <ulink url="XKBproto.htm#50332257_81140">See +Key Behavior</ulink>. +</para> + + +</sect1> +<sect1 id='boolean_controls_and_the_enabledcontrols_control'> +<title>"Boolean" Controls and The EnabledControls Control</title> + +<para> +All of the controls described above, along with the <emphasis> +AudibleBell</emphasis> + control (described in <ulink url="XKBproto.htm#50332257_18543">See Disabling +Server Generated Bells</ulink>) and the <emphasis> +IgnoreGroupLock</emphasis> + control (described in <ulink url="XKBproto.htm#50332257_45660">See Server +Internal Modifiers and Ignore Locks Behavior</ulink>) comprise the <emphasis> +boolean controls</emphasis> +. In addition to any parameters listed in the descriptions of the individual +controls, the boolean controls can be individually enabled or disabled by +changing the value of the <emphasis> +EnabledControls</emphasis> + control. +</para> + + +<para> +The following <emphasis> +non-boolean</emphasis> + controls are always active and cannot be changed using the <emphasis> +EnabledControls</emphasis> + control or specified in any context that accepts only boolean controls: +<emphasis> +GroupsWrap</emphasis> + (<ulink url="XKBproto.htm#50332257_67222">See Computing Effective Modifier and +Group</ulink>), <emphasis> +EnabledControls</emphasis> +, <emphasis> +InternalMods</emphasis> + (<ulink url="XKBproto.htm#50332257_45660">See Server Internal Modifiers and +Ignore Locks Behavior</ulink>), and <emphasis> +IgnoreLockMods</emphasis> + (<ulink url="XKBproto.htm#50332257_45660">See Server Internal Modifiers and +Ignore Locks Behavior</ulink>) and <emphasis> +PerKeyRepeat</emphasis> + (<ulink url="XKBproto.htm#50332257_48937">See The RepeatKeys Control</ulink>) +</para> + + +</sect1> +<sect1 id='automatic_reset_of_boolean_controls'> +<title>Automatic Reset of Boolean Controls</title> + +<para> +The <emphasis> +auto-reset controls</emphasis> + are a per-client value which consist of two masks that can contain any of the +boolean controls (see <ulink url="XKBproto.htm#50332257_12486">See "Boolean" +Controls and The EnabledControls Control</ulink>). Whenever the client exits +for any reason, any boolean controls specified in the <emphasis> +auto-reset mask</emphasis> + are set to the corresponding value from the <emphasis> +auto-reset values</emphasis> + mask. This makes it possible for clients to "clean up after themselves" +automatically, even if abnormally terminated. +</para> + + +<para> +For example, a client that replace the keyboard bell with some other audible +cue might want to turn off the <emphasis> +AudibleBell</emphasis> + control (<ulink url="XKBproto.htm#50332257_18543">See Disabling Server +Generated Bells</ulink>) to prevent the server from also generating a sound and +thus avoid cacophony. If the client were to exit without resetting the +<emphasis> +AudibleBell </emphasis> +control, the user would be left without any feedback at all. Setting <emphasis> +AudibleBell</emphasis> + in both the auto-reset mask and auto-reset values guarantees that the audible +bell will be turned back on when the client exits. +</para> +</sect1> +</chapter> diff --git a/specs/ch05.xml b/specs/ch05.xml new file mode 100644 index 0000000..d00a26d --- /dev/null +++ b/specs/ch05.xml @@ -0,0 +1,88 @@ + +<chapter id='key_event_processing_overview'> +<title>Key Event Processing Overview</title> + +<para> +There are three steps to processing each key event in the X server, and at +least three in the client. This section describes each of these steps briefly; +the following sections describe each step in more detail. +</para> + +<orderedlist> +<listitem> + <para>First, the server applies global keyboard controls to determine whether +the key event should be processed immediately, deferred, or ignored. For +example, the <emphasis> +SlowKeys</emphasis> + control can cause a key event to be deferred until the slow keys delay has +elapsed while the <emphasis> +RepeatKeys</emphasis> + control can cause multiple X events from a single physical key press if the +key is held down for an extended period. The global keyboard controls affect +all of the keys on the keyboard and are described in <ulink +url="XKBproto.htm#50332257_28742">See Global Keyboard Controls</ulink>. + </para> +</listitem> +<listitem> + <para>Next, the server applies per-key behavior. Per key-behavior can be used +to simulate or indicate some special kinds of key behavior. For example, +keyboard overlays, in which a key generates an alternate keycode under certain +circumstances, can be implemented using per-key behavior. Every key has a +single behavior, so the effect of key behavior does not depend on keyboard +modifier or group state, though it might depend on global keyboard controls. +Per-key behaviors are described in detail in <ulink +url="XKBproto.htm#50332257_81140">See Key Behavior</ulink>. + </para> +</listitem> +<listitem> + <para>Finally, the server applies key actions. Logically, every keysym on the +keyboard has some action associated with it. The key action tells the server +what to do when an event which yields the corresponding keysym is generated. +Key actions might change or suppress the event, generate some other event, or +change some aspect of the server. Key actions are described in <ulink +url="XKBproto.htm#50332257_15763">See Key Actions</ulink>. + </para> +</listitem> +</orderedlist> + +<para> +If the global controls, per-key behavior and key action combine to cause a key +event, the client which receives the event processes it in several steps. +</para> + +<orderedlist> +<listitem> + <para>First the client extracts the effective keyboard group and a set of +modifiers from the state field of the event. See <ulink +url="XKBproto.htm#50332257_90933">See Computing A State Field from an XKB +State</ulink> for details. + </para> +</listitem> +<listitem> + <para>Using the modifiers and effective keyboard group, the client selects a +symbol from the list of keysyms bound to the key. <ulink +url="XKBproto.htm#50332257_24122">See Determining the KeySym Associated with a +Key Event</ulink> discusses symbol selection. + </para> +</listitem> +<listitem> + <para>If necessary, the client transforms the symbol and resulting string +using any modifiers that are "left over" from the process of looking up a +symbol. For example, if the <emphasis> +Lock</emphasis> + modifier is left over, the resulting keysym is capitalized according to the +capitalization rules specified by the system. See <ulink +url="XKBproto.htm#50332257_25094">See Transforming the KeySym Associated with a +Key Event</ulink> for a more detailed discussion of the transformations defined +by XKB. + </para> +</listitem> +<listitem> + <para>Finally, the client uses the keysym and remaining modifiers in an +application-specific way. For example, applications based on the X toolkit +might apply translations based on the symbol and modifiers reported by the +first three steps. + </para> +</listitem> +</orderedlist> +</chapter> diff --git a/specs/ch06.xml b/specs/ch06.xml new file mode 100644 index 0000000..74a8e3c --- /dev/null +++ b/specs/ch06.xml @@ -0,0 +1,1765 @@ +<chapter id='key_event_processing_in_the_server'> +<title>Key Event Processing in the Server</title> + +<para> +This section describes the steps involved in processing a key event within the +server when XKB is present. Key events can be generated due to keyboard +activity and passed to XKB by the DDX layer, or they can be synthesized by +another extension, such as XTEST. +</para> + +<sect1 id='applying_global_controls'> +<title>Applying Global Controls</title> + +<para> +When the X Keyboard Extension receives a key event, it first checks the global +key controls to decide whether to process the event immediately or at all. The +global key controls which might affect the event, in descending order of +priority, are: +</para> + +<itemizedlist> +<listitem> + <para>If a key is pressed while the <emphasis> +BounceKeys</emphasis> + control is enabled, the extension generates the event only if the key is +active. When a key is released, the server deactivates the key and starts a +<emphasis> +bounce keys timer</emphasis> + with an interval specified by the debounce delay. + </para> + <para> +If the bounce keys timer expires or if some other key is pressed before the +timer expires, the server reactivates the corresponding key and deactivates the +timer. Neither expiration nor deactivation of a bounce keys timer causes an +event.</para> +</listitem> +<listitem> + <para>If the <emphasis> +SlowKeys</emphasis> + control is enabled, the extension sets a <emphasis> +slow keys timer</emphasis> + with an interval specified by the slow keys delay, but does not process the +key event immediately. The corresponding key release deactivates this timer. + </para> + <para> +If the slow keys timer expires, the server generates a key press for the +corresponding key, sends an <emphasis> +XkbAccessXNotify</emphasis> + and deactivates the timer. + </para> +</listitem> +<listitem> + <para>The extension processes key press events normally whether or not the +<emphasis> +RepeatKeys</emphasis> + control is active, but if <emphasis> +RepeatKeys</emphasis> + are enabled and per-key autorepeat is enabled for the event key, the extension +processes key press events normally, but it also initiates an <emphasis> +autorepeat timer</emphasis> + with an interval specified by the autorepeat delay. The corresponding key +release deactivates the timer. + </para> + <para> +If the autorepeat timer expires, the server generates a key release and a key +press for the corresponding key and reschedules the timer according to the +autorepeat interval. + </para> +</listitem> +</itemizedlist> + +<para> +Key events are processed by each global control in turn: if the <emphasis> +BounceKeys</emphasis> + control accepts a key event, <emphasis> +SlowKeys</emphasis> + considers it. Once <emphasis> +SlowKeys</emphasis> + allows or synthesizes an event, the <emphasis> +RepeatKeys</emphasis> + control acts on it. +</para> + + +</sect1> +<sect1 id='key_behavior'> +<title>Key Behavior</title> + +<para> +Once an event is accepted by all of the controls or generated by a timer, the +server checks the per-key behavior of the corresponding key. This extension +currently defines the following key behaviors: +</para> + +<informaltable frame='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Behavior</entry> + <entry>Effect</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis> +KB_Default</emphasis> + </entry> + <entry>Press and release events are processed normally.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +KB_Lock</emphasis> + </entry> + <entry>If a key is logically up (i.e. 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. +</entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis> +KB_RadioGroup +</emphasis> + </para> + <para> + flags: CARD8 + </para> + <para> + index: CARD8 + </para> + </entry> + <entry><para>If another member of the radio group specified by <emphasis> +index</emphasis> + is logically down 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. </para> +<para> +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 <emphasis> +RGAllowNone</emphasis> + bit in <emphasis> +flags</emphasis> +. If it is set, the key release is processed normally; otherwise the key +release is also ignored. +</para> +<para> +All other key release events are ignored.</para> + </entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis> +KB_Overlay1 +</emphasis> + </para> + <para> + key: KEYCODE + </para> + </entry> + <entry>If the <emphasis> +Overlay1</emphasis> + control is enabled, events from this key are reported as if they came from the +key specified in <emphasis> +key</emphasis> +. Otherwise, press and release events are processed normally.</entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis> +KB_Overlay2 +</emphasis> + </para> + <para> + key: KEYCODE + </para> + </entry> + <entry>If the <emphasis> +Overlay2</emphasis> + control is enabled, events from this key are reported as if they came from the +key specified in <emphasis> +key</emphasis> +. Otherwise, press and release events are processed normally.</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +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. +</para> + +<para> +Key behaviors can be used to simulate any of these types of keys or to indicate +an unmodifiable physical, electrical or software driver characteristic of a +key. An optional <emphasis> +permanent</emphasis> + flag can modify any of the supported behaviors and indicates that behavior +describes an unalterable physical, electrical or software aspect of the +keyboard. Permanent behaviors cannot be changed or set by the <emphasis> +XkbSetMap</emphasis> + request. The <emphasis> +permanent</emphasis> + flag indicates a characteristic of the underlying system that XKB cannot +affect, so XKB treats all permanent behaviors as if they were <emphasis> +KB_Default</emphasis> + and does not filter key events described in the table above. +</para> + + +</sect1> +<sect1 id='key_actions'> +<title>Key Actions</title> + +<para> +Once the server has applied the global controls and per-key behavior and has +decided to process a key event, it applies <emphasis> +key actions</emphasis> + to determine the effects of the key on the internal state of the server. A key +action consists of an operator and some optional data. XKB supports actions +which: +</para> + +<itemizedlist> +<listitem> + <para>change base, latched or locked modifiers or group + </para> +</listitem> +<listitem> + <para>move the core pointer or simulate core pointer button events + </para> +</listitem> +<listitem> + <para>change most aspects of keyboard behavior + </para> +</listitem> +<listitem> + <para>terminate or suspend the server + </para> +</listitem> +<listitem> + <para>send a message to interested clients + </para> +</listitem> +<listitem> + <para>simulate events on other keys + </para> +</listitem> +</itemizedlist> + +<para> +Each key has an optional list of actions. If present, this list parallels the +list of symbols associated with the key (i.e. it has one action per symbol +associated with the key). For key press events, the server looks up the action +to be applied from this list using the key symbol mapping associated with the +event key, just as a client looks up symbols as described in <ulink +url="XKBproto.htm#50332257_24122">See Determining the KeySym Associated with a +Key Event</ulink>; if the event key does not have any actions, the server uses +the <emphasis> +SA_NoAction</emphasis> + event for that key regardless of modifier or group state. +</para> + + +<para> +Key actions have essentially two halves; the effects on the server when the key +is pressed and the effects when the key is released. The action applied for a +key press event determines the further actions, if any, that are applied to the +corresponding release event or to events that occur while the key is held down. +Clients can change the actions associated with a key while the key is down +without changing the action applied next time the key is released; subsequent +press-release pairs will use the newly bound key action. +</para> + + +<para> +Most actions directly change the state of the keyboard or server; some actions +also modify other actions that occur simultaneously with them. Two actions +occur simultaneously if the keys which invoke the actions are both logically +down at the same time, regardless of the order in which they are pressed or +delay between the activation of one and the other. +</para> + + +<para> +Most actions which affect keyboard modifier state accept a modifier definition +(see <ulink url="XKBproto.htm#50332257_51617">See Virtual Modifiers</ulink>) +named <emphasis> +mods</emphasis> + and a boolean flag name <emphasis> +useModMap</emphasis> + among their arguments. These two fields combine to specify the modifiers +affected by the action as follows: If <emphasis> +useModMap</emphasis> + is <emphasis> +True</emphasis> +, the action sets any modifiers bound by the modifier mapping to the key that +initiated the action; otherwise, the action sets the modifiers specified by +<emphasis> +mods</emphasis> +. For brevity in the text of the following definitions, we refer to this +combination of <emphasis> +useModMap</emphasis> + and <emphasis> +mods</emphasis> + as the "action modifiers." +</para> + + +<para> +The X Keyboard Extension supports the following actions: +</para> + +<informaltable frame='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Action</entry> + <entry>Effect</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis>SA_NoAction</emphasis></entry> + <entry> + <itemizedlist> + <listitem> + <para> +No direct effect, though <emphasis>SA_NoAction</emphasis> + events may change the effect of other server actions (see below). + </para> + </listitem> + </itemizedlist> + </entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis>SA_SetMods</emphasis> + </para> + <para> + mods: MOD_DEF + </para> + <para> + useModMap: BOOL + </para> + <para> + clearLocks: BOOL + </para> + </entry> + <entry> + <itemizedlist> + <listitem> + <para> +Key press adds any action modifiers to the keyboard’s base modifiers<emphasis>.</emphasis> + </para> + </listitem> + <listitem> + <para>Key release clears any action modifiers in the keyboard’s base +modifiers, provided that no other key which affects the same modifiers is +logically down. + </para> + </listitem> + <listitem> + <para>If no keys were operated simultaneously with this key and <emphasis> +clearLocks</emphasis> + is set, release unlocks any action modifiers. + </para> + </listitem> + </itemizedlist> + </entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis> +SA_LatchMods +</emphasis> + </para> + <para> + mods: MOD_DEF + </para> + <para> + useModMap: BOOL + </para> + <para> + clearLocks: BOOL + </para> + <para> + latchToLock: BOOL + </para> + </entry> +<entry> +<itemizedlist> +<listitem> + <para>Key press and release events have the same effect as for <emphasis> +SA_SetMods</emphasis> +; if no keys were operated simultaneously with the latching modifier key, key +release events have the following additional effects: + </para> +</listitem> +<listitem> + <para>Modifiers that were unlocked due to <emphasis> +clearLocks</emphasis> + have no further effect. + </para> +</listitem> +<listitem> + <para>If <emphasis> +latchToLock</emphasis> + is set, key release locks and then unlatches any remaining action modifiers +that are already latched. + </para> +</listitem> +<listitem> + <para>Finally, key release latches any action modifiers that were not used by +the <emphasis> +clearLocks</emphasis> + or <emphasis> +latchToLock</emphasis> + flags. + </para> +</listitem> +</itemizedlist> +</entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis> +SA_LockMods + </emphasis> + </para> + <para> + mods: MOD_DEF + </para> + <para> + useModMap: BOOL + </para> + <para> + noLock: BOOL + </para> + <para> + noUnlock: BOOL + </para> + </entry> +<entry> +<itemizedlist> +<listitem> + <para>Key press sets the base and possibly the locked state of any action +modifiers. If <emphasis> +noLock</emphasis> + is <emphasis> +True</emphasis> +, only the base state is changed. + </para> +</listitem> +<listitem> + <para>For key release events, clears any action modifiers in the keyboard’s +base modifiers, provided that no other key which affects the same modifiers is +down. If <emphasis> +noUnlock</emphasis> + is <emphasis> +False</emphasis> + and any of the action modifiers were locked before the corresponding key press +occurred, key release unlocks them. + </para> +</listitem> +</itemizedlist> +</entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis> +SA_SetGroup +</emphasis> + </para> + <para> + group: INT8 + </para> + <para> + groupAbsolute: BOOL + </para> + <para> + clearLocks: BOOL + </para> + </entry> +<entry> +<itemizedlist> +<listitem> + <para>If <emphasis> +groupAbsolute</emphasis> + is set, key press events change the base keyboard group to <emphasis> +group</emphasis> +; otherwise, they add <emphasis> +group</emphasis> + to the base keyboard group. In either case, the resulting effective keyboard +group is brought back into range depending on the value of the <emphasis> +GroupsWrap</emphasis> + control for the keyboard. + </para> +</listitem> +<listitem> + <para>If an <emphasis> +SA_ISOLock</emphasis> + key is pressed while this key is held down, key release has no effect, +otherwise it cancels the effects of the press. + </para> +</listitem> +<listitem> + <para>If no keys were operated simultaneously with this key and <emphasis> +clearLocks</emphasis> + is set, key release also sets the locked keyboard group to <emphasis> +Group1</emphasis> +. + </para> +</listitem> +</itemizedlist> +</entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis> +SA_LatchGroup + </emphasis> + </para> + <para> + group: INT8 + </para> + <para> + groupAbsolute: BOOL + </para> + <para> + clearLocks: BOOL + </para> + <para> + latchToLock: BOOL + </para> + </entry> +<entry> +<itemizedlist> +<listitem> + <para>Key press and release events have the same effect as an <emphasis> +SA_SetGroup</emphasis> + action; if no keys were operated simultaneously with the latching group key +and the <emphasis> +clearLocks</emphasis> + flag was not set or had no effect, key release has the following additional +effects: + </para> +</listitem> +<listitem> + <para>If <emphasis> +latchToLock</emphasis> + is set and the latched keyboard group is non-zero, 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 global +<emphasis> +GroupsWrap</emphasis> + control for the keyboard. + </para> +</listitem> +<listitem> + <para>Otherwise, key release adds the key press delta to the latched keyboard +group. + </para> +</listitem> +</itemizedlist> +</entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis> +SA_LockGroup + </emphasis> + </para> + <para> + group: INT8 + </para> + <para> + groupAbsolute: BOOL + </para> + </entry> +<entry> +<itemizedlist> +<listitem> + <para>If <emphasis> +groupAbsolute</emphasis> + is set, key press sets the locked keyboard group to <emphasis> +group</emphasis> +. Otherwise, key press adds <emphasis> +group</emphasis> + to the locked keyboard group. In either case, the resulting locked and +effective group is brought back into range depending on the value of the +<emphasis> +GroupsWrap</emphasis> + control for the keyboard. + </para> +</listitem> +<listitem> + <para>Key release has no effect. + </para> +</listitem> +</itemizedlist> +</entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis> +SA_MovePtr +</emphasis> + </para> + <para> + x, y: INT16 + </para> + <para> + noAccel: BOOL + </para> + <para> + absoluteX: BOOL + </para> + <para> + absoluteY: BOOL + </para> + </entry> +<entry> +<itemizedlist> +<listitem> + <para>If <emphasis> +MouseKeys</emphasis> + are not enabled, this action behaves like <emphasis> +SA_NoAction</emphasis> +, otherwise this action cancels any pending repeat key timers for this key and +has the following additional effects. + </para> +</listitem> +<listitem> + <para>Key press generates a core pointer <emphasis> +MotionNotify</emphasis> + event instead of the usual <emphasis> +KeyPress</emphasis> +. If <emphasis> +absoluteX</emphasis> + is <emphasis> +True</emphasis> +, <emphasis> +x</emphasis> + specifies the new pointer X coordinate, otherwise <emphasis> +x</emphasis> + is added to the current pointer X coordinate; <emphasis> +absoluteY</emphasis> + and <emphasis> +y</emphasis> + specify the new Y coordinate in the same way. + </para> +</listitem> +<listitem> + <para>If <emphasis> +noAccel</emphasis> + is <emphasis> +False</emphasis> +, and the <emphasis> +MouseKeysAccel</emphasis> + keyboard control is enabled, key press also initiates the mouse keys timer for +this key; every time this timer expires, the cursor moves again. The distance +the cursor moves in these subsequent events is determined by the mouse keys +acceleration as described in <ulink url="XKBproto.htm#50332257_29074">See The +MouseKeysAccel Control</ulink>. + </para> +</listitem> +<listitem> + <para>Key release disables the mouse keys timer (if it was initiated by the +corresponding key press) but has no other effect and is ignored (does not +generate an event of any type). + </para> +</listitem> +</itemizedlist> +</entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis> +SA_PtrBtn + </emphasis> + </para> + <para> + button: CARD8 + </para> + <para> + count: CARD8 + </para> + <para> + useDfltBtn: BOOL + </para> + </entry> +<entry> +<itemizedlist> +<listitem> + <para>If <emphasis> +MouseKeys</emphasis> + are not enabled, this action behaves like <emphasis> +SA_NoAction</emphasis> +. + </para> +</listitem> +<listitem> + <para>If <emphasis> +useDfltBtn</emphasis> + is set, the event is generated for the current default core button. Otherwise, +the event is generated for the button specified by <emphasis> +button</emphasis> +. + </para> +</listitem> +<listitem> + <para>If the mouse button specified for this action is logically down, the +key press and corresponding release are ignored and have no effect. + </para> +</listitem> +<listitem> + <para>Otherwise, key press causes one or more core pointer button events +instead of the usual key press. If <emphasis> +count</emphasis> + is <emphasis> +0</emphasis> +, key press generates a single <emphasis> +ButtonPress</emphasis> + event; if <emphasis> +count</emphasis> + is greater than <emphasis> +0</emphasis> +, key press generates <emphasis> +count</emphasis> + pairs of <emphasis> +ButtonPress</emphasis> + and <emphasis> +ButtonRelease</emphasis> + events. + </para> +</listitem> +<listitem> + <para>If <emphasis> +count</emphasis> + is <emphasis> +0</emphasis> +, key release generates a core pointer <emphasis> +ButtonRelease</emphasis> + which matches the event generated by the corresponding key press; if count is +non-zero, key release does not cause a <emphasis> +ButtonRelease</emphasis> + event. Key release never causes a key release event. + </para> +</listitem> +</itemizedlist> +</entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis> +SA_LockPtrBtn +</emphasis> + </para> + <para> + button: BUTTON + </para> + <para> + noLock: BOOL + </para> + <para> + noUnlock: BOOL + </para> + <para> + useDfltBtn: BOOL + </para> + </entry> +<entry> +<itemizedlist> +<listitem> + <para>If <emphasis> +MouseKeys</emphasis> + are not enabled, this action behaves like <emphasis> +SA_NoAction</emphasis> +. + </para> +</listitem> +<listitem> + <para>Otherwise, if the button specified by <emphasis> +useDfltBtn</emphasis> + and <emphasis> +button</emphasis> + is not locked, key press causes a <emphasis> +ButtonPress</emphasis> + instead of a key press and locks the button. If the button is already locked +or if <emphasis> +noLock</emphasis> + is <emphasis> +True</emphasis> +, key press is ignored and has no effect. + </para> +</listitem> +<listitem> + <para>If the corresponding key press was ignored, and if <emphasis> +noUnlock</emphasis> + is <emphasis> +False</emphasis> +, key release generates a <emphasis> +ButtonRelease</emphasis> + event instead of a key release event and unlocks the specified button. If the +corresponding key press locked a button, key release is ignored and has no +effect. + </para> +</listitem> +</itemizedlist> +</entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis> +SA_SetPtrDflt +</emphasis> + </para> + <para> + affect: CARD8 + </para> + <para> + value: CARD8 + </para> + <para> + dfltBtnAbs: BOOL + </para> + </entry> +<entry> +<itemizedlist> +<listitem> + <para>If <emphasis> +MouseKeys</emphasis> + are not enabled, this action behaves like <emphasis> +SA_NoAction</emphasis> +. + </para> +</listitem> +<listitem> + <para>Otherwise, both key press and key release are ignored, but key press +changes the pointer value specified by <emphasis> +affect </emphasis> +to <emphasis> +value</emphasis> +, as follows: + </para> +</listitem> +<listitem> + <para>If <emphasis> +which</emphasis> + is <emphasis> +SA_AffectDfltBtn</emphasis> +, <emphasis> +value</emphasis> + and <emphasis> +dfltBtnAbs</emphasis> + specify the default pointer button used by the various pointer actions as +follow: If <emphasis> +dfltBtnAbs </emphasis> +is True, value specifies the button to be used, otherwise, <emphasis> +value</emphasis> + specifies the amount to be added to the current default button. In either +case, illegal button choices are wrapped back into range. + </para> +</listitem> +</itemizedlist> +</entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis> +SA_ISOLock +</emphasis> + </para> + <para> + dfltIsGroup: <emphasis> +False +</emphasis> + </para> + <para> + mods: MOD_DEF + </para> + <para> + useModMap: BOOL + </para> + <para> + noLock: BOOL + </para> + <para> + noUnlock: BOOL + </para> + <para> + noAffectMods: BOOL + </para> + <para> + noAffectGrp: BOOL + </para> + <para> + noAffectPtr: BOOL + </para> + <para> + noAffectCtrls: BOOL + </para> + <para> +or + </para> + <para> + dfltIsGroup: <emphasis> +True +</emphasis> + </para> + <para> + group: INT8 + </para> + <para> + groupAbsolute: BOOL + </para> + <para> + noAffectMods: BOOL + </para> + <para> + noAffectGrp: BOOL + </para> + <para> + noAffectPtr: BOOL + </para> + <para> + noAffectCtrls: BOOL + </para> + </entry> +<entry> +<itemizedlist> +<listitem> + <para>If <emphasis> +dfltIsGroup</emphasis> + is <emphasis> +True</emphasis> +, key press sets the base group specified by <emphasis> +groupAbsolute</emphasis> + and <emphasis> +group</emphasis> +. Otherwise, key press sets the action modifiers in the keyboard’s base +modifiers. + </para> +</listitem> +<listitem> + <para>Key release clears the base modifiers or group that were set by the key +press; it may have additional effects if no other appropriate actions occur +simultaneously with the <emphasis> +SA_ISOLock</emphasis> + operation. + </para> +</listitem> +<listitem> + <para>If <emphasis> +noAffectMods</emphasis> + is <emphasis> +False</emphasis> +, any <emphasis> +SA_SetMods</emphasis> + or <emphasis> +SA_LatchMods</emphasis> + actions that occur simultaneously with the <emphasis> +ISOLock</emphasis> + action are treated as <emphasis> +SA_LockMods</emphasis> + instead. + </para> +</listitem> +<listitem> + <para>If <emphasis> +noAffectGrp</emphasis> + is <emphasis> +False</emphasis> +, any <emphasis> +SA_SetGroup</emphasis> + or <emphasis> +SA_LatchGroup</emphasis> + actions that occur simultaneously with this action are treated as <emphasis> +SA_LockGroup</emphasis> + actions instead. + </para> +</listitem> +<listitem> + <para>If <emphasis> +noAffectPtr</emphasis> + is <emphasis> +False</emphasis> +, <emphasis> +SA_PtrBtn</emphasis> + actions that occur simultaneously with the <emphasis> +SA_ISOLock</emphasis> + action are treated as <emphasis> +SA_LockPtrBtn</emphasis> + actions instead. + </para> +</listitem> +<listitem> + <para>If <emphasis> +noAffectCtrls</emphasis> + is <emphasis> +False</emphasis> +, any <emphasis> +SA_SetControls</emphasis> + actions that occur simultaneously with the <emphasis> +SA_ISOLock</emphasis> + action are treated as <emphasis> +SA_LockControls</emphasis> + actions instead. + </para> +</listitem> +<listitem> + <para>If no other actions were transformed by the <emphasis> +SA_ISOLock</emphasis> + action, key release locks the group or modifiers specified by the action +arguments. + </para> +</listitem> +</itemizedlist> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +SA_TerminateServer</emphasis> + </entry> +<entry> +<itemizedlist> +<listitem> + <para>Key press terminates the server. Key release is ignored. + </para> +</listitem> +<listitem> + <para>This action is optional; servers are free to ignore it. If ignored, it +behaves like <emphasis> +SA_NoAction</emphasis> +. + </para> +</listitem> +</itemizedlist> +</entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis> +SA_SwitchScreen +</emphasis> + </para> + <para> + num: INT8 + </para> + <para> + switchApp: BOOL + </para> + <para> + screenAbs: BOOL + </para> +</entry> +<entry> +<itemizedlist> +<listitem> + <para>If the server supports this action and multiple screens or displays +(either virtual or real), this action changes to the active screen indicated by +<emphasis> +num</emphasis> + and <emphasis> +screenAbs</emphasis> +. If <emphasis> +screenAbs</emphasis> + is <emphasis> +True</emphasis> +, num specifies the index of the new screen; otherwise, num specifies an offset +from the current screen to the new screen. + </para> +</listitem> +<listitem> + <para>If <emphasis> +switchApp</emphasis> + is <emphasis> +False</emphasis> +, it should switch to another screen on the same server. Otherwise it should +switch to another X server or application which shares the same physical +display. + </para> +</listitem> +<listitem> + <para>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 <emphasis> +SA_NoAction</emphasis> +, otherwise neither key press nor release generate an event. + </para> +</listitem> +</itemizedlist> +</entry> + </row> + <row rowsep='0'> + <entry> + <para><emphasis>SA_SetControls</emphasis></para> + <para>controls: KB_BOOLCTRLMASK</para> + </entry> + <entry> + <itemizedlist> + <listitem> + <para> +Key press enables any boolean controls that are specified in <emphasis> +controls</emphasis> + and not already enabled at the time of the key press. Key release disables any +controls that were enabled by the corresponding key press. This action can +cause <emphasis> +XkbControlsNotify</emphasis> + events. + </para> + </listitem> + </itemizedlist> + </entry> + </row> + <row rowsep='0'> + <entry> + <para><emphasis>SA_LockControls</emphasis></para> + <para> + controls: KB_BOOLCTRLMASK + </para> + <para> + noLock: BOOL + </para> + <para> + noUnlock: BOOL + </para> + </entry> + <entry> +<itemizedlist> +<listitem> + <para>If <emphasis> +noLock</emphasis> + is <emphasis> +False</emphasis> +, key press locks and enables any controls that are specified in <emphasis> +controls</emphasis> + and not already locked at the time of the key press. +</para> +<para> +If <emphasis> +noUnlock</emphasis> + is <emphasis> +False</emphasis> +, key release unlocks and disables any controls that are specified in <emphasis> +controls</emphasis> + and were not enabled at the time of the corresponding key press. + </para> +</listitem> +</itemizedlist> +</entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis> +SA_ActionMessage</emphasis> +: + pressMsg: BOOL + </para> + <para> + releaseMsg: BOOL + </para> + <para> + genEvent: BOOL + </para> + <para> + message: STRING + </para> + </entry> +<entry> +<itemizedlist> +<listitem> + <para>if <emphasis> +pressMsg</emphasis> + is <emphasis> +True</emphasis> +, key press generates an <emphasis> +XkbActionMessage</emphasis> + event which reports the keycode, event type and the contents of <emphasis> +message</emphasis> +. + </para> +</listitem> +<listitem> + <para>If <emphasis> +releaseMsg</emphasis> + is <emphasis> +True</emphasis> +, key release generates an <emphasis> +XkbActionMessage</emphasis> + event which reports the keycode, event type and contents of <emphasis> +message</emphasis> +. + </para> +</listitem> +<listitem> + <para>If <emphasis> +genEvent</emphasis> + is <emphasis> +True</emphasis> +, both press and release generate key press and key release events, regardless +of whether they also cause an <emphasis> +XkbActionMessage</emphasis> +. + </para> +</listitem> +</itemizedlist> +</entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis> +SA_RedirectKey +</emphasis> + </para> + <para> + newKey: KEYCODE + </para> + <para> + modsMask: KEYMASK + </para> + <para> + mods: KEYMASK + </para> + <para> + vmodsMask: CARD16 + </para> + <para> + vmods: CARD16 + </para> + </entry> +<entry> +<itemizedlist> +<listitem> + <para>Key press causes a key press event for the key specified by <emphasis> +newKey</emphasis> + instead of for the actual key. The state reported in this event reports of the +current effective modifiers changed as follow: Any real modifiers specified in +<emphasis> +modsMask</emphasis> + are set to corresponding values from <emphasis> +mods</emphasis> +. Any real modifiers bound to the virtual modifiers specified in <emphasis> +vmodsMask</emphasis> + are either set or cleared, depending on the corresponding value in <emphasis> +vmods</emphasis> +. If the real and virtual modifier definitions specify conflicting values for a +single modifier, the real modifier definition has priority. + </para> +</listitem> +<listitem> + <para>Key release causes a key release event for the key specified by +<emphasis> +newKey</emphasis> +; the state field for this event consists of the effective keyboard modifiers +at the time of the release, changed as described above. + </para> +</listitem> +<listitem> + <para>The <emphasis> +SA_RedirectKey</emphasis> + action normally redirects to another key on the same device as the key or +button which caused the event, unless that device does not belong to the input +extension KEYCLASS, in which case this action causes an event on the core +keyboard device. + </para> +</listitem> +</itemizedlist> +</entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis> +SA_DeviceBtn +</emphasis> + </para> + <para> + count: CARD8 + </para> + <para> + button: BUTTON + </para> + <para> + device: CARD8 + </para> + </entry> +<entry> +<itemizedlist> +<listitem> + <para>The <emphasis> +device</emphasis> + field specifies the ID of an extension device; the <emphasis> +button</emphasis> + field specifies the index of a button on that device. 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 <emphasis> +SA_NoAction</emphasis> +. + </para> +</listitem> +<listitem> + <para>Otherwise, key press causes one or more input extension device button +events instead of the usual key press event. If <emphasis> +count</emphasis> + is <emphasis> +0</emphasis> +, key press generates a single <emphasis> +DeviceButtonPress</emphasis> + event; if <emphasis> +count</emphasis> + is greater than <emphasis> +0</emphasis> +, key press generates <emphasis> +count</emphasis> + pairs of <emphasis> +DeviceButtonPress</emphasis> + and <emphasis> +DeviceButtonRelease</emphasis> + events. + </para> +</listitem> +<listitem> + <para>If <emphasis> +count</emphasis> + is <emphasis> +0</emphasis> +, key release generates an input extension <emphasis> +DeviceButtonRelease</emphasis> + which matches the event generated by the corresponding key press; if count is +non-zero, key release does not cause a <emphasis> +DeviceButtonRelease</emphasis> + event. Key release never causes a key release event. + </para> +</listitem> +</itemizedlist> +</entry> + </row> + <row rowsep='0'> + <entry> + <para> + <emphasis> +SA_LockDeviceBtn +</emphasis> + </para> + <para> + button: BUTTON + </para> + <para> + device: CARD8 + </para> + <para> + noLock: BOOL + </para> + <para> + noUnlock: BOOL + </para> + </entry> +<entry> +<itemizedlist> +<listitem> + <para>The <emphasis> +device</emphasis> + field specifies the ID of an extension device; the <emphasis> +button</emphasis> + field specifies the index of a button on that device. If the device or button +specified by this action are illegal, it behaves like <emphasis> +SA_NoAction</emphasis> +. + </para> +</listitem> +<listitem> + <para>Otherwise, if the specified button is not locked and if <emphasis> +noLock</emphasis> + is <emphasis> +False</emphasis> +, key press causes an input extension <emphasis> +DeviceButtonPress</emphasis> + event instead of a key press event and locks the button. If the button is +already locked or if <emphasis> +noLock</emphasis> + is <emphasis> +True</emphasis> +, key press is ignored and has no effect. + </para> +</listitem> +<listitem> + <para>If the corresponding key press was ignored, and if <emphasis> +noUnlock</emphasis> + is <emphasis> +False</emphasis> +, key release generates an input extension <emphasis> +DeviceButtonRelease</emphasis> + event instead of a core protocol or input extension key release event and +unlocks the specified button. If the corresponding key press locked a button, +key release is ignored and has no effect. + </para> +</listitem> +</itemizedlist> +</entry> + </row> + <row rowsep='0'> + <entry> +<para> + <emphasis> +SA_DeviceValuator +</emphasis> +</para> +<para> + <emphasis> +device</emphasis> +: CARD8 +</para> +<para> + <emphasis> +val1What</emphasis> +: SA_DVOP +</para> +<para> + <emphasis> +val1</emphasis> +: CARD8 +</para> +<para> + <emphasis> +val1Value</emphasis> +: INT8 +</para> +<para> + <emphasis> +val1Scale</emphasis> +: 0...7 +</para> +<para> + <emphasis> +val2What</emphasis> +: BOOL +</para> +<para> + <emphasis> +val2</emphasis> +: CARD8 +</para> +<para> + <emphasis> +val2Value</emphasis> +: INT8 +</para> +<para> + <emphasis> +val2Scale</emphasis> +: 0...7 +</para> +</entry> +<entry> +<itemizedlist> +<listitem> + <para>The <emphasis> +device</emphasis> + field specifies the ID of an extension device; <emphasis> +val1</emphasis> + and <emphasis> +val2</emphasis> + specify valuators on that device. If <emphasis> +device</emphasis> + is illegal or if neither <emphasis> +val1</emphasis> + nor <emphasis> +val2</emphasis> + specifies a legal valuator, this action behaves like <emphasis> +SA_NoAction</emphasis> +. + </para> +</listitem> +<listitem> + <para>If <emphasis> +valn</emphasis> + specifies a legal valuator and <emphasis> +valnWhat</emphasis> + is not <emphasis> +SA_IgnoreVal</emphasis> +, the specified value is adjusted as specified by <emphasis> +valnWhat</emphasis> +: + </para> +</listitem> +<listitem> + <para>If <emphasis> +valnWhat</emphasis> + is <emphasis> +SA_SetValMin</emphasis> +, <emphasis> +valn</emphasis> + is set to its minimum legal value. + </para> +</listitem> +<listitem> + <para>If <emphasis> +valnWhat</emphasis> + is <emphasis> +SA_SetValCenter</emphasis> +, <emphasis> +valn</emphasis> + is centered (to (max-min)/2). + </para> +</listitem> +<listitem> + <para>If <emphasis> +valnWhat</emphasis> + is <emphasis> +SA_SetValMax</emphasis> +, <emphasis> +valn</emphasis> + is set to its maximum legal value. + </para> +</listitem> +<listitem> + <para>if <emphasis> +valnWhat</emphasis> + is <emphasis> +SA_SetValRelative</emphasis> +, <mediaobject> + <imageobject> <imagedata fileref="XKBproto-4.gif"/> + </imageobject> + </mediaobject> + + is added to <emphasis> +valn</emphasis> +. + </para> +</listitem> +<listitem> + <para>if <emphasis> +valnWhat</emphasis> + is <emphasis> +SA_SetValAbsolute</emphasis> +, <emphasis> +valn</emphasis> + is set to <mediaobject> + <imageobject> <imagedata fileref="XKBproto-5.gif"/> + </imageobject> + </mediaobject> + +. + </para> +</listitem> +<listitem> + <para>Illegal values for <emphasis> +SA_SetValRelative</emphasis> + or <emphasis> +SA_SetValAbsolute</emphasis> + are clamped into range. + </para> +</listitem> +</itemizedlist> +</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +If <emphasis> +StickyKeys</emphasis> + are enabled, all <emphasis> +SA_SetMods</emphasis> + and <emphasis> +SA_SetGroup</emphasis> + actions act like <emphasis> +SA_LatchMods</emphasis> + and <emphasis> +SA_LatchGroup</emphasis> + respectively. If the <emphasis> +LatchToLock</emphasis> + AccessX option is set, either action behaves as if both the <emphasis> +SA_ClearLocks</emphasis> + and <emphasis> +SA_LatchToLock</emphasis> + flags are set. +</para> + + +<para> +Actions which cause an event from another key or from a button on another +device immediately generate the specified event. These actions do not consider +the behavior or actions (if any) that are bound to the key or button to which +the event is redirected. +</para> + + +<para> +Core events generated by server actions contain the keyboard state that was in +effect at the time the key event occurred; the reported state does not reflect +any changes in state that occur as a result of the actions bound to the key +event that caused them. +</para> + + +<para> +Events sent to clients that have not issued an <emphasis> +XkbUseExtension</emphasis> + request contain a compatibility state in place of the actual XKB keyboard +state. See <ulink url="XKBproto.htm#50332257_39705">See Effects of XKB on Core +Protocol Events</ulink> for a description of this compatibility mapping. +</para> + + +</sect1> +<sect1 id='delivering_a_key_or_button_event_to_a_client'> +<title>Delivering a Key or Button Event to a Client</title> + +<para> +The window and client that receive core protocol and input extension key or +button events are determined using the focus policy, window hierarchy and +passive grabs as specified by the core protocol and the input extension, with +the following changes: +</para> + +<itemizedlist> +<listitem> + <para>A passive grab triggers if the modifier state specified in the grab +matches the grab compatibility state (described in <ulink +url="XKBproto.htm#50332257_32581">See Compatibility Components of Keyboard +State</ulink>). Clients can choose to use the XKB grab state instead by setting +the <emphasis> +GrabsUseXKBState</emphasis> + per-client flag. This flag affects all passive grabs that are requested by the +client which sets it but does not affect passive grabs that are set by any +other client. + </para> +</listitem> +<listitem> + <para>The state field of events which trigger a passive grab reports the XKB +or compatibility grab state in effect at the time the grab is triggered; the +state field of the corresponding release event reports the corresponding grab +state in effect when the key or button is released. + </para> +</listitem> +<listitem> + <para>If the <emphasis> +LookupStateWhenGrabbed</emphasis> + per-client flag is set, all key or button events that occur while a keyboard +or pointer grab is active contain the XKB or compatibility lookup state, +depending on the value of the <emphasis> +GrabsUseXKBState</emphasis> + per-client flag. If <emphasis> +LookupStateWhenGrabbed</emphasis> + is not set, they include the XKB or compatibility grab state, instead. + </para> +</listitem> +<listitem> + <para>Otherwise, the state field of events that do not trigger a passive grab +report is derived from the XKB effective modifiers and group, as described in +<ulink url="XKBproto.htm#50332257_90933">See Computing A State Field from an +XKB State</ulink>. + </para> +</listitem> +<listitem> + <para>If a key release event is the result of an autorepeating key that is +being held down, and the client to which the event is reported has requested +detectable autorepeat (see <ulink url="XKBproto.htm#50332257_79074">See +Detectable Autorepeat</ulink>), the event is not delivered to the client. + </para> +</listitem> +</itemizedlist> + +<para> +The following section explains the intent of the XKB interactions with core +protocol grabs and the reason that the per-client flags are needed. +</para> + + +<sect2 id='xkb_interactions_with_core_protocol_grabs'> +<title>XKB Interactions With Core Protocol Grabs</title> + +<para> +XKB provides the separate lookup and grab states to help work around some +difficulties with the way the core protocol specifies passive grabs. +Unfortunately, many clients work around those problems differently, and the way +that XKB handles grabs and reports keyboard state can sometimes interact with +those client workarounds in unexpected and unpleasant ways. +</para> + + +<para> +To provide more reasonable behavior for clients that are aware of XKB without +causing problems for clients that are unaware of XKB, this extension provides +two per-client flags that specify the way that XKB and the core protocol should +interact. +</para> + +<itemizedlist> +<listitem> + <para>The largest problems arise from the fact that an XKB state field +encodes an explicit keyboard group in bits 13-14 (as described in <ulink +url="XKBproto.htm#50332257_90933">See Computing A State Field from an XKB +State</ulink>), while pre-XKB clients use one of the eight keyboard modifiers +to select an alternate keyboard group. To make existing clients behave +reasonably, XKB normally uses the compatibility grab state instead of the XKB +grab state to determine whether or not a passive grab is triggered. XKB-aware +clients can set the <emphasis> +GrabsUseXKBState</emphasis> + per-client flag to indicate that they are specifying passive grabs using an +XKB state. + </para> +</listitem> +<listitem> + <para>Some toolkits start an active grab when a passive grab is triggered, in +order to have more control over the conditions under which the grab is +terminated. Unfortunately, the fact that XKB reports a different state in +events that trigger or terminate grabs means that this grab simulation can fail +to terminate the grab under some conditions. To work around this problem, XKB +normally reports the grab state in all events whenever a grab is active. +Clients which do not use active grabs like this can set the <emphasis> +LookupStateWhenGrabbed</emphasis> + per-client flag in order to receive the same state component whether or not a +grab is active. + </para> +<para> +The <emphasis> +GrabsUseXKBState</emphasis> + per-client flag also applies to the state of events sent while a grab is +active. If it is set, events during a grab contain the XKB lookup or grab +state; by default, events during a grab contain the compatibility lookup or +grab state.</para> +</listitem> +</itemizedlist> + +<para> +The state used to trigger a passive grab is controlled by the setting of the +<emphasis> +GrabsUseXKBState</emphasis> + per-client flag at the time the grab is registered. Changing this flag does +not affect existing passive grabs. +</para> +</sect2> +</sect1> +</chapter> diff --git a/specs/ch07.xml b/specs/ch07.xml new file mode 100644 index 0000000..8ba8f61 --- /dev/null +++ b/specs/ch07.xml @@ -0,0 +1,685 @@ +<chapter id='key_event_processing_in_the_client'> +<title>Key Event Processing in the Client</title> + +<para> +The XKB <emphasis> +client map</emphasis> + for a keyboard is the collection of information a client needs to interpret +key events that come from that keyboard. It contains a global list of <emphasis> +key types</emphasis> +, described in <ulink url="XKBproto.htm#50332257_45629">See Key Types</ulink>, +and an array of <emphasis> +key symbol map</emphasis> +s, each of which describes the symbols bound to one particular key and the +rules to be used to interpret those symbols. +</para> + +<sect1 id='notation_and_terminology'> +<title>Notation and Terminology</title> + +<para> +XKB associates a two-dimensional array of symbols with each key. Symbols are +addressed by keyboard group (see <ulink url="XKBproto.htm#50332257_13933">See +Keyboard State</ulink>) and shift level, where level is defined as in the +ISO9995 standard: +</para> + +<variablelist> + <varlistentry> + <term>Level</term> + <listitem> + <para> +One of several states (normally 2 or 3) which govern which graphic +character is produced when a graphic key is actuated. In certain cases the +level may also affect function keys. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +Note that shift level is derived from the modifier state, but not necessarily +in the same way for all keys. For example, the <emphasis> +Shift</emphasis> + modifier selects shift level 2 on most keys, but for keypad keys the modifier +bound to <emphasis> +Num_Lock</emphasis> + (i.e. the <emphasis> +NumLock</emphasis> + virtual modifier) also selects shift level 2.gray symbols on a key +</para> + +<para> +We use the notation G<emphasis> +n</emphasis> +L<emphasis> +n</emphasis> + to specify the position of a symbol on a key or in memory: +</para> + +<mediaobject> + <imageobject> <imagedata fileref="XKBproto-6.gif"/> + </imageobject> + </mediaobject> + + +<para> +The gray characters indicate symbols that are implied or expected but are not +actually engraved on the key. +</para> + +<note><para>Unfortunately, the "natural" orientation of symbols on a key and +the natural orientation in memory are reversed from one another, so keyboard +group refers to a column on the key and a row in memory. There’s no real help +for it, but we try to minimize confusion by using "group" and "level" (or +"shift level") to refer to symbols regardless of context.</para></note> + +</sect1> +<sect1 id='determining_the_keysym_associated_with_a_key_event'> +<title>Determining the KeySym Associated with a Key Event</title> + +<para> +To look up the symbol associated with an XKB key event, we need to know the +group and shift level that correspond to the event. +</para> + + +<para> +Group is reported in bits 13-14 of the state field of the key event, as +described in <ulink url="XKBproto.htm#50332257_90933">See Computing A State +Field from an XKB State</ulink>. The keyboard group reported in the event might +be out-of-range for any particular key because the number of groups can vary +from key to key. The XKB description of each key contains a <emphasis> +group info</emphasis> + field which is interpreted identically to the global groups wrap control (see +<ulink url="XKBproto.htm#50332257_67222">See Computing Effective Modifier and +Group</ulink>) and which specifies the interpretation of groups that are +out-of-range for that key. +</para> + + +<para> +Once we have determined the group to be used for the event, we have to +determine the shift level. The description of a key includes a <emphasis> +key type</emphasis> + for each group of symbols bound to the key. Given the modifiers from the key +event, this key type yields a shift level and a set of "leftover" modifiers, as +described in <ulink url="XKBproto.htm#50332257_45629">See Key Types</ulink> +below. +</para> + + +<para> +Finally, we can use the effective group and the shift level returned by the +type of that group to look up a symbol in a two-dimensional array of symbols +associated with the key. +</para> + + +<sect2 id='key_types'> +<title>Key Types</title> + +<para> +Each entry of a key type’s <emphasis> +map</emphasis> + field specifies the shift level that corresponds to some XKB modifier +definition; any combination of modifiers that is not explicitly listed +somewhere in the map yields shift level one. Map entries which specify unbound +virtual modifiers (see <ulink url="XKBproto.htm#50332257_29579">See Inactive +Modifier Definitions</ulink>) are not considered; each entry contains an +automatically-updated <emphasis> +active</emphasis> + field which indicates whether or not it should be used. +</para> + + +<para> +Each key type includes a few fields that are derived from the contents of the +map and which report some commonly used values so they don’t have to be +constantly recalculated. The <emphasis> +numLevels</emphasis> + field contains the highest shift level reported by any of its map entries; XKB +uses <emphasis> +numLevels</emphasis> + to insure that the array of symbols bound to a key is large enough (the number +of levels reported by a key type is also referred to as its width). The +<emphasis> +modifiers</emphasis> + field reports all real modifiers considered by any of the map entries for the +type. Both <emphasis> +modifiers</emphasis> +<emphasis> + </emphasis> +and <emphasis> +numLevels</emphasis> + are updated automatically by XKB and neither can be changed explicitly. +</para> + + +<para> +Any modifiers specified in <emphasis> +modifiers</emphasis> + are normally <emphasis> +consumed</emphasis> + (see <ulink url="XKBproto.htm#50332257_25094">See Transforming the KeySym +Associated with a Key Event</ulink>), which means that they are not considered +during any of the later stages of event processing. For those rare occasions +that a modifier <emphasis> +should</emphasis> + be considered despite having been used to look up a symbol, key types include +an optional <emphasis> +preserve</emphasis> + field. If a <emphasis> +preserve</emphasis> + list is present, each entry corresponds to one of the key type’s map entries +and lists the modifiers that should <emphasis> +not</emphasis> + be consumed if the matching map entry is used to determine shift level. +</para> + + +<para> +For example, the following key type implements caps lock as defined by the core +protocol (using the second symbol bound to the key): +</para> + +<literallayout class='monospaced'> +type "ALPHABETIC" { + modifiers = Shift+Lock; + map[Shift]= Level2; + map[Lock]= Level2; + map[Shift+Lock]= Level2; +}; +</literallayout> + +<para> +The problem with this kind of definition is that we could assign completely +unrelated symbols to the two shift levels, and "Caps Lock" would choose the +second symbol. Another definition for alphabetic keys uses system routines to +capitalize the keysym: +</para> + +<literallayout class='monospaced'> +type "ALPHABETIC" { + modifiers= Shift; + map[Shift]= Level2; +}; +</literallayout> + +<para> +When caps lock is applied using this definition, we take the symbol from shift +level one and capitalize it using system-specific capitalization rules. If +shift and caps lock are both set, we take the symbol from shift level two and +try to capitalize it, which usually has no effect. +</para> + + +<para> +The following key type implements shift-cancels-caps lock behavior for +alphabetic keys: +</para> + +<literallayout class='monospaced'> +type "ALPHABETIC" { + modifiers = Shift+Lock; + map[Shift] = Level2; + preserve[Lock]= Lock; +}; +</literallayout> + +<para> +Consider the four possible states that can affect alphabetic keys: no +modifiers, shift alone, caps lock alone or shift and caps lock together. The +map contains no explicit entry for <emphasis> +None</emphasis> + (no modifiers), so if no modifiers are set, any group with this type returns +the first keysym. The map entry for <emphasis> +Shift</emphasis> + reports <emphasis> +Level2</emphasis> +, so any group with this type returns the second symbol when <emphasis> +Shift</emphasis> + is set. There is no map entry for <emphasis> +Lock</emphasis> + alone, but the type specifies that the <emphasis> +Lock</emphasis> + modifier should be preserved in this case, so <emphasis> +Lock</emphasis> + alone returns the first symbol in the group but first applies the +capitalization transformation, yielding the capital form of the symbol. In the +final case, there is no map entry for <emphasis> +Shift+Lock</emphasis> +, so it returns the first symbol in the group; there is no preserve entry, so +the <emphasis> +Lock</emphasis> + modifier is consumed and the symbol is not capitalized. +</para> + + +</sect2> +<sect2 id='key_symbol_map'> +<title>Key Symbol Map</title> + +<para> +The <emphasis> +key symbol map</emphasis> + for a key contains all of the information that a client needs to process +events generated by that key. Each key symbol mapping reports: +</para> + +<itemizedlist> +<listitem> + <para>The number of groups of symbols bound to the key (<emphasis> +numGroups</emphasis> +). + </para> +</listitem> +<listitem> + <para>The treatment of out-of-range groups (<emphasis> +groupInfo</emphasis> +). + </para> +</listitem> +<listitem> + <para>The index of the key type to for each <emphasis> +possible</emphasis> + group (<emphasis> +kt_index[MaxKbdGroups]</emphasis> +). + </para> +</listitem> +<listitem> + <para>The width of the widest type associated with the key (<emphasis> +groupsWidth</emphasis> +). + </para> +</listitem> +<listitem> + <para>The two-dimensional (numGroups <emphasis> +×</emphasis> + groupsWidth) array of symbols bound to the key. + </para> +</listitem> +</itemizedlist> + +<para> +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 <emphasis> +NoSymbol</emphasis> +. The array of key types is of fixed width and is large enough to hold key +types for the maximum legal number of groups (<emphasis> +MaxKbdGroups</emphasis> +, currently four); if a key has fewer than <emphasis> +MaxKbdGroups</emphasis> + groups, the extra key types are reported but ignored. The <emphasis> +groupsWidth</emphasis> + field cannot be explicitly changed; it is updated automatically whenever the +symbols or set of types bound to a key are changed. +</para> + + +<para> +If, when looking up a symbol, the effective keyboard group is out-of-range for +the key, the <emphasis> +groupInfo</emphasis> + field of the key symbol map specifies the rules for determining the +corresponding legal group as follows: +</para> + +<itemizedlist> +<listitem> + <para>If the <emphasis> +RedirectIntoRange</emphasis> + flag is set, the two least significant bits of <emphasis> +groupInfo</emphasis> + specify the index of a group to which all illegal groups correspond. If the +specified group is also out of range, all illegal groups map to <emphasis> +Group1</emphasis> +. + </para> +</listitem> +<listitem> + <para>If <emphasis> +ClampIntoRange</emphasis> + flag is set, out-of-range groups correspond to the nearest legal group. +Effective groups larger than the highest supported group are mapped to the +highest supported group; effective groups less than <emphasis> +Group1</emphasis> + are mapped to <emphasis> +Group1</emphasis> +. For example, a key with two groups of symbols uses <emphasis> +Group2</emphasis> + type and symbols if the global effective group is either <emphasis> +Group3</emphasis> + or <emphasis> +Group4</emphasis> +. + </para> +</listitem> +<listitem> + <para>If neither flag is set, group is wrapped into range using integer +modulus. For example, a key with two groups of symbols for which groups wrap +uses <emphasis> +Group1</emphasis> + symbols if the global effective group is <emphasis> +Group3</emphasis> + or <emphasis> +Group2</emphasis> + symbols if the global effective group is <emphasis> +Group4</emphasis> +. + </para> +</listitem> +</itemizedlist> + +<para> +The client map contains an array of key symbol mappings, with one entry for +each key between the minimum and maximum legal keycodes, inclusive. All +keycodes which fall in that range have key symbol mappings, whether or not any +key actually yields that code. +</para> + + +</sect2> +</sect1> +<sect1 id='transforming_the_keysym_associated_with_a_key_event'> +<title>Transforming the KeySym Associated with a Key Event</title> + +<para> +Any modifiers that were not used to look up the keysym, or which were +explicitly preserved, might indicate further transformations to be performed on +the keysym or the character string that is derived from it. For example, If the +<emphasis> +Lock</emphasis> + modifier is set, the symbol and corresponding string should be capitalized +according to the locale-sensitive capitalization rules specified by the system. +If the <emphasis> +Control</emphasis> + modifier is set, the keysym is not affected, but the corresponding character +should be converted to a control character as described in <ulink +url="dflttrns.htm#17949"></ulink>. +</para> + + +<para> +This extension specifies the transformations to be applied when the <emphasis> +Control</emphasis> + or <emphasis> +Lock</emphasis> + modifiers are active but were not used to determine the keysym to be used: +</para> + +<informaltable frame='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Modifier</entry> + <entry>Transformation</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis> +Control</emphasis> + </entry> + <entry>Report the control character associated with the symbol. This +extension defines the control characters associated with the ASCII alphabetic +characters (both upper and lower case) and for a small set of punctuation +characters (see <ulink url="dflttrns.htm#17949"></ulink>). Applications are +free to associate control characters with any symbols that are not specified by +this extension.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +Lock</emphasis> + </entry> + <entry>Capitalize the symbol either according to capitalization rules +appropriate to the application locale or using the capitalization rules defined +by this extension (see <ulink url="dflttrns.htm#17949"></ulink>).</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +Interpretation of other modifiers is application dependent. +</para> + +<note><para>This definition of capitalization is fundamentally different from +the core protocol’s, which uses the lock modifier to select from the symbols +bound to the key. Consider key 9 in the example keyboard on <ulink +url="XKBproto.htm#50332257_ClientMapExample">See Consider a simple, if +unlikely, keyboard with the following keys (gray characters indicate symbols +that are implied or expected but are not actually engraved on the +key):</ulink>; the core protocol provides no way to generate the capital form +of either symbol bound to this key. XKB specifies that we first look up the +symbol and then capitalize, so XKB yields the capital form of the two symbols +when caps lock is active. </para></note> + +<para> +XKB specifies the behavior of <emphasis> +Lock</emphasis> + and <emphasis> +Control</emphasis> +, but interpretation of other modifiers is left to the application. +</para> + + +</sect1> +<sect1 id='client_map_example'> +<title>Client Map Example</title> + +<para> +Consider a simple, if unlikely, keyboard with the following keys (gray +characters indicate symbols that are implied or expected but are not actually +engraved on the key): +</para> + +<mediaobject> + <imageobject> <imagedata fileref="XKBproto-7.gif"/> + </imageobject> + </mediaobject> + + +<para> +The core protocol represents this keyboard as a simple array with one row per +key and four columns (the widest key, key 10, determines the width of the +entire array). +</para> + +<informaltable frame='none'> +<tgroup cols='5'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Key</entry> + <entry>G1L1</entry> + <entry>G1L2</entry> + <entry>G2L1</entry> + <entry>G2L2</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>8</entry> + <entry>Q</entry> + <entry>NoSymbol</entry> + <entry>at</entry> + <entry>NoSymbol</entry> + </row> + <row rowsep='0'> + <entry>9</entry> + <entry>odiaeresis</entry> + <entry>egrave</entry> + <entry>NoSymbol</entry> + <entry>NoSymbol</entry> + </row> + <row rowsep='0'> + <entry>10</entry> + <entry>A</entry> + <entry>NoSymbol</entry> + <entry>Æ</entry> + <entry>NoSymbol</entry> + </row> + <row rowsep='0'> + <entry>11</entry> + <entry>ssharp</entry> + <entry>question</entry> + <entry>backslash</entry> + <entry>questiondown</entry> + </row> + <row rowsep='0'> + <entry>12</entry> + <entry>KP_End</entry> + <entry>KP_1</entry> + <entry>NoSymbol</entry> + <entry>NoSymbol</entry> + </row> + <row rowsep='0'> + <entry>13</entry> + <entry>Num_Lock</entry> + <entry>NoSymbol</entry> + <entry>NoSymbol</entry> + <entry>NoSymbol</entry> + </row> + <row rowsep='0'> + <entry>14</entry> + <entry>NoSymbol</entry> + <entry>NoSymbol</entry> + <entry>NoSymbol</entry> + <entry>NoSymbol</entry> + </row> + <row rowsep='0'> + <entry>15</entry> + <entry>Return</entry> + <entry>NoSymbol</entry> + <entry>NoSymbol</entry> + <entry>NoSymbol</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +The row to be used for a given key event is determined by keycode; the column +to be used is determined by the symbols bound to the key, the state of the +<emphasis> +Shift</emphasis> + and <emphasis> +Lock</emphasis> + Modifiers and the state of the modifiers bound to the <emphasis> +Num_Lock</emphasis> + and <emphasis> +Mode_switch</emphasis> + keys as specified by the core protocol. +</para> + + +<para> +The XKB description of this keyboard consists of six key symbol maps, each of +which specifies the types and symbols associated with each keyboard group for +one key: +</para> + +<informaltable frame='none'> +<tgroup cols='4'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Key</entry> + <entry>Group: Type</entry> + <entry>L1</entry> + <entry>L2</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>8</entry> + <entry>G1: ALPHABETIC</entry> + <entry>q</entry> + <entry>Q</entry> + </row> + <row rowsep='0'> + <entry>G2: ONE_LEVEL</entry> + <entry>@</entry> + <entry>NoSymbol</entry> + </row> + <row rowsep='0'> + <entry>9</entry> + <entry>G1: TWO_LEVEL</entry> + <entry>odiaeresis</entry> + <entry>egrave</entry> + </row> + <row rowsep='0'> + <entry>10</entry> + <entry>G1: ALPHABETIC</entry> + <entry>a</entry> + <entry>A</entry> + </row> + <row rowsep='0'> + <entry>G2: ALPHABETIC</entry> + <entry>ae</entry> + <entry>AE</entry> + </row> + <row rowsep='0'> + <entry>11</entry> + <entry>G1: TWO_LEVEL</entry> + <entry>ssharp</entry> + <entry>question</entry> + </row> + <row rowsep='0'> + <entry>G2: ONE_LEVEL</entry> + <entry>backslash</entry> + <entry>questiondown</entry> + </row> + <row rowsep='0'> + <entry>12</entry> + <entry>G1: KEYPAD</entry> + <entry>KP_End</entry> + <entry>KP_1</entry> + </row> + <row rowsep='0'> + <entry>13</entry> + <entry>G1: ONE_LEVEL</entry> + <entry>Num_Lock</entry> + <entry> </entry> + </row> + <row rowsep='0'> + <entry>14</entry> + <entry>No Groups</entry> + <entry> </entry> + <entry> </entry> + </row> + <row rowsep='0'> + <entry>15</entry> + <entry>G1: ONE_LEVEL</entry> + <entry>Return</entry> + <entry> </entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +The keycode reported in a key event determines the row to be used for that +event; the effective keyboard group determines the list of symbols and key type +to be used. The key type determines which symbol is chosen from the list. +</para> + + +<para> +<ulink url="XKBproto.htm#50332257_24122">See Determining the KeySym Associated +with a Key Event</ulink> details the procedure to map from a key event to a +symbol and/or a string. +</para> +</sect1> +</chapter> diff --git a/specs/ch08.xml b/specs/ch08.xml new file mode 100644 index 0000000..feaa995 --- /dev/null +++ b/specs/ch08.xml @@ -0,0 +1,156 @@ +<chapter id='symbolic_names'> +<title>Symbolic Names</title> + +<para> +The core protocol does not provide any information to clients other than that +actually used to interpret events. This makes it difficult to write a client +which 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 have to examine keysyms and +modifier mappings to determine the effects of most modifiers (the <emphasis> +Shift</emphasis> +, <emphasis> +Lock</emphasis> + and <emphasis> +Control</emphasis> + modifiers are defined by the core protocol but no semantics are implied for +any other modifiers). +</para> + + +<para> +This extension provides such applications with symbolic names for most +components of the keyboard extension and a description of the physical layout +of the keyboard. +</para> + + +<para> +The <emphasis> +keycodes</emphasis> + name describes the range and meaning of the keycodes returned by the keyboard +in question; the <emphasis> +keyboard</emphasis> + <emphasis> +geometry </emphasis> +name describes 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 <emphasis> +F1</emphasis> + regardless of physical position. Thus, all PC-compatible keyboards might share +a keycodes name but different geometry names. +</para> + +<note><para>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 that the keys that all keys +have the same semantics when present. For example, 101 and 102 key PC keyboards +might use the same name. Applications can use the keyboard geometry to +determine which subset of the named keyboard type is in use.</para></note> + +<para> +The <emphasis> +symbols</emphasis> + name identifies the symbols 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 <emphasis> +physical symbols</emphasis> + name describes the symbols actually engraved on the keyboard, which might be +different than the symbols currently being used. +</para> + + +<para> +The <emphasis> +types</emphasis> + name provides some information about the set of key types that can be +associated with the keyboard keys. The <emphasis> +compat</emphasis> + name provides some information about the rules used to bind actions to keys +changed using core protocol requests. +</para> + + +<para> +The <emphasis> +compat</emphasis> +, <emphasis> +types</emphasis> +, <emphasis> +keycodes</emphasis> +, <emphasis> +symbols</emphasis> + and <emphasis> +geometry</emphasis> + names typically correspond to the keyboard components from which the current +keyboard description was assembled. These components are stored individually in +the server’s database of keyboard components, described in <ulink +url="XKBproto.htm#50332257_46669">See The Server Database of Keyboard +Components</ulink>, and can be combined to assemble a complete keyboard +description. +</para> + + +<para> +Each key has a four-byte symbolic name. The key name links keys with similar +functions or in similar positions on keyboards that report different scan +codes. <emphasis> +Key aliases</emphasis> + allow the keyboard layout designer to assign multiple names to a single key, +to make it easier to refer to keys using either their position <emphasis> +or</emphasis> + their "function." +</para> + + +<para> +For example, consider the common keyboard customizations: +</para> + +<itemizedlist> +<listitem> + <para>Set the "key to the left of the letter a" to be a control key. + </para> +</listitem> +<listitem> + <para>Change the "caps lock" key, wherever it might be, to a control key. + </para> +</listitem> +</itemizedlist> + +<para> +If we specify key names by position, the first customization is simple but the +second is impossible; if we specify key names by function, the second +customization is simple but the first is impossible. Using key aliases, we can +specify both function and position for "troublesome" keys, and both +customizations are straightforward. +</para> + + +<para> +Key aliases can be specified both in the symbolic names component and in the +keyboard geometry (see <ulink url="XKBproto.htm#50332257_23341">See Keyboard +Geometry</ulink>). 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, applications should consider the definitions from the +geometry before considering the definitions from the symbolic names section. +</para> + + +<para> +XKB provides symbolic names for each of the four keyboard groups, sixteen +virtual modifiers, thirty-two keyboard indicators, and up to <emphasis> +MaxRadioGroups</emphasis> + (32) radio groups. +</para> + + +<para> +XKB allows keyboard layout designers or editors to assign names to each key +type and to each of the levels in a key type. For example, the second position +on an alphabetic key might be called the "Caps" level while the second position +on a numeric keypad key might be called the "Num Lock" level. +</para> +</chapter> diff --git a/specs/ch09.xml b/specs/ch09.xml new file mode 100644 index 0000000..b5cae3f --- /dev/null +++ b/specs/ch09.xml @@ -0,0 +1,604 @@ +<chapter id='keyboard_indicators'> +<title>Keyboard Indicators</title> + +<para> +Although the core X protocol supports thirty-two LEDs on a keyboard, it does +not provide any way to link the state of the LEDs and the logical state of the +keyboard. For example, most keyboards have a "Caps Lock" LED, but X does not +provide any standard way to make the LED automatically follow the logical state +of the modifier bound to the <emphasis> +Caps Lock</emphasis> + key. +</para> + + +<para> +The core protocol also gives no way to determine which bits in the <emphasis> +led_mask</emphasis> + field of the keyboard state map to the particular LEDs on the keyboard. For +example, X does not provide a method for a client to determine which bit to set +in the <emphasis> +led_mask</emphasis> + to turn on the "Scroll Lock" LED, or even if the keyboard has a "Scroll Lock" +LED. +</para> + + +<para> +Most X servers implement some kind of automatic behavior for one or more of the +keyboard LEDs, but the details of that automatic behavior are +implementation-specific and can be difficult or impossible to control. +</para> + + +<para> +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. +</para> + +<sect1 id='global_information_about_indicators'> +<title>Global Information About Indicators</title> + +<para> +XKB provides only two pieces of information about the indicators as a group. +</para> + + +<para> +The <emphasis> +physical indicators</emphasis> + mask reports which of the 32 logical keyboard indicators supported by the core +protocol and XKB corresponds to some actual indicator on the keyboard itself. +Because the physical indicators mask describes a physical characteristic of the +keyboard, it cannot be directly changed under program control. It is possible, +however, for the set of physical indicators to be change if a new keyboard is +attached or if a completely new keyboard description is loaded by the <emphasis> +XkbGetKeyboardByName</emphasis> + request (see <ulink url="XKBproto.htm#50332257_13490">See Using the Server’s +Database of Keyboard Components</ulink>). +</para> + + +<para> +The <emphasis> +indicator state</emphasis> + mask reports the current state of the 32 logical keyboard indicators. This +field and the core protocol indicator state (as reported by the <emphasis> +led-mask</emphasis> + field of the core protocol <emphasis> +GetKeyboardControl</emphasis> + request) are always identical. +</para> + + +</sect1> +<sect1 id='per_indicator_information'> +<title>Per-Indicator Information</title> + +<para> +Each of the thirty-two keyboard indicators has a symbolic name, of type ATOM. +The <emphasis> +XkbGetNames</emphasis> + request reports the symbolic names for all keyboard components, including the +indicators. Use the <emphasis> +XkbSetNames</emphasis> + request to change symbolic names. Both requests are described in <ulink +url="XKBproto.htm#50332257_14207">See Querying and Changing Symbolic +Names</ulink>. +</para> + + +<sect2 id='indicator_maps'> +<title>Indicator Maps</title> + +<para> +XKB also provides an <emphasis> +indicator map</emphasis> + for each of the thirty-two keyboard indicators; an indicator map specifies: +</para> + +<itemizedlist> +<listitem> + <para>The conditions under which the keyboard modifier state affects the +indicator. + </para> +</listitem> +<listitem> + <para>The conditions under which the keyboard group state affects the +indicator. + </para> +</listitem> +<listitem> + <para>The conditions under which the state of the boolean controls affects +the indicator. + </para> +</listitem> +<listitem> + <para>The effect (if any) of attempts to explicitly change the state of the +indicator using the core protocol <emphasis> +SetKeyboardControl</emphasis> + request. + </para> +</listitem> +</itemizedlist> + +<para> +If <emphasis> +IM_NoAutomatic</emphasis> + is set in the <emphasis> +flags</emphasis> + field of an indicator map, that indicator never changes in response to changes +in keyboard state or controls, regardless of the values for the other fields of +the indicator map. If <emphasis> +IM_NoAutomatic</emphasis> + is not set in <emphasis> +flags</emphasis> +, the other fields of the indicator map specify the automatic changes to the +indicator in response to changes in the keyboard state or controls. +</para> + + +<para> +The <emphasis> +which_groups</emphasis> + and the <emphasis> +groups</emphasis> + fields of an indicator map determine how the keyboard group state affects the +corresponding indicator. The <emphasis> +which_groups</emphasis> + field controls the interpretation of <emphasis> +groups</emphasis> + and may contain any one of the following values: +</para> + +<informaltable frame='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Value</entry> + <entry>Interpretation of the Groups Field</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis> +IM_UseNone</emphasis> +</entry> + <entry>The <emphasis> +groups</emphasis> + field and the current keyboard group state are ignored.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +IM_UseBase</emphasis> +</entry> + <entry>If <emphasis> +groups</emphasis> + is non-zero, the indicator is lit whenever the base keyboard group is +non-zero. If <emphasis> +groups</emphasis> + is zero, the indicator is lit whenever the base keyboard group is zero.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +IM_UseLatched</emphasis> +</entry> + <entry>If <emphasis> +groups</emphasis> + is non-zero, the indicator is lit whenever the latched keyboard group is +non-zero. If <emphasis> +groups</emphasis> + is zero, the indicator is lit whenever the latched keyboard group is +zero.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +IM_UseLocked</emphasis> +</entry> + <entry>The <emphasis> +groups</emphasis> + 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 <emphasis> +groups</emphasis> +.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +IM_UseEffective</emphasis> +</entry> + <entry>The <emphasis> +groups</emphasis> + 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 <emphasis> +groups</emphasis> +.</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +The <emphasis> +which_mods</emphasis> + and <emphasis> +mods</emphasis> + fields of an indicator map determine how the state of the keyboard modifiers +affect the corresponding indicator. The <emphasis> +mods</emphasis> + field is an XKB modifier definition, as described in <ulink +url="XKBproto.htm#50332257_11005">See Modifier Definitions</ulink>, which can +specify both real and virtual modifiers. The mods field takes effect even if +some or all of the virtual indicators specified in <emphasis> +mods</emphasis> + are unbound. +</para> + + +<para> +The <emphasis> +which_mods</emphasis> + field can specify one or more components of the XKB keyboard state. The +corresponding indicator is lit whenever any of the real modifiers specified in +the <emphasis> +mask</emphasis> + field of the <emphasis> +mods</emphasis> + modifier definition are also set in any of the current keyboard state +components specified by the <emphasis> +which_mods</emphasis> +. The <emphasis> +which_mods</emphasis> + field may have any combination of the following values: +</para> + +<informaltable frame='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Value</entry> + <entry>Keyboard State Component To Be Considered</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis> +IM_UseBase</emphasis> +</entry> + <entry>Base modifier state</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +IM_UseLatched</emphasis> +</entry> + <entry>Latched modifier state</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +IM_UseLocked</emphasis> +</entry> + <entry>Locked modifier state</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +IM_UseEffective</emphasis> +</entry> + <entry>Effective modifier state</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +IM_UseCompat</emphasis> +</entry> + <entry>Modifier compatibility state</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +The <emphasis> +controls</emphasis> + field specifies a subset of the boolean keyboard controls (see <ulink +url="XKBproto.htm#50332257_12486">See "Boolean" Controls and The +EnabledControls Control</ulink>). The indicator is lit whenever any of the +boolean controls specified in <emphasis> +controls</emphasis> + are enabled. +</para> + + +<para> +An indicator is lit whenever any of the conditions specified by its indicator +map are met, unless overridden by the <emphasis> +IM_NoAutomatic</emphasis> + flag (described above) or an explicit indicator change (described below). +</para> + + +<sect3 id='effects_of_explicit_changes_on_indicators'> +<title>Effects of Explicit Changes on Indicators</title> + +<para> +If the <emphasis> +IM_NoExplicit</emphasis> + flag is set in an indicator map, attempts to change the state of the indicator +are ignored. +</para> + + +<para> +If both <emphasis> +IM_NoExplicit</emphasis> + and <emphasis> +IM_NoAutomatic</emphasis> + are both absent from an indicator map, requests to change the state of the +indicator are honored but might be immediately superseded by automatic changes +to the indicator state which reflect changes to keyboard state or controls. +</para> + + +<para> +If the <emphasis> +IM_LEDDrivesKB</emphasis> + flag is set and the <emphasis> +IM_NoExplicit</emphasis> + flag is not, the keyboard state and controls are changed to reflect the other +fields of the indicator map, as described in the remainder of this section. +Attempts to explicitly change the value of an indicator for which <emphasis> +IM_LEDDrivesKB</emphasis> + is absent or for which <emphasis> +IM_NoExplicit</emphasis> + is present do not affect keyboard state or controls. +</para> + + +<para> +The effect on group state of changing an explicit indicator which drives the +keyboard is determined by the value of <emphasis> +which_groups</emphasis> + and <emphasis> +groups</emphasis> +, as follows: +</para> + +<informaltable frame='none'> +<tgroup cols='3'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry> which_groups</entry> + <entry>New State</entry> + <entry>Effect on Keyboard Group State</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis> +IM_UseNone</emphasis> +, or <emphasis> +IM_UseBase</emphasis> +</entry> + <entry>On or Off</entry> + <entry>No Effect</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +IM_UseLatched</emphasis> +</entry> + <entry>On</entry> + <entry>The <emphasis> +groups</emphasis> + field is treated as a group mask. The keyboard group latch is changed to the +lowest numbered group specified in <emphasis> +groups</emphasis> +; if <emphasis> +groups</emphasis> + is empty, the keyboard group latch is changed to zero.</entry> + </row> + <row rowsep='0'> + <entry>IM_UseLatched</entry> + <entry>Off</entry> + <entry>The <emphasis> +groups</emphasis> + 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 +<emphasis> +groups</emphasis> +; if <emphasis> +groups</emphasis> + is zero, the keyboard group latch is set to the index of the highest legal +keyboard group.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +IM_UseLocked</emphasis> +, or <emphasis> +IM_UseEffective</emphasis> +</entry> + <entry>On</entry> + <entry>If the <emphasis> +groups</emphasis> + mask is empty, group is not changed, otherwise the locked keyboard group is +changed to the lowest numbered group specified in <emphasis> +groups</emphasis> +.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +IM_UseLocked</emphasis> +, or <emphasis> +IM_UseEffective</emphasis> +</entry> + <entry>Off</entry> + <entry>Locked keyboard group is changed to the lowest numbered group that +is not specified in the <emphasis> +groups</emphasis> + mask, or to <emphasis> +Group1</emphasis> + if the <emphasis> +groups</emphasis> + mask contains all keyboard groups.</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +The effect on the keyboard modifiers of changing an explicit indicator which +drives the keyboard is determined by the values that are set in of <emphasis> +which_mods</emphasis> + and <emphasis> +mods</emphasis> +, as follows: +</para> + +<informaltable frame='none'> +<tgroup cols='3'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Set in which_mods</entry> + <entry>New State</entry> + <entry>Effect on Keyboard Modifiers</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis> +IM_UseBase</emphasis> +</entry> + <entry>On or Off</entry> + <entry>No Effect</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +IM_UseLatched</emphasis> +</entry> + <entry>On</entry> + <entry>Any modifiers specified in the <emphasis> +mask</emphasis> + field of <emphasis> +mods</emphasis> + are added to the latched modifiers.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +IM_UseLatched</emphasis> +</entry> + <entry>Off</entry> + <entry>Any modifiers specified in the <emphasis> +mask</emphasis> + field of <emphasis> +mods</emphasis> + are removed from the latched modifiers.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +IM_UseLocked</emphasis> +, <emphasis> +IM_UseCompat</emphasis> +, or <emphasis> +IM_UseEffective</emphasis> +</entry> + <entry>On</entry> + <entry>Any modifiers specified in the <emphasis> +mask</emphasis> + field of <emphasis> +mods</emphasis> + are added to the locked modifiers.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +IM_UseLocked</emphasis> +</entry> + <entry>Off</entry> + <entry>Any modifiers specified in the <emphasis> +mask</emphasis> + field of <emphasis> +mods</emphasis> + are removed from the locked modifiers.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +IM_UseCompat</emphasis> +, or <emphasis> +IM_UseEffective</emphasis> +</entry> + <entry>Off</entry> + <entry>Any modifiers specified in the <emphasis> +mask</emphasis> + field of <emphasis> +mods</emphasis> + are removed from both the locked and latched modifiers.</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +Lighting an explicit indicator which drives the keyboard also enables all of +the boolean controls specified in the <emphasis> +controls</emphasis> + field of its indicator map. Explicitly extinguishing such an indicator +disables all of the boolean controls specified in <emphasis> +controls</emphasis> +. +</para> + + +<para> +The effects of changing an indicator which drives the keyboard are cumulative; +it is possible for a single change to affect keyboard group, modifiers and +controls simultaneously. +</para> + + +<para> +If an indicator for which both the <emphasis> +IM_LEDDrivesKB</emphasis> + and <emphasis> +IM_NoAutomatic</emphasis> + flags are specified is changed, the keyboard changes specified above are +applied and the indicator is changed to reflect the state that was explicitly +requested. The indicator will remain in the new state until it is explicitly +changed again. +</para> + + +<para> +If the <emphasis> +IM_NoAutomatic</emphasis> + flag is not set for an indicator which drives the keyboard, the changes +specified above are applied and the state of the indicator is set 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, an indicator with <emphasis> +which_mods</emphasis> + of <emphasis> +IM_UseBase</emphasis> + and <emphasis> +mods</emphasis> + of <emphasis> +Shift</emphasis> + is not extinguished if one of the <emphasis> +Shift</emphasis> + keys is physically depressed when the request to extinguish the indicator is +processed. +</para> +</sect3> +</sect2> +</sect1> +</chapter> diff --git a/specs/ch10.xml b/specs/ch10.xml new file mode 100644 index 0000000..66b5cab --- /dev/null +++ b/specs/ch10.xml @@ -0,0 +1,174 @@ +<chapter id='keyboard_bells'> +<title>Keyboard Bells</title> + +<para> +The core protocol provides requests to control the pitch, volume and duration +of the keyboard bell and a request to explicitly sound the bell. +</para> + + +<para> +The X Keyboard Extension allows clients to disable the audible bell, attach a +symbolic name to a bell request or receive an event when the keyboard bell is +rung. +</para> + +<sect1 id='client_notification_of_bells'> +<title>Client Notification of Bells</title> + +<para> +Clients can ask to receive <emphasis> +XkbBellNotify</emphasis> + event when a bell is requested by a client or generated by the server. Bells +can be sounded due to core protocol <emphasis> +Bell</emphasis> + requests, X Input Extension <emphasis> +DeviceBell</emphasis> + requests, X Keyboard Extension <emphasis> +XkbBell</emphasis> + requests or for reasons internal to the server such as the XKB <emphasis> +AccessXFeedback</emphasis> + control. +</para> + + +<para> +Bell events caused by the <emphasis> +XkbBell</emphasis> + request or by the <emphasis> +AccessXFeedback</emphasis> + control include an optional window and symbolic name for the bell. If present, +the window makes it possible to provide some kind of visual indication of which +window caused the sound. The symbolic name can report some information about +the reason the bell was generated and makes it possible to generate a distinct +sound for each type of bell. +</para> + + +</sect1> +<sect1 id='disabling_server_generated_bells'> +<title>Disabling Server Generated Bells</title> + +<para> +The global <emphasis> +AudibleBell</emphasis> + boolean control for a keyboard indicates whether bells sent to that device +should normally cause the server to generate a sound. Applications which +provide "sound effects" for the various named bells will typically disable the +server generation of bells to avoid burying the user in sounds. +</para> + + +<para> +When the <emphasis> +AudibleBell</emphasis> + control is active, all bells caused by core protocol <emphasis> +Bell</emphasis> + and X Input Extension <emphasis> +DeviceBell</emphasis> + requests cause the server to generate a sound, as do all bells generated by +the XKB <emphasis> +AccessXFeedback</emphasis> + control. Bells requested via the X<emphasis> +kbBell</emphasis> + request normally cause a server-generated sound, but clients can ask the +server not to sound the default keyboard bell. +</para> + + +<para> +When the <emphasis> +AudibleBell</emphasis> + control is disabled, the server generates a sound only for bells that are +generated using the <emphasis> +XkbBell</emphasis> + request and which specify forced delivery of the bell. +</para> + + +</sect1> +<sect1 id='generating_named_bells'> +<title>Generating Named Bells</title> + +<para> +The <emphasis> +XkbBell</emphasis> + request allows clients to specify a symbolic name which is reported in the +bell events they cause. Bells generated by the <emphasis> +AccessXFeedback</emphasis> + control of this extension also include a symbolic name, but all kinds of +feedback cause a single event even if they sound multiple tones. +</para> + + +<para> +The X server is permitted to use symbolic bell names (when present) to generate +sounds other than simple tones, but it is not required to do so. +</para> + + +<para> +Aside from those used by the XKB <emphasis> +AccessXFeedback</emphasis> + control (see <ulink url="XKBproto.htm#50332257_21748">See The AccessXFeedback +Control</ulink>), this extension does not specify bell names or their +interpretation. +</para> + + +</sect1> +<sect1 id='generating_optional_named_bells'> +<title>Generating Optional Named Bells</title> + +<para> +Under some circumstances, some kind of quiet audio feedback is useful, but a +normal keyboard bell is not. For example, a quiet "launch effect" can be +helpful to let the user know that an application has been started, but a loud +bell would simply be annoying. +</para> + + +<para> +To simplify generation of these kinds of effects, the <emphasis> +XkbBell</emphasis> + request allows clients to specify "event only" bells. The X server never +generates a normal keyboard bell for "event only" bells, regardless of the +setting of the global <emphasis> +AudibleBell</emphasis> + control. +</para> + + +<para> +If the X server generates different sounds depending bell name, it is permitted +to generate a sound even for "event only" bells. This field is intended simply +to weed out "normal" keyboard bells. +</para> + + +</sect1> +<sect1 id='forcing_a_server_generated_bell'> +<title>Forcing a Server Generated Bell</title> + +<para> +Occasionally, it is useful to force the server to generate a sound. For +example, a client could "filter" server bells, generating sound effects for +some but sounding the normal server bell for others. Such a client needs a way +to tell the server that the requested bell should be generated regardless of +the setting of the <emphasis> +AudibleBell</emphasis> + control. +</para> + + +<para> +To simplify this process, clients which call the <emphasis> +XkbBell</emphasis> + request can specify that a bell is forced. A forced bell always causes a +server generated sound and never causes a <emphasis> +XkbBellNotify</emphasis> + event. Because forced bells do not cause bell notify events, they have no +associated symbolic name or event window. +</para> +</sect1> +</chapter> diff --git a/specs/ch11.xml b/specs/ch11.xml new file mode 100644 index 0000000..ed3596d --- /dev/null +++ b/specs/ch11.xml @@ -0,0 +1,414 @@ + +<chapter id='keyboard_geometry'> +<title>Keyboard Geometry</title> + +<para> +The XKB description of a keyboard includes an optional keyboard geometry which +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. +</para> + + +<para> +The components of the keyboard geometry include the following: +</para> + +<itemizedlist> +<listitem> + <para>A <emphasis> +symbolic name</emphasis> + to help users identify the keyboard. + </para> +</listitem> +<listitem> + <para>The <emphasis> +width</emphasis> + and <emphasis> +height</emphasis> + of the keyboard, in <mediaobject> + <imageobject> <imagedata fileref="XKBproto-8.gif"/> + </imageobject> + </mediaobject> +. For non-rectangular keyboards, the width and height describe the smallest +bounding-box that encloses the outline of the keyboard. + </para> +</listitem> +<listitem> + <para>A list of up to <emphasis> +MaxColors</emphasis> + (<emphasis> +32</emphasis> +) <emphasis> +color names</emphasis> +. A color name is a string whose interpretation is not specified by XKB. Other +geometry components refer to colors using their indices in this list. + </para> +</listitem> +<listitem> + <para>The<emphasis> + base color</emphasis> + 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. + </para> +</listitem> +<listitem> + <para>The <emphasis> +label color</emphasis> + is the color used to draw the labels on most of the keyboard keys. + </para> +</listitem> +<listitem> + <para>The <emphasis> +label font</emphasis> + is a string which describes the font used to draw labels on most keys; XKB +does not specify a format or name space for font names. + </para> +</listitem> +<listitem> + <para>A list of <emphasis> +geometry properties</emphasis> +. 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. + </para> +</listitem> +<listitem> + <para>A list of <emphasis> +key aliases</emphasis> +, as described in <ulink url="XKBproto.htm#50332257_15645">See Symbolic +Names</ulink>. + </para> +</listitem> +<listitem> + <para>A list of <emphasis> +shapes</emphasis> +; other keyboard components refer to shapes by their index in this list. A +shape consists of a name and one or more closed-polygons called <emphasis> +outlines</emphasis> +. Shapes and outlines are described in detail in <ulink +url="XKBproto.htm#50332257_35210">See Shapes and Outlines</ulink>. + </para> +</listitem> +</itemizedlist> + +<para> +Unless otherwise specified, geometry measurements are in <mediaobject> + <imageobject> <imagedata fileref="XKBproto-9.gif"/> + </imageobject> + </mediaobject> + + units. The origin (0,0) is in the top left corner of the keyboard image. Some +geometry components can be drawn rotated; all such objects rotate about their +origin in <mediaobject> + <imageobject> <imagedata fileref="XKBproto-10.gif"/> + </imageobject> + </mediaobject> + + increments. +</para> + + +<para> +All geometry components include a <emphasis> +priority</emphasis> +, which indicates the order in which overlapping objects should be drawn. +Objects are drawn in order from highest priority (<emphasis> +0</emphasis> +) to lowest (<emphasis> +255</emphasis> +). +</para> + + +<para> +The description of the actual appearance of the keyboard is subdivided into +named <emphasis> +sections</emphasis> + of related keys and <emphasis> +doodads</emphasis> +. A a <emphasis> +doodad</emphasis> + describes some visible aspect of the keyboard that is not a key. A section is +a collection of keys and doodads that are physically close together and +logically related. +</para> + +<sect1 id='shapes_and_outlines'> +<title>Shapes and Outlines</title> + +<para> +An outline is a list of one or more points which describes a single +closed-polygon, as follows: +</para> + +<itemizedlist> +<listitem> + <para>A list with a single point describes a rectangle with one corner at the +origin of the shape (<emphasis> +0</emphasis> +,<emphasis> +0</emphasis> +) and the opposite corner at the specified point. + </para> +</listitem> +<listitem> + <para>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. + </para> +</listitem> +<listitem> + <para>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. + </para> +</listitem> +<listitem> + <para>A non-zero value for the <emphasis> +cornerRadius</emphasis> + field specifies that the corners of the polygon should be drawn as circles +with the specified radius. + </para> +</listitem> +</itemizedlist> + +<para> +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. +</para> + + +<para> +One outline (usually the first) is the primary outline; a keyboard display +application can generate a simpler but still accurate keyboard image by +displaying only the primary outlines for each shape. Non-rectangular keys must +include a rectangular <emphasis> +approximation</emphasis> + 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. +</para> + + +</sect1> +<sect1 id='sections'> +<title>Sections</title> + +<para> +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 include: +</para> + +<itemizedlist> +<listitem> + <para>A list of <emphasis> +rows</emphasis> +. A row is a list of horizontally or vertically adjacent keys. Horizontal rows +parallel the (pre-rotation) top of the section and vertical rows parallel the +(pre-rotation) 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. + </para> +<para> +A key description consists of a key <emphasis> +name</emphasis> +, a <emphasis> +shape</emphasis> +, a key <emphasis> +color</emphasis> +, and a <emphasis> +gap</emphasis> +. The key <emphasis> +name</emphasis> + should correspond to one of the keys named in the keyboard names description, +the <emphasis> +shape</emphasis> + specifies the appearance of the key, and the key <emphasis> +color</emphasis> + specifies the color of the key (not the label on the key). Keys are normally +drawn immediately adjacent to one another from left-to-right (or top-to-bottom) +within a row. The <emphasis> +gap</emphasis> + field specifies the distance between a key and its predecessor. + </para> +</listitem> +<listitem> + <para>An optional list of doodads; 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 is relative to the +other components of the section, not to the keyboard as a whole. + </para> +</listitem> +<listitem> + <para>An optional list of <emphasis> +overlay keys</emphasis> +. Each overlay key definition indicates a key that can yield multiple scan +codes and consists of a field named <emphasis> +under</emphasis> +, which specifies the primary name of the key and a field named <emphasis> +over</emphasis> +, which specifies the name for the key when the overlay keycode is selected. +The key specified in <emphasis> +under</emphasis> + must be a member of the section that contains the overlay key definition, +while the key specified in over must not. + </para> +</listitem> +</itemizedlist> + +</sect1> +<sect1 id='doodads'> +<title>Doodads</title> + +<para> +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 describes the outline of the entire +keyboard, if present. +</para> + + +<para> +All doodads report their origin in fields named <emphasis> +left</emphasis> + and <emphasis> +top</emphasis> +. XKB supports five kinds of doodads: +</para> + +<itemizedlist> +<listitem> + <para>An <emphasis> +indicator doodad</emphasis> + describes one of the physical keyboard indicators. Indicator doodads specify +the shape of the indicator, the indicator color when it is lit (<emphasis> +on_color</emphasis> +) and the indicator color when it is dark (<emphasis> +off_color</emphasis> +). + </para> +</listitem> +<listitem> + <para>An <emphasis> +outline doodad</emphasis> + 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. + </para> +</listitem> +<listitem> + <para>A <emphasis> +solid doodad</emphasis> + 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. + </para> +</listitem> +<listitem> + <para>A <emphasis> +text doodad</emphasis> + 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. + </para> +</listitem> +<listitem> + <para>A <emphasis> +logo doodad</emphasis> + 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. + </para> + <para> +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. + </para> + <para> +The XKB extension does not specify the interpretation of logo names. + </para> +</listitem> +</itemizedlist> + +</sect1> +<sect1 id='keyboard_geometry_example'> +<title>Keyboard Geometry Example</title> + +<para> +Consider the following example keyboard: +</para> + +<mediaobject> + <imageobject> + <imagedata fileref="XKBproto-11.gif"/> + </imageobject> +</mediaobject> + + +<para> +This keyboard has six sections: The left and right function sections (at the +very top) each have one horizontal row with eight keys. The left and right +alphanumeric sections (the large sections in the middle) each have six vertical +rows, with four or five keys in each row. The left and right editing sections +each have three vertical rows with one to three keys per row; the left editing +section is rotated 20° clockwise about its origin while the right editing +section is rotated 20° counterclockwise. +</para> + + +<para> +This keyboard has four global doodads: Three small, round indicators and a +rectangular logo. The program which generated this image did not recognize the +logo, so it displays an outline with an appropriate shape in its place. +</para> + + +<para> +This keyboard has seven shapes: All of the keys in the two function sections +use the "FKEY" shape. Most of the keys in the alphanumeric sections, as well as +four of the keys in each of the editing sections use the "NORM" shape. The keys +in the first column of the left alphanumeric section and the last column of the +right alphanumeric section all use the "WIDE" shape. Two keys in each of the +editing sections use the "TALL" shape. The "LED" shape describes the three +small, round indicators between the function and alphabetic sections. The +"LOGO" shape describes the keyboard logo, and the "EDGE" shape describes the +outline of the keyboard as a whole. +</para> + + +<para> +The keyboard itself is white, as are all of the keys except for the eight keys +that make up the home row, which use the "grey20" color. It isn’t really +visible in this picture, but the three indicators have an "on" color of "green" +and are "green30" when they are turned off. The keys in the alphanumeric and +editing sections all have a (vertical) gap of 0.5mm; the keys in the two +function sections have a (horizontal) gap of 3mm. +</para> + + +<para> +Many of the keys in the right alphanumeric section, and the rightmost key in +the right editing section are drawn with two names in this image. Those are +overlay keys; the bottom key name is the normal name while the overlay name is +printed at the top. For example, the right editing section has a single overlay +key entry, which specifies an <emphasis> +under</emphasis> + name of <emphasis> +<SPCE></emphasis> + and an <emphasis> +over</emphasis> + name of <emphasis> +<KP0></emphasis> +, which indicates that the key in question is usually the shift key, but can +behave like the <emphasis> +0</emphasis> + key on the numeric keypad when an overlay is active. +</para> +</sect1> +</chapter> diff --git a/specs/ch12.xml b/specs/ch12.xml new file mode 100644 index 0000000..ff399a1 --- /dev/null +++ b/specs/ch12.xml @@ -0,0 +1,1025 @@ + +<chapter id='interactions_between_xkb_and_the_core_protocol'> +<title>Interactions Between XKB and the Core Protocol</title> + +<para> +In addition to providing a number of new requests, XKB replaces or extends +existing core protocol requests and events. Some aspects of the this extension, +such as the ability to lock any key or modifier, are visible even to clients +that are unaware of the XKB extension. Other capabilities, such as control of +keysym selection on a per-key basis, are available only to XKB-aware clients. +</para> + + +<para> +Though they do not have access to some advanced extension capabilities, the XKB +extension includes compatibility mechanisms to ensure that non-XKB clients +behave as expected and operate at least as well with an XKB-capable server as +they do today. +</para> + + +<para> +There are a few significant areas in which XKB state and mapping differences +might be visible to XKB-unaware clients: +</para> + +<itemizedlist> +<listitem> + <para>The core protocol uses a modifier to choose between two keyboard +groups, while this extension provides explicit support for multiple groups. + </para> +</listitem> +<listitem> + <para>The order of the symbols associated with any given key by XKB might not +match the ordering demanded by the core protocol. + </para> +</listitem> +</itemizedlist> + +<para> +To minimize problems that might result from these differences, XKB includes +ways to specify the correspondence between core protocol and XKB modifiers and +symbols. +</para> + + +<para> +This section describes the differences between the core X protocol’s notion +of a keyboard mapping and XKB and explains the ways they can interact. +</para> + +<sect1 id='group_compatibility_map'> +<title>Group Compatibility Map</title> + +<para> +As described in <ulink url="XKBproto.htm#50332257_13933">See Keyboard +State</ulink>, the current keyboard group is reported to XKB-aware clients in +bits 13-14 of the state field of many core protocol events. XKB-unaware clients +cannot interpret those bits, but they might use a keyboard modifier to +implement support for a single keyboard group. To ensure that pre-XKB clients +continue to work when XKB is present, XKB makes it possible to map an XKB state +field, which includes both keyboard group and modifier state into a pre-XKB +state field which contains only modifiers. +</para> + + +<para> +A keyboard description includes one <emphasis> +group compatibility map</emphasis> + per keyboard group (four in all). Each such map is a modifier definition (i.e. +specifies both real and virtual modifiers) which specifies the modifiers to be +set in the compatibility states when the corresponding keyboard group is +active. Here are a few examples to illustrate the application of the group +compatibility map: +</para> + +<informaltable frame='none'> +<tgroup cols='6'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Group</entry> + <entry>GroupCompat Map</entry> + <entry>Effective Modifiers</entry> + <entry> State for XKB Clients</entry> + <entry>Compatibility Modifiers</entry> + <entry>State for non-XKB Clients</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>1</entry> + <entry>Group1=None</entry> + <entry>Shift</entry> + <entry>x00xxxxx00000001</entry> + <entry>Shift</entry> + <entry>xxxxxxxx00000001</entry> + </row> + <row rowsep='0'> + <entry>2</entry> + <entry>Group2=Mod3</entry> + <entry>None</entry> + <entry>x01xxxxx00000000</entry> + <entry>Mod3</entry> + <entry>xxxxxxxx00100000</entry> + </row> + <row rowsep='0'> + <entry>3</entry> + <entry>Group3=Mod2</entry> + <entry>Shift</entry> + <entry>x10xxxxx00000001</entry> + <entry>Shift+Mod2</entry> + <entry>xxxxxxxx00010001</entry> + </row> + <row rowsep='0'> + <entry>4</entry> + <entry>Group4=None</entry> + <entry>Control</entry> + <entry>x11xxxxx00000100</entry> + <entry>Control</entry> + <entry>xxxxxxxx00000100</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +Note that non-XKB clients (i.e. clients that are linked with a version of the X +library that does not support XKB) cannot detect the fact that <emphasis> +Group4</emphasis> + is active in this example because the group compatibility map for <emphasis> +Group4</emphasis> + does not specify any modifiers. +</para> + + +<sect2 id='setting_a_passive_grab_for_an_xkb_state'> +<title>Setting a Passive Grab for an XKB State</title> + +<para> +The fact that the <emphasis> +state</emphasis> + field of an event might look different when XKB is present can cause problems +with passive grabs. Existing clients specify the modifiers they wish to grab +using the rules defined by the core protocol, which use a normal modifier to +indicate keyboard group. If we used an XKB state field, the high bits of the +state field would be non-zero whenever the keyboard was in any group other than +<emphasis> +Group1</emphasis> +, and none of the passive grabs set by clients could ever be triggered. +</para> + + +<para> +To avoid this behavior, the X server normally uses the compatibility grab state +to decide whether or not to activate a passive grab, even for XKB-aware +clients. The group compatibility map attempts to encode the keyboard group in +one or more modifiers of the compatibility state, so existing clients continue +to work exactly the way they do today. By default, there is no way to directly +specify a keyboard group in a <emphasis> +Grabbed</emphasis> + or <emphasis> +GrabButton</emphasis> + request, but groups can be specified indirectly by correctly adjusting the +group compatibility map. +</para> + + +<para> +Clients that wish to specify an XKB keyboard state, including a separate +keyboard group, can set the <emphasis> +GrabsUseXKBState</emphasis> + per-client flag which indicates that all subsequent key and button grabs from +the requesting clients are specified using an XKB state. +</para> + + +<para> +Whether the XKB or core state should be used to trigger a grab is determined by +the setting of the <emphasis> +GrabsUseXKBState</emphasis> + flag for the requesting client at the time the key or button is grabbed. There +is no way to change the state to be used for a grab that is already registered +or for grabs that are set by some other client. +</para> + + +</sect2> +</sect1> +<sect1 id='changing_the_keyboard_mapping_using_the_core_protocol'> +<title>Changing the Keyboard Mapping Using the Core Protocol</title> + +<para> +An XKB keyboard description includes a lot of information that is not present +in the core protocol description of a keyboard. 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. +</para> + + +<para> +Some aspects of this automatic mapping are configurable, and make it fairly +easy to take advantage of many XKB features using existing tools like <emphasis> +xmodmap</emphasis> +, but much of the process of mapping a core keyboard description into an XKB +description is designed to preserve compatible behavior for pre-XKB clients and +cannot be redefined by the user. Clients or users that want behavior that +cannot be described using this mapping should use XKB functions directly. +</para> + + +<sect2 id='explicit_keyboard_mapping_components'> +<title>Explicit Keyboard Mapping Components</title> + +<para> +This automatic remapping might accidentally replace definitions that were +explicitly requested by an application, so the XKB keyboard description defines +a set of <emphasis> +explicit components</emphasis> + for each key; any components that are listed in the explicit components for a +key are not changed by the automatic keyboard mapping. The explicit components +field for a key can contain any combination of the following values: +</para> + +<informaltable frame='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Bit in Explicit Mask</entry> + <entry>Protects Against</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>ExplicitKeyType1</entry> + <entry>Automatic determination of the key type associated with <emphasis> +Group1</emphasis> + (see <ulink url="XKBproto.htm#50332257_35661">See Assigning Types To Groups of +Symbols for a Key</ulink>)</entry> + </row> + <row rowsep='0'> + <entry>ExplicitKeyType2</entry> + <entry>Automatic determination of the key type associated with <emphasis> +Group2 </emphasis> +(see <ulink url="XKBproto.htm#50332257_35661">See Assigning Types To Groups of +Symbols for a Key</ulink>)</entry> + </row> + <row rowsep='0'> + <entry>ExplicitKeyType3</entry> + <entry>Automatic determination of the key type associated with <emphasis> +Group3 </emphasis> +(see <ulink url="XKBproto.htm#50332257_35661">See Assigning Types To Groups of +Symbols for a Key</ulink>).</entry> + </row> + <row rowsep='0'> + <entry>ExplicitKeyType4</entry> + <entry>Automatic determination of the key type associated with <emphasis> +Group4 </emphasis> +(see <ulink url="XKBproto.htm#50332257_35661">See Assigning Types To Groups of +Symbols for a Key</ulink>).</entry> + </row> + <row rowsep='0'> + <entry>ExplicitInterpret</entry> + <entry>Application of any of the fields of a symbol interpretation to the +key in question (see <ulink url="XKBproto.htm#50332257_66444">See Assigning +Actions To Keys</ulink>).</entry> + </row> + <row rowsep='0'> + <entry>ExplicitAutoRepeat</entry> + <entry>Automatic determination of autorepeat status for the key, as +specified in a symbol interpretation (see <ulink +url="XKBproto.htm#50332257_66444">See Assigning Actions To +Keys</ulink>).</entry> + </row> + <row rowsep='0'> + <entry>ExplicitBehavior</entry> + <entry>Automatic assignment of the <emphasis> +KB_Lock</emphasis> + behavior to the key, if the <emphasis> +LockingKey</emphasis> + flag is set in a symbol interpretation (see <ulink +url="XKBproto.htm#50332257_66444">See Assigning Actions To +Keys</ulink>).</entry> + </row> + <row rowsep='0'> + <entry>ExplicitVModMap</entry> + <entry>Automatic determination of the virtual modifier map for the key +based on the actions assigned to the key and the symbol interpretations which +match the key (see <ulink url="XKBproto.htm#50332257_66444">See Assigning +Actions To Keys</ulink>).</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +</sect2> +<sect2 id='assigning_symbols_to_groups'> +<title>Assigning Symbols To Groups</title> + +<para> +The first step in applying the changes specified by a core protocol <emphasis> +ChangeKeyboardMapping</emphasis> + request to the XKB description of a keyboard is to determine the number of +groups that are defined for the key and the width of each group. The XKB +extension does not change key types in response to core protocol <emphasis> +SetModifierMapping</emphasis> + requests, but it does choose key actions as described in <ulink +url="XKBproto.htm#50332257_66444">See Assigning Actions To Keys</ulink>. +</para> + + +<para> +Determining the number of symbols required for each group is straightforward. +If the key type for some group is not protected by the corresponding <emphasis> +ExplicitKeyType</emphasis> + component, that group has two symbols. If any of the explicit components for +the key include <emphasis> +ExplicitKeyType3</emphasis> + or <emphasis> +ExplicitKeyType4</emphasis> +, the width of the key type currently assigned to that group determines the +number of symbols required for the group in the core protocol keyboard +description. The explicit type components for <emphasis> +Group1</emphasis> + and <emphasis> +Group2</emphasis> + behave similarly, but for compatibility reasons the first two groups must have +at least two symbols in the core protocol symbol mapping. Even if an explicit +type assigned to either of the first two keyboard groups has fewer than two +symbols, XKB requires two symbols for it in the core keyboard description. +</para> + + +<para> +If the core protocol request contains fewer symbols than XKB needs, XKB adds +trailing <emphasis> +NoSymbol</emphasis> + keysyms to the request to pad it to the required length. If the core protocol +request includes more symbols than it needs, XKB truncates the list of keysyms +to the appropriate length. +</para> + + +<para> +Finally, XKB divides the symbols from the (possibly padded or truncated) list +of symbols specified by the core protocol request among the four keyboard +groups. In most cases, the symbols for each group are taken from the core +protocol definition in sequence (i.e. the first pair of symbols is assigned to +<emphasis> +Group1</emphasis> +, the second pair of symbols is assigned to <emphasis> +Group2</emphasis> +, and so forth). If either <emphasis> +Group1</emphasis> + or <emphasis> +Group2</emphasis> + has an explicitly defined key type with a width other than two, it gets a +little more complicated. +</para> + + +<sect3 id="assigning_symbols_to_groups_one_and_two_with_explicitly_defined_key_types"> +<title>Assigning Symbols to Groups One and Two with Explicitly Defined Key Types</title> + +<para> +The server assigns the first four symbols from the expanded or truncated map to +the symbol positions <emphasis>G1L1</emphasis> , <emphasis>G1L2</emphasis>, +<emphasis>G2L1</emphasis> and <emphasis>G2L2</emphasis>, respectively. If the key +type assigned to <emphasis>Group1</emphasis> reports more than two shift levels, +the fifth and following symbols contain +the extra keysyms for <emphasis> +Group2</emphasis> +. If the key type assigned to <emphasis> +Group2</emphasis> + reports more than two shift levels, the extra symbols follow the symbols (if +any) for <emphasis> +Group1</emphasis> + in the core protocol list of symbols. Symbols for <emphasis> +Group3</emphasis> + and <emphasis> +Group4</emphasis> + are contiguous and follow the extra symbols, if any, for <emphasis> +Group1</emphasis> + and <emphasis> +Group2</emphasis> +. +</para> + + +<para> +For example, consider a key with a key type that returns three shift levels +bound to each group. The symbols bound to the core protocol are assigned in +sequence to the symbol positions: +</para> + +<literallayout class='monospaced'> +<emphasis>G1L1</emphasis>, <emphasis>G1L2</emphasis>, <emphasis>G2L1</emphasis>, <emphasis>G2L2</emphasis>, <emphasis>G1L3</emphasis>, <emphasis>G2L3</emphasis>, <emphasis>G3L1</emphasis>, <emphasis>G3L2</emphasis>, <emphasis>G3L3</emphasis>, <emphasis>G4L1</emphasis>, <emphasis>G4L2</emphasis>, and <emphasis>G4L3</emphasis> +</literallayout> + +<para> +For a key with a width one key type on group one, a width two key type on group +two and a width three key type on group three, the symbols bound to the key by +the core protocol are assigned to the following key positions: +</para> + +<literallayout class='monospaced'> +<emphasis>G1L1</emphasis>, (<emphasis>G1L2</emphasis>), <emphasis>G2L1</emphasis>, <emphasis>G2L2</emphasis>, <emphasis>G3L1</emphasis>, <emphasis>G3L2</emphasis>, <emphasis>G3L3</emphasis> +</literallayout> + +<para> +Note that the second and fourth symbols (positions <emphasis> +G1L2 and G2L2</emphasis> +) can never be generated if the key type associated with the group yields only +one symbol. XKB accepts and ignores them in order to maintain compatibility +with the core protocol. +</para> + + +</sect3> +</sect2> +<sect2 id='assigning_types_to_groups_of_symbols_for_a_key'> +<title>Assigning Types To Groups of Symbols for a Key</title> + +<para> +Once the symbols specified by <emphasis> +ChangeKeyboardMapping</emphasis> + have been assigned to the four keyboard groups for a key, the X server assigns +a key type to each group on the key from a canonical list of key types. The +first four key types in any keyboard map are reserved for these standard key +types: +</para> + +<informaltable frame='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Key Type Name</entry> + <entry>Standard Definition</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis> +ONE_LEVEL</emphasis> +</entry> + <entry>Describes keys that have exactly one symbol per group. Most special +or function keys (such as <emphasis> +Return</emphasis> +) are <emphasis> +ONE_LEVEL</emphasis> + keys. Any combination of modifiers yields level <emphasis> +0</emphasis> +. Index <emphasis> +0</emphasis> + in any key symbol map specifies key type <emphasis> +ONE_LEVEL</emphasis> +.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +TWO_LEVEL</emphasis> +</entry> + <entry>Describes non-keypad and non-alphabetic keys that have exactly two +symbols per group. By default, the <emphasis> +TWO_LEVEL</emphasis> + type yields column <emphasis> +1</emphasis> + if the Shift modifier is set, column <emphasis> +0</emphasis> + otherwise. Index <emphasis> +1</emphasis> + in any key symbol map specifies key type <emphasis> +TWO_LEVEL</emphasis> +.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +ALPHABETIC</emphasis> +</entry> + <entry>Describes alphabetic keys that have exactly two symbols per group. +The default definition of the <emphasis> +ALPHABETIC</emphasis> + type provides shift-cancels-caps behavior as described in <ulink +url="XKBproto.htm#50332257_45629">See Key Types</ulink>. Index <emphasis> +2</emphasis> + in any key symbol map specifies key type <emphasis> +ALPHABETIC</emphasis> +.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +KEYPAD</emphasis> +</entry> + <entry>Describes numeric keypad keys with two symbols per group. Yields +column <emphasis> +1</emphasis> + if either of the <emphasis> +Shift</emphasis> + modifier or the real modifier bound to the virtual modifier named <emphasis> +NumLock</emphasis> + are set. Yields column <emphasis> +0</emphasis> + if neither or both modifiers are set. Index <emphasis> +3</emphasis> + in any key symbol map specifies key type <emphasis> +KEYPAD</emphasis> +.</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +Users or applications may change these key types to get different default +behavior (to make shift cancel caps lock, for example) but they must always +have the specified number of symbols per group. +</para> + + +<para> +Before assigning key types to groups, the X server expands any alphanumeric +symbol definitions as follows: +</para> + + +<para> +If the second symbol of either group is <emphasis> +NoSymbol</emphasis> + and the first symbol of that group is an alphabetic keysym for which both +lowercase and uppercase forms are defined, the X server treats the key as if +the first element of the group were the lowercase form of the symbol and the +second element were the uppercase form of the symbol. For the purposes of this +expansion, XKB ignores the locale and uses the capitalization rules defined in +<ulink url="dflttrns.htm#17949"></ulink>. +</para> + + +<para> +For each keyboard group that does not have an explicit type definition, XKB +chooses a key type from the canonical key types. If the second symbol assigned +to a group is <emphasis> +NoSymbol</emphasis> + (after alphabetic expansion), the server assigns key type <emphasis> +ONE_LEVEL</emphasis> +. If the group contains the lowercase and uppercase forms of a single glyph +(after alphanumeric expansion), the server assigns key type <emphasis> +ALPHABETIC</emphasis> +. If either of the symbols in a group is a numeric keypad keysym (<emphasis> +KP_*</emphasis> +), the server assigns key type <emphasis> +KEYPAD</emphasis> +. Otherwise, it assigns key type <emphasis> +TWO_LEVEL</emphasis> +. +</para> + + +<para> +Finally, XKB determines the number of groups of symbols that are actually +defined for the key. Trailing empty groups (i.e. groups that have <emphasis> +NoSymbol</emphasis> + in all symbol positions) are ignored. +</para> + + +<para> +There are two last special cases for compatibility with the core protocol: If, +after trailing empty groups are excluded, all of the groups of symbols bound to +the key have identical type and symbol bindings, XKB assigns only one group to +the key. If <emphasis> +Group2</emphasis> + is empty and either of <emphasis> +Group3</emphasis> + or <emphasis> +Group4</emphasis> + are not, and if neither <emphasis> +Group1</emphasis> + nor <emphasis> +Group2</emphasis> + have explicit key types, XKB copies the symbols and key type from <emphasis> +Group1</emphasis> + into <emphasis> +Group2</emphasis> +. +</para> + + +</sect2> +<sect2 id='assigning_actions_to_keys'> +<title>Assigning Actions To Keys</title> + +<para> +Once symbols have been divided into groups and key types chosen for the keys +affected by a <emphasis> +ChangeKeyboardMapping</emphasis> + request, XKB examines the symbols and modifier mapping for each changed key +and assigns server actions where appropriate. XKB also automatically assigns +server actions to changed keys if the client issues a core protocol <emphasis> +SetModifierMapping</emphasis> + request, and does so optionally in response to <emphasis> +XkbSetMap</emphasis> + and <emphasis> +XkbSetCompatMap</emphasis> + requests. +</para> + + +<para> +The compatibility map includes a list of <emphasis> +symbol interpretations</emphasis> +, which XKB compares to each symbol associated with any changed keys in turn, +unless the <emphasis> +ExplicitInterp</emphasis> + component is set for a key. Setting the <emphasis> +ExplicitInterp</emphasis> + component prevents the application of symbol interpretations to that key. +</para> + + +<para> +If the modifiers and keysym specified in a symbol interpretation match the +modifier mapping and a symbol bound to a changed key that is not protected by +<emphasis> +ExplicitInterp</emphasis> +, the server applies the symbol interpretation to the symbol position. The +server considers all symbol interpretations which specify an explicit keysym +before considering any that do not. The server uses the first interpretation +which matches the given combination of keysym and modifier mapping; other +matching interpretations are ignored. +</para> + + +<para> +XKB uses four of the fields of a symbol interpretation to decide if it matches +one of the symbols bound to some changed key: +</para> + +<itemizedlist> +<listitem> + <para>The <emphasis> +symbol</emphasis> + field is a keysym which matches if it has the value <emphasis> +NoSymbol</emphasis> + or is identical to the symbol in question. + </para> +</listitem> +<listitem> + <para>The modifiers specified in the <emphasis> +mods</emphasis> + field are compared to the modifiers affected by the key in question as +indicated by <emphasis> +match</emphasis> +. + </para> +</listitem> +<listitem> + <para>The <emphasis> +match</emphasis> + field can specify any of the comparisons: <emphasis> +NoneOf</emphasis> +, <emphasis> +AnyOfOrNone</emphasis> +, <emphasis> +AnyOf</emphasis> +, <emphasis> +AllOf</emphasis> + or <emphasis> +Exactly</emphasis> +. + </para> +</listitem> +<listitem> + <para>The <emphasis> +levelOneOnly</emphasis> + setting, indicates that the interpretation in question should only use the +modifiers bound to this key by the modifier mapping if the symbol that matches +in level one of its group. Otherwise, if the symbol being considered is not in +shift level one of its group, the server behaves as if the modifier map for the +key were empty. Note that it is still possible for such an interpretation to +apply to a symbol in a shift level other than one if it matches a key without +modifiers; the <emphasis> +levelOneOnly</emphasis> + flag only controls the way that matches are determined and that the key +modifiers are applied when an interpretation does match. + </para> +</listitem> +</itemizedlist> + +<para> +Applying a symbol interpretation can affect several aspects of the XKB +definition of the key symbol mapping to which it is applied: +</para> + +<itemizedlist> +<listitem> + <para>The <emphasis> +action</emphasis> + specified in the symbol interpretation is bound to the symbol position; any +key event which yields that symbol will also activate the new action. + </para> +</listitem> +<listitem> + <para>If the matching symbol is in position G1L1, the autorepeat behavior of +the key is set from the <emphasis> +autorepeat</emphasis> + field of the symbol interpretation. The <emphasis> +ExplicitAutoRepeat</emphasis> + component protects the autorepeat status of a key from symbol interpretation +initiated changes. + </para> +</listitem> +<listitem> + <para>If the symbol interpretation specifies an associated virtual modifier, +that virtual modifier is added to the virtual modifier map for the key. The +<emphasis> +ExplicitVModMap</emphasis> + component guards the virtual modifier map for a key from automatic changes. If +the <emphasis> +levelOneOnly</emphasis> + flag is set for the interpretation, and the symbol in question is not in +position G1L1, the virtual modifier map is not updated. + </para> +</listitem> +<listitem> + <para>If the matching symbol is in position G1L1, and the <emphasis> +locking key</emphasis> + field is set in the symbol interpretation, the behavior of the key is changed +to <emphasis> +KB_Lock</emphasis> + (see <ulink url="XKBproto.htm#50332257_81140">See Key Behavior</ulink>). The +<emphasis> +ExplicitBehavior</emphasis> + component prevents this change. + </para> +</listitem> +</itemizedlist> + +<para> +If no interpretations match a given symbol or key, the server uses: <emphasis> +SA_NoAction</emphasis> +, autorepeat enabled, non-locking key. with no virtual modifiers. +</para> + + +<para> +If all of the actions computed for a key are <emphasis> +SA_NoAction</emphasis> +, the server assigns an length zero list of actions to the key. +</para> + + +<para> +If the core protocol modifier mapping is changed, the server regenerates +actions for the affected keys. The <emphasis> +XkbSetMap</emphasis> + and <emphasis> +XkbSetCompatMap</emphasis> + requests can also cause actions for some or all keyboard keys to be recomputed. +</para> + + +</sect2> +<sect2 id='updating_everything_else'> +<title>Updating Everything Else</title> + +<para> +Changes to the symbols or modifier mapping can affect the bindings of virtual +modifiers. If any virtual modifiers change, XKB updates all of its data +structures to reflect the change. Applying virtual modifier changes to the +keyboard mapping night result in changes to types, the group compatibility map, +indicator maps, internal modifiers or ignore locks modifiers. +</para> + + +</sect2> +</sect1> +<sect1 id='effects_of_xkb_on_core_protocol_events'> +<title>Effects of XKB on Core Protocol Events</title> + +<para> +After applying server actions which modify the base, latched or locked modifier +or group state of the keyboard, the X server recomputes the effective group and +state. Several components of the keyboard state are reported to XKB-aware +clients depending on context (see <ulink url="XKBproto.htm#50332257_13933">See +Keyboard State</ulink> for a detailed description of each of the keyboard state +components): +</para> + +<itemizedlist> +<listitem> + <para>The effective modifier state is reported in <emphasis> +XkbStateNotify</emphasis> + events and in response to <emphasis> +XkbGetState</emphasis> + requests. + </para> +</listitem> +<listitem> + <para>The symbol lookup state is reported to XKB-aware clients in the state +field of core protocol and input extension key press and release events that do +not activate passive grabs. Unless the <emphasis> +LookupStateWhenGrabbed</emphasis> + per-client flag is set, the lookup state is only reported in these events when +no grabs are active. + </para> +</listitem> +<listitem> + <para>The grab state is reported to XKB-aware clients in the state field of +all core protocol events that report keyboard state, except <emphasis> +KeyPress</emphasis> + and <emphasis> +KeyRelease</emphasis> + events that do not activate passive grabs. + </para> +</listitem> +<listitem> + <para>The effective group is the sum of the base, latched and locked keyboard +groups. An out of range effective group is wrapped or truncated into range +according to the setting of the <emphasis> +groupsWrap</emphasis> + flag for the keyboard. + </para> +</listitem> +</itemizedlist> + +<para> +The server reports compatibility states to any clients that have not issued a +successful <emphasis> +XkbUseExtension</emphasis> + request. The server computes the compatibility symbol lookup state and the +compatibility effective grab state by applying the compatibility modifier map +to the corresponding computed XKB states. +</para> + + +<para> +The compatibility symbol lookup state is reported to non-XKB clients whenever +an XKB-aware client would receive the XKB lookup state. The compatibility grab +state is reported to XKB-unaware clients whenever an XKB client would receive +the XKB grab state. +</para> + + +<para> +If the <emphasis> +GrabsUseXKBState</emphasis> + per-client option is not set, even XKB-aware clients receive the compatibility +grab state in events that trigger or terminate passive grabs. If this flag is +not set, XKB clients also receive the compatibility grab or lookup state +whenever any keyboard grab is active. +</para> + + +<para> +If the <emphasis> +LookupStateWhenGrabbed</emphasis> + per-client option is set, clients receive either the XKB or compatibility +lookup state when the keyboard is grabbed, otherwise they receive either the +XKB or compatibility grab state. All non-XKB clients receive the compatibility +form of the appropriate state component; the form that is sent to an XKB-aware +client depends on the setting of the <emphasis> +GrabsUseXKBState</emphasis> + option for that client. +</para> + + +</sect1> +<sect1 id='effect_of_xkb_on_core_protocol_requests'> +<title>Effect of XKB on Core Protocol Requests</title> + +<para> +Whenever a client updates the keyboard mapping using a core protocol request, +the server saves the requested core protocol keyboard mapping and reports it to +any clients that issue <emphasis> +GetKeyboardMapping</emphasis> + or <emphasis> +GetModifierMapping</emphasis> + requests. Whenever a client updates the keyboard mapping using XKB requests, +the server discards the affected portion of the stored core keyboard +description and regenerates it based on the XKB description of the keyboard. +</para> + + +<para> +The symbols associated with the XKB keyboard description appear in the order: +</para> + +<literallayout class='monospaced'> +G1L1 G1L2 G2L1 G2L2 G1L3-n G2L3-n G3L* G4L* +</literallayout> + +<para> +If the type associated with <emphasis> +Group1</emphasis> + is width one, the second symbol is <emphasis> +NoSymbol</emphasis> +; if the type associated with <emphasis> +Group2</emphasis> + is width one, the fourth symbol is <emphasis> +NoSymbol</emphasis> +. +</para> + + +<para> +If a key has only one group but the keyboard has several, the symbols for +<emphasis> +Group1</emphasis> + are repeated for each group. For example, given a keyboard with three groups +and a key with one group that contains the symbols { <emphasis> +a A</emphasis> + }, the core protocol description would contain the six symbols: { <emphasis> +a</emphasis> + <emphasis> +A</emphasis> + <emphasis> +a</emphasis> + <emphasis> +A</emphasis> + <emphasis> +a</emphasis> + <emphasis> +A</emphasis> + }. As a slightly more complicated example, an XKB key which had a single width +three group with the symbols { <emphasis> +a</emphasis> + <emphasis> +b</emphasis> + <emphasis> +c</emphasis> + } would show up in the generated core protocol keyboard description with the +symbols { <emphasis> +a</emphasis> + <emphasis> +b</emphasis> + <emphasis> +a</emphasis> + <emphasis> +b</emphasis> + <emphasis> +c</emphasis> + <emphasis> +c</emphasis> + <emphasis> +a</emphasis> + <emphasis> +b</emphasis> + <emphasis> +c</emphasis> + } for a keyboard with three groups. +</para> + + +<para> +The generated modifier mapping for a key contains all of the modifiers affected +by all of the actions associated with the key plus all of the modifiers +associated with any virtual modifiers bound to the key by the virtual modifier +mapping. If any of the actions associated with a key affect any component of +the keyboard group, any modifiers specified in any entry of the group +compatibility map (see <ulink url="XKBproto.htm#50332257_40656">See Group +Compatibility Map</ulink>) are reported in the modifier mask. The <emphasis> +SA_ISOLock</emphasis> + action can theoretically affect any modifier, but the modifier map of an +<emphasis> +SA_ISOLock</emphasis> + key contains only the modifiers or group state that it sets by default. +</para> + + +<para> +The server notifies interested clients of keyboard map changes in one of two +ways. It sends <emphasis> +XkbMapNotify</emphasis> + to clients that have explicitly selected them and core protocol <emphasis> +MappingNotify</emphasis> + events to clients that have not. Once a client requests <emphasis> +XkbMapNotify</emphasis> + events, the server stops sending it <emphasis> +MappingNotify</emphasis> + events to inform it of keyboard changes. +</para> + + +</sect1> +<sect1 id='sending_events_to_clients'> +<title>Sending Events to Clients</title> + +<para> +XKB normally assumes that events sent to clients using the core protocol +<emphasis> +SendEvent</emphasis> + request contain a core protocol state, if applicable. If the client which will +receive the event is not XKB-capable, XKB attempts to convert the core state to +an XKB state as follows: if any of the modifiers bound to <emphasis> +Group2</emphasis> + in the group compatibility map are set in the event state, XKB clears them in +the resulting event but sets the effective group in the event state to +<emphasis> +Group2</emphasis> +. +</para> + + +<para> +If the <emphasis> +PCF_SendEventUsesXKBState</emphasis> + per-client flag is set at the time of the SendEvent request, XKB instead +assumes that the event reported in the event is an XKB state. If the receiving +client is not XKB-aware, the extension converts the XKB state (which contains +the effective state in bits 13-14) to a core state by applying the group +compatibility map just as it would for actual key events. +</para> + +</sect1> +</chapter> diff --git a/specs/ch13.xml b/specs/ch13.xml new file mode 100644 index 0000000..5797f9f --- /dev/null +++ b/specs/ch13.xml @@ -0,0 +1,440 @@ +<chapter id='the_server_database_of_keyboard_components'> +<title>The Server Database of Keyboard Components</title> + +<para> +The X server maintains a database of keyboard components and common keyboard +mappings. This database contains five kinds of components; when combined, these +five components provide a complete description of a keyboard and its behavior. +</para> + + +<para> +The X Keyboard Extension provides requests to list the contents of this +database, to assemble and complete keyboard descriptions by merging the current +keyboard description with the contents of this database, or to replace the +current keyboard description with a complete keyboard description assembled as +described below. +</para> + +<sect1 id='component_names'> +<title>Component Names</title> + +<para> +Component and keymap names have the form "<emphasis> +class</emphasis> +(<emphasis> +member</emphasis> +)" where <emphasis> +class</emphasis> + describes a subset of the available components for a particular type and the +optional <emphasis> +member</emphasis> + identifies a specific component from that subset. For example, the name +"atlantis(acme)" might specify the symbols used for the atlantis national +keyboard layout by the vendor "acme." Each class has an optional <emphasis> +default</emphasis> + member — references which specify a class but not a member refer to the +default member of the class, if one exists. +</para> + + +<para> +The <emphasis> +class</emphasis> + and <emphasis> +member</emphasis> + 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. +</para> + + +</sect1> +<sect1 id='partial_components_and_combining_multiple_components'> +<title>Partial Components and Combining Multiple Components</title> + +<para> +Some of the elements in the server database contain describe only a piece of +the corresponding keyboard component. These <emphasis> +partial</emphasis> + components should be combined with other components of the same type to be +useful. +</para> + + +<para> +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 configure <emphasis> +any</emphasis> + ASCII keyboard to use a national layout. +</para> + + +<para> +Two components can be combined in two ways: +</para> + +<itemizedlist> +<listitem> + <para>If the second component <emphasis> +overrides</emphasis> + the first, any definitions that are present in both components are taken from +the second. + </para> +</listitem> +<listitem> + <para>If the second component <emphasis> +augments</emphasis> + the first, any definitions that are present in both components are taken from +the first. + </para> +</listitem> +</itemizedlist> + +<para> +Applications can use a <emphasis> +component expression</emphasis> + to combine multiple components of some time into a complete description of +some aspect of the keyboard. A component expression is a string which lists the +components to be combined separated by operators which specify the rules for +combining them. A complete description is assembled from the listed components, +left to right, as follows: +</para> + +<itemizedlist> +<listitem> + <para>If the new elements are being merged with an existing map, the special +component name ‘%’ refers to the unmodified value of the map. + </para> +</listitem> +<listitem> + <para>The ‘+’ operator specifies that the next specified component should +override the current assembled definition. + </para> +</listitem> +<listitem> + <para>The ‘|’ operator specifies that the next specified component should +augment the currently assembled definition. + </para> +</listitem> +<listitem> + <para>If the new elements are being merged with an existing map and the +component expression begins with an operator, a leading ‘%’ is implied. + </para> +</listitem> +<listitem> + <para>If any unknown or illegal characters appear anywhere in the string, the +entire expression is invalid and is ignored. + </para> +</listitem> +</itemizedlist> + +<para> +For example, the component expression "+de" specifies that the default element +of the "de" map should be applied to the current keyboard mapping, overriding +any existing definitions. +</para> + + +<para> +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 default ASCII keyboard for Acme, overrides them with any +keys that are defined for the default German keyboard layout and then applies +the definitions from the iso9995-3 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). +</para> + + +</sect1> +<sect1 id='component_hints'> +<title>Component Hints</title> + +<para> +Each component has a set of flags that provide some additional hints about that +component. XKB provides these hints for clients that present the keyboard +database to users and specifies their interpretation only loosely. Clients can +use these hints to constrain the list of components or to control the way that +components are presented to the user. +</para> + + +<para> +Hints for a component are reported with its name. The least significant byte of +the hints field has the same meaning for all five types of keyboard components, +and can contain any combination of the following values: +</para> + +<informaltable frame='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Flag</entry> + <entry>Meaning</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis> +LC_Hidden</emphasis> +</entry> + <entry>Indicates a component that should not normally be presented to the +user.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +LC_Default</emphasis> +</entry> + <entry>Indicates a component that is the default member of its +class.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +LC_Partial</emphasis> +</entry> + <entry>Indicates a partial component.</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +The interpretation of the most significant byte of the hints field is dependent +on the type of component. The hints defined for each kind of component are +listed in the section below that describes that kind of component. +</para> + + +</sect1> +<sect1 id='keyboard_components'> +<title>Keyboard Components</title> + +<para> +The five types of components stored in the server database of keyboard +components correspond to the <emphasis> +symbols</emphasis> +, <emphasis> +geometry</emphasis> +, <emphasis> +keycodes</emphasis> +, <emphasis> +compat</emphasis> + and <emphasis> +types</emphasis> + symbolic names associated with a keyboard. +</para> + +</sect1> +<sect1 id='the_keycodes_component'> +<title>The Keycodes Component</title> + +<para> +The <emphasis> +keycodes</emphasis> + component of a keyboard mapping specifies the range and interpretation of the +raw keycodes reported by the device. It sets the <emphasis> +keycodes</emphasis> + symbolic name, the minimum and maximum legal keycodes for the keyboard, and +the symbolic name for each key. The keycodes component might also contain +aliases for some keys, symbolic names for some indicators, and a description of +which indicators are physically present. +</para> + + +<para> +The special keycodes component named "computed" indicates that XKB should +assign unused keycodes to any unknown keys referenced by name by any of the +other components. The computed keycodes component is useful primarily when +browsing keymaps because it makes it possible to use the symbols and geometry +components without having to find a set of keycodes that includes keycode +definitions for all of the keys listed in the two components. +</para> + + +<para> +XKB defines no hints that are specific to the keycodes component. +</para> + + +<sect2 id='the_types_component'> +<title>The Types Component</title> + +<para> +The <emphasis> +types</emphasis> + component of a keyboard mapping specifies the key types that can be associated +with the various keyboard keys. It affects the <emphasis> +types</emphasis> + symbolic name and the list of types associated with the keyboard (see <ulink +url="XKBproto.htm#50332257_45629">See Key Types</ulink>). The types component +of a keyboard mapping can also optionally contain real modifier bindings and +symbolic names for one or more virtual modifiers. +</para> + + +<para> +The special types component named "canonical" always contains the types and +definitions listed in <ulink url="types.htm#24591"></ulink> of this document. +</para> + + +<para> +XKB defines no hints that are specific to the types component. +</para> + + +</sect2> +<sect2 id='the_compatibility_map_component'> +<title>The Compatibility Map Component</title> + +<para> +The <emphasis> +compatibility map</emphasis> + component of a keyboard mapping primarily specifies the rules used to assign +actions to keysyms. It affects the <emphasis> +compat</emphasis> + symbolic name, the symbol compatibility map and the group compatibility map. +The compat component might also specify maps for some indicators and the real +modifier bindings and symbolic names of some virtual modifiers. +</para> + + +<para> +XKB defines no hints that are specific to the compatibility map component. +</para> + + +</sect2> +<sect2 id='the_symbols_component'> +<title>The Symbols Component</title> + +<para> +The <emphasis> +symbols</emphasis> + component of a keyboard mapping specifies primarily the symbols bound to each +keyboard key. It affects the <emphasis> +symbols</emphasis> + symbolic name, a key symbol mapping for each key, they keyboard modifier +mapping, and the symbolic names for the keyboard symbol groups. Optionally, the +<emphasis> +symbols</emphasis> + component can contain explicit actions and behaviors for some keys, or the +real modifier bindings and symbolic names for some virtual modifiers. +</para> + + +<para> +XKB defines the following additional hints for the symbols component: +</para> + +<informaltable frame='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Flag</entry> + <entry>Meaning</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis> +LC_AlphanumericKeys</emphasis> +</entry> + <entry>Indicates a symbol component that contains bindings primarily for an +alphanumeric section of the keyboard.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +LC_ModifierKeys</emphasis> +</entry> + <entry>Indicates a symbol component that contains bindings primarily for +modifier keys.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +LC_KeypadKeys</emphasis> +</entry> + <entry>Indicates a symbol component that contains bindings primarily for +numeric keypad keys.</entry> + </row> + <row rowsep='0'> + <entry>LC_FunctionKeys</entry> + <entry>Indicates a symbol component that contains bindings primarily for +function keys.</entry> + </row> + <row rowsep='0'> + <entry>LC_AlternateGroup</entry> + <entry>Indicates a symbol component that contains bindings for an alternate +keyboard group.</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +These hints only apply to partial symbols components; full symbols components +are assumed to specify all of the pieces listed above. +</para> + +<note><para>The alphanumeric, modifier, keypad or function keys hints should +describe the primary intent of the component designer and should not 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 too; such mappings should set only <emphasis> +LC_AlphanumericKeys</emphasis> + hint. In general, symbol components should set only one of those four flags +(though <emphasis> +LC_AlternateGroup</emphasis> + may be combined with any of the other flags).</para></note> + +</sect2> +<sect2 id='the_geometry_component'> +<title>The Geometry Component</title> + +<para> +The <emphasis> +geometry</emphasis> + component of a keyboard mapping specifies primarily the geometry of the +keyboard. It contains the geometry symbolic name and the keyboard geometry +description. The geometry component might also contain aliases for some keys or +symbolic names for some indicators and might affect the set of indicators that +are physically present. Key aliases defined in the geometry component of a +keyboard mapping override those defined in the keycodes component. +</para> + + +<para> +XKB defines no hints that are specific to the geometry component. +</para> + + +</sect2> +</sect1> +<sect1 id='complete_keymaps'> +<title>Complete Keymaps</title> + +<para> +The X server also reports a set of fully specified keymaps. The keymaps +specified in this list are usually assembled from the components stored in the +rest of the database and typically represent the most commonly used keymaps for +a particular system. +</para> + + +<para> +XKB defines no hints that are specific to complete keymaps. +</para> +</sect1> +</chapter> diff --git a/specs/ch14.xml b/specs/ch14.xml new file mode 100644 index 0000000..98bde5d --- /dev/null +++ b/specs/ch14.xml @@ -0,0 +1,94 @@ +<chapter id='replacing_the_keyboard_on_the_fly'> +<title>Replacing the Keyboard "On-the-Fly"</title> + +<para> +XKB supports the <emphasis> +XkbNewKeyboardNotify</emphasis> + event, which reports a change in keyboard geometry or the range of supported +keycodes. The server can generate an <emphasis> +XkbNewKeyboardNotify</emphasis> + event when it detects a new keyboard, or in response to an <emphasis> +XkbGetKeyboardByName</emphasis> + request (see <ulink url="XKBproto.htm#50332257_13490">See Using the Server’s +Database of Keyboard Components</ulink>) which loads a new keyboard description. +</para> + + +<para> +When a client opens a connection to the X server, the server reports the +minimum and maximum keycodes. If the range of supported keycodes is changed, +XKB keeps track of the minimum and maximum keycodes that were reported to each +client and filters out any events that fall outside of that range. Note that +these events are simply ignored; they are not delivered to some other client. +</para> + + +<para> +When the server sends an <emphasis> +XkbNewKeyboardNotify</emphasis> + event to a client to inform it of the new keycode range, XKB resets the stored +range of legal keycodes to the keycode range reported in the event. Non-XKB +clients and XKB-aware clients that do not request <emphasis> +XkbNewKeyboardNotify</emphasis> + events never receive events from keys that fall outside of the legal range +that XKB maintains for that client. +</para> + + +<para> +When a client requests <emphasis> +XkbNewKeyboardNotify</emphasis> + 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 that client an <emphasis> +XkbNewKeyboardNotify</emphasis> + event. Even if the "new" keyboard is not new to the server, it is new to this +particular client. +</para> + + +<para> +In addition to filtering out-of-range key events, XKB: +</para> + +<itemizedlist> +<listitem> + <para>Adjusts core protocol <emphasis> +MappingNotify</emphasis> + events to refer only to keys that match the stored legal range. + </para> +</listitem> +<listitem> + <para>Reports keyboard mappings for keys that match the stored legal range to +clients that issue a core protocol <emphasis> +GetKeyboardMapping</emphasis> + request. + </para> +</listitem> +<listitem> + <para>Reports modifier mappings only for keys that match the stored legal +range to clients that issue a core protocol <emphasis> +GetModifierMapping</emphasis> + request. + </para> +</listitem> +<listitem> + <para>Restricts the core protocol <emphasis> +ChangeKeyboardMapping</emphasis> + and <emphasis> +SetModifierMapping</emphasis> + requests to keys that fall inside the stored legal range. + </para> +</listitem> +</itemizedlist> + +<para> +In short, XKB does everything possible to hide the fact that the range of legal +keycodes has changed from clients non-XKB clients, which cannot be expected to +deal with it. The corresponding XKB events and requests do <emphasis> +not</emphasis> + pay attention to the legal keycode range in the same way because XKB makes it +possible for clients to track changes to the keycode range for a device and +respond to them. +</para> +</chapter> diff --git a/specs/ch15.xml b/specs/ch15.xml new file mode 100644 index 0000000..fb9472f --- /dev/null +++ b/specs/ch15.xml @@ -0,0 +1,232 @@ +<chapter id='interactions_between_xkb_and_the_x_input_extension'> +<title>Interactions Between XKB and the X Input Extension</title> + +<para> +All XKB interactions with the input extension are optional; implementors are +free to restrict the effects of the X Keyboard Extension to the core keyboard +device. The <emphasis> +XkbGetExtensionDeviceInfo</emphasis> + request reports whether or not an XKB implementation supports a particular +capability for input extension devices. +</para> + + +<para> +XKB recognizes the following interactions with the X Input Extension: +</para> + +<informaltable frame='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Name</entry> + <entry>Capability</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>XI_Keyboards</entry> + <entry>If set, applications can use all XKB requests and events with +extension keyboards.</entry> + </row> + <row rowsep='0'> + <entry>XI_ButtonActions</entry> + <entry>If set, clients can assign key actions to buttons, even on input +extension devices that are not keyboards.</entry> + </row> + <row rowsep='0'> + <entry>XI_IndicatorNames</entry> + <entry>If set, clients can assign names to indicators on non-keyboard +extension devices.</entry> + </row> + <row rowsep='0'> + <entry>XI_IndicatorMaps</entry> + <entry>If set, clients can assign indicator maps to indicators on +non-keyboard extension devices. </entry> + </row> + <row rowsep='0'> + <entry>XI_IndicatorState</entry> + <entry>If set, clients can change the state of device indicators using the +<emphasis> +XkbSetExtensionDeviceInfo</emphasis> + request.</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +Attempts to use an XKB feature with an extension device fail with a <emphasis> +Keyboard</emphasis> + error if the server does not support the <emphasis> +XkbXI_Keyboards</emphasis> + optional feature. If a capability particular capability other than <emphasis> +XkbXI_Keyboards</emphasis> + is not supported, attempts to use it fail silently. The replies for most +requests that can use one of the other optional features include a field to +report whether or not the request was successful, but such requests do not +cause an error condition. +</para> + + +<para> +Clients can also request an <emphasis> +XkbExtensionDeviceNotify</emphasis> + event. This event notifies interested clients of changes to any of the +supported XKB features for extension devices, or if a request from the client +that is receiving the event attempted to use an unsupported feature. +</para> + +<sect1 id='using_xkb_functions_with_input_extension_keyboards'> +<title>Using XKB Functions with Input Extension Keyboards</title> + +<para> +All XKB requests and events include a device identifier which can refer to an +input extension <emphasis> +KeyClass</emphasis> + device, if the implementation allows XKB to control extension devices. If the +implementation does not support XKB manipulation of extension devices, the +device identifier is ignored but it must be either <emphasis> +0</emphasis> + or <emphasis> +UseCoreKbd</emphasis> +. +</para> + + +<para> +Implementations which do not support the use of XKB functions with extension +keyboards must not set the <emphasis> +XkbXI_Keyboards</emphasis> + flag. Attempts to use XKB features on an extension keyboard with an +implementation that does not support this feature yield a <emphasis> +Keyboard</emphasis> + error. +</para> + + +</sect1> +<sect1 id='pointer_and_device_button_actions'> +<title>Pointer and Device Button Actions</title> + +<para> +The XKB extension optionally allows clients to assign any key action (see +<ulink url="XKBproto.htm#50332257_15763">See Key Actions</ulink>) to 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. +</para> + + +<para> +XKB implementations are required to support actions for the buttons of the core +pointer device, but support for actions on extension devices is optional. +Implementations which do not support button actions for extension devices must +not set the <emphasis> +XkbXI_ButtonActions</emphasis> + flag. +</para> + + +<para> +Attempts to query or assign button actions with an implementation that does not +support this feature report failure in the request reply and might cause the +server to send an <emphasis> +XkbExtensionDeviceNotify</emphasis> + event to the client which issued the request that failed. Such requests never +cause an error condition. +</para> + + +</sect1> +<sect1 id='indicator_maps_for_extension_devices'> +<title>Indicator Maps for Extension Devices</title> + +<para> +The XKB extension allows applications to assign indicator maps to the +indicators of non-keyboard extension devices. If supported, maps can be +assigned to all extension device indicators, whether they are part of a +keyboard feedback or part of an indicator feedback. +</para> + + +<para> +Implementations which do not support indicator maps for extension devices must +not set the <emphasis> +XkbXI_IndicatorMaps</emphasis> + flag. +</para> + + +<para> +Attempts to query or assign indicator maps with an implementation that does not +support this feature report failure in the request reply and might cause the +server to send an <emphasis> +XkbExtensionDeviceNotify</emphasis> + event to the client which issued the request that failed. Such requests never +cause an error condition. +</para> + + +<para> +If this feature is supported, the maps for the default indicators on the core +keyboard device are visible both as extension indicators and as the core +indicators. Changes made with <emphasis> +XkbSetDeviceInfo</emphasis> + are visible via <emphasis> +XkbGetIndicatorMap</emphasis> + and changes made with <emphasis> +XkbSetIndicatorMap</emphasis> + are visible via <emphasis> +XkbGetDeviceInfo</emphasis> +. +</para> + + +</sect1> +<sect1 id='indicator_names_for_extension_devices'> +<title>Indicator Names for Extension Devices</title> + +<para> +The XKB extension allows applications to assign symbolic names to the +indicators of non-keyboard extension devices. If supported, symbolic names can +be assigned to all extension device indicators, whether they are part of a +keyboard feedback or part of an indicator feedback. +</para> + + +<para> +Implementations which do not support indicator maps for extension devices must +not set the <emphasis> +XkbXI_IndicatorMaps</emphasis> + flag. +</para> + + +<para> +Attempts to query or assign indicator names with an implementation that does +not support this feature report failure in the request reply and might cause +the server to send an <emphasis> +XkbExtensionDeviceNotify</emphasis> + event to the client which issued the request that failed. Such requests never +cause an error condition. +</para> + + +<para> +If this feature is supported, the names for the default indicators on the core +keyboard device are visible both as extension indicators and as the core +indicators. Changes made with <emphasis> +XkbSetDeviceInfo</emphasis> + are visible via <emphasis> +XkbGetNames</emphasis> + and changes made with <emphasis> +XkbSetNames</emphasis> + are visible via <emphasis> +XkbGetDeviceInfo</emphasis> +. +</para> +</sect1> +</chapter> diff --git a/specs/ch16.xml b/specs/ch16.xml new file mode 100644 index 0000000..2ec152b --- /dev/null +++ b/specs/ch16.xml @@ -0,0 +1,9378 @@ + +<chapter id='xkb_protocol_requests'> +<title>XKB Protocol Requests</title> + +<para> +This document uses the syntactic conventions and common types defined by the +specification of the core X protocol with a number of additions, which are +detailed below. +</para> + +<sect1 id='errors'> +<title>Errors</title> + +<para> +If a client attempts to use any other XKB request except <emphasis> +XkbUseExtension</emphasis> + before the extension is properly initialized, XKB reports an <emphasis> +Access</emphasis> + error and ignores the request. XKB is properly initialized once <emphasis> +XkbUseExtension</emphasis> + reports that the client has asked for a supported or compatible version of the +extension. +</para> + + +<sect2 id='keyboard_errors'> +<title>Keyboard Errors</title> + +<para> +In addition to all of the errors defined by the core protocol, the X Keyboard +Extension defines a single error, <emphasis> +Keyboard</emphasis> +, which indicates that some request specified an illegal device identifier or +an extension device that is not a member of an appropriate. Unless otherwise +noted, any request with an argument of type KB_DEVICESPEC can cause <emphasis> +Keyboard</emphasis> + errors if an illegal or inappropriate device is specified. +</para> + + +<para> +When the extension reports a Keyboard error, the most significant byte of the +<emphasis> +resource_id</emphasis> + is a further refinement of the error cause, as defined in the table below. The +least significant byte contains the device, class, or feedback id as indicated: +</para> + +<informaltable frame='none'> +<tgroup cols='4'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>high-order byte</entry> + <entry>value</entry> + <entry>meaning</entry> + <entry>low-order byte</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>XkbErr_BadDevice</entry> + <entry>0xff</entry> + <entry>device not found</entry> + <entry>device id</entry> + </row> + <row rowsep='0'> + <entry>XkbErr_BadClass</entry> + <entry>0xfe</entry> + <entry>device found, but is the wrong class</entry> + <entry>class id</entry> + </row> + <row rowsep='0'> + <entry>XkbErr_BadId</entry> + <entry>0xfd</entry> + <entry>device found, class ok, but device does not have a feedback with the +indicated id</entry> + <entry>feedback id</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +</sect2> +<sect2 id='side_effects_of_errors'> +<title>Side-Effects of Errors</title> + +<para> +With the exception of <emphasis> +Alloc</emphasis> + or <emphasis> +Implementation</emphasis> + errors, which might result in an inconsistent internal state, no XKB request +that reports an error condition has any effect. Unless otherwise stated, +requests which update some aspect of the keyboard description will not apply +only part of a request — if part of a request fails, the whole thing is +ignored. +</para> + + +</sect2> +</sect1> +<sect1 id='common_types'> +<title>Common Types</title> + +<para> +The following types are used in the request and event definitions in subsequent +sections: +</para> + +<informaltable frame='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Name</entry> + <entry>Value</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>LISTofITEMs</entry> + <entry> The type LISTofITEMs is special. It is similar to the +LISTofVALUE defined by the core protocol, but the elements of a LISTofITEMs are +not necessarily all the same size. The use of a BITMASK to indicate which +members are present is optional for a LISTofITEMs — it is possible for the +set of elements to be derived from one or more fields of the request.</entry> + </row> + <row rowsep='0'> + <entry>KB_DEVICESPEC</entry> + <entry>8 bit unsigned integer, <emphasis> +UseCoreKbd, or UseCorePtr</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry>KB_LEDCLASSSPEC</entry> + <entry>{ <emphasis> +KbdFeedbackClass</emphasis> +, <emphasis> +LedFeedbackClass</emphasis> +, <emphasis> +DfltXIClass</emphasis> +, <emphasis> +AllXIClasses</emphasis> +, <emphasis> +XINone</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_BELLCLASSSPEC</entry> + <entry>{ <emphasis> +KbdFeedbackClass</emphasis> +, <emphasis> +BellFeedbackClass</emphasis> +, <emphasis> +DfltXIClass</emphasis> +, <emphasis> +AllXIClasses</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_IDSPEC</entry> + <entry>8 bit unsigned integer or <emphasis> +DfltXIId</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry>KB_VMODMASK</entry> + <entry> CARD16, each bit corresponds to a virtual modifier</entry> + </row> + <row rowsep='0'> + <entry>KB_GROUPMASK</entry> + <entry>{ <emphasis> +Group1</emphasis> +, <emphasis> +Group2</emphasis> +, <emphasis> +Group3</emphasis> +, <emphasis> +Group4</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_GROUPSWRAP</entry> + <entry>{ <emphasis> +WrapIntoRange</emphasis> +, <emphasis> +ClampIntoRange</emphasis> +, <emphasis> +RedirectIntoRange</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_GROUPINFO</entry> + <entry>{ groupsWrap: KB_GROUPSWRAP +redirectGroup: 1…4, +numGroups: 1…4 }</entry> + </row> + <row rowsep='0'> + <entry>KB_NKNDETAILSMASK</entry> + <entry>{ <emphasis> +NKN_Keycodes</emphasis> +, NKN_Geometry, <emphasis> +NKN_DeviceID</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_STATEMASK</entry> + <entry> KEYBUTMASK or KB_GROUPMASK</entry> + </row> + <row rowsep='0'> + <entry>KB_STATEPARTMASK</entry> + <entry>{ <emphasis> +ModifierState</emphasis> +, <emphasis> +ModifierBase</emphasis> +, <emphasis> +ModifierLatch</emphasis> +, <emphasis> +ModifierLock</emphasis> +, <emphasis> +GroupState</emphasis> +, <emphasis> +GroupBase</emphasis> +, <emphasis> +GroupLatch</emphasis> +, <emphasis> +GroupLock</emphasis> +, <emphasis> +CompatState</emphasis> +, <emphasis> +GrabMods</emphasis> +, <emphasis> +CompatGrabMods</emphasis> +, <emphasis> +LookupMods</emphasis> +, <emphasis> +CompatLookupMods</emphasis> +, <emphasis> +PointerButtons</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_BOOLCTRLMASK</entry> + <entry>{ <emphasis> +RepeatKeys</emphasis> +, <emphasis> +SlowKeys</emphasis> +, <emphasis> +BounceKeys</emphasis> +, <emphasis> +StickyKeys</emphasis> +, <emphasis> +MouseKeys</emphasis> +, <emphasis> +MouseKeysAccel</emphasis> +, <emphasis> +AccessXKeys</emphasis> +, <emphasis> +AccessXTimeout</emphasis> +, <emphasis> +AccessXFeedback</emphasis> +, <emphasis> +AudibleBell</emphasis> +, <emphasis> +Overlay1</emphasis> +, <emphasis> +Overlay2</emphasis> +, <emphasis> +IgnoreGroupLock</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_CONTROLSMASK</entry> + <entry>{ <emphasis> +GroupsWrap, InternalMods</emphasis> +, <emphasis> +IgnoreLockMods</emphasis> +, <emphasis> +PerKeyRepeat</emphasis> +, <emphasis> +ControlsEnabled</emphasis> + } or KB_BOOLCTRLMASK</entry> + </row> + <row rowsep='0'> + <entry>KB_MAPPARTMASK</entry> + <entry>{ <emphasis> +KeyTypes</emphasis> +, <emphasis> +KeySyms</emphasis> +, <emphasis> +ModifierMap</emphasis> +, <emphasis> +ExplicitComponents</emphasis> +, <emphasis> +KeyActions</emphasis> +, <emphasis> +KeyBehaviors</emphasis> +, <emphasis> +VirtualMods</emphasis> +, <emphasis> +VirtualModMap</emphasis> +}</entry> + </row> + <row rowsep='0'> + <entry>KB_CMDETAILMASK</entry> + <entry>{ <emphasis> +SymInterp</emphasis> +, <emphasis> +GroupCompat</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_NAMEDETAILMASK</entry> + <entry>{ <emphasis> +KeycodesName</emphasis> +, <emphasis> +GeometryName</emphasis> +, <emphasis> +SymbolsName</emphasis> +, + <emphasis> +PhysSymbolsName</emphasis> +, <emphasis> +TypesName</emphasis> +, <emphasis> +CompatName</emphasis> +, <emphasis> +KeyTypeNames</emphasis> +, <emphasis> +KTLevelNames</emphasis> +, <emphasis> +IndicatorNames</emphasis> +, <emphasis> +KeyNames</emphasis> +, <emphasis> +KeyAliases</emphasis> +, <emphasis> +VirtualModNames</emphasis> +, <emphasis> +GroupNames</emphasis> +, <emphasis> +RGNames</emphasis> +}</entry> + </row> + <row rowsep='0'> + <entry>KB_AXNDETAILMASK</entry> + <entry>{ <emphasis> +AXN_SKPress</emphasis> +, <emphasis> +AXN_SKAccept</emphasis> +, <emphasis> +AXN_SKReject</emphasis> +, <emphasis> +AXN_SKRelease, AXN_BKAccept, AXN_BKReject, AXN_AXKWarning </emphasis> +}</entry> + </row> + <row rowsep='0'> + <entry>KB_AXSKOPTSMASK</entry> + <entry>{ <emphasis> +AX_TwoKeys</emphasis> +, <emphasis> +AX_LatchToLock</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_AXFBOPTSMASK</entry> + <entry>{ <emphasis> +AX_SKPressFB</emphasis> +, <emphasis> +AX_SKAcceptFB</emphasis> +, <emphasis> +AX_FeatureFB</emphasis> +, <emphasis> +AX_SlowWarnFB</emphasis> +, <emphasis> +AX_IndicatorFB</emphasis> +, <emphasis> +AX_StickyKeysFB</emphasis> +, <emphasis> +AX_SKReleaseFB</emphasis> +,<emphasis> + AX_SKRejectFB</emphasis> +, <emphasis> +AX_BKRejectFB</emphasis> +, <emphasis> +AX_DumbBellFB</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_AXOPTIONSMASK</entry> + <entry> KB_AXFBOPTSMASK or KB_AXSKOPTSMASK</entry> + </row> + <row rowsep='0'> + <entry>KB_GBNDETAILMASK</entry> + <entry>{ <emphasis> +GBN_Types</emphasis> +, <emphasis> +GBN_CompatMap</emphasis> +, <emphasis> +GBN_ClientSymbols</emphasis> +, <emphasis> +GBN_ServerSymbols</emphasis> +, <emphasis> +GBN_IndicatorMap</emphasis> +, <emphasis> +GBN_KeyNames</emphasis> +, <emphasis> +GBN_Geometry</emphasis> +, <emphasis> +GBN_OtherNames</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_BELLDETAILMASK</entry> + <entry>{ <emphasis> +XkbAllBellNotifyEvents</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_MSGDETAILMASK</entry> + <entry>{ <emphasis> +XkbAllActionMessages</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_EVENTTYPE</entry> + <entry>{ <emphasis> +XkbNewKeyboardNotify</emphasis> +, <emphasis> +XkbMapNotify</emphasis> +, <emphasis> +XkbStateNotify</emphasis> +, <emphasis> +XkbControlsNotify</emphasis> +, <emphasis> +XkbIndicatorStateNotify</emphasis> +, <emphasis> +XkbIndicatorMapNotify</emphasis> +, <emphasis> +XkbNamesNotify</emphasis> +, <emphasis> +XkbCompatMapNotify</emphasis> +, <emphasis> +XkbBellNotify</emphasis> +, <emphasis> +XkbActionMessage</emphasis> +, <emphasis> +XkbAccessXNotify</emphasis> +, <emphasis> +XkbExtensionDeviceNotify</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_ACTION</entry> + <entry>[ type: CARD8 +data: LISTofCARD8 ]</entry> + </row> + <row rowsep='0'> + <entry>KB_BEHAVIOR</entry> + <entry>[ type: CARD8, data: CARD 8 ]</entry> + </row> + <row rowsep='0'> + <entry>KB_MODDEF</entry> + <entry>[ mask: KEYMASK, +mods: KEYMASK, +vmods: KB_VMODMASK ]</entry> + </row> + <row rowsep='0'> + <entry>KB_KTMAPENTRY</entry> + <entry>[ active: BOOL, +level: CARD8, +mods: KB_MODDEF ]</entry> + </row> + <row rowsep='0'> + <entry>KB_KTSETMAPENTRY</entry> + <entry>[ level: CARD8, +mods: KB_MODDEF ]</entry> + </row> + <row rowsep='0'> + <entry>KB_KEYTYPE</entry> + <entry>[ mods: KB_MODDEF, +numLevels: CARD8, +map: LISTofKB_KTMAPENTRY, +preserve: LISTofKB_MODDEF ]</entry> + </row> + <row rowsep='0'> + <entry>KB_SETKEYTYPE</entry> + <entry>[ realMods: KEYMASK, +vmods: CARD16, +numLevels: CARD8, +map: LISTofKB_KTSETMAPENTRY, +preserve: LISTofKB_MODDEF ]</entry> + </row> + <row rowsep='0'> + <entry>KB_KEYSYMMAP</entry> + <entry>[ ktIndex: LISTofCARD8, width: CARD8 + numGroups: 0…4, + groupsWrap: KB_GROUPSWRAP, + redirectGroup: 0…3, + syms: LISTofKEYSYM ]</entry> + </row> + <row rowsep='0'> + <entry>KB_KEYVMODMAP</entry> + <entry>[ key: KEYCODE, vmods: CARD16 ]</entry> + </row> + <row rowsep='0'> + <entry>KB_KEYMODMAP</entry> + <entry>[ key: KEYCODE, mods: KEYMASK ]</entry> + </row> + <row rowsep='0'> + <entry>KB_EXPLICITMASK</entry> + <entry>{ <emphasis> +ExplicitKeyType1</emphasis> +, <emphasis> +ExplicitKeyType2</emphasis> +, <emphasis> +ExplicitKeyType3</emphasis> +, <emphasis> +ExplicitKeyType4</emphasis> +, <emphasis> +ExplicitInterpret</emphasis> +, <emphasis> +ExplicitAutoRepeat</emphasis> +, <emphasis> +ExplicitBehavior</emphasis> +, <emphasis> +ExplicitVModMap</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_INDICATORMASK</entry> + <entry> CARD32, each bit corresponds to an indicator</entry> + </row> + <row rowsep='0'> + <entry>KB_IMFLAGS</entry> + <entry>{ <emphasis> +IM_NoExplicit</emphasis> +, <emphasis> +IM_NoAutomatic</emphasis> +, <emphasis> +IM_LEDDrivesKB</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_IMMODSWHICH</entry> + <entry>{ <emphasis> +IM_UseNone</emphasis> +, <emphasis> +IM_UseBase</emphasis> +, <emphasis> +IM_UseLatched</emphasis> +, <emphasis> +IM_UseLocked</emphasis> +, <emphasis> +IM_UseEffective</emphasis> +, <emphasis> +IM_UseCompat</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_IMGROUPSWHICH</entry> + <entry>{ <emphasis> +IM_UseNone</emphasis> +, <emphasis> +IM_UseBase</emphasis> +, <emphasis> +IM_UseLatched</emphasis> +, <emphasis> +IM_UseLocked</emphasis> +, <emphasis> +IM_UseEffective</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_INDICATORMAP</entry> + <entry>[ flags: CARD8, +mods: KB_MODDEF, +whichMods: +groups: KB_GROUPMASK, +whichGroups: +ctrls: KB_BOOLCTRLMASK ]</entry> + </row> + <row rowsep='0'> + <entry>KB_SYMINTERPMATCH</entry> + <entry>{ <emphasis> +SI_NoneOf</emphasis> +, <emphasis> +SI_AnyOfOrNone</emphasis> +, <emphasis> +SI_AnyOf</emphasis> +, <emphasis> +SI_AllOf</emphasis> +, <emphasis> +SI_Exactly</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_SYMINTERP</entry> + <entry>[ sym: KEYSYM, + mods; KEYMASK, + levelOneOnly: BOOL, + match: KB_SYMINTERPMATCH, + virtualMod: CARD8, + autoRepeat: BOOL, + lockingKey: BOOL ]</entry> + </row> + <row rowsep='0'> + <entry>KB_PCFMASK</entry> + <entry>{ <emphasis> +PCF_DetectableAutorepeat</emphasis> +, <emphasis> +PCF_GrabsUseXkbState</emphasis> +, <emphasis> +PCF_AutoResetControls</emphasis> +, <emphasis> +PCF_LookupStateWhenGrabbed</emphasis> +, <emphasis> +PCF_SendEventUsesXKBState</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_LCFLAGSMASK</entry> + <entry>{ <emphasis> +LC_Hidden</emphasis> +, <emphasis> +LC_Default</emphasis> +, <emphasis> +LC_Partial</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_LCSYMFLAGSMASK</entry> + <entry>{ <emphasis> +LC_AlphanumericKeys</emphasis> +, <emphasis> +LC_ModifierKeys</emphasis> +, <emphasis> +LC_KeypadKeys</emphasis> +, <emphasis> +LC_FunctionKeys</emphasis> +, <emphasis> +LC_AlternateGroup</emphasis> + }</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +These types are used by the <emphasis> +XkbGetGeometry</emphasis> + and <emphasis> +XkbSetGeometry</emphasis> + requests: +</para> + +<informaltable frame='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Name</entry> + <entry>Value</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>KB_PROPERTY</entry> + <entry>[ name, value: STRING8 ]</entry> + </row> + <row rowsep='0'> + <entry>KB_POINT</entry> + <entry>[ x, y: CARD16 ]</entry> + </row> + <row rowsep='0'> + <entry>KB_OUTLINE</entry> + <entry>[ cornerRadius: CARD8, points: LISTofKB_POINT ]</entry> + </row> + <row rowsep='0'> + <entry>KB_SHAPE</entry> + <entry>[ name: ATOM, outlines: LISTofKB_OUTLINE + primaryNdx, approxNdx: CARD8 ]</entry> + </row> + <row rowsep='0'> + <entry>KB_KEYNAME</entry> + <entry>[ name: LISTofCHAR ]</entry> + </row> + <row rowsep='0'> + <entry>KB_KEYALIAS</entry> + <entry>[ real: LISTofCHAR, alias: LISTofCHAR ]</entry> + </row> + <row rowsep='0'> + <entry>KB_KEY</entry> + <entry>[ name: KB_KEYNAME, gap: INT16, + shapeNdx, colorNdx: CARD8 ]</entry> + </row> + <row rowsep='0'> + <entry>KB_ROW</entry> + <entry>[ top, left: INT16, vertical: BOOL, keys LISTofKB_KEY ]</entry> + </row> + <row rowsep='0'> + <entry>KB_OVERLAYKEY</entry> + <entry>[ over, under: KB_KEYNAME ]</entry> + </row> + <row rowsep='0'> + <entry>KB_OVERLAYROW</entry> + <entry>[ rowUnder: CARD8, keys: LISTofKB_OVERLAYKEY ]</entry> + </row> + <row rowsep='0'> + <entry>KB_OVERLAY</entry> + <entry>[ sectionUnder: CARD8, +rows: LISTofKB_OVERLAYROW ]</entry> + </row> + <row rowsep='0'> + <entry>KB_SHAPEDOODAD</entry> + <entry>[ name: ATOM, priority: CARD8, top, left: INT16, + type: { SolidDoodad, OutlineDoodad }, + angle: INT16, width, height: CARD16 + colorNdx, shapeNdx: CARD8 ]</entry> + </row> + <row rowsep='0'> + <entry>KB_TEXTDOODAD</entry> + <entry>[ name: ATOM, priority: CARD8, top, left: INT16, + angle: INT16, width, height: CARD16, + colorNdx: CARD8, text: STRING8, font: STRING8 ]</entry> + </row> + <row rowsep='0'> + <entry>KB_INDICATORDOODAD</entry> + <entry>[ name: ATOM, priority: CARD8, top, left: INT16, +angle: INT16, +shapeNdx, onColorNdx, offColorNdx: CARD8 ]</entry> + </row> + <row rowsep='0'> + <entry>KB_LOGODOODAD</entry> + <entry>[ name: ATOM, priority: CARD8, top, left: INT16, + angle: INT16, colorNdx, shapeNdx: CARD8, + logoName: STRING8 ]</entry> + </row> + <row rowsep='0'> + <entry>KB_DOODAD</entry> + <entry>KB_SHAPEDOODAD, or KB_TEXTDOODAD, or KB_INDICATORDOODAD, or +KB_LOGODOODAD</entry> + </row> + <row rowsep='0'> + <entry>KB_SECTION</entry> + <entry>[ name: ATOM, + top, left, angle: INT16, + width, height: CARD16, + priority: CARD8, + rows: LISTofKB_ROW, + doodads: LISTofKB_DOODAD, + overlays: LISTofKB_OVERLAY ]</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +These types are used by <emphasis> +XkbGetDeviceInfo</emphasis> + and <emphasis> +XkbSetDeviceInfo</emphasis> +: +</para> + +<informaltable frame='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Name</entry> + <entry>Value</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>KB_XIDEVFEATUREMASK</entry> + <entry>{ <emphasis> +XI_ButtonActions</emphasis> +, <emphasis> +XI_IndicatorNames</emphasis> +, <emphasis> +XI_IndicatorMaps</emphasis> +, <emphasis> +XI_IndicatorState</emphasis> + }</entry> + </row> + <row rowsep='0'> + <entry>KB_XIFEATUREMASK</entry> + <entry>{ KB_XIDEVFEATURES or <emphasis> +XI_Keyboards</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry>KB_XIDETAILMASK</entry> + <entry> { KB_XIFEATURES or <emphasis> +XI_UnsupportedFeature</emphasis> + <emphasis> +}</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry>KB_DEVICELEDINFO</entry> + <entry>[ ledClass: KB_LEDCLASSSPEC, +ledID: KB_IDSPEC, +physIndicators: CARD32, +state: CARD32, +names: LISTofATOM, +maps: LISTofKB_INDICATORMAP ]</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +</sect1> +<sect1 id='requests'> +<title>Requests</title> + +<para> +This section lists all of the requests supported by the X Keyboard Extension, +separated into categories of related requests. +</para> + + +<sect2 id='initializing_the_x_keyboard_extension'> +<title>Initializing the X Keyboard Extension</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbUseExtension</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>wantedMajor, wantedMinor: CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +supported: BOOL + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +serverMajor, serverMinor: CARD16</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +This request enables XKB extension capabilities for the client that issues the +request; the <emphasis> +wantedMajor</emphasis> + and <emphasis> +wantedMinor</emphasis> + fields specify the extension version in use by the requesting client. The +<emphasis> +supported</emphasis> + field is <emphasis> +True</emphasis> + if the server supports a compatible version, <emphasis> +False</emphasis> + otherwise. The <emphasis> +serverMajor</emphasis> + and <emphasis> +serverMinor</emphasis> + fields return the actual version supported by the server. +</para> + + +<para> +Until a client explicitly and successfully requests the XKB extension, an XKB +capable server reports compatibility state in all core protocol events and +requests. Once a client asks for XKB extension semantics by issuing this +request, the server reports the extended XKB keyboard state in some core +protocol events and requests, as described in the overview section of this +specification. +</para> + + +<para> +Clients should issue an <emphasis> +XkbUseExtension</emphasis> + request before using any other extension requests. +</para> + + +</sect2> +<sect2 id='selecting_events'> +<title>Selecting Events</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbSelectEvents</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +affectWhich, clear, selectAll: KB_EVENTTYPE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +affectMap, map: KB_MAPPARTMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +details: LISTofITEMs</entry> + </row> + + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +, <emphasis> +Match</emphasis> +, <emphasis> +Value</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +This request updates the event masks of the keyboard indicated by <emphasis> +deviceSpec</emphasis> + for this client. If <emphasis> +deviceSpec</emphasis> + specifies an illegal device, a <emphasis> +Keyboard</emphasis> + error results. +</para> + + +<para> +The <emphasis> +affectMap</emphasis> + and <emphasis> +map</emphasis> + fields specify changes to the event details mask for the <emphasis> +XkbMapNotify</emphasis> + event. If any map components are set in <emphasis> +map</emphasis> + but not in <emphasis> +affectMap</emphasis> +, a <emphasis> +Match</emphasis> + error results. Otherwise, any map components that are set in <emphasis> +affectMap</emphasis> + are set or cleared in the map notify details mask, depending on the value of +the corresponding field in <emphasis> +map</emphasis> +. +</para> + + +<para> +The <emphasis> +affectWhich</emphasis> +, <emphasis> +clear</emphasis> +, and <emphasis> +selectAll</emphasis> + fields specify changes to any other event details masks. If any event types +are set in both <emphasis> +clear</emphasis> + and <emphasis> +selectAll</emphasis> +, a <emphasis> +Match</emphasis> + error results; if any event types are specified in either <emphasis> +clear</emphasis> + or <emphasis> +selectAll</emphasis> + but not in <emphasis> +affectWhich</emphasis> +, a <emphasis> +Match</emphasis> + error results. Otherwise, the detail masks for any event types specified in +the <emphasis> +affectWhich</emphasis> + field of this request are changed as follows: +</para> + +<itemizedlist> +<listitem> + <para>If the event type is also set in <emphasis> +clear</emphasis> +, the detail mask for the corresponding event is set to <emphasis> +0</emphasis> + or <emphasis> +False</emphasis> +, as appropriate. + </para> +</listitem> +<listitem> + <para>If the event type is also set in <emphasis> +selectAll</emphasis> +, the detail mask for the corresponding event is set to include all legal +detail values for that type. + </para> +</listitem> +<listitem> + <para>If the event type is not set in either <emphasis> +clear</emphasis> + or <emphasis> +selectAll</emphasis> +, the corresponding element of <emphasis> +details</emphasis> + lists a set of explicit changes to the details mask for the event, as +described below. + </para> +</listitem> +</itemizedlist> + +<para> +Each entry of the <emphasis> +details</emphasis> + list specifies changes to the event details mask for a single type of event, +and consists of an <emphasis> +affects</emphasis> + mask and a <emphasis> +values</emphasis> + mask. All details that are specified in <emphasis> +affects</emphasis> + are set to the corresponding value from <emphasis> +values</emphasis> +; if any details are listed in <emphasis> +values</emphasis> + but not in <emphasis> +affects</emphasis> +, a <emphasis> +Match</emphasis> + error results. +</para> + + +<para> +The details list contains entries only for those event types, if any, that are +listed in the <emphasis> +affectWhich</emphasis> + mask and not in either <emphasis> +clear</emphasis> + or <emphasis> +selectAll</emphasis> +. When present, the items of the <emphasis> +details</emphasis> + list appear in the following order: +</para> + +<informaltable frame='none'> +<tgroup cols='3'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Event Type</entry> + <entry>Legal Details</entry> + <entry>Type</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis> +XkbNewKeyboardNotify</emphasis> +</entry> + <entry><emphasis> +KB_NKNDETAILSMASK</emphasis> +</entry> + <entry><emphasis> +CARD16</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbStateNotify</emphasis> +</entry> + <entry><emphasis> +KB_STATEPARTMASK</emphasis> +</entry> + <entry><emphasis> +CARD16</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbControlsNotify</emphasis> +</entry> + <entry><emphasis> +KB_CONTROLMASK</emphasis> +</entry> + <entry><emphasis> +CARD32</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbIndicatorMapNotify</emphasis> +</entry> + <entry><emphasis> +KB_INDICATORMASK</emphasis> +</entry> + <entry><emphasis> +CARD32</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbIndicatorStateNotify</emphasis> +</entry> + <entry><emphasis> +KB_INDICATORMASK</emphasis> +</entry> + <entry><emphasis> +CARD32</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbNamesNotify</emphasis> +</entry> + <entry><emphasis> +KB_NAMEDETAILMASK</emphasis> +</entry> + <entry><emphasis> +CARD16</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbCompatMapNotify</emphasis> +</entry> + <entry><emphasis> +KB_CMDETAILMASK</emphasis> +</entry> + <entry><emphasis> +CARD8</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbBellNotify</emphasis> +</entry> + <entry><emphasis> +KB_BELLDETAILMASK</emphasis> +</entry> + <entry><emphasis> +CARD8</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbActionMessage</emphasis> +</entry> + <entry><emphasis> +KB_MSGDETAILMASK</emphasis> +</entry> + <entry><emphasis> +CARD8</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbAccessXNotify</emphasis> +</entry> + <entry><emphasis> +KB_AXNDETAILMASK</emphasis> +</entry> + <entry><emphasis> +CARD16</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbExtensionDeviceNotify</emphasis> +</entry> + <entry><emphasis> +KB_XIDETAILMASK</emphasis> +</entry> + <entry><emphasis> +CARD16</emphasis> +</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +Detail masks for event types that are not specified in <emphasis> +affectWhich</emphasis> + are not changed. +</para> + + +<para> +If any components are specified in a client’s event masks, the X server sends +the client an appropriate event whenever any of those components change state. +Unless explicitly modified, all event detail masks are empty. <ulink +url="XKBproto.htm#50332257_22322">See Events</ulink> describes all XKB events +and the conditions under which the server generates them. +</para> + + +</sect2> +<sect2 id='generating_named_keyboard_bells'> +<title>Generating Named Keyboard Bells</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbBell</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +bellClass: KB_BELLCLASSSPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +bellID: KB_IDSPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +percent: INT8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +forceSound: BOOL</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +eventOnly: BOOL</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +pitch, duration: INT16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +name: ATOM</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +window: WINDOW</entry> + </row> + + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +, <emphasis> +Value</emphasis> +, <emphasis> +Match</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +This request generates audible bells and/or <emphasis> +XkbBellNotify</emphasis> + events for the bell specified by the <emphasis> +bellClass</emphasis> + and <emphasis> +bellID</emphasis> + on the device specified by <emphasis> +deviceSpec</emphasis> + at the specified <emphasis> +pitch</emphasis> +, <emphasis> +duration</emphasis> + and volume (<emphasis> +percent</emphasis> +). If deviceSpec specifies a device that does not have a bell or keyboard +feedback, a <emphasis> +Keyboard</emphasis> + error results. +</para> + + +<para> +If both <emphasis> +forceSound</emphasis> + and <emphasis> +eventOnly</emphasis> + are set, this request yields a <emphasis> +Match</emphasis> + error. Otherwise, if <emphasis> +forceSound</emphasis> + is <emphasis> +True</emphasis> +, this request always generates a sound and never generates an event; if +<emphasis> +eventOnly</emphasis> + is <emphasis> +True</emphasis> +, it causes an event but no sound. If neither <emphasis> +forceSound</emphasis> + nor <emphasis> +eventOnly</emphasis> + are <emphasis> +True</emphasis> +, this request always generates an event; if the keyboard’s global <emphasis> +AudibleBell</emphasis> + control is enabled, it also generates a sound. +</para> + + +<para> +Any bell event generated by this request contains all of the information about +the bell that was requested, including the symbolic name specified by <emphasis> +name</emphasis> + and the event window specified by window. The <emphasis> +name</emphasis> + and <emphasis> +window</emphasis> + are not directly interpreted by XKB, but they must have the value <emphasis> +None</emphasis> + or specify a legal Atom or Window, respectively. <emphasis> +XkbBellNotify</emphasis> + events generated in response to core protocol or X input extension bell +requests always report <emphasis> +None</emphasis> + as their <emphasis> +name</emphasis> +. +</para> + + +<para> +The <emphasis> +bellClass</emphasis> +, <emphasis> +bellID</emphasis> +, and <emphasis> +percent</emphasis> + fields are interpreted as for the X input extension <emphasis> +DeviceBell</emphasis> + request. If <emphasis> +pitch</emphasis> + and <emphasis> +duration</emphasis> + are zero, the server uses the corresponding values for that bell from the core +protocol or input extension, otherwise <emphasis> +pitch</emphasis> + and <emphasis> +duration</emphasis> + are interpreted as for the core protocol <emphasis> +ChangeKeyboardControl</emphasis> + request; if they do not include legal values, a <emphasis> +Value</emphasis> + error results. The <emphasis> +window</emphasis> + field must specify a legal Window or have the value <emphasis> +None</emphasis> +, or a <emphasis> +Value</emphasis> + error results. The name field must specify a legal Atom or have the value +<emphasis> +None</emphasis> +, or an <emphasis> +Atom</emphasis> + error results. If an error occurs, this request has no other effect (i.e. does +not cause a sound or generate an event). +</para> + + +<para> +The <emphasis> +pitch</emphasis> +, <emphasis> +volume</emphasis> +, and <emphasis> +duration</emphasis> + are suggested values for the bell, but XKB does not require the server to +honor them. +</para> + + +</sect2> +<sect2 id='querying_and_changing_keyboard_state'> +<title>Querying and Changing Keyboard State</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbGetState</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +deviceID: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +mods, baseMods, latchedMods, lockedMods: KEYMASK + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +group, lockedGroup: KB_GROUP + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +baseGroup, latchedGroup: INT16 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +compatState: KEYMASK + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +grabMods, compatGrabMods: KB_GROUP + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +lookupMods, compatLookupMods: KEYMASK + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +ptrBtnState: BUTMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +This request returns a detailed description of the current state of the +keyboard specified by <emphasis> +deviceSpec</emphasis> +. +</para> + + +<para> +The <emphasis> +deviceID</emphasis> + return value contains the input extension identifier for the specified device, +or <emphasis> +0</emphasis> + if the server does not support the input extension. +</para> + + +<para> +The <emphasis> +baseMods</emphasis> + return value reports the modifiers that are set because one or more modifier +keys are logically down. The <emphasis> +latchedMods</emphasis> + and <emphasis> +lockedMods</emphasis> + return values report the modifiers that are latched or locked respectively. +The <emphasis> +mods</emphasis> + return value reports the effective modifier mask which results from the +current combination of base, latched and locked modifiers. +</para> + + +<para> +The <emphasis> +baseGroup</emphasis> + return value reports the group state selected by group shift keys that are +logically down. The <emphasis> +latchedGroup</emphasis> + and <emphasis> +lockedGroup</emphasis> + return values detail the effects of latching or locking group shift keys and +<emphasis> +XkbLatchLockState</emphasis> + requests. The <emphasis> +group</emphasis> + return value reports the effective keyboard group which results from the +current combination of base, latched and locked group values. +</para> + + +<para> +The <emphasis> +lookupMods</emphasis> + return value reports the lookup modifiers, which consist of the current +effective modifiers minus any server internal modifiers. The <emphasis> +grabMods</emphasis> + return value reports the grab modifiers, which consist of the lookup modifiers +minus any members of the ignore locks mask that are not either latched or +logically depressed. <ulink url="XKBproto.htm#50332257_13933">See Keyboard +State</ulink> describes the lookup modifiers and grab modifiers in more detail. +</para> + + +<para> +The <emphasis> +ptrBtnState</emphasis> + return value reports the current logical state of up to five buttons on the +core pointer device. +</para> + + +<para> +The <emphasis> +compatState</emphasis> + return value reports the compatibility state that corresponds to the effective +keyboard group and modifier state. The <emphasis> +compatLookupMods</emphasis> + and <emphasis> +compatGrabMods</emphasis> + return values report the core protocol compatibility states that correspond to +the XKB lookup and grab state. All of the compatibility states are computed by +applying the group compatibility mapping to the corresponding XKB modifier and +group states, as described in <ulink url="XKBproto.htm#50332257_40656">See +Group Compatibility Map</ulink>. +</para> + + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbLatchLockState</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +affectModLocks, modLocks: KEYMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +lockGroup: BOOL</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +groupLock: KB_GROUP</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +affectModLatches,modLatches: KEYMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +latchGroup: BOOL</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +groupLatch: INT16</entry> + </row> + + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +, <emphasis> +Value</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +This request locks or latches keyboard modifiers and group state for the device +specified by <emphasis> +deviceSpec</emphasis> +. If <emphasis> +deviceSpec</emphasis> + specifies an illegal or non-keyboard device, a <emphasis> +Keyboard</emphasis> + error occurs. +</para> + + +<para> +The locked state of any modifier specified in the <emphasis> +affectModLocks</emphasis> + mask is set to the corresponding value from <emphasis> +modLocks</emphasis> +. If <emphasis> +lockGroup</emphasis> + is <emphasis> +True</emphasis> +, the locked keyboard group is set to the group specified by <emphasis> +groupLock</emphasis> +. If any modifiers are set in <emphasis> +modLocks</emphasis> + but not <emphasis> +affectModLocks</emphasis> +, a <emphasis> +Match</emphasis> + error occurs. +</para> + + +<para> +The latched state of any modifier specified in the <emphasis> +affectModLatches</emphasis> + mask is set to the corresponding value from <emphasis> +modLatches</emphasis> +. If <emphasis> +latchGroup</emphasis> + is <emphasis> +True</emphasis> +, the latched keyboard group is set to the group specified by <emphasis> +groupLatch</emphasis> +. if any modifiers are set in <emphasis> +modLatches</emphasis> + but not in <emphasis> +affectModLatches</emphasis> +, a <emphasis> +Match</emphasis> + error occurs. +</para> + + +<para> +If the locked group exceeds the maximum number of groups permitted for the +specified keyboard, it is wrapped or truncated back into range as specified by +the global <emphasis> +GroupsWrap</emphasis> +<emphasis> + </emphasis> +control. No error results from an out-of-range group specification. +</para> + + +<para> +After changing the locked and latched modifiers and groups as specified, the X +server recalculates the effective and compatibility keyboard state and +generates <emphasis> +XkbStateNotify</emphasis> + events as appropriate if any state components have changed. Changing the +keyboard state might also turn indicators on or off which can cause <emphasis> +XkbIndicatorStateNotify</emphasis> + events as well. +</para> + + +<para> +If any errors occur, this request has no effect. +</para> + + +</sect2> +<sect2 id='querying_and_changing_keyboard_controls'> +<title>Querying and Changing Keyboard Controls</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbGetControls</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +deviceID: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +mouseKeysDfltBtn: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +numGroups: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +groupsWrap: KB_GROUPINFO + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +internalMods,ignoreLockMods: KB_MODDEF + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +repeatDelay,repeatInterval: CARD16 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +slowKeysDelay, debounceDelay: CARD16 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +mouseKeysDelay, mouseKeysInterval: CARD16 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +mouseKeysTimeToMax, mouseKeysMaxSpeed: CARD16 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +mouseKeysCurve: INT16 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +accessXOptions: KB_AXOPTIONMASK + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +accessXTimeout: CARD16 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +accessXTimeoutOptionsMask, accessXTimeoutOptionValues: CARD16 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +accessXTimeoutMask,accessXTimeoutValues: CARD32 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +enabledControls: KB_BOOLCTRLMASK + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +perKeyRepeat: LISTofCARD8</entry> + </row> + + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +This request returns the current values and status of all controls for the +keyboard specified by <emphasis> +deviceSpec</emphasis> +. If <emphasis> +deviceSpec</emphasis> + specifies an illegal device a <emphasis> +Keyboard</emphasis> + error results. On return, the <emphasis> +deviceID</emphasis> + specifies the identifier of the requested device or zero if the server does +not support the input extension. +</para> + + +<para> +The <emphasis> +numGroups</emphasis> + return value reports the current number of groups, and <emphasis> +groupsWrap</emphasis> + reports the treatment of out-of-range groups, as described in <ulink +url="XKBproto.htm#50332257_52755">See Key Symbol Map</ulink>. The <emphasis> +internalMods</emphasis> + and <emphasis> +ignoreLockMods</emphasis> + return values report the current values of the server internal and ignore +locks modifiers as described in <ulink url="XKBproto.htm#50332257_13933">See +Keyboard State</ulink>. Both are modifier definitions (<ulink +url="XKBproto.htm#50332257_11005">See Modifier Definitions</ulink>) which +report the real modifiers, virtual modifiers, and the resulting combination of +real modifiers that are bound to the corresponding control. +</para> + + +<para> +The <emphasis> +repeatDelay</emphasis> +, <emphasis> +repeatInterval</emphasis> +, <emphasis> +slowKeysDelay</emphasis> + and <emphasis> +debounceDelay</emphasis> + fields report the current values of the for the autorepeat delay, autorepeat +interval, slow keys delay and bounce keys timeout, respectively. The <emphasis> +mouseKeysDelay</emphasis> +, <emphasis> +mouseKeysInterval</emphasis> +, <emphasis> +mouseKeysTimeToMax</emphasis> + and <emphasis> +mouseKeysMaxSpeed</emphasis> + and <emphasis> +mouseKeysCurve</emphasis> + return values report the current acceleration applied to mouse keys, as +described in <ulink url="XKBproto.htm#50332257_29074">See The MouseKeysAccel +Control</ulink>. All times are reported in milliseconds. +</para> + + +<para> +The <emphasis> +mouseKeysDfltBtn</emphasis> + return value reports the current default pointer button for which events are +synthesized by the mouse keys server actions. +</para> + + +<para> +The <emphasis> +accessXOptions</emphasis> + return value reports the current settings of the various AccessX options flags +which govern the behavior of the <emphasis> +StickyKeys</emphasis> + control and of AccessX feedback. +</para> + + +<para> +The <emphasis> +accessXTimeout</emphasis> + return value reports the length of time, in seconds, that the keyboard must +remain idle before AccessX controls are automatically changed; an <emphasis> +accessXTimeout</emphasis> + of <emphasis> +0</emphasis> + indicates that AccessX controls are not automatically changed. The <emphasis> +accessXTimeoutMask</emphasis> + specifies the boolean controls to be changed if the AccessX timeout expires; +the <emphasis> +accessXTimeoutValues</emphasis> + field specifies new values for all of the controls in the timeout mask. The +<emphasis> +accessXTimeoutOptionsMask</emphasis> + field specifies the AccessX options to be changed when the AccessX timeout +expires; the <emphasis> +accessXTimeoutOptionValues</emphasis> + return value reports the values to which they will be set. +</para> + + +<para> +The <emphasis> +enabledControls</emphasis> + return value reports the current state of all of the global boolean controls. +</para> + + +<para> +The <emphasis> +perKeyRepeat</emphasis> + array consists of one bit per key and reports the current autorepeat behavior +of each keyboard key; if a bit is set in <emphasis> +perKeyRepeat</emphasis> +, the corresponding key repeats if it is held down while global keyboard +autorepeat is enabled. This array parallels the core protocol and input +extension keyboard controls, if the autorepeat behavior of a key is changed via +the core protocol or input extension, those changes are automatically reflected +in the <emphasis> +perKeyRepeat</emphasis> + array. +</para> + + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbSetControls</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +affectInternalRealMods, internalRealMods: KEYMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +affectInternalVirtualMods,internalVirtualMods: KB_VMODMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +affectIgnoreLockRealMods,ignoreLockRealMods: KB_MODMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +affectIgnoreLockVirtualMods,ignoreLockVirtualMods: KB_VMODMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +mouseKeysDfltBtn: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +groupsWrap: KB_GROUPINFO</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +accessXOptions: CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +affectEnabledControls: KB_BOOLCTRLMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +enabledControls: KB_BOOLCTRLMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +changeControls: KB_CONTROLMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +repeatDelay,repeatInterval: CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +slowKeysDelay, debounceDelay: CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +mouseKeysDelay, mouseKeysInterval: CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +mouseKeysTimeToMax, mouseKeysMaxSpeed: CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +mouseKeysCurve: INT16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +accessXTimeout: CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +accessXTimeoutMask, accessXTimeoutValues: KB_BOOLCTRLMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +accessXTimeoutOptionsMask,accessXTimeoutOptionsValues: CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +perKeyRepeat: LISTofCARD8</entry> + </row> + + <row rowsep='0'> + <entry role='protoerror'>Errors:<emphasis> + Keyboard</emphasis> +, <emphasis> +Value</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +This request sets the keyboard controls indicated in <emphasis> +changeControls</emphasis> + for the keyboard specified by <emphasis> +deviceSpec</emphasis> +. Each bit that is set in <emphasis> +changeControls</emphasis> + indicates that one or more of the other request fields should be applied, as +follows: +</para> + +<informaltable frame='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Bit in changeControls</entry> + <entry>Field(s) to be Applied</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis> +XkbRepeatKeysMask</emphasis> +</entry> + <entry><emphasis> +repeatDelay</emphasis> +, <emphasis> +repeatInterval</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbSlowKeysMask</emphasis> +</entry> + <entry><emphasis> +slowKeysDelay</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbStickyKeysMask</emphasis> +</entry> + <entry><emphasis> +accessXOptions</emphasis> + (only the <emphasis> +XkbAX_TwoKeys</emphasis> +<emphasis> + </emphasis> +and the <emphasis> +XkbAX_LatchToLock</emphasis> + options are affected)</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbBounceKeysMask</emphasis> +</entry> + <entry><emphasis> +debounceDelay</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbMouseKeysMask</emphasis> +</entry> + <entry><emphasis> +mouseKeysDfltBtn</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbMouseKeysAccelMask</emphasis> +</entry> + <entry><emphasis> +mouseKeysDelay</emphasis> +, <emphasis> +mouseKeysInterval</emphasis> +, <emphasis> +mouseKeysCurve</emphasis> +, <emphasis> +mouseKeysTimeToMax</emphasis> +, <emphasis> +mouseKeysMaxSpeed</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbAccessXKeysMask</emphasis> +</entry> + <entry><emphasis> +accessXOptions (all options)</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbAccessXTimeoutMask</emphasis> +</entry> + <entry><emphasis> +accessXTimeout</emphasis> +, <emphasis> +accessXTimeoutMask</emphasis> +, <emphasis> +accessXTimeoutValues</emphasis> +, <emphasis> +accessXTimeoutOptionsMask</emphasis> +, <emphasis> +accessXTimeoutOptionsValues</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry>XkbAccessXFeedbackMask</entry> + <entry><emphasis> +accessXOptions</emphasis> + (all options except those affected by the <emphasis> +XkbStickyKeysMask</emphasis> + bit)</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbGroupsWrapMask</emphasis> +</entry> + <entry><emphasis> +groupsWrap</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbInternalModsMask</emphasis> +</entry> + <entry><emphasis> +affectInternalRealMods</emphasis> +, <emphasis> +internalRealMods</emphasis> +, <emphasis> +affectInternalVirtualMods</emphasis> +, <emphasis> +internalVirtualMods</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbIgnoreLockModsMask</emphasis> +</entry> + <entry><emphasis> +affectIgnoreLockRealMods</emphasis> +, <emphasis> +ignoreLockRealMods</emphasis> +, <emphasis> +affectIgnoreLockVirtualMods</emphasis> +, <emphasis> +ignoreLockVirtualMods</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbPerKeyRepeatMask</emphasis> +</entry> + <entry><emphasis> +perKeyRepeat</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbControlsEnabledMask</emphasis> +</entry> + <entry><emphasis> +affectEnabledControls</emphasis> +, <emphasis> +enabledControls</emphasis> +</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +If any other bits are set in <emphasis> +changeControls</emphasis> +, a <emphasis> +Value</emphasis> + error results. If any of the bits listed above are not set in <emphasis> +changeControls</emphasis> +, the corresponding fields must have the value <emphasis> +0</emphasis> +, or a <emphasis> +Match</emphasis> + error results. +</para> + + +<para> +If applied, <emphasis> +repeatDelay</emphasis> + and <emphasis> +repeatInterval</emphasis> + change the autorepeat characteristics of the keyboard, as described in <ulink +url="XKBproto.htm#50332257_48937">See The RepeatKeys Control</ulink>. If +specified, <emphasis> +repeatDelay</emphasis> + and <emphasis> +repeatInterval</emphasis> + must both be non-zero or a <emphasis> +Value</emphasis> + error results. +</para> + + +<para> +If applied, the <emphasis> +slowKeysDelay</emphasis> + field specifies a new delay for the <emphasis> +SlowKeys</emphasis> + control, as defined in <ulink url="XKBproto.htm#50332257_59600">See The +SlowKeys Control</ulink>. If specified, <emphasis> +slowKeysDelay</emphasis> + must be non-zero, or a <emphasis> +Value</emphasis> + error results. +</para> + + +<para> +If applied, the <emphasis> +debounceDelay</emphasis> + field specifies a new delay for the <emphasis> +BounceKeys</emphasis> + control, as described in <ulink url="XKBproto.htm#50332257_12450">See The +BounceKeys Control</ulink>. If present, the <emphasis> +debounceDelay</emphasis> + must be non-zero or a <emphasis> +Value</emphasis> + error results. +</para> + + +<para> +If applied, the <emphasis> +mouseKeysDfltBtn</emphasis> + field specifies the core pointer button for which events are generated +whenever a <emphasis> +SA_PtrBtn</emphasis> + or <emphasis> +SA_LockPtrBtn</emphasis> + key action is activated. If present, <emphasis> +mouseKeysDfltBtn</emphasis> + must specify a legal button for the core pointer device, or a <emphasis> +Value</emphasis> + error results. <ulink url="XKBproto.htm#50332257_15763">See Key +Actions</ulink> describes the <emphasis> +SA_PtrBtn</emphasis> + and <emphasis> +SA_LockPtrBtn</emphasis> + actions in more detail. +</para> + + +<para> +If applied, the <emphasis> +mouseKeysDelay</emphasis> +, <emphasis> +mouseKeysInterval</emphasis> +, <emphasis> +mouseKeysTimeToMax</emphasis> +, <emphasis> +mouseKeysMaxSpeed</emphasis> + and <emphasis> +mouseKeysCurve</emphasis> + fields change the rate at which the pointer moves when a key which generates a +<emphasis> +SA_MovePtr</emphasis> + action is held down. <ulink url="XKBproto.htm#50332257_29074">See The +MouseKeysAccel Control</ulink> describes these <emphasis> +MouseKeysAccel</emphasis> + parameters in more detail. If defined, the <emphasis> +mouseKeysDelay</emphasis> +, <emphasis> +mouseKeysInterval</emphasis> +, <emphasis> +mouseKeysTimeToMax</emphasis> + and <emphasis> +mouseKeysMaxSpeed</emphasis> + values must all be greater than zero, or a <emphasis> +Value</emphasis> + error results. The <emphasis> +mouseKeysCurve</emphasis> + value must be greater than <emphasis> +-1000</emphasis> + or a <emphasis> +Value</emphasis> + error results. +</para> + + +<para> +If applied, the <emphasis> +accessXOptions</emphasis> + field sets the AccessX options, which are described in detail in <ulink +url="XKBproto.htm#50332257_27926">See The AccessXKeys Control</ulink>. If +either one of <emphasis> +XkbStickyKeysMask</emphasis> + and <emphasis> +XkbAccessXFeedbackMask</emphasis> + are set in <emphasis> +changeControls</emphasis> + and <emphasis> +XkbAccessXKeysMask</emphasis> + is not, only a subset of the AccessX options are changed, as described in the +table above; if both are set or if the <emphasis> +AccessXKeys</emphasis> + bit is set in <emphasis> +changeControls</emphasis> +, all of the AccessX options are updated. Any bit in <emphasis> +accessXOptions</emphasis> + whose interpretation is undefined must be zero, or a <emphasis> +Value</emphasis> + error results. +</para> + + +<para> +If applied, the <emphasis> +accessXTimeout</emphasis> +, <emphasis> +accessXTimeoutMask</emphasis> +, <emphasis> +accessXTimeoutValues</emphasis> +, <emphasis> +accessXTimeoutOptionsMask</emphasis> + and <emphasis> +accessXTimeoutOptionsValues</emphasis> + fields change the behavior of the AccessX Timeout control, as described in +<ulink url="XKBproto.htm#50332257_27038">See The AccessXTimeout +Control</ulink>. The <emphasis> +accessXTimeout</emphasis> + must be greater than zero, or a <emphasis> +Value</emphasis> + error results. The <emphasis> +accessXTimeoutMask</emphasis> + or <emphasis> +accessXTimeoutValues</emphasis> + fields must specify only legal boolean controls, or a <emphasis> +Value</emphasis> + error results. The <emphasis> +accessXTimeoutOptionsMask</emphasis> + and <emphasis> +accessXTimeoutOptionsValues</emphasis> + fields must contain only legal AccessX options or a <emphasis> +Value</emphasis> + error results. If any bits are set in either values field but not in the +corresponding mask, a <emphasis> +Match</emphasis> + error results. +</para> + + +<para> +If present, the <emphasis> +groupsWrap</emphasis> + field specifies the treatment of out-of-range keyboard groups, as described in +<ulink url="XKBproto.htm#50332257_52755">See Key Symbol Map</ulink>. If the +<emphasis> +groupsWrap</emphasis> + field does not specify a legal treatment for out-of-range groups, a <emphasis> +Value</emphasis> + error results. +</para> + + +<para> +If present, the <emphasis> +affectInternalRealMods</emphasis> + field specifies the set of real modifiers to be changed in the internal +modifier definition and the <emphasis> +internalRealMods</emphasis> + field specifies new values for those modifiers. The <emphasis> +affectInternalVirtualMods</emphasis> + and <emphasis> +internalVirtualMods</emphasis> + fields update the virtual modifier component of the modifier definition that +describes the internal modifiers in the same way. If any bits are set in either +values field but not in the corresponding mask field, a <emphasis> +Match</emphasis> + error results. +</para> + + +<para> +If present, the <emphasis> +affectIgnoreLockRealMods</emphasis> + field specifies the set of real modifiers to be changed in the ignore locks +modifier definition and the <emphasis> +ignoreLockRealMods</emphasis> + field specifies new values for those modifiers. The <emphasis> +affectIgnoreLockVirtualMods</emphasis> + and <emphasis> +ignoreLockVirtualMods</emphasis> + fields update the virtual modifier component of the ignore locks modifier +definition in the same way. If any bits are set in either values field but not +in the corresponding mask field, a <emphasis> +Match</emphasis> + error results. +</para> + + +<para> +If present, the <emphasis> +perKeyRepeat</emphasis> + array specifies the repeat behavior of the individual keyboard keys. The +corresponding core protocol or input extension per-key autorepeat information +is updated to reflect any changes specified in <emphasis> +perKeyRepeat</emphasis> +. If the bits that correspond to any out-of-range keys are set in <emphasis> +perKeyRepeat</emphasis> +, a <emphasis> +Value</emphasis> + error results. +</para> + + +<para> +If present, the <emphasis> +affectEnabledControls</emphasis> + and <emphasis> +enabledControls</emphasis> + field enable and disable global boolean controls. Any controls set in both +fields are enabled; any controls that are set in <emphasis> +affectEnabledControls</emphasis> + but not in <emphasis> +enabledControls</emphasis> + are disabled. Controls that are not set in either field are not affected. If +any controls are specified in <emphasis> +enabledControls</emphasis> + but not in <emphasis> +affectEnabledControls</emphasis> +, a <emphasis> +Match</emphasis> + error results. If either field contains anything except boolean controls, a +<emphasis> +Value</emphasis> + error results. +</para> + + +</sect2> +<sect2 id='querying_and_changing_the_keyboard_mapping'> +<title>Querying and Changing the Keyboard Mapping</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbGetMap</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +full, partial: KB_MAPPARTMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstType, nTypes: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstKeySym, firstKeyAction: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +nKeySyms, nKeyActions: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstKeyBehavior,firstKeyExplicit: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +nKeyBehaviors,nKeyExplicit: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstModMapKey,firstVModMapKey: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +nModMapKeys, nVModMapKeys: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +virtualMods: KB_VMODMASK + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +deviceID: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +minKeyCode, maxKeyCode: KEYCODE + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +present: KB_MAPPARTMASK + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +firstType, nTypes, nTotalTypes: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +firstKeySym, firstKeyAction: KEYCODE + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +nKeySyms, nKeyActions: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +totalSyms, totalActions: CARD16 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +firstKeyBehavior, firstKeyExplicit: KEYCODE + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +nKeyBehaviors, nKeyExplicit: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +totalKeyBehaviors, totalKeyExplicit: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +firstModMapKey, firstVModMapKey: KEYCODE + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +nModMapKeys, nVModMapKeys: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +totalModMapKeys, totalVModMapKeys: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +virtualMods: KB_VMODMASK + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +typesRtrn: LISTofKB_KEYTYPE + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +symsRtrn: LISTofKB_KEYSYMMAP + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +actsRtrn: { count: LISTofCARD8, acts: LISTofKB_ACTION } + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +behaviorsRtrn: LISTofKB_SETBEHAVIOR + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +vmodsRtrn: LISTofSETofKEYMASK + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +explicitRtrn: LISTofKB_SETEXPLICIT + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +modmapRtrn: LISTofKB_KEYMODMAP + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +vmodMapRtrn: LISTofKB_KEYVMODMAP + </entry> + </row> + <row rowsep='0'> + <entry role='protoerror'> +Errors: <emphasis> +Keyboard</emphasis> +, <emphasis> +Value</emphasis> +, <emphasis> +Match</emphasis> +, <emphasis> +Alloc</emphasis> +</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +This request returns the indicated components of the server and client maps of +the keyboard specified by <emphasis> +deviceSpec</emphasis> +. The <emphasis> +full</emphasis> + mask specifies the map components to be returned in full; the <emphasis> +partial</emphasis> + mask specifies the components for which some subset of the legal elements are +to be returned. The server returns a <emphasis> +Match</emphasis> + error if any component is specified in both <emphasis> +full</emphasis> + and <emphasis> +partial</emphasis> +, or a <emphasis> +Value</emphasis> + error if any undefined bits are set in either <emphasis> +full</emphasis> + or <emphasis> +partial</emphasis> +. +</para> + + +<para> +Each bit in the <emphasis> +partial</emphasis> + mask controls the interpretation of one or more of the other request fields, +as follows: +</para> + +<informaltable frame='none'> +<tgroup cols='3'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Bit in the Partial Mask</entry> + <entry>Type</entry> + <entry>Corresponding Field(s)</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis> +XkbKeyTypesMask</emphasis> +</entry> + <entry>key types</entry> + <entry><emphasis> +firstType</emphasis> +, <emphasis> +nTypes</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbKeySymsMask</emphasis> +</entry> + <entry>keycodes</entry> + <entry><emphasis> +firstKeySym</emphasis> +, <emphasis> +nKeySyms</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbKeyActionsMask</emphasis> +</entry> + <entry>keycodes</entry> + <entry><emphasis> +firstKeyAction</emphasis> +, <emphasis> +nKeyActions</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbKeyBehaviorsMask</emphasis> +</entry> + <entry>keycodes</entry> + <entry><emphasis> +firstKeyBehavior</emphasis> +, <emphasis> +nKeyBehaviors</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbExplicitComponentsMask</emphasis> +</entry> + <entry>keycodes</entry> + <entry><emphasis> +firstKeyExplicit</emphasis> +, <emphasis> +nKeyExplicit</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbModifierMapMask</emphasis> +</entry> + <entry>keycodes</entry> + <entry><emphasis> +firstModMapKey</emphasis> +, <emphasis> +nModMapKeys</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbVirtualModMapMask</emphasis> +</entry> + <entry>keycodes</entry> + <entry><emphasis> +firstVModMapKey</emphasis> +, <emphasis> +nVModMapKeys</emphasis> +</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbVirtualModsMask</emphasis> +</entry> + <entry>virtual modifiers</entry> + <entry><emphasis> +virtualMods</emphasis> +</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +If any of these keyboard map components are specified in <emphasis> +partial</emphasis> +, the corresponding values must specify a valid subset of the requested +components or this request reports a <emphasis> +Value</emphasis> + error. If a keyboard map component is not specified in <emphasis> +partial</emphasis> +, the corresponding fields must contain zeroes, or a <emphasis> +Match</emphasis> + error results. +</para> + + +<para> +If any error is generated, the request aborts and does not report any values. +</para> + + +<para> +On successful return, the <emphasis> +deviceID</emphasis> + field reports the X input extension device ID of the keyboard for which +information is being returned, or <emphasis> +0</emphasis> + if the server does not support the X input extension. The <emphasis> +minKeyCode</emphasis> + and <emphasis> +maxKeyCode</emphasis> + return values report the minimum and maximum keycodes that are legal for the +keyboard in question. +</para> + + +<para> +The <emphasis> +present</emphasis> + return value lists all of the keyboard map components contained in the reply. +The bits in <emphasis> +present</emphasis> + affect the interpretation of the other return values as follows: +</para> + + +<para> +If <emphasis> +XkbKeyTypesMask</emphasis> + is set in <emphasis> +present</emphasis> +: +</para> + +<itemizedlist> +<listitem> + <para><emphasis> +firstType</emphasis> + and <emphasis> +nTypes</emphasis> + specify the types reported in the reply. + </para> +</listitem> +<listitem> + <para><emphasis> +nTotalTypes</emphasis> + reports the total number of types defined for the keyboard + </para> +</listitem> +<listitem> + <para><emphasis> +typesRtrn</emphasis> + has <emphasis> +nTypes</emphasis> + elements of type KB_KEYTYPE which describe consecutive key types starting from +<emphasis> +firstType</emphasis> +. + </para> +</listitem> +</itemizedlist> + +<para> +If <emphasis> +XkbKeySymsMask</emphasis> + is set in <emphasis> +present</emphasis> +: +</para> + +<itemizedlist> +<listitem> + <para><emphasis> +firstKeySym</emphasis> + and <emphasis> +nKeySyms</emphasis> + specify the subset of the keyboard keys for which symbols will be reported. + </para> +</listitem> +<listitem> + <para><emphasis> +totalSyms</emphasis> + reports the total number of keysyms bound to the keys returned in this reply. + </para> +</listitem> +<listitem> + <para><emphasis> +symsRtrn</emphasis> + has <emphasis> +nKeySyms</emphasis> + elements of type KB_KEYSYMMAP, which describe the symbols bound to consecutive +keys starting from <emphasis> +firstKeySym</emphasis> +. + </para> +</listitem> +</itemizedlist> + +<para> +If <emphasis> +XkbKeyActionsMask</emphasis> + is set in <emphasis> +present</emphasis> +: +</para> + +<itemizedlist> +<listitem> + <para><emphasis> +firstKeyAction</emphasis> + and <emphasis> +nKeyActions</emphasis> + specify the subset of the keys for which actions are reported. + </para> +</listitem> +<listitem> + <para><emphasis> +totalActions</emphasis> + reports the total number of actions bound to the returned keys. + </para> +</listitem> +<listitem> + <para>The <emphasis> +count </emphasis> +field of the <emphasis> +actsRtrn</emphasis> + return value has <emphasis> +nKeyActions</emphasis> + entries of type CARD8, which specify the number of actions bound to +consecutive keys starting from <emphasis> +firstKeyAction</emphasis> +. The <emphasis> +acts</emphasis> + field of <emphasis> +actsRtrn</emphasis> + has <emphasis> +totalActions</emphasis> + elements of type KB_ACTION and specifies the actions bound to the keys. + </para> +</listitem> +</itemizedlist> + +<para> +If <emphasis> +XkbKeyBehaviorsMask</emphasis> + is set in <emphasis> +present</emphasis> +: +</para> + +<itemizedlist> +<listitem> + <para>The <emphasis> +firstKeyBehavior</emphasis> + and <emphasis> +nKeyBehaviors</emphasis> + return values report the range of keyboard keys for which behaviors will be +reported. + </para> +</listitem> +<listitem> + <para>The <emphasis> +totalKeyBehaviors</emphasis> + return value reports the number of keys in the range to be reported that have +non-default values. + </para> +</listitem> +<listitem> + <para>The <emphasis> +behaviorsRtrn</emphasis> + value has <emphasis> +totalKeyBehaviors</emphasis> + entries of type KB_BEHAVIOR. Each entry specifies a key in the range for which +behaviors are being reported and the behavior associated with that key. Any +keys in that range that do not have an entry in <emphasis> +behaviorsRtrn</emphasis> + have the default behavior, <emphasis> +KB_Default</emphasis> +. + </para> +</listitem> +</itemizedlist> + +<para> +If <emphasis> +XkbExplicitComponentsMask</emphasis> + is set in <emphasis> +present</emphasis> +: +</para> + +<itemizedlist> +<listitem> + <para>The <emphasis> +firstKeyExplicit</emphasis> + and <emphasis> +nKeyExplicit</emphasis> + return values report the range of keyboard keys for which the set of explicit +components is to be returned. + </para> +</listitem> +<listitem> + <para>The <emphasis> +totalKeyExplicit</emphasis> + return value reports the number of keys in the range specified by <emphasis> +firstKeyExplicit</emphasis> + and <emphasis> +nKeyExplicit</emphasis> + that have one or more explicit components. + </para> +</listitem> +<listitem> + <para>The <emphasis> +explicitRtrn</emphasis> + return value has <emphasis> +totalKeyExplicit</emphasis> + entries of type KB_KEYEXPLICIT. Each entry specifies the a key in the range +for which explicit components are being reported and the explicit components +that are bound to it. Any keys in that range that do not have an entry in +<emphasis> +explicitRtrn</emphasis> + have no explicit components. + </para> +</listitem> +</itemizedlist> + +<para> +If <emphasis> +XkbModifierMapMask</emphasis> + is set in <emphasis> +present</emphasis> +: +</para> + +<itemizedlist> +<listitem> + <para>The <emphasis> +firstModMapKey</emphasis> + and <emphasis> +nModMapKeys</emphasis> + return values report the range of keyboard keys for which the modifier map is +to be reported. + </para> +</listitem> +<listitem> + <para>The <emphasis> +totalModMapKeys</emphasis> + return value reports the number of keys in the range specified by <emphasis> +firstModMapKey</emphasis> + and <emphasis> +nModMapKeys</emphasis> + that are bound with to one or more modifiers. + </para> +</listitem> +<listitem> + <para>The <emphasis> +modmapRtrn</emphasis> + return value has <emphasis> +totalModMapKeys</emphasis> + entries of type KB_KEYMODMAP. Each entry specifies the a key in the range for +which the modifier map is being reported and the set of modifiers that are +bound to that key. Any keys in that range that do not have an entry in +<emphasis> +modmapRtrn</emphasis> + are not associated with any modifiers by the modifier mapping. + </para> +</listitem> +</itemizedlist> + +<para> +If <emphasis> +XkbVirtualModMapMask</emphasis> + is set in <emphasis> +present</emphasis> +: +</para> + +<itemizedlist> +<listitem> + <para>The <emphasis> +firstVModMapKey</emphasis> + and <emphasis> +nVModMapKeys</emphasis> + return values report the range of keyboard keys for which the virtual modifier +map is to be reported. + </para> +</listitem> +<listitem> + <para>The <emphasis> +totalVModMapKeys</emphasis> + return value reports the number of keys in the range specified by <emphasis> +firstVModMapKey</emphasis> + and <emphasis> +nVModMapKeys</emphasis> + that are bound with to or more virtual modifiers. + </para> +</listitem> +<listitem> + <para>The <emphasis> +vmodmapRtrn</emphasis> + return value has <emphasis> +totalVModMapKeys</emphasis> + entries of type KB_KEYVMODMAP. Each entry specifies the a key in the range for +which the virtual modifier map is being reported and the set of virtual +modifiers that are bound to that key. Any keys in that range that do not have +an entry in <emphasis> +vmodmapRtrn</emphasis> + are not associated with any virtual modifiers, + </para> +</listitem> +</itemizedlist> + +<para> +If <emphasis> +XkbVirtualModsMask</emphasis> + is set in <emphasis> +present</emphasis> +: +</para> + +<itemizedlist> +<listitem> + <para>The <emphasis> +virtualMods</emphasis> + return value is a mask with one bit per virtual modifier which specifies the +virtual modifiers for which a set of corresponding real modifiers is to be +returned. + </para> +</listitem> +<listitem> + <para>The <emphasis> +vmodsRtrn</emphasis> + return value is a list with one entry of type KEYBUTMASK for each virtual +modifier that is specified in <emphasis> +virtualMods</emphasis> +. The entries in <emphasis> +vmodsRtrn</emphasis> + contain the real modifier bindings for the specified virtual modifiers, +beginning with the lowest-numbered virtual modifier that is present in +<emphasis> +virtualMods</emphasis> + and proceeding to the highest. + </para> +</listitem> +</itemizedlist> + +<para> +If any of these bits are not set in <emphasis> +present</emphasis> +, the corresponding numeric fields all have the value zero, and the +corresponding lists are all of length zero. +</para> + + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbSetMap</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +flags: { <emphasis> +SetMapResizeTypes, SetMapRecomputeActions </emphasis> +}</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +present: KB_MAPPARTMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +minKeyCode, maxKeyCode: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstType, nTypes: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstKeySym, firstKeyAction: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +nKeySyms, nKeyActions: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +totalSyms, totalActions: CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstKeyBehavior, firstKeyExplicit: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +nKeyBehaviors, nKeyExplicit: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +totalKeyBehaviors, totalKeyExplicit: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstModMapKey, firstVModMapKey: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +nModMapKeys, nVModMapKeys: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +totalModMapKeys, totalVModMapKeys: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +virtualMods: VMODMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +types: LISTofKB_KEYTYPE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +syms: LISTofKB_KEYSYMMAP</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +actions: { count: LISTofCARD8, actions: LISTofKB_ACTION }</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +behaviors: LISTofKB_BEHAVIOR</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +vmods: LISTofKEYMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +explicit: LISTofKB_EXPLICIT</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +modmap: LISTofKB_KEYMODMAP</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +vmodmap: LISTofKB_KEYVMODMAP</entry> + </row> + + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +, <emphasis> +Value</emphasis> +, <emphasis> +Match</emphasis> +, <emphasis> +Alloc</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +This request changes the indicated parts of the keyboard specified by <emphasis> +deviceSpec</emphasis> +. With XKB, the effect of a key release is independent of the keyboard mapping +at the time of the release, so this request can be processed regardless of the +logical state of the modifier keys at the time of the request. +</para> + + +<para> +The <emphasis> +present</emphasis> + field specifies the keyboard map components contained to be changed. The bits +in <emphasis> +present</emphasis> + affect the interpretation of the other fields as follows: +</para> + + +<para> +If <emphasis> +XkbKeyTypesMask</emphasis> + is set in <emphasis> +present</emphasis> +, <emphasis> +firstType</emphasis> + and <emphasis> +nTypes</emphasis> + specify a subset of the key types bound to the keyboard to be changed or +created. The index of the first key type to be changed must be less than or +equal to the unmodified length of the list of key types or a <emphasis> +Value</emphasis> + error results. +</para> + + +<para> +If <emphasis> +XkbKeyTypesMask</emphasis> + is set in <emphasis> +present</emphasis> + and <emphasis> +SetMapResizeTypes</emphasis> + is set in <emphasis> +flags</emphasis> +, the server resizes the list of key types bound to the keyboard so that the +last key type specified by this request is the last element in the list. If the +list of key types is shrunk, any existing key definitions that use key types +that eliminated are automatically assigned key types from the list of canonical +key types as described in <ulink url="XKBproto.htm#50332257_35661">See +Assigning Types To Groups of Symbols for a Key</ulink>. The list of key types +bound to a keyboard must always include the four canonical types and cannot +have more than <emphasis> +XkbMaxTypesPerKey</emphasis> + (32) types; any attempt to reduce the number of types bound to a keyboard +below four or above <emphasis> +XkbMaxTypesPerKey</emphasis> + causes a <emphasis> +Value</emphasis> + error. Symbolic names for newly created key types or levels within a key type +are initialized to <emphasis> +None</emphasis> +. +</para> + + +<para> +If <emphasis> +XkbKeyTypesMask</emphasis> + is set in <emphasis> +present</emphasis> +, the types list has <emphasis> +nTypes</emphasis> + entries of type KB_KEYTYPE.Each key type specified in <emphasis> +types</emphasis> + must be valid or a <emphasis> +Value</emphasis> + error results. To be valid a key type definition must meet the following +criteria: +</para> + +<itemizedlist> +<listitem> + <para>The <emphasis> +numLevels</emphasis> + for the type must be greater than zero. + </para> +</listitem> +<listitem> + <para>If the key type is <emphasis> +ONE_LEVEL</emphasis> + (i.e. index zero in the list of key types), <emphasis> +numLevels</emphasis> + must be one. + </para> +</listitem> +<listitem> + <para>If the key type is <emphasis> +TWO_LEVEL</emphasis> + or <emphasis> +KEYPAD</emphasis> +, or <emphasis> +ALPHABETIC</emphasis> + (i.e. index one, two, or three in the lest of key types) group width must be +two. + </para> +</listitem> +</itemizedlist> + +<para> +Each key type in types must also be internally consistent, or a Match error +results. To be internally consistent, a key type definition must meet the +following criteria: +</para> + +<itemizedlist> +<listitem> + <para>Each map entry must specify a resulting level that is legal for the +type. + </para> +</listitem> +<listitem> + <para>Any real or virtual modifiers specified in any of the map entries must +also be specified in the <emphasis> +mods</emphasis> + for the type. + </para> +</listitem> +</itemizedlist> + +<para> +If <emphasis> +XkbKeySymsMask</emphasis> + is set in <emphasis> +present</emphasis> +, <emphasis> +firstKeySym</emphasis> + and <emphasis> +nKeySyms</emphasis> + specify a subset of the keyboard keys to which new symbols are to be assigned +and <emphasis> +totalSyms</emphasis> + specifies the total number of symbols to be assigned to those keys. If any of +the keys specified by <emphasis> +firstKeySym</emphasis> + and <emphasis> +nKeySyms</emphasis> + are not legal, a <emphasis> +Match</emphasis> + error results. The <emphasis> +syms</emphasis> + list has <emphasis> +nKeySyms</emphasis> + elements of type KB_KEYSYMMAP. Each key in the resulting key symbol map must +be valid and internally consistent or a <emphasis> +Value</emphasis> + error results. To be valid and internally consistent, a key symbol map must +meet the following criteria: +</para> + +<itemizedlist> +<listitem> + <para>The key type indices must specify legal result key types. + </para> +</listitem> +<listitem> + <para>The number of groups specified by <emphasis> +groupInfo</emphasis> + must be in the range <emphasis> +0…4</emphasis> +. + </para> +</listitem> +<listitem> + <para>The <emphasis> +width</emphasis> + of the key symbol map must be equal to <emphasis> +numLevels</emphasis> + of the widest key type bound to the key. + </para> +</listitem> +<listitem> + <para>The number of symbols, <emphasis> +nSyms</emphasis> +, must equal the number of groups times <emphasis> +width</emphasis> +. + </para> +</listitem> +</itemizedlist> + +<para> +If <emphasis> +XkbKeyActionsMask</emphasis> + is set in <emphasis> +present</emphasis> +, <emphasis> +firstKeyAction</emphasis> + and <emphasis> +nKeyActions</emphasis> + specify a subset of the keyboard keys to which new actions are to be assigned +and <emphasis> +totalActions</emphasis> + specifies the total number of actions to be assigned to those keys. If any of +the keys specified by <emphasis> +firstKeyAction</emphasis> + and <emphasis> +nKeyActions</emphasis> + are not legal, a <emphasis> +Match</emphasis> + error results. The <emphasis> +count</emphasis> + field of the <emphasis> +actions</emphasis> + return value has <emphasis> +nKeyActions</emphasis> + elements of type CARD8; each element of <emphasis> +count</emphasis> + specifies the number of actions bound to the corresponding key. The <emphasis> +actions</emphasis> + list in the <emphasis> +actions</emphasis> + field has <emphasis> +totalActions</emphasis> + elements of type KB_ACTION. These actions are assigned to each target key in +turn, as specified by <emphasis> +count</emphasis> +. The list of actions assigned to each key must either be empty or have exactly +as many actions as the key has symbols, or a <emphasis> +Match</emphasis> + error results. +</para> + + +<para> +If <emphasis> +XkbKeyBehaviorsMask</emphasis> + is set in <emphasis> +present</emphasis> +, <emphasis> +firstKeyBehavior</emphasis> + and <emphasis> +nKeyBehaviors</emphasis> + specify a subset of the keyboard keys to which new behaviors are to be +assigned, and <emphasis> +totalKeyBehaviors</emphasis> + specifies the total number of keys in that range to be assigned non-default +behavior. If any of the keys specified by <emphasis> +firstKeyBehavior</emphasis> + and <emphasis> +nKeyBehaviors</emphasis> + are not legal, a <emphasis> +Match</emphasis> + error results. The <emphasis> +behaviors</emphasis> + list has <emphasis> +totalKeyBehaviors</emphasis> + elements of type KB_BEHAVIOR; each entry of <emphasis> +behaviors</emphasis> + specifies a key in the specified range and a new behavior for that key; any +key that falls in the range specified by <emphasis> +firstBehavior</emphasis> + and <emphasis> +nBehaviors</emphasis> + for which no behavior is specified in <emphasis> +behaviors</emphasis> + is assigned the default behavior, <emphasis> +KB_Default</emphasis> +. The new behaviors must be legal, or a <emphasis> +Value</emphasis> + error results. To be legal, the behavior specified in the <emphasis> +XkbSetMap</emphasis> + request must: +</para> + +<itemizedlist> +<listitem> + <para>Specify a key in the range indicated by <emphasis> +firstKeyBehavior</emphasis> + and <emphasis> +nKeyBehaviors</emphasis> +. + </para> +</listitem> +<listitem> + <para>Not specify the <emphasis> +permanent</emphasis> + flag; permanent behaviors cannot be set or changed using the <emphasis> +XkbSetMap</emphasis> + request. + </para> +</listitem> +<listitem> + <para>If present, the <emphasis> +KB_Overlay1</emphasis> + and <emphasis> +KB_Overlay2</emphasis> + behaviors must specify a keycode for the overlay key that is valid for the +current keyboard. + </para> +</listitem> +<listitem> + <para>If present, the <emphasis> +KB_RadioGroup</emphasis> + behavior must specify a legal index (0…31) for the radio group to which the +key belongs. + </para> +</listitem> +</itemizedlist> + +<para> +Key behaviors that are not recognized by the server are accepted but ignored. +Attempts to replace a "permanent" behavior are silently ignored; the behavior +is not replaced, but not error is generated and any other components specified +in the <emphasis> +XkbSetMap</emphasis> + request are updated, as appropriate. +</para> + + +<para> +If <emphasis> +XkbVirtualModsMask</emphasis> + is set in <emphasis> +present</emphasis> +, <emphasis> +virtualMods</emphasis> + is a mask which specifies the virtual modifiers to be rebound. The <emphasis> +vmods</emphasis> + list specifies the real modifiers that are bound to each of the virtual +modifiers specified in <emphasis> +virtualMods</emphasis> +, starting from the lowest numbered virtual modifier and progressing upward. +Any virtual modifier that is not specified in <emphasis> +virtualMods</emphasis> + has no corresponding entry in <emphasis> +vmods</emphasis> +, so the <emphasis> +vmods</emphasis> + list has one entry for each bit that is set in <emphasis> +virtualMods</emphasis> +. +</para> + + +<para> +If <emphasis> +XkbExplicitComponentsMask</emphasis> + is set in <emphasis> +present</emphasis> +, <emphasis> +firstKeyExplicit</emphasis> + and <emphasis> +nKeyExplicit</emphasis> + specify a subset of the keyboard keys to which new explicit components are to +be assigned, and <emphasis> +totalKeyExplicit</emphasis> + specifies the total number of keys in that range that have at least one +explicit component. The <emphasis> +explicit</emphasis> + list has <emphasis> +totalKeyExplicit</emphasis> + elements of type KB_KEYEXPLICIT; each entry of <emphasis> +explicit</emphasis> + specifies a key in the specified range and a new set of explicit components +for that key. Any key that falls in the range specified by <emphasis> +firstKeyExplicit</emphasis> + and <emphasis> +nKeyExplicit</emphasis> + that is not assigned some value in <emphasis> +explicit</emphasis> + has no explicit components. +</para> + + +<para> +If <emphasis> +XkbModifierMapMask</emphasis> + is set in <emphasis> +present</emphasis> +, <emphasis> +firstModMapKey</emphasis> + and <emphasis> +nModMapKeys</emphasis> + specify a subset of the keyboard keys for which new modifier mappings are to +be assigned, and <emphasis> +totalModMapKeys</emphasis> + specifies the total number of keys in that range to which at least one +modifier is bound. The <emphasis> +modmap</emphasis> + list has <emphasis> +totalModMapKeys</emphasis> + elements of type KB_KEYMODMAP; each entry of <emphasis> +modmap</emphasis> + specifies a key in the specified range and a new set of modifiers to be +associated with that key. Any key that falls in the range specified by +<emphasis> +firstModMapKey</emphasis> + and <emphasis> +nModMapKeys</emphasis> + that is not assigned some value in <emphasis> +modmap</emphasis> + has no associated modifiers. +</para> + + +<para> +If the modifier map is changed by the <emphasis> +XkbSetMap</emphasis> + request, any changes are also reflected in the core protocol modifier mapping. +Changes to the core protocol modifier mapping are reported to XKB-unaware +clients via <emphasis> +MappingNotify</emphasis> + events and can be retrieved with the core protocol <emphasis> +GetModifierMapping</emphasis> + request. +</para> + + +<para> +If <emphasis> +XkbVirtualModMapMask</emphasis> + is set in <emphasis> +present</emphasis> +, <emphasis> +firstVModMapKey</emphasis> + and <emphasis> +nVModMapKeys</emphasis> + specify a subset of the keyboard keys for which new modifier mappings are to +be assigned, and <emphasis> +totalVModMapKeys</emphasis> + specifies the total number of keys in that range to which at least one virtual +modifier is bound. The <emphasis> +vmodmap</emphasis> + list has <emphasis> +totalVModMapKeys</emphasis> + elements of type KB_KEYVMODMAP; each entry of <emphasis> +vmodmap</emphasis> + specifies a key in the specified range and a new set of virtual modifiers to +be associated with that key. Any key that falls in the range specified by +<emphasis> +firstVModMapKey</emphasis> + and <emphasis> +nVModMapKeys</emphasis> + that is not assigned some value in <emphasis> +vmodmap</emphasis> + has no associated virtual modifiers. +</para> + + +<para> +If the resulting keyboard map is legal, the server updates the keyboard map. +Changes to some keyboard components have indirect effects on others: +</para> + + +<para> +If the <emphasis> +XkbSetMapRecomputeActions</emphasis> + bit is set in <emphasis> +flags</emphasis> +, the actions associated with any keys for which symbol or modifier bindings +were changed by this request are recomputed as described in <ulink +url="XKBproto.htm#50332257_66444">See Assigning Actions To Keys</ulink>. Note +that actions are recomputed <emphasis> +after </emphasis> +any actions specified in this request are bound to keys, so the actions +specified in this request might be clobbered by the automatic assignment of +actions to keys. +</para> + + +<para> +If the group width of an existing key type is changed, the list of symbols +associated with any keys of the changed type might be resized accordingly. If +the list increases in size, any unspecified new symbols are initialized to +<emphasis> +NoSymbol</emphasis> +. +</para> + + +<para> +If the list of actions associated with a key is not empty, changing the key +type of the key resizes the list. Unspecified new actions are calculated by +applying any keyboard symbol interpretations to the corresponding symbols. +</para> + + +<para> +The number of groups global to the keyboard is always equal to the largest +number of groups specified by any of the key symbol maps. Changing the number +of groups in one or more key symbol maps may change the number of groups global +to the keyboard. +</para> + + +<para> +Assigning key behavior <emphasis> +KB_RadioGroup</emphasis> + to a key adds that key as a member of the specified radio group. Changing a +key with the existing behavior <emphasis> +KB_RadioGroup</emphasis> + removes that key from the group. Changing the elements of a radio group can +cause synthetic key press or key release events if the key to be added or +removed is logically down at the time of the change. +</para> + + +<para> +Changing a key with behavior <emphasis> +KB_Lock</emphasis> + causes a synthetic key release event if the key is logically but not +physically down at the time of the change. +</para> + + +<para> +This request sends an <emphasis> +XkbMapNotify</emphasis> + event which reflects both explicit and indirect map changes to any interested +clients. If any symbolic names are changed, it sends a <emphasis> +XkbNamesNotify</emphasis> + reflecting the changes to any interested clients. XKB-unaware clients are +notified of keyboard changes via core protocol <emphasis> +MappingNotify</emphasis> + events. +</para> + + +<para> +Key press and key release events caused by changing key behavior may cause +additional <emphasis> +XkbStateNotify</emphasis> + or <emphasis> +XkbIndicatorStateNotify</emphasis> + events. +</para> + + +</sect2> +<sect2 id='querying_and_changing_the_compatibility_map'> +<title>Querying and Changing the Compatibility Map</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbGetCompatMap</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +groups: KB_GROUPMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +getAllSI: BOOL</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstSI, nSI: CARD16 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +deviceID: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +groupsRtrn: KB_GROUPMASK + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +firstSIRtrn, nSIRtrn, nTotalSI: CARD16 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +siRtrn: LISTofKB_SYMINTERP + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +groupRtrn: LISTofKB_MODDEF</entry> + </row> + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +, <emphasis> +Match</emphasis> +, <emphasis> +Alloc</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +This request returns the listed compatibility map components for the keyboard +specified by <emphasis> +deviceSpec</emphasis> +. If <emphasis> +deviceSpec</emphasis> + does not specify a valid keyboard device, a <emphasis> +Keyboard</emphasis> + Error results. On return, <emphasis> +deviceID</emphasis> + reports the input extension identifier of the keyboard device or <emphasis> +0</emphasis> + if the server does not support the input extension. +</para> + + +<para> +If <emphasis> +getAllSI</emphasis> + is <emphasis> +False</emphasis> +, <emphasis> +firstSI</emphasis> + and <emphasis> +nSI</emphasis> + specify a subset of the symbol interpretations to be returned; if used, +<emphasis> +nSI</emphasis> + must be greater than <emphasis> +0</emphasis> + and all of the elements specified by <emphasis> +firstSI</emphasis> + and <emphasis> +nSI</emphasis> + must be defined or a <emphasis> +Value</emphasis> + error results. If <emphasis> +getAllSyms</emphasis> + is <emphasis> +True</emphasis> +, the server ignores <emphasis> +firstSym</emphasis> + and <emphasis> +nSyms</emphasis> + and returns all of the symbol interpretations defined for the keyboard. +</para> + + +<para> +The <emphasis> +groups</emphasis> + mask specifies the groups for which compatibility maps are to be returned. +</para> + + +<para> +The <emphasis> +nTotalSI</emphasis> + return value reports the total number of symbol interpretations defined for +the keyboard. On successful return, the <emphasis> +siRtrn</emphasis> + return list contains the definitions for <emphasis> +nSIRtrn</emphasis> + symbol interpretations beginning at <emphasis> +firstSIRtrn</emphasis> +. +</para> + + +<para> +The <emphasis> +groupRtrn</emphasis> + return values report the entries in the group compatibility map for any groups +specified in the <emphasis> +groupsRtrn</emphasis> + return value. +</para> + + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbSetCompatMap</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +recomputeActions: BOOL</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +truncateSI: BOOL</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +groups: KB_GROUPMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstSI, nSI: CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +si: LISTofKB_SYMINTERPRET</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +groupMaps: LISTofKB_MODDEF</entry> + </row> + + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +, <emphasis> +Match</emphasis> +, <emphasis> +Value</emphasis> +, <emphasis> +Alloc</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +This request changes a specified subset of the compatibility map of the +keyboard indicated by <emphasis> +deviceSpec</emphasis> +. If <emphasis> +deviceSpec</emphasis> + specifies an invalid device, a <emphasis> +Keyboard</emphasis> + error results and nothing is changed. +</para> + + +<para> +The <emphasis> +firstSI</emphasis> + and <emphasis> +nSI</emphasis> + fields specify a subset of the keyboard symbol interpretations to be changed. +The <emphasis> +si</emphasis> + list specifies new values for each of the interpretations in that range. +</para> + + +<para> +The first symbol interpretation to be changed, <emphasis> +firstSI</emphasis> +, must be less than or equal to the unchanged length of the list of symbol +interpretations, or a <emphasis> +Value</emphasis> + error results. If the resulting list would be larger than the unchanged list, +it server list of symbol interpretations is automatically increased in size. +Otherwise, if <emphasis> +truncateSyms</emphasis> + is <emphasis> +True</emphasis> +, the server deletes any symbol interpretations after the last element changed +by this request, and reduces the length of the list accordingly. +</para> + + +<para> +The <emphasis> +groupMaps</emphasis> + fields contain new definitions for a subset of the group compatibility map; +<emphasis> +groups</emphasis> + specifies the group compatibility map entries to be updated from <emphasis> +groupMaps</emphasis> +. +</para> + + +<para> + All changed compatibility maps and symbol interpretations must either ignore +group state or specify a legal range of groups, or a <emphasis> +Value</emphasis> + error results. +</para> + + +<para> +If the <emphasis> +recomputeActions</emphasis> + field is <emphasis> +True</emphasis> +, the server regenerates recalculates the actions bound to all keyboard keys by +applying the new symbol interpretations to the entire key symbol map, as +described in <ulink url="XKBproto.htm#50332257_66444">See Assigning Actions To +Keys</ulink>. +</para> + + +</sect2> +<sect2 id='querying_and_changing_indicators'> +<title>Querying and Changing Indicators</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbGetIndicatorState</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +deviceID: CARD8 +state: KB_INDICATORMASK</entry> + </row> + + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +This request reports the current state of the indicators for the keyboard +specified by <emphasis> +deviceSpec</emphasis> +. If <emphasis> +deviceSpec</emphasis> + does not specify a valid keyboard, a <emphasis> +Keyboard</emphasis> + error results. +</para> + + +<para> +On successful return, the <emphasis> +deviceID</emphasis> + field reports the input extension identifier of the keyboard or <emphasis> +0</emphasis> + if the server does not support the input extension. The <emphasis> +state</emphasis> + return value reports the state of each of the thirty-two indicators on the +specified keyboard. The least-significant bit corresponds to indicator 0, the +most significant bit to indicator 31; if a bit is set, the corresponding +indicator is lit. +</para> + + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbGetIndicatorMap</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +which: KB_INDICATORMASK + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +deviceID: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +which: KB_INDICATORMASK + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +realIndicators: KB_INDICATORMASK + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +nIndicators: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +maps: LISTofKB_INDICATORMAP</entry> + </row> + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +, <emphasis> +Value</emphasis> +</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +This request returns a subset of the maps for the indicators on the keyboard +specified by <emphasis> +deviceSpec</emphasis> +. If <emphasis> +deviceSpec</emphasis> + does not specify a valid keyboard device, a <emphasis> +Keyboard</emphasis> + error results. +</para> + + +<para> +The <emphasis> +which</emphasis> + field specifies the subset to be returned; a set bit in the which field +indicates that the map for the corresponding indicator should be returned. +</para> + + +<para> +On successful return, the <emphasis> +deviceID</emphasis> + field reports the input extension identifier of the keyboard or <emphasis> +0</emphasis> + if the server does not support the input extension. Any indicators specified +in <emphasis> +realIndicators</emphasis> + are actually present on the keyboard; the rest are virtual indicators. Virtual +indicators do not directly cause any visible or audible effect when they change +state, but they do cause <emphasis> +XkbIndicatorStateNotify</emphasis> + events. +</para> + + +<para> +The <emphasis> +maps</emphasis> + return value reports the requested indicator maps. Indicator maps are +described in <ulink url="XKBproto.htm#50332257_36844">See Indicator Maps</ulink> +</para> + + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbSetIndicatorMap</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +which: KB_INDICATORMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +maps: LISTofKB_INDICATORMAP</entry> + </row> + + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +, <emphasis> +Value</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +This request changes a subset of the maps on the keyboard specified by +<emphasis> +deviceSpec</emphasis> +. If <emphasis> +deviceSpec</emphasis> + does not specify a valid keyboard device, a <emphasis> +Keyboard</emphasis> + error results. +</para> + + +<para> +The <emphasis> +which</emphasis> + field specifies the subset to be changed; the <emphasis> +maps</emphasis> + field contains the new definitions. +</para> + + +<para> +If successful, the new indicator maps are applied immediately. If any +indicators change state as a result of the new maps, the server generates +<emphasis> +XkbIndicatorStateNotify</emphasis> + events as appropriate. +</para> + + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbGetNamedIndicator</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +ledClass: KB_LEDCLASSSPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +ledID: KB_IDSPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +indicator: ATOM + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +deviceID: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +supported: BOOL + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +indicator: ATOM + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +found: BOOL + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +on: BOOL + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +realIndicator: BOOL + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +ndx: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +map: KB_INDICATORMAP</entry> + </row> + + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +, <emphasis> +Atom</emphasis> +, <emphasis> +Value</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +This request returns information about the indicator specified by <emphasis> +ledClass</emphasis> +, <emphasis> +ledID</emphasis> +, and <emphasis> +indicator</emphasis> + on the keyboard specified by <emphasis> +deviceSpec</emphasis> +. The <emphasis> +indicator</emphasis> + field specifies the name of the indicator for which information is to be +returned. +</para> + + +<para> +If <emphasis> +deviceSpec</emphasis> + does not specify a device with indicators, a <emphasis> +Keyboard</emphasis> + error results. If <emphasis> +ledClass</emphasis> + does not have the value <emphasis> +DfltXIClass</emphasis> +, <emphasis> +LedFeedbackClass</emphasis> +, or <emphasis> +KbdFeedbackClass</emphasis> +, a <emphasis> +Value</emphasis> + error results. If <emphasis> +ledID</emphasis> + does not have the value <emphasis> +DfltXIId</emphasis> + or specify the identifier of a feedback of the class specified by <emphasis> +ledClass</emphasis> + on the device specified by <emphasis> +deviceSpec</emphasis> +, a <emphasis> +Match</emphasis> + error results. If <emphasis> +indicator</emphasis> + is not a valid ATOM other than <emphasis> +None</emphasis> +, an <emphasis> +Atom</emphasis> + error results. +</para> + + +<para> +This request is always supported with default class and identifier on the core +keyboard device. If the request specifies a device other than the core keyboard +device or a feedback class and identifier other than the defaults, and the +server does not support indicator names or indicator maps for extension +devices, the <emphasis> +supported</emphasis> + return value is <emphasis> +False</emphasis> + and the values of the other fields in the reply are undefined. If the client +which issued the unsupported request has also selected to do so, it will also +receive an <emphasis> +XkbExtensionDeviceNotify</emphasis> + event which reports the attempt to use an unsupported feature, in this case +one or both of <emphasis> +XkbXI_IndicatorMaps</emphasis> + or <emphasis> +XkbXI_IndicatorNames</emphasis> +. +</para> + + +<para> +Otherwise, <emphasis> +supported</emphasis> + is <emphasis> +True</emphasis> + and the <emphasis> +deviceID</emphasis> + field reports the input extension identifier of the keyboard or <emphasis> +0</emphasis> + if the server does not support the input extension. The <emphasis> +indicator</emphasis> + return value reports the name for which information was requested and the +<emphasis> +found</emphasis> + return value is <emphasis> +True</emphasis> + if an indicator with the specified name was found on the device. +</para> + + +<para> +If a matching indicator was found: +</para> + +<itemizedlist> +<listitem> + <para>The <emphasis> +on</emphasis> + return value reports the state of the indicator at the time of the request. + </para> +</listitem> +<listitem> + <para>The <emphasis> +realIndicator</emphasis> + return value is <emphasis> +True</emphasis> + if the requested indicator is actually present on the keyboard or <emphasis> +False</emphasis> + if it is virtual. + </para> +</listitem> +<listitem> + <para>The <emphasis> +ndx</emphasis> + return value reports the index of the indicator in the requested feedback. + </para> +</listitem> +<listitem> + <para>The <emphasis> +map</emphasis> + return value reports the indicator map used by to automatically change the +state of the specified indicator in response to changes in keyboard state or +controls. + </para> +</listitem> +</itemizedlist> + +<para> +If no matching indicator is found, the <emphasis> +found</emphasis> + return value is <emphasis> +False</emphasis> +, and the <emphasis> +on</emphasis> +, <emphasis> +realIndicator</emphasis> +, <emphasis> +ndx</emphasis> +, and <emphasis> +map</emphasis> + return values are undefined. +</para> + + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbSetNamedIndicator</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +ledClass: KB_LEDCLASSSPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +ledID: KB_IDSPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +indicator: ATOM</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +setState: BOOL</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +on: BOOL</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +setMap: BOOL</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +createMap: BOOL</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +map: KB_SETINDICATORMAP</entry> + </row> + + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +, <emphasis> +Atom</emphasis> +, <emphasis> +Access</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +This request changes various aspects of the indicator specified by <emphasis> +ledClass</emphasis> +, <emphasis> +ledID</emphasis> +, and <emphasis> +indicator</emphasis> + on the keyboard specified by <emphasis> +deviceSpec</emphasis> +. The <emphasis> +indicator</emphasis> + argument specifies the name of the indicator to be updated. +</para> + + +<para> +If <emphasis> +deviceSpec</emphasis> + does not specify a device with indicators, a <emphasis> +Keyboard</emphasis> + error results. If <emphasis> +ledClass</emphasis> + does not have the value <emphasis> +DfltXIClass</emphasis> +, <emphasis> +LedFeedbackClass</emphasis> +, or <emphasis> +KbdFeedbackClass</emphasis> +, a <emphasis> +Value</emphasis> + error results. If <emphasis> +ledID</emphasis> + does not have the value <emphasis> +DfltXIId</emphasis> + or specify the identifier of a feedback of the class specified by <emphasis> +ledClass</emphasis> + on the device specified by <emphasis> +deviceSpec</emphasis> +, a <emphasis> +Match</emphasis> + error results. If <emphasis> +indicator</emphasis> + is not a valid ATOM other than <emphasis> +None</emphasis> +, an <emphasis> +Atom</emphasis> + error results. +</para> + + +<para> +This request is always supported with default class and identifier on the core +keyboard device. If the request specifies a device other than the core keyboard +device or a feedback class and identifier other than the defaults, and the +server does not support indicator names or indicator maps for extension +devices, the <emphasis> +supported</emphasis> + return value is <emphasis> +False</emphasis> + and the values of the other fields in the reply are undefined. If the client +which issued the unsupported request has also selected to do so, it will also +receive an <emphasis> +XkbExtensionDeviceNotify</emphasis> + event which reports the attempt to use an unsupported feature, in this case +one or both of <emphasis> +XkbXI_IndicatorMaps</emphasis> + and <emphasis> +XkbXI_IndicatorNames</emphasis> +. +</para> + + +<para> +Otherwise, <emphasis> +supported</emphasis> + is <emphasis> +True</emphasis> + and the <emphasis> +deviceID</emphasis> + field reports the input extension identifier of the keyboard or <emphasis> +0</emphasis> + if the server does not support the input extension. The <emphasis> +indicator</emphasis> + return value reports the name for which information was requested and the +<emphasis> +found</emphasis> + return value is <emphasis> +True</emphasis> + if an indicator with the specified name was found on the device. +</para> + + +<para> +If no indicator with the specified name is found on the specified device, and +the <emphasis> +createMap</emphasis> + field is <emphasis> +True</emphasis> +, XKB assigns the specified name to the lowest-numbered indicator that has no +name (i.e. whose name is <emphasis> +None</emphasis> +) and applies the rest of the fields in the request to the newly named +indicator. If no unnamed indicators remain, this request reports no error and +has no effect. +</para> + + +<para> +If no matching indicator is found or new indicator assigned this request +reports no error and has no effect. Otherwise, it updates the indicator as +follows: +</para> + + +<para> +If <emphasis> +setMap </emphasis> +is <emphasis> +True</emphasis> +, XKB changes the map for the indicator (see <ulink +url="XKBproto.htm#50332257_36844">See Indicator Maps</ulink>) to reflect the +values specified in <emphasis> +map</emphasis> +. +</para> + + +<para> +If <emphasis> +setState</emphasis> + is <emphasis> +True</emphasis> +, XKB attempts to explicitly change the state of the indicator to the state +specified in <emphasis> +on</emphasis> +. The effects of an attempt to explicitly change the state of an indicator +depend on the values in the map for that indicator and are not guaranteed to +succeed. +</para> + + +<para> +If this request affects both indicator map and state, it updates the indicator +map before attempting to change its state, so the success of the explicit +change depends on the indicator map values specified in the request. +</para> + + +<para> +If this request changes the indicator map, it applies the new map immediately +to determine the appropriate state for the indicator given the new indicator +map and the current state of the keyboard. +</para> + + +</sect2> +<sect2 id='querying_and_changing_symbolic_names'> +<title>Querying and Changing Symbolic Names</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbGetNames</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +which: KB_NAMEDETAILMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +deviceID: CARD8 +which: KB_NAMESMASK +minKeyCode, maxKeyCode: KEYCODE +nTypes: CARD8 +nKTLevels: CARD16 +groupNames: KB_GROUPMASK +virtualMods: KB_VMODMASK +firstKey: KEYCODE +nKeys: CARD8 +indicators: KB_INDICATORMASK +nRadioGroups, nKeyAliases: CARD8 +present: KB_NAMEDETAILMASK +valueList: LISTofITEMs</entry> + </row> + + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +, <emphasis> +Value</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +This request returns the symbolic names for various components of the keyboard +mapping for the device specified by <emphasis> +deviceSpec</emphasis> +. The <emphasis> +which</emphasis> + field specifies the keyboard components for which names are to be returned. If +<emphasis> +deviceSpec</emphasis> + does not specify a valid keyboard device, a <emphasis> +Keyboard</emphasis> + error results. If any undefined bits in <emphasis> +which</emphasis> + are non-zero, a <emphasis> +Value</emphasis> + error results. +</para> + + +<para> +The <emphasis> +deviceID</emphasis> + return value contains the X Input Extension device identifier of the specified +device or <emphasis> +0</emphasis> + if the server does not support the input extension. The <emphasis> +present</emphasis> + and <emphasis> +valueList</emphasis> + return values specify the components for which names are being reported. If a +component is specified in <emphasis> +present</emphasis> +, the corresponding element is present in the <emphasis> +valueList</emphasis> +, otherwise that component has length <emphasis> +0</emphasis> +. The components of the <emphasis> +valueList</emphasis> + appear in the following order, when present:. +</para> + +<informaltable frame='none'> +<tgroup cols='3'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Component</entry> + <entry>Size</entry> + <entry>Type</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis> +XkbKeycodesName</emphasis> +</entry> + <entry>1</entry> + <entry> ATOM</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbGeometryName</emphasis> +</entry> + <entry>1</entry> + <entry> ATOM</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbSymbolsName</emphasis> +</entry> + <entry>1</entry> + <entry> ATOM</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbPhysSymbolsName</emphasis> +</entry> + <entry>1</entry> + <entry> ATOM</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbTypesName</emphasis> +</entry> + <entry>1</entry> + <entry> ATOM</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbCompatName</emphasis> +</entry> + <entry>1</entry> + <entry> ATOM</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbKeyTypeNames</emphasis> + </entry> + <entry><emphasis> +nTypes</emphasis> +</entry> + <entry> LISTofATOM</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbKTLevelNames</emphasis> + </entry> + <entry><emphasis> +nTypes</emphasis> +, +<emphasis> +nKTLevels</emphasis> +</entry> + <entry>{ count: LISTofCARD8, + names: LISTofATOM }</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbIndicatorNames</emphasis> + </entry> + <entry>One per bit set in <emphasis> +indicators</emphasis> +</entry> + <entry> LISTofATOM</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbVirtualModNames</emphasis> + </entry> + <entry>One per bit set in <emphasis> +virtualMods</emphasis> +</entry> + <entry> LISTofATOM</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbGroupNames </emphasis> +</entry> + <entry>One per bit set in <emphasis> +groupNames</emphasis> +</entry> + <entry> LISTofATOM</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbKeyNames</emphasis> +</entry> + <entry><emphasis> +nKeys</emphasis> +</entry> + <entry> LISTofKB_KEYNAME</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbKeyAliases</emphasis> +</entry> + <entry><emphasis> +nKeyAliases</emphasis> +</entry> + <entry> LISTofKB_KEYALIAS</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbRGNames</emphasis> +</entry> + <entry><emphasis> +nRadioGroups</emphasis> +</entry> + <entry> LISTofATOM</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +If type names are reported, the <emphasis> +nTypes</emphasis> + return value reports the number of types defined for the keyboard, and the +list of key type names in <emphasis> +valueList</emphasis> + has <emphasis> +nTypes</emphasis> + elements. +</para> + + +<para> +If key type level names are reported, the list of key type level names in the +<emphasis> +valueList</emphasis> + has two parts: The <emphasis> +count</emphasis> + array has <emphasis> +nTypes</emphasis> + elements, each of which reports the number of level names reported for the +corresponding key type. The <emphasis> +names</emphasis> + array has <emphasis> +nKTLevels</emphasis> + atoms and reports the names of each type sequentially. The <emphasis> +nKTLevels</emphasis> + return value is always equal to the sum of all of the elements of the +<emphasis> +count</emphasis> + array. +</para> + + +<para> +If indicator names are reported, the <emphasis> +indicators</emphasis> + mask specifies the indicators for which names are defined; any indicators not +specified in <emphasis> +indicators</emphasis> + have the name <emphasis> +None</emphasis> +. The list of indicator names in <emphasis> +valueList</emphasis> + contains the names of the listed indicators, beginning with the +lowest-numbered indicator for which a name is defined and proceeding to the +highest. +</para> + + +<para> +If virtual modifier names are reported, the <emphasis> +virtualMods</emphasis> + mask specifies the virtual modifiers for which names are defined; any virtual +modifiers not specified in <emphasis> +virtualMods</emphasis> + have the name <emphasis> +None</emphasis> +. The list of virtual modifier names in <emphasis> +valueList</emphasis> + contains the names of the listed virtual modifiers, beginning with the +lowest-numbered virtual modifier for which a name is defined and proceeding to +the highest. +</para> + + +<para> +If group names are reported, the <emphasis> +groupNames</emphasis> + mask specifies the groups for which names are defined; any groups not +specified in <emphasis> +groupNames</emphasis> + have the name <emphasis> +None</emphasis> +. The list of group names in <emphasis> +valueList</emphasis> + contains the names of the listed groups, beginning with the lowest-numbered +group for which a name is defined and proceeding to the highest. +</para> + + +<para> +If key names are reported, the <emphasis> +firstKey</emphasis> + and <emphasis> +nKeys</emphasis> + return values specify a range of keys which includes all keys for which names +are defined; any key that does not fall in the range specified by <emphasis> +firstKey</emphasis> + and <emphasis> +nKeys</emphasis> + has the name <emphasis> +NullKeyName</emphasis> +. The list of key names in the <emphasis> +valueList</emphasis> + has <emphasis> +nKeys</emphasis> + entries and specifies the names of the keys beginning at <emphasis> +firstKey</emphasis> +. +</para> + + +<para> +If key aliases are reported, the <emphasis> +nKeyAliases</emphasis> + return value specifies the total number of key aliases defined for the +keyboard. The list of key aliases in <emphasis> +valueList</emphasis> + has <emphasis> +nKeyAliases</emphasis> + entries, each of which reports an alias and the real name of the key to which +it corresponds. +</para> + + +<para> +If radio group names are reported, the <emphasis> +nRadioGroups</emphasis> + return value specifies the number of radio groups on the keyboard for which +names are defined. The list of radio group names in <emphasis> +valueList</emphasis> + reports the names of each group and has <emphasis> +nRadioGroups</emphasis> + entries. +</para> + + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbSetNames</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoargs'>which: KB_NAMEDETAILMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +virtualMods: KB_VMODMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstType, nTypes: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstKTLevel, nKTLevels: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +totalKTLevelNames: CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +indicators: KB_INDICATORMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +groupNames: KB_GROUPMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +nRadioGroups: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstKey: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +nKeys, nKeyAliases: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +valueList: LISTofITEMs</entry> + </row> + + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +, <emphasis> +Atom</emphasis> +, <emphasis> +Value</emphasis> +, <emphasis> +Match</emphasis> +, <emphasis> +Alloc</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +This request changes the symbolic names for the requested components of the +keyboard specified by <emphasis> +deviceSpec</emphasis> +. The <emphasis> +which</emphasis> + field specifies the components for which one or more names are to be updated. +If <emphasis> +deviceSpec</emphasis> + does not specify a valid keyboard device, a <emphasis> +Keyboard</emphasis> + error results. If any undefined bits in <emphasis> +which</emphasis> + are non-zero, a <emphasis> +Value</emphasis> + error results. If any error (other than <emphasis> +Alloc</emphasis> + or <emphasis> +Implementation</emphasis> +) occurs, this request returns without modifying any names. +</para> + + +<para> +The <emphasis> +which</emphasis> + and <emphasis> +valueList</emphasis> + fields specify the components to be changed; the type of each <emphasis> +valueList</emphasis> + entry, the order in which components appear in the <emphasis> +valueList</emphasis> + when specified, and the correspondence between components in <emphasis> +which</emphasis> + and the entries in the <emphasis> +valueList</emphasis> + are as specified for the <emphasis> +XkbGetNames</emphasis> + request. +</para> + + +<para> +If keycodes, geometry, symbols, physical symbols, types or compatibility map +names are to be changed, the corresponding entries in the <emphasis> +valueList</emphasis> + must have the value <emphasis> +None</emphasis> + or specify a valid ATOM, else an <emphasis> +Atom</emphasis> + error occurs. +</para> + + +<para> +If key type names are to be changed, the <emphasis> +firstType</emphasis> + and <emphasis> +nTypes</emphasis> + fields specify a range of types for which new names are supplied, and the list +of key type names in <emphasis> +valueList</emphasis> + has <emphasis> +nTypes</emphasis> + elements. Names for types that fall outside of the range specified by +<emphasis> +firstType</emphasis> + and <emphasis> +nTypes</emphasis> + are not affected. If this request specifies names for types that are not +present on the keyboard, a <emphasis> +Match</emphasis> + error results. All of the type names in the <emphasis> +valueList</emphasis> + must be valid ATOMs or have the value <emphasis> +None</emphasis> +, or an <emphasis> +Atom</emphasis> + error results. +</para> + + +<para> +The names of the first four keyboard types are specified by the XKB extension +and cannot be changed; including any of the canonical types in this request +causes an <emphasis> +Access</emphasis> + error, as does trying to assign the name reserved for a canonical type to one +of the other key types. +</para> + + +<para> +If key type level names are to be changed, the <emphasis> +firstKTLevel</emphasis> + and <emphasis> +nKTLevels</emphasis> + fields specify a range of key types for which new level names are supplied, +and the list of key type level names in the <emphasis> +valueList</emphasis> + has two parts: The <emphasis> +count</emphasis> + array has <emphasis> +nKTLevels</emphasis> + elements, each of which specifies the number of levels for which names are +supplied on the corresponding key type; any levels for which no names are +specified are assigned the name <emphasis> +None</emphasis> +. The <emphasis> +names</emphasis> + array has <emphasis> +totalKTLevels</emphasis> + atoms and specifies the names of each type sequentially. The <emphasis> +totalKTLevels</emphasis> + field must always equal the sum of all of the elements of the <emphasis> +count</emphasis> + array. Level names for types that fall outside of the specified range are not +affected. If this request specifies level names for types that are not present +on the keyboard, or if it specifies more names for a type than the type has +levels, a <emphasis> +Match</emphasis> + error results. All specified type level names must be <emphasis> +None</emphasis> + or a valid ATOM or an <emphasis> +Atom</emphasis> + error results. +</para> + + +<para> +If indicator names are to be changed, the <emphasis> +indicators</emphasis> + mask specifies the indicators for which new names are specified; the names for +indicators not specified in <emphasis> +indicators</emphasis> + are not affected. The list of indicator names in <emphasis> +valueList</emphasis> + contains the new names for the listed indicators, beginning with the +lowest-numbered indicator for which a name is defined and proceeding to the +highest. All specified indicator names must be a valid ATOM or <emphasis> +None</emphasis> +, or an <emphasis> +Atom</emphasis> + error results. +</para> + + +<para> +If virtual modifier names are to be changed, the <emphasis> +virtualMods</emphasis> + mask specifies the virtual modifiers for which new names are specified; names +for any virtual modifiers not specified in <emphasis> +virtualMods</emphasis> + are not affected. The list of virtual modifier names in <emphasis> +valueList</emphasis> + contains the new names for the specified virtual modifiers, beginning with the +lowest-numbered virtual modifier for which a name is defined and proceeding to +the highest. All virtual modifier names must be valid ATOMs or <emphasis> +None</emphasis> +, or an <emphasis> +Atom</emphasis> + error results. +</para> + + +<para> +If group names are to be changed, the <emphasis> +groupNames</emphasis> + mask specifies the groups for which new names are specified; the name of any +group not specified in <emphasis> +groupNames</emphasis> + is not changed. The list of group names in <emphasis> +valueList</emphasis> + contains the new names for the listed groups, beginning with the +lowest-numbered group for which a name is defined and proceeding to the +highest. All specified group names must be a valid ATOM or <emphasis> +None</emphasis> +, or an <emphasis> +Atom</emphasis> + error results. +</para> + + +<para> +If key names are to be changed, the <emphasis> +firstKey</emphasis> + and <emphasis> +nKeys</emphasis> + fields specify a range of keys for which new names are defined; the name of +any key that does not fall in the range specified by <emphasis> +firstKey</emphasis> + and <emphasis> +nKeys</emphasis> + is not changed. The list of key names in the <emphasis> +valueList</emphasis> + has <emphasis> +nKeys</emphasis> + entries and specifies the names of the keys beginning at <emphasis> +firstKey</emphasis> +. +</para> + + +<para> +If key aliases are to be changed, the <emphasis> +nKeyAliases</emphasis> + field specifies the length of a new list of key aliases for the keyboard. The +list of key aliases can only be replaced in its entirety; it cannot be +replaced. The list of key aliases in <emphasis> +valueList</emphasis> + has <emphasis> +nKeyAliases</emphasis> + entries, each of which reports an alias and the real name of the key to which +it corresponds. +</para> + + +<para> +XKB does not check key names or aliases for consistency and validity, so +applications should take care not to assign duplicate names or aliases +</para> + + +<para> +If radio group names are to be changed, the <emphasis> +nRadioGroups</emphasis> + field specifies the length of a new list of radio group names for the +keyboard. There is no way to edit the list of radio group names; it can only be +replaced in its entirety. The list of radio group names in <emphasis> +valueList</emphasis> + reports the names of each group and has <emphasis> +nRadioGroups</emphasis> + entries. If the list of radio group names specifies names for more radio +groups than XKB allows (32), a <emphasis> +Match</emphasis> + error results. All specified radio group names must be valid ATOMs or have the +value <emphasis> +None</emphasis> +, or an <emphasis> +Atom</emphasis> + error results. +</para> + + +</sect2> +<sect2 id='querying_and_changing_keyboard_geometry'> +<title>Querying and Changing Keyboard Geometry</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbGetGeometry</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC + </entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +name: ATOM</entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +deviceID: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +name: ATOM + </entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +found: BOOL + </entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +widthMM, heightMM: CARD16 + </entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +baseColorNdx, labelColorNdx: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +properties: LISTofKB_PROPERTY + </entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +colors: LISTofSTRING8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +shapes: LISTofKB_SHAPE + </entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +sections: LISTofKB_SECTION + </entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +doodads: LISTofKB_DOODAD + </entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +keyAliases: LISTofKB_KEYALIAS</entry> + </row> + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +This request returns a description of the physical layout of a keyboard. If the +<emphasis> +name</emphasis> + field has the value <emphasis> +None</emphasis> +, or if name is identical to the name of the geometry for the keyboard +specified by <emphasis> +deviceSpec</emphasis> +, this request returns the geometry of the keyboard specified by <emphasis> +deviceSpec</emphasis> +; otherwise, if <emphasis> +name</emphasis> + is a valid atom other than <emphasis> +None</emphasis> +, the server returns the keyboard geometry description with that name in the +server database of keyboard components (see <ulink +url="XKBproto.htm#50332257_46669">See The Server Database of Keyboard +Components</ulink>) if one exists. If <emphasis> +deviceSpec</emphasis> + does not specify a valid keyboard device, a <emphasis> +Keyboard</emphasis> + error results. If <emphasis> +name</emphasis> + has a value other than <emphasis> +None</emphasis> + or a valid ATOM, an <emphasis> +Atom</emphasis> + error results. +</para> + + +<para> +On successful return, the <emphasis> +deviceID</emphasis> + field reports the X Input extension identifier of the keyboard device +specified in the request, or <emphasis> +0</emphasis> + if the server does not support the input extension. +</para> + + +<para> +The <emphasis> +found</emphasis> + return value reports whether the requested geometry was available. If +<emphasis> +found</emphasis> + is <emphasis> +False</emphasis> +, no matching geometry was found and the remaining fields in the request reply +are undefined; if <emphasis> +found</emphasis> + is <emphasis> +True</emphasis> +, the remaining fields of the reply describe the requested keyboard geometry. +The interpretation of the components that make up a keyboard geometry is +described in detail in <ulink url="XKBproto.htm#50332257_23341">See Keyboard +Geometry</ulink> +</para> + + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbSetGeometry</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +name: ATOM</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +widthMM, heightMM, CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +baseColorNdx, labelColorNdx: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +shapes: LISTofKB_SHAPE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +sections: LISTofKB_SECTION</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +properties: LISTofKB_PROPERTY</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +colors: LISTofSTRING8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +doodads: LISTofKB_DOODAD</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +keyAliases: LISTofKB_KEYALIAS</entry> + </row> + + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +, <emphasis> +Atom</emphasis> +, <emphasis> +Value</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +This request changes the reported description of the geometry for the keyboard +specified by <emphasis> +deviceSpec</emphasis> +. If deviceSpec does not specify a valid keyboard device, a <emphasis> +Keyboard</emphasis> + error results. +</para> + + +<para> +The <emphasis> +name</emphasis> + field specifies the name of the new keyboard geometry and must be a valid ATOM +or an <emphasis> +Atom</emphasis> + error results. The new geometry is not added to the server database of +keyboard components, but it can be retrieved using the <emphasis> +XkbGetGeometry</emphasis> + request for as long as it is bound to the keyboard. The keyboard geometry +symbolic name is also updated from the name field, and an <emphasis> +XkbNamesNotify</emphasis> + event is generated, if necessary. +</para> + + +<para> +The list of <emphasis> +colors</emphasis> + must include at least two definitions, or a <emphasis> +Value</emphasis> + error results. All color definitions in the geometry must specify a legal +color (i.e. must specify a valid index for one of the entries of the <emphasis> +colors</emphasis> + list) or a <emphasis> +Match</emphasis> + error results. The <emphasis> +baseColorNdx</emphasis> + and the <emphasis> +labelColorNdx</emphasis> + must be different or a <emphasis> +Match</emphasis> + error results. +</para> + + +<para> +The list of <emphasis> +shapes</emphasis> + must include at least one shape definition, or a <emphasis> +Value</emphasis> + error results. If any two shapes have the same name, a <emphasis> +Match</emphasis> + error result. All doodads and keys which specify shape must specify a valid +index for one of the elements of the <emphasis> +shapes</emphasis> + list, or a <emphasis> +Match</emphasis> + error results. +</para> + + +<para> +All section, shape and doodad names must be valid ATOMs or an <emphasis> +Atom</emphasis> + error results; the constant <emphasis> +None</emphasis> + is not permitted for any of these components. +</para> + + +<para> +All doodads must be of a known type; XKB does not support "private" doodad +types. +</para> + + +<para> +If, after rotation, any keys or doodads fall outside of the bounding box for a +section, the bounding box is automatically adjusted to the minimum size which +encloses all of its components. +</para> + + +<para> +If, after adjustment and rotation, the bounding box of any section or doodad +extends below zero on either the X or Y axes, the entire geometry is translated +so that the minimum extent along either axis is zero. +</para> + + +<para> +If, after rotation and translation, any keyboard components fall outside of the +rectangle specified by <emphasis> +widthMM</emphasis> + and <emphasis> +heightMM</emphasis> +, the keyboard dimensions are automatically resized to the minimum bounding box +that surrounds all components. Otherwise, the width and height of the keyboard +are left as specified. +</para> + + +<para> +The <emphasis> +under</emphasis> + field of any overlay key definitions must specify a key that is in the section +that contains the overlay key, or a <emphasis> +Match</emphasis> + error results. This request does not check the value of the <emphasis> +over</emphasis> + field of an overlay key definition, so applications must be careful to avoid +conflicts with actual keys. +</para> + + +<para> +This request does not verify that key names or aliases are unique. It also does +not verify that all key names specified in the geometry are bound to some +keycode or that all keys that are named in the keyboard definition are also +available in the geometry. Applications should make sure that keyboard geometry +has no internal conflicts and is consistent with the other components of the +keyboard definition, but XKB does not check for or guarantee it. +</para> + + +</sect2> +<sect2 id='querying_and_changing_per_client_flags'> +<title>Querying and Changing Per-Client Flags</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbPerClientFlags</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +change: KB_PCFMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +value: KB_PCFMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +ctrlsToChange: KB_BOOLCTRLMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +autoCtrls: KB_BOOLCTRLMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +autoCtrlValues: KB_BOOLCTRLMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +deviceID: CARD8 +supported: KB_PCFMASK +value: KB_PCFMASK +autoCtrls: KB_BOOLCTRLMASK +autoCtrlValues: KB_BOOLCTRLMASK +where: KB_PCFMASK:</entry> + </row> + + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +, <emphasis> +Value</emphasis> +, <emphasis> +Match</emphasis> +, <emphasis> +Alloc</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +Changes the client specific flags for the keyboard specified by <emphasis> +deviceSpec</emphasis> +. Reports a <emphasis> +Keyboard</emphasis> + error if <emphasis> +deviceSpec</emphasis> + does not specify a valid keyboard device. +</para> + + +<para> +Any flags specified in <emphasis> +change</emphasis> + are set to the corresponding values in <emphasis> +value</emphasis> +, provided that the server supports the requested control. Legal +per-client-flags are: +</para> + +<informaltable frame='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Flag…</entry> + <entry>Described in…</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis> +XkbPCF_DetectableAutorepeat</emphasis> +</entry> + <entry><ulink url="XKBproto.htm#50332257_79074">See Detectable +Autorepeat</ulink></entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbPCF_GrabsUseXKBStateMask</emphasis> +</entry> + <entry><ulink url="XKBproto.htm#50332257_83380">See Setting a Passive Grab +for an XKB State</ulink></entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbPCF_AutoResetControlsMask</emphasis> +</entry> + <entry><ulink url="XKBproto.htm#50332257_29682">See Automatic Reset of +Boolean Controls</ulink></entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbPCF_LookupStateWhenGrabbed</emphasis> +</entry> + <entry><ulink url="XKBproto.htm#50332257_39705">See Effects of XKB on Core +Protocol Events</ulink></entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbPCF_SendEventUsesXKBState</emphasis> +</entry> + <entry><ulink url="XKBproto.htm#50332257_67792">See Sending Events to +Clients</ulink></entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +If <emphasis> +PCF_AutoResetControls</emphasis> + is set in both <emphasis> +change</emphasis> + and <emphasis> +value</emphasis> +, the client’s mask of controls to be changed is updated from <emphasis> +ctrlsToChange</emphasis> +, <emphasis> +autoCtrls</emphasis> +, and <emphasis> +autoCtrlValues</emphasis> +. Any controls specified in <emphasis> +ctrlsToChange</emphasis> + are modified in the auto-reset controls mask for the client; the corresponding +bits from the <emphasis> +autoCtrls</emphasis> + field are copied into the auto-reset controls mask and the corresponding bits +from <emphasis> +autoCtrlValues</emphasis> + are copied into the auto-reset controls state values. If any controls are +specified in <emphasis> +autoCtrlValues</emphasis> + but not in <emphasis> +autoCtrls</emphasis> +, a <emphasis> +Match</emphasis> + error results. If any controls are specified in <emphasis> +autoCtrls</emphasis> + but not in <emphasis> +ctrlsToChange</emphasis> +, a <emphasis> +Match</emphasis> + error results. +</para> + + +<para> +If <emphasis> +PCF_AutoResetControls</emphasis> + is set in <emphasis> +change</emphasis> + but not in <emphasis> +value</emphasis> +, the client’s mask of controls to be changed is reset to all zeroes (i.e. +the client does not change any controls when it exits). +</para> + + +<para> +This request reports a <emphasis> +Match</emphasis> + error if a bit is set in any of the value masks but not in the control mask +that governs it or a <emphasis> +Value</emphasis> + error if any undefined bits are set in any of the masks. +</para> + + +<para> +On successful return, the <emphasis> +deviceID</emphasis> + field reports the X Input extension identifier of the keyboard, or <emphasis> +0</emphasis> + if the server does not support the X Input Extension. +</para> + + +<para> +The <emphasis> +supported</emphasis> + return value reports the set of per-client flags that are supported by the +server; in this version of XKB, only the <emphasis> +XkbPCF_DetectableAutorepeat</emphasis> + per-client flag is optional; all other per-client flags must be supported. +</para> + + +<para> +The <emphasis> +value</emphasis> + return value reports the current settings of all per-client flags for the +specified keyboard. The <emphasis> +autoCtrls</emphasis> + return value reports the current set of controls to be reset when the client +exits, while the <emphasis> +autoCtrlValues</emphasis> + return value reports the state to which they should be set. +</para> + + +</sect2> +<sect2 id='using_the_servers_database_of_keyboard_components'> +<title>Using the Server’s Database of Keyboard Components</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbListComponents</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +maxNames: CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +keymapsSpec: STRING8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +keycodesSpec: STRING8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +typesSpec: STRING8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +compatMapSpec: STRING8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +symbolsSpec: STRING8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +geometrySpec: STRING8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +deviceID: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +extra: CARD16 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +keymaps,keycodes,types,compatMaps: LISTofKB_COMPONENTNAME + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +symbols, geometries: LISTofKB_COMPONENTNAME</entry> + </row> + <row rowsep='0'> + <entry role='protoreply'>Where:</entry> + </row> + <row rowsep='0'> + <entry role='protoreply'>KB_COMPONENTNAME { hints: CARD8, name: +STRING8 }</entry> + </row> + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +, <emphasis> +Alloc</emphasis> +</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +This request returns one or more lists of keyboard components that are +available from the X server database of keyboard components for the device +specified by <emphasis> +deviceSpec</emphasis> +. The X server is allowed, but not required or expected, to maintain separate +databases for each keyboard device. A <emphasis> +Keyboard</emphasis> + error results if <emphasis> +deviceSpec</emphasis> + does not specify a valid keyboard device. +</para> + + +<para> +The <emphasis> +maxNames</emphasis> + field specifies the maximum number of component names to be reported, in +total, by this request. +</para> + + +<para> +The <emphasis> +keymapsSpec</emphasis> +, <emphasis> +keycodesSpec</emphasis> +, <emphasis> +typesSpec</emphasis> +, <emphasis> +compatMapSpec</emphasis> +, <emphasis> +symbolsSpec</emphasis> + and <emphasis> +geometrySpec</emphasis> + request fields specify a pattern to be matched against the names of all +components of the corresponding type in the server database of keyboard +components. +</para> + + +<para> +Each pattern uses the ISO Latin-1 encoding and should contain only parentheses, +the wildcard characters "?" and "*" or characters that are permitted in a +component class or member name (see <ulink +url="XKBproto.htm#50332257_49632">See Component Names</ulink>). Illegal +characters in a pattern are simply ignored; no error results if a pattern +contains illegal characters. +</para> + + +<para> +Comparison is case-sensitive and, in a pattern, the "?" wildcard character +matches any single character except parentheses while the "*" character matches +any number of characters except parentheses. If an implementation accepts +characters other than those required by XKB, whether or not those characters +match either wildcard is also implementation dependent. An empty pattern does +not match any component names. +</para> + + +<para> +On successful return, the <emphasis> +deviceID</emphasis> + return value reports the X Input Extension device identifier of the specified +device, or <emphasis> +0</emphasis> + if the server does not support the X input extension. The <emphasis> +extra</emphasis> + return value reports the number of matching component names that could not be +returned due to the setting of the <emphasis> +maxNames</emphasis> + field in the request. +</para> + + +<para> +The <emphasis> +keymaps</emphasis> +, <emphasis> +keycodes</emphasis> +, <emphasis> +types</emphasis> +, <emphasis> +compatMaps</emphasis> +, <emphasis> +symbols</emphasis> + and <emphasis> +geometries</emphasis> + return the hints (see <ulink url="XKBproto.htm#50332257_98074">See Component +Hints</ulink>) and names of any components from the server database that match +the corresponding pattern. +</para> + + +<para> +<ulink url="XKBproto.htm#50332257_46669">See The Server Database of Keyboard +Components</ulink> describes the X server database of keyboard components in +more detail. +</para> + + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbGetKbdByName</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +need, want: KB_GBNDETAILMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +load: BOOL</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +keymapsSpec: STRING8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +keycodesSpec, typesSpec: STRING8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +compatMapSpec, symbolsSpec: STRING8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +geometrySpec: STRING8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +deviceID: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +minKeyCode, maxKeyCode: KEYCODE + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +loaded, newKeyboard: BOOL + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +found, reported: KB_GBNDETAILMASK + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +map: optional <emphasis> +XkbGetMap</emphasis> + reply + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +compat: optional <emphasis> +XkbGetCompatMap</emphasis> + reply + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +indicators: optional <emphasis> +XkbGetIndicatorMap</emphasis> + reply + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +names: optional <emphasis> +XkbGetNames</emphasis> + reply + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +geometry: optional <emphasis> +XkbGetGeometry</emphasis> + reply</entry> + </row> + + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Keyboard</emphasis> +, <emphasis> +Access</emphasis> +, <emphasis> +Alloc</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +Assembles and returns a keymap from the current mapping and specified elements +from the server database of keymap components for the keyboard specified by +<emphasis> +deviceSpec</emphasis> +, and optionally replaces the current keyboard mapping with the newly generated +description. If <emphasis> +deviceSpec</emphasis> + does not specify a valid keyboard device, a <emphasis> +Keyboard</emphasis> + error results. +</para> + + +<para> +The <emphasis> +keymapsSpec</emphasis> +, <emphasis> +keycodesSpec</emphasis> +, <emphasis> +typesSpec</emphasis> +, <emphasis> +compatMapSpec</emphasis> +, <emphasis> +symbolsSpec</emphasis> + and <emphasis> +geometrySpec</emphasis> + component expressions (see <ulink url="XKBproto.htm#50332257_26148">See +Partial Components and Combining Multiple Components</ulink>) specify the +database components to be used to assemble the keyboard description. +</para> + + +<para> +The <emphasis> +want</emphasis> + field lists the pieces of the keyboard description that the client wants to +have reported for the newly constructed keymap. The <emphasis> +need</emphasis> + field lists all of the pieces that must be reported. If any of the pieces in +<emphasis> +need</emphasis> + cannot be loaded from the specified names, no description of the keyboard is +returned. +</para> + + +<para> +The <emphasis> +want</emphasis> + and <emphasis> +need</emphasis> + fields can include any combinations of these <emphasis> +XkbGetMapByName</emphasis> + (GBN) components: +</para> + +<informaltable frame='none'> +<tgroup cols='3'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>XkbGetMapByName Keyboard Component…</entry> + <entry>Database Component…</entry> + <entry>Components of Keyboard Description</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis> +XkbGBN_Types</emphasis> +</entry> + <entry>types</entry> + <entry>key types</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbGBN_CompatMap</emphasis> +</entry> + <entry>compat</entry> + <entry>symbol interpretations, group compatibility map</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbGBN_ClientSymbols</emphasis> +</entry> + <entry>symbols, types, keycodes</entry> + <entry>key types, key symbol mappings, modifier mapping</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbGBN_ServerSymbols</emphasis> +</entry> + <entry>symbols, types, keycodes</entry> + <entry>key behaviors, key actions, key explicit components, virtual +modifiers, virtual modifier mapping</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbGBN_IndicatorMap</emphasis> +</entry> + <entry>compat</entry> + <entry>indicator maps, indicator names</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbGBN_KeyNames</emphasis> +</entry> + <entry>keycodes</entry> + <entry>key names, key aliases</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbGBN_Geometry</emphasis> +</entry> + <entry>geometry</entry> + <entry>keyboard geometry</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +XkbGBN_OtherNames</emphasis> +</entry> + <entry>all</entry> + <entry>key types, symbol interpretations, indicator maps, names, +geometry</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +If either field contains a GBN component that depends on some database +component for which the request does not supply an expression, XKB +automatically substitutes the special pattern "%" which copies the +corresponding component from the current keyboard description, as described in +<ulink url="XKBproto.htm#50332257_26148">See Partial Components and Combining +Multiple Components</ulink>. +</para> + + +<para> +The <emphasis> +load</emphasis> + flag asks the server to replace the current keyboard description for <emphasis> +deviceSpec</emphasis> + with the newly constructed keyboard description. If <emphasis> +load</emphasis> + is <emphasis> +True</emphasis> +, the request must include component expressions for all of the database +components; if any are missing, XKB substitutes "%" as described above. +</para> + + +<para> +If all necessary components are both specified and found, the new keyboard +description is loaded. If the new keyboard description has a different geometry +or keycode range than the previous keyboard description, XKB sends <emphasis> +XkbNewKeyboardNotify</emphasis> + events to all interested clients. See <ulink +url="XKBproto.htm#50332257_89133">See Replacing the Keyboard +"On-the-Fly"</ulink> for more information about the effects of replacing the +keyboard description on the fly. +</para> + + +<para> +If the range of keycodes changes, clients that have requested <emphasis> +XkbNewKeyboardNotify</emphasis> + events are not sent any other change notification events by this request. +Clients that do not request <emphasis> +XkbNewKeyboardNotify</emphasis> + events are sent other XKB change notification events (e.g. <emphasis> +XkbMapNotify</emphasis> +, <emphasis> +XkbNamesNotify</emphasis> +) as necessary to alert them to as many of the keyboard changes as possible. +</para> + + +<para> +If no error occurs, the request reply reports the GBN components that were +found and sends a description of any of the resulting keyboard that includes +and of the components that were requested. +</para> + + +<para> +The <emphasis> +deviceID</emphasis> + return value reports the X Input extension device identifier of the keyboard +that was used, or <emphasis> +0</emphasis> + if the server does not support the X input extension. +</para> + + +<para> +The <emphasis> +minKeyCode</emphasis> + and <emphasis> +maxKeyCode</emphasis> + return values report the legal range of keycodes for the keyboard description +that was created. If the resulting keyboard description does not include at +least one of the key names, client symbols or server symbols components, +<emphasis> +minKeyCode</emphasis> + and <emphasis> +maxKeyCode</emphasis> + are both <emphasis> +0</emphasis> +. +</para> + + +<para> +The <emphasis> +loaded</emphasis> + return value reports whether or not the existing keyboard definition was +replaced with the newly created one. If <emphasis> +loaded</emphasis> + is <emphasis> +True</emphasis> +, the <emphasis> +newKeyboard</emphasis> + return value reports whether or not the new map changed the geometry or range +of keycodes and caused <emphasis> +XkbNewKeyboardNotify</emphasis> + events for clients that have requested them. +</para> + + +<para> +The <emphasis> +found</emphasis> + return value reports the GBN components that were present in the keymap that +was constructed by this request. The <emphasis> +reported</emphasis> + return value lists the subset of those components for which descriptions +follow. if any of the components specified in the <emphasis> +need</emphasis> + field of the request were not found, <emphasis> +reported</emphasis> + is empty, otherwise it contains the intersection of the <emphasis> +found</emphasis> + return value with the union of the <emphasis> +need</emphasis> + and <emphasis> +want</emphasis> + request fields. +</para> + + +<para> +If any of <emphasis> +GBN_Types</emphasis> +, <emphasis> +GBN_ClientSymbols</emphasis> + or <emphasis> +GBN_ServerSymbols</emphasis> + are set in <emphasis> +reported</emphasis> +, the <emphasis> +map</emphasis> + return value has the same format as the reply to an <emphasis> +XkbGetMap</emphasis> + request and reports the corresponding pieces of the newly constructed keyboard +description. +</para> + + +<para> +If <emphasis> +GBN_CompatMap</emphasis> + is set in <emphasis> +reported</emphasis> +, the <emphasis> +compat</emphasis> + return value has the same format as the reply to an <emphasis> +XkbGetCompatMap</emphasis> + request and reports the symbol interpretations and group compatibility map for +the newly constructed keyboard description. +</para> + + +<para> +If <emphasis> +GBN_IndicatorMap</emphasis> + is set in <emphasis> +reported</emphasis> +, the <emphasis> +indicators</emphasis> + return value has the same format as the reply to an <emphasis> +XkbGetIndicatorMap</emphasis> + request and reports the physical indicators and indicator maps for the newly +constructed keyboard description. +</para> + + +<para> +If <emphasis> +GBN_KeyNames</emphasis> + or <emphasis> +GBN_OtherNames</emphasis> + are set in <emphasis> +reported</emphasis> +, the <emphasis> +names</emphasis> + return value has the same format as the reply to an <emphasis> +XkbGetNames</emphasis> + reply and reports the corresponding set of symbolic names for the newly +constructed keyboard description. +</para> + + +<para> +If <emphasis> +GBN_Geometry</emphasis> + is set in <emphasis> +reported</emphasis> +, the <emphasis> +geometry</emphasis> + return value has the same format as the reply to an <emphasis> +XkbGetGeometryMap</emphasis> + request and reports the keyboard geometry for the newly constructed keyboard +description. +</para> + + +</sect2> +<sect2 id='querying_and_changing_input_extension_devices'> +<title>Querying and Changing Input Extension Devices</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbGetDeviceInfo</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +wanted: KB_XIDEVFEATUREMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +ledClass: KB_LEDCLASSSPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +ledID: KB_IDSPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +allButtons: BOOL</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstButton, nButtons: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +deviceID: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +present: KB_XIDEVFEATUREMASK + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +supported: KB_XIFEATUREMASK + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +unsupported: KB_XIFEATUREMASK + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +firstBtnWanted: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +nBtnsWanted: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +firstBtnRtrn: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +nBtnsRtrn: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +totalBtns: CARD8 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +hasOwnState: BOOL + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +dfltKbdFB, dfltLedFB: KB_IDSPEC + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +devType: ATOM + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +name: STRING + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +btnActions: LISTofKB_ACTION + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +leds: LISTofKB_DEVICELEDINFO</entry> + </row> + + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Device</emphasis> +, <emphasis> +Match</emphasis> +, <emphasis> +Access</emphasis> +, <emphasis> +Alloc</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +Reports a subset of the XKB-supplied information about the input device +specified by <emphasis> +deviceSpec</emphasis> +. Unlike most XKB requests, the device specified for <emphasis> +XkbGetDeviceInfo</emphasis> + need not be a keyboard device. Nonetheless, a <emphasis> +Keyboard</emphasis> + error results if <emphasis> +deviceSpec</emphasis> + does not specify a valid core or input extension device. +</para> + + +<para> +The <emphasis> +wanted</emphasis> + field specifies the types of information to be returned, and controls the +interpretation of the other request fields. +</para> + + +<para> +If the server does not support assignment of XKB actions to extension device +buttons, the <emphasis> +allButtons</emphasis> +, <emphasis> +firstButton</emphasis> + and <emphasis> +nButtons</emphasis> + fields are ignored. +</para> + + +<para> +Otherwise, if the <emphasis> +XkbXI_ButtonActions</emphasis> + flag is set in <emphasis> +wanted</emphasis> +, the <emphasis> +allButtons</emphasis> +, <emphasis> +firstButton</emphasis> + and <emphasis> +nButtons</emphasis> + fields specify the device buttons for which actions should be returned. +Setting <emphasis> +allButtons</emphasis> + to <emphasis> +True</emphasis> + requests actions for all device buttons; if <emphasis> +allButtons</emphasis> + is <emphasis> +False</emphasis> +, <emphasis> +firstButton</emphasis> + and <emphasis> +nButtons</emphasis> + specify a range of buttons for which actions are requested. If the device has +no buttons or if <emphasis> +firstButton</emphasis> + and <emphasis> +nButtons</emphasis> + specify illegal buttons, a <emphasis> +Match</emphasis> + error results. If <emphasis> +allButtons</emphasis> + is <emphasis> +True</emphasis> +, <emphasis> +firstButton</emphasis> + and <emphasis> +nButtons</emphasis> + are ignored. +</para> + + +<para> +If the server does not support XKB access to any aspect of the indicators on +extension devices, or if the <emphasis> +wanted</emphasis> + field does not include any of the indicator flags, the <emphasis> +ledClass</emphasis> + and <emphasis> +ledID</emphasis> + fields are ignored. Otherwise, <emphasis> +ledClass</emphasis> + and <emphasis> +ledID</emphasis> + specify one or more feedback(s) for which indicator information is requested. +If <emphasis> +ledClass</emphasis> + or <emphasis> +ledID</emphasis> + have illegal values, a <emphasis> +Value</emphasis> + error results. If they have legal values but do not specify a keyboard or +indicator class feedback for the device in question, a <emphasis> +Match</emphasis> + error results. +</para> + + +<para> +The <emphasis> +ledClass</emphasis> + field can specify either <emphasis> +KbdFeedbackClass</emphasis> +, <emphasis> +LedFeedbackClass</emphasis> +, <emphasis> +XkbDfltXIClass</emphasis> +, or <emphasis> +XkbAllXIClasses</emphasis> +. If at least one keyboard feedback is defined for the specified device, +<emphasis> +XkbDfltXIClass</emphasis> + is equivalent to <emphasis> +KbdFeedbackClass</emphasis> +, otherwise it is equivalent to <emphasis> +LedFeedbackClass</emphasis> +. If <emphasis> +XkbAllXIClasses</emphasis> + is specified, this request returns information about both indicator and +keyboard class feedbacks which match the requested identifier, as described +below. +</para> + + +<para> +The <emphasis> +ledID</emphasis> + field can specify any valid input extension feedback identifier, <emphasis> +XkbDfltXIId</emphasis> +, or <emphasis> +XkbAllXIIds</emphasis> +. The default keyboard feedback is the one that is affected by core protocol +requests; the default led feedback is implementation-specific. If <emphasis> +XkbAllXIIds</emphasis> + is specified, this request returns indicator information about all feedbacks +of the class(es) specified by <emphasis> +ledClass</emphasis> +. +</para> + + +<para> +If no error results, the <emphasis> +deviceID</emphasis> + return value reports the input extension device identifier of the device for +which values are being returned. The <emphasis> +supported</emphasis> + return value reports the set of optional XKB extension device features that +are supported by this implementation (see <ulink +url="XKBproto.htm#50332257_36398">See Interactions Between XKB and the X Input +Extension</ulink>) for the specified device, and the unsupported return value +reports any <emphasis> +unsupported</emphasis> + features. +</para> + + +<para> +If <emphasis> +hasOwnState</emphasis> + is <emphasis> +True</emphasis> +, the device is also a keyboard, and any indicator maps bound to the device use +the current state and control settings for this device to control automatic +changes. If <emphasis> +hasOwnState</emphasis> + is <emphasis> +False</emphasis> +, the state and control settings of the core keyboard device control automatic +indicator changes. +</para> + + +<para> +The <emphasis> +name</emphasis> + field reports the X Input Extension name for the device. The <emphasis> +devType</emphasis> + field reports the X Input Extension device type. Both fields are provided +merely for convenience and are not interpreted by XKB. +</para> + + +<para> +The <emphasis> +present</emphasis> + return value reports the kinds of device information being returned, and +controls the interpretation of the remaining fields. The <emphasis> +present</emphasis> + field consists of the <emphasis> +wanted</emphasis> + field from the original request minus the flags for any unsupported features. +</para> + + +<para> +If <emphasis> +XkbXI_ButtonActions</emphasis> + is set in <emphasis> +present</emphasis> +, the <emphasis> +totalBtns</emphasis> + return value reports the total number of buttons present on the device, +<emphasis> +firstBtnWanted</emphasis> + and <emphasis> +nBtnsWanted</emphasis> + specify the range of buttons for which actions were requested, and the +<emphasis> +firstBtnRtrn</emphasis> + and <emphasis> +nBtnsRtrn </emphasis> +values specify the range of buttons for which actions are reported. The +<emphasis> +actionsRtrn</emphasis> + list has <emphasis> +nButtonsRtrn</emphasis> + entries which contain the actions bound to the specified buttons on the +device. Any buttons for which actions were requested but not returned have the +action <emphasis> +NoAction()</emphasis> +. +</para> + + +<para> +If any indicator information is reported, the leds list contains one element +for each requested feedback. For example, if <emphasis> +ledClass</emphasis> + is <emphasis> +XkbAllXIClasses</emphasis> + and <emphasis> +ledID</emphasis> + is <emphasis> +XkbAllXIIds</emphasis> +, <emphasis> +leds</emphasis> + describes all of the indicators on the device and has one element for each +keyboard or led class feedback defined for the device. If any information at +all is reported about a feedback, the set of physical indicators is also +reported in the <emphasis> +physIndicators</emphasis> + field of the corresponding element of <emphasis> +leds</emphasis> +. +</para> + + +<para> +If the server supports assignment of indicator maps to extension device +indicators, and if the <emphasis> +XkbXI_IndicatorMaps</emphasis> + flag is set in <emphasis> +wanted</emphasis> +, each member of <emphasis> +leds</emphasis> + reports any indicators on the corresponding feedback to which names have been +assigned. Any indicators for which no map is reported have the default map, +which allows explicit changes and does not request any automatic changes. +</para> + + +<para> +If the server supports assignment of indicator names to extension device +indicators, and the <emphasis> +XkbXI_IndicatorNames</emphasis> + flag is set in <emphasis> +wanted</emphasis> +, each member of <emphasis> +leds</emphasis> + reports any indicators on the corresponding feedback to which names have been +assigned. Any indicators for which no name is reported have the name <emphasis> +None</emphasis> +. +</para> + + +<para> +If the server supports XKB access to the state of extension device indicators, +and the <emphasis> +XkbXI_IndicatorState</emphasis> + flag is set in wanted, each member of leds reports the state of the indicators +on the corresponding feedback. +</para> + + +<para> +If any unsupported features are requested, and the requesting client has +selected for them, the server sends the client an <emphasis> +XkbExtensionDeviceNotify</emphasis> + event which indicates that an unsupported feature was requested. This event is +only generated if the client which issued the unsupported request has selected +for it and, if generated, is not sent to any other clients. +</para> + + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbSetDeviceInfo</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>deviceSpec: KB_DEVICESPEC</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +change: KB_XIDEVFEATUREMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstBtn, nBtns: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +btnActions:LISTofKB_ACTION</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +leds: LISTofKB_DEVICELEDINFO</entry> + </row> + + <row rowsep='0'> + <entry role='protoerror'>Errors: <emphasis> +Device</emphasis> +, <emphasis> +Match</emphasis> +, <emphasis> +Access</emphasis> +, <emphasis> +Alloc</emphasis> +</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +Changes a subset of the XKB-supplied information about the input device +specified by <emphasis> +deviceSpec</emphasis> +. Unlike most XKB requests, the device specified for <emphasis> +XkbGetDeviceInfo</emphasis> + need not be a keyboard device. Nonetheless, a <emphasis> +Keyboard</emphasis> + error results if <emphasis> +deviceSpec</emphasis> + does not specify a valid core or input extension device +</para> + + +<para> +The <emphasis> +change</emphasis> + field specifies the features for which new values are supplied, and controls +the interpretation of the other request fields. +</para> + + +<para> +If the server does not support assignment of XKB actions to extension device +buttons, the <emphasis> +firstButton</emphasis> + and <emphasis> +nButtons</emphasis> + fields are ignored. +</para> + + +<para> +Otherwise, if the <emphasis> +XkbXI_ButtonActions</emphasis> + flag is set in <emphasis> +change</emphasis> +, the <emphasis> +firstBtn</emphasis> + and <emphasis> +nBtns</emphasis> + fields specify a range of buttons for which actions are specified in this +request. If the device has no buttons or if <emphasis> +firstBtn</emphasis> + and <emphasis> +nBtns</emphasis> + specify illegal buttons, a <emphasis> +Match</emphasis> + error results. +</para> + + +<para> +Each element of the <emphasis> +leds</emphasis> + list describes the changes for a single keyboard or led feedback. If the +<emphasis> +ledClass</emphasis> + field of any element of <emphasis> +leds</emphasis> + contains any value other than <emphasis> +KbdFeedbackClass</emphasis> +, <emphasis> +LedFeedbackClass</emphasis> + or <emphasis> +XkbDfltXIClass</emphasis> +, a <emphasis> +Value</emphasis> + error results. If the <emphasis> +ledId</emphasis> + field of any element of leds contains any value other than a valid input +extension feedback identifier or <emphasis> +XkbDfltXIId</emphasis> +, a <emphasis> +Value</emphasis> + error results. If both fields are valid, but the device has no matching +feedback, a <emphasis> +Match</emphasis> + error results. +</para> + + +<para> +The fields of each element of <emphasis> +leds</emphasis> + are interpreted as follows: +</para> + +<itemizedlist> +<listitem> + <para>If <emphasis> +XkbXI_IndicatorMaps</emphasis> + is set in <emphasis> +change</emphasis> + and the server supports XKB assignment of indicator maps to the corresponding +feedback, the maps for all indicators on the corresponding feedback are taken +from <emphasis> +leds</emphasis> +. If the server does not support this feature, any maps specified in <emphasis> +leds</emphasis> + are ignored. + </para> +</listitem> +<listitem> + <para>If <emphasis> +XkbXI_IndicatorNames</emphasis> + is set in <emphasis> +change</emphasis> +, and the server supports XKB assignment of names to indicators for the +corresponding feedback, the names for all indicators on the corresponding +feedback are taken from <emphasis> +leds</emphasis> +. If the server does not support this feature, any names specified in <emphasis> +leds</emphasis> + are ignored. Regardless of whether they are used, any names be a valid Atom or +<emphasis> +None</emphasis> +, or an <emphasis> +Atom</emphasis> + error results. + </para> +</listitem> +<listitem> + <para>If <emphasis> +XkbXI_IndicatorState</emphasis> + is set in change, and the server supports XKB changes to extension device +indicator state, the server attempts to change the indicators on the +corresponding feedback as specified by <emphasis> +leds</emphasis> +. Any indicator maps bound to the feedback are applied, so state changes might +be blocked or have side-effects. + </para> +</listitem> +</itemizedlist> + +<para> +If any unsupported features are requested, and the requesting client has +selected for them, the server sends the client an <emphasis> +XkbExtensionDeviceNotify</emphasis> + event which indicates that an unsupported feature was requested. This event is +only generated if the client which issued the unsupported request has selected +for it and, if generated, is not sent to any other clients. +</para> + + +</sect2> +<sect2 id='debugging_the_x_keyboard_extension'> +<title>Debugging the X Keyboard Extension</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbSetDebuggingFlags</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>affectFlags, flags: CARD32</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +affectCtrls, ctrls: CARD32</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +message: STRING + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +currentFlags, supportedFlags: CARD32 + </entry> + </row> + <row rowsep='0'> + <entry role='protoreply'> +currentCtrls, supportedCtrls: CARD32</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +This request sets up various internal XKB debugging flags and controls. It is +intended for developer use and may be disabled in production servers. If +disabled, <emphasis> +XkbSetDebuggingFlags</emphasis> + has no effect but returns <emphasis> +Success</emphasis> +. +</para> + + +<para> +The <emphasis> +affectFlags</emphasis> + field specifies the debugging flags to be changed, the <emphasis> +flags</emphasis> + field specifies new values for the changed flags. The interpretation of the +debugging flags is implementation-specific, but flags are intended to control +debugging output and should not otherwise affect the operation of the server. +</para> + + +<para> +The <emphasis> +affectCtrls</emphasis> + field specifies the debugging controls to be changed, the <emphasis> +ctrls</emphasis> + field specifies new values for the changed controls. The interpretation of the +debugging controls is implementation-specific, but debugging controls are +allowed to affect the behavior of the server. +</para> + + +<para> +The <emphasis> +message</emphasis> + field provides a message that the X server can print in any logging or +debugging files before changing the flags. The server must accept this field +but it is not required to actually display it anywhere. +</para> + + +<para> +The X Test Suite makes some assumptions about the implementation of locking +modifier keys that do not apply when XKB is present. The <emphasis> +XkbDF_DisableLocks</emphasis> + debugging control provides a simple workaround to these test suite problems by +simply disabling all locking keys. If <emphasis> +XkbDF_DisableLocks</emphasis> + is enabled, the <emphasis> +SA_LockMods</emphasis> + and <emphasis> +SA_LockGroup</emphasis> + actions behave like <emphasis> +SA_SetMods</emphasis> + and <emphasis> +SA_LockMods</emphasis> +, respectively. If it is disabled, <emphasis> +SA_LockMods</emphasis> + and <emphasis> +SA_LockGroup</emphasis> + actions behave normally. +</para> + + +<para> +Implementations are free to ignore the <emphasis> +XkbDF_DisableLocks</emphasis> + debugging control or to define others. +</para> + + +<para> +The <emphasis> +currentFlags</emphasis> + return value reports the current setting for the debugging flags, if +applicable. The <emphasis> +currentCtrls</emphasis> + return value reports the setting for the debugging controls, if applicable. +The <emphasis> +supportedFlags</emphasis> + and <emphasis> +supportedCtrls</emphasis> + fields report the flags and controls that are recognized by the +implementation. Attempts to change unsupported fields or controls are silently +ignored. +</para> + + +<para> +If the <emphasis> +XkbSetDebuggingFlags</emphasis> + request contains more data than expected, the server ignores the extra data, +but no error results. If the request has less data than expected, a <emphasis> +Length</emphasis> + error results. +</para> + + +<para> +If the <emphasis> +XkbSetDebuggingFlags</emphasis> + reply contains more data than expected, the client just ignores any +uninterpreted data without reporting an error. If the reply has less data than +expected, a <emphasis> +Length</emphasis> + error results. +</para> + + +</sect2> +</sect1> +<sect1 id='events'> +<title>Events</title> + +<para> +All XKB events report the time at which they occurred in a field named +<emphasis> +time</emphasis> + and the device on which they occurred in a field named <emphasis> +deviceID</emphasis> +. XKB uses a single X event code for all events and uses a common field to +distinguish XKB event type. +</para> + + +<sect2 id='tracking_keyboard_replacement'> +<title>Tracking Keyboard Replacement</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbNewKeyboardNotify</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>time: TIMESTAMP</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +deviceID: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +changed: KB_NKNDETAILMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +minKeyCode, maxKeyCode: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +oldDeviceID: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +oldMinKeyCode, oldMaxKeyCode: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +requestMajor, requestMinor: CARD8</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +An <emphasis> +XkbNewKeyboardNotify</emphasis> + event reports that a new core keyboard has been installed. New keyboard notify +events can be generated: +</para> + +<itemizedlist> +<listitem> + <para>When the X server detects that the keyboard was changed. + </para> +</listitem> +<listitem> + <para>When a client installs a new extension device as the core keyboard +using the X Input Extension <emphasis> +ChangeKeyboardDevice</emphasis> + request. + </para> +</listitem> +<listitem> + <para>When a client issues an <emphasis> +XkbGetMapByName</emphasis> + request which changes the keycodes range or geometry. + </para> +</listitem> +</itemizedlist> + +<para> +The <emphasis> +changed</emphasis> + field of the event reports the aspects of the keyboard that have changed, and +can contain any combination of the event details for this event: +</para> + +<informaltable frame='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Bit in Changed</entry> + <entry>Meaning</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>NKN_Keycodes</entry> + <entry>The new keyboard has a different minimum or maximum keycode.</entry> + </row> + <row rowsep='0'> + <entry>NKN_Geometry</entry> + <entry>The new keyboard has a different keyboard geometry.</entry> + </row> + <row rowsep='0'> + <entry>NKN_DeviceID</entry> + <entry>The new keyboard has a new X Input Extension device +identifier</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +The server sends an <emphasis> +XkbNewKeyboardNotify</emphasis> + event to a client only if at least one of the bits that is set in the +<emphasis> +changed</emphasis> + field of the event is also set in the appropriate event details mask for the +client. +</para> + + +<para> +The <emphasis> +minKeyCode</emphasis> + and <emphasis> +maxKeyCode</emphasis> + fields report the minimum and maximum keycodes that can be returned by the new +keyboard. The <emphasis> +oldMinKeyCode</emphasis> + and <emphasis> +oldMaxKeyCode</emphasis> + fields report the minimum and maximum values that could be returned before the +change. This event always reports all four values, but the old and new values +are the same unless <emphasis> +NKN_Keycodes</emphasis> + is set in <emphasis> +changed</emphasis> +. +</para> + + +<para> +Once a client receives a new keyboard notify event which reports a new keycode +range, the X server reports events from all keys in the new range to that +client. Clients that do not request or receive new keyboard notify events +receive events only from keys that fall in the last range for legal keys +reported to that client. See <ulink url="XKBproto.htm#50332257_89133">See +Replacing the Keyboard "On-the-Fly"</ulink> for a more detailed explanation. +</para> + + +<para> +If <emphasis> +NKN_Keycodes</emphasis> + is set in <emphasis> +changed</emphasis> +, the <emphasis> +XkbNewKeyboardNotify</emphasis> + event subsumes all other change notification events (e.g. <emphasis> +XkbMapNotify</emphasis> +, <emphasis> +XkbNamesNotify</emphasis> +) that would otherwise result from the keyboard change. Clients who receive an +<emphasis> +XkbNewKeyboardNotify</emphasis> + event should assume that all other aspects of the keyboard mapping have +changed and regenerate the entire local copy of the keyboard description. +</para> + + +<para> +The <emphasis> +deviceID</emphasis> + field reports the X Input Extension device identifier of the new keyboard +device; <emphasis> +oldDeviceID</emphasis> + reports the device identifier before the change. This event always includes +both values, but they are the same unless <emphasis> +NKN_DeviceID</emphasis> + is set in <emphasis> +changed</emphasis> +. If the server does not support the X Input Extension, both fields have the +value <emphasis> +0</emphasis> +. +</para> + + +<para> +The <emphasis> +requestMajor</emphasis> + and <emphasis> +requestMinor</emphasis> + fields report the major and minor opcode of the request that caused the +keyboard change. If the keyboard change was not caused by some client request, +both fields have the value <emphasis> +0</emphasis> +. +</para> + + +</sect2> +<sect2 id='tracking_keyboard_mapping_changes'> +<title>Tracking Keyboard Mapping Changes</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbMapNotify</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>time: TIMESTAMP</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +deviceID: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +ptrBtnActions: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +changed: KB_MAPPARTMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +minKeyCode, maxKeyCode: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstType, nTypes: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstKeySym, firstKeyAction: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +nKeySyms, nKeyActions: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstKeyBehavior, firstKeyExplicit: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +nKeyBehaviors, nKeyExplicit: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +virtualMods: KB_VMODMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstModMapKey, firstVModMapKey: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +nModMapKeys, nVModMapKeys: CARD8</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +An <emphasis> +XkbMapNotify</emphasis> + event reports that some aspect of XKB map for a keyboard has changed. Map +notify events can be generated whenever some aspect of the keyboard map is +changed by an XKB or core protocol request. +</para> + + +<para> +The <emphasis> +deviceID</emphasis> + field reports the keyboard for which some map component has changed and the +<emphasis> +changed</emphasis> + field reports the components with new values, and can contain any of the +values that are legal for the <emphasis> +full</emphasis> + and <emphasis> +partial</emphasis> + fields of the <emphasis> +XkbGetMap</emphasis> + request. The server sends an <emphasis> +XkbMapNotify</emphasis> + event to a client only if at least one of the bits that is set in the +<emphasis> +changed</emphasis> + field of the event is also set in the appropriate event details mask for the +client. +</para> + + +<para> +The <emphasis> +minKeyCode</emphasis> + and <emphasis> +maxKeyCode</emphasis> + fields report the range of keycodes that are legal on the keyboard for which +the change is being reported. +</para> + + +<para> +If <emphasis> +XkbKeyTypesMask</emphasis> + is set in <emphasis> +changed</emphasis> +, the <emphasis> +firstType</emphasis> + and <emphasis> +nTypes</emphasis> + fields report a range of key types that includes all changed types. Otherwise, +both fields are <emphasis> +0</emphasis> +. +</para> + + +<para> +If <emphasis> +XkbKeySymsMask</emphasis> + is set in <emphasis> +changed</emphasis> +, the <emphasis> +firstKeySym</emphasis> + and <emphasis> +nKeySyms</emphasis> + fields report a range of keycodes that includes all keys with new symbols. +Otherwise, both fields are <emphasis> +0</emphasis> +. +</para> + + +<para> +If <emphasis> +XkbKeyActionsMask</emphasis> + is set in <emphasis> +changed</emphasis> +, the <emphasis> +firstKeyAction</emphasis> + and <emphasis> +nKeyActions</emphasis> + fields report a range of keycodes that includes all keys with new actions. +Otherwise, both fields are <emphasis> +0</emphasis> +. +</para> + + +<para> +If <emphasis> +XkbKeyBehaviorsMask</emphasis> + is set in <emphasis> +changed</emphasis> +, the <emphasis> +firstKeyBehavior </emphasis> +and <emphasis> +nKeyBehaviors</emphasis> + fields report a range of keycodes that includes all keys with new key +behavior. Otherwise, both fields are <emphasis> +0</emphasis> +. +</para> + + +<para> +If <emphasis> +XkbVirtualModsMask</emphasis> + is set in <emphasis> +changed</emphasis> +, <emphasis> +virtualMods</emphasis> + contains all virtual modifiers to which a new set of real modifiers is bound. +Otherwise, <emphasis> +virtualMods</emphasis> + is <emphasis> +0</emphasis> +. +</para> + + +<para> +If <emphasis> +XkbExplicitComponentsMask</emphasis> + is set in <emphasis> +changed</emphasis> +, the <emphasis> +firstKeyExplicit</emphasis> + and <emphasis> +nKeyExplicit</emphasis> + fields report a range of keycodes that includes all keys with changed explicit +components. Otherwise, both fields are <emphasis> +0</emphasis> +. +</para> + + +<para> +If <emphasis> +XkbModifierMapMask</emphasis> + is set in <emphasis> +changed</emphasis> +, the <emphasis> +firstModMapKey</emphasis> + and <emphasis> +nModMapKeys</emphasis> + fields report a range of keycodes that includes all keys with changed modifier +bindings. Otherwise, both fields are <emphasis> +0</emphasis> +. +</para> + + +<para> +If <emphasis> +XkbVirtualModMapMask</emphasis> + is set in <emphasis> +changed</emphasis> +, the <emphasis> +firstVModMapKey</emphasis> + and <emphasis> +nVModMapKeys</emphasis> + fields report a range of keycodes that includes all keys with changed virtual +modifier mappings. Otherwise, both fields are <emphasis> +0</emphasis> +. +</para> + + +</sect2> +<sect2 id='tracking_keyboard_state_changes'> +<title>Tracking Keyboard State Changes</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbStateNotify</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>time: TIMESTAMP</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +deviceID: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +mods, baseMods, latchedMods, lockedMods: KEYMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +group, lockedGroup: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +baseGroup, latchedGroup: INT16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +compatState: KEYMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +grabMods, compatGrabMods: KEYMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +lookupMods, compatLookupMods: KEYMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +ptrBtnState: BUTMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +changed: KB_STATEPARTMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +keycode: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +eventType: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +requestMajor, requestMinor: CARD8</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +An <emphasis> +XkbStateNotify</emphasis> + event reports that some component of the XKB state (see <ulink +url="XKBproto.htm#50332257_13933">See Keyboard State</ulink>) has changed. +State notify events are usually caused by key or pointer activity, but they can +also result from explicit state changes requested by the <emphasis> +XkbLatchLockState</emphasis> + request or by other extensions. +</para> + + +<para> +The <emphasis> +deviceID</emphasis> + field reports the keyboard on which some state component changed. The +<emphasis> +changed</emphasis> + field reports the XKB state components (see <ulink +url="XKBproto.htm#50332257_13933">See Keyboard State</ulink>) that have changed +and contain any combination of: +</para> + +<informaltable frame='none'> +<tgroup cols='3'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Bit in changed</entry> + <entry>Event field</entry> + <entry>Changed component</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis> +ModifierState</emphasis> +</entry> + <entry><emphasis> +mods</emphasis> +</entry> + <entry>The effective modifiers</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +ModifierBase</emphasis> +</entry> + <entry><emphasis> +baseMods</emphasis> +</entry> + <entry>The base modifiers</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +ModifierLatch</emphasis> +</entry> + <entry><emphasis> +latchedMods</emphasis> +</entry> + <entry>The latched modifiers</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +ModifierLock</emphasis> +</entry> + <entry><emphasis> +lockedMods</emphasis> +</entry> + <entry>The locked modifiers</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +GroupState</emphasis> +</entry> + <entry><emphasis> +group</emphasis> +</entry> + <entry>The effective keyboard group</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +GroupBase</emphasis> +</entry> + <entry><emphasis> +baseGroup</emphasis> +</entry> + <entry>The base keyboard group</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +GroupLatch</emphasis> +</entry> + <entry><emphasis> +latchedGroup</emphasis> +</entry> + <entry>The latched keyboard group</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +GroupLock</emphasis> +</entry> + <entry><emphasis> +lockedGroup</emphasis> +</entry> + <entry>The locked keyboard group</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +PointerButtons</emphasis> +</entry> + <entry><emphasis> +ptrBtnState</emphasis> +</entry> + <entry>The state of the core pointer buttons</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +GrabMods</emphasis> +</entry> + <entry><emphasis> +grabMods</emphasis> +</entry> + <entry>The XKB state used to compute grabs</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +LookupMods</emphasis> +</entry> + <entry><emphasis> +lookupMods</emphasis> +</entry> + <entry>The XKB state used to look up symbols</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +CompatState</emphasis> +</entry> + <entry><emphasis> +compatState</emphasis> +</entry> + <entry>Default state for non-XKB clients</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +CompatGrabMods</emphasis> +</entry> + <entry><emphasis> +compatGrabMods</emphasis> +</entry> + <entry>The core state used to compute grabs</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +CompatLookupMods</emphasis> +</entry> + <entry><emphasis> +compatLookupMods</emphasis> +</entry> + <entry>The core state used to look up symbols</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +The server sends an <emphasis> +XkbStateNotify</emphasis> + event to a client only if at least one of the bits that is set in the +<emphasis> +changed</emphasis> + field of the event is also set in the appropriate event details mask for the +client. +</para> + + +<para> +A state notify event reports current values for all state components, even +those with unchanged values. +</para> + + +<para> +The <emphasis> +keycode</emphasis> + field reports the key or button which caused the change in state while the +<emphasis> +eventType</emphasis> + field reports the exact type of event (e.g. <emphasis> +KeyPress</emphasis> +). If the change in state was not caused by key or button activity, both fields +have the value <emphasis> +0</emphasis> +. +</para> + + +<para> +The <emphasis> +requestMajor</emphasis> + and <emphasis> +requestMinor</emphasis> + fields report the major and minor opcodes of the request that caused the +change in state and have the value <emphasis> +0</emphasis> + if it was resulted from key or button activity. +</para> + + +</sect2> +<sect2 id='tracking_keyboard_control_changes'> +<title>Tracking Keyboard Control Changes</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbControlsNotify</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>time: TIMESTAMP</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +deviceID: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +numGroups: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +changedControls: KB_CONTROLMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +enabledControls,enabledControlChanges: KB_BOOLCTRLMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +keycode: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +eventType: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +requestMajor: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +requestMinor: CARD8</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +An <emphasis> +XkbControlsNotify</emphasis> + event reports a change in one or more of the global keyboard controls (see +<ulink url="XKBproto.htm#50332257_28742">See Global Keyboard Controls</ulink>) +or in the internal modifiers or ignore locks masks (see <ulink +url="XKBproto.htm#50332257_45660">See Server Internal Modifiers and Ignore +Locks Behavior</ulink>). Controls notify events are usually caused by and +<emphasis> +XkbSetControls</emphasis> + request, but they can also be caused by keyboard activity or certain core +protocol and input extension requests. +</para> + + +<para> +The <emphasis> +deviceID</emphasis> + field reports the keyboard for which some control has changed, and the +<emphasis> +changed</emphasis> + field reports the controls that have new values. +</para> + + +<para> +The <emphasis> +changed</emphasis> + field can contain any of the values that are permitted for the <emphasis> +changeControls</emphasis> + field of the <emphasis> +XkbSetControls</emphasis> + request. The server sends an <emphasis> +XkbControlsNotify</emphasis> + event to a client only if at least one of the bits that is set in the +<emphasis> +changed</emphasis> + field of the event is also set in the appropriate event details mask for the +client. +</para> + + +<para> +The <emphasis> +numGroups</emphasis> + field reports the total number of groups defined for the keyboard, whether or +not the number of groups has changed. +</para> + + +<para> +The <emphasis> +enabledControls</emphasis> + field reports the current status of all of the boolean controls, whether or +not any boolean controls changed state. If <emphasis> +EnabledControls</emphasis> + is set in <emphasis> +changed</emphasis> +, the <emphasis> +enabledControlChanges</emphasis> + field reports the boolean controls that were enabled or disabled; if a control +is specified in <emphasis> +enabledControlChanges</emphasis> +, the value that is reported for that control in <emphasis> +enabledControls</emphasis> + represents a change in state. +</para> + + +<para> +The <emphasis> +keycode</emphasis> + field reports the key or button which caused the change in state while the +<emphasis> +eventType</emphasis> + field reports the exact type of event (e.g. <emphasis> +KeyPress</emphasis> +). If the change in state was not caused by key or button activity, both fields +have the value <emphasis> +0</emphasis> +. +</para> + + +<para> +The <emphasis> +requestMajor</emphasis> + and <emphasis> +requestMinor</emphasis> + fields report the major and minor opcodes of the request that caused the +change in state and have the value <emphasis> +0</emphasis> + if it was resulted from key or button activity. +</para> + + +</sect2> +<sect2 id='tracking_keyboard_indicator_state_changes'> +<title>Tracking Keyboard Indicator State Changes</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbIndicatorStateNotify</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>time: TIMESTAMP</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +deviceID: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +stateChanged, state: KB_INDICATORMASK</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +An <emphasis> +XkbIndicatorStateNotify</emphasis> + event indicates that one or more of the indicators on a keyboard have changed +state. Indicator state notify events can be caused by: +</para> + +<itemizedlist> +<listitem> + <para>Automatic update to reflect changes in keyboard state (keyboard +activity, <emphasis> +XkbLatchLockState</emphasis> + requests). + </para> +</listitem> +<listitem> + <para>Automatic update to reflect changes in keyboard controls (<emphasis> +XkbSetControls</emphasis> +, keyboard activity, certain core protocol and input extension requests). + </para> +</listitem> +<listitem> + <para>Explicit attempts to change indicator state (core protocol and input +extension requests, <emphasis> +XkbSetNamedIndicator</emphasis> + requests). + </para> +</listitem> +<listitem> + <para>Changes to indicator maps (<emphasis> +XkbSetIndicatorMap</emphasis> + and <emphasis> +XkbSetNamedIndicator</emphasis> + requests). + </para> +</listitem> +</itemizedlist> + +<para> +The <emphasis> +deviceID</emphasis> + field reports the keyboard for which some indicator has changed, and the +<emphasis> +state</emphasis> + field reports the new state for all indicators on the specified keyboard. The +<emphasis> +stateChanged</emphasis> + field specifies which of the values in <emphasis> +state</emphasis> + represent a new state for the corresponding indicator. The server sends an +<emphasis> +XkbIndicatorStateNotify</emphasis> + event to a client only if at least one of the bits that is set in the +<emphasis> +stateChanged</emphasis> + field of the event is also set in the appropriate event details mask for the +client. +</para> + + +</sect2> +<sect2 id='tracking_keyboard_indicator_map_changes'> +<title>Tracking Keyboard Indicator Map Changes</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbIndicatorMapNotify</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>time: TIMESTAMP</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +deviceID: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +state: KB_INDICATORMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +mapChanged: KB_INDICATORMASK</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +An <emphasis> +XkbIndicatorMapNotify</emphasis> + event indicates that the maps for one or more keyboard indicators have been +changed. Indicator map notify events can be caused by <emphasis> +XkbSetIndicatorMap</emphasis> + and <emphasis> +XkbSetNamedIndicator</emphasis> + requests. +</para> + + +<para> +The <emphasis> +deviceID</emphasis> + field reports the keyboard for which some indicator map has changed, and the +<emphasis> +mapChanged</emphasis> + field reports the indicators with changed maps. The server sends an <emphasis> +XkbIndicatorMapNotify</emphasis> + event to a client only if at least one of the bits that is set in the +<emphasis> +mapChanged</emphasis> + field of the event is also set in the appropriate event details mask for the +client. +</para> + + +<para> +The <emphasis> +state</emphasis> + field reports the current state of all indicators on the specified keyboard. +</para> + + +</sect2> +<sect2 id='tracking_keyboard_name_changes'> +<title>Tracking Keyboard Name Changes</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbNamesNotify</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>time: TIMESTAMP</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +deviceID: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +changed: KB_NAMEDETAILMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstType, nTypes: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstLevelName, nLevelNames: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstKey: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +nKeys, nKeyAliases, nRadioGroups: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +changedGroupNames: KB_GROUPMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +changedVirtualMods: KB_VMODMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +changedIndicators: KB_INDICATORMASK</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +An <emphasis> +XkbNamesNotify</emphasis> + event reports a change to one or more of the symbolic names associated with a +keyboard. Symbolic names can change when: +</para> + +<itemizedlist> +<listitem> + <para> Some client explicitly changes them using <emphasis> +XkbSetNames</emphasis> +. + </para> +</listitem> +<listitem> + <para>The list of key types or radio groups is resized + </para> +</listitem> +<listitem> + <para>The group width of some key type is changed + </para> +</listitem> +</itemizedlist> + +<para> +The <emphasis> +deviceID</emphasis> + field reports the keyboard on which names were changed. The <emphasis> +changed</emphasis> + mask lists the components for which some names have changed and can have any +combination of the values permitted for the <emphasis> +which</emphasis> + field of the <emphasis> +XkbGetNames</emphasis> + request. The server sends an <emphasis> +XkbNamesNotify</emphasis> + event to a client only if at least one of the bits that is set in the +<emphasis> +changed</emphasis> + field of the event is also set in the appropriate event details mask for the +client. +</para> + + +<para> +If <emphasis> +KeyTypeNames</emphasis> + is set in <emphasis> +changed</emphasis> +, the <emphasis> +firstType</emphasis> + and <emphasis> +nTypes</emphasis> + fields report a range of types that includes all types with changed names. +Otherwise, both fields are <emphasis> +0</emphasis> +. +</para> + + +<para> +If <emphasis> +KTLevelNames</emphasis> + is set in <emphasis> +changed</emphasis> +, the <emphasis> +firstLevelName</emphasis> + and <emphasis> +nLevelNames</emphasis> + fields report a range of types that includes all types with changed level +names. Otherwise, both fields are <emphasis> +0</emphasis> +. +</para> + + +<para> +If <emphasis> +IndicatorNames</emphasis> + is set in <emphasis> +changed</emphasis> +, the <emphasis> +changedIndicators</emphasis> + field reports the indicators with changed names. Otherwise, <emphasis> +changedIndicators</emphasis> + is <emphasis> +0</emphasis> +. +</para> + + +<para> +If <emphasis> +VirtualModNames</emphasis> + is set in <emphasis> +changed</emphasis> +, the <emphasis> +changedVirtualMods</emphasis> + field reports the virtual modifiers with changed names. Otherwise, <emphasis> +changedVirtualMods</emphasis> + is <emphasis> +0</emphasis> +. +</para> + + +<para> +If <emphasis> +GroupNames</emphasis> + is set in <emphasis> +changed</emphasis> +, the <emphasis> +changedGroupNames</emphasis> + field reports the groups with changed names. Otherwise, <emphasis> +changedGroupNames</emphasis> + is <emphasis> +0</emphasis> +. +</para> + + +<para> +If <emphasis> +KeyNames</emphasis> + is set in <emphasis> +changed</emphasis> +, the <emphasis> +firstKey</emphasis> + and <emphasis> +nKeys</emphasis> + fields report a range of keycodes that includes all keys with changed names. +Otherwise, both fields are <emphasis> +0</emphasis> +. +</para> + + +<para> +The <emphasis> +nKeyAliases</emphasis> + field reports the total number of key aliases associated with the keyboard, +regardless of whether <emphasis> +KeyAliases</emphasis> + is set in <emphasis> +changed</emphasis> +. +</para> + + +<para> +The <emphasis> +nRadioGroups</emphasis> + field reports the total number of radio group names associated with the +keyboard, regardless of whether <emphasis> +RGNames</emphasis> + is set in <emphasis> +changed</emphasis> +. +</para> + + +</sect2> +<sect2 id='tracking_compatibility_map_changes'> +<title>Tracking Compatibility Map Changes</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbCompatMapNotify</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>time: TIMESTAMP</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +deviceID: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +changedGroups: KB_GROUPMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstSI, nSI: CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +nTotalSI: CARD16</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +An <emphasis> +XkbCompatMapNotify</emphasis> + event indicates that some component of the compatibility map for a keyboard +has been changed. Compatibility map notify events can be caused by <emphasis> +XkbSetCompatMap</emphasis> + and <emphasis> +XkbGetMapByName</emphasis> + requests. +</para> + + +<para> +The <emphasis> +deviceID</emphasis> + field reports the keyboard for which the compatibility map has changed; if the +server does not support the X input extension, <emphasis> +deviceID</emphasis> + is <emphasis> +0</emphasis> +. +</para> + + +<para> +The <emphasis> +changedGroups</emphasis> + field reports the keyboard groups, if any, with a changed entry in the group +compatibility map. The <emphasis> +firstSI</emphasis> + and <emphasis> +nSI</emphasis> + fields specify a range of symbol interpretations in the symbol compatibility +map that includes all changed symbol interpretations; if the symbol +compatibility map is unchanged, both fields are <emphasis> +0</emphasis> +. The <emphasis> +nTotalSI</emphasis> + field always reports the total number of symbol interpretations present in the +symbol compatibility map, regardless of whether any symbol interpretations have +been changed. +</para> + + +<para> +The server sends an <emphasis> +XkbCompatMapNotify</emphasis> + event to a client only if at least one of the following conditions is met: +</para> + +<itemizedlist> +<listitem> + <para>The <emphasis> +nSI</emphasis> + field of the event is non-zero, and the <emphasis> +XkbSymInterpMask</emphasis> + bit is set in the appropriate event details mask for the client. + </para> +</listitem> +<listitem> + <para>The <emphasis> +changedGroups</emphasis> + field of the event contains at least one group, and the <emphasis> +XkbGroupCompatMask</emphasis> + bit is set in the appropriate event details mask for the client. + </para> +</listitem> +</itemizedlist> + +</sect2> +<sect2 id='tracking_application_bell_requests'> +<title>Tracking Application Bell Requests</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbBellNotify</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>time: TIMESTAMP</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +deviceID: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +bellClass: { KbdFeedbackClass, BellFeedbackClass }</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +bellID: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +percent: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +pitch: CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +duration: CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +eventOnly: BOOL</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +name: ATOM</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +window: WINDOW</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +An <emphasis> +XkbBellNotify</emphasis> + event indicates that some client has requested a keyboard bell. Bell notify +events are usually caused by <emphasis> +Bell</emphasis> +, <emphasis> +DeviceBell</emphasis> +, or <emphasis> +XkbBell</emphasis> + requests, but they can also be generated by the server (e.g. if the <emphasis> +AccessXFeedback</emphasis> + control is active). +</para> + + +<para> +The server sends an <emphasis> +XkbBellNotify</emphasis> + event to a client if the appropriate event details field for the client has +the value <emphasis> +True</emphasis> +. +</para> + + +<para> +The <emphasis> +deviceID</emphasis> + field specifies the device for which a bell was requested, while the <emphasis> +bellClass</emphasis> + and <emphasis> +bellID</emphasis> + fields specify the input extension class and identifier of the feedback for +which the bell was requested. If the reporting server does not support the +input extension, all three fields have the value 0. +</para> + + +<para> +The <emphasis> +percent</emphasis> +, <emphasis> +pitch</emphasis> + and <emphasis> +duration</emphasis> + fields report the volume, tone and duration requested for the bell as +specified by the <emphasis> +XkbBell</emphasis> + request. Bell notify events caused by core protocol or input extension +requests use the pitch and duration specified in the corresponding bell or +keyboard feedback control. +</para> + + +<para> +If the bell was caused by an <emphasis> +XkbBell</emphasis> + request or by the X server, <emphasis> +name</emphasis> + reports an optional symbolic name for the bell and the <emphasis> +window</emphasis> + field optionally reports the window for which the bell was generated. +Otherwise, both fields have the value <emphasis> +None</emphasis> +. +</para> + + +<para> +If the <emphasis> +eventOnly</emphasis> + field is <emphasis> +True</emphasis> +, the server did not generate a sound in response to the request, otherwise the +server issues the beep before sending the event. The eventOnly field can be +<emphasis> +True</emphasis> + if the <emphasis> +AudibleBell</emphasis> + control is disabled or if a client explicitly requests <emphasis> +eventOnly</emphasis> + when it issues an <emphasis> +XkbBell</emphasis> + request. +</para> + + +</sect2> +<sect2 id='tracking_messages_generated_by_key_actions'> +<title>Tracking Messages Generated by Key Actions</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbActionMessage</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>time: TIMESTAMP</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +deviceID: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +keycode: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +press: BOOL</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +mods: KEYMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +group: KB_GROUP</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +keyEventFollows: BOOL</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +message: LISTofCARD8</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +An <emphasis> +XkbActionMessage</emphasis> + event is generated when the user operates a key to which an <emphasis> +SA_ActionMessage</emphasis> + message is bound under the appropriate state and group. The server sends an +<emphasis> +XkbActionMessage</emphasis> + event to a client if the appropriate event details field for the client has +the value <emphasis> +True</emphasis> +. +</para> + + +<para> +The <emphasis> +deviceID</emphasis> + field specifies the keyboard device that contains the key which activated the +event. The <emphasis> +keycode</emphasis> + field specifies the key whose operation caused the message and press is +<emphasis> +True</emphasis> + if the message was caused by the user pressing the key. The <emphasis> +mods</emphasis> + and <emphasis> +group</emphasis> + fields report the effective keyboard modifiers and group in effect at the time +the key was pressed or released. +</para> + + +<para> +If <emphasis> +keyEventFollows</emphasis> + is <emphasis> +True</emphasis> +, the server will also send a key press or release event, as appropriate, for +the key that generated the message. If it is <emphasis> +False</emphasis> +, the key causes only a message. Note that the key event is delivered normally +with respect to passive grabs, keyboard focus, and cursor position, so that +<emphasis> +keyEventFollows</emphasis> + does not guarantee that any particular client which receives the <emphasis> +XkbActionMessage</emphasis> + notify event will also receive a key press or release event. +</para> + + +<para> +The <emphasis> +message</emphasis> + field is <emphasis> +NULL</emphasis> +-terminated string of up to <emphasis> +ActionMessageLength</emphasis> + (<emphasis> +6</emphasis> +) bytes, which reports the contents of the <emphasis> +message</emphasis> + field in the action that caused the message notify event. +</para> + + +</sect2> +<sect2 id='tracking_changes_to_accessx_state_and_keys'> +<title>Tracking Changes to AccessX State and Keys</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbAccessXNotify</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>time: TIMESTAMP</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +deviceID: CARD8</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +detail: KB_AXNDETAILMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +keycode: KEYCODE</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +slowKeysDelay: CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +debounceDelay: CARD16</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +An <emphasis> +XkbAccessXNotify</emphasis> + event reports on some kinds of keyboard activity when any of the <emphasis> +SlowKeys</emphasis> +, <emphasis> +BounceKeys</emphasis> + or <emphasis> +AccessXKeys</emphasis> + controls are active. Compatibility map notify events can only be caused by +keyboard activity. +</para> + + +<para> +The <emphasis> +deviceID</emphasis> + and <emphasis> +keycode</emphasis> + fields specify the keyboard and key for which the event occurred. The +<emphasis> +detail</emphasis> + field describes the event that occurred and has one of the following values: +</para> + +<informaltable frame='none'> +<tgroup cols='3'> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Detail</entry> + <entry>Control</entry> + <entry>Meaning</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis> +AXN_SKPress</emphasis> +</entry> + <entry><emphasis> +SlowKeys</emphasis> +</entry> + <entry>Key pressed</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +AXN_SKAccept</emphasis> +</entry> + <entry><emphasis> +SlowKeys</emphasis> +</entry> + <entry><emphasis> +K</emphasis> +ey held until it was accepted.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +AXN_SKReject</emphasis> +</entry> + <entry><emphasis> +SlowKeys</emphasis> +</entry> + <entry>Key released before it was accepted.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +AXN_SKRelease</emphasis> +</entry> + <entry><emphasis> +SlowKeys</emphasis> +</entry> + <entry>Key released after it was accepted.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +AXN_BKAccept</emphasis> +</entry> + <entry><emphasis> +BounceKeys</emphasis> +</entry> + <entry>Key pressed while it was active.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +AXN_BKReject</emphasis> +</entry> + <entry><emphasis> +BounceKeys</emphasis> +</entry> + <entry>Key pressed while it was still disabled.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +AXN_AXKWarning</emphasis> +</entry> + <entry><emphasis> +AccessXKeys</emphasis> +</entry> + <entry>Shift key held down for four seconds</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +Each subclass of the AccessX notify event is generated only when the control +specified in the table above is enabled. The server sends an <emphasis> +XkbAccessXNotify</emphasis> + event to a client only if the bit which corresponds to the value of the +<emphasis> +detail</emphasis> + field for the event is set in the appropriate event details mask for the +client. +</para> + + +<para> +Regardless of the value of <emphasis> +detail</emphasis> +, the <emphasis> +slowKeysDelay</emphasis> + and <emphasis> +debounceDelay</emphasis> + fields always reports the current slow keys acceptance delay (see <ulink +url="XKBproto.htm#50332257_59600">See The SlowKeys Control</ulink>) and +debounce delay (see <ulink url="XKBproto.htm#50332257_12450">See The BounceKeys +Control</ulink>) for the specified keyboard. +</para> + + +</sect2> +<sect2 id='tracking_changes_to_extension_devices'> +<title>Tracking Changes To Extension Devices</title> + + +<informaltable frame='none' tabstyle='proto'> +<tgroup cols='1'> +<colspec colsep='0'/> + <thead> + <row rowsep='0'> + <entry role='protoname'>XkbExtensionDeviceNotify</entry> + </row> + </thead> + <tbody> + <row rowsep='0'> + <entry role='protoargs'>time: TIMESTAMP</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +deviceID: CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +ledClass: { KbdFeedbackClass, LedFeedbackClass }</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +ledID: CARD16</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +reason: KB_XIDETAILMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +supported: KB_XIFEATUREMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +unsupported: KB_XIFEATUREMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +ledsDefined: KB_INDICATORMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +ledState: KB_INDICATORMASK</entry> + </row> + <row rowsep='0'> + <entry role='protoname'> +firstButton, nButtons: CARD8</entry> + </row> + + </tbody> + </tgroup> +</informaltable> + +<para> +An <emphasis> +XkbExtensionDeviceNotify</emphasis> + event reports: +</para> + +<itemizedlist> +<listitem> + <para>A change to some part of the XKB information for an extension device. + </para> +</listitem> +<listitem> + <para>An attempt to use an XKB extension device feature that is not supported +for the specified device by the current implementation. + </para> +</listitem> +</itemizedlist> + +<para> +The <emphasis> +deviceID</emphasis> + field specifies the X Input Extension device identifier of some device on +which an XKB feature was requested, or <emphasis> +XkbUseCorePtr</emphasis> + if the request affected the core pointer device. The <emphasis> +reason</emphasis> + field explains why the event was generated in response to the request, and can +contain any combination of <emphasis> +XkbXI_UnsupportedFeature</emphasis> + and the values permitted for the change field of the <emphasis> +XkbSetDeviceInfo</emphasis> + request. +</para> + + +<para> +If <emphasis> +XkbXI_ButtonActions</emphasis> + is set in <emphasis> +reason</emphasis> +, this event reports a successful change to the XKB actions bound to one or +more buttons on the core pointer or an extension device. The <emphasis> +firstButton</emphasis> + and <emphasis> +nButtons</emphasis> + fields report a range of device buttons that include all of the buttons for +which actions were changed. +</para> + + +<para> +If any combination of <emphasis> +XkbXI_IndicatorNames</emphasis> +, <emphasis> +XkbXI_IndicatorMaps</emphasis> +, or <emphasis> +XkbXI_IndicatorState</emphasis> + is set in either <emphasis> +reason</emphasis> + or <emphasis> +unsupported</emphasis> +, the <emphasis> +ledClass</emphasis> + and <emphasis> +ledID</emphasis> + fields specify the X Input Extension feedback class and identifier of the +feedback for which the change is reported. If this event reports any changes to +an indicator feedback, the <emphasis> +ledsDefined</emphasis> + field reports all indicators on that feedback for which either a name or a +indicator map are defined, and <emphasis> +ledState</emphasis> + reports the current state of all of the indicators on the specified feedback. +</para> + + +<para> +If <emphasis> +XkbXI_IndicatorNames</emphasis> + is set in <emphasis> +reason</emphasis> +, this event reports a successful change to the symbolic names bound to one or +more extension device indicators by XKB. If <emphasis> +XkbXI_IndicatorMaps</emphasis> + is set in <emphasis> +reason</emphasis> +, this event reports a successful change to the indicator maps bound to one or +more extension device indicators by XKB. If <emphasis> +XkbXI_IndicatorState</emphasis> + is set in reason, this event reports that one or more indicators in the +specified device and feedback have changed state. +</para> + + +<para> +If <emphasis> +XkbXI_UnsupportedFeature</emphasis> + is set in reason, this event reports an unsuccessful attempt to use some XKB +extension device feature that is not supported by the XKB implementation in the +server for the specified device. The <emphasis> +unsupported</emphasis> + mask reports the requested features that are not available on the specified +device. See <ulink url="XKBproto.htm#50332257_36398">See Interactions Between +XKB and the X Input Extension</ulink> for more information about possible XKB +interactions with the X Input Extension. +</para> + + +<para> +The server sends an <emphasis> +XkbExtensionDeviceNotify</emphasis> + event to a client only if at least one of the bits that is set in the +<emphasis> +reason</emphasis> + field of the event is also set in the appropriate event details mask for the +client. +</para> + + +<para> +Events that report a successful change to some extension device feature are +reported to all clients that have expressed interest in the event; events that +report an attempt to use an unsupported feature are reported only to the client +which issued the request. Events which report a partial success are reported to +all interested clients, but only the client that issued the request is informed +of the attempt to use unsupported features. +</para> +</sect2> +</sect1> +</chapter> diff --git a/specs/xkbproto.xml b/specs/xkbproto.xml new file mode 100644 index 0000000..ac22885 --- /dev/null +++ b/specs/xkbproto.xml @@ -0,0 +1,84 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE book + PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> + +<book id="xkbproto"> + +<bookinfo> + <title>The X Keyboard Extension: Protocol Specification</title> + <subtitle>X Consortium Standard</subtitle> + <revhistory> + <revision> + <revnumber>1.0</revnumber> + <date/> + <revremark>Protocol Version</revremark> + </revision> + <revision> + <revnumber>1.0</revnumber> + <date/> + <revremark>Document Version</revremark> + </revision> + </revhistory> + <author> + <firstname>Erik</firstname> + <surname>Fortune</surname> + <affiliation><orgname>Silicon Graphics, Inc</orgname></affiliation> + </author> + <releaseinfo>X Version 11, Release 6.4</releaseinfo> +<legalnotice> +<para> +Copyright © 1995, 1996 X Consortium Inc. +</para> +<para> +Copyright © 1995, 1996 Silicon Graphics Inc. +</para> +<para> +Copyright © 1995, 1996 Hewlett-Packard Company +</para> +<para> +Copyright © 1995, 1996 Digital Equipment Corporation +</para> +<para> +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: +</para> +<para> +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. +</para> +<para> +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. +</para> +<para> +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. +</para> +</legalnotice> + +</bookinfo> + +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="acknowledgements.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ch01.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ch02.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ch03.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ch04.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ch05.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ch06.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ch07.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ch08.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ch09.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ch10.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ch11.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ch12.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ch13.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ch14.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ch15.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ch16.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="appA.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="appB.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="appC.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="appD.xml"/> + +<!-- +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="credits.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="glossary.xml"/> +--> +</book> |
