<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<!-- lifted from troff+man by doclifter -->
<refentry id='xlookksymman'>
<!--  Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium -->

<!--  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 name of the X Consortium shall -->
<!--  not be used in advertising or otherwise to promote the sale, use or -->
<!--  other dealings in this Software without prior written authorization -->
<!--  from the X Consortium. -->

<!--  Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by -->
<!--  Digital Equipment Corporation -->

<!--  Portions Copyright \(co 1990, 1991 by -->
<!--  Tektronix, Inc. -->

<!--  Permission to use, copy, modify and distribute this documentation for -->
<!--  any purpose and without fee is hereby granted, provided that the above -->
<!--  copyright notice appears in all copies and that both that copyright notice -->
<!--  and this permission notice appear in all copies, and that the names of -->
<!--  Digital and Tektronix not be used in in advertising or publicity pertaining -->
<!--  to this documentation without specific, written prior permission. -->
<!--  Digital and Tektronix makes no representations about the suitability -->
<!--  of this documentation for any purpose. -->
<!--  It is provided ``as is'' without express or implied warranty. -->
<!--   -->
<!--  $XFree86: xc/doc/man/X11/XLookKsym.man,v 1.5 2003/04/28 22:17:55 herrb Exp $ -->

<!-- .na -->
<!-- Ds listing suppressed (not used) -->
<!-- De listing suppressed (not used) -->
<!-- FD listing suppressed (not used) -->
<!-- FN listing suppressed (not used) -->
<!-- IN listing suppressed (not used) -->
<!-- C{ listing suppressed (not used) -->
<!-- C} listing suppressed (not used) -->
<!-- Pn listing suppressed (not used) -->
<!-- hN listing suppressed (not used) -->
<!-- NT listing suppressed (not used) -->
<!-- .		\" Note End \-\- doug kraft 3/85 -->
<!-- NE listing suppressed (not used) -->
<!-- .ny0 -->
<refmeta>
<refentrytitle>XLookupKeysym</refentrytitle>
<manvolnum>3X11</manvolnum>
<refmiscinfo class='date'>__xorgversion__</refmiscinfo>
<refmiscinfo class='source'>XLIB FUNCTIONS</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>XLookupKeysym</refname>
<refname>XRefreshKeyboardMapping</refname>
<refname>XLookupString</refname>
<refname>XRebindKeysym</refname>
<refpurpose>handle keyboard input events in Latin-1</refpurpose>
</refnamediv>
<!-- body begins here -->

<refsect1 id='syntax'><title>SYNTAX</title>

<para>KeySym XLookupKeysym(&hairsp;XKeyEvent *<emphasis remap='I'>key_event</emphasis>&hairsp;, int <emphasis remap='I'>index</emphasis>&hairsp;);</para> 

<para>int XRefreshKeyboardMapping(&hairsp;XMappingEvent *<emphasis remap='I'>event_map</emphasis>&hairsp;);</para> 

<para>int XLookupString(&hairsp;XKeyEvent *<emphasis remap='I'>event_struct</emphasis>&hairsp;, char
*<emphasis remap='I'>buffer_return</emphasis>&hairsp;, int <emphasis remap='I'>bytes_buffer</emphasis>&hairsp;, KeySym
*<emphasis remap='I'>keysym_return</emphasis>&hairsp;, XComposeStatus *<emphasis remap='I'>status_in_out</emphasis>&hairsp;);</para> 

<para>int XRebindKeysym(&hairsp;Display *<emphasis remap='I'>display</emphasis>&hairsp;, KeySym <emphasis remap='I'>keysym</emphasis>&hairsp;, KeySym
<emphasis remap='I'>list</emphasis>&hairsp;[&hairsp;]&hairsp;, int <emphasis remap='I'>mod_count</emphasis>&hairsp;, unsigned char *<emphasis remap='I'>string</emphasis>&hairsp;, int
<emphasis remap='I'>num_bytes</emphasis>&hairsp;);</para> 
</refsect1>

<refsect1 id='arguments'><title>ARGUMENTS</title>
<variablelist remap='IP'>
  <varlistentry>
  <term><emphasis remap='I'>buffer_return</emphasis></term>
  <listitem>
<para>Returns the translated characters.</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><emphasis remap='I'>bytes_buffer</emphasis></term>
  <listitem>
<para>Specifies the length of the buffer.
No more than bytes_buffer of translation are returned.</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><emphasis remap='I'>num_bytes</emphasis></term>
  <listitem>
<para>Specifies the number of bytes in the string argument.</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><emphasis remap='I'>display</emphasis></term>
  <listitem>
<para>Specifies the connection to the X server.</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><emphasis remap='I'>event_map</emphasis></term>
  <listitem>
<para>Specifies the mapping event that is to be used.</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><emphasis remap='I'>event_struct</emphasis></term>
  <listitem>
<para>Specifies the key event structure to be used.
You can pass
<emphasis remap='I'>&hairsp;XKeyPressedEvent&hairsp;</emphasis>
or
<emphasis remap='I'>&hairsp;XKeyReleasedEvent&hairsp;</emphasis>.</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><emphasis remap='I'>index</emphasis></term>
  <listitem>
<para>Specifies the index into the KeySyms list for the event's KeyCode.</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><emphasis remap='I'>key_event</emphasis></term>
  <listitem>
<para>Specifies the 
<emphasis remap='I'>&hairsp;KeyPress&hairsp;</emphasis>
or
<emphasis remap='I'>&hairsp;KeyRelease&hairsp;</emphasis>
event.</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><emphasis remap='I'>keysym</emphasis></term>
  <listitem>
<para>Specifies the KeySym that is to be \*(Fn.</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><emphasis remap='I'>keysym_return</emphasis></term>
  <listitem>
<para>Returns the KeySym computed from the event if this argument is not NULL.</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><emphasis remap='I'>list</emphasis></term>
  <listitem>
<para>Specifies the KeySyms to be used as modifiers.</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><emphasis remap='I'>mod_count</emphasis></term>
  <listitem>
<para>Specifies the number of modifiers in the modifier list.</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><emphasis remap='I'>status_in_out</emphasis></term>
  <listitem>
<para>Specifies or returns the 
<emphasis remap='I'>&hairsp;XComposeStatus&hairsp;</emphasis>
structure or NULL.</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><emphasis remap='I'>string</emphasis></term>
  <listitem>
<para>Specifies the string that is copied and will be returned by 
<emphasis remap='I'>&hairsp;XLookupString&hairsp;</emphasis>.</para>
  </listitem>
  </varlistentry>
</variablelist>
</refsect1>

<refsect1 id='description'><title>DESCRIPTION</title>
<para>The
<emphasis remap='I'>&hairsp;XLookupKeysym&hairsp;</emphasis>
function uses a given keyboard event and the index you specified to return
the KeySym from the list that corresponds to the KeyCode member in the
<emphasis remap='I'>&hairsp;XKeyPressedEvent&hairsp;</emphasis>
or
<emphasis remap='I'>&hairsp;XKeyReleasedEvent&hairsp;</emphasis>
structure.
If no KeySym is defined for the KeyCode of the event,
<emphasis remap='I'>&hairsp;XLookupKeysym&hairsp;</emphasis>
returns
<emphasis remap='I'>&hairsp;NoSymbol&hairsp;</emphasis>.</para>

<para>The
<emphasis remap='I'>&hairsp;XRefreshKeyboardMapping&hairsp;</emphasis>
function refreshes the stored modifier and keymap information.
You usually call this function when a
<emphasis remap='I'>&hairsp;MappingNotify&hairsp;</emphasis>
event with a request member of
<emphasis remap='I'>&hairsp;MappingKeyboard&hairsp;</emphasis>
or
<emphasis remap='I'>&hairsp;MappingModifier&hairsp;</emphasis>
occurs.
The result is to update Xlib's knowledge of the keyboard.</para>

<para>The
<emphasis remap='I'>&hairsp;XLookupString&hairsp;</emphasis>
function translates a key event to a KeySym and a string.
The KeySym is obtained by using the standard interpretation of the
<emphasis remap='I'>&hairsp;Shift&hairsp;</emphasis>,
<emphasis remap='I'>&hairsp;Lock&hairsp;</emphasis>,
group, and numlock modifiers as defined in the X Protocol specification.
If the KeySym has been rebound (see
<emphasis remap='I'>&hairsp;XRebindKeysym&hairsp;</emphasis>),
the bound string will be stored in the buffer.
Otherwise, the KeySym is mapped, if possible, to an ISO Latin-1 character
or (if the Control modifier is on) to an ASCII control character,
and that character is stored in the buffer.
<emphasis remap='I'>&hairsp;XLookupString&hairsp;</emphasis>
returns the number of characters that are stored in the buffer.</para>

<para>If present (non-NULL),
the
<emphasis remap='I'>&hairsp;XComposeStatus&hairsp;</emphasis>
structure records the state,
which is private to Xlib,
that needs preservation across calls to
<emphasis remap='I'>&hairsp;XLookupString&hairsp;</emphasis>
to implement compose processing.
The creation of
<emphasis remap='I'>&hairsp;XComposeStatus&hairsp;</emphasis>
structures is implementation-dependent;
a portable program must pass NULL for this argument.</para>

<para>The
<emphasis remap='I'>&hairsp;XRebindKeysym&hairsp;</emphasis>
function can be used to rebind the meaning of a KeySym for the client.
It does not redefine any key in the X server but merely
provides an easy way for long strings to be attached to keys.
<emphasis remap='I'>&hairsp;XLookupString&hairsp;</emphasis>
returns this string when the appropriate set of
modifier keys are pressed and when the KeySym would have been used for
the translation.
No text conversions are performed;
the client is responsible for supplying appropriately encoded strings.
Note that you can rebind a KeySym that may not exist.</para>
</refsect1>

<refsect1 id='see_also'><title>SEE ALSO</title>
<para>XButtonEvent(3X11),
XMapEvent(3X11),
XStringToKeysym(3X11)
<!-- .br -->
<userinput>Xlib - C Language X Interface</userinput></para>
</refsect1>
</refentry>

