path: root/docs/reference/pygtk-gdkkeymap.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-gdkkeymap">
  <refnamediv>
    <refname>gtk.gdk.Keymap</refname>
    <refpurpose>an object containing mappings of keys to key
values.</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.gdk.Keymap</classname></ooclass>
      <ooclass><classname><link
linkend="class-gobject">gobject.GObject</link></classname></ooclass>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gdkkeymap--lookup-key">lookup_key</link></methodname>
	<methodparam><parameter role="keyword">keycode</parameter></methodparam>
	<methodparam><parameter role="keyword">group</parameter></methodparam>
	<methodparam><parameter role="keyword">level</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gdkkeymap--translate-keyboard-state">translate_keyboard_state</link></methodname>
	<methodparam><parameter role="keyword">keycode</parameter></methodparam>
	<methodparam><parameter role="keyword">state</parameter></methodparam>
	<methodparam><parameter role="keyword">group</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gdkkeymap--get-entries-for-keyval">get_entries_for_keyval</link></methodname>
	<methodparam><parameter role="keyword">keyval</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gdkkeymap--get-entries-for-keycode">get_entries_for_keycode</link></methodname>
	<methodparam><parameter role="keyword">hardware_keycode</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkkeymap--get-direction">get_direction</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
    </classsynopsis>

    <programlisting>
<emphasis role="bold">Functions</emphasis>

<methodsynopsis language="python">
	<methodname><link
linkend="function-gdk--keymap-get-default">gtk.gdk.keymap_get_default</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gdk--keymap-get-for-display">gtk.gdk.keymap_get_for_display</link></methodname>
	<methodparam><parameter role="keyword">display</parameter></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gdk--keyval-name">gtk.gdk.keyval_name</link></methodname>
	<methodparam><parameter
		       role="keyword">keyval</parameter></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gdk--keyval-from-name">gtk.gdk.keyval_from_name</link></methodname>
	<methodparam><parameter
		       role="keyword">keyval_name</parameter></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gdk--keyval-convert-case">gtk.gdk.keyval_convert_case</link></methodname>
	<methodparam><parameter
		       role="keyword">symbol</parameter></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gdk--keyval-to-upper">gtk.gdk.keyval_to_upper</link></methodname>
	<methodparam><parameter
		       role="keyword">keyval</parameter></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gdk--keyval-to-lower">gtk.gdk.keyval_to_lower</link></methodname>
	<methodparam><parameter
		       role="keyword">keyval</parameter></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gdk--keyval-is-upper">gtk.gdk.keyval_is_upper</link></methodname>
	<methodparam><parameter
		       role="keyword">keyval</parameter></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gdk--keyval-is-lower">gtk.gdk.keyval_is_lower</link></methodname>
	<methodparam><parameter
		       role="keyword">keyval</parameter></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gdk--keyval-to-unicode">gtk.gdk.keyval_to_unicode</link></methodname>
	<methodparam><parameter
		       role="keyword">keyval</parameter></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link
linkend="function-gdk--unicode-to-keyval">gtk.gdk.unicode_to_keyval</link></methodname>
	<methodparam><parameter role="keyword">wc</parameter></methodparam>
      </methodsynopsis></programlisting>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gdkkeymap">gtk.gdk.Keymap</link>
</synopsis>

  </refsect1>

  <refsect1>
    <title>Signal Prototypes</title>

    <variablelist>
      <varlistentry>
        <term>"<link linkend="signal-gdkkeymap--direction-changed">direction-changed</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>gdkkeymap</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link linkend="signal-gdkkeymap--keys-changed">keys-changed</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>gdkkeymap</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>A <link
linkend="class-gdkkeymap"><classname>gtk.gdk.Keymap</classname></link>
defines the translation from keyboard state (including a hardware key, a
modifier mask, and active keyboard group) to a keyval. This translation has
two phases. The first phase is to determine the effective keyboard group and
level for the keyboard state; the second phase is to look up the
keycode/group/level triplet in the keymap and see what keyval it corresponds
to. One <link
linkend="class-gdkkeymap"><classname>gtk.gdk.Keymap</classname></link>
object exists for each user display. <literal>PyGTK</literal> supports only
one display, so <link
linkend="function-gdk--keymap-get-default"><function>gtk.gdk.keymap_get_default()</function>()</link> 
returns the singleton <link
linkend="class-gdkkeymap"><classname>gtk.gdk.Keymap</classname></link>.</para>

    <para>A keymap is a mapping from a Keymap key to key values. You can
think of a Keymap key as a representation of a symbol printed on a physical
keyboard key. That is, it contains three pieces of information. First, it
contains the hardware keycode; this is an identifying number for a physical
key. Second, it contains the level of the key. The level indicates which
symbol on the key will be used, in a vertical direction. So on a standard US
keyboard, the key with the number "1" on it also has the exclamation point
("!") character on it. The level indicates whether to use the "1" or the "!"
symbol. The letter keys are considered to have a lowercase letter at level
0, and an uppercase letter at level 1, though only the uppercase letter is
printed. Third, the Keymap key contains a group; groups are not used on
standard US keyboards, but are used in many other countries. On a keyboard
with groups, there can be 3 or 4 symbols printed on a single key. The group
indicates movement in a horizontal direction. Usually groups are used for
two different languages. In group 0, a key might have two English
characters, and in group 1 it might have two Hebrew characters. The Hebrew
characters will be printed on the key next to the English characters.
</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gdkkeymap--lookup-key">
      <title>gtk.gdk.Keymap.lookup_key</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>lookup_key</methodname>
	  <methodparam><parameter
	  role="keyword">keycode</parameter></methodparam>
	  <methodparam><parameter
	  role="keyword">group</parameter></methodparam>
	  <methodparam><parameter
	  role="keyword">level</parameter></methodparam>
	  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">keycode</parameter>&nbsp;:</term>
	  <listitem><simpara>the hardware keycode.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">group</parameter>&nbsp;:</term>
	  <listitem><simpara>the key group</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">level</parameter>&nbsp;:</term>
	  <listitem><simpara>the key level</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a keyval, or 0 if none was mapped to the
	  (<parameter>keycode</parameter>, <parameter>group</parameter>,
	  <parameter>level</parameter>) triplet.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <methodname>lookup_key</methodname>() method returns the
keyval mapped to the specified (<parameter>keycode</parameter>,
<parameter>group</parameter>, <parameter>level</parameter>) triplet.  This
method returns 0 if no keyval is found. For normal user input, you want to
use the <link
linkend="method-gdkkeymap--translate-keyboard-state"><methodname>translate_keyboard_state()</methodname></link>
method instead of this method, since the effective group or level may not be
the same as the current keyboard state.</para>

      <para>The parameters to this method are:</para>

      <variablelist>
	<varlistentry>
	  <term><parameter>keycode</parameter>&nbsp;:</term>
	  <listitem>
	    <simpara>the hardware keycode. This is an identifying number for
a physical key.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>group</parameter>&nbsp;:</term>
	  <listitem>
	    <simpara>indicates movement in a horizontal direction. Usually
groups are used for two different languages. In group 0, a key might have
two English characters, and in group 1 it might have two Hebrew
characters. The Hebrew characters will be printed on the key next to the
English characters.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>level</parameter>&nbsp;:</term>
	  <listitem>
	    <simpara>indicates which symbol on the key will be used, in a
vertical direction. So on a standard US keyboard, the key with the number
"1" on it also has the exclamation point ("!")  character on it. The level
indicates whether to use the "1" or the "!" symbol. The letter keys are
considered to have a lowercase letter at level 0, and an uppercase letter at
level 1, though only the uppercase letter is printed.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para></para>

    </refsect2>

    <refsect2 id="method-gdkkeymap--translate-keyboard-state">
      <title>gtk.gdk.Keymap.translate_keyboard_state</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>translate_keyboard_state</methodname>
	  <methodparam><parameter role="keyword">keycode</parameter></methodparam>
	  <methodparam><parameter role="keyword">state</parameter></methodparam>
	  <methodparam><parameter role="keyword">group</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">keycode</parameter>&nbsp;:</term>
	  <listitem><simpara>a keycode</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">state</parameter>&nbsp;:</term>
	  <listitem><simpara>a modifier state</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">group</parameter>&nbsp;:</term>
	  <listitem><simpara>an active keyboard group</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem>
	    <simpara>a 4-tuple containing the keyval, the effective group,
the level and the modifiers that were used to determine the group or
level</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <methodname>translate_keyboard_state</methodname>() method
translates the contents of a keyboard <link
linkend="class-gdkevent"><classname>gtk.gdk.Event</classname></link>
(specified by <parameter>keycode</parameter>, <parameter>state</parameter>
and <parameter>group</parameter>) into a keyval, effective group, level and
consumed modifiers that affected the translation (and are unavailable for
application use) which are returned in a 4-tuple. See the <link
linkend="method-gdkkeymap--lookup-key"><methodname>lookup_key</methodname>()</link>
method for an explanation of groups and levels. The effective group is the
group that was actually used for the translation; some keys such as
<keycap>Enter</keycap> are not affected by the active keyboard group. The
level is derived from <parameter>state</parameter>. For convenience, the
keyboard <link
linkend="class-gdkevent"><classname>gtk.gdk.Event</classname></link> already
contains the translated keyval, so this method isn't as useful as you might
think.</para>

      <para>The value of <parameter>state</parameter> or the consumed
modifiers is a combination of:</para>

      <variablelist>
	<varlistentry>
	  <term><literal>gtk.gdk.SHIFT_MASK</literal></term>
	  <listitem>
	    <simpara>The Shift key.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.LOCK_MASK</literal></term>
	  <listitem>
	    <simpara>A Lock key (depending on the modifier mapping of the X
server this may either be CapsLock or ShiftLock).</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.CONTROL_MASK</literal></term>
	  <listitem>
	    <simpara>The Control key. </simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.MOD1_MASK</literal></term>
	  <listitem>
	    <simpara>The fourth modifier key (it depends on the modifier
mapping of the X server which key is interpreted as this modifier, but
normally it is the Alt key).</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.MOD2_MASK</literal></term>
	  <listitem>
	    <simpara>The fifth modifier key (it depends on the modifier
mapping of the X server which key is interpreted as this
modifier).</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.MOD3_MASK</literal></term>
	  <listitem>
	    <simpara>The sixth modifier key (it depends on the modifier
mapping of the X server which key is interpreted as this
modifier).</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.MOD4_MASK</literal></term>
	  <listitem>
	    <simpara>The seventh modifier key (it depends on the modifier
mapping of the X server which key is interpreted as this
modifier).</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.MOD5_MASK</literal></term>
	  <listitem>
	    <simpara>The eighth modifier key (it depends on the modifier
mapping of the X server which key is interpreted as this
modifier).</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.BUTTON1_MASK</literal></term>
	  <listitem>
	    <simpara>The first mouse button.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.BUTTON2_MASK</literal></term>
	  <listitem>
	    <simpara>The second mouse button.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.BUTTON3_MASK</literal></term>
	  <listitem>
	    <simpara>The third mouse button.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.BUTTON4_MASK</literal></term>
	  <listitem>
	    <simpara>The fourth mouse button.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.BUTTON5_MASK</literal></term>
	  <listitem>
	    <simpara>The fifth mouse button.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.RELEASE_MASK</literal></term>
	  <listitem>
	    <simpara>Differentiates between (keyval, modifiers) pairs from
key press and release events.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.MODIFIER_MASK</literal></term>
	  <listitem>
	    <simpara>all of the above</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para></para>

      <refsect3>
	<title>Consumed Modifiers</title>

	<para>The consumed modifiers are modifiers that should be masked out
from <parameter>state</parameter> when comparing this key press to a hot
key. For instance, on a US keyboard, the <keysym>plus</keysym> symbol is
shifted, so when comparing a key press to a
<keycombo>
	    <keycap>Control</keycap><keysym>plus</keysym></keycombo>
	    accelerator <keycap>Shift</keycap> should be masked out. For
	    example:</para>

	<programlisting>
  # We want to ignore irrelevant modifiers like ScrollLock
  ALL_ACCELS_MASK = (gtk.gdk.CONTROL_MASK | gtk.gdk.SHIFT_MASK
                     | gtk.gdk.MOD1_MASK)
  keyval, egroup, level, consumed = keymap.translate_keyboard_state(
                   event.hardware_keycode, event.state, event.group)
  if (keyval == gtk.keysyms.plus and 
      (event.state &amp; ~consumed &amp; ALL_ACCELS_MASK) == gtk.gdk.CONTROL_MASK):
    # Control was pressed
</programlisting>

        <para>Note that most keys that are affected by the
<keycap>Shift</keycap> key will have <literal>gtk.gdk.SHIFT_MASK</literal>
part of the consumed modifiers (e.g. <keycombo>
<keycap>Control</keycap><keycap>Shift</keycap><keycap>Tab</keycap>
</keycombo>).</para>

	<para>All single modifier combinations that could affect the key for
any combination of modifiers will be returned in consumed_modifiers.
Multi-modifier combinations are returned only when actually found in
<parameter>state</parameter>. When you store accelerators, you should always
store them with consumed modifiers removed. Store &lt;Control&gt;plus, not
&lt;Control&gt;&lt;Shift&gt;plus,</para>

      </refsect3>

    </refsect2>

  <refsect2 id="method-gdkkeymap--get-entries-for-keyval">
    <title>gtk.gdk.Keymap.get_entries_for_keyval</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_entries_for_keyval</methodname>
	  <methodparam><parameter role="keyword">keyval</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">keyval</parameter>&nbsp;:</term>
	  <listitem><simpara>a keyval, such as <literal>GDK_a</literal>,
<literal>GDK_Up</literal>, <literal>GDK_Return</literal>,
etc.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing 3-tuple containing a keycode,
a group and a level that will generate
<parameter>keyval</parameter>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <methodname>get_entries_for_keyval</methodname>() method
returns a tuple of (keycode, group, level) 3-tuples that will generate
<parameter>keyval</parameter>. Groups and levels are two kinds of keyboard
mode; in general, the level determines whether the top or bottom symbol on a
key is used, and the group determines whether the left or right symbol is
used. On US keyboards, the shift key changes the keyboard level, and there
are no groups. A group switch key might convert a keyboard between Hebrew to
English modes, for example, the <literal>gtk.gdk.KEY_PRESS</literal> and
<literal>gtk.gdk.KEY_RELEASE</literal> <link
linkend="class-gdkevent"><classname>gtk.gdk.Event</classname></link> objects
contain a <literal>group</literal> attribute that indicates the active
keyboard group. The level is computed from the modifier mask.</para>

    </refsect2>

  <refsect2 id="method-gdkkeymap--get-entries-for-keycode">
    <title>gtk.gdk.Keymap.get_entries_for_keycode</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_entries_for_keycode</methodname>
	  <methodparam><parameter role="keyword">hardware_keycode</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">hardware_keycode</parameter>&nbsp;:</term>
	  <listitem><simpara>a keycode</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing 4-tuples: (keyval, keycode,
group, level)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <methodname>get_entries_for_keycode</methodname>() method
returns a tuple containing 4-tuples with: the keyvals bound to
<parameter>hardware_keycode</parameter>, the keycode, the group and the
level.  When a keycode is pressed by the user, the keyval from this list of
entries is selected by considering the effective keyboard group and
level. See the <link
linkend="method-gdkkeymap--translate-keyboard-state"><methodname>translate_keyboard_state()</methodname></link>
method for more information.</para>

    </refsect2>

    <refsect2 id="method-gdkkeymap--get-direction">
    <title>gtk.gdk.Keymap.get_direction</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_direction</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a Pango direction: <literal>pango.DIRECTION_LTR</literal> or <literal>pango.DIRECTION_RTL</literal>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_direction</methodname>() method returns the direction of the keymap.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-gdk--keymap-get-default">
      <title>gtk.gdk.keymap_get_default</title>

      <programlisting><methodsynopsis language="python">
          <methodname>gtk.gdk.keymap_get_default</methodname>
          <methodparam></methodparam>
        </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the default gdk keymap for the
display.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The <function>gtk.gdk.keymap_get_default</function>() function
returns the default <link
linkend="class-gdkkeymap"><classname>gtk.gdk.Keymap</classname></link> for
the display.</para>

    </refsect2>

    <refsect2 id="function-gdk--keymap-get-for-display">
      <title>gtk.gdk.keymap_get_for_display</title>

      <programlisting><methodsynopsis language="python">
          <methodname>gtk.gdk.keymap_get_for_display</methodname>
	<methodparam><parameter role="keyword">display</parameter></methodparam>
        </methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">display</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link linkend="class-gdkdisplay"><classname>gtk.gdk.Display</classname></link></simpara></listitem>
	</varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the keymap for
          <parameter>display</parameter>.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
	<para>This function is available in PyGTK 2.2 and above.</para>
      </note>

      <para>The <function>gtk.gdk.keymap_get_for_display</function>()
function returns the <link
linkend="class-gdkkeymap"><classname>gtk.gdk.Keymap</classname></link> for
the <link
linkend="class-gdkdisplay"><classname>gtk.gdk.Display</classname></link>
specified by <parameter>display</parameter>.</para>

    </refsect2>

    <refsect2 id="function-gdk--keyval-name">
      <title>gtk.gdk.keyval_name</title>

      <programlisting><methodsynopsis language="python">
          <methodname>gtk.gdk.keyval_name</methodname>
          <methodparam><parameter
			 role="keyword">keyval</parameter></methodparam>
        </methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
          <term><parameter role="keyword">keyval</parameter>&nbsp;:</term>
          <listitem><simpara>a key value</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a string containing the name of the key, or
None if keyval is not a valid key.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The <function>gtk.gdk.keyval_name</function>() function converts
the key value specified by <parameter>keyval</parameter> into a symbolic
name.</para>

    </refsect2>

    <refsect2 id="function-gdk--keyval-from-name">
      <title>gtk.gdk.keyval_from_name</title>

      <programlisting><methodsynopsis language="python">
          <methodname>gtk.gdk.keyval_from_name</methodname>
          <methodparam><parameter
			 role="keyword">keyval_name</parameter></methodparam>
        </methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
          <term><parameter
role="keyword">keyval_name</parameter>&nbsp;:</term>
          <listitem><simpara>a key name</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the corresponding key value or 0 if the key
name is not a valid key.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The <function>gtk.gdk.keyval_from_name</function>() function
converts the key name specified by <parameter>keyval_name</parameter> to a
key value.</para>

    </refsect2>

    <refsect2 id="function-gdk--keyval-convert-case">
      <title>gtk.gdk.keyval_convert_case</title>

      <programlisting><methodsynopsis language="python">
          <methodname>gtk.gdk.keyval_convert_case</methodname>
          <methodparam><parameter
			 role="keyword">symbol</parameter></methodparam>
        </methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
          <term><parameter
role="keyword">symbol</parameter>&nbsp;:</term>
          <listitem><simpara>a keyval</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a 2-tuple containing the lowercase and
          uppercase versions of
          <parameter>symbol</parameter></simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
	<para>This function is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <function>gtk.gdk.keyval_convert_case</function>() function
returns the lowercase and uppercase versions of the keyval specified by
<parameter>symbol</parameter>.</para>

    </refsect2>

    <refsect2 id="function-gdk--keyval-to-upper">
      <title>gtk.gdk.keyval_to_upper</title>

      <programlisting><methodsynopsis language="python">
          <methodname>gtk.gdk.keyval_to_upper</methodname>
          <methodparam><parameter
			 role="keyword">keyval</parameter></methodparam>
        </methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
          <term><parameter role="keyword">keyval</parameter>&nbsp;:</term>
          <listitem><simpara>a key value.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the upper case form of keyval, or keyval itself
if it is already in upper case or it is not subject to case
conversion.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The <function>gtk.gdk.keyval_to_upper</function>() function
converts the key value specified by <parameter>keyval</parameter> to upper
case, if applicable.</para>

    </refsect2>

    <refsect2 id="function-gdk--keyval-to-lower">
      <title>gtk.gdk.keyval_to_lower</title>

      <programlisting><methodsynopsis language="python">
          <methodname>gtk.gdk.keyval_to_lower</methodname>
          <methodparam><parameter
			 role="keyword">keyval</parameter></methodparam>
        </methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
          <term><parameter role="keyword">keyval</parameter>&nbsp;:</term>
          <listitem><simpara>the key value</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the lower case form of keyval, or keyval itself
if it is already in lower case or it is not subject to case
conversion.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The <function>gtk.gdk.keyval_to_lower</function>() function
converts the key value specified by <parameter>keyval</parameter> to lower
case, if applicable. </para>

    </refsect2>

    <refsect2 id="function-gdk--keyval-is-upper">
      <title>gtk.gdk.keyval_is_upper</title>

      <programlisting><methodsynopsis language="python">
          <methodname>gtk.gdk.keyval_is_upper</methodname>
          <methodparam><parameter
			 role="keyword">keyval</parameter></methodparam>
        </methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
          <term><parameter role="keyword">keyval</parameter>&nbsp;:</term>
          <listitem><simpara>the key value</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>TRUE</literal> if
<parameter>keyval</parameter> is in upper case or if keyval is not subject
to case conversion.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The <function>gtk.gdk.keyval_is_upper</function>() function
returns <literal>TRUE</literal> if the key value specified by
<parameter>keyval</parameter> is in upper case or not subject to case
conversion.</para>

    </refsect2>

    <refsect2 id="function-gdk--keyval-is-lower">
      <title>gtk.gdk.keyval_is_lower</title>

      <programlisting><methodsynopsis language="python">
          <methodname>gtk.gdk.keyval_is_lower</methodname>
          <methodparam><parameter
			 role="keyword">keyval</parameter></methodparam>
        </methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
          <term><parameter role="keyword">keyval</parameter>&nbsp;:</term>
          <listitem><simpara>the key value</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>TRUE</literal> if
<parameter>keyval</parameter> is in lower case, or if
<parameter>keyval</parameter> is not subject to case
conversion.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The <function>gtk.gdk.keyval_is_lower</function>() function
returns <literal>TRUE</literal> if the key value specified by
<parameter>keyval</parameter> is in lower case or is not subject to case
conversion.</para>

    </refsect2>

    <refsect2 id="function-gdk--keyval-to-unicode">
      <title>gtk.gdk.keyval_to_unicode</title>

      <programlisting><methodsynopsis language="python">
          <methodname>gtk.gdk.keyval_to_unicode</methodname>
          <methodparam><parameter
			 role="keyword">keyval</parameter></methodparam>
        </methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
          <term><parameter role="keyword">keyval</parameter>&nbsp;:</term>
          <listitem><simpara>the key value</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara> the corresponding unicode character, or 0 if
there is no corresponding character.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The <function>gtk.gdk.keyval_to_unicode</function>() function
converts the key value specified by <parameter>keyval</parameter> to the
corresponding ISO10646 (Unicode) character.</para>

    </refsect2>

    <refsect2 id="function-gdk--unicode-to-keyval">
      <title>gtk.gdk.unicode_to_keyval</title>

      <programlisting><methodsynopsis language="python">
          <methodname>gtk.gdk.unicode_to_keyval</methodname>
          <methodparam><parameter
			 role="keyword">wc</parameter></methodparam>
        </methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
          <term><parameter role="keyword">wc</parameter>&nbsp;:</term>
          <listitem><simpara> a ISO10646 encoded (unicode)
character</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the corresponding key value, if one exists. or,
if there is no corresponding symbol, <parameter>wc</parameter> |
0x01000000</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The <function>gtk.gdk.unicode_to_keyval</function>() function
converts the ISO10646 (unicode) character specified by
<parameter>wc</parameter> to a key value.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gdkkeymap--direction-changed">
      <title>The "direction-changed" gtk.gdk.Keymap Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>gdkkeymap</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>gdkkeymap</parameter>&nbsp;:</term>
	  <listitem><simpara>the gdkkeymap that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "direction-changed" signal is emitted when the pango text
direction of <parameter>gdkkeymap</parameter> is changed</para>

    </refsect2>

    <refsect2 id="signal-gdkkeymap--keys-changed">
      <title>The "keys-changed" gtk.gdk.Keymap Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>gdkkeymap</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>gdkkeymap</parameter>&nbsp;:</term>
	  <listitem><simpara>the gdkkeymap that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This signal is available in GTK+ 2.2 and above.</para>
      </note>

      <para>The "keys-changed" signal is emitted when the mapping
represented by <parameter>keymap</parameter> changes.</para>

    </refsect2>

  </refsect1>

</refentry>