Blame man/XChangeKeyboardMapping.man

Packit 5bd3a9
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
Packit 5bd3a9
.\"
Packit 5bd3a9
.\" Permission is hereby granted, free of charge, to any person obtaining
Packit 5bd3a9
.\" a copy of this software and associated documentation files (the
Packit 5bd3a9
.\" "Software"), to deal in the Software without restriction, including
Packit 5bd3a9
.\" without limitation the rights to use, copy, modify, merge, publish,
Packit 5bd3a9
.\" distribute, sublicense, and/or sell copies of the Software, and to
Packit 5bd3a9
.\" permit persons to whom the Software is furnished to do so, subject to
Packit 5bd3a9
.\" the following conditions:
Packit 5bd3a9
.\"
Packit 5bd3a9
.\" The above copyright notice and this permission notice shall be included
Packit 5bd3a9
.\" in all copies or substantial portions of the Software.
Packit 5bd3a9
.\"
Packit 5bd3a9
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
Packit 5bd3a9
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
Packit 5bd3a9
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
Packit 5bd3a9
.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
Packit 5bd3a9
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
Packit 5bd3a9
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
Packit 5bd3a9
.\" OTHER DEALINGS IN THE SOFTWARE.
Packit 5bd3a9
.\"
Packit 5bd3a9
.\" Except as contained in this notice, the name of the X Consortium shall
Packit 5bd3a9
.\" not be used in advertising or otherwise to promote the sale, use or
Packit 5bd3a9
.\" other dealings in this Software without prior written authorization
Packit 5bd3a9
.\" from the X Consortium.
Packit 5bd3a9
.\"
Packit 5bd3a9
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
Packit 5bd3a9
.\" Digital Equipment Corporation
Packit 5bd3a9
.\"
Packit 5bd3a9
.\" Portions Copyright \(co 1990, 1991 by
Packit 5bd3a9
.\" Tektronix, Inc.
Packit 5bd3a9
.\"
Packit 5bd3a9
.\" Permission to use, copy, modify and distribute this documentation for
Packit 5bd3a9
.\" any purpose and without fee is hereby granted, provided that the above
Packit 5bd3a9
.\" copyright notice appears in all copies and that both that copyright notice
Packit 5bd3a9
.\" and this permission notice appear in all copies, and that the names of
Packit 5bd3a9
.\" Digital and Tektronix not be used in in advertising or publicity pertaining
Packit 5bd3a9
.\" to this documentation without specific, written prior permission.
Packit 5bd3a9
.\" Digital and Tektronix makes no representations about the suitability
Packit 5bd3a9
.\" of this documentation for any purpose.
Packit 5bd3a9
.\" It is provided ``as is'' without express or implied warranty.
Packit 5bd3a9
.\" 
Packit 5bd3a9
.\"
Packit 5bd3a9
.ds xT X Toolkit Intrinsics \- C Language Interface
Packit 5bd3a9
.ds xW Athena X Widgets \- C Language X Toolkit Interface
Packit 5bd3a9
.ds xL Xlib \- C Language X Interface
Packit 5bd3a9
.ds xC Inter-Client Communication Conventions Manual
Packit 5bd3a9
.na
Packit 5bd3a9
.de Ds
Packit 5bd3a9
.nf
Packit 5bd3a9
.\\$1D \\$2 \\$1
Packit 5bd3a9
.ft CW
Packit 5bd3a9
.\".ps \\n(PS
Packit 5bd3a9
.\".if \\n(VS>=40 .vs \\n(VSu
Packit 5bd3a9
.\".if \\n(VS<=39 .vs \\n(VSp
Packit 5bd3a9
..
Packit 5bd3a9
.de De
Packit 5bd3a9
.ce 0
Packit 5bd3a9
.if \\n(BD .DF
Packit 5bd3a9
.nr BD 0
Packit 5bd3a9
.in \\n(OIu
Packit 5bd3a9
.if \\n(TM .ls 2
Packit 5bd3a9
.sp \\n(DDu
Packit 5bd3a9
.fi
Packit 5bd3a9
..
Packit 5bd3a9
.de IN		\" send an index entry to the stderr
Packit 5bd3a9
..
Packit 5bd3a9
.de Pn
Packit 5bd3a9
.ie t \\$1\fB\^\\$2\^\fR\\$3
Packit 5bd3a9
.el \\$1\fI\^\\$2\^\fP\\$3
Packit 5bd3a9
..
Packit 5bd3a9
.de ZN
Packit 5bd3a9
.ie t \fB\^\\$1\^\fR\\$2
Packit 5bd3a9
.el \fI\^\\$1\^\fP\\$2
Packit 5bd3a9
..
Packit 5bd3a9
.de hN
Packit 5bd3a9
.ie t <\fB\\$1\fR>\\$2
Packit 5bd3a9
.el <\fI\\$1\fP>\\$2
Packit 5bd3a9
..
Packit 5bd3a9
.ny0
Packit 5bd3a9
.TH XChangeKeyboardMapping __libmansuffix__ __xorgversion__ "XLIB FUNCTIONS"
Packit 5bd3a9
.SH NAME
Packit 5bd3a9
XChangeKeyboardMapping, XGetKeyboardMapping, XDisplayKeycodes, XSetModifierMapping, XGetModifierMapping, XNewModifiermap, XInsertModifiermapEntry, XDeleteModifiermapEntry, XFreeModifiermap, XModifierKeymap \- manipulate keyboard encoding and keyboard encoding structure
Packit 5bd3a9
.SH SYNTAX
Packit 5bd3a9
.HP
Packit 5bd3a9
int XChangeKeyboardMapping(\^Display *\fIdisplay\fP, int \fIfirst_keycode\fP,
Packit 5bd3a9
int \fIkeysyms_per_keycode\fP, KeySym *\fIkeysyms\fP, int \fInum_codes\fP\^); 
Packit 5bd3a9
.HP
Packit 5bd3a9
KeySym *XGetKeyboardMapping(\^Display *\fIdisplay\fP, KeyCode
Packit 5bd3a9
\fIfirst_keycode\fP, int \fIkeycode_count\fP, int
Packit 5bd3a9
*\fIkeysyms_per_keycode_return\fP\^); 
Packit 5bd3a9
.HP
Packit 5bd3a9
int XDisplayKeycodes\^(\^Display *\fIdisplay\fP\^, int
Packit 5bd3a9
*\fImin_keycodes_return\fP\^, int *\fImax_keycodes_return\fP\^); 
Packit 5bd3a9
.HP
Packit 5bd3a9
int XSetModifierMapping(\^Display *\fIdisplay\fP, XModifierKeymap
Packit 5bd3a9
*\fImodmap\fP\^); 
Packit 5bd3a9
.HP
Packit 5bd3a9
XModifierKeymap *XGetModifierMapping(\^Display *\fIdisplay\fP\^); 
Packit 5bd3a9
.HP
Packit 5bd3a9
XModifierKeymap *XNewModifiermap(\^int \fImax_keys_per_mod\fP\^); 
Packit 5bd3a9
.HP
Packit 5bd3a9
XModifierKeymap *XInsertModifiermapEntry\^(\^XModifierKeymap *\fImodmap\fP,
Packit 5bd3a9
KeyCode \fIkeycode_entry\fP, int \fImodifier\fP\^); 
Packit 5bd3a9
.HP
Packit 5bd3a9
XModifierKeymap *XDeleteModifiermapEntry\^(\^XModifierKeymap *\fImodmap\fP,
Packit 5bd3a9
KeyCode \fIkeycode_entry\fP, int \fImodifier\fP\^); 
Packit 5bd3a9
.HP
Packit 5bd3a9
int XFreeModifiermap(\^XModifierKeymap *\fImodmap\fP\^); 
Packit 5bd3a9
.SH ARGUMENTS
Packit 5bd3a9
.IP \fIdisplay\fP 1i
Packit 5bd3a9
Specifies the connection to the X server.
Packit 5bd3a9
.ds Kc changed or returned
Packit 5bd3a9
.IP \fIfirst_keycode\fP 1i
Packit 5bd3a9
Specifies the first KeyCode that is to be \*(Kc.
Packit 5bd3a9
.IP \fIkeycode_count\fP 1i
Packit 5bd3a9
Specifies the number of KeyCodes that are to be returned.
Packit 5bd3a9
.IP \fIkeycode_entry\fP 1i
Packit 5bd3a9
Specifies the KeyCode. 
Packit 5bd3a9
.IP \fIkeysyms\fP 1i
Packit 5bd3a9
Specifies an array of KeySyms.
Packit 5bd3a9
.IP \fIkeysyms_per_keycode\fP 1i
Packit 5bd3a9
Specifies the number of KeySyms per KeyCode.
Packit 5bd3a9
.IP \fIkeysyms_per_keycode_return\fP 1i
Packit 5bd3a9
Returns the number of KeySyms per KeyCode.
Packit 5bd3a9
.IP \fImax_keys_per_mod\fP 1i
Packit 5bd3a9
Specifies the number of KeyCode entries preallocated to the modifiers
Packit 5bd3a9
in the map.
Packit 5bd3a9
.IP \fImax_keycodes_return\fP 1i
Packit 5bd3a9
Returns the maximum number of KeyCodes.
Packit 5bd3a9
.IP \fImin_keycodes_return\fP 1i
Packit 5bd3a9
Returns the minimum number of KeyCodes.
Packit 5bd3a9
.IP \fImodifier\fP 1i
Packit 5bd3a9
Specifies the modifier.
Packit 5bd3a9
.IP \fImodmap\fP 1i
Packit 5bd3a9
Specifies the 
Packit 5bd3a9
.ZN XModifierKeymap
Packit 5bd3a9
structure.
Packit 5bd3a9
.IP \fInum_codes\fP 1i
Packit 5bd3a9
Specifies the number of KeyCodes that are to be changed.
Packit 5bd3a9
.SH DESCRIPTION
Packit 5bd3a9
The
Packit 5bd3a9
.ZN XChangeKeyboardMapping
Packit 5bd3a9
function defines the symbols for the specified number of KeyCodes
Packit 5bd3a9
starting with first_keycode.
Packit 5bd3a9
The symbols for KeyCodes outside this range remain unchanged.  
Packit 5bd3a9
The number of elements in keysyms must be:
Packit 5bd3a9
.LP
Packit 5bd3a9
.Ds
Packit 5bd3a9
num_codes * keysyms_per_keycode
Packit 5bd3a9
.De
Packit 5bd3a9
.LP
Packit 5bd3a9
The specified first_keycode must be greater than or equal to min_keycode 
Packit 5bd3a9
returned by
Packit 5bd3a9
.ZN XDisplayKeycodes ,
Packit 5bd3a9
or a 
Packit 5bd3a9
.ZN BadValue 
Packit 5bd3a9
error results.
Packit 5bd3a9
In addition, the following expression must be less than or equal to 
Packit 5bd3a9
max_keycode as returned by
Packit 5bd3a9
.ZN XDisplayKeycodes ,
Packit 5bd3a9
or a
Packit 5bd3a9
.ZN BadValue 
Packit 5bd3a9
error results:
Packit 5bd3a9
.LP
Packit 5bd3a9
.Ds
Packit 5bd3a9
first_keycode + num_codes \- 1
Packit 5bd3a9
.De
Packit 5bd3a9
.LP
Packit 5bd3a9
KeySym number N, counting from zero, for KeyCode K has the following index
Packit 5bd3a9
in keysyms, counting from zero: 
Packit 5bd3a9
.LP
Packit 5bd3a9
.Ds 
Packit 5bd3a9
(K \- first_keycode) * keysyms_per_keycode + N
Packit 5bd3a9
.De
Packit 5bd3a9
.LP
Packit 5bd3a9
The specified keysyms_per_keycode can be chosen arbitrarily by the client
Packit 5bd3a9
to be large enough to hold all desired symbols. 
Packit 5bd3a9
A special KeySym value of 
Packit 5bd3a9
.ZN NoSymbol 
Packit 5bd3a9
should be used to fill in unused elements 
Packit 5bd3a9
for individual KeyCodes.  
Packit 5bd3a9
It is legal for 
Packit 5bd3a9
.ZN NoSymbol 
Packit 5bd3a9
to appear in nontrailing positions
Packit 5bd3a9
of the effective list for a KeyCode.
Packit 5bd3a9
.ZN XChangeKeyboardMapping
Packit 5bd3a9
generates a 
Packit 5bd3a9
.ZN MappingNotify 
Packit 5bd3a9
event.
Packit 5bd3a9
.LP
Packit 5bd3a9
There is no requirement that the X server interpret this mapping. 
Packit 5bd3a9
It is merely stored for reading and writing by clients.
Packit 5bd3a9
.LP
Packit 5bd3a9
.ZN XChangeKeyboardMapping
Packit 5bd3a9
can generate
Packit 5bd3a9
.ZN BadAlloc 
Packit 5bd3a9
and
Packit 5bd3a9
.ZN BadValue 
Packit 5bd3a9
errors.
Packit 5bd3a9
.LP
Packit 5bd3a9
The
Packit 5bd3a9
.ZN XGetKeyboardMapping
Packit 5bd3a9
function returns the symbols for the specified number of KeyCodes
Packit 5bd3a9
starting with first_keycode.
Packit 5bd3a9
The value specified in first_keycode must be greater than 
Packit 5bd3a9
or equal to min_keycode as returned by
Packit 5bd3a9
.ZN XDisplayKeycodes ,
Packit 5bd3a9
or a
Packit 5bd3a9
.ZN BadValue 
Packit 5bd3a9
error results.
Packit 5bd3a9
In addition, the following expression must be less than or equal 
Packit 5bd3a9
to max_keycode as returned by
Packit 5bd3a9
.ZN XDisplayKeycodes :
Packit 5bd3a9
.LP
Packit 5bd3a9
.Ds 
Packit 5bd3a9
first_keycode + keycode_count \- 1
Packit 5bd3a9
.De
Packit 5bd3a9
.LP
Packit 5bd3a9
If this is not the case, a 
Packit 5bd3a9
.ZN BadValue 
Packit 5bd3a9
error results. 
Packit 5bd3a9
The number of elements in the KeySyms list is:
Packit 5bd3a9
.LP
Packit 5bd3a9
.Ds 
Packit 5bd3a9
keycode_count * keysyms_per_keycode_return
Packit 5bd3a9
.De
Packit 5bd3a9
.LP
Packit 5bd3a9
KeySym number N, counting from zero, for KeyCode K has the following index
Packit 5bd3a9
in the list, counting from zero: 
Packit 5bd3a9
.Ds
Packit 5bd3a9
(K \- first_code) * keysyms_per_code_return + N
Packit 5bd3a9
.De
Packit 5bd3a9
.LP
Packit 5bd3a9
The X server arbitrarily chooses the keysyms_per_keycode_return value 
Packit 5bd3a9
to be large enough to report all requested symbols. 
Packit 5bd3a9
A special KeySym value of 
Packit 5bd3a9
.ZN NoSymbol 
Packit 5bd3a9
is used to fill in unused elements for
Packit 5bd3a9
individual KeyCodes.
Packit 5bd3a9
To free the storage returned by 
Packit 5bd3a9
.ZN XGetKeyboardMapping ,
Packit 5bd3a9
use
Packit 5bd3a9
.ZN XFree .
Packit 5bd3a9
.LP
Packit 5bd3a9
.ZN XGetKeyboardMapping
Packit 5bd3a9
can generate a
Packit 5bd3a9
.ZN BadValue 
Packit 5bd3a9
error.
Packit 5bd3a9
.LP
Packit 5bd3a9
The
Packit 5bd3a9
.ZN XDisplayKeycodes
Packit 5bd3a9
function returns the min-keycodes and max-keycodes supported by the
Packit 5bd3a9
specified display.
Packit 5bd3a9
The minimum number of KeyCodes returned is never less than 8,
Packit 5bd3a9
and the maximum number of KeyCodes returned is never greater than 255.
Packit 5bd3a9
Not all KeyCodes in this range are required to have corresponding keys.
Packit 5bd3a9
.LP
Packit 5bd3a9
The
Packit 5bd3a9
.ZN XSetModifierMapping
Packit 5bd3a9
function specifies the KeyCodes of the keys (if any) that are to be used 
Packit 5bd3a9
as modifiers.
Packit 5bd3a9
If it succeeds,
Packit 5bd3a9
the X server generates a
Packit 5bd3a9
.ZN MappingNotify
Packit 5bd3a9
event, and
Packit 5bd3a9
.ZN XSetModifierMapping
Packit 5bd3a9
returns
Packit 5bd3a9
.ZN MappingSuccess .
Packit 5bd3a9
X permits at most 8 modifier keys.
Packit 5bd3a9
If more than 8 are specified in the
Packit 5bd3a9
.ZN XModifierKeymap
Packit 5bd3a9
structure, a
Packit 5bd3a9
.ZN BadLength
Packit 5bd3a9
error results.
Packit 5bd3a9
.LP
Packit 5bd3a9
The modifiermap member of the 
Packit 5bd3a9
.ZN XModifierKeymap
Packit 5bd3a9
structure contains 8 sets of max_keypermod KeyCodes, 
Packit 5bd3a9
one for each modifier in the order 
Packit 5bd3a9
.ZN Shift , 
Packit 5bd3a9
.ZN Lock , 
Packit 5bd3a9
.ZN Control , 
Packit 5bd3a9
.ZN Mod1 , 
Packit 5bd3a9
.ZN Mod2 , 
Packit 5bd3a9
.ZN Mod3 , 
Packit 5bd3a9
.ZN Mod4 , 
Packit 5bd3a9
and 
Packit 5bd3a9
.ZN Mod5 .
Packit 5bd3a9
Only nonzero KeyCodes have meaning in each set, 
Packit 5bd3a9
and zero KeyCodes are ignored.
Packit 5bd3a9
In addition, all of the nonzero KeyCodes must be in the range specified by 
Packit 5bd3a9
min_keycode and max_keycode in the 
Packit 5bd3a9
.ZN Display 
Packit 5bd3a9
structure,
Packit 5bd3a9
or a 
Packit 5bd3a9
.ZN BadValue 
Packit 5bd3a9
error results.
Packit 5bd3a9
.LP
Packit 5bd3a9
An X server can impose restrictions on how modifiers can be changed, 
Packit 5bd3a9
for example,
Packit 5bd3a9
if certain keys do not generate up transitions in hardware,
Packit 5bd3a9
if auto-repeat cannot be disabled on certain keys,
Packit 5bd3a9
or if multiple modifier keys are not supported.  
Packit 5bd3a9
If some such restriction is violated, 
Packit 5bd3a9
the status reply is
Packit 5bd3a9
.ZN MappingFailed ,
Packit 5bd3a9
and none of the modifiers are changed.
Packit 5bd3a9
If the new KeyCodes specified for a modifier differ from those
Packit 5bd3a9
currently defined and any (current or new) keys for that modifier are
Packit 5bd3a9
in the logically down state, 
Packit 5bd3a9
.ZN XSetModifierMapping
Packit 5bd3a9
returns
Packit 5bd3a9
.ZN MappingBusy , 
Packit 5bd3a9
and none of the modifiers is changed.
Packit 5bd3a9
.LP
Packit 5bd3a9
.ZN XSetModifierMapping
Packit 5bd3a9
can generate
Packit 5bd3a9
.ZN BadAlloc
Packit 5bd3a9
and 
Packit 5bd3a9
.ZN BadValue
Packit 5bd3a9
errors.
Packit 5bd3a9
.LP
Packit 5bd3a9
The
Packit 5bd3a9
.ZN XGetModifierMapping
Packit 5bd3a9
function returns a pointer to a newly created
Packit 5bd3a9
.ZN XModifierKeymap
Packit 5bd3a9
structure that contains the keys being used as modifiers.
Packit 5bd3a9
The structure should be freed after use by calling
Packit 5bd3a9
.ZN XFreeModifiermap .
Packit 5bd3a9
If only zero values appear in the set for any modifier, 
Packit 5bd3a9
that modifier is disabled.
Packit 5bd3a9
.LP
Packit 5bd3a9
The
Packit 5bd3a9
.ZN XNewModifiermap
Packit 5bd3a9
function returns a pointer to
Packit 5bd3a9
.ZN XModifierKeymap
Packit 5bd3a9
structure for later use.
Packit 5bd3a9
.LP
Packit 5bd3a9
The
Packit 5bd3a9
.ZN XInsertModifiermapEntry
Packit 5bd3a9
function adds the specified KeyCode to the set that controls the specified
Packit 5bd3a9
modifier and returns the resulting
Packit 5bd3a9
.ZN XModifierKeymap
Packit 5bd3a9
structure (expanded as needed).
Packit 5bd3a9
.LP
Packit 5bd3a9
The
Packit 5bd3a9
.ZN XDeleteModifiermapEntry
Packit 5bd3a9
function deletes the specified KeyCode from the set that controls the
Packit 5bd3a9
specified modifier and returns a pointer to the resulting
Packit 5bd3a9
.ZN XModifierKeymap
Packit 5bd3a9
structure.
Packit 5bd3a9
.LP
Packit 5bd3a9
The
Packit 5bd3a9
.ZN XFreeModifiermap
Packit 5bd3a9
function frees the specified
Packit 5bd3a9
.ZN XModifierKeymap
Packit 5bd3a9
structure.
Packit 5bd3a9
.SH STRUCTURES
Packit 5bd3a9
The
Packit 5bd3a9
.ZN XModifierKeymap
Packit 5bd3a9
structure contains:
Packit 5bd3a9
.LP
Packit 5bd3a9
.Ds 0
Packit 5bd3a9
typedef struct {
Packit 5bd3a9
        int max_keypermod;      /\&* This server's max number of keys per modifier */
Packit 5bd3a9
        KeyCode *modifiermap;   /\&* An 8 by max_keypermod array of the modifiers */
Packit 5bd3a9
} XModifierKeymap;
Packit 5bd3a9
.De
Packit 5bd3a9
.SH DIAGNOSTICS
Packit 5bd3a9
.TP 1i
Packit 5bd3a9
.ZN BadAlloc
Packit 5bd3a9
The server failed to allocate the requested resource or server memory.
Packit 5bd3a9
.TP 1i
Packit 5bd3a9
.ZN BadValue
Packit 5bd3a9
Some numeric value falls outside the range of values accepted by the request.
Packit 5bd3a9
Unless a specific range is specified for an argument, the full range defined
Packit 5bd3a9
by the argument's type is accepted.  Any argument defined as a set of
Packit 5bd3a9
alternatives can generate this error.
Packit 5bd3a9
.SH "SEE ALSO"
Packit 5bd3a9
XFree(__libmansuffix__),
Packit 5bd3a9
XkbGetMap(__libmansuffix__),
Packit 5bd3a9
XSetPointerMapping(__libmansuffix__) 
Packit 5bd3a9
.br
Packit 5bd3a9
\fI\*(xL\fP