<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="gdk4-Keyboard-Handling">
<refmeta>
<refentrytitle role="top_of_page" id="gdk4-Keyboard-Handling.top_of_page">Key Values</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Key Values</refname>
<refpurpose>Functions for manipulating keyboard codes</refpurpose>
</refnamediv>

<refsect1 id="gdk4-Keyboard-Handling.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type">const <link linkend="char"><returnvalue>char</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gdk-keyval-name">gdk_keyval_name</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-keyval-from-name">gdk_keyval_from_name</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-keyval-convert-case">gdk_keyval_convert_case</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-keyval-to-upper">gdk_keyval_to_upper</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-keyval-to-lower">gdk_keyval_to_lower</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-keyval-is-upper">gdk_keyval_is_upper</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-keyval-is-lower">gdk_keyval_is_lower</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint32"><returnvalue>guint32</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-keyval-to-unicode">gdk_keyval_to_unicode</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-unicode-to-keyval">gdk_unicode_to_keyval</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 id="gdk4-Keyboard-Handling.includes"><title>Includes</title><synopsis>#include &lt;gdk/gdk.h&gt;
</synopsis></refsect1>

<refsect1 id="gdk4-Keyboard-Handling.description" role="desc">
<title role="desc.title">Description</title>
<para>Key values are the codes which are sent whenever a key is pressed or released.
They are included in the data contained in a key press or release <link linkend="GdkEvent"><type>GdkEvent</type></link>.
The complete list of key values can be found in the <literal>gdk/gdkkeysyms.h</literal> header
file.</para>
<para>Key values are regularly updated from the upstream X.org X11 implementation,
so new values are added regularly. They will be prefixed with GDK_KEY_ rather
than XF86XK_ or XK_ (for older symbols).</para>
<para>Key values can be converted into a string representation using
<link linkend="gdk-keyval-name"><function>gdk_keyval_name()</function></link>. The reverse function, converting a string to a key value,
is provided by <link linkend="gdk-keyval-from-name"><function>gdk_keyval_from_name()</function></link>.</para>
<para>The case of key values can be determined using <link linkend="gdk-keyval-is-upper"><function>gdk_keyval_is_upper()</function></link> and
<link linkend="gdk-keyval-is-lower"><function>gdk_keyval_is_lower()</function></link>. Key values can be converted to upper or lower case
using <link linkend="gdk-keyval-to-upper"><function>gdk_keyval_to_upper()</function></link> and <link linkend="gdk-keyval-to-lower"><function>gdk_keyval_to_lower()</function></link>.</para>
<para>When it makes sense, key values can be converted to and from
Unicode characters with <link linkend="gdk-keyval-to-unicode"><function>gdk_keyval_to_unicode()</function></link> and <link linkend="gdk-unicode-to-keyval"><function>gdk_unicode_to_keyval()</function></link>.</para>
<refsect2 id="key-group-explanation"><title>Groups</title><para>At the lowest level, physical keys on the keyboard are represented by
numeric keycodes, and GDK knows how to translate these keycodes into
key values according to the configured keyboard layout and the current
state of the keyboard. In the GDK api, the mapping from keycodes to key
values is available via <link linkend="gdk-display-map-keycode"><function>gdk_display_map_keycode()</function></link>, and the reverse mapping
is available via <link linkend="gdk-display-map-keyval"><function>gdk_display_map_keyval()</function></link>. The results of these functions
are returned in <link linkend="GdkKeymapKey"><type>GdkKeymapKey</type></link> structs.</para>
<para>You can think of a <link linkend="GdkKeymapKey"><type>GdkKeymapKey</type></link> 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 normally only the uppercase letter
is printed on the key. Third, the <link linkend="GdkKeymapKey"><type>GdkKeymapKey</type></link> 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>
<para>When GDK creates a key event in order to deliver a key press or release,
it first converts the current keyboard state into an effective group and
level. This is done via a set of rules that varies widely according to
type of keyboard and user configuration. The input to this translation
consists of the hardware keycode pressed, the active modifiers, and the
active group. It then applies the appropriate rules, and returns the
group/level to be used to index the keymap, along with the modifiers
which did not affect the group and level. i.e. it returns “unconsumed
modifiers.” The keyboard group may differ from the effective group used
for lookups because some keys don't have multiple groups - e.g. the Enter
key is always in group 0 regardless of keyboard state.</para>
<para>The results of the translation, including the keyval, are all included
in the key event and can be obtained via <link linkend="GdkEvent"><type>GdkEvent</type></link> getters.</para>
</refsect2>
<refsect2><title>Consumed modifiers</title><para>The <parameter>consumed_modifiers</parameter>
 in a key event 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 <literal>plus</literal> symbol is shifted, so when comparing a key
press to a <literal>&lt;Control&gt;plus</literal> accelerator <literal>&lt;Shift&gt;</literal> should be masked out.</para>
<informalexample><programlisting role="example"><![CDATA[
// We want to ignore irrelevant modifiers like ScrollLock
#define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_ALT_MASK)
state = gdk_event_get_modifier_state (event);
gdk_keymap_translate_keyboard_state (keymap,
                                     gdk_key_event_get_keycode (event),
                                     state,
                                     gdk_key_event_get_group (event),
                                     &keyval, NULL, NULL, &consumed);
if (keyval == GDK_PLUS &&
    (state & ~consumed & ALL_ACCELS_MASK) == GDK_CONTROL_MASK)
  // Control was pressed
]]></programlisting></informalexample>
<para></para>
<para>An older interpretation <parameter>consumed_modifiers</parameter>
 was that it contained
all modifiers that might affect the translation of the key;
this allowed accelerators to be stored with irrelevant consumed
modifiers, by doing:</para>
<informalexample><programlisting role="example"><![CDATA[
// XXX Don’t do this XXX
if (keyval == accel_keyval &&
    (state & ~consumed & ALL_ACCELS_MASK) == (accel_mods & ~consumed))
  // Accelerator was pressed
]]></programlisting></informalexample>
<para></para>
<para>However, this did not work if multi-modifier combinations were
used in the keymap, since, for instance, <literal>&lt;Control&gt;</literal> would be
masked out even if only <literal>&lt;Control&gt;&amp;lt;Alt&gt;</literal> was used in the keymap.
To support this usage as well as well as possible, all single
modifier combinations that could affect the key for any combination
of modifiers will be returned in <parameter>consumed_modifiers</parameter>
; 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 <literal>&lt;Control&gt;plus</literal>, not <literal>&lt;Control&gt;&amp;lt;Shift&gt;plus</literal>.</para>
</refsect2>

</refsect1>
<refsect1 id="gdk4-Keyboard-Handling.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gdk-keyval-name" role="function">
<title>gdk_keyval_name&#160;()</title>
<indexterm zone="gdk-keyval-name"><primary>gdk_keyval_name</primary></indexterm>
<programlisting language="C">const <link linkend="char"><returnvalue>char</returnvalue></link>&#160;*
gdk_keyval_name (<parameter><link linkend="guint"><type>guint</type></link> keyval</parameter>);</programlisting>
<para>Converts a key value into a symbolic name.</para>
<para>The names are the same as those in the
<literal>gdk/gdkkeysyms.h</literal> header file
but without the leading “GDK_KEY_”.</para>
<refsect3 id="gdk-keyval-name.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>keyval</para></entry>
<entry role="parameter_description"><para>a key value</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-keyval-name.returns" role="returns">
<title>Returns</title>
<para>a string containing the name
of the key, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if <parameter>keyval</parameter>
is not a valid key. The string
should not be modified. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gdk-keyval-from-name" role="function">
<title>gdk_keyval_from_name&#160;()</title>
<indexterm zone="gdk-keyval-from-name"><primary>gdk_keyval_from_name</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
gdk_keyval_from_name (<parameter>const <link linkend="char"><type>char</type></link> *keyval_name</parameter>);</programlisting>
<para>Converts a key name to a key value.</para>
<para>The names are the same as those in the
<literal>gdk/gdkkeysyms.h</literal> header file
but without the leading “GDK_KEY_”.</para>
<refsect3 id="gdk-keyval-from-name.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>keyval_name</para></entry>
<entry role="parameter_description"><para>a key name</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-keyval-from-name.returns" role="returns">
<title>Returns</title>
<para> the corresponding key value, or <link linkend="GDK-KEY-VoidSymbol"><literal>GDK_KEY_VoidSymbol</literal></link>
if the key name is not a valid key</para>
</refsect3></refsect2>
<refsect2 id="gdk-keyval-convert-case" role="function">
<title>gdk_keyval_convert_case&#160;()</title>
<indexterm zone="gdk-keyval-convert-case"><primary>gdk_keyval_convert_case</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gdk_keyval_convert_case (<parameter><link linkend="guint"><type>guint</type></link> symbol</parameter>,
                         <parameter><link linkend="guint"><type>guint</type></link> *lower</parameter>,
                         <parameter><link linkend="guint"><type>guint</type></link> *upper</parameter>);</programlisting>
<para>Obtains the upper- and lower-case versions of the keyval <parameter>symbol</parameter>
.
Examples of keyvals are <link linkend="GDK-KEY-a"><type>GDK_KEY_a</type></link>, <link linkend="GDK-KEY-Enter"><type>GDK_KEY_Enter</type></link>, <link linkend="GDK-KEY-F1:CAPS"><type>GDK_KEY_F1</type></link>, etc.</para>
<refsect3 id="gdk-keyval-convert-case.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>symbol</para></entry>
<entry role="parameter_description"><para>a keyval</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>lower</para></entry>
<entry role="parameter_description"><para>return location for lowercase version of <parameter>symbol</parameter>
. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>upper</para></entry>
<entry role="parameter_description"><para>return location for uppercase version of <parameter>symbol</parameter>
. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gdk-keyval-to-upper" role="function">
<title>gdk_keyval_to_upper&#160;()</title>
<indexterm zone="gdk-keyval-to-upper"><primary>gdk_keyval_to_upper</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
gdk_keyval_to_upper (<parameter><link linkend="guint"><type>guint</type></link> keyval</parameter>);</programlisting>
<para>Converts a key value to upper case, if applicable.</para>
<refsect3 id="gdk-keyval-to-upper.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>keyval</para></entry>
<entry role="parameter_description"><para>a key value.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-keyval-to-upper.returns" role="returns">
<title>Returns</title>
<para> the upper case form of <parameter>keyval</parameter>
, or <parameter>keyval</parameter>
itself if it is already
in upper case or it is not subject to case conversion.</para>
</refsect3></refsect2>
<refsect2 id="gdk-keyval-to-lower" role="function">
<title>gdk_keyval_to_lower&#160;()</title>
<indexterm zone="gdk-keyval-to-lower"><primary>gdk_keyval_to_lower</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
gdk_keyval_to_lower (<parameter><link linkend="guint"><type>guint</type></link> keyval</parameter>);</programlisting>
<para>Converts a key value to lower case, if applicable.</para>
<refsect3 id="gdk-keyval-to-lower.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>keyval</para></entry>
<entry role="parameter_description"><para>a key value.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-keyval-to-lower.returns" role="returns">
<title>Returns</title>
<para> the lower case form of <parameter>keyval</parameter>
, or <parameter>keyval</parameter>
itself if it is already
in lower case or it is not subject to case conversion.</para>
</refsect3></refsect2>
<refsect2 id="gdk-keyval-is-upper" role="function">
<title>gdk_keyval_is_upper&#160;()</title>
<indexterm zone="gdk-keyval-is-upper"><primary>gdk_keyval_is_upper</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gdk_keyval_is_upper (<parameter><link linkend="guint"><type>guint</type></link> keyval</parameter>);</programlisting>
<para>Returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the given key value is in upper case.</para>
<refsect3 id="gdk-keyval-is-upper.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>keyval</para></entry>
<entry role="parameter_description"><para>a key value.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-keyval-is-upper.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>keyval</parameter>
is in upper case, or if <parameter>keyval</parameter>
is not subject to
case conversion.</para>
</refsect3></refsect2>
<refsect2 id="gdk-keyval-is-lower" role="function">
<title>gdk_keyval_is_lower&#160;()</title>
<indexterm zone="gdk-keyval-is-lower"><primary>gdk_keyval_is_lower</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gdk_keyval_is_lower (<parameter><link linkend="guint"><type>guint</type></link> keyval</parameter>);</programlisting>
<para>Returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the given key value is in lower case.</para>
<refsect3 id="gdk-keyval-is-lower.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>keyval</para></entry>
<entry role="parameter_description"><para>a key value.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-keyval-is-lower.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>keyval</parameter>
is in lower case, or if <parameter>keyval</parameter>
is not
subject to case conversion.</para>
</refsect3></refsect2>
<refsect2 id="gdk-keyval-to-unicode" role="function">
<title>gdk_keyval_to_unicode&#160;()</title>
<indexterm zone="gdk-keyval-to-unicode"><primary>gdk_keyval_to_unicode</primary></indexterm>
<programlisting language="C"><link linkend="guint32"><returnvalue>guint32</returnvalue></link>
gdk_keyval_to_unicode (<parameter><link linkend="guint"><type>guint</type></link> keyval</parameter>);</programlisting>
<para>Convert from a GDK key symbol to the corresponding ISO10646 (Unicode)
character.</para>
<para>Note that the conversion does not take the current locale
into consideration, which might be expected for particular
keyvals, such as <link linkend="GDK-KEY-KP-Decimal"><literal>GDK_KEY_KP_Decimal</literal></link>.</para>
<refsect3 id="gdk-keyval-to-unicode.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>keyval</para></entry>
<entry role="parameter_description"><para>a GDK key symbol</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-keyval-to-unicode.returns" role="returns">
<title>Returns</title>
<para> the corresponding unicode character, or 0 if there
is no corresponding character.</para>
</refsect3></refsect2>
<refsect2 id="gdk-unicode-to-keyval" role="function">
<title>gdk_unicode_to_keyval&#160;()</title>
<indexterm zone="gdk-unicode-to-keyval"><primary>gdk_unicode_to_keyval</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
gdk_unicode_to_keyval (<parameter><link linkend="guint32"><type>guint32</type></link> wc</parameter>);</programlisting>
<para>Convert from a ISO10646 character to a key symbol.</para>
<refsect3 id="gdk-unicode-to-keyval.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>wc</para></entry>
<entry role="parameter_description"><para>a ISO10646 encoded character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-unicode-to-keyval.returns" role="returns">
<title>Returns</title>
<para> the corresponding GDK key symbol, if one exists.
or, if there is no corresponding symbol,
wc | 0x01000000</para>
</refsect3></refsect2>

</refsect1>

</refentry>
