gtk/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>

<!-- ##### ENUM GdkIMStyle ##### -->
<para>
A set of bit-flags used to specify the input method styles which are supported
or which are currently in use. The flags can be divided into 2 groups, the
pre-edit flags and the status flags.
</para>
<para>
The pre-edit flags specify how pre-editing data is displayed.
For example, this could display the text being typed in the phonetic
alphabet before it is composed and inserted as an ideograph.
</para>
<para>
The status flags specify how status information is displayed.
The status information can be thought of as an extension of the
standard keyboard mode indicators, such as the Caps Lock indicator.
</para>
<note>
<para>
The %GDK_IM_PREEDIT_CALLBACKS and %GDK_IM_STATUS_CALLBACKS styles are not 
currently supported in GTK+.
</para>
</note>

@GDK_IM_PREEDIT_AREA: The application provides the input method with an area
in which to perform <emphasis>off-the-spot</emphasis> pre-editing.
@GDK_IM_PREEDIT_CALLBACKS: The application registers a number of callback
functions which are used to display pre-editing data.
@GDK_IM_PREEDIT_POSITION: The application provides the input method with the
position of the insertion cursor, for <emphasis>over-the-spot</emphasis>
pre-editing. The input method creates its own window over the widget to
display the pre-editing data.
@GDK_IM_PREEDIT_NOTHING: The input method uses the root X window to perform
pre-editing, so the application does not need to do anything.
@GDK_IM_PREEDIT_NONE: No pre-editing is done by the input method, or no
pre-editing data needs to be displayed.
@GDK_IM_PREEDIT_MASK: A bit-mask containing all the pre-edit flags.
@GDK_IM_STATUS_AREA: The application provides the input method with an area
in which to display status information.
@GDK_IM_STATUS_CALLBACKS: The applications registers a number of callback
functions which are used to display status information.
@GDK_IM_STATUS_NOTHING: The input method uses the root X window to display
status information, so the application does not need to do anything.
@GDK_IM_STATUS_NONE: The input method does not display status information.
@GDK_IM_STATUS_MASK: A bit-mask containing all the status flags.

<!-- ##### FUNCTION gdk_im_ready ##### -->
<para>
Checks if an input method is to be used for the current locale.
If GTK+ has been compiled without support for input methods, or the current
locale doesn't need an input method, then this will return FALSE.
</para>

@Returns: TRUE if an input method is available and should be used.


<!-- ##### FUNCTION gdk_im_decide_style ##### -->
<para>
Decides which input method style should be used, by comparing the styles given
in @supported_style with those of the available input method.
</para>

@supported_style: styles which are supported by the widget.
@Returns: the best style in @supported_style that is also supported by the
available input method.


<!-- ##### FUNCTION gdk_im_set_best_style ##### -->
<para>
Sets the best pre-edit and/or status style which should be used.
This will affect the style chosen in gdk_im_decide_style().
</para>
<para>
The order of the pre-edit styles is (from worst to best):
%GDK_IM_PREEDIT_NONE, %GDK_IM_PREEDIT_NOTHING, %GDK_IM_PREEDIT_AREA,
%GDK_IM_PREEDIT_POSITION, %GDK_IM_PREEDIT_CALLBACKS.
The order of the status styles is:
%GDK_IM_STATUS_NONE, %GDK_IM_STATUS_NOTHING, %GDK_IM_STATUS_AREA,
%GDK_IM_STATUS_CALLBACKS.
</para>
<para>
So, for example, to set the best allowed pre-edit style to %GDK_IM_PREEDIT_AREA
you would do this:

<informalexample>
<programlisting>
  gdk_im_set_best_style (GDK_IM_PREEDIT_AREA);
</programlisting>
</informalexample>

Or to set the best allowed pre-edit style to %GDK_IM_PREEDIT_POSITION and the
best allowed status style to %GDK_IM_STATUS_NOTHING you can do this:

<informalexample>
<programlisting>
  gdk_im_set_best_style (GDK_IM_PREEDIT_POSITION | GDK_IM_STATUS_NOTHING);
</programlisting>
</informalexample>
</para>

@best_allowed_style: a bit-mask with the best pre-edit style and/or the best
status style to use. If 0 is used, then the current bit-mask of all allowed
styles is returned.
@Returns: a bit-mask of all the styles allowed.


<!-- ##### FUNCTION gdk_im_begin ##### -->
<para>
Starts editing, using the given input context and #GdkWindow.
This should be called when the widget receives the input focus, typically in
the widget's focus_in_event method.
</para>

@ic: a #GdkIC.
@window: the #GdkWindow which will be receiving the key press events.


<!-- ##### FUNCTION gdk_im_end ##### -->
<para>
Stops editing using the input method.
This should be called when the widget loses the input focus, typically in
the widget's focus_out_event method.
</para>