forked from AuroraMiddleware/gtk
50ab749f4b
2000-02-02 Damon Chaplin <damon@karuna.freeserve.co.uk>
* gdk/tmpl/*.sgml: ran make templates.
* gdk/gdk-docs.sgml: rearranged sections.
* gdk/tmpl/events.sgml: documented.
* gdk/tmpl/general.sgml: documented.
* gdk/tmpl/rgb.sgml: fixed a few '@' -> '#'.
* gdk/gdk-sections.txt: rearranged a few bits, including moving
GdkWChar and related functions from the input method section to the
font section, and GdkCapStyle etc. from Drawing Primitives to GCs.
* gdk/tmpl/images.sgml: documented.
* gdk/tmpl/drawing.sgml: updated.
* gdk/tmpl/regions.sgml: updated.
* gdk/tmpl/input_contexts.sgml: documented.
* gdk/tmpl/input_methods.sgml: documented.
* gdk/tmpl/selections.sgml: changed xref to a link since Jade says
a xref to a RefEntry is not supported.
214 lines
7.4 KiB
Plaintext
214 lines
7.4 KiB
Plaintext
<!-- ##### 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 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 #GdkInputContext 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 #GdkInputContext.
|
|
@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>
|
|
|
|
|
|
|