1 /* GTK - The GIMP Toolkit
2 * Copyright (C) 2000 Red Hat, Inc.
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
20 #include "gtkimcontext.h"
21 #include "gtkprivate.h"
22 #include "gtktypebuiltins.h"
23 #include "gtkmarshalers.h"
27 * SECTION:gtkimcontext
28 * @title: GtkIMContext
29 * @short_description: Base class for input method contexts
30 * @include: gtk/gtk.h,gtk/gtkimmodule.h
32 * #GtkIMContext defines the interface for GTK+ input methods. An input method
33 * is used by GTK+ text input widgets like #GtkEntry to map from key events to
34 * Unicode character strings.
36 * The user may change the current input method via a context menu, unless the
37 * #GtkSettings:gtk-show-input-method-menu GtkSettings property is set to FALSE.
38 * The default input method can be set programmatically via the
39 * #GtkSettings:gtk-im-module GtkSettings property. Alternatively, you may set
40 * the GTK_IM_MODULE environment variable as documented in #gtk-running.
42 * The #GtkEntry #GtkEntry:im-module and #GtkTextView #GtkTextView:im-module
43 * properties may also be used to set input methods for specific widget
44 * instances. For instance, a certain entry widget might be expected to contain
45 * certain characters which would be easier to input with a certain input
48 * An input method may consume multiple key events in sequence and finally
49 * output the composed result. This is called preediting, and an input method
50 * may provide feedback about this process by displaying the intermediate
51 * composition states as preedit text. For instance, the default GTK+ input
52 * method implements the input of arbitrary Unicode code points by holding down
53 * the Control and Shift keys and then typing "U" followed by the hexadecimal
54 * digits of the code point. When releasing the Control and Shift keys,
55 * preediting ends and the character is inserted as text. Ctrl+Shift+u20AC for
56 * example results in the € sign.
58 * Additional input methods can be made available for use by GTK+ widgets as
59 * loadable modules. An input method module is a small shared library which
60 * implements a subclass of #GtkIMContext or #GtkIMContextSimple and exports
61 * these four functions:
63 * <informalexample><programlisting>
64 * void im_module_init(#GTypeModule *module);
65 * </programlisting></informalexample>
66 * This function should register the #GType of the #GtkIMContext subclass which
67 * implements the input method by means of g_type_module_register_type(). Note
68 * that g_type_register_static() cannot be used as the type needs to be
69 * registered dynamically.
71 * <informalexample><programlisting>
72 * void im_module_exit(void);
73 * </programlisting></informalexample>
74 * Here goes any cleanup code your input method might require on module unload.
76 * <informalexample><programlisting>
77 * void im_module_list(const #GtkIMContextInfo ***contexts, int *n_contexts)
79 * *contexts = info_list;
80 * *n_contexts = G_N_ELEMENTS (info_list);
82 * </programlisting></informalexample>
83 * This function returns the list of input methods provided by the module. The
84 * example implementation above shows a common solution and simply returns a
85 * pointer to statically defined array of #GtkIMContextInfo items for each
86 * provided input method.
88 * <informalexample><programlisting>
89 * #GtkIMContext * im_module_create(const #gchar *context_id);
90 * </programlisting></informalexample>
91 * This function should return a pointer to a newly created instance of the
92 * #GtkIMContext subclass identified by @context_id. The context ID is the same
93 * as specified in the #GtkIMContextInfo array returned by im_module_list().
95 * After a new loadable input method module has been installed on the system,
96 * the configuration file <filename>gtk.immodules</filename> needs to be
97 * regenerated by <link linkend="gtk-query-immodules-3.0">gtk-query-immodules-3.0</link>,
98 * in order for the new input method to become available to GTK+ applications.
106 RETRIEVE_SURROUNDING,
112 PROP_INPUT_PURPOSE = 1,
117 static guint im_context_signals[LAST_SIGNAL] = { 0, };
118 static GParamSpec *properties[LAST_PROPERTY] = { NULL, };
120 typedef struct _GtkIMContextPrivate GtkIMContextPrivate;
121 struct _GtkIMContextPrivate {
122 GtkInputPurpose purpose;
126 static void gtk_im_context_real_get_preedit_string (GtkIMContext *context,
128 PangoAttrList **attrs,
130 static gboolean gtk_im_context_real_filter_keypress (GtkIMContext *context,
132 static gboolean gtk_im_context_real_get_surrounding (GtkIMContext *context,
135 static void gtk_im_context_real_set_surrounding (GtkIMContext *context,
140 static void gtk_im_context_get_property (GObject *obj,
144 static void gtk_im_context_set_property (GObject *obj,
150 G_DEFINE_ABSTRACT_TYPE (GtkIMContext, gtk_im_context, G_TYPE_OBJECT)
154 * @preedit_start: Default handler of the #GtkIMContext::preedit-start signal.
155 * @preedit_end: Default handler of the #GtkIMContext::preedit-end signal.
156 * @preedit_changed: Default handler of the #GtkIMContext::preedit-changed
158 * @commit: Default handler of the #GtkIMContext::commit signal.
159 * @retrieve_surrounding: Default handler of the
160 * #GtkIMContext::retrieve-surrounding signal.
161 * @delete_surrounding: Default handler of the
162 * #GtkIMContext::delete-surrounding signal.
163 * @set_client_window: Called via gtk_im_context_set_client_window() when the
164 * input window where the entered text will appear changes. Override this to
165 * keep track of the current input window, for instance for the purpose of
166 * positioning a status display of your input method.
167 * @get_preedit_string: Called via gtk_im_context_get_preedit_string() to
168 * retrieve the text currently being preedited for display at the cursor
169 * position. Any input method which composes complex characters or any
170 * other compositions from multiple sequential key presses should override
171 * this method to provide feedback.
172 * @filter_keypress: Called via gtk_im_context_filter_keypress() on every
173 * key press or release event. Every non-trivial input method needs to
174 * override this in order to implement the mapping from key events to text.
175 * A return value of %TRUE indicates to the caller that the event was
176 * consumed by the input method. In that case, the #GtkIMContext::commit
177 * signal should be emitted upon completion of a key sequence to pass the
178 * resulting text back to the input widget. Alternatively, %FALSE may be
179 * returned to indicate that the event wasn't handled by the input method.
180 * If a builtin mapping exists for the key, it is used to produce a
182 * @focus_in: Called via gtk_im_context_focus_in() when the input widget
183 * has gained focus. May be overridden to keep track of the current focus.
184 * @focus_out: Called via gtk_im_context_focus_out() when the input widget
185 * has lost focus. May be overridden to keep track of the current focus.
186 * @reset: Called via gtk_im_context_reset() to signal a change such as a
187 * change in cursor position. An input method that implements preediting
188 * should override this method to clear the preedit state on reset.
189 * @set_cursor_location: Called via gtk_im_context_set_cursor_location()
190 * to inform the input method of the current cursor location relative to
191 * the client window. May be overridden to implement the display of popup
192 * windows at the cursor position.
193 * @set_use_preedit: Called via gtk_im_context_set_use_preedit() to control
194 * the use of the preedit string. Override this to display feedback by some
195 * other means if turned off.
196 * @set_surrounding: Called via gtk_im_context_set_surrounding() in response
197 * to signal #GtkIMContext::retrieve-surrounding to update the input
198 * method's idea of the context around the cursor. It is not necessary to
199 * override this method even with input methods which implement
200 * context-dependent behavior. The base implementation is sufficient for
201 * gtk_im_context_get_surrounding() to work.
202 * @get_surrounding: Called via gtk_im_context_get_surrounding() to update
203 * the context around the cursor location. It is not necessary to override
204 * this method even with input methods which implement context-dependent
205 * behavior. The base implementation emits
206 * #GtkIMContext::retrieve-surrounding and records the context received
207 * by the subsequent invocation of @get_surrounding.
210 gtk_im_context_class_init (GtkIMContextClass *klass)
212 GObjectClass *object_class = G_OBJECT_CLASS (klass);
214 object_class->get_property = gtk_im_context_get_property;
215 object_class->set_property = gtk_im_context_set_property;
217 klass->get_preedit_string = gtk_im_context_real_get_preedit_string;
218 klass->filter_keypress = gtk_im_context_real_filter_keypress;
219 klass->get_surrounding = gtk_im_context_real_get_surrounding;
220 klass->set_surrounding = gtk_im_context_real_set_surrounding;
223 * GtkIMContext::preedit-start:
224 * @context: the object on which the signal is emitted
226 * The ::preedit-start signal is emitted when a new preediting sequence
229 im_context_signals[PREEDIT_START] =
230 g_signal_new (I_("preedit-start"),
231 G_TYPE_FROM_CLASS (klass),
233 G_STRUCT_OFFSET (GtkIMContextClass, preedit_start),
235 _gtk_marshal_VOID__VOID,
238 * GtkIMContext::preedit-end:
239 * @context: the object on which the signal is emitted
241 * The ::preedit-end signal is emitted when a preediting sequence
242 * has been completed or canceled.
244 im_context_signals[PREEDIT_END] =
245 g_signal_new (I_("preedit-end"),
246 G_TYPE_FROM_CLASS (klass),
248 G_STRUCT_OFFSET (GtkIMContextClass, preedit_end),
250 _gtk_marshal_VOID__VOID,
253 * GtkIMContext::preedit-changed:
254 * @context: the object on which the signal is emitted
256 * The ::preedit-changed signal is emitted whenever the preedit sequence
257 * currently being entered has changed. It is also emitted at the end of
258 * a preedit sequence, in which case
259 * gtk_im_context_get_preedit_string() returns the empty string.
261 im_context_signals[PREEDIT_CHANGED] =
262 g_signal_new (I_("preedit-changed"),
263 G_TYPE_FROM_CLASS (klass),
265 G_STRUCT_OFFSET (GtkIMContextClass, preedit_changed),
267 _gtk_marshal_VOID__VOID,
270 * GtkIMContext::commit:
271 * @context: the object on which the signal is emitted
272 * @str: the completed character(s) entered by the user
274 * The ::commit signal is emitted when a complete input sequence
275 * has been entered by the user. This can be a single character
276 * immediately after a key press or the final result of preediting.
278 im_context_signals[COMMIT] =
279 g_signal_new (I_("commit"),
280 G_TYPE_FROM_CLASS (klass),
282 G_STRUCT_OFFSET (GtkIMContextClass, commit),
284 _gtk_marshal_VOID__STRING,
288 * GtkIMContext::retrieve-surrounding:
289 * @context: the object on which the signal is emitted
291 * The ::retrieve-surrounding signal is emitted when the input method
292 * requires the context surrounding the cursor. The callback should set
293 * the input method surrounding context by calling the
294 * gtk_im_context_set_surrounding() method.
296 * Return value: %TRUE if the signal was handled.
298 im_context_signals[RETRIEVE_SURROUNDING] =
299 g_signal_new (I_("retrieve-surrounding"),
300 G_TYPE_FROM_CLASS (klass),
302 G_STRUCT_OFFSET (GtkIMContextClass, retrieve_surrounding),
303 _gtk_boolean_handled_accumulator, NULL,
304 _gtk_marshal_BOOLEAN__VOID,
307 * GtkIMContext::delete-surrounding:
308 * @context: the object on which the signal is emitted
309 * @offset: the character offset from the cursor position of the text
310 * to be deleted. A negative value indicates a position before
312 * @n_chars: the number of characters to be deleted
314 * The ::delete-surrounding signal is emitted when the input method
315 * needs to delete all or part of the context surrounding the cursor.
317 * Return value: %TRUE if the signal was handled.
319 im_context_signals[DELETE_SURROUNDING] =
320 g_signal_new (I_("delete-surrounding"),
321 G_TYPE_FROM_CLASS (klass),
323 G_STRUCT_OFFSET (GtkIMContextClass, delete_surrounding),
324 _gtk_boolean_handled_accumulator, NULL,
325 _gtk_marshal_BOOLEAN__INT_INT,
330 properties[PROP_INPUT_PURPOSE] =
331 g_param_spec_enum ("input-purpose",
333 P_("Purpose of the text field"),
334 GTK_TYPE_INPUT_PURPOSE,
335 GTK_INPUT_PURPOSE_FREE_FORM,
336 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
338 properties[PROP_INPUT_HINTS] =
339 g_param_spec_flags ("input-hints",
341 P_("Hints for the text field behaviour"),
342 GTK_TYPE_INPUT_HINTS,
344 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
346 g_type_class_add_private (klass, sizeof (GtkIMContextPrivate));
347 g_object_class_install_properties (object_class, LAST_PROPERTY, properties);
351 gtk_im_context_init (GtkIMContext *im_context)
356 gtk_im_context_real_get_preedit_string (GtkIMContext *context,
358 PangoAttrList **attrs,
362 *str = g_strdup ("");
364 *attrs = pango_attr_list_new ();
370 gtk_im_context_real_filter_keypress (GtkIMContext *context,
383 gtk_im_context_real_set_surrounding (GtkIMContext *context,
388 SurroundingInfo *info = g_object_get_data (G_OBJECT (context),
389 "gtk-im-surrounding-info");
394 info->text = g_strndup (text, len);
395 info->cursor_index = cursor_index;
400 gtk_im_context_real_get_surrounding (GtkIMContext *context,
405 gboolean info_is_local = FALSE;
406 SurroundingInfo local_info = { NULL, 0 };
407 SurroundingInfo *info;
409 info = g_object_get_data (G_OBJECT (context), "gtk-im-surrounding-info");
413 g_object_set_data (G_OBJECT (context), I_("gtk-im-surrounding-info"), info);
414 info_is_local = TRUE;
417 g_signal_emit (context,
418 im_context_signals[RETRIEVE_SURROUNDING], 0,
423 *text = g_strdup (info->text ? info->text : "");
424 *cursor_index = info->cursor_index;
435 g_object_set_data (G_OBJECT (context), I_("gtk-im-surrounding-info"), NULL);
442 * gtk_im_context_set_client_window:
443 * @context: a #GtkIMContext
444 * @window: (allow-none): the client window. This may be %NULL to indicate
445 * that the previous client window no longer exists.
447 * Set the client window for the input context; this is the
448 * #GdkWindow in which the input appears. This window is
449 * used in order to correctly position status windows, and may
450 * also be used for purposes internal to the input method.
453 gtk_im_context_set_client_window (GtkIMContext *context,
456 GtkIMContextClass *klass;
458 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
460 klass = GTK_IM_CONTEXT_GET_CLASS (context);
461 if (klass->set_client_window)
462 klass->set_client_window (context, window);
466 * gtk_im_context_get_preedit_string:
467 * @context: a #GtkIMContext
468 * @str: (out) (transfer full): location to store the retrieved
469 * string. The string retrieved must be freed with g_free().
470 * @attrs: (out) (transfer full): location to store the retrieved
471 * attribute list. When you are done with this list, you
472 * must unreference it with pango_attr_list_unref().
473 * @cursor_pos: (out): location to store position of cursor (in characters)
474 * within the preedit string.
476 * Retrieve the current preedit string for the input context,
477 * and a list of attributes to apply to the string.
478 * This string should be displayed inserted at the insertion
482 gtk_im_context_get_preedit_string (GtkIMContext *context,
484 PangoAttrList **attrs,
487 GtkIMContextClass *klass;
489 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
491 klass = GTK_IM_CONTEXT_GET_CLASS (context);
492 klass->get_preedit_string (context, str, attrs, cursor_pos);
493 g_return_if_fail (str == NULL || g_utf8_validate (*str, -1, NULL));
497 * gtk_im_context_filter_keypress:
498 * @context: a #GtkIMContext
499 * @event: the key event
501 * Allow an input method to internally handle key press and release
502 * events. If this function returns %TRUE, then no further processing
503 * should be done for this key event.
505 * Return value: %TRUE if the input method handled the key event.
509 gtk_im_context_filter_keypress (GtkIMContext *context,
512 GtkIMContextClass *klass;
514 g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
515 g_return_val_if_fail (key != NULL, FALSE);
517 klass = GTK_IM_CONTEXT_GET_CLASS (context);
518 return klass->filter_keypress (context, key);
522 * gtk_im_context_focus_in:
523 * @context: a #GtkIMContext
525 * Notify the input method that the widget to which this
526 * input context corresponds has gained focus. The input method
527 * may, for example, change the displayed feedback to reflect
531 gtk_im_context_focus_in (GtkIMContext *context)
533 GtkIMContextClass *klass;
535 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
537 klass = GTK_IM_CONTEXT_GET_CLASS (context);
539 klass->focus_in (context);
543 * gtk_im_context_focus_out:
544 * @context: a #GtkIMContext
546 * Notify the input method that the widget to which this
547 * input context corresponds has lost focus. The input method
548 * may, for example, change the displayed feedback or reset the contexts
549 * state to reflect this change.
552 gtk_im_context_focus_out (GtkIMContext *context)
554 GtkIMContextClass *klass;
556 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
558 klass = GTK_IM_CONTEXT_GET_CLASS (context);
559 if (klass->focus_out)
560 klass->focus_out (context);
564 * gtk_im_context_reset:
565 * @context: a #GtkIMContext
567 * Notify the input method that a change such as a change in cursor
568 * position has been made. This will typically cause the input
569 * method to clear the preedit state.
572 gtk_im_context_reset (GtkIMContext *context)
574 GtkIMContextClass *klass;
576 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
578 klass = GTK_IM_CONTEXT_GET_CLASS (context);
580 klass->reset (context);
585 * gtk_im_context_set_cursor_location:
586 * @context: a #GtkIMContext
587 * @area: new location
589 * Notify the input method that a change in cursor
590 * position has been made. The location is relative to the client
594 gtk_im_context_set_cursor_location (GtkIMContext *context,
595 const GdkRectangle *area)
597 GtkIMContextClass *klass;
599 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
601 klass = GTK_IM_CONTEXT_GET_CLASS (context);
602 if (klass->set_cursor_location)
603 klass->set_cursor_location (context, (GdkRectangle *) area);
607 * gtk_im_context_set_use_preedit:
608 * @context: a #GtkIMContext
609 * @use_preedit: whether the IM context should use the preedit string.
611 * Sets whether the IM context should use the preedit string
612 * to display feedback. If @use_preedit is FALSE (default
613 * is TRUE), then the IM context may use some other method to display
614 * feedback, such as displaying it in a child of the root window.
617 gtk_im_context_set_use_preedit (GtkIMContext *context,
618 gboolean use_preedit)
620 GtkIMContextClass *klass;
622 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
624 klass = GTK_IM_CONTEXT_GET_CLASS (context);
625 if (klass->set_use_preedit)
626 klass->set_use_preedit (context, use_preedit);
630 * gtk_im_context_set_surrounding:
631 * @context: a #GtkIMContext
632 * @text: text surrounding the insertion point, as UTF-8.
633 * the preedit string should not be included within
635 * @len: the length of @text, or -1 if @text is nul-terminated
636 * @cursor_index: the byte index of the insertion cursor within @text.
638 * Sets surrounding context around the insertion point and preedit
639 * string. This function is expected to be called in response to the
640 * GtkIMContext::retrieve_surrounding signal, and will likely have no
641 * effect if called at other times.
644 gtk_im_context_set_surrounding (GtkIMContext *context,
649 GtkIMContextClass *klass;
651 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
652 g_return_if_fail (text != NULL || len == 0);
654 if (text == NULL && len == 0)
659 g_return_if_fail (cursor_index >= 0 && cursor_index <= len);
661 klass = GTK_IM_CONTEXT_GET_CLASS (context);
662 if (klass->set_surrounding)
663 klass->set_surrounding (context, text, len, cursor_index);
667 * gtk_im_context_get_surrounding:
668 * @context: a #GtkIMContext
669 * @text: (out) (transfer full): location to store a UTF-8 encoded
670 * string of text holding context around the insertion point.
671 * If the function returns %TRUE, then you must free the result
672 * stored in this location with g_free().
673 * @cursor_index: (out): location to store byte index of the insertion
674 * cursor within @text.
676 * Retrieves context around the insertion point. Input methods
677 * typically want context in order to constrain input text based on
678 * existing text; this is important for languages such as Thai where
679 * only some sequences of characters are allowed.
681 * This function is implemented by emitting the
682 * GtkIMContext::retrieve_surrounding signal on the input method; in
683 * response to this signal, a widget should provide as much context as
684 * is available, up to an entire paragraph, by calling
685 * gtk_im_context_set_surrounding(). Note that there is no obligation
686 * for a widget to respond to the ::retrieve_surrounding signal, so input
687 * methods must be prepared to function without context.
689 * Return value: %TRUE if surrounding text was provided; in this case
690 * you must free the result stored in *text.
693 gtk_im_context_get_surrounding (GtkIMContext *context,
697 GtkIMContextClass *klass;
698 gchar *local_text = NULL;
700 gboolean result = FALSE;
702 g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
704 klass = GTK_IM_CONTEXT_GET_CLASS (context);
705 if (klass->get_surrounding)
706 result = klass->get_surrounding (context,
707 text ? text : &local_text,
708 cursor_index ? cursor_index : &local_index);
717 * gtk_im_context_delete_surrounding:
718 * @context: a #GtkIMContext
719 * @offset: offset from cursor position in chars;
720 * a negative value means start before the cursor.
721 * @n_chars: number of characters to delete.
723 * Asks the widget that the input context is attached to to delete
724 * characters around the cursor position by emitting the
725 * GtkIMContext::delete_surrounding signal. Note that @offset and @n_chars
726 * are in characters not in bytes which differs from the usage other
727 * places in #GtkIMContext.
729 * In order to use this function, you should first call
730 * gtk_im_context_get_surrounding() to get the current context, and
731 * call this function immediately afterwards to make sure that you
732 * know what you are deleting. You should also account for the fact
733 * that even if the signal was handled, the input context might not
734 * have deleted all the characters that were requested to be deleted.
736 * This function is used by an input method that wants to make
737 * subsitutions in the existing text in response to new input. It is
738 * not useful for applications.
740 * Return value: %TRUE if the signal was handled.
743 gtk_im_context_delete_surrounding (GtkIMContext *context,
749 g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
751 g_signal_emit (context,
752 im_context_signals[DELETE_SURROUNDING], 0,
753 offset, n_chars, &result);
759 gtk_im_context_get_property (GObject *obj,
764 GtkIMContextPrivate *priv = G_TYPE_INSTANCE_GET_PRIVATE (obj, GTK_TYPE_IM_CONTEXT, GtkIMContextPrivate);
768 case PROP_INPUT_PURPOSE:
769 g_value_set_enum (value, priv->purpose);
771 case PROP_INPUT_HINTS:
772 g_value_set_flags (value, priv->hints);
775 G_OBJECT_WARN_INVALID_PROPERTY_ID (obj, property_id, pspec);
781 gtk_im_context_set_property (GObject *obj,
786 GtkIMContextPrivate *priv = G_TYPE_INSTANCE_GET_PRIVATE (obj, GTK_TYPE_IM_CONTEXT, GtkIMContextPrivate);
790 case PROP_INPUT_PURPOSE:
791 priv->purpose = g_value_get_enum (value);
793 case PROP_INPUT_HINTS:
794 priv->hints = g_value_get_flags (value);
797 G_OBJECT_WARN_INVALID_PROPERTY_ID (obj, property_id, pspec);