man/XLookupKeysym.man

   1 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
   2 .\"
   3 .\" Permission is hereby granted, free of charge, to any person obtaining
   4 .\" a copy of this software and associated documentation files (the
   5 .\" "Software"), to deal in the Software without restriction, including
   6 .\" without limitation the rights to use, copy, modify, merge, publish,
   7 .\" distribute, sublicense, and/or sell copies of the Software, and to
   8 .\" permit persons to whom the Software is furnished to do so, subject to
   9 .\" the following conditions:
  10 .\"
  11 .\" The above copyright notice and this permission notice shall be included
  12 .\" in all copies or substantial portions of the Software.
  13 .\"
  14 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  15 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  16 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  17 .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
  18 .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  19 .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  20 .\" OTHER DEALINGS IN THE SOFTWARE.
  21 .\"
  22 .\" Except as contained in this notice, the name of the X Consortium shall
  23 .\" not be used in advertising or otherwise to promote the sale, use or
  24 .\" other dealings in this Software without prior written authorization
  25 .\" from the X Consortium.
  26 .\"
  27 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
  28 .\" Digital Equipment Corporation
  29 .\"
  30 .\" Portions Copyright \(co 1990, 1991 by
  31 .\" Tektronix, Inc.
  32 .\"
  33 .\" Permission to use, copy, modify and distribute this documentation for
  34 .\" any purpose and without fee is hereby granted, provided that the above
  35 .\" copyright notice appears in all copies and that both that copyright notice
  36 .\" and this permission notice appear in all copies, and that the names of
  37 .\" Digital and Tektronix not be used in in advertising or publicity pertaining
  38 .\" to this documentation without specific, written prior permission.
  39 .\" Digital and Tektronix makes no representations about the suitability
  40 .\" of this documentation for any purpose.
  41 .\" It is provided ``as is'' without express or implied warranty.
  42 .\"
  43 .\"
  44 .ds xT X Toolkit Intrinsics \- C Language Interface
  45 .ds xW Athena X Widgets \- C Language X Toolkit Interface
  46 .ds xL Xlib \- C Language X Interface
  47 .ds xC Inter-Client Communication Conventions Manual
  48 .na
  49 .de Ds
  50 .nf
  51 .\\$1D \\$2 \\$1
  52 .ft CW
  53 .\".ps \\n(PS
  54 .\".if \\n(VS>=40 .vs \\n(VSu
  55 .\".if \\n(VS<=39 .vs \\n(VSp
  56 ..
  57 .de De
  58 .ce 0
  59 .if \\n(BD .DF
  60 .nr BD 0
  61 .in \\n(OIu
  62 .if \\n(TM .ls 2
  63 .sp \\n(DDu
  64 .fi
  65 ..
  66 .de IN          \" send an index entry to the stderr
  67 ..
  68 .de Pn
  69 .ie t \\$1\fB\^\\$2\^\fR\\$3
  70 .el \\$1\fI\^\\$2\^\fP\\$3
  71 ..
  72 .de ZN
  73 .ie t \fB\^\\$1\^\fR\\$2
  74 .el \fI\^\\$1\^\fP\\$2
  75 ..
  76 .de hN
  77 .ie t <\fB\\$1\fR>\\$2
  78 .el <\fI\\$1\fP>\\$2
  79 ..
  80 .ny0
  81 .TH XLookupKeysym __libmansuffix__ __xorgversion__ "XLIB FUNCTIONS"
  82 .SH NAME
  83 XLookupKeysym, XRefreshKeyboardMapping, XLookupString, XRebindKeysym \- handle keyboard input events in Latin-1
  84 .SH SYNTAX
  85 .HP
  86 KeySym XLookupKeysym(\^XKeyEvent *\fIkey_event\fP\^, int \fIindex\fP\^);
  87 .HP
  88 int XRefreshKeyboardMapping(\^XMappingEvent *\fIevent_map\fP\^);
  89 .HP
  90 int XLookupString(\^XKeyEvent *\fIevent_struct\fP\^, char
  91 *\fIbuffer_return\fP\^, int \fIbytes_buffer\fP\^, KeySym
  92 *\fIkeysym_return\fP\^, XComposeStatus *\fIstatus_in_out\fP\^);
  93 .HP
  94 int XRebindKeysym(\^Display *\fIdisplay\fP\^, KeySym \fIkeysym\fP\^, KeySym
  95 \fIlist\fP\^[\^]\^, int \fImod_count\fP\^, unsigned char *\fIstring\fP\^, int
  96 \fInum_bytes\fP\^);
  97 .SH ARGUMENTS
  98 .IP \fIbuffer_return\fP 1i
  99 Returns the translated characters.
 100 .IP \fIbytes_buffer\fP 1i
 101 Specifies the length of the buffer.
 102 No more than bytes_buffer of translation are returned.
 103 .IP \fInum_bytes\fP 1i
 104 Specifies the number of bytes in the string argument.
 105 .IP \fIdisplay\fP 1i
 106 Specifies the connection to the X server.
 107 .IP \fIevent_map\fP 1i
 108 Specifies the mapping event that is to be used.
 109 .IP \fIevent_struct\fP 1i
 110 Specifies the key event structure to be used.
 111 You can pass
 112 .ZN XKeyPressedEvent
 113 or
 114 .ZN XKeyReleasedEvent .
 115 .IP \fIindex\fP 1i
 116 Specifies the index into the KeySyms list for the event's KeyCode.
 117 .IP \fIkey_event\fP 1i
 118 Specifies the
 119 .ZN KeyPress
 120 or
 121 .ZN KeyRelease
 122 event.
 123 .IP \fIkeysym\fP 1i
 124 Specifies the KeySym that is to be \*(Fn.
 125 .IP \fIkeysym_return\fP 1i
 126 Returns the KeySym computed from the event if this argument is not NULL.
 127 .IP \fIlist\fP 1i
 128 Specifies the KeySyms to be used as modifiers.
 129 .IP \fImod_count\fP 1i
 130 Specifies the number of modifiers in the modifier list.
 131 .IP \fIstatus_in_out\fP 1i
 132 Specifies or returns the
 133 .ZN XComposeStatus
 134 structure or NULL.
 135 .IP \fIstring\fP 1i
 136 Specifies the string that is copied and will be returned by
 137 .ZN XLookupString .
 138 .SH DESCRIPTION
 139 The
 140 .ZN XLookupKeysym
 141 function uses a given keyboard event and the index you specified to return
 142 the KeySym from the list that corresponds to the KeyCode member in the
 143 .ZN XKeyPressedEvent
 144 or
 145 .ZN XKeyReleasedEvent
 146 structure.
 147 If no KeySym is defined for the KeyCode of the event,
 148 .ZN XLookupKeysym
 149 returns
 150 .ZN NoSymbol .
 151 .LP
 152 The
 153 .ZN XRefreshKeyboardMapping
 154 function refreshes the stored modifier and keymap information.
 155 You usually call this function when a
 156 .ZN MappingNotify
 157 event with a request member of
 158 .ZN MappingKeyboard
 159 or
 160 .ZN MappingModifier
 161 occurs.
 162 The result is to update Xlib's knowledge of the keyboard.
 163 .LP
 164 The
 165 .ZN XLookupString
 166 function translates a key event to a KeySym and a string.
 167 The KeySym is obtained by using the standard interpretation of the
 168 .ZN Shift ,
 169 .ZN Lock ,
 170 group, and numlock modifiers as defined in the X Protocol specification.
 171 If the KeySym has been rebound (see
 172 .ZN XRebindKeysym ),
 173 the bound string will be stored in the buffer.
 174 Otherwise, the KeySym is mapped, if possible, to an ISO Latin-1 character
 175 or (if the Control modifier is on) to an ASCII control character,
 176 and that character is stored in the buffer.
 177 .ZN XLookupString
 178 returns the number of characters that are stored in the buffer.
 179 .LP
 180 If present (non-NULL),
 181 the
 182 .ZN XComposeStatus
 183 structure records the state,
 184 which is private to Xlib,
 185 that needs preservation across calls to
 186 .ZN XLookupString
 187 to implement compose processing.
 188 The creation of
 189 .ZN XComposeStatus
 190 structures is implementation-dependent;
 191 a portable program must pass NULL for this argument.
 192 .LP
 193 The
 194 .ZN XRebindKeysym
 195 function can be used to rebind the meaning of a KeySym for the client.
 196 It does not redefine any key in the X server but merely
 197 provides an easy way for long strings to be attached to keys.
 198 .ZN XLookupString
 199 returns this string when the appropriate set of
 200 modifier keys are pressed and when the KeySym would have been used for
 201 the translation.
 202 No text conversions are performed;
 203 the client is responsible for supplying appropriately encoded strings.
 204 Note that you can rebind a KeySym that may not exist.
 205 .SH "SEE ALSO"
 206 XButtonEvent(__libmansuffix__),
 207 XMapEvent(__libmansuffix__),
 208 XStringToKeysym(__libmansuffix__),
 209 XkbLookupKeySym(__libmansuffix__),
 210 XkbRefreshKeyboardMapping(__libmansuffix__),
 211 XmbLookupString(__libmansuffix__),
 212 XwcLookupString(__libmansuffix__),
 213 Xutf8LookupString(__libmansuffix__),
 214 Compose(__filemansuffix__)
 215 .br
 216 \fI\*(xL\fP