gtk2/docs/reference/gdk/tmpl/input_methods.sgml

<!-- ##### SECTION Title ##### -->
Input Methods

<!-- ##### SECTION Short_Description ##### -->
support for internationalized text input.

<!-- ##### SECTION Long_Description ##### -->
<para>
Input Methods provide a way for complex character sets to be used in GTK+.
Languages such as Chinese, Japanese, and Korean (often abbreviated to CJK)
use a large number of ideographs, making it impossible to support all
characters with a simple keyboard. Instead, text is usually
<emphasis>pre-edited</emphasis> using a phonetic alphabet and then
<emphasis>composed</emphasis> to form the ideographs.
</para>
<para>
GTK+ makes use of the input method mechanism provided by the X Windows
platform. When a GTK+ application is started, it opens a connection to the
input method appropriate for the current locale (if any). 
</para>
<para>
Widgets which handle textual input, such as #GtkEntry, need to do a number of
things to support internationalized text input:
<variablelist>
<varlistentry>
<term>When the widget is realized:</term>
<listitem><para>Check if an input method is being used with gdk_im_ready().
If it is, create a new <link linkend="gdk-Input-Contexts">Input Context</link>
using gdk_ic_new(). Find out which events the
<link linkend="gdk-Input-Contexts">Input Context</link> needs to receive
with gdk_ic_get_events(), and make sure that the widget's window receives
these events using gdk_window_set_events().
</para></listitem>
</varlistentry>

<varlistentry>
<term>When the widget's size, state or cursor position changes:</term>
<listitem><para>
Update the appropriate
<link linkend="gdk-Input-Contexts">Input Context</link> attributes
using gdk_ic_set_attr().
</para></listitem>
</varlistentry>

<varlistentry>
<term>When the keyboard focus enters or leaves the widget:</term>
<listitem><para>
Call gdk_im_begin() or gdk_im_end() to start or finish editing the text.
</para></listitem>
</varlistentry>

<varlistentry>
<term>When the widget receives a key_press event:</term>
<listitem><para>
The <structfield>string</structfield> and <structfield>length</structfield>
fields of the #GdkEventKey struct should be used to insert the composed text
into the widget.
</para></listitem>
</varlistentry>

<varlistentry>
<term>When the widget is unrealized:</term>
<listitem><para>
Destroy the <link linkend="gdk-Input-Contexts">Input Context</link>.
</para></listitem>
</varlistentry>
</variablelist>

</para>
<para>
See the XLib reference manual for more detailed information on input methods,
and the #GtkEntry and #GtkText widgets for some example code.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term><link linkend="gdk-Input-Contexts">Input Contexts</link></term>
<listitem><para>
Used for each widget that handles internationalized text input using the
global input method.
</para></listitem>
</varlistentry>
</variablelist>

</para>