diff options
104 files changed, 24871 insertions, 27172 deletions
diff --git a/fontconfig/configure.ac b/fontconfig/configure.ac index ce468b89e..a366853e2 100644 --- a/fontconfig/configure.ac +++ b/fontconfig/configure.ac @@ -138,7 +138,7 @@ dnl ========================================================================== # Checks for header files. AC_HEADER_DIRENT AC_HEADER_STDC -AC_CHECK_HEADERS([fcntl.h regex.h stdlib.h string.h unistd.h sys/statvfs.h sys/vfs.h sys/statfs.h sys/param.h sys/mount.h]) +AC_CHECK_HEADERS([fcntl.h stdlib.h string.h unistd.h sys/statvfs.h sys/vfs.h sys/statfs.h sys/param.h sys/mount.h]) AX_CREATE_STDINT_H([src/fcstdint.h]) # Checks for typedefs, structures, and compiler characteristics. @@ -150,7 +150,7 @@ AC_TYPE_PID_T # Checks for library functions. AC_FUNC_VPRINTF AC_FUNC_MMAP -AC_CHECK_FUNCS([link mkstemp mkostemp _mktemp_s mkdtemp getopt getopt_long getprogname getexecname rand random lrand48 random_r rand_r readlink regcomp regerror regexec regfree fstatvfs fstatfs lstat]) +AC_CHECK_FUNCS([link mkstemp mkostemp _mktemp_s mkdtemp getopt getopt_long getprogname getexecname rand random lrand48 random_r rand_r readlink fstatvfs fstatfs lstat]) dnl AC_CHECK_FUNCS doesn't check for header files. dnl posix_fadvise() may be not available in older libc. @@ -211,12 +211,6 @@ if test "x$ac_cv_func_fstatfs" = "xyes"; then fi AC_CHECK_MEMBERS([struct dirent.d_type],,, [#include <dirent.h>]) -# -# regex -# -if test "x$ac_cv_func_regcomp" = "xyes" -a "x$ac_cv_func_regerror" = "xyes" -a "x$ac_cv_func_regexec" = "xyes" -a "x$ac_cv_func_regfree"; then - AC_DEFINE(USE_REGEX,,[Use regex]) -fi # # Checks for iconv diff --git a/fontconfig/doc/Makefile.am b/fontconfig/doc/Makefile.am index 7503219b8..9141ab236 100644 --- a/fontconfig/doc/Makefile.am +++ b/fontconfig/doc/Makefile.am @@ -85,6 +85,7 @@ DOC_FUNCS_FNCS = \ fcstring.fncs \ fcstrset.fncs \ fcvalue.fncs \ + fcweight.fncs \ $(NULL) SGML_FILES = \ fontconfig-user.sgml \ diff --git a/fontconfig/doc/fcweight.fncs b/fontconfig/doc/fcweight.fncs new file mode 100644 index 000000000..2872dd66c --- /dev/null +++ b/fontconfig/doc/fcweight.fncs @@ -0,0 +1,47 @@ +/* + * fontconfig/doc/fcweight.fncs + * + * Permission to use, copy, modify, distribute, and sell this software and its + * documentation for any purpose is hereby granted without fee, provided that + * the above copyright notice appear in all copies and that both that + * copyright notice and this permission notice appear in supporting + * documentation, and that the name of the author(s) not be used in + * advertising or publicity pertaining to distribution of the software without + * specific, written prior permission. The authors make no + * representations about the suitability of this software for any purpose. It + * is provided "as is" without express or implied warranty. + * + * THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + * EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR + * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + * PERFORMANCE OF THIS SOFTWARE. + */ +@RET@ int +@FUNC@ FcWeightFromOpenType +@TYPE1@ int @ARG1@ ot_weight +@PURPOSE@ Convert from OpenType weight values to fontconfig ones +@DESC@ +<function>FcWeightFromOpenType</function> returns an integer value +to use with FC_WEIGHT, from an integer in the 1..1000 range, resembling +the numbers from OpenType specification's OS/2 usWeight numbers, which +are also similar to CSS font-weight numbers. If input is negative, +zero, or greater than 1000, returns -1. This function linearly interpolates +between various FC_WEIGHT_* constants. As such, the returned value does not +necessarily match any of the predefined constants. +@SINCE@ 2.11.91 +@@ + +@RET@ int +@FUNC@ FcWeightToOpenType +@TYPE1@ int @ARG1@ ot_weight +@PURPOSE@ Convert from fontconfig weight values to OpenType ones +@DESC@ +<function>FcWeightToOpenType</function> is the inverse of +<function>FcWeightFromOpenType</function>. If the input is less than +FC_WEIGHT_THIN or greater than FC_WEIGHT_EXTRABLACK, returns -1. Otherwise +returns a number in the range 1 to 1000. +@SINCE@ 2.11.91 +@@ diff --git a/fontconfig/doc/fontconfig-user.sgml b/fontconfig/doc/fontconfig-user.sgml index 775d1f725..482b45331 100644 --- a/fontconfig/doc/fontconfig-user.sgml +++ b/fontconfig/doc/fontconfig-user.sgml @@ -473,6 +473,8 @@ symbolic names for common font values: extralight weight 40 ultralight weight 40 light weight 50 + demilight weight 55 + semilight weight 55 book weight 75 regular weight 80 normal weight 80 diff --git a/fontconfig/fontconfig/fontconfig.h b/fontconfig/fontconfig/fontconfig.h index 8575cc4d3..e5b09591b 100644 --- a/fontconfig/fontconfig/fontconfig.h +++ b/fontconfig/fontconfig/fontconfig.h @@ -131,6 +131,8 @@ typedef int FcBool; #define FC_WEIGHT_EXTRALIGHT 40 #define FC_WEIGHT_ULTRALIGHT FC_WEIGHT_EXTRALIGHT #define FC_WEIGHT_LIGHT 50 +#define FC_WEIGHT_DEMILIGHT 55 +#define FC_WEIGHT_SEMILIGHT FC_WEIGHT_DEMILIGHT #define FC_WEIGHT_BOOK 75 #define FC_WEIGHT_REGULAR 80 #define FC_WEIGHT_NORMAL FC_WEIGHT_REGULAR @@ -906,6 +908,13 @@ FcRangeDestroy (FcRange *range); FcPublic FcRange * FcRangeCopy (const FcRange *r); +/* fcweight.c */ + +FcPublic int +FcWeightFromOpenType (int ot_weight); + +FcPublic int +FcWeightToOpenType (int fc_weight); /* fcstr.c */ diff --git a/fontconfig/src/Makefile.am b/fontconfig/src/Makefile.am index c1991b284..3757cf8f3 100644 --- a/fontconfig/src/Makefile.am +++ b/fontconfig/src/Makefile.am @@ -154,6 +154,7 @@ libfontconfig_la_SOURCES = \ fcserialize.c \ fcstat.c \ fcstr.c \ + fcweight.c \ fcwindows.h \ fcxml.c \ ftglue.h \ diff --git a/fontconfig/src/fccfg.c b/fontconfig/src/fccfg.c index 6d3259513..f8ee8d20e 100644 --- a/fontconfig/src/fccfg.c +++ b/fontconfig/src/fccfg.c @@ -1546,10 +1546,38 @@ FcConfigSubstituteWithPat (FcConfig *config, FcStrSetDestroy (strs); while (l && (lang = FcStrListNext (l))) { + FcPatternElt *e = FcPatternObjectFindElt (p, FC_LANG_OBJECT); + + if (e) + { + FcValueListPtr ll; + + for (ll = FcPatternEltValues (e); ll; ll = FcValueListNext (ll)) + { + FcValue vv = FcValueCanonicalize (&ll->value); + + if (vv.type == FcTypeLangSet) + { + FcLangSet *ls = FcLangSetCreate (); + FcBool b; + + FcLangSetAdd (ls, lang); + b = FcLangSetContains (vv.u.l, ls); + FcLangSetDestroy (ls); + if (b) + goto bail_lang; + } + else + if (FcStrCmpIgnoreCase (vv.u.s, lang) == 0) + goto bail_lang; + } + } v.type = FcTypeString; v.u.s = lang; + FcPatternObjectAddWithBinding (p, FC_LANG_OBJECT, v, FcValueBindingWeak, FcTrue); } + bail_lang: FcStrListDone (l); } if (FcPatternObjectGet (p, FC_PRGNAME_OBJECT, 0, &v) == FcResultNoMatch) diff --git a/fontconfig/src/fccompat.c b/fontconfig/src/fccompat.c index f4f3f5fdc..31d80bef1 100644 --- a/fontconfig/src/fccompat.c +++ b/fontconfig/src/fccompat.c @@ -255,3 +255,7 @@ FcMakeDirectory (const FcChar8 *dir) FcStrFree (parent); return ret; } + +#define __fccompat__ +#include "fcaliastail.h" +#undef __fccompat__ diff --git a/fontconfig/src/fcfreetype.c b/fontconfig/src/fcfreetype.c index baf13e56d..aca2f70b2 100644 --- a/fontconfig/src/fcfreetype.c +++ b/fontconfig/src/fcfreetype.c @@ -558,6 +558,139 @@ FcFontCapabilities(FT_Face face); #define NUM_FC_MAC_ROMAN_FAKE (int) (sizeof (fcMacRomanFake) / sizeof (fcMacRomanFake[0])) + +/* From http://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/ROMAN.TXT */ +static const FcChar16 fcMacRomanNonASCIIToUnicode[128] = { + /*0x80*/ 0x00C4, /* LATIN CAPITAL LETTER A WITH DIAERESIS */ + /*0x81*/ 0x00C5, /* LATIN CAPITAL LETTER A WITH RING ABOVE */ + /*0x82*/ 0x00C7, /* LATIN CAPITAL LETTER C WITH CEDILLA */ + /*0x83*/ 0x00C9, /* LATIN CAPITAL LETTER E WITH ACUTE */ + /*0x84*/ 0x00D1, /* LATIN CAPITAL LETTER N WITH TILDE */ + /*0x85*/ 0x00D6, /* LATIN CAPITAL LETTER O WITH DIAERESIS */ + /*0x86*/ 0x00DC, /* LATIN CAPITAL LETTER U WITH DIAERESIS */ + /*0x87*/ 0x00E1, /* LATIN SMALL LETTER A WITH ACUTE */ + /*0x88*/ 0x00E0, /* LATIN SMALL LETTER A WITH GRAVE */ + /*0x89*/ 0x00E2, /* LATIN SMALL LETTER A WITH CIRCUMFLEX */ + /*0x8A*/ 0x00E4, /* LATIN SMALL LETTER A WITH DIAERESIS */ + /*0x8B*/ 0x00E3, /* LATIN SMALL LETTER A WITH TILDE */ + /*0x8C*/ 0x00E5, /* LATIN SMALL LETTER A WITH RING ABOVE */ + /*0x8D*/ 0x00E7, /* LATIN SMALL LETTER C WITH CEDILLA */ + /*0x8E*/ 0x00E9, /* LATIN SMALL LETTER E WITH ACUTE */ + /*0x8F*/ 0x00E8, /* LATIN SMALL LETTER E WITH GRAVE */ + /*0x90*/ 0x00EA, /* LATIN SMALL LETTER E WITH CIRCUMFLEX */ + /*0x91*/ 0x00EB, /* LATIN SMALL LETTER E WITH DIAERESIS */ + /*0x92*/ 0x00ED, /* LATIN SMALL LETTER I WITH ACUTE */ + /*0x93*/ 0x00EC, /* LATIN SMALL LETTER I WITH GRAVE */ + /*0x94*/ 0x00EE, /* LATIN SMALL LETTER I WITH CIRCUMFLEX */ + /*0x95*/ 0x00EF, /* LATIN SMALL LETTER I WITH DIAERESIS */ + /*0x96*/ 0x00F1, /* LATIN SMALL LETTER N WITH TILDE */ + /*0x97*/ 0x00F3, /* LATIN SMALL LETTER O WITH ACUTE */ + /*0x98*/ 0x00F2, /* LATIN SMALL LETTER O WITH GRAVE */ + /*0x99*/ 0x00F4, /* LATIN SMALL LETTER O WITH CIRCUMFLEX */ + /*0x9A*/ 0x00F6, /* LATIN SMALL LETTER O WITH DIAERESIS */ + /*0x9B*/ 0x00F5, /* LATIN SMALL LETTER O WITH TILDE */ + /*0x9C*/ 0x00FA, /* LATIN SMALL LETTER U WITH ACUTE */ + /*0x9D*/ 0x00F9, /* LATIN SMALL LETTER U WITH GRAVE */ + /*0x9E*/ 0x00FB, /* LATIN SMALL LETTER U WITH CIRCUMFLEX */ + /*0x9F*/ 0x00FC, /* LATIN SMALL LETTER U WITH DIAERESIS */ + /*0xA0*/ 0x2020, /* DAGGER */ + /*0xA1*/ 0x00B0, /* DEGREE SIGN */ + /*0xA2*/ 0x00A2, /* CENT SIGN */ + /*0xA3*/ 0x00A3, /* POUND SIGN */ + /*0xA4*/ 0x00A7, /* SECTION SIGN */ + /*0xA5*/ 0x2022, /* BULLET */ + /*0xA6*/ 0x00B6, /* PILCROW SIGN */ + /*0xA7*/ 0x00DF, /* LATIN SMALL LETTER SHARP S */ + /*0xA8*/ 0x00AE, /* REGISTERED SIGN */ + /*0xA9*/ 0x00A9, /* COPYRIGHT SIGN */ + /*0xAA*/ 0x2122, /* TRADE MARK SIGN */ + /*0xAB*/ 0x00B4, /* ACUTE ACCENT */ + /*0xAC*/ 0x00A8, /* DIAERESIS */ + /*0xAD*/ 0x2260, /* NOT EQUAL TO */ + /*0xAE*/ 0x00C6, /* LATIN CAPITAL LETTER AE */ + /*0xAF*/ 0x00D8, /* LATIN CAPITAL LETTER O WITH STROKE */ + /*0xB0*/ 0x221E, /* INFINITY */ + /*0xB1*/ 0x00B1, /* PLUS-MINUS SIGN */ + /*0xB2*/ 0x2264, /* LESS-THAN OR EQUAL TO */ + /*0xB3*/ 0x2265, /* GREATER-THAN OR EQUAL TO */ + /*0xB4*/ 0x00A5, /* YEN SIGN */ + /*0xB5*/ 0x00B5, /* MICRO SIGN */ + /*0xB6*/ 0x2202, /* PARTIAL DIFFERENTIAL */ + /*0xB7*/ 0x2211, /* N-ARY SUMMATION */ + /*0xB8*/ 0x220F, /* N-ARY PRODUCT */ + /*0xB9*/ 0x03C0, /* GREEK SMALL LETTER PI */ + /*0xBA*/ 0x222B, /* INTEGRAL */ + /*0xBB*/ 0x00AA, /* FEMININE ORDINAL INDICATOR */ + /*0xBC*/ 0x00BA, /* MASCULINE ORDINAL INDICATOR */ + /*0xBD*/ 0x03A9, /* GREEK CAPITAL LETTER OMEGA */ + /*0xBE*/ 0x00E6, /* LATIN SMALL LETTER AE */ + /*0xBF*/ 0x00F8, /* LATIN SMALL LETTER O WITH STROKE */ + /*0xC0*/ 0x00BF, /* INVERTED QUESTION MARK */ + /*0xC1*/ 0x00A1, /* INVERTED EXCLAMATION MARK */ + /*0xC2*/ 0x00AC, /* NOT SIGN */ + /*0xC3*/ 0x221A, /* SQUARE ROOT */ + /*0xC4*/ 0x0192, /* LATIN SMALL LETTER F WITH HOOK */ + /*0xC5*/ 0x2248, /* ALMOST EQUAL TO */ + /*0xC6*/ 0x2206, /* INCREMENT */ + /*0xC7*/ 0x00AB, /* LEFT-POINTING DOUBLE ANGLE QUOTATION MARK */ + /*0xC8*/ 0x00BB, /* RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK */ + /*0xC9*/ 0x2026, /* HORIZONTAL ELLIPSIS */ + /*0xCA*/ 0x00A0, /* NO-BREAK SPACE */ + /*0xCB*/ 0x00C0, /* LATIN CAPITAL LETTER A WITH GRAVE */ + /*0xCC*/ 0x00C3, /* LATIN CAPITAL LETTER A WITH TILDE */ + /*0xCD*/ 0x00D5, /* LATIN CAPITAL LETTER O WITH TILDE */ + /*0xCE*/ 0x0152, /* LATIN CAPITAL LIGATURE OE */ + /*0xCF*/ 0x0153, /* LATIN SMALL LIGATURE OE */ + /*0xD0*/ 0x2013, /* EN DASH */ + /*0xD1*/ 0x2014, /* EM DASH */ + /*0xD2*/ 0x201C, /* LEFT DOUBLE QUOTATION MARK */ + /*0xD3*/ 0x201D, /* RIGHT DOUBLE QUOTATION MARK */ + /*0xD4*/ 0x2018, /* LEFT SINGLE QUOTATION MARK */ + /*0xD5*/ 0x2019, /* RIGHT SINGLE QUOTATION MARK */ + /*0xD6*/ 0x00F7, /* DIVISION SIGN */ + /*0xD7*/ 0x25CA, /* LOZENGE */ + /*0xD8*/ 0x00FF, /* LATIN SMALL LETTER Y WITH DIAERESIS */ + /*0xD9*/ 0x0178, /* LATIN CAPITAL LETTER Y WITH DIAERESIS */ + /*0xDA*/ 0x2044, /* FRACTION SLASH */ + /*0xDB*/ 0x20AC, /* EURO SIGN */ + /*0xDC*/ 0x2039, /* SINGLE LEFT-POINTING ANGLE QUOTATION MARK */ + /*0xDD*/ 0x203A, /* SINGLE RIGHT-POINTING ANGLE QUOTATION MARK */ + /*0xDE*/ 0xFB01, /* LATIN SMALL LIGATURE FI */ + /*0xDF*/ 0xFB02, /* LATIN SMALL LIGATURE FL */ + /*0xE0*/ 0x2021, /* DOUBLE DAGGER */ + /*0xE1*/ 0x00B7, /* MIDDLE DOT */ + /*0xE2*/ 0x201A, /* SINGLE LOW-9 QUOTATION MARK */ + /*0xE3*/ 0x201E, /* DOUBLE LOW-9 QUOTATION MARK */ + /*0xE4*/ 0x2030, /* PER MILLE SIGN */ + /*0xE5*/ 0x00C2, /* LATIN CAPITAL LETTER A WITH CIRCUMFLEX */ + /*0xE6*/ 0x00CA, /* LATIN CAPITAL LETTER E WITH CIRCUMFLEX */ + /*0xE7*/ 0x00C1, /* LATIN CAPITAL LETTER A WITH ACUTE */ + /*0xE8*/ 0x00CB, /* LATIN CAPITAL LETTER E WITH DIAERESIS */ + /*0xE9*/ 0x00C8, /* LATIN CAPITAL LETTER E WITH GRAVE */ + /*0xEA*/ 0x00CD, /* LATIN CAPITAL LETTER I WITH ACUTE */ + /*0xEB*/ 0x00CE, /* LATIN CAPITAL LETTER I WITH CIRCUMFLEX */ + /*0xEC*/ 0x00CF, /* LATIN CAPITAL LETTER I WITH DIAERESIS */ + /*0xED*/ 0x00CC, /* LATIN CAPITAL LETTER I WITH GRAVE */ + /*0xEE*/ 0x00D3, /* LATIN CAPITAL LETTER O WITH ACUTE */ + /*0xEF*/ 0x00D4, /* LATIN CAPITAL LETTER O WITH CIRCUMFLEX */ + /*0xF0*/ 0xF8FF, /* Apple logo */ + /*0xF1*/ 0x00D2, /* LATIN CAPITAL LETTER O WITH GRAVE */ + /*0xF2*/ 0x00DA, /* LATIN CAPITAL LETTER U WITH ACUTE */ + /*0xF3*/ 0x00DB, /* LATIN CAPITAL LETTER U WITH CIRCUMFLEX */ + /*0xF4*/ 0x00D9, /* LATIN CAPITAL LETTER U WITH GRAVE */ + /*0xF5*/ 0x0131, /* LATIN SMALL LETTER DOTLESS I */ + /*0xF6*/ 0x02C6, /* MODIFIER LETTER CIRCUMFLEX ACCENT */ + /*0xF7*/ 0x02DC, /* SMALL TILDE */ + /*0xF8*/ 0x00AF, /* MACRON */ + /*0xF9*/ 0x02D8, /* BREVE */ + /*0xFA*/ 0x02D9, /* DOT ABOVE */ + /*0xFB*/ 0x02DA, /* RING ABOVE */ + /*0xFC*/ 0x00B8, /* CEDILLA */ + /*0xFD*/ 0x02DD, /* DOUBLE ACUTE ACCENT */ + /*0xFE*/ 0x02DB, /* OGONEK */ + /*0xFF*/ 0x02C7, /* CARON */ +}; + #if USE_ICONV #include <iconv.h> #endif @@ -696,6 +829,35 @@ FcSfntNameTranscode (FT_SfntName *sname) *u8 = '\0'; goto done; } + if (!strcmp (fromcode, FC_ENCODING_MAC_ROMAN)) + { + FcChar8 *src = sname->string; + int src_len = sname->string_len; + int olen; + FcChar8 *u8; + FcChar32 ucs4; + + /* + * Convert Latin1 to Utf8. Freed below + */ + utf8 = malloc (src_len * 3 + 1); + if (!utf8) + return 0; + + u8 = utf8; + while (src_len > 0) + { + ucs4 = *src++; + if (ucs4 >= 128) + ucs4 = fcMacRomanNonASCIIToUnicode[ucs4 - 128]; + src_len--; + olen = FcUcs4ToUtf8 (ucs4, u8); + u8 += olen; + } + *u8 = '\0'; + goto done; + } + #if USE_ICONV cd = iconv_open ("UTF-8", fromcode); if (cd && cd != (iconv_t) (-1)) @@ -933,6 +1095,8 @@ static const FcStringConst weightConsts[] = { { (FC8) "thin", FC_WEIGHT_THIN }, { (FC8) "extralight", FC_WEIGHT_EXTRALIGHT }, { (FC8) "ultralight", FC_WEIGHT_ULTRALIGHT }, + { (FC8) "demilight", FC_WEIGHT_DEMILIGHT }, + { (FC8) "semilight", FC_WEIGHT_SEMILIGHT }, { (FC8) "light", FC_WEIGHT_LIGHT }, { (FC8) "book", FC_WEIGHT_BOOK }, { (FC8) "regular", FC_WEIGHT_REGULAR }, @@ -1107,6 +1271,8 @@ FcFreeTypeQueryFace (const FT_Face face, FcRange *r = NULL; double lower_size = 0.0L, upper_size = DBL_MAX; + FcInitDebug (); /* We might be called with no initizalization whatsoever. */ + pat = FcPatternCreate (); if (!pat) goto bail0; @@ -1282,10 +1448,10 @@ FcFreeTypeQueryFace (const FT_Face face, free (utf8); if (lang) { - /* pad lang list with 'xx' to line up with elt */ + /* pad lang list with 'und' to line up with elt */ while (*nlangp < *np) { - if (!FcPatternAddString (pat, eltlang, (FcChar8 *) "xx")) + if (!FcPatternAddString (pat, eltlang, (FcChar8 *) "und")) goto bail1; ++*nlangp; } @@ -1462,28 +1628,7 @@ FcFreeTypeQueryFace (const FT_Face face, if (os2 && os2->version != 0xffff) { - if (os2->usWeightClass == 0) - ; - else if (os2->usWeightClass < 150) - weight = FC_WEIGHT_THIN; - else if (os2->usWeightClass < 250) - weight = FC_WEIGHT_EXTRALIGHT; - else if (os2->usWeightClass < 350) - weight = FC_WEIGHT_LIGHT; - else if (os2->usWeightClass < 450) - weight = FC_WEIGHT_REGULAR; - else if (os2->usWeightClass < 550) - weight = FC_WEIGHT_MEDIUM; - else if (os2->usWeightClass < 650) - weight = FC_WEIGHT_SEMIBOLD; - else if (os2->usWeightClass < 750) - weight = FC_WEIGHT_BOLD; - else if (os2->usWeightClass < 850) - weight = FC_WEIGHT_EXTRABOLD; - else if (os2->usWeightClass < 925) - weight = FC_WEIGHT_BLACK; - else if (os2->usWeightClass < 1000) - weight = FC_WEIGHT_EXTRABLACK; + weight = FcWeightFromOpenType (os2->usWeightClass); if ((FcDebug() & FC_DBG_SCANV) && weight != -1) printf ("\tos2 weight class %d maps to weight %d\n", os2->usWeightClass, weight); diff --git a/fontconfig/src/fcint.h b/fontconfig/src/fcint.h index d3079edcc..45dfc6e61 100644 --- a/fontconfig/src/fcint.h +++ b/fontconfig/src/fcint.h @@ -1152,12 +1152,6 @@ FcStrCmpIgnoreBlanksAndCase (const FcChar8 *s1, const FcChar8 *s2); FcPrivate int FcStrCmpIgnoreCaseAndDelims (const FcChar8 *s1, const FcChar8 *s2, const FcChar8 *delims); -FcPrivate FcBool -FcStrRegexCmp (const FcChar8 *s, const FcChar8 *regex); - -FcPrivate FcBool -FcStrRegexCmpIgnoreCase (const FcChar8 *s, const FcChar8 *regex); - FcPrivate const FcChar8 * FcStrContainsIgnoreBlanksAndCase (const FcChar8 *s1, const FcChar8 *s2); diff --git a/fontconfig/src/fcmatch.c b/fontconfig/src/fcmatch.c index 78255186f..b0e695df3 100644 --- a/fontconfig/src/fcmatch.c +++ b/fontconfig/src/fcmatch.c @@ -483,7 +483,7 @@ FcFontRenderPrepare (FcConfig *config, { FcPattern *new; int i; - FcPatternElt *fe, *pe, *fel, *pel; + FcPatternElt *fe, *pe; FcValue v; FcResult result; @@ -508,36 +508,25 @@ FcFontRenderPrepare (FcConfig *config, fe->object == FC_STYLE_OBJECT || fe->object == FC_FULLNAME_OBJECT) { + FcPatternElt *fel, *pel; + FC_ASSERT_STATIC ((FC_FAMILY_OBJECT + 1) == FC_FAMILYLANG_OBJECT); FC_ASSERT_STATIC ((FC_STYLE_OBJECT + 1) == FC_STYLELANG_OBJECT); FC_ASSERT_STATIC ((FC_FULLNAME_OBJECT + 1) == FC_FULLNAMELANG_OBJECT); fel = FcPatternObjectFindElt (font, fe->object + 1); pel = FcPatternObjectFindElt (pat, fe->object + 1); - } - else - { - fel = NULL; - pel = NULL; - } - pe = FcPatternObjectFindElt (pat, fe->object); - if (pe) - { - const FcMatcher *match = FcObjectToMatcher (pe->object, FcFalse); - if (!FcCompareValueList (pe->object, match, - FcPatternEltValues(pe), - FcPatternEltValues(fe), &v, NULL, NULL, &result)) - { - FcPatternDestroy (new); - return NULL; - } if (fel && pel) { + /* The font has name languages, and pattern asks for specific language(s). + * Match on language and and prefer that result. + * Note: Currently the code only give priority to first matching language. + */ int n = 1, j; FcValueListPtr l1, l2, ln = NULL, ll = NULL; + const FcMatcher *match = FcObjectToMatcher (pel->object, FcTrue); - match = FcObjectToMatcher (pel->object, FcTrue); if (!FcCompareValueList (pel->object, match, FcPatternEltValues (pel), FcPatternEltValues (fel), NULL, NULL, &n, &result)) @@ -580,9 +569,10 @@ FcFontRenderPrepare (FcConfig *config, } else if (fel) { + /* Pattern doesn't ask for specific language. Copy all for name and + * lang. */ FcValueListPtr l1, l2; - copy_lang: l1 = FcValueListDuplicate (FcPatternEltValues (fe)); l2 = FcValueListDuplicate (FcPatternEltValues (fel)); FcPatternObjectListAdd (new, fe->object, l1, FcFalse); @@ -590,12 +580,23 @@ FcFontRenderPrepare (FcConfig *config, continue; } + } + + pe = FcPatternObjectFindElt (pat, fe->object); + if (pe) + { + const FcMatcher *match = FcObjectToMatcher (pe->object, FcFalse); + if (!FcCompareValueList (pe->object, match, + FcPatternEltValues(pe), + FcPatternEltValues(fe), &v, NULL, NULL, &result)) + { + FcPatternDestroy (new); + return NULL; + } FcPatternObjectAdd (new, fe->object, v, FcFalse); } else { - if (fel) - goto copy_lang; FcPatternObjectListAdd (new, fe->object, FcValueListDuplicate (FcPatternEltValues (fe)), FcTrue); diff --git a/fontconfig/src/fcname.c b/fontconfig/src/fcname.c index 466617872..1d8fe757c 100644 --- a/fontconfig/src/fcname.c +++ b/fontconfig/src/fcname.c @@ -136,6 +136,8 @@ static const FcConstant _FcBaseConstants[] = { { (FcChar8 *) "thin", "weight", FC_WEIGHT_THIN, }, { (FcChar8 *) "extralight", "weight", FC_WEIGHT_EXTRALIGHT, }, { (FcChar8 *) "ultralight", "weight", FC_WEIGHT_EXTRALIGHT, }, + { (FcChar8 *) "demilight", "weight", FC_WEIGHT_DEMILIGHT, }, + { (FcChar8 *) "semilight", "weight", FC_WEIGHT_DEMILIGHT, }, { (FcChar8 *) "light", "weight", FC_WEIGHT_LIGHT, }, { (FcChar8 *) "book", "weight", FC_WEIGHT_BOOK, }, { (FcChar8 *) "regular", "weight", FC_WEIGHT_REGULAR, }, diff --git a/fontconfig/src/fcrange.c b/fontconfig/src/fcrange.c index 7d0c1c0b1..39eafd82d 100644 --- a/fontconfig/src/fcrange.c +++ b/fontconfig/src/fcrange.c @@ -205,3 +205,7 @@ FcRangeSerialize (FcSerialize *serialize, const FcRange *r) return r_serialize; } + +#define __fcrange__ +#include "fcaliastail.h" +#undef __fcrange__ diff --git a/fontconfig/src/fcstat.c b/fontconfig/src/fcstat.c index 0a880975a..bbae10216 100644 --- a/fontconfig/src/fcstat.c +++ b/fontconfig/src/fcstat.c @@ -360,3 +360,7 @@ FcIsFsMtimeBroken (const FcChar8 *dir) return FcFalse; } + +#define __fcstat__ +#include "fcaliastail.h" +#undef __fcstat__ diff --git a/fontconfig/src/fcstr.c b/fontconfig/src/fcstr.c index 024dae325..29a577d10 100644 --- a/fontconfig/src/fcstr.c +++ b/fontconfig/src/fcstr.c @@ -26,9 +26,6 @@ #include <stdlib.h> #include <ctype.h> #include <string.h> -#ifdef HAVE_REGEX_H -#include <regex.h> -#endif /* Objects MT-safe for readonly access. */ @@ -242,55 +239,6 @@ FcStrCmp (const FcChar8 *s1, const FcChar8 *s2) return (int) c1 - (int) c2; } -#ifdef USE_REGEX -static FcBool -_FcStrRegexCmp (const FcChar8 *s, const FcChar8 *regex, int cflags, int eflags) -{ - int ret = -1; - regex_t reg; - - if ((ret = regcomp (®, (const char *)regex, cflags)) != 0) - { - if (FcDebug () & FC_DBG_MATCHV) - { - char buf[512]; - - regerror (ret, ®, buf, 512); - printf("Regexp compile error: %s\n", buf); - } - return FcFalse; - } - ret = regexec (®, (const char *)s, 0, NULL, eflags); - if (ret != 0) - { - if (FcDebug () & FC_DBG_MATCHV) - { - char buf[512]; - - regerror (ret, ®, buf, 512); - printf("Regexp exec error: %s\n", buf); - } - } - regfree (®); - - return ret == 0 ? FcTrue : FcFalse; -} -#else -# define _FcStrRegexCmp(_s_, _regex_, _cflags_, _eflags_) (FcFalse) -#endif - -FcBool -FcStrRegexCmp (const FcChar8 *s, const FcChar8 *regex) -{ - return _FcStrRegexCmp (s, regex, REG_EXTENDED | REG_NOSUB, 0); -} - -FcBool -FcStrRegexCmpIgnoreCase (const FcChar8 *s, const FcChar8 *regex) -{ - return _FcStrRegexCmp (s, regex, REG_EXTENDED | REG_NOSUB | REG_ICASE, 0); -} - /* * Return a hash value for a string */ diff --git a/fontconfig/src/fcweight.c b/fontconfig/src/fcweight.c new file mode 100644 index 000000000..87bbe67ab --- /dev/null +++ b/fontconfig/src/fcweight.c @@ -0,0 +1,88 @@ +/* + * fontconfig/src/fcweight.c + * + * Permission to use, copy, modify, distribute, and sell this software and its + * documentation for any purpose is hereby granted without fee, provided that + * the above copyright notice appear in all copies and that both that + * copyright notice and this permission notice appear in supporting + * documentation, and that the name of the author(s) not be used in + * advertising or publicity pertaining to distribution of the software without + * specific, written prior permission. The authors make no + * representations about the suitability of this software for any purpose. It + * is provided "as is" without express or implied warranty. + * + * THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + * EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR + * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + * PERFORMANCE OF THIS SOFTWARE. + */ + +#include "fcint.h" + +static const struct { + int ot; + int fc; +} map[] = { + { 0, FC_WEIGHT_THIN }, + { 100, FC_WEIGHT_THIN }, + { 200, FC_WEIGHT_EXTRALIGHT }, + { 350, FC_WEIGHT_DEMILIGHT }, + { 300, FC_WEIGHT_LIGHT }, + { 380, FC_WEIGHT_BOOK }, + { 400, FC_WEIGHT_REGULAR }, + { 500, FC_WEIGHT_MEDIUM }, + { 600, FC_WEIGHT_DEMIBOLD }, + { 700, FC_WEIGHT_BOLD }, + { 800, FC_WEIGHT_EXTRABOLD }, + { 900, FC_WEIGHT_BLACK }, + {1000, FC_WEIGHT_EXTRABLACK }, +}; + +static int lerp(int x, int x1, int x2, int y1, int y2) +{ + int dx = x2 - x1; + int dy = y2 - y1; + assert (dx > 0 && dy > 0 && x1 <= x && x <= x2); + return y1 + (dy*(x-x1) + dx/2) / dx; +} + +FcPublic int +FcWeightFromOpenType (int ot_weight) +{ + int i; + if (ot_weight <= 0 || ot_weight > 1000) + return -1; + + for (i = 1; ot_weight > map[i].ot; i++) + ; + + if (ot_weight == map[i].ot) + return map[i].fc; + + /* Interpolate between two items. */ + return lerp (ot_weight, map[i-1].ot, map[i].ot, map[i-1].fc, map[i].fc); +} + +FcPublic int +FcWeightToOpenType (int fc_weight) +{ + int i; + if (fc_weight < 0 || fc_weight > FC_WEIGHT_EXTRABLACK) + return -1; + + for (i = 1; fc_weight > map[i].fc; i++) + ; + + if (fc_weight == map[i].fc) + return map[i].ot; + + /* Interpolate between two items. */ + return lerp (fc_weight, map[i-1].fc, map[i].fc, map[i-1].ot, map[i].ot); +} + +#define __fcweight__ +#include "fcaliastail.h" +#undef __fcweight__ diff --git a/fontconfig/src/fcwindows.h b/fontconfig/src/fcwindows.h index 02489d9dc..a0eee675e 100644 --- a/fontconfig/src/fcwindows.h +++ b/fontconfig/src/fcwindows.h @@ -32,8 +32,13 @@ #endif #ifdef _WIN32 + /* Request Windows Vista for building. This is required to + * get MemoryBarrier on mingw32... */ +# if defined(_WIN32_WINNT) && _WIN32_WINNT < 0x0600 +# undef _WIN32_WINNT +# endif # ifndef _WIN32_WINNT -# define _WIN32_WINNT 0x0500 +# define _WIN32_WINNT 0x0600 # endif # define WIN32_LEAN_AND_MEAN # define WIN32_EXTRA_LEAN diff --git a/libX11/specs/XKB/acknowledgement.xml b/libX11/specs/XKB/acknowledgement.xml index 4ecb798c1..43be0946f 100644 --- a/libX11/specs/XKB/acknowledgement.xml +++ b/libX11/specs/XKB/acknowledgement.xml @@ -1,3 +1,6 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <preface id='acknowledgement'> <title>Acknowledgement</title> <para> @@ -36,8 +39,10 @@ X Consortium Inc. This document is made available to you in modern formats such as HTML and PDF thanks to the efforts of Matt Dew, who converted the original troff sources to DocBook/XML and edited them into shape; Fernando Carrijo, who converted the -images to SVG format; and Gaetan Nadon, who set up the formatting machinery in -the libX11 builds and performed further editing of the DocBook markup. +images to SVG format; Gaetan Nadon, who set up the formatting machinery in +the libX11 builds and performed further editing of the DocBook markup; and +Alan Coopersmith, who converted the DocBook tags to semantic markup and +cleaned up other formatting issues. </para> </simplesect> </preface> diff --git a/libX11/specs/XKB/ch01.xml b/libX11/specs/XKB/ch01.xml index 15cc97dad..79aed476d 100644 --- a/libX11/specs/XKB/ch01.xml +++ b/libX11/specs/XKB/ch01.xml @@ -1,3 +1,6 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Overview'> <title>Overview</title> @@ -11,12 +14,12 @@ cumbersome in the core X protocol. <para> The core X protocol specifies the ways that the -<emphasis>Shift</emphasis>, -<emphasis>Control</emphasis>, and -<emphasis>Lock</emphasis> +<symbol>Shift</symbol>, +<symbol>Control</symbol>, and +<symbol>Lock</symbol> modifiers and the modifiers bound to the -<emphasis>Mode_switch</emphasis> or -<emphasis>Num_Lock</emphasis> +<keysym>Mode_switch</keysym> or +<keysym>Num_Lock</keysym> 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 @@ -43,7 +46,7 @@ Furthermore, this approach limits the number of keyboard groups to two. <listitem> <para> Poorly specified locking key behavior requires X servers to look for a few -"magic" keysyms to determine that keys should lock when pressed. This leads to +<quote>magic</quote> keysyms to determine that keys should lock when pressed. This leads to incompatibilities between X servers with no way for clients to detect implementation differences. </para> @@ -60,7 +63,7 @@ incompatibilities between system wide and X library capitalization behavior. Limited interactions between modifiers specified by the core protocol make many common keyboard behaviors difficult or impossible to implement. For example, there is no reliable way to indicate whether or not the shift modifier should -"cancel" the lock modifier. +<quote>cancel</quote> the lock modifier. </para> </listitem> <listitem> @@ -105,23 +108,28 @@ server and Xlib versions must be at least X11 R6. <para> -Figure 1.1 shows the overall structure of the Xkb extension: +<link linkend="figure1.1">Figure 1.1</link> shows the overall structure of the Xkb extension: </para> -<mediaobject> - <imageobject> - <imagedata format="SVG" fileref="XKBlib-1.svg"/> - </imageobject> - <caption>Overall Xkb Structure</caption> -</mediaobject> +<figure id='figure1.1'> + <title>Overall Xkb Structure</title> + <mediaobject> + <imageobject> + <imagedata format="SVG" fileref="XKBlib-1.svg"/> + </imageobject> + </mediaobject> +</figure> -<para> +<para id="keyboard_description"> The server portion of the Xkb extension encompasses a database of named keyboard components, in unspecified format, that may be used to configure a -keyboard. Internally, the server maintains a <emphasis> -keyboard description</emphasis> - that includes the keyboard state and configuration (mapping). By "keyboard" we +keyboard. Internally, the server maintains a +<firstterm>keyboard description</firstterm> +<indexterm significance="preferred" zone="keyboard_description"> +<primary>keyboard description</primary></indexterm> +that includes the keyboard state and configuration (mapping). By +<quote>keyboard</quote> we mean the logical keyboard device, which includes not only the physical keys, but also potentially a set of up to 32 indicators (usually LEDs) and bells. </para> @@ -131,12 +139,12 @@ but also potentially a set of up to 32 indicators (usually LEDs) and bells. The keyboard description is a composite of several different data structures, each of which may be manipulated separately. When manipulating the server components, the design allows partial components to be transmitted between the -server and a client. The individual components are shown in Figure 1.1. +server and a client. The individual components are shown in <link linkend="figure1.1">Figure 1.1</link>. </para> <variablelist> <varlistentry> - <term>Client Map</term> + <term><link linkend="Xkb_Client_Keyboard_Mapping">Client Map</link></term> <listitem> <para> The key mapping information needed to convert arbitrary keycodes to symbols. @@ -144,7 +152,7 @@ The key mapping information needed to convert arbitrary keycodes to symbols. </listitem> </varlistentry> <varlistentry> - <term>Server Map</term> + <term><link linkend="Xkb_Server_Keyboard_Mapping">Server Map</link></term> <listitem> <para> The key mapping information categorizing keys by functionality (which keys are @@ -153,7 +161,7 @@ modifiers, how keys behave, and so on). </listitem> </varlistentry> <varlistentry> - <term>Controls</term> + <term><link linkend="Keyboard_Controls">Controls</link></term> <listitem> <para> Client configurable quantities effecting how the keyboard behaves, such as @@ -162,7 +170,7 @@ repeat behavior and modifications for people with movement impairments. </listitem> </varlistentry> <varlistentry> - <term>Indicators</term> + <term><link linkend="Indicators">Indicators</link></term> <listitem> <para> The mapping of behavior to indicators. @@ -170,7 +178,7 @@ The mapping of behavior to indicators. </listitem> </varlistentry> <varlistentry> - <term>Geometry</term> + <term><link linkend="Keyboard_Geometry">Geometry</link></term> <listitem> <para> A complete description of the physical keyboard layout, sufficient to draw a @@ -179,7 +187,7 @@ representation of the keyboard. </listitem> </varlistentry> <varlistentry> - <term>Names</term> + <term><link linkend="Symbolic_Names">Names</link></term> <listitem> <para> A mapping of names to various aspects of the keyboard such as individual @@ -188,7 +196,7 @@ virtual modifiers, indicators, and bells. </listitem> </varlistentry> <varlistentry> - <term>Compatibility Map</term> + <term><link linkend="The_Xkb_Compatibility_Map">Compatibility Map</link></term> <listitem> <para> The definition of how to map core protocol keyboard state to Xkb keyboard state. @@ -219,7 +227,7 @@ and incremental reconfiguration are both supported. <para> The graphic characters or control functions that may be accessed by one key are -logically arranged in groups and levels. See section 14.1for a complete +logically arranged in groups and levels. See <link linkend="Notation_and_Terminology">section 14.1</link> for a complete description of groups and levels. </para> @@ -229,14 +237,19 @@ description of groups and levels. <title>Radio Groups</title> <para> -A radio group is a set of keys whose behavior simulates a set of radio buttons. +<indexterm significance="preferred" zone="Radio_Groups"> +<primary>radio group</primary></indexterm> +<indexterm significance="preferred" zone="Radio_Groups"> +<primary>group</primary><secondary>radio</secondary></indexterm> +A <firstterm>radio group</firstterm> +is a set of keys whose behavior simulates a set of radio buttons. Once a key in a radio group is pressed, it stays logically depressed until another key in the group is pressed, at which point the previously depressed key is logically released. Consequently, at most one key in a radio group can be logically depressed at one time. A radio group is defined by a radio group -index, an optional name, and by assigning each key in the radio group <emphasis> -XkbKB_RadioGroup</emphasis> - behavior and the radio group index. +index, an optional name, and by assigning each key in the radio group +<symbol>XkbKB_RadioGroup</symbol> +behavior and the radio group index. </para> </sect2> @@ -305,12 +318,11 @@ configuration. <title>Additional Protocol Errors</title> <para> -The Xkb extension adds a single protocol error, <emphasis> -BadKeyboard</emphasis> -, to the core protocol error set. See section 2.6 for a discussion of the <!-- xref --> -<emphasis> -BadKeyboard</emphasis> - protocol error. +The Xkb extension adds a single protocol error, +<errorname>BadKeyboard</errorname>, +to the core protocol error set. See <link linkend="Protocol_Errors">section 2.6</link> for a discussion of the +<errorname>BadKeyboard</errorname> +protocol error. </para> @@ -322,7 +334,7 @@ BadKeyboard</emphasis> The X Keyboard Extension replaces the core protocol definition of a keyboard with a more comprehensive one. The X Keyboard Extension library interfaces are included in Xlib.<footnote><para> -X11R6.1 is the first release by the X Consortium, Inc.,that includes the X +X11R6.1 is the first release by the X Consortium, Inc., that includes the X Keyboard Extension in Xlib. X11R6 included work in progress on this extension as nonstandard additions to the library. </para> @@ -347,21 +359,23 @@ directly manipulate the new capabilities. <sect2 id='Error_Indications'> <title>Error Indications</title> +<indexterm zone="Error_Indications"><primary>errors</primary></indexterm> <para> Xkb functions that communicate with the X server check to be sure the Xkb extension has been properly initialized prior to doing any other operations. If the extension has not been properly initialized or the application, library, and server versions are incompatible, these functions return an error -indication as shown in Table 1.1. Because of this test, <emphasis> -BadAccess</emphasis> - and <emphasis> -BadMatch</emphasis> - (due to incompatible versions) protocol errors should normally not be +indication as shown in <link linkend="table1.1">Table 1.1</link>. +Because of this test, +<errorname>BadAccess</errorname> +and +<errorname>BadMatch</errorname> +(due to incompatible versions) protocol errors should normally not be generated. </para> -<table frame='topbot'> +<table id='table1.1' frame='topbot'> <!-- <caption>Function Error Returns Due to Extension Problems</caption> --> <title>Function Error Returns Due to Extension Problems</title> <?dbfo keep-together="always" ?> @@ -377,15 +391,15 @@ generated. <tbody> <row> <entry>pointer to a structure</entry> - <entry>NULL</entry> + <entry><symbol>NULL</symbol></entry> </row> <row> <entry>Bool</entry> - <entry>False</entry> + <entry><symbol>False</symbol></entry> </row> <row> <entry>Status</entry> - <entry>BadAccess</entry> + <entry><errorname>BadAccess</errorname></entry> </row> </tbody> </tgroup> @@ -398,7 +412,8 @@ applications may never actually need to communicate with the server; they simply use the Xkb library capabilities. The functions that do not communicate with the server return either a pointer to a structure, a Bool, or a Status. These functions check that the application has queried the Xkb library version -and return the values shown in Table 1.1 if it has not. +and return the values shown in <link linkend="table1.1">Table 1.1</link> +if it has not. </para> </sect2> </sect1> diff --git a/libX11/specs/XKB/ch02.xml b/libX11/specs/XKB/ch02.xml index b626a4322..ca0616e6e 100644 --- a/libX11/specs/XKB/ch02.xml +++ b/libX11/specs/XKB/ch02.xml @@ -1,3 +1,6 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Initialization_and_General_Programming_Information'> <title>Initialization and General Programming Information</title> <sect1 id='Extension_Header_Files'> @@ -8,40 +11,40 @@ The following include files are part of the Xkb standard: <itemizedlist> <listitem> <para> -<emphasis><X11/XKBlib.h></emphasis> +<filename class="headerfile"><X11/XKBlib.h></filename> </para> - <para><emphasis>XKBlib.h</emphasis> + <para><filename class="headerfile">XKBlib.h</filename> is the main header file for Xkb; it declares constants, types, and functions. </para> </listitem> <listitem> <para> -<emphasis><X11/extensions/XKBstr.h></emphasis> +<filename class="headerfile"><X11/extensions/XKBstr.h></filename> </para> <para> -<emphasis>XKBstr.h</emphasis> declares types and +<filename class="headerfile">XKBstr.h</filename> declares types and constants for Xkb. It is included automatically from -<emphasis><X11/XKBlib.h></emphasis> -; you should never need to reference it directly in your application code. +<filename class="headerfile"><X11/XKBlib.h></filename>; +you should never need to reference it directly in your application code. </para> </listitem> <listitem> <para> -<emphasis><X11/extensions/XKB.h></emphasis> +<filename class="headerfile"><X11/extensions/XKB.h></filename> </para> <para> -<emphasis>XKB.h</emphasis> -defines constants for Xkb. It is included automatically from <emphasis> -<X11/XKBstr.h></emphasis> -; you should never need to reference it directly in your application code. +<filename class="headerfile">XKB.h</filename> +defines constants for Xkb. It is included automatically from +<filename class="headerfile"><X11/XKBstr.h></filename>; +you should never need to reference it directly in your application code. </para> </listitem> <listitem> <para> -<emphasis><X11/extensions/XKBgeom.h></emphasis> +<filename class="headerfile"><X11/extensions/XKBgeom.h></filename> </para> - <para><emphasis>XKBgeom.h</emphasis> + <para><filename class="headerfile">XKBgeom.h</filename> declares types, symbolic constants, and functions for manipulating keyboard geometry descriptions. </para> @@ -50,24 +53,24 @@ keyboard geometry descriptions. </sect1> <sect1 id='Extension_Name'> <title>Extension Name</title> +<indexterm significance="preferred" zone="Extension_Name"><primary><symbol>XkbName</symbol></primary></indexterm> <para> -The name of the Xkb extension is given in <emphasis> -<X11/extensions/Xkb.h>:</emphasis> -</para> +The name of the Xkb extension is given in +<filename class="headerfile"><X11/extensions/Xkb.h></filename>: -<para> -<emphasis> -#define XkbName "XKEYBOARD"</emphasis> +<programlisting> +#define XkbName "XKEYBOARD" +</programlisting> </para> <para> -Most extensions to the X protocol are initialized by calling <emphasis> -XInitExtension</emphasis> - and passing the extension name. However, as explained in section 2.4, Xkb +Most extensions to the X protocol are initialized by calling +<function>XInitExtension</function> +and passing the extension name. However, as explained in <link linkend="Initializing_the_Keyboard_Extension">section 2.4</link>, Xkb requires a more complex initialization sequence, and a client program should -not call <emphasis> -XInitExtension</emphasis> - directly. +not call +<function>XInitExtension</function> +directly. </para> </sect1> <sect1 id='Determining_Library_Compatibility'> @@ -89,384 +92,409 @@ against one set of header files and link against a different, incompatible, version of the library, although this should not normally occur.) </para> <para> -To determine the compatibility of a library at runtime, call <emphasis> -XkbLibraryVersion</emphasis>. +To determine the compatibility of a library at runtime, call +<function>XkbLibraryVersion</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbLibraryVersion</emphasis> -(<emphasis> -lib_major_in_out</emphasis> -, <emphasis> -lib_minor_in_out</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -int * <emphasis> -lib_major_in_out;</emphasis> - /* specifies and returns the major Xkb library version. */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int * <emphasis> -lib_minor_in_out;</emphasis> - /* specifies and returns the minor Xkb library version. */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -Pass the symbolic value <emphasis> -XkbMajorVersion</emphasis> - in <emphasis> -lib_major_in_out</emphasis> - and <emphasis> -XkbMinorVersion</emphasis> - in <emphasis> -lib_minor_in_out</emphasis> -. These arguments represent the version of the library used at compile time. -The <emphasis> -XkbLibraryVersion </emphasis> +<indexterm significance="preferred" zone="XkbLibraryVersion"><primary><function>XkbLibraryVersion</function></primary></indexterm> +<funcsynopsis id="XkbLibraryVersion"> + <funcprototype> + <funcdef>Bool <function>XkbLibraryVersion</function></funcdef> +<!-- ( +<parameter>lib_major_in_out</parameter>, +<parameter>lib_minor_in_out</parameter> +) --> + + <paramdef>int *<parameter>lib_major_in_out</parameter></paramdef> + <paramdef>int *<parameter>lib_minor_in_out</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>lib_major_in_out</parameter> + </term> + <listitem> + <para> + specifies and returns the major Xkb library version. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>lib_minor_in_out</parameter> + </term> + <listitem> + <para> + specifies and returns the minor Xkb library version. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +Pass the symbolic value +<symbol>XkbMajorVersion</symbol> +in +<parameter>lib_major_in_out</parameter> +and +<symbol>XkbMinorVersion</symbol> +in +<parameter>lib_minor_in_out</parameter>. +These arguments represent the version of the library used at compile time. +The +<function>XkbLibraryVersion</function> function backfills the major and minor version numbers of the library used at -run time in <emphasis> -lib_major_in_out</emphasis> - and <emphasis> -lib_minor_in_out</emphasis> -. If the versions of the compile time and run time libraries are compatible, -<emphasis> -XkbLibraryVersion </emphasis> -returns <emphasis> -True</emphasis> -, otherwise, it returns <emphasis> -False.</emphasis> +run time in +<parameter>lib_major_in_out</parameter> +and +<parameter>lib_minor_in_out</parameter>. +If the versions of the compile time and run time libraries are compatible, +<function>XkbLibraryVersion</function> +returns +<symbol>True</symbol>, +otherwise, it returns +<symbol>False</symbol>. </para> <para> In addition, in order to use the Xkb extension, you must ensure that the extension is present in the server and that the server supports the version of -the extension expected by the client. Use <emphasis> -XkbQueryExtension</emphasis> - to do this, as described in the next section. +the extension expected by the client. Use +<function>XkbQueryExtension</function> +to do this, as described in the next section. </para> </sect1> <sect1 id='Initializing_the_Keyboard_Extension'> <title>Initializing the Keyboard Extension</title> <para> -Call <emphasis> -XkbQueryExtension</emphasis> - to check for the presence and compatibility of the extension in the server and +Call +<function>XkbQueryExtension</function> +to check for the presence and compatibility of the extension in the server and to initialize the extension. Because of potential version mismatches, you -cannot use the generic extension mechanism functions (<emphasis> -XQueryExtension </emphasis> -and<emphasis> - XInitExtension</emphasis> -) for checking for the presence of, and initializing the Xkb extension. +cannot use the generic extension mechanism functions +(<function>XQueryExtension</function> +and +<function>XInitExtension</function>) +for checking for the presence of, and initializing the Xkb extension. </para> <para> -You must call <emphasis> -XkbQueryExtension</emphasis> - or <emphasis> -XkbOpenDisplay</emphasis> - before using any other Xkb library interfaces, unless such usage is explicitly +You must call +<function>XkbQueryExtension</function> +or +<function>XkbOpenDisplay</function> +before using any other Xkb library interfaces, unless such usage is explicitly allowed in the interface description in this document. The exceptions are: -<emphasis> -XkbIgnoreExtension</emphasis> -, <emphasis> -XkbLibraryVersion</emphasis> -, and a handful of audible-bell functions. You should not use any other Xkb +<function>XkbIgnoreExtension</function>, +<function>XkbLibraryVersion</function>, +and a handful of audible-bell functions. You should not use any other Xkb functions if the extension is not present or is uninitialized. In general, calls to Xkb library functions made prior to initializing the Xkb extension -cause <emphasis> -BadAccess</emphasis> - protocol errors. +cause +<errorname>BadAccess</errorname> +protocol errors. +<indexterm zone="Initializing_the_Keyboard_Extension"><primary>errors</primary> +<secondary><errorname>BadAccess</errorname></secondary></indexterm> +<indexterm zone="Initializing_the_Keyboard_Extension"> +<primary><errorname>BadAccess</errorname></primary></indexterm> </para> <para> -<emphasis> -XkbQueryExtension</emphasis> - both determines whether a compatible Xkb extension is present in the X server +<function>XkbQueryExtension</function> +both determines whether a compatible Xkb extension is present in the X server and initializes the extension when it is present. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbQueryExtension</emphasis> -(<emphasis> -dpy, opcode_rtrn, event_rtrn, error_rtrn, major_in_out, minor_in_out</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy; </emphasis> - /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int * <emphasis> -opcode_rtrn</emphasis> -; /* backfilled with the major extension opcode */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int * <emphasis> -event_rtrn</emphasis> -; /* backfilled with the extension base event code */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int * <emphasis> -error_rtrn</emphasis> -; /* backfilled with the extension base error code */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int * <emphasis> -major_in_out</emphasis> -; /* compile time lib major version in, server major version out */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int * <emphasis> -minor_in_out; </emphasis> - /* compile time lib min version in, server minor version out */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -The <emphasis> -XkbQueryExtension</emphasis> - function determines whether a compatible version of the X Keyboard Extension -is present in the server. If a compatible extension is present, <emphasis> -XkbQueryExtension</emphasis> - returns <emphasis> -True</emphasis> -; otherwise, it returns <emphasis> -False</emphasis> -. -</para> - -<para> -If a compatible version of Xkb is present, <emphasis> -XkbQueryExtension</emphasis> - initializes the extension. It backfills the major opcode for the keyboard -extension in <emphasis> -opcode_rtrn</emphasis> -, the base event code in <emphasis> -event_rtrn</emphasis> -<emphasis> -, the base error code</emphasis> - in <emphasis> -error_rtrn</emphasis> -, and the major and minor version numbers of the extension in <emphasis> -major_in_out</emphasis> - and <emphasis> -minor_in_out</emphasis> -. The major opcode is reported in the <emphasis> -req_major</emphasis> - fields of some Xkb events. For a discussion of the base event code, see -section 4.1. <!-- xref --> -</para> - -<para> -As a convenience, you can use the function <emphasis> -XkbOpenDisplay</emphasis> - to perform these three tasks at once: open a connection to an X server, check +<indexterm significance="preferred" zone="XkbQueryExtension"><primary><function>XkbQueryExtension</function></primary></indexterm> +<funcsynopsis id="XkbQueryExtension"> + <funcprototype> + <funcdef>Bool <function>XkbQueryExtension</function></funcdef> +<!-- ( +<parameter>dpy, opcode_rtrn, event_rtrn, error_rtrn, major_in_out, minor_in_out</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>int *<parameter>opcode_rtrn</parameter></paramdef> + <paramdef>int *<parameter>event_rtrn</parameter></paramdef> + <paramdef>int *<parameter>error_rtrn</parameter></paramdef> + <paramdef>int *<parameter>major_in_out</parameter></paramdef> + <paramdef>int *<parameter>minor_in_out</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>opcode_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with the major extension opcode + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>event_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with the extension base event code + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>error_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with the extension base error code + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>major_in_out</parameter> + </term> + <listitem> + <para> + compile time lib major version in, server major version out + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>minor_in_out</parameter> + </term> + <listitem> + <para> + compile time lib min version in, server minor version out + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<function>XkbQueryExtension</function> +function determines whether a compatible version of the X Keyboard Extension +is present in the server. If a compatible extension is present, +<function>XkbQueryExtension</function> +returns +<symbol>True</symbol>; +otherwise, it returns +<symbol>False</symbol>. +</para> + +<para> +If a compatible version of Xkb is present, +<function>XkbQueryExtension</function> +initializes the extension. It backfills the major opcode for the keyboard +extension in +<parameter>opcode_rtrn</parameter>, +the base event code in +<parameter>event_rtrn</parameter>, +the base error code in +<parameter>error_rtrn</parameter>, +and the major and minor version numbers of the extension in +<parameter>major_in_out</parameter> +and +<parameter>minor_in_out</parameter>. +The major opcode is reported in the +<structfield>req_major</structfield> +fields of some Xkb events. For a discussion of the base event code, see +<link linkend="Xkb_Event_Types">section 4.1</link>. +</para> + +<para> +As a convenience, you can use the function +<function>XkbOpenDisplay</function> +to perform these three tasks at once: open a connection to an X server, check for a compatible version of the Xkb extension in both the library and the server, and initialize the extension for use. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Display *<emphasis> -XkbOpenDisplay</emphasis> -(<emphasis> -display_name, event_rtrn, error_rtrn, major_in_out, minor_in_out, -reason_rtrn)</emphasis> - </entry> - </row> - <row> - <entry role='functionargdecl'> -char * <emphasis> -display_name</emphasis> -; /* hardware display name, which determines the display and -communications domain to be used */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int * <emphasis> -event_rtrn</emphasis> -; /* backfilled with the extension base event code */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int * <emphasis> -error_rtrn</emphasis> -; /* backfilled with the extension base error code */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int * <emphasis> -major_in_out</emphasis> -; /* compile time lib major version in, server major version out */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int * <emphasis> -minor_in_out</emphasis> -; /* compile time lib minor version in, server minor version out */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int * <emphasis> -reason_rtrn</emphasis> -; /* backfilled with a status code */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbOpenDisplay"><primary><function>XkbOpenDisplay</function></primary></indexterm> +<funcsynopsis id="XkbOpenDisplay"> + <funcprototype> + <funcdef>Display *<function>XkbOpenDisplay</function></funcdef> +<!-- ( +<parameter>display_name, event_rtrn, error_rtrn, major_in_out, minor_in_out, +reason_rtrn)</parameter> --> + + <paramdef>char *<parameter>display_name</parameter></paramdef> + <paramdef>int *<parameter>event_rtrn</parameter></paramdef> + <paramdef>int *<parameter>error_rtrn</parameter></paramdef> + <paramdef>int *<parameter>major_in_out</parameter></paramdef> + <paramdef>int *<parameter>minor_in_out</parameter></paramdef> + <paramdef>int *<parameter>reason_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display_name</parameter> + </term> + <listitem> + <para> + hardware display name, which determines the display and + communications domain to be used + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>event_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with the extension base event code + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>error_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with the extension base error code + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>major_in_out</parameter> + </term> + <listitem> + <para> + compile time lib major version in, server major version out + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>minor_in_out</parameter> + </term> + <listitem> + <para> + compile time lib minor version in, server minor version out + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>reason_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with a status code + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbOpenDisplay </emphasis> +<function>XkbOpenDisplay</function> is a convenience function that opens an X display connection and initializes -the X keyboard extension. In all cases, upon return <emphasis> -reason_rtrn</emphasis> - contains a status value indicating success or the type of failure. If -<emphasis> -major_in_out</emphasis> - and <emphasis> -minor_in_out</emphasis> - are not <emphasis> -NULL</emphasis> -, <emphasis> -XkbOpenDisplay</emphasis> - first calls <emphasis> -XkbLibraryVersion</emphasis> - to determine whether the client library is compatible, passing it the values -pointed to by <emphasis> -major_in_out</emphasis> - and <emphasis> -minor_in_out</emphasis> -. If the library is incompatible, <emphasis> -XkbOpenDisplay</emphasis> - backfills <emphasis> -major_in_out</emphasis> - and <emphasis> -minor_in_out</emphasis> - with the major and minor extension versions of the library being used and -returns <emphasis> -NULL</emphasis> -. If the library is compatible,<emphasis> - XkbOpenDisplay </emphasis> -next calls <emphasis> -XOpenDisplay</emphasis> - with the <emphasis> -display_name</emphasis> -. If this fails, the function returns <emphasis> -NULL</emphasis> -. If successful, <emphasis> -XkbOpenDisplay </emphasis> -calls <emphasis> -XkbQueryExtension</emphasis> - and<emphasis> - </emphasis> -backfills the major and minor Xkb server extension version numbers in <emphasis> -major_in_out</emphasis> - and <emphasis> -minor_in_out</emphasis> -.<emphasis> - </emphasis> +the X keyboard extension. In all cases, upon return +<parameter>reason_rtrn</parameter> +contains a status value indicating success or the type of failure. If +<parameter>major_in_out</parameter> +and +<parameter>minor_in_out</parameter> +are not +<symbol>NULL</symbol>, +<function>XkbOpenDisplay</function> +first calls +<function>XkbLibraryVersion</function> +to determine whether the client library is compatible, passing it the values +pointed to by +<parameter>major_in_out</parameter> +and +<parameter>minor_in_out</parameter>. +If the library is incompatible, +<function>XkbOpenDisplay</function> +backfills +<parameter>major_in_out</parameter> +and +<parameter>minor_in_out</parameter> +with the major and minor extension versions of the library being used and +returns +<symbol>NULL</symbol>. +If the library is compatible, +<function>XkbOpenDisplay</function> +next calls +<function>XOpenDisplay</function> +with the +<parameter>display_name</parameter>. +If this fails, the function returns +<symbol>NULL</symbol>. +If successful, +<function>XkbOpenDisplay</function> +calls +<function>XkbQueryExtension</function> +and +backfills the major and minor Xkb server extension version numbers in +<parameter>major_in_out</parameter> +and +<parameter>minor_in_out</parameter>. If the server extension version is not compatible with the library extension -version or if the server extension is not present, <emphasis> -XkbOpenDisplay </emphasis> -closes the display and returns <emphasis> -NULL</emphasis> -. When successful, the function returns the display connection<emphasis> -.</emphasis> +version or if the server extension is not present, +<function>XkbOpenDisplay</function> +closes the display and returns +<symbol>NULL</symbol>. +When successful, the function returns the display connection. </para> <para> -The possible values for <emphasis> -reason_rtrn</emphasis> are: +The possible values for +<parameter>reason_rtrn</parameter> are: </para> <itemizedlist> <listitem> <para> -<emphasis> -XkbOD_BadLibraryVersion</emphasis> - indicates <emphasis> -XkbLibraryVersion </emphasis> -returned <emphasis> -False</emphasis>. +<errorname>XkbOD_BadLibraryVersion</errorname> +indicates +<function>XkbLibraryVersion</function> +returned +<symbol>False</symbol>. </para> </listitem> <listitem> <para> -<emphasis> -XkbOD_ConnectionRefused</emphasis> - indicates the display could not be opened. +<errorname>XkbOD_ConnectionRefused</errorname> +indicates the display could not be opened. </para> </listitem> <listitem> <para> -<emphasis> -XkbOD_BadServerVersion</emphasis> - indicates the library and the server have incompatible extension versions. +<errorname>XkbOD_BadServerVersion</errorname> +indicates the library and the server have incompatible extension versions. </para> </listitem> <listitem> <para> -<emphasis> -XkbOD_NonXkbServer</emphasis> - indicates the extension is not present in the X server. +<errorname>XkbOD_NonXkbServer</errorname> +indicates the extension is not present in the X server. </para> </listitem> <listitem> <para> -<emphasis> -XkbOD_Success</emphasis> - indicates that the function succeeded. +<errorname>XkbOD_Success</errorname> +indicates that the function succeeded. </para> </listitem> </itemizedlist> @@ -484,84 +512,82 @@ functionality. </para> <para> -Call <emphasis> -XkbIgnoreExtension</emphasis> - to prevent core X library keyboard functions from using the X Keyboard -Extension. You must call <emphasis> -XkbIgnoreExtension</emphasis> - before you open a server connection; Xkb does not provide a way to enable or +Call +<function>XkbIgnoreExtension</function> +to prevent core X library keyboard functions from using the X Keyboard +Extension. You must call +<function>XkbIgnoreExtension</function> +before you open a server connection; Xkb does not provide a way to enable or disable use of the extension once a connection is established. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool<emphasis> - XkbIgnoreExtension</emphasis> -(<emphasis> -ignore</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> -ignore</emphasis> -; /* <emphasis> -True</emphasis> - means ignore the extension */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbIgnoreExtension"><primary><function>XkbIgnoreExtension</function></primary></indexterm> +<funcsynopsis id="XkbIgnoreExtension"> + <funcprototype> + <funcdef>Bool <function>XkbIgnoreExtension</function></funcdef> +<!-- ( +<parameter>ignore</parameter> +) --> + + <paramdef>Bool <parameter>ignore</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>ignore</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> means ignore the extension + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbIgnoreExtension</emphasis> - tells the X library whether to use the X Keyboard Extension on any -subsequently opened X display connections. If ignore is <emphasis> -True</emphasis> -, the library does not initialize the Xkb extension when it opens a new +<function>XkbIgnoreExtension</function> +tells the X library whether to use the X Keyboard Extension on any +subsequently opened X display connections. If ignore is +<symbol>True</symbol>, +the library does not initialize the Xkb extension when it opens a new display. This forces the X server to use compatibility mode and communicate with the client using only core protocol requests and events. If ignore is -<emphasis> -False</emphasis> -, the library treats subsequent calls to <emphasis> -XOpenDisplay</emphasis> - normally and uses Xkb extension requests, events, and state. Do not explicitly -use Xkb on a connection for which it is disabled.<emphasis> - XkbIgnoreExtension</emphasis> - returns <emphasis> -False</emphasis> - if it was unable to apply the ignore request. +<symbol>False</symbol>, +the library treats subsequent calls to +<function>XOpenDisplay</function> +normally and uses Xkb extension requests, events, and state. Do not explicitly +use Xkb on a connection for which it is disabled. +<function>XkbIgnoreExtension</function> +returns +<symbol>False</symbol> +if it was unable to apply the ignore request. </para> </sect1> <sect1 id='Protocol_Errors'> <title>Protocol Errors</title> +<indexterm significance="preferred" zone="Protocol_Errors"> +<primary>errors</primary></indexterm> + <para> Many of the Xkb extension library functions described in this document can cause the X server to report an error, referred to in this document as a -<emphasis> -BadXxx</emphasis> - protocol error, where <emphasis> -Xxx</emphasis> - is some name. These errors are fielded in the normal manner, by the default +<errorname>Bad<replaceable>Xxx</replaceable></errorname> +protocol error, where +<replaceable>Xxx</replaceable> +is some name. These errors are fielded in the normal manner, by the default Xlib error handler or one replacing it. Note that X protocol errors are not necessarily reported immediately because of the buffering of X protocol requests in Xlib and the server. </para> <para> -Table 2.1 lists the protocol errors that can be generated, and their causes. <!-- xref --> +<link linkend="table2.1">Table 2.1</link> +lists the protocol errors that can be generated, and their causes. </para> -<table frame='topbot'> +<table id='table2.1' frame='topbot'> <title>Xkb Protocol Errors</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -575,7 +601,7 @@ Table 2.1 lists the protocol errors that can be generated, and their causes. <!- </thead> <tbody> <row> - <entry>BadAccess</entry> + <entry><errorname>BadAccess</errorname></entry> <entry> <para> The Xkb extension has not been properly initialized @@ -583,7 +609,7 @@ The Xkb extension has not been properly initialized </entry> </row> <row> - <entry>BadKeyboard</entry> + <entry><errorname>BadKeyboard</errorname></entry> <entry> <para> The device specified was not a valid core or input extension device @@ -591,7 +617,7 @@ The device specified was not a valid core or input extension device </entry> </row> <row> - <entry>BadImplementation</entry> + <entry><errorname>BadImplementation</errorname></entry> <entry> <para> Invalid reply from server @@ -599,7 +625,7 @@ Invalid reply from server </entry> </row> <row> - <entry>BadAlloc</entry> + <entry><errorname>BadAlloc</errorname></entry> <entry> <para> Unable to allocate storage @@ -607,7 +633,7 @@ Unable to allocate storage </entry> </row> <row> - <entry>BadMatch</entry> + <entry><errorname>BadMatch</errorname></entry> <entry> <para> A compatible version of Xkb was not available in the server or an argument has @@ -616,7 +642,7 @@ correct type and range, but is otherwise invalid </entry> </row> <row> - <entry>BadValue</entry> + <entry><errorname>BadValue</errorname></entry> <entry> <para> An argument is out of range @@ -624,16 +650,16 @@ An argument is out of range </entry> </row> <row> - <entry>BadAtom</entry> + <entry><errorname>BadAtom</errorname></entry> <entry> <para> -A name is neither a valid Atom or <emphasis> -None</emphasis> +A name is neither a valid Atom or +<symbol>None</symbol> </para> </entry> </row> <row> - <entry>BadDevice</entry> + <entry><errorname>BadDevice</errorname></entry> <entry> <para> Device, Feedback Class, or Feedback ID invalid @@ -644,29 +670,33 @@ Device, Feedback Class, or Feedback ID invalid </tgroup> </table> -<para> -The Xkb extension adds a single protocol error, <emphasis> -BadKeyboard</emphasis> -, to the core protocol error set. This error code will be reported as the -<emphasis> -error_rtrn</emphasis> - when <emphasis> -XkbQueryExtension</emphasis> - is called. When a <emphasis> -BadKeyboard</emphasis> - error is reported in an <emphasis> -XErrorEvent</emphasis> -, additional information is reported in the <emphasis> -resource_id</emphasis> - field. The most significant byte of the <emphasis> -resource_id</emphasis> - is a further refinement of the error cause, as defined in Table 2.2. The least +<para id='BadKeyboard'> +<indexterm zone="BadKeyboard"><primary>errors</primary> +<secondary><errorname>BadKeyboard</errorname></secondary></indexterm> +<indexterm zone="BadKeyboard"> +<primary><errorname>BadKeyboard</errorname></primary></indexterm> +The Xkb extension adds a single protocol error, +<errorname>BadKeyboard</errorname>, +to the core protocol error set. This error code will be reported as the +<parameter>error_rtrn</parameter> +when +<function>XkbQueryExtension</function> +is called. When a +<errorname>BadKeyboard</errorname> +error is reported in an +<structname>XErrorEvent</structname>, +additional information is reported in the +<structfield>resourceid</structfield> +field. The most significant byte of the +<structfield>resource_id</structfield> +is a further refinement of the error cause, as defined in +<link linkend="table2.2">Table 2.2</link>. The least significant byte will contain the device, class, or feedback ID as indicated in the table. </para> -<table frame='topbot'> -<title>BadKeyboard Protocol Error resource_id Values</title> +<table id='table2.2' frame='topbot'> +<title><errorname>BadKeyboard</errorname> Protocol Error resource_id Values</title> <?dbfo keep-together="always" ?> <tgroup cols='4' align='left' colsep='0' rowsep='0'> <colspec colname='c1' colwidth='2.0*'/> @@ -683,7 +713,7 @@ the table. </thead> <tbody> <row> - <entry>XkbErr_BadDevice</entry> + <entry><errorname>XkbErr_BadDevice</errorname></entry> <entry>0xff</entry> <entry> <para> @@ -693,7 +723,7 @@ device not found <entry>device ID</entry> </row> <row> - <entry>XkbErr_BadClass</entry> + <entry><errorname>XkbErr_BadClass</errorname></entry> <entry>0xfe</entry> <entry> <para> @@ -703,7 +733,7 @@ device found, but it is of the wrong class <entry>class ID</entry> </row> <row> - <entry>XkbErr_BadId</entry> + <entry><errorname>XkbErr_BadId</errorname></entry> <entry>0xfd</entry> <entry> <para> @@ -722,90 +752,85 @@ indicated ID <title>Display and Device Specifications in Function Calls</title> <para> Where a connection to the server is passed as an argument (Display*) and an -<emphasis> -XkbDescPtr</emphasis> - is also passed as an argument, the Display* argument must match the <emphasis> -dpy</emphasis> - field of the <emphasis> -XkbDescRec</emphasis> - pointed to by the <emphasis> -XkbDescPtr</emphasis> - argument, or else the <emphasis> -dpy</emphasis> - field of the <emphasis> -XkbDescRec</emphasis> - must be <emphasis> -NULL</emphasis> -. If they don’t match or the <emphasis> -dpy</emphasis> - field is not <emphasis> -NULL</emphasis> -, a <emphasis> -BadMatch</emphasis> - error is returned (either in the return value or a backfilled <emphasis> -Status</emphasis> - variable). Upon successful return, the <emphasis> -dpy</emphasis> - field of the <emphasis> -XkbDescRec</emphasis> - always contains the Display* value passed in. +<type>XkbDescPtr</type> +is also passed as an argument, the Display* argument must match the +<structfield>dpy</structfield> +field of the +<structname>XkbDescRec</structname> +pointed to by the +<type>XkbDescPtr</type> +argument, or else the +<structfield>dpy</structfield> +field of the +<structname>XkbDescRec</structname> +must be +<symbol>NULL</symbol>. +If they don’t match or the +<structfield>dpy</structfield> +field is not +<symbol>NULL</symbol>, +a +<errorname>BadMatch</errorname> +error is returned (either in the return value or a backfilled +<type>Status</type> +variable). Upon successful return, the +<structfield>dpy</structfield> +field of the +<structname>XkbDescRec</structname> +always contains the Display* value passed in. </para> <para> The Xkb extension can communicate with the X input extension if it is present. Consequently, there can potentially be more than one input device connected to the server. Most Xkb library calls that require communicating with the server -involve both a server connection (Display * <emphasis> -dpy</emphasis> -) and a device identifier (unsigned int <emphasis> -device_spec</emphasis> -). In some cases, the device identifier is implicit and is taken as the -<emphasis> -device_spec</emphasis> - field of an <emphasis> -XkbDescRec</emphasis> - structure passed as an argument. -</para> - -<para> -The device identifier can specify any X input extension device with a <emphasis> -KeyClass</emphasis> - component, or it can specify the constant, <emphasis> -XkbUseCoreKbd</emphasis> -. The use of <emphasis> -XkbUseCoreKbd</emphasis> - allows applications to indicate the core keyboard without having to determine +involve both a server connection (Display * +<structfield>dpy</structfield>) +and a device identifier (unsigned int +<structfield>device_spec</structfield>). +In some cases, the device identifier is implicit and is taken as the +<structfield>device_spec</structfield> +field of an +<structname>XkbDescRec</structname> +structure passed as an argument. +</para> + +<para id='XkbUseCoreKbd'> +<indexterm significance="preferred" zone="XkbUseCoreKbd"><primary><symbol>XkbUseCoreKbd</symbol></primary></indexterm> +The device identifier can specify any X input extension device with a +<symbol>KeyClass</symbol> +component, or it can specify the constant, +<symbol>XkbUseCoreKbd</symbol>. +The use of +<symbol>XkbUseCoreKbd</symbol> +allows applications to indicate the core keyboard without having to determine its device identifier. </para> <para> -Where an Xkb device identifier is passed as an argument and an <emphasis> -XkbDescPtr</emphasis> - is also passed as an argument, if either the argument or the <emphasis> -XkbDescRec</emphasis> - <emphasis> -device_spec</emphasis> - field is <emphasis> -XkbUseCoreKbd</emphasis> -, and if the function returns successfully, the <emphasis> -XkbDescPtr</emphasis> - <emphasis> -device_spec</emphasis> - field will have been converted from <emphasis> -XkbUseCoreKbd</emphasis> - to a real Xkb device ID. If the function does not complete successfully, the -<emphasis> -device_spec</emphasis> - field remains unchanged. Subsequently, the device id argument must match the -<emphasis> -device_spec</emphasis> - field of the <emphasis> -XkbDescPtr</emphasis> - argument. If they don’t match, a <emphasis> -BadMatch</emphasis> - error is returned (either in the return value or a backfilled <emphasis> -Status</emphasis> - variable). +Where an Xkb device identifier is passed as an argument and an +<type>XkbDescPtr</type> +is also passed as an argument, if either the argument or the +<structname>XkbDescRec</structname> +<structfield>device_spec</structfield> +field is +<symbol>XkbUseCoreKbd</symbol>, +and if the function returns successfully, the +<type>XkbDescPtr</type> +<structfield>device_spec</structfield> +field will have been converted from +<symbol>XkbUseCoreKbd</symbol> +to a real Xkb device ID. If the function does not complete successfully, the +<structfield>device_spec</structfield> +field remains unchanged. Subsequently, the device id argument must match the +<structfield>device_spec</structfield> +field of the +<type>XkbDescPtr</type> +argument. If they don’t match, a +<errorname>BadMatch</errorname> +error is returned (either in the return value or a backfilled +<type>Status</type> +variable). </para> <para> @@ -813,11 +838,10 @@ When the Xkb extension in the server hands an application a device identifier to use for the keyboard, that ID is the input extension identifier for the device if the server supports the X Input Extension. If the server does not support the input extension, the meaning of the identifier is undefined — the -only guarantee is that when you use <emphasis> -XkbUseCoreKbd</emphasis> -, <emphasis> -XkbUseCoreKbd</emphasis> - will work and the identifier returned by the server will refer to the core +only guarantee is that when you use +<symbol>XkbUseCoreKbd</symbol>, +<symbol>XkbUseCoreKbd</symbol> +will work and the identifier returned by the server will refer to the core keyboard device. </para> </sect1> diff --git a/libX11/specs/XKB/ch03.xml b/libX11/specs/XKB/ch03.xml index 06d6d93f0..3aeb81b47 100644 --- a/libX11/specs/XKB/ch03.xml +++ b/libX11/specs/XKB/ch03.xml @@ -1,3 +1,6 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Data_Structures'> <title>Data Structures</title> @@ -73,20 +76,20 @@ values are properly updated for those Xkb structures that have interdependencies. As a general rule, if there is a helper function or macro to edit the data structure, use it. For example, increasing the width of a type requires you to resize every key that uses that type. This is complicated and -ugly, which is why there’s an <emphasis> -XkbResizeKeyType</emphasis> - function. +ugly, which is why there’s an +<function>XkbResizeKeyType</function> +function. </para> <para> Many Xkb data structures have arrays whose size is reported by two fields. The -first field, whose name is usually prefixed by <emphasis> -sz_</emphasis> -, represents the total number of elements that can be stored in the array. The -second field, whose name is usually prefixed by <emphasis> -num_</emphasis> -, specifies the number of elements currently stored there. These arrays +first field, whose name is usually prefixed by +<emphasis>sz_</emphasis>, +represents the total number of elements that can be stored in the array. The +second field, whose name is usually prefixed by +<emphasis>num_</emphasis>, +specifies the number of elements currently stored there. These arrays typically represent data whose total size cannot always be determined when the array is created. In these instances, the usual way to allocate space and add data is as follows: @@ -100,9 +103,9 @@ Call the allocator function with some arbitrary size, as a hint. </listitem> <listitem> <para> -For those arrays that have an <emphasis> -Xkb...Add...</emphasis> - function, call it each time you want to add new data to the array. The +For those arrays that have an +<function>Xkb...Add...</function> +function, call it each time you want to add new data to the array. The function expands the array if necessary. </para> </listitem> @@ -110,33 +113,31 @@ function expands the array if necessary. <para> For example, call: -</para> -<para> +<programlisting> XkbAllocGeomShapes(geom,4) -</para> - -<para> -to say "I’ll need space for four new shapes in this geometry." This makes -sure that <emphasis> -sz_shapes</emphasis> - - <emphasis> -num_shapes</emphasis> - >= 4, and resizes the shapes array if it isn’t. If this function +</programlisting> + +to say <quote>I’ll need space for four new shapes in this geometry.</quote> +This makes sure that +<structfield>sz_shapes</structfield> +− +<structfield>num_shapes</structfield> +>= 4, and resizes the shapes array if it isn’t. If this function succeeds, you are guaranteed to have space for the number of shapes you need. </para> <para> When you call an editing function for a structure, you do not need to check for -space, because the function automatically checks the <emphasis> -sz_</emphasis> - and <emphasis> -num_</emphasis> - fields of the array, resizes the array if necessary, adds the entry to the -array, and then updates the <emphasis> -num_</emphasis> - field. +space, because the function automatically checks the +<emphasis>sz_</emphasis> +and +<emphasis>num_</emphasis> +fields of the array, resizes the array if necessary, adds the entry to the +array, and then updates the +<emphasis>num_</emphasis> +field. </para> @@ -156,9 +157,11 @@ description or even an entire data structure for only minor changes. <para> To help you keep track of the changes you make to a local copy of the keyboard -description, Xkb provides separate special <emphasis> -changes</emphasis> - data structures for each major Xkb data structure. These data structures do +description, Xkb provides separate special +<firstterm>changes</firstterm> +<indexterm significance="preferred" zone="Making_Changes_to_the_Servers_Keyboard_Description"> +<primary>changes data structures</primary></indexterm> +data structures for each major Xkb data structure. These data structures do not contain the actual changed values: they only indicate the changes that have been made to the structures that actually describe the keyboard. </para> @@ -203,21 +206,21 @@ the server. <para> When your client application receives a report from the server indicating the keyboard description has changed, you can determine the set of changes by -passing the event to an Xkb function that "notes" event information in the -corresponding changes data structure. These "note changes" functions are -defined for all major Xkb components, and their names have the form <emphasis> -XkbNote{Component}Changes</emphasis> -, where <emphasis> -Component</emphasis> - is the name of a major Xkb component such as <emphasis> -Map</emphasis> - or <emphasis> -Names</emphasis> -. When you want to copy these changes from the server into a local copy of the -keyboard description, use the corresponding <emphasis> -XkbGet{Component}Changes</emphasis> - function<emphasis> -, </emphasis> +passing the event to an Xkb function that <quote>notes</quote> event +information in the corresponding changes data structure. These +<quote>note changes</quote> functions are +defined for all major Xkb components, and their names have the form +<function>XkbNote<replaceable>{Component}</replaceable>Changes</function>, +where +<replaceable>Component</replaceable> +is the name of a major Xkb component such as +<literal>Map</literal> +or +<literal>Names</literal>. +When you want to copy these changes from the server into a local copy of the +keyboard description, use the corresponding +<function>XkbGet<replaceable>{Component}</replaceable>Changes</function> +function, passing it the changes structure. The function then retrieves only the changed structures from the server and copies the modified pieces into the local keyboard description. @@ -228,20 +231,19 @@ keyboard description. <title>Freeing Data Structures</title> <para> -For the same reasons you should not directly use <emphasis> -malloc</emphasis> - to allocate Xkb data structures, you should not free Xkb data structures or -components directly using <emphasis> -free</emphasis> - or <emphasis> -Xfree</emphasis> -. Xkb provides functions to free the various data structures and their +For the same reasons you should not directly use +<function>malloc</function> +to allocate Xkb data structures, you should not free Xkb data structures or +components directly using +<function>free</function> +or +<function>Xfree</function>. +Xkb provides functions to free the various data structures and their components. Always use the free functions supplied by Xkb. There is no -guarantee that any particular field can be safely freed by <emphasis> -free</emphasis> - or <emphasis> -Xfree</emphasis> -. +guarantee that any particular field can be safely freed by +<function>free</function> +or +<function>Xfree</function>. </para> </sect1> </chapter> diff --git a/libX11/specs/XKB/ch04.xml b/libX11/specs/XKB/ch04.xml index 223b44497..dee00b32f 100644 --- a/libX11/specs/XKB/ch04.xml +++ b/libX11/specs/XKB/ch04.xml @@ -1,5 +1,9 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Xkb_Events'> <title>Xkb Events</title> +<indexterm zone="Xkb_Events"><primary>events</primary></indexterm> <para> The primary way the X server communicates with clients is by sending X events @@ -17,25 +21,24 @@ Xkb keyboard status events are reported to all interested clients, regardless of which window currently has the keyboard focus and regardless of the grab state of the keyboard.<footnote><para>The one exception to this rule is the XkbExtensionDeviceNotify event report that is sent when a client attempts to -use an unsupported feature of an X Input Extension device (see section 21.4). -</para></footnote> <!-- xref --> +use an unsupported feature of an X Input Extension device (see <link linkend="Setting_Xkb_Features_for_Non_KeyClass_Input_Extension_Devices">section 21.4</link>). +</para></footnote> </para> <para> The X server reports the events defined by the Xkb extension to your client application only if you have requested them. You may request Xkb events by -calling either <emphasis> -XkbSelectEvents</emphasis> - or <emphasis> -XkbSelectEventDetails</emphasis> -. <emphasis> -XkbSelectEvents</emphasis> - requests Xkb events by their event type and causes them to be reported to your +calling either +<function>XkbSelectEvents</function> +or +<function>XkbSelectEventDetails</function>. +<function>XkbSelectEvents</function> +requests Xkb events by their event type and causes them to be reported to your client application under all circumstances. You can specify a finer granularity -for event reporting by using <emphasis> -XkbSelectEventDetails</emphasis> -; in this case events are reported only when the specific detail conditions you +for event reporting by using +<function>XkbSelectEventDetails</function>; +in this case events are reported only when the specific detail conditions you specify have been met. </para> @@ -45,220 +48,109 @@ specify have been met. <para> The Xkb Extension adds new event types to the X protocol definition. An Xkb event type is defined by two fields in the X event data structure. One is the -<emphasis> -type</emphasis> - field, containing the <emphasis> -base event code.</emphasis> - This base event code is a value the X server assigns to each X extension at -runtime and thatidentifies the extension that generated the event; thus, the -event code in the <emphasis> -type</emphasis> - field identifies the event as an Xkb extension event, rather than an event +<structfield>type</structfield> +field, containing the +<emphasis>base event code</emphasis>. +This base event code is a value the X server assigns to each X extension at +runtime and that identifies the extension that generated the event; thus, the +event code in the +<structfield>type</structfield> +field identifies the event as an Xkb extension event, rather than an event from another extension or a core X protocol event. You can obtain the base -event code via a call to <emphasis> -XkbQueryExtension</emphasis> - or <emphasis> -XkbOpenDisplay</emphasis> -. The second field is the Xkb event type, which contains a value uniquely +event code via a call to +<function>XkbQueryExtension</function> +or +<function>XkbOpenDisplay</function>. +The second field is the Xkb event type, which contains a value uniquely identifying each different Xkb event type. Possible values are defined by -constants declared in the header file <X11/extensions/Xkb.h>. +constants declared in the header file +<filename class="headerfile"><X11/extensions/Xkb.h></filename>. </para> <para> -Table 4.1 lists the categories of events defined by Xkb and their associated -event types, as defined in <emphasis> -Xkb.h</emphasis> -. Each event is described in more detail in the section referenced for that +<link linkend="table4.1">Table 4.1</link> +lists the categories of events defined by Xkb and their associated +event types, as defined in +<filename class="headerfile">Xkb.h</filename>. +Each event is described in more detail in the section referenced for that event. </para> -<table frame='topbot'> +<table id='table4.1' frame='topbot'> <title>Xkb Event Types</title> <?dbfo keep-together="always" ?> -<tgroup cols='4' align='left' colsep='0' rowsep='0'> +<tgroup cols='3' align='left' colsep='0' rowsep='0'> <colspec colname='c1' colwidth='3.0*'/> <colspec colname='c2' colwidth='4.0*'/> <colspec colname='c3' colwidth='1.0*'/> -<colspec colname='c4' colwidth='1.0*'/> <thead> <row rowsep='1'> <entry>Event Type</entry> <entry>Conditions Generating Event</entry> <entry>Section</entry> - <entry>Page</entry> </row> </thead> <tbody> <row> - <entry> - <para><emphasis>XkbNewKeyboardNotify</emphasis></para> - </entry> - <entry> - <para>Keyboard geometry; keycode range change</para> - </entry> - <entry> - <para>19</para> - </entry> - <entry> - <para>187</para> - </entry> + <entry><symbol>XkbNewKeyboardNotify</symbol></entry> + <entry>Keyboard geometry; keycode range change</entry> + <entry><link linkend="Replacing_a_Keyboard_On_the_Fly">19</link></entry> </row> <row> - <entry> - <para> - <emphasis>XkbMapNotify</emphasis> - </para> - </entry> - <entry> - <para>Keyboard mapping change</para> - </entry> - <entry> - <para>14.4</para> - </entry> - <entry> - <para>122</para> - </entry> + <entry><symbol>XkbMapNotify</symbol></entry> + <entry>Keyboard mapping change</entry> + <entry><link linkend="Tracking_Changes_to_Map_Components">14.4</link></entry> </row> <row> - <entry> - <para><emphasis>XkbStateNotify</emphasis></para> - </entry> - <entry> - <para>Keyboard state change</para> - </entry> - <entry> - <para>5.4</para> - </entry> - <entry> - <para>25</para> - </entry> + <entry><symbol>XkbStateNotify</symbol></entry> + <entry>Keyboard state change</entry> + <entry><link linkend="Tracking_Keyboard_State">5.4</link></entry> </row> <row> - <entry> - <para><emphasis>XkbControlsNotify</emphasis></para> - </entry> - <entry> - <para>Keyboard controls state change</para> - </entry> - <entry> - <para>10.11</para> - </entry> - <entry> - <para>79</para> - </entry> + <entry><symbol>XkbControlsNotify</symbol></entry> + <entry>Keyboard controls state change</entry> + <entry><link linkend="Tracking_Changes_to_Keyboard_Controls">10.11</link></entry> </row> <row> - <entry> - <para><emphasis>XkbIndicatorStateNotify</emphasis></para> - </entry> - <entry> - <para>Keyboard indicators state change</para> - </entry> - <entry> - <para>8.5</para> - </entry> - <entry> - <para>45</para> - </entry> + <entry><symbol>XkbIndicatorStateNotify</symbol></entry> + <entry>Keyboard indicators state change</entry> + <entry><link linkend="Tracking_Changes_to_Indicator_State_or_Map">8.5</link></entry> </row> <row> - <entry> - <para><emphasis>XkbIndicatorMapNotify</emphasis></para> - </entry> - <entry> - <para>Keyboard indicators map change</para> - </entry> - <entry> - <para>8.5</para> - </entry> - <entry> - <para>45</para> - </entry> + <entry><symbol>XkbIndicatorMapNotify</symbol></entry> + <entry>Keyboard indicators map change</entry> + <entry><link linkend="Tracking_Changes_to_Indicator_State_or_Map">8.5</link></entry> </row> <row> - <entry> - <para><emphasis>XkbNamesNotify</emphasis></para> - </entry> - <entry> - <para>Keyboard name change</para> - </entry> - <entry> - <para>18.5</para> - </entry> - <entry> - <para>185</para> - </entry> + <entry><symbol>XkbNamesNotify</symbol></entry> + <entry>Keyboard name change</entry> + <entry><link linkend="Tracking_Name_Changes">18.5</link></entry> </row> <row> - <entry> - <para><emphasis>XkbCompatMapNotify</emphasis></para> - </entry> - <entry> - <para>Keyboard compatibility map change</para> - </entry> - <entry> - <para>17.5</para> - </entry> - <entry> - <para>178</para> - </entry> + <entry><symbol>XkbCompatMapNotify</symbol></entry> + <entry>Keyboard compatibility map change</entry> + <entry><link linkend="Tracking_Changes_to_the_Compatibility_Map">17.5</link></entry> </row> <row> - <entry> - <para><emphasis>XkbBellNotify</emphasis></para> - </entry> - <entry> - <para>Keyboard bell generated</para> - </entry> - <entry> - <para>9.4</para> - </entry> - <entry> - <para>52</para> - </entry> + <entry><symbol>XkbBellNotify</symbol></entry> + <entry>Keyboard bell generated</entry> + <entry><link linkend="Detecting_Bells">9.4</link></entry> </row> <row> - <entry> - <para><emphasis>XkbActionMessage</emphasis></para> - </entry> - <entry> - <para>Keyboard action message</para> - </entry> - <entry> - <para>16.1.11</para> - </entry> - <entry> - <para>155</para> - </entry> + <entry><symbol>XkbActionMessage</symbol></entry> + <entry>Keyboard action message</entry> + <entry><link linkend="Actions_for_Generating_Messages">16.1.11</link></entry> </row> <row> - <entry> - <para><emphasis>XkbAccessXNotify</emphasis></para> - </entry> - <entry> - <para>AccessX state change</para> - </entry> - <entry> - <para>10.6.4</para> - </entry> - <entry> - <para>65</para> - </entry> + <entry><symbol>XkbAccessXNotify</symbol></entry> + <entry>AccessX state change</entry> + <entry><link linkend="AccessXNotify_Events">10.6.4</link></entry> </row> <row> - <entry> - <para><emphasis>XkbExtensionDeviceNotify</emphasis></para> - </entry> - <entry> - <para>Extension device change</para> - </entry> - <entry> - <para>21.6</para> - </entry> - <entry> - <para>207</para> - </entry> + <entry><symbol>XkbExtensionDeviceNotify</symbol></entry> + <entry>Extension device change</entry> + <entry><link linkend="Tracking_Changes_to_Extension_Devices">21.6</link></entry> </row> </tbody> </tgroup> @@ -268,63 +160,61 @@ event. <sect1 id='Xkb_Event_Data_Structures'> <title>Xkb Event Data Structures</title> -<para> +<para id='XkbAnyEvent'> +<indexterm significance="preferred" zone="Xkb_Event_Data_Structures"> +<primary>events</primary><secondary><structname>XkbAnyEvent</structname></secondary></indexterm> +<indexterm significance="preferred" zone="Xkb_Event_Data_Structures"> +<primary><structname>XkbAnyEvent</structname></primary></indexterm> Xkb reports each event it generates in a unique structure holding the data values needed to describe the conditions the event is reporting. However, all Xkb events have certain things in common. These common features are contained in the same fields at the beginning of all Xkb event structures and are -described in the <emphasis> -XkbAnyEvent</emphasis> - structure: -</para> +described in the +<structname>XkbAnyEvent</structname> +structure: -<para><programlisting> +<programlisting> typedef struct { - int type; /* Xkb extension base event code */ - unsigned long serial; /* X server serial number for event */ - Bool send_event; /* <emphasis> True</emphasis> => synthetically generated */ - Display * display; /* server connection where event -generated */ - Time time; /* server time when event generated */ - int xkb_type; /* Xkb minor event code */ - unsigned int device; /* Xkb device ID, will not be - <emphasis>XkbUseCoreKbd</emphasis> */ -} <emphasis>XkbAnyEvent</emphasis> -; + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* <symbol>True</symbol> ⇒ synthetically generated */ + Display * display; /* server connection where event generated */ + Time time; /* server time when event generated */ + int xkb_type; /* Xkb minor event code */ + unsigned int device; /* Xkb device ID, will not be <symbol>XkbUseCoreKbd</symbol> */ +} <structname>XkbAnyEvent</structname>; </programlisting></para> <para> -For any Xkb event, the <emphasis> -type</emphasis> - field is set to the base event code for the Xkb extension, assigned by the -server to all Xkb extension events. The <emphasis> -serial</emphasis> -, <emphasis> -send_event</emphasis> -, and <emphasis> -display</emphasis> - fields are as described for all X11 events. The <emphasis> -time</emphasis> - field is set to the time when the event was generated and is expressed in -milliseconds. The <emphasis> -xkb_type</emphasis> - field contains the minor extension event code, which is the extension event -type, and is one of the values listed in Table 4.1. The <emphasis> -device</emphasis> - field contains the keyboard device identifier associated with the event. This -is never <emphasis> -XkbUseCoreKbd</emphasis> -, even if the request that generated the event specified a device of <emphasis> -XkbUseCoreKbd</emphasis> -. If the request that generated the event specified <emphasis> -XkbUseCoreKbd</emphasis> -, <emphasis> -device</emphasis> - contains a value assigned by the server to specify the core keyboard. If the +For any Xkb event, the +<structfield>type</structfield> +field is set to the base event code for the Xkb extension, assigned by the +server to all Xkb extension events. The +<structfield>serial</structfield>, +<structfield>send_event</structfield>, +and +<structfield>display</structfield> +fields are as described for all X11 events. The +<structfield>time</structfield> +field is set to the time when the event was generated and is expressed in +milliseconds. The +<structfield>xkb_type</structfield> +field contains the minor extension event code, which is the extension event +type, and is one of the values listed in +<link linkend="table4.1">Table 4.1</link>. The +<structfield>device</structfield> +field contains the keyboard device identifier associated with the event. This +is never +<symbol>XkbUseCoreKbd</symbol>, +even if the request that generated the event specified a device of +<symbol>XkbUseCoreKbd</symbol>. +If the request that generated the event specified +<symbol>XkbUseCoreKbd</symbol>, +<structfield>device</structfield> +contains a value assigned by the server to specify the core keyboard. If the request that generated the event specified an X input extension device, -<emphasis> -device</emphasis> - contains that same identifier. +<structfield>device</structfield> +contains that same identifier. </para> @@ -337,6 +227,10 @@ chapters where the events are described. </sect1> <sect1 id='Selecting_Xkb_Events'> <title>Selecting Xkb Events</title> +<indexterm significance="preferred" zone="Selecting_Xkb_Events"> +<primary>events</primary><secondary>mask</secondary></indexterm> +<indexterm significance="preferred" zone="Selecting_Xkb_Events"> +<primary>mask</primary><secondary>event</secondary></indexterm> <para> Xkb events are selected using an event mask, much the same as normal core X @@ -363,18 +257,16 @@ same granularity. <para> Xkb provides two functions to select and deselect delivery of Xkb events. -<emphasis> -XkbSelectEvents</emphasis> - allows you to select or deselect delivery of more than one Xkb event type at -once. Events selected using <emphasis> -XkbSelectEvents</emphasis> - are delivered to your program under all circumstances that generate the +<function>XkbSelectEvents</function> +allows you to select or deselect delivery of more than one Xkb event type at +once. Events selected using +<function>XkbSelectEvents</function> +are delivered to your program under all circumstances that generate the events. To restrict delivery of an event to a subset of the conditions under -which it occurs, use <emphasis> -XkbSelectEventDetails</emphasis> -. <emphasis> -XkbSelectEventDetails</emphasis> - only allows you to change the selection conditions for a single event at a +which it occurs, use +<function>XkbSelectEventDetails</function>. +<function>XkbSelectEventDetails</function> +only allows you to change the selection conditions for a single event at a time, but it provides a means of fine-tuning the conditions under which the event is delivered. </para> @@ -382,259 +274,269 @@ event is delivered. <para> To select and / or deselect for delivery of one or more Xkb events and have -them delivered under all conditions, use <emphasis> -XkbSelectEvents</emphasis> -. +them delivered under all conditions, use +<function>XkbSelectEvents</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSelectEvents</emphasis> -(<emphasis> -display, device_spec, bits_to_change, values_for_bits</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -display</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned long int <emphasis> -bits_to_change; </emphasis> -/* determines events to be selected / deselected */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned long int <emphasis> -values_for_bits</emphasis> -; /* 1=>select, 0->deselect; for events in <emphasis> -bits_to_change</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbSelectEvents"><primary><function>XkbSelectEvents</function></primary></indexterm> +<funcsynopsis id="XkbSelectEvents"> + <funcprototype> + <funcdef>Bool <function>XkbSelectEvents</function></funcdef> +<!-- ( +<parameter>display, device_spec, bits_to_change, values_for_bits</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned long int <parameter>bits_to_change</parameter></paramdef> + <paramdef>unsigned long int <parameter>values_for_bits</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>bits_to_change</parameter> + </term> + <listitem> + <para> + determines events to be selected / deselected + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>values_for_bits</parameter> + </term> + <listitem> + <para> + 1⇒select, 0→deselect; for events in <parameter>bits_to_change</parameter> + </para> + </listitem> + </varlistentry> +</variablelist> <para> This request changes the Xkb event selection mask for the keyboard specified by -<emphasis> -device_spec</emphasis> -. +<parameter>device_spec</parameter>. </para> <para> -Each Xkb event that can be selected is represented by a bit in the <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> - masks. Only the event selection bits specified by the <emphasis> -bits_to_change</emphasis> - parameter are affected; any unspecified bits are left unchanged. To turn on -event selection for an event, set the bit for the event in the <emphasis> -bits_to_change</emphasis> - parameter and set the corresponding bit in the <emphasis> -values_for_bits</emphasis> - parameter. To turn off event selection for an event, set the bit for the event -in the <emphasis> -bits_to_change</emphasis> - parameter and do not set the corresponding bit in the <emphasis> -values_for_bits</emphasis> - parameter. The valid values for both of these parameters are an inclusive -bitwise OR of the masks shown in Table 4.2. There is no interface to return +Each Xkb event that can be selected is represented by a bit in the +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +masks. Only the event selection bits specified by the +<parameter>bits_to_change</parameter> +parameter are affected; any unspecified bits are left unchanged. To turn on +event selection for an event, set the bit for the event in the +<parameter>bits_to_change</parameter> +parameter and set the corresponding bit in the +<parameter>values_for_bits</parameter> +parameter. To turn off event selection for an event, set the bit for the event +in the +<parameter>bits_to_change</parameter> +parameter and do not set the corresponding bit in the +<parameter>values_for_bits</parameter> +parameter. The valid values for both of these parameters are an inclusive +bitwise OR of the masks shown in <link linkend="table4.2">Table 4.2</link>. +There is no interface to return your client’s current event selection mask. Clients cannot set other clients’ event selection masks. </para> <para> -If a bit is not set in the <emphasis> -bits_to_change</emphasis> - parameter, but the corresponding bit is set in the <emphasis> -values_for_bits</emphasis> - parameter, a <emphasis> -BadMatch</emphasis> - protocol error results. If an undefined bit is set in either the <emphasis> -bits_to_change</emphasis> - or the <emphasis> -values_for_bits</emphasis> - parameter, a <emphasis> -BadValue</emphasis> - protocol error results. +If a bit is not set in the +<parameter>bits_to_change</parameter> +parameter, but the corresponding bit is set in the +<parameter>values_for_bits</parameter> +parameter, a +<errorname>BadMatch</errorname> +protocol error results. If an undefined bit is set in either the +<parameter>bits_to_change</parameter> +or the +<parameter>values_for_bits</parameter> +parameter, a +<errorname>BadValue</errorname> +protocol error results. </para> <para> All event selection bits are initially zero for clients using the Xkb extension. Once you set some bits, they remain set for your client until you -clear them via another call to <emphasis> -XkbSelectEvents</emphasis> -. +clear them via another call to +<function>XkbSelectEvents</function>. </para> <para> -<emphasis> -XkbSelectEvents</emphasis> - returns <emphasis> -False</emphasis> - if the Xkb extension has not been initilialized and <emphasis> -True</emphasis> - otherwise. +<function>XkbSelectEvents</function> +returns +<symbol>False</symbol> +if the Xkb extension has not been initialized and +<symbol>True</symbol> +otherwise. </para> <para> To select or deselect for a specific Xkb event and optionally place conditions -on when events of that type are reported to your client, use <emphasis> -XkbSelectEventDetails</emphasis> -. This allows you to exercise a finer granularity of control over delivery of -Xkb events with <emphasis> -XkbSelectEvents</emphasis> -. +on when events of that type are reported to your client, use +<function>XkbSelectEventDetails</function>. +This allows you to exercise a finer granularity of control over delivery of +Xkb events with +<function>XkbSelectEvents</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSelectEventDetails</emphasis> -(<emphasis> -display, device_spec, event_type, bits_to_change</emphasis> -, <emphasis> -values_for_bits</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -display</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -event_type</emphasis> -; /* Xkb event type of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned long int <emphasis> -bits_to_change</emphasis> -; /* event selection details */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned long int <emphasis> -values_for_bits</emphasis> -; /* values for bits selected by <emphasis> -bits_to_change</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbSelectEventDetails"><primary><function>XkbSelectEventDetails</function></primary></indexterm> +<funcsynopsis id="XkbSelectEventDetails"> + <funcprototype> + <funcdef>Bool <function>XkbSelectEventDetails</function></funcdef> +<!-- ( +<parameter>display, device_spec, event_type, bits_to_change</parameter>, +<parameter>values_for_bits</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>event_type</parameter></paramdef> + <paramdef>unsigned long int <parameter>bits_to_change</parameter></paramdef> + <paramdef>unsigned long int <parameter>values_for_bits</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>event_type</parameter> + </term> + <listitem> + <para> + Xkb event type of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>bits_to_change</parameter> + </term> + <listitem> + <para> + event selection details + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>values_for_bits</parameter> + </term> + <listitem> + <para> + values for bits selected by <parameter>bits_to_change</parameter> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -While <emphasis> -XkbSelectEvents</emphasis> - allows multiple events to be selected, <emphasis> -XkbSelectEventDetails</emphasis> - changes the selection criteria for a single type of Xkb event. The -interpretation of the <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> - masks depends on the event type in question. +While +<function>XkbSelectEvents</function> +allows multiple events to be selected, +<function>XkbSelectEventDetails</function> +changes the selection criteria for a single type of Xkb event. The +interpretation of the +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +masks depends on the event type in question. </para> <para> -<emphasis> -XkbSelectEventDetails</emphasis> - changes the Xkb event selection mask for the keyboard specified by <emphasis> -device_spec</emphasis> - and the Xkb event specified by <emphasis> -event_type</emphasis> -. To turn on event selection for an event detail, set the bit for the detail in -the <emphasis> -bits_to_change</emphasis> - parameter and set the corresponding bit in the <emphasis> -values_for_bits</emphasis> - parameter. To turn off event detail selection for a detail, set the bit for -the detail in the <emphasis> -bits_to_change</emphasis> - parameter and do not set the corresponding bit in the <emphasis> -values_for_bits</emphasis> - parameter. +<function>XkbSelectEventDetails</function> +changes the Xkb event selection mask for the keyboard specified by +<parameter>device_spec</parameter> +and the Xkb event specified by +<parameter>event_type</parameter>. +To turn on event selection for an event detail, set the bit for the detail in +the +<parameter>bits_to_change</parameter> +parameter and set the corresponding bit in the +<parameter>values_for_bits</parameter> +parameter. To turn off event detail selection for a detail, set the bit for +the detail in the +<parameter>bits_to_change</parameter> +parameter and do not set the corresponding bit in the +<parameter>values_for_bits</parameter> +parameter. </para> <para> -If an invalid event type is specified, a <emphasis> -BadValue</emphasis> - protocol error results. If a bit is not set in the <emphasis> -bits_to_change</emphasis> - parameter, but the corresponding bit is set in the <emphasis> -values_for_bits</emphasis> - parameter, a <emphasis> -BadMatch</emphasis> - protocol error results. If an undefined bit is set in either the <emphasis> -bits_to_change</emphasis> - or the <emphasis> -values_for_bits</emphasis> - parameter, a <emphasis> -BadValue</emphasis> - protocol error results. +If an invalid event type is specified, a +<errorname>BadValue</errorname> +protocol error results. If a bit is not set in the +<parameter>bits_to_change</parameter> +parameter, but the corresponding bit is set in the +<parameter>values_for_bits</parameter> +parameter, a +<errorname>BadMatch</errorname> +protocol error results. If an undefined bit is set in either the +<parameter>bits_to_change</parameter> +or the +<parameter>values_for_bits</parameter> +parameter, a +<errorname>BadValue</errorname> +protocol error results. </para> <para> For each type of Xkb event, the legal event details that you can specify in the -<emphasis> -XkbSelectEventDetails</emphasis> - request are listed in the chapters that describe each event in detail. +<function>XkbSelectEventDetails</function> +request are listed in the chapters that describe each event in detail. </para> @@ -643,23 +545,23 @@ XkbSelectEventDetails</emphasis> <para> The X server reports the events defined by Xkb to your client application only -if you have requested them via a call to <emphasis> -XkbSelectEvents</emphasis> - or <emphasis> -XkbSelectEventDetails</emphasis> -. Specify the event types in which you are interested in a mask, as described -in section 4.3. +if you have requested them via a call to +<function>XkbSelectEvents</function> +or +<function>XkbSelectEventDetails</function>. +Specify the event types in which you are interested in a mask, as described +in <link linkend="Selecting_Xkb_Events">section 4.3</link>. </para> <para> -Table 4.2 lists the event mask constants that can be specified with the <!-- xref --> -<emphasis> -XkbSelectEvents</emphasis> - request and the circumstances in which the mask should be specified. +<link linkend="table4.2">Table 4.2</link> +lists the event mask constants that can be specified with the +<function>XkbSelectEvents</function> +request and the circumstances in which the mask should be specified. </para> -<table frame='topbot'> +<table id='table4.2' frame='topbot'> <title>XkbSelectEvents Mask Constants</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -676,91 +578,91 @@ XkbSelectEvents</emphasis> <tbody> <row> <entry> -<emphasis>XkbNewKeyboardNotifyMask</emphasis> +<symbol>XkbNewKeyboardNotifyMask</symbol> </entry> <entry>(1L<<0)</entry> <entry>Keyboard geometry change</entry> </row> <row> <entry> - <emphasis>XkbMapNotifyMask</emphasis> + <symbol>XkbMapNotifyMask</symbol> </entry> <entry>(1L<<1)</entry> <entry>Keyboard mapping change</entry> </row> <row> <entry> -<para><emphasis>XkbStateNotifyMask</emphasis></para> +<para><symbol>XkbStateNotifyMask</symbol></para> </entry> <entry>(1L<<2)</entry> <entry><para>Keyboard state change</para></entry> </row> <row> <entry> -<para><emphasis>XkbControlsNotifyMask</emphasis></para> +<para><symbol>XkbControlsNotifyMask</symbol></para> </entry> <entry>(1L<<3)</entry> <entry>Keyboard control change</entry> </row> <row> <entry> -<emphasis>XkbIndicatorStateNotifyMask</emphasis> +<symbol>XkbIndicatorStateNotifyMask</symbol> </entry> <entry>(1L<<4)</entry> <entry>Keyboard indicator state change</entry> </row> <row> <entry> -<emphasis>XkbIndicatorMapNotifyMask</emphasis> +<symbol>XkbIndicatorMapNotifyMask</symbol> </entry> <entry>(1L<<5)</entry> <entry>Keyboard indicator map change</entry> </row> <row> <entry> -<emphasis>XkbNamesNotifyMask</emphasis> +<symbol>XkbNamesNotifyMask</symbol> </entry> <entry>(1L<<6)</entry> <entry>Keyboard name change</entry> </row> <row> <entry> -<emphasis>XkbCompatMapNotifyMask</emphasis> +<symbol>XkbCompatMapNotifyMask</symbol> </entry> <entry>(1L<<7)</entry> <entry>Keyboard compat map change</entry> </row> <row> <entry> -<emphasis>XkbBellNotifyMask</emphasis> +<symbol>XkbBellNotifyMask</symbol> </entry> <entry>(1L<<8)</entry> <entry>Bell</entry> </row> <row> <entry> -<emphasis>XkbActionMessageMask</emphasis> +<symbol>XkbActionMessageMask</symbol> </entry> <entry>(1L<<9)</entry> <entry>Action message</entry> </row> <row> <entry> -<emphasis>XkbAccessXNotifyMask</emphasis> +<symbol>XkbAccessXNotifyMask</symbol> </entry> <entry>(1L<<10)</entry> <entry>AccessX features</entry> </row> <row> <entry> -<emphasis>XkbExtensionDeviceNotifyMask</emphasis> +<symbol>XkbExtensionDeviceNotifyMask</symbol> </entry> <entry>(1L<<11)</entry> <entry>Extension device</entry> </row> <row> <entry> -<emphasis>XkbAllEventsMask</emphasis> +<symbol>XkbAllEventsMask</symbol> </entry> <entry>(0xFFF)</entry> <entry>All Xkb events</entry> @@ -773,23 +675,27 @@ XkbSelectEvents</emphasis> </sect1> <sect1 id='Unified_Xkb_Event_Type'> <title>Unified Xkb Event Type</title> +<indexterm significance="preferred" zone="Unified_Xkb_Event_Type"> +<primary>events</primary><secondary><structname>XkbEvent</structname></secondary></indexterm> +<indexterm significance="preferred" zone="Unified_Xkb_Event_Type"> +<primary><structname>XkbEvent</structname></primary></indexterm> <para> -The <emphasis> -XkbEvent</emphasis> - structure is a union of the individual structures declared for each Xkb event -type and for the core protocol <emphasis> -XEvent</emphasis> - type. Given an <emphasis> -XkbEvent</emphasis> - structure, you may use the <emphasis> -type</emphasis> - field to determine if the event is an Xkb event (<emphasis> -type</emphasis> - equals the Xkb base event code; see section 2.4). If the event is an Xkb -event, you may then use the <emphasis> -any.xkb_type</emphasis> - field to determine the type of Xkb event and thereafter access the +The +<structname>XkbEvent</structname> +structure is a union of the individual structures declared for each Xkb event +type and for the core protocol +<structname>XEvent</structname> +type. Given an +<structname>XkbEvent</structname> +structure, you may use the +<structfield>type</structfield> +field to determine if the event is an Xkb event +(<structfield>type</structfield> +equals the Xkb base event code; see <link linkend="Initializing_the_Keyboard_Extension">section 2.4</link>). If the event is an Xkb +event, you may then use the +<structfield>any.xkb_type</structfield> +field to determine the type of Xkb event and thereafter access the event-dependent components using the union member corresponding to the particular Xkb event type. </para> @@ -810,20 +716,20 @@ typedef union _XkbEvent { XkbExtensionDeviceNotifyEvent device; XkbNewKeyboardNotifyEvent new_kbd; XEvent core; -} <emphasis>XkbEvent</emphasis>; +} <structname>XkbEvent</structname>; </programlisting></para> <para> -This unified Xkb event type includes a normal <emphasis> -XEvent</emphasis> - as used by the core protocol, so it is straightforward for applications that +This unified Xkb event type includes a normal +<structname>XEvent</structname> +as used by the core protocol, so it is straightforward for applications that use Xkb events to call the X library event functions without having to cast every reference. For example, to get the next event, you can simply declare a -variable of type <emphasis> -XkbEvent</emphasis> - and call: -</para> +variable of type +<structname>XkbEvent</structname> +and call: -<para>XNextEvent(dpy,&xkbev.core);</para> +<programlisting>XNextEvent(dpy,&xkbev.core);</programlisting> +</para> </sect1> </chapter> diff --git a/libX11/specs/XKB/ch05.xml b/libX11/specs/XKB/ch05.xml index 3a507aa3b..77d1995e0 100644 --- a/libX11/specs/XKB/ch05.xml +++ b/libX11/specs/XKB/ch05.xml @@ -1,16 +1,21 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Keyboard_State'> <title>Keyboard State</title> <para> -Keyboard state encompasses all of the transitory information necessary to map a physical key press or release to an appropriate event. The Xkb keyboard state consists of primitive components and additional derived components that are maintained for efficiency reasons. Figure 5.1 shows the components of Xkb keyboard state and their relationships. +Keyboard state encompasses all of the transitory information necessary to map a physical key press or release to an appropriate event. The Xkb keyboard state consists of primitive components and additional derived components that are maintained for efficiency reasons. <link linkend="figure5.1">Figure 5.1</link> shows the components of Xkb keyboard state and their relationships. </para> -<mediaobject> -<!-- <title>Keyboard State Description</title> --> - <imageobject> <imagedata format="SVG" fileref="XKBlib-2.svg"/> - </imageobject> -<caption>Xkb State</caption> -</mediaobject> +<figure id='figure5.1'> + <title>Xkb State</title> + <mediaobject> + <!-- <title>Keyboard State Description</title> --> + <imageobject> <imagedata format="SVG" fileref="XKBlib-2.svg"/> + </imageobject> + </mediaobject> +</figure> <sect1 id='Keyboard_State_Description'> @@ -47,29 +52,33 @@ The state of the core pointer buttons </listitem> </itemizedlist> -<para> -The <emphasis> -modifiers</emphasis> - are <emphasis> -Shift</emphasis> -, <emphasis> -Lock</emphasis> -, <emphasis> -Control</emphasis> -, and <emphasis> -Mod1</emphasis> --<emphasis> -Mod5</emphasis> -, as defined by the core protocol. A modifier can be thought of as a toggle that is either set or unset. All modifiers are initially unset. When a modifier is locked, it is set and remains set for all future key events, until it is explicitly unset. A latched modifier is set, but automatically unsets after the next key event that does not change the keyboard state. Locked and latched modifier state can be changed by keyboard activity or via Xkb extension library functions. +<para id='modifiers'> +The +<firstterm>modifiers</firstterm> +<indexterm significance="preferred" zone="modifiers"> +<primary>modifiers</primary></indexterm> +are +<symbol>Shift</symbol>, +<symbol>Lock</symbol>, +<symbol>Control</symbol>, +and +<symbol>Mod1</symbol> +– +<symbol>Mod5</symbol>, +as defined by the core protocol. A modifier can be thought of as a toggle that is either set or unset. All modifiers are initially unset. When a modifier is locked, it is set and remains set for all future key events, until it is explicitly unset. A latched modifier is set, but automatically unsets after the next key event that does not change the keyboard state. Locked and latched modifier state can be changed by keyboard activity or via Xkb extension library functions. </para> -<para> -The Xkb extension provides support for <emphasis> -keysym</emphasis> - <emphasis> -groups</emphasis> -, as defined by ISO9995: +<para id='keysym_groups'> +The Xkb extension provides support for +<firstterm>keysym groups</firstterm>, +<indexterm significance="preferred" zone="keysym_groups"> +<primary>keysym groups</primary></indexterm> +<indexterm significance="preferred" zone="keysym_groups"> +<primary>group</primary><secondary>keysym</secondary></indexterm> +<indexterm significance="preferred" zone="keysym_groups"> +<primary>group</primary><secondary>ISO9995</secondary></indexterm> +as defined by ISO9995: </para> @@ -99,22 +108,30 @@ Changing to a different group changes the keyboard state to produce characters f <para> -The <emphasis> -pointer buttons</emphasis> - are <emphasis> -Button1</emphasis> - - <emphasis> -Button5</emphasis> -, as defined by the core protocol. +The +<firstterm>pointer buttons</firstterm> +are +<symbol>Button1</symbol> +– +<symbol>Button5</symbol>, +as defined by the core protocol. </para> -<para> -The <emphasis> -base group</emphasis> - and <emphasis> -base modifiers</emphasis> - represent keys that are physically or logically down. These +<para id='base_group'> +The +<firstterm>base group</firstterm> +<indexterm significance="preferred" zone="base_group"> +<primary>base group</primary></indexterm> +<indexterm significance="preferred" zone="base_group"> +<primary>group</primary><secondary>base</secondary></indexterm> +and +<firstterm>base modifiers</firstterm> +<indexterm significance="preferred" zone="base_group"> +<primary>base modifiers</primary></indexterm> +<indexterm significance="preferred" zone="base_group"> +<primary>modifiers</primary><secondary>base</secondary></indexterm> +represent keys that are physically or logically down. These and the pointer buttons can be changed by keyboard activity and not by Xkb requests. It is possible for a key to be logically down, but not physically down, and neither latched nor locked. @@ -127,17 +144,25 @@ in the X server having filtered the key release, for esoteric reasons. </para> -<para> -The <emphasis> -effective modifiers</emphasis> - are the bitwise union of the locked, latched, and the base modifiers. +<para id='effective_modifiers'> +The +<firstterm>effective modifiers</firstterm> +<indexterm significance="preferred" zone="effective_modifiers"> +<primary>effective modifiers</primary></indexterm> +<indexterm significance="preferred" zone="effective_modifiers"> +<primary>modifiers</primary><secondary>effective</secondary></indexterm> +are the bitwise union of the locked, latched, and the base modifiers. </para> -<para> -The <emphasis> -effective group</emphasis> - is the arithmetic sum of the group indices of the latched group, locked group, and base group, which is then normalized by some function. The result is a meaningful group index. +<para id='effective_group'> +The +<firstterm>effective group</firstterm> +<indexterm significance="preferred" zone="effective_group"> +<primary>effective group</primary></indexterm> +<indexterm significance="preferred" zone="effective_group"> +<primary>group</primary><secondary>effective</secondary></indexterm> +is the arithmetic sum of the group indices of the latched group, locked group, and base group, which is then normalized by some function. The result is a meaningful group index. </para> <simplelist type='vert' columns='1'> @@ -165,19 +190,19 @@ There are two circumstances under which groups are normalized: <orderedlist> <listitem><para> -The global locked or effective group changes. In this case, the changed group is normalized into range according to the settings of the <emphasis> -groups_wrap</emphasis> - field of the <emphasis> -XkbControlsRec</emphasis> - structure for the keyboard (see section 10.7.1). <!-- xref --> +The global locked or effective group changes. In this case, the changed group is normalized into range according to the settings of the +<structfield>groups_wrap</structfield> +field of the +<structname>XkbControlsRec</structname> +structure for the keyboard (see <link linkend="The_GroupsWrap_Control">section 10.7.1</link>). </para></listitem> <listitem><para> -The Xkb library is interpreting an event with an effective group that is legal for the keyboard as a whole, but not for the key in question. In this case, the group to use for this event only is determined using the <emphasis> -group_info</emphasis> - field of the key symbol mapping (<emphasis> -XkbSymMapRec</emphasis> -) for the event key. +The Xkb library is interpreting an event with an effective group that is legal for the keyboard as a whole, but not for the key in question. In this case, the group to use for this event only is determined using the +<structfield>group_info</structfield> +field of the key symbol mapping +(<structname>XkbSymMapRec</structname>) +for the event key. </para></listitem> </orderedlist> @@ -186,12 +211,17 @@ Each nonmodifier key on a keyboard has zero or more symbols, or keysyms, associa </para> -<para> -A client that does not explicitly call Xkb functions, but that otherwise makes use of an X library containing the Xkb extension, will have keyboard state represented in bits 0 - 14 of the state field of events that report modifier and button state. Such a client is said to be <emphasis> -Xkb-capable</emphasis> -. A client that does explicitly call Xkb functions is an <emphasis> -Xkb-aware</emphasis> - client. The Xkb keyboard state includes information derived from the effective state and from two server parameters that can be set through the keyboard extension. The following components of keyboard state pertain to Xkb-capable and Xkb-aware clients: +<para id='Xkb-aware'> +A client that does not explicitly call Xkb functions, but that otherwise makes use of an X library containing the Xkb extension, will have keyboard state represented in bits 0 – 14 of the state field of events that report modifier and button state. Such a client is said to be +<firstterm>Xkb-capable</firstterm>. +<indexterm significance="preferred" zone="Xkb-aware"> +<primary>Xkb-capable client</primary></indexterm> + +A client that does explicitly call Xkb functions is an +<firstterm>Xkb-aware</firstterm> +<indexterm significance="preferred" zone="Xkb-aware"> +<primary>Xkb-aware client</primary></indexterm> +client. The Xkb keyboard state includes information derived from the effective state and from two server parameters that can be set through the keyboard extension. The following components of keyboard state pertain to Xkb-capable and Xkb-aware clients: </para> <itemizedlist> @@ -207,29 +237,33 @@ grab state: grab group and grab modifiers </listitem> </itemizedlist> -<para> -The <emphasis> -lookup modifiers</emphasis> - and <emphasis> -lookup group</emphasis> - are represented in the state field of core X events. The modifier state and keycode of a key event are used to determine the symbols associated with the event. For <emphasis> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events, the lookup modifiers are computed as: +<para id='lookup_state'> +The +<firstterm>lookup modifiers</firstterm> +<indexterm significance="preferred" zone="lookup_state"> +<primary>lookup modifiers</primary></indexterm> +<indexterm significance="preferred" zone="lookup_state"> +<primary>modifiers</primary><secondary>lookup</secondary></indexterm> +and +<firstterm>lookup group</firstterm> +<indexterm significance="preferred" zone="lookup_state"> +<primary>lookup group</primary></indexterm> +<indexterm significance="preferred" zone="lookup_state"> +<primary>group</primary><secondary>lookup</secondary></indexterm> +are represented in the state field of core X events. The modifier state and keycode of a key event are used to determine the symbols associated with the event. For +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events, the lookup modifiers are computed as: + +<literallayout> ((base | latched | locked) & ~<emphasis>server_internal_modifiers</emphasis>)</literallayout> </para> -<literallayout> - ((base | latched | locked) & ~<emphasis> server_internal_modifiers</emphasis>) -</literallayout> - <para> Otherwise the lookup modifiers are computed as: -</para> -<literallayout> -(((base | latched | (locked & ~<emphasis> ignore_locks</emphasis>)) & ~<emphasis> server_internal_modifiers</emphasis>) -</literallayout> +<literallayout> (((base | latched | (locked & ~<emphasis>ignore_locks</emphasis>)) & ~<emphasis>server_internal_modifiers</emphasis>)</literallayout> +</para> <para> The lookup group is the same as the effective group. @@ -237,36 +271,50 @@ The lookup group is the same as the effective group. <para> -When an Xkb-capable or Xkb-aware client wishes to map a keycode to a keysym, it should use the <emphasis> -lookup state</emphasis> - — the lookup group and the lookup modifiers. +When an Xkb-capable or Xkb-aware client wishes to map a keycode to a keysym, it should use the +<firstterm>lookup state</firstterm> +<indexterm significance="preferred" zone="lookup_state"> +<primary>lookup state</primary></indexterm> +<indexterm significance="preferred" zone="lookup_state"> +<primary>state</primary><secondary>lookup</secondary></indexterm> +— the lookup group and the lookup modifiers. </para> -<para> -The <emphasis> -grab state</emphasis> - is the state used when matching events to passive grabs. If the event activates a grab, the <emphasis> -grab modifiers</emphasis> - and <emphasis> -grab group</emphasis> - are represented in the state field of core X events; otherwise, the lookup state is used. The grab modifiers are computed as: +<para id='grab_state'> +The +<firstterm>grab state</firstterm> +<indexterm significance="preferred" zone="grab_state"> +<primary>grab state</primary></indexterm> +<indexterm significance="preferred" zone="grab_state"> +<primary>state</primary><secondary>grab</secondary></indexterm> +is the state used when matching events to passive grabs. If the event activates a grab, the +<firstterm>grab modifiers</firstterm> +<indexterm significance="preferred" zone="grab_state"> +<primary>grab modifiers</primary></indexterm> +<indexterm significance="preferred" zone="grab_state"> +<primary>modifiers</primary><secondary>grab</secondary></indexterm> +and +<firstterm>grab group</firstterm> +<indexterm significance="preferred" zone="grab_state"> +<primary>grab group</primary></indexterm> +<indexterm significance="preferred" zone="grab_state"> +<primary>group</primary><secondary>grab</secondary></indexterm> +are represented in the state field of core X events; otherwise, the lookup state is used. The grab modifiers are computed as: + +<literallayout> (((base | latched | (locked & ~ignore_locks)) & ~server_internal_modifiers)</literallayout> </para> -<literallayout> -(((base | latched | (locked & ~ignore_locks)) & ~server_internal_modifiers) -</literallayout> - <para> -If the server’s <emphasis> -IgnoreGroupLock</emphasis> - control (see section 10.7.3) is not set, the grab group is the same as the effective group. Otherwise, the grab group is computed from the base group and latched group, ignoring the locked group. +If the server’s +<emphasis>IgnoreGroupLock</emphasis> +control (see <link linkend="The_IgnoreGroupLock_Control">section 10.7.3</link>) is not set, the grab group is the same as the effective group. Otherwise, the grab group is computed from the base group and latched group, ignoring the locked group. </para> <para> -The final three components of Xkb state are applicable to clients that are not linked with an Xlib containing the X keyboard extension library and therefore are not aware of the keyboard extension (<emphasis> -Xkb-unaware </emphasis> +The final three components of Xkb state are applicable to clients that are not linked with an Xlib containing the X keyboard extension library and therefore are not aware of the keyboard extension +(<emphasis>Xkb-unaware</emphasis> clients): </para> @@ -300,13 +348,20 @@ The X11 protocol interpretation of modifiers does not include direct support for <sect2 id='Changing_Modifiers'> <title>Changing Modifiers</title> +<indexterm zone="Changing_Modifiers"> +<primary>real modifiers</primary></indexterm> +<indexterm zone="Changing_Modifiers"> +<primary>modifiers</primary><secondary>real</secondary></indexterm> +<indexterm significance="preferred" zone="Changing_Modifiers"> +<primary>mask</primary><secondary>real modifiers</secondary></indexterm> + <para> -The functions in this section that change the use of modifiers use a mask in the parameter <emphasis> -affect</emphasis> -. It is a bitwise inclusive OR of the legal modifier masks: +The functions in this section that change the use of modifiers use a mask in the parameter +<structfield>affect</structfield>. +It is a bitwise inclusive OR of the legal modifier masks: </para> -<table frame='none'> +<table id='table5.1' frame='none'> <title>Real Modifier Masks</title> <?dbfo keep-together="always" ?> <tgroup cols='1' align='left' colsep='0' rowsep='0'> @@ -344,153 +399,165 @@ affect</emphasis> </table> <para> -To lock and unlock any of the eight real keyboard modifiers, use <emphasis> -XkbLockModifiers:</emphasis> +To lock and unlock any of the eight real keyboard modifiers, use +<function>XkbLockModifiers</function>: </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> XkbLockModifiers</emphasis> -(<emphasis> -display, device_spec, affect, values</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -display</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - affect</emphasis> -; /* mask of real modifiers whose lock state is to change */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -values</emphasis> -; /* 1 => lock, 0 => unlock; only for modifiers selected by <emphasis> -affect</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbLockModifiers"><primary><function>XkbLockModifiers</function></primary></indexterm> +<funcsynopsis id="XkbLockModifiers"> + <funcprototype> + <funcdef>Bool <function>XkbLockModifiers</function></funcdef> +<!-- ( +<parameter>display, device_spec, affect, values</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>affect</parameter></paramdef> + <paramdef>unsigned int <parameter>values</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>affect</parameter> + </term> + <listitem> + <para> + mask of real modifiers whose lock state is to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>values</parameter> + </term> + <listitem> + <para> + 1 ⇒ lock, 0 ⇒ unlock; only for modifiers selected by <parameter>affect</parameter> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbLockModifiers</emphasis> - sends a request to the server to lock the real modifiers selected by both <emphasis> -affect</emphasis> - and <emphasis> -values</emphasis> - and to unlock the real modifiers selected by <emphasis> -affect</emphasis> - but not selected by <emphasis> -values</emphasis> -. <emphasis> -XkbLockModifiers</emphasis> - does not wait for a reply from the server. It returns <emphasis> -True</emphasis> - if the request was sent, and <emphasis> -False</emphasis> - otherwise. +<function>XkbLockModifiers</function> +sends a request to the server to lock the real modifiers selected by both +<parameter>affect</parameter> +and +<parameter>values</parameter> +and to unlock the real modifiers selected by +<parameter>affect</parameter> +but not selected by +<parameter>values</parameter>. +<function>XkbLockModifiers</function> +does not wait for a reply from the server. It returns +<symbol>True</symbol> +if the request was sent, and +<symbol>False</symbol> +otherwise. </para> <para> -To latch and unlatch any of the eight real keyboard modifiers, use <emphasis> -XkbLatchModifiers:</emphasis> +To latch and unlatch any of the eight real keyboard modifiers, use +<function>XkbLatchModifiers</function>: </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbLatchModifiers</emphasis> -(d<emphasis> -isplay, device_spec, affect, values</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -display</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - affect</emphasis> -; /* mask of modifiers whose latch state is to change */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis>values</emphasis>; -/* 1 => latch, 0 => unlatch; only for mods selected by <emphasis> -affect</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbLatchModifiers"><primary><function>XkbLatchModifiers</function></primary></indexterm> +<funcsynopsis id="XkbLatchModifiers"> + <funcprototype> + <funcdef>Bool <function>XkbLatchModifiers</function></funcdef> +<!-- ( +<parameter>display, device_spec, affect, values</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>affect</parameter></paramdef> + <paramdef>unsigned int <parameter>values</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>affect</parameter> + </term> + <listitem> + <para> + mask of modifiers whose latch state is to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>values</parameter> + </term> + <listitem> + <para> + 1 ⇒ latch, 0 ⇒ unlatch; only for mods selected by <parameter>affect</parameter> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbLatchModifiers</emphasis> - sends a request to the server to latch the real modifiers selected by both <emphasis> -affect</emphasis> - and <emphasis> -values</emphasis> - and to unlatch the real modifiers selected by <emphasis> -affect</emphasis> - but not selected by <emphasis> -values</emphasis> -. <emphasis> -XkbLatchModifiers</emphasis> - does not wait for a reply from the server. It returns <emphasis> -True</emphasis> - if the request was sent, and <emphasis> -False</emphasis> - otherwise. +<function>XkbLatchModifiers</function> +sends a request to the server to latch the real modifiers selected by both +<parameter>affect</parameter> +and +<parameter>values</parameter> +and to unlatch the real modifiers selected by +<parameter>affect</parameter> +but not selected by +<parameter>values</parameter>. +<function>XkbLatchModifiers</function> +does not wait for a reply from the server. It returns +<symbol>True</symbol> +if the request was sent, and +<symbol>False</symbol> +otherwise. </para> @@ -498,11 +565,16 @@ False</emphasis> <sect2 id='Changing_Groups'> <title>Changing Groups</title> +<indexterm zone="Changing_Groups"> +<primary>keysym groups</primary></indexterm> +<indexterm zone="Changing_Groups"> +<primary>group</primary><secondary>keysym</secondary></indexterm> + <para> Reference the keysym group indices with these symbolic constants: </para> -<table frame='topbot'> +<table id='table5.2' frame='topbot'> <title>Symbolic Group Names</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -514,19 +586,19 @@ Reference the keysym group indices with these symbolic constants: <entry>Value</entry> </row> <row> - <entry>XkbGroup1Index</entry> + <entry><symbol>XkbGroup1Index</symbol></entry> <entry>0</entry> </row> <row> - <entry>XkbGroup2Index</entry> + <entry><symbol>XkbGroup2Index</symbol></entry> <entry>1</entry> </row> <row> - <entry>XkbGroup3Index</entry> + <entry><symbol>XkbGroup3Index</symbol></entry> <entry>2</entry> </row> <row> - <entry>XkbGroup4Index</entry> + <entry><symbol>XkbGroup4Index</symbol></entry> <entry>3</entry> </row> </tbody> @@ -534,119 +606,127 @@ Reference the keysym group indices with these symbolic constants: </table> <para> -To lock the keysym group, use <emphasis> -XkbLockGroup. </emphasis> +To lock the keysym group, use +<function>XkbLockGroup</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbLockGroup</emphasis> -(<emphasis> -display, device_spec, group</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -display</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -group</emphasis> -; /* index of the keysym group to lock */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbLockGroup"><primary><function>XkbLockGroup</function></primary></indexterm> +<funcsynopsis id="XkbLockGroup"> + <funcprototype> + <funcdef>Bool <function>XkbLockGroup</function></funcdef> +<!-- ( +<parameter>display, device_spec, group</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>group</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>group</parameter> + </term> + <listitem> + <para> + index of the keysym group to lock + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbLockGroup</emphasis> - sends a request to the server to lock the specified <emphasis> -group </emphasis> -and does not wait for a reply. It returns <emphasis> -True</emphasis> - if the request was sent and <emphasis> -False</emphasis> - otherwise. +<function>XkbLockGroup</function> +sends a request to the server to lock the specified +<parameter>group</parameter> +and does not wait for a reply. It returns +<symbol>True</symbol> +if the request was sent and +<symbol>False</symbol> +otherwise. </para> <para> -To latch the keysym group, use <emphasis> -XkbLatchGroup.</emphasis> +To latch the keysym group, use +<function>XkbLatchGroup</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbLatchGroup</emphasis> -(<emphasis> -display, device_spec, group</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -display</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - group</emphasis> -; /* index of the keysym group to latch */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbLatchGroup"><primary><function>XkbLatchGroup</function></primary></indexterm> +<funcsynopsis id="XkbLatchGroup"> + <funcprototype> + <funcdef>Bool <function>XkbLatchGroup</function></funcdef> +<!-- ( +<parameter>display, device_spec, group</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>group</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>group</parameter> + </term> + <listitem> + <para> + index of the keysym group to latch + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbLatchGroup</emphasis> - sends a request to the server to latch the specified group and does not wait for a reply. It returns <emphasis> -True</emphasis> - if the request was sent and <emphasis> -False</emphasis> - otherwise. +<function>XkbLatchGroup</function> +sends a request to the server to latch the specified group and does not wait for a reply. It returns +<symbol>True</symbol> +if the request was sent and +<symbol>False</symbol> +otherwise. </para> @@ -655,89 +735,95 @@ False</emphasis> <sect1 id='Determining_Keyboard_State'> <title>Determining Keyboard State</title> +<indexterm significance="preferred" zone="Determining_Keyboard_State"> +<primary><structname>XkbStateRec</structname></primary></indexterm> + <para> -Xkb keyboard state may be represented in an <emphasis> -XkbStateRec</emphasis> - structure: -</para> +Xkb keyboard state may be represented in an +<structname>XkbStateRec</structname> +structure: -<para><programlisting> +<programlisting> typedef struct { - unsigned char group; /* effective group index */ - unsigned char base_group; /* base group index */ - unsigned char latched_group; /* latched group index */ - unsigned char locked_group; /* locked group index */ - unsigned char mods; /* effective modifiers */ - unsigned char base_mods; /* base modifiers */ - unsigned char latched_mods; /* latched modifiers */ - unsigned char locked_mods; /* locked modifiers */ - unsigned char compat_state; /* effective group => modifiers */ - unsigned char grab_mods; /* modifiers used for grabs */ - unsigned char compat_grab_mods; /* mods used for compatibility mode grabs */ - unsigned char lookup_mods; /* modifiers used to lookup symbols */ - unsigned char compat_lookup_mods; /* mods used for compatibility lookup */ - unsigned short ptr_buttons; /* 1 bit => corresponding pointer btn is down */ -} <emphasis> -XkbStateRec</emphasis> -,*XkbStatePtr; + unsigned char group; /* effective group index */ + unsigned char base_group; /* base group index */ + unsigned char latched_group; /* latched group index */ + unsigned char locked_group; /* locked group index */ + unsigned char mods; /* effective modifiers */ + unsigned char base_mods; /* base modifiers */ + unsigned char latched_mods; /* latched modifiers */ + unsigned char locked_mods; /* locked modifiers */ + unsigned char compat_state; /* effective group ⇒ modifiers */ + unsigned char grab_mods; /* modifiers used for grabs */ + unsigned char compat_grab_mods; /* mods used for compatibility + mode grabs */ + unsigned char lookup_mods; /* mods used to lookup symbols */ + unsigned char compat_lookup_mods; /* mods used for compatibility + lookup */ + unsigned short ptr_buttons; /* 1 bit ⇒ corresponding + pointer btn is down */ +} <structname>XkbStateRec</structname>, *XkbStatePtr; </programlisting></para> <para> -To obtain the keyboard state, use <emphasis> -XkbGetState.</emphasis> +To obtain the keyboard state, use +<function>XkbGetState</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetState</emphasis> -(<emphasis> -display</emphasis> -, <emphasis> -device_spec</emphasis> -, <emphasis> -state_return</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -display</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbStatePtr <emphasis> -state_return</emphasis> -; /* backfilled with Xkb state */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbGetState"><primary><function>XkbGetState</function></primary></indexterm> +<funcsynopsis id="XkbGetState"> + <funcprototype> + <funcdef>Status <function>XkbGetState</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec</parameter>, +<parameter>state_return</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>XkbStatePtr <parameter>state_return</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>state_return</parameter> + </term> + <listitem> + <para> + backfilled with Xkb state + </para> + </listitem> + </varlistentry> +</variablelist> <para> -The <emphasis> -XkbGetState </emphasis> -function queries the server for the current keyboard state, waits for a reply, and then backfills <emphasis> -state_return</emphasis> - with the results. +The +<function>XkbGetState</function> +function queries the server for the current keyboard state, waits for a reply, and then backfills +<parameter>state_return</parameter> +with the results. </para> @@ -750,20 +836,27 @@ All group values are expressed as group indices in the range [0..3]. Modifiers a <sect1 id='Tracking_Keyboard_State'> <title>Tracking Keyboard State</title> +<indexterm significance="preferred" zone="Tracking_Keyboard_State"> +<primary>events</primary><secondary><symbol>XkbStateNotify</symbol></secondary></indexterm> +<indexterm significance="preferred" zone="Tracking_Keyboard_State"> +<primary><structname>XkbStateNotifyEvent</structname></primary></indexterm> + <para> -The Xkb extension reports <emphasis> -XkbStateNotify </emphasis> -events to clients wanting notification whenever the Xkb state changes. The changes reported include changes to any aspect of the keyboard state: when a modifier is set or unset, when the current group changes, or when a pointer button is pressed or released. As with all Xkb events, <emphasis> -XkbStateNotify</emphasis> - events are reported to all interested clients without regard to the current keyboard input focus or grab state. +The Xkb extension reports +<symbol>XkbStateNotify</symbol> +events to clients wanting notification whenever the Xkb state changes. The changes reported include changes to any aspect of the keyboard state: when a modifier is set or unset, when the current group changes, or when a pointer button is pressed or released. As with all Xkb events, +<symbol>XkbStateNotify</symbol> +events are reported to all interested clients without regard to the current keyboard input focus or grab state. </para> <para> -There are many different types of Xkb state changes. Xkb defines an event detail mask corresponding to each type of change. The event detail masks are listed in Table 5.3. +There are many different types of Xkb state changes. Xkb defines an event +detail mask corresponding to each type of change. The event detail masks are +listed in <link linkend="table5.3">Table 5.3</link>. </para> -<table frame='topbot'> +<table id='table5.3' frame='topbot'> <title>XkbStateNotify Event Detail Masks</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -777,63 +870,63 @@ There are many different types of Xkb state changes. Xkb defines an event detail </thead> <tbody> <row> - <entry>XkbModifierStateMask</entry> + <entry><symbol>XkbModifierStateMask</symbol></entry> <entry>(1L << 0)</entry> </row> <row> - <entry>XkbModifierBaseMask</entry> + <entry><symbol>XkbModifierBaseMask</symbol></entry> <entry>(1L << 1)</entry> </row> <row> - <entry>XkbModifierLatchMask</entry> + <entry><symbol>XkbModifierLatchMask</symbol></entry> <entry>(1L << 2)</entry> </row> <row> - <entry>XkbModifierLockMask</entry> + <entry><symbol>XkbModifierLockMask</symbol></entry> <entry>(1L << 3)</entry> </row> <row> - <entry>XkbGroupStateMask</entry> + <entry><symbol>XkbGroupStateMask</symbol></entry> <entry>(1L << 4)</entry> </row> <row> - <entry>XkbGroupBaseMask</entry> + <entry><symbol>XkbGroupBaseMask</symbol></entry> <entry>(1L << 5)</entry> </row> <row> - <entry>XkbGroupLatchMask</entry> + <entry><symbol>XkbGroupLatchMask</symbol></entry> <entry>(1L << 6)</entry> </row> <row> - <entry>XkbGroupLockMask</entry> + <entry><symbol>XkbGroupLockMask</symbol></entry> <entry>(1L << 7)</entry> </row> <row> - <entry>XkbCompatStateMask</entry> + <entry><symbol>XkbCompatStateMask</symbol></entry> <entry>(1L << 8)</entry> </row> <row> - <entry>XkbGrabModsMask</entry> + <entry><symbol>XkbGrabModsMask</symbol></entry> <entry>(1L << 9)</entry> </row> <row> - <entry>XkbCompatGrabModsMask</entry> + <entry><symbol>XkbCompatGrabModsMask</symbol></entry> <entry>(1L << 10)</entry> </row> <row> - <entry>XkbLookupModsMask</entry> + <entry><symbol>XkbLookupModsMask</symbol></entry> <entry>(1L << 11)</entry> </row> <row> - <entry>XkbCompatLookupModsMask</entry> + <entry><symbol>XkbCompatLookupModsMask</symbol></entry> <entry>(1L << 12)</entry> </row> <row> - <entry>XkbPointerButtonMask</entry> + <entry><symbol>XkbPointerButtonMask</symbol></entry> <entry>(1L << 13)</entry> </row> <row> - <entry>XkbAllStateComponentsMask</entry> + <entry><symbol>XkbAllStateComponentsMask</symbol></entry> <entry>(0x3fff)</entry> </row> </tbody> @@ -841,117 +934,117 @@ There are many different types of Xkb state changes. Xkb defines an event detail </table> <para> -To track changes in the keyboard state for a particular device, select to receive <emphasis> -XkbStateNotify</emphasis> - events by calling either <emphasis> -XkbSelectEvents</emphasis> - or <emphasis> -XkbSelectEventDetails</emphasis> - (see section 4.3). <!-- xref --> +To track changes in the keyboard state for a particular device, select to receive +<symbol>XkbStateNotify</symbol> +events by calling either +<function>XkbSelectEvents</function> +or +<function>XkbSelectEventDetails</function> +(see <link linkend="Selecting_Xkb_Events">section 4.3</link>). </para> <para> -To receive <emphasis> -XkbStateNotify</emphasis> - events under all possible conditions, use <emphasis> -XkbSelectEvents</emphasis> - and pass <emphasis> -XkbStateNotifyMask</emphasis> - in both <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> -. +To receive +<symbol>XkbStateNotify</symbol> +events under all possible conditions, use +<function>XkbSelectEvents</function> +and pass +<symbol>XkbStateNotifyMask</symbol> +in both +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter>. </para> <para> -To receive <emphasis> -XkbStateNotify</emphasis> - events only under certain conditions, use <emphasis> -XkbSelectEventDetails</emphasis> - using <emphasis> -XkbStateNotify</emphasis> - as the <emphasis> -event_type</emphasis> - and specifying the desired state changes in <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> - using mask bits from Table 5.3. <!-- xref --> +To receive +<symbol>XkbStateNotify</symbol> +events only under certain conditions, use +<function>XkbSelectEventDetails</function> +using +<symbol>XkbStateNotify</symbol> +as the +<structfield>event_type</structfield> +and specifying the desired state changes in +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +using mask bits from <link linkend="table5.3">Table 5.3</link>. </para> <para> -The structure for <emphasis> -XkbStateNotify</emphasis> - events is: -</para> +The structure for +<symbol>XkbStateNotify</symbol> +events is: -<para><programlisting> +<programlisting> typedef struct { - int type; /* Xkb extension base event code */ - unsigned long serial; /* X server serial number for event */ - Bool send_event; /* <emphasis> True</emphasis> => synthetically generated */ - Display * display; /* server connection where event generated */ - Time time; /* server time when event generated */ - int xkb_type; /* <emphasis> XkbStateNotify</emphasis> */ - int device; /* Xkb device ID, will not be <emphasis> XkbUseCoreKbd</emphasis> */ - unsigned int changed; /* bits indicating what has changed */ - int group; /* group index of effective group */ - int base_group; /* group index of base group */ - int latched_group; /* group index of latched group */ - int locked_group; /* group index of locked group */ - unsigned int mods; /* effective modifiers */ - unsigned int base_mods; /* base modifiers */ - unsigned int latched_mods; /* latched modifiers */ - unsigned int locked_mods; /* locked modifiers */ - int compat_state; /* computed compatibility state */ - unsigned char grab_mods; /* modifiers used for grabs */ - unsigned char compat_grab_mods; /* modifiers used for compatibility grabs */ - unsigned char lookup_mods; /* modifiers used to lookup symbols */ - unsigned char compat_lookup_mods; /* mods used for compatibility look up */ - int ptr_buttons; /* core pointer buttons */ - KeyCode keycode; /* keycode causing event, 0 if programmatic */ - char event_type; /* core event if <emphasis> req_major</emphasis> or - <emphasis> req_minor</emphasis> non zero */ - char req_major; /* major request code if program trigger, else 0 */ - char req_minor; /* minor request code if program trigger, else 0 */ -} <emphasis>XkbStateNotifyEvent</emphasis> -; + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* <symbol>True</symbol> ⇒ synthetically generated */ + Display * display; /* server connection where event generated */ + Time time; /* server time when event generated */ + int xkb_type; /* <symbol>XkbStateNotify</symbol> */ + int device; /* Xkb device ID, + will not be <symbol>XkbUseCoreKbd</symbol> */ + unsigned int changed; /* bits indicating what has changed */ + int group; /* group index of effective group */ + int base_group; /* group index of base group */ + int latched_group; /* group index of latched group */ + int locked_group; /* group index of locked group */ + unsigned int mods; /* effective modifiers */ + unsigned int base_mods; /* base modifiers */ + unsigned int latched_mods; /* latched modifiers */ + unsigned int locked_mods; /* locked modifiers */ + int compat_state; /* computed compatibility state */ + unsigned char grab_mods; /* modifiers used for grabs */ + unsigned char compat_grab_mods; /* modifiers used for compatibility grabs */ + unsigned char lookup_mods; /* modifiers used to lookup symbols */ + unsigned char compat_lookup_mods; /* mods used for compatibility look up */ + int ptr_buttons; /* core pointer buttons */ + KeyCode keycode; /* keycode causing event, + 0 if programmatic */ + char event_type; /* core event if <structfield>req_major</structfield> or <structfield>req_minor</structfield> + non zero */ + char req_major; /* major request code if program trigger, + else 0 */ + char req_minor; /* minor request code if program trigger, + else 0 */ +} <structname>XkbStateNotifyEvent</structname>; </programlisting></para> <para> -When you receive an <emphasis> -XkbStateNotify</emphasis> - event, the <emphasis> -changed</emphasis> - field indicates which elements of keyboard state have changed. -This will be the bitwise inclusive OR of one or more of the <emphasis> -XkbStateNotify</emphasis> - event detail masks shown in Table 5.3. All fields reported in <!-- xref --> -the event are valid, but only those indicated in <emphasis> -changed</emphasis> - have changed values. +When you receive an +<symbol>XkbStateNotify</symbol> +event, the +<structfield>changed</structfield> +field indicates which elements of keyboard state have changed. +This will be the bitwise inclusive OR of one or more of the +<symbol>XkbStateNotify</symbol> +event detail masks shown in <link linkend="table5.3">Table 5.3</link>. +All fields reported in the event are valid, but only those indicated in +<structfield>changed</structfield> +have changed values. </para> <para> -The <emphasis> -group</emphasis> - field is the group index of the effective keysym group. The <emphasis> -base_group</emphasis> -, <emphasis> -latched_group</emphasis> -, and <emphasis> -locked_group</emphasis> - fields are set to a group index value representing the base group, +The +<structfield>group</structfield> +field is the group index of the effective keysym group. The +<structfield>base_group</structfield>, +<structfield>latched_group</structfield>, +and +<structfield>locked_group</structfield> +fields are set to a group index value representing the base group, the latched group, and the locked group, respectively. The X server can set the modifier and compatibility state fields to a union of the core modifier mask bits; this union represents the -corresponding modifier states. The <emphasis>ptr_button</emphasis> - field gives the state of the core pointer buttons as a +corresponding modifier states. The <structfield>ptr_buttons</structfield> +field gives the state of the core pointer buttons as a mask composed of an inclusive OR of zero or more of the core pointer button masks. </para> @@ -960,28 +1053,28 @@ core pointer button masks. <para> Xkb state changes can occur either in response to keyboard activity or under application control. If a key event -caused the state change, the <emphasis> -keycode</emphasis> - field gives the keycode of the key event, and the <emphasis> -event_type</emphasis> - field is set to either <emphasis>KeyPress</emphasis> - or <emphasis> -KeyRelease</emphasis> -. If a pointer button event caused the state change, the <emphasis> -keycode</emphasis> - field is zero, and the <emphasis>event_type</emphasis> - field is set to either <emphasis>ButtonPress</emphasis> - or <emphasis>ButtonRelease</emphasis> -. Otherwise, the major and minor codes of the request that caused the -state change are given in the <emphasis> -req_major</emphasis> - and <emphasis> -req_minor</emphasis> - fields, and the <emphasis> -keycode</emphasis> - field is zero. The <emphasis> -req_major</emphasis> - value is the same as the major extension opcode. +caused the state change, the +<structfield>keycode</structfield> +field gives the keycode of the key event, and the +<structfield>event_type</structfield> +field is set to either <symbol>KeyPress</symbol> +or +<symbol>KeyRelease</symbol>. +If a pointer button event caused the state change, the +<structfield>keycode</structfield> +field is zero, and the <structfield>event_type</structfield> +field is set to either <symbol>ButtonPress</symbol> +or <symbol>ButtonRelease</symbol>. +Otherwise, the major and minor codes of the request that caused the +state change are given in the +<structfield>req_major</structfield> +and +<structfield>req_minor</structfield> +fields, and the +<structfield>keycode</structfield> +field is zero. The +<structfield>req_major</structfield> +value is the same as the major extension opcode. </para> </sect1> </chapter> diff --git a/libX11/specs/XKB/ch06.xml b/libX11/specs/XKB/ch06.xml index 422e6d23b..b3b58da28 100644 --- a/libX11/specs/XKB/ch06.xml +++ b/libX11/specs/XKB/ch06.xml @@ -1,3 +1,6 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Complete_Keyboard_Description'> <title>Complete Keyboard Description</title> @@ -11,73 +14,64 @@ document that discuss the major Xkb components in detail. <sect1 id='The_XkbDescRec_Structure'> <title>The XkbDescRec Structure</title> +<indexterm significance="preferred" zone="The_XkbDescRec_Structure"> +<primary><structname>XkbDescRec</structname></primary></indexterm> + <para> -The complete description of an Xkb keyboard is given by an <emphasis> -XkbDescRec</emphasis> -. The component structures in the <emphasis> -XkbDescRec</emphasis> - represent the major Xkb components outlined in Figure 1.1. <!-- xref --> +The complete description of an Xkb keyboard is given by an +<structname>XkbDescRec</structname>. +The component structures in the +<structname>XkbDescRec</structname> +represent the major Xkb components outlined in <link linkend="figure1.1">Figure 1.1</link>. </para> <para><programlisting> typedef struct { - struct _XDisplay * display; /* connection to -X server */ - unsigned short flags; /* private to Xkb, do -not modify */ - unsigned short device_spec; /* device of -interest */ - KeyCode min_key_code; /* minimum keycode for -device */ - KeyCode max_key_code; /* maximum keycode for -device */ - XkbControlsPtr ctrls; /* controls */ - XkbServerMapPtr server; /* server keymap */ - XkbClientMapPtr map; /* client keymap */ - XkbIndicatorPtr indicators; /* indicator map -*/ - XkbNamesPtr names; /* names for all -components */ - XkbCompatMapPtr compat; /* compatibility map -*/ - XkbGeometryPtr geom; /* physical geometry of -keyboard */ -} <emphasis> -XkbDescRec</emphasis> -, *XkbDescPtr; + struct _XDisplay * display; /* connection to X server */ + unsigned short flags; /* private to Xkb, do not modify */ + unsigned short device_spec; /* device of interest */ + KeyCode min_key_code; /* minimum keycode for device */ + KeyCode max_key_code; /* maximum keycode for device */ + XkbControlsPtr ctrls; /* controls */ + XkbServerMapPtr server; /* server keymap */ + XkbClientMapPtr map; /* client keymap */ + XkbIndicatorPtr indicators; /* indicator map */ + XkbNamesPtr names; /* names for all components */ + XkbCompatMapPtr compat; /* compatibility map */ + XkbGeometryPtr geom; /* physical geometry of keyboard */ +} <structname>XkbDescRec</structname>, *XkbDescPtr; </programlisting></para> <para> -The <emphasis> -display</emphasis> - field points to an X display structure. The <emphasis> -flags</emphasis> - field is private to the library: modifying <emphasis> -flags</emphasis> - may yield unpredictable results. The <emphasis> -device_spec</emphasis> - field specifies the device identifier of the keyboard input device, or -<emphasis> -XkbUseCoreKeyboard</emphasis> -, which specifies the core keyboard device. The <emphasis> -min_key_code</emphasis> - and <emphasis> -max_key_code</emphasis> - fields specify the least and greatest keycode that can be returned by the +The +<parameter>display</parameter> +field points to an X display structure. The +<structfield>flags</structfield> +field is private to the library: modifying +<structfield>flags</structfield> +may yield unpredictable results. The +<parameter>device_spec</parameter> +field specifies the device identifier of the keyboard input device, or +<symbol>XkbUseCoreKbd</symbol>, +which specifies the core keyboard device. The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields specify the least and greatest keycode that can be returned by the keyboard. </para> <para> The other fields specify structure components of the keyboard description and -are described in detail in other sections of this document. Table 6.1 +are described in detail in other sections of this document. +<link linkend="table6.1">Table 6.1</link> identifies the subsequent sections of this document that discuss the individual -components of the <emphasis> -XkbDescRec</emphasis> -. +components of the +<structname>XkbDescRec</structname>. </para> -<table frame='topbot'> +<table id='table6.1' frame='topbot'> <title>XkbDescRec Component References</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -92,31 +86,31 @@ XkbDescRec</emphasis> <tbody> <row> <entry>ctrls</entry> - <entry>Chapter 10</entry> + <entry><xref linkend="Keyboard_Controls" /></entry> </row> <row> <entry>server</entry> - <entry>Chapter 16</entry> + <entry><xref linkend="Xkb_Server_Keyboard_Mapping" /></entry> </row> <row> <entry>map</entry> - <entry>Chapter 15</entry> + <entry><xref linkend="Xkb_Client_Keyboard_Mapping" /></entry> </row> <row> <entry>indicators</entry> - <entry>Chapter 8</entry> + <entry><xref linkend="Indicators" /></entry> </row> <row> <entry>names</entry> - <entry>Chapter 18</entry> + <entry><xref linkend="Symbolic_Names" /></entry> </row> <row> <entry>compat</entry> - <entry>Chapter 17</entry> + <entry><xref linkend="The_Xkb_Compatibility_Map" /></entry> </row> <row> <entry>geom</entry> - <entry>Chapter 13</entry> + <entry><xref linkend="Keyboard_Geometry" /></entry> </row> </tbody> </tgroup> @@ -126,12 +120,12 @@ XkbDescRec</emphasis> Each structure component has a corresponding mask bit that is used in function calls to indicate that the structure should be manipulated in some manner, such as allocating it or freeing it. These masks and their relationships to the -fields in the <emphasis> -XkbDescRec</emphasis> - are shown in Table 6.2. <!-- xref --> +fields in the +<structname>XkbDescRec</structname> +are shown in <link linkend="table6.2">Table 6.2</link>. </para> -<table frame='topbot'> +<table id='table6.2' frame='topbot'> <title>Mask Bits for XkbDescRec</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -147,12 +141,12 @@ XkbDescRec</emphasis> </thead> <tbody> <row> - <entry>XkbControlsMask</entry> + <entry><symbol>XkbControlsMask</symbol></entry> <entry>ctrls</entry> <entry>(1L<<0)</entry> </row> <row> - <entry>XkbServerMapMask</entry> + <entry><symbol>XkbServerMapMask</symbol></entry> <entry>server</entry> <entry>(1L<<1)</entry> </row> @@ -162,27 +156,27 @@ XkbDescRec</emphasis> <entry>(1L<<2)</entry> </row> <row> - <entry>XkbIndicatorMapMask</entry> + <entry><symbol>XkbIndicatorMapMask</symbol></entry> <entry>indicators</entry> <entry>(1L<<3)</entry> </row> <row> - <entry>XkbNamesMask</entry> + <entry><symbol>XkbNamesMask</symbol></entry> <entry>names</entry> <entry>(1L<<4)</entry> </row> <row> - <entry>XkbCompatMapMask</entry> + <entry><symbol>XkbCompatMapMask</symbol></entry> <entry>compat</entry> <entry>(1L<<5)</entry> </row> <row> - <entry>XkbGeometryMask</entry> + <entry><symbol>XkbGeometryMask</symbol></entry> <entry>geom</entry> <entry>(1L<<6)</entry> </row> <row> - <entry>XkbAllComponentsMask</entry> + <entry><symbol>XkbAllComponentsMask</symbol></entry> <entry>All Fields</entry> <entry>(0x7f)</entry> </row> @@ -196,86 +190,88 @@ XkbDescRec</emphasis> <para> To retrieve one or more components of a keyboard device description, use -<emphasis> -XkbGetKeyboard</emphasis> - (see also <emphasis> -XkbGetKeyboardbyName</emphasis> -). +<function>XkbGetKeyboard</function> +(see also +<link linkend="XkbGetKeyboardByName"><function>XkbGetKeyboardByName</function></link>). + </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbDescPtr <emphasis> -XkbGetKeyboard</emphasis> -(<emphasis> -display, which, device_spec</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -which</emphasis> -; /* mask indicating components to return */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - device_spec</emphasis> -; /* device for which to fetch description, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbGetKeyboard"><primary><function>XkbGetKeyboard</function></primary></indexterm> +<funcsynopsis id="XkbGetKeyboard"> + <funcprototype> + <funcdef>XkbDescPtr <function>XkbGetKeyboard</function></funcdef> +<!-- ( +<parameter>display, which, device_spec</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask indicating components to return + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device for which to fetch description, or +<symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbGetKeyboard </emphasis> +<function>XkbGetKeyboard</function> allocates and returns a pointer to a keyboard description. It queries the -server for those components specified in the <emphasis> -which</emphasis> - parameter for device <emphasis> -device_spec</emphasis> - and copies the results to the <emphasis> -XkbDescRec</emphasis> - it allocated. The remaining fields in the keyboard description are set to -<emphasis> -NULL</emphasis> -. The valid masks for <emphasis> -which</emphasis> - are those listed in Table 6.2. <!-- xref --> +server for those components specified in the +<parameter>which</parameter> +parameter for device +<parameter>device_spec</parameter> +and copies the results to the +<structname>XkbDescRec</structname> +it allocated. The remaining fields in the keyboard description are set to +<symbol>NULL</symbol>. +The valid masks for +<parameter>which</parameter> +are those listed in <link linkend="table6.2">Table 6.2</link>. </para> <para> -<emphasis> -XkbGetKeyboard</emphasis> - can generate <emphasis> -BadAlloc</emphasis> - protocol errors. +<function>XkbGetKeyboard</function> +can generate +<errorname>BadAlloc</errorname> +protocol errors. </para> <para> -To free the returned keyboard description, use <emphasis> -XkbFreeKeyboard</emphasis> - (see section 6.4). <!-- xref --> +To free the returned keyboard description, use +<function>XkbFreeKeyboard</function> +(see <link linkend="Allocating_and_Freeing_a_Keyboard_Description">section 6.4</link>). </para> @@ -285,7 +281,7 @@ XkbFreeKeyboard</emphasis> <para> The server can generate events whenever its copy of the keyboard description -for a device changes. Refer to section 14.4 for detailed information on <!-- xref --> +for a device changes. Refer to <link linkend="Tracking_Changes_to_Map_Components">section 14.4</link> for detailed information on tracking changes to the keyboard description. </para> @@ -296,122 +292,114 @@ tracking changes to the keyboard description. <para> Applications seldom need to directly allocate a keyboard description; calling -<emphasis> -XkbGetKeyboard</emphasis> - usually suffices. In the event you need to create a keyboard description from -scratch, however, use <emphasis> -XkbAllocKeyboard</emphasis> - rather than directly calling <emphasis> -malloc </emphasis> -or <emphasis> -Xmalloc</emphasis> -. +<function>XkbGetKeyboard</function> +usually suffices. In the event you need to create a keyboard description from +scratch, however, use +<function>XkbAllocKeyboard</function> +rather than directly calling +<function>malloc</function> +or +<function>Xmalloc</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbDescRec * <emphasis> -XkbAllocKeyboard</emphasis> -(void) - </entry> - </row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbAllocKeyboard"><primary><function>XkbAllocKeyboard</function></primary></indexterm> +<funcsynopsis id="XkbAllocKeyboard"> + <funcprototype> + <funcdef>XkbDescRec *<function>XkbAllocKeyboard</function></funcdef> + <void /> + + </funcprototype> +</funcsynopsis> <para> -If <emphasis> -XkbAllocKeyboard</emphasis> - fails to allocate the keyboard description, it returns <emphasis> -NULL</emphasis> -. Otherwise, it returns a pointer to an empty keyboard description structure. -The <emphasis> -device_spec</emphasis> - field will have been initialized to <emphasis> -XkbUseCoreKbd</emphasis> -. You may then either fill in the structure components or use Xkb functions to +If +<function>XkbAllocKeyboard</function> +fails to allocate the keyboard description, it returns +<symbol>NULL</symbol>. +Otherwise, it returns a pointer to an empty keyboard description structure. +The +<structfield>device_spec</structfield> +field will have been initialized to +<symbol>XkbUseCoreKbd</symbol>. +You may then either fill in the structure components or use Xkb functions to obtain values for the structure components from a keyboard device. </para> <para> -To destroy either an entire an <emphasis> -XkbDescRec</emphasis> - or just some of its members, use <emphasis> -XkbFreeKeyboard.</emphasis> +To destroy either an entire an +<structname>XkbDescRec</structname> +or just some of its members, use +<function>XkbFreeKeyboard</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeKeyboard</emphasis> -<emphasis> -(xkb, which, free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* keyboard description with components to free */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - which</emphasis> -; /* mask selecting components to free */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all</emphasis> -; /* <emphasis> -True</emphasis> - => free all components and <emphasis> -xkb</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbFreeKeyboard"><primary><function>XkbFreeKeyboard</function></primary></indexterm> +<funcsynopsis id="XkbFreeKeyboard"> + <funcprototype> + <funcdef>void <function>XkbFreeKeyboard</function></funcdef> +<!-- +<parameter>(xkb, which, free_all</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description with components to free + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask selecting components to free + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ free all components and <parameter>xkb</parameter> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbFreeKeyboard</emphasis> - frees the components of <emphasis> -xkb</emphasis> - specified by <emphasis> -which</emphasis> - and sets the corresponding values to <emphasis> -NULL</emphasis> -. If <emphasis> -free_all</emphasis> - is <emphasis> -True</emphasis> -, <emphasis> -XkbFreeKeyboard</emphasis> - frees every non-<emphasis> -NULL</emphasis> - component of <emphasis> -xkb</emphasis> - and then frees the <emphasis> -xkb</emphasis> - structure itself. +<function>XkbFreeKeyboard</function> +frees the components of +<parameter>xkb</parameter> +specified by +<parameter>which</parameter> +and sets the corresponding values to +<symbol>NULL</symbol>. +If +<parameter>free_all</parameter> +is +<symbol>True</symbol>, +<function>XkbFreeKeyboard</function> +frees every non- +<symbol>NULL</symbol> +component of +<parameter>xkb</parameter> +and then frees the +<parameter>xkb</parameter> +structure itself. </para> </sect1> diff --git a/libX11/specs/XKB/ch07.xml b/libX11/specs/XKB/ch07.xml index 35b45901f..cbb549ce8 100644 --- a/libX11/specs/XKB/ch07.xml +++ b/libX11/specs/XKB/ch07.xml @@ -1,23 +1,26 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <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 the <emphasis> -Num_Lock</emphasis> - keysym is bound to some modifier, that modifier is used to select between +when the +<keysym>Num_Lock</keysym> +keysym is bound to some modifier, that modifier is used to select between shifted and unshifted state for the numeric keypad keys. The core protocol does not provide a convenient way to determine the mapping of modifier bits (in -particular <emphasis> -Mod1</emphasis> - through <emphasis> -Mod5</emphasis> -) to keysyms such as <emphasis> -Num_Lock</emphasis> - and <emphasis> -Mode_switch</emphasis> -. Using the core protocol only, a client application must retrieve and search +particular +<symbol>Mod1</symbol> +through +<symbol>Mod5</symbol>) +to keysyms such as +<keysym>Num_Lock</keysym> +and +<keysym>Mode_switch</keysym>. +Using the core protocol only, a client application must retrieve and search the modifier map to determine the keycodes bound to each modifier, and then retrieve and search the keyboard mapping to determine the keysyms bound to the keycodes. It must repeat this process for all modifiers whenever any part of @@ -27,35 +30,41 @@ the modifier mapping is changed. <para> Xkb alleviates these problems by defining virtual modifiers. In addition to the -eight core modifiers, referred to as the <emphasis> -real modifiers</emphasis> -, Xkb provides a set of sixteen named <emphasis> -virtual modifiers</emphasis> -. Each virtual modifier can be bound to any set of the real modifiers -(<emphasis> -Shift</emphasis> -, <emphasis> -Lock</emphasis> -, <emphasis> -Control,</emphasis> - and <emphasis> -Mod1</emphasis> --<emphasis> -Mod5</emphasis> -). +eight core modifiers, referred to as the +<firstterm>real modifiers</firstterm>, +<indexterm significance="preferred" zone="Virtual_Modifiers"> +<primary>real modifiers</primary></indexterm> +<indexterm significance="preferred" zone="Virtual_Modifiers"> +<primary>modifiers</primary><secondary>real</secondary></indexterm> +Xkb provides a set of sixteen named +<firstterm>virtual modifiers</firstterm>. +<indexterm significance="preferred" zone="Virtual_Modifiers"> +<primary>virtual modifiers</primary></indexterm> +<indexterm significance="preferred" zone="Virtual_Modifiers"> +<primary>modifiers</primary><secondary>virtual</secondary></indexterm> +Each virtual modifier can be bound to any set of the real modifiers +( +<symbol>Shift</symbol>, +<symbol>Lock</symbol>, +<symbol>Control</symbol>, +and +<symbol>Mod1</symbol> +– +<symbol>Mod5</symbol>). + </para> <para> The separation of function from physical modifier bindings makes it easier to specify more clearly the intent of a binding. X servers do not all assign -modifiers the same way — for example, <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 +modifiers the same way — for example, +<keysym>Num_Lock</keysym> +might be bound to +<symbol>Mod2</symbol> +for one vendor and to +<symbol>Mod4</symbol> +for another. This makes it cumbersome to automatically remap the keyboard to a desired configuration without some kind of prior knowledge about the keyboard layout and bindings. With XKB, applications can use virtual modifiers to specify the desired behavior, without regard for the actual physical bindings @@ -66,19 +75,19 @@ in effect. <title>Virtual Modifier Names and Masks</title> <para> -Virtual modifiers are named by converting their string name to an X <emphasis> -Atom</emphasis> - and storing the Atom in the <emphasis> -names.vmods</emphasis> - array in an <emphasis> -XkbDescRec</emphasis> - structure (see section 6.1). The position of a name Atom in the <emphasis> -names.vmods</emphasis> - array defines the bit position used to represent the virtual modifier and also +Virtual modifiers are named by converting their string name to an X +<type>Atom</type> +and storing the Atom in the +<structfield>names.vmods</structfield> +array in an +<structname>XkbDescRec</structname> +structure (see <link linkend="The_XkbDescRec_Structure">section 6.1</link>). The position of a name Atom in the +<structfield>names.vmods</structfield> +array defines the bit position used to represent the virtual modifier and also the index used when accessing virtual modifier information in arrays: the name -in the i-th (0 relative) entry of <emphasis> -names.vmods</emphasis> - is the i-th virtual modifier, represented by the mask (1<<i). Throughout +in the i-th (0 relative) entry of +<structfield>names.vmods</structfield> +is the i-th virtual modifier, represented by the mask (1<<i). Throughout Xkb, various functions have a parameter that is a mask representing virtual modifier choices. In each case, the i-th bit (0 relative) of the mask represents the i-th virtual modifier. @@ -86,17 +95,17 @@ represents the i-th virtual modifier. <para> -To set the name of a virtual modifier, use <emphasis> -XkbSetNames</emphasis> -, using <emphasis> -XkbVirtualModNamesMask</emphasis> - in <emphasis> -which</emphasis> - and the name in the <emphasis> -xkb</emphasis> - argument; to retrieve indicator names, use <emphasis> -XkbGetNames</emphasis> -. These functions are discussed in Chapter 18. +To set the name of a virtual modifier, use +<function>XkbSetNames</function>, +using +<symbol>XkbVirtualModNamesMask</symbol> +in +<parameter>which</parameter> +and the name in the +<parameter>xkb</parameter> +argument; to retrieve indicator names, use +<function>XkbGetNames</function>. +These functions are discussed in <xref linkend="Symbolic_Names" />. </para> @@ -104,52 +113,53 @@ XkbGetNames</emphasis> <sect1 id='Modifier_Definitions'> <title>Modifier Definitions</title> +<indexterm significance="preferred" zone="Modifier_Definitions"> +<primary><structname>XkbModsRec</structname></primary></indexterm> + <para> -An Xkb<emphasis> - modifier definition</emphasis> - enumerates a collection of real and virtual modifiers but does not in itself +An Xkb +<firstterm>modifier definition</firstterm> +<indexterm significance="preferred" zone="grab_state"> +<primary>modifier definition</primary></indexterm> +enumerates a collection of real and virtual modifiers but does not in itself bind those modifiers to any particular key or to each other. Modifier definitions are included in a number of structures in the keyboard description to define the collection of modifiers that affect or are affected by some other entity. A modifier definition is relevant only in the context of some other -entity such as an indicator map, a control, or a key type. (See sections 8.2.2, -10.8, and 15.2.) <!-- xref --> +entity such as an indicator map, a control, or a key type. (See +<link linkend="XkbIndicatorMapRec">section 8.2.2</link>, +<link linkend="The_XkbControlsRec_Structure">section 10.8</link>, and +<link linkend="Key_Types">section 15.2</link>.) </para> <para><programlisting> typedef struct _XkbMods { - unsigned char mask; /* real_mods | vmods mapped to -real modifiers */ - unsigned char real_mods; /* real modifier bits */ - unsigned short vmods; /* virtual modifier bits */ -} <emphasis> -XkbModsRec</emphasis> -,*XkbModsPtr; + unsigned char mask; /* real_mods | vmods mapped to real modifiers */ + unsigned char real_mods; /* real modifier bits */ + unsigned short vmods; /* virtual modifier bits */ +} <structname>XkbModsRec</structname>, *XkbModsPtr; </programlisting></para> <para> An Xkb modifier definition consists of a set of bit masks corresponding to the -eight real modifiers (<emphasis> -real_mods</emphasis> -); a similar set of bitmasks corresponding to the 16 named virtual modifiers -(<emphasis> -vmods</emphasis> -); and an effective mask (<emphasis> -mask</emphasis> -). The effective mask represents the set of all real modifiers that can +eight real modifiers +(<structfield>real_mods</structfield>); +a similar set of bitmasks corresponding to the 16 named virtual modifiers +(<structfield>vmods</structfield>); +and an effective mask +(<structfield>mask</structfield>). +The effective mask represents the set of all real modifiers that can logically be set either by setting any of the real modifiers or by setting any -of the virtual modifiers in the definition. <emphasis> -mask</emphasis> - is derived from the real and virtual modifiers and should never be explicitly +of the virtual modifiers in the definition. +<structfield>mask</structfield> +is derived from the real and virtual modifiers and should never be explicitly changed — it contains all of the real modifiers specified in the definition -(<emphasis> -real_mods</emphasis> -)<emphasis> - plus</emphasis> - any real modifiers that are bound to the virtual modifiers specified in the -definition (<emphasis> -vmods</emphasis> -). The binding of the virtual modifiers to real modifiers is exterior to the +(<structfield>real_mods</structfield>) +<emphasis>plus</emphasis> +any real modifiers that are bound to the virtual modifiers specified in the +definition +(<structfield>vmods</structfield>). +The binding of the virtual modifiers to real modifiers is exterior to the modifier definition. Xkb automatically recomputes the mask field of modifier definitions as necessary. Whenever you access a modifier definition that has been retrieved using an Xkb library function, the mask field will be correct @@ -162,14 +172,14 @@ for the keyboard mapping of interest. <title>Binding Virtual Modifiers to Real Modifiers</title> <para> -The binding of virtual modifiers to real modifiers is defined by the <emphasis> -server.vmods</emphasis> - array in an <emphasis> -XkbDescRec</emphasis> - structure. Each entry contains the real modifier bits that are bound to the +The binding of virtual modifiers to real modifiers is defined by the +<structfield>server.vmods</structfield> +array in an +<structname>XkbDescRec</structname> +structure. Each entry contains the real modifier bits that are bound to the virtual modifier corresponding to the entry. The overall relationship of fields dealing with virtual modifiers in the server keyboard description are shown in -Figure 16.2. <!-- xref --> +<link linkend="figure16.2">Figure 16.2</link>. </para> @@ -178,151 +188,153 @@ Figure 16.2. <!-- xref --> <title>Virtual Modifier Key Mapping</title> <para> -Xkb maintains a <emphasis> -virtual modifier mapping</emphasis> -, which lists the virtual modifiers associated with, or bound to, each key. The +Xkb maintains a +<firstterm>virtual modifier mapping</firstterm>, +<indexterm significance="preferred" zone="Virtual_Modifier_Key_Mapping"> +<primary>virtual modifier mapping</primary></indexterm> +<indexterm significance="preferred" zone="Virtual_Modifier_Key_Mapping"> +<primary>modifiers</primary><secondary>virtual mapping</secondary></indexterm> +which lists the virtual modifiers associated with, or bound to, each key. The real modifiers bound to a virtual modifier always include all of the modifiers bound to any of the keys that specify that virtual modifier in their virtual -modifier mapping. The <emphasis> -server.vmodmap</emphasis> - array indicates which virtual modifiers are bound to each key; each entry is a -bitmask for the virtual modifier bits. The <emphasis> -server.vmodmap</emphasis> - array is indexed by keycode. +modifier mapping. The +<structfield>server.vmodmap</structfield> +array indicates which virtual modifiers are bound to each key; each entry is a +bitmask for the virtual modifier bits. The +<structfield>server.vmodmap</structfield> +array is indexed by keycode. </para> <para> -The <emphasis> -vmodmap</emphasis> - and <emphasis> -vmods</emphasis> - members of the server map are the "master" virtual modifier definitions. Xkb +The +<structfield>vmodmap</structfield> +and +<structfield>vmods</structfield> +members of the server map are the <quote>master</quote> virtual modifier definitions. Xkb automatically propagates any changes to these fields to all other fields that -use virtual modifier mappings (see section 16.4). +use virtual modifier mappings (see <link linkend="Virtual_Modifier_Mapping">section 16.4</link>). </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 <emphasis> -NumLock</emphasis> -. +For example, if +<symbol>Mod3</symbol> +is bound to the +<keysym>Num_Lock</keysym> +key by the core protocol modifier mapping, and the +<emphasis>NumLock</emphasis> +virtual modifier is bound to they +<keysym>Num_Lock</keysym> +key by the virtual modifier mapping, +<symbol>Mod3</symbol> +is added to the set of modifiers associated with +<emphasis>NumLock</emphasis>. </para> <para> The virtual modifier mapping is normally updated whenever actions are -automatically applied to symbols (see section 16.4 for details), and few +automatically applied to symbols (see <link linkend="Virtual_Modifier_Mapping">section 16.4</link> for details), and few applications should need to change the virtual modifier mapping explicitly. </para> <para> -Use <emphasis> -XkbGetMap </emphasis> -(see section 14.2) to get the virtual modifiers from the server or use <!-- xref --> -<emphasis> -XkbGetVirtualMods</emphasis> - (see section 16.4.1) to update a local copy of the virtual modifiers bindings <!-- xref --> +Use +<function>XkbGetMap</function> +(see <link linkend="Getting_Map_Components_from_the_Server">section 14.2</link>) to get the virtual modifiers from the server or use +<function>XkbGetVirtualMods</function> +(see <link linkend="Obtaining_Virtual_Modifier_Bindings_from_the_Server">section 16.4.1</link>) to update a local copy of the virtual modifiers bindings from the server. To set the binding of a virtual modifier to a real modifier, -use <emphasis> -XkbSetMap</emphasis> - (see<emphasis> - </emphasis> -section 14.3<emphasis> <!-- xref --> -).</emphasis> +use +<function>XkbSetMap</function> +(see +<link linkend="Changing_Map_Components_in_the_Server">section 14.3</link>). </para> <para> To determine the mapping of virtual modifiers to core X protocol modifiers, use -<emphasis> -XkbVirtualModsToReal</emphasis> -. +<function>XkbVirtualModsToReal</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbVirtualModsToReal</emphasis> -(<emphasis> -xkb, virtual_mask, mask_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* keyboard description for input device */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - virtual_mask</emphasis> -; /* virtual modifier mask to translate */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -mask_rtrn</emphasis> -; /* backfilled with real modifiers */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbVirtualModsToReal"><primary><function>XkbVirtualModsToReal</function></primary></indexterm> +<funcsynopsis id="XkbVirtualModsToReal"> + <funcprototype> + <funcdef>Bool <function>XkbVirtualModsToReal</function></funcdef> +<!-- ( +<parameter>xkb, virtual_mask, mask_rtrn</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>virtual_mask</parameter></paramdef> + <paramdef>unsigned int *<parameter>mask_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description for input device + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>virtual_mask</parameter> + </term> + <listitem> + <para> + virtual modifier mask to translate + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>mask_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with real modifiers + </para> + </listitem> + </varlistentry> +</variablelist> <para> -If the keyboard description defined by <emphasis> -xkb</emphasis> - includes bindings for virtual modifiers, <emphasis> -XkbVirtualModsToReal</emphasis> - uses those bindings to determine the set of real modifiers that correspond to -the set of virtual modifiers specified in <emphasis> -virtual_mask</emphasis> -. The <emphasis> -virtual_mask</emphasis> - parameter is a mask specifying the virtual modifiers to translate; the i-th -bit (0 relative) of the mask represents the i-th virtual modifier. If <emphasis> -mask_rtrn</emphasis> - is non-<emphasis> -NULL</emphasis> -, <emphasis> -XkbVirtualModsToReal</emphasis> - backfills it with the resulting real modifier mask. If the keyboard -description in <emphasis> -xkb</emphasis> - does not include virtual modifier bindings, <emphasis> -XkbVirtualModsToReal</emphasis> - returns <emphasis> -False</emphasis> -; otherwise, it returns <emphasis> -True</emphasis> -. +If the keyboard description defined by +<parameter>xkb</parameter> +includes bindings for virtual modifiers, +<function>XkbVirtualModsToReal</function> +uses those bindings to determine the set of real modifiers that correspond to +the set of virtual modifiers specified in +<parameter>virtual_mask</parameter>. +The +<parameter>virtual_mask</parameter> +parameter is a mask specifying the virtual modifiers to translate; the i-th +bit (0 relative) of the mask represents the i-th virtual modifier. If +<parameter>mask_rtrn</parameter> +is non- +<symbol>NULL</symbol>, +<function>XkbVirtualModsToReal</function> +backfills it with the resulting real modifier mask. If the keyboard +description in +<parameter>xkb</parameter> +does not include virtual modifier bindings, +<function>XkbVirtualModsToReal</function> +returns +<symbol>False</symbol>; +otherwise, it returns +<symbol>True</symbol>. </para> <note><para>It is possible for a local (client-side) keyboard description (the -<emphasis> -xkb</emphasis> - parameter) to not contain any virtual modifier information (simply because the +<parameter>xkb</parameter> +parameter) to not contain any virtual modifier information (simply because the client has not requested it) while the server’s corresponding definition may contain virtual modifier information. </para></note> @@ -332,10 +344,8 @@ contain virtual modifier information. </para></note> <para> An unbound virtual modifier is one that is not bound to any real modifier -(<emphasis> -server</emphasis> --><emphasis> -vmods</emphasis> +( +<structfield>server</structfield>-><structfield>vmods</structfield> [virtual_modifier_index] is zero). </para> @@ -343,22 +353,21 @@ vmods</emphasis> <para> Some Xkb operations ignore modifier definitions in which the virtual modifiers are unbound. Consider this example: -</para> -<literallayout> -if (state matches {Shift}) Do OneThing; -if (state matches {Shift+NumLock}) Do Another; +<literallayout> if (state matches {Shift}) Do OneThing; + if (state matches {Shift+NumLock}) Do Another; </literallayout> +</para> <para> -If the <emphasis> -NumLock</emphasis> - virtual modifier is not bound to any real modifiers, the effective masks for -these two cases are identical (that is, 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 +If the +<emphasis>NumLock</emphasis> +virtual modifier is not bound to any real modifiers, the effective masks for +these two cases are identical (that is, contain only +<symbol>Shift</symbol>). +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> @@ -368,41 +377,43 @@ virtual modifiers are bound. <sect1 id='Conventions'> <title>Conventions</title> +<indexterm significance="preferred" zone="Conventions"> +<primary>modifiers</primary><secondary>names</secondary></indexterm> + <para> The Xkb extension does not require any specific virtual modifier names. However, everyone benefits if the same names are used for common modifiers. The following names are suggested: -</para> -<literallayout class='monospaced'> - <emphasis> - NumLock - ScrollLock - Alt - Meta - AltGr - LevelThree</emphasis> -</literallayout> + <simplelist type='vert' columns='1'> + <member><emphasis>NumLock</emphasis></member> + <member><emphasis>ScrollLock</emphasis></member> + <member><emphasis>Alt</emphasis></member> + <member><emphasis>Meta</emphasis></member> + <member><emphasis>AltGr</emphasis></member> + <member><emphasis>LevelThree</emphasis></member> + </simplelist> +</para> </sect1> <sect1 id='Example'> <title>Example</title> <para> -If the second (0-relative) entry in <emphasis> -names.vmods</emphasis> - contains the Atom for "NumLock", then 0x4 (1<<2) is the virtual modifier -bit for the <emphasis> -NumLock</emphasis> - virtual modifier. If <emphasis> -server.vmods</emphasis> -[2] contains <emphasis> -Mod3Mask</emphasis> -, then the <emphasis> -NumLock</emphasis> - virtual modifier is bound to the <emphasis> -Mod3</emphasis> - real modifier. +If the second (0-relative) entry in +<structfield>names.vmods</structfield> +contains the Atom for "NumLock", then 0x4 (1<<2) is the virtual modifier +bit for the +<emphasis>NumLock</emphasis> +virtual modifier. If +<structfield>server.vmods</structfield> +[2] contains +<symbol>Mod3Mask</symbol>, +then the +<emphasis>NumLock</emphasis> +virtual modifier is bound to the +<symbol>Mod3</symbol> +real modifier. </para> @@ -417,25 +428,25 @@ A virtual modifier definition for this example would have: </literallayout> <para> -Continuing the example, if the keyboard has a <emphasis> -Num_Lock</emphasis> - keysym bound to the key with keycode 14, and the <emphasis> -NumLock</emphasis> - virtual modifier is bound to this key, <emphasis> -server.vmodmap</emphasis> -[14] contains 0x4. +Continuing the example, if the keyboard has a +<keysym>Num_Lock</keysym> +keysym bound to the key with keycode 14, and the +<emphasis>NumLock</emphasis> +virtual modifier is bound to this key, +<structfield>server.vmodmap[14]</structfield> +contains 0x4. </para> <para> -Finally, if the keyboard also used the real <emphasis> -Mod1</emphasis> - modifier for numeric lock operations, the modifier definition below would -represent the situation where either the key bound to <emphasis> -Mod1</emphasis> - or the <emphasis> -NumLock</emphasis> - virtual modifier could be used for this purpose: +Finally, if the keyboard also used the real +<symbol>Mod1</symbol> +modifier for numeric lock operations, the modifier definition below would +represent the situation where either the key bound to +<symbol>Mod1</symbol> +or the +<emphasis>NumLock</emphasis> +virtual modifier could be used for this purpose: </para> <literallayout class='monospaced'> diff --git a/libX11/specs/XKB/ch08.xml b/libX11/specs/XKB/ch08.xml index 2b91f00ff..3bb6be629 100644 --- a/libX11/specs/XKB/ch08.xml +++ b/libX11/specs/XKB/ch08.xml @@ -1,32 +1,38 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Indicators'> <title>Indicators</title> +<indexterm significance="preferred" zone="Indicators"> +<primary>indicators</primary></indexterm> + <para> Although the core X implementation supports up to 32 LEDs on an input device, it does not provide any linkage between the state of the LEDs and the logical -state of the input device. For example, most keyboards have a <emphasis> -CapsLock</emphasis> - LED, but X does not provide a mechanism to make the LED automatically follow -the logical state of the <emphasis> -CapsLock</emphasis> - key. +state of the input device. For example, most keyboards have a +<guilabel>CapsLock</guilabel> +LED, but X does not provide a mechanism to make the LED automatically follow +the logical state of the +<keycap>CapsLock</keycap> +key. </para> <para> Furthermore, the core X implementation does not provide clients with the -ability to determine what bits in the <emphasis> -led_mask</emphasis> - field of the <emphasis> -XKeyboardState</emphasis> - map to the particular LEDs on the keyboard. For example, X does not provide a -method for a client to determine what bit to set in the <emphasis> -led_mask</emphasis> - field to turn on the <emphasis> -Scroll Lock </emphasis> -LED or whether the keyboard even has a <emphasis> -Scroll Lock</emphasis> - LED. +ability to determine what bits in the +<structfield>led_mask</structfield> +field of the +<structname>XKeyboardState</structname> +map to the particular LEDs on the keyboard. For example, X does not provide a +method for a client to determine what bit to set in the +<structfield>led_mask</structfield> +field to turn on the +<guilabel>Scroll Lock</guilabel> +LED or whether the keyboard even has a +<guilabel>Scroll Lock</guilabel> +LED. </para> @@ -38,7 +44,8 @@ to reflect keyboard changes, and determine which of the 32 keyboard indicators reported by the protocol are actually present on the keyboard. Clients may also request immediate notification of changes to the state of any subset of the keyboard indicators, which makes it straightforward to provide an on-screen -"virtual" LED panel. This chapter describes Xkb indicators and the functions +<quote>virtual</quote> LED panel. +This chapter describes Xkb indicators and the functions used for manipulating them. </para> @@ -49,15 +56,16 @@ used for manipulating them. Xkb provides the capability of symbolically naming indicators. Xkb itself doesn’t use these symbolic names for anything; they are there only to help make the keyboard description comprehensible to humans. To set the names of -specific indicators, use <emphasis> -XkbSetNames</emphasis> - as discussed in Chapter 18. Then set the map using <emphasis> <!-- xref --> -XkbSetMap</emphasis> - (see section 14.3) or <emphasis> <!-- xref --> -XkbSetNamedIndicator</emphasis> - (below). To retrieve indicator names, use <emphasis> -XkbGetNames</emphasis> - (Chapter 18). <!-- xref --> +specific indicators, use +<function>XkbSetNames</function> +as discussed in <xref linkend="Symbolic_Names" />. Then set the map using +<function>XkbSetMap</function> +(see <link linkend="Changing_Map_Components_in_the_Server">section 14.3</link>) +or +<function>XkbSetNamedIndicator</function> +(below). To retrieve indicator names, use +<function>XkbGetNames</function> +(<xref linkend="Symbolic_Names" />). </para> @@ -66,65 +74,65 @@ XkbGetNames</emphasis> <title>Indicator Data Structures</title> <para> -Use the indicator description record, <emphasis> -XkbIndicatorRec</emphasis> -, and its indicator map, <emphasis> -XkbIndicatorMapRec</emphasis> -, to inquire about and control most indicator properties and behaviors. +Use the indicator description record, +<structname>XkbIndicatorRec</structname>, +and its indicator map, +<structname>XkbIndicatorMapRec</structname>, +to inquire about and control most indicator properties and behaviors. </para> <sect2 id='XkbIndicatorRec'> <title>XkbIndicatorRec</title> +<indexterm significance="preferred" zone="XkbIndicatorRec"> +<primary><structname>XkbIndicatorRec</structname></primary></indexterm> + <para> -The description for all the Xkb indicators is held in the <emphasis> -indicators</emphasis> - field of the complete keyboard description (see Chapter 6), which is defined <!-- xref --> +The description for all the Xkb indicators is held in the +<structfield>indicators</structfield> +field of the complete keyboard description (see <xref linkend="Complete_Keyboard_Description" />), which is defined as follows: -</para> -<para><programlisting> +<programlisting> #define XkbNumIndicators 32 -</programlisting></para> -<para><programlisting> + typedef struct { - unsigned long phys_indicators; /* LEDs existence */ - XkbIndicatorMapRec maps[XkbNumIndicators]; /* indicator maps */ -} <emphasis>XkbIndicatorRec</emphasis>,*XkbIndicatorPtr; + unsigned long phys_indicators; /* LEDs existence */ + XkbIndicatorMapRec maps[XkbNumIndicators]; /* indicator maps */ +} <structname>XkbIndicatorRec</structname>, *XkbIndicatorPtr; </programlisting></para> <para> -This structure contains the <emphasis> -phys_indicators</emphasis> - field, which relates some information about the correspondence between +This structure contains the +<structfield>phys_indicators</structfield> +field, which relates some information about the correspondence between indicators and physical LEDs on the keyboard, and an array of indicator -<emphasis> -maps</emphasis> -, one map per indicator. +<structfield>maps</structfield>, +one map per indicator. </para> <para> -The <emphasis> -phys_indicators</emphasis> - field indicates which indicators are bound to physical LEDs on the keyboard; -if a bit is set in <emphasis> -phys_indicators</emphasis> -, then the associated indicator has a physical LED associated with it. This +The +<structfield>phys_indicators</structfield> +field indicates which indicators are bound to physical LEDs on the keyboard; +if a bit is set in +<structfield>phys_indicators</structfield>, +then the associated indicator has a physical LED associated with it. This field is necessary because some indicators may not have corresponding physical LEDs on the keyboard. For example, most keyboards have an LED for indicating -the state of <emphasis> -CapsLock</emphasis> -, but most keyboards do not have an LED that indicates the current group. -Because <emphasis> -phys_indicators</emphasis> - describes a physical characteristic of the keyboard, you cannot directly +the state of +<keycap>CapsLock</keycap>, +but most keyboards do not have an LED that indicates the current group. +Because +<structfield>phys_indicators</structfield> +describes a physical characteristic of the keyboard, you cannot directly change it under program control. However, if a client program loads a -completely new keyboard description via <emphasis> -XkbGetKeyboardByName</emphasis> -, or if a new keyboard is attached and the X implementation notices, <emphasis> -phys_indicators</emphasis> - changes if the indicators for the new keyboard are different. +completely new keyboard description via +<function>XkbGetKeyboardByName</function>, +or if a new keyboard is attached and the X implementation notices, +<structfield>phys_indicators</structfield> +changes if the indicators for the new keyboard are different. </para> @@ -132,25 +140,27 @@ phys_indicators</emphasis> <sect2 id='XkbIndicatorMapRec'> <title>XkbIndicatorMapRec</title> +<indexterm significance="preferred" zone="XkbIndicatorMapRec"> +<primary><structname>XkbIndicatorMapRec</structname></primary></indexterm> + <para> Each indicator has its own set of attributes that specify whether clients can explicitly set its state and whether it tracks the keyboard state. The -attributes of each indicator are held in the <emphasis> -maps</emphasis> - array, which is an array of <emphasis> -XkbIndicatorRec</emphasis> - structures: -</para> +attributes of each indicator are held in the +<structfield>maps</structfield> +array, which is an array of +<structname>XkbIndicatorRec</structname> +structures: -<para><programlisting> +<programlisting> typedef struct { - unsigned char flags; /* how the indicator can be changed */ - unsigned char which_groups; /* match criteria for groups */ - unsigned char groups; /* which keyboard groups the indicator watches */ - unsigned char which_mods; /* match criteria for modifiers */ - XkbModsRec mods; /* which modifiers the indicator watches */ - unsigned int ctrls; /* which controls the indicator watches */ -} <emphasis>XkbIndicatorMapRec</emphasis>, *XkbIndicatorMapPtr; + unsigned char flags; /* how the indicator can be changed */ + unsigned char which_groups; /* match criteria for groups */ + unsigned char groups; /* which keyboard groups the indicator watches */ + unsigned char which_mods; /* match criteria for modifiers */ + XkbModsRec mods; /* which modifiers the indicator watches */ + unsigned int ctrls; /* which controls the indicator watches */ +} <structname>XkbIndicatorMapRec</structname>, *XkbIndicatorMapPtr; </programlisting></para> <para> @@ -177,10 +187,10 @@ indicator <listitem> <para> The effect (if any) of attempts to explicitly change the state of the indicator -using the functions <emphasis> -XkbSetControls</emphasis> - or <emphasis> -XChangeKeyboardControl</emphasis> +using the functions +<function>XkbSetControls</function> +or +<function>XChangeKeyboardControl</function> </para> </listitem> @@ -188,22 +198,22 @@ XChangeKeyboardControl</emphasis> <para> For more information on the effects of explicit changes to indicators and the -relationship to the indicator map, see section 8.4.1. <!-- xref --> +relationship to the indicator map, see <link linkend="Effects_of_Explicit_Changes_on_Indicators">section 8.4.1</link>. </para> <sect3 id='XkbIndicatorMapRec_flags_field'> <title>XkbIndicatorMapRec flags field</title> <para> -The <emphasis> -flags</emphasis> - field specifies the conditions under which the indicator can be changed and -the effects of changing the indicator. The valid values for <emphasis> -flags</emphasis> - and their effects are shown in Table 8.1. <!-- xref --> +The +<structfield>flags</structfield> +field specifies the conditions under which the indicator can be changed and +the effects of changing the indicator. The valid values for +<structfield>flags</structfield> +and their effects are shown in <link linkend="table8.1">Table 8.1</link>. </para> -<table frame='topbot'> +<table id='table8.1' frame='topbot'> <title>XkbIndicatorMapRec flags Field</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -219,19 +229,19 @@ flags</emphasis> </thead> <tbody> <row> - <entry>XkbIM_NoExplicit</entry> + <entry><symbol>XkbIM_NoExplicit</symbol></entry> <entry>(1L<<7)</entry> <entry>Client applications cannot change the state of the indicator.</entry> </row> <row> - <entry>XkbIM_NoAutomatic</entry> + <entry><symbol>XkbIM_NoAutomatic</symbol></entry> <entry>(1L<<6)</entry> <entry>Xkb does not automatically change the value of the indicator based upon a change in the keyboard state, regardless of the values for the other fields of the indicator map.</entry> </row> <row> - <entry>XkbIM_LEDDrivesKB</entry> + <entry><symbol>XkbIM_LEDDrivesKB</symbol></entry> <entry>(1L<<5)</entry> <entry>A client application changing the state of the indicator causes the state of the keyboard to change.</entry> @@ -241,67 +251,64 @@ state of the keyboard to change.</entry> </table> <para> -Note that if <emphasis> -XkbIM_NoAutomatic</emphasis> - is not set, by default the indicator follows the keyboard state. +Note that if +<symbol>XkbIM_NoAutomatic</symbol> +is not set, by default the indicator follows the keyboard state. </para> <para> -If <emphasis> -XkbIM_LEDDrivesKB</emphasis> - is set and <emphasis> -XkbIM_NoExplicit</emphasis> - is not, and if you call a function which updates the server’s image of the -indicator map (such as <emphasis> -XkbSetIndicatorMap</emphasis> - or <emphasis> -XkbSetNamedIndicator</emphasis> -), Xkb changes the keyboard state and controls to reflect the other fields of +If +<symbol>XkbIM_LEDDrivesKB</symbol> +is set and +<symbol>XkbIM_NoExplicit</symbol> +is not, and if you call a function which updates the server’s image of the +indicator map (such as +<function>XkbSetIndicatorMap</function> +or +<function>XkbSetNamedIndicator</function>), +Xkb changes the keyboard state and controls to reflect the other fields of the indicator map, as described in the remainder of this section. If you -attempt to explicitly change the value of an indicator for which <emphasis> -XkbIM_LEDDrivesKB</emphasis> - is absent or for which <emphasis> -XkbIM_NoExplicit</emphasis> - is present, keyboard state or controls are unaffected. -</para> - - -<para> -For example, a keyboard designer may want to make the <emphasis> -CapsLock</emphasis> - LED controllable only by the server, but allow the <emphasis> -Scroll Lock</emphasis> - LED to be controlled by client applications. To do so, the keyboard designer -could set the <emphasis> -XkbIM_NoExplicit</emphasis> - flag for the <emphasis> -CapsLock</emphasis> -<emphasis> - </emphasis> -LED, but not set it for the <emphasis> -Scroll Lock</emphasis> - LED. Or the keyboard designer may wish to allow the <emphasis> -CapsLock</emphasis> - LED to be controlled by both the server and client applications and also have -the server to automatically change the <emphasis> -CapsLock</emphasis> -<emphasis> - </emphasis> -modifier state whenever a client application changes the <emphasis> -CapsLock</emphasis> - LED. To do so, the keyboard designer would not set the <emphasis> -XkbIM_NoExplicit</emphasis> - flag, but would instead set the <emphasis> -XkbIM_LEDDrivesKB</emphasis> - flag. +attempt to explicitly change the value of an indicator for which +<symbol>XkbIM_LEDDrivesKB</symbol> +is absent or for which +<symbol>XkbIM_NoExplicit</symbol> +is present, keyboard state or controls are unaffected. +</para> + + +<para> +For example, a keyboard designer may want to make the +<guilabel>CapsLock</guilabel> +LED controllable only by the server, but allow the +<guilabel>Scroll Lock</guilabel> +LED to be controlled by client applications. To do so, the keyboard designer +could set the +<symbol>XkbIM_NoExplicit</symbol> +flag for the +<guilabel>CapsLock</guilabel> +LED, but not set it for the +<guilabel>Scroll Lock</guilabel> +LED. Or the keyboard designer may wish to allow the +<guilabel>CapsLock</guilabel> +LED to be controlled by both the server and client applications and also have +the server to automatically change the +<emphasis>CapsLock</emphasis> + +modifier state whenever a client application changes the +<guilabel>CapsLock</guilabel> +LED. To do so, the keyboard designer would not set the +<symbol>XkbIM_NoExplicit</symbol> +flag, but would instead set the +<symbol>XkbIM_LEDDrivesKB</symbol> +flag. </para> <para> The remaining fields in the indicator map specify the conditions under which -Xkb automatically turns an indicator on or off (only if <emphasis> -XkbIM_NoAutomatic</emphasis> - is not set). If these conditions match the keyboard state, Xkb turns the +Xkb automatically turns an indicator on or off (only if +<symbol>XkbIM_NoAutomatic</symbol> +is not set). If these conditions match the keyboard state, Xkb turns the indicator on. If the conditions do not match, Xkb turns the indicator off. </para> @@ -311,19 +318,18 @@ indicator on. If the conditions do not match, Xkb turns the indicator off. <title>XkbIndicatorMapRec which_groups and groups fields</title> <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> +The +<structfield>which_groups</structfield> +and the +<structfield>groups</structfield> +fields of an indicator map determine how the keyboard group state affects the +corresponding indicator. The +<structfield>which_groups</structfield> +field controls the interpretation of +<structfield>groups</structfield> +and may contain any one of the following values: -<para><programlisting> +<programlisting> #define XkbIM_UseNone 0 #define XkbIM_UseBase (1L << 0) #define XkbIM_UseLatched (1L << 1) @@ -334,13 +340,12 @@ groups</emphasis> </programlisting></para> <para> -The <emphasis> -groups </emphasis> +The +<structfield>groups</structfield> field specifies what keyboard groups an indicator watches and is the bitwise inclusive OR of the following valid values: -</para> -<para><programlisting> +<programlisting> #define XkbGroup1Mask (1<<0) #define XkbGroup2Mask (1<<1) #define XkbGroup3Mask (1<<2) @@ -350,16 +355,16 @@ inclusive OR of the following valid values: </programlisting></para> <para> -If <emphasis> -XkbIM_NoAutomatic</emphasis> - is not set (the keyboard drives the indicator), the effect of <emphasis> -which_groups</emphasis> - and <emphasis> -groups</emphasis> - is shown in Table 8.2. <!-- xref --> +If +<symbol>XkbIM_NoAutomatic</symbol> +is not set (the keyboard drives the indicator), the effect of +<structfield>which_groups</structfield> +and +<structfield>groups</structfield> +is shown in <link linkend="table8.2">Table 8.2</link>. </para> -<table frame='topbot'> +<table id='table8.2' frame='topbot'> <title>XkbIndicatorMapRec which_groups and groups, Keyboard Drives Indicator</title> <?dbfo keep-together="always" ?> @@ -374,72 +379,72 @@ Indicator</title> </thead> <tbody> <row> - <entry>XkbIM_UseNone</entry> + <entry><symbol>XkbIM_UseNone</symbol></entry> <entry> -The <emphasis> -groups</emphasis> - field and the current keyboard group state are ignored. +The +<structfield>groups</structfield> +field and the current keyboard group state are ignored. </entry> </row> <row> - <entry>XkbIM_UseBase</entry> + <entry><symbol>XkbIM_UseBase</symbol></entry> <entry> -If <emphasis> -groups</emphasis> - is nonzero, the indicator is lit whenever the base keyboard group is nonzero. -If <emphasis> -groups</emphasis> - is zero, the indicator is lit whenever the base keyboard group is zero. +If +<structfield>groups</structfield> +is nonzero, the indicator is lit whenever the base keyboard group is nonzero. +If +<structfield>groups</structfield> +is zero, the indicator is lit whenever the base keyboard group is zero. </entry> </row> <row> - <entry>XkbIM_UseLatched</entry> + <entry><symbol>XkbIM_UseLatched</symbol></entry> <entry> -If <emphasis> -groups</emphasis> - is nonzero, the indicator is lit whenever the latched keyboard group is -nonzero. If <emphasis> -groups</emphasis> - is zero, the indicator is lit whenever the latched keyboard group is zero. +If +<structfield>groups</structfield> +is nonzero, the indicator is lit whenever the latched keyboard group is +nonzero. If +<structfield>groups</structfield> +is zero, the indicator is lit whenever the latched keyboard group is zero. </entry> </row> <row> - <entry>XkbIM_UseLocked</entry> + <entry><symbol>XkbIM_UseLocked</symbol></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>. +The +<structfield>groups</structfield> +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 +<structfield>groups</structfield>. </entry> </row> <row> - <entry>XkbIM_UseEffective</entry> + <entry><symbol>XkbIM_UseEffective</symbol></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> +The +<structfield>groups</structfield> +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 +<structfield>groups</structfield>. +</entry> </row> </tbody> </tgroup> </table> <para> -The effect of <emphasis> -which_groups</emphasis> - and <emphasis> -groups</emphasis> - when you change an indicator for which <emphasis> -XkbIM_LEDDrivesKB</emphasis> - is set (the indicator drives the keyboard) is shown in Table 8.3. The "New -State" column refers to the new state to which you set the indicator. +The effect of +<structfield>which_groups</structfield> +and +<structfield>groups</structfield> +when you change an indicator for which +<symbol>XkbIM_LEDDrivesKB</symbol> +is set (the indicator drives the keyboard) is shown in +<link linkend="table8.3">Table 8.3</link>. The <quote>New State</quote> +column refers to the new state to which you set the indicator. </para> -<table frame='topbot'> +<table id='table8.3' frame='topbot'> <title>XkbIndicatorMapRec which_groups and groups, Indicator Drives Keyboard</title> <?dbfo keep-together="always" ?> @@ -456,42 +461,41 @@ Keyboard</title> </thead> <tbody> <row> - <entry>XkbIM_UseNone </entry> + <entry><symbol>XkbIM_UseNone</symbol></entry> <entry>On or Off</entry> <entry>No effect</entry> </row> <row> - <entry>XkbIM_UseBase</entry> + <entry><symbol>XkbIM_UseBase</symbol></entry> <entry>On or Off</entry> <entry>No effect</entry> </row> <row> - <entry>XkbIM_UseLatched</entry> + <entry><symbol>XkbIM_UseLatched</symbol></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. +The +<structfield>groups</structfield> +field is treated as a group mask. The keyboard group latch is changed to the +lowest numbered group specified in +<structfield>groups</structfield>; +if +<structfield>groups</structfield> +is empty, the keyboard group latch is changed to zero. </entry> </row> <row> - <entry>XkbIM_UseLatched</entry> + <entry><symbol>XkbIM_UseLatched</symbol></entry> <entry>Off</entry> <entry> -The <emphasis> -groups</emphasis> - field is treated as a group mask. If the indicator is explicitly extinguished, +The +<structfield>groups</structfield> +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 +<structfield>groups</structfield>; +if +<structfield>groups</structfield> +is zero, the keyboard group latch is set to the index of the highest legal keyboard group. </entry> </row> @@ -499,11 +503,11 @@ keyboard group. <entry>XkbIM_UseLocked or XkbIM_UseEffective</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>. +If the +<structfield>groups</structfield> +mask is empty, group is not changed; otherwise, the locked keyboard group is +changed to the lowest numbered group specified in +<structfield>groups</structfield>. </entry> </row> <row> @@ -511,13 +515,13 @@ groups</emphasis>. <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. +specified in the +<structfield>groups</structfield> +mask, or to +<emphasis>Group1</emphasis> +if the +<structfield>groups</structfield> +mask contains all keyboard groups. </entry> </row> </tbody> @@ -529,66 +533,60 @@ groups</emphasis> <title>XkbIndicatorMapRec which_mods and mods fields</title> <para> -The <emphasis> -mods </emphasis> -field specifies what modifiers an indicator watches. The <emphasis> -mods</emphasis> - field is an Xkb modifier definition, <emphasis> -XkbModsRec</emphasis> -, as described in section 7.2, which can specify both real and virtual <!-- xref --> -modifiers. The <emphasis> -mods</emphasis> - field takes effect even if some or all of the virtual indicators specified in -<emphasis> -mods</emphasis> - are unbound. To specify the mods field, in general, assign the modifiers of -interest to <emphasis> -mods.real_mods</emphasis> - and the virtual modifiers of interest to <emphasis> -mods.vmods</emphasis> -. You can disregard the <emphasis> -mods.mask</emphasis> - field unless your application needs to interpret the indicator map directly +The +<structfield>mods</structfield> +field specifies what modifiers an indicator watches. The +<structfield>mods</structfield> +field is an Xkb modifier definition, +<structname>XkbModsRec</structname>, +as described in <link linkend="Modifier_Definitions">section 7.2</link>, which can specify both real and virtual +modifiers. The +<structfield>mods</structfield> +field takes effect even if some or all of the virtual indicators specified in +<structfield>mods</structfield> +are unbound. To specify the mods field, in general, assign the modifiers of +interest to +<structfield>mods.real_mods</structfield> +and the virtual modifiers of interest to +<structfield>mods.vmods</structfield>. +You can disregard the +<structfield>mods.mask</structfield> +field unless your application needs to interpret the indicator map directly (that is, to simulate automatic indicator behavior on its own). Relatively few applications need to do so, but if you find it necessary, you can either read the indicator map back from the server after you update it (the server automatically updates the mask field whenever any of the real or virtual -modifiers are changed in the modifier definition) or you can use <emphasis> -XkbVirtualModsToReal</emphasis> - to determine the proper contents for the mask field, assuming that the -<emphasis> -XkbDescRec</emphasis> - contains the virtual modifier definitions. -</para> - -<para> -<emphasis> -which_mods</emphasis> - specifies what criteria Xkb uses to determine a match with the corresponding -<emphasis> -mods</emphasis> - field by specifying one or more components of the Xkb keyboard state. If -<emphasis> -XkbIM_NoAutomatic</emphasis> - is not set (the keyboard drives the indicator), the indicator is lit whenever -any of the 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 <emphasis> -which_mods</emphasis> -. Remember that the <emphasis> -mask</emphasis> - field is comprised of all of the real modifiers specified in the definition +modifiers are changed in the modifier definition) or you can use +<function>XkbVirtualModsToReal</function> +to determine the proper contents for the mask field, assuming that the +<structname>XkbDescRec</structname> +contains the virtual modifier definitions. +</para> + +<para> +<structfield>which_mods</structfield> +specifies what criteria Xkb uses to determine a match with the corresponding +<structfield>mods</structfield> +field by specifying one or more components of the Xkb keyboard state. If +<symbol>XkbIM_NoAutomatic</symbol> +is not set (the keyboard drives the indicator), the indicator is lit whenever +any of the modifiers specified in the +<structfield>mask</structfield> +field of the +<structfield>mods</structfield> +modifier definition are also set in any of the current keyboard state +components specified by +<structfield>which_mods</structfield>. +Remember that the +<structfield>mask</structfield> +field is comprised of all of the real modifiers specified in the definition plus any real modifiers that are bound to the virtual modifiers specified in -the definition. (See Chapter 5 for more information on the keyboard state and <!-- xref --> -Chapter 7 for more information on virtual modifiers.) Use a bitwise inclusive -OR of the following values to compose a value for <emphasis> -which_mods</emphasis>: -</para> +the definition. (See <xref linkend="Keyboard_State" /> for more information on the keyboard state and +<xref linkend="Virtual_Modifiers" /> for more information on virtual modifiers.) Use a bitwise inclusive +OR of the following values to compose a value for +<structfield>which_mods</structfield>: -<para><programlisting> +<programlisting> #define XkbIM_UseNone 0 #define XkbIM_UseBase (1L << 0) #define XkbIM_UseLatched (1L << 1) @@ -601,16 +599,16 @@ which_mods</emphasis>: </programlisting></para> <para> -If <emphasis> -XkbIM_NoAutomatic</emphasis> - is not set (the keyboard drives the indicator), the effect of <emphasis> -which_mods</emphasis> - and <emphasis> -mods</emphasis> - is shown in Table 8.4 <!-- xref --> +If +<symbol>XkbIM_NoAutomatic</symbol> +is not set (the keyboard drives the indicator), the effect of +<structfield>which_mods</structfield> +and +<structfield>mods</structfield> +is shown in <link linkend="table8.4">Table 8.4</link> </para> -<table frame='topbot'> +<table id='table8.4' frame='topbot'> <title>XkbIndicatorMapRec which_mods and mods, Keyboard Drives Indicator</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -624,80 +622,80 @@ mods</emphasis> </thead> <tbody> <row> - <entry>XkbIM_UseNone</entry> + <entry><symbol>XkbIM_UseNone</symbol></entry> <entry>The mods field and the current keyboard modifier state are ignored.</entry> </row> <row> - <entry>XkbIM_UseBase</entry> + <entry><symbol>XkbIM_UseBase</symbol></entry> <entry> -The indicator is lit when any of the modifiers specified in the <emphasis> -mask</emphasis> - field of <emphasis> -mods</emphasis> - are on in the keyboard base state. If both <emphasis> -mods.real_mods</emphasis> - and <emphasis> -mods.vmods</emphasis> - are zero, the indicator is lit when the base keyboard state contains no +The indicator is lit when any of the modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are on in the keyboard base state. If both +<structfield>mods.real_mods</structfield> +and +<structfield>mods.vmods</structfield> +are zero, the indicator is lit when the base keyboard state contains no modifiers. </entry> </row> <row> - <entry>XkbIM_UseLatched</entry> + <entry><symbol>XkbIM_UseLatched</symbol></entry> <entry> -The indicator is lit when any of the modifiers specified in the <emphasis> -mask</emphasis> - field of <emphasis> -mods</emphasis> - are latched. If both <emphasis> -mods.real_mods</emphasis> - and <emphasis> -mods.vmods</emphasis> - are zero, the indicator is lit when none of the modifier keys are latched. +The indicator is lit when any of the modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are latched. If both +<structfield>mods.real_mods</structfield> +and +<structfield>mods.vmods</structfield> +are zero, the indicator is lit when none of the modifier keys are latched. </entry> </row> <row> - <entry>XkbIM_UseLocked</entry> + <entry><symbol>XkbIM_UseLocked</symbol></entry> <entry> -The indicator is lit when any of the modifiers specified in the <emphasis> -mask</emphasis> - field of <emphasis> -mods</emphasis> - are locked. If both <emphasis> -mods.real_mods</emphasis> - and <emphasis> -mods.vmods</emphasis> - are zero, the indicator is lit when none of the modifier keys are locked. +The indicator is lit when any of the modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are locked. If both +<structfield>mods.real_mods</structfield> +and +<structfield>mods.vmods</structfield> +are zero, the indicator is lit when none of the modifier keys are locked. </entry> </row> <row> - <entry>XkbIM_UseEffective</entry> + <entry><symbol>XkbIM_UseEffective</symbol></entry> <entry> -The indicator is lit when any of the modifiers specified in the <emphasis> -mask</emphasis> - field of <emphasis> -mods</emphasis> - are in the effective keyboard state. If both <emphasis> -mods.real_mods</emphasis> - and <emphasis> -mods.vmods</emphasis> - are zero, the indicator is lit when the effective keyboard state contains no +The indicator is lit when any of the modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are in the effective keyboard state. If both +<structfield>mods.real_mods</structfield> +and +<structfield>mods.vmods</structfield> +are zero, the indicator is lit when the effective keyboard state contains no modifiers. </entry> </row> <row> - <entry>XkbIM_UseCompat</entry> + <entry><symbol>XkbIM_UseCompat</symbol></entry> <entry> -The indicator is lit when any of the modifiers specified in the <emphasis> -mask</emphasis> - field of <emphasis> -mods</emphasis> - are in the keyboard compatibility state. If both <emphasis> -mods.real_mods</emphasis> - and <emphasis> -mods.vmods</emphasis> - are zero, the indicator is lit when the keyboard compatibility state contains +The indicator is lit when any of the modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are in the keyboard compatibility state. If both +<structfield>mods.real_mods</structfield> +and +<structfield>mods.vmods</structfield> +are zero, the indicator is lit when the keyboard compatibility state contains no modifiers. </entry> </row> @@ -706,17 +704,18 @@ no modifiers. </table> <para> -The effect on the keyboard modifiers of <emphasis> -which_mods</emphasis> - and <emphasis> -mods</emphasis> - when you change an indicator for which <emphasis> -XkbIM_LEDDrivesKB</emphasis> - is set (the indicator drives the keyboard) is shown in Table 8.5. The "New -State" column refers to the new state to which you set the indicator. -</para> <!-- xref --> +The effect on the keyboard modifiers of +<structfield>which_mods</structfield> +and +<structfield>mods</structfield> +when you change an indicator for which +<symbol>XkbIM_LEDDrivesKB</symbol> +is set (the indicator drives the keyboard) is shown in +<link linkend="table8.5">Table 8.5</link>. The <quote>New State</quote> +column refers to the new state to which you set the indicator. +</para> -<table frame='topbot'> +<table id='table8.5' frame='topbot'> <title>XkbIndicatorMapRec which_mods and mods, Indicator Drives Keyboard</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -737,58 +736,58 @@ State" column refers to the new state to which you set the indicator. <entry>No Effect</entry> </row> <row> - <entry>XkbIM_UseLatched</entry> + <entry><symbol>XkbIM_UseLatched</symbol></entry> <entry>On</entry> <entry> -Any modifiers specified in the <emphasis> -mask</emphasis> - field of <emphasis> -mods</emphasis> - are added to the latched modifiers. +Any modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are added to the latched modifiers. </entry> </row> <row> - <entry>XkbIM_UseLatched</entry> + <entry><symbol>XkbIM_UseLatched</symbol></entry> <entry>Off</entry> <entry> -Any modifiers specified in the <emphasis> -mask</emphasis> - field of <emphasis> -mods</emphasis> - are removed from the latched modifiers. +Any modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are removed from the latched modifiers. </entry> </row> <row> <entry>XkbIM_UseLocked, XkbIM_UseCompat, or XkbIM_UseEffective</entry> <entry>On</entry> <entry> -Any modifiers specified in the <emphasis> -mask</emphasis> - field of <emphasis> -mods</emphasis> - are added to the locked modifiers. +Any modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are added to the locked modifiers. </entry> </row> <row> - <entry>XkbIM_UseLocked</entry> + <entry><symbol>XkbIM_UseLocked</symbol></entry> <entry>Off</entry> <entry> -Any modifiers specified in the <emphasis> -mask</emphasis> - field of <emphasis> -mods</emphasis> - are removed from the locked modifiers. +Any modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are removed from the locked modifiers. </entry> </row> <row> <entry>XkbIM_UseCompat or XkbIM_UseEffective</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. +Any modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are removed from both the locked and latched modifiers. </entry> </row> </tbody> @@ -800,13 +799,12 @@ mods</emphasis> <title>XkbIndicatorMapRec ctrls field</title> <para> -The <emphasis> -ctrls</emphasis> - field specifies what controls (see Chapter 10) the indicator watches and is +The +<structfield>ctrls</structfield> +field specifies what controls (see <xref linkend="Keyboard_Controls" />) the indicator watches and is composed using the bitwise inclusive OR of the following values: -</para> <!-- xref --> -<para><programlisting> +<programlisting> #define XkbRepeatKeysMask (1L << 0) #define XkbSlowKeysMask (1L << 1) #define XkbBounceKeysMask (1L << 2) @@ -824,9 +822,8 @@ composed using the bitwise inclusive OR of the following values: <para> Xkb lights the indicator whenever any of the boolean controls specified in -<emphasis> -ctrls</emphasis> - is enabled. +<structfield>ctrls</structfield> +is enabled. </para> @@ -842,12 +839,12 @@ different methods. The first method, which is similar to the core X implementation, uses a mask to specify the indicators. The second method, which is more suitable for applications concerned with interoperability, uses indicator names. The correspondence between the indicator name and the bit -position in masks is as follows: one of the parameters returned from <emphasis> -XkbGetNamedIndicators</emphasis> - is an index that is the bit position to use in any function call that requires -a mask of indicator bits, as well as the indicator’s index into the <emphasis> -XkbIndicatorRec</emphasis> - array of indicator maps. +position in masks is as follows: one of the parameters returned from +<function>XkbGetNamedIndicator</function> +is an index that is the bit position to use in any function call that requires +a mask of indicator bits, as well as the indicator’s index into the +<structname>XkbIndicatorRec</structname> +array of indicator maps. </para> @@ -857,78 +854,79 @@ XkbIndicatorRec</emphasis> <para> Because the state of the indicators is relatively volatile, the keyboard description does not hold the current state of the indicators. To obtain the -current state of the keyboard indicators, use <emphasis> -XkbGetIndicatorState</emphasis>. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetIndicatorState</emphasis> -(<emphasis> -display</emphasis> -, <emphasis> -device_spec</emphasis> -, <emphasis> -state_return</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -display</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -state_return</emphasis> -; /* backfilled with a mask of the indicator state */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetIndicatorState</emphasis> - queries the <emphasis> -display</emphasis> - for the state of the indicators on the device specified by the <emphasis> -device_spec</emphasis> -. For each indicator that is "turned on" on the device, the associated bit is -set in <emphasis> -state_return</emphasis> -. If a compatible version of the Xkb extension is not available in the server, -<emphasis> -XkbGetIndicatorState</emphasis> - returns a <emphasis> -BadMatch</emphasis> - error. Otherwise, it sends the request to the X server, places the state of -the indicators into <emphasis> -state_return,</emphasis> - and returns <emphasis> -Success</emphasis> -. Thus the value reported by <emphasis> -XkbGetIndicatorState</emphasis> - is identical to the value reported by the core protocol. +current state of the keyboard indicators, use +<function>XkbGetIndicatorState</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetIndicatorState"><primary><function>XkbGetIndicatorState</function></primary></indexterm> +<funcsynopsis id="XkbGetIndicatorState"> + <funcprototype> + <funcdef>Status <function>XkbGetIndicatorState</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec</parameter>, +<parameter>state_return</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int *<parameter>state_return</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>state_return</parameter> + </term> + <listitem> + <para> + backfilled with a mask of the indicator state + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetIndicatorState</function> +queries the +<parameter>display</parameter> +for the state of the indicators on the device specified by the +<parameter>device_spec</parameter>. +For each indicator that is <quote>turned on</quote> on the device, +the associated bit is set in +<parameter>state_return</parameter>. +If a compatible version of the Xkb extension is not available in the server, +<function>XkbGetIndicatorState</function> +returns a +<errorname>BadMatch</errorname> +error. Otherwise, it sends the request to the X server, places the state of +the indicators into +<parameter>state_return</parameter>, +and returns +<symbol>Success</symbol>. +Thus the value reported by +<function>XkbGetIndicatorState</function> +is identical to the value reported by the core protocol. </para> @@ -938,93 +936,91 @@ XkbGetIndicatorState</emphasis> <para> To get the map for one or more indicators, using a mask to specify the -indicators, use <emphasis> -XkbGetIndicatorMap</emphasis>. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetIndicatorMap</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - which</emphasis> -,<emphasis> - desc</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -which</emphasis> -; /* mask of indicators for which maps should be returned */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -desc</emphasis> -; /* keyboard description to be updated */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetIndicatorMap</emphasis> - obtains the maps from the server for only those indicators specified by the -<emphasis> -which</emphasis> - mask and copies the values into the keyboard description specified by -<emphasis> -desc</emphasis> -. If the <emphasis> -indicators</emphasis> - field of the <emphasis> -desc</emphasis> - parameter is <emphasis> -NULL</emphasis> -, <emphasis> -XkbGetIndicatorMap</emphasis> - allocates and initializes it. -</para> - - -<para> -<emphasis> -XkbGetIndicatorMap</emphasis> - can generate <emphasis> -BadAlloc</emphasis> -, <emphasis> -BadLength</emphasis> -, <emphasis> -BadMatch</emphasis> -, and <emphasis> -BadImplementation</emphasis> - errors. -</para> - - -<para> -To free the indicator maps, use <emphasis> -XkbFreeIndicatorMaps</emphasis> - (see section 8.6). +indicators, use +<function>XkbGetIndicatorMap</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetIndicatorMap"><primary><function>XkbGetIndicatorMap</function></primary></indexterm> +<funcsynopsis id="XkbGetIndicatorMap"> + <funcprototype> + <funcdef>Status <function>XkbGetIndicatorMap</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>which</parameter>, +<parameter>desc</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>desc</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of indicators for which maps should be returned + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>desc</parameter> + </term> + <listitem> + <para> + keyboard description to be updated + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetIndicatorMap</function> +obtains the maps from the server for only those indicators specified by the +<parameter>which</parameter> +mask and copies the values into the keyboard description specified by +<parameter>desc</parameter>. +If the +<structfield>indicators</structfield> +field of the +<parameter>desc</parameter> +parameter is +<symbol>NULL</symbol>, +<function>XkbGetIndicatorMap</function> +allocates and initializes it. +</para> + + +<para> +<function>XkbGetIndicatorMap</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadLength</errorname>, +<errorname>BadMatch</errorname>, +and +<errorname>BadImplementation</errorname> +errors. +</para> + + +<para> +To free the indicator maps, use +<function>XkbFreeIndicatorMaps</function> +(see <link linkend="Allocating_and_Freeing_Indicator_Maps">section 8.6</link>). </para> @@ -1033,169 +1029,175 @@ XkbFreeIndicatorMaps</emphasis> <title>Getting Indicator Information by Name</title> <para> -Xkb also allows applications to refer to indicators by name. Use <emphasis> -XkbGetNames</emphasis> - to get the indicator names (see Chapter 18). Using names eliminates the need +Xkb also allows applications to refer to indicators by name. Use +<function>XkbGetNames</function> +to get the indicator names (see <xref linkend="Symbolic_Names" />). Using names eliminates the need for hard-coding bitmask values for particular keyboards. For example, instead -of using vendor-specific constants such as <emphasis> -WSKBLed_ScrollLock</emphasis> - mask on Digital workstations or <emphasis> -XLED_SCROLL_LOCK</emphasis> - on Sun workstations, you can instead use <emphasis> -XkbGetNamedIndicator</emphasis> - to look up information on the indicator named "Scroll Lock." -</para> - -<para> -Use <emphasis> -XkbGetNamedIndicator</emphasis> - to look up the indicator map and other information for an indicator by name. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbGetNamedIndicator</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - dev_spec</emphasis> -,<emphasis> - name</emphasis> -,<emphasis> - ndx_rtrn</emphasis> -,<emphasis> - state_rtrn</emphasis> -,<emphasis> - map_rtrn</emphasis> -, <emphasis> -real_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - device_spec</emphasis> -; /* keyboard device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Atom <emphasis> - name</emphasis> -; /* name of the indicator to be retrieved */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int * <emphasis> -ndx_rtrn</emphasis> -; /* backfilled with the index of the retrieved indicator */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool * <emphasis> -state_rtrn</emphasis> -; /* backfilled with the current state of the retrieved indicator */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbIndicatorMapPtr <emphasis> - map_rtrn</emphasis> -; /* backfilled with the mapping for the retrieved indicator */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool * <emphasis> -real_rtrn</emphasis> -; /* backfilled with <emphasis> -True</emphasis> - if the named indicator is real (physical) */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -If the device specified by <emphasis> -device_spec</emphasis> - has an indicator named <emphasis> -name</emphasis> -,<emphasis> - XkbGetNamedIndicator</emphasis> - returns <emphasis> -True</emphasis> - and populates the rest of the parameters with information about the indicator. -Otherwise, <emphasis> -XkbGetNamedIndicator</emphasis> - returns <emphasis> -False</emphasis> -. -</para> - - -<para> -The <emphasis> -ndx_rtrn</emphasis> - field returns the zero-based index of the named indicator. This index is the +of using vendor-specific constants such as +<symbol>WSKBLed_ScrollLock</symbol> +mask on Digital workstations or +<symbol>XLED_SCROLL_LOCK</symbol> +on Sun workstations, you can instead use +<function>XkbGetNamedIndicator</function> +to look up information on the indicator named <quote>Scroll Lock.</quote> +</para> + +<para> +Use +<function>XkbGetNamedIndicator</function> +to look up the indicator map and other information for an indicator by name. +</para> + +<indexterm significance="preferred" zone="XkbGetNamedIndicator"><primary><function>XkbGetNamedIndicator</function></primary></indexterm> +<funcsynopsis id="XkbGetNamedIndicator"> + <funcprototype> + <funcdef>Bool <function>XkbGetNamedIndicator</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>dev_spec</parameter>, +<parameter>name</parameter>, +<parameter>ndx_rtrn</parameter>, +<parameter>state_rtrn</parameter>, +<parameter>map_rtrn</parameter>, +<parameter>real_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>Atom <parameter>name</parameter></paramdef> + <paramdef>int *<parameter>ndx_rtrn</parameter></paramdef> + <paramdef>Bool *<parameter>state_rtrn</parameter></paramdef> + <paramdef>XkbIndicatorMapPtr <parameter>map_rtrn</parameter></paramdef> + <paramdef>Bool *<parameter>real_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + keyboard device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>name</parameter> + </term> + <listitem> + <para> + name of the indicator to be retrieved + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ndx_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with the index of the retrieved indicator + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>state_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with the current state of the retrieved indicator + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>map_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with the mapping for the retrieved indicator + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>real_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with <symbol>True</symbol> + if the named indicator is real (physical) + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If the device specified by +<parameter>device_spec</parameter> +has an indicator named +<parameter>name</parameter>, +<function>XkbGetNamedIndicator</function> +returns +<symbol>True</symbol> +and populates the rest of the parameters with information about the indicator. +Otherwise, +<function>XkbGetNamedIndicator</function> +returns +<symbol>False</symbol>. +</para> + + +<para> +The +<parameter>ndx_rtrn</parameter> +field returns the zero-based index of the named indicator. This index is the bit position to use in any function call that requires a mask of indicator -bits, as well as the indicator’s index into the <emphasis> -XkbIndicatorRec</emphasis> - array of indicator maps. <emphasis> -state_rtrn</emphasis> - returns the current state of the named indicator (<emphasis> -True</emphasis> - = on, <emphasis> -False</emphasis> - = off). <emphasis> -map_rtrn</emphasis> - returns the indicator map for the named indicator. In addition, if the -indicator is mapped to a physical LED, the <emphasis> -real_rtrn</emphasis> - parameter is set to <emphasis> -True</emphasis> -. +bits, as well as the indicator’s index into the +<structname>XkbIndicatorRec</structname> +array of indicator maps. +<parameter>state_rtrn</parameter> +returns the current state of the named indicator +(<symbol>True</symbol> += on, +<symbol>False</symbol> += off). +<parameter>map_rtrn</parameter> +returns the indicator map for the named indicator. In addition, if the +indicator is mapped to a physical LED, the +<parameter>real_rtrn</parameter> +parameter is set to +<symbol>True</symbol>. </para> <para> -Each of the "<emphasis> -_rtrn</emphasis> -" arguments is optional; you can pass <emphasis> -NULL</emphasis> - for any unneeded "<emphasis> -_rtrn</emphasis> -" arguments. +Each of the "<parameter>_rtrn</parameter>" arguments is optional; you can pass +<symbol>NULL</symbol> +for any unneeded "<parameter>_rtrn</parameter>" arguments. </para> <para> -<emphasis> -XkbGetNamedIndicator</emphasis> - can generate <emphasis> -BadAtom</emphasis> - and <emphasis> -BadImplementation</emphasis> - errors. +<function>XkbGetNamedIndicator</function> +can generate +<errorname>BadAtom</errorname> +and +<errorname>BadImplementation</errorname> +errors. </para> @@ -1209,22 +1211,22 @@ Just as you can get the indicator map using a mask or using an indicator name, so you can change it using a mask or a name. </para> -<note><para>You cannot change the <emphasis> -phys_indicators</emphasis> - field of the indicators structure. The only way to change the <emphasis> -phys_indicators</emphasis> - field is to change the keyboard map.</para></note> +<note><para>You cannot change the +<structfield>phys_indicators</structfield> +field of the indicators structure. The only way to change the +<structfield>phys_indicators</structfield> +field is to change the keyboard map.</para></note> <para> There are two ways to make changes to indicator maps and state: either change a -local copy of the indicator maps and use <emphasis> -XkbSetIndicatorMap</emphasis> - or <emphasis> -XkbSetNamedIndicator</emphasis> -, or, to reduce network traffic, use an<emphasis> - XkbIndicatorChangesRec</emphasis> - structure and use <emphasis> -XkbChangeIndicators</emphasis>. +local copy of the indicator maps and use +<function>XkbSetIndicatorMap</function> +or +<function>XkbSetNamedIndicator</function>, +or, to reduce network traffic, use an +<structname>XkbIndicatorChangesRec</structname> +structure and use +<function>XkbChangeIndicators</function>. </para> @@ -1233,38 +1235,40 @@ XkbChangeIndicators</emphasis>. <para> This section discusses the effects of explicitly changing indicators depending -upon different settings in the indicator map. See Tables 8.3 and Table 8.5 for +upon different settings in the indicator map. See +<link linkend="table8.3">Table 8.3</link> and +<link linkend="table8.5">Table 8.5</link> for information on the effects of the indicator map fields when explicit changes are made. </para> <para> -If <emphasis> -XkbIM_LEDDrivesKB</emphasis> - is set and <emphasis> -XkbIM_NoExplicit</emphasis> - is not, and if you call a function that updates the server’s image of the -indicator map (such as <emphasis> -XkbSetIndicatorMap</emphasis> - or <emphasis> -XkbSetNamedIndicator</emphasis> -), Xkb changes the keyboard state and controls to reflect the other fields of +If +<symbol>XkbIM_LEDDrivesKB</symbol> +is set and +<symbol>XkbIM_NoExplicit</symbol> +is not, and if you call a function that updates the server’s image of the +indicator map (such as +<function>XkbSetIndicatorMap</function> +or +<function>XkbSetNamedIndicator</function>), +Xkb changes the keyboard state and controls to reflect the other fields of the indicator map. If you attempt to explicitly change the value of an -indicator for which <emphasis> -XkbIM_LEDDrivesKB</emphasis> - is absent or for which <emphasis> -XkbIM_NoExplicit</emphasis> - is present, keyboard state or controls are unaffected. +indicator for which +<symbol>XkbIM_LEDDrivesKB</symbol> +is absent or for which +<symbol>XkbIM_NoExplicit</symbol> +is present, keyboard state or controls are unaffected. </para> <para> -If neither <emphasis> -XkbIM_NoAutomatic</emphasis> - nor <emphasis> -XkbIM_NoExplicit</emphasis> - is set in an indicator map, Xkb honors any request to change the state of the +If neither +<symbol>XkbIM_NoAutomatic</symbol> +nor +<symbol>XkbIM_NoExplicit</symbol> +is set in an indicator map, Xkb honors any request to change the state of the indicator, but the new state might be immediately superseded by automatic changes to the indicator state if the keyboard state or controls change. </para> @@ -1278,11 +1282,11 @@ controls simultaneously. <para> -If you change an indicator for which both the <emphasis> -XkbIM_LEDDrivesKB</emphasis> - and <emphasis> -XkbIM_NoAutomatic</emphasis> - flags are specified, Xkb applies the keyboard changes specified in the other +If you change an indicator for which both the +<symbol>XkbIM_LEDDrivesKB</symbol> +and +<symbol>XkbIM_NoAutomatic</symbol> +flags are specified, Xkb applies the keyboard changes specified in the other indicator map fields and changes the indicator to reflect the state that was explicitly requested. The indicator remains in the new state until it is explicitly changed again. @@ -1290,38 +1294,37 @@ explicitly changed again. <para> -If the <emphasis> -XkbIM_NoAutomatic</emphasis> - flag is not set and <emphasis> -XkbIM_LEDDrivesKB</emphasis> - is set, Xkb applies the changes specified in the other indicator map fields +If the +<symbol>XkbIM_NoAutomatic</symbol> +flag is not set and +<symbol>XkbIM_LEDDrivesKB</symbol> +is set, Xkb applies the changes specified in the other indicator map fields and sets the state of the indicator to the values specified by the indicator map. Note that it is possible in this case for the indicator to end up in a different state than the one that was explicitly requested. For example, Xkb -does not extinguish an indicator with <emphasis> -which_mods</emphasis> - of <emphasis> -XkbIM_UseBase</emphasis> - and <emphasis> -mods</emphasis> - of <emphasis> -Shift</emphasis> - if, at the time Xkb processes the request to extinguish the indicator, one of -the <emphasis> -Shift</emphasis> - keys is physically depressed. +does not extinguish an indicator with +<structfield>which_mods</structfield> +of +<symbol>XkbIM_UseBase</symbol> +and +<structfield>mods</structfield> +of +<symbol>Shift</symbol> +if, at the time Xkb processes the request to extinguish the indicator, one of +the +<symbol>Shift</symbol> +keys is physically depressed. </para> <para> -If you explicitly light an indicator for which <emphasis> -XkbIM_LEDDrivesKB</emphasis> - is set, Xkb enables all of the boolean controls specified in the <emphasis> -ctrls</emphasis> - field of its indicator map. Explicitly extinguishing such an indicator causes -Xkb to disable all of the boolean controls specified in <emphasis> -ctrls</emphasis> -. +If you explicitly light an indicator for which +<symbol>XkbIM_LEDDrivesKB</symbol> +is set, Xkb enables all of the boolean controls specified in the +<structfield>ctrls</structfield> +field of its indicator map. Explicitly extinguishing such an indicator causes +Xkb to disable all of the boolean controls specified in +<structfield>ctrls</structfield>. </para> @@ -1331,64 +1334,68 @@ ctrls</emphasis> <para> To update the maps for one or more indicators, first modify a local copy of the -keyboard description, then use <emphasis> -XkbSetIndicatorMap</emphasis> - to download the changes to the server: -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool<emphasis> - XkbSetIndicatorMap</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - which</emphasis> -,<emphasis> - desc</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -which</emphasis> -; /* mask of indicators to change */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -desc</emphasis> -; /* keyboard description from which the maps are taken */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -For each<emphasis> - </emphasis> -bit set in the <emphasis> -which </emphasis> -parameter,<emphasis> - XkbSetIndicatorMap</emphasis> - sends the corresponding indicator map from the <emphasis> -desc</emphasis> - parameter to the server. +keyboard description, then use +<function>XkbSetIndicatorMap</function> +to download the changes to the server: +</para> + +<indexterm significance="preferred" zone="XkbSetIndicatorMap"><primary><function>XkbSetIndicatorMap</function></primary></indexterm> +<funcsynopsis id="XkbSetIndicatorMap"> + <funcprototype> + <funcdef>Bool <function>XkbSetIndicatorMap</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>which</parameter>, +<parameter>desc</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>desc</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of indicators to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>desc</parameter> + </term> + <listitem> + <para> + keyboard description from which the maps are taken + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +For each +bit set in the +<parameter>which</parameter> +parameter, +<function>XkbSetIndicatorMap</function> +sends the corresponding indicator map from the +<parameter>desc</parameter> +parameter to the server. </para> @@ -1397,9 +1404,8 @@ desc</emphasis> <title>Changing Indicator Maps by Name</title> <para> -<emphasis> -XkbSetNamedIndicator</emphasis> - can do several related things: +<function>XkbSetNamedIndicator</function> +can do several related things: </para> <itemizedlist> @@ -1425,295 +1431,298 @@ Set the indicator map for the indicator </listitem> </itemizedlist> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool<emphasis> - XkbSetNamedIndicator</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - device_spec</emphasis> -,<emphasis> - name</emphasis> -,<emphasis> - change_state, state</emphasis> -,<emphasis> - create_new</emphasis> -,<emphasis> - map</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> - dpy</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Atom <emphasis> - name</emphasis> -; /* name of the indicator to change */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - change_state</emphasis> -; /* whether to change the indicator state or not */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - state</emphasis> -; /* desired new state for the indicator */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> -create_new</emphasis> -; /* whether a new indicator with the specified name should be -created when necessary */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbIndicatorMapPtr <emphasis> -map</emphasis> -; /* new map for the indicator */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbSetNamedIndicator"><primary><function>XkbSetNamedIndicator</function></primary></indexterm> +<funcsynopsis id="XkbSetNamedIndicator"> + <funcprototype> + <funcdef>Bool<function>XkbSetNamedIndicator</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>device_spec</parameter>, +<parameter>name</parameter>, +<parameter>change_state, state</parameter>, +<parameter>create_new</parameter>, +<parameter>map</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>Atom <parameter>name</parameter></paramdef> + <paramdef>Bool <parameter>change_state</parameter></paramdef> + <paramdef>Bool <parameter>state</parameter></paramdef> + <paramdef>Bool <parameter>create_new</parameter></paramdef> + <paramdef>XkbIndicatorMapPtr <parameter>map</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>name</parameter> + </term> + <listitem> + <para> + name of the indicator to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>change_state</parameter> + </term> + <listitem> + <para> + whether to change the indicator state or not + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>state</parameter> + </term> + <listitem> + <para> + desired new state for the indicator + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>create_new</parameter> + </term> + <listitem> + <para> + whether a new indicator with the specified name should be + created when necessary + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>map</parameter> + </term> + <listitem> + <para> + new map for the indicator + </para> + </listitem> + </varlistentry> +</variablelist> <para> If a compatible version of the Xkb extension is not available in the server, -<emphasis> -XkbSetNamedIndicator</emphasis> - returns <emphasis> -False</emphasis> -. Otherwise, it sends a request to the X server to change the indicator -specified by <emphasis> -name</emphasis> - and returns <emphasis> -True</emphasis>. +<function>XkbSetNamedIndicator</function> +returns +<symbol>False</symbol>. +Otherwise, it sends a request to the X server to change the indicator +specified by +<parameter>name</parameter> +and returns +<symbol>True</symbol>. </para> <para> -If <emphasis> -change_state</emphasis> - is <emphasis> -True</emphasis> -, and the optional parameter, <emphasis> -state</emphasis> -, is not <emphasis> -NULL</emphasis> -, <emphasis> -XkbSetNamedIndicator</emphasis> - tells the server to change the state of the named indicator to the value -specified by <emphasis> -state</emphasis>. +If +<parameter>change_state</parameter> +is +<symbol>True</symbol>, +and the optional parameter, +<parameter>state</parameter>, +is not +<symbol>NULL</symbol>, +<function>XkbSetNamedIndicator</function> +tells the server to change the state of the named indicator to the value +specified by +<parameter>state</parameter>. </para> <para> -If an indicator with the name specified by <emphasis> -name</emphasis> - does not already exist, the <emphasis> -create_new</emphasis> - parameter tells the server whether it should create a new named indicator. If -<emphasis> -create_new</emphasis> - is <emphasis> -True</emphasis> -, the server finds the first indicator that doesn’t have a name and gives it -the name specified by <emphasis> -name</emphasis>. +If an indicator with the name specified by +<parameter>name</parameter> +does not already exist, the +<parameter>create_new</parameter> +parameter tells the server whether it should create a new named indicator. If +<parameter>create_new</parameter> +is +<symbol>True</symbol>, +the server finds the first indicator that doesn’t have a name and gives it +the name specified by +<parameter>name</parameter>. </para> <para> -If the optional parameter, <emphasis> -map</emphasis> -, is not <emphasis> -NULL</emphasis> -, <emphasis> -XkbSetNamedIndicator</emphasis> - tells the server to change the indicator’s map to the values specified -in <emphasis>map</emphasis>. +If the optional parameter, +<parameter>map</parameter>, +is not +<symbol>NULL</symbol>, +<function>XkbSetNamedIndicator</function> +tells the server to change the indicator’s map to the values specified +in <parameter>map</parameter>. </para> <para> -<emphasis> -XkbSetNamedIndicator</emphasis> - can generate <emphasis> -BadAtom</emphasis> - and <emphasis> -BadImplementation</emphasis> - errors. In addition, it can also generate <emphasis> -XkbIndicatorStateNotify</emphasis> - (see section 8.5), <emphasis> <!-- xref --> -XkbIndicatorMapNotify</emphasis> -, and <emphasis> -XkbNamesNotify</emphasis> - events (see section 18.5). <!-- xref --> +<function>XkbSetNamedIndicator</function> +can generate +<errorname>BadAtom</errorname> +and +<errorname>BadImplementation</errorname> +errors. In addition, it can also generate +<symbol>XkbIndicatorStateNotify</symbol> +(see <link linkend="Tracking_Changes_to_Indicator_State_or_Map">section 8.5</link>), +<symbol>XkbIndicatorMapNotify</symbol>, +and +<symbol>XkbNamesNotify</symbol> +events (see <link linkend="Tracking_Name_Changes">section 18.5</link>). </para> </sect2> -<sect2 id='The_XkbIndicatorChangesRec_Structure'> +<sect2 id='XkbIndicatorChangesRec'> <title>The XkbIndicatorChangesRec Structure</title> +<indexterm significance="preferred" zone="XkbIndicatorChangesRec"> +<primary><structname>XkbIndicatorChangesRec</structname></primary></indexterm> + <para> -The <emphasis> -XkbIndicatorChangesRec</emphasis> - identifies small modifications to the indicator map. Use it with the function -<emphasis> -XkbChangeIndicators</emphasis> - to reduce the amount of traffic sent to the server. +The +<structname>XkbIndicatorChangesRec</structname> +identifies small modifications to the indicator map. Use it with the function +<function>XkbChangeIndicators</function> +to reduce the amount of traffic sent to the server. </para> <para><programlisting> typedef struct _XkbIndicatorChanges { - unsigned int state_changes; - unsigned int map_changes; -}<emphasis> -XkbIndicatorChangesRec</emphasis>,*XkbIndicatorChangesPtr; + unsigned int state_changes; + unsigned int map_changes; +} <structname>XkbIndicatorChangesRec</structname>,*XkbIndicatorChangesPtr; </programlisting></para> <para> -The <emphasis> -state_changes</emphasis> - field is a mask that specifies the indicators that have changed state, and -<emphasis> -map_changes</emphasis> - is a mask that specifies the indicators whose maps have changed. +The +<structfield>state_changes</structfield> +field is a mask that specifies the indicators that have changed state, and +<structfield>map_changes</structfield> +is a mask that specifies the indicators whose maps have changed. </para> <para> To change indicator maps or state without passing the entire keyboard -description, use <emphasis> -XkbChangeIndicators</emphasis> -. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbChangeIndicators</emphasis> -(<emphasis> -dpy, xkb, changes, state</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description from which names are to be - </entry> - </row> - <row> - <entry role='functionargdecl'> - taken. */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbIndicatorChangesPtr <emphasis> -changes</emphasis> -; /* indicators to be updated on the server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -state</emphasis> -; /* new state of indicators listed in - </entry> - </row> - <row> - <entry role='functionargdecl'> -<emphasis> - changes</emphasis> --><emphasis> -state_changes</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbChangeIndicators</emphasis> - copies any maps specified by <emphasis> -changes</emphasis> - from the keyboard description, <emphasis> -xkb</emphasis> -, to the server specified by <emphasis> -dpy</emphasis> -. If any bits are set in the <emphasis> -state_changes</emphasis> - field of <emphasis> -changes</emphasis> -, <emphasis> -XkbChangeIndicators</emphasis> - also sets the state of those indicators to the values specified in the -<emphasis> -state</emphasis> - mask. A 1 bit in <emphasis> -state</emphasis> - turns the corresponding indicator on, a 0 bit turns it off. -</para> - - -<para> -<emphasis> -XkbChangeIndicator</emphasis> -s can generate <emphasis> -BadAtom</emphasis> - and <emphasis> -BadImplementation</emphasis> - errors. In addition, it can also generate <emphasis> -XkbIndicatorStateNotify</emphasis> - and <emphasis> -XkbIndicatorMapNotify</emphasis> - events (see section 8.5). <!-- xref --> +description, use +<function>XkbChangeIndicators</function>. +</para> + +<indexterm significance="preferred" zone="XkbChangeIndicators"><primary><function>XkbChangeIndicators</function></primary></indexterm> +<funcsynopsis id="XkbChangeIndicators"> + <funcprototype> + <funcdef>Bool <function>XkbChangeIndicators</function></funcdef> +<!-- ( +<parameter>dpy, xkb, changes, state</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>XkbIndicatorChangesPtr <parameter>changes</parameter></paramdef> + <paramdef>unsigned int <parameter>state</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description from which names are to be taken. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + indicators to be updated on the server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>state</parameter> + </term> + <listitem> + <para> + new state of indicators listed in <parameter>changes</parameter>-><structfield>state_changes</structfield> + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbChangeIndicators</function> +copies any maps specified by +<parameter>changes</parameter> +from the keyboard description, +<parameter>xkb</parameter>, +to the server specified by +<parameter>dpy</parameter>. +If any bits are set in the +<structfield>state_changes</structfield> +field of +<parameter>changes</parameter>, +<function>XkbChangeIndicators</function> +also sets the state of those indicators to the values specified in the +<parameter>state</parameter> +mask. A 1 bit in +<parameter>state</parameter> +turns the corresponding indicator on, a 0 bit turns it off. +</para> + + +<para> +<function>XkbChangeIndicators</function> +can generate +<errorname>BadAtom</errorname> +and +<errorname>BadImplementation</errorname> +errors. In addition, it can also generate +<symbol>XkbIndicatorStateNotify</symbol> +and +<symbol>XkbIndicatorMapNotify</symbol> +events (see <link linkend="Tracking_Changes_to_Indicator_State_or_Map">section 8.5</link>). </para> @@ -1722,280 +1731,292 @@ XkbIndicatorMapNotify</emphasis> <sect1 id='Tracking_Changes_to_Indicator_State_or_Map'> <title>Tracking Changes to Indicator State or Map</title> -<para> -Whenever an indicator changes state, the server sends <emphasis> -XkbIndicatorStateNotify</emphasis> - events to all interested clients. Similarly, whenever an indicator’s map -changes, the server sends <emphasis> -XkbIndicatorMapNotify</emphasis> - events to all interested clients. -</para> - - -<para> -To receive <emphasis> -XkbIndicatorStateNotify</emphasis> - events, use <emphasis> -XkbSelectEvents</emphasis> - (see section 4.3) with both the <emphasis> <!-- xref --> -bits_to_change </emphasis> -and<emphasis> - values_for_bits</emphasis> - parameters containing <emphasis> -XkbIndicatorStateNotifyMask</emphasis> -. To receive <emphasis> -XkbIndicatorMapNotify</emphasis> - events, use <emphasis> -XkbSelectEvents</emphasis> - with <emphasis> -XkbIndicatorMapNotifyMask</emphasis> -. -</para> - - -<para> -To receive events for only specific indicators, use <emphasis> -XkbSelectEventDetails</emphasis> -. Set the <emphasis> -event_type</emphasis> - parameter<emphasis> - to XkbIndicatorStateNotify</emphasis> - or <emphasis> -XkbIndicatorMapNotify</emphasis> -, and set both the <emphasis> -bits_to_change </emphasis> -and<emphasis> - values_for_bits</emphasis> - detail parameters to a mask where each bit specifies one indicator, turning on +<indexterm significance="preferred" zone="Tracking_Changes_to_Indicator_State_or_Map"> +<primary>events</primary><secondary><symbol>XkbIndicatorStateNotify</symbol></secondary></indexterm> +<indexterm significance="preferred" zone="Tracking_Changes_to_Indicator_State_or_Map"> +<primary><structname>XkbIndicatorStateNotifyEvent</structname></primary></indexterm> + +<indexterm significance="preferred" zone="Tracking_Changes_to_Indicator_State_or_Map"> +<primary>events</primary><secondary><symbol>XkbIndicatorMapNotify</symbol></secondary></indexterm> +<indexterm significance="preferred" zone="Tracking_Changes_to_Indicator_State_or_Map"> +<primary><structname>XkbIndicatorMapNotifyEvent</structname></primary></indexterm> + +<para> +Whenever an indicator changes state, the server sends +<symbol>XkbIndicatorStateNotify</symbol> +events to all interested clients. Similarly, whenever an indicator’s map +changes, the server sends +<symbol>XkbIndicatorMapNotify</symbol> +events to all interested clients. +</para> + + +<para> +To receive +<symbol>XkbIndicatorStateNotify</symbol> +events, use +<function>XkbSelectEvents</function> +(see <link linkend="Selecting_Xkb_Events">section 4.3</link>) with both the +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +parameters containing +<symbol>XkbIndicatorStateNotifyMask</symbol>. +To receive +<symbol>XkbIndicatorMapNotify</symbol> +events, use +<function>XkbSelectEvents</function> +with +<symbol>XkbIndicatorMapNotifyMask</symbol>. +</para> + + +<para> +To receive events for only specific indicators, use +<function>XkbSelectEventDetails</function>. +Set the +<structfield>event_type</structfield> +parameter to +<symbol>XkbIndicatorStateNotify</symbol> +or +<symbol>XkbIndicatorMapNotify</symbol>, +and set both the +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +detail parameters to a mask where each bit specifies one indicator, turning on those bits that specify the indicators for which you want to receive events. </para> <para> Both types of indicator events use the same structure: -</para> -<para><programlisting> +<programlisting> typedef struct _XkbIndicatorNotify { - int type; /* Xkb extension base event code */ - unsigned long serial; /* X server serial number for event */ - Bool send_event; /* <emphasis> True</emphasis> => synthetically generated */ - Display * display; /* server connection where event generated */ - Time time; /* server time when event generated */ - int xkb_type; /* specifies state or map notify */ - int device; /* Xkb device ID, will not be <emphasis> XkbUseCoreKbd</emphasis> */ - unsigned int changed; /* mask of indicators with new state or map */ - unsigned int state; /* current state of all indicators */ -} <emphasis>XkbIndicatorNotifyEvent</emphasis>; + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* <symbol>True</symbol> ⇒ synthetically generated */ + Display * display; /* server connection where event generated */ + Time time; /* server time when event generated */ + int xkb_type; /* specifies state or map notify */ + int device; /* Xkb device ID, will not be <symbol>XkbUseCoreKbd</symbol> */ + unsigned int changed; /* mask of indicators with new state or map */ + unsigned int state; /* current state of all indicators */ +} <structname>XkbIndicatorNotifyEvent</structname>; </programlisting></para> <para> -<emphasis> -xkb_type</emphasis> - is either <emphasis> -XkbIndicatorStateNotify</emphasis> - or <emphasis> -XkbIndicatorMapNotify</emphasis> -, depending on whether the event is a <emphasis> -kbIndicatorStateNotify</emphasis> - event or <emphasis> -kbIndicatorMapNotify</emphasis> - event. -</para> - -<para> -The <emphasis> -changed</emphasis> - parameter is a mask that is the bitwise inclusive OR of the indicators that -have changed. If the event is of type <emphasis> -XkbIndicatorMapNotify</emphasis> -, <emphasis> -changed</emphasis> - reports the maps that changed. If the event is of type <emphasis> -XkbIndicatorStateNotify</emphasis> -, <emphasis> -changed</emphasis> - reports the indicators that have changed state. <emphasis> -state</emphasis> - is a mask that specifies the current state of all indicators, whether they -have changed or not, for both <emphasis> -XkbIndicatorStateNotify</emphasis> - and <emphasis>IndicatorMapNotify</emphasis> events. -</para> - -<para> -When your client application receives either a <emphasis> -XkbIndicatorStateNotify</emphasis> - event or <emphasis> -XkbIndicatorMapNotify</emphasis> - event, you can note the changes in a changes structure by calling <emphasis> -XkbNoteIndicatorChanges</emphasis>. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbNoteIndicatorChanges</emphasis> -(<emphasis> -old</emphasis> -,<emphasis> - new</emphasis> -,<emphasis> - wanted</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbIndicatorChangesPtr <emphasis> - old</emphasis> -; /* XkbIndicatorChanges structure to be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbIndicatorNotifyEvent * <emphasis> -new</emphasis> -; /* event from which changes are to be copied */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - wanted</emphasis> -; /* which changes are to be noted */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -The <emphasis> -wanted</emphasis> - parameter is the bitwise inclusive OR of <emphasis> -XkbIndicatorMapMask</emphasis> - and <emphasis> -XkbIndicatorStateMask</emphasis> -. <emphasis> -XkbNoteIndicatorChanges</emphasis> - copies any changes reported in <emphasis> -new</emphasis> - and specified in <emphasis> -wanted</emphasis> - into the changes record specified by <emphasis> -old</emphasis>. +<structfield>xkb_type</structfield> +is either +<symbol>XkbIndicatorStateNotify</symbol> +or +<symbol>XkbIndicatorMapNotify</symbol>, +depending on whether the event is a +<symbol>XkbIndicatorStateNotify</symbol> +event or +<symbol>XkbIndicatorMapNotify</symbol>, +event. +</para> + +<para> +The +<structfield>changed</structfield> +parameter is a mask that is the bitwise inclusive OR of the indicators that +have changed. If the event is of type +<symbol>XkbIndicatorMapNotify</symbol>, +<structfield>changed</structfield> +reports the maps that changed. If the event is of type +<symbol>XkbIndicatorStateNotify</symbol>, +<structfield>changed</structfield> +reports the indicators that have changed state. +<parameter>state</parameter> +is a mask that specifies the current state of all indicators, whether they +have changed or not, for both +<symbol>XkbIndicatorStateNotify</symbol> +and <symbol>XkbIndicatorMapNotify</symbol> events. +</para> + +<para> +When your client application receives either a +<symbol>XkbIndicatorStateNotify</symbol> +event or +<symbol>XkbIndicatorMapNotify</symbol> +event, you can note the changes in a changes structure by calling +<function>XkbNoteIndicatorChanges</function>. +</para> + +<indexterm significance="preferred" zone="XkbNoteIndicatorChanges"><primary><function>XkbNoteIndicatorChanges</function></primary></indexterm> +<funcsynopsis id="XkbNoteIndicatorChanges"> + <funcprototype> + <funcdef>void <function>XkbNoteIndicatorChanges</function></funcdef> +<!-- ( +<parameter>old</parameter>, +<parameter>new</parameter>, +<parameter>wanted</parameter> +) --> + + <paramdef>XkbIndicatorChangesPtr <parameter>old</parameter></paramdef> + <paramdef>XkbIndicatorNotifyEvent *<parameter>new</parameter></paramdef> + <paramdef>unsigned int <parameter>wanted</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>old</parameter> + </term> + <listitem> + <para> + XkbIndicatorChanges structure to be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>new</parameter> + </term> + <listitem> + <para> + event from which changes are to be copied + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>wanted</parameter> + </term> + <listitem> + <para> + which changes are to be noted + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<parameter>wanted</parameter> +parameter is the bitwise inclusive OR of +<symbol>XkbIndicatorMapMask</symbol> +and +<emphasis>XkbIndicatorStateMask</emphasis>. +<function>XkbNoteIndicatorChanges</function> +copies any changes reported in +<parameter>new</parameter> +and specified in +<parameter>wanted</parameter> +into the changes record specified by +<parameter>old</parameter>. </para> <para> To update a local copy of the keyboard description with the actual values, pass -the results of one or more calls to <emphasis> -XkbNoteIndicatorChanges</emphasis> - to <emphasis> -XkbGetIndicatorChanges</emphasis>: -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetIndicatorChanges</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - xkb</emphasis> -,<emphasis> - changes</emphasis> -,<emphasis> - state</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description to hold the new values */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbIndicatorChangesPtr <emphasis> -changes</emphasis> -; /* indicator maps/state to be obtained from the server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -state</emphasis> -; /* backfilled with the state of the indicators */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetIndicatorChanges</emphasis> - examines the <emphasis> -changes</emphasis> - parameter, pulls over the necessary information from the server, and copies -the results into the <emphasis> -xkb</emphasis> - keyboard description. If any bits are set in the <emphasis> -state_changes</emphasis> - field of <emphasis> -changes</emphasis> -, <emphasis> -XkbGetIndicatorChanges</emphasis> - also places the state of those indicators in <emphasis> -state</emphasis> -. If the <emphasis> -indicators</emphasis> - field of <emphasis> -xkb</emphasis> - is <emphasis> -NULL</emphasis> -, <emphasis> -XkbGetIndicatorChanges</emphasis> - allocates and initializes it. To free the <emphasis> -indicators</emphasis> - field, use <emphasis> -XkbFreeIndicators</emphasis> - (see section 8.6). <!-- xref --> -</para> - - -<para> -<emphasis> -XkbGetIndicatorChanges</emphasis> - can generate <emphasis> -BadAlloc</emphasis> -, <emphasis> -BadImplementation,</emphasis> - and <emphasis> -BadMatch</emphasis> - errors. +the results of one or more calls to +<function>XkbNoteIndicatorChanges</function> +to +<function>XkbGetIndicatorChanges</function>: +</para> + + +<indexterm significance="preferred" zone="XkbGetIndicatorChanges"><primary><function>XkbGetIndicatorChanges</function></primary></indexterm> +<funcsynopsis id="XkbGetIndicatorChanges"> + <funcprototype> + <funcdef>Status <function>XkbGetIndicatorChanges</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>xkb</parameter>, +<parameter>changes</parameter>, +<parameter>state</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>XkbIndicatorChangesPtr <parameter>changes</parameter></paramdef> + <paramdef>unsigned int *<parameter>state</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description to hold the new values + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + indicator maps/state to be obtained from the server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>state</parameter> + </term> + <listitem> + <para> + backfilled with the state of the indicators + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetIndicatorChanges</function> +examines the +<parameter>changes</parameter> +parameter, pulls over the necessary information from the server, and copies +the results into the +<parameter>xkb</parameter> +keyboard description. If any bits are set in the +<structfield>state_changes</structfield> +field of +<parameter>changes</parameter>, +<function>XkbGetIndicatorChanges</function> +also places the state of those indicators in +<parameter>state</parameter>. +If the +<structfield>indicators</structfield> +field of +<parameter>xkb</parameter> +is +<symbol>NULL</symbol>, +<function>XkbGetIndicatorChanges</function> +allocates and initializes it. To free the +<structfield>indicators</structfield> +field, use +<function>XkbFreeIndicatorMaps</function> +(see <link linkend="Allocating_and_Freeing_Indicator_Maps">section 8.6</link>). +</para> + + +<para> +<function>XkbGetIndicatorChanges</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadImplementation</errorname>, +and +<errorname>BadMatch</errorname> +errors. </para> @@ -2004,102 +2025,99 @@ BadMatch</emphasis> <title>Allocating and Freeing Indicator Maps</title> <para> -Most applications do not need to directly allocate the <emphasis> -indicators</emphasis> - member of the keyboard description record (the keyboard description record is -described in Chapter 6). If the need arises, however, use <emphasis> -XkbAllocIndicatorMaps.</emphasis> -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocIndicatorMaps</emphasis> -(<emphasis> -xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description structure */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -The <emphasis> -xkb</emphasis> - parameter must point to a valid keyboard description. If it doesn’t, -<emphasis> -XkbAllocIndicatorMaps</emphasis> - returns a <emphasis> -BadMatch</emphasis> - error. Otherwise, <emphasis> -XkbAllocIndicatorMaps</emphasis> - allocates and initializes the <emphasis> -indicators</emphasis> - member of the keyboard description record and returns <emphasis> -Success</emphasis> -. If <emphasis> -XkbAllocIndicatorMaps</emphasis> - was unable to allocate the indicators record, it reports a Bad<emphasis> -Alloc</emphasis> - error. -</para> - -<para> -To free memory used by the <emphasis> -indicators</emphasis> - member of an <emphasis> -XkbDescRec</emphasis> - structure, use <emphasis> -XkbFreeIndicatorMaps.</emphasis> -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeIndicatorMaps</emphasis> -(<emphasis> -xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description structure */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -If the <emphasis>indicators</emphasis> - member of the keyboard description record -pointed to by <emphasis>xkb</emphasis> -is not <emphasis>NULL</emphasis> -, <emphasis>XkbFreeIndicatorMaps</emphasis> +Most applications do not need to directly allocate the +<structfield>indicators</structfield> +member of the keyboard description record (the keyboard description record is +described in <xref linkend="Complete_Keyboard_Description" />). If the need arises, however, use +<function>XkbAllocIndicatorMaps</function>. +</para> + +<indexterm significance="preferred" zone="XkbAllocIndicatorMaps"><primary><function>XkbAllocIndicatorMaps</function></primary></indexterm> +<funcsynopsis id="XkbAllocIndicatorMaps"> + <funcprototype> + <funcdef>Status <function>XkbAllocIndicatorMaps</function></funcdef> +<!-- ( +<parameter>xkb</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description structure + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<parameter>xkb</parameter> +parameter must point to a valid keyboard description. If it doesn’t, +<function>XkbAllocIndicatorMaps</function> +returns a +<errorname>BadMatch</errorname> +error. Otherwise, +<function>XkbAllocIndicatorMaps</function> +allocates and initializes the +<structfield>indicators</structfield> +member of the keyboard description record and returns +<symbol>Success</symbol>. +If +<function>XkbAllocIndicatorMaps</function> +was unable to allocate the indicators record, it reports a +<errorname>BadAlloc</errorname> +error. +</para> + +<para> +To free memory used by the +<structfield>indicators</structfield> +member of an +<structname>XkbDescRec</structname> +structure, use +<function>XkbFreeIndicatorMaps</function>. +</para> + +<indexterm significance="preferred" zone="XkbFreeIndicatorMaps"><primary><function>XkbFreeIndicatorMaps</function></primary></indexterm> +<funcsynopsis id="XkbFreeIndicatorMaps"> + <funcprototype> + <funcdef>void <function>XkbFreeIndicatorMaps</function></funcdef> +<!-- ( +<parameter>xkb</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description structure + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If the <structfield>indicators</structfield> +member of the keyboard description record +pointed to by <parameter>xkb</parameter> +is not <symbol>NULL</symbol>, +<function>XkbFreeIndicatorMaps</function> frees the memory associated with -the <emphasis>indicators</emphasis> -member of <emphasis>xkb</emphasis>. +the <structfield>indicators</structfield> +member of <parameter>xkb</parameter>. </para> </sect1> diff --git a/libX11/specs/XKB/ch09.xml b/libX11/specs/XKB/ch09.xml index 3f14eed68..0241880b9 100644 --- a/libX11/specs/XKB/ch09.xml +++ b/libX11/specs/XKB/ch09.xml @@ -1,22 +1,30 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Bells'> <title>Bells</title> +<indexterm zone="Bells"><primary>bell</primary></indexterm> <para> The core X protocol allows only applications to explicitly sound the system bell with a given duration, pitch, and volume. Xkb extends this capability by allowing clients to attach symbolic names to bells, disable audible bells, and receive an event whenever the keyboard bell is rung. For the purposes of this -document, the <emphasis> -audible</emphasis> - bell is defined to be the system bell, or the default keyboard bell, as +document, the +<firstterm>audible</firstterm> +<indexterm significance="preferred" zone="Bells"> +<primary>audible bell</primary></indexterm> +<indexterm significance="preferred" zone="Bells"> +<primary>bell</primary><secondary>audible</secondary></indexterm> +bell is defined to be the system bell, or the default keyboard bell, as opposed to any other audible sound generated elsewhere in the system. </para> <para> -You can ask to receive <emphasis> -XkbBellNotify</emphasis> - events (see section 9.4) when any client rings any one of the following: <!-- xref --> +You can ask to receive +<symbol>XkbBellNotify</symbol> +events (see <link linkend="Detecting_Bells">section 9.4</link>) when any client rings any one of the following: </para> <itemizedlist> @@ -27,11 +35,11 @@ The default bell </listitem> <listitem> <para> -Any bell on an input device that can be specified by a <emphasis> -bell_class</emphasis> - and <emphasis> -bell_id</emphasis> - pair +Any bell on an input device that can be specified by a +<structfield>bell_class</structfield> +and +<structfield>bell_id</structfield> +pair </para> </listitem> <listitem> @@ -45,49 +53,49 @@ visual feedback, if any, that is associated with the name.) </itemizedlist> <para> -You can also ask to receive <emphasis> -XkbBellNotify</emphasis> - events when the server rings the default bell or if any client has requested +You can also ask to receive +<symbol>XkbBellNotify</symbol> +events when the server rings the default bell or if any client has requested events only (without the bell sounding) for any of the bell types previously listed. </para> <para> -You can disable audible bells on a global basis (to set the <emphasis> -AudibleBell</emphasis> - control, see Chapter 10). For example, a client that replaces the keyboard -bell with some other audible cue might want to turn off the <emphasis> -AudibleBell</emphasis> - control to prevent the server from also generating a sound and avoid -cacophony. If you disable audible bells and request to receive <emphasis> -XkbBellNotify</emphasis> - events, you can generate feedback different from the default bell. +You can disable audible bells on a global basis (to set the +<emphasis>AudibleBell</emphasis> +control, see <xref linkend="Keyboard_Controls" />). For example, a client that replaces the keyboard +bell with some other audible cue might want to turn off the +<emphasis>AudibleBell</emphasis> +control to prevent the server from also generating a sound and avoid +cacophony. If you disable audible bells and request to receive +<symbol>XkbBellNotify</symbol> +events, you can generate feedback different from the default bell. </para> <para> -You can, however, override the <emphasis> -AudibleBell</emphasis> - control by calling one of the functions that force the ringing of a bell in -spite of the setting of the <emphasis> -AudibleBell</emphasis> - control — <emphasis> -XkbForceDeviceBell</emphasis> - or <emphasis> -XkbForceBell</emphasis> - (see section 9.3.3). In this case the server does not generate a bell event. <!-- xref --> +You can, however, override the +<emphasis>AudibleBell</emphasis> +control by calling one of the functions that force the ringing of a bell in +spite of the setting of the +<emphasis>AudibleBell</emphasis> +control — +<function>XkbForceDeviceBell</function> +or +<function>XkbForceBell</function> +(see <link linkend="Forcing_a_Server_Generated_Bell">section 9.3.3</link>). In this case the server does not generate a bell event. </para> <para> Just as some keyboards can produce keyclicks to indicate when a key is pressed or repeating, Xkb can provide feedback for the controls by using special beep -codes. The <emphasis> -AccessXFeedback</emphasis> - control is used to configure the specific types of operations that generate -feedback. See section 10.6.3 for a discussion on <emphasis> <!-- xref --> -AccessXFeedback</emphasis> - control. +codes. The +<emphasis>AccessXFeedback</emphasis> +control is used to configure the specific types of operations that generate +feedback. See <link linkend="The_AccessXFeedback_Control">section 10.6.3</link> for a discussion on +<emphasis>AccessXFeedback</emphasis> +control. </para> <para> @@ -102,20 +110,22 @@ and the events the server generates for bells. You can associate a name to an act of ringing a bell by converting the name to an Atom and then using this name when you call the functions listed in this chapter. If an event is generated as a result, the name is then passed to all -other clients interested in receiving <emphasis> -XkbBellNotify</emphasis> - events. Note that these are arbitrary names and that there is no binding to +other clients interested in receiving +<symbol>XkbBellNotify</symbol> +events. Note that these are arbitrary names and that there is no binding to any sounds. Any sounds or other effects (such as visual bells on the screen) must be generated by a client application upon receipt of the bell event containing the name. There is no default name for the default keyboard bell. The server does generate some predefined bells for the AccessX controls (see -section 10.6.3). These named bells are shown in Table 9.1; the name is included -in any bell event sent to clients that have requested to receive <emphasis> -XkbBellNotify</emphasis> - events. +<link linkend="The_AccessXFeedback_Control">section 10.6.3</link>). +These named bells are shown in <link linkend="table9.1">Table 9.1</link>; +the name is included +in any bell event sent to clients that have requested to receive +<symbol>XkbBellNotify</symbol> +events. </para> -<table frame='topbot'> +<table id='table9.1' frame='topbot'> <title>Predefined Bells</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -200,36 +210,36 @@ XkbBellNotify</emphasis> Using Xkb you can generate bell events that do not necessarily ring the system bell. This is useful if you need to use an audio server instead of the system beep. For example, when an audio client starts, it could disable the audible -bell (the system bell) and then listen for <emphasis> -XkbBellNotify</emphasis> - events (see section 9.4). When it receives a <emphasis> <!-- xref --> -XkbBellNotify</emphasis> - event, the audio client could then send a request to an audio server to play a +bell (the system bell) and then listen for +<symbol>XkbBellNotify</symbol> +events (see <link linkend="Detecting_Bells">section 9.4</link>). When it receives a +<symbol>XkbBellNotify</symbol> +event, the audio client could then send a request to an audio server to play a sound. </para> <para> -You can control the audible bells feature by passing the <emphasis> -XkbAudibleBellMask</emphasis> - to <emphasis> -XkbChangeEnabledControls</emphasis> - (see section 10.1.1). If you set <emphasis> <!-- xref --> -XkbAudibleBellMask</emphasis> - on, the server rings the system bell when a bell event occurs. This is the -default. If you set <emphasis> -XkbAudibleBellMask</emphasis> - off and a bell event occurs, the server does not ring the system bell unless -you call <emphasis> -XkbForceDeviceBell</emphasis> - or <emphasis> -XkbForceBell</emphasis> - (see section 9.3.3). <!-- xref --> +You can control the audible bells feature by passing the +<symbol>XkbAudibleBellMask</symbol> +to +<function>XkbChangeEnabledControls</function> +(see <link linkend="The_EnabledControls_Control">section 10.1.1</link>). If you set +<symbol>XkbAudibleBellMask</symbol> +on, the server rings the system bell when a bell event occurs. This is the +default. If you set +<symbol>XkbAudibleBellMask</symbol> +off and a bell event occurs, the server does not ring the system bell unless +you call +<function>XkbForceDeviceBell</function> +or +<function>XkbForceBell</function> +(see <link linkend="Forcing_a_Server_Generated_Bell">section 9.3.3</link>). </para> <para> Audible bells are also part of the per-client auto-reset controls. For more -information on auto-reset controls, see section 10.1.2. <!-- xref --> +information on auto-reset controls, see <link linkend="The_AutoReset_Control">section 10.1.2</link>. </para> </sect1> @@ -244,30 +254,29 @@ events. <para> The input extension has two types of feedbacks that can generate bells — bell feedback and keyboard feedback. Some of the functions in this section have -<emphasis> -bell_class</emphasis> - and <emphasis> -bell_id</emphasis> - parameters; set them as follows: Set <emphasis> -bell_class</emphasis> - to <emphasis> -BellFeedbackClass</emphasis> - or <emphasis> -KbdFeedbackClass</emphasis> -. A device can have more than one feedback of each type; set <emphasis> -bell_id</emphasis> - to the particular bell feedback of <emphasis> -bell_class</emphasis> - type. +<structfield>bell_class</structfield> +and +<structfield>bell_id</structfield> +parameters; set them as follows: Set +<structfield>bell_class</structfield> +to +<symbol>BellFeedbackClass</symbol> +or +<symbol>KbdFeedbackClass</symbol>. +A device can have more than one feedback of each type; set +<structfield>bell_id</structfield> +to the particular bell feedback of +<structfield>bell_class</structfield> +type. </para> <para> -Table 9.2 shows the conditions that cause a bell to sound or an <emphasis> <!-- xref --> -XkbBellNotifyEvent</emphasis> - to be generated when a bell function is called. +<link linkend="table9.2">Table 9.2</link> shows the conditions that cause +a bell to sound or an <structname>XkbBellNotifyEvent</structname> +to be generated when a bell function is called. </para> -<table frame='topbot'> +<table id='table9.2' frame='topbot'> <title>Bell Sounding and Bell Event Generating</title> <?dbfo keep-together="always" ?> <tgroup cols='4' align='left' colsep='0' rowsep='0'> @@ -341,230 +350,257 @@ XkbBellNotifyEvent</emphasis> <para> To ring the bell on an X input extension device or the default keyboard, use -<emphasis> -XkbDeviceBell.</emphasis> +<function>XkbDeviceBell</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbDeviceBell</emphasis> -(<emphasis> -display, window, device_id, bell_class, bell_id, percent, name</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Window<emphasis> - window</emphasis> -; /* window for which the bell is generated, or None */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -bell_class</emphasis> -; /* X input extension bell class of the bell to be rung */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -bell_id</emphasis> -; /* X input extension bell ID of the bell to be rung */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -percent</emphasis> -; /* bell volume, from -100 to 100 inclusive */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Atom <emphasis> -name</emphasis> -; /* a name for the bell, or <emphasis> -NULL</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbDeviceBell"><primary><function>XkbDeviceBell</function></primary></indexterm> +<funcsynopsis id="XkbDeviceBell"> + <funcprototype> + <funcdef>Bool <function>XkbDeviceBell</function></funcdef> +<!-- ( +<parameter>display, window, device_id, bell_class, bell_id, percent, name</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>Window <parameter>window</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>bell_class</parameter></paramdef> + <paramdef>unsigned int <parameter>bell_id</parameter></paramdef> + <paramdef>int <parameter>percent</parameter></paramdef> + <paramdef>Atom <parameter>name</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>window</parameter> + </term> + <listitem> + <para> + window for which the bell is generated, or None + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>bell_class</parameter> + </term> + <listitem> + <para> + X input extension bell class of the bell to be rung + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>bell_id</parameter> + </term> + <listitem> + <para> + X input extension bell ID of the bell to be rung + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>percent</parameter> + </term> + <listitem> + <para> + bell volume, from −100 to 100 inclusive + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>name</parameter> + </term> + <listitem> + <para> + a name for the bell, or <symbol>NULL</symbol> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -Set <emphasis> -percent</emphasis> - to be the volume relative to the base volume for the keyboard as described for -<emphasis> -XBell</emphasis>. +Set +<parameter>percent</parameter> +to be the volume relative to the base volume for the keyboard as described for +<function>XBell</function>. </para> <para> -Note that <emphasis> -bell_class</emphasis> - and <emphasis> -bell_id</emphasis> - indicate the bell to physically ring. <emphasis> -name</emphasis> - is simply an arbitrary moniker for the client application’s use. +Note that +<parameter>bell_class</parameter> +and +<parameter>bell_id</parameter> +indicate the bell to physically ring. +<parameter>name</parameter> +is simply an arbitrary moniker for the client application’s use. </para> <para> To determine the current feedback settings of an extension input device, use -<emphasis> -XGetFeedbackControl</emphasis> -. See the X input extension documentation for more information on <emphasis> -XGetFeedbackControl</emphasis> - and related data structures. +<function>XGetFeedbackControl</function>. +See <olink targetdoc='inputlib' targetptr='Controlling_Device_Feedback'>the +X input extension documentation</olink> for more information on +<function>XGetFeedbackControl</function> +and related data structures. </para> <para> -If a compatible keyboard extension is not present in the X server, <emphasis> -XkbDeviceBell</emphasis> - immediately returns <emphasis> -False</emphasis> -. Otherwise, <emphasis> -XkbDeviceBell </emphasis> +If a compatible keyboard extension is not present in the X server, +<function>XkbDeviceBell</function> +immediately returns +<symbol>False</symbol>. +Otherwise, +<function>XkbDeviceBell</function> rings the bell as specified for the display and keyboard device and returns -<emphasis> -True</emphasis> -. If you have disabled the audible bell, the server does not ring the system -bell, although it does generate a <emphasis> -XkbBellNotify</emphasis> - event. +<symbol>True</symbol>. +If you have disabled the audible bell, the server does not ring the system +bell, although it does generate a +<symbol>XkbBellNotify</symbol> +event. </para> <para> -You can call <emphasis> -XkbDeviceBell</emphasis> - without first initializing the keyboard extension. +You can call +<function>XkbDeviceBell</function> +without first initializing the keyboard extension. </para> <para> As a convenience function, Xkb provides a function to ring the bell on the -default keyboard: <emphasis> -XkbBell.</emphasis> +default keyboard: +<function>XkbBell</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbBell</emphasis> -(<emphasis> -display, window, percent, name</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -display</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Window<emphasis> - window</emphasis> -; /* event window, or None*/ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int<emphasis> - percent</emphasis> -; /* relative volume, which can range from -100 to 100 inclusive */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Atom<emphasis> - name</emphasis> -; /* a bell name, or <emphasis> -NULL</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbBell"><primary><function>XkbBell</function></primary></indexterm> +<funcsynopsis id="XkbBell"> + <funcprototype> + <funcdef>Bool <function>XkbBell</function></funcdef> +<!-- ( +<parameter>display, window, percent, name</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>Window <parameter>window</parameter></paramdef> + <paramdef>int <parameter>percent</parameter></paramdef> + <paramdef>Atom <parameter>name</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>window</parameter> + </term> + <listitem> + <para> + event window, or None + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>percent</parameter> + </term> + <listitem> + <para> + relative volume, which can range from −100 to 100 inclusive + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>name</parameter> + </term> + <listitem> + <para> + a bell name, or <symbol>NULL</symbol> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -If a compatible keyboard extension isn’t present in the X server, <emphasis> -XkbBell</emphasis> - calls <emphasis> -XBell </emphasis> -with the specified <emphasis> -display</emphasis> - and <emphasis> -percent</emphasis> -, and returns <emphasis> -False</emphasis> -. Otherwise, <emphasis> -XkbBell </emphasis> -calls <emphasis> -XkbDeviceBell</emphasis> - with the specified <emphasis> -display, window, percent, </emphasis> -and <emphasis> -name</emphasis> -, a <emphasis> -device_spec</emphasis> - of <emphasis> -XkbUseCoreKbd</emphasis> -, a <emphasis> -bell_class </emphasis> -of <emphasis> -XkbDfltXIClass</emphasis> -, and a <emphasis> -bell_id </emphasis> -of <emphasis> -XkbDfltXIId,</emphasis> - and returns <emphasis> -True</emphasis>. +If a compatible keyboard extension isn’t present in the X server, +<function>XkbBell</function> +calls +<function>XBell</function> +with the specified +<parameter>display</parameter> +and +<parameter>percent</parameter>, +and returns +<symbol>False</symbol>. +Otherwise, +<function>XkbBell</function> +calls +<function>XkbDeviceBell</function> +with the specified +<parameter>display</parameter>, +<parameter>window</parameter>, +<parameter>percent</parameter>, +and +<parameter>name</parameter>, +a +<structfield>device_spec</structfield> +of +<symbol>XkbUseCoreKbd</symbol>, +a +<structfield>bell_class</structfield> +of +<symbol>XkbDfltXIClass</symbol>, +and a +<structfield>bell_id</structfield> +of +<symbol>XkbDfltXIId</symbol>, +and returns +<symbol>True</symbol>. </para> <para> If you have disabled the audible bell, the server does not ring the system -bell, although it does generate a <emphasis> -XkbBellNotify</emphasis> - event. +bell, although it does generate a +<symbol>XkbBellNotify</symbol> +event. </para> <para> -You can call <emphasis> -XkbBell</emphasis> - without first initializing the keyboard extension. +You can call +<function>XkbBell</function> +without first initializing the keyboard extension. </para> </sect2> @@ -579,7 +615,7 @@ application starts. <para> For example, if an audio client listens for these types of bells, it can -produce a "whoosh" sound when it receives a named bell event to indicate a +produce a <quote>whoosh</quote> sound when it receives a named bell event to indicate a client just started. In this manner, applications can generate start-up feedback and not worry about producing annoying beeps if an audio server is not running. @@ -588,207 +624,237 @@ running. <para> To cause a bell event for an X input extension device or for the keyboard, -without ringing the corresponding bell, use <emphasis> -XkbDeviceBellEvent.</emphasis> +without ringing the corresponding bell, use +<function>XkbDeviceBellEvent</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbDeviceBellEvent</emphasis> -(<emphasis> -display, window, device_spec, bell_class, bell_id, percent, name</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -display</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Window <emphasis> -window</emphasis> -; /* event window, or None*/ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -bell_class;</emphasis> - /* input extension bell class for the event */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -bell_id</emphasis> -; /* input extension bell ID for the event */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -percent</emphasis> -; /* volume for the bell, which can range from -100 to 100 inclusive */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Atom <emphasis> -name</emphasis> -; /* a bell name, or <emphasis> -NULL</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbDeviceBellEvent"><primary><function>XkbDeviceBellEvent</function></primary></indexterm> +<funcsynopsis id="XkbDeviceBellEvent"> + <funcprototype> + <funcdef>Bool <function>XkbDeviceBellEvent</function></funcdef> +<!-- ( +<parameter>display, window, device_spec, bell_class, bell_id, percent, name</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>Window <parameter>window</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>bell_class</parameter></paramdef> + <paramdef>unsigned int <parameter>bell_id</parameter></paramdef> + <paramdef>int <parameter>percent</parameter></paramdef> + <paramdef>Atom <parameter>name</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>window</parameter> + </term> + <listitem> + <para> + event window, or None + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>bell_class</parameter> + </term> + <listitem> + <para> + input extension bell class for the event + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>bell_id</parameter> + </term> + <listitem> + <para> + input extension bell ID for the event + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>percent</parameter> + </term> + <listitem> + <para> + volume for the bell, which can range from −100 to 100 inclusive + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>name</parameter> + </term> + <listitem> + <para> + a bell name, or <symbol>NULL</symbol> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -If a compatible keyboard extension isn’t present in the X server, <emphasis> -XkbDeviceBellEvent</emphasis> - immediately returns <emphasis> -False</emphasis> -. Otherwise, <emphasis> -XkbDeviceBellEvent</emphasis> - causes an <emphasis> -XkbBellNotify</emphasis> - event to be sent to all interested clients and returns <emphasis> -True</emphasis> -. Set <emphasis> -percent</emphasis> - to be the volume relative to the base volume for the keyboard as described for -<emphasis>XBell</emphasis>. +If a compatible keyboard extension isn’t present in the X server, +<function>XkbDeviceBellEvent</function> +immediately returns +<symbol>False</symbol>. +Otherwise, +<function>XkbDeviceBellEvent</function> +causes an +<symbol>XkbBellNotify</symbol> +event to be sent to all interested clients and returns +<symbol>True</symbol>. +Set +<parameter>percent</parameter> +to be the volume relative to the base volume for the keyboard as described for +<function>XBell</function>. </para> <para> -In addition, <emphasis> -XkbDeviceBellEvent</emphasis> - may generate <emphasis> -Atom</emphasis> - protocol errors as well as <emphasis> -XkbBellNotify</emphasis> - events. You can call <emphasis> -XkbBell</emphasis> - without first initializing the keyboard extension. +In addition, +<function>XkbDeviceBellEvent</function> +may generate +<type>Atom</type> +protocol errors as well as +<symbol>XkbBellNotify</symbol> +events. You can call +<function>XkbBell</function> +without first initializing the keyboard extension. </para> <para> As a convenience function, Xkb provides a function to cause a bell event for -the keyboard without ringing the bell: <emphasis> -XkbBellEvent.</emphasis> +the keyboard without ringing the bell: +<function>XkbBellEvent</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbBellEvent</emphasis> -(<emphasis> -display, window, percent, name</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -display</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Window <emphasis> -window</emphasis> -; /* the event window, or None */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -percent</emphasis> -; /* relative volume, which can range from -100 to 100 inclusive */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Atom <emphasis> -name</emphasis> -; /* a bell name, or <emphasis> -NULL</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbBellEvent"><primary><function>XkbBellEvent</function></primary></indexterm> +<funcsynopsis id="XkbBellEvent"> + <funcprototype> + <funcdef>Bool <function>XkbBellEvent</function></funcdef> +<!-- ( +<parameter>display, window, percent, name</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>Window <parameter>window</parameter></paramdef> + <paramdef>int <parameter>percent</parameter></paramdef> + <paramdef>Atom <parameter>name</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>window</parameter> + </term> + <listitem> + <para> + the event window, or None + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>percent</parameter> + </term> + <listitem> + <para> + relative volume, which can range from −100 to 100 inclusive + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>name</parameter> + </term> + <listitem> + <para> + a bell name, or <symbol>NULL</symbol> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -If a compatible keyboard extension isn’t present in the X server, <emphasis> -XkbBellEvent</emphasis> - immediately returns <emphasis> -False</emphasis> -. Otherwise, <emphasis> -XkbBellEvent </emphasis> -calls<emphasis> - XkbDeviceBellEvent</emphasis> - with the specified <emphasis> -display, window, percent, </emphasis> -and <emphasis> -name</emphasis> -, a <emphasis> -device_spec</emphasis> - of <emphasis> -XkbUseCoreKbd</emphasis> -, a <emphasis> -bell_class </emphasis> -of <emphasis> -XkbDfltXIClass</emphasis> -, and a <emphasis> -bell_id </emphasis> -of <emphasis> -XkbDfltXIId,</emphasis> - and returns what <emphasis> -XkbDeviceBellEvent</emphasis> - returns. +If a compatible keyboard extension isn’t present in the X server, +<function>XkbBellEvent</function> +immediately returns +<symbol>False</symbol>. +Otherwise, +<function>XkbBellEvent</function> +calls +<function>XkbDeviceBellEvent</function> +with the specified +<parameter>display</parameter>, +<parameter>window</parameter>, +<parameter>percent</parameter>, +and +<parameter>name</parameter>, +a +<structfield>device_spec</structfield> +of +<symbol>XkbUseCoreKbd</symbol>, +a +<structfield>bell_class</structfield> +of +<symbol>XkbDfltXIClass</symbol>, +and a +<structfield>bell_id</structfield> +of +<symbol>XkbDfltXIId</symbol>, +and returns what +<function>XkbDeviceBellEvent</function> +returns. </para> <para> -<emphasis>XkbBellEvent</emphasis> -generates a <emphasis>XkbBellNotify</emphasis> +<function>XkbBellEvent</function> +generates a <symbol>XkbBellNotify</symbol> event. </para> <para> -You can call <emphasis> -XkbBellEvent</emphasis> +You can call +<function>XkbBellEvent</function> without first initializing the keyboard extension. </para> @@ -798,192 +864,205 @@ without first initializing the keyboard extension. <para> To ring the bell on any keyboard, overriding user preference settings for -audible bells, use <emphasis>XkbForceDeviceBell</emphasis>. +audible bells, use <function>XkbForceDeviceBell</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbForceDeviceBell</emphasis> -(<emphasis> -display, window, device_spec, bell_class, bell_id, percent</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -display</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Window <emphasis> -window</emphasis> -; /* event window, or None */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -bell_class</emphasis> -; /* input extension class of the bell to be rung */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -bell_id</emphasis> -; /* input extension ID of the bell to be rung */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -percent</emphasis> -; /* relative volume, which can range from -100 to 100 inclusive */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbForceDeviceBell"><primary><function>XkbForceDeviceBell</function></primary></indexterm> +<funcsynopsis id="XkbForceDeviceBell"> + <funcprototype> + <funcdef>Bool <function>XkbForceDeviceBell</function></funcdef> +<!-- ( +<parameter>display, window, device_spec, bell_class, bell_id, percent</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>Window <parameter>window</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>bell_class</parameter></paramdef> + <paramdef>unsigned int <parameter>bell_id</parameter></paramdef> + <paramdef>int <parameter>percent</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>window</parameter> + </term> + <listitem> + <para> + event window, or None + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>bell_class</parameter> + </term> + <listitem> + <para> + input extension class of the bell to be rung + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>bell_id</parameter> + </term> + <listitem> + <para> + input extension ID of the bell to be rung + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>percent</parameter> + </term> + <listitem> + <para> + relative volume, which can range from −100 to 100 inclusive + </para> + </listitem> + </varlistentry> +</variablelist> <para> -If a compatible keyboard extension isn’t present in the X server, <emphasis> -XkbForceDeviceBell</emphasis> - immediately returns <emphasis> -False</emphasis> -. Otherwise, <emphasis> -XkbForceDeviceBell </emphasis> +If a compatible keyboard extension isn’t present in the X server, +<function>XkbForceDeviceBell</function> +immediately returns +<symbol>False</symbol>. +Otherwise, +<function>XkbForceDeviceBell</function> rings the bell as specified for the display and keyboard device and returns -<emphasis> -True</emphasis> -. Set <emphasis> -percent</emphasis> - to be the volume relative to the base volume for the keyboard as described for -<emphasis> -XBell</emphasis> -. There is no <emphasis> -name</emphasis> - parameter because <emphasis> -XkbForceDeviceBell </emphasis> -does not cause an <emphasis> -XkbBellNotify</emphasis> - event. +<symbol>True</symbol>. +Set +<parameter>percent</parameter> +to be the volume relative to the base volume for the keyboard as described for +<function>XBell</function>. +There is no +<structfield>name</structfield> +parameter because +<function>XkbForceDeviceBell</function> +does not cause an +<symbol>XkbBellNotify</symbol> +event. </para> <para> -You can call <emphasis> -XkbBell</emphasis> - without first initializing the keyboard extension. +You can call +<function>XkbBell</function> +without first initializing the keyboard extension. </para> <para> To ring the bell on the default keyboard, overriding user preference settings -for audible bells, use <emphasis> -XkbForceBell</emphasis>. +for audible bells, use +<function>XkbForceBell</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbForceBell</emphasis> -(<emphasis> -display, percent)</emphasis> - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -display</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -percent</emphasis> -; /* volume for the bell, which can range from -100 to 100 inclusive */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbForceBell"><primary><function>XkbForceBell</function></primary></indexterm> +<funcsynopsis id="XkbForceBell"> + <funcprototype> + <funcdef>Bool <function>XkbForceBell</function></funcdef> +<!-- ( +<parameter>display, percent)</parameter> --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>int <parameter>percent</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>percent</parameter> + </term> + <listitem> + <para> + volume for the bell, which can range from −100 to 100 inclusive + </para> + </listitem> + </varlistentry> +</variablelist> <para> -If a compatible keyboard extension isn’t present in the X server, <emphasis> -XkbForceBell</emphasis> - calls <emphasis> -XBell </emphasis> -with the specified <emphasis> -display</emphasis> - and <emphasis> -percent</emphasis> - and returns <emphasis> -False</emphasis> -. Otherwise, <emphasis> -XkbForceBell </emphasis> -calls <emphasis> -XkbForceDeviceBell</emphasis> - with the specified <emphasis> -display </emphasis> -and<emphasis> - percent</emphasis> -, <emphasis> -device_spec</emphasis> - =<emphasis> -XkbUseCoreKbd</emphasis> -, <emphasis> -bell_class </emphasis> -= <emphasis> -XkbDfltXIClass</emphasis> -, <emphasis> -bell_id </emphasis> -= <emphasis> -XkbDfltXIId,</emphasis> - <emphasis> -window</emphasis> - = None, and <emphasis> -name</emphasis> - = <emphasis> -NULL</emphasis> -, and returns what<emphasis> - XkbForceDeviceBell</emphasis> - returns. +If a compatible keyboard extension isn’t present in the X server, +<function>XkbForceBell</function> +calls +<function>XBell</function> +with the specified +<parameter>display</parameter> +and +<parameter>percent</parameter> +and returns +<symbol>False</symbol>. +Otherwise, +<function>XkbForceBell</function> +calls +<function>XkbForceDeviceBell</function> +with the specified +<parameter>display</parameter> +and +<parameter>percent</parameter>, +<structfield>device_spec</structfield> += +<symbol>XkbUseCoreKbd</symbol>, +<structfield>bell_class</structfield> += +<symbol>XkbDfltXIClass</symbol>, +<structfield>bell_id</structfield> += +<symbol>XkbDfltXIId</symbol>, +<structfield>window</structfield> += None, and +<structfield>name</structfield> += +<symbol>NULL</symbol>, +and returns what +<function>XkbForceDeviceBell</function> +returns. </para> <para> -<emphasis> -XkbForceBell </emphasis> -does not cause an <emphasis> -XkbBellNotify</emphasis> - event. +<function>XkbForceBell</function> +does not cause an +<symbol>XkbBellNotify</symbol> +event. </para> <para> -You can call <emphasis> -XkbBell</emphasis> - without first initializing the keyboard extension. +You can call +<function>XkbBell</function> +without first initializing the keyboard extension. </para> </sect2> @@ -992,76 +1071,75 @@ XkbBell</emphasis> <title>Detecting Bells</title> <para> -Xkb generates <emphasis> -XkbBellNotify</emphasis> - events for all bells except for those resulting from calls to <emphasis> -XkbForceDeviceBell</emphasis> - and <emphasis> -XkbForceBell</emphasis> -. To receive <emphasis> -XkbBellNotify</emphasis> - events under all possible conditions, pass <emphasis> -XkbBellNotifyMask</emphasis> - in both the <emphasis> -bits_to_change </emphasis> -and<emphasis> - values_for_bits</emphasis> - parameters to <emphasis> -XkbSelectEvents</emphasis> - (see section 4.3). <!-- xref --> +Xkb generates +<symbol>XkbBellNotify</symbol> +events for all bells except for those resulting from calls to +<function>XkbForceDeviceBell</function> +and +<function>XkbForceBell</function>. +To receive +<symbol>XkbBellNotify</symbol> +events under all possible conditions, pass +<symbol>XkbBellNotifyMask</symbol> +in both the +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +parameters to +<function>XkbSelectEvents</function> +(see <link linkend="Selecting_Xkb_Events">section 4.3</link>). </para> <para> -The <emphasis> -XkbBellNotify</emphasis> - event has no event details. It is either selected or it is not. However, you -can call <emphasis> -XkbSelectEventDetails</emphasis> - using <emphasis> -XkbBellNotify</emphasis> - as the <emphasis> -event_type</emphasis> - and specifying <emphasis> -XkbAllBellNotifyMask</emphasis> - in <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits.</emphasis> - This has the same effect as a call to <emphasis> -XkbSelectEvents</emphasis>. +The +<symbol>XkbBellNotify</symbol> +event has no event details. It is either selected or it is not. However, you +can call +<function>XkbSelectEventDetails</function> +using +<symbol>XkbBellNotify</symbol> +as the +<structfield>event_type</structfield> +and specifying +<symbol>XkbAllBellEventsMask</symbol> +in +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter>. +This has the same effect as a call to +<function>XkbSelectEvents</function>. </para> <para> -The structure for the <emphasis> -XkbBellNotify</emphasis> - event type contains: -</para> +The structure for the +<symbol>XkbBellNotify</symbol> +event type contains: -<para><programlisting> +<programlisting> typedef struct _XkbBellNotify { - int type; /* Xkb extension base event code */ - unsigned long serial; /* X server serial number for event */ - Bool send_event; /* <emphasis> True</emphasis> => synthetically generated */ - Display * display; /* server connection where event generated */ - Time time; /* server time when event generated */ - int xkb_type; /* <emphasis> XkbBellNotify</emphasis> */ - unsigned int device; /* Xkb device ID, will not be <emphasis> XkbUseCoreKbd</emphasis> */ - int percent; /* requested volume as % of max */ - int pitch; /* requested pitch in Hz */ - int duration; /* requested duration in microseconds */ - unsigned int bell_class; /* X input extension feedback class */ - unsigned int bell_id; /* X input extension feedback ID */ - Atom name; /* "name" of requested bell */ - Window window; /* window associated with event */ - Bool event_only; /* <emphasis> False</emphasis> -> the server did not produce a beep */ -} <emphasis>XkbBellNotifyEvent</emphasis>; + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* <symbol>True</symbol> ⇒ synthetically generated */ + Display * display; /* server connection where event generated */ + Time time; /* server time when event generated */ + int xkb_type; /* <symbol>XkbBellNotify</symbol> */ + unsigned int device; /* Xkb device ID, will not be <symbol>XkbUseCoreKbd</symbol> */ + int percent; /* requested volume as % of max */ + int pitch; /* requested pitch in Hz */ + int duration; /* requested duration in microseconds */ + unsigned int bell_class; /* X input extension feedback class */ + unsigned int bell_id; /* X input extension feedback ID */ + Atom name; /* "name" of requested bell */ + Window window; /* window associated with event */ + Bool event_only; /* <symbol>False</symbol> → the server did not produce a beep */ +} <structname>XkbBellNotifyEvent</structname>; </programlisting></para> <para> If your application needs to generate visual bell feedback on the screen when -it receives a bell event, use the window ID in the <emphasis> -XkbBellNotifyEvent</emphasis> -, if present. +it receives a bell event, use the window ID in the +<structname>XkbBellNotifyEvent</structname>, +if present. </para> </sect1> diff --git a/libX11/specs/XKB/ch10.xml b/libX11/specs/XKB/ch10.xml index b7f306938..72727f224 100644 --- a/libX11/specs/XKB/ch10.xml +++ b/libX11/specs/XKB/ch10.xml @@ -1,11 +1,21 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Keyboard_Controls'> <title>Keyboard Controls</title> +<indexterm significance="preferred" zone="Keyboard_Controls"> +<primary>controls</primary></indexterm> +<indexterm significance="preferred" zone="Keyboard_Controls"> +<primary>server controls</primary></indexterm> +<indexterm significance="preferred" zone="Keyboard_Controls"> +<primary>controls</primary><secondary>server</secondary></indexterm> + <para> The Xkb extension is composed of two parts: a server extension, and a client-side X library extension. This chapter discusses functions used to modify controls effecting the behavior of the server portion of the Xkb -extension. Chapter 11 discusses functions used to modify controls that affect +extension. <xref linkend="X_Library_Controls" /> discusses functions used to modify controls that affect only the behavior of the client portion of the extension; those controls are known as Library Controls. </para> @@ -14,15 +24,23 @@ known as Library Controls. <para> Xkb contains control features that affect the entire keyboard, known as global keyboard controls. Some of the controls may be selectively enabled and -disabled; these controls are known as the <emphasis> -Boolean Controls</emphasis> -. Boolean Controls can be turned on or off under program control and can also +disabled; these controls are known as the +<firstterm>Boolean Controls</firstterm>. +<indexterm significance="preferred" zone="Keyboard_Controls"> +<primary>boolean controls</primary></indexterm> +<indexterm significance="preferred" zone="Keyboard_Controls"> +<primary>controls</primary><secondary>boolean</secondary></indexterm> +Boolean Controls can be turned on or off under program control and can also be automatically set to an on or off condition when a client program exits. The -remaining controls, known as the <emphasis> -Non-Boolean Controls</emphasis> -, are always active. The<emphasis> - XkbControlsRec</emphasis> - structure describes the current state of most of the global controls and the +remaining controls, known as the +<firstterm>Non-Boolean Controls</firstterm>, +<indexterm significance="preferred" zone="Keyboard_Controls"> +<primary>non-boolean controls</primary></indexterm> +<indexterm significance="preferred" zone="Keyboard_Controls"> +<primary>controls</primary><secondary>non-boolean</secondary></indexterm> +are always active. The +<structname>XkbControlsRec</structname> +structure describes the current state of most of the global controls and the attributes effecting the behavior of each of these Xkb features. This chapter describes the Xkb controls and how to manipulate them. </para> @@ -32,31 +50,32 @@ describes the Xkb controls and how to manipulate them. There are two possible components for each of the Boolean Controls: attributes describing how the control should work, and a state describing whether the behavior as a whole is enabled or disabled. The attributes and state for most -of these controls are held in the <emphasis> -XkbControlsRec</emphasis> - structure (see section 10.8). +of these controls are held in the +<structname>XkbControlsRec</structname> +structure (see <link linkend="The_XkbControlsRec_Structure">section 10.8</link>). </para> <para> You can manipulate the Xkb controls individually, via convenience functions, or -as a whole. To treat them as a group, modify an <emphasis> -XkbControlsRec</emphasis> - structure to describe all of the changes to be made, and then pass that -structure and appropriate flags to an Xkb library function, or use a <emphasis> -XkbControlsChangesRec</emphasis> - (see section 10.10.1) to reduce network traffic. When using a convenience -function to manipulate one control individually, you do not use an <emphasis> -XkbControlsRec</emphasis> - structure directly. +as a whole. To treat them as a group, modify an +<structname>XkbControlsRec</structname> +structure to describe all of the changes to be made, and then pass that +structure and appropriate flags to an Xkb library function, or use a +<structname>XkbControlsChangesRec</structname> +(see <link linkend="The_XkbControlsChangesRec_Structure">section 10.10.1</link>) to reduce network traffic. When using a convenience +function to manipulate one control individually, you do not use an +<structname>XkbControlsRec</structname> +structure directly. </para> <para> -The Xkb controls are grouped as shown in Table 10.1. <!-- xref --> +The Xkb controls are grouped as shown in +<link linkend="table10.1">Table 10.1</link>. </para> -<table frame='topbot'> +<table id='table10.1' frame='topbot'> <title>Xkb Keyboard Controls</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -192,9 +211,9 @@ The Xkb controls are grouped as shown in Table 10.1. <!-- xref --> <para> The individual categories and controls are described first, together with -functions for manipulating them. A description of the <emphasis> -XkbControlsRec</emphasis> - structure and the general functions for dealing with all of the controls at +functions for manipulating them. A description of the +<structname>XkbControlsRec</structname> +structure and the general functions for dealing with all of the controls at once follow at the end of the chapter. </para> @@ -203,12 +222,10 @@ once follow at the end of the chapter. <para> Enable and disable the boolean controls under program control by using the -<emphasis> -EnabledControls</emphasis> - control; enable and disable them upon program exit by configuring the -<emphasis> -AutoReset</emphasis> - control. +<emphasis>EnabledControls</emphasis> +control; enable and disable them upon program exit by configuring the +<emphasis>AutoReset</emphasis> +control. </para> @@ -216,124 +233,130 @@ AutoReset</emphasis> <title>The EnabledControls Control</title> <para> -The <emphasis> -EnabledControls</emphasis> - control is a bit mask where each bit that is turned on means the corresponding +The +<emphasis>EnabledControls</emphasis> +control is a bit mask where each bit that is turned on means the corresponding control is enabled, and when turned off, disabled. It corresponds to the -<emphasis> -enabled_ctrls</emphasis> - field of an <emphasis> -XkbControlsRec</emphasis> - structure (see section 10.8). The bits describing which controls are turned on -or off are defined in Table 10.7. <!-- xref --> -</para> - - -<para> -Use <emphasis> -XkbChangeEnabledControls</emphasis> - to manipulate the <emphasis> -EnabledControls</emphasis> - control. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbChangeEnabledControls</emphasis> -(<emphasis> -dpy</emphasis> -, <emphasis> -device_spec</emphasis> -, <emphasis> -mask</emphasis> -,<emphasis> - values</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* keyboard device to modify */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -mask</emphasis> -; /* 1 bit -> controls to enable / disable */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -values</emphasis> -; /* 1 bit => enable, 0 bit => disable */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -The <emphasis> -mask</emphasis> - parameter specifies the boolean controls to be enabled or disabled, and the -<emphasis> -values</emphasis> - mask specifies the new state for those controls. Valid values for both of +<structfield>enabled_ctrls</structfield> +field of an +<structname>XkbControlsRec</structname> +structure (see <link linkend="The_XkbControlsRec_Structure">section 10.8</link>). The bits describing which controls are turned on +or off are defined in <link linkend="table10.7">Table 10.7</link>. +</para> + + +<para> +Use +<function>XkbChangeEnabledControls</function> +to manipulate the +<emphasis>EnabledControls</emphasis> +control. +</para> + +<indexterm significance="preferred" zone="XkbChangeEnabledControls"><primary><function>XkbChangeEnabledControls</function></primary></indexterm> +<funcsynopsis id="XkbChangeEnabledControls"> + <funcprototype> + <funcdef>Bool <function>XkbChangeEnabledControls</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>device_spec</parameter>, +<parameter>mask</parameter>, +<parameter>values</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>mask</parameter></paramdef> + <paramdef>unsigned int <parameter>values</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + keyboard device to modify + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>mask</parameter> + </term> + <listitem> + <para> + 1 bit → controls to enable / disable + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>values</parameter> + </term> + <listitem> + <para> + 1 bit ⇒ enable, 0 bit ⇒ disable + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<parameter>mask</parameter> +parameter specifies the boolean controls to be enabled or disabled, and the +<parameter>values</parameter> +mask specifies the new state for those controls. Valid values for both of these masks are composed of a bitwise inclusive OR of bits taken from the set -of mask bits in Table 10.7, using only those masks with "ok" in the <emphasis> -enabled_ctrls</emphasis> - column. +of mask bits in <link linkend="table10.7">Table 10.7</link>, +using only those masks with <quote>ok</quote> in the +<structfield>enabled_ctrls</structfield> +column. </para> <para> If the X server does not support a compatible version of Xkb or the Xkb -extension has not been properly initialized, <emphasis> -XkbChangeEnabledControls</emphasis> - returns <emphasis> -False</emphasis> -; otherwise, it sends the request to the X server and returns <emphasis> -True</emphasis> -. +extension has not been properly initialized, +<function>XkbChangeEnabledControls</function> +returns +<symbol>False</symbol>; +otherwise, it sends the request to the X server and returns +<symbol>True</symbol>. </para> <para> -Note that the <emphasis> -EnabledControls</emphasis> - control only enables and disables controls; it does not configure them. Some -controls, such as the <emphasis> -AudibleBell</emphasis> - control, have no configuration attributes and are therefore manipulated solely +Note that the +<emphasis>EnabledControls</emphasis> +control only enables and disables controls; it does not configure them. Some +controls, such as the +<emphasis>AudibleBell</emphasis> +control, have no configuration attributes and are therefore manipulated solely by enabling and disabling them. Others, however, have additional attributes to -configure their behavior. For example, the <emphasis> -RepeatControl</emphasis> - control uses <emphasis> -repeat_delay</emphasis> - and <emphasis> -repeat_interval</emphasis> - fields to describe the timing behavior of keys that repeat. The <emphasis> -RepeatControl</emphasis> - behavior is turned on or off depending on the value of the <emphasis> -XkbRepeatKeysMask</emphasis> - bit, but you must use other means, as described in this chapter, to configure +configure their behavior. For example, the +<emphasis>RepeatControl</emphasis> +control uses +<structfield>repeat_delay</structfield> +and +<structfield>repeat_interval</structfield> +fields to describe the timing behavior of keys that repeat. The +<emphasis>RepeatControl</emphasis> +behavior is turned on or off depending on the value of the +<symbol>XkbRepeatKeysMask</symbol> +bit, but you must use other means, as described in this chapter, to configure its behavior in detail. </para> @@ -347,255 +370,242 @@ You can configure the boolean controls to automatically be enabled or disabled when a program exits. This capability is controlled via two masks maintained in the X server on a per-client basis. There is no client-side Xkb data structure corresponding to these masks. Whenever the client exits for any reason, any -boolean controls specified in the <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" +boolean controls specified in the +<firstterm>auto-reset mask</firstterm> +<indexterm significance="preferred" zone="The_AutoReset_Control"> +<primary>auto-reset mask</primary></indexterm> +<indexterm significance="preferred" zone="The_AutoReset_Control"> +<primary>mask</primary><secondary>auto-reset</secondary></indexterm> +are set to the corresponding value from the +<firstterm>auto-reset values</firstterm> +mask. This makes it possible for clients to "clean up after themselves" automatically, even if abnormally terminated. The bits used in the masks -correspond to the <emphasis> -EnabledControls</emphasis> - control bits. +correspond to the +<emphasis>EnabledControls</emphasis> +control bits. </para> <para> For example, a client that replaces the keyboard bell with some other audible -cue might want to turn off the <emphasis> -AudibleBell</emphasis> - control to prevent the server from also generating a sound and 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 +cue might want to turn off the +<emphasis>AudibleBell</emphasis> +control to prevent the server from also generating a sound and 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> <para> -To get the current values of the auto-reset controls, use <emphasis> -XkbGetAutoResetControls</emphasis> -. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbGetAutoResetControls</emphasis> -(<emphasis> -dpy</emphasis> -, <emphasis> -auto_ctrls</emphasis> -, <emphasis> -auto_values</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -auto_ctrls</emphasis> -; /* specifies which bits in <emphasis> -auto_values</emphasis> - are relevant */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -auto_values</emphasis> -; /* 1 bit => corresponding control has auto-reset on */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetAutoResetControls</emphasis> - backfills <emphasis> -auto_ctrls</emphasis> - and <emphasis> -auto_values</emphasis> - with the <emphasis> -AutoReset</emphasis> - control attributes for this particular client. It returns <emphasis> -True</emphasis> - if successful, and <emphasis> -False</emphasis> - otherwise. -</para> - - -<para> -To change the current values of the <emphasis> -AutoReset</emphasis> - control attributes, use <emphasis> -XkbSetAutoResetControls.</emphasis> -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetAutoResetControls</emphasis> -(<emphasis> -dpy</emphasis> -, <emphasis> -changes</emphasis> -,<emphasis> - auto_ctrls</emphasis> -, <emphasis> -auto_values</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -changes</emphasis> -; /* controls for which to change auto-reset values */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -auto_ctrls</emphasis> -; /* controls from changes that should auto reset */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -auto_values</emphasis> -; /* 1 bit => auto-reset on */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetAutoResetControls changes the auto-reset status and associated auto-reset -values for the controls selected by </emphasis> -<emphasis> -changes</emphasis> -<emphasis> -. For any control selected by </emphasis> -<emphasis> -changes</emphasis> -<emphasis> -, if the corresponding bit is set in </emphasis> -<emphasis> -auto_ctrls</emphasis> -<emphasis> -, the control is configured to auto-reset when the client exits. If the -corresponding bit in </emphasis> -<emphasis> -auto_values</emphasis> -<emphasis> - is on, the control is turned on when the client exits; if zero, the control is -turned off when the client exits.</emphasis> - For any control selected by <emphasis> -changes</emphasis> -, if the corresponding bit is not set in <emphasis> -auto_ctrls</emphasis> -, the control is configured to not reset when the client exits. For example: -</para> - - -<para> -<emphasis> -To leave the auto-reset controls for </emphasis> -<emphasis> -StickyKeys</emphasis> -<emphasis> - the way they are:</emphasis> -</para> +To get the current values of the auto-reset controls, use +<function>XkbGetAutoResetControls</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetAutoResetControls"><primary><function>XkbGetAutoResetControls</function></primary></indexterm> +<funcsynopsis id="XkbGetAutoResetControls"> + <funcprototype> + <funcdef>Bool <function>XkbGetAutoResetControls</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>auto_ctrls</parameter>, +<parameter>auto_values</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int *<parameter>auto_ctrls</parameter></paramdef> + <paramdef>unsigned int *<parameter>auto_values</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>auto_ctrls</parameter> + </term> + <listitem> + <para> + specifies which bits in <parameter>auto_values</parameter> are relevant + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>auto_values</parameter> + </term> + <listitem> + <para> + 1 bit ⇒ corresponding control has auto-reset on + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetAutoResetControls</function> +backfills +<parameter>auto_ctrls</parameter> +and +<parameter>auto_values</parameter> +with the +<emphasis>AutoReset</emphasis> +control attributes for this particular client. It returns +<symbol>True</symbol> +if successful, and +<symbol>False</symbol> +otherwise. +</para> + + +<para> +To change the current values of the +<emphasis>AutoReset</emphasis> +control attributes, use +<function>XkbSetAutoResetControls</function>. +</para> + + +<indexterm significance="preferred" zone="XkbSetAutoResetControls"><primary><function>XkbSetAutoResetControls</function></primary></indexterm> +<funcsynopsis id="XkbSetAutoResetControls"> + <funcprototype> + <funcdef>Bool <function>XkbSetAutoResetControls</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>changes</parameter>, +<parameter>auto_ctrls</parameter>, +<parameter>auto_values</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>changes</parameter></paramdef> + <paramdef>unsigned int *<parameter>auto_ctrls</parameter></paramdef> + <paramdef>unsigned int *<parameter>auto_values</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + controls for which to change auto-reset values + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>auto_ctrls</parameter> + </term> + <listitem> + <para> + controls from changes that should auto reset + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>auto_values</parameter> + </term> + <listitem> + <para> + 1 bit ⇒ auto-reset on + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetAutoResetControls</function> +changes the auto-reset status and associated auto-reset +values for the controls selected by +<parameter>changes</parameter>. +For any control selected by +<parameter>changes</parameter>, +if the corresponding bit is set in +<parameter>auto_ctrls</parameter>, +the control is configured to auto-reset when the client exits. If the +corresponding bit in +<parameter>auto_values</parameter> +is on, the control is turned on when the client exits; +if zero, the control is turned off when the client exits. +For any control selected by +<parameter>changes</parameter>, +if the corresponding bit is not set in +<parameter>auto_ctrls</parameter>, +the control is configured to not reset when the client exits. For example: +</para> + + +<para> +To leave the auto-reset controls for +<emphasis>StickyKeys</emphasis> +the way they are: -<para><programlisting> -ok = XkbSetAutoResetControls(dpy, 0, 0, 0); +<programlisting> + ok = XkbSetAutoResetControls(dpy, 0, 0, 0); </programlisting></para> <para> -<emphasis> -To change the auto-reset controls so that </emphasis> -<emphasis> -StickyKeys</emphasis> -<emphasis> - are unaffected when the client exits:</emphasis> -</para> +To change the auto-reset controls so that +<emphasis>StickyKeys</emphasis> +are unaffected when the client exits: -<para><programlisting> -ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, 0, 0); +<programlisting> + ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, 0, 0); </programlisting></para> <para> -<emphasis> -To change the auto-reset controls so that </emphasis> -<emphasis> -StickyKeys</emphasis> -<emphasis> - are turned off when the client exits:</emphasis> -</para> +To change the auto-reset controls so that +<emphasis>StickyKeys</emphasis> +are turned off when the client exits: -<para><programlisting> -ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask, 0); +<programlisting> + ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask, 0); </programlisting></para> <para> -<emphasis> -To change the auto-reset controls so that </emphasis> -<emphasis> -StickyKeys</emphasis> -<emphasis> - are turned on when the client exits:</emphasis> -</para> +To change the auto-reset controls so that +<emphasis>StickyKeys</emphasis> +are turned on when the client exits: -<para><programlisting> -ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask, -XkbStickyKeysMask); +<programlisting> + ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask, + XkbStickyKeysMask); </programlisting></para> <para> -<emphasis> -XkbSetAutoResetControls</emphasis> - backfills <emphasis> -auto_ctrls</emphasis> - and <emphasis> -auto_values</emphasis> - with the auto-reset controls for this particular client. Note that all of the +<function>XkbSetAutoResetControls</function> +backfills +<parameter>auto_ctrls</parameter> +and +<parameter>auto_values</parameter> +with the auto-reset controls for this particular client. Note that all of the bits are valid in the returned values, not just the ones selected in the -<emphasis> -changes</emphasis> - mask. +<parameter>changes</parameter> +mask. </para> @@ -605,9 +615,9 @@ changes</emphasis> <title>Control for Bell Behavior</title> <para> -The X server’s generation of sounds is controlled by the <emphasis> -AudibleBell</emphasis> - control. Configuration of different bell sounds is discussed in Chapter 9. +The X server’s generation of sounds is controlled by the +<emphasis>AudibleBell</emphasis> +control. Configuration of different bell sounds is discussed in <xref linkend="Bells" />. </para> @@ -615,17 +625,17 @@ AudibleBell</emphasis> <title>The AudibleBell Control</title> <para> -The <emphasis> -AudibleBell</emphasis> - control is a boolean control that has no attributes. As such, you may enable -and disable it using either the <emphasis> -EnabledControls</emphasis> - control or the <emphasis> -AutoReset</emphasis> - control discussed in section 10.1.1. When enabled, protocol requests to <!-- xref --> +The +<emphasis>AudibleBell</emphasis> +control is a boolean control that has no attributes. As such, you may enable +and disable it using either the +<emphasis>EnabledControls</emphasis> +control or the +<emphasis>AutoReset</emphasis> +control discussed in <link linkend="The_EnabledControls_Control">section 10.1.1</link>. When enabled, protocol requests to generate a sound result in the X server actually producing a real sound; when disabled, requests to the server to generate a sound are ignored unless the -sound is forced. See section 9.2. <!-- xref --> +sound is forced. See <link linkend="Audible_Bells">section 9.2</link>. </para> @@ -634,22 +644,23 @@ sound is forced. See section 9.2. <!-- xref --> <sect1 id='Controls_for_Repeat_Key_Behavior'> <title>Controls for Repeat Key Behavior</title> +<indexterm significance="preferred" zone="Controls_for_Repeat_Key_Behavior"> +<primary>auto-repeat</primary><secondary>controls</secondary></indexterm> + <para> The repeating behavior of keyboard keys is governed by three controls, the -<emphasis> -PerKeyRepeat</emphasis> - control, which is always active, and the <emphasis> -RepeatKeys</emphasis> - and <emphasis> -DetectableAutorepeat</emphasis> - controls, which are boolean controls that may be enabled and disabled. -<emphasis> -PerKeyRepeat</emphasis> - determines which keys are allowed to repeat. <emphasis> -RepeatKeys</emphasis> - governs the behavior of an individual key when it is repeating. <emphasis> -DetectableAutorepeat</emphasis> - allows a client to detect when a key is repeating as a result of being held +<emphasis>PerKeyRepeat</emphasis> +control, which is always active, and the +<emphasis>RepeatKeys</emphasis> +and +<emphasis>DetectableAutorepeat</emphasis> +controls, which are boolean controls that may be enabled and disabled. +<emphasis>PerKeyRepeat</emphasis> +determines which keys are allowed to repeat. +<emphasis>RepeatKeys</emphasis> +governs the behavior of an individual key when it is repeating. +<emphasis>DetectableAutorepeat</emphasis> +allows a client to detect when a key is repeating as a result of being held down. </para> @@ -658,20 +669,20 @@ down. <title>The PerKeyRepeat Control</title> <para> -The <emphasis> -PerKeyRepeat</emphasis> - control is a bitmask long enough to contain a bit for each key on the device; -it determines which individual keys are allowed to repeat. The Xkb <emphasis> -PerKeyRepeat</emphasis> - control provides no functionality different from that available via the core X +The +<emphasis>PerKeyRepeat</emphasis> +control is a bitmask long enough to contain a bit for each key on the device; +it determines which individual keys are allowed to repeat. The Xkb +<emphasis>PerKeyRepeat</emphasis> +control provides no functionality different from that available via the core X protocol. There are no convenience functions in Xkb for manipulating this -control. The <emphasis> -PerKeyRepeat</emphasis> - control settings are carried in the <emphasis> -per_key_repeat</emphasis> - field of an <emphasis> -XkbControlsRec</emphasis> - structure, discussed in section 10.8. <!-- xref --> +control. The +<emphasis>PerKeyRepeat</emphasis> +control settings are carried in the +<structfield>per_key_repeat</structfield> +field of an +<structname>XkbControlsRec</structname> +structure, discussed in <link linkend="The_XkbControlsRec_Structure">section 10.8</link>. </para> @@ -681,192 +692,200 @@ XkbControlsRec</emphasis> <para> The core protocol allows only control over whether or not the entire keyboard -or individual keys should auto-repeat when held down. <emphasis> -RepeatKeys</emphasis> - is a boolean control that extends this capability by adding control over the -delay until a key begins to repeat and the rate at which it repeats. <emphasis> -RepeatKeys</emphasis> - is coupled with the core auto-repeat control: when <emphasis> -RepeatKeys</emphasis> - is enabled or disabled, the core auto-repeat is enabled or disabled and vice +or individual keys should auto-repeat when held down. +<emphasis>RepeatKeys</emphasis> +is a boolean control that extends this capability by adding control over the +delay until a key begins to repeat and the rate at which it repeats. +<emphasis>RepeatKeys</emphasis> +is coupled with the core auto-repeat control: when +<emphasis>RepeatKeys</emphasis> +is enabled or disabled, the core auto-repeat is enabled or disabled and vice versa. </para> <para> -Auto-repeating keys are controlled by two attributes. The first, <emphasis> -timeout</emphasis> -, is the delay after the initial press of an auto-repeating key and the first -generated repeat event. The second, <emphasis> -interval</emphasis> -, is the delay between all subsequent generated repeat events. As with all +Auto-repeating keys are controlled by two attributes. The first, +<firstterm>timeout</firstterm>, +is the delay after the initial press of an auto-repeating key and the first +generated repeat event. The second, +<firstterm>interval</firstterm>, +is the delay between all subsequent generated repeat events. As with all boolean controls, configuring the attributes that determine how the control -operates does not automatically enable the control as a whole; see section 10.1. -</para> - - -<para> -To get the current attributes of the <emphasis> -RepeatKeys</emphasis> - control for a keyboard device, use <emphasis> -XkbGetAutoRepeatRate</emphasis> -. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbGetAutoRepeatRate</emphasis> -(<emphasis> -display, device_spec, timeout_rtrn, interval_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - device_spec</emphasis> -; /* desired device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -* timeout_rtrn</emphasis> -; /* backfilled with initial repeat delay, ms */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -* interval_rtrn</emphasis> -; /* backfilled with subsequent repeat delay, ms */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetAutoRepeatRate</emphasis> - queries the server for the current values of the <emphasis> -RepeatControls</emphasis> - control attributes, backfills <emphasis> -timeout_rtrn</emphasis> - and <emphasis> -interval_rtrn</emphasis> - with them, and returns <emphasis> -True</emphasis> -. If a compatible version of the Xkb extension is not available in the server -<emphasis> -XkbGetAutoRepeatRate</emphasis> - returns <emphasis> -False</emphasis> -. +operates does not automatically enable the control as a whole; see <link linkend="Controls_that_Enable_and_Disable_Other_Controls">section 10.1</link>. +</para> + + +<para> +To get the current attributes of the +<emphasis>RepeatKeys</emphasis> +control for a keyboard device, use +<function>XkbGetAutoRepeatRate</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetAutoRepeatRate"><primary><function>XkbGetAutoRepeatRate</function></primary></indexterm> +<funcsynopsis id="XkbGetAutoRepeatRate"> + <funcprototype> + <funcdef>Bool <function>XkbGetAutoRepeatRate</function></funcdef> +<!-- ( +<parameter>display, device_spec, timeout_rtrn, interval_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int *<parameter>timeout_rtrn</parameter></paramdef> + <paramdef>unsigned int *<parameter>interval_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + desired device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>timeout_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with initial repeat delay, ms + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>interval_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with subsequent repeat delay, ms + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetAutoRepeatRate</function> +queries the server for the current values of the +<emphasis>RepeatControls</emphasis> +control attributes, backfills +<parameter>timeout_rtrn</parameter> +and +<parameter>interval_rtrn</parameter> +with them, and returns +<symbol>True</symbol>. +If a compatible version of the Xkb extension is not available in the server +<function>XkbGetAutoRepeatRate</function> +returns +<symbol>False</symbol>. </para> <para> To set the attributes of the RepeatKeys control for a keyboard device, use -<emphasis> -XkbSetAutoRepeatRate</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetAutoRepeatRate</emphasis> -(<emphasis> -display, device_spec, timeout, interval</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device to configure, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - timeout</emphasis> -; /* initial delay, ms */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - interval</emphasis> -; /* delay between repeats, ms */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetAutoRepeatRate</emphasis> - sends a request to the X server to configure the <emphasis> -AutoRepeat</emphasis> - control attributes to the values specified in <emphasis> -timeout</emphasis> - and <emphasis> -interval</emphasis> -. -</para> - - -<para> -<emphasis> -XkbSetAutoRepeatRate</emphasis> - does not wait for a reply; it normally returns <emphasis> -True</emphasis> -. Specifying a zero value for either <emphasis> -timeout</emphasis> - or <emphasis> -interval</emphasis> - causes the server to generate a <emphasis> -BadValue</emphasis> - protocol error. If a compatible version of the Xkb extension is not available -in the server, <emphasis> -XkbSetAutoRepeatRate</emphasis> - returns <emphasis> -False</emphasis> -. +<function>XkbSetAutoRepeatRate</function>. +</para> + + +<indexterm significance="preferred" zone="XkbSetAutoRepeatRate"><primary><function>XkbSetAutoRepeatRate</function></primary></indexterm> +<funcsynopsis id="XkbSetAutoRepeatRate"> + <funcprototype> + <funcdef>Bool <function>XkbSetAutoRepeatRate</function></funcdef> +<!-- ( +<parameter>display, device_spec, timeout, interval</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>timeout</parameter></paramdef> + <paramdef>unsigned int <parameter>interval</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device to configure, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>timeout</parameter> + </term> + <listitem> + <para> + initial delay, ms + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>interval</parameter> + </term> + <listitem> + <para> + delay between repeats, ms + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetAutoRepeatRate</function> +sends a request to the X server to configure the +<emphasis>AutoRepeat</emphasis> +control attributes to the values specified in +<parameter>timeout</parameter> +and +<parameter>interval</parameter>. +</para> + + +<para> +<function>XkbSetAutoRepeatRate</function> +does not wait for a reply; it normally returns +<symbol>True</symbol>. +Specifying a zero value for either +<parameter>timeout</parameter> +or +<parameter>interval</parameter> +causes the server to generate a +<errorname>BadValue</errorname> +protocol error. If a compatible version of the Xkb extension is not available +in the server, +<function>XkbSetAutoRepeatRate</function> +returns +<symbol>False</symbol>. </para> @@ -877,242 +896,242 @@ False</emphasis> <para> Auto-repeat is the generation of multiple key events by a keyboard when the user presses a key and holds it down. Keyboard hardware and device-dependent X -server software often implement auto-repeat by generating multiple <emphasis> -KeyPress</emphasis> - events with no intervening <emphasis> -KeyRelease</emphasis> - event. The standard behavior of the X server is to generate a <emphasis> -KeyRelease</emphasis> - event for every <emphasis> -KeyPress</emphasis> - event. If the keyboard hardware and device-dependent software of the X server -implement auto-repeat by generating multiple <emphasis> -KeyPress</emphasis> - events, the device-independent part of the X server by default synthetically -generates a <emphasis> -KeyRelease</emphasis> - event after each <emphasis> -KeyPress</emphasis> - event. This provides predictable behavior for X clients, but does not allow +server software often implement auto-repeat by generating multiple +<symbol>KeyPress</symbol> +events with no intervening +<symbol>KeyRelease</symbol> +event. The standard behavior of the X server is to generate a +<symbol>KeyRelease</symbol> +event for every +<symbol>KeyPress</symbol> +event. If the keyboard hardware and device-dependent software of the X server +implement auto-repeat by generating multiple +<symbol>KeyPress</symbol> +events, the device-independent part of the X server by default synthetically +generates a +<symbol>KeyRelease</symbol> +event after each +<symbol>KeyPress</symbol> +event. This provides predictable behavior for X clients, but does not allow those clients to detect the fact that a key is auto-repeating. </para> <para> -Xkb allows clients to request <emphasis> -detectable auto-repeat</emphasis> -. If a client requests and the server supports <emphasis> -DetectableAutorepeat</emphasis> -, Xkb generates <emphasis> -KeyRelease</emphasis> - events only when the key is physically released. If <emphasis> -DetectableAutorepeat</emphasis> - is not supported or has not been requested, the server synthesizes a <emphasis> -KeyRelease</emphasis> - event for each repeating <emphasis> -KeyPress</emphasis> - event it generates. +Xkb allows clients to request +<firstterm>detectable auto-repeat</firstterm>. +<indexterm significance="preferred" zone="The_DetectableAutorepeat_Control"> +<primary>detectable auto-repeat</primary></indexterm> +<indexterm significance="preferred" zone="The_DetectableAutorepeat_Control"> +<primary>auto-repeat</primary><secondary>detectable</secondary></indexterm> +If a client requests and the server supports +<emphasis>DetectableAutorepeat</emphasis>, +Xkb generates +<symbol>KeyRelease</symbol> +events only when the key is physically released. If +<emphasis>DetectableAutorepeat</emphasis> +is not supported or has not been requested, the server synthesizes a +<symbol>KeyRelease</symbol> +event for each repeating +<symbol>KeyPress</symbol> +event it generates. </para> <para> -<emphasis> -DetectableAutorepeat</emphasis> -, unlike the other controls in this chapter, is not contained in the <emphasis> -XkbControlsRec</emphasis> - structure, nor can it be enabled or disabled via the <emphasis> -EnabledControls</emphasis> - control. Instead, query and set <emphasis> -DetectableAutorepeat</emphasis> - using <emphasis> -XkbGetDetectableAutorepeat</emphasis> - and <emphasis> -XkbSetDetectableAutorepeat</emphasis> -. +<emphasis>DetectableAutorepeat</emphasis>, +unlike the other controls in this chapter, is not contained in the +<structname>XkbControlsRec</structname> +structure, nor can it be enabled or disabled via the +<emphasis>EnabledControls</emphasis> +control. Instead, query and set +<emphasis>DetectableAutorepeat</emphasis> +using +<function>XkbGetDetectableAutorepeat</function> +and +<function>XkbSetDetectableAutorepeat</function>. </para> <para> -<emphasis> -DetectableAutorepeat</emphasis> - is a condition that applies to all keyboard devices for a client’s +<emphasis>DetectableAutorepeat</emphasis> +is a condition that applies to all keyboard devices for a client’s connection to a given X server; it cannot be selectively set for some devices and not for others. For this reason, none of the Xkb library functions -involving <emphasis> -DetectableAutorepeat</emphasis> - involve a device specifier. -</para> - - -<para> -To determine whether or not the server supports <emphasis> -DetectableAutorepeat</emphasis> -, use <emphasis> -XkbGetDetectableAutorepeat</emphasis> -. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbGetDetectableAutorepeat</emphasis> -(<emphasis> -display, supported_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool *<emphasis> - supported_rtrn</emphasis> -; /* backfilled <emphasis> -True</emphasis> - if <emphasis> -DetectableAutorepeat</emphasis> - supported */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetDetectableAutorepeat</emphasis> - queries the server for the current state of <emphasis> -DetectableAutorepeat</emphasis> - and waits for a reply. If <emphasis> -supported_rtrn</emphasis> - is not <emphasis> -NULL</emphasis> -, it backfills supported_rtrn with <emphasis> -True</emphasis> - if the server supports <emphasis> -DetectableAutorepeat</emphasis> -, and <emphasis> -False</emphasis> - otherwise. <emphasis> -XkbGetDetectableAutorepeat</emphasis> - returns the current state of <emphasis> -DetectableAutorepeat</emphasis> - for the requesting client: <emphasis> -True</emphasis> - if <emphasis> -DetectableAutorepeat</emphasis> - is set, and <emphasis> -False</emphasis> - otherwise. -</para> - - -<para> -To set <emphasis> -DetectableAutorepeat</emphasis> -, use <emphasis> -XkbSetDetectableAutorepeat</emphasis> -. This request affects all keyboard activity for the requesting client only; +involving +<emphasis>DetectableAutorepeat</emphasis> +involve a device specifier. +</para> + + +<para> +To determine whether or not the server supports +<emphasis>DetectableAutorepeat</emphasis>, +use +<function>XkbGetDetectableAutorepeat</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetDetectableAutorepeat"><primary><function>XkbGetDetectableAutorepeat</function></primary></indexterm> +<funcsynopsis id="XkbGetDetectableAutorepeat"> + <funcprototype> + <funcdef>Bool <function>XkbGetDetectableAutorepeat</function></funcdef> +<!-- ( +<parameter>display, supported_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>Bool *<parameter>supported_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>supported_rtrn</parameter> + </term> + <listitem> + <para> + backfilled <symbol>True</symbol> if +<emphasis>DetectableAutorepeat</emphasis> + supported + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetDetectableAutorepeat</function> +queries the server for the current state of +<emphasis>DetectableAutorepeat</emphasis> +and waits for a reply. If +<parameter>supported_rtrn</parameter> +is not +<symbol>NULL</symbol>, +it backfills supported_rtrn with +<symbol>True</symbol> +if the server supports +<emphasis>DetectableAutorepeat</emphasis>, +and +<symbol>False</symbol> +otherwise. +<function>XkbGetDetectableAutorepeat</function> +returns the current state of +<emphasis>DetectableAutorepeat</emphasis> +for the requesting client: +<symbol>True</symbol> +if +<emphasis>DetectableAutorepeat</emphasis> +is set, and +<symbol>False</symbol> +otherwise. +</para> + + +<para> +To set +<emphasis>DetectableAutorepeat</emphasis>, +use +<function>XkbSetDetectableAutorepeat</function>. +This request affects all keyboard activity for the requesting client only; other clients still see the expected nondetectable auto-repeat behavior, unless they have requested otherwise. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetDetectableAutorepeat</emphasis> -(<emphasis> -display, detectable, supported_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool<emphasis> - detectable</emphasis> -; /* <emphasis> -True</emphasis> - => set <emphasis> -DetectableAutorepeat</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool *<emphasis> - supported_rtrn</emphasis> -; /* backfilled <emphasis> -True</emphasis> - if <emphasis> -DetectableAutorepeat</emphasis> - supported */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetDetectableAutorepeat</emphasis> - sends a request to the server to set <emphasis> -DetectableAutorepeat</emphasis> - on for the current client if <emphasis> -detectable</emphasis> - is <emphasis> -True</emphasis> -, and off it <emphasis> -detectable</emphasis> - is <emphasis> -False</emphasis> -; it then waits for a reply. If <emphasis> -supported_rtrn</emphasis> - is not <emphasis> -NULL</emphasis> -, <emphasis> -XkbSetDetectableAutorepeat</emphasis> - backfills <emphasis> -supported_rtrn</emphasis> - with <emphasis> -True</emphasis> - if the server supports <emphasis> -DetectableAutorepeat</emphasis> -, and <emphasis> -False</emphasis> - if it does not. <emphasis> -XkbSetDetectableAutorepeat</emphasis> - returns the current state of <emphasis> -DetectableAutorepeat</emphasis> - for the requesting client: <emphasis> -True</emphasis> - if <emphasis> -DetectableAutorepeat</emphasis> - is set, and <emphasis> -False</emphasis> - otherwise. +<indexterm significance="preferred" zone="XkbSetDetectableAutorepeat"><primary><function>XkbSetDetectableAutorepeat</function></primary></indexterm> +<funcsynopsis id="XkbSetDetectableAutorepeat"> + <funcprototype> + <funcdef>Bool <function>XkbSetDetectableAutorepeat</function></funcdef> +<!-- ( +<parameter>display, detectable, supported_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>Bool <parameter>detectable</parameter></paramdef> + <paramdef>Bool *<parameter>supported_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>detectable</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ set +<emphasis>DetectableAutorepeat</emphasis> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>supported_rtrn</parameter> + </term> + <listitem> + <para> + backfilled <symbol>True</symbol> if +<emphasis>DetectableAutorepeat</emphasis> + supported + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetDetectableAutorepeat</function> +sends a request to the server to set +<emphasis>DetectableAutorepeat</emphasis> +on for the current client if +<parameter>detectable</parameter> +is +<symbol>True</symbol>, +and off it +<parameter>detectable</parameter> +is +<symbol>False</symbol>; +it then waits for a reply. If +<parameter>supported_rtrn</parameter> +is not +<symbol>NULL</symbol>, +<function>XkbSetDetectableAutorepeat</function> +backfills +<parameter>supported_rtrn</parameter> +with +<symbol>True</symbol> +if the server supports +<emphasis>DetectableAutorepeat</emphasis>, +and +<symbol>False</symbol> +if it does not. +<function>XkbSetDetectableAutorepeat</function> +returns the current state of +<emphasis>DetectableAutorepeat</emphasis> +for the requesting client: +<symbol>True</symbol> +if +<emphasis>DetectableAutorepeat</emphasis> +is set, and +<symbol>False</symbol> +otherwise. </para> @@ -1132,37 +1151,37 @@ keyboards. <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 +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. The two overlays are mutually exclusive; any -particular key may be in at most one overlay. <emphasis> -Overlay1</emphasis> - and <emphasis> -Overlay2</emphasis> - are boolean controls. As such, you may enable and disable them using either -the <emphasis> -EnabledControls</emphasis> - control or the <emphasis> -AutoReset</emphasis> - control discussed in section 10.1.1. <!-- xref --> +particular key may be in at most one overlay. +<emphasis>Overlay1</emphasis> +and +<emphasis>Overlay2</emphasis> +are boolean controls. As such, you may enable and disable them using either +the +<emphasis>EnabledControls</emphasis> +control or the +<emphasis>AutoReset</emphasis> +control discussed in <link linkend="The_EnabledControls_Control">section 10.1.1</link>. </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> -XkbKB_Overlay1</emphasis> - or <emphasis> -XkbKB_Overlay2</emphasis> - key behaviors, as described in section 16.2. <!-- xref --> +should generate when that overlay is enabled, assign it either the +<symbol>XkbKB_Overlay1</symbol> +or +<symbol>XkbKB_Overlay2</symbol> +key behaviors, as described in <link linkend="Key_Behavior">section 16.2</link>. </para> @@ -1174,20 +1193,20 @@ XkbKB_Overlay2</emphasis> Using Xkb, it is possible to configure the keyboard to allow simulation of the X pointer device. This simulation includes both movement of the pointer itself and press and release events associated with the buttons on the pointer. Two -controls affect this behavior: the <emphasis> -MouseKeys</emphasis> - control determines whether or not simulation of the pointer device is active, -as well as configuring the default button; the <emphasis> -MouseKeysAccel</emphasis> - control determines the movement characteristics of the pointer when simulated +controls affect this behavior: the +<emphasis>MouseKeys</emphasis> +control determines whether or not simulation of the pointer device is active, +as well as configuring the default button; the +<emphasis>MouseKeysAccel</emphasis> +control determines the movement characteristics of the pointer when simulated via the keyboard. Both of them are boolean controls; as such, you may enable -and disable them using either the <emphasis> -EnabledControls</emphasis> - control or the <emphasis> -AutoReset</emphasis> - control discussed in section 10.1.1. The individual keys that simulate <!-- xref --> +and disable them using either the +<emphasis>EnabledControls</emphasis> +control or the +<emphasis>AutoReset</emphasis> +control discussed in <link linkend="The_EnabledControls_Control">section 10.1.1</link>. The individual keys that simulate different aspects of the pointer device are determined by the keyboard mapping, -discussed in Chapter 16. <!-- xref --> +discussed in <xref linkend="Xkb_Server_Keyboard_Mapping" />. </para> @@ -1195,64 +1214,63 @@ discussed in Chapter 16. <!-- xref --> <title>The MouseKeys Control</title> <para> -The <emphasis> -MouseKeys</emphasis> - control allows a user to 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 <emphasis> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events. +The +<emphasis>MouseKeys</emphasis> +control allows a user to 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 +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events. </para> <para> -The <emphasis> -MouseKeys</emphasis> - control has a single attribute, <emphasis> -mk_dflt_btn</emphasis> - that specifies the core button number to be used by mouse keys actions that do +The +<emphasis>MouseKeys</emphasis> +control has a single attribute, +<structfield>mk_dflt_btn</structfield> +that specifies the core button number to be used by mouse keys actions that do not explicitly specify a button. There is no convenience function for getting -or setting the attribute; instead use <emphasis> -XkbGetControls</emphasis> - and <emphasis> -XkbSetControls</emphasis> - (see sections 10.9 and 10.10). <!-- xref --> -</para> - -<note><para><emphasis> -MouseKeys</emphasis> - can also be turned on and off by pressing the key combination necessary to -produce an <emphasis> -XK_Pointer_EnableKeys</emphasis> - keysym. The de facto default standard for this is <emphasis> -Shift+Alt+NumLock</emphasis> -, but this may vary depending on the keymap.</para></note> +or setting the attribute; instead use +<function>XkbGetControls</function> +and +<function>XkbSetControls</function> +(see <link linkend="Querying_Controls">section 10.9</link> and <link linkend="Changing_Controls">section 10.10</link>). +</para> + +<note><para> +<emphasis>MouseKeys</emphasis> +can also be turned on and off by pressing the key combination necessary to +produce an +<keysym>XK_Pointer_EnableKeys</keysym> +keysym. The de facto default standard for this is +<keycombo><keycap>Shift</keycap><keycap>Alt</keycap><keycap>NumLock</keycap></keycombo>, +but this may vary depending on the keymap.</para></note> </sect2> <sect2 id='The_MouseKeysAccel_Control'> <title>The MouseKeysAccel Control</title> <para> -When the <emphasis> -MouseKeysAccel</emphasis> - control is enabled, the effect of a key-activated pointer motion action +When the +<emphasis>MouseKeysAccel</emphasis> +control is enabled, the effect of a key-activated pointer motion action changes as a key is held down. If the control is disabled, pressing a -mouse-pointer key yields one mouse event. When <emphasis> -MouseKeysAccel</emphasis> - is enabled, mouse movement is defined by an initial distance specified in the -<emphasis> -XkbSA_MovePtr</emphasis> - action and the following fields in the <emphasis> -XkbControlsRec</emphasis> - structure (see section 10.8). <!-- xref --> +mouse-pointer key yields one mouse event. When +<emphasis>MouseKeysAccel</emphasis> +is enabled, mouse movement is defined by an initial distance specified in the +<symbol>XkbSA_MovePtr</symbol> +action and the following fields in the +<structname>XkbControlsRec</structname> +structure (see <link linkend="The_XkbControlsRec_Structure">section 10.8</link>). </para> -<table frame='topbot'> +<table id='table10.2' frame='topbot'> <title>MouseKeysAccel Fields</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1293,35 +1311,34 @@ speed</entry> <para> There are no convenience functions to query or change the attributes of the -<emphasis> -MouseKeysAccel</emphasis> - control; instead use <emphasis> -XkbGetControls</emphasis> - and <emphasis> -XkbSetControls</emphasis> - (see sections 10.9 and 10.10). <!-- xref --> +<emphasis>MouseKeysAccel</emphasis> +control; instead use +<function>XkbGetControls</function> +and +<function>XkbSetControls</function> +(see <link linkend="Querying_Controls">section 10.9</link> and <link linkend="Changing_Controls">section 10.10</link>). </para> <para> -The effects of the attributes of the <emphasis> -MouseKeysAccel</emphasis> - control depend on whether the <emphasis> -XkbSA_MovePtr</emphasis> - action (see section 16.1) specifies relative or absolute pointer motion. <!-- xref --> +The effects of the attributes of the +<emphasis>MouseKeysAccel</emphasis> +control depend on whether the +<symbol>XkbSA_MovePtr</symbol> +action (see <link linkend="Key_Actions">section 16.1</link>) specifies relative or absolute pointer motion. </para> <sect3 id='Absolute_Pointer_Motion'> <title>Absolute Pointer Motion</title> <para> -If an <emphasis> -XkbSA_MovePtr</emphasis> - action specifies an absolute position for one of the coordinates but still +If an +<symbol>XkbSA_MovePtr</symbol> +action specifies an absolute position for one of the coordinates but still allows acceleration, all repeated events contain any absolute coordinates -specified in the action. For example, if the <emphasis> -XkbSA_MovePtr</emphasis> - action specifies an absolute position for the X direction, but a relative +specified in the action. For example, if the +<symbol>XkbSA_MovePtr</symbol> +action specifies an absolute position for the X direction, but a relative motion for the Y direction, the pointer accelerates in the Y direction, but stays at the same X position. </para> @@ -1332,43 +1349,41 @@ stays at the same X position. <title>Relative Pointer Motion</title> <para> -If the <emphasis> -XkbSA_MovePtr</emphasis> - action specifies relative motion, the initial event always moves the cursor -the distance specified in the action. After <emphasis> -mk_delay</emphasis> - milliseconds, a second motion event is generated, and another occurs every -<emphasis> -mk_interval</emphasis> - milliseconds until the user releases the key. +If the +<symbol>XkbSA_MovePtr</symbol> +action specifies relative motion, the initial event always moves the cursor +the distance specified in the action. After +<structfield>mk_delay</structfield> +milliseconds, a second motion event is generated, and another occurs every +<structfield>mk_interval</structfield> +milliseconds until the user releases the key. </para> <para> -Between the time of the second motion event and <emphasis> -mk_time_to_max</emphasis> - intervals, the change in pointer distance per interval increases with each -interval. After <emphasis> -mk_time_to_max</emphasis> - intervals have elapsed, the change in pointer distance per interval remains +Between the time of the second motion event and +<structfield>mk_time_to_max</structfield> +intervals, the change in pointer distance per interval increases with each +interval. After +<structfield>mk_time_to_max</structfield> +intervals have elapsed, the change in pointer distance per interval remains the same and is calculated by multiplying the original distance specified in -the action by <emphasis> -mk_max_speed</emphasis> -. +the action by +<structfield>mk_max_speed</structfield>. </para> <para> -For example, if the <emphasis> -XkbSA_MovePtr</emphasis> - action specifies a relative motion in the X direction of 5, <emphasis> -mk_delay</emphasis> -=160, <emphasis> -mk_interval</emphasis> -=40, <emphasis> -mk_time_to_max</emphasis> -=30, and <emphasis> -mk_max_speed</emphasis> +For example, if the +<symbol>XkbSA_MovePtr</symbol> +action specifies a relative motion in the X direction of 5, +<structfield>mk_delay</structfield> +=160, +<structfield>mk_interval</structfield> +=40, +<structfield>mk_time_to_max</structfield> +=30, and +<structfield>mk_max_speed</structfield> =30, the following happens when the user presses the key: </para> @@ -1381,100 +1396,101 @@ pressed. </listitem> <listitem> <para> -After 160 milliseconds (<emphasis> -mk_delay</emphasis> -), and every 40 milliseconds thereafter (<emphasis> -mk_interval</emphasis> -), the pointer moves in the X direction. +After 160 milliseconds +(<structfield>mk_delay</structfield>), +and every 40 milliseconds thereafter +(<structfield>mk_interval</structfield>), +the pointer moves in the X direction. </para> </listitem> <listitem> <para> The distance in the X direction increases with each interval until 30 intervals -(<emphasis> -mk_time_to_max</emphasis> -) have elapsed. +( +<structfield>mk_time_to_max</structfield>) +have elapsed. </para> </listitem> <listitem> <para> After 30 intervals, the pointer stops accelerating, and moves 150 pixels -(<emphasis> -mk_max_speed</emphasis> - * the original distance) every interval thereafter, until the key is released. +( +<structfield>mk_max_speed</structfield> +* the original distance) every interval thereafter, until the key is released. </para> </listitem> </itemizedlist> <para> -The increase in pointer difference for each interval is a function of<emphasis> - mk_curve.</emphasis> - Events after the first but before maximum acceleration has been achieved are +The increase in pointer difference for each interval is a function of +<structfield>mk_curve</structfield>. +Events after the first but before maximum acceleration has been achieved are accelerated according to the formula: </para> <mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-3.svg"/> - </imageobject> - </mediaobject> +<imageobject> <imagedata format="SVG" fileref="XKBlib-3.svg"/> +</imageobject> +</mediaobject> <para> -Where <emphasis> -action_delta</emphasis> - is the relative motion specified by the <emphasis> -XkbSA_MovePtr</emphasis> - action, <emphasis> -mk_max_speed </emphasis> -and <emphasis> -mk_time_to_max</emphasis> - are parameters to the <emphasis> -MouseKeysAccel</emphasis> - control, and the curveFactor is computed using the <emphasis> -MouseKeysAccel</emphasis> - <emphasis> -mk_curve</emphasis> - parameter as follows: +Where +<emphasis>action_delta</emphasis> +is the relative motion specified by the +<symbol>XkbSA_MovePtr</symbol> +action, +<structfield>mk_max_speed</structfield> +and +<structfield>mk_time_to_max</structfield> +are parameters to the +<emphasis>MouseKeysAccel</emphasis> +control, and the curveFactor is computed using the +<emphasis>MouseKeysAccel</emphasis> +<structfield>mk_curve</structfield> +parameter as follows: </para> <mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-4.svg"/> - </imageobject> - </mediaobject> - - -<para> -With the result that a <emphasis> -mk_curve</emphasis> - of zero causes the distance moved to increase linearly from <emphasis> -action_delta</emphasis> - to <mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-5.svg"/> - </imageobject> - </mediaobject> - -. A negative <emphasis> -mk_curve</emphasis> - causes an initial sharp increase in acceleration that tapers off, and a +<imageobject> <imagedata format="SVG" fileref="XKBlib-4.svg"/> +</imageobject> +</mediaobject> + + +<para> +With the result that a +<structfield>mk_curve</structfield> +of zero causes the distance moved to increase linearly from +<emphasis>action_delta</emphasis> +to <mediaobject> +<imageobject> <imagedata format="SVG" fileref="XKBlib-5.svg"/> +</imageobject> +</mediaobject>. +A negative +<structfield>mk_curve</structfield> +causes an initial sharp increase in acceleration that tapers off, and a positive curve yields a slower initial increase in acceleration followed by a sharp increase as the number of pointer events generated by the action -approaches <emphasis> -mk_time_to_max</emphasis> -. The legal values for <emphasis> -mk_curve</emphasis> - are between -1000 and 1000. +approaches +<structfield>mk_time_to_max</structfield>. +The legal values for +<structfield>mk_curve</structfield> +are between −1000 and 1000. </para> <para> -A distance vs. time graph of the pointer motion is shown in Figure 10.1. <!-- xref --> +A distance vs. time graph of the pointer motion is shown in +<link linkend="figure10.1">Figure 10.1</link>. </para> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-6.svg"/> - </imageobject> -<caption>MouseKeys Acceleration</caption> - </mediaobject> +<figure id='figure10.1'> + <title>MouseKeys Acceleration</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-6.svg"/> + </imageobject> + </mediaobject> +</figure> <!-- <H5 CLASS="Figure"> @@ -1508,65 +1524,65 @@ Wisconsin-Madison WI 53705-2280. Phone: 608-262-6966. e-mail: info@trace.wisc.ed <para> Enabling or disabling the keyboard controls through a graphical user interface may be impossible for people who need to use the controls. For example, a user -who needs <emphasis> -SlowKeys</emphasis> - (see section 10.6.6) may not even be able to start the graphical application, <!-- xref --> -let alone use it, if <emphasis> -SlowKeys</emphasis> - is not enabled. To allow easier access to some of the controls, the <emphasis> -AccessXKeys</emphasis> - control provides a set of special key sequences similar to those available in +who needs +<emphasis>SlowKeys</emphasis> +(see <link linkend="The_SlowKeys_Control">section 10.6.6</link>) may not even be able to start the graphical application, +let alone use it, if +<emphasis>SlowKeys</emphasis> +is not enabled. To allow easier access to some of the controls, the +<emphasis>AccessXKeys</emphasis> +control provides a set of special key sequences similar to those available in AccessDOS. </para> <para> -When the <emphasis> -AccessXKeys</emphasis> - control is enabled, the user can turn controls on or off from the keyboard by +When the +<emphasis>AccessXKeys</emphasis> +control is enabled, the user can turn controls 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. +Holding down a <keycap>Shift</keycap> key by itself for eight seconds +toggles the +<emphasis>SlowKeys</emphasis> +control. </para> </listitem> <listitem> <para> -Pressing and releasing the left or right <emphasis> -Shift</emphasis> - key five times in a row, without any intervening key events and with less than +Pressing and releasing the left or right +<keycap>Shift</keycap> +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. +<emphasis>StickyKeys</emphasis> +control. </para> </listitem> <listitem> <para> -Simultaneously operating two or more modifier keys deactivates the <emphasis> -StickyKeys</emphasis> - control. +Simultaneously operating two or more modifier keys deactivates the +<emphasis>StickyKeys</emphasis> +control. </para> </listitem> </itemizedlist> <para> -When the <emphasis> -AccessXKeys</emphasis> - control is disabled, Xkb does not look for the above special key sequences. +When the +<emphasis>AccessXKeys</emphasis> +control is disabled, Xkb does not look for the above special key sequences. </para> <para> Some of these key sequences optionally generate audible feedback of the change -in state, as described in section 10.6.3, or <!-- xref --> -<emphasis>XkbControlsNotify</emphasis> - events, described in section 10.11. <!-- xref --> +in state, as described in <link linkend="The_AccessXFeedback_Control">section 10.6.3</link>, or +<symbol>XkbControlsNotify</symbol> +events, described in <link linkend="Tracking_Changes_to_Keyboard_Controls">section 10.11</link>. </para> </sect2> @@ -1574,288 +1590,300 @@ in state, as described in section 10.6.3, or <!-- xref --> <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 are not +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 are not accepted until they are held for a certain period of time. To help solve this -problem, Xkb provides an <emphasis> -AccessXTimeout</emphasis> - control to automatically change the enabled/disabled state of any boolean -controls and to change the value of the <emphasis> -AccessXKeys</emphasis> - and <emphasis> -AccessXFeedback</emphasis> - control attributes if the keyboard is idle for a specified period of time. -</para> - - -<para> -When a timeout as specified by <emphasis> -AccessXTimeout</emphasis> - occurs and a control is consequently modified, Xkb generates an <emphasis> -XkbControlsNotify</emphasis> - event. For more information on <emphasis> -XkbControlsNotify</emphasis> - events, refer to section 10.11. <!-- xref --> -</para> - - -<para> -Use <emphasis> -XkbGetAccessXTimeout</emphasis> - to query the current <emphasis> -AccessXTimeout</emphasis> - options for a keyboard device. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbGetAccessXTimeout</emphasis> -(<emphasis> -display</emphasis> -,<emphasis> - device_spec</emphasis> -,<emphasis> - timeout_rtrn</emphasis> -,<emphasis> - ctrls_mask_rtrn</emphasis> -,<emphasis> - ctrls_values_rtrn</emphasis> -,<emphasis> - options_mask_rtrn, options_values_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device to query, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned short * <emphasis> -timeout_rtrn</emphasis> -; /* delay until AccessXTimeout, seconds */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int *<emphasis> - ctrls_mask_rtrn</emphasis> -; /* backfilled with controls to modify */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -ctrls_values_rtrn</emphasis> -; /* backfilled with on/off status for controls */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned short * <emphasis> -opts_mask_rtrn</emphasis> -; /* backfilled with <emphasis> -ax_options</emphasis> - to modify */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned short * <emphasis> -opts_values_rtrn</emphasis> -; /* backfilled with values for <emphasis> -ax_options</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetAccessXTimeout</emphasis> - sends a request to the X server to obtain the current values for the <emphasis> -AccessXTimeout</emphasis> - attributes, waits for a reply, and backfills the values into the appropriate -arguments.<emphasis> - </emphasis> -The parameters <emphasis> -opts_mask_rtrn</emphasis> - and <emphasis> -opts_values_rtrn</emphasis> - are backfilled with the options to modify and the values for <emphasis> -ax_options</emphasis> -, which is a field in the -<emphasis>XkbControlsRec</emphasis> - structure (see section 10.8). <!-- xref --> -<emphasis> -XkbGetAccessXTimeout </emphasis> -returns<emphasis> - </emphasis> -<emphasis> -True</emphasis> - if successful; if a compatible version of the Xkb extension is not available -in the server, <emphasis> -XkbGetAccessXTimeout</emphasis> - returns <emphasis> -False</emphasis> -. -</para> - - -<para> -To configure the <emphasis> -AccessXTimeout</emphasis> - options for a keyboard device, use <emphasis> -XkbSetAccessXTimeout</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetAccessXTimeout</emphasis> -(<emphasis> -display</emphasis> -,<emphasis> - device_spec, timeout, ctrls_mask, ctrls_values, opts_mask, -opts_values</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - device_spec</emphasis> -; /* device to configure, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned short <emphasis> -timeout</emphasis> -; /* seconds idle until AccessXTimeout occurs */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - ctrls_mask</emphasis> -; /* boolean controls to modify */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - ctrls_values</emphasis> -; /* new bits for controls selected by <emphasis> -ctrls_mask</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned short <emphasis> -opts_mask</emphasis> -; /* <emphasis> -ax_options</emphasis> - to change */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned short <emphasis> -opts_values</emphasis> -; /* new bits for <emphasis> -ax_options</emphasis> - selected by <emphasis> -opts_mask</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -timeout</emphasis> - specifies the number of seconds the keyboard must be idle before the controls -are modified. <emphasis> -ctrls_mask</emphasis> - specifies what controls are to be enabled or disabled, and <emphasis> -ctrls_values</emphasis> - specifies whether those controls are to be enabled or disabled. The bit values -correspond to those for enabling and disabling boolean controls (see section -10.1.1). The <emphasis> -opts_mask</emphasis> - field specifies which attributes of the <emphasis> -AccessXKeys</emphasis> - and <emphasis> -AccessXFeedback</emphasis> - controls are to be changed, and <emphasis> -opts_values</emphasis> - specifies the new values for those options. The bit values correspond to those -for the <emphasis> -ax_options</emphasis> - field of an <emphasis> -XkbDescRec</emphasis> - (see section 10.8). <!-- xref --> -</para> - - -<para> -<emphasis> -XkbSetAccessXTimeout</emphasis> - sends a request to configure the <emphasis> -AccessXTimeout</emphasis> - control to the server.<emphasis> - </emphasis> -It does not wait for a reply, and normally returns <emphasis> -True</emphasis> -. If a compatible version of the Xkb extension is not available in the server, -<emphasis> -XkbSetAccessXTimeout</emphasis> - returns <emphasis> -False</emphasis> -. +problem, Xkb provides an +<emphasis>AccessXTimeout</emphasis> +control to automatically change the enabled/disabled state of any boolean +controls and to change the value of the +<emphasis>AccessXKeys</emphasis> +and +<emphasis>AccessXFeedback</emphasis> +control attributes if the keyboard is idle for a specified period of time. +</para> + + +<para> +When a timeout as specified by +<emphasis>AccessXTimeout</emphasis> +occurs and a control is consequently modified, Xkb generates an +<symbol>XkbControlsNotify</symbol> +event. For more information on +<symbol>XkbControlsNotify</symbol> +events, refer to <link linkend="Tracking_Changes_to_Keyboard_Controls">section 10.11</link>. +</para> + + +<para> +Use +<function>XkbGetAccessXTimeout</function> +to query the current +<emphasis>AccessXTimeout</emphasis> +options for a keyboard device. +</para> + +<indexterm significance="preferred" zone="XkbGetAccessXTimeout"><primary><function>XkbGetAccessXTimeout</function></primary></indexterm> +<funcsynopsis id="XkbGetAccessXTimeout"> + <funcprototype> + <funcdef>Bool <function>XkbGetAccessXTimeout</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec</parameter>, +<parameter>timeout_rtrn</parameter>, +<parameter>ctrls_mask_rtrn</parameter>, +<parameter>ctrls_values_rtrn</parameter>, +<parameter>options_mask_rtrn, options_values_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned short *<parameter>timeout_rtrn</parameter></paramdef> + <paramdef>unsigned int *<parameter>ctrls_mask_rtrn</parameter></paramdef> + <paramdef>unsigned int *<parameter>ctrls_values_rtrn</parameter></paramdef> + <paramdef>unsigned short *<parameter>opts_mask_rtrn</parameter></paramdef> + <paramdef>unsigned short *<parameter>opts_values_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device to query, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>timeout_rtrn</parameter> + </term> + <listitem> + <para> + delay until AccessXTimeout, seconds + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ctrls_mask_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with controls to modify + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ctrls_values_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with on/off status for controls + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>opts_mask_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with <structfield>ax_options</structfield> to modify + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>opts_values_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with values for <structfield>ax_options</structfield> + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetAccessXTimeout</function> +sends a request to the X server to obtain the current values for the +<emphasis>AccessXTimeout</emphasis> +attributes, waits for a reply, and backfills the values into the appropriate +arguments. +The parameters +<parameter>opts_mask_rtrn</parameter> +and +<parameter>opts_values_rtrn</parameter> +are backfilled with the options to modify and the values for +<structfield>ax_options</structfield>, +which is a field in the +<structname>XkbControlsRec</structname> +structure (see <link linkend="The_XkbControlsRec_Structure">section 10.8</link>). +<function>XkbGetAccessXTimeout</function> +returns +<symbol>True</symbol> +if successful; if a compatible version of the Xkb extension is not available +in the server, +<function>XkbGetAccessXTimeout</function> +returns +<symbol>False</symbol>. +</para> + + +<para> +To configure the +<emphasis>AccessXTimeout</emphasis> +options for a keyboard device, use +<function>XkbSetAccessXTimeout</function>. +</para> + + +<indexterm significance="preferred" zone="XkbSetAccessXTimeout"><primary><function>XkbSetAccessXTimeout</function></primary></indexterm> +<funcsynopsis id="XkbSetAccessXTimeout"> + <funcprototype> + <funcdef>Bool <function>XkbSetAccessXTimeout</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec, timeout, ctrls_mask, ctrls_values, opts_mask, +opts_values</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned short <parameter>timeout</parameter></paramdef> + <paramdef>unsigned int <parameter>ctrls_mask</parameter></paramdef> + <paramdef>unsigned int <parameter>ctrls_values</parameter></paramdef> + <paramdef>unsigned short <parameter>opts_mask</parameter></paramdef> + <paramdef>unsigned short <parameter>opts_values</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device to configure, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>timeout</parameter> + </term> + <listitem> + <para> + seconds idle until AccessXTimeout occurs + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ctrls_mask</parameter> + </term> + <listitem> + <para> + boolean controls to modify + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ctrls_values</parameter> + </term> + <listitem> + <para> + new bits for controls selected by <parameter>ctrls_mask</parameter> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>opts_mask</parameter> + </term> + <listitem> + <para> + <structfield>ax_options</structfield> to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>opts_values</parameter> + </term> + <listitem> + <para> + new bits for <structfield>ax_options</structfield> selected by <parameter>opts_mask</parameter> + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<parameter>timeout</parameter> +specifies the number of seconds the keyboard must be idle before the controls +are modified. +<parameter>ctrls_mask</parameter> +specifies what controls are to be enabled or disabled, and +<parameter>ctrls_values</parameter> +specifies whether those controls are to be enabled or disabled. The bit values +correspond to those for enabling and disabling boolean controls +(see <link linkend="The_EnabledControls_Control">section 10.1.1</link>). The +<parameter>opts_mask</parameter> +field specifies which attributes of the +<emphasis>AccessXKeys</emphasis> +and +<emphasis>AccessXFeedback</emphasis> +controls are to be changed, and +<parameter>opts_values</parameter> +specifies the new values for those options. The bit values correspond to those +for the +<structfield>ax_options</structfield> +field of an +<structname>XkbDescRec</structname> +(see <link linkend="The_XkbControlsRec_Structure">section 10.8</link>). +</para> + + +<para> +<function>XkbSetAccessXTimeout</function> +sends a request to configure the +<emphasis>AccessXTimeout</emphasis> +control to the server. +It does not wait for a reply, and normally returns +<symbol>True</symbol>. +If a compatible version of the Xkb extension is not available in the server, +<function>XkbSetAccessXTimeout</function> +returns +<symbol>False</symbol>. </para> @@ -1866,27 +1894,27 @@ False</emphasis> <para> Just as some keyboards can produce keyclicks to indicate when a key is pressed or repeating, Xkb can provide feedback for the controls by using special beep -codes. Use the <emphasis> -AccessXFeedback</emphasis> - control to configure the specific types of operations that generate feedback. +codes. Use the +<emphasis>AccessXFeedback</emphasis> +control to configure the specific types of operations that generate feedback. </para> <para> -There is no convenience function for modifying the <emphasis> -AccessXFeedback</emphasis> - control, although the feedback as a whole can be enabled or disabled just as -other boolean controls are (see section 10.1). Individual beep codes are turned -on or off by modifying the following bits in the <emphasis> -ax_options</emphasis> - field of an <emphasis> -XkbControlsRec</emphasis> - structure and using <emphasis> -XkbSetControls</emphasis> - (see section 10.10): <!-- xref --> +There is no convenience function for modifying the +<emphasis>AccessXFeedback</emphasis> +control, although the feedback as a whole can be enabled or disabled just as +other boolean controls are (see <link linkend="Controls_that_Enable_and_Disable_Other_Controls">section 10.1</link>). Individual beep codes are turned +on or off by modifying the following bits in the +<structfield>ax_options</structfield> +field of an +<structname>XkbControlsRec</structname> +structure and using +<function>XkbSetControls</function> +(see <link linkend="Changing_Controls">section 10.10</link>): </para> -<table frame='topbot'> +<table id='table10.3' frame='topbot'> <title>AccessXFeedback Masks</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -1904,77 +1932,77 @@ XkbSetControls</emphasis> <row> <entry>LED turned on</entry> <entry>High-pitched beep</entry> - <entry>XkbAX_IndicatorFBMask</entry> + <entry><symbol>XkbAX_IndicatorFBMask</symbol></entry> </row> <row> <entry>LED turned off</entry> <entry>Low-pitched beep</entry> - <entry>XkbAX_IndicatorFBMask</entry> + <entry><symbol>XkbAX_IndicatorFBMask</symbol></entry> </row> <row> <entry>More than one LED changed state</entry> <entry>Two high-pitched beeps</entry> - <entry>XkbAX_IndicatorFBMask</entry> + <entry><symbol>XkbAX_IndicatorFBMask</symbol></entry> </row> <row> <entry>Control turned on</entry> <entry>Rising tone</entry> - <entry>XkbAX_FeatureFBMask</entry> + <entry><symbol>XkbAX_FeatureFBMask</symbol></entry> </row> <row> <entry>Control turned off</entry> <entry>Falling tone</entry> - <entry>XkbAX_FeatureFBMask</entry> + <entry><symbol>XkbAX_FeatureFBMask</symbol></entry> </row> <row> <entry>More than one control changed state</entry> <entry>Two high-pitched beeps</entry> - <entry>XkbAX_FeatureFBMask</entry> + <entry><symbol>XkbAX_FeatureFBMask</symbol></entry> </row> <row> <entry>SlowKeys and BounceKeys about to be turned on or off</entry> <entry>Three high-pitched beeps</entry> - <entry>XkbAX_SlowWarnFBMask</entry> + <entry><symbol>XkbAX_SlowWarnFBMask</symbol></entry> </row> <row> <entry>SlowKeys key pressed</entry> <entry>Medium-pitched beep</entry> - <entry>XkbAX_SKPressFBMask</entry> + <entry><symbol>XkbAX_SKPressFBMask</symbol></entry> </row> <row> <entry>SlowKeys key accepted</entry> <entry>Medium-pitched beep</entry> - <entry>XkbAX_SKAcceptFBMask</entry> + <entry><symbol>XkbAX_SKAcceptFBMask</symbol></entry> </row> <row> <entry>SlowKeys key rejected</entry> <entry>Low-pitched beep</entry> - <entry>XkbAX_SKRejectFBMask</entry> + <entry><symbol>XkbAX_SKRejectFBMask</symbol></entry> </row> <row> <entry>Accepted SlowKeys key released</entry> <entry>Medium-pitched beep</entry> - <entry>XkbAX_SKReleaseFBMask</entry> + <entry><symbol>XkbAX_SKReleaseFBMask</symbol></entry> </row> <row> <entry>BounceKeys key rejected</entry> <entry>Low-pitched beep</entry> - <entry>XkbAX_BKRejectFBMask</entry> + <entry><symbol>XkbAX_BKRejectFBMask</symbol></entry> </row> <row> <entry>StickyKeys key latched</entry> <entry>Low-pitched beep followed by high-pitched beep</entry> - <entry>XkbAX_StickyKeysFBMask</entry> + <entry><symbol>XkbAX_StickyKeysFBMask</symbol></entry> </row> <row> <entry>StickyKeys key locked</entry> <entry>High-pitched beep</entry> - <entry>XkbAX_StickyKeysFBMask</entry> + <entry><symbol>XkbAX_StickyKeysFBMask</symbol></entry> </row> <row> <entry>StickyKeys key unlocked</entry> <entry>Low-pitched beep</entry> - <entry>XkbAX_StickyKeysFBMask</entry> + <entry><symbol>XkbAX_StickyKeysFBMask</symbol></entry> </row> </tbody> </tgroup> @@ -1985,18 +2013,18 @@ Implementations that cannot generate continuous tones may generate multiple beeps instead of falling and rising tones; for example, they can generate a high-pitched beep followed by a low-pitched beep instead of a continuous falling tone. Other implementations can only ring the bell with one fixed -pitch. In these cases, use the <emphasis> -XkbAX_DumbBellFBMask</emphasis> - bit of <emphasis> -ax_options</emphasis> - to indicate that the bell can only ring with a fixed pitch. +pitch. In these cases, use the +<symbol>XkbAX_DumbBellFBMask</symbol> +bit of +<structfield>ax_options</structfield> +to indicate that the bell can only ring with a fixed pitch. </para> <para> -When any of the above feedbacks occur, Xkb may generate a <emphasis> -XkbBellNotify</emphasis> - event (see section 9.4). <!-- xref --> +When any of the above feedbacks occur, Xkb may generate a +<symbol>XkbBellNotify</symbol> +event (see <link linkend="Detecting_Bells">section 9.4</link>). </para> @@ -2004,39 +2032,42 @@ XkbBellNotify</emphasis> <sect2 id='AccessXNotify_Events'> <title>AccessXNotify Events</title> +<indexterm significance="preferred" zone="AccessXNotify_Events"> +<primary>events</primary><secondary><symbol>XkbAccessXNotify</symbol></secondary></indexterm> +<indexterm significance="preferred" zone="AccessXNotify_Events"> +<primary><structname>XkbAccessXNotifyEvent</structname></primary></indexterm> + <para> -The server can generate <emphasis> -XkbAccessXNotify</emphasis> - events for some of the global keyboard controls. The structure for the -<emphasis> -XkbAccessXNotify</emphasis> - event type is as follows: -</para> +The server can generate +<symbol>XkbAccessXNotify</symbol> +events for some of the global keyboard controls. The structure for the +<symbol>XkbAccessXNotify</symbol> +event type is as follows: -<para><programlisting> +<programlisting> typedef struct { - int type; /* Xkb extension base event code */ - unsigned long serial; /* X server serial number for event */ - Bool send_event; /* <emphasis> True</emphasis> => synthetically generated */ - Display * display; /* server connection where event generated */ - Time time; /* server time when event generated */ - int xkb_type; /* <emphasis> XkbAccessXNotify</emphasis> */ - int device; /* Xkb device ID, will not be <emphasis> XkbUseCoreKbd</emphasis> */ - int detail; /* XkbAXN_* */ - KeyCode keycode; /* key of event */ - int slowKeysDelay; /* current SlowKeys delay */ - int debounceDelay; /* current debounce delay */ -} <emphasis>XkbAccessXNotifyEvent</emphasis>; + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* <symbol>True</symbol> ⇒ synthetically generated */ + Display * display; /* server connection where event generated */ + Time time; /* server time when event generated */ + int xkb_type; /* <symbol>XkbAccessXNotify</symbol> */ + int device; /* Xkb device ID, will not be <symbol>XkbUseCoreKbd</symbol> */ + int detail; /* XkbAXN_* */ + KeyCode keycode; /* key of event */ + int slowKeysDelay; /* current SlowKeys delay */ + int debounceDelay; /* current debounce delay */ +} <structname>XkbAccessXNotifyEvent</structname>; </programlisting></para> <para> -The <emphasis> -detail</emphasis> - field describes what AccessX event just occurred and can be any of the values -in Table 10.4. <!-- xref --> +The +<structfield>detail</structfield> +field describes what AccessX event just occurred and can be any of the values +in <link linkend="table10.4">Table 10.4</link>. </para> -<table frame='topbot'> +<table id='table10.4' frame='topbot'> <title>AccessXNotify Events</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -2050,33 +2081,33 @@ in Table 10.4. <!-- xref --> </thead> <tbody> <row> - <entry>XkbAXN_SKPress</entry> + <entry><symbol>XkbAXN_SKPress</symbol></entry> <entry>A key was pressed when SlowKeys was enabled.</entry> </row> <row> - <entry>XkbAXN_SKAccept</entry> + <entry><symbol>XkbAXN_SKAccept</symbol></entry> <entry>A key was accepted (held longer than the SlowKeys delay).</entry> </row> <row> - <entry>XkbAXN_SKRelease</entry> + <entry><symbol>XkbAXN_SKRelease</symbol></entry> <entry>An accepted SlowKeys key was released.</entry> </row> <row> - <entry>XkbAXN_SKReject</entry> + <entry><symbol>XkbAXN_SKReject</symbol></entry> <entry>A key was rejected (released before the SlowKeys delay expired).</entry> </row> <row> - <entry>XkbAXN_BKAccept</entry> + <entry><symbol>XkbAXN_BKAccept</symbol></entry> <entry>A key was accepted by BounceKeys.</entry> </row> <row> - <entry>XkbAXN_BKReject</entry> + <entry><symbol>XkbAXN_BKReject</symbol></entry> <entry>A key was rejected (pressed before the BounceKeys delay expired).</entry> </row> <row> - <entry>XkbAXN_AXKWarning</entry> + <entry><symbol>XkbAXN_AXKWarning</symbol></entry> <entry>AccessXKeys is about to turn on/off StickyKeys or BounceKeys.</entry> </row> </tbody> @@ -2084,59 +2115,58 @@ expired).</entry> </table> <para> -The <emphasis> -keycode</emphasis> - field reports the keycode of the key for which the event occurred. If the -action is related to <emphasis> -SlowKeys</emphasis> -, the <emphasis> -slowKeysDelay</emphasis> - field contains the current <emphasis> -SlowKeys</emphasis> - acceptance delay. If the action is related to <emphasis> -BounceKeys</emphasis> -, the <emphasis> -debounceDelay</emphasis> - field contains the current <emphasis> -BounceKeys</emphasis> - debounce delay. +The +<structfield>keycode</structfield> +field reports the keycode of the key for which the event occurred. If the +action is related to +<emphasis>SlowKeys</emphasis>, +the +<structfield>slowKeysDelay</structfield> +field contains the current +<emphasis>SlowKeys</emphasis> +acceptance delay. If the action is related to +<emphasis>BounceKeys</emphasis>, +the +<structfield>debounceDelay</structfield> +field contains the current +<emphasis>BounceKeys</emphasis> +debounce delay. </para> <sect3 id='Selecting_for_AccessX_Events'> <title>Selecting for AccessX Events</title> <para> -To receive <emphasis> -XkbAccessXNotify</emphasis> - events under all possible conditions, use <emphasis> -XkbSelectEvents</emphasis> - (see section 4.3) and pass <emphasis> <!-- xref --> -XkbAccesXNotifyMask</emphasis> - in both <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> -. +To receive +<symbol>XkbAccessXNotify</symbol> +events under all possible conditions, use +<function>XkbSelectEvents</function> +(see <link linkend="Selecting_Xkb_Events">section 4.3</link>) and pass +<symbol>XkbAccessXNotifyMask</symbol> +in both +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter>. </para> <para> -To receive <emphasis> -XkbStateNotify</emphasis> - events only under certain conditions, use <emphasis> -XkbSelectEventDetails</emphasis> - using <emphasis> -XkbAccessXNotify</emphasis> - as the <emphasis> -event_type</emphasis> - and specifying the desired state changes in <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> - using mask bits from Table 10.5. <!-- xref --> +To receive +<symbol>XkbStateNotify</symbol> +events only under certain conditions, use +<function>XkbSelectEventDetails</function> +using +<symbol>XkbAccessXNotify</symbol> +as the +<structfield>event_type</structfield> +and specifying the desired state changes in +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +using mask bits from <link linkend="table10.5">Table 10.5</link>. </para> -<table frame='topbot'> +<table id='table10.5' frame='topbot'> <title>AccessXNotify Event Details</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -2152,37 +2182,37 @@ values_for_bits</emphasis> </thead> <tbody> <row> - <entry>XkbAXN_SKPressMask</entry> + <entry><symbol>XkbAXN_SKPressMask</symbol></entry> <entry>(1<<0)</entry> <entry>Slow key press notification wanted</entry> </row> <row> - <entry>XkbAXN_SKAcceptMask</entry> + <entry><symbol>XkbAXN_SKAcceptMask</symbol></entry> <entry>(1<<1)</entry> <entry>Slow key accept notification wanted</entry> </row> <row> - <entry>XkbAXN_SKRejectMask</entry> + <entry><symbol>XkbAXN_SKRejectMask</symbol></entry> <entry>(1<<2)</entry> <entry>Slow key reject notification wanted</entry> </row> <row> - <entry>XkbAXN_SKReleaseMask</entry> + <entry><symbol>XkbAXN_SKReleaseMask</symbol></entry> <entry>(1<<3)</entry> <entry>Slow key release notification wanted</entry> </row> <row> - <entry>XkbAXN_BKAcceptMask</entry> + <entry><symbol>XkbAXN_BKAcceptMask</symbol></entry> <entry>(1<<4)</entry> <entry>Bounce key accept notification wanted</entry> </row> <row> - <entry>XkbAXN_BKRejectMask</entry> + <entry><symbol>XkbAXN_BKRejectMask</symbol></entry> <entry>(1<<5)</entry> <entry>Bounce key reject notification wanted</entry> </row> <row> - <entry>XkbAXN_AXKWarningMask</entry> + <entry><symbol>XkbAXN_AXKWarningMask</symbol></entry> <entry>(1<<6)</entry> <entry>AccessX warning notification wanted</entry> </row> @@ -2201,26 +2231,25 @@ values_for_bits</emphasis> <title>StickyKeys, RepeatKeys, and MouseKeys Events</title> <para> -The <emphasis> -StickyKeys</emphasis> -, <emphasis> -RepeatKeys</emphasis> -, and <emphasis> -MouseKeys</emphasis> - controls do not generate specific events. Instead, the latching, unlatching, -locking, or unlocking of modifiers using <emphasis> -StickyKeys</emphasis> - generates <emphasis> -XkbStateNotify</emphasis> - events as described in section 5.4. Repeating keys generate normal <emphasis> <!-- xref --> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events, though the auto-repeat can be detected using <emphasis> -DetectableAutorepeat</emphasis> - (see section 10.3.3). Finally, <emphasis> <!-- xref --> -MouseKeys</emphasis> - generates pointer events identical to those of the core pointer device. +The +<emphasis>StickyKeys</emphasis>, +<emphasis>RepeatKeys</emphasis>, +and +<emphasis>MouseKeys</emphasis> +controls do not generate specific events. Instead, the latching, unlatching, +locking, or unlocking of modifiers using +<emphasis>StickyKeys</emphasis> +generates +<symbol>XkbStateNotify</symbol> +events as described in <link linkend="Tracking_Keyboard_State">section 5.4</link>. Repeating keys generate normal +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events, though the auto-repeat can be detected using +<emphasis>DetectableAutorepeat</emphasis> +(see <link linkend="The_DetectableAutorepeat_Control">section 10.3.3</link>). Finally, +<emphasis>MouseKeys</emphasis> +generates pointer events identical to those of the core pointer device. </para> @@ -2231,186 +2260,181 @@ MouseKeys</emphasis> <para> Some users may accidentally bump keys while moving a hand or typing stick toward the key they want. Usually, the keys that are accidentally bumped are -just hit for a very short period of time. The <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 +just hit 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 +<firstterm>SlowKeys acceptance delay</firstterm>, +before delivering key events. If the key is released before this period elapses, no key events are generated. Users can then bump any number of keys on their way to the one they want without accidentally getting those characters. Once they have reached the key they want, they can then hold the desired key -long enough for the computer to accept it. <emphasis> -SlowKeys</emphasis> - is a boolean control with one configurable attribute. +long enough for the computer to accept it. +<emphasis>SlowKeys</emphasis> +is a boolean control with one configurable attribute. </para> <para> -When the <emphasis> -SlowKeys</emphasis> - control is active, the server reports the initial key press, subsequent +When the +<emphasis>SlowKeys</emphasis> +control is active, the server reports the initial key press, subsequent acceptance or rejection, and release of any key to interested clients by -sending an appropriate <emphasis> -AccessXNotify</emphasis> - event (see section 10.6.4). <!-- xref --> -</para> - -<para> -To get the <emphasis> -SlowKeys</emphasis> - acceptance delay for a keyboard device, use <emphasis> -XkbGetSlowKeysDelay</emphasis> -. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbGetSlowKeysDelay</emphasis> -(<emphasis> -display</emphasis> -,<emphasis> - device_spec</emphasis> -,<emphasis> - delay_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -delay_rtrn</emphasis> -; /* backfilled with <emphasis> -SlowKeys</emphasis> - delay, ms */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetSlowKeysDelay </emphasis> -requests the attributes of the <emphasis> -SlowKeys</emphasis> - control from the server, waits for a reply and backfills <emphasis> -delay_rtrn </emphasis> -with the <emphasis> -SlowKeys</emphasis> - delay attribute. <emphasis> -XkbGetSlowKeysDelay </emphasis> -returns <emphasis> -True</emphasis> - if successful; if a compatible version of the Xkb extension is not available -in the server, <emphasis> -XkbGetSlowKeysDelay</emphasis> - returns <emphasis> -False</emphasis> -. -</para> - - -<para> -To set the <emphasis> -SlowKeys</emphasis> - acceptance delay for a keyboard device, use <emphasis> -XkbSetSlowKeysDelay</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetSlowKeysDelay</emphasis> -(<emphasis> -display</emphasis> -,<emphasis> - device_spec</emphasis> -,<emphasis> - delay</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device to configure, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -delay</emphasis> -; /* <emphasis> -SlowKeys</emphasis> - delay, ms */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetSlowKeysDelay</emphasis> - sends a request to configure the <emphasis> -SlowKeys</emphasis> - control to the server.<emphasis> - </emphasis> -It does not wait for a reply, and normally returns <emphasis> -True</emphasis> -. Specifying a value of <emphasis> -0</emphasis> - for the <emphasis> -delay </emphasis> -parameter causes <emphasis> -XkbSetSlowKeys</emphasis> - to generate a <emphasis> -BadValue</emphasis> - protocol error. If a compatible version of the Xkb extension is not available -in the server <emphasis> -XkbSetSlowKeysDelay</emphasis> - returns <emphasis> -False</emphasis> -. +sending an appropriate +<emphasis>AccessXNotify</emphasis> +event (see <link linkend="AccessXNotify_Events">section 10.6.4</link>). +</para> + +<para> +To get the +<emphasis>SlowKeys</emphasis> +acceptance delay for a keyboard device, use +<function>XkbGetSlowKeysDelay</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetSlowKeysDelay"><primary><function>XkbGetSlowKeysDelay</function></primary></indexterm> +<funcsynopsis id="XkbGetSlowKeysDelay"> + <funcprototype> + <funcdef>Bool <function>XkbGetSlowKeysDelay</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec</parameter>, +<parameter>delay_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int *<parameter>delay_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>delay_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with <emphasis>SlowKeys</emphasis> delay, ms + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetSlowKeysDelay</function> +requests the attributes of the +<emphasis>SlowKeys</emphasis> +control from the server, waits for a reply and backfills +<parameter>delay_rtrn</parameter> +with the +<emphasis>SlowKeys</emphasis> +delay attribute. +<function>XkbGetSlowKeysDelay</function> +returns +<symbol>True</symbol> +if successful; if a compatible version of the Xkb extension is not available +in the server, +<function>XkbGetSlowKeysDelay</function> +returns +<symbol>False</symbol>. +</para> + + +<para> +To set the +<emphasis>SlowKeys</emphasis> +acceptance delay for a keyboard device, use +<function>XkbSetSlowKeysDelay</function>. +</para> + + +<indexterm significance="preferred" zone="XkbSetSlowKeysDelay"><primary><function>XkbSetSlowKeysDelay</function></primary></indexterm> +<funcsynopsis id="XkbSetSlowKeysDelay"> + <funcprototype> + <funcdef>Bool <function>XkbSetSlowKeysDelay</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec</parameter>, +<parameter>delay</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>delay</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device to configure, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>delay</parameter> + </term> + <listitem> + <para> + <emphasis>SlowKeys</emphasis> delay, ms + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetSlowKeysDelay</function> +sends a request to configure the +<emphasis>SlowKeys</emphasis> +control to the server. +It does not wait for a reply, and normally returns +<symbol>True</symbol>. +Specifying a value of +<literal>0</literal> +for the +<parameter>delay</parameter> +parameter causes +<function>XkbSetSlowKeysDelay</function> +to generate a +<errorname>BadValue</errorname> +protocol error. If a compatible version of the Xkb extension is not available +in the server +<function>XkbSetSlowKeysDelay</function> +returns +<symbol>False</symbol>. </para> @@ -2419,183 +2443,180 @@ False</emphasis> <title>The BounceKeys Control</title> <para> -Some users may accidentally "bounce" on a key when they release it. They press -it once, then accidentally press it again after they release it. The <emphasis> -BounceKeys</emphasis> - control temporarily disables a key after it has been pressed, effectively -"debouncing" the keyboard. The period of time the key is disabled after it is -released is known as the <emphasis> -BounceKeys delay</emphasis> -. <emphasis> -BounceKeys</emphasis> - is a boolean control. -</para> - - -<para> -When the <emphasis> -BounceKeys</emphasis> - control is active, the server reports acceptance or rejection of any key to -interested clients by sending an appropriate <emphasis> -AccessXNotify</emphasis> - event (see section 10.6.4). <!-- xref --> -</para> - - -<para> -Use <emphasis> -XkbGetBounceKeysDelay</emphasis> - to query the current <emphasis> -BounceKeys</emphasis> - delay for a keyboard device. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbGetBounceKeysDelay</emphasis> -(<emphasis> -display</emphasis> -,<emphasis> - device_spec</emphasis> -,<emphasis> - delay_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -delay_rtrn</emphasis> -; /* backfilled with bounce keys delay, ms */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetBounceKeysDelay </emphasis> -requests the attributes of the <emphasis> -BounceKeys</emphasis> - control from the server, waits for a reply, and backfills <emphasis> -delay_rtrn </emphasis> -with the <emphasis> -BounceKeys</emphasis> - delay attribute. <emphasis> -XkbGetBounceKeysDelay </emphasis> -returns<emphasis> - </emphasis> -<emphasis> -True</emphasis> - if successful; if a compatible version of the Xkb extension is not available -in the server <emphasis> -XkbGetSlowKeysDelay</emphasis> - returns <emphasis> -False</emphasis> -. -</para> - - -<para> -To set the <emphasis> -BounceKeys</emphasis> - delay for a keyboard device, use <emphasis> -XkbSetBounceKeysDelay</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetBounceKeysDelay</emphasis> -(<emphasis> -display</emphasis> -,<emphasis> - device_spec</emphasis> -,<emphasis> - delay</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - device_spec</emphasis> -; /* device to configure, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -delay</emphasis> -; /* bounce keys delay, ms */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetBounceKeysDelay</emphasis> - sends a request to configure the <emphasis> -BounceKeys</emphasis> - control to the server.<emphasis> - </emphasis> -It does not wait for a reply and normally returns <emphasis> -True</emphasis> -. Specifying a value of <emphasis> -zero </emphasis> -for the <emphasis> -delay </emphasis> -parameter causes <emphasis> -XkbSetBounceKeysDelay</emphasis> - to generate a <emphasis> -BadValue</emphasis> - protocol error. If a compatible version of the Xkb extension is not available -in the server, <emphasis> -XkbSetBounceKeysDelay</emphasis> - returns <emphasis> -False</emphasis> -. +Some users may accidentally <quote>bounce</quote> on a key when they release it. +They press it once, then accidentally press it again after they release it. The +<emphasis>BounceKeys</emphasis> +control temporarily disables a key after it has been pressed, effectively +<quote>debouncing</quote> the keyboard. The period of time the key is disabled +after it is released is known as the +<firstterm>BounceKeys delay</firstterm>. +<emphasis>BounceKeys</emphasis> +is a boolean control. +</para> + + +<para> +When the +<emphasis>BounceKeys</emphasis> +control is active, the server reports acceptance or rejection of any key to +interested clients by sending an appropriate +<emphasis>AccessXNotify</emphasis> +event (see <link linkend="AccessXNotify_Events">section 10.6.4</link>). +</para> + + +<para> +Use +<function>XkbGetBounceKeysDelay</function> +to query the current +<emphasis>BounceKeys</emphasis> +delay for a keyboard device. +</para> + +<indexterm significance="preferred" zone="XkbGetBounceKeysDelay"><primary><function>XkbGetBounceKeysDelay</function></primary></indexterm> +<funcsynopsis id="XkbGetBounceKeysDelay"> + <funcprototype> + <funcdef>Bool <function>XkbGetBounceKeysDelay</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec</parameter>, +<parameter>delay_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int *<parameter>delay_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>delay_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with bounce keys delay, ms + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetBounceKeysDelay</function> +requests the attributes of the +<emphasis>BounceKeys</emphasis> +control from the server, waits for a reply, and backfills +<parameter>delay_rtrn</parameter> +with the +<emphasis>BounceKeys</emphasis> +delay attribute. +<function>XkbGetBounceKeysDelay</function> +returns +<symbol>True</symbol> +if successful; if a compatible version of the Xkb extension is not available +in the server +<function>XkbGetSlowKeysDelay</function> +returns +<symbol>False</symbol>. +</para> + + +<para> +To set the +<emphasis>BounceKeys</emphasis> +delay for a keyboard device, use +<function>XkbSetBounceKeysDelay</function>. +</para> + + +<indexterm significance="preferred" zone="XkbSetBounceKeysDelay"><primary><function>XkbSetBounceKeysDelay</function></primary></indexterm> +<funcsynopsis id="XkbSetBounceKeysDelay"> + <funcprototype> + <funcdef>Bool <function>XkbSetBounceKeysDelay</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec</parameter>, +<parameter>delay</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>delay</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device to configure, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>delay</parameter> + </term> + <listitem> + <para> + bounce keys delay, ms + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetBounceKeysDelay</function> +sends a request to configure the +<emphasis>BounceKeys</emphasis> +control to the server. +It does not wait for a reply and normally returns +<symbol>True</symbol>. +Specifying a value of +<emphasis>zero</emphasis> +for the +<parameter>delay</parameter> +parameter causes +<function>XkbSetBounceKeysDelay</function> +to generate a +<errorname>BadValue</errorname> +protocol error. If a compatible version of the Xkb extension is not available +in the server, +<function>XkbSetBounceKeysDelay</function> +returns +<symbol>False</symbol>. </para> </sect2> @@ -2605,32 +2626,30 @@ False</emphasis> <para> Some people find it difficult or even impossible to press two keys at once. For example, a one-fingered typist or someone using a mouth stick cannot press the -<emphasis> -Shift</emphasis> - and <emphasis> -1</emphasis> - keys at the same time. The <emphasis> -StickyKeys</emphasis> - control solves this problem by changing the behavior of the modifier keys. -With <emphasis> -StickyKeys</emphasis> -, the user can first press a modifier, release it, then press another key. For +<keycap>Shift</keycap> +and +<keycap>1</keycap> +keys at the same time. The +<emphasis>StickyKeys</emphasis> +control solves this problem by changing the behavior of the modifier keys. +With +<emphasis>StickyKeys</emphasis>, +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, and then press the <emphasis> -1</emphasis> - key. +the +<keycap>Shift</keycap> +key, release it, and then press the +<keycap>1</keycap> +key. </para> <para> -<emphasis> -StickyKeys</emphasis> - also allows users to lock modifier keys without requiring special locking -keys. When <emphasis> -StickyKeys</emphasis> - is enabled, a modifier is latched when the user presses it just once. The user +<emphasis>StickyKeys</emphasis> +also allows users to lock modifier keys without requiring special locking +keys. When +<emphasis>StickyKeys</emphasis> +is enabled, a modifier is latched when the user presses it just once. The user can press a modifier twice in a row to lock it, and then unlock it by pressing it one more time. </para> @@ -2639,42 +2658,41 @@ it one more time. <para> When a modifier is latched, it becomes unlatched when the user presses a nonmodifier key or a pointer button. For instance, to enter the sequence -<emphasis> -Shift</emphasis> -+<emphasis> -Control</emphasis> -+<emphasis> -Z</emphasis> - the user could press and release the <emphasis> -Shift</emphasis> - key to latch it, then press and release the <emphasis> -Control</emphasis> - key to latch it, and finally press and release the Z key. Because the -<emphasis> -Control</emphasis> - key is a modifier key, pressing it does not unlatch the <emphasis> -Shift</emphasis> - key. Thus, after the user presses the <emphasis> -Control</emphasis> - key, both the <emphasis> -Shift</emphasis> - and <emphasis> -Control</emphasis> - modifiers are latched. When the user presses the <emphasis> -Z</emphasis> - key, the effect is as though the user had pressed <emphasis> -Shift</emphasis> -+<emphasis> -Control</emphasis> -+<emphasis> -Z</emphasis> -. In addition, because the <emphasis> -Z</emphasis> - key is not a modifier key, the <emphasis> -Shift</emphasis> - and <emphasis> -Control</emphasis> - modifiers are unlatched. +<keycombo> +<keycap>Shift</keycap> +<keycap>Control</keycap> +<keycap>Z</keycap> +</keycombo> +the user could press and release the +<keycap>Shift</keycap> +key to latch it, then press and release the +<keycap>Control</keycap> +key to latch it, and finally press and release the +<keycap>Z</keycap> key. Because the +<keycap>Control</keycap> +key is a modifier key, pressing it does not unlatch the +<keycap>Shift</keycap> +key. Thus, after the user presses the +<keycap>Control</keycap> +key, both the +<symbol>Shift</symbol> +and +<symbol>Control</symbol> +modifiers are latched. When the user presses the +<keycap>Z</keycap> +key, the effect is as though the user had pressed +<keycombo> +<keycap>Shift</keycap> +<keycap>Control</keycap> +<keycap>Z</keycap> +</keycombo>. +In addition, because the +<keycap>Z</keycap> +key is not a modifier key, the +<symbol>Shift</symbol> +and +<symbol>Control</symbol> +modifiers are unlatched. </para> @@ -2683,35 +2701,30 @@ Locking a modifier key means that the modifier affects any key or pointer button the user presses until the user unlocks it or it is unlocked programmatically. For example, to enter the sequence ("XKB") on a keyboard where ‘(’ is a shifted ‘9’, ‘)’ is a shifted ‘0’, and ‘"’ -is a shifted single quote, the user could press and release the <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 generates ("XKB"). To unlock the <emphasis> -Shift</emphasis> - modifier, the user can press and release the <emphasis> -Shift</emphasis> - key. +is a shifted single quote, the user could press and release the +<keycap>Shift</keycap> +key twice to lock the +<symbol>Shift</symbol> +modifier. Then, when the user presses the +<keycap>9</keycap>, +<keycap>'</keycap>, +<keycap>x</keycap>, +<keycap>k</keycap>, +<keycap>b</keycap>, +<keycap>'</keycap>, +and +<keycap>0</keycap> +keys in sequence, it generates ("XKB"). To unlock the +<symbol>Shift</symbol> +modifier, the user can press and release the +<keycap>Shift</keycap> +key. </para> <para> <emphasis>StickyKeys</emphasis> - is a boolean control with two separate attributes that may be individually +is a boolean control with two separate attributes that may be individually configured: one to automatically disable it, and one to control the latching behavior of modifier keys. </para> @@ -2720,205 +2733,206 @@ behavior of modifier keys. <title>StickyKeys Options</title> <para> -The <emphasis> -StickyKeys</emphasis> - control has two options that can be accessed via the <emphasis> -ax_options</emphasis> - of an <emphasis> -XkbControlsRec</emphasis> - structure (see section 10.8). The first option, <emphasis> -TwoKeys</emphasis> -, specifies whether <emphasis> -StickyKeys</emphasis> - should automatically turn off when two keys are pressed at the same time. This +The +<emphasis>StickyKeys</emphasis> +control has two options that can be accessed via the +<structfield>ax_options</structfield> +of an +<structname>XkbControlsRec</structname> +structure (see <link linkend="The_XkbControlsRec_Structure">section 10.8</link>). The first option, +<emphasis>TwoKeys</emphasis>, +specifies whether +<emphasis>StickyKeys</emphasis> +should automatically turn off when two keys are pressed at the same time. This feature is useful for shared computers so people who do not want them do not -need to turn <emphasis> -StickyKeys</emphasis> - off if a previous user left <emphasis> -StickyKeys</emphasis> - on. The second option, <emphasis> -LatchToLock</emphasis> -, specifies whether or not <emphasis> -StickyKeys</emphasis> - locks a modifier when pressed twice in a row. +need to turn +<emphasis>StickyKeys</emphasis> +off if a previous user left +<emphasis>StickyKeys</emphasis> +on. The second option, +<emphasis>LatchToLock</emphasis>, +specifies whether or not +<emphasis>StickyKeys</emphasis> +locks a modifier when pressed twice in a row. </para> <para> -Use <emphasis> -XkbGetStickyKeysOptions</emphasis> - to query the current <emphasis> -StickyKeys</emphasis> - attributes for a keyboard device. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbGetStickyKeysOptions</emphasis> -(<emphasis> -display</emphasis> -,<emphasis> - device_spec</emphasis> -,<emphasis> - options_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -options_rtrn</emphasis> -; /* backfilled with StickyKeys option mask */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetStickyKeysOptions </emphasis> -requests the attributes of the <emphasis> -StickyKeys</emphasis> - control from the server, waits for a reply, and backfills <emphasis> -options_rtrn </emphasis> -with a mask indicating whether the individual <emphasis> -StickyKeys</emphasis> - options are on or off. Valid bits in <emphasis> -options_rtrn</emphasis> - are: -</para> - -<para> -<programlisting> - <emphasis>XkbAX_TwoKeysMask</emphasis> - <emphasis>XkbAX_LatchToLockMask</emphasis> -</programlisting> -</para> +Use +<function>XkbGetStickyKeysOptions</function> +to query the current +<emphasis>StickyKeys</emphasis> +attributes for a keyboard device. +</para> + +<indexterm significance="preferred" zone="XkbGetStickyKeysOptions"><primary><function>XkbGetStickyKeysOptions</function></primary></indexterm> +<funcsynopsis id="XkbGetStickyKeysOptions"> + <funcprototype> + <funcdef>Bool <function>XkbGetStickyKeysOptions</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec</parameter>, +<parameter>options_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int *<parameter>options_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>options_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with StickyKeys option mask + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetStickyKeysOptions</function> +requests the attributes of the +<emphasis>StickyKeys</emphasis> +control from the server, waits for a reply, and backfills +<parameter>options_rtrn</parameter> +with a mask indicating whether the individual +<emphasis>StickyKeys</emphasis> +options are on or off. Valid bits in +<parameter>options_rtrn</parameter> +are: -<para> -<emphasis> -XkbGetStickyKeysOptions </emphasis> -returns <emphasis> -True</emphasis> - if successful; if a compatible version of the Xkb extension is not available -in the server <emphasis> -XkbGetStickyKeysOptions</emphasis> - returns <emphasis> -False</emphasis> -. + <simplelist type='vert' columns='1'> + <member><symbol>XkbAX_TwoKeysMask</symbol></member> + <member><symbol>XkbAX_LatchToLockMask</symbol></member> + </simplelist> </para> - <para> -To set the <emphasis> -StickyKeys</emphasis> - attributes for a keyboard device, use <emphasis> -XkbSetStickyKeysOptions</emphasis> -. +<function>XkbGetStickyKeysOptions</function> +returns +<symbol>True</symbol> +if successful; if a compatible version of the Xkb extension is not available +in the server +<function>XkbGetStickyKeysOptions</function> +returns +<symbol>False</symbol>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetStickyKeysOptions</emphasis> -(<emphasis> -display</emphasis> -,<emphasis> - device_spec, mask, values</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device to configure, or XkbUseCoreKbd */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -mask</emphasis> -; /* selects StickyKeys attributes to modify */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -values;</emphasis> - /* values for selected attributes */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - <para> -<emphasis> -XkbSetStickyKeysOptions</emphasis> - sends a request to configure the <emphasis> -StickyKeys</emphasis> - control to the server.<emphasis> - </emphasis> -It does not wait for a reply and normally returns <emphasis> -True</emphasis> -. The valid bits to use for both the <emphasis> -mask</emphasis> - and <emphasis> -values</emphasis> - parameters are: -</para> +To set the +<emphasis>StickyKeys</emphasis> +attributes for a keyboard device, use +<function>XkbSetStickyKeysOptions</function>. +</para> + + +<indexterm significance="preferred" zone="XkbSetStickyKeysOptions"><primary><function>XkbSetStickyKeysOptions</function></primary></indexterm> +<funcsynopsis id="XkbSetStickyKeysOptions"> + <funcprototype> + <funcdef>Bool <function>XkbSetStickyKeysOptions</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec, mask, values</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>mask</parameter></paramdef> + <paramdef>unsigned int <parameter>values</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device to configure, or XkbUseCoreKbd + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>mask</parameter> + </term> + <listitem> + <para> + selects StickyKeys attributes to modify + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>values</parameter> + </term> + <listitem> + <para> + values for selected attributes + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetStickyKeysOptions</function> +sends a request to configure the +<emphasis>StickyKeys</emphasis> +control to the server. +It does not wait for a reply and normally returns +<symbol>True</symbol>. +The valid bits to use for both the +<parameter>mask</parameter> +and +<parameter>values</parameter> +parameters are: -<para> -<programlisting> - <emphasis>XkbAX_TwoKeysMask</emphasis> - <emphasis>XkbAX_LatchToLockMask</emphasis> -</programlisting> + <simplelist type='vert' columns='1'> + <member><symbol>XkbAX_TwoKeysMask</symbol></member> + <member><symbol>XkbAX_LatchToLockMask</symbol></member> + </simplelist> </para> <para> - If a compatible version of the Xkb extension is not available in the server, -<emphasis> -XkbSetStickyKeysOptions</emphasis> - returns <emphasis> -False</emphasis> -. +If a compatible version of the Xkb extension is not available in the server, +<function>XkbSetStickyKeysOptions</function> +returns +<symbol>False</symbol>. </para> </sect3> @@ -2931,36 +2945,33 @@ False</emphasis> There are several controls that apply to the keyboard mapping in general. They control handling of out-of-range group indices and how modifiers are processed and consumed in the server. These are: -</para> -<para> -<programlisting> - <emphasis>GroupsWrap</emphasis> - <emphasis>IgnoreGroupLock</emphasis> - <emphasis>IgnoreLockMods</emphasis> - <emphasis>InternalMods </emphasis> -</programlisting> + <simplelist type='vert' columns='1'> + <member><emphasis>GroupsWrap</emphasis></member> + <member><emphasis>IgnoreGroupLock</emphasis></member> + <member><emphasis>IgnoreLockMods</emphasis></member> + <member><emphasis>InternalMods</emphasis></member> + </simplelist> </para> <para> -<emphasis> -IgnoreGroupLock</emphasis> - is a boolean control; the rest are always active. +<emphasis>IgnoreGroupLock</emphasis> +is a boolean control; the rest are always active. </para> <para> Without the modifier processing options provided by Xkb, passive grabs set via -translations in a client (for example, <emphasis> -Alt<KeyPress>space</emphasis> -) do not trigger if any modifiers other than those specified by the translation -are set. This results in problems in the user interface when either <emphasis> -NumLock</emphasis> - or a secondary keyboard group is active. The <emphasis> -IgnoreLockMods</emphasis> - and <emphasis> -IgnoreGroupLock</emphasis> - controls make it possible to avoid this behavior without exhaustively +translations in a client (for example, +<emphasis>Alt<KeyPress>space</emphasis>) +do not trigger if any modifiers other than those specified by the translation +are set. This results in problems in the user interface when either +<emphasis>NumLock</emphasis> +or a secondary keyboard group is active. The +<emphasis>IgnoreLockMods</emphasis> +and +<emphasis>IgnoreGroupLock</emphasis> +controls make it possible to avoid this behavior without exhaustively specifying a grab for every possible modifier combination. </para> @@ -2968,23 +2979,23 @@ specifying a grab for every possible modifier combination. <title>The GroupsWrap Control</title> <para> -The <emphasis> -GroupsWrap</emphasis> - control determines how illegal groups are handled on a global basis. There are +The +<emphasis>GroupsWrap</emphasis> +control determines how illegal groups are handled on a global basis. There are a number of valid keyboard sequences that can cause the effective group number to go out of range. When this happens, the group must be normalized back to a -valid number. The <emphasis> -GroupsWrap</emphasis> - control specifies how this is done. +valid number. The +<emphasis>GroupsWrap</emphasis> +control specifies how this is done. </para> <para> When dealing with group numbers, all computations are done using the group index, which is the group number minus one. There are three different -algorithms; the <emphasis> -GroupsWrap</emphasis> - control specifies which one is used: +algorithms; the +<emphasis>GroupsWrap</emphasis> +control specifies which one is used: </para> <itemizedlist> @@ -2992,9 +3003,9 @@ GroupsWrap</emphasis> <para>XkbRedirectIntoRange</para> <para> All invalid group numbers are converted to a valid group number by taking the -last four bits of the <emphasis> -GroupsWrap</emphasis> - control and using them as the group index. If the result is still out of +last four bits of the +<emphasis>GroupsWrap</emphasis> +control and using them as the group index. If the result is still out of range, Group one is used. </para> </listitem> @@ -3018,25 +3029,24 @@ modulus applied to the group index. </itemizedlist> <para> -There are no convenience functions for manipulating the <emphasis> -GroupsWrap</emphasis> - control. Manipulate the <emphasis> -GroupsWrap</emphasis> - control via the <emphasis> -groups_wrap</emphasis> - field in the <emphasis> -XkbControlsRec</emphasis> - structure, then use <emphasis> -XkbSetControls</emphasis> - and <emphasis> -XkbGetControls</emphasis> - (see section 10.9 and section 10.10) to query and change this control. <!-- xref --> +There are no convenience functions for manipulating the +<emphasis>GroupsWrap</emphasis> +control. Manipulate the +<emphasis>GroupsWrap</emphasis> +control via the +<structfield>groups_wrap</structfield> +field in the +<structname>XkbControlsRec</structname> +structure, then use +<function>XkbSetControls</function> +and +<function>XkbGetControls</function> +(see <link linkend="Querying_Controls">section 10.9</link> and <link linkend="Changing_Controls">section 10.10</link>) to query and change this control. </para> -<note><para>See also section 15.3.2 or a discussion of the related field, <!-- xref --> -<emphasis> -group_info</emphasis> -, which also normalizes a group under certain circumstances.</para></note> +<note><para>See also <link linkend="Per_Key_Group_Information">section 15.3.2</link> or a discussion of the related field, +<structfield>group_info</structfield>, +which also normalizes a group under certain circumstances.</para></note> </sect2> <sect2 id='The_IgnoreLockMods_Control'> @@ -3050,176 +3060,184 @@ unanticipated side effects. <para> -The <emphasis> -IgnoreLockMods</emphasis> - control specifies modifiers that should be excluded from grab calculations. -These modifiers are also not reported in any core events except <emphasis> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events that do not activate a passive grab and that do not occur while a grab +The +<emphasis>IgnoreLockMods</emphasis> +control specifies modifiers that should be excluded from grab calculations. +These modifiers are also not reported in any core events except +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events that do not activate a passive grab and that do not occur while a grab is active. </para> <para> -Manipulate the <emphasis> -IgnoreLockMods</emphasis> - control via the <emphasis> -ignore_lock</emphasis> - field in the <emphasis> -XkbControlsRec</emphasis> - structure, then use <emphasis> -XkbSetControls</emphasis> - and <emphasis> -XkbGetControls</emphasis> - (see sections 10.9 and 10.10) to query and change this control. Alternatively, <!-- xref --> -use <emphasis> -XkbSetIgnoreLockMods</emphasis> -. +Manipulate the +<emphasis>IgnoreLockMods</emphasis> +control via the +<structfield>ignore_lock</structfield> +field in the +<structname>XkbControlsRec</structname> +structure, then use +<function>XkbSetControls</function> +and +<function>XkbGetControls</function> +(see <link linkend="Querying_Controls">section 10.9</link> and <link linkend="Changing_Controls">section 10.10</link>) to query and change this control. Alternatively, +use +<function>XkbSetIgnoreLockMods</function>. </para> <para> To set the modifiers that, if locked, are not to be reported in matching events -to passive grabs, use <emphasis> -XkbSetIgnoreLockMods.</emphasis> -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetIgnoreLockMods</emphasis> -(<emphasis> -display, device_spec, affect_real, real_values, affect_virtual, -virtual_values</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -display</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - affect_real</emphasis> -; /* mask of real modifiers affected by this call */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - real_values</emphasis> -; /* values for affected real modifiers (1=>set, 0=>unset) */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - affect_virtual</emphasis> -; /* mask of virtual modifiers affected by this call */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - virtual_values</emphasis> -; /* values for affected virtual modifiers (1=>set, 0=>unset) -*/ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetIgnoreLockMods</emphasis> - sends a request to the server to change the server’s <emphasis> -IgnoreLockMods</emphasis> - control. <emphasis> -affect_real</emphasis> - and <emphasis> -real_values</emphasis> - are masks of real modifier bits indicating which real modifiers are to be -added and removed from the server’s <emphasis> -IgnoreLockMods</emphasis> - control. Modifiers selected by both <emphasis> -affect_real</emphasis> - and <emphasis> -real_values</emphasis> - are added to the server’s <emphasis> -IgnoreLockMods</emphasis> - control; those selected by <emphasis> -affect_real</emphasis> - but not by <emphasis> -real_values</emphasis> - are removed from the server’s <emphasis> -IgnoreLockMods</emphasis> - control. Valid values for <emphasis> -affect_real</emphasis> - and <emphasis> -real_values</emphasis> - consist of any combination of the eight core modifier bits: <emphasis> -ShiftMask</emphasis> -, <emphasis> -LockMask</emphasis> -, <emphasis> -ControlMask</emphasis> -, <emphasis> -Mod1Mask</emphasis> - - <emphasis> -Mod5Mask</emphasis> -. <emphasis> -affect_virtual</emphasis> - and <emphasis> -virtual_values</emphasis> - are masks of virtual modifier bits indicating which virtual modifiers are to -be added and removed from the server’s <emphasis> -IgnoreLockMods</emphasis> - control. Modifiers selected by both <emphasis> -affect_virtual</emphasis> - and <emphasis> -virtual_values</emphasis> - are added to the server’s <emphasis> -IgnoreLockMods</emphasis> - control; those selected by <emphasis> -affect_virtual</emphasis> - but not by <emphasis> -virtual_values</emphasis> - are removed from the server’s <emphasis> -IgnoreLockMods</emphasis> - control.<emphasis> - </emphasis> -See section 7.1 for a discussion of virtual modifier masks to use in <emphasis> <!-- xref --> -affect_virtual</emphasis> - and <emphasis> -virtual_values</emphasis> -. <emphasis> -XkbSetIgnoreLockMods</emphasis> - does not wait for a reply from the server. It returns <emphasis> -True</emphasis> - if the request was sent, and <emphasis> -False</emphasis> - otherwise. +to passive grabs, use +<function>XkbSetIgnoreLockMods</function>. +</para> + +<indexterm significance="preferred" zone="XkbSetIgnoreLockMods"><primary><function>XkbSetIgnoreLockMods</function></primary></indexterm> +<funcsynopsis id="XkbSetIgnoreLockMods"> + <funcprototype> + <funcdef>Bool <function>XkbSetIgnoreLockMods</function></funcdef> +<!-- ( +<parameter>display, device_spec, affect_real, real_values, affect_virtual, +virtual_values</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>affect_real</parameter></paramdef> + <paramdef>unsigned int <parameter>real_values</parameter></paramdef> + <paramdef>unsigned int <parameter>affect_virtual</parameter></paramdef> + <paramdef>unsigned int <parameter>virtual_values</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>affect_real</parameter> + </term> + <listitem> + <para> + mask of real modifiers affected by this call + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>real_values</parameter> + </term> + <listitem> + <para> + values for affected real modifiers (1⇒set, 0⇒unset) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>affect_virtual</parameter> + </term> + <listitem> + <para> + mask of virtual modifiers affected by this call + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>virtual_values</parameter> + </term> + <listitem> + <para> + values for affected virtual modifiers (1⇒set, 0⇒unset) + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetIgnoreLockMods</function> +sends a request to the server to change the server’s +<emphasis>IgnoreLockMods</emphasis> +control. +<parameter>affect_real</parameter> +and +<parameter>real_values</parameter> +are masks of real modifier bits indicating which real modifiers are to be +added and removed from the server’s +<emphasis>IgnoreLockMods</emphasis> +control. Modifiers selected by both +<parameter>affect_real</parameter> +and +<parameter>real_values</parameter> +are added to the server’s +<emphasis>IgnoreLockMods</emphasis> +control; those selected by +<parameter>affect_real</parameter> +but not by +<parameter>real_values</parameter> +are removed from the server’s +<emphasis>IgnoreLockMods</emphasis> +control. Valid values for +<parameter>affect_real</parameter> +and +<parameter>real_values</parameter> +consist of any combination of the eight core modifier bits: +<symbol>ShiftMask</symbol>, +<symbol>LockMask</symbol>, +<symbol>ControlMask</symbol>, +<symbol>Mod1Mask</symbol> +– +<symbol>Mod5Mask</symbol>. +<parameter>affect_virtual</parameter> +and +<parameter>virtual_values</parameter> +are masks of virtual modifier bits indicating which virtual modifiers are to +be added and removed from the server’s +<emphasis>IgnoreLockMods</emphasis> +control. Modifiers selected by both +<parameter>affect_virtual</parameter> +and +<parameter>virtual_values</parameter> +are added to the server’s +<emphasis>IgnoreLockMods</emphasis> +control; those selected by +<parameter>affect_virtual</parameter> +but not by +<parameter>virtual_values</parameter> +are removed from the server’s +<emphasis>IgnoreLockMods</emphasis> +control. +See <link linkend="Virtual_Modifier_Names_and_Masks">section 7.1</link> for a discussion of virtual modifier masks to use in +<parameter>affect_virtual</parameter> +and +<parameter>virtual_values</parameter>. +<function>XkbSetIgnoreLockMods</function> +does not wait for a reply from the server. It returns +<symbol>True</symbol> +if the request was sent, and +<symbol>False</symbol> +otherwise. </para> </sect2> @@ -3227,18 +3245,18 @@ False</emphasis> <title>The IgnoreGroupLock Control</title> <para> -The <emphasis> -IgnoreGroupLock</emphasis> - control is a boolean control with no attributes. If enabled, it specifies that +The +<emphasis>IgnoreGroupLock</emphasis> +control is a boolean control with no attributes. If enabled, it specifies that the locked state of the keyboard group should not be considered when activating passive grabs. </para> <para> -Because <emphasis> -IgnoreGroupLock</emphasis> - is a boolean control with no attributes, use the general boolean controls -functions (see section 10.1) to change its state. <!-- xref --> +Because +<emphasis>IgnoreGroupLock</emphasis> +is a boolean control with no attributes, use the general boolean controls +functions (see <link linkend="Controls_that_Enable_and_Disable_Other_Controls">section 10.1</link>) to change its state. </para> @@ -3249,171 +3267,176 @@ functions (see section 10.1) to change its state. <!-- xref --> <para> The core protocol does not provide any means to prevent a modifier from being reported in events sent to clients; Xkb, however makes this possible via the -<emphasis> -InternalMods</emphasis> - control. It specifies modifiers that should be consumed by the server and not +<emphasis>InternalMods</emphasis> +control. It specifies modifiers that should be consumed by the server and not reported to clients. When a key is pressed and a modifier that has its bit set -in the <emphasis> -InternalMods</emphasis> - control is reported to the server, the server uses the modifier when +in the +<emphasis>InternalMods</emphasis> +control is reported to the server, the server uses the modifier when determining the actions to apply for the key. The server then clears the bit, so it is not actually reported to the client. In addition, modifiers specified -in the <emphasis> -InternalMods</emphasis> - control are not used to determine grabs and are not used to calculate core +in the +<emphasis>InternalMods</emphasis> +control are not used to determine grabs and are not used to calculate core protocol compatibility state. </para> <para> -Manipulate the <emphasis> -InternalMods</emphasis> - control via the <emphasis> -internal</emphasis> - field in the <emphasis> -XkbControlsRec</emphasis> - structure, using <emphasis> -XkbSetControls</emphasis> - and <emphasis> -XkbGetControls</emphasis> - (see sections10.9 and 10.10). Alternatively, use <emphasis> <!-- xref --> -XkbSetServerInternalMods</emphasis> -. +Manipulate the +<emphasis>InternalMods</emphasis> +control via the +<structfield>internal</structfield> +field in the +<structname>XkbControlsRec</structname> +structure, using +<function>XkbSetControls</function> +and +<function>XkbGetControls</function> +(see <link linkend="Querying_Controls">section 10.9</link> +and <link linkend="Changing_Controls">section 10.10</link>). Alternatively, use +<function>XkbSetServerInternalMods</function>. </para> <para> To set the modifiers that are consumed by the server before events are -delivered to the client, use <emphasis> -XkbSetServerInternalMods.</emphasis> -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetServerInternalMods</emphasis> -(<emphasis> -display, device_spec, affect_real, real_values, affect_virtual, -virtual_values</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -display</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -;‘ /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - affect_real</emphasis> -; /* mask of real modifiers affected by this call */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - real_values</emphasis> -; /* values for affected real modifiers (1=>set, 0=>unset) */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - affect_virtual</emphasis> -; /* mask of virtual modifiers affected by this call */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - virtual_values</emphasis> -; /* values for affected virtual modifiers (1=>set, 0=>unset) -*/ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetServerInternalMods</emphasis> - sends a request to the server to change the internal modifiers consumed by the -server. <emphasis> -affect_real</emphasis> - and <emphasis> -real_values</emphasis> - are masks of real modifier bits indicating which real modifiers are to be +delivered to the client, use +<function>XkbSetServerInternalMods</function>. +</para> + +<indexterm significance="preferred" zone="XkbSetServerInternalMods"><primary><function>XkbSetServerInternalMods</function></primary></indexterm> +<funcsynopsis id="XkbSetServerInternalMods"> + <funcprototype> + <funcdef>Bool <function>XkbSetServerInternalMods</function></funcdef> +<!-- ( +<parameter>display, device_spec, affect_real, real_values, affect_virtual, +virtual_values</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>affect_real</parameter></paramdef> + <paramdef>unsigned int <parameter>real_values</parameter></paramdef> + <paramdef>unsigned int <parameter>affect_virtual</parameter></paramdef> + <paramdef>unsigned int <parameter>virtual_values</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + ‘device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>affect_real</parameter> + </term> + <listitem> + <para> + mask of real modifiers affected by this call + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>real_values</parameter> + </term> + <listitem> + <para> + values for affected real modifiers (1⇒set, 0⇒unset) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>affect_virtual</parameter> + </term> + <listitem> + <para> + mask of virtual modifiers affected by this call + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>virtual_values</parameter> + </term> + <listitem> + <para> + values for affected virtual modifiers (1⇒set, 0⇒unset) + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetServerInternalMods</function> +sends a request to the server to change the internal modifiers consumed by the +server. +<parameter>affect_real</parameter> +and +<parameter>real_values</parameter> +are masks of real modifier bits indicating which real modifiers are to be added and removed from the server’s internal modifiers control. Modifiers -selected by both <emphasis> -affect_real</emphasis> - and <emphasis> -real_values</emphasis> - are added to the server’s internal modifiers control; those selected by -<emphasis> -affect_real</emphasis> - but not by <emphasis> -real_values</emphasis> - are removed from the server’s internal modifiers mask. Valid values for -<emphasis> -affect_real</emphasis> - and <emphasis> -real_values</emphasis> - consist of any combination of the eight core modifier bits: <emphasis> -ShiftMask</emphasis> -, <emphasis> -LockMask</emphasis> -, <emphasis> -ControlMask</emphasis> -, <emphasis> -Mod1Mask</emphasis> - - <emphasis> -Mod5Mask</emphasis> -.<emphasis> - affect_virtual</emphasis> - and <emphasis> -virtual_values</emphasis> - are masks of virtual modifier bits indicating which virtual modifiers are to +selected by both +<parameter>affect_real</parameter> +and +<parameter>real_values</parameter> +are added to the server’s internal modifiers control; those selected by +<parameter>affect_real</parameter> +but not by +<parameter>real_values</parameter> +are removed from the server’s internal modifiers mask. Valid values for +<parameter>affect_real</parameter> +and +<parameter>real_values</parameter> +consist of any combination of the eight core modifier bits: +<symbol>ShiftMask</symbol>, +<symbol>LockMask</symbol>, +<symbol>ControlMask</symbol>, +<symbol>Mod1Mask</symbol> +– +<symbol>Mod5Mask</symbol>. +<parameter>affect_virtual</parameter> +and +<parameter>virtual_values</parameter> +are masks of virtual modifier bits indicating which virtual modifiers are to be added and removed from the server’s internal modifiers control. Modifiers -selected by both <emphasis> -affect_virtual</emphasis> - and <emphasis> -virtual_values</emphasis> - are added to the server’s internal modifiers control; those selected by -<emphasis> -affect_virtual</emphasis> - but not by <emphasis> -virtual_values</emphasis> - are removed from the server’s internal modifiers control.<emphasis> - </emphasis> -See section 7.1 for a discussion of virtual modifier masks to use in <emphasis> <!-- xref --> -affect_virtual</emphasis> - and <emphasis> -virtual_values</emphasis> -.<emphasis> - XkbSetServerInternalMods</emphasis> - does not wait for a reply from the server. It returns <emphasis> -True</emphasis> - if the request was sent and <emphasis> -False</emphasis> - otherwise. +selected by both +<parameter>affect_virtual</parameter> +and +<parameter>virtual_values</parameter> +are added to the server’s internal modifiers control; those selected by +<parameter>affect_virtual</parameter> +but not by +<parameter>virtual_values</parameter> +are removed from the server’s internal modifiers control. +See <link linkend="Virtual_Modifier_Names_and_Masks">section 7.1</link> for a discussion of virtual modifier masks to use in +<parameter>affect_virtual</parameter> +and +<parameter>virtual_values</parameter>. +<function>XkbSetServerInternalMods</function> +does not wait for a reply from the server. It returns +<symbol>True</symbol> +if the request was sent and +<symbol>False</symbol> +otherwise. </para> @@ -3422,77 +3445,87 @@ False</emphasis> <sect1 id='The_XkbControlsRec_Structure'> <title>The XkbControlsRec Structure</title> +<indexterm significance="preferred" zone="The_XkbControlsRec_Structure"> +<primary><structname>XkbControlsRec</structname></primary></indexterm> + <para> Many of the individual controls described in sections 10.1 through 10.7 may be manipulated via convenience functions discussed in those sections. Some of -them, however, have no convenience functions. The <emphasis> -XkbControlsRec</emphasis> - structure allows the manipulation of one or more of the controls in a single -operation and to track changes to any of them in conjunction with the <emphasis> -XkbGetControls</emphasis> - and <emphasis> -XkbSetControls</emphasis> - functions. This is the only way to manipulate those controls that have no +them, however, have no convenience functions. The +<structname>XkbControlsRec</structname> +structure allows the manipulation of one or more of the controls in a single +operation and to track changes to any of them in conjunction with the +<function>XkbGetControls</function> +and +<function>XkbSetControls</function> +functions. This is the only way to manipulate those controls that have no convenience functions. </para> <para> -The <emphasis> -XkbControlsRec</emphasis> - structure is defined as follows: -</para> +The +<structname>XkbControlsRec</structname> +structure is defined as follows: -<para> <programlisting> #define XkbMaxLegalKeyCode 255 #define XkbPerKeyBitArraySize ((XkbMaxLegalKeyCode+1)/8) -</programlisting> -</para> -<para> -<programlisting> + typedef struct { - unsigned char mk_dflt_btn; /* default button for keyboard driven mouse */ - unsigned char num_groups; /* number of keyboard groups */ - unsigned char groups_wrap; /* how to wrap out-of-bounds groups */ - XkbModsRec internal; /* defines server internal modifiers */ - XkbModsRec ignore_lock; /* modifiers to ignore when checking for grab */ - unsigned int enabled_ctrls; /* 1 bit => corresponding boolean control enabled */ - unsigned short repeat_delay; /* ms delay until first repeat */ - unsigned short repeat_interval; /* ms delay between repeats */ - unsigned short slow_keys_delay; /* ms minimum time key must be down to be ok */ - unsigned short debounce_delay; /* ms delay before key reactivated */ - unsigned short mk_delay; /* ms delay to second mouse motion event */ - unsigned short mk_interval; /* ms delay between repeat mouse events */ - unsigned short mk_time_to_max; /* # intervals until constant mouse move */ - unsigned short mk_max_speed; /* multiplier for maximum mouse speed */ - short mk_curve; /* determines mouse move curve type */ - unsigned short ax_options; /* 1 bit => Access X option enabled */ - unsigned short ax_timeout; /* seconds until Access X disabled */ - unsigned short axt_opts_mask; /* 1 bit => options to reset on Access X timeout */ - unsigned short axt_opts_values; /* 1 bit => turn option on, 0=> off */ - unsigned int axt_ctrls_mask; /* which bits in <emphasis> enabled_ctrls</emphasis> to modify */ - unsigned int axt_ctrls_values; /* values for new bits in <emphasis> enabled_ctrls</emphasis> */ - unsigned char per_key_repeat[XkbPerKeyBitArraySize]; /* per key auto repeat */ -} <emphasis>XkbControlsRec</emphasis>, *XkbControlsPtr; + unsigned char mk_dflt_btn; /* default button for + keyboard driven mouse */ + unsigned char num_groups; /* number of keyboard groups */ + unsigned char groups_wrap; /* how to wrap out-of-bounds groups */ + XkbModsRec internal; /* defines server internal modifiers */ + XkbModsRec ignore_lock; /* modifiers to ignore when + checking for grab */ + unsigned int enabled_ctrls; /* 1 bit ⇒ corresponding + boolean control enabled */ + unsigned short repeat_delay; /* ms delay until first repeat */ + unsigned short repeat_interval; /* ms delay between repeats */ + unsigned short slow_keys_delay; /* ms minimum time key must be + down to be ok */ + unsigned short debounce_delay; /* ms delay before key reactivated */ + unsigned short mk_delay; /* ms delay to second mouse + motion event */ + unsigned short mk_interval; /* ms delay between repeat mouse + events */ + unsigned short mk_time_to_max; /* # intervals until constant + mouse move */ + unsigned short mk_max_speed; /* multiplier for maximum mouse speed */ + short mk_curve; /* determines mouse move curve type */ + unsigned short ax_options; /* 1 bit ⇒ Access X option enabled */ + unsigned short ax_timeout; /* seconds until Access X disabled */ + unsigned short axt_opts_mask; /* 1 bit ⇒ options to reset + on Access X timeout */ + unsigned short axt_opts_values; /* 1 bit ⇒ turn option on, 0⇒ off */ + unsigned int axt_ctrls_mask; /* which bits in <structfield>enabled_ctrls</structfield> + to modify */ + unsigned int axt_ctrls_values; /* values for new bits in + <structfield>enabled_ctrls</structfield> */ + unsigned char per_key_repeat[XkbPerKeyBitArraySize]; + /* per key auto repeat */ +} <structname>XkbControlsRec</structname>, *XkbControlsPtr; </programlisting> </para> <para> -The general-purpose functions that work with the <emphasis> -XkbControlsRec</emphasis> - structure use a mask to specify which controls are to be manipulated. Table -10.6 lists these controls, the masks used to select them in the general -function calls (<emphasis> -which</emphasis> - parameter), and the data fields in the <emphasis> -XkbControlsRec</emphasis> - structure that comprise each of the individual controls. Also listed are the +The general-purpose functions that work with the +<structname>XkbControlsRec</structname> +structure use a mask to specify which controls are to be manipulated. +<link linkend="table10.6">Table 10.6</link> +lists these controls, the masks used to select them in the general +function calls +(<structfield>which</structfield> +parameter), and the data fields in the +<structname>XkbControlsRec</structname> +structure that comprise each of the individual controls. Also listed are the bit used to turn boolean controls on and off and the section where each control is described in more detail. </para> -<table frame='topbot'> +<table id='table10.6' frame='topbot'> <title>Xkb Controls</title> <?dbfo keep-together="auto" ?> <tgroup cols='5' align='left' colsep='0' rowsep='0'> @@ -3513,21 +3546,21 @@ is described in more detail. <tbody> <row> <entry>AccessXFeedback</entry> - <entry>XkbAccessXFeedbackMask</entry> + <entry><symbol>XkbAccessXFeedbackMask</symbol></entry> <entry>ax_options: XkbAX_*FBMask</entry> <entry>XkbAccessXFeedback­Mask</entry> - <entry>10.6.3</entry> <!-- xref --> + <entry><link linkend="The_AccessXFeedback_Control">10.6.3</link></entry> </row> <row> <entry>AccessXKeys</entry> <entry></entry> <entry></entry> <entry>XkbAccessXKeys­Mask</entry> - <entry>10.6.1</entry> <!-- xref --> + <entry><link linkend="The_AccessXKeys_Control">10.6.1</link></entry> </row> <row> <entry>AccessXTimeout</entry> - <entry>XkbAccessXTimeoutMask</entry> + <entry><symbol>XkbAccessXTimeoutMask</symbol></entry> <entry> <para>ax_timeout</para> <para>axt_opts_mask</para> @@ -3536,81 +3569,81 @@ is described in more detail. <para>axt_ctrls_values</para> </entry> <entry>XkbAccessXTimeout­Mask</entry> - <entry>10.6.2</entry> + <entry><link linkend="The_AccessXTimeout_Control">10.6.2</link></entry> </row> <row> <entry>AudibleBell</entry> <entry></entry> <entry></entry> - <entry>XkbAudibleBellMask</entry> - <entry>9.2</entry> + <entry><symbol>XkbAudibleBellMask</symbol></entry> + <entry><link linkend="Audible_Bells">9.2</link></entry> </row> <row> <entry>AutoReset</entry> <entry></entry> <entry></entry> <entry></entry> - <entry>10.1.2</entry> + <entry><link linkend="The_AutoReset_Control">10.1.2</link></entry> </row> <row> <entry>BounceKeys</entry> - <entry>XkbBounceKeysMask</entry> + <entry><symbol>XkbBounceKeysMask</symbol></entry> <entry>debounce_delay</entry> - <entry>XkbBounceKeysMask</entry> - <entry>10.6.7</entry> + <entry><symbol>XkbBounceKeysMask</symbol></entry> + <entry><link linkend="The_BounceKeys_Control">10.6.7</link></entry> </row> <row> <entry>Detectable-Autorepeat</entry> <entry></entry> <entry></entry> <entry></entry> - <entry>10.3.3</entry> + <entry><link linkend="The_DetectableAutorepeat_Control">10.3.3</link></entry> </row> <row> <entry>EnabledControls</entry> - <entry>XkbControlsEnabledMask</entry> + <entry><symbol>XkbControlsEnabledMask</symbol></entry> <entry>enabled_ctrls</entry> <entry><emphasis>Non-Boolean Control</emphasis></entry> - <entry>10.1.1</entry> + <entry><link linkend="The_EnabledControls_Control">10.1.1</link></entry> </row> <row> <entry>GroupsWrap</entry> - <entry>XkbGroupsWrapMask</entry> + <entry><symbol>XkbGroupsWrapMask</symbol></entry> <entry>groups_wrap</entry> <entry><emphasis>Non-Boolean Control</emphasis></entry> - <entry>10.7.1</entry> + <entry><link linkend="The_GroupsWrap_Control">10.7.1</link></entry> </row> <row> <entry>IgnoreGroupLock</entry> <entry></entry> <entry></entry> <entry>XkbIgnoreGroupLock­Mask</entry> - <entry>10.7.3</entry> + <entry><link linkend="The_IgnoreGroupLock_Control">10.7.3</link></entry> </row> <row> <entry>IgnoreLockMods</entry> - <entry>XkbIgnoreLockModsMask</entry> + <entry><symbol>XkbIgnoreLockModsMask</symbol></entry> <entry>ignore_lock</entry> <entry><emphasis>Non-Boolean Control</emphasis></entry> - <entry>5.1</entry> + <entry><link linkend="Keyboard_State_Description">5.1</link></entry> </row> <row> <entry>InternalMods</entry> - <entry>XkbInternalModsMask</entry> + <entry><symbol>XkbInternalModsMask</symbol></entry> <entry>internal</entry> <entry><emphasis>Non-Boolean Control</emphasis></entry> - <entry>5.1</entry> + <entry><link linkend="Keyboard_State_Description">5.1</link></entry> </row> <row> <entry>MouseKeys</entry> - <entry>XkbMouseKeysMask</entry> + <entry><symbol>XkbMouseKeysMask</symbol></entry> <entry>mk_dflt_btn</entry> - <entry>XkbMouseKeysMask</entry> - <entry>10.5.1</entry> + <entry><symbol>XkbMouseKeysMask</symbol></entry> + <entry><link linkend="The_MouseKeys_Control">10.5.1</link></entry> </row> <row> <entry>MouseKeysAccel</entry> - <entry>XkbMouseKeysAccelMask</entry> + <entry><symbol>XkbMouseKeysAccelMask</symbol></entry> <entry> <para>mk_delay</para> <para>mk_interval</para> @@ -3619,75 +3652,76 @@ is described in more detail. <para>mk_curve</para> </entry> <entry>XkbMouseKeysAccel­Mask</entry> - <entry>10.5.2</entry> + <entry><link linkend="The_MouseKeysAccel_Control">10.5.2</link></entry> </row> <row> <entry>Overlay1</entry> <entry></entry> <entry></entry> - <entry>XkbOverlay1Mask</entry> - <entry>10.4</entry> + <entry><symbol>XkbOverlay1Mask</symbol></entry> + <entry><link linkend="Controls_for_Keyboard_Overlays_Overlay1_and_Overlay2_Controls">10.4</link></entry> </row> <row> <entry>Overlay2</entry> <entry></entry> <entry></entry> - <entry>XkbOverlay2Mask</entry> - <entry>10.4</entry> + <entry><symbol>XkbOverlay2Mask</symbol></entry> + <entry><link linkend="Controls_for_Keyboard_Overlays_Overlay1_and_Overlay2_Controls">10.4</link></entry> </row> <row> <entry>PerKeyRepeat</entry> - <entry>XkbPerKeyRepeatMask</entry> + <entry><symbol>XkbPerKeyRepeatMask</symbol></entry> <entry>per_key_repeat</entry> <entry><emphasis>Non-Boolean Control</emphasis></entry> - <entry>10.3.1</entry> + <entry><link linkend="The_PerKeyRepeat_Control">10.3.1</link></entry> </row> <row> <entry>RepeatKeys</entry> - <entry>XkbRepeatKeysMask</entry> + <entry><symbol>XkbRepeatKeysMask</symbol></entry> <entry> <para>repeat_delay</para> <para>repeat_interval</para> </entry> - <entry>XkbRepeatKeysMask</entry> - <entry>10.3</entry> + <entry><symbol>XkbRepeatKeysMask</symbol></entry> + <entry><link linkend="Controls_for_Repeat_Key_Behavior">10.3</link></entry> </row> <row> <entry>SlowKeys</entry> - <entry>XkbSlowKeysMask</entry> + <entry><symbol>XkbSlowKeysMask</symbol></entry> <entry>slow_keys_delay</entry> - <entry>XkbSlowKeysMask</entry> - <entry>10.6.6</entry> + <entry><symbol>XkbSlowKeysMask</symbol></entry> + <entry><link linkend="The_SlowKeys_Control">10.6.6</link></entry> </row> <row> <entry>StickyKeys</entry> - <entry>XkbStickyKeysMask</entry> + <entry><symbol>XkbStickyKeysMask</symbol></entry> <entry> <para>ax_options:</para> <para>XkbAX_Two­KeysMask</para> <para>XkbAX_Latch­ToLockMask</para> </entry> - <entry>XkbStickyKeysMask</entry> - <entry>10.6.8</entry> + <entry><symbol>XkbStickyKeysMask</symbol></entry> + <entry><link linkend="The_StickyKeys_Control">10.6.8</link></entry> </row> </tbody> </tgroup> </table> <para> -Table 10.7 shows the actual values for the individual mask bits used to select <!-- xref --> +<link linkend="table10.7">Table 10.7</link> +shows the actual values for the individual mask bits used to select controls for modification and to enable and disable the control. Note that the same mask bit is used to specify general modifications to the parameters used -to configure the control (<emphasis> -which</emphasis> -), and to enable and disable the control (<emphasis> -enabled_ctrls</emphasis> -). The anomalies in the table (no "ok" in column) are for controls that have no +to configure the control +(<structfield>which</structfield>), +and to enable and disable the control +(<structfield>enabled_ctrls</structfield>). +The anomalies in the table (no <quote>ok</quote> in column) are for controls that have no configurable attributes; and for controls that are not boolean controls and therefore cannot be enabled or disabled. </para> -<table frame='topbot'> +<table id='table10.7' frame='topbot'> <title>Controls Mask Bits</title> <?dbfo keep-together="always" ?> <tgroup cols='4' align='left' colsep='0' rowsep='0'> @@ -3705,127 +3739,127 @@ therefore cannot be enabled or disabled. </thead> <tbody> <row> - <entry>XkbRepeatKeysMask</entry> + <entry><symbol>XkbRepeatKeysMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(1L<<0)</entry> </row> <row> - <entry>XkbSlowKeysMask</entry> + <entry><symbol>XkbSlowKeysMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(1L<<1)</entry> </row> <row> - <entry>XkbBounceKeysMask</entry> + <entry><symbol>XkbBounceKeysMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(1L<<2)</entry> </row> <row> - <entry>XkbStickyKeysMask</entry> + <entry><symbol>XkbStickyKeysMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(1L<<3)</entry> </row> <row> - <entry>XkbMouseKeysMask</entry> + <entry><symbol>XkbMouseKeysMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(1L<<4)</entry> </row> <row> - <entry>XkbMouseKeysAccelMask</entry> + <entry><symbol>XkbMouseKeysAccelMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(1L<<5)</entry> </row> <row> - <entry>XkbAccessXKeysMask</entry> + <entry><symbol>XkbAccessXKeysMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(1L<<6)</entry> </row> <row> - <entry>XkbAccessXTimeoutMask</entry> + <entry><symbol>XkbAccessXTimeoutMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(1L<<7)</entry> </row> <row> - <entry>XkbAccessXFeedbackMask</entry> + <entry><symbol>XkbAccessXFeedbackMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(1L<<8)</entry> </row> <row> - <entry>XkbAudibleBellMask</entry> + <entry><symbol>XkbAudibleBellMask</symbol></entry> <entry></entry> <entry>ok</entry> <entry>(1L<<9)</entry> </row> <row> - <entry>XkbOverlay1Mask</entry> + <entry><symbol>XkbOverlay1Mask</symbol></entry> <entry></entry> <entry>ok</entry> <entry>(1L<<10)</entry> </row> <row> - <entry>XkbOverlay2Mask</entry> + <entry><symbol>XkbOverlay2Mask</symbol></entry> <entry></entry> <entry>ok</entry> <entry>(1L<<11)</entry> </row> <row> - <entry>XkbIgnoreGroupLockMask</entry> + <entry><symbol>XkbIgnoreGroupLockMask</symbol></entry> <entry></entry> <entry>ok</entry> <entry>(1L<<12)</entry> </row> <row> - <entry>XkbGroupsWrapMask</entry> + <entry><symbol>XkbGroupsWrapMask</symbol></entry> <entry>ok</entry> <entry></entry> <entry>(1L<<27)</entry> </row> <row> - <entry>XkbInternalModsMask</entry> + <entry><symbol>XkbInternalModsMask</symbol></entry> <entry>ok</entry> <entry></entry> <entry>(1L<<28)</entry> </row> <row> - <entry>XkbIgnoreLockModsMask</entry> + <entry><symbol>XkbIgnoreLockModsMask</symbol></entry> <entry>ok</entry> <entry></entry> <entry>(1L<<29)</entry> </row> <row> - <entry>XkbPerKeyRepeatMask</entry> + <entry><symbol>XkbPerKeyRepeatMask</symbol></entry> <entry>ok</entry> <entry></entry> <entry>(1L<<30)</entry> </row> <row> - <entry>XkbControlsEnabledMask</entry> + <entry><symbol>XkbControlsEnabledMask</symbol></entry> <entry>ok</entry> <entry></entry> <entry>(1L<<31)</entry> </row> <row> - <entry>XkbAccessXOptionsMask</entry> + <entry><symbol>XkbAccessXOptionsMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(XkbStickyKeysMask | XkbAccessXFeedbackMask)</entry> </row> <row> - <entry>XkbAllBooleanCtrlsMask</entry> + <entry><symbol>XkbAllBooleanCtrlsMask</symbol></entry> <entry></entry> <entry>ok</entry> <entry>(0x00001FFF) </entry> </row> <row> - <entry>XkbAllControlsMask</entry> + <entry><symbol>XkbAllControlsMask</symbol></entry> <entry>ok</entry> <entry></entry> <entry>(0xF8001FFF)</entry> @@ -3835,9 +3869,9 @@ therefore cannot be enabled or disabled. </table> <para> -The individual fields of the <emphasis> -XkbControlsRec</emphasis> - structure are defined as follows. +The individual fields of the +<structname>XkbControlsRec</structname> +structure are defined as follows. </para> <sect2> @@ -3846,20 +3880,15 @@ XkbControlsRec</emphasis> <title>mk_dflt_btn</title> <para> -<emphasis> -mk_dflt_btn is an attribute of the </emphasis> -<emphasis> -MouseKeys</emphasis> -<emphasis> - control</emphasis> - (see section 10.5<emphasis> <!-- xref --> -). It</emphasis> - specifies the mouse button number to use for keyboard simulated mouse button -operations. Its value should be one of the core symbols <emphasis> -Button1</emphasis> - - <emphasis> -Button5</emphasis> -. +<structfield>mk_dflt_btn</structfield> is an attribute of the +<emphasis>MouseKeys</emphasis> +control +(see <link linkend="Controls_for_Using_the_Mouse_from_the_Keyboard">section 10.5</link>). It +specifies the mouse button number to use for keyboard simulated mouse button +operations. Its value should be one of the core symbols +<symbol>Button1</symbol> +– +<symbol>Button5</symbol>. </para> @@ -3868,11 +3897,10 @@ Button5</emphasis> <title>num_groups</title> <para> -<emphasis> -num_groups</emphasis> - is not a part of any control, but is reported in the <emphasis> -XkbControlsRec</emphasis> - structure whenever any of its components are fetched from the server. It +<structfield>num_groups</structfield> +is not a part of any control, but is reported in the +<structname>XkbControlsRec</structname> +structure whenever any of its components are fetched from the server. It reports the number of groups the particular keyboard configuration uses and is computed automatically by the server whenever the keyboard mapping changes. </para> @@ -3883,17 +3911,16 @@ computed automatically by the server whenever the keyboard mapping changes. <title>groups_wrap</title> <para> -<emphasis> -groups_wrap</emphasis> - is an attribute of the <emphasis> -GroupsWrap</emphasis> - control (see section 10.7.1). It specifies the handling of illegal groups on a <!-- xref --> -global basis. Valid values for <emphasis> -groups_wrap</emphasis> - are shown in Table 10.8. +<structfield>groups_wrap</structfield> +is an attribute of the +<emphasis>GroupsWrap</emphasis> +control (see <link linkend="The_GroupsWrap_Control">section 10.7.1</link>). It specifies the handling of illegal groups on a +global basis. Valid values for +<structfield>groups_wrap</structfield> +are shown in <link linkend="table10.8">Table 10.8</link>. </para> -<table frame='topbot'> +<table id='table10.8' frame='topbot'> <title>GroupsWrap options (groups_wrap field)</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -3907,15 +3934,15 @@ groups_wrap</emphasis> </thead> <tbody> <row> - <entry>XkbWrapIntoRange</entry> + <entry><symbol>XkbWrapIntoRange</symbol></entry> <entry>(0x00)</entry> </row> <row> - <entry>XkbClampIntoRange</entry> + <entry><symbol>XkbClampIntoRange</symbol></entry> <entry>(0x40)</entry> </row> <row> - <entry>XkbRedirectIntoRange</entry> + <entry><symbol>XkbRedirectIntoRange</symbol></entry> <entry>(0x80)</entry> </row> </tbody> @@ -3923,11 +3950,11 @@ groups_wrap</emphasis> </table> <para> -When <emphasis> -groups_wrap</emphasis> - is set to <emphasis> -XkbRedirectIntoRange</emphasis> -, its four low-order bits specify the index of the group to use. +When +<structfield>groups_wrap</structfield> +is set to +<symbol>XkbRedirectIntoRange</symbol>, +its four low-order bits specify the index of the group to use. </para> @@ -3936,23 +3963,18 @@ XkbRedirectIntoRange</emphasis> <title>internal</title> <para> -<emphasis> -internal</emphasis> - is an attribute of the <emphasis> -InternalMods</emphasis> - control (see section 10.7.4). It specifies modifiers to be consumed in the <!-- xref --> +<structfield>internal</structfield> +is an attribute of the +<emphasis>InternalMods</emphasis> +control (see <link linkend="The_InternalMods_Control">section 10.7.4</link>). It specifies modifiers to be consumed in the server and not passed on to clients when events are reported. Valid values -consist of any combination of the eight core modifier bits: <emphasis> -ShiftMask</emphasis> -, <emphasis> -LockMask</emphasis> -, <emphasis> -ControlMask</emphasis> -, <emphasis> -Mod1Mask</emphasis> - - <emphasis> -Mod5Mask</emphasis> -. +consist of any combination of the eight core modifier bits: +<symbol>ShiftMask</symbol>, +<symbol>LockMask</symbol>, +<symbol>ControlMask</symbol>, +<symbol>Mod1Mask</symbol> +– +<symbol>Mod5Mask</symbol>. </para> @@ -3961,23 +3983,18 @@ Mod5Mask</emphasis> <title>ignore_lock</title> <para> -<emphasis> -ignore_lock</emphasis> - is an attribute of the <emphasis> -IgnoreLockMods</emphasis> - control (see section 10.7.2). It specifies modifiers to be ignored in grab <!-- xref --> +<structfield>ignore_lock</structfield> +is an attribute of the +<emphasis>IgnoreLockMods</emphasis> +control (see <link linkend="The_IgnoreLockMods_Control">section 10.7.2</link>). It specifies modifiers to be ignored in grab calculations. Valid values consist of any combination of the eight core -modifier bits: <emphasis> -ShiftMask</emphasis> -, <emphasis> -LockMask</emphasis> -, <emphasis> -ControlMask</emphasis> -, <emphasis> -Mod1Mask</emphasis> - - <emphasis> -Mod5Mask</emphasis> -. +modifier bits: +<symbol>ShiftMask</symbol>, +<symbol>LockMask</symbol>, +<symbol>ControlMask</symbol>, +<symbol>Mod1Mask</symbol> +– +<symbol>Mod5Mask</symbol>. </para> @@ -3986,16 +4003,16 @@ Mod5Mask</emphasis> <title>enabled_ctrls</title> <para> -<emphasis> -enabled_ctrls</emphasis> - is an attribute of the <emphasis> -EnabledControls</emphasis> - control (see section 10.1.1). It contains one bit per boolean control. Each <!-- xref --> +<structfield>enabled_ctrls</structfield> +is an attribute of the +<emphasis>EnabledControls</emphasis> +control (see <link linkend="The_EnabledControls_Control">section 10.1.1</link>). It contains one bit per boolean control. Each bit determines whether the corresponding control is enabled or disabled; a one bit means the control is enabled. The mask bits used to enable these controls -are listed in Table 10.7, using only those masks with "ok" in the <emphasis> -enabled_ctrls</emphasis> - column. +are listed in <link linkend="table10.7">Table 10.7</link>, +using only those masks with <quote>ok</quote> in the +<structfield>enabled_ctrls</structfield> +column. </para> @@ -4004,17 +4021,16 @@ enabled_ctrls</emphasis> <title>repeat_delay and repeat_interval</title> <para> -<emphasis> -repeat_delay</emphasis> - and <emphasis> -repeat_interval</emphasis> - are attributes of the <emphasis> -RepeatKeys</emphasis> - control (see section 10.3.2). <emphasis> <!-- xref --> -repeat_delay</emphasis> - is the initial delay before a key begins repeating, in milliseconds; <emphasis> -repeat_interval</emphasis> - is the delay between subsequent key events, in milliseconds. +<structfield>repeat_delay</structfield> +and +<structfield>repeat_interval</structfield> +are attributes of the +<emphasis>RepeatKeys</emphasis> +control (see <link linkend="The_RepeatKeys_Control">section 10.3.2</link>). +<structfield>repeat_delay</structfield> +is the initial delay before a key begins repeating, in milliseconds; +<structfield>repeat_interval</structfield> +is the delay between subsequent key events, in milliseconds. </para> @@ -4023,13 +4039,12 @@ repeat_interval</emphasis> <title>slow_keys_delay</title> <para> -<emphasis> -slow_keys_delay</emphasis> - is an attribute of the <emphasis> -SlowKeys</emphasis> - control (see section 10.6.6). Its value specifies the <emphasis> <!-- xref --> -SlowKeys</emphasis> - acceptance delay period in milliseconds before a key press is accepted by the +<structfield>slow_keys_delay</structfield> +is an attribute of the +<emphasis>SlowKeys</emphasis> +control (see <link linkend="The_SlowKeys_Control">section 10.6.6</link>). Its value specifies the +<emphasis>SlowKeys</emphasis> +acceptance delay period in milliseconds before a key press is accepted by the server. </para> @@ -4039,13 +4054,12 @@ server. <title>debounce_delay</title> <para> -<emphasis> -debounce_delay</emphasis> - is an attribute of the <emphasis> -BounceKeys</emphasis> - control (see section 10.6.7). Its value specifies the <emphasis> <!-- xref --> -BounceKeys</emphasis> - delay period in milliseconds for which the key is disabled after having been +<structfield>debounce_delay</structfield> +is an attribute of the +<emphasis>BounceKeys</emphasis> +control (see <link linkend="The_BounceKeys_Control">section 10.6.7</link>). Its value specifies the +<emphasis>BounceKeys</emphasis> +delay period in milliseconds for which the key is disabled after having been pressed before another press of the same key is accepted by the server. </para> @@ -4055,19 +4069,15 @@ pressed before another press of the same key is accepted by the server. <title>mk_delay, mk_interval, mk_time_to_max, mk_max_speed, and mk_curve</title> <para> -<emphasis> -mk_delay</emphasis> -, <emphasis> -mk_interval</emphasis> -, <emphasis> -mk_time_to_max</emphasis> -, <emphasis> -mk_max_speed</emphasis> -, and <emphasis> -mk_curve</emphasis> - are attributes of the <emphasis> -MouseKeysAccel</emphasis> - control. Refer to section 10.5.2 for a description of these fields and the <!-- xref --> +<structfield>mk_delay</structfield>, +<structfield>mk_interval</structfield>, +<structfield>mk_time_to_max</structfield>, +<structfield>mk_max_speed</structfield>, +and +<structfield>mk_curve</structfield> +are attributes of the +<emphasis>MouseKeysAccel</emphasis> +control. Refer to <link linkend="The_MouseKeysAccel_Control">section 10.5.2</link> for a description of these fields and the units involved. </para> @@ -4077,20 +4087,19 @@ units involved. <title>ax_options</title> <para> -The <emphasis> -ax_options</emphasis> - field contains attributes used to configure two different controls, the -<emphasis> -StickyKeys</emphasis> - control (see section 10.6.8) and the <emphasis> <!-- xref --> -AccessXFeedback</emphasis> - control (see section 10.6.3). The <emphasis> <!-- xref --> -ax_options</emphasis> - field is a bitmask and may include any combination of the bits defined in -Table 10.9. <!-- xref --> +The +<structfield>ax_options</structfield> +field contains attributes used to configure two different controls, the +<emphasis>StickyKeys</emphasis> +control (see <link linkend="The_StickyKeys_Control">section 10.6.8</link>) and the +<emphasis>AccessXFeedback</emphasis> +control (see <link linkend="The_AccessXFeedback_Control">section 10.6.3</link>). The +<structfield>ax_options</structfield> +field is a bitmask and may include any combination of the bits defined in +<link linkend="table10.9">Table 10.9</link>. </para> -<table frame='topbot'> +<table id='table10.9' frame='topbot'> <title>Access X Enable/Disable Bits (ax_options field)</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -4107,67 +4116,67 @@ Table 10.9. <!-- xref --> <tbody> <row> <entry>AccessXFeedback</entry> - <entry>XkbAX_SKPressFBMask</entry> + <entry><symbol>XkbAX_SKPressFBMask</symbol></entry> <entry>(1L<<0)</entry> </row> <row> <entry></entry> - <entry>XkbAX_SKAcceptFBMask</entry> + <entry><symbol>XkbAX_SKAcceptFBMask</symbol></entry> <entry>(1L << 1)</entry> </row> <row> <entry></entry> - <entry>XkbAX_FeatureFBMask</entry> + <entry><symbol>XkbAX_FeatureFBMask</symbol></entry> <entry>(1L << 2)</entry> </row> <row> <entry></entry> - <entry>XkbAX_SlowWarnFBMask</entry> + <entry><symbol>XkbAX_SlowWarnFBMask</symbol></entry> <entry>(1L << 3)</entry> </row> <row> <entry></entry> - <entry>XkbAX_IndicatorFBMask</entry> + <entry><symbol>XkbAX_IndicatorFBMask</symbol></entry> <entry>(1L << 4)</entry> </row> <row> <entry></entry> - <entry>XkbAX_StickyKeysFBMask</entry> + <entry><symbol>XkbAX_StickyKeysFBMask</symbol></entry> <entry>(1L << 5)</entry> </row> <row> <entry></entry> - <entry>XkbAX_SKReleaseFBMask</entry> + <entry><symbol>XkbAX_SKReleaseFBMask</symbol></entry> <entry>(1L << 8)</entry> </row> <row> <entry></entry> - <entry>XkbAX_SKRejectFBMask</entry> + <entry><symbol>XkbAX_SKRejectFBMask</symbol></entry> <entry>(1L << 9)</entry> </row> <row> <entry></entry> - <entry>XkbAX_BKRejectFBMask</entry> + <entry><symbol>XkbAX_BKRejectFBMask</symbol></entry> <entry>(1L << 10)</entry> </row> <row> <entry></entry> - <entry>XkbAX_DumbBellFBMask</entry> + <entry><symbol>XkbAX_DumbBellFBMask</symbol></entry> <entry>(1L << 11)</entry> </row> <row> <entry>StickyKeys</entry> - <entry>XkbAX_TwoKeysMask</entry> + <entry><symbol>XkbAX_TwoKeysMask</symbol></entry> <entry>(1L << 6)</entry> </row> <row> <entry></entry> - <entry>XkbAX_LatchToLockMask</entry> + <entry><symbol>XkbAX_LatchToLockMask</symbol></entry> <entry>(1L << 7)</entry> </row> <row> <entry></entry> - <entry>XkbAX_AllOptionsMask</entry> + <entry><symbol>XkbAX_AllOptionsMask</symbol></entry> <entry>(0xFFF)</entry> </row> </tbody> @@ -4176,100 +4185,93 @@ Table 10.9. <!-- xref --> <para> The fields pertaining to each control are relevant only when the control is -enabled (<emphasis> -XkbAccessXFeedbackMask</emphasis> - or <emphasis> -XkbStickyKeysMask</emphasis> - bit is turned on in the <emphasis> -enabled_cntrls</emphasis> - field). +enabled +(<symbol>XkbAccessXFeedbackMask</symbol> +or +<symbol>XkbStickyKeysMask</symbol> +bit is turned on in the +<structfield>enabled_ctrls</structfield> +field). </para> <para> -Xkb provides a set of convenience macros for working with the <emphasis> -ax_options</emphasis> - field of an <emphasis> -XkbControlsRec</emphasis> - structure: -</para> +Xkb provides a set of convenience macros for working with the +<structfield>ax_options</structfield> +field of an +<structname>XkbControlsRec</structname> +structure: -<para><programlisting> -#define <emphasis>XkbAX_NeedOption</emphasis> -(c,w) ((c)->ax_options&(w)) +<programlisting> +#define <symbol>XkbAX_NeedOption</symbol>(c,w) ((c)->ax_options & (w)) </programlisting></para> <para> -The <emphasis> -XkbAX_NeedOption</emphasis> - macro is useful for determining whether a particular AccessX option is enabled -or not. It accepts a pointer to an <emphasis> -XkbControlsRec</emphasis> - structure and a valid mask bit from Table 10.9. If the specified mask bit in -the <emphasis> -ax_options</emphasis> - field of the controls structure is set, the macro returns the mask bit. +The +<symbol>XkbAX_NeedOption</symbol> +macro is useful for determining whether a particular AccessX option is enabled +or not. It accepts a pointer to an +<structname>XkbControlsRec</structname> +structure and a valid mask bit from +<link linkend="table10.9">Table 10.9</link>. +If the specified mask bit in the +<structfield>ax_options</structfield> +field of the controls structure is set, the macro returns the mask bit. Otherwise, it returns zero. Thus, -</para> - - -<para> -XkbAX_NeedOption(ctlrec, XkbAX_LatchToLockMask) -</para> +<programlisting> + XkbAX_NeedOption(ctlrec, XkbAX_LatchToLockMask) +</programlisting> -<para> is nonzero if the latch to lock transition for latching keys is enabled, and -zero if it is disabled. Note that <emphasis> -XkbAX_NeedOption</emphasis> - only determines whether or not the particular capability is configured to -operate; the <emphasis> -XkbAccessXFeedbackMask</emphasis> - bit must also be turned on in <emphasis> -enabled_ctrls</emphasis> - for the capability to actually be functioning. +zero if it is disabled. Note that +<symbol>XkbAX_NeedOption</symbol> +only determines whether or not the particular capability is configured to +operate; the +<symbol>XkbAccessXFeedbackMask</symbol> +bit must also be turned on in +<structfield>enabled_ctrls</structfield> +for the capability to actually be functioning. </para> <para><programlisting> -#define <emphasis>XkbAX_AnyFeedback</emphasis> -(c) ((c)->enabled_ctrls&XkbAccessXFeedbackMask) +#define <symbol>XkbAX_AnyFeedback</symbol>(c) \ + ((c)->enabled_ctrls & XkbAccessXFeedbackMask) </programlisting></para> <para> -The <emphasis> -XkbAX_AnyFeeback</emphasis> - macro accepts a pointer to an <emphasis> -XkbControlsRec</emphasis> - structure and tells whether the <emphasis> -AccessXFeedback</emphasis> - control is enabled or not. If the <emphasis> -AccessXFeedback</emphasis> - control is enabled, the macro returns <emphasis> -XkbAccessXFeedbackMask</emphasis> -. Otherwise, it returns zero. +The +<symbol>XkbAX_AnyFeedback</symbol> +macro accepts a pointer to an +<structname>XkbControlsRec</structname> +structure and tells whether the +<emphasis>AccessXFeedback</emphasis> +control is enabled or not. If the +<emphasis>AccessXFeedback</emphasis> +control is enabled, the macro returns +<symbol>XkbAccessXFeedbackMask</symbol>. +Otherwise, it returns zero. </para> <para><programlisting> -#define <emphasis>XkbAX_NeedFeedback</emphasis> -(c,w) (XkbAX_AnyFeedback(c)&&XkbAX_NeedOption(c,w)) +#define <symbol>XkbAX_NeedFeedback</symbol>(c,w) \ + (XkbAX_AnyFeedback(c) && XkbAX_NeedOption(c,w)) </programlisting></para> <para> -The <emphasis> -XkbAX_NeedFeedback</emphasis> - macro is useful for determining if both the <emphasis> -AccessXFeedback</emphasis> - control and a particular AccessX feedback option are enabled. The macro -accepts a pointer to an <emphasis> -XkbControlsRec</emphasis> - structure and a feedback option from the table above. If both the <emphasis> -AccessXFeedback</emphasis> - control and the specified feedback option are enabled, the macro returns -<emphasis> -True</emphasis> -. Otherwise it returns <emphasis> -False</emphasis> -. +The +<symbol>XkbAX_NeedFeedback</symbol> +macro is useful for determining if both the +<emphasis>AccessXFeedback</emphasis> +control and a particular AccessX feedback option are enabled. The macro +accepts a pointer to an +<structname>XkbControlsRec</structname> +structure and a feedback option from the table above. If both the +<emphasis>AccessXFeedback</emphasis> +control and the specified feedback option are enabled, the macro returns +<symbol>True</symbol>. +Otherwise it returns +<symbol>False</symbol>. </para> @@ -4279,19 +4281,15 @@ id='ax_timeout_axt_opts_mask_axt_opts_values_axt_ctrls_mask_and_axt_ctrls_values <title>ax_timeout, axt_opts_mask, axt_opts_values, axt_ctrls_mask, and axt_ctrls_values</title> <para> -<emphasis> -ax_timeout</emphasis> -, <emphasis> -act_opts_mask</emphasis> -, <emphasis> -axt_opts_values</emphasis> -, <emphasis> -axt_ctrls_mask</emphasis> -, and <emphasis> -axt_ctrls_values</emphasis> - are attributes of the <emphasis> -AccessXTimeout</emphasis> - control. Refer to section 10.6.2 for a description of these fields and the <!-- xref --> +<structfield>ax_timeout</structfield>, +<structfield>axt_opts_mask</structfield>, +<structfield>axt_opts_values</structfield>, +<structfield>axt_ctrls_mask</structfield>, +and +<structfield>axt_ctrls_values</structfield> +are attributes of the +<emphasis>AccessXTimeout</emphasis> +control. Refer to <link linkend="The_AccessXTimeout_Control">section 10.6.2</link> for a description of these fields and the units involved. </para> @@ -4301,30 +4299,30 @@ units involved. <title>per_key_repeat</title> <para> -The <emphasis> -per_key_repeat</emphasis> - field mirrors the <emphasis> -auto_repeats</emphasis> - field of the core protocol <emphasis> -XKeyboardState</emphasis> - structure: changing the <emphasis> -auto_repeats</emphasis> - field automatically changes <emphasis> -per_key_repeat</emphasis> - and vice versa. It is provided for convenience and to reduce protocol traffic. +The +<structfield>per_key_repeat</structfield> +field mirrors the +<structfield>auto_repeats</structfield> +field of the core protocol +<structname>XKeyboardState</structname> +structure: changing the +<structfield>auto_repeats</structfield> +field automatically changes +<structfield>per_key_repeat</structfield> +and vice versa. It is provided for convenience and to reduce protocol traffic. For example, to obtain the individual repeat key behavior as well as the repeat -delay and rate, use <emphasis> -XkbGetControls</emphasis> -. If the <emphasis> -per_key_repeat</emphasis> - were not in this structure, you would have to call both <emphasis> -XGetKeyboardControl</emphasis> - and <emphasis> -XkbGetControls</emphasis> - to get this information. The bits correspond to keycodes. The first seven keys -(keycodes 1-7) are indicated in <emphasis> -per_key_repeat</emphasis> -[0], with bit position 0 (low order) corresponding to the fictitious keycode 0. +delay and rate, use +<function>XkbGetControls</function>. +If the +<structfield>per_key_repeat</structfield> +were not in this structure, you would have to call both +<function>XGetKeyboardControl</function> +and +<function>XkbGetControls</function> +to get this information. The bits correspond to keycodes. The first seven keys +(keycodes 1–7) are indicated in +<structfield>per_key_repeat</structfield>[0], +with bit position 0 (low order) corresponding to the fictitious keycode 0. Following array elements correspond to 8 keycodes per element. A 1 bit indicates that the key is a repeating key. </para> @@ -4337,404 +4335,395 @@ indicates that the key is a repeating key. <title>Querying Controls</title> <para> -Use <emphasis> -XkbGetControls</emphasis> - to find the current state of Xkb server controls. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetControls</emphasis> -(<emphasis> -display, which, xkb)</emphasis> - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned long<emphasis> - which</emphasis> -; /* mask of controls requested */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr<emphasis> - xkb</emphasis> -; /* keyboard description for controls information*/ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetControls</emphasis> - queries the server for the requested control information, waits for a reply, +Use +<function>XkbGetControls</function> +to find the current state of Xkb server controls. +</para> + +<indexterm significance="preferred" zone="XkbGetControls"><primary><function>XkbGetControls</function></primary></indexterm> +<funcsynopsis id="XkbGetControls"> + <funcprototype> + <funcdef>Status <function>XkbGetControls</function></funcdef> +<!-- ( +<parameter>display, which, xkb)</parameter> --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned long <parameter>which</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of controls requested + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description for controls information + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetControls</function> +queries the server for the requested control information, waits for a reply, and then copies the server’s values for the requested information into the -<emphasis> -ctrls</emphasis> - structure of the <emphasis> -xkb</emphasis> - argument. Only those components specified by the <emphasis> -which</emphasis> - parameter are copied. Valid values for <emphasis> -which</emphasis> - are any combination of the masks listed in Table 10.7 that have "ok" in the -<emphasis> -which</emphasis> - column. -</para> - - -<para> -If <emphasis> -xkb</emphasis> --><emphasis> -ctrls </emphasis> -is <emphasis> -NULL</emphasis> -, <emphasis> -XkbGetControls</emphasis> - allocates and initializes it before obtaining the values specified by -<emphasis> -which</emphasis> -. If <emphasis> -xkb</emphasis> --><emphasis> -ctrls</emphasis> - is not <emphasis> -NULL</emphasis> -, <emphasis> -XkbGetControls</emphasis> - modifies only those portions of <emphasis> -xkb</emphasis> --><emphasis> -ctrls</emphasis> - corresponding to the values specified by <emphasis> -which</emphasis> -. -</para> - - -<para> -<emphasis> -XkbGetControls</emphasis> - returns <emphasis> -Success</emphasis> - if successful; otherwise, it returns <emphasis> -BadAlloc</emphasis> - if it cannot obtain sufficient storage, <emphasis> -BadMatch</emphasis> - if <emphasis> -xkb</emphasis> - is <emphasis> -NULL</emphasis> - or <emphasis> -which</emphasis> - is empty, or <emphasis> -BadImplementation</emphasis> -. -</para> - - -<para> -To free the <emphasis> -ctrls</emphasis> - member of a keyboard description, use <emphasis> -XkbFreeControls</emphasis> - (see section 10.12) -</para> - - -<para> -The <emphasis> -num_groups</emphasis> - field in the <emphasis> -ctrls</emphasis> - structure is always filled in by <emphasis> -XkbGetControls</emphasis> -, regardless of which bits are selected by <emphasis> -which</emphasis> -. +<structfield>ctrls</structfield> +structure of the +<parameter>xkb</parameter> +argument. Only those components specified by the +<parameter>which</parameter> +parameter are copied. Valid values for +<parameter>which</parameter> +are any combination of the masks listed in +<link linkend="table10.7">Table 10.7</link> that have <quote>ok</quote> in the +<parameter>which</parameter> +column. </para> -</sect1> -<sect1 id='Changing_Controls'> -<title>Changing Controls</title> - <para> -There are two ways to make changes to controls: either change a local copy -keyboard description and call <emphasis> -XkbSetControls</emphasis> -, or, to reduce network traffic, use an<emphasis> - XkbControlsChangesRec</emphasis> - structure and call <emphasis> -XkbChangeControls</emphasis> -. +If +<parameter>xkb</parameter>-><structfield>ctrls</structfield> +is +<symbol>NULL</symbol>, +<function>XkbGetControls</function> +allocates and initializes it before obtaining the values specified by +<parameter>which</parameter>. +If +<parameter>xkb</parameter>-><structfield>ctrls</structfield> +is not +<symbol>NULL</symbol>, +<function>XkbGetControls</function> +modifies only those portions of +<parameter>xkb</parameter>-><structfield>ctrls</structfield> +corresponding to the values specified by +<parameter>which</parameter>. </para> <para> -To change the state of one or more controls, first modify the <emphasis> -ctrls</emphasis> - structure in a local copy of the keyboard description and then use <emphasis> -XkbSetControls</emphasis> - to copy those changes to the X server. +<function>XkbGetControls</function> +returns +<symbol>Success</symbol> +if successful; otherwise, it returns +<errorname>BadAlloc</errorname> +if it cannot obtain sufficient storage, +<errorname>BadMatch</errorname> +if +<parameter>xkb</parameter> +is +<symbol>NULL</symbol> +or +<parameter>which</parameter> +is empty, or +<errorname>BadImplementation</errorname>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetControls</emphasis> -(<emphasis> -display, which, xkb)</emphasis> - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned long <emphasis> - which </emphasis> -; /* mask of controls to change */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* <emphasis> -ctrls</emphasis> - field contains new values to be set */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> <para> -For each bit that is set in the <emphasis> -which</emphasis> - parameter, <emphasis> -XkbSetControls</emphasis> - sends the corresponding values from the <emphasis> -xkb</emphasis> --><emphasis> -ctrls</emphasis> - field to the server. Valid values for <emphasis> -which</emphasis> - are any combination of the masks listed in Table 10.7 that have "ok" in the -<emphasis> -which</emphasis> - column. +To free the +<structfield>ctrls</structfield> +member of a keyboard description, use +<function>XkbFreeControls</function> +(see <link linkend="Allocating_and_Freeing_an_XkbControlsRec">section 10.12</link>) </para> <para> -If <emphasis> -xkb</emphasis> --><emphasis> -ctrls</emphasis> - is <emphasis> -NULL</emphasis> -, the server does not support a compatible version of Xkb, or the Xkb extension -has not been properly initialized, <emphasis> -XkbSetControls</emphasis> - returns <emphasis> -False</emphasis> -. Otherwise, it sends the request to the X server and returns <emphasis> -True</emphasis> -. +The +<structfield>num_groups</structfield> +field in the +<structfield>ctrls</structfield> +structure is always filled in by +<function>XkbGetControls</function>, +regardless of which bits are selected by +<parameter>which</parameter>. </para> +</sect1> +<sect1 id='Changing_Controls'> +<title>Changing Controls</title> + <para> -Note that changes to attributes of controls in the <emphasis> -XkbControlsRec</emphasis> - structure are apparent only when the associated control is enabled, although +There are two ways to make changes to controls: either change a local copy +keyboard description and call +<function>XkbSetControls</function>, +or, to reduce network traffic, use an +<structname>XkbControlsChangesRec</structname> +structure and call +<function>XkbChangeControls</function>. +</para> + + +<para> +To change the state of one or more controls, first modify the +<structfield>ctrls</structfield> +structure in a local copy of the keyboard description and then use +<function>XkbSetControls</function> +to copy those changes to the X server. +</para> + +<indexterm significance="preferred" zone="XkbSetControls"><primary><function>XkbSetControls</function></primary></indexterm> +<funcsynopsis id="XkbSetControls"> + <funcprototype> + <funcdef>Bool <function>XkbSetControls</function></funcdef> +<!-- ( +<parameter>display, which, xkb)</parameter> --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned long <parameter>which</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of controls to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + <structfield>ctrls</structfield> field contains new values to be set + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +For each bit that is set in the +<parameter>which</parameter> +parameter, +<function>XkbSetControls</function> +sends the corresponding values from the +<parameter>xkb</parameter>-><structfield>ctrls</structfield> +field to the server. Valid values for +<parameter>which</parameter> +are any combination of the masks listed in +<link linkend="table10.7">Table 10.7</link> that have <quote>ok</quote> in the +<parameter>which</parameter> +column. +</para> + + +<para> +If +<parameter>xkb</parameter>-><structfield>ctrls</structfield> +is +<symbol>NULL</symbol>, +the server does not support a compatible version of Xkb, or the Xkb extension +has not been properly initialized, +<function>XkbSetControls</function> +returns +<symbol>False</symbol>. +Otherwise, it sends the request to the X server and returns +<symbol>True</symbol>. +</para> + + +<para> +Note that changes to attributes of controls in the +<structname>XkbControlsRec</structname> +structure are apparent only when the associated control is enabled, although the corresponding values are still updated in the X server. For example, the -<emphasis> -repeat_delay</emphasis> - and <emphasis> -repeat_interval</emphasis> - fields are ignored unless the <emphasis> -RepeatKeys</emphasis> - control is enabled (that is, the X server’s equivalent of <emphasis> -xkb->ctrls</emphasis> - has <emphasis> -XkbRepeatKeyMask</emphasis> - set in <emphasis> -enabled_ctrls</emphasis> -). It is permissible to modify the attributes of a control in one call to -XkbSetControls and enable the control in a subsequent call. See section 10.1.1 <!-- xref --> +<structfield>repeat_delay</structfield> +and +<structfield>repeat_interval</structfield> +fields are ignored unless the +<emphasis>RepeatKeys</emphasis> +control is enabled (that is, the X server’s equivalent of +<structfield>xkb->ctrls</structfield> +has +<symbol>XkbRepeatKeysMask</symbol> +set in +<structfield>enabled_ctrls</structfield>). +It is permissible to modify the attributes of a control in one call to +XkbSetControls and enable the control in a subsequent call. See <link linkend="The_EnabledControls_Control">section 10.1.1</link> for more information on enabling and disabling controls. </para> <para> -Note that the <emphasis> -enabled_ctrls</emphasis> - field is itself a control — the <emphasis> -EnabledControls</emphasis> - control. As such, to set a specific configuration of enabled and disabled -boolean controls, you must set <emphasis> -enabled_ctrls</emphasis> - to the appropriate bits to enable only the controls you want and disable all -others, then specify the <emphasis> -XkbControlsEnabledMask</emphasis> - in a call to <emphasis> -XkbSetControls</emphasis> -. Because this is somewhat awkward if all you want to do is enable and disable +Note that the +<structfield>enabled_ctrls</structfield> +field is itself a control — the +<emphasis>EnabledControls</emphasis> +control. As such, to set a specific configuration of enabled and disabled +boolean controls, you must set +<structfield>enabled_ctrls</structfield> +to the appropriate bits to enable only the controls you want and disable all +others, then specify the +<symbol>XkbControlsEnabledMask</symbol> +in a call to +<function>XkbSetControls</function>. +Because this is somewhat awkward if all you want to do is enable and disable controls, and not modify any of their attributes, a convenience function is -also provided for this purpose (<emphasis> -XkbChangeEnabledControls</emphasis> -, section 10.1.1). <!-- xref --> +also provided for this purpose +(<function>XkbChangeEnabledControls</function>, +<link linkend="The_EnabledControls_Control">section 10.1.1</link>). </para> <sect2 id='The_XkbControlsChangesRec_Structure'> <title>The XkbControlsChangesRec Structure</title> +<indexterm significance="preferred" zone="The_XkbControlsChangesRec_Structure"> +<primary><structname>XkbControlsChangesRec</structname></primary></indexterm> + <para> -The <emphasis> -XkbControlsChangesRec</emphasis> - structure allows applications to track modifications to an <emphasis> -XkbControlsRec</emphasis> - structure and thereby reduce the amount of traffic sent to the server. The -same <emphasis> -XkbControlsChangesRec</emphasis> - structure may be used in several successive modifications to the same -<emphasis> -XkbControlsRec</emphasis> - structure, then subsequently used to cause all of the changes, and only the -changes, to be propagated to the server. The <emphasis> -XkbControlsChangesRec</emphasis> - structure is defined as follows: -</para> +The +<structname>XkbControlsChangesRec</structname> +structure allows applications to track modifications to an +<structname>XkbControlsRec</structname> +structure and thereby reduce the amount of traffic sent to the server. The +same +<structname>XkbControlsChangesRec</structname> +structure may be used in several successive modifications to the same +<structname>XkbControlsRec</structname> +structure, then subsequently used to cause all of the changes, and only the +changes, to be propagated to the server. The +<structname>XkbControlsChangesRec</structname> +structure is defined as follows: -<para><programlisting> +<programlisting> typedef struct _XkbControlsChanges { - unsigned int changed_ctrls; /* bits indicating changed control data */ - unsigned int enabled_ctrls_changes; /* bits indicating enabled/disabled controls */ - Bool num_groups_changed; /* <emphasis> True</emphasis> if - number of keyboard groups changed */ -} <emphasis>XkbControlsChangesRec</emphasis>,*XkbControlsChangesPtr; + unsigned int changed_ctrls; /* bits indicating changed + control data */ + unsigned int enabled_ctrls_changes; /* bits indicating + enabled/disabled controls */ + Bool num_groups_changed; /* <symbol>True</symbol> if number of keyboard + groups changed */ +} <structname>XkbControlsChangesRec</structname>, *XkbControlsChangesPtr; </programlisting></para> <para> -The <emphasis> -changed_ctrls</emphasis> - field is a mask specifying which logical sets of data in the controls -structure have been modified. In this context, modified means <emphasis> -set</emphasis> -, that is, if a value is set to the same value it previously contained, it has -still been modified, and is noted as changed. Valid values for <emphasis> -changed_ctrls</emphasis> - are any combination of the masks listed in Table 10.7 that have "ok" in the -<emphasis> -changed_ctrls</emphasis> - column. Setting a bit implies the corresponding data fields from the "Relevant -XkbControlsRec Data Fields" column in Table 10.6 have been modified. The -<emphasis> -enabled_ctrls_changes</emphasis> - field specifies which bits in the <emphasis> -enabled_ctrls</emphasis> - field have changed. If the number of keyboard groups has changed, the -<emphasis>num_groups_changed</emphasis> - field is set to <emphasis>True</emphasis>. +The +<structfield>changed_ctrls</structfield> +field is a mask specifying which logical sets of data in the controls +structure have been modified. In this context, modified means +<emphasis>set</emphasis>, +that is, if a value is set to the same value it previously contained, it has +still been modified, and is noted as changed. Valid values for +<structfield>changed_ctrls</structfield> +are any combination of the masks listed in +<link linkend="table10.7">Table 10.7</link> that have <quote>ok</quote> in the +<structfield>changed_ctrls</structfield> +column. Setting a bit implies the corresponding data fields from the +<quote>Relevant XkbControlsRec Data Fields</quote> column in +<link linkend="table10.6">Table 10.6</link> have been modified. The +<structfield>enabled_ctrls_changes</structfield> +field specifies which bits in the +<structfield>enabled_ctrls</structfield> +field have changed. If the number of keyboard groups has changed, the +<structfield>num_groups_changed</structfield> +field is set to <symbol>True</symbol>. </para> <para> If you have an Xkb description with controls that have been modified and an -<emphasis> -XkbControlsChangesRec</emphasis> - that describes the changes that have been made, the <emphasis> -XkbChangeControls</emphasis> - function provides a flexible method for updating the controls in a server to +<structname>XkbControlsChangesRec</structname> +that describes the changes that have been made, the +<function>XkbChangeControls</function> +function provides a flexible method for updating the controls in a server to match those in the changed keyboard description. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbChangeControls</emphasis> -(<emphasis> -dpy, xkb, changes</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description with changed <emphasis> -xkb->ctrls</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbControlsChangesPtr <emphasis> -changes</emphasis> -; /* which parts of <emphasis> -xkb->ctrls</emphasis> - have changed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbChangeControls</emphasis> - copies any controls fields specified by <emphasis> -changes</emphasis> - from the keyboard description controls structure, <emphasis> -xkb</emphasis> --><emphasis> -ctrls</emphasis> -, to the server specified by <emphasis> -dpy</emphasis> -. +<indexterm significance="preferred" zone="XkbChangeControls"><primary><function>XkbChangeControls</function></primary></indexterm> +<funcsynopsis id="XkbChangeControls"> + <funcprototype> + <funcdef>Bool <function>XkbChangeControls</function></funcdef> +<!-- ( +<parameter>dpy, xkb, changes</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>XkbControlsChangesPtr <parameter>changes</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description with changed <structfield>xkb->ctrls</structfield> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + which parts of <structfield>xkb->ctrls</structfield> have changed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbChangeControls</function> +copies any controls fields specified by +<parameter>changes</parameter> +from the keyboard description controls structure, +<parameter>xkb</parameter>-><structfield>ctrls</structfield>, +to the server specified by +<parameter>dpy</parameter>. </para> @@ -4743,313 +4732,313 @@ dpy</emphasis> <sect1 id='Tracking_Changes_to_Keyboard_Controls'> <title>Tracking Changes to Keyboard Controls</title> +<indexterm significance="preferred" zone="Tracking_Changes_to_Keyboard_Controls"> +<primary>events</primary><secondary><symbol>XkbControlsNotify</symbol></secondary></indexterm> +<indexterm significance="preferred" zone="Tracking_Changes_to_Keyboard_Controls"> +<primary><structname>XkbControlsNotifyEvent</structname></primary></indexterm> + <para> Whenever a field in the controls structure changes in the server’s keyboard -description, the server sends an <emphasis> -XkbControlsNotify</emphasis> - event to all interested clients.To receive <emphasis> -XkbControlsNotify</emphasis> - events under all possible conditions, use <emphasis> -XkbSelectEvents</emphasis> - (see section 4.3) and pass <emphasis> -XkbControlsNotifyMask</emphasis> - in both <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> -. +description, the server sends an +<symbol>XkbControlsNotify</symbol> +event to all interested clients.To receive +<symbol>XkbControlsNotify</symbol> +events under all possible conditions, use +<function>XkbSelectEvents</function> +(see <link linkend="Selecting_Xkb_Events">section 4.3</link>) and pass +<symbol>XkbControlsNotifyMask</symbol> +in both +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter>. </para> <para> -To receive <emphasis> -XkbControlsNotify</emphasis> - events only under certain conditions, use <emphasis> -XkbSelectEventDetails</emphasis> - using <emphasis> -XkbControlsNotify</emphasis> - as the <emphasis> -event_type</emphasis> - and specifying the desired state changes in <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> - using mask bits from Table 10.7. <!-- xref --> +To receive +<symbol>XkbControlsNotify</symbol> +events only under certain conditions, use +<function>XkbSelectEventDetails</function> +using +<symbol>XkbControlsNotify</symbol> +as the +<structfield>event_type</structfield> +and specifying the desired state changes in +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +using mask bits from <link linkend="table10.7">Table 10.7</link>. </para> <para> -The structure for the <emphasis> -XkbControlsNotify</emphasis> - event is defined as follows: -</para> +The structure for the +<symbol>XkbControlsNotify</symbol> +event is defined as follows: -<para><programlisting> +<programlisting> typedef struct { - int type; /* Xkb extension base event code */ - unsigned long serial; /* X server serial number for event */ - Bool send_event; /* <emphasis> True</emphasis> => synthetically generated */ - Display * display; /* server connection where event generated */ - Time time; /* server time when event generated */ - int xkb_type; /* <emphasis> XkbCompatMapNotify</emphasis> */ - int device; /* Xkb device ID, will not be <emphasis> XkbUseCoreKbd</emphasis> */ - unsigned int changed_ctrls; /* bits indicating which controls data have changed*/ - unsigned int enabled_ctrls; /* controls currently enabled in server */ - unsigned int enabled_ctrl_changes; /* bits indicating enabled/disabled controls */ - int num_groups; /* current number of keyboard groups */ - KeyCode keycode; /* != 0 => keycode of key causing change */ - char event_type; /* Type of event causing change */ - char req_major; /* major event code of event causing change */ - char req_minor; /* minor event code of event causing change */ -} <emphasis>XkbControlsNotifyEvent</emphasis>; + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* <symbol>True</symbol> ⇒ synthetically generated */ + Display * display; /* server connection where event generated */ + Time time; /* server time when event generated */ + int xkb_type; /* <symbol>XkbCompatMapNotify</symbol> */ + int device; /* Xkb device ID, + will not be <symbol>XkbUseCoreKbd</symbol> */ + unsigned int changed_ctrls; /* bits indicating which controls + data have changed */ + unsigned int enabled_ctrls; /* controls currently enabled in server */ + unsigned int enabled_ctrl_changes; /* bits indicating + enabled/disabled controls */ + int num_groups; /* current number of keyboard groups */ + KeyCode keycode; /* != 0 ⇒ keycode of key causing change */ + char event_type; /* Type of event causing change */ + char req_major; /* major event code of event causing change */ + char req_minor; /* minor event code of event causing change */ +} <structname>XkbControlsNotifyEvent</structname>; </programlisting></para> <para> -The <emphasis> -changed_ctrls</emphasis> - field specifies the controls components that have changed and consists of bits -taken from the masks defined in Table 10.7 with "ok" in the <emphasis> -changed_ctrls</emphasis> - column. +The +<structfield>changed_ctrls</structfield> +field specifies the controls components that have changed and consists of bits +taken from the masks defined in +<link linkend="table10.7">Table 10.7</link> with <quote>ok</quote> in the +<structfield>changed_ctrls</structfield> +column. </para> <para> -The controls currently enabled in the server are reported in the <emphasis> -enabled_ctrls</emphasis> - field. If any controls were just enabled or disabled (that is, the contents of -the <emphasis> -enabled_ctrls</emphasis> - field changed), they are flagged in the <emphasis> -enabled_ctrl_changes</emphasis> - field. The valid bits for these fields are the masks listed in Table 10.7 with -"ok" in the <emphasis> -enabled_ctrls</emphasis> - column. The <emphasis> -num_groups</emphasis> - field reports the number of groups bound to the key belonging to the most +The controls currently enabled in the server are reported in the +<structfield>enabled_ctrls</structfield> +field. If any controls were just enabled or disabled (that is, the contents of +the +<structfield>enabled_ctrls</structfield> +field changed), they are flagged in the +<structfield>enabled_ctrl_changes</structfield> +field. The valid bits for these fields are the masks listed in +<link linkend="table10.7">Table 10.7</link> with +<quote>ok</quote> in the +<structfield>enabled_ctrls</structfield> +column. The +<structfield>num_groups</structfield> +field reports the number of groups bound to the key belonging to the most number of groups and is automatically updated when the keyboard mapping changes. </para> <para> -If the change was caused by a request from a client, the <emphasis> -keycode</emphasis> - and <emphasis> -event_type</emphasis> - fields are set to <emphasis> -zero </emphasis> -and the <emphasis> -req_major</emphasis> - and <emphasis> -req_minor</emphasis> - fields identify the request. The <emphasis> -req_major</emphasis> - value is the same as the major extension opcode. Otherwise, <emphasis> -event_type</emphasis> - is set to the type of event that caused the change (one of <emphasis> -KeyPress</emphasis> -, <emphasis> -KeyRelease</emphasis> -, <emphasis> -DeviceKeyPress</emphasis> -, <emphasis> -DeviceKeyRelease</emphasis> -, <emphasis> -ButtonPress</emphasis> - or <emphasis> -ButtonRelease</emphasis> -), and <emphasis> -req_major</emphasis> - and <emphasis> -req_minor</emphasis> - are undefined. If <emphasis> -event_type</emphasis> - is <emphasis> -KeyPress</emphasis> -, <emphasis> -KeyRelease</emphasis> -, <emphasis> -DeviceKeyPress</emphasis> -, or <emphasis> -DeviceKeyRelease</emphasis> -, the <emphasis> -keycode</emphasis> - field is set to the key that caused the change. If <emphasis> -event_type</emphasis> - is <emphasis> -ButtonPress</emphasis> - or <emphasis> -ButtonRelease</emphasis> -, <emphasis> -keycode</emphasis> - contains the button number. -</para> - - -<para> -When a client receives an <emphasis> -XkbControlsNotify</emphasis> - event, it can note the changes in a changes structure using <emphasis> -XkbNoteControlsChanges</emphasis> -. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbNoteControlsChanges</emphasis> -(<emphasis> -changes</emphasis> -,<emphasis> - new</emphasis> -,<emphasis> - wanted</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbControlsChangesPtr <emphasis> - changes</emphasis> -; /* records changes indicated by new */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbControlsNotifyEvent * <emphasis> - new</emphasis> -; /* tells which things have changed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - wanted</emphasis> -; /* tells which parts of new to record in changes */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -The <emphasis> -wanted</emphasis> - parameter is a bitwise inclusive OR of bits taken from the set of masks -specified in Table 10.7 with "ok" in the <emphasis> -changed_ctrls</emphasis> - column. <emphasis> -XkbNoteControlsChanges</emphasis> - copies any changes reported in <emphasis> -new</emphasis> - and specified in <emphasis> -wanted</emphasis> - into the changes record specified by <emphasis> -old</emphasis> -. -</para> - - -<para> -Use <emphasis> -XkbGetControlsChanges</emphasis> - to update a local copy of a keyboard description with the changes previously -noted by one or more calls to <emphasis> -XkbNoteControlsChanges.</emphasis> -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetControlsChanges</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - xkb</emphasis> -,<emphasis> - changes</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* <emphasis> -xkb->ctrls</emphasis> - will be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbNameChangesPtr <emphasis> -changes</emphasis> -; /* indicates which parts of <emphasis> -xkb->ctrls</emphasis> - to update */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetControlsChanges</emphasis> - examines the <emphasis> -changes</emphasis> - parameter, queries the server for the necessary information, and copies the -results into the <emphasis> -xkb</emphasis> --><emphasis> -ctrls</emphasis> - keyboard description. If the <emphasis> -ctrls</emphasis> - field of <emphasis> -xkb</emphasis> - is <emphasis> -NULL</emphasis> -, <emphasis> -XkbGetControlsChanges</emphasis> - allocates and initializes it. To free the <emphasis> -ctrls</emphasis> - field, use <emphasis> -XkbFreeControls</emphasis> - (see section 10.12). <!-- xref --> -</para> - - -<para> -<emphasis> -XkbGetControlsChanges</emphasis> - returns <emphasis> -Success</emphasis> - if successful and can generate <emphasis> -BadAlloc</emphasis> -, <emphasis> -BadImplementation,</emphasis> - and <emphasis> -BadMatch</emphasis> - errors. +If the change was caused by a request from a client, the +<structfield>keycode</structfield> +and +<structfield>event_type</structfield> +fields are set to +<emphasis>zero</emphasis> +and the +<structfield>req_major</structfield> +and +<structfield>req_minor</structfield> +fields identify the request. The +<structfield>req_major</structfield> +value is the same as the major extension opcode. Otherwise, +<structfield>event_type</structfield> +is set to the type of event that caused the change (one of +<symbol>KeyPress</symbol>, +<symbol>KeyRelease</symbol>, +<symbol>DeviceKeyPress</symbol>, +<symbol>DeviceKeyRelease</symbol>, +<symbol>ButtonPress</symbol> +or +<symbol>ButtonRelease</symbol>), +and +<structfield>req_major</structfield> +and +<structfield>req_minor</structfield> +are undefined. If +<structfield>event_type</structfield> +is +<symbol>KeyPress</symbol>, +<symbol>KeyRelease</symbol>, +<symbol>DeviceKeyPress</symbol>, +or +<symbol>DeviceKeyRelease</symbol>, +the +<structfield>keycode</structfield> +field is set to the key that caused the change. If +<structfield>event_type</structfield> +is +<symbol>ButtonPress</symbol> +or +<symbol>ButtonRelease</symbol>, +<structfield>keycode</structfield> +contains the button number. +</para> + + +<para> +When a client receives an +<symbol>XkbControlsNotify</symbol> +event, it can note the changes in a changes structure using +<function>XkbNoteControlsChanges</function>. +</para> + +<indexterm significance="preferred" zone="XkbNoteControlsChanges"><primary><function>XkbNoteControlsChanges</function></primary></indexterm> +<funcsynopsis id="XkbNoteControlsChanges"> + <funcprototype> + <funcdef>void <function>XkbNoteControlsChanges</function></funcdef> +<!-- ( +<parameter>changes</parameter>, +<parameter>new</parameter>, +<parameter>wanted</parameter> +) --> + + <paramdef>XkbControlsChangesPtr <parameter>changes</parameter></paramdef> + <paramdef>XkbControlsNotifyEvent *<parameter>new</parameter></paramdef> + <paramdef>unsigned int <parameter>wanted</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + records changes indicated by new + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>new</parameter> + </term> + <listitem> + <para> + tells which things have changed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>wanted</parameter> + </term> + <listitem> + <para> + tells which parts of new to record in changes + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<parameter>wanted</parameter> +parameter is a bitwise inclusive OR of bits taken from the set of masks +specified in <link linkend="table10.7">Table 10.7</link> with <quote>ok</quote> +in the +<structfield>changed_ctrls</structfield> +column. +<function>XkbNoteControlsChanges</function> +copies any changes reported in +<parameter>new</parameter> +and specified in +<parameter>wanted</parameter> +into the changes record specified by +<parameter>changes</parameter>. +</para> + + +<para> +Use +<function>XkbGetControlsChanges</function> +to update a local copy of a keyboard description with the changes previously +noted by one or more calls to +<function>XkbNoteControlsChanges</function>. +</para> + + +<indexterm significance="preferred" zone="XkbGetControlsChanges"><primary><function>XkbGetControlsChanges</function></primary></indexterm> +<funcsynopsis id="XkbGetControlsChanges"> + <funcprototype> + <funcdef>Status <function>XkbGetControlsChanges</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>xkb</parameter>, +<parameter>changes</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>XkbNameChangesPtr <parameter>changes</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + <structfield>xkb->ctrls</structfield> will be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + indicates which parts of <structfield>xkb->ctrls</structfield> to update + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetControlsChanges</function> +examines the +<parameter>changes</parameter> +parameter, queries the server for the necessary information, and copies the +results into the +<parameter>xkb</parameter>-><structfield>ctrls</structfield> +keyboard description. If the +<structfield>ctrls</structfield> +field of +<parameter>xkb</parameter> +is +<symbol>NULL</symbol>, +<function>XkbGetControlsChanges</function> +allocates and initializes it. To free the +<structfield>ctrls</structfield> +field, use +<function>XkbFreeControls</function> +(see <link linkend="Allocating_and_Freeing_an_XkbControlsRec">section 10.12</link>). +</para> + + +<para> +<function>XkbGetControlsChanges</function> +returns +<symbol>Success</symbol> +if successful and can generate +<errorname>BadAlloc</errorname>, +<errorname>BadImplementation</errorname>, +and +<errorname>BadMatch</errorname> +errors. </para> @@ -5058,190 +5047,188 @@ BadMatch</emphasis> <title>Allocating and Freeing an XkbControlsRec</title> <para> -The need to allocate an <emphasis> -XkbControlsRec</emphasis> - structure seldom arises; Xkb creates one when an application calls <emphasis> -XkbGetControls</emphasis> - or a related function. For those situations where there is not an <emphasis> -XkbControlsRec</emphasis> - structure allocated in the <emphasis> -XkbDescRec</emphasis> -, allocate one by calling <emphasis> -XkbAllocControls</emphasis> -. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocControls</emphasis> -(<emphasis> -xkb, which</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* Xkb description in which to allocate ctrls rec */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask of components of <emphasis> -ctrls</emphasis> - to allocate */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocControls</emphasis> - allocates the <emphasis> -ctrls</emphasis> - field of the <emphasis> -xkb</emphasis> - parameter, initializes all fields to zero, and returns <emphasis> -Success</emphasis> -. If the <emphasis> -ctrls</emphasis> - field is not <emphasis> -NULL</emphasis> -, <emphasis> -XkbAllocControls</emphasis> - simply returns <emphasis> -Success</emphasis> -. If <emphasis> -xkb</emphasis> - is <emphasis> -NULL</emphasis> -, <emphasis> -XkbAllocControls</emphasis> - reports a <emphasis> -BadMatch</emphasis> - error. If the <emphasis> -ctrls</emphasis> - field could not be allocated, it reports a <emphasis> -BadAlloc</emphasis> - error. -</para> - - -<para> -The <emphasis> -which</emphasis> - mask specifies the individual fields of the <emphasis> -ctrls</emphasis> - structure to be allocated and can contain any of the valid masks defined in -Table 10.7. Because none of the currently existing controls have any structures +The need to allocate an +<structname>XkbControlsRec</structname> +structure seldom arises; Xkb creates one when an application calls +<function>XkbGetControls</function> +or a related function. For those situations where there is not an +<structname>XkbControlsRec</structname> +structure allocated in the +<structname>XkbDescRec</structname>, +allocate one by calling +<function>XkbAllocControls</function>. +</para> + +<indexterm significance="preferred" zone="XkbAllocControls"><primary><function>XkbAllocControls</function></primary></indexterm> +<funcsynopsis id="XkbAllocControls"> + <funcprototype> + <funcdef>Status <function>XkbAllocControls</function></funcdef> +<!-- ( +<parameter>xkb, which</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description in which to allocate ctrls rec + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of components of <structfield>ctrls</structfield> to allocate + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocControls</function> +allocates the +<structfield>ctrls</structfield> +field of the +<parameter>xkb</parameter> +parameter, initializes all fields to zero, and returns +<symbol>Success</symbol>. +If the +<structfield>ctrls</structfield> +field is not +<symbol>NULL</symbol>, +<function>XkbAllocControls</function> +simply returns +<symbol>Success</symbol>. +If +<parameter>xkb</parameter> +is +<symbol>NULL</symbol>, +<function>XkbAllocControls</function> +reports a +<errorname>BadMatch</errorname> +error. If the +<structfield>ctrls</structfield> +field could not be allocated, it reports a +<errorname>BadAlloc</errorname> +error. +</para> + + +<para> +The +<parameter>which</parameter> +mask specifies the individual fields of the +<structfield>ctrls</structfield> +structure to be allocated and can contain any of the valid masks defined in +<link linkend="table10.7">Table 10.7</link>. +Because none of the currently existing controls have any structures associated with them, which is currently of little practical value in this call. </para> <para> -To free memory used by the <emphasis> -ctrls</emphasis> - member of an <emphasis> -XkbDescRec </emphasis> -structure, use <emphasis> -XkbFreeControls:</emphasis> -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeControls</emphasis> -(<emphasis> -xkb, which, free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr<emphasis> - xkb</emphasis> -; /* Xkb description in which to free controls components */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -which</emphasis> -; /* mask of components of <emphasis> -ctrls</emphasis> - to free */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> -free_all</emphasis> -; /* <emphasis> -True</emphasis> - => free everything + ctrls itself */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbFreeControls</emphasis> - frees the specified components of the <emphasis> -ctrls</emphasis> - field in the <emphasis> -xkb</emphasis> - keyboard description and sets the corresponding structure component values to -<emphasis> -NULL</emphasis> - or <emphasis> -zero</emphasis> -. The <emphasis> -which</emphasis> - mask specifies the fields of <emphasis> -ctrls</emphasis> - to be freed and can contain any of the controls components specified in Table -10.7. -</para> - - -<para> -If <emphasis> -free_all</emphasis> - is <emphasis> -True</emphasis> -, <emphasis> -XkbFreeControls</emphasis> - frees every non-<emphasis> -NULL</emphasis> - structure component in the controls, frees the <emphasis> -XkbControlsRec</emphasis> - structure referenced by the <emphasis> -ctrls</emphasis> - member of <emphasis> -xkb</emphasis> -, and sets <emphasis> -ctrls</emphasis> - to <emphasis> -NULL.</emphasis> +To free memory used by the +<structfield>ctrls</structfield> +member of an +<structname>XkbDescRec</structname> +structure, use +<function>XkbFreeControls</function>: +</para> + + +<indexterm significance="preferred" zone="XkbFreeControls"><primary><function>XkbFreeControls</function></primary></indexterm> +<funcsynopsis id="XkbFreeControls"> + <funcprototype> + <funcdef>void <function>XkbFreeControls</function></funcdef> +<!-- ( +<parameter>xkb, which, free_all</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description in which to free controls components + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of components of <structfield>ctrls</structfield> to free + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ free everything + ctrls itself + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbFreeControls</function> +frees the specified components of the +<structfield>ctrls</structfield> +field in the +<parameter>xkb</parameter> +keyboard description and sets the corresponding structure component values to +<symbol>NULL</symbol> +or +<emphasis>zero</emphasis>. +The +<parameter>which</parameter> +mask specifies the fields of +<structfield>ctrls</structfield> +to be freed and can contain any of the controls components specified in +<link linkend="table10.7">Table 10.7</link>. +</para> + + +<para> +If +<parameter>free_all</parameter> +is +<symbol>True</symbol>, +<function>XkbFreeControls</function> +frees every non- +<symbol>NULL</symbol> +structure component in the controls, frees the +<structname>XkbControlsRec</structname> +structure referenced by the +<structfield>ctrls</structfield> +member of +<parameter>xkb</parameter>, +and sets +<structfield>ctrls</structfield> +to +<symbol>NULL</symbol>. </para> </sect1> @@ -5250,136 +5237,146 @@ NULL.</emphasis> <para> You can configure the boolean per-client controls which affect the state -reported in button and key events. See section 12.1.1, 12.3, 12.5, and 16.3.11 <!-- xref --> -of the XKB Protocol specification for more details. -</para> - - -<para> -To get the current values of the <emphasis> -per-client</emphasis> - controls, use <emphasis> -XkbGetPerClientControls</emphasis> -. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbGetPerClientControls</emphasis> -(<emphasis> -dpy</emphasis> -, <emphasis> -ctrls</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -ctrls</emphasis> -; /* 1 bit => corresponding control is on */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetPerClientControls</emphasis> - backfills <emphasis> -ctrls</emphasis> - with the <emphasis> -per-client </emphasis> -control attributes for this particular client. It returns <emphasis> -True</emphasis> - if successful, and <emphasis> -False</emphasis> - otherwise. -</para> - - -<para> -To change the current values of the <emphasis> -per-client</emphasis> - control attributes, use <emphasis> -XkbSetPerClientControls.</emphasis> -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetPerClientControls</emphasis> -(<emphasis> -dpy</emphasis> -, <emphasis> -ctrls</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -change</emphasis> -; /* 1 bit => change control */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -value</emphasis> -; /* 1 bit => control on */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetPerClientControls changes the per-client values for the controls selected -by </emphasis> -<emphasis> -change to the corresponding value in value. Legal values for change and value +reported in button and key events. See +<olink targetdoc='xkbproto' targetptr='Setting_a_Passive_Grab_for_an_XKB_State'>section 12.1.1</olink>, +<olink targetdoc='xkbproto' targetptr='Effects_of_XKB_on_Core_Protocol_Events'>12.3</olink>, +<olink targetdoc='xkbproto' targetptr='Sending_Events_to_Clients'>12.5</olink>, +and +<olink targetdoc='xkbproto' targetptr='Querying_and_Changing_Per_Client_Flags'>16.3.11</olink> +of the +<olink targetdoc='xkbproto' targetptr='xkbproto'><citetitle>XKB Protocol specification</citetitle></olink> +for more details. +</para> + + +<para> +To get the current values of the +<emphasis>per-client</emphasis> +controls, use +<function>XkbGetPerClientControls</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetPerClientControls"><primary><function>XkbGetPerClientControls</function></primary></indexterm> +<funcsynopsis id="XkbGetPerClientControls"> + <funcprototype> + <funcdef>Bool <function>XkbGetPerClientControls</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>ctrls</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int *<parameter>ctrls</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ctrls</parameter> + </term> + <listitem> + <para> + 1 bit ⇒ corresponding control is on + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetPerClientControls</function> +backfills +<parameter>ctrls</parameter> +with the +<emphasis>per-client</emphasis> +control attributes for this particular client. It returns +<symbol>True</symbol> +if successful, and +<symbol>False</symbol> +otherwise. +</para> + + +<para> +To change the current values of the +<emphasis>per-client</emphasis> +control attributes, use +<function>XkbSetPerClientControls</function>. +</para> + + +<indexterm significance="preferred" zone="XkbSetPerClientControls"><primary><function>XkbSetPerClientControls</function></primary></indexterm> +<funcsynopsis id="XkbSetPerClientControls"> + <funcprototype> + <funcdef>Bool <function>XkbSetPerClientControls</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>ctrls</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>change</parameter></paramdef> + <paramdef>unsigned int *<parameter>value</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>change</parameter> + </term> + <listitem> + <para> + 1 bit ⇒ change control + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>value</parameter> + </term> + <listitem> + <para> + 1 bit ⇒ control on + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetPerClientControls</function> +changes the per-client values for the controls selected by +<parameter>change</parameter> to the corresponding value in +<parameter>value</parameter>. Legal values for +<parameter>change</parameter> and <parameter>value</parameter> are: XkbPCF_GrabsUseXKBStateMask, XkbPCF_LookupStateWhenGrabbed, and XkbPCF_SendEventUsesXKBState. More than one control may be changed at one time by OR-ing the values together. XkbSetPerClientControls backfills value with the -</emphasis> -<emphasis> -per-client </emphasis> -<emphasis> -control attributes for this particular client. </emphasis> -It returns <emphasis> -True</emphasis> - if successful, and <emphasis> -False</emphasis> - otherwise. +<emphasis>per-client</emphasis> +control attributes for this particular client. +It returns +<symbol>True</symbol> +if successful, and +<symbol>False</symbol> +otherwise. </para> </sect1> diff --git a/libX11/specs/XKB/ch11.xml b/libX11/specs/XKB/ch11.xml index 52f089775..6463878b6 100644 --- a/libX11/specs/XKB/ch11.xml +++ b/libX11/specs/XKB/ch11.xml @@ -1,13 +1,20 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='X_Library_Controls'> <title>X Library Controls</title> <para> The Xkb extension is composed of two parts: a server extension, and a -client-side X library extension. Chapter 10 discusses functions used to modify +client-side X library extension. <xref linkend="Keyboard_Controls" /> discusses functions used to modify controls affecting the behavior of the server portion of the Xkb extension. This chapter discusses functions used to modify controls that affect only the behavior of the client portion of the extension; these controls are known as -Library Controls. +<firstterm>Library Controls</firstterm>. +<indexterm significance="preferred" zone="X_Library_Controls"> +<primary>library controls</primary></indexterm> +<indexterm significance="preferred" zone="X_Library_Controls"> +<primary>controls</primary><secondary>library</secondary></indexterm> </para> @@ -35,9 +42,11 @@ Controls affecting event delivery </itemizedlist> <para> -There are two types of string lookups performed by <emphasis> -XLookupString</emphasis> -. The first type involves translating a single keycode into a string; the +There are two types of string lookups performed by +<function>XLookupString</function>. +<indexterm significance="preferred" zone="X_Library_Controls"> +<primary><function>XLookupString</function></primary></indexterm> +The first type involves translating a single keycode into a string; the controls in the first category affect this type of lookup. The second type involves translating a series of keysyms into a string; the controls in the second category affect this type of lookup. @@ -57,33 +66,33 @@ enabled may be missing. <title>Controls Affecting Keycode-to-String Translation</title> <para> -The first type of string lookups, which are here called <emphasis> -simple string lookups</emphasis> -, involves translating a single keycode into a string. Because these simple +The first type of string lookups, which are here called +<firstterm>simple string lookups</firstterm>, +involves translating a single keycode into a string. Because these simple lookups involve only a single keycode, all of the information needed to do the translation is contained in the keyboard state in a single event. The controls affecting simple string lookups are: -</para> -<para><programlisting> - <emphasis>ForceLatin1Lookup</emphasis> - <emphasis>ConsumeLookupMods</emphasis> - <emphasis>LevelOneUsesShiftAndLock</emphasis> -</programlisting></para> + <simplelist type='vert' columns='1'> + <member><emphasis>ForceLatin1Lookup</emphasis></member> + <member><emphasis>ConsumeLookupMods</emphasis></member> + <member><emphasis>LevelOneUsesShiftAndLock</emphasis></member> + </simplelist> +</para> <sect2 id='ForceLatin1Lookup'> <title>ForceLatin1Lookup</title> <para> -If the <emphasis> -ForceLatin1Lookup</emphasis> - control is enabled, <emphasis> -XLookupString</emphasis> - only returns strings using the Latin1 character set. If <emphasis> -ForceLatin1Lookup</emphasis> - is not enabled, <emphasis> -XLookupString</emphasis> - can return characters that are not in the Latin1 set. By default, this control +If the +<emphasis>ForceLatin1Lookup</emphasis> +control is enabled, +<function>XLookupString</function> +only returns strings using the Latin1 character set. If +<emphasis>ForceLatin1Lookup</emphasis> +is not enabled, +<function>XLookupString</function> +can return characters that are not in the Latin1 set. By default, this control is disabled, allowing characters outside of the Latin1 set to be returned. </para> @@ -93,9 +102,9 @@ is disabled, allowing characters outside of the Latin1 set to be returned. <title>ConsumeLookupMods</title> <para> -Simple string lookups in <emphasis> -XLookupString</emphasis> - involve two different translation phases. The first phase translates raw +Simple string lookups in +<function>XLookupString</function> +involve two different translation phases. The first phase translates raw device keycodes to individual keysyms. The second phase attempts to map the resulting keysym into a string of one or more characters. In the first phase, some of the modifiers are normally used to determine the appropriate shift @@ -104,64 +113,62 @@ level for a key. <para> -The <emphasis> -ConsumeLookupMods</emphasis> - control determines whether or not <emphasis> -XLookupString</emphasis> - <emphasis> -consumes</emphasis> - the modifiers it uses during the first phase of processing (mapping a keycode +The +<emphasis>ConsumeLookupMods</emphasis> +control determines whether or not +<function>XLookupString</function> +<emphasis>consumes</emphasis> +the modifiers it uses during the first phase of processing (mapping a keycode to a keysym). When a modifier is consumed, it is effectively removed from the -working copy of the keyboard state information <emphasis> -XLookupString</emphasis> - is using and appears to be unset for the remainder of the processing. +working copy of the keyboard state information +<function>XLookupString</function> +is using and appears to be unset for the remainder of the processing. </para> <para> -If the <emphasis> -ConsumeLookupMods</emphasis> - control is enabled, <emphasis> -XLookupString</emphasis> - does not use the modifiers used to translate the keycode of the event to a +If the +<emphasis>ConsumeLookupMods</emphasis> +control is enabled, +<function>XLookupString</function> +does not use the modifiers used to translate the keycode of the event to a keysym when it is determining the string associated with a keysym. For example, assume the keymap for the ‘A’ key only contains the shift modifier and the -<emphasis> -ConsumeLookupMods</emphasis> - control is enabled. If a user presses the <emphasis> -Shift</emphasis> - key and the <emphasis> -A</emphasis> - key while the <emphasis> -Num_Lock</emphasis> - key is locked, <emphasis> -XLookupString</emphasis> - uses the <emphasis> -Shift</emphasis> - modifier when mapping the keycode for the ‘a’ key to the keysym for -‘A’; subsequently, it only uses the <emphasis> -NumLock</emphasis> - modifier when determining the string associated with the keysym ‘A’. +<emphasis>ConsumeLookupMods</emphasis> +control is enabled. If a user presses the +<keycap>Shift</keycap> +key and the +<keycap>A</keycap> +key while the +<keycap>Num_Lock</keycap> +key is locked, +<function>XLookupString</function> +uses the +<symbol>Shift</symbol> +modifier when mapping the keycode for the ‘a’ key to the keysym for +‘A’; subsequently, it only uses the +<emphasis>NumLock</emphasis> +modifier when determining the string associated with the keysym ‘A’. </para> <para> -If the <emphasis> -ConsumeLookupMods</emphasis> - control is not enabled, <emphasis> -XLookupString</emphasis> - uses all of the event modifiers to determine the string associated with a -keysym. This behavior mirrors the behavior of <emphasis> -XLookupString</emphasis> - in the core implementation. +If the +<emphasis>ConsumeLookupMods</emphasis> +control is not enabled, +<function>XLookupString</function> +uses all of the event modifiers to determine the string associated with a +keysym. This behavior mirrors the behavior of +<function>XLookupString</function> +in the core implementation. </para> <para> -The <emphasis> -ConsumeLookupMods</emphasis> - control is unset by default. For more information on modifier consumption, -refer to Chapter 12. +The +<emphasis>ConsumeLookupMods</emphasis> +control is unset by default. For more information on modifier consumption, +refer to <xref linkend="Interpreting_Key_Events" />. </para> @@ -170,18 +177,18 @@ refer to Chapter 12. <title>AlwaysConsumeShiftAndLock</title> <para> -The <emphasis> -AlwaysConsumeShiftAndLock</emphasis> - control, if enabled, forces <emphasis> -XLookupString</emphasis> - to consume the <emphasis> -Shift</emphasis> - and <emphasis> -Lock</emphasis> - modifiers when processing all keys, even if the definition for the key type -does not specify these modifiers. The <emphasis> -AlwaysConsumeShiftAndLock</emphasis> - control is unset by default. See section 15.2 for a discussion of key types. +The +<emphasis>AlwaysConsumeShiftAndLock</emphasis> +control, if enabled, forces +<function>XLookupString</function> +to consume the +<symbol>Shift</symbol> +and +<symbol>Lock</symbol> +modifiers when processing all keys, even if the definition for the key type +does not specify these modifiers. The +<emphasis>AlwaysConsumeShiftAndLock</emphasis> +control is unset by default. See <link linkend="Key_Types">section 15.2</link> for a discussion of key types. </para> @@ -191,23 +198,25 @@ AlwaysConsumeShiftAndLock</emphasis> <title>Controls Affecting Compose Processing</title> <para> -The second type of string lookup performed by <emphasis> -XLookupString</emphasis> - involves translating a series of keysyms into a string. Because these lookups -can involve more than one key event, they require <emphasis> -XLookupString</emphasis> - to retain some state information between successive calls. The process of -mapping a series of keysyms to a string is known as <emphasis> -compose processing</emphasis> -. The controls affecting compose processing are: +The second type of string lookup performed by +<function>XLookupString</function> +involves translating a series of keysyms into a string. Because these lookups +can involve more than one key event, they require +<function>XLookupString</function> +to retain some state information between successive calls. The process of +mapping a series of keysyms to a string is known as +<firstterm>compose processing</firstterm>. +<indexterm significance="preferred" zone="Controls_Affecting_Compose_Processing"> +<primary>compose processing</primary></indexterm> +The controls affecting compose processing are: + + <simplelist type='vert' columns='1'> + <member><emphasis>ConsumeKeysOnComposeFail</emphasis></member> + <member><emphasis>ComposeLED</emphasis></member> + <member><emphasis>BeepOnComposeFail</emphasis></member> + </simplelist> </para> -<para><programlisting> -<emphasis>ConsumeKeysOnComposeFail</emphasis> -<emphasis>ComposeLED</emphasis> -<emphasis>BeepOnComposeFail</emphasis> -</programlisting></para> - <para> Because different vendors have historically used different algorithms to implement compose processing, and these algorithms may be incompatible with the @@ -221,36 +230,36 @@ the compose processing controls is optional in an Xkb implementation. <para> Some compose processing algorithms signal the start of a compose sequence by a -key event meaning "start compose". +key event meaning <quote>start compose</quote>. <footnote><para> Another possibility is to have the compose processing simply be the result of a finite state acceptor; a compose sequence would never fail for a properly written finite state acceptor. </para></footnote> The subsequent key events should normally result in a valid composition yielding a valid translation to a string. If the subsequent key events do not have a valid translation, some decision must be made about what to do with the key events -that were processed while attempting the compose. The <emphasis> -ConsumeKeysOnComposeFail</emphasis> - control allows a client to specify what happens with the key events <emphasis> -XLookupString</emphasis> - has been considering when it reaches a dead end in a compose sequence. +that were processed while attempting the compose. The +<emphasis>ConsumeKeysOnComposeFail</emphasis> +control allows a client to specify what happens with the key events +<function>XLookupString</function> +has been considering when it reaches a dead end in a compose sequence. </para> <para> -If the <emphasis> -ConsumeKeysOnComposeFail</emphasis> - control is set, all keys associated with a failed compose sequence should be -consumed (discarded). If the <emphasis> -ConsumeKeysOnComposeFail</emphasis> - control is not set, the key events associated with a failed compose sequence +If the +<emphasis>ConsumeKeysOnComposeFail</emphasis> +control is set, all keys associated with a failed compose sequence should be +consumed (discarded). If the +<emphasis>ConsumeKeysOnComposeFail</emphasis> +control is not set, the key events associated with a failed compose sequence should be processed as a normal sequence of key events. </para> <para> -The <emphasis> -ConsumeKeysOnComposeFail</emphasis> - control is disabled by default. +The +<emphasis>ConsumeKeysOnComposeFail</emphasis> +control is disabled by default. </para> @@ -259,30 +268,28 @@ ConsumeKeysOnComposeFail</emphasis> <title>ComposeLED</title> <para> -The <emphasis> -ComposeLED</emphasis> - control allows a client to specify whether or not an indicator should be set +The +<emphasis>ComposeLED</emphasis> +control allows a client to specify whether or not an indicator should be set and cleared to provide feedback when compose processing is in progress. The control does not specify which indicator should be used; the mapping for this -is up to the individual implementation. If the <emphasis> -ComposeLED</emphasis> - control is enabled, it specifies that an indicator should be set when a +is up to the individual implementation. If the +<emphasis>ComposeLED</emphasis> +control is enabled, it specifies that an indicator should be set when a compose sequence is in progress and cleared when one is not in progress. The -<emphasis> -ComposeLED</emphasis> - control is disabled by default. +<emphasis>ComposeLED</emphasis> +control is disabled by default. </para> <para> While the Xkb extension does not specify the type of type of indicator to be -used when the <emphasis> -ComposeLED</emphasis> - control is implemented, a consistent convention between implementations is to +used when the +<emphasis>ComposeLED</emphasis> +control is implemented, a consistent convention between implementations is to everyone’s benefit. If a named indicator is used for this purpose, the -recommended name is "<emphasis> -Compose</emphasis> -". Note that some implementations may use an unnamed, custom hardware LED for +recommended name is “<literal>Compose</literal>”. +Note that some implementations may use an unnamed, custom hardware LED for this purpose. </para> @@ -292,34 +299,30 @@ this purpose. <title>BeepOnComposeFail</title> <para> -The <emphasis> -BeepOnComposeFail</emphasis> - control allows a client to specify whether or not a bell should be activated +The +<emphasis>BeepOnComposeFail</emphasis> +control allows a client to specify whether or not a bell should be activated to provide feedback when a compose sequence fails. The control does not specify the type of bell that should be used; the mapping for this is up to the -individual implementation. If the <emphasis> -BeepOnComposeFail</emphasis> - control is enabled, it specifies that a bell should be activated when a -compose sequence fails. The <emphasis> -BeepOnComposeFail</emphasis> - control is disabled by default. If implemented, the bell should be activated -using <emphasis> -XkbBell</emphasis> - or <emphasis> -XkbDeviceBell</emphasis> -. +individual implementation. If the +<emphasis>BeepOnComposeFail</emphasis> +control is enabled, it specifies that a bell should be activated when a +compose sequence fails. The +<emphasis>BeepOnComposeFail</emphasis> +control is disabled by default. If implemented, the bell should be activated +using +<function>XkbBell</function> +or +<function>XkbDeviceBell</function>. </para> <para> While the Xkb extension does not specify the type of bell to be used when the -<emphasis> -BeepOnComposeFail</emphasis> - control is implemented, a consistent convention between implementations is to +<emphasis>BeepOnComposeFail</emphasis> +control is implemented, a consistent convention between implementations is to everyone’s benefit. If a named bell is used for this purpose, the recommended -name is "<emphasis> -ComposeFail</emphasis> -". +name is “<literal>ComposeFail</literal>”. </para> @@ -331,31 +334,36 @@ ComposeFail</emphasis> <sect2 id='IgnoreNewKeyboards'> <title>IgnoreNewKeyboards</title> +<indexterm zone="IgnoreNewKeyboards"> +<primary>events</primary><secondary><symbol>NewKeyboardNotify</symbol></secondary></indexterm> +<indexterm zone="IgnoreNewKeyboards"> +<primary>events</primary><secondary><symbol>MappingNotify</symbol></secondary></indexterm> + <para> -When Xkb is initialized, it implicitly forces requests for <emphasis> -NewKeyboardNotify</emphasis> - events. These events may be used by the Xkb library extension internally; they -are normally translated into core protocol <emphasis> -MappingNotify</emphasis> - events before being passed to the client. While delivering the event to the +When Xkb is initialized, it implicitly forces requests for +<symbol>NewKeyboardNotify</symbol> +events. These events may be used by the Xkb library extension internally; they +are normally translated into core protocol +<symbol>MappingNotify</symbol> +events before being passed to the client. While delivering the event to the client is appropriate in most cases, it is not appropriate for some clients that maintain per-key data structures. This is because once the server has sent -a <emphasis> -NewKeyboardNotify</emphasis> - event, it is free to send the client events for all keys in the new range and +a +<symbol>NewKeyboardNotify</symbol> +event, it is free to send the client events for all keys in the new range and that range may be outside of the per-key data structures the client is maintaining. </para> <para> -The <emphasis> -IgnoreNewKeyboards</emphasis> - control, if enabled, prevents Xkb from mapping <emphasis> -NewKeyboardNotify</emphasis> - events to core <emphasis> -MappingNotify</emphasis> - events and passing them to the client. The control is initially disabled. +The +<emphasis>IgnoreNewKeyboards</emphasis> +control, if enabled, prevents Xkb from mapping +<symbol>NewKeyboardNotify</symbol> +events to core +<symbol>MappingNotify</symbol> +events and passing them to the client. The control is initially disabled. </para> @@ -367,10 +375,10 @@ MappingNotify</emphasis> <para> The Library Controls are manipulated using functions that deal with bitmasks to indicate which controls to manipulate. The controls are identified by the masks -defined in Table 11.1. <!-- xref --> +defined in <link linkend="table11.1">Table 11.1</link>. </para> -<table frame='topbot'> +<table id='table11.1' frame='topbot'> <title>Library Control Masks</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -384,35 +392,35 @@ defined in Table 11.1. <!-- xref --> </thead> <tbody> <row> - <entry>XkbLC_ForceLatin1Lookup</entry> + <entry><symbol>XkbLC_ForceLatin1Lookup</symbol></entry> <entry>(1 << 0)</entry> </row> <row> - <entry>XkbLC_ConsumeLookupMods</entry> + <entry><symbol>XkbLC_ConsumeLookupMods</symbol></entry> <entry>(1 << 1)</entry> </row> <row> - <entry>XkbLC_AlwaysConsumeShiftAndLock</entry> + <entry><symbol>XkbLC_AlwaysConsumeShiftAndLock</symbol></entry> <entry>(1 << 2)</entry> </row> <row> - <entry>XkbLC_IgnoreNewKeyboards</entry> + <entry><symbol>XkbLC_IgnoreNewKeyboards</symbol></entry> <entry>(1 << 3)</entry> </row> <row> - <entry>XkbLC_ConsumeKeysOnComposeFail</entry> + <entry><symbol>XkbLC_ConsumeKeysOnComposeFail</symbol></entry> <entry>(1 << 29)</entry> </row> <row> - <entry>XkbLC_ComposeLED</entry> + <entry><symbol>XkbLC_ComposeLED</symbol></entry> <entry>(1 << 30)</entry> </row> <row> - <entry>XkbLC_BeepOnComposeFail</entry> + <entry><symbol>XkbLC_BeepOnComposeFail</symbol></entry> <entry>(1 << 31)</entry> </row> <row> - <entry>XkbLC_AllControls</entry> + <entry><symbol>XkbLC_AllControls</symbol></entry> <entry>(0xc0000007)</entry> </row> </tbody> @@ -424,39 +432,38 @@ defined in Table 11.1. <!-- xref --> <para> To determine which Library Controls are actually -implemented, use <emphasis>XkbXlibControlsImplemented</emphasis>. +implemented, use <function>XkbXlibControlsImplemented</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -unsigned int <emphasis> -XkbXlibControlsImplemented</emphasis> -(<emphasis> -display</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbXlibControlsImplemented"><primary><function>XkbXlibControlsImplemented</function></primary></indexterm> +<funcsynopsis id="XkbXlibControlsImplemented"> + <funcprototype> + <funcdef>unsigned int <function>XkbXlibControlsImplemented</function></funcdef> +<!-- ( +<parameter>display</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbXlibControlsImplemented</emphasis> - returns a bitmask indicating the controls actually implemented in the Xkb -library and is composed of an inclusive OR of bits from Table 11.1. +<function>XkbXlibControlsImplemented</function> +returns a bitmask indicating the controls actually implemented in the Xkb +library and is composed of an inclusive OR of bits from +<link linkend="table11.1">Table 11.1</link>. </para> @@ -465,41 +472,39 @@ library and is composed of an inclusive OR of bits from Table 11.1. <title>Determining the State of the Library Controls</title> <para> -To determine the current state of the Library Controls, use <emphasis> -XkbGetXlibControls</emphasis> -. +To determine the current state of the Library Controls, use +<function>XkbGetXlibControls</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -unsigned int <emphasis> -XkbGetXlibControls</emphasis> -(<emphasis> -display</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbGetXlibControls"><primary><function>XkbGetXlibControls</function></primary></indexterm> +<funcsynopsis id="XkbGetXlibControls"> + <funcprototype> + <funcdef>unsigned int <function>XkbGetXlibControls</function></funcdef> +<!-- ( +<parameter>display</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbGetXlibControls</emphasis> - returns the current state of the Library Controls as a bit mask that is an -inclusive OR of the control masks from Table 11.1 for the controls that are +<function>XkbGetXlibControls</function> +returns the current state of the Library Controls as a bit mask that is an +inclusive OR of the control masks from +<link linkend="table11.1">Table 11.1</link> for the controls that are enabled. For the optional compose processing controls, the fact that a control is enabled does not imply that it is actually implemented. </para> @@ -510,65 +515,72 @@ is enabled does not imply that it is actually implemented. <para> To change the state of the Library Controls, use -<emphasis>XkbSetXlibControls</emphasis>. +<function>XkbSetXlibControls</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetXlibControls</emphasis> -(<emphasis> -display, bits_to_change, values_for_bits</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned long <emphasis> -bits_to_change</emphasis> -; /* selects controls to be modified */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned long <emphasis> -values_for_bits</emphasis> -; /* turns selected controls on (1) or off (0) */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbSetXlibControls"><primary><function>XkbSetXlibControls</function></primary></indexterm> +<funcsynopsis id="XkbSetXlibControls"> + <funcprototype> + <funcdef>Bool <function>XkbSetXlibControls</function></funcdef> +<!-- ( +<parameter>display, bits_to_change, values_for_bits</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned long <parameter>bits_to_change</parameter></paramdef> + <paramdef>unsigned long <parameter>values_for_bits</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>bits_to_change</parameter> + </term> + <listitem> + <para> + selects controls to be modified + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>values_for_bits</parameter> + </term> + <listitem> + <para> + turns selected controls on (1) or off (0) + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbSetXlibControls</emphasis> - modifies the state of the controls selected by <emphasis> -bits_to_change</emphasis> -; only the controls selected by <emphasis> -bits_to_change</emphasis> - are modified. If the bit corresponding to a control is on in <emphasis> -bits_to_change</emphasis> - and also on in values_for_bits, the control is enabled. If the bit -corresponding to a control is on in <emphasis> -bits_to_change</emphasis> - but off in <emphasis> -values_for_bits</emphasis> -, the control is disabled. <emphasis> -bits_to_change</emphasis> - should be an inclusive OR of bits from Table 11.1. +<function>XkbSetXlibControls</function> +modifies the state of the controls selected by +<parameter>bits_to_change</parameter>; +only the controls selected by +<parameter>bits_to_change</parameter> +are modified. If the bit corresponding to a control is on in +<parameter>bits_to_change</parameter> +and also on in values_for_bits, the control is enabled. If the bit +corresponding to a control is on in +<parameter>bits_to_change</parameter> +but off in +<parameter>values_for_bits</parameter>, +the control is disabled. +<parameter>bits_to_change</parameter> +should be an inclusive OR of bits from +<link linkend="table11.1">Table 11.1</link>. </para> </sect2> diff --git a/libX11/specs/XKB/ch12.xml b/libX11/specs/XKB/ch12.xml index 1a062014e..fcfa8f9f2 100644 --- a/libX11/specs/XKB/ch12.xml +++ b/libX11/specs/XKB/ch12.xml @@ -1,3 +1,6 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Interpreting_Key_Events'> <title>Interpreting Key Events</title> @@ -11,12 +14,12 @@ several core X library functions. <title>Effects of Xkb on the Core X Library</title> <para> -When support for Xkb is built into the X library, the <emphasis> -XOpenDisplay</emphasis> - function looks for a compatible version of Xkb on the server. If it finds a -compatible version, it initializes the extension and enables <emphasis> -implicit support</emphasis> - for Xkb in a number of X library functions. This makes it possible for clients +When support for Xkb is built into the X library, the +<function>XOpenDisplay</function> +function looks for a compatible version of Xkb on the server. If it finds a +compatible version, it initializes the extension and enables +<firstterm>implicit support</firstterm> +for Xkb in a number of X library functions. This makes it possible for clients to take advantage of nearly all Xkb features without having to be rewritten or even recompiled, if they are built with shared libraries. This implicit support is invisible to most clients, but it can have side effects, so the extension @@ -28,10 +31,10 @@ includes ways to control or disable it. <title>Effects of Xkb on Event State</title> <para> -Because <emphasis> -XOpenDisplay</emphasis> - initializes Xkb, some events contain an Xkb description of the keyboard state -instead of that normally used by the core protocol. See section 17.1.1 for more +Because +<function>XOpenDisplay</function> +initializes Xkb, some events contain an Xkb description of the keyboard state +instead of that normally used by the core protocol. See <link linkend="Xkb_State_to_Core_Protocol_State_Transformation">section 17.1.1</link> for more information about the differences between Xkb keyboard state and that reported by the core protocol. </para> @@ -41,50 +44,53 @@ by the core protocol. <sect2 id='Effects_of_Xkb_on_MappingNotify_Events'> <title>Effects of Xkb on MappingNotify Events</title> +<indexterm zone="Effects_of_Xkb_on_MappingNotify_Events"> +<primary>events</primary><secondary><symbol>MappingNotify</symbol></secondary></indexterm> + <para> When Xkb is missing or disabled, the X library tracks changes to the keyboard -mapping using <emphasis> -MappingNotify</emphasis> - events. Whenever the keyboard mapping is changed, the server sends all clients -a <emphasis> -MappingNotify</emphasis> - event to report the change. When a client receives a <emphasis> -MappingNotify</emphasis> - event, it is supposed to call <emphasis> -XRefreshKeyboardMapping</emphasis> - to update the keyboard description used internally by the X library. +mapping using +<symbol>MappingNotify</symbol> +events. Whenever the keyboard mapping is changed, the server sends all clients +a +<symbol>MappingNotify</symbol> +event to report the change. When a client receives a +<symbol>MappingNotify</symbol> +event, it is supposed to call +<function>XRefreshKeyboardMapping</function> +to update the keyboard description used internally by the X library. </para> <para> -The X Keyboard Extension uses <emphasis> -XkbMapNotify</emphasis> - and <emphasis> -XkbNewKeyboardNotify</emphasis> - events to track changes to the keyboard mapping. When an Xkb-aware client -receives either event, it should call <emphasis> -XkbRefreshKeyboardMapping</emphasis> - to update the keyboard description used internally by the X library. To avoid -duplicate events, the X server does not send core protocol <emphasis> -MappingNotify</emphasis> - events to a client that has selected for <emphasis> -XkbMapNotify</emphasis> - events. +The X Keyboard Extension uses +<symbol>XkbMapNotify</symbol> +and +<symbol>XkbNewKeyboardNotify</symbol> +events to track changes to the keyboard mapping. When an Xkb-aware client +receives either event, it should call +<function>XkbRefreshKeyboardMapping</function> +to update the keyboard description used internally by the X library. To avoid +duplicate events, the X server does not send core protocol +<symbol>MappingNotify</symbol> +events to a client that has selected for +<symbol>XkbMapNotify</symbol> +events. </para> <para> -The implicit support for Xkb selects for <emphasis> -XkbMapNotify</emphasis> - events. This means that clients that do not explicitly use Xkb but that are +The implicit support for Xkb selects for +<symbol>XkbMapNotify</symbol> +events. This means that clients that do not explicitly use Xkb but that are using a version of the X library that has implicit support for Xkb do not -receive <emphasis> -MappingNotify</emphasis> - events over the wire. Clients that were not written with Xkb in mind do not +receive +<symbol>MappingNotify</symbol> +events over the wire. Clients that were not written with Xkb in mind do not recognize or properly handle the new Xkb events, so the implicit support -converts them to <emphasis> -MappingNotify</emphasis> - events that report approximately the same information, unless the client has +converts them to +<symbol>MappingNotify</symbol> +events that report approximately the same information, unless the client has explicitly selected for the Xkb version of the event. </para> @@ -92,21 +98,20 @@ explicitly selected for the Xkb version of the event. <para> An Xkb-capable X server does not send events from keys that fall outside the legal range of keycodes expected by that client. Once the server sends a client -an <emphasis> -XkbNewKeyboardNotify</emphasis> - event, it reports events from all keys because it assumes that any client that -has receieved an <emphasis> -XkbNewKeyboardNotify</emphasis> - event expects key events from the new range of keycodes. The implicit support -for Xkb asks for <emphasis> -XkbNewKeyboardNotify</emphasis> - events, so the range of keycodes reported to the client might vary without the +an +<symbol>XkbNewKeyboardNotify</symbol> +event, it reports events from all keys because it assumes that any client that +has received an +<symbol>XkbNewKeyboardNotify</symbol> +event expects key events from the new range of keycodes. The implicit support +for Xkb asks for +<symbol>XkbNewKeyboardNotify</symbol> +events, so the range of keycodes reported to the client might vary without the client’s knowledge. Most clients don’t really care about the range of legal keycodes, but some clients maintain information about each key and might have problems with events that come from unexpected keys. Such clients can set the -<emphasis> -XkbLC_IgnoreNewKeyboards</emphasis> - library control (see section 11.3.1) to prevent the implicit support from +<symbol>XkbLC_IgnoreNewKeyboards</symbol> +library control (see <link linkend="IgnoreNewKeyboards">section 11.3.1</link>) to prevent the implicit support from requesting notification of changes to the legal range of keycodes. </para> @@ -117,16 +122,16 @@ requesting notification of changes to the legal range of keycodes. <para> The following X library functions are modified by Xkb: -</para> -<para><programlisting> - <emphasis>XKeycodeToKeysym</emphasis> - <emphasis>XKeysymToKeycode</emphasis> - <emphasis>XLookupKeysym</emphasis> - <emphasis>XLookupString</emphasis> - <emphasis>XRefreshKeyboardMapping</emphasis> - <emphasis>XRebindKeysym</emphasis> -</programlisting></para> + <simplelist type='vert' columns='1'> + <member><function>XKeycodeToKeysym</function></member> + <member><function>XKeysymToKeycode</function></member> + <member><function>XLookupKeysym</function></member> + <member><function>XLookupString</function></member> + <member><function>XRefreshKeyboardMapping</function></member> + <member><function>XRebindKeysym</function></member> + </simplelist> +</para> <para> The implicit support for Xkb replaces a number of X library functions with @@ -138,23 +143,25 @@ clients. </para> -<para> -The <emphasis> -XKeycodeToKeysym</emphasis> - function reports the keysym associated with a particular index for a single +<para id='XKeycodeToKeysym'> +The +<olink targetdoc='libX11' targetptr='XKeycodeToKeysym'><function>XKeycodeToKeysym</function></olink> +<indexterm significance="preferred" zone="XKeycodeToKeysym"><primary><function>XKeycodeToKeysym</function></primary></indexterm> +function reports the keysym associated with a particular index for a single key. The index specifies a column of symbols in the core keyboard mapping (that -is, as reported by the core protocol <emphasis> -GetKeyboardMapping</emphasis> - request). The order of the symbols in the core mapping does not necessarily -correspond to the order of the symbols used by Xkb; section 17.1.3 describes +is, as reported by the core protocol +<systemitem>GetKeyboardMapping</systemitem> +request). The order of the symbols in the core mapping does not necessarily +correspond to the order of the symbols used by Xkb; <link linkend="Xkb_Keyboard_Mapping_to_Core_Keyboard_Mapping_Transformations">section 17.1.3</link> describes the differences. </para> -<para> -The <emphasis> -XKeysymToKeycode</emphasis> - function reports a keycode to which a particular keysym is bound. When Xkb is +<para id='XKeysymToKeycode'> +The +<olink targetdoc='libX11' targetptr='XKeysymToKeycode'><function>XKeysymToKeycode</function></olink> +<indexterm significance="preferred" zone="XKeysymToKeycode"><primary><function>XKeysymToKeycode</function></primary></indexterm> +function reports a keycode to which a particular keysym is bound. When Xkb is missing or disabled, this function looks in each column of the core keyboard mapping in turn and returns the lowest numbered key that matches in the lowest numbered group. When Xkb is present, this function uses the Xkb ordering for @@ -162,65 +169,67 @@ symbols instead. </para> -<para> -The <emphasis> -XLookupKeysym</emphasis> - function reports the symbol in a specific column of the key associated with an +<para id='XLookupKeysym'> +The +<olink targetdoc='libX11' targetptr='XLookupKeysym'><function>XLookupKeysym</function></olink> +<indexterm significance="preferred" zone="XLookupKeysym"><primary><function>XLookupKeysym</function></primary></indexterm> +function reports the symbol in a specific column of the key associated with an event. Whether or not Xkb is present, the column specifies an index into the core symbol mapping. </para> -<para> -The <emphasis> -XLookupString</emphasis> - function reports the symbol and string associated with a key event, taking +<para id='XLookupString'> +The +<olink targetdoc='libX11' targetptr='XLookupString'><function>XLookupString</function></olink> +<indexterm significance="preferred" zone="XLookupString"><primary><function>XLookupString</function></primary></indexterm> +function reports the symbol and string associated with a key event, taking into account the keycode and keyboard state as reported in the event. When Xkb -is disabled or missing, <emphasis> -XLookupString</emphasis> - uses the rules specified by the core protocol and reports only ISO Latin-1 -characters. When Xkb is present, <emphasis> -XLookupString</emphasis> - uses the explicit keyboard group, key types, and rules specified by Xkb. When -Xkb is present, <emphasis> -XLookupString</emphasis> - is allowed, but not required, to return strings in character sets other than +is disabled or missing, +<function>XLookupString</function> +uses the rules specified by the core protocol and reports only ISO Latin-1 +characters. When Xkb is present, +<function>XLookupString</function> +uses the explicit keyboard group, key types, and rules specified by Xkb. When +Xkb is present, +<function>XLookupString</function> +is allowed, but not required, to return strings in character sets other than ISO Latin-1, depending on the current locale. If any key bindings are defined, -<emphasis> -XLookupString</emphasis> - does not use any consumed modifiers (see sections 11.1.2 and 15.2) to +<function>XLookupString</function> +does not use any consumed modifiers (see <link linkend="ConsumeLookupMods">section 11.1.2</link> and <link linkend="Key_Types">section 15.2</link>) to determine matching bindings. </para> -<para> -The <emphasis> -XRefreshKeyboardMapping</emphasis> - function updates the X library’s internal representation of the keyboard to -reflect changes reported via <emphasis> -MappingNotify</emphasis> - events. When Xkb is missing or disabled, this function reloads the entire +<para id='XRefreshKeyboardMapping'> +The +<olink targetdoc='libX11' targetptr='XRefreshKeyboardMapping'><function>XRefreshKeyboardMapping</function></olink> +<indexterm significance="preferred" zone="XRefreshKeyboardMapping"><primary><function>XRefreshKeyboardMapping</function></primary></indexterm> +function updates the X library’s internal representation of the keyboard to +reflect changes reported via +<symbol>MappingNotify</symbol> +events. When Xkb is missing or disabled, this function reloads the entire modifier map or keyboard mapping. When Xkb is present, the implicit Xkb support -keeps track of the changed components reported by each <emphasis> -XkbMapNotify</emphasis> - event and updates only those pieces of the keyboard description that have +keeps track of the changed components reported by each +<symbol>XkbMapNotify</symbol> +event and updates only those pieces of the keyboard description that have changed. If the implicit support has not noted any keyboard mapping changes, -<emphasis> -XRefreshKeyboardMapping</emphasis> - updates the entire keyboard description. +<function>XRefreshKeyboardMapping</function> +updates the entire keyboard description. </para> -<para> -The <emphasis> -XRebindKeysym</emphasis> - function associates a string with a keysym and a set of modifiers. Xkb does +<para id='XRebindKeysym'> +The +<olink targetdoc='libX11' targetptr='XRebindKeysym'><function>XRebindKeysym</function></olink> +<indexterm significance="preferred" zone="XRebindKeysym"><primary><function>XRebindKeysym</function></primary></indexterm> +function associates a string with a keysym and a set of modifiers. Xkb does not directly change this function, but it does affect the way that the state -reported in the event is compared to the state specified to <emphasis> -XRebindKeysym</emphasis> -. When Xkb is missing or disabled, <emphasis> -XLookupString</emphasis> - returns the specified string if the modifiers in the event exactly match the +reported in the event is compared to the state specified to +<function>XRebindKeysym</function>. +When Xkb is missing or disabled, +<function>XLookupString</function> +returns the specified string if the modifiers in the event exactly match the modifiers from this call. When Xkb is present, any modifiers used to determine the keysym are consumed and are not used to look up the string. </para> @@ -233,616 +242,645 @@ the keysym are consumed and are not used to look up the string. <para> To find the keysym bound to a particular key at a specified group and shift -level, use <emphasis>XkbKeycodeToKeysym</emphasis>. +level, use <function>XkbKeycodeToKeysym</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -KeySym <emphasis> -XkbKeycodeToKeysym</emphasis> -(<emphasis> -dpy, kc, group, level</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * dpy; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode kc; /* key of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int group; /* group of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int level; /* shift level of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbKeycodeToKeysym"><primary><function>XkbKeycodeToKeysym</function></primary></indexterm> +<funcsynopsis id="XkbKeycodeToKeysym"> + <funcprototype> + <funcdef>KeySym <function>XkbKeycodeToKeysym</function></funcdef> +<!-- ( +<parameter>dpy, kc, group, level</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>KeyCode <parameter>kc</parameter></paramdef> + <paramdef>unsigned int <parameter>group</parameter></paramdef> + <paramdef>unsigned int <parameter>level</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>kc</parameter> + </term> + <listitem> + <para> + key of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>group</parameter> + </term> + <listitem> + <para> + group of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>level</parameter> + </term> + <listitem> + <para> + shift level of interest + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbKeycodeToKeysym</emphasis> - returns the keysym bound to a particular group and shift level for a -particular key on the core keyboard. If <emphasis> -kc</emphasis> - is not a legal keycode for the core keyboard, or if <emphasis> -group</emphasis> - or <emphasis> -level</emphasis> - are out of range for the specified key, <emphasis> -XkbKeycodeToKeysym</emphasis> - returns <emphasis> -NoSymbol</emphasis> -. +<function>XkbKeycodeToKeysym</function> +returns the keysym bound to a particular group and shift level for a +particular key on the core keyboard. If +<parameter>kc</parameter> +is not a legal keycode for the core keyboard, or if +<parameter>group</parameter> +or +<parameter>level</parameter> +are out of range for the specified key, +<function>XkbKeycodeToKeysym</function> +returns +<symbol>NoSymbol</symbol>. </para> <para> To find the set of modifiers bound to a particular keysym on the core keyboard, -use <emphasis> -XkbKeysymToModifiers</emphasis> -. +use +<function>XkbKeysymToModifiers</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -unsigned<emphasis> - </emphasis> -int <emphasis> -XkbKeysymToModifiers</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - ks</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeySym <emphasis> - ks</emphasis> -; /* keysym of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbKeysymToModifiers"><primary><function>XkbKeysymToModifiers</function></primary></indexterm> +<funcsynopsis id="XkbKeysymToModifiers"> + <funcprototype> + <funcdef>unsigned int <function>XkbKeysymToModifiers</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>ks</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>KeySym <parameter>ks</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ks</parameter> + </term> + <listitem> + <para> + keysym of interest + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbKeysymToModifiers</emphasis> - finds the set of modifiers currently bound to the keysym <emphasis> -ks</emphasis> - on the core keyboard. The value returned is the mask of modifiers bound to the -keysym <emphasis> -ks</emphasis> -. If no modifiers are bound to the keysym, <emphasis> -XkbKeysymToModifiers</emphasis> - returns zero; otherwise, it returns the inclusive OR of zero or more of the -following: <emphasis> -ShiftMask</emphasis> -, <emphasis> -ControlMask</emphasis> -, <emphasis> -LockMask</emphasis> -, <emphasis> -Mod1Mask</emphasis> -, <emphasis> -Mod2Mask</emphasis> -, <emphasis> -Mod3Mask</emphasis> -, <emphasis> -Mod4Mask,</emphasis> - and <emphasis> -Mod5Mask</emphasis> -. +<function>XkbKeysymToModifiers</function> +finds the set of modifiers currently bound to the keysym +<parameter>ks</parameter> +on the core keyboard. The value returned is the mask of modifiers bound to the +keysym +<parameter>ks</parameter>. +If no modifiers are bound to the keysym, +<function>XkbKeysymToModifiers</function> +returns zero; otherwise, it returns the inclusive OR of zero or more of the +following: +<symbol>ShiftMask</symbol>, +<symbol>ControlMask</symbol>, +<symbol>LockMask</symbol>, +<symbol>Mod1Mask</symbol>, +<symbol>Mod2Mask</symbol>, +<symbol>Mod3Mask</symbol>, +<symbol>Mod4Mask</symbol>, +and +<symbol>Mod5Mask</symbol>. </para> <para> -Use <emphasis> -XkbLookupKeySym</emphasis> - to find the symbol associated with a key for a particular state. +Use +<function>XkbLookupKeySym</function> +to find the symbol associated with a key for a particular state. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbLookupKeySym</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - key</emphasis> -,<emphasis> - state</emphasis> -,<emphasis> - mods_rtrn</emphasis> -,<emphasis> - sym_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> - key</emphasis> -; /* key for which symbols are to be found */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - state</emphasis> -; /* state for which symbol should be found */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> - mods_rtrn</emphasis> -; /* backfilled with unconsumed modifiers */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeySym *<emphasis> - sym_rtrn</emphasis> -; /* backfilled with symbol associated with key + state */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbLookupKeySym"><primary><function>XkbLookupKeySym</function></primary></indexterm> +<funcsynopsis id="XkbLookupKeySym"> + <funcprototype> + <funcdef>Bool <function>XkbLookupKeySym</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>key</parameter>, +<parameter>state</parameter>, +<parameter>mods_rtrn</parameter>, +<parameter>sym_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>KeyCode <parameter>key</parameter></paramdef> + <paramdef>unsigned int <parameter>state</parameter></paramdef> + <paramdef>unsigned int *<parameter>mods_rtrn</parameter></paramdef> + <paramdef>KeySym *<parameter>sym_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>key</parameter> + </term> + <listitem> + <para> + key for which symbols are to be found + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>state</parameter> + </term> + <listitem> + <para> + state for which symbol should be found + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>mods_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with unconsumed modifiers + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>sym_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with symbol associated with key + state + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbLookupKeySym</emphasis> - is the equivalent of the core <emphasis> -XLookupKeySym</emphasis> - function. For the core keyboard, given a keycode <emphasis> -key</emphasis> - and an Xkb state <emphasis> -state</emphasis> -, <emphasis> -XkbLookupKeySym</emphasis> - returns the symbol associated with the key in <emphasis> -sym_rtrn</emphasis> - and the list of modifiers that should still be applied in <emphasis> -mods_rtrn</emphasis> -. The <emphasis> -state</emphasis> - parameter is the state from a <emphasis> -KeyPress</emphasis> - or <emphasis> -KeyRelease</emphasis> - event. <emphasis> -XkbLookupKeySym</emphasis> - returns <emphasis> -True</emphasis> - if it succeeds. +<function>XkbLookupKeySym</function> +is the equivalent of the core +<symbol>XLookupKeySym</symbol> +function. For the core keyboard, given a keycode +<parameter>key</parameter> +and an Xkb state +<parameter>state</parameter>, +<function>XkbLookupKeySym</function> +returns the symbol associated with the key in +<parameter>sym_rtrn</parameter> +and the list of modifiers that should still be applied in +<parameter>mods_rtrn</parameter>. +The +<parameter>state</parameter> +parameter is the state from a +<symbol>KeyPress</symbol> +or +<symbol>KeyRelease</symbol> +event. +<function>XkbLookupKeySym</function> +returns +<symbol>True</symbol> +if it succeeds. </para> <para> -Use <emphasis> -XkbLookupKeyBinding</emphasis> - to find the string bound to a key by <emphasis> -XRebindKeySym</emphasis> -. <emphasis> -XkbLookupKeyBinding</emphasis> - is the equivalent of the core <emphasis> -XLookupString</emphasis> - function. +Use +<function>XkbLookupKeyBinding</function> +to find the string bound to a key by +<function>XRebindKeysym</function>. +<function>XkbLookupKeyBinding</function> +is the equivalent of the core +<function>XLookupString</function> +function. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -int <emphasis> -XkbLookupKeyBinding</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - sym</emphasis> -,<emphasis> - state</emphasis> -,<emphasis> - buf</emphasis> -,<emphasis> - nbytes</emphasis> -,<emphasis> - extra_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> - dpy</emphasis> -; /* connection to server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeySym<emphasis> - sym</emphasis> -; /* symbol to be looked up */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -state</emphasis> -; /* state for which string is to be looked up */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -char * <emphasis> - buf</emphasis> -; /* buffer into which returned string is written */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - nbytes</emphasis> -; /* size of buffer in bytes */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int * <emphasis> - extra_rtrn</emphasis> -; /* backfilled with number bytes overflow */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbLookupKeyBinding"><primary><function>XkbLookupKeyBinding</function></primary></indexterm> +<funcsynopsis id="XkbLookupKeyBinding"> + <funcprototype> + <funcdef>int <function>XkbLookupKeyBinding</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>sym</parameter>, +<parameter>state</parameter>, +<parameter>buf</parameter>, +<parameter>nbytes</parameter>, +<parameter>extra_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>KeySym <parameter>sym</parameter></paramdef> + <paramdef>unsigned int <parameter>state</parameter></paramdef> + <paramdef>char *<parameter>buf</parameter></paramdef> + <paramdef>int <parameter>nbytes</parameter></paramdef> + <paramdef>int *<parameter>extra_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>sym</parameter> + </term> + <listitem> + <para> + symbol to be looked up + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>state</parameter> + </term> + <listitem> + <para> + state for which string is to be looked up + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>buf</parameter> + </term> + <listitem> + <para> + buffer into which returned string is written + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>nbytes</parameter> + </term> + <listitem> + <para> + size of buffer in bytes + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>extra_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with number bytes overflow + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XRebindKeysym</emphasis> - binds an ASCII string to a specified keysym, so that the string and keysym are +<function>XRebindKeysym</function> +binds an ASCII string to a specified keysym, so that the string and keysym are returned when the key is pressed and a specified list of modifiers are also -being held down. <emphasis> -XkbLookupKeyBinding</emphasis> - returns in <emphasis> -buf</emphasis> - the string associated with the keysym <emphasis> -sym</emphasis> - and modifier state <emphasis> -state</emphasis> -. <emphasis> -buf</emphasis> - is <emphasis> -NULL</emphasis> - terminated unless there’s an overflow. If the string returned is larger than -<emphasis> -nbytes</emphasis> -, a count of bytes that does not fit into the buffer is returned in extra_rtrn. -<emphasis> -XkbTranslateKeySym</emphasis> - returns the number of bytes that it placed into <emphasis> -buf</emphasis> -. +being held down. +<function>XkbLookupKeyBinding</function> +returns in +<parameter>buf</parameter> +the string associated with the keysym +<parameter>sym</parameter> +and modifier state +<parameter>state</parameter>. +<parameter>buf</parameter> +is +<symbol>NULL</symbol> +terminated unless there’s an overflow. If the string returned is larger than +<parameter>nbytes</parameter>, +a count of bytes that does not fit into the buffer is returned in extra_rtrn. +<function>XkbTranslateKeySym</function> +returns the number of bytes that it placed into +<parameter>buf</parameter>. </para> <para> To find the string and symbol associated with a keysym for a given keyboard -state, use <emphasis> -XkbTranslateKeySym</emphasis> -. +state, use +<function>XkbTranslateKeySym</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -int <emphasis> -XkbTranslateKeySym</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - sym_inout</emphasis> -,<emphasis> - mods</emphasis> -,<emphasis> - buf</emphasis> -,<emphasis> - nbytes</emphasis> -, <emphasis> -extra_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeySym * <emphasis> - sym_inout</emphasis> -; /* symbol to be translated; result of translation */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - mods</emphasis> -; /* modifiers to apply to <emphasis> -sym_inout</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -char * <emphasis> - buf</emphasis> -; /* buffer into which returned string is written */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - nbytes</emphasis> -; /* size of buffer in bytes */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int *<emphasis> - extra_rtrn</emphasis> -; /* number of bytes overflow*/ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbTranslateKeySym"><primary><function>XkbTranslateKeySym</function></primary></indexterm> +<funcsynopsis id="XkbTranslateKeySym"> + <funcprototype> + <funcdef>int <function>XkbTranslateKeySym</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>sym_inout</parameter>, +<parameter>mods</parameter>, +<parameter>buf</parameter>, +<parameter>nbytes</parameter>, +<parameter>extra_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>KeySym *<parameter>sym_inout</parameter></paramdef> + <paramdef>unsigned int <parameter>mods</parameter></paramdef> + <paramdef>char *<parameter>buf</parameter></paramdef> + <paramdef>int <parameter>nbytes</parameter></paramdef> + <paramdef>int *<parameter>extra_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>sym_inout</parameter> + </term> + <listitem> + <para> + symbol to be translated; result of translation + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>mods</parameter> + </term> + <listitem> + <para> + modifiers to apply to <parameter>sym_inout</parameter> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>buf</parameter> + </term> + <listitem> + <para> + buffer into which returned string is written + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>nbytes</parameter> + </term> + <listitem> + <para> + size of buffer in bytes + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>extra_rtrn</parameter> + </term> + <listitem> + <para> + number of bytes overflow + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbTranslateKeySym</emphasis> - applies the transformations specified in <emphasis> -mods</emphasis> - to the symbol specified by <emphasis> -sym_inout</emphasis> -. It returns in <emphasis> -buf</emphasis> - the string, if any, associated with the keysym for the current locale. If the -transformations in <emphasis> -mods</emphasis> - changes the keysym, <emphasis> -sym_inout</emphasis> - is updated accordingly. If the string returned is larger than <emphasis> -nbytes</emphasis> -, a count of bytes that does not fit into the buffer is returned in extra_rtrn. -<emphasis> -XkbTranslateKeySym</emphasis> - returns the number of bytes it placed into <emphasis> -buf</emphasis> -. +<function>XkbTranslateKeySym</function> +applies the transformations specified in +<parameter>mods</parameter> +to the symbol specified by +<parameter>sym_inout</parameter>. +It returns in +<parameter>buf</parameter> +the string, if any, associated with the keysym for the current locale. If the +transformations in +<parameter>mods</parameter> +changes the keysym, +<parameter>sym_inout</parameter> +is updated accordingly. If the string returned is larger than +<parameter>nbytes</parameter>, +a count of bytes that does not fit into the buffer is returned in extra_rtrn. +<function>XkbTranslateKeySym</function> +returns the number of bytes it placed into +<parameter>buf</parameter>. </para> <para> To update the keyboard description that is internal to the X library, use -<emphasis> -XkbRefreshKeyboardMapping</emphasis> -. +<function>XkbRefreshKeyboardMapping</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbRefreshKeyboardMapping</emphasis> -(<emphasis> -event)</emphasis> - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbMapNotifyEvent * <emphasis> - event</emphasis> -; /* event initiating remapping */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbRefreshKeyboardMapping"><primary><function>XkbRefreshKeyboardMapping</function></primary></indexterm> +<funcsynopsis id="XkbRefreshKeyboardMapping"> + <funcprototype> + <funcdef>Status <function>XkbRefreshKeyboardMapping</function></funcdef> +<!-- ( +<parameter>event)</parameter> --> + + <paramdef>XkbMapNotifyEvent *<parameter>event</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>event</parameter> + </term> + <listitem> + <para> + event initiating remapping + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbRefreshKeyboardMapping</emphasis> - is the Xkb equivalent of the core <emphasis> -XRefreshKeyboardMapping</emphasis> - function. It requests that the X server send the current key mapping -information to this client. A client usually invokes <emphasis> -XkbRefreshKeyboardMapping</emphasis> - after receiving an <emphasis> -XkbMapNotify</emphasis> - event. <emphasis> -XkbRefreshKeyboardMapping</emphasis> - returns <emphasis> -Success</emphasis> - if it succeeds and <emphasis> -BadMatch</emphasis> - if the event is not an Xkb event. +<function>XkbRefreshKeyboardMapping</function> +is the Xkb equivalent of the core +<function>XRefreshKeyboardMapping</function> +function. It requests that the X server send the current key mapping +information to this client. A client usually invokes +<function>XkbRefreshKeyboardMapping</function> +after receiving an +<symbol>XkbMapNotify</symbol> +event. +<function>XkbRefreshKeyboardMapping</function> +returns +<symbol>Success</symbol> +if it succeeds and +<errorname>BadMatch</errorname> +if the event is not an Xkb event. </para> <para> -The <emphasis> -XkbMapNotify</emphasis> - event can be generated when some client calls <emphasis> -XkbSetMap</emphasis> -, <emphasis> -XkbChangeMap</emphasis> -, <emphasis> -XkbGetKeyboardByName</emphasis> -, or any of the standard X library functions that change the keyboard mapping +The +<symbol>XkbMapNotify</symbol> +event can be generated when some client calls +<function>XkbSetMap</function>, +<function>XkbChangeMap</function>, +<function>XkbGetKeyboardByName</function>, +or any of the standard X library functions that change the keyboard mapping or modifier mapping. </para> <para> -To translate a keycode to a key symbol and modifiers, use <emphasis> -XkbTranslateKeyCode</emphasis> -. +To translate a keycode to a key symbol and modifiers, use +<function>XkbTranslateKeyCode</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Booll <emphasis> -XkbTranslateKeyCode</emphasis> -(<emphasis> -xkb, key, mods, mods_rtrn, keysym_rtrn)</emphasis> - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description to use for translation */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -key</emphasis> -; /* keycode to translate */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -mods</emphasis> -; /* modifiers to apply when translating <emphasis> -key</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -mods_rtrn</emphasis> -; /* backfilled with unconsumed modifiers */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeySym * <emphasis> -keysym_rtrn</emphasis> -; /* keysym resulting from translation */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbTranslateKeyCode"><primary><function>XkbTranslateKeyCode</function></primary></indexterm> +<funcsynopsis id="XkbTranslateKeyCode"> + <funcprototype> + <funcdef>Bool <function>XkbTranslateKeyCode</function></funcdef> +<!-- ( +<parameter>xkb, key, mods, mods_rtrn, keysym_rtrn)</parameter> --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>key</parameter></paramdef> + <paramdef>unsigned int <parameter>mods</parameter></paramdef> + <paramdef>unsigned int *<parameter>mods_rtrn</parameter></paramdef> + <paramdef>KeySym *<parameter>keysym_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description to use for translation + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>key</parameter> + </term> + <listitem> + <para> + keycode to translate + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>mods</parameter> + </term> + <listitem> + <para> + modifiers to apply when translating <parameter>key</parameter> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>mods_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with unconsumed modifiers + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keysym_rtrn</parameter> + </term> + <listitem> + <para> + keysym resulting from translation + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -mods_rtrn</emphasis> - is backfilled with the modifiers consumed by the translation process. -<emphasis> -mods</emphasis> - is a bitwise inclusive OR of the legal modifier masks: <emphasis> -ShiftMask</emphasis> -, <emphasis> -LockMask</emphasis> -, <emphasis> -ControlMask</emphasis> -, <emphasis> -Mod1Mask</emphasis> -, <emphasis> -Mod2Mask</emphasis> -, <emphasis> -Mod3Mask</emphasis> -, <emphasis> -Mod4Mask</emphasis> -, <emphasis> -Mod5Mask</emphasis> -.The <emphasis> -AlwaysConsumeShiftAndLock</emphasis> - library control (see section 11.1.3), if enabled, causes <emphasis> -XkbTranslateKeyCode</emphasis> - to consume shift and lock.<emphasis> - XkbTranslateKeyCode</emphasis> - returns <emphasis> -True</emphasis> - if the translation resulted in a keysym, and <emphasis> -False</emphasis> - if it resulted in <emphasis> -NoSymbol</emphasis> -. +<parameter>mods_rtrn</parameter> +is backfilled with the modifiers consumed by the translation process. +<parameter>mods</parameter> +is a bitwise inclusive OR of the legal modifier masks: +<symbol>ShiftMask</symbol>, +<symbol>LockMask</symbol>, +<symbol>ControlMask</symbol>, +<symbol>Mod1Mask</symbol>, +<symbol>Mod2Mask</symbol>, +<symbol>Mod3Mask</symbol>, +<symbol>Mod4Mask</symbol>, +<symbol>Mod5Mask</symbol>. +The +<emphasis>AlwaysConsumeShiftAndLock</emphasis> +library control (see <link linkend="AlwaysConsumeShiftAndLock">section 11.1.3</link>), if enabled, causes +<function>XkbTranslateKeyCode</function> +to consume shift and lock. +<function>XkbTranslateKeyCode</function> +returns +<symbol>True</symbol> +if the translation resulted in a keysym, and +<symbol>False</symbol> +if it resulted in +<symbol>NoSymbol</symbol>. </para> </sect1> </chapter> diff --git a/libX11/specs/XKB/ch13.xml b/libX11/specs/XKB/ch13.xml index ed6066d10..b07a900e6 100644 --- a/libX11/specs/XKB/ch13.xml +++ b/libX11/specs/XKB/ch13.xml @@ -1,3 +1,6 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Keyboard_Geometry'> <title>Keyboard Geometry</title> @@ -25,17 +28,18 @@ top left corner of the keyboard image. A component’s own origin is also its upper left corner. In some cases a component needs to be drawn rotated. For example, a special keyboard may have a section of keys arranged in rows in a rectangular area, but the entire rectangle may not be in alignment with the -rest of the keyboard, and instead, it is rotated from horizontal by 30<emphasis> -o</emphasis> -. Rotation for a geometry object is specified in 1/10 o increments about its -origin. An example of a keyboard with rotated sections is shown in Figure 13.1. +rest of the keyboard, and instead, it is rotated from horizontal by 30°. +Rotation for a geometry object is specified in 1/10° increments about its +origin. An example of a keyboard with rotated sections is shown in <link linkend="figure13.1">Figure 13.1</link>. </para> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-7.svg"/> - </imageobject> -<caption>Rotated Keyboard Sections</caption> -</mediaobject> +<figure id='figure13.1'> + <title>Rotated Keyboard Sections</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-7.svg"/> + </imageobject> + </mediaobject> +</figure> <!-- <H5 CLASS="Figure"> @@ -43,17 +47,19 @@ Rotated Keyboard Sections</H5> --> <para> -Some geometry components include a <emphasis> -priority</emphasis> -, which indicates the order in which overlapping objects should be drawn. +Some geometry components include a +<structfield>priority</structfield>, +which indicates the order in which overlapping objects should be drawn. Objects should be drawn in order from highest priority (0) to lowest (255). </para> -<para> -The keyboard geometry’s top-level description is stored in a <emphasis> -XkbGeometryRec</emphasis> - structure. This structure contains three types of information: +<para id='XkbGeometryRec'> +<indexterm significance="preferred" zone="XkbGeometryRec"> +<primary><structname>XkbGeometryRec</structname></primary></indexterm> +The keyboard geometry’s top-level description is stored in a +<structname>XkbGeometryRec</structname> +structure. This structure contains three types of information: </para> <orderedlist> @@ -91,14 +97,13 @@ as follows: <itemizedlist> <listitem> <para> -The top-level keyboard geometry description includes a list of up to <emphasis> -MaxColors</emphasis> - (32) <emphasis> -color names</emphasis> -. A color name is a string whose interpretation is not specified by Xkb. The -<emphasis> -XkbColorRec</emphasis> - structure provides a field for this name as well as a pixel field. The pixel +The top-level keyboard geometry description includes a list of up to +<symbol>XkbGeomMaxColors</symbol> +(32) +<firstterm>color names</firstterm>. +A color name is a string whose interpretation is not specified by Xkb. The +<structname>XkbColorRec</structname> +structure provides a field for this name as well as a pixel field. The pixel field is a convenient place for an application to store a pixel value or color definition, if it needs to. All other geometry data structures refer to colors using their indices in this global list. @@ -106,15 +111,15 @@ using their indices in this global list. </listitem> <listitem> <para> -The top-level keyboard geometry description includes a list of <emphasis> -geometry properties</emphasis> -. A geometry property associates an arbitrary string with an equally arbitrary +The top-level keyboard geometry description includes a list of +<firstterm>geometry properties</firstterm>. +A geometry property associates an arbitrary string with an equally arbitrary name. Geometry properties can be used to provide hints to programs that display images of keyboards, but they are not interpreted by Xkb. No other geometry structures refer to geometry properties. As an example of a possible use of -<emphasis> -properties</emphasis> -, consider the pause/break key on most PC keyboards: the "break" symbol is +<structfield>properties</structfield>, +consider the pause/break key on most PC keyboards: the <quote>break</quote> +symbol is usually on the front of the key and is often a different color. A program might set a property to: </para> @@ -128,40 +133,39 @@ a top label. </listitem> <listitem> <para> -The top-level keyboard geometry description includes a list of <emphasis> -key aliases</emphasis> - (see Chapter 18). Key aliases allow the keyboard layout designer to assign +The top-level keyboard geometry description includes a list of +<firstterm>key aliases</firstterm> +(see <xref linkend="Symbolic_Names" />). Key aliases allow the keyboard layout designer to assign multiple key names to a single key. </para> <note><para>Key aliases defined in the geometry component of a keyboard mapping override those defined in the keycodes component of the server database, which -are stored in the <emphasis> -XkbNamesRec</emphasis> - (<emphasis> -xkb->names</emphasis> -). Therefore, consider the key aliases defined by the geometry before +are stored in the +<structname>XkbNamesRec</structname> + +(<structfield>xkb->names</structfield>). +Therefore, consider the key aliases defined by the geometry before considering key aliases supplied by the keycodes.</para></note> </listitem> <listitem> <para> -The top-level keyboard geometry description includes a list of <emphasis> -shapes</emphasis> -; other keyboard components refer to shapes by their index in this list. A +The top-level keyboard geometry description includes a list of +<structfield>shapes</structfield>; +other keyboard components refer to shapes by their index in this list. A shape consists of an arbitrary name of type Atom and one or more closed-polygon -<emphasis> -outlines</emphasis> -. All points in an outline are specified relative to the origin of its +<structfield>outlines</structfield>. +All points in an outline are specified relative to the origin of its enclosing shape, that is, whichever shape that contains this outline in its list of outlines. One outline is the primary outline. The primary outline is by -default the first outline, or it can be optionally specified by the <emphasis> -primary</emphasis> - field in the <emphasis> -XkbShapeRec</emphasis> - structure. A keyboard display application can generate a simpler but still +default the first outline, or it can be optionally specified by the +<structfield>primary</structfield> +field in the +<structname>XkbShapeRec</structname> +structure. A keyboard display application can generate a simpler but still accurate keyboard image by displaying only the primary outlines for each shape. -Nonrectangular keys must include a rectangular <emphasis> -approximation</emphasis> - as one of the outlines associated with the shape. The approximation is not +Nonrectangular keys must include a rectangular +<firstterm>approximation</firstterm> +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> @@ -169,50 +173,50 @@ to generate a recognizable but degraded image of the keyboard. </itemizedlist> <para> -The <emphasis> -XkbGeometryRec</emphasis> - top-level geometry description contains the following information that +The +<structname>XkbGeometryRec</structname> +top-level geometry description contains the following information that pertains to the keyboard as a whole: </para> <itemizedlist> <listitem> <para> -A <emphasis> -keyboard symbolic name</emphasis> - of type Atom to help users identify the keyboard. +A +<firstterm>keyboard symbolic name</firstterm> +of type Atom to help users identify the keyboard. </para> </listitem> <listitem> <para> -The <emphasis> -width</emphasis> - and <emphasis> -height</emphasis> - of the keyboard, in mm/10. For nonrectangular keyboards, the width and height +The +<structfield>width</structfield> +and +<structfield>height</structfield> +of the keyboard, in mm/10. For nonrectangular keyboards, the width and height describe the smallest bounding box that encloses the outline of the keyboard. </para> </listitem> <listitem> <para> -The<emphasis> - base color</emphasis> - of the keyboard is the predominant color on the keyboard and is used as the +The +<firstterm>base color</firstterm> +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. +The +<firstterm>label color</firstterm> +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 that describes the font used to draw labels on most keys; label +The +<firstterm>label font</firstterm> +is a string that describes the font used to draw labels on most keys; label fonts are arbitrary strings, because Xkb does not specify the format or name space for font names. </para> @@ -220,24 +224,26 @@ space for font names. </itemizedlist> <para> -The keyboard is subdivided into named <emphasis> -sections</emphasis> - of related keys and doodads. The sections and doodads on the keyboard are -listed in the <emphasis> -XkbGeometryRec</emphasis> - top-level keyboard geometry description. A section is composed of keys that -are physically together and logically related. Figure 13.2 shows a keyboard -that is divided into four sections. A <emphasis> -doodad</emphasis> - describes some visible aspect of the keyboard that is not a key and is not a +The keyboard is subdivided into named +<structfield>sections</structfield> +of related keys and doodads. The sections and doodads on the keyboard are +listed in the +<structname>XkbGeometryRec</structname> +top-level keyboard geometry description. A section is composed of keys that +are physically together and logically related. <link linkend="figure13.2">Figure 13.2</link> shows a keyboard +that is divided into four sections. A +<structfield>doodad</structfield> +describes some visible aspect of the keyboard that is not a key and is not a section. </para> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-8.svg"/> - </imageobject> -<caption>Keyboard with Four Sections</caption> -</mediaobject> +<figure id='figure13.2'> + <title>Keyboard with Four Sections</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-8.svg"/> + </imageobject> + </mediaobject> +</figure> <!-- <H5 CLASS="Figure"> @@ -248,11 +254,11 @@ Keyboard with Four Sections</H5> <title>Shapes and Outlines</title> <para> -A <emphasis> -shape</emphasis> -, used to draw keyboard components and stored in a <emphasis> -XkbShapeRec</emphasis> - structure, has: +A +<structfield>shape</structfield>, +used to draw keyboard components and stored in a +<structname>XkbShapeRec</structname> +structure, has: </para> <itemizedlist> @@ -275,20 +281,20 @@ A list of one or more outlines (described below). <listitem> <para> Optional pointers to a primary and an approximation outline (described below). -If either of these pointers is <emphasis> -NULL</emphasis> -, the default primary/approximation outline is the first one in the list of +If either of these pointers is +<symbol>NULL</symbol>, +the default primary/approximation outline is the first one in the list of outlines for the shape. </para> </listitem> </itemizedlist> <para> -An <emphasis> -outline</emphasis> -, stored in a <emphasis> -XkbOutlineRec</emphasis> - structure, is a list of one or more points that describes a single +An +<firstterm>outline</firstterm>, +stored in a +<structname>XkbOutlineRec</structname> +structure, is a list of one or more points that describes a single closed-polygon, as follows: </para> @@ -315,9 +321,9 @@ with the first. </listitem> <listitem> <para> -A nonzero value for the <emphasis> -corner_radius</emphasis> - field specifies that the corners of the polygon should be drawn as circles +A nonzero value for the +<structfield>corner_radius</structfield> +field specifies that the corners of the polygon should be drawn as circles with the specified radius. </para> </listitem> @@ -333,15 +339,15 @@ shape. Points in an outline may have negative values for the X and Y coordinate. One outline is the primary outline; a keyboard display application can generate a simple but still accurate keyboard image by displaying only the primary outlines for each shape. The default primary outline is the first in a -shape’s list of outlines. If the <emphasis> -primary</emphasis> - field of the <emphasis> -XkbShapeRec</emphasis> - structure is not <emphasis> -NULL</emphasis> -, it points to the primary outline. A rectangular <emphasis> -approximation</emphasis> - must be included for nonrectangular keys as one of the outlines associated +shape’s list of outlines. If the +<structfield>primary</structfield> +field of the +<structname>XkbShapeRec</structname> +structure is not +<symbol>NULL</symbol>, +it points to the primary outline. A rectangular +<firstterm>approximation</firstterm> +must be included for nonrectangular keys as one of the outlines associated with the shape; the approximation is not normally displayed but can be used by very simple keyboard display applications to generate a recognizable but degraded image of the keyboard. @@ -352,14 +358,14 @@ degraded image of the keyboard. <title>Sections</title> <para> -As previously noted, a keyboard is subdivided into <emphasis> -sections</emphasis> - of related keys. Each section has its own coordinate system — if a section +As previously noted, a keyboard is subdivided into +<structfield>sections</structfield> +of related keys. Each section has its own coordinate system — if a section is rotated, the coordinates of any components within the section are interpreted relative to the edges that were on the top and left before -rotation. The components that make up a section, stored in a <emphasis> -XkbSectionRec</emphasis> -, include: +rotation. The components that make up a section, stored in a +<structname>XkbSectionRec</structname>, +include: </para> <itemizedlist> @@ -386,23 +392,25 @@ The width and height and the angle of rotation. </listitem> <listitem> <para> -A list of <emphasis> -rows</emphasis> -. A row is a list of horizontally or vertically adjacent keys. Horizontal rows +A list of +<structfield>rows</structfield>. +A row is a list of horizontally or vertically adjacent keys. Horizontal rows parallel the (prerotation) top of the section, and vertical rows parallel the (prerotation) left of the section. All keys in a horizontal row share a common -top coordinate; all keys in a vertical row share a left coordinate. Figure 13.3 -shows the alpha section from the keyboard shown in Figure 13.2, divided into +top coordinate; all keys in a vertical row share a left coordinate. <link linkend="figure13.3">Figure 13.3</link> +shows the alpha section from the keyboard shown in <link linkend="figure13.2">Figure 13.2</link>, divided into rows. Rows and keys are defined below. </para> </listitem> </itemizedlist> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-9.svg"/> - </imageobject> - <caption>Rows in a Section</caption> -</mediaobject> +<figure id='figure13.3'> + <title>Rows in a Section</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-9.svg"/> + </imageobject> + </mediaobject> +</figure> @@ -413,9 +421,9 @@ Rows in a Section</H5> <itemizedlist> <listitem> <para> -An optional list of <emphasis> -doodads</emphasis> -; any type of doodad can be enclosed within a section. Position and angle of +An optional list of +<structfield>doodads</structfield>; +any type of doodad can be enclosed within a section. Position and angle of rotation are relative to the origin and angle of rotation of the sections that contain them. Priority for doodads in a section is relative to the other components of the section, not to the keyboard as a whole. @@ -423,9 +431,9 @@ components of the section, not to the keyboard as a whole. </listitem> <listitem> <para> -An optional <emphasis> -overlay</emphasis> - with a name of type Atom and a list of overlay rows (described below). +An optional +<firstterm>overlay</firstterm> +with a name of type Atom and a list of overlay rows (described below). </para> </listitem> <listitem> @@ -440,24 +448,23 @@ containing the entire section. <title>Rows and Keys</title> <para> -A row description (<emphasis> -XkbRowRec</emphasis> -) consists of the coordinates of its origin relative to its enclosing section, +A row description +(<structname>XkbRowRec</structname>) +consists of the coordinates of its origin relative to its enclosing section, a flag indicating whether the row is horizontal or vertical, and a list of keys in the row. </para> <para> -A key description (<emphasis> -XkbKeyRec</emphasis> -) consists of a key name, a shape, a key color, and a gap. The key name should +A key description +(<structname>XkbKeyRec</structname>) +consists of a key name, a shape, a key color, and a gap. The key name should correspond to one of the keys named in the keyboard names description, the shape specifies the appearance of the key, and the key color specifies the color of the key (not the label on the key; the label color is stored in the -<emphasis> -XkbGeometryRec</emphasis> -). Keys are normally drawn immediately adjacent to one another from left to +<structname>XkbGeometryRec</structname>). +Keys are normally drawn immediately adjacent to one another from left to right (or top to bottom) within a row. The gap field specifies the distance between a key and its predecessor. </para> @@ -470,25 +477,25 @@ between a key and its predecessor. <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, if present, describes the outline of the -entire keyboard. +is specified by Xkb is <quote>Edges</quote>, which, if present, describes the +outline of the entire keyboard. </para> <para> -Each doodad’s origin is stored in fields named <emphasis> -left</emphasis> - and <emphasis> -top</emphasis> -, which are the coordinates of the doodad’s origin relative to its enclosing +Each doodad’s origin is stored in fields named +<structfield>left</structfield> +and +<structfield>top</structfield>, +which are the coordinates of the doodad’s origin relative to its enclosing object, whether it be a section or the top-level keyboard. The priority for doodads that are listed in the top-level geometry is relative to the other doodads listed in the top-level geometry and the sections listed in the top-level geometry. The priority for doodads listed in a section are relative to the other components of the section. Each doodad is stored in a structure -with a <emphasis> -type</emphasis> - field, which specifies the type of doodad. +with a +<structfield>type</structfield> +field, which specifies the type of doodad. </para> <para> @@ -498,47 +505,47 @@ Xkb supports five types of doodads: <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> -). +An +<firstterm>indicator doodad</firstterm> +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, +An +<firstterm>outline doodad</firstterm> +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 +A +<firstterm>solid doodad</firstterm> +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 +A +<firstterm>text doodad</firstterm> +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> +A +<firstterm>logo doodad</firstterm> is a catch-all, which describes some other visible element of the keyboard. A logo doodad is essentially an outline doodad with an additional symbolic name that describes the element to be drawn. If a keyboard display program @@ -552,12 +559,12 @@ specify the interpretation of logo names. </itemizedlist> <para> -The structures these doodads are stored in and the values of the <emphasis> -type</emphasis> - fields are shown in Table 13.1. +The structures these doodads are stored in and the values of the +<structfield>type</structfield> +fields are shown in <link linkend="table13.1">Table 13.1</link>. </para> -<table frame='topbot'> +<table id='table13.1' frame='topbot'> <title>Doodad Types</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -573,58 +580,58 @@ type</emphasis> </thead> <tbody> <row> - <entry><emphasis> -indicator doodad</emphasis> + <entry> +<emphasis>indicator doodad</emphasis> </entry> - <entry><emphasis> -XkbIndicatorDoodadRec</emphasis> + <entry> +<structname>XkbIndicatorDoodadRec</structname> </entry> - <entry><emphasis> -XkbIndicatorDoodad</emphasis> + <entry> +<symbol>XkbIndicatorDoodad</symbol> </entry> </row> <row> - <entry><emphasis> -outline doodad</emphasis> + <entry> +<emphasis>outline doodad</emphasis> </entry> - <entry><emphasis> -XkbShapeDoodadRec</emphasis> + <entry> +<structname>XkbShapeDoodadRec</structname> </entry> - <entry><emphasis> -XkbOutlineDoodad</emphasis> + <entry> +<symbol>XkbOutlineDoodad</symbol> </entry> </row> <row> - <entry><emphasis> -solid doodad</emphasis> + <entry> +<emphasis>solid doodad</emphasis> </entry> - <entry><emphasis> -XkbShapeDoodadRec</emphasis> + <entry> +<structname>XkbShapeDoodadRec</structname> </entry> - <entry><emphasis> -XkbSolidDoodad</emphasis> + <entry> +<symbol>XkbSolidDoodad</symbol> </entry> </row> <row> - <entry><emphasis> -text doodad</emphasis> + <entry> +<emphasis>text doodad</emphasis> </entry> - <entry><emphasis> -XkbTextDoodadRec</emphasis> + <entry> +<structname>XkbTextDoodadRec</structname> </entry> - <entry><emphasis> -XkbTextDoodad</emphasis> + <entry> +<symbol>XkbTextDoodad</symbol> </entry> </row> <row> - <entry><emphasis> -logo doodad</emphasis> + <entry> +<emphasis>logo doodad</emphasis> </entry> - <entry><emphasis> -XkbLogoDoodadRec</emphasis> + <entry> +<structname>XkbLogoDoodadRec</structname> </entry> - <entry><emphasis> -XkbLogoDoodad</emphasis> + <entry> +<symbol>XkbLogoDoodad</symbol> </entry> </row> </tbody> @@ -636,28 +643,27 @@ XkbLogoDoodad</emphasis> <title>Overlay Rows and Overlay Keys</title> <para> -An <emphasis> -overlay row</emphasis> - (<emphasis> -XkbOverlayRowRec</emphasis> -) contains a pointer to the row it overlays and a list of <emphasis> -overlay keys</emphasis> -. +An +<firstterm>overlay row</firstterm> + +(<structname>XkbOverlayRowRec</structname>) +contains a pointer to the row it overlays and a list of +<firstterm>overlay keys</firstterm>. </para> <para> -Each overlay key definition (<emphasis> -XkbOverlayKeyRec</emphasis> -) indicates a key that can yield multiple keycodes 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, +Each overlay key definition +(<structname>XkbOverlayKeyRec</structname>) +indicates a key that can yield multiple keycodes and consists of a field +named +<structfield>under</structfield>, +which specifies the primary name of the key and a field named +<structfield>over</structfield>, +which specifies the name for the key when the overlay keycode is selected. +The key specified in +<structfield>under</structfield> +must be a member of the section that contains the overlay key definition, while the key specified in over must not be. </para> @@ -668,9 +674,8 @@ while the key specified in over must not be. <para> To draw a representation of the keyboard, draw in the following order: -</para> -<para><programlisting> +<programlisting> Draw the top-level keyboard as a rectangle, using its width and height. For each component (section or doodad) of the top-level geometry, in priority order: If component is a section @@ -694,11 +699,13 @@ pointer into the array. <MAP NAME="XKBlib-10"> </MAP> --> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-10.svg"/> - </imageobject> -<caption>Xkb Geometry Data Structures</caption> -</mediaobject> +<figure id='figure13.4'> + <title>Xkb Geometry Data Structures</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-10.svg"/> + </imageobject> + </mediaobject> +</figure> <!-- <H5 CLASS="Figure"> @@ -708,11 +715,13 @@ Xkb Geometry Data Structures</H5> <MAP NAME="XKBlib-11"> </MAP> --> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-11.svg"/> - </imageobject> -<caption>Xkb Geometry Data Structures (Doodads)</caption> -</mediaobject> +<figure id='figure13.5'> + <title>Xkb Geometry Data Structures (Doodads)</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-11.svg"/> + </imageobject> + </mediaobject> +</figure> <!-- <H5 CLASS="Figure"> @@ -723,251 +732,257 @@ Xkb Geometry Data Structures (Doodads)</H5> <MAP NAME="XKBlib-12"> </MAP> --> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-12.svg"/> - </imageobject> -<caption>Xkb Geometry Data Structures (Overlays)</caption> -</mediaobject> +<figure id='figure13.6'> + <title>Xkb Geometry Data Structures (Overlays)</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-12.svg"/> + </imageobject> + </mediaobject> +</figure> <!-- <H5 CLASS="Figure"> Xkb Geometry Data Structures (Overlays)</H5> --> <para><programlisting> -typedef struct _XkbGeometry { /* top-level keyboard geometry structure */ - Atom name; /* keyboard name */ - unsigned short width_mm; /* keyboard width in <emphasis> mm</emphasis> /<emphasis> 10</emphasis> */ - unsigned short height_mm; /* keyboard height in <emphasis> mm</emphasis> /<emphasis> 10</emphasis> */ - char * label_font; /* font for key labels */ - XkbColorPtr label_color; /* color for key labels - pointer into colors array */ - XkbColorPtr base_color; /* color for basic keyboard - pointer into colors array */ - unsigned short sz_properties; /* size of properties array */ - unsigned short sz_colors; /* size of colors array */ - unsigned short sz_shapes; /* size of shapes array */ - unsigned short sz_sections; /* size of sections array */ - unsigned short sz_doodads; /* size of doodads array */ - unsigned short sz_key_aliases; /* size of key aliases array */ - unsigned short num_properties; /* number of properties in the properties array */ - unsigned short num_colors; /* number of colors in the colors array */ - unsigned short num_shapes; /* number of shapes in the shapes array */ - unsigned short num_sections; /* number of sections in the sections array */ - unsigned short num_doodads; /* number of doodads in the doodads array */ - unsigned short num_key_aliases; /* number of key aliases in the key */ - XkbPropertyPtr properties; /* properties array */ - XkbColorPtr colors; /* colors array */ - XkbShapePtr shapes; /* shapes array */ - XkbSectionPtr sections; /* sections array */ - XkbDoodadPtr doodads; /* doodads array */ - XkbKeyAliasPtr key_aliases; /* key aliases array */ -} <emphasis>XkbGeometryRec</emphasis>*XkbGeometryPtr; +typedef struct _XkbGeometry { /* top-level keyboard geometry structure */ + Atom name; /* keyboard name */ + unsigned short width_mm; /* keyboard width in <superscript>mm</superscript>/<subscript>10</subscript> */ + unsigned short height_mm; /* keyboard height in <superscript>mm</superscript>/<subscript>10</subscript> */ + char * label_font; /* font for key labels */ + XkbColorPtr label_color; /* color for key labels + - pointer into colors array */ + XkbColorPtr base_color; /* color for basic keyboard + - pointer into colors array */ + unsigned short sz_properties; /* size of properties array */ + unsigned short sz_colors; /* size of colors array */ + unsigned short sz_shapes; /* size of shapes array */ + unsigned short sz_sections; /* size of sections array */ + unsigned short sz_doodads; /* size of doodads array */ + unsigned short sz_key_aliases; /* size of key aliases array */ + unsigned short num_properties; /* number of properties in the + properties array */ + unsigned short num_colors; /* number of colors in the + colors array */ + unsigned short num_shapes; /* number of shapes in the + shapes array */ + unsigned short num_sections; /* number of sections in the + sections array */ + unsigned short num_doodads; /* number of doodads in the + doodads array */ + unsigned short num_key_aliases; /* number of key aliases in the + key_aliases array */ + XkbPropertyPtr properties; /* properties array */ + XkbColorPtr colors; /* colors array */ + XkbShapePtr shapes; /* shapes array */ + XkbSectionPtr sections; /* sections array */ + XkbDoodadPtr doodads; /* doodads array */ + XkbKeyAliasPtr key_aliases; /* key aliases array */ +} <structname>XkbGeometryRec</structname>, *XkbGeometryPtr; </programlisting></para> <para> -The <emphasis> -doodads</emphasis> - array is only for doodads not contained in any of the <emphasis> -sections</emphasis> - that has its own <emphasis> -doodads</emphasis> -. The key aliases contained in the <emphasis> -key_aliases</emphasis> - array take precedence over any defined in the keycodes component of the +The +<structfield>doodads</structfield> +array is only for doodads not contained in any of the +<structfield>sections</structfield> +that has its own +<structfield>doodads</structfield>. +The key aliases contained in the +<structfield>key_aliases</structfield> +array take precedence over any defined in the keycodes component of the keyboard description. </para> <para><programlisting> typedef struct _XkbProperty { - char * name; /* property name */ - char * value; /* property value */ -} <emphasis>XkbPropertyRec</emphasis>,*XkbPropertyPtr; + char * name; /* property name */ + char * value; /* property value */ +} <structname>XkbPropertyRec</structname>, *XkbPropertyPtr; </programlisting></para> <para><programlisting> typedef struct _XkbColor { - unsigned int pixel; /* color */ - char * spec; /* color name */ -} <emphasis>XkbColorRec</emphasis>,*XkbColorPtr; + unsigned int pixel; /* color */ + char * spec; /* color name */ +} <structname>XkbColorRec</structname>, *XkbColorPtr; </programlisting></para> <para><programlisting> typedef struct _XkbKeyAliasRec { - char real[XkbKeyNameLength]; /* real name of the key */ - char alias[XkbKeyNameLength]; /* alias for the key */ -} <emphasis>XkbKeyAliasRec</emphasis>,*XkbKeyAliasPtr; + char real[XkbKeyNameLength]; /* real name of the key */ + char alias[XkbKeyNameLength]; /* alias for the key */ +} <structname>XkbKeyAliasRec</structname>, *XkbKeyAliasPtr; </programlisting></para> <para><programlisting> -typedef struct _XkbPoint { /* x,y coordinates */ - short x; - short y; -} <emphasis>XkbPointRec</emphasis>, *XkbPointPtr; +typedef struct _XkbPoint { /* x, y coordinates */ + short x; + short y; +} <structname>XkbPointRec</structname>, *XkbPointPtr; </programlisting></para> <para><programlisting> typedef struct _XkbOutline { - unsigned short num_points; /* number of points in the outline */ - unsigned short sz_points; /* size of the points array */ - unsigned short corner_radius; /* draw corners as circles with this radius */ - XkbPointPtr points; /* array of points defining the outline */ -} <emphasis>XkbOutlineRec</emphasis>, *XkbOutlinePtr; + unsigned short num_points; /* number of points in the outline */ + unsigned short sz_points; /* size of the points array */ + unsigned short corner_radius; /* draw corners as circles + with this radius */ + XkbPointPtr points; /* array of points defining + the outline */ +} <structname>XkbOutlineRec</structname>, *XkbOutlinePtr; </programlisting></para> <para><programlisting> typedef struct _XkbBounds { - short x1,y1; /* upper left corner of the bounds, - in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */ - short x2,y2; /* lower right corner of the bounds, in - <emphasis>mm</emphasis>/<emphasis>10</emphasis> */ -} <emphasis>XkbBoundsRec</emphasis>, *XkbBoundsPtr; + short x1, y1; /* upper left corner of the bounds, in <superscript>mm</superscript>/<subscript>10</subscript> */ + short x2, y2; /* lower right corner of the bounds, in <superscript>mm</superscript>/<subscript>10</subscript> */ +} <structname>XkbBoundsRec</structname>, *XkbBoundsPtr; </programlisting></para> <para><programlisting> typedef struct _XkbShape { - Atom name; /* shape’s name */ - unsigned short num_outlines; /* number of outlines for the shape */ - unsigned short sz_outlines; /* size of the outlines array */ - XkbOutlinePtr outlines; /* array of outlines for the shape */ - XkbOutlinePtr approx; /* pointer into the array to the approximating outline */ - XkbOutlinePtr primary; /* pointer into the array to the primary outline */ - XkbBoundsRec bounds; /* bounding box for the shape; encompasses all outlines */ -} <emphasis>XkbShapeRec</emphasis>, *XkbShapePtr; + Atom name; /* shape’s name */ + unsigned short num_outlines; /* number of outlines for the shape */ + unsigned short sz_outlines; /* size of the outlines array */ + XkbOutlinePtr outlines; /* array of outlines for the shape */ + XkbOutlinePtr approx; /* pointer into the array to the + approximating outline */ + XkbOutlinePtr primary; /* pointer into the array to the + primary outline */ + XkbBoundsRec bounds; /* bounding box for the shape; + encompasses all outlines */ +} <structname>XkbShapeRec</structname>, *XkbShapePtr; </programlisting></para> <para> -If <emphasis> -approx</emphasis> - and/or <emphasis> -primary</emphasis> - is <emphasis> -NULL</emphasis> -, the default value is used. The default primary outline is the first element +If +<structfield>approx</structfield> +and/or +<structfield>primary</structfield> +is +<symbol>NULL</symbol>, +the default value is used. The default primary outline is the first element in the outlines array, as is the default approximating outline. </para> <para><programlisting> -typedef struct _XkbKey { /* key in a row */ - XkbKeyNameRec name; /* key name */ - short gap; /* gap in <emphasis>mm</emphasis>/<emphasis>10</emphasis> from previous key in row */ - unsigned char shape_ndx; /* index of shape for key */ - unsigned char color_ndx; /* index of color for key body */ -} <emphasis>XkbKeyRec</emphasis>, *XkbKeyPtr; +typedef struct _XkbKey { /* key in a row */ + XkbKeyNameRec name; /* key name */ + short gap; /* gap in <superscript>mm</superscript>/<subscript>10</subscript> from previous key in row */ + unsigned char shape_ndx; /* index of shape for key */ + unsigned char color_ndx; /* index of color for key body */ +} <structname>XkbKeyRec</structname>, *XkbKeyPtr; </programlisting></para> <para><programlisting> -typedef struct _XkbRow { /* row in a section */ - short top; /* top coordinate of row origin, relative to section’s origin */ - short left; /* left coordinate of row origin, relative to section’s origin */ - unsigned short num_keys; /* number of keys in the keys array */ - unsigned short sz_keys; /* size of the keys array */ - int vertical; /* <emphasis>True</emphasis> =>vertical row, - <emphasis> False</emphasis> =>horizontal row */ - XkbKeyPtr keys; /* array of keys in the row*/ - XkbBoundsRec bounds; /* bounding box for the row */ -} <emphasis>XkbRowRec</emphasis>, *XkbRowPtr; +typedef struct _XkbRow { /* row in a section */ + short top; /* top coordinate of row origin, + relative to section’s origin */ + short left; /* left coordinate of row origin, + relative to section’s origin */ + unsigned short num_keys; /* number of keys in the keys array */ + unsigned short sz_keys; /* size of the keys array */ + int vertical; /* <symbol>True</symbol> ⇒vertical row, + <symbol>False</symbol> ⇒horizontal row */ + XkbKeyPtr keys; /* array of keys in the row */ + XkbBoundsRec bounds; /* bounding box for the row */ +} <structname>XkbRowRec</structname>, *XkbRowPtr; </programlisting></para> <para> -<emphasis> -top</emphasis> - and <emphasis> -left</emphasis> - are in <emphasis> -mm</emphasis> -/<emphasis> -10</emphasis> -. +<structfield>top</structfield> +and +<structfield>left</structfield> +are in +<superscript>mm</superscript>/<subscript>10</subscript>. </para> <para><programlisting> typedef struct _XkbOverlayRec { - Atom name; /* overlay name */ - XkbSectionPtr section_under; /* the section under this overlay */ - unsigned short num_rows; /* number of rows in the rows array */ - unsigned short sz_rows; /* size of the rows array */ - XkbOverlayRowPtr rows; /* array of rows in the overlay */ - XkbBoundsPtr bounds; /* bounding box for the overlay */ -} <emphasis>XkbOverlayRec</emphasis>,*XkbOverlayPtr; + Atom name; /* overlay name */ + XkbSectionPtr section_under; /* the section under this overlay */ + unsigned short num_rows; /* number of rows in the rows array */ + unsigned short sz_rows; /* size of the rows array */ + XkbOverlayRowPtr rows; /* array of rows in the overlay */ + XkbBoundsPtr bounds; /* bounding box for the overlay */ +} <structname>XkbOverlayRec</structname>, *XkbOverlayPtr; </programlisting></para> <para><programlisting> typedef struct _XkbOverlayRow { - unsigned short row_under; /* index into the row under this overlay row */ - unsigned short num_keys; /* number of keys in the keys array */ - unsigned short sz_keys; /* size of the keys array */ - XkbOverlayKeyPtr keys; /* array of keys in the overlay row */ -} <emphasis>XkbOverlayRowRec</emphasis>,*XkbOverlayRowPtr; + unsigned short row_under; /* index into the row under this + overlay row */ + unsigned short num_keys; /* number of keys in the keys array */ + unsigned short sz_keys; /* size of the keys array */ + XkbOverlayKeyPtr keys; /* array of keys in the overlay row */ +} <structname>XkbOverlayRowRec</structname>, *XkbOverlayRowPtr; </programlisting></para> <para> -<emphasis> -row_under</emphasis> - is an index into the array of <emphasis> -rows</emphasis> - in the section under this overlay. The section under this overlay row is the -one pointed to by <emphasis> -section_under</emphasis> - in this overlay row’s <emphasis> -XkbOverlayRec</emphasis> -. +<structfield>row_under</structfield> +is an index into the array of +<structfield>rows</structfield> +in the section under this overlay. The section under this overlay row is the +one pointed to by +<structfield>section_under</structfield> +in this overlay row’s +<structname>XkbOverlayRec</structname>. </para> <para><programlisting> typedef struct _XkbOverlayKey { - XkbKeyNameRec over; /* name of this overlay key */ - XkbKeyNameRec under; /* name of the key under this overlay key */ -} <emphasis>XkbOverlayKeyRec</emphasis>,*XkbOverlayKeyPtr; + XkbKeyNameRec over; /* name of this overlay key */ + XkbKeyNameRec under; /* name of the key under this overlay key */ +} <structname>XkbOverlayKeyRec</structname>, *XkbOverlayKeyPtr; </programlisting></para> <para><programlisting> typedef struct _XkbSection { - Atom name; /* section name */ - unsigned char priority; /* drawing priority, 0=>highest, 255=>lowest */ - short top; /* top coordinate of section origin */ - short left; /* left coordinate of row origin */ - unsigned short width; /* section width, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */ - unsigned short height; /* section height, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */ - short angle; /* angle of section rotation, counterclockwise */ - unsigned short num_rows; /* number of rows in the rows array */ - unsigned short num_doodads; /* number of doodads in the doodads array */ - unsigned short num_overlays; /* number of overlays in the overlays array */ - unsigned short sz_rows; /* size of the rows array */ - unsigned short sz_doodads; /* size of the doodads array */ - unsigned short sz_overlays; /* size of the overlays array */ - XkbRowPtr rows; /* section rows array */ - XkbDoodadPtr doodads; /* section doodads array */ - XkbBoundsRec bounds; /* bounding box for the section, before rotation*/ - XkbOverlayPtr overlays; /* section overlays array */ -} <emphasis>XkbSectionRec</emphasis>, *XkbSectionPtr; + Atom name; /* section name */ + unsigned char priority; /* drawing priority, 0⇒highest, 255⇒lowest */ + short top; /* top coordinate of section origin */ + short left; /* left coordinate of row origin */ + unsigned short width; /* section width, in <superscript>mm</superscript>/<subscript>10</subscript> */ + unsigned short height; /* section height, in <superscript>mm</superscript>/<subscript>10</subscript> */ + short angle; /* angle of section rotation, + counterclockwise */ + unsigned short num_rows; /* number of rows in the rows array */ + unsigned short num_doodads; /* number of doodads in the doodads array */ + unsigned short num_overlays; /* number of overlays in the overlays array */ + unsigned short sz_rows; /* size of the rows array */ + unsigned short sz_doodads; /* size of the doodads array */ + unsigned short sz_overlays; /* size of the overlays array */ + XkbRowPtr rows; /* section rows array */ + XkbDoodadPtr doodads; /* section doodads array */ + XkbBoundsRec bounds; /* bounding box for the section, + before rotation */ + XkbOverlayPtr overlays; /* section overlays array */ +} <structname>XkbSectionRec</structname>, *XkbSectionPtr; </programlisting></para> <para> -<emphasis> -top</emphasis> - and <emphasis> -left</emphasis> - are the origin of the section, relative to the origin of the keyboard, in -<emphasis> -mm</emphasis> -/<emphasis> -10</emphasis> -. <emphasis> -angle</emphasis> - is in <emphasis> -1</emphasis> -/<emphasis> -10</emphasis> - degrees. +<structfield>top</structfield> +and +<structfield>left</structfield> +are the origin of the section, relative to the origin of the keyboard, in +<superscript>mm</superscript>/<subscript>10</subscript>. +<structfield>angle</structfield> +is in +<superscript>1</superscript>/<subscript>10</subscript> +degrees. </para> <sect2 id='DoodadRec_Structures'> <title>DoodadRec Structures</title> <para> -The doodad arrays in the <emphasis> -XkbGeometryRec</emphasis> - and the <emphasis> -XkbSectionRec</emphasis> - may contain any of the doodad structures and types shown in Table 13.1. +The doodad arrays in the +<structname>XkbGeometryRec</structname> +and the +<structname>XkbSectionRec</structname> +may contain any of the doodad structures and types shown in +<link linkend="table13.1">Table 13.1</link>. </para> @@ -977,99 +992,101 @@ The doodad structures form a union: <para><programlisting> typedef union _XkbDoodad { - XkbAnyDoodadRec any; - XkbShapeDoodadRec shape; - XkbTextDoodadRec text; - XkbIndicatorDoodadRec indicator; - XkbLogoDoodadRec logo; -} <emphasis>XkbDoodadRec</emphasis>, *XkbDoodadPtr; + XkbAnyDoodadRec any; + XkbShapeDoodadRec shape; + XkbTextDoodadRec text; + XkbIndicatorDoodadRec indicator; + XkbLogoDoodadRec logo; +} <structname>XkbDoodadRec</structname>, *XkbDoodadPtr; </programlisting></para> <para> -The <emphasis> -top</emphasis> - and <emphasis> -left</emphasis> - coordinates of each doodad are the coordinates of the origin of the doodad -relative to the keyboard’s origin if the doodad is in the <emphasis> -XkbGeometryRec</emphasis> - doodad array, and with respect to the section’s origin if the doodad is in a -<emphasis> -XkbSectionRec</emphasis> - doodad array. The <emphasis> -color_ndx</emphasis> - or <emphasis> -on_color_ndx</emphasis> - and <emphasis> -off_color_ndx</emphasis> - fields are color indices into the <emphasis> -XkbGeometryRec</emphasis> -’s color array and are the colors to draw the doodads with. Similarly, the -<emphasis> -shape_ndx</emphasis> - fields are indices into the <emphasis> -XkbGeometryRec</emphasis> -’s shape array. +The +<structfield>top</structfield> +and +<structfield>left</structfield> +coordinates of each doodad are the coordinates of the origin of the doodad +relative to the keyboard’s origin if the doodad is in the +<structname>XkbGeometryRec</structname> +doodad array, and with respect to the section’s origin if the doodad is in a +<structname>XkbSectionRec</structname> +doodad array. The +<structfield>color_ndx</structfield> +or +<structfield>on_color_ndx</structfield> +and +<structfield>off_color_ndx</structfield> +fields are color indices into the +<structname>XkbGeometryRec</structname>’s +color array and are the colors to draw the doodads with. Similarly, the +<structfield>shape_ndx</structfield> +fields are indices into the +<structname>XkbGeometryRec</structname>’s +shape array. </para> <para><programlisting> typedef struct _XkbShapeDoodad { - Atom name; /* doodad name */ - unsigned char type; /* <emphasis>XkbOutlineDoodad</emphasis> - or <emphasis>XkbSolidDoodad</emphasis> */ - unsigned char priority; /* drawing priority, - 0=>highest, 255=>lowest */ - short top; /* top coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */ - short left; /* left coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */ - short angle; /* angle of rotation, clockwise, in <emphasis>1</emphasis>/<emphasis>10</emphasis> degrees */ - unsigned short color_ndx; /* doodad color */ - unsigned short shape_ndx; /* doodad shape */ -} <emphasis>XkbShapeDoodadRec</emphasis>, *XkbShapeDoodadPtr; + Atom name; /* doodad name */ + unsigned char type; /* <symbol>XkbOutlineDoodad</symbol> + or <symbol>XkbSolidDoodad</symbol> */ + unsigned char priority; /* drawing priority, + 0⇒highest, 255⇒lowest */ + short top; /* top coordinate, in <superscript>mm</superscript>/<subscript>10</subscript> */ + short left; /* left coordinate, in <superscript>mm</superscript>/<subscript>10</subscript> */ + short angle; /* angle of rotation, clockwise, + in <superscript>1</superscript>/<subscript>10</subscript> degrees */ + unsigned short color_ndx; /* doodad color */ + unsigned short shape_ndx; /* doodad shape */ +} <structname>XkbShapeDoodadRec</structname>, *XkbShapeDoodadPtr; </programlisting></para> <para><programlisting> typedef struct _XkbTextDoodad { - Atom name; /* doodad name */ - unsigned char type; /* <emphasis> XkbTextDoodad</emphasis> */ - unsigned char priority; /* drawing priority, - 0=>highest, 255=>lowest */ - short top; /* top coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */ - short left; /* left coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */ - short angle; /* angle of rotation, clockwise, in <emphasis>1</emphasis>/<emphasis>10</emphasis> degrees */ - short width; /* width in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */ - short height; /* height in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */ - unsigned short color_ndx; /* doodad color */ - char * text; /* doodad text */ - char * font; /* arbitrary font name for doodad text */ -} <emphasis>XkbTextDoodadRec</emphasis>, *XkbTextDoodadPtr; + Atom name; /* doodad name */ + unsigned char type; /* <symbol>XkbTextDoodad</symbol> */ + unsigned char priority; /* drawing priority, + 0⇒highest, 255⇒lowest */ + short top; /* top coordinate, in <superscript>mm</superscript>/<subscript>10</subscript> */ + short left; /* left coordinate, in <superscript>mm</superscript>/<subscript>10</subscript> */ + short angle; /* angle of rotation, clockwise, + in <superscript>1</superscript>/<subscript>10</subscript> degrees */ + short width; /* width in <superscript>mm</superscript>/<subscript>10</subscript> */ + short height; /* height in <superscript>mm</superscript>/<subscript>10</subscript> */ + unsigned short color_ndx; /* doodad color */ + char * text; /* doodad text */ + char * font; /* arbitrary font name for doodad text */ +} <structname>XkbTextDoodadRec</structname>, *XkbTextDoodadPtr; </programlisting></para> <para><programlisting> typedef struct _XkbIndicatorDoodad { - Atom name; /* doodad name */ - unsigned char type; /* <emphasis>XkbIndicatorDoodad</emphasis> */ - unsigned char priority; /* drawing priority, 0=>highest, 255=>lowest */ - short top; /* top coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */ - short left; /* left coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */ - short angle; /* angle of rotation, clockwise, in <emphasis>1</emphasis>/<emphasis>10</emphasis> degrees */ - unsigned short shape_ndx; /* doodad shape */ - unsigned short on_color_ndx; /* color for doodad if indicator is on */ - unsigned short off_color_ndx; /* color for doodad if indicator is off */ -} <emphasis>XkbIndicatorDoodadRec</emphasis>, *XkbIndicatorDoodadPtr; + Atom name; /* doodad name */ + unsigned char type; /* <symbol>XkbIndicatorDoodad</symbol> */ + unsigned char priority; /* drawing priority, 0⇒highest, 255⇒lowest */ + short top; /* top coordinate, in <superscript>mm</superscript>/<subscript>10</subscript> */ + short left; /* left coordinate, in <superscript>mm</superscript>/<subscript>10</subscript> */ + short angle; /* angle of rotation, clockwise, + in <superscript>1</superscript>/<subscript>10</subscript> degrees */ + unsigned short shape_ndx; /* doodad shape */ + unsigned short on_color_ndx; /* color for doodad if indicator is on */ + unsigned short off_color_ndx;/* color for doodad if indicator is off */ +} <structname>XkbIndicatorDoodadRec</structname>, *XkbIndicatorDoodadPtr; </programlisting></para> <para><programlisting> typedef struct _XkbLogoDoodad { - Atom name; /* doodad name */ - unsigned char type; /* <emphasis> XkbLogoDoodad</emphasis> */ - unsigned char priority; /* drawing priority, 0=>highest, 255=>lowest */ - short top; /* top coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */ - short left; /* left coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */ - short angle; /* angle of rotation, clockwise, in <emphasis>1</emphasis>/<emphasis>10</emphasis> degrees */ - unsigned short color_ndx; /* doodad color */ - unsigned short shape_ndx; /* doodad shape */ - char * logo_name; /* text for logo */ -} <emphasis>XkbLogoDoodadRec</emphasis>, *XkbLogoDoodadPtr + Atom name; /* doodad name */ + unsigned char type; /* <symbol>XkbLogoDoodad</symbol> */ + unsigned char priority; /* drawing priority, 0⇒highest, 255⇒lowest */ + short top; /* top coordinate, in <superscript>mm</superscript>/<subscript>10</subscript> */ + short left; /* left coordinate, in <superscript>mm</superscript>/<subscript>10</subscript> */ + short angle; /* angle of rotation, clockwise, + in <superscript>1</superscript>/<subscript>10</subscript> degrees */ + unsigned short color_ndx; /* doodad color */ + unsigned short shape_ndx; /* doodad shape */ + char * logo_name; /* text for logo */ +} <structname>XkbLogoDoodadRec</structname>, *XkbLogoDoodadPtr </programlisting></para> </sect2> @@ -1079,131 +1096,133 @@ typedef struct _XkbLogoDoodad { <para> You can load a keyboard geometry as part of the keyboard description returned -by <emphasis> -XkbGetKeyboard</emphasis> -. However, if a keyboard description has been previously loaded, you can -instead obtain the geometry by calling the <emphasis> -XkbGetGeometry</emphasis> -. In this case, the geometry returned is the one associated with the keyboard +by +<function>XkbGetKeyboard</function>. +However, if a keyboard description has been previously loaded, you can +instead obtain the geometry by calling the +<function>XkbGetGeometry</function>. +In this case, the geometry returned is the one associated with the keyboard whose device ID is contained in the keyboard description. </para> <para> To load a keyboard geometry if you already have the keyboard description, use -<emphasis>XkbGetGeometry</emphasis>. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetGeometry</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* keyboard description that contains the ID for the keyboard and into -which the geometry should be loaded */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetGeometry</emphasis> - can return <emphasis> -BadValue</emphasis> -, <emphasis> -BadImplementation</emphasis> -, <emphasis> -BadName</emphasis> -, <emphasis> -BadAlloc,</emphasis> - or <emphasis> -BadLength</emphasis> - errors or <emphasis> -Success</emphasis> - if it succeeds. +<function>XkbGetGeometry</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetGeometry"><primary><function>XkbGetGeometry</function></primary></indexterm> +<funcsynopsis id="XkbGetGeometry"> + <funcprototype> + <funcdef>Status <function>XkbGetGeometry</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>xkb</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description that contains the ID for the keyboard and into + which the geometry should be loaded + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetGeometry</function> +can return +<errorname>BadValue</errorname>, +<errorname>BadImplementation</errorname>, +<errorname>BadName</errorname>, +<errorname>BadAlloc</errorname>, +or +<errorname>BadLength</errorname> +errors or +<symbol>Success</symbol> +if it succeeds. </para> <para> It is also possible to load a keyboard geometry by name. The X server maintains -a database of keyboard components (see Chapter 20). To load a keyboard geometry -description from this database by name, use <emphasis> -XkbGetNamedGeometry</emphasis>. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetNamedGeometry</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - xkb</emphasis> -,<emphasis> - name</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description into which the geometry should be loaded */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Atom <emphasis> -name</emphasis> -; /* name of the geometry to be loaded */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetNamedGeometry</emphasis> - can return <emphasis> -BadName</emphasis> - if the <emphasis> -name</emphasis> - cannot be found. +a database of keyboard components (see <xref linkend="Server_Database_of_Keyboard_Components" />). To load a keyboard geometry +description from this database by name, use +<function>XkbGetNamedGeometry</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetNamedGeometry"><primary><function>XkbGetNamedGeometry</function></primary></indexterm> +<funcsynopsis id="XkbGetNamedGeometry"> + <funcprototype> + <funcdef>Status <function>XkbGetNamedGeometry</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>xkb</parameter>, +<parameter>name</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>Atom <parameter>name</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description into which the geometry should be loaded + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>name</parameter> + </term> + <listitem> + <para> + name of the geometry to be loaded + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetNamedGeometry</function> +can return +<errorname>BadName</errorname> +if the +<parameter>name</parameter> +cannot be found. </para> </sect1> @@ -1222,11 +1241,13 @@ of a number of points. The bounding box of a shape is a rectangle that contains all the outlines of that shape. </para> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-13.svg"/> - </imageobject> -<caption>Key Surface, Shape Outlines, and Bounding Box</caption> - </mediaobject> +<figure id='figure13.7'> + <title>Key Surface, Shape Outlines, and Bounding Box</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-13.svg"/> + </imageobject> + </mediaobject> +</figure> <!-- @@ -1235,321 +1256,318 @@ Key Surface, Shape Outlines, and Bounding Box</H5> --> <para> -To determine the bounding box of the top surface of a shape, use <emphasis> -XkbComputeShapeTop</emphasis>. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbComputeShapeTop</emphasis> -(<emphasis> -shape</emphasis> -,<emphasis> - bounds_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbShapePtr <emphasis> - shape</emphasis> -; /* shape to be examined */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbBoundsPtr <emphasis> - bounds_rtrn</emphasis> - /* backfilled with the bounding box for the shape */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbComputeShapeTop</emphasis> - returns a <emphasis> -BoundsRec</emphasis> - that contains two x and y coordinates. These coordinates describe the corners +To determine the bounding box of the top surface of a shape, use +<function>XkbComputeShapeTop</function>. +</para> + +<indexterm significance="preferred" zone="XkbComputeShapeTop"><primary><function>XkbComputeShapeTop</function></primary></indexterm> +<funcsynopsis id="XkbComputeShapeTop"> + <funcprototype> + <funcdef>Bool <function>XkbComputeShapeTop</function></funcdef> +<!-- ( +<parameter>shape</parameter>, +<parameter>bounds_rtrn</parameter> +) --> + + <paramdef>XkbShapePtr <parameter>shape</parameter></paramdef> + <paramdef>XkbBoundsPtr <parameter>bounds_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>shape</parameter> + </term> + <listitem> + <para> + shape to be examined + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>bounds_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with the bounding box for the shape + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbComputeShapeTop</function> +returns a +<structname>BoundsRec</structname> +that contains two x and y coordinates. These coordinates describe the corners of a rectangle that contains the outline that describes the top surface of the shape. The top surface is defined to be the approximating outline if the -<emphasis> -approx</emphasis> - field of <emphasis> -shape</emphasis> - is not <emphasis> -NULL</emphasis> -. If <emphasis> -approx</emphasis> - is <emphasis> -NULL</emphasis> -, the top surface is defined as the last outline in the <emphasis> -shape</emphasis> -’s array of outlines. <emphasis> -XkbComputeShapeTop</emphasis> - returns <emphasis> -False</emphasis> - if <emphasis> -shape</emphasis> - is <emphasis> -NULL</emphasis> - or if there are no outlines for the shape; otherwise, it returns -<emphasis>True</emphasis>. -</para> - - -<para> -A <emphasis> -ShapeRec</emphasis> - contains a <emphasis> -BoundsRec</emphasis> - that describes the bounds of the shape. If you add or delete an outline to or +<structfield>approx</structfield> +field of +<parameter>shape</parameter> +is not +<symbol>NULL</symbol>. +If +<structfield>approx</structfield> +is +<symbol>NULL</symbol>, +the top surface is defined as the last outline in the +<parameter>shape</parameter>’s +array of outlines. +<function>XkbComputeShapeTop</function> +returns +<symbol>False</symbol> +if +<parameter>shape</parameter> +is +<symbol>NULL</symbol> +or if there are no outlines for the shape; otherwise, it returns +<symbol>True</symbol>. +</para> + + +<para> +A +<structname>ShapeRec</structname> +contains a +<structname>BoundsRec</structname> +that describes the bounds of the shape. If you add or delete an outline to or from a shape, the bounding box must be updated. To update the bounding box of a -shape, use <emphasis>XkbComputeShapeBounds</emphasis>. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbComputeShapeBounds</emphasis> -(<emphasis> -shape</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbShapePtr <emphasis> - shape</emphasis> -; /* shape to be examined */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbComputeShapeBounds</emphasis> - updates the <emphasis> -BoundsRec</emphasis> - contained in the <emphasis> -shape</emphasis> - by examining all the outlines of the shape and setting the <emphasis> -BoundsRec</emphasis> - to the minimum x and minimum y, and maximum x and maximum y values found in -those outlines. <emphasis> -XkbComputeShapeBounds</emphasis> - returns <emphasis> -False</emphasis> - if <emphasis> -shape</emphasis> - is <emphasis> -NULL</emphasis> - or if there are no outlines for the shape; otherwise, it returns <emphasis> -True</emphasis> -. -</para> - -<para> - If you add or delete a key to or from a row, or if you update the shape of one +shape, use <function>XkbComputeShapeBounds</function>. +</para> + + +<indexterm significance="preferred" zone="XkbComputeShapeBounds"><primary><function>XkbComputeShapeBounds</function></primary></indexterm> +<funcsynopsis id="XkbComputeShapeBounds"> + <funcprototype> + <funcdef>Bool <function>XkbComputeShapeBounds</function></funcdef> +<!-- ( +<parameter>shape</parameter> +) --> + + <paramdef>XkbShapePtr <parameter>shape</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>shape</parameter> + </term> + <listitem> + <para> + shape to be examined + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbComputeShapeBounds</function> +updates the +<structname>BoundsRec</structname> +contained in the +<parameter>shape</parameter> +by examining all the outlines of the shape and setting the +<structname>BoundsRec</structname> +to the minimum x and minimum y, and maximum x and maximum y values found in +those outlines. +<function>XkbComputeShapeBounds</function> +returns +<symbol>False</symbol> +if +<parameter>shape</parameter> +is +<symbol>NULL</symbol> +or if there are no outlines for the shape; otherwise, it returns +<symbol>True</symbol>. +</para> + +<para> +If you add or delete a key to or from a row, or if you update the shape of one of the keys in that row, you may need to update the bounding box of that row. -To update the bounding box of a row, use <emphasis>XkbComputeRowBounds</emphasis>. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbComputeRowBounds</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - section</emphasis> -,<emphasis> - row</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry that contains the <emphasis> -section</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbSectionPtr <emphasis> - section</emphasis> -; /* section that contains the row */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbRowPtr <emphasis> -row</emphasis> -; /* row to be examined and updated */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbComputeRowBounds</emphasis> - checks the bounds of all keys in the <emphasis> -row </emphasis> -and updates the bounding box of the row if necessary. <emphasis> -XkbComputeRowBounds</emphasis> - returns <emphasis> -False</emphasis> - if any of the arguments is <emphasis> -NULL</emphasis> -; otherwise, it returns <emphasis> -True</emphasis> -. -</para> - -<para> - If you add or delete a row to or from a section, or if you change the geometry +To update the bounding box of a row, use <function>XkbComputeRowBounds</function>. +</para> + +<indexterm significance="preferred" zone="XkbComputeRowBounds"><primary><function>XkbComputeRowBounds</function></primary></indexterm> +<funcsynopsis id="XkbComputeRowBounds"> + <funcprototype> + <funcdef>Bool <function>XkbComputeRowBounds</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>section</parameter>, +<parameter>row</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>XkbSectionPtr <parameter>section</parameter></paramdef> + <paramdef>XkbRowPtr <parameter>row</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry that contains the <parameter>section</parameter> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>section</parameter> + </term> + <listitem> + <para> + section that contains the row + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>row</parameter> + </term> + <listitem> + <para> + row to be examined and updated + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbComputeRowBounds</function> +checks the bounds of all keys in the +<parameter>row</parameter> +and updates the bounding box of the row if necessary. +<function>XkbComputeRowBounds</function> +returns +<symbol>False</symbol> +if any of the arguments is +<symbol>NULL</symbol>; +otherwise, it returns +<symbol>True</symbol>. +</para> + +<para> +If you add or delete a row to or from a section, or if you change the geometry of any of the rows in that section, you may need to update the bounding box for that section. To update the bounding box of a section, use -<emphasis>XkbComputeSectionBounds</emphasis>. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbComputeSectionBounds</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - section</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry that contains the <emphasis> -section</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbSectionPtr <emphasis> - section</emphasis> -; /* section to be examined and updated */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbComputeSectionBounds</emphasis> - examines all the rows of the <emphasis> -section</emphasis> - and updates the bounding box of that section so that it contains all rows. -<emphasis> -XkbComputeSectionBounds</emphasis> - returns <emphasis> -False</emphasis> - if any of the arguments is <emphasis> -NULL</emphasis> -; otherwise, it returns <emphasis> -True</emphasis> -. +<function>XkbComputeSectionBounds</function>. +</para> + +<indexterm significance="preferred" zone="XkbComputeSectionBounds"><primary><function>XkbComputeSectionBounds</function></primary></indexterm> +<funcsynopsis id="XkbComputeSectionBounds"> + <funcprototype> + <funcdef>Bool <function>XkbComputeSectionBounds</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>section</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>XkbSectionPtr <parameter>section</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry that contains the <parameter>section</parameter> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>section</parameter> + </term> + <listitem> + <para> + section to be examined and updated + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbComputeSectionBounds</function> +examines all the rows of the +<parameter>section</parameter> +and updates the bounding box of that section so that it contains all rows. +<function>XkbComputeSectionBounds</function> +returns +<symbol>False</symbol> +if any of the arguments is +<symbol>NULL</symbol>; +otherwise, it returns +<symbol>True</symbol>. </para> <para> Keys that can generate multiple keycodes may be associated with multiple names. Such keys have a primary name and an alternate name. To find the alternate name -by using the primary name for a key that is part of an overlay, use <emphasis> -XkbFindOverlayForKey</emphasis>. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -char * <emphasis> -XkbFindOverlayForKey</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - section</emphasis> -,<emphasis> - under</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry that contains the <emphasis> -section</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbSectionPtr <emphasis> - section</emphasis> -; /* section to be searched for matching keys */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -char * <emphasis> - under</emphasis> -. /* primary name of the key to be considered */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbFindOverlayForKey</emphasis> - uses the primary name of the key, <emphasis> -under</emphasis> -, to look up the alternate name, which it returns. +by using the primary name for a key that is part of an overlay, use +<function>XkbFindOverlayForKey</function>. +</para> + +<indexterm significance="preferred" zone="XkbFindOverlayForKey"><primary><function>XkbFindOverlayForKey</function></primary></indexterm> +<funcsynopsis id="XkbFindOverlayForKey"> + <funcprototype> + <funcdef>char *<function>XkbFindOverlayForKey</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>section</parameter>, +<parameter>under</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>XkbSectionPtr <parameter>section</parameter></paramdef> + <paramdef>char *<parameter>under</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry that contains the <parameter>section</parameter> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>section</parameter> + </term> + <listitem> + <para> + section to be searched for matching keys + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>under</parameter> + </term> + <listitem> + <para> + .primary name of the key to be considered + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbFindOverlayForKey</function> +uses the primary name of the key, +<parameter>under</parameter>, +to look up the alternate name, which it returns. </para> @@ -1559,25 +1577,21 @@ under</emphasis> <para> Xkb provides functions to add a single new element to the top-level keyboard -geometry. In each case the <emphasis> -num_ </emphasis> -<emphasis> -*</emphasis> - fields of the corresponding structure is incremented by 1. These functions do -not change <emphasis> -sz_</emphasis> -<emphasis> -*</emphasis> - unless there is no more room in the array. Some of these functions fill in the +geometry. In each case the +<structfield>num_<replaceable>*</replaceable></structfield> +fields of the corresponding structure is incremented by 1. These functions do +not change +<structfield>sz_<replaceable>*</replaceable></structfield> +unless there is no more room in the array. Some of these functions fill in the values of the element’s structure from the arguments. For other functions, you must explicitly write code to fill the structure’s elements. </para> <para> -The top-level geometry description includes a list of <emphasis> -geometry properties</emphasis> -. A geometry property associates an arbitrary string with an equally arbitrary +The top-level geometry description includes a list of +<firstterm>geometry properties</firstterm>. +A geometry property associates an arbitrary string with an equally arbitrary name. Programs that display images of keyboards can use geometry properties as hints, but they are not interpreted by Xkb. No other geometry structures refer to geometry properties. @@ -1585,68 +1599,69 @@ to geometry properties. <para> -To add one property to an existing keyboard geometry description, use <emphasis> -XkbAddGeomProperty</emphasis> -. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbPropertyPtr <emphasis> -XkbAddGeomProperty</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - name</emphasis> -,<emphasis> - value</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry to be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -char * <emphasis> - name</emphasis> -; /* name of the new property */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -char * <emphasis> - value</emphasis> -; /* value for the new property */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAddGeomProperty</emphasis> - adds one property with the specified <emphasis> -name</emphasis> - and <emphasis> -value</emphasis> - to the keyboard geometry specified by geom.<emphasis> - </emphasis> -<emphasis> -XkbAddGeomProperty</emphasis> - returns <emphasis> -NULL</emphasis> - if any of the parameters is empty or if it was not able to allocate space for +To add one property to an existing keyboard geometry description, use +<function>XkbAddGeomProperty</function>. +</para> + +<indexterm significance="preferred" zone="XkbAddGeomProperty"><primary><function>XkbAddGeomProperty</function></primary></indexterm> +<funcsynopsis id="XkbAddGeomProperty"> + <funcprototype> + <funcdef>XkbPropertyPtr <function>XkbAddGeomProperty</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>name</parameter>, +<parameter>value</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>char *<parameter>name</parameter></paramdef> + <paramdef>char *<parameter>value</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry to be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>name</parameter> + </term> + <listitem> + <para> + name of the new property + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>value</parameter> + </term> + <listitem> + <para> + value for the new property + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAddGeomProperty</function> +adds one property with the specified +<parameter>name</parameter> +and +<parameter>value</parameter> +to the keyboard geometry specified by geom. +<function>XkbAddGeomProperty</function> +returns +<symbol>NULL</symbol> +if any of the parameters is empty or if it was not able to allocate space for the property. To allocate space for an arbitrary number of properties, use the XkbAllocGeomProps function. </para> @@ -1654,62 +1669,65 @@ XkbAllocGeomProps function. <para> To add one key alias to an existing keyboard geometry description, use -<emphasis> -XkbAddGeomKeyAlias</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbKeyAliasPtr <emphasis> -XkbAddGeomKeyAlias</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - alias, real</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry to be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -char * <emphasis> - alias</emphasis> -; /* alias to be added */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -char * <emphasis> - real</emphasis> -; /* real name to be bound to the new alias */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAddGeomKeyAlias</emphasis> - adds one key alias with the value alias to the geometry geom, and associates -it with the key whose real name is real. <emphasis> -XkbAddGeomKeyAlias</emphasis> - returns <emphasis> -NULL</emphasis> - if any of the parameters is empty or if it was not able to allocate space for +<function>XkbAddGeomKeyAlias</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAddGeomKeyAlias"><primary><function>XkbAddGeomKeyAlias</function></primary></indexterm> +<funcsynopsis id="XkbAddGeomKeyAlias"> + <funcprototype> + <funcdef>XkbKeyAliasPtr <function>XkbAddGeomKeyAlias</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>alias, real</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>char *<parameter>alias</parameter></paramdef> + <paramdef>char *<parameter>real</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry to be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>alias</parameter> + </term> + <listitem> + <para> + alias to be added + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>real</parameter> + </term> + <listitem> + <para> + real name to be bound to the new alias + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAddGeomKeyAlias</function> +adds one key alias with the value alias to the geometry geom, and associates +it with the key whose real name is real. +<function>XkbAddGeomKeyAlias</function> +returns +<symbol>NULL</symbol> +if any of the parameters is empty or if it was not able to allocate space for the alias. To allocate space for an arbitrary number of aliases, use the XkbAllocGeomKeyAliases function. </para> @@ -1717,414 +1735,423 @@ XkbAllocGeomKeyAliases function. <para> To add one color name to an existing keyboard geometry description, use -<emphasis> -XkbAddGeomColor</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbColorPtr <emphasis> -XkbAddGeomColor</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - spec</emphasis> -,<emphasis> - pixel</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry to be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -char * <emphasis> - spec</emphasis> -; /* color to be added */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - pixel</emphasis> -; /* color to be added */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAddGeomColor</emphasis> - adds the specified color <emphasis> -name</emphasis> - and <emphasis> -pixel</emphasis> - to the specified geometry <emphasis> -geom</emphasis> -. The top-level geometry description includes a list of up to <emphasis> -MaxColors</emphasis> - (32) <emphasis> -color names</emphasis> -. A color <emphasis> -name</emphasis> - is a string whose interpretation is not specified by Xkb and neither is the -<emphasis> -pixel</emphasis> - value’s interpretation. All other geometry data structures refer to colors +<function>XkbAddGeomColor</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAddGeomColor"><primary><function>XkbAddGeomColor</function></primary></indexterm> +<funcsynopsis id="XkbAddGeomColor"> + <funcprototype> + <funcdef>XkbColorPtr <function>XkbAddGeomColor</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>spec</parameter>, +<parameter>pixel</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>char *<parameter>spec</parameter></paramdef> + <paramdef>unsigned int <parameter>pixel</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry to be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>spec</parameter> + </term> + <listitem> + <para> + color to be added + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>pixel</parameter> + </term> + <listitem> + <para> + color to be added + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAddGeomColor</function> +adds the specified color +<structfield>name</structfield> +and +<parameter>pixel</parameter> +to the specified geometry +<parameter>geom</parameter>. +The top-level geometry description includes a list of up to +<emphasis>MaxColors</emphasis> +(32) +<emphasis>color names</emphasis>. +A color +<structfield>name</structfield> +is a string whose interpretation is not specified by Xkb and neither is the +<parameter>pixel</parameter> +value’s interpretation. All other geometry data structures refer to colors using their indices in this global list or pointers to colors in this list. -<emphasis> -XkbAddGeomColor</emphasis> - returns <emphasis> -NULL</emphasis> - if any of the parameters is empty or if it was not able to allocate space for +<function>XkbAddGeomColor</function> +returns +<symbol>NULL</symbol> +if any of the parameters is empty or if it was not able to allocate space for the color. To allocate space for an arbitrary number of colors to a geometry, -use the <emphasis> -XkbAllocGeomColors</emphasis> - function. -</para> - -<para> -To add one outline to an existing shape, use <emphasis> -XkbAddGeomOutline</emphasis>. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbOutlinePtr <emphasis> -XkbAddGeomOutline</emphasis> -(<emphasis> -shape</emphasis> -,<emphasis> - sz_points</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbShapePtr <emphasis> - shape</emphasis> -; /* shape to be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - sz_points</emphasis> -; /* number of points to be reserved */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -An outline consists of an arbitrary number of points. <emphasis> -XkbAddGeomOutline</emphasis> - adds an outline to the specified <emphasis> -shape</emphasis> - by reserving <emphasis> -sz_points</emphasis> - points for it. The new outline is allocated and zeroed. <emphasis> -XkbAddGeomOutline</emphasis> - returns <emphasis> -NULL</emphasis> - if any of the parameters is empty or if it was not able to allocate space. To +use the +<function>XkbAllocGeomColors</function> +function. +</para> + +<para> +To add one outline to an existing shape, use +<function>XkbAddGeomOutline</function>. +</para> + +<indexterm significance="preferred" zone="XkbAddGeomOutline"><primary><function>XkbAddGeomOutline</function></primary></indexterm> +<funcsynopsis id="XkbAddGeomOutline"> + <funcprototype> + <funcdef>XkbOutlinePtr <function>XkbAddGeomOutline</function></funcdef> +<!-- ( +<parameter>shape</parameter>, +<parameter>sz_points</parameter> +) --> + + <paramdef>XkbShapePtr <parameter>shape</parameter></paramdef> + <paramdef>int <parameter>sz_points</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>shape</parameter> + </term> + <listitem> + <para> + shape to be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>sz_points</parameter> + </term> + <listitem> + <para> + number of points to be reserved + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +An outline consists of an arbitrary number of points. +<function>XkbAddGeomOutline</function> +adds an outline to the specified +<parameter>shape</parameter> +by reserving +<parameter>sz_points</parameter> +points for it. The new outline is allocated and zeroed. +<function>XkbAddGeomOutline</function> +returns +<symbol>NULL</symbol> +if any of the parameters is empty or if it was not able to allocate space. To allocate space for an arbitrary number of outlines to a shape, use XkbAllocGeomOutlines. </para> <para> -To add a shape to a keyboard geometry, use <emphasis> -XkbAddGeomShape</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbShapePtr <emphasis> -XkbAddGeomShape</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - name</emphasis> -,<emphasis> - sz_outlines</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry to be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Atom <emphasis> - name</emphasis> -; /* name of the new shape */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - sz_outlines</emphasis> -; /* number of outlines to be reserved */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +To add a shape to a keyboard geometry, use +<function>XkbAddGeomShape</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAddGeomShape"><primary><function>XkbAddGeomShape</function></primary></indexterm> +<funcsynopsis id="XkbAddGeomShape"> + <funcprototype> + <funcdef>XkbShapePtr <function>XkbAddGeomShape</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>name</parameter>, +<parameter>sz_outlines</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>Atom <parameter>name</parameter></paramdef> + <paramdef>int <parameter>sz_outlines</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry to be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>name</parameter> + </term> + <listitem> + <para> + name of the new shape + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>sz_outlines</parameter> + </term> + <listitem> + <para> + number of outlines to be reserved + </para> + </listitem> + </varlistentry> +</variablelist> <para> A geometry contains an arbitrary number of shapes, each of which is made up of -an arbitrary number of outlines. <emphasis> -XkbAddGeomShape</emphasis> - adds a shape to a geometry <emphasis> -geom</emphasis> - by allocating space for <emphasis> -sz_outlines</emphasis> - outlines for it and giving it the name specified by name. If a shape with name -<emphasis> -name</emphasis> - already exists in the geometry, a pointer to the existing shape is returned. -<emphasis> -XkbAddGeomShape</emphasis> - returns <emphasis> -NULL</emphasis> - if any of the parameters is empty or if it was not able to allocate space. To -allocate space for an arbitrary number of geometry shapes, use <emphasis> -XkbAllocGeomShapes</emphasis> -. -</para> - - -<para> -To add one key at the end of an existing row of keys, use <emphasis> -XkbAddGeomKey</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbKeyPtr <emphasis> -XkbAddGeomKey</emphasis> -(<emphasis> -row</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbRowPtr <emphasis> - row</emphasis> -; /* row to be updated */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -Keys are grouped into rows. <emphasis> -XkbAddGeomKey</emphasis> - adds one key to the end of the specified <emphasis> -row</emphasis> -. The key is allocated and zeroed. <emphasis> -XkbAddGeomKey</emphasis> - returns <emphasis> -NULL</emphasis> - if <emphasis> -row</emphasis> - is empty or if it was not able to allocate space for the key. To allocate +an arbitrary number of outlines. +<function>XkbAddGeomShape</function> +adds a shape to a geometry +<parameter>geom</parameter> +by allocating space for +<parameter>sz_outlines</parameter> +outlines for it and giving it the name specified by name. If a shape with name +<parameter>name</parameter> +already exists in the geometry, a pointer to the existing shape is returned. +<function>XkbAddGeomShape</function> +returns +<symbol>NULL</symbol> +if any of the parameters is empty or if it was not able to allocate space. To +allocate space for an arbitrary number of geometry shapes, use +<function>XkbAllocGeomShapes</function>. +</para> + + +<para> +To add one key at the end of an existing row of keys, use +<function>XkbAddGeomKey</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAddGeomKey"><primary><function>XkbAddGeomKey</function></primary></indexterm> +<funcsynopsis id="XkbAddGeomKey"> + <funcprototype> + <funcdef>XkbKeyPtr <function>XkbAddGeomKey</function></funcdef> +<!-- ( +<parameter>row</parameter> +) --> + + <paramdef>XkbRowPtr <parameter>row</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>row</parameter> + </term> + <listitem> + <para> + row to be updated + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +Keys are grouped into rows. +<function>XkbAddGeomKey</function> +adds one key to the end of the specified +<parameter>row</parameter>. +The key is allocated and zeroed. +<function>XkbAddGeomKey</function> +returns +<symbol>NULL</symbol> +if +<parameter>row</parameter> +is empty or if it was not able to allocate space for the key. To allocate space for an arbitrary number of keys to a row, use XkbAllocGeomKeys. </para> <para> -To add one section to an existing keyboard geometry, use <emphasis> -XkbAddGeomSection</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbSectionPtr <emphasis> -XkbAddGeomSection</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - name</emphasis> -,<emphasis> - sz_rows</emphasis> -,<emphasis> - sz_doodads</emphasis> -,<emphasis> - sz_overlays</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry to be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Atom <emphasis> - name</emphasis> -; /* name of the new section */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - sz_rows</emphasis> -; /* number of rows to reserve in the section */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - sz_doodads</emphasis> -; /* number of doodads to reserve in the section */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - sz_overlays</emphasis> -; /* number of overlays to reserve in the section */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -A keyboard geometry contains an arbitrary number of sections. <emphasis> -XkbAddGeomSection</emphasis> - adds one section to an existing keyboard geometry <emphasis> -geom</emphasis> -. The new section contains space for the number of rows, doodads, and overlays -specified by <emphasis> -sz_rows</emphasis> -, <emphasis> -sz_doodads</emphasis> -, and <emphasis> -sz_overlays</emphasis> -. The new section is allocated and zeroed and given the name specified by -<emphasis> -name</emphasis> -. If a section with name <emphasis> -name</emphasis> - already exists in the geometry, a pointer to the existing section is -returned.<emphasis> - XkbAddGeomSection</emphasis> - returns <emphasis> -NULL</emphasis> - if any of the parameters is empty or if it was not able to allocate space for +To add one section to an existing keyboard geometry, use +<function>XkbAddGeomSection</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAddGeomSection"><primary><function>XkbAddGeomSection</function></primary></indexterm> +<funcsynopsis id="XkbAddGeomSection"> + <funcprototype> + <funcdef>XkbSectionPtr <function>XkbAddGeomSection</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>name</parameter>, +<parameter>sz_rows</parameter>, +<parameter>sz_doodads</parameter>, +<parameter>sz_overlays</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>Atom <parameter>name</parameter></paramdef> + <paramdef>int <parameter>sz_rows</parameter></paramdef> + <paramdef>int <parameter>sz_doodads</parameter></paramdef> + <paramdef>int <parameter>sz_overlays</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry to be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>name</parameter> + </term> + <listitem> + <para> + name of the new section + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>sz_rows</parameter> + </term> + <listitem> + <para> + number of rows to reserve in the section + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>sz_doodads</parameter> + </term> + <listitem> + <para> + number of doodads to reserve in the section + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>sz_overlays</parameter> + </term> + <listitem> + <para> + number of overlays to reserve in the section + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +A keyboard geometry contains an arbitrary number of sections. +<function>XkbAddGeomSection</function> +adds one section to an existing keyboard geometry +<parameter>geom</parameter>. +The new section contains space for the number of rows, doodads, and overlays +specified by +<parameter>sz_rows</parameter>, +<parameter>sz_doodads</parameter>, +and +<parameter>sz_overlays</parameter>. +The new section is allocated and zeroed and given the name specified by +<parameter>name</parameter>. +If a section with name +<parameter>name</parameter> +already exists in the geometry, a pointer to the existing section is +returned. +<function>XkbAddGeomSection</function> +returns +<symbol>NULL</symbol> +if any of the parameters is empty or if it was not able to allocate space for the section. To allocate space for an arbitrary number of sections to a geometry, use XkbAllocGeomSections. </para> <para> -To add a row to a section, use <emphasis> -XkbAddGeomRow</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbRowPtr <emphasis> -XkbAddGeomRow</emphasis> -(<emphasis> -section</emphasis> -,<emphasis> - sz_keys</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbSectionPtr <emphasis> - section</emphasis> -; /* section to be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -sz_keys</emphasis> -; /* number of keys to be reserved */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +To add a row to a section, use +<function>XkbAddGeomRow</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAddGeomRow"><primary><function>XkbAddGeomRow</function></primary></indexterm> +<funcsynopsis id="XkbAddGeomRow"> + <funcprototype> + <funcdef>XkbRowPtr <function>XkbAddGeomRow</function></funcdef> +<!-- ( +<parameter>section</parameter>, +<parameter>sz_keys</parameter> +) --> + + <paramdef>XkbSectionPtr <parameter>section</parameter></paramdef> + <paramdef>int <parameter>sz_keys</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>section</parameter> + </term> + <listitem> + <para> + section to be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>sz_keys</parameter> + </term> + <listitem> + <para> + number of keys to be reserved + </para> + </listitem> + </varlistentry> +</variablelist> <para> One of the components of a keyboard geometry section is one or more rows of -keys. <emphasis> -XkbAddGeomRow</emphasis> - adds one row to the specified <emphasis> -section</emphasis> -. The newly created row contains space for the number of keys specified in -<emphasis> -sz_keys</emphasis> -. They are allocated and zeroed, but otherwise uninitialized. <emphasis> -XkbAddGeomRow</emphasis> - returns <emphasis> -NULL</emphasis> - if any of the parameters is empty or if it was not able to allocate space for +keys. +<function>XkbAddGeomRow</function> +adds one row to the specified +<parameter>section</parameter>. +The newly created row contains space for the number of keys specified in +<parameter>sz_keys</parameter>. +They are allocated and zeroed, but otherwise uninitialized. +<function>XkbAddGeomRow</function> +returns +<symbol>NULL</symbol> +if any of the parameters is empty or if it was not able to allocate space for the row. To allocate space for an arbitrary number of rows to a section, use the XkbAllocGeomRows function. </para> @@ -2132,85 +2159,88 @@ the XkbAllocGeomRows function. <para> To add one doodad to a section of a keyboard geometry or to the top-level -geometry, use <emphasis> -XkbAddGeomDoodad</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbDoodadPtr <emphasis> -XkbAddGeomDoodad</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - section</emphasis> -,<emphasis> - name</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry to which the doodad is added */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbSectionPtr <emphasis> - section</emphasis> -; /* section, if any, to which the doodad is added */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Atom <emphasis> - name</emphasis> -; /* name of the new doodad */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -A <emphasis> -doodad</emphasis> - describes some visible aspect of the keyboard that is not a key and is not a -section. <emphasis> -XkbAddGeomDoodad</emphasis> - adds a doodad with name specified by name to the geometry <emphasis> -geom</emphasis> - if section is <emphasis> -NULL</emphasis> - or to the section of the geometry specified by section if <emphasis> -section</emphasis> - is not <emphasis> -NULL</emphasis> -. <emphasis> -XkbAddGeomDoodad</emphasis> - returns <emphasis> -NULL</emphasis> - if any of the parameters is empty or if it was not able to allocate space for -the doodad. If there is already a doodad with the name <emphasis> -name</emphasis> - in the doodad array for the geometry (if <emphasis> -section</emphasis> - is <emphasis> -NULL</emphasis> -) or the section (if <emphasis> -section</emphasis> - is non-<emphasis> -NULL</emphasis> -), a pointer to that doodad is returned. To allocate space for an arbitrary +geometry, use +<function>XkbAddGeomDoodad</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAddGeomDoodad"><primary><function>XkbAddGeomDoodad</function></primary></indexterm> +<funcsynopsis id="XkbAddGeomDoodad"> + <funcprototype> + <funcdef>XkbDoodadPtr <function>XkbAddGeomDoodad</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>section</parameter>, +<parameter>name</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>XkbSectionPtr <parameter>section</parameter></paramdef> + <paramdef>Atom <parameter>name</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry to which the doodad is added + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>section</parameter> + </term> + <listitem> + <para> + section, if any, to which the doodad is added + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>name</parameter> + </term> + <listitem> + <para> + name of the new doodad + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +A +<structfield>doodad</structfield> +describes some visible aspect of the keyboard that is not a key and is not a +section. +<function>XkbAddGeomDoodad</function> +adds a doodad with name specified by name to the geometry +<parameter>geom</parameter> +if section is +<symbol>NULL</symbol> +or to the section of the geometry specified by section if +<parameter>section</parameter> +is not +<symbol>NULL</symbol>. +<function>XkbAddGeomDoodad</function> +returns +<symbol>NULL</symbol> +if any of the parameters is empty or if it was not able to allocate space for +the doodad. If there is already a doodad with the name +<parameter>name</parameter> +in the doodad array for the geometry (if +<parameter>section</parameter> +is +<symbol>NULL</symbol>) +or the section (if +<parameter>section</parameter> +is non- +<symbol>NULL</symbol>), +a pointer to that doodad is returned. To allocate space for an arbitrary number of doodads to a section, use the XkbAllocGeomSectionDoodads function. To allocate space for an arbitrary number of doodads to a keyboard geometry, use the XkbAllocGeomDoodads function. @@ -2218,208 +2248,217 @@ the XkbAllocGeomDoodads function. <para> -To add one overlay to a section, use <emphasis> -XkbAddGeomOverlay</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbOverlayPtr <emphasis> -XkbAddGeomOverlay</emphasis> -(<emphasis> -section</emphasis> -,<emphasis> - name</emphasis> -,<emphasis> - sz_rows</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbSectionPtr <emphasis> - section</emphasis> -; /* section to which an overlay will be added */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Atom <emphasis> - name</emphasis> -; /* name of the overlay */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - sz_rows</emphasis> -; /* number of rows to reserve in the overlay */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAddGeomOverlay</emphasis> - adds an overlay with the specified name to the specified <emphasis> -section</emphasis> -. The new overlay is created with space allocated for sz_rows rows. If an -overlay with name <emphasis> -name</emphasis> - already exists in the section, a pointer to the existing overlay is -returned.<emphasis> - XkbAddGeomOverlay</emphasis> - returns <emphasis> -NULL</emphasis> - if any of the parameters is empty or if it was not able to allocate space for +To add one overlay to a section, use +<function>XkbAddGeomOverlay</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAddGeomOverlay"><primary><function>XkbAddGeomOverlay</function></primary></indexterm> +<funcsynopsis id="XkbAddGeomOverlay"> + <funcprototype> + <funcdef>XkbOverlayPtr <function>XkbAddGeomOverlay</function></funcdef> +<!-- ( +<parameter>section</parameter>, +<parameter>name</parameter>, +<parameter>sz_rows</parameter> +) --> + + <paramdef>XkbSectionPtr <parameter>section</parameter></paramdef> + <paramdef>Atom <parameter>name</parameter></paramdef> + <paramdef>int <parameter>sz_rows</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>section</parameter> + </term> + <listitem> + <para> + section to which an overlay will be added + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>name</parameter> + </term> + <listitem> + <para> + name of the overlay + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>sz_rows</parameter> + </term> + <listitem> + <para> + number of rows to reserve in the overlay + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAddGeomOverlay</function> +adds an overlay with the specified name to the specified +<parameter>section</parameter>. +The new overlay is created with space allocated for sz_rows rows. If an +overlay with name +<parameter>name</parameter> +already exists in the section, a pointer to the existing overlay is +returned. +<function>XkbAddGeomOverlay</function> +returns +<symbol>NULL</symbol> +if any of the parameters is empty or if it was not able to allocate space for the overlay. To allocate space for an arbitrary number of overlays to a section, use the XkbAllocGeomOverlay function. </para> <para> -To add a row to an existing overlay, use <emphasis> -XkbAddGeomOverlayRow</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbOverlayRowPtr <emphasis> -XkbAddGeomOverlayRow</emphasis> -(<emphasis> -overlay</emphasis> -,<emphasis> - row_under, sz_keys</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbOverlayPtr <emphasis> - overlay</emphasis> -; /* overlay to be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbRowPtr <emphasis> - row_under</emphasis> -; /* row to be overlayed in the section <emphasis> -overlay</emphasis> - overlays */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - sz_keys</emphasis> -; /* number of keys to reserve in the row */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAddGeomOverlayRow</emphasis> - adds one row to the <emphasis> -overlay</emphasis> -. The new row contains space for <emphasis> -sz_keys</emphasis> - keys. If <emphasis> -row_under</emphasis> - specifies a row that doesn’t exist on the underlying section, <emphasis> -XkbAddGeomOverlayRow</emphasis> - returns <emphasis> -NULL</emphasis> - and doesn’t change the overlay.<emphasis> - XkbAddGeomOverlayRow</emphasis> - returns <emphasis> -NULL</emphasis> - if any of the parameters is empty or if it was not able to allocate space for +To add a row to an existing overlay, use +<function>XkbAddGeomOverlayRow</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAddGeomOverlayRow"><primary><function>XkbAddGeomOverlayRow</function></primary></indexterm> +<funcsynopsis id="XkbAddGeomOverlayRow"> + <funcprototype> + <funcdef>XkbOverlayRowPtr <function>XkbAddGeomOverlayRow</function></funcdef> +<!-- ( +<parameter>overlay</parameter>, +<parameter>row_under, sz_keys</parameter> +) --> + + <paramdef>XkbOverlayPtr <parameter>overlay</parameter></paramdef> + <paramdef>XkbRowPtr <parameter>row_under</parameter></paramdef> + <paramdef>int <parameter>sz_keys</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>overlay</parameter> + </term> + <listitem> + <para> + overlay to be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>row_under</parameter> + </term> + <listitem> + <para> + row to be overlayed in the section <parameter>overlay</parameter> + overlays + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>sz_keys</parameter> + </term> + <listitem> + <para> + number of keys to reserve in the row + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAddGeomOverlayRow</function> +adds one row to the +<parameter>overlay</parameter>. +The new row contains space for +<parameter>sz_keys</parameter> +keys. If +<parameter>row_under</parameter> +specifies a row that doesn’t exist on the underlying section, +<function>XkbAddGeomOverlayRow</function> +returns +<symbol>NULL</symbol> +and doesn’t change the overlay. +<function>XkbAddGeomOverlayRow</function> +returns +<symbol>NULL</symbol> +if any of the parameters is empty or if it was not able to allocate space for the overlay. </para> <para> -To add a key to an existing overlay row, use <emphasis> -XkbAddGeomOverlayKey</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbOverlayKeyPtr <emphasis> -XkbAddGeomOverlayKey</emphasis> -(<emphasis> -overlay</emphasis> -,<emphasis> - row, under</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbOverlayPtr <emphasis> - overlay</emphasis> -; /* overlay to be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbRowPtr <emphasis> - row</emphasis> -; /* row in overlay to be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -char * <emphasis> - under</emphasis> -; /* primary name of the key to be considered */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAddGeomOverlayKey</emphasis> - adds one key to the <emphasis> -row</emphasis> - in the <emphasis> -overlay</emphasis> -. If there is no key named <emphasis> -under</emphasis> - in the row of the underlying section, <emphasis> -XkbAddGeomOverlayKey</emphasis> - returns <emphasis> -NULL</emphasis> -. +To add a key to an existing overlay row, use +<function>XkbAddGeomOverlayKey</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAddGeomOverlayKey"><primary><function>XkbAddGeomOverlayKey</function></primary></indexterm> +<funcsynopsis id="XkbAddGeomOverlayKey"> + <funcprototype> + <funcdef>XkbOverlayKeyPtr <function>XkbAddGeomOverlayKey</function></funcdef> +<!-- ( +<parameter>overlay</parameter>, +<parameter>row, under</parameter> +) --> + + <paramdef>XkbOverlayPtr <parameter>overlay</parameter></paramdef> + <paramdef>XkbRowPtr <parameter>row</parameter></paramdef> + <paramdef>char *<parameter>under</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>overlay</parameter> + </term> + <listitem> + <para> + overlay to be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>row</parameter> + </term> + <listitem> + <para> + row in overlay to be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>under</parameter> + </term> + <listitem> + <para> + primary name of the key to be considered + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAddGeomOverlayKey</function> +adds one key to the +<parameter>row</parameter> +in the +<parameter>overlay</parameter>. +If there is no key named +<parameter>under</parameter> +in the row of the underlying section, +<function>XkbAddGeomOverlayKey</function> +returns +<symbol>NULL</symbol>. </para> @@ -2432,30 +2471,21 @@ Xkb provides a number of functions to allocate and free subcomponents of a keyboard geometry. Use these functions to create or modify keyboard geometries. Note that these functions merely allocate space for the new element(s), and it is up to you to fill in the values explicitly in your code. These allocation -functions increase <emphasis> -sz_</emphasis> -<emphasis> -*</emphasis> - but never touch <emphasis> -num_</emphasis> -<emphasis> -*</emphasis> - (unless there is an allocation failure, in which case they reset both -<emphasis> -sz_</emphasis> -<emphasis> -*</emphasis> - and <emphasis> -num_</emphasis> -<emphasis> -*</emphasis> - to zero). These functions return <emphasis> -Success</emphasis> - if they succeed, <emphasis> -BadAlloc</emphasis> - if they are not able to allocate space, or <emphasis> -BadValue</emphasis> - if a parameter is not as expected. +functions increase +<structfield>sz_<replaceable>*</replaceable></structfield> +but never touch +<structfield>num_<replaceable>*</replaceable></structfield> +(unless there is an allocation failure, in which case they reset both +<structfield>sz_<replaceable>*</replaceable></structfield> +and +<structfield>num_<replaceable>*</replaceable></structfield> +to zero). These functions return +<symbol>Success</symbol> +if they succeed, +<errorname>BadAlloc</errorname> +if they are not able to allocate space, or +<errorname>BadValue</errorname> +if a parameter is not as expected. </para> @@ -2464,116 +2494,122 @@ To allocate space for an arbitrary number of outlines to a shape, use XkbAllocGeomOutlines. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocGeomOutlines</emphasis> -(<emphasis> -shape</emphasis> -,<emphasis> - num_needed</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbShapePtr <emphasis> -shape</emphasis> -; /* shape for which outlines should be allocated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - num_needed</emphasis> -; /* number of new outlines required */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocGeomOutlines</emphasis> - allocates space for <emphasis> -num_needed</emphasis> - outlines in the specified <emphasis> -shape</emphasis> -. The outlines are not initialized. -</para> - - -<para> -To free geometry outlines, use <emphasis> -XkbFreeGeomOutlines</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeGeomOutlines</emphasis> -(<emphasis> -shape</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - count</emphasis> -,<emphasis> - free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbShapePtr <emphasis> - shape</emphasis> -; /* shape in which outlines should be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - first</emphasis> -; /* first outline to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - count</emphasis> -; /* number of outlines to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all;</emphasis> - /* <emphasis> -True</emphasis> - => all outlines are freed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -If free_all is <emphasis> -True</emphasis> -, all outlines are freed regardless of the value of first or count. Otherwise, +<indexterm significance="preferred" zone="XkbAllocGeomOutlines"><primary><function>XkbAllocGeomOutlines</function></primary></indexterm> +<funcsynopsis id="XkbAllocGeomOutlines"> + <funcprototype> + <funcdef>Status <function>XkbAllocGeomOutlines</function></funcdef> +<!-- ( +<parameter>shape</parameter>, +<parameter>num_needed</parameter> +) --> + + <paramdef>XkbShapePtr <parameter>shape</parameter></paramdef> + <paramdef>int <parameter>num_needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>shape</parameter> + </term> + <listitem> + <para> + shape for which outlines should be allocated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_needed</parameter> + </term> + <listitem> + <para> + number of new outlines required + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocGeomOutlines</function> +allocates space for +<parameter>num_needed</parameter> +outlines in the specified +<parameter>shape</parameter>. +The outlines are not initialized. +</para> + + +<para> +To free geometry outlines, use +<function>XkbFreeGeomOutlines</function>. +</para> + + +<indexterm significance="preferred" zone="XkbFreeGeomOutlines"><primary><function>XkbFreeGeomOutlines</function></primary></indexterm> +<funcsynopsis id="XkbFreeGeomOutlines"> + <funcprototype> + <funcdef>void <function>XkbFreeGeomOutlines</function></funcdef> +<!-- ( +<parameter>shape</parameter>, +<parameter>first</parameter>, +<parameter>count</parameter>, +<parameter>free_all</parameter> +) --> + + <paramdef>XkbShapePtr <parameter>shape</parameter></paramdef> + <paramdef>int <parameter>first</parameter></paramdef> + <paramdef>int <parameter>count</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>shape</parameter> + </term> + <listitem> + <para> + shape in which outlines should be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + first outline to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>count</parameter> + </term> + <listitem> + <para> + number of outlines to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ all outlines are freed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If free_all is +<symbol>True</symbol>, +all outlines are freed regardless of the value of first or count. Otherwise, count outlines are freed beginning with the one specified by first. </para> @@ -2584,165 +2620,171 @@ XkbAllocGeomKeys. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocGeomKeys</emphasis> -(<emphasis> -row</emphasis> -,<emphasis> - num_needed</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbRowPtr <emphasis> - row</emphasis> -; /* row to which keys should be allocated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - num_needed</emphasis> -; /* number of new keys required */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocGeomKeys</emphasis> - allocates num_needed keys and adds them to the row. No initialization of the +<indexterm significance="preferred" zone="XkbAllocGeomKeys"><primary><function>XkbAllocGeomKeys</function></primary></indexterm> +<funcsynopsis id="XkbAllocGeomKeys"> + <funcprototype> + <funcdef>Status <function>XkbAllocGeomKeys</function></funcdef> +<!-- ( +<parameter>row</parameter>, +<parameter>num_needed</parameter> +) --> + + <paramdef>XkbRowPtr <parameter>row</parameter></paramdef> + <paramdef>int <parameter>num_needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>row</parameter> + </term> + <listitem> + <para> + row to which keys should be allocated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_needed</parameter> + </term> + <listitem> + <para> + number of new keys required + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocGeomKeys</function> +allocates num_needed keys and adds them to the row. No initialization of the keys is done. </para> <para> -To free geometry keys, use <emphasis> -XkbFreeGeomKeys</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeGeomKeys</emphasis> -(<emphasis> -row</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - count</emphasis> -,<emphasis> - free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbRowPtr <emphasis> - row</emphasis> -; /* row in which keys should be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - first</emphasis> -; /* first key to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - count</emphasis> -; /* number of keys to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all;</emphasis> - /* <emphasis> -True</emphasis> - => all keys are freed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -If free_all is <emphasis> -True</emphasis> -, all keys are freed regardless of the value of first or count. Otherwise, +To free geometry keys, use +<function>XkbFreeGeomKeys</function>. +</para> + + +<indexterm significance="preferred" zone="XkbFreeGeomKeys"><primary><function>XkbFreeGeomKeys</function></primary></indexterm> +<funcsynopsis id="XkbFreeGeomKeys"> + <funcprototype> + <funcdef>void <function>XkbFreeGeomKeys</function></funcdef> +<!-- ( +<parameter>row</parameter>, +<parameter>first</parameter>, +<parameter>count</parameter>, +<parameter>free_all</parameter> +) --> + + <paramdef>XkbRowPtr <parameter>row</parameter></paramdef> + <paramdef>int <parameter>first</parameter></paramdef> + <paramdef>int <parameter>count</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>row</parameter> + </term> + <listitem> + <para> + row in which keys should be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + first key to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>count</parameter> + </term> + <listitem> + <para> + number of keys to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ all keys are freed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If free_all is +<symbol>True</symbol>, +all keys are freed regardless of the value of first or count. Otherwise, count keys are freed beginning with the one specified by first. </para> <para> -To allocate geometry properties, use <emphasis> -XkbAllocGeomProps</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocGeomProps</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - num_needed</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry for which properties should be allocated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - num_needed</emphasis> -; /* number of new properties required */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocGeomProps</emphasis> - allocates space for num_needed properties and adds them to the specified -geometry <emphasis> -geom</emphasis> -. No initialization of the properties is done. A geometry property associates +To allocate geometry properties, use +<function>XkbAllocGeomProps</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAllocGeomProps"><primary><function>XkbAllocGeomProps</function></primary></indexterm> +<funcsynopsis id="XkbAllocGeomProps"> + <funcprototype> + <funcdef>Status <function>XkbAllocGeomProps</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>num_needed</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>int <parameter>num_needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry for which properties should be allocated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_needed</parameter> + </term> + <listitem> + <para> + number of new properties required + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocGeomProps</function> +allocates space for num_needed properties and adds them to the specified +geometry +<parameter>geom</parameter>. +No initialization of the properties is done. A geometry property associates an arbitrary string with an equally arbitrary name. Geometry properties can be used to provide hints to programs that display images of keyboards, but they are not interpreted by Xkb. No other geometry structures refer to geometry @@ -2751,1367 +2793,1418 @@ properties. <para> -To free geometry properties, use <emphasis> -XkbFreeGeomProperties</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeGeomProperties</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - count</emphasis> -,<emphasis> - free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry in which properties should be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - first</emphasis> -; /* first property to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - count</emphasis> -; /* number of properties to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all;</emphasis> - /* <emphasis> -True</emphasis> - => all properties are freed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -If free_all is <emphasis> -True</emphasis> -, all properties are freed regardless of the value of first or count. +To free geometry properties, use +<function>XkbFreeGeomProperties</function>. +</para> + + +<indexterm significance="preferred" zone="XkbFreeGeomProperties"><primary><function>XkbFreeGeomProperties</function></primary></indexterm> +<funcsynopsis id="XkbFreeGeomProperties"> + <funcprototype> + <funcdef>void <function>XkbFreeGeomProperties</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>first</parameter>, +<parameter>count</parameter>, +<parameter>free_all</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>int <parameter>first</parameter></paramdef> + <paramdef>int <parameter>count</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry in which properties should be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + first property to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>count</parameter> + </term> + <listitem> + <para> + number of properties to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ all properties are freed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If free_all is +<symbol>True</symbol>, +all properties are freed regardless of the value of first or count. Otherwise, count properties are freed beginning with the one specified by first. </para> <para> -To allocate geometry key aliases, use <emphasis> -XkbAllocGeomKeyAliases</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocGeomKeyAliases</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - num_needed</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry for which key aliases should be allocated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - num_needed</emphasis> -; /* number of new key aliases required */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocGeomKeyAliases</emphasis> - allocates space for num_needed key aliases and adds them to the specified -geometry <emphasis> -geom</emphasis> -. A key alias is a pair of strings that associates an alternate name for a key +To allocate geometry key aliases, use +<function>XkbAllocGeomKeyAliases</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAllocGeomKeyAliases"><primary><function>XkbAllocGeomKeyAliases</function></primary></indexterm> +<funcsynopsis id="XkbAllocGeomKeyAliases"> + <funcprototype> + <funcdef>Status <function>XkbAllocGeomKeyAliases</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>num_needed</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>int <parameter>num_needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry for which key aliases should be allocated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_needed</parameter> + </term> + <listitem> + <para> + number of new key aliases required + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocGeomKeyAliases</function> +allocates space for num_needed key aliases and adds them to the specified +geometry +<parameter>geom</parameter>. +A key alias is a pair of strings that associates an alternate name for a key with the real name for that key. </para> <para> -To free geometry key aliases, use <emphasis> -XkbFreeGeomKeyAliases</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeGeomKeyAliases</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - first</emphasis> -, <emphasis> -count</emphasis> -, <emphasis> -free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry in which key aliases should be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - first</emphasis> -; /* first key alias to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - count</emphasis> -; /* number of key aliases to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all;</emphasis> - /* <emphasis> -True</emphasis> - => all key aliases are freed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -If free_all is <emphasis> -True</emphasis> -, all aliases in the top level of the specified geometry <emphasis> -geom</emphasis> - are freed regardless of the value of first or count. Otherwise, count aliases -in <emphasis> -geom</emphasis> - are freed beginning with the one specified by first. -</para> - - -<para> -To allocate geometry colors, use <emphasis> -XkbAllocGeomColors</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocGeomColors</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - num_needed</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry for which colors should be allocated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - num_needed</emphasis> -; /* number of new colors required. */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocGeomColors</emphasis> - allocates space for num_needed colors and adds them to the specified geometry -<emphasis> -geom</emphasis> -. A color name is a string whose interpretation is not specified by Xkb. All +To free geometry key aliases, use +<function>XkbFreeGeomKeyAliases</function>. +</para> + + +<indexterm significance="preferred" zone="XkbFreeGeomKeyAliases"><primary><function>XkbFreeGeomKeyAliases</function></primary></indexterm> +<funcsynopsis id="XkbFreeGeomKeyAliases"> + <funcprototype> + <funcdef>void <function>XkbFreeGeomKeyAliases</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>first</parameter>, +<parameter>count</parameter>, +<parameter>free_all</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>int <parameter>first</parameter></paramdef> + <paramdef>int <parameter>count</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry in which key aliases should be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + first key alias to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>count</parameter> + </term> + <listitem> + <para> + number of key aliases to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ all key aliases are freed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If free_all is +<symbol>True</symbol>, +all aliases in the top level of the specified geometry +<parameter>geom</parameter> +are freed regardless of the value of first or count. Otherwise, count aliases +in +<parameter>geom</parameter> +are freed beginning with the one specified by first. +</para> + + +<para> +To allocate geometry colors, use +<function>XkbAllocGeomColors</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAllocGeomColors"><primary><function>XkbAllocGeomColors</function></primary></indexterm> +<funcsynopsis id="XkbAllocGeomColors"> + <funcprototype> + <funcdef>Status <function>XkbAllocGeomColors</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>num_needed</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>int <parameter>num_needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry for which colors should be allocated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_needed</parameter> + </term> + <listitem> + <para> + number of new colors required. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocGeomColors</function> +allocates space for num_needed colors and adds them to the specified geometry +<parameter>geom</parameter>. +A color name is a string whose interpretation is not specified by Xkb. All other geometry data structures refer to colors using their indices in this global list or pointers to colors in this list. </para> <para> -To free geometry colors, use <emphasis> -XkbFreeGeomColors</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeGeomColors</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - count</emphasis> -,<emphasis> - free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry in which colors should be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - first</emphasis> -; /* first color to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - count</emphasis> -; /* number of colors to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all;</emphasis> - /* <emphasis> -True</emphasis> - => all colors are freed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -If free_all is <emphasis> -True</emphasis> -, all colors are freed regardless of the value of first or count. Otherwise, +To free geometry colors, use +<function>XkbFreeGeomColors</function>. +</para> + + +<indexterm significance="preferred" zone="XkbFreeGeomColors"><primary><function>XkbFreeGeomColors</function></primary></indexterm> +<funcsynopsis id="XkbFreeGeomColors"> + <funcprototype> + <funcdef>void <function>XkbFreeGeomColors</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>first</parameter>, +<parameter>count</parameter>, +<parameter>free_all</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>int <parameter>first</parameter></paramdef> + <paramdef>int <parameter>count</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry in which colors should be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + first color to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>count</parameter> + </term> + <listitem> + <para> + number of colors to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ all colors are freed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If free_all is +<symbol>True</symbol>, +all colors are freed regardless of the value of first or count. Otherwise, count colors are freed beginning with the one specified by first. </para> <para> -To allocate points in an outline, use <emphasis> -XkbAllocGeomPoints</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocGeomPoints</emphasis> -(<emphasis> -outline</emphasis> -,<emphasis> - num_needed</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbOutlinePtr <emphasis> - outline</emphasis> -; /* outline for which points should be allocated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - num_needed</emphasis> -; /* number of new points required */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocGeomPoints</emphasis> - allocates space for <emphasis> -num_needed</emphasis> - points in the specified <emphasis> -outline</emphasis> -. The points are not initialized. -</para> - - -<para> -To free points in a outline, use <emphasis> -XkbFreeGeomPoints</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeGeomPoints</emphasis> -(<emphasis> -outline</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - count</emphasis> -,<emphasis> - free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbOutlinePtr <emphasis> - outline</emphasis> -; /* outline in which points should be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - first</emphasis> -; /* first point to be freed. */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - count</emphasis> -; /* number of points to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all;</emphasis> - /* <emphasis> -True</emphasis> - => all points are freed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -If free_all is <emphasis> -True</emphasis> -, all points are freed regardless of the value of first and count. Otherwise, +To allocate points in an outline, use +<function>XkbAllocGeomPoints</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAllocGeomPoints"><primary><function>XkbAllocGeomPoints</function></primary></indexterm> +<funcsynopsis id="XkbAllocGeomPoints"> + <funcprototype> + <funcdef>Status <function>XkbAllocGeomPoints</function></funcdef> +<!-- ( +<parameter>outline</parameter>, +<parameter>num_needed</parameter> +) --> + + <paramdef>XkbOutlinePtr <parameter>outline</parameter></paramdef> + <paramdef>int <parameter>num_needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>outline</parameter> + </term> + <listitem> + <para> + outline for which points should be allocated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_needed</parameter> + </term> + <listitem> + <para> + number of new points required + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocGeomPoints</function> +allocates space for +<parameter>num_needed</parameter> +points in the specified +<parameter>outline</parameter>. +The points are not initialized. +</para> + + +<para> +To free points in a outline, use +<function>XkbFreeGeomPoints</function>. +</para> + + +<indexterm significance="preferred" zone="XkbFreeGeomPoints"><primary><function>XkbFreeGeomPoints</function></primary></indexterm> +<funcsynopsis id="XkbFreeGeomPoints"> + <funcprototype> + <funcdef>void <function>XkbFreeGeomPoints</function></funcdef> +<!-- ( +<parameter>outline</parameter>, +<parameter>first</parameter>, +<parameter>count</parameter>, +<parameter>free_all</parameter> +) --> + + <paramdef>XkbOutlinePtr <parameter>outline</parameter></paramdef> + <paramdef>int <parameter>first</parameter></paramdef> + <paramdef>int <parameter>count</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>outline</parameter> + </term> + <listitem> + <para> + outline in which points should be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + first point to be freed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>count</parameter> + </term> + <listitem> + <para> + number of points to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ all points are freed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If free_all is +<symbol>True</symbol>, +all points are freed regardless of the value of first and count. Otherwise, the number of points specified by count are freed, beginning with the point specified by first in the specified outline. </para> <para> -To allocate space for an arbitrary number of geometry shapes, use <emphasis> -XkbAllocGeomShapes</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocGeomShapes</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - num_needed</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry for which shapes should be allocated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - num_needed</emphasis> -; /* number of new shapes required */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocGeomShapes</emphasis> - allocates space for <emphasis> -num_needed</emphasis> - shapes in the specified geometry <emphasis> -geom</emphasis> -. The shapes are not initialized. -</para> - - -<para> -To free geometry shapes, use <emphasis> -XkbFreeGeomShapes</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeGeomShapes</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - count</emphasis> -,<emphasis> - f ree_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry in which shapes should be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - first</emphasis> -; /* first shape to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - count</emphasis> -; /* number of shapes to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all;</emphasis> - /* <emphasis> -True</emphasis> - => all shapes are freed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -If free_all is <emphasis> -True</emphasis> -, all shapes in the geometry are freed regardless of the values of first and +To allocate space for an arbitrary number of geometry shapes, use +<function>XkbAllocGeomShapes</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAllocGeomShapes"><primary><function>XkbAllocGeomShapes</function></primary></indexterm> +<funcsynopsis id="XkbAllocGeomShapes"> + <funcprototype> + <funcdef>Status <function>XkbAllocGeomShapes</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>num_needed</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>int <parameter>num_needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry for which shapes should be allocated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_needed</parameter> + </term> + <listitem> + <para> + number of new shapes required + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocGeomShapes</function> +allocates space for +<parameter>num_needed</parameter> +shapes in the specified geometry +<parameter>geom</parameter>. +The shapes are not initialized. +</para> + + +<para> +To free geometry shapes, use +<function>XkbFreeGeomShapes</function>. +</para> + + +<indexterm significance="preferred" zone="XkbFreeGeomShapes"><primary><function>XkbFreeGeomShapes</function></primary></indexterm> +<funcsynopsis id="XkbFreeGeomShapes"> + <funcprototype> + <funcdef>void <function>XkbFreeGeomShapes</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>first</parameter>, +<parameter>count</parameter>, +<parameter>free_all</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>int <parameter>first</parameter></paramdef> + <paramdef>int <parameter>count</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry in which shapes should be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + first shape to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>count</parameter> + </term> + <listitem> + <para> + number of shapes to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ all shapes are freed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If free_all is +<symbol>True</symbol>, +all shapes in the geometry are freed regardless of the values of first and count. Otherwise, count shapes are freed, beginning with the shape specified by first. </para> <para> -To allocate geometry sections, use <emphasis> -XkbAllocGeomSections</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocGeomSections</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - num_needed</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /*geometry for which sections should be allocated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - num_needed</emphasis> -; /* number of new sections required */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocGeomSections</emphasis> - allocates num_needed sections and adds them to the geometry geom. No +To allocate geometry sections, use +<function>XkbAllocGeomSections</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAllocGeomSections"><primary><function>XkbAllocGeomSections</function></primary></indexterm> +<funcsynopsis id="XkbAllocGeomSections"> + <funcprototype> + <funcdef>Status <function>XkbAllocGeomSections</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>num_needed</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>int <parameter>num_needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry for which sections should be allocated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_needed</parameter> + </term> + <listitem> + <para> + number of new sections required + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocGeomSections</function> +allocates num_needed sections and adds them to the geometry geom. No initialization of the sections is done. </para> <para> -To free geometry sections, use <emphasis> -XkbFreeGeomSections</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeGeomSections</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - count</emphasis> -,<emphasis> - free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry in which sections should be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - first</emphasis> -; /* first section to be freed. */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - count</emphasis> -; /* number of sections to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all;</emphasis> - /* <emphasis> -True</emphasis> - => all sections are freed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -If free_all is <emphasis> -True</emphasis> -, all sections are freed regardless of the value of first and count. Otherwise, +To free geometry sections, use +<function>XkbFreeGeomSections</function>. +</para> + + +<indexterm significance="preferred" zone="XkbFreeGeomSections"><primary><function>XkbFreeGeomSections</function></primary></indexterm> +<funcsynopsis id="XkbFreeGeomSections"> + <funcprototype> + <funcdef>void <function>XkbFreeGeomSections</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>first</parameter>, +<parameter>count</parameter>, +<parameter>free_all</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>int <parameter>first</parameter></paramdef> + <paramdef>int <parameter>count</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry in which sections should be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + first section to be freed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>count</parameter> + </term> + <listitem> + <para> + number of sections to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ all sections are freed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If free_all is +<symbol>True</symbol>, +all sections are freed regardless of the value of first and count. Otherwise, the number of sections specified by count are freed, beginning with the section specified by first in the specified geometry. </para> <para> -To allocate rows in a section, use <emphasis> -XkbAllocGeomRows</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocGeomRows</emphasis> -(<emphasis> -section</emphasis> -,<emphasis> - num_needed</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbSectionPtr <emphasis> -section</emphasis> -; /* section for which rows should be allocated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - num_needed</emphasis> -; /* number of new rows required */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocGeomRows</emphasis> - allocates num_needed rows and adds them to the section. No initialization of +To allocate rows in a section, use +<function>XkbAllocGeomRows</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAllocGeomRows"><primary><function>XkbAllocGeomRows</function></primary></indexterm> +<funcsynopsis id="XkbAllocGeomRows"> + <funcprototype> + <funcdef>Status <function>XkbAllocGeomRows</function></funcdef> +<!-- ( +<parameter>section</parameter>, +<parameter>num_needed</parameter> +) --> + + <paramdef>XkbSectionPtr <parameter>section</parameter></paramdef> + <paramdef>int <parameter>num_needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>section</parameter> + </term> + <listitem> + <para> + section for which rows should be allocated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_needed</parameter> + </term> + <listitem> + <para> + number of new rows required + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocGeomRows</function> +allocates num_needed rows and adds them to the section. No initialization of the rows is done. </para> <para> -To free rows in a section, use <emphasis> -XkbFreeGeomRows</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeGeomRows</emphasis> -(<emphasis> -section</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - count</emphasis> -,<emphasis> - free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbSectionPtr <emphasis> - section</emphasis> -; /* section in which rows should be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - first</emphasis> -; /* first row to be freed. */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - count</emphasis> -; /* number of rows to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all;</emphasis> - /* <emphasis> -True</emphasis> - => all rows are freed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -If free_all is <emphasis> -True</emphasis> -, all rows are freed regardless of the value of first and count. Otherwise, the +To free rows in a section, use +<function>XkbFreeGeomRows</function>. +</para> + + +<indexterm significance="preferred" zone="XkbFreeGeomRows"><primary><function>XkbFreeGeomRows</function></primary></indexterm> +<funcsynopsis id="XkbFreeGeomRows"> + <funcprototype> + <funcdef>void <function>XkbFreeGeomRows</function></funcdef> +<!-- ( +<parameter>section</parameter>, +<parameter>first</parameter>, +<parameter>count</parameter>, +<parameter>free_all</parameter> +) --> + + <paramdef>XkbSectionPtr <parameter>section</parameter></paramdef> + <paramdef>int <parameter>first</parameter></paramdef> + <paramdef>int <parameter>count</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>section</parameter> + </term> + <listitem> + <para> + section in which rows should be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + first row to be freed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>count</parameter> + </term> + <listitem> + <para> + number of rows to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ all rows are freed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If free_all is +<symbol>True</symbol>, +all rows are freed regardless of the value of first and count. Otherwise, the number of rows specified by count are freed, beginning with the row specified by first in the specified section. </para> <para> -To allocate overlays in a section, use <emphasis> -XkbAllocGeomOverlays</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocGeomOverlays</emphasis> -(<emphasis> -section</emphasis> -,<emphasis> - num_needed</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbSectionPtr <emphasis> -section</emphasis> -; /* section for which overlays should be allocated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - num_needed</emphasis> -; /* number of new overlays required */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocGeomRows</emphasis> - allocates num_needed overlays and adds them to the section. No initialization +To allocate overlays in a section, use +<function>XkbAllocGeomOverlays</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAllocGeomOverlays"><primary><function>XkbAllocGeomOverlays</function></primary></indexterm> +<funcsynopsis id="XkbAllocGeomOverlays"> + <funcprototype> + <funcdef>Status <function>XkbAllocGeomOverlays</function></funcdef> +<!-- ( +<parameter>section</parameter>, +<parameter>num_needed</parameter> +) --> + + <paramdef>XkbSectionPtr <parameter>section</parameter></paramdef> + <paramdef>int <parameter>num_needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>section</parameter> + </term> + <listitem> + <para> + section for which overlays should be allocated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_needed</parameter> + </term> + <listitem> + <para> + number of new overlays required + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocGeomRows</function> +allocates num_needed overlays and adds them to the section. No initialization of the overlays is done. </para> <para> -To free rows in an section, use <emphasis> -XkbFreeGeomOverlays</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeGeomOverlays</emphasis> -(<emphasis> -section</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - count</emphasis> -,<emphasis> - free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbSectionPtr <emphasis> - section</emphasis> -; /* section in which overlays should be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - first</emphasis> -; /* first overlay to be freed. */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - count</emphasis> -; /* number of overlays to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all;</emphasis> - /* <emphasis> -True</emphasis> - => all overlays are freed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -If free_all is <emphasis> -True</emphasis> -, all overlays are freed regardless of the value of first and count. Otherwise, +To free rows in an section, use +<function>XkbFreeGeomOverlays</function>. +</para> + + +<indexterm significance="preferred" zone="XkbFreeGeomOverlays"><primary><function>XkbFreeGeomOverlays</function></primary></indexterm> +<funcsynopsis id="XkbFreeGeomOverlays"> + <funcprototype> + <funcdef>void <function>XkbFreeGeomOverlays</function></funcdef> +<!-- ( +<parameter>section</parameter>, +<parameter>first</parameter>, +<parameter>count</parameter>, +<parameter>free_all</parameter> +) --> + + <paramdef>XkbSectionPtr <parameter>section</parameter></paramdef> + <paramdef>int <parameter>first</parameter></paramdef> + <paramdef>int <parameter>count</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>section</parameter> + </term> + <listitem> + <para> + section in which overlays should be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + first overlay to be freed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>count</parameter> + </term> + <listitem> + <para> + number of overlays to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ all overlays are freed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If free_all is +<symbol>True</symbol>, +all overlays are freed regardless of the value of first and count. Otherwise, the number of overlays specified by count are freed, beginning with the overlay specified by first in the specified section. </para> <para> -To allocate rows in a overlay, use <emphasis> -XkbAllocGeomOverlayRows</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocGeomOverlayRows</emphasis> -(<emphasis> -overlay</emphasis> -,<emphasis> - num_needed</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbSectionPtr <emphasis> -overlay</emphasis> -; /* section for which rows should be allocated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - num_needed</emphasis> -; /* number of new rows required */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocGeomOverlayRows</emphasis> - allocates num_needed rows and adds them to the overlay. No initialization of +To allocate rows in a overlay, use +<function>XkbAllocGeomOverlayRows</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAllocGeomOverlayRows"><primary><function>XkbAllocGeomOverlayRows</function></primary></indexterm> +<funcsynopsis id="XkbAllocGeomOverlayRows"> + <funcprototype> + <funcdef>Status <function>XkbAllocGeomOverlayRows</function></funcdef> +<!-- ( +<parameter>overlay</parameter>, +<parameter>num_needed</parameter> +) --> + + <paramdef>XkbSectionPtr <parameter>overlay</parameter></paramdef> + <paramdef>int <parameter>num_needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>overlay</parameter> + </term> + <listitem> + <para> + section for which rows should be allocated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_needed</parameter> + </term> + <listitem> + <para> + number of new rows required + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocGeomOverlayRows</function> +allocates num_needed rows and adds them to the overlay. No initialization of the rows is done. </para> <para> -To free rows in an overlay, use <emphasis> -XkbFreeGeomOverlayRows</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeGeomOverlayRows</emphasis> -(<emphasis> -overlay</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - count</emphasis> -,<emphasis> - free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbSectionPtr <emphasis> - overlay</emphasis> -; /* section in which rows should be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - first</emphasis> -; /* first row to be freed. */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - count</emphasis> -; /* number of rows to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all;</emphasis> - /* <emphasis> -True</emphasis> - => all rows are freed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -If free_all is <emphasis> -True</emphasis> -, all rows are freed regardless of the value of first and count. Otherwise, the +To free rows in an overlay, use +<function>XkbFreeGeomOverlayRows</function>. +</para> + + +<indexterm significance="preferred" zone="XkbFreeGeomOverlayRows"><primary><function>XkbFreeGeomOverlayRows</function></primary></indexterm> +<funcsynopsis id="XkbFreeGeomOverlayRows"> + <funcprototype> + <funcdef>void <function>XkbFreeGeomOverlayRows</function></funcdef> +<!-- ( +<parameter>overlay</parameter>, +<parameter>first</parameter>, +<parameter>count</parameter>, +<parameter>free_all</parameter> +) --> + + <paramdef>XkbSectionPtr <parameter>overlay</parameter></paramdef> + <paramdef>int <parameter>first</parameter></paramdef> + <paramdef>int <parameter>count</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>overlay</parameter> + </term> + <listitem> + <para> + section in which rows should be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + first row to be freed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>count</parameter> + </term> + <listitem> + <para> + number of rows to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ all rows are freed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If free_all is +<symbol>True</symbol>, +all rows are freed regardless of the value of first and count. Otherwise, the number of rows specified by count are freed, beginning with the row specified by first in the specified overlay. </para> <para> -To allocate keys in an overlay row, use <emphasis> -XkbAllocGeomOverlayKeys</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocGeomOverlayKeys</emphasis> -(<emphasis> -row</emphasis> -,<emphasis> - num_needed</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbRowPtr <emphasis> -row</emphasis> -; /* section for which rows should be allocated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - num_needed</emphasis> -; /* number of new rows required */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocGeomOverlayKeys</emphasis> - allocates num_needed keys and adds them to the row. No initialization of the +To allocate keys in an overlay row, use +<function>XkbAllocGeomOverlayKeys</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAllocGeomOverlayKeys"><primary><function>XkbAllocGeomOverlayKeys</function></primary></indexterm> +<funcsynopsis id="XkbAllocGeomOverlayKeys"> + <funcprototype> + <funcdef>Status <function>XkbAllocGeomOverlayKeys</function></funcdef> +<!-- ( +<parameter>row</parameter>, +<parameter>num_needed</parameter> +) --> + + <paramdef>XkbRowPtr <parameter>row</parameter></paramdef> + <paramdef>int <parameter>num_needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>row</parameter> + </term> + <listitem> + <para> + section for which rows should be allocated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_needed</parameter> + </term> + <listitem> + <para> + number of new rows required + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocGeomOverlayKeys</function> +allocates num_needed keys and adds them to the row. No initialization of the keys is done. </para> <para> -To free keys in an overlay row, use <emphasis> -XkbFreeGeomOverlayKeys</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeGeomOverlayKeys</emphasis> -(<emphasis> -row</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - count</emphasis> -,<emphasis> - free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbRowPtr <emphasis> - row</emphasis> -; /* row in which keys should be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - first</emphasis> -; /* first key to be freed. */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - count</emphasis> -; /* number of keys to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all;</emphasis> - /* <emphasis> -True</emphasis> - => all keys are freed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -If free_all is <emphasis> -True</emphasis> -, all keys are freed regardless of the value of first and count. Otherwise, the +To free keys in an overlay row, use +<function>XkbFreeGeomOverlayKeys</function>. +</para> + + +<indexterm significance="preferred" zone="XkbFreeGeomOverlayKeys"><primary><function>XkbFreeGeomOverlayKeys</function></primary></indexterm> +<funcsynopsis id="XkbFreeGeomOverlayKeys"> + <funcprototype> + <funcdef>void <function>XkbFreeGeomOverlayKeys</function></funcdef> +<!-- ( +<parameter>row</parameter>, +<parameter>first</parameter>, +<parameter>count</parameter>, +<parameter>free_all</parameter> +) --> + + <paramdef>XkbRowPtr <parameter>row</parameter></paramdef> + <paramdef>int <parameter>first</parameter></paramdef> + <paramdef>int <parameter>count</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>row</parameter> + </term> + <listitem> + <para> + row in which keys should be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + first key to be freed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>count</parameter> + </term> + <listitem> + <para> + number of keys to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ all keys are freed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If free_all is +<symbol>True</symbol>, +all keys are freed regardless of the value of first and count. Otherwise, the number of keys specified by count are freed, beginning with the key specified by first in the specified row. </para> <para> -To allocate doodads that are global to a keyboard geometry, use <emphasis> -XkbAllocGeomDoodads</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocGeomDoodads</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - num_needed</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry for which doodads should be allocated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - num_needed</emphasis> -; /* number of new doodads required */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocGeomDoodads</emphasis> - allocates num_needed doodads and adds them to the specified geometry <emphasis> -geom</emphasis> -. No initialization of the doodads is done. -</para> - - -<para> -To allocate doodads that are specific to a section, use <emphasis> -XkbAllocGeomSectionDoodads</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocGeomSectionDoodads</emphasis> -(<emphasis> -section</emphasis> -,<emphasis> - num_needed</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbSectionPtr <emphasis> - section</emphasis> -; /* section for which doodads should be allocated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - num_needed</emphasis> -; /* number of new doodads required */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocGeomSectionDoodads</emphasis> - allocates num_needed doodads and adds them to the specified <emphasis> -section</emphasis> -. No initialization of the doodads is done. -</para> - - -<para> -To free geometry doodads, use <emphasis> -XkbFreeGeomDoodads</emphasis> -. -</para> - +To allocate doodads that are global to a keyboard geometry, use +<function>XkbAllocGeomDoodads</function>. +</para> + -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeGeomDoodads</emphasis> -(<emphasis> -doodads</emphasis> -,<emphasis> - count</emphasis> -,<emphasis> - free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDoodadPtr <emphasis> - doodads</emphasis> -; /* doodads to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - count</emphasis> -; /* number of doodads to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all;</emphasis> - /* <emphasis> -True</emphasis> - => all doodads are freed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -If <emphasis> -free_all</emphasis> - is <emphasis> -True</emphasis> -, all doodads in the array are freed, regardless of the value of count. +<indexterm significance="preferred" zone="XkbAllocGeomDoodads"><primary><function>XkbAllocGeomDoodads</function></primary></indexterm> +<funcsynopsis id="XkbAllocGeomDoodads"> + <funcprototype> + <funcdef>Status <function>XkbAllocGeomDoodads</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>num_needed</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>int <parameter>num_needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry for which doodads should be allocated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_needed</parameter> + </term> + <listitem> + <para> + number of new doodads required + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocGeomDoodads</function> +allocates num_needed doodads and adds them to the specified geometry +<parameter>geom</parameter>. +No initialization of the doodads is done. +</para> + + +<para> +To allocate doodads that are specific to a section, use +<function>XkbAllocGeomSectionDoodads</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAllocGeomSectionDoodads"><primary><function>XkbAllocGeomSectionDoodads</function></primary></indexterm> +<funcsynopsis id="XkbAllocGeomSectionDoodads"> + <funcprototype> + <funcdef>Status <function>XkbAllocGeomSectionDoodads</function></funcdef> +<!-- ( +<parameter>section</parameter>, +<parameter>num_needed</parameter> +) --> + + <paramdef>XkbSectionPtr <parameter>section</parameter></paramdef> + <paramdef>int <parameter>num_needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>section</parameter> + </term> + <listitem> + <para> + section for which doodads should be allocated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_needed</parameter> + </term> + <listitem> + <para> + number of new doodads required + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocGeomSectionDoodads</function> +allocates num_needed doodads and adds them to the specified +<parameter>section</parameter>. +No initialization of the doodads is done. +</para> + + +<para> +To free geometry doodads, use +<function>XkbFreeGeomDoodads</function>. +</para> + + +<indexterm significance="preferred" zone="XkbFreeGeomDoodads"><primary><function>XkbFreeGeomDoodads</function></primary></indexterm> +<funcsynopsis id="XkbFreeGeomDoodads"> + <funcprototype> + <funcdef>void <function>XkbFreeGeomDoodads</function></funcdef> +<!-- ( +<parameter>doodads</parameter>, +<parameter>count</parameter>, +<parameter>free_all</parameter> +) --> + + <paramdef>XkbDoodadPtr <parameter>doodads</parameter></paramdef> + <paramdef>int <parameter>count</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>doodads</parameter> + </term> + <listitem> + <para> + doodads to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>count</parameter> + </term> + <listitem> + <para> + number of doodads to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ all doodads are freed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If +<parameter>free_all</parameter> +is +<symbol>True</symbol>, +all doodads in the array are freed, regardless of the value of count. Otherwise, count doodads are freed. </para> <para> -To allocate an entire geometry, use <emphasis> -XkbAllocGeometry</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocGeometry</emphasis> -(<emphasis> -xkb</emphasis> -,<emphasis> - sizes</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* keyboard description for which geometry is to be allocated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometrySizesPtr<emphasis> - sizes</emphasis> -; /* initial sizes for all geometry components */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocGeometry</emphasis> - allocates a keyboard geometry and adds it to the keyboard description +To allocate an entire geometry, use +<function>XkbAllocGeometry</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAllocGeometry"><primary><function>XkbAllocGeometry</function></primary></indexterm> +<funcsynopsis id="XkbAllocGeometry"> + <funcprototype> + <funcdef>Status <function>XkbAllocGeometry</function></funcdef> +<!-- ( +<parameter>xkb</parameter>, +<parameter>sizes</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>XkbGeometrySizesPtr <parameter>sizes</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description for which geometry is to be allocated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>sizes</parameter> + </term> + <listitem> + <para> + initial sizes for all geometry components + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocGeometry</function> +allocates a keyboard geometry and adds it to the keyboard description specified by xkb. The keyboard description should be obtained via the XkbGetKeyboard or XkbAllockeyboard functions. The sizes parameter specifies the number of elements to be reserved for the subcomponents of the keyboard @@ -4121,63 +4214,64 @@ colors, shapes, sections, and doodads. <para> -To free an entire geometry, use <emphasis> -XkbFreeGeometry</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeGeometry</emphasis> -(<emphasis> -geom</emphasis> -,<emphasis> - which</emphasis> -,<emphasis> - free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbGeometryPtr <emphasis> - geom</emphasis> -; /* geometry to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - which</emphasis> -; /* mask of geometry components to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all;</emphasis> - /* <emphasis> -True</emphasis> - => the entire geometry is freed. */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +To free an entire geometry, use +<function>XkbFreeGeometry</function>. +</para> + + +<indexterm significance="preferred" zone="XkbFreeGeometry"><primary><function>XkbFreeGeometry</function></primary></indexterm> +<funcsynopsis id="XkbFreeGeometry"> + <funcprototype> + <funcdef>void <function>XkbFreeGeometry</function></funcdef> +<!-- ( +<parameter>geom</parameter>, +<parameter>which</parameter>, +<parameter>free_all</parameter> +) --> + + <paramdef>XkbGeometryPtr <parameter>geom</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>geom</parameter> + </term> + <listitem> + <para> + geometry to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of geometry components to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ the entire geometry is freed. + </para> + </listitem> + </varlistentry> +</variablelist> <para> The values of which and free_all determine how much of the specified geometry is freed. The valid values for which are: -</para> -<para><programlisting> +<programlisting> #define XkbGeomPropertiesMask (1<<0) #define XkbGeomColorsMask (1<<1) #define XkbGeomShapesMask (1<<2) @@ -4187,9 +4281,9 @@ is freed. The valid values for which are: </programlisting></para> <para> -If free_all is <emphasis> -True</emphasis> -, the entire geometry is freed regardless of the value of which. Otherwise, the +If free_all is +<symbol>True</symbol>, +the entire geometry is freed regardless of the value of which. Otherwise, the portions of the geometry specified by which are freed. </para> diff --git a/libX11/specs/XKB/ch14.xml b/libX11/specs/XKB/ch14.xml index 1fcc76800..cb30105c5 100644 --- a/libX11/specs/XKB/ch14.xml +++ b/libX11/specs/XKB/ch14.xml @@ -1,3 +1,6 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Xkb_Keyboard_Mapping'> <title>Xkb Keyboard Mapping</title> @@ -11,14 +14,21 @@ utilities for manipulating the keyboard mapping. <para> The mapping consists of two components, a server map and a client map. The -<emphasis> -client</emphasis> - map is the collection of information a client needs to interpret key events +<firstterm>client map</firstterm> +<indexterm significance="preferred" zone="Xkb_Keyboard_Mapping"> +<primary>client map</primary></indexterm> +<indexterm significance="preferred" zone="Xkb_Keyboard_Mapping"> +<primary>map</primary><secondary>client</secondary></indexterm> +is the collection of information a client needs to interpret key events from the keyboard. It contains a global list of key types and an array of key symbol maps, each of which describes the symbols bound to a key and the rules -to be used to interpret those symbols. The <emphasis> -server</emphasis> - map contains the information the server needs to interpret key events. This +to be used to interpret those symbols. The +<firstterm>server map</firstterm> +<indexterm significance="preferred" zone="Xkb_Keyboard_Mapping"> +<primary>server map</primary></indexterm> +<indexterm significance="preferred" zone="Xkb_Keyboard_Mapping"> +<primary>map</primary><secondary>server</secondary></indexterm> +contains the information the server needs to interpret key events. This includes actions and behaviors for each key, explicit components for a key, and the virtual modifiers and the per-key virtual modifier mapping. </para> @@ -26,20 +36,25 @@ the virtual modifiers and the per-key virtual modifier mapping. <para> For detailed information on particular components of the keyboard map, refer to -Chapter 15, "Xkb Client Keyboard Mapping" and Chapter 16, "Xkb Server Keyboard -Mapping." +<xref linkend="Xkb_Client_Keyboard_Mapping" />, and +<xref linkend="Xkb_Server_Keyboard_Mapping" />. </para> <sect1 id='Notation_and_Terminology'> <title>Notation and Terminology</title> +<indexterm significance="preferred" zone="Notation_and_Terminology"> +<primary>level</primary></indexterm> +<indexterm significance="preferred" zone="Notation_and_Terminology"> +<primary>shift level</primary></indexterm> + <para> The graphic characters or control functions that may be accessed by one key are -logically arranged in groups and levels, where <emphasis> -group</emphasis> - and <emphasis> -level</emphasis> - are defined as in the ISO9995 standard: +logically arranged in groups and levels, where +<structfield>group</structfield> +and +<structfield>level</structfield> +are defined as in the ISO9995 standard: </para> <variablelist> @@ -74,30 +89,32 @@ character the key is capable of generating. <para> -Level is often referred to as "Shift Level". Levels are numbered sequentially -starting at one. +Level is often referred to as <quote>Shift Level</quote>. +Levels are numbered sequentially starting at one. </para> <note><para>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> - (that is, the <emphasis> -NumLock</emphasis> - virtual modifier) also selects shift level 2.</para></note> +in the same way for all keys. For example, the +<symbol>Shift</symbol> +modifier selects shift level 2 on most keys, but for keypad keys the modifier +bound to +<keysym>Num_Lock</keysym> +(that is, the +<emphasis>NumLock</emphasis> +virtual modifier) also selects shift level 2.</para></note> <para> For example, consider the following key (the gray characters indicate symbols that are implied or expected but are not actually engraved on the key): </para> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-14.svg"/> - </imageobject> -<caption>Shift Levels and Groups</caption> - </mediaobject> +<figure id='figure14.1'> + <title>Shift Levels and Groups</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-14.svg"/> + </imageobject> + </mediaobject> +</figure> <!-- @@ -107,15 +124,14 @@ Shift Levels and Groups</H5> <para> This key has two groups, indicated by the columns, and each group has two shift -levels. For the first group (Group1), the symbol shift level one is <emphasis> -a</emphasis> -, and the symbol for shift level two is <emphasis> -A</emphasis> -. For the second group, the symbol for shift level one is <emphasis> -æ</emphasis> -, and the symbol for shift level two is <emphasis> -Æ</emphasis> -. +levels. For the first group (Group1), the symbol shift level one is +<keysym>a</keysym>, +and the symbol for shift level two is +<keysym>A</keysym>. +For the second group, the symbol for shift level one is +<keysym>æ</keysym>, +and the symbol for shift level two is +<keysym>Æ</keysym>. </para> <sect2 id='Core_Implementation'> @@ -123,40 +139,38 @@ A</emphasis> <para> The standard interpretation rules for the core X keymap only allow clients to -access keys such as the one shown in Figure 14.1. That is, clients using the +access keys such as the one shown in <link linkend="figure14.1">Figure 14.1</link>. That is, clients using the standard interpretation rules can only access one of four keysyms for any given -<emphasis> -KeyPress</emphasis> - event — two different symbols in two different groups. +<symbol>KeyPress</symbol> +event — two different symbols in two different groups. </para> <para> -In general, the <emphasis> -Shift</emphasis> - modifier, the <emphasis> -Lock</emphasis> - modifier, and the modifier bound to the <emphasis> -Num_Lock</emphasis> - key are used to change between shift level 1 and shift level 2. To switch +In general, the +<symbol>Shift</symbol> +modifier, the +<symbol>Lock</symbol> +modifier, and the modifier bound to the +<keysym>Num_Lock</keysym> +key are used to change between shift level 1 and shift level 2. To switch between groups, the core implementation uses the modifier bound to the -<emphasis> -Mode_switch</emphasis> - key. When the <emphasis> -Mode_switch</emphasis> - modifier is set, the keyboard is logically in Group 2. When the <emphasis> -Mode_switch</emphasis> - modifier is not set, the keyboard is logically in Group 1. +<keysym>Mode_switch</keysym> +key. When the +<keysym>Mode_switch</keysym> +modifier is set, the keyboard is logically in Group 2. When the +<keysym>Mode_switch</keysym> +modifier is not set, the keyboard is logically in Group 1. </para> <para> The core implementation does not clearly specify the behavior of keys. For -example, the locking behavior of the <emphasis> -CapsLock</emphasis> - and <emphasis> -Num_Lock</emphasis> - keys depends on the vendor. +example, the locking behavior of the +<emphasis>CapsLock</emphasis> +and +<keysym>Num_Lock</keysym> +keys depends on the vendor. </para> @@ -174,14 +188,14 @@ group. Most keys will only have a few shift levels. </para></footnote>. In addition, Xkb provides precise specifications regarding the behavior of keys. In Xkb, modifier state and the current group are independent (with the -exception of compatibility mapping, discussed in Chapter 17). +exception of compatibility mapping, discussed in <xref linkend="The_Xkb_Compatibility_Map" />). </para> <para> Xkb handles switching between groups via key actions, independent of any modifier state information. Key actions are in the server map component and are -described in detail in section 16.1.4. +described in detail in <link linkend="Actions_for_Changing_Group_State">section 16.1.4</link>. </para> @@ -193,17 +207,17 @@ type and specifies the modifier combinations necessary to access each level. <para> -For example, Xkb allows key types where the <emphasis> -Control</emphasis> - modifier can be used to access the shift level two of a key. Key types are in -the client map component and are described in detail in section 15.2. <!-- xref --> +For example, Xkb allows key types where the +<symbol>Control</symbol> +modifier can be used to access the shift level two of a key. Key types are in +the client map component and are described in detail in <link linkend="Key_Types">section 15.2</link>. </para> <para> Xkb provides precise specification of the behavior of a key using key behaviors. Key behaviors are in the server map component and are described in -detail in section 16.2. <!-- xref --> +detail in <link linkend="Key_Behavior">section 16.2</link>. </para> @@ -214,148 +228,150 @@ detail in section 16.2. <!-- xref --> <para> Xkb provides two functions to obtain the keyboard mapping components from the -server. The first function, <emphasis> -XkbGetMap</emphasis> -, allocates an <emphasis> -XkbDescRec</emphasis> - structure, retrieves mapping components from the server, and stores them in -the <emphasis> -XkbDescRec</emphasis> - structure it just allocated. The second function, <emphasis> -XkbGetUpdatedMap</emphasis> -, retrieves mapping components from the server and stores them in an <emphasis> -XkbDescRec</emphasis> - structure that has previously been allocated. +server. The first function, +<function>XkbGetMap</function>, +allocates an +<structname>XkbDescRec</structname> +structure, retrieves mapping components from the server, and stores them in +the +<structname>XkbDescRec</structname> +structure it just allocated. The second function, +<function>XkbGetUpdatedMap</function>, +retrieves mapping components from the server and stores them in an +<structname>XkbDescRec</structname> +structure that has previously been allocated. </para> <para> -To allocate an <emphasis> -XkbDescRec</emphasis> - structure and populate it with the server’s keyboard client map and server -map, use <emphasis> -XkbGetMap. XkbGetMap </emphasis> -is similar to <emphasis> -XkbGetKeyboard</emphasis> - (see section 6.2), but is used only for obtaining the address of an <emphasis> -XkbDescRec</emphasis> - structure that is populated with keyboard mapping components. It allows finer +To allocate an +<structname>XkbDescRec</structname> +structure and populate it with the server’s keyboard client map and server +map, use +<function>XkbGetMap</function>. +<function>XkbGetMap</function> +is similar to +<function>XkbGetKeyboard</function> +(see <link linkend="Obtaining_a_Keyboard_Description_from_the_Server">section 6.2</link>), but is used only for obtaining the address of an +<structname>XkbDescRec</structname> +structure that is populated with keyboard mapping components. It allows finer control over which substructures of the keyboard mapping components are to be -populated. <emphasis> -XkbGetKeyboard</emphasis> - always returns fully populated components, while <emphasis> -XkbGetMap</emphasis> - can be instructed to return a partially populated component. +populated. +<function>XkbGetKeyboard</function> +always returns fully populated components, while +<function>XkbGetMap</function> +can be instructed to return a partially populated component. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbDescPtr <emphasis> -XkbGetMap</emphasis> -(<emphasis> -display, which, device_spec</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - which</emphasis> -; /* mask selecting subcomponents to populate */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - device_spec</emphasis> -; /* device_id, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbGetMap"><primary><function>XkbGetMap</function></primary></indexterm> +<funcsynopsis id="XkbGetMap"> + <funcprototype> + <funcdef>XkbDescPtr <function>XkbGetMap</function></funcdef> +<!-- ( +<parameter>display, which, device_spec</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask selecting subcomponents to populate + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device_id, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -The <emphasis> -which</emphasis> - mask is a bitwise inclusive OR of the masks defined in Table 14.1. Only those +The +<parameter>which</parameter> +mask is a bitwise inclusive OR of the masks defined in +<link linkend="table14.1">Table 14.1</link>. Only those portions of the keyboard server map and the keyboard client maps that are -specified in <emphasis> -which</emphasis> - are allocated and populated. +specified in +<parameter>which</parameter> +are allocated and populated. </para> <para> In addition to allocating and obtaining the server map and the client map, -<emphasis> -XkbGetMap</emphasis> - also sets the <emphasis> -device_spec</emphasis> -, the <emphasis> -min_key_code</emphasis> -<emphasis> -, </emphasis> -and <emphasis> -max_key_code</emphasis> - fields of the keyboard description. +<function>XkbGetMap</function> +also sets the +<parameter>device_spec</parameter>, +the +<structfield>min_key_code</structfield>, +and +<structfield>max_key_code</structfield> +fields of the keyboard description. </para> <para> -<emphasis> -XkbGetMap</emphasis> - is synchronous; it queries the server for the desired information, waits for a -reply, and then returns. If successful<emphasis> -, XkbGetMap</emphasis> - returns a pointer to the <emphasis> -XkbDescRec</emphasis> - structure it allocated. If unsuccessful, <emphasis> -XkbGetMap</emphasis> - returns <emphasis> -NULL</emphasis> -. When unsuccessful, one of the following protocol errors is also generated: -<emphasis> -BadAlloc</emphasis> - (unable to allocate the <emphasis> -XkbDescRec</emphasis> - structure), <emphasis> -BadValue</emphasis> - (some mask bits in <emphasis> -which</emphasis> - are undefined)<emphasis> -,</emphasis> - or <emphasis> -BadImplementation</emphasis> - (a compatible version of the Xkb extension is not available in the server). To -free the returned data, use <emphasis> -XkbFreeClientMap</emphasis> -. +<function>XkbGetMap</function> +is synchronous; it queries the server for the desired information, waits for a +reply, and then returns. If successful, +<function>XkbGetMap</function> +returns a pointer to the +<structname>XkbDescRec</structname> +structure it allocated. If unsuccessful, +<function>XkbGetMap</function> +returns +<symbol>NULL</symbol>. +When unsuccessful, one of the following protocol errors is also generated: +<errorname>BadAlloc</errorname> +(unable to allocate the +<structname>XkbDescRec</structname> +structure), +<errorname>BadValue</errorname> +(some mask bits in +<parameter>which</parameter> +are undefined), +or +<errorname>BadImplementation</errorname> +(a compatible version of the Xkb extension is not available in the server). To +free the returned data, use +<function>XkbFreeClientMap</function>. </para> <para> Xkb also provides convenience functions to get partial component definitions -from the server. These functions are specified in the "convenience functions" -column in Table 14.1. Refer to the sections listed in the table for more +from the server. These functions are specified in the +<quote>convenience functions</quote> +column in <link linkend="table14.1">Table 14.1</link>. +Refer to the sections listed in the table for more information on these functions. </para> -<table frame='topbot'> +<table id='table14.1' frame='topbot'> <title>Xkb Mapping Component Masks and Convenience Functions</title> <?dbfo keep-together="always" ?> <tgroup cols='6' align='left' colsep='0' rowsep='0'> @@ -377,94 +393,94 @@ information on these functions. </thead> <tbody> <row> - <entry><emphasis>XkbKeyTypesMask</emphasis></entry> + <entry><symbol>XkbKeyTypesMask</symbol></entry> <entry>(1<<0)</entry> <entry>client</entry> <entry> - <para><emphasis>types</emphasis></para> - <para><emphasis>size_types</emphasis></para> - <para><emphasis>num_types</emphasis></para> + <para><structfield>types</structfield></para> + <para><structfield>size_types</structfield></para> + <para><structfield>num_types</structfield></para> </entry> <entry> - <para><emphasis>XkbGetKeyTypes</emphasis></para> - <para><emphasis>XkbResizeKeyType</emphasis></para> - <para><emphasis>XkbCopyKeyType</emphasis></para> - <para><emphasis>XkbCopyKeyTypes</emphasis></para> + <para><function>XkbGetKeyTypes</function></para> + <para><function>XkbResizeKeyType</function></para> + <para><function>XkbCopyKeyType</function></para> + <para><function>XkbCopyKeyTypes</function></para> </entry> - <entry>15.2</entry> + <entry><link linkend="Key_Types">15.2</link></entry> </row> <row> - <entry><emphasis>XkbKeySymsMask</emphasis></entry> + <entry><symbol>XkbKeySymsMask</symbol></entry> <entry>(1<<1)</entry> <entry>client</entry> <entry> - <para><emphasis>syms</emphasis></para> - <para><emphasis>size_syms</emphasis></para> - <para><emphasis>num_syms</emphasis></para> - <para><emphasis>key_sym_map</emphasis></para> + <para><structfield>syms</structfield></para> + <para><structfield>size_syms</structfield></para> + <para><structfield>num_syms</structfield></para> + <para><structfield>key_sym_map</structfield></para> </entry> <entry> - <para><emphasis>XkbGetKeySyms</emphasis></para> - <para><emphasis>XkbResizeKeySyms</emphasis></para> - <para><emphasis>XkbChangeTypes­OfKey</emphasis></para> + <para><function>XkbGetKeySyms</function></para> + <para><function>XkbResizeKeySyms</function></para> + <para><function>XkbChangeTypes­OfKey</function></para> </entry> - <entry>15.3</entry> + <entry><link linkend="Key_Symbol_Map">15.3</link></entry> </row> <row> - <entry><emphasis>XkbModifierMapMask</emphasis></entry> + <entry><symbol>XkbModifierMapMask</symbol></entry> <entry>(1<<2)</entry> <entry>client</entry> - <entry><emphasis>modmap</emphasis></entry> - <entry><emphasis>XkbGetKeyModifier­Map</emphasis></entry> - <entry>15.4</entry> + <entry><structfield>modmap</structfield></entry> + <entry><function>XkbGetKeyModifier­Map</function></entry> + <entry><link linkend="The_Per_Key_Modifier_Map">15.4</link></entry> </row> <row> - <entry><emphasis>XkbExplicitComponentsMask</emphasis></entry> + <entry><symbol>XkbExplicitComponentsMask</symbol></entry> <entry>(1<<3)</entry> <entry>server</entry> - <entry><emphasis>explicit</emphasis></entry> - <entry><emphasis>XkbGetKeyExplicit­Components</emphasis></entry> - <entry>16.3</entry> + <entry><structfield>explicit</structfield></entry> + <entry><function>XkbGetKeyExplicit­Components</function></entry> + <entry><link linkend="Explicit_ComponentsAvoiding_Automatic_Remapping_by_the_Server">16.3</link></entry> </row> <row> - <entry><emphasis>XkbKeyActionsMask</emphasis></entry> + <entry><symbol>XkbKeyActionsMask</symbol></entry> <entry>(1<<4)</entry> <entry>server</entry> <entry> - <para><emphasis>key_acts</emphasis></para> - <para><emphasis>acts</emphasis></para> - <para><emphasis>num_acts</emphasis></para> - <para><emphasis>size_acts</emphasis></para> + <para><structfield>key_acts</structfield></para> + <para><structfield>acts</structfield></para> + <para><structfield>num_acts</structfield></para> + <para><structfield>size_acts</structfield></para> </entry> <entry> - <para><emphasis>XkbGetKeyActions</emphasis></para> - <para><emphasis>XkbResizeKey­Actions</emphasis></para> + <para><function>XkbGetKeyActions</function></para> + <para><function>XkbResizeKey­Actions</function></para> </entry> - <entry>16.1</entry> + <entry><link linkend="Key_Actions">16.1</link></entry> </row> <row> - <entry><emphasis>XkbKeyBehaviorsMask</emphasis></entry> + <entry><symbol>XkbKeyBehaviorsMask</symbol></entry> <entry>(1<<5)</entry> <entry>server</entry> - <entry><emphasis>behaviors</emphasis></entry> - <entry><emphasis>XkbGetKey­Behaviors</emphasis></entry> - <entry>16.2</entry> + <entry><structfield>behaviors</structfield></entry> + <entry><function>XkbGetKey­Behaviors</function></entry> + <entry><link linkend="Key_Behavior">16.2</link></entry> </row> <row> - <entry><emphasis>XkbVirtualModsMask</emphasis></entry> + <entry><symbol>XkbVirtualModsMask</symbol></entry> <entry>(1<<6)</entry> <entry>server</entry> - <entry><emphasis>vmods</emphasis></entry> - <entry><emphasis>XkbGetVirtualMods</emphasis></entry> - <entry>16.4</entry> + <entry><structfield>vmods</structfield></entry> + <entry><function>XkbGetVirtualMods</function></entry> + <entry><link linkend="Virtual_Modifier_Mapping">16.4</link></entry> </row> <row> - <entry><emphasis>XkbVirtualModMapMask</emphasis></entry> + <entry><symbol>XkbVirtualModMapMask</symbol></entry> <entry>(1<<7)</entry> <entry>server</entry> - <entry><emphasis>vmodmap</emphasis></entry> - <entry><emphasis>XkbGetVirtualMod­Map</emphasis></entry> - <entry>16.4</entry> + <entry><structfield>vmodmap</structfield></entry> + <entry><function>XkbGetVirtualMod­Map</function></entry> + <entry><link linkend="Virtual_Modifier_Mapping">16.4</link></entry> </row> </tbody> </tgroup> @@ -472,9 +488,8 @@ information on these functions. <para> Xkb defines combinations of these masks for convenience: -</para> -<para><programlisting> +<programlisting> #define XkbResizableInfoMask (XkbKeyTypesMask) #define XkbAllClientInfoMask (XkbKeyTypesMask | XkbKeySymsMask | XkbModifierMapMask) @@ -493,88 +508,95 @@ these components and handle the interdependencies. <para> To update the client or server map information in an existing keyboard -description, use <emphasis>XkbGetUpdatedMap</emphasis>. +description, use <function>XkbGetUpdatedMap</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetUpdatedMap</emphasis> -(<emphasis> -display, which, xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask selecting subcomponents to populate */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description to be updated */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbGetUpdatedMap"><primary><function>XkbGetUpdatedMap</function></primary></indexterm> +<funcsynopsis id="XkbGetUpdatedMap"> + <funcprototype> + <funcdef>Status <function>XkbGetUpdatedMap</function></funcdef> +<!-- ( +<parameter>display, which, xkb</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask selecting subcomponents to populate + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description to be updated + </para> + </listitem> + </varlistentry> +</variablelist> <para> -The <emphasis> -which</emphasis> - parameter is a bitwise inclusive OR of the masks in Table 14.1. If the needed -components of the <emphasis> -xkb</emphasis> - structure are not already allocated, <emphasis> -XkbGetUpdatedMap</emphasis> - allocates them. <emphasis> -XkbGetUpdatedMap</emphasis> - fetches the requested information for the device specified in the <emphasis> -XkbDescRec</emphasis> - passed in the <emphasis> -xkb</emphasis> - parameter. +The +<parameter>which</parameter> +parameter is a bitwise inclusive OR of the masks in +<link linkend="table14.1">Table 14.1</link>. +If the needed components of the +<parameter>xkb</parameter> +structure are not already allocated, +<function>XkbGetUpdatedMap</function> +allocates them. +<function>XkbGetUpdatedMap</function> +fetches the requested information for the device specified in the +<structname>XkbDescRec</structname> +passed in the +<parameter>xkb</parameter> +parameter. </para> <para> -<emphasis> -XkbGetUpdatedMap</emphasis> - is synchronous; it queries the server for the desired information, waits for a -reply, and then returns. If successful<emphasis> -, XkbGetUpdatedMap</emphasis> - returns <emphasis> -Success</emphasis> -. If unsuccessful, <emphasis> -XkbGetUpdatedMap</emphasis> - returns one of the following: <emphasis> -BadAlloc</emphasis> - (unable to allocate a component in the <emphasis> -XkbDescRec</emphasis> - structure), <emphasis> -BadValue</emphasis> - (some mask bits in <emphasis> -which</emphasis> - are undefined), <emphasis> -BadImplementation</emphasis> - (a compatible version of the Xkb extension is not available in the server or +<function>XkbGetUpdatedMap</function> +is synchronous; it queries the server for the desired information, waits for a +reply, and then returns. If successful, +<function>XkbGetUpdatedMap</function> +returns +<symbol>Success</symbol>. +If unsuccessful, +<function>XkbGetUpdatedMap</function> +returns one of the following: +<errorname>BadAlloc</errorname> +(unable to allocate a component in the +<structname>XkbDescRec</structname> +structure), +<errorname>BadValue</errorname> +(some mask bits in +<parameter>which</parameter> +are undefined), +<errorname>BadImplementation</errorname> +(a compatible version of the Xkb extension is not available in the server or the reply from the server was invalid). </para> @@ -584,183 +606,190 @@ the reply from the server was invalid). <para> There are two ways to make changes to map components: either change a local -copy of the keyboard map and call <emphasis> -XkbSetMap</emphasis> - to send the modified map to the server, or, to reduce network traffic, use -an<emphasis> - XkbMapChangesRec</emphasis> - structure and call <emphasis>XkbChangeMap</emphasis>. +copy of the keyboard map and call +<function>XkbSetMap</function> +to send the modified map to the server, or, to reduce network traffic, use +an +<structname>XkbMapChangesRec</structname> +structure and call <function>XkbChangeMap</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetMap</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - which</emphasis> -,<emphasis> - xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask selecting subcomponents to update */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* description from which new values are taken */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbSetMap"><primary><function>XkbSetMap</function></primary></indexterm> +<funcsynopsis id="XkbSetMap"> + <funcprototype> + <funcdef>Bool <function>XkbSetMap</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>which</parameter>, +<parameter>xkb</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask selecting subcomponents to update + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + description from which new values are taken + </para> + </listitem> + </varlistentry> +</variablelist> <para> -Use <emphasis> -XkbSetMap</emphasis> - to send a complete new set of values for entire components (for example, all -symbols, all actions, and so on) to the server. The <emphasis> -which</emphasis> - parameter specifies the components to be sent to the server, and is a bitwise -inclusive OR of the masks listed in Table 14.1. The <emphasis> -xkb</emphasis> - parameter is a pointer to an <emphasis> -XkbDescRec</emphasis> - structure and contains the information to be copied to the server. For each -bit set in the <emphasis> -which</emphasis> - parameter, <emphasis> -XkbSetMap</emphasis> - takes the corresponding structure values from the <emphasis> -xkb</emphasis> - parameter and sends it to the server specified by <emphasis> -dpy</emphasis>. +Use +<function>XkbSetMap</function> +to send a complete new set of values for entire components (for example, all +symbols, all actions, and so on) to the server. The +<parameter>which</parameter> +parameter specifies the components to be sent to the server, and is a bitwise +inclusive OR of the masks listed in +<link linkend="table14.1">Table 14.1</link>. The +<parameter>xkb</parameter> +parameter is a pointer to an +<structname>XkbDescRec</structname> +structure and contains the information to be copied to the server. For each +bit set in the +<parameter>which</parameter> +parameter, +<function>XkbSetMap</function> +takes the corresponding structure values from the +<parameter>xkb</parameter> +parameter and sends it to the server specified by +<parameter>dpy</parameter>. </para> <para> -If any components specified by <emphasis> -which</emphasis> - are not present in the <emphasis> -xkb</emphasis> - parameter, <emphasis> -XkbSetMap</emphasis> - returns <emphasis> -False</emphasis> -. Otherwise, it sends the update request to the server and returns <emphasis> -True</emphasis> -. <emphasis> -XkbSetMap</emphasis> - can generate <emphasis> -BadAlloc</emphasis> -, <emphasis> -BadLength</emphasis> -, and <emphasis> -BadValue</emphasis> - protocol errors. +If any components specified by +<parameter>which</parameter> +are not present in the +<parameter>xkb</parameter> +parameter, +<function>XkbSetMap</function> +returns +<symbol>False</symbol>. +Otherwise, it sends the update request to the server and returns +<symbol>True</symbol>. +<function>XkbSetMap</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadLength</errorname>, +and +<errorname>BadValue</errorname> +protocol errors. </para> <para> Key types, symbol maps, and actions are all interrelated; changes in one require changes in the others. Xkb provides functions to make it easier to edit -these components and handle the interdependencies. Table 14.1 lists these +these components and handle the interdependencies. +<link linkend="table14.1">Table 14.1</link> lists these helper functions and provides a pointer to where they are defined. </para> <sect2 id='The_XkbMapChangesRec_Structure'> <title>The XkbMapChangesRec Structure</title> +<indexterm significance="preferred" zone="The_XkbMapChangesRec_Structure"> +<primary><structname>XkbMapChangesRec</structname></primary></indexterm> <para> -Use the <emphasis> -XkbMapChangesRec</emphasis> - structure to identify and track partial modifications to the mapping +Use the +<structname>XkbMapChangesRec</structname> +structure to identify and track partial modifications to the mapping components and to reduce the amount of traffic between the server and clients. </para> <para><programlisting> typedef struct _XkbMapChanges { - unsigned short changed; /* identifies valid components - in structure */ - KeyCode min_key_code; /* lowest numbered keycode for - device */ - KeyCode max_key_code; /* highest numbered keycode for - device */ - unsigned char first_type; /* index of first key <emphasis>type</emphasis> - modified */ - unsigned char num_types; /* # types modified */ - KeyCode first_key_sym; /* first key whose <emphasis>key_sym_map</emphasis> - changed */ - unsigned char num_key_syms; /* # <emphasis>key_sym_map</emphasis> - entries changed */ - KeyCode first_key_act; /* first key whose <emphasis>key_acts</emphasis> - entry changed */ - unsigned char num_key_acts; /* # <emphasis>key_acts</emphasis> - entries changed */ - KeyCode first_key_behavior; /* first key whose <emphasis>behaviors</emphasis> - changed */ - unsigned char num_key_behaviors; /* # <emphasis>behaviors</emphasis> - entries changed */ - KeyCode first_key_explicit; /* first key whose <emphasis>explicit</emphasis> - entry changed */ - unsigned char num_key_explicit; /* # <emphasis> explicit</emphasis> - entries changed */ - KeyCode first_modmap_key; /* first key whose <emphasis>modmap</emphasis> - entry changed */ - unsigned char num_modmap_keys; /* # <emphasis>modmap</emphasis> - entries changed */ - KeyCode first_vmodmap_key; /* first key whose <emphasis>vmodmap</emphasis> - changed */ - unsigned char num_vmodmap_keys; /* # <emphasis> vmodmap</emphasis> - entries changed */ - unsigned char pad1; /* reserved */ - unsigned short vmods; /* mask indicating which <emphasis>vmods</emphasis> - changed */ -} <emphasis>XkbMapChangesRec</emphasis>,*XkbMapChangesPtr; + unsigned short changed; /* identifies valid components + in structure */ + KeyCode min_key_code; /* lowest numbered keycode for + device */ + KeyCode max_key_code; /* highest numbered keycode for + device */ + unsigned char first_type; /* index of first key <structfield>type</structfield> + modified */ + unsigned char num_types; /* # types modified */ + KeyCode first_key_sym; /* first key whose <structfield>key_sym_map</structfield> + changed */ + unsigned char num_key_syms; /* # <structfield>key_sym_map</structfield> + entries changed */ + KeyCode first_key_act; /* first key whose <structfield>key_acts</structfield> + entry changed */ + unsigned char num_key_acts; /* # <structfield>key_acts</structfield> + entries changed */ + KeyCode first_key_behavior; /* first key whose <structfield>behaviors</structfield> + changed */ + unsigned char num_key_behaviors; /* # <structfield>behaviors</structfield> + entries changed */ + KeyCode first_key_explicit; /* first key whose <structfield>explicit</structfield> + entry changed */ + unsigned char num_key_explicit; /* # <structfield>explicit</structfield> + entries changed */ + KeyCode first_modmap_key; /* first key whose <structfield>modmap</structfield> + entry changed */ + unsigned char num_modmap_keys; /* # <structfield>modmap</structfield> + entries changed */ + KeyCode first_vmodmap_key; /* first key whose <structfield>vmodmap</structfield> + changed */ + unsigned char num_vmodmap_keys; /* # <structfield>vmodmap</structfield> + entries changed */ + unsigned char pad1; /* reserved */ + unsigned short vmods; /* mask indicating which <structfield>vmods</structfield> + changed */ +} <structname>XkbMapChangesRec</structname>, *XkbMapChangesPtr; </programlisting></para> <para> -The <emphasis> -changed</emphasis> - field identifies the map components that have changed in an <emphasis> -XkbDescRec</emphasis> - structure and may contain any of the bits in Table 14.1, which are also shown -in Table 14.2. Every 1 bit in <emphasis> -changed</emphasis> - also identifies which other fields in the <emphasis> -XkbMapChangesRec</emphasis> - structure contain valid values, as indicated in Table 14.2. The <emphasis> -min_key_code</emphasis> - and <emphasis> -max_key_code</emphasis> - fields are for reference only; they are ignored on any requests sent to the +The +<structfield>changed</structfield> +field identifies the map components that have changed in an +<structname>XkbDescRec</structname> +structure and may contain any of the bits in +<link linkend="table14.1">Table 14.1</link>, which are also shown +in <link linkend="table14.2">Table 14.2</link>. Every 1 bit in +<structfield>changed</structfield> +also identifies which other fields in the +<structname>XkbMapChangesRec</structname> +structure contain valid values, as indicated in +<link linkend="table14.2">Table 14.2</link>. The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields are for reference only; they are ignored on any requests sent to the server and are always updated by the server whenever it returns the data for an -<emphasis> -XkbMapChangesRec</emphasis> -. +<structname>XkbMapChangesRec</structname>. </para> -<table frame='topbot'> +<table id='table14.2' frame='topbot'> <title>XkbMapChangesRec Masks</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -776,85 +805,85 @@ XkbMapChangesRec</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbKeyTypesMask</emphasis></entry> + <entry><symbol>XkbKeyTypesMask</symbol></entry> <entry> -<para>first_type</para>, -<para>num_types</para> +<structfield>first_type</structfield>, +<structfield>num_types</structfield> </entry> <entry> -<para>map->type[first_type] ..</para> -<para>map->type[first_type + num_types - 1]</para> +<structfield>map->type[first_type]</structfield> .. +<structfield>map->type[first_type + num_types - 1]</structfield> </entry> </row> <row> - <entry><emphasis>XkbKeySymsMask</emphasis></entry> + <entry><symbol>XkbKeySymsMask</symbol></entry> <entry> -<para>first_key_sym</para>, -<para>num_key_syms</para> +<structfield>first_key_sym</structfield>, +<structfield>num_key_syms</structfield> </entry> <entry> -<para>map->key_sym_map[first_key_sym] ..</para> -<para>map->key_sym_map[first_key_sym + num_key_syms - 1]</para> +<structfield>map->key_sym_map[first_key_sym]</structfield> .. +<structfield>map->key_sym_map[first_key_sym + num_key_syms - 1]</structfield> </entry> </row> <row> - <entry><emphasis>XkbModifierMapMask</emphasis></entry> + <entry><symbol>XkbModifierMapMask</symbol></entry> <entry> -<para>first_modmap_key</para>, -<para>num_modmap_keys</para> +<structfield>first_modmap_key</structfield>, +<structfield>num_modmap_keys</structfield> </entry> <entry> -<para>map->modmap[first_modmap_key] ..</para> -<para>map->modmap[first_modmap_key + num_modmap_keys-1]</para> +<structfield>map->modmap[first_modmap_key]</structfield> .. +<structfield>map->modmap[first_modmap_key + num_modmap_keys-1]</structfield> </entry> </row> <row> - <entry><emphasis>XkbExplicitComponentsMask</emphasis></entry> + <entry><symbol>XkbExplicitComponentsMask</symbol></entry> <entry> -<para>first_key_explicit</para>, -<para>num_key_explicit</para> +<structfield>first_key_explicit</structfield>, +<structfield>num_key_explicit</structfield> </entry> <entry> -<para>server->explicit[first_key_explicit] ..</para> -<para>server->explicit[first_key_explicit + num_key_explicit - 1]</para> +<structfield>server->explicit[first_key_explicit]</structfield> .. +<structfield>server->explicit[first_key_explicit + num_key_explicit - 1]</structfield> </entry> </row> <row> - <entry><emphasis>XkbKeyActionsMask</emphasis></entry> + <entry><symbol>XkbKeyActionsMask</symbol></entry> <entry> -<para>first_key_act,</para> -<para>num_key_acts</para> +<structfield>first_key_act</structfield>, +<structfield>num_key_acts</structfield> </entry> <entry> -<para>server->key_acts[first_key_act] ..</para> -<para>server->key_acts[first_key_act + num_key_acts - 1]</para> +<structfield>server->key_acts[first_key_act]</structfield> .. +<structfield>server->key_acts[first_key_act + num_key_acts - 1]</structfield> </entry> </row> <row> - <entry><emphasis>XkbKeyBehaviorsMask</emphasis></entry> + <entry><symbol>XkbKeyBehaviorsMask</symbol></entry> <entry> -<para>first_key_behavior,</para> -<para>num_key_behaviors</para> +<structfield>first_key_behavior</structfield>, +<structfield>num_key_behaviors</structfield> </entry> <entry> -<para>server->behaviors[first_key_behavior] ..</para> -<para>server->behaviors[first_key_behavior + num_key_behaviors - 1]</para> +<structfield>server->behaviors[first_key_behavior]</structfield> .. +<structfield>server->behaviors[first_key_behavior + num_key_behaviors - 1]</structfield> </entry> </row> <row> - <entry><emphasis>XkbVirtuawModsMask</emphasis></entry> - <entry>vmods</entry> - <entry>server->vmods[*]</entry> + <entry><symbol>XkbVirtualModsMask</symbol></entry> + <entry><structfield>vmods</structfield></entry> + <entry><structfield>server->vmods[*]</structfield></entry> </row> <row> - <entry><emphasis>XkbVirtualModMapMask</emphasis></entry> + <entry><symbol>XkbVirtualModMapMask</symbol></entry> <entry> -<para>first_vmodmap_key,</para> -<para>num_vmodmap_keys</para> +<structfield>first_vmodmap_key</structfield>, +<structfield>num_vmodmap_keys</structfield> </entry> <entry> -<para>server->vmodmap[first_vmodmap_key] ..</para> -<para>server->vmodmap[first_vmodmap_key + num_vmodmap_keys - 1]</para> +<structfield>server->vmodmap[first_vmodmap_key]</structfield> .. +<structfield>server->vmodmap[first_vmodmap_key + num_vmodmap_keys - 1]</structfield> </entry> </row> </tbody> @@ -864,94 +893,94 @@ XkbMapChangesRec</emphasis> <para> To update only partial components of a keyboard description, modify the appropriate fields in the server and map components of a local copy of the -keyboard description, then call <emphasis> -XkbChangeMap</emphasis> - with an <emphasis> -XkbMapChangesRec</emphasis> - structure indicating which components have changed. +keyboard description, then call +<function>XkbChangeMap</function> +with an +<structname>XkbMapChangesRec</structname> +structure indicating which components have changed. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbChangeMap</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - xkb</emphasis> -,<emphasis> - changes</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* description from which new values are taken */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbMapChangesPtr <emphasis> - changes</emphasis> -; /*identifies component parts to update */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbChangeMap"><primary><function>XkbChangeMap</function></primary></indexterm> +<funcsynopsis id="XkbChangeMap"> + <funcprototype> + <funcdef>Bool <function>XkbChangeMap</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>xkb</parameter>, +<parameter>changes</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>XkbMapChangesPtr <parameter>changes</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + description from which new values are taken + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + identifies component parts to update + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbChangeMap</emphasis> - copies any components specified by the <emphasis> -changes</emphasis> - structure from the keyboard description, <emphasis> -xkb</emphasis> -, to the X server specified by <emphasis> -dpy</emphasis> -. +<function>XkbChangeMap</function> +copies any components specified by the +<parameter>changes</parameter> +structure from the keyboard description, +<parameter>xkb</parameter>, +to the X server specified by +<parameter>dpy</parameter>. </para> <para> -If any components specified by <emphasis> -changes</emphasis> - are not present in the <emphasis> -xkb</emphasis> - parameter, <emphasis> -XkbChangeMap</emphasis> - returns <emphasis> -False</emphasis> -. Otherwise, it sends a request to the server and returns <emphasis> -True</emphasis> -. +If any components specified by +<parameter>changes</parameter> +are not present in the +<parameter>xkb</parameter> +parameter, +<function>XkbChangeMap</function> +returns +<symbol>False</symbol>. +Otherwise, it sends a request to the server and returns +<symbol>True</symbol>. </para> <para> -<emphasis> -XkbChangeMap</emphasis> - can generate <emphasis> -BadAlloc</emphasis> -, <emphasis> -BadLength</emphasis> -, and <emphasis> -BadValue</emphasis> - protocol errors. +<function>XkbChangeMap</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadLength</errorname>, +and +<errorname>BadValue</errorname> +protocol errors. </para> @@ -960,97 +989,102 @@ BadValue</emphasis> <sect1 id='Tracking_Changes_to_Map_Components'> <title>Tracking Changes to Map Components</title> +<indexterm significance="preferred" zone="Tracking_Changes_to_Map_Components"> +<primary>events</primary><secondary><symbol>XkbMapNotify</symbol></secondary></indexterm> +<indexterm significance="preferred" zone="Tracking_Changes_to_Map_Components"> +<primary><structname>XkbMapNotifyEvent</structname></primary></indexterm> + <para> -The Xkb extension reports <emphasis> -XkbMapNotify</emphasis> - events to clients wanting notification whenever a map component of the Xkb +The Xkb extension reports +<symbol>XkbMapNotify</symbol> +events to clients wanting notification whenever a map component of the Xkb description for a device changes. There are many different types of Xkb keyboard map changes. Xkb uses an event detail mask to identify each type of -change. The event detail masks are identical to the masks listed in Table 14.1. +change. The event detail masks are identical to the masks listed in +<link linkend="table14.1">Table 14.1</link>. </para> <para> -To receive <emphasis> -XkbMapNotify</emphasis> - events under all possible conditions, use <emphasis> -XkbSelectEvents</emphasis> - (see section 4.3) and pass <emphasis> -XkbMapNotifyMask</emphasis> - in both <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> -. +To receive +<symbol>XkbMapNotify</symbol> +events under all possible conditions, use +<function>XkbSelectEvents</function> +(see <link linkend="Selecting_Xkb_Events">section 4.3</link>) and pass +<symbol>XkbMapNotifyMask</symbol> +in both +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter>. </para> <para> -To receive <emphasis> -XkbMapNotify</emphasis> - events only under certain conditions, use <emphasis> -XkbSelectEventDetails</emphasis> - using <emphasis> -XkbMapNotify</emphasis> - as the <emphasis> -event_type</emphasis> - and specifying the desired map changes in <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> - using mask bits from Table 14.1. +To receive +<symbol>XkbMapNotify</symbol> +events only under certain conditions, use +<function>XkbSelectEventDetails</function> +using +<symbol>XkbMapNotify</symbol> +as the +<structfield>event_type</structfield> +and specifying the desired map changes in +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +using mask bits from <link linkend="table14.1">Table 14.1</link>. </para> <para> -The structure for <emphasis> -XkbMapNotify</emphasis> - events is: -</para> +The structure for +<symbol>XkbMapNotify</symbol> +events is: -<para><programlisting> +<programlisting> typedef struct { - int type; /* Xkb extension base event code */ - unsigned long serial; /* X server serial number for event */ - Bool send_event; /* <emphasis>True</emphasis> => synthetically generated */ - Display * display; /* server connection where event generated */ - Time time; /* server time when event generated */ - int xkb_type; /* <emphasis> XkbMapNotify</emphasis> */ - int device; /* Xkb device ID, will not be <emphasis>XkbUseCoreKbd</emphasis> */ - unsigned int changed; /* identifies valid fields in rest of event */ - unsigned int resized; /* reserved */ - int first_type; /* index of first key <emphasis> type</emphasis> modified */ - int num_types /* # types modified */ - KeyCode min_key_code; /* minimum keycode for device */ - KeyCode max_key_code; /* maximum keycode for device */ - KeyCode first_key_sym; /* first key whose <emphasis>key_sym_map</emphasis> changed */ - KeyCode first_key_act; /* first key whose <emphasis> key_acts</emphasis> entry changed */ - KeyCode first_key_behavior; /* first key whose <emphasis> behaviors</emphasis> changed */ - KeyCode first_key_explicit; /* first key whose <emphasis> explicit </emphasis> entry changed */ - KeyCode first_modmap_key; /* first key whose <emphasis> modmap</emphasis> entry changed */ - KeyCode first_vmodmap_key; /* # <emphasis> modmap</emphasis> entries changed */ - int num_key_syms; /* # <emphasis>key_sym_map</emphasis> entries changed */ - int num_key_acts; /* # <emphasis> key_acts</emphasis> entries changed */ - int num_key_behaviors; /* # <emphasis> behaviors</emphasis> entries changed */ - int num_key_explicit; /* # <emphasis> explicit</emphasis> entries changed */ - int num_modmap_keys; /* # <emphasis> modmap</emphasis> entries changed */ - int num_vmodmap_keys; /* # <emphasis> vmodmap</emphasis> entries changed */ - unsigned in t vmods; /* mask indicating which <emphasis> vmods</emphasis> changed */ -} <emphasis>XkbMapNotifyEvent</emphasis>; + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* <symbol>True</symbol> ⇒ synthetically generated */ + Display * display; /* server connection where event generated */ + Time time; /* server time when event generated */ + int xkb_type; /* <symbol>XkbMapNotify</symbol> */ + int device; /* Xkb device ID, will not be <symbol>XkbUseCoreKbd</symbol> */ + unsigned int changed; /* identifies valid fields in rest of event */ + unsigned int resized; /* reserved */ + int first_type; /* index of first key <structfield>type</structfield> modified */ + int num_types /* # types modified */ + KeyCode min_key_code; /* minimum keycode for device */ + KeyCode max_key_code; /* maximum keycode for device */ + KeyCode first_key_sym; /* first key whose <structfield>key_sym_map</structfield> changed */ + KeyCode first_key_act; /* first key whose <structfield>key_acts</structfield> entry changed */ + KeyCode first_key_behavior; /* first key whose <structfield>behaviors</structfield> changed */ + KeyCode first_key_explicit; /* first key whose <structfield>explicit</structfield> entry changed */ + KeyCode first_modmap_key; /* first key whose <structfield>modmap</structfield> entry changed */ + KeyCode first_vmodmap_key; /* # <structfield>modmap</structfield> entries changed */ + int num_key_syms; /* # <structfield>key_sym_map</structfield> entries changed */ + int num_key_acts; /* # <structfield>key_acts</structfield> entries changed */ + int num_key_behaviors; /* # <structfield>behaviors</structfield> entries changed */ + int num_key_explicit; /* # <structfield>explicit</structfield> entries changed */ + int num_modmap_keys; /* # <structfield>modmap</structfield> entries changed */ + int num_vmodmap_keys; /* # <structfield>vmodmap</structfield> entries changed */ + unsigned int vmods; /* mask indicating which <structfield>vmods</structfield> changed */ +} <structname>XkbMapNotifyEvent</structname>; </programlisting></para> <para> -The <emphasis> -changed</emphasis> - field specifies the map components that have changed and is the bitwise -inclusive OR of the mask bits defined in Table 14.1. The other fields in this -event are interpreted as the like-named fields in an <emphasis> -XkbMapChangesRec</emphasis> - (see section 14.3.1). The <emphasis> -XkbMapNotifyEvent</emphasis> - structure also has an additional <emphasis> -resized</emphasis> - field that is reserved for future use. +The +<structfield>changed</structfield> +field specifies the map components that have changed and is the bitwise +inclusive OR of the mask bits defined in +<link linkend="table14.1">Table 14.1</link>. The other fields in this +event are interpreted as the like-named fields in an +<structname>XkbMapChangesRec</structname> +(see <link linkend="The_XkbMapChangesRec_Structure">section 14.3.1</link>). The +<structname>XkbMapNotifyEvent</structname> +structure also has an additional +<structfield>resized</structfield> +field that is reserved for future use. </para> @@ -1059,9 +1093,9 @@ resized</emphasis> <title>Allocating and Freeing Client and Server Maps</title> <para> -Calling <emphasis> -XkbGetMap</emphasis> - (see section 14.2) should be sufficient for most applications to get client +Calling +<function>XkbGetMap</function> +(see <link linkend="Getting_Map_Components_from_the_Server">section 14.2</link>) should be sufficient for most applications to get client and server maps. As a result, most applications do not need to directly allocate client and server maps. </para> @@ -1070,28 +1104,26 @@ allocate client and server maps. <para> If you change the number of key types or construct map components without loading the necessary components from the X server, do not allocate any map -components directly using <emphasis> -malloc</emphasis> - or <emphasis> -Xmalloc</emphasis> -. Instead, use the Xkb allocators, <emphasis> -XkbAllocClientMap,</emphasis> - and <emphasis> -XkbAllocServerMap</emphasis> -. +components directly using +<function>malloc</function> +or +<function>Xmalloc</function>. +Instead, use the Xkb allocators, +<function>XkbAllocClientMap</function>, +and +<function>XkbAllocServerMap</function>. </para> <para> -Similarly, use the Xkb destructors, <emphasis> -XkbFreeClientMap,</emphasis> - and <emphasis> -XkbFreeServerMap</emphasis> - instead of <emphasis> -free</emphasis> - or <emphasis> -Xfree</emphasis> -. +Similarly, use the Xkb destructors, +<function>XkbFreeClientMap</function>, +and +<function>XkbFreeServerMap</function> +instead of +<function>free</function> +or +<function>Xfree</function>. </para> @@ -1100,66 +1132,69 @@ Xfree</emphasis> <para> To allocate and initialize an empty client map description record, use -<emphasis> -XkbAllocClientMap.</emphasis> +<function>XkbAllocClientMap</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocClientMap</emphasis> -(<emphasis> -xkb, which, type_count</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* keyboard description in which to allocate client map */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask selecting map components to allocate */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - type_count</emphasis> -; /* value of <emphasis> -num_types</emphasis> - field in map to be allocated */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbAllocClientMap"><primary><function>XkbAllocClientMap</function></primary></indexterm> +<funcsynopsis id="XkbAllocClientMap"> + <funcprototype> + <funcdef>Status <function>XkbAllocClientMap</function></funcdef> +<!-- ( +<parameter>xkb, which, type_count</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>unsigned int <parameter>type_count</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description in which to allocate client map + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask selecting map components to allocate + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>type_count</parameter> + </term> + <listitem> + <para> + value of <structfield>num_types</structfield> field in map to be allocated + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbAllocClientMap</emphasis> - allocates and initializes an empty client map in the <emphasis> -map</emphasis> - field of the keyboard description specified by <emphasis> -xkb</emphasis> -. The <emphasis> -which</emphasis> - parameter specifies the particular components of the client map structure to +<function>XkbAllocClientMap</function> +allocates and initializes an empty client map in the +<structfield>map</structfield> +field of the keyboard description specified by +<parameter>xkb</parameter>. +The +<parameter>which</parameter> +parameter specifies the particular components of the client map structure to allocate and is a mask composed by a bitwise inclusive OR of one or more of the -masks shown in Table 14.3. +masks shown in <link linkend="table14.3">Table 14.3</link>. </para> -<table frame='topbot'> +<table id='table14.3' frame='topbot'> <title>XkbAllocClientMap Masks</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1173,116 +1208,115 @@ masks shown in Table 14.3. </thead> <tbody> <row> - <entry>XkbKeyTypesMask</entry> + <entry><symbol>XkbKeyTypesMask</symbol></entry> <entry> -The <emphasis> -type_count </emphasis> -field specifies the number of entries to preallocate for the <emphasis> -types</emphasis> - field of the client map. If the <emphasis> -type_count </emphasis> -field is less than <emphasis> -XkbNumRequiredTypes</emphasis> - (see section 15.2.1), returns <emphasis> -BadValue</emphasis>. +The +<parameter>type_count</parameter> +field specifies the number of entries to preallocate for the +<structfield>types</structfield> +field of the client map. If the +<parameter>type_count</parameter> +field is less than +<symbol>XkbNumRequiredTypes</symbol> +(see <link linkend="The_Canonical_Key_Types">section 15.2.1</link>), returns +<errorname>BadValue</errorname>. </entry> </row> <row> - <entry>XkbKeySymsMask</entry> + <entry><symbol>XkbKeySymsMask</symbol></entry> <entry> -The <emphasis> -min_key_code</emphasis> - and <emphasis> -max_key_code</emphasis> - fields of the <emphasis> -xkb</emphasis> - parameter are used to allocate the <emphasis> -syms</emphasis> - and <emphasis> -key_sym_map</emphasis> - fields of the client map. The fields are allocated to contain the maximum -number of entries necessary for <emphasis> -max_key_code</emphasis> - - <emphasis> -min_key_code</emphasis> - + 1 keys. +The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields of the +<parameter>xkb</parameter> +parameter are used to allocate the +<structfield>syms</structfield> +and +<structfield>key_sym_map</structfield> +fields of the client map. The fields are allocated to contain the maximum +number of entries necessary for +<structfield>max_key_code</structfield> +− +<structfield>min_key_code</structfield> ++ 1 keys. </entry> </row> <row> - <entry>XkbModifierMapMask</entry> + <entry><symbol>XkbModifierMapMask</symbol></entry> <entry> -The <emphasis> -min_key_code</emphasis> - and <emphasis> -max_key_code</emphasis> - fields of the <emphasis> -xkb</emphasis> - parameter are used to allocate the <emphasis> -modmap</emphasis> - field of the client map. The field is allocated to contain the maximum number -of entries necessary for <emphasis> -max_key_code</emphasis> - - <emphasis> -min_key_code</emphasis> - + 1 keys. +The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields of the +<parameter>xkb</parameter> +parameter are used to allocate the +<structfield>modmap</structfield> +field of the client map. The field is allocated to contain the maximum number +of entries necessary for +<structfield>max_key_code</structfield> +− +<structfield>min_key_code</structfield> ++ 1 keys. </entry> </row> </tbody> </tgroup> </table> -<note><para>The <emphasis> -min_key_code</emphasis> - and <emphasis> -max_key_code</emphasis> - fields of the <emphasis> -xkb</emphasis> - parameter must be legal values if the <emphasis> -XkbKeySymsMask</emphasis> - or <emphasis> -XkbModifierMapMask</emphasis> - masks are set in the <emphasis> -which</emphasis> - parameter. If they are not valid, <emphasis> -XkbAllocClientMap</emphasis> - returns <emphasis> -BadValue</emphasis> -. </para></note> +<note><para>The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields of the +<parameter>xkb</parameter> +parameter must be legal values if the +<symbol>XkbKeySymsMask</symbol> +or +<symbol>XkbModifierMapMask</symbol> +masks are set in the +<parameter>which</parameter> +parameter. If they are not valid, +<function>XkbAllocClientMap</function> +returns +<errorname>BadValue</errorname>. +</para></note> <para> -If the client map of the keyboard description is not <emphasis> -NULL</emphasis> -, and any fields are already allocated in the client map, <emphasis> -XkbAllocClientMap</emphasis> - does not overwrite the existing values; it simply ignores that part of the -request. The only exception is the <emphasis> -types</emphasis> - array. If <emphasis> -type_count</emphasis> - is greater than the current <emphasis> -num_types</emphasis> - field of the client map, <emphasis> -XkbAllocClientMap</emphasis> - resizes the <emphasis> -types</emphasis> - array and resets the <emphasis> -num_types</emphasis> - field accordingly. +If the client map of the keyboard description is not +<symbol>NULL</symbol>, +and any fields are already allocated in the client map, +<function>XkbAllocClientMap</function> +does not overwrite the existing values; it simply ignores that part of the +request. The only exception is the +<structfield>types</structfield> +array. If +<parameter>type_count</parameter> +is greater than the current +<structfield>num_types</structfield> +field of the client map, +<function>XkbAllocClientMap</function> +resizes the +<structfield>types</structfield> +array and resets the +<structfield>num_types</structfield> +field accordingly. </para> <para> -If <emphasis> -XkbAllocClientMap</emphasis> - is successful, it returns <emphasis> -Success</emphasis> -. Otherwise, it can return either <emphasis> -BadMatch</emphasis> -, <emphasis> -BadAlloc</emphasis> -, or <emphasis> -BadValue</emphasis> - errors. +If +<function>XkbAllocClientMap</function> +is successful, it returns +<symbol>Success</symbol>. +Otherwise, it can return either +<errorname>BadMatch</errorname>, +<errorname>BadAlloc</errorname>, +or +<errorname>BadValue</errorname> +errors. </para> @@ -1291,91 +1325,96 @@ BadValue</emphasis> <title>Freeing a Client Map</title> <para> -To free memory used by the client map member of an <emphasis> -XkbDescRec</emphasis> - structure, use <emphasis> -XkbFreeClientMap.</emphasis> +To free memory used by the client map member of an +<structname>XkbDescRec</structname> +structure, use +<function>XkbFreeClientMap</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeClientMap</emphasis> -(<emphasis> -xkb, which, free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* keyboard description containing client map to free */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask identifying components of map to free */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all</emphasis> -; /* <emphasis> -True</emphasis> - => free all client components and map itself */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbFreeClientMap"><primary><function>XkbFreeClientMap</function></primary></indexterm> +<funcsynopsis id="XkbFreeClientMap"> + <funcprototype> + <funcdef>void <function>XkbFreeClientMap</function></funcdef> +<!-- ( +<parameter>xkb, which, free_all</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description containing client map to free + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask identifying components of map to free + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> + ⇒ free all client components and map itself + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbFreeClientMap</emphasis> - frees the components of client map specified by <emphasis> -which</emphasis> - in the <emphasis> -XkbDescRec</emphasis> - structure specified by the <emphasis> -xkb</emphasis> - parameter and sets the corresponding structure component values to <emphasis> -NULL</emphasis> -. The <emphasis> -which</emphasis> - parameter specifies a combination of the client map masks shown in Table 14.3. +<function>XkbFreeClientMap</function> +frees the components of client map specified by +<parameter>which</parameter> +in the +<structname>XkbDescRec</structname> +structure specified by the +<parameter>xkb</parameter> +parameter and sets the corresponding structure component values to +<symbol>NULL</symbol>. +The +<parameter>which</parameter> +parameter specifies a combination of the client map masks shown in +<link linkend="table14.3">Table 14.3</link>. </para> <para> -If <emphasis> -free_all</emphasis> - is <emphasis> -True</emphasis> -, <emphasis> -which</emphasis> - is ignored; <emphasis> -XkbFreeClientMap</emphasis> - frees every non-<emphasis> -NULL</emphasis> - structure component in the client map, frees the <emphasis> -XkbClientMapRec</emphasis> - structure referenced by the <emphasis> -map</emphasis> - member of the <emphasis> -xkb</emphasis> - parameter, and sets the <emphasis> -map</emphasis> - member to <emphasis> -NULL.</emphasis> +If +<parameter>free_all</parameter> +is +<symbol>True</symbol>, +<parameter>which</parameter> +is ignored; +<function>XkbFreeClientMap</function> +frees every non- +<symbol>NULL</symbol> +structure component in the client map, frees the +<structname>XkbClientMapRec</structname> +structure referenced by the +<structfield>map</structfield> +member of the +<parameter>xkb</parameter> +parameter, and sets the +<structfield>map</structfield> +member to +<symbol>NULL</symbol>. </para> @@ -1385,65 +1424,68 @@ NULL.</emphasis> <para> To allocate and initialize an empty server map description record, use -<emphasis> -XkbAllocServerMap.</emphasis> +<function>XkbAllocServerMap</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocServerMap</emphasis> -(<emphasis> -xkb, which, count_acts</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* keyboard description in which to allocate server map */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask selecting map components to allocate */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - count_acts</emphasis> -; /* value of <emphasis> -num_acts</emphasis> - field in map to be allocated */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbAllocServerMap"><primary><function>XkbAllocServerMap</function></primary></indexterm> +<funcsynopsis id="XkbAllocServerMap"> + <funcprototype> + <funcdef>Status <function>XkbAllocServerMap</function></funcdef> +<!-- ( +<parameter>xkb, which, count_acts</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>unsigned int <parameter>count_acts</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description in which to allocate server map + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask selecting map components to allocate + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>count_acts</parameter> + </term> + <listitem> + <para> + value of <structfield>num_acts</structfield> field in map to be allocated + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbAllocServerMap</emphasis> - allocates and initializes an empty server map in the <emphasis> -server</emphasis> - field of the keyboard description specified by <emphasis> -xkb</emphasis> -. The <emphasis> -which</emphasis> - parameter specifies the particular components of the server map structure to -allocate, as specified in Table 14.4. +<function>XkbAllocServerMap</function> +allocates and initializes an empty server map in the +<structfield>server</structfield> +field of the keyboard description specified by +<parameter>xkb</parameter>. +The +<parameter>which</parameter> +parameter specifies the particular components of the server map structure to +allocate, as specified in <link linkend="table14.4">Table 14.4</link>. </para> -<table frame='topbot'> +<table id='table14.4' frame='topbot'> <title>XkbAllocServerMap Masks</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1457,62 +1499,62 @@ allocate, as specified in Table 14.4. </thead> <tbody> <row> - <entry>XkbExplicitComponentsMask</entry> + <entry><symbol>XkbExplicitComponentsMask</symbol></entry> <entry> -The <emphasis> -min_key_code</emphasis> - and <emphasis> -max_key_code</emphasis> - fields of the <emphasis> -xkb</emphasis> - parameter are used to allocate the <emphasis> -explicit </emphasis> +The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields of the +<parameter>xkb</parameter> +parameter are used to allocate the +<structfield>explicit</structfield> field of the server map. </entry> </row> <row> - <entry>XkbKeyActionsMask</entry> + <entry><symbol>XkbKeyActionsMask</symbol></entry> <entry> -The <emphasis> -min_key_code</emphasis> - and <emphasis> -max_key_code</emphasis> - fields of the <emphasis> -xkb</emphasis> - parameter are used to allocate the <emphasis> -key_acts </emphasis> -field of the server map. The <emphasis> -count_acts</emphasis> - parameter is used to allocate the <emphasis> -acts</emphasis> - field of the server map. +The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields of the +<parameter>xkb</parameter> +parameter are used to allocate the +<structfield>key_acts</structfield> +field of the server map. The +<parameter>count_acts</parameter> +parameter is used to allocate the +<structfield>acts</structfield> +field of the server map. </entry> </row> <row> - <entry>XkbKeyBehaviorsMask</entry> + <entry><symbol>XkbKeyBehaviorsMask</symbol></entry> <entry> -The <emphasis> -min_key_code</emphasis> - and <emphasis> -max_key_code</emphasis> - fields of the <emphasis> -xkb</emphasis> - parameter are used to allocate the <emphasis> -behaviors </emphasis> +The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields of the +<parameter>xkb</parameter> +parameter are used to allocate the +<structfield>behaviors</structfield> field of the server map. </entry> </row> <row> - <entry>XkbVirtualModMapMask</entry> + <entry><symbol>XkbVirtualModMapMask</symbol></entry> <entry> -The <emphasis> -min_key_code</emphasis> - and <emphasis> -max_key_code</emphasis> - fields of the <emphasis> -xkb </emphasis> -parameter are used to allocate the <emphasis> -vmodmap </emphasis> +The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields of the +<parameter>xkb</parameter> +parameter are used to allocate the +<structfield>vmodmap</structfield> field of the server map. </entry> </row> @@ -1520,50 +1562,49 @@ field of the server map. </tgroup> </table> -<note><para>The <emphasis> -min_key_code</emphasis> - and <emphasis> -max_key_code</emphasis> - fields of the <emphasis> -xkb</emphasis> - parameter must be legal values. If they are not valid, <emphasis> -XkbAllocServerMap</emphasis> - returns <emphasis> -BadValue</emphasis> -. </para></note> +<note><para>The +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +fields of the +<parameter>xkb</parameter> +parameter must be legal values. If they are not valid, +<function>XkbAllocServerMap</function> +returns +<errorname>BadValue</errorname>. +</para></note> <para> -If the server map of the keyboard description is not <emphasis> -NULL</emphasis> - and any fields are already allocated in the server map, <emphasis> -XkbAllocServerMap</emphasis> - does not overwrite the existing values. The only exception is with the -<emphasis> -acts </emphasis> -array. If the <emphasis> -count_acts </emphasis> -parameter is greater than the current <emphasis> -num_acts </emphasis> -field of the server map, <emphasis> -XkbAllocServerMap</emphasis> - resizes the <emphasis> -acts </emphasis> -array and resets the <emphasis> -num_acts </emphasis> +If the server map of the keyboard description is not +<symbol>NULL</symbol> +and any fields are already allocated in the server map, +<function>XkbAllocServerMap</function> +does not overwrite the existing values. The only exception is with the +<structfield>acts</structfield> +array. If the +<parameter>count_acts</parameter> +parameter is greater than the current +<structfield>num_acts</structfield> +field of the server map, +<function>XkbAllocServerMap</function> +resizes the +<structfield>acts</structfield> +array and resets the +<structfield>num_acts</structfield> field accordingly. </para> <para> -If <emphasis> -XkbAllocServerMap</emphasis> - is successful, it returns <emphasis> -Success</emphasis> -. Otherwise, it can return either <emphasis> -BadMatch</emphasis> - or <emphasis> -BadAlloc</emphasis> - errors. +If +<function>XkbAllocServerMap</function> +is successful, it returns +<symbol>Success</symbol>. +Otherwise, it can return either +<errorname>BadMatch</errorname> +or +<errorname>BadAlloc</errorname> +errors. </para> @@ -1572,85 +1613,91 @@ BadAlloc</emphasis> <title>Freeing a Server Map</title> <para> -To free memory used by the server member of an <emphasis> -XkbDescRec</emphasis> - structure, use <emphasis> -XkbFreeServerMap.</emphasis> +To free memory used by the server member of an +<structname>XkbDescRec</structname> +structure, use +<function>XkbFreeServerMap</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeServerMap</emphasis> -(<emphasis> -xkb, which, free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* keyboard description containing server map to free */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask identifying components of map to free */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_all</emphasis> -; /* <emphasis> -True</emphasis> - => free all server map components and server itself */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbFreeServerMap"><primary><function>XkbFreeServerMap</function></primary></indexterm> +<funcsynopsis id="XkbFreeServerMap"> + <funcprototype> + <funcdef>void <function>XkbFreeServerMap</function></funcdef> +<!-- ( +<parameter>xkb, which, free_all</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description containing server map to free + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask identifying components of map to free + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> + ⇒ free all server map components and server itself + </para> + </listitem> + </varlistentry> +</variablelist> <para> -The <emphasis> -XkbFreeServerMap</emphasis> - function frees the specified components of server map in the <emphasis> -XkbDescRec</emphasis> - structure specified by the <emphasis> -xkb</emphasis> - parameter and sets the corresponding structure component values to <emphasis> -NULL</emphasis> -. The <emphasis> -which</emphasis> - parameter specifies a combination of the server map masks and is a bitwise -inclusive OR of the masks listed in Table 14.4. If <emphasis> -free_all</emphasis> - is <emphasis> -True</emphasis> -, <emphasis> -which</emphasis> - is ignored and <emphasis> -XkbFreeServerMap</emphasis> - frees every non-<emphasis> -NULL</emphasis> - structure component in the server map, frees the <emphasis> -XkbServerMapRec</emphasis> - structure referenced by the <emphasis> -server</emphasis> - member of the <emphasis> -xkb</emphasis> - parameter, and sets the <emphasis> -server</emphasis> - member to <emphasis> -NULL.</emphasis> +The +<function>XkbFreeServerMap</function> +function frees the specified components of server map in the +<structname>XkbDescRec</structname> +structure specified by the +<parameter>xkb</parameter> +parameter and sets the corresponding structure component values to +<symbol>NULL</symbol>. +The +<parameter>which</parameter> +parameter specifies a combination of the server map masks and is a bitwise +inclusive OR of the masks listed in +<link linkend="table14.4">Table 14.4</link>. If +<parameter>free_all</parameter> +is +<symbol>True</symbol>, +<parameter>which</parameter> +is ignored and +<function>XkbFreeServerMap</function> +frees every non- +<symbol>NULL</symbol> +structure component in the server map, frees the +<structname>XkbServerMapRec</structname> +structure referenced by the +<structfield>server</structfield> +member of the +<parameter>xkb</parameter> +parameter, and sets the +<structfield>server</structfield> +member to +<symbol>NULL</symbol>. </para> </sect2> diff --git a/libX11/specs/XKB/ch15.xml b/libX11/specs/XKB/ch15.xml index b12bc8cf3..a6f3f7c68 100644 --- a/libX11/specs/XKB/ch15.xml +++ b/libX11/specs/XKB/ch15.xml @@ -1,6 +1,14 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Xkb_Client_Keyboard_Mapping'> <title>Xkb Client Keyboard Mapping</title> +<indexterm zone="Xkb_Client_Keyboard_Mapping"> +<primary>client map</primary></indexterm> +<indexterm zone="Xkb_Client_Keyboard_Mapping"> +<primary>map</primary><secondary>client</secondary></indexterm> + <para> The Xkb client map for a keyboard is the collection of information a client needs to interpret key events from the keyboard. It contains a global list of @@ -10,14 +18,16 @@ bound to a key and the rules to be used to interpret those symbols. <para> -Figure 15.1 shows the relationships between elements in the client map: +<link linkend="figure15.1">Figure 15.1</link> shows the relationships between elements in the client map: </para> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-15.svg"/> - </imageobject> -<caption>Xkb Client Map</caption> - </mediaobject> +<figure id='figure15.1'> + <title>Xkb Client Map</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-15.svg"/> + </imageobject> + </mediaobject> +</figure> <!-- @@ -27,207 +37,203 @@ Xkb Client Map</H5> <sect1 id='The_XkbClientMapRec_Structure'> <title>The XkbClientMapRec Structure</title> - -<para> -The <emphasis> -map </emphasis> -field of the complete Xkb keyboard description (see section 6.1) is a pointer -to the Xkb client map, which is of type <emphasis> -XkbClientMapRec</emphasis> -: -</para> - -<para><programlisting> -typedef struct { /* Client Map */ - unsigned char size_types; /* # occupied entries in <emphasis> types</emphasis> */ - unsigned char num_types; /* # entries in <emphasis>types</emphasis> */ - XkbKeyTypePtr types; /* vector of key types used by this keymap */ - unsigned short size_syms; /* length of the <emphasis>syms</emphasis> array */ - unsigned short num_syms; /* # entries in <emphasis>syms</emphasis> */ - KeySym * syms; /* linear 2d tables of keysyms, 1 per key */ - XkbSymMapPtr key_sym_map; /* 1 per keycode, maps keycode to <emphasis>syms</emphasis> */ - unsigned char * modmap; /* 1 per keycode, real mods bound to key */ -} <emphasis>XkbClientMapRec</emphasis>, *XkbClientMapPtr; +<indexterm significance="preferred" zone="The_XkbClientMapRec_Structure"> +<primary><structname>XkbClientMapRec</structname></primary></indexterm> + +<para> +The +<structfield>map</structfield> +field of the complete Xkb keyboard description (see <link linkend="The_XkbDescRec_Structure">section 6.1</link>) is a pointer +to the Xkb client map, which is of type +<structname>XkbClientMapRec</structname>: + +<programlisting> +typedef struct { /* Client Map */ + unsigned char size_types; /* # occupied entries in <structfield>types</structfield> */ + unsigned char num_types; /* # entries in <structfield>types</structfield> */ + XkbKeyTypePtr types; /* vector of key types used by this keymap */ + unsigned short size_syms; /* length of the <structfield>syms</structfield> array */ + unsigned short num_syms; /* # entries in <structfield>syms</structfield> */ + KeySym * syms; /* linear 2d tables of keysyms, 1 per key */ + XkbSymMapPtr key_sym_map; /* 1 per keycode, maps keycode to <structfield>syms</structfield> */ + unsigned char * modmap; /* 1 per keycode, real mods bound to key */ +} <structname>XkbClientMapRec</structname>, *XkbClientMapPtr; </programlisting></para> <para> -The following sections describe each of the elements of the <emphasis> -XkbClientMapRec</emphasis> - structure in more detail. +The following sections describe each of the elements of the +<structname>XkbClientMapRec</structname> +structure in more detail. </para> </sect1> <sect1 id='Key_Types'> <title>Key Types</title> +<indexterm significance="preferred" zone="Key_Types"> +<primary><structname>XkbKeyTypeRec</structname></primary></indexterm> +<indexterm significance="preferred" zone="Key_Types"> +<primary><structname>XkbKTMapEntryRec</structname></primary></indexterm> <para> Key types are used to determine the shift level of a key given the current state of the keyboard. The set of all possible key types for the Xkb keyboard -description are held in the <emphasis> -types</emphasis> - field of the client map, whose total size is stored in <emphasis> -size_types</emphasis> -, and whose total number of valid entries is stored in <emphasis> -num_types</emphasis> -. Key types are defined using the following structures: -</para> - -<para><programlisting> -typedef struct { /* Key Type */ - XkbModsRec mods; /* modifiers used to compute shift - level */ - unsigned char num_levels; /* total # shift levels, do not - modify directly */ - unsigned char map_count; /* # entries in <emphasis>map</emphasis>, - <emphasis> preserve</emphasis> - (if non-<emphasis> NULL</emphasis>) */ - XkbKTMapEntryPtr map; /* vector of modifiers for each - shift level */ - XkbModsPtr preserve; /* mods to preserve for corresponding - <emphasis>map</emphasis> entry */ - Atom name; /* name of key type */ - Atom * level_names; /* array of names of each shift level */ -} <emphasis>XkbKeyTypeRec</emphasis>, *XkbKeyTypePtr; -</programlisting></para> - -<para><programlisting> -typedef struct { /* Modifiers for a key type */ - Bool active; /* <emphasis> True</emphasis> => entry - active when determining shift level */ - unsigned char level; /* shift level if modifiers match <emphasis> mods</emphasis> */ - XkbModsRec mods; /* mods needed for this level to be - selected */ -} <emphasis>XkbKTMapEntryRec</emphasis>,*XkbKTMapEntryPtr; +description are held in the +<structfield>types</structfield> +field of the client map, whose total size is stored in +<structfield>size_types</structfield>, +and whose total number of valid entries is stored in +<structfield>num_types</structfield>. +Key types are defined using the following structures: + +<programlisting> +typedef struct { /* Key Type */ + XkbModsRec mods; /* modifiers used to compute shift level */ + unsigned char num_levels; /* total # shift levels, do not + modify directly */ + unsigned char map_count; /* # entries in <structfield>map</structfield>, <structfield>preserve</structfield> + (if non-<symbol>NULL</symbol>) */ + XkbKTMapEntryPtr map; /* vector of modifiers for each + shift level */ + XkbModsPtr preserve; /* mods to preserve for + corresponding <structfield>map</structfield> entry */ + Atom name; /* name of key type */ + Atom * level_names; /* array of names of each shift level */ +} <structname>XkbKeyTypeRec</structname>, *XkbKeyTypePtr; +</programlisting> + +<programlisting> +typedef struct { /* Modifiers for a key type */ + Bool active; /* <symbol>True</symbol> ⇒ entry active when + determining shift level */ + unsigned char level; /* shift level if modifiers match <structfield>mods</structfield> */ + XkbModsRec mods; /* mods needed for this level to be + selected */ +} <structname>XkbKTMapEntryRec</structname>, *XkbKTMapEntryPtr; </programlisting></para> <para> -The <emphasis> -mods</emphasis> - field of a key type is an <emphasis> -XkbModsRec</emphasis> - (see section 7.2) specifying the modifiers the key type uses when calculating +The +<structfield>mods</structfield> +field of a key type is an +<structname>XkbModsRec</structname> +(see <link linkend="Modifier_Definitions">section 7.2</link>) specifying the modifiers the key type uses when calculating the shift level, and can be composed of both the core modifiers and virtual modifiers. To set the modifiers associated with a key type, modify the -<emphasis> -real_mods</emphasis> - and <emphasis> -vmods</emphasis> - fields of the <emphasis> -mods</emphasis> - <emphasis> -XkbModsRec</emphasis> - accordingly. The <emphasis> -mask</emphasis> - field of the <emphasis> -XkbModsRec</emphasis> - is reserved for use by Xkb and is calculated from the <emphasis> -real_mods</emphasis> - and <emphasis> -vmods</emphasis> - fields. -</para> - - -<para> -The <emphasis> -num_levels</emphasis> - field holds the total number of shift levels for the key type. Xkb uses -<emphasis> -num_levels</emphasis> - to ensure the array of symbols bound to a key is large enough. Do not modify -<emphasis> -num_levels</emphasis> - directly to change the number if shift levels for a key type. Instead, use -<emphasis> -XkbResizeKeyType</emphasis> - (see section 15.2.3). -</para> - - -<para> -The <emphasis> -map</emphasis> - field is a vector of <emphasis> -XkbKTMapEntryRec</emphasis> - structures, with <emphasis> -map_count</emphasis> - entries, that specify the modifier combinations for each possible shift level. -Each map entry contains an <emphasis> -active</emphasis> - field, a <emphasis> -mods</emphasis> - field, and a <emphasis> -level</emphasis> - field. The <emphasis> -active</emphasis> - field determines whether the modifier combination listed in the <emphasis> -mods</emphasis> - field should be considered when determining shift level. If <emphasis> -active</emphasis> - is <emphasis> -False</emphasis> -, this <emphasis> -map</emphasis> - entry is ignored. If <emphasis> -active</emphasis> - is <emphasis> -True</emphasis> -, the <emphasis> -level</emphasis> - field of the <emphasis> -map </emphasis> +<structfield>real_mods</structfield> +and +<structfield>vmods</structfield> +fields of the +<structfield>mods</structfield> +<structname>XkbModsRec</structname> +accordingly. The +<structfield>mask</structfield> +field of the +<structname>XkbModsRec</structname> +is reserved for use by Xkb and is calculated from the +<structfield>real_mods</structfield> +and +<structfield>vmods</structfield> +fields. +</para> + + +<para> +The +<structfield>num_levels</structfield> +field holds the total number of shift levels for the key type. Xkb uses +<structfield>num_levels</structfield> +to ensure the array of symbols bound to a key is large enough. Do not modify +<structfield>num_levels</structfield> +directly to change the number if shift levels for a key type. Instead, use +<function>XkbResizeKeyType</function> +(see <link linkend="Changing_the_Number_of_Levels_in_a_Key_Type">section 15.2.3</link>). +</para> + + +<para> +The +<structfield>map</structfield> +field is a vector of +<structname>XkbKTMapEntryRec</structname> +structures, with +<structfield>map_count</structfield> +entries, that specify the modifier combinations for each possible shift level. +Each map entry contains an +<structfield>active</structfield> +field, a +<structfield>mods</structfield> +field, and a +<structfield>level</structfield> +field. The +<structfield>active</structfield> +field determines whether the modifier combination listed in the +<structfield>mods</structfield> +field should be considered when determining shift level. If +<structfield>active</structfield> +is +<symbol>False</symbol>, +this +<structfield>map</structfield> +entry is ignored. If +<structfield>active</structfield> +is +<symbol>True</symbol>, +the +<structfield>level</structfield> +field of the +<structfield>map</structfield> entry specifies the shift level to use when the current modifier combination -matches the combination specified in the <emphasis> -mods</emphasis> - field of the <emphasis> -map</emphasis> - entry. +matches the combination specified in the +<structfield>mods</structfield> +field of the +<structfield>map</structfield> +entry. </para> <para> -Any combination of modifiers not explicitly listed somewhere in the <emphasis> -map</emphasis> - yields shift level one. In addition, <emphasis> -map</emphasis> - entries specifying unbound virtual modifiers are not considered. +Any combination of modifiers not explicitly listed somewhere in the +<structfield>map</structfield> +yields shift level one. In addition, +<structfield>map</structfield> +entries specifying unbound virtual modifiers are not considered. </para> <para> -Any modifiers specified in <emphasis> -mods</emphasis> - are normally <emphasis> -consumed</emphasis> - by <emphasis> -XkbTranslateKeyCode</emphasis> - (see section 12.1.3). For those rare occasions 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> - member of a key type is not <emphasis> -NULL</emphasis> -, it represents a list of modifiers where each entry corresponds directly to -one of the key type’s <emphasis> -map</emphasis> -. Each entry lists the modifiers that should <emphasis> -not</emphasis> - be consumed if the matching map entry is used to determine shift level. +Any modifiers specified in +<structfield>mods</structfield> +are normally +<emphasis>consumed</emphasis> +by +<function>XkbTranslateKeyCode</function> +(see <link linkend="X_Library_Functions_Affected_by_Xkb">section 12.1.3</link>). For those rare occasions a modifier +<emphasis>should</emphasis> +be considered despite having been used to look up a symbol, key types include +an optional +<structfield>preserve</structfield> +field. If a +<structfield>preserve</structfield> +member of a key type is not +<symbol>NULL</symbol>, +it represents a list of modifiers where each entry corresponds directly to +one of the key type’s +<structfield>map</structfield>. +Each entry lists the modifiers that should +<emphasis>not</emphasis> +be consumed if the matching map entry is used to determine shift level. </para> <para> -Each shift level has a name and these names are held in the <emphasis> -level_names</emphasis> - array, whose length is <emphasis> -num_levels</emphasis> -. The type itself also has a name, which is held in the <emphasis> -name</emphasis> - field. +Each shift level has a name and these names are held in the +<structfield>level_names</structfield> +array, whose length is +<structfield>num_levels</structfield>. +The type itself also has a name, which is held in the +<structfield>name</structfield> +field. </para> @@ -238,7 +244,7 @@ keyboard mappings in the server database is not specified by the Xkb extension, although this format is one possible example): </para> -<table frame='topbot'> +<table id='table15.1' frame='topbot'> <title>Example Key Type</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -281,7 +287,7 @@ although this format is one possible example): </row> <row> <entry><emphasis>preserve[None]= None;</emphasis></entry> - <entry>Xkb->map->types[i].perserve[0]</entry> + <entry>Xkb->map->types[i].preserve[0]</entry> </row> <row> <entry>preserve[Lock]= Lock;</entry> @@ -320,79 +326,76 @@ although this format is one possible example): </table> <para> -The <emphasis> -name</emphasis> - of the example key type is "ALPHATHREE," and the modifiers it pays attention -to are <emphasis> -Shift</emphasis> -, <emphasis> -Lock</emphasis> -, and the virtual modifier <emphasis> -LevelThree</emphasis> -. There are three shift levels. The name of shift level one is "Base," the name +The +<structfield>name</structfield> +of the example key type is "ALPHATHREE," and the modifiers it pays attention +to are +<symbol>Shift</symbol>, +<symbol>Lock</symbol>, +and the virtual modifier +<emphasis>LevelThree</emphasis>. +There are three shift levels. The name of shift level one is "Base," the name of shift level two is "Caps," and the name of shift level three is "Level3." </para> <para> -Given the combination of the <emphasis> -map</emphasis> - and <emphasis> -preserve</emphasis> - specifications, there are five <emphasis> -map</emphasis> - entries. The first map entry specifies that shift level one is to be used if -no modifiers are set. The second entry specifies the <emphasis> -Lock</emphasis> - modifier alone also yields shift level one. The third entry specifies the -<emphasis> -Shift</emphasis> - modifier alone yields shift level two. The fourth and fifth entries specify -that the virtual <emphasis> -LevelThree</emphasis> - modifier alone, or in combination with the <emphasis> -Shift</emphasis> - modifier, yields shift level three. +Given the combination of the +<structfield>map</structfield> +and +<structfield>preserve</structfield> +specifications, there are five +<structfield>map</structfield> +entries. The first map entry specifies that shift level one is to be used if +no modifiers are set. The second entry specifies the +<symbol>Lock</symbol> +modifier alone also yields shift level one. The third entry specifies the +<symbol>Shift</symbol> +modifier alone yields shift level two. The fourth and fifth entries specify +that the virtual +<emphasis>LevelThree</emphasis> +modifier alone, or in combination with the +<symbol>Shift</symbol> +modifier, yields shift level three. </para> <note><para>Shift level three can be reached only if the virtual modifier -<emphasis> -LevelThree</emphasis> - is bound to a real modifier (see section 16.4). If <emphasis> -LevelThree</emphasis> - is not bound to a real modifier, the <emphasis> -map</emphasis> - entries associated with it are ignored.</para></note> - -<para> -Because the <emphasis> -Lock</emphasis> - modifier is to be preserved for further event processing, the <emphasis> -preserve</emphasis> - list is not <emphasis> -NULL</emphasis> - and parallels the <emphasis> -map</emphasis> - list. All <emphasis> -preserve</emphasis> - entries, except for the one corresponding to the <emphasis> -map</emphasis> - entry that specifies the <emphasis> -Lock </emphasis> -modifier, do not list any modifiers. For the <emphasis> -map</emphasis> - entry that specifies the <emphasis> -Lock</emphasis> - modifier, the corresponding <emphasis> -preserve</emphasis> - list entry lists the <emphasis> -Lock</emphasis> - modifier, meaning do not consume the <emphasis> -Lock</emphasis> - modifier. In this particular case, the preserved modifier is passed to Xlib -translation functions and causes them to notice that the <emphasis> -Lock</emphasis> - modifier is set; consequently, the Xlib functions apply the appropriate +<emphasis>LevelThree</emphasis> +is bound to a real modifier (see <link linkend="Virtual_Modifier_Mapping">section 16.4</link>). If +<emphasis>LevelThree</emphasis> +is not bound to a real modifier, the +<structfield>map</structfield> +entries associated with it are ignored.</para></note> + +<para> +Because the +<symbol>Lock</symbol> +modifier is to be preserved for further event processing, the +<structfield>preserve</structfield> +list is not +<symbol>NULL</symbol> +and parallels the +<structfield>map</structfield> +list. All +<structfield>preserve</structfield> +entries, except for the one corresponding to the +<structfield>map</structfield> +entry that specifies the +<symbol>Lock</symbol> +modifier, do not list any modifiers. For the +<structfield>map</structfield> +entry that specifies the +<symbol>Lock</symbol> +modifier, the corresponding +<structfield>preserve</structfield> +list entry lists the +<symbol>Lock</symbol> +modifier, meaning do not consume the +<symbol>Lock</symbol> +modifier. In this particular case, the preserved modifier is passed to Xlib +translation functions and causes them to notice that the +<symbol>Lock</symbol> +modifier is set; consequently, the Xlib functions apply the appropriate capitalization rules to the symbol. Because this preserve entry is set only for a modifier that yields shift level one, the capitalization occurs only for level-one symbols. @@ -403,26 +406,26 @@ level-one symbols. <title>The Canonical Key Types</title> <para> -Xkb allows up to <emphasis> -XkbMaxKeyTypes</emphasis> - (255) key types to be defined, but requires at least <emphasis> -XkbNumRequiredTypes</emphasis> - (4) predefined types to be in a key map. These predefined key types are +Xkb allows up to +<symbol>XkbMaxKeyTypes</symbol> +(255) key types to be defined, but requires at least +<symbol>XkbNumRequiredTypes</symbol> +(4) predefined types to be in a key map. These predefined key types are referred to as the canonical key types and describe the types of keys available on most keyboards. The definitions for the canonical key types are held in the -first <emphasis> -XkbNumRequiredTypes</emphasis> - entries of the <emphasis> -types</emphasis> - field of the client map and are indexed using the following constants: -</para> - -<para><programlisting> - <emphasis>XkbOneLevelIndex</emphasis> - <emphasis>XkbTwoLevelIndex</emphasis> - <emphasis>XkbAlphabeticIndex</emphasis> - <emphasis>XkbKeypadIndex</emphasis> -</programlisting></para> +first +<symbol>XkbNumRequiredTypes</symbol> +entries of the +<structfield>types</structfield> +field of the client map and are indexed using the following constants: + + <simplelist type='vert' columns='1'> + <member><symbol>XkbOneLevelIndex</symbol></member> + <member><symbol>XkbTwoLevelIndex</symbol></member> + <member><symbol>XkbAlphabeticIndex</symbol></member> + <member><symbol>XkbKeypadIndex</symbol></member> + </simplelist> +</para> <sect3 id='ONE_LEVEL'> <title>ONE_LEVEL</title> @@ -435,18 +438,18 @@ following: </para> <literallayout> -type "ONE_LEVEL" { - modifiers = None; - map[None]= Level1; - level_name[Level1]= "Any"; -}; + type "ONE_LEVEL" { + modifiers = None; + map[None]= Level1; + level_name[Level1]= "Any"; + }; </literallayout> <para> -The description of the ONE_LEVEL key type is stored in the <emphasis> -types</emphasis> -[<emphasis> -XkbOneLevelIndex</emphasis> +The description of the ONE_LEVEL key type is stored in the +<structfield>types</structfield> +[ +<symbol>XkbOneLevelIndex</symbol> ] entry of the client key map. </para> @@ -458,28 +461,28 @@ XkbOneLevelIndex</emphasis> <para> The TWO_LEVEL key type describes groups that consist of two symbols but are neither alphabetic nor numeric keypad keys. The default TWO_LEVEL type uses -only the <emphasis> -Shift</emphasis> - modifier. It returns shift level two if <emphasis> -Shift</emphasis> - is set, and level one if it is not. A symbolic representation of this key type +only the +<symbol>Shift</symbol> +modifier. It returns shift level two if +<symbol>Shift</symbol> +is set, and level one if it is not. A symbolic representation of this key type could look like the following: </para> <literallayout> -type "TWO_LEVEL" { - modifiers = Shift; - map[Shift]= Level2; - level_name[Level1]= "Base"; - level_name[Level2]= "Shift"; -}; + type "TWO_LEVEL" { + modifiers = Shift; + map[Shift]= Level2; + level_name[Level1]= "Base"; + level_name[Level2]= "Shift"; + }; </literallayout> <para> -The description of the TWO_LEVEL key type is stored in the <emphasis> -types</emphasis> -[<emphasis> -XkbTwoLevelIndex</emphasis> +The description of the TWO_LEVEL key type is stored in the +<structfield>types</structfield> +[ +<symbol>XkbTwoLevelIndex</symbol> ] entry of the client key map. </para> @@ -491,49 +494,49 @@ XkbTwoLevelIndex</emphasis> <para> The ALPHABETIC key type describes groups consisting of two symbols: the lowercase form of a symbol followed by the uppercase form of the same symbol. -The default ALPHABETIC type implements locale-sensitive "Shift cancels -CapsLock" behavior using both the <emphasis> -Shift</emphasis> - and <emphasis> -Lock</emphasis> - modifiers as follows: +The default ALPHABETIC type implements locale-sensitive <quote>Shift cancels +CapsLock</quote> behavior using both the +<symbol>Shift</symbol> +and +<symbol>Lock</symbol> +modifiers as follows: </para> <itemizedlist> <listitem> <para> -If <emphasis> -Shift</emphasis> - and <emphasis> -Lock</emphasis> - are both set, the default ALPHABETIC type yields level one. +If +<symbol>Shift</symbol> +and +<symbol>Lock</symbol> +are both set, the default ALPHABETIC type yields level one. </para> </listitem> <listitem> <para> -If <emphasis> -Shift</emphasis> - alone is set, it yields level two. +If +<symbol>Shift</symbol> +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 so Xlib notices and applies the appropriate capitalization rules. The +If +<symbol>Lock</symbol> +alone is set, it yields level one, but preserves the +<symbol>Lock</symbol> +modifier so Xlib notices and applies the appropriate capitalization rules. The Xlib functions are locale-sensitive and apply different capitalization rules for different locales. </para> </listitem> <listitem> <para> -If neither <emphasis> -Shift</emphasis> - nor <emphasis> -Lock</emphasis> - is set, it yields level one. +If neither +<symbol>Shift</symbol> +nor +<symbol>Lock</symbol> +is set, it yields level one. </para> </listitem> </itemizedlist> @@ -543,20 +546,20 @@ A symbolic representation of this key type could look like the following: </para> <literallayout> -type "ALPHABETIC" { - modifiers = Shift+Lock; - map[Shift]= Level2; - preserve[Lock]= Lock; - level_name[Level1]= "Base"; - level_name[Level2]= "Caps"; -}; + type "ALPHABETIC" { + modifiers = Shift+Lock; + map[Shift]= Level2; + preserve[Lock]= Lock; + level_name[Level1]= "Base"; + level_name[Level2]= "Caps"; + }; </literallayout> <para> -The description of the ALPHABETIC key type is stored in the <emphasis> -types</emphasis> -[<emphasis> -XkbAlphabeticIndex</emphasis> +The description of the ALPHABETIC key type is stored in the +<structfield>types</structfield> +[ +<symbol>XkbAlphabeticIndex</symbol> ] entry of the client key map. </para> @@ -568,44 +571,45 @@ XkbAlphabeticIndex</emphasis> <para> The KEYPAD key type describes groups that consist of two symbols, at least one of which is a numeric keypad symbol. The numeric keypad symbol is assumed to -reside at level two. The default KEYPAD key type implements "Shift cancels -NumLock" behavior using the Shift modifier and the real modifier bound to the -virtual modifier named "NumLock," known as the <emphasis> -NumLock</emphasis> - modifier, as follows: +reside at level two. The default KEYPAD key type implements +<quote>Shift cancels NumLock</quote> behavior using the Shift modifier +and the real modifier bound to the virtual modifier named +<quote>NumLock</quote>, known as the +<emphasis>NumLock</emphasis> +modifier, as follows: </para> <itemizedlist> <listitem> <para> -If <emphasis> -Shift</emphasis> - and <emphasis> -NumLock</emphasis> - are both set, the default KEYPAD type yields level one. +If +<symbol>Shift</symbol> +and +<emphasis>NumLock</emphasis> +are both set, the default KEYPAD type yields level one. </para> </listitem> <listitem> <para> -If <emphasis> -Shift</emphasis> - alone is set, it yields level two. +If +<symbol>Shift</symbol> +alone is set, it yields level two. </para> </listitem> <listitem> <para> -If <emphasis> -NumLock</emphasis> - alone is set, it yields level two. +If +<emphasis>NumLock</emphasis> +alone is set, it yields level two. </para> </listitem> <listitem> <para> -If neither <emphasis> -Shift</emphasis> - nor <emphasis> -NumLock</emphasis> - is set, it yields level one. +If neither +<symbol>Shift</symbol> +nor +<emphasis>NumLock</emphasis> +is set, it yields level one. </para> </listitem> </itemizedlist> @@ -615,22 +619,22 @@ A symbolic representation of this key type could look like the following: </para> <literallayout> -type "KEYPAD" { - modifiers = Shift+NumLock; - map[None]= Level1; - map[Shift]= Level2; - map[NumLock]= Level2; - map[Shift+NumLock]= Level1; - level_name[Level1]= "Base"; - level_name[Level2]= "Caps"; -}; + type "KEYPAD" { + modifiers = Shift+NumLock; + map[None]= Level1; + map[Shift]= Level2; + map[NumLock]= Level2; + map[Shift+NumLock]= Level1; + level_name[Level1]= "Base"; + level_name[Level2]= "Caps"; + }; </literallayout> <para> -The description of the KEYPAD key type is stored in the <emphasis> -types</emphasis> -[<emphasis> -XkbKeypadIndex</emphasis> +The description of the KEYPAD key type is stored in the +<structfield>types</structfield> +[ +<symbol>XkbKeypadIndex</symbol> ] entry of the client key map. </para> @@ -641,101 +645,104 @@ XkbKeypadIndex</emphasis> <para> To set the definitions of the canonical key types in a client map to their -default values, use <emphasis> -XkbInitCanonicalKeyTypes.</emphasis> -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbInitCanonicalKeyTypes</emphasis> -(<emphasis> -xkb, which, keypadVMod</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description containing client map to initialize */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -which</emphasis> -; /* mask of types to initialize */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -keypadVMod</emphasis> -; /* index of NumLock virtual modifier */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbInitCanonicalKeyTypes</emphasis> - initializes the first <emphasis> -XkbNumRequiredTypes</emphasis> - key types of the keyboard specified by the <emphasis> -xkb</emphasis> - parameter to their default values. The <emphasis> -which</emphasis> - parameter specifies what canonical key types to initialize and is a bitwise -inclusive OR of the following masks: <emphasis> -XkbOneLevelMask</emphasis> -, <emphasis> -XkbTwoLevelMask</emphasis> -, <emphasis> -XkbAlphabeticMask</emphasis> -, and <emphasis> -XkbKeypadMask</emphasis> -. Only those canonical types specified by the <emphasis> -which</emphasis> - mask are initialized. -</para> - - -<para> -If <emphasis> -XkbKeypadMask</emphasis> - is set in the <emphasis> -which</emphasis> - parameter, <emphasis> -XkbInitCanonicalKeyTypes</emphasis> - looks up the <emphasis> -NumLock</emphasis> - named virtual modifier to determine which virtual modifier to use when -initializing the KEYPAD key type. If the <emphasis> -NumLock</emphasis> - virtual modifier does not exist, <emphasis> -XkbInitCanonicalKeyTypes</emphasis> - creates it. -</para> - - -<para> -<emphasis> -XkbInitCanonicalKeyTypes</emphasis> - normally returns Success. It returns <emphasis> -BadAccess</emphasis> - if the Xkb extension has not been properly initialized, and <emphasis> -BadAccess</emphasis> - if the <emphasis> -xkb</emphasis> - parameter is not valid. +default values, use +<function>XkbInitCanonicalKeyTypes</function>. +</para> + +<indexterm significance="preferred" zone="XkbInitCanonicalKeyTypes"><primary><function>XkbInitCanonicalKeyTypes</function></primary></indexterm> +<funcsynopsis id="XkbInitCanonicalKeyTypes"> + <funcprototype> + <funcdef>Status <function>XkbInitCanonicalKeyTypes</function></funcdef> +<!-- ( +<parameter>xkb, which, keypadVMod</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>int <parameter>keypadVMod</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description containing client map to initialize + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of types to initialize + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keypadVMod</parameter> + </term> + <listitem> + <para> + index of NumLock virtual modifier + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbInitCanonicalKeyTypes</function> +initializes the first +<symbol>XkbNumRequiredTypes</symbol> +key types of the keyboard specified by the +<parameter>xkb</parameter> +parameter to their default values. The +<parameter>which</parameter> +parameter specifies what canonical key types to initialize and is a bitwise +inclusive OR of the following masks: +<symbol>XkbOneLevelMask</symbol>, +<symbol>XkbTwoLevelMask</symbol>, +<symbol>XkbAlphabeticMask</symbol>, +and +<symbol>XkbKeypadMask</symbol>. +Only those canonical types specified by the +<parameter>which</parameter> +mask are initialized. +</para> + + +<para> +If +<symbol>XkbKeypadMask</symbol> +is set in the +<parameter>which</parameter> +parameter, +<function>XkbInitCanonicalKeyTypes</function> +looks up the +<emphasis>NumLock</emphasis> +named virtual modifier to determine which virtual modifier to use when +initializing the KEYPAD key type. If the +<emphasis>NumLock</emphasis> +virtual modifier does not exist, +<function>XkbInitCanonicalKeyTypes</function> +creates it. +</para> + + +<para> +<function>XkbInitCanonicalKeyTypes</function> +normally returns Success. It returns +<errorname>BadAccess</errorname> +if the Xkb extension has not been properly initialized, and +<errorname>BadAccess</errorname> +if the +<parameter>xkb</parameter> +parameter is not valid. </para> @@ -747,92 +754,97 @@ xkb</emphasis> <para> To obtain the list of available key types in the server’s keyboard mapping, -use <emphasis> -XkbGetKeyTypes</emphasis> -. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetKeyTypes</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - num</emphasis> -,<emphasis> - xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - first</emphasis> -; /* index to first type to get, 0 => 1st type */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -num</emphasis> -; /* number of key types to be returned */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description containing client map to update */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> -<note><para><emphasis> -XkbGetKeyTypes</emphasis> - is used to obtain descriptions of the key types themselves, not the key types +use +<function>XkbGetKeyTypes</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetKeyTypes"><primary><function>XkbGetKeyTypes</function></primary></indexterm> +<funcsynopsis id="XkbGetKeyTypes"> + <funcprototype> + <funcdef>Status <function>XkbGetKeyTypes</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>first</parameter>, +<parameter>num</parameter>, +<parameter>xkb</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>first</parameter></paramdef> + <paramdef>unsigned int <parameter>num</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + index to first type to get, 0 ⇒ 1st type + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num</parameter> + </term> + <listitem> + <para> + number of key types to be returned + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description containing client map to update + </para> + </listitem> + </varlistentry> +</variablelist> +<note><para> +<function>XkbGetKeyTypes</function> +is used to obtain descriptions of the key types themselves, not the key types bound to individual keys. To obtain the key types bound to an individual key, -refer to the <emphasis> -key_sym_map</emphasis> - field of the client map (see section 15.3.1).</para></note> +refer to the +<structfield>key_sym_map</structfield> +field of the client map (see <link linkend="Per_Key_Key_Type_Indices">section 15.3.1</link>).</para></note> <para> -<emphasis> -XkbGetKeyTypes</emphasis> - queries the server for the desired types, waits for a reply, and returns the -desired types in the <emphasis> -xkb->map->types</emphasis> -. If successful, it returns Success. +<function>XkbGetKeyTypes</function> +queries the server for the desired types, waits for a reply, and returns the +desired types in the +<structfield>xkb->map->types</structfield>. +If successful, it returns Success. </para> <para> -<emphasis> -XkbGetKeyTypes</emphasis> - returns <emphasis> -BadAccess</emphasis> - if the Xkb extension has not been properly initialized and <emphasis> -BadValue</emphasis> - if the combination of <emphasis> -first</emphasis> - and <emphasis> -num</emphasis> - results in numbers out of valid range. +<function>XkbGetKeyTypes</function> +returns +<errorname>BadAccess</errorname> +if the Xkb extension has not been properly initialized and +<errorname>BadValue</errorname> +if the combination of +<parameter>first</parameter> +and +<parameter>num</parameter> +results in numbers out of valid range. </para> @@ -841,169 +853,170 @@ num</emphasis> <title>Changing the Number of Levels in a Key Type</title> <para> -To change the number of levels in a key type, use <emphasis> -XkbResizeKeyType</emphasis> -. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbResizeKeyType</emphasis> -(<emphasis> -xkb</emphasis> -,<emphasis> - type_ndx</emphasis> -,<emphasis> - map_count</emphasis> -,<emphasis> - want_preserve</emphasis> -,<emphasis> - new_num_lvls</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr<emphasis> - xkb</emphasis> -; /* keyboard description containing client map to update */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - type_ndx</emphasis> -; /* index in xkb->map->types of type to change */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -map_count</emphasis> -; /* total # of map entries needed for the type */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> -want_preserve</emphasis> -; /* <emphasis> -True</emphasis> - => list of preserved modifiers is necessary */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - new_num_lvls</emphasis> -; /* new max # of levels for type */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbResizeKeyType</emphasis> - changes the type specified by <emphasis> -xkb</emphasis> --><emphasis> -map->types</emphasis> -[<emphasis> -type_ndx</emphasis> +To change the number of levels in a key type, use +<function>XkbResizeKeyType</function>. +</para> + +<indexterm significance="preferred" zone="XkbResizeKeyType"><primary><function>XkbResizeKeyType</function></primary></indexterm> +<funcsynopsis id="XkbResizeKeyType"> + <funcprototype> + <funcdef>Status <function>XkbResizeKeyType</function></funcdef> +<!-- ( +<parameter>xkb</parameter>, +<parameter>type_ndx</parameter>, +<parameter>map_count</parameter>, +<parameter>want_preserve</parameter>, +<parameter>new_num_lvls</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>int <parameter>type_ndx</parameter></paramdef> + <paramdef>int <parameter>map_count</parameter></paramdef> + <paramdef>Bool <parameter>want_preserve</parameter></paramdef> + <paramdef>int <parameter>new_num_lvls</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description containing client map to update + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>type_ndx</parameter> + </term> + <listitem> + <para> + index in xkb->map->types of type to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>map_count</parameter> + </term> + <listitem> + <para> + total # of map entries needed for the type + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>want_preserve</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> + ⇒ list of preserved modifiers is necessary + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>new_num_lvls</parameter> + </term> + <listitem> + <para> + new max # of levels for type + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbResizeKeyType</function> +changes the type specified by +<parameter>xkb</parameter>-><structfield>map->types</structfield> +[ +<parameter>type_ndx</parameter> ], and reallocates the symbols and actions bound to all keys that use the type, -if necessary. <emphasis> -XkbResizeKeyType</emphasis> - updates only the local copy of the types in <emphasis> -xkb</emphasis> -; to update the server’s copy for the physical device, use <emphasis> -XkbSetMap</emphasis> - or <emphasis> -XkbChangeMap</emphasis> - after calling <emphasis> -XkbResizeKeyType</emphasis> -. -</para> - - -<para> -The <emphasis> -map_count</emphasis> - parameter specifies the total number of map entries needed for the type, and -can be zero or greater. If <emphasis> -map_count</emphasis> - is zero, <emphasis> -XkbResizeKeyType</emphasis> - frees the existing <emphasis> -map</emphasis> - and <emphasis> -preserve</emphasis> - entries for the type if they exist and sets them to <emphasis> -NULL</emphasis> -. -</para> - - -<para> -The <emphasis> -want_preserve</emphasis> - parameter specifies whether a <emphasis> -preserve</emphasis> - list for the key should be created. If <emphasis> -want_preserve</emphasis> - is <emphasis> -True</emphasis> -, the <emphasis> -preserve</emphasis> - list with <emphasis> -map_count</emphasis> - entries is allocated or reallocated if it already exists. Otherwise, if -<emphasis> -want_preserve</emphasis> - is <emphasis> -False</emphasis> -, the <emphasis> -preserve</emphasis> - field is freed if necessary and set to <emphasis> -NULL</emphasis> -. -</para> - - -<para> -The <emphasis> -new_num_lvls</emphasis> - parameter specifies the new maximum number of shift levels for the type and is +if necessary. +<function>XkbResizeKeyType</function> +updates only the local copy of the types in +<parameter>xkb</parameter>; +to update the server’s copy for the physical device, use +<function>XkbSetMap</function> +or +<function>XkbChangeMap</function> +after calling +<function>XkbResizeKeyType</function>. +</para> + + +<para> +The +<parameter>map_count</parameter> +parameter specifies the total number of map entries needed for the type, and +can be zero or greater. If +<parameter>map_count</parameter> +is zero, +<function>XkbResizeKeyType</function> +frees the existing +<structfield>map</structfield> +and +<structfield>preserve</structfield> +entries for the type if they exist and sets them to +<symbol>NULL</symbol>. +</para> + + +<para> +The +<parameter>want_preserve</parameter> +parameter specifies whether a +<structfield>preserve</structfield> +list for the key should be created. If +<parameter>want_preserve</parameter> +is +<symbol>True</symbol>, +the +<structfield>preserve</structfield> +list with +<parameter>map_count</parameter> +entries is allocated or reallocated if it already exists. Otherwise, if +<parameter>want_preserve</parameter> +is +<symbol>False</symbol>, +the +<structfield>preserve</structfield> +field is freed if necessary and set to +<symbol>NULL</symbol>. +</para> + + +<para> +The +<parameter>new_num_lvls</parameter> +parameter specifies the new maximum number of shift levels for the type and is used to calculate and resize the symbols and actions bound to all keys that use the type. </para> <para> -If <emphasis> -type_ndx</emphasis> - does not specify a legal type, <emphasis> -new_num_lvls</emphasis> - is less than 1, or the <emphasis> -map_count</emphasis> - is less than zero, <emphasis> -XkbResizeKeyType</emphasis> - returns <emphasis> -BadValue</emphasis> -. If <emphasis> -XkbResizeKeyType</emphasis> - encounters any problems with allocation, it returns <emphasis> -BadAlloc</emphasis> -. Otherwise, it returns <emphasis> -Success</emphasis> -. +If +<parameter>type_ndx</parameter> +does not specify a legal type, +<parameter>new_num_lvls</parameter> +is less than 1, or the +<parameter>map_count</parameter> +is less than zero, +<function>XkbResizeKeyType</function> +returns +<errorname>BadValue</errorname>. +If +<function>XkbResizeKeyType</function> +encounters any problems with allocation, it returns +<errorname>BadAlloc</errorname>. +Otherwise, it returns +<symbol>Success</symbol>. </para> @@ -1012,177 +1025,176 @@ Success</emphasis> <title>Copying Key Types</title> <para> -Use <emphasis> -XkbCopyKeyType</emphasis> - and <emphasis> -XkbCopyKeyTypes</emphasis> - to copy one or more <emphasis> -XkbKeyTypeRec</emphasis> - structures. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbCopyKeyType</emphasis> -(<emphasis> -from</emphasis> -,<emphasis> - into</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbKeyTypePtr <emphasis> - from</emphasis> -; /* pointer to XkbKeyTypeRec to be copied */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbKeyTypePtr <emphasis> - into</emphasis> -; /* pointer to XkbKeyTypeRec to be changed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbCopyKeyType</emphasis> - copies the key type specified by <emphasis> -from</emphasis> - to the key type specified by <emphasis> -into</emphasis> -. Both must point to legal <emphasis> -XkbKeyTypeRec</emphasis> - structures. Xkb assumes <emphasis> -from</emphasis> - and <emphasis> -into</emphasis> - point to different places. As a result, overlaps can be fatal. <emphasis> -XkbCopyKeyType</emphasis> - frees any existing <emphasis> -map</emphasis> -, <emphasis> -preserve</emphasis> -, and <emphasis> -level_names</emphasis> - in <emphasis> -into</emphasis> - prior to copying. If any allocation errors occur while copying <emphasis> -from</emphasis> - to <emphasis> -into</emphasis> -, <emphasis> -XkbCopyKeyType</emphasis> - returns <emphasis> -BadAlloc</emphasis> -. Otherwise, <emphasis> -XkbCopyKeyType</emphasis> - copies <emphasis> -from</emphasis> - to <emphasis> -into</emphasis> - and returns <emphasis> -Success</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbCopyKeyTypes</emphasis> -(<emphasis> -from</emphasis> -,<emphasis> - into</emphasis> -, <emphasis> -num_types</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbKeyTypePtr <emphasis> - from</emphasis> -; /* pointer to array of XkbKeyTypeRecs to copy */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbKeyTypePtr <emphasis> - into</emphasis> -; /* pointer to array of XkbKeyTypeRecs to change */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - num_types</emphasis> -; /* number of types to copy */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbCopyKeyTypes</emphasis> - copies <emphasis> -num_types</emphasis> - <emphasis> -XkbKeyTypeRec</emphasis> - structures from the array specified by <emphasis> -from</emphasis> - into the array specified by <emphasis> -into</emphasis> -. It is intended for copying between, rather than within, keyboard +Use +<function>XkbCopyKeyType</function> +and +<function>XkbCopyKeyTypes</function> +to copy one or more +<structname>XkbKeyTypeRec</structname> +structures. +</para> + +<indexterm significance="preferred" zone="XkbCopyKeyType"><primary><function>XkbCopyKeyType</function></primary></indexterm> +<funcsynopsis id="XkbCopyKeyType"> + <funcprototype> + <funcdef>Status <function>XkbCopyKeyType</function></funcdef> +<!-- ( +<parameter>from</parameter>, +<parameter>into</parameter> +) --> + + <paramdef>XkbKeyTypePtr <parameter>from</parameter></paramdef> + <paramdef>XkbKeyTypePtr <parameter>into</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>from</parameter> + </term> + <listitem> + <para> + pointer to XkbKeyTypeRec to be copied + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>into</parameter> + </term> + <listitem> + <para> + pointer to XkbKeyTypeRec to be changed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbCopyKeyType</function> +copies the key type specified by +<parameter>from</parameter> +to the key type specified by +<parameter>into</parameter>. +Both must point to legal +<structname>XkbKeyTypeRec</structname> +structures. Xkb assumes +<parameter>from</parameter> +and +<parameter>into</parameter> +point to different places. As a result, overlaps can be fatal. +<function>XkbCopyKeyType</function> +frees any existing +<structfield>map</structfield>, +<structfield>preserve</structfield>, +and +<structfield>level_names</structfield> +in +<parameter>into</parameter> +prior to copying. If any allocation errors occur while copying +<parameter>from</parameter> +to +<parameter>into</parameter>, +<function>XkbCopyKeyType</function> +returns +<errorname>BadAlloc</errorname>. +Otherwise, +<function>XkbCopyKeyType</function> +copies +<parameter>from</parameter> +to +<parameter>into</parameter> +and returns +<symbol>Success</symbol>. +</para> + + +<indexterm significance="preferred" zone="XkbCopyKeyTypes"><primary><function>XkbCopyKeyTypes</function></primary></indexterm> +<funcsynopsis id="XkbCopyKeyTypes"> + <funcprototype> + <funcdef>Status <function>XkbCopyKeyTypes</function></funcdef> +<!-- ( +<parameter>from</parameter>, +<parameter>into</parameter>, +<parameter>num_types</parameter> +) --> + + <paramdef>XkbKeyTypePtr <parameter>from</parameter></paramdef> + <paramdef>XkbKeyTypePtr <parameter>into</parameter></paramdef> + <paramdef>int <parameter>num_types</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>from</parameter> + </term> + <listitem> + <para> + pointer to array of XkbKeyTypeRecs to copy + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>into</parameter> + </term> + <listitem> + <para> + pointer to array of XkbKeyTypeRecs to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_types</parameter> + </term> + <listitem> + <para> + number of types to copy + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbCopyKeyTypes</function> +copies +<parameter>num_types</parameter> +<structname>XkbKeyTypeRec</structname> +structures from the array specified by +<parameter>from</parameter> +into the array specified by +<parameter>into</parameter>. +It is intended for copying between, rather than within, keyboard descriptions, so it doesn’t check for overlaps. The same rules that apply to -the <emphasis> -from</emphasis> - and <emphasis> -into</emphasis> - parameters in <emphasis> -XkbCopyKeyType</emphasis> - apply to each entry of the <emphasis> -from</emphasis> - and <emphasis> -into</emphasis> - arrays of <emphasis> -XkbCopyKeyTypes</emphasis> -. If any allocation errors occur while copying <emphasis> -from</emphasis> - to <emphasis> -into</emphasis> -, <emphasis> -XkbCopyKeyTypes</emphasis> - returns <emphasis> -BadAlloc</emphasis> -. Otherwise, <emphasis> -XkbCopyKeyTypes</emphasis> - copies <emphasis> -from</emphasis> - to <emphasis> -into</emphasis> - and returns <emphasis> -Success</emphasis> -. +the +<parameter>from</parameter> +and +<parameter>into</parameter> +parameters in +<function>XkbCopyKeyType</function> +apply to each entry of the +<parameter>from</parameter> +and +<parameter>into</parameter> +arrays of +<function>XkbCopyKeyTypes</function>. +If any allocation errors occur while copying +<parameter>from</parameter> +to +<parameter>into</parameter>, +<function>XkbCopyKeyTypes</function> +returns +<errorname>BadAlloc</errorname>. +Otherwise, +<function>XkbCopyKeyTypes</function> +copies +<parameter>from</parameter> +to +<parameter>into</parameter> +and returns +<symbol>Success</symbol>. </para> @@ -1190,79 +1202,80 @@ Success</emphasis> </sect1> <sect1 id='Key_Symbol_Map'> <title>Key Symbol Map</title> +<indexterm significance="preferred" zone="Key_Symbol_Map"> +<primary><structname>XkbSymMapRec</structname></primary></indexterm> <para> The entire list of key symbols for the keyboard mapping is held in the -<emphasis> -syms</emphasis> - field of the client map. Whereas the core keyboard mapping is a -two-dimensional array of <emphasis> -KeySyms</emphasis> - whose rows are indexed by keycode, the <emphasis> -syms</emphasis> - field of Xkb is a linear list of <emphasis> -KeySyms</emphasis> - that needs to be indexed uniquely for each key. This section describes the key +<structfield>syms</structfield> +field of the client map. Whereas the core keyboard mapping is a +two-dimensional array of +<type>KeySym</type>s +whose rows are indexed by keycode, the +<structfield>syms</structfield> +field of Xkb is a linear list of +<type>KeySym</type>s +that needs to be indexed uniquely for each key. This section describes the key symbol map and the methods for determining the symbols bound to a key. </para> <para> -The reason the <emphasis> -syms</emphasis> - field is a linear list of <emphasis> -KeySyms</emphasis> - is to reduce the memory consumption associated with a keymap; because Xkb +The reason the +<structfield>syms</structfield> +field is a linear list of +<type>KeySym</type>s +is to reduce the memory consumption associated with a keymap; because Xkb allows individual keys to have multiple shift levels and a different number of -groups per key, a single two-dimensional array of <emphasis> -KeySyms</emphasis> - would potentially be very large and sparse. Instead, Xkb provides a small -two-dimensional array of <emphasis> -KeySyms</emphasis> - for each key. To store all of these individual arrays, Xkb concatenates each -array together in the <emphasis> -syms</emphasis> - field of the client map. -</para> - - -<para> -In order to determine which <emphasis> -KeySyms</emphasis> - in the <emphasis> -syms</emphasis> - field are associated with each keycode, the client map contains an array of -key symbol mappings, held in the <emphasis> -key_sym_map</emphasis> - field. The <emphasis> -key_sym_map</emphasis> - field is an array of <emphasis> -XkbSymMapRec</emphasis> - structures indexed by keycode. The <emphasis> -key_sym_map</emphasis> - array has <emphasis> -min_key_code</emphasis> - unused entries at the start to allow direct indexing using a keycode. All +groups per key, a single two-dimensional array of +<type>KeySym</type>s +would potentially be very large and sparse. Instead, Xkb provides a small +two-dimensional array of +<type>KeySym</type>s +for each key. To store all of these individual arrays, Xkb concatenates each +array together in the +<structfield>syms</structfield> +field of the client map. +</para> + + +<para> +In order to determine which +<type>KeySym</type>s +in the +<structfield>syms</structfield> +field are associated with each keycode, the client map contains an array of +key symbol mappings, held in the +<structfield>key_sym_map</structfield> +field. The +<structfield>key_sym_map</structfield> +field is an array of +<structname>XkbSymMapRec</structname> +structures indexed by keycode. The +<structfield>key_sym_map</structfield> +array has +<structfield>min_key_code</structfield> +unused entries at the start to allow direct indexing using a keycode. All keycodes falling between the minimum and maximum legal keycodes, inclusive, -have <emphasis> -key_sym_map</emphasis> - arrays, whether or not any key actually yields that code. The <emphasis> -KeySymMapRec</emphasis> - structure is defined as follows: -</para> +have +<structfield>key_sym_map</structfield> +arrays, whether or not any key actually yields that code. The +<structname>KeySymMapRec</structname> +structure is defined as follows: -<para><programlisting> +<programlisting> #define XkbNumKbdGroups 4 #define XkbMaxKbdGroup (XkbNumKbdGroups-1) -</programlisting></para> -<para><programlisting> -typedef struct { /* map to keysyms for a single keycode */ - unsigned char kt_index[XkbNumKbdGroups]; /* key type index for each group */ - unsigned char group_info; /* # of groups and out of range group handling */ - unsigned char width; /* max # of shift levels for key */ - unsigned short offset; /* index to keysym table in <emphasis> syms</emphasis> array */ -} <emphasis>XkbSymMapRec</emphasis>, *XkbSymMapPtr; +typedef struct { /* map to keysyms for a single keycode */ + unsigned char kt_index[XkbNumKbdGroups]; + /* key type index for each group */ + unsigned char group_info; /* # of groups and out of range + group handling */ + unsigned char width; /* max # of shift levels for key */ + unsigned short offset; /* index to keysym table in + <structfield>syms</structfield> array */ +} <structname>XkbSymMapRec</structname>, *XkbSymMapPtr; </programlisting></para> <para> @@ -1274,128 +1287,140 @@ These fields are described in detail in the following sections. <title>Per-Key Key Type Indices</title> <para> -The <emphasis> -kt_index</emphasis> - array of the <emphasis> -XkbSymMapRec</emphasis> - structure contains the indices of the key types (see section 15.2) for each +The +<structfield>kt_index</structfield> +array of the +<structname>XkbSymMapRec</structname> +structure contains the indices of the key types (see <link linkend="Key_Types">section 15.2</link>) for each possible group of symbols associated with the key. To obtain the index of a key type or the pointer to a key type, Xkb provides the following macros, to access the key types: </para> <note><para>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> -XkbNumKbdGroups</emphasis> -, currently four); if a key has fewer than <emphasis> -XkbNumKbdGroups</emphasis> - groups, the extra key types are reported but ignored.</para></note> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -int <emphasis> -XkbKeyTypeIndex</emphasis> -(<emphasis> -xkb, keycode, group</emphasis> -) /* macro*/ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -group</emphasis> -; /* group index */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbKeyTypeIndex</emphasis> - computes an index into the <emphasis> -types</emphasis> - vector of the client map in <emphasis> -xkb</emphasis> - from the given <emphasis> -keycode</emphasis> - and <emphasis> -group</emphasis> - index. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbKeyTypePtr <emphasis> -XkbKeyType</emphasis> -(<emphasis> -xkb, keycode, group</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -group</emphasis> -; /* group index */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbKeyType</emphasis> - returns a pointer to the key type in the <emphasis> -types</emphasis> - vector of the client map in <emphasis> -xkb</emphasis> - corresponding to the given <emphasis> -keycode</emphasis> - and <emphasis> -group</emphasis> - index. +hold key types for the maximum legal number of groups +(<symbol>XkbNumKbdGroups</symbol>, +currently four); if a key has fewer than +<symbol>XkbNumKbdGroups</symbol> +groups, the extra key types are reported but ignored.</para></note> + +<indexterm significance="preferred" zone="XkbKeyTypeIndex"><primary><function>XkbKeyTypeIndex</function></primary></indexterm> +<funcsynopsis id="XkbKeyTypeIndex"> + <funcprototype> + <funcdef>int <function>XkbKeyTypeIndex</function></funcdef> +<!-- ( +<parameter>xkb, keycode, group</parameter> +) /* macro*/ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + <paramdef>int <parameter>group</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>group</parameter> + </term> + <listitem> + <para> + group index + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbKeyTypeIndex</function> +computes an index into the +<structfield>types</structfield> +vector of the client map in +<parameter>xkb</parameter> +from the given +<parameter>keycode</parameter> +and +<parameter>group</parameter> +index. +</para> + + +<indexterm significance="preferred" zone="XkbKeyType"><primary><function>XkbKeyType</function></primary></indexterm> +<funcsynopsis id="XkbKeyType"> + <funcprototype> + <funcdef>XkbKeyTypePtr <function>XkbKeyType</function></funcdef> +<!-- ( +<parameter>xkb, keycode, group</parameter> +) /* macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + <paramdef>int <parameter>group</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>group</parameter> + </term> + <listitem> + <para> + group index + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbKeyType</function> +returns a pointer to the key type in the +<structfield>types</structfield> +vector of the client map in +<parameter>xkb</parameter> +corresponding to the given +<parameter>keycode</parameter> +and +<parameter>group</parameter> +index. </para> @@ -1404,64 +1429,64 @@ group</emphasis> <title>Per-Key Group Information</title> <para> -The <emphasis> -group_info</emphasis> - field of an <emphasis> -XkbSymMapRec</emphasis> - is an encoded value containing the number of groups of symbols bound to the +The +<structfield>group_info</structfield> +field of an +<structname>XkbSymMapRec</structname> +is an encoded value containing the number of groups of symbols bound to the key as well as the specification of the treatment of out-of-range groups. It is legal for a key to have zero groups, in which case it also has zero symbols and -all events from that key yield <emphasis> -NoSymbol</emphasis> -. To obtain the number of groups of symbols bound to the key, use <emphasis> -XkbKeyNumGroups</emphasis> -. To change the number of groups bound to a key, use <emphasis> -XkbChangeTypesOfKey</emphasis> - (see section 15.3.6). To obtain a mask that determines the treatment of -out-of-range groups, use <emphasis> -XkbKeyGroupInfo</emphasis> - and <emphasis> -XkbOutOfRangeGroupInfo</emphasis> -. +all events from that key yield +<symbol>NoSymbol</symbol>. +To obtain the number of groups of symbols bound to the key, use +<function>XkbKeyNumGroups</function>. +To change the number of groups bound to a key, use +<function>XkbChangeTypesOfKey</function> +(see <link linkend="Changing_the_Number_of_Groups_and_Types_Bound_to_a_Key">section 15.3.6</link>). To obtain a mask that determines the treatment of +out-of-range groups, use +<function>XkbKeyGroupInfo</function> +and +<function>XkbOutOfRangeGroupInfo</function>. </para> <para> -The keyboard controls (see Chapter 10) contain a <emphasis> -groups_wrap</emphasis> - field specifying the handling of illegal groups on a global basis. That is, +The keyboard controls (see <xref linkend="Keyboard_Controls" />) contain a +<structfield>groups_wrap</structfield> +field specifying the handling of illegal groups on a global basis. That is, when the user performs an action causing the effective group to go out of the -legal range, the <emphasis> -groups_wrap</emphasis> - field specifies how to normalize the effective keyboard group to a group that +legal range, the +<structfield>groups_wrap</structfield> +field specifies how to normalize the effective keyboard group to a group that is legal for the keyboard as a whole, but there is no guarantee that the normalized group will be within the range of legal groups for any individual -key. The per-key <emphasis> -group_info</emphasis> - field specifies how a key treats a legal effective group if the key does not -have a type specified for the group of concern. For example, the <emphasis> -Enter</emphasis> - key usually has just one group defined. If the user performs an action causing -the global keyboard group to change to <emphasis> -Group2</emphasis> -, the <emphasis> -group_info</emphasis> - field for the <emphasis> -Enter</emphasis> - key describes how to handle this situation. +key. The per-key +<structfield>group_info</structfield> +field specifies how a key treats a legal effective group if the key does not +have a type specified for the group of concern. For example, the +<keycap>Enter</keycap> +key usually has just one group defined. If the user performs an action causing +the global keyboard group to change to +<emphasis>Group2</emphasis>, +the +<structfield>group_info</structfield> +field for the +<keycap>Enter</keycap> +key describes how to handle this situation. </para> <para> Out-of-range groups for individual keys are mapped to a legal group using the same options as are used for the overall keyboard group. The particular type of -mapping used is controlled by the bits set in the <emphasis> -group_info</emphasis> - flag, as shown in Table 15.2. See section 10.7.1 for more details on the -normalization methods in this table. +mapping used is controlled by the bits set in the +<structfield>group_info</structfield> +flag, as shown in <link linkend="table15.2">Table 15.2</link>. +See <link linkend="The_GroupsWrap_Control">section 10.7.1</link> +for more details on the normalization methods in this table. </para> -<table frame='topbot'> +<table id='table15.2' frame='topbot'> <title>group_info Range Normalization</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1475,16 +1500,16 @@ normalization methods in this table. </thead> <tbody> <row> - <entry>XkbRedirectIntoRange</entry> - <entry>XkbRedirectIntoRange</entry> + <entry><symbol>XkbRedirectIntoRange</symbol></entry> + <entry><symbol>XkbRedirectIntoRange</symbol></entry> </row> <row> - <entry>XkbClampIntoRange</entry> - <entry>XkbClampIntoRange</entry> + <entry><symbol>XkbClampIntoRange</symbol></entry> + <entry><symbol>XkbClampIntoRange</symbol></entry> </row> <row> <entry>none of the above</entry> - <entry>XkbWrapIntoRange</entry> + <entry><symbol>XkbWrapIntoRange</symbol></entry> </row> </tbody> </tgroup> @@ -1494,167 +1519,159 @@ normalization methods in this table. Xkb provides the following macros to access group information: </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -int <emphasis> -XkbKeyNumGroups</emphasis> -(<emphasis> -xkb, keycode</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbKeyNumGroups</emphasis> - returns the number of groups of symbols bound to the key corresponding to -<emphasis> -keycode</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -unsigned char <emphasis> -XkbKeyGroupInfo</emphasis> -(<emphasis> -xkb, keycode</emphasis> -) /*macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbKeyGroupInfo</emphasis> - returns the <emphasis> -group_info</emphasis> - field from the <emphasis> -XkbSymMapRec</emphasis> - structure associated with the key corresponding to <emphasis> -keycode</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -unsigned char <emphasis> -XkbOutOfRangeGroupInfo</emphasis> -(<emphasis> -grp_inf</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned char <emphasis> -grp_inf</emphasis> -; /* group_info field of <emphasis> -XkbSymMapRec</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbOutOfRangeGroupInfo</emphasis> - returns only the out-of-range processing information from the <emphasis> -group_info</emphasis> - field of an <emphasis> -XkbSymMapRec</emphasis> - structure. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -unsigned char <emphasis> -XkbOutOfRangeGroupNumber</emphasis> -(<emphasis> -grp_inf</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned char <emphasis> -grp_inf</emphasis> -; /* group_info field of <emphasis> -XkbSymMapRec</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbOutOfRangeGroupNumber</emphasis> - returns the out-of-range group number, represented as a group index, from the -<emphasis> -group_info</emphasis> - field of an <emphasis> -XkbSymMapRec</emphasis> - structure. +<indexterm significance="preferred" zone="XkbKeyNumGroups"><primary><function>XkbKeyNumGroups</function></primary></indexterm> +<funcsynopsis id="XkbKeyNumGroups"> + <funcprototype> + <funcdef>int <function>XkbKeyNumGroups</function></funcdef> +<!-- ( +<parameter>xkb, keycode</parameter> +) /* macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbKeyNumGroups</function> +returns the number of groups of symbols bound to the key corresponding to +<parameter>keycode</parameter>. +</para> + + +<indexterm significance="preferred" zone="XkbKeyGroupInfo"><primary><function>XkbKeyGroupInfo</function></primary></indexterm> +<funcsynopsis id="XkbKeyGroupInfo"> + <funcprototype> + <funcdef>unsigned char <function>XkbKeyGroupInfo</function></funcdef> +<!-- ( +<parameter>xkb, keycode</parameter> +) /*macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbKeyGroupInfo</function> +returns the +<structfield>group_info</structfield> +field from the +<structname>XkbSymMapRec</structname> +structure associated with the key corresponding to +<parameter>keycode</parameter>. +</para> + + +<indexterm significance="preferred" zone="XkbOutOfRangeGroupInfo"><primary><function>XkbOutOfRangeGroupInfo</function></primary></indexterm> +<funcsynopsis id="XkbOutOfRangeGroupInfo"> + <funcprototype> + <funcdef>unsigned char <function>XkbOutOfRangeGroupInfo</function></funcdef> +<!-- ( +<parameter>grp_inf</parameter> +) /* macro */ --> + + <paramdef>unsigned char <parameter>grp_inf</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>grp_inf</parameter> + </term> + <listitem> + <para> + group_info field of <structname>XkbSymMapRec</structname> + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbOutOfRangeGroupInfo</function> +returns only the out-of-range processing information from the +<structfield>group_info</structfield> +field of an +<structname>XkbSymMapRec</structname> +structure. +</para> + + +<indexterm significance="preferred" zone="XkbOutOfRangeGroupNumber"><primary><function>XkbOutOfRangeGroupNumber</function></primary></indexterm> +<funcsynopsis id="XkbOutOfRangeGroupNumber"> + <funcprototype> + <funcdef>unsigned char <function>XkbOutOfRangeGroupNumber</function></funcdef> +<!-- ( +<parameter>grp_inf</parameter> +) /* macro */ --> + + <paramdef>unsigned char <parameter>grp_inf</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>grp_inf</parameter> + </term> + <listitem> + <para> + group_info field of <structname>XkbSymMapRec</structname> + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbOutOfRangeGroupNumber</function> +returns the out-of-range group number, represented as a group index, from the +<structfield>group_info</structfield> +field of an +<structname>XkbSymMapRec</structname> +structure. </para> @@ -1664,13 +1681,13 @@ XkbSymMapRec</emphasis> <para> The maximum number of shift levels for a type is also referred to as the width -of a key type. The <emphasis> -width</emphasis> - field of the <emphasis> -key_sym_map</emphasis> - entry for a key contains the width of the widest type associated with the key. -The <emphasis> -width </emphasis> +of a key type. The +<structfield>width</structfield> +field of the +<structfield>key_sym_map</structfield> +entry for a key contains the width of the widest type associated with the key. +The +<structfield>width</structfield> field cannot be explicitly changed; it is updated automatically whenever the symbols or set of types bound to a key are changed. </para> @@ -1682,13 +1699,13 @@ symbols or set of types bound to a key are changed. <para> The key width and number of groups associated with a key are used to form a -small two-dimensional array of <emphasis> -KeySyms</emphasis> - for a key. This array may be different sizes for different keys. The array for +small two-dimensional array of +<type>KeySym</type>s +for a key. This array may be different sizes for different keys. The array for a single key is stored as a linear list, in row-major order. The arrays for all -of the keys are stored in the <emphasis> -syms</emphasis> - field of the client map. There is one row for each group associated with a key +of the keys are stored in the +<structfield>syms</structfield> +field of the client map. There is one row for each group associated with a key and one column for each level. The index corresponding to a given group and shift level is computed as: </para> @@ -1698,297 +1715,315 @@ shift level is computed as: </literallayout> <para> -The <emphasis> -offset</emphasis> - field of the <emphasis> -key_sym_map</emphasis> - entry for a key is used to access the beginning of the array. +The +<structfield>offset</structfield> +field of the +<structfield>key_sym_map</structfield> +entry for a key is used to access the beginning of the array. </para> <para> -Xkb provides the following macros for accessing the <emphasis> -width</emphasis> - and <emphasis> -offset</emphasis> - for individual keys, as well as macros for accessing the two-dimensional array +Xkb provides the following macros for accessing the +<structfield>width</structfield> +and +<structfield>offset</structfield> +for individual keys, as well as macros for accessing the two-dimensional array of symbols bound to the key: </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -int <emphasis> -XkbKeyGroupsWidth</emphasis> -(<emphasis> -xkb, keycode</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbKeyGroupsWidth</emphasis> - computes the maximum width associated with the key corresponding to <emphasis> -keycode</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -int <emphasis> -XkbKeyGroupWidth</emphasis> -(<emphasis> -xkb, keycode, grp</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -grp</emphasis> -; /* group of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbKeyGroupWidth</emphasis> - computes the width of the type associated with the group <emphasis> -grp</emphasis> - for the key corresponding to <emphasis> -keycode</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -int <emphasis> -XkbKeySymsOffset</emphasis> -(<emphasis> -xkb, keycode</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbKeySymsOffset</emphasis> - returns the offset of the two-dimensional array of keysyms for the key -corresponding to <emphasis> -keycode</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -int <emphasis> -XkbKeyNumSyms</emphasis> -(<emphasis> -xkb, keycode</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbKeyNumSyms</emphasis> - returns the total number of keysyms for the key corresponding to <emphasis> -keycode</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -KeySym * <emphasis> -XkbKeySymsPtr</emphasis> -(<emphasis> -xkb, keycode</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbKeySymsPtr</emphasis> - returns the pointer to the two-dimensional array of keysyms for the key -corresponding to <emphasis> -keycode</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -KeySym <emphasis> -XkbKeySymEntry</emphasis> -(<emphasis> -xkb, keycode, shift, grp</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -shift</emphasis> -; /* shift level of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -grp</emphasis> -; /* group of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbKeySymEntry</emphasis> - returns the <emphasis> -keysym</emphasis> - corresponding to shift level <emphasis> -shift</emphasis> - and group <emphasis> -grp</emphasis> - from the two-dimensional array of keysyms for the key corresponding to -<emphasis> -keycode</emphasis> +<indexterm significance="preferred" zone="XkbKeyGroupsWidth"><primary><function>XkbKeyGroupsWidth</function></primary></indexterm> +<funcsynopsis id="XkbKeyGroupsWidth"> + <funcprototype> + <funcdef>int <function>XkbKeyGroupsWidth</function></funcdef> +<!-- ( +<parameter>xkb, keycode</parameter> +) /* macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbKeyGroupsWidth</function> +computes the maximum width associated with the key corresponding to +<parameter>keycode</parameter>. +</para> + + +<indexterm significance="preferred" zone="XkbKeyGroupWidth"><primary><function>XkbKeyGroupWidth</function></primary></indexterm> +<funcsynopsis id="XkbKeyGroupWidth"> + <funcprototype> + <funcdef>int <function>XkbKeyGroupWidth</function></funcdef> +<!-- ( +<parameter>xkb, keycode, grp</parameter> +) /* macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + <paramdef>int <parameter>grp</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>grp</parameter> + </term> + <listitem> + <para> + group of interest + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbKeyGroupWidth</function> +computes the width of the type associated with the group +<parameter>grp</parameter> +for the key corresponding to +<parameter>keycode</parameter>. +</para> + + +<indexterm significance="preferred" zone="XkbKeySymsOffset"><primary><function>XkbKeySymsOffset</function></primary></indexterm> +<funcsynopsis id="XkbKeySymsOffset"> + <funcprototype> + <funcdef>int <function>XkbKeySymsOffset</function></funcdef> +<!-- ( +<parameter>xkb, keycode</parameter> +) /* macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbKeySymsOffset</function> +returns the offset of the two-dimensional array of keysyms for the key +corresponding to +<parameter>keycode</parameter>. +</para> + + +<indexterm significance="preferred" zone="XkbKeyNumSyms"><primary><function>XkbKeyNumSyms</function></primary></indexterm> +<funcsynopsis id="XkbKeyNumSyms"> + <funcprototype> + <funcdef>int <function>XkbKeyNumSyms</function></funcdef> +<!-- ( +<parameter>xkb, keycode</parameter> +) /* macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbKeyNumSyms</function> +returns the total number of keysyms for the key corresponding to +<parameter>keycode</parameter>. +</para> + + +<indexterm significance="preferred" zone="XkbKeySymsPtr"><primary><function>XkbKeySymsPtr</function></primary></indexterm> +<funcsynopsis id="XkbKeySymsPtr"> + <funcprototype> + <funcdef>KeySym *<function>XkbKeySymsPtr</function></funcdef> +<!-- ( +<parameter>xkb, keycode</parameter> +) /* macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbKeySymsPtr</function> +returns the pointer to the two-dimensional array of keysyms for the key +corresponding to +<parameter>keycode</parameter>. +</para> + + +<indexterm significance="preferred" zone="XkbKeySymEntry"><primary><function>XkbKeySymEntry</function></primary></indexterm> +<funcsynopsis id="XkbKeySymEntry"> + <funcprototype> + <funcdef>KeySym <function>XkbKeySymEntry</function></funcdef> +<!-- ( +<parameter>xkb, keycode, shift, grp</parameter> +) /* macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + <paramdef>int <parameter>shift</parameter></paramdef> + <paramdef>int <parameter>grp</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>shift</parameter> + </term> + <listitem> + <para> + shift level of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>grp</parameter> + </term> + <listitem> + <para> + group of interest + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbKeySymEntry</function> +returns the +<type>KeySym</type> +corresponding to shift level +<parameter>shift</parameter> +and group +<parameter>grp</parameter> +from the two-dimensional array of keysyms for the key corresponding to +<parameter>keycode</parameter> </para> @@ -1998,114 +2033,118 @@ keycode</emphasis> <para> To obtain the symbols for a subset of the keys in a keyboard description, use -<emphasis> -XkbGetKeySyms</emphasis> -: -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetKeySyms</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - first</emphasis> -, <emphasis> -num</emphasis> -,<emphasis> - xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - first</emphasis> -; /* keycode of first key to get */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - num</emphasis> -; /* number of keycodes for which syms desired */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description to be updated */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetKeySyms</emphasis> - sends a request to the server to obtain the set of keysyms bound to <emphasis> -num</emphasis> - keys starting with the key whose keycode is <emphasis> -first</emphasis> -. It waits for a reply and returns the keysyms in the <emphasis> -map.syms</emphasis> - field of <emphasis> -xkb</emphasis> -. If successful, <emphasis> -XkbGetKeySyms</emphasis> - returns <emphasis> -Success</emphasis> -. The <emphasis> -xkb</emphasis> - parameter must be a pointer to a valid Xkb keyboard description. -</para> - - -<para> -If the client <emphasis> -map</emphasis> - in the <emphasis> -xkb</emphasis> - parameter has not been allocated, <emphasis> -XkbGetKeySyms</emphasis> - allocates and initializes it before obtaining the symbols. +<function>XkbGetKeySyms</function>: + +</para> + +<indexterm significance="preferred" zone="XkbGetKeySyms"><primary><function>XkbGetKeySyms</function></primary></indexterm> +<funcsynopsis id="XkbGetKeySyms"> + <funcprototype> + <funcdef>Status <function>XkbGetKeySyms</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>first</parameter>, +<parameter>num</parameter>, +<parameter>xkb</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>first</parameter></paramdef> + <paramdef>unsigned int <parameter>num</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + keycode of first key to get + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num</parameter> + </term> + <listitem> + <para> + number of keycodes for which syms desired + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description to be updated + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetKeySyms</function> +sends a request to the server to obtain the set of keysyms bound to +<parameter>num</parameter> +keys starting with the key whose keycode is +<parameter>first</parameter>. +It waits for a reply and returns the keysyms in the +<structfield>map.syms</structfield> +field of +<parameter>xkb</parameter>. +If successful, +<function>XkbGetKeySyms</function> +returns +<symbol>Success</symbol>. +The +<parameter>xkb</parameter> +parameter must be a pointer to a valid Xkb keyboard description. +</para> + + +<para> +If the client +<structfield>map</structfield> +in the +<parameter>xkb</parameter> +parameter has not been allocated, +<function>XkbGetKeySyms</function> +allocates and initializes it before obtaining the symbols. </para> <para> If a compatible version of Xkb is not available in the server or the Xkb -extension has not been properly initialized, <emphasis> -XkbGetKeySyms</emphasis> - returns <emphasis> -BadAccess</emphasis> -. If <emphasis> -num</emphasis> - is less than 1 or greater than <emphasis> -XkbMaxKeyCount</emphasis> -, <emphasis> -XkbGetKeySyms</emphasis> - returns <emphasis> -BadValue</emphasis> -. If any allocation errors occur, <emphasis> -XkbGetKeySyms</emphasis> - returns <emphasis> -BadAlloc</emphasis> -. +extension has not been properly initialized, +<function>XkbGetKeySyms</function> +returns +<errorname>BadAccess</errorname>. +If +<parameter>num</parameter> +is less than 1 or greater than +<symbol>XkbMaxKeyCount</symbol>, +<function>XkbGetKeySyms</function> +returns +<errorname>BadValue</errorname>. +If any allocation errors occur, +<function>XkbGetKeySyms</function> +returns +<errorname>BadAlloc</errorname>. </para> @@ -2114,164 +2153,166 @@ BadAlloc</emphasis> <title>Changing the Number of Groups and Types Bound to a Key</title> <para> -To change the number of groups and the types bound to a key, use <emphasis> -XkbChangeTypesOfKey</emphasis> -. -</para> - - -<para> -Status <emphasis> -XkbChangeTypesOfKey</emphasis> -(<emphasis> -xkb</emphasis> -,<emphasis> - key</emphasis> -,<emphasis> - n_groups</emphasis> -,<emphasis> - groups</emphasis> -,<emphasis> - new_types_in</emphasis> -,<emphasis> - p_changes</emphasis> -) -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* keyboard description to be changed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - key</emphasis> -; /* keycode for key of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - n_groups</emphasis> -; /* new number of groups for key */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -groups</emphasis> -; /* mask indicating groups to change */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int * <emphasis> -new_types_in</emphasis> -; /* indices for new groups specified in <emphasis> -groups</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbMapChangesPtr <emphasis> -p_changes</emphasis> -; /* notes changes made to <emphasis> -xkb</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbChangeTypesOfKey</emphasis> - reallocates the symbols and actions bound to the key, if necessary, and -initializes any new symbols or actions to <emphasis> -NoSymbol</emphasis> - or <emphasis> -NoAction</emphasis> -, as appropriate. If the <emphasis> -p_changes</emphasis> - parameter is not <emphasis> -NULL</emphasis> -, <emphasis> -XkbChangeTypesOfKey</emphasis> - adds the <emphasis> -XkbKeySymsMask</emphasis> - to the <emphasis> -changes</emphasis> - field of <emphasis> -p_changes</emphasis> - and modifies the <emphasis> -first_key_sym</emphasis> - and <emphasis> -num_key_syms</emphasis> - fields of <emphasis> -p_changes</emphasis> - to include the <emphasis> -key</emphasis> - that was changed. See section 14.3.1 for more information on the <emphasis> -XkbMapChangesPtr</emphasis> - structure. If successful, <emphasis> -XkbChangeTypesOfKey</emphasis> - returns <emphasis> -Success</emphasis> -. -</para> - - -<para> -The <emphasis> -n_groups</emphasis> - parameter specifies the new number of groups for the key. The <emphasis> -groups</emphasis> - parameter is a mask specifying the groups for which new types are supplied and -is a bitwise inclusive OR of the following masks: <emphasis> -XkbGroup1Mask</emphasis> -, <emphasis> -XkbGroup2Mask</emphasis> -, <emphasis> -XkbGroup3Mask</emphasis> -, and <emphasis> -XkbGroup4Mask</emphasis> -. -</para> - - -<para> -The <emphasis> -new_types_in</emphasis> - parameter is an integer array of length <emphasis> -n_groups</emphasis> -. Each entry represents the type to use for the associated group and is an -index into <emphasis> -xkb</emphasis> --><emphasis> -map->types</emphasis> -. The <emphasis> -new_types_in</emphasis> - array is indexed by group index; if <emphasis> -n_groups</emphasis> - is four and <emphasis> -groups</emphasis> - only has <emphasis> -Group1Mask</emphasis> - and <emphasis> -Group3Mask</emphasis> - set, <emphasis> -new_types_in</emphasis> - looks like this: +To change the number of groups and the types bound to a key, use +<function>XkbChangeTypesOfKey</function>. +</para> + + +<indexterm significance="preferred" zone="XkbChangeTypesOfKey"><primary><function>XkbChangeTypesOfKey</function></primary></indexterm> +<funcsynopsis id="XkbChangeTypesOfKey"> + <funcprototype> + <funcdef>Status <function>XkbChangeTypesOfKey</function></funcdef> +<!-- ( +<parameter>xkb</parameter>, +<parameter>key</parameter>, +<parameter>n_groups</parameter>, +<parameter>groups</parameter>, +<parameter>new_types_in</parameter>, +<parameter>p_changes</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>int <parameter>key</parameter></paramdef> + <paramdef>int <parameter>n_groups</parameter></paramdef> + <paramdef>unsigned int <parameter>groups</parameter></paramdef> + <paramdef>int *<parameter>new_types_in</parameter></paramdef> + <paramdef>XkbMapChangesPtr <parameter>p_changes</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description to be changed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>key</parameter> + </term> + <listitem> + <para> + keycode for key of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>n_groups</parameter> + </term> + <listitem> + <para> + new number of groups for key + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>groups</parameter> + </term> + <listitem> + <para> + mask indicating groups to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>new_types_in</parameter> + </term> + <listitem> + <para> + indices for new groups specified in <parameter>groups</parameter> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>p_changes</parameter> + </term> + <listitem> + <para> + notes changes made to <parameter>xkb</parameter> + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbChangeTypesOfKey</function> +reallocates the symbols and actions bound to the key, if necessary, and +initializes any new symbols or actions to +<symbol>NoSymbol</symbol> +or +<emphasis>NoAction</emphasis>, +as appropriate. If the +<parameter>p_changes</parameter> +parameter is not +<symbol>NULL</symbol>, +<function>XkbChangeTypesOfKey</function> +adds the +<symbol>XkbKeySymsMask</symbol> +to the +<structfield>changes</structfield> +field of +<parameter>p_changes</parameter> +and modifies the +<structfield>first_key_sym</structfield> +and +<structfield>num_key_syms</structfield> +fields of +<parameter>p_changes</parameter> +to include the +<parameter>key</parameter> +that was changed. See <link linkend="The_XkbMapChangesRec_Structure">section 14.3.1</link> for more information on the +<type>XkbMapChangesPtr</type> +structure. If successful, +<function>XkbChangeTypesOfKey</function> +returns +<symbol>Success</symbol>. +</para> + + +<para> +The +<parameter>n_groups</parameter> +parameter specifies the new number of groups for the key. The +<parameter>groups</parameter> +parameter is a mask specifying the groups for which new types are supplied and +is a bitwise inclusive OR of the following masks: +<symbol>XkbGroup1Mask</symbol>, +<symbol>XkbGroup2Mask</symbol>, +<symbol>XkbGroup3Mask</symbol>, +and +<symbol>XkbGroup4Mask</symbol>. +</para> + + +<para> +The +<parameter>new_types_in</parameter> +parameter is an integer array of length +<parameter>n_groups</parameter>. +Each entry represents the type to use for the associated group and is an +index into +<parameter>xkb</parameter>-><structfield>map->types</structfield>. +The +<parameter>new_types_in</parameter> +array is indexed by group index; if +<parameter>n_groups</parameter> +is four and +<parameter>groups</parameter> +only has +<symbol>XkbGroup1Mask</symbol> +and +<symbol>XkbGroup3Mask</symbol> +set, +<parameter>new_types_in</parameter> +looks like this: </para> <literallayout> @@ -2286,7 +2327,7 @@ For convenience, Xkb provides the following constants to use as indices to the groups: </para> -<table frame='topbot'> +<table id='table15.3' frame='topbot'> <title>Group Index Constants</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -2300,19 +2341,19 @@ groups: </thead> <tbody> <row> - <entry>XkbGroup1Index</entry> + <entry><symbol>XkbGroup1Index</symbol></entry> <entry>0</entry> </row> <row> - <entry>XkbGroup2Index</entry> + <entry><symbol>XkbGroup2Index</symbol></entry> <entry>1</entry> </row> <row> - <entry>XkbGroup3Index</entry> + <entry><symbol>XkbGroup3Index</symbol></entry> <entry>2</entry> </row> <row> - <entry>XkbGroup4Index</entry> + <entry><symbol>XkbGroup4Index</symbol></entry> <entry>3</entry> </row> </tbody> @@ -2320,36 +2361,35 @@ groups: </table> <para> -If the Xkb extension has not been properly initialized, <emphasis> -XkbChangeTypesOfKey</emphasis> - returns <emphasis> -BadAccess</emphasis> -. If the <emphasis> -xkb</emphasis> - parameter it not valid (that is, it is <emphasis> -NULL</emphasis> - or it does not contain a valid client map), <emphasis> -XkbChangeTypesOfKey</emphasis> - returns <emphasis> -Bad</emphasis> -Match. If the <emphasis> -key</emphasis> - is not a valid keycode, <emphasis> -n_groups</emphasis> - is greater than <emphasis> -XkbNumKbdGroups</emphasis> -, or the <emphasis> -groups</emphasis> - mask does not contain any of the valid group mask bits, <emphasis> -XkbChangeTypesOfKey</emphasis> - returns <emphasis> -BadValue</emphasis> -. If it is necessary to resize the key symbols or key actions arrays and any -allocation errors occur, <emphasis> -XkbChangeTypesOfKey</emphasis> - returns <emphasis> -BadAlloc</emphasis> -. +If the Xkb extension has not been properly initialized, +<function>XkbChangeTypesOfKey</function> +returns +<errorname>BadAccess</errorname>. +If the +<parameter>xkb</parameter> +parameter it not valid (that is, it is +<symbol>NULL</symbol> +or it does not contain a valid client map), +<function>XkbChangeTypesOfKey</function> +returns +<errorname>BadMatch</errorname>. +If the +<parameter>key</parameter> +is not a valid keycode, +<parameter>n_groups</parameter> +is greater than +<symbol>XkbNumKbdGroups</symbol>, +or the +<parameter>groups</parameter> +mask does not contain any of the valid group mask bits, +<function>XkbChangeTypesOfKey</function> +returns +<errorname>BadValue</errorname>. +If it is necessary to resize the key symbols or key actions arrays and any +allocation errors occur, +<function>XkbChangeTypesOfKey</function> +returns +<errorname>BadAlloc</errorname>. </para> @@ -2358,124 +2398,121 @@ BadAlloc</emphasis> <title>Changing the Number of Symbols Bound to a Key</title> <para> -To change the number of symbols bound to a key, use <emphasis> -XkbResizeKeySyms</emphasis> -. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -KeySym *<emphasis> -XkbResizeKeySyms</emphasis> -(<emphasis> -xkb</emphasis> -,<emphasis> - key</emphasis> -,<emphasis> - needed</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescRec *<emphasis> - xkb</emphasis> -; /* keyboard description to be changed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - key</emphasis> -; /* keycode for key to modify */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - needed</emphasis> -; /* new number of keysyms required for key */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbResizeKeySyms</emphasis> - reserves the space needed for <emphasis> -needed</emphasis> - keysyms and returns a pointer to the beginning of the new array that holds the -keysyms. It adjusts the <emphasis> -offset</emphasis> - field of the <emphasis> -key_sym_map</emphasis> - entry for the key if necessary and can also change the <emphasis> -syms</emphasis> -, <emphasis> -num_syms</emphasis> -, and <emphasis> -size_syms</emphasis> - fields of <emphasis> -xkb</emphasis> --<emphasis> ->map</emphasis> - if it is necessary to reallocate the <emphasis> -syms</emphasis> - array. <emphasis> -XkbResizeKeySyms</emphasis> - does not modify either the width or number of groups associated with the key. -</para> - - -<para> -If <emphasis> -needed</emphasis> - is greater than the current number of keysyms for the key, <emphasis> -XkbResizeKeySyms</emphasis> - initializes all new keysyms in the array to <emphasis> -NoSymbol</emphasis> -. +To change the number of symbols bound to a key, use +<function>XkbResizeKeySyms</function>. +</para> + +<indexterm significance="preferred" zone="XkbResizeKeySyms"><primary><function>XkbResizeKeySyms</function></primary></indexterm> +<funcsynopsis id="XkbResizeKeySyms"> + <funcprototype> + <funcdef>KeySym *<function>XkbResizeKeySyms</function></funcdef> +<!-- ( +<parameter>xkb</parameter>, +<parameter>key</parameter>, +<parameter>needed</parameter> +) --> + + <paramdef>XkbDescRec *<parameter>xkb</parameter></paramdef> + <paramdef>int <parameter>key</parameter></paramdef> + <paramdef>int <parameter>needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description to be changed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>key</parameter> + </term> + <listitem> + <para> + keycode for key to modify + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>needed</parameter> + </term> + <listitem> + <para> + new number of keysyms required for key + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbResizeKeySyms</function> +reserves the space needed for +<parameter>needed</parameter> +keysyms and returns a pointer to the beginning of the new array that holds the +keysyms. It adjusts the +<structfield>offset</structfield> +field of the +<structfield>key_sym_map</structfield> +entry for the key if necessary and can also change the +<structfield>syms</structfield>, +<structfield>num_syms</structfield>, +and +<structfield>size_syms</structfield> +fields of +<structfield>xkb->map</structfield> +if it is necessary to reallocate the +<structfield>syms</structfield> +array. +<function>XkbResizeKeySyms</function> +does not modify either the width or number of groups associated with the key. +</para> + + +<para> +If +<parameter>needed</parameter> +is greater than the current number of keysyms for the key, +<function>XkbResizeKeySyms</function> +initializes all new keysyms in the array to +<symbol>NoSymbol</symbol>. </para> <para> Because the number of symbols needed by a key is normally computed as width * -number of groups, and <emphasis> -XkbResizeKeySyms</emphasis> - does not modify either the width or number of groups for the key, a -discrepancy exists upon return from <emphasis> -XkbResizeKeySyms</emphasis> - between the space allocated for the keysyms and the number required. The -unused entries in the list of symbols returned by <emphasis> -XkbResizeKeySyms</emphasis> - are not preserved across future calls to any of the map editing functions, so +number of groups, and +<function>XkbResizeKeySyms</function> +does not modify either the width or number of groups for the key, a +discrepancy exists upon return from +<function>XkbResizeKeySyms</function> +between the space allocated for the keysyms and the number required. The +unused entries in the list of symbols returned by +<function>XkbResizeKeySyms</function> +are not preserved across future calls to any of the map editing functions, so you must update the key symbol mapping (which updates the width and number of groups for the key) before calling another allocator function. A call to -<emphasis> -XkbChangeTypesOfKey</emphasis> - will update the mapping. +<function>XkbChangeTypesOfKey</function> +will update the mapping. </para> <para> If any allocation errors occur while resizing the number of symbols bound to -the key, <emphasis> -XkbResizeKeySyms</emphasis> - returns <emphasis> -NULL</emphasis> -. +the key, +<function>XkbResizeKeySyms</function> +returns +<symbol>NULL</symbol>. </para> <note><para>A change to the number of symbols bound to a key should be accompanied by a change in the number of actions bound to a key. Refer to -section 16.1.16 for more information on changing the number of actions bound to +<link linkend="Changing_the_Number_of_Actions_Bound_to_a_Key">section 16.1.16</link> for more information on changing the number of actions bound to a key.</para></note> @@ -2485,29 +2522,23 @@ a key.</para></note> <title>The Per-Key Modifier Map</title> <para> -The <emphasis> -modmap</emphasis> - entry of the client map is an array, indexed by keycode, specifying the real +The +<structfield>modmap</structfield> +entry of the client map is an array, indexed by keycode, specifying the real modifiers bound to a key. Each entry is a mask composed of a bitwise inclusive -OR of the legal real modifiers: <emphasis> -ShiftMask</emphasis> -, <emphasis> -LockMask</emphasis> -, <emphasis> -ControlMask</emphasis> -, <emphasis> -Mod1Mask</emphasis> -, <emphasis> -Mod2Mask</emphasis> -, <emphasis> -Mod3Mask</emphasis> -, <emphasis> -Mod4Mask</emphasis> -, and <emphasis> -Mod5Mask</emphasis> -. If a bit is set in a <emphasis> -modmap</emphasis> - entry, the corresponding key is bound to that modifier. +OR of the legal real modifiers: +<symbol>ShiftMask</symbol>, +<symbol>LockMask</symbol>, +<symbol>ControlMask</symbol>, +<symbol>Mod1Mask</symbol>, +<symbol>Mod2Mask</symbol>, +<symbol>Mod3Mask</symbol>, +<symbol>Mod4Mask</symbol>, +and +<symbol>Mod5Mask</symbol>. +If a bit is set in a +<structfield>modmap</structfield> +entry, the corresponding key is bound to that modifier. </para> @@ -2515,7 +2546,7 @@ modmap</emphasis> Pressing or releasing the key bound to a modifier changes the modifier set and unset state. The particular manner in which the modifier set and unset state changes is determined by the behavior and actions assigned to the key (see -Chapter 16). +<xref linkend="Xkb_Server_Keyboard_Mapping" />). </para> @@ -2524,100 +2555,103 @@ Chapter 16). <para> To update the modifier map for one or more of the keys in a keyboard -description, use <emphasis> -XkbGetKeyModifierMap</emphasis> -. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetKeyModifierMap</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - num</emphasis> -,<emphasis> - xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -first</emphasis> -; /* keycode of first key to get */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -num</emphasis> -; /* number of keys for which information is desired */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description to update */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetKeyModifierMap</emphasis> - sends a request to the server for the modifier mappings for <emphasis> -num</emphasis> - keys starting with the key whose keycode is <emphasis> -first</emphasis> -. It waits for a reply and places the results in the <emphasis> -xkb</emphasis> -->map->modmap array. If successful, <emphasis> -XkbGetKeyModifier</emphasis> - returns <emphasis> -Success</emphasis> -. -</para> - - -<para> -If the map component of the <emphasis> -xkb</emphasis> - parameter has not been allocated, <emphasis> -XkbGetKeyModifierMap</emphasis> - allocates and initializes it. +description, use +<function>XkbGetKeyModifierMap</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetKeyModifierMap"><primary><function>XkbGetKeyModifierMap</function></primary></indexterm> +<funcsynopsis id="XkbGetKeyModifierMap"> + <funcprototype> + <funcdef>Status <function>XkbGetKeyModifierMap</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>first</parameter>, +<parameter>num</parameter>, +<parameter>xkb</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>first</parameter></paramdef> + <paramdef>unsigned int <parameter>num</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + keycode of first key to get + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num</parameter> + </term> + <listitem> + <para> + number of keys for which information is desired + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description to update + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetKeyModifierMap</function> +sends a request to the server for the modifier mappings for +<parameter>num</parameter> +keys starting with the key whose keycode is +<parameter>first</parameter>. +It waits for a reply and places the results in the +<parameter>xkb</parameter>->map->modmap array. If successful, +<function>XkbGetKeyModifierMap</function> +returns +<symbol>Success</symbol>. +</para> + + +<para> +If the map component of the +<parameter>xkb</parameter> +parameter has not been allocated, +<function>XkbGetKeyModifierMap</function> +allocates and initializes it. </para> <para> If a compatible version of Xkb is not available in the server or the Xkb -extension has not been properly initialized, <emphasis> -XkbGetKeySyms</emphasis> - returns <emphasis> -BadAccess</emphasis> -. If any allocation errors occur while obtaining the modifier map, <emphasis> -XkbGetKeyModifierMap</emphasis> - returns <emphasis> -BadAlloc</emphasis> -. +extension has not been properly initialized, +<function>XkbGetKeySyms</function> +returns +<errorname>BadAccess</errorname>. +If any allocation errors occur while obtaining the modifier map, +<function>XkbGetKeyModifierMap</function> +returns +<errorname>BadAlloc</errorname>. </para> </sect2> </sect1> diff --git a/libX11/specs/XKB/ch16.xml b/libX11/specs/XKB/ch16.xml index 2640ea2dd..3f5e42f04 100644 --- a/libX11/specs/XKB/ch16.xml +++ b/libX11/specs/XKB/ch16.xml @@ -1,23 +1,33 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Xkb_Server_Keyboard_Mapping'> <title>Xkb Server Keyboard Mapping</title> +<indexterm zone="Xkb_Server_Keyboard_Mapping"> +<primary>server map</primary></indexterm> +<indexterm zone="Xkb_Server_Keyboard_Mapping"> +<primary>map</primary><secondary>server</secondary></indexterm> + <para> -The <emphasis> -server</emphasis> - field of the complete Xkb keyboard description (see section 6.1) is a pointer +The +<structfield>server</structfield> +field of the complete Xkb keyboard description (see <link linkend="The_XkbDescRec_Structure">section 6.1</link>) is a pointer to the Xkb server map. </para> <para> -Figure 16.1 shows the relationships between elements in the server map: +<link linkend="figure16.1">Figure 16.1</link> shows the relationships between elements in the server map: </para> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-16.svg"/> - </imageobject> -<caption>Server Map Relationships</caption> - </mediaobject> +<figure id='figure16.1'> + <title>Server Map Relationships</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-16.svg"/> + </imageobject> + </mediaobject> +</figure> <!-- @@ -25,51 +35,50 @@ Figure 16.1 shows the relationships between elements in the server map: Server Map Relationships</H5> --> -<para> +<para id='XkbServerMapRec'> +<indexterm significance="preferred" zone="XkbServerMapRec"> +<primary><structname>XkbServerMapRec</structname></primary></indexterm> The Xkb server map contains the information the server needs to interpret key -events and is of type <emphasis> -XkbServerMapRec</emphasis> -: -</para> +events and is of type +<structname>XkbServerMapRec</structname>: -<para><programlisting> +<programlisting> #define XkbNumVirtualMods 16 -</programlisting></para> -<para><programlisting> -typedef struct { /* Server Map */ - unsigned short num_acts; /* # of occupied entries in <emphasis> acts</emphasis> */ - unsigned short size_acts; /* # of entries in <emphasis> acts</emphasis> */ - XkbAction * acts; /* linear 2d tables of key actions, 1 per keycode */ - XkbBehavior * behaviors; /* key behaviors,1 per keycode */ - unsigned short * key_acts; /* index into <emphasis> acts</emphasis> , 1 per keycode */ - unsigned char * explicit; /* explicit overrides of core remapping, 1 per key */ - unsigned char vmods[XkbNumVirtualMods]; /* real mods bound to virtual mods */ - unsigned short * vmodmap; /* virtual mods bound to key, 1 per keycode*/ -} <emphasis>XkbServerMapRec</emphasis>, *XkbServerMapPtr; +typedef struct { /* Server Map */ + unsigned short num_acts; /* # of occupied entries in <structfield>acts</structfield> */ + unsigned short size_acts; /* # of entries in <structfield>acts</structfield> */ + XkbAction * acts; /* linear 2d tables of key actions, + 1 per keycode */ + XkbBehavior * behaviors; /* key behaviors, 1 per keycode */ + unsigned short * key_acts; /* index into <structfield>acts</structfield>, 1 per keycode */ + unsigned char * explicit; /* explicit overrides of core + remapping, 1 per key */ + unsigned char vmods[XkbNumVirtualMods]; /* real mods bound + to virtual mods */ + unsigned short * vmodmap; /* virtual mods bound to key, + 1 per keycode */ +} <structname>XkbServerMapRec</structname>, *XkbServerMapPtr; </programlisting></para> <para> -The <emphasis> -num_acts</emphasis> -, <emphasis> -size_acts</emphasis> -, <emphasis> -acts</emphasis> -, and <emphasis> -key_acts</emphasis> - fields specify the key actions, defined in section 16.1. The <emphasis> -behaviors</emphasis> - field describes the behavior for each key and is defined in section 16.2. The -<emphasis> -explicit</emphasis> - field describes the explicit components for a key and is defined in section -16.3. The <emphasis> -vmods</emphasis> - and the <emphasis> -vmodmap</emphasis> - fields describe the virtual modifiers and the per-key virtual modifier mapping -and are defined in section 16.4. +The +<structfield>num_acts</structfield>, +<structfield>size_acts</structfield>, +<structfield>acts</structfield>, +and +<structfield>key_acts</structfield> +fields specify the key actions, defined in <link linkend="Key_Actions">section 16.1</link>. The +<structfield>behaviors</structfield> +field describes the behavior for each key and is defined in <link linkend="Key_Behavior">section 16.2</link>. The +<structfield>explicit</structfield> +field describes the explicit components for a key and is defined in +<link linkend="Explicit_ComponentsAvoiding_Automatic_Remapping_by_the_Server">section 16.3</link>. The +<structfield>vmods</structfield> +and the +<structfield>vmodmap</structfield> +fields describe the virtual modifiers and the per-key virtual modifier mapping +and are defined in <link linkend="Virtual_Modifier_Mapping">section 16.4</link>. </para> <sect1 id='Key_Actions'> @@ -78,74 +87,71 @@ and are defined in section 16.4. <para> A key action defines the effect key presses and releases have on the internal state of the server. For example, the expected key action associated with -pressing the <emphasis> -Shift</emphasis> - key is to set the <emphasis> -Shift</emphasis> - modifier. There is zero or one key action associated with each keysym bound to +pressing the +<symbol>Shift</symbol> +key is to set the +<symbol>Shift</symbol> +modifier. There is zero or one key action associated with each keysym bound to each key. </para> <para> Just as the entire list of key symbols for the keyboard mapping is held in the -<emphasis> -syms</emphasis> - field of the client map, the entire list of key actions for the keyboard -mapping is held in the <emphasis> -acts</emphasis> - array of the server map. The total size of <emphasis> -acts</emphasis> - is specified by <emphasis> -size_acts</emphasis> -, and the number of entries is specified by <emphasis> -num_acts</emphasis>. -</para> - - -<para> -The <emphasis> -key_acts</emphasis> - array, indexed by keycode, describes the actions associated with a key. The -<emphasis> -key_acts</emphasis> - array has <emphasis> -min_key_code</emphasis> - unused entries at the start to allow direct indexing using a keycode. If a -<emphasis> -key_acts</emphasis> - entry is <emphasis> -zero</emphasis> -, it means the key does not have any actions associated with it. If an entry is -not <emphasis> -zero</emphasis> -, the entry represents an index into the <emphasis> -acts</emphasis> - field of the server map, much as the <emphasis> -offset</emphasis> - field of a <emphasis> -KeySymMapRec</emphasis> - structure is an index into the <emphasis> -syms</emphasis> - field of the client map. -</para> - -<para> -The reason the <emphasis> -acts</emphasis> - field is a linear list of <emphasis> -XkbAction</emphasis> -s is to reduce the memory consumption associated with a keymap. Because Xkb +<structfield>syms</structfield> +field of the client map, the entire list of key actions for the keyboard +mapping is held in the +<structfield>acts</structfield> +array of the server map. The total size of +<structfield>acts</structfield> +is specified by +<structfield>size_acts</structfield>, +and the number of entries is specified by +<structfield>num_acts</structfield>. +</para> + + +<para> +The +<structfield>key_acts</structfield> +array, indexed by keycode, describes the actions associated with a key. The +<structfield>key_acts</structfield> +array has +<structfield>min_key_code</structfield> +unused entries at the start to allow direct indexing using a keycode. If a +<structfield>key_acts</structfield> +entry is +<emphasis>zero</emphasis>, +it means the key does not have any actions associated with it. If an entry is +not +<emphasis>zero</emphasis>, +the entry represents an index into the +<structfield>acts</structfield> +field of the server map, much as the +<structfield>offset</structfield> +field of a +<structname>KeySymMapRec</structname> +structure is an index into the +<structfield>syms</structfield> +field of the client map. +</para> + +<para> +The reason the +<structfield>acts</structfield> +field is a linear list of +<structname>XkbAction</structname>s +is to reduce the memory consumption associated with a keymap. Because Xkb allows individual keys to have multiple shift levels and a different number of -groups per key, a single two-dimensional array of <emphasis> -KeySyms</emphasis> - would potentially be very large and sparse. Instead, Xkb provides a small -two-dimensional array of <emphasis> -XkbAction</emphasis> -s for each key. To store all of these individual arrays, Xkb concatenates each -array together in the <emphasis> -acts</emphasis> - field of the server map. +groups per key, a single two-dimensional array of +<type>KeySym</type>s +would potentially be very large and sparse. Instead, Xkb provides a small +two-dimensional array of +<structname>XkbAction</structname>s +for each key. To store all of these individual arrays, Xkb concatenates each +array together in the +<structfield>acts</structfield> +field of the server map. </para> @@ -163,290 +169,308 @@ Xkb provides the following macros, to simplify accessing information pertaining to key actions: </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbKeyHasActions</emphasis> -(<emphasis> -xkb, keycode</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbKeyHasActions</emphasis> - returns <emphasis> -True</emphasis> - if the key corresponding to <emphasis> -keycode</emphasis> - has any actions associated with it; otherwise, it returns <emphasis> -False</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -int <emphasis> -XkbKeyNumActions</emphasis> -(<emphasis> -xkb, keycode</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbKeyNumActions</emphasis> - computes the number of actions associated with the key corresponding to -<emphasis> -keycode</emphasis> -. This should be the same value as the result of <emphasis> -XkbKeyNumSyms</emphasis> - (see section 15.3.3). -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbKeyActionPtr <emphasis> -XkbKeyActionsPtr</emphasis> -(<emphasis> -xkb, keycode</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbKeyActionsPtr</emphasis> - returns a pointer to the two-dimensional array of key actions associated with -the key corresponding to <emphasis> -keycode</emphasis> -. Use<emphasis> - XkbKeyActionsPtr</emphasis> - only if the key actually has some actions associated with it, that is, -<emphasis> -XkbKeyNumActions</emphasis> +<indexterm significance="preferred" zone="XkbKeyHasActions"><primary><function>XkbKeyHasActions</function></primary></indexterm> +<funcsynopsis id="XkbKeyHasActions"> + <funcprototype> + <funcdef>Bool <function>XkbKeyHasActions</function></funcdef> +<!-- ( +<parameter>xkb, keycode</parameter> +) /* macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbKeyHasActions</function> +returns +<symbol>True</symbol> +if the key corresponding to +<parameter>keycode</parameter> +has any actions associated with it; otherwise, it returns +<symbol>False</symbol>. +</para> + + +<indexterm significance="preferred" zone="XkbKeyNumActions"><primary><function>XkbKeyNumActions</function></primary></indexterm> +<funcsynopsis id="XkbKeyNumActions"> + <funcprototype> + <funcdef>int <function>XkbKeyNumActions</function></funcdef> +<!-- ( +<parameter>xkb, keycode</parameter> +) /* macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbKeyNumActions</function> +computes the number of actions associated with the key corresponding to +<parameter>keycode</parameter>. +This should be the same value as the result of +<function>XkbKeyNumSyms</function> +(see <link linkend="Key_Width">section 15.3.3</link>). +</para> + + +<indexterm significance="preferred" zone="XkbKeyActionsPtr"><primary><function>XkbKeyActionsPtr</function></primary></indexterm> +<funcsynopsis id="XkbKeyActionsPtr"> + <funcprototype> + <funcdef>XkbKeyActionPtr <function>XkbKeyActionsPtr</function></funcdef> +<!-- ( +<parameter>xkb, keycode</parameter> +) /* macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbKeyActionsPtr</function> +returns a pointer to the two-dimensional array of key actions associated with +the key corresponding to +<parameter>keycode</parameter>. +Use +<function>XkbKeyActionsPtr</function> +only if the key actually has some actions associated with it, that is, +<function>XkbKeyNumActions</function> (xkb, keycode) returns something greater than zero. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbAction <emphasis> -XkbKeyAction</emphasis> -(<emphasis> -xkb, keycode, idx</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -idx</emphasis> -; /* index for group and shift level */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbKeyAction"><primary><function>XkbKeyAction</function></primary></indexterm> +<funcsynopsis id="XkbKeyAction"> + <funcprototype> + <funcdef>XkbAction <function>XkbKeyAction</function></funcdef> +<!-- ( +<parameter>xkb, keycode, idx</parameter> +) /* macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + <paramdef>int <parameter>idx</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>idx</parameter> + </term> + <listitem> + <para> + index for group and shift level + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbKeyAction</emphasis> - returns the key action indexed by <emphasis> -idx</emphasis> - in the two-dimensional array of key actions associated with the key -corresponding to <emphasis> -keycode</emphasis> -. <emphasis> -idx</emphasis> - may be computed from the group and shift level of interest as follows: +<function>XkbKeyAction</function> +returns the key action indexed by +<parameter>idx</parameter> +in the two-dimensional array of key actions associated with the key +corresponding to +<parameter>keycode</parameter>. +<parameter>idx</parameter> +may be computed from the group and shift level of interest as follows: </para> <literallayout> idx = group_index * key_width + shift_level </literallayout> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbAction <emphasis> -XkbKeyActionEntry</emphasis> -(<emphasis> -xkb, keycode, shift, grp</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> -keycode</emphasis> -; /* keycode of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -shift</emphasis> -; /* shift level within group */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -grp</emphasis> -; /* group index for group of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbKeyActionEntry"><primary><function>XkbKeyActionEntry</function></primary></indexterm> +<funcsynopsis id="XkbKeyActionEntry"> + <funcprototype> + <funcdef>XkbAction <function>XkbKeyActionEntry</function></funcdef> +<!-- ( +<parameter>xkb, keycode, shift, grp</parameter> +) /* macro */ --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + <paramdef>int <parameter>shift</parameter></paramdef> + <paramdef>int <parameter>grp</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>keycode</parameter> + </term> + <listitem> + <para> + keycode of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>shift</parameter> + </term> + <listitem> + <para> + shift level within group + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>grp</parameter> + </term> + <listitem> + <para> + group index for group of interest + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbKeyActionEntry</emphasis> - returns the key action corresponding to group <emphasis> -grp</emphasis> - and shift level <emphasis> -lvl</emphasis> - from the two-dimensional table of key actions associated with the key -corresponding to <emphasis> -keycode</emphasis> -. +<function>XkbKeyActionEntry</function> +returns the key action corresponding to group +<parameter>grp</parameter> +and shift level +<parameter>shift</parameter> +from the two-dimensional table of key actions associated with the key +corresponding to +<parameter>keycode</parameter>. </para> <sect2 id='The_XkbAction_Structure'> <title>The XkbAction Structure</title> +<indexterm significance="preferred" zone="The_XkbAction_Structure"> +<primary><structname>XkbAction</structname></primary></indexterm> <para> -The description for an action is held in an <emphasis> -XkbAction</emphasis> - structure, which is a union of all possible Xkb action types: -</para> +The description for an action is held in an +<structname>XkbAction</structname> +structure, which is a union of all possible Xkb action types: -<para><programlisting> +<programlisting> typedef union _XkbAction { - XkbAnyAction any; - XkbModAction mods; - XkbGroupAction group; - XkbISOAction iso; - XkbPtrAction ptr; - XkbPtrBtnAction btn; - XkbPtrDfltAction dflt; - XkbSwitchScreenAction screen; - XkbCtrlsAction ctrls; - XkbMessageAction msg; - XkbRedirectKeyAction redirect; - XkbDeviceBtnAction devbtn; - XkbDeviceValuatorAction devval; - unsigned char type; -} <emphasis>XkbAction</emphasis>; + XkbAnyAction any; + XkbModAction mods; + XkbGroupAction group; + XkbISOAction iso; + XkbPtrAction ptr; + XkbPtrBtnAction btn; + XkbPtrDfltAction dflt; + XkbSwitchScreenAction screen; + XkbCtrlsAction ctrls; + XkbMessageAction msg; + XkbRedirectKeyAction redirect; + XkbDeviceBtnAction devbtn; + XkbDeviceValuatorAction devval; + unsigned char type; +} <structname>XkbAction</structname>; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field is provided for convenience and is the same as the type field in the +The +<structfield>type</structfield> +field is provided for convenience and is the same as the type field in the individual structures. The following sections describe the individual structures for each action in detail. </para> @@ -455,36 +479,36 @@ structures for each action in detail. </sect2> <sect2 id='The_XkbAnyAction_Structure'> <title>The XkbAnyAction Structure</title> +<indexterm significance="preferred" zone="The_XkbAnyAction_Structure"> +<primary><structname>XkbAnyAction</structname></primary></indexterm> <para> -The <emphasis> -XkbAnyAction</emphasis> - structure is a convenience structure that refers to any of the actions: -</para> +The +<structname>XkbAnyAction</structname> +structure is a convenience structure that refers to any of the actions: -<para><programlisting> +<programlisting> #define XkbAnyActionDataSize 7 -</programlisting></para> -<para><programlisting> typedef struct _XkbAnyAction { - unsigned char type; /* type of action; determines interpretation for data */ - unsigned char data[XkbAnyActionDataSize]; -} <emphasis>XkbAnyAction</emphasis>; + unsigned char type; /* type of action; determines interpretation for data */ + unsigned char data[XkbAnyActionDataSize]; +} <structname>XkbAnyAction</structname>; </programlisting></para> <para> -The <emphasis> -data</emphasis> - field represents a structure for an action, and its interpretation depends on -the <emphasis> -type</emphasis> - field. The valid values for the <emphasis> -type</emphasis> - field, and the data structures associated with them are shown in Table 16.1: +The +<structfield>data</structfield> +field represents a structure for an action, and its interpretation depends on +the +<structfield>type</structfield> +field. The valid values for the +<structfield>type</structfield> +field, and the data structures associated with them are shown in +<link linkend="table16.1">Table 16.1</link>: </para> -<table frame='topbot'> +<table id='table16.1' frame='topbot'> <title>Action Types</title> <?dbfo keep-together="always" ?> <tgroup cols='4' align='left' colsep='0' rowsep='0'> @@ -502,10 +526,10 @@ type</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_NoAction</emphasis></entry> + <entry><symbol>XkbSA_NoAction</symbol></entry> <entry> -<emphasis>XkbSA_NoAction</emphasis> - means the server does not perform an action for the key; this action does not +<symbol>XkbSA_NoAction</symbol> +means the server does not perform an action for the key; this action does not have an associated data structure. </entry> <entry>any</entry> @@ -513,91 +537,91 @@ have an associated data structure. </row> <row> <entry> -<para><emphasis>XkbSA_SetMods</emphasis></para> -<para><emphasis>XkbSA_LatchMods</emphasis></para> -<para><emphasis>XkbSA_LockMods</emphasis></para> +<para><symbol>XkbSA_SetMods</symbol></para> +<para><symbol>XkbSA_LatchMods</symbol></para> +<para><symbol>XkbSA_LockMods</symbol></para> </entry> - <entry><para><emphasis>XkbModAction</emphasis></para></entry> + <entry><para><structname>XkbModAction</structname></para></entry> <entry>mods</entry> - <entry>16.1.3</entry> + <entry><link linkend="Actions_for_Changing_Modifiers_State">16.1.3</link></entry> </row> <row> <entry> -<para><emphasis>XkbSA_SetGroup</emphasis></para> -<para><emphasis>XkbSA_LatchGroup</emphasis></para> -<para><emphasis>XkbSA_LockGroup</emphasis></para> +<para><symbol>XkbSA_SetGroup</symbol></para> +<para><symbol>XkbSA_LatchGroup</symbol></para> +<para><symbol>XkbSA_LockGroup</symbol></para> </entry> - <entry><emphasis>XkbGroupAction</emphasis></entry> + <entry><structname>XkbGroupAction</structname></entry> <entry>group</entry> - <entry>16.1.4</entry> + <entry><link linkend="Actions_for_Changing_Group_State">16.1.4</link></entry> </row> <row> - <entry><emphasis>XkbSA_MovePtr</emphasis></entry> - <entry><emphasis>XkbPtrAction</emphasis></entry> + <entry><symbol>XkbSA_MovePtr</symbol></entry> + <entry><structname>XkbPtrAction</structname></entry> <entry>ptr</entry> - <entry>16.1.5</entry> + <entry><link linkend="Actions_for_Moving_the_Pointer">16.1.5</link></entry> </row> <row> <entry> -<para><emphasis>XKbSA_PtrBtn</emphasis></para> -<para><emphasis>XkbSA_LockPtrBtn</emphasis></para> +<para><symbol>XkbSA_PtrBtn</symbol></para> +<para><symbol>XkbSA_LockPtrBtn</symbol></para> </entry> - <entry><emphasis>XkbPtrBtnAction</emphasis></entry><entry>btn</entry> - <entry>16.1.6</entry> + <entry><structname>XkbPtrBtnAction</structname></entry><entry>btn</entry> + <entry><link linkend="Actions_for_Simulating_Pointer_Button_Press_and_Release">16.1.6</link></entry> </row> <row> - <entry><emphasis>XkbSA_SetPtrDflt</emphasis></entry> - <entry><emphasis>XkbPtrDfltAction</emphasis></entry> + <entry><symbol>XkbSA_SetPtrDflt</symbol></entry> + <entry><structname>XkbPtrDfltAction</structname></entry> <entry>dflt</entry> - <entry>16.1.7</entry> + <entry><link linkend="Actions_for_Changing_the_Pointer_Button_Simulated">16.1.7</link></entry> </row> <row> - <entry><emphasis>XkbSA_ISOLock</emphasis></entry> - <entry><emphasis>XkbISOAction</emphasis></entry> + <entry><symbol>XkbSA_ISOLock</symbol></entry> + <entry><structname>XkbISOAction</structname></entry> <entry>iso</entry> - <entry>16.1.8</entry> + <entry><link linkend="Actions_for_Locking_Modifiers_and_Group">16.1.8</link></entry> </row> <row> - <entry><emphasis>XkbSA_SwitchScreen</emphasis></entry> - <entry><emphasis>XkbSwitchScreenAction</emphasis></entry> + <entry><symbol>XkbSA_SwitchScreen</symbol></entry> + <entry><structname>XkbSwitchScreenAction</structname></entry> <entry>screen</entry> - <entry>16.1.9</entry> + <entry><link linkend="Actions_for_Changing_the_Active_Screen">16.1.9</link></entry> </row> <row> <entry> -<para><emphasis>XkbSA_SetControls</emphasis></para> -<para><emphasis>XkbSA_LockControls</emphasis></para> +<para><symbol>XkbSA_SetControls</symbol></para> +<para><symbol>XkbSA_LockControls</symbol></para> </entry> - <entry><emphasis>XkbCtrlsAction</emphasis></entry> + <entry><structname>XkbCtrlsAction</structname></entry> <entry>ctrls</entry> - <entry>16.1.10</entry> + <entry><link linkend="Actions_for_Changing_Boolean_Controls_State">16.1.10</link></entry> </row> <row> - <entry><emphasis>XkbSA_ActionMessage</emphasis></entry> - <entry><emphasis>XkbMessgeAction</emphasis></entry> + <entry><symbol>XkbSA_ActionMessage</symbol></entry> + <entry><structname>XkbMessageAction</structname></entry> <entry>msg</entry> - <entry>16.1.11</entry> + <entry><link linkend="Actions_for_Generating_Messages">16.1.11</link></entry> </row> <row> - <entry><emphasis>XkbSA_RedirectKey</emphasis></entry> - <entry><emphasis>XkbRedirectKeyAction</emphasis></entry> + <entry><symbol>XkbSA_RedirectKey</symbol></entry> + <entry><structname>XkbRedirectKeyAction</structname></entry> <entry>redirect</entry> - <entry>16.1.12</entry> + <entry><link linkend="Actions_for_Generating_a_Different_Keycode">16.1.12</link></entry> </row> <row> <entry> -<para><emphasis>XkbSA_DeviceBtn</emphasis></para> -<para><emphasis>XKbSA_LockDeviceBtn</emphasis></para> +<para><symbol>XkbSA_DeviceBtn</symbol></para> +<para><symbol>XkbSA_LockDeviceBtn</symbol></para> </entry> - <entry><emphasis>XkbDeviceBtnAction</emphasis></entry> + <entry><structname>XkbDeviceBtnAction</structname></entry> <entry>devbtn</entry> - <entry>16.1.13</entry> + <entry><link linkend="Actions_for_Generating_DeviceButtonPress_and_DeviceButtonRelease">16.1.13</link></entry> </row> <row> - <entry><emphasis>XkbSA_DeviceValuator</emphasis></entry> - <entry><emphasis>XkbDeviceValuatorAction</emphasis></entry> + <entry><symbol>XkbSA_DeviceValuator</symbol></entry> + <entry><structname>XkbDeviceValuatorAction</structname></entry> <entry>devval</entry> - <entry>16.1.14</entry> + <entry><link linkend="Actions_for_Simulating_Events_from_Device_Valuators">16.1.14</link></entry> </row> </tbody> </tgroup> @@ -606,53 +630,63 @@ have an associated data structure. </sect2> <sect2 id='Actions_for_Changing_Modifiers_State'> <title>Actions for Changing Modifiers’ State</title> +<indexterm significance="preferred" zone="Actions_for_Changing_Modifiers_State"> +<primary><structname>XkbModAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbModAction</emphasis> - structure change the state of the modifiers when keys are pressed and released -(see Chapter 7 for a discussion of modifiers): -</para> +Actions associated with the +<structname>XkbModAction</structname> +structure change the state of the modifiers when keys are pressed and released +(see <xref linkend="Virtual_Modifiers" /> for a discussion of modifiers): -<para><programlisting> +<programlisting> typedef struct _XkbModAction { - unsigned char type; /* <emphasis> XkbSA_{Set|Latch|Lock}Mods</emphasis> */ - unsigned char flags; /* with <emphasis> type</emphasis> , controls the effect on modifiers */ - unsigned char mask; /* same as <emphasis> mask</emphasis> field of a modifier description */ - unsigned char real_mods; /* same as <emphasis> real_mods</emphasis> field of a modifier description */ - unsigned char vmods1; /* derived from <emphasis> vmods</emphasis> field of a modifier description */ - unsigned char vmods2; /* derived from <emphasis> vmods</emphasis> field of a modifier description */ -} <emphasis>XkbModAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_{Set|Latch|Lock}Mods</symbol> */ + unsigned char flags; /* with <structfield>type</structfield>, controls the effect + on modifiers */ + unsigned char mask; /* same as <structfield>mask</structfield> field of + a modifier description */ + unsigned char real_mods; /* same as <structfield>real_mods</structfield> field of + a modifier description */ + unsigned char vmods1; /* derived from <structfield>vmods</structfield> field of + a modifier description */ + unsigned char vmods2; /* derived from <structfield>vmods</structfield> field of + a modifier description */ +} <structname>XkbModAction</structname>; </programlisting></para> <para> -In the following description, the term <emphasis> -action modifiers</emphasis> - means the real modifier bits associated with this action. Depending on the -value of <emphasis> -flags</emphasis> - (see Table 16.3), these are designated either in the <emphasis> -mask</emphasis> - field of the <emphasis> -XkbModAction</emphasis> - structure itself or the real modifiers bound to the key for which the action -is being used. In the latter case, this is the client <emphasis> -map</emphasis> --><emphasis> -modmap</emphasis> -[<emphasis> -keycode</emphasis> +In the following description, the term +<firstterm>action modifiers</firstterm> +<indexterm significance="preferred" zone="Actions_for_Changing_Modifiers_State"> +<primary>action modifiers</primary></indexterm> +<indexterm significance="preferred" zone="Actions_for_Changing_Modifiers_State"> +<primary>modifiers</primary><secondary>action</secondary></indexterm> +means the real modifier bits associated with this action. Depending on the +value of +<structfield>flags</structfield> +(see <link linkend="table16.3">Table 16.3</link>), +these are designated either in the +<structfield>mask</structfield> +field of the +<structname>XkbModAction</structname> +structure itself or the real modifiers bound to the key for which the action +is being used. In the latter case, this is the client +<structfield>map</structfield>-><structfield>modmap</structfield> +[ +<parameter>keycode</parameter> ] field. </para> <para> -The <emphasis> -type</emphasis> - field can have any of the values shown in Table 16.2. +The +<structfield>type</structfield> +field can have any of the values shown in +<link linkend="table16.2">Table 16.2</link>. </para> -<table frame='topbot'> +<table id='table16.2' frame='topbot'> <title>Modifier Action Types</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -666,7 +700,7 @@ type</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_SetMods</emphasis></entry> + <entry><symbol>XkbSA_SetMods</symbol></entry> <entry> <itemizedlist> <listitem> @@ -683,78 +717,77 @@ provided no other key affecting the same modifiers is logically down. <listitem> <para> If no other keys are physically depressed when this key is released, and -<emphasis> -XkbSA_ClearLocks</emphasis> - is set in the <emphasis> -flags</emphasis> - field, the key release unlocks any action modifiers. +<symbol>XkbSA_ClearLocks</symbol> +is set in the +<structfield>flags</structfield> +field, the key release unlocks any action modifiers. </para> </listitem> </itemizedlist> </entry> </row> <row> - <entry><emphasis>XkbSA_LatchMods</emphasis></entry> + <entry><symbol>XkbSA_LatchMods</symbol></entry> <entry> <itemizedlist> <listitem> <para> -Key press and key release events have the same effect as for <emphasis> -XkbSA_SetMods</emphasis> -; if no keys are physically depressed when this key is released, key release +Key press and key release events have the same effect as for +<symbol>XkbSA_SetMods</symbol>; +if no keys are physically depressed when this key is released, key release events have the following additional effects: </para> </listitem> <listitem> <para> -Modifiers unlocked due to <emphasis> -XkbSA_ClearLocks</emphasis> - have no further effect. +Modifiers unlocked due to +<symbol>XkbSA_ClearLocks</symbol> +have no further effect. </para> </listitem> <listitem> <para> -If <emphasis> -XkbSA_LatchToLock</emphasis> - is set in the <emphasis> -flags</emphasis> - field, a key release locks and then unlatches any remaining action modifiers +If +<symbol>XkbSA_LatchToLock</symbol> +is set in the +<structfield>flags</structfield> +field, a key release locks and then unlatches any remaining action modifiers that are already latched. </para> </listitem> <listitem> <para> -A key release latches any action modifiers not used by the <emphasis> -XkbSA_ClearLocks</emphasis> - and <emphasis> -XkbSA_LatchToLock</emphasis> - flags. +A key release latches any action modifiers not used by the +<symbol>XkbSA_ClearLocks</symbol> +and +<symbol>XkbSA_LatchToLock</symbol> +flags. </para> </listitem> </itemizedlist> </entry> </row> <row> - <entry><emphasis>XkbSA_LockMods</emphasis></entry> + <entry><symbol>XkbSA_LockMods</symbol></entry> <entry> <itemizedlist> <listitem> <para> -A key press sets the base state of any action modifiers. If <emphasis> -XkbSA_LockNoLock</emphasis> - is set in the <emphasis> -flags</emphasis> - field, a key press also sets the locked state of any action modifiers. +A key press sets the base state of any action modifiers. If +<symbol>XkbSA_LockNoLock</symbol> +is set in the +<structfield>flags</structfield> +field, a key press also sets the locked state of any action modifiers. </para> </listitem> <listitem> <para> A key release clears any action modifiers in the keyboard’s base modifiers, -provided no other key that affects the same modifiers is down. If <emphasis> -XkbSA_LockNoUnlock</emphasis> - is not set in the <emphasis> -flags</emphasis> - field, and any of the action modifiers were locked before the corresponding +provided no other key that affects the same modifiers is down. If +<symbol>XkbSA_LockNoUnlock</symbol> +is not set in the +<structfield>flags</structfield> +field, and any of the action modifiers were locked before the corresponding key press occurred, a key release unlocks them. </para> </listitem> @@ -766,14 +799,15 @@ key press occurred, a key release unlocks them. </table> <para> -The <emphasis> -flags</emphasis> - field is composed of the bitwise inclusive OR of the masks shown in Table -16.3. A general meaning is given in the table, but the exact meaning depends on -the action <emphasis>type</emphasis>. +The +<structfield>flags</structfield> +field is composed of the bitwise inclusive OR of the masks shown in +<link linkend="table16.3">Table 16.3</link>. +A general meaning is given in the table, but the exact meaning depends on +the action <structfield>type</structfield>. </para> -<table frame='topbot'> +<table id='table16.3' frame='topbot'> <title>Modifier Action Flags</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -787,50 +821,48 @@ the action <emphasis>type</emphasis>. </thead> <tbody> <row> - <entry><emphasis>XkbSA_UseModMapMods</emphasis></entry> + <entry><symbol>XkbSA_UseModMapMods</symbol></entry> <entry> If set, the action modifiers are determined by the modifiers bound by the modifier mapping of the key. Otherwise, the action modifiers are set to the -modifiers specified by the <emphasis> -mask</emphasis> -, <emphasis> -real_mods</emphasis> -, <emphasis> -vmod1</emphasis> -, and <emphasis> -vmod2</emphasis> - fields. +modifiers specified by the +<structfield>mask</structfield>, +<structfield>real_mods</structfield>, +<structfield>vmods1</structfield>, +and +<structfield>vmods2</structfield> +fields. </entry> </row> <row> - <entry><emphasis>XkbSA_ClearLocks</emphasis></entry> + <entry><symbol>XkbSA_ClearLocks</symbol></entry> <entry> If set and no keys are physically depressed when this key transition occurs, the server unlocks any action modifiers. </entry> </row> <row> - <entry><emphasis>XkbSA_LatchToLock</emphasis></entry> + <entry><symbol>XkbSA_LatchToLock</symbol></entry> <entry> -If set, and the action type is <emphasis> -XkbSA_LatchMods</emphasis> -, the server locks the action modifiers if they are already latched. +If set, and the action type is +<symbol>XkbSA_LatchMods</symbol>, +the server locks the action modifiers if they are already latched. </entry> </row> <row> - <entry><emphasis>XkbSA_LockNoLock</emphasis></entry> + <entry><symbol>XkbSA_LockNoLock</symbol></entry> <entry> -If set, and the action type is <emphasis> -XkbSA_LockMods</emphasis> -, the server only unlocks the action modifiers. +If set, and the action type is +<symbol>XkbSA_LockMods</symbol>, +the server only unlocks the action modifiers. </entry> </row> <row> - <entry><emphasis>XkbSA_LockNoUnlock</emphasis></entry> + <entry><symbol>XkbSA_LockNoUnlock</symbol></entry> <entry> -If set, and the action is <emphasis> -XkbSA_LockMods</emphasis> -, the server only locks the action modifiers. +If set, and the action is +<symbol>XkbSA_LockMods</symbol>, +the server only locks the action modifiers. </entry> </row> </tbody> @@ -838,177 +870,172 @@ XkbSA_LockMods</emphasis> </table> <para> -If <emphasis> -XkbSA_UseModMapMods</emphasis> - is not set in the <emphasis> -flags</emphasis> - field, the <emphasis> -mask</emphasis> -, <emphasis> -real_mods</emphasis> -, <emphasis> -vmods1</emphasis> -, and <emphasis> -vmods2 </emphasis> +If +<symbol>XkbSA_UseModMapMods</symbol> +is not set in the +<structfield>flags</structfield> +field, the +<structfield>mask</structfield>, +<structfield>real_mods</structfield>, +<structfield>vmods1</structfield>, +and +<structfield>vmods2</structfield> fields are used to determine the action modifiers. Otherwise they are ignored -and the modifiers bound to the key (client <emphasis> -map</emphasis> --><emphasis> -modmap</emphasis> -[<emphasis> -keycode</emphasis> +and the modifiers bound to the key (client +<structfield>map</structfield>-><structfield>modmap</structfield> +[ +<parameter>keycode</parameter> ]) are used instead. </para> <para> -The <emphasis> -mask</emphasis> -, <emphasis> -real_mods</emphasis> -, <emphasis> -vmods1</emphasis> -, and <emphasis> -vmods2</emphasis> - fields represent the components of an Xkb modifier description (see section -7.2). While the <emphasis> -mask</emphasis> - and <emphasis> -real_mods</emphasis> - fields correspond directly to the <emphasis> -mask</emphasis> - and <emphasis> -real_mods</emphasis> - fields of an Xkb modifier description, the <emphasis> -vmods1</emphasis> - and <emphasis> -vmods2</emphasis> - fields are combined to correspond to the <emphasis> -vmods</emphasis> - field of an Xkb modifier description. Xkb provides the following macros, to +The +<structfield>mask</structfield>, +<structfield>real_mods</structfield>, +<structfield>vmods1</structfield>, +and +<structfield>vmods2</structfield> +fields represent the components of an Xkb modifier description +(see <link linkend="Modifier_Definitions">section 7.2</link>). While the +<structfield>mask</structfield> +and +<structfield>real_mods</structfield> +fields correspond directly to the +<structfield>mask</structfield> +and +<structfield>real_mods</structfield> +fields of an Xkb modifier description, the +<structfield>vmods1</structfield> +and +<structfield>vmods2</structfield> +fields are combined to correspond to the +<structfield>vmods</structfield> +field of an Xkb modifier description. Xkb provides the following macros, to convert between the two formats: </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -unsigned short <emphasis> -XkbModActionVMods</emphasis> -(<emphasis> -act</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbAction <emphasis> -act</emphasis> -; /* action from which to extract virtual mods */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbModActionVMods</emphasis> - returns the <emphasis> -vmods1</emphasis> - and <emphasis> -vmods2</emphasis> - fields of <emphasis> -act</emphasis> - converted to the <emphasis> -vmods</emphasis> - format of an Xkb modifier description. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbSetModActionVMods</emphasis> -(<emphasis> -act, vmods</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbAction <emphasis> -act</emphasis> -; /* action in which to set vmods */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned short <emphasis> -vmods</emphasis> -; /* virtual mods to set */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbModActionVMods"><primary><function>XkbModActionVMods</function></primary></indexterm> +<funcsynopsis id="XkbModActionVMods"> + <funcprototype> + <funcdef>unsigned short <function>XkbModActionVMods</function></funcdef> +<!-- ( +<parameter>act</parameter> +) /* macro */ --> + + <paramdef>XkbAction <parameter>act</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to extract virtual mods + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbModActionVMods</function> +returns the +<structfield>vmods1</structfield> +and +<structfield>vmods2</structfield> +fields of +<parameter>act</parameter> +converted to the +<structfield>vmods</structfield> +format of an Xkb modifier description. +</para> + + +<indexterm significance="preferred" zone="XkbSetModActionVMods"><primary><function>XkbSetModActionVMods</function></primary></indexterm> +<funcsynopsis id="XkbSetModActionVMods"> + <funcprototype> + <funcdef>void <function>XkbSetModActionVMods</function></funcdef> +<!-- ( +<parameter>act, vmods</parameter> +) /* macro */ --> + + <paramdef>XkbAction <parameter>act</parameter></paramdef> + <paramdef>unsigned short <parameter>vmods</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action in which to set vmods + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>vmods</parameter> + </term> + <listitem> + <para> + virtual mods to set + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbSetModActionVMods</emphasis> - sets the <emphasis> -vmods1</emphasis> - and <emphasis> -vmods2</emphasis> - fields of <emphasis> -act</emphasis> - using the <emphasis> -vmods</emphasis> - format of an Xkb modifier description. +<function>XkbSetModActionVMods</function> +sets the +<structfield>vmods1</structfield> +and +<structfield>vmods2</structfield> +fields of +<parameter>act</parameter> +using the +<parameter>vmods</parameter> +format of an Xkb modifier description. </para> <note><para>Despite the fact that the first parameter of these two macros is of -type XkbAction, these macros may be used only with Actions of type <emphasis> -XkbModAction</emphasis> - and <emphasis> -XkbISOAction</emphasis> -.</para></note> +type XkbAction, these macros may be used only with Actions of type +<structname>XkbModAction</structname> +and +<structname>XkbISOAction</structname>. +</para></note> </sect2> <sect2 id='Actions_for_Changing_Group_State'> <title>Actions for Changing Group State</title> +<indexterm significance="preferred" zone="Actions_for_Changing_Group_State"> +<primary><structname>XkbGroupAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbGroupAction</emphasis> - structure change the current group state when keys are pressed and released -(see Chapter 5 for a description of groups and keyboard state): -</para> +Actions associated with the +<structname>XkbGroupAction</structname> +structure change the current group state when keys are pressed and released +(see <xref linkend="Keyboard_State" /> for a description of groups and keyboard state): -<para><programlisting> +<programlisting> typedef struct _XkbGroupAction { - unsigned char type; /* <emphasis> XkbSA_{Set|Latch|Lock}Group</emphasis> */ - unsigned char flags; /* with <emphasis> type</emphasis> , controls the effect on groups */ - char group_XXX; /* represents a group index or delta */ -} <emphasis>XkbGroupAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_{Set|Latch|Lock}Group</symbol> */ + unsigned char flags; /* with <structfield>type</structfield> , controls the effect on groups */ + char group_XXX; /* represents a group index or delta */ +} <structname>XkbGroupAction</structname>; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field can have any of the following values: +The +<structfield>type</structfield> +field can have any of the following values: </para> -<table frame='topbot'> +<table id='table16.4' frame='topbot'> <title>Group Action Types</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1022,76 +1049,72 @@ type</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_SetGroup</emphasis></entry> + <entry><symbol>XkbSA_SetGroup</symbol></entry> <entry> <itemizedlist> <listitem> <para> -If the <emphasis> -XkbSA_GroupAbsolute</emphasis> - bit is set in the <emphasis> -flags</emphasis> - field, key press events change the base keyboard group to the group specified -by the <emphasis> -group_XXX</emphasis> - field. Otherwise, key press events change the base keyboard group by adding -the <emphasis> -group_XXX</emphasis> - field to the base keyboard group. In either case, the resulting effective +If the +<symbol>XkbSA_GroupAbsolute</symbol> +bit is set in the +<structfield>flags</structfield> +field, key press events change the base keyboard group to the group specified +by the +<structfield>group_XXX</structfield> +field. Otherwise, key press events change the base keyboard group by adding +the +<structfield>group_XXX</structfield> +field to the base keyboard group. In either case, the resulting effective keyboard group is brought back into range depending on the value of the -<emphasis> -groups_wrap</emphasis> - field of the controls structure (see section 10.7.1). +<structfield>groups_wrap</structfield> +field of the controls structure (see <link linkend="The_GroupsWrap_Control">section 10.7.1</link>). </para> </listitem> <listitem> <para> -If a key with an <emphasis> -XkbSA_ISOLock</emphasis> - action (see section 16.1.8) is pressed while this key is down, the key release +If a key with an +<symbol>XkbSA_ISOLock</symbol> +action (see <link linkend="Actions_for_Locking_Modifiers_and_Group">section 16.1.8</link>) is pressed while this key is down, the key release of this key has no effect. Otherwise, the key release cancels the effects of the key press. </para> </listitem> <listitem> <para> -If the <emphasis> -XkbSA_ClearLocks</emphasis> - bit is set in the flags field, and no keys are physically depressed when this +If the +<symbol>XkbSA_ClearLocks</symbol> +bit is set in the flags field, and no keys are physically depressed when this key is released, the key release also sets the locked keyboard group to -<emphasis> -Group1</emphasis> -. - </para> +<emphasis>Group1</emphasis>. +</para> </listitem> </itemizedlist> </entry> </row> <row> - <entry><emphasis>XkbSA_LatchGroup</emphasis></entry> + <entry><symbol>XkbSA_LatchGroup</symbol></entry> <entry> <itemizedlist> <listitem> <para> -Key press and key release events have the same effect as for <emphasis> -XkbSA_SetGroup</emphasis> -; if no keys are physically depressed when this key is released, key release +Key press and key release events have the same effect as for +<symbol>XkbSA_SetGroup</symbol>; +if no keys are physically depressed when this key is released, key release events have the following additional effects. </para> </listitem> <listitem> <para> -If the <emphasis> -XkbSA_LatchToLock</emphasis> - bit is set in the <emphasis> -flags</emphasis> - field and the latched keyboard group index is nonzero, the key release adds +If the +<symbol>XkbSA_LatchToLock</symbol> +bit is set in the +<structfield>flags</structfield> +field and the latched keyboard group index is nonzero, the key release adds the delta applied by the corresponding key press to the locked keyboard group and subtracts it from the latched keyboard group. The locked and effective keyboard group are brought back into range according to the value of the -<emphasis> -groups_wrap</emphasis> - field of the controls structure. +<structfield>groups_wrap</structfield> +field of the controls structure. </para> </listitem> <listitem> @@ -1103,25 +1126,25 @@ Otherwise, the key press adds the key press delta to the latched keyboard group. </entry> </row> <row> - <entry><emphasis>XkbSA_LockGroup</emphasis></entry> + <entry><symbol>XkbSA_LockGroup</symbol></entry> <entry> <itemizedlist> <listitem> <para> -If the <emphasis> -XkbSA_GroupAbsolute</emphasis> - is set in the <emphasis> -flags</emphasis> - field, key press events set the locked keyboard group to the group specified -by the <emphasis> -group_XXX</emphasis> - field. Otherwise, key press events add the group specified by the <emphasis> -group_XXX</emphasis> - field to the locked keyboard group. In either case, the resulting locked and +If the +<symbol>XkbSA_GroupAbsolute</symbol> +is set in the +<structfield>flags</structfield> +field, key press events set the locked keyboard group to the group specified +by the +<structfield>group_XXX</structfield> +field. Otherwise, key press events add the group specified by the +<structfield>group_XXX</structfield> +field to the locked keyboard group. In either case, the resulting locked and effective keyboard groups are brought back into range depending on the value of -the <emphasis> -groups_wrap</emphasis> - field of the controls structure. +the +<structfield>groups_wrap</structfield> +field of the controls structure. </para> </listitem> <listitem> @@ -1137,16 +1160,16 @@ A key release has no effect. </table> <para> -The <emphasis> -flags</emphasis> - field is composed of the bitwise inclusive OR of the masks shown in Table -16.5. A general meaning is given in the table, but the exact meaning depends on -the action <emphasis> -type</emphasis> -. +The +<structfield>flags</structfield> +field is composed of the bitwise inclusive OR of the masks shown in +<link linkend="table16.5">Table 16.5</link>. +A general meaning is given in the table, but the exact meaning depends on +the action +<structfield>type</structfield>. </para> -<table frame='topbot'> +<table id='table16.5' frame='topbot'> <title>Group Action Flags</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1160,28 +1183,28 @@ type</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_ClearLocks</emphasis></entry> + <entry><symbol>XkbSA_ClearLocks</symbol></entry> <entry> If set and no keys are physically depressed when this key transition occurs, -the server sets the locked keyboard group to <emphasis> -Group1</emphasis> - on a key release. +the server sets the locked keyboard group to +<emphasis>Group1</emphasis> +on a key release. </entry> </row> <row> - <entry><emphasis>XkbSA_LatchToLock</emphasis></entry> + <entry><symbol>XkbSA_LatchToLock</symbol></entry> <entry> -If set, and the action type is <emphasis> -SA_LatchGroup</emphasis> -, the server locks the action group if it is already latched. +If set, and the action type is +<symbol>XkbSA_LatchGroup</symbol>, +the server locks the action group if it is already latched. </entry> </row> <row> - <entry><emphasis>XkbSA_GroupAbsolute</emphasis></entry> + <entry><symbol>XkbSA_GroupAbsolute</symbol></entry> <entry> -If set, the <emphasis> -group_XXX</emphasis> - field represents an absolute group number. Otherwise, it represents a group +If set, the +<structfield>group_XXX</structfield> +field represents an absolute group number. Otherwise, it represents a group delta to be added to the current group to determine the new group number. </entry> </row> @@ -1190,170 +1213,168 @@ delta to be added to the current group to determine the new group number. </table> <para> -The <emphasis> -group_XXX</emphasis> - field represents a signed character. Xkb provides the following macros to +The +<structfield>group_XXX</structfield> +field represents a signed character. Xkb provides the following macros to convert between a signed integer value and a signed character: </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -int <emphasis> -XkbSAGroup</emphasis> -(<emphasis> -act</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbAction <emphasis> -act</emphasis> -; /* action from which to extract group */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSAGroup</emphasis> - returns the <emphasis> -group_XXX</emphasis> - field of <emphasis> -act</emphasis> - converted to a signed int. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbSASetGroup</emphasis> -(<emphasis> -act, grp</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbAction <emphasis> -act</emphasis> -; /* action from which to set group */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -grp</emphasis> -; /* group index to set in <emphasis> -group_XXX</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbSAGroup"><primary><function>XkbSAGroup</function></primary></indexterm> +<funcsynopsis id="XkbSAGroup"> + <funcprototype> + <funcdef>int <function>XkbSAGroup</function></funcdef> +<!-- ( +<parameter>act</parameter> +) /* macro */ --> + + <paramdef>XkbAction <parameter>act</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to extract group + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSAGroup</function> +returns the +<structfield>group_XXX</structfield> +field of +<parameter>act</parameter> +converted to a signed int. +</para> + + +<indexterm significance="preferred" zone="XkbSASetGroup"><primary><function>XkbSASetGroup</function></primary></indexterm> +<funcsynopsis id="XkbSASetGroup"> + <funcprototype> + <funcdef>void <function>XkbSASetGroup</function></funcdef> +<!-- ( +<parameter>act, grp</parameter> +) /* macro */ --> + + <paramdef>XkbAction <parameter>act</parameter></paramdef> + <paramdef>int <parameter>grp</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to set group + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>grp</parameter> + </term> + <listitem> + <para> + group index to set in <structfield>group_XXX</structfield> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbSASetGroup</emphasis> - sets the <emphasis> -group_XXX</emphasis> - field of <emphasis> -act</emphasis> - from the group index <emphasis> -grp</emphasis> -. +<function>XkbSASetGroup</function> +sets the +<structfield>group_XXX</structfield> +field of +<parameter>act</parameter> +from the group index +<parameter>grp</parameter>. </para> <note><para>Despite the fact that the first parameter of these two macros is of -type XkbAction, these macros may only be used with Actions of type <emphasis> -XkbGroupAction</emphasis> - and <emphasis> -XkbISOAction</emphasis> -.</para></note> +type XkbAction, these macros may only be used with Actions of type +<structname>XkbGroupAction</structname> +and +<structname>XkbISOAction</structname>. +</para></note> </sect2> <sect2 id='Actions_for_Moving_the_Pointer'> <title>Actions for Moving the Pointer</title> +<indexterm significance="preferred" zone="Actions_for_Moving_the_Pointer"> +<primary><structname>XkbPtrAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbPtrAction</emphasis> - structure move the pointer when keys are pressed and released: -</para> +Actions associated with the +<structname>XkbPtrAction</structname> +structure move the pointer when keys are pressed and released: -<para><programlisting> +<programlisting> typedef struct _XkbPtrAction { - unsigned char type; /* <emphasis> XkbSA_MovePtr</emphasis> */ - unsigned char flags; /* determines type of pointer motion */ - unsigned char high_XXX; /* x coordinate, high bits*/ - unsigned char low_XXX; /* y coordinate, low bits */ - unsigned char high_YYY; /* x coordinate, high bits */ - unsigned char low_YYY; /* y coordinate, low bits */ -} <emphasis>XkbPtrAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_MovePtr</symbol> */ + unsigned char flags; /* determines type of pointer motion */ + unsigned char high_XXX; /* x coordinate, high bits */ + unsigned char low_XXX; /* y coordinate, low bits */ + unsigned char high_YYY; /* x coordinate, high bits */ + unsigned char low_YYY; /* y coordinate, low bits */ +} <structname>XkbPtrAction</structname>; </programlisting></para> <para> -If the <emphasis> -MouseKeys</emphasis> - control is not enabled (see section 10.5.1), <emphasis> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events are treated as though the action is <emphasis> -XkbSA_NoAction</emphasis>. +If the +<emphasis>MouseKeys</emphasis> +control is not enabled (see <link linkend="The_MouseKeys_Control">section 10.5.1</link>), +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events are treated as though the action is +<symbol>XkbSA_NoAction</symbol>. </para> <para> -If the <emphasis> -MouseKeys</emphasis> - control is enabled, a server action of type <emphasis> -XkbSA_MovePtr</emphasis> - instructs the server to generate core pointer <emphasis> -MotionNotify</emphasis> - events rather than the usual <emphasis> -KeyPress</emphasis> - event, and the corresponding <emphasis> -KeyRelease</emphasis> - event disables any mouse keys timers that were created as a result of handling -the <emphasis> -XkbSA_MovePtr</emphasis> - action. +If the +<emphasis>MouseKeys</emphasis> +control is enabled, a server action of type +<symbol>XkbSA_MovePtr</symbol> +instructs the server to generate core pointer +<symbol>MotionNotify</symbol> +events rather than the usual +<symbol>KeyPress</symbol> +event, and the corresponding +<symbol>KeyRelease</symbol> +event disables any mouse keys timers that were created as a result of handling +the +<symbol>XkbSA_MovePtr</symbol> +action. </para> <para> -The <emphasis> -type</emphasis> - field of the <emphasis> -XkbPtrAction</emphasis> - structure is always <emphasis> -XkbSA_MovePtr</emphasis> -. +The +<structfield>type</structfield> +field of the +<structname>XkbPtrAction</structname> +structure is always +<symbol>XkbSA_MovePtr</symbol>. </para> <para> -The <emphasis> -flags</emphasis> - field is a bitwise inclusive OR of the masks shown in Table 16.6. +The +<structfield>flags</structfield> +field is a bitwise inclusive OR of the masks shown in +<link linkend="table16.6">Table 16.6</link>. </para> -<table frame='topbot'> +<table id='table16.6' frame='topbot'> <title>Pointer Action Types</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1367,25 +1388,25 @@ flags</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_NoAcceleration</emphasis></entry> + <entry><symbol>XkbSA_NoAcceleration</symbol></entry> <entry> -If not set, and the <emphasis> -MouseKeysAccel</emphasis> - control is enabled (see section 10.5.2), the <emphasis> -KeyPress</emphasis> - initiates a mouse keys timer for this key; every time the timer expires, the +If not set, and the +<emphasis>MouseKeysAccel</emphasis> +control is enabled (see <link linkend="The_MouseKeysAccel_Control">section 10.5.2</link>), the +<symbol>KeyPress</symbol> +initiates a mouse keys timer for this key; every time the timer expires, the cursor moves. </entry> </row> <row> - <entry><emphasis>XkbSA_MoveAbsoluteX</emphasis></entry> + <entry><symbol>XkbSA_MoveAbsoluteX</symbol></entry> <entry>If set, the X portion of the structure specifies the new pointer X coordinate. Otherwise, the X portion is added to the current pointer X coordinate to determine the new pointer X coordinate. </entry> </row> <row> - <entry><emphasis>XkbSA_MoveAbsoluteY</emphasis></entry> + <entry><symbol>XkbSA_MoveAbsoluteY</symbol></entry> <entry> If set, the Y portion of the structure specifies the new pointer Y coordinate. Otherwise, the Y portion is added @@ -1397,231 +1418,231 @@ to the current pointer Y coordinate to determine the new pointer Y coordinate. </table> <para> -Each of the X and Y coordinantes of the <emphasis> -XkbPtrAction</emphasis> - structure is composed of two signed 16-bit values, that is, the X coordinate -is composed of <emphasis> -high_XXX</emphasis> - and <emphasis> -low_XXX</emphasis> -, and similarly for the Y coordinate. Xkb provides the following macros, to -convert between a signed integer and two signed 16-bit values in <emphasis> -XkbPtrAction</emphasis> - structures: -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -int <emphasis> -XkbPtrActionX</emphasis> -(<emphasis> -act</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbPtrAction <emphasis> -act</emphasis> -; /* action from which to extract X */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbPtrActionX</emphasis> - returns the <emphasis> -high_XXX</emphasis> - and <emphasis> -low_XXX</emphasis> - fields of <emphasis> -act</emphasis> - converted to a signed int. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -int <emphasis> -XkbPtrActionY</emphasis> -(<emphasis> -act</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbPtrAction <emphasis> -act</emphasis> -; /* action from which to extract Y */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbPtrActionY</emphasis> - returns the <emphasis> -high_YYY</emphasis> - and <emphasis> -low_YYY</emphasis> - fields of <emphasis> -act</emphasis> - converted to a signed int. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbSetPtrActionX</emphasis> -(<emphasis> -act</emphasis> -, <emphasis> -x</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbPtrAction <emphasis> -act</emphasis> -; /* action in which to set X */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -x; </emphasis> - /* new value to set */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetPtrActionX</emphasis> - sets the <emphasis> -high_XXX</emphasis> - and <emphasis> -low_XXX</emphasis> - fields of <emphasis> -act</emphasis> - from the signed integer value <emphasis> -x</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbSetPtrActionY</emphasis> -(<emphasis> -act, y</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbPtrAction <emphasis> -act</emphasis> -; /* action in which to set Y */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -y</emphasis> -; /* new value to set */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +Each of the X and Y coordinates of the +<structname>XkbPtrAction</structname> +structure is composed of two signed 16-bit values, that is, the X coordinate +is composed of +<structfield>high_XXX</structfield> +and +<structfield>low_XXX</structfield>, +and similarly for the Y coordinate. Xkb provides the following macros, to +convert between a signed integer and two signed 16-bit values in +<structname>XkbPtrAction</structname> +structures: +</para> + +<indexterm significance="preferred" zone="XkbPtrActionX"><primary><function>XkbPtrActionX</function></primary></indexterm> +<funcsynopsis id="XkbPtrActionX"> + <funcprototype> + <funcdef>int <function>XkbPtrActionX</function></funcdef> +<!-- ( +<parameter>act</parameter> +) /* macro */ --> + + <paramdef>XkbPtrAction <parameter>act</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to extract X + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbPtrActionX</function> +returns the +<structfield>high_XXX</structfield> +and +<structfield>low_XXX</structfield> +fields of +<parameter>act</parameter> +converted to a signed int. +</para> + + +<indexterm significance="preferred" zone="XkbPtrActionY"><primary><function>XkbPtrActionY</function></primary></indexterm> +<funcsynopsis id="XkbPtrActionY"> + <funcprototype> + <funcdef>int <function>XkbPtrActionY</function></funcdef> +<!-- ( +<parameter>act</parameter> +) /* macro */ --> + + <paramdef>XkbPtrAction <parameter>act</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to extract Y + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbPtrActionY</function> +returns the +<structfield>high_YYY</structfield> +and +<structfield>low_YYY</structfield> +fields of +<parameter>act</parameter> +converted to a signed int. +</para> + + +<indexterm significance="preferred" zone="XkbSetPtrActionX"><primary><function>XkbSetPtrActionX</function></primary></indexterm> +<funcsynopsis id="XkbSetPtrActionX"> + <funcprototype> + <funcdef>void <function>XkbSetPtrActionX</function></funcdef> +<!-- ( +<parameter>act</parameter>, +<parameter>x</parameter> +) /* macro */ --> + + <paramdef>XkbPtrAction <parameter>act</parameter></paramdef> + <paramdef>int <parameter>x</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action in which to set X + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>x</parameter> + </term> + <listitem> + <para> + new value to set + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetPtrActionX</function> +sets the +<structfield>high_XXX</structfield> +and +<structfield>low_XXX</structfield> +fields of +<parameter>act</parameter> +from the signed integer value +<parameter>x</parameter>. +</para> + + +<indexterm significance="preferred" zone="XkbSetPtrActionY"><primary><function>XkbSetPtrActionY</function></primary></indexterm> +<funcsynopsis id="XkbSetPtrActionY"> + <funcprototype> + <funcdef>void <function>XkbSetPtrActionY</function></funcdef> +<!-- ( +<parameter>act, y</parameter> +) /* macro */ --> + + <paramdef>XkbPtrAction <parameter>act</parameter></paramdef> + <paramdef>int <parameter>y</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action in which to set Y + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>y</parameter> + </term> + <listitem> + <para> + new value to set + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbSetPtrActionX</emphasis> - sets the <emphasis> -high_YYY</emphasis> - and <emphasis> -low_YYY</emphasis> - fields of <emphasis> -act</emphasis> - from the signed integer value <emphasis> -y</emphasis> -. +<function>XkbSetPtrActionX</function> +sets the +<structfield>high_YYY</structfield> +and +<structfield>low_YYY</structfield> +fields of +<parameter>act</parameter> +from the signed integer value +<parameter>y</parameter>. </para> </sect2> <sect2 id='Actions_for_Simulating_Pointer_Button_Press_and_Release'> <title>Actions for Simulating Pointer Button Press and Release</title> +<indexterm significance="preferred" zone="Actions_for_Simulating_Pointer_Button_Press_and_Release"> +<primary><structname>XkbPtrBtnAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbPtrBtnAction</emphasis> - structure simulate the press and release of pointer buttons when keys are +Actions associated with the +<structname>XkbPtrBtnAction</structname> +structure simulate the press and release of pointer buttons when keys are pressed and released: -</para> -<para><programlisting> +<programlisting> typedef struct _XkbPtrBtnAction { - unsigned char type; /*<emphasis> XkbSA_PtrBtn, XkbSA_LockPtrBtn</emphasis> */ - unsigned char flags; /* with <emphasis> type</emphasis> , controls the effect on pointer buttons*/ - unsigned char count; /* controls number of ButtonPress and ButtonRelease events */ - unsigned char button; /* pointer button to simulate */ -} <emphasis>XkbPtrBtnAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_PtrBtn</symbol>, <symbol>XkbSA_LockPtrBtn</symbol> */ + unsigned char flags; /* with <structfield>type</structfield>, controls the effect + on pointer buttons */ + unsigned char count; /* controls number of ButtonPress and + ButtonRelease events */ + unsigned char button; /* pointer button to simulate */ +} <structname>XkbPtrBtnAction</structname>; </programlisting></para> <para> -If the <emphasis> -MouseKeys</emphasis> - (see section 10.5.1) control is not enabled, <emphasis> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events are treated as though the action is <emphasis> -XkbSA_NoAction</emphasis> -. +If the +<emphasis>MouseKeys</emphasis> +(see <link linkend="The_MouseKeys_Control">section 10.5.1</link>) control is not enabled, +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events are treated as though the action is +<symbol>XkbSA_NoAction</symbol>. </para> <para> -The <emphasis> -type</emphasis> - field can have any one of the values shown in Table 16.7. +The +<structfield>type</structfield> +field can have any one of the values shown in +<link linkend="table16.7">Table 16.7</link>. </para> -<table frame='topbot'> +<table id='table16.7' frame='topbot'> <title>Pointer Button Action Types</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1635,24 +1656,23 @@ type</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_PtrBtn</emphasis></entry> + <entry><symbol>XkbSA_PtrBtn</symbol></entry> <entry> <itemizedlist> <listitem> <para> -If<emphasis> - XkbSA_UseDfltButton</emphasis> - is set in the <emphasis> -flags</emphasis> - field, the event is generated for the pointer button specified by the -<emphasis> -mk_dflt_btn</emphasis> - attribute of the <emphasis> -MouseKeys</emphasis> - control (see section 10.5.1). Otherwise, the event is generated for the button -specified by the <emphasis> -button</emphasis> - field. +If +<symbol>XkbSA_UseDfltButton</symbol> +is set in the +<structfield>flags</structfield> +field, the event is generated for the pointer button specified by the +<structfield>mk_dflt_btn</structfield> +attribute of the +<emphasis>MouseKeys</emphasis> +control (see <link linkend="The_MouseKeys_Control">section 10.5.1</link>). Otherwise, the event is generated for the button +specified by the +<structfield>button</structfield> +field. </para> </listitem> <listitem> @@ -1660,83 +1680,81 @@ button</emphasis> If the mouse button specified for this action is logically down, the key press and corresponding key release are ignored and have no effect. Otherwise, a key press causes one or more core pointer button events instead of the usual -<emphasis> -KeyPress</emphasis> - event. If <emphasis> -count</emphasis> - is <emphasis> -zero</emphasis> -, a key press generates a single <emphasis> -ButtonPress</emphasis> - event; if <emphasis> -count</emphasis> - is greater than <emphasis> -zero</emphasis> -, a key press generates <emphasis> -count</emphasis> - pairs of <emphasis> -ButtonPress</emphasis> - and <emphasis> -ButtonRelease</emphasis> - events. +<symbol>KeyPress</symbol> +event. If +<structfield>count</structfield> +is +<emphasis>zero</emphasis>, +a key press generates a single +<symbol>ButtonPress</symbol> +event; if +<structfield>count</structfield> +is greater than +<emphasis>zero</emphasis>, +a key press generates +<structfield>count</structfield> +pairs of +<symbol>ButtonPress</symbol> +and +<symbol>ButtonRelease</symbol> +events. </para> </listitem> <listitem> <para> -If <emphasis> -count</emphasis> - is <emphasis> -zero</emphasis> -, a key release generates a core pointer <emphasis> -ButtonRelease</emphasis> - that matches the event generated by the corresponding <emphasis> -KeyPress</emphasis> -; if <emphasis> -count</emphasis> - is nonzero, a key release does not cause a <emphasis> -ButtonRelease</emphasis> - event. A key release never generates a key <emphasis> -KeyRelease</emphasis> - event. +If +<structfield>count</structfield> +is +<emphasis>zero</emphasis>, +a key release generates a core pointer +<symbol>ButtonRelease</symbol> +that matches the event generated by the corresponding +<symbol>KeyPress</symbol>; +if +<structfield>count</structfield> +is nonzero, a key release does not cause a +<symbol>ButtonRelease</symbol> +event. A key release never generates a key +<symbol>KeyRelease</symbol> +event. </para> </listitem> </itemizedlist> </entry> </row> <row> - <entry><emphasis>XkbSA_LockPtrBtn</emphasis></entry> + <entry><symbol>XkbSA_LockPtrBtn</symbol></entry> <entry> <itemizedlist> <listitem> <para> -If the button specified by the <emphasis> -MouseKeys</emphasis> - default button<emphasis> - </emphasis> -or <emphasis> -button</emphasis> - is not locked, a key press causes a <emphasis> -ButtonPress</emphasis> - event instead of a <emphasis> -KeyPress</emphasis> - event and locks the button. If the button is already locked or if <emphasis> -XkbSA_LockNoUnlock</emphasis> - is set in the <emphasis> -flags</emphasis> - field, a key press is ignored and has no effect. +If the button specified by the +<emphasis>MouseKeys</emphasis> +default button +or +<structfield>button</structfield> +is not locked, a key press causes a +<symbol>ButtonPress</symbol> +event instead of a +<symbol>KeyPress</symbol> +event and locks the button. If the button is already locked or if +<symbol>XkbSA_LockNoUnlock</symbol> +is set in the +<structfield>flags</structfield> +field, a key press is ignored and has no effect. </para> </listitem> <listitem> <para> -If the corresponding key press was ignored, and if <emphasis> -XkbSA_LockNoLock</emphasis> - is not set in the <emphasis> -flags</emphasis> - field, a key release generates a <emphasis> -ButtonRelease</emphasis> - event instead of a <emphasis> -KeyRelease</emphasis> - event and unlocks the specified button. If the corresponding key press locked +If the corresponding key press was ignored, and if +<symbol>XkbSA_LockNoLock</symbol> +is not set in the +<structfield>flags</structfield> +field, a key release generates a +<symbol>ButtonRelease</symbol> +event instead of a +<symbol>KeyRelease</symbol> +event and unlocks the specified button. If the corresponding key press locked a button, the key release is ignored and has no effect. </para> </listitem> @@ -1748,16 +1766,16 @@ a button, the key release is ignored and has no effect. </table> <para> -The <emphasis> -flags</emphasis> - field is composed of the bitwise inclusive OR of the masks shown in Table -16.8. A general meaning is given in the table, but the exact meaning depends on -the action <emphasis> -type.</emphasis> -: +The +<structfield>flags</structfield> +field is composed of the bitwise inclusive OR of the masks shown in +<link linkend="table16.8">Table 16.8</link>. +A general meaning is given in the table, but the exact meaning depends on +the action +<structfield>type</structfield>: </para> -<table frame='topbot'> +<table id='table16.8' frame='topbot'> <title>Pointer Button Action Flags</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1771,32 +1789,32 @@ type.</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_UseDfltButton</emphasis></entry> + <entry><symbol>XkbSA_UseDfltButton</symbol></entry> <entry> -If set, the action uses the pointer button specified by the <emphasis> -mk_dflt_btn</emphasis> - attribute of the <emphasis> -MouseKeys</emphasis> - control (see section 10.5.1). Otherwise, the action uses the pointer button -specified by the<emphasis> - button </emphasis> +If set, the action uses the pointer button specified by the +<structfield>mk_dflt_btn</structfield> +attribute of the +<emphasis>MouseKeys</emphasis> +control (see <link linkend="The_MouseKeys_Control">section 10.5.1</link>). Otherwise, the action uses the pointer button +specified by the +<structfield>button</structfield> field. </entry> </row> <row> - <entry><emphasis>XkbSA_LockNoLock</emphasis></entry> + <entry><symbol>XkbSA_LockNoLock</symbol></entry> <entry> -If set, and the action type is <emphasis> -XkbSA_LockPtrBtn</emphasis> -, the server only unlocks the pointer button. +If set, and the action type is +<symbol>XkbSA_LockPtrBtn</symbol>, +the server only unlocks the pointer button. </entry> </row> <row> - <entry><emphasis>XkbSA_LockNoUnlock</emphasis></entry> + <entry><symbol>XkbSA_LockNoUnlock</symbol></entry> <entry> -If set, and the action type is <emphasis> -XkbSA_LockPtrBtn</emphasis> -, the server only locks the pointer button. +If set, and the action type is +<symbol>XkbSA_LockPtrBtn</symbol>, +the server only locks the pointer button. </entry> </row> </tbody> @@ -1806,62 +1824,63 @@ XkbSA_LockPtrBtn</emphasis> </sect2> <sect2 id='Actions_for_Changing_the_Pointer_Button_Simulated'> <title>Actions for Changing the Pointer Button Simulated</title> +<indexterm significance="preferred" zone="Actions_for_Changing_the_Pointer_Button_Simulated"> +<primary><structname>XkbPtrDfltAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbPtrDfltAction</emphasis> - structure change the <emphasis> -mk_dflt_btn</emphasis> - attribute of the <emphasis> -MouseKeys</emphasis> - control (see section 10.5.1): -</para> +Actions associated with the +<structname>XkbPtrDfltAction</structname> +structure change the +<structfield>mk_dflt_btn</structfield> +attribute of the +<emphasis>MouseKeys</emphasis> +control (see <link linkend="The_MouseKeys_Control">section 10.5.1</link>): -<para><programlisting> +<programlisting> typedef struct _XkbPtrDfltAction { - unsigned char type; /* <emphasis> XkbSA_SetPtrDflt</emphasis> */ - unsigned char flags; /* controls the pointer button number */ - unsigned char affect; /* <emphasis> XkbSA_AffectDfltBtn</emphasis> */ - char valueXXX; /* new default button member */ -} <emphasis>XkbPtrDfltAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_SetPtrDflt</symbol> */ + unsigned char flags; /* controls the pointer button number */ + unsigned char affect; /* <symbol>XkbSA_AffectDfltBtn</symbol> */ + char valueXXX; /* new default button member */ +} <structname>XkbPtrDfltAction</structname>; </programlisting></para> <para> -If the <emphasis> -MouseKeys</emphasis> - control is not enabled, <emphasis> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events are treated as though the action is <emphasis> -XkbSA_NoAction</emphasis> -. Otherwise, this action changes the <emphasis> -mk_dflt_btn</emphasis> - attribute of the <emphasis> -MouseKeys</emphasis> - control. +If the +<emphasis>MouseKeys</emphasis> +control is not enabled, +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events are treated as though the action is +<symbol>XkbSA_NoAction</symbol>. +Otherwise, this action changes the +<structfield>mk_dflt_btn</structfield> +attribute of the +<emphasis>MouseKeys</emphasis> +control. </para> <para> -The <emphasis> -type</emphasis> - field of the <emphasis> -XkbPtrDfltAction</emphasis> - structure should always be <emphasis> -XkbSA_SetPtrDflt</emphasis> -. +The +<structfield>type</structfield> +field of the +<structname>XkbPtrDfltAction</structname> +structure should always be +<symbol>XkbSA_SetPtrDflt</symbol>. </para> <para> -The <emphasis> -flags</emphasis> - field is composed of the bitwise inclusive OR of the values shown in Table -16.9 (currently there is only one value defined). +The +<structfield>flags</structfield> +field is composed of the bitwise inclusive OR of the values shown in +<link linkend="table16.9">Table 16.9</link> +(currently there is only one value defined). </para> -<table frame='topbot'> +<table id='table16.9' frame='topbot'> <title>Pointer Default Flags</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1875,13 +1894,13 @@ flags</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_DfltBtnAbsolute</emphasis></entry> + <entry><symbol>XkbSA_DfltBtnAbsolute</symbol></entry> <entry> -If set, the <emphasis> -value</emphasis> - field represents an absolute pointer button. Otherwise, the <emphasis> -value</emphasis> - field represents the amount to be added to the current default button. +If set, the +<structfield>value</structfield> +field represents an absolute pointer button. Otherwise, the +<structfield>value</structfield> +field represents the amount to be added to the current default button. </entry> </row> </tbody> @@ -1889,219 +1908,219 @@ value</emphasis> </table> <para> -The <emphasis> -affect</emphasis> - field specifies what changes as a result of this action. The only valid value -for the <emphasis> -affect</emphasis> - field is <emphasis>XkbSA_AffectDfltBtn</emphasis>. -</para> - -<para> -The <emphasis> -valueXXX</emphasis> - field is a signed character that represents the new button value for the -<emphasis> -mk_dflt_btn</emphasis> - attribute of the <emphasis> -MouseKeys</emphasis> - control (see section 10.5.1). If <emphasis> -XkbSA_DfltBtnAbsolute</emphasis> - is set in <emphasis> -flags</emphasis> -, <emphasis> -valueXXX</emphasis> - specifies the button to be used; otherwise, <emphasis> -valueXXX</emphasis> - specifies the amount to be added to the current default button. In either +The +<structfield>affect</structfield> +field specifies what changes as a result of this action. The only valid value +for the +<structfield>affect</structfield> +field is <symbol>XkbSA_AffectDfltBtn</symbol>. +</para> + +<para> +The +<structfield>valueXXX</structfield> +field is a signed character that represents the new button value for the +<structfield>mk_dflt_btn</structfield> +attribute of the +<emphasis>MouseKeys</emphasis> +control (see <link linkend="The_MouseKeys_Control">section 10.5.1</link>). If +<symbol>XkbSA_DfltBtnAbsolute</symbol> +is set in +<structfield>flags</structfield>, +<structfield>valueXXX</structfield> +specifies the button to be used; otherwise, +<structfield>valueXXX</structfield> +specifies the amount to be added to the current default button. In either case, illegal button choices are wrapped back around into range. Xkb provides the following macros, to convert between the integer and signed character -values in <emphasis> -XkbPtrDfltAction</emphasis> - structures: -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -int <emphasis> -XkbSAPtrDfltValue</emphasis> -(<emphasis> -act</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbAction <emphasis> -act</emphasis> -; /* action from which to extract group */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSAPtrDfltValue</emphasis> - returns the <emphasis> -valueXXX</emphasis> - field of <emphasis> -act</emphasis> - converted to a signed int. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbSASetPtrDfltValue</emphasis> -(<emphasis> -act, val</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbPtrDfltAction <emphasis> -act</emphasis> -; /* action in which to set <emphasis> -valueXXX</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -val</emphasis> -; /* value to set in <emphasis> -valueXXX</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +values in +<structname>XkbPtrDfltAction</structname> +structures: +</para> + +<indexterm significance="preferred" zone="XkbSAPtrDfltValue"><primary><function>XkbSAPtrDfltValue</function></primary></indexterm> +<funcsynopsis id="XkbSAPtrDfltValue"> + <funcprototype> + <funcdef>int <function>XkbSAPtrDfltValue</function></funcdef> +<!-- ( +<parameter>act</parameter> +) /* macro */ --> + + <paramdef>XkbAction <parameter>act</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to extract group + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSAPtrDfltValue</function> +returns the +<structfield>valueXXX</structfield> +field of +<parameter>act</parameter> +converted to a signed int. +</para> + + +<indexterm significance="preferred" zone="XkbSASetPtrDfltValue"><primary><function>XkbSASetPtrDfltValue</function></primary></indexterm> +<funcsynopsis id="XkbSASetPtrDfltValue"> + <funcprototype> + <funcdef>void <function>XkbSASetPtrDfltValue</function></funcdef> +<!-- ( +<parameter>act, val</parameter> +) /* macro */ --> + + <paramdef>XkbPtrDfltAction <parameter>act</parameter></paramdef> + <paramdef>int <parameter>val</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action in which to set <structfield>valueXXX</structfield> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>val</parameter> + </term> + <listitem> + <para> + value to set in <structfield>valueXXX</structfield> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbSASetPtrDfltValue</emphasis> - sets the <emphasis> -valueXXX</emphasis> - field of <emphasis> -act</emphasis> - from <emphasis> -val</emphasis> -. +<function>XkbSASetPtrDfltValue</function> +sets the +<structfield>valueXXX</structfield> +field of +<parameter>act</parameter> +from +<parameter>val</parameter>. </para> </sect2> <sect2 id='Actions_for_Locking_Modifiers_and_Group'> <title>Actions for Locking Modifiers and Group</title> +<indexterm significance="preferred" zone="Actions_for_Locking_Modifiers_and_Group"> +<primary><structname>XkbISOAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbISOAction</emphasis> - structure lock modifiers and the group according to the ISO9995 specification. +Actions associated with the +<structname>XkbISOAction</structname> +structure lock modifiers and the group according to the ISO9995 specification. </para> <para> -Operated by itself, the <emphasis> -XkbISOAction</emphasis> - is just a caps lock. Operated simultaneously with another modifier key, it -transforms the other key into a locking key. For example, press <emphasis> -ISO_Lock</emphasis> -, press and release <emphasis> -Control_L</emphasis> -, release <emphasis> -ISO_Lock</emphasis> - ends up locking the <emphasis> -Control</emphasis> - modifier. +Operated by itself, the +<structname>XkbISOAction</structname> +is just a caps lock. Operated simultaneously with another modifier key, it +transforms the other key into a locking key. For example, press +<keysym>ISO_Lock</keysym>, +press and release +<keysym>Control_L</keysym>, +release +<keysym>ISO_Lock</keysym> +ends up locking the +<symbol>Control</symbol> +modifier. </para> <para> The default behavior is to convert: -</para> -<literallayout> - {Set,Latch}Mods to: LockMods - {Set,Latch}Group to: LockGroup - SetPtrBtn to: LockPtrBtn - SetControls to: LockControls -</literallayout> +<simplelist type='vert' columns='1'> + <member>{Set,Latch}Mods to: LockMods</member> + <member>{Set,Latch}Group to: LockGroup</member> + <member>SetPtrBtn to: LockPtrBtn</member> + <member>SetControls to: LockControls</member> +</simplelist> +</para> <para> -The <emphasis> -affects</emphasis> - field allows you to turn those effects on or off individually. Set <emphasis> -XkbSA_ISONoAffectMods</emphasis> - to disable the first, <emphasis> -XkbSA_ISONoAffectGroup</emphasis> - to disable the second, and so forth. +The +<emphasis>affects</emphasis> +field allows you to turn those effects on or off individually. Set +<symbol>XkbSA_ISONoAffectMods</symbol> +to disable the first, +<symbol>XkbSA_ISONoAffectGroup</symbol> +to disable the second, and so forth. </para> <para><programlisting> typedef struct _XkbISOAction { - unsigned char type; /* <emphasis>XkbSA_ISOLock</emphasis> */ - unsigned char flags; /* controls changes to group or modifier state */ - unsigned char mask; /* same as <emphasis>mask</emphasis> field of a modifier description */ - unsigned char real_mods; /* same as <emphasis>real_mods</emphasis> field of a modifier description */ - char group_XXX; /* group index or delta group */ - unsigned char affect; /* specifies whether to affect mods, group, ptrbtn, or controls*/ - unsigned char vmods1; /* derived from <emphasis>vmods</emphasis> field of a modifier description */ - unsigned char vmods2; /* derived from <emphasis>vmods</emphasis> field of a modifier description */ -} <emphasis>XkbISOAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_ISOLock</symbol> */ + unsigned char flags; /* controls changes to group or + modifier state */ + unsigned char mask; /* same as <structfield>mask</structfield> field of + a modifier description */ + unsigned char real_mods; /* same as <structfield>real_mods</structfield> field of + a modifier description */ + char group_XXX; /* group index or delta group */ + unsigned char affect; /* specifies whether to affect + mods, group, ptrbtn, or controls */ + unsigned char vmods1; /* derived from <structfield>vmods</structfield> field of + a modifier description */ + unsigned char vmods2; /* derived from <structfield>vmods</structfield> field of + a modifier description */ +} <structname>XkbISOAction</structname>; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field of the <emphasis> -XkbISOAction</emphasis> - structure should always be <emphasis> -XkbSA_ISOLock</emphasis> -. +The +<structfield>type</structfield> +field of the +<structname>XkbISOAction</structname> +structure should always be +<symbol>XkbSA_ISOLock</symbol>. </para> <para> -The interpretation of the <emphasis> -flags</emphasis> - field depends on whether the <emphasis> -XkbSA_ISODfltIsGroup</emphasis> - is set in the <emphasis> -flags</emphasis> - field or not. +The interpretation of the +<structfield>flags</structfield> +field depends on whether the +<symbol>XkbSA_ISODfltIsGroup</symbol> +is set in the +<structfield>flags</structfield> +field or not. </para> <para> -If the <emphasis> -XkbSA_ISODfltIsGroup</emphasis> - is set in the <emphasis> -flags</emphasis> - field, the action is used to change the group state. The remaining valid bits -of the <emphasis> -flags</emphasis> - field are composed of a bitwise inclusive OR using the masks shown in Table -16.10. +If the +<symbol>XkbSA_ISODfltIsGroup</symbol> +is set in the +<structfield>flags</structfield> +field, the action is used to change the group state. The remaining valid bits +of the +<structfield>flags</structfield> +field are composed of a bitwise inclusive OR using the masks shown in +<link linkend="table16.10">Table 16.10</link>. </para> -<table frame='topbot'> +<table id='table16.10' frame='topbot'> <title>ISO Action Flags when XkbSA_ISODfltIsGroup is Set</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -2115,85 +2134,85 @@ flags</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_ISODfltIsGroup</emphasis></entry> + <entry><symbol>XkbSA_ISODfltIsGroup</symbol></entry> <entry> <para> If set, the action is used to change the base group state. Must be set for the remaining bits in this table to carry their interpretations. </para> <para> -A key press sets the base group as specified by the <emphasis> -group_XXX</emphasis> - field and the <emphasis> -XkbSA_GroupAbsolute</emphasis> - bit of the <emphasis> -flags</emphasis> - field (see section Note). If no other actions are transformed by the <emphasis> -XkbISO_Lock</emphasis> - action, a key release locks the group. Otherwise, a key release clears group +A key press sets the base group as specified by the +<structfield>group_XXX</structfield> +field and the +<symbol>XkbSA_GroupAbsolute</symbol> +bit of the +<structfield>flags</structfield> +field (see section Note). If no other actions are transformed by the +<symbol>XkbSA_ISOLock</symbol> +action, a key release locks the group. Otherwise, a key release clears group set by the key press. </para> </entry> </row> <row> - <entry><emphasis>XkbSA_GroupAbsolute</emphasis></entry> + <entry><symbol>XkbSA_GroupAbsolute</symbol></entry> <entry> -If set, the <emphasis> -group_XXX</emphasis> - field represents an absolute group number. Otherwise, it represents a group +If set, the +<structfield>group_XXX</structfield> +field represents an absolute group number. Otherwise, it represents a group delta to be added to the current group to determine the new group number. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectMods</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectMods</symbol></entry> <entry> -If not set, any <emphasis> -XkbSA_SetMods</emphasis> - or <emphasis> -XkbSA_LatchMods</emphasis> - actions that occur simultaneously with the <emphasis> -XkbSA_ISOLock</emphasis> - action are treated as <emphasis> -XkbSA_LockMod</emphasis> - actions instead. +If not set, any +<symbol>XkbSA_SetMods</symbol> +or +<symbol>XkbSA_LatchMods</symbol> +actions that occur simultaneously with the +<symbol>XkbSA_ISOLock</symbol> +action are treated as +<symbol>XkbSA_LockMods</symbol> +actions instead. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectGroup</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectGroup</symbol></entry> <entry> -If not set, any <emphasis> -XkbSA_SetGroup</emphasis> - or <emphasis> -XkbSA_LatchGroup</emphasis> - actions that occur simultaneously with the <emphasis> -XkbSA_ISOLock</emphasis> - action are treated as <emphasis> -XkbSA_LockGroup</emphasis> - actions instead. +If not set, any +<symbol>XkbSA_SetGroup</symbol> +or +<symbol>XkbSA_LatchGroup</symbol> +actions that occur simultaneously with the +<symbol>XkbSA_ISOLock</symbol> +action are treated as +<symbol>XkbSA_LockGroup</symbol> +actions instead. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectPtr</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectPtr</symbol></entry> <entry> -If not set, any <emphasis> -XkbSA_PtrBtn</emphasis> - actions that occur simultaneously with the <emphasis> -XkbSA_ISOLock</emphasis> - action are treated as <emphasis> -XkbSA_LockPtrBtn</emphasis> - actions instead. +If not set, any +<symbol>XkbSA_PtrBtn</symbol> +actions that occur simultaneously with the +<symbol>XkbSA_ISOLock</symbol> +action are treated as +<symbol>XkbSA_LockPtrBtn</symbol> +actions instead. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectCtrls</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectCtrls</symbol></entry> <entry> -If not set, any <emphasis> -XkbSA_SetControls</emphasis> - actions that occur simultaneously with the <emphasis> -XkbSA_ISOLock</emphasis> - action are treated as <emphasis> -XkbSA_LockControls</emphasis> - actions instead. +If not set, any +<symbol>XkbSA_SetControls</symbol> +actions that occur simultaneously with the +<symbol>XkbSA_ISOLock</symbol> +action are treated as +<symbol>XkbSA_LockControls</symbol> +actions instead. </entry> </row> </tbody> @@ -2201,18 +2220,18 @@ XkbSA_LockControls</emphasis> </table> <para> -If the <emphasis> -XkbSA_ISODfltIsGroup</emphasis> - is not set in the <emphasis> -flags</emphasis> - field, the action is used to change the modifier state and the remaining valid -bits of the <emphasis> -flags</emphasis> - field are composed of a bitwise inclusive OR using the masks shown in Table -16.11. +If the +<symbol>XkbSA_ISODfltIsGroup</symbol> +is not set in the +<structfield>flags</structfield> +field, the action is used to change the modifier state and the remaining valid +bits of the +<structfield>flags</structfield> +field are composed of a bitwise inclusive OR using the masks shown in +<link linkend="table16.11">Table 16.11</link>. </para> -<table frame='topbot'> +<table id='table16.11' frame='topbot'> <title>ISO Action Flags when XkbSA_ISODfltIsGroup is Not Set</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -2226,7 +2245,7 @@ flags</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_ISODfltIsGroup</emphasis> </entry> + <entry><symbol>XkbSA_ISODfltIsGroup</symbol> </entry> <entry> <para> If not set, action is used to change the base modifier state. Must not be set @@ -2234,96 +2253,91 @@ for the remaining bits in this table to carry their interpretations. </para> <para> A key press sets the action modifiers in the keyboard’s base modifiers using -the <emphasis> -mask</emphasis> -, <emphasis> -real_mods</emphasis> -, <emphasis> -vmods1</emphasis> -, and <emphasis> -vmods2 </emphasis> -fields (see section 16.1.3). If no other actions are transformed by the -<emphasis> -XkbISO_Lock</emphasis> - action, a key release locks the action modifiers. Otherwise, a key release +the +<structfield>mask</structfield>, +<structfield>real_mods</structfield>, +<structfield>vmods1</structfield>, +and +<structfield>vmods2</structfield> +fields (see <link linkend="Actions_for_Changing_Modifiers_State">section 16.1.3</link>). If no other actions are transformed by the +<symbol>XkbSA_ISOLock</symbol> +action, a key release locks the action modifiers. Otherwise, a key release clears the base modifiers set by the key press. </para> </entry> </row> <row> - <entry><emphasis>XkbSA_UseModMapMods</emphasis></entry> + <entry><symbol>XkbSA_UseModMapMods</symbol></entry> <entry> If set, the action modifiers are determined by the modifiers bound by the modifier mapping of the key. Otherwise, the action modifiers are set to the -modifiers specified by the <emphasis> -mask</emphasis> -, <emphasis> -real_mods</emphasis> -, <emphasis> -vmod1</emphasis> -, and <emphasis> -vmod2</emphasis> - fields. +modifiers specified by the +<structfield>mask</structfield>, +<structfield>real_mods</structfield>, +<structfield>vmods1</structfield>, +and +<structfield>vmods2</structfield> +fields. </entry> </row> <row> - <entry><emphasis>XkbSA_LockNoLock</emphasis></entry> + <entry><symbol>XkbSA_LockNoLock</symbol></entry> <entry>If set, the server only unlocks the action modifiers.</entry> </row> <row> - <entry><emphasis>XkbSA_LockNoUnlock</emphasis></entry> + <entry><symbol>XkbSA_LockNoUnlock</symbol></entry> <entry>If set, the server only locks the action modifiers. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectMods</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectMods</symbol></entry> <entry> -If not set, any <emphasis> -XkbSA_SetMods</emphasis> - or <emphasis> -XkbSA_LatchMods</emphasis> - actions that occur simultaneously with the <emphasis> -XkbSA_ISOLock</emphasis> - action are treated as <emphasis> -XkbSA_LockMod</emphasis> - actions instead. +If not set, any +<symbol>XkbSA_SetMods</symbol> +or +<symbol>XkbSA_LatchMods</symbol> +actions that occur simultaneously with the +<symbol>XkbSA_ISOLock</symbol> +action are treated as +<symbol>XkbSA_LockMods</symbol> +actions instead. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectGroup</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectGroup</symbol></entry> <entry> -If not set, any <emphasis> -XkbSA_SetGroup</emphasis> - or <emphasis> -XkbSA_LatchGroup</emphasis> - actions that occur simultaneously with the <emphasis> -XkbSA_ISOLock</emphasis> - action are treated as <emphasis> -XkbSA_LockGroup</emphasis> - actions instead. +If not set, any +<symbol>XkbSA_SetGroup</symbol> +or +<symbol>XkbSA_LatchGroup</symbol> +actions that occur simultaneously with the +<symbol>XkbSA_ISOLock</symbol> +action are treated as +<symbol>XkbSA_LockGroup</symbol> +actions instead. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectPtr</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectPtr</symbol></entry> <entry> -If not set, any <emphasis> -XkbSA_PtrBtn</emphasis> - actions that occur simultaneously with the <emphasis> -XkbSA_ISOLock</emphasis> - action are treated as <emphasis> -XkbSA_LockPtrBtn</emphasis> - actions instead. +If not set, any +<symbol>XkbSA_PtrBtn</symbol> +actions that occur simultaneously with the +<symbol>XkbSA_ISOLock</symbol> +action are treated as +<symbol>XkbSA_LockPtrBtn</symbol> +actions instead. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectCtrls</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectCtrls</symbol></entry> <entry> -If not set, any <emphasis> -XkbSA_SetControls</emphasis> - actions that occur simultaneously with the <emphasis> -XkbSA_ISOLock</emphasis> - action are treated as <emphasis> -XkbSA_LockControls</emphasis> - actions instead. +If not set, any +<symbol>XkbSA_SetControls</symbol> +actions that occur simultaneously with the +<symbol>XkbSA_ISOLock</symbol> +action are treated as +<symbol>XkbSA_LockControls</symbol> +actions instead. </entry> </row> </tbody> @@ -2331,50 +2345,48 @@ XkbSA_LockControls</emphasis> </table> <para> -The <emphasis> -group_XXX</emphasis> - field represents a signed character. Xkb provides macros to convert between a +The +<structfield>group_XXX</structfield> +field represents a signed character. Xkb provides macros to convert between a signed integer value and a signed character as shown in section Note. </para> <para> -The <emphasis> -mask</emphasis> -, <emphasis> -real_mods</emphasis> -, <emphasis> -vmods1</emphasis> -, and <emphasis> -vmods2</emphasis> - fields represent the components of an Xkb modifier description (see section -7.2). While the <emphasis> -mask</emphasis> - and <emphasis> -real_mods</emphasis> - fields correspond directly to the <emphasis> -mask</emphasis> - and <emphasis> -real_mods</emphasis> - fields of an Xkb modifier description, the <emphasis> -vmods1</emphasis> - and <emphasis> -vmods2</emphasis> - fields are combined to correspond to the <emphasis> -vmods</emphasis> - field of an Xkb modifier description. Xkb provides macros to convert between -the two formats as shown in section 16.1.3. +The +<structfield>mask</structfield>, +<structfield>real_mods</structfield>, +<structfield>vmods1</structfield>, +and +<structfield>vmods2</structfield> +fields represent the components of an Xkb modifier description +(see <link linkend="Modifier_Definitions">section 7.2</link>). While the +<structfield>mask</structfield> +and +<structfield>real_mods</structfield> +fields correspond directly to the +<structfield>mask</structfield> +and +<structfield>real_mods</structfield> +fields of an Xkb modifier description, the +<structfield>vmods1</structfield> +and +<structfield>vmods2</structfield> +fields are combined to correspond to the +<structfield>vmods</structfield> +field of an Xkb modifier description. Xkb provides macros to convert between +the two formats as shown in <link linkend="Actions_for_Changing_Modifiers_State">section 16.1.3</link>. </para> <para> -The <emphasis> -affect</emphasis> - field is composed of a bitwise inclusive OR using the masks shown in Table -16.11. +The +<structfield>affect</structfield> +field is composed of a bitwise inclusive OR using the masks shown in +<link linkend="table16.11">Table 16.11</link>. </para> -<table frame='topbot'> +<table id='table16.12' frame='topbot'> <title>ISO Action Affect Field Values</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -2388,63 +2400,63 @@ affect</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_ISODNoAffectMods</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectMods</symbol></entry> <entry> -If <emphasis> -XkbSA_ISONoAffectMods</emphasis> - is not set, any <emphasis> -SA_SetMods</emphasis> - or <emphasis> -SA_LatchMods</emphasis> - actions occurring simultaneously with the <emphasis> -XkbISOAction</emphasis> - are treated as <emphasis> -SA_LockMods</emphasis> - instead. +If +<symbol>XkbSA_ISONoAffectMods</symbol> +is not set, any +<emphasis>SA_SetMods</emphasis> +or +<emphasis>SA_LatchMods</emphasis> +actions occurring simultaneously with the +<structname>XkbISOAction</structname> +are treated as +<emphasis>SA_LockMods</emphasis> +instead. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectGroup</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectGroup</symbol></entry> <entry> -If <emphasis> -XkbSA_ISONoAffectGroup</emphasis> - is not set, any <emphasis> -SA_SetGroup</emphasis> - or <emphasis> -SA_LatchGroup</emphasis> - actions occurring simultaneously with the <emphasis> -XkbISOAction</emphasis> - are treated as <emphasis> -SA_LockGroup</emphasis> - instead. +If +<symbol>XkbSA_ISONoAffectGroup</symbol> +is not set, any +<emphasis>SA_SetGroup</emphasis> +or +<emphasis>SA_LatchGroup</emphasis> +actions occurring simultaneously with the +<structname>XkbISOAction</structname> +are treated as +<emphasis>SA_LockGroup</emphasis> +instead. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectPtr</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectPtr</symbol></entry> <entry> -If <emphasis> -XkbSA_ISONoAffectPtr</emphasis> - is not set, any <emphasis> -SA_PtrBtn</emphasis> - actions occurring simultaneously with the <emphasis> -XkbISOAction</emphasis> - are treated as <emphasis> -SA_LockPtrBtn</emphasis> - instead. +If +<symbol>XkbSA_ISONoAffectPtr</symbol> +is not set, any +<emphasis>SA_PtrBtn</emphasis> +actions occurring simultaneously with the +<structname>XkbISOAction</structname> +are treated as +<emphasis>SA_LockPtrBtn</emphasis> +instead. </entry> </row> <row> - <entry><emphasis>XkbSA_ISONoAffectCtrls</emphasis></entry> + <entry><symbol>XkbSA_ISONoAffectCtrls</symbol></entry> <entry> -If <emphasis> -XkbSA_ISONoAffectCtrls</emphasis> - is not set, any <emphasis> -SA_SetControls</emphasis> - actions occurring simultaneously with the <emphasis> -XkbISOAction</emphasis> - are treated as <emphasis> -SA_LockControls</emphasis> - instead. +If +<symbol>XkbSA_ISONoAffectCtrls</symbol> +is not set, any +<emphasis>SA_SetControls</emphasis> +actions occurring simultaneously with the +<structname>XkbISOAction</structname> +are treated as +<emphasis>SA_LockControls</emphasis> +instead. </entry> </row> </tbody> @@ -2454,46 +2466,48 @@ SA_LockControls</emphasis> </sect2> <sect2 id='Actions_for_Changing_the_Active_Screen'> <title>Actions for Changing the Active Screen</title> +<indexterm significance="preferred" zone="Actions_for_Changing_the_Active_Screen"> +<primary><structname>XkbSwitchScreenAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbSwitchScreen</emphasis> - action structure change the active screen on a multiscreen display: +Actions associated with the +<structname>XkbSwitchScreenAction</structname> +action structure change the active screen on a multiscreen display: </para> <note><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> -XkbSA_NoAction</emphasis> -. Otherwise, key press and key release events do not generate an event. +is ignored, it behaves like +<symbol>XkbSA_NoAction</symbol>. +Otherwise, key press and key release events do not generate an event. </para></note> <para><programlisting> typedef struct _XkbSwitchScreenAction { - unsigned char type; /* <emphasis> XkbSA_SwitchScreen</emphasis> */ - unsigned char flags; /* controls screen switching */ - char screenXXX; /* screen number or delta */ -} <emphasis>XkbSwitchScreenAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_SwitchScreen</symbol> */ + unsigned char flags; /* controls screen switching */ + char screenXXX; /* screen number or delta */ +} <structname>XkbSwitchScreenAction</structname>; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field of the <emphasis> -XkbSwitchScreenAction</emphasis> - structure should always be <emphasis> -XkbSA_SwitchScreen</emphasis>. +The +<structfield>type</structfield> +field of the +<structname>XkbSwitchScreenAction</structname> +structure should always be +<symbol>XkbSA_SwitchScreen</symbol>. </para> <para> -The <emphasis> -flags</emphasis> - field is composed of the bitwise inclusive OR of the masks shown in Table -16.13. +The +<structfield>flags</structfield> +field is composed of the bitwise inclusive OR of the masks shown in +<link linkend="table16.13">Table 16.13</link>. </para> -<table frame='topbot'> +<table id='table16.13' frame='topbot'> <title>Switch Screen Action Flags</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -2507,16 +2521,16 @@ flags</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_SwitchAbsolute</emphasis></entry> + <entry><symbol>XkbSA_SwitchAbsolute</symbol></entry> <entry> -If set, the <emphasis> -screenXXX</emphasis> - field represents the index of the new screen. Otherwise, it represents an +If set, the +<structfield>screenXXX</structfield> +field represents the index of the new screen. Otherwise, it represents an offset from the current screen to the new screen. </entry> </row> <row> - <entry><emphasis>XkbSA_SwitchApplication</emphasis></entry> + <entry><symbol>XkbSA_SwitchApplication</symbol></entry> <entry> If not set, the action should switch to another screen on the same server. Otherwise, it should switch to another X server or application that @@ -2528,138 +2542,135 @@ shares the same physical display. </table> <para> -The <emphasis> -screenXXX</emphasis> - field is a signed character value that represents either the relative or -absolute screen index, depending on the state of the <emphasis> -XkbSA_SwitchAbsolute</emphasis> - bit in the <emphasis> -flags</emphasis> - field. Xkb provides the following macros to convert between the integer and -signed character value for screen numbers in <emphasis> -XkbSwitchScreenAction</emphasis> - structures: -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -int <emphasis> -XkbSAScreen</emphasis> -(<emphasis> -act</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbSwitchScreenAction <emphasis> -act</emphasis> -; /* action from which to extract screen */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSAScreen</emphasis> - returns the <emphasis> -screenXXX</emphasis> - field of <emphasis> -act</emphasis> - converted to a signed int. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbSASetScreen</emphasis> -(<emphasis> -act, s</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbSwitchScreenAction <emphasis> -act</emphasis> -; /* action in which to set <emphasis> -screenXXX</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -s</emphasis> -; /* value to set in <emphasis> -screenXXX</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +The +<structfield>screenXXX</structfield> +field is a signed character value that represents either the relative or +absolute screen index, depending on the state of the +<symbol>XkbSA_SwitchAbsolute</symbol> +bit in the +<structfield>flags</structfield> +field. Xkb provides the following macros to convert between the integer and +signed character value for screen numbers in +<structname>XkbSwitchScreenAction</structname> +structures: +</para> + +<indexterm significance="preferred" zone="XkbSAScreen"><primary><function>XkbSAScreen</function></primary></indexterm> +<funcsynopsis id="XkbSAScreen"> + <funcprototype> + <funcdef>int <function>XkbSAScreen</function></funcdef> +<!-- ( +<parameter>act</parameter> +) /* macro */ --> + + <paramdef>XkbSwitchScreenAction <parameter>act</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to extract screen + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSAScreen</function> +returns the +<structfield>screenXXX</structfield> +field of +<parameter>act</parameter> +converted to a signed int. +</para> + + +<indexterm significance="preferred" zone="XkbSASetScreen"><primary><function>XkbSASetScreen</function></primary></indexterm> +<funcsynopsis id="XkbSASetScreen"> + <funcprototype> + <funcdef>void <function>XkbSASetScreen</function></funcdef> +<!-- ( +<parameter>act, s</parameter> +) /* macro */ --> + + <paramdef>XkbSwitchScreenAction <parameter>act</parameter></paramdef> + <paramdef>int <parameter>s</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action in which to set <structfield>screenXXX</structfield> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>s</parameter> + </term> + <listitem> + <para> + value to set in <structfield>screenXXX</structfield> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbSASetScreen</emphasis> - sets the <emphasis> -screenXXX</emphasis> - field of <emphasis> -act</emphasis> - from <emphasis> -s</emphasis> -. +<function>XkbSASetScreen</function> +sets the +<structfield>screenXXX</structfield> +field of +<parameter>act</parameter> +from +<parameter>s</parameter>. </para> </sect2> <sect2 id='Actions_for_Changing_Boolean_Controls_State'> <title>Actions for Changing Boolean Controls State</title> +<indexterm significance="preferred" zone="Actions_for_Changing_Boolean_Controls_State"> +<primary><structname>XkbCtrlsAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbCtrlsAction</emphasis> - structure change the state of the boolean controls (see section 10.1): -</para> +Actions associated with the +<structname>XkbCtrlsAction</structname> +structure change the state of the boolean controls (see <link linkend="Controls_that_Enable_and_Disable_Other_Controls">section 10.1</link>): -<para><programlisting> +<programlisting> typedef struct _XkbCtrlsAction { - unsigned char type; /* <emphasis> XkbSA_SetControls, - XkbSA_LockControls</emphasis> */ - unsigned char flags; /* with <emphasis> type</emphasis>, - controls enabling and disabling of controls */ - unsigned char ctrls3; /* <emphasis>ctrls0</emphasis> through - <emphasis> ctrls3</emphasis> represent the boolean controls */ - unsigned char ctrls2; /* <emphasis>ctrls0</emphasis> through - <emphasis> ctrls3</emphasis> represent the boolean controls */ - unsigned char ctrls1; /* <emphasis>ctrls0</emphasis> through - <emphasis> ctrls3</emphasis> represent the boolean controls */ - unsigned char ctrls0; /* <emphasis>ctrls0</emphasis> through - <emphasis> ctrls3</emphasis> represent the boolean controls */ -} <emphasis>XkbCtrlsAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_SetControls</symbol>, + <symbol>XkbSA_LockControls</symbol> */ + unsigned char flags; /* with <structfield>type</structfield>, controls enabling + and disabling of controls */ + unsigned char ctrls3; /* <structfield>ctrls0</structfield> through <structfield>ctrls3</structfield> + represent the boolean controls */ + unsigned char ctrls2; /* <structfield>ctrls0</structfield> through <structfield>ctrls3</structfield> + represent the boolean controls */ + unsigned char ctrls1; /* <structfield>ctrls0</structfield> through <structfield>ctrls3</structfield> + represent the boolean controls */ + unsigned char ctrls0; /* <structfield>ctrls0</structfield> through <structfield>ctrls3</structfield> + represent the boolean controls */ +} <structname>XkbCtrlsAction</structname>; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field can have any one of the values shown in Table 16.14. +The +<structfield>type</structfield> +field can have any one of the values shown in +<link linkend="table16.14">Table 16.14</link>. </para> -<table frame='topbot'> +<table id='table16.14' frame='topbot'> <title>Controls Action Types</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -2673,14 +2684,14 @@ type</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_SetControls</emphasis></entry> + <entry><symbol>XkbSA_SetControls</symbol></entry> <entry> <itemizedlist> <listitem> <para> -A key press enables any boolean controls specified in the <emphasis> -ctrls</emphasis> - fields that were not already enabled at the time of the key press. +A key press enables any boolean controls specified in the +<structfield>ctrls</structfield> +fields that were not already enabled at the time of the key press. </para> </listitem> <listitem> @@ -2690,45 +2701,45 @@ A key release disables any controls enabled by the key press. </listitem> <listitem> <para> -This action can cause <emphasis> -XkbControlsNotify</emphasis> - events (see section 10.1). +This action can cause +<symbol>XkbControlsNotify</symbol> +events (see <link linkend="Controls_that_Enable_and_Disable_Other_Controls">section 10.1</link>). </para> </listitem> </itemizedlist> </entry> </row> <row> - <entry><emphasis>XkbSA_LockControls</emphasis></entry> + <entry><symbol>XkbSA_LockControls</symbol></entry> <entry> <itemizedlist> <listitem> <para> -If the <emphasis> -XkbSA_LockNoLock</emphasis> - bit is not set in the <emphasis> -flags</emphasis> - field, a key press enables any controls specified in the <emphasis> -ctrls</emphasis> - fields that were not already enabled at the time of the key press. +If the +<symbol>XkbSA_LockNoLock</symbol> +bit is not set in the +<structfield>flags</structfield> +field, a key press enables any controls specified in the +<structfield>ctrls</structfield> +fields that were not already enabled at the time of the key press. </para> </listitem> <listitem> <para> -If the <emphasis> -XkbSA_LockNoUnlock</emphasis> - bit is not set in the <emphasis> -flags</emphasis> - field, a key release disables any controls specified in the <emphasis> -ctrls</emphasis> - fields that were not already disabled at the time of the key press. +If the +<symbol>XkbSA_LockNoUnlock</symbol> +bit is not set in the +<structfield>flags</structfield> +field, a key release disables any controls specified in the +<structfield>ctrls</structfield> +fields that were not already disabled at the time of the key press. </para> </listitem> <listitem> <para> -This action can cause <emphasis> -XkbControlsNotify</emphasis> - events (see section 10.1). +This action can cause +<symbol>XkbControlsNotify</symbol> +events (see <link linkend="Controls_that_Enable_and_Disable_Other_Controls">section 10.1</link>). </para> </listitem> </itemizedlist> @@ -2739,13 +2750,13 @@ XkbControlsNotify</emphasis> </table> <para> -The <emphasis> -flags</emphasis> - field is composed of the bitwise inclusive OR of the masks shown in Table -16.15. +The +<structfield>flags</structfield> +field is composed of the bitwise inclusive OR of the masks shown in +<link linkend="table16.15">Table 16.15</link>. </para> -<table frame='topbot'> +<table id='table16.15' frame='topbot'> <title>Control Action Flags</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -2759,19 +2770,19 @@ flags</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_LockNoLock</emphasis></entry> + <entry><symbol>XkbSA_LockNoLock</symbol></entry> <entry> -If set, and the action type is <emphasis> -XkbSA_LockControls</emphasis> -, the server only disables controls. +If set, and the action type is +<symbol>XkbSA_LockControls</symbol>, +the server only disables controls. </entry> </row> <row> - <entry><emphasis>XkbSA_LockNoUnlock</emphasis></entry> + <entry><symbol>XkbSA_LockNoUnlock</symbol></entry> <entry> -If set, and the action type is <emphasis> -XkbSA_LockControls</emphasis> -, the server only enables controls. +If set, and the action type is +<symbol>XkbSA_LockControls</symbol>, +the server only enables controls. </entry> </row> </tbody> @@ -2779,161 +2790,158 @@ XkbSA_LockControls</emphasis> </table> <para> -The <emphasis> -XkbSA_SetControls</emphasis> - action implements a key that enables a boolean control when pressed and -disables it when released. The <emphasis> -XkbSA_LockControls</emphasis> - action is used to implement a key that toggles the state of a boolean control -each time it is pressed and released. The <emphasis> -XkbSA_LockNoLock</emphasis> - and <emphasis> -XkbSA_LockNoUnlock</emphasis> - flags allow modifying the toggling behavior to only unlock or only lock the +The +<symbol>XkbSA_SetControls</symbol> +action implements a key that enables a boolean control when pressed and +disables it when released. The +<symbol>XkbSA_LockControls</symbol> +action is used to implement a key that toggles the state of a boolean control +each time it is pressed and released. The +<symbol>XkbSA_LockNoLock</symbol> +and +<symbol>XkbSA_LockNoUnlock</symbol> +flags allow modifying the toggling behavior to only unlock or only lock the boolean control. </para> <para> -The <emphasis> -ctrls0</emphasis> -, <emphasis> -ctrls1</emphasis> -, <emphasis> -ctrls2</emphasis> -, and <emphasis> -ctrls3</emphasis> - fields represent the boolean controls in the <emphasis> -enabled_ctrls</emphasis> - field of the controls structure (see section 10.1). Xkb provides the following +The +<structfield>ctrls0</structfield>, +<structfield>ctrls1</structfield>, +<structfield>ctrls2</structfield>, +and +<structfield>ctrls3</structfield> +fields represent the boolean controls in the +<structfield>enabled_ctrls</structfield> +field of the controls structure (see <link linkend="Controls_that_Enable_and_Disable_Other_Controls">section 10.1</link>). Xkb provides the following macros, to convert between the two formats: </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -unsigned int <emphasis> -XkbActionCtrls</emphasis> -(<emphasis> -act</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbCtrlsAction <emphasis> -act</emphasis> -; /* action from which to extract controls */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbActionCtrls</emphasis> - returns the <emphasis> -ctrls</emphasis> - fields of <emphasis> -act</emphasis> - converted to an unsigned int. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbSAActionSetCtrls</emphasis> -(<emphasis> -act, ctrls</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbCtrlsAction <emphasis> -act</emphasis> -; /* action in which to set ctrls0-ctrls3 */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -ctrls</emphasis> -; /* value to set in ctrls0-ctrls3 */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbActionCtrls"><primary><function>XkbActionCtrls</function></primary></indexterm> +<funcsynopsis id="XkbActionCtrls"> + <funcprototype> + <funcdef>unsigned int <function>XkbActionCtrls</function></funcdef> +<!-- ( +<parameter>act</parameter> +) /* macro */ --> + + <paramdef>XkbCtrlsAction <parameter>act</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to extract controls + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbActionCtrls</function> +returns the +<structfield>ctrls</structfield> +fields of +<parameter>act</parameter> +converted to an unsigned int. +</para> + + +<indexterm significance="preferred" zone="XkbSAActionSetCtrls"><primary><function>XkbSAActionSetCtrls</function></primary></indexterm> +<funcsynopsis id="XkbSAActionSetCtrls"> + <funcprototype> + <funcdef>void <function>XkbSAActionSetCtrls</function></funcdef> +<!-- ( +<parameter>act, ctrls</parameter> +) /* macro */ --> + + <paramdef>XkbCtrlsAction <parameter>act</parameter></paramdef> + <paramdef>unsigned int <parameter>ctrls</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action in which to set ctrls0-ctrls3 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ctrls</parameter> + </term> + <listitem> + <para> + value to set in ctrls0-ctrls3 + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbSAActionSetCtrls</emphasis> - sets the <emphasis> -ctrls0</emphasis> - through <emphasis> -ctrls3</emphasis> - fields of <emphasis> -act</emphasis> - from <emphasis> -ctrls</emphasis> -. +<function>XkbSAActionSetCtrls</function> +sets the +<structfield>ctrls0</structfield> +through +<structfield>ctrls3</structfield> +fields of +<parameter>act</parameter> +from +<parameter>ctrls</parameter>. </para> </sect2> <sect2 id='Actions_for_Generating_Messages'> <title>Actions for Generating Messages</title> +<indexterm significance="preferred" zone="Actions_for_Generating_Messages"> +<primary><structname>XkbMessageAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbMessageAction</emphasis> - structure generate <emphasis> -XkbActionMessage</emphasis> - events: -</para> +Actions associated with the +<structname>XkbMessageAction</structname> +structure generate +<symbol>XkbActionMessage</symbol> +events: + +<programlisting> +#define XkbActionMessageLength 6 -<para><programlisting> -#define XkbActionMessageLength 6 -</programlisting></para> -<para><programlisting> typedef struct _XkbMessageAction { - unsigned char type; /* <emphasis> XkbSA_ActionMessage</emphasis> */ - unsigned char flags; /* controls event generation via key presses and releases */ - unsigned char message[XkbActionMessageLength]; /* message */ -} <emphasis>XkbMessageAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_ActionMessage</symbol> */ + unsigned char flags; /* controls event generation via + key presses and releases */ + unsigned char message[XkbActionMessageLength]; /* message */ +} <structname>XkbMessageAction</structname>; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field of the <emphasis> -XkbMessageAction</emphasis> - structure should always be <emphasis> -XkbSA_ActionMessage</emphasis> -. +The +<structfield>type</structfield> +field of the +<structname>XkbMessageAction</structname> +structure should always be +<symbol>XkbSA_ActionMessage</symbol>. </para> <para> -The <emphasis> -flags</emphasis> - field is composed of the bitwise inclusive OR of the masks shown in Table -16.16. +The +<structfield>flags</structfield> +field is composed of the bitwise inclusive OR of the masks shown in +<link linkend="table16.16">Table 16.16</link>. </para> -<table frame='topbot'> +<table id='table16.16' frame='topbot'> <title>Message Action Flags</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -2947,35 +2955,35 @@ flags</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_MessageOnPress</emphasis></entry> + <entry><symbol>XkbSA_MessageOnPress</symbol></entry> <entry> -If set, key press events generate an <emphasis> -XkbActionMessage</emphasis> - event that reports the keycode, event type, and contents of the <emphasis> -message</emphasis> - field. +If set, key press events generate an +<symbol>XkbActionMessage</symbol> +event that reports the keycode, event type, and contents of the +<structfield>message</structfield> +field. </entry> </row> <row> - <entry><emphasis>XkbSA_MessageOnRelease</emphasis></entry> + <entry><symbol>XkbSA_MessageOnRelease</symbol></entry> <entry> -If set, key release events generate an <emphasis> -XkbActionMessage</emphasis> - event that reports the keycode, event type, and contents of the <emphasis> -message</emphasis> - field. +If set, key release events generate an +<symbol>XkbActionMessage</symbol> +event that reports the keycode, event type, and contents of the +<structfield>message</structfield> +field. </entry> </row> <row> - <entry><emphasis>XkbSA_MessageGenKeyEvent</emphasis></entry> + <entry><symbol>XkbSA_MessageGenKeyEvent</symbol></entry> <entry> -If set, key press and key release events generate <emphasis> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events, regardless of whether they generate <emphasis> -XkbActionMessage</emphasis> - events. +If set, key press and key release events generate +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events, regardless of whether they generate +<symbol>XkbActionMessage</symbol> +events. </entry> </row> </tbody> @@ -2983,143 +2991,145 @@ XkbActionMessage</emphasis> </table> <para> -The <emphasis> -message</emphasis> - field is an array of <emphasis> -XkbActionMessageLength</emphasis> - unsigned characters and may be set to anything the keymap designer wishes. +The +<structfield>message</structfield> +field is an array of +<symbol>XkbActionMessageLength</symbol> +unsigned characters and may be set to anything the keymap designer wishes. </para> <sect3 id='Detecting_Key_Action_Messages'> <title>Detecting Key Action Messages</title> +<indexterm significance="preferred" zone="Detecting_Key_Action_Messages"> +<primary>events</primary><secondary><symbol>XkbActionMessage</symbol></secondary></indexterm> +<indexterm significance="preferred" zone="Detecting_Key_Action_Messages"> +<primary><structname>XkbActionMessageEvent</structname></primary></indexterm> <para> -To receive <emphasis> -XkbActionMessage</emphasis> - events by calling either <emphasis> -XkbSelectEvents</emphasis> - or <emphasis> -XkbSelectEventDetails</emphasis> - (see section 4.3). +To receive +<symbol>XkbActionMessage</symbol> +events by calling either +<function>XkbSelectEvents</function> +or +<function>XkbSelectEventDetails</function> +(see <link linkend="Selecting_Xkb_Events">section 4.3</link>). </para> <para> -To receive <emphasis> -XkbActionMessage</emphasis> - events under all possible conditions, use <emphasis> -XkbSelectEvents</emphasis> - and pass <emphasis> -XkbActionMessageMask</emphasis> - in both <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> -. +To receive +<symbol>XkbActionMessage</symbol> +events under all possible conditions, use +<function>XkbSelectEvents</function> +and pass +<symbol>XkbActionMessageMask</symbol> +in both +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter>. </para> <para> -The <emphasis> -XkbActionMessage</emphasis> - event has no event details. However, you can call <emphasis> -XkbSelectEventDetails</emphasis> - using <emphasis> -XkbActionMessage</emphasis> - as the <emphasis> -event_type</emphasis> - and specifying <emphasis> -XkbAllActionMessageMask</emphasis> - in <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits.</emphasis> - This has the same effect as a call to <emphasis> -XkbSelectEvents</emphasis>. +The +<symbol>XkbActionMessage</symbol> +event has no event details. However, you can call +<function>XkbSelectEventDetails</function> +using +<symbol>XkbActionMessage</symbol> +as the +<structfield>event_type</structfield> +and specifying +<symbol>XkbAllActionMessagesMask</symbol> +in +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter>. +This has the same effect as a call to +<function>XkbSelectEvents</function>. </para> <para> -The structure for the <emphasis> -XkbActionMessage</emphasis> - event is defined as follows: -</para> +The structure for the +<symbol>XkbActionMessage</symbol> +event is defined as follows: -<para><programlisting> +<programlisting> typedef struct _XkbActionMessage { - int type; /* Xkb extension base event code */ - unsigned long serial; /* X server serial number for event */ - Bool send_event; /* <emphasis>True</emphasis> => synthetically generated */ - Display * display; /* server connection where event generated */ - Time time; /* server time when event generated */ - int xkb_type; /* <emphasis>XkbActionMessage</emphasis> */ - int device; /* Xkb device ID, will not be <emphasis> XkbUseCoreKbd</emphasis> */ - KeyCode keycode; /* keycode of key triggering event */ - Bool press; /* <emphasis>True</emphasis> => key press, - <emphasis>False</emphasis> => release */ - Bool key_event_follows; /* <emphasis>True</emphasis> => KeyPress/KeyRelease follows */ - char message[XkbActionMessageLength+1]; /* message text */ -} <emphasis>XkbActionMessageEvent</emphasis>; + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* <symbol>True</symbol> ⇒ synthetically generated */ + Display * display; /* server connection where event generated */ + Time time; /* server time when event generated */ + int xkb_type; /* <symbol>XkbActionMessage</symbol> */ + int device; /* Xkb device ID, + will not be <symbol>XkbUseCoreKbd</symbol> */ + KeyCode keycode; /* keycode of key triggering event */ + Bool press; /* <symbol>True</symbol> ⇒ key press, + <symbol>False</symbol> ⇒ release */ + Bool key_event_follows;/* <symbol>True</symbol> ⇒ KeyPress/KeyRelease follows */ + char message[XkbActionMessageLength+1]; /* message text */ +} <structname>XkbActionMessageEvent</structname>; </programlisting></para> <para> -The <emphasis> -keycode</emphasis> - is the keycode of the key that was pressed or released. The <emphasis> -press</emphasis> - field specifies whether the event was the result of a key press or key +The +<structfield>keycode</structfield> +is the keycode of the key that was pressed or released. The +<structfield>press</structfield> +field specifies whether the event was the result of a key press or key release. </para> <para> -The <emphasis> -key_event_follows</emphasis> - specifies whether a <emphasis> -KeyPress</emphasis> - (if <emphasis> -press</emphasis> - is <emphasis> -True</emphasis> -) or <emphasis> -KeyRelease</emphasis> - (if <emphasis> -press</emphasis> - is <emphasis> -False</emphasis> -) event is also sent to the client. As with all other Xkb events, <emphasis> -XkbActionMessageEvent</emphasis> -s are delivered to all clients requesting them, regardless of the current -keyboard focus. However, the <emphasis> -KeyPress</emphasis> - or <emphasis> -KeyRelease</emphasis> - event that conditionally follows an <emphasis> -XkbActionMessageEvent</emphasis> - is sent only to the client selected by the current keyboard focus. <emphasis> -key_event_follows</emphasis> - is <emphasis> -True</emphasis> - only for the client that is actually sent the following <emphasis> -KeyPress</emphasis> - or <emphasis> -KeyRelease</emphasis> - event. -</para> - - -<para> -The <emphasis> -message</emphasis> - field is set to the message specified in the action and is guaranteed to be -<emphasis> -NULL</emphasis> --terminated; the Xkb extension forces a <emphasis> -NULL</emphasis> - into <emphasis> -message</emphasis> -[<emphasis> -XkbActionMessageLength</emphasis> +The +<structfield>key_event_follows</structfield> +specifies whether a +<symbol>KeyPress</symbol> +(if +<structfield>press</structfield> +is +<symbol>True</symbol>) +or +<symbol>KeyRelease</symbol> +(if +<structfield>press</structfield> +is +<symbol>False</symbol>) +event is also sent to the client. As with all other Xkb events, +<structname>XkbActionMessageEvent</structname>s +are delivered to all clients requesting them, regardless of the current +keyboard focus. However, the +<symbol>KeyPress</symbol> +or +<symbol>KeyRelease</symbol> +event that conditionally follows an +<structname>XkbActionMessageEvent</structname> +is sent only to the client selected by the current keyboard focus. +<structfield>key_event_follows</structfield> +is +<symbol>True</symbol> +only for the client that is actually sent the following +<symbol>KeyPress</symbol> +or +<symbol>KeyRelease</symbol> +event. +</para> + + +<para> +The +<structfield>message</structfield> +field is set to the message specified in the action and is guaranteed to be +<symbol>NULL</symbol> +-terminated; the Xkb extension forces a +<symbol>NULL</symbol> +into +<structfield>message</structfield> +[ +<symbol>XkbActionMessageLength</symbol> ]. </para> @@ -3128,87 +3138,88 @@ XkbActionMessageLength</emphasis> </sect2> <sect2 id='Actions_for_Generating_a_Different_Keycode'> <title>Actions for Generating a Different Keycode</title> +<indexterm significance="preferred" zone="Actions_for_Generating_a_Different_Keycode"> +<primary><structname>XkbRedirectKeyAction</structname></primary></indexterm> <para> -Actions associated with the <emphasis> -XkbRedirectKeyAction</emphasis> - structure generate <emphasis> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events containing a keycode different from the key that was pressed or +Actions associated with the +<structname>XkbRedirectKeyAction</structname> +structure generate +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events containing a keycode different from the key that was pressed or released: -</para> -<para><programlisting> +<programlisting> typedef struct _XkbRedirectKeyAction { - unsigned char type; /* <emphasis> XkbSA_RedirectKey</emphasis> */ - unsigned char new_key; /* keycode to be put in event */ - unsigned char mods_mask; /* mask of real mods to be reset */ - unsigned char mods; /* mask of real mods to take values from */ - unsigned char vmods_mask0; /* first half of mask of virtual mods to be reset */ - unsigned char vmods_mask1; /* other half of mask of virtual mods to be reset */ - unsigned char vmods0; /* first half of mask of virtual mods to take values from */ - unsigned char vmods1; /* other half of mask of virtual mods to take values from */ -} <emphasis>XkbRedirectKeyAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_RedirectKey</symbol> */ + unsigned char new_key; /* keycode to be put in event */ + unsigned char mods_mask; /* mask of real mods to be reset */ + unsigned char mods; /* mask of real mods to take values from */ + unsigned char vmods_mask0; /* first half of mask of virtual mods + to be reset */ + unsigned char vmods_mask1; /* other half of mask of virtual mods + to be reset */ + unsigned char vmods0; /* first half of mask of virtual mods + to take values from */ + unsigned char vmods1; /* other half of mask of virtual mods + to take values from */ +} <structname>XkbRedirectKeyAction</structname>; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field for the <emphasis> -XkbRedirectKeyAction</emphasis> - structure should always be <emphasis> -XkbSA_RedirectKey</emphasis> -. +The +<structfield>type</structfield> +field for the +<structname>XkbRedirectKeyAction</structname> +structure should always be +<symbol>XkbSA_RedirectKey</symbol>. </para> <para> -Key presses cause a <emphasis> -KeyPress</emphasis> - event for the key specified by the <emphasis> -new_key</emphasis> - field instead of the actual key. The state reported in this event reports the +Key presses cause a +<symbol>KeyPress</symbol> +event for the key specified by the +<structfield>new_key</structfield> +field instead of the actual key. The state reported in this event reports the current effective modifiers changed as follows: any real modifiers selected by -the <emphasis> -mods_mask</emphasis> - field are set to corresponding values from the <emphasis> -mods</emphasis> - field. Any real modifiers bound to the virtual modifiers specified by the -<emphasis> -vmods_mask0</emphasis> - and <emphasis> -vmods_mask1</emphasis> - fields are either set or cleared, depending on the corresponding values in the -<emphasis> -vmods0</emphasis> - and <emphasis> -vmods1</emphasis> - fields. If the real and virtual modifier definitions specify conflicting +the +<structfield>mods_mask</structfield> +field are set to corresponding values from the +<structfield>mods</structfield> +field. Any real modifiers bound to the virtual modifiers specified by the +<structfield>vmods_mask0</structfield> +and +<structfield>vmods_mask1</structfield> +fields are either set or cleared, depending on the corresponding values in the +<structfield>vmods0</structfield> +and +<structfield>vmods1</structfield> +fields. If the real and virtual modifier definitions specify conflicting values for a single modifier, the real modifier definition has priority. </para> <para> -Key releases cause a <emphasis> -KeyRelease</emphasis> - event for the key specified by the <emphasis> -new_key</emphasis> - field instead of the actual key. The state for this event consists of the +Key releases cause a +<symbol>KeyRelease</symbol> +event for the key specified by the +<structfield>new_key</structfield> +field instead of the actual key. The state for this event consists of the effective keyboard modifiers at the time of the release, changed as described previously. </para> <para> -The <emphasis> -XkbSA_RedirectKey</emphasis> - action normally redirects to another key on the same device as the key that +The +<symbol>XkbSA_RedirectKey</symbol> +action normally redirects to another key on the same device as the key that caused the event, unless that device does not belong to the input extension -<emphasis> -KeyClass</emphasis> -, in which case this action causes an event on the core keyboard device. (The +<symbol>KeyClass</symbol>, +in which case this action causes an event on the core keyboard device. (The input extension categorizes devices by breaking them into classes. Keyboards, and other input devices with keys, are classified as KeyClass devices by the input extension.) @@ -3216,215 +3227,219 @@ input extension.) <para> -The <emphasis> -vmods_mask0</emphasis> - and <emphasis> -vmods_mask1</emphasis> - fields actually represent one <emphasis> -vmods_mask</emphasis> - value, as described in Chapter 7. Xkb provides the following macros, to +The +<structfield>vmods_mask0</structfield> +and +<structfield>vmods_mask1</structfield> +fields actually represent one +<emphasis>vmods_mask</emphasis> +value, as described in <xref linkend="Virtual_Modifiers" />. Xkb provides the following macros, to convert between the two formats: </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -unsigned int <emphasis> -XkbSARedirectVModsMask</emphasis> -(<emphasis> -act</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbRedirectKeyAction <emphasis> -act</emphasis> -; /* action from which to extract vmods */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSARedirectVModsMask</emphasis> - returns the <emphasis> -vmods_mask0</emphasis> - and <emphasis> -vmods_mask1</emphasis> - fields of <emphasis> -act</emphasis> - converted to an unsigned int. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbSARedirectSetVModsMask</emphasis> -(<emphasis> -act, vm</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbRedirectKeyAction <emphasis> -act</emphasis> -; /* action in which to set vmods */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -vm</emphasis> -; /* new value for virtual modifier mask */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbSARedirectVModsMask"><primary><function>XkbSARedirectVModsMask</function></primary></indexterm> +<funcsynopsis id="XkbSARedirectVModsMask"> + <funcprototype> + <funcdef>unsigned int <function>XkbSARedirectVModsMask</function></funcdef> +<!-- ( +<parameter>act</parameter> +) /* macro */ --> + + <paramdef>XkbRedirectKeyAction <parameter>act</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to extract vmods + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSARedirectVModsMask</function> +returns the +<structfield>vmods_mask0</structfield> +and +<structfield>vmods_mask1</structfield> +fields of +<parameter>act</parameter> +converted to an unsigned int. +</para> + + +<indexterm significance="preferred" zone="XkbSARedirectSetVModsMask"><primary><function>XkbSARedirectSetVModsMask</function></primary></indexterm> +<funcsynopsis id="XkbSARedirectSetVModsMask"> + <funcprototype> + <funcdef>void <function>XkbSARedirectSetVModsMask</function></funcdef> +<!-- ( +<parameter>act, vm</parameter> +) /* macro */ --> + + <paramdef>XkbRedirectKeyAction <parameter>act</parameter></paramdef> + <paramdef>unsigned int <parameter>vm</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action in which to set vmods + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>vm</parameter> + </term> + <listitem> + <para> + new value for virtual modifier mask + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbSARedirectSetVModsMask</emphasis> - sets the <emphasis> -vmods_mask0</emphasis> - and <emphasis> -vmods_mask1</emphasis> - fields of <emphasis> -act</emphasis> - from <emphasis> -vm</emphasis> -. +<function>XkbSARedirectSetVModsMask</function> +sets the +<structfield>vmods_mask0</structfield> +and +<structfield>vmods_mask1</structfield> +fields of +<parameter>act</parameter> +from +<parameter>vm</parameter>. </para> <para> -Similarly, the <emphasis> -vmods0</emphasis> - and <emphasis> -vmods1</emphasis> - fields actually represent one <emphasis> -vmods </emphasis> -value, as described in Chapter 7. To convert between the two formats, Xkb +Similarly, the +<structfield>vmods0</structfield> +and +<structfield>vmods1</structfield> +fields actually represent one +<structfield>vmods</structfield> +value, as described in <xref linkend="Virtual_Modifiers" />. To convert between the two formats, Xkb provides the following convenience macros: </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -unsigned int <emphasis> -XkbSARedirectVMods</emphasis> -(<emphasis> -act</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbRedirectKeyAction <emphasis> -act</emphasis> -; /* action from which to extract vmods */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbSARedirectVMods"><primary><function>XkbSARedirectVMods</function></primary></indexterm> +<funcsynopsis id="XkbSARedirectVMods"> + <funcprototype> + <funcdef>unsigned int <function>XkbSARedirectVMods</function></funcdef> +<!-- ( +<parameter>act</parameter> +) /* macro */ --> + + <paramdef>XkbRedirectKeyAction <parameter>act</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action from which to extract vmods + </para> + </listitem> + </varlistentry> +</variablelist> -<literallayout> - <emphasis>XkbSARedirectVModsMask</emphasis> returns the <emphasis>vmods0</emphasis> - and <emphasis>vmods1</emphasis> fields of <emphasis>act</emphasis> +<para> + <function>XkbSARedirectVModsMask</function> returns the <structfield>vmods0</structfield> + and <structfield>vmods1</structfield> fields of <parameter>act</parameter> converted to an unsigned int. -</literallayout> +</para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbSARedirectSetVMods</emphasis> -(<emphasis> -act, vm</emphasis> -) /* macro */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbRedirectKeyAction <emphasis> -act</emphasis> -; /* action in which to set vmods */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -v</emphasis> -; /* new value for virtual modifiers */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> -<literallayout> - <emphasis> XkbSARedirectSetVModsMask</emphasis> sets the <emphasis>vmods0</emphasis> - and <emphasis>vmods1</emphasis> of <emphasis>act</emphasis> from <emphasis>v</emphasis>. -</literallayout> +<indexterm significance="preferred" zone="XkbSARedirectSetVMods"><primary><function>XkbSARedirectSetVMods</function></primary></indexterm> +<funcsynopsis id="XkbSARedirectSetVMods"> + <funcprototype> + <funcdef>void <function>XkbSARedirectSetVMods</function></funcdef> +<!-- ( +<parameter>act, vm</parameter> +) /* macro */ --> + + <paramdef>XkbRedirectKeyAction <parameter>act</parameter></paramdef> + <paramdef>unsigned int <parameter>v</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>act</parameter> + </term> + <listitem> + <para> + action in which to set vmods + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>v</parameter> + </term> + <listitem> + <para> + new value for virtual modifiers + </para> + </listitem> + </varlistentry> +</variablelist> +<para> + <function>XkbSARedirectSetVModsMask</function> sets the <structfield>vmods0</structfield> + and <structfield>vmods1</structfield> of <parameter>act</parameter> from <parameter>v</parameter>. +</para> </sect2> <sect2 id='Actions_for_Generating_DeviceButtonPress_and_DeviceButtonRelease'> <title>Actions for Generating DeviceButtonPress and DeviceButtonRelease</title> - -<para> -Actions associated with <emphasis> -XkbDeviceBtnAction</emphasis> - structures generate <emphasis> -DeviceButtonPress</emphasis> - and <emphasis> -DeviceButtonRelease</emphasis> - events instead of normal <emphasis> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events: -</para> - -<para><programlisting> +<indexterm significance="preferred" zone="Actions_for_Generating_DeviceButtonPress_and_DeviceButtonRelease"> +<primary><structname>XkbDeviceBtnAction</structname></primary></indexterm> + +<para> +Actions associated with +<structname>XkbDeviceBtnAction</structname> +structures generate +<symbol>DeviceButtonPress</symbol> +and +<symbol>DeviceButtonRelease</symbol> +events instead of normal +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events: + +<programlisting> typedef struct _XkbDeviceBtnAction { - unsigned char type; /* <emphasis> XkbSA_DeviceBtn, XkbSA_LockDeviceBtn</emphasis> */ - unsigned char flags; /* with <emphasis> type</emphasis> , specifies locking or unlocking */ - unsigned char count; /* controls number of DeviceButtonPress and Release events */ - unsigned char button; /* index of button on <emphasis> device</emphasis> */ - unsigned char device; /* device ID of an X input extension device */ -} <emphasis>XkbDeviceBtnAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_DeviceBtn</symbol>, <symbol>XkbSA_LockDeviceBtn</symbol> */ + unsigned char flags; /* with <structfield>type</structfield>, specifies locking or unlocking */ + unsigned char count; /* controls number of DeviceButtonPress + and Release events */ + unsigned char button; /* index of button on <structfield>device</structfield> */ + unsigned char device; /* device ID of an X input extension device */ +} <structname>XkbDeviceBtnAction</structname>; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field can have any one of the values shown in Table 16.17. +The +<structfield>type</structfield> +field can have any one of the values shown in +<link linkend="table16.17">Table 16.17</link>. </para> -<table frame='topbot'> +<table id='table16.17' frame='topbot'> <title>Device Button Action Types</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -3438,90 +3453,89 @@ type</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_DeviceBtn</emphasis></entry> + <entry><symbol>XkbSA_DeviceBtn</symbol></entry> <entry> <itemizedlist> <listitem> <para> 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> -XkbSA_NoAction</emphasis>. +specified by this action are illegal, this action behaves like +<symbol>XkbSA_NoAction</symbol>. </para> </listitem> <listitem> <para> Otherwise, key presses cause one or more input extension device events instead -of the usual key press event. If the <emphasis> -count</emphasis> - field is zero, a key press generates a single <emphasis> -DeviceButtonPress</emphasis> - event. If count is greater than zero, a key press event generates <emphasis> -count</emphasis> - pairs of <emphasis> -DeviceButtonPress</emphasis> - and <emphasis> -DeviceButtonRelease</emphasis> - events. +of the usual key press event. If the +<structfield>count</structfield> +field is zero, a key press generates a single +<symbol>DeviceButtonPress</symbol> +event. If count is greater than zero, a key press event generates +<structfield>count</structfield> +pairs of +<symbol>DeviceButtonPress</symbol> +and +<symbol>DeviceButtonRelease</symbol> +events. </para> </listitem> <listitem> <para> -If <emphasis> -count</emphasis> - is zero, a key release generates an input extension <emphasis> -DeviceButtonRelease</emphasis> - event that matches the event generated by the corresponding key press. If -<emphasis> -count</emphasis> - is nonzero, a key release does not cause a <emphasis> -DeviceButtonRelease</emphasis> - event. Key releases never cause <emphasis> -KeyRelease</emphasis> - events. +If +<structfield>count</structfield> +is zero, a key release generates an input extension +<symbol>DeviceButtonRelease</symbol> +event that matches the event generated by the corresponding key press. If +<structfield>count</structfield> +is nonzero, a key release does not cause a +<symbol>DeviceButtonRelease</symbol> +event. Key releases never cause +<symbol>KeyRelease</symbol> +events. </para> </listitem> </itemizedlist> </entry> </row> <row> - <entry><emphasis>XkbSA_LockDeviceBtn</emphasis></entry> + <entry><symbol>XkbSA_LockDeviceBtn</symbol></entry> <entry> <itemizedlist> <listitem> <para> If the device or button specified by this action are illegal, this action -behaves like <emphasis>XkbSA_NoAction</emphasis>. +behaves like <symbol>XkbSA_NoAction</symbol>. </para> </listitem> <listitem> <para> -Otherwise, if the specified button is not locked and the <emphasis> -XkbSA_LockNoLock</emphasis> - bit is not set in the <emphasis> -flags</emphasis> - field, a key press generates an input extension <emphasis> -DeviceButtonPress</emphasis> - event instead of a <emphasis> -KeyPress</emphasis> - event and locks the button. If the button is already locked or if <emphasis> -XkbSA_LockNoLock</emphasis> - bit is set in the <emphasis> -flags</emphasis> - field, the key press is ignored and has no effect. +Otherwise, if the specified button is not locked and the +<symbol>XkbSA_LockNoLock</symbol> +bit is not set in the +<structfield>flags</structfield> +field, a key press generates an input extension +<symbol>DeviceButtonPress</symbol> +event instead of a +<symbol>KeyPress</symbol> +event and locks the button. If the button is already locked or if +<symbol>XkbSA_LockNoLock</symbol> +bit is set in the +<structfield>flags</structfield> +field, the key press is ignored and has no effect. </para> </listitem> <listitem> <para> -If the corresponding key press was ignored, and if the <emphasis> -XkbSA_LockNoUnlock</emphasis> - bit is not set in the <emphasis> -flags</emphasis> - field, a key release generates an input extension <emphasis> -DeviceButtonRelease</emphasis> - event instead of a <emphasis> -KeyRelease</emphasis> - event and unlocks the button. If the corresponding key press locked a button, +If the corresponding key press was ignored, and if the +<symbol>XkbSA_LockNoUnlock</symbol> +bit is not set in the +<structfield>flags</structfield> +field, a key release generates an input extension +<symbol>DeviceButtonRelease</symbol> +event instead of a +<symbol>KeyRelease</symbol> +event and unlocks the button. If the corresponding key press locked a button, the key release is ignored and has no effect. </para> </listitem> @@ -3533,13 +3547,13 @@ the key release is ignored and has no effect. </table> <para> -The <emphasis> -flags</emphasis> - field is composed of the bitwise inclusive OR of the masks shown in Table -16.18. +The +<structfield>flags</structfield> +field is composed of the bitwise inclusive OR of the masks shown in +<link linkend="table16.18">Table 16.18</link>. </para> -<table frame='topbot'> +<table id='table16.18' frame='topbot'> <title>Device Button Action Flags</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -3553,19 +3567,19 @@ flags</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_LockNoLock</emphasis></entry> + <entry><symbol>XkbSA_LockNoLock</symbol></entry> <entry> -If set, and the action type is <emphasis> -XkbSA_LockDeviceBtn</emphasis> -, the server only unlocks the button. +If set, and the action type is +<symbol>XkbSA_LockDeviceBtn</symbol>, +the server only unlocks the button. </entry> </row> <row> - <entry><emphasis>XkbSA_LockNoUnlock</emphasis></entry> + <entry><symbol>XkbSA_LockNoUnlock</symbol></entry> <entry> -If set, and the action type is <emphasis> -XkbSA_LockDeviceBtn</emphasis> -, the server only locks the button. +If set, and the action type is +<symbol>XkbSA_LockDeviceBtn</symbol>, +the server only locks the button. </entry> </row> </tbody> @@ -3575,64 +3589,71 @@ XkbSA_LockDeviceBtn</emphasis> </sect2> <sect2 id='Actions_for_Simulating_Events_from_Device_Valuators'> <title>Actions for Simulating Events from Device Valuators</title> - -<para> -A <emphasis> -valuator</emphasis> - manipulates a range of values for some entity, like a mouse axis, a slider or -a dial. Actions associated with <emphasis> -XkbDeviceValuatorAction</emphasis> - structures are used to simulate events from one or two input extension device +<indexterm significance="preferred" zone="Actions_for_Simulating_Events_from_Device_Valuators"> +<primary><structname>XkbDeviceValuatorAction</structname></primary></indexterm> + +<para> +A +<firstterm>valuator</firstterm> +<indexterm significance="preferred" zone="Actions_for_Simulating_Events_from_Device_Valuators"> +<primary>valuator</primary></indexterm> +manipulates a range of values for some entity, like a mouse axis, a slider or +a dial. Actions associated with +<structname>XkbDeviceValuatorAction</structname> +structures are used to simulate events from one or two input extension device valuators. </para> <para><programlisting> typedef struct _XkbDeviceValuatorAction { - unsigned char type; /*<emphasis> XkbSA_DeviceValuator</emphasis> */ - unsigned char device; /* device ID */ - unsigned char v1_what; /* determines how valuator is to behave for valuator 1 */ - unsigned char v1_ndx; /* specifies a real valuator */ - unsigned char v1_value; /* the value for valuator 1 */ - unsigned char v2_what; /* determines how valuator is to behave for valuator 2 */ - unsigned char v2_ndx; /* specifies a real valuator */ - unsigned char v2_value; /* the value for valuator 1 */ -} <emphasis>XkbDeviceValuatorAction</emphasis>; + unsigned char type; /* <symbol>XkbSA_DeviceValuator</symbol> */ + unsigned char device; /* device ID */ + unsigned char v1_what; /* determines how valuator is + to behave for valuator 1 */ + unsigned char v1_ndx; /* specifies a real valuator */ + unsigned char v1_value; /* the value for valuator 1 */ + unsigned char v2_what; /* determines how valuator is + to behave for valuator 2 */ + unsigned char v2_ndx; /* specifies a real valuator */ + unsigned char v2_value; /* the value for valuator 1 */ +} <structname>XkbDeviceValuatorAction</structname>; </programlisting></para> <para> -If <emphasis> -device</emphasis> - is illegal or if neither <emphasis> -v1_ndx</emphasis> - nor <emphasis> -v2_ndx</emphasis> - specifies a legal valuator, this action behaves like <emphasis> -XkbSA_NoAction</emphasis>. -</para> - - -<para> -The low four bits of <emphasis> -v1_what</emphasis> - and <emphasis> -v2_what</emphasis> - specify the corresponding scale value (denoted <emphasis> -val<n>Scale</emphasis> - in Table 16.17), if needed. The high four bits of <emphasis> -v1_what</emphasis> - and <emphasis> -v2_what</emphasis> - specify the operation to perform to set the values. The high four bits of -<emphasis> -v1_what</emphasis> - and <emphasis> -v2_what</emphasis> - can have the values shown in Table 16.17; the use of <emphasis> -val<n>Scale</emphasis> - is shown in that table also. -</para> - -<table frame='topbot'> +If +<structfield>device</structfield> +is illegal or if neither +<structfield>v1_ndx</structfield> +nor +<structfield>v2_ndx</structfield> +specifies a legal valuator, this action behaves like +<symbol>XkbSA_NoAction</symbol>. +</para> + + +<para> +The low four bits of +<structfield>v1_what</structfield> +and +<structfield>v2_what</structfield> +specify the corresponding scale value (denoted +<structfield>val<n>Scale</structfield> +in <link linkend="table16.17">Table 16.17</link>), if needed. +The high four bits of +<structfield>v1_what</structfield> +and +<structfield>v2_what</structfield> +specify the operation to perform to set the values. The high four bits of +<structfield>v1_what</structfield> +and +<structfield>v2_what</structfield> +can have the values shown in <link linkend="table16.17">Table 16.17</link>; +the use of +<structfield>val<n>Scale</structfield> +is shown in that table also. +</para> + +<table id='table16.19' frame='topbot'> <title>Device Valuator v<n>_what High Bits Values</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -3646,40 +3667,40 @@ val<n>Scale</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSA_IgnoreVal</emphasis></entry> + <entry><symbol>XkbSA_IgnoreVal</symbol></entry> <entry>No action</entry> </row> <row> - <entry><emphasis>XkbSA_SetValMin</emphasis></entry> + <entry><symbol>XkbSA_SetValMin</symbol></entry> <entry> -<emphasis>v<n>_value</emphasis> is set to its minimum legal value. +<structfield>v<n>_value</structfield> is set to its minimum legal value. </entry> </row> <row> - <entry><emphasis>XkbSA_SetValCenter</emphasis></entry> + <entry><symbol>XkbSA_SetValCenter</symbol></entry> <entry> -<emphasis>v<n>_value</emphasis>is centered (to (max-min)/2). +<structfield>v<n>_value</structfield>is centered (to (max-min)/2). </entry> </row> <row> - <entry><emphasis>XkbSA_SetValMax</emphasis></entry> + <entry><symbol>XkbSA_SetValMax</symbol></entry> <entry> -<emphasis>v<n>_value</emphasis> is set to its maximum legal value. +<structfield>v<n>_value</structfield> is set to its maximum legal value. </entry> </row> <row> - <entry><emphasis>XkbSA_SetValRelative</emphasis></entry> + <entry><symbol>XkbSA_SetValRelative</symbol></entry> <entry> -<emphasis>v<n>_value</emphasis> * (2 -<emphasis>val<n>Scale</emphasis>) is added to -<emphasis>v<n>_value</emphasis>. +<structfield>v<n>_value</structfield> * (2 +<structfield>val<n>Scale</structfield>) is added to +<structfield>v<n>_value</structfield>. </entry> </row> <row> - <entry><emphasis>XkbSA_SetValAbsolute</emphasis></entry> + <entry><symbol>XkbSA_SetValAbsolute</symbol></entry> <entry> -<emphasis>v<n>_value</emphasis> - is set to (2 <emphasis>val<n>Scale</emphasis>). +<structfield>v<n>_value</structfield> +is set to (2 <structfield>val<n>Scale</structfield>). </entry> </row> </tbody> @@ -3687,39 +3708,37 @@ val<n>Scale</emphasis> </table> <para> -Illegal values for <emphasis> -XkbSA_SetValRelative</emphasis> - or <emphasis> -XkbSA_SetValAbsolute</emphasis> - are clamped into range. Note that all of these possibilities are legal for -absolute valuators. For relative valuators, only <emphasis> -XkbSA_SetValRelative</emphasis> - is permitted. Part of the input extension description of a device is the range +Illegal values for +<symbol>XkbSA_SetValRelative</symbol> +or +<symbol>XkbSA_SetValAbsolute</symbol> +are clamped into range. Note that all of these possibilities are legal for +absolute valuators. For relative valuators, only +<symbol>XkbSA_SetValRelative</symbol> +is permitted. Part of the input extension description of a device is the range of legal values for all absolute valuators, whence the maximum and minimum -legal values shown in Table 16.17. +legal values shown in <link linkend="table16.17">Table 16.17</link>. </para> <para> The following two masks are provided as a convenience to select either portion -of <emphasis> -v1_what</emphasis> - or <emphasis> -v2_what</emphasis> -: -</para> +of +<structfield>v1_what</structfield> +or +<structfield>v2_what</structfield>: -<literallayout> - #define XkbSA_ValOpMask (0x70) - #define XkbSA_ValScaleMask (0x07) -</literallayout> +<programlisting> +#define XkbSA_ValOpMask (0x70) +#define XkbSA_ValScaleMask (0x07) +</programlisting> +</para> <para> -<emphasis> -v1_ndx</emphasis> - and <emphasis> -v2_ndx</emphasis> - specify valuators that actually exists. For example, most mice have two +<structfield>v1_ndx</structfield> +and +<structfield>v2_ndx</structfield> +specify valuators that actually exists. For example, most mice have two valuators (x and y axes) so the only legal values for a mouse would be 0 and 1. For a dial box with eight dials, any value in the range 0..7 would be correct. </para> @@ -3730,118 +3749,120 @@ For a dial box with eight dials, any value in the range 0..7 would be correct. <title>Obtaining Key Actions for Keys from the Server</title> <para> -To update the actions (the <emphasis> -key_acts</emphasis> - array) for a subset of the keys in a keyboard description, use <emphasis> -XkbGetKeyActions</emphasis> -. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetKeyActions</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - first</emphasis> -, <emphasis> -num</emphasis> -,<emphasis> - xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -first</emphasis> -; /* keycode of first key of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -num</emphasis> -; /* number of keys desired */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* pointer to keyboard description where result is stored */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +To update the actions (the +<structfield>key_acts</structfield> +array) for a subset of the keys in a keyboard description, use +<function>XkbGetKeyActions</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetKeyActions"><primary><function>XkbGetKeyActions</function></primary></indexterm> +<funcsynopsis id="XkbGetKeyActions"> + <funcprototype> + <funcdef>Status <function>XkbGetKeyActions</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>first</parameter>, +<parameter>num</parameter>, +<parameter>xkb</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>first</parameter></paramdef> + <paramdef>unsigned int <parameter>num</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + keycode of first key of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num</parameter> + </term> + <listitem> + <para> + number of keys desired + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + pointer to keyboard description where result is stored + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbGetKeyActions</emphasis> - sends a request to the server to obtain the actions for <emphasis> -num</emphasis> - keys on the keyboard starting with key <emphasis> -first</emphasis> -. It waits for a reply and returns the actions in the <emphasis> -server</emphasis> --><emphasis> -key_acts</emphasis> - field of <emphasis> -xkb</emphasis> -. If successful, <emphasis> -XkbGetKeyActions</emphasis> - returns <emphasis> -Success</emphasis> -. The <emphasis> -xkb</emphasis> - parameter must be a pointer to a valid Xkb keyboard description. +<function>XkbGetKeyActions</function> +sends a request to the server to obtain the actions for +<parameter>num</parameter> +keys on the keyboard starting with key +<parameter>first</parameter>. +It waits for a reply and returns the actions in the +<structfield>server</structfield>-><structfield>key_acts</structfield> +field of +<parameter>xkb</parameter>. +If successful, +<function>XkbGetKeyActions</function> +returns +<symbol>Success</symbol>. +The +<parameter>xkb</parameter> +parameter must be a pointer to a valid Xkb keyboard description. </para> <para> -If the <emphasis> -server</emphasis> - map in the <emphasis> -xkb</emphasis> - parameter has not been allocated, <emphasis> -XkbGetKeyActions</emphasis> - allocates and initializes it before obtaining the actions. +If the +<structfield>server</structfield> +map in the +<parameter>xkb</parameter> +parameter has not been allocated, +<function>XkbGetKeyActions</function> +allocates and initializes it before obtaining the actions. </para> <para> If the server does not have a compatible version of Xkb, or the Xkb extension -has not been properly initialized, <emphasis> -XkbGetKeyActions</emphasis> - returns <emphasis> -BadAccess</emphasis> -. If <emphasis> -num</emphasis> - is less than 1 or greater than <emphasis> -XkbMaxKeyCount</emphasis> -, <emphasis> -XkbGetKeyActions</emphasis> - returns <emphasis> -BadValue</emphasis> -. If any allocation errors occur, <emphasis> -XkbGetKeyActions</emphasis> - returns <emphasis> -BadAlloc</emphasis> -. +has not been properly initialized, +<function>XkbGetKeyActions</function> +returns +<errorname>BadAccess</errorname>. +If +<parameter>num</parameter> +is less than 1 or greater than +<symbol>XkbMaxKeyCount</symbol>, +<function>XkbGetKeyActions</function> +returns +<errorname>BadValue</errorname>. +If any allocation errors occur, +<function>XkbGetKeyActions</function> +returns +<errorname>BadAlloc</errorname>. </para> @@ -3850,128 +3871,126 @@ BadAlloc</emphasis> <title>Changing the Number of Actions Bound to a Key</title> <para> -To change the number of actions bound to a key, use <emphasis> -XkbResizeKeyAction</emphasis> -. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbAction *<emphasis> -XkbResizeKeyActions</emphasis> -(<emphasis> -xkb</emphasis> -,<emphasis> - key</emphasis> -,<emphasis> - needed</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescRec *<emphasis> - xkb</emphasis> -; /* keyboard description to change */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - key</emphasis> -; /* keycode of key to change */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - needed</emphasis> -; /* new number of actions required */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -The <emphasis> -xkb</emphasis> - parameter points to the keyboard description containing the <emphasis> -key</emphasis> - whose number of actions is to be changed. The <emphasis> -key</emphasis> - parameter is the keycode of the key to change, and <emphasis> -needed</emphasis> - specifies the new number of actions required for the key. -</para> - - -<para> -<emphasis> -XkbResizeKeyActions</emphasis> - reserves the space needed for the actions and returns a pointer to the -beginning of the new array that holds the actions. It can change the <emphasis> -acts</emphasis> -, <emphasis> -num_acts</emphasis> -, and <emphasis> -size_acts</emphasis> - fields of <emphasis> -xkb</emphasis> --><emphasis> -server</emphasis> - if it is necessary to reallocate the <emphasis> -acts </emphasis> +To change the number of actions bound to a key, use +<function>XkbResizeKeyActions</function>. +</para> + +<indexterm significance="preferred" zone="XkbResizeKeyActions"><primary><function>XkbResizeKeyActions</function></primary></indexterm> +<funcsynopsis id="XkbResizeKeyActions"> + <funcprototype> + <funcdef>XkbAction *<function>XkbResizeKeyActions</function></funcdef> +<!-- ( +<parameter>xkb</parameter>, +<parameter>key</parameter>, +<parameter>needed</parameter> +) --> + + <paramdef>XkbDescRec *<parameter>xkb</parameter></paramdef> + <paramdef>int <parameter>key</parameter></paramdef> + <paramdef>int <parameter>needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>key</parameter> + </term> + <listitem> + <para> + keycode of key to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>needed</parameter> + </term> + <listitem> + <para> + new number of actions required + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<parameter>xkb</parameter> +parameter points to the keyboard description containing the +<parameter>key</parameter> +whose number of actions is to be changed. The +<parameter>key</parameter> +parameter is the keycode of the key to change, and +<parameter>needed</parameter> +specifies the new number of actions required for the key. +</para> + + +<para> +<function>XkbResizeKeyActions</function> +reserves the space needed for the actions and returns a pointer to the +beginning of the new array that holds the actions. It can change the +<structfield>acts</structfield>, +<structfield>num_acts</structfield>, +and +<structfield>size_acts</structfield> +fields of +<parameter>xkb</parameter>-><structfield>server</structfield> +if it is necessary to reallocate the +<structfield>acts</structfield> array. </para> <para> -If <emphasis> -needed</emphasis> - is greater than the current number of keysyms for the key, <emphasis> -XkbResizeKeyActions</emphasis> - initializes all new actions in the array to <emphasis> -NoAction</emphasis> -. +If +<parameter>needed</parameter> +is greater than the current number of keysyms for the key, +<function>XkbResizeKeyActions</function> +initializes all new actions in the array to +<emphasis>NoAction</emphasis>. </para> <para> Because the number of actions needed by a key is normally computed as width * -number of groups, and <emphasis> -XkbResizeKeyActions</emphasis> - does not modify either the width or number of groups for the key, a -discrepancy exists on return from <emphasis> -XkbResizeKeyActions</emphasis> - between the space allocated for the actions and the number required. The -unused entries in the list of actions returned by <emphasis> -XkbResizeKeyActions</emphasis> - are not preserved across future calls to any of the map editing functions, so +number of groups, and +<function>XkbResizeKeyActions</function> +does not modify either the width or number of groups for the key, a +discrepancy exists on return from +<function>XkbResizeKeyActions</function> +between the space allocated for the actions and the number required. The +unused entries in the list of actions returned by +<function>XkbResizeKeyActions</function> +are not preserved across future calls to any of the map editing functions, so you must update the key actions (which updates the width and number of groups -for the key) before calling another allocator function. A call to <emphasis> -XkbChangeTypesOfKey</emphasis> - updates these. +for the key) before calling another allocator function. A call to +<function>XkbChangeTypesOfKey</function> +updates these. </para> <para> If any allocation errors occur while resizing the number of actions bound to -the key, <emphasis> -XkbResizeKeyActions</emphasis> - returns <emphasis> -NULL</emphasis> -. +the key, +<function>XkbResizeKeyActions</function> +returns +<symbol>NULL</symbol>. </para> <note><para>A change to the number of actions bound to a key should be accompanied by a change in the number of symbols bound to a key. Refer to -section 15.3.7 for more information on changing the number of symbols bound to +<link linkend="Changing_the_Number_of_Symbols_Bound_to_a_Key">section 15.3.7</link> for more information on changing the number of symbols bound to a key.</para></note> @@ -3982,9 +4001,9 @@ a key.</para></note> <para> Key behavior refers to the demeanor of a key. For example, the expected -behavior of the <emphasis> -CapsLock</emphasis> - key is that it logically locks when pressed, and then logically unlocks when +behavior of the +<keycap>CapsLock</keycap> +key is that it logically locks when pressed, and then logically unlocks when pressed again. </para> @@ -3993,80 +4012,79 @@ pressed again. <title>Radio Groups</title> <para> -Keys that belong to the same radio group have the <emphasis> -XkbKB_RadioGroup</emphasis> - type in the <emphasis> -type</emphasis> - field and the radio group index specified in the <emphasis> -data</emphasis> - field in the <emphasis> -XkbBehavior</emphasis> - structure. If the radio group has a name in the <emphasis> -XkbNamesRec</emphasis> - structure, the radio group index is the index into the <emphasis> -radio_group</emphasis> - array in the <emphasis> -XkbNamesRec</emphasis> - structure. A radio group key when pressed stays logically down until another +Keys that belong to the same radio group have the +<symbol>XkbKB_RadioGroup</symbol> +type in the +<structfield>type</structfield> +field and the radio group index specified in the +<structfield>data</structfield> +field in the +<structname>XkbBehavior</structname> +structure. If the radio group has a name in the +<structname>XkbNamesRec</structname> +structure, the radio group index is the index into the +<structfield>radio_group</structfield> +array in the +<structname>XkbNamesRec</structname> +structure. A radio group key when pressed stays logically down until another key in the radio group is pressed, when the first key becomes logically up and -the new key becomes logically down. Setting the <emphasis> -XkbKB_RGAllowNone</emphasis> - bit in the behavior for all of the keys of the radio group means that pressing +the new key becomes logically down. Setting the +<symbol>XkbKB_RGAllowNone</symbol> +bit in the behavior for all of the keys of the radio group means that pressing the logically down member of the radio group causes it to logically release, in which case none of the keys of the radio group would be logically down. If -<emphasis> -XkbKB_RGAllowNone</emphasis> - is not set, there is no way to release the logically down member of the group. +<symbol>XkbKB_RGAllowNone</symbol> +is not set, there is no way to release the logically down member of the group. </para> <para> -The low five bits of the <emphasis> -data</emphasis> - field of the <emphasis> -XkbBehavior</emphasis> - structure are the group number, the high three bits are flags. The only flag +The low five bits of the +<structfield>data</structfield> +field of the +<structname>XkbBehavior</structname> +structure are the group number, the high three bits are flags. The only flag currently defined is: -</para> -<para><programlisting> -#define XkbRG_AllowNone 0x80 +<programlisting> +#define XkbKB_RGAllowNone 0x80 </programlisting></para> </sect2> <sect2 id='The_XkbBehavior_Structure'> <title>The XkbBehavior Structure</title> +<indexterm significance="preferred" zone="The_XkbBehavior_Structure"> +<primary><structname>XkbBehavior</structname></primary></indexterm> <para> -The <emphasis> -behaviors</emphasis> - field of the server map is an array of <emphasis> -XkbBehavior</emphasis> - structures, indexed by keycode, and contains the behavior for each key. The -<emphasis> -XkbBehavior</emphasis> - structure is defined as follows: -</para> +The +<structfield>behaviors</structfield> +field of the server map is an array of +<structname>XkbBehavior</structname> +structures, indexed by keycode, and contains the behavior for each key. The +<structname>XkbBehavior</structname> +structure is defined as follows: -<para><programlisting> +<programlisting> typedef struct _XkbBehavior { - unsigned char type; /* behavior type + optional - <emphasis> XkbKB_Permanent</emphasis> bit */ - unsigned char data; -} <emphasis>XkbBehavior</emphasis>; + unsigned char type; /* behavior type + optional + <symbol>XkbKB_Permanent</symbol> bit */ + unsigned char data; +} <structname>XkbBehavior</structname>; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field specifies the Xkb behavior, and the value of the <emphasis> -data</emphasis> - field depends on the <emphasis> -type</emphasis> -. Xkb supports the key behaviors shown in Table 16.20. +The +<structfield>type</structfield> +field specifies the Xkb behavior, and the value of the +<structfield>data</structfield> +field depends on the +<structfield>type</structfield>. +Xkb supports the key behaviors shown in +<link linkend="table16.20">Table 16.20</link>. </para> -<table frame='topbot'> +<table id='table16.20' frame='topbot'> <title>Key Behaviors</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -4080,43 +4098,43 @@ type</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbKB_Default</emphasis></entry> + <entry><symbol>XkbKB_Default</symbol></entry> <entry> -Press and release events are processed normally. The <emphasis> -data</emphasis> - field is unused. +Press and release events are processed normally. The +<structfield>data</structfield> +field is unused. </entry> </row> <row> - <entry><emphasis>XkbKB_Lock</emphasis></entry> + <entry><symbol>XkbKB_Lock</symbol></entry> <entry> If a key is logically up (that is, the corresponding bit of the core key map is cleared) when it is pressed, the key press is processed normally and the corresponding release is ignored. If the key is logically down when pressed, the key press is ignored but the corresponding release is processed normally. -The <emphasis> -data</emphasis> - field is unused. +The +<structfield>data</structfield> +field is unused. </entry> </row> <row> - <entry><emphasis>XkbKB_RadioGroup</emphasis></entry> + <entry><symbol>XkbKB_RadioGroup</symbol></entry> <entry> <para> If another member of the radio group is logically down (all members of the -radio group have the same index, specified in <emphasis> -data</emphasis> -) when a key is pressed, the server synthesizes a key release for the member +radio group have the same index, specified in +<structfield>data</structfield>) +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> -Xkb_RGAllowNone</emphasis> - bit in <emphasis> -flags</emphasis> -. If it is set, the key release is processed normally; otherwise, the key +value of the +<symbol>XkbKB_RGAllowNone</symbol> +bit in +<structfield>flags</structfield>. +If it is set, the key release is processed normally; otherwise, the key release is also ignored. </para> <para> @@ -4125,29 +4143,29 @@ All other key release events are ignored. </entry> </row> <row> - <entry><emphasis>XkbKB_Overlay1</emphasis></entry> + <entry><symbol>XkbKB_Overlay1</symbol></entry> <entry> -If the <emphasis> -Overlay1</emphasis> - control is enabled (see section 10.4), <emphasis> -data</emphasis> - is interpreted as a keycode, and events from this key are reported as if they -came from <emphasis> -data</emphasis> -’s keycode. Otherwise, press and release events are processed normally. +If the +<emphasis>Overlay1</emphasis> +control is enabled (see <link linkend="Controls_for_Keyboard_Overlays_Overlay1_and_Overlay2_Controls">section 10.4</link>), +<structfield>data</structfield> +is interpreted as a keycode, and events from this key are reported as if they +came from +<structfield>data</structfield>’s +keycode. Otherwise, press and release events are processed normally. </entry> </row> <row> - <entry><emphasis>XkbKB_Overlay2</emphasis></entry> + <entry><symbol>XkbKB_Overlay2</symbol></entry> <entry> -If the <emphasis> -Overlay2</emphasis> - control is enabled (see section 10.4), <emphasis> -data</emphasis> - is interpreted as a keycode, and events from this key are reported as if they -came from <emphasis> -data</emphasis> -’s keycode. Otherwise, press and release events are processed normally. +If the +<emphasis>Overlay2</emphasis> +control is enabled (see <link linkend="Controls_for_Keyboard_Overlays_Overlay1_and_Overlay2_Controls">section 10.4</link>), +<structfield>data</structfield> +is interpreted as a keycode, and events from this key are reported as if they +came from +<structfield>data</structfield>’s +keycode. Otherwise, press and release events are processed normally. </entry> </row> </tbody> @@ -4155,15 +4173,15 @@ data</emphasis> </table> <para> -Xkb also provides the mask, <emphasis> -XkbKB_Permanent</emphasis> - to specify whether the key behavior type should be simulated by Xkb or whether +Xkb also provides the mask, +<symbol>XkbKB_Permanent</symbol> +to specify whether the key behavior type should be simulated by Xkb or whether the key behavior describes an unalterable physical, electrical, or software -aspect of the keyboard. If the <emphasis> -XkbKB_Permanent</emphasis> - bit is not set in the <emphasis> -type</emphasis> - field, Xkb simulates the behavior in software. Otherwise, Xkb relies upon the +aspect of the keyboard. If the +<symbol>XkbKB_Permanent</symbol> +bit is not set in the +<structfield>type</structfield> +field, Xkb simulates the behavior in software. Otherwise, Xkb relies upon the keyboard to implement the behavior. </para> @@ -4173,117 +4191,118 @@ keyboard to implement the behavior. <title>Obtaining Key Behaviors for Keys from the Server</title> <para> -To obtain the behaviors (the <emphasis> -behaviors</emphasis> - array) for a subset of the keys in a keyboard description from the server, use -<emphasis> -XkbGetKeyBehaviors</emphasis> -: -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetKeyBehaviors</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - num</emphasis> -,<emphasis> - xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -first</emphasis> -; /* keycode of first key to get */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -num</emphasis> -; /* number of keys for which behaviors are desired */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description to contain the result */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +To obtain the behaviors (the +<structfield>behaviors</structfield> +array) for a subset of the keys in a keyboard description from the server, use +<function>XkbGetKeyBehaviors</function>: + +</para> + +<indexterm significance="preferred" zone="XkbGetKeyBehaviors"><primary><function>XkbGetKeyBehaviors</function></primary></indexterm> +<funcsynopsis id="XkbGetKeyBehaviors"> + <funcprototype> + <funcdef>Status <function>XkbGetKeyBehaviors</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>first</parameter>, +<parameter>num</parameter>, +<parameter>xkb</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>first</parameter></paramdef> + <paramdef>unsigned int <parameter>num</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + keycode of first key to get + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num</parameter> + </term> + <listitem> + <para> + number of keys for which behaviors are desired + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description to contain the result + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbGetKeyBehaviors</emphasis> - sends a request to the server to obtain the behaviors for <emphasis> -num</emphasis> - keys on the keyboard starting with the key whose keycode is <emphasis> -first</emphasis> -. It waits for a reply and returns the behaviors in the <emphasis> -server</emphasis> --><emphasis> -behaviors</emphasis> - field of <emphasis> -xkb</emphasis> -. If successful, <emphasis> -XkbGetKeyBehaviors</emphasis> - returns <emphasis> -Success</emphasis> -. +<function>XkbGetKeyBehaviors</function> +sends a request to the server to obtain the behaviors for +<parameter>num</parameter> +keys on the keyboard starting with the key whose keycode is +<parameter>first</parameter>. +It waits for a reply and returns the behaviors in the +<structfield>server</structfield>-><structfield>behaviors</structfield> +field of +<parameter>xkb</parameter>. +If successful, +<function>XkbGetKeyBehaviors</function> +returns +<symbol>Success</symbol>. </para> <para> -If the <emphasis> -server</emphasis> - map in the <emphasis> -xkb</emphasis> - parameter has not been allocated, <emphasis> -XkbGetKeyBehaviors</emphasis> - allocates and initializes it before obtaining the actions. +If the +<structfield>server</structfield> +map in the +<parameter>xkb</parameter> +parameter has not been allocated, +<function>XkbGetKeyBehaviors</function> +allocates and initializes it before obtaining the actions. </para> <para> If the server does not have a compatible version of Xkb, or the Xkb extension -has not been properly initialized, <emphasis> -XkbGetKeyBehaviors</emphasis> - returns <emphasis> -BadAccess</emphasis> -. If <emphasis> -num</emphasis> - is less than 1 or greater than <emphasis> -XkbMaxKeyCount</emphasis> -, <emphasis> -XkbGetKeyBehaviors</emphasis> - returns <emphasis> -BadValue</emphasis> -. If any allocation errors occur, <emphasis> -XkbGetKeyBehaviors</emphasis> - returns <emphasis> -BadAlloc</emphasis> -. +has not been properly initialized, +<function>XkbGetKeyBehaviors</function> +returns +<errorname>BadAccess</errorname>. +If +<parameter>num</parameter> +is less than 1 or greater than +<symbol>XkbMaxKeyCount</symbol>, +<function>XkbGetKeyBehaviors</function> +returns +<errorname>BadValue</errorname>. +If any allocation errors occur, +<function>XkbGetKeyBehaviors</function> +returns +<errorname>BadAlloc</errorname>. </para> @@ -4295,7 +4314,7 @@ BadAlloc</emphasis> <para> Whenever a client remaps the keyboard using core protocol requests, Xkb examines the map to determine likely default values for the components that -cannot be specified using the core protocol (see section 17.1.2 for more +cannot be specified using the core protocol (see <link linkend="Core_Keyboard_Mapping_to_Xkb_Keyboard_Mapping_Transformation">section 17.1.2</link> for more information on how Xkb chooses the default values). </para> @@ -4310,14 +4329,14 @@ mapping. <para> -The explicit components masks are held in the <emphasis> -explicit</emphasis> - field of the server map, which is an array indexed by keycode. Each entry in +The explicit components masks are held in the +<structfield>explicit</structfield> +field of the server map, which is an array indexed by keycode. Each entry in this array is a mask that is a bitwise inclusive OR of the values shown in -Table 16.21. +<link linkend="table16.21">Table 16.21</link>. </para> -<table frame='topbot'> +<table id='table16.21' frame='topbot'> <title>Explicit Component Masks</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -4336,32 +4355,32 @@ Table 16.21. <entry><emphasis>ExplicitKeyType1</emphasis></entry> <entry>(1<<0)</entry> <entry> -Automatic determination of the key type associated with <emphasis> -Group1.</emphasis> +Automatic determination of the key type associated with +<emphasis>Group1</emphasis>. </entry> </row> <row> <entry><emphasis>ExplicitKeyType2</emphasis></entry> <entry>(1<<1)</entry> <entry> -Automatic determination of the key type associated with <emphasis> -Group2.</emphasis> +Automatic determination of the key type associated with +<emphasis>Group2</emphasis>. </entry> </row> <row> <entry><emphasis>ExplicitKeyType3</emphasis></entry> <entry>(1<<2)</entry> <entry> -Automatic determination of the key type associated with <emphasis> -Group3.</emphasis> +Automatic determination of the key type associated with +<emphasis>Group3</emphasis>. </entry> </row> <row> <entry><emphasis>ExplicitKeyType4</emphasis></entry> <entry>(1<<3)</entry> <entry> -Automatic determination of the key type associated with <emphasis> -Group4.</emphasis> +Automatic determination of the key type associated with +<emphasis>Group4</emphasis>. </entry> </row> <row> @@ -4382,11 +4401,11 @@ specified in a symbol interpretation.</entry> <entry><emphasis>ExplicitBehavior</emphasis></entry> <entry>(1<<6)</entry> <entry> -Automatic assignment of the <emphasis> -XkbKB_Lock</emphasis> - behavior to the key, if the <emphasis> -XkbSI_LockingKey</emphasis> - flag is set in a symbol interpretation. +Automatic assignment of the +<symbol>XkbKB_Lock</symbol> +behavior to the key, if the +<symbol>XkbSI_LockingKey</symbol> +flag is set in a symbol interpretation. </entry> </row> <row> @@ -4406,117 +4425,120 @@ match the key. <title>Obtaining Explicit Components for Keys from the Server</title> <para> -To obtain the explicit components (the <emphasis> -explicit</emphasis> - array) for a subset of the keys in a keyboard description, use <emphasis> -XkbGetKeyExplicitComponents</emphasis>. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetKeyExplicitComponents</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - num</emphasis> -,<emphasis> - xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -first</emphasis> -; /* keycode of first key to fetch */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -num</emphasis> -; /* number of keys for which to get explicit info */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description in which to put results */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +To obtain the explicit components (the +<structfield>explicit</structfield> +array) for a subset of the keys in a keyboard description, use +<function>XkbGetKeyExplicitComponents</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetKeyExplicitComponents"><primary><function>XkbGetKeyExplicitComponents</function></primary></indexterm> +<funcsynopsis id="XkbGetKeyExplicitComponents"> + <funcprototype> + <funcdef>Status <function>XkbGetKeyExplicitComponents</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>first</parameter>, +<parameter>num</parameter>, +<parameter>xkb</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>first</parameter></paramdef> + <paramdef>unsigned int <parameter>num</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + keycode of first key to fetch + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num</parameter> + </term> + <listitem> + <para> + number of keys for which to get explicit info + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description in which to put results + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbGetKeyExplicitComponents</emphasis> - sends a request to the server to obtain the explicit components for <emphasis> -num</emphasis> - keys on the keyboard starting with key <emphasis> -first</emphasis> -. It waits for a reply and returns the explicit components in the <emphasis> -server</emphasis> --><emphasis> -explicit</emphasis> - array of <emphasis> -xkb</emphasis> -. If successful, <emphasis> -XkbGetKeyExplicitComponents</emphasis> - returns <emphasis> -Success</emphasis> -. The <emphasis> -xkb</emphasis> - parameter must be a pointer to a valid Xkb keyboard description. +<function>XkbGetKeyExplicitComponents</function> +sends a request to the server to obtain the explicit components for +<parameter>num</parameter> +keys on the keyboard starting with key +<parameter>first</parameter>. +It waits for a reply and returns the explicit components in the +<structfield>server</structfield>-><structfield>explicit</structfield> +array of +<parameter>xkb</parameter>. +If successful, +<function>XkbGetKeyExplicitComponents</function> +returns +<symbol>Success</symbol>. +The +<parameter>xkb</parameter> +parameter must be a pointer to a valid Xkb keyboard description. </para> <para> -If the <emphasis> -server</emphasis> - map in the <emphasis> -xkb</emphasis> - parameter has not been allocated, <emphasis> -XkbGetKeyExplicitComponents</emphasis> - allocates and initializes it before obtaining the actions. +If the +<structfield>server</structfield> +map in the +<parameter>xkb</parameter> +parameter has not been allocated, +<function>XkbGetKeyExplicitComponents</function> +allocates and initializes it before obtaining the actions. </para> <para> If the server does not have a compatible version of Xkb, or the Xkb extension -has not been properly initialized, <emphasis> -XkbGetKeyExplicitComponents</emphasis> - returns <emphasis> -BadMatch</emphasis> -. If <emphasis> -num</emphasis> - is less than 1 or greater than <emphasis> -XkbMaxKeyCount</emphasis> -, <emphasis> -XkbGetKeyExplicitComponents</emphasis> - returns <emphasis> -BadValue</emphasis> -. If any allocation errors occur, <emphasis> -XkbGetKeyExplicitComponents</emphasis> - returns <emphasis> -BadAlloc</emphasis> -. +has not been properly initialized, +<function>XkbGetKeyExplicitComponents</function> +returns +<errorname>BadMatch</errorname>. +If +<parameter>num</parameter> +is less than 1 or greater than +<symbol>XkbMaxKeyCount</symbol>, +<function>XkbGetKeyExplicitComponents</function> +returns +<errorname>BadValue</errorname>. +If any allocation errors occur, +<function>XkbGetKeyExplicitComponents</function> +returns +<errorname>BadAlloc</errorname>. </para> @@ -4526,71 +4548,71 @@ BadAlloc</emphasis> <title>Virtual Modifier Mapping</title> <para> -The <emphasis> -vmods</emphasis> - member of the server map is a fixed-length array containing <emphasis> -XkbNumVirtualMods</emphasis> - entries. Each entry corresponds to a virtual modifier and provides the binding -of the virtual modifier to the real modifier bits. Each entry in the <emphasis> -vmods</emphasis> - array is a bitwise inclusive OR of the legal modifier masks: -</para> - -<literallayout> - <emphasis>ShiftMask</emphasis> - <emphasis>LockMask</emphasis> - <emphasis>ControlMask</emphasis> - <emphasis>Mod1Mask</emphasis> - <emphasis>Mod2Mask</emphasis> - <emphasis>Mod3Mask</emphasis> - <emphasis>Mod4Mask</emphasis> - <emphasis>Mod5Mask</emphasis> -</literallayout> - -<para> -The <emphasis> -vmodmap</emphasis> - member of the server map is similar to the <emphasis> -modmap</emphasis> - array of the client map (see section 15.4), but is used to define the virtual -modifier mapping for each key. Like the <emphasis> -modmap</emphasis> - member, it is indexed by keycode, and each entry is a mask representing the +The +<structfield>vmods</structfield> +member of the server map is a fixed-length array containing +<symbol>XkbNumVirtualMods</symbol> +entries. Each entry corresponds to a virtual modifier and provides the binding +of the virtual modifier to the real modifier bits. Each entry in the +<structfield>vmods</structfield> +array is a bitwise inclusive OR of the legal modifier masks: +</para> + +<simplelist type='vert' columns='1'> + <member><symbol>ShiftMask</symbol></member> + <member><symbol>LockMask</symbol></member> + <member><symbol>ControlMask</symbol></member> + <member><symbol>Mod1Mask</symbol></member> + <member><symbol>Mod2Mask</symbol></member> + <member><symbol>Mod3Mask</symbol></member> + <member><symbol>Mod4Mask</symbol></member> + <member><symbol>Mod5Mask</symbol></member> +</simplelist> + +<para> +The +<structfield>vmodmap</structfield> +member of the server map is similar to the +<structfield>modmap</structfield> +array of the client map (see <link linkend="The_Per_Key_Modifier_Map">section 15.4</link>), but is used to define the virtual +modifier mapping for each key. Like the +<structfield>modmap</structfield> +member, it is indexed by keycode, and each entry is a mask representing the virtual modifiers bound to the corresponding key: </para> <itemizedlist> <listitem> <para> -Each of the bits in a <emphasis> -vmodmap</emphasis> - entry represents an index into the <emphasis> -vmods</emphasis> - member. That is, bit 0 of a <emphasis> -vmodmap</emphasis> - entry refers to index 0 of the <emphasis> -vmods</emphasis> - array, bit 1 refers to index 1, and so on. +Each of the bits in a +<structfield>vmodmap</structfield> +entry represents an index into the +<structfield>vmods</structfield> +member. That is, bit 0 of a +<structfield>vmodmap</structfield> +entry refers to index 0 of the +<structfield>vmods</structfield> +array, bit 1 refers to index 1, and so on. </para> </listitem> <listitem> <para> -If a bit is set in the <emphasis> -vmodmap</emphasis> - entry for a key, that key is bound to the corresponding virtual modifier in -the <emphasis> -vmods</emphasis> - array. +If a bit is set in the +<structfield>vmodmap</structfield> +entry for a key, that key is bound to the corresponding virtual modifier in +the +<structfield>vmods</structfield> +array. </para> </listitem> </itemizedlist> <para> -The <emphasis> -vmodmap</emphasis> - and <emphasis> -vmods</emphasis> - members of the server map are the "master" virtual modifier definitions. Xkb +The +<structfield>vmodmap</structfield> +and +<structfield>vmods</structfield> +members of the server map are the <quote>master</quote> virtual modifier definitions. Xkb automatically propagates any changes to these fields to all other fields that use virtual modifier mappings. </para> @@ -4598,14 +4620,16 @@ use virtual modifier mappings. <para> The overall relationship of fields dealing with virtual modifiers in an Xkb -keyboard description are shown in Figure 16.2. +keyboard description are shown in <link linkend="figure16.2">Figure 16.2</link>. </para> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-17.svg"/> - </imageobject> -<caption>Virtual Modifier Relationships</caption> -</mediaobject> +<figure id='figure16.2'> + <title>Virtual Modifier Relationships</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-17.svg"/> + </imageobject> + </mediaobject> +</figure> @@ -4618,104 +4642,106 @@ Virtual Modifier Relationships</H5> <title>Obtaining Virtual Modifier Bindings from the Server</title> <para> -To obtain a subset of the virtual modifier bindings (the <emphasis> -vmods</emphasis> - array) in a keyboard description, use <emphasis> -XkbGetVirtualMods</emphasis> -: -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetVirtualMods</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - which</emphasis> -,<emphasis> - xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -which</emphasis> -; /* mask indicating virtual modifier bindings to get */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description where results will be placed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +To obtain a subset of the virtual modifier bindings (the +<structfield>vmods</structfield> +array) in a keyboard description, use +<function>XkbGetVirtualMods</function>: + +</para> + +<indexterm significance="preferred" zone="XkbGetVirtualMods"><primary><function>XkbGetVirtualMods</function></primary></indexterm> +<funcsynopsis id="XkbGetVirtualMods"> + <funcprototype> + <funcdef>Status <function>XkbGetVirtualMods</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>which</parameter>, +<parameter>xkb</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask indicating virtual modifier bindings to get + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description where results will be placed + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbGetVirtualMods</emphasis> - sends a request to the server to obtain the <emphasis> -vmods</emphasis> - entries for the virtual modifiers specified in the mask, <emphasis> -which</emphasis> -, and waits for a reply. See section 7.1 for a description of how to determine -the virtual modifier mask. For each bit set in <emphasis> -which</emphasis> -, <emphasis> -XkbGetVirtualMods</emphasis> - updates the corresponding virtual modifier definition in the <emphasis> -server->vmods</emphasis> - array of <emphasis> -xkb</emphasis> -. The <emphasis> -xkb</emphasis> - parameter must be a pointer to a valid Xkb keyboard description. If -successful, <emphasis> -XkbGetVirtualMods</emphasis> - returns <emphasis> -Success</emphasis> -. +<function>XkbGetVirtualMods</function> +sends a request to the server to obtain the +<structfield>vmods</structfield> +entries for the virtual modifiers specified in the mask, +<parameter>which</parameter>, +and waits for a reply. See <link linkend="Virtual_Modifier_Names_and_Masks">section 7.1</link> for a description of how to determine +the virtual modifier mask. For each bit set in +<parameter>which</parameter>, +<function>XkbGetVirtualMods</function> +updates the corresponding virtual modifier definition in the +<structfield>server->vmods</structfield> +array of +<parameter>xkb</parameter>. +The +<parameter>xkb</parameter> +parameter must be a pointer to a valid Xkb keyboard description. If +successful, +<function>XkbGetVirtualMods</function> +returns +<symbol>Success</symbol>. </para> <para> -If the <emphasis> -server</emphasis> - map has not been allocated in the <emphasis> -xkb</emphasis> - parameter, <emphasis> -XkbGetVirtualMods</emphasis> - allocates and initializes it before obtaining the virtual modifier bindings. +If the +<structfield>server</structfield> +map has not been allocated in the +<parameter>xkb</parameter> +parameter, +<function>XkbGetVirtualMods</function> +allocates and initializes it before obtaining the virtual modifier bindings. </para> <para> If the server does not have a compatible version of Xkb, or the Xkb extension -has not been properly initialized, <emphasis> -XkbGetVirtualMods</emphasis> - returns <emphasis> -BadMatch</emphasis> -. Any errors in allocation cause <emphasis> -XkbGetVirtualMods </emphasis> -to return <emphasis> -BadAlloc</emphasis>. +has not been properly initialized, +<function>XkbGetVirtualMods</function> +returns +<errorname>BadMatch</errorname>. +Any errors in allocation cause +<function>XkbGetVirtualMods</function> +to return +<errorname>BadAlloc</errorname>. </para> @@ -4724,120 +4750,121 @@ BadAlloc</emphasis>. <title>Obtaining Per-Key Virtual Modifier Mappings from the Server</title> <para> -To obtain the virtual modifier map (the <emphasis> -vmodmap</emphasis> - array) for a subset of the keys in a keyboard description, use <emphasis> -XkbGetKeyVirtualModMap</emphasis> -: -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetKeyVirtualModMap</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - first</emphasis> -,<emphasis> - num</emphasis> -,<emphasis> - xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -first</emphasis> -; /* keycode of first key to fetch */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -num</emphasis> -; /* # keys for which virtual mod maps are desired */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* Xkb description where results will be placed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +To obtain the virtual modifier map (the +<structfield>vmodmap</structfield> +array) for a subset of the keys in a keyboard description, use +<function>XkbGetKeyVirtualModMap</function>: + +</para> + +<indexterm significance="preferred" zone="XkbGetKeyVirtualModMap"><primary><function>XkbGetKeyVirtualModMap</function></primary></indexterm> +<funcsynopsis id="XkbGetKeyVirtualModMap"> + <funcprototype> + <funcdef>Status <function>XkbGetKeyVirtualModMap</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>first</parameter>, +<parameter>num</parameter>, +<parameter>xkb</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>first</parameter></paramdef> + <paramdef>unsigned int <parameter>num</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first</parameter> + </term> + <listitem> + <para> + keycode of first key to fetch + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num</parameter> + </term> + <listitem> + <para> + # keys for which virtual mod maps are desired + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description where results will be placed + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbGetKeyVirutalModmap </emphasis> +<function>XkbGetKeyVirtualModmap</function> sends a request to the server to obtain the virtual modifier mappings for -<emphasis> -num</emphasis> - keys on the keyboard starting with key <emphasis> -first</emphasis> -. It waits for a reply and returns the virtual modifier mappings in the -<emphasis> -server</emphasis> --><emphasis> -vmodmap</emphasis> - array of <emphasis> -xkb</emphasis> -. If successful, <emphasis> -XkbGetKeyVirtualModMap</emphasis> - returns <emphasis> -Success</emphasis> -. The <emphasis> -xkb</emphasis> - parameter must be a pointer to a valid Xkb keyboard description +<parameter>num</parameter> +keys on the keyboard starting with key +<parameter>first</parameter>. +It waits for a reply and returns the virtual modifier mappings in the +<structfield>server</structfield>-><structfield>vmodmap</structfield> +array of +<parameter>xkb</parameter>. +If successful, +<function>XkbGetKeyVirtualModMap</function> +returns +<symbol>Success</symbol>. +The +<parameter>xkb</parameter> +parameter must be a pointer to a valid Xkb keyboard description </para> <para> -If the <emphasis> -server</emphasis> - map in the <emphasis> -xkb</emphasis> - parameter has not been allocated, <emphasis> -XkbGetKeyVirtualModMap</emphasis> - allocates and initializes it before obtaining the virtual modifier mappings. +If the +<structfield>server</structfield> +map in the +<parameter>xkb</parameter> +parameter has not been allocated, +<function>XkbGetKeyVirtualModMap</function> +allocates and initializes it before obtaining the virtual modifier mappings. </para> <para> If the server does not have a compatible version of Xkb, or the Xkb extension -has not been properly initialized, <emphasis> -XkbGetKeyVirtualModMap</emphasis> - returns <emphasis> -BadMatch</emphasis> -. If <emphasis> -num</emphasis> - is less than 1 or greater than <emphasis> -XkbMaxKeyCount</emphasis> -, <emphasis> -XkbGetKeyVirtualModMap</emphasis> - returns <emphasis> -BadValue</emphasis> -. If any allocation errors occur, <emphasis> -XkbGetKeyVirtualModMap</emphasis> - returns <emphasis> -BadAlloc</emphasis> -. +has not been properly initialized, +<function>XkbGetKeyVirtualModMap</function> +returns +<errorname>BadMatch</errorname>. +If +<parameter>num</parameter> +is less than 1 or greater than +<symbol>XkbMaxKeyCount</symbol>, +<function>XkbGetKeyVirtualModMap</function> +returns +<errorname>BadValue</errorname>. +If any allocation errors occur, +<function>XkbGetKeyVirtualModMap</function> +returns +<errorname>BadAlloc</errorname>. </para> </sect2> diff --git a/libX11/specs/XKB/ch17.xml b/libX11/specs/XKB/ch17.xml index 32a1c8cb6..dcc2b214f 100644 --- a/libX11/specs/XKB/ch17.xml +++ b/libX11/specs/XKB/ch17.xml @@ -1,8 +1,11 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='The_Xkb_Compatibility_Map'> <title>The Xkb Compatibility Map</title> <para> -As shown in Figure 17.1, the X server is normally dealing with more than one +As shown in <link linkend="figure17.1">Figure 17.1</link>, the X server is normally dealing with more than one client, each of which may be receiving events from the keyboard, and each of which may issue requests to modify the keyboard in some manner. Each client may be either Xkb-unaware, Xkb-capable, or Xkb-aware. The server itself may be @@ -15,11 +18,13 @@ Consequently, for some situations, conversions must be made between Xkb state / keyboard mappings and core protocol state / keyboard mappings, and vice versa. </para> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-18.svg"/> - </imageobject> - <caption>Server Interaction with Types of Clients</caption> -</mediaobject> +<figure id='figure17.1'> + <title>Server Interaction with Types of Clients</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-18.svg"/> + </imageobject> + </mediaobject> +</figure> @@ -39,28 +44,30 @@ state and an Xkb keyboard mapping plus a compatibility map used to convert from Xkb components to core components and vice versa. In addition, the server also maintains a core keyboard mapping that approximates the Xkb keyboard mapping. The core keyboard mapping may be updated piecemeal, on a per-key basis. When -the server receives a core protocol <emphasis> -ChangeKeyboardMapping</emphasis> - or <emphasis> -SetModifierMapping</emphasis> - request, it updates its core keyboard mapping, then uses the compatibility map -to update its Xkb keyboard mapping. When the server receives an <emphasis> -XkbSetMap</emphasis> - request, it updates those portions of its Xkb keyboard mapping specified by +the server receives a core protocol +<systemitem>ChangeKeyboardMapping</systemitem> +or +<systemitem>SetModifierMapping</systemitem> +request, it updates its core keyboard mapping, then uses the compatibility map +to update its Xkb keyboard mapping. When the server receives an +<function>XkbSetMap</function> +request, it updates those portions of its Xkb keyboard mapping specified by the request, then uses its compatibility map to update the corresponding parts of its core keyboard map. Consequently, the server’s Xkb keyboard map and also its core keyboard map may contain components that were set directly and -others that were computed. Figure 17.2 illustrates these relationships. +others that were computed. <link linkend="figure17.2">Figure 17.2</link> illustrates these relationships. </para> <note><para>The core keyboard map is contained only in the server, not in any client-side data structures.</para></note> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-19.svg"/> - </imageobject> - <caption>Server Derivation of State and Keyboard Mapping Components</caption> -</mediaobject> +<figure id='figure17.2'> + <title>Server Derivation of State and Keyboard Mapping Components</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-19.svg"/> + </imageobject> + </mediaobject> +</figure> @@ -78,15 +85,14 @@ server, which includes a group number, to core protocol state, which does not. </para> <para> -In addition, whenever the Xkb state is retrieved, the <emphasis> -compat_state</emphasis> -, <emphasis> -compat_grab_mods</emphasis> -, and <emphasis> -compat_lookup_mods</emphasis> - fields of the <emphasis> -XkbStateRec</emphasis> - returned indicate the result of applying the compatibility map to the current +In addition, whenever the Xkb state is retrieved, the +<structfield>compat_state</structfield>, +<structfield>compat_grab_mods</structfield>, +and +<structfield>compat_lookup_mods</structfield> +fields of the +<structname>XkbStateRec</structname> +returned indicate the result of applying the compatibility map to the current Xkb state in the server. </para> </listitem> @@ -94,11 +100,11 @@ Xkb state in the server. <para><emphasis role='bold'>Core Keyboard Mapping to Xkb Keyboard Mapping</emphasis></para> <para> After core protocol requests received by the server to change the keyboard -mapping (<emphasis> -ChangeKeyboardMapping</emphasis> - and <emphasis> -SetModifierMapping</emphasis> -) have been applied to the server’s core keyboard map, the results must be +mapping +(<systemitem>ChangeKeyboardMapping</systemitem> +and +<systemitem>SetModifierMapping</systemitem>) +have been applied to the server’s core keyboard map, the results must be transformed to achieve an equivalent change of the Xkb keyboard mapping maintained by the server. </para> @@ -107,9 +113,9 @@ maintained by the server. <para><emphasis role='bold'>Xkb Keyboard Mapping to Core Keyboard Mapping</emphasis></para> <para> After Xkb protocol requests received by the server to change the keyboard -mapping (<emphasis> -XkbSetMap</emphasis> -) have been applied to the server’s Xkb keyboard map, the results are +mapping +(<function>XkbSetMap</function>) +have been applied to the server’s Xkb keyboard map, the results are transformed to achieve an approximately equivalent change to the core keyboard mapping maintained by the server. </para> @@ -124,45 +130,48 @@ subsequent transformations have a particular result. <sect1 id='The_XkbCompatMap_Structure'> <title>The XkbCompatMap Structure</title> +<indexterm significance="preferred" zone="The_XkbCompatMap_Structure"> +<primary><structname>XkbCompatMapRec</structname></primary></indexterm> <para> All configurable aspects of mapping Xkb state and configuration to and from core protocol state and configuration are defined by a compatibility map, -contained in an <emphasis> -XkbCompatMap</emphasis> - structure; plus a set of explicit override controls used to prevent particular +contained in an +<structname>XkbCompatMapRec</structname> +structure; plus a set of explicit override controls used to prevent particular components of type 2 (core-to-Xkb keyboard mapping) transformations from automatically occurring. These explicit override controls are maintained in a -separate data structure discussed in section 16.3. <!-- xref --> +separate data structure discussed in <link linkend="Explicit_ComponentsAvoiding_Automatic_Remapping_by_the_Server">section 16.3</link>. </para> <para> -The <emphasis> -compat</emphasis> - member of an Xkb keyboard description (<emphasis> -XkbDescRec</emphasis> -) points to the<emphasis> - XkbCompatMap</emphasis> - structure: -</para> +The +<structfield>compat</structfield> +member of an Xkb keyboard description +(<structname>XkbDescRec</structname>) +points to the +<structname>XkbCompatMapRec</structname> +structure: -<para><programlisting> +<programlisting> typedef struct _XkbCompatMapRec { - XkbSymInterpretPtr sym_interpret; /* symbol based key semantics*/ - XkbModsRec groups[XkbNumKbdGroups]; /* group => modifier map */ - unsigned short num_si; /* # structures used in - <emphasis>sym_interpret</emphasis> */ - unsigned short size_si; /* # structures allocated in - <emphasis>sym_interpret</emphasis> */ -} <emphasis>XkbCompatMapRec</emphasis>, *XkbCompatMapPtr; + XkbSymInterpretPtr sym_interpret; /* symbol based key semantics */ + XkbModsRec groups[XkbNumKbdGroups]; /* group ⇒ modifier map */ + unsigned short num_si; /* # structures used in + <structfield>sym_interpret</structfield> */ + unsigned short size_si; /* # structures allocated in + <structfield>sym_interpret</structfield> */ +} <structname>XkbCompatMapRec</structname>, *XkbCompatMapPtr; </programlisting></para> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-20.svg"/> - </imageobject> - <caption>Xkb Compatibility Data Structures</caption> -</mediaobject> +<figure id='figure17.3'> + <title>Xkb Compatibility Data Structures</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-20.svg"/> + </imageobject> + </mediaobject> +</figure> <para> @@ -175,34 +184,38 @@ transformations are made. <title>Xkb State to Core Protocol State Transformation</title> <para> -As shown in Figure 17.3, there are four <emphasis> -group compatibility maps</emphasis> - (contained in <emphasis> -groups</emphasis> - [0..3]) in the <emphasis> -XkbCompatMapRec</emphasis> - structure, one per possible Xkb group. Each group compatibility map is a -modifier definition (see section 7.2 for a description of modifier -definitions). The <emphasis> -mask</emphasis> - component of the definition specifies which real modifiers should be set in +As shown in <link linkend="figure17.3">Figure 17.3</link>, there are four +<firstterm>group compatibility maps</firstterm> +<indexterm significance="preferred" zone="Xkb_State_to_Core_Protocol_State_Transformation"> +<primary>group compatibility map</primary></indexterm> +<indexterm significance="preferred" zone="Xkb_State_to_Core_Protocol_State_Transformation"> +<primary>map</primary><secondary>group compatibility</secondary></indexterm> +(contained in +<structfield>groups</structfield> +[0..3]) in the +<structname>XkbCompatMapRec</structname> +structure, one per possible Xkb group. Each group compatibility map is a +modifier definition (see <link linkend="Modifier_Definitions">section 7.2</link> for a description of modifier +definitions). The +<structfield>mask</structfield> +component of the definition specifies which real modifiers should be set in the core protocol state field when the corresponding group is active. Because only one group is active at any one time, only one of the four possible transformations is ever applied at any one point in time. If the device -described by the <emphasis> -XkbDescRec</emphasis> - does not support four groups, the extra groups fields are present, but +described by the +<structname>XkbDescRec</structname> +does not support four groups, the extra groups fields are present, but undefined. </para> <para> -Normally, the Xkb-aware server reports keyboard state in the <emphasis> -state</emphasis> - member of events such as a <emphasis> -KeyPress</emphasis> - event and <emphasis> -ButtonPress</emphasis> - event, encoded as follows: +Normally, the Xkb-aware server reports keyboard state in the +<structfield>state</structfield> +member of events such as a +<symbol>KeyPress</symbol> +event and +<symbol>ButtonPress</symbol> +event, encoded as follows: </para> <informaltable frame='topbot'> @@ -222,15 +235,15 @@ ButtonPress</emphasis> <entry>0</entry> </row> <row> - <entry>13-14</entry> + <entry>13–14</entry> <entry>Group index</entry> </row> <row> - <entry>8-12</entry> + <entry>8–12</entry> <entry>Pointer Buttons</entry> </row> <row> - <entry>0-7</entry> + <entry>0–7</entry> <entry>Modifiers</entry> </row> </tbody> @@ -240,10 +253,10 @@ ButtonPress</emphasis> <para> For Xkb-unaware clients, only core protocol keyboard information may be reported. Because core protocol does not define the group index, the group -index is mapped to modifier bits as specified by the <emphasis> -groups</emphasis> +index is mapped to modifier bits as specified by the +<structfield>groups</structfield> [group index] field of the compatibility map (the bits set in the compatibility -map are ORed into bits 0-7 of the state), and bits 13-14 are reported in the +map are ORed into bits 0–7 of the state), and bits 13–14 are reported in the event as zero. </para> @@ -259,7 +272,7 @@ Xkb keyboard mapping in the server, this automatic regeneration of the Xkb keyboard mapping from the core protocol keyboard mapping should not modify any components of the Xkb keyboard mapping that were explicitly set by a client. The client must set explicit override controls to prevent this from happening -(see section 16.3). The core-to-Xkb mapping is done as follows: +(see <link linkend="Explicit_ComponentsAvoiding_Automatic_Remapping_by_the_Server">section 16.3</link>). The core-to-Xkb mapping is done as follows: </para> <orderedlist> @@ -291,11 +304,11 @@ Xkb map. <para> For each changed key, determine the number of symbols in each of the groups found in step 1a. There is one explicit override control associated with each -of the four possible groups for each Xkb key, <emphasis> -ExplicitKeyType1</emphasis> - through <emphasis> -ExplicitKeyType4</emphasis> -. If no explicit override control is set for a group, the number of symbols +of the four possible groups for each Xkb key, +<emphasis>ExplicitKeyType1</emphasis> +through +<emphasis>ExplicitKeyType4</emphasis>. +If no explicit override control is set for a group, the number of symbols used for that group from the core map is two. If the explicit override control is set for a group on the key, the number of symbols used for that Xkb group from the core map is the width of the Xkb group with one exception: because of @@ -309,9 +322,9 @@ or the width of the Xkb group. For each changed key, assign the symbols in the core map to the appropriate group on the key. If the total number of symbols required by the Xkb map for a particular key needs more symbols than the core protocol map contains, the -additional symbols are taken to be <emphasis> -NoSymbol</emphasis> - keysyms appended to the end of the core set. If the core map contains more +additional symbols are taken to be +<symbol>NoSymbol</symbol> +keysyms appended to the end of the core set. If the core map contains more symbols than are needed by the Xkb map, trailing symbols in the core map are discarded. In the absence of an explicit override for group one or two, symbols are assigned in order by group; the first symbols in the core map are assigned @@ -365,10 +378,10 @@ the corresponding key definitions in the Xkb map. <listitem> <para> Apply symbol interpretations to modify key operation. This phase is completely -skipped if the <emphasis> -ExplicitInterpret</emphasis> - override control bit is set in the explicit controls mask for the Xkb key (see -section 16.3). +skipped if the +<emphasis>ExplicitInterpret</emphasis> +override control bit is set in the explicit controls mask for the Xkb key (see +<link linkend="Explicit_ComponentsAvoiding_Automatic_Remapping_by_the_Server">section 16.3</link>). </para> <orderedlist> <listitem> @@ -391,24 +404,26 @@ apply a default interpretation. <para> The symbol interpretations used in step 2 are configurable and may be specified -using <emphasis> -XkbSymInterpretRec</emphasis> - structures referenced by the <emphasis> -sym_interpret</emphasis> - field of an <emphasis> -XkbCompatMapRec</emphasis> - (see Figure 17.3). +using +<structname>XkbSymInterpretRec</structname> +structures referenced by the +<structfield>sym_interpret</structfield> +field of an +<structname>XkbCompatMapRec</structname> +(see <link linkend="figure17.3">Figure 17.3</link>). </para> <sect3 id='Symbol_Interpretations__the_XkbSymInterpretRec_Structure'> <title>Symbol Interpretations — the XkbSymInterpretRec Structure</title> +<indexterm significance="preferred" zone="Symbol_Interpretations__the_XkbSymInterpretRec_Structure"> +<primary><structname>XkbSymInterpretRec</structname></primary></indexterm> <para> Symbol interpretations are used to guide the X server when it modifies the Xkb keymap in step 2. An initial set of symbol interpretations is loaded by the -server when it starts. A client may add new ones using <emphasis> -XkbSetCompatMap</emphasis> - (see section 17.4). +server when it starts. A client may add new ones using +<function>XkbSetCompatMap</function> +(see <link linkend="Changing_the_Servers_Compatibility_Map">section 17.4</link>). </para> @@ -416,62 +431,62 @@ XkbSetCompatMap</emphasis> Symbol interpretations result in key semantics being set. When a symbol interpretation is applied, the following components of server key event processing may be modified for the particular key involved: -</para> -<literallayout> - Virtual modifier map - Auto repeat - Key behavior (may be set to <emphasis>XkbKB_Lock</emphasis>) - Key action (see section 16.1) -</literallayout> + <simplelist type='vert' columns='1'> + <member>Virtual modifier map</member> + <member>Auto repeat</member> + <member>Key behavior (may be set to <symbol>XkbKB_Lock</symbol>)</member> + <member>Key action (see <link linkend="Key_Actions">section 16.1</link>)</member> + </simplelist> +</para> <para> -The <emphasis>XkbSymInterpretRec</emphasis> +The <structname>XkbSymInterpretRec</structname> structure specifies a symbol interpretation: -</para> -<para><programlisting> +<programlisting> typedef struct { - KeySym sym; /* keysym of interest or <emphasis>NULL</emphasis> */ - unsigned char flags; /* <emphasis>XkbSI_AutoRepeat, XkbSI_LockingKey</emphasis> */ - unsigned char match; /* specifies how mods is interpreted */ - unsigned char mods; /* modifier bits, correspond to eight real modifiers */ - unsigned char virtual_mod; /* 1 modifier to add to key virtual mod map */ - XkbAnyAction act; /* action to bind to symbol position on key */ -} <emphasis>XkbSymInterpretRec</emphasis>,*XkbSymInterpretPtr; + KeySym sym; /* keysym of interest or <symbol>NULL</symbol> */ + unsigned char flags; /* <symbol>XkbSI_AutoRepeat</symbol>, <symbol>XkbSI_LockingKey</symbol> */ + unsigned char match; /* specifies how mods is interpreted */ + unsigned char mods; /* modifier bits, correspond to + eight real modifiers */ + unsigned char virtual_mod; /* 1 modifier to add to key virtual mod map */ + XkbAnyAction act; /* action to bind to symbol position on key */ +} <structname>XkbSymInterpretRec</structname>,*XkbSymInterpretPtr; </programlisting></para> <para> -If <emphasis> -sym</emphasis> - is not <emphasis> -NULL</emphasis> -, it limits the symbol interpretation to keys on which that particular keysym -is selected by the modifiers matching the criteria specified by <emphasis> -mods</emphasis> - and <emphasis> -match</emphasis> -. If <emphasis> -sym</emphasis> - is <emphasis> -NULL</emphasis> -, the interpretation may be applied to any symbol selected on a key when the -modifiers match the criteria specified by <emphasis> -mods</emphasis> - and <emphasis> -match</emphasis> -. -</para> - - -<para> -<emphasis>match</emphasis> -must be one of the values shown in Table 17.1 and specifies how the real -modifiers specified in <emphasis>mods</emphasis> +If +<structfield>sym</structfield> +is not +<symbol>NULL</symbol>, +it limits the symbol interpretation to keys on which that particular keysym +is selected by the modifiers matching the criteria specified by +<structfield>mods</structfield> +and +<structfield>match</structfield>. +If +<structfield>sym</structfield> +is +<symbol>NULL</symbol>, +the interpretation may be applied to any symbol selected on a key when the +modifiers match the criteria specified by +<structfield>mods</structfield> +and +<structfield>match</structfield>. +</para> + + +<para> +<structfield>match</structfield> +must be one of the values shown in +<link linkend="table17.1">Table 17.1</link> and specifies how the real +modifiers specified in <structfield>mods</structfield> are to be interpreted. </para> -<table frame='topbot'> +<table id='table17.1' frame='topbot'> <title>Symbol Interpretation Match Criteria</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -487,47 +502,47 @@ are to be interpreted. </thead> <tbody> <row> - <entry><emphasis>XkbSI_NoneOf</emphasis></entry> + <entry><symbol>XkbSI_NoneOf</symbol></entry> <entry>(0)</entry> <entry> -None of the bits that are on in <emphasis>mods</emphasis> - can be set, but other bits can be. +None of the bits that are on in <structfield>mods</structfield> +can be set, but other bits can be. </entry> </row> <row> - <entry><emphasis>XkbSI_AnyOfOrNone</emphasis></entry> + <entry><symbol>XkbSI_AnyOfOrNone</symbol></entry> <entry>(1)</entry> <entry> -Zero or more of the bits that are on in <emphasis> -mods</emphasis> - can be set, as well as others. +Zero or more of the bits that are on in +<structfield>mods</structfield> +can be set, as well as others. </entry> </row> <row> - <entry><emphasis>XkbSI_AnyOf</emphasis></entry> + <entry><symbol>XkbSI_AnyOf</symbol></entry> <entry>(2)</entry> <entry> -One or more of the bits that are on in <emphasis> -mods</emphasis> - can be set, as well as any others. +One or more of the bits that are on in +<structfield>mods</structfield> +can be set, as well as any others. </entry> </row> <row> - <entry><emphasis>XkbSI_AllOf</emphasis></entry> + <entry><symbol>XkbSI_AllOf</symbol></entry> <entry>(3)</entry> <entry> -All of the bits that are on in <emphasis> -mods</emphasis> - must be set, but others may be set as well. +All of the bits that are on in +<structfield>mods</structfield> +must be set, but others may be set as well. </entry> </row> <row> - <entry><emphasis>XkbSI_Exactly</emphasis></entry> + <entry><symbol>XkbSI_Exactly</symbol></entry> <entry>(4)</entry> <entry> -All of the bits that are on in <emphasis> -mods</emphasis> - must be set, and no other bits may be set. +All of the bits that are on in +<structfield>mods</structfield> +must be set, and no other bits may be set. </entry> </row> </tbody> @@ -535,21 +550,21 @@ mods</emphasis> </table> <para> -In addition to the above bits, <emphasis> -match</emphasis> - may contain the <emphasis> -XkbSI_LevelOneOnly</emphasis> - bit, in which case the modifier match criteria specified by <emphasis> -mods</emphasis> - and <emphasis> -match</emphasis> - applies only if <emphasis> -sym</emphasis> - is in level one of its group; otherwise, <emphasis> -mods</emphasis> - and <emphasis> -match</emphasis> - are ignored and the symbol matches a condition where no modifiers are set. +In addition to the above bits, +<structfield>match</structfield> +may contain the +<symbol>XkbSI_LevelOneOnly</symbol> +bit, in which case the modifier match criteria specified by +<structfield>mods</structfield> +and +<structfield>match</structfield> +applies only if +<structfield>sym</structfield> +is in level one of its group; otherwise, +<structfield>mods</structfield> +and +<structfield>match</structfield> +are ignored and the symbol matches a condition where no modifiers are set. </para> <para><programlisting> @@ -569,28 +584,28 @@ interpretation where: <colspec colname='c1' colwidth='3.0*'/> <tbody> <row> - <entry><emphasis>sym</emphasis> =</entry> + <entry><structfield>sym</structfield> =</entry> <entry>0</entry> </row> <row> - <entry><emphasis>flags</emphasis> =</entry> - <entry><emphasis>XkbSI_AutoRepeat</emphasis></entry> + <entry><structfield>flags</structfield> =</entry> + <entry><symbol>XkbSI_AutoRepeat</symbol></entry> </row> <row> - <entry><emphasis>match</emphasis> =</entry> - <entry><emphasis>XkbSI_AnyOfOrNone</emphasis></entry> + <entry><structfield>match</structfield> =</entry> + <entry><symbol>XkbSI_AnyOfOrNone</symbol></entry> </row> <row> - <entry><emphasis>mods</emphasis> =</entry> + <entry><structfield>mods</structfield> =</entry> <entry>0</entry> </row> <row> - <entry><emphasis>virtual_mod</emphasis> =</entry> - <entry><emphasis>XkbNoModifier</emphasis></entry> + <entry><structfield>virtual_mod</structfield> =</entry> + <entry><symbol>XkbNoModifier</symbol></entry> </row> <row> - <entry><emphasis>act</emphasis> =</entry> + <entry><structfield>act</structfield> =</entry> <entry><emphasis>SA_NoAction</emphasis></entry> </row> </tbody> @@ -603,74 +618,70 @@ is applied to modify the Xkb map as follows. </para> <para> -The <emphasis> -act</emphasis> - field specifies a single action to be bound to the symbol position; any key +The +<structfield>act</structfield> +field specifies a single action to be bound to the symbol position; any key event that selects the symbol causes the action to be taken. Valid actions are -defined in section 16.1. +defined in <link linkend="Key_Actions">section 16.1</link>. </para> <para> -If the Xkb keyboard map for the key does not have its <emphasis> -ExplicitVModMap</emphasis> - control set, the <emphasis> -XkbSI_LevelOneOnly</emphasis> - bit and symbol position are examined. If the <emphasis> -XkbSI_LevelOneOnly</emphasis> - bit is not set in <emphasis> -match</emphasis> - or the symbol is in position G1L1, the <emphasis> -virtual_mod</emphasis> - field is examined. If <emphasis> -virtual_mod</emphasis> - is not <emphasis> -XkbNoModifier</emphasis> -, <emphasis> -virtual_mod</emphasis> - specifies a single virtual modifier to be added to the virtual modifier map -for the key.<emphasis> - virtual_mod</emphasis> - is specified as an index in the range [0..15]. +If the Xkb keyboard map for the key does not have its +<emphasis>ExplicitVModMap</emphasis> +control set, the +<symbol>XkbSI_LevelOneOnly</symbol> +bit and symbol position are examined. If the +<symbol>XkbSI_LevelOneOnly</symbol> +bit is not set in +<structfield>match</structfield> +or the symbol is in position G1L1, the +<structfield>virtual_mod</structfield> +field is examined. If +<structfield>virtual_mod</structfield> +is not +<symbol>XkbNoModifier</symbol>, +<structfield>virtual_mod</structfield> +specifies a single virtual modifier to be added to the virtual modifier map +for the key. +<structfield>virtual_mod</structfield> +is specified as an index in the range [0..15]. </para> <para> If the matching symbol is in position G1L1 of the key, two bits in the flags field potentially specify additional behavior modifications: -</para> -<para><programlisting> -#define XkbSI_AutoRepeat (1<<0) - /* key repeats if sym is in position G1L1 */ -#define XkbSI_LockingKey (1<<1) - /* set <emphasis> KB_Lock</emphasis> - behavior if sym is in psn G1L1 */ +<programlisting> +#define XkbSI_AutoRepeat (1<<0) /* key repeats if sym + is in position G1L1 */ +#define XkbSI_LockingKey (1<<1) /* set <emphasis>KB_Lock</emphasis> behavior + if sym is in psn G1L1 */ </programlisting></para> <para> -If the Xkb keyboard map for the key does not have its <emphasis> -ExplicitAutoRepeat</emphasis> - control set, its auto repeat behavior is set based on the value of the -<emphasis> -XkbSI_AutoRepeat</emphasis> - bit. If the <emphasis> -XkbSI_AutoRepeat</emphasis> - bit is set, the auto-repeat behavior of the key is turned on; otherwise, it is +If the Xkb keyboard map for the key does not have its +<emphasis>ExplicitAutoRepeat</emphasis> +control set, its auto repeat behavior is set based on the value of the +<symbol>XkbSI_AutoRepeat</symbol> +bit. If the +<symbol>XkbSI_AutoRepeat</symbol> +bit is set, the auto-repeat behavior of the key is turned on; otherwise, it is turned off. </para> <para> -If the Xkb keyboard map for the key does not have its <emphasis> -ExplicitBehavior</emphasis> - control set, its locking behavior is set based on the value of the <emphasis> -XkbSI_LockingKey</emphasis> - bit. If <emphasis> -XkbSI_LockingKey</emphasis> - is set, the key behavior is set to <emphasis> -KB_Lock</emphasis> -; otherwise, it is turned off (see section 16.3). +If the Xkb keyboard map for the key does not have its +<emphasis>ExplicitBehavior</emphasis> +control set, its locking behavior is set based on the value of the +<symbol>XkbSI_LockingKey</symbol> +bit. If +<symbol>XkbSI_LockingKey</symbol> +is set, the key behavior is set to +<emphasis>KB_Lock</emphasis>; +otherwise, it is turned off (see <link linkend="Explicit_ComponentsAvoiding_Automatic_Remapping_by_the_Server">section 16.3</link>). </para> @@ -723,15 +734,15 @@ modifier mapping is generated as well. The modifier mapping contains all of the modifiers affected by any of the actions associated with the key combined with all of the real modifiers associated with any of the virtual modifiers bound to the key. In addition, if any of the actions associated with the key affect any -component of the keyboard group, all of the modifiers in the <emphasis> -mask</emphasis> - field of all of the group compatibility maps are added to the modifier mapping -as well. While an <emphasis> -XkbSA_ISOLock</emphasis> - action can theoretically affect any modifier, if the Xkb mapping for a key -specifies an <emphasis> -XkbSA_ISOLock</emphasis> - action, only the modifiers or group that are set by default are added to the +component of the keyboard group, all of the modifiers in the +<structfield>mask</structfield> +field of all of the group compatibility maps are added to the modifier mapping +as well. While an +<symbol>XkbSA_ISOLock</symbol> +action can theoretically affect any modifier, if the Xkb mapping for a key +specifies an +<symbol>XkbSA_ISOLock</symbol> +action, only the modifiers or group that are set by default are added to the modifier mapping. </para> @@ -742,15 +753,15 @@ modifier mapping. <title>Getting Compatibility Map Components From the Server</title> <para> -Use <emphasis> -XkbGetCompatMap</emphasis> - to fetch any combination of the current compatibility map components from the +Use +<function>XkbGetCompatMap</function> +to fetch any combination of the current compatibility map components from the server. When another client modifies the compatibility map, you are notified if -you have selected for <emphasis> -XkbCompatMapNotify</emphasis> - events (see section 17.5). <emphasis> -XkbGetCompatMap</emphasis> - is particularly useful when you receive an event of this type, as it allows +you have selected for +<symbol>XkbCompatMapNotify</symbol> +events (see <link linkend="Tracking_Changes_to_the_Compatibility_Map">section 17.5</link>). +<function>XkbGetCompatMap</function> +is particularly useful when you receive an event of this type, as it allows you to update your program’s version of the compatibility map to match the modified version now in the server. If your program is dealing with multiple servers and needs to configure them all in a similar manner, the updated @@ -760,62 +771,69 @@ compatibility map may be used to reconfigure other servers. <note><para>To make a complete matching configuration you must also update the explicit override components of the server state.</para></note> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetCompatMap</emphasis> -(<emphasis> -display, which, xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> - display</emphasis> -; /* connection to server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask of compatibility map components to fetch */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescRec * <emphasis> - xkb</emphasis> -; /* keyboard description where results placed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetCompatMap</emphasis> - fetches the components of the compatibility map specified in <emphasis> -which</emphasis> - from the server specified by <emphasis> -display</emphasis> - and places them in the <emphasis> -compat</emphasis> - structure of the keyboard description <emphasis> -xkb</emphasis> -. Valid values for <emphasis> -which</emphasis> - are an inclusive OR of the values shown in Table 17.2. -</para> - -<table frame='topbot'> +<indexterm significance="preferred" zone="XkbGetCompatMap"><primary><function>XkbGetCompatMap</function></primary></indexterm> +<funcsynopsis id="XkbGetCompatMap"> + <funcprototype> + <funcdef>Status <function>XkbGetCompatMap</function></funcdef> +<!-- ( +<parameter>display, which, xkb</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>XkbDescRec *<parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of compatibility map components to fetch + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description where results placed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetCompatMap</function> +fetches the components of the compatibility map specified in +<parameter>which</parameter> +from the server specified by +<parameter>display</parameter> +and places them in the +<structfield>compat</structfield> +structure of the keyboard description +<parameter>xkb</parameter>. +Valid values for +<parameter>which</parameter> +are an inclusive OR of the values shown in +<link linkend="table17.2">Table 17.2</link>. +</para> + +<table id='table17.2' frame='topbot'> <title>Compatibility Map Component Masks</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -831,17 +849,17 @@ which</emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbSymInterpMask</emphasis></entry> + <entry><symbol>XkbSymInterpMask</symbol></entry> <entry>(1<<0)</entry> <entry>Symbol interpretations</entry> </row> <row> - <entry><emphasis>XkbGroupCompatMask</emphasis></entry> + <entry><symbol>XkbGroupCompatMask</symbol></entry> <entry>(1<<1)</entry> <entry>Group maps</entry> </row> <row> - <entry><emphasis>XkbAllCompatMask</emphasis></entry> + <entry><symbol>XkbAllCompatMask</symbol></entry> <entry>(0x3)</entry> <entry>All compatibility map components</entry> </row> @@ -850,44 +868,42 @@ which</emphasis> </table> <para> -If no compatibility map structure is allocated in <emphasis> -xkb</emphasis> - upon entry, <emphasis> -XkbGetCompatMap</emphasis> - allocates one. If one already exists, its contents are overwritten with the +If no compatibility map structure is allocated in +<parameter>xkb</parameter> +upon entry, +<function>XkbGetCompatMap</function> +allocates one. If one already exists, its contents are overwritten with the returned results. </para> <para> -<emphasis> -XkbGetCompatMap</emphasis> - fetches compatibility map information for the device specified by the -<emphasis> -device_spec</emphasis> - field of <emphasis> -xkb</emphasis> -. Unless you have specifically modified this field, it is the default keyboard -device. <emphasis> -XkbGetCompatMap</emphasis> - returns <emphasis> -Success</emphasis> - if successful, <emphasis> -BadAlloc</emphasis> - if it is unable to obtain necessary storage for either the return values or -work space, <emphasis> -BadMatch</emphasis> - if the <emphasis> -dpy</emphasis> - field of the <emphasis> -xkb</emphasis> - argument is non-<emphasis> -NULL</emphasis> - and does not match the <emphasis> -display</emphasis> - argument, and <emphasis> -BadLength</emphasis> - under certain conditions caused by server or Xkb implementation errors. +<function>XkbGetCompatMap</function> +fetches compatibility map information for the device specified by the +<structfield>device_spec</structfield> +field of +<parameter>xkb</parameter>. +Unless you have specifically modified this field, it is the default keyboard +device. +<function>XkbGetCompatMap</function> +returns +<symbol>Success</symbol> +if successful, +<errorname>BadAlloc</errorname> +if it is unable to obtain necessary storage for either the return values or +work space, +<errorname>BadMatch</errorname> +if the +<structfield>dpy</structfield> +field of the +<parameter>xkb</parameter> +argument is non- +<symbol>NULL</symbol> +and does not match the +<parameter>display</parameter> +argument, and +<errorname>BadLength</errorname> +under certain conditions caused by server or Xkb implementation errors. </para> @@ -899,294 +915,310 @@ BadLength</emphasis> Xkb provides several functions that make it easier to apply the compatibility map to configure a client-side Xkb keyboard mapping, given a core protocol representation of part or all of a keyboard mapping. Obtain a core protocol -representation of a keyboard mapping from an actual server (by using <emphasis> -XGetKeyboardMapping</emphasis> -, for example), a data file, or some other source. +representation of a keyboard mapping from an actual server (by using +<function>XGetKeyboardMapping</function>, +for example), a data file, or some other source. </para> <para> To update a local Xkb keyboard map to reflect the mapping expressed by a core -format mapping by calling the function <emphasis> -XkbUpdateMapFromCore</emphasis> -. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbUpdateMapFromCore</emphasis> -(<emphasis> -xkb</emphasis> -,<emphasis> - first_key</emphasis> -,<emphasis> - num_keys</emphasis> -,<emphasis> - map_width</emphasis> -,<emphasis> - core_keysyms</emphasis> -,<emphasis> - changes</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* keyboard description to update */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeyCode <emphasis> - first_key</emphasis> -; /* keycode of first key description to update */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - num_keys</emphasis> -; /* number of key descriptions to update */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> - map_width</emphasis> -; /* width of core protocol keymap */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeySym *<emphasis> - core_keysyms</emphasis> -; /* symbols in core protocol keymap */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbChangesPtr <emphasis> - changes</emphasis> -; /* backfilled with changes made to Xkb */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbUpdateMapFromCore</emphasis> - interprets input argument information representing a keyboard map in core -format to update the Xkb keyboard description passed in <emphasis> -xkb</emphasis> -. Only a portion of the Xkb map is updated — the portion corresponding to -keys with keycodes in the range <emphasis> -first_key</emphasis> - through <emphasis> -first_key</emphasis> - + <emphasis> -num_keys</emphasis> - - 1. If <emphasis> -XkbUpdateMapFromCore</emphasis> - is being called in response to a<emphasis> - </emphasis> -<emphasis> -MappingNotify</emphasis> -<emphasis> - </emphasis> -event<emphasis> -, first_key</emphasis> - and <emphasis> -num_keys</emphasis> - are reported in the <emphasis> -MappingNotify</emphasis> - event. <emphasis> -core_keysyms</emphasis> - contains the keysyms corresponding to the keycode range being updated, in core -keyboard description order. <emphasis> -map_width</emphasis> - is the number of keysyms per key in <emphasis> -core_keysyms</emphasis> -. Thus, the first <emphasis> -map_width</emphasis> - entries in <emphasis> -core_keysyms</emphasis> - are for the key with keycode <emphasis> -first_key</emphasis> -, the next <emphasis> -map_width</emphasis> - entries are for key <emphasis> -first_key</emphasis> - + 1, and so on. -</para> - - -<para> -In addition to modifying the Xkb keyboard mapping in <emphasis> -xkb</emphasis> -, <emphasis> -XkbUpdateMapFromCore</emphasis> - backfills the changes structure whose address is passed in <emphasis> -changes</emphasis> - to indicate the modifications that were made. You may then use <emphasis> -changes</emphasis> - in subsequent calls such as <emphasis> -XkbSetMap</emphasis> -, to propagate the local modifications to a server. +format mapping by calling the function +<function>XkbUpdateMapFromCore</function>. +</para> + +<indexterm significance="preferred" zone="XkbUpdateMapFromCore"><primary><function>XkbUpdateMapFromCore</function></primary></indexterm> +<funcsynopsis id="XkbUpdateMapFromCore"> + <funcprototype> + <funcdef>Bool <function>XkbUpdateMapFromCore</function></funcdef> +<!-- ( +<parameter>xkb</parameter>, +<parameter>first_key</parameter>, +<parameter>num_keys</parameter>, +<parameter>map_width</parameter>, +<parameter>core_keysyms</parameter>, +<parameter>changes</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>first_key</parameter></paramdef> + <paramdef>int <parameter>num_keys</parameter></paramdef> + <paramdef>int <parameter>map_width</parameter></paramdef> + <paramdef>KeySym *<parameter>core_keysyms</parameter></paramdef> + <paramdef>XkbChangesPtr <parameter>changes</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description to update + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first_key</parameter> + </term> + <listitem> + <para> + keycode of first key description to update + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_keys</parameter> + </term> + <listitem> + <para> + number of key descriptions to update + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>map_width</parameter> + </term> + <listitem> + <para> + width of core protocol keymap + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>core_keysyms</parameter> + </term> + <listitem> + <para> + symbols in core protocol keymap + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + backfilled with changes made to Xkb + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbUpdateMapFromCore</function> +interprets input argument information representing a keyboard map in core +format to update the Xkb keyboard description passed in +<parameter>xkb</parameter>. +Only a portion of the Xkb map is updated — the portion corresponding to +keys with keycodes in the range +<parameter>first_key</parameter> +through +<parameter>first_key</parameter> ++ +<parameter>num_keys</parameter> +- 1. If +<function>XkbUpdateMapFromCore</function> +is being called in response to a +<symbol>MappingNotify</symbol> +event, +<parameter>first_key</parameter> +and +<parameter>num_keys</parameter> +are reported in the +<symbol>MappingNotify</symbol> +event. +<parameter>core_keysyms</parameter> +contains the keysyms corresponding to the keycode range being updated, in core +keyboard description order. +<parameter>map_width</parameter> +is the number of keysyms per key in +<parameter>core_keysyms</parameter>. +Thus, the first +<parameter>map_width</parameter> +entries in +<parameter>core_keysyms</parameter> +are for the key with keycode +<parameter>first_key</parameter>, +the next +<parameter>map_width</parameter> +entries are for key +<parameter>first_key</parameter> ++ 1, and so on. +</para> + + +<para> +In addition to modifying the Xkb keyboard mapping in +<parameter>xkb</parameter>, +<function>XkbUpdateMapFromCore</function> +backfills the changes structure whose address is passed in +<parameter>changes</parameter> +to indicate the modifications that were made. You may then use +<parameter>changes</parameter> +in subsequent calls such as +<function>XkbSetMap</function>, +to propagate the local modifications to a server. </para> <para> When dealing with core keyboard mappings or descriptions, it is sometimes necessary to determine the Xkb key types appropriate for the symbols bound to a -key in a core keyboard mapping. Use <emphasis> -XkbKeyTypesForCoreSymbols</emphasis> - for this purpose: -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -int <emphasis> -XkbKeyTypesForCoreSymbols</emphasis> -(<emphasis> -map_width</emphasis> -,<emphasis> - core_syms</emphasis> -,<emphasis> - protected, types_inout, xkb_syms_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr<emphasis> - xkb</emphasis> -; /* keyboard description in which to place symbols*/ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int<emphasis> - map_width</emphasis> -; /* width of core protocol keymap in <emphasis> -xkb_syms_rtrn</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeySym *<emphasis> - core_syms</emphasis> -; /* core protocol format array of KeySyms */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -protected</emphasis> -; /* explicit key types */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int *<emphasis> - types_inout;</emphasis> - /* backfilled with the canonical types bound to groups one and two -for the key */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -KeySym * <emphasis> -xkb_syms_rtrn</emphasis> - ; /* backfilled with symbols bound to the key in the Xkb mapping */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbKeyTypesForCoreSymbols</emphasis> - expands the symbols in <emphasis> -core_syms</emphasis> - and types in <emphasis> -types_inout</emphasis> - according to the rules specified in section 12 of the core protocol, then -chooses canonical key types (canonical key types are defined in section 15.2.1) +key in a core keyboard mapping. Use +<function>XkbKeyTypesForCoreSymbols</function> +for this purpose: +</para> + + +<indexterm significance="preferred" zone="XkbKeyTypesForCoreSymbols"><primary><function>XkbKeyTypesForCoreSymbols</function></primary></indexterm> +<funcsynopsis id="XkbKeyTypesForCoreSymbols"> + <funcprototype> + <funcdef>int <function>XkbKeyTypesForCoreSymbols</function></funcdef> +<!-- ( +<parameter>map_width</parameter>, +<parameter>core_syms</parameter>, +<parameter>protected, types_inout, xkb_syms_rtrn</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>int <parameter>map_width</parameter></paramdef> + <paramdef>KeySym *<parameter>core_syms</parameter></paramdef> + <paramdef>unsigned int <parameter>protected</parameter></paramdef> + <paramdef>int *<parameter>types_inout</parameter></paramdef> + <paramdef>KeySym *<parameter>xkb_syms_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description in which to place symbols + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>map_width</parameter> + </term> + <listitem> + <para> + width of core protocol keymap in <parameter>xkb_syms_rtrn</parameter> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>core_syms</parameter> + </term> + <listitem> + <para> + core protocol format array of KeySyms + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>protected</parameter> + </term> + <listitem> + <para> + explicit key types + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>types_inout</parameter> + </term> + <listitem> + <para> + backfilled with the canonical types bound to groups one and two + for the key + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb_syms_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with symbols bound to the key in the Xkb mapping + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbKeyTypesForCoreSymbols</function> +expands the symbols in +<parameter>core_syms</parameter> +and types in +<parameter>types_inout</parameter> +according to the rules specified in section 12 of the core protocol, then +chooses canonical key types (canonical key types are defined in <link linkend="The_Canonical_Key_Types">section 15.2.1</link>) for groups 1 and 2 using the rules specified by the Xkb protocol and places -them in <emphasis> -xkb_syms_rtrn</emphasis> -, which will be non-<emphasis> -NULL</emphasis> -. +them in +<parameter>xkb_syms_rtrn</parameter>, +which will be non- +<symbol>NULL</symbol>. </para> <para> -A core keymap is a two-dimensional array of keysyms. It has <emphasis> -map_width</emphasis> - columns and <emphasis> -max_key_code</emphasis> - rows. <emphasis> -XkbKeyTypesForCoreSymbols</emphasis> - takes a single row from a core keymap, determines the number of groups +A core keymap is a two-dimensional array of keysyms. It has +<parameter>map_width</parameter> +columns and +<structfield>max_key_code</structfield> +rows. +<function>XkbKeyTypesForCoreSymbols</function> +takes a single row from a core keymap, determines the number of groups associated with it, the type of each group, and the symbols bound to each -group. The return value is the number of groups, <emphasis> -types_inout</emphasis> - has the types for each group, and <emphasis> -xkb_syms_rtrn</emphasis> - has the symbols in Xkb order (that is, groups are contiguous, regardless of +group. The return value is the number of groups, +<parameter>types_inout</parameter> +has the types for each group, and +<parameter>xkb_syms_rtrn</parameter> +has the symbols in Xkb order (that is, groups are contiguous, regardless of size). </para> <para> -<emphasis> -protected</emphasis> - contains the explicitly protected key types. There is one explicit override +<parameter>protected</parameter> +contains the explicitly protected key types. There is one explicit override control associated with each of the four possible groups for each Xkb key, -<emphasis> -ExplicitKeyType1</emphasis> - through <emphasis> -ExplicitKeyType4</emphasis> -<emphasis> -; protected </emphasis> -is an inclusive OR of these controls. <emphasis> -map_width</emphasis> - is the width of the core keymap and is not dependent on any Xkb definitions. -<emphasis> -types_inout</emphasis> - is an array of four type indices. On input, <emphasis> -types_inout</emphasis> - contains the indices of any types already assigned to the key, in case they +<emphasis>ExplicitKeyType1</emphasis> +through +<emphasis>ExplicitKeyType4</emphasis>; +<parameter>protected</parameter> +is an inclusive OR of these controls. +<parameter>map_width</parameter> +is the width of the core keymap and is not dependent on any Xkb definitions. +<parameter>types_inout</parameter> +is an array of four type indices. On input, +<parameter>types_inout</parameter> +contains the indices of any types already assigned to the key, in case they are explicitly protected from change. </para> <para> -Upon return, <emphasis> -types_inout</emphasis> - contains any automatically selected (that is, canonical) types plus any +Upon return, +<parameter>types_inout</parameter> +contains any automatically selected (that is, canonical) types plus any protected types. Canonical types are assigned to all four groups if there are -enough symbols to do so. The four entries in <emphasis> -types_inout</emphasis> - correspond to the four groups for the key in question. +enough symbols to do so. The four entries in +<parameter>types_inout</parameter> +correspond to the four groups for the key in question. </para> @@ -1194,59 +1226,62 @@ types_inout</emphasis> If the groups mapping does not change, but the symbols assigned to an Xkb keyboard compatibility map do change, the semantics of the key may be modified. To apply the new compatibility mapping to an individual key to get its -semantics updated, use <emphasis> -XkbApplyCompatMapToKey</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbApplyCompatMapToKey</emphasis> -(<emphasis> -xkb</emphasis> -,<emphasis> - key</emphasis> -,<emphasis> - changes</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> - XkbDescPtr<emphasis> - xkb; </emphasis> -/* keyboard description to be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> - KeyCode<emphasis> - key</emphasis> -; /* key to be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> - XkbChangesPtr<emphasis> - changes</emphasis> -; /* notes changes to the Xkb keyboard description */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbApplyCompatMapToKey</emphasis> - essentially performs the operation described in section 17.1.2 to a specific +semantics updated, use +<function>XkbApplyCompatMapToKey</function>. +</para> + + +<indexterm significance="preferred" zone="XkbApplyCompatMapToKey"><primary><function>XkbApplyCompatMapToKey</function></primary></indexterm> +<funcsynopsis id="XkbApplyCompatMapToKey"> + <funcprototype> + <funcdef>Bool <function>XkbApplyCompatMapToKey</function></funcdef> +<!-- ( +<parameter>xkb</parameter>, +<parameter>key</parameter>, +<parameter>changes</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>KeyCode <parameter>key</parameter></paramdef> + <paramdef>XkbChangesPtr <parameter>changes</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description to be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>key</parameter> + </term> + <listitem> + <para> + key to be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + notes changes to the Xkb keyboard description + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbApplyCompatMapToKey</function> +essentially performs the operation described in <link linkend="Core_Keyboard_Mapping_to_Xkb_Keyboard_Mapping_Transformation">section 17.1.2</link> to a specific key. This updates the behavior, actions, repeat status, and virtual modifier bindings of the key. </para> @@ -1258,268 +1293,280 @@ bindings of the key. <para> To modify the server’s compatibility map, first modify a local copy of the -Xkb compatibility map, then call <emphasis> -XkbSetCompatMap</emphasis> -. You may allocate a new compatibility map for this purpose using <emphasis> -XkbAllocCompatMap</emphasis> - (see section 17.6). You may also use a compatibility map from another server, -although you need to adjust the <emphasis> -device_spec</emphasis> - field in the <emphasis> -XkbDescRec</emphasis> - accordingly. Note that symbol interpretations in a compatibility map -(<emphasis> -sym_interpret</emphasis> -, the vector of <emphasis> -XkbSymInterpretRec</emphasis> - structures) are also allocated using this same function. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetCompatMap</emphasis> -(<emphasis> -display, which, xkb, update_actions</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> - display</emphasis> -; /* connection to server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask of compat map components to set */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* source for compat map components */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - update_actions</emphasis> -; /* <emphasis> -True</emphasis> - => apply to server’s keyboard map */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetCompatMap</emphasis> - copies compatibility map information from the keyboard description in -<emphasis> -xkb</emphasis> - to the server specified in <emphasis> -display</emphasis> -’s compatibility map for the device specified by the <emphasis> -device_spec</emphasis> - field of <emphasis> -xkb</emphasis> -. Unless you have specifically modified this field, it is the default keyboard -device.<emphasis> - which</emphasis> - specifies the compatibility map components to be set, and is an inclusive OR -of the bits shown in Table 17.2. -</para> - - -<para> -After updating its compatibility map for the specified device, if <emphasis> -update_actions</emphasis> - is <emphasis> -True,</emphasis> - the server applies the new compatibility map to its entire keyboard for the +Xkb compatibility map, then call +<function>XkbSetCompatMap</function>. +You may allocate a new compatibility map for this purpose using +<function>XkbAllocCompatMap</function> +(see <link linkend="Allocating_and_Freeing_the_Compatibility_Map">section 17.6</link>). You may also use a compatibility map from another server, +although you need to adjust the +<structfield>device_spec</structfield> +field in the +<structname>XkbDescRec</structname> +accordingly. Note that symbol interpretations in a compatibility map +( +<structfield>sym_interpret</structfield>, +the vector of +<structname>XkbSymInterpretRec</structname> +structures) are also allocated using this same function. +</para> + +<indexterm significance="preferred" zone="XkbSetCompatMap"><primary><function>XkbSetCompatMap</function></primary></indexterm> +<funcsynopsis id="XkbSetCompatMap"> + <funcprototype> + <funcdef>Bool <function>XkbSetCompatMap</function></funcdef> +<!-- ( +<parameter>display, which, xkb, update_actions</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>Bool <parameter>update_actions</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of compat map components to set + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + source for compat map components + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>update_actions</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ apply to server’s keyboard map + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetCompatMap</function> +copies compatibility map information from the keyboard description in +<parameter>xkb</parameter> +to the server specified in +<parameter>display</parameter>’s +compatibility map for the device specified by the +<structfield>device_spec</structfield> +field of +<parameter>xkb</parameter>. +Unless you have specifically modified this field, it is the default keyboard +device. +<parameter>which</parameter> +specifies the compatibility map components to be set, and is an inclusive OR +of the bits shown in <link linkend="table17.2">Table 17.2</link>. +</para> + + +<para> +After updating its compatibility map for the specified device, if +<parameter>update_actions</parameter> +is +<symbol>True</symbol>, +the server applies the new compatibility map to its entire keyboard for the device to generate a new set of key semantics, compatibility state, and a new -core keyboard map. If <emphasis> -update_actions</emphasis> - is <emphasis> -False</emphasis> -, the new compatibility map is not used to generate any modifications to the +core keyboard map. If +<parameter>update_actions</parameter> +is +<symbol>False</symbol>, +the new compatibility map is not used to generate any modifications to the current device semantics, state, or core keyboard map. One reason for not applying the compatibility map immediately would be if one server was being configured to match another on a piecemeal basis; the map should not be applied -until everything is updated. To force an update at a later time, use <emphasis> -XkbSetCompatMap</emphasis> - specifying <emphasis> -which</emphasis> - as zero and <emphasis> -update_actions</emphasis> - as <emphasis> -True</emphasis> -. -</para> - - -<para> -<emphasis> -XkbSetCompatMap</emphasis> - returns <emphasis> -True</emphasis> - if successful and <emphasis> -False</emphasis> - if unsuccessful. The server may report problems it encounters when processing -the request subsequently via protocol errors. +until everything is updated. To force an update at a later time, use +<function>XkbSetCompatMap</function> +specifying +<parameter>which</parameter> +as zero and +<parameter>update_actions</parameter> +as +<symbol>True</symbol>. </para> <para> -To add a symbol interpretation to the list of symbol interpretations in an -<emphasis> -XkbCompatRec</emphasis> -, use <emphasis> -XkbAddSymInterpret</emphasis> -. +<function>XkbSetCompatMap</function> +returns +<symbol>True</symbol> +if successful and +<symbol>False</symbol> +if unsuccessful. The server may report problems it encounters when processing +the request subsequently via protocol errors. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbSymInterpretPtr <emphasis> -XkbAddSymInterpret</emphasis> -(<emphasis> -xkb, si, updateMap, changes</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr<emphasis> - xkb</emphasis> -; /* keyboard description to be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbSymInterpretPtr<emphasis> - si</emphasis> -; /* symbol interpretation to be added */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool<emphasis> - updateMap</emphasis> -; /* <emphasis> -True</emphasis> -=>apply compatibility map to keys */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbChangesPtr<emphasis> - changes</emphasis> -; /* changes are put here */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - <para> -<emphasis> -XkbAddSymInterpret</emphasis> - adds <emphasis> -si</emphasis> - to the list of symbol interpretations in <emphasis> -xkb</emphasis> -. If <emphasis> -updateMap</emphasis> - is <emphasis> -True</emphasis> -, it (re)applies the compatibility map to all of the keys on the keyboard. If -<emphasis> -changes</emphasis> - is non-<emphasis> -NULL</emphasis> -, it reports the parts of the keyboard that were affected (unless <emphasis> -updateMap</emphasis> - is <emphasis> -True</emphasis> -, not much changes). <emphasis> -XkbAddSymInterpret</emphasis> - returns a pointer to the actual new symbol interpretation in the list or -<emphasis> -NULL</emphasis> - if it failed. +To add a symbol interpretation to the list of symbol interpretations in an +<structname>XkbCompatRec</structname>, +use +<function>XkbAddSymInterpret</function>. +</para> + + +<indexterm significance="preferred" zone="XkbAddSymInterpret"><primary><function>XkbAddSymInterpret</function></primary></indexterm> +<funcsynopsis id="XkbAddSymInterpret"> + <funcprototype> + <funcdef>XkbSymInterpretPtr <function>XkbAddSymInterpret</function></funcdef> +<!-- ( +<parameter>xkb, si, updateMap, changes</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>XkbSymInterpretPtr <parameter>si</parameter></paramdef> + <paramdef>Bool <parameter>updateMap</parameter></paramdef> + <paramdef>XkbChangesPtr <parameter>changes</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description to be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>si</parameter> + </term> + <listitem> + <para> + symbol interpretation to be added + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>updateMap</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol>⇒apply compatibility map to keys + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + changes are put here + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAddSymInterpret</function> +adds +<parameter>si</parameter> +to the list of symbol interpretations in +<parameter>xkb</parameter>. +If +<parameter>updateMap</parameter> +is +<symbol>True</symbol>, +it (re)applies the compatibility map to all of the keys on the keyboard. If +<parameter>changes</parameter> +is non- +<symbol>NULL</symbol>, +it reports the parts of the keyboard that were affected (unless +<parameter>updateMap</parameter> +is +<symbol>True</symbol>, +not much changes). +<function>XkbAddSymInterpret</function> +returns a pointer to the actual new symbol interpretation in the list or +<symbol>NULL</symbol> +if it failed. </para> </sect1> <sect1 id='Tracking_Changes_to_the_Compatibility_Map'> <title>Tracking Changes to the Compatibility Map</title> +<indexterm significance="preferred" zone="Tracking_Changes_to_the_Compatibility_Map"> +<primary>events</primary><secondary><symbol></symbol>XkbCompatMapNotify</secondary></indexterm> +<indexterm significance="preferred" zone="Tracking_Changes_to_the_Compatibility_Map"> +<primary><structname>XkbCompatMapNotifyEvent</structname></primary></indexterm> <para> -The server automatically generates <emphasis> -MappingNotify</emphasis> - events when the keyboard mapping changes. If you wish to be notified of -changes to the compatibility map, you should select for <emphasis> -XkbCompatMapNotify</emphasis> - events. If you select for <emphasis> -XkbMapNotify</emphasis> - events, you no longer receive the automatically generated <emphasis> -MappingNotify</emphasis> - events. If you subsequently deselect <emphasis> -XkbMapNotifyEvent</emphasis> - delivery, you again receive <emphasis> -MappingNotify</emphasis> - events. +The server automatically generates +<symbol>MappingNotify</symbol> +events when the keyboard mapping changes. If you wish to be notified of +changes to the compatibility map, you should select for +<symbol>XkbCompatMapNotify</symbol> +events. If you select for +<symbol>XkbMapNotify</symbol> +events, you no longer receive the automatically generated +<symbol>MappingNotify</symbol> +events. If you subsequently deselect +<structname>XkbMapNotifyEvent</structname> +delivery, you again receive +<symbol>MappingNotify</symbol> +events. </para> <para> -To receive <emphasis> -XkbCompatMapNotify</emphasis> - events under all possible conditions, use <emphasis> -XkbSelectEvents</emphasis> - (see section 4.3) and pass <emphasis> -XkbCompatMapNotifyMask</emphasis> - in both <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> -. +To receive +<symbol>XkbCompatMapNotify</symbol> +events under all possible conditions, use +<function>XkbSelectEvents</function> +(see <link linkend="Selecting_Xkb_Events">section 4.3</link>) and pass +<symbol>XkbCompatMapNotifyMask</symbol> +in both +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter>. </para> <para> -To receive <emphasis> -XkbCompatMapNotify</emphasis> - events only under certain conditions, use <emphasis> -XkbSelectEventDetails</emphasis> - using <emphasis> -XkbCompatMapNotify</emphasis> - as the <emphasis> -event_type</emphasis> - and specifying the desired map changes in <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> - using mask bits from Table 17.2. +To receive +<symbol>XkbCompatMapNotify</symbol> +events only under certain conditions, use +<function>XkbSelectEventDetails</function> +using +<symbol>XkbCompatMapNotify</symbol> +as the +<structfield>event_type</structfield> +and specifying the desired map changes in +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +using mask bits from <link linkend="table17.2">Table 17.2</link>. </para> @@ -1530,71 +1577,65 @@ made by other clients. <para> -The structure for the <emphasis> -XkbCompatMapNotifyEvent</emphasis> - is: -</para> +The structure for the +<structname>XkbCompatMapNotifyEvent</structname> +is: -<para><programlisting> +<programlisting> typedef struct { - int type; /* Xkb extension base event code */ - unsigned long serial; /* X server serial number for event */ - Bool send_event; /* <emphasis>True</emphasis> => - synthetically generated */ - Display * display; /* server connection where event generated */ - Time time; /* server time when event generated */ - int xkb_type; /* <emphasis>XkbCompatMapNotify</emphasis> */ - int device; /* Xkb device ID, will not be - <emphasis>XkbUseCoreKbd</emphasis> */ - unsigned int changed_groups;/* number of group maps changed */ - int first_si; /* index to 1st changed symbol - interpretation */ - int num_si; /* number of changed symbol - interpretations */ - int num_total_si; /* total number of valid symbol - interpretations */ -} <emphasis>XkbCompatMapNotifyEvent</emphasis>; + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* <symbol>True</symbol> ⇒ + synthetically generated */ + Display * display; /* server connection where event generated */ + Time time; /* server time when event generated */ + int xkb_type; /* <symbol>XkbCompatMapNotify</symbol> */ + int device; /* Xkb device ID, will not be + <symbol>XkbUseCoreKbd</symbol> */ + unsigned int changed_groups; /* number of group maps changed */ + int first_si; /* index to 1st changed symbol + interpretation */ + int num_si; /* number of changed symbol + interpretations */ + int num_total_si; /* total number of valid symbol + interpretations */ +} <structname>XkbCompatMapNotifyEvent</structname>; </programlisting></para> <para> -<emphasis> -changed_groups</emphasis> - is the number of group compatibility maps that have changed. If you are +<structfield>changed_groups</structfield> +is the number of group compatibility maps that have changed. If you are maintaining a corresponding copy of the compatibility map, or get a fresh copy -from the server using <emphasis> -XkbGetCompatMap</emphasis> -, <emphasis> -changed_groups</emphasis> - references <emphasis> -groups</emphasis> -[0..<emphasis> -changed_groups</emphasis> --1] in the <emphasis> -XkbCompatMapRec</emphasis> - structure. -</para> - - -<para> -<emphasis> -first_si</emphasis> - is the index of the first changed symbol interpretation, <emphasis> -num_si</emphasis> - is the number of changed symbol interpretations, and <emphasis> -num_total_si</emphasis> - is the total number of valid symbol interpretations. If you are maintaining a +from the server using +<function>XkbGetCompatMap</function>, +<structfield>changed_groups</structfield> +references +<structfield>groups</structfield> +[0.. +<structfield>changed_groups</structfield> +-1] in the +<structname>XkbCompatMapRec</structname> +structure. +</para> + + +<para> +<structfield>first_si</structfield> +is the index of the first changed symbol interpretation, +<structfield>num_si</structfield> +is the number of changed symbol interpretations, and +<structfield>num_total_si</structfield> +is the total number of valid symbol interpretations. If you are maintaining a corresponding copy of the compatibility map, or get a fresh copy from the -server using <emphasis> -XkbGetCompatMap</emphasis> -, <emphasis> -first_si</emphasis> -, <emphasis> -num_si</emphasis> -, and <emphasis> -num_total_si</emphasis> - are appropriate for use with the <emphasis> -compat.sym_interpret</emphasis> - vector in this structure. +server using +<function>XkbGetCompatMap</function>, +<structfield>first_si</structfield>, +<structfield>num_si</structfield>, +and +<structfield>num_total_si</structfield> +are appropriate for use with the +<structfield>compat.sym_interpret</structfield> +vector in this structure. </para> @@ -1605,200 +1646,201 @@ compat.sym_interpret</emphasis> <para> If you are modifying the compatibility map, you need to allocate a new compatibility map if you do not already have one available. To do so, use -<emphasis> -XkbAllocCompatMap</emphasis> -. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocCompatMap</emphasis> -(<emphasis> -xkb, which, num_si</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* keyboard description in which to allocate compat map */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask of compatibility map components to allocate */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - num_si</emphasis> -; /* number of symbol interpretations to allocate */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -xkb</emphasis> - specifies the keyboard description for which compatibility maps are to be -allocated. The compatibility map is the <emphasis> -compat</emphasis> - field in this structure. -</para> - - -<para> -<emphasis> -which</emphasis> - specifies the compatibility map components to be allocated (see <emphasis> -XkbGetCompatMap</emphasis> -, in section 17.2). <emphasis> -which</emphasis> - is an inclusive OR of the bits shown in Table 17.2. -</para> - - -<para> -<emphasis> -num_si</emphasis> - specifies the total number of entries to allocate in the symbol interpretation -vector (<emphasis> -xkb.compat.sym_interpret</emphasis> -). -</para> - - -<para> -Note that symbol interpretations in a compatibility map (the <emphasis> -sym_interpret</emphasis> - vector of <emphasis> -XkbSymInterpretRec</emphasis> - structures) are also allocated using this same function. To ensure that there +<function>XkbAllocCompatMap</function>. +</para> + +<indexterm significance="preferred" zone="XkbAllocCompatMap"><primary><function>XkbAllocCompatMap</function></primary></indexterm> +<funcsynopsis id="XkbAllocCompatMap"> + <funcprototype> + <funcdef>Status <function>XkbAllocCompatMap</function></funcdef> +<!-- ( +<parameter>xkb, which, num_si</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>unsigned int <parameter>num_si</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description in which to allocate compat map + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of compatibility map components to allocate + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_si</parameter> + </term> + <listitem> + <para> + number of symbol interpretations to allocate + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<parameter>xkb</parameter> +specifies the keyboard description for which compatibility maps are to be +allocated. The compatibility map is the +<structfield>compat</structfield> +field in this structure. +</para> + + +<para> +<parameter>which</parameter> +specifies the compatibility map components to be allocated (see +<link linkend="XkbGetCompatMap"><function>XkbGetCompatMap</function></link>, +in <link linkend="Getting_Compatibility_Map_Components_From_the_Server">section 17.2</link>). +<parameter>which</parameter> +is an inclusive OR of the bits shown in +<link linkend="table17.2">Table 17.2</link>. +</para> + + +<para> +<parameter>num_si</parameter> +specifies the total number of entries to allocate in the symbol interpretation +vector +(<structfield>xkb.compat.sym_interpret</structfield>). + +</para> + + +<para> +Note that symbol interpretations in a compatibility map (the +<structfield>sym_interpret</structfield> +vector of +<structname>XkbSymInterpretRec</structname> +structures) are also allocated using this same function. To ensure that there is sufficient space in the symbol interpretation vector for entries to be -added, use <emphasis> -XkbAllocCompatMap</emphasis> - specifying <emphasis> -which</emphasis> - as <emphasis> -XkbSymInterpretMask</emphasis> - and the number of free symbol interpretations needed in <emphasis> -num_si</emphasis> -. -</para> - - -<para> -<emphasis> -XkbAllocCompatMap</emphasis> - returns <emphasis> -Success</emphasis> - if successful, <emphasis> -BadMatch</emphasis> - if <emphasis> -xkb</emphasis> - is <emphasis> -NULL</emphasis> -, or <emphasis> -BadAlloc</emphasis> - if errors are encountered when attempting to allocate storage. -</para> - - -<para> -To free an entire compatibility map or selected portions of one, use <emphasis> -XkbFreeCompatMap</emphasis> -. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeCompatMap</emphasis> -(<emphasis> -xkb, which, free_map</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* Xkb description in which to free compatibility map */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask of compatibility map components to free */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - free_map</emphasis> -; /* <emphasis> -True</emphasis> - => free <emphasis> -XkbCompatMap</emphasis> - structure itself */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -which</emphasis> - specifies the compatibility map components to be freed (see <emphasis> -XkbGetCompatMap</emphasis> -, in section 17.2). <emphasis> -which</emphasis> - is an inclusive OR of the bits shown in Table 17.2 -</para> - - -<para> -<emphasis> -free_map</emphasis> - indicates whether the <emphasis> -XkbCompatMap</emphasis> - structure itself should be freed. If <emphasis> -free_map</emphasis> - is <emphasis> -True</emphasis> -, <emphasis> -which</emphasis> - is ignored, all non-<emphasis> -NULL</emphasis> - compatibility map components are freed, and the <emphasis> -compat</emphasis> - field in the <emphasis> -XkbDescRec</emphasis> - referenced by <emphasis> -xkb</emphasis> - is set to <emphasis> -NULL</emphasis> -. +added, use +<function>XkbAllocCompatMap</function> +specifying +<parameter>which</parameter> +as +<emphasis>XkbSymInterpretMask</emphasis> +and the number of free symbol interpretations needed in +<parameter>num_si</parameter>. +</para> + + +<para> +<function>XkbAllocCompatMap</function> +returns +<symbol>Success</symbol> +if successful, +<errorname>BadMatch</errorname> +if +<parameter>xkb</parameter> +is +<symbol>NULL</symbol>, +or +<errorname>BadAlloc</errorname> +if errors are encountered when attempting to allocate storage. +</para> + + +<para> +To free an entire compatibility map or selected portions of one, use +<function>XkbFreeCompatMap</function>. +</para> + + +<indexterm significance="preferred" zone="XkbFreeCompatMap"><primary><function>XkbFreeCompatMap</function></primary></indexterm> +<funcsynopsis id="XkbFreeCompatMap"> + <funcprototype> + <funcdef>void <function>XkbFreeCompatMap</function></funcdef> +<!-- ( +<parameter>xkb, which, free_map</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>Bool <parameter>free_map</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description in which to free compatibility map + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of compatibility map components to free + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_map</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ free <structname>XkbCompatMapRec</structname> + structure itself + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<parameter>which</parameter> +specifies the compatibility map components to be freed (see +<link linkend="XkbGetCompatMap"><function>XkbGetCompatMap</function></link>, +in <link linkend="Getting_Compatibility_Map_Components_From_the_Server">section 17.2</link>). +<parameter>which</parameter> +is an inclusive OR of the bits shown in +<link linkend="table17.2">Table 17.2</link> +</para> + + +<para> +<parameter>free_map</parameter> +indicates whether the +<structname>XkbCompatMapRec</structname> +structure itself should be freed. If +<parameter>free_map</parameter> +is +<symbol>True</symbol>, +<parameter>which</parameter> +is ignored, all non- +<symbol>NULL</symbol> +compatibility map components are freed, and the +<structfield>compat</structfield> +field in the +<structname>XkbDescRec</structname> +referenced by +<parameter>xkb</parameter> +is set to +<symbol>NULL</symbol>. </para> </sect1> diff --git a/libX11/specs/XKB/ch18.xml b/libX11/specs/XKB/ch18.xml index 806b09a45..0f283ecfc 100644 --- a/libX11/specs/XKB/ch18.xml +++ b/libX11/specs/XKB/ch18.xml @@ -1,3 +1,6 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Symbolic_Names'> <title>Symbolic Names</title> @@ -7,13 +10,12 @@ actually used to interpret events. This makes it difficult to write an application that presents the keyboard to a user in an easy-to-understand way. Such applications have to examine the vendor string and keycodes to determine the type of keyboard connected to the server and then examine keysyms and -modifier mappings to determine the effects of most modifiers (the <emphasis> -Shift</emphasis> -, <emphasis> -Lock</emphasis> - and <emphasis> -Control</emphasis> - modifiers are defined by the core protocol but no semantics are implied for +modifier mappings to determine the effects of most modifiers (the +<symbol>Shift</symbol>, +<symbol>Lock</symbol> +and +<symbol>Control</symbol> +modifiers are defined by the core protocol but no semantics are implied for any other modifiers). </para> @@ -21,69 +23,76 @@ any other modifiers). <para> To make it easier for applications to present a keyboard to the user, Xkb supports symbolic names for most components of the keyboard extension. Most of -these symbolic names are grouped into the <emphasis> -names</emphasis> - component of the keyboard description. +these symbolic names are grouped into the +<structfield>names</structfield> +component of the keyboard description. </para> <sect1 id='The_XkbNamesRec_Structure'> <title>The XkbNamesRec Structure</title> +<indexterm significance="preferred" zone="The_XkbNamesRec_Structure"> +<primary><structname>XkbKeyNameRec</structname></primary></indexterm> +<indexterm significance="preferred" zone="The_XkbNamesRec_Structure"> +<primary><structname>XkbKeyAliasRec</structname></primary></indexterm> +<indexterm significance="preferred" zone="The_XkbNamesRec_Structure"> +<primary><structname>XkbNamesRec</structname></primary></indexterm> <para> The names component of the keyboard description is defined as follows: -</para> -<para><programlisting> +<programlisting> #define XkbKeyNameLength 4 #define XkbKeyNumVirtualMods 16 #define XkbKeyNumIndicators 32 #define XkbKeyNumKbdGroups 4 #define XkbMaxRadioGroups 32 -</programlisting></para> -<para><programlisting> typedef struct { - char name[XkbKeyNameLength]; /* symbolic key names */ -} <emphasis>XkbKeyNameRec</emphasis>,*XkbKeyNamePtr; -</programlisting></para> + char name[XkbKeyNameLength]; /* symbolic key names */ +} <structname>XkbKeyNameRec</structname>, *XkbKeyNamePtr; -<para><programlisting> typedef struct { - char real[XkbKeyNameLength]; - /* this key name must be in the keys array */ - char alias[XkbKeyNameLength]; - /* symbolic key name as alias for the key */ -} <emphasis>XkbKeyAliasRec</emphasis>,*XkbKeyAliasPtr; -</programlisting></para> + char real[XkbKeyNameLength]; + /* this key name must be in the keys array */ + char alias[XkbKeyNameLength]; + /* symbolic key name as alias for the key */ +} <structname>XkbKeyAliasRec</structname>, *XkbKeyAliasPtr; -<para><programlisting> typedef struct _XkbNamesRec { - Atom keycodes; /* identifies range and meaning of keycodes */ - Atom geometry; /* identifies physical location, size, and shape of keys */ - Atom symbols; /* identifies the symbols logically bound to the keys */ - Atom types; /* identifies the set of key types */ - Atom compat; /* identifies actions for keys using core protocol */ - Atom vmods[XkbNumVirtualMods]; /* symbolic names for virtual modifiers */ - Atom indicators[XkbNumIndicators]; /* symbolic names for indicators */ - Atom groups[XkbNumKbdGroups]; /* symbolic names for keyboard groups */ - XkbKeyNamePtr keys; /* symbolic key name array */ - XkbKeyAliasPtr key_aliases; /* real/alias symbolic name pairs array */ - Atom * radio_groups; /* radio group name array */ - Atom phys_symbols; /* identifies the symbols engraved on the keyboard */ - unsigned char num_keys; /* number of keys in the <emphasis> keys</emphasis> array */ - unsigned char num_key_aliases; /* number of keys in the - <emphasis> key_aliases</emphasis> array */ - unsigned short num_rg; /* number of radio groups */ -} <emphasis>XkbNamesRec</emphasis>,*XkbNamesPtr; /* + Atom keycodes; /* identifies range and meaning + of keycodes */ + Atom geometry; /* identifies physical location, + size, and shape of keys */ + Atom symbols; /* identifies the symbols logically + bound to the keys */ + Atom types; /* identifies the set of key types */ + Atom compat; /* identifies actions for keys using + core protocol */ + Atom vmods[XkbNumVirtualMods]; /* symbolic names for + virtual modifiers */ + Atom indicators[XkbNumIndicators]; /* symbolic names + for indicators */ + Atom groups[XkbNumKbdGroups]; /* symbolic names for + keyboard groups */ + XkbKeyNamePtr keys; /* symbolic key name array */ + XkbKeyAliasPtr key_aliases; /* real/alias symbolic name pairs array */ + Atom * radio_groups; /* radio group name array */ + Atom phys_symbols; /* identifies the symbols engraved + on the keyboard */ + unsigned char num_keys; /* number of keys in the <structfield>keys</structfield> array */ + unsigned char num_key_aliases; /* number of keys in the + <structfield>key_aliases</structfield> array */ + unsigned short num_rg; /* number of radio groups */ +} <structname>XkbNamesRec</structname>, *XkbNamesPtr; </programlisting></para> <para> -The <emphasis> -keycodes</emphasis> - name identifies the range and meaning of the keycodes returned by the keyboard -in question. The <emphasis> -geometry</emphasis> - name, on the other hand, identifies the physical location, size and shape of +The +<structfield>keycodes</structfield> +name identifies the range and meaning of the keycodes returned by the keyboard +in question. The +<structfield>geometry</structfield> +name, on the other hand, identifies the physical location, size and shape of the various keys on the keyboard. As an example to distinguish between these two names, consider function keys on PC-compatible keyboards. Function keys are sometimes above the main keyboard and sometimes to the left of the main @@ -96,36 +105,35 @@ similar keycodes name but may have different geometry names. the keycodes returned by a keyboard; a single keycodes name might cover keyboards with differing numbers of keys provided all keys have the same semantics when present. For example, 101 and 102 key PC keyboards might use the -same name. In these cases, applications can use the keyboard <emphasis> -geometry</emphasis> - name to determine which subset of the named keycodes is in use.</para></note> +same name. In these cases, applications can use the keyboard +<structfield>geometry</structfield> +name to determine which subset of the named keycodes is in use.</para></note> <para> -The <emphasis> -symbols</emphasis> - name identifies the symbols logically bound to the keys. The symbols name is a +The +<structfield>symbols</structfield> +name identifies the symbols logically bound to the keys. The symbols name is a human or application-readable description of the intended locale or usage of -the keyboard with these symbols. The <emphasis> -phys_symbols</emphasis> - name, on the other hand, identifies the symbols actually engraved on the -keyboard. Given this, the <emphasis> -symbols</emphasis> - name and <emphasis> -phys_symbols</emphasis> - names might be different. For example, the description for a keyboard that has +the keyboard with these symbols. The +<structfield>phys_symbols</structfield> +name, on the other hand, identifies the symbols actually engraved on the +keyboard. Given this, the +<structfield>symbols</structfield> +name and +<structfield>phys_symbols</structfield> +names might be different. For example, the description for a keyboard that has English US engravings, but that is using Swiss German symbols might have a -<emphasis> -phys_symbols</emphasis> - name of "en_US" and a <emphasis> -symbols</emphasis> - name of "de_CH." +<structfield>phys_symbols</structfield> +name of "en_US" and a +<structfield>symbols</structfield> +name of "de_CH." </para> <para> -The <emphasis> -types</emphasis> - name provides some information about the set of key types (see section 15.2) +The +<structfield>types</structfield> +name provides some information about the set of key types (see <link linkend="Key_Types">section 15.2</link>) that can be associated with the keyboard. In addition, each key type can have a name, and each shift level of a type can have a name. Although these names are stored in the map description with each of the types, they are accessed using @@ -134,9 +142,9 @@ the same methods as the other symbolic names. <para> -The <emphasis> -compat</emphasis> - name provides some information about the rules used to bind actions to keys +The +<structfield>compat</structfield> +name provides some information about the rules used to bind actions to keys that are changed using core protocol requests. </para> @@ -144,27 +152,26 @@ that are changed using core protocol requests. <para> Xkb provides symbolic names for each of the 4 keyboard groups, 16 virtual modifiers, 32 keyboard indicators, and 4 keyboard groups. These names are held -in the <emphasis> -vmods</emphasis> -, <emphasis> -indicators</emphasis> -, and <emphasis> -groups</emphasis> - fixed-length arrays. +in the +<structfield>vmods</structfield>, +<structfield>indicators</structfield>, +and +<structfield>groups</structfield> +fixed-length arrays. </para> <para> Each key has a four-byte symbolic name. All of the symbolic key names are held -in the <emphasis> -keys</emphasis> - array, and <emphasis> -num_keys</emphasis> - reports the number of entries that are in the keys array. For each key, the +in the +<structfield>keys</structfield> +array, and +<structfield>num_keys</structfield> +reports the number of entries that are in the keys array. For each key, the key name links keys with similar functions or in similar positions on keyboards -that report different keycodes. For example, the <emphasis> -F1</emphasis> - key may emit keycode 23 on one keyboard and keycode 86 on another. By naming +that report different keycodes. For example, the +<keycap>F1</keycap> +key may emit keycode 23 on one keyboard and keycode 86 on another. By naming this key "FK01" on both keyboards, the keyboard layout designer can reuse parts of keyboard descriptions for different keyboards. </para> @@ -173,37 +180,38 @@ of keyboard descriptions for different keyboards. <para> Key aliases allow the keyboard layout designer to assign multiple key names to a single key. This allows the keyboard layout designer to refer to keys using -either their position or their "function." For example, a keyboard layout +either their position or their <quote>function</quote>. +For example, a keyboard layout designer may wish to refer to the left arrow key on a PC keyboard using the ISO9995-5 positional specification of A31 or using the functional specification -of LEFT. The <emphasis> -key_aliases</emphasis> - field holds a variable-length array of real and alias key name pairs, and the -total number of entries in the <emphasis> -key_aliases</emphasis> - array is held in <emphasis> -num_key_aliases</emphasis> -. For each real and alias key name pair, the <emphasis> -real</emphasis> - field refers to the a name in the keys array, and the <emphasis> -alias</emphasis> - field refers to the alias for that key. Using the previous example, the +of LEFT. The +<structfield>key_aliases</structfield> +field holds a variable-length array of real and alias key name pairs, and the +total number of entries in the +<structfield>key_aliases</structfield> +array is held in +<structfield>num_key_aliases</structfield>. +For each real and alias key name pair, the +<structfield>real</structfield> +field refers to the a name in the keys array, and the +<structfield>alias</structfield> +field refers to the alias for that key. Using the previous example, the keyboard designer may use the name A31 in the keys array, but also define the -name LEFT as an alias for A31 in the <emphasis> -key_aliases</emphasis> - array. +name LEFT as an alias for A31 in the +<structfield>key_aliases</structfield> +array. </para> <note><para>Key aliases defined in the geometry component of a keyboard mapping -(see Chapter 13) override those defined in the keycodes component of the server -database, which are stored in the <emphasis> -XkbNamesRec</emphasis> - (<emphasis> -xkb->names</emphasis> -). Therefore, consider the key aliases defined by the geometry before -considering key aliases supplied by the <emphasis> -XkbNamesRec</emphasis> -.</para></note> +(see <xref linkend="Keyboard_Geometry" />) override those defined in the keycodes component of the server +database, which are stored in the +<structname>XkbNamesRec</structname> + +(<structfield>xkb->names</structfield>). +Therefore, consider the key aliases defined by the geometry before +considering key aliases supplied by the +<structname>XkbNamesRec</structname>. +</para></note> <para> A radio group is a set of keys whose behavior simulates a set of radio buttons. @@ -216,13 +224,13 @@ be logically depressed at one time. <para> Each radio group in the keyboard description can have a name. These names are -held in the variable-length array <emphasis> -radio_groups</emphasis> -, and <emphasis> -num_rg</emphasis> - tells how many elements are in the <emphasis> -radio_groups</emphasis> - array. +held in the variable-length array +<structfield>radio_groups</structfield>, +and +<structfield>num_rg</structfield> +tells how many elements are in the +<structfield>radio_groups</structfield> +array. </para> @@ -234,10 +242,10 @@ radio_groups</emphasis> Xkb provides several functions that work with symbolic names. Each of these functions uses a mask to specify individual fields of the structures described above. These masks and their relationships to the fields in a keyboard -description are shown in Table 18.1. +description are shown in <link linkend="table18.1">Table 18.1</link>. </para> -<table frame='topbot'> +<table id='table18.1' frame='topbot'> <title>Symbolic Names Masks</title> <?dbfo keep-together="always" ?> <tgroup cols='4' align='left' colsep='0' rowsep='0'> @@ -255,91 +263,91 @@ description are shown in Table 18.1. </thead> <tbody> <row> - <entry>XkbKeycodesNameMask</entry> + <entry><symbol>XkbKeycodesNameMask</symbol></entry> <entry>(1<<0)</entry> <entry>Xkb->names</entry> <entry>keycodes</entry> </row> <row> - <entry>XkbGeometryNameMask</entry> + <entry><symbol>XkbGeometryNameMask</symbol></entry> <entry>(1<<1)</entry> <entry>Xkb->names</entry> <entry>geometry</entry> </row> <row> - <entry>XkbSymbolsNameMask</entry> + <entry><symbol>XkbSymbolsNameMask</symbol></entry> <entry>(1<<2)</entry> <entry>Xkb->names</entry> <entry>symbols</entry> </row> <row> - <entry>XkbPhysSymbolsNameMask</entry> + <entry><symbol>XkbPhysSymbolsNameMask</symbol></entry> <entry>(1<<3)</entry> <entry>Xkb->names</entry> <entry>phys_symbols</entry> </row> <row> - <entry>XkbTypesNameMask</entry> + <entry><symbol>XkbTypesNameMask</symbol></entry> <entry>(1<<4)</entry> <entry>Xkb->names</entry> <entry>type</entry> </row> <row> - <entry>XkbCompatNameMask</entry> + <entry><symbol>XkbCompatNameMask</symbol></entry> <entry>(1<<5)</entry> <entry>Xkb->names</entry> <entry>compat</entry> </row> <row> - <entry>XkbKeyTypeNamesMask</entry> + <entry><symbol>XkbKeyTypeNamesMask</symbol></entry> <entry>(1<<6)</entry> <entry>Xkb->map</entry> <entry>type[*].name</entry> </row> <row> - <entry>XkbKTLevelNamesMask</entry> + <entry><symbol>XkbKTLevelNamesMask</symbol></entry> <entry>(1<<7)</entry> <entry>Xkb->map</entry> <entry>type[*].lvl_names[*]</entry> </row> <row> - <entry>XkbIndicatorNamesMask</entry> + <entry><symbol>XkbIndicatorNamesMask</symbol></entry> <entry>(1<<8)</entry> <entry>Xkb->names</entry> <entry>indicators[*]</entry> </row> <row> - <entry>XkbKeyNamesMask</entry> + <entry><symbol>XkbKeyNamesMask</symbol></entry> <entry>(1<<9)</entry> <entry>Xkb->names</entry> <entry>keys[*], num_keys</entry> </row> <row> - <entry>XkbKeyAliasesMask</entry> + <entry><symbol>XkbKeyAliasesMask</symbol></entry> <entry>(1<<10)</entry> <entry>Xkb->names</entry> <entry>key_aliases[*], num_key_aliases</entry> </row> <row> - <entry>XkbVirtualModNamesMask</entry> + <entry><symbol>XkbVirtualModNamesMask</symbol></entry> <entry>(1<<11)</entry> <entry>Xkb->names</entry> <entry>vmods[*]</entry> </row> <row> - <entry>XkbGroupNamesMask</entry> + <entry><symbol>XkbGroupNamesMask</symbol></entry> <entry>(1<<12)</entry> <entry>Xkb->names</entry> <entry>groups[*]</entry> </row> <row> - <entry>XkbRGNamesMask</entry> + <entry><symbol>XkbRGNamesMask</symbol></entry> <entry>(1<<13)</entry> <entry>Xkb->names</entry> <entry>radio_groups[*], num_rg</entry> </row> <row> - <entry>XkbComponentNamesMask</entry> + <entry><symbol>XkbComponentNamesMask</symbol></entry> <entry>(0x3f)</entry> <entry>Xkb->names</entry> <entry> @@ -352,7 +360,7 @@ description are shown in Table 18.1. </entry> </row> <row> - <entry>XkbAllNamesMask</entry> + <entry><symbol>XkbAllNamesMask</symbol></entry> <entry>(0x3fff)</entry> <entry>Xkb->names</entry> <entry>all name components</entry> @@ -366,133 +374,129 @@ description are shown in Table 18.1. <title>Getting Symbolic Names From the Server</title> <para> -To obtain symbolic names from the server, use <emphasis> -XkbGetNames</emphasis> -. +To obtain symbolic names from the server, use +<function>XkbGetNames</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetNames</emphasis> -(<emphasis> -dpy, which, Xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -which</emphasis> -; /* mask of names or map components to be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> - /* keyboard description to be updated */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbGetNames"><primary><function>XkbGetNames</function></primary></indexterm> +<funcsynopsis id="XkbGetNames"> + <funcprototype> + <funcdef>Status <function>XkbGetNames</function></funcdef> +<!-- ( +<parameter>dpy, which, Xkb</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of names or map components to be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description to be updated + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbGetNames</emphasis> - retrieves symbolic names for the components of the keyboard extension from the -X server. The <emphasis> -which</emphasis> - parameter specifies the name components to be updated in the <emphasis> -xkb</emphasis> - parameter, and is the bitwise inclusive OR of the valid names mask bits -defined in Table 18.1. +<function>XkbGetNames</function> +retrieves symbolic names for the components of the keyboard extension from the +X server. The +<parameter>which</parameter> +parameter specifies the name components to be updated in the +<parameter>xkb</parameter> +parameter, and is the bitwise inclusive OR of the valid names mask bits +defined in <link linkend="table18.1">Table 18.1</link>. </para> <para> -If the <emphasis> -names</emphasis> - field of the keyboard description <emphasis> -xkb</emphasis> - is <emphasis> -NULL</emphasis> -, <emphasis> -XkbGetNames</emphasis> - allocates and initializes the <emphasis> -names</emphasis> - component of the keyboard description before obtaining the values specified by -<emphasis> -which</emphasis> -. If the <emphasis> -names</emphasis> - field of <emphasis> -xkb</emphasis> - is not <emphasis> -NULL</emphasis> -, <emphasis> -XkbGetNames</emphasis> - obtains the values specified by <emphasis> -which</emphasis> - and copies them into the keyboard description <emphasis> -Xkb</emphasis> -. +If the +<structfield>names</structfield> +field of the keyboard description +<parameter>xkb</parameter> +is +<symbol>NULL</symbol>, +<function>XkbGetNames</function> +allocates and initializes the +<structfield>names</structfield> +component of the keyboard description before obtaining the values specified by +<parameter>which</parameter>. +If the +<structfield>names</structfield> +field of +<parameter>xkb</parameter> +is not +<symbol>NULL</symbol>, +<function>XkbGetNames</function> +obtains the values specified by +<parameter>which</parameter> +and copies them into the keyboard description +<parameter>xkb</parameter>. </para> <para> -If the <emphasis> -map</emphasis> - component of the <emphasis> -xkb</emphasis> - parameter is <emphasis> -NULL</emphasis> -, <emphasis> -XkbGetNames</emphasis> - does not retrieve type or shift level names, even if <emphasis> -XkbKeyTypeNamesMask</emphasis> - or <emphasis> -XkbKTLevelNamesMask</emphasis> - are set in <emphasis> -which</emphasis> -. +If the +<structfield>map</structfield> +component of the +<parameter>xkb</parameter> +parameter is +<symbol>NULL</symbol>, +<function>XkbGetNames</function> +does not retrieve type or shift level names, even if +<symbol>XkbKeyTypeNamesMask</symbol> +or +<symbol>XkbKTLevelNamesMask</symbol> +are set in +<parameter>which</parameter>. </para> <para> -<emphasis> -XkbGetNames</emphasis> - can return <emphasis> -Success</emphasis> -, or <emphasis> -BadAlloc</emphasis> -, <emphasis> -BadLength</emphasis> -, <emphasis> -BadMatch</emphasis> -, and <emphasis> -BadImplementation</emphasis> - errors. +<function>XkbGetNames</function> +can return +<symbol>Success</symbol>, +or +<errorname>BadAlloc</errorname>, +<errorname>BadLength</errorname>, +<errorname>BadMatch</errorname>, +and +<errorname>BadImplementation</errorname> +errors. </para> <para> -To free symbolic names, use <emphasis> -XkbFreeNames</emphasis> - (see section 18.6) +To free symbolic names, use +<function>XkbFreeNames</function> +(see <link linkend="Allocating_and_Freeing_Symbolic_Names">section 18.6</link>) </para> @@ -502,122 +506,133 @@ XkbFreeNames</emphasis> <para> To change the symbolic names in the server, first modify a local copy of the -keyboard description and then use either <emphasis> -XkbSetNames,</emphasis> - or, to save network traffic, use a <emphasis> -XkbNameChangesRec</emphasis> -structure and call <emphasis> -XkbChangeNames</emphasis> - to download the changes to the server. <emphasis> -XkbSetNames</emphasis> - and <emphasis> -XkbChangeNames</emphasis> - can generate <emphasis> -BadAlloc</emphasis> -, <emphasis> -BadAtom</emphasis> -, <emphasis> -BadLength</emphasis> -, <emphasis> -BadMatch,</emphasis> - and <emphasis> -BadImplementation</emphasis> - errors. +keyboard description and then use either +<function>XkbSetNames</function>, +or, to save network traffic, use a +<structname>XkbNameChangesRec</structname> +structure and call +<function>XkbChangeNames</function> +to download the changes to the server. +<function>XkbSetNames</function> +and +<function>XkbChangeNames</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadAtom</errorname>, +<errorname>BadLength</errorname>, +<errorname>BadMatch</errorname>, +and +<errorname>BadImplementation</errorname> +errors. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetNames</emphasis> -(<emphasis> -dpy, which, first_type, num_types, xkb</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -which</emphasis> -; /* mask of names or map components to be changed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -first_type</emphasis> - ; /* first type whose name is to be changed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -num_types</emphasis> -; /* number of types for which names are to be changed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description from which names are to be taken */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbSetNames"><primary><function>XkbSetNames</function></primary></indexterm> +<funcsynopsis id="XkbSetNames"> + <funcprototype> + <funcdef>Bool <function>XkbSetNames</function></funcdef> +<!-- ( +<parameter>dpy, which, first_type, num_types, xkb</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>unsigned int <parameter>first_type</parameter></paramdef> + <paramdef>unsigned int <parameter>num_types</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of names or map components to be changed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first_type</parameter> + </term> + <listitem> + <para> + first type whose name is to be changed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_types</parameter> + </term> + <listitem> + <para> + number of types for which names are to be changed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description from which names are to be taken + </para> + </listitem> + </varlistentry> +</variablelist> <para> -Use<emphasis> - XkbSetNames</emphasis> - to change many names at the same time. For each bit set in <emphasis> -which</emphasis> -, <emphasis> -XkbSetNames</emphasis> - takes the corresponding value (or values in the case of arrays) from the -keyboard description <emphasis> -xkb</emphasis> - and sends it to the server. +Use +<function>XkbSetNames</function> +to change many names at the same time. For each bit set in +<parameter>which</parameter>, +<function>XkbSetNames</function> +takes the corresponding value (or values in the case of arrays) from the +keyboard description +<parameter>xkb</parameter> +and sends it to the server. </para> <para> -The <emphasis> -first_type</emphasis> - and <emphasis> -num_types</emphasis> - arguments are used only if <emphasis> -XkbKeyTypeNamesMask</emphasis> - or <emphasis> -XkbKTLevelNamesMask</emphasis> - is set in <emphasis> -which</emphasis> - and specify a subset of the types for which the corresponding names are to be +The +<parameter>first_type</parameter> +and +<parameter>num_types</parameter> +arguments are used only if +<symbol>XkbKeyTypeNamesMask</symbol> +or +<symbol>XkbKTLevelNamesMask</symbol> +is set in +<parameter>which</parameter> +and specify a subset of the types for which the corresponding names are to be changed. If either or both of these mask bits are set but the specified types -are illegal, <emphasis> -XkbSetNames</emphasis> - returns <emphasis> -False</emphasis> - and does not update any of the names specified in <emphasis> -which</emphasis> -. The specified types are illegal if <emphasis> -xkb</emphasis> - does not include a map component or if <emphasis> -first_type</emphasis> - and <emphasis> -num_types</emphasis> - specify types that are not defined in the keyboard description. +are illegal, +<function>XkbSetNames</function> +returns +<symbol>False</symbol> +and does not update any of the names specified in +<parameter>which</parameter>. +The specified types are illegal if +<parameter>xkb</parameter> +does not include a map component or if +<parameter>first_type</parameter> +and +<parameter>num_types</parameter> +specify types that are not defined in the keyboard description. </para> @@ -626,52 +641,52 @@ num_types</emphasis> <sect3 id='The_XkbNameChangesRec_Structure'> <title>The XkbNameChangesRec Structure</title> +<indexterm significance="preferred" zone="The_XkbNameChangesRec_Structure"> +<primary><structname>XkbNameChangesRec</structname></primary></indexterm> <para> -The <emphasis> -XkbNameChangesRec</emphasis> - allows applications to identify small modifications to the symbolic names and +The +<structname>XkbNameChangesRec</structname> +allows applications to identify small modifications to the symbolic names and effectively reduces the amount of traffic sent to the server: -</para> -<para><programlisting> +<programlisting> typedef struct _XkbNameChanges { - unsigned int changed; /* name components that have - changed */ - unsigned char first_type; /* first key type with a new - name */ - unsigned char num_types; /* number of types with new - names */ - unsigned char first_lvl; /* first key type with new level - names */ - unsigned char num_lvls; /* number of key types with new - level names */ - unsigned char num_aliases; /* if key aliases changed, - total number of key aliases */ - unsigned char num_rg; /* if radio groups changed, total - number of radio groups */ - unsigned char first_key; /* first key with a new name */ - unsigned char num_keys; /* number of keys with new names - */ - unsigned short changed_vmods; /* mask of virtual - modifiers for which names have changed */ - unsigned long changed_indicators; /* mask of indicators - for which names were changed */ - unsigned char changed_groups; /* mask of groups for - which names were changed */ -} <emphasis>XkbNameChangesRec</emphasis>, *XkbNameChangesPtr + unsigned int changed; /* name components that have + changed */ + unsigned char first_type; /* first key type with a new name */ + unsigned char num_types; /* number of types with new names */ + unsigned char first_lvl; /* first key type with new level + names */ + unsigned char num_lvls; /* number of key types with new + level names */ + unsigned char num_aliases; /* if key aliases changed, + total number of key aliases */ + unsigned char num_rg; /* if radio groups changed, total + number of radio groups */ + unsigned char first_key; /* first key with a new name */ + unsigned char num_keys; /* number of keys with new names */ + unsigned short changed_vmods; /* mask of virtual modifiers + for which names have changed */ + unsigned long changed_indicators; /* mask of indicators + for which names were changed */ + unsigned char changed_groups; /* mask of groups for + which names were changed */ +} <structname>XkbNameChangesRec</structname>, *XkbNameChangesPtr; </programlisting></para> <para> -The <emphasis> -changed</emphasis> - field specifies the name components that have changed and is the bitwise -inclusive OR of the valid names mask bits defined in Table 18.1. The rest of +The +<structfield>changed</structfield> +field specifies the name components that have changed and is the bitwise +inclusive OR of the valid names mask bits defined in +<link linkend="table18.1">Table 18.1</link>. The rest of the fields in the structure specify the ranges that have changed for the -various kinds of symbolic names, as shown in Table 18.2. +various kinds of symbolic names, as shown in +<link linkend="table18.2">Table 18.2</link>. </para> -<table frame='topbot'> +<table id='table18.2' frame='topbot'> <title>XkbNameChanges Fields</title> <?dbfo keep-together="always" ?> <tgroup cols='4' align='left' colsep='0' rowsep='0'> @@ -689,7 +704,7 @@ various kinds of symbolic names, as shown in Table 18.2. </thead> <tbody> <row> - <entry>XkbKeyTypeNamesMask</entry> + <entry><symbol>XkbKeyTypeNamesMask</symbol></entry> <entry> <para>first_type,</para> <para>num_types</para> @@ -698,7 +713,7 @@ various kinds of symbolic names, as shown in Table 18.2. <entry>type[*].name</entry> </row> <row> - <entry>XkbKTLevelNamesMask</entry> + <entry><symbol>XkbKTLevelNamesMask</symbol></entry> <entry> <para>first_lvl,</para> <para>num_lvls</para> @@ -707,19 +722,19 @@ various kinds of symbolic names, as shown in Table 18.2. <entry>type[*].lvl_names[*]</entry> </row> <row> - <entry>XkbKeyAliasesMask</entry> + <entry><symbol>XkbKeyAliasesMask</symbol></entry> <entry>num_aliases</entry> <entry>Xkb->names</entry> <entry>key_aliases[*]</entry> </row> <row> - <entry>XkbRGNamesMask</entry> + <entry><symbol>XkbRGNamesMask</symbol></entry> <entry>num_rg</entry> <entry>Xkb->names</entry> <entry>radio_groups[*]</entry> </row> <row> - <entry>XkbKeyNamesMask</entry> + <entry><symbol>XkbKeyNamesMask</symbol></entry> <entry> <para>first_key,</para> <para>num_keys</para> @@ -728,19 +743,19 @@ various kinds of symbolic names, as shown in Table 18.2. <entry>keys[*]</entry> </row> <row> - <entry>XkbVirtualModNamesMask</entry> + <entry><symbol>XkbVirtualModNamesMask</symbol></entry> <entry>changed_vmods</entry> <entry>Xkb->names</entry> <entry>vmods[*]</entry> </row> <row> - <entry>XkbIndicatorNamesMask</entry> + <entry><symbol>XkbIndicatorNamesMask</symbol></entry> <entry>changed_indicators</entry> <entry>Xkb->names</entry> <entry>indicators[*]</entry> </row> <row> - <entry>XkbGroupNamesMask</entry> + <entry><symbol>XkbGroupNamesMask</symbol></entry> <entry>changed_groups</entry> <entry>Xkb->names</entry> <entry>groups[*]</entry> @@ -750,70 +765,73 @@ various kinds of symbolic names, as shown in Table 18.2. </table> <para> -<emphasis> -XkbChangeNames</emphasis> - provides a more flexible method for changing symbolic names than <emphasis> -XkbSetNames</emphasis> - and requires the use of an <emphasis> -XkbNameChangesRec</emphasis> - structure. +<function>XkbChangeNames</function> +provides a more flexible method for changing symbolic names than +<function>XkbSetNames</function> +and requires the use of an +<structname>XkbNameChangesRec</structname> +structure. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbChangeNames</emphasis> -(<emphasis> -dpy, xkb, changes</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* keyboard description from which names are to be taken */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbNameChangesPtr <emphasis> - changes</emphasis> -; /* names map components to be updated on the server */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbChangeNames"><primary><function>XkbChangeNames</function></primary></indexterm> +<funcsynopsis id="XkbChangeNames"> + <funcprototype> + <funcdef>Bool <function>XkbChangeNames</function></funcdef> +<!-- ( +<parameter>dpy, xkb, changes</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>XkbNameChangesPtr <parameter>changes</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description from which names are to be taken + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + names map components to be updated on the server + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbChangeNames</emphasis> - copies any names specified by <emphasis> -changes</emphasis> - from the keyboard description, <emphasis> -xkb</emphasis> -, to the X server specified by <emphasis> -dpy</emphasis> -.<emphasis> - XkbChangeNames</emphasis> - aborts and returns <emphasis> -False</emphasis> - if any illegal type names or type shift level names are specified by <emphasis> -changes</emphasis> -. +<function>XkbChangeNames</function> +copies any names specified by +<parameter>changes</parameter> +from the keyboard description, +<parameter>xkb</parameter>, +to the X server specified by +<parameter>dpy</parameter>. +<function>XkbChangeNames</function> +aborts and returns +<symbol>False</symbol> +if any illegal type names or type shift level names are specified by +<parameter>changes</parameter>. </para> </sect3> @@ -821,232 +839,236 @@ changes</emphasis> </sect1> <sect1 id='Tracking_Name_Changes'> <title>Tracking Name Changes</title> +<indexterm significance="preferred" zone="Tracking_Name_Changes"> +<primary>events</primary><secondary><symbol>XkbNamesNotify</symbol></secondary></indexterm> +<indexterm significance="preferred" zone="Tracking_Name_Changes"> +<primary><structname>XkbNamesNotifyEvent</structname></primary></indexterm> <para> Whenever a symbolic name changes in the server’s keyboard description, the -server sends a <emphasis> -XkbNamesNotify</emphasis> - event to all interested clients. To receive name notify events, use <emphasis> -XkbSelectEvents</emphasis> - (see section 4.3) with <emphasis> -XkbNamesNotifyMask</emphasis> - in both the <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> - parameters. +server sends a +<symbol>XkbNamesNotify</symbol> +event to all interested clients. To receive name notify events, use +<function>XkbSelectEvents</function> +(see <link linkend="Selecting_Xkb_Events">section 4.3</link>) with +<symbol>XkbNamesNotifyMask</symbol> +in both the +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +parameters. </para> <para> -To receive events for only specific names, use <emphasis> -XkbSelectEventDetails</emphasis> -. Set the <emphasis> -event_type</emphasis> - parameter to <emphasis> -XkbNamesNotify</emphasis> -, and set both the <emphasis> -bits_to_change </emphasis> -and<emphasis> - values_for_bits</emphasis> - detail parameter to a mask composed of a bitwise OR of masks in Table 18.1. +To receive events for only specific names, use +<function>XkbSelectEventDetails</function>. +Set the +<structfield>event_type</structfield> +parameter to +<symbol>XkbNamesNotify</symbol>, +and set both the +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +detail parameter to a mask composed of a bitwise OR of masks in +<link linkend="table18.1">Table 18.1</link>. </para> <para> -The structure for the <emphasis> -XkbNamesNotify</emphasis> - event is defined as follows: -</para> +The structure for the +<symbol>XkbNamesNotify</symbol> +event is defined as follows: -<para><programlisting> +<programlisting> typedef struct { - int type; /* Xkb extension base event code */ - unsigned long serial; /* X server serial number for - event */ - Bool send_event; /* <emphasis>True</emphasis> - => synthetically generated */ - Display * display; /* server connection where event - generated */ - Time time; /* server time when event generated */ - int xkb_type; /* <emphasis>XkbNamesNotify</emphasis> */ - int device; /* Xkb device ID, will not be - <emphasis>XkbUseCoreKbd</emphasis> */ - unsigned int changed; /* mask of name components -that have changed */ - int first_type; /* first key type with a new name */ - int num_types; /* number of types with new names */ - int first_lvl; /* first key type with new level names */ - int num_lvls; /* number of key types with new level names */ - int num_aliases; /* if key aliases changed, total number - of key aliases */ - int num_radio_groups; /* if radio groups changed, + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* <symbol>True</symbol> ⇒ synthetically generated */ + Display * display; /* server connection where event generated */ + Time time; /* server time when event generated */ + int xkb_type; /* <symbol>XkbNamesNotify</symbol> */ + int device; /* Xkb device ID, will not be + <symbol>XkbUseCoreKbd</symbol> */ + unsigned int changed; /* mask of name components + that have changed */ + int first_type; /* first key type with a new name */ + int num_types; /* number of types with new names */ + int first_lvl; /* first key type with new level names */ + int num_lvls; /* number of key types with new level names */ + int num_aliases; /* if key aliases changed, total number + of key aliases */ + int num_radio_groups; /* if radio groups changed, total number of radio groups */ - unsigned int changed_vmods; /* mask of virtual modifiers for - which names have changed */ - unsigned int changed_groups; /* mask of groups for - which names were changed */ - unsigned int changed_indicators; /* mask of indicators for which - names were changed */ - int first_key; /* first key with a new name */ - int num_keys; /* number of keys with new names */ -} <emphasis>XkbNamesNotifyEvent</emphasis>; + unsigned int changed_vmods; /* mask of virtual modifiers for + which names have changed */ + unsigned int changed_groups; /* mask of groups for + which names were changed */ + unsigned int changed_indicators; /* mask of indicators for which + names were changed */ + int first_key; /* first key with a new name */ + int num_keys; /* number of keys with new names */ +} <structname>XkbNamesNotifyEvent</structname>; </programlisting></para> <para> -The <emphasis> -changed</emphasis> - field specifies the name components that have changed and is the bitwise -inclusive OR of the valid names mask bits defined in Table 18.1. The other -fields in this event are interpreted as the like-named fields in an <emphasis> -XkbNameChangesRec</emphasis> , as previously defined. +The +<structfield>changed</structfield> +field specifies the name components that have changed and is the bitwise +inclusive OR of the valid names mask bits defined in +<link linkend="table18.1">Table 18.1</link>. The other +fields in this event are interpreted as the like-named fields in an +<structname>XkbNameChangesRec</structname> , as previously defined. </para> <para> -When your application receives a X<emphasis> -kbNamesNotify</emphasis> - event, you can note the changed names in a changes structure using <emphasis> -XkbNoteNameChanges</emphasis> -. +When your application receives a +<symbol>XkbNamesNotify</symbol> +event, you can note the changed names in a changes structure using +<function>XkbNoteNameChanges</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbNoteNameChanges</emphasis> -(<emphasis> -old</emphasis> -,<emphasis> - new</emphasis> -,<emphasis> - wanted</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbNameChangesPtr <emphasis> -old</emphasis> -; /* <emphasis> -XkbNameChanges</emphasis> - structure to be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbNamesNotifyEvent * <emphasis> -new</emphasis> -; /* event from which changes are to be copied */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -wanted</emphasis> -; /* types of names for which changes are to be noted */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbNoteNameChanges"><primary><function>XkbNoteNameChanges</function></primary></indexterm> +<funcsynopsis id="XkbNoteNameChanges"> + <funcprototype> + <funcdef>void <function>XkbNoteNameChanges</function></funcdef> +<!-- ( +<parameter>old</parameter>, +<parameter>new</parameter>, +<parameter>wanted</parameter> +) --> + + <paramdef>XkbNameChangesPtr <parameter>old</parameter></paramdef> + <paramdef>XkbNamesNotifyEvent *<parameter>new</parameter></paramdef> + <paramdef>unsigned int <parameter>wanted</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>old</parameter> + </term> + <listitem> + <para> + <structname>XkbNameChangesRec</structname> structure to be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>new</parameter> + </term> + <listitem> + <para> + event from which changes are to be copied + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>wanted</parameter> + </term> + <listitem> + <para> + types of names for which changes are to be noted + </para> + </listitem> + </varlistentry> +</variablelist> <para> -The <emphasis> -wanted</emphasis> - parameter is the bitwise inclusive OR of the valid names mask bits shown in -Table 18.1. <emphasis> -XkbNoteNameChanges</emphasis> - copies any changes that are reported in <emphasis> -new</emphasis> - and specified in <emphasis> -wanted</emphasis> - into the changes record specified by <emphasis> -old</emphasis> -. +The +<parameter>wanted</parameter> +parameter is the bitwise inclusive OR of the valid names mask bits shown in +<link linkend="table18.1">Table 18.1</link>. +<function>XkbNoteNameChanges</function> +copies any changes that are reported in +<parameter>new</parameter> +and specified in +<parameter>wanted</parameter> +into the changes record specified by +<parameter>old</parameter>. </para> <para> To update the local copy of the keyboard description with the actual values, -pass to <emphasis> -XkbGetNameChanges</emphasis> - the results of one or more calls to <emphasis> -XkbNoteNameChanges</emphasis> -. +pass to +<function>XkbGetNameChanges</function> +the results of one or more calls to +<function>XkbNoteNameChanges</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetNameChanges</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - xkb</emphasis> -,<emphasis> - changes</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description to which names are copied */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbNameChangesPtr <emphasis> -changes</emphasis> -; /* names components to be obtained from the server */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbGetNameChanges"><primary><function>XkbGetNameChanges</function></primary></indexterm> +<funcsynopsis id="XkbGetNameChanges"> + <funcprototype> + <funcdef>Status <function>XkbGetNameChanges</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>xkb</parameter>, +<parameter>changes</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>XkbNameChangesPtr <parameter>changes</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description to which names are copied + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + names components to be obtained from the server + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbGetNameChanges</emphasis> - examines the <emphasis> -changes</emphasis> - parameter, retrieves the necessary information from the server, and places the -results into the <emphasis> -xkb</emphasis> - keyboard description. +<function>XkbGetNameChanges</function> +examines the +<parameter>changes</parameter> +parameter, retrieves the necessary information from the server, and places the +results into the +<parameter>xkb</parameter> +keyboard description. </para> <para> -<emphasis> -XkbGetNamesChanges</emphasis> - can generate <emphasis> -BadAlloc</emphasis> -, <emphasis> -BadImplementation,</emphasis> - and <emphasis> -BadMatch</emphasis> - errors. +<function>XkbGetNameChanges</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadImplementation</errorname>, +and +<errorname>BadMatch</errorname> +errors. </para> @@ -1056,136 +1078,149 @@ BadMatch</emphasis> <para> Most applications do not need to directly allocate symbolic names structures. -Do not allocate a names structure directly using <emphasis> -malloc</emphasis> - or <emphasis> -Xmalloc</emphasis> - if your application changes the number of key aliases or radio groups or +Do not allocate a names structure directly using +<function>malloc</function> +or +<function>Xmalloc</function> +if your application changes the number of key aliases or radio groups or constructs a symbolic names structure without loading the necessary components -from the X server. Instead use <emphasis> -XkbAllocNames</emphasis> -. +from the X server. Instead use +<function>XkbAllocNames</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocNames</emphasis> -(<emphasis> -xkb, which, num_rg, num_key_aliases)</emphasis> - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb;</emphasis> - /* keyboard description for which names are to be allocated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -which;</emphasis> - /* mask of names to be allocated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -num_rg;</emphasis> - /* total number of radio group names needed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -num_key_aliases;</emphasis> - /* total number of key aliases needed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbAllocNames"><primary><function>XkbAllocNames</function></primary></indexterm> +<funcsynopsis id="XkbAllocNames"> + <funcprototype> + <funcdef>Status <function>XkbAllocNames</function></funcdef> +<!-- ( +<parameter>xkb, which, num_rg, num_key_aliases)</parameter> --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>int <parameter>num_rg</parameter></paramdef> + <paramdef>int <parameter>num_key_aliases</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description for which names are to be allocated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of names to be allocated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_rg</parameter> + </term> + <listitem> + <para> + total number of radio group names needed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_key_aliases</parameter> + </term> + <listitem> + <para> + total number of key aliases needed + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbAllocNames</emphasis> - can return <emphasis> -BadAlloc</emphasis> -, <emphasis> -BadMatch,</emphasis> - and <emphasis> -BadValue</emphasis> - errors.<emphasis> - </emphasis> -The <emphasis> -which</emphasis> - parameter is the bitwise inclusive OR of the valid names mask bits defined in -Table 18.1. +<function>XkbAllocNames</function> +can return +<errorname>BadAlloc</errorname>, +<errorname>BadMatch</errorname>, +and +<errorname>BadValue</errorname> +errors. +The +<parameter>which</parameter> +parameter is the bitwise inclusive OR of the valid names mask bits defined in +<link linkend="table18.1">Table 18.1</link>. </para> <para> -Do not free symbolic names structures directly using <emphasis> -free</emphasis> - or <emphasis> -XFree</emphasis> -. Use <emphasis> -XkbFreeNames</emphasis> - instead. +Do not free symbolic names structures directly using +<function>free</function> +or +<function>XFree</function>. +Use +<function>XkbFreeNames</function> +instead. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeNames</emphasis> -(<emphasis> -xkb, which, free_map)</emphasis> - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description for which names are to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -which</emphasis> -; /* mask of names components to be freed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> -free_map</emphasis> -; /* <emphasis> -True</emphasis> - => XkbNamesRec structure itself should be freed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbFreeNames"><primary><function>XkbFreeNames</function></primary></indexterm> +<funcsynopsis id="XkbFreeNames"> + <funcprototype> + <funcdef>void <function>XkbFreeNames</function></funcdef> +<!-- ( +<parameter>xkb, which, free_map)</parameter> --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>Bool <parameter>free_map</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description for which names are to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of names components to be freed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_map</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> + ⇒ XkbNamesRec structure itself should be freed + </para> + </listitem> + </varlistentry> +</variablelist> <para> -The <emphasis> -which</emphasis> - parameter is the bitwise inclusive OR of the valid names mask bits defined in -Table 18.1. +The +<parameter>which</parameter> +parameter is the bitwise inclusive OR of the valid names mask bits defined in +<link linkend="table18.1">Table 18.1</link>. </para> </sect1> </chapter> diff --git a/libX11/specs/XKB/ch19.xml b/libX11/specs/XKB/ch19.xml index 4b4b0a023..faa62a278 100644 --- a/libX11/specs/XKB/ch19.xml +++ b/libX11/specs/XKB/ch19.xml @@ -1,8 +1,12 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Replacing_a_Keyboard_On_the_Fly'> -<title>Replacing a Keyboard "On the Fly"</title> +<title>Replacing a Keyboard <quote>On the Fly</quote></title> <para> -Some operating system and X server implementations allow "hot plugging" of +Some operating system and X server implementations allow +<quote>hot plugging</quote> of input devices. When using these implementations, input devices can be unplugged and new ones plugged in without restarting the software that is using those devices. There is no provision in the standard X server for notification of @@ -18,11 +22,11 @@ program may also change the X keyboard programmatically. The XChangeKeyboardDevice input extension request allows a client to designate an input extension keyboard device as the X keyboard, in which case the old X keyboard device becomes inaccessible except via the input device extension. In -this case, core protocol <emphasis> -XMappingNotify</emphasis> - and input extension <emphasis> -XChangeDeviceNotify</emphasis> - events are generated to notify all clients that a new keyboard with a new +this case, core protocol +<symbol>MappingNotify</symbol> +and input extension +<symbol>XChangeDeviceNotify</symbol> +events are generated to notify all clients that a new keyboard with a new keymap has been designated. </para> @@ -37,77 +41,75 @@ for the client. <para> -Xkb provides an <emphasis> -XkbNewKeyboardNotify</emphasis> - event that reports a change in keyboard geometry and/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 that loads a new keyboard description. Selecting for <emphasis> -XkbNewKeyboardNotify</emphasis> - events allows Xkb-aware clients to be notified whenever a keyboard change +Xkb provides an +<symbol>XkbNewKeyboardNotify</symbol> +event that reports a change in keyboard geometry and/or the range of supported +keycodes. The server can generate an +<symbol>XkbNewKeyboardNotify</symbol> +event when it detects a new keyboard or in response to an +<function>XkbGetKeyboardByName</function> +request that loads a new keyboard description. Selecting for +<symbol>XkbNewKeyboardNotify</symbol> +events allows Xkb-aware clients to be notified whenever a keyboard change occurs that may affect the keymap. </para> <para> -When a client requests <emphasis> -XkbNewKeyboardNotify</emphasis> - events, the server compares the range of keycodes for the current keyboard to +When a client requests +<symbol>XkbNewKeyboardNotify</symbol> +events, the server compares the range of keycodes for the current keyboard to the range of keycodes that are valid for the client. If they are not the same, -the server immediately sends the client an <emphasis> -XkbNewKeyboardNotify</emphasis> - event. Even if the "new" keyboard is not new to the server, it is new to this -particular client. +the server immediately sends the client an +<symbol>XkbNewKeyboardNotify</symbol> +event. Even if the <quote>new</quote> keyboard is not new to the server, +it is new to this particular client. </para> <para> -When the server sends an <emphasis> -XkbNewKeyboardNotify</emphasis> - event to a client to inform it of a new keycode range, it resets the stored +When the server sends an +<symbol>XkbNewKeyboardNotify</symbol> +event to a client to inform it of a new keycode range, it resets the stored range of legal keycodes for the client to the keycode range reported in the event; it does not reset this range for the client if it does not sent an -<emphasis> -XkbNewKeyboardNotify</emphasis> - event to a client. Because Xkb-unaware clients and Xkb-aware clients that do -not request <emphasis> -XkbNewKeyboardNotify</emphasis> - events are never sent these events, the server’s notion of the legal keycode +<symbol>XkbNewKeyboardNotify</symbol> +event to a client. Because Xkb-unaware clients and Xkb-aware clients that do +not request +<symbol>XkbNewKeyboardNotify</symbol> +events are never sent these events, the server’s notion of the legal keycode range never changes, and these clients never receive events from keys that fall outside of their notion of the legal keycode range. </para> <para> -Clients that have not selected to receive <emphasis> -XkbNewKeyboardNotify</emphasis> - events do, however, receive the <emphasis> -XkbNewKeyboardNotify</emphasis> - event when a keyboard change occurs. Clients that have not selected to receive +Clients that have not selected to receive +<symbol>XkbNewKeyboardNotify</symbol> +events do, however, receive the +<symbol>XkbNewKeyboardNotify</symbol> +event when a keyboard change occurs. Clients that have not selected to receive this event also receive numerous other events detailing the individual changes that occur when a keyboard change occurs. </para> <para> -Clients wishing to track changes in <emphasis> -min_key_code</emphasis> - and <emphasis> -max_key_code</emphasis> - must watch for both <emphasis> -XkbNewKeyboardNotify</emphasis> - and <emphasis> -XkbMapNotify</emphasis> - events, because a simple mapping change causes an <emphasis> -XkbMapNotify</emphasis> - event and may change the range of valid keycodes, but does not cause an -<emphasis> -XkbNewKeyboardNotify</emphasis> - event. If a client does not select for <emphasis> -XkbNewKeyboardNotify</emphasis> - events, the server restricts the range of keycodes reported to the client. +Clients wishing to track changes in +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +must watch for both +<symbol>XkbNewKeyboardNotify</symbol> +and +<symbol>XkbMapNotify</symbol> +events, because a simple mapping change causes an +<symbol>XkbMapNotify</symbol> +event and may change the range of valid keycodes, but does not cause an +<symbol>XkbNewKeyboardNotify</symbol> +event. If a client does not select for +<symbol>XkbNewKeyboardNotify</symbol> +events, the server restricts the range of keycodes reported to the client. </para> @@ -118,34 +120,34 @@ In addition to filtering out-of-range key events, Xkb: <itemizedlist> <listitem> <para> -Adjusts core protocol <emphasis> -MappingNotify</emphasis> - events to refer only to keys that match the stored legal range. +Adjusts core protocol +<symbol>MappingNotify</symbol> +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. +that issue a core protocol +<systemitem>GetKeyboardMapping</systemitem> +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. +clients that issue a core protocol +<systemitem>GetModifierMapping</systemitem> +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. +Restricts the core protocol +<systemitem>ChangeKeyboardMapping</systemitem> +and +<systemitem>SetModifierMapping</systemitem> +requests to keys that fall inside the stored legal range. </para> </listitem> </itemizedlist> @@ -158,57 +160,60 @@ manner; all Xkb events report the full range of legal keycodes. No requested Xkb events are discarded, and no Xkb requests have their keycode range clamped. </para> +<indexterm significance="preferred" zone="Replacing_a_Keyboard_On_the_Fly"> +<primary>events</primary><secondary><symbol>XkbNewKeyboardNotify</symbol></secondary></indexterm> +<indexterm significance="preferred" zone="Replacing_a_Keyboard_On_the_Fly"> +<primary><structname>XkbNewKeyboardNotifyEvent</structname></primary></indexterm> <para> -The structure for the <emphasis> -XkbNewKeyboardNotify</emphasis> - event is defined as follows: -</para> +The structure for the +<symbol>XkbNewKeyboardNotify</symbol> +event is defined as follows: -<para><programlisting> +<programlisting> typedef struct _XkbNewKeyboardNotify { - int type; /* Xkb extension base event code */ - unsigned long serial; /* X server serial number for event*/ - Bool send_event; /* <emphasis>True</emphasis> - => synthetically generated */ - Display * display; /* server connection where event generated */ - Time time; /* server time when event generated */ - int xkb_type; /* <emphasis>XkbNewKeyboardNotify</emphasis> */ - int device; /* device ID of new keyboard */ - int old_device; /* device ID of old keyboard */ - int min_key_code; /* min keycode of new keyboard */ - int max_key_code; /* max keycode of new keyboard */ - int old_min_key_code; /* min keycode of old keyboard */ - int old_max_key_code; /* max keycode of old keyboard */ - unsigned int changed; /* changed aspects - see masks below */ - char req_major; /* major request that caused change */ - char req_minor; /* minor request that caused change */ -} <emphasis>XkbNewKeyboardNotifyEvent</emphasis>; + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* <symbol>True</symbol> ⇒ synthetically generated */ + Display * display; /* server connection where event generated */ + Time time; /* server time when event generated */ + int xkb_type; /* <symbol>XkbNewKeyboardNotify</symbol> */ + int device; /* device ID of new keyboard */ + int old_device; /* device ID of old keyboard */ + int min_key_code; /* min keycode of new keyboard */ + int max_key_code; /* max keycode of new keyboard */ + int old_min_key_code; /* min keycode of old keyboard */ + int old_max_key_code; /* max keycode of old keyboard */ + unsigned int changed; /* changed aspects - see masks below */ + char req_major; /* major request that caused change */ + char req_minor; /* minor request that caused change */ +} <structname>XkbNewKeyboardNotifyEvent</structname>; </programlisting></para> <para> -To receive name notify events, use <emphasis> -XkbSelectEvents</emphasis> - (see section 4.3) with <emphasis> -XkbNewKeyboardNotifyMask</emphasis> - in both the <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> - parameters. To receive events for only specific names, use <emphasis> -XkbSelectEventDetails</emphasis> -. Set the <emphasis> -event_type</emphasis> - parameter to <emphasis> -XkbNewKeyboardNotify</emphasis> -, and set both the <emphasis> -bits_to_change </emphasis> -and<emphasis> - values_for_bits</emphasis> - detail parameter to a mask composed of a bitwise OR of masks in Table 19.1. +To receive name notify events, use +<function>XkbSelectEvents</function> +(see <link linkend="Selecting_Xkb_Events">section 4.3</link>) with +<symbol>XkbNewKeyboardNotifyMask</symbol> +in both the +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +parameters. To receive events for only specific names, use +<function>XkbSelectEventDetails</function>. +Set the +<structfield>event_type</structfield> +parameter to +<symbol>XkbNewKeyboardNotify</symbol>, +and set both the +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +detail parameter to a mask composed of a bitwise OR of masks in +<link linkend="table19.1">Table 19.1</link>. </para> -<table frame='topbot'> +<table id='table19.1' frame='topbot'> <title>XkbNewKeyboardNotifyEvent Details</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -224,22 +229,22 @@ and<emphasis> </thead> <tbody> <row> - <entry><emphasis>XkbNKN_KeycodesMask</emphasis></entry> + <entry><symbol>XkbNKN_KeycodesMask</symbol></entry> <entry>(1L<<0)</entry> <entry>Notification of keycode range changes wanted</entry> </row> <row> - <entry><emphasis>XkbNKN_GeometryMask</emphasis></entry> + <entry><symbol>XkbNKN_GeometryMask</symbol></entry> <entry>(1L<<1)</entry> <entry>Notification of geometry changes wanted</entry> </row> <row> - <entry>XkbNKN_DeviceIDMask</entry> + <entry><symbol>XkbNKN_DeviceIDMask</symbol></entry> <entry>(1L<<2)</entry> <entry>Notification of device ID changes wanted</entry> </row> <row> - <entry><emphasis>XkbNKN_AllChangesMask</emphasis></entry> + <entry><symbol>XkbAllNewKeyboardEventsMask</symbol></entry> <entry>(0x7)</entry> <entry>Includes all of the above masks</entry> </row> @@ -248,36 +253,35 @@ and<emphasis> </table> <para> -The <emphasis> -req_major</emphasis> - and <emphasis> -req_minor</emphasis> - fields indicate what type of keyboard change has occurred. +The +<structfield>req_major</structfield> +and +<structfield>req_minor</structfield> +fields indicate what type of keyboard change has occurred. </para> <para> -If <emphasis> -req_major</emphasis> - and <emphasis> -req_minor</emphasis> - are zero, the device change was not caused by a software request to the server +If +<structfield>req_major</structfield> +and +<structfield>req_minor</structfield> +are zero, the device change was not caused by a software request to the server — a spontaneous change has occurred, such as hot-plugging a new device. In -this case, <emphasis> -device</emphasis> - is the device identifier for the new, current X keyboard device, but no -implementation-independent guarantee can be made about <emphasis> -old_device</emphasis> -. <emphasis> -old_device</emphasis> - may be identical to <emphasis> -device</emphasis> - (an implementor is permitted to reuse the device specifier when the device -changes); or it may be different. Note that <emphasis> -req_major</emphasis> - and <emphasis> -req_minor</emphasis> - being zero do not necessarily mean that the physical keyboard device has +this case, +<structfield>device</structfield> +is the device identifier for the new, current X keyboard device, but no +implementation-independent guarantee can be made about +<structfield>old_device</structfield>. +<structfield>old_device</structfield> +may be identical to +<structfield>device</structfield> +(an implementor is permitted to reuse the device specifier when the device +changes); or it may be different. Note that +<structfield>req_major</structfield> +and +<structfield>req_minor</structfield> +being zero do not necessarily mean that the physical keyboard device has changed; rather, they only imply a spontaneous change outside of software control (some systems have keyboards that can change personality at the press of a key). @@ -285,45 +289,44 @@ of a key). <para> -If the keyboard change is the result of an X Input Extension <emphasis> -ChangeKeyboardDevice</emphasis> - request, <emphasis> -req_major</emphasis> - contains the input extension major opcode, and <emphasis> -req_minor</emphasis> - contains the input extension request number for <emphasis> -X_ChangeKeyboardDevice</emphasis> -. In this case, <emphasis> -device</emphasis> - and <emphasis> -old_device</emphasis> - are different, with <emphasis> -device</emphasis> - being the identifier for the new, current X keyboard device, and <emphasis> -old_device</emphasis> - being the identifier for the former device. +If the keyboard change is the result of an X Input Extension +<systemitem>ChangeKeyboardDevice</systemitem> +request, +<structfield>req_major</structfield> +contains the input extension major opcode, and +<structfield>req_minor</structfield> +contains the input extension request number for +<symbol>X_ChangeKeyboardDevice</symbol>. +In this case, +<structfield>device</structfield> +and +<structfield>old_device</structfield> +are different, with +<structfield>device</structfield> +being the identifier for the new, current X keyboard device, and +<structfield>old_device</structfield> +being the identifier for the former device. </para> <para> -If the keyboard change is the result of an <emphasis> -XkbGetKeyboardByName</emphasis> - function call, which generates an <emphasis> -X_kbGetKbdByName</emphasis> - request, <emphasis> -req_major</emphasis> - contains the Xkb extension base event code (see section 2.4), and <emphasis> -req_minor</emphasis> - contains the event code for the Xkb extension request <emphasis> -X_kbGetKbdByName</emphasis> -. <emphasis> -device</emphasis> - contains the device identifier for the new device, but nothing definitive can -be said for <emphasis> -old_device</emphasis> -; it may be identical to <emphasis> -device</emphasis> -, or it may be different, depending on the implementation. +If the keyboard change is the result of an +<function>XkbGetKeyboardByName</function> +function call, which generates an +<symbol>X_kbGetKbdByName</symbol> +request, +<structfield>req_major</structfield> +contains the Xkb extension base event code (see <link linkend="Initializing_the_Keyboard_Extension">section 2.4</link>), and +<structfield>req_minor</structfield> +contains the event code for the Xkb extension request +<symbol>X_kbGetKbdByName</symbol>. +<structfield>device</structfield> +contains the device identifier for the new device, but nothing definitive can +be said for +<structfield>old_device</structfield>; +it may be identical to +<structfield>device</structfield>, +or it may be different, depending on the implementation. </para> </chapter> diff --git a/libX11/specs/XKB/ch20.xml b/libX11/specs/XKB/ch20.xml index 6067b5b8f..33501fb7f 100644 --- a/libX11/specs/XKB/ch20.xml +++ b/libX11/specs/XKB/ch20.xml @@ -1,3 +1,6 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Server_Database_of_Keyboard_Components'> <title>Server Database of Keyboard Components</title> @@ -5,11 +8,11 @@ The X server maintains a database of keyboard components, identified by component type. The database contains all the information necessary to build a complete keyboard description for a particular device, as well as to assemble -partial descriptions. Table 20.1 identifies the component types and the type of -information they contain. +partial descriptions. <link linkend="table20.1">Table 20.1</link> +identifies the component types and the type of information they contain. </para> -<table frame='topbot'> +<table id='table20.1' frame='topbot'> <title>Server Database Keyboard Components</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -94,11 +97,11 @@ used to refer to either individual components or a keymap. <para> There may be multiple entries for each of the component types. An entry may be -either <emphasis> -complete</emphasis> - or <emphasis> -partial</emphasis> -. Partial entries describe only a piece of the corresponding keyboard component +either +<emphasis>complete</emphasis> +or +<emphasis>partial</emphasis>. +Partial entries describe only a piece of the corresponding keyboard component and are designed to be combined with other entries of the same type to form a complete entry. </para> @@ -108,43 +111,42 @@ For example, a partial symbols map might describe the differences between a common ASCII keyboard and some national layout. Such a partial map is not useful on its own because it does not include those symbols that are the same on both the ASCII and national layouts (such as function keys). On the other -hand, this partial map can be used to configure <emphasis> -any</emphasis> - ASCII keyboard to use a national layout. +hand, this partial map can be used to configure +<emphasis>any</emphasis> +ASCII keyboard to use a national layout. </para> <para> When a keyboard description is built, the components are processed in the order -in which they appear in Table 20.1; later definitions override earlier ones. +in which they appear in <link linkend="table20.1">Table 20.1</link>; +later definitions override earlier ones. </para> <sect1 id='Component_Names'> <title>Component Names</title> <para> -Component names have the form "<emphasis> -class(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 +Component names have the form “<replaceable>class(member)</replaceable>” where +<replaceable>class</replaceable> +describes a subset of the available components for a particular type and the +optional +<replaceable>member</replaceable> +identifies a specific component from that subset. For example, the name "atlantis(acme)" for a symbols component might specify the symbols used for the atlantis national keyboard layout by the vendor "acme." Each class has an -optional <emphasis> -default</emphasis> - member — references that specify a class but not a member refer to the +optional +<emphasis>default</emphasis> +member — references that specify a class but not a member refer to the default member of the class, if one exists. Xkb places no constraints on the interpretation of the class and member names used in component names. </para> <para> -The <emphasis> -class</emphasis> - and <emphasis> -member</emphasis> - names are both specified using characters from the Latin-1 character set. Xkb +The +<replaceable>class</replaceable> +and +<replaceable>member</replaceable> +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 @@ -159,112 +161,109 @@ use of other characters is implementation-dependent. You may ask the server for a list of components for one or more component types. The request takes the form of a set of patterns, one pattern for each of the component types, including a pattern for the complete keyboard description. -To obtain this list, use <emphasis> -XkbListComponents</emphasis> -. +To obtain this list, use +<function>XkbListComponents</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbComponentListPtr<emphasis> - XkbListComponents</emphasis> -(<emphasis> -dpy</emphasis> -, <emphasis> -device_spec</emphasis> -, <emphasis> -ptrns</emphasis> -, <emphasis> -max_inout</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbComponentNamesPtr <emphasis> -ptrns</emphasis> -; /* namelist for components of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int * <emphasis> -max_inout</emphasis> -; /* max # returned names, # left over */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbListComponents"><primary><function>XkbListComponents</function></primary></indexterm> +<funcsynopsis id="XkbListComponents"> + <funcprototype> + <funcdef>XkbComponentListPtr <function>XkbListComponents</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>device_spec</parameter>, +<parameter>ptrns</parameter>, +<parameter>max_inout</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>XkbComponentNamesPtr <parameter>ptrns</parameter></paramdef> + <paramdef>int *<parameter>max_inout</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ptrns</parameter> + </term> + <listitem> + <para> + namelist for components of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>max_inout</parameter> + </term> + <listitem> + <para> + max # returned names, # left over + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbListComponents</emphasis> - queries the server for a list of component names matching the patterns -specified in <emphasis> -ptrns</emphasis> -. It waits for a reply and returns the matching component names in an <emphasis> -XkbComponentListRec</emphasis> - structure. When you are done using the structure, you should free it using -<emphasis> -XkbFreeComponentList</emphasis> -. <emphasis> -device_spec</emphasis> - indicates a particular device in which the caller is interested. A server is +<function>XkbListComponents</function> +queries the server for a list of component names matching the patterns +specified in +<parameter>ptrns</parameter>. +It waits for a reply and returns the matching component names in an +<structname>XkbComponentListRec</structname> +structure. When you are done using the structure, you should free it using +<function>XkbFreeComponentList</function>. +<parameter>device_spec</parameter> +indicates a particular device in which the caller is interested. A server is allowed (but not required) to restrict its reply to portions of the database that are relevant for that particular device. </para> <para> -<emphasis> -ptrns</emphasis> - is a pointer to an <emphasis> -XkbComponentNamesRec</emphasis> -, described below. Each of the fields in <emphasis> -ptrns</emphasis> - contains a pattern naming the components of interest. Each of the patterns is -composed of characters from the ISO <emphasis> -Latin1</emphasis> - encoding, but can contain only parentheses, the wildcard characters -‘<emphasis> -?</emphasis> -’ and ‘<emphasis> -*</emphasis> -’, and characters permitted in a component class or member name (see section -20.1). A pattern may be <emphasis> -NULL</emphasis> -, in which case no components for that type is returned. Pattern matches with -component names are case sensitive. The ‘<emphasis> -?</emphasis> -’ wildcard matches any single character, except a left or right parenthesis; -the ‘<emphasis> -*</emphasis> -’ wildcard matches any number of characters, except a left or right +<parameter>ptrns</parameter> +is a pointer to an +<structname>XkbComponentNamesRec</structname>, +described below. Each of the fields in +<parameter>ptrns</parameter> +contains a pattern naming the components of interest. Each of the patterns is +composed of characters from the ISO +<emphasis>Latin1</emphasis> +encoding, but can contain only parentheses, the wildcard characters +‘<literal>?</literal>’ and ‘<literal>*</literal>’, +and characters permitted in a component class or member name +(see <link linkend="Component_Names">section 20.1</link>). A pattern may be +<symbol>NULL</symbol>, +in which case no components for that type is returned. Pattern matches with +component names are case sensitive. The +‘<literal>?</literal>’ +wildcard matches any single character, except a left or right parenthesis; +the ‘<literal>*</literal>’ +wildcard matches any number of characters, except a left or right parenthesis. If an implementation allows additional characters in a component class or member name other than those required by the Xkb extension (see -section 20.1), the result of comparing one of the additional characters to +<link linkend="Component_Names">section 20.1</link>), the result of comparing one of the additional characters to either of the wildcard characters is implementation-dependent. </para> @@ -277,118 +276,112 @@ from the pattern. <para> -<emphasis> -max_inout</emphasis> - is used to throttle the amount of data passed to and from the server. On +<parameter>max_inout</parameter> +is used to throttle the amount of data passed to and from the server. On input, it specifies the maximum number of names to be returned (the total -number of names in all component categories). Upon return from <emphasis> -XkbListComponents</emphasis> -, <emphasis> -max_inout</emphasis> - contains the number of names that matched the request but were not returned +number of names in all component categories). Upon return from +<function>XkbListComponents</function>, +<parameter>max_inout</parameter> +contains the number of names that matched the request but were not returned because of the limit. </para> -<para> +<para id='XkbComponentNamesRec'> +<indexterm significance="preferred" zone="XkbComponentNamesRec"> +<primary><structname>XkbComponentNamesRec</structname></primary></indexterm> The component name patterns used to describe the request are passed to -<emphasis> -XkbListComponents</emphasis> - using an <emphasis> -XkbComponentNamesRec</emphasis> - structure. This structure has no special allocation constraints or +<function>XkbListComponents</function> +using an +<structname>XkbComponentNamesRec</structname> +structure. This structure has no special allocation constraints or interrelationships with other structures; allocate and free this structure -using standard <emphasis> -malloc</emphasis> - and <emphasis> -free</emphasis> - calls or their equivalent: -</para> +using standard +<function>malloc</function> +and +<function>free</function> +calls or their equivalent: -<para><programlisting> +<programlisting> typedef struct _XkbComponentNames { - char * keymap; /* keymap names */ - char * keycodes; /* keycode names */ - char * types; /* type names */ - char * compat; /* compatibility map names */ - char * symbols; /* symbol names */ - char * geometry; /* geometry names */ -} <emphasis>XkbComponentNamesRec</emphasis>, *XkbComponentNamesPtr; + char * keymap; /* keymap names */ + char * keycodes; /* keycode names */ + char * types; /* type names */ + char * compat; /* compatibility map names */ + char * symbols; /* symbol names */ + char * geometry; /* geometry names */ +} <structname>XkbComponentNamesRec</structname>, *XkbComponentNamesPtr; </programlisting></para> -<para> -<emphasis> -XkbListComponents</emphasis> - returns a pointer to an <emphasis> -XkbComponentListRec</emphasis> -: -</para> +<para id='XkbComponentListRec'> +<indexterm significance="preferred" zone="XkbComponentListRec"> +<primary><structname>XkbComponentListRec</structname></primary></indexterm> +<indexterm significance="preferred" zone="XkbComponentListRec"> +<primary><structname>XkbComponentNameRec</structname></primary></indexterm> +<function>XkbListComponents</function> +returns a pointer to an +<structname>XkbComponentListRec</structname>: -<para><programlisting> +<programlisting> typedef struct _XkbComponentList { - int num_keymaps; /* number of entries in keymap */ - int num_keycodes; /* number of entries in keycodes */ - int num_types; /* number of entries in types */ - int num_compat; /* number of entries in compat */ - int num_symbols; /* number of entries in symbols */ - int num_geometry; /* number of entries in geometry; - XkbComponentNamePtr keymap; /* keymap names */ - XkbComponentNamePtr keycodes; /* keycode names */ - XkbComponentNamePtr types; /* type names */ - XkbComponentNamePtr compat; /* compatibility map names */ - XkbComponentNamePtr symbols; /* symbol names */ - XkbComponentNamePtr geometry; /* geometry names */ -} <emphasis>XkbComponentListRec</emphasis>, *XkbComponentListPtr; -</programlisting></para> + int num_keymaps; /* number of entries in keymap */ + int num_keycodes; /* number of entries in keycodes */ + int num_types; /* number of entries in types */ + int num_compat; /* number of entries in compat */ + int num_symbols; /* number of entries in symbols */ + int num_geometry; /* number of entries in geometry; + XkbComponentNamePtr keymap; /* keymap names */ + XkbComponentNamePtr keycodes; /* keycode names */ + XkbComponentNamePtr types; /* type names */ + XkbComponentNamePtr compat; /* compatibility map names */ + XkbComponentNamePtr symbols; /* symbol names */ + XkbComponentNamePtr geometry; /* geometry names */ +} <structname>XkbComponentListRec</structname>, *XkbComponentListPtr; -<para><programlisting> typedef struct _XkbComponentName { - unsigned short flags; /* hints regarding component name */ - char * name; /* name of component */ -} <emphasis>XkbComponentNameRec</emphasis>, *XkbComponentNamePtr; + unsigned short flags; /* hints regarding component name */ + char * name; /* name of component */ +} <structname>XkbComponentNameRec</structname>, *XkbComponentNamePtr; </programlisting></para> <para> -Note that the structure used to specify patterns on input is an <emphasis> -XkbComponentNamesRec</emphasis> -, and that used to hold the individual component names upon return is an -<emphasis> -XkbComponentNameRec</emphasis> - (no trailing ‘s’ in Name). +Note that the structure used to specify patterns on input is an +<structname>XkbComponentNamesRec</structname>, +and that used to hold the individual component names upon return is an +<structname>XkbComponentNameRec</structname> +(no trailing ‘s’ in Name). </para> <para> -When you are done using the structure returned by <emphasis> -XkbListComponents</emphasis> -, free it using <emphasis> -XkbFreeComponentList</emphasis> -. +When you are done using the structure returned by +<function>XkbListComponents</function>, +free it using +<function>XkbFreeComponentList</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeComponentList</emphasis> -(list) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbComponentListPtr list; /* pointer to <emphasis> -XkbComponentListRec</emphasis> - to free */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbFreeComponentList"><primary><function>XkbFreeComponentList</function></primary></indexterm> +<funcsynopsis id="XkbFreeComponentList"> + <funcprototype> + <funcdef>void <function>XkbFreeComponentList</function></funcdef> +<!-- (list) --> + + <paramdef>XkbComponentListPtr <parameter>list</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>list</parameter> + </term> + <listitem> + <para> + pointer to <structname>XkbComponentListRec</structname> to free + </para> + </listitem> + </varlistentry> +</variablelist> </sect1> @@ -398,19 +391,21 @@ XkbComponentListRec</emphasis> <para> A set of flags is associated with each component; these flags provide additional hints about the component’s use. These hints are designated by bit -masks in the flags field of the <emphasis> -XkbComponentNameRec</emphasis> - structures contained in the <emphasis> -XkbComponentListRec</emphasis> - returned from <emphasis> -XkbListComponents</emphasis> -. The least significant byte of the flags field has the same meaning for all +masks in the flags field of the +<structname>XkbComponentNameRec</structname> +structures contained in the +<structname>XkbComponentListRec</structname> +returned from +<function>XkbListComponents</function>. +The least significant byte of the flags field has the same meaning for all types of keyboard components; the interpretation of the most significant byte -is dependent on the type of component. The flags bits are defined in Table -20.2. The symbols hints in Table 20.2 apply only to partial symbols components -(those with <emphasis> -XkbLC_Partial</emphasis> - also set); full symbols components are assumed to specify all of the pieces. +is dependent on the type of component. The flags bits are defined in +<link linkend="table20.2">Table 20.2</link>. +The symbols hints in <link linkend="table20.2">Table 20.2</link> +apply only to partial symbols components +(those with +<symbol>XkbLC_Partial</symbol> +also set); full symbols components are assumed to specify all of the pieces. </para> @@ -419,15 +414,15 @@ The alphanumeric, modifier, keypad or function keys symbols hints should describe the primary intent of the component designer and should not be simply an exhaustive list of the kinds of keys that are affected. For example, national keyboard layouts affect primarily alphanumeric keys, but many affect a -few modifier keys as well; such mappings should set only the <emphasis> -XkbLC_AlphanumericKeys</emphasis> - hint. In general, symbols components should set only one of the four flags -(<emphasis> -XkbLC_AlternateGroup</emphasis> - may be combined with any of the other flags). +few modifier keys as well; such mappings should set only the +<symbol>XkbLC_AlphanumericKeys</symbol> +hint. In general, symbols components should set only one of the four flags +( +<symbol>XkbLC_AlternateGroup</symbol> +may be combined with any of the other flags). </para> -<table frame='topbot'> +<table id='table20.2' frame='topbot'> <title>XkbComponentNameRec Flags Bits</title> <?dbfo keep-together="always" ?> <tgroup cols='4' align='left' colsep='0' rowsep='0'> @@ -446,19 +441,19 @@ XkbLC_AlternateGroup</emphasis> <tbody> <row> <entry>All Components</entry> - <entry><para><emphasis>XkbLC_Hidden</emphasis></para></entry> + <entry><para><symbol>XkbLC_Hidden</symbol></para></entry> <entry>Do not present to user</entry> <entry>(1L<<0)</entry> </row> <row> <entry></entry> - <entry><emphasis>XkbLC_Default</emphasis></entry> + <entry><symbol>XkbLC_Default</symbol></entry> <entry>Default member of class</entry> <entry>(1L<<1)</entry> </row> <row> <entry></entry> - <entry><emphasis>XkbLC_Partial</emphasis></entry> + <entry><symbol>XkbLC_Partial</symbol></entry> <entry>Partial component</entry> <entry>(1L<<2)</entry> </row> @@ -488,31 +483,31 @@ XkbLC_AlternateGroup</emphasis> </row> <row> <entry>Symbols</entry> - <entry><emphasis>XkbLC_AlphanumericKeys</emphasis></entry> + <entry><symbol>XkbLC_AlphanumericKeys</symbol></entry> <entry>Bindings primarily for alphanumeric keyboard section</entry> <entry>(1L<<8)</entry> </row> <row> <entry></entry> - <entry><emphasis>XkbLC_ModifierKeys</emphasis></entry> + <entry><symbol>XkbLC_ModifierKeys</symbol></entry> <entry>Bindings primarily for modifier keys</entry> <entry>(1L<<9)</entry> </row> <row> <entry></entry> - <entry><emphasis>XkbLC_KeypadKeys</emphasis></entry> + <entry><symbol>XkbLC_KeypadKeys</symbol></entry> <entry>Bindings primarily for numeric keypad keys</entry> <entry>(1L<<10)</entry> </row> <row> <entry></entry> - <entry><emphasis>XkbLC_FunctionKeys</emphasis></entry> + <entry><symbol>XkbLC_FunctionKeys</symbol></entry> <entry>Bindings primarily for function keys</entry> <entry>(1L<<11)</entry> </row> <row> <entry></entry> - <entry><emphasis>XkbLC_AlternateGroup</emphasis></entry> + <entry><symbol>XkbLC_AlternateGroup</symbol></entry> <entry>Bindings for an alternate group</entry> <entry>(1L<<12)</entry> </row> @@ -547,189 +542,179 @@ specific device, in which case the behavior of the device changes accordingly. <para> To build a new keyboard description from a set of named components, and to optionally have the server use the resulting description to replace an active -one, use <emphasis> -XkbGetKeyboardByName</emphasis> -. +one, use +<function>XkbGetKeyboardByName</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbDescPtr <emphasis> -XkbGetKeyboardByName</emphasis> -(<emphasis> -dpy</emphasis> -, <emphasis> -device_spec</emphasis> -, <emphasis> -names</emphasis> -, <emphasis> -want</emphasis> -, <emphasis> -need</emphasis> -, <emphasis> -load</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbComponentNamesPtr <emphasis> -names</emphasis> -; /* names of components to fetch */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -want</emphasis> -; /* desired structures in returned record */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -need</emphasis> -; /* mandatory structures in returned record */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> -load</emphasis> -; /* <emphasis> -True</emphasis> - => load into <emphasis> -device_spec</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbGetKeyboardByName"><primary><function>XkbGetKeyboardByName</function></primary></indexterm> +<funcsynopsis id="XkbGetKeyboardByName"> + <funcprototype> + <funcdef>XkbDescPtr <function>XkbGetKeyboardByName</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>device_spec</parameter>, +<parameter>names</parameter>, +<parameter>want</parameter>, +<parameter>need</parameter>, +<parameter>load</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>XkbComponentNamesPtr <parameter>names</parameter></paramdef> + <paramdef>unsigned int <parameter>want</parameter></paramdef> + <paramdef>unsigned int <parameter>need</parameter></paramdef> + <paramdef>Bool <parameter>load</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>names</parameter> + </term> + <listitem> + <para> + names of components to fetch + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>want</parameter> + </term> + <listitem> + <para> + desired structures in returned record + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>need</parameter> + </term> + <listitem> + <para> + mandatory structures in returned record + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>load</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ load into <parameter>device_spec</parameter> + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -names</emphasis> - contains a set of expressions describing the keyboard components the server -should use to build the new keyboard description. <emphasis> -want</emphasis> - and <emphasis> -need</emphasis> - are bit fields describing the parts of the resulting keyboard description that -should be present in the returned <emphasis> -XkbDescRec</emphasis> -. +<parameter>names</parameter> +contains a set of expressions describing the keyboard components the server +should use to build the new keyboard description. +<parameter>want</parameter> +and +<parameter>need</parameter> +are bit fields describing the parts of the resulting keyboard description that +should be present in the returned +<structname>XkbDescRec</structname>. </para> <para> -The individual fields in <emphasis> -names</emphasis> - are <emphasis> -component expressions</emphasis> - composed of keyboard component names (no wildcarding as may be used in -<emphasis> -XkbListComponents</emphasis> -), the special component name symbol ‘%’, and the special operator -characters ‘<emphasis> -+</emphasis> -’ and ‘<emphasis> -|</emphasis> -’. A component expression is parsed left to right, as follows: +The individual fields in +<parameter>names</parameter> +are +<firstterm>component expressions</firstterm> +composed of keyboard component names (no wildcarding as may be used in +<function>XkbListComponents</function>), +the special component name symbol ‘<literal>%</literal>’, +and the special operator characters +‘<literal>+</literal>’ and ‘<literal>|</literal>’. +A component expression is parsed left to right, as follows: </para> <itemizedlist> <listitem> <para> -The special component name "<emphasis> -computed</emphasis> -" may be used in <emphasis> -keycodes</emphasis> - component expressions and refers to a component consisting of a set of +The special component name “<literal>computed</literal>” +may be used in +<structfield>keycodes</structfield> +component expressions and refers to a component consisting of a set of keycodes computed automatically by the server as needed. </para> </listitem> <listitem> <para> -The special component name "<emphasis> -canonical</emphasis> -" may be used in <emphasis> -types</emphasis> - component expressions and refers to a partial component defining the four -standard key types: <emphasis> -ALPHABETIC</emphasis> -, <emphasis> -ONE_LEVEL</emphasis> -, <emphasis> -TWO_LEVEL</emphasis> -, and <emphasis> -KEYPAD</emphasis> -. - </para> +The special component name “<literal>canonical</literal>” may be used in +<structfield>types</structfield> +component expressions and refers to a partial component defining the four +standard key types: +<emphasis>ALPHABETIC</emphasis>, +<emphasis>ONE_LEVEL</emphasis>, +<emphasis>TWO_LEVEL</emphasis>, +and +<emphasis>KEYPAD</emphasis>. +</para> </listitem> <listitem> <para> -The special component name ‘<emphasis> -%</emphasis> -’ refers to the keyboard description for the device specified in <emphasis> -device_spec</emphasis> - or the keymap names component. If a keymap names component is specified that -does not begin with ‘+’ or ‘|’ and does not contain ‘<emphasis> -%</emphasis> -’, then ‘<emphasis> -%</emphasis> -’ refers to the description generated by the keymap names component. -Otherwise, it refers to the keyboard description for <emphasis> -device_spec</emphasis> -. - </para> +The special component name ‘<literal>%</literal>’ +refers to the keyboard description for the device specified in +<parameter>device_spec</parameter> +or the keymap names component. If a keymap names component is specified that +does not begin with +‘<literal>+</literal>’ or ‘<literal>|</literal>’ and does not contain +‘<literal>%</literal>’, then ‘<literal>%</literal>’ +refers to the description generated by the keymap names component. +Otherwise, it refers to the keyboard description for +<parameter>device_spec</parameter>. +</para> </listitem> <listitem> <para> -The ‘<emphasis> -+</emphasis> -’ operator specifies that the following component should <emphasis> -override</emphasis> - the currently assembled description; any definitions that are present in both +The ‘<literal>+</literal>’ +operator specifies that the following component should +<emphasis>override</emphasis> +the currently assembled description; any definitions that are present in both components are taken from the second. </para> </listitem> <listitem> <para> -The ‘<emphasis> -|</emphasis> -’ operator specifies that the next specified component should <emphasis> -augment</emphasis> - the currently assembled description; any definitions that are present in both +The ‘<literal>|</literal>’ +operator specifies that the next specified component should +<emphasis>augment</emphasis> +the currently assembled description; any definitions that are present in both components are taken from the first. </para> </listitem> <listitem> <para> -If the component expression begins with an operator, a leading ‘<emphasis> -%</emphasis> -’ is implied. +If the component expression begins with an operator, a leading +‘<literal>%</literal>’ is implied. </para> </listitem> <listitem> @@ -741,9 +726,9 @@ entire expression is invalid and is ignored. </itemizedlist> <para> -For example, if <emphasis> -names->symbols</emphasis> - contained the expression "+de", it specifies that the default member of the +For example, if +<structfield>names->symbols</structfield> +contained the expression "+de", it specifies that the default member of the "de" class of symbols should be applied to the current keyboard mapping, overriding any existing definitions (it could also be written "+de(default)"). </para> @@ -753,14 +738,14 @@ overriding any existing definitions (it could also be written "+de(default)"). Here is a slightly more involved example: the expression "acme(ascii)+de(basic)|iso9995-3" constructs a German (de) mapping for the ASCII keyboard supplied by the "acme" vendor. The new definition begins with -the symbols for the ASCII keyboard for Acme (<emphasis> -acme(ascii)</emphasis> -), overrides them with definitions for the basic German keyboard (<emphasis> -de(basic)</emphasis> -), and then applies the definitions from the default iso9995-3 keyboard -(<emphasis> -iso9995-3</emphasis> -) to any undefined keys or groups of keys (part three of the iso9995 standard +the symbols for the ASCII keyboard for Acme +(<literal>acme(ascii)</literal>), +overrides them with definitions for the basic German keyboard +(<literal>de(basic)</literal>), +and then applies the definitions from the default iso9995-3 keyboard +( +<literal>iso9995-3</literal>) +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> @@ -770,74 +755,69 @@ de, basic, iso9995-3) is not defined by Xkb; only the operations and their ordering are.</para></note> <para> -Note that the presence of a keymap <emphasis> -names</emphasis> - component that does not contain ‘<emphasis> -%</emphasis> -’ (either explicit or implied by virtue of an expression starting with an +Note that the presence of a keymap +<parameter>names</parameter> +component that does not contain +‘<literal>%</literal>’ +(either explicit or implied by virtue of an expression starting with an operator) indicates a description that is independent of the keyboard -description for the device specified in <emphasis> -device_spec</emphasis> -. The same is true of requests in which the keymap names component is empty and +description for the device specified in +<parameter>device_spec</parameter>. +The same is true of requests in which the keymap names component is empty and all five other names components contain expressions void of references to -‘<emphasis> -%</emphasis> -’. Requests of this form allow you to deal with keyboard definitions +‘<literal>%</literal>’. +Requests of this form allow you to deal with keyboard definitions independent of any actual device. </para> <para> -The server parses all non-<emphasis> -NULL</emphasis> - fields in <emphasis> -names</emphasis> - and uses them to build a keyboard description. However, before parsing the -expressions in <emphasis> -names</emphasis> -, the server ORs the bits in <emphasis> -want</emphasis> - and <emphasis> -need</emphasis> - together and examines the result in relationship to the expressions in -<emphasis> -names</emphasis> -. Table 20.3 identifies the components that are required for each of the -possible bits in <emphasis> -want</emphasis> - or <emphasis> -need</emphasis> -. If a required component has not been specified in the <emphasis> -names</emphasis> - structure (the corresponding field is <emphasis> -NULL</emphasis> -), the server substitutes the expression "<emphasis> -%</emphasis> -", resulting in the component values being taken from <emphasis> -device_spec</emphasis> -. In addition, if <emphasis> -load</emphasis> - is <emphasis> -True</emphasis> -, the server modifies <emphasis> -names</emphasis> - if necessary (again using a "<emphasis> -%</emphasis> -" entry) to ensure all of the following fields are non-<emphasis> -NULL</emphasis> -: <emphasis> -types</emphasis> -, <emphasis> -keycodes</emphasis> -, <emphasis> -symbols</emphasis> -, and <emphasis> -compat</emphasis> -.<emphasis> -</emphasis> +The server parses all non- +<symbol>NULL</symbol> +fields in +<parameter>names</parameter> +and uses them to build a keyboard description. However, before parsing the +expressions in +<parameter>names</parameter>, +the server ORs the bits in +<parameter>want</parameter> +and +<parameter>need</parameter> +together and examines the result in relationship to the expressions in +<parameter>names</parameter>. +<link linkend="table20.3">Table 20.3</link> +identifies the components that are required for each of the +possible bits in +<parameter>want</parameter> +or +<parameter>need</parameter>. +If a required component has not been specified in the +<parameter>names</parameter> +structure (the corresponding field is +<symbol>NULL</symbol>), +the server substitutes the expression +“<literal>%</literal>”, +resulting in the component values being taken from +<parameter>device_spec</parameter>. +In addition, if +<parameter>load</parameter> +is +<symbol>True</symbol>, +the server modifies +<parameter>names</parameter> +if necessary (again using a +“<literal>%</literal>” +entry) to ensure all of the following fields are non- +<symbol>NULL</symbol>: + +<structfield>types</structfield>, +<structfield>keycodes</structfield>, +<structfield>symbols</structfield>, +and +<structfield>compat</structfield>. </para> -<table frame='topbot'> +<table id='table20.3' frame='topbot'> <title>Want and Need Mask Bits and Required Names Components</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -853,52 +833,52 @@ compat</emphasis> </thead> <tbody> <row> - <entry>XkbGBN_TypesMask</entry> + <entry><symbol>XkbGBN_TypesMask</symbol></entry> <entry>Types</entry> <entry>(1L<<0)</entry> </row> <row> - <entry>XkbGBN_CompatMapMask</entry> + <entry><symbol>XkbGBN_CompatMapMask</symbol></entry> <entry>Compat</entry> <entry>(1L<<1)</entry> </row> <row> - <entry>XkbGBN_ClientSymbolsMask</entry> + <entry><symbol>XkbGBN_ClientSymbolsMask</symbol></entry> <entry>Types + Symbols + Keycodes</entry> <entry>(1L<<2)</entry> </row> <row> - <entry>XkbGBN_ServerSymbolsMask</entry> + <entry><symbol>XkbGBN_ServerSymbolsMask</symbol></entry> <entry>Types + Symbols + Keycodes</entry> <entry>(1L<<3)</entry> </row> <row> - <entry>XkbGBN_SymbolsMask</entry> + <entry><symbol>XkbGBN_SymbolsMask</symbol></entry> <entry>Symbols</entry> <entry>(1L<<1)</entry> </row> <row> - <entry>XkbGBN_IndicatorMapMask</entry> + <entry><symbol>XkbGBN_IndicatorMapMask</symbol></entry> <entry>Compat</entry> <entry>(1L<<4)</entry> </row> <row> - <entry>XkbGBN_KeyNamesMask</entry> + <entry><symbol>XkbGBN_KeyNamesMask</symbol></entry> <entry>Keycodes</entry> <entry>(1L<<5)</entry> </row> <row> - <entry>XkbGBN_GeometryMask</entry> + <entry><symbol>XkbGBN_GeometryMask</symbol></entry> <entry>Geometry</entry> <entry>(1L<<6)</entry> </row> <row> - <entry>XkbGBN_OtherNamesMask</entry> + <entry><symbol>XkbGBN_OtherNamesMask</symbol></entry> <entry>Types + Symbols + Keycodes + Compat + Geometry</entry> <entry>(1L<<7)</entry> </row> <row> - <entry>XkbGBN_AllComponentsMask</entry> + <entry><symbol>XkbGBN_AllComponentsMask</symbol></entry> <entry></entry> <entry>(0xff)</entry> </row> @@ -907,67 +887,63 @@ compat</emphasis> </table> <para> -<emphasis> -need</emphasis> - specifies a set of keyboard components that the server must be able to resolve -in order for <emphasis> -XkbGetKeyboardByName</emphasis> - to succeed; if any of the components specified in <emphasis> -need</emphasis> - cannot be successfully resolved, <emphasis> -XkbGetKeyboardByName</emphasis> - fails. +<parameter>need</parameter> +specifies a set of keyboard components that the server must be able to resolve +in order for +<function>XkbGetKeyboardByName</function> +to succeed; if any of the components specified in +<parameter>need</parameter> +cannot be successfully resolved, +<function>XkbGetKeyboardByName</function> +fails. </para> <para> -<emphasis> -want</emphasis> - specifies a set of keyboard components that the server should attempt to +<parameter>want</parameter> +specifies a set of keyboard components that the server should attempt to resolve, but that are not mandatory. If the server is unable to resolve any of -these components, <emphasis> -XkbGetKeyboardByName</emphasis> - still succeeds. Bits specified in <emphasis> -want</emphasis> - that are also specified in <emphasis> -need</emphasis> - have no effect in the context of <emphasis> -want</emphasis> -. +these components, +<function>XkbGetKeyboardByName</function> +still succeeds. Bits specified in +<parameter>want</parameter> +that are also specified in +<parameter>need</parameter> +have no effect in the context of +<parameter>want</parameter>. </para> <para> -If <emphasis> -load</emphasis> - is <emphasis> -True</emphasis> -, the server updates its keyboard description for <emphasis> -device_spec</emphasis> - to match the result of the keyboard description just built. If load is -<emphasis> -False</emphasis> -, the server’s description for device <emphasis> -device_spec</emphasis> - is not updated. In all cases, the parts specified by <emphasis> -want</emphasis> - and <emphasis> -need</emphasis> - from the just-built keyboard description are returned. +If +<parameter>load</parameter> +is +<symbol>True</symbol>, +the server updates its keyboard description for +<parameter>device_spec</parameter> +to match the result of the keyboard description just built. If load is +<symbol>False</symbol>, +the server’s description for device +<parameter>device_spec</parameter> +is not updated. In all cases, the parts specified by +<parameter>want</parameter> +and +<parameter>need</parameter> +from the just-built keyboard description are returned. </para> <para> -The <emphasis> -names</emphasis> - structure in an <emphasis> -XkbDescRec</emphasis> - keyboard description record (see Chapter 18) contains one field for each of +The +<parameter>names</parameter> +structure in an +<structname>XkbDescRec</structname> +keyboard description record (see <xref linkend="Symbolic_Names" />) contains one field for each of the five component types used to build a keyboard description. When a keyboard description is built from a set of database components, the corresponding -fields in this <emphasis> -names</emphasis> - structure are set to match the expressions used to build the component. +fields in this +<parameter>names</parameter> +structure are set to match the expressions used to build the component. </para> @@ -977,24 +953,26 @@ database of components and returning all or part of it is diagrammed in Figure 20.1: </para> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-21.svg"/> - </imageobject> - <caption>Building a New Keyboard Description from the Server Database</caption> -</mediaobject> +<figure id='figure20.1'> + <title>Building a New Keyboard Description from the Server Database</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-21.svg"/> + </imageobject> + </mediaobject> +</figure> <para> -The information returned to the client in the <emphasis> -XkbDescRec</emphasis> - is essentially the result of a series of calls to extract information from a +The information returned to the client in the +<structname>XkbDescRec</structname> +is essentially the result of a series of calls to extract information from a fictitious device whose description matches the one just built. The calls -corresponding to each of the mask bits are summarized in Table 20.4, together -with the <emphasis> -XkbDescRec</emphasis> - components that are filled in. +corresponding to each of the mask bits are summarized in +<link linkend="table20.4">Table 20.4</link>, together with the +<structname>XkbDescRec</structname> +components that are filled in. </para> -<table frame='topbot'> +<table id='table20.4' frame='topbot'> <title>XkbDescRec Components Returned for Values of Want & Needs</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -1010,17 +988,17 @@ XkbDescRec</emphasis> </thead> <tbody> <row> - <entry>XkbGBN_TypesMask</entry> + <entry><symbol>XkbGBN_TypesMask</symbol></entry> <entry>map.types</entry> <entry>XkbGetUpdatedMap(dpy, XkbTypesMask, Xkb)</entry> </row> <row> - <entry>XkbGBN_ServerSymbolsMask</entry> + <entry><symbol>XkbGBN_ServerSymbolsMask</symbol></entry> <entry>server</entry> <entry>XkbGetUpdatedMap(dpy, XkbAllClientInfoMask, Xkb)</entry> </row> <row> - <entry>XkbGBN_ClientSymbolsMask</entry> + <entry><symbol>XkbGBN_ClientSymbolsMask</symbol></entry> <entry>map, including map.types</entry> <entry>XkbGetUpdatedMap(dpy, XkbAllServerInfoMask, Xkb)</entry> </row> @@ -1030,17 +1008,17 @@ XkbDescRec</emphasis> <entry>XkbGetIndicatorMap(dpy, XkbAllIndicators, Xkb)</entry> </row> <row> - <entry>XkbGBN_CompatMapMask</entry> + <entry><symbol>XkbGBN_CompatMapMask</symbol></entry> <entry>compat</entry> <entry>XkbGetCompatMap(dpy, XkbAllCompatMask, Xkb)</entry> </row> <row> - <entry>XkbGBN_GeometryMask</entry> + <entry><symbol>XkbGBN_GeometryMask</symbol></entry> <entry>geom</entry> <entry>XkbGetGeometry(dpy, Xkb)</entry> </row> <row> - <entry>XkbGBN_KeyNamesMask</entry> + <entry><symbol>XkbGBN_KeyNamesMask</symbol></entry> <entry> <para>names.keys</para> <para>names.key_aliases</para> @@ -1050,7 +1028,7 @@ XkbGetNames(dpy, XkbKeyNamesMask | XkbKeyAliasesMask, Xkb) </entry> </row> <row> - <entry>XkbGBN_OtherNamesMask</entry> + <entry><symbol>XkbGBN_OtherNamesMask</symbol></entry> <entry> <para>names.keycodes</para> <para>names.geometry</para> @@ -1075,37 +1053,35 @@ XkbGetNames(dpy, XkbKeyNamesMask | XkbKeyAliasesMask, Xkb) </table> <para> -There is no way to determine which components specified in <emphasis> -want</emphasis> - (but not in <emphasis> -need</emphasis> -) were actually fetched, other than breaking the call into successive calls to -<emphasis> -XkbGetKeyboardByName</emphasis> - and specifying individual components. +There is no way to determine which components specified in +<parameter>want</parameter> +(but not in +<parameter>need</parameter>) +were actually fetched, other than breaking the call into successive calls to +<function>XkbGetKeyboardByName</function> +and specifying individual components. </para> <para> -<emphasis> -XkbGetKeyboardByName</emphasis> - always sets <emphasis> -min_key_code</emphasis> - and <emphasis> -max_key_code</emphasis> - in the returned <emphasis> -XkbDescRec</emphasis> - structure. +<function>XkbGetKeyboardByName</function> +always sets +<structfield>min_key_code</structfield> +and +<structfield>max_key_code</structfield> +in the returned +<structname>XkbDescRec</structname> +structure. </para> <para> -<emphasis>XkbGetKeyboardByName</emphasis> +<function>XkbGetKeyboardByName</function> is synchronous; it sends the request to the server to build a new keyboard description and waits for the reply. If successful, the return value is -non-<emphasis>NULL</emphasis>. -<emphasis>XkbGetKeyboardByName</emphasis> -generates a <emphasis>BadMatch</emphasis> +non-<symbol>NULL</symbol>. +<function>XkbGetKeyboardByName</function> +generates a <errorname>BadMatch</errorname> protocol error if errors are encountered when building the keyboard description. </para> @@ -1114,82 +1090,78 @@ description. <para> If you simply want to obtain information about the current keyboard device, rather than generating a new keyboard description from elements in the server -database, use <emphasis> -XkbGetKeyboard</emphasis> - (see section 6.2). +database, use +<function>XkbGetKeyboard</function> +(see <link linkend="Obtaining_a_Keyboard_Description_from_the_Server">section 6.2</link>). </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbDescPtr <emphasis> -XkbGetKeyboard</emphasis> -(<emphasis> -dpy</emphasis> -, <emphasis> -which</emphasis> -, <emphasis> -device_spec</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask of components of <emphasis> -XkbDescRec</emphasis> - of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - device_spec</emphasis> -; /* device ID */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbGetKeyboard"><primary><function>XkbGetKeyboard</function></primary></indexterm> +<funcsynopsis id="XkbGetKeyboard.20"> + <funcprototype> + <funcdef>XkbDescPtr <function>XkbGetKeyboard</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>which</parameter>, +<parameter>device_spec</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of components of <structname>XkbDescRec</structname> of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbGetKeyboard</emphasis> - is used to read the current description for one or more components of a -keyboard device. It calls <emphasis> -XkbGetKeyboardByName</emphasis> - as follows: +<function>XkbGetKeyboard</function> +is used to read the current description for one or more components of a +keyboard device. It calls +<function>XkbGetKeyboardByName</function> +as follows: </para> <para> -<emphasis> -XkbGetKeyboardByName</emphasis> -(<emphasis> -dpy</emphasis> -, <emphasis> -device_spec</emphasis> -, <emphasis> -NULL</emphasis> -, <emphasis> -which</emphasis> -, <emphasis> -which</emphasis> -, <emphasis> -False</emphasis> -). +<function>XkbGetKeyboardByName</function> +( +<parameter>dpy</parameter>, +<parameter>device_spec</parameter>, +<symbol>NULL</symbol>, +<parameter>which</parameter>, +<parameter>which</parameter>, +<symbol>False</symbol>). + </para> </sect1> diff --git a/libX11/specs/XKB/ch21.xml b/libX11/specs/XKB/ch21.xml index 7b2c653ba..7d122d92b 100644 --- a/libX11/specs/XKB/ch21.xml +++ b/libX11/specs/XKB/ch21.xml @@ -1,3 +1,6 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Attaching_Xkb_Actions_to_X_Input_Extension_Devices'> <title>Attaching Xkb Actions to X Input Extension Devices</title> @@ -10,8 +13,8 @@ input extension. Other types of devices supported by the input extension include, but are not limited to: mice, tablets, touchscreens, barcode readers, button boxes, trackballs, identifier devices, data gloves, and eye trackers. Xkb provides additional control over all X input extension devices, whether -they are <emphasis>KeyClass</emphasis> - devices or not, as well as the core keyboard and pointer. +they are <symbol>KeyClass</symbol> +devices or not, as well as the core keyboard and pointer. </para> @@ -58,16 +61,16 @@ the following additional access is provided: <itemizedlist> <listitem> <para> -If allowed, Xkb functionality for additional <emphasis> -KeyClass</emphasis> - devices supported by the input extension is accessed via those same functions. +If allowed, Xkb functionality for additional +<symbol>KeyClass</symbol> +devices supported by the input extension is accessed via those same functions. </para> </listitem> <listitem> <para> -If allowed, Xkb functionality for non-<emphasis> -KeyClass</emphasis> - devices supported by the input extension is also accessed via the +If allowed, Xkb functionality for non- +<symbol>KeyClass</symbol> +devices supported by the input extension is also accessed via the XkbGetDeviceInfo and XkbSetDeviceInfo functions described in this chapter. </para> </listitem> @@ -76,11 +79,11 @@ XkbGetDeviceInfo and XkbSetDeviceInfo functions described in this chapter. <para> Each device has an X Input Extension device ID. Each device may have several classes of feedback. For example, there are two types of feedbacks that can -generate bells: bell feedback and keyboard feedback (<emphasis> -BellFeedbackClass</emphasis> - and <emphasis> -KbdFeedbackClass</emphasis> -). A device can have more than one feedback of each type; the feedback ID +generate bells: bell feedback and keyboard feedback +(<symbol>BellFeedbackClass</symbol> +and +<symbol>KbdFeedbackClass</symbol>). +A device can have more than one feedback of each type; the feedback ID identifies the particular feedback within its class. </para> @@ -123,109 +126,107 @@ Up to 32 LEDs If the input extension is present and the server allows interaction between the input extension and Xkb, then the core keyboard, the core keyboard indicators, and the core keyboard bells may each be addressed using an appropriate device -spec, class, and ID. The constant <emphasis> -XkbXIDfltID</emphasis> - may be used as the device ID to specify the core keyboard indicators for the +spec, class, and ID. The constant +<symbol>XkbDfltXIId</symbol> +may be used as the device ID to specify the core keyboard indicators for the core indicator feedback. The particular device ID corresponding to the core keyboard feedback and the core indicator feedback may be obtained by calling -<emphasis> -XkbGetDeviceInfo</emphasis> - and specifying <emphasis> -XkbUseCoreKbd</emphasis> - as the <emphasis> -device_spec</emphasis> -; the values will be returned in <emphasis> -dflt_kbd_id</emphasis> - and <emphasis> -dflt_led_id</emphasis> -. -</para> - - -<para> -If the server does not allow Xkb access to input extension <emphasis> -KeyClass</emphasis> - devices, attempts to use Xkb requests with those devices fail with a -Bad<emphasis> -Keyboard</emphasis> - error. Attempts to access non-<emphasis> -KeyClass</emphasis> - input extension devices via XkbGetDeviceInfo and XkbSetDeviceInfo fail +<function>XkbGetDeviceInfo</function> +and specifying +<symbol>XkbUseCoreKbd</symbol> +as the +<parameter>device_spec</parameter>; +the values will be returned in +<structfield>dflt_kbd_fb</structfield> +and +<structfield>dflt_led_fb</structfield>. +</para> + + +<para> +If the server does not allow Xkb access to input extension +<symbol>KeyClass</symbol> +devices, attempts to use Xkb requests with those devices fail with a +<errorname>BadKeyboard</errorname> +error. Attempts to access non- +<symbol>KeyClass</symbol> +input extension devices via XkbGetDeviceInfo and XkbSetDeviceInfo fail silently if Xkb access to those devices is not supported by the X server. </para> <sect1 id='XkbDeviceInfoRec'> <title>XkbDeviceInfoRec</title> +<indexterm significance="preferred" zone="XkbDeviceInfoRec"> +<primary><structname>XkbDeviceInfoRec</structname></primary></indexterm> +<indexterm significance="preferred" zone="XkbDeviceInfoRec"> +<primary><structname>XkbDeviceLedInfoRec</structname></primary></indexterm> <para> Information about X Input Extension devices is transferred between a client -program and the Xkb extension in an <emphasis> -XkbDeviceInfoRec</emphasis> - structure: -</para> +program and the Xkb extension in an +<structname>XkbDeviceInfoRec</structname> +structure: -<para><programlisting> +<programlisting> typedef struct { - char * name; /* name for device */ - Atom type; /* name for class of devices */ - unsigned short device_spec; /* device of interest */ - Bool has_own_state; /* <emphasis> True</emphasis> =>this - device has its own state */ - unsigned short supported; /* bits indicating supported capabilities */ - unsigned short unsupported; /* bits indicating unsupported capabilities */ - unsigned short num_btns; /* number of entries in <emphasis> btn_acts</emphasis> */ - XkbAction * btn_acts; /* button actions */ - unsigned short sz_leds; /* total number of entries in LEDs vector */ - unsigned short num_leds; /* number of valid entries in LEDs vector */ - unsigned short dflt_kbd_fb; /* input extension ID of default (core kbd) indicator */ - unsigned short dflt_led_fb; /* input extension ID of default indicator feedback */ - XkbDeviceLedInfoPtr leds; /* LED descriptions */ -} <emphasis>XkbDeviceInfoRec</emphasis>, *XkbDeviceInfoPtr; -</programlisting></para> + char * name; /* name for device */ + Atom type; /* name for class of devices */ + unsigned short device_spec; /* device of interest */ + Bool has_own_state; /* <symbol>True</symbol> ⇒ this device has + its own state */ + unsigned short supported; /* bits indicating supported capabilities */ + unsigned short unsupported; /* bits indicating unsupported capabilities */ + unsigned short num_btns; /* number of entries in <structfield>btn_acts</structfield> */ + XkbAction * btn_acts; /* button actions */ + unsigned short sz_leds; /* total number of entries in LEDs vector */ + unsigned short num_leds; /* number of valid entries in LEDs vector */ + unsigned short dflt_kbd_fb; /* input extension ID of default + (core kbd) indicator */ + unsigned short dflt_led_fb; /* input extension ID of default + indicator feedback */ + XkbDeviceLedInfoPtr leds; /* LED descriptions */ +} <structname>XkbDeviceInfoRec</structname>, *XkbDeviceInfoPtr; -<para><programlisting> typedef struct { - unsigned short led_class; /* class for this LED device*/ - unsigned short led_id; /* ID for this LED device */ - unsigned int phys_indicators; /* bits for which LEDs physically - present */ - unsigned int maps_present; /* bits for which LEDs have maps in - <emphasis>maps</emphasis> */ - unsigned int names_present; /* bits for which LEDs are in - <emphasis> names</emphasis> */ - unsigned int state; /* 1 bit => corresponding LED is on */ - Atom names[XkbNumIndicators]; /* names for LEDs */ - XkbIndicatorMapRec maps; /* indicator maps for each LED */ -} <emphasis>XkbDeviceLedInfoRec</emphasis>, *XkbDeviceLedInfoPtr; + unsigned short led_class; /* class for this LED device */ + unsigned short led_id; /* ID for this LED device */ + unsigned int phys_indicators; /* bits for which LEDs physically present */ + unsigned int maps_present; /* bits for which LEDs have maps in <structfield>maps</structfield> */ + unsigned int names_present; /* bits for which LEDs are in <structfield>names</structfield> */ + unsigned int state; /* 1 bit ⇒ corresponding LED is on */ + Atom names[XkbNumIndicators]; /* names for LEDs */ + XkbIndicatorMapRec maps; /* indicator maps for each LED */ +} <structname>XkbDeviceLedInfoRec</structname>, *XkbDeviceLedInfoPtr; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field is a registered symbolic name for a class of devices (for example, -"TABLET"). If a device is a keyboard (that is, is a member of <emphasis> -KeyClass</emphasis> -), it has its own state, and <emphasis> -has_own_state</emphasis> - is <emphasis> -True</emphasis> -. If <emphasis> -has_own_state</emphasis> - is <emphasis> -False</emphasis> -, the state of the core keyboard is used. The <emphasis> -supported</emphasis> - and <emphasis> -unsupported</emphasis> - fields are masks where each bit indicates a capability. The meaning of the -mask bits is listed in Table 21.1, together with the fields in the <emphasis> -XkbDeviceInfoRec</emphasis> - structure that are associated with the capability represented by each bit. The +The +<structfield>type</structfield> +field is a registered symbolic name for a class of devices (for example, +"TABLET"). If a device is a keyboard (that is, is a member of +<symbol>KeyClass</symbol>), +it has its own state, and +<structfield>has_own_state</structfield> +is +<symbol>True</symbol>. +If +<structfield>has_own_state</structfield> +is +<symbol>False</symbol>, +the state of the core keyboard is used. The +<structfield>supported</structfield> +and +<structfield>unsupported</structfield> +fields are masks where each bit indicates a capability. The meaning of the +mask bits is listed in <link linkend="table21.1">Table 21.1</link>, +together with the fields in the +<structname>XkbDeviceInfoRec</structname> +structure that are associated with the capability represented by each bit. The same bits are used to indicate the specific information desired in many of the functions described subsequently in this section. </para> -<table frame='topbot'> +<table id='table21.1' frame='topbot'> <title>XkbDeviceInfoRec Mask Bits</title> <?dbfo keep-together="always" ?> <tgroup cols='4' align='left' colsep='0' rowsep='0'> @@ -243,60 +244,60 @@ functions described subsequently in this section. </thead> <tbody> <row> - <entry>XkbXI_KeyboardsMask</entry> + <entry><symbol>XkbXI_KeyboardsMask</symbol></entry> <entry></entry> <entry>(1L << 0)</entry> <entry> Clients can use all Xkb requests and events with -<emphasis>KeyClass</emphasis> +<symbol>KeyClass</symbol> devices supported by the input device extension. </entry> </row> <row> - <entry>XkbXI_ButtonActionsMask</entry> + <entry><symbol>XkbXI_ButtonActionsMask</symbol></entry> <entry> <para>num_btns</para> <para>btn_acts</para> </entry> <entry>(1L <<1)</entry> <entry> -Clients can assign key actions to buttons on non-<emphasis> -KeyClass</emphasis> +Clients can assign key actions to buttons on non- +<symbol>KeyClass</symbol> input extension devices. </entry> </row> <row> - <entry>XkbXI_IndicatorNamesMask</entry> + <entry><symbol>XkbXI_IndicatorNamesMask</symbol></entry> <entry>leds->names</entry> <entry>(1L <<2)</entry> <entry> -Clients can assign names to indicators on non-<emphasis> -KeyClass</emphasis> - input extension devices. +Clients can assign names to indicators on non- +<symbol>KeyClass</symbol> +input extension devices. </entry> </row> <row> - <entry>XkbXI_IndicatorMapsMask</entry> + <entry><symbol>XkbXI_IndicatorMapsMask</symbol></entry> <entry>leds->maps</entry> <entry>(1L <<3)</entry> <entry> -Clients can assign indicator maps to indicators on non-<emphasis> -KeyClass</emphasis> - input extension devices. +Clients can assign indicator maps to indicators on non- +<symbol>KeyClass</symbol> +input extension devices. </entry> </row> <row> - <entry>XkbXI_IndicatorStateMask</entry> + <entry><symbol>XkbXI_IndicatorStateMask</symbol></entry> <entry>leds->state</entry> <entry>(1L <<4)</entry> <entry> -Clients can request the status of indicators on non-<emphasis> -KeyClass</emphasis> - input extension devices. +Clients can request the status of indicators on non- +<symbol>KeyClass</symbol> +input extension devices. </entry> </row> <row> - <entry>XkbXI_IndicatorsMask</entry> + <entry><symbol>XkbXI_IndicatorsMask</symbol></entry> <entry> <para>sz_leds</para> <para>num_leds</para> @@ -304,42 +305,42 @@ KeyClass</emphasis> </entry> <entry>(0x1c)</entry> <entry> -<para>XkbXI_IndicatorNames­Mask |</para> -<para>XkbXI_IndicatorMaps­Mask |</para> -<para>XkbXI_IndicatorState­Mask</para> +<para><symbol>XkbXI_IndicatorNames­Mask</symbol> |</para> +<para><symbol>XkbXI_IndicatorMaps­Mask</symbol> |</para> +<para><symbol>XkbXI_IndicatorState­Mask</symbol></para> </entry> </row> <row> - <entry>XkbXI_UnsupportedFeaturesMask</entry> + <entry><symbol>XkbXI_UnsupportedFeaturesMask</symbol></entry> <entry>unsupported</entry> <entry>(1L <<15)</entry> <entry></entry> </row> <row> - <entry>XkbXI_AllDeviceFeaturesMask</entry> + <entry><symbol>XkbXI_AllDeviceFeaturesMask</symbol></entry> <entry>Those selected by Value column masks</entry> <entry>(0x1e)</entry> <entry> -<para>XkbXI_Indicators­Mask | </para> -<para>XkbSI_ButtonActions­Mask</para> +<para><symbol>XkbXI_Indicators­Mask</symbol> | </para> +<para><symbol>XkbXI_ButtonActions­Mask</symbol> </para> </entry> </row> <row> - <entry>XkbXI_AllFeaturesMask</entry> + <entry><symbol>XkbXI_AllFeaturesMask</symbol></entry> <entry>Those selected by Value column masks</entry> <entry>(0x1f)</entry> <entry> -<para>XkbSI_AllDevice­FeaturesMask |</para> -<para>XkbSI_Keyboards­Mask</para> +<para><symbol>XkbXI_AllDevice­FeaturesMask</symbol> | </para> +<para><symbol>XkbXI_Keyboards­Mask</symbol> </para> </entry> </row> <row> - <entry>XkbXI_AllDetailsMask</entry> + <entry><symbol>XkbXI_AllDetailsMask</symbol></entry> <entry>Those selected by Value column masks</entry> <entry>(0x801f)</entry> <entry> -<para>XkbXI_AllFeatures­Mask | </para> -<para>XkbXI_Unsupported­FeaturesMask</para> +<para><symbol>XkbXI_AllFeatures­Mask</symbol> | </para> +<para><symbol>XkbXI_Unsupported­FeaturesMask</symbol></para> </entry> </row> </tbody> @@ -347,20 +348,17 @@ KeyClass</emphasis> </table> <para> -The <emphasis> -name</emphasis> -, <emphasis> -type</emphasis> -, <emphasis> -has_own_state</emphasis> -, <emphasis> -supported</emphasis> -, and <emphasis> -unsupported</emphasis> - fields are always filled in when a valid reply is returned from the server -involving an <emphasis> -XkbDeviceInfoRec</emphasis> -. All of the other fields are modified only if the particular function asks for +The +<structfield>name</structfield>, +<structfield>type</structfield>, +<structfield>has_own_state</structfield>, +<structfield>supported</structfield>, +and +<structfield>unsupported</structfield> +fields are always filled in when a valid reply is returned from the server +involving an +<structname>XkbDeviceInfoRec</structname>. +All of the other fields are modified only if the particular function asks for them. </para> @@ -371,235 +369,242 @@ them. <para> To determine whether the X server allows Xkb access to particular capabilities of input devices other than the core X keyboard, or to determine the status of -indicator maps, indicator names or button actions on a non-<emphasis> -KeyClass</emphasis> - extension device, use XkbGetDeviceInfo. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbDeviceInfoPtr <emphasis> -XkbGetDeviceInfo</emphasis> -(<emphasis> -dpy</emphasis> -, which, device_spec, ind_class, ind_id) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int which; /* mask indicating information to -return */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -ind_class</emphasis> -; /* feedback class for indicator requests */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -ind_id</emphasis> -; /* feedback ID for indicator requests */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetDeviceInfo</emphasis> - returns information about the input device specified by <emphasis> -device_spec</emphasis> -. Unlike the <emphasis> -device_spec</emphasis> - parameter of most Xkb functions, <emphasis> -device_spec</emphasis> - does not need to be a keyboard device. It must, however, indicate either the +indicator maps, indicator names or button actions on a non- +<symbol>KeyClass</symbol> +extension device, use XkbGetDeviceInfo. +</para> + +<indexterm significance="preferred" zone="XkbGetDeviceInfo"><primary><function>XkbGetDeviceInfo</function></primary></indexterm> +<funcsynopsis id="XkbGetDeviceInfo"> + <funcprototype> + <funcdef>XkbDeviceInfoPtr <function>XkbGetDeviceInfo</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +which, device_spec, ind_class, ind_id) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>ind_class</parameter></paramdef> + <paramdef>unsigned int <parameter>ind_id</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask indicating information to return + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ind_class</parameter> + </term> + <listitem> + <para> + feedback class for indicator requests + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ind_id</parameter> + </term> + <listitem> + <para> + feedback ID for indicator requests + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetDeviceInfo</function> +returns information about the input device specified by +<parameter>device_spec</parameter>. +Unlike the +<parameter>device_spec</parameter> +parameter of most Xkb functions, +<parameter>device_spec</parameter> +does not need to be a keyboard device. It must, however, indicate either the core keyboard or a valid X Input Extension device. </para> <para> -The <emphasis> -which </emphasis> -parameter<emphasis> - </emphasis> +The +<parameter>which</parameter> +parameter is a mask specifying optional information to be returned. It is an inclusive OR -of one or more of the values from Table 21.1 and causes the returned <emphasis> -XkbDeviceInfoRec</emphasis> - to contain values for the corresponding fields specified in the table. +of one or more of the values from <link linkend="table21.1">Table 21.1</link> +and causes the returned +<structname>XkbDeviceInfoRec</structname> +to contain values for the corresponding fields specified in the table. </para> <para> -The <emphasis> -XkbDeviceInfoRec</emphasis> - returned by <emphasis> -XkbGetDeviceInfo</emphasis> - always has values for <emphasis> -name</emphasis> - (may be a null string, ""), <emphasis> -type</emphasis> -, <emphasis> -supported</emphasis> -, <emphasis> -unsupported</emphasis> -, <emphasis> -has_own_state</emphasis> -, <emphasis> -dflt_kbd_fd</emphasis> -, and <emphasis> -dflt_kbd_fb</emphasis> -. Other fields are filled in as specified by <emphasis> -which</emphasis> -. +The +<structname>XkbDeviceInfoRec</structname> +returned by +<function>XkbGetDeviceInfo</function> +always has values for +<structfield>name</structfield> +(may be a null string, ""), +<structfield>type</structfield>, +<structfield>supported</structfield>, +<structfield>unsupported</structfield>, +<structfield>has_own_state</structfield>, +<structfield>dflt_kbd_fb</structfield>, +and +<structfield>dflt_led_fb</structfield>. +Other fields are filled in as specified by +<parameter>which</parameter>. </para> <para> -Upon return, the <emphasis> -supported</emphasis> - field will be set to the inclusive OR of zero or more bits from Table 21.1; +Upon return, the +<structfield>supported</structfield> +field will be set to the inclusive OR of zero or more bits from +<link linkend="table21.1">Table 21.1</link>; each bit set indicates an optional Xkb extension device feature supported by the server implementation, and a client may modify the associated behavior. </para> <para> -If the <emphasis> -XkbButtonActionsMask</emphasis> - bit is set in <emphasis> -which</emphasis> -, the <emphasis> -XkbDeviceInfoRec</emphasis> - returned will have the button actions (<emphasis> -btn_acts</emphasis> - field) filled in for all buttons. +If the +<symbol>XkbXI_ButtonActionsMask</symbol> +bit is set in +<parameter>which</parameter>, +the +<structname>XkbDeviceInfoRec</structname> +returned will have the button actions +(<structfield>btn_acts</structfield> +field) filled in for all buttons. </para> <para> -If <emphasis> -which</emphasis> - includes one of the bits in XkbXI_IndicatorsMask, the feedback class of the +If +<parameter>which</parameter> +includes one of the bits in <symbol>XkbXI_IndicatorsMask</symbol>, +the feedback class of the indicators must be specified in ind_class, and the feedback ID of the indicators must be specified in ind_id. If the request does not include any of -the bits in XkbXI_IndicatorsMask, the ind_class and ind_id parameters are +the bits in <symbol>XkbXI_IndicatorsMask</symbol>, +the ind_class and ind_id parameters are ignored. The class and ID can be obtained via the input device extension XListInputDevices request. </para> <para> -If any of the <emphasis> -XkbXI_IndicatorsMask</emphasis> - bits are set in <emphasis> -which</emphasis> -, the <emphasis> -XkbDeviceInfoRec</emphasis> - returned will have filled in the portions of the <emphasis> -leds</emphasis> - structure corresponding to the indicator feedback identified by <emphasis> -ind_class</emphasis> - and <emphasis> -ind_id</emphasis> -. The <emphasis> -leds</emphasis> - vector of the <emphasis> -XkbDeviceInfoRec</emphasis> - is allocated if necessary and <emphasis> -sz_leds</emphasis> - and <emphasis> -num_leds</emphasis> - filled in. The <emphasis> -led_class</emphasis> -, <emphasis> -led_id</emphasis> - and <emphasis> -phys_indicators</emphasis> - fields of the <emphasis> -leds</emphasis> - entry corresponding to <emphasis> -ind_class</emphasis> - and <emphasis> -ind_id</emphasis> - are always filled in. If <emphasis> -which</emphasis> - contains <emphasis> -XkbXI_IndicatorNamesMask</emphasis> -, the <emphasis> -names_present</emphasis> - and <emphasis> -names</emphasis> - fields of the <emphasis> -leds</emphasis> - structure corresponding to <emphasis> -ind_class</emphasis> - and <emphasis> -ind_id</emphasis> - are returned.<emphasis> - </emphasis> -If <emphasis> -which</emphasis> - contains <emphasis> -XkbXI_IndicatorStateMask</emphasis> -<emphasis> -,</emphasis> - the corresponding <emphasis> -state</emphasis> - field is updated. If <emphasis> -which</emphasis> - contains <emphasis> -XkbXI_IndicatorMapsMask</emphasis> -, the <emphasis> -maps_present</emphasis> - and <emphasis> -maps</emphasis> - fields are updated. +If any of the +<symbol>XkbXI_IndicatorsMask</symbol> +bits are set in +<parameter>which</parameter>, +the +<structname>XkbDeviceInfoRec</structname> +returned will have filled in the portions of the +<structfield>leds</structfield> +structure corresponding to the indicator feedback identified by +<parameter>ind_class</parameter> +and +<parameter>ind_id</parameter>. +The +<structfield>leds</structfield> +vector of the +<structname>XkbDeviceInfoRec</structname> +is allocated if necessary and +<structfield>sz_leds</structfield> +and +<structfield>num_leds</structfield> +filled in. The +<structfield>led_class</structfield>, +<structfield>led_id</structfield> +and +<structfield>phys_indicators</structfield> +fields of the +<structfield>leds</structfield> +entry corresponding to +<parameter>ind_class</parameter> +and +<parameter>ind_id</parameter> +are always filled in. If +<parameter>which</parameter> +contains +<symbol>XkbXI_IndicatorNamesMask</symbol>, +the +<structfield>names_present</structfield> +and +<structfield>names</structfield> +fields of the +<structfield>leds</structfield> +structure corresponding to +<parameter>ind_class</parameter> +and +<parameter>ind_id</parameter> +are returned. +If +<parameter>which</parameter> +contains +<symbol>XkbXI_IndicatorStateMask</symbol>, +the corresponding +<structfield>state</structfield> +field is updated. If +<parameter>which</parameter> +contains +<symbol>XkbXI_IndicatorMapsMask</symbol>, +the +<structfield>maps_present</structfield> +and +<structfield>maps</structfield> +fields are updated. </para> <para> Xkb provides convenience functions to request subsets of the information -available via <emphasis> -XkbGetDeviceInfo</emphasis> -. These convenience functions mirror some of the mask bits. The functions all -take an <emphasis> -XkbDeviceInfoPtr</emphasis> - as an input argument and operate on the X Input Extension device specified by -the <emphasis> -device_spec</emphasis> - field of the structure. Only the parts of the structure indicated in the -function description are updated. The <emphasis> -XkbDeviceInfo</emphasis> -Rec structure used in the function call can be obtained by calling -XkbGetDeviceInfo or can be allocated by calling XkbAllocDeviceInfo (see section -21.3). +available via +<function>XkbGetDeviceInfo</function>. +These convenience functions mirror some of the mask bits. The functions all +take an +<type>XkbDeviceInfoPtr</type> +as an input argument and operate on the X Input Extension device specified by +the +<parameter>device_spec</parameter> +field of the structure. Only the parts of the structure indicated in the +function description are updated. The +<structname>XkbDeviceInfoRec</structname> +structure used in the function call can be obtained by calling +XkbGetDeviceInfo or can be allocated by calling XkbAllocDeviceInfo +(see <link linkend="Allocating_Initializing_and_Freeing_the_XkbDeviceInfoRecStructure">section 21.3</link>). </para> @@ -614,131 +619,137 @@ XkbGetDeviceButtonActions. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetDeviceButtonActions</emphasis> -(<emphasis> -dpy, device_info, all_buttons, first_button, num_buttons</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr device_info; /* structure to update with -results */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> -all_buttons</emphasis> -; /* <emphasis> -True</emphasis> - => get information for all buttons */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int first_button; /* number of first button for -which info is desired */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int num_buttons; /* number of buttons for which -info is desired */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetDeviceButtonActions</emphasis> - queries the server for the desired button information for the device indicated -by the <emphasis> -device_spec</emphasis> - field of <emphasis> -device_info</emphasis> - and waits for a reply. If successful,<emphasis> - XkbGetDeviceButtonActions</emphasis> - backfills the button actions (<emphasis> -btn_acts</emphasis> - field of <emphasis> -device_info</emphasis> -) for only the requested buttons, updates the <emphasis> -name</emphasis> -, <emphasis> -type</emphasis> -, <emphasis> -supported</emphasis> -, and <emphasis> -unsupported</emphasis> - fields, and returns <emphasis> -Success</emphasis> -. -</para> - - -<para> -<emphasis> -all_buttons</emphasis> -, <emphasis> -first_button</emphasis> - and <emphasis> -num_buttons</emphasis> - specify the device buttons for which actions should be returned. Setting -<emphasis> -all_buttons</emphasis> - to <emphasis> -True</emphasis> - requests actions for all device buttons; if <emphasis> -all_buttons</emphasis> - is <emphasis> -False</emphasis> -, <emphasis> -first_button</emphasis> - and <emphasis> -num_buttons</emphasis> - specify a range of buttons for which actions are requested. +<indexterm significance="preferred" zone="XkbGetDeviceButtonActions"><primary><function>XkbGetDeviceButtonActions</function></primary></indexterm> +<funcsynopsis id="XkbGetDeviceButtonActions"> + <funcprototype> + <funcdef>Status <function>XkbGetDeviceButtonActions</function></funcdef> +<!-- ( +<parameter>dpy, device_info, all_buttons, first_button, num_buttons</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + <paramdef>Bool <parameter>all_buttons</parameter></paramdef> + <paramdef>unsigned int <parameter>first_button</parameter></paramdef> + <paramdef>unsigned int <parameter>num_buttons</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + structure to update with results + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>all_buttons</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ get information for all buttons + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first_button</parameter> + </term> + <listitem> + <para> + number of first button for which info is desired + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_buttons</parameter> + </term> + <listitem> + <para> + number of buttons for which info is desired + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetDeviceButtonActions</function> +queries the server for the desired button information for the device indicated +by the +<structfield>device_spec</structfield> +field of +<parameter>device_info</parameter> +and waits for a reply. If successful, +<function>XkbGetDeviceButtonActions</function> +backfills the button actions +(<structfield>btn_acts</structfield> +field of +<parameter>device_info</parameter>) +for only the requested buttons, updates the +<structfield>name</structfield>, +<structfield>type</structfield>, +<structfield>supported</structfield>, +and +<structfield>unsupported</structfield> +fields, and returns +<symbol>Success</symbol>. +</para> + + +<para> +<parameter>all_buttons</parameter>, +<parameter>first_button</parameter> +and +<parameter>num_buttons</parameter> +specify the device buttons for which actions should be returned. Setting +<parameter>all_buttons</parameter> +to +<symbol>True</symbol> +requests actions for all device buttons; if +<parameter>all_buttons</parameter> +is +<symbol>False</symbol>, +<parameter>first_button</parameter> +and +<parameter>num_buttons</parameter> +specify a range of buttons for which actions are requested. </para> <para> If a compatible version of Xkb is not available in the server or the Xkb extension has not been properly initialized, XkbGetDeviceButtonActions returns -<emphasis> -BadAccess</emphasis> -. If allocation errors occur, a <emphasis> -BadAlloc</emphasis> - status is returned. If the specified device (<emphasis> -device_info</emphasis> --><emphasis> -device_spec</emphasis> -) is invalid, a BadKeyboard status is returned. If the device has no buttons, a -Bad<emphasis> -Match</emphasis> - status is returned. If <emphasis> -first_button</emphasis> - and <emphasis> -num_buttons</emphasis> - specify illegal buttons, a Bad<emphasis> -Value</emphasis> - status is returned. +<errorname>BadAccess</errorname>. +If allocation errors occur, a +<errorname>BadAlloc</errorname> +status is returned. If the specified device +(<parameter>device_info</parameter>-><structfield>device_spec</structfield>) +is invalid, a +<errorname>BadKeyboard</errorname> +status is returned. If the device has no buttons, a +<errorname>BadMatch</errorname> +status is returned. If +<parameter>first_button</parameter> +and +<parameter>num_buttons</parameter> +specify illegal buttons, a +<errorname>BadValue</errorname> +status is returned. </para> @@ -748,181 +759,192 @@ of an input extension device, use XkbGetDeviceLedInfo. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetDeviceLedInfo</emphasis> -(<emphasis> -dpy, device_i</emphasis> -nfo, led_class, led_id, which) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr device_info; /* structure to update with -results */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -led_class</emphasis> -; /* LED feedback class assigned by input extension */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int led_id; /* LED feedback ID assigned by input -extension */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int which; /* mask indicating desired -information */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetDeviceLedInfo</emphasis> - queries the server for the desired LED information for the feedback specified -by <emphasis> -led_class</emphasis> - and <emphasis> -led_id</emphasis> - for the X input extension device indicated by <emphasis> -device_spec</emphasis> --><emphasis> -device_info</emphasis> - and waits for a reply. If successful, <emphasis> -XkbGetDeviceLedInfo</emphasis> - backfills the relevant fields of <emphasis> -device_info</emphasis> - as determined by <emphasis> -which</emphasis> - with the results and returns <emphasis> -Success</emphasis> -. Valid values for <emphasis> -which</emphasis> - are the inclusive OR of any of <emphasis> -XkbXI_IndicatorNamesMask</emphasis> -, <emphasis> -XkbXI_IndicatorMapsMask</emphasis> -, and <emphasis> -XkbXI_IndicatorStateMask</emphasis> -. -</para> - - -<para> -The fields of <emphasis> -device_info</emphasis> - that are filled in when this request succeeds are <emphasis> -name, type, supported</emphasis> -, and <emphasis> -unsupported</emphasis> -, and portions of the <emphasis> -leds</emphasis> - structure corresponding to <emphasis> -led_class</emphasis> - and <emphasis> -led_id</emphasis> - as indicated by the bits set in <emphasis> -which</emphasis> -. The <emphasis> -device_info->leds</emphasis> - vector is allocated if necessary and <emphasis> -sz_leds</emphasis> - and <emphasis> -num_leds</emphasis> - filled in. The <emphasis> -led_class</emphasis> -, <emphasis> -led_id</emphasis> - and <emphasis> -phys_indicators</emphasis> - fields of the <emphasis> -device_info</emphasis> --><emphasis> -leds</emphasis> - entry corresponding to <emphasis> -led_class</emphasis> - and <emphasis> -led_id</emphasis> - are always filled in. -</para> - - -<para> -If <emphasis> -which</emphasis> - contains <emphasis> -XkbXI_IndicatorNamesMask</emphasis> -, the <emphasis> -names_present</emphasis> - and <emphasis> -names</emphasis> - fields of the <emphasis> -device_info</emphasis> --><emphasis> -leds</emphasis> - structure corresponding to <emphasis> -led_class</emphasis> - and <emphasis> -led_id</emphasis> - are updated, if <emphasis> -which</emphasis> - contains <emphasis> -XkbXI_IndicatorStateMask</emphasis> -<emphasis> -,</emphasis> - the corresponding <emphasis> -state</emphasis> - field is updated, and if <emphasis> -which</emphasis> - contains <emphasis> -XkbXI_IndicatorMapsMask</emphasis> -, the <emphasis> -maps_present</emphasis> - and <emphasis> -maps</emphasis> - fields are updated. +<indexterm significance="preferred" zone="XkbGetDeviceLedInfo"><primary><function>XkbGetDeviceLedInfo</function></primary></indexterm> +<funcsynopsis id="XkbGetDeviceLedInfo"> + <funcprototype> + <funcdef>Status <function>XkbGetDeviceLedInfo</function></funcdef> +<!-- ( +<parameter>dpy, device_i</parameter> +nfo, led_class, led_id, which) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + <paramdef>unsigned int <parameter>led_class</parameter></paramdef> + <paramdef>unsigned int <parameter>led_id</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + structure to update with results + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>led_class</parameter> + </term> + <listitem> + <para> + LED feedback class assigned by input extension + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>led_id</parameter> + </term> + <listitem> + <para> + LED feedback ID assigned by input extension + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask indicating desired information + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetDeviceLedInfo</function> +queries the server for the desired LED information for the feedback specified +by +<parameter>led_class</parameter> +and +<parameter>led_id</parameter> +for the X input extension device indicated by +<structfield>device_spec</structfield>-><parameter>device_info</parameter> +and waits for a reply. If successful, +<function>XkbGetDeviceLedInfo</function> +backfills the relevant fields of +<parameter>device_info</parameter> +as determined by +<parameter>which</parameter> +with the results and returns +<symbol>Success</symbol>. +Valid values for +<parameter>which</parameter> +are the inclusive OR of any of +<symbol>XkbXI_IndicatorNamesMask</symbol>, +<symbol>XkbXI_IndicatorMapsMask</symbol>, +and +<symbol>XkbXI_IndicatorStateMask</symbol>. +</para> + + +<para> +The fields of +<parameter>device_info</parameter> +that are filled in when this request succeeds are +<structfield>name</structfield>, +<structfield>type</structfield>, +<structfield>supported</structfield>, +and +<structfield>unsupported</structfield>, +and portions of the +<structfield>leds</structfield> +structure corresponding to +<parameter>led_class</parameter> +and +<parameter>led_id</parameter> +as indicated by the bits set in +<parameter>which</parameter>. +The +<structfield>device_info->leds</structfield> +vector is allocated if necessary and +<structfield>sz_leds</structfield> +and +<structfield>num_leds</structfield> +filled in. The +<parameter>led_class</parameter>, +<parameter>led_id</parameter> +and +<structfield>phys_indicators</structfield> +fields of the +<parameter>device_info</parameter>-><structfield>leds</structfield> +entry corresponding to +<parameter>led_class</parameter> +and +<parameter>led_id</parameter> +are always filled in. +</para> + + +<para> +If +<parameter>which</parameter> +contains +<symbol>XkbXI_IndicatorNamesMask</symbol>, +the +<structfield>names_present</structfield> +and +<structfield>names</structfield> +fields of the +<parameter>device_info</parameter>-><structfield>leds</structfield> +structure corresponding to +<parameter>led_class</parameter> +and +<parameter>led_id</parameter> +are updated, if +<parameter>which</parameter> +contains +<symbol>XkbXI_IndicatorStateMask</symbol>, +the corresponding +<structfield>state</structfield> +field is updated, and if +<parameter>which</parameter> +contains +<symbol>XkbXI_IndicatorMapsMask</symbol>, +the +<structfield>maps_present</structfield> +and +<structfield>maps</structfield> +fields are updated. </para> <para> If a compatible version of Xkb is not available in the server or the Xkb -extension has not been properly initialized, <emphasis> -XkbGetDeviceLedInfo</emphasis> - returns <emphasis> -BadAccess</emphasis> -. If allocation errors occur, a BadAlloc status is returned. If the device has -no indicators, a BadMatch error is returned. If <emphasis> -ledClass</emphasis> - or <emphasis> -ledID</emphasis> - have illegal values, a Bad<emphasis> -Value</emphasis> - error is returned. If they have legal values but do not specify a feedback -that contains LEDs and is associated with the specified device, a Bad<emphasis> -Match</emphasis> - error is returned. +extension has not been properly initialized, +<function>XkbGetDeviceLedInfo</function> +returns +<errorname>BadAccess</errorname>. +If allocation errors occur, a +<errorname>BadAlloc</errorname> +status is returned. If the device has no indicators, a +<errorname>BadMatch</errorname> +error is returned. If +<structfield>ledClass</structfield> +or +<structfield>ledID</structfield> +have illegal values, a +<errorname>BadValue</errorname> +error is returned. If they have legal values but do not specify a feedback +that contains LEDs and is associated with the specified device, a +<errorname>BadMatch</errorname> +error is returned. </para> @@ -932,396 +954,396 @@ Match</emphasis> Structure</title> <para> -To obtain an <emphasis> -XkbDeviceInfoRec</emphasis> - structure, use XkbGetDeviceInfo or XkbAllocDeviceInfo. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbDeviceInfoPtr <emphasis> -XkbAllocDeviceInfo</emphasis> -(device_spec, n_buttons, sz_leds) - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int device_spec; /* device ID with which -structure will be used */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -n_buttons</emphasis> -; /* number of button actions to allocate space for*/ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -sz_leds</emphasis> -; /* number of LED feedbacks to allocate space for */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocDeviceInfo</emphasis> - allocates space for an <emphasis> -XkbDeviceInfoRec</emphasis> - structure and initializes that structure’s <emphasis> -device_spec</emphasis> - field with the device ID specified by device_spec. If <emphasis> -n_buttons</emphasis> - is nonzero, <emphasis> -n_buttons</emphasis> - <emphasis> -XkbActions</emphasis> - are linked into the <emphasis> -XkbDeviceInfoRec</emphasis> - structure and initialized to zero. If sz_leds is nonzero, <emphasis> -sz_leds</emphasis> - <emphasis> -XkbDeviceLedInfoRec</emphasis> - structures are also allocated and linked into the <emphasis> -XkbDeviceInfoRec</emphasis> - structure. If you request <emphasis> -XkbDeviceLedInfoRec</emphasis> - structures be allocated using this request, you must initialize them +To obtain an +<structname>XkbDeviceInfoRec</structname> +structure, use XkbGetDeviceInfo or XkbAllocDeviceInfo. +</para> + +<indexterm significance="preferred" zone="XkbAllocDeviceInfo"><primary><function>XkbAllocDeviceInfo</function></primary></indexterm> +<funcsynopsis id="XkbAllocDeviceInfo"> + <funcprototype> + <funcdef>XkbDeviceInfoPtr <function>XkbAllocDeviceInfo</function></funcdef> +<!-- (device_spec, n_buttons, sz_leds) --> + + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>n_buttons</parameter></paramdef> + <paramdef>unsigned int <parameter>sz_leds</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID with which structure will be used + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>n_buttons</parameter> + </term> + <listitem> + <para> + number of button actions to allocate space for + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>sz_leds</parameter> + </term> + <listitem> + <para> + number of LED feedbacks to allocate space for + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocDeviceInfo</function> +allocates space for an +<structname>XkbDeviceInfoRec</structname> +structure and initializes that structure’s +<parameter>device_spec</parameter> +field with the device ID specified by device_spec. If +<parameter>n_buttons</parameter> +is nonzero, +<parameter>n_buttons</parameter> +<structname>XkbAction</structname>s +are linked into the +<structname>XkbDeviceInfoRec</structname> +structure and initialized to zero. If sz_leds is nonzero, +<parameter>sz_leds</parameter> +<structname>XkbDeviceLedInfoRec</structname> +structures are also allocated and linked into the +<structname>XkbDeviceInfoRec</structname> +structure. If you request +<structname>XkbDeviceLedInfoRec</structname> +structures be allocated using this request, you must initialize them explicitly. </para> <para> -To obtain an <emphasis> -XkbDeviceLedInfoRec</emphasis> - structure, use XkbAllocDeviceLedInfo. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocDeviceLedInfo</emphasis> -(devi, num_needed) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr <emphasis> -device_info</emphasis> -; /* structure in which to allocate LED space */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -num_needed</emphasis> -; /* number of indicators to allocate space for */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocDeviceLedInfo</emphasis> - allocates space for an <emphasis> -XkbDeviceLedInfoRec</emphasis> - and places it in <emphasis> -device_info</emphasis> -. If num_needed is nonzero, <emphasis> -num_needed</emphasis> - <emphasis> -XkbIndicatorMapRec</emphasis> - structures are also allocated and linked into the <emphasis> -XkbDeviceLedInfoRec</emphasis> - structure. If you request <emphasis> -XkbIndicatorMapRec</emphasis> - structures be allocated using this request, you must initialize them +To obtain an +<structname>XkbDeviceLedInfoRec</structname> +structure, use XkbAllocDeviceLedInfo. +</para> + + +<indexterm significance="preferred" zone="XkbAllocDeviceLedInfo"><primary><function>XkbAllocDeviceLedInfo</function></primary></indexterm> +<funcsynopsis id="XkbAllocDeviceLedInfo"> + <funcprototype> + <funcdef>Status <function>XkbAllocDeviceLedInfo</function></funcdef> +<!-- (devi, num_needed) --> + + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + <paramdef>int <parameter>num_needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + structure in which to allocate LED space + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_needed</parameter> + </term> + <listitem> + <para> + number of indicators to allocate space for + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocDeviceLedInfo</function> +allocates space for an +<structname>XkbDeviceLedInfoRec</structname> +and places it in +<parameter>device_info</parameter>. +If num_needed is nonzero, +<parameter>num_needed</parameter> +<structname>XkbIndicatorMapRec</structname> +structures are also allocated and linked into the +<structname>XkbDeviceLedInfoRec</structname> +structure. If you request +<structname>XkbIndicatorMapRec</structname> +structures be allocated using this request, you must initialize them explicitly. All other fields are initialized to zero. </para> <para> -To initialize an <emphasis> -XkbDeviceLedInfoRec</emphasis> - structure, use XkbAddDeviceLedInfo. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbDeviceLedInfoPtr <emphasis> -XkbAddDeviceLedInfo</emphasis> -(device_info, led_class, led_id) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr device_info; /* structure in which to -add LED info */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -led_class</emphasis> -; /* input extension class for LED device of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -led_id</emphasis> -; /* input extension ID for LED device of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAddDeviceLedInfo</emphasis> - first checks to see whether an entry matching <emphasis> -led_class</emphasis> - and <emphasis> -led_id</emphasis> - already exists in the <emphasis> -device_info->leds</emphasis> - array. If it finds a matching entry, it returns a pointer to that entry. -Otherwise, it checks to be sure there is at least one empty entry in <emphasis> -device_info</emphasis> --><emphasis> -leds</emphasis> - and extends it if there is not enough room. It then increments <emphasis> -device_info</emphasis> --><emphasis> -num_leds</emphasis> - and fills in the next available entry in <emphasis> -device_info</emphasis> --><emphasis> -leds</emphasis> - with <emphasis> -led_class</emphasis> - and <emphasis> -led_id</emphasis> -. -</para> - - -<para> -If successful, <emphasis> -XkbAddDeviceLedInfo</emphasis> - returns a pointer to the <emphasis> -XkbDeviceLedInfoRec</emphasis> - structure that was initialized. If unable to allocate sufficient storage, or -if <emphasis> -device_info</emphasis> - points to an invalid <emphasis> -XkbDeviceInfoRec</emphasis> - structure, or if <emphasis> -led_class</emphasis> - or <emphasis> -led_id</emphasis> - are inappropriate, <emphasis> -XkbAddDeviceLedInfo</emphasis> - returns <emphasis> -NULL</emphasis> -. -</para> - - -<para> -To allocate additional space for button actions in an <emphasis> -XkbDeviceInfoRec</emphasis> - structure, use XkbResizeDeviceButtonActions. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbResizeDeviceButtonActions</emphasis> -(device_info, new_total) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr device_info; /* structure in which to -allocate button actions */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -new_total</emphasis> -; /* new total number of button actions needed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbResizeDeviceButton</emphasis> - reallocates space, if necessary, to make sure there is room for a total of -<emphasis> -new_total</emphasis> - button actions in the <emphasis> -device_info</emphasis> - structure. Any new entries allocated are zeroed. If successful, <emphasis> -XkbResizeDeviceButton</emphasis> - returns Success. If new_total is zero, all button actions are deleted, -<emphasis> -device_info</emphasis> --><emphasis> -num_btns</emphasis> - is set to zero, and <emphasis> -device_info</emphasis> --><emphasis> -btn_acts</emphasis> - is set to <emphasis> -NULL</emphasis> -. If device_info is invalid or new_total is greater than 255, BadValue is -returned. If a memory allocation failure occurs, a <emphasis> -BadAlloc</emphasis> - is returned. -</para> - - -<para> -To free an <emphasis> -XkbDeviceInfoRec</emphasis> - structure, use XkbFreeDeviceInfo. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeDeviceInfo</emphasis> -(device_info, which, free_all) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr device_info; /* pointer to <emphasis> -XkbDeviceInfoRec</emphasis> - in which to free items */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -which</emphasis> -; /* mask of components of <emphasis> -device_info</emphasis> - to free */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> -free_all</emphasis> -; /* <emphasis> -True</emphasis> - => free everything, including device_info */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -If free_all is <emphasis> -True</emphasis> -, the <emphasis> -XkbFreeDeviceInfo</emphasis> - frees all components of <emphasis> -device_info</emphasis> - and the <emphasis> -XkbDeviceInfoRec</emphasis> - structure pointed to by <emphasis> -device_info</emphasis> - itself. If free_all is <emphasis> -False</emphasis> -, the value of which determines which subcomponents are freed. <emphasis> -which </emphasis> -is an inclusive OR of one or more of the values from Table 21.1. If which -contains XkbXI_ButtonActionsMask, all button actions associated with <emphasis> -device_info</emphasis> - are freed, <emphasis> -device_info</emphasis> --><emphasis> -btn_acts</emphasis> - is set to <emphasis> -NULL</emphasis> -, and <emphasis> -device_info</emphasis> --><emphasis> -num_btns</emphasis> - is set to zero. If which contains all bits in XkbXI_IndicatorsMask, all -<emphasis> -XkbDeviceLedInfoRec</emphasis> - structures associated with <emphasis> -device_info</emphasis> - are freed, <emphasis> -device_info</emphasis> --><emphasis> -leds</emphasis> - is set to <emphasis> -NULL</emphasis> -, and <emphasis> -device_info</emphasis> --><emphasis> -sz_leds</emphasis> - and <emphasis> -device_info</emphasis> --><emphasis> -num_leds</emphasis> - are set to zero. If which contains XkbXI_IndicatorMapsMask, all indicator maps -associated with <emphasis> -device_info</emphasis> - are cleared, but the number of LEDs and the leds structures themselves are -preserved. If which contains XkbXI_IndicatorNamesMask, all indicator names +To initialize an +<structname>XkbDeviceLedInfoRec</structname> +structure, use XkbAddDeviceLedInfo. +</para> + + +<indexterm significance="preferred" zone="XkbAddDeviceLedInfo"><primary><function>XkbAddDeviceLedInfo</function></primary></indexterm> +<funcsynopsis id="XkbAddDeviceLedInfo"> + <funcprototype> + <funcdef>XkbDeviceLedInfoPtr <function>XkbAddDeviceLedInfo</function></funcdef> +<!-- (device_info, led_class, led_id) --> + + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + <paramdef>unsigned int <parameter>led_class</parameter></paramdef> + <paramdef>unsigned int <parameter>led_id</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + structure in which to add LED info + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>led_class</parameter> + </term> + <listitem> + <para> + input extension class for LED device of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>led_id</parameter> + </term> + <listitem> + <para> + input extension ID for LED device of interest + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAddDeviceLedInfo</function> +first checks to see whether an entry matching +<parameter>led_class</parameter> +and +<parameter>led_id</parameter> +already exists in the +<structfield>device_info->leds</structfield> +array. If it finds a matching entry, it returns a pointer to that entry. +Otherwise, it checks to be sure there is at least one empty entry in +<parameter>device_info</parameter>-><structfield>leds</structfield> +and extends it if there is not enough room. It then increments +<parameter>device_info</parameter>-><structfield>num_leds</structfield> +and fills in the next available entry in +<parameter>device_info</parameter>-><structfield>leds</structfield> +with +<parameter>led_class</parameter> +and +<parameter>led_id</parameter>. +</para> + + +<para> +If successful, +<function>XkbAddDeviceLedInfo</function> +returns a pointer to the +<structname>XkbDeviceLedInfoRec</structname> +structure that was initialized. If unable to allocate sufficient storage, or +if +<parameter>device_info</parameter> +points to an invalid +<structname>XkbDeviceInfoRec</structname> +structure, or if +<parameter>led_class</parameter> +or +<parameter>led_id</parameter> +are inappropriate, +<function>XkbAddDeviceLedInfo</function> +returns +<symbol>NULL</symbol>. +</para> + + +<para> +To allocate additional space for button actions in an +<structname>XkbDeviceInfoRec</structname> +structure, use XkbResizeDeviceButtonActions. +</para> + + +<indexterm significance="preferred" zone="XkbResizeDeviceButtonActions"><primary><function>XkbResizeDeviceButtonActions</function></primary></indexterm> +<funcsynopsis id="XkbResizeDeviceButtonActions"> + <funcprototype> + <funcdef>Status <function>XkbResizeDeviceButtonActions</function></funcdef> +<!-- (device_info, new_total) --> + + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + <paramdef>unsigned int <parameter>new_total</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + structure in which to allocate button actions + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>new_total</parameter> + </term> + <listitem> + <para> + new total number of button actions needed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbResizeDeviceButtonActions</function> +reallocates space, if necessary, to make sure there is room for a total of +<parameter>new_total</parameter> +button actions in the +<parameter>device_info</parameter> +structure. Any new entries allocated are zeroed. If successful, +<function>XkbResizeDeviceButtonActions</function> +returns Success. If new_total is zero, all button actions are deleted, +<parameter>device_info</parameter>-><structfield>num_btns</structfield> +is set to zero, and +<parameter>device_info</parameter>-><structfield>btn_acts</structfield> +is set to +<symbol>NULL</symbol>. +If device_info is invalid or new_total is greater than 255, +<errorname>BadValue</errorname> +is returned. If a memory allocation failure occurs, a +<errorname>BadAlloc</errorname> +is returned. +</para> + + +<para> +To free an +<structname>XkbDeviceInfoRec</structname> +structure, use XkbFreeDeviceInfo. +</para> + + +<indexterm significance="preferred" zone="XkbFreeDeviceInfo"><primary><function>XkbFreeDeviceInfo</function></primary></indexterm> +<funcsynopsis id="XkbFreeDeviceInfo"> + <funcprototype> + <funcdef>void <function>XkbFreeDeviceInfo</function></funcdef> +<!-- (device_info, which, free_all) --> + + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + pointer to <structname>XkbDeviceInfoRec</structname> in which to free items + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of components of <parameter>device_info</parameter> to free + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ free everything, including device_info + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If free_all is +<symbol>True</symbol>, +the +<function>XkbFreeDeviceInfo</function> +frees all components of +<parameter>device_info</parameter> +and the +<structname>XkbDeviceInfoRec</structname> +structure pointed to by +<parameter>device_info</parameter> +itself. If free_all is +<symbol>False</symbol>, +the value of which determines which subcomponents are freed. +<parameter>which</parameter> +is an inclusive OR of one or more of the values from +<link linkend="table21.1">Table 21.1</link>. If which +contains <symbol>XkbXI_ButtonActionsMask</symbol>, +all button actions associated with +<parameter>device_info</parameter> +are freed, +<parameter>device_info</parameter>-><structfield>btn_acts</structfield> +is set to +<symbol>NULL</symbol>, +and +<parameter>device_info</parameter>-><structfield>num_btns</structfield> +is set to zero. If which contains all bits in +<symbol>XkbXI_IndicatorsMask</symbol>, all +<structname>XkbDeviceLedInfoRec</structname> +structures associated with +<parameter>device_info</parameter> +are freed, +<parameter>device_info</parameter>-><structfield>leds</structfield> +is set to +<symbol>NULL</symbol>, +and +<parameter>device_info</parameter>-><structfield>sz_leds</structfield> +and +<parameter>device_info</parameter>-><structfield>num_leds</structfield> +are set to zero. If which contains <symbol>XkbXI_IndicatorMapsMask</symbol>, +all indicator maps associated with +<parameter>device_info</parameter> +are cleared, but the number of LEDs and the leds structures themselves are +preserved. If which contains <symbol>XkbXI_IndicatorNamesMask</symbol>, +all indicator names associated with device_info are cleared, but the number of LEDs and the leds structures themselves are preserved. If which contains -XkbXI_IndicatorStateMask, the indicator state associated with the <emphasis> -device_info</emphasis> - leds are set to zeros but the number of LEDs and the leds structures +<symbol>XkbXI_IndicatorStateMask</symbol>, +the indicator state associated with the +<parameter>device_info</parameter> +leds are set to zeros but the number of LEDs and the leds structures themselves are preserved. </para> @@ -1349,13 +1371,13 @@ core X keyboard. Xkb implementations are required to support key actions for the buttons of the core pointer device, but support for actions on extension devices is optional. Implementations that do not support button actions for extension devices must -not set the <emphasis> -XkbXI_ButtonActionsMask</emphasis> - bit in the <emphasis> -supported</emphasis> - field of an <emphasis> -XkbDeviceInfoRec</emphasis> - structure. +not set the +<symbol>XkbXI_ButtonActionsMask</symbol> +bit in the +<structfield>supported</structfield> +field of an +<structname>XkbDeviceInfoRec</structname> +structure. </para> @@ -1363,22 +1385,22 @@ XkbDeviceInfoRec</emphasis> If a client attempts to modify valid characteristics of a device using an implementation that does not support modification of those characteristics, no protocol error is generated. Instead, the server reports a failure for the -request; it also sends an <emphasis> -XkbExtensionDeviceNotify</emphasis> - event to the client that issued the request if the client has selected to +request; it also sends an +<symbol>XkbExtensionDeviceNotify</symbol> +event to the client that issued the request if the client has selected to receive these events. </para> <para> To change characteristics of an X Input Extension device in the server, first -modify a local copy of the device structure and then use either <emphasis> -XkbSetDeviceInfo,</emphasis> - or, to save network traffic, use an <emphasis> -XkbDeviceChangesRec</emphasis> - structure (see section 21.6) and call <emphasis> -XkbChangeDeviceInfo</emphasis> - to download the changes to the server. +modify a local copy of the device structure and then use either +<function>XkbSetDeviceInfo</function>, +or, to save network traffic, use an +<structname>XkbDeviceChangesRec</structname> +structure (see <link linkend="Tracking_Changes_to_Extension_Devices">section 21.6</link>) and call +<function>XkbChangeDeviceInfo</function> +to download the changes to the server. </para> @@ -1387,130 +1409,128 @@ To modify some or all of the characteristics of an X Input Extension device, use XkbSetDeviceInfo. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetDeviceInfo</emphasis> -(<emphasis> -dpy</emphasis> -, which, device_info) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -which</emphasis> -; /* mask indicating characteristics to modify */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr device_info; /* structure defining the -device and modifications */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetDeviceInfo</emphasis> - sends a request to the server to modify the characteristics of the device -specified in the <emphasis> -device_info</emphasis> - structure. The particular characteristics modified are identified by the bits -set in <emphasis> -which</emphasis> - and take their values from the relevant fields in <emphasis> -device_info</emphasis> - (see Table 21.1). <emphasis> -XkbSetDeviceInfo</emphasis> - returns <emphasis> -True</emphasis> - if the request was successfully sent to the server. If the X server +<indexterm significance="preferred" zone="XkbSetDeviceInfo"><primary><function>XkbSetDeviceInfo</function></primary></indexterm> +<funcsynopsis id="XkbSetDeviceInfo"> + <funcprototype> + <funcdef>Bool <function>XkbSetDeviceInfo</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +which, device_info) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask indicating characteristics to modify + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + structure defining the device and modifications + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetDeviceInfo</function> +sends a request to the server to modify the characteristics of the device +specified in the +<parameter>device_info</parameter> +structure. The particular characteristics modified are identified by the bits +set in +<parameter>which</parameter> +and take their values from the relevant fields in +<parameter>device_info</parameter> +(see <link linkend="table21.1">Table 21.1</link>). +<function>XkbSetDeviceInfo</function> +returns +<symbol>True</symbol> +if the request was successfully sent to the server. If the X server implementation does not allow interaction between the X input extension and the -Xkb Extension, the function does nothing and returns <emphasis> -False</emphasis> -. +Xkb Extension, the function does nothing and returns +<symbol>False</symbol>. </para> <para> -The <emphasis> -which</emphasis> - parameter specifies which aspects of the device should be changed and is a +The +<parameter>which</parameter> +parameter specifies which aspects of the device should be changed and is a bitmask composed of an inclusive OR or one or more of the following bits: -<emphasis> -XkbXI_ButtonActionsMask</emphasis> -, <emphasis> -XkbXI_IndicatorNamesMask</emphasis> -, <emphasis> -XkbXI_IndicatorMapsMask</emphasis> -. If the features requested to be manipulated in <emphasis> -which</emphasis> - are valid for the device, but the server does not support assignment of one or +<symbol>XkbXI_ButtonActionsMask</symbol>, +<symbol>XkbXI_IndicatorNamesMask</symbol>, +<symbol>XkbXI_IndicatorMapsMask</symbol>. +If the features requested to be manipulated in +<parameter>which</parameter> +are valid for the device, but the server does not support assignment of one or more of them, that particular portion of the request is ignored. </para> <para> -If the device specified in <emphasis> -device_info</emphasis> --><emphasis> -device_spec</emphasis> - does not contain buttons and a request affecting buttons is made, or the +If the device specified in +<parameter>device_info</parameter>-><structfield>device_spec</structfield> +does not contain buttons and a request affecting buttons is made, or the device does not contain indicators and a request affecting indicators is made, -a <emphasis> -BadMatch</emphasis> - protocol error results. +a +<errorname>BadMatch</errorname> +protocol error results. </para> <para> -If the <emphasis> -XkbXI_ButtonActionsMask</emphasis> - bit is set in the supported mask returned by XkbGetDeviceInfo, the Xkb +If the +<symbol>XkbXI_ButtonActionsMask</symbol> +bit is set in the supported mask returned by XkbGetDeviceInfo, the Xkb extension allows applications to assign key actions to buttons on input -extension devices other than the core keyboard device. If the <emphasis> -XkbXI_ButtonActionsMask</emphasis> - is set in <emphasis> -which</emphasis> -, the actions for all buttons specified in device_info are set to the <emphasis> -XkbAction</emphasis> -s specified in <emphasis> -device_info</emphasis> --><emphasis> -btn_acts</emphasis> -. If the number of buttons requested to be updated is not valid for the device, -<emphasis> -XkbSetDeviceInfo</emphasis> - returns <emphasis> -False</emphasis> - and a <emphasis> -BadValue</emphasis> - protocol error results. -</para> - - -<para> -If the <emphasis> -XkbXI_IndicatorMaps</emphasis> - and / or <emphasis> -XkbXI_IndicatorNamesMask</emphasis> - bit is set in the supported mask returned by XkbGetDeviceInfo, the Xkb +extension devices other than the core keyboard device. If the +<symbol>XkbXI_ButtonActionsMask</symbol> +is set in +<parameter>which</parameter>, +the actions for all buttons specified in device_info are set to the +<structname>XkbAction</structname>s +specified in +<parameter>device_info</parameter>-><structfield>btn_acts</structfield>. +If the number of buttons requested to be updated is not valid for the device, +<function>XkbSetDeviceInfo</function> +returns +<symbol>False</symbol> +and a +<errorname>BadValue</errorname> +protocol error results. +</para> + + +<para> +If the +<symbol>XkbXI_IndicatorMapsMask</symbol> +and / or +<symbol>XkbXI_IndicatorNamesMask</symbol> +bit is set in the supported mask returned by XkbGetDeviceInfo, the Xkb extension allows applications to assign maps and / or names to the indicators of nonkeyboard extension devices. If supported, maps and / or names can be assigned to all extension device indicators, whether they are part of a @@ -1519,63 +1539,46 @@ keyboard feedback or part of an indicator feedback. <para> -If the <emphasis> -XkbXI_IndicatorMapsMask</emphasis> - and / or <emphasis> -XkbXI_IndicatorNamesMask</emphasis> - flag is set in <emphasis> -which</emphasis> -, the indicator maps and / or names for all <emphasis> -device_info</emphasis> --><emphasis> -num_leds</emphasis> - indicator devices specified in <emphasis> -device_info</emphasis> --><emphasis> -leds</emphasis> - are set to the maps and / or names specified in <emphasis> -device_info</emphasis> --><emphasis> -leds</emphasis> -. <emphasis> -device_info</emphasis> --><emphasis> -leds</emphasis> --><emphasis> -led_class</emphasis> - and <emphasis> -led_id</emphasis> - specify the input extension class and device ID for each indicator device to -modify; if they have invalid values, a <emphasis> -BadValue</emphasis> - protocol error results and <emphasis> -XkbSetDeviceInfo</emphasis> - returns <emphasis> -False</emphasis> -. If they have legal values but do not specify a keyboard or indicator class -feedback for the device in question, a <emphasis> -BadMatch</emphasis> - error results. If any of the values in <emphasis> -device_info</emphasis> --><emphasis> -leds</emphasis> -<emphasis> --></emphasis> -<emphasis> -names</emphasis> - are not a valid Atom or <emphasis> -None</emphasis> -, a <emphasis> -BadAtom</emphasis> - protocol error results. +If the +<symbol>XkbXI_IndicatorMapsMask</symbol> +and / or +<symbol>XkbXI_IndicatorNamesMask</symbol> +flag is set in +<parameter>which</parameter>, +the indicator maps and / or names for all +<parameter>device_info</parameter>-><structfield>num_leds</structfield> +indicator devices specified in +<parameter>device_info</parameter>-><structfield>leds</structfield> +are set to the maps and / or names specified in +<parameter>device_info</parameter>-><structfield>leds</structfield>. +<parameter>device_info</parameter>-><structfield>leds</structfield>-><structfield>led_class</structfield> +and +<structfield>led_id</structfield> +specify the input extension class and device ID for each indicator device to +modify; if they have invalid values, a +<errorname>BadValue</errorname> +protocol error results and +<function>XkbSetDeviceInfo</function> +returns +<symbol>False</symbol>. +If they have legal values but do not specify a keyboard or indicator class +feedback for the device in question, a +<errorname>BadMatch</errorname> +error results. If any of the values in +<parameter>device_info</parameter>-><structfield>leds->names</structfield> +are not a valid Atom or +<symbol>None</symbol>, +a +<errorname>BadAtom</errorname> +protocol error results. </para> <para> Xkb provides convenience functions to modify subsets of the information -accessible via <emphasis> -XkbSetDeviceInfo</emphasis> -. Only the parts of the structure indicated in the function description are +accessible via +<function>XkbSetDeviceInfo</function>. +Only the parts of the structure indicated in the function description are modified. These convenience functions are described as follows. </para> @@ -1586,118 +1589,124 @@ XkbSetDeviceButtonActions. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetDeviceButtonActions</emphasis> -(<emphasis> -dpy</emphasis> -, device, first_button, num_buttons, actions) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr device_info; /* structure defining the -device and modifications */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int first_button; /* number of first button to -update, 0 relative */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int num_buttons; /* number of buttons to update -*/ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetDeviceButtonActions</emphasis> - assigns actions to the buttons of the device specified in -device_info-><emphasis> -device_spec</emphasis> -. Actions are assigned to <emphasis> -num_buttons</emphasis> - buttons beginning with <emphasis> -first_button</emphasis> - and are taken from the actions specified in <emphasis> -device_info</emphasis> --><emphasis> -btn_acts</emphasis> -. +<indexterm significance="preferred" zone="XkbSetDeviceButtonActions"><primary><function>XkbSetDeviceButtonActions</function></primary></indexterm> +<funcsynopsis id="XkbSetDeviceButtonActions"> + <funcprototype> + <funcdef>Bool <function>XkbSetDeviceButtonActions</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +device, first_button, num_buttons, actions) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + <paramdef>unsigned int <parameter>first_button</parameter></paramdef> + <paramdef>unsigned int <parameter>num_buttons</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + structure defining the device and modifications + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first_button</parameter> + </term> + <listitem> + <para> + number of first button to update, 0 relative + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_buttons</parameter> + </term> + <listitem> + <para> + number of buttons to update + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetDeviceButtonActions</function> +assigns actions to the buttons of the device specified in +device_info-><structfield>device_spec</structfield>. +Actions are assigned to +<parameter>num_buttons</parameter> +buttons beginning with +<parameter>first_button</parameter> +and are taken from the actions specified in +<parameter>device_info</parameter>-><structfield>btn_acts</structfield>. </para> <para> If the server does not support assignment of Xkb actions to extension device -buttons, <emphasis> -XkbSetDeviceButtonActions</emphasis> - has no effect and returns <emphasis> -False</emphasis> -. If the device has no buttons or if <emphasis> -first_button</emphasis> - or <emphasis> -num_buttons</emphasis> - specify buttons outside of the valid range as determined by <emphasis> -device_info</emphasis> --><emphasis> -num_btns</emphasis> -, the function has no effect and returns <emphasis> -False</emphasis> -. Otherwise, <emphasis> -XkbSetDeviceButtonActions</emphasis> - sends a request to the server to change the actions for the specified buttons -and returns <emphasis> -True</emphasis> -. +buttons, +<function>XkbSetDeviceButtonActions</function> +has no effect and returns +<symbol>False</symbol>. +If the device has no buttons or if +<parameter>first_button</parameter> +or +<parameter>num_buttons</parameter> +specify buttons outside of the valid range as determined by +<parameter>device_info</parameter>-><structfield>num_btns</structfield>, +the function has no effect and returns +<symbol>False</symbol>. +Otherwise, +<function>XkbSetDeviceButtonActions</function> +sends a request to the server to change the actions for the specified buttons +and returns +<symbol>True</symbol>. </para> <para> If the actual request sent to the server involved illegal button numbers, a -<emphasis> -BadValue</emphasis> - protocol error is generated. If an invalid device identifier is specified in -device_info-><emphasis> -device_spec</emphasis> -, a BadKeyboard protocol error results. If the actual device specified in -<emphasis> -device_info</emphasis> --><emphasis> -device_spec</emphasis> - does not contain buttons and a request affecting buttons is made, a <emphasis> -BadMatch</emphasis> - protocol error is generated. +<errorname>BadValue</errorname> +protocol error is generated. If an invalid device identifier is specified in +device_info-><structfield>device_spec</structfield>, +a <errorname>BadKeyboard</errorname> +protocol error results. If the actual device specified in +<parameter>device_info</parameter>-><structfield>device_spec</structfield> +does not contain buttons and a request affecting buttons is made, a +<errorname>BadMatch</errorname> +protocol error is generated. </para> </sect1> <sect1 id='XkbExtensionDeviceNotify_Event'> <title>XkbExtensionDeviceNotify Event</title> +<indexterm significance="preferred" zone="XkbExtensionDeviceNotify_Event"> +<primary>events</primary><secondary><symbol>XkbExtensionDeviceNotify</symbol></secondary></indexterm> +<indexterm significance="preferred" zone="XkbExtensionDeviceNotify_Event"> +<primary><structname>XkbExtensionDeviceNotifyEvent</structname></primary></indexterm> <para> -The Xkb extension generates <emphasis> -XkbExtensionDeviceNotify</emphasis> - events when the status of an input extension device changes or when an attempt +The Xkb extension generates +<symbol>XkbExtensionDeviceNotify</symbol> +events when the status of an input extension device changes or when an attempt is made to use an Xkb feature that is not supported by a particular device. </para> @@ -1706,86 +1715,81 @@ delivered only to the client requesting the event.</para></note> <para> To track changes to the status of input extension devices or attempts to use -unsupported features of a device, select to receive <emphasis> -XkbExtensionDeviceNotify</emphasis> - events by calling either <emphasis> -XkbSelectEvents</emphasis> - or <emphasis> -XkbSelectEventDetails</emphasis> - (see section 4.3). +unsupported features of a device, select to receive +<symbol>XkbExtensionDeviceNotify</symbol> +events by calling either +<function>XkbSelectEvents</function> +or +<function>XkbSelectEventDetails</function> +(see <link linkend="Selecting_Xkb_Events">section 4.3</link>). </para> <para> -To receive <emphasis> -XkbExtensionDeviceNotify</emphasis> - events under all possible conditions, call <emphasis> -XkbSelectEvents</emphasis> - and pass <emphasis> -XkbExtensionDeviceNotifyMask</emphasis> - in both <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> -. +To receive +<symbol>XkbExtensionDeviceNotify</symbol> +events under all possible conditions, call +<function>XkbSelectEvents</function> +and pass +<symbol>XkbExtensionDeviceNotifyMask</symbol> +in both +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter>. </para> <para> -The <emphasis> -XkbExtensionDeviceNotify</emphasis> - event has no event details. However, you can call <emphasis> -XkbSelectEventDetails</emphasis> - using <emphasis> -XkbExtensionDeviceNotify</emphasis> - as the <emphasis> -event_type</emphasis> - and specifying <emphasis> -XkbAllExtensionDeviceMask</emphasis> - in <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits.</emphasis> - This has the same effect as a call to <emphasis> -XkbSelectEvents</emphasis> -. +The +<symbol>XkbExtensionDeviceNotify</symbol> +event has no event details. However, you can call +<function>XkbSelectEventDetails</function> +using +<symbol>XkbExtensionDeviceNotify</symbol> +as the +<structfield>event_type</structfield> +and specifying +<symbol>XkbAllExtensionDeviceEventsMask</symbol> +in +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter>. +This has the same effect as a call to +<function>XkbSelectEvents</function>. </para> <para> -The structure for <emphasis> -XkbExtensionDeviceNotify</emphasis> - events is: -</para> +The structure for +<symbol>XkbExtensionDeviceNotify</symbol> +events is: -<para><programlisting> +<programlisting> typedef struct { - int type; /* Xkb extension base event code */ - unsigned long serial; /* X server serial number for event */ - Bool send_event; /* <emphasis>True</emphasis> - => synthetically generated*/ - Display * display; /* server connection where event generated */ - Time time; /* server time when event generated */ - int xkb_type; /* <emphasis>XkbExtensionDeviceNotifyEvent</emphasis> */ - int device; /* Xkb device ID, will not be - <emphasis>XkbUseCoreKbd</emphasis> */ - unsigned int reason; /* reason for the event */ - unsigned int supported; /* mask of supported features */ - unsigned int unsupported; /* unsupported features this client + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* <symbol>True</symbol> ⇒ synthetically generated */ + Display * display; /* server connection where event generated */ + Time time; /* server time when event generated */ + int xkb_type; /* <structname>XkbExtensionDeviceNotifyEvent</structname> */ + int device; /* Xkb device ID, will not be <symbol>XkbUseCoreKbd</symbol> */ + unsigned int reason; /* reason for the event */ + unsigned int supported; /* mask of supported features */ + unsigned int unsupported; /* unsupported features this client attempted to use */ - int first_btn; /* first button that changed */ - int num_btns; /* number of buttons that changed */ - unsigned int leds_defined; /* indicators with names or maps */ - unsigned int led_state; /* current state of the indicators */ - int led_class; /* feedback class for LED changes */ - int led_id; /* feedback ID for LED changes */ -} <emphasis>XkbExtensionDeviceNotifyEvent</emphasis>; + int first_btn; /* first button that changed */ + int num_btns; /* number of buttons that changed */ + unsigned int leds_defined; /* indicators with names or maps */ + unsigned int led_state; /* current state of the indicators */ + int led_class; /* feedback class for LED changes */ + int led_id; /* feedback ID for LED changes */ +} <structname>XkbExtensionDeviceNotifyEvent</structname>; </programlisting></para> <para> -The <emphasis> -XkbExtensionDeviceNotify</emphasis> - event has fields enabling it to report changes in the state (on/off) of all of +The +<symbol>XkbExtensionDeviceNotify</symbol> +event has fields enabling it to report changes in the state (on/off) of all of the buttons for a device, but only for one LED feedback associated with a device. You will get multiple events when more than one LED feedback changes state or configuration. @@ -1795,43 +1799,44 @@ state or configuration. </sect1> <sect1 id='Tracking_Changes_to_Extension_Devices'> <title>Tracking Changes to Extension Devices</title> +<indexterm significance="preferred" zone="Tracking_Changes_to_Extension_Devices"> +<primary><structname>XkbDeviceChangesRec</structname></primary></indexterm> +<indexterm significance="preferred" zone="Tracking_Changes_to_Extension_Devices"> +<primary><structname>XkbDeviceLedChangesRec</structname></primary></indexterm> <para> -Changes to an Xkb extension device may be tracked by listening to <emphasis> -XkbDeviceExtensionNotify</emphasis> - events and accumulating the changes in an <emphasis> -XkbDeviceChangesRec</emphasis> - structure. The changes noted in the structure may then be used in subsequent +Changes to an Xkb extension device may be tracked by listening to +<symbol>XkbExtensionDeviceNotify</symbol> +events and accumulating the changes in an +<structname>XkbDeviceChangesRec</structname> +structure. The changes noted in the structure may then be used in subsequent operations to update either a server configuration or a local copy of an Xkb extension device configuration. The changes structure is defined as follows: -</para> -<para><programlisting> +<programlisting> typedef struct _XkbDeviceChanges { - unsigned int changed; /* bits indicating what has changed */ - unsigned short first_btn; /* number of first button which changed, - if any */ - unsigned short num_btns; /* number of buttons that have changed */ - XkbDeviceLedChangesRec leds; -} <emphasis>XkbDeviceChangesRec</emphasis>,*XkbDeviceChangesPtr; -</programlisting></para> + unsigned int changed; /* bits indicating what has changed */ + unsigned short first_btn; /* number of first button which changed, + if any */ + unsigned short num_btns; /* number of buttons that have changed */ + XkbDeviceLedChangesRec leds; +} <structname>XkbDeviceChangesRec</structname>, *XkbDeviceChangesPtr; -<para><programlisting> typedef struct _XkbDeviceLedChanges { - unsigned short led_class; /* class of this indicator feedback bundle */ - unsigned short led_id; /* ID of this indicator feedback bundle */ - unsigned int names; /* bits indicating which names have changed */ - unsigned int maps; /* bits indicating which maps have changed */ - struct _XkbDeviceLedChanges *next; /* link to indicator change record - for next set */ -} <emphasis>XkbDeviceLedChangesRec</emphasis>,*XkbDeviceLedChangesPtr; + unsigned short led_class; /* class of this indicator feedback bundle */ + unsigned short led_id; /* ID of this indicator feedback bundle */ + unsigned int names; /* bits indicating which names have changed */ + unsigned int maps; /* bits indicating which maps have changed */ + struct _XkbDeviceLedChanges *next; /* link to indicator change record + for next set */ +} <structname>XkbDeviceLedChangesRec</structname>, *XkbDeviceLedChangesPtr; </programlisting></para> <para> A local description of the configuration and state of a device may be kept in -an <emphasis> -XkbDeviceInfoRec</emphasis> - structure. The actual state or configuration of the device may change because +an +<structname>XkbDeviceInfoRec</structname> +structure. The actual state or configuration of the device may change because of XkbSetDeviceInfo and XkbSetButtonActions requests made by clients or by user interaction with the device. The X server sends an XkbExtensionDeviceNotify event to all interested clients when the state of any buttons or indicators or @@ -1847,81 +1852,84 @@ server. <para> -To note device changes reported in an <emphasis> -XkbExtensionDeviceNotify</emphasis> - event, use XkbNoteDeviceChanges. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbNoteDeviceChanges</emphasis> - (<emphasis> -old, new, wanted</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceChangesPtr <emphasis> -old</emphasis> -; /* structure tracking state changes */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbExtensionDeviceNotifyEvent * <emphasis> -new</emphasis> -; /* event indicating state changes */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -wanted</emphasis> -; /* mask indicating changes to note */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -The wanted field specifies the changes that should be noted in <emphasis> -old</emphasis> -, and is composed of the bitwise inclusive OR of one or more of the masks from -Table 21.1<emphasis> -.</emphasis> - The <emphasis> -reason</emphasis> - field of the event in <emphasis> -new</emphasis> - indicates the types of changes the event is reporting. <emphasis> -XkbNoteDeviceChanges</emphasis> - updates the <emphasis> -XkbDeviceChangesRec</emphasis> - specified by <emphasis> -old</emphasis> - with the changes that are both specified in <emphasis> -wanted</emphasis> - and contained in <emphasis> -new</emphasis> --><emphasis> -reason</emphasis> -. +To note device changes reported in an +<symbol>XkbExtensionDeviceNotify</symbol> +event, use XkbNoteDeviceChanges. +</para> + +<indexterm significance="preferred" zone="XkbNoteDeviceChanges"><primary><function>XkbNoteDeviceChanges</function></primary></indexterm> +<funcsynopsis id="XkbNoteDeviceChanges"> + <funcprototype> + <funcdef>void <function>XkbNoteDeviceChanges</function></funcdef> +<!-- ( +<parameter>old, new, wanted</parameter> +) --> + + <paramdef>XkbDeviceChangesPtr <parameter>old</parameter></paramdef> + <paramdef>XkbExtensionDeviceNotifyEvent *<parameter>new</parameter></paramdef> + <paramdef>unsigned int <parameter>wanted</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>old</parameter> + </term> + <listitem> + <para> + structure tracking state changes + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>new</parameter> + </term> + <listitem> + <para> + event indicating state changes + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>wanted</parameter> + </term> + <listitem> + <para> + mask indicating changes to note + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The wanted field specifies the changes that should be noted in +<parameter>old</parameter>, +and is composed of the bitwise inclusive OR of one or more of the masks from +<link linkend="table21.1">Table 21.1</link>. +The +<structfield>reason</structfield> +field of the event in +<parameter>new</parameter> +indicates the types of changes the event is reporting. +<function>XkbNoteDeviceChanges</function> +updates the +<structname>XkbDeviceChangesRec</structname> +specified by +<parameter>old</parameter> +with the changes that are both specified in +<parameter>wanted</parameter> +and contained in +<parameter>new</parameter>-><structfield>reason</structfield>. </para> <para> To update a local copy of the state and configuration of an X input extension -device with the changes previously noted in an <emphasis> -XkbDeviceChangesRec</emphasis> - structure, use XkbGetDeviceInfoChanges. +device with the changes previously noted in an +<structname>XkbDeviceChangesRec</structname> +structure, use XkbGetDeviceInfoChanges. </para> @@ -1932,62 +1940,66 @@ XkbGetDeviceInfoChanges. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetDeviceInfoChanges</emphasis> -(<emphasis> -dpy</emphasis> -, <emphasis> -device_info</emphasis> -, changes) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr device_info; /* structure to update with -results */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceChangesPtr <emphasis> -changes</emphasis> -; /* contains notes of changes that have occurred */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbGetDeviceInfoChanges"><primary><function>XkbGetDeviceInfoChanges</function></primary></indexterm> +<funcsynopsis id="XkbGetDeviceInfoChanges"> + <funcprototype> + <funcdef>Status <function>XkbGetDeviceInfoChanges</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>device_info</parameter>, +changes) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + <paramdef>XkbDeviceChangesPtr <parameter>changes</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + structure to update with results + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + contains notes of changes that have occurred + </para> + </listitem> + </varlistentry> +</variablelist> <para> The changes->changed field indicates which attributes of the device -specified in <emphasis> -changes</emphasis> --><emphasis> -device</emphasis> - have changed. The parameters describing the changes are contained in the other -fields of <emphasis> -changes</emphasis> -. <emphasis> -XkbGetDeviceInfoChanges</emphasis> - uses that information to call XkbGetDeviceInfo to obtain the current status of +specified in +<parameter>changes</parameter>-><structfield>device</structfield> +have changed. The parameters describing the changes are contained in the other +fields of +<parameter>changes</parameter>. +<function>XkbGetDeviceInfoChanges</function> +uses that information to call XkbGetDeviceInfo to obtain the current status of those attributes that have changed. It then updates the local description of -the device in <emphasis> -device_info</emphasis> - with the new information. +the device in +<parameter>device_info</parameter> +with the new information. </para> @@ -1997,59 +2009,61 @@ XkbDeviceChangesRec, use XkbChangeDeviceInfo. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbChangeDeviceInfo</emphasis> - (<emphasis> -dpy, device_info, changes</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr <emphasis> -device_info</emphasis> -; /* local copy of device state and configuration */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceChangesPtr <emphasis> -changes</emphasis> -; /* note specifying changes in <emphasis> -device_info</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbChangeDeviceInfo</emphasis> - updates the server’s description of the device specified in <emphasis> -device_info</emphasis> --><emphasis> -device_spec</emphasis> - with the changes specified in <emphasis> -changes</emphasis> - and contained in <emphasis> -device_info</emphasis> -. The update is made by an XkbSetDeviceInfo request. +<indexterm significance="preferred" zone="XkbChangeDeviceInfo"><primary><function>XkbChangeDeviceInfo</function></primary></indexterm> +<funcsynopsis id="XkbChangeDeviceInfo"> + <funcprototype> + <funcdef>Bool <function>XkbChangeDeviceInfo</function></funcdef> +<!-- ( +<parameter>dpy, device_info, changes</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + <paramdef>XkbDeviceChangesPtr <parameter>changes</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + local copy of device state and configuration + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + note specifying changes in <parameter>device_info</parameter> + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbChangeDeviceInfo</function> +updates the server’s description of the device specified in +<parameter>device_info</parameter>-><structfield>device_spec</structfield> +with the changes specified in +<parameter>changes</parameter> +and contained in +<parameter>device_info</parameter>. +The update is made by an XkbSetDeviceInfo request. </para> </sect1> diff --git a/libX11/specs/XKB/ch22.xml b/libX11/specs/XKB/ch22.xml index 4dea73387..4a3981afa 100644 --- a/libX11/specs/XKB/ch22.xml +++ b/libX11/specs/XKB/ch22.xml @@ -1,3 +1,6 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Debugging_Aids'> <title>Debugging Aids</title> @@ -15,153 +18,175 @@ Both bitmasks are initially all zeros. <para> -To change the values of any of the debug controls, use <emphasis> -XkbSetDebuggingFlags</emphasis> -. +To change the values of any of the debug controls, use +<function>XkbSetDebuggingFlags</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetDebuggingFlags</emphasis> -(<emphasis> -display, mask, flags, msg, ctrls_mask, ctrls, ret_flags, ret_ctrls</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - mask</emphasis> -; /* mask selecting debug output flags to change */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - flags</emphasis> -; /* values for debug output flags selected by <emphasis> -mask</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -char * <emphasis> - msg</emphasis> -; /* message to print right now */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -ctrls_mask</emphasis> -; /* mask selecting debug controls to change */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -ctrls</emphasis> -; /* values for debug controls selected by <emphasis> -ctrls_mask</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> - ret_flags</emphasis> -; /* resulting state of all debug output flags */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -ret_ctrls</emphasis> -; /* resulting state of all debug controls */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbSetDebuggingFlags"><primary><function>XkbSetDebuggingFlags</function></primary></indexterm> +<funcsynopsis id="XkbSetDebuggingFlags"> + <funcprototype> + <funcdef>Bool <function>XkbSetDebuggingFlags</function></funcdef> +<!-- ( +<parameter>display, mask, flags, msg, ctrls_mask, ctrls, ret_flags, ret_ctrls</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>mask</parameter></paramdef> + <paramdef>unsigned int <parameter>flags</parameter></paramdef> + <paramdef>char *<parameter>msg</parameter></paramdef> + <paramdef>unsigned int <parameter>ctrls_mask</parameter></paramdef> + <paramdef>unsigned int <parameter>ctrls</parameter></paramdef> + <paramdef>unsigned int *<parameter>ret_flags</parameter></paramdef> + <paramdef>unsigned int *<parameter>ret_ctrls</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>mask</parameter> + </term> + <listitem> + <para> + mask selecting debug output flags to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>flags</parameter> + </term> + <listitem> + <para> + values for debug output flags selected by <parameter>mask</parameter> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>msg</parameter> + </term> + <listitem> + <para> + message to print right now + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ctrls_mask</parameter> + </term> + <listitem> + <para> + mask selecting debug controls to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ctrls</parameter> + </term> + <listitem> + <para> + values for debug controls selected by <parameter>ctrls_mask</parameter> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ret_flags</parameter> + </term> + <listitem> + <para> + resulting state of all debug output flags + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ret_ctrls</parameter> + </term> + <listitem> + <para> + resulting state of all debug controls + </para> + </listitem> + </varlistentry> +</variablelist> <para> -<emphasis> -XkbSetDebuggingFlags</emphasis> - modifies the debug output flags as specified by <emphasis> -mask</emphasis> - and <emphasis> -flags</emphasis> -, modifies the debug controls flags as specified by <emphasis> -ctrls_mask</emphasis> - and <emphasis> -ctrls</emphasis> -, prints the message <emphasis> -msg</emphasis> -, and backfills <emphasis> -ret_flags</emphasis> - and <emphasis> -ret_ctrls</emphasis> - with the resulting debug output and debug controls flags. +<function>XkbSetDebuggingFlags</function> +modifies the debug output flags as specified by +<parameter>mask</parameter> +and +<parameter>flags</parameter>, +modifies the debug controls flags as specified by +<parameter>ctrls_mask</parameter> +and +<parameter>ctrls</parameter>, +prints the message +<parameter>msg</parameter>, +and backfills +<parameter>ret_flags</parameter> +and +<parameter>ret_ctrls</parameter> +with the resulting debug output and debug controls flags. </para> <para> -When bits are set in the debug output masks, <emphasis> -mask</emphasis> - and <emphasis> -flags</emphasis> -, Xkb prints debug information corresponding to each bit at appropriate points +When bits are set in the debug output masks, +<parameter>mask</parameter> +and +<parameter>flags</parameter>, +Xkb prints debug information corresponding to each bit at appropriate points during its processing. The device to which the output is written is implementation-dependent, but is normally the same device to which X server -error messages are directed; thus the bits that can be set in <emphasis> -mask</emphasis> - and <emphasis> -flags</emphasis> - is implementation-specific. To turn on a debug output selection, set the bit -for the output in the <emphasis> -mask</emphasis> - parameter and set the corresponding bit in the <emphasis> -flags</emphasis> - parameter. To turn off event selection for an event, set the bit for the -output in the <emphasis> -mask</emphasis> - parameter and do not set the corresponding bit in the <emphasis> -flags</emphasis> - parameter. +error messages are directed; thus the bits that can be set in +<parameter>mask</parameter> +and +<parameter>flags</parameter> +is implementation-specific. To turn on a debug output selection, set the bit +for the output in the +<parameter>mask</parameter> +parameter and set the corresponding bit in the +<parameter>flags</parameter> +parameter. To turn off event selection for an event, set the bit for the +output in the +<parameter>mask</parameter> +parameter and do not set the corresponding bit in the +<parameter>flags</parameter> +parameter. </para> <para> -When bits are set in the debug controls masks, <emphasis> -ctrls_mask</emphasis> - and <emphasis> -ctrls</emphasis> -, Xkb modifies its behavior according to each controls bit. <emphasis> -ctrls_mask</emphasis> - and <emphasis> -ctrls</emphasis> - are related in the same way that <emphasis> -mask</emphasis> - and <emphasis> -flags</emphasis> - are. The valid controls bits are defined in Table 22.1. +When bits are set in the debug controls masks, +<parameter>ctrls_mask</parameter> +and +<parameter>ctrls</parameter>, +Xkb modifies its behavior according to each controls bit. +<parameter>ctrls_mask</parameter> +and +<parameter>ctrls</parameter> +are related in the same way that +<parameter>mask</parameter> +and +<parameter>flags</parameter> +are. The valid controls bits are defined in +<link linkend="table22.1">Table 22.1</link>. </para> -<table frame='topbot'> +<table id='table22.1' frame='topbot'> <title>Debug Control Masks</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -177,7 +202,7 @@ flags</emphasis> </thead> <tbody> <row> - <entry>XkbDF_DisableLocks</entry> + <entry><symbol>XkbDF_DisableLocks</symbol></entry> <entry>(1 << 0)</entry> <entry>Disable actions that lock modifiers</entry> </row> @@ -186,32 +211,30 @@ flags</emphasis> </table> <para> -<emphasis> -XkbSetDebuggingFlags</emphasis> - returns <emphasis> -True</emphasis> - if successful and <emphasis> -False</emphasis> - otherwise. The only protocol error it may generate is <emphasis> -BadAlloc</emphasis> -, if for some reason it is unable to allocate storage. +<function>XkbSetDebuggingFlags</function> +returns +<symbol>True</symbol> +if successful and +<symbol>False</symbol> +otherwise. The only protocol error it may generate is +<errorname>BadAlloc</errorname>, +if for some reason it is unable to allocate storage. </para> <para> -<emphasis> -XkbSetDebuggingFlags</emphasis> - is intended for developer use and may be disabled in production X servers. If -it is disabled, <emphasis> -XkbSetDebuggingFlags</emphasis> - has no effect and does not generate any protocol errors. +<function>XkbSetDebuggingFlags</function> +is intended for developer use and may be disabled in production X servers. If +it is disabled, +<function>XkbSetDebuggingFlags</function> +has no effect and does not generate any protocol errors. </para> <para> -The message in <emphasis> -msg</emphasis> - is written immediately. The device to which it is written is implementation +The message in +<parameter>msg</parameter> +is written immediately. The device to which it is written is implementation dependent but is normally the same device where X server error messages are directed. </para> diff --git a/libX11/specs/XKB/glossary.xml b/libX11/specs/XKB/glossary.xml index 0cccf0f8f..1eb600c90 100644 --- a/libX11/specs/XKB/glossary.xml +++ b/libX11/specs/XKB/glossary.xml @@ -1,3 +1,6 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <glossary id='glossary'> <title>Glossary</title> <glossentry> @@ -84,31 +87,31 @@ upon client program exit. <para> The canonical key types are predefined key types that describe the types of keys available on most keyboards. The definitions for the canonical key types -are held in the first <emphasis> -XkbNumRequiredTypes</emphasis> - entries of the <emphasis> -types</emphasis> - field of the client map and are indexed using the following constants: +are held in the first +<symbol>XkbNumRequiredTypes</symbol> +entries of the +<structfield>types</structfield> +field of the client map and are indexed using the following constants: </para> <itemizedlist> <listitem> <para> -<emphasis>XkbOneLevelIndex</emphasis> +<symbol>XkbOneLevelIndex</symbol> </para> </listitem> <listitem> <para> -<emphasis>XkbTwoLevelIndex</emphasis> +<symbol>XkbTwoLevelIndex</symbol> </para> </listitem> <listitem> <para> -<emphasis>XkbAlphabeticIndex</emphasis> +<symbol>XkbAlphabeticIndex</symbol> </para> </listitem> <listitem> <para> -<emphasis>XkbKeypadIndex</emphasis> +<symbol>XkbKeypadIndex</symbol> </para> </listitem> </itemizedlist> @@ -127,9 +130,9 @@ The key mapping information needed to convert arbitrary keycodes to symbols. <glossterm>Compat Name</glossterm> <glossdef> <para> -The <emphasis> -compat</emphasis> - name is a string that provides some information about the rules used to bind +The +<emphasis>compat</emphasis> +name is a string that provides some information about the rules used to bind actions to keys that are changed using core protocol requests. </para> </glossdef> @@ -186,12 +189,12 @@ processing. <para> Xkb normally consumes modifiers in determining the appropriate symbol for an event, that is, the modifiers are not considered during any of the later stages -of event processing. For those rare occasions when a modifier <emphasis> -should</emphasis> - be considered despite having been used to look up a symbol, key types include -an optional <emphasis> -preserve</emphasis> - field. +of event processing. For those rare occasions when a modifier +<emphasis>should</emphasis> +be considered despite having been used to look up a symbol, key types include +an optional +<structfield>preserve</structfield> +field. </para> </glossdef> </glossentry> @@ -209,16 +212,15 @@ An event created from the core X server. <para> Detectable auto-repeat allows a client to detect an auto-repeating key. If a client requests and the server supports detectable auto-repeat, Xkb generates -<emphasis> -KeyRelease</emphasis> - events only when the key is physically released. Thus the client receives a -number of <emphasis> -KeyPress</emphasis> - events for that key without intervening <emphasis> -KeyRelease</emphasis> - events until the key is finally released, when a <emphasis> -KeyRelease</emphasis> - event is received. +<symbol>KeyRelease</symbol> +events only when the key is physically released. Thus the client receives a +number of +<symbol>KeyPress</symbol> +events for that key without intervening +<symbol>KeyRelease</symbol> +events until the key is finally released, when a +<symbol>KeyRelease</symbol> +event is received. </para> </glossdef> </glossentry> @@ -228,17 +230,16 @@ KeyRelease</emphasis> <para> The effective group is the arithmetic sum of the locked, latched, and base groups. The effective keyboard group is always brought back into range -depending on the value of the <emphasis> -GroupsWrap</emphasis> - control for the keyboard. If an event occurs with an effective group that is +depending on the value of the +<emphasis>GroupsWrap</emphasis> +control for the keyboard. If an event occurs with an effective group that is legal for the keyboard as a whole, but not for the key in question, the group -<emphasis> -for that event only</emphasis> - is normalized using the algorithm specified by the <emphasis> -group_info</emphasis> - member of the key symbol map (<emphasis> -XkbSymMapRec</emphasis> -). +<emphasis>for that event only</emphasis> +is normalized using the algorithm specified by the +<structfield>group_info</structfield> +member of the key symbol map +(<structname>XkbSymMapRec</structname>). + </para> </glossdef> </glossentry> @@ -352,14 +353,14 @@ Group 4 have indices of 0 through 3. <para> If a group index exceeds the maximum number of groups permitted for the specified keyboard, it is wrapped or truncated back into range as specified by -the global <emphasis>GroupsWrap</emphasis> control. <emphasis> -GroupsWrap</emphasis> can have the following values: +the global <emphasis>GroupsWrap</emphasis> control. +<emphasis>GroupsWrap</emphasis> can have the following values: + <simplelist type='vert' columns='1'> + <member><emphasis>WrapIntoRange</emphasis></member> + <member><emphasis>ClampIntoRange</emphasis></member> + <member><emphasis>RedirectIntoRange</emphasis></member> + </simplelist> </para> - <literallayout> - <emphasis>WrapIntoRange</emphasis> - <emphasis>ClampIntoRange</emphasis> - <emphasis>RedirectIntoRange</emphasis> - </literallayout> </glossdef> </glossentry> @@ -390,8 +391,8 @@ collection of characters. A group usually contains a set of characters that logically belong together and that may be arranged on several shift levels within that group. For example, Group1 could be the English alphabet, and Group2 could be Greek. Xkb supports up to four different groups for an input -device or keyboard. Groups are in the range 1-4 (Group1 - Group4), and are -often referred to as G1 - G4 and indexed as 0 - 3. +device or keyboard. Groups are in the range 1–4 (Group1–Group4), +and are often referred to as G1–G4 and indexed as 0–3. </para> </glossdef> </glossentry> @@ -424,11 +425,11 @@ specifies which lights are on or off. An indicator has its own set of attributes that specify whether clients can explicitly set its state and whether it tracks the keyboard state. The indicator map is the collection of these attributes for each indicator and is -held in the <emphasis> -maps</emphasis> - array, which is an array of <emphasis> -XkbIndicatorRec</emphasis> - structures. +held in the +<structfield>maps</structfield> +array, which is an array of +<structname>XkbIndicatorRec</structname> +structures. </para> </glossdef> </glossentry> @@ -495,7 +496,8 @@ Simulate events on other keys A key alias is a symbolic name for a specific physical key. Key aliases allow the keyboard layout designer to assign multiple key names to a single key. This allows the keyboard layout designer to refer to keys using either their -position or their "function." Key aliases can be specified both in the symbolic +position or their <quote>function</quote>. +Key aliases can be specified both in the symbolic names component and in the keyboard geometry. Both sets of aliases are always valid, but key alias definitions in the keyboard geometry have priority; if both symbolic names and geometry include aliases, you should consider the @@ -508,11 +510,11 @@ symbolic names section. <glossterm>Key Behavior</glossterm> <glossdef> <para> -The <emphasis> -behaviors</emphasis> - field of the server map is an array of <emphasis> -XkbBehavior</emphasis> -, indexed by keycode, and contains the behavior for each key. The X server uses +The +<structfield>behaviors</structfield> +field of the server map is an array of +<structname>XkbBehavior</structname>, +indexed by keycode, and contains the behavior for each key. The X server uses key behavior to determine whether to process or filter out any given key event; key behavior is independent of keyboard modifier or group state. Each key has exactly one behavior. @@ -542,9 +544,9 @@ exactly one behavior. <glossdef> <para> A key symbol map describes the symbols bound to a key and the rules to be used -to interpret those symbols. It is an array of <emphasis> -XkbSymMapRec</emphasis> - structures indexed by keycode. +to interpret those symbols. It is an array of +<structname>XkbSymMapRec</structname> +structures indexed by keycode. </para> </glossdef> </glossentry> @@ -554,15 +556,15 @@ XkbSymMapRec</emphasis> <para> Key types are used to determine the shift level of a key given the current state of the keyboard. There is one key type for each group for a key. Key -types are defined using the <emphasis> -XkbKeyTypeRec</emphasis> - and <emphasis> -XkbKTMapEntryRec</emphasis> - structures. Xkb allows up to <emphasis> -XkbMaxKeyTypes</emphasis> - (255) key types to be defined, but requires at least <emphasis> -XkbNumRequiredTypes</emphasis> - (4) predefined types to be in a key map. +types are defined using the +<structname>XkbKeyTypeRec</structname> +and +<structname>XkbKTMapEntryRec</structname> +structures. Xkb allows up to +<symbol>XkbMaxKeyTypes</symbol> +(255) key types to be defined, but requires at least +<symbol>XkbNumRequiredTypes</symbol> +(4) predefined types to be in a key map. </para> </glossdef> </glossentry> @@ -572,7 +574,7 @@ XkbNumRequiredTypes</emphasis> <para> The sound the default bell makes when rung is the system bell or the default keyboard bell. Some input devices may have more than one bell, identified by -<emphasis>bell_class</emphasis> and <emphasis>bell_id</emphasis>. +<structfield>bell_class</structfield> and <structfield>bell_id</structfield>. </para> </glossdef> </glossentry> @@ -581,11 +583,14 @@ keyboard bell. Some input devices may have more than one bell, identified by <glossdef> <para> There are five types of components stored in the X server database of keyboard -components. They correspond to the <emphasis> -symbols, geometry, keycodes, compat, </emphasis> -and<emphasis> - types</emphasis> - symbolic names associated with a keyboard. +components. They correspond to the +<structfield>>symbols</structfield>, +<structfield>geometry</structfield>, +<structfield>keycodes</structfield>, +<structfield>compat</structfield>, +and +<structfield>types</structfield> +symbolic names associated with a keyboard. </para> </glossdef> </glossentry> @@ -594,16 +599,16 @@ and<emphasis> <glossdef> <para> A keyboard feedback includes the following: + <simplelist type='vert' columns='1'> + <member>Keyclick volume</member> + <member>Bell volume</member> + <member>Bell pitch</member> + <member>Bell duration</member> + <member>Global auto-repeat</member> + <member>Per key auto-repeat</member> + <member>32 LEDs</member> + </simplelist> </para> -<literallayout> - Keyclick volume - Bell volume - Bell pitch - Bell duration - Global auto-repeat - Per key auto-repeat - 32 LEDs -</literallayout> </glossdef> </glossentry> @@ -622,9 +627,9 @@ key type. <para> Keyboard geometry describes the physical appearance of the keyboard, including the shape, location, and color of all keyboard keys or other visible keyboard -components such as indicators and is stored in a <emphasis> -XkbGeometryRec</emphasis> - structure. The information contained in a keyboard geometry is sufficient to +components such as indicators and is stored in a +<structname>XkbGeometryRec</structname> +structure. The information contained in a keyboard geometry is sufficient to allow a client program to draw an accurate two-dimensional image of the keyboard. </para> @@ -635,9 +640,9 @@ keyboard. <glossdef> <para> The keyboard geometry name describes the physical location, size, and shape of -the various keys on the keyboard and is part of the <emphasis> -XkbNamesRec</emphasis> - structure. +the various keys on the keyboard and is part of the +<structname>XkbNamesRec</structname> +structure. </para> </glossdef> </glossentry> @@ -666,9 +671,9 @@ the device. <glossdef> <para> The keycode name describes the range and meaning of the keycodes returned by -the keyboard and is part of the <emphasis> -XkbNamesRec</emphasis> - structure. +the keyboard and is part of the +<structname>XkbNamesRec</structname> +structure. </para> </glossdef> </glossentry> @@ -741,19 +746,17 @@ to a keysym. <para> A modifier is a logical condition that is either set or unset. The modifiers control the Shift Level selected when a key event occurs. Xkb supports the core -protocol eight modifiers (<emphasis> -Shift</emphasis> -, <emphasis> -Lock</emphasis> -, <emphasis> -Control</emphasis> -, and <emphasis> -Mod1</emphasis> - through <emphasis> -Mod5</emphasis> -), called the <emphasis> -real</emphasis> - modifiers. In addition, Xkb extends modifier flexibility by providing a set of +protocol eight modifiers +(<symbol>Shift</symbol>, +<symbol>Lock</symbol>, +<symbol>Control</symbol>, +and +<symbol>Mod1</symbol> +through +<symbol>Mod5</symbol>), +called the +<emphasis>real</emphasis> +modifiers. In addition, Xkb extends modifier flexibility by providing a set of sixteen named virtual modifiers, each of which can be bound to any set of the eight real modifiers. </para> @@ -773,9 +776,9 @@ may be, for example, a shift key or a control key. <glossterm>Modifier Definition</glossterm> <glossdef> <para> -An Xkb modifier definition, held in an <emphasis> -XkbModsRec</emphasis> -, consists of a set of real modifiers, a set of virtual modifiers, and an +An Xkb modifier definition, held in an +<structname>XkbModsRec</structname>, +consists of a set of real modifiers, a set of virtual modifiers, and an effective mask. The mask is the union of the real modifiers and the set of real modifiers to which the virtual modifiers map; the mask cannot be explicitly changed. @@ -806,12 +809,12 @@ polygon, used in the geometry specification for a keyboard. <glossterm>Physical Indicator Mask</glossterm> <glossdef> <para> -The physical indicator mask is a field in the <emphasis> -XkbIndicatorRec</emphasis> - that indicates which indicators are bound to physical LEDs on the keyboard; if -a bit is set in <emphasis> -phys_indicators</emphasis> -, then the associated indicator has a physical LED associated with it. This +The physical indicator mask is a field in the +<structname>XkbIndicatorRec</structname> +that indicates which indicators are bound to physical LEDs on the keyboard; if +a bit is set in +<structfield>phys_indicators</structfield>, +then the associated indicator has a physical LED associated with it. This field is necessary because some indicators may not have corresponding physical LEDs on the keyboard. </para> @@ -821,13 +824,13 @@ LEDs on the keyboard. <glossterm>Physical Symbol Keyboard Name</glossterm> <glossdef> <para> -The <emphasis> -symbols</emphasis> - keyboard name identifies the symbols logically bound to the keys. The symbols +The +<structfield>symbols</structfield> +keyboard name identifies the symbols logically bound to the keys. The symbols name is a human or application-readable description of the intended locale or -usage of the keyboard with these symbols. The <emphasis> -phys_symbols</emphasis> - keyboard name, on the other hand, identifies the symbols actually engraved on +usage of the keyboard with these symbols. The +<structfield>phys_symbols</structfield> +keyboard name, on the other hand, identifies the symbols actually engraved on the keyboard. </para> </glossdef> @@ -838,14 +841,14 @@ the keyboard. <para> Xkb normally consumes modifiers in determining the appropriate symbol for an event, that is, the modifiers are not considered during any of the later stages -of event processing. For those rare occasions when a modifier <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 modifier is present in the <emphasis> -preserve</emphasis> - list, it is a preserved modifier. +of event processing. For those rare occasions when a modifier +<emphasis>should</emphasis> +be considered despite having been used to look up a symbol, key types include +an optional +<structfield>preserve</structfield> +field. If a modifier is present in the +<structfield>preserve</structfield> +list, it is a preserved modifier. </para> </glossdef> </glossentry> @@ -865,19 +868,17 @@ be logically depressed at one time. <glossterm>Real Modifier</glossterm> <glossdef> <para> -Xkb supports the eight core protocol modifiers (<emphasis> -Shift</emphasis> -, <emphasis> -Lock</emphasis> -, <emphasis> -Control</emphasis> -, and <emphasis> -Mod1</emphasis> - through <emphasis> -Mod5</emphasis> -); these are called the <emphasis> -real</emphasis> - modifiers, as opposed to the set of sixteen named virtual modifiers that can +Xkb supports the eight core protocol modifiers +(<symbol>Shift</symbol>, +<symbol>Lock</symbol>, +<symbol>Control</symbol>, +and +<symbol>Mod1</symbol> +through +<symbol>Mod5</symbol>); +these are called the +<emphasis>real</emphasis> +modifiers, as opposed to the set of sixteen named virtual modifiers that can be bound to any set of the eight real modifiers. </para> </glossdef> @@ -904,13 +905,13 @@ produced when a key is actuated. <glossterm>Symbol Keyboard Name</glossterm> <glossdef> <para> -The <emphasis> -symbols</emphasis> - keyboard name identifies the symbols logically bound to the keys. The symbols +The +<structfield>symbols</structfield> +keyboard name identifies the symbols logically bound to the keys. The symbols name is a human or application-readable description of the intended locale or -usage of the keyboard with these symbols. The <emphasis> -phys_symbols</emphasis> - keyboard name, on the other hand, identifies the symbols actually engraved on +usage of the keyboard with these symbols. The +<structfield>phys_symbols</structfield> +keyboard name, on the other hand, identifies the symbols actually engraved on the keyboard. </para> </glossdef> @@ -920,9 +921,9 @@ the keyboard. <glossdef> <para> Xkb supports symbolic names for most components of the keyboard extension. Most -of these symbolic names are grouped into the <emphasis> -names</emphasis> - component of the keyboard description. +of these symbolic names are grouped into the +<structfield>names</structfield> +component of the keyboard description. </para> </glossdef> </glossentry> @@ -939,9 +940,9 @@ group, and button state information pertaining to the event. <glossterm>Types Name</glossterm> <glossdef> <para> -The <emphasis> -types</emphasis> - name provides some information about the set of key types that can be +The +<emphasis>types</emphasis> +name provides some information about the set of key types that can be associated with the keyboard. In addition, each key type can have a name, and each shift level of a type can have a name. </para> @@ -962,17 +963,15 @@ slider, or a dial. <para> Xkb provides a set of sixteen named virtual modifiers that can be bound to any set of the eight real modifiers. Each virtual modifier can be bound to any set -of the real modifiers (<emphasis> -Shift</emphasis> -, <emphasis> -Lock</emphasis> -, <emphasis> -Control,</emphasis> - and <emphasis> -Mod1</emphasis> --<emphasis> -Mod5</emphasis> -). +of the real modifiers +(<symbol>Shift</symbol>, +<symbol>Lock</symbol>, +<symbol>Control</symbol>, +and +<symbol>Mod1</symbol> +– +<symbol>Mod5</symbol>). + </para> </glossdef> </glossentry> diff --git a/libX11/specs/XKB/xkblib.xml b/libX11/specs/XKB/xkblib.xml index e4aa58741..c7508d484 100644 --- a/libX11/specs/XKB/xkblib.xml +++ b/libX11/specs/XKB/xkblib.xml @@ -105,4 +105,5 @@ other dealings in this Software without prior written authorization. <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ch21.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ch22.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="glossary.xml"/> +<index id='index' /> </book> diff --git a/libXext/configure.ac b/libXext/configure.ac index 491aac086..8efdd1f09 100644 --- a/libXext/configure.ac +++ b/libXext/configure.ac @@ -1,7 +1,7 @@ # Initialize Autoconf AC_PREREQ([2.60]) -AC_INIT([libXext], [1.3.2], +AC_INIT([libXext], [1.3.3], [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg], [libXext]) AC_CONFIG_SRCDIR([Makefile.am]) AC_CONFIG_HEADERS([config.h]) diff --git a/mesalib/configure.ac b/mesalib/configure.ac index 744e55ce3..d06730d34 100644 --- a/mesalib/configure.ac +++ b/mesalib/configure.ac @@ -32,7 +32,7 @@ LIBDRM_RADEON_REQUIRED=2.4.54 LIBDRM_INTEL_REQUIRED=2.4.52 LIBDRM_NVVIEUX_REQUIRED=2.4.33 LIBDRM_NOUVEAU_REQUIRED="2.4.33 libdrm >= 2.4.41" -LIBDRM_FREEDRENO_REQUIRED=2.4.51 +LIBDRM_FREEDRENO_REQUIRED=2.4.55 DRI2PROTO_REQUIRED=2.6 DRI3PROTO_REQUIRED=1.0 PRESENTPROTO_REQUIRED=1.0 diff --git a/mesalib/docs/GL3.txt b/mesalib/docs/GL3.txt index 0f37da410..f9e33b4fe 100644 --- a/mesalib/docs/GL3.txt +++ b/mesalib/docs/GL3.txt @@ -157,7 +157,7 @@ GL 4.3: GL_ARB_arrays_of_arrays started (Timothy) GL_ARB_ES3_compatibility DONE (i965) GL_ARB_clear_buffer_object DONE (all drivers) - GL_ARB_compute_shader started (Paul Berry) + GL_ARB_compute_shader started (currently stalled) GL_ARB_copy_image not started GL_KHR_debug DONE (all drivers) GL_ARB_explicit_uniform_location DONE (all drivers that support GLSL) @@ -183,7 +183,7 @@ GL 4.4: GLSL 4.4 not started GL_MAX_VERTEX_ATTRIB_STRIDE not started GL_ARB_buffer_storage DONE (i965, nv30, nv50, nvc0, r300, r600, radeonsi) - GL_ARB_clear_texture not started + GL_ARB_clear_texture DONE (i965) GL_ARB_enhanced_layouts not started GL_ARB_multi_bind DONE (all drivers) GL_ARB_query_buffer_object not started diff --git a/mesalib/docs/relnotes/10.3.html b/mesalib/docs/relnotes/10.3.html index 90247c09c..1f4e1da7b 100644 --- a/mesalib/docs/relnotes/10.3.html +++ b/mesalib/docs/relnotes/10.3.html @@ -58,6 +58,7 @@ Note: some of the new features are only available with certain drivers. <li>GL_ARB_seamless_cubemap_per_texture on i965, llvmpipe, nvc0, r600, radeonsi, softpipe</li> <li>GL_ARB_fragment_layer_viewport on nv50, nvc0, llvmpipe, r600</li> <li>GL_AMD_vertex_shader_viewport_index on i965/gen7+, r600</li> +<li>GL_ARB_clear_texture on i965</li> </ul> diff --git a/mesalib/src/gallium/auxiliary/util/u_math.h b/mesalib/src/gallium/auxiliary/util/u_math.h index b9ed197d7..f6dcb228f 100644 --- a/mesalib/src/gallium/auxiliary/util/u_math.h +++ b/mesalib/src/gallium/auxiliary/util/u_math.h @@ -812,6 +812,23 @@ util_bswap16(uint16_t n) (n << 8); } +static INLINE void* +util_memcpy_cpu_to_le32(void * restrict dest, const void * restrict src, size_t n) +{ +#ifdef PIPE_ARCH_BIG_ENDIAN + size_t i, e; + asset(n % 4 == 0); + + for (i = 0, e = n / 4; i < e; i++) { + uint32_t * restrict d = (uint32_t* restrict)dest; + const uint32_t * restrict s = (const uint32_t* restrict)src; + d[i] = util_bswap32(s[i]); + } + return dest; +#else + return memcpy(dest, src, n); +#endif +} /** * Clamp X to [MIN, MAX]. diff --git a/mesalib/src/glsl/ast_array_index.cpp b/mesalib/src/glsl/ast_array_index.cpp index f3b060ea6..50f9987c8 100644 --- a/mesalib/src/glsl/ast_array_index.cpp +++ b/mesalib/src/glsl/ast_array_index.cpp @@ -181,7 +181,8 @@ _mesa_ast_array_index_to_hir(void *mem_ctx, if (array->type->is_unsized_array()) { _mesa_glsl_error(&loc, state, "unsized array index must be constant"); } else if (array->type->fields.array->is_interface() - && array->variable_referenced()->data.mode == ir_var_uniform) { + && array->variable_referenced()->data.mode == ir_var_uniform + && !state->is_version(400, 0) && !state->ARB_gpu_shader5_enable) { /* Page 46 in section 4.3.7 of the OpenGL ES 3.00 spec says: * * "All indexes used to index a uniform block array must be diff --git a/mesalib/src/glsl/ast_to_hir.cpp b/mesalib/src/glsl/ast_to_hir.cpp index 328cd1b1b..a15ee9c05 100644 --- a/mesalib/src/glsl/ast_to_hir.cpp +++ b/mesalib/src/glsl/ast_to_hir.cpp @@ -5212,7 +5212,7 @@ ast_process_structure_or_interface_block(exec_list *instructions, fields[i].row_major = false; } - i++; + i++; } } diff --git a/mesalib/src/glsl/builtin_variables.cpp b/mesalib/src/glsl/builtin_variables.cpp index 34973023f..4c5b9c070 100644 --- a/mesalib/src/glsl/builtin_variables.cpp +++ b/mesalib/src/glsl/builtin_variables.cpp @@ -672,6 +672,12 @@ builtin_variable_generator::generate_constants() } if (state->is_version(430, 0) || state->ARB_compute_shader_enable) { + add_const("gl_MaxComputeAtomicCounterBuffers", MAX_COMPUTE_ATOMIC_COUNTER_BUFFERS); + add_const("gl_MaxComputeAtomicCounters", MAX_COMPUTE_ATOMIC_COUNTERS); + add_const("gl_MaxComputeImageUniforms", MAX_COMPUTE_IMAGE_UNIFORMS); + add_const("gl_MaxComputeTextureImageUnits", MAX_COMPUTE_TEXTURE_IMAGE_UNITS); + add_const("gl_MaxComputeUniformComponents", MAX_COMPUTE_UNIFORM_COMPONENTS); + add_const_ivec3("gl_MaxComputeWorkGroupCount", state->Const.MaxComputeWorkGroupCount[0], state->Const.MaxComputeWorkGroupCount[1], diff --git a/mesalib/src/glsl/ir_validate.cpp b/mesalib/src/glsl/ir_validate.cpp index 37e1ce33e..4f85b7db8 100644 --- a/mesalib/src/glsl/ir_validate.cpp +++ b/mesalib/src/glsl/ir_validate.cpp @@ -495,7 +495,6 @@ ir_validate::visit_leave(ir_expression *ir) break; case ir_binop_ubo_load: - assert(ir->operands[0]->as_constant()); assert(ir->operands[0]->type == glsl_type::uint_type); assert(ir->operands[1]->type == glsl_type::uint_type); diff --git a/mesalib/src/glsl/link_uniform_block_active_visitor.cpp b/mesalib/src/glsl/link_uniform_block_active_visitor.cpp index d19ce20c7..854309f9b 100644 --- a/mesalib/src/glsl/link_uniform_block_active_visitor.cpp +++ b/mesalib/src/glsl/link_uniform_block_active_visitor.cpp @@ -109,32 +109,44 @@ link_uniform_block_active_visitor::visit_enter(ir_dereference_array *ir) assert((b->num_array_elements == 0) == (b->array_elements == NULL)); assert(b->type != NULL); - /* Determine whether or not this array index has already been added to the - * list of active array indices. At this point all constant folding must - * have occured, and the array index must be a constant. - */ ir_constant *c = ir->array_index->as_constant(); - assert(c != NULL); - const unsigned idx = c->get_uint_component(0); + if (c) { + /* Index is a constant, so mark just that element used, if not already */ + const unsigned idx = c->get_uint_component(0); - unsigned i; - for (i = 0; i < b->num_array_elements; i++) { - if (b->array_elements[i] == idx) - break; - } + unsigned i; + for (i = 0; i < b->num_array_elements; i++) { + if (b->array_elements[i] == idx) + break; + } - assert(i <= b->num_array_elements); + assert(i <= b->num_array_elements); - if (i == b->num_array_elements) { - b->array_elements = reralloc(this->mem_ctx, - b->array_elements, - unsigned, - b->num_array_elements + 1); + if (i == b->num_array_elements) { + b->array_elements = reralloc(this->mem_ctx, + b->array_elements, + unsigned, + b->num_array_elements + 1); - b->array_elements[b->num_array_elements] = idx; + b->array_elements[b->num_array_elements] = idx; - b->num_array_elements++; + b->num_array_elements++; + } + } else { + /* The array index is not a constant, so mark the entire array used. */ + assert(b->type->is_array()); + if (b->num_array_elements < b->type->length) { + b->num_array_elements = b->type->length; + b->array_elements = reralloc(this->mem_ctx, + b->array_elements, + unsigned, + b->num_array_elements); + + for (unsigned i = 0; i < b->num_array_elements; i++) { + b->array_elements[i] = i; + } + } } return visit_continue_with_parent; diff --git a/mesalib/src/glsl/link_uniform_blocks.cpp b/mesalib/src/glsl/link_uniform_blocks.cpp index 53a18c934..fef3626bf 100644 --- a/mesalib/src/glsl/link_uniform_blocks.cpp +++ b/mesalib/src/glsl/link_uniform_blocks.cpp @@ -92,13 +92,13 @@ private: unsigned len = strlen(close_bracket + 1) + 1; memmove(open_bracket, close_bracket + 1, len); - } else { + } else { v->IndexName = v->Name; } const unsigned alignment = record_type - ? record_type->std140_base_alignment(v->RowMajor) - : type->std140_base_alignment(v->RowMajor); + ? record_type->std140_base_alignment(v->RowMajor) + : type->std140_base_alignment(v->RowMajor); unsigned size = type->std140_size(v->RowMajor); this->offset = glsl_align(this->offset, alignment); diff --git a/mesalib/src/glsl/lower_ubo_reference.cpp b/mesalib/src/glsl/lower_ubo_reference.cpp index 90e65bd0e..67b752d3d 100644 --- a/mesalib/src/glsl/lower_ubo_reference.cpp +++ b/mesalib/src/glsl/lower_ubo_reference.cpp @@ -57,7 +57,7 @@ public: void *mem_ctx; struct gl_shader *shader; struct gl_uniform_buffer_variable *ubo_var; - unsigned uniform_block; + ir_rvalue *uniform_block; bool progress; }; @@ -69,9 +69,11 @@ public: * \c UniformBlocks array. */ static const char * -interface_field_name(void *mem_ctx, char *base_name, ir_dereference *d) +interface_field_name(void *mem_ctx, char *base_name, ir_dereference *d, + ir_rvalue **nonconst_block_index) { - ir_constant *previous_index = NULL; + ir_rvalue *previous_index = NULL; + *nonconst_block_index = NULL; while (d != NULL) { switch (d->ir_type) { @@ -79,13 +81,21 @@ interface_field_name(void *mem_ctx, char *base_name, ir_dereference *d) ir_dereference_variable *v = (ir_dereference_variable *) d; if (previous_index && v->var->is_interface_instance() - && v->var->type->is_array()) - return ralloc_asprintf(mem_ctx, - "%s[%d]", - base_name, - previous_index->get_uint_component(0)); - else + && v->var->type->is_array()) { + + ir_constant *const_index = previous_index->as_constant(); + if (!const_index) { + *nonconst_block_index = previous_index; + return ralloc_asprintf(mem_ctx, "%s[0]", base_name); + } else { + return ralloc_asprintf(mem_ctx, + "%s[%d]", + base_name, + const_index->get_uint_component(0)); + } + } else { return base_name; + } break; } @@ -101,7 +111,8 @@ interface_field_name(void *mem_ctx, char *base_name, ir_dereference *d) ir_dereference_array *a = (ir_dereference_array *) d; d = a->array->as_dereference(); - previous_index = a->array_index->as_constant(); + previous_index = a->array_index; + break; } @@ -131,14 +142,24 @@ lower_ubo_reference_visitor::handle_rvalue(ir_rvalue **rvalue) mem_ctx = ralloc_parent(*rvalue); + ir_rvalue *nonconst_block_index; const char *const field_name = interface_field_name(mem_ctx, (char *) var->get_interface_type()->name, - deref); + deref, &nonconst_block_index); - this->uniform_block = -1; + this->uniform_block = NULL; for (unsigned i = 0; i < shader->NumUniformBlocks; i++) { if (strcmp(field_name, shader->UniformBlocks[i].Name) == 0) { - this->uniform_block = i; + + ir_constant *index = new(mem_ctx) ir_constant(i); + + if (nonconst_block_index) { + if (nonconst_block_index->type != glsl_type::uint_type) + nonconst_block_index = i2u(nonconst_block_index); + this->uniform_block = add(nonconst_block_index, index); + } else { + this->uniform_block = index; + } struct gl_uniform_block *block = &shader->UniformBlocks[i]; @@ -149,7 +170,7 @@ lower_ubo_reference_visitor::handle_rvalue(ir_rvalue **rvalue) } } - assert(this->uniform_block != (unsigned) -1); + assert(this->uniform_block); ir_rvalue *offset = new(mem_ctx) ir_constant(0u); unsigned const_offset = 0; @@ -267,11 +288,12 @@ ir_expression * lower_ubo_reference_visitor::ubo_load(const glsl_type *type, ir_rvalue *offset) { + ir_rvalue *block_ref = this->uniform_block->clone(mem_ctx, NULL); return new(mem_ctx) ir_expression(ir_binop_ubo_load, - type, - new(mem_ctx) ir_constant(this->uniform_block), - offset); + type, + block_ref, + offset); } diff --git a/mesalib/src/mapi/glapi/gen/ARB_clear_texture.xml b/mesalib/src/mapi/glapi/gen/ARB_clear_texture.xml new file mode 100644 index 000000000..bd9116f8b --- /dev/null +++ b/mesalib/src/mapi/glapi/gen/ARB_clear_texture.xml @@ -0,0 +1,34 @@ +<?xml version="1.0"?> +<!DOCTYPE OpenGLAPI SYSTEM "gl_API.dtd"> + +<OpenGLAPI> + +<category name="GL_ARB_clear_texture" number="145"> + + <enum name="CLEAR_TEXTURE" value="0x9365"/> + + <function name ="ClearTexImage" offset="assign"> + <param name="texture" type="GLuint"/> + <param name="level" type="GLint"/> + <param name="format" type="GLenum"/> + <param name="type" type="GLenum"/> + <param name="data" type="const GLvoid *"/> + </function> + + <function name ="ClearTexSubImage" offset="assign"> + <param name="texture" type="GLuint"/> + <param name="level" type="GLint"/> + <param name="xoffset" type="GLint"/> + <param name="yoffset" type="GLint"/> + <param name="zoffset" type="GLint"/> + <param name="width" type="GLsizei"/> + <param name="height" type="GLsizei"/> + <param name="depth" type="GLsizei"/> + <param name="format" type="GLenum"/> + <param name="type" type="GLenum"/> + <param name="data" type="const GLvoid *"/> + </function> + +</category> + +</OpenGLAPI> diff --git a/mesalib/src/mapi/glapi/gen/Makefile.am b/mesalib/src/mapi/glapi/gen/Makefile.am index be7d9e0ef..212731fa4 100644 --- a/mesalib/src/mapi/glapi/gen/Makefile.am +++ b/mesalib/src/mapi/glapi/gen/Makefile.am @@ -112,6 +112,7 @@ API_XML = \ ARB_base_instance.xml \ ARB_blend_func_extended.xml \ ARB_clear_buffer_object.xml \ + ARB_clear_texture.xml \ ARB_color_buffer_float.xml \ ARB_compressed_texture_pixel_storage.xml \ ARB_compute_shader.xml \ diff --git a/mesalib/src/mapi/glapi/gen/gl_API.xml b/mesalib/src/mapi/glapi/gen/gl_API.xml index 882e66e0b..e011509e5 100644 --- a/mesalib/src/mapi/glapi/gen/gl_API.xml +++ b/mesalib/src/mapi/glapi/gen/gl_API.xml @@ -8358,7 +8358,9 @@ </function> </category> -<!-- ARB extensions #145...#146 --> +<xi:include href="ARB_clear_texture.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + +<!-- ARB extension #146 --> <xi:include href="ARB_multi_bind.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> diff --git a/mesalib/src/mesa/drivers/common/driverfuncs.c b/mesalib/src/mesa/drivers/common/driverfuncs.c index 6ece5d80e..4f0f7a686 100644 --- a/mesalib/src/mesa/drivers/common/driverfuncs.c +++ b/mesalib/src/mesa/drivers/common/driverfuncs.c @@ -95,6 +95,7 @@ _mesa_init_driver_functions(struct dd_function_table *driver) driver->TexImage = _mesa_store_teximage; driver->TexSubImage = _mesa_store_texsubimage; driver->GetTexImage = _mesa_meta_GetTexImage; + driver->ClearTexSubImage = _mesa_meta_ClearTexSubImage; driver->CopyTexSubImage = _mesa_meta_CopyTexSubImage; driver->GenerateMipmap = _mesa_meta_GenerateMipmap; driver->TestProxyTexImage = _mesa_test_proxy_teximage; diff --git a/mesalib/src/mesa/drivers/common/meta.c b/mesalib/src/mesa/drivers/common/meta.c index 89d7a157c..b12898f26 100644 --- a/mesalib/src/mesa/drivers/common/meta.c +++ b/mesalib/src/mesa/drivers/common/meta.c @@ -40,6 +40,7 @@ #include "main/blit.h" #include "main/bufferobj.h" #include "main/buffers.h" +#include "main/clear.h" #include "main/colortab.h" #include "main/condrender.h" #include "main/depth.h" @@ -47,6 +48,7 @@ #include "main/fbobject.h" #include "main/feedback.h" #include "main/formats.h" +#include "main/format_unpack.h" #include "main/glformats.h" #include "main/image.h" #include "main/macros.h" @@ -71,6 +73,7 @@ #include "main/teximage.h" #include "main/texparam.h" #include "main/texstate.h" +#include "main/texstore.h" #include "main/transformfeedback.h" #include "main/uniforms.h" #include "main/varray.h" @@ -505,6 +508,11 @@ _mesa_meta_begin(struct gl_context *ctx, GLbitfield state) _mesa_set_enable(ctx, GL_COLOR_LOGIC_OP, GL_FALSE); } + if (state & MESA_META_DITHER) { + save->DitherFlag = ctx->Color.DitherFlag; + _mesa_set_enable(ctx, GL_DITHER, GL_TRUE); + } + if (state & MESA_META_COLOR_MASK) { memcpy(save->ColorMask, ctx->Color.ColorMask, sizeof(ctx->Color.ColorMask)); @@ -875,6 +883,9 @@ _mesa_meta_end(struct gl_context *ctx) _mesa_set_enable(ctx, GL_COLOR_LOGIC_OP, save->ColorLogicOpEnabled); } + if (state & MESA_META_DITHER) + _mesa_set_enable(ctx, GL_DITHER, save->DitherFlag); + if (state & MESA_META_COLOR_MASK) { GLuint i; for (i = 0; i < ctx->Const.MaxDrawBuffers; i++) { @@ -3339,3 +3350,189 @@ _mesa_meta_DrawTex(struct gl_context *ctx, GLfloat x, GLfloat y, GLfloat z, _mesa_meta_end(ctx); } + +static bool +cleartexsubimage_color(struct gl_context *ctx, + struct gl_texture_image *texImage, + const GLvoid *clearValue, + GLint zoffset) +{ + mesa_format format; + union gl_color_union colorValue; + GLenum datatype; + GLenum status; + + _mesa_meta_bind_fbo_image(GL_COLOR_ATTACHMENT0, texImage, zoffset); + + status = _mesa_CheckFramebufferStatus(GL_DRAW_FRAMEBUFFER); + if (status != GL_FRAMEBUFFER_COMPLETE) + return false; + + /* We don't want to apply an sRGB conversion so override the format */ + format = _mesa_get_srgb_format_linear(texImage->TexFormat); + datatype = _mesa_get_format_datatype(format); + + switch (datatype) { + case GL_UNSIGNED_INT: + case GL_INT: + if (clearValue) + _mesa_unpack_uint_rgba_row(format, 1, clearValue, + (GLuint (*)[4]) colorValue.ui); + else + memset(&colorValue, 0, sizeof colorValue); + if (datatype == GL_INT) + _mesa_ClearBufferiv(GL_COLOR, 0, colorValue.i); + else + _mesa_ClearBufferuiv(GL_COLOR, 0, colorValue.ui); + break; + default: + if (clearValue) + _mesa_unpack_rgba_row(format, 1, clearValue, + (GLfloat (*)[4]) colorValue.f); + else + memset(&colorValue, 0, sizeof colorValue); + _mesa_ClearBufferfv(GL_COLOR, 0, colorValue.f); + break; + } + + return true; +} + +static bool +cleartexsubimage_depth_stencil(struct gl_context *ctx, + struct gl_texture_image *texImage, + const GLvoid *clearValue, + GLint zoffset) +{ + GLint stencilValue; + GLfloat depthValue; + GLenum status; + + _mesa_meta_bind_fbo_image(GL_DEPTH_ATTACHMENT, texImage, zoffset); + + if (texImage->_BaseFormat == GL_DEPTH_STENCIL) + _mesa_meta_bind_fbo_image(GL_STENCIL_ATTACHMENT, texImage, zoffset); + + status = _mesa_CheckFramebufferStatus(GL_DRAW_FRAMEBUFFER); + if (status != GL_FRAMEBUFFER_COMPLETE) + return false; + + if (clearValue) { + GLuint depthStencilValue[2]; + + /* Convert the clearValue from whatever format it's in to a floating + * point value for the depth and an integer value for the stencil index + */ + _mesa_unpack_float_32_uint_24_8_depth_stencil_row(texImage->TexFormat, + 1, /* n */ + clearValue, + depthStencilValue); + /* We need a memcpy here instead of a cast because we need to + * reinterpret the bytes as a float rather than converting it + */ + memcpy(&depthValue, depthStencilValue, sizeof depthValue); + stencilValue = depthStencilValue[1] & 0xff; + } else { + depthValue = 0.0f; + stencilValue = 0; + } + + if (texImage->_BaseFormat == GL_DEPTH_STENCIL) + _mesa_ClearBufferfi(GL_DEPTH_STENCIL, 0, depthValue, stencilValue); + else + _mesa_ClearBufferfv(GL_DEPTH, 0, &depthValue); + + return true; +} + +static bool +cleartexsubimage_for_zoffset(struct gl_context *ctx, + struct gl_texture_image *texImage, + GLint zoffset, + const GLvoid *clearValue) +{ + GLuint fbo; + bool success; + + _mesa_GenFramebuffers(1, &fbo); + _mesa_BindFramebuffer(GL_DRAW_FRAMEBUFFER, fbo); + + switch(texImage->_BaseFormat) { + case GL_DEPTH_STENCIL: + case GL_DEPTH_COMPONENT: + success = cleartexsubimage_depth_stencil(ctx, texImage, + clearValue, zoffset); + break; + default: + success = cleartexsubimage_color(ctx, texImage, clearValue, zoffset); + break; + } + + _mesa_DeleteFramebuffers(1, &fbo); + + return success; +} + +static bool +cleartexsubimage_using_fbo(struct gl_context *ctx, + struct gl_texture_image *texImage, + GLint xoffset, GLint yoffset, GLint zoffset, + GLsizei width, GLsizei height, GLsizei depth, + const GLvoid *clearValue) +{ + bool success = true; + GLint z; + + _mesa_meta_begin(ctx, + MESA_META_SCISSOR | + MESA_META_COLOR_MASK | + MESA_META_DITHER | + MESA_META_FRAMEBUFFER_SRGB); + + _mesa_set_enable(ctx, GL_DITHER, GL_FALSE); + + _mesa_set_enable(ctx, GL_SCISSOR_TEST, GL_TRUE); + _mesa_Scissor(xoffset, yoffset, width, height); + + for (z = zoffset; z < zoffset + depth; z++) { + if (!cleartexsubimage_for_zoffset(ctx, texImage, z, clearValue)) { + success = false; + break; + } + } + + _mesa_meta_end(ctx); + + return success; +} + +extern void +_mesa_meta_ClearTexSubImage(struct gl_context *ctx, + struct gl_texture_image *texImage, + GLint xoffset, GLint yoffset, GLint zoffset, + GLsizei width, GLsizei height, GLsizei depth, + const GLvoid *clearValue) +{ + bool res; + + _mesa_unlock_texture(ctx, texImage->TexObject); + + res = cleartexsubimage_using_fbo(ctx, texImage, + xoffset, yoffset, zoffset, + width, height, depth, + clearValue); + + _mesa_lock_texture(ctx, texImage->TexObject); + + if (res) + return; + + _mesa_warning(ctx, + "Falling back to mapping the texture in " + "glClearTexSubImage\n"); + + _mesa_store_cleartexsubimage(ctx, texImage, + xoffset, yoffset, zoffset, + width, height, depth, + clearValue); +} diff --git a/mesalib/src/mesa/drivers/common/meta.h b/mesalib/src/mesa/drivers/common/meta.h index 765f8dfe4..b269dceed 100644 --- a/mesalib/src/mesa/drivers/common/meta.h +++ b/mesalib/src/mesa/drivers/common/meta.h @@ -59,6 +59,7 @@ #define MESA_META_FRAMEBUFFER_SRGB 0x200000 #define MESA_META_OCCLUSION_QUERY 0x400000 #define MESA_META_DRAW_BUFFERS 0x800000 +#define MESA_META_DITHER 0x1000000 /**\}*/ /** @@ -84,6 +85,9 @@ struct save_state GLbitfield BlendEnabled; GLboolean ColorLogicOpEnabled; + /** MESA_META_DITHER */ + GLboolean DitherFlag; + /** MESA_META_COLOR_MASK */ GLubyte ColorMask[MAX_DRAW_BUFFERS][4]; @@ -473,6 +477,13 @@ _mesa_meta_CopyTexSubImage(struct gl_context *ctx, GLuint dims, GLsizei width, GLsizei height); extern void +_mesa_meta_ClearTexSubImage(struct gl_context *ctx, + struct gl_texture_image *texImage, + GLint xoffset, GLint yoffset, GLint zoffset, + GLsizei width, GLsizei height, GLsizei depth, + const GLvoid *clearValue); + +extern void _mesa_meta_GetTexImage(struct gl_context *ctx, GLenum format, GLenum type, GLvoid *pixels, struct gl_texture_image *texImage); diff --git a/mesalib/src/mesa/main/config.h b/mesalib/src/mesa/main/config.h index c96502a7f..4ec4b7502 100644 --- a/mesalib/src/mesa/main/config.h +++ b/mesalib/src/mesa/main/config.h @@ -289,6 +289,17 @@ #define PERFQUERY_HAVE_GPA_EXTENDED_COUNTERS 0 /*@}*/ +/** For GL_ARB_compute_shader */ +/*@{*/ +#define MAX_COMPUTE_UNIFORM_BLOCKS 12 +#define MAX_COMPUTE_TEXTURE_IMAGE_UNITS 16 +#define MAX_COMPUTE_ATOMIC_COUNTER_BUFFERS 8 +#define MAX_COMPUTE_ATOMIC_COUNTERS 8 +#define MAX_COMPUTE_SHARED_MEMORY_SIZE 32768 +#define MAX_COMPUTE_UNIFORM_COMPONENTS 512 +#define MAX_COMPUTE_IMAGE_UNIFORMS 8 +/*@}*/ + /* * Color channel component order * diff --git a/mesalib/src/mesa/main/dd.h b/mesalib/src/mesa/main/dd.h index 633ea2c3a..89765351e 100644 --- a/mesalib/src/mesa/main/dd.h +++ b/mesalib/src/mesa/main/dd.h @@ -239,6 +239,20 @@ struct dd_function_table { struct gl_texture_image *texImage ); /** + * Called by glClearTex[Sub]Image + * + * Clears a rectangular region of the image to a given value. The + * clearValue argument is either NULL or points to a single texel to use as + * the clear value in the same internal format as the texture image. If it + * is NULL then the texture should be cleared to zeroes. + */ + void (*ClearTexSubImage)(struct gl_context *ctx, + struct gl_texture_image *texImage, + GLint xoffset, GLint yoffset, GLint zoffset, + GLsizei width, GLsizei height, GLsizei depth, + const GLvoid *clearValue); + + /** * Called by glCopyTex[Sub]Image[123]D(). * * This function should copy a rectangular region in the rb to a single diff --git a/mesalib/src/mesa/main/extensions.c b/mesalib/src/mesa/main/extensions.c index 92e3f0d68..9ac8377a4 100644 --- a/mesalib/src/mesa/main/extensions.c +++ b/mesalib/src/mesa/main/extensions.c @@ -90,6 +90,7 @@ static const struct extension extension_table[] = { { "GL_ARB_blend_func_extended", o(ARB_blend_func_extended), GL, 2009 }, { "GL_ARB_buffer_storage", o(ARB_buffer_storage), GL, 2013 }, { "GL_ARB_clear_buffer_object", o(dummy_true), GL, 2012 }, + { "GL_ARB_clear_texture", o(ARB_clear_texture), GL, 2013 }, { "GL_ARB_color_buffer_float", o(ARB_color_buffer_float), GL, 2004 }, { "GL_ARB_compressed_texture_pixel_storage", o(dummy_true), GL, 2011 }, { "GL_ARB_compute_shader", o(ARB_compute_shader), GL, 2012 }, diff --git a/mesalib/src/mesa/main/get_hash_params.py b/mesalib/src/mesa/main/get_hash_params.py index d45962d95..35d6172a3 100644 --- a/mesalib/src/mesa/main/get_hash_params.py +++ b/mesalib/src/mesa/main/get_hash_params.py @@ -774,6 +774,13 @@ descriptor=[ # GL_ARB_compute_shader [ "MAX_COMPUTE_WORK_GROUP_INVOCATIONS", "CONTEXT_INT(Const.MaxComputeWorkGroupInvocations), extra_ARB_compute_shader" ], + [ "MAX_COMPUTE_UNIFORM_BLOCKS", "CONST(MAX_COMPUTE_UNIFORM_BLOCKS), extra_ARB_compute_shader" ], + [ "MAX_COMPUTE_TEXTURE_IMAGE_UNITS", "CONST(MAX_COMPUTE_TEXTURE_IMAGE_UNITS), extra_ARB_compute_shader" ], + [ "MAX_COMPUTE_ATOMIC_COUNTER_BUFFERS", "CONST(MAX_COMPUTE_ATOMIC_COUNTER_BUFFERS), extra_ARB_compute_shader" ], + [ "MAX_COMPUTE_ATOMIC_COUNTERS", "CONST(MAX_COMPUTE_ATOMIC_COUNTERS), extra_ARB_compute_shader" ], + [ "MAX_COMPUTE_SHARED_MEMORY_SIZE", "CONST(MAX_COMPUTE_SHARED_MEMORY_SIZE), extra_ARB_compute_shader" ], + [ "MAX_COMPUTE_UNIFORM_COMPONENTS", "CONST(MAX_COMPUTE_UNIFORM_COMPONENTS), extra_ARB_compute_shader" ], + [ "MAX_COMPUTE_IMAGE_UNIFORMS", "CONST(MAX_COMPUTE_IMAGE_UNIFORMS), extra_ARB_compute_shader" ], # GL_ARB_gpu_shader5 [ "MAX_GEOMETRY_SHADER_INVOCATIONS", "CONST(MAX_GEOMETRY_SHADER_INVOCATIONS), extra_ARB_gpu_shader5" ], diff --git a/mesalib/src/mesa/main/imports.h b/mesalib/src/mesa/main/imports.h index af780b249..09e55ebf0 100644 --- a/mesalib/src/mesa/main/imports.h +++ b/mesalib/src/mesa/main/imports.h @@ -274,10 +274,12 @@ static inline int IROUND_POS(float f) return (int) (f + 0.5F); } +#ifdef __x86_64__ +# include <xmmintrin.h> +#endif /** * Convert float to int using a fast method. The rounding mode may vary. - * XXX We could use an x86-64/SSE2 version here. */ static inline int F_TO_I(float f) { @@ -292,6 +294,8 @@ static inline int F_TO_I(float f) fistp r } return r; +#elif defined(__x86_64__) + return _mm_cvt_ss2si(_mm_load_ss(&f)); #else return IROUND(f); #endif diff --git a/mesalib/src/mesa/main/mtypes.h b/mesalib/src/mesa/main/mtypes.h index 91d9172f9..3f60a5530 100644 --- a/mesalib/src/mesa/main/mtypes.h +++ b/mesalib/src/mesa/main/mtypes.h @@ -3527,6 +3527,7 @@ struct gl_extensions GLboolean ARB_base_instance; GLboolean ARB_blend_func_extended; GLboolean ARB_buffer_storage; + GLboolean ARB_clear_texture; GLboolean ARB_color_buffer_float; GLboolean ARB_compute_shader; GLboolean ARB_conservative_depth; diff --git a/mesalib/src/mesa/main/teximage.c b/mesalib/src/mesa/main/teximage.c index a06959463..fb2dee7d8 100644 --- a/mesalib/src/mesa/main/teximage.c +++ b/mesalib/src/mesa/main/teximage.c @@ -51,6 +51,7 @@ #include "textureview.h" #include "mtypes.h" #include "glformats.h" +#include "texstore.h" /** @@ -2010,6 +2011,43 @@ _mesa_legal_texture_base_format_for_target(struct gl_context *ctx, return true; } +static bool +texture_formats_agree(GLenum internalFormat, + GLenum format) +{ + GLboolean colorFormat; + GLboolean is_format_depth_or_depthstencil; + GLboolean is_internalFormat_depth_or_depthstencil; + + /* Even though there are no color-index textures, we still have to support + * uploading color-index data and remapping it to RGB via the + * GL_PIXEL_MAP_I_TO_[RGBA] tables. + */ + const GLboolean indexFormat = (format == GL_COLOR_INDEX); + + is_internalFormat_depth_or_depthstencil = + _mesa_is_depth_format(internalFormat) || + _mesa_is_depthstencil_format(internalFormat); + + is_format_depth_or_depthstencil = + _mesa_is_depth_format(format) || + _mesa_is_depthstencil_format(format); + + colorFormat = _mesa_is_color_format(format); + + if (_mesa_is_color_format(internalFormat) && !colorFormat && !indexFormat) + return false; + + if (is_internalFormat_depth_or_depthstencil != + is_format_depth_or_depthstencil) + return false; + + if (_mesa_is_ycbcr_format(internalFormat) != _mesa_is_ycbcr_format(format)) + return false; + + return true; +} + /** * Test the glTexImage[123]D() parameters for errors. * @@ -2043,17 +2081,8 @@ texture_error_check( struct gl_context *ctx, GLint width, GLint height, GLint depth, GLint border ) { - GLboolean colorFormat; - GLboolean is_format_depth_or_depthstencil; - GLboolean is_internalFormat_depth_or_depthstencil; GLenum err; - /* Even though there are no color-index textures, we still have to support - * uploading color-index data and remapping it to RGB via the - * GL_PIXEL_MAP_I_TO_[RGBA] tables. - */ - const GLboolean indexFormat = (format == GL_COLOR_INDEX); - /* Note: for proxy textures, some error conditions immediately generate * a GL error in the usual way. But others do not generate a GL error. * Instead, they cause the width, height, depth, format fields of the @@ -2136,18 +2165,7 @@ texture_error_check( struct gl_context *ctx, } /* make sure internal format and format basically agree */ - is_internalFormat_depth_or_depthstencil = - _mesa_is_depth_format(internalFormat) || - _mesa_is_depthstencil_format(internalFormat); - - is_format_depth_or_depthstencil = - _mesa_is_depth_format(format) || - _mesa_is_depthstencil_format(format); - - colorFormat = _mesa_is_color_format(format); - if ((_mesa_is_color_format(internalFormat) && !colorFormat && !indexFormat) || - (is_internalFormat_depth_or_depthstencil != is_format_depth_or_depthstencil) || - (_mesa_is_ycbcr_format(internalFormat) != _mesa_is_ycbcr_format(format))) { + if (!texture_formats_agree(internalFormat, format)) { _mesa_error(ctx, GL_INVALID_OPERATION, "glTexImage%dD(incompatible internalFormat = %s, format = %s)", dimensions, _mesa_lookup_enum_by_nr(internalFormat), @@ -3818,6 +3836,266 @@ _mesa_CopyTexSubImage3D( GLenum target, GLint level, x, y, width, height); } +static bool +check_clear_tex_image(struct gl_context *ctx, + const char *function, + struct gl_texture_image *texImage, + GLenum format, GLenum type, + const void *data, + GLubyte *clearValue) +{ + struct gl_texture_object *texObj = texImage->TexObject; + static const GLubyte zeroData[MAX_PIXEL_BYTES]; + GLenum internalFormat = texImage->InternalFormat; + GLenum err; + + if (texObj->Target == GL_TEXTURE_BUFFER) { + _mesa_error(ctx, GL_INVALID_OPERATION, + "%s(buffer texture)", function); + return false; + } + + if (_mesa_is_compressed_format(ctx, internalFormat)) { + _mesa_error(ctx, GL_INVALID_OPERATION, + "%s(compressed texture)", function); + return false; + } + + err = _mesa_error_check_format_and_type(ctx, format, type); + if (err != GL_NO_ERROR) { + _mesa_error(ctx, err, + "%s(incompatible format = %s, type = %s)", + function, + _mesa_lookup_enum_by_nr(format), + _mesa_lookup_enum_by_nr(type)); + return false; + } + + /* make sure internal format and format basically agree */ + if (!texture_formats_agree(internalFormat, format)) { + _mesa_error(ctx, GL_INVALID_OPERATION, + "%s(incompatible internalFormat = %s, format = %s)", + function, + _mesa_lookup_enum_by_nr(internalFormat), + _mesa_lookup_enum_by_nr(format)); + return false; + } + + if (ctx->Version >= 30 || ctx->Extensions.EXT_texture_integer) { + /* both source and dest must be integer-valued, or neither */ + if (_mesa_is_format_integer_color(texImage->TexFormat) != + _mesa_is_enum_format_integer(format)) { + _mesa_error(ctx, GL_INVALID_OPERATION, + "%s(integer/non-integer format mismatch)", + function); + return false; + } + } + + if (!_mesa_texstore(ctx, + 1, /* dims */ + texImage->_BaseFormat, + texImage->TexFormat, + 0, /* dstRowStride */ + &clearValue, + 1, 1, 1, /* srcWidth/Height/Depth */ + format, type, + data ? data : zeroData, + &ctx->DefaultPacking)) { + _mesa_error(ctx, GL_INVALID_OPERATION, "%s(invalid format)", function); + return false; + } + + return true; +} + +static struct gl_texture_object * +get_tex_obj_for_clear(struct gl_context *ctx, + const char *function, + GLuint texture) +{ + struct gl_texture_object *texObj; + + if (texture == 0) { + _mesa_error(ctx, GL_INVALID_OPERATION, "%s(zero texture)", function); + return NULL; + } + + texObj = _mesa_lookup_texture(ctx, texture); + + if (texObj == NULL) { + _mesa_error(ctx, GL_INVALID_OPERATION, "%s(non-gen name)", function); + return NULL; + } + + if (texObj->Target == 0) { + _mesa_error(ctx, GL_INVALID_OPERATION, "%s(unbound tex)", function); + return NULL; + } + + return texObj; +} + +static int +get_tex_images_for_clear(struct gl_context *ctx, + const char *function, + struct gl_texture_object *texObj, + GLint level, + struct gl_texture_image **texImages) +{ + GLenum target; + int i; + + if (level < 0 || level >= MAX_TEXTURE_LEVELS) { + _mesa_error(ctx, GL_INVALID_OPERATION, "%s(invalid level)", function); + return 0; + } + + if (texObj->Target == GL_TEXTURE_CUBE_MAP) { + for (i = 0; i < MAX_FACES; i++) { + target = GL_TEXTURE_CUBE_MAP_POSITIVE_X + i; + + texImages[i] = _mesa_select_tex_image(ctx, texObj, target, level); + if (texImages[i] == NULL) { + _mesa_error(ctx, GL_INVALID_OPERATION, + "%s(invalid level)", function); + return 0; + } + } + + return MAX_FACES; + } + + texImages[0] = _mesa_select_tex_image(ctx, texObj, texObj->Target, level); + + if (texImages[0] == NULL) { + _mesa_error(ctx, GL_INVALID_OPERATION, "%s(invalid level)", function); + return 0; + } + + return 1; +} + +void GLAPIENTRY +_mesa_ClearTexSubImage( GLuint texture, GLint level, + GLint xoffset, GLint yoffset, GLint zoffset, + GLsizei width, GLsizei height, GLsizei depth, + GLenum format, GLenum type, const void *data ) +{ + GET_CURRENT_CONTEXT(ctx); + struct gl_texture_object *texObj; + struct gl_texture_image *texImages[MAX_FACES]; + GLubyte clearValue[MAX_FACES][MAX_PIXEL_BYTES]; + int i, numImages; + int minDepth, maxDepth; + + texObj = get_tex_obj_for_clear(ctx, "glClearTexSubImage", texture); + + if (texObj == NULL) + return; + + _mesa_lock_texture(ctx, texObj); + + numImages = get_tex_images_for_clear(ctx, "glClearTexSubImage", + texObj, level, texImages); + if (numImages == 0) + goto out; + + if (numImages == 1) { + minDepth = -(int) texImages[0]->Border; + maxDepth = texImages[0]->Depth; + } else { + minDepth = 0; + maxDepth = numImages; + } + + if (xoffset < -(GLint) texImages[0]->Border || + yoffset < -(GLint) texImages[0]->Border || + zoffset < minDepth || + width < 0 || + height < 0 || + depth < 0 || + xoffset + width > texImages[0]->Width || + yoffset + height > texImages[0]->Height || + zoffset + depth > maxDepth) { + _mesa_error(ctx, GL_INVALID_OPERATION, + "glClearSubTexImage(invalid dimensions)"); + goto out; + } + + if (numImages == 1) { + if (check_clear_tex_image(ctx, "glClearTexSubImage", + texImages[0], + format, type, data, clearValue[0])) { + ctx->Driver.ClearTexSubImage(ctx, + texImages[0], + xoffset, yoffset, zoffset, + width, height, depth, + data ? clearValue[0] : NULL); + } + } else { + for (i = zoffset; i < zoffset + depth; i++) { + if (!check_clear_tex_image(ctx, "glClearTexSubImage", + texImages[i], + format, type, data, clearValue[i])) + goto out; + } + for (i = zoffset; i < zoffset + depth; i++) { + ctx->Driver.ClearTexSubImage(ctx, + texImages[i], + xoffset, yoffset, 0, + width, height, 1, + data ? clearValue[i] : NULL); + } + } + + out: + _mesa_unlock_texture(ctx, texObj); +} + +void GLAPIENTRY +_mesa_ClearTexImage( GLuint texture, GLint level, + GLenum format, GLenum type, const void *data ) +{ + GET_CURRENT_CONTEXT(ctx); + struct gl_texture_object *texObj; + struct gl_texture_image *texImages[MAX_FACES]; + GLubyte clearValue[MAX_FACES][MAX_PIXEL_BYTES]; + int i, numImages; + + texObj = get_tex_obj_for_clear(ctx, "glClearTexImage", texture); + + if (texObj == NULL) + return; + + _mesa_lock_texture(ctx, texObj); + + numImages = get_tex_images_for_clear(ctx, "glClearTexImage", + texObj, level, texImages); + + for (i = 0; i < numImages; i++) { + if (!check_clear_tex_image(ctx, "glClearTexImage", + texImages[i], + format, type, data, + clearValue[i])) + goto out; + } + + for (i = 0; i < numImages; i++) { + ctx->Driver.ClearTexSubImage(ctx, texImages[i], + -(GLint) texImages[i]->Border, /* xoffset */ + -(GLint) texImages[i]->Border, /* yoffset */ + -(GLint) texImages[i]->Border, /* zoffset */ + texImages[i]->Width, + texImages[i]->Height, + texImages[i]->Depth, + data ? clearValue[i] : NULL); + } + +out: + _mesa_unlock_texture(ctx, texObj); +} + @@ -4578,7 +4856,6 @@ _mesa_TexStorage2DMultisample(GLenum target, GLsizei samples, "glTexStorage2DMultisample"); } - void GLAPIENTRY _mesa_TexStorage3DMultisample(GLenum target, GLsizei samples, GLenum internalformat, GLsizei width, diff --git a/mesalib/src/mesa/main/teximage.h b/mesalib/src/mesa/main/teximage.h index dd1504b40..42305f44f 100644 --- a/mesalib/src/mesa/main/teximage.h +++ b/mesalib/src/mesa/main/teximage.h @@ -261,6 +261,16 @@ _mesa_CopyTexSubImage3D( GLenum target, GLint level, extern void GLAPIENTRY +_mesa_ClearTexSubImage( GLuint texture, GLint level, + GLint xoffset, GLint yoffset, GLint zoffset, + GLsizei width, GLsizei height, GLsizei depth, + GLenum format, GLenum type, const void *data ); + +extern void GLAPIENTRY +_mesa_ClearTexImage( GLuint texture, GLint level, + GLenum format, GLenum type, const void *data ); + +extern void GLAPIENTRY _mesa_CompressedTexImage1D(GLenum target, GLint level, GLenum internalformat, GLsizei width, GLint border, GLsizei imageSize, diff --git a/mesalib/src/mesa/main/texstore.c b/mesalib/src/mesa/main/texstore.c index d363f9faa..aea53f8d1 100644 --- a/mesalib/src/mesa/main/texstore.c +++ b/mesalib/src/mesa/main/texstore.c @@ -3830,6 +3830,21 @@ _mesa_texstore_can_use_memcpy(struct gl_context *ctx, return GL_FALSE; } + /* Depth texture data needs clamping in following cases: + * - Floating point dstFormat with signed srcType: clamp to [0.0, 1.0]. + * - Fixed point dstFormat with signed srcType: clamp to [0, 2^n -1]. + * + * All the cases except one (float dstFormat with float srcType) are ruled + * out by _mesa_format_matches_format_and_type() check above. Handle the + * remaining case here. + */ + if ((baseInternalFormat == GL_DEPTH_COMPONENT || + baseInternalFormat == GL_DEPTH_STENCIL) && + (srcType == GL_FLOAT || + srcType == GL_FLOAT_32_UNSIGNED_INT_24_8_REV)) { + return GL_FALSE; + } + return GL_TRUE; } @@ -4079,6 +4094,78 @@ _mesa_store_texsubimage(struct gl_context *ctx, GLuint dims, format, type, pixels, packing, "glTexSubImage"); } +static void +clear_image_to_zero(GLubyte *dstMap, GLint dstRowStride, + GLsizei width, GLsizei height, + GLsizei clearValueSize) +{ + GLsizei y; + + for (y = 0; y < height; y++) { + memset(dstMap, 0, clearValueSize * width); + dstMap += dstRowStride; + } +} + +static void +clear_image_to_value(GLubyte *dstMap, GLint dstRowStride, + GLsizei width, GLsizei height, + const GLvoid *clearValue, + GLsizei clearValueSize) +{ + GLsizei y, x; + + for (y = 0; y < height; y++) { + for (x = 0; x < width; x++) { + memcpy(dstMap, clearValue, clearValueSize); + dstMap += clearValueSize; + } + dstMap += dstRowStride - clearValueSize * width; + } +} + +/* + * Fallback for Driver.ClearTexSubImage(). + */ +void +_mesa_store_cleartexsubimage(struct gl_context *ctx, + struct gl_texture_image *texImage, + GLint xoffset, GLint yoffset, GLint zoffset, + GLsizei width, GLsizei height, GLsizei depth, + const GLvoid *clearValue) +{ + GLubyte *dstMap; + GLint dstRowStride; + GLsizeiptr clearValueSize; + GLsizei z; + + clearValueSize = _mesa_get_format_bytes(texImage->TexFormat); + + for (z = 0; z < depth; z++) { + ctx->Driver.MapTextureImage(ctx, texImage, + z + zoffset, xoffset, yoffset, + width, height, + GL_MAP_WRITE_BIT, + &dstMap, &dstRowStride); + if (dstMap == NULL) { + _mesa_error(ctx, GL_OUT_OF_MEMORY, "glClearTex*Image"); + return; + } + + if (clearValue) { + clear_image_to_value(dstMap, dstRowStride, + width, height, + clearValue, + clearValueSize); + } else { + clear_image_to_zero(dstMap, dstRowStride, + width, height, + clearValueSize); + } + + ctx->Driver.UnmapTextureImage(ctx, texImage, z + zoffset); + } +} /** * Fallback for Driver.CompressedTexImage() diff --git a/mesalib/src/mesa/main/texstore.h b/mesalib/src/mesa/main/texstore.h index c4cfffde6..dd1e1d015 100644 --- a/mesalib/src/mesa/main/texstore.h +++ b/mesalib/src/mesa/main/texstore.h @@ -118,6 +118,13 @@ _mesa_store_texsubimage(struct gl_context *ctx, GLuint dims, extern void +_mesa_store_cleartexsubimage(struct gl_context *ctx, + struct gl_texture_image *texImage, + GLint xoffset, GLint yoffset, GLint zoffset, + GLsizei width, GLsizei height, GLsizei depth, + const GLvoid *clearValue); + +extern void _mesa_store_compressed_teximage(struct gl_context *ctx, GLuint dims, struct gl_texture_image *texImage, GLsizei imageSize, const GLvoid *data); diff --git a/mesalib/src/mesa/main/uniform_query.cpp b/mesalib/src/mesa/main/uniform_query.cpp index 480bc6f16..609d94bd7 100644 --- a/mesalib/src/mesa/main/uniform_query.cpp +++ b/mesalib/src/mesa/main/uniform_query.cpp @@ -91,7 +91,7 @@ _mesa_GetActiveUniformsiv(GLuint program, if (uniformCount < 0) { _mesa_error(ctx, GL_INVALID_VALUE, - "glGetUniformIndices(uniformCount < 0)"); + "glGetActiveUniformsiv(uniformCount < 0)"); return; } diff --git a/mesalib/src/mesa/state_tracker/st_glsl_to_tgsi.cpp b/mesalib/src/mesa/state_tracker/st_glsl_to_tgsi.cpp index 5c51e63d9..5ea146547 100644 --- a/mesalib/src/mesa/state_tracker/st_glsl_to_tgsi.cpp +++ b/mesalib/src/mesa/state_tracker/st_glsl_to_tgsi.cpp @@ -2028,6 +2028,15 @@ glsl_to_tgsi_visitor::visit(ir_expression *ir) */ emit(ir, TGSI_OPCODE_MAD, result_dst, op[0], op[1], op[2]); break; + case ir_unop_interpolate_at_centroid: + emit(ir, TGSI_OPCODE_INTERP_CENTROID, result_dst, op[0]); + break; + case ir_binop_interpolate_at_offset: + emit(ir, TGSI_OPCODE_INTERP_OFFSET, result_dst, op[0], op[1]); + break; + case ir_binop_interpolate_at_sample: + emit(ir, TGSI_OPCODE_INTERP_SAMPLE, result_dst, op[0], op[1]); + break; case ir_unop_pack_snorm_2x16: case ir_unop_pack_unorm_2x16: case ir_unop_pack_half_2x16: @@ -2049,9 +2058,6 @@ glsl_to_tgsi_visitor::visit(ir_expression *ir) case ir_binop_ldexp: case ir_binop_carry: case ir_binop_borrow: - case ir_unop_interpolate_at_centroid: - case ir_binop_interpolate_at_offset: - case ir_binop_interpolate_at_sample: /* This operation is not supported, or should have already been handled. */ assert(!"Invalid ir opcode in glsl_to_tgsi_visitor::visit()"); diff --git a/tools/plink/ssh.c b/tools/plink/ssh.c index 7e63b4e0b..893321e2b 100644 --- a/tools/plink/ssh.c +++ b/tools/plink/ssh.c @@ -6226,6 +6226,10 @@ static void do_ssh2_transport(Ssh ssh, void *vin, int inlen, pktin->savedpos += 16; /* skip garbage cookie */ ssh_pkt_getstring(pktin, &str, &len); /* key exchange algorithms */ + if (!str) { + bombout(("KEXINIT packet was incomplete")); + crStopV; + } preferred = NULL; for (i = 0; i < s->n_preferred_kex; i++) { @@ -6245,8 +6249,8 @@ static void do_ssh2_transport(Ssh ssh, void *vin, int inlen, break; } if (!ssh->kex) { - bombout(("Couldn't agree a key exchange algorithm (available: %s)", - str ? str : "(null)")); + bombout(("Couldn't agree a key exchange algorithm" + " (available: %.*s)", len, str)); crStopV; } /* @@ -6256,6 +6260,10 @@ static void do_ssh2_transport(Ssh ssh, void *vin, int inlen, */ s->guessok = first_in_commasep_string(preferred, str, len); ssh_pkt_getstring(pktin, &str, &len); /* host key algorithms */ + if (!str) { + bombout(("KEXINIT packet was incomplete")); + crStopV; + } for (i = 0; i < lenof(hostkey_algs); i++) { if (in_commasep_string(hostkey_algs[i]->name, str, len)) { ssh->hostkey = hostkey_algs[i]; @@ -6263,14 +6271,18 @@ static void do_ssh2_transport(Ssh ssh, void *vin, int inlen, } } if (!ssh->hostkey) { - bombout(("Couldn't agree a host key algorithm (available: %s)", - str ? str : "(null)")); + bombout(("Couldn't agree a host key algorithm" + " (available: %.*s)", len, str)); crStopV; } s->guessok = s->guessok && first_in_commasep_string(hostkey_algs[0]->name, str, len); ssh_pkt_getstring(pktin, &str, &len); /* client->server cipher */ + if (!str) { + bombout(("KEXINIT packet was incomplete")); + crStopV; + } for (i = 0; i < s->n_preferred_ciphers; i++) { const struct ssh2_ciphers *c = s->preferred_ciphers[i]; if (!c) { @@ -6287,12 +6299,16 @@ static void do_ssh2_transport(Ssh ssh, void *vin, int inlen, break; } if (!s->cscipher_tobe) { - bombout(("Couldn't agree a client-to-server cipher (available: %s)", - str ? str : "(null)")); + bombout(("Couldn't agree a client-to-server cipher" + " (available: %.*s)", len, str)); crStopV; } ssh_pkt_getstring(pktin, &str, &len); /* server->client cipher */ + if (!str) { + bombout(("KEXINIT packet was incomplete")); + crStopV; + } for (i = 0; i < s->n_preferred_ciphers; i++) { const struct ssh2_ciphers *c = s->preferred_ciphers[i]; if (!c) { @@ -6309,12 +6325,16 @@ static void do_ssh2_transport(Ssh ssh, void *vin, int inlen, break; } if (!s->sccipher_tobe) { - bombout(("Couldn't agree a server-to-client cipher (available: %s)", - str ? str : "(null)")); + bombout(("Couldn't agree a server-to-client cipher" + " (available: %.*s)", len, str)); crStopV; } ssh_pkt_getstring(pktin, &str, &len); /* client->server mac */ + if (!str) { + bombout(("KEXINIT packet was incomplete")); + crStopV; + } for (i = 0; i < s->nmacs; i++) { if (in_commasep_string(s->maclist[i]->name, str, len)) { s->csmac_tobe = s->maclist[i]; @@ -6322,6 +6342,10 @@ static void do_ssh2_transport(Ssh ssh, void *vin, int inlen, } } ssh_pkt_getstring(pktin, &str, &len); /* server->client mac */ + if (!str) { + bombout(("KEXINIT packet was incomplete")); + crStopV; + } for (i = 0; i < s->nmacs; i++) { if (in_commasep_string(s->maclist[i]->name, str, len)) { s->scmac_tobe = s->maclist[i]; @@ -6329,6 +6353,10 @@ static void do_ssh2_transport(Ssh ssh, void *vin, int inlen, } } ssh_pkt_getstring(pktin, &str, &len); /* client->server compression */ + if (!str) { + bombout(("KEXINIT packet was incomplete")); + crStopV; + } for (i = 0; i < lenof(compressions) + 1; i++) { const struct ssh_compress *c = i == 0 ? s->preferred_comp : compressions[i - 1]; @@ -6345,6 +6373,10 @@ static void do_ssh2_transport(Ssh ssh, void *vin, int inlen, } } ssh_pkt_getstring(pktin, &str, &len); /* server->client compression */ + if (!str) { + bombout(("KEXINIT packet was incomplete")); + crStopV; + } for (i = 0; i < lenof(compressions) + 1; i++) { const struct ssh_compress *c = i == 0 ? s->preferred_comp : compressions[i - 1]; diff --git a/xorg-server/configure.ac b/xorg-server/configure.ac index 4338dc551..f3d9654a4 100644 --- a/xorg-server/configure.ac +++ b/xorg-server/configure.ac @@ -139,7 +139,8 @@ AC_CHECK_HEADERS([fcntl.h stdlib.h string.h unistd.h dlfcn.h stropts.h \ dnl Checks for typedefs, structures, and compiler characteristics. AC_C_CONST AC_C_TYPEOF -AC_C_BIGENDIAN([ENDIAN="X_BIG_ENDIAN"], [ENDIAN="X_LITTLE_ENDIAN"]) +AC_C_BIGENDIAN(AC_DEFINE(X_BYTE_ORDER, X_BIG_ENDIAN, [byte order]), + AC_DEFINE(X_BYTE_ORDER, X_LITTLE_ENDIAN, [byte order])) AC_CHECK_SIZEOF([unsigned long]) if test "$ac_cv_sizeof_unsigned_long" = 8; then @@ -648,6 +649,7 @@ AC_ARG_ENABLE(kdrive-kbd, AS_HELP_STRING([--enable-kdrive-kbd], [Build kbd d AC_ARG_ENABLE(kdrive-mouse, AS_HELP_STRING([--enable-kdrive-mouse], [Build mouse driver for kdrive (default: auto)]), [KDRIVE_MOUSE=$enableval], [KDRIVE_MOUSE=auto]) AC_ARG_ENABLE(kdrive-evdev, AS_HELP_STRING([--enable-kdrive-evdev], [Build evdev driver for kdrive (default: auto)]), [KDRIVE_EVDEV=$enableval], [KDRIVE_EVDEV=auto]) AC_ARG_ENABLE(libunwind, AS_HELP_STRING([--enable-libunwind], [Use libunwind for backtracing (default: auto)]), [LIBUNWIND="$enableval"], [LIBUNWIND="auto"]) +AC_ARG_ENABLE(xshmfence, AS_HELP_STRING([--disable-xshmfence], [Disable xshmfence (default: auto)]), [XSHMFENCE="$enableval"], [XSHMFENCE="auto"]) dnl chown/chmod to be setuid root as part of build @@ -787,7 +789,7 @@ DMXPROTO="dmxproto >= 2.2.99.1" VIDMODEPROTO="xf86vidmodeproto >= 2.2.99.1" WINDOWSWMPROTO="windowswmproto" APPLEWMPROTO="applewmproto >= 1.4" -XSHMFENCE="xshmfence >= 1.1" +LIBXSHMFENCE="xshmfence >= 1.1" dnl Required modules XPROTO="xproto >= 7.0.26" @@ -1235,20 +1237,23 @@ esac AM_CONDITIONAL(BUSFAULT, test x"$BUSFAULT" = xyes) -PKG_CHECK_MODULES([XSHMFENCE], $XSHMFENCE, - [HAVE_XSHMFENCE=yes], [HAVE_XSHMFENCE=no]) -AM_CONDITIONAL(XSHMFENCE, test "x$HAVE_XSHMFENCE" = xyes) +PKG_CHECK_MODULES([XSHMFENCE], $LIBXSHMFENCE, [HAVE_XSHMFENCE=yes], [HAVE_XSHMFENCE=no]) +if test "x$XSHMFENCE" = "xauto"; then + XSHMFENCE="$HAVE_XSHMFENCE" +fi -case x"$HAVE_XSHMFENCE" in - xyes) - AC_DEFINE(HAVE_XSHMFENCE, 1, [Have X Shared Memory Fence library]) - REQUIRED_LIBS="$REQUIRED_LIBS xshmfence" - ;; -esac +if test "x$XSHMFENCE" = "xyes"; then + if test "x$HAVE_XSHMFENCE" != "xyes"; then + AC_MSG_ERROR([xshmfence requested but not installed.]) + fi + AC_DEFINE(HAVE_XSHMFENCE, 1, [Have xshmfence support]) + REQUIRED_LIBS="$REQUIRED_LIBS $LIBXSHMFENCE" +fi +AM_CONDITIONAL(XSHMFENCE, [test "x$XSHMFENCE" = xyes]) -case "$DRI3,$HAVE_XSHMFENCE" in +case "$DRI3,$XSHMFENCE" in yes,yes | auto,yes) ;; yes,no) diff --git a/xorg-server/glamor/glamor_sync.c b/xorg-server/glamor/glamor_sync.c index d3d64a925..5e158c33a 100644 --- a/xorg-server/glamor/glamor_sync.c +++ b/xorg-server/glamor/glamor_sync.c @@ -53,7 +53,7 @@ glamor_sync_fence_set_triggered (SyncFence *fence) /* Flush pending rendering operations */ glamor_make_current(glamor); - glFinish(); + glFlush(); fence->funcs.SetTriggered = glamor_fence->set_triggered; fence->funcs.SetTriggered(fence); diff --git a/xorg-server/hw/xfree86/i2c/Makefile.am b/xorg-server/hw/xfree86/i2c/Makefile.am index c31159196..8bf795ded 100644 --- a/xorg-server/hw/xfree86/i2c/Makefile.am +++ b/xorg-server/hw/xfree86/i2c/Makefile.am @@ -1,43 +1,9 @@ noinst_LTLIBRARIES = libi2c.la -multimediadir = $(moduledir)/multimedia -multimedia_LTLIBRARIES = \ - bt829_drv.la \ - fi1236_drv.la \ - msp3430_drv.la \ - tda8425_drv.la \ - tda9850_drv.la \ - tda9885_drv.la \ - uda1380_drv.la - libi2c_la_SOURCES = xf86i2c.c AM_CPPFLAGS = $(XORG_INCS) AM_CFLAGS = $(DIX_CFLAGS) $(XORG_CFLAGS) -sdk_HEADERS = xf86i2c.h bt829.h fi1236.h msp3430.h tda8425.h tda9850.h tda9885.h uda1380.h i2c_def.h - -# -# i2c drivers -# -bt829_drv_la_LDFLAGS = -module -avoid-version $(LD_NO_UNDEFINED_FLAG) -bt829_drv_la_SOURCES = bt829.c bt829.h bt829_module.c - -fi1236_drv_la_LDFLAGS = -module -avoid-version $(LD_NO_UNDEFINED_FLAG) -fi1236_drv_la_SOURCES = fi1236.c fi1236.h fi1236_module.c tda9885.c - -msp3430_drv_la_LDFLAGS = -module -avoid-version $(LD_NO_UNDEFINED_FLAG) -msp3430_drv_la_SOURCES = msp3430.c msp3430.h msp3430_module.c - -tda8425_drv_la_LDFLAGS = -module -avoid-version $(LD_NO_UNDEFINED_FLAG) -tda8425_drv_la_SOURCES = tda8425.c tda8425.h tda8425_module.c - -tda9850_drv_la_LDFLAGS = -module -avoid-version $(LD_NO_UNDEFINED_FLAG) -tda9850_drv_la_SOURCES = tda9850.c tda9850.h tda9850_module.c - -tda9885_drv_la_LDFLAGS = -module -avoid-version $(LD_NO_UNDEFINED_FLAG) -tda9885_drv_la_SOURCES = tda9885.c tda9885.h tda9885_module.c - -uda1380_drv_la_LDFLAGS = -module -avoid-version $(LD_NO_UNDEFINED_FLAG) -uda1380_drv_la_SOURCES = uda1380.c uda1380.h uda1380_module.c +sdk_HEADERS = xf86i2c.h i2c_def.h diff --git a/xorg-server/hw/xfree86/i2c/bt829.c b/xorg-server/hw/xfree86/i2c/bt829.c deleted file mode 100644 index 991c26eab..000000000 --- a/xorg-server/hw/xfree86/i2c/bt829.c +++ /dev/null @@ -1,822 +0,0 @@ -/* TODO: clean up/fix CC code */ - -#ifdef HAVE_XORG_CONFIG_H -#include <xorg-config.h> -#endif - -#include <stdlib.h> -#include <string.h> -#include <stdio.h> - -#include "xf86.h" -#include "xf86i2c.h" -#include "bt829.h" -#include "i2c_def.h" - -/* Changing the following settings (especially VCROP) may */ -/* require modifying code that calls this driver. */ -#define HCROP 0 /* amount to crop from the left and right edges */ -#define VCROP 0 /* amount to crop from the top and bottom edges */ - -#define BTVERSION (bt->id>>4) - -#define H(X) ( ((X)>>8) & 0xFF ) -#define L(X) ( (X) & 0xFF ) - -#define LIMIT(X,A,B) (((X)<(A)) ? (A) : ((X)>(B)) ? (B) : (X) ) - -/* Bt829 family chip ID's */ -#define BT815 0x02 -#define BT817 0x06 -#define BT819 0x07 -#define BT827 0x0C -#define BT829 0x0E - -/* Bt829 registers */ -#define STATUS 0x00 /* Device Status */ -#define IFORM 0x01 /* Input Format */ -#define TDEC 0x02 /* Temporal Decimation */ -#define CROP 0x03 /* MSB Cropping */ -#define VDELAY_LO 0x04 /* Vertical Delay */ -#define VACTIVE_LO 0x05 /* Vertical Active */ -#define HDELAY_LO 0x06 /* Horizontal Delay */ -#define HACTIVE_LO 0x07 /* Horizontal Active */ -#define HSCALE_HI 0x08 /* Horizontal Scaling */ -#define HSCALE_LO 0x09 /* Horizontal Scaling */ -#define BRIGHT 0x0A /* Brightness Control */ -#define CONTROL 0x0B /* Miscellaneous Control */ -#define CONTRAST_LO 0x0C /* Luma Gain (Contrast) */ -#define SAT_U_LO 0x0D /* Chroma (U) Gain (Saturation) */ -#define SAT_V_LO 0x0E /* Chroma (V) Gain (Saturation) */ -#define HUE 0x0F /* Hue Control */ -#define SCLOOP 0x10 /* SC Loop Control */ -#define WC_UP 0x11 /* White Crush Up Count */ -#define OFORM 0x12 /* Output Format */ -#define VSCALE_HI 0x13 /* Vertical Scaling */ -#define VSCALE_LO 0x14 /* Vertical Scaling */ -#define TEST 0x15 /* Test Control */ -#define VPOLE 0x16 /* Video Timing Polarity */ -#define IDCODE 0x17 /* ID Code */ -#define ADELAY 0x18 /* AGC Delay */ -#define BDELAY 0x19 /* Burst Gate Delay */ -#define ADC 0x1A /* ADC Interface */ -#define VTC 0x1B /* Video Timing Control */ -#define CC_STATUS 0x1C /* Extended Data Services/Closed Capt Status */ -#define CC_DATA 0x1D /* Extended Data Services/Closed Capt Data */ -#define WC_DN 0x1E /* White Crush Down Count */ -#define SRESET 0x1F /* Software Reset */ -#define P_IO 0x3F /* Programmable I/O */ - -static CARD8 -btread(BT829Ptr bt, CARD8 reg) -{ - CARD8 v; - - I2C_WriteRead(&(bt->d), ®, 1, &v, 1); - - return v; -} - -static void -btwrite(BT829Ptr bt, CARD8 reg, CARD8 val) -{ - CARD8 data[2]; - - data[0] = reg; - data[1] = val; - I2C_WriteRead(&(bt->d), data, 2, NULL, 0); -} - -/* - * Register access - */ -static void -btwrite_status(BT829Ptr bt) -{ /* STATUS */ - btwrite(bt, STATUS, 0x00); /* clear */ -} - -static void -btwrite_iform(BT829Ptr bt) -{ /* IFORM */ - int xtsel; - - switch (bt->format) { - case BT829_NTSC: - case BT829_NTSC_JAPAN: - case BT829_PAL_M: - case BT829_PAL_N_COMB: /* gatos says xtsel = 2 */ - xtsel = 1; - break; - case BT829_PAL: - case BT829_PAL_N: - case BT829_SECAM: - xtsel = 2; - break; - default: /* shouldn't get here */ - xtsel = 3; /* hardware default */ - break; - } - - btwrite(bt, IFORM, (bt->mux << 5) | (xtsel << 3) | bt->format); -} - -static void -btwrite_tdec(BT829Ptr bt) -{ /* TDEC */ - /* use default */ -} - -static void -btwrite_crop(BT829Ptr bt) -{ /* CROP */ - btwrite(bt, CROP, (H(bt->vdelay) << 6) | (H(bt->vactive) << 4) | - (H(bt->hdelay) << 2) | H(bt->width)); -} - -static void -btwrite_vdelay_lo(BT829Ptr bt) -{ /* VDELAY_LO */ - btwrite(bt, VDELAY_LO, L(bt->vdelay)); -} - -static void -btwrite_vactive_lo(BT829Ptr bt) -{ /* VACTIVE_LO */ - btwrite(bt, VACTIVE_LO, L(bt->vactive)); -} - -static void -btwrite_hdelay_lo(BT829Ptr bt) -{ /* HDELAY_LO */ - btwrite(bt, HDELAY_LO, L(bt->hdelay)); -} - -static void -btwrite_hactive_lo(BT829Ptr bt) -{ /* HACTIVE_LO */ - btwrite(bt, HACTIVE_LO, L(bt->width)); -} - -static void -btwrite_hscale_hi(BT829Ptr bt) -{ /* HSCALE_HI */ - btwrite(bt, HSCALE_HI, H(bt->hscale)); -} - -static void -btwrite_hscale_lo(BT829Ptr bt) -{ /* HSCALE_LO */ - btwrite(bt, HSCALE_LO, L(bt->hscale)); -} - -static void -btwrite_bright(BT829Ptr bt) -{ /* BRIGHT */ - btwrite(bt, BRIGHT, bt->brightness); -} - -static void -btwrite_control(BT829Ptr bt) -{ /* CONTROL */ - int ldec; - - /* The data sheet says ldec should always be 0 for SECAM */ - /* but the picture quality is better with ldec = 1 */ - ldec = (bt->width > 360); /* gatos says 384 */ - - btwrite(bt, CONTROL, ((bt->mux == bt->svideo_mux) ? 0xC0 : 0x00) | /* LNOTCH and COMP */ - (ldec << 5) | (H(bt->contrast) << 2) | (H(bt->sat_u) << 1) | H(bt-> - sat_v)); -} - -static void -btwrite_contrast_lo(BT829Ptr bt) -{ /* CONTRAST_LO */ - btwrite(bt, CONTRAST_LO, L(bt->contrast)); -} - -static void -btwrite_sat_u_lo(BT829Ptr bt) -{ /* SAT_U_LO */ - btwrite(bt, SAT_U_LO, L(bt->sat_u)); -} - -static void -btwrite_sat_v_lo(BT829Ptr bt) -{ /* SAT_V_LO */ - btwrite(bt, SAT_V_LO, L(bt->sat_v)); -} - -static void -btwrite_hue(BT829Ptr bt) -{ /* HUE */ - btwrite(bt, HUE, bt->hue); -} - -static void -btwrite_scloop(BT829Ptr bt) -{ /* SCLOOP */ - if (BTVERSION >= BT827) { - btwrite(bt, SCLOOP, (bt->format == BT829_SECAM) ? 0x10 : 0x00 /* QCIF or AUTO */ - ); - } -} - -static void -btwrite_wc_up(BT829Ptr bt) -{ /* WC_UP */ - if (BTVERSION >= BT827) { - /* use default */ - } -} - -static void -btwrite_oform(BT829Ptr bt) -{ /* OFORM */ - btwrite(bt, OFORM, (bt->code << 3) | (bt->len << 2) | 0x02 /* RANGE = 0, CORE = 0, VBI_FRAME = 0, OES = 2 (default) */ - ); -} - -static void -btwrite_vscale_hi(BT829Ptr bt) -{ /* VSCALE_HI */ - btwrite(bt, VSCALE_HI, H(bt->vscale) | 0x60 /* YCOMB = 0, COMB = 1, INT = 1 (default) */ - ); -} - -static void -btwrite_vscale_lo(BT829Ptr bt) -{ /* VSCALE_LO */ - btwrite(bt, VSCALE_LO, L(bt->vscale)); -} - -/* TEST should not be written to */ - -static void -btwrite_vpole(BT829Ptr bt) -{ /* VPOLE */ - btwrite(bt, VPOLE, (bt->out_en << 7)); -} - -/* IDCODE is read only */ - -static void -btwrite_adelay(BT829Ptr bt) -{ /* ADELAY */ - switch (bt->format) { - case BT829_NTSC: - case BT829_NTSC_JAPAN: - case BT829_PAL_M: - btwrite(bt, ADELAY, 104); - break; - case BT829_PAL: - case BT829_PAL_N: - case BT829_SECAM: - case BT829_PAL_N_COMB: - btwrite(bt, ADELAY, 127); - break; - default: /* shouldn't get here */ - btwrite(bt, ADELAY, 104); /* hardware default */ - break; - } -} - -static void -btwrite_bdelay(BT829Ptr bt) -{ /* BDELAY */ - switch (bt->format) { - case BT829_NTSC: - case BT829_NTSC_JAPAN: - case BT829_PAL_M: - btwrite(bt, BDELAY, 93); - break; - case BT829_PAL: - case BT829_PAL_N: - case BT829_PAL_N_COMB: - btwrite(bt, BDELAY, 114); - break; - case BT829_SECAM: - btwrite(bt, BDELAY, 160); - break; - default: /* shouldn't get here */ - btwrite(bt, BDELAY, 93); /* hardware default */ - break; - } -} - -static void -btwrite_adc(BT829Ptr bt) -{ /* ADC */ - btwrite(bt, ADC, bt->mux == bt->svideo_mux ? 0x80 : 0x82); /* CSLEEP = 0 or 1 */ -} - -static void -btwrite_vtc(BT829Ptr bt) -{ /* VTC */ - int vfilt = 0; /* hardware default */ - - if (BTVERSION > BT827) { /* gatos says >= BT827 */ - switch (bt->format) { - case BT829_NTSC: - case BT829_NTSC_JAPAN: - case BT829_PAL_M: - case BT829_PAL_N_COMB: /* gatos groups with BT829_PAL */ - if (bt->width <= 360) - vfilt = 1; /* gatos says <= 240 */ - if (bt->width <= 180) - vfilt = 2; /* gatos says <= 120 */ - if (bt->width <= 90) - vfilt = 3; /* gatos says <= 60 */ - break; - case BT829_PAL: - case BT829_PAL_N: - case BT829_SECAM: - if (bt->width <= 384) - vfilt = 1; - if (bt->width <= 192) - vfilt = 2; - if (bt->width <= 96) - vfilt = 3; - break; - default: /* shouldn't get here */ - break; /* use hardware default */ - } - btwrite(bt, VTC, (bt->vbien << 4) | (bt->vbifmt << 3) | vfilt); - } -} - -static void -btwrite_cc_status(BT829Ptr bt) -{ /* CC_STATUS *//* FIXME: ATI specific */ - if (BTVERSION >= BT827) { - if (bt->ccmode == 0) - btwrite(bt, CC_STATUS, 0x00); - /* 0x40 is activate to set the CCVALID line. Not required yet */ - else - btwrite(bt, CC_STATUS, (bt->ccmode << 4) | 0x40); - } -} - -/* CC_DATA is read only */ - -static void -btwrite_wc_dn(BT829Ptr bt) -{ /* WC_DN */ - if (BTVERSION >= BT827) { - /* use default */ - } -} - -static void -bt_reset(BT829Ptr bt) -{ /* SRESET */ - btwrite(bt, SRESET, 0x0); /* Reset all registers */ -} - -static void -btwrite_p_io(BT829Ptr bt) -{ /* P_IO */ - if (BTVERSION >= BT827) { - btwrite(bt, P_IO, bt->p_io); - } -} - -/* - * Deal with dependencies - */ -static void -propagate_changes(BT829Ptr bt) -{ - CARD16 hdelay, unscaled_hdelay, vdelay, hscale, vscale; - int htotal, vactive; - - switch (bt->format) { - case BT829_NTSC: - case BT829_NTSC_JAPAN: - case BT829_PAL_M: - vdelay = 22; - htotal = 754; - vactive = 480; - unscaled_hdelay = 135; - break; - case BT829_PAL: - case BT829_PAL_N: - vdelay = (bt->tunertype == 5) ? 34 : 22; - htotal = 922; - vactive = 576; - unscaled_hdelay = 186; - break; - case BT829_SECAM: - vdelay = 34; - htotal = 922; - vactive = 576; - unscaled_hdelay = 186; - break; - case BT829_PAL_N_COMB: - vdelay = (bt->tunertype == 5) ? 34 : 22; /* windows says 22 */ - htotal = 754; /* gatos and windows say 922 */ - vactive = 576; - unscaled_hdelay = 135; /* gatos and windows say 186 */ - break; - default: /* shouldn't get here */ - vdelay = 22; /* hardware default */ - htotal = 754; - vactive = 480; /* hardware default */ - unscaled_hdelay = 135; - break; - } - - bt->htotal = htotal; /* Used for error checking in bt829_SetCaptSize */ - - hscale = 4096 * htotal / (bt->width + 2 * HCROP) - 4096; - hdelay = - (HCROP + (bt->width + 2 * HCROP) * unscaled_hdelay / htotal) & 0x3FE; - - vactive = vactive - 2 * VCROP; - vdelay = vdelay + VCROP; - vscale = (0x10000 - (512 * vactive / bt->height - 512)) & 0x1FFF; - - if ((hdelay != bt->hdelay) || (vdelay != bt->vdelay) || - (vactive != bt->vactive) || (hscale != bt->hscale) || - (vscale != bt->vscale)) { - bt->hdelay = hdelay; - bt->vdelay = vdelay; - bt->vactive = vactive; - bt->hscale = hscale; - bt->vscale = vscale; - btwrite_crop(bt); - btwrite_vdelay_lo(bt); - btwrite_vactive_lo(bt); - btwrite_hdelay_lo(bt); - btwrite_hscale_hi(bt); - btwrite_hscale_lo(bt); - btwrite_control(bt); - btwrite_vscale_hi(bt); - btwrite_vscale_lo(bt); - } -} - -static void -write_all(BT829Ptr bt) -{ - bt_reset(bt); - propagate_changes(bt); /* ensure consistency */ - btwrite_iform(bt); - btwrite_tdec(bt); - btwrite_crop(bt); - btwrite_vdelay_lo(bt); - btwrite_vactive_lo(bt); - btwrite_hdelay_lo(bt); - btwrite_hactive_lo(bt); - btwrite_hscale_hi(bt); - btwrite_hscale_lo(bt); - btwrite_bright(bt); - btwrite_control(bt); - btwrite_contrast_lo(bt); - btwrite_sat_u_lo(bt); - btwrite_sat_v_lo(bt); - btwrite_hue(bt); - btwrite_scloop(bt); - btwrite_wc_up(bt); - btwrite_oform(bt); - btwrite_vscale_hi(bt); - btwrite_vscale_lo(bt); - btwrite_vpole(bt); - btwrite_adelay(bt); - btwrite_bdelay(bt); - btwrite_adc(bt); - btwrite_vtc(bt); - /* btwrite_cc_status(bt); *//* FIXME: CC code needs cleaning */ - btwrite_wc_dn(bt); - btwrite_p_io(bt); -} - -/* - * Public functions - */ -BT829Ptr -bt829_Detect(I2CBusPtr b, I2CSlaveAddr addr) -{ - BT829Ptr bt; - I2CByte a; - char *devname; - - bt = calloc(1, sizeof(BT829Rec)); - if (bt == NULL) - return NULL; - bt->d.DevName = strdup("BT829 video decoder"); - bt->d.SlaveAddr = addr; - bt->d.pI2CBus = b; - bt->d.NextDev = NULL; - bt->d.StartTimeout = b->StartTimeout; - bt->d.BitTimeout = b->BitTimeout; - bt->d.AcknTimeout = b->AcknTimeout; - bt->d.ByteTimeout = b->ByteTimeout; - - if (!I2C_WriteRead(&(bt->d), NULL, 0, &a, 1)) { - free(bt); - return NULL; - } - - bt->id = btread(bt, IDCODE); - - free((void *) bt->d.DevName); - bt->d.DevName = devname = calloc(200, sizeof(char)); - switch (BTVERSION) { - case BT815: - sprintf(devname, "bt815a video decoder, revision %d", - bt->id & 0xf); - break; - case BT817: - sprintf(devname, "bt817a video decoder, revision %d", - bt->id & 0xf); - break; - case BT819: - sprintf(devname, "bt819a video decoder, revision %d", - bt->id & 0xf); - break; - case BT827: - sprintf(devname, "bt827a/b video decoder, revision %d", - bt->id & 0xf); - break; - case BT829: - sprintf(devname, "bt829a/b video decoder, revision %d", - bt->id & 0xf); - break; - default: - sprintf(devname, - "bt8xx/unknown video decoder version %d, revision %d", - bt->id >> 4, bt->id & 0xf); - break; - } - - /* set default parameters */ - if (!I2CDevInit(&(bt->d))) { - free(bt); - return NULL; - } - - bt->tunertype = 1; - - bt->brightness = 0; /* hardware default */ - bt->ccmode = 0; - bt->code = 0; /* hardware default */ - bt->contrast = 216; /* hardware default */ - bt->format = BT829_NTSC; - bt->height = 480; /* hardware default for vactive */ - bt->hue = 0; /* hardware default */ - bt->len = 1; /* hardware default */ - bt->mux = BT829_MUX0; /* hardware default */ - bt->out_en = 0; /* hardware default */ - bt->p_io = 0; /* hardware default */ - bt->sat_u = 254; /* hardware default */ - bt->sat_v = 180; /* hardware default */ - bt->vbien = 0; /* hardware default */ - bt->vbifmt = 0; /* hardware default */ - bt->width = 640; /* hardware default for hactive */ - - bt->hdelay = 120; /* hardware default */ - bt->hscale = 684; /* hardware default */ - bt->vactive = 480; /* hardware default */ - bt->vdelay = 22; /* hardware default */ - bt->vscale = 0; /* hardware default */ - - bt->htotal = 754; /* NTSC */ - bt->svideo_mux = 0; /* no s-video */ - - return bt; -} - -int -bt829_ATIInit(BT829Ptr bt) -{ - bt->code = 1; - bt->len = 0; - bt->vbien = 1; - bt->vbifmt = 1; - bt->svideo_mux = BT829_MUX1; - - write_all(bt); - - return 0; -} - -int -bt829_SetFormat(BT829Ptr bt, CARD8 format) -{ - if ((format < 1) || (format > 7)) - return -1; - if ((BTVERSION <= BT819) && (format != BT829_NTSC) && (format != BT829_PAL)) - return -1; - if (format == bt->format) - return 0; - bt->format = format; - propagate_changes(bt); - btwrite_iform(bt); - btwrite_scloop(bt); - btwrite_adelay(bt); - btwrite_bdelay(bt); - btwrite_vtc(bt); - return 0; -} - -int -bt829_SetMux(BT829Ptr bt, CARD8 mux) -{ - if ((mux < 1) || (mux > 3)) - return -1; - if (mux == bt->mux) - return 0; - bt->mux = mux; - /* propagate_changes(bt); *//* no dependencies */ - btwrite_iform(bt); - btwrite_control(bt); - btwrite_adc(bt); - return 0; -} - -void -bt829_SetBrightness(BT829Ptr bt, int brightness) -{ - brightness = LIMIT(brightness, -1000, 999); /* ensure -128 <= brightness <= 127 below */ - brightness = (128 * brightness) / 1000; - if (brightness == bt->brightness) - return; - bt->brightness = brightness; - /* propagate_changes(bt); *//* no dependencies */ - btwrite_bright(bt); -} - -void -bt829_SetContrast(BT829Ptr bt, int contrast) -{ - contrast = LIMIT(contrast, -1000, 1000); - contrast = (216 * (contrast + 1000)) / 1000; - if (contrast == bt->contrast) - return; - bt->contrast = contrast; - /* propagate_changes(bt); *//* no dependencies */ - btwrite_control(bt); - btwrite_contrast_lo(bt); -} - -void -bt829_SetSaturation(BT829Ptr bt, int saturation) -{ - CARD16 sat_u, sat_v; - - saturation = LIMIT(saturation, -1000, 1000); - sat_u = (254 * (saturation + 1000)) / 1000; - sat_v = (180 * (saturation + 1000)) / 1000; - if ((sat_u == bt->sat_u) && (sat_v == bt->sat_v)) - return; - bt->sat_u = sat_u; - bt->sat_v = sat_v; - /* propagate_changes(bt); *//* no dependencies */ - btwrite_control(bt); - btwrite_sat_u_lo(bt); - btwrite_sat_v_lo(bt); -} - -void -bt829_SetTint(BT829Ptr bt, int hue) -{ - hue = LIMIT(hue, -1000, 999); /* ensure -128 <= hue <= 127 below */ - hue = (128 * hue) / 1000; - if (hue == bt->hue) - return; - bt->hue = hue; - /* propagate_changes(bt); *//* no dependencies */ - btwrite_hue(bt); -} - -int -bt829_SetCaptSize(BT829Ptr bt, int width, int height) -{ - if ((width > bt->htotal - 2 * HCROP) || - (16 * width < bt->htotal - 32 * HCROP)) - return -1; - if ((height > bt->vactive) || (16 * height < bt->vactive)) - return -1; - if ((width == bt->width) && (height == bt->height)) - return 0; - bt->width = width; - bt->height = height; - propagate_changes(bt); - btwrite_crop(bt); - btwrite_hactive_lo(bt); - btwrite_control(bt); - btwrite_vtc(bt); - return 0; -} - -int -bt829_SetCC(BT829Ptr bt) -{ /* FIXME: should take ccmode as a parameter */ - if (BTVERSION < BT827) - return -1; /* can't do it */ - /* propagate_changes(bt); *//* no dependencies */ - btwrite_cc_status(bt); - /* we write to STATUS to reset the CCVALID flag */ - if (bt->ccmode != 0) - btwrite_status(bt); - return 0; -} - -void -bt829_SetOUT_EN(BT829Ptr bt, BOOL out_en) -{ - out_en = (out_en != 0); - if (out_en == bt->out_en) - return; - bt->out_en = out_en; - /* propagate_changes(bt); *//* no dependencies */ - btwrite_vpole(bt); -} - -void -bt829_SetP_IO(BT829Ptr bt, CARD8 p_io) -{ - if (p_io == bt->p_io) - return; - bt->p_io = p_io; - /* propagate_changes(bt); *//* no dependencies */ - btwrite_p_io(bt); -} - -#define BTREAD(R) btread(bt,(R)) - -#if 0 - -void -bt829_getCCdata(BT829Ptr bt, struct CCdata *data) -{ - CARD8 status; - - data->num_valid = 0; - /* wait for buffer to be half full (means 8/16 bytes) - * either 4 (one of CC/EDS) or 2 (both CC/EDS) frames */ - if (!(BTREAD(STATUS) & 0x04)) - return; /* could comment this line */ - for (; data->num_valid < CC_FIFO_SIZE; data->num_valid++) { - status = BTREAD(CC_STATUS); - if (!(status & 0x04)) - break; - data->data[data->num_valid] = BTREAD(CC_DATA) & 0x7f; - /* stripped high bit (parity) */ - data->status[data->num_valid] = (CCS_EDS * ((status & 0x02) >> 1)) | - (CCS_HIGH * (status & 0x01)) | - (CCS_OVER * ((status & 0x08) >> 3)) | - (CCS_PAR * ((status & 0x80) >> 7)); - } - btwrite(bt, STATUS, 0x00); /* Reset CCVALID status bit */ - return; -} - -#endif - -/* ------------------------------------------------------------------------ */ -/* Debug and report routines */ - -#define DUMPREG(REG) \ - xf86DrvMsg(bt->d.pI2CBus->scrnIndex,X_INFO," %-12s (0x%02X) = 0x%02X\n", \ - #REG,REG,BTREAD(REG)) - -/*static void bt829_dumpregs(BT829Ptr bt) -{ - DUMPREG(STATUS); - DUMPREG(IFORM); - DUMPREG(TDEC); - DUMPREG(CROP); - DUMPREG(VDELAY_LO); - DUMPREG(VACTIVE_LO); - DUMPREG(HDELAY_LO); - DUMPREG(HACTIVE_LO); - DUMPREG(HSCALE_HI); - DUMPREG(HSCALE_LO); - DUMPREG(BRIGHT); - DUMPREG(CONTROL); - DUMPREG(CONTRAST_LO); - DUMPREG(SAT_U_LO); - DUMPREG(SAT_V_LO); - DUMPREG(HUE); - if (BTVERSION >= BT827) { - DUMPREG(SCLOOP); - DUMPREG(WC_UP) ; } - DUMPREG(OFORM); - DUMPREG(VSCALE_HI); - DUMPREG(VSCALE_LO); - DUMPREG(TEST); - DUMPREG(VPOLE); - DUMPREG(IDCODE); - DUMPREG(ADELAY); - DUMPREG(BDELAY); - DUMPREG(ADC); - if (BTVERSION >= BT827) { - DUMPREG(VTC); - DUMPREG(CC_STATUS); - DUMPREG(CC_DATA); - DUMPREG(WC_DN); - DUMPREG(P_IO) ; } -}*/ diff --git a/xorg-server/hw/xfree86/i2c/bt829.h b/xorg-server/hw/xfree86/i2c/bt829.h deleted file mode 100644 index 2709bee50..000000000 --- a/xorg-server/hw/xfree86/i2c/bt829.h +++ /dev/null @@ -1,103 +0,0 @@ -#ifndef __BT829_H__ -#define __BT829_H__ - -#include "xf86i2c.h" - -typedef struct { - int tunertype; /* Must be set before init */ - /* Private variables */ - I2CDevRec d; - - CARD8 brightness; - CARD8 ccmode; - CARD8 code; - CARD16 contrast; - CARD8 format; - int height; - CARD8 hue; - CARD8 len; - CARD8 mux; - CARD8 out_en; - CARD8 p_io; - CARD16 sat_u; - CARD16 sat_v; - CARD8 vbien; - CARD8 vbifmt; - int width; - - CARD16 hdelay; - CARD16 hscale; - CARD16 vactive; - CARD16 vdelay; - CARD16 vscale; - - CARD16 htotal; - CARD8 id; - CARD8 svideo_mux; -} BT829Rec, *BT829Ptr; - -#define xf86_bt829_Detect bt829_Detect -extern _X_EXPORT BT829Ptr bt829_Detect(I2CBusPtr b, I2CSlaveAddr addr); - -/* ATI card specific initialization */ -#define BT829_ATI_ADDR_1 0x8A -#define BT829_ATI_ADDR_2 0x88 - -#define xf86_bt829_ATIInit bt829_ATIInit -extern _X_EXPORT int bt829_ATIInit(BT829Ptr bt); - -#define BT829_NTSC 1 /* NTSC-M */ -#define BT829_NTSC_JAPAN 2 /* NTSC-Japan */ -#define BT829_PAL 3 /* PAL-B,D,G,H,I */ -#define BT829_PAL_M 4 /* PAL-M */ -#define BT829_PAL_N 5 /* PAL-N */ -#define BT829_SECAM 6 /* SECAM */ -#define BT829_PAL_N_COMB 7 /* PAL-N combination */ - -#define xf86_bt829_SetFormat bt829_SetFormat -extern _X_EXPORT int bt829_SetFormat(BT829Ptr bt, CARD8 format); - -#define BT829_MUX2 1 /* ATI -> composite video */ -#define BT829_MUX0 2 /* ATI -> tv tuner */ -#define BT829_MUX1 3 /* ATI -> s-video */ - -#define xf86_bt829_SetMux bt829_SetMux -extern _X_EXPORT int bt829_SetMux(BT829Ptr bt, CARD8 mux); - -#define xf86_bt829_SetCaptSize bt829_SetCaptSize -extern _X_EXPORT int bt829_SetCaptSize(BT829Ptr bt, int width, int height); - -#define xf86_bt829_SetBrightness bt829_SetBrightness -extern _X_EXPORT void bt829_SetBrightness(BT829Ptr bt, int brightness); - -#define xf86_bt829_SetContrast bt829_SetContrast -extern _X_EXPORT void bt829_SetContrast(BT829Ptr bt, int contrast); - -#define xf86_bt829_SetSaturation bt829_SetSaturation -extern _X_EXPORT void bt829_SetSaturation(BT829Ptr bt, int saturation); - -#define xf86_bt829_SetTint bt829_SetTint -extern _X_EXPORT void bt829_SetTint(BT829Ptr bt, int hue); /* Hue */ - -#define xf86_bt829_SetOUT_EN bt829_SetOUT_EN -extern _X_EXPORT void bt829_SetOUT_EN(BT829Ptr bt, BOOL out_en); /* VPOLE register */ - -#define xf86_bt829_SetP_IO bt829_SetP_IO -extern _X_EXPORT void bt829_SetP_IO(BT829Ptr bt, CARD8 p_io); /* P_IO register */ - -extern _X_EXPORT int bt829_SetCC(BT829Ptr bt); - -#define BT829SymbolsList \ - "bt829_Detect", \ - "bt829_ATIInit", \ - "bt829_SetFormat", \ - "bt829_SetMux", \ - "bt829_SetBrightness", \ - "bt829_SetContrast", \ - "bt829_SetSaturation", \ - "bt829_SetTint", \ - "bt829_SetCaptSize", \ - "bt829_SetOUT_EN", \ - "bt829_SetP_IO" - -#endif diff --git a/xorg-server/hw/xfree86/i2c/bt829_module.c b/xorg-server/hw/xfree86/i2c/bt829_module.c deleted file mode 100644 index c8a6ac6d1..000000000 --- a/xorg-server/hw/xfree86/i2c/bt829_module.c +++ /dev/null @@ -1,20 +0,0 @@ -#ifdef HAVE_XORG_CONFIG_H -#include <xorg-config.h> -#endif - -#include "xf86Module.h" - -static XF86ModuleVersionInfo bt829VersRec = { - "bt829", - MODULEVENDORSTRING, - MODINFOSTRING1, - MODINFOSTRING2, - XORG_VERSION_CURRENT, - 1, 0, 0, - ABI_CLASS_VIDEODRV, /* This needs the video driver ABI */ - ABI_VIDEODRV_VERSION, - MOD_CLASS_NONE, - {0, 0, 0, 0} -}; - -_X_EXPORT XF86ModuleData bt829ModuleData = { &bt829VersRec, NULL, NULL }; diff --git a/xorg-server/hw/xfree86/i2c/fi1236.c b/xorg-server/hw/xfree86/i2c/fi1236.c deleted file mode 100644 index ebd14547d..000000000 --- a/xorg-server/hw/xfree86/i2c/fi1236.c +++ /dev/null @@ -1,686 +0,0 @@ -#ifdef HAVE_XORG_CONFIG_H -#include <xorg-config.h> -#endif - -#include <unistd.h> -#include <stdlib.h> -#include <string.h> -#include <math.h> - -#include "xf86.h" -#include "xf86i2c.h" -#include "fi1236.h" -#include "tda9885.h" -#include "i2c_def.h" - -#define NUM_TUNERS 8 - -const FI1236_parameters tuner_parms[NUM_TUNERS] = { - /* 0 - FI1236 */ - {733, 884, 12820, 2516, 7220, 0xA2, 0x94, 0x34, 0x8e}, - /* !!!based on documentation - it should be: - {733, 16*55.25, 16*801.25, 16*160, 16*454, 0xA0, 0x90, 0x30, 0x8e}, */ - - /* 1 - FI1216 */ - {623, 16 * 48.75, 16 * 855.25, 16 * 170, 16 * 450, 0xA0, 0x90, 0x30, 0x8e}, - /* 2 - TEMIC FN5AL */ - {623, 16 * 45.75, 16 * 855.25, 16 * 169, 16 * 454, 0xA0, 0x90, 0x30, 0x8e}, - /* 3 - MT2032.. */ - {733, 768, 13760, 0, 0, 0, 0, 0, 0}, - /* 4 - FI1246 */ - {623, 16 * 45.75, 16 * 855.25, 16 * 170, 16 * 450, 0xA0, 0x90, 0x30, 0x8e}, - /* 5 - FI1256 */ - {623, 16 * 49.75, 16 * 863.25, 16 * 170, 16 * 450, 0xA0, 0x90, 0x30, 0x8e}, - /* 6 - FI1236W */ - /*{ 733, 884, 12820, 2516, 7220, 0x1, 0x2, 0x4, 0x8e }, */ - {732, 16 * 55.25, 16 * 801.25, 16 * 160, 16 * 442, 0x1, 0x2, 0x4, 0x8e}, - /* 7 - FM1216ME */ - {623, 16 * 48.25, 16 * 863.25, 16 * 158.00, 16 * 442.00, 0x1, 0x2, 0x4, 0x8e} -}; - -FI1236Ptr -Detect_FI1236(I2CBusPtr b, I2CSlaveAddr addr) -{ - FI1236Ptr f; - I2CByte a; - - f = calloc(1, sizeof(FI1236Rec)); - if (f == NULL) - return NULL; - f->d.DevName = strdup("FI12xx Tuner"); - f->d.SlaveAddr = addr; - f->d.pI2CBus = b; - f->d.NextDev = NULL; - f->d.StartTimeout = b->StartTimeout; - f->d.BitTimeout = b->BitTimeout; - f->d.AcknTimeout = b->AcknTimeout; - f->d.ByteTimeout = b->ByteTimeout; - f->type = TUNER_TYPE_FI1236; - f->afc_timer_installed = FALSE; - f->last_afc_hint = TUNER_OFF; - f->video_if = 45.7812; - - if (!I2C_WriteRead(&(f->d), NULL, 0, &a, 1)) { - free(f); - return NULL; - } - FI1236_set_tuner_type(f, TUNER_TYPE_FI1236); - if (!I2CDevInit(&(f->d))) { - free(f); - return NULL; - } - return f; -} - -static void -MT2032_dump_parameters(FI1236Ptr f, MT2032_parameters * m) -{ - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "MT2032: input f_rf=%g f_if1=%g f_if2=%g f_ref=%g f_ifbw=%g f_step=%g\n", - m->f_rf, m->f_if1, m->f_if2, m->f_ref, m->f_ifbw, m->f_step); - - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "MT2032: computed f_lo1=%g f_lo2=%g LO1I=%d LO2I=%d SEL=%d STEP=%d NUM=%d\n", - m->f_lo1, m->f_lo2, m->LO1I, m->LO2I, m->SEL, m->STEP, m->NUM); -} - -static void -MT2032_getid(FI1236Ptr f) -{ - CARD8 out[4]; - CARD8 in; - - in = 0x11; - I2C_WriteRead(&(f->d), (I2CByte *) &in, 1, out, 4); - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "MT2032: Company code 0x%02x%02x, part code 0x%02x, revision code 0x%02x\n", - out[0], out[1], out[2], out[3]); - -} - -/* might be buggy */ -#if 0 -static void -MT2032_shutdown(FI1236Ptr f) -{ - CARD8 data[10]; - - data[0] = 0x00; /* start with register 0x00 */ - data[1] = 0x1A; - data[2] = 0x44; - data[3] = 0x20; - - I2C_WriteRead(&(f->d), (I2CByte *) data, 4, NULL, 0); - - data[0] = 0x05; /* now start with register 0x05 */ - data[1] = 0xD7; - data[2] = 0x14; - data[3] = 0x05; - I2C_WriteRead(&(f->d), (I2CByte *) data, 4, NULL, 0); - - data[0] = 0x0B; /* now start with register 0x05 */ - data[1] = 0x8F; - data[2] = 0x07; - data[3] = 0x43; - I2C_WriteRead(&(f->d), (I2CByte *) data, 4, NULL, 0); - - usleep(15000); -} -#endif - -static void MT2032_dump_status(FI1236Ptr f); - -static void -MT2032_init(FI1236Ptr f) -{ - CARD8 data[10]; - CARD8 value; - CARD8 xogc = 0x00; - - MT2032_getid(f); - - data[0] = 0x02; /* start with register 0x02 */ - data[1] = 0xFF; - data[2] = 0x0F; - data[3] = 0x1F; - - I2C_WriteRead(&(f->d), (I2CByte *) data, 4, NULL, 0); - - data[0] = 0x06; /* now start with register 0x06 */ - data[1] = 0xE4; - data[2] = 0x8F; - data[3] = 0xC3; - data[4] = 0x4E; - data[5] = 0xEC; - I2C_WriteRead(&(f->d), (I2CByte *) data, 6, NULL, 0); - - data[0] = 0x0d; /* now start with register 0x0d */ - data[1] = 0x32; - I2C_WriteRead(&(f->d), (I2CByte *) data, 2, NULL, 0); - - while (1) { - usleep(15000); /* wait 15 milliseconds */ - - data[0] = 0x0e; /* register number 7, status */ - value = 0xFF; - if (!I2C_WriteRead(&(f->d), (I2CByte *) data, 1, &value, 1)) - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "MT2032: failed to read XOK\n"); - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "MT2032: XOK=%d\n", value & 0x01); - if (value & 1) - break; - - data[0] = 0x07; - if (!I2C_WriteRead(&(f->d), (I2CByte *) data, 1, &value, 1)) - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "MT2032: failed to read XOGC\n"); - - xogc = value & 0x7; - if (xogc == 4) - break; /* XOGC has reached 4.. stop */ - xogc--; - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "MT2032: try XOGC=%d\n", xogc); - usleep(15000); - data[0] = 0x07; /* register number 7, control byte 2 */ - data[1] = 0x08 | xogc; - I2C_WriteRead(&(f->d), (I2CByte *) data, 2, NULL, 0); - } - f->xogc = xogc; - /* wait before continuing */ - usleep(15000); /* wait 50 milliseconds */ - MT2032_dump_status(f); -} - -static int -MT2032_no_spur_in_band(MT2032_parameters * m) -{ - int n_max, n1, n2; - double f_test; - - n_max = 5; - n1 = 1; - while (1) { - n2 = -n1; - f_test = n1 * (m->f_lo1 - m->f_lo2); - while (1) { - n2--; - f_test = f_test - m->f_lo2; - xf86DrvMsg(0, X_INFO, - "testing f_test=%g n1=%d n2=%d f_lo1=%g f_lo2=%g f_if2=%g\n", - f_test, n1, n2, m->f_lo1, m->f_lo2, m->f_if2); - xf86DrvMsg(0, X_INFO, "d_f=%g f_ifbw=%g\n", - fabs(fabs(f_test) - m->f_if2), m->f_ifbw); - if ((fabs(fabs(f_test) - m->f_if2) * 2.0) <= m->f_ifbw) - return 0; - if (n2 <= -n_max) - break; - /* this line in the manual is bogus. I say it is faster - and more correct to go over all harmonics.. */ -#if 0 - if (f_test < (m->f_lo2 - m->f_if2 - m->f_ifbw)) - break; -#endif - } - n1++; - if (n1 >= n_max) - return 1; - } - -} - -static void -MT2032_calculate_register_settings(MT2032_parameters * m, double f_rf, - double f_if1, double f_if2, double f_ref, - double f_ifbw, double f_step) -{ - int n; - - m->f_rf = f_rf; - m->f_if1 = f_if1; - m->f_if2 = f_if2; - m->f_ref = f_ref; - m->f_ifbw = f_ifbw; - m->f_step = f_step; - - m->f_lo1 = f_rf + f_if1; - m->LO1I = lrint(m->f_lo1 / f_ref); - m->f_lo1 = f_ref * m->LO1I; - - m->f_lo2 = m->f_lo1 - f_rf - f_if2; - - /* check for spurs */ - n = 1; - while (n < 3) { - if (MT2032_no_spur_in_band(m)) - break; - - if (m->f_lo1 < (f_rf + f_if1)) - m->LO1I += n; - else - m->LO1I -= n; - - m->f_lo1 = m->LO1I * f_ref; - m->f_lo2 = m->f_lo1 - f_rf - f_if2; - n++; - } - /* xf86DrvMsg(0, X_INFO, "MT2032: n=%d\n", n); */ - /* select VCO */ - - /* m->f_lo1>1100.0 */ - if (m->f_lo1 < 1370.0) - m->SEL = 4; - else if (m->f_lo1 < 1530.0) - m->SEL = 3; - else if (m->f_lo1 < 1720.0) - m->SEL = 2; - else if (m->f_lo1 < 1890.0) - m->SEL = 1; - else /* m->f_lo1 < 1958.0 */ - m->SEL = 0; - - /* calculate the rest of the registers */ - m->LO2I = floor(m->f_lo2 / f_ref); - m->STEP = floor(3780.0 * f_step / f_ref); - m->NUM = floor(3780.0 * (m->f_lo2 / f_ref - m->LO2I)); - m->NUM = m->STEP * lrint((1.0 * m->NUM) / (1.0 * m->STEP)); -} - -static int -MT2032_wait_for_lock(FI1236Ptr f) -{ - int n; - CARD8 data[10]; - CARD8 value; - - n = 12; - while (1) { - data[0] = 0x0e; /* register number 7, status */ - I2C_WriteRead(&(f->d), (I2CByte *) data, 1, &value, 1); - /* xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "MT2032: LO1LK=%d LO2LK=%d\n", - (value & 0x04)>>2, (value & 0x02)>>1); */ - if ((value & 6) == 6) - break; - usleep(1500); - n--; - if (n < 0) - break; - } - if (n < 0) { - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "MT2032: failed to set frequency\n"); - return 0; - } - return 1; -} - -static void -MT2032_implement_settings(FI1236Ptr f, MT2032_parameters * m) -{ - CARD8 data[10]; - CARD8 value; - - data[0] = 0x00; /* start with register 0x00 */ - data[1] = (m->LO1I >> 3) - 1; - data[2] = (m->SEL << 4) | (m->LO1I & 0x7); - data[3] = 0x86; - I2C_WriteRead(&(f->d), (I2CByte *) data, 4, NULL, 0); - - data[0] = 0x05; /* start with register 0x05 */ - data[1] = ((m->LO2I & 0x7) << 5) | ((m->LO2I >> 3) - 1); - if (m->f_rf < 400.0) - data[2] = 0xe4; - else - data[2] = 0xf4; - I2C_WriteRead(&(f->d), (I2CByte *) data, 3, NULL, 0); - - data[0] = 0x07; /* register number 7, control byte 2 */ - I2C_WriteRead(&(f->d), (I2CByte *) data, 1, &value, 1); - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "MT2032: using XOGC=%d\n", (value & 0x07)); - data[1] = 8 | (value & 0x7); - I2C_WriteRead(&(f->d), (I2CByte *) data, 2, NULL, 0); - - data[0] = 0x0b; /* start with register 0x0b */ - data[1] = m->NUM & 0xff; - data[2] = (1 << 7) | ((m->NUM >> 8) & 0x0f); - I2C_WriteRead(&(f->d), (I2CByte *) data, 3, NULL, 0); - - MT2032_wait_for_lock(f); -} - -static void -MT2032_optimize_VCO(FI1236Ptr f, MT2032_parameters * m) -{ - CARD8 data[10]; - CARD8 value; - CARD8 TAD1; - - data[0] = 0x0f; /* register number 7, status */ - I2C_WriteRead(&(f->d), (I2CByte *) data, 1, &value, 1); - TAD1 = value & 0x07; - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "MT2032: TAD1=%d SEL=%d\n", TAD1, m->SEL); - if (TAD1 < 2) - return; - if (TAD1 == 2) { - if (m->SEL == 0) - return; - m->SEL--; - } - else { - if (m->SEL >= 4) - return; - m->SEL++; - } - data[0] = 0x01; /* start with register 1 */ - data[1] = (m->SEL << 4) | (m->LO1I & 0x7); - I2C_WriteRead(&(f->d), (I2CByte *) data, 2, NULL, 0); - -} - -static int -FI1236_get_afc_hint(FI1236Ptr f) -{ - CARD8 out; - CARD8 AFC; - - if ((f->type == TUNER_TYPE_FM1216ME) || (f->type == TUNER_TYPE_FI1236W)) { - TDA9885Ptr t = (TDA9885Ptr) f->afc_source; - - if (t == NULL) - return TUNER_OFF; - - tda9885_getstatus(t); - tda9885_dumpstatus(t); - AFC = t->afc_status & 0x0f; - - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "AFC: FI1236_get_afc_hint: %i\n", AFC); - if (AFC == 0) - return TUNER_TUNED; - else if (AFC <= 0x07) - return TUNER_JUST_BELOW; - else if (AFC < 0x0f) - return TUNER_JUST_ABOVE; - else if (AFC == 0x0f) - return TUNER_TUNED; - } - else { - I2C_WriteRead(&(f->d), NULL, 0, &out, 1); - AFC = out & 0x7; - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "AFC: FI1236_get_afc_hint: %i\n", AFC); - if (AFC == 2) - return TUNER_TUNED; - if (AFC == 3) - return TUNER_JUST_BELOW; - if (AFC == 1) - return TUNER_JUST_ABOVE; - return TUNER_OFF; - } - return TUNER_OFF; -} - -static int -MT2032_get_afc_hint(FI1236Ptr f) -{ - CARD8 in; - CARD8 out[2]; - CARD8 AFC; - - in = 0x0e; - I2C_WriteRead(&(f->d), (I2CByte *) &in, 1, out, 2); - AFC = (out[0] >> 4) & 0x7; -#if 0 - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, "AFC=%d TAD1=%d TAD2=%d\n", - AFC, out[1] & 0x7, (out[1] >> 4) & 0x07); -#endif - if (AFC == 2) - return TUNER_TUNED; - if (AFC == 3) - return TUNER_JUST_BELOW; - if (AFC == 1) - return TUNER_JUST_ABOVE; - return TUNER_OFF; -} - -/* this function is for external use only */ -int -TUNER_get_afc_hint(FI1236Ptr f) -{ - if (f->afc_timer_installed) - return TUNER_STILL_TUNING; - return f->last_afc_hint; -} - -static void -MT2032_dump_status(FI1236Ptr f) -{ - CARD8 in; - CARD8 out[2]; - CARD8 AFC; - CARD8 LDONrb; - CARD8 LO1LK, LO2LK, XOK; - CARD8 TAD2, TAD1; - - in = 0x0e; - I2C_WriteRead(&(f->d), (I2CByte *) &in, 1, out, 2); - XOK = out[0] & 1; - LO1LK = (out[0] >> 2) & 1; - LO2LK = (out[0] >> 1) & 1; - LDONrb = (out[0] >> 3) & 1; - - AFC = (out[0] >> 4) & 0x7; - - TAD1 = (out[1] & 0x7); - TAD2 = (out[1] >> 4) & 0x7; - - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "MT2032: status: XOK=%d LO1LK=%d LO2LK=%d LDONrb=%d AFC=%d TAD1=%d TAD2=%d\n", - XOK, LO1LK, LO2LK, LDONrb, AFC, TAD1, TAD2); - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "MT2032: status: OSCILLATOR:%s PLL1:%s PLL2:%s\n", - XOK ? "ok" : "off", - LO1LK ? "locked" : "off", LO2LK ? "locked" : "off"); - -} - -static void -MT2032_tune(FI1236Ptr f, double freq, double step) -{ - MT2032_parameters m; - CARD8 data[10]; - int i; - - /* NTSC IF is 44mhz.. but 733/16=45.8125 and all TDAXXXX docs mention - 45.75, 39, 58.75 and 30. */ -#if 0 - MT2032_calculate_register_settings(&m, freq, 1090.0, 45.125, 5.25, 6.0, - step); - MT2032_calculate_register_settings(&m, freq, 1090.0, 45.74, 5.25, 6.0, - step); -#endif - MT2032_calculate_register_settings(&m, freq, 1090.0, f->video_if, 5.25, 3.0, - step); - MT2032_dump_parameters(f, &m); - MT2032_implement_settings(f, &m); - /* MT2032_dump_parameters(f, &m); */ - for (i = 0; i < 3; i++) { - MT2032_optimize_VCO(f, &m); - if (MT2032_wait_for_lock(f)) { - data[0] = 0x02; /* LO Gain control register 0x02 */ - data[1] = 0x20; - I2C_WriteRead(&(f->d), (I2CByte *) data, 2, NULL, 0); - return; - } - data[0] = 0x07; - data[1] = 0x88 | f->xogc; - I2C_WriteRead(&(f->d), (I2CByte *) data, 2, NULL, 0); - usleep(15000); - data[1] = 0x08 | f->xogc; - I2C_WriteRead(&(f->d), (I2CByte *) data, 2, NULL, 0); - } - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "MT2032: failed to set frequency\n"); -} - -void -FI1236_set_tuner_type(FI1236Ptr f, int type) -{ - f->type = type; - if (type >= NUM_TUNERS) - type = NUM_TUNERS - 1; - if (type < 0) - type = 0; - memcpy(&(f->parm), &(tuner_parms[type]), sizeof(FI1236_parameters)); - f->original_frequency = f->parm.min_freq; - f->afc_delta = 0; - if (type == TUNER_TYPE_MT2032) { - MT2032_init(f); - return; - } -} - -static CARD32 -AFC_TimerCallback(OsTimerPtr timer, CARD32 time, void *data) -{ - FI1236Ptr f = (FI1236Ptr) data; - - if (FI1236_AFC(f)) - return 150; - else { - f->afc_timer_installed = FALSE; - f->afc_count = 0; - return 0; - } -} - -void -FI1236_tune(FI1236Ptr f, CARD32 frequency) -{ - CARD16 divider; - CARD8 data; - - if (frequency < f->parm.min_freq) - frequency = f->parm.min_freq; - if (frequency > f->parm.max_freq) - frequency = f->parm.max_freq; - - divider = (f->parm.fcar + (CARD16) frequency) & 0x7fff; - f->tuner_data.div1 = (CARD8) ((divider >> 8) & 0x7f); - f->tuner_data.div2 = (CARD8) (divider & 0xff); - f->tuner_data.control = f->parm.control; - - if (frequency < f->parm.threshold1) - f->tuner_data.band = f->parm.band_low; - else if (frequency < f->parm.threshold2) - f->tuner_data.band = f->parm.band_mid; - else - f->tuner_data.band = f->parm.band_high; - - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "Setting tuner band to %d\n", f->tuner_data.band); - - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "Setting tuner frequency to %d\n", (int) frequency); - - if ((f->type == TUNER_TYPE_FM1216ME) || (f->type == TUNER_TYPE_FI1236W)) { - f->tuner_data.aux = 0x20; - I2C_WriteRead(&(f->d), (I2CByte *) &(f->tuner_data), 5, NULL, 0); - I2C_WriteRead(&(f->d), NULL, 0, &data, 1); - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, "Tuner status %x\n", data); - } - else - I2C_WriteRead(&(f->d), (I2CByte *) &(f->tuner_data), 4, NULL, 0); -} - -void -TUNER_set_frequency(FI1236Ptr f, CARD32 frequency) -{ - if (frequency < f->parm.min_freq) - frequency = f->parm.min_freq; - if (frequency > f->parm.max_freq) - frequency = f->parm.max_freq; - - f->afc_delta = 0; - f->original_frequency = frequency; - - if (f->type == TUNER_TYPE_MT2032) - MT2032_tune(f, (1.0 * frequency) / 16.0, 0.0625); - else - FI1236_tune(f, frequency); - - if (!f->afc_timer_installed) { - f->afc_timer_installed = TRUE; -/* RegisterBlockAndWakeupHandlers(FI1236_BlockHandler, AFCWakeup, f); */ - TimerSet(NULL, 0, 300, AFC_TimerCallback, f); - } - -} - -int -FI1236_AFC(FI1236Ptr f) -{ -#if 0 - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "AFC: f=%p f->count=%d f->original_frequency=%d f->afc_delta=%d\n", - f, f->afc_count, f->original_frequency, f->afc_delta); -#endif - f->afc_count++; - if (f->type == TUNER_TYPE_MT2032) { - f->last_afc_hint = MT2032_get_afc_hint(f); - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "AFC: afc_hint=%d\n", f->last_afc_hint); - if (f->last_afc_hint == TUNER_TUNED) - return 0; - if (f->afc_count > 3) - f->last_afc_hint = TUNER_OFF; - if (f->last_afc_hint == TUNER_OFF) - f->afc_delta = 0; - else - f->afc_delta += f->last_afc_hint; - - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "AFC: Setting tuner frequency to %g\n", - (0.5 * (2 * f->original_frequency + f->afc_delta)) / 16.0); - MT2032_tune(f, - (1.0 * f->original_frequency + 0.5 * f->afc_delta) / 16.0, - 0.03125); - if (f->last_afc_hint == TUNER_OFF) - return 0; - return 1; /* call me again */ - } - else { - f->last_afc_hint = FI1236_get_afc_hint(f); - if (f->last_afc_hint == TUNER_TUNED) { - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, "AFC: TUNER_TUNNED\n"); - return 0; - } - if (f->afc_count > 3) - f->last_afc_hint = TUNER_OFF; - - if (f->last_afc_hint == TUNER_OFF) - f->afc_delta = 0; - else - f->afc_delta += f->last_afc_hint; - - xf86DrvMsg(f->d.pI2CBus->scrnIndex, X_INFO, - "AFC: Setting tuner frequency to %g\n", - (0.5 * (2 * f->original_frequency + f->afc_delta)) / 16.0); - FI1236_tune(f, f->original_frequency + f->afc_delta); - if (f->last_afc_hint == TUNER_OFF) - return 0; - return 1; /* call me again */ - } - return 0; /* done */ -} - -void -fi1236_dump_status(FI1236Ptr f) -{ - if (f->type == TUNER_TYPE_MT2032) - MT2032_dump_status(f); -} diff --git a/xorg-server/hw/xfree86/i2c/fi1236.h b/xorg-server/hw/xfree86/i2c/fi1236.h deleted file mode 100644 index 053089277..000000000 --- a/xorg-server/hw/xfree86/i2c/fi1236.h +++ /dev/null @@ -1,113 +0,0 @@ -#ifndef __FI1236_H__ -#define __FI1236_H__ - -#include "xf86i2c.h" - -/* why someone has defined NUM someplace else is beyoung me.. */ -#undef NUM - -typedef struct { - CARD32 fcar; /* 16 * fcar_Mhz */ - CARD32 min_freq; /* 16 * min_freq_Mhz */ - CARD32 max_freq; /* 16 * max_freq_Mhz */ - - CARD32 threshold1; /* 16 * Value_Mhz */ - CARD32 threshold2; /* 16 * Value_Mhz */ - - CARD8 band_low; - CARD8 band_mid; - CARD8 band_high; - CARD8 control; -} FI1236_parameters; - -typedef struct { - /* what we want */ - /* all frequencies are in Mhz */ - double f_rf; /* frequency to tune to */ - double f_if1; /* first intermediate frequency */ - double f_if2; /* second intermediate frequency */ - double f_ref; /* reference frequency */ - double f_ifbw; /* bandwidth */ - double f_step; /* step */ - - /* what we compute */ - double f_lo1; - double f_lo2; - int LO1I; - int LO2I; - int SEL; - int STEP; - int NUM; -} MT2032_parameters; - -typedef struct { - I2CDevRec d; - int type; - - void *afc_source; /* The AFC source may be another chip like TDA988x */ - - int afc_delta; - CARD32 original_frequency; - Bool afc_timer_installed; - int afc_count; - int last_afc_hint; - - double video_if; - FI1236_parameters parm; - int xogc; /* for MT2032 */ - - struct { - CARD8 div1; - CARD8 div2; - CARD8 control; - CARD8 band; - CARD8 aux; /* this is for MK3 tuners */ - } tuner_data; -} FI1236Rec, *FI1236Ptr; - -#define TUNER_TYPE_FI1236 0 -#define TUNER_TYPE_FI1216 1 -#define TUNER_TYPE_TEMIC_FN5AL 2 -#define TUNER_TYPE_MT2032 3 -#define TUNER_TYPE_FI1246 4 -#define TUNER_TYPE_FI1256 5 -#define TUNER_TYPE_FI1236W 6 -#define TUNER_TYPE_FM1216ME 7 - -#define FI1236_ADDR(a) ((a)->d.SlaveAddr) - -#define FI1236_ADDR_1 0xC6 -#define FI1236_ADDR_2 0xC0 - -#define TUNER_TUNED 0 -#define TUNER_JUST_BELOW 1 -#define TUNER_JUST_ABOVE -1 -#define TUNER_OFF 4 -#define TUNER_STILL_TUNING 5 - -void FI1236_tune(FI1236Ptr f, CARD32 frequency); - -#define FI1236SymbolsList \ - "Detect_FI1236", \ - "FI1236_set_tuner_type", \ - "TUNER_set_frequency" - -#define xf86_Detect_FI1236 Detect_FI1236 -extern _X_EXPORT FI1236Ptr Detect_FI1236(I2CBusPtr b, I2CSlaveAddr addr); - -#define xf86_FI1236_set_tuner_type FI1236_set_tuner_type -extern _X_EXPORT void FI1236_set_tuner_type(FI1236Ptr f, int type); - -#define xf86_TUNER_set_frequency TUNER_set_frequency -extern _X_EXPORT void TUNER_set_frequency(FI1236Ptr f, CARD32 frequency); - -#define xf86_FI1236_AFC FI1236_AFC -extern _X_EXPORT int FI1236_AFC(FI1236Ptr f); - -#define xf86_TUNER_get_afc_hint TUNER_get_afc_hint -extern _X_EXPORT int TUNER_get_afc_hint(FI1236Ptr f); - -#define xf86_fi1236_dump_status fi1236_dump_status -extern _X_EXPORT void fi1236_dump_status(FI1236Ptr f); - -#endif diff --git a/xorg-server/hw/xfree86/i2c/fi1236_module.c b/xorg-server/hw/xfree86/i2c/fi1236_module.c deleted file mode 100644 index 2f453d964..000000000 --- a/xorg-server/hw/xfree86/i2c/fi1236_module.c +++ /dev/null @@ -1,24 +0,0 @@ -#ifdef HAVE_XORG_CONFIG_H -#include <xorg-config.h> -#endif - -#include "xf86Module.h" - -static XF86ModuleVersionInfo fi1236VersRec = { - "fi1236", - MODULEVENDORSTRING, - MODINFOSTRING1, - MODINFOSTRING2, - XORG_VERSION_CURRENT, - 1, 0, 0, - ABI_CLASS_VIDEODRV, /* This needs the video driver ABI */ - ABI_VIDEODRV_VERSION, - MOD_CLASS_NONE, - {0, 0, 0, 0} -}; - -_X_EXPORT XF86ModuleData fi1236ModuleData = { - &fi1236VersRec, - NULL, - NULL -}; diff --git a/xorg-server/hw/xfree86/i2c/msp3430.c b/xorg-server/hw/xfree86/i2c/msp3430.c deleted file mode 100644 index a501489ee..000000000 --- a/xorg-server/hw/xfree86/i2c/msp3430.c +++ /dev/null @@ -1,779 +0,0 @@ -#ifdef HAVE_XORG_CONFIG_H -#include <xorg-config.h> -#endif - -#include <string.h> -#include <unistd.h> - -#include "xf86.h" -#include "xf86i2c.h" -#include "msp3430.h" -#include "i2c_def.h" - -#define CONTROL 0x00 -#define WR_DEM 0x10 -#define RD_DEM 0x11 -#define WR_DSP 0x12 -#define RD_DSP 0x13 - -void InitMSP34xxG(MSP3430Ptr m); -void InitMSP34x5D(MSP3430Ptr m); -void CheckModeMSP34x5D(MSP3430Ptr m); -static const char *MSP_getProductName(CARD16 product_id); -void mpause(int milliseconds); - -#define __MSPDEBUG__ 0 - -#if __MSPDEBUG__ > 3 - -void MSPBeep(MSP3430Ptr m, CARD8 freq); - -#define __MSPBEEP MSPBeep(m,0x14); - -#else - -#define __MSPBEEP -#endif - -static void -SetMSP3430Control(MSP3430Ptr m, CARD8 RegAddress, CARD8 RegValueHigh, - CARD8 RegValueLow) -{ - I2CByte data[3]; - - data[0] = RegAddress; - data[1] = RegValueHigh; - data[2] = RegValueLow; - - I2C_WriteRead(&(m->d), data, 3, NULL, 0); -} - -static void -SetMSP3430Data(MSP3430Ptr m, CARD8 RegAddress, CARD8 RegSubAddressHigh, - CARD8 RegSubAddressLow, CARD8 RegValueHigh, CARD8 RegValueLow) -{ - I2CByte data[5]; - -#ifdef MSP_DEBUG - if (!m->registers_present[RegSubAddressLow]) { - xf86DrvMsg(m->d.pI2CBus->scrnIndex, X_ERROR, - "Attempt to access non-existent register in MSP34xxX: 0x%02x 0x%02x 0x%02x <- 0x%02x 0x%02x\n", - RegAddress, RegSubAddressHigh, RegSubAddressLow, - RegValueHigh, RegValueLow); - } -#endif - - data[0] = RegAddress; - data[1] = RegSubAddressHigh; - data[2] = RegSubAddressLow; - data[3] = RegValueHigh; - data[4] = RegValueLow; - - I2C_WriteRead(&(m->d), data, 5, NULL, 0); -} - -static void -GetMSP3430Data(MSP3430Ptr m, CARD8 RegAddress, CARD8 RegSubAddressHigh, - CARD8 RegSubAddressLow, CARD8 *RegValueHigh, CARD8 *RegValueLow) -{ - I2CByte send[3]; - I2CByte receive[2]; - - send[0] = RegAddress; - send[1] = RegSubAddressHigh; - send[2] = RegSubAddressLow; - - I2C_WriteRead(&(m->d), send, 3, receive, 2); - - *RegValueHigh = receive[0]; - *RegValueLow = receive[1]; -} - -#if __MSPDEBUG__ > 2 -static void -MSP3430DumpStatus(MSP3430Ptr m) -{ - CARD8 status_hi, status_lo; - CARD8 subaddr, data[2]; - - GetMSP3430Data(m, RD_DEM, 0x02, 0x00, &status_hi, &status_lo); - xf86DrvMsg(m->d.pI2CBus->scrnIndex, X_INFO, - "MSP34xx: SAP(8)=%d mono/NICAM(7)=%d stereo=%d %s O_1=%d O_0=%d 2nd car=%d 1st car=%d\n", - status_hi & 1, (status_lo >> 7) & 1, (status_lo >> 6) & 1, - (status_lo >> 5) ? ((status_hi >> 1) & 1 ? "bad NICAM reception" - : "NICAM") : ((status_hi >> 1) & 1 ? "bogus" - : "ANALOG FM/AM"), - (status_lo >> 4) & 1, (status_lo >> 3) & 1, - !((status_lo >> 2) & 1), !((status_lo >> 1) & 1)); - - GetMSP3430Data(m, RD_DEM, 0x00, 0x7E, &status_hi, &status_lo); - xf86DrvMsg(m->d.pI2CBus->scrnIndex, X_INFO, - "MSP34xx: standard result=0x%02x%02x\n", status_hi, status_lo); - subaddr = 0x0; - I2C_WriteRead(&(m->d), &subaddr, 1, data, 2); - xf86DrvMsg(m->d.pI2CBus->scrnIndex, X_INFO, "MSP34xx: control=0x%02x%02x\n", - data[1], data[0]); -} -#endif - -/* wrapper */ -void -InitMSP3430(MSP3430Ptr m) -{ -#if __MSPDEBUG__ > 1 - xf86DrvMsg(m->d.pI2CBus->scrnIndex, X_INFO, - "InitMSP3430(m->connector=%d, m->standard=%d, m->chip_family=%d)\n", - m->connector, m->standard, m->chip_family); -#endif - switch (m->chip_family) { - case MSPFAMILY_34x0G: - InitMSP34xxG(m); - break; - case MSPFAMILY_34x5G: - InitMSP34xxG(m); - break; - case MSPFAMILY_34x5D: - InitMSP34x5D(m); - break; - } -} - -/*----------------------------------------------------------------- -| common functions for all MSP34xx chips -|----------------------------------------------------------------*/ - -MSP3430Ptr -DetectMSP3430(I2CBusPtr b, I2CSlaveAddr addr) -{ - MSP3430Ptr m; - I2CByte a; - CARD8 hardware_version, major_revision, product_code, rom_version; - Bool supported; - - m = calloc(1, sizeof(MSP3430Rec)); - if (m == NULL) - return NULL; - m->d.DevName = strdup("MSP34xx"); - m->d.SlaveAddr = addr; - m->d.pI2CBus = b; - m->d.NextDev = NULL; - m->d.StartTimeout = b->StartTimeout; - m->d.BitTimeout = b->BitTimeout; - m->d.AcknTimeout = b->AcknTimeout; - m->d.ByteTimeout = b->ByteTimeout; - - if (!I2C_WriteRead(&(m->d), NULL, 0, &a, 1)) { - free((void *) m->d.DevName); - free(m); - return NULL; - } - - m->standard = MSP3430_NTSC; - m->connector = MSP3430_CONNECTOR_1; - m->mode = MSPMODE_STEREO_A; /*stereo or chanel A if avail. */ - m->c_format = MSPFORMAT_UNKNOWN; - m->c_standard = MSPSTANDARD_UNKNOWN; - m->c_matrix = m->c_fmmatrix = m->c_source = 0; - m->volume = 0; - m->recheck = FALSE; - - GetMSP3430Data(m, RD_DSP, 0x00, 0x1E, &hardware_version, &major_revision); - GetMSP3430Data(m, RD_DSP, 0x00, 0x1F, &product_code, &rom_version); - m->hardware_version = hardware_version; - m->major_revision = major_revision; - m->product_code = product_code; - m->rom_version = rom_version; - - m->chip_id = ((major_revision << 8) | product_code); - - supported = FALSE; - switch (major_revision) { - case 4: /* 34xxD */ - switch (product_code) { - case 0x05: /* 3405D */ - case 0x0A: /* 3410D */ - case 0x0F: /* 3415D */ - m->chip_family = MSPFAMILY_34x5D; - m->recheck = TRUE; - supported = TRUE; - break; - default: - m->chip_family = MSPFAMILY_34x0D; - } - break; - case 7: /* 34xxG */ - switch (product_code) { - case 0x00: - case 0x0A: - case 0x1E: - case 0x28: - case 0x32: - m->chip_family = MSPFAMILY_34x0G; - supported = TRUE; - break; - case 0x0f: - case 0x19: - case 0x2d: - case 0x37: - case 0x41: - m->chip_family = MSPFAMILY_34x5G; - supported = TRUE; -#ifdef MSP_DEBUG - memset(m->registers_present, 0, 256); -#define A(num) m->registers_present[(num)]=1; -#define B(num1, num2) memset(&(m->registers_present[num1]), 1, num2-num1); - A(0x20) - A(0x30) - A(0x40) - A(0x00) - B(0x01, 0x08) - B(0x0B, 0x0E) - A(0x10) - B(0x12, 0x14) - A(0x16) - A(0x29) -#undef B -#undef A -#endif - break; - default: - m->chip_family = MSPFAMILY_UNKNOWN; - } - break; - default: - m->chip_family = MSPFAMILY_UNKNOWN; - } - - xf86DrvMsg(m->d.pI2CBus->scrnIndex, X_INFO, - "Found %s%s, rom version 0x%02x, chip_id=0x%04x\n", - MSP_getProductName(m->chip_id), - supported ? "" : " (unsupported)", rom_version, m->chip_id); - - if (!supported) { - free((void *) m->d.DevName); - free(m); - return NULL; - } - if (!I2CDevInit(&(m->d))) { - free((void *) m->d.DevName); - free(m); - return NULL; - } - - return m; -} - -void -ResetMSP3430(MSP3430Ptr m) -{ - /* Reset the MSP3430 */ - SetMSP3430Control(m, 0x00, 0x80, 0x00); - /* Set it back to normal operation */ - SetMSP3430Control(m, 0x00, 0x00, 0x00); - - m->c_format = MSPFORMAT_UNKNOWN; - m->c_standard = MSPSTANDARD_UNKNOWN; - m->c_matrix = m->c_fmmatrix = m->c_source = 0; - m->volume = 0; -} - -void -MSP3430SetVolume(MSP3430Ptr m, CARD8 value) -{ - CARD8 result; - -#if 0 - CARD8 old_volume; - - GetMSP3430Data(m, RD_DSP, 0x00, 0x00, &old_volume, &result); - xf86DrvMsg(m->d.pI2CBus->scrnIndex, X_INFO, "MSP3430 result 0x%02x\n", - result); -#endif - /* save an extra Get call */ - result = 0; - - SetMSP3430Data(m, WR_DSP, 0x00, 0x00, value, result); - - SetMSP3430Data(m, WR_DSP, 0x00, 0x07, value, 0); - m->volume = value; - -#if __MSPDEBUG__ > 2 - MSP3430DumpStatus(m); - __MSPBEEP GetMSP3430Data(m, RD_DSP, 0x00, 0x00, &old_volume, &result); - xf86DrvMsg(m->d.pI2CBus->scrnIndex, X_INFO, "MSP3430 volume 0x%02x\n", - value); -#endif -} - -void -MSP3430SetSAP(MSP3430Ptr m, int mode) -{ - xf86DrvMsg(m->d.pI2CBus->scrnIndex, X_INFO, - "Put actual code to change SAP here\n"); - - SetMSP3430Data(m, WR_DSP, 0x00, 0x08, mode & 0xff, 0x20); -} - -#if 0 -void -MSP3430SetSource(MSP3430Ptr m, CARD8 value) -{ - /* Write to DSP, register 0x0008, (loudspeaker channel source/matrix) */ - /* This sets the source to the TV tuner, for stereo operation */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x08, value, 0x20); -} -#endif - -static const char * -MSP_getProductName(CARD16 product_id) -{ - switch (product_id) { - case 0x0400: - return "MSP3400D"; - case 0x040a: - return "MSP3410D"; - case 0x0405: - return "MSP3405D"; - case 0x040f: - return "MSP3415D"; - case 0x0700: - return "MSP3400G"; - case 0x070a: - return "MSP3410G"; - case 0x071e: - return "MSP3430G"; - case 0x0728: - return "MSP3440G"; - case 0x0732: - return "MSP3450G"; - case 0x070f: - return "MSP3415G"; - case 0x0719: - return "MSP3425G"; - case 0x072d: - return "MSP3445G"; - case 0x0737: - return "MSP3455G"; - case 0x0741: - return "MSP3465G"; - } - return "MSP - unknown type"; -} - -#if __MSPDEBUG__ > 2 -/*puts beep in MSP output - freq = 0x01 - 16Hz ... 0x40 - 1kHz ... 0xff - 4kHz -*/ -void -MSPBeep(MSP3430Ptr m, CARD8 freq) -{ - SetMSP3430Data(m, WR_DSP, 0x00, freq, 0x7f, 0x40); - mpause(100); - SetMSP3430Data(m, WR_DSP, 0x00, 0x14, 0x00, 0x00); -} -#endif - -void -mpause(int milliseconds) -{ - int i, m; - - m = milliseconds / 20; - for (i = 0; i < m; i++) - usleep(20000); -} - -/*----------------------------------------------------------------- -| specific functions for all MSP34xxG chips -|----------------------------------------------------------------*/ - -void -InitMSP34xxG(MSP3430Ptr m) -{ - -#if __MSPDEBUG__ > 1 - xf86DrvMsg(m->d.pI2CBus->scrnIndex, X_INFO, - "InitMSP34xxG(m->connector=%d, m->standard=%d, m->chip_family=%d)\n", - m->connector, m->standard, m->chip_family); -#endif - /* Reset MSP3430 */ - SetMSP3430Control(m, 0x00, 0x80, 0x00); - /* Set it back to normal operation */ - SetMSP3430Control(m, 0x00, 0x00, 0x00); - - /*set MODUS register */ - /* bits: 0 - automatic sound detection */ - /* 1 - enable STATUS change */ - /* 12 - detect 6.5 Mhz carrier as D/K1, D/K2 or D/K NICAM (does not seem to work ) */ - /* 13 - detect 4.5 Mhz carrier as BTSC */ - if ((m->standard & 0xff) == MSP3430_PAL) { - SetMSP3430Data(m, WR_DEM, 0x00, 0x30, 0x30, 0x03 | 0x08); /* make O_ pins tristate */ - /* PAL standard */ - SetMSP3430Data(m, WR_DEM, 0x00, 0x20, 0x00, 0x01); /* possibly wrong */ - } - else { - SetMSP3430Data(m, WR_DEM, 0x00, 0x30, 0x20, 0x03 | 0x08); - /* standard selection is M-BTSC-Stereo */ - SetMSP3430Data(m, WR_DEM, 0x00, 0x20, 0x00, 0x20); - } - - switch (m->connector) { - case MSP3430_CONNECTOR_1: - SetMSP3430Data(m, WR_DSP, 0x00, 0x08, 0x03, 0x20); - break; - case MSP3430_CONNECTOR_2: - /* this has not been checked yet.. could be bogus */ - /* SCART Input Prescale: 0 dB gain */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x0d, 0x19, 0x00); - SetMSP3430Data(m, WR_DSP, 0x00, 0x08, 0x02, 0x20); - break; - case MSP3430_CONNECTOR_3: - default: - /* SCART Input Prescale: 0 dB gain */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x0d, 0x19, 0x00); - - SetMSP3430Data(m, WR_DSP, 0x00, 0x08, 0x02, 0x20); - break; - } - - switch (m->standard) { - case MSP3430_PAL: - SetMSP3430Data(m, WR_DSP, 0x00, 0x0e, 0x24, 0x03); - SetMSP3430Data(m, WR_DSP, 0x00, 0x10, 0x00, 0x5a); - SetMSP3430Data(m, WR_DEM, 0x00, 0x20, 0x00, 0x03); - /* Set volume to FAST_MUTE. */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x00, 0xFF, 0x00); - break; - case MSP3430_PAL_DK1: - SetMSP3430Data(m, WR_DSP, 0x00, 0x0e, 0x24, 0x03); - SetMSP3430Data(m, WR_DSP, 0x00, 0x10, 0x00, 0x5a); - SetMSP3430Data(m, WR_DEM, 0x00, 0x20, 0x00, 0x04); - /* Set volume to FAST_MUTE. */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x00, 0xFF, 0x00); - break; - case MSP3430_SECAM: /* is this right ? */ - case MSP3430_NTSC: - /* Write to DSP, register 0x000E, (prescale FM/FM matrix) */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x0e, 0x24, 0x03); - - /* Set volume to FAST_MUTE. */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x00, 0xFF, 0x00); - break; - } - -} - -/*----------------------------------------------------------------- -| specific functions for all MSP34x5D chips -|----------------------------------------------------------------*/ - -void -InitMSP34x5D(MSP3430Ptr m) -{ - int count; - CARD8 high, low; - CARD16 result, standard; - CARD16 peak; - - if (m->c_format == MSPFORMAT_UNKNOWN) - ResetMSP3430(m); - else { - /*mute volume */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x00, 0x00, 0x00); - } - - switch (m->connector) { - case MSP3430_CONNECTOR_2: - case MSP3430_CONNECTOR_3: - if (m->c_format != MSPFORMAT_SCART) { - /* SCART Input Prescale: 0 dB gain */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x0d, 0x19, 0x00); - /* this has not been checked yet.. could be bogus */ - m->c_format = MSPFORMAT_SCART; /*stereo */ - } - break; - case MSP3430_CONNECTOR_1: - default: - - switch (m->standard & 0x00ff) { - case MSP3430_PAL: - switch (m->standard) { - case MSP3430_PAL_DK1: - standard = MSPSTANDARD_FM_DK1; - break; -/* case MSP3430_PAL_DK2: - standard=MSPSTANDARD_FM_DK2; - break; - case MSP3430_PAL_BG: - may be FM stereo (Germany) or FM NICAM (Scandinavia,spain) - standard=MSPSTANDARD_AUTO; - break; -*/ - default: - standard = MSPSTANDARD_AUTO; - } - break; - case MSP3430_SECAM: - standard = MSPSTANDARD_AUTO; - case MSP3430_NTSC: - /* Only MSP34x5 supported format - Korean NTSC-M */ - standard = MSPSTANDARD_FM_M; - default: - standard = MSPSTANDARD_AUTO; - } - - /*no NICAM support in MSP3410D - force to autodetect */ - if ((m->chip_id == 0x405) && (standard >= MSPSTANDARD_NICAM_BG)) - standard = MSPSTANDARD_AUTO; - - if (m->c_standard != standard) { - - SetMSP3430Data(m, WR_DEM, 0x00, 0x20, standard >> 8, - standard & 0xFF); - if (standard == MSPSTANDARD_AUTO) { - count = 50; /* time shouldn't exceed 1s, just in case */ - do { - usleep(20000); - GetMSP3430Data(m, RD_DEM, 0x00, 0x7e, &high, &low); - result = (high << 8) | low; - --count; - } while (result > 0x07ff && count > 0); - - if ((result > MSPSTANDARD_AUTO)) - standard = result; - else - standard = MSPSTANDARD_UNKNOWN; -#if __MSPDEBUG__ > 1 - xf86DrvMsg(m->d.pI2CBus->scrnIndex, X_INFO, - "Detected audio standard: %d\n", result); -#endif - /* result = MSPSTANDARD_NICAM_L can be one of: - SECAM_L - MSPSTANDARD_NICAM_L - D/K1 - MSPSTANDARD_FM_DK1 - D/K2 - MSPSTANDARD_FM_DK2 - D/K-NICAM - MSPSTANDARD_NICAM_DK */ - if (standard == MSPSTANDARD_NICAM_L) { - if ((m->standard & 0x00ff) == MSP3430_PAL) { - /* force PAL D/K */ - standard = MSPSTANDARD_FM_DK1; - SetMSP3430Data(m, WR_DEM, 0x00, 0x20, standard >> 8, - standard & 0xFF); -#if __MSPDEBUG__ > 1 - xf86DrvMsg(m->d.pI2CBus->scrnIndex, X_INFO, - "Detected 6.5MHz carrier - forced to D/K1 !!!\n"); -#endif - } - } - } - m->c_standard = standard; - } /*end - standard changed */ - else { - if (standard < MSPSTANDARD_NICAM_BG) { - /* get old value of ident. mode register */ - GetMSP3430Data(m, RD_DSP, 0x00, 0x15, &high, &low); - /* reset Ident-Filter */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x14, 0x00, 0x3F); - /* put back old value to ident. mode register */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x14, 0x00, low); - } - } - - if (standard <= MSPSTANDARD_AUTO) { - m->c_format = MSPFORMAT_1xFM; - } - else if (standard < MSPSTANDARD_NICAM_BG) { - /* set FM prescale */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x0e, 0x30, 0); - /* set FM deemphasis */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x0f, - ((standard == MSPSTANDARD_FM_M) ? 0 : 1), 0); - - /* check if FM2 carrier is present */ - /*turn off FM DC Notch */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x17, 0x00, 0x3f); - /*matrix source for Quasi-Peak Detector - stereo: ch2->L ch1->R */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x0c, 0x00, 0x20); - - mpause(250); - GetMSP3430Data(m, RD_DSP, 0x00, 0x1A, &high, &low); - peak = (high << 8) | low; -#if __MSPDEBUG__ > 1 - xf86DrvMsg(m->d.pI2CBus->scrnIndex, X_INFO, - "Second carrier Quasi-Peak detection: %d\n", peak); -#endif - /*turn on FM DC Notch */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x17, 0x00, 0x00); - - if (peak < 5) { - /* if second carrier not detected - only mono from first carrier */ - m->c_format = MSPFORMAT_1xFM; - } - else { - m->c_format = MSPFORMAT_2xFM; - /*start of FM identification process - FM_WAIT - wait at least 0.5s - used 1s - gives beter resolution */ - mpause(1000); - } - } - else { - if (standard == MSPSTANDARD_NICAM_L) { - m->c_format = MSPFORMAT_NICAM_AM; - /* set AM prescale */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x0e, 0x7C, 0); - } - else { - m->c_format = MSPFORMAT_NICAM_FM; - /* set FM prescale */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x0e, 0x30, 0); - } - /* set FM deemphasis */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x0f, 0x00, 0); - /* set NICAM prescale to 0dB */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x10, 0x20, 0); - } - - break; - } /*end - case conector */ - - CheckModeMSP34x5D(m); - - /* Set volume to FAST_MUTE. */ - /*SetMSP3430Data(m, WR_DSP, 0x00, 0x00, 0xFF, 0x00); */ - /*set volume */ - MSP3430SetVolume(m, m->volume); - -__MSPBEEP} /* EnableMSP34x5D ()... */ - -void -CheckModeMSP34x5D(MSP3430Ptr m) -{ - const char stereo_on = 25; - const char stereo_off = 20; - const char dual_on = -stereo_on; - const char dual_off = -stereo_off; - char detect; - CARD8 matrix, fmmatrix, source, high, low; - - fmmatrix = 0; /*no matrix */ - source = 0; - /*FM*/ switch (m->c_format) { - case MSPFORMAT_NICAM_FM: - case MSPFORMAT_NICAM_AM: - case MSPFORMAT_SCART: - source = ((m->c_format == MSPFORMAT_SCART) ? 2 : 1); - switch (m->mode) { - case MSPMODE_MONO: - matrix = 0x30; - /*MONO*/ break; - case MSPMODE_A: - matrix = 0x00; - /*A*/ break; - case MSPMODE_B: - matrix = 0x10; - /*B*/ break; - default: - matrix = 0x20; - /*STEREO*/ break; - } - break; - default: - case MSPFORMAT_1xFM: - matrix = 0x00; - /*A*/ break; - case MSPFORMAT_2xFM: - switch (m->mode) { - case MSPMODE_MONO: - matrix = 0x30; - /*MONO*/ break; - case MSPMODE_STEREO: - matrix = 0x20; - /*STEREO*/ fmmatrix = ((m->c_standard == MSPSTANDARD_FM_M) ? 2 : 1); - break; - case MSPMODE_AB: - matrix = 0x20; - /*STEREO*/ break; - case MSPMODE_A: - matrix = 0x00; - /*A*/ break; - case MSPMODE_B: - matrix = 0x10; - /*B*/ break; - default: - /*FM_IDENT_CHECK */ - GetMSP3430Data(m, RD_DSP, 0x00, 0x18, &high, &low); - detect = (char) high; -#if __MSPDEBUG__ > 1 - xf86DrvMsg(m->d.pI2CBus->scrnIndex, X_INFO, - "Stereo Detection Register: %d\n", detect); -#endif - if (detect >= - ((m->c_mode == MSPMODE_STEREO) ? stereo_off : stereo_on)) { - m->c_mode = MSPMODE_STEREO; - matrix = 0x20; - /*STEREO*/ - fmmatrix = ((m->c_standard == MSPSTANDARD_FM_M) ? 2 : 1); - } - else if (detect <= ((m->c_mode == MSPMODE_AB) ? dual_off : dual_on)) { - m->c_mode = MSPMODE_AB; - switch (m->mode) { - case MSPMODE_STEREO_AB: - matrix = 0x20; - break; - case MSPMODE_STEREO_B: - matrix = 0x10; - break; - default: - case MSPMODE_A: - matrix = 0x00; - break; - } - } - else { - m->c_mode = MSPMODE_MONO; - matrix = 0x30; - /*MONO*/} - break; - } /* end - case mode */ - break; - } - - if (m->c_fmmatrix != fmmatrix) { - GetMSP3430Data(m, RD_DSP, 0x00, 0x0e, &high, &low); - SetMSP3430Data(m, WR_DSP, 0x00, 0x0e, high, fmmatrix); - m->c_fmmatrix = fmmatrix; - } - - if ((m->c_matrix != matrix) || (m->c_source != source)) { - /*set chanel source and matrix for loudspeaker */ - SetMSP3430Data(m, WR_DSP, 0x00, 0x08, source, matrix); - - m->c_matrix = matrix; - m->c_source = source; - } - - if (((m->c_format) & 0xF0) == MSPFORMAT_NICAM) - SetMSP3430Data(m, WR_DEM, 0x00, 0x21, 0, 1); - -#if __MSPDEBUG__ > 0 - char *msg; - - switch (matrix) { - case 0x30: - /*MONO*/ msg = "MONO"; - break; - case 0x00: - /*LEFT*/ msg = "MONO/CHANNEL_1"; - break; - case 0x10: - /*RIGHT*/ msg = "MONO/CHANNEL_2"; - break; - case 0x20: - /*LEFT*/ msg = "STEREO"; - break; - default: - msg = "unknown"; - break; - } - xf86DrvMsg(m->d.pI2CBus->scrnIndex, X_INFO, "Audio mode set to: %s\n", msg); -#endif -} diff --git a/xorg-server/hw/xfree86/i2c/msp3430.h b/xorg-server/hw/xfree86/i2c/msp3430.h deleted file mode 100644 index ef66e1ed8..000000000 --- a/xorg-server/hw/xfree86/i2c/msp3430.h +++ /dev/null @@ -1,116 +0,0 @@ -#ifndef __MSP3430_H__ -#define __MSP3430_H__ - -#include "xf86i2c.h" - -typedef struct { - I2CDevRec d; - - int standard; - int connector; - int mode; - - CARD8 hardware_version, major_revision, product_code, rom_version; -#ifdef MSP_DEBUG - CARD8 registers_present[256]; -#endif - - CARD16 chip_id; - CARD8 chip_family; - Bool recheck; /*reinitialization needed after channel change */ - CARD8 c_format; /*current state of audio format */ - CARD16 c_standard; /*current state of standard register */ - CARD8 c_source; /*current state of source register */ - CARD8 c_matrix; /*current state of matrix register */ - CARD8 c_fmmatrix; /*current state of fmmatrix register */ - int c_mode; /* current state of mode for autoswitchimg */ - CARD8 volume; -} MSP3430Rec, *MSP3430Ptr; - -#define MSP3430_ADDR_1 0x80 -#define MSP3430_ADDR_2 0x84 -#define MSP3430_ADDR_3 0x88 - -#define MSP3430_PAL 1 -#define MSP3430_NTSC 2 -#define MSP3430_PAL_DK1 (0x100 | MSP3430_PAL) -#define MSP3430_SECAM 3 - -#define MSP3430_CONNECTOR_1 1 /* tuner on AIW cards */ -#define MSP3430_CONNECTOR_2 2 /* SVideo on AIW cards */ -#define MSP3430_CONNECTOR_3 3 /* composite on AIW cards */ - -#define MSP3430_ADDR(a) ((a)->d.SlaveAddr) - -#define MSP3430_FAST_MUTE 0xFF -/* a handy volume transform function, -1000..1000 -> 0x01..0x7F */ -#define MSP3430_VOLUME(value) (0x01+(0x7F-0x01)*log(value+1001)/log(2001)) - -/*----------------------------------------------------------*/ - -/* MSP chip families */ -#define MSPFAMILY_UNKNOWN 0 -#define MSPFAMILY_34x0D 1 -#define MSPFAMILY_34x5D 2 -#define MSPFAMILY_34x0G 3 -#define MSPFAMILY_34x5G 4 - -/* values for MSP standard */ -#define MSPSTANDARD_UNKNOWN 0x00 -#define MSPSTANDARD_AUTO 0x01 -#define MSPSTANDARD_FM_M 0x02 -#define MSPSTANDARD_FM_BG 0x03 -#define MSPSTANDARD_FM_DK1 0x04 -#define MSPSTANDARD_FM_DK2 0x04 -#define MSPSTANDARD_NICAM_BG 0x08 -#define MSPSTANDARD_NICAM_L 0x09 -#define MSPSTANDARD_NICAM_I 0x0A -#define MSPSTANDARD_NICAM_DK 0x0B - -/* values for MSP format */ -#define MSPFORMAT_UNKNOWN 0x00 -#define MSPFORMAT_FM 0x10 -#define MSPFORMAT_1xFM 0x00|MSPFORMAT_FM -#define MSPFORMAT_2xFM 0x01|MSPFORMAT_FM -#define MSPFORMAT_NICAM 0x20 -#define MSPFORMAT_NICAM_FM 0x00|MSPFORMAT_NICAM -#define MSPFORMAT_NICAM_AM 0x01|MSPFORMAT_NICAM -#define MSPFORMAT_SCART 0x30 - -/* values for MSP mode */ -#define MSPMODE_UNKNOWN 0 -/* automatic modes */ -#define MSPMODE_STEREO_AB 1 -#define MSPMODE_STEREO_A 2 -#define MSPMODE_STEREO_B 3 -/* forced modes */ -#define MSPMODE_MONO 4 -#define MSPMODE_STEREO 5 -#define MSPMODE_AB 6 -#define MSPMODE_A 7 -#define MSPMODE_B 8 -/*----------------------------------------------------------*/ - -#define xf86_InitMSP3430 InitMSP3430 -extern _X_EXPORT void InitMSP3430(MSP3430Ptr m); - -#define xf86_DetectMSP3430 DetectMSP3430 -extern _X_EXPORT MSP3430Ptr DetectMSP3430(I2CBusPtr b, I2CSlaveAddr addr); - -#define xf86_ResetMSP3430 ResetMSP3430 -extern _X_EXPORT void ResetMSP3430(MSP3430Ptr m); - -#define xf86_MSP3430SetVolume MSP3430SetVolume -extern _X_EXPORT void MSP3430SetVolume(MSP3430Ptr m, CARD8 value); - -#define xf86_MSP3430SetSAP MSP3430SetSAP -extern _X_EXPORT void MSP3430SetSAP(MSP3430Ptr m, int mode); - -#define MSP3430SymbolsList \ - "InitMSP3430", \ - "DetectMSP3430", \ - "ResetMSP3430", \ - "MSP3430SetVolume", \ - "MSP3430SetSAP" - -#endif diff --git a/xorg-server/hw/xfree86/i2c/msp3430_module.c b/xorg-server/hw/xfree86/i2c/msp3430_module.c deleted file mode 100644 index e177efe7f..000000000 --- a/xorg-server/hw/xfree86/i2c/msp3430_module.c +++ /dev/null @@ -1,24 +0,0 @@ -#ifdef HAVE_XORG_CONFIG_H -#include <xorg-config.h> -#endif - -#include "xf86Module.h" - -static XF86ModuleVersionInfo msp3430VersRec = { - "msp3430", - MODULEVENDORSTRING, - MODINFOSTRING1, - MODINFOSTRING2, - XORG_VERSION_CURRENT, - 1, 0, 0, - ABI_CLASS_VIDEODRV, /* This needs the video driver ABI */ - ABI_VIDEODRV_VERSION, - MOD_CLASS_NONE, - {0, 0, 0, 0} -}; - -_X_EXPORT XF86ModuleData msp3430ModuleData = { - &msp3430VersRec, - NULL, - NULL -}; diff --git a/xorg-server/hw/xfree86/i2c/tda8425.c b/xorg-server/hw/xfree86/i2c/tda8425.c deleted file mode 100644 index 051249b8a..000000000 --- a/xorg-server/hw/xfree86/i2c/tda8425.c +++ /dev/null @@ -1,83 +0,0 @@ -#ifdef HAVE_XORG_CONFIG_H -#include <xorg-config.h> -#endif - -#include "xf86.h" -#include "xf86i2c.h" -#include "tda8425.h" -#include "i2c_def.h" - -#define TDA8425(a,b) { \ - data[0]=a; \ - data[1]=b; \ - I2C_WriteRead(&(t->d), data, 2, NULL, 0); \ - } - -TDA8425Ptr -Detect_tda8425(I2CBusPtr b, I2CSlaveAddr addr, Bool force) -{ - TDA8425Ptr t; - - t = calloc(1, sizeof(TDA8425Rec)); - if (t == NULL) - return NULL; - t->d.DevName = "TDA8425 BTSC Stereo Audio Processor"; - t->d.SlaveAddr = addr; - t->d.pI2CBus = b; - t->d.NextDev = NULL; - t->d.StartTimeout = b->StartTimeout; - t->d.BitTimeout = b->BitTimeout; - t->d.AcknTimeout = b->AcknTimeout; - t->d.ByteTimeout = b->ByteTimeout; - - if (!force && !I2CProbeAddress(b, addr)) { - free(t); - return NULL; - } - - /* set default parameters */ - if (!I2CDevInit(&(t->d))) { - free(t); - return NULL; - } - - return t; -} - -Bool -tda8425_init(TDA8425Ptr t) -{ - t->stereo = 3; /* 3 = Spacial 2 = Linear 1 = Pseudo 0 = Forced mono */ - t->v_left = 0xFF; /* FF - C0 */ - t->v_right = 0xFF; /* FF - C0 */ - t->bass = 0xF6; /* 0xFF - 0xF0 */ - t->treble = 0xF6; /* 0xFF - 0xF0 */ - t->src_sel = 3; /* 3 - stereo */ - t->mute = TRUE; - t->mux = 0; /* 0 - source one, 1 -source 2 */ - - tda8425_setaudio(t); - return TRUE; -} - -void -tda8425_setaudio(TDA8425Ptr t) -{ - I2CByte data[2]; - - TDA8425(0x00, t->v_left); - TDA8425(0x01, t->v_right); - TDA8425(0x02, t->bass); - TDA8425(0x03, t->treble); - TDA8425(0x08, - 0xC0 | (t->mute ? 0x20 : 0x0) | (t->stereo << 3) | (t-> - src_sel << 1) | - t->mux); -} - -void -tda8425_mute(TDA8425Ptr t, Bool mute) -{ - t->mute = mute; - tda8425_setaudio(t); -} diff --git a/xorg-server/hw/xfree86/i2c/tda8425.h b/xorg-server/hw/xfree86/i2c/tda8425.h deleted file mode 100644 index e3dfb1384..000000000 --- a/xorg-server/hw/xfree86/i2c/tda8425.h +++ /dev/null @@ -1,44 +0,0 @@ -#ifndef __TDA8425_H__ -#define __TDA8425_H__ - -#include "xf86i2c.h" - -typedef struct { - I2CDevRec d; - - int mux; - int stereo; - int v_left; - int v_right; - int bass; - int treble; - int src_sel; - Bool mute; -} TDA8425Rec, *TDA8425Ptr; - -#define TDA8425_ADDR_1 0x82 - -/* the third parameter is meant to force detection of tda8425. - This is because tda8425 is write-only and complete implementation - of I2C protocol is not always available. Besides address there is no good - way to autodetect it so we have to _know_ it is there anyway */ - -#define xf86_Detect_tda8425 Detect_tda8425 -extern _X_EXPORT TDA8425Ptr Detect_tda8425(I2CBusPtr b, I2CSlaveAddr addr, - Bool force); -#define xf86_tda8425_init tda8425_init -extern _X_EXPORT Bool tda8425_init(TDA8425Ptr t); - -#define xf86_tda8425_setaudio tda8425_setaudio -extern _X_EXPORT void tda8425_setaudio(TDA8425Ptr t); - -#define xf86_tda8425_mute tda8425_mute -extern _X_EXPORT void tda8425_mute(TDA8425Ptr t, Bool mute); - -#define TDA8425SymbolsList \ - "Detect_tda8425", \ - "tda8425_init", \ - "tda8425_setaudio", \ - "tda8425_mute" - -#endif diff --git a/xorg-server/hw/xfree86/i2c/tda8425_module.c b/xorg-server/hw/xfree86/i2c/tda8425_module.c deleted file mode 100644 index 74c820f73..000000000 --- a/xorg-server/hw/xfree86/i2c/tda8425_module.c +++ /dev/null @@ -1,24 +0,0 @@ -#ifdef HAVE_XORG_CONFIG_H -#include <xorg-config.h> -#endif - -#include "xf86Module.h" - -static XF86ModuleVersionInfo tda8425VersRec = { - "tda8425", - MODULEVENDORSTRING, - MODINFOSTRING1, - MODINFOSTRING2, - XORG_VERSION_CURRENT, - 1, 0, 0, - ABI_CLASS_VIDEODRV, /* This needs the video driver ABI */ - ABI_VIDEODRV_VERSION, - MOD_CLASS_NONE, - {0, 0, 0, 0} -}; - -_X_EXPORT XF86ModuleData tda8425ModuleData = { - &tda8425VersRec, - NULL, - NULL -}; diff --git a/xorg-server/hw/xfree86/i2c/tda9850.c b/xorg-server/hw/xfree86/i2c/tda9850.c deleted file mode 100644 index d258bda05..000000000 --- a/xorg-server/hw/xfree86/i2c/tda9850.c +++ /dev/null @@ -1,136 +0,0 @@ -#ifdef HAVE_XORG_CONFIG_H -#include <xorg-config.h> -#endif - -#include "xf86.h" -#include "xf86i2c.h" -#include "tda9850.h" -#include "i2c_def.h" - -#define TDA9850(a,b) { \ - data[0]=a; \ - data[1]=b; \ - I2C_WriteRead(&(t->d), data, 2, NULL, 0); \ - } - -TDA9850Ptr -Detect_tda9850(I2CBusPtr b, I2CSlaveAddr addr) -{ - TDA9850Ptr t; - I2CByte a; - - t = calloc(1, sizeof(TDA9850Rec)); - if (t == NULL) - return NULL; - switch (addr) { - case TDA9850_ADDR_1: - t->d.DevName = "TDA9850 BTSC Stereo+SAP Audio Processor"; - break; - default: - t->d.DevName = "Generic TDAxxxx"; - break; - } - t->d.SlaveAddr = addr; - t->d.pI2CBus = b; - t->d.NextDev = NULL; - t->d.StartTimeout = b->StartTimeout; - t->d.BitTimeout = b->BitTimeout; - t->d.AcknTimeout = b->AcknTimeout; - t->d.ByteTimeout = b->ByteTimeout; - - if (!I2C_WriteRead(&(t->d), NULL, 0, &a, 1)) { - free(t); - return NULL; - } - - /* set default parameters */ - if (!I2CDevInit(&(t->d))) { - free(t); - return NULL; - } - - return t; -} - -Bool -tda9850_init(TDA9850Ptr t) -{ - t->stereo = 1; - t->sap = 0; - t->mute = TRUE; - t->sap_mute = TRUE; - tda9850_setaudio(t); - return TRUE; -} - -void -tda9850_setaudio(TDA9850Ptr t) -{ - CARD8 data[2]; - - if (t->mux == 2) { - TDA9850(0x04, 0x0F); - TDA9850(0x05, 0x0F); - TDA9850(0x06, 0x58); - TDA9850(0x07, 0x07); - TDA9850(0x08, 0x00); - TDA9850(0x09, 0x00); - TDA9850(0x0A, 0x03); - } - else { - TDA9850(0x04, 0x07); - TDA9850(0x05, 0x07); - TDA9850(0x06, 0x58); - TDA9850(0x07, 0x07); - TDA9850(0x08, 0x10); - TDA9850(0x09, 0x10); - TDA9850(0x0A, 0x03); - } - - TDA9850(0x06, - (t->stereo << 6) | (t->sap << 7) | (t->mute ? 0x8 : 0) | (t-> - sap_mute ? - 0x10 : - 0x0)); -} - -void -tda9850_mute(TDA9850Ptr t, Bool mute) -{ - CARD8 data[2]; - - xf86DrvMsg(t->d.pI2CBus->scrnIndex, X_INFO, "tda9850_mute %s\n", - mute ? "on" : "off"); - t->mute = mute; - - TDA9850(0x06, - (t->stereo << 6) | (t->sap << 7) | (t->mute ? 0x8 : 0x0) | (t-> - sap_mute - ? 0x10 : - 0x0)); -} - -void -tda9850_sap_mute(TDA9850Ptr t, Bool sap_mute) -{ - CARD8 data[2]; - - xf86DrvMsg(t->d.pI2CBus->scrnIndex, X_INFO, "tda9850_sap_mute %s\n", - sap_mute ? "on" : "off"); - t->sap_mute = sap_mute; - - TDA9850(0x06, - (t->stereo << 6) | (t->sap << 7) | (t->mute ? 0x8 : 0x0) | (t-> - sap_mute - ? 0x10 : - 0x0)); -} - -CARD16 -tda9850_getstatus(TDA9850Ptr t) -{ - CARD16 status; - - I2C_WriteRead(&(t->d), NULL, 0, (I2CByte *) &status, 2); - return status; -} diff --git a/xorg-server/hw/xfree86/i2c/tda9850.h b/xorg-server/hw/xfree86/i2c/tda9850.h deleted file mode 100644 index 7d82095f0..000000000 --- a/xorg-server/hw/xfree86/i2c/tda9850.h +++ /dev/null @@ -1,43 +0,0 @@ -#ifndef __TDA9850_H__ -#define __TDA9850_H__ - -#include "xf86i2c.h" - -typedef struct { - I2CDevRec d; - - int mux; - int stereo; - int sap; - Bool mute; - Bool sap_mute; -} TDA9850Rec, *TDA9850Ptr; - -#define TDA9850_ADDR_1 0xB4 - -#define xf86_Detect_tda9850 Detect_tda9850 -extern _X_EXPORT TDA9850Ptr Detect_tda9850(I2CBusPtr b, I2CSlaveAddr addr); - -#define xf86_tda9850_init tda9850_init -extern _X_EXPORT Bool tda9850_init(TDA9850Ptr t); - -#define xf86_tda9850_setaudio tda9850_setaudio -extern _X_EXPORT void tda9850_setaudio(TDA9850Ptr t); - -#define xf86_tda9850_mute tda9850_mute -extern _X_EXPORT void tda9850_mute(TDA9850Ptr t, Bool mute); - -#define xf86_tda9850_sap_mute tda9850_sap_mute -extern _X_EXPORT void tda9850_sap_mute(TDA9850Ptr t, Bool sap_mute); - -#define xf86_tda9850_getstatus tda9850_getstatus -extern _X_EXPORT CARD16 tda9850_getstatus(TDA9850Ptr t); - -#define TDA9850SymbolsList \ - "Detect_tda9850", \ - "tda9850_init", \ - "tda9850_setaudio", \ - "tda9850_mute", \ - "tda9850_sap_mute" - -#endif diff --git a/xorg-server/hw/xfree86/i2c/tda9850_module.c b/xorg-server/hw/xfree86/i2c/tda9850_module.c deleted file mode 100644 index 197d65a71..000000000 --- a/xorg-server/hw/xfree86/i2c/tda9850_module.c +++ /dev/null @@ -1,24 +0,0 @@ -#ifdef HAVE_XORG_CONFIG_H -#include <xorg-config.h> -#endif - -#include "xf86Module.h" - -static XF86ModuleVersionInfo tda9850VersRec = { - "tda9850", - MODULEVENDORSTRING, - MODINFOSTRING1, - MODINFOSTRING2, - XORG_VERSION_CURRENT, - 1, 0, 0, - ABI_CLASS_VIDEODRV, /* This needs the video driver ABI */ - ABI_VIDEODRV_VERSION, - MOD_CLASS_NONE, - {0, 0, 0, 0} -}; - -_X_EXPORT XF86ModuleData tda9850ModuleData = { - &tda9850VersRec, - NULL, - NULL -}; diff --git a/xorg-server/hw/xfree86/i2c/tda9885.c b/xorg-server/hw/xfree86/i2c/tda9885.c deleted file mode 100644 index fd859bde0..000000000 --- a/xorg-server/hw/xfree86/i2c/tda9885.c +++ /dev/null @@ -1,100 +0,0 @@ -#ifdef HAVE_XORG_CONFIG_H -#include <xorg-config.h> -#endif - -#include "xf86.h" -#include "xf86i2c.h" -#include "tda9885.h" -#include "i2c_def.h" - -TDA9885Ptr -Detect_tda9885(I2CBusPtr b, I2CSlaveAddr addr) -{ - TDA9885Ptr t; - I2CByte a; - - t = calloc(1, sizeof(TDA9885Rec)); - if (t == NULL) - return NULL; - switch (addr) { - case TDA9885_ADDR_1: - case TDA9885_ADDR_2: - case TDA9885_ADDR_3: - case TDA9885_ADDR_4: - t->d.DevName = "TDA9885 Alignment-free IF-PLL"; - break; - default: - t->d.DevName = "Generic TDAxxxx"; - break; - } - t->d.SlaveAddr = addr; - t->d.pI2CBus = b; - t->d.NextDev = NULL; - t->d.StartTimeout = b->StartTimeout; - t->d.BitTimeout = b->BitTimeout; - t->d.AcknTimeout = b->AcknTimeout; - t->d.ByteTimeout = b->ByteTimeout; - - if (!I2C_WriteRead(&(t->d), NULL, 0, &a, 1)) { - free(t); - return NULL; - } - - /* set default parameters */ - if (!I2CDevInit(&(t->d))) { - free(t); - return NULL; - } - - return t; -} - -Bool -tda9885_init(TDA9885Ptr t) -{ - t->forced_mute_audio = 1; - return TRUE; -} - -void -tda9885_getstatus(TDA9885Ptr t) -{ - CARD8 value; - - I2C_WriteRead(&(t->d), NULL, 0, &value, 1); - t->after_reset = value & 1; - t->afc_status = (value >> 1) & 0xf; - t->fm_carrier = (value >> 5) & 1; - t->vif_level = (value >> 6) & 1; - t->afc_win = (value >> 7) & 1; -} - -void -tda9885_setparameters(TDA9885Ptr t) -{ - CARD8 data[4]; - - data[0] = 0; /* start with subaddress 0 */ - data[1] = (t->sound_trap & 1) | ((t->auto_mute_fm & 1) << 1) | ((t->carrier_mode & 1) << 2) | ((t->modulation & 3) << 3) | ((t->forced_mute_audio & 1) << 5) | ((t->port1 & 1) << 6) | ((t->port2 & 1) << 7); /* B data */ - data[2] = (t->top_adjustment & 0x1f) | ((t->deemphasis & 0x3) << 5) | ((t->audio_gain & 1) << 7); /* C data */ - data[3] = (t->standard_sound_carrier & 0x3) | ((t->standard_video_if & 0x07) << 2) | ((t->minimum_gain & 0x01) << 5) | ((t->gating & 0x01) << 6) | ((t->vif_agc & 0x01) << 7); /* E data */ - - I2C_WriteRead(&(t->d), data, 4, NULL, 0); - - xf86DrvMsg(t->d.pI2CBus->scrnIndex, X_INFO, - "TDA9885 setparam: B data: %x, C data: %x, E data: %x\n", - data[1], data[2], data[3]); -} - -void -tda9885_dumpstatus(TDA9885Ptr t) -{ - xf86DrvMsg(t->d.pI2CBus->scrnIndex, X_INFO, - "TDA9885 status: after_reset=%d afc_status=%d (%3.1f kHz off) fm_carrier=%d vif_level=%d afc_win=%d %s\n", - t->after_reset, t->afc_status, - (t->afc_status < - 8) ? -12.5 - t->afc_status * 25.0 : -12.5 + (16 - - t->afc_status) * - 25.0, t->fm_carrier, t->vif_level, t->afc_win, - t->afc_win ? "VCO in" : "VCO out"); -} diff --git a/xorg-server/hw/xfree86/i2c/tda9885.h b/xorg-server/hw/xfree86/i2c/tda9885.h deleted file mode 100644 index 2d8a8af15..000000000 --- a/xorg-server/hw/xfree86/i2c/tda9885.h +++ /dev/null @@ -1,63 +0,0 @@ -#ifndef __TDA9885_H__ -#define __TDA9885_H__ - -#include "xf86i2c.h" - -typedef struct { - I2CDevRec d; - - /* write-only parameters */ - /* B DATA */ - CARD8 sound_trap; - CARD8 auto_mute_fm; - CARD8 carrier_mode; - CARD8 modulation; - CARD8 forced_mute_audio; - CARD8 port1; - CARD8 port2; - /* C DATA */ - CARD8 top_adjustment; - CARD8 deemphasis; - CARD8 audio_gain; - /* E DATA */ - CARD8 standard_sound_carrier; - CARD8 standard_video_if; - CARD8 minimum_gain; - CARD8 gating; - CARD8 vif_agc; - /* read-only values */ - - CARD8 after_reset; - CARD8 afc_status; - CARD8 vif_level; - CARD8 afc_win; - CARD8 fm_carrier; -} TDA9885Rec, *TDA9885Ptr; - -#define TDA9885_ADDR_1 0x86 -#define TDA9885_ADDR_2 0x84 -#define TDA9885_ADDR_3 0x96 -#define TDA9885_ADDR_4 0x94 - -#define xf86_Detect_tda9885 Detect_tda9885 -extern _X_EXPORT TDA9885Ptr Detect_tda9885(I2CBusPtr b, I2CSlaveAddr addr); - -#define xf86_tda9885_init tda9885_init -extern _X_EXPORT Bool tda9885_init(TDA9885Ptr t); - -#define xf86_tda9885_setparameters tda9885_setparameters -extern _X_EXPORT void tda9885_setparameters(TDA9885Ptr t); - -#define xf86_tda9885_getstatus tda9885_getstatus -extern _X_EXPORT void tda9885_getstatus(TDA9885Ptr t); - -#define xf86_tda9885_dumpstatus tda9885_dumpstatus -extern _X_EXPORT void tda9885_dumpstatus(TDA9885Ptr t); - -#define TDA9885SymbolsList \ - "Detect_tda9885", \ - "tda9885_init", \ - "tda9885_setaudio", \ - "tda9885_mute" - -#endif diff --git a/xorg-server/hw/xfree86/i2c/tda9885_module.c b/xorg-server/hw/xfree86/i2c/tda9885_module.c deleted file mode 100644 index e71bd6061..000000000 --- a/xorg-server/hw/xfree86/i2c/tda9885_module.c +++ /dev/null @@ -1,24 +0,0 @@ -#ifdef HAVE_XORG_CONFIG_H -#include <xorg-config.h> -#endif - -#include "xf86Module.h" - -static XF86ModuleVersionInfo tda9885VersRec = { - "tda9885", - MODULEVENDORSTRING, - MODINFOSTRING1, - MODINFOSTRING2, - XORG_VERSION_CURRENT, - 1, 0, 0, - ABI_CLASS_VIDEODRV, /* This needs the video driver ABI */ - ABI_VIDEODRV_VERSION, - MOD_CLASS_NONE, - {0, 0, 0, 0} -}; - -_X_EXPORT XF86ModuleData tda9885ModuleData = { - &tda9885VersRec, - NULL, - NULL -}; diff --git a/xorg-server/hw/xfree86/i2c/uda1380.c b/xorg-server/hw/xfree86/i2c/uda1380.c deleted file mode 100644 index 87226877b..000000000 --- a/xorg-server/hw/xfree86/i2c/uda1380.c +++ /dev/null @@ -1,196 +0,0 @@ -/************************************************************************************* - * Copyright (C) 2005 Bogdan D. bogdand@users.sourceforge.net - * - * Permission is hereby granted, free of charge, to any person obtaining a copy of this - * software and associated documentation files (the "Software"), to deal in the Software - * without restriction, including without limitation the rights to use, copy, modify, - * merge, publish, distribute, sublicense, and/or sell copies of the Software, - * and to permit persons to whom the Software is furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in all copies or - * substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, - * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE - * AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, - * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - * - * Except as contained in this notice, the name of the author shall not be used in advertising or - * otherwise to promote the sale, use or other dealings in this Software without prior written - * authorization from the author. - * - ************************************************************************************/ - -#ifdef HAVE_XORG_CONFIG_H -#include <xorg-config.h> -#endif - -#include "xf86.h" -#include "xf86i2c.h" -#include "uda1380.h" -#include "i2c_def.h" - -UDA1380Ptr -Detect_uda1380(I2CBusPtr b, I2CSlaveAddr addr) -{ - UDA1380Ptr t; - I2CByte a; - - t = calloc(1, sizeof(UDA1380Rec)); - if (t == NULL) - return NULL; - switch (addr) { - case UDA1380_ADDR_1: - case UDA1380_ADDR_2: - t->d.DevName = "UDA1380 Stereo audion coder-decoder"; - break; - default: - t->d.DevName = "Generic UDAxxxx"; - break; - } - t->d.SlaveAddr = addr; - t->d.pI2CBus = b; - t->d.NextDev = NULL; - t->d.StartTimeout = b->StartTimeout; - t->d.BitTimeout = b->BitTimeout; - t->d.AcknTimeout = b->AcknTimeout; - t->d.ByteTimeout = b->ByteTimeout; - - if (!I2C_WriteRead(&(t->d), NULL, 0, &a, 1)) { - free(t); - return NULL; - } - - /* set default parameters */ - if (!I2CDevInit(&(t->d))) { - free(t); - return NULL; - } - - xf86DrvMsg(t->d.pI2CBus->scrnIndex, X_INFO, - "UDA1380 stereo coder-decoder detected\n"); - - return t; -} - -Bool -uda1380_init(UDA1380Ptr t) -{ - CARD8 data[3]; - CARD16 tmp; - Bool ret; - - /* Power control */ - data[0] = 0x02; - tmp = - (1 << 13) | (1 << 10) | (1 << 8) | (1 << 7) | (1 << 6) | (1 << 3) | (1 - << - 1); - data[1] = (CARD8) ((tmp >> 8) & 0xff); - data[2] = (CARD8) (tmp & 0xff); - ret = I2C_WriteRead(&(t->d), data, 3, NULL, 0); - if (ret == FALSE) { - xf86DrvMsg(t->d.pI2CBus->scrnIndex, X_INFO, - "UDA1380 failed to initialize\n"); - return FALSE; - } - - /* Analog mixer (AVC) */ - data[0] = 0x03; - /* the analog mixer is muted initially */ - data[1] = 0x3f; - data[2] = 0x3f; - ret = I2C_WriteRead(&(t->d), data, 3, NULL, 0); - if (ret == FALSE) { - xf86DrvMsg(t->d.pI2CBus->scrnIndex, X_INFO, - "UDA1380 failed to initialize\n"); - return FALSE; - } - - xf86DrvMsg(t->d.pI2CBus->scrnIndex, X_INFO, "UDA1380 initialized\n"); - - return TRUE; -} - -void -uda1380_shutdown(UDA1380Ptr t) -{ - CARD8 data[3]; - Bool ret; - - /* Power control */ - data[0] = 0x02; - data[1] = 0; - data[2] = 0; - ret = I2C_WriteRead(&(t->d), data, 3, NULL, 0); - if (ret == FALSE) - xf86DrvMsg(t->d.pI2CBus->scrnIndex, X_INFO, - "UDA1380 failed to shutdown\n"); -} - -void -uda1380_setvolume(UDA1380Ptr t, INT32 value) -{ - CARD8 data[3]; - - /* - * We have to scale the value ranging from -1000 to 1000 to 0x2c to 0 - */ - CARD8 volume = 47 - (CARD8) ((value + 1000) * 47 / 2000); - Bool ret; - - t->analog_mixer_settings = ((volume << 8) & 0x3f00) | (volume & 0x3f); - - /* Analog mixer (AVC) */ - data[0] = 0x03; - data[1] = volume & 0x3f; - data[2] = volume & 0x3f; - ret = I2C_WriteRead(&(t->d), data, 3, NULL, 0); - if (ret == FALSE) - xf86DrvMsg(t->d.pI2CBus->scrnIndex, X_INFO, - "UDA1380 failed to set volume\n"); -} - -void -uda1380_mute(UDA1380Ptr t, Bool mute) -{ - CARD8 data[3]; - Bool ret; - - if (mute == TRUE) { - /* Analog mixer (AVC) */ - data[0] = 0x03; - data[1] = 0xff; - data[2] = 0xff; - ret = I2C_WriteRead(&(t->d), data, 3, NULL, 0); - if (ret == FALSE) - xf86DrvMsg(t->d.pI2CBus->scrnIndex, X_INFO, - "UDA1380 failed to mute\n"); - } - else { - /* Analog mixer (AVC) */ - data[0] = 0x03; - data[1] = (CARD8) ((t->analog_mixer_settings >> 8) & 0x3f); - data[2] = (CARD8) (t->analog_mixer_settings & 0x3f); - ret = I2C_WriteRead(&(t->d), data, 3, NULL, 0); - if (ret == FALSE) - xf86DrvMsg(t->d.pI2CBus->scrnIndex, X_INFO, - "UDA1380 failed to unmute\n"); - } -} - -void -uda1380_getstatus(UDA1380Ptr t) -{ -} - -void -uda1380_setparameters(UDA1380Ptr t) -{ -} - -void -uda1380_dumpstatus(UDA1380Ptr t) -{ -} diff --git a/xorg-server/hw/xfree86/i2c/uda1380.h b/xorg-server/hw/xfree86/i2c/uda1380.h deleted file mode 100644 index f0bc6167a..000000000 --- a/xorg-server/hw/xfree86/i2c/uda1380.h +++ /dev/null @@ -1,81 +0,0 @@ -/************************************************************************************* - * Copyright (C) 2005 Bogdan D. bogdand@users.sourceforge.net - * - * Permission is hereby granted, free of charge, to any person obtaining a copy of this - * software and associated documentation files (the "Software"), to deal in the Software - * without restriction, including without limitation the rights to use, copy, modify, - * merge, publish, distribute, sublicense, and/or sell copies of the Software, - * and to permit persons to whom the Software is furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in all copies or - * substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, - * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE - * AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, - * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - * - * Except as contained in this notice, the name of the author shall not be used in advertising or - * otherwise to promote the sale, use or other dealings in this Software without prior written - * authorization from the author. - * - * Revision 1.3 2005/09/24 21:56:00 bogdand - * Changed the license to a X/MIT one - * - * Revision 1.2 2005/07/01 22:43:11 daniels - * Change all misc.h and os.h references to <X11/foo.h>. - * - * - ************************************************************************************/ - -#ifndef __UDA1380_H__ -#define __UDA1380_H__ - -#include "xf86i2c.h" - -typedef struct { - I2CDevRec d; - - CARD16 analog_mixer_settings; /* register 0x03 */ - -} UDA1380Rec, *UDA1380Ptr; - -#define UDA1380_ADDR_1 0x30 -#define UDA1380_ADDR_2 0x34 - -#define xf86_Detect_uda1380 Detect_uda1380 -extern _X_EXPORT UDA1380Ptr Detect_uda1380(I2CBusPtr b, I2CSlaveAddr addr); - -#define xf86_uda1380_init uda1380_init -extern _X_EXPORT Bool uda1380_init(UDA1380Ptr t); - -#define xf86_uda1380_shutdown uda1380_shutdown -extern _X_EXPORT void uda1380_shutdown(UDA1380Ptr t); - -#define xf86_uda1380_setvolume uda1380_setvolume -extern _X_EXPORT void uda1380_setvolume(UDA1380Ptr t, INT32); - -#define xf86_uda1380_mute uda1380_mute -extern _X_EXPORT void uda1380_mute(UDA1380Ptr t, Bool); - -#define xf86_uda1380_setparameters uda1380_setparameters -extern _X_EXPORT void uda1380_setparameters(UDA1380Ptr t); - -#define xf86_uda1380_getstatus uda1380_getstatus -extern _X_EXPORT void uda1380_getstatus(UDA1380Ptr t); - -#define xf86_uda1380_dumpstatus uda1380_dumpstatus -extern _X_EXPORT void uda1380_dumpstatus(UDA1380Ptr t); - -#define UDA1380SymbolsList \ - "Detect_uda1380", \ - "uda1380_init", \ - "uda1380_shutdown", \ - "uda1380_setvolume", \ - "uda1380_mute", \ - "uda1380_setparameters", \ - "uda1380_getstatus", \ - "uda1380_dumpstatus" - -#endif diff --git a/xorg-server/hw/xfree86/i2c/uda1380_module.c b/xorg-server/hw/xfree86/i2c/uda1380_module.c deleted file mode 100644 index dca834b12..000000000 --- a/xorg-server/hw/xfree86/i2c/uda1380_module.c +++ /dev/null @@ -1,24 +0,0 @@ -#ifdef HAVE_XORG_CONFIG_H -#include <xorg-config.h> -#endif - -#include "xf86Module.h" - -static XF86ModuleVersionInfo uda1380VersRec = { - "uda1380", - MODULEVENDORSTRING, - MODINFOSTRING1, - MODINFOSTRING2, - XORG_VERSION_CURRENT, - 1, 0, 0, - ABI_CLASS_VIDEODRV, /* This needs the video driver ABI */ - ABI_VIDEODRV_VERSION, - MOD_CLASS_NONE, - {0, 0, 0, 0} -}; - -_X_EXPORT XF86ModuleData uda1380ModuleData = { - &uda1380VersRec, - NULL, - NULL -}; diff --git a/xorg-server/hw/xfree86/loader/loadmod.c b/xorg-server/hw/xfree86/loader/loadmod.c index e1f649a74..f1f7c224f 100644 --- a/xorg-server/hw/xfree86/loader/loadmod.c +++ b/xorg-server/hw/xfree86/loader/loadmod.c @@ -197,7 +197,6 @@ static const char *stdSubdirs[] = { "", "input/", "drivers/", - "multimedia/", "extensions/", "internal/", NULL diff --git a/xorg-server/hw/xfree86/man/xorg.conf.man b/xorg-server/hw/xfree86/man/xorg.conf.man index bc33df197..16312124d 100644 --- a/xorg-server/hw/xfree86/man/xorg.conf.man +++ b/xorg-server/hw/xfree86/man/xorg.conf.man @@ -132,14 +132,14 @@ is the path specified with the .B \-configdir command line option (which may be absolute or relative). .PP -Finally, configuration files will also be searched for in directories -reserved for system use. These are to separate configuration files from -the vendor or 3rd party packages from those of local administration. -These files are found in the following directories: +Finally, configuration files will also be searched for in a directory reserved +for system use. +This is to separate configuration files from the vendor or 3rd party packages +from those of local administration. +These files are found in the following directory: .PP .RS 4 .nf -.I /usr/share/X11/__xconfigdir__ .I __datadir__/X11/__xconfigdir__ .fi .RE diff --git a/xorg-server/hw/xwayland/xwayland-input.c b/xorg-server/hw/xwayland/xwayland-input.c index 990cb82d8..cc5f7df05 100644 --- a/xorg-server/hw/xwayland/xwayland-input.c +++ b/xorg-server/hw/xwayland/xwayland-input.c @@ -491,31 +491,43 @@ seat_handle_capabilities(void *data, struct wl_seat *seat, { struct xwl_seat *xwl_seat = data; - if (caps & WL_SEAT_CAPABILITY_POINTER && xwl_seat->pointer == NULL) { + if (caps & WL_SEAT_CAPABILITY_POINTER && xwl_seat->wl_pointer == NULL) { xwl_seat->wl_pointer = wl_seat_get_pointer(seat); wl_pointer_add_listener(xwl_seat->wl_pointer, &pointer_listener, xwl_seat); - xwl_seat_set_cursor(xwl_seat); - xwl_seat->pointer = - add_device(xwl_seat, "xwayland-pointer", xwl_pointer_proc); - } - else if (!(caps & WL_SEAT_CAPABILITY_POINTER) && xwl_seat->pointer) { + + if (xwl_seat->pointer) + EnableDevice(xwl_seat->pointer, TRUE); + else { + xwl_seat_set_cursor(xwl_seat); + xwl_seat->pointer = + add_device(xwl_seat, "xwayland-pointer", xwl_pointer_proc); + } + } else if (!(caps & WL_SEAT_CAPABILITY_POINTER) && xwl_seat->wl_pointer) { wl_pointer_release(xwl_seat->wl_pointer); - RemoveDevice(xwl_seat->pointer, FALSE); - xwl_seat->pointer = NULL; + xwl_seat->wl_pointer = NULL; + + if (xwl_seat->pointer) + DisableDevice(xwl_seat->pointer, TRUE); } - if (caps & WL_SEAT_CAPABILITY_KEYBOARD && xwl_seat->keyboard == NULL) { + if (caps & WL_SEAT_CAPABILITY_KEYBOARD && xwl_seat->wl_keyboard == NULL) { xwl_seat->wl_keyboard = wl_seat_get_keyboard(seat); wl_keyboard_add_listener(xwl_seat->wl_keyboard, &keyboard_listener, xwl_seat); - xwl_seat->keyboard = - add_device(xwl_seat, "xwayland-keyboard", xwl_keyboard_proc); - } - else if (!(caps & WL_SEAT_CAPABILITY_KEYBOARD) && xwl_seat->keyboard) { + + if (xwl_seat->keyboard) + EnableDevice(xwl_seat->keyboard, TRUE); + else { + xwl_seat->keyboard = + add_device(xwl_seat, "xwayland-keyboard", xwl_keyboard_proc); + } + } else if (!(caps & WL_SEAT_CAPABILITY_KEYBOARD) && xwl_seat->wl_keyboard) { wl_keyboard_release(xwl_seat->wl_keyboard); - RemoveDevice(xwl_seat->keyboard, FALSE); - xwl_seat->keyboard = NULL; + xwl_seat->wl_keyboard = NULL; + + if (xwl_seat->keyboard) + DisableDevice(xwl_seat->keyboard, TRUE); } xwl_seat->xwl_screen->expecting_event--; diff --git a/xorg-server/include/dix-config.h.in b/xorg-server/include/dix-config.h.in index f980a3d37..2203f82b4 100644 --- a/xorg-server/include/dix-config.h.in +++ b/xorg-server/include/dix-config.h.in @@ -493,4 +493,7 @@ /* Build glamor's GBM-based EGL support */ #undef GLAMOR_HAS_GBM +/* byte order */ +#undef X_BYTE_ORDER + #endif /* _DIX_CONFIG_H_ */ diff --git a/xorg-server/include/servermd.h b/xorg-server/include/servermd.h index e41331463..0132d67bf 100644 --- a/xorg-server/include/servermd.h +++ b/xorg-server/include/servermd.h @@ -47,290 +47,21 @@ SOFTWARE. #ifndef SERVERMD_H #define SERVERMD_H 1 -/* - * Note: much of this is vestigial from mfb/cfb times. This should - * really be simplified even further. - */ - -/* - * Machine dependent values: - * GLYPHPADBYTES should be chosen with consideration for the space-time - * trade-off. Padding to 0 bytes means that there is no wasted space - * in the font bitmaps (both on disk and in memory), but that access of - * the bitmaps will cause odd-address memory references. Padding to - * 2 bytes would ensure even address memory references and would - * be suitable for a 68010-class machine, but at the expense of wasted - * space in the font bitmaps. Padding to 4 bytes would be good - * for real 32 bit machines, etc. Be sure that you tell the font - * compiler what kind of padding you want because its defines are - * kept separate from this. See server/include/font.h for how - * GLYPHPADBYTES is used. - */ - -#ifdef __avr32__ - -#define IMAGE_BYTE_ORDER MSBFirst -#define BITMAP_BIT_ORDER MSBFirst -#define GLYPHPADBYTES 4 - -#endif /* __avr32__ */ - -#ifdef __arm32__ - -#define IMAGE_BYTE_ORDER LSBFirst -#define BITMAP_BIT_ORDER LSBFirst -#define GLYPHPADBYTES 4 - -#endif /* __arm32__ */ - -#if defined(__nds32__) - -#define IMAGE_BYTE_ORDER LSBFirst - -#if defined(XF86MONOVGA) || defined(XF86VGA16) || defined(XF86MONO) -#define BITMAP_BIT_ORDER MSBFirst -#else -#define BITMAP_BIT_ORDER LSBFirst -#endif - -#if defined(XF86MONOVGA) || defined(XF86VGA16) -#define BITMAP_SCANLINE_UNIT 8 -#endif - -#define GLYPHPADBYTES 4 -#define GETLEFTBITS_ALIGNMENT 1 -#define LARGE_INSTRUCTION_CACHE -#define AVOID_MEMORY_READ - -#endif /* __nds32__ */ - -#if defined __hppa__ - -#define IMAGE_BYTE_ORDER MSBFirst -#define BITMAP_BIT_ORDER MSBFirst -#define GLYPHPADBYTES 4 /* to make fb work */ - /* byte boundries */ -#endif /* hpux || __hppa__ */ - -#if defined(__powerpc__) || defined(__ppc__) || defined(__ppc64__) - -#if defined(__LITTLE_ENDIAN__) -#define IMAGE_BYTE_ORDER LSBFirst -#define BITMAP_BIT_ORDER LSBFirst -#else -#define IMAGE_BYTE_ORDER MSBFirst -#define BITMAP_BIT_ORDER MSBFirst -#endif -#define GLYPHPADBYTES 4 - -#endif /* PowerPC */ - -#if defined(__sh__) - -#if defined(__BIG_ENDIAN__) -#define IMAGE_BYTE_ORDER MSBFirst -#define BITMAP_BIT_ORDER MSBFirst -#define GLYPHPADBYTES 4 -#else -#define IMAGE_BYTE_ORDER LSBFirst -#define BITMAP_BIT_ORDER LSBFirst -#define GLYPHPADBYTES 4 -#endif - -#endif /* SuperH */ - -#if defined(__m32r__) - -#if defined(__BIG_ENDIAN__) -#define IMAGE_BYTE_ORDER MSBFirst -#define BITMAP_BIT_ORDER MSBFirst -#define GLYPHPADBYTES 4 -#else -#define IMAGE_BYTE_ORDER LSBFirst -#define BITMAP_BIT_ORDER LSBFirst -#define GLYPHPADBYTES 4 -#endif - -#endif /* __m32r__ */ - -#if (defined(sun) && (defined(__sparc) || defined(sparc))) || \ - (defined(__uxp__) && (defined(sparc) || defined(mc68000))) || \ - defined(__sparc__) || defined(__mc68000__) - -#if defined(__sparc) || defined(__sparc__) -#if !defined(sparc) -#define sparc 1 -#endif -#endif - -#if defined(sun386) || defined(sun5) -#define IMAGE_BYTE_ORDER LSBFirst /* Values for the SUN only */ -#define BITMAP_BIT_ORDER LSBFirst -#else -#define IMAGE_BYTE_ORDER MSBFirst /* Values for the SUN only */ -#define BITMAP_BIT_ORDER MSBFirst -#endif - -#define GLYPHPADBYTES 4 - -#endif /* sun && !(i386 && SVR4) */ - -#if defined(ibm032) || defined (ibm) - -#ifdef __i386__ -#define IMAGE_BYTE_ORDER LSBFirst /* Value for PS/2 only */ -#else -#define IMAGE_BYTE_ORDER MSBFirst /* Values for the RT only */ -#endif -#define BITMAP_BIT_ORDER MSBFirst -#define GLYPHPADBYTES 1 -/* ibm pcc doesn't understand pragmas. */ +#include "dix-config.h" -#ifdef __i386__ -#define BITMAP_SCANLINE_UNIT 8 -#endif - -#endif /* ibm */ - -#if (defined(mips) || defined(__mips)) - -#if defined(MIPSEL) || defined(__MIPSEL__) -#define IMAGE_BYTE_ORDER LSBFirst /* Values for the PMAX only */ -#define BITMAP_BIT_ORDER LSBFirst -#define GLYPHPADBYTES 4 -#else -#define IMAGE_BYTE_ORDER MSBFirst /* Values for the MIPS only */ -#define BITMAP_BIT_ORDER MSBFirst -#define GLYPHPADBYTES 4 -#endif - -#endif /* mips */ - -#if defined(__alpha) || defined(__alpha__) -#define IMAGE_BYTE_ORDER LSBFirst /* Values for the Alpha only */ -#define BITMAP_BIT_ORDER LSBFirst -#define GLYPHPADBYTES 4 - -#endif /* alpha */ - -#if defined (linux) && defined (__s390__) - -#define IMAGE_BYTE_ORDER MSBFirst -#define BITMAP_BIT_ORDER MSBFirst -#define GLYPHPADBYTES 4 - -#define BITMAP_SCANLINE_UNIT 8 -#define FAST_UNALIGNED_READ - -#endif /* linux/s390 */ - -#if defined (linux) && defined (__s390x__) - -#define IMAGE_BYTE_ORDER MSBFirst -#define BITMAP_BIT_ORDER MSBFirst -#define GLYPHPADBYTES 4 - -#define BITMAP_SCANLINE_UNIT 8 -#define FAST_UNALIGNED_READ - -#endif /* linux/s390x */ - -#if defined(__ia64__) || defined(ia64) - -#define IMAGE_BYTE_ORDER LSBFirst -#define BITMAP_BIT_ORDER LSBFirst -#define GLYPHPADBYTES 4 - -#endif /* ia64 */ - -#if defined(__amd64__) || defined(amd64) || defined(__amd64) -#define IMAGE_BYTE_ORDER LSBFirst -#define BITMAP_BIT_ORDER LSBFirst -#define GLYPHPADBYTES 4 -/* ???? */ -#endif /* AMD64 */ - -#if defined(SVR4) && (defined(__i386__) || defined(__i386) ) || \ - defined(__alpha__) || defined(__alpha) || \ - defined(__i386__) || \ - defined(__s390x__) || defined(__s390__) - -#ifndef IMAGE_BYTE_ORDER -#define IMAGE_BYTE_ORDER LSBFirst -#endif - -#ifndef BITMAP_BIT_ORDER -#define BITMAP_BIT_ORDER LSBFirst -#endif - -#ifndef GLYPHPADBYTES -#define GLYPHPADBYTES 4 -#endif - -#endif /* SVR4 / BSD / i386 */ - -#if defined (linux) && defined (__mc68000__) - -#define IMAGE_BYTE_ORDER MSBFirst -#define BITMAP_BIT_ORDER MSBFirst -#define GLYPHPADBYTES 4 - -#endif /* linux/m68k */ - -/* linux on ARM */ -#if defined(linux) && defined(__arm__) -#define IMAGE_BYTE_ORDER LSBFirst -#define BITMAP_BIT_ORDER LSBFirst -#define GLYPHPADBYTES 4 -#endif - -/* linux on IBM S/390 */ -#if defined (linux) && defined (__s390__) -#define IMAGE_BYTE_ORDER MSBFirst -#define BITMAP_BIT_ORDER MSBFirst -#define GLYPHPADBYTES 4 -#endif /* linux/s390 */ - -#ifdef __aarch64__ - -#ifdef __AARCH64EL__ +#if X_BYTE_ORDER == X_LITTLE_ENDIAN #define IMAGE_BYTE_ORDER LSBFirst #define BITMAP_BIT_ORDER LSBFirst -#endif -#ifdef __AARCH64EB__ +#elif X_BYTE_ORDER == X_BIG_ENDIAN #define IMAGE_BYTE_ORDER MSBFirst #define BITMAP_BIT_ORDER MSBFirst -#endif -#define GLYPHPADBYTES 4 - -#endif /* __aarch64__ */ - -#if defined(__arc__) - -#if defined(__BIG_ENDIAN__) -#define IMAGE_BYTE_ORDER MSBFirst -#define BITMAP_BIT_ORDER MSBFirst #else -#define IMAGE_BYTE_ORDER LSBFirst -#define BITMAP_BIT_ORDER LSBFirst +#error "Too weird to live." #endif -#define GLYPHPADBYTES 4 - -#endif /* ARC */ - -#ifdef __xtensa__ -#ifdef __XTENSA_EL__ -#define IMAGE_BYTE_ORDER LSBFirst -#define BITMAP_BIT_ORDER LSBFirst -#endif -#ifdef __XTENSA_EB__ -#define IMAGE_BYTE_ORDER MSBFirst -#define BITMAP_BIT_ORDER MSBFirst -#endif +#ifndef GLYPHPADBYTES #define GLYPHPADBYTES 4 - -#endif /* __xtensa__ */ +#endif /* size of buffer to use with GetImage, measured in bytes. There's obviously * a trade-off between the amount of heap used and the number of times the @@ -390,8 +121,4 @@ extern _X_EXPORT PaddingInfo PixmapWidthPaddingInfo[]; #define BitmapBytePad(w) \ (((int)((w) + BITMAP_SCANLINE_PAD - 1) >> LOG2_BITMAP_PAD) << LOG2_BYTES_PER_SCANLINE_PAD) -#define PixmapWidthInPadUnitsProto(w, d) PixmapWidthInPadUnits(w, d) -#define PixmapBytePadProto(w, d) PixmapBytePad(w, d) -#define BitmapBytePadProto(w) BitmapBytePad(w) - #endif /* SERVERMD_H */ diff --git a/xorg-server/mi/mieq.c b/xorg-server/mi/mieq.c index 872ff93da..8907a6ea1 100644 --- a/xorg-server/mi/mieq.c +++ b/xorg-server/mi/mieq.c @@ -516,7 +516,7 @@ mieqProcessDeviceEvent(DeviceIntPtr dev, InternalEvent *event, ScreenPtr screen) verify_internal_event(event); /* refuse events from disabled devices */ - if (!dev->enabled) + if (dev && !dev->enabled) return; /* Custom event handler */ diff --git a/xorg-server/xkeyboard-config/symbols/es b/xorg-server/xkeyboard-config/symbols/es index ab29a05df..ce407ff96 100644 --- a/xorg-server/xkeyboard-config/symbols/es +++ b/xorg-server/xkeyboard-config/symbols/es @@ -86,8 +86,8 @@ xkb_symbols "dvorak" { key <AE11> {[ apostrophe, question, dead_macron, dead_ogonek ]}; key <AE12> {[ exclamdown, questiondown, dead_breve, dead_abovedot ]}; - key <AD01> {[ period, colon, less ]}; - key <AD02> {[ comma, semicolon, greater ]}; + key <AD01> {[ period, colon, less, guillemotleft ]}; + key <AD02> {[ comma, semicolon, greater, guillemotright ]}; key <AD03> {[ ntilde, Ntilde, lstroke, Lstroke ]}; key <AD04> {[ p, P, paragraph ]}; key <AD05> {[ y, Y, yen ]}; |