The Transport Layer FunctionsAlternate Entry (Interface Layer)XimProto member (Transport Layer)Section_XimConnectconnect3.1_XimShutdownshutdown3.2_XimWritewrite3.3_XimReadread3.4_XimFlushflush3.5_XimRegisterDispatcherregister_dispatcher3.6_XimCallDispatchercall_dispatcher3.7
The Protocol layer calls the above functions using the Alternative
Entry in the left column. The transport implementation defines
XimProto member function in the right column. The Alternative Entry is
provided so as to make easier to implement the Protocol Layer.
Opening connection
When XOpenIM is called, the following function is called to connect
with the IM Server.
Bool (*connect)XIM imim
Specifies XIM structure address.
This function must establishes the connection to the IM Server. If the
connection is established successfully, this function returns True.
The Alternative Entry for this function is:
Bool _XimConnectXIM imim
Specifies XIM structure address.
Closing connection
When XCloseIM is called, the following function is called to
disconnect the connection with the IM Server. The Alternative Entry
for this function is:
Bool (*shutdown)XIM imim
Specifies XIM structure address.
This function must close connection with the IM Server. If the
connection is closed successfully, this function returns True. The
Alternative Entry for this function is:
Bool _XimShutdownXIM imim
Specifies XIM structure address.
Writing data
The following function is called, when Xlib needs to write data to the
IM Server.
Bool _XimWriteXIM imINT16 lenXPointer dataim
Specifies XIM structure address.
len
Specifies the length of writing data.
data
Specifies the writing data.
This function writes the data to the IM Server, regardless
of the contents. The number of bytes is passed to len. The
writing data is passed to data. If data is sent successfully,
the function returns True. Refer to "The Input Method Protocol" for
the contents of the writing data. The Alternative Entry for this
function is:
Bool _XimWriteXIM imINT16 lenXPointer dataim
Specifies XIM structure address.
len
Specifies the length of writing data.
data
Specifies the writing data.
Reading data
The following function is called when Xlib waits for response from IM
server synchronously.
Bool _XimReadXIM imXPointer read_bufint buf_lenint *ret_lenim
Specifies XIM structure address.
read_buf
Specifies the buffer to store data.
buf_len
Specifies the size of the bufferret_len
Specifies the length of stored data.
This function stores the read data in read_buf, which size is
specified as buf_len. The size of data is set to ret_len.
This function return True, if the data is read normally or reading
data is completed.
The Alternative Entry for this function is:
Bool _XimReadXIM imINT16 *ret_lenXPointer bufint buf_lenBool (*predicate)()XPointer predicate_argim
Specifies XIM structure address.
ret_len
Specifies the size of the data buffer.
buf
Specifies the buffer to store data.
buf_len
Specifies the length of buffer.
predicate
Specifies the predicate for the XIM data.
predicate_arg
Specifies the predicate specific data.
The predicate procedure indicates whether the data is for the
XIM or not. len
This function stores the read data in buf, which size
is specified as buf_len. The size of data is set to
ret_len. If preedicate()
returns True, this function returns True. If not, it calls the registered callback function.
The procedure and its arguments are:
void (*predicate)XIM imINT16 lenXPointer dataXPointer predicate_argim
Specifies XIM structure address.
len
Specifies the size of the data buffer.
data
Specifies the buffer to store data.
predicate_arg
Specifies the predicate specific data.
Flushing buffer
The following function is called when Xlib needs to flush the data.
void (*flush)XIM imim
Specifies XIM structure address.
This function must flush the data stored in internal buffer on the
transport layer. If data transfer is completed, the function returns
True. The Alternative Entry for this function is:
void _XimFlushXIM imim
Specifies XIM structure address.
Registering asynchronous data handler
Xlib needs to handle asynchronous response from IM Server. This is
because some of the XIM data occur asynchronously to X events.
Those data will be handled in the Filter,
and the Filter
will call asynchronous data handler in the protocol layer. Then it
calls dispatchers in the transport layer. The dispatchers are
implemented by the protocol layer. This function must store the
information and prepare for later call of the dispatchers using
.
When multiple dispatchers are registered, they will be called
sequentially in order of registration, on arrival of asynchronous
data. The register_dispatcher is declared as following:
Bool (*register_dispatcher)XIM imBool (*dispatcher)()XPointer call_dataim
Specifies XIM structure address.
dispatcher
Specifies the dispatcher function to register.
call_data
Specifies a parameter for the dispatcher.
The dispatcher is a function of the following type:
Bool (*dispatcher)XIM imINT16 lenXPointer dataXPointer call_dataim
Specifies XIM structure address.
len
Specifies the size of the data buffer.
data
Specifies the buffer to store data.
call_data
Specifies a parameter passed to the register_dispatcher.
The dispatcher is provided by the protocol layer. They are called once
for every asynchronous data, in order of registration. If the data is
used, it must return True. otherwise, it must return False.
If the dispatcher function returns True, the Transport Layer assume
that the data has been processed by the upper layer. The Alternative
Entry for this function is:
Bool _XimRegisterDispatcherXIM imBool (*dispatcher)()XPointer call_dataim
Specifies XIM structure address.
dispatcher
Specifies the dispatcher function to register.
call_data
Specifies a parameter for the dispatcher.
Calling dispatcher
The following function is used to call the registered dispatcher
function, when the asynchronous response from IM Server has arrived.
Bool (*call_dispatcher)XIM imINT16 lenXPointer dataim
Specifies XIM structure address.
len
Specifies the size of data buffer.
data
Specifies the buffer to store data.
The call_dispatcher must call the dispatcher function, in order of
their registration. len and data are the data passed to
register_dispatcher.
The return values are checked at each invocation, and if it finds
True, it immediately return with true for its return value.
It is depend on the upper layer whether the read data is XIM
Protocol packet unit or not.
The Alternative Entry for this function is:
Bool _XimCallDispatcherXIM imINT16 lenXPointer call_dataSample implementations for the Transport Layer
Sample implementations for the transporter using the X connection is
described here.
X Transport
At the beginning of the X Transport connection for the XIM transport
mechanism, two different windows must be created either in an Xlib XIM
or in an IM Server, with which the Xlib and the IM Server exchange the
XIM transports by using the ClientMessage events and Window Properties.
In the following, the window created by the Xlib is referred as the
"client communication window", and on the other hand, the window created
by the IM Server is referred as the "IMS communication window".
Connection
In order to establish a connection, a communication window is created.
A ClientMessage in the following event's format is sent to the owner
window of XIM_SERVER selection, which the IM Server has created.
Refer to "The Input Method Protocol" for the XIM_SERVER atom.
The ClientMessage sent to the IMS window.Structure MemberContentsinttypeClientMessageu_longserialSet by the X Window SystemBoolsend_eventSet by the X Window SystemDisplay*displayThe display to which connectsWindowwindowIMS Window IDAtommessage_typeXInternAtom(display, "_XIM_CONNECT", false)intformat32longdata.1[0]client communication window IDlongdata.1[1]client-major-transport-version(*1)longdata.1[2]client-major-transport-version(*1)
In order to establish the connection (to notify the IM Server communication
window), the IM Server sends a ClientMessage in the following event's
format to the client communication window.
The ClientMessage sent by IM Server.Structure MemberContentsinttypeClientMessageu_longserialSet by the X Window SystemBoolsend_eventSet by the X Window SystemDisplay*displayThe display to which connectsWindowwindowIMS Window IDAtommessage_typeXInternAtom(display, "_XIM_CONNECT", false)intformat32longdata.1[0]client communication window IDlongdata.1[1]client-major-transport-version(*1)longdata.1[2]client-major-transport-version(*1)longdata.1[3]dividing size between ClientMessage and Property(*2)
(*1) major/minor-transport-version
The read/write method is decided by the combination of
major/minor-transport-version, as follows:
The read/write method and the major/minor-transport-versionTransport-versionread/writemajorminor00only-CM & Property-with-CM1only-CM & multi-CM2only-CM & multi-CM & Property-with-CM10PropertyNotify20only-CM & PropertyNotify1only-CM & multi-CM & PropertyNotify
only-CM : data is sent via a ClientMessage
multi-CM : data is sent via multiple ClientMessages
Property-with-CM : data is written in Property, and its Atom
is send via ClientMessage
PropertyNotify : data is written in Property, and its Atom
is send via PropertyNotify
The method to decide major/minor-transport-version is as follows:
The client sends 0 as major/minor-transport-version to the IM Server.
The client must support all methods in Table 4-3.
The client may send another number as major/minor-transport-version to
use other method than the above in the future.
The IM Server sends its major/minor-transport-version number to
the client. The client sends data using the method specified by the
IM Server.
If major/minor-transport-version number is not available, it is regarded
as 0.
(*2) dividing size between ClientMessage and Property
If data is sent via both of multi-CM and Property, specify the dividing
size between ClientMessage and Property. The data, which is smaller than
this size, is sent via multi-CM (or only-CM), and the data, which is
lager than this size, is sent via Property.
read/write
The data is transferred via either ClientMessage or Window Property in
the X Window System.
Format for the data from the Client to the IM ServerClientMessage
If data is sent via ClientMessage event, the format is as follows:
The ClientMessage event's format (first or middle)Structure MemberContentsinttypeClientMessageu_longserialSet by the X Window SystemBoolsend_eventSet by the X Window SystemDisplay*displayThe display to which connectsWindowwindowIMS Window IDAtommessage_typeXInternAtom(display, "_XIM_MOREDATA", False)intformat8chardata.b[20](read/write DATA : 20 byte)
The ClientMessage event's format (only or last)Structure MemberContentsinttypeClientMessageu_longserialSet by the X Window SystemBoolsend_eventSet by the X Window SystemDisplay*displayThe display to which connectsWindowwindowIMS Window IDAtommessage_typeXInternAtom(display, "_XIM_PROTOCOL", False)intformat8chardata.b[20](read/write DATA : MAX 20 byte)
If the data is smaller
than 20 bytes, all data other than available data must be 0.
Property
In the case of large data, data will be sent via the Window Property
for the efficiency. There are the following two methods to notify
Property, and transport-version is decided which method is used.
The XChangeProperty function is used to store data in the client
communication window, and Atom of the stored data is notified to the
IM Server via ClientMessage event.
The XChangeProperty function is used to store data in the client
communication window, and Atom of the stored data is notified to the
IM Server via PropertyNotify event.
The arguments of the XChangeProperty are as follows:
The XChangeProperty event's formatArgumentContentsDisplay*displayThe display to which connectsWindowwindowIMS communication window IDAtompropertyread/write property Atom (*1)intformat8intmodePropModeAppendu_char*dataread/write DATAintnelementslength of DATA
(*1) The read/write property ATOM allocates the following strings by
XInternAtom.
"_clientXXX"
The client changes the property with the mode of PropModeAppend and
the IM Server will read it with the delete mode i.e. (delete = True).
If Atom is notified via ClientMessage event, the format of the ClientMessage
is as follows:
The ClientMessage event's format to send Atom of propertyStructure MemberContentsinttypeClientMessageu_longserialSet by the X Window SystemBoolsend_eventSet by the X Window SystemDisplay*displayThe display to which connectsWindowwindowIMS Window IDAtommessage_typeXInternAtom(display, "_XIM_PROTOCOL", False)intformat8longdata.1[0]length of read/write property Atomlongdata.1[1]read/write property Atom
Format for the data from the IM Server to the ClientClientMessage
The format of the ClientMessage is as follows:
The ClientMessage event's format (first or middle)Structure MemberContentsinttypeClientMessageu_longserialSet by the X Window SystemBoolsend_eventSet by the X Window SystemDisplay*displayThe display to which connectsWindowwindowIMS Window IDAtommessage_typeXInternAtom(display, "_XIM_MOREDATA", False)intformat8chardata.b[20](read/write DATA : 20 byte)
The ClientMessage event's format (only or last)Structure MemberContentsinttypeClientMessageu_longserialSet by the X Window SystemBoolsend_eventSet by the X Window SystemDisplay*displayThe display to which connectsWindowwindowIMS Window IDAtommessage_typeXInternAtom(display, "_XIM_PROTOCOL", False)intformat8chardata.b[20](read/write DATA : MAX 20 byte) (*1)
(*1) If the data size is smaller than 20 bytes, all data other than available
data must be 0.
Property
In the case of large data, data will be sent via the Window Property
for the efficiency. There are the following two methods to notify
Property, and transport-version is decided which method is used.
The XChangeProperty function is used to store data in the IMS
communication window, and Atom of the property is sent via the
ClientMessage event.
The XChangeProperty function is used to store data in the IMS
communication window, and Atom of the property is sent via
PropertyNotify event.
The arguments of the XChangeProperty are as follows:
The XChangeProperty event's formatArgumentContentsDisplay*displayThe display to which connectsWindowwindowIMS communication window IDAtompropertyread/write property Atom (*1)intformat8intmodePropModeAppendu_char*dataread/write DATAintnelementslength of DATA
(*1) The read/write property ATOM allocates some strings, which are not
allocated by the client, by XInternAtom.
The IM Server changes the property with the mode of PropModeAppend and
the client reads it with the delete mode, i.e. (delete = True).
If Atom is notified via ClientMessage event, the format of the ClientMessage
is as follows:
The ClientMessage event's format to send Atom of propertyStructure MemberContentsinttypeClientMessageu_longserialSet by the X Window SystemBoolsend_eventSet by the X Window SystemDisplay*displayThe display to which connectsWindowwindowIMS Window IDAtommessage_typeXInternAtom(display, "_XIM_PROTOCOL", False)intformat8longdata.1[0]length of read/write property Atomlongdata.1[1]read/write property Atom
Closing Connection
If the client disconnect with the IM Server, shutdown function should
free the communication window properties and etc..
References
[1] Masahiko Narita and Hideki Hiura, "The Input Method Protocol"
s follows:
The ClientMessage event's format to send Atom of property&2; \
exit 1;; \
esac; \
has_opt=no; \
sane_makeflags=$$MAKEFLAGS; \
if $(am__is_gnu_make); then \
sane_makeflags=$$MFLAGS; \
else \
case $$MAKEFLAGS in \
*\\[\ \ ]*) \
bs=\\; \
sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \
| sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \
esac; \
fi; \
skip_next=no; \
strip_trailopt () \
{ \
flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \
}; \
for flg in $$sane_makeflags; do \
test $$skip_next = yes && { skip_next=no; continue; }; \
case $$flg in \
*=*|--*) continue;; \
-*I) strip_trailopt 'I'; skip_next=yes;; \
-*I?*) strip_trailopt 'I';; \
-*O) strip_trailopt 'O'; skip_next=yes;; \
-*O?*) strip_trailopt 'O';; \
-*l) strip_trailopt 'l'; skip_next=yes;; \
-*l?*) strip_trailopt 'l';; \
-[dEDm]) skip_next=yes;; \
-[JT]) skip_next=yes;; \
esac; \
case $$flg in \
*$$target_option*) has_opt=yes; break;; \
esac; \
done; \
test $$has_opt = yes
am__make_dryrun = (target_option=n; $(am__make_running_with_option))
am__make_keepgoing = (target_option=k; $(am__make_running_with_option))
pkgdatadir = $(datadir)/@PACKAGE@
pkgincludedir = $(includedir)/@PACKAGE@
pkglibdir = $(libdir)/@PACKAGE@
pkglibexecdir = $(libexecdir)/@PACKAGE@
am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
install_sh_DATA = $(install_sh) -c -m 644
install_sh_PROGRAM = $(install_sh) -c
install_sh_SCRIPT = $(install_sh) -c
INSTALL_HEADER = $(INSTALL_DATA)
transform = $(program_transform_name)
NORMAL_INSTALL = :
PRE_INSTALL = :
POST_INSTALL = :
NORMAL_UNINSTALL = :
PRE_UNINSTALL = :
POST_UNINSTALL = :
build_triplet = @build@
host_triplet = @host@
subdir = specs/i18n
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
am__aclocal_m4_deps = $(top_srcdir)/m4/ax_define_dir.m4 \
$(top_srcdir)/configure.ac
am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
$(ACLOCAL_M4)
DIST_COMMON = $(srcdir)/Makefile.am $(am__DIST_COMMON)
mkinstalldirs = $(install_sh) -d
CONFIG_HEADER = $(top_builddir)/src/config.h \
$(top_builddir)/include/X11/XlibConf.h
CONFIG_CLEAN_FILES =
CONFIG_CLEAN_VPATH_FILES =
AM_V_P = $(am__v_P_@AM_V@)
am__v_P_ = $(am__v_P_@AM_DEFAULT_V@)
am__v_P_0 = false
am__v_P_1 = :
AM_V_GEN = $(am__v_GEN_@AM_V@)
am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@)
am__v_GEN_0 = @echo " GEN " $@;
am__v_GEN_1 =
AM_V_at = $(am__v_at_@AM_V@)
am__v_at_ = $(am__v_at_@AM_DEFAULT_V@)
am__v_at_0 = @
am__v_at_1 =
SOURCES =
DIST_SOURCES =
RECURSIVE_TARGETS = all-recursive check-recursive cscopelist-recursive \
ctags-recursive dvi-recursive html-recursive info-recursive \
install-data-recursive install-dvi-recursive \
install-exec-recursive install-html-recursive \
install-info-recursive install-pdf-recursive \
install-ps-recursive install-recursive installcheck-recursive \
installdirs-recursive pdf-recursive ps-recursive \
tags-recursive uninstall-recursive
am__can_run_installinfo = \
case $$AM_UPDATE_INFO_DIR in \
n|no|NO) false;; \
*) (install-info --version) >/dev/null 2>&1;; \
esac
RECURSIVE_CLEAN_TARGETS = mostlyclean-recursive clean-recursive \
distclean-recursive maintainer-clean-recursive
am__recursive_targets = \
$(RECURSIVE_TARGETS) \
$(RECURSIVE_CLEAN_TARGETS) \
$(am__extra_recursive_targets)
AM_RECURSIVE_TARGETS = $(am__recursive_targets:-recursive=) TAGS CTAGS \
distdir
am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
# Read a list of newline-separated strings from the standard input,
# and print each of them once, without duplicates. Input order is
# *not* preserved.
am__uniquify_input = $(AWK) '\
BEGIN { nonempty = 0; } \
{ items[$$0] = 1; nonempty = 1; } \
END { if (nonempty) { for (i in items) print i; }; } \
'
# Make sure the list of sources is unique. This is necessary because,
# e.g., the same source file might be shared among _SOURCES variables
# for different programs/libraries.
am__define_uniq_tagged_files = \
list='$(am__tagged_files)'; \
unique=`for i in $$list; do \
if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
done | $(am__uniquify_input)`
ETAGS = etags
CTAGS = ctags
DIST_SUBDIRS = $(SUBDIRS)
am__DIST_COMMON = $(srcdir)/Makefile.in
DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
am__relativize = \
dir0=`pwd`; \
sed_first='s,^\([^/]*\)/.*$$,\1,'; \
sed_rest='s,^[^/]*/*,,'; \
sed_last='s,^.*/\([^/]*\)$$,\1,'; \
sed_butlast='s,/*[^/]*$$,,'; \
while test -n "$$dir1"; do \
first=`echo "$$dir1" | sed -e "$$sed_first"`; \
if test "$$first" != "."; then \
if test "$$first" = ".."; then \
dir2=`echo "$$dir0" | sed -e "$$sed_last"`/"$$dir2"; \
dir0=`echo "$$dir0" | sed -e "$$sed_butlast"`; \
else \
first2=`echo "$$dir2" | sed -e "$$sed_first"`; \
if test "$$first2" = "$$first"; then \
dir2=`echo "$$dir2" | sed -e "$$sed_rest"`; \
else \
dir2="../$$dir2"; \
fi; \
dir0="$$dir0"/"$$first"; \
fi; \
fi; \
dir1=`echo "$$dir1" | sed -e "$$sed_rest"`; \
done; \
reldir="$$dir2"
ACLOCAL = @ACLOCAL@
ADMIN_MAN_DIR = @ADMIN_MAN_DIR@
ADMIN_MAN_SUFFIX = @ADMIN_MAN_SUFFIX@
AMTAR = @AMTAR@
AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@
APP_MAN_DIR = @APP_MAN_DIR@
APP_MAN_SUFFIX = @APP_MAN_SUFFIX@
AR = @AR@
AUTOCONF = @AUTOCONF@
AUTOHEADER = @AUTOHEADER@
AUTOMAKE = @AUTOMAKE@
AWK = @AWK@
BASE_CFLAGS = @BASE_CFLAGS@
BIGFONT_CFLAGS = @BIGFONT_CFLAGS@
BIGFONT_LIBS = @BIGFONT_LIBS@
CC = @CC@
CCDEPMODE = @CCDEPMODE@
CC_FOR_BUILD = @CC_FOR_BUILD@
CFLAGS = @CFLAGS@
CFLAGS_FOR_BUILD = @CFLAGS_FOR_BUILD@
CHANGELOG_CMD = @CHANGELOG_CMD@
CPP = @CPP@
CPPFLAGS = @CPPFLAGS@
CPPFLAGS_FOR_BUILD = @CPPFLAGS_FOR_BUILD@
CWARNFLAGS = @CWARNFLAGS@
CYGPATH_W = @CYGPATH_W@
DEFS = @DEFS@
DEPDIR = @DEPDIR@
DLLTOOL = @DLLTOOL@
DRIVER_MAN_DIR = @DRIVER_MAN_DIR@
DRIVER_MAN_SUFFIX = @DRIVER_MAN_SUFFIX@
DSYMUTIL = @DSYMUTIL@
DUMPBIN = @DUMPBIN@
ECHO_C = @ECHO_C@
ECHO_N = @ECHO_N@
ECHO_T = @ECHO_T@
EGREP = @EGREP@
EXEEXT = @EXEEXT@
FGREP = @FGREP@
FILE_MAN_DIR = @FILE_MAN_DIR@
FILE_MAN_SUFFIX = @FILE_MAN_SUFFIX@
FOP = @FOP@
GREP = @GREP@
I18N_MODULE_LIBS = @I18N_MODULE_LIBS@
INSTALL = @INSTALL@
INSTALL_CMD = @INSTALL_CMD@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
INSTALL_SCRIPT = @INSTALL_SCRIPT@
INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
KEYSYMDEFS = @KEYSYMDEFS@
LAUNCHD = @LAUNCHD@
LD = @LD@
LDFLAGS = @LDFLAGS@
LDFLAGS_FOR_BUILD = @LDFLAGS_FOR_BUILD@
LIBOBJS = @LIBOBJS@
LIBS = @LIBS@
LIBTOOL = @LIBTOOL@
LIB_MAN_DIR = @LIB_MAN_DIR@
LIB_MAN_SUFFIX = @LIB_MAN_SUFFIX@
LINT = @LINT@
LINTLIB = @LINTLIB@
LINT_FLAGS = @LINT_FLAGS@
LIPO = @LIPO@
LN_S = @LN_S@
LTLIBOBJS = @LTLIBOBJS@
MAKEINFO = @MAKEINFO@
MALLOC_ZERO_CFLAGS = @MALLOC_ZERO_CFLAGS@
MANIFEST_TOOL = @MANIFEST_TOOL@
MAN_SUBSTS = @MAN_SUBSTS@
MISC_MAN_DIR = @MISC_MAN_DIR@
MISC_MAN_SUFFIX = @MISC_MAN_SUFFIX@
MKDIR_P = @MKDIR_P@
NM = @NM@
NMEDIT = @NMEDIT@
OBJDUMP = @OBJDUMP@
OBJEXT = @OBJEXT@
OTOOL = @OTOOL@
OTOOL64 = @OTOOL64@
PACKAGE = @PACKAGE@
PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
PACKAGE_NAME = @PACKAGE_NAME@
PACKAGE_STRING = @PACKAGE_STRING@
PACKAGE_TARNAME = @PACKAGE_TARNAME@
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
PERL = @PERL@
PKG_CONFIG = @PKG_CONFIG@
RANLIB = @RANLIB@
RAWCPP = @RAWCPP@
RAWCPPFLAGS = @RAWCPPFLAGS@
SED = @SED@
SET_MAKE = @SET_MAKE@
SHELL = @SHELL@
STRICT_CFLAGS = @STRICT_CFLAGS@
STRIP = @STRIP@
STYLESHEET_SRCDIR = @STYLESHEET_SRCDIR@
TRADITIONALCPPFLAGS = @TRADITIONALCPPFLAGS@
VERSION = @VERSION@
WCHAR32 = @WCHAR32@
X11_CFLAGS = @X11_CFLAGS@
X11_DATADIR = @X11_DATADIR@
X11_EXTRA_DEPS = @X11_EXTRA_DEPS@
X11_LIBDIR = @X11_LIBDIR@
X11_LIBS = @X11_LIBS@
X11_LOCALEDATADIR = @X11_LOCALEDATADIR@
X11_LOCALEDIR = @X11_LOCALEDIR@
X11_LOCALELIBDIR = @X11_LOCALELIBDIR@
XERRORDB = @XERRORDB@
XKBPROTO_REQUIRES = @XKBPROTO_REQUIRES@
XKEYSYMDB = @XKEYSYMDB@
XLOCALEDATADIR = @XLOCALEDATADIR@
XLOCALEDIR = @XLOCALEDIR@
XLOCALELIBDIR = @XLOCALELIBDIR@
XMALLOC_ZERO_CFLAGS = @XMALLOC_ZERO_CFLAGS@
XMLTO = @XMLTO@
XORG_MAN_PAGE = @XORG_MAN_PAGE@
XORG_SGML_PATH = @XORG_SGML_PATH@
XSLTPROC = @XSLTPROC@
XSL_STYLESHEET = @XSL_STYLESHEET@
XTHREADLIB = @XTHREADLIB@
XTHREAD_CFLAGS = @XTHREAD_CFLAGS@
XTMALLOC_ZERO_CFLAGS = @XTMALLOC_ZERO_CFLAGS@
abs_builddir = @abs_builddir@
abs_srcdir = @abs_srcdir@
abs_top_builddir = @abs_top_builddir@
abs_top_srcdir = @abs_top_srcdir@
ac_ct_AR = @ac_ct_AR@
ac_ct_CC = @ac_ct_CC@
ac_ct_DUMPBIN = @ac_ct_DUMPBIN@
am__include = @am__include@
am__leading_dot = @am__leading_dot@
am__quote = @am__quote@
am__tar = @am__tar@
am__untar = @am__untar@
bindir = @bindir@
build = @build@
build_alias = @build_alias@
build_cpu = @build_cpu@
build_os = @build_os@
build_vendor = @build_vendor@
builddir = @builddir@
datadir = @datadir@
datarootdir = @datarootdir@
docdir = @docdir@
dvidir = @dvidir@
exec_prefix = @exec_prefix@
host = @host@
host_alias = @host_alias@
host_cpu = @host_cpu@
host_os = @host_os@
host_vendor = @host_vendor@
htmldir = @htmldir@
includedir = @includedir@
infodir = @infodir@
install_sh = @install_sh@
libdir = @libdir@
libexecdir = @libexecdir@
localedir = @localedir@
locales = @locales@
localstatedir = @localstatedir@
mandir = @mandir@
mkdir_p = @mkdir_p@
oldincludedir = @oldincludedir@
pdfdir = @pdfdir@
prefix = @prefix@
program_transform_name = @program_transform_name@
psdir = @psdir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
sysconfdir = @sysconfdir@
target_alias = @target_alias@
top_build_prefix = @top_build_prefix@
top_builddir = @top_builddir@
top_srcdir = @top_srcdir@
SUBDIRS = compose framework localedb trans
all: all-recursive
.SUFFIXES:
$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps)
@for dep in $?; do \
case '$(am__configure_deps)' in \
*$$dep*) \
( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \
&& { if test -f $@; then exit 0; else break; fi; }; \
exit 1;; \
esac; \
done; \
echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign specs/i18n/Makefile'; \
$(am__cd) $(top_srcdir) && \
$(AUTOMAKE) --foreign specs/i18n/Makefile
Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
@case '$?' in \
*config.status*) \
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
*) \
echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
esac;
$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(top_srcdir)/configure: $(am__configure_deps)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(ACLOCAL_M4): $(am__aclocal_m4_deps)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(am__aclocal_m4_deps):
mostlyclean-libtool:
-rm -f *.lo
clean-libtool:
-rm -rf .libs _libs
# This directory's subdirectories are mostly independent; you can cd
# into them and run 'make' without going through this Makefile.
# To change the values of 'make' variables: instead of editing Makefiles,
# (1) if the variable is set in 'config.status', edit 'config.status'
# (which will cause the Makefiles to be regenerated when you run 'make');
# (2) otherwise, pass the desired values on the 'make' command line.
$(am__recursive_targets):
@fail=; \
if $(am__make_keepgoing); then \
failcom='fail=yes'; \
else \
failcom='exit 1'; \
fi; \
dot_seen=no; \
target=`echo $@ | sed s/-recursive//`; \
case "$@" in \
distclean-* | maintainer-clean-*) list='$(DIST_SUBDIRS)' ;; \
*) list='$(SUBDIRS)' ;; \
esac; \
for subdir in $$list; do \
echo "Making $$target in $$subdir"; \
if test "$$subdir" = "."; then \
dot_seen=yes; \
local_target="$$target-am"; \
else \
local_target="$$target"; \
fi; \
($(am__cd) $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \
|| eval $$failcom; \
done; \
if test "$$dot_seen" = "no"; then \
$(MAKE) $(AM_MAKEFLAGS) "$$target-am" || exit 1; \
fi; test -z "$$fail"
ID: $(am__tagged_files)
$(am__define_uniq_tagged_files); mkid -fID $$unique
tags: tags-recursive
TAGS: tags
tags-am: $(TAGS_DEPENDENCIES) $(am__tagged_files)
set x; \
here=`pwd`; \
if ($(ETAGS) --etags-include --version) >/dev/null 2>&1; then \
include_option=--etags-include; \
empty_fix=.; \
else \
include_option=--include; \
empty_fix=; \
fi; \
list='$(SUBDIRS)'; for subdir in $$list; do \
if test "$$subdir" = .; then :; else \
test ! -f $$subdir/TAGS || \
set "$$@" "$$include_option=$$here/$$subdir/TAGS"; \
fi; \
done; \
$(am__define_uniq_tagged_files); \
shift; \
if test -z "$(ETAGS_ARGS)$$*$$unique"; then :; else \
test -n "$$unique" || unique=$$empty_fix; \
if test $$# -gt 0; then \
$(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \
"$$@" $$unique; \
else \
$(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \
$$unique; \
fi; \
fi
ctags: ctags-recursive
CTAGS: ctags
ctags-am: $(TAGS_DEPENDENCIES) $(am__tagged_files)
$(am__define_uniq_tagged_files); \
test -z "$(CTAGS_ARGS)$$unique" \
|| $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \
$$unique
GTAGS:
here=`$(am__cd) $(top_builddir) && pwd` \
&& $(am__cd) $(top_srcdir) \
&& gtags -i $(GTAGS_ARGS) "$$here"
cscopelist: cscopelist-recursive
cscopelist-am: $(am__tagged_files)
list='$(am__tagged_files)'; \
case "$(srcdir)" in \
[\\/]* | ?:[\\/]*) sdir="$(srcdir)" ;; \
*) sdir=$(subdir)/$(srcdir) ;; \
esac; \
for i in $$list; do \
if test -f "$$i"; then \
echo "$(subdir)/$$i"; \
else \
echo "$$sdir/$$i"; \
fi; \
done >> $(top_builddir)/cscope.files
distclean-tags:
-rm -f TAGS ID GTAGS GRTAGS GSYMS GPATH tags
distdir: $(DISTFILES)
@srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
list='$(DISTFILES)'; \
dist_files=`for file in $$list; do echo $$file; done | \
sed -e "s|^$$srcdirstrip/||;t" \
-e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
case $$dist_files in \
*/*) $(MKDIR_P) `echo "$$dist_files" | \
sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
sort -u` ;; \
esac; \
for file in $$dist_files; do \
if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
if test -d $$d/$$file; then \
dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
if test -d "$(distdir)/$$file"; then \
find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
fi; \
if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \
find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
fi; \
cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \
else \
test -f "$(distdir)/$$file" \
|| cp -p $$d/$$file "$(distdir)/$$file" \
|| exit 1; \
fi; \
done
@list='$(DIST_SUBDIRS)'; for subdir in $$list; do \
if test "$$subdir" = .; then :; else \
$(am__make_dryrun) \
|| test -d "$(distdir)/$$subdir" \
|| $(MKDIR_P) "$(distdir)/$$subdir" \
|| exit 1; \
dir1=$$subdir; dir2="$(distdir)/$$subdir"; \
$(am__relativize); \
new_distdir=$$reldir; \
dir1=$$subdir; dir2="$(top_distdir)"; \
$(am__relativize); \
new_top_distdir=$$reldir; \
echo " (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) top_distdir="$$new_top_distdir" distdir="$$new_distdir" \\"; \
echo " am__remove_distdir=: am__skip_length_check=: am__skip_mode_fix=: distdir)"; \
($(am__cd) $$subdir && \
$(MAKE) $(AM_MAKEFLAGS) \
top_distdir="$$new_top_distdir" \
distdir="$$new_distdir" \
am__remove_distdir=: \
am__skip_length_check=: \
am__skip_mode_fix=: \
distdir) \
|| exit 1; \
fi; \
done
check-am: all-am
check: check-recursive
all-am: Makefile
installdirs: installdirs-recursive
installdirs-am:
install: install-recursive
install-exec: install-exec-recursive
install-data: install-data-recursive
uninstall: uninstall-recursive
install-am: all-am
@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
installcheck: installcheck-recursive
install-strip:
if test -z '$(STRIP)'; then \
$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
install; \
else \
$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
"INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \
fi
mostlyclean-generic:
clean-generic:
distclean-generic:
-test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
-test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES)
maintainer-clean-generic:
@echo "This command is intended for maintainers to use"
@echo "it deletes files that may require special tools to rebuild."
clean: clean-recursive
clean-am: clean-generic clean-libtool mostlyclean-am
distclean: distclean-recursive
-rm -f Makefile
distclean-am: clean-am distclean-generic distclean-tags
dvi: dvi-recursive
dvi-am:
html: html-recursive
html-am:
info: info-recursive
info-am:
install-data-am:
install-dvi: install-dvi-recursive
install-dvi-am:
install-exec-am:
install-html: install-html-recursive
install-html-am:
install-info: install-info-recursive
install-info-am:
install-man:
install-pdf: install-pdf-recursive
install-pdf-am:
install-ps: install-ps-recursive
install-ps-am:
installcheck-am:
maintainer-clean: maintainer-clean-recursive
-rm -f Makefile
maintainer-clean-am: distclean-am maintainer-clean-generic
mostlyclean: mostlyclean-recursive
mostlyclean-am: mostlyclean-generic mostlyclean-libtool
pdf: pdf-recursive
pdf-am:
ps: ps-recursive
ps-am:
uninstall-am:
.MAKE: $(am__recursive_targets) install-am install-strip
.PHONY: $(am__recursive_targets) CTAGS GTAGS TAGS all all-am check \
check-am clean clean-generic clean-libtool cscopelist-am ctags \
ctags-am distclean distclean-generic distclean-libtool \
distclean-tags distdir dvi dvi-am html html-am info info-am \
install install-am install-data install-data-am install-dvi \
install-dvi-am install-exec install-exec-am install-html \
install-html-am install-info install-info-am install-man \
install-pdf install-pdf-am install-ps install-ps-am \
install-strip installcheck installcheck-am installdirs \
installdirs-am maintainer-clean maintainer-clean-generic \
mostlyclean mostlyclean-generic mostlyclean-libtool pdf pdf-am \
ps ps-am tags tags-am uninstall uninstall-am
.PRECIOUS: Makefile
# Tell versions [3.59,3.63) of GNU make to not export all variables.
# Otherwise a system limit (for SysV at least) may be exceeded.
.NOEXPORT:
ilddir = @builddir@
datadir = @datadir@
datarootdir = @datarootdir@
docdir = @docdir@
dvidir = @dvidir@
exec_prefix = @exec_prefix@
host = @host@
host_alias = @host_alias@
host_cpu = @host_cpu@
host_os = @host_os@
host_vlibX11-1.6.3/specs/i18n/compose/Makefile.am 0000644 0143106 0000012 00000000750 12477417235 0020455 0 ustar 00alanc staff 0000266 0200006 if ENABLE_SPECS
if HAVE_PERL
# Main DocBook/XML files (DOCTYPE book)
docbook = libX11-keys.xml
# Included chapters, appendix, images
chapters = $(locales:%=%.xml)
# The location where the DocBook/XML generated formats are installed
shelfdir = $(docdir)/i18n/compose
# Generate DocBook/XML output formats with or without stylesheets
# The XML source is generated and cleaned but not distributed
include docbook-nl.am
endif HAVE_PERL
endif ENABLE_SPECS
EXTRA_DIST = compose-chart.pl
libX11-1.6.3/specs/i18n/compose/compose-chart.pl 0000755 0143106 0000012 00000023604 12477417235 0021530 0 ustar 00alanc staff 0000266 0200006 #! /usr/bin/perl
#
# Copyright 2009, 2010, Oracle and/or its affiliates. All rights reserved.
#
# Permission is hereby granted, free of charge, to any person obtaining a
# copy of this software and associated documentation files (the "Software"),
# to deal in the Software without restriction, including without limitation
# the rights to use, copy, modify, merge, publish, distribute, sublicense,
# and/or sell copies of the Software, and to permit persons to whom the
# Software is furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice (including the next
# paragraph) shall be included in all copies or substantial portions of the
# Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
# DEALINGS IN THE SOFTWARE.
#
#
# Make a DocBook chart showing compose combinations for a locale
#
# See perldoc at end (or run with --help or --man options) for details
# of command-line options.
#
# Compose file grammar is defined in modules/im/ximcp/imLcPrs.c
use strict;
use warnings;
use Getopt::Long;
use Pod::Usage;
my $error_count = 0;
my $charset;
my $locale_name;
my $output_filename = '-';
my $man = 0;
my $help = 0;
my $make_index = 0;
GetOptions ('charset:s' => \$charset,
'locale=s' => \$locale_name,
'output=s' => \$output_filename,
'index' => \$make_index,
'help|?' => \$help,
'man' => \$man)
or pod2usage(2);
pod2usage(1) if $help;
pod2usage(-exitstatus => 0, -verbose => 2) if $man;
if (!defined($charset) || ($charset eq "")) {
if (defined($locale_name)) {
my $guessed_charset = $locale_name;
$guessed_charset =~ s{^.*\.}{};
if ($guessed_charset =~ m{^(utf-8|gbk|gb18030)$}i) {
$charset = $1;
} elsif ($guessed_charset =~ m{iso8859-(\d+)}i) {
$charset = "iso-8859-$1";
} elsif ($guessed_charset =~ m{^microsoft-cp(125\d)$}) {
$charset = "windows-$1";
}
}
if (!defined($charset) || ($charset eq "")) {
$charset = "utf-8";
}
}
if ($make_index) {
# Print Docbook output
open my $OUTPUT, '>', $output_filename
or die "Could not create $output_filename: $!";
print $OUTPUT
join ("\n",
qq(),
q(),
q(),
q( ),
q( Xlib Compose Key Charts),
q( ),
( map { qq( \
$_\
) }
@ARGV ),
q(),
"\n"
);
close $OUTPUT or die "Couldn't write $output_filename: $!";
exit(0);
}
foreach my $a (@ARGV) {
$error_count += make_compose_chart($a);
}
exit($error_count);
sub make_compose_chart {
my ($filename) = @_;
my $errors = 0;
my @compose_table = ();
my @included_files = ();
my $line = 0;
my $pre_file = ($filename =~ m{\.pre$}) ? 1 : 0;
my $in_c_comment = 0;
my $in_comment = 0;
my $keyseq_count = 0;
open my $COMPOSE, '<', $filename or die "Could not open $filename: $!";
COMPOSE_LINE:
while (my $cl = <$COMPOSE>) {
$line++;
chomp($cl);
my $original_line = $cl;
# Special handling for changes cpp makes to .pre files
if ($pre_file == 1) {
if ($in_c_comment) { # Look for end of multi-line C comment
if ($cl =~ m{\*/(.*)$}) {
$cl = $1;
$in_c_comment = 0;
} else {
next;
}
}
$cl =~ s{/\*.\**/}{}; # Remove single line C comments
if ($cl =~ m{^(.*)/\*}) { # Start of a multi-line C comment
$cl = $1;
$in_c_comment = 1;
}
$cl =~ s{^\s*XCOMM}{#}; # Translate pre-processing comments
}
chomp($cl);
if ($cl =~ m{^\s*#\s*(.*)$}) { # Comment only lines
# Combine commment blocks
my $comment = $1;
if ($in_comment) {
my $prev_comment = pop @compose_table;
$comment = join(' ', $prev_comment->{-comment}, $comment);
} else {
$in_comment = 1;
}
push @compose_table, { -type => 'comment', -comment => $comment };
next COMPOSE_LINE;
}
$in_comment = 0;
if ($cl =~ m{^\s*$}) { # Skip blank lines
next COMPOSE_LINE;
}
elsif ($cl =~ m{^(STATE\s+|END_STATE)}) {
# Sun extension to compose file syntax
next COMPOSE_LINE;
}
elsif ($cl =~ m{^([^:]+)\s*:\s*(.+)$}) {
my ($seq, $action) = ($1, $2);
$seq =~ s{\s+$}{};
my @keys = grep { $_ !~ m/^\s*$/ } split /[\s\<\>]+/, $seq;
push @compose_table, {
-type => 'keyseq',
-keys => [ @keys ],
-action => $action
};
$keyseq_count++;
next COMPOSE_LINE;
} elsif ($cl =~ m{^(STATE_TYPE:|\@StartDeadKeyMap|\@EndDeadKeyMap)}) {
# ignore
next COMPOSE_LINE;
} elsif ($cl =~ m{^include "(.*)"}) {
my $incpath = $1;
$incpath =~ s{^X11_LOCALEDATADIR/(.*)/Compose}{the $1 compose table};
push @included_files, $incpath;
next COMPOSE_LINE;
} else {
print STDERR ('Unrecognized pattern in ', $filename,
' on line #', $line, ":\n ", $cl, "\n");
}
}
close $COMPOSE;
if ($errors > 0) {
return $errors;
}
# Print Docbook output
open my $OUTPUT, '>', $output_filename
or die "Could not create $output_filename: $!";
print $OUTPUT
join ("\n",
qq(),
q(),
qq(),
qq(Xlib Compose Keys for $locale_name),
q(Applications using Xlib input handling should recognize),
q( these compose key sequences in locales using the),
qq( $locale_name compose table.),
"\n"
);
if (@included_files) {
print $OUTPUT
q(This compose table includes the non-conflicting),
q( entries from: ),
join(',', @included_files),
q(. Those entries are not shown here - see those charts for the),
q( included key sequences.),
"\n";
}
my @pretable_comments = ();
if ($keyseq_count == 0) {
@pretable_comments = @compose_table;
} elsif ($compose_table[0]->{-type} eq 'comment') {
push @pretable_comments, shift @compose_table;
}
foreach my $comment_ref (@pretable_comments) {
print $OUTPUT
qq(), xml_escape($comment_ref->{-comment}), qq(\n);
}
if ($keyseq_count > 0) {
start_table($OUTPUT);
my $row_count = 0;
foreach my $cr (@compose_table) {
if ($row_count++ > 750) {
# Break tables every 750 rows to avoid overflowing
# xmlto/xsltproc limits on the largest tables
end_table($OUTPUT);
start_table($OUTPUT);
$row_count = 0;
}
if ($cr->{-type} eq 'comment') {
print $OUTPUT
qq(),
xml_escape($cr->{-comment}), qq(\n);
} elsif ($cr->{-type} eq 'keyseq') {
my $action = join(" ", xml_escape($cr->{-action}));
if ($action =~ m{^\s*"\\([0-7]+)"}) {
my $char = oct($1);
if ($char >= 32) {
$action =~ s{^\s*"\\[0-7]+"}{"&#$char;"};
}
}
$action =~ s{^\s*"(.+)"}{"$1"};
print $OUTPUT
qq(),
qq(),
(map { qq($_) } xml_escape(@{$cr->{-keys}})),
qq(),
qq(),
$action,
qq(\n);
}
}
end_table($OUTPUT);
} else {
print $OUTPUT
qq(),
qq(This compose table defines no sequences of its own.),
qq(\n);
}
print $OUTPUT "\n";
close $OUTPUT or die "Couldn't write $output_filename: $!";
return $errors;
}
sub xml_escape {
my @output;
foreach my $l (@_) {
$l =~ s{\&}{&}g;
$l =~ s{\<}{<}g;
$l =~ s{\>}{>}g;
push @output, $l;
}
return @output;
}
sub start_table {
my ($OUTPUT) = @_;
print $OUTPUT
join("\n",
qq(
Compose Key Sequences for $locale_name),
qq(),
qq( ),
qq( ),
qq( Key SequenceAction),
qq( ),
qq( \n),
);
}
sub end_table {
my ($OUTPUT) = @_;
print $OUTPUT "\n\n
\n";
}
__END__
=head1 NAME
compose-chart - Make DocBook/XML charts of compose table entries
=head1 SYNOPSIS
compose-chart [options] [file ...]
Options:
--charset[=] character set to specify in XML doctype
--locale= name of locale to display in chart
--output= filename to output chart to
--index make index of charts instead of individual chart
--help brief help message
--man full documentation
=head1 OPTIONS
=over 8
=item B<--charset>[=I]
Specify a character set to list in the doctype declaration in the XML output.
If not specified, attempts to guess from the locale name, else default to
"utf-8".
=item B<--locale>=I
Specify the locale name to use in the chart titles and introductory text.
=item B<--output>=I
Specify the output file to write the DocBook output to.
=item B<--index>
Generate an index of the listed locale charts instead of a chart for a
specific locale.
=item B<--help>
Print a brief help message and exit.
=item B<--man>
Print the manual page and exit.
=back
=head1 DESCRIPTION
This program will read the given compose table file(s) and generate
DocBook/XML charts listing the available characters for end-user reference.
=cut
libX11-1.6.3/specs/i18n/compose/Makefile.in 0000644 0143106 0000012 00000064541 12477417255 0020500 0 ustar 00alanc staff 0000266 0200006 # Makefile.in generated by automake 1.15 from Makefile.am.
# @configure_input@
# Copyright (C) 1994-2014 Free Software Foundation, Inc.
# This Makefile.in is free software; the Free Software Foundation
# gives unlimited permission to copy and/or distribute it,
# with or without modifications, as long as this notice is preserved.
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
# PARTICULAR PURPOSE.
@SET_MAKE@
#
# Generate output formats for a single DocBook/XML with/without chapters
#
# This version of docbook.am handles cases where XML source is generated
# and the html to be produced must be in chunks, one per chapter.
# The generated source must be cleaned, installed but not distributed
#
# Variables set by the calling Makefile:
# shelfdir: the location where the docs/specs are installed. Typically $(docdir)
# docbook: the main DocBook/XML file, no chapters, appendix or image files
# chapters: all files pulled in by an XInclude statement and images.
#
#
# This makefile is intended for Users Documentation and Functional Specifications.
# Do not use for Developer Documentation which is not installed and does not require olink.
# Refer to http://www.x.org/releases/X11R7.6/doc/xorg-docs/ReleaseNotes.html#id2584393
# for an explanation on documents classification.
#
VPATH = @srcdir@
am__is_gnu_make = { \
if test -z '$(MAKELEVEL)'; then \
false; \
elif test -n '$(MAKE_HOST)'; then \
true; \
elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \
true; \
else \
false; \
fi; \
}
am__make_running_with_option = \
case $${target_option-} in \
?) ;; \
*) echo "am__make_running_with_option: internal error: invalid" \
"target option '$${target_option-}' specified" >&2; \
exit 1;; \
esac; \
has_opt=no; \
sane_makeflags=$$MAKEFLAGS; \
if $(am__is_gnu_make); then \
sane_makeflags=$$MFLAGS; \
else \
case $$MAKEFLAGS in \
*\\[\ \ ]*) \
bs=\\; \
sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \
| sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \
esac; \
fi; \
skip_next=no; \
strip_trailopt () \
{ \
flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \
}; \
for flg in $$sane_makeflags; do \
test $$skip_next = yes && { skip_next=no; continue; }; \
case $$flg in \
*=*|--*) continue;; \
-*I) strip_trailopt 'I'; skip_next=yes;; \
-*I?*) strip_trailopt 'I';; \
-*O) strip_trailopt 'O'; skip_next=yes;; \
-*O?*) strip_trailopt 'O';; \
-*l) strip_trailopt 'l'; skip_next=yes;; \
-*l?*) strip_trailopt 'l';; \
-[dEDm]) skip_next=yes;; \
-[JT]) skip_next=yes;; \
esac; \
case $$flg in \
*$$target_option*) has_opt=yes; break;; \
esac; \
done; \
test $$has_opt = yes
am__make_dryrun = (target_option=n; $(am__make_running_with_option))
am__make_keepgoing = (target_option=k; $(am__make_running_with_option))
pkgdatadir = $(datadir)/@PACKAGE@
pkgincludedir = $(includedir)/@PACKAGE@
pkglibdir = $(libdir)/@PACKAGE@
pkglibexecdir = $(libexecdir)/@PACKAGE@
am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
install_sh_DATA = $(install_sh) -c -m 644
install_sh_PROGRAM = $(install_sh) -c
install_sh_SCRIPT = $(install_sh) -c
INSTALL_HEADER = $(INSTALL_DATA)
transform = $(program_transform_name)
NORMAL_INSTALL = :
PRE_INSTALL = :
POST_INSTALL = :
NORMAL_UNINSTALL = :
PRE_UNINSTALL = :
POST_UNINSTALL = :
build_triplet = @build@
host_triplet = @host@
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@am__append_1 = $(docbook:.xml=.html) $(chapters:.xml=.html)
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TEXT_TRUE@@HAVE_XMLTO_TRUE@am__append_2 = $(docbook:.xml=.txt)
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@am__append_3 = $(docbook:.xml=.pdf) \
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(docbook:.xml=.ps)
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@am__append_4 = $(docbook:.xml=.html.db) \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(docbook:.xml=.pdf.db)
subdir = specs/i18n/compose
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
am__aclocal_m4_deps = $(top_srcdir)/m4/ax_define_dir.m4 \
$(top_srcdir)/configure.ac
am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
$(ACLOCAL_M4)
DIST_COMMON = $(srcdir)/Makefile.am $(am__DIST_COMMON)
mkinstalldirs = $(install_sh) -d
CONFIG_HEADER = $(top_builddir)/src/config.h \
$(top_builddir)/include/X11/XlibConf.h
CONFIG_CLEAN_FILES =
CONFIG_CLEAN_VPATH_FILES =
AM_V_P = $(am__v_P_@AM_V@)
am__v_P_ = $(am__v_P_@AM_DEFAULT_V@)
am__v_P_0 = false
am__v_P_1 = :
AM_V_GEN = $(am__v_GEN_@AM_V@)
am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@)
am__v_GEN_0 = @echo " GEN " $@;
am__v_GEN_1 =
AM_V_at = $(am__v_at_@AM_V@)
am__v_at_ = $(am__v_at_@AM_DEFAULT_V@)
am__v_at_0 = @
am__v_at_1 =
SOURCES =
DIST_SOURCES =
am__can_run_installinfo = \
case $$AM_UPDATE_INFO_DIR in \
n|no|NO) false;; \
*) (install-info --version) >/dev/null 2>&1;; \
esac
am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`;
am__vpath_adj = case $$p in \
$(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \
*) f=$$p;; \
esac;
am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`;
am__install_max = 40
am__nobase_strip_setup = \
srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'`
am__nobase_strip = \
for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||"
am__nobase_list = $(am__nobase_strip_setup); \
for p in $$list; do echo "$$p $$p"; done | \
sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \
$(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \
if (++n[$$2] == $(am__install_max)) \
{ print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \
END { for (dir in files) print dir, files[dir] }'
am__base_list = \
sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \
sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g'
am__uninstall_files_from_dir = { \
test -z "$$files" \
|| { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \
|| { echo " ( cd '$$dir' && rm -f" $$files ")"; \
$(am__cd) "$$dir" && rm -f $$files; }; \
}
am__installdirs = "$(DESTDIR)$(shelfdir)"
DATA = $(shelf_DATA)
am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
am__DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/docbook-nl.am
DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
ACLOCAL = @ACLOCAL@
ADMIN_MAN_DIR = @ADMIN_MAN_DIR@
ADMIN_MAN_SUFFIX = @ADMIN_MAN_SUFFIX@
AMTAR = @AMTAR@
AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@
APP_MAN_DIR = @APP_MAN_DIR@
APP_MAN_SUFFIX = @APP_MAN_SUFFIX@
AR = @AR@
AUTOCONF = @AUTOCONF@
AUTOHEADER = @AUTOHEADER@
AUTOMAKE = @AUTOMAKE@
AWK = @AWK@
BASE_CFLAGS = @BASE_CFLAGS@
BIGFONT_CFLAGS = @BIGFONT_CFLAGS@
BIGFONT_LIBS = @BIGFONT_LIBS@
CC = @CC@
CCDEPMODE = @CCDEPMODE@
CC_FOR_BUILD = @CC_FOR_BUILD@
CFLAGS = @CFLAGS@
CFLAGS_FOR_BUILD = @CFLAGS_FOR_BUILD@
CHANGELOG_CMD = @CHANGELOG_CMD@
CPP = @CPP@
CPPFLAGS = @CPPFLAGS@
CPPFLAGS_FOR_BUILD = @CPPFLAGS_FOR_BUILD@
CWARNFLAGS = @CWARNFLAGS@
CYGPATH_W = @CYGPATH_W@
DEFS = @DEFS@
DEPDIR = @DEPDIR@
DLLTOOL = @DLLTOOL@
DRIVER_MAN_DIR = @DRIVER_MAN_DIR@
DRIVER_MAN_SUFFIX = @DRIVER_MAN_SUFFIX@
DSYMUTIL = @DSYMUTIL@
DUMPBIN = @DUMPBIN@
ECHO_C = @ECHO_C@
ECHO_N = @ECHO_N@
ECHO_T = @ECHO_T@
EGREP = @EGREP@
EXEEXT = @EXEEXT@
FGREP = @FGREP@
FILE_MAN_DIR = @FILE_MAN_DIR@
FILE_MAN_SUFFIX = @FILE_MAN_SUFFIX@
FOP = @FOP@
GREP = @GREP@
I18N_MODULE_LIBS = @I18N_MODULE_LIBS@
INSTALL = @INSTALL@
INSTALL_CMD = @INSTALL_CMD@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
INSTALL_SCRIPT = @INSTALL_SCRIPT@
INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
KEYSYMDEFS = @KEYSYMDEFS@
LAUNCHD = @LAUNCHD@
LD = @LD@
LDFLAGS = @LDFLAGS@
LDFLAGS_FOR_BUILD = @LDFLAGS_FOR_BUILD@
LIBOBJS = @LIBOBJS@
LIBS = @LIBS@
LIBTOOL = @LIBTOOL@
LIB_MAN_DIR = @LIB_MAN_DIR@
LIB_MAN_SUFFIX = @LIB_MAN_SUFFIX@
LINT = @LINT@
LINTLIB = @LINTLIB@
LINT_FLAGS = @LINT_FLAGS@
LIPO = @LIPO@
LN_S = @LN_S@
LTLIBOBJS = @LTLIBOBJS@
MAKEINFO = @MAKEINFO@
MALLOC_ZERO_CFLAGS = @MALLOC_ZERO_CFLAGS@
MANIFEST_TOOL = @MANIFEST_TOOL@
MAN_SUBSTS = @MAN_SUBSTS@
MISC_MAN_DIR = @MISC_MAN_DIR@
MISC_MAN_SUFFIX = @MISC_MAN_SUFFIX@
MKDIR_P = @MKDIR_P@
NM = @NM@
NMEDIT = @NMEDIT@
OBJDUMP = @OBJDUMP@
OBJEXT = @OBJEXT@
OTOOL = @OTOOL@
OTOOL64 = @OTOOL64@
PACKAGE = @PACKAGE@
PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
PACKAGE_NAME = @PACKAGE_NAME@
PACKAGE_STRING = @PACKAGE_STRING@
PACKAGE_TARNAME = @PACKAGE_TARNAME@
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
PERL = @PERL@
PKG_CONFIG = @PKG_CONFIG@
RANLIB = @RANLIB@
RAWCPP = @RAWCPP@
RAWCPPFLAGS = @RAWCPPFLAGS@
SED = @SED@
SET_MAKE = @SET_MAKE@
SHELL = @SHELL@
STRICT_CFLAGS = @STRICT_CFLAGS@
STRIP = @STRIP@
STYLESHEET_SRCDIR = @STYLESHEET_SRCDIR@
TRADITIONALCPPFLAGS = @TRADITIONALCPPFLAGS@
VERSION = @VERSION@
WCHAR32 = @WCHAR32@
X11_CFLAGS = @X11_CFLAGS@
X11_DATADIR = @X11_DATADIR@
X11_EXTRA_DEPS = @X11_EXTRA_DEPS@
X11_LIBDIR = @X11_LIBDIR@
X11_LIBS = @X11_LIBS@
X11_LOCALEDATADIR = @X11_LOCALEDATADIR@
X11_LOCALEDIR = @X11_LOCALEDIR@
X11_LOCALELIBDIR = @X11_LOCALELIBDIR@
XERRORDB = @XERRORDB@
XKBPROTO_REQUIRES = @XKBPROTO_REQUIRES@
XKEYSYMDB = @XKEYSYMDB@
XLOCALEDATADIR = @XLOCALEDATADIR@
XLOCALEDIR = @XLOCALEDIR@
XLOCALELIBDIR = @XLOCALELIBDIR@
XMALLOC_ZERO_CFLAGS = @XMALLOC_ZERO_CFLAGS@
XMLTO = @XMLTO@
XORG_MAN_PAGE = @XORG_MAN_PAGE@
XORG_SGML_PATH = @XORG_SGML_PATH@
XSLTPROC = @XSLTPROC@
XSL_STYLESHEET = @XSL_STYLESHEET@
XTHREADLIB = @XTHREADLIB@
XTHREAD_CFLAGS = @XTHREAD_CFLAGS@
XTMALLOC_ZERO_CFLAGS = @XTMALLOC_ZERO_CFLAGS@
abs_builddir = @abs_builddir@
abs_srcdir = @abs_srcdir@
abs_top_builddir = @abs_top_builddir@
abs_top_srcdir = @abs_top_srcdir@
ac_ct_AR = @ac_ct_AR@
ac_ct_CC = @ac_ct_CC@
ac_ct_DUMPBIN = @ac_ct_DUMPBIN@
am__include = @am__include@
am__leading_dot = @am__leading_dot@
am__quote = @am__quote@
am__tar = @am__tar@
am__untar = @am__untar@
bindir = @bindir@
build = @build@
build_alias = @build_alias@
build_cpu = @build_cpu@
build_os = @build_os@
build_vendor = @build_vendor@
builddir = @builddir@
datadir = @datadir@
datarootdir = @datarootdir@
docdir = @docdir@
dvidir = @dvidir@
exec_prefix = @exec_prefix@
host = @host@
host_alias = @host_alias@
host_cpu = @host_cpu@
host_os = @host_os@
host_vendor = @host_vendor@
htmldir = @htmldir@
includedir = @includedir@
infodir = @infodir@
install_sh = @install_sh@
libdir = @libdir@
libexecdir = @libexecdir@
localedir = @localedir@
locales = @locales@
localstatedir = @localstatedir@
mandir = @mandir@
mkdir_p = @mkdir_p@
oldincludedir = @oldincludedir@
pdfdir = @pdfdir@
prefix = @prefix@
program_transform_name = @program_transform_name@
psdir = @psdir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
sysconfdir = @sysconfdir@
target_alias = @target_alias@
top_build_prefix = @top_build_prefix@
top_builddir = @top_builddir@
top_srcdir = @top_srcdir@
# Main DocBook/XML files (DOCTYPE book)
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@docbook = libX11-keys.xml
# Included chapters, appendix, images
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@chapters = $(locales:%=%.xml)
# The location where the DocBook/XML generated formats are installed
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@shelfdir = $(docdir)/i18n/compose
# DocBook/XML generated output formats to be installed
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@shelf_DATA = $(chapters) $(docbook) \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@ $(am__append_1) \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@ $(am__append_2) \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@ $(am__append_3) \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@ $(am__append_4)
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_SEARCHPATH_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --searchpath "$(XORG_SGML_PATH)/X11" \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --searchpath "$(abs_top_builddir)"
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_HTML_OLINK_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --stringparam target.database.document=$(XORG_SGML_PATH)/X11/dbs/masterdb.html.xml \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --stringparam current.docid="$(<:.xml=)"
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_HTML_STYLESHEET_FLAGS = -x $(STYLESHEET_SRCDIR)/xorg-chunk.xsl
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_TXT_STYLESHEET_FLAGS = -x $(STYLESHEET_SRCDIR)/xorg-xhtml.xsl
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_HTML_CHUNKING_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --stringparam root.filename="$(<:.xml=)"
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_HTML_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_SEARCHPATH_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_HTML_STYLESHEET_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_HTML_CHUNKING_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_HTML_OLINK_FLAGS)
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_TXT_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_SEARCHPATH_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_TXT_STYLESHEET_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_HTML_OLINK_FLAGS)
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_FO_IMAGEPATH_FLAGS = --stringparam img.src.path=$(abs_builddir)/
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_FO_STYLESHEET_FLAGS = -x $(STYLESHEET_SRCDIR)/xorg-fo.xsl
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_PDF_OLINK_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --stringparam target.database.document=$(XORG_SGML_PATH)/X11/dbs/masterdb.pdf.xml \
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --stringparam current.docid="$(<:.xml=)"
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_FO_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_SEARCHPATH_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_FO_STYLESHEET_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_FO_IMAGEPATH_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_PDF_OLINK_FLAGS)
# Generate documents cross-reference target databases
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@XSLT_SEARCHPATH_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --path "$(XORG_SGML_PATH)/X11" \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --path "$(abs_top_builddir)"
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@XSLT_OLINK_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --stringparam targets.filename "$@" \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --stringparam collect.xref.targets "only"
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@XSLT_FO_OLINK_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --stringparam olink.base.uri "$(@:.db=)"
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@XSLT_HTML_CHUNKING_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --stringparam root.filename "$(<:.xml=)"
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@XSLT_HTML_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(XSLT_SEARCHPATH_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(XSLT_HTML_CHUNKING_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(XSLT_OLINK_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --nonet --xinclude \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(STYLESHEET_SRCDIR)/xorg-chunk.xsl
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@XSLT_PDF_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(XSLT_SEARCHPATH_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(XSLT_OLINK_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(XSLT_FO_OLINK_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --nonet --xinclude \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(STYLESHEET_SRCDIR)/xorg-fo.xsl
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@CLEANFILES = $(shelf_DATA)
# Generate DocBook/XML output formats with or without stylesheets
# The XML source is generated and cleaned but not distributed
EXTRA_DIST = compose-chart.pl
all: all-am
.SUFFIXES:
$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(srcdir)/docbook-nl.am $(am__configure_deps)
@for dep in $?; do \
case '$(am__configure_deps)' in \
*$$dep*) \
( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \
&& { if test -f $@; then exit 0; else break; fi; }; \
exit 1;; \
esac; \
done; \
echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign specs/i18n/compose/Makefile'; \
$(am__cd) $(top_srcdir) && \
$(AUTOMAKE) --foreign specs/i18n/compose/Makefile
Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
@case '$?' in \
*config.status*) \
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
*) \
echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
esac;
$(srcdir)/docbook-nl.am $(am__empty):
$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(top_srcdir)/configure: $(am__configure_deps)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(ACLOCAL_M4): $(am__aclocal_m4_deps)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(am__aclocal_m4_deps):
mostlyclean-libtool:
-rm -f *.lo
clean-libtool:
-rm -rf .libs _libs
install-shelfDATA: $(shelf_DATA)
@$(NORMAL_INSTALL)
@list='$(shelf_DATA)'; test -n "$(shelfdir)" || list=; \
if test -n "$$list"; then \
echo " $(MKDIR_P) '$(DESTDIR)$(shelfdir)'"; \
$(MKDIR_P) "$(DESTDIR)$(shelfdir)" || exit 1; \
fi; \
for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
echo "$$d$$p"; \
done | $(am__base_list) | \
while read files; do \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(shelfdir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(shelfdir)" || exit $$?; \
done
uninstall-shelfDATA:
@$(NORMAL_UNINSTALL)
@list='$(shelf_DATA)'; test -n "$(shelfdir)" || list=; \
files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \
dir='$(DESTDIR)$(shelfdir)'; $(am__uninstall_files_from_dir)
tags TAGS:
ctags CTAGS:
cscope cscopelist:
distdir: $(DISTFILES)
@srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
list='$(DISTFILES)'; \
dist_files=`for file in $$list; do echo $$file; done | \
sed -e "s|^$$srcdirstrip/||;t" \
-e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
case $$dist_files in \
*/*) $(MKDIR_P) `echo "$$dist_files" | \
sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
sort -u` ;; \
esac; \
for file in $$dist_files; do \
if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
if test -d $$d/$$file; then \
dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
if test -d "$(distdir)/$$file"; then \
find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
fi; \
if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \
find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
fi; \
cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \
else \
test -f "$(distdir)/$$file" \
|| cp -p $$d/$$file "$(distdir)/$$file" \
|| exit 1; \
fi; \
done
check-am: all-am
check: check-am
all-am: Makefile $(DATA)
installdirs:
for dir in "$(DESTDIR)$(shelfdir)"; do \
test -z "$$dir" || $(MKDIR_P) "$$dir"; \
done
install: install-am
install-exec: install-exec-am
install-data: install-data-am
uninstall: uninstall-am
install-am: all-am
@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
installcheck: installcheck-am
install-strip:
if test -z '$(STRIP)'; then \
$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
install; \
else \
$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
"INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \
fi
mostlyclean-generic:
clean-generic:
-test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)
distclean-generic:
-test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
-test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES)
maintainer-clean-generic:
@echo "This command is intended for maintainers to use"
@echo "it deletes files that may require special tools to rebuild."
clean: clean-am
clean-am: clean-generic clean-libtool mostlyclean-am
distclean: distclean-am
-rm -f Makefile
distclean-am: clean-am distclean-generic
dvi: dvi-am
dvi-am:
html: html-am
html-am:
info: info-am
info-am:
install-data-am: install-shelfDATA
install-dvi: install-dvi-am
install-dvi-am:
install-exec-am:
install-html: install-html-am
install-html-am:
install-info: install-info-am
install-info-am:
install-man:
install-pdf: install-pdf-am
install-pdf-am:
install-ps: install-ps-am
install-ps-am:
installcheck-am:
maintainer-clean: maintainer-clean-am
-rm -f Makefile
maintainer-clean-am: distclean-am maintainer-clean-generic
mostlyclean: mostlyclean-am
mostlyclean-am: mostlyclean-generic mostlyclean-libtool
pdf: pdf-am
pdf-am:
ps: ps-am
ps-am:
uninstall-am: uninstall-shelfDATA
.MAKE: install-am install-strip
.PHONY: all all-am check check-am clean clean-generic clean-libtool \
cscopelist-am ctags-am distclean distclean-generic \
distclean-libtool distdir dvi dvi-am html html-am info info-am \
install install-am install-data install-data-am install-dvi \
install-dvi-am install-exec install-exec-am install-html \
install-html-am install-info install-info-am install-man \
install-pdf install-pdf-am install-ps install-ps-am \
install-shelfDATA install-strip installcheck installcheck-am \
installdirs maintainer-clean maintainer-clean-generic \
mostlyclean mostlyclean-generic mostlyclean-libtool pdf pdf-am \
ps ps-am tags-am uninstall uninstall-am uninstall-shelfDATA
.PRECIOUS: Makefile
# Generated DocBook/XML source files using a perl script
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@%.xml: $(top_builddir)/nls/%/Compose
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@ $(AM_V_GEN)$(PERL) $(srcdir)/compose-chart.pl \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@ --locale="$(@:.xml=)" --output="$@" $<
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@libX11-keys.xml: $(locales:%=%.xml)
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@ $(AM_V_GEN)$(PERL) $(srcdir)/compose-chart.pl \
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@ --index --output="$@" $(locales)
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@%.html: %.xml $(chapters)
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(AM_V_GEN)$(XMLTO) $(XMLTO_HTML_FLAGS) xhtml $<
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TEXT_TRUE@@HAVE_XMLTO_TRUE@%.txt: %.xml $(chapters)
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TEXT_TRUE@@HAVE_XMLTO_TRUE@ $(AM_V_GEN)$(XMLTO) $(XMLTO_TXT_FLAGS) txt $<
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@%.pdf: %.xml $(chapters)
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(AM_V_GEN)$(XMLTO) $(XMLTO_FO_FLAGS) --with-fop pdf $<
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@%.ps: %.xml $(chapters)
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(AM_V_GEN)$(XMLTO) $(XMLTO_FO_FLAGS) --with-fop ps $<
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@%.html.db: %.xml $(chapters)
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(AM_V_GEN)$(XSLTPROC) $(XSLT_HTML_FLAGS) $<
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@%.pdf.db: %.xml $(chapters)
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(AM_V_GEN)$(XSLTPROC) $(XSLT_PDF_FLAGS) $<
# Tell versions [3.59,3.63) of GNU make to not export all variables.
# Otherwise a system limit (for SysV at least) may be exceeded.
.NOEXPORT:
@ENABLE_SPECS_TRUE@@HAVE_PERL_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --stringparam root.filename "$(<:.xml=)"
@ENABLE_SPECS_TRUE@@HlibX11-1.6.3/specs/i18n/compose/docbook-nl.am 0000644 0143106 0000012 00000010047 12477417235 0020767 0 ustar 00alanc staff 0000266 0200006 #
# Generate output formats for a single DocBook/XML with/without chapters
#
# This version of docbook.am handles cases where XML source is generated
# and the html to be produced must be in chunks, one per chapter.
# The generated source must be cleaned, installed but not distributed
#
# Variables set by the calling Makefile:
# shelfdir: the location where the docs/specs are installed. Typically $(docdir)
# docbook: the main DocBook/XML file, no chapters, appendix or image files
# chapters: all files pulled in by an XInclude statement and images.
#
#
# This makefile is intended for Users Documentation and Functional Specifications.
# Do not use for Developer Documentation which is not installed and does not require olink.
# Refer to http://www.x.org/releases/X11R7.6/doc/xorg-docs/ReleaseNotes.html#id2584393
# for an explanation on documents classification.
#
# DocBook/XML generated output formats to be installed
shelf_DATA = $(chapters) $(docbook)
# Generated DocBook/XML source files using a perl script
%.xml: $(top_builddir)/nls/%/Compose
$(AM_V_GEN)$(PERL) $(srcdir)/compose-chart.pl \
--locale="$(@:.xml=)" --output="$@" $<
libX11-keys.xml: $(locales:%=%.xml)
$(AM_V_GEN)$(PERL) $(srcdir)/compose-chart.pl \
--index --output="$@" $(locales)
if HAVE_XMLTO
if HAVE_STYLESHEETS
XMLTO_SEARCHPATH_FLAGS = \
--searchpath "$(XORG_SGML_PATH)/X11" \
--searchpath "$(abs_top_builddir)"
XMLTO_HTML_OLINK_FLAGS = \
--stringparam target.database.document=$(XORG_SGML_PATH)/X11/dbs/masterdb.html.xml \
--stringparam current.docid="$(<:.xml=)"
XMLTO_HTML_STYLESHEET_FLAGS = -x $(STYLESHEET_SRCDIR)/xorg-chunk.xsl
XMLTO_TXT_STYLESHEET_FLAGS = -x $(STYLESHEET_SRCDIR)/xorg-xhtml.xsl
XMLTO_HTML_CHUNKING_FLAGS = \
--stringparam root.filename="$(<:.xml=)"
XMLTO_HTML_FLAGS = \
$(XMLTO_SEARCHPATH_FLAGS) \
$(XMLTO_HTML_STYLESHEET_FLAGS) \
$(XMLTO_HTML_CHUNKING_FLAGS) \
$(XMLTO_HTML_OLINK_FLAGS)
XMLTO_TXT_FLAGS = \
$(XMLTO_SEARCHPATH_FLAGS) \
$(XMLTO_TXT_STYLESHEET_FLAGS) \
$(XMLTO_HTML_OLINK_FLAGS)
shelf_DATA += $(docbook:.xml=.html) $(chapters:.xml=.html)
%.html: %.xml $(chapters)
$(AM_V_GEN)$(XMLTO) $(XMLTO_HTML_FLAGS) xhtml $<
if HAVE_XMLTO_TEXT
shelf_DATA += $(docbook:.xml=.txt)
%.txt: %.xml $(chapters)
$(AM_V_GEN)$(XMLTO) $(XMLTO_TXT_FLAGS) txt $<
endif HAVE_XMLTO_TEXT
if HAVE_FOP
XMLTO_FO_IMAGEPATH_FLAGS = --stringparam img.src.path=$(abs_builddir)/
XMLTO_FO_STYLESHEET_FLAGS = -x $(STYLESHEET_SRCDIR)/xorg-fo.xsl
XMLTO_PDF_OLINK_FLAGS = \
--stringparam target.database.document=$(XORG_SGML_PATH)/X11/dbs/masterdb.pdf.xml \
--stringparam current.docid="$(<:.xml=)"
XMLTO_FO_FLAGS = \
$(XMLTO_SEARCHPATH_FLAGS) \
$(XMLTO_FO_STYLESHEET_FLAGS) \
$(XMLTO_FO_IMAGEPATH_FLAGS) \
$(XMLTO_PDF_OLINK_FLAGS)
shelf_DATA += $(docbook:.xml=.pdf)
%.pdf: %.xml $(chapters)
$(AM_V_GEN)$(XMLTO) $(XMLTO_FO_FLAGS) --with-fop pdf $<
shelf_DATA += $(docbook:.xml=.ps)
%.ps: %.xml $(chapters)
$(AM_V_GEN)$(XMLTO) $(XMLTO_FO_FLAGS) --with-fop ps $<
endif HAVE_FOP
# Generate documents cross-reference target databases
if HAVE_XSLTPROC
XSLT_SEARCHPATH_FLAGS = \
--path "$(XORG_SGML_PATH)/X11" \
--path "$(abs_top_builddir)"
XSLT_OLINK_FLAGS = \
--stringparam targets.filename "$@" \
--stringparam collect.xref.targets "only"
XSLT_FO_OLINK_FLAGS = \
--stringparam olink.base.uri "$(@:.db=)"
XSLT_HTML_CHUNKING_FLAGS = \
--stringparam root.filename "$(<:.xml=)"
XSLT_HTML_FLAGS = \
$(XSLT_SEARCHPATH_FLAGS) \
$(XSLT_HTML_CHUNKING_FLAGS) \
$(XSLT_OLINK_FLAGS) \
--nonet --xinclude \
$(STYLESHEET_SRCDIR)/xorg-chunk.xsl
XSLT_PDF_FLAGS = \
$(XSLT_SEARCHPATH_FLAGS) \
$(XSLT_OLINK_FLAGS) \
$(XSLT_FO_OLINK_FLAGS) \
--nonet --xinclude \
$(STYLESHEET_SRCDIR)/xorg-fo.xsl
shelf_DATA += $(docbook:.xml=.html.db)
%.html.db: %.xml $(chapters)
$(AM_V_GEN)$(XSLTPROC) $(XSLT_HTML_FLAGS) $<
shelf_DATA += $(docbook:.xml=.pdf.db)
%.pdf.db: %.xml $(chapters)
$(AM_V_GEN)$(XSLTPROC) $(XSLT_PDF_FLAGS) $<
endif HAVE_XSLTPROC
endif HAVE_STYLESHEETS
endif HAVE_XMLTO
CLEANFILES = $(shelf_DATA)
es.
#
#
# This makefile is intended for Users Documentation and Functional Specifications.
# Do not use for Developer Documentation which is not installed and does not require olink.
# Refer to http://www.x.org/releases/X11R7.6/doc/xorg-docs/ReleaseNotes.html#id2584393
# for an explanation on documents classification.
#
# DocBook/XML generated output formats to be installed
shelf_DATA = $(chapters) $(docbook)
# Generated DocBook/XML source files using a perl script
libX11-1.6.3/specs/XKB/acknowledgement.xml 0000644 0143106 0000012 00000004006 12477417235 0020510 0 ustar 00alanc staff 0000266 0200006
Acknowledgement
This document is the result of a great deal of hard work by a great
many people. Without Erik Fortune’s work as Architect of the X
Keyboard Extension and the longtime support of Silicon Graphics
Inc. there would not be a keyboard extension.
We gratefully thank Will Walker and George Sachs for their help and
expertise in providing some of the content for this document, and
Digital Equipment Corporation and Hewlett-Packard for allowing them
to participate in this project, and we are deeply indebted to IBM for
providing the funding to complete this library specification.
Most of all, we thank Gary Aitken and Amber J. Benson for their long
hours and late nights as ultimate authors of this specification, and
for serving as authors, document editors, and XKB protocol and
implementation reviewers. Their commitment to accuracy and completeness,
their attention to detail, their keen insight, and their good natures
when working under tremendous pressure are in some measure responsible
not only for the quality of this document, but for the quality of the
Keyboard extension itself.
Matt Landau
Manager, X Window System
X Consortium Inc.
X Version 11, Release 7 addendum
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; 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.
libX11-1.6.3/specs/XKB/ch15.xml 0000644 0143106 0000012 00000215616 12477417235 0016114 0 ustar 00alanc staff 0000266 0200006
Xkb Client Keyboard Mappingclient mapmapclient
The Xkb client map for a keyboard is the collection of information a client
needs to interpret key events from the keyboard. It contains a global list of
key types and an array of key symbol maps, each of which describes the symbols
bound to a key and the rules to be used to interpret those symbols.
Figure 15.1 shows the relationships between elements in the client map:
Xkb Client MapThe XkbClientMapRec StructureXkbClientMapRec
The
map
field of the complete Xkb keyboard description (see section 6.1) is a pointer
to the Xkb client map, which is of type
XkbClientMapRec:
typedef struct { /* Client Map */
unsigned char size_types; /* # occupied entries in types */
unsigned char num_types; /* # entries in types */
XkbKeyTypePtr types; /* vector of key types used by this keymap */
unsigned short size_syms; /* length of the syms array */
unsigned short num_syms; /* # entries in syms */
KeySym * syms; /* linear 2d tables of keysyms, 1 per key */
XkbSymMapPtr key_sym_map; /* 1 per keycode, maps keycode to syms */
unsigned char * modmap; /* 1 per keycode, real mods bound to key */
} XkbClientMapRec, *XkbClientMapPtr;
The following sections describe each of the elements of the
XkbClientMapRec
structure in more detail.
Key TypesXkbKeyTypeRecXkbKTMapEntryRec
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
types
field of the client map, whose total size is stored in
size_types,
and whose total number of valid entries is stored in
num_types.
Key types are defined using the following structures:
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 map, preserve
(if non-NULL) */
XkbKTMapEntryPtr map; /* vector of modifiers for each
shift level */
XkbModsPtr preserve; /* mods to preserve for
corresponding map entry */
Atom name; /* name of key type */
Atom * level_names; /* array of names of each shift level */
} XkbKeyTypeRec, *XkbKeyTypePtr;
typedef struct { /* Modifiers for a key type */
Bool active; /* True ⇒ entry active when
determining shift level */
unsigned char level; /* shift level if modifiers match mods */
XkbModsRec mods; /* mods needed for this level to be
selected */
} XkbKTMapEntryRec, *XkbKTMapEntryPtr;
The
mods
field of a key type is an
XkbModsRec
(see section 7.2) specifying the modifiers the key type uses when calculating
the shift level, and can be composed of both the core modifiers and virtual
modifiers. To set the modifiers associated with a key type, modify the
real_mods
and
vmods
fields of the
modsXkbModsRec
accordingly. The
mask
field of the
XkbModsRec
is reserved for use by Xkb and is calculated from the
real_mods
and
vmods
fields.
The
num_levels
field holds the total number of shift levels for the key type. Xkb uses
num_levels
to ensure the array of symbols bound to a key is large enough. Do not modify
num_levels
directly to change the number if shift levels for a key type. Instead, use
XkbResizeKeyType
(see section 15.2.3).
The
map
field is a vector of
XkbKTMapEntryRec
structures, with
map_count
entries, that specify the modifier combinations for each possible shift level.
Each map entry contains an
active
field, a
mods
field, and a
level
field. The
active
field determines whether the modifier combination listed in the
mods
field should be considered when determining shift level. If
active
is
False,
this
map
entry is ignored. If
active
is
True,
the
level
field of the
map
entry specifies the shift level to use when the current modifier combination
matches the combination specified in the
mods
field of the
map
entry.
Any combination of modifiers not explicitly listed somewhere in the
map
yields shift level one. In addition,
map
entries specifying unbound virtual modifiers are not considered.
Any modifiers specified in
mods
are normally
consumed
by
XkbTranslateKeyCode
(see section 12.1.3). For those rare occasions a modifier
should
be considered despite having been used to look up a symbol, key types include
an optional
preserve
field. If a
preserve
member of a key type is not
NULL,
it represents a list of modifiers where each entry corresponds directly to
one of the key type’s
map.
Each entry lists the modifiers that should
not
be consumed if the matching map entry is used to determine shift level.
Each shift level has a name and these names are held in the
level_names
array, whose length is
num_levels.
The type itself also has a name, which is held in the
name
field.
For example, consider how the server handles the following possible symbolic
description of a possible key type (note that the format used to specify
keyboard mappings in the server database is not specified by the Xkb extension,
although this format is one possible example):
Example Key TypeSymbolic DescriptionKey Type Data Structuretype "ALPHATHREE" {Xkb->map->types[i].namemodifiers = Shift+Lock+LevelThree;Xkb->map->types[i].modsmap[None]= Level1;Xkb->map->types[i].map[0]map[Lock]= Level1;Xkb->map->types[i].map[1]map[Shift]= Level2;Xkb->map->types[i].map[2]map[LevelThree]= Level3;Xkb->map->types[i].map[3]map[Shift+LevelThree]= Level3;Xkb->map->types[i].map[4]preserve[None]= None;Xkb->map->types[i].preserve[0]preserve[Lock]= Lock;Xkb->map->types[i].preserve[1]preserve[Shift]= None;Xkb->map->types[i].preserve[2]preserve[LevelThree]= None;Xkb->map->types[i].preserve[3]preserve[Shift+Level3]= None;Xkb->map->types[i].preserve[4]level_name[Level1]= "Base";Xkb->map->types[i].level_names[0]level_name[Level2]= "Caps";Xkb->map->types[i].level_names[1]level_name[Level3]= "Level3";Xkb->map->types[i].level_names[2]};
The
name
of the example key type is "ALPHATHREE," and the modifiers it pays attention
to are
Shift,
Lock,
and the virtual modifier
LevelThree.
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."
Given the combination of the
map
and
preserve
specifications, there are five
map
entries. The first map entry specifies that shift level one is to be used if
no modifiers are set. The second entry specifies the
Lock
modifier alone also yields shift level one. The third entry specifies the
Shift
modifier alone yields shift level two. The fourth and fifth entries specify
that the virtual
LevelThree
modifier alone, or in combination with the
Shift
modifier, yields shift level three.
Shift level three can be reached only if the virtual modifier
LevelThree
is bound to a real modifier (see section 16.4). If
LevelThree
is not bound to a real modifier, the
map
entries associated with it are ignored.
Because the
Lock
modifier is to be preserved for further event processing, the
preserve
list is not
NULL
and parallels the
map
list. All
preserve
entries, except for the one corresponding to the
map
entry that specifies the
Lock
modifier, do not list any modifiers. For the
map
entry that specifies the
Lock
modifier, the corresponding
preserve
list entry lists the
Lock
modifier, meaning do not consume the
Lock
modifier. In this particular case, the preserved modifier is passed to Xlib
translation functions and causes them to notice that the
Lock
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.
The Canonical Key Types
Xkb allows up to
XkbMaxKeyTypes
(255) key types to be defined, but requires at least
XkbNumRequiredTypes
(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
XkbNumRequiredTypes
entries of the
types
field of the client map and are indexed using the following constants:
XkbOneLevelIndexXkbTwoLevelIndexXkbAlphabeticIndexXkbKeypadIndexONE_LEVEL
The ONE_LEVEL key type describes groups that have only one symbol. The default
ONE_LEVEL key type has no map entries and does not pay attention to any
modifiers. A symbolic representation of this key type could look like the
following:
type "ONE_LEVEL" {
modifiers = None;
map[None]= Level1;
level_name[Level1]= "Any";
};
The description of the ONE_LEVEL key type is stored in the
types
[
XkbOneLevelIndex
] entry of the client key map.
TWO_LEVEL
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
Shift
modifier. It returns shift level two if
Shift
is set, and level one if it is not. A symbolic representation of this key type
could look like the following:
type "TWO_LEVEL" {
modifiers = Shift;
map[Shift]= Level2;
level_name[Level1]= "Base";
level_name[Level2]= "Shift";
};
The description of the TWO_LEVEL key type is stored in the
types
[
XkbTwoLevelIndex
] entry of the client key map.
ALPHABETIC
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
Shift
and
Lock
modifiers as follows:
If
Shift
and
Lock
are both set, the default ALPHABETIC type yields level one.
If
Shift
alone is set, it yields level two.
If
Lock
alone is set, it yields level one, but preserves the
Lock
modifier so Xlib notices and applies the appropriate capitalization rules. The
Xlib functions are locale-sensitive and apply different capitalization rules
for different locales.
If neither
Shift
nor
Lock
is set, it yields level one.
A symbolic representation of this key type could look like the following:
type "ALPHABETIC" {
modifiers = Shift+Lock;
map[Shift]= Level2;
preserve[Lock]= Lock;
level_name[Level1]= "Base";
level_name[Level2]= "Caps";
};
The description of the ALPHABETIC key type is stored in the
types
[
XkbAlphabeticIndex
] entry of the client key map.
KEYPAD
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
NumLock
modifier, as follows:
If
Shift
and
NumLock
are both set, the default KEYPAD type yields level one.
If
Shift
alone is set, it yields level two.
If
NumLock
alone is set, it yields level two.
If neither
Shift
nor
NumLock
is set, it yields level one.
A symbolic representation of this key type could look like the following:
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";
};
The description of the KEYPAD key type is stored in the
types
[
XkbKeypadIndex
] entry of the client key map.
Initializing the Canonical Key Types in a New Client Map
To set the definitions of the canonical key types in a client map to their
default values, use
XkbInitCanonicalKeyTypes.
XkbInitCanonicalKeyTypesStatus XkbInitCanonicalKeyTypesXkbDescPtr xkbunsigned int whichint keypadVModxkb
keyboard description containing client map to initialize
which
mask of types to initialize
keypadVMod
index of NumLock virtual modifier
XkbInitCanonicalKeyTypes
initializes the first
XkbNumRequiredTypes
key types of the keyboard specified by the
xkb
parameter to their default values. The
which
parameter specifies what canonical key types to initialize and is a bitwise
inclusive OR of the following masks:
XkbOneLevelMask,
XkbTwoLevelMask,
XkbAlphabeticMask,
and
XkbKeypadMask.
Only those canonical types specified by the
which
mask are initialized.
If
XkbKeypadMask
is set in the
which
parameter,
XkbInitCanonicalKeyTypes
looks up the
NumLock
named virtual modifier to determine which virtual modifier to use when
initializing the KEYPAD key type. If the
NumLock
virtual modifier does not exist,
XkbInitCanonicalKeyTypes
creates it.
XkbInitCanonicalKeyTypes
normally returns Success. It returns
BadAccess
if the Xkb extension has not been properly initialized, and
BadAccess
if the
xkb
parameter is not valid.
Getting Key Types from the Server
To obtain the list of available key types in the server’s keyboard mapping,
use
XkbGetKeyTypes.
XkbGetKeyTypesStatus XkbGetKeyTypesDisplay *dpyunsigned int firstunsigned int numXkbDescPtr xkbdpy
connection to X server
first
index to first type to get, 0 ⇒ 1st type
num
number of key types to be returned
xkb
keyboard description containing client map to update
XkbGetKeyTypes
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
key_sym_map
field of the client map (see section 15.3.1).XkbGetKeyTypes
queries the server for the desired types, waits for a reply, and returns the
desired types in the
xkb->map->types.
If successful, it returns Success.
XkbGetKeyTypes
returns
BadAccess
if the Xkb extension has not been properly initialized and
BadValue
if the combination of
first
and
num
results in numbers out of valid range.
Changing the Number of Levels in a Key Type
To change the number of levels in a key type, use
XkbResizeKeyType.
XkbResizeKeyTypeStatus XkbResizeKeyTypeXkbDescPtr xkbint type_ndxint map_countBool want_preserveint new_num_lvlsxkb
keyboard description containing client map to update
type_ndx
index in xkb->map->types of type to change
map_count
total # of map entries needed for the type
want_preserveTrue
⇒ list of preserved modifiers is necessary
new_num_lvls
new max # of levels for type
XkbResizeKeyType
changes the type specified by
xkb->map->types
[
type_ndx
], and reallocates the symbols and actions bound to all keys that use the type,
if necessary.
XkbResizeKeyType
updates only the local copy of the types in
xkb;
to update the server’s copy for the physical device, use
XkbSetMap
or
XkbChangeMap
after calling
XkbResizeKeyType.
The
map_count
parameter specifies the total number of map entries needed for the type, and
can be zero or greater. If
map_count
is zero,
XkbResizeKeyType
frees the existing
map
and
preserve
entries for the type if they exist and sets them to
NULL.
The
want_preserve
parameter specifies whether a
preserve
list for the key should be created. If
want_preserve
is
True,
the
preserve
list with
map_count
entries is allocated or reallocated if it already exists. Otherwise, if
want_preserve
is
False,
the
preserve
field is freed if necessary and set to
NULL.
The
new_num_lvls
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.
If
type_ndx
does not specify a legal type,
new_num_lvls
is less than 1, or the
map_count
is less than zero,
XkbResizeKeyType
returns
BadValue.
If
XkbResizeKeyType
encounters any problems with allocation, it returns
BadAlloc.
Otherwise, it returns
Success.
Copying Key Types
Use
XkbCopyKeyType
and
XkbCopyKeyTypes
to copy one or more
XkbKeyTypeRec
structures.
XkbCopyKeyTypeStatus XkbCopyKeyTypeXkbKeyTypePtr fromXkbKeyTypePtr intofrom
pointer to XkbKeyTypeRec to be copied
into
pointer to XkbKeyTypeRec to be changed
XkbCopyKeyType
copies the key type specified by
from
to the key type specified by
into.
Both must point to legal
XkbKeyTypeRec
structures. Xkb assumes
from
and
into
point to different places. As a result, overlaps can be fatal.
XkbCopyKeyType
frees any existing
map,
preserve,
and
level_names
in
into
prior to copying. If any allocation errors occur while copying
from
to
into,
XkbCopyKeyType
returns
BadAlloc.
Otherwise,
XkbCopyKeyType
copies
from
to
into
and returns
Success.
XkbCopyKeyTypesStatus XkbCopyKeyTypesXkbKeyTypePtr fromXkbKeyTypePtr intoint num_typesfrom
pointer to array of XkbKeyTypeRecs to copy
into
pointer to array of XkbKeyTypeRecs to change
num_types
number of types to copy
XkbCopyKeyTypes
copies
num_typesXkbKeyTypeRec
structures from the array specified by
from
into the array specified by
into.
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
from
and
into
parameters in
XkbCopyKeyType
apply to each entry of the
from
and
into
arrays of
XkbCopyKeyTypes.
If any allocation errors occur while copying
from
to
into,
XkbCopyKeyTypes
returns
BadAlloc.
Otherwise,
XkbCopyKeyTypes
copies
from
to
into
and returns
Success.
Key Symbol MapXkbSymMapRec
The entire list of key symbols for the keyboard mapping is held in the
syms
field of the client map. Whereas the core keyboard mapping is a
two-dimensional array of
KeySyms
whose rows are indexed by keycode, the
syms
field of Xkb is a linear list of
KeySyms
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.
The reason the
syms
field is a linear list of
KeySyms
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
KeySyms
would potentially be very large and sparse. Instead, Xkb provides a small
two-dimensional array of
KeySyms
for each key. To store all of these individual arrays, Xkb concatenates each
array together in the
syms
field of the client map.
In order to determine which
KeySyms
in the
syms
field are associated with each keycode, the client map contains an array of
key symbol mappings, held in the
key_sym_map
field. The
key_sym_map
field is an array of
XkbSymMapRec
structures indexed by keycode. The
key_sym_map
array has
min_key_code
unused entries at the start to allow direct indexing using a keycode. All
keycodes falling between the minimum and maximum legal keycodes, inclusive,
have
key_sym_map
arrays, whether or not any key actually yields that code. The
KeySymMapRec
structure is defined as follows:
#define XkbNumKbdGroups 4
#define XkbMaxKbdGroup (XkbNumKbdGroups-1)
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
syms array */
} XkbSymMapRec, *XkbSymMapPtr;
These fields are described in detail in the following sections.
Per-Key Key Type Indices
The
kt_index
array of the
XkbSymMapRec
structure contains the indices of the key types (see section 15.2) for each
possible group of symbols associated with the key. To obtain the index of a key
type or the pointer to a key type, Xkb provides the following macros, to access
the key types:
The array of key types is of fixed width and is large enough to
hold key types for the maximum legal number of groups
(XkbNumKbdGroups,
currently four); if a key has fewer than
XkbNumKbdGroups
groups, the extra key types are reported but ignored.XkbKeyTypeIndexint XkbKeyTypeIndexXkbDescPtr xkbKeyCode keycodeint groupxkb
Xkb description of interest
keycode
keycode of interest
group
group index
XkbKeyTypeIndex
computes an index into the
types
vector of the client map in
xkb
from the given
keycode
and
group
index.
XkbKeyTypeXkbKeyTypePtr XkbKeyTypeXkbDescPtr xkbKeyCode keycodeint groupxkb
Xkb description of interest
keycode
keycode of interest
group
group index
XkbKeyType
returns a pointer to the key type in the
types
vector of the client map in
xkb
corresponding to the given
keycode
and
group
index.
Per-Key Group Information
The
group_info
field of an
XkbSymMapRec
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
NoSymbol.
To obtain the number of groups of symbols bound to the key, use
XkbKeyNumGroups.
To change the number of groups bound to a key, use
XkbChangeTypesOfKey
(see section 15.3.6). To obtain a mask that determines the treatment of
out-of-range groups, use
XkbKeyGroupInfo
and
XkbOutOfRangeGroupInfo.
The keyboard controls (see ) contain a
groups_wrap
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
groups_wrap
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
group_info
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
Enter
key usually has just one group defined. If the user performs an action causing
the global keyboard group to change to
Group2,
the
group_info
field for the
Enter
key describes how to handle this situation.
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
group_info
flag, as shown in Table 15.2.
See section 10.7.1
for more details on the normalization methods in this table.
group_info Range NormalizationBits set in group_infoNormalization methodXkbRedirectIntoRangeXkbRedirectIntoRangeXkbClampIntoRangeXkbClampIntoRangenone of the aboveXkbWrapIntoRange
Xkb provides the following macros to access group information:
XkbKeyNumGroupsint XkbKeyNumGroupsXkbDescPtr xkbKeyCode keycodexkb
Xkb description of interest
keycode
keycode of interest
XkbKeyNumGroups
returns the number of groups of symbols bound to the key corresponding to
keycode.
XkbKeyGroupInfounsigned char XkbKeyGroupInfoXkbDescPtr xkbKeyCode keycodexkb
Xkb description of interest
keycode
keycode of interest
XkbKeyGroupInfo
returns the
group_info
field from the
XkbSymMapRec
structure associated with the key corresponding to
keycode.
XkbOutOfRangeGroupInfounsigned char XkbOutOfRangeGroupInfounsigned char grp_infgrp_inf
group_info field of XkbSymMapRecXkbOutOfRangeGroupInfo
returns only the out-of-range processing information from the
group_info
field of an
XkbSymMapRec
structure.
XkbOutOfRangeGroupNumberunsigned char XkbOutOfRangeGroupNumberunsigned char grp_infgrp_inf
group_info field of XkbSymMapRecXkbOutOfRangeGroupNumber
returns the out-of-range group number, represented as a group index, from the
group_info
field of an
XkbSymMapRec
structure.
Key Width
The maximum number of shift levels for a type is also referred to as the width
of a key type. The
width
field of the
key_sym_map
entry for a key contains the width of the widest type associated with the key.
The
width
field cannot be explicitly changed; it is updated automatically whenever the
symbols or set of types bound to a key are changed.
Offset in to the Symbol Map
The key width and number of groups associated with a key are used to form a
small two-dimensional array of
KeySyms
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
syms
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:
idx = group_index * key_width + shift_level
The
offset
field of the
key_sym_map
entry for a key is used to access the beginning of the array.
Xkb provides the following macros for accessing the
width
and
offset
for individual keys, as well as macros for accessing the two-dimensional array
of symbols bound to the key:
XkbKeyGroupsWidthint XkbKeyGroupsWidthXkbDescPtr xkbKeyCode keycodexkb
Xkb description of interest
keycode
keycode of interest
XkbKeyGroupsWidth
computes the maximum width associated with the key corresponding to
keycode.
XkbKeyGroupWidthint XkbKeyGroupWidthXkbDescPtr xkbKeyCode keycodeint grpxkb
Xkb description of interest
keycode
keycode of interest
grp
group of interest
XkbKeyGroupWidth
computes the width of the type associated with the group
grp
for the key corresponding to
keycode.
XkbKeySymsOffsetint XkbKeySymsOffsetXkbDescPtr xkbKeyCode keycodexkb
Xkb description of interest
keycode
keycode of interest
XkbKeySymsOffset
returns the offset of the two-dimensional array of keysyms for the key
corresponding to
keycode.
XkbKeyNumSymsint XkbKeyNumSymsXkbDescPtr xkbKeyCode keycodexkb
Xkb description of interest
keycode
keycode of interest
XkbKeyNumSyms
returns the total number of keysyms for the key corresponding to
keycode.
XkbKeySymsPtrKeySym *XkbKeySymsPtrXkbDescPtr xkbKeyCode keycodexkb
Xkb description of interest
keycode
keycode of interest
XkbKeySymsPtr
returns the pointer to the two-dimensional array of keysyms for the key
corresponding to
keycode.
XkbKeySymEntryKeySym XkbKeySymEntryXkbDescPtr xkbKeyCode keycodeint shiftint grpxkb
Xkb description of interest
keycode
keycode of interest
shift
shift level of interest
grp
group of interest
XkbKeySymEntry
returns the
KeySym
corresponding to shift level
shift
and group
grp
from the two-dimensional array of keysyms for the key corresponding to
keycodeGetting the Symbol Map for Keys from the Server
To obtain the symbols for a subset of the keys in a keyboard description, use
XkbGetKeySyms:
XkbGetKeySymsStatus XkbGetKeySymsDisplay *dpyunsigned int firstunsigned int numXkbDescPtr xkbdpy
connection to X server
first
keycode of first key to get
num
number of keycodes for which syms desired
xkb
Xkb description to be updated
XkbGetKeySyms
sends a request to the server to obtain the set of keysyms bound to
num
keys starting with the key whose keycode is
first.
It waits for a reply and returns the keysyms in the
map.syms
field of
xkb.
If successful,
XkbGetKeySyms
returns
Success.
The
xkb
parameter must be a pointer to a valid Xkb keyboard description.
If the client
map
in the
xkb
parameter has not been allocated,
XkbGetKeySyms
allocates and initializes it before obtaining the symbols.
If a compatible version of Xkb is not available in the server or the Xkb
extension has not been properly initialized,
XkbGetKeySyms
returns
BadAccess.
If
num
is less than 1 or greater than
XkbMaxKeyCount,
XkbGetKeySyms
returns
BadValue.
If any allocation errors occur,
XkbGetKeySyms
returns
BadAlloc.
Changing the Number of Groups and Types Bound to a Key
To change the number of groups and the types bound to a key, use
XkbChangeTypesOfKey.
XkbChangeTypesOfKeyStatus XkbChangeTypesOfKeyXkbDescPtr xkbint keyint n_groupsunsigned int groupsint *new_types_inXkbMapChangesPtr p_changesxkb
keyboard description to be changed
key
keycode for key of interest
n_groups
new number of groups for key
groups
mask indicating groups to change
new_types_in
indices for new groups specified in groupsp_changes
notes changes made to xkbXkbChangeTypesOfKey
reallocates the symbols and actions bound to the key, if necessary, and
initializes any new symbols or actions to
NoSymbol
or
NoAction,
as appropriate. If the
p_changes
parameter is not
NULL,
XkbChangeTypesOfKey
adds the
XkbKeySymsMask
to the
changes
field of
p_changes
and modifies the
first_key_sym
and
num_key_syms
fields of
p_changes
to include the
key
that was changed. See section 14.3.1 for more information on the
XkbMapChangesPtr
structure. If successful,
XkbChangeTypesOfKey
returns
Success.
The
n_groups
parameter specifies the new number of groups for the key. The
groups
parameter is a mask specifying the groups for which new types are supplied and
is a bitwise inclusive OR of the following masks:
XkbGroup1Mask,
XkbGroup2Mask,
XkbGroup3Mask,
and
XkbGroup4Mask.
The
new_types_in
parameter is an integer array of length
n_groups.
Each entry represents the type to use for the associated group and is an
index into
xkb->map->types.
The
new_types_in
array is indexed by group index; if
n_groups
is four and
groups
only has
XkbGroup1Mask
and
XkbGroup3Mask
set,
new_types_in
looks like this:
new_types_in[0] = type for Group1
new_types_in[1] = ignored
new_types_in[2] = type for Group3
new_types_in[3] = ignored
For convenience, Xkb provides the following constants to use as indices to the
groups:
Group Index ConstantsConstant NameValueXkbGroup1Index0XkbGroup2Index1XkbGroup3Index2XkbGroup4Index3
If the Xkb extension has not been properly initialized,
XkbChangeTypesOfKey
returns
BadAccess.
If the
xkb
parameter it not valid (that is, it is
NULL
or it does not contain a valid client map),
XkbChangeTypesOfKey
returns
BadMatch.
If the
key
is not a valid keycode,
n_groups
is greater than
XkbNumKbdGroups,
or the
groups
mask does not contain any of the valid group mask bits,
XkbChangeTypesOfKey
returns
BadValue.
If it is necessary to resize the key symbols or key actions arrays and any
allocation errors occur,
XkbChangeTypesOfKey
returns
BadAlloc.
Changing the Number of Symbols Bound to a Key
To change the number of symbols bound to a key, use
XkbResizeKeySyms.
XkbResizeKeySymsKeySym *XkbResizeKeySymsXkbDescRec *xkbint keyint neededxkb
keyboard description to be changed
key
keycode for key to modify
needed
new number of keysyms required for key
XkbResizeKeySyms
reserves the space needed for
needed
keysyms and returns a pointer to the beginning of the new array that holds the
keysyms. It adjusts the
offset
field of the
key_sym_map
entry for the key if necessary and can also change the
syms,
num_syms,
and
size_syms
fields of
xkb->map
if it is necessary to reallocate the
syms
array.
XkbResizeKeySyms
does not modify either the width or number of groups associated with the key.
If
needed
is greater than the current number of keysyms for the key,
XkbResizeKeySyms
initializes all new keysyms in the array to
NoSymbol.
Because the number of symbols needed by a key is normally computed as width *
number of groups, and
XkbResizeKeySyms
does not modify either the width or number of groups for the key, a
discrepancy exists upon return from
XkbResizeKeySyms
between the space allocated for the keysyms and the number required. The
unused entries in the list of symbols returned by
XkbResizeKeySyms
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
XkbChangeTypesOfKey
will update the mapping.
If any allocation errors occur while resizing the number of symbols bound to
the key,
XkbResizeKeySyms
returns
NULL.
A change to the number of symbols bound to a key should be
accompanied by a change in the number of actions bound to a key. Refer to
section 16.1.16 for more information on changing the number of actions bound to
a key.The Per-Key Modifier Map
The
modmap
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:
ShiftMask,
LockMask,
ControlMask,
Mod1Mask,
Mod2Mask,
Mod3Mask,
Mod4Mask,
and
Mod5Mask.
If a bit is set in a
modmap
entry, the corresponding key is bound to that modifier.
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
).
Getting the Per-Key Modifier Map from the Server
To update the modifier map for one or more of the keys in a keyboard
description, use
XkbGetKeyModifierMap.
XkbGetKeyModifierMapStatus XkbGetKeyModifierMapDisplay *dpyunsigned int firstunsigned int numXkbDescPtr xkbdpy
connection to X server
first
keycode of first key to get
num
number of keys for which information is desired
xkb
keyboard description to update
XkbGetKeyModifierMap
sends a request to the server for the modifier mappings for
num
keys starting with the key whose keycode is
first.
It waits for a reply and places the results in the
xkb->map->modmap array. If successful,
XkbGetKeyModifierMap
returns
Success.
If the map component of the
xkb
parameter has not been allocated,
XkbGetKeyModifierMap
allocates and initializes it.
If a compatible version of Xkb is not available in the server or the Xkb
extension has not been properly initialized,
XkbGetKeySyms
returns
BadAccess.
If any allocation errors occur while obtaining the modifier map,
XkbGetKeyModifierMap
returns
BadAlloc.
If successful,
XkbChangeTypesOfKey
returns
Success.
The
Interpreting Key Events
Xkb provides functions to help developers interpret key events without having
to directly interpret Xkb data structures. Xkb also modifies the behavior of
several core X library functions.
Effects of Xkb on the Core X Library
When support for Xkb is built into the X library, the
XOpenDisplay
function looks for a compatible version of Xkb on the server. If it finds a
compatible version, it initializes the extension and enables
implicit support
for Xkb in a number of X library functions. This makes it possible for clients
to take advantage of nearly all Xkb features without having to be rewritten or
even recompiled, if they are built with shared libraries. This implicit support
is invisible to most clients, but it can have side effects, so the extension
includes ways to control or disable it.
Effects of Xkb on Event State
Because
XOpenDisplay
initializes Xkb, some events contain an Xkb description of the keyboard state
instead of that normally used by the core protocol. See section 17.1.1 for more
information about the differences between Xkb keyboard state and that reported
by the core protocol.
Effects of Xkb on MappingNotify EventseventsMappingNotify
When Xkb is missing or disabled, the X library tracks changes to the keyboard
mapping using
MappingNotify
events. Whenever the keyboard mapping is changed, the server sends all clients
a
MappingNotify
event to report the change. When a client receives a
MappingNotify
event, it is supposed to call
XRefreshKeyboardMapping
to update the keyboard description used internally by the X library.
The X Keyboard Extension uses
XkbMapNotify
and
XkbNewKeyboardNotify
events to track changes to the keyboard mapping. When an Xkb-aware client
receives either event, it should call
XkbRefreshKeyboardMapping
to update the keyboard description used internally by the X library. To avoid
duplicate events, the X server does not send core protocol
MappingNotify
events to a client that has selected for
XkbMapNotify
events.
The implicit support for Xkb selects for
XkbMapNotify
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
MappingNotify
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
MappingNotify
events that report approximately the same information, unless the client has
explicitly selected for the Xkb version of the event.
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
XkbNewKeyboardNotify
event, it reports events from all keys because it assumes that any client that
has received an
XkbNewKeyboardNotify
event expects key events from the new range of keycodes. The implicit support
for Xkb asks for
XkbNewKeyboardNotify
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
XkbLC_IgnoreNewKeyboards
library control (see section 11.3.1) to prevent the implicit support from
requesting notification of changes to the legal range of keycodes.
X Library Functions Affected by Xkb
The following X library functions are modified by Xkb:
XKeycodeToKeysymXKeysymToKeycodeXLookupKeysymXLookupStringXRefreshKeyboardMappingXRebindKeysym
The implicit support for Xkb replaces a number of X library functions with
versions that understand and use the X Keyboard Extension. In most cases, the
semantics of the new versions are identical to those of the old, but there are
occasional visible differences. This section lists all of the functions that
are affected and the differences in behavior, if any, that are visible to
clients.
The
XKeycodeToKeysymXKeycodeToKeysym
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
GetKeyboardMapping
request). The order of the symbols in the core mapping does not necessarily
correspond to the order of the symbols used by Xkb; section 17.1.3 describes
the differences.
The
XKeysymToKeycodeXKeysymToKeycode
function reports a keycode to which a particular keysym is bound. When Xkb is
missing or disabled, this function looks in each column of the core keyboard
mapping in turn and returns the lowest numbered key that matches in the lowest
numbered group. When Xkb is present, this function uses the Xkb ordering for
symbols instead.
The
XLookupKeysymXLookupKeysym
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.
The
XLookupStringXLookupString
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,
XLookupString
uses the rules specified by the core protocol and reports only ISO Latin-1
characters. When Xkb is present,
XLookupString
uses the explicit keyboard group, key types, and rules specified by Xkb. When
Xkb is present,
XLookupString
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,
XLookupString
does not use any consumed modifiers (see section 11.1.2 and section 15.2) to
determine matching bindings.
The
XRefreshKeyboardMappingXRefreshKeyboardMapping
function updates the X library’s internal representation of the keyboard to
reflect changes reported via
MappingNotify
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
XkbMapNotify
event and updates only those pieces of the keyboard description that have
changed. If the implicit support has not noted any keyboard mapping changes,
XRefreshKeyboardMapping
updates the entire keyboard description.
The
XRebindKeysymXRebindKeysym
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
XRebindKeysym.
When Xkb is missing or disabled,
XLookupString
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.
Xkb Event and Keymap Functions
To find the keysym bound to a particular key at a specified group and shift
level, use XkbKeycodeToKeysym.
XkbKeycodeToKeysymKeySym XkbKeycodeToKeysymDisplay *dpyKeyCode kcunsigned int groupunsigned int leveldpy
connection to X server
kc
key of interest
group
group of interest
level
shift level of interest
XkbKeycodeToKeysym
returns the keysym bound to a particular group and shift level for a
particular key on the core keyboard. If
kc
is not a legal keycode for the core keyboard, or if
group
or
level
are out of range for the specified key,
XkbKeycodeToKeysym
returns
NoSymbol.
To find the set of modifiers bound to a particular keysym on the core keyboard,
use
XkbKeysymToModifiers.
XkbKeysymToModifiersunsigned int XkbKeysymToModifiersDisplay *dpyKeySym ksdpy
connection to X server
ks
keysym of interest
XkbKeysymToModifiers
finds the set of modifiers currently bound to the keysym
ks
on the core keyboard. The value returned is the mask of modifiers bound to the
keysym
ks.
If no modifiers are bound to the keysym,
XkbKeysymToModifiers
returns zero; otherwise, it returns the inclusive OR of zero or more of the
following:
ShiftMask,
ControlMask,
LockMask,
Mod1Mask,
Mod2Mask,
Mod3Mask,
Mod4Mask,
and
Mod5Mask.
Use
XkbLookupKeySym
to find the symbol associated with a key for a particular state.
XkbLookupKeySymBool XkbLookupKeySymDisplay *dpyKeyCode keyunsigned int stateunsigned int *mods_rtrnKeySym *sym_rtrndpy
connection to X server
key
key for which symbols are to be found
state
state for which symbol should be found
mods_rtrn
backfilled with consumed modifiers
sym_rtrn
backfilled with symbol associated with key + state
XkbLookupKeySym
is the equivalent of the core
XLookupKeySym
function. For the core keyboard, given a keycode
key
and an Xkb state
state,
XkbLookupKeySym
returns the symbol associated with the key in
sym_rtrn
and the list of modifiers that should still be applied in
mods_rtrn.
The
state
parameter is the state from a
KeyPress
or
KeyRelease
event.
XkbLookupKeySym
returns
True
if it succeeds.
Use
XkbLookupKeyBinding
to find the string bound to a key by
XRebindKeysym.
XkbLookupKeyBinding
is the equivalent of the core
XLookupString
function.
XkbLookupKeyBindingint XkbLookupKeyBindingDisplay *dpyKeySym symunsigned int statechar *bufint nbytesint *extra_rtrndpy
connection to server
sym
symbol to be looked up
state
state for which string is to be looked up
buf
buffer into which returned string is written
nbytes
size of buffer in bytes
extra_rtrn
backfilled with number bytes overflow
XRebindKeysym
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.
XkbLookupKeyBinding
returns in
buf
the string associated with the keysym
sym
and modifier state
state.
buf
is
NULL
terminated unless there’s an overflow. If the string returned is larger than
nbytes,
a count of bytes that does not fit into the buffer is returned in extra_rtrn.
XkbTranslateKeySym
returns the number of bytes that it placed into
buf.
To find the string and symbol associated with a keysym for a given keyboard
state, use
XkbTranslateKeySym.
XkbTranslateKeySymint XkbTranslateKeySymDisplay *dpyKeySym *sym_inoutunsigned int modschar *bufint nbytesint *extra_rtrndpy
connection to X server
sym_inout
symbol to be translated; result of translation
mods
modifiers to apply to sym_inoutbuf
buffer into which returned string is written
nbytes
size of buffer in bytes
extra_rtrn
number of bytes overflow
XkbTranslateKeySym
applies the transformations specified in
mods
to the symbol specified by
sym_inout.
It returns in
buf
the string, if any, associated with the keysym for the current locale. If the
transformations in
mods
changes the keysym,
sym_inout
is updated accordingly. If the string returned is larger than
nbytes,
a count of bytes that does not fit into the buffer is returned in extra_rtrn.
XkbTranslateKeySym
returns the number of bytes it placed into
buf.
To update the keyboard description that is internal to the X library, use
XkbRefreshKeyboardMapping.
XkbRefreshKeyboardMappingStatus XkbRefreshKeyboardMappingXkbMapNotifyEvent *eventevent
event initiating remapping
XkbRefreshKeyboardMapping
is the Xkb equivalent of the core
XRefreshKeyboardMapping
function. It requests that the X server send the current key mapping
information to this client. A client usually invokes
XkbRefreshKeyboardMapping
after receiving an
XkbMapNotify
event.
XkbRefreshKeyboardMapping
returns
Success
if it succeeds and
BadMatch
if the event is not an Xkb event.
The
XkbMapNotify
event can be generated when some client calls
XkbSetMap,
XkbChangeMap,
XkbGetKeyboardByName,
or any of the standard X library functions that change the keyboard mapping
or modifier mapping.
To translate a keycode to a key symbol and modifiers, use
XkbTranslateKeyCode.
XkbTranslateKeyCodeBool XkbTranslateKeyCodeXkbDescPtr xkbKeyCode keyunsigned int modsunsigned int *mods_rtrnKeySym *keysym_rtrnxkb
keyboard description to use for translation
key
keycode to translate
mods
modifiers to apply when translating keymods_rtrn
backfilled with consumed modifiers
keysym_rtrn
keysym resulting from translation
mods_rtrn
is backfilled with the modifiers consumed by the translation process.
mods
is a bitwise inclusive OR of the legal modifier masks:
ShiftMask,
LockMask,
ControlMask,
Mod1Mask,
Mod2Mask,
Mod3Mask,
Mod4Mask,
Mod5Mask.
The
AlwaysConsumeShiftAndLock
library control (see section 11.1.3), if enabled, causes
XkbTranslateKeyCode
to consume shift and lock.
XkbTranslateKeyCode
returns
True
if the translation resulted in a keysym, and
False
if it resulted in
NoSymbol.
ind the string bound to a key by
XRebindKeysym.
XkbLookupKeyBinding
is the equivalent of the core
XLookupString
function.
XkbLookupKeyBindingServer Database of Keyboard Components
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.
Server Database Keyboard ComponentsComponent TypeComponent Primary ContentsMay also containKeymapComplete keyboard descriptionNormally assembled using a complete component from each of the other typesKeycodesSymbolic name for each keyMinimum and maximum legal keycodesAliases for some keysSymbolic names for indicatorsDescription of indicators physically presentTypesKey types
Real modifier bindings and symbolic names for some virtual modifiers
CompatibilityRules used to assign actions to keysymsMaps for some indicatorsReal modifier bindings and symbolic names for some virtual modifiersSymbolsSymbol mapping for keyboard keysModifier mappingSymbolic names for groupsExplicit actions and behaviors for some keysReal modifier bindings and symbolic names for some virtual modifiersGeometryLayout of the keyboardAliases for some keys; overrides keycodes component aliasesSymbolic names for some indicatorsDescription of indicators physically present
While a keymap is a database entry for a complete keyboard description, and
therefore logically different from the individual component database entries,
the rules for processing keymap entries are identical to those for the
individual components. In the discussion that follows, the term component is
used to refer to either individual components or a keymap.
There may be multiple entries for each of the component types. An entry may be
either
complete
or
partial.
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.
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
any
ASCII keyboard to use a national layout.
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.
Component Names
Component names have the form “class(member)” where
class
describes a subset of the available components for a particular type and the
optional
member
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
default
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.
The
class
and
member
names are both specified using characters from the Latin-1 character set. Xkb
implementations must accept all alphanumeric characters, minus (‘-’) and
underscore (‘_’) in class or member names, and must not accept parentheses,
plus, vertical bar, percent sign, asterisk, question mark, or white space. The
use of other characters is implementation-dependent.
Listing the Known Keyboard Components
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
XkbListComponents.
XkbListComponentsXkbComponentListPtr XkbListComponentsDisplay *dpyunsigned int device_specXkbComponentNamesPtr ptrnsint *max_inoutdpy
connection to X server
device_spec
device ID, or XkbUseCoreKbdptrns
namelist for components of interest
max_inout
max # returned names, # left over
XkbListComponents
queries the server for a list of component names matching the patterns
specified in
ptrns.
It waits for a reply and returns the matching component names in an
XkbComponentListRec
structure. When you are done using the structure, you should free it using
XkbFreeComponentList.
device_spec
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.
ptrns
is a pointer to an
XkbComponentNamesRec,
described below. Each of the fields in
ptrns
contains a pattern naming the components of interest. Each of the patterns is
composed of characters from the ISO
Latin1
encoding, but can contain only parentheses, the wildcard characters
‘?’ and ‘*’,
and characters permitted in a component class or member name
(see section 20.1). A pattern may be
NULL,
in which case no components for that type is returned. Pattern matches with
component names are case sensitive. The
‘?’
wildcard matches any single character, except a left or right parenthesis;
the ‘*’
wildcard matches any number of characters, except a left or right
parenthesis. If an implementation allows additional characters in a component
class or member name other than those required by the Xkb extension (see
section 20.1), the result of comparing one of the additional characters to
either of the wildcard characters is implementation-dependent.
If a pattern contains illegal characters, the illegal characters are ignored.
The matching process is carried out as if the illegal characters were omitted
from the pattern.
max_inout
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
XkbListComponents,
max_inout
contains the number of names that matched the request but were not returned
because of the limit.
XkbComponentNamesRec
The component name patterns used to describe the request are passed to
XkbListComponents
using an
XkbComponentNamesRec
structure. This structure has no special allocation constraints or
interrelationships with other structures; allocate and free this structure
using standard
malloc
and
free
calls or their equivalent:
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 */
} XkbComponentNamesRec, *XkbComponentNamesPtr;
XkbComponentListRecXkbComponentNameRecXkbListComponents
returns a pointer to an
XkbComponentListRec:
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 */
} XkbComponentListRec, *XkbComponentListPtr;
typedef struct _XkbComponentName {
unsigned short flags; /* hints regarding component name */
char * name; /* name of component */
} XkbComponentNameRec, *XkbComponentNamePtr;
Note that the structure used to specify patterns on input is an
XkbComponentNamesRec,
and that used to hold the individual component names upon return is an
XkbComponentNameRec
(no trailing ‘s’ in Name).
When you are done using the structure returned by
XkbListComponents,
free it using
XkbFreeComponentList.
XkbFreeComponentListvoid XkbFreeComponentListXkbComponentListPtr listlist
pointer to XkbComponentListRec to free
Component Hints
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
XkbComponentNameRec
structures contained in the
XkbComponentListRec
returned from
XkbListComponents.
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
XkbLC_Partial
also set); full symbols components are assumed to specify all of the pieces.
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
XkbLC_AlphanumericKeys
hint. In general, symbols components should set only one of the four flags
(
XkbLC_AlternateGroup
may be combined with any of the other flags).
XkbComponentNameRec Flags BitsComponent TypeComponent Hints (flags)MeaningValueAll ComponentsXkbLC_HiddenDo not present to user(1L<<0)XkbLC_DefaultDefault member of class(1L<<1)XkbLC_PartialPartial component(1L<<2)KeymapnoneKeycodesnoneTypesnoneCompatibilitynoneSymbolsXkbLC_AlphanumericKeysBindings primarily for alphanumeric keyboard section(1L<<8)XkbLC_ModifierKeysBindings primarily for modifier keys(1L<<9)XkbLC_KeypadKeysBindings primarily for numeric keypad keys(1L<<10)XkbLC_FunctionKeysBindings primarily for function keys(1L<<11)XkbLC_AlternateGroupBindings for an alternate group(1L<<12)Geometrynone
Building a Keyboard Description Using the Server Database
A client may request that the server fetch one or more components from its
database and use those components to build a new server keyboard description.
The new keyboard description may be built from scratch, or it may be built
starting with the current keyboard description for a particular device. Once
the keyboard description is built, all or part of it may be returned to the
client. The parts returned to the client need not include all of the parts used
to build the description. At the time it requests the server to build a new
keyboard description, a client may also request that the server use the new
description internally to replace the current keyboard description for a
specific device, in which case the behavior of the device changes accordingly.
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
XkbGetKeyboardByName.
XkbGetKeyboardByNameXkbDescPtr XkbGetKeyboardByNameDisplay *dpyunsigned int device_specXkbComponentNamesPtr namesunsigned int wantunsigned int needBool loaddpy
connection to X server
device_spec
device ID, or XkbUseCoreKbdnames
names of components to fetch
want
desired structures in returned record
need
mandatory structures in returned record
loadTrue ⇒ load into device_specnames
contains a set of expressions describing the keyboard components the server
should use to build the new keyboard description.
want
and
need
are bit fields describing the parts of the resulting keyboard description that
should be present in the returned
XkbDescRec.
The individual fields in
names
are
component expressions
composed of keyboard component names (no wildcarding as may be used in
XkbListComponents),
the special component name symbol ‘%’,
and the special operator characters
‘+’ and ‘|’.
A component expression is parsed left to right, as follows:
The special component name “computed”
may be used in
keycodes
component expressions and refers to a component consisting of a set of
keycodes computed automatically by the server as needed.
The special component name “canonical” may be used in
types
component expressions and refers to a partial component defining the four
standard key types:
ALPHABETIC,
ONE_LEVEL,
TWO_LEVEL,
and
KEYPAD.
The special component name ‘%’
refers to the keyboard description for the device specified in
device_spec
or the keymap names component. If a keymap names component is specified that
does not begin with
‘+’ or ‘|’ and does not contain
‘%’, then ‘%’
refers to the description generated by the keymap names component.
Otherwise, it refers to the keyboard description for
device_spec.
The ‘+’
operator specifies that the following component should
override
the currently assembled description; any definitions that are present in both
components are taken from the second.
The ‘|’
operator specifies that the next specified component should
augment
the currently assembled description; any definitions that are present in both
components are taken from the first.
If the component expression begins with an operator, a leading
‘%’ is implied.
If any unknown or illegal characters appear anywhere in the expression, the
entire expression is invalid and is ignored.
For example, if
names->symbols
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)").
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
(acme(ascii)),
overrides them with definitions for the basic German keyboard
(de(basic)),
and then applies the definitions from the default iso9995-3 keyboard
(
iso9995-3)
to any undefined keys or groups of keys (part three of the iso9995 standard
defines a common set of bindings for the secondary group, but allows national
layouts to override those definitions where necessary).
The interpretation of the above expression components (acme, ascii,
de, basic, iso9995-3) is not defined by Xkb; only the operations and their
ordering are.
Note that the presence of a keymap
names
component that does not contain
‘%’
(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
device_spec.
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
‘%’.
Requests of this form allow you to deal with keyboard definitions
independent of any actual device.
The server parses all non-
NULL
fields in
names
and uses them to build a keyboard description. However, before parsing the
expressions in
names,
the server ORs the bits in
want
and
need
together and examines the result in relationship to the expressions in
names.
Table 20.3
identifies the components that are required for each of the
possible bits in
want
or
need.
If a required component has not been specified in the
names
structure (the corresponding field is
NULL),
the server substitutes the expression
“%”,
resulting in the component values being taken from
device_spec.
In addition, if
load
is
True,
the server modifies
names
if necessary (again using a
“%”
entry) to ensure all of the following fields are non-
NULL:
types,
keycodes,
symbols,
and
compat.
Want and Need Mask Bits and Required Names Componentswant or need mask bitRequired names ComponentsvalueXkbGBN_TypesMaskTypes(1L<<0)XkbGBN_CompatMapMaskCompat(1L<<1)XkbGBN_ClientSymbolsMaskTypes + Symbols + Keycodes(1L<<2)XkbGBN_ServerSymbolsMaskTypes + Symbols + Keycodes(1L<<3)XkbGBN_SymbolsMaskSymbols(1L<<1)XkbGBN_IndicatorMapMaskCompat(1L<<4)XkbGBN_KeyNamesMaskKeycodes(1L<<5)XkbGBN_GeometryMaskGeometry(1L<<6)XkbGBN_OtherNamesMaskTypes + Symbols + Keycodes + Compat + Geometry(1L<<7)XkbGBN_AllComponentsMask(0xff)
need
specifies a set of keyboard components that the server must be able to resolve
in order for
XkbGetKeyboardByName
to succeed; if any of the components specified in
need
cannot be successfully resolved,
XkbGetKeyboardByName
fails.
want
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,
XkbGetKeyboardByName
still succeeds. Bits specified in
want
that are also specified in
need
have no effect in the context of
want.
If
load
is
True,
the server updates its keyboard description for
device_spec
to match the result of the keyboard description just built. If load is
False,
the server’s description for device
device_spec
is not updated. In all cases, the parts specified by
want
and
need
from the just-built keyboard description are returned.
The
names
structure in an
XkbDescRec
keyboard description record (see ) 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
names
structure are set to match the expressions used to build the component.
The entire process of building a new keyboard description from the server
database of components and returning all or part of it is diagrammed in Figure
20.1:
Building a New Keyboard Description from the Server Database
The information returned to the client in the
XkbDescRec
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
XkbDescRec
components that are filled in.
XkbDescRec Components Returned for Values of Want & NeedsRequest (want+need)Fills in Xkb componentsEquivalent Function CallXkbGBN_TypesMaskmap.typesXkbGetUpdatedMap(dpy, XkbTypesMask, Xkb)XkbGBN_ServerSymbolsMaskserverXkbGetUpdatedMap(dpy, XkbAllClientInfoMask, Xkb)XkbGBN_ClientSymbolsMaskmap, including map.typesXkbGetUpdatedMap(dpy, XkbAllServerInfoMask, Xkb)XkbGBN_IndicatorMapsindicatorsXkbGetIndicatorMap(dpy, XkbAllIndicators, Xkb)XkbGBN_CompatMapMaskcompatXkbGetCompatMap(dpy, XkbAllCompatMask, Xkb)XkbGBN_GeometryMaskgeomXkbGetGeometry(dpy, Xkb)XkbGBN_KeyNamesMasknames.keysnames.key_aliases
XkbGetNames(dpy, XkbKeyNamesMask | XkbKeyAliasesMask, Xkb)
XkbGBN_OtherNamesMasknames.keycodesnames.geometrynames.symbolsnames.typesmap.types[*].lvl_names[*]names.compatnames.vmodsnames.indicatorsnames.groupsnames.radio_groupsnames.phys_symbolsXkbGetNames(dpy, XkbAllNamesMask &~(XkbKeyNamesMask | XkbKeyAliasesMask),Xkb)
There is no way to determine which components specified in
want
(but not in
need)
were actually fetched, other than breaking the call into successive calls to
XkbGetKeyboardByName
and specifying individual components.
XkbGetKeyboardByName
always sets
min_key_code
and
max_key_code
in the returned
XkbDescRec
structure.
XkbGetKeyboardByName
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-NULL.
XkbGetKeyboardByName
generates a BadMatch
protocol error if errors are encountered when building the keyboard
description.
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
XkbGetKeyboard
(see section 6.2).
XkbGetKeyboardXkbDescPtr XkbGetKeyboardDisplay *dpyunsigned int whichunsigned int device_specdpy
connection to X server
which
mask of components of XkbDescRec of interest
device_spec
device ID
XkbGetKeyboard
is used to read the current description for one or more components of a
keyboard device. It calls
XkbGetKeyboardByName
as follows:
XkbGetKeyboardByName
(
dpy,
device_spec,
NULL,
which,
which,
False).
r substitutes the expression
“%”,
resulting in the component values being taken from
device_spec.
In addition, if
load
is
True,
the server mlibX11-1.6.3/specs/XKB/XKBlib-19.svg 0000644 0143106 0000012 00000065253 12477417235 0016715 0 ustar 00alanc staff 0000266 0200006
125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:DejaVu Sans;-inkscape-font-specification:DejaVu Sans"
xml:space="preserve">Core libX11-1.6.3/specs/XKB/XKBlib-17.svg 0000644 0143106 0000012 00000073457 12477417235 0016720 0 ustar 00alanc staff 0000266 0200006
y="101.25849"
x="185.9855"
id="tspan3053-0-1-0"
sodipodi:role="line">vmods[1]
-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:DejaVu Sans;-inkscaplibX11-1.6.3/specs/XKB/xkblib.xml 0000644 0143106 0000012 00000011454 12477417235 0016621 0 ustar 00alanc staff 0000266 0200006
%defs;
]>
The X Keyboard Extension:Library SpecificationX Version 11, Release &fullrelvers;AmberJ.BensonGaryAitkenErikFortuneSilicon Graphics, IncDonnaConverseX Consortium, IncGeorgeSachsHewlett-Packard CompanyWillWalkerDigital Equipment Corporation19951996X Consortium Inc.Silicon Graphics Inc.Hewlett-Packard CompanyDigital Equipment Corporation
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the “Software”),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Except as contained in this notice, the names of the X Consortium, Silicon
Graphics Inc., Hewlett-Packard Company, and Digital Equipment Corporation
shall not be used in advertising or otherwise to promote the sale, use or
other dealings in this Software without prior written authorization.
libX11-1.6.3/specs/XKB/XKBlib-3.svg 0000644 0143106 0000012 00000145245 12477417235 0016626 0 ustar 00alanc staff 0000266 0200006
style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none"
d="m 270.58984,157.55078 103.5586,0 0,0.48047 -103.5586,0 z m 0,0"
id="path216"
inkscape:connector-curvature="0" />
Attaching Xkb Actions to X Input Extension Devices
The X input extension allows an X server to support multiple keyboards, as well
as other input devices, in addition to the core X keyboard and pointer. The
input extension categorizes devices by grouping them into classes. Keyboards
and other input devices with keys are classified as KeyClass devices by the
input extension. Other types of devices supported by the input extension
include, but are not limited to: mice, tablets, touchscreens, barcode readers,
button boxes, trackballs, identifier devices, data gloves, and eye trackers.
Xkb provides additional control over all X input extension devices, whether
they are KeyClass
devices or not, as well as the core keyboard and pointer.
If an X server implements support for both the input extension and Xkb, the
server implementor determines whether interaction between Xkb and the input
extension is allowed. Implementors are free to restrict the effects of Xkb to
only the core X keyboard device or allow interaction between Xkb and the input
extension.
Several types of interaction between Xkb and the input extension are defined by
Xkb. Some or all may be allowed by the X server implementation.
Regardless of whether the server allows interaction between Xkb and the input
extension, the following access is provided:
Xkb functionality for the core X keyboard device and its mapping is accessed
via the functions described in the other chapters of this specification.
Xkb functionality for the core X pointer device is accessed via the
XkbGetDeviceInfo and XkbSetDeviceInfo functions described in this chapter.
If all types of interaction are allowed between Xkb and the input extension,
the following additional access is provided:
If allowed, Xkb functionality for additional
KeyClass
devices supported by the input extension is accessed via those same functions.
If allowed, Xkb functionality for non-
KeyClass
devices supported by the input extension is also accessed via the
XkbGetDeviceInfo and XkbSetDeviceInfo functions described in this chapter.
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
(BellFeedbackClass
and
KbdFeedbackClass).
A device can have more than one feedback of each type; the feedback ID
identifies the particular feedback within its class.
A keyboard feedback has:
Auto-repeat status (global and per key)
32 LEDs
A bell
An indicator feedback has:
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
XkbDfltXIId
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
XkbGetDeviceInfo
and specifying
XkbUseCoreKbd
as the
device_spec;
the values will be returned in
dflt_kbd_fb
and
dflt_led_fb.
If the server does not allow Xkb access to input extension
KeyClass
devices, attempts to use Xkb requests with those devices fail with a
BadKeyboard
error. Attempts to access non-
KeyClass
input extension devices via XkbGetDeviceInfo and XkbSetDeviceInfo fail
silently if Xkb access to those devices is not supported by the X server.
XkbDeviceInfoRecXkbDeviceInfoRecXkbDeviceLedInfoRec
Information about X Input Extension devices is transferred between a client
program and the Xkb extension in an
XkbDeviceInfoRec
structure:
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; /* True ⇒ 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 btn_acts */
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 */
} XkbDeviceInfoRec, *XkbDeviceInfoPtr;
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 maps */
unsigned int names_present; /* bits for which LEDs are in names */
unsigned int state; /* 1 bit ⇒ corresponding LED is on */
Atom names[XkbNumIndicators]; /* names for LEDs */
XkbIndicatorMapRec maps; /* indicator maps for each LED */
} XkbDeviceLedInfoRec, *XkbDeviceLedInfoPtr;
The
type
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
KeyClass),
it has its own state, and
has_own_state
is
True.
If
has_own_state
is
False,
the state of the core keyboard is used. The
supported
and
unsupported
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
XkbDeviceInfoRec
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.
XkbDeviceInfoRec Mask BitsNameXkbDeviceInfoRec Fields EffectedValueCapability If SetXkbXI_KeyboardsMask(1L << 0)
Clients can use all Xkb requests and events with
KeyClass
devices supported by the input device extension.
XkbXI_ButtonActionsMasknum_btnsbtn_acts(1L <<1)
Clients can assign key actions to buttons on non-
KeyClass
input extension devices.
XkbXI_IndicatorNamesMaskleds->names(1L <<2)
Clients can assign names to indicators on non-
KeyClass
input extension devices.
XkbXI_IndicatorMapsMaskleds->maps(1L <<3)
Clients can assign indicator maps to indicators on non-
KeyClass
input extension devices.
XkbXI_IndicatorStateMaskleds->state(1L <<4)
Clients can request the status of indicators on non-
KeyClass
input extension devices.
XkbXI_IndicatorsMasksz_ledsnum_ledsleds->*(0x1c)XkbXI_IndicatorNamesMask |XkbXI_IndicatorMapsMask |XkbXI_IndicatorStateMaskXkbXI_UnsupportedFeaturesMaskunsupported(1L <<15)XkbXI_AllDeviceFeaturesMaskThose selected by Value column masks(0x1e)XkbXI_IndicatorsMask | XkbXI_ButtonActionsMaskXkbXI_AllFeaturesMaskThose selected by Value column masks(0x1f)XkbXI_AllDeviceFeaturesMask | XkbXI_KeyboardsMaskXkbXI_AllDetailsMaskThose selected by Value column masks(0x801f)XkbXI_AllFeaturesMask | XkbXI_UnsupportedFeaturesMask
The
name,
type,
has_own_state,
supported,
and
unsupported
fields are always filled in when a valid reply is returned from the server
involving an
XkbDeviceInfoRec.
All of the other fields are modified only if the particular function asks for
them.
Querying Xkb Features for Non-KeyClass Input Extension Devices
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-
KeyClass
extension device, use XkbGetDeviceInfo.
XkbGetDeviceInfoXkbDeviceInfoPtr XkbGetDeviceInfoDisplay *dpyunsigned int whichunsigned int device_specunsigned int ind_classunsigned int ind_iddpy
connection to X server
which
mask indicating information to return
device_spec
device ID, or XkbUseCoreKbdind_class
feedback class for indicator requests
ind_id
feedback ID for indicator requests
XkbGetDeviceInfo
returns information about the input device specified by
device_spec.
Unlike the
device_spec
parameter of most Xkb functions,
device_spec
does not need to be a keyboard device. It must, however, indicate either the
core keyboard or a valid X Input Extension device.
The
which
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
XkbDeviceInfoRec
to contain values for the corresponding fields specified in the table.
The
XkbDeviceInfoRec
returned by
XkbGetDeviceInfo
always has values for
name
(may be a null string, ""),
type,
supported,
unsupported,
has_own_state,
dflt_kbd_fb,
and
dflt_led_fb.
Other fields are filled in as specified by
which.
Upon return, the
supported
field will be set to the inclusive OR of zero or more bits from
Table 21.1;
each bit set indicates an optional Xkb extension device feature supported by
the server implementation, and a client may modify the associated behavior.
If the
XkbXI_ButtonActionsMask
bit is set in
which,
the
XkbDeviceInfoRec
returned will have the button actions
(btn_acts
field) filled in for all buttons.
If
which
includes one of the bits in XkbXI_IndicatorsMask,
the feedback class of the
indicators must be specified in ind_class, and the feedback ID of the
indicators must be specified in ind_id. If the request does not include any of
the bits in XkbXI_IndicatorsMask,
the ind_class and ind_id parameters are
ignored. The class and ID can be obtained via the input device extension
XListInputDevices request.
If any of the
XkbXI_IndicatorsMask
bits are set in
which,
the
XkbDeviceInfoRec
returned will have filled in the portions of the
leds
structure corresponding to the indicator feedback identified by
ind_class
and
ind_id.
The
leds
vector of the
XkbDeviceInfoRec
is allocated if necessary and
sz_leds
and
num_leds
filled in. The
led_class,
led_id
and
phys_indicators
fields of the
leds
entry corresponding to
ind_class
and
ind_id
are always filled in. If
which
contains
XkbXI_IndicatorNamesMask,
the
names_present
and
names
fields of the
leds
structure corresponding to
ind_class
and
ind_id
are returned.
If
which
contains
XkbXI_IndicatorStateMask,
the corresponding
state
field is updated. If
which
contains
XkbXI_IndicatorMapsMask,
the
maps_present
and
maps
fields are updated.
Xkb provides convenience functions to request subsets of the information
available via
XkbGetDeviceInfo.
These convenience functions mirror some of the mask bits. The functions all
take an
XkbDeviceInfoPtr
as an input argument and operate on the X Input Extension device specified by
the
device_spec
field of the structure. Only the parts of the structure indicated in the
function description are updated. The
XkbDeviceInfoRec
structure used in the function call can be obtained by calling
XkbGetDeviceInfo or can be allocated by calling XkbAllocDeviceInfo
(see section 21.3).
These convenience functions are described as follows.
To query the button actions associated with an X Input Extension device, use
XkbGetDeviceButtonActions.
XkbGetDeviceButtonActionsStatus XkbGetDeviceButtonActionsDisplay *dpyXkbDeviceInfoPtr device_infoBool all_buttonsunsigned int first_buttonunsigned int num_buttonsdpy
connection to X server
device_info
structure to update with results
all_buttonsTrue ⇒ get information for all buttons
first_button
number of first button for which info is desired
num_buttons
number of buttons for which info is desired
XkbGetDeviceButtonActions
queries the server for the desired button information for the device indicated
by the
device_spec
field of
device_info
and waits for a reply. If successful,
XkbGetDeviceButtonActions
backfills the button actions
(btn_acts
field of
device_info)
for only the requested buttons, updates the
name,
type,
supported,
and
unsupported
fields, and returns
Success.
all_buttons,
first_button
and
num_buttons
specify the device buttons for which actions should be returned. Setting
all_buttons
to
True
requests actions for all device buttons; if
all_buttons
is
False,
first_button
and
num_buttons
specify a range of buttons for which actions are requested.
If a compatible version of Xkb is not available in the server or the Xkb
extension has not been properly initialized, XkbGetDeviceButtonActions returns
BadAccess.
If allocation errors occur, a
BadAlloc
status is returned. If the specified device
(device_info->device_spec)
is invalid, a
BadKeyboard
status is returned. If the device has no buttons, a
BadMatch
status is returned. If
first_button
and
num_buttons
specify illegal buttons, a
BadValue
status is returned.
To query the indicator names, maps, and state associated with an LED feedback
of an input extension device, use XkbGetDeviceLedInfo.
XkbGetDeviceLedInfoStatus XkbGetDeviceLedInfoDisplay *dpyXkbDeviceInfoPtr device_infounsigned int led_classunsigned int led_idunsigned int whichdpy
connection to X server
device_info
structure to update with results
led_class
LED feedback class assigned by input extension
led_id
LED feedback ID assigned by input extension
which
mask indicating desired information
XkbGetDeviceLedInfo
queries the server for the desired LED information for the feedback specified
by
led_class
and
led_id
for the X input extension device indicated by
device_spec->device_info
and waits for a reply. If successful,
XkbGetDeviceLedInfo
backfills the relevant fields of
device_info
as determined by
which
with the results and returns
Success.
Valid values for
which
are the inclusive OR of any of
XkbXI_IndicatorNamesMask,
XkbXI_IndicatorMapsMask,
and
XkbXI_IndicatorStateMask.
The fields of
device_info
that are filled in when this request succeeds are
name,
type,
supported,
and
unsupported,
and portions of the
leds
structure corresponding to
led_class
and
led_id
as indicated by the bits set in
which.
The
device_info->leds
vector is allocated if necessary and
sz_leds
and
num_leds
filled in. The
led_class,
led_id
and
phys_indicators
fields of the
device_info->leds
entry corresponding to
led_class
and
led_id
are always filled in.
If
which
contains
XkbXI_IndicatorNamesMask,
the
names_present
and
names
fields of the
device_info->leds
structure corresponding to
led_class
and
led_id
are updated, if
which
contains
XkbXI_IndicatorStateMask,
the corresponding
state
field is updated, and if
which
contains
XkbXI_IndicatorMapsMask,
the
maps_present
and
maps
fields are updated.
If a compatible version of Xkb is not available in the server or the Xkb
extension has not been properly initialized,
XkbGetDeviceLedInfo
returns
BadAccess.
If allocation errors occur, a
BadAlloc
status is returned. If the device has no indicators, a
BadMatch
error is returned. If
ledClass
or
ledID
have illegal values, a
BadValue
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
BadMatch
error is returned.
Allocating, Initializing, and Freeing the XkbDeviceInfoRec
Structure
To obtain an
XkbDeviceInfoRec
structure, use XkbGetDeviceInfo or XkbAllocDeviceInfo.
XkbAllocDeviceInfoXkbDeviceInfoPtr XkbAllocDeviceInfounsigned int device_specunsigned int n_buttonsunsigned int sz_ledsdevice_spec
device ID with which structure will be used
n_buttons
number of button actions to allocate space for
sz_leds
number of LED feedbacks to allocate space for
XkbAllocDeviceInfo
allocates space for an
XkbDeviceInfoRec
structure and initializes that structure’s
device_spec
field with the device ID specified by device_spec. If
n_buttons
is nonzero,
n_buttonsXkbActions
are linked into the
XkbDeviceInfoRec
structure and initialized to zero. If sz_leds is nonzero,
sz_ledsXkbDeviceLedInfoRec
structures are also allocated and linked into the
XkbDeviceInfoRec
structure. If you request
XkbDeviceLedInfoRec
structures be allocated using this request, you must initialize them
explicitly.
To obtain an
XkbDeviceLedInfoRec
structure, use XkbAllocDeviceLedInfo.
XkbAllocDeviceLedInfoStatus XkbAllocDeviceLedInfoXkbDeviceInfoPtr device_infoint num_neededdevice_info
structure in which to allocate LED space
num_needed
number of indicators to allocate space for
XkbAllocDeviceLedInfo
allocates space for an
XkbDeviceLedInfoRec
and places it in
device_info.
If num_needed is nonzero,
num_neededXkbIndicatorMapRec
structures are also allocated and linked into the
XkbDeviceLedInfoRec
structure. If you request
XkbIndicatorMapRec
structures be allocated using this request, you must initialize them
explicitly. All other fields are initialized to zero.
To initialize an
XkbDeviceLedInfoRec
structure, use XkbAddDeviceLedInfo.
XkbAddDeviceLedInfoXkbDeviceLedInfoPtr XkbAddDeviceLedInfoXkbDeviceInfoPtr device_infounsigned int led_classunsigned int led_iddevice_info
structure in which to add LED info
led_class
input extension class for LED device of interest
led_id
input extension ID for LED device of interest
XkbAddDeviceLedInfo
first checks to see whether an entry matching
led_class
and
led_id
already exists in the
device_info->leds
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
device_info->leds
and extends it if there is not enough room. It then increments
device_info->num_leds
and fills in the next available entry in
device_info->leds
with
led_class
and
led_id.
If successful,
XkbAddDeviceLedInfo
returns a pointer to the
XkbDeviceLedInfoRec
structure that was initialized. If unable to allocate sufficient storage, or
if
device_info
points to an invalid
XkbDeviceInfoRec
structure, or if
led_class
or
led_id
are inappropriate,
XkbAddDeviceLedInfo
returns
NULL.
To allocate additional space for button actions in an
XkbDeviceInfoRec
structure, use XkbResizeDeviceButtonActions.
XkbResizeDeviceButtonActionsStatus XkbResizeDeviceButtonActionsXkbDeviceInfoPtr device_infounsigned int new_totaldevice_info
structure in which to allocate button actions
new_total
new total number of button actions needed
XkbResizeDeviceButtonActions
reallocates space, if necessary, to make sure there is room for a total of
new_total
button actions in the
device_info
structure. Any new entries allocated are zeroed. If successful,
XkbResizeDeviceButtonActions
returns Success. If new_total is zero, all button actions are deleted,
device_info->num_btns
is set to zero, and
device_info->btn_acts
is set to
NULL.
If device_info is invalid or new_total is greater than 255,
BadValue
is returned. If a memory allocation failure occurs, a
BadAlloc
is returned.
To free an
XkbDeviceInfoRec
structure, use XkbFreeDeviceInfo.
XkbFreeDeviceInfovoid XkbFreeDeviceInfoXkbDeviceInfoPtr device_infounsigned int whichBool free_alldevice_info
pointer to XkbDeviceInfoRec in which to free items
which
mask of components of device_info to free
free_allTrue ⇒ free everything, including device_info
If free_all is
True,
the
XkbFreeDeviceInfo
frees all components of
device_info
and the
XkbDeviceInfoRec
structure pointed to by
device_info
itself. If free_all is
False,
the value of which determines which subcomponents are freed.
which
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
device_info
are freed,
device_info->btn_acts
is set to
NULL,
and
device_info->num_btns
is set to zero. If which contains all bits in
XkbXI_IndicatorsMask, all
XkbDeviceLedInfoRec
structures associated with
device_info
are freed,
device_info->leds
is set to
NULL,
and
device_info->sz_leds
and
device_info->num_leds
are set to zero. If which contains XkbXI_IndicatorMapsMask,
all indicator maps associated with
device_info
are cleared, but the number of LEDs and the leds structures themselves are
preserved. If which contains XkbXI_IndicatorNamesMask,
all indicator names
associated with device_info are cleared, but the number of LEDs and the leds
structures themselves are preserved. If which contains
XkbXI_IndicatorStateMask,
the indicator state associated with the
device_info
leds are set to zeros but the number of LEDs and the leds structures
themselves are preserved.
Setting Xkb Features for Non-KeyClass Input Extension Devices
The Xkb extension allows clients to assign any key action to either core
pointer or input extension device buttons. This makes it possible to control
the keyboard or generate keyboard key events from extension devices or from the
core pointer.
Key actions assigned to core X pointer buttons or input extension device
buttons cause key events to be generated as if they had originated from the
core X keyboard.
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
XkbXI_ButtonActionsMask
bit in the
supported
field of an
XkbDeviceInfoRec
structure.
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
XkbExtensionDeviceNotify
event to the client that issued the request if the client has selected to
receive these events.
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
XkbSetDeviceInfo,
or, to save network traffic, use an
XkbDeviceChangesRec
structure (see section 21.6) and call
XkbChangeDeviceInfo
to download the changes to the server.
To modify some or all of the characteristics of an X Input Extension device,
use XkbSetDeviceInfo.
XkbSetDeviceInfoBool XkbSetDeviceInfoDisplay *dpyunsigned int whichXkbDeviceInfoPtr device_infodpy
connection to X server
which
mask indicating characteristics to modify
device_info
structure defining the device and modifications
XkbSetDeviceInfo
sends a request to the server to modify the characteristics of the device
specified in the
device_info
structure. The particular characteristics modified are identified by the bits
set in
which
and take their values from the relevant fields in
device_info
(see Table 21.1).
XkbSetDeviceInfo
returns
True
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
False.
The
which
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:
XkbXI_ButtonActionsMask,
XkbXI_IndicatorNamesMask,
XkbXI_IndicatorMapsMask.
If the features requested to be manipulated in
which
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.
If the device specified in
device_info->device_spec
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
BadMatch
protocol error results.
If the
XkbXI_ButtonActionsMask
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
XkbXI_ButtonActionsMask
is set in
which,
the actions for all buttons specified in device_info are set to the
XkbActions
specified in
device_info->btn_acts.
If the number of buttons requested to be updated is not valid for the device,
XkbSetDeviceInfo
returns
False
and a
BadValue
protocol error results.
If the
XkbXI_IndicatorMapsMask
and / or
XkbXI_IndicatorNamesMask
bit is set in the supported mask returned by XkbGetDeviceInfo, the Xkb
extension allows applications to assign maps and / or names to the indicators
of nonkeyboard extension devices. If supported, maps and / or names can be
assigned to all extension device indicators, whether they are part of a
keyboard feedback or part of an indicator feedback.
If the
XkbXI_IndicatorMapsMask
and / or
XkbXI_IndicatorNamesMask
flag is set in
which,
the indicator maps and / or names for all
device_info->num_leds
indicator devices specified in
device_info->leds
are set to the maps and / or names specified in
device_info->leds.
device_info->leds->led_class
and
led_id
specify the input extension class and device ID for each indicator device to
modify; if they have invalid values, a
BadValue
protocol error results and
XkbSetDeviceInfo
returns
False.
If they have legal values but do not specify a keyboard or indicator class
feedback for the device in question, a
BadMatch
error results. If any of the values in
device_info->leds->names
are not a valid Atom or
None,
a
BadAtom
protocol error results.
Xkb provides convenience functions to modify subsets of the information
accessible via
XkbSetDeviceInfo.
Only the parts of the structure indicated in the function description are
modified. These convenience functions are described as follows.
To change only the button actions for an input extension device, use
XkbSetDeviceButtonActions.
XkbSetDeviceButtonActionsBool XkbSetDeviceButtonActionsDisplay *dpyXkbDeviceInfoPtr device_infounsigned int first_buttonunsigned int num_buttonsdpy
connection to X server
device_info
structure defining the device and modifications
first_button
number of first button to update, 0 relative
num_buttons
number of buttons to update
XkbSetDeviceButtonActions
assigns actions to the buttons of the device specified in
device_info->device_spec.
Actions are assigned to
num_buttons
buttons beginning with
first_button
and are taken from the actions specified in
device_info->btn_acts.
If the server does not support assignment of Xkb actions to extension device
buttons,
XkbSetDeviceButtonActions
has no effect and returns
False.
If the device has no buttons or if
first_button
or
num_buttons
specify buttons outside of the valid range as determined by
device_info->num_btns,
the function has no effect and returns
False.
Otherwise,
XkbSetDeviceButtonActions
sends a request to the server to change the actions for the specified buttons
and returns
True.
If the actual request sent to the server involved illegal button numbers, a
BadValue
protocol error is generated. If an invalid device identifier is specified in
device_info->device_spec,
a BadKeyboard
protocol error results. If the actual device specified in
device_info->device_spec
does not contain buttons and a request affecting buttons is made, a
BadMatch
protocol error is generated.
XkbExtensionDeviceNotify EventeventsXkbExtensionDeviceNotifyXkbExtensionDeviceNotifyEvent
The Xkb extension generates
XkbExtensionDeviceNotify
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.
Events indicating an attempt to use an unsupported feature are
delivered only to the client requesting the event.
To track changes to the status of input extension devices or attempts to use
unsupported features of a device, select to receive
XkbExtensionDeviceNotify
events by calling either
XkbSelectEvents
or
XkbSelectEventDetails
(see section 4.3).
To receive
XkbExtensionDeviceNotify
events under all possible conditions, call
XkbSelectEvents
and pass
XkbExtensionDeviceNotifyMask
in both
bits_to_change
and
values_for_bits.
The
XkbExtensionDeviceNotify
event has no event details. However, you can call
XkbSelectEventDetails
using
XkbExtensionDeviceNotify
as the
event_type
and specifying
XkbAllExtensionDeviceEventsMask
in
bits_to_change
and
values_for_bits.
This has the same effect as a call to
XkbSelectEvents.
The structure for
XkbExtensionDeviceNotify
events is:
typedef struct {
int type; /* Xkb extension base event code */
unsigned long serial; /* X server serial number for event */
Bool send_event; /* True ⇒ synthetically generated */
Display * display; /* server connection where event generated */
Time time; /* server time when event generated */
int xkb_type; /* XkbExtensionDeviceNotifyEvent */
int device; /* Xkb device ID, will not be XkbUseCoreKbd */
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 */
} XkbExtensionDeviceNotifyEvent;
The
XkbExtensionDeviceNotify
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.
Tracking Changes to Extension DevicesXkbDeviceChangesRecXkbDeviceLedChangesRec
Changes to an Xkb extension device may be tracked by listening to
XkbExtensionDeviceNotify
events and accumulating the changes in an
XkbDeviceChangesRec
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:
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;
} XkbDeviceChangesRec, *XkbDeviceChangesPtr;
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 */
} XkbDeviceLedChangesRec, *XkbDeviceLedChangesPtr;
A local description of the configuration and state of a device may be kept in
an
XkbDeviceInfoRec
structure. The actual state or configuration of the device may change because
of XkbSetDeviceInfo and XkbSetButtonActions requests made by clients or by user
interaction with the device. The X server sends an XkbExtensionDeviceNotify
event to all interested clients when the state of any buttons or indicators or
the configuration of the buttons or indicators on the core keyboard or any
input extension device changes. The event reports the state of indicators for a
single indicator feedback, and the state of up to 128 buttons. If more than 128
buttons or more than one indicator feedback are changed, the additional buttons
and indicator feedbacks are reported in subsequent events. Xkb provides
functions with which you can track changes to input extension devices by noting
the changes that were made and then requesting the changed information from the
server.
To note device changes reported in an
XkbExtensionDeviceNotify
event, use XkbNoteDeviceChanges.
XkbNoteDeviceChangesvoid XkbNoteDeviceChangesXkbDeviceChangesPtr oldXkbExtensionDeviceNotifyEvent *newunsigned int wantedold
structure tracking state changes
new
event indicating state changes
wanted
mask indicating changes to note
The wanted field specifies the changes that should be noted in
old,
and is composed of the bitwise inclusive OR of one or more of the masks from
Table 21.1.
The
reason
field of the event in
new
indicates the types of changes the event is reporting.
XkbNoteDeviceChanges
updates the
XkbDeviceChangesRec
specified by
old
with the changes that are both specified in
wanted
and contained in
new->reason.
To update a local copy of the state and configuration of an X input extension
device with the changes previously noted in an
XkbDeviceChangesRec
structure, use XkbGetDeviceInfoChanges.
To query the changes that have occurred in the button actions or indicator
names and indicator maps associated with an input extension device, use
XkbGetDeviceInfoChanges.
XkbGetDeviceInfoChangesStatus XkbGetDeviceInfoChangesDisplay *dpyXkbDeviceInfoPtr device_infoXkbDeviceChangesPtr changesdpy
connection to X server
device_info
structure to update with results
changes
contains notes of changes that have occurred
The changes->changed field indicates which attributes of the device
specified in
changes->device
have changed. The parameters describing the changes are contained in the other
fields of
changes.
XkbGetDeviceInfoChanges
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
device_info
with the new information.
To update the server’s description of a device with the changes noted in an
XkbDeviceChangesRec, use XkbChangeDeviceInfo.
XkbChangeDeviceInfoBool XkbChangeDeviceInfoDisplay *dpyXkbDeviceInfoPtr device_infoXkbDeviceChangesPtr changesdpy
connection to X server
device_info
local copy of device state and configuration
changes
note specifying changes in device_infoXkbChangeDeviceInfo
updates the server’s description of the device specified in
device_info->device_spec
with the changes specified in
changes
and contained in
device_info.
The update is made by an XkbSetDeviceInfo request.
/* server connection where event generated */
Time tilibX11-1.6.3/specs/XKB/XKBlib-18.svg 0000644 0143106 0000012 00000116730 12477417235 0016711 0 ustar 00alanc staff 0000266 0200006
ipodi:role="line">config
libX11-1.6.3/specs/XKB/ch13.xml 0000644 0143106 0000012 00000352713 12477417235 0016112 0 ustar 00alanc staff 0000266 0200006
Keyboard Geometry
The Xkb description of a keyboard includes an optional keyboard geometry that
describes the physical appearance of the keyboard. Keyboard geometry describes
the shape, location, and color of all keyboard keys or other visible keyboard
components such as indicators. The information contained in a keyboard geometry
is sufficient to allow a client program to draw an accurate two-dimensional
image of the keyboard.
You can retrieve a keyboard geometry from an X server that supports Xkb, or you
can allocate it from scratch and initialize it in a client program. The
keyboard geometry need not have any correspondence with the physical keyboard
that is connected to the X server.
Geometry measurements are specified in mm/10 units. The origin (0,0) is in the
top left corner of the keyboard image. A component’s own origin is also its
upper left corner. In some cases a component needs to be drawn rotated. For
example, a special keyboard may have a section of keys arranged in rows in a
rectangular area, but the entire rectangle may not be in alignment with the
rest of the keyboard, and instead, it is rotated from horizontal by 30°.
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 Figure 13.1.
Rotated Keyboard Sections
Some geometry components include a
priority,
which indicates the order in which overlapping objects should be drawn.
Objects should be drawn in order from highest priority (0) to lowest (255).
XkbGeometryRec
The keyboard geometry’s top-level description is stored in a
XkbGeometryRec
structure. This structure contains three types of information:
Lists of items, not used to draw the basic keyboard, but indexed by the
geometry descriptions that comprise the entire keyboard geometry (colors,
geometry properties, key aliases, shapes)
A number of singleton items that describe the keyboard as a whole (keyboard
name, width and height, a color for the keyboard as a whole, and a color for
keyboard key labels)
A list of the keyboard’s sections and nonkey doodads
The top-level geometry is described in more detail in the following.
The lists of items used by components of the keyboard geometry description is
as follows:
The top-level keyboard geometry description includes a list of up to
XkbGeomMaxColors
(32)
color names.
A color name is a string whose interpretation is not specified by Xkb. The
XkbColorRec
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.
The top-level keyboard geometry description includes a list of
geometry properties.
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
properties,
consider the pause/break key on most PC keyboards: the break
symbol is
usually on the front of the key and is often a different color. A program might
set a property to:
LBL_PAUS = "{Pause/top/black,Break/front/red}"
and use the property information to draw the key with a front label as well as
a top label.
The top-level keyboard geometry description includes a list of
key aliases
(see ). Key aliases allow the keyboard layout designer to assign
multiple key names to a single key.
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
XkbNamesRec
(xkb->names).
Therefore, consider the key aliases defined by the geometry before
considering key aliases supplied by the keycodes.
The top-level keyboard geometry description includes a list of
shapes;
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
outlines.
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
primary
field in the
XkbShapeRec
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
approximation
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.
The
XkbGeometryRec
top-level geometry description contains the following information that
pertains to the keyboard as a whole:
A
keyboard symbolic name
of type Atom to help users identify the keyboard.
The
width
and
height
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.
The
base color
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.
The
label color
is the color used to draw the labels on most of the keyboard keys.
The
label font
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.
The keyboard is subdivided into named
sections
of related keys and doodads. The sections and doodads on the keyboard are
listed in the
XkbGeometryRec
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
doodad
describes some visible aspect of the keyboard that is not a key and is not a
section.
Keyboard with Four SectionsShapes and Outlines
A
shape,
used to draw keyboard components and stored in a
XkbShapeRec
structure, has:
An arbitrary name of type Atom.
Bounds (two x and y coordinates) that describe the corners of a rectangle
containing the shape’s top surface outline.
A list of one or more outlines (described below).
Optional pointers to a primary and an approximation outline (described below).
If either of these pointers is
NULL,
the default primary/approximation outline is the first one in the list of
outlines for the shape.
An
outline,
stored in a
XkbOutlineRec
structure, is a list of one or more points that describes a single
closed-polygon, as follows:
A list with a single point describes a rectangle with one corner at the origin
of the shape (0,0) and the opposite corner at the specified point.
A list of two points describes a rectangle with one corner at the position
specified by the first point and the opposite corner at the position specified
by the second point.
A list of three or more points describes an arbitrary polygon. If necessary,
the polygon is automatically closed by connecting the last point in the list
with the first.
A nonzero value for the
corner_radius
field specifies that the corners of the polygon should be drawn as circles
with the specified radius.
All points in an outline are specified relative to the origin of the enclosing
shape. Points in an outline may have negative values for the X and Y coordinate.
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
primary
field of the
XkbShapeRec
structure is not
NULL,
it points to the primary outline. A rectangular
approximation
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.
Sections
As previously noted, a keyboard is subdivided into
sections
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
XkbSectionRec,
include:
An arbitrary name of type Atom.
A priority, to indicate drawing order. 0 is the highest priority, 255 the
lowest.
Origin of the section, relative to the origin of the keyboard.
The width and height and the angle of rotation.
A list of
rows.
A row is a list of horizontally or vertically adjacent keys. Horizontal rows
parallel the (prerotation) top of the section, and vertical rows parallel the
(prerotation) left of the section. All keys in a horizontal row share a common
top coordinate; all keys in a vertical row share a left coordinate. Figure 13.3
shows the alpha section from the keyboard shown in Figure 13.2, divided into
rows. Rows and keys are defined below.
Rows in a Section
An optional list of
doodads;
any type of doodad can be enclosed within a section. Position and angle of
rotation are relative to the origin and angle of rotation of the sections that
contain them. Priority for doodads in a section is relative to the other
components of the section, not to the keyboard as a whole.
An optional
overlay
with a name of type Atom and a list of overlay rows (described below).
Bounds (two x and y coordinates) that describe the corners of a rectangle
containing the entire section.
Rows and Keys
A row description
(XkbRowRec)
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.
A key description
(XkbKeyRec)
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
XkbGeometryRec).
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.
Doodads
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.
Each doodad’s origin is stored in fields named
left
and
top,
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
type
field, which specifies the type of doodad.
Xkb supports five types of doodads:
An
indicator doodad
describes one of the physical keyboard indicators. Indicator doodads specify
the shape of the indicator, the indicator color when it is lit
(on_color)
and the indicator color when it is dark
(off_color).
An
outline doodad
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.
A
solid doodad
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.
A
text doodad
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.
A
logo doodad
is a catch-all, which describes some other visible element of the keyboard. A
logo doodad is essentially an outline doodad with an additional symbolic name
that describes the element to be drawn. If a keyboard display program
recognizes the symbolic name, it can draw something appropriate within the
bounding region of the shape specified in the doodad. If the symbolic name does
not describe a recognizable image, it should draw an outline using the
specified shape, outline, and angle of rotation. The Xkb extension does not
specify the interpretation of logo names.
The structures these doodads are stored in and the values of the
type
fields are shown in Table 13.1.
Overlay Rows and Overlay Keys
An
overlay row
(XkbOverlayRowRec)
contains a pointer to the row it overlays and a list of
overlay keys.
Each overlay key definition
(XkbOverlayKeyRec)
indicates a key that can yield multiple keycodes and consists of a field
named
under,
which specifies the primary name of the key and a field named
over,
which specifies the name for the key when the overlay keycode is selected.
The key specified in
under
must be a member of the section that contains the overlay key definition,
while the key specified in over must not be.
Drawing a Keyboard Representation
To draw a representation of the keyboard, draw in the following order:
Draw the top-level keyboard as a rectangle, using its width and height.
For each component (section or doodad) of the top-level geometry, in priority order:
If component is a section
For each row, in the order it appears in the section
Draw keys in the order they appear in the row
Draw doodads within the section in priority order.
Else draw doodad
Geometry Data Structures
In the following figures, a solid arrow denotes a pointer to an array of
structures or a singleton structure. A dotted arrow denotes an index or a
pointer into the array.
Xkb Geometry Data StructuresXkb Geometry Data Structures (Doodads)Xkb Geometry Data Structures (Overlays)
typedef struct _XkbGeometry { /* top-level keyboard geometry structure */
Atom name; /* keyboard name */
unsigned short width_mm; /* keyboard width in mm/10 */
unsigned short height_mm; /* keyboard height in mm/10 */
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 */
} XkbGeometryRec, *XkbGeometryPtr;
The
doodads
array is only for doodads not contained in any of the
sections
that has its own
doodads.
The key aliases contained in the
key_aliases
array take precedence over any defined in the keycodes component of the
keyboard description.
typedef struct _XkbProperty {
char * name; /* property name */
char * value; /* property value */
} XkbPropertyRec, *XkbPropertyPtr;
typedef struct _XkbColor {
unsigned int pixel; /* color */
char * spec; /* color name */
} XkbColorRec, *XkbColorPtr;
typedef struct _XkbKeyAliasRec {
char real[XkbKeyNameLength]; /* real name of the key */
char alias[XkbKeyNameLength]; /* alias for the key */
} XkbKeyAliasRec, *XkbKeyAliasPtr;
typedef struct _XkbPoint { /* x, y coordinates */
short x;
short y;
} XkbPointRec, *XkbPointPtr;
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 */
} XkbOutlineRec, *XkbOutlinePtr;
typedef struct _XkbBounds {
short x1, y1; /* upper left corner of the bounds, in mm/10 */
short x2, y2; /* lower right corner of the bounds, in mm/10 */
} XkbBoundsRec, *XkbBoundsPtr;
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 */
} XkbShapeRec, *XkbShapePtr;
If
approx
and/or
primary
is
NULL,
the default value is used. The default primary outline is the first element
in the outlines array, as is the default approximating outline.
typedef struct _XkbKey { /* key in a row */
XkbKeyNameRec name; /* key name */
short gap; /* gap in mm/10 from previous key in row */
unsigned char shape_ndx; /* index of shape for key */
unsigned char color_ndx; /* index of color for key body */
} XkbKeyRec, *XkbKeyPtr;
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; /* True ⇒vertical row,
False ⇒horizontal row */
XkbKeyPtr keys; /* array of keys in the row */
XkbBoundsRec bounds; /* bounding box for the row */
} XkbRowRec, *XkbRowPtr;
top
and
left
are in
mm/10.
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 */
} XkbOverlayRec, *XkbOverlayPtr;
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 */
} XkbOverlayRowRec, *XkbOverlayRowPtr;
row_under
is an index into the array of
rows
in the section under this overlay. The section under this overlay row is the
one pointed to by
section_under
in this overlay row’s
XkbOverlayRec.
typedef struct _XkbOverlayKey {
XkbKeyNameRec over; /* name of this overlay key */
XkbKeyNameRec under; /* name of the key under this overlay key */
} XkbOverlayKeyRec, *XkbOverlayKeyPtr;
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 mm/10 */
unsigned short height; /* section height, in mm/10 */
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 */
} XkbSectionRec, *XkbSectionPtr;
top
and
left
are the origin of the section, relative to the origin of the keyboard, in
mm/10.
angle
is in
1/10
degrees.
DoodadRec Structures
The doodad arrays in the
XkbGeometryRec
and the
XkbSectionRec
may contain any of the doodad structures and types shown in
Table 13.1.
The doodad structures form a union:
typedef union _XkbDoodad {
XkbAnyDoodadRec any;
XkbShapeDoodadRec shape;
XkbTextDoodadRec text;
XkbIndicatorDoodadRec indicator;
XkbLogoDoodadRec logo;
} XkbDoodadRec, *XkbDoodadPtr;
The
top
and
left
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
XkbGeometryRec
doodad array, and with respect to the section’s origin if the doodad is in a
XkbSectionRec
doodad array. The
color_ndx
or
on_color_ndx
and
off_color_ndx
fields are color indices into the
XkbGeometryRec’s
color array and are the colors to draw the doodads with. Similarly, the
shape_ndx
fields are indices into the
XkbGeometryRec’s
shape array.
typedef struct _XkbShapeDoodad {
Atom name; /* doodad name */
unsigned char type; /* XkbOutlineDoodad
or XkbSolidDoodad */
unsigned char priority; /* drawing priority,
0⇒highest, 255⇒lowest */
short top; /* top coordinate, in mm/10 */
short left; /* left coordinate, in mm/10 */
short angle; /* angle of rotation, clockwise,
in 1/10 degrees */
unsigned short color_ndx; /* doodad color */
unsigned short shape_ndx; /* doodad shape */
} XkbShapeDoodadRec, *XkbShapeDoodadPtr;
typedef struct _XkbTextDoodad {
Atom name; /* doodad name */
unsigned char type; /* XkbTextDoodad */
unsigned char priority; /* drawing priority,
0⇒highest, 255⇒lowest */
short top; /* top coordinate, in mm/10 */
short left; /* left coordinate, in mm/10 */
short angle; /* angle of rotation, clockwise,
in 1/10 degrees */
short width; /* width in mm/10 */
short height; /* height in mm/10 */
unsigned short color_ndx; /* doodad color */
char * text; /* doodad text */
char * font; /* arbitrary font name for doodad text */
} XkbTextDoodadRec, *XkbTextDoodadPtr;
typedef struct _XkbIndicatorDoodad {
Atom name; /* doodad name */
unsigned char type; /* XkbIndicatorDoodad */
unsigned char priority; /* drawing priority, 0⇒highest, 255⇒lowest */
short top; /* top coordinate, in mm/10 */
short left; /* left coordinate, in mm/10 */
short angle; /* angle of rotation, clockwise,
in 1/10 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 */
} XkbIndicatorDoodadRec, *XkbIndicatorDoodadPtr;
typedef struct _XkbLogoDoodad {
Atom name; /* doodad name */
unsigned char type; /* XkbLogoDoodad */
unsigned char priority; /* drawing priority, 0⇒highest, 255⇒lowest */
short top; /* top coordinate, in mm/10 */
short left; /* left coordinate, in mm/10 */
short angle; /* angle of rotation, clockwise,
in 1/10 degrees */
unsigned short color_ndx; /* doodad color */
unsigned short shape_ndx; /* doodad shape */
char * logo_name; /* text for logo */
} XkbLogoDoodadRec, *XkbLogoDoodadPtr
Getting Keyboard Geometry From the Server
You can load a keyboard geometry as part of the keyboard description returned
by
XkbGetKeyboard.
However, if a keyboard description has been previously loaded, you can
instead obtain the geometry by calling the
XkbGetGeometry.
In this case, the geometry returned is the one associated with the keyboard
whose device ID is contained in the keyboard description.
To load a keyboard geometry if you already have the keyboard description, use
XkbGetGeometry.
XkbGetGeometryStatus XkbGetGeometryDisplay *dpyXkbDescPtr xkbdpy
connection to the X server
xkb
keyboard description that contains the ID for the keyboard and into
which the geometry should be loaded
XkbGetGeometry
can return
BadValue,
BadImplementation,
BadName,
BadAlloc,
or
BadLength
errors or
Success
if it succeeds.
It is also possible to load a keyboard geometry by name. The X server maintains
a database of keyboard components (see ). To load a keyboard geometry
description from this database by name, use
XkbGetNamedGeometry.
XkbGetNamedGeometryStatus XkbGetNamedGeometryDisplay *dpyXkbDescPtr xkbAtom namedpy
connection to the X server
xkb
keyboard description into which the geometry should be loaded
name
name of the geometry to be loaded
XkbGetNamedGeometry
can return
BadName
if the
name
cannot be found.
Using Keyboard Geometry
Xkb provides a number of convenience functions to help use a keyboard geometry.
These include functions to return the bounding box of a shape’s top surface
and to update the bounding box of a shape row or section.
A shape is made up of a number of outlines. Each outline is a polygon made up
of a number of points. The bounding box of a shape is a rectangle that contains
all the outlines of that shape.
Key Surface, Shape Outlines, and Bounding Box
To determine the bounding box of the top surface of a shape, use
XkbComputeShapeTop.
XkbComputeShapeTopBool XkbComputeShapeTopXkbShapePtr shapeXkbBoundsPtr bounds_rtrnshape
shape to be examined
bounds_rtrn
backfilled with the bounding box for the shape
XkbComputeShapeTop
returns a
BoundsRec
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
approx
field of
shape
is not
NULL.
If
approx
is
NULL,
the top surface is defined as the last outline in the
shape’s
array of outlines.
XkbComputeShapeTop
returns
False
if
shape
is
NULL
or if there are no outlines for the shape; otherwise, it returns
True.
A
ShapeRec
contains a
BoundsRec
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 XkbComputeShapeBounds.
XkbComputeShapeBoundsBool XkbComputeShapeBoundsXkbShapePtr shapeshape
shape to be examined
XkbComputeShapeBounds
updates the
BoundsRec
contained in the
shape
by examining all the outlines of the shape and setting the
BoundsRec
to the minimum x and minimum y, and maximum x and maximum y values found in
those outlines.
XkbComputeShapeBounds
returns
False
if
shape
is
NULL
or if there are no outlines for the shape; otherwise, it returns
True.
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 XkbComputeRowBounds.
XkbComputeRowBoundsBool XkbComputeRowBoundsXkbGeometryPtr geomXkbSectionPtr sectionXkbRowPtr rowgeom
geometry that contains the sectionsection
section that contains the row
row
row to be examined and updated
XkbComputeRowBounds
checks the bounds of all keys in the
row
and updates the bounding box of the row if necessary.
XkbComputeRowBounds
returns
False
if any of the arguments is
NULL;
otherwise, it returns
True.
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
XkbComputeSectionBounds.
XkbComputeSectionBoundsBool XkbComputeSectionBoundsXkbGeometryPtr geomXkbSectionPtr sectiongeom
geometry that contains the sectionsection
section to be examined and updated
XkbComputeSectionBounds
examines all the rows of the
section
and updates the bounding box of that section so that it contains all rows.
XkbComputeSectionBounds
returns
False
if any of the arguments is
NULL;
otherwise, it returns
True.
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
XkbFindOverlayForKey.
XkbFindOverlayForKeychar *XkbFindOverlayForKeyXkbGeometryPtr geomXkbSectionPtr sectionchar *undergeom
geometry that contains the sectionsection
section to be searched for matching keys
under
.primary name of the key to be considered
XkbFindOverlayForKey
uses the primary name of the key,
under,
to look up the alternate name, which it returns.
Adding Elements to a Keyboard Geometry
Xkb provides functions to add a single new element to the top-level keyboard
geometry. In each case the
num_*
fields of the corresponding structure is incremented by 1. These functions do
not change
sz_*
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.
The top-level geometry description includes a list of
geometry properties.
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.
To add one property to an existing keyboard geometry description, use
XkbAddGeomProperty.
XkbAddGeomPropertyXkbPropertyPtr XkbAddGeomPropertyXkbGeometryPtr geomchar *namechar *valuegeom
geometry to be updated
name
name of the new property
value
value for the new property
XkbAddGeomProperty
adds one property with the specified
name
and
value
to the keyboard geometry specified by geom.
XkbAddGeomProperty
returns
NULL
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.
To add one key alias to an existing keyboard geometry description, use
XkbAddGeomKeyAlias.
XkbAddGeomKeyAliasXkbKeyAliasPtr XkbAddGeomKeyAliasXkbGeometryPtr geomchar *aliaschar *realgeom
geometry to be updated
alias
alias to be added
real
real name to be bound to the new alias
XkbAddGeomKeyAlias
adds one key alias with the value alias to the geometry geom, and associates
it with the key whose real name is real.
XkbAddGeomKeyAlias
returns
NULL
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.
To add one color name to an existing keyboard geometry description, use
XkbAddGeomColor.
XkbAddGeomColorXkbColorPtr XkbAddGeomColorXkbGeometryPtr geomchar *specunsigned int pixelgeom
geometry to be updated
spec
color to be added
pixel
color to be added
XkbAddGeomColor
adds the specified color
name
and
pixel
to the specified geometry
geom.
The top-level geometry description includes a list of up to
MaxColors
(32)
color names.
A color
name
is a string whose interpretation is not specified by Xkb and neither is the
pixel
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.
XkbAddGeomColor
returns
NULL
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
XkbAllocGeomColors
function.
To add one outline to an existing shape, use
XkbAddGeomOutline.
XkbAddGeomOutlineXkbOutlinePtr XkbAddGeomOutlineXkbShapePtr shapeint sz_pointsshape
shape to be updated
sz_points
number of points to be reserved
An outline consists of an arbitrary number of points.
XkbAddGeomOutline
adds an outline to the specified
shape
by reserving
sz_points
points for it. The new outline is allocated and zeroed.
XkbAddGeomOutline
returns
NULL
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.
To add a shape to a keyboard geometry, use
XkbAddGeomShape.
XkbAddGeomShapeXkbShapePtr XkbAddGeomShapeXkbGeometryPtr geomAtom nameint sz_outlinesgeom
geometry to be updated
name
name of the new shape
sz_outlines
number of outlines to be reserved
A geometry contains an arbitrary number of shapes, each of which is made up of
an arbitrary number of outlines.
XkbAddGeomShape
adds a shape to a geometry
geom
by allocating space for
sz_outlines
outlines for it and giving it the name specified by name. If a shape with name
name
already exists in the geometry, a pointer to the existing shape is returned.
XkbAddGeomShape
returns
NULL
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
XkbAllocGeomShapes.
To add one key at the end of an existing row of keys, use
XkbAddGeomKey.
XkbAddGeomKeyXkbKeyPtr XkbAddGeomKeyXkbRowPtr rowrow
row to be updated
Keys are grouped into rows.
XkbAddGeomKey
adds one key to the end of the specified
row.
The key is allocated and zeroed.
XkbAddGeomKey
returns
NULL
if
row
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.
To add one section to an existing keyboard geometry, use
XkbAddGeomSection.
XkbAddGeomSectionXkbSectionPtr XkbAddGeomSectionXkbGeometryPtr geomAtom nameint sz_rowsint sz_doodadsint sz_overlaysgeom
geometry to be updated
name
name of the new section
sz_rows
number of rows to reserve in the section
sz_doodads
number of doodads to reserve in the section
sz_overlays
number of overlays to reserve in the section
A keyboard geometry contains an arbitrary number of sections.
XkbAddGeomSection
adds one section to an existing keyboard geometry
geom.
The new section contains space for the number of rows, doodads, and overlays
specified by
sz_rows,
sz_doodads,
and
sz_overlays.
The new section is allocated and zeroed and given the name specified by
name.
If a section with name
name
already exists in the geometry, a pointer to the existing section is
returned.
XkbAddGeomSection
returns
NULL
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.
To add a row to a section, use
XkbAddGeomRow.
XkbAddGeomRowXkbRowPtr XkbAddGeomRowXkbSectionPtr sectionint sz_keyssection
section to be updated
sz_keys
number of keys to be reserved
One of the components of a keyboard geometry section is one or more rows of
keys.
XkbAddGeomRow
adds one row to the specified
section.
The newly created row contains space for the number of keys specified in
sz_keys.
They are allocated and zeroed, but otherwise uninitialized.
XkbAddGeomRow
returns
NULL
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.
To add one doodad to a section of a keyboard geometry or to the top-level
geometry, use
XkbAddGeomDoodad.
XkbAddGeomDoodadXkbDoodadPtr XkbAddGeomDoodadXkbGeometryPtr geomXkbSectionPtr sectionAtom namegeom
geometry to which the doodad is added
section
section, if any, to which the doodad is added
name
name of the new doodad
A
doodad
describes some visible aspect of the keyboard that is not a key and is not a
section.
XkbAddGeomDoodad
adds a doodad with name specified by name to the geometry
geom
if section is
NULL
or to the section of the geometry specified by section if
section
is not
NULL.
XkbAddGeomDoodad
returns
NULL
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
name
in the doodad array for the geometry (if
section
is
NULL)
or the section (if
section
is non-
NULL),
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.
To add one overlay to a section, use
XkbAddGeomOverlay.
XkbAddGeomOverlayXkbOverlayPtr XkbAddGeomOverlayXkbSectionPtr sectionAtom nameint sz_rowssection
section to which an overlay will be added
name
name of the overlay
sz_rows
number of rows to reserve in the overlay
XkbAddGeomOverlay
adds an overlay with the specified name to the specified
section.
The new overlay is created with space allocated for sz_rows rows. If an
overlay with name
name
already exists in the section, a pointer to the existing overlay is
returned.
XkbAddGeomOverlay
returns
NULL
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.
To add a row to an existing overlay, use
XkbAddGeomOverlayRow.
XkbAddGeomOverlayRowXkbOverlayRowPtr XkbAddGeomOverlayRowXkbOverlayPtr overlayXkbRowPtr row_underint sz_keysoverlay
overlay to be updated
row_under
row to be overlayed in the section overlay
overlays
sz_keys
number of keys to reserve in the row
XkbAddGeomOverlayRow
adds one row to the
overlay.
The new row contains space for
sz_keys
keys. If
row_under
specifies a row that doesn’t exist on the underlying section,
XkbAddGeomOverlayRow
returns
NULL
and doesn’t change the overlay.
XkbAddGeomOverlayRow
returns
NULL
if any of the parameters is empty or if it was not able to allocate space for
the overlay.
To add a key to an existing overlay row, use
XkbAddGeomOverlayKey.
XkbAddGeomOverlayKeyXkbOverlayKeyPtr XkbAddGeomOverlayKeyXkbOverlayPtr overlayXkbRowPtr rowchar *underoverlay
overlay to be updated
row
row in overlay to be updated
under
primary name of the key to be considered
XkbAddGeomOverlayKey
adds one key to the
row
in the
overlay.
If there is no key named
under
in the row of the underlying section,
XkbAddGeomOverlayKey
returns
NULL.
Allocating and Freeing Geometry Components
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
sz_*
but never touch
num_*
(unless there is an allocation failure, in which case they reset both
sz_*
and
num_*
to zero). These functions return
Success
if they succeed,
BadAlloc
if they are not able to allocate space, or
BadValue
if a parameter is not as expected.
To allocate space for an arbitrary number of outlines to a shape, use
XkbAllocGeomOutlines.
XkbAllocGeomOutlinesStatus XkbAllocGeomOutlinesXkbShapePtr shapeint num_neededshape
shape for which outlines should be allocated
num_needed
number of new outlines required
XkbAllocGeomOutlines
allocates space for
num_needed
outlines in the specified
shape.
The outlines are not initialized.
To free geometry outlines, use
XkbFreeGeomOutlines.
XkbFreeGeomOutlinesvoid XkbFreeGeomOutlinesXkbShapePtr shapeint firstint countBool free_allshape
shape in which outlines should be freed
first
first outline to be freed
count
number of outlines to be freed
free_allTrue ⇒ all outlines are freed
If free_all is
True,
all outlines are freed regardless of the value of first or count. Otherwise,
count outlines are freed beginning with the one specified by first.
To allocate space for an arbitrary number of keys to a row, use
XkbAllocGeomKeys.
XkbAllocGeomKeysStatus XkbAllocGeomKeysXkbRowPtr rowint num_neededrow
row to which keys should be allocated
num_needed
number of new keys required
XkbAllocGeomKeys
allocates num_needed keys and adds them to the row. No initialization of the
keys is done.
To free geometry keys, use
XkbFreeGeomKeys.
XkbFreeGeomKeysvoid XkbFreeGeomKeysXkbRowPtr rowint firstint countBool free_allrow
row in which keys should be freed
first
first key to be freed
count
number of keys to be freed
free_allTrue ⇒ all keys are freed
If free_all is
True,
all keys are freed regardless of the value of first or count. Otherwise,
count keys are freed beginning with the one specified by first.
To allocate geometry properties, use
XkbAllocGeomProps.
XkbAllocGeomPropsStatus XkbAllocGeomPropsXkbGeometryPtr geomint num_neededgeom
geometry for which properties should be allocated
num_needed
number of new properties required
XkbAllocGeomProps
allocates space for num_needed properties and adds them to the specified
geometry
geom.
No initialization of the properties is done. A geometry property associates
an arbitrary string with an equally arbitrary name. Geometry properties can be
used to provide hints to programs that display images of keyboards, but they
are not interpreted by Xkb. No other geometry structures refer to geometry
properties.
To free geometry properties, use
XkbFreeGeomProperties.
XkbFreeGeomPropertiesvoid XkbFreeGeomPropertiesXkbGeometryPtr geomint firstint countBool free_allgeom
geometry in which properties should be freed
first
first property to be freed
count
number of properties to be freed
free_allTrue ⇒ all properties are freed
If free_all is
True,
all properties are freed regardless of the value of first or count.
Otherwise, count properties are freed beginning with the one specified by first.
To allocate geometry key aliases, use
XkbAllocGeomKeyAliases.
XkbAllocGeomKeyAliasesStatus XkbAllocGeomKeyAliasesXkbGeometryPtr geomint num_neededgeom
geometry for which key aliases should be allocated
num_needed
number of new key aliases required
XkbAllocGeomKeyAliases
allocates space for num_needed key aliases and adds them to the specified
geometry
geom.
A key alias is a pair of strings that associates an alternate name for a key
with the real name for that key.
To free geometry key aliases, use
XkbFreeGeomKeyAliases.
XkbFreeGeomKeyAliasesvoid XkbFreeGeomKeyAliasesXkbGeometryPtr geomint firstint countBool free_allgeom
geometry in which key aliases should be freed
first
first key alias to be freed
count
number of key aliases to be freed
free_allTrue ⇒ all key aliases are freed
If free_all is
True,
all aliases in the top level of the specified geometry
geom
are freed regardless of the value of first or count. Otherwise, count aliases
in
geom
are freed beginning with the one specified by first.
To allocate geometry colors, use
XkbAllocGeomColors.
XkbAllocGeomColorsStatus XkbAllocGeomColorsXkbGeometryPtr geomint num_neededgeom
geometry for which colors should be allocated
num_needed
number of new colors required.
XkbAllocGeomColors
allocates space for num_needed colors and adds them to the specified geometry
geom.
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.
To free geometry colors, use
XkbFreeGeomColors.
XkbFreeGeomColorsvoid XkbFreeGeomColorsXkbGeometryPtr geomint firstint countBool free_allgeom
geometry in which colors should be freed
first
first color to be freed
count
number of colors to be freed
free_allTrue ⇒ all colors are freed
If free_all is
True,
all colors are freed regardless of the value of first or count. Otherwise,
count colors are freed beginning with the one specified by first.
To allocate points in an outline, use
XkbAllocGeomPoints.
XkbAllocGeomPointsStatus XkbAllocGeomPointsXkbOutlinePtr outlineint num_neededoutline
outline for which points should be allocated
num_needed
number of new points required
XkbAllocGeomPoints
allocates space for
num_needed
points in the specified
outline.
The points are not initialized.
To free points in a outline, use
XkbFreeGeomPoints.
XkbFreeGeomPointsvoid XkbFreeGeomPointsXkbOutlinePtr outlineint firstint countBool free_alloutline
outline in which points should be freed
first
first point to be freed.
count
number of points to be freed
free_allTrue ⇒ all points are freed
If free_all is
True,
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.
To allocate space for an arbitrary number of geometry shapes, use
XkbAllocGeomShapes.
XkbAllocGeomShapesStatus XkbAllocGeomShapesXkbGeometryPtr geomint num_neededgeom
geometry for which shapes should be allocated
num_needed
number of new shapes required
XkbAllocGeomShapes
allocates space for
num_needed
shapes in the specified geometry
geom.
The shapes are not initialized.
To free geometry shapes, use
XkbFreeGeomShapes.
XkbFreeGeomShapesvoid XkbFreeGeomShapesXkbGeometryPtr geomint firstint countBool free_allgeom
geometry in which shapes should be freed
first
first shape to be freed
count
number of shapes to be freed
free_allTrue ⇒ all shapes are freed
If free_all is
True,
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.
To allocate geometry sections, use
XkbAllocGeomSections.
XkbAllocGeomSectionsStatus XkbAllocGeomSectionsXkbGeometryPtr geomint num_neededgeom
geometry for which sections should be allocated
num_needed
number of new sections required
XkbAllocGeomSections
allocates num_needed sections and adds them to the geometry geom. No
initialization of the sections is done.
To free geometry sections, use
XkbFreeGeomSections.
XkbFreeGeomSectionsvoid XkbFreeGeomSectionsXkbGeometryPtr geomint firstint countBool free_allgeom
geometry in which sections should be freed
first
first section to be freed.
count
number of sections to be freed
free_allTrue ⇒ all sections are freed
If free_all is
True,
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.
To allocate rows in a section, use
XkbAllocGeomRows.
XkbAllocGeomRowsStatus XkbAllocGeomRowsXkbSectionPtr sectionint num_neededsection
section for which rows should be allocated
num_needed
number of new rows required
XkbAllocGeomRows
allocates num_needed rows and adds them to the section. No initialization of
the rows is done.
To free rows in a section, use
XkbFreeGeomRows.
XkbFreeGeomRowsvoid XkbFreeGeomRowsXkbSectionPtr sectionint firstint countBool free_allsection
section in which rows should be freed
first
first row to be freed.
count
number of rows to be freed
free_allTrue ⇒ all rows are freed
If free_all is
True,
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.
To allocate overlays in a section, use
XkbAllocGeomOverlays.
XkbAllocGeomOverlaysStatus XkbAllocGeomOverlaysXkbSectionPtr sectionint num_neededsection
section for which overlays should be allocated
num_needed
number of new overlays required
XkbAllocGeomRows
allocates num_needed overlays and adds them to the section. No initialization
of the overlays is done.
To free rows in an section, use
XkbFreeGeomOverlays.
XkbFreeGeomOverlaysvoid XkbFreeGeomOverlaysXkbSectionPtr sectionint firstint countBool free_allsection
section in which overlays should be freed
first
first overlay to be freed.
count
number of overlays to be freed
free_allTrue ⇒ all overlays are freed
If free_all is
True,
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.
To allocate rows in a overlay, use
XkbAllocGeomOverlayRows.
XkbAllocGeomOverlayRowsStatus XkbAllocGeomOverlayRowsXkbSectionPtr overlayint num_neededoverlay
section for which rows should be allocated
num_needed
number of new rows required
XkbAllocGeomOverlayRows
allocates num_needed rows and adds them to the overlay. No initialization of
the rows is done.
To free rows in an overlay, use
XkbFreeGeomOverlayRows.
XkbFreeGeomOverlayRowsvoid XkbFreeGeomOverlayRowsXkbSectionPtr overlayint firstint countBool free_alloverlay
section in which rows should be freed
first
first row to be freed.
count
number of rows to be freed
free_allTrue ⇒ all rows are freed
If free_all is
True,
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.
To allocate keys in an overlay row, use
XkbAllocGeomOverlayKeys.
XkbAllocGeomOverlayKeysStatus XkbAllocGeomOverlayKeysXkbRowPtr rowint num_neededrow
section for which rows should be allocated
num_needed
number of new rows required
XkbAllocGeomOverlayKeys
allocates num_needed keys and adds them to the row. No initialization of the
keys is done.
To free keys in an overlay row, use
XkbFreeGeomOverlayKeys.
XkbFreeGeomOverlayKeysvoid XkbFreeGeomOverlayKeysXkbRowPtr rowint firstint countBool free_allrow
row in which keys should be freed
first
first key to be freed.
count
number of keys to be freed
free_allTrue ⇒ all keys are freed
If free_all is
True,
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.
To allocate doodads that are global to a keyboard geometry, use
XkbAllocGeomDoodads.
XkbAllocGeomDoodadsStatus XkbAllocGeomDoodadsXkbGeometryPtr geomint num_neededgeom
geometry for which doodads should be allocated
num_needed
number of new doodads required
XkbAllocGeomDoodads
allocates num_needed doodads and adds them to the specified geometry
geom.
No initialization of the doodads is done.
To allocate doodads that are specific to a section, use
XkbAllocGeomSectionDoodads.
XkbAllocGeomSectionDoodadsStatus XkbAllocGeomSectionDoodadsXkbSectionPtr sectionint num_neededsection
section for which doodads should be allocated
num_needed
number of new doodads required
XkbAllocGeomSectionDoodads
allocates num_needed doodads and adds them to the specified
section.
No initialization of the doodads is done.
To free geometry doodads, use
XkbFreeGeomDoodads.
XkbFreeGeomDoodadsvoid XkbFreeGeomDoodadsXkbDoodadPtr doodadsint countBool free_alldoodads
doodads to be freed
count
number of doodads to be freed
free_allTrue ⇒ all doodads are freed
If
free_all
is
True,
all doodads in the array are freed, regardless of the value of count.
Otherwise, count doodads are freed.
To allocate an entire geometry, use
XkbAllocGeometry.
XkbAllocGeometryStatus XkbAllocGeometryXkbDescPtr xkbXkbGeometrySizesPtr sizesxkb
keyboard description for which geometry is to be allocated
sizes
initial sizes for all geometry components
XkbAllocGeometry
allocates a keyboard geometry and adds it to the keyboard description
specified by xkb. The keyboard description should be obtained via the
XkbGetKeyboard or XkbAllockeyboard functions. The sizes parameter specifies the
number of elements to be reserved for the subcomponents of the keyboard
geometry and can be zero or more. These subcomponents include the properties,
colors, shapes, sections, and doodads.
To free an entire geometry, use
XkbFreeGeometry.
XkbFreeGeometryvoid XkbFreeGeometryXkbGeometryPtr geomunsigned int whichBool free_allgeom
geometry to be freed
which
mask of geometry components to be freed
free_allTrue ⇒ the entire geometry is freed.
The values of which and free_all determine how much of the specified geometry
is freed. The valid values for which are:
#define XkbGeomPropertiesMask (1<<0)
#define XkbGeomColorsMask (1<<1)
#define XkbGeomShapesMask (1<<2)
#define XkbGeomSectionsMask (1<<3)
#define XkbGeomDoodadsMask (1<<4)
#define XkbGeomAllMask (0x1f)
If free_all is
True,
the entire geometry is freed regardless of the value of which. Otherwise, the
portions of the geometry specified by which are freed.
rlayKeys">
Status Xkb Keyboard Mapping
The Xkb keyboard mapping contains all the information the server and clients
need to interpret key events. This chapter provides an overview of the
terminology used to describe an Xkb keyboard mapping and introduces common
utilities for manipulating the keyboard mapping.
The mapping consists of two components, a server map and a client map. The
client mapclient mapmapclient
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
server mapserver mapmapserver
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.
For detailed information on particular components of the keyboard map, refer to
, and
.
Notation and Terminologylevelshift level
The graphic characters or control functions that may be accessed by one key are
logically arranged in groups and levels, where
group
and
level
are defined as in the ISO9995 standard:
Group:
A logical state of a keyboard providing access to a collection of
graphic characters. Usually these graphic characters logically belong together
and may be arranged on several levels within a group.
Level:
One of several states (normally 2 or 3) governing which graphic
character is produced when a graphic key is actuated. In certain cases the
level may also affect function keys.
These definitions, taken from the ISO standard, refer to graphic keys and
characters. In the context of Xkb, Group and Level are not constrained to
graphic keys and characters; they may be used with any key to access any
character the key is capable of generating.
Level is often referred to as Shift Level.
Levels are numbered sequentially starting at one.
Shift level is derived from the modifier state, but not necessarily
in the same way for all keys. For example, the
Shift
modifier selects shift level 2 on most keys, but for keypad keys the modifier
bound to
Num_Lock
(that is, the
NumLock
virtual modifier) also selects shift level 2.
For example, consider the following key (the gray characters indicate symbols
that are implied or expected but are not actually engraved on the key):
Shift Levels and Groups
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
a,
and the symbol for shift level two is
A.
For the second group, the symbol for shift level one is
æ,
and the symbol for shift level two is
Æ.
Core Implementation
The standard interpretation rules for the core X keymap only allow clients to
access keys such as the one shown in Figure 14.1. That is, clients using the
standard interpretation rules can only access one of four keysyms for any given
KeyPress
event — two different symbols in two different groups.
In general, the
Shift
modifier, the
Lock
modifier, and the modifier bound to the
Num_Lock
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
Mode_switch
key. When the
Mode_switch
modifier is set, the keyboard is logically in Group 2. When the
Mode_switch
modifier is not set, the keyboard is logically in Group 1.
The core implementation does not clearly specify the behavior of keys. For
example, the locking behavior of the
CapsLock
and
Num_Lock
keys depends on the vendor.
Xkb Implementation
Xkb extends the core implementation by providing access to up to four keyboard
groups with up to 63 shift levels per key
The core implementation restricts the number of symbols per key to 255.
With four groups, this allows for up to 63 symbols (or shift levels) per
group. Most keys will only have a few shift levels.
. 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 ).
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.
Xkb handles shift levels by associating a key type with each group on each key.
Each key type defines the shift levels available for the groups on keys of its
type and specifies the modifier combinations necessary to access each level.
For example, Xkb allows key types where the
Control
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.
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.
Getting Map Components from the Server
Xkb provides two functions to obtain the keyboard mapping components from the
server. The first function,
XkbGetMap,
allocates an
XkbDescRec
structure, retrieves mapping components from the server, and stores them in
the
XkbDescRec
structure it just allocated. The second function,
XkbGetUpdatedMap,
retrieves mapping components from the server and stores them in an
XkbDescRec
structure that has previously been allocated.
To allocate an
XkbDescRec
structure and populate it with the server’s keyboard client map and server
map, use
XkbGetMap.
XkbGetMap
is similar to
XkbGetKeyboard
(see section 6.2), but is used only for obtaining the address of an
XkbDescRec
structure that is populated with keyboard mapping components. It allows finer
control over which substructures of the keyboard mapping components are to be
populated.
XkbGetKeyboard
always returns fully populated components, while
XkbGetMap
can be instructed to return a partially populated component.
XkbGetMapXkbDescPtr XkbGetMapDisplay *displayunsigned int whichunsigned int device_specdisplay
connection to X server
which
mask selecting subcomponents to populate
device_spec
device_id, or XkbUseCoreKbd
The
which
mask is a bitwise inclusive OR of the masks defined in
Table 14.1. Only those
portions of the keyboard server map and the keyboard client maps that are
specified in
which
are allocated and populated.
In addition to allocating and obtaining the server map and the client map,
XkbGetMap
also sets the
device_spec,
the
min_key_code,
and
max_key_code
fields of the keyboard description.
XkbGetMap
is synchronous; it queries the server for the desired information, waits for a
reply, and then returns. If successful,
XkbGetMap
returns a pointer to the
XkbDescRec
structure it allocated. If unsuccessful,
XkbGetMap
returns
NULL.
When unsuccessful, one of the following protocol errors is also generated:
BadAlloc
(unable to allocate the
XkbDescRec
structure),
BadValue
(some mask bits in
which
are undefined),
or
BadImplementation
(a compatible version of the Xkb extension is not available in the server). To
free the returned data, use
XkbFreeClientMap.
Xkb also provides convenience functions to get partial component definitions
from the server. These functions are specified in the
convenience functions
column in Table 14.1.
Refer to the sections listed in the table for more
information on these functions.
Xkb Mapping Component Masks and Convenience FunctionsMaskValueMapFieldsConvenience FunctionsSectionXkbKeyTypesMask(1<<0)clienttypessize_typesnum_typesXkbGetKeyTypesXkbResizeKeyTypeXkbCopyKeyTypeXkbCopyKeyTypes15.2XkbKeySymsMask(1<<1)clientsymssize_symsnum_symskey_sym_mapXkbGetKeySymsXkbResizeKeySymsXkbChangeTypesOfKey15.3XkbModifierMapMask(1<<2)clientmodmapXkbGetKeyModifierMap15.4XkbExplicitComponentsMask(1<<3)serverexplicitXkbGetKeyExplicitComponents16.3XkbKeyActionsMask(1<<4)serverkey_actsactsnum_actssize_actsXkbGetKeyActionsXkbResizeKeyActions16.1XkbKeyBehaviorsMask(1<<5)serverbehaviorsXkbGetKeyBehaviors16.2XkbVirtualModsMask(1<<6)servervmodsXkbGetVirtualMods16.4XkbVirtualModMapMask(1<<7)servervmodmapXkbGetVirtualModMap16.4
Xkb defines combinations of these masks for convenience:
#define XkbResizableInfoMask (XkbKeyTypesMask)
#define XkbAllClientInfoMask (XkbKeyTypesMask | XkbKeySymsMask |
XkbModifierMapMask)
#define XkbAllServerInfoMask (XkbExplicitComponentsMask |
XkbKeyActionsMask| XkbKeyBehaviorsMask |
XkbVirtualModsMask | XkbVirtualModMapMask)
#define XkbAllMapComponentsMask (XkbAllClientInfoMask|XkbAllServerInfoMask)
Key types, symbol maps, and actions are all interrelated: changes in one
require changes in the others. The convenience functions make it easier to edit
these components and handle the interdependencies.
To update the client or server map information in an existing keyboard
description, use XkbGetUpdatedMap.
XkbGetUpdatedMapStatus XkbGetUpdatedMapDisplay *displayunsigned int whichXkbDescPtr xkbdisplay
connection to X server
which
mask selecting subcomponents to populate
xkb
keyboard description to be updated
The
which
parameter is a bitwise inclusive OR of the masks in
Table 14.1.
If the needed components of the
xkb
structure are not already allocated,
XkbGetUpdatedMap
allocates them.
XkbGetUpdatedMap
fetches the requested information for the device specified in the
XkbDescRec
passed in the
xkb
parameter.
XkbGetUpdatedMap
is synchronous; it queries the server for the desired information, waits for a
reply, and then returns. If successful,
XkbGetUpdatedMap
returns
Success.
If unsuccessful,
XkbGetUpdatedMap
returns one of the following:
BadAlloc
(unable to allocate a component in the
XkbDescRec
structure),
BadValue
(some mask bits in
which
are undefined),
BadImplementation
(a compatible version of the Xkb extension is not available in the server or
the reply from the server was invalid).
Changing Map Components in the Server
There are two ways to make changes to map components: either change a local
copy of the keyboard map and call
XkbSetMap
to send the modified map to the server, or, to reduce network traffic, use
an
XkbMapChangesRec
structure and call XkbChangeMap.
XkbSetMapBool XkbSetMapDisplay *dpyunsigned int whichXkbDescPtr xkbdpy
connection to X server
which
mask selecting subcomponents to update
xkb
description from which new values are taken
Use
XkbSetMap
to send a complete new set of values for entire components (for example, all
symbols, all actions, and so on) to the server. The
which
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
xkb
parameter is a pointer to an
XkbDescRec
structure and contains the information to be copied to the server. For each
bit set in the
which
parameter,
XkbSetMap
takes the corresponding structure values from the
xkb
parameter and sends it to the server specified by
dpy.
If any components specified by
which
are not present in the
xkb
parameter,
XkbSetMap
returns
False.
Otherwise, it sends the update request to the server and returns
True.
XkbSetMap
can generate
BadAlloc,
BadLength,
and
BadValue
protocol errors.
Key types, symbol maps, and actions are all interrelated; changes in one
require changes in the others. Xkb provides functions to make it easier to edit
these components and handle the interdependencies.
Table 14.1 lists these
helper functions and provides a pointer to where they are defined.
The XkbMapChangesRec StructureXkbMapChangesRec
Use the
XkbMapChangesRec
structure to identify and track partial modifications to the mapping
components and to reduce the amount of traffic between the server and clients.
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 type
modified */
unsigned char num_types; /* # types modified */
KeyCode first_key_sym; /* first key whose key_sym_map
changed */
unsigned char num_key_syms; /* # key_sym_map
entries changed */
KeyCode first_key_act; /* first key whose key_acts
entry changed */
unsigned char num_key_acts; /* # key_acts
entries changed */
KeyCode first_key_behavior; /* first key whose behaviors
changed */
unsigned char num_key_behaviors; /* # behaviors
entries changed */
KeyCode first_key_explicit; /* first key whose explicit
entry changed */
unsigned char num_key_explicit; /* # explicit
entries changed */
KeyCode first_modmap_key; /* first key whose modmap
entry changed */
unsigned char num_modmap_keys; /* # modmap
entries changed */
KeyCode first_vmodmap_key; /* first key whose vmodmap
changed */
unsigned char num_vmodmap_keys; /* # vmodmap
entries changed */
unsigned char pad1; /* reserved */
unsigned short vmods; /* mask indicating which vmods
changed */
} XkbMapChangesRec, *XkbMapChangesPtr;
The
changed
field identifies the map components that have changed in an
XkbDescRec
structure and may contain any of the bits in
Table 14.1, which are also shown
in Table 14.2. Every 1 bit in
changed
also identifies which other fields in the
XkbMapChangesRec
structure contain valid values, as indicated in
Table 14.2. The
min_key_code
and
max_key_code
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
XkbMapChangesRec.
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
XkbChangeMap
with an
XkbMapChangesRec
structure indicating which components have changed.
XkbChangeMapBool XkbChangeMapDisplay *dpyXkbDescPtr xkbXkbMapChangesPtr changesdpy
connection to X server
xkb
description from which new values are taken
changes
identifies component parts to update
XkbChangeMap
copies any components specified by the
changes
structure from the keyboard description,
xkb,
to the X server specified by
dpy.
If any components specified by
changes
are not present in the
xkb
parameter,
XkbChangeMap
returns
False.
Otherwise, it sends a request to the server and returns
True.
XkbChangeMap
can generate
BadAlloc,
BadLength,
and
BadValue
protocol errors.
Tracking Changes to Map ComponentseventsXkbMapNotifyXkbMapNotifyEvent
The Xkb extension reports
XkbMapNotify
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.
To receive
XkbMapNotify
events under all possible conditions, use
XkbSelectEvents
(see section 4.3) and pass
XkbMapNotifyMask
in both
bits_to_change
and
values_for_bits.
To receive
XkbMapNotify
events only under certain conditions, use
XkbSelectEventDetails
using
XkbMapNotify
as the
event_type
and specifying the desired map changes in
bits_to_change
and
values_for_bits
using mask bits from Table 14.1.
The structure for
XkbMapNotify
events is:
typedef struct {
int type; /* Xkb extension base event code */
unsigned long serial; /* X server serial number for event */
Bool send_event; /* True ⇒ synthetically generated */
Display * display; /* server connection where event generated */
Time time; /* server time when event generated */
int xkb_type; /* XkbMapNotify */
int device; /* Xkb device ID, will not be XkbUseCoreKbd */
unsigned int changed; /* identifies valid fields in rest of event */
unsigned int resized; /* reserved */
int first_type; /* index of first key type 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 key_sym_map changed */
KeyCode first_key_act; /* first key whose key_acts entry changed */
KeyCode first_key_behavior; /* first key whose behaviors changed */
KeyCode first_key_explicit; /* first key whose explicit entry changed */
KeyCode first_modmap_key; /* first key whose modmap entry changed */
KeyCode first_vmodmap_key; /* # modmap entries changed */
int num_key_syms; /* # key_sym_map entries changed */
int num_key_acts; /* # key_acts entries changed */
int num_key_behaviors; /* # behaviors entries changed */
int num_key_explicit; /* # explicit entries changed */
int num_modmap_keys; /* # modmap entries changed */
int num_vmodmap_keys; /* # vmodmap entries changed */
unsigned int vmods; /* mask indicating which vmods changed */
} XkbMapNotifyEvent;
The
changed
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
XkbMapChangesRec
(see section 14.3.1). The
XkbMapNotifyEvent
structure also has an additional
resized
field that is reserved for future use.
Allocating and Freeing Client and Server Maps
Calling
XkbGetMap
(see section 14.2) should be sufficient for most applications to get client
and server maps. As a result, most applications do not need to directly
allocate client and server maps.
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
malloc
or
Xmalloc.
Instead, use the Xkb allocators,
XkbAllocClientMap,
and
XkbAllocServerMap.
Similarly, use the Xkb destructors,
XkbFreeClientMap,
and
XkbFreeServerMap
instead of
free
or
Xfree.
Allocating an Empty Client Map
To allocate and initialize an empty client map description record, use
XkbAllocClientMap.
XkbAllocClientMapStatus XkbAllocClientMapXkbDescPtr xkbunsigned int whichunsigned int type_countxkb
keyboard description in which to allocate client map
which
mask selecting map components to allocate
type_count
value of num_types field in map to be allocated
XkbAllocClientMap
allocates and initializes an empty client map in the
map
field of the keyboard description specified by
xkb.
The
which
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.
XkbAllocClientMap MasksMaskEffectXkbKeyTypesMask
The
type_count
field specifies the number of entries to preallocate for the
types
field of the client map. If the
type_count
field is less than
XkbNumRequiredTypes
(see section 15.2.1), returns
BadValue.
XkbKeySymsMask
The
min_key_code
and
max_key_code
fields of the
xkb
parameter are used to allocate the
syms
and
key_sym_map
fields of the client map. The fields are allocated to contain the maximum
number of entries necessary for
max_key_code
−
min_key_code
+ 1 keys.
XkbModifierMapMask
The
min_key_code
and
max_key_code
fields of the
xkb
parameter are used to allocate the
modmap
field of the client map. The field is allocated to contain the maximum number
of entries necessary for
max_key_code
−
min_key_code
+ 1 keys.
The
min_key_code
and
max_key_code
fields of the
xkb
parameter must be legal values if the
XkbKeySymsMask
or
XkbModifierMapMask
masks are set in the
which
parameter. If they are not valid,
XkbAllocClientMap
returns
BadValue.
If the client map of the keyboard description is not
NULL,
and any fields are already allocated in the client map,
XkbAllocClientMap
does not overwrite the existing values; it simply ignores that part of the
request. The only exception is the
types
array. If
type_count
is greater than the current
num_types
field of the client map,
XkbAllocClientMap
resizes the
types
array and resets the
num_types
field accordingly.
If
XkbAllocClientMap
is successful, it returns
Success.
Otherwise, it can return either
BadMatch,
BadAlloc,
or
BadValue
errors.
Freeing a Client Map
To free memory used by the client map member of an
XkbDescRec
structure, use
XkbFreeClientMap.
XkbFreeClientMapvoid XkbFreeClientMapXkbDescPtr xkbunsigned int whichBool free_allxkb
keyboard description containing client map to free
which
mask identifying components of map to free
free_allTrue
⇒ free all client components and map itself
XkbFreeClientMap
frees the components of client map specified by
which
in the
XkbDescRec
structure specified by the
xkb
parameter and sets the corresponding structure component values to
NULL.
The
which
parameter specifies a combination of the client map masks shown in
Table 14.3.
If
free_all
is
True,
which
is ignored;
XkbFreeClientMap
frees every non-
NULL
structure component in the client map, frees the
XkbClientMapRec
structure referenced by the
map
member of the
xkb
parameter, and sets the
map
member to
NULL.
Allocating an Empty Server Map
To allocate and initialize an empty server map description record, use
XkbAllocServerMap.
XkbAllocServerMapStatus XkbAllocServerMapXkbDescPtr xkbunsigned int whichunsigned int count_actsxkb
keyboard description in which to allocate server map
which
mask selecting map components to allocate
count_acts
value of num_acts field in map to be allocated
XkbAllocServerMap
allocates and initializes an empty server map in the
server
field of the keyboard description specified by
xkb.
The
which
parameter specifies the particular components of the server map structure to
allocate, as specified in Table 14.4.
XkbAllocServerMap MasksMaskEffectXkbExplicitComponentsMask
The
min_key_code
and
max_key_code
fields of the
xkb
parameter are used to allocate the
explicit
field of the server map.
XkbKeyActionsMask
The
min_key_code
and
max_key_code
fields of the
xkb
parameter are used to allocate the
key_acts
field of the server map. The
count_acts
parameter is used to allocate the
acts
field of the server map.
XkbKeyBehaviorsMask
The
min_key_code
and
max_key_code
fields of the
xkb
parameter are used to allocate the
behaviors
field of the server map.
XkbVirtualModMapMask
The
min_key_code
and
max_key_code
fields of the
xkb
parameter are used to allocate the
vmodmap
field of the server map.
The
min_key_code
and
max_key_code
fields of the
xkb
parameter must be legal values. If they are not valid,
XkbAllocServerMap
returns
BadValue.
If the server map of the keyboard description is not
NULL
and any fields are already allocated in the server map,
XkbAllocServerMap
does not overwrite the existing values. The only exception is with the
acts
array. If the
count_acts
parameter is greater than the current
num_acts
field of the server map,
XkbAllocServerMap
resizes the
acts
array and resets the
num_acts
field accordingly.
If
XkbAllocServerMap
is successful, it returns
Success.
Otherwise, it can return either
BadMatch
or
BadAlloc
errors.
Freeing a Server Map
To free memory used by the server member of an
XkbDescRec
structure, use
XkbFreeServerMap.
XkbFreeServerMapvoid XkbFreeServerMapXkbDescPtr xkbunsigned int whichBool free_allxkb
keyboard description containing server map to free
which
mask identifying components of map to free
free_allTrue
⇒ free all server map components and server itself
The
XkbFreeServerMap
function frees the specified components of server map in the
XkbDescRec
structure specified by the
xkb
parameter and sets the corresponding structure component values to
NULL.
The
which
parameter specifies a combination of the server map masks and is a bitwise
inclusive OR of the masks listed in
Table 14.4. If
free_all
is
True,
which
is ignored and
XkbFreeServerMap
frees every non-
NULL
structure component in the server map, frees the
XkbServerMapRec
structure referenced by the
server
member of the
xkb
parameter, and sets the
server
member to
NULL.
s that part of the
request. The only exception is the
types
array. If
type_count
is greater than the current
num_types
field of the client map,
XkbAllocClientMap
resizes the
types
array and resets the
num_types
field accordingly.
If
XkbAllolibX11-1.6.3/specs/XKB/ch05.xml 0000644 0143106 0000012 00000105015 12477417235 0016102 0 ustar 00alanc staff 0000266 0200006
Keyboard State
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.
Xkb StateKeyboard State Description
The Xkb keyboard state is comprised of the state of all keyboard modifiers, the keyboard group, and the state of the pointer buttons. These are grouped into the following components:
The locked group and locked modifiers
The latched group and latched modifiers
The base group and base modifiers
The effective group and effective modifiers
The state of the core pointer buttons
The
modifiersmodifiers
are
Shift,
Lock,
Control,
and
Mod1
–
Mod5,
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.
The Xkb extension provides support for
keysym groups,
keysym groupsgroupkeysymgroupISO9995
as defined by ISO9995:
Group
A logical state of a keyboard providing access to a collection of characters.
A group usually contains a set of characters that logically belong together
and that may be arranged on several shift levels within that group.
The Xkb extension supports up to four keysym groups. Groups are named beginning with one and indexed beginning with zero. All group states are indicated using the group index. At any point in time, there is zero or one locked group, zero or one latched group, and one base group. When a group is locked, it supersedes any previous locked group and remains the locked group for all future key events, until a new group is locked. A latched group applies only to the next key event that does not change the keyboard state. The locked and latched group can be changed by keyboard activity or via Xkb extension library functions.
Changing to a different group changes the keyboard state to produce characters from a different group. Groups are typically used to switch between keysyms of different languages and locales.
The
pointer buttons
are
Button1
–
Button5,
as defined by the core protocol.
The
base groupbase groupgroupbase
and
base modifiersbase modifiersmodifiersbase
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.
Keys may be logically down when they are physically up because
of their electrical properties or because of the keyboard extension
in the X server having filtered the key release, for esoteric reasons.
The
effective modifierseffective modifiersmodifierseffective
are the bitwise union of the locked, latched, and the base modifiers.
The
effective groupeffective groupgroupeffective
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.
n = number of keyboard groups, 1<= n <= 4
0 <= any of locked, latched, or base group < n
effective group = f(locked group + latched group + base group)
The function f ensures that the effective group is within range. The precise function is specified for the keyboard and can be retrieved through the keyboard description. It may wrap around, clamp down, or default. Few applications will actually examine the effective group, and far fewer still will examine the locked, latched, and base groups.
There are two circumstances under which groups are normalized:
The global locked or effective group changes. In this case, the changed group is normalized into range according to the settings of the
groups_wrap
field of the
XkbControlsRec
structure for the keyboard (see section 10.7.1).
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
group_info
field of the key symbol mapping
(XkbSymMapRec)
for the event key.
Each nonmodifier key on a keyboard has zero or more symbols, or keysyms, associated with it. These are the logical symbols that the key can generate when it is pressed. The set of all possible keysyms for a keyboard is divided into groups. Each key is associated with zero or more groups; each group contains one or more symbols. When a key is pressed, the determination of which symbol for the key is selected is based on the effective group and the shift level, which is determined by which modifiers are set.
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
Xkb-capable.
Xkb-capable client
A client that does explicitly call Xkb functions is an
Xkb-awareXkb-aware client
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:
lookup state: lookup group and lookup modifiers
grab state: grab group and grab modifiers
The
lookup modifierslookup modifiersmodifierslookup
and
lookup grouplookup groupgrouplookup
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
KeyPress
and
KeyRelease
events, the lookup modifiers are computed as:
((base | latched | locked) & ~server_internal_modifiers)
Otherwise the lookup modifiers are computed as:
(((base | latched | (locked & ~ignore_locks)) & ~server_internal_modifiers)
The lookup group is the same as the effective group.
When an Xkb-capable or Xkb-aware client wishes to map a keycode to a keysym, it should use the
lookup statelookup statestatelookup
— the lookup group and the lookup modifiers.
The
grab stategrab statestategrab
is the state used when matching events to passive grabs. If the event activates a grab, the
grab modifiersgrab modifiersmodifiersgrab
and
grab groupgrab groupgroupgrab
are represented in the state field of core X events; otherwise, the lookup state is used. The grab modifiers are computed as:
(((base | latched | (locked & ~ignore_locks)) & ~server_internal_modifiers)
If the server’s
IgnoreGroupLock
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.
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
(Xkb-unaware
clients):
The compatibility modifier state
The compatibility lookup modifier state
The compatibility grab modifier state
The X11 protocol interpretation of modifiers does not include direct support for multiple groups. When an Xkb-extended X server connects to an Xkb-unaware client, the compatibility states remap the keyboard group into a core modifier whenever possible. The compatibility state corresponds to the effective modifier and effective group state, with the group remapped to a modifier. The compatibility lookup and grab states correspond to the lookup and grab states, respectively, with the group remapped to a modifier. The compatibility lookup state is reported in events that do not trigger passive grabs; otherwise, the compatibility grab state is reported.
Changing the Keyboard StateChanging Modifiersreal modifiersmodifiersrealmaskreal modifiers
The functions in this section that change the use of modifiers use a mask in the parameter
affect.
It is a bitwise inclusive OR of the legal modifier masks:
Real Modifier MasksMaskShiftMaskLockMaskControlMaskMod1MaskMod2MaskMod3MaskMod4MaskMod5Mask
To lock and unlock any of the eight real keyboard modifiers, use
XkbLockModifiers:
XkbLockModifiersBool XkbLockModifiersDisplay *displayunsigned int device_specunsigned int affectunsigned int valuesdisplay
connection to the X server
device_spec
device ID, or XkbUseCoreKbdaffect
mask of real modifiers whose lock state is to change
values
1 ⇒ lock, 0 ⇒ unlock; only for modifiers selected by affectXkbLockModifiers
sends a request to the server to lock the real modifiers selected by both
affect
and
values
and to unlock the real modifiers selected by
affect
but not selected by
values.
XkbLockModifiers
does not wait for a reply from the server. It returns
True
if the request was sent, and
False
otherwise.
To latch and unlatch any of the eight real keyboard modifiers, use
XkbLatchModifiers:
XkbLatchModifiersBool XkbLatchModifiersDisplay *displayunsigned int device_specunsigned int affectunsigned int valuesdisplay
connection to the X server
device_spec
device ID, or XkbUseCoreKbdaffect
mask of modifiers whose latch state is to change
values
1 ⇒ latch, 0 ⇒ unlatch; only for mods selected by affectXkbLatchModifiers
sends a request to the server to latch the real modifiers selected by both
affect
and
values
and to unlatch the real modifiers selected by
affect
but not selected by
values.
XkbLatchModifiers
does not wait for a reply from the server. It returns
True
if the request was sent, and
False
otherwise.
Changing Groupskeysym groupsgroupkeysym
Reference the keysym group indices with these symbolic constants:
Symbolic Group NamesSymbolic NameValueXkbGroup1Index0XkbGroup2Index1XkbGroup3Index2XkbGroup4Index3
To lock the keysym group, use
XkbLockGroup.
XkbLockGroupBool XkbLockGroupDisplay *displayunsigned int device_specunsigned int groupdisplay
connection to the X server
device_spec
device ID, or XkbUseCoreKbdgroup
index of the keysym group to lock
XkbLockGroup
sends a request to the server to lock the specified
group
and does not wait for a reply. It returns
True
if the request was sent and
False
otherwise.
To latch the keysym group, use
XkbLatchGroup.
XkbLatchGroupBool XkbLatchGroupDisplay *displayunsigned int device_specunsigned int groupdisplay
connection to the X server
device_spec
device ID, or XkbUseCoreKbdgroup
index of the keysym group to latch
XkbLatchGroup
sends a request to the server to latch the specified group and does not wait for a reply. It returns
True
if the request was sent and
False
otherwise.
Determining Keyboard StateXkbStateRec
Xkb keyboard state may be represented in an
XkbStateRec
structure:
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; /* 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 */
} XkbStateRec, *XkbStatePtr;
To obtain the keyboard state, use
XkbGetState.
XkbGetStateStatus XkbGetStateDisplay *displayunsigned int device_specXkbStatePtr state_returndisplay
connection to the X server
device_spec
device ID, or XkbUseCoreKbdstate_return
backfilled with Xkb state
The
XkbGetState
function queries the server for the current keyboard state, waits for a reply, and then backfills
state_return
with the results.
All group values are expressed as group indices in the range [0..3]. Modifiers and the compatibility modifier state values are expressed as the bitwise union of the core X11 modifier masks. The pointer button state is reported as in the core X11 protocol.
Tracking Keyboard StateeventsXkbStateNotifyXkbStateNotifyEvent
The Xkb extension reports
XkbStateNotify
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,
XkbStateNotify
events are reported to all interested clients without regard to the current keyboard input focus or grab state.
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.
To track changes in the keyboard state for a particular device, select to receive
XkbStateNotify
events by calling either
XkbSelectEvents
or
XkbSelectEventDetails
(see section 4.3).
To receive
XkbStateNotify
events under all possible conditions, use
XkbSelectEvents
and pass
XkbStateNotifyMask
in both
bits_to_change
and
values_for_bits.
To receive
XkbStateNotify
events only under certain conditions, use
XkbSelectEventDetails
using
XkbStateNotify
as the
event_type
and specifying the desired state changes in
bits_to_change
and
values_for_bits
using mask bits from Table 5.3.
The structure for
XkbStateNotify
events is:
typedef struct {
int type; /* Xkb extension base event code */
unsigned long serial; /* X server serial number for event */
Bool send_event; /* True ⇒ synthetically generated */
Display * display; /* server connection where event generated */
Time time; /* server time when event generated */
int xkb_type; /* XkbStateNotify */
int device; /* Xkb device ID,
will not be XkbUseCoreKbd */
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 req_major or req_minor
non zero */
char req_major; /* major request code if program trigger,
else 0 */
char req_minor; /* minor request code if program trigger,
else 0 */
} XkbStateNotifyEvent;
When you receive an
XkbStateNotify
event, the
changed
field indicates which elements of keyboard state have changed.
This will be the bitwise inclusive OR of one or more of the
XkbStateNotify
event detail masks shown in Table 5.3.
All fields reported in the event are valid, but only those indicated in
changed
have changed values.
The
group
field is the group index of the effective keysym group. The
base_group,
latched_group,
and
locked_group
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 ptr_buttons
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.
Xkb state changes can occur either in response to keyboard
activity or under application control. If a key event
caused the state change, the
keycode
field gives the keycode of the key event, and the
event_type
field is set to either KeyPress
or
KeyRelease.
If a pointer button event caused the state change, the
keycode
field is zero, and the event_type
field is set to either ButtonPress
or ButtonRelease.
Otherwise, the major and minor codes of the request that caused the
state change are given in the
req_major
and
req_minor
fields, and the
keycode
field is zero. The
req_major
value is the same as the major extension opcode.
ction>XkbGetStateStatus XkbGetStateDisplay *displayunsigned int device_specXkbStatePtr state_returnInitialization and General Programming InformationExtension Header Files
The following include files are part of the Xkb standard:
<X11/XKBlib.h>XKBlib.h
is the main header file for Xkb; it declares constants, types, and
functions.
<X11/extensions/XKBstr.h>XKBstr.h declares types and
constants for Xkb. It is included automatically from
<X11/XKBlib.h>;
you should never need to reference it directly in your application code.
<X11/extensions/XKB.h>XKB.h
defines constants for Xkb. It is included automatically from
<X11/XKBstr.h>;
you should never need to reference it directly in your application code.
<X11/extensions/XKBgeom.h>XKBgeom.h
declares types, symbolic constants, and functions for manipulating
keyboard geometry descriptions.
Extension NameXkbName
The name of the Xkb extension is given in
<X11/extensions/Xkb.h>:
#define XkbName "XKEYBOARD"
Most extensions to the X protocol are initialized by calling
XInitExtension
and passing the extension name. However, as explained in section 2.4, Xkb
requires a more complex initialization sequence, and a client program should
not call
XInitExtension
directly.
Determining Library Compatibility
If an application is dynamically linked, both the X server and the client-side
X library must contain the Xkb extension in order for the client to use the Xkb
extension capabilities. Therefore a dynamically linked application must check
both the library and the server for compatibility before using Xkb function
calls. A properly written program must check for compatibility between the
version of the Xkb library that is dynamically loaded and the one used when the
application was built. It must then check the server version for compatibility
with the version of Xkb in the library.
If your application is statically linked, you must still check for server
compatibility and may check library compatibility. (It is possible to compile
against one set of header files and link against a different, incompatible,
version of the library, although this should not normally occur.)
To determine the compatibility of a library at runtime, call
XkbLibraryVersion.
XkbLibraryVersionBool XkbLibraryVersionint *lib_major_in_outint *lib_minor_in_outlib_major_in_out
specifies and returns the major Xkb library version.
lib_minor_in_out
specifies and returns the minor Xkb library version.
Pass the symbolic value
XkbMajorVersion
in
lib_major_in_out
and
XkbMinorVersion
in
lib_minor_in_out.
These arguments represent the version of the library used at compile time.
The
XkbLibraryVersion
function backfills the major and minor version numbers of the library used at
run time in
lib_major_in_out
and
lib_minor_in_out.
If the versions of the compile time and run time libraries are compatible,
XkbLibraryVersion
returns
True,
otherwise, it returns
False.
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
XkbQueryExtension
to do this, as described in the next section.
Initializing the Keyboard Extension
Call
XkbQueryExtension
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
(XQueryExtension
and
XInitExtension)
for checking for the presence of, and initializing the Xkb extension.
You must call
XkbQueryExtension
or
XkbOpenDisplay
before using any other Xkb library interfaces, unless such usage is explicitly
allowed in the interface description in this document. The exceptions are:
XkbIgnoreExtension,
XkbLibraryVersion,
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
BadAccess
protocol errors.
errorsBadAccessBadAccessXkbQueryExtension
both determines whether a compatible Xkb extension is present in the X server
and initializes the extension when it is present.
XkbQueryExtensionBool XkbQueryExtensionDisplay *dpyint *opcode_rtrnint *event_rtrnint *error_rtrnint *major_in_outint *minor_in_outdpy
connection to the X server
opcode_rtrn
backfilled with the major extension opcode
event_rtrn
backfilled with the extension base event code
error_rtrn
backfilled with the extension base error code
major_in_out
compile time lib major version in, server major version out
minor_in_out
compile time lib min version in, server minor version out
The
XkbQueryExtension
function determines whether a compatible version of the X Keyboard Extension
is present in the server. If a compatible extension is present,
XkbQueryExtension
returns
True;
otherwise, it returns
False.
If a compatible version of Xkb is present,
XkbQueryExtension
initializes the extension. It backfills the major opcode for the keyboard
extension in
opcode_rtrn,
the base event code in
event_rtrn,
the base error code in
error_rtrn,
and the major and minor version numbers of the extension in
major_in_out
and
minor_in_out.
The major opcode is reported in the
req_major
fields of some Xkb events. For a discussion of the base event code, see
section 4.1.
As a convenience, you can use the function
XkbOpenDisplay
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.
XkbOpenDisplayDisplay *XkbOpenDisplaychar *display_nameint *event_rtrnint *error_rtrnint *major_in_outint *minor_in_outint *reason_rtrndisplay_name
hardware display name, which determines the display and
communications domain to be used
event_rtrn
backfilled with the extension base event code
error_rtrn
backfilled with the extension base error code
major_in_out
compile time lib major version in, server major version out
minor_in_out
compile time lib minor version in, server minor version out
reason_rtrn
backfilled with a status code
XkbOpenDisplay
is a convenience function that opens an X display connection and initializes
the X keyboard extension. In all cases, upon return
reason_rtrn
contains a status value indicating success or the type of failure. If
major_in_out
and
minor_in_out
are not
NULL,
XkbOpenDisplay
first calls
XkbLibraryVersion
to determine whether the client library is compatible, passing it the values
pointed to by
major_in_out
and
minor_in_out.
If the library is incompatible,
XkbOpenDisplay
backfills
major_in_out
and
minor_in_out
with the major and minor extension versions of the library being used and
returns
NULL.
If the library is compatible,
XkbOpenDisplay
next calls
XOpenDisplay
with the
display_name.
If this fails, the function returns
NULL.
If successful,
XkbOpenDisplay
calls
XkbQueryExtension
and
backfills the major and minor Xkb server extension version numbers in
major_in_out
and
minor_in_out.
If the server extension version is not compatible with the library extension
version or if the server extension is not present,
XkbOpenDisplay
closes the display and returns
NULL.
When successful, the function returns the display connection.
The possible values for
reason_rtrn are:
XkbOD_BadLibraryVersion
indicates
XkbLibraryVersion
returned
False.
XkbOD_ConnectionRefused
indicates the display could not be opened.
XkbOD_BadServerVersion
indicates the library and the server have incompatible extension versions.
XkbOD_NonXkbServer
indicates the extension is not present in the X server.
XkbOD_Success
indicates that the function succeeded.
Disabling the Keyboard Extension
If a server supports the Xkb extension, the X library normally implements
preXkb keyboard functions using the Xkb keyboard description and state. The
server Xkb keyboard state may differ from the preXkb keyboard state. This
difference does not affect most clients, but there are exceptions. To allow
these clients to work properly, you may instruct the extension not to use Xkb
functionality.
Call
XkbIgnoreExtension
to prevent core X library keyboard functions from using the X Keyboard
Extension. You must call
XkbIgnoreExtension
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.
XkbIgnoreExtensionBool XkbIgnoreExtensionBool ignoreignoreTrue means ignore the extension
XkbIgnoreExtension
tells the X library whether to use the X Keyboard Extension on any
subsequently opened X display connections. If ignore is
True,
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
False,
the library treats subsequent calls to
XOpenDisplay
normally and uses Xkb extension requests, events, and state. Do not explicitly
use Xkb on a connection for which it is disabled.
XkbIgnoreExtension
returns
False
if it was unable to apply the ignore request.
Protocol Errorserrors
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
BadXxx
protocol error, where
Xxx
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.
Table 2.1
lists the protocol errors that can be generated, and their causes.
Xkb Protocol ErrorsErrorCauseBadAccess
The Xkb extension has not been properly initialized
BadKeyboard
The device specified was not a valid core or input extension device
BadImplementation
Invalid reply from server
BadAlloc
Unable to allocate storage
BadMatch
A compatible version of Xkb was not available in the server or an argument has
correct type and range, but is otherwise invalid
BadValue
An argument is out of range
BadAtom
A name is neither a valid Atom or
NoneBadDevice
Device, Feedback Class, or Feedback ID invalid
errorsBadKeyboardBadKeyboard
The Xkb extension adds a single protocol error,
BadKeyboard,
to the core protocol error set. This error code will be reported as the
error_rtrn
when
XkbQueryExtension
is called. When a
BadKeyboard
error is reported in an
XErrorEvent,
additional information is reported in the
resourceid
field. The most significant byte of the
resource_id
is a further refinement of the error cause, as defined in
Table 2.2. The least
significant byte will contain the device, class, or feedback ID as indicated in
the table.
<errorname>BadKeyboard</errorname> Protocol Error resource_id Valueshigh-order bytevaluemeaninglow-order byteXkbErr_BadDevice0xff
device not found
device IDXkbErr_BadClass0xfe
device found, but it is of the wrong class
class IDXkbErr_BadId0xfd
device found, class ok, but device does not contain a feedback with the
indicated ID
feedback ID
Display and Device Specifications in Function Calls
Where a connection to the server is passed as an argument (Display*) and an
XkbDescPtr
is also passed as an argument, the Display* argument must match the
dpy
field of the
XkbDescRec
pointed to by the
XkbDescPtr
argument, or else the
dpy
field of the
XkbDescRec
must be
NULL.
If they don’t match or the
dpy
field is not
NULL,
a
BadMatch
error is returned (either in the return value or a backfilled
Status
variable). Upon successful return, the
dpy
field of the
XkbDescRec
always contains the Display* value passed in.
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 *
dpy)
and a device identifier (unsigned int
device_spec).
In some cases, the device identifier is implicit and is taken as the
device_spec
field of an
XkbDescRec
structure passed as an argument.
XkbUseCoreKbd
The device identifier can specify any X input extension device with a
KeyClass
component, or it can specify the constant,
XkbUseCoreKbd.
The use of
XkbUseCoreKbd
allows applications to indicate the core keyboard without having to determine
its device identifier.
Where an Xkb device identifier is passed as an argument and an
XkbDescPtr
is also passed as an argument, if either the argument or the
XkbDescRecdevice_spec
field is
XkbUseCoreKbd,
and if the function returns successfully, the
XkbDescPtrdevice_spec
field will have been converted from
XkbUseCoreKbd
to a real Xkb device ID. If the function does not complete successfully, the
device_spec
field remains unchanged. Subsequently, the device id argument must match the
device_spec
field of the
XkbDescPtr
argument. If they don’t match, a
BadMatch
error is returned (either in the return value or a backfilled
Status
variable).
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
XkbUseCoreKbd,
XkbUseCoreKbd
will work and the identifier returned by the server will refer to the core
keyboard device.
tension, the X library normally implements
preXkb keyboard functions using the Xkb keyboard description and state. The
server Xkb keyboard state may differ from the preXkb keyboard state. This
difference does not affect most clients, but there are exceptions. To allow
these clients to work properly, you may instruct the extension not to use Xkb
functionality.
Call
XkbIgnoreExtension
to prevent core X library keyboard functions from libX11-1.6.3/specs/XKB/XKBlib-5.svg 0000644 0143106 0000012 00000073122 12477417235 0016622 0 ustar 00alanc staff 0000266 0200006
0.5 0.140625,-0.3125 0.671875,-1.21875 1.625,-1.21875 0.453125,0 0.53125,0.375 0.53125,0.703125 0,0.609375 -0.484375,1.890625 -0.640625,2.3125 C 3.578125,-0.9375 3.5625,-0.8125 3.5625,-0.703125 c 0,0.46875 0.359375,0.8125 0.828125,0.8125 0.9375,0 1.296875,-1.453125 1.296875,-1.53125 0,-0.109375 -0.078125,-0.109375 -0.109375,-0.109375 -0.109375,0 -0.109375,0.03125 -0.15625,0.1875 -0.203125,0.671875 -0.53125,1.234375 -1.015625,1libX11-1.6.3/specs/XKB/XKBlib-2.svg 0000644 0143106 0000012 00000077235 12477417235 0016630 0 ustar 00alanc staff 0000266 0200006
id="text8147-3-1-6"
y="145.50685"
x="269.78455"
style="font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:DejaVu SanlibX11-1.6.3/specs/XKB/ch08.xml 0000644 0143106 0000012 00000171201 12477417235 0016105 0 ustar 00alanc staff 0000266 0200006
Indicatorsindicators
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
CapsLock
LED, but X does not provide a mechanism to make the LED automatically follow
the logical state of the
CapsLock
key.
Furthermore, the core X implementation does not provide clients with the
ability to determine what bits in the
led_mask
field of the
XKeyboardState
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
led_mask
field to turn on the
Scroll Lock
LED or whether the keyboard even has a
Scroll Lock
LED.
Xkb provides indicator names and programmable indicators to help solve these
problems. Using Xkb, clients can determine the names of the various indicators,
determine and control the way that the individual indicators should be updated
to reflect keyboard changes, and determine which of the 32 keyboard indicators
reported by the protocol are actually present on the keyboard. Clients may also
request immediate notification of changes to the state of any subset of the
keyboard indicators, which makes it straightforward to provide an on-screen
virtual LED panel.
This chapter describes Xkb indicators and the functions
used for manipulating them.
Indicator Names
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
XkbSetNames
as discussed in . Then set the map using
XkbSetMap
(see section 14.3)
or
XkbSetNamedIndicator
(below). To retrieve indicator names, use
XkbGetNames
().
Indicator Data Structures
Use the indicator description record,
XkbIndicatorRec,
and its indicator map,
XkbIndicatorMapRec,
to inquire about and control most indicator properties and behaviors.
XkbIndicatorRecXkbIndicatorRec
The description for all the Xkb indicators is held in the
indicators
field of the complete keyboard description (see ), which is defined
as follows:
#define XkbNumIndicators 32
typedef struct {
unsigned long phys_indicators; /* LEDs existence */
XkbIndicatorMapRec maps[XkbNumIndicators]; /* indicator maps */
} XkbIndicatorRec, *XkbIndicatorPtr;
This structure contains the
phys_indicators
field, which relates some information about the correspondence between
indicators and physical LEDs on the keyboard, and an array of indicator
maps,
one map per indicator.
The
phys_indicators
field indicates which indicators are bound to physical LEDs on the keyboard;
if a bit is set in
phys_indicators,
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
CapsLock,
but most keyboards do not have an LED that indicates the current group.
Because
phys_indicators
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
XkbGetKeyboardByName,
or if a new keyboard is attached and the X implementation notices,
phys_indicators
changes if the indicators for the new keyboard are different.
XkbIndicatorMapRecXkbIndicatorMapRec
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
maps
array, which is an array of
XkbIndicatorRec
structures:
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 */
} XkbIndicatorMapRec, *XkbIndicatorMapPtr;
This indicator map specifies for each indicator:
The conditions under which the keyboard modifier state affects the indicator
The conditions under which the keyboard group state affects the indicator
The conditions under which the state of the boolean controls affects the
indicator
The effect (if any) of attempts to explicitly change the state of the indicator
using the functions
XkbSetControls
or
XChangeKeyboardControl
For more information on the effects of explicit changes to indicators and the
relationship to the indicator map, see section 8.4.1.
XkbIndicatorMapRec flags field
The
flags
field specifies the conditions under which the indicator can be changed and
the effects of changing the indicator. The valid values for
flags
and their effects are shown in Table 8.1.
XkbIndicatorMapRec flags FieldValueEffectXkbIM_NoExplicit(1L<<7)Client applications cannot change the state of the indicator.XkbIM_NoAutomatic(1L<<6)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.XkbIM_LEDDrivesKB(1L<<5)A client application changing the state of the indicator causes the
state of the keyboard to change.
Note that if
XkbIM_NoAutomatic
is not set, by default the indicator follows the keyboard state.
If
XkbIM_LEDDrivesKB
is set and
XkbIM_NoExplicit
is not, and if you call a function which updates the server’s image of the
indicator map (such as
XkbSetIndicatorMap
or
XkbSetNamedIndicator),
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
XkbIM_LEDDrivesKB
is absent or for which
XkbIM_NoExplicit
is present, keyboard state or controls are unaffected.
For example, a keyboard designer may want to make the
CapsLock
LED controllable only by the server, but allow the
Scroll Lock
LED to be controlled by client applications. To do so, the keyboard designer
could set the
XkbIM_NoExplicit
flag for the
CapsLock
LED, but not set it for the
Scroll Lock
LED. Or the keyboard designer may wish to allow the
CapsLock
LED to be controlled by both the server and client applications and also have
the server to automatically change the
CapsLock
modifier state whenever a client application changes the
CapsLock
LED. To do so, the keyboard designer would not set the
XkbIM_NoExplicit
flag, but would instead set the
XkbIM_LEDDrivesKB
flag.
The remaining fields in the indicator map specify the conditions under which
Xkb automatically turns an indicator on or off (only if
XkbIM_NoAutomatic
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.
XkbIndicatorMapRec which_groups and groups fields
The
which_groups
and the
groups
fields of an indicator map determine how the keyboard group state affects the
corresponding indicator. The
which_groups
field controls the interpretation of
groups
and may contain any one of the following values:
#define XkbIM_UseNone 0
#define XkbIM_UseBase (1L << 0)
#define XkbIM_UseLatched (1L << 1)
#define XkbIM_UseLocked (1L << 2)
#define XkbIM_UseEffective (1L << 3)
#define XkbIM_UseAnyGroup XkbIM_UseLatched | XkbIM_UseLocked |
XkbIM_UseEffective
The
groups
field specifies what keyboard groups an indicator watches and is the bitwise
inclusive OR of the following valid values:
#define XkbGroup1Mask (1<<0)
#define XkbGroup2Mask (1<<1)
#define XkbGroup3Mask (1<<2)
#define XkbGroup4Mask (1<<3)
#define XkbAnyGroupMask (1<<7)
#define XkbAllGroupsMask (0xf)
If
XkbIM_NoAutomatic
is not set (the keyboard drives the indicator), the effect of
which_groups
and
groups
is shown in Table 8.2.
XkbIndicatorMapRec which_groups and groups, Keyboard Drives
Indicatorwhich_groupsEffectXkbIM_UseNone
The
groups
field and the current keyboard group state are ignored.
XkbIM_UseBase
If
groups
is nonzero, the indicator is lit whenever the base keyboard group is nonzero.
If
groups
is zero, the indicator is lit whenever the base keyboard group is zero.
XkbIM_UseLatched
If
groups
is nonzero, the indicator is lit whenever the latched keyboard group is
nonzero. If
groups
is zero, the indicator is lit whenever the latched keyboard group is zero.
XkbIM_UseLocked
The
groups
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
groups.
XkbIM_UseEffective
The
groups
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
groups.
The effect of
which_groups
and
groups
when you change an indicator for which
XkbIM_LEDDrivesKB
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.
XkbIndicatorMapRec which_groups and groups, Indicator Drives
Keyboardwhich_groupsNew StateEffect on Keyboard Group StateXkbIM_UseNoneOn or OffNo effectXkbIM_UseBaseOn or OffNo effectXkbIM_UseLatchedOn
The
groups
field is treated as a group mask. The keyboard group latch is changed to the
lowest numbered group specified in
groups;
if
groups
is empty, the keyboard group latch is changed to zero.
XkbIM_UseLatchedOff
The
groups
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
groups;
if
groups
is zero, the keyboard group latch is set to the index of the highest legal
keyboard group.
XkbIM_UseLocked or XkbIM_UseEffectiveOn
If the
groups
mask is empty, group is not changed; otherwise, the locked keyboard group is
changed to the lowest numbered group specified in
groups.
XkbIM_UseLocked or XkbIM_UseEffectiveOff
Locked keyboard group is changed to the lowest numbered group that is not
specified in the
groups
mask, or to
Group1
if the
groups
mask contains all keyboard groups.
XkbIndicatorMapRec which_mods and mods fields
The
mods
field specifies what modifiers an indicator watches. The
mods
field is an Xkb modifier definition,
XkbModsRec,
as described in section 7.2, which can specify both real and virtual
modifiers. The
mods
field takes effect even if some or all of the virtual indicators specified in
mods
are unbound. To specify the mods field, in general, assign the modifiers of
interest to
mods.real_mods
and the virtual modifiers of interest to
mods.vmods.
You can disregard the
mods.mask
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
XkbVirtualModsToReal
to determine the proper contents for the mask field, assuming that the
XkbDescRec
contains the virtual modifier definitions.
which_mods
specifies what criteria Xkb uses to determine a match with the corresponding
mods
field by specifying one or more components of the Xkb keyboard state. If
XkbIM_NoAutomatic
is not set (the keyboard drives the indicator), the indicator is lit whenever
any of the modifiers specified in the
mask
field of the
mods
modifier definition are also set in any of the current keyboard state
components specified by
which_mods.
Remember that the
mask
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 for more information on the keyboard state and
for more information on virtual modifiers.) Use a bitwise inclusive
OR of the following values to compose a value for
which_mods:
#define XkbIM_UseNone 0
#define XkbIM_UseBase (1L << 0)
#define XkbIM_UseLatched (1L << 1)
#define XkbIM_UseLocked (1L << 2)
#define XkbIM_UseEffective (1L << 3)
#define XkbIM_UseCompat (1L << 4)
#define XkbIM_UseAnyMods XkbIM_UseBase | XkbIM_UseLatched |
XkbIM_UseLocked | XkbIM_UseEffective |
XkbIM_UseCompat
If
XkbIM_NoAutomatic
is not set (the keyboard drives the indicator), the effect of
which_mods
and
mods
is shown in Table 8.4
XkbIndicatorMapRec which_mods and mods, Keyboard Drives Indicatorwhich_modsEffect on Keyboard ModifiersXkbIM_UseNoneThe mods field and the current keyboard modifier state are
ignored.XkbIM_UseBase
The indicator is lit when any of the modifiers specified in the
mask
field of
mods
are on in the keyboard base state. If both
mods.real_mods
and
mods.vmods
are zero, the indicator is lit when the base keyboard state contains no
modifiers.
XkbIM_UseLatched
The indicator is lit when any of the modifiers specified in the
mask
field of
mods
are latched. If both
mods.real_mods
and
mods.vmods
are zero, the indicator is lit when none of the modifier keys are latched.
XkbIM_UseLocked
The indicator is lit when any of the modifiers specified in the
mask
field of
mods
are locked. If both
mods.real_mods
and
mods.vmods
are zero, the indicator is lit when none of the modifier keys are locked.
XkbIM_UseEffective
The indicator is lit when any of the modifiers specified in the
mask
field of
mods
are in the effective keyboard state. If both
mods.real_mods
and
mods.vmods
are zero, the indicator is lit when the effective keyboard state contains no
modifiers.
XkbIM_UseCompat
The indicator is lit when any of the modifiers specified in the
mask
field of
mods
are in the keyboard compatibility state. If both
mods.real_mods
and
mods.vmods
are zero, the indicator is lit when the keyboard compatibility state contains
no modifiers.
The effect on the keyboard modifiers of
which_mods
and
mods
when you change an indicator for which
XkbIM_LEDDrivesKB
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.
XkbIndicatorMapRec which_mods and mods, Indicator Drives Keyboardwhich_modsNew StateEffect on Keyboard ModifiersXkbIM_UseNone or XkbIM_UseBaseOn or OffNo EffectXkbIM_UseLatchedOn
Any modifiers specified in the
mask
field of
mods
are added to the latched modifiers.
XkbIM_UseLatchedOff
Any modifiers specified in the
mask
field of
mods
are removed from the latched modifiers.
XkbIM_UseLocked, XkbIM_UseCompat, or XkbIM_UseEffectiveOn
Any modifiers specified in the
mask
field of
mods
are added to the locked modifiers.
XkbIM_UseLockedOff
Any modifiers specified in the
mask
field of
mods
are removed from the locked modifiers.
XkbIM_UseCompat or XkbIM_UseEffectiveOff
Any modifiers specified in the
mask
field of
mods
are removed from both the locked and latched modifiers.
XkbIndicatorMapRec ctrls field
The
ctrls
field specifies what controls (see ) the indicator watches and is
composed using the bitwise inclusive OR of the following values:
#define XkbRepeatKeysMask (1L << 0)
#define XkbSlowKeysMask (1L << 1)
#define XkbBounceKeysMask (1L << 2)
#define XkbStickyKeysMask (1L << 3)
#define XkbMouseKeysMask (1L << 4)
#define XkbMouseKeysAccelMask (1L << 5)
#define XkbAccessXKeysMask (1L << 6)
#define XkbAccessXTimeoutMask (1L << 7)
#define XkbAccessXFeedbackMask (1L << 8)
#define XkbAudibleBellMask (1L << 9)
#define XkbOverlay1Mask (1L << 10)
#define XkbOverlay2Mask (1L << 11)
#define XkbAllBooleanCtrlsMask (0x00001FFF)
Xkb lights the indicator whenever any of the boolean controls specified in
ctrls
is enabled.
Getting Information About Indicators
Xkb allows applications to obtain information about indicators using two
different methods. The first method, which is similar to the core X
implementation, uses a mask to specify the indicators. The second method, which
is more suitable for applications concerned with interoperability, uses
indicator names. The correspondence between the indicator name and the bit
position in masks is as follows: one of the parameters returned from
XkbGetNamedIndicator
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
XkbIndicatorRec
array of indicator maps.
Getting Indicator State
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
XkbGetIndicatorState.
XkbGetIndicatorStateStatus XkbGetIndicatorStateDisplay *displayunsigned int device_specunsigned int *state_returndisplay
connection to the X server
device_spec
device ID, or XkbUseCoreKbdstate_return
backfilled with a mask of the indicator state
XkbGetIndicatorState
queries the
display
for the state of the indicators on the device specified by the
device_spec.
For each indicator that is turned on on the device,
the associated bit is set in
state_return.
If a compatible version of the Xkb extension is not available in the server,
XkbGetIndicatorState
returns a
BadMatch
error. Otherwise, it sends the request to the X server, places the state of
the indicators into
state_return,
and returns
Success.
Thus the value reported by
XkbGetIndicatorState
is identical to the value reported by the core protocol.
Getting Indicator Information by Index
To get the map for one or more indicators, using a mask to specify the
indicators, use
XkbGetIndicatorMap.
XkbGetIndicatorMapStatus XkbGetIndicatorMapDisplay *dpyunsigned int whichXkbDescPtr descdpy
connection to the X server
which
mask of indicators for which maps should be returned
desc
keyboard description to be updated
XkbGetIndicatorMap
obtains the maps from the server for only those indicators specified by the
which
mask and copies the values into the keyboard description specified by
desc.
If the
indicators
field of the
desc
parameter is
NULL,
XkbGetIndicatorMap
allocates and initializes it.
XkbGetIndicatorMap
can generate
BadAlloc,
BadLength,
BadMatch,
and
BadImplementation
errors.
To free the indicator maps, use
XkbFreeIndicatorMaps
(see section 8.6).
Getting Indicator Information by Name
Xkb also allows applications to refer to indicators by name. Use
XkbGetNames
to get the indicator names (see ). Using names eliminates the need
for hard-coding bitmask values for particular keyboards. For example, instead
of using vendor-specific constants such as
WSKBLed_ScrollLock
mask on Digital workstations or
XLED_SCROLL_LOCK
on Sun workstations, you can instead use
XkbGetNamedIndicator
to look up information on the indicator named Scroll Lock.
Use
XkbGetNamedIndicator
to look up the indicator map and other information for an indicator by name.
XkbGetNamedIndicatorBool XkbGetNamedIndicatorDisplay *dpyunsigned int device_specAtom nameint *ndx_rtrnBool *state_rtrnXkbIndicatorMapPtr map_rtrnBool *real_rtrndpy
connection to the X server
device_spec
keyboard device ID, or XkbUseCoreKbdname
name of the indicator to be retrieved
ndx_rtrn
backfilled with the index of the retrieved indicator
state_rtrn
backfilled with the current state of the retrieved indicator
map_rtrn
backfilled with the mapping for the retrieved indicator
real_rtrn
backfilled with True
if the named indicator is real (physical)
If the device specified by
device_spec
has an indicator named
name,
XkbGetNamedIndicator
returns
True
and populates the rest of the parameters with information about the indicator.
Otherwise,
XkbGetNamedIndicator
returns
False.
The
ndx_rtrn
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
XkbIndicatorRec
array of indicator maps.
state_rtrn
returns the current state of the named indicator
(True
= on,
False
= off).
map_rtrn
returns the indicator map for the named indicator. In addition, if the
indicator is mapped to a physical LED, the
real_rtrn
parameter is set to
True.
Each of the "_rtrn" arguments is optional; you can pass
NULL
for any unneeded "_rtrn" arguments.
XkbGetNamedIndicator
can generate
BadAtom
and
BadImplementation
errors.
Changing Indicator Maps and State
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.
You cannot change the
phys_indicators
field of the indicators structure. The only way to change the
phys_indicators
field is to change the keyboard map.
There are two ways to make changes to indicator maps and state: either change a
local copy of the indicator maps and use
XkbSetIndicatorMap
or
XkbSetNamedIndicator,
or, to reduce network traffic, use an
XkbIndicatorChangesRec
structure and use
XkbChangeIndicators.
Effects of Explicit Changes on Indicators
This section discusses the effects of explicitly changing indicators depending
upon different settings in the indicator map. See
Table 8.3 and
Table 8.5 for
information on the effects of the indicator map fields when explicit changes
are made.
If
XkbIM_LEDDrivesKB
is set and
XkbIM_NoExplicit
is not, and if you call a function that updates the server’s image of the
indicator map (such as
XkbSetIndicatorMap
or
XkbSetNamedIndicator),
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
XkbIM_LEDDrivesKB
is absent or for which
XkbIM_NoExplicit
is present, keyboard state or controls are unaffected.
If neither
XkbIM_NoAutomatic
nor
XkbIM_NoExplicit
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.
The effects of changing an indicator that drives the keyboard are cumulative;
it is possible for a single change to affect keyboard group, modifiers, and
controls simultaneously.
If you change an indicator for which both the
XkbIM_LEDDrivesKB
and
XkbIM_NoAutomatic
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.
If the
XkbIM_NoAutomatic
flag is not set and
XkbIM_LEDDrivesKB
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
which_mods
of
XkbIM_UseBase
and
mods
of
Shift
if, at the time Xkb processes the request to extinguish the indicator, one of
the
Shift
keys is physically depressed.
If you explicitly light an indicator for which
XkbIM_LEDDrivesKB
is set, Xkb enables all of the boolean controls specified in the
ctrls
field of its indicator map. Explicitly extinguishing such an indicator causes
Xkb to disable all of the boolean controls specified in
ctrls.
Changing Indicator Maps by Index
To update the maps for one or more indicators, first modify a local copy of the
keyboard description, then use
XkbSetIndicatorMap
to download the changes to the server:
XkbSetIndicatorMapBool XkbSetIndicatorMapDisplay *dpyunsigned int whichXkbDescPtr descdpy
connection to the X server
which
mask of indicators to change
desc
keyboard description from which the maps are taken
For each
bit set in the
which
parameter,
XkbSetIndicatorMap
sends the corresponding indicator map from the
desc
parameter to the server.
Changing Indicator Maps by NameXkbSetNamedIndicator
can do several related things:
Name an indicator if it is not already named
Toggle the state of the indicator
Set the indicator to a specified state
Set the indicator map for the indicator
XkbSetNamedIndicatorBoolXkbSetNamedIndicatorDisplay *dpyunsigned int device_specAtom nameBool change_stateBool stateBool create_newXkbIndicatorMapPtr mapdpy
connection to the X server
device_spec
device ID, or XkbUseCoreKbdname
name of the indicator to change
change_state
whether to change the indicator state or not
state
desired new state for the indicator
create_new
whether a new indicator with the specified name should be
created when necessary
map
new map for the indicator
If a compatible version of the Xkb extension is not available in the server,
XkbSetNamedIndicator
returns
False.
Otherwise, it sends a request to the X server to change the indicator
specified by
name
and returns
True.
If
change_state
is
True,
and the optional parameter,
state,
is not
NULL,
XkbSetNamedIndicator
tells the server to change the state of the named indicator to the value
specified by
state.
If an indicator with the name specified by
name
does not already exist, the
create_new
parameter tells the server whether it should create a new named indicator. If
create_new
is
True,
the server finds the first indicator that doesn’t have a name and gives it
the name specified by
name.
If the optional parameter,
map,
is not
NULL,
XkbSetNamedIndicator
tells the server to change the indicator’s map to the values specified
in map.
XkbSetNamedIndicator
can generate
BadAtom
and
BadImplementation
errors. In addition, it can also generate
XkbIndicatorStateNotify
(see section 8.5),
XkbIndicatorMapNotify,
and
XkbNamesNotify
events (see section 18.5).
The XkbIndicatorChangesRec StructureXkbIndicatorChangesRec
The
XkbIndicatorChangesRec
identifies small modifications to the indicator map. Use it with the function
XkbChangeIndicators
to reduce the amount of traffic sent to the server.
typedef struct _XkbIndicatorChanges {
unsigned int state_changes;
unsigned int map_changes;
} XkbIndicatorChangesRec,*XkbIndicatorChangesPtr;
The
state_changes
field is a mask that specifies the indicators that have changed state, and
map_changes
is a mask that specifies the indicators whose maps have changed.
To change indicator maps or state without passing the entire keyboard
description, use
XkbChangeIndicators.
XkbChangeIndicatorsBool XkbChangeIndicatorsDisplay *dpyXkbDescPtr xkbXkbIndicatorChangesPtr changesunsigned int statedpy
connection to the X server
xkb
keyboard description from which names are to be taken.
changes
indicators to be updated on the server
state
new state of indicators listed in changes->state_changesXkbChangeIndicators
copies any maps specified by
changes
from the keyboard description,
xkb,
to the server specified by
dpy.
If any bits are set in the
state_changes
field of
changes,
XkbChangeIndicators
also sets the state of those indicators to the values specified in the
state
mask. A 1 bit in
state
turns the corresponding indicator on, a 0 bit turns it off.
XkbChangeIndicators
can generate
BadAtom
and
BadImplementation
errors. In addition, it can also generate
XkbIndicatorStateNotify
and
XkbIndicatorMapNotify
events (see section 8.5).
Tracking Changes to Indicator State or MapeventsXkbIndicatorStateNotifyXkbIndicatorStateNotifyEventeventsXkbIndicatorMapNotifyXkbIndicatorMapNotifyEvent
Whenever an indicator changes state, the server sends
XkbIndicatorStateNotify
events to all interested clients. Similarly, whenever an indicator’s map
changes, the server sends
XkbIndicatorMapNotify
events to all interested clients.
To receive
XkbIndicatorStateNotify
events, use
XkbSelectEvents
(see section 4.3) with both the
bits_to_change
and
values_for_bits
parameters containing
XkbIndicatorStateNotifyMask.
To receive
XkbIndicatorMapNotify
events, use
XkbSelectEvents
with
XkbIndicatorMapNotifyMask.
To receive events for only specific indicators, use
XkbSelectEventDetails.
Set the
event_type
parameter to
XkbIndicatorStateNotify
or
XkbIndicatorMapNotify,
and set both the
bits_to_change
and
values_for_bits
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.
Both types of indicator events use the same structure:
typedef struct _XkbIndicatorNotify {
int type; /* Xkb extension base event code */
unsigned long serial; /* X server serial number for event */
Bool send_event; /* True ⇒ 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 XkbUseCoreKbd */
unsigned int changed; /* mask of indicators with new state or map */
unsigned int state; /* current state of all indicators */
} XkbIndicatorNotifyEvent;
xkb_type
is either
XkbIndicatorStateNotify
or
XkbIndicatorMapNotify,
depending on whether the event is a
XkbIndicatorStateNotify
event or
XkbIndicatorMapNotify,
event.
The
changed
parameter is a mask that is the bitwise inclusive OR of the indicators that
have changed. If the event is of type
XkbIndicatorMapNotify,
changed
reports the maps that changed. If the event is of type
XkbIndicatorStateNotify,
changed
reports the indicators that have changed state.
state
is a mask that specifies the current state of all indicators, whether they
have changed or not, for both
XkbIndicatorStateNotify
and XkbIndicatorMapNotify events.
When your client application receives either a
XkbIndicatorStateNotify
event or
XkbIndicatorMapNotify
event, you can note the changes in a changes structure by calling
XkbNoteIndicatorChanges.
XkbNoteIndicatorChangesvoid XkbNoteIndicatorChangesXkbIndicatorChangesPtr oldXkbIndicatorNotifyEvent *newunsigned int wantedold
XkbIndicatorChanges structure to be updated
new
event from which changes are to be copied
wanted
which changes are to be noted
The
wanted
parameter is the bitwise inclusive OR of
XkbIndicatorMapMask
and
XkbIndicatorStateMask.
XkbNoteIndicatorChanges
copies any changes reported in
new
and specified in
wanted
into the changes record specified by
old.
To update a local copy of the keyboard description with the actual values, pass
the results of one or more calls to
XkbNoteIndicatorChanges
to
XkbGetIndicatorChanges:
XkbGetIndicatorChangesStatus XkbGetIndicatorChangesDisplay *dpyXkbDescPtr xkbXkbIndicatorChangesPtr changesunsigned int *statedpy
connection to the X server
xkb
keyboard description to hold the new values
changes
indicator maps/state to be obtained from the server
state
backfilled with the state of the indicators
XkbGetIndicatorChanges
examines the
changes
parameter, pulls over the necessary information from the server, and copies
the results into the
xkb
keyboard description. If any bits are set in the
state_changes
field of
changes,
XkbGetIndicatorChanges
also places the state of those indicators in
state.
If the
indicators
field of
xkb
is
NULL,
XkbGetIndicatorChanges
allocates and initializes it. To free the
indicators
field, use
XkbFreeIndicatorMaps
(see section 8.6).
XkbGetIndicatorChanges
can generate
BadAlloc,
BadImplementation,
and
BadMatch
errors.
Allocating and Freeing Indicator Maps
Most applications do not need to directly allocate the
indicators
member of the keyboard description record (the keyboard description record is
described in ). If the need arises, however, use
XkbAllocIndicatorMaps.
XkbAllocIndicatorMapsStatus XkbAllocIndicatorMapsXkbDescPtr xkbxkb
keyboard description structure
The
xkb
parameter must point to a valid keyboard description. If it doesn’t,
XkbAllocIndicatorMaps
returns a
BadMatch
error. Otherwise,
XkbAllocIndicatorMaps
allocates and initializes the
indicators
member of the keyboard description record and returns
Success.
If
XkbAllocIndicatorMaps
was unable to allocate the indicators record, it reports a
BadAlloc
error.
To free memory used by the
indicators
member of an
XkbDescRec
structure, use
XkbFreeIndicatorMaps.
XkbFreeIndicatorMapsvoid XkbFreeIndicatorMapsXkbDescPtr xkbxkb
keyboard description structure
If the indicators
member of the keyboard description record
pointed to by xkb
is not NULL,
XkbFreeIndicatorMaps
frees the memory associated with
the indicators
member of xkb.
ectEvents
(see section 4.3) with both the
bits_to_change
and
values_for_bits
parameters containing
XkbIndicatorStateNotifyMask.
To receive
XkbIndicatorMapNotify
events, use
XkbSelectEvents
with
XkbIndicatorMapNotifyMasklibX11-1.6.3/specs/XKB/ch01.xml 0000644 0143106 0000012 00000034204 12477417235 0016077 0 ustar 00alanc staff 0000266 0200006
Overview
The X Keyboard Extension provides capabilities that are lacking or are
cumbersome in the core X protocol.
Core X Protocol Support for Keyboards
The core X protocol specifies the ways that the
Shift,
Control, and
Lock
modifiers and the modifiers bound to the
Mode_switch or
Num_Lock
keysyms interact to generate keysyms and characters. The core protocol also
allows users to specify that a key affects one or more modifiers. This behavior
is simple and fairly flexible, but it has a number of limitations that make it
difficult or impossible to properly support many common varieties of keyboard
behavior. The limitations of core protocol support for keyboards include:
Use of a single, uniform, four-symbol mapping for all keyboard keys makes it
difficult to properly support keyboard overlays, PC-style break keys, or
keyboards that comply with ISO9995, or a host of other national and
international standards.
A second keyboard group may be specified using a modifier, but this has side
effects that wreak havoc with client grabs and X toolkit translations.
Furthermore, this approach limits the number of keyboard groups to two.
Poorly specified locking key behavior requires X servers to look for a few
magic keysyms to determine that keys should lock when pressed. This leads to
incompatibilities between X servers with no way for clients to detect
implementation differences.
Poorly specified capitalization and control behavior requires modifications to
X library source code to support new character sets or locales and can lead to
incompatibilities between system wide and X library capitalization behavior.
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.
The lack of any explicit descriptions for indicators, most modifiers, and other
aspects of the keyboard appearance requires clients that wish to clearly
describe the keyboard to a user to resort to a mish-mash of prior knowledge and
heuristics.
Xkb Keyboard Extension Support for Keyboards
The X Keyboard Extension makes it possible to clearly and explicitly specify
most aspects of keyboard behavior on a per-key basis. It adds the notion of a
keyboard group to the global keyboard state and provides mechanisms to more
closely track the logical and physical state of the keyboard. For
keyboard-control clients, Xkb provides descriptions and symbolic names for many
aspects of keyboard appearance and behavior.
In addition, the X Keyboard Extension includes additional keyboard controls
designed to make keyboards more accessible to people with movement impairments.
Xkb Extension Components
The Xkb extension is composed of two parts: a server extension, and a
client-side X library extension. These consist of a loadable module that may be
activated when an X server is started and a modified version of Xlib. Both
server and Xlib versions must be at least X11 R6.
Figure 1.1 shows the overall structure of the Xkb extension:
Overall Xkb Structure
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
keyboard descriptionkeyboard description
that includes the keyboard state and configuration (mapping). By
keyboard we
mean the logical keyboard device, which includes not only the physical keys,
but also potentially a set of up to 32 indicators (usually LEDs) and bells.
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.
Client Map
The key mapping information needed to convert arbitrary keycodes to symbols.
Server Map
The key mapping information categorizing keys by functionality (which keys are
modifiers, how keys behave, and so on).
Controls
Client configurable quantities effecting how the keyboard behaves, such as
repeat behavior and modifications for people with movement impairments.
Indicators
The mapping of behavior to indicators.
Geometry
A complete description of the physical keyboard layout, sufficient to draw a
representation of the keyboard.
Names
A mapping of names to various aspects of the keyboard such as individual
virtual modifiers, indicators, and bells.
Compatibility Map
The definition of how to map core protocol keyboard state to Xkb keyboard state.
A client application interrogates and manipulates the keyboard by reading and
writing portions of the server description for the keyboard. In a typical
sequence a client would fetch the current information it is interested in,
modify it, and write it back. If a client wishes to track some portion of the
keyboard state, it typically maintains a local copy of the portion of the
server keyboard description dealing with the items of interest and updates this
local copy from events describing state transitions that are sent by the server.
A client may request the server to reconfigure the keyboard either by sending
explicit reconfiguration instructions to it, or by telling it to load a new
configuration from its database of named components. Partial reconfiguration
and incremental reconfiguration are both supported.
Groups and Shift Levels
The graphic characters or control functions that may be accessed by one key are
logically arranged in groups and levels. See section 14.1 for a complete
description of groups and levels.
Radio Groupsradio groupgroupradio
A radio group
is a set of keys whose behavior simulates a set of radio buttons.
Once a key in a radio group is pressed, it stays logically depressed until
another key in the group is pressed, at which point the previously depressed
key is logically released. Consequently, at most one key in a radio group can
be logically depressed at one time. A radio group is defined by a radio group
index, an optional name, and by assigning each key in the radio group
XkbKB_RadioGroup
behavior and the radio group index.
Client Types
This specification differentiates between three different classes of client
applications:
Xkb-aware applications
These applications make specific use of Xkb functionality and APIs not present
in the core protocol.
Xkb-capable applications
These applications make no use of Xkb extended functionality and Application
Programming Interfaces (APIs) directly. However, they are linked with a version
of Xlib that includes Xkb and indirectly benefit from some of Xkb’s
features.
Xkb-unaware applications
These applications make no use of Xkb extended functionality or APIs and
require Xkb’s functionality to be mapped to core Xlib functionality to
operate properly.
Compatibility With the Core Protocol
Because the Xkb extension allows a keyboard to be configured in ways not
foreseen by the core protocol, and because Xkb-unaware clients are allowed to
connect to a server using the Xkb extension, there must be a means of
converting between the Xkb domain and the core protocol. The Xkb server
extension maintains a compatibility map as part of its keyboard description;
this map controls the conversion of Xkb generated events to core protocol
events and the results of core protocol requests to appropriate Xkb state and
configuration.
Additional Protocol Errors
The Xkb extension adds a single protocol error,
BadKeyboard,
to the core protocol error set. See section 2.6 for a discussion of the
BadKeyboard
protocol error.
Extension Library Functions
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.
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.
Xlib detects the presence of the X Keyboard server extension and uses Xkb
protocol to replace some standard X library functions related to the keyboard.
If an application uses only standard X library functions to examine the
keyboard or process key events, it should not need to be modified when linked
with an X library containing the X keyboard extension. All of the
keyboard-related X library functions have been modified to automatically use
Xkb protocol when the server extension is present.
The Xkb extension adds library interfaces to allow a client application to
directly manipulate the new capabilities.
Error Indicationserrors
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,
BadAccess
and
BadMatch
(due to incompatible versions) protocol errors should normally not be
generated.
Function Error Returns Due to Extension ProblemsFunctions return typeReturn valuepointer to a structureNULLBoolFalseStatusBadAccess
Many Xkb functions do not actually communicate with the X server; they only
require processing in the client-side portion of the library. Furthermore, some
applications may never actually need to communicate with the server; they
simply use the Xkb library capabilities. The functions that do not communicate
with the server return either a pointer to a structure, a Bool, or a Status.
These functions check that the application has queried the Xkb library version
and return the values shown in Table 1.1
if it has not.
ys are
modifiers, how keys behave, and so on).
Controls
Client configurable quantities effecting how the keyboard behaves, such as
repeat behavior and modifications for people with movement impairments.
&2; \
exit 1;; \
esac; \
has_opt=no; \
sane_makeflags=$$MAKEFLAGS; \
if $(am__is_gnu_make); then \
sane_makeflags=$$MFLAGS; \
else \
case $$MAKEFLAGS in \
*\\[\ \ ]*) \
bs=\\; \
sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \
| sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \
esac; \
fi; \
skip_next=no; \
strip_trailopt () \
{ \
flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \
}; \
for flg in $$sane_makeflags; do \
test $$skip_next = yes && { skip_next=no; continue; }; \
case $$flg in \
*=*|--*) continue;; \
-*I) strip_trailopt 'I'; skip_next=yes;; \
-*I?*) strip_trailopt 'I';; \
-*O) strip_trailopt 'O'; skip_next=yes;; \
-*O?*) strip_trailopt 'O';; \
-*l) strip_trailopt 'l'; skip_next=yes;; \
-*l?*) strip_trailopt 'l';; \
-[dEDm]) skip_next=yes;; \
-[JT]) skip_next=yes;; \
esac; \
case $$flg in \
*$$target_option*) has_opt=yes; break;; \
esac; \
done; \
test $$has_opt = yes
am__make_dryrun = (target_option=n; $(am__make_running_with_option))
am__make_keepgoing = (target_option=k; $(am__make_running_with_option))
pkgdatadir = $(datadir)/@PACKAGE@
pkgincludedir = $(includedir)/@PACKAGE@
pkglibdir = $(libdir)/@PACKAGE@
pkglibexecdir = $(libexecdir)/@PACKAGE@
am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
install_sh_DATA = $(install_sh) -c -m 644
install_sh_PROGRAM = $(install_sh) -c
install_sh_SCRIPT = $(install_sh) -c
INSTALL_HEADER = $(INSTALL_DATA)
transform = $(program_transform_name)
NORMAL_INSTALL = :
PRE_INSTALL = :
POST_INSTALL = :
NORMAL_UNINSTALL = :
PRE_UNINSTALL = :
POST_UNINSTALL = :
build_triplet = @build@
host_triplet = @host@
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@am__append_1 = $(docbook:.xml=.html)
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TEXT_TRUE@@HAVE_XMLTO_TRUE@am__append_2 = $(docbook:.xml=.txt)
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@am__append_3 = $(docbook:.xml=.pdf) \
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(docbook:.xml=.ps)
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@am__append_4 = $(docbook:.xml=.html.db) \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(docbook:.xml=.pdf.db)
subdir = specs/XKB
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
am__aclocal_m4_deps = $(top_srcdir)/m4/ax_define_dir.m4 \
$(top_srcdir)/configure.ac
am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
$(ACLOCAL_M4)
DIST_COMMON = $(srcdir)/Makefile.am $(am__dist_shelf_DATA_DIST) \
$(am__DIST_COMMON)
mkinstalldirs = $(install_sh) -d
CONFIG_HEADER = $(top_builddir)/src/config.h \
$(top_builddir)/include/X11/XlibConf.h
CONFIG_CLEAN_FILES =
CONFIG_CLEAN_VPATH_FILES =
AM_V_P = $(am__v_P_@AM_V@)
am__v_P_ = $(am__v_P_@AM_DEFAULT_V@)
am__v_P_0 = false
am__v_P_1 = :
AM_V_GEN = $(am__v_GEN_@AM_V@)
am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@)
am__v_GEN_0 = @echo " GEN " $@;
am__v_GEN_1 =
AM_V_at = $(am__v_at_@AM_V@)
am__v_at_ = $(am__v_at_@AM_DEFAULT_V@)
am__v_at_0 = @
am__v_at_1 =
SOURCES =
DIST_SOURCES =
am__can_run_installinfo = \
case $$AM_UPDATE_INFO_DIR in \
n|no|NO) false;; \
*) (install-info --version) >/dev/null 2>&1;; \
esac
am__dist_shelf_DATA_DIST = xkblib.xml acknowledgement.xml ch01.xml \
ch02.xml ch03.xml ch04.xml ch05.xml ch06.xml ch07.xml ch08.xml \
ch09.xml ch10.xml ch11.xml ch12.xml ch13.xml ch14.xml ch15.xml \
ch16.xml ch17.xml ch18.xml ch19.xml ch20.xml ch21.xml ch22.xml \
glossary.xml XKBlib-1.svg XKBlib-2.svg XKBlib-3.svg \
XKBlib-4.svg XKBlib-5.svg XKBlib-6.svg XKBlib-7.svg \
XKBlib-8.svg XKBlib-9.svg XKBlib-10.svg XKBlib-11.svg \
XKBlib-12.svg XKBlib-13.svg XKBlib-14.svg XKBlib-15.svg \
XKBlib-16.svg XKBlib-17.svg XKBlib-18.svg XKBlib-19.svg \
XKBlib-20.svg XKBlib-21.svg
am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`;
am__vpath_adj = case $$p in \
$(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \
*) f=$$p;; \
esac;
am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`;
am__install_max = 40
am__nobase_strip_setup = \
srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'`
am__nobase_strip = \
for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||"
am__nobase_list = $(am__nobase_strip_setup); \
for p in $$list; do echo "$$p $$p"; done | \
sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \
$(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \
if (++n[$$2] == $(am__install_max)) \
{ print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \
END { for (dir in files) print dir, files[dir] }'
am__base_list = \
sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \
sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g'
am__uninstall_files_from_dir = { \
test -z "$$files" \
|| { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \
|| { echo " ( cd '$$dir' && rm -f" $$files ")"; \
$(am__cd) "$$dir" && rm -f $$files; }; \
}
am__installdirs = "$(DESTDIR)$(shelfdir)" "$(DESTDIR)$(shelfdir)"
DATA = $(dist_shelf_DATA) $(shelf_DATA)
am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
am__DIST_COMMON = $(srcdir)/Makefile.in $(top_srcdir)/docbook.am
DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
ACLOCAL = @ACLOCAL@
ADMIN_MAN_DIR = @ADMIN_MAN_DIR@
ADMIN_MAN_SUFFIX = @ADMIN_MAN_SUFFIX@
AMTAR = @AMTAR@
AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@
APP_MAN_DIR = @APP_MAN_DIR@
APP_MAN_SUFFIX = @APP_MAN_SUFFIX@
AR = @AR@
AUTOCONF = @AUTOCONF@
AUTOHEADER = @AUTOHEADER@
AUTOMAKE = @AUTOMAKE@
AWK = @AWK@
BASE_CFLAGS = @BASE_CFLAGS@
BIGFONT_CFLAGS = @BIGFONT_CFLAGS@
BIGFONT_LIBS = @BIGFONT_LIBS@
CC = @CC@
CCDEPMODE = @CCDEPMODE@
CC_FOR_BUILD = @CC_FOR_BUILD@
CFLAGS = @CFLAGS@
CFLAGS_FOR_BUILD = @CFLAGS_FOR_BUILD@
CHANGELOG_CMD = @CHANGELOG_CMD@
CPP = @CPP@
CPPFLAGS = @CPPFLAGS@
CPPFLAGS_FOR_BUILD = @CPPFLAGS_FOR_BUILD@
CWARNFLAGS = @CWARNFLAGS@
CYGPATH_W = @CYGPATH_W@
DEFS = @DEFS@
DEPDIR = @DEPDIR@
DLLTOOL = @DLLTOOL@
DRIVER_MAN_DIR = @DRIVER_MAN_DIR@
DRIVER_MAN_SUFFIX = @DRIVER_MAN_SUFFIX@
DSYMUTIL = @DSYMUTIL@
DUMPBIN = @DUMPBIN@
ECHO_C = @ECHO_C@
ECHO_N = @ECHO_N@
ECHO_T = @ECHO_T@
EGREP = @EGREP@
EXEEXT = @EXEEXT@
FGREP = @FGREP@
FILE_MAN_DIR = @FILE_MAN_DIR@
FILE_MAN_SUFFIX = @FILE_MAN_SUFFIX@
FOP = @FOP@
GREP = @GREP@
I18N_MODULE_LIBS = @I18N_MODULE_LIBS@
INSTALL = @INSTALL@
INSTALL_CMD = @INSTALL_CMD@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
INSTALL_SCRIPT = @INSTALL_SCRIPT@
INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
KEYSYMDEFS = @KEYSYMDEFS@
LAUNCHD = @LAUNCHD@
LD = @LD@
LDFLAGS = @LDFLAGS@
LDFLAGS_FOR_BUILD = @LDFLAGS_FOR_BUILD@
LIBOBJS = @LIBOBJS@
LIBS = @LIBS@
LIBTOOL = @LIBTOOL@
LIB_MAN_DIR = @LIB_MAN_DIR@
LIB_MAN_SUFFIX = @LIB_MAN_SUFFIX@
LINT = @LINT@
LINTLIB = @LINTLIB@
LINT_FLAGS = @LINT_FLAGS@
LIPO = @LIPO@
LN_S = @LN_S@
LTLIBOBJS = @LTLIBOBJS@
MAKEINFO = @MAKEINFO@
MALLOC_ZERO_CFLAGS = @MALLOC_ZERO_CFLAGS@
MANIFEST_TOOL = @MANIFEST_TOOL@
MAN_SUBSTS = @MAN_SUBSTS@
MISC_MAN_DIR = @MISC_MAN_DIR@
MISC_MAN_SUFFIX = @MISC_MAN_SUFFIX@
MKDIR_P = @MKDIR_P@
NM = @NM@
NMEDIT = @NMEDIT@
OBJDUMP = @OBJDUMP@
OBJEXT = @OBJEXT@
OTOOL = @OTOOL@
OTOOL64 = @OTOOL64@
PACKAGE = @PACKAGE@
PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
PACKAGE_NAME = @PACKAGE_NAME@
PACKAGE_STRING = @PACKAGE_STRING@
PACKAGE_TARNAME = @PACKAGE_TARNAME@
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
PERL = @PERL@
PKG_CONFIG = @PKG_CONFIG@
RANLIB = @RANLIB@
RAWCPP = @RAWCPP@
RAWCPPFLAGS = @RAWCPPFLAGS@
SED = @SED@
SET_MAKE = @SET_MAKE@
SHELL = @SHELL@
STRICT_CFLAGS = @STRICT_CFLAGS@
STRIP = @STRIP@
STYLESHEET_SRCDIR = @STYLESHEET_SRCDIR@
TRADITIONALCPPFLAGS = @TRADITIONALCPPFLAGS@
VERSION = @VERSION@
WCHAR32 = @WCHAR32@
X11_CFLAGS = @X11_CFLAGS@
X11_DATADIR = @X11_DATADIR@
X11_EXTRA_DEPS = @X11_EXTRA_DEPS@
X11_LIBDIR = @X11_LIBDIR@
X11_LIBS = @X11_LIBS@
X11_LOCALEDATADIR = @X11_LOCALEDATADIR@
X11_LOCALEDIR = @X11_LOCALEDIR@
X11_LOCALELIBDIR = @X11_LOCALELIBDIR@
XERRORDB = @XERRORDB@
XKBPROTO_REQUIRES = @XKBPROTO_REQUIRES@
XKEYSYMDB = @XKEYSYMDB@
XLOCALEDATADIR = @XLOCALEDATADIR@
XLOCALEDIR = @XLOCALEDIR@
XLOCALELIBDIR = @XLOCALELIBDIR@
XMALLOC_ZERO_CFLAGS = @XMALLOC_ZERO_CFLAGS@
XMLTO = @XMLTO@
XORG_MAN_PAGE = @XORG_MAN_PAGE@
XORG_SGML_PATH = @XORG_SGML_PATH@
XSLTPROC = @XSLTPROC@
XSL_STYLESHEET = @XSL_STYLESHEET@
XTHREADLIB = @XTHREADLIB@
XTHREAD_CFLAGS = @XTHREAD_CFLAGS@
XTMALLOC_ZERO_CFLAGS = @XTMALLOC_ZERO_CFLAGS@
abs_builddir = @abs_builddir@
abs_srcdir = @abs_srcdir@
abs_top_builddir = @abs_top_builddir@
abs_top_srcdir = @abs_top_srcdir@
ac_ct_AR = @ac_ct_AR@
ac_ct_CC = @ac_ct_CC@
ac_ct_DUMPBIN = @ac_ct_DUMPBIN@
am__include = @am__include@
am__leading_dot = @am__leading_dot@
am__quote = @am__quote@
am__tar = @am__tar@
am__untar = @am__untar@
bindir = @bindir@
build = @build@
build_alias = @build_alias@
build_cpu = @build_cpu@
build_os = @build_os@
build_vendor = @build_vendor@
builddir = @builddir@
datadir = @datadir@
datarootdir = @datarootdir@
docdir = @docdir@
dvidir = @dvidir@
exec_prefix = @exec_prefix@
host = @host@
host_alias = @host_alias@
host_cpu = @host_cpu@
host_os = @host_os@
host_vendor = @host_vendor@
htmldir = @htmldir@
includedir = @includedir@
infodir = @infodir@
install_sh = @install_sh@
libdir = @libdir@
libexecdir = @libexecdir@
localedir = @localedir@
locales = @locales@
localstatedir = @localstatedir@
mandir = @mandir@
mkdir_p = @mkdir_p@
oldincludedir = @oldincludedir@
pdfdir = @pdfdir@
prefix = @prefix@
program_transform_name = @program_transform_name@
psdir = @psdir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
sysconfdir = @sysconfdir@
target_alias = @target_alias@
top_build_prefix = @top_build_prefix@
top_builddir = @top_builddir@
top_srcdir = @top_srcdir@
# Main DocBook/XML files (DOCTYPE book)
@ENABLE_SPECS_TRUE@docbook = xkblib.xml
# Included chapters, appendix, images
@ENABLE_SPECS_TRUE@chapters = \
@ENABLE_SPECS_TRUE@ acknowledgement.xml \
@ENABLE_SPECS_TRUE@ ch01.xml \
@ENABLE_SPECS_TRUE@ ch02.xml \
@ENABLE_SPECS_TRUE@ ch03.xml \
@ENABLE_SPECS_TRUE@ ch04.xml \
@ENABLE_SPECS_TRUE@ ch05.xml \
@ENABLE_SPECS_TRUE@ ch06.xml \
@ENABLE_SPECS_TRUE@ ch07.xml \
@ENABLE_SPECS_TRUE@ ch08.xml \
@ENABLE_SPECS_TRUE@ ch09.xml \
@ENABLE_SPECS_TRUE@ ch10.xml \
@ENABLE_SPECS_TRUE@ ch11.xml \
@ENABLE_SPECS_TRUE@ ch12.xml \
@ENABLE_SPECS_TRUE@ ch13.xml \
@ENABLE_SPECS_TRUE@ ch14.xml \
@ENABLE_SPECS_TRUE@ ch15.xml \
@ENABLE_SPECS_TRUE@ ch16.xml \
@ENABLE_SPECS_TRUE@ ch17.xml \
@ENABLE_SPECS_TRUE@ ch18.xml \
@ENABLE_SPECS_TRUE@ ch19.xml \
@ENABLE_SPECS_TRUE@ ch20.xml \
@ENABLE_SPECS_TRUE@ ch21.xml \
@ENABLE_SPECS_TRUE@ ch22.xml \
@ENABLE_SPECS_TRUE@ glossary.xml \
@ENABLE_SPECS_TRUE@ XKBlib-1.svg \
@ENABLE_SPECS_TRUE@ XKBlib-2.svg \
@ENABLE_SPECS_TRUE@ XKBlib-3.svg \
@ENABLE_SPECS_TRUE@ XKBlib-4.svg \
@ENABLE_SPECS_TRUE@ XKBlib-5.svg \
@ENABLE_SPECS_TRUE@ XKBlib-6.svg \
@ENABLE_SPECS_TRUE@ XKBlib-7.svg \
@ENABLE_SPECS_TRUE@ XKBlib-8.svg \
@ENABLE_SPECS_TRUE@ XKBlib-9.svg \
@ENABLE_SPECS_TRUE@ XKBlib-10.svg \
@ENABLE_SPECS_TRUE@ XKBlib-11.svg \
@ENABLE_SPECS_TRUE@ XKBlib-12.svg \
@ENABLE_SPECS_TRUE@ XKBlib-13.svg \
@ENABLE_SPECS_TRUE@ XKBlib-14.svg \
@ENABLE_SPECS_TRUE@ XKBlib-15.svg \
@ENABLE_SPECS_TRUE@ XKBlib-16.svg \
@ENABLE_SPECS_TRUE@ XKBlib-17.svg \
@ENABLE_SPECS_TRUE@ XKBlib-18.svg \
@ENABLE_SPECS_TRUE@ XKBlib-19.svg \
@ENABLE_SPECS_TRUE@ XKBlib-20.svg \
@ENABLE_SPECS_TRUE@ XKBlib-21.svg
# The location where the DocBook/XML files and their generated formats are installed
@ENABLE_SPECS_TRUE@shelfdir = $(docdir)/XKB
# DocBook/XML generated output formats to be installed
@ENABLE_SPECS_TRUE@shelf_DATA = $(am__append_1) $(am__append_2) \
@ENABLE_SPECS_TRUE@ $(am__append_3) $(am__append_4)
# DocBook/XML file with chapters, appendix and images it includes
@ENABLE_SPECS_TRUE@dist_shelf_DATA = $(docbook) $(chapters)
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_SEARCHPATH_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --searchpath "$(XORG_SGML_PATH)/X11" \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --searchpath "$(abs_top_builddir)"
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_HTML_OLINK_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --stringparam target.database.document=$(XORG_SGML_PATH)/X11/dbs/masterdb.html.xml \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --stringparam current.docid="$(<:.xml=)"
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_HTML_STYLESHEET_FLAGS = -x $(STYLESHEET_SRCDIR)/xorg-xhtml.xsl
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_HTML_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_SEARCHPATH_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_HTML_STYLESHEET_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_HTML_OLINK_FLAGS)
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_FO_IMAGEPATH_FLAGS = --stringparam img.src.path=$(abs_builddir)/
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_PDF_OLINK_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --stringparam target.database.document=$(XORG_SGML_PATH)/X11/dbs/masterdb.pdf.xml \
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ --stringparam current.docid="$(<:.xml=)"
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_FO_STYLESHEET_FLAGS = -x $(STYLESHEET_SRCDIR)/xorg-fo.xsl
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@XMLTO_FO_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_SEARCHPATH_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_FO_STYLESHEET_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_FO_IMAGEPATH_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(XMLTO_PDF_OLINK_FLAGS)
# Generate documents cross-reference target databases
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@XSLT_SEARCHPATH_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --path "$(XORG_SGML_PATH)/X11" \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --path "$(abs_top_builddir)"
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@XSLT_OLINK_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --stringparam targets.filename "$@" \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --stringparam collect.xref.targets "only" \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --stringparam olink.base.uri "$(@:.db=)"
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@XSLT_HTML_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(XSLT_SEARCHPATH_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(XSLT_OLINK_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --nonet --xinclude \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(STYLESHEET_SRCDIR)/xorg-xhtml.xsl
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@XSLT_PDF_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(XSLT_SEARCHPATH_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(XSLT_OLINK_FLAGS) \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --nonet --xinclude \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(STYLESHEET_SRCDIR)/xorg-fo.xsl
@ENABLE_SPECS_TRUE@CLEANFILES = $(shelf_DATA)
all: all-am
.SUFFIXES:
$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(top_srcdir)/docbook.am $(am__configure_deps)
@for dep in $?; do \
case '$(am__configure_deps)' in \
*$$dep*) \
( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \
&& { if test -f $@; then exit 0; else break; fi; }; \
exit 1;; \
esac; \
done; \
echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign specs/XKB/Makefile'; \
$(am__cd) $(top_srcdir) && \
$(AUTOMAKE) --foreign specs/XKB/Makefile
Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
@case '$?' in \
*config.status*) \
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
*) \
echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
esac;
$(top_srcdir)/docbook.am $(am__empty):
$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(top_srcdir)/configure: $(am__configure_deps)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(ACLOCAL_M4): $(am__aclocal_m4_deps)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(am__aclocal_m4_deps):
mostlyclean-libtool:
-rm -f *.lo
clean-libtool:
-rm -rf .libs _libs
install-dist_shelfDATA: $(dist_shelf_DATA)
@$(NORMAL_INSTALL)
@list='$(dist_shelf_DATA)'; test -n "$(shelfdir)" || list=; \
if test -n "$$list"; then \
echo " $(MKDIR_P) '$(DESTDIR)$(shelfdir)'"; \
$(MKDIR_P) "$(DESTDIR)$(shelfdir)" || exit 1; \
fi; \
for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
echo "$$d$$p"; \
done | $(am__base_list) | \
while read files; do \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(shelfdir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(shelfdir)" || exit $$?; \
done
uninstall-dist_shelfDATA:
@$(NORMAL_UNINSTALL)
@list='$(dist_shelf_DATA)'; test -n "$(shelfdir)" || list=; \
files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \
dir='$(DESTDIR)$(shelfdir)'; $(am__uninstall_files_from_dir)
install-shelfDATA: $(shelf_DATA)
@$(NORMAL_INSTALL)
@list='$(shelf_DATA)'; test -n "$(shelfdir)" || list=; \
if test -n "$$list"; then \
echo " $(MKDIR_P) '$(DESTDIR)$(shelfdir)'"; \
$(MKDIR_P) "$(DESTDIR)$(shelfdir)" || exit 1; \
fi; \
for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
echo "$$d$$p"; \
done | $(am__base_list) | \
while read files; do \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(shelfdir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(shelfdir)" || exit $$?; \
done
uninstall-shelfDATA:
@$(NORMAL_UNINSTALL)
@list='$(shelf_DATA)'; test -n "$(shelfdir)" || list=; \
files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \
dir='$(DESTDIR)$(shelfdir)'; $(am__uninstall_files_from_dir)
tags TAGS:
ctags CTAGS:
cscope cscopelist:
distdir: $(DISTFILES)
@srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
list='$(DISTFILES)'; \
dist_files=`for file in $$list; do echo $$file; done | \
sed -e "s|^$$srcdirstrip/||;t" \
-e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
case $$dist_files in \
*/*) $(MKDIR_P) `echo "$$dist_files" | \
sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
sort -u` ;; \
esac; \
for file in $$dist_files; do \
if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
if test -d $$d/$$file; then \
dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
if test -d "$(distdir)/$$file"; then \
find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
fi; \
if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \
find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
fi; \
cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \
else \
test -f "$(distdir)/$$file" \
|| cp -p $$d/$$file "$(distdir)/$$file" \
|| exit 1; \
fi; \
done
check-am: all-am
check: check-am
all-am: Makefile $(DATA)
installdirs:
for dir in "$(DESTDIR)$(shelfdir)" "$(DESTDIR)$(shelfdir)"; do \
test -z "$$dir" || $(MKDIR_P) "$$dir"; \
done
install: install-am
install-exec: install-exec-am
install-data: install-data-am
uninstall: uninstall-am
install-am: all-am
@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
installcheck: installcheck-am
install-strip:
if test -z '$(STRIP)'; then \
$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
install; \
else \
$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
"INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \
fi
mostlyclean-generic:
clean-generic:
-test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)
distclean-generic:
-test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
-test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES)
maintainer-clean-generic:
@echo "This command is intended for maintainers to use"
@echo "it deletes files that may require special tools to rebuild."
clean: clean-am
clean-am: clean-generic clean-libtool mostlyclean-am
distclean: distclean-am
-rm -f Makefile
distclean-am: clean-am distclean-generic
dvi: dvi-am
dvi-am:
html: html-am
html-am:
info: info-am
info-am:
install-data-am: install-dist_shelfDATA install-shelfDATA
install-dvi: install-dvi-am
install-dvi-am:
install-exec-am:
install-html: install-html-am
install-html-am:
install-info: install-info-am
install-info-am:
install-man:
install-pdf: install-pdf-am
install-pdf-am:
install-ps: install-ps-am
install-ps-am:
installcheck-am:
maintainer-clean: maintainer-clean-am
-rm -f Makefile
maintainer-clean-am: distclean-am maintainer-clean-generic
mostlyclean: mostlyclean-am
mostlyclean-am: mostlyclean-generic mostlyclean-libtool
pdf: pdf-am
pdf-am:
ps: ps-am
ps-am:
uninstall-am: uninstall-dist_shelfDATA uninstall-shelfDATA
.MAKE: install-am install-strip
.PHONY: all all-am check check-am clean clean-generic clean-libtool \
cscopelist-am ctags-am distclean distclean-generic \
distclean-libtool distdir dvi dvi-am html html-am info info-am \
install install-am install-data install-data-am \
install-dist_shelfDATA install-dvi install-dvi-am install-exec \
install-exec-am install-html install-html-am install-info \
install-info-am install-man install-pdf install-pdf-am \
install-ps install-ps-am install-shelfDATA install-strip \
installcheck installcheck-am installdirs maintainer-clean \
maintainer-clean-generic mostlyclean mostlyclean-generic \
mostlyclean-libtool pdf pdf-am ps ps-am tags-am uninstall \
uninstall-am uninstall-dist_shelfDATA uninstall-shelfDATA
.PRECIOUS: Makefile
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@%.html: %.xml $(chapters)
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(AM_V_GEN)$(XMLTO) $(XMLTO_HTML_FLAGS) xhtml-nochunks $<
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TEXT_TRUE@@HAVE_XMLTO_TRUE@%.txt: %.xml $(chapters)
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TEXT_TRUE@@HAVE_XMLTO_TRUE@ $(AM_V_GEN)$(XMLTO) $(XMLTO_HTML_FLAGS) txt $<
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@%.pdf: %.xml $(chapters)
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(AM_V_GEN)$(XMLTO) $(XMLTO_FO_FLAGS) --with-fop pdf $<
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@%.ps: %.xml $(chapters)
@ENABLE_SPECS_TRUE@@HAVE_FOP_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@ $(AM_V_GEN)$(XMLTO) $(XMLTO_FO_FLAGS) --with-fop ps $<
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@%.html.db: %.xml $(chapters)
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(AM_V_GEN)$(XSLTPROC) $(XSLT_HTML_FLAGS) $<
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@%.pdf.db: %.xml $(chapters)
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ $(AM_V_GEN)$(XSLTPROC) $(XSLT_PDF_FLAGS) $<
# Generate DocBook/XML output formats with or without stylesheets
# Tell versions [3.59,3.63) of GNU make to not export all variables.
# Otherwise a system limit (for SysV at least) may be exceeded.
.NOEXPORT:
ABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@XSLT_OLINK_FLAGS = \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --stringparam targets.filename "$@" \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --stringparam collect.xref.targets "only" \
@ENABLE_SPECS_TRUE@@HAVE_STYLESHEETS_TRUE@@HAVE_XMLTO_TRUE@@HAVE_XSLTPROC_TRUE@ --stringparam olinklibX11-1.6.3/specs/XKB/ch06.xml 0000644 0143106 0000012 00000026603 12477417235 0016110 0 ustar 00alanc staff 0000266 0200006
Complete Keyboard Description
The complete Xkb description for a keyboard device is accessed using a single
structure containing pointers to major Xkb components. This chapter describes
this single structure and provides references to other sections of this
document that discuss the major Xkb components in detail.
The XkbDescRec StructureXkbDescRec
The complete description of an Xkb keyboard is given by an
XkbDescRec.
The component structures in the
XkbDescRec
represent the major Xkb components outlined in Figure 1.1.
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 */
} XkbDescRec, *XkbDescPtr;
The
display
field points to an X display structure. The
flags
field is private to the library: modifying
flags
may yield unpredictable results. The
device_spec
field specifies the device identifier of the keyboard input device, or
XkbUseCoreKbd,
which specifies the core keyboard device. The
min_key_code
and
max_key_code
fields specify the least and greatest keycode that can be returned by the
keyboard.
The other fields specify structure components of the keyboard description and
are described in detail in other sections of this document.
Table 6.1
identifies the subsequent sections of this document that discuss the individual
components of the
XkbDescRec.
XkbDescRec Component ReferencesXkbDescRec FieldFor more infoctrlsservermapindicatorsnamescompatgeom
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
XkbDescRec
are shown in Table 6.2.
Mask Bits for XkbDescRecMask BitXkbDescRec FieldValueXkbControlsMaskctrls(1L<<0)XkbServerMapMaskserver(1L<<1)XkbIClientMapMaskmap(1L<<2)XkbIndicatorMapMaskindicators(1L<<3)XkbNamesMasknames(1L<<4)XkbCompatMapMaskcompat(1L<<5)XkbGeometryMaskgeom(1L<<6)XkbAllComponentsMaskAll Fields(0x7f)
Obtaining a Keyboard Description from the Server
To retrieve one or more components of a keyboard device description, use
XkbGetKeyboard
(see also
XkbGetKeyboardByName).
XkbGetKeyboardXkbDescPtr XkbGetKeyboardDisplay *displayunsigned int whichunsigned int device_specdisplay
connection to X server
which
mask indicating components to return
device_spec
device for which to fetch description, or
XkbUseCoreKbdXkbGetKeyboard
allocates and returns a pointer to a keyboard description. It queries the
server for those components specified in the
which
parameter for device
device_spec
and copies the results to the
XkbDescRec
it allocated. The remaining fields in the keyboard description are set to
NULL.
The valid masks for
which
are those listed in Table 6.2.
XkbGetKeyboard
can generate
BadAlloc
protocol errors.
To free the returned keyboard description, use
XkbFreeKeyboard
(see section 6.4).
Tracking Changes to the Keyboard Description in the Server
The server can generate events whenever its copy of the keyboard description
for a device changes. Refer to section 14.4 for detailed information on
tracking changes to the keyboard description.
Allocating and Freeing a Keyboard Description
Applications seldom need to directly allocate a keyboard description; calling
XkbGetKeyboard
usually suffices. In the event you need to create a keyboard description from
scratch, however, use
XkbAllocKeyboard
rather than directly calling
malloc
or
Xmalloc.
XkbAllocKeyboardXkbDescRec *XkbAllocKeyboard
If
XkbAllocKeyboard
fails to allocate the keyboard description, it returns
NULL.
Otherwise, it returns a pointer to an empty keyboard description structure.
The
device_spec
field will have been initialized to
XkbUseCoreKbd.
You may then either fill in the structure components or use Xkb functions to
obtain values for the structure components from a keyboard device.
To destroy either an entire an
XkbDescRec
or just some of its members, use
XkbFreeKeyboard.
XkbFreeKeyboardvoid XkbFreeKeyboardXkbDescPtr xkbunsigned int whichBool free_allxkb
keyboard description with components to free
which
mask selecting components to free
free_allTrue ⇒ free all components and xkbXkbFreeKeyboard
frees the components of
xkb
specified by
which
and sets the corresponding values to
NULL.
If
free_all
is
True,
XkbFreeKeyboard
frees every non-
NULL
component of
xkb
and then frees the
xkb
structure itself.
ntry>XkbIClientMapMask
map(1L<<2)XkbIndlibX11-1.6.3/specs/XKB/XKBlib-1.svg 0000644 0143106 0000012 00000100416 12477417235 0016613 0 ustar 00alanc staff 0000266 0200006
id="text3057-5-8-4-8-0-3"
y="918.67493"
x="517.61279"
style="font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-slibX11-1.6.3/specs/XKB/XKBlib-6.svg 0000644 0143106 0000012 00000057575 12477417235 0016641 0 ustar 00alanc staff 0000266 0200006
id="path5563-6-8"
inkscape:connector-curvature="0" />
-9-0"
style="fill:none;stroke:#000000;stroke-width:0.99999988;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:nonlibX11-1.6.3/specs/XKB/XKBlib-15.svg 0000644 0143106 0000012 00000120525 12477417235 0016703 0 ustar 00alanc staff 0000266 0200006
649658"
x="209.78336"
style="font-size:9px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%libX11-1.6.3/specs/XKB/XKBlib-12.svg 0000644 0143106 0000012 00000075252 12477417235 0016706 0 ustar 00alanc staff 0000266 0200006
family:DejaVu Sans;-inkscape-font-specification:DejaVu Sans"
xml:space="preserve">. . .Debugging Aids
The debugging aids are intended for use primarily by Xkb implementors and are
optional in any implementation.
There are two bitmasks that may be used to control debugging. One bitmask
controls the output of debugging information, and the other controls behavior.
Both bitmasks are initially all zeros.
To change the values of any of the debug controls, use
XkbSetDebuggingFlags.
XkbSetDebuggingFlagsBool XkbSetDebuggingFlagsDisplay *displayunsigned int maskunsigned int flagschar *msgunsigned int ctrls_maskunsigned int ctrlsunsigned int *ret_flagsunsigned int *ret_ctrlsdisplay
connection to X server
mask
mask selecting debug output flags to change
flags
values for debug output flags selected by maskmsg
message to print right now
ctrls_mask
mask selecting debug controls to change
ctrls
values for debug controls selected by ctrls_maskret_flags
resulting state of all debug output flags
ret_ctrls
resulting state of all debug controls
XkbSetDebuggingFlags
modifies the debug output flags as specified by
mask
and
flags,
modifies the debug controls flags as specified by
ctrls_mask
and
ctrls,
prints the message
msg,
and backfills
ret_flags
and
ret_ctrls
with the resulting debug output and debug controls flags.
When bits are set in the debug output masks,
mask
and
flags,
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
mask
and
flags
is implementation-specific. To turn on a debug output selection, set the bit
for the output in the
mask
parameter and set the corresponding bit in the
flags
parameter. To turn off event selection for an event, set the bit for the
output in the
mask
parameter and do not set the corresponding bit in the
flags
parameter.
When bits are set in the debug controls masks,
ctrls_mask
and
ctrls,
Xkb modifies its behavior according to each controls bit.
ctrls_mask
and
ctrls
are related in the same way that
mask
and
flags
are. The valid controls bits are defined in
Table 22.1.
Debug Control MasksDebug Control MaskValueMeaningXkbDF_DisableLocks(1 << 0)Disable actions that lock modifiers
XkbSetDebuggingFlags
returns
True
if successful and
False
otherwise. The only protocol error it may generate is
BadAlloc,
if for some reason it is unable to allocate storage.
XkbSetDebuggingFlags
is intended for developer use and may be disabled in production X servers. If
it is disabled,
XkbSetDebuggingFlags
has no effect and does not generate any protocol errors.
The message in
msg
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.
varlistentry>
ret_flags
resulting state of all debug output flags
libX11-1.6.3/specs/XKB/ch17.xml 0000644 0143106 0000012 00000162224 12477417235 0016112 0 ustar 00alanc staff 0000266 0200006
The Xkb Compatibility Map
As shown in Figure 17.1, the X server is normally dealing with more than one
client, each of which may be receiving events from the keyboard, and each of
which may issue requests to modify the keyboard in some manner. Each client may
be either Xkb-unaware, Xkb-capable, or Xkb-aware. The server itself may be
either Xkb-aware or Xkb-unaware. If the server is Xkb-unaware, Xkb state and
keyboard mappings are not involved in any manner, and Xkb-aware clients may not
issue Xkb requests to the server. If the server is Xkb-aware, the server must
be able to deliver events and accept requests in which the keyboard state and
mapping are compatible with the mode in which the client is operating.
Consequently, for some situations, conversions must be made between Xkb state /
keyboard mappings and core protocol state / keyboard mappings, and vice versa.
Server Interaction with Types of Clients
In addition to these situations involving a single server, there are cases
where a client that deals with multiple servers may need to configure keyboards
on different servers to be similar and the different servers may not all be
Xkb-aware. Finally, a client may be dealing with descriptions of keyboards
(files, and so on) that are based on core protocol and therefore may need to be
able to map these descriptions to Xkb descriptions.
An Xkb-aware server maintains keyboard state and mapping as an Xkb keyboard
state and an Xkb keyboard mapping plus a compatibility map used to convert from
Xkb components to core components and vice versa. In addition, the server also
maintains a core keyboard mapping that approximates the Xkb keyboard mapping.
The core keyboard mapping may be updated piecemeal, on a per-key basis. When
the server receives a core protocol
ChangeKeyboardMapping
or
SetModifierMapping
request, it updates its core keyboard mapping, then uses the compatibility map
to update its Xkb keyboard mapping. When the server receives an
XkbSetMap
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.
The core keyboard map is contained only in the server, not in any
client-side data structures.Server Derivation of State and Keyboard Mapping Components
There are three kinds of compatibility transformations made by the server:
Xkb State to Core State
Keyboard state information reported to a client in the state field of various
core events may be translated from the Xkb keyboard state maintained by the
server, which includes a group number, to core protocol state, which does
not.
In addition, whenever the Xkb state is retrieved, the
compat_state,
compat_grab_mods,
and
compat_lookup_mods
fields of the
XkbStateRec
returned indicate the result of applying the compatibility map to the current
Xkb state in the server.
Core Keyboard Mapping to Xkb Keyboard Mapping
After core protocol requests received by the server to change the keyboard
mapping
(ChangeKeyboardMapping
and
SetModifierMapping)
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.
Xkb Keyboard Mapping to Core Keyboard Mapping
After Xkb protocol requests received by the server to change the keyboard
mapping
(XkbSetMap)
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.
This chapter discusses how a client may modify the compatibility map so that
subsequent transformations have a particular result.
The XkbCompatMap StructureXkbCompatMapRec
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
XkbCompatMapRec
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.
The
compat
member of an Xkb keyboard description
(XkbDescRec)
points to the
XkbCompatMapRec
structure:
typedef struct _XkbCompatMapRec {
XkbSymInterpretPtr sym_interpret; /* symbol based key semantics */
XkbModsRec groups[XkbNumKbdGroups]; /* group ⇒ modifier map */
unsigned short num_si; /* # structures used in
sym_interpret */
unsigned short size_si; /* # structures allocated in
sym_interpret */
} XkbCompatMapRec, *XkbCompatMapPtr;
Xkb Compatibility Data Structures
The subsections that follow discuss how the compatibility map and explicit
override controls are used in each of the three cases where compatibility
transformations are made.
Xkb State to Core Protocol State Transformation
As shown in Figure 17.3, there are four
group compatibility mapsgroup compatibility mapmapgroup compatibility
(contained in
groups
[0..3]) in the
XkbCompatMapRec
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
mask
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
XkbDescRec
does not support four groups, the extra groups fields are present, but
undefined.
Normally, the Xkb-aware server reports keyboard state in the
state
member of events such as a
KeyPress
event and
ButtonPress
event, encoded as follows:
bitsmeaning15013–14Group index8–12Pointer Buttons0–7Modifiers
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
groups
[group index] field of the compatibility map (the bits set in the compatibility
map are ORed into bits 0–7 of the state), and bits 13–14 are reported in the
event as zero.
Core Keyboard Mapping to Xkb Keyboard Mapping Transformation
When a core protocol keyboard mapping request is received by the server, the
server’s core keyboard map is updated, and then the Xkb map maintained by the
server is updated. Because a client may have explicitly configured some of the
Xkb keyboard mapping in the server, this automatic regeneration of the Xkb
keyboard mapping from the core protocol keyboard mapping should not modify any
components of the Xkb keyboard mapping that were explicitly set by a client.
The client must set explicit override controls to prevent this from happening
(see section 16.3). The core-to-Xkb mapping is done as follows:
Map the symbols from the keys in the core keyboard map to groups and symbols on
keys in the Xkb keyboard map. The core keyboard mapping is of fixed width, so
each key in the core mapping has the same number of symbols associated with it.
The Xkb mapping allows a different number of symbols to be associated with each
key; those symbols may be divided into a different number of groups (1-4) for
each key. For each key, this process therefore involves partitioning the fixed
number of symbols from the core mapping into a set of variable-length groups
with a variable number of symbols in each group. For example, if the core
protocol map is of width five, the partition for one key might result in one
group with two symbols and another with three symbols. A different key might
result in two groups with two symbols plus a third group with one symbol. The
core protocol map requires at least two symbols in each of the first two
groups.
For each changed key, determine the number of groups represented in the new
core keyboard map. This results in a tentative group count for each key in the
Xkb map.
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,
ExplicitKeyType1
through
ExplicitKeyType4.
If no explicit override control is set for a group, the number of symbols
used for that group from the core map is two. If the explicit override control
is set for a group on the key, the number of symbols used for that Xkb group
from the core map is the width of the Xkb group with one exception: because of
the core protocol requirement for at least two symbols in each of groups one
and two, the number of symbols used for groups one and two is the maximum of 2
or the width of the Xkb group.
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
NoSymbol
keysyms appended to the end of the core set. If the core map contains more
symbols than are needed by the Xkb map, trailing symbols in the core map are
discarded. In the absence of an explicit override for group one or two, symbols
are assigned in order by group; the first symbols in the core map are assigned
to group one, in order, followed by group two, and so on. For example, if the
core map contained eight symbols per key, and a particular Xkb map contained 2
symbols for G1 and G2 and three for G3, the symbols would be assigned as (G is
group, L is shift level):
G1L1 G1L2 G2L1 G2L2 G3L1 G3L2 G3L3
If an explicit override control is set for group one or two, the symbols are
taken from the core set in a somewhat different order. The first four symbols
from the core set are assigned to G1L1, G1L2, G2L1, G2L2, respectively. If
group one requires more symbols, they are taken next, and then any additional
symbols needed by group two. Group three and four symbols are taken in complete
sequence after group two. For example, a key with four groups and three symbols
in each group would take symbols from the core set in the following order:
G1L1 G1L2 G2L1 G2L2 G1L3 G2L3 G3L1 G3L2 G3L3 G4L1 G4L2 G4L3
As previously noted, the core protocol map requires at lease two symbols in
groups one and two. Because of this, if an explicit override control for an Xkb
key is set and group one and / or group two is of width one, it is not possible
to generate the symbols taken from the core protocol set and assigned to
position G1L2 and / or G2L2.
For each group on each changed key, assign a key type appropriate for the
symbols in the group.
For each changed key, remove any empty or redundant groups.
At this point, the groups and their associated symbols have been assigned to
the corresponding key definitions in the Xkb map.
Apply symbol interpretations to modify key operation. This phase is completely
skipped if the
ExplicitInterpret
override control bit is set in the explicit controls mask for the Xkb key (see
section 16.3).
For each symbol on each changed key, attempt to match the symbol and modifiers
from the Xkb map to a symbol interpretation describing how to generate the
symbol.
When a match is found in step 2a, apply the symbol interpretation to change the
semantics associated with the symbol in the Xkb key map. If no match is found,
apply a default interpretation.
The symbol interpretations used in step 2 are configurable and may be specified
using
XkbSymInterpretRec
structures referenced by the
sym_interpret
field of an
XkbCompatMapRec
(see Figure 17.3).
Symbol Interpretations — the XkbSymInterpretRec StructureXkbSymInterpretRec
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
XkbSetCompatMap
(see section 17.4).
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:
Virtual modifier mapAuto repeatKey behavior (may be set to XkbKB_Lock)Key action (see section 16.1)
The XkbSymInterpretRec
structure specifies a symbol interpretation:
typedef struct {
KeySym sym; /* keysym of interest or NULL */
unsigned char flags; /* XkbSI_AutoRepeat, XkbSI_LockingKey */
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 */
} XkbSymInterpretRec,*XkbSymInterpretPtr;
If
sym
is not
NULL,
it limits the symbol interpretation to keys on which that particular keysym
is selected by the modifiers matching the criteria specified by
mods
and
match.
If
sym
is
NULL,
the interpretation may be applied to any symbol selected on a key when the
modifiers match the criteria specified by
mods
and
match.
match
must be one of the values shown in
Table 17.1 and specifies how the real
modifiers specified in mods
are to be interpreted.
Symbol Interpretation Match CriteriaMatch CriteriaValueEffectXkbSI_NoneOf(0)
None of the bits that are on in mods
can be set, but other bits can be.
XkbSI_AnyOfOrNone(1)
Zero or more of the bits that are on in
mods
can be set, as well as others.
XkbSI_AnyOf(2)
One or more of the bits that are on in
mods
can be set, as well as any others.
XkbSI_AllOf(3)
All of the bits that are on in
mods
must be set, but others may be set as well.
XkbSI_Exactly(4)
All of the bits that are on in
mods
must be set, and no other bits may be set.
In addition to the above bits,
match
may contain the
XkbSI_LevelOneOnly
bit, in which case the modifier match criteria specified by
mods
and
match
applies only if
sym
is in level one of its group; otherwise,
mods
and
match
are ignored and the symbol matches a condition where no modifiers are set.
#define XkbSI_LevelOneOnly (0x80)
/* use mods + match only if sym is level 1 */
If no matching symbol interpretation is found, the server uses a default
interpretation where:
sym =0flags =XkbSI_AutoRepeatmatch =XkbSI_AnyOfOrNonemods =0virtual_mod =XkbNoModifieract =SA_NoAction
When a matching symbol interpretation is found in step 2a, the interpretation
is applied to modify the Xkb map as follows.
The
act
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.
If the Xkb keyboard map for the key does not have its
ExplicitVModMap
control set, the
XkbSI_LevelOneOnly
bit and symbol position are examined. If the
XkbSI_LevelOneOnly
bit is not set in
match
or the symbol is in position G1L1, the
virtual_mod
field is examined. If
virtual_mod
is not
XkbNoModifier,
virtual_mod
specifies a single virtual modifier to be added to the virtual modifier map
for the key.
virtual_mod
is specified as an index in the range [0..15].
If the matching symbol is in position G1L1 of the key, two bits in the flags
field potentially specify additional behavior modifications:
#define XkbSI_AutoRepeat (1<<0) /* key repeats if sym
is in position G1L1 */
#define XkbSI_LockingKey (1<<1) /* set KB_Lock behavior
if sym is in psn G1L1 */
If the Xkb keyboard map for the key does not have its
ExplicitAutoRepeat
control set, its auto repeat behavior is set based on the value of the
XkbSI_AutoRepeat
bit. If the
XkbSI_AutoRepeat
bit is set, the auto-repeat behavior of the key is turned on; otherwise, it is
turned off.
If the Xkb keyboard map for the key does not have its
ExplicitBehavior
control set, its locking behavior is set based on the value of the
XkbSI_LockingKey
bit. If
XkbSI_LockingKey
is set, the key behavior is set to
KB_Lock;
otherwise, it is turned off (see section 16.3).
Xkb Keyboard Mapping to Core Keyboard Mapping Transformations
Whenever the server processes Xkb requests to change the keyboard mapping, it
discards the affected portion of its core keyboard mapping and regenerates it
based on the new Xkb mapping.
When the Xkb mapping for a key is transformed to a core protocol mapping, the
symbols for the core map are taken in the following order from the Xkb map:
G1L1 G1L2 G2L1 G2L2 G1L3-n G2L3-n G3L1-n G4L1-n
If group one is of width one in the Xkb map, G1L2 is taken to be NoSymbol;
similarly, if group two is of width one in the Xkb map, G2L2 is taken to be
NoSymbol.
If the Xkb key map for a particular key has fewer groups than the core
keyboard, the symbols for group one are repeated to fill in the missing core
components. For example, an Xkb key with a single width-three group would be
mapped to a core mapping counting three groups as:
G1L1 G1L2 G1L1 G1L2 G1L3 G1L3 G1L1 G1L2 G1L3
When a core keyboard map entry is generated from an Xkb keyboard map entry, a
modifier mapping is generated as well. The modifier mapping contains all of the
modifiers affected by any of the actions associated with the key combined with
all of the real modifiers associated with any of the virtual modifiers bound to
the key. In addition, if any of the actions associated with the key affect any
component of the keyboard group, all of the modifiers in the
mask
field of all of the group compatibility maps are added to the modifier mapping
as well. While an
XkbSA_ISOLock
action can theoretically affect any modifier, if the Xkb mapping for a key
specifies an
XkbSA_ISOLock
action, only the modifiers or group that are set by default are added to the
modifier mapping.
Getting Compatibility Map Components From the Server
Use
XkbGetCompatMap
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
XkbCompatMapNotify
events (see section 17.5).
XkbGetCompatMap
is particularly useful when you receive an event of this type, as it allows
you to update your program’s version of the compatibility map to match the
modified version now in the server. If your program is dealing with multiple
servers and needs to configure them all in a similar manner, the updated
compatibility map may be used to reconfigure other servers.
To make a complete matching configuration you must also update the
explicit override components of the server state.XkbGetCompatMapStatus XkbGetCompatMapDisplay *displayunsigned int whichXkbDescRec *xkbdisplay
connection to server
which
mask of compatibility map components to fetch
xkb
keyboard description where results placed
XkbGetCompatMap
fetches the components of the compatibility map specified in
which
from the server specified by
display
and places them in the
compat
structure of the keyboard description
xkb.
Valid values for
which
are an inclusive OR of the values shown in
Table 17.2.
If no compatibility map structure is allocated in
xkb
upon entry,
XkbGetCompatMap
allocates one. If one already exists, its contents are overwritten with the
returned results.
XkbGetCompatMap
fetches compatibility map information for the device specified by the
device_spec
field of
xkb.
Unless you have specifically modified this field, it is the default keyboard
device.
XkbGetCompatMap
returns
Success
if successful,
BadAlloc
if it is unable to obtain necessary storage for either the return values or
work space,
BadMatch
if the
dpy
field of the
xkb
argument is non-
NULL
and does not match the
display
argument, and
BadLength
under certain conditions caused by server or Xkb implementation errors.
Using the Compatibility Map
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
XGetKeyboardMapping,
for example), a data file, or some other source.
To update a local Xkb keyboard map to reflect the mapping expressed by a core
format mapping by calling the function
XkbUpdateMapFromCore.
XkbUpdateMapFromCoreBool XkbUpdateMapFromCoreXkbDescPtr xkbKeyCode first_keyint num_keysint map_widthKeySym *core_keysymsXkbChangesPtr changesxkb
keyboard description to update
first_key
keycode of first key description to update
num_keys
number of key descriptions to update
map_width
width of core protocol keymap
core_keysyms
symbols in core protocol keymap
changes
backfilled with changes made to Xkb
XkbUpdateMapFromCore
interprets input argument information representing a keyboard map in core
format to update the Xkb keyboard description passed in
xkb.
Only a portion of the Xkb map is updated — the portion corresponding to
keys with keycodes in the range
first_key
through
first_key
+
num_keys
- 1. If
XkbUpdateMapFromCore
is being called in response to a
MappingNotify
event,
first_key
and
num_keys
are reported in the
MappingNotify
event.
core_keysyms
contains the keysyms corresponding to the keycode range being updated, in core
keyboard description order.
map_width
is the number of keysyms per key in
core_keysyms.
Thus, the first
map_width
entries in
core_keysyms
are for the key with keycode
first_key,
the next
map_width
entries are for key
first_key
+ 1, and so on.
In addition to modifying the Xkb keyboard mapping in
xkb,
XkbUpdateMapFromCore
backfills the changes structure whose address is passed in
changes
to indicate the modifications that were made. You may then use
changes
in subsequent calls such as
XkbSetMap,
to propagate the local modifications to a server.
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
XkbKeyTypesForCoreSymbols
for this purpose:
XkbKeyTypesForCoreSymbolsint XkbKeyTypesForCoreSymbolsXkbDescPtr xkbint map_widthKeySym *core_symsunsigned int protectedint *types_inoutKeySym *xkb_syms_rtrnxkb
keyboard description in which to place symbols
map_width
width of core protocol keymap in xkb_syms_rtrncore_syms
core protocol format array of KeySyms
protected
explicit key types
types_inout
backfilled with the canonical types bound to groups one and two
for the key
xkb_syms_rtrn
backfilled with symbols bound to the key in the Xkb mapping
XkbKeyTypesForCoreSymbols
expands the symbols in
core_syms
and types in
types_inout
according to the rules specified in section 12 of the core protocol, then
chooses canonical key types (canonical key types are defined in section 15.2.1)
for groups 1 and 2 using the rules specified by the Xkb protocol and places
them in
xkb_syms_rtrn,
which will be non-
NULL.
A core keymap is a two-dimensional array of keysyms. It has
map_width
columns and
max_key_code
rows.
XkbKeyTypesForCoreSymbols
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,
types_inout
has the types for each group, and
xkb_syms_rtrn
has the symbols in Xkb order (that is, groups are contiguous, regardless of
size).
protected
contains the explicitly protected key types. There is one explicit override
control associated with each of the four possible groups for each Xkb key,
ExplicitKeyType1
through
ExplicitKeyType4;
protected
is an inclusive OR of these controls.
map_width
is the width of the core keymap and is not dependent on any Xkb definitions.
types_inout
is an array of four type indices. On input,
types_inout
contains the indices of any types already assigned to the key, in case they
are explicitly protected from change.
Upon return,
types_inout
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
types_inout
correspond to the four groups for the key in question.
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
XkbApplyCompatMapToKey.
XkbApplyCompatMapToKeyBool XkbApplyCompatMapToKeyXkbDescPtr xkbKeyCode keyXkbChangesPtr changesxkb
keyboard description to be updated
key
key to be updated
changes
notes changes to the Xkb keyboard description
XkbApplyCompatMapToKey
essentially performs the operation described in section 17.1.2 to a specific
key. This updates the behavior, actions, repeat status, and virtual modifier
bindings of the key.
Changing the Server’s Compatibility Map
To modify the server’s compatibility map, first modify a local copy of the
Xkb compatibility map, then call
XkbSetCompatMap.
You may allocate a new compatibility map for this purpose using
XkbAllocCompatMap
(see section 17.6). You may also use a compatibility map from another server,
although you need to adjust the
device_spec
field in the
XkbDescRec
accordingly. Note that symbol interpretations in a compatibility map
(
sym_interpret,
the vector of
XkbSymInterpretRec
structures) are also allocated using this same function.
XkbSetCompatMapBool XkbSetCompatMapDisplay *displayunsigned int whichXkbDescPtr xkbBool update_actionsdisplay
connection to server
which
mask of compat map components to set
xkb
source for compat map components
update_actionsTrue ⇒ apply to server’s keyboard map
XkbSetCompatMap
copies compatibility map information from the keyboard description in
xkb
to the server specified in
display’s
compatibility map for the device specified by the
device_spec
field of
xkb.
Unless you have specifically modified this field, it is the default keyboard
device.
which
specifies the compatibility map components to be set, and is an inclusive OR
of the bits shown in Table 17.2.
After updating its compatibility map for the specified device, if
update_actions
is
True,
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
update_actions
is
False,
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
XkbSetCompatMap
specifying
which
as zero and
update_actions
as
True.
XkbSetCompatMap
returns
True
if successful and
False
if unsuccessful. The server may report problems it encounters when processing
the request subsequently via protocol errors.
To add a symbol interpretation to the list of symbol interpretations in an
XkbCompatRec,
use
XkbAddSymInterpret.
XkbAddSymInterpretXkbSymInterpretPtr XkbAddSymInterpretXkbDescPtr xkbXkbSymInterpretPtr siBool updateMapXkbChangesPtr changesxkb
keyboard description to be updated
si
symbol interpretation to be added
updateMapTrue⇒apply compatibility map to keys
changes
changes are put here
XkbAddSymInterpret
adds
si
to the list of symbol interpretations in
xkb.
If
updateMap
is
True,
it (re)applies the compatibility map to all of the keys on the keyboard. If
changes
is non-
NULL,
it reports the parts of the keyboard that were affected (unless
updateMap
is
True,
not much changes).
XkbAddSymInterpret
returns a pointer to the actual new symbol interpretation in the list or
NULL
if it failed.
Tracking Changes to the Compatibility MapeventsXkbCompatMapNotifyXkbCompatMapNotifyEvent
The server automatically generates
MappingNotify
events when the keyboard mapping changes. If you wish to be notified of
changes to the compatibility map, you should select for
XkbCompatMapNotify
events. If you select for
XkbMapNotify
events, you no longer receive the automatically generated
MappingNotify
events. If you subsequently deselect
XkbMapNotifyEvent
delivery, you again receive
MappingNotify
events.
To receive
XkbCompatMapNotify
events under all possible conditions, use
XkbSelectEvents
(see section 4.3) and pass
XkbCompatMapNotifyMask
in both
bits_to_change
and
values_for_bits.
To receive
XkbCompatMapNotify
events only under certain conditions, use
XkbSelectEventDetails
using
XkbCompatMapNotify
as the
event_type
and specifying the desired map changes in
bits_to_change
and
values_for_bits
using mask bits from Table 17.2.
Note that you are notified of changes you make yourself, as well as changes
made by other clients.
The structure for the
XkbCompatMapNotifyEvent
is:
typedef struct {
int type; /* Xkb extension base event code */
unsigned long serial; /* X server serial number for event */
Bool send_event; /* True ⇒
synthetically generated */
Display * display; /* server connection where event generated */
Time time; /* server time when event generated */
int xkb_type; /* XkbCompatMapNotify */
int device; /* Xkb device ID, will not be
XkbUseCoreKbd */
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 */
} XkbCompatMapNotifyEvent;
changed_groups
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
XkbGetCompatMap,
changed_groups
references
groups
[0..
changed_groups
-1] in the
XkbCompatMapRec
structure.
first_si
is the index of the first changed symbol interpretation,
num_si
is the number of changed symbol interpretations, and
num_total_si
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
XkbGetCompatMap,
first_si,
num_si,
and
num_total_si
are appropriate for use with the
compat.sym_interpret
vector in this structure.
Allocating and Freeing the Compatibility Map
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
XkbAllocCompatMap.
XkbAllocCompatMapStatus XkbAllocCompatMapXkbDescPtr xkbunsigned int whichunsigned int num_sixkb
keyboard description in which to allocate compat map
which
mask of compatibility map components to allocate
num_si
number of symbol interpretations to allocate
xkb
specifies the keyboard description for which compatibility maps are to be
allocated. The compatibility map is the
compat
field in this structure.
which
specifies the compatibility map components to be allocated (see
XkbGetCompatMap,
in section 17.2).
which
is an inclusive OR of the bits shown in
Table 17.2.
num_si
specifies the total number of entries to allocate in the symbol interpretation
vector
(xkb.compat.sym_interpret).
Note that symbol interpretations in a compatibility map (the
sym_interpret
vector of
XkbSymInterpretRec
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
XkbAllocCompatMap
specifying
which
as
XkbSymInterpretMask
and the number of free symbol interpretations needed in
num_si.
XkbAllocCompatMap
returns
Success
if successful,
BadMatch
if
xkb
is
NULL,
or
BadAlloc
if errors are encountered when attempting to allocate storage.
To free an entire compatibility map or selected portions of one, use
XkbFreeCompatMap.
XkbFreeCompatMapvoid XkbFreeCompatMapXkbDescPtr xkbunsigned int whichBool free_mapxkb
Xkb description in which to free compatibility map
which
mask of compatibility map components to free
free_mapTrue ⇒ free XkbCompatMapRec
structure itself
which
specifies the compatibility map components to be freed (see
XkbGetCompatMap,
in section 17.2).
which
is an inclusive OR of the bits shown in
Table 17.2
free_map
indicates whether the
XkbCompatMapRec
structure itself should be freed. If
free_map
is
True,
which
is ignored, all non-
NULL
compatibility map components are freed, and the
compat
field in the
XkbDescRec
referenced by
xkb
is set to
NULL.
parameter>.
If
updateMap
is
True,
it (re)applies the compatibility map to all of the keys on the keyboard. If
changes
is non-
NULL,
it reports the parts of the keyboard that were affected (unless
updateMap
is
True,
not much changes).
libX11-1.6.3/specs/XKB/ch10.xml 0000644 0143106 0000012 00000465734 12477417235 0016117 0 ustar 00alanc staff 0000266 0200006
Keyboard Controlscontrolsserver controlscontrolsserver
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. 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.
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
Boolean Controls.
boolean controlscontrolsboolean
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
Non-Boolean Controls,
non-boolean controlscontrolsnon-boolean
are always active. The
XkbControlsRec
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.
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
XkbControlsRec
structure (see section 10.8).
You can manipulate the Xkb controls individually, via convenience functions, or
as a whole. To treat them as a group, modify an
XkbControlsRec
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
XkbControlsChangesRec
(see section 10.10.1) to reduce network traffic. When using a convenience
function to manipulate one control individually, you do not use an
XkbControlsRec
structure directly.
The Xkb controls are grouped as shown in
Table 10.1.
Xkb Keyboard ControlsType of ControlControl NameBoolean Control?Controls for enabling and disabling other controlsEnabledControlsNoAutoResetNoControl for bell behaviorAudibleBellBooleanControls for repeat key behaviorPerKeyRepeatNoRepeatKeysBooleanDetectableAutorepeatBooleanControls for keyboard overlaysOverlay1BooleanOverlay2BooleanControls for using the mouse from the keyboardMouseKeysBooleanMouseKeysAccelBooleanControls for better keyboard access by AccessXFeedbackBooleanphysically impaired personsAccessXKeysBooleanAccessXTimeoutBooleanBounceKeysBooleanSlowKeysBooleanStickyKeysBooleanControls for general keyboard mappingGroupsWrapNoIgnoreGroupLockBooleanIgnoreLockModsNoInternalModsNoMiscellaneous per-client controlsGrabsUseXKBStateBooleanLookupStateWhenGrabbedBooleanSendEventUsesXKBStateBoolean
The individual categories and controls are described first, together with
functions for manipulating them. A description of the
XkbControlsRec
structure and the general functions for dealing with all of the controls at
once follow at the end of the chapter.
Controls that Enable and Disable Other Controls
Enable and disable the boolean controls under program control by using the
EnabledControls
control; enable and disable them upon program exit by configuring the
AutoReset
control.
The EnabledControls Control
The
EnabledControls
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
enabled_ctrls
field of an
XkbControlsRec
structure (see section 10.8). The bits describing which controls are turned on
or off are defined in Table 10.7.
Use
XkbChangeEnabledControls
to manipulate the
EnabledControls
control.
XkbChangeEnabledControlsBool XkbChangeEnabledControlsDisplay *dpyunsigned int device_specunsigned int maskunsigned int valuesdpy
connection to X server
device_spec
keyboard device to modify
mask
1 bit → controls to enable / disable
values
1 bit ⇒ enable, 0 bit ⇒ disable
The
mask
parameter specifies the boolean controls to be enabled or disabled, and the
values
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
enabled_ctrls
column.
If the X server does not support a compatible version of Xkb or the Xkb
extension has not been properly initialized,
XkbChangeEnabledControls
returns
False;
otherwise, it sends the request to the X server and returns
True.
Note that the
EnabledControls
control only enables and disables controls; it does not configure them. Some
controls, such as the
AudibleBell
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
RepeatControl
control uses
repeat_delay
and
repeat_interval
fields to describe the timing behavior of keys that repeat. The
RepeatControl
behavior is turned on or off depending on the value of the
XkbRepeatKeysMask
bit, but you must use other means, as described in this chapter, to configure
its behavior in detail.
The AutoReset Control
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
auto-reset maskauto-reset maskmaskauto-reset
are set to the corresponding value from the
auto-reset values
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
EnabledControls
control bits.
For example, a client that replaces the keyboard bell with some other audible
cue might want to turn off the
AudibleBell
control to prevent the server from also generating a sound and avoid
cacophony. If the client were to exit without resetting the
AudibleBell
control, the user would be left without any feedback at all. Setting
AudibleBell
in both the auto-reset mask and auto-reset values guarantees that the audible
bell will be turned back on when the client exits.
To get the current values of the auto-reset controls, use
XkbGetAutoResetControls.
XkbGetAutoResetControlsBool XkbGetAutoResetControlsDisplay *dpyunsigned int *auto_ctrlsunsigned int *auto_valuesdpy
connection to X server
auto_ctrls
specifies which bits in auto_values are relevant
auto_values
1 bit ⇒ corresponding control has auto-reset on
XkbGetAutoResetControls
backfills
auto_ctrls
and
auto_values
with the
AutoReset
control attributes for this particular client. It returns
True
if successful, and
False
otherwise.
To change the current values of the
AutoReset
control attributes, use
XkbSetAutoResetControls.
XkbSetAutoResetControlsBool XkbSetAutoResetControlsDisplay *dpyunsigned int changesunsigned int *auto_ctrlsunsigned int *auto_valuesdpy
connection to X server
changes
controls for which to change auto-reset values
auto_ctrls
controls from changes that should auto reset
auto_values
1 bit ⇒ auto-reset on
XkbSetAutoResetControls
changes the auto-reset status and associated auto-reset
values for the controls selected by
changes.
For any control selected by
changes,
if the corresponding bit is set in
auto_ctrls,
the control is configured to auto-reset when the client exits. If the
corresponding bit in
auto_values
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
changes,
if the corresponding bit is not set in
auto_ctrls,
the control is configured to not reset when the client exits. For example:
To leave the auto-reset controls for
StickyKeys
the way they are:
ok = XkbSetAutoResetControls(dpy, 0, 0, 0);
To change the auto-reset controls so that
StickyKeys
are unaffected when the client exits:
ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, 0, 0);
To change the auto-reset controls so that
StickyKeys
are turned off when the client exits:
ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask, 0);
To change the auto-reset controls so that
StickyKeys
are turned on when the client exits:
ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask,
XkbStickyKeysMask);
XkbSetAutoResetControls
backfills
auto_ctrls
and
auto_values
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
changes
mask.
Control for Bell Behavior
The X server’s generation of sounds is controlled by the
AudibleBell
control. Configuration of different bell sounds is discussed in .
The AudibleBell Control
The
AudibleBell
control is a boolean control that has no attributes. As such, you may enable
and disable it using either the
EnabledControls
control or the
AutoReset
control discussed in section 10.1.1. When enabled, protocol requests to
generate a sound result in the X server actually producing a real sound; when
disabled, requests to the server to generate a sound are ignored unless the
sound is forced. See section 9.2.
Controls for Repeat Key Behaviorauto-repeatcontrols
The repeating behavior of keyboard keys is governed by three controls, the
PerKeyRepeat
control, which is always active, and the
RepeatKeys
and
DetectableAutorepeat
controls, which are boolean controls that may be enabled and disabled.
PerKeyRepeat
determines which keys are allowed to repeat.
RepeatKeys
governs the behavior of an individual key when it is repeating.
DetectableAutorepeat
allows a client to detect when a key is repeating as a result of being held
down.
The PerKeyRepeat Control
The
PerKeyRepeat
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
PerKeyRepeat
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
PerKeyRepeat
control settings are carried in the
per_key_repeat
field of an
XkbControlsRec
structure, discussed in section 10.8.
The RepeatKeys Control
The core protocol allows only control over whether or not the entire keyboard
or individual keys should auto-repeat when held down.
RepeatKeys
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.
RepeatKeys
is coupled with the core auto-repeat control: when
RepeatKeys
is enabled or disabled, the core auto-repeat is enabled or disabled and vice
versa.
Auto-repeating keys are controlled by two attributes. The first,
timeout,
is the delay after the initial press of an auto-repeating key and the first
generated repeat event. The second,
interval,
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.
To get the current attributes of the
RepeatKeys
control for a keyboard device, use
XkbGetAutoRepeatRate.
XkbGetAutoRepeatRateBool XkbGetAutoRepeatRateDisplay *displayunsigned int device_specunsigned int *timeout_rtrnunsigned int *interval_rtrndisplay
connection to X server
device_spec
desired device ID, or XkbUseCoreKbdtimeout_rtrn
backfilled with initial repeat delay, ms
interval_rtrn
backfilled with subsequent repeat delay, ms
XkbGetAutoRepeatRate
queries the server for the current values of the
RepeatControls
control attributes, backfills
timeout_rtrn
and
interval_rtrn
with them, and returns
True.
If a compatible version of the Xkb extension is not available in the server
XkbGetAutoRepeatRate
returns
False.
To set the attributes of the RepeatKeys control for a keyboard device, use
XkbSetAutoRepeatRate.
XkbSetAutoRepeatRateBool XkbSetAutoRepeatRateDisplay *displayunsigned int device_specunsigned int timeoutunsigned int intervaldisplay
connection to X server
device_spec
device to configure, or XkbUseCoreKbdtimeout
initial delay, ms
interval
delay between repeats, ms
XkbSetAutoRepeatRate
sends a request to the X server to configure the
AutoRepeat
control attributes to the values specified in
timeout
and
interval.
XkbSetAutoRepeatRate
does not wait for a reply; it normally returns
True.
Specifying a zero value for either
timeout
or
interval
causes the server to generate a
BadValue
protocol error. If a compatible version of the Xkb extension is not available
in the server,
XkbSetAutoRepeatRate
returns
False.
The DetectableAutorepeat Control
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
KeyPress
events with no intervening
KeyRelease
event. The standard behavior of the X server is to generate a
KeyRelease
event for every
KeyPress
event. If the keyboard hardware and device-dependent software of the X server
implement auto-repeat by generating multiple
KeyPress
events, the device-independent part of the X server by default synthetically
generates a
KeyRelease
event after each
KeyPress
event. This provides predictable behavior for X clients, but does not allow
those clients to detect the fact that a key is auto-repeating.
Xkb allows clients to request
detectable auto-repeat.
detectable auto-repeatauto-repeatdetectable
If a client requests and the server supports
DetectableAutorepeat,
Xkb generates
KeyRelease
events only when the key is physically released. If
DetectableAutorepeat
is not supported or has not been requested, the server synthesizes a
KeyRelease
event for each repeating
KeyPress
event it generates.
DetectableAutorepeat,
unlike the other controls in this chapter, is not contained in the
XkbControlsRec
structure, nor can it be enabled or disabled via the
EnabledControls
control. Instead, query and set
DetectableAutorepeat
using
XkbGetDetectableAutorepeat
and
XkbSetDetectableAutorepeat.
DetectableAutorepeat
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
DetectableAutorepeat
involve a device specifier.
To determine whether or not the server supports
DetectableAutorepeat,
use
XkbGetDetectableAutorepeat.
XkbGetDetectableAutorepeatBool XkbGetDetectableAutorepeatDisplay *displayBool *supported_rtrndisplay
connection to X server
supported_rtrn
backfilled True if
DetectableAutorepeat
supported
XkbGetDetectableAutorepeat
queries the server for the current state of
DetectableAutorepeat
and waits for a reply. If
supported_rtrn
is not
NULL,
it backfills supported_rtrn with
True
if the server supports
DetectableAutorepeat,
and
False
otherwise.
XkbGetDetectableAutorepeat
returns the current state of
DetectableAutorepeat
for the requesting client:
True
if
DetectableAutorepeat
is set, and
False
otherwise.
To set
DetectableAutorepeat,
use
XkbSetDetectableAutorepeat.
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.
XkbSetDetectableAutorepeatBool XkbSetDetectableAutorepeatDisplay *displayBool detectableBool *supported_rtrndisplay
connection to X server
detectableTrue ⇒ set
DetectableAutorepeatsupported_rtrn
backfilled True if
DetectableAutorepeat
supported
XkbSetDetectableAutorepeat
sends a request to the server to set
DetectableAutorepeat
on for the current client if
detectable
is
True,
and off it
detectable
is
False;
it then waits for a reply. If
supported_rtrn
is not
NULL,
XkbSetDetectableAutorepeat
backfills
supported_rtrn
with
True
if the server supports
DetectableAutorepeat,
and
False
if it does not.
XkbSetDetectableAutorepeat
returns the current state of
DetectableAutorepeat
for the requesting client:
True
if
DetectableAutorepeat
is set, and
False
otherwise.
Controls for Keyboard Overlays (Overlay1 and Overlay2 Controls)
A keyboard overlay allows some subset of the keyboard to report alternate
keycodes when the overlay is enabled. For example, a keyboard overlay can be
used to simulate a numeric or editing keypad on a keyboard that does not
actually have one by reusing some portion of the keyboard as an overlay. This
technique is very common on portable computers and embedded systems with small
keyboards.
Xkb includes direct support for two keyboard overlays, using the
Overlay1
and
Overlay2
controls. When
Overlay1
is enabled, all of the keys that are members of the first keyboard overlay
generate an alternate keycode. When
Overlay2
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.
Overlay1
and
Overlay2
are boolean controls. As such, you may enable and disable them using either
the
EnabledControls
control or the
AutoReset
control discussed in section 10.1.1.
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
XkbKB_Overlay1
or
XkbKB_Overlay2
key behaviors, as described in section 16.2.
Controls for Using the Mouse from the Keyboard
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
MouseKeys
control determines whether or not simulation of the pointer device is active,
as well as configuring the default button; the
MouseKeysAccel
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
EnabledControls
control or the
AutoReset
control discussed in section 10.1.1. The individual keys that simulate
different aspects of the pointer device are determined by the keyboard mapping,
discussed in .
The MouseKeys Control
The
MouseKeys
control allows a user to control all the mouse functions from the keyboard.
When
MouseKeys
are enabled, all keys with
MouseKeys
actions bound to them generate core pointer events instead of normal
KeyPress
and
KeyRelease
events.
The
MouseKeys
control has a single attribute,
mk_dflt_btn
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
XkbGetControls
and
XkbSetControls
(see section 10.9 and section 10.10).
MouseKeys
can also be turned on and off by pressing the key combination necessary to
produce an
XK_Pointer_EnableKeys
keysym. The de facto default standard for this is
ShiftAltNumLock,
but this may vary depending on the keymap.The MouseKeysAccel Control
When the
MouseKeysAccel
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
MouseKeysAccel
is enabled, mouse movement is defined by an initial distance specified in the
XkbSA_MovePtr
action and the following fields in the
XkbControlsRec
structure (see section 10.8).
MouseKeysAccel FieldsFieldFunctionmk_delayTime (ms) between the initial key press and the first repeated
motion eventmk_intervalTime (ms) between repeated motion eventsmk_time_to_maxNumber of events (count) before the pointer reaches maximum
speedmk_max_speedThe maximum speed (in pixels per event) the pointer reachesmk_curveThe ramp used to reach maximum pointer speed
There are no convenience functions to query or change the attributes of the
MouseKeysAccel
control; instead use
XkbGetControls
and
XkbSetControls
(see section 10.9 and section 10.10).
The effects of the attributes of the
MouseKeysAccel
control depend on whether the
XkbSA_MovePtr
action (see section 16.1) specifies relative or absolute pointer motion.
Absolute Pointer Motion
If an
XkbSA_MovePtr
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
XkbSA_MovePtr
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.
Relative Pointer Motion
If the
XkbSA_MovePtr
action specifies relative motion, the initial event always moves the cursor
the distance specified in the action. After
mk_delay
milliseconds, a second motion event is generated, and another occurs every
mk_interval
milliseconds until the user releases the key.
Between the time of the second motion event and
mk_time_to_max
intervals, the change in pointer distance per interval increases with each
interval. After
mk_time_to_max
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
mk_max_speed.
For example, if the
XkbSA_MovePtr
action specifies a relative motion in the X direction of 5,
mk_delay
=160,
mk_interval
=40,
mk_time_to_max
=30, and
mk_max_speed
=30, the following happens when the user presses the key:
The pointer immediately moves 5 pixels in the X direction when the key is
pressed.
After 160 milliseconds
(mk_delay),
and every 40 milliseconds thereafter
(mk_interval),
the pointer moves in the X direction.
The distance in the X direction increases with each interval until 30 intervals
(
mk_time_to_max)
have elapsed.
After 30 intervals, the pointer stops accelerating, and moves 150 pixels
(
mk_max_speed
* the original distance) every interval thereafter, until the key is released.
The increase in pointer difference for each interval is a function of
mk_curve.
Events after the first but before maximum acceleration has been achieved are
accelerated according to the formula:
Where
action_delta
is the relative motion specified by the
XkbSA_MovePtr
action,
mk_max_speed
and
mk_time_to_max
are parameters to the
MouseKeysAccel
control, and the curveFactor is computed using the
MouseKeysAccelmk_curve
parameter as follows:
With the result that a
mk_curve
of zero causes the distance moved to increase linearly from
action_delta
to .
A negative
mk_curve
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
mk_time_to_max.
The legal values for
mk_curve
are between −1000 and 1000.
A distance vs. time graph of the pointer motion is shown in
Figure 10.1.
MouseKeys AccelerationControls for Better Keyboard Access by Physically Impaired
Persons
The Xkb extension includes several controls specifically aimed at making
keyboard use more effective for physically impaired people. All of these
controls are boolean controls and may be individually enabled and disabled, as
well as configured to tune their specific behavior. The behavior of these
controls is based on the AccessDOS package
AccessDOS provides access to the DOS operating system for people with physical
impairments and was developed by the Trace R&D Center at the University of
Wisconsin. For more information on AccessDOS, contact the Trace R&D Center,
Waisman Center and Department of Industrial Engineering, University of
Wisconsin-Madison WI 53705-2280. Phone: 608-262-6966. e-mail: info@trace.wisc.edu.
.
The AccessXKeys Control
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
SlowKeys
(see section 10.6.6) may not even be able to start the graphical application,
let alone use it, if
SlowKeys
is not enabled. To allow easier access to some of the controls, the
AccessXKeys
control provides a set of special key sequences similar to those available in
AccessDOS.
When the
AccessXKeys
control is enabled, the user can turn controls on or off from the keyboard by
entering the following standard key sequences:
Holding down a Shift key by itself for eight seconds
toggles the
SlowKeys
control.
Pressing and releasing the left or right
Shift
key five times in a row, without any intervening key events and with less than
30 seconds delay between consecutive presses, toggles the state of the
StickyKeys
control.
Simultaneously operating two or more modifier keys deactivates the
StickyKeys
control.
When the
AccessXKeys
control is disabled, Xkb does not look for the above special key sequences.
Some of these key sequences optionally generate audible feedback of the change
in state, as described in section 10.6.3, or
XkbControlsNotify
events, described in section 10.11.
The AccessXTimeout Control
In environments where computers are shared, features such as
SlowKeys
present a problem: if
SlowKeys
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
AccessXTimeout
control to automatically change the enabled/disabled state of any boolean
controls and to change the value of the
AccessXKeys
and
AccessXFeedback
control attributes if the keyboard is idle for a specified period of time.
When a timeout as specified by
AccessXTimeout
occurs and a control is consequently modified, Xkb generates an
XkbControlsNotify
event. For more information on
XkbControlsNotify
events, refer to section 10.11.
Use
XkbGetAccessXTimeout
to query the current
AccessXTimeout
options for a keyboard device.
XkbGetAccessXTimeoutBool XkbGetAccessXTimeoutDisplay *displayunsigned int device_specunsigned short *timeout_rtrnunsigned int *ctrls_mask_rtrnunsigned int *ctrls_values_rtrnunsigned short *opts_mask_rtrnunsigned short *opts_values_rtrndisplay
connection to X server
device_spec
device to query, or XkbUseCoreKbdtimeout_rtrn
delay until AccessXTimeout, seconds
ctrls_mask_rtrn
backfilled with controls to modify
ctrls_values_rtrn
backfilled with on/off status for controls
opts_mask_rtrn
backfilled with ax_options to modify
opts_values_rtrn
backfilled with values for ax_optionsXkbGetAccessXTimeout
sends a request to the X server to obtain the current values for the
AccessXTimeout
attributes, waits for a reply, and backfills the values into the appropriate
arguments.
The parameters
opts_mask_rtrn
and
opts_values_rtrn
are backfilled with the options to modify and the values for
ax_options,
which is a field in the
XkbControlsRec
structure (see section 10.8).
XkbGetAccessXTimeout
returns
True
if successful; if a compatible version of the Xkb extension is not available
in the server,
XkbGetAccessXTimeout
returns
False.
To configure the
AccessXTimeout
options for a keyboard device, use
XkbSetAccessXTimeout.
XkbSetAccessXTimeoutBool XkbSetAccessXTimeoutDisplay *displayunsigned int device_specunsigned short timeoutunsigned int ctrls_maskunsigned int ctrls_valuesunsigned short opts_maskunsigned short opts_valuesdisplay
connection to X server
device_spec
device to configure, or XkbUseCoreKbdtimeout
seconds idle until AccessXTimeout occurs
ctrls_mask
boolean controls to modify
ctrls_values
new bits for controls selected by ctrls_maskopts_maskax_options to change
opts_values
new bits for ax_options selected by opts_masktimeout
specifies the number of seconds the keyboard must be idle before the controls
are modified.
ctrls_mask
specifies what controls are to be enabled or disabled, and
ctrls_values
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
opts_mask
field specifies which attributes of the
AccessXKeys
and
AccessXFeedback
controls are to be changed, and
opts_values
specifies the new values for those options. The bit values correspond to those
for the
ax_options
field of an
XkbDescRec
(see section 10.8).
XkbSetAccessXTimeout
sends a request to configure the
AccessXTimeout
control to the server.
It does not wait for a reply, and normally returns
True.
If a compatible version of the Xkb extension is not available in the server,
XkbSetAccessXTimeout
returns
False.
The AccessXFeedback Control
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
AccessXFeedback
control to configure the specific types of operations that generate feedback.
There is no convenience function for modifying the
AccessXFeedback
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
ax_options
field of an
XkbControlsRec
structure and using
XkbSetControls
(see section 10.10):
AccessXFeedback MasksActionBeep Codeax_options bitLED turned onHigh-pitched beepXkbAX_IndicatorFBMaskLED turned offLow-pitched beepXkbAX_IndicatorFBMaskMore than one LED changed stateTwo high-pitched beepsXkbAX_IndicatorFBMaskControl turned onRising toneXkbAX_FeatureFBMaskControl turned offFalling toneXkbAX_FeatureFBMaskMore than one control changed stateTwo high-pitched beepsXkbAX_FeatureFBMaskSlowKeys and BounceKeys about to be turned on or offThree high-pitched beepsXkbAX_SlowWarnFBMaskSlowKeys key pressedMedium-pitched beepXkbAX_SKPressFBMaskSlowKeys key acceptedMedium-pitched beepXkbAX_SKAcceptFBMaskSlowKeys key rejectedLow-pitched beepXkbAX_SKRejectFBMaskAccepted SlowKeys key releasedMedium-pitched beepXkbAX_SKReleaseFBMaskBounceKeys key rejectedLow-pitched beepXkbAX_BKRejectFBMaskStickyKeys key latchedLow-pitched beep followed by high-pitched beepXkbAX_StickyKeysFBMaskStickyKeys key lockedHigh-pitched beepXkbAX_StickyKeysFBMaskStickyKeys key unlockedLow-pitched beepXkbAX_StickyKeysFBMask
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
XkbAX_DumbBellFBMask
bit of
ax_options
to indicate that the bell can only ring with a fixed pitch.
When any of the above feedbacks occur, Xkb may generate a
XkbBellNotify
event (see section 9.4).
AccessXNotify EventseventsXkbAccessXNotifyXkbAccessXNotifyEvent
The server can generate
XkbAccessXNotify
events for some of the global keyboard controls. The structure for the
XkbAccessXNotify
event type is as follows:
typedef struct {
int type; /* Xkb extension base event code */
unsigned long serial; /* X server serial number for event */
Bool send_event; /* True ⇒ synthetically generated */
Display * display; /* server connection where event generated */
Time time; /* server time when event generated */
int xkb_type; /* XkbAccessXNotify */
int device; /* Xkb device ID, will not be XkbUseCoreKbd */
int detail; /* XkbAXN_* */
KeyCode keycode; /* key of event */
int slowKeysDelay; /* current SlowKeys delay */
int debounceDelay; /* current debounce delay */
} XkbAccessXNotifyEvent;
The
detail
field describes what AccessX event just occurred and can be any of the values
in Table 10.4.
AccessXNotify EventsdetailReasonXkbAXN_SKPressA key was pressed when SlowKeys was enabled.XkbAXN_SKAcceptA key was accepted (held longer than the SlowKeys delay).XkbAXN_SKReleaseAn accepted SlowKeys key was released.XkbAXN_SKRejectA key was rejected (released before the SlowKeys delay
expired).XkbAXN_BKAcceptA key was accepted by BounceKeys.XkbAXN_BKRejectA key was rejected (pressed before the BounceKeys delay
expired).XkbAXN_AXKWarningAccessXKeys is about to turn on/off StickyKeys or BounceKeys.
The
keycode
field reports the keycode of the key for which the event occurred. If the
action is related to
SlowKeys,
the
slowKeysDelay
field contains the current
SlowKeys
acceptance delay. If the action is related to
BounceKeys,
the
debounceDelay
field contains the current
BounceKeys
debounce delay.
Selecting for AccessX Events
To receive
XkbAccessXNotify
events under all possible conditions, use
XkbSelectEvents
(see section 4.3) and pass
XkbAccessXNotifyMask
in both
bits_to_change
and
values_for_bits.
To receive
XkbStateNotify
events only under certain conditions, use
XkbSelectEventDetails
using
XkbAccessXNotify
as the
event_type
and specifying the desired state changes in
bits_to_change
and
values_for_bits
using mask bits from Table 10.5.
StickyKeys, RepeatKeys, and MouseKeys Events
The
StickyKeys,
RepeatKeys,
and
MouseKeys
controls do not generate specific events. Instead, the latching, unlatching,
locking, or unlocking of modifiers using
StickyKeys
generates
XkbStateNotify
events as described in section 5.4. Repeating keys generate normal
KeyPress
and
KeyRelease
events, though the auto-repeat can be detected using
DetectableAutorepeat
(see section 10.3.3). Finally,
MouseKeys
generates pointer events identical to those of the core pointer device.
The SlowKeys Control
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
SlowKeys
control helps filter these accidental bumps by telling the server to wait a
specified period, called the
SlowKeys acceptance delay,
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.
SlowKeys
is a boolean control with one configurable attribute.
When the
SlowKeys
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
AccessXNotify
event (see section 10.6.4).
To get the
SlowKeys
acceptance delay for a keyboard device, use
XkbGetSlowKeysDelay.
XkbGetSlowKeysDelayBool XkbGetSlowKeysDelayDisplay *displayunsigned int device_specunsigned int *delay_rtrndisplay
connection to X server
device_spec
device ID, or XkbUseCoreKbddelay_rtrn
backfilled with SlowKeys delay, ms
XkbGetSlowKeysDelay
requests the attributes of the
SlowKeys
control from the server, waits for a reply and backfills
delay_rtrn
with the
SlowKeys
delay attribute.
XkbGetSlowKeysDelay
returns
True
if successful; if a compatible version of the Xkb extension is not available
in the server,
XkbGetSlowKeysDelay
returns
False.
To set the
SlowKeys
acceptance delay for a keyboard device, use
XkbSetSlowKeysDelay.
XkbSetSlowKeysDelayBool XkbSetSlowKeysDelayDisplay *displayunsigned int device_specunsigned int delaydisplay
connection to X server
device_spec
device to configure, or XkbUseCoreKbddelaySlowKeys delay, ms
XkbSetSlowKeysDelay
sends a request to configure the
SlowKeys
control to the server.
It does not wait for a reply, and normally returns
True.
Specifying a value of
0
for the
delay
parameter causes
XkbSetSlowKeysDelay
to generate a
BadValue
protocol error. If a compatible version of the Xkb extension is not available
in the server
XkbSetSlowKeysDelay
returns
False.
The BounceKeys Control
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
BounceKeys
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
BounceKeys delay.
BounceKeys
is a boolean control.
When the
BounceKeys
control is active, the server reports acceptance or rejection of any key to
interested clients by sending an appropriate
AccessXNotify
event (see section 10.6.4).
Use
XkbGetBounceKeysDelay
to query the current
BounceKeys
delay for a keyboard device.
XkbGetBounceKeysDelayBool XkbGetBounceKeysDelayDisplay *displayunsigned int device_specunsigned int *delay_rtrndisplay
connection to X server
device_spec
device ID, or XkbUseCoreKbddelay_rtrn
backfilled with bounce keys delay, ms
XkbGetBounceKeysDelay
requests the attributes of the
BounceKeys
control from the server, waits for a reply, and backfills
delay_rtrn
with the
BounceKeys
delay attribute.
XkbGetBounceKeysDelay
returns
True
if successful; if a compatible version of the Xkb extension is not available
in the server
XkbGetSlowKeysDelay
returns
False.
To set the
BounceKeys
delay for a keyboard device, use
XkbSetBounceKeysDelay.
XkbSetBounceKeysDelayBool XkbSetBounceKeysDelayDisplay *displayunsigned int device_specunsigned int delaydisplay
connection to X server
device_spec
device to configure, or XkbUseCoreKbddelay
bounce keys delay, ms
XkbSetBounceKeysDelay
sends a request to configure the
BounceKeys
control to the server.
It does not wait for a reply and normally returns
True.
Specifying a value of
zero
for the
delay
parameter causes
XkbSetBounceKeysDelay
to generate a
BadValue
protocol error. If a compatible version of the Xkb extension is not available
in the server,
XkbSetBounceKeysDelay
returns
False.
The StickyKeys Control
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
Shift
and
1
keys at the same time. The
StickyKeys
control solves this problem by changing the behavior of the modifier keys.
With
StickyKeys,
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
Shift
key, release it, and then press the
1
key.
StickyKeys
also allows users to lock modifier keys without requiring special locking
keys. When
StickyKeys
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.
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
ShiftControlZ
the user could press and release the
Shift
key to latch it, then press and release the
Control
key to latch it, and finally press and release the
Z key. Because the
Control
key is a modifier key, pressing it does not unlatch the
Shift
key. Thus, after the user presses the
Control
key, both the
Shift
and
Control
modifiers are latched. When the user presses the
Z
key, the effect is as though the user had pressed
ShiftControlZ.
In addition, because the
Z
key is not a modifier key, the
Shift
and
Control
modifiers are unlatched.
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
Shift
key twice to lock the
Shift
modifier. Then, when the user presses the
9,
',
x,
k,
b,
',
and
0
keys in sequence, it generates ("XKB"). To unlock the
Shift
modifier, the user can press and release the
Shift
key.
StickyKeys
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.
StickyKeys Options
The
StickyKeys
control has two options that can be accessed via the
ax_options
of an
XkbControlsRec
structure (see section 10.8). The first option,
TwoKeys,
specifies whether
StickyKeys
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
StickyKeys
off if a previous user left
StickyKeys
on. The second option,
LatchToLock,
specifies whether or not
StickyKeys
locks a modifier when pressed twice in a row.
Use
XkbGetStickyKeysOptions
to query the current
StickyKeys
attributes for a keyboard device.
XkbGetStickyKeysOptionsBool XkbGetStickyKeysOptionsDisplay *displayunsigned int device_specunsigned int *options_rtrndisplay
connection to X server
device_spec
device ID, or XkbUseCoreKbdoptions_rtrn
backfilled with StickyKeys option mask
XkbGetStickyKeysOptions
requests the attributes of the
StickyKeys
control from the server, waits for a reply, and backfills
options_rtrn
with a mask indicating whether the individual
StickyKeys
options are on or off. Valid bits in
options_rtrn
are:
XkbAX_TwoKeysMaskXkbAX_LatchToLockMaskXkbGetStickyKeysOptions
returns
True
if successful; if a compatible version of the Xkb extension is not available
in the server
XkbGetStickyKeysOptions
returns
False.
To set the
StickyKeys
attributes for a keyboard device, use
XkbSetStickyKeysOptions.
XkbSetStickyKeysOptionsBool XkbSetStickyKeysOptionsDisplay *displayunsigned int device_specunsigned int maskunsigned int valuesdisplay
connection to X server
device_spec
device to configure, or XkbUseCoreKbd
mask
selects StickyKeys attributes to modify
values
values for selected attributes
XkbSetStickyKeysOptions
sends a request to configure the
StickyKeys
control to the server.
It does not wait for a reply and normally returns
True.
The valid bits to use for both the
mask
and
values
parameters are:
XkbAX_TwoKeysMaskXkbAX_LatchToLockMask
If a compatible version of the Xkb extension is not available in the server,
XkbSetStickyKeysOptions
returns
False.
Controls for General Keyboard Mapping
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:
GroupsWrapIgnoreGroupLockIgnoreLockModsInternalModsIgnoreGroupLock
is a boolean control; the rest are always active.
Without the modifier processing options provided by Xkb, passive grabs set via
translations in a client (for example,
Alt<KeyPress>space)
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
NumLock
or a secondary keyboard group is active. The
IgnoreLockMods
and
IgnoreGroupLock
controls make it possible to avoid this behavior without exhaustively
specifying a grab for every possible modifier combination.
The GroupsWrap Control
The
GroupsWrap
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
GroupsWrap
control specifies how this is done.
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
GroupsWrap
control specifies which one is used:
XkbRedirectIntoRange
All invalid group numbers are converted to a valid group number by taking the
last four bits of the
GroupsWrap
control and using them as the group index. If the result is still out of
range, Group one is used.
XkbClampIntoRange
All invalid group numbers are converted to the nearest valid group number.
Group numbers larger than the highest supported group number are mapped to the
highest supported group; those less than one are mapped to group one.
XkbWrapIntoRange
All invalid group numbers are converted to a valid group number using integer
modulus applied to the group index.
There are no convenience functions for manipulating the
GroupsWrap
control. Manipulate the
GroupsWrap
control via the
groups_wrap
field in the
XkbControlsRec
structure, then use
XkbSetControls
and
XkbGetControls
(see section 10.9 and section 10.10) to query and change this control.
See also section 15.3.2 or a discussion of the related field,
group_info,
which also normalizes a group under certain circumstances.The IgnoreLockMods Control
The core protocol does not provide a way to exclude specific modifiers from
grab calculations, with the result that locking modifiers sometimes have
unanticipated side effects.
The
IgnoreLockMods
control specifies modifiers that should be excluded from grab calculations.
These modifiers are also not reported in any core events except
KeyPress
and
KeyRelease
events that do not activate a passive grab and that do not occur while a grab
is active.
Manipulate the
IgnoreLockMods
control via the
ignore_lock
field in the
XkbControlsRec
structure, then use
XkbSetControls
and
XkbGetControls
(see section 10.9 and section 10.10) to query and change this control. Alternatively,
use
XkbSetIgnoreLockMods.
To set the modifiers that, if locked, are not to be reported in matching events
to passive grabs, use
XkbSetIgnoreLockMods.
XkbSetIgnoreLockModsBool XkbSetIgnoreLockModsDisplay *displayunsigned int device_specunsigned int affect_realunsigned int real_valuesunsigned int affect_virtualunsigned int virtual_valuesdisplay
connection to the X server
device_spec
device ID, or XkbUseCoreKbdaffect_real
mask of real modifiers affected by this call
real_values
values for affected real modifiers (1⇒set, 0⇒unset)
affect_virtual
mask of virtual modifiers affected by this call
virtual_values
values for affected virtual modifiers (1⇒set, 0⇒unset)
XkbSetIgnoreLockMods
sends a request to the server to change the server’s
IgnoreLockMods
control.
affect_real
and
real_values
are masks of real modifier bits indicating which real modifiers are to be
added and removed from the server’s
IgnoreLockMods
control. Modifiers selected by both
affect_real
and
real_values
are added to the server’s
IgnoreLockMods
control; those selected by
affect_real
but not by
real_values
are removed from the server’s
IgnoreLockMods
control. Valid values for
affect_real
and
real_values
consist of any combination of the eight core modifier bits:
ShiftMask,
LockMask,
ControlMask,
Mod1Mask
–
Mod5Mask.
affect_virtual
and
virtual_values
are masks of virtual modifier bits indicating which virtual modifiers are to
be added and removed from the server’s
IgnoreLockMods
control. Modifiers selected by both
affect_virtual
and
virtual_values
are added to the server’s
IgnoreLockMods
control; those selected by
affect_virtual
but not by
virtual_values
are removed from the server’s
IgnoreLockMods
control.
See section 7.1 for a discussion of virtual modifier masks to use in
affect_virtual
and
virtual_values.
XkbSetIgnoreLockMods
does not wait for a reply from the server. It returns
True
if the request was sent, and
False
otherwise.
The IgnoreGroupLock Control
The
IgnoreGroupLock
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.
Because
IgnoreGroupLock
is a boolean control with no attributes, use the general boolean controls
functions (see section 10.1) to change its state.
The InternalMods Control
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
InternalMods
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
InternalMods
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
InternalMods
control are not used to determine grabs and are not used to calculate core
protocol compatibility state.
Manipulate the
InternalMods
control via the
internal
field in the
XkbControlsRec
structure, using
XkbSetControls
and
XkbGetControls
(see section 10.9
and section 10.10). Alternatively, use
XkbSetServerInternalMods.
To set the modifiers that are consumed by the server before events are
delivered to the client, use
XkbSetServerInternalMods.
XkbSetServerInternalModsBool XkbSetServerInternalModsDisplay *displayunsigned int device_specunsigned int affect_realunsigned int real_valuesunsigned int affect_virtualunsigned int virtual_valuesdisplay
connection to the X server
device_spec
‘device ID, or XkbUseCoreKbdaffect_real
mask of real modifiers affected by this call
real_values
values for affected real modifiers (1⇒set, 0⇒unset)
affect_virtual
mask of virtual modifiers affected by this call
virtual_values
values for affected virtual modifiers (1⇒set, 0⇒unset)
XkbSetServerInternalMods
sends a request to the server to change the internal modifiers consumed by the
server.
affect_real
and
real_values
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
affect_real
and
real_values
are added to the server’s internal modifiers control; those selected by
affect_real
but not by
real_values
are removed from the server’s internal modifiers mask. Valid values for
affect_real
and
real_values
consist of any combination of the eight core modifier bits:
ShiftMask,
LockMask,
ControlMask,
Mod1Mask
–
Mod5Mask.
affect_virtual
and
virtual_values
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
affect_virtual
and
virtual_values
are added to the server’s internal modifiers control; those selected by
affect_virtual
but not by
virtual_values
are removed from the server’s internal modifiers control.
See section 7.1 for a discussion of virtual modifier masks to use in
affect_virtual
and
virtual_values.
XkbSetServerInternalMods
does not wait for a reply from the server. It returns
True
if the request was sent and
False
otherwise.
The XkbControlsRec StructureXkbControlsRec
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
XkbControlsRec
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
XkbGetControls
and
XkbSetControls
functions. This is the only way to manipulate those controls that have no
convenience functions.
The
XkbControlsRec
structure is defined as follows:
#define XkbMaxLegalKeyCode 255
#define XkbPerKeyBitArraySize ((XkbMaxLegalKeyCode+1)/8)
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 enabled_ctrls
to modify */
unsigned int axt_ctrls_values; /* values for new bits in
enabled_ctrls */
unsigned char per_key_repeat[XkbPerKeyBitArraySize];
/* per key auto repeat */
} XkbControlsRec, *XkbControlsPtr;
The general-purpose functions that work with the
XkbControlsRec
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
(which
parameter), and the data fields in the
XkbControlsRec
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.
Xkb ControlsControlControl Selection Mask (which parameter)Relevant XkbControlsRec Data FieldsBoolean Control enabled_ctrls bitSectionAccessXFeedbackXkbAccessXFeedbackMaskax_options: XkbAX_*FBMaskXkbAccessXFeedbackMask10.6.3AccessXKeysXkbAccessXKeysMask10.6.1AccessXTimeoutXkbAccessXTimeoutMaskax_timeoutaxt_opts_maskaxt_opts_valuesaxt_ctrls_maskaxt_ctrls_valuesXkbAccessXTimeoutMask10.6.2AudibleBellXkbAudibleBellMask9.2AutoReset10.1.2BounceKeysXkbBounceKeysMaskdebounce_delayXkbBounceKeysMask10.6.7Detectable-Autorepeat10.3.3EnabledControlsXkbControlsEnabledMaskenabled_ctrlsNon-Boolean Control10.1.1GroupsWrapXkbGroupsWrapMaskgroups_wrapNon-Boolean Control10.7.1IgnoreGroupLockXkbIgnoreGroupLockMask10.7.3IgnoreLockModsXkbIgnoreLockModsMaskignore_lockNon-Boolean Control5.1InternalModsXkbInternalModsMaskinternalNon-Boolean Control5.1MouseKeysXkbMouseKeysMaskmk_dflt_btnXkbMouseKeysMask10.5.1MouseKeysAccelXkbMouseKeysAccelMaskmk_delaymk_intervalmk_time_to_maxmk_max_speedmk_curveXkbMouseKeysAccelMask10.5.2Overlay1XkbOverlay1Mask10.4Overlay2XkbOverlay2Mask10.4PerKeyRepeatXkbPerKeyRepeatMaskper_key_repeatNon-Boolean Control10.3.1RepeatKeysXkbRepeatKeysMaskrepeat_delayrepeat_intervalXkbRepeatKeysMask10.3SlowKeysXkbSlowKeysMaskslow_keys_delayXkbSlowKeysMask10.6.6StickyKeysXkbStickyKeysMaskax_options:XkbAX_TwoKeysMaskXkbAX_LatchToLockMaskXkbStickyKeysMask10.6.8
Table 10.7
shows the actual values for the individual mask bits used to select
controls for modification and to enable and disable the control. Note that the
same mask bit is used to specify general modifications to the parameters used
to configure the control
(which),
and to enable and disable the control
(enabled_ctrls).
The anomalies in the table (no ok in column) are for controls that have no
configurable attributes; and for controls that are not boolean controls and
therefore cannot be enabled or disabled.
Controls Mask BitsMask Bitwhich or changed_ctrlsenabled_ctrlsValueXkbRepeatKeysMaskokok(1L<<0)XkbSlowKeysMaskokok(1L<<1)XkbBounceKeysMaskokok(1L<<2)XkbStickyKeysMaskokok(1L<<3)XkbMouseKeysMaskokok(1L<<4)XkbMouseKeysAccelMaskokok(1L<<5)XkbAccessXKeysMaskokok(1L<<6)XkbAccessXTimeoutMaskokok(1L<<7)XkbAccessXFeedbackMaskokok(1L<<8)XkbAudibleBellMaskok(1L<<9)XkbOverlay1Maskok(1L<<10)XkbOverlay2Maskok(1L<<11)XkbIgnoreGroupLockMaskok(1L<<12)XkbGroupsWrapMaskok(1L<<27)XkbInternalModsMaskok(1L<<28)XkbIgnoreLockModsMaskok(1L<<29)XkbPerKeyRepeatMaskok(1L<<30)XkbControlsEnabledMaskok(1L<<31)XkbAccessXOptionsMaskokok(XkbStickyKeysMask | XkbAccessXFeedbackMask)XkbAllBooleanCtrlsMaskok(0x00001FFF) XkbAllControlsMaskok(0xF8001FFF)
The individual fields of the
XkbControlsRec
structure are defined as follows.
mk_dflt_btnmk_dflt_btn is an attribute of the
MouseKeys
control
(see section 10.5). It
specifies the mouse button number to use for keyboard simulated mouse button
operations. Its value should be one of the core symbols
Button1
–
Button5.
num_groupsnum_groups
is not a part of any control, but is reported in the
XkbControlsRec
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.
groups_wrapgroups_wrap
is an attribute of the
GroupsWrap
control (see section 10.7.1). It specifies the handling of illegal groups on a
global basis. Valid values for
groups_wrap
are shown in Table 10.8.
When
groups_wrap
is set to
XkbRedirectIntoRange,
its four low-order bits specify the index of the group to use.
internalinternal
is an attribute of the
InternalMods
control (see section 10.7.4). It specifies modifiers to be consumed in the
server and not passed on to clients when events are reported. Valid values
consist of any combination of the eight core modifier bits:
ShiftMask,
LockMask,
ControlMask,
Mod1Mask
–
Mod5Mask.
ignore_lockignore_lock
is an attribute of the
IgnoreLockMods
control (see section 10.7.2). It specifies modifiers to be ignored in grab
calculations. Valid values consist of any combination of the eight core
modifier bits:
ShiftMask,
LockMask,
ControlMask,
Mod1Mask
–
Mod5Mask.
enabled_ctrlsenabled_ctrls
is an attribute of the
EnabledControls
control (see section 10.1.1). It contains one bit per boolean control. Each
bit determines whether the corresponding control is enabled or disabled; a one
bit means the control is enabled. The mask bits used to enable these controls
are listed in Table 10.7,
using only those masks with ok in the
enabled_ctrls
column.
repeat_delay and repeat_intervalrepeat_delay
and
repeat_interval
are attributes of the
RepeatKeys
control (see section 10.3.2).
repeat_delay
is the initial delay before a key begins repeating, in milliseconds;
repeat_interval
is the delay between subsequent key events, in milliseconds.
slow_keys_delayslow_keys_delay
is an attribute of the
SlowKeys
control (see section 10.6.6). Its value specifies the
SlowKeys
acceptance delay period in milliseconds before a key press is accepted by the
server.
debounce_delaydebounce_delay
is an attribute of the
BounceKeys
control (see section 10.6.7). Its value specifies the
BounceKeys
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.
mk_delay, mk_interval, mk_time_to_max, mk_max_speed, and mk_curvemk_delay,
mk_interval,
mk_time_to_max,
mk_max_speed,
and
mk_curve
are attributes of the
MouseKeysAccel
control. Refer to section 10.5.2 for a description of these fields and the
units involved.
ax_options
The
ax_options
field contains attributes used to configure two different controls, the
StickyKeys
control (see section 10.6.8) and the
AccessXFeedback
control (see section 10.6.3). The
ax_options
field is a bitmask and may include any combination of the bits defined in
Table 10.9.
The fields pertaining to each control are relevant only when the control is
enabled
(XkbAccessXFeedbackMask
or
XkbStickyKeysMask
bit is turned on in the
enabled_ctrls
field).
Xkb provides a set of convenience macros for working with the
ax_options
field of an
XkbControlsRec
structure:
#define XkbAX_NeedOption(c,w) ((c)->ax_options & (w))
The
XkbAX_NeedOption
macro is useful for determining whether a particular AccessX option is enabled
or not. It accepts a pointer to an
XkbControlsRec
structure and a valid mask bit from
Table 10.9.
If the specified mask bit in the
ax_options
field of the controls structure is set, the macro returns the mask bit.
Otherwise, it returns zero. Thus,
XkbAX_NeedOption(ctlrec, XkbAX_LatchToLockMask)
is nonzero if the latch to lock transition for latching keys is enabled, and
zero if it is disabled. Note that
XkbAX_NeedOption
only determines whether or not the particular capability is configured to
operate; the
XkbAccessXFeedbackMask
bit must also be turned on in
enabled_ctrls
for the capability to actually be functioning.
#define XkbAX_AnyFeedback(c) \
((c)->enabled_ctrls & XkbAccessXFeedbackMask)
The
XkbAX_AnyFeedback
macro accepts a pointer to an
XkbControlsRec
structure and tells whether the
AccessXFeedback
control is enabled or not. If the
AccessXFeedback
control is enabled, the macro returns
XkbAccessXFeedbackMask.
Otherwise, it returns zero.
#define XkbAX_NeedFeedback(c,w) \
(XkbAX_AnyFeedback(c) && XkbAX_NeedOption(c,w))
The
XkbAX_NeedFeedback
macro is useful for determining if both the
AccessXFeedback
control and a particular AccessX feedback option are enabled. The macro
accepts a pointer to an
XkbControlsRec
structure and a feedback option from the table above. If both the
AccessXFeedback
control and the specified feedback option are enabled, the macro returns
True.
Otherwise it returns
False.
ax_timeout, axt_opts_mask, axt_opts_values, axt_ctrls_mask, and axt_ctrls_valuesax_timeout,
axt_opts_mask,
axt_opts_values,
axt_ctrls_mask,
and
axt_ctrls_values
are attributes of the
AccessXTimeout
control. Refer to section 10.6.2 for a description of these fields and the
units involved.
per_key_repeat
The
per_key_repeat
field mirrors the
auto_repeats
field of the core protocol
XKeyboardState
structure: changing the
auto_repeats
field automatically changes
per_key_repeat
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
XkbGetControls.
If the
per_key_repeat
were not in this structure, you would have to call both
XGetKeyboardControl
and
XkbGetControls
to get this information. The bits correspond to keycodes. The first seven keys
(keycodes 1–7) are indicated in
per_key_repeat[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.
Querying Controls
Use
XkbGetControls
to find the current state of Xkb server controls.
XkbGetControlsStatus XkbGetControlsDisplay *displayunsigned long whichXkbDescPtr xkbdisplay
connection to X server
which
mask of controls requested
xkb
keyboard description for controls information
XkbGetControls
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
ctrls
structure of the
xkb
argument. Only those components specified by the
which
parameter are copied. Valid values for
which
are any combination of the masks listed in
Table 10.7 that have ok in the
which
column.
If
xkb->ctrls
is
NULL,
XkbGetControls
allocates and initializes it before obtaining the values specified by
which.
If
xkb->ctrls
is not
NULL,
XkbGetControls
modifies only those portions of
xkb->ctrls
corresponding to the values specified by
which.
XkbGetControls
returns
Success
if successful; otherwise, it returns
BadAlloc
if it cannot obtain sufficient storage,
BadMatch
if
xkb
is
NULL
or
which
is empty, or
BadImplementation.
To free the
ctrls
member of a keyboard description, use
XkbFreeControls
(see section 10.12)
The
num_groups
field in the
ctrls
structure is always filled in by
XkbGetControls,
regardless of which bits are selected by
which.
Changing Controls
There are two ways to make changes to controls: either change a local copy
keyboard description and call
XkbSetControls,
or, to reduce network traffic, use an
XkbControlsChangesRec
structure and call
XkbChangeControls.
To change the state of one or more controls, first modify the
ctrls
structure in a local copy of the keyboard description and then use
XkbSetControls
to copy those changes to the X server.
XkbSetControlsBool XkbSetControlsDisplay *displayunsigned long whichXkbDescPtr xkbdisplay
connection to X server
which
mask of controls to change
xkbctrls field contains new values to be set
For each bit that is set in the
which
parameter,
XkbSetControls
sends the corresponding values from the
xkb->ctrls
field to the server. Valid values for
which
are any combination of the masks listed in
Table 10.7 that have ok in the
which
column.
If
xkb->ctrls
is
NULL,
the server does not support a compatible version of Xkb, or the Xkb extension
has not been properly initialized,
XkbSetControls
returns
False.
Otherwise, it sends the request to the X server and returns
True.
Note that changes to attributes of controls in the
XkbControlsRec
structure are apparent only when the associated control is enabled, although
the corresponding values are still updated in the X server. For example, the
repeat_delay
and
repeat_interval
fields are ignored unless the
RepeatKeys
control is enabled (that is, the X server’s equivalent of
xkb->ctrls
has
XkbRepeatKeysMask
set in
enabled_ctrls).
It is permissible to modify the attributes of a control in one call to
XkbSetControls and enable the control in a subsequent call. See section 10.1.1
for more information on enabling and disabling controls.
Note that the
enabled_ctrls
field is itself a control — the
EnabledControls
control. As such, to set a specific configuration of enabled and disabled
boolean controls, you must set
enabled_ctrls
to the appropriate bits to enable only the controls you want and disable all
others, then specify the
XkbControlsEnabledMask
in a call to
XkbSetControls.
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
(XkbChangeEnabledControls,
section 10.1.1).
The XkbControlsChangesRec StructureXkbControlsChangesRec
The
XkbControlsChangesRec
structure allows applications to track modifications to an
XkbControlsRec
structure and thereby reduce the amount of traffic sent to the server. The
same
XkbControlsChangesRec
structure may be used in several successive modifications to the same
XkbControlsRec
structure, then subsequently used to cause all of the changes, and only the
changes, to be propagated to the server. The
XkbControlsChangesRec
structure is defined as follows:
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; /* True if number of keyboard
groups changed */
} XkbControlsChangesRec, *XkbControlsChangesPtr;
The
changed_ctrls
field is a mask specifying which logical sets of data in the controls
structure have been modified. In this context, modified means
set,
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
changed_ctrls
are any combination of the masks listed in
Table 10.7 that have ok in the
changed_ctrls
column. Setting a bit implies the corresponding data fields from the
Relevant XkbControlsRec Data Fields column in
Table 10.6 have been modified. The
enabled_ctrls_changes
field specifies which bits in the
enabled_ctrls
field have changed. If the number of keyboard groups has changed, the
num_groups_changed
field is set to True.
If you have an Xkb description with controls that have been modified and an
XkbControlsChangesRec
that describes the changes that have been made, the
XkbChangeControls
function provides a flexible method for updating the controls in a server to
match those in the changed keyboard description.
XkbChangeControlsBool XkbChangeControlsDisplay *dpyXkbDescPtr xkbXkbControlsChangesPtr changesdpy
connection to X server
xkb
keyboard description with changed xkb->ctrlschanges
which parts of xkb->ctrls have changed
XkbChangeControls
copies any controls fields specified by
changes
from the keyboard description controls structure,
xkb->ctrls,
to the server specified by
dpy.
Tracking Changes to Keyboard ControlseventsXkbControlsNotifyXkbControlsNotifyEvent
Whenever a field in the controls structure changes in the server’s keyboard
description, the server sends an
XkbControlsNotify
event to all interested clients.To receive
XkbControlsNotify
events under all possible conditions, use
XkbSelectEvents
(see section 4.3) and pass
XkbControlsNotifyMask
in both
bits_to_change
and
values_for_bits.
To receive
XkbControlsNotify
events only under certain conditions, use
XkbSelectEventDetails
using
XkbControlsNotify
as the
event_type
and specifying the desired state changes in
bits_to_change
and
values_for_bits
using mask bits from Table 10.7.
The structure for the
XkbControlsNotify
event is defined as follows:
typedef struct {
int type; /* Xkb extension base event code */
unsigned long serial; /* X server serial number for event */
Bool send_event; /* True ⇒ synthetically generated */
Display * display; /* server connection where event generated */
Time time; /* server time when event generated */
int xkb_type; /* XkbCompatMapNotify */
int device; /* Xkb device ID,
will not be XkbUseCoreKbd */
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 */
} XkbControlsNotifyEvent;
The
changed_ctrls
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
changed_ctrls
column.
The controls currently enabled in the server are reported in the
enabled_ctrls
field. If any controls were just enabled or disabled (that is, the contents of
the
enabled_ctrls
field changed), they are flagged in the
enabled_ctrl_changes
field. The valid bits for these fields are the masks listed in
Table 10.7 with
ok in the
enabled_ctrls
column. The
num_groups
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.
If the change was caused by a request from a client, the
keycode
and
event_type
fields are set to
zero
and the
req_major
and
req_minor
fields identify the request. The
req_major
value is the same as the major extension opcode. Otherwise,
event_type
is set to the type of event that caused the change (one of
KeyPress,
KeyRelease,
DeviceKeyPress,
DeviceKeyRelease,
ButtonPress
or
ButtonRelease),
and
req_major
and
req_minor
are undefined. If
event_type
is
KeyPress,
KeyRelease,
DeviceKeyPress,
or
DeviceKeyRelease,
the
keycode
field is set to the key that caused the change. If
event_type
is
ButtonPress
or
ButtonRelease,
keycode
contains the button number.
When a client receives an
XkbControlsNotify
event, it can note the changes in a changes structure using
XkbNoteControlsChanges.
XkbNoteControlsChangesvoid XkbNoteControlsChangesXkbControlsChangesPtr changesXkbControlsNotifyEvent *newunsigned int wantedchanges
records changes indicated by new
new
tells which things have changed
wanted
tells which parts of new to record in changes
The
wanted
parameter is a bitwise inclusive OR of bits taken from the set of masks
specified in Table 10.7 with ok
in the
changed_ctrls
column.
XkbNoteControlsChanges
copies any changes reported in
new
and specified in
wanted
into the changes record specified by
changes.
Use
XkbGetControlsChanges
to update a local copy of a keyboard description with the changes previously
noted by one or more calls to
XkbNoteControlsChanges.
XkbGetControlsChangesStatus XkbGetControlsChangesDisplay *dpyXkbDescPtr xkbXkbNameChangesPtr changesdpy
connection to X server
xkbxkb->ctrls will be updated
changes
indicates which parts of xkb->ctrls to update
XkbGetControlsChanges
examines the
changes
parameter, queries the server for the necessary information, and copies the
results into the
xkb->ctrls
keyboard description. If the
ctrls
field of
xkb
is
NULL,
XkbGetControlsChanges
allocates and initializes it. To free the
ctrls
field, use
XkbFreeControls
(see section 10.12).
XkbGetControlsChanges
returns
Success
if successful and can generate
BadAlloc,
BadImplementation,
and
BadMatch
errors.
Allocating and Freeing an XkbControlsRec
The need to allocate an
XkbControlsRec
structure seldom arises; Xkb creates one when an application calls
XkbGetControls
or a related function. For those situations where there is not an
XkbControlsRec
structure allocated in the
XkbDescRec,
allocate one by calling
XkbAllocControls.
XkbAllocControlsStatus XkbAllocControlsXkbDescPtr xkbunsigned int whichxkb
Xkb description in which to allocate ctrls rec
which
mask of components of ctrls to allocate
XkbAllocControls
allocates the
ctrls
field of the
xkb
parameter, initializes all fields to zero, and returns
Success.
If the
ctrls
field is not
NULL,
XkbAllocControls
simply returns
Success.
If
xkb
is
NULL,
XkbAllocControls
reports a
BadMatch
error. If the
ctrls
field could not be allocated, it reports a
BadAlloc
error.
The
which
mask specifies the individual fields of the
ctrls
structure to be allocated and can contain any of the valid masks defined in
Table 10.7.
Because none of the currently existing controls have any structures
associated with them, which is currently of little practical value in this call.
To free memory used by the
ctrls
member of an
XkbDescRec
structure, use
XkbFreeControls:
XkbFreeControlsvoid XkbFreeControlsXkbDescPtr xkbunsigned int whichBool free_allxkb
Xkb description in which to free controls components
which
mask of components of ctrls to free
free_allTrue ⇒ free everything + ctrls itself
XkbFreeControls
frees the specified components of the
ctrls
field in the
xkb
keyboard description and sets the corresponding structure component values to
NULL
or
zero.
The
which
mask specifies the fields of
ctrls
to be freed and can contain any of the controls components specified in
Table 10.7.
If
free_all
is
True,
XkbFreeControls
frees every non-
NULL
structure component in the controls, frees the
XkbControlsRec
structure referenced by the
ctrls
member of
xkb,
and sets
ctrls
to
NULL.
The Miscellaneous Per-client Controls
You can configure the boolean per-client controls which affect the state
reported in button and key events. See
section 12.1.1,
12.3,
12.5,
and
16.3.11
of the
XKB Protocol specification
for more details.
To get the current values of the
per-client
controls, use
XkbGetPerClientControls.
XkbGetPerClientControlsBool XkbGetPerClientControlsDisplay *dpyunsigned int *ctrlsdpy
connection to X server
ctrls
1 bit ⇒ corresponding control is on
XkbGetPerClientControls
backfills
ctrls
with the
per-client
control attributes for this particular client. It returns
True
if successful, and
False
otherwise.
To change the current values of the
per-client
control attributes, use
XkbSetPerClientControls.
XkbSetPerClientControlsBool XkbSetPerClientControlsDisplay *dpyunsigned int changeunsigned int *valuedpy
connection to X server
change
1 bit ⇒ change control
value
1 bit ⇒ control on
XkbSetPerClientControls
changes the per-client values for the controls selected by
change to the corresponding value in
value. Legal values for
change and value
are: XkbPCF_GrabsUseXKBStateMask, XkbPCF_LookupStateWhenGrabbed, and
XkbPCF_SendEventUsesXKBState. More than one control may be changed at one time
by OR-ing the values together. XkbSetPerClientControls backfills value with the
per-client
control attributes for this particular client.
It returns
True
if successful, and
False
otherwise.
xkbReplacing a Keyboard <quote>On the Fly</quote>
Some operating system and X server implementations allow
hot plugging of
input devices. When using these implementations, input devices can be unplugged
and new ones plugged in without restarting the software that is using those
devices. There is no provision in the standard X server for notification of
client programs if input devices are unplugged and/or new ones plugged in. In
the case of the X keyboard, this could result in the X server having a keymap
that does not match the new keyboard.
If the X server implementation supports the X input device extension, a client
program may also change the X keyboard programmatically. The
XChangeKeyboardDevice input extension request allows a client to designate an
input extension keyboard device as the X keyboard, in which case the old X
keyboard device becomes inaccessible except via the input device extension. In
this case, core protocol
MappingNotify
and input extension
XChangeDeviceNotify
events are generated to notify all clients that a new keyboard with a new
keymap has been designated.
When a client opens a connection to the X server, the server reports the
minimum and maximum keycodes. The server keeps track of the minimum and maximum
keycodes last reported to each client. When delivering events to a particular
client, the server filters out any events that fall outside of the valid range
for the client.
Xkb provides an
XkbNewKeyboardNotify
event that reports a change in keyboard geometry and/or the range of supported
keycodes. The server can generate an
XkbNewKeyboardNotify
event when it detects a new keyboard or in response to an
XkbGetKeyboardByName
request that loads a new keyboard description. Selecting for
XkbNewKeyboardNotify
events allows Xkb-aware clients to be notified whenever a keyboard change
occurs that may affect the keymap.
When a client requests
XkbNewKeyboardNotify
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
XkbNewKeyboardNotify
event. Even if the new keyboard is not new to the server,
it is new to this particular client.
When the server sends an
XkbNewKeyboardNotify
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
XkbNewKeyboardNotify
event to a client. Because Xkb-unaware clients and Xkb-aware clients that do
not request
XkbNewKeyboardNotify
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.
Clients that have not selected to receive
XkbNewKeyboardNotify
events do, however, receive the
XkbNewKeyboardNotify
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.
Clients wishing to track changes in
min_key_code
and
max_key_code
must watch for both
XkbNewKeyboardNotify
and
XkbMapNotify
events, because a simple mapping change causes an
XkbMapNotify
event and may change the range of valid keycodes, but does not cause an
XkbNewKeyboardNotify
event. If a client does not select for
XkbNewKeyboardNotify
events, the server restricts the range of keycodes reported to the client.
In addition to filtering out-of-range key events, Xkb:
Adjusts core protocol
MappingNotify
events to refer only to keys that match the stored legal range.
Reports keyboard mappings for keys that match the stored legal range to clients
that issue a core protocol
GetKeyboardMapping
request.
Reports modifier mappings only for keys that match the stored legal range to
clients that issue a core protocol
GetModifierMapping
request.
Restricts the core protocol
ChangeKeyboardMapping
and
SetModifierMapping
requests to keys that fall inside the stored legal range.
In short, Xkb does everything possible to hide from Xkb-unaware clients the
fact that the range of legal keycodes has changed, because such clients cannot
be expected to deal with them. Xkb events and requests are not modified in this
manner; all Xkb events report the full range of legal keycodes. No requested
Xkb events are discarded, and no Xkb requests have their keycode range clamped.
eventsXkbNewKeyboardNotifyXkbNewKeyboardNotifyEvent
The structure for the
XkbNewKeyboardNotify
event is defined as follows:
typedef struct _XkbNewKeyboardNotify {
int type; /* Xkb extension base event code */
unsigned long serial; /* X server serial number for event */
Bool send_event; /* True ⇒ synthetically generated */
Display * display; /* server connection where event generated */
Time time; /* server time when event generated */
int xkb_type; /* XkbNewKeyboardNotify */
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 */
} XkbNewKeyboardNotifyEvent;
To receive name notify events, use
XkbSelectEvents
(see section 4.3) with
XkbNewKeyboardNotifyMask
in both the
bits_to_change
and
values_for_bits
parameters. To receive events for only specific names, use
XkbSelectEventDetails.
Set the
event_type
parameter to
XkbNewKeyboardNotify,
and set both the
bits_to_change
and
values_for_bits
detail parameter to a mask composed of a bitwise OR of masks in
Table 19.1.
XkbNewKeyboardNotifyEvent DetailsXkbNewKeyboardNotify Event DetailsValueCircumstancesXkbNKN_KeycodesMask(1L<<0)Notification of keycode range changes wantedXkbNKN_GeometryMask(1L<<1)Notification of geometry changes wantedXkbNKN_DeviceIDMask(1L<<2)Notification of device ID changes wantedXkbAllNewKeyboardEventsMask(0x7)Includes all of the above masks
The
req_major
and
req_minor
fields indicate what type of keyboard change has occurred.
If
req_major
and
req_minor
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,
device
is the device identifier for the new, current X keyboard device, but no
implementation-independent guarantee can be made about
old_device.
old_device
may be identical to
device
(an implementor is permitted to reuse the device specifier when the device
changes); or it may be different. Note that
req_major
and
req_minor
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).
If the keyboard change is the result of an X Input Extension
ChangeKeyboardDevice
request,
req_major
contains the input extension major opcode, and
req_minor
contains the input extension request number for
X_ChangeKeyboardDevice.
In this case,
device
and
old_device
are different, with
device
being the identifier for the new, current X keyboard device, and
old_device
being the identifier for the former device.
If the keyboard change is the result of an
XkbGetKeyboardByName
function call, which generates an
X_kbGetKbdByName
request,
req_major
contains the Xkb extension base event code (see section 2.4), and
req_minor
contains the event code for the Xkb extension request
X_kbGetKbdByName.
device
contains the device identifier for the new device, but nothing definitive can
be said for
old_device;
it may be identical to
device,
or it may be different, depending on the implementation.
libX11-1.6.3/specs/XKB/XKBlib-20.svg 0000644 0143106 0000012 00000042246 12477417235 0016702 0 ustar 00alanc staff 0000266 0200006
letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:DejaVu Sans;-inkscape-font-specification:DejaVu Sans"
xml:space="preserve">groups[1]libX11-1.6.3/specs/XKB/XKBlib-9.svg 0000644 0143106 0000012 00000225135 12477417235 0016631 0 ustar 00alanc staff 0000266 0200006
erlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
e;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoflibX11-1.6.3/specs/XKB/ch07.xml 0000644 0143106 0000012 00000036104 12477417235 0016106 0 ustar 00alanc staff 0000266 0200006
Virtual Modifiers
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
Num_Lock
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
Mod1
through
Mod5)
to keysyms such as
Num_Lock
and
Mode_switch.
Using the core protocol only, a client application must retrieve and search
the modifier map to determine the keycodes bound to each modifier, and then
retrieve and search the keyboard mapping to determine the keysyms bound to the
keycodes. It must repeat this process for all modifiers whenever any part of
the modifier mapping is changed.
Xkb alleviates these problems by defining virtual modifiers. In addition to the
eight core modifiers, referred to as the
real modifiers,
real modifiersmodifiersreal
Xkb provides a set of sixteen named
virtual modifiers.
virtual modifiersmodifiersvirtual
Each virtual modifier can be bound to any set of the real modifiers
(
Shift,
Lock,
Control,
and
Mod1
–
Mod5).
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,
Num_Lock
might be bound to
Mod2
for one vendor and to
Mod4
for another. This makes it cumbersome to automatically remap the keyboard to a
desired configuration without some kind of prior knowledge about the keyboard
layout and bindings. With XKB, applications can use virtual modifiers to
specify the desired behavior, without regard for the actual physical bindings
in effect.
Virtual Modifier Names and Masks
Virtual modifiers are named by converting their string name to an X
Atom
and storing the Atom in the
names.vmods
array in an
XkbDescRec
structure (see section 6.1). The position of a name Atom in the
names.vmods
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
names.vmods
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.
To set the name of a virtual modifier, use
XkbSetNames,
using
XkbVirtualModNamesMask
in
which
and the name in the
xkb
argument; to retrieve indicator names, use
XkbGetNames.
These functions are discussed in .
Modifier DefinitionsXkbModsRec
An Xkb
modifier definitionmodifier definition
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
section 8.2.2,
section 10.8, and
section 15.2.)
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 */
} XkbModsRec, *XkbModsPtr;
An Xkb modifier definition consists of a set of bit masks corresponding to the
eight real modifiers
(real_mods);
a similar set of bitmasks corresponding to the 16 named virtual modifiers
(vmods);
and an effective mask
(mask).
The effective mask represents the set of all real modifiers that can
logically be set either by setting any of the real modifiers or by setting any
of the virtual modifiers in the definition.
mask
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
(real_mods)
plus
any real modifiers that are bound to the virtual modifiers specified in the
definition
(vmods).
The binding of the virtual modifiers to real modifiers is exterior to the
modifier definition. Xkb automatically recomputes the mask field of modifier
definitions as necessary. Whenever you access a modifier definition that has
been retrieved using an Xkb library function, the mask field will be correct
for the keyboard mapping of interest.
Binding Virtual Modifiers to Real Modifiers
The binding of virtual modifiers to real modifiers is defined by the
server.vmods
array in an
XkbDescRec
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.
Virtual Modifier Key Mapping
Xkb maintains a
virtual modifier mapping,
virtual modifier mappingmodifiersvirtual mapping
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
server.vmodmap
array indicates which virtual modifiers are bound to each key; each entry is a
bitmask for the virtual modifier bits. The
server.vmodmap
array is indexed by keycode.
The
vmodmap
and
vmods
members of the server map are the master virtual modifier definitions. Xkb
automatically propagates any changes to these fields to all other fields that
use virtual modifier mappings (see section 16.4).
For example, if
Mod3
is bound to the
Num_Lock
key by the core protocol modifier mapping, and the
NumLock
virtual modifier is bound to they
Num_Lock
key by the virtual modifier mapping,
Mod3
is added to the set of modifiers associated with
NumLock.
The virtual modifier mapping is normally updated whenever actions are
automatically applied to symbols (see section 16.4 for details), and few
applications should need to change the virtual modifier mapping explicitly.
Use
XkbGetMap
(see section 14.2) to get the virtual modifiers from the server or use
XkbGetVirtualMods
(see section 16.4.1) to update a local copy of the virtual modifiers bindings
from the server. To set the binding of a virtual modifier to a real modifier,
use
XkbSetMap
(see
section 14.3).
To determine the mapping of virtual modifiers to core X protocol modifiers, use
XkbVirtualModsToReal.
XkbVirtualModsToRealBool XkbVirtualModsToRealXkbDescPtr xkbunsigned int virtual_maskunsigned int *mask_rtrnxkb
keyboard description for input device
virtual_mask
virtual modifier mask to translate
mask_rtrn
backfilled with real modifiers
If the keyboard description defined by
xkb
includes bindings for virtual modifiers,
XkbVirtualModsToReal
uses those bindings to determine the set of real modifiers that correspond to
the set of virtual modifiers specified in
virtual_mask.
The
virtual_mask
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
mask_rtrn
is non-
NULL,
XkbVirtualModsToReal
backfills it with the resulting real modifier mask. If the keyboard
description in
xkb
does not include virtual modifier bindings,
XkbVirtualModsToReal
returns
False;
otherwise, it returns
True.
It is possible for a local (client-side) keyboard description (the
xkb
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. Inactive Modifier Sets
An unbound virtual modifier is one that is not bound to any real modifier
(
server->vmods
[virtual_modifier_index] is zero).
Some Xkb operations ignore modifier definitions in which the virtual modifiers
are unbound. Consider this example:
if (state matches {Shift}) Do OneThing;
if (state matches {Shift+NumLock}) Do Another;
If the
NumLock
virtual modifier is not bound to any real modifiers, the effective masks for
these two cases are identical (that is, contain only
Shift).
When it is essential to distinguish between
OneThing
and Another, Xkb considers only those modifier definitions for which all
virtual modifiers are bound.
Conventionsmodifiersnames
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:
NumLockScrollLockAltMetaAltGrLevelThreeExample
If the second (0-relative) entry in
names.vmods
contains the Atom for "NumLock", then 0x4 (1<<2) is the virtual modifier
bit for the
NumLock
virtual modifier. If
server.vmods
[2] contains
Mod3Mask,
then the
NumLock
virtual modifier is bound to the
Mod3
real modifier.
A virtual modifier definition for this example would have:
real_mods = 0
vmods = 0x4 (NumLock named virtual modifier)
mask = 0x20 (Mod3Mask)
Continuing the example, if the keyboard has a
Num_Lock
keysym bound to the key with keycode 14, and the
NumLock
virtual modifier is bound to this key,
server.vmodmap[14]
contains 0x4.
Finally, if the keyboard also used the real
Mod1
modifier for numeric lock operations, the modifier definition below would
represent the situation where either the key bound to
Mod1
or the
NumLock
virtual modifier could be used for this purpose:
real_mods = 0x8 (Mod1Mask)
vmods = 0x4 (NumLock named virtual modifier)
mask = 0x28 (Mod1Mask | Mod3Mask)
unsigned char real_mods; /* real modifier bits */
unsigned short vmods; /* virtual modifier bits */
} XkbModsRec, *XkbModsPtr;
An Xkb modifier definition consists of a set of bit masks corresponding to the
eight real modifiers
(real_mods);
a similar set of bitmasks corresponding to the 16 named virtual modifiers
(vmods
Bellsbell
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
audibleaudible bellbellaudible
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.
You can ask to receive
XkbBellNotify
events (see section 9.4) when any client rings any one of the following:
The default bell
Any bell on an input device that can be specified by a
bell_class
and
bell_id
pair
Any bell specified only by an arbitrary name. (This is, from the server’s
point of view, merely a name, and not connected with any physical
sound-generating device. Some client application must generate the sound, or
visual feedback, if any, that is associated with the name.)
You can also ask to receive
XkbBellNotify
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.
You can disable audible bells on a global basis (to set the
AudibleBell
control, see ). For example, a client that replaces the keyboard
bell with some other audible cue might want to turn off the
AudibleBell
control to prevent the server from also generating a sound and avoid
cacophony. If you disable audible bells and request to receive
XkbBellNotify
events, you can generate feedback different from the default bell.
You can, however, override the
AudibleBell
control by calling one of the functions that force the ringing of a bell in
spite of the setting of the
AudibleBell
control —
XkbForceDeviceBell
or
XkbForceBell
(see section 9.3.3). In this case the server does not generate a bell event.
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
AccessXFeedback
control is used to configure the specific types of operations that generate
feedback. See section 10.6.3 for a discussion on
AccessXFeedback
control.
This chapter describes bell names, the functions used to generate named bells,
and the events the server generates for bells.
Bell Names
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
XkbBellNotify
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
XkbBellNotify
events.
Predefined BellsActionNamed BellIndicator turned onAX_IndicatorOnIndicator turned offAX_IndicatorOffMore than one indicator changed stateAX_IndicatorChangeControl turned onAX_FeatureOnControl turned offAX_FeatureOffMore than one control changed stateAX_FeatureChangeSlowKeys and BounceKeys about to be turned on or offAX_SlowKeysWarningSlowKeys key pressedAX_SlowKeyPressSlowKeys key acceptedAX_SlowKeyAcceptSlowKeys key rejectedAX_SlowKeyRejectAccepted SlowKeys key releasedAX_SlowKeyReleaseBounceKeys key rejectedAX_BounceKeyRejectStickyKeys key latchedAX_StickyLatchStickyKeys key lockedAX_StickyLockStickyKeys key unlockedAX_StickyUnlock
Audible Bells
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
XkbBellNotify
events (see section 9.4). When it receives a
XkbBellNotify
event, the audio client could then send a request to an audio server to play a
sound.
You can control the audible bells feature by passing the
XkbAudibleBellMask
to
XkbChangeEnabledControls
(see section 10.1.1). If you set
XkbAudibleBellMask
on, the server rings the system bell when a bell event occurs. This is the
default. If you set
XkbAudibleBellMask
off and a bell event occurs, the server does not ring the system bell unless
you call
XkbForceDeviceBell
or
XkbForceBell
(see section 9.3.3).
Audible bells are also part of the per-client auto-reset controls. For more
information on auto-reset controls, see section 10.1.2.
Bell Functions
Use the functions described in this section to ring bells and to generate bell
events.
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
bell_class
and
bell_id
parameters; set them as follows: Set
bell_class
to
BellFeedbackClass
or
KbdFeedbackClass.
A device can have more than one feedback of each type; set
bell_id
to the particular bell feedback of
bell_class
type.
Table 9.2 shows the conditions that cause
a bell to sound or an XkbBellNotifyEvent
to be generated when a bell function is called.
Bell Sounding and Bell Event GeneratingFunction calledAudibleBellServer sounds a bellServer sends an XkbBellNotifyEventXkbDeviceBellOnYesYesXkbDeviceBellOffNoYesXkbBellOnYesYesXkbBellOffNoYesXkbDeviceBellEventOn or OffNoYesXkbBellEventOn or OffNoYesXkbDeviceForceBellOn or OffYesNoXkbForceBellOn or OffYesNo
Generating Named Bells
To ring the bell on an X input extension device or the default keyboard, use
XkbDeviceBell.
XkbDeviceBellBool XkbDeviceBellDisplay *displayWindow windowunsigned int device_specunsigned int bell_classunsigned int bell_idint percentAtom namedisplay
connection to the X server
window
window for which the bell is generated, or None
device_spec
device ID, or XkbUseCoreKbdbell_class
X input extension bell class of the bell to be rung
bell_id
X input extension bell ID of the bell to be rung
percent
bell volume, from −100 to 100 inclusive
name
a name for the bell, or NULL
Set
percent
to be the volume relative to the base volume for the keyboard as described for
XBell.
Note that
bell_class
and
bell_id
indicate the bell to physically ring.
name
is simply an arbitrary moniker for the client application’s use.
To determine the current feedback settings of an extension input device, use
XGetFeedbackControl.
See the
X input extension documentation for more information on
XGetFeedbackControl
and related data structures.
If a compatible keyboard extension is not present in the X server,
XkbDeviceBell
immediately returns
False.
Otherwise,
XkbDeviceBell
rings the bell as specified for the display and keyboard device and returns
True.
If you have disabled the audible bell, the server does not ring the system
bell, although it does generate a
XkbBellNotify
event.
You can call
XkbDeviceBell
without first initializing the keyboard extension.
As a convenience function, Xkb provides a function to ring the bell on the
default keyboard:
XkbBell.
XkbBellBool XkbBellDisplay *displayWindow windowint percentAtom namedisplay
connection to the X server
window
event window, or None
percent
relative volume, which can range from −100 to 100 inclusive
name
a bell name, or NULL
If a compatible keyboard extension isn’t present in the X server,
XkbBell
calls
XBell
with the specified
display
and
percent,
and returns
False.
Otherwise,
XkbBell
calls
XkbDeviceBell
with the specified
display,
window,
percent,
and
name,
a
device_spec
of
XkbUseCoreKbd,
a
bell_class
of
XkbDfltXIClass,
and a
bell_id
of
XkbDfltXIId,
and returns
True.
If you have disabled the audible bell, the server does not ring the system
bell, although it does generate a
XkbBellNotify
event.
You can call
XkbBell
without first initializing the keyboard extension.
Generating Named Bell Events
Using Xkb, you can also generate a named bell event that does not ring any
bell. This allows you to do things such as generate events when your
application starts.
For example, if an audio client listens for these types of bells, it can
produce a whoosh sound when it receives a named bell event to indicate a
client just started. In this manner, applications can generate start-up
feedback and not worry about producing annoying beeps if an audio server is not
running.
To cause a bell event for an X input extension device or for the keyboard,
without ringing the corresponding bell, use
XkbDeviceBellEvent.
XkbDeviceBellEventBool XkbDeviceBellEventDisplay *displayWindow windowunsigned int device_specunsigned int bell_classunsigned int bell_idint percentAtom namedisplay
connection to the X server
window
event window, or None
device_spec
device ID, or XkbUseCoreKbdbell_class
input extension bell class for the event
bell_id
input extension bell ID for the event
percent
volume for the bell, which can range from −100 to 100 inclusive
name
a bell name, or NULL
If a compatible keyboard extension isn’t present in the X server,
XkbDeviceBellEvent
immediately returns
False.
Otherwise,
XkbDeviceBellEvent
causes an
XkbBellNotify
event to be sent to all interested clients and returns
True.
Set
percent
to be the volume relative to the base volume for the keyboard as described for
XBell.
In addition,
XkbDeviceBellEvent
may generate
Atom
protocol errors as well as
XkbBellNotify
events. You can call
XkbBell
without first initializing the keyboard extension.
As a convenience function, Xkb provides a function to cause a bell event for
the keyboard without ringing the bell:
XkbBellEvent.
XkbBellEventBool XkbBellEventDisplay *displayWindow windowint percentAtom namedisplay
connection to the X server
window
the event window, or None
percent
relative volume, which can range from −100 to 100 inclusive
name
a bell name, or NULL
If a compatible keyboard extension isn’t present in the X server,
XkbBellEvent
immediately returns
False.
Otherwise,
XkbBellEvent
calls
XkbDeviceBellEvent
with the specified
display,
window,
percent,
and
name,
a
device_spec
of
XkbUseCoreKbd,
a
bell_class
of
XkbDfltXIClass,
and a
bell_id
of
XkbDfltXIId,
and returns what
XkbDeviceBellEvent
returns.
XkbBellEvent
generates a XkbBellNotify
event.
You can call
XkbBellEvent
without first initializing the keyboard extension.
Forcing a Server-Generated Bell
To ring the bell on any keyboard, overriding user preference settings for
audible bells, use XkbForceDeviceBell.
XkbForceDeviceBellBool XkbForceDeviceBellDisplay *displayWindow windowunsigned int device_specunsigned int bell_classunsigned int bell_idint percentdisplay
connection to the X server
window
event window, or None
device_spec
device ID, or XkbUseCoreKbdbell_class
input extension class of the bell to be rung
bell_id
input extension ID of the bell to be rung
percent
relative volume, which can range from −100 to 100 inclusive
If a compatible keyboard extension isn’t present in the X server,
XkbForceDeviceBell
immediately returns
False.
Otherwise,
XkbForceDeviceBell
rings the bell as specified for the display and keyboard device and returns
True.
Set
percent
to be the volume relative to the base volume for the keyboard as described for
XBell.
There is no
name
parameter because
XkbForceDeviceBell
does not cause an
XkbBellNotify
event.
You can call
XkbBell
without first initializing the keyboard extension.
To ring the bell on the default keyboard, overriding user preference settings
for audible bells, use
XkbForceBell.
XkbForceBellBool XkbForceBellDisplay *displayint percentdisplay
connection to the X server
percent
volume for the bell, which can range from −100 to 100 inclusive
If a compatible keyboard extension isn’t present in the X server,
XkbForceBell
calls
XBell
with the specified
display
and
percent
and returns
False.
Otherwise,
XkbForceBell
calls
XkbForceDeviceBell
with the specified
display
and
percent,
device_spec
=
XkbUseCoreKbd,
bell_class
=
XkbDfltXIClass,
bell_id
=
XkbDfltXIId,
window
= None, and
name
=
NULL,
and returns what
XkbForceDeviceBell
returns.
XkbForceBell
does not cause an
XkbBellNotify
event.
You can call
XkbBell
without first initializing the keyboard extension.
Detecting Bells
Xkb generates
XkbBellNotify
events for all bells except for those resulting from calls to
XkbForceDeviceBell
and
XkbForceBell.
To receive
XkbBellNotify
events under all possible conditions, pass
XkbBellNotifyMask
in both the
bits_to_change
and
values_for_bits
parameters to
XkbSelectEvents
(see section 4.3).
The
XkbBellNotify
event has no event details. It is either selected or it is not. However, you
can call
XkbSelectEventDetails
using
XkbBellNotify
as the
event_type
and specifying
XkbAllBellEventsMask
in
bits_to_change
and
values_for_bits.
This has the same effect as a call to
XkbSelectEvents.
The structure for the
XkbBellNotify
event type contains:
typedef struct _XkbBellNotify {
int type; /* Xkb extension base event code */
unsigned long serial; /* X server serial number for event */
Bool send_event; /* True ⇒ synthetically generated */
Display * display; /* server connection where event generated */
Time time; /* server time when event generated */
int xkb_type; /* XkbBellNotify */
unsigned int device; /* Xkb device ID, will not be XkbUseCoreKbd */
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; /* False → the server did not produce a beep */
} XkbBellNotifyEvent;
If your application needs to generate visual bell feedback on the screen when
it receives a bell event, use the window ID in the
XkbBellNotifyEvent,
if present.
ara>
As a convenience function, Xkb providelibX11-1.6.3/specs/XKB/ch18.xml 0000644 0143106 0000012 00000111312 12477417235 0016103 0 ustar 00alanc staff 0000266 0200006
Symbolic Names
The core protocol does not provide any information to clients other than that
actually used to interpret events. This makes it difficult to write an
application that presents the keyboard to a user in an easy-to-understand way.
Such applications have to examine the vendor string and keycodes to determine
the type of keyboard connected to the server and then examine keysyms and
modifier mappings to determine the effects of most modifiers (the
Shift,
Lock
and
Control
modifiers are defined by the core protocol but no semantics are implied for
any other modifiers).
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
names
component of the keyboard description.
The XkbNamesRec StructureXkbKeyNameRecXkbKeyAliasRecXkbNamesRec
The names component of the keyboard description is defined as follows:
#define XkbKeyNameLength 4
#define XkbKeyNumVirtualMods 16
#define XkbKeyNumIndicators 32
#define XkbKeyNumKbdGroups 4
#define XkbMaxRadioGroups 32
typedef struct {
char name[XkbKeyNameLength]; /* symbolic key names */
} XkbKeyNameRec, *XkbKeyNamePtr;
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 */
} XkbKeyAliasRec, *XkbKeyAliasPtr;
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 keys array */
unsigned char num_key_aliases; /* number of keys in the
key_aliases array */
unsigned short num_rg; /* number of radio groups */
} XkbNamesRec, *XkbNamesPtr;
The
keycodes
name identifies the range and meaning of the keycodes returned by the keyboard
in question. The
geometry
name, on the other hand, identifies the physical location, size and shape of
the various keys on the keyboard. As an example to distinguish between these
two names, consider function keys on PC-compatible keyboards. Function keys are
sometimes above the main keyboard and sometimes to the left of the main
keyboard, but the same keycode is used for the key that is logically F1
regardless of physical position. Thus, all PC-compatible keyboards share a
similar keycodes name but may have different geometry names.
The keycodes name is intended to be a very general description of
the keycodes returned by a keyboard; a single keycodes name might cover
keyboards with differing numbers of keys provided all keys have the same
semantics when present. For example, 101 and 102 key PC keyboards might use the
same name. In these cases, applications can use the keyboard
geometry
name to determine which subset of the named keycodes is in use.
The
symbols
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
phys_symbols
name, on the other hand, identifies the symbols actually engraved on the
keyboard. Given this, the
symbols
name and
phys_symbols
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
phys_symbols
name of "en_US" and a
symbols
name of "de_CH."
The
types
name provides some information about the set of key types (see section 15.2)
that can be associated with the keyboard. In addition, each key type can have a
name, and each shift level of a type can have a name. Although these names are
stored in the map description with each of the types, they are accessed using
the same methods as the other symbolic names.
The
compat
name provides some information about the rules used to bind actions to keys
that are changed using core protocol requests.
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
vmods,
indicators,
and
groups
fixed-length arrays.
Each key has a four-byte symbolic name. All of the symbolic key names are held
in the
keys
array, and
num_keys
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
F1
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.
Key aliases allow the keyboard layout designer to assign multiple key names to
a single key. This allows the keyboard layout designer to refer to keys using
either their position or their function.
For example, a keyboard layout
designer may wish to refer to the left arrow key on a PC keyboard using the
ISO9995-5 positional specification of A31 or using the functional specification
of LEFT. The
key_aliases
field holds a variable-length array of real and alias key name pairs, and the
total number of entries in the
key_aliases
array is held in
num_key_aliases.
For each real and alias key name pair, the
real
field refers to the a name in the keys array, and the
alias
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
key_aliases
array.
Key aliases defined in the geometry component of a keyboard mapping
(see ) override those defined in the keycodes component of the server
database, which are stored in the
XkbNamesRec
(xkb->names).
Therefore, consider the key aliases defined by the geometry before
considering key aliases supplied by the
XkbNamesRec.
A radio group is a set of keys whose behavior simulates a set of radio buttons.
Once a key in a radio group is pressed, it stays logically depressed until
another key in the group is pressed, at which point the previously depressed
key is logically released. Consequently, at most one key in a radio group can
be logically depressed at one time.
Each radio group in the keyboard description can have a name. These names are
held in the variable-length array
radio_groups,
and
num_rg
tells how many elements are in the
radio_groups
array.
Symbolic Names Masks
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.
Getting Symbolic Names From the Server
To obtain symbolic names from the server, use
XkbGetNames.
XkbGetNamesStatus XkbGetNamesDisplay *dpyunsigned int whichXkbDescPtr xkbdpy
connection to the X server
which
mask of names or map components to be updated
xkb
keyboard description to be updated
XkbGetNames
retrieves symbolic names for the components of the keyboard extension from the
X server. The
which
parameter specifies the name components to be updated in the
xkb
parameter, and is the bitwise inclusive OR of the valid names mask bits
defined in Table 18.1.
If the
names
field of the keyboard description
xkb
is
NULL,
XkbGetNames
allocates and initializes the
names
component of the keyboard description before obtaining the values specified by
which.
If the
names
field of
xkb
is not
NULL,
XkbGetNames
obtains the values specified by
which
and copies them into the keyboard description
xkb.
If the
map
component of the
xkb
parameter is
NULL,
XkbGetNames
does not retrieve type or shift level names, even if
XkbKeyTypeNamesMask
or
XkbKTLevelNamesMask
are set in
which.
XkbGetNames
can return
Success,
or
BadAlloc,
BadLength,
BadMatch,
and
BadImplementation
errors.
To free symbolic names, use
XkbFreeNames
(see section 18.6)
Changing Symbolic Names on the Server
To change the symbolic names in the server, first modify a local copy of the
keyboard description and then use either
XkbSetNames,
or, to save network traffic, use a
XkbNameChangesRec
structure and call
XkbChangeNames
to download the changes to the server.
XkbSetNames
and
XkbChangeNames
can generate
BadAlloc,
BadAtom,
BadLength,
BadMatch,
and
BadImplementation
errors.
XkbSetNamesBool XkbSetNamesDisplay *dpyunsigned int whichunsigned int first_typeunsigned int num_typesXkbDescPtr xkbdpy
connection to the X server
which
mask of names or map components to be changed
first_type
first type whose name is to be changed
num_types
number of types for which names are to be changed
xkb
keyboard description from which names are to be taken
Use
XkbSetNames
to change many names at the same time. For each bit set in
which,
XkbSetNames
takes the corresponding value (or values in the case of arrays) from the
keyboard description
xkb
and sends it to the server.
The
first_type
and
num_types
arguments are used only if
XkbKeyTypeNamesMask
or
XkbKTLevelNamesMask
is set in
which
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,
XkbSetNames
returns
False
and does not update any of the names specified in
which.
The specified types are illegal if
xkb
does not include a map component or if
first_type
and
num_types
specify types that are not defined in the keyboard description.
The XkbNameChangesRec StructureXkbNameChangesRec
The
XkbNameChangesRec
allows applications to identify small modifications to the symbolic names and
effectively reduces the amount of traffic sent to the server:
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 */
} XkbNameChangesRec, *XkbNameChangesPtr;
The
changed
field specifies the name components that have changed and is the bitwise
inclusive OR of the valid names mask bits defined in
Table 18.1. The rest of
the fields in the structure specify the ranges that have changed for the
various kinds of symbolic names, as shown in
Table 18.2.
XkbChangeNames
provides a more flexible method for changing symbolic names than
XkbSetNames
and requires the use of an
XkbNameChangesRec
structure.
XkbChangeNamesBool XkbChangeNamesDisplay *dpyXkbDescPtr xkbXkbNameChangesPtr changesdpy
connection to the X server
xkb
keyboard description from which names are to be taken
changes
names map components to be updated on the server
XkbChangeNames
copies any names specified by
changes
from the keyboard description,
xkb,
to the X server specified by
dpy.
XkbChangeNames
aborts and returns
False
if any illegal type names or type shift level names are specified by
changes.
Tracking Name ChangeseventsXkbNamesNotifyXkbNamesNotifyEvent
Whenever a symbolic name changes in the server’s keyboard description, the
server sends a
XkbNamesNotify
event to all interested clients. To receive name notify events, use
XkbSelectEvents
(see section 4.3) with
XkbNamesNotifyMask
in both the
bits_to_change
and
values_for_bits
parameters.
To receive events for only specific names, use
XkbSelectEventDetails.
Set the
event_type
parameter to
XkbNamesNotify,
and set both the
bits_to_change
and
values_for_bits
detail parameter to a mask composed of a bitwise OR of masks in
Table 18.1.
The structure for the
XkbNamesNotify
event is defined as follows:
typedef struct {
int type; /* Xkb extension base event code */
unsigned long serial; /* X server serial number for event */
Bool send_event; /* True ⇒ synthetically generated */
Display * display; /* server connection where event generated */
Time time; /* server time when event generated */
int xkb_type; /* XkbNamesNotify */
int device; /* Xkb device ID, will not be
XkbUseCoreKbd */
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 */
} XkbNamesNotifyEvent;
The
changed
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
XkbNameChangesRec , as previously defined.
When your application receives a
XkbNamesNotify
event, you can note the changed names in a changes structure using
XkbNoteNameChanges.
XkbNoteNameChangesvoid XkbNoteNameChangesXkbNameChangesPtr oldXkbNamesNotifyEvent *newunsigned int wantedoldXkbNameChangesRec structure to be updated
new
event from which changes are to be copied
wanted
types of names for which changes are to be noted
The
wanted
parameter is the bitwise inclusive OR of the valid names mask bits shown in
Table 18.1.
XkbNoteNameChanges
copies any changes that are reported in
new
and specified in
wanted
into the changes record specified by
old.
To update the local copy of the keyboard description with the actual values,
pass to
XkbGetNameChanges
the results of one or more calls to
XkbNoteNameChanges.
XkbGetNameChangesStatus XkbGetNameChangesDisplay *dpyXkbDescPtr xkbXkbNameChangesPtr changesdpy
connection to the X server
xkb
keyboard description to which names are copied
changes
names components to be obtained from the server
XkbGetNameChanges
examines the
changes
parameter, retrieves the necessary information from the server, and places the
results into the
xkb
keyboard description.
XkbGetNameChanges
can generate
BadAlloc,
BadImplementation,
and
BadMatch
errors.
Allocating and Freeing Symbolic Names
Most applications do not need to directly allocate symbolic names structures.
Do not allocate a names structure directly using
malloc
or
Xmalloc
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
XkbAllocNames.
XkbAllocNamesStatus XkbAllocNamesXkbDescPtr xkbunsigned int whichint num_rgint num_key_aliasesxkb
keyboard description for which names are to be allocated
which
mask of names to be allocated
num_rg
total number of radio group names needed
num_key_aliases
total number of key aliases needed
XkbAllocNames
can return
BadAlloc,
BadMatch,
and
BadValue
errors.
The
which
parameter is the bitwise inclusive OR of the valid names mask bits defined in
Table 18.1.
Do not free symbolic names structures directly using
free
or
XFree.
Use
XkbFreeNames
instead.
XkbFreeNamesvoid XkbFreeNamesXkbDescPtr xkbunsigned int whichBool free_mapxkb
keyboard description for which names are to be freed
which
mask of names components to be freed
free_mapTrue
⇒ XkbNamesRec structure itself should be freed
The
which
parameter is the bitwise inclusive OR of the valid names mask bits defined in
Table 18.1.
and set both the
bits_to_change
and
values_for_bits
detail parameter to a mask composed of a bitwise OR of masks in
Table 18.1.
The structure for the
XkbNamesNotify
event is defined as follows:
e">X Library Controls
The Xkb extension is composed of two parts: a server extension, and a
client-side X library extension. 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.
library controlscontrolslibrary
All of the Library Controls are boolean flags that may be enabled and disabled.
The controls can be divided into several categories:
Controls affecting general string lookups
Controls affecting compose processing
Controls affecting event delivery
There are two types of string lookups performed by
XLookupString.
XLookupString
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.
An Xkb implementation is required to support the programming interface for all
of the controls. However, an implementation may choose not to support the
semantics associated with the controls that deal with compose processing. In
this case, a program that accesses these controls should still function
normally; however, the feedback that would normally occur with the controls
enabled may be missing.
Controls Affecting Keycode-to-String Translation
The first type of string lookups, which are here called
simple string lookups,
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:
ForceLatin1LookupConsumeLookupModsLevelOneUsesShiftAndLockForceLatin1Lookup
If the
ForceLatin1Lookup
control is enabled,
XLookupString
only returns strings using the Latin1 character set. If
ForceLatin1Lookup
is not enabled,
XLookupString
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.
ConsumeLookupMods
Simple string lookups in
XLookupString
involve two different translation phases. The first phase translates raw
device keycodes to individual keysyms. The second phase attempts to map the
resulting keysym into a string of one or more characters. In the first phase,
some of the modifiers are normally used to determine the appropriate shift
level for a key.
The
ConsumeLookupMods
control determines whether or not
XLookupStringconsumes
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
XLookupString
is using and appears to be unset for the remainder of the processing.
If the
ConsumeLookupMods
control is enabled,
XLookupString
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
ConsumeLookupMods
control is enabled. If a user presses the
Shift
key and the
A
key while the
Num_Lock
key is locked,
XLookupString
uses the
Shift
modifier when mapping the keycode for the ‘a’ key to the keysym for
‘A’; subsequently, it only uses the
NumLock
modifier when determining the string associated with the keysym ‘A’.
If the
ConsumeLookupMods
control is not enabled,
XLookupString
uses all of the event modifiers to determine the string associated with a
keysym. This behavior mirrors the behavior of
XLookupString
in the core implementation.
The
ConsumeLookupMods
control is unset by default. For more information on modifier consumption,
refer to .
AlwaysConsumeShiftAndLock
The
AlwaysConsumeShiftAndLock
control, if enabled, forces
XLookupString
to consume the
Shift
and
Lock
modifiers when processing all keys, even if the definition for the key type
does not specify these modifiers. The
AlwaysConsumeShiftAndLock
control is unset by default. See section 15.2 for a discussion of key types.
Controls Affecting Compose Processing
The second type of string lookup performed by
XLookupString
involves translating a series of keysyms into a string. Because these lookups
can involve more than one key event, they require
XLookupString
to retain some state information between successive calls. The process of
mapping a series of keysyms to a string is known as
compose processing.
compose processing
The controls affecting compose processing are:
ConsumeKeysOnComposeFailComposeLEDBeepOnComposeFail
Because different vendors have historically used different algorithms to
implement compose processing, and these algorithms may be incompatible with the
semantics required by the Xkb compose processing controls, implementation of
the compose processing controls is optional in an Xkb implementation.
ConsumeKeysOnComposeFail
Some compose processing algorithms signal the start of a compose sequence by a
key event meaning start compose.
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.
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
ConsumeKeysOnComposeFail
control allows a client to specify what happens with the key events
XLookupString
has been considering when it reaches a dead end in a compose sequence.
If the
ConsumeKeysOnComposeFail
control is set, all keys associated with a failed compose sequence should be
consumed (discarded). If the
ConsumeKeysOnComposeFail
control is not set, the key events associated with a failed compose sequence
should be processed as a normal sequence of key events.
The
ConsumeKeysOnComposeFail
control is disabled by default.
ComposeLED
The
ComposeLED
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
ComposeLED
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
ComposeLED
control is disabled by default.
While the Xkb extension does not specify the type of type of indicator to be
used when the
ComposeLED
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 “Compose”.
Note that some implementations may use an unnamed, custom hardware LED for
this purpose.
BeepOnComposeFail
The
BeepOnComposeFail
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
BeepOnComposeFail
control is enabled, it specifies that a bell should be activated when a
compose sequence fails. The
BeepOnComposeFail
control is disabled by default. If implemented, the bell should be activated
using
XkbBell
or
XkbDeviceBell.
While the Xkb extension does not specify the type of bell to be used when the
BeepOnComposeFail
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 “ComposeFail”.
Controls Effecting Event DeliveryIgnoreNewKeyboardseventsNewKeyboardNotifyeventsMappingNotify
When Xkb is initialized, it implicitly forces requests for
NewKeyboardNotify
events. These events may be used by the Xkb library extension internally; they
are normally translated into core protocol
MappingNotify
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
NewKeyboardNotify
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.
The
IgnoreNewKeyboards
control, if enabled, prevents Xkb from mapping
NewKeyboardNotify
events to core
MappingNotify
events and passing them to the client. The control is initially disabled.
Manipulating the Library Controls
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.
Library Control MasksLibrary Control MaskValueXkbLC_ForceLatin1Lookup(1 << 0)XkbLC_ConsumeLookupMods(1 << 1)XkbLC_AlwaysConsumeShiftAndLock(1 << 2)XkbLC_IgnoreNewKeyboards(1 << 3)XkbLC_ConsumeKeysOnComposeFail(1 << 29)XkbLC_ComposeLED(1 << 30)XkbLC_BeepOnComposeFail(1 << 31)XkbLC_AllControls(0xc0000007)
Determining Which Library Controls are Implemented
To determine which Library Controls are actually
implemented, use XkbXlibControlsImplemented.
XkbXlibControlsImplementedunsigned int XkbXlibControlsImplementedDisplay *displaydisplay
connection to X server
XkbXlibControlsImplemented
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.
Determining the State of the Library Controls
To determine the current state of the Library Controls, use
XkbGetXlibControls.
XkbGetXlibControlsunsigned int XkbGetXlibControlsDisplay *displaydisplay
connection to X server
XkbGetXlibControls
returns the current state of the Library Controls as a bit mask that is an
inclusive OR of the control masks from
Table 11.1 for the controls that are
enabled. For the optional compose processing controls, the fact that a control
is enabled does not imply that it is actually implemented.
Changing the State of the Library Controls
To change the state of the Library Controls, use
XkbSetXlibControls.
XkbSetXlibControlsBool XkbSetXlibControlsDisplay *displayunsigned long bits_to_changeunsigned long values_for_bitsdisplay
connection to X server
bits_to_change
selects controls to be modified
values_for_bits
turns selected controls on (1) or off (0)
XkbSetXlibControls
modifies the state of the controls selected by
bits_to_change;
only the controls selected by
bits_to_change
are modified. If the bit corresponding to a control is on in
bits_to_change
and also on in values_for_bits, the control is enabled. If the bit
corresponding to a control is on in
bits_to_change
but off in
values_for_bits,
the control is disabled.
bits_to_change
should be an inclusive OR of bits from
Table 11.1.
unction>
has been considering when it reaches a dead end in a compose sequence.
If the
ConsumeKeysOnComposeFail
control is set, all keys associated with a failed compose sequence should libX11-1.6.3/specs/XKB/ch16.xml 0000644 0143106 0000012 00000417005 12477417235 0016111 0 ustar 00alanc staff 0000266 0200006
Xkb Server Keyboard Mappingserver mapmapserver
The
server
field of the complete Xkb keyboard description (see section 6.1) is a pointer
to the Xkb server map.
Figure 16.1 shows the relationships between elements in the server map:
Server Map RelationshipsXkbServerMapRec
The Xkb server map contains the information the server needs to interpret key
events and is of type
XkbServerMapRec:
#define XkbNumVirtualMods 16
typedef struct { /* Server Map */
unsigned short num_acts; /* # of occupied entries in acts */
unsigned short size_acts; /* # of entries in acts */
XkbAction * acts; /* linear 2d tables of key actions,
1 per keycode */
XkbBehavior * behaviors; /* key behaviors, 1 per keycode */
unsigned short * key_acts; /* index into acts, 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 */
} XkbServerMapRec, *XkbServerMapPtr;
The
num_acts,
size_acts,
acts,
and
key_acts
fields specify the key actions, defined in section 16.1. The
behaviors
field describes the behavior for each key and is defined in section 16.2. The
explicit
field describes the explicit components for a key and is defined in
section 16.3. The
vmods
and the
vmodmap
fields describe the virtual modifiers and the per-key virtual modifier mapping
and are defined in section 16.4.
Key Actions
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
Shift
key is to set the
Shift
modifier. There is zero or one key action associated with each keysym bound to
each key.
Just as the entire list of key symbols for the keyboard mapping is held in the
syms
field of the client map, the entire list of key actions for the keyboard
mapping is held in the
acts
array of the server map. The total size of
acts
is specified by
size_acts,
and the number of entries is specified by
num_acts.
The
key_acts
array, indexed by keycode, describes the actions associated with a key. The
key_acts
array has
min_key_code
unused entries at the start to allow direct indexing using a keycode. If a
key_acts
entry is
zero,
it means the key does not have any actions associated with it. If an entry is
not
zero,
the entry represents an index into the
acts
field of the server map, much as the
offset
field of a
KeySymMapRec
structure is an index into the
syms
field of the client map.
The reason the
acts
field is a linear list of
XkbActions
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
KeySyms
would potentially be very large and sparse. Instead, Xkb provides a small
two-dimensional array of
XkbActions
for each key. To store all of these individual arrays, Xkb concatenates each
array together in the
acts
field of the server map.
The key action structures consist only of fields of type char or unsigned char.
This is done to optimize data transfer when the server sends bytes over the
wire. If the fields are anything but bytes, the server has to sift through all
of the actions and swap any nonbyte fields. Because they consist of nothing but
bytes, it can just copy them out.
Xkb provides the following macros, to simplify accessing information pertaining
to key actions:
XkbKeyHasActionsBool XkbKeyHasActionsXkbDescPtr xkbKeyCode keycodexkb
Xkb description of interest
keycode
keycode of interest
XkbKeyHasActions
returns
True
if the key corresponding to
keycode
has any actions associated with it; otherwise, it returns
False.
XkbKeyNumActionsint XkbKeyNumActionsXkbDescPtr xkbKeyCode keycodexkb
Xkb description of interest
keycode
keycode of interest
XkbKeyNumActions
computes the number of actions associated with the key corresponding to
keycode.
This should be the same value as the result of
XkbKeyNumSyms
(see section 15.3.3).
XkbKeyActionsPtrXkbKeyActionPtr XkbKeyActionsPtrXkbDescPtr xkbKeyCode keycodexkb
Xkb description of interest
keycode
keycode of interest
XkbKeyActionsPtr
returns a pointer to the two-dimensional array of key actions associated with
the key corresponding to
keycode.
Use
XkbKeyActionsPtr
only if the key actually has some actions associated with it, that is,
XkbKeyNumActions
(xkb, keycode) returns something greater than zero.
XkbKeyActionXkbAction XkbKeyActionXkbDescPtr xkbKeyCode keycodeint idxxkb
Xkb description of interest
keycode
keycode of interest
idx
index for group and shift level
XkbKeyAction
returns the key action indexed by
idx
in the two-dimensional array of key actions associated with the key
corresponding to
keycode.
idx
may be computed from the group and shift level of interest as follows:
idx = group_index * key_width + shift_level
XkbKeyActionEntryXkbAction XkbKeyActionEntryXkbDescPtr xkbKeyCode keycodeint shiftint grpxkb
Xkb description of interest
keycode
keycode of interest
shift
shift level within group
grp
group index for group of interest
XkbKeyActionEntry
returns the key action corresponding to group
grp
and shift level
shift
from the two-dimensional table of key actions associated with the key
corresponding to
keycode.
The XkbAction StructureXkbAction
The description for an action is held in an
XkbAction
structure, which is a union of all possible Xkb action types:
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;
} XkbAction;
The
type
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.
The XkbAnyAction StructureXkbAnyAction
The
XkbAnyAction
structure is a convenience structure that refers to any of the actions:
#define XkbAnyActionDataSize 7
typedef struct _XkbAnyAction {
unsigned char type; /* type of action; determines interpretation for data */
unsigned char data[XkbAnyActionDataSize];
} XkbAnyAction;
The
data
field represents a structure for an action, and its interpretation depends on
the
type
field. The valid values for the
type
field, and the data structures associated with them are shown in
Table 16.1:
Action TypesTypeStructure for DataXkbAction Union MemberSectionXkbSA_NoActionXkbSA_NoAction
means the server does not perform an action for the key; this action does not
have an associated data structure.
anyXkbSA_SetModsXkbSA_LatchModsXkbSA_LockModsXkbModActionmods16.1.3XkbSA_SetGroupXkbSA_LatchGroupXkbSA_LockGroupXkbGroupActiongroup16.1.4XkbSA_MovePtrXkbPtrActionptr16.1.5XkbSA_PtrBtnXkbSA_LockPtrBtnXkbPtrBtnActionbtn16.1.6XkbSA_SetPtrDfltXkbPtrDfltActiondflt16.1.7XkbSA_ISOLockXkbISOActioniso16.1.8XkbSA_SwitchScreenXkbSwitchScreenActionscreen16.1.9XkbSA_SetControlsXkbSA_LockControlsXkbCtrlsActionctrls16.1.10XkbSA_ActionMessageXkbMessageActionmsg16.1.11XkbSA_RedirectKeyXkbRedirectKeyActionredirect16.1.12XkbSA_DeviceBtnXkbSA_LockDeviceBtnXkbDeviceBtnActiondevbtn16.1.13XkbSA_DeviceValuatorXkbDeviceValuatorActiondevval16.1.14
Actions for Changing Modifiers’ StateXkbModAction
Actions associated with the
XkbModAction
structure change the state of the modifiers when keys are pressed and released
(see for a discussion of modifiers):
typedef struct _XkbModAction {
unsigned char type; /* XkbSA_{Set|Latch|Lock}Mods */
unsigned char flags; /* with type, controls the effect
on modifiers */
unsigned char mask; /* same as mask field of
a modifier description */
unsigned char real_mods; /* same as real_mods field of
a modifier description */
unsigned char vmods1; /* derived from vmods field of
a modifier description */
unsigned char vmods2; /* derived from vmods field of
a modifier description */
} XkbModAction;
In the following description, the term
action modifiersaction modifiersmodifiersaction
means the real modifier bits associated with this action. Depending on the
value of
flags
(see Table 16.3),
these are designated either in the
mask
field of the
XkbModAction
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
map->modmap
[
keycode
] field.
The
type
field can have any of the values shown in
Table 16.2.
Modifier Action TypesTypeEffectXkbSA_SetMods
A key press adds any action modifiers to the keyboard’s base modifiers.
A key release clears any action modifiers in the keyboard’s base modifiers,
provided no other key affecting the same modifiers is logically down.
If no other keys are physically depressed when this key is released, and
XkbSA_ClearLocks
is set in the
flags
field, the key release unlocks any action modifiers.
XkbSA_LatchMods
Key press and key release events have the same effect as for
XkbSA_SetMods;
if no keys are physically depressed when this key is released, key release
events have the following additional effects:
Modifiers unlocked due to
XkbSA_ClearLocks
have no further effect.
If
XkbSA_LatchToLock
is set in the
flags
field, a key release locks and then unlatches any remaining action modifiers
that are already latched.
A key release latches any action modifiers not used by the
XkbSA_ClearLocks
and
XkbSA_LatchToLock
flags.
XkbSA_LockMods
A key press sets the base state of any action modifiers. If
XkbSA_LockNoLock
is set in the
flags
field, a key press also sets the locked state of any action modifiers.
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
XkbSA_LockNoUnlock
is not set in the
flags
field, and any of the action modifiers were locked before the corresponding
key press occurred, a key release unlocks them.
The
flags
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 type.
Modifier Action FlagsFlagMeaningXkbSA_UseModMapMods
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
mask,
real_mods,
vmods1,
and
vmods2
fields.
XkbSA_ClearLocks
If set and no keys are physically depressed when this key transition
occurs, the server unlocks any action modifiers.
XkbSA_LatchToLock
If set, and the action type is
XkbSA_LatchMods,
the server locks the action modifiers if they are already latched.
XkbSA_LockNoLock
If set, and the action type is
XkbSA_LockMods,
the server only unlocks the action modifiers.
XkbSA_LockNoUnlock
If set, and the action is
XkbSA_LockMods,
the server only locks the action modifiers.
If
XkbSA_UseModMapMods
is not set in the
flags
field, the
mask,
real_mods,
vmods1,
and
vmods2
fields are used to determine the action modifiers. Otherwise they are ignored
and the modifiers bound to the key (client
map->modmap
[
keycode
]) are used instead.
The
mask,
real_mods,
vmods1,
and
vmods2
fields represent the components of an Xkb modifier description
(see section 7.2). While the
mask
and
real_mods
fields correspond directly to the
mask
and
real_mods
fields of an Xkb modifier description, the
vmods1
and
vmods2
fields are combined to correspond to the
vmods
field of an Xkb modifier description. Xkb provides the following macros, to
convert between the two formats:
XkbModActionVModsunsigned short XkbModActionVModsXkbAction actact
action from which to extract virtual mods
XkbModActionVMods
returns the
vmods1
and
vmods2
fields of
act
converted to the
vmods
format of an Xkb modifier description.
XkbSetModActionVModsvoid XkbSetModActionVModsXkbAction actunsigned short vmodsact
action in which to set vmods
vmods
virtual mods to set
XkbSetModActionVMods
sets the
vmods1
and
vmods2
fields of
act
using the
vmods
format of an Xkb modifier description.
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
XkbModAction
and
XkbISOAction.
Actions for Changing Group StateXkbGroupAction
Actions associated with the
XkbGroupAction
structure change the current group state when keys are pressed and released
(see for a description of groups and keyboard state):
typedef struct _XkbGroupAction {
unsigned char type; /* XkbSA_{Set|Latch|Lock}Group */
unsigned char flags; /* with type , controls the effect on groups */
char group_XXX; /* represents a group index or delta */
} XkbGroupAction;
The
type
field can have any of the following values:
Group Action TypesTypeEffectXkbSA_SetGroup
If the
XkbSA_GroupAbsolute
bit is set in the
flags
field, key press events change the base keyboard group to the group specified
by the
group_XXX
field. Otherwise, key press events change the base keyboard group by adding
the
group_XXX
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
groups_wrap
field of the controls structure (see section 10.7.1).
If a key with an
XkbSA_ISOLock
action (see section 16.1.8) is pressed while this key is down, the key release
of this key has no effect. Otherwise, the key release cancels the effects of
the key press.
If the
XkbSA_ClearLocks
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
Group1.
XkbSA_LatchGroup
Key press and key release events have the same effect as for
XkbSA_SetGroup;
if no keys are physically depressed when this key is released, key release
events have the following additional effects.
If the
XkbSA_LatchToLock
bit is set in the
flags
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
groups_wrap
field of the controls structure.
Otherwise, the key press adds the key press delta to the latched keyboard group.
XkbSA_LockGroup
If the
XkbSA_GroupAbsolute
is set in the
flags
field, key press events set the locked keyboard group to the group specified
by the
group_XXX
field. Otherwise, key press events add the group specified by the
group_XXX
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
groups_wrap
field of the controls structure.
A key release has no effect.
The
flags
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
type.
Group Action FlagsFlagMeaningXkbSA_ClearLocks
If set and no keys are physically depressed when this key transition occurs,
the server sets the locked keyboard group to
Group1
on a key release.
XkbSA_LatchToLock
If set, and the action type is
XkbSA_LatchGroup,
the server locks the action group if it is already latched.
XkbSA_GroupAbsolute
If set, the
group_XXX
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.
The
group_XXX
field represents a signed character. Xkb provides the following macros to
convert between a signed integer value and a signed character:
XkbSAGroupint XkbSAGroupXkbAction actact
action from which to extract group
XkbSAGroup
returns the
group_XXX
field of
act
converted to a signed int.
XkbSASetGroupvoid XkbSASetGroupXkbAction actint grpact
action from which to set group
grp
group index to set in group_XXXXkbSASetGroup
sets the
group_XXX
field of
act
from the group index
grp.
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
XkbGroupAction
and
XkbISOAction.
Actions for Moving the PointerXkbPtrAction
Actions associated with the
XkbPtrAction
structure move the pointer when keys are pressed and released:
typedef struct _XkbPtrAction {
unsigned char type; /* XkbSA_MovePtr */
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 */
} XkbPtrAction;
If the
MouseKeys
control is not enabled (see section 10.5.1),
KeyPress
and
KeyRelease
events are treated as though the action is
XkbSA_NoAction.
If the
MouseKeys
control is enabled, a server action of type
XkbSA_MovePtr
instructs the server to generate core pointer
MotionNotify
events rather than the usual
KeyPress
event, and the corresponding
KeyRelease
event disables any mouse keys timers that were created as a result of handling
the
XkbSA_MovePtr
action.
The
type
field of the
XkbPtrAction
structure is always
XkbSA_MovePtr.
The
flags
field is a bitwise inclusive OR of the masks shown in
Table 16.6.
Pointer Action TypesAction TypeMeaningXkbSA_NoAcceleration
If not set, and the
MouseKeysAccel
control is enabled (see section 10.5.2), the
KeyPress
initiates a mouse keys timer for this key; every time the timer expires, the
cursor moves.
XkbSA_MoveAbsoluteXIf 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.
XkbSA_MoveAbsoluteY
If set, the Y portion of the structure specifies the new
pointer Y coordinate. Otherwise, the Y portion is added
to the current pointer Y coordinate to determine the new pointer Y coordinate.
Each of the X and Y coordinates of the
XkbPtrAction
structure is composed of two signed 16-bit values, that is, the X coordinate
is composed of
high_XXX
and
low_XXX,
and similarly for the Y coordinate. Xkb provides the following macros, to
convert between a signed integer and two signed 16-bit values in
XkbPtrAction
structures:
XkbPtrActionXint XkbPtrActionXXkbPtrAction actact
action from which to extract X
XkbPtrActionX
returns the
high_XXX
and
low_XXX
fields of
act
converted to a signed int.
XkbPtrActionYint XkbPtrActionYXkbPtrAction actact
action from which to extract Y
XkbPtrActionY
returns the
high_YYY
and
low_YYY
fields of
act
converted to a signed int.
XkbSetPtrActionXvoid XkbSetPtrActionXXkbPtrAction actint xact
action in which to set X
x
new value to set
XkbSetPtrActionX
sets the
high_XXX
and
low_XXX
fields of
act
from the signed integer value
x.
XkbSetPtrActionYvoid XkbSetPtrActionYXkbPtrAction actint yact
action in which to set Y
y
new value to set
XkbSetPtrActionX
sets the
high_YYY
and
low_YYY
fields of
act
from the signed integer value
y.
Actions for Simulating Pointer Button Press and ReleaseXkbPtrBtnAction
Actions associated with the
XkbPtrBtnAction
structure simulate the press and release of pointer buttons when keys are
pressed and released:
typedef struct _XkbPtrBtnAction {
unsigned char type; /* XkbSA_PtrBtn, XkbSA_LockPtrBtn */
unsigned char flags; /* with type, controls the effect
on pointer buttons */
unsigned char count; /* controls number of ButtonPress and
ButtonRelease events */
unsigned char button; /* pointer button to simulate */
} XkbPtrBtnAction;
If the
MouseKeys
(see section 10.5.1) control is not enabled,
KeyPress
and
KeyRelease
events are treated as though the action is
XkbSA_NoAction.
The
type
field can have any one of the values shown in
Table 16.7.
Pointer Button Action TypesTypeEffectXkbSA_PtrBtn
If
XkbSA_UseDfltButton
is set in the
flags
field, the event is generated for the pointer button specified by the
mk_dflt_btn
attribute of the
MouseKeys
control (see section 10.5.1). Otherwise, the event is generated for the button
specified by the
button
field.
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
KeyPress
event. If
count
is
zero,
a key press generates a single
ButtonPress
event; if
count
is greater than
zero,
a key press generates
count
pairs of
ButtonPress
and
ButtonRelease
events.
If
count
is
zero,
a key release generates a core pointer
ButtonRelease
that matches the event generated by the corresponding
KeyPress;
if
count
is nonzero, a key release does not cause a
ButtonRelease
event. A key release never generates a key
KeyRelease
event.
XkbSA_LockPtrBtn
If the button specified by the
MouseKeys
default button
or
button
is not locked, a key press causes a
ButtonPress
event instead of a
KeyPress
event and locks the button. If the button is already locked or if
XkbSA_LockNoUnlock
is set in the
flags
field, a key press is ignored and has no effect.
If the corresponding key press was ignored, and if
XkbSA_LockNoLock
is not set in the
flags
field, a key release generates a
ButtonRelease
event instead of a
KeyRelease
event and unlocks the specified button. If the corresponding key press locked
a button, the key release is ignored and has no effect.
The
flags
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
type:
Pointer Button Action FlagsFlagMeaningXkbSA_UseDfltButton
If set, the action uses the pointer button specified by the
mk_dflt_btn
attribute of the
MouseKeys
control (see section 10.5.1). Otherwise, the action uses the pointer button
specified by the
button
field.
XkbSA_LockNoLock
If set, and the action type is
XkbSA_LockPtrBtn,
the server only unlocks the pointer button.
XkbSA_LockNoUnlock
If set, and the action type is
XkbSA_LockPtrBtn,
the server only locks the pointer button.
Actions for Changing the Pointer Button SimulatedXkbPtrDfltAction
Actions associated with the
XkbPtrDfltAction
structure change the
mk_dflt_btn
attribute of the
MouseKeys
control (see section 10.5.1):
typedef struct _XkbPtrDfltAction {
unsigned char type; /* XkbSA_SetPtrDflt */
unsigned char flags; /* controls the pointer button number */
unsigned char affect; /* XkbSA_AffectDfltBtn */
char valueXXX; /* new default button member */
} XkbPtrDfltAction;
If the
MouseKeys
control is not enabled,
KeyPress
and
KeyRelease
events are treated as though the action is
XkbSA_NoAction.
Otherwise, this action changes the
mk_dflt_btn
attribute of the
MouseKeys
control.
The
type
field of the
XkbPtrDfltAction
structure should always be
XkbSA_SetPtrDflt.
The
flags
field is composed of the bitwise inclusive OR of the values shown in
Table 16.9
(currently there is only one value defined).
Pointer Default FlagsFlagMeaningXkbSA_DfltBtnAbsolute
If set, the
value
field represents an absolute pointer button. Otherwise, the
value
field represents the amount to be added to the current default button.
The
affect
field specifies what changes as a result of this action. The only valid value
for the
affect
field is XkbSA_AffectDfltBtn.
The
valueXXX
field is a signed character that represents the new button value for the
mk_dflt_btn
attribute of the
MouseKeys
control (see section 10.5.1). If
XkbSA_DfltBtnAbsolute
is set in
flags,
valueXXX
specifies the button to be used; otherwise,
valueXXX
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
XkbPtrDfltAction
structures:
XkbSAPtrDfltValueint XkbSAPtrDfltValueXkbAction actact
action from which to extract group
XkbSAPtrDfltValue
returns the
valueXXX
field of
act
converted to a signed int.
XkbSASetPtrDfltValuevoid XkbSASetPtrDfltValueXkbPtrDfltAction actint valact
action in which to set valueXXXval
value to set in valueXXXXkbSASetPtrDfltValue
sets the
valueXXX
field of
act
from
val.
Actions for Locking Modifiers and GroupXkbISOAction
Actions associated with the
XkbISOAction
structure lock modifiers and the group according to the ISO9995 specification.
Operated by itself, the
XkbISOAction
is just a caps lock. Operated simultaneously with another modifier key, it
transforms the other key into a locking key. For example, press
ISO_Lock,
press and release
Control_L,
release
ISO_Lock
ends up locking the
Control
modifier.
The default behavior is to convert:
{Set,Latch}Mods to: LockMods{Set,Latch}Group to: LockGroupSetPtrBtn to: LockPtrBtnSetControls to: LockControls
The
affects
field allows you to turn those effects on or off individually. Set
XkbSA_ISONoAffectMods
to disable the first,
XkbSA_ISONoAffectGroup
to disable the second, and so forth.
typedef struct _XkbISOAction {
unsigned char type; /* XkbSA_ISOLock */
unsigned char flags; /* controls changes to group or
modifier state */
unsigned char mask; /* same as mask field of
a modifier description */
unsigned char real_mods; /* same as real_mods 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 vmods field of
a modifier description */
unsigned char vmods2; /* derived from vmods field of
a modifier description */
} XkbISOAction;
The
type
field of the
XkbISOAction
structure should always be
XkbSA_ISOLock.
The interpretation of the
flags
field depends on whether the
XkbSA_ISODfltIsGroup
is set in the
flags
field or not.
If the
XkbSA_ISODfltIsGroup
is set in the
flags
field, the action is used to change the group state. The remaining valid bits
of the
flags
field are composed of a bitwise inclusive OR using the masks shown in
Table 16.10.
ISO Action Flags when XkbSA_ISODfltIsGroup is SetFlagMeaningXkbSA_ISODfltIsGroup
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.
A key press sets the base group as specified by the
group_XXX
field and the
XkbSA_GroupAbsolute
bit of the
flags
field (see section Note). If no other actions are transformed by the
XkbSA_ISOLock
action, a key release locks the group. Otherwise, a key release clears group
set by the key press.
XkbSA_GroupAbsolute
If set, the
group_XXX
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.
XkbSA_ISONoAffectMods
If not set, any
XkbSA_SetMods
or
XkbSA_LatchMods
actions that occur simultaneously with the
XkbSA_ISOLock
action are treated as
XkbSA_LockMods
actions instead.
XkbSA_ISONoAffectGroup
If not set, any
XkbSA_SetGroup
or
XkbSA_LatchGroup
actions that occur simultaneously with the
XkbSA_ISOLock
action are treated as
XkbSA_LockGroup
actions instead.
XkbSA_ISONoAffectPtr
If not set, any
XkbSA_PtrBtn
actions that occur simultaneously with the
XkbSA_ISOLock
action are treated as
XkbSA_LockPtrBtn
actions instead.
XkbSA_ISONoAffectCtrls
If not set, any
XkbSA_SetControls
actions that occur simultaneously with the
XkbSA_ISOLock
action are treated as
XkbSA_LockControls
actions instead.
If the
XkbSA_ISODfltIsGroup
is not set in the
flags
field, the action is used to change the modifier state and the remaining valid
bits of the
flags
field are composed of a bitwise inclusive OR using the masks shown in
Table 16.11.
ISO Action Flags when XkbSA_ISODfltIsGroup is Not SetFlagMeaningXkbSA_ISODfltIsGroup
If not set, action is used to change the base modifier state. Must not be set
for the remaining bits in this table to carry their interpretations.
A key press sets the action modifiers in the keyboard’s base modifiers using
the
mask,
real_mods,
vmods1,
and
vmods2
fields (see section 16.1.3). If no other actions are transformed by the
XkbSA_ISOLock
action, a key release locks the action modifiers. Otherwise, a key release
clears the base modifiers set by the key press.
XkbSA_UseModMapMods
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
mask,
real_mods,
vmods1,
and
vmods2
fields.
XkbSA_LockNoLockIf set, the server only unlocks the action modifiers.XkbSA_LockNoUnlockIf set, the server only locks the action modifiers. XkbSA_ISONoAffectMods
If not set, any
XkbSA_SetMods
or
XkbSA_LatchMods
actions that occur simultaneously with the
XkbSA_ISOLock
action are treated as
XkbSA_LockMods
actions instead.
XkbSA_ISONoAffectGroup
If not set, any
XkbSA_SetGroup
or
XkbSA_LatchGroup
actions that occur simultaneously with the
XkbSA_ISOLock
action are treated as
XkbSA_LockGroup
actions instead.
XkbSA_ISONoAffectPtr
If not set, any
XkbSA_PtrBtn
actions that occur simultaneously with the
XkbSA_ISOLock
action are treated as
XkbSA_LockPtrBtn
actions instead.
XkbSA_ISONoAffectCtrls
If not set, any
XkbSA_SetControls
actions that occur simultaneously with the
XkbSA_ISOLock
action are treated as
XkbSA_LockControls
actions instead.
The
group_XXX
field represents a signed character. Xkb provides macros to convert between a
signed integer value and a signed character as shown in section Note.
The
mask,
real_mods,
vmods1,
and
vmods2
fields represent the components of an Xkb modifier description
(see section 7.2). While the
mask
and
real_mods
fields correspond directly to the
mask
and
real_mods
fields of an Xkb modifier description, the
vmods1
and
vmods2
fields are combined to correspond to the
vmods
field of an Xkb modifier description. Xkb provides macros to convert between
the two formats as shown in section 16.1.3.
The
affect
field is composed of a bitwise inclusive OR using the masks shown in
Table 16.11.
ISO Action Affect Field ValuesAffectMeaningXkbSA_ISONoAffectMods
If
XkbSA_ISONoAffectMods
is not set, any
SA_SetMods
or
SA_LatchMods
actions occurring simultaneously with the
XkbISOAction
are treated as
SA_LockMods
instead.
XkbSA_ISONoAffectGroup
If
XkbSA_ISONoAffectGroup
is not set, any
SA_SetGroup
or
SA_LatchGroup
actions occurring simultaneously with the
XkbISOAction
are treated as
SA_LockGroup
instead.
XkbSA_ISONoAffectPtr
If
XkbSA_ISONoAffectPtr
is not set, any
SA_PtrBtn
actions occurring simultaneously with the
XkbISOAction
are treated as
SA_LockPtrBtn
instead.
XkbSA_ISONoAffectCtrls
If
XkbSA_ISONoAffectCtrls
is not set, any
SA_SetControls
actions occurring simultaneously with the
XkbISOAction
are treated as
SA_LockControls
instead.
Actions for Changing the Active ScreenXkbSwitchScreenAction
Actions associated with the
XkbSwitchScreenAction
action structure change the active screen on a multiscreen display:
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
XkbSA_NoAction.
Otherwise, key press and key release events do not generate an event.
typedef struct _XkbSwitchScreenAction {
unsigned char type; /* XkbSA_SwitchScreen */
unsigned char flags; /* controls screen switching */
char screenXXX; /* screen number or delta */
} XkbSwitchScreenAction;
The
type
field of the
XkbSwitchScreenAction
structure should always be
XkbSA_SwitchScreen.
The
flags
field is composed of the bitwise inclusive OR of the masks shown in
Table 16.13.
Switch Screen Action FlagsFlagMeaningXkbSA_SwitchAbsolute
If set, the
screenXXX
field represents the index of the new screen. Otherwise, it represents an
offset from the current screen to the new screen.
XkbSA_SwitchApplication
If not set, the action should switch to another screen on the same
server. Otherwise, it should switch to another X server or application that
shares the same physical display.
The
screenXXX
field is a signed character value that represents either the relative or
absolute screen index, depending on the state of the
XkbSA_SwitchAbsolute
bit in the
flags
field. Xkb provides the following macros to convert between the integer and
signed character value for screen numbers in
XkbSwitchScreenAction
structures:
XkbSAScreenint XkbSAScreenXkbSwitchScreenAction actact
action from which to extract screen
XkbSAScreen
returns the
screenXXX
field of
act
converted to a signed int.
XkbSASetScreenvoid XkbSASetScreenXkbSwitchScreenAction actint sact
action in which to set screenXXXs
value to set in screenXXXXkbSASetScreen
sets the
screenXXX
field of
act
from
s.
Actions for Changing Boolean Controls StateXkbCtrlsAction
Actions associated with the
XkbCtrlsAction
structure change the state of the boolean controls (see section 10.1):
typedef struct _XkbCtrlsAction {
unsigned char type; /* XkbSA_SetControls,
XkbSA_LockControls */
unsigned char flags; /* with type, controls enabling
and disabling of controls */
unsigned char ctrls3; /* ctrls0 through ctrls3
represent the boolean controls */
unsigned char ctrls2; /* ctrls0 through ctrls3
represent the boolean controls */
unsigned char ctrls1; /* ctrls0 through ctrls3
represent the boolean controls */
unsigned char ctrls0; /* ctrls0 through ctrls3
represent the boolean controls */
} XkbCtrlsAction;
The
type
field can have any one of the values shown in
Table 16.14.
Controls Action TypesTypeEffectXkbSA_SetControls
A key press enables any boolean controls specified in the
ctrls
fields that were not already enabled at the time of the key press.
A key release disables any controls enabled by the key press.
This action can cause
XkbControlsNotify
events (see section 10.1).
XkbSA_LockControls
If the
XkbSA_LockNoLock
bit is not set in the
flags
field, a key press enables any controls specified in the
ctrls
fields that were not already enabled at the time of the key press.
If the
XkbSA_LockNoUnlock
bit is not set in the
flags
field, a key release disables any controls specified in the
ctrls
fields that were not already disabled at the time of the key press.
This action can cause
XkbControlsNotify
events (see section 10.1).
The
flags
field is composed of the bitwise inclusive OR of the masks shown in
Table 16.15.
Control Action FlagsFlagMeaningXkbSA_LockNoLock
If set, and the action type is
XkbSA_LockControls,
the server only disables controls.
XkbSA_LockNoUnlock
If set, and the action type is
XkbSA_LockControls,
the server only enables controls.
The
XkbSA_SetControls
action implements a key that enables a boolean control when pressed and
disables it when released. The
XkbSA_LockControls
action is used to implement a key that toggles the state of a boolean control
each time it is pressed and released. The
XkbSA_LockNoLock
and
XkbSA_LockNoUnlock
flags allow modifying the toggling behavior to only unlock or only lock the
boolean control.
The
ctrls0,
ctrls1,
ctrls2,
and
ctrls3
fields represent the boolean controls in the
enabled_ctrls
field of the controls structure (see section 10.1). Xkb provides the following
macros, to convert between the two formats:
XkbActionCtrlsunsigned int XkbActionCtrlsXkbCtrlsAction actact
action from which to extract controls
XkbActionCtrls
returns the
ctrls
fields of
act
converted to an unsigned int.
XkbSAActionSetCtrlsvoid XkbSAActionSetCtrlsXkbCtrlsAction actunsigned int ctrlsact
action in which to set ctrls0-ctrls3
ctrls
value to set in ctrls0-ctrls3
XkbSAActionSetCtrls
sets the
ctrls0
through
ctrls3
fields of
act
from
ctrls.
Actions for Generating MessagesXkbMessageAction
Actions associated with the
XkbMessageAction
structure generate
XkbActionMessage
events:
#define XkbActionMessageLength 6
typedef struct _XkbMessageAction {
unsigned char type; /* XkbSA_ActionMessage */
unsigned char flags; /* controls event generation via
key presses and releases */
unsigned char message[XkbActionMessageLength]; /* message */
} XkbMessageAction;
The
type
field of the
XkbMessageAction
structure should always be
XkbSA_ActionMessage.
The
flags
field is composed of the bitwise inclusive OR of the masks shown in
Table 16.16.
Message Action FlagsFlagMeaningXkbSA_MessageOnPress
If set, key press events generate an
XkbActionMessage
event that reports the keycode, event type, and contents of the
message
field.
XkbSA_MessageOnRelease
If set, key release events generate an
XkbActionMessage
event that reports the keycode, event type, and contents of the
message
field.
XkbSA_MessageGenKeyEvent
If set, key press and key release events generate
KeyPress
and
KeyRelease
events, regardless of whether they generate
XkbActionMessage
events.
The
message
field is an array of
XkbActionMessageLength
unsigned characters and may be set to anything the keymap designer wishes.
Detecting Key Action MessageseventsXkbActionMessageXkbActionMessageEvent
To receive
XkbActionMessage
events by calling either
XkbSelectEvents
or
XkbSelectEventDetails
(see section 4.3).
To receive
XkbActionMessage
events under all possible conditions, use
XkbSelectEvents
and pass
XkbActionMessageMask
in both
bits_to_change
and
values_for_bits.
The
XkbActionMessage
event has no event details. However, you can call
XkbSelectEventDetails
using
XkbActionMessage
as the
event_type
and specifying
XkbAllActionMessagesMask
in
bits_to_change
and
values_for_bits.
This has the same effect as a call to
XkbSelectEvents.
The structure for the
XkbActionMessage
event is defined as follows:
typedef struct _XkbActionMessage {
int type; /* Xkb extension base event code */
unsigned long serial; /* X server serial number for event */
Bool send_event; /* True ⇒ synthetically generated */
Display * display; /* server connection where event generated */
Time time; /* server time when event generated */
int xkb_type; /* XkbActionMessage */
int device; /* Xkb device ID,
will not be XkbUseCoreKbd */
KeyCode keycode; /* keycode of key triggering event */
Bool press; /* True ⇒ key press,
False ⇒ release */
Bool key_event_follows;/* True ⇒ KeyPress/KeyRelease follows */
char message[XkbActionMessageLength+1]; /* message text */
} XkbActionMessageEvent;
The
keycode
is the keycode of the key that was pressed or released. The
press
field specifies whether the event was the result of a key press or key
release.
The
key_event_follows
specifies whether a
KeyPress
(if
press
is
True)
or
KeyRelease
(if
press
is
False)
event is also sent to the client. As with all other Xkb events,
XkbActionMessageEvents
are delivered to all clients requesting them, regardless of the current
keyboard focus. However, the
KeyPress
or
KeyRelease
event that conditionally follows an
XkbActionMessageEvent
is sent only to the client selected by the current keyboard focus.
key_event_follows
is
True
only for the client that is actually sent the following
KeyPress
or
KeyRelease
event.
The
message
field is set to the message specified in the action and is guaranteed to be
NULL
-terminated; the Xkb extension forces a
NULL
into
message
[
XkbActionMessageLength
].
Actions for Generating a Different KeycodeXkbRedirectKeyAction
Actions associated with the
XkbRedirectKeyAction
structure generate
KeyPress
and
KeyRelease
events containing a keycode different from the key that was pressed or
released:
typedef struct _XkbRedirectKeyAction {
unsigned char type; /* XkbSA_RedirectKey */
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 */
} XkbRedirectKeyAction;
The
type
field for the
XkbRedirectKeyAction
structure should always be
XkbSA_RedirectKey.
Key presses cause a
KeyPress
event for the key specified by the
new_key
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
mods_mask
field are set to corresponding values from the
mods
field. Any real modifiers bound to the virtual modifiers specified by the
vmods_mask0
and
vmods_mask1
fields are either set or cleared, depending on the corresponding values in the
vmods0
and
vmods1
fields. If the real and virtual modifier definitions specify conflicting
values for a single modifier, the real modifier definition has priority.
Key releases cause a
KeyRelease
event for the key specified by the
new_key
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.
The
XkbSA_RedirectKey
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
KeyClass,
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.)
The
vmods_mask0
and
vmods_mask1
fields actually represent one
vmods_mask
value, as described in . Xkb provides the following macros, to
convert between the two formats:
XkbSARedirectVModsMaskunsigned int XkbSARedirectVModsMaskXkbRedirectKeyAction actact
action from which to extract vmods
XkbSARedirectVModsMask
returns the
vmods_mask0
and
vmods_mask1
fields of
act
converted to an unsigned int.
XkbSARedirectSetVModsMaskvoid XkbSARedirectSetVModsMaskXkbRedirectKeyAction actunsigned int vmact
action in which to set vmods
vm
new value for virtual modifier mask
XkbSARedirectSetVModsMask
sets the
vmods_mask0
and
vmods_mask1
fields of
act
from
vm.
Similarly, the
vmods0
and
vmods1
fields actually represent one
vmods
value, as described in . To convert between the two formats, Xkb
provides the following convenience macros:
XkbSARedirectVModsunsigned int XkbSARedirectVModsXkbRedirectKeyAction actact
action from which to extract vmods
XkbSARedirectVModsMask returns the vmods0
and vmods1 fields of act
converted to an unsigned int.
XkbSARedirectSetVModsvoid XkbSARedirectSetVModsXkbRedirectKeyAction actunsigned int vact
action in which to set vmods
v
new value for virtual modifiers
XkbSARedirectSetVModsMask sets the vmods0
and vmods1 of act from v.
Actions for Generating DeviceButtonPress and DeviceButtonReleaseXkbDeviceBtnAction
Actions associated with
XkbDeviceBtnAction
structures generate
DeviceButtonPress
and
DeviceButtonRelease
events instead of normal
KeyPress
and
KeyRelease
events:
typedef struct _XkbDeviceBtnAction {
unsigned char type; /* XkbSA_DeviceBtn, XkbSA_LockDeviceBtn */
unsigned char flags; /* with type, specifies locking or unlocking */
unsigned char count; /* controls number of DeviceButtonPress
and Release events */
unsigned char button; /* index of button on device */
unsigned char device; /* device ID of an X input extension device */
} XkbDeviceBtnAction;
The
type
field can have any one of the values shown in
Table 16.17.
Device Button Action TypesTypeEffectXkbSA_DeviceBtn
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
XkbSA_NoAction.
Otherwise, key presses cause one or more input extension device events instead
of the usual key press event. If the
count
field is zero, a key press generates a single
DeviceButtonPress
event. If count is greater than zero, a key press event generates
count
pairs of
DeviceButtonPress
and
DeviceButtonRelease
events.
If
count
is zero, a key release generates an input extension
DeviceButtonRelease
event that matches the event generated by the corresponding key press. If
count
is nonzero, a key release does not cause a
DeviceButtonRelease
event. Key releases never cause
KeyRelease
events.
XkbSA_LockDeviceBtn
If the device or button specified by this action are illegal, this action
behaves like XkbSA_NoAction.
Otherwise, if the specified button is not locked and the
XkbSA_LockNoLock
bit is not set in the
flags
field, a key press generates an input extension
DeviceButtonPress
event instead of a
KeyPress
event and locks the button. If the button is already locked or if
XkbSA_LockNoLock
bit is set in the
flags
field, the key press is ignored and has no effect.
If the corresponding key press was ignored, and if the
XkbSA_LockNoUnlock
bit is not set in the
flags
field, a key release generates an input extension
DeviceButtonRelease
event instead of a
KeyRelease
event and unlocks the button. If the corresponding key press locked a button,
the key release is ignored and has no effect.
The
flags
field is composed of the bitwise inclusive OR of the masks shown in
Table 16.18.
Device Button Action FlagsFlagMeaningXkbSA_LockNoLock
If set, and the action type is
XkbSA_LockDeviceBtn,
the server only unlocks the button.
XkbSA_LockNoUnlock
If set, and the action type is
XkbSA_LockDeviceBtn,
the server only locks the button.
Actions for Simulating Events from Device ValuatorsXkbDeviceValuatorAction
A
valuatorvaluator
manipulates a range of values for some entity, like a mouse axis, a slider or
a dial. Actions associated with
XkbDeviceValuatorAction
structures are used to simulate events from one or two input extension device
valuators.
typedef struct _XkbDeviceValuatorAction {
unsigned char type; /* XkbSA_DeviceValuator */
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 */
} XkbDeviceValuatorAction;
If
device
is illegal or if neither
v1_ndx
nor
v2_ndx
specifies a legal valuator, this action behaves like
XkbSA_NoAction.
The low four bits of
v1_what
and
v2_what
specify the corresponding scale value (denoted
val<n>Scale
in Table 16.17), if needed.
The high four bits of
v1_what
and
v2_what
specify the operation to perform to set the values. The high four bits of
v1_what
and
v2_what
can have the values shown in Table 16.17;
the use of
val<n>Scale
is shown in that table also.
Device Valuator v<n>_what High Bits ValuesValue of high bitsEffectXkbSA_IgnoreValNo actionXkbSA_SetValMinv<n>_value is set to its minimum legal value.
XkbSA_SetValCenterv<n>_valueis centered (to (max-min)/2).
XkbSA_SetValMaxv<n>_value is set to its maximum legal value.
XkbSA_SetValRelativev<n>_value * (2
val<n>Scale) is added to
v<n>_value.
XkbSA_SetValAbsolutev<n>_value
is set to (2 val<n>Scale).
Illegal values for
XkbSA_SetValRelative
or
XkbSA_SetValAbsolute
are clamped into range. Note that all of these possibilities are legal for
absolute valuators. For relative valuators, only
XkbSA_SetValRelative
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.
The following two masks are provided as a convenience to select either portion
of
v1_what
or
v2_what:
#define XkbSA_ValOpMask (0x70)
#define XkbSA_ValScaleMask (0x07)
v1_ndx
and
v2_ndx
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.
Obtaining Key Actions for Keys from the Server
To update the actions (the
key_acts
array) for a subset of the keys in a keyboard description, use
XkbGetKeyActions.
XkbGetKeyActionsStatus XkbGetKeyActionsDisplay *dpyunsigned int firstunsigned int numXkbDescPtr xkbdpy
connection to X server
first
keycode of first key of interest
num
number of keys desired
xkb
pointer to keyboard description where result is stored
XkbGetKeyActions
sends a request to the server to obtain the actions for
num
keys on the keyboard starting with key
first.
It waits for a reply and returns the actions in the
server->key_acts
field of
xkb.
If successful,
XkbGetKeyActions
returns
Success.
The
xkb
parameter must be a pointer to a valid Xkb keyboard description.
If the
server
map in the
xkb
parameter has not been allocated,
XkbGetKeyActions
allocates and initializes it before obtaining the actions.
If the server does not have a compatible version of Xkb, or the Xkb extension
has not been properly initialized,
XkbGetKeyActions
returns
BadAccess.
If
num
is less than 1 or greater than
XkbMaxKeyCount,
XkbGetKeyActions
returns
BadValue.
If any allocation errors occur,
XkbGetKeyActions
returns
BadAlloc.
Changing the Number of Actions Bound to a Key
To change the number of actions bound to a key, use
XkbResizeKeyActions.
XkbResizeKeyActionsXkbAction *XkbResizeKeyActionsXkbDescRec *xkbint keyint neededxkb
keyboard description to change
key
keycode of key to change
needed
new number of actions required
The
xkb
parameter points to the keyboard description containing the
key
whose number of actions is to be changed. The
key
parameter is the keycode of the key to change, and
needed
specifies the new number of actions required for the key.
XkbResizeKeyActions
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
acts,
num_acts,
and
size_acts
fields of
xkb->server
if it is necessary to reallocate the
acts
array.
If
needed
is greater than the current number of keysyms for the key,
XkbResizeKeyActions
initializes all new actions in the array to
NoAction.
Because the number of actions needed by a key is normally computed as width *
number of groups, and
XkbResizeKeyActions
does not modify either the width or number of groups for the key, a
discrepancy exists on return from
XkbResizeKeyActions
between the space allocated for the actions and the number required. The
unused entries in the list of actions returned by
XkbResizeKeyActions
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
XkbChangeTypesOfKey
updates these.
If any allocation errors occur while resizing the number of actions bound to
the key,
XkbResizeKeyActions
returns
NULL.
A change to the number of actions bound to a key should be
accompanied by a change in the number of symbols bound to a key. Refer to
section 15.3.7 for more information on changing the number of symbols bound to
a key.Key Behavior
Key behavior refers to the demeanor of a key. For example, the expected
behavior of the
CapsLock
key is that it logically locks when pressed, and then logically unlocks when
pressed again.
Radio Groups
Keys that belong to the same radio group have the
XkbKB_RadioGroup
type in the
type
field and the radio group index specified in the
data
field in the
XkbBehavior
structure. If the radio group has a name in the
XkbNamesRec
structure, the radio group index is the index into the
radio_group
array in the
XkbNamesRec
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
XkbKB_RGAllowNone
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
XkbKB_RGAllowNone
is not set, there is no way to release the logically down member of the group.
The low five bits of the
data
field of the
XkbBehavior
structure are the group number, the high three bits are flags. The only flag
currently defined is:
#define XkbKB_RGAllowNone 0x80
The XkbBehavior StructureXkbBehavior
The
behaviors
field of the server map is an array of
XkbBehavior
structures, indexed by keycode, and contains the behavior for each key. The
XkbBehavior
structure is defined as follows:
typedef struct _XkbBehavior {
unsigned char type; /* behavior type + optional
XkbKB_Permanent bit */
unsigned char data;
} XkbBehavior;
The
type
field specifies the Xkb behavior, and the value of the
data
field depends on the
type.
Xkb supports the key behaviors shown in
Table 16.20.
Key BehaviorsTypeEffectXkbKB_Default
Press and release events are processed normally. The
data
field is unused.
XkbKB_Lock
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
data
field is unused.
XkbKB_RadioGroup
If another member of the radio group is logically down (all members of the
radio group have the same index, specified in
data)
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.
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
XkbKB_RGAllowNone
bit in
flags.
If it is set, the key release is processed normally; otherwise, the key
release is also ignored.
All other key release events are ignored.
XkbKB_Overlay1
If the
Overlay1
control is enabled (see section 10.4),
data
is interpreted as a keycode, and events from this key are reported as if they
came from
data’s
keycode. Otherwise, press and release events are processed normally.
XkbKB_Overlay2
If the
Overlay2
control is enabled (see section 10.4),
data
is interpreted as a keycode, and events from this key are reported as if they
came from
data’s
keycode. Otherwise, press and release events are processed normally.
Xkb also provides the mask,
XkbKB_Permanent
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
XkbKB_Permanent
bit is not set in the
type
field, Xkb simulates the behavior in software. Otherwise, Xkb relies upon the
keyboard to implement the behavior.
Obtaining Key Behaviors for Keys from the Server
To obtain the behaviors (the
behaviors
array) for a subset of the keys in a keyboard description from the server, use
XkbGetKeyBehaviors:
XkbGetKeyBehaviorsStatus XkbGetKeyBehaviorsDisplay *dpyunsigned int firstunsigned int numXkbDescPtr xkbdpy
connection to server
first
keycode of first key to get
num
number of keys for which behaviors are desired
xkb
Xkb description to contain the result
XkbGetKeyBehaviors
sends a request to the server to obtain the behaviors for
num
keys on the keyboard starting with the key whose keycode is
first.
It waits for a reply and returns the behaviors in the
server->behaviors
field of
xkb.
If successful,
XkbGetKeyBehaviors
returns
Success.
If the
server
map in the
xkb
parameter has not been allocated,
XkbGetKeyBehaviors
allocates and initializes it before obtaining the actions.
If the server does not have a compatible version of Xkb, or the Xkb extension
has not been properly initialized,
XkbGetKeyBehaviors
returns
BadAccess.
If
num
is less than 1 or greater than
XkbMaxKeyCount,
XkbGetKeyBehaviors
returns
BadValue.
If any allocation errors occur,
XkbGetKeyBehaviors
returns
BadAlloc.
Explicit Components—Avoiding Automatic Remapping by the Server
Whenever a client remaps the keyboard using core protocol requests, Xkb
examines the map to determine likely default values for the components that
cannot be specified using the core protocol (see section 17.1.2 for more
information on how Xkb chooses the default values).
This automatic remapping might replace definitions explicitly requested by an
application, so the Xkb keyboard description defines an explicit components
mask for each key. Any aspects of the automatic remapping listed in the
explicit components mask for a key are not changed by the automatic keyboard
mapping.
The explicit components masks are held in the
explicit
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.
Explicit Component MasksBit in Explicit MaskValueProtects AgainstExplicitKeyType1(1<<0)
Automatic determination of the key type associated with
Group1.
ExplicitKeyType2(1<<1)
Automatic determination of the key type associated with
Group2.
ExplicitKeyType3(1<<2)
Automatic determination of the key type associated with
Group3.
ExplicitKeyType4(1<<3)
Automatic determination of the key type associated with
Group4.
ExplicitInterpret(1<<4)
Application of any of the fields of a symbol interpretation to the
key in question.
ExplicitAutoRepeat(1<<5)Automatic determination of auto-repeat status for the key, as
specified in a symbol interpretation.ExplicitBehavior(1<<6)
Automatic assignment of the
XkbKB_Lock
behavior to the key, if the
XkbSI_LockingKey
flag is set in a symbol interpretation.
ExplicitVModMap(1<<7)
Automatic determination of the virtual modifier map for the key
based on the actions assigned to the key and the symbol interpretations that
match the key.
Protocol requests made by each Xlib functionXlib FunctionProtocol RequestForceScreenSaverChangeHostsChangeHostsChangeSaveSetAllocColorAllocColorCellsAllocColorPlanesAllocNamedColorAllowEventsChangeKeyboardControlChangeKeyboardControlBellChangeActivePointerGrabChangeGCChangeKeyboardControlChangeKeyboardMappingChangePointerControlChangePropertyChangeSaveSetChangeWindowAttributesCirculateWindowCirculateWindowCirculateWindowClearAreaClearAreaConfigureWindowConvertSelectionCopyAreaCopyColormapAndFreeCopyGCCopyPlaneCreateGCCreatePixmapFreeGCPutImageCreateColormapCreateGlyphCursorCreateGCCreateGlyphCursorCreatePixmapCreateCursorXCreatePixmapFromDataCreateGCCreatePixmapFreeGCPutImageCreateWindowCreateWindowChangeWindowAttributesDeletePropertyDestroySubwindowsDestroyWindowSetAccessControlPolyArcPolyArcImageText8ImageText16PolySegmentPolyLinePolyPointPolyPointPolyRectanglePolyRectanglePolySegmentPolyText8PolyText16PolyText8PolyText16SetAccessControlGetPropertyGetPropertyPolyFillArcPolyFillArcFillPolyPolyFillRectanglePolyFillRectangleForceScreenSaverFreeColormapFreeColorsFreeCursorCloseFontFreeGCFreePixmapGetAtomNameGetPropertyGetFontPathGetGeometryGetPropertyGetPropertyGetImageGetInputFocusGetKeyboardControlGetKeyboardMappingGetModifierMappingGetMotionEventsGetPropertyGetPointerControlGetPointerMappingGetPropertyGetScreenSaverGetSelectionOwnerGetPropertyGetPropertyGetPropertyGetPropertyGetPropertyInternAtomGetPropertyGetPropertyGetPropertyGetPropertyGetPropertyInternAtomGetPropertyGetWindowAttributesGetGeometryGetPropertyGetPropertyGrabButtonGrabKeyGrabKeyboardGrabPointerGrabServerInternAtomSendEventQueryExtensionInstallColormapInternAtomKillClientListExtensionsListFontsListFontsWithInfoListHostsListInstalledColormapsListPropertiesOpenFontOpenFontQueryFontLookupColorConfigureWindowConfigureWindowMapWindowMapSubwindowsMapWindowConfigureWindowConfigureWindowNoOperationCreateGCLookupColorPutImageQueryBestSizeQueryBestSizeQueryBestSizeQueryBestSizeQueryColorsQueryColorsQueryExtensionQueryFontQueryKeymapQueryPointerQueryTextExtentsQueryTextExtentsQueryTreeConfigureWindowCreateGCCreatePixmapFreeGCPutImageRecolorCursorConfigureWindowSendEventChangeSaveSetChangeHostsChangeHostsReparentWindowForceScreenSaverConfigureWindowConfigureWindowRotatePropertiesRotatePropertiesChangeWindowAttributesSendEventSetAccessControlChangeGCChangeGCChangePropertyChangeGCChangeGCSetClipRectanglesSetCloseDownModeChangePropertySetDashesChangeGCChangeGCChangeGCSetFontPathChangeGCChangeGCChangeGCChangePropertyChangePropertySetInputFocusChangeGCSetModifierMappingChangePropertyChangeGCSetPointerMappingChangePropertySetScreenSaverSetSelectionOwnerChangePropertyChangePropertyChangeGCChangeGCChangeGCChangePropertyChangeGCChangePropertyChangeGCChangePropertyChangePropertyInternAtomChangePropertyChangePropertyChangePropertyChangePropertyChangePropertyChangePropertyInternAtomChangePropertyChangeWindowAttributesChangeWindowAttributesChangeWindowAttributesChangeWindowAttributesConfigureWindowChangeWindowAttributesChangePropertyChangePropertyChangePropertyStoreColorsStoreColorsChangePropertyStoreNamedColorGetInputFocusXSynchronizeGetInputFocusTranslateCoordinatesChangeWindowAttributesUngrabButtonUngrabKeyUngrabKeyboardUngrabPointerUngrabServerUninstallColormapCloseFontUnmapSubwindowsUnmapWindowWarpPointerSendEventUnmapWindow
The following table lists each X protocol request (in alphabetical
order) and the Xlib functions that reference it.
Xlib functions which use each Protocol RequestProtocol RequestXlib FunctionAllocColorAllocColorCellsAllocColorPlanesAllocNamedColorAllowEventsBellChangeActivePointerGrabChangeGCChangeHostsChangeKeyboardControlChangeKeyboardMappingChangePointerControlChangePropertyChangeSaveSetChangeWindowAttributesCirculateWindowClearAreaCloseFontConfigureWindowConvertSelectionCopyAreaCopyColormapAndFreeCopyGCCopyPlaneCreateColormapCreateCursorCreateGCXCreatePixmapFromDataCreateGlyphCursorCreatePixmapXCreatePixmapFromDataCreateWindowDeletePropertyDestroySubwindowsDestroyWindowFillPolyForceScreenSaverFreeColormapFreeColorsFreeCursorFreeGCXCreatePixmapFromDataFreePixmapGetAtomNameGetFontPathGetGeometryGetImageGetInputFocusXSynchronizeGetKeyboardControlGetKeyboardMappingGetModifierMappingGetMotionEventsGetPointerControlGetPointerMappingGetPropertyGetSelectionOwnerGetWindowAttributesGrabButtonGrabKeyGrabKeyboardGrabPointerGrabServerImageText8ImageText16InstallColormapInternAtomKillClientListExtensionsListFontsListFontsWithInfoListHostsListInstalledColormapsListPropertiesLookupColorMapSubwindowsMapWindowNoOperationOpenFontPolyArcPolyFillArcPolyFillRectanglePolyLinePolyPointPolyRectanglePolySegmentPolyText8PolyText16PutImageXCreatePixmapFromDataQueryBestSizeQueryColorsQueryExtensionQueryFontQueryKeymapQueryPointerQueryTextExtentsQueryTreeRecolorCursorReparentWindowRotatePropertiesSendEventSetAccessControlSetClipRectanglesSetCloseDownModeSetDashesSetFontPathSetInputFocusSetModifierMappingSetPointerMappingSetScreenSaverSetSelectionOwnerStoreColorsStoreNamedColorTranslateCoordinatesUngrabButtonUngrabKeyUngrabKeyboardUngrabPointerUngrabServerUninstallColormapUnmapSubwindowsXUnmapSubWindowsUnmapWindowWarpPointer
Event Flow Control
This protocol supports two event flow models for communication between the
IM library and the IM Server (Static and Dynamic).
Static Event Flow requires that input events always be sent to the IM
Server from the client.
Dynamic Event Flow, however, requires only that those input events which
need to be processed (converted) be sent to the IM Server from the client.
For instance, in the case of inputing a combination of ASCII characters
and Chinese characters, ASCII characters do not need to be processed in
the IM Server, so their key events do not have to be sent to the IM
Server. On the other hand, key events necessary for composing Chinese
characters must be sent to the IM Server.
Thus, by adopting the Dynamic Event Flow, the number of requests among the
X Server, the client, and the IM Server is significantly reduced, and the
number of context switches is also reduced, resulting in improved performance.
The IM Server can send
XIM_REGISTER_TRIGGERKEYS
message in order to switch the event flow in the Dynamic Event Flow.
The protocol for this process is described in
.
Default Preconnection Convention
IM Servers are strongly encouraged to register their symbolic
names as the ATOM names into the IM Server directory property,
XIM_SERVERS,
on the root window of the screen_number 0.
This property can contain a list of ATOMs, and the each ATOM represents
each possible IM Server.
IM Server names are restricted to POSIX Portable Filename Character Set.
To discover if the IM Server is active, see if there is an owner for
the selection with that atom name. To learn the address of that IM Server,
convert the selection target
TRANSPORT,
which will return a string form of the transport address(es).
To learn the supported locales of that IM Server, convert the selection target
LOCALES,
which will return a set of names of the supported locales in the syntax
X/Open defines.
The basic semantics to determine the IM Server if there are
multiple ATOMs are found in
XIM_SERVERS
property, is first fit if the IM Server name is not given as
a X modifier's category
im.
The address information retrievable from the
TRANSPORT
target is a transport-specific name.
The preregistered formats for transport-specific names are listed in
.
Additional transport-specific names may be registered with X Consortium.
For environments that lack X connections, or for IM Servers which
do not use the X Window System, the preconnection convention with IM Server
may be given outside the X Window system (e.g. using a Name Service).
Protocol
The protocol described below uses the bi-directional
synchronous/asynchronous request/reply/error model and is specified
using the same conventions outlined in Section 2 of the core X Window
System protocol [1]:
Basic Requests Packet Format
This section describes the requests that may be exchanged between the client
and the IM Server.
The basic request packet header format is as follows.
major-opcode: CARD8
minor-opcode: CARD8
length: CARD16
The MAJOR-OPCODE specifies which core request or extension package this
packet represents. If the MAJOR-OPCODE corresponds to a core request,
the MINOR-OPCODE contains 8 bits of request-specific data.
(If the MINOR-OPCODE is not used, it is 0.)
Otherwise, the MAJOR-OPCODE and the MINOR-OPCODE are specified by
XIM_QUERY_EXTENSION
message. (Refer to 4.7. Query the supported extension protocol list.)
The LENGTH field specifies the number of 4 bytes elements following the
header. If no additional data is followed by the header, the LENGTH field
will be 0.
Data Types
The following data types are used in the core X IM Server protocol:
BITMASK16
CARD16
BITMASK32
CARD32
PADDING FORMAT
Where N is some expression, and Pad(N) is the number of bytes needed to round N up to a
Pad(N) = (4 - (N mod 4)) mod 4
LPCE
1 A character from the4 X Portable Character Set in Latin Portable
Character Encoding
STRING
2 n length of string in bytes
n LISTofLPCE string
p unused, p=Pad(2+n)
STR
1 n length of name in bytes
n STRING8 name
XIMATTR
2 CARD16 attribute ID (*1)
2 CARD16 type of the value (*2)
2 n length of im-attribute
n STRING8 im-attribute
p unused, p = Pad(2+n)
The im-attribute argument specifies XIM values such as XNQueryInputStyle.
XICATTR
2 CARD16 attribute ID (*1)
2 CARD16 type of the value (*2)
2 n length of ic-attribute
n STRING8 ic-attribute
p unused, p = Pad(2+n)
(*1) XIMATTR and XICATTR are used during the setup stage and XIMATTRIBUTE and
XICATTRIBUTE are used after each attribute ID has been recognized by
the IM Server and the IM library.
(*2) The value types are defined as follows:
valuesdataformat#0Separator of NestedList-----(*3)#1byte dataCARD8#2word dataCARD16#3long dataCARD32#4char dataSTRING8#5WindowCARD32#10XIMStyles2nnumber of XIMStyle list2unusednCARD32XIMStyle list#11XRectangle2INT16X2INT16Y2CARD16width2CARD16height#12XPoint2INT16X2INT16Y#13XFontSet2nlength of Base font namenSTRING8Base font name listpunused, p = Pad(2+n)#15XIMHotKeyTriggers4nnumber of XIMTRIGGERKEY list (*4)nXIMTRIGGERKEYXIMHotkeyTrigger listnXIMHOTKEYSTATEHotKey processing state#17XIMStringConversionXIMSTRCONVTEXT#18XIMPreeditStateXIMPREEDITSTATE#19XIMResetStateXIMRESETSTATE#x7fffNestedList-----
(*3) The IC value for the separator of NestedList is defined as follows,
#define XNSeparatorofNestedList "separatorofNestedList"
, which is registered in X Consortium and cannot be used for any other purpose.
(*4) LISTofFOO
A Type name of the form LISTof FOO means a counted list of elements of type FOO.
The size of the length field may vary (it is not necessarily the same
size as a FOO), and in some cases, it may be implicit.
XIMTRIGGERKEY
4 CARD32 keysym
4 CARD32 modifier
4 CARD32 modifier mask
ENCODINGINFO
2 n length of encoding info
n STRING8 encoding info
p unused, p=Pad(2+n)
1 CARD8 extension major-opcode
1 CARD8 extension minor-opcode
2 n length of extension name
n STRING8 extension name
p unused, p = Pad(n)
XIMATTRIBUTE
2 CARD16 attribute ID
2 n value length
n value
p unused, p = Pad(n)
XICATTRIBUTE
2 CARD16 attribute ID
2 n value length
n value
p unused, p = Pad(n)
XIMSTRCONVTEXT
2 CARD16 XIMStringConversionFeedback
#x0000001 XIMStringConversionLeftEdge
#x0000002 XIMStringConversionRightEdge
#x0000004 XIMStringConversionTopEdge
#x0000008 XIMStringConversionBottomEdge
#x0000010 XIMStringConversionConvealed
#x0000020 XIMStringConversionWrapped
2 n byte length of the retrieved string
n STRING8 retrieved string
p unused, p = Pad(n)
2 m byte length of feedback array
2 unused
m LISTofXIMSTRCONVFEEDBACK feedback array(*1)
(*1) This field is reserved for future use.
XIMFEEDBACK
4 CARD32 XIMFeedback
#x000001 XIMReverse
#x000002 XIMUnderline
#x000004 XIMHighlight
#x000008 XIMPrimary
#x000010 XIMSecondary
#x000020 XIMTertiary
#x000040 XIMVisibleToForward
#x000080 XIMVisibleToBackward
#x000100 XIMVisibleCenter
XIMHOTKEYSTATE
4 CARD32 XIMHotKeyState
#x0000001 XIMHotKeyStateON
#x0000002 XIMHotKeyStateOFF
XIMPREEDITSTATE
4 CARD32 XIMPreeditState
#x0000001 XIMPreeditEnable
#x0000002 XIMPreeditDisable
XIMRESETSTATE
4 CARD32 XIMResetState
#x0000001 XIMInitialState
#x0000002 XIMPreserveState
Error Notification
Both the IM Server and the IM library return
XIM_ERROR
messages instead of the corresponding reply messages if any errors occur
during data processing.
At most one error is generated per request. If more than one error condition
is encountered in processing a request, the choice of which error is returned
is implementation-dependent.
XIM_ERROR (IM Server <--> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
2 BITMASK16 flag (*1)
#0000 Both Input-Method-ID and Input-Context-ID are invalid
#0001 Input-Method-ID is valid
#0002 Input-Context-ID is valid
2 CARD16 Error Code
#1 BadAlloc
#2 BadStyle
#3 BadClientWindow
#4 BadFocusWindow
#5 BadArea
#6 BadSpotLocation
#7 BadColormap
#8 BadAtom
#9 BadPixel
#10 BadPixmap
#11 BadName
#12 BadCursor
#13 BadProtocol
#14 BadForeground
#15 BadBackground
#16 LocaleNotSupported
#999 BadSomething (*2)
2 n byte length of error detail.
2 CARD16 type of error detail (*3)
n STRING8 error detail (*4)
p unused, p = Pad(n)
(*1) Before an IM is created, both Input-Method-ID and
Input-Context-ID are invalid.
Before an IC is created, only Input-Method-ID is valid.
After that, both of Input-Method-ID and Input-Context-ID are valid.
(*2) Unspecific error, for example "language engine died"
(*3) This field is reserved for future use.
(*4) Vendor defined detail error message
Connection EstablishmentXIM_CONNECT
message requests to establish a connection over a mutually-understood virtual
stream.
XIM_CONNECT (IM library -> IM Server)
1 byte order
#x42 MSB first
#x6c LSB first
1 unused
2 CARD16 client-major-protocol-version (*1)
2 CARD16 client-minor-protocol-version (*1)
2 CARD16 number of client-auth-protocol-names
n LISTofSTRING client-auth-protocol-names
(*1) Specify the version of IM Protocol that the client supports.
A client must send
XIM_CONNECT
message as the first message on the connection.
The list specifies the names of authentication protocols the sending
IM Server is willing to perform.
(If the client need not authenticate, the list may be omited.)
XIM_AUTH_REQUIRED
message is used to send the authentication protocol name and protocol-specific
data.
XIM_AUTH_REQUIRED (IM library <--> IM Server)
1 CARD8 auth-protocol-index
3 unused
2 n length of authentication data
2 unused
n <varies> data
p unused, p = Pad(n)
The auth-protocol is specified by an index into the list of names
given in the
XIM_CONNECT
or
XIM_AUTH_SETUP
message. Any protocol-specific data that might be required is also sent.
The IM library sends
XIM_AUTH_REPLY
message as the reply to
XIM_AUTH_REQUIRED
message, if the IM Server is authenticated.
XIM_AUTH_REPLY (IM library -> IM Server)
2 n length of authentication data
2 unused
2 n length of authentication data
2 unused
n <varies> data
p unused, p = Pad(n)
The auth data is specific to the authentication protocol in use.
XIM_AUTH_NEXT
message requests to send more auth data.
XIM_AUTH_NEXT (IM library <--> IM Server)
2 n length of authentication data
2 unused
n <varies> data
p unused, p = Pad(n)
The auth data is specific to the authentication protocol in use.
The IM Server sends
XIM_AUTH_SETUP
message to authenticate the client.
XIM_AUTH_SETUP (IM Server -> IM library)
2 CARD16 number of client-auth-protocol-names
2 unused
n LISTofSTRING server-auth-protocol-names
The list specifies the names of authentication protocols the
client is willing to perform.
XIM_AUTH_NG
message requests to give up the connection.
XIM_AUTH_NG (IM library <--> IM Server)
The IM Server sends
XIM_CONNECT_REPLY
message as the reply to
XIM_CONNECT
or
XIM_AUTH_REQUIRED
message.
XIM_CONNECT_REPLY (IM Server -> IM library)
2 CARD16 server-major-protocol-version (*1)
2 CARD16 server-minor-protocol-version (*1)
(*1) Specify the version of IM Protocol that the IM Server supports.
This document specifies major version one, minor version zero.
Here are the state diagrams for the client and the IM Server.
State transitions for the client
init_status:
Use authorization function -> client_ask
Not use authorization function -> client_no_checkstart:
Send XIM_CONNECT
If client_ask -> client_wait1
If client_no_check,
client-auth-protocol-names may be omited -> client_wait2client_wait1:
Receive XIM_AUTH_REQUIRED
-> client_check
Receive <other> -> client_NGclient_check:
If no more auth needed, send XIM_AUTH_REPLY
-> client_wait2
If good auth data, send XIM_AUTH_NEXT
-> client_wait1
If bad auth data, send XIM_AUTH_NG
-> give up on this protocol
client_wait2:
Receive XIM_CONNECT_REPLY
-> connect Receive
XIM_AUTH_SETUP
-> client_more
Receive XIM_AUTH_NEXT
-> client_more
Receive XIM_AUTH_NG
-> give up on this protocol
Receive <other> -> client_NGclient_more:
Send XIM_AUTH_REQUIRED
-> client_wait2client_NG:
Send XIM_AUTH_NG
-> give up on this protocol
State transitions for the IM Server
init_status:
Use authorization function -> server_ask
Not use authorization function -> server_no_checkstart:
Receive XIM_CONNECT
-> start2
Receive <other> -> server_NGstart2:
If client_ask, send
XIM_AUTH_REQUIRED
-> server_wait1
If client_no_check and
server_ask, send
XIM_AUTH_SETUP
-> server_wait2
If client_no_check and
server_no_check, send
XIM_CONNECT_REPLY
-> connect
server_wait1:
Receive
XIM_AUTH_REPLY
-> server2
Receive
XIM_AUTH_NEXT
-> server_more
Receive <other> -> server_NGserver_more
Send
XIM_AUTH_REQUIRED
-> server_wait1server2
If server_ask, send
XIM_AUTH_SETUP
-> server_wait2
If server_no_check, send
XIM_CONNECT_REPLY
-> connect
server_wait2
Receive
XIM_AUTH_REQUIRED
-> server_check
Receive <other> -> server_NGserver_check
If no more auth data, send
XIM_CONNECT_REPLY
-> connect
If bad auth data, send
XIM_AUTH_NG
-> give up on this protocol
If good auth data, send
XIM_AUTH_NEXT
-> server_wait2server_NG
Send
XIM_AUTH_NG
-> give up on this protocol
XIM_DISCONNECT
message requests to shutdown the connection over a mutually-understood
virtual stream.
XIM_DISCONNECT (IM library -> IM Server)
XIM_DISCONNECT
is a synchronous request. The IM library should wait until it receives
either an
XIM_DISCONNECT_REPLY
packet or an XIM_ERROR packet.
XIM_DISCONNECT_REPLY (IM Server -> IM library)
XIM_OPEN
requests to establish a logical connection between the IM library and the IM
Server.
XIM_OPEN (IM library -> IM Server)
n STR locale name
p unused, p = Pad(n)
XIM_OPEN
is a synchronous request. The IM library should wait until receiving
either an XIM_OPEN_REPLY
packet or an XIM_ERROR packet.
XIM_OPEN_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 n byte length of IM attributes supported
n LISTofXIMATTR IM attributes supported
2 m byte length of IC attributes supported
2 CARD16 unused
m LISTofXICATTR IC attributes supported
XIM_OPEN_REPLY
message returns all supported IM and IC attributes in LISTofXIMATTR and
LISTofXICATTR. These IM and IC attribute IDs are used to reduce the amount
of data which must be transferred via the network. In addition, this
indicates to the IM library what kinds of IM/IC attributes can be used
in this session, and what types of data will be exchanged. This allows
the IM Server provider and application writer to support IM system
enhancements with new IM/IC attributes, without modifying Xlib.
The IC value for the separator of NestedList must be included in the
LISTofXICATTR.
XIM_CLOSE
message requests to shutdown the logical connection between the IM library
and the IM Server.
XIM_CLOSE (IM library -> IM Server)
2 CARD16 input-method-ID
2 unused
XIM_CLOSE
is a synchronous request. The IM library should wait until receiving
either an XIM_CLOSE_REPLY
packet or an XIM_ERROR packet.
XIM_CLOSE_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 unused
Event Flow Control
An IM Server must send
XIM_SET_EVENT_MASK
message to the IM library in order for events to be forwarded to the IM
Server, since the IM library initially doesn't forward any events to the
IM Server. In the protocol, the IM Server will specify masks of X events
to be forwarded and which need to be synchronized by the IM library.
XIM_SET_EVENT_MASK (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
4 EVENTMASK forward-event-mask (*1)
4 EVENTMASK synchronous-event-mask (*2)
(*1) Specify all the events to be forwarded to the IM Server by the IM library.
(*2) Specify the events to be forwarded with synchronous flag on by the IM library.
XIM_SET_EVENT_MASK
is an asynchronous request. The event masks are valid immediately after
they are set until changed by another
XIM_SET_EVENT_MASK
message. If input-context-ID is set to zero, the default value of the
input-method-ID will be changed to the event masks specified in the request.
That value will be used for the IC's which have no individual values.
Using the Dynamic Event Flow model, an IM Server sends
XIM_REGISTER_TRIGGERKEYS
message to the IM library before sending
XIM_OPEN_REPLY
message.
Or the IM library may suppose that the IM Server uses the Static Event Flow
model.
XIM_REGISTER_TRIGGERKEYS (IM Server -> IM library)
2 CARD16 input-method-ID
2 unused
4 n byte length of on-keys
n LISTofXIMTRIGGERKEY on-keys list
4 m byte length of off-keys
m LISTofXIMTRIGGERKEY off-keys list
XIM_REGISTER_TRIGGERKEYS
is an asynchronous request.
The IM Server notifys the IM library of on-keys and off-keys lists with
this message.
The IM library notifys the IM Server with
XIM_TRIGGER_NOTIFY
message that a key event matching either on-keys or off-keys has been occurred.
XIM_TRIGGER_NOTIFY (IM library -> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
4 CARD32 flag
#0 on-keys list
#1 off-keys list
4 CARD32 index of keys list
4 EVENTMASK client-select-event-mask (*1)
(*1) Specify the events currently selected by the IM library with XSelectInput.
XIM_TRIGGER_NOTIFY
is a synchronous request. The IM library should wait until receiving
either an XIM_TRIGGER_NOTIFY_REPLY
packet or an XIM_ERROR packet.
XIM_TRIGGER_NOTIFY_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
Encoding NegotiationXIM_ENCODING_NEGOTIATION
message requests to decide which encoding to be sent across the wire.
When the negotiation fails, the fallback default encoding is Portable
Character Encoding.
XIM_ENCODING_NEGOTIATION (IM library -> IM Server).sp 6p
2 CARD16 input-method-ID
2 n byte length of encodings listed by name
n LISTofSTR list of encodings supported in the IM library.
p unused, p = Pad(n)
2 m byte length of encodings listed by detailed data
2 unused
m LISTofENCODINGINFO list of encordings supported in the IM library
The IM Server must choose one encoding from the list sent by the IM library.
If index of the encording determined is -1 to indicate that the negotiation
is failed, the fallback default encoding is used.
The message must be issued after sending
XIM_OPEN message via XOpenIM().
The name of encoding may be registered with X Consortium.
XIM_ENCODING_NEGOTIATION
is a synchronous request. The IM library should wait until receiving
either an XIM_ENCODING_NEGOTIATION_REPLY
packet or an XIM_ERROR packet.
XIM_ENCODING_NEGOTIATION_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 category of the encoding determined.
#0 name
#1 detailed data
2 INT16 index of the encoding determinated.
2 unused
Query the supported extension protocol listXIM_QUERY_EXTENSION
message requests to query the IM extensions supported by the IM Server to
which the client is being connected.
XIM_QUERY_EXTENSION (IM library -> IM Server)
2 CARD16 input-method-ID
2 n byte length of extensions supported by the IM library
n LISTofSTR extensions supported by the IM library
p unused, p = Pad(n)
An example of a supported extension is FrontEnd.
The message must be issued after sending
XIM_OPEN message via XOpenIM().
If n is 0, the IM library queries the IM Server for all extensions.
If n is not 0, the IM library queries whether the IM Server supports the
contents specified in the list.
If a client uses an extension request without previously having issued a
XIM_QUERY_EXTENSION
message for that extension, the IM Server responds with a
BadProtocol
error. If the IM Server encounters a request with an unknown MAJOR-OPCODE
or MINOR-OPCODE, it responds with a
BadProtocol error.
XIM_QUERY_EXTENSION
is a synchronous request. The IM library should wait until receiving
either an XIM_QUERY_EXTENSION_REPLY
packet or an XIM_ERROR packet.
XIM_QUERY_EXTENSION_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 n byte length of extensions supported by both the IM library and the IM Server
n LISTofEXT list of extensions supported by both the IM library and the IM Server
XIM_QUERY_EXTENSION_REPLY
message returns the list of extensions supported by both the IM library and
the IM Server. If the list passed in
XIM_QUERY_EXTENSION
message is NULL, the IM Server returns the full list of extensions supported
by the IM Server. If the list is not NULL, the IM Server returns the
extensions in the list that are supported by the IM Server.
A zero-length string is not a valid extension name. The IM library should
disregard any zero-length strings that are returned in the extension list.
The IM library does not use the requests which are not supported by the IM
Server.
Setting IM ValuesXIM_SET_IM_VALUES
requests to set attributes to the IM.
XIM_SET_IM_VALUES (IM library -> IM Server)
2 CARD16 input-method-ID
2 n byte length of im-attribute
n LISTofXIMATTRIBUTE im-attributes
The im-attributes in
XIM_SET_IM_VALUES
message are specified as a LISTofXIMATTRIBUTE, specifying the attributes
to be set. Attributes other than the ones returned by
XIM_OPEN_REPLY
message should not be specified.
XIM_SET_IM_VALUES
is a synchronous request. The IM library should wait until receiving
either an
XIM_SET_IM_VALUES_REPLY
packet or an
XIM_ERROR
packet, because it must receive the error attribute if
XIM_ERROR message is returned.
XIM_SET_IM_VALUES_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 unused
XIM_SET_IM_VALUES_REPLY
message returns the input-method-ID to distinguish replies from multiple IMs.
Getting IM ValuesXIM_GET_IM_VALUES
requests to query IM values supported by the IM Server currently being
connected.
XIM_GET_IM_VALUES (IM library -> IM Server)
2 CARD16 input-method-ID
2 n byte length of im-attribute-id
n LISTofCARD16 im-attribute-id
p unused, p=Pad(n)
XIM_GET_IM_VALUES
is a synchronous request. The IM library should wait until it receives
either an
XIM_GET_IM_VALUES_REPLY
packet or an XIM_ERROR packet.
XIM_GET_IM_VALUES_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 n byte length of im-attributes returned
n LISTofXIMATTRIBUTE im-attributes returned
The IM Server returns IM values with
XIM_GET_IM_VALUES_REPLY
message. The order of the returned im-attribute values corresponds directly
to that of the list passed with the
XIM_GET_IM_VALUES message.
Creating an ICXIM_CREATE_IC message requests to create an IC.
XIM_CREATE_IC (IM library -> IM Server)
2 CARD16 input-method-ID
2 n byte length of ic-attributes
n LISTofXICATTRIBUTE ic-attributes
The input-context-id is specified by the IM Server to identify the client
(IC). (It is not specified by the client in
XIM_CREATE_IC
message.), and it should not be set to zero.
XIM_CREATE_IC
is a synchronous request which returns the input-context-ID.
The IM library should wait until it receives either an
XIM_CREATE_IC_REPLY
packet or an
XIM_ERROR
packet.
XIM_CREATE_IC_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
Destroying the ICXIM_DESTROY_IC
message requests to destroy the IC.
XIM_DESTROY_IC (IM library -> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
XIM_DESTROY_IC
is a synchronous request. The IM library should not free its resources
until it receives an
XIM_DESTROY_IC_REPLY
message because XIM_DESTROY_IC
message may result in Callback packets such as
XIM_PREEDIT_DRAW
and XIM_PREEDIT_DONE.
XIM_DESTROY_IC_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
Setting IC ValuesXIM_SET_IC_VALUES
messages requests to set attributes to the IC.
XIM_SET_IC_VALUES (IM library -> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
2 n byte length of ic-attributes
2 unused
n LISTofXICATTRIBUTE ic-attributes
The ic-attributes in
XIM_SET_IC_VALUES
message are specified as a LISTofXICATTRIBUTE, specifying the attributes
to be set. Attributes other than the ones returned by
XIM_OPEN_REPLY message should not be specified.
XIM_SET_IC_VALUES
is a synchronous request. The IM library should wait until receiving
either an XIM_SET_IC_VALUES_REPLY
packet or an XIM_ERROR
packet, because it must receive the error attribute if
XIM_ERROR message is returned.
XIM_SET_IC_VALUES_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
Getting IC ValuesXIM_GET_IC_VALUES
message requests to query IC values supported by the IM Server currently
being connected.
XIM_GET_IC_VALUES (IM library -> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
2 n byte length of ic-attribute-id
n LISTofCARD16 ic-attribute-id
p unused, p=Pad(2+n)
In LISTofCARD16, the appearance of the ic-attribute-id for the separator
of NestedList shows the end of the heading nested list.
XIM_GET_IC_VALUES
is a synchronous request and returns each attribute with its values to
show the correspondence. The IM library should wait until receiving
either an XIM_GET_IC_VALUES_REPLY
packet or an XIM_ERROR packet.
XIM_GET_IC_VALUES_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
2 n byte length of ic-attribute
2 unused
n LISTofXICATTRIBUTE ic-attribute
Setting IC FocusXIM_SET_IC_FOCUS
message requests to set the focus to the IC.
XIM_SET_IC_FOCUS (IM library -> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
XIM_SET_IC_FOCUS is an asynchronous request.
Unsetting IC FocusXIM_UNSET_IC_FOCUS
message requests to unset the focus to the focused IC.
XIM_UNSET_IC_FOCUS (IM library -> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
XIM_UNSET_IC_FOCUS
is an asynchronous request.
Filtering Events
Event filtering is mainly provided for BackEnd method to allow input method
to capture X events transparently to clients.
X Events are forwarded by
XIM_FORWARD_EVENT message.
This message can be operated both synchronously and asynchronously.
If the requester sets the synchronous flag, the receiver must send
XIM_SYNC_REPLY
message back to the requester when all the data processing is done.
Protocol flow of BackEnd model
With BackEnd method, the protocol flow can be classified into two
methods in terms of synchronization, depending on the synchronous-eventmask
of XIM_SET_EVENT_MASK
message. One can be called on-demand-synchronous method and another
can be called as full-synchronous method.
In on-demand-synchronous method, the IM library always receives
XIM_FORWARD_EVENT
or
XIM_COMMIT
message as a synchronous request. Also, the IM Server needs to synchronously
process the correspondent reply from the IM library and the following
XIM_FORWARD_EVENT
message sent from the IM library when any of the event causes the IM Server
to send
XIM_FORWARD_EVENT
or
XIM_COMMIT
message to the IM library, so that the input service is consistent. If the
IM library gets the control back from the application after receiving the
synchronous request, the IM library replies for the synchronous request before
processing any of the events. In this time, the IM Server blocks
XIM_FORWARD_EVENT
message which is sent by the IM library, and handles it after receiving the
reply. However, the IM Server handles the other protocols at any time.
In full-synchronous method, the IM library always sends
XIM_FORWARD_EVENT
message to the IM Server as a synchronous request. Therefore, the reply to it
from the IM Server will be put between the
XIM_FORWARD_EVENT message and its
XIM_SYNC_REPLY message. In case of sending
XIM_FORWARD_EVENT or
XIM_COMMIT
message, the IM Server should set the synchronous flag off. Because the
synchronization can be done by the following
XIM_SYNC_REPLY message.
Following chart shows one of the simplest protocol flow which only
deals with keyevents for preediting operation.
Sample Protocol Flow
Following chart shows one of the complex protocol flow, which deals
with multiple focus windows and button press event as well as keyevent,
and the focus is moved by the application triggered by both of keyevent
and button press event.
Sample Protocol Flow 2
XIM_FORWARD_EVENT (IM library <--> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
2 BITMASK16 flag
#0001 synchronous
#0002 request filtering (*1)
#0004 request lookupstring (*2)
2 CARD16 serial number
XEVENT X event
(*1) Indicate the receiver should filter events and possible preedit may be invoked.
(*2) Indicate the receiver should only do lookup string. The IM Server is expected
to just do a conversion of the key event to the best candidate. This bit may
affect the state of the preedit state (e.g. compose of dead key sequences).
XEVENT format is same as the X Protocol event format(xEvent).
As the value of xEvent's sequenceNumber is the bottom of 16 bit of XEvent's
xany.serial, the top of 16 bit is sent by serial number(INT16).
XIM_FORWARD_EVENT
message is used for forwarding the events from the IM library to the IM Server
in order for IM to be able to filter the event. On the other hand, this
message is also used for forwarding the events from the IM Server to the IM
library if the event forwarded from the IM library is not filtered.
The IM Server, which receives
XIM_FORWARD_EVENT
message without synchronous bit, should set synchronous bit.
If both "request event filtering" and "request lookupstring" flag are
set, then both filtering and lookup should be done for the same event.
Synchronizing with the IM ServerXIM_SYNC
message requests to synchronize the IM library and the IM Server.
XIM_SYNC (IM library <--> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
This synchronization can be started either on the IM library side or on the
IM Server side. The side which receives
XIM_SYNC
message should process all XIM requests before replying. The input-context-ID
is necessary to distinguish the IC with which the IM library and the IM
Server are synchronized.
XIM_SYNC_REPLY (IM Server <--> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
The side which receives
XIM_FORWARD_EVENT, XIM_COMMIT
or any other message with synchronous bit, should process all XIM request
before replying, and send
XIM_SYNC_REPLY
message as the reply to the previous message.
Sending a committed string
When the IM Server commits a string, the IM Server sends either the committed
string or list of KeySym, or both, by
XIM_COMMIT
message.
XIM_COMMIT (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
2 BITMASK16 flag
#0001 synchronous
#0002 XLookupChars
#0004 XLookupKeySym
#0006 XLookupBoth = XLookupChars | XLookupKeySym
If flag is XLookupKeySym, the arguments continue as follows:
2 unused
4 KEYSYM KeySym
If flag is XLookupChars, the arguments continue as follows
2 m byte length of committed string
m LISTofBYTE committed string
p unused, p = Pad(m)
If flag is XLookupBoth, the arguments continue as follows
2 unused
4 KEYSYM KeySym
2 n byte length of committed string
n LISTofBYTE committed string
p unused, p = Pad(2+n)
The IM Server which receives
XIM_COMMIT
message without synchronous bit should set synchronous bit.
Reset ICXIM_RESET_IC
message requests to reset the status of IC in the IM Server.
XIM_RESET_IC (IM library -> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
XIM_RESET_IC
is a synchronous request. The IM library should wait until receiving either an
XIM_RESET_IC_REPLY packet or an
XIM_ERROR packet.
XIM_RESET_IC_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
2 n byte length of preedit string
n LISTofBYTE preedit string
p unused, p = Pad(2+n)
XIM_RESET_IC_REPLY
message returns the input-context-ID to distinguish replies from multiple ICs.
Callbacks
If XIMStyle has XIMPreeditArea or XIMStatusArea set, XIMGeometryCallback
may be used, and if XIMPreeditCallback and/or XIMStatusCallback are set,
corresponding callbacks may be used.
Any callback request may be sent from an IM Server to an IM client
asynchronously in response to any request previously sent by the IM client
to the IM Server.
When an IM Server needs to send a callback request synchronously with
the request previously sent by an IM client, the IM Server sends it
before replying to the previous request.
Negotiating geometry
The IM Server sends
XIM_GEOMETRY
message to start geometry negotiation, if XIMStyle has XIMPreeditArea or
XIMStatusArea set.
XIM_GEOMETRY (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
There is always a single Focus Window, even if some input fields have only
one IC.
Converting a string
XIM_STR_CONVERSION (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
2 CARD16 XIMStringConversionPosition
2 unused
4 CARD32 XIMCaretDirection
#0 XIMForwardChar
#1 XIMBackwardChar
#2 XIMForwardWord
#3 XIMBackwardWord
#4 XIMCaretUp
#5 XIMCaretDown
#6 XIMNextLine
#7 XIMCPreviousLine
#8 XIMLineStart
#9 XIMLineEnd
#10 XIMAbsolutePosition
#11 XIMDontChange
2 CARD16 factor
2 CARD16 XIMStringConversionOperation
#0001 XIMStringConversionSubstitution
#0002 XIMStringConversionRetrieval
2 INT16 byte length to multiply the XIMStringConversionType
XIM_STR_CONVERSION
message may be used to start the string conversion from the IM Server.
XIM_STR_CONVERSION_REPLY (IM library -> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
4 CARD32 XIMStringConversionFeedback
XIMSTRCONVTEXT XIMStringConversionText
XIM_STR_CONVERSION_REPLY
message returns the string to be converted and the feedback information array.
Preedit Callbacks
The IM Server sends
XIM_PREEDIT_START
message to call the XIMPreeditStartCallback function.
XIM_PREEDIT_START (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
The reply to this message must be sent synchronously. The reply forwards
the return value from the callback function to the IM Server.
XIM_PREEDIT_START_REPLY (IM library -> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
4 INT32 return value
XIM_PREEDIT_START_REPLY
message returns the input-context-ID to distinguish replies from multiple
IC's. The return value contains the return value of the function
XIMPreeditStartCallback.
The IM Server sends
XIM_PREEDIT_DRAW
message to call the XIMPreeditDrawCallback function.
XIM_PREEDIT_DRAW (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
4 INT32 caret
4 INT32 chg_first
4 INT32 chg_length
4 BITMASK32 status
#x0000001 no string
#x0000002 no feedback
2 n length of preedit string
n STRING8 preedit string
p unused, p = Pad(2+n)
2 m byte length of feedback array
2 unused
m LISTofXIMFEEDBACK feedback array
The fields "caret", "chg_first" and "chg_length" correspond to the
fields of XIMPreeditDrawCallbackStruct.
When the "no string" bit of the status field is set, the text field of
XIMPreeditDrawCallbackStruct is NULL.
When the "no feedback" bit of the status field is set, the text feedback
field of XIMPreeditDrawCallbackStruct is NULL.
When the above bits are not set, "preedit string" contains the preedit
string to be displayed, and the feedback array contains feedback information.
The IM Server sends
XIM_PREEDIT_CARET
message to call the PreeditCaretCallback function.
XIM_PREEDIT_CARET (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
4 INT32 position
4 CARD32 direction
#0 XIMForwardChar
#1 XIMBackwardChar
#2 XIMForwardWord
#3 XIMBackwardWord
#4 XIMCaretUp
#5 XIMCaretDown
#6 XIMNextLine
#7 XIMCPreviousLine
#8 XIMLineStart
#9 XIMLineEnd
#10 XIMAbsolutePosition
#11 XIMDontChange
4 CARD32 style
#0 XIMInvisible
#1 XIMCPrimary
#2 XIMSecondary
Each entry corresponds to a field of XIMPreeditCaretCallbackStruct.
Since this callback sets the caret position, its reply must be sent
synchronously.
XIM_PREEDIT_CARET_REPLY (IM library -> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
4 CARD32 position
The position is the value returned by the callback function after it
has been called.
The IM Server sends
XIM_PREEDIT_DONE
message to call the XIMPreeditDoneCallback function.
XIM_PREEDIT_DONE (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
Preedit state notify
XIM_PREEDITSTATE (IM Server -> IM Library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
4 BITMASK32 XIMPreeditState
#x0000000 XIMPreeditUnknown
#x0000001 XIMPreeditEnable
#x0000002 XIMPreeditDisable
XIM_PREEDITSTATE
message is used to call the XIMPreeditStateNotifyCallback function.
Status Callbacks
The IM Server sends
XIM_STATUS_START
message to call the XIMStatusStartCallback function.
XIM_STATUS_START (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
The IM Server sends
XIM_STATUS_DRAW
message to call the XIMStatusDrawCallback function.
XIM_STATUS_DRAW (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
4 CARD32 type
#0 XIMTextType
#1 XIMBitmapType
If type is XIMTextType, the arguments continue as follows.
4 BITMASK32 status
#x0000001 no string
#x0000002 no feedback
2 n length of status string
n STRING8 status string
p unused, p = Pad(2+n)
2 m byte length of feedback array
2 unused
m LISTofXIMFEEDBACK feedback array
If type is XIMBitmapType, the arguments continue as follows.
4 PIXMAP pixmap data
The field "type" corresponds to the field in XIMStatusDrawCallbackStruct.
The IM Server sends
XIM_STATUS_DONE
message to call the XIMStatusDoneCallback function.
XIM_STATUS_DONE (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
Acknowledgements
This document represents the culmination of several years of debate and
experiments done under the auspices of the MIT X Consortium i18n working
group. Although this was a group effort, the author remains responsible
for any errors or omissions.
We would like to thank to all members of this group.
And we would like to make special thanks to the following people
(in alphabetical order) for their participation in the IM Protocol
design,
Hector Chan, Takashi Fujiwara, Yoshio Horiuchi, Makoto Inada,
Hiromu Inukai, Mickael Kung, Seiji Kuwari, Franky Ling, Hiroyuki Machida,
Hiroyuki Miyamoto, Frank Rojas, Bob Scheifler, Makiko Shimamura,
Shoji Sugiyama, Hidetoshi Tajima, Masaki Takeuchi, Makoto Wakamatsu,
Masaki Wakao, Nobuyuki Tanaka, Shigeru Yamada, Katsuhisa Yano, Jinsoo Yoon.
ReferencesX Window System Protocol Version 11Robert W.ScheiflerXlib - C Language X Interface"Robert W.ScheiflerCommon Extensions
Extension opcodes and packet names (e.g.
XIM_EXT_SET_EVENT_MASK
) for additional extensions may be registered with X Consortium.
The following is a commonly well-known extended packet.
(1) Extension to manipulate the event handling\fP
XIM_EXT_SET_EVENT_MASK
message specifies the set of event masks that the IM library should manipulate.
XIM_EXT_SET_EVENT_MASK (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
4 EVENTMASK filter-event-mask (*1)
4 EVENTMASK intercept-event-mask (*2)
4 EVENTMASK select-event-mask (*3)
4 EVENTMASK forward-event-mask (*4)
4 EVENTMASK synchronous-event-mask (*5)
(*1) Specify the events to be neglected by the IM library via XFilterEvent.
(*2) Specify the events to be deselected by the IM library with XSelectInput.
(*3) Specify the events to be selected by the IM library with XSelectInput.
(*4) Specify all the events to be forwarded to the IM Server by the IM library.
(*5) Specify the events to be forwarded with synchronous flag on by the IM library.
The IM library must reply
XIM_SYNC_REPLY
message to the IM Server. This request is valid after the ic is created.
(2) Extension for improvement of performance.
The following requests may be used for improvement of performance.
XIM_EXT_FORWARD_KEYEVENT
message may be used instead of
XIM_FORWARD_EVENT
message.
XIM_EXT_FORWARD_KEYEVENT (IM Server <--> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
2 BITMASK16 flag
#0001 synchronous
2 CARD16 sequence number
1 BYTE xEvent.u.u.type
1 BYTE keycode
2 CARD16 state
4 CARD32 time
4 CARD32 window
XIM_EXT_MOVE
message may be used to change the spot location instead of
XIM_SET_IC_VALUES
message.
It is effective only if the client specified XIMPreeditPosition.
XIM_EXT_MOVE (IM library -> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
2 INT16 X
2 INT16 Y
XIM_EXT_MOVE
message is a asynchronous request.
Transport List
The list of transport specific IM Server address format registered
The following format represents the ATOM contained in
XIM_SERVERS
property and the string returned from the request converting
selection target LOCALES and TRANSPORT.
"{category=[value,...]}..."
The following categories are currently registered.
server;: IM Server name (used for XIM_SERVERS)
locale;: XPG4 locale name (LOCALES)
transport;: transport-specific name (TRANSPORT)
The preregistered formats for transport-specific names are as follows:
TCP/IP Names
The following syntax should be used for system internal domain names:
<local name> ::= "local/"<hostname>":"<pathname>
Where <pathname> is a path name of socket address.
IM Server's name should be set to <pathname> to run multiple IM Server
at the same time
The following syntax should be used for Internet domain names:
<TCP name> ::= "tcp/"<hostname>":"<ipportnumber>
where <hostname> is either symbolic (such as expo.lcs.mit.edu) or
numeric decimal (such as 18.30.0.212). The <ipportnumber> is the
port on which the IM Server is listening for connections.
For example:
tcp/expo.lcs.mit.edu:8012
tcp/18.30.0.212:7890
DECnet Names
The following syntax should be used for DECnet names:
<DECnet name> ::= "decnet/"<nodename>"::IMSERVER$"<objname>
where <nodename> is either
symbolic (such as SRVNOD) or the numeric
decimal form of the DECnet address (such as 44.70).
The <objname>
is normal, case-insensitive DECnet object name. For example:
DECNET/SRVNOD::IMSERVER$DEFAULT
decnet/44.70::IMSERVER$other
X Names
The following syntax should be used for X names:
<X name> ::= "X/"
If a given category has multiple values, the value is evaluated in order of
setting.
Protocol NumberMajor Protocol number
XIM_CONNECT #001
XIM_CONNECT_REPLY #002
XIM_DISCONNECT #003
XIM_DISCONNECT_REPLY #004
XIM_AUTH_REQUIRED #010
XIM_AUTH_REPLY #011
XIM_AUTH_NEXT #012
XIM_AUTH_SETUP #013
XIM_AUTH_NG #014
XIM_ERROR #020
XIM_OPEN #030
XIM_OPEN_REPLY #031
XIM_CLOSE #032
XIM_CLOSE_REPLY #033
XIM_REGISTER_TRIGGERKEYS #034
XIM_TRIGGER_NOTIFY #035
XIM_TRIGGER_NOTIFY_REPLY #036
XIM_SET_EVENT_MASK #037
XIM_ENCODING_NEGOTIATION #038
XIM_ENCODING_NEGOTIATION_REPLY #039
XIM_QUERY_EXTENSION #040
XIM_QUERY_EXTENSION_REPLY #041
XIM_SET_IM_VALUES #042
XIM_SET_IM_VALUES_REPLY #043
XIM_GET_IM_VALUES #044
XIM_GET_IM_VALUES_REPLY #045
XIM_CREATE_IC #050
XIM_CREATE_IC_REPLY #051
XIM_DESTROY_IC #052
XIM_DESTROY_IC_REPLY #053
XIM_SET_IC_VALUES #054
XIM_SET_IC_VALUES_REPLY #055
XIM_GET_IC_VALUES #056
XIM_GET_IC_VALUES_REPLY #057
XIM_SET_IC_FOCUS #058
XIM_UNSET_IC_FOCUS #059
XIM_FORWARD_EVENT #060
XIM_SYNC #061
XIM_SYNC_REPLY #062
XIM_COMMIT #063
XIM_RESET_IC #064
XIM_RESET_IC_REPLY #065
XIM_GEOMETRY #070
XIM_STR_CONVERSION #071
XIM_STR_CONVERSION_REPLY #072
XIM_PREEDIT_START #073
XIM_PREEDIT_START_REPLY #074
XIM_PREEDIT_DRAW #075
XIM_PREEDIT_CARET #076
XIM_PREEDIT_CARET_REPLY #077
XIM_PREEDIT_DONE #078
XIM_STATUS_START #079
XIM_STATUS_DRAW #080
XIM_STATUS_DONE #081
XIM_PREEDITSTATE #082
(*) The IM Server's extension protocol number should be more than #128.
Implementation Tips
(1) FrontEnd Method
FrontEnd method is recognized as a performance acceleration by the
trade off of the variety of the reliability.
In order to use the FrontEnd method, the IM library must query the IM
Server to see if the FrontEnd extension is available. The query is
made by using the
XIM_QUERY_EXTENSION
message. The IM Server may send
XIM_EXT_SET_EVENT_MASK
message with intercept-event-mask, forward-event-mask, and
synchronous-event-mask values set after replying
XIM_QUERY_EXTENSION_REPLY
message.
FrontEnd method can be implemented in a couple of ways depending on
how the IM Server utilize
XIM_EXT_SET_EVENT_MASK
message.
One approach is to update both of the input mask and the filter-event-mask
depending on the preeidting state. The sample protocol sequence using the
static event flow is as follows:
The flow of events
To pursuit a maximum performance regardless of the preediting mode,
the IM Server may use the dynamic event flow with the following
sample protocol sequence.
The flow of events
This method can reduce the XIM protocol traffic dramatically
by updating intercept-event-mask and select-event-mask accordingly.
The tradeoff of this performance improvement is that the key
events may be lost or disordered in some particular situation, such as
when the user types the keyboard in following sequence really fast:
<preediting on key>"some strings"<preediting off
key>"another string"
Since this method requires the input mask updates to the both the IM Server
and Xlib when turning on and off the preediting, and there is a time lag
till the requests take effect when two client issues the input mask updates
simultaneously.
Another approach of the FrontEnd method is to update the filter-event-mask
depending on the preediting state and not to update the input mask.
The IM Server must register both of the preediting on key list and off key
list by
XIM_REGISTER_TRIGGERKEYS
message.
In this method, Both the IM Server and the IM client select the same
events on the same client's window, so that the events are delivered
to both of the IM Server and the client. The preediting on and off
states are expressed by whether the key events are filtered or not.
The sample protocol sequence are as follows:
<<Using static event flow>>
The flow of events
<<Using the dynamic event flow>>
The flow of events
This method does not have the problem of the time lag when going across
the preediting on and off mode, however, the amount of the performance
acceleration is not as good as the method described above.
In general, the FrontEnd method requires some synchronization to some
of the X protocols, such as the ChangeWindowAttribute protocol for the
event mask change or the GrabKey protocol, since it relies on the X's
principal event dispatching mechanism. Any X protocol bindings do not
consider the synchronization might cause some mis-synchronization
between the IM clients and the IM Server.
(2) Transport Layer
The Xlib XIM implementation is layered into three functions, a protocol
layer, an interface layer and a transport layer. The purpose of this
layering is to make the protocol independent of transport implementation.
Each function of these layers are:
The protocol layer
implements overall function of XIM and calls the interface layer
functions when it needs to communicate to IM Server.
The interface layer
separates the implementation of the transport layer from the protocol
layer, in other words, it provides implementation independent hook for
the transport layer functions.
The transport layer
handles actual data communication with IM Server. It is done by a set
of several functions named transporters.
The interface layer and the transport layer make various communication
channels usable such as X Protocol, TCP/IP, DECnet or STREAM.
The following is a sample implementation for the transporter using
the X connection.
Refer to "xtrans" for the transporter using Socket Transport.
At the beginning of the X Transport connection for the XIM transport
mechanism, two different windows must be created either in an Xlib XIM
or in an IM Server, with which the Xlib and the IM Server exchange the
XIM transports by using the ClientMessage events and Window Properties.
In the following, the window created by the Xlib is referred as the
"client communication window", and on the other hand, the window created
by the IM Server is referred as the "IMS communication window".
Connection
In order to establish a connection, a communication window is created.
A ClientMessage in the following event's format is sent to the owner
window of XIM_SERVER selection, which the IM Server has created.
Refer to "The Input Method Protocol" for the XIM_SERVER atom.
The ClientMessage sent to the IMS window.Structure MemberContentsinttypeClientMessageu_longserialSet by the X Window SystemBoolsend_eventSet by the X Window SystemDisplay*displayThe display to which connectsWindowwindowIMS Window IDAtommessage_typeXInternAtom(display, "_XIM_XCONNECT", False)intformat32longdata.l[0]client communication window IDlongdata.l[1]client-major-transport-version (*1)longdata.l[2]client-major-transport-version (*1)
In order to establish the connection (to notify the IM Server communication
window), the IM Server sends a ClientMessage in the following event's
format to the client communication window.
The ClientMessage sent by the IM Server.Structure MemberContentsinttypeClientMessageu_longserialSet by the X Window SystemBoolsend_eventSet by the X Window SystemDisplay*displayThe display to which connectsWindowwindowclient communication window IDAtommessage_typeXInternAtom(display, "_XIM_XCONNECT", False)intformat32longdata.l[0]IMS communication window IDlongdata.l[1]server-major-transport-version (*1)longdata.l[2]server-minor-transport-version (*1)longdata.l[3]dividing size between ClientMessage and Property (*2)
(*1) major/minor-transport-version
The read/write method is decided by the combination of
major/minor-transport-version, as follows:
The read/write method and the major/minor-transport-versionTransport-versionread/writemajorminor00only-CM & Property-with-CM1only-CM & multi-CM2only-CM & multi-CM & Property-with-CM10PropertyNotify20only-CM & PropertyNotify1only-CM & multi-CM & PropertyNotify
only-CM : data is sent via a ClientMessage
multi-CM : data is sent via multiple ClientMessages
Property-with-CM : data is written in Property, and its Atom
is send via ClientMessage
PropertyNotify : data is written in Property, and its Atom
is send via PropertyNotify
The method to decide major/minor-transport-version is as follows:
The client sends 0 as major/minor-transport-version to the IM Server.
The client must support all methods in Table D-3.
The client may send another number as major/minor-transport-version to
use other method than the above in the future.
The IM Server sends its major/minor-transport-version number to
the client. The client sends data using the method specified by the
IM Server.
If major/minor-transport-version number is not available, it is regarded
as 0.
(*2) dividing size between ClientMessage and Property
If data is sent via both of multi-CM and Property, specify the dividing
size between ClientMessage and Property. The data, which is smaller than
this size, is sent via multi-CM (or only-CM), and the data, which is
lager than this size, is sent via Property.
read/write
The data is transferred via either ClientMessage or Window Property in
the X Window System.
Format for the data from the Client to the IM Server
ClientMessage
If data is sent via ClientMessage event, the format is as follows:
The ClientMessage event's format (first or middle)Structure MemberContentsinttypeClientMessageu_longserialSet by the X Window SystemBoolsend_eventSet by the X Window SystemDisplay*displayThe display to which connectsWindowwindowIMS communication window IDAtommessage_typeXInternAtom(display, "_XIM_MOREDATA", False)intformat8chardata.b[20](read/write DATA : 20 byte)
The ClientMessage event's format (only or last)Structure MemberContentsinttypeClientMessageu_longserialSet by the X Window SystemBoolsend_eventSet by the X Window SystemDisplay*displayThe display to which connectsWindowwindowIMS communication window IDAtommessage_typeXInternAtom(display, "_XIM_PROTOCOL", False)intformat8chardata.b[20](read/write DATA : MAX 20 byte) (*1)
(*1) If the data is smaller than 20 byte, all data other than available data
must be 0.
Property
In the case of large data, data will be sent via the Window Property
for the efficiency. There are the following two methods to notify
Property, and transport-version is decided which method is used.
The XChangeProperty function is used to store data in the client
communication window, and Atom of the stored data is notified to the
IM Server via ClientMessage event.
The XChangeProperty function is used to store data in the client
communication window, and Atom of the stored data is notified to the
IM Server via PropertyNotify event.
The arguments of the XChangeProperty are as follows:
The XChangeProperty event's formatArgumentContentsDisplay*displayThe display to which connectsWindowwindowIMS communication window IDAtompropertyread/write property Atom (*1)AtomtypeXA_STRING intformat8intmodePropModeAppendu_char*dataread/write DATAintnelementslength of DATA
The read/write property ATOM allocates the following strings by
XInternAtom.
"_clientXXX"
The client changes the property with the mode of PropModeAppend and
the IM Server will read it with the delete mode i.e. (delete = True).
If Atom is notified via ClientMessage event, the format of the ClientMessage
is as follows:
The ClientMessage event's format to send Atom of propertyStructure MembersContentsinttypeClientMessageu_longserialSet by the X Window SystemBoolsend_eventSet by the X Window SystemDisplay*displayThe display to which connectsWindowwindowIMS communication window IDAtommessage_typeXInternAtom(display, "_XIM_PROTOCOL", False)intformat32longdata.l[0]length of read/write property Atomlongdata.l[1]read/write property Atom
Format for the data from the IM Server to the Client
ClientMessage
The format of the ClientMessage is as follows:
The ClientMessage event's format (first or middle)Structure MembersContentsinttypeClientMessageu_longserialSet by the X Window SystemBoolsend_event Set by the X Window SystemDisplay*displayThe display to which connectsWindowwindowclient communication window IDAtommessage_typeXInternAtom(display, "_XIM_MOREDATA", False)intformat8chardata.b[20](read/write DATA : 20 byte)
The ClientMessage event's format (only or last)Structure MembersContentsinttypeClientMessageu_longserialSet by the X Window SystemBoolsend_event Set by the X Window SystemDisplay*displayThe display to which connectsWindowwindowclient communication window IDAtommessage_typeXInternAtom(display, "_XIM_PROTOCOL", False)intformat8chardata.b[20](read/write DATA : MAX 20 byte) (*1)
(*1) If the data size is smaller than 20 bytes, all data other than available
data must be 0.
Property
In the case of large data, data will be sent via the Window Property
for the efficiency. There are the following two methods to notify
Property, and transport-version is decided which method is used.
The XChangeProperty function is used to store data in the IMS
communication window, and Atom of the property is sent via the
ClientMessage event.
The XChangeProperty function is used to store data in the IMS
communication window, and Atom of the property is sent via
PropertyNotify event.
The arguments of the XChangeProperty are as follows:
The XChangeProperty event's formatArgumentContentsDisplay*displayThe display which to connectsWindowwindowclient communication window IDAtompropertyread/write property Atom (*1)AtomtypeXA_STRINGintformat8intmodePropModeAppendu_char*dataread/write DATAintnelementslength of DATA
(*1) The read/write property ATOM allocates some strings, which are not
allocated by the client, by XInternAtom.
The IM Server changes the property with the mode of PropModeAppend and
the client reads it with the delete mode, i.e. (delete = True).
If Atom is notified via ClientMessage event, the format of the ClientMessage
is as follows:
The ClientMessage event's format to send Atom of propertyStructure MemberContentsinttypeClientMessage u_longserialSet by the X Window System Boolsend_eventSet by the X Window System Display*displayThe display to which connects Windowwindowclient communication window ID Atommessage_typeXInternAtom(display, "_XIM_PROTOCOL", False)intformat32 longdata.l[0]length of read/write property ATOM longdata.l[1]read/write property ATOM
Closing Connection
If the client disconnect with the IM Server, shutdown function should
free the communication window properties and etc..
ra>
If Atom is notified via ClientMessage event, the format of the ClientMessage
is as follows: