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, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
20 #include "gtkimcontext.h"
21 #include "gtkmain.h" /* For _gtk_boolean_handled_accumulator */
22 #include "gtkmarshalers.h"
23 #include "gtksignal.h"
36 static guint im_context_signals[LAST_SIGNAL] = { 0 };
38 static void gtk_im_context_class_init (GtkIMContextClass *class);
39 static void gtk_im_context_init (GtkIMContext *im_context);
41 static void gtk_im_context_real_get_preedit_string (GtkIMContext *context,
43 PangoAttrList **attrs,
45 static gboolean gtk_im_context_real_filter_keypress (GtkIMContext *context,
47 static gboolean gtk_im_context_real_get_surrounding (GtkIMContext *context,
50 static void gtk_im_context_real_set_surrounding (GtkIMContext *context,
56 gtk_im_context_get_type (void)
58 static GtkType im_context_type = 0;
62 static const GTypeInfo im_context_info =
64 sizeof (GtkIMContextClass),
66 (GBaseFinalizeFunc) NULL,
67 (GClassInitFunc) gtk_im_context_class_init,
68 NULL, /* class_finalize */
69 NULL, /* class_data */
70 sizeof (GtkIMContext),
72 (GInstanceInitFunc) gtk_im_context_init,
75 im_context_type = g_type_register_static (G_TYPE_OBJECT,
80 return im_context_type;
84 gtk_im_context_class_init (GtkIMContextClass *klass)
86 GtkObjectClass *object_class;
88 object_class = (GtkObjectClass*) klass;
90 klass->get_preedit_string = gtk_im_context_real_get_preedit_string;
91 klass->filter_keypress = gtk_im_context_real_filter_keypress;
92 klass->get_surrounding = gtk_im_context_real_get_surrounding;
93 klass->set_surrounding = gtk_im_context_real_set_surrounding;
95 im_context_signals[PREEDIT_START] =
96 gtk_signal_new ("preedit_start",
98 GTK_CLASS_TYPE (object_class),
99 GTK_SIGNAL_OFFSET (GtkIMContextClass, preedit_start),
100 _gtk_marshal_VOID__VOID,
103 im_context_signals[PREEDIT_END] =
104 gtk_signal_new ("preedit_end",
106 GTK_CLASS_TYPE (object_class),
107 GTK_SIGNAL_OFFSET (GtkIMContextClass, preedit_end),
108 _gtk_marshal_VOID__VOID,
111 im_context_signals[PREEDIT_CHANGED] =
112 gtk_signal_new ("preedit_changed",
114 GTK_CLASS_TYPE (object_class),
115 GTK_SIGNAL_OFFSET (GtkIMContextClass, preedit_changed),
116 _gtk_marshal_VOID__VOID,
119 im_context_signals[COMMIT] =
120 gtk_signal_new ("commit",
122 GTK_CLASS_TYPE (object_class),
123 GTK_SIGNAL_OFFSET (GtkIMContextClass, commit),
124 _gtk_marshal_VOID__STRING,
128 im_context_signals[RETRIEVE_SURROUNDING] =
129 g_signal_new ("retrieve_surrounding",
130 GTK_CLASS_TYPE (object_class),
132 GTK_SIGNAL_OFFSET (GtkIMContextClass, retrieve_surrounding),
133 _gtk_boolean_handled_accumulator, NULL,
134 _gtk_marshal_BOOLEAN__VOID,
136 im_context_signals[DELETE_SURROUNDING] =
137 g_signal_new ("delete_surrounding",
138 GTK_CLASS_TYPE (object_class),
140 GTK_SIGNAL_OFFSET (GtkIMContextClass, delete_surrounding),
141 _gtk_boolean_handled_accumulator, NULL,
142 _gtk_marshal_BOOLEAN__INT_INT,
149 gtk_im_context_init (GtkIMContext *im_context)
154 gtk_im_context_real_get_preedit_string (GtkIMContext *context,
156 PangoAttrList **attrs,
160 *str = g_strdup ("");
162 *attrs = pango_attr_list_new ();
168 gtk_im_context_real_filter_keypress (GtkIMContext *context,
181 gtk_im_context_real_set_surrounding (GtkIMContext *context,
186 SurroundingInfo *info = g_object_get_data (G_OBJECT (context), "gtk-im-surrounding-info");
191 info->text = g_strndup (text, len);
192 info->cursor_index = cursor_index;
197 gtk_im_context_real_get_surrounding (GtkIMContext *context,
202 gboolean info_is_local = FALSE;
203 SurroundingInfo local_info = { NULL, 0 };
204 SurroundingInfo *info;
206 info = g_object_get_data (G_OBJECT (context), "gtk-im-surrounding-info");
210 g_object_set_data (G_OBJECT (context), "gtk-im-surrounding-info", info);
211 info_is_local = TRUE;
214 g_signal_emit (context,
215 im_context_signals[RETRIEVE_SURROUNDING], 0,
220 *text = g_strdup (info->text ? info->text : "");
221 *cursor_index = info->cursor_index;
236 * gtk_im_context_set_client_window:
237 * @context: a #GtkIMContext
238 * @window: the client window. This may be %NULL to indicate
239 * that the previous client window no longer exists.
241 * Set the client window for the input context; this is the
242 * #GdkWindow in which the input appears. This window is
243 * used in order to correctly position status windows, and may
244 * also be used for purposes internal to the input method.
247 gtk_im_context_set_client_window (GtkIMContext *context,
250 GtkIMContextClass *klass;
252 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
254 klass = GTK_IM_CONTEXT_GET_CLASS (context);
255 if (klass->set_client_window)
256 klass->set_client_window (context, window);
260 * gtk_im_context_get_preedit_string:
261 * @context: a #GtkIMContext
262 * @str: location to store the retrieved string. The
263 * string retrieved must be freed with g_free ().
264 * @attrs: location to store the retrieved attribute list.
265 * When you are done with this list, you must
266 * unreference it with pango_attr_list_unref().
267 * @cursor_pos: location to store position of cursor (in bytes)
268 * within the preedit string.
270 * Retrieve the current preedit string for the input context,
271 * and a list of attributes to apply to the string.
272 * This string should be displayed inserted at the insertion
276 gtk_im_context_get_preedit_string (GtkIMContext *context,
278 PangoAttrList **attrs,
281 GtkIMContextClass *klass;
283 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
285 klass = GTK_IM_CONTEXT_GET_CLASS (context);
286 klass->get_preedit_string (context, str, attrs, cursor_pos);
287 g_return_if_fail (str == NULL || g_utf8_validate (*str, -1, NULL));
291 * gtk_im_context_filter_keypress:
292 * @context: a #GtkIMContext
293 * @event: the key event
295 * Allow an input method to internally handle a key press event.
296 * If this function returns %TRUE, then no further processing
297 * should be done for this keystroke.
299 * Return value: %TRUE if the input method handled the keystroke.
303 gtk_im_context_filter_keypress (GtkIMContext *context,
306 GtkIMContextClass *klass;
308 g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
309 g_return_val_if_fail (key != NULL, FALSE);
311 klass = GTK_IM_CONTEXT_GET_CLASS (context);
312 return klass->filter_keypress (context, key);
316 * gtk_im_context_focus_in:
317 * @context: a #GtkIMContext
319 * Notify the input method that the widget to which this
320 * input context corresponds has lost gained. The input method
321 * may, for example, change the displayed feedback to reflect
325 gtk_im_context_focus_in (GtkIMContext *context)
327 GtkIMContextClass *klass;
329 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
331 klass = GTK_IM_CONTEXT_GET_CLASS (context);
333 klass->focus_in (context);
337 * gtk_im_context_focus_out:
338 * @context: a #GtkIMContext
340 * Notify the input method that the widget to which this
341 * input context corresponds has lost focus. The input method
342 * may, for example, change the displayed feedback or reset the contexts
343 * state to reflect this change.
346 gtk_im_context_focus_out (GtkIMContext *context)
348 GtkIMContextClass *klass;
350 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
352 klass = GTK_IM_CONTEXT_GET_CLASS (context);
353 if (klass->focus_out)
354 klass->focus_out (context);
358 * gtk_im_context_reset:
359 * @context: a #GtkIMContext
361 * Notify the input method that a change such as a change in cursor
362 * position has been made. This will typically cause the input
363 * method to clear the preedit state.
366 gtk_im_context_reset (GtkIMContext *context)
368 GtkIMContextClass *klass;
370 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
372 klass = GTK_IM_CONTEXT_GET_CLASS (context);
374 klass->reset (context);
379 * gtk_im_context_set_cursor_location:
380 * @context: a #GtkIMContext
381 * @area: new location
383 * Notify the input method that a change in cursor
384 * position has been made.
387 gtk_im_context_set_cursor_location (GtkIMContext *context,
390 GtkIMContextClass *klass;
392 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
394 klass = GTK_IM_CONTEXT_GET_CLASS (context);
395 if (klass->set_cursor_location)
396 klass->set_cursor_location (context, area);
400 * gtk_im_context_set_use_preedit:
401 * @context: a #GtkIMContext
402 * @use_preedit: whether the IM context should use the preedit string.
404 * Sets whether the IM context should use the preedit string
405 * to display feedback. If @use_preedit is FALSE (default
406 * is TRUE), then the IM context may use some other method to display
407 * feedback, such as displaying it in a child of the root window.
410 gtk_im_context_set_use_preedit (GtkIMContext *context,
411 gboolean use_preedit)
413 GtkIMContextClass *klass;
415 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
417 klass = GTK_IM_CONTEXT_GET_CLASS (context);
418 if (klass->set_use_preedit)
419 klass->set_use_preedit (context, use_preedit);
423 * gtk_im_context_set_surrounding:
424 * @context: a #GtkIMContext
425 * @text: text surrounding the insertion point, as UTF-8.
426 * the preedit string should not be included within
428 * @len: the length of @text, or -1 if @text is nul-terminated
429 * @cursor_index: the byte index of the insertion cursor within @text.
431 * Sets surrounding context around the insertion point and preedit
432 * string. This function is expected to be called in response to the
433 * GtkIMContext::retrieve_context signal, and will likely have no
434 * effect if called at other times.
437 gtk_im_context_set_surrounding (GtkIMContext *context,
442 GtkIMContextClass *klass;
444 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
445 g_return_if_fail (text != NULL || len == 0);
447 if (text == NULL && len == 0)
452 g_return_if_fail (cursor_index >= 0 && cursor_index <= len);
454 klass = GTK_IM_CONTEXT_GET_CLASS (context);
455 if (klass->set_surrounding)
456 klass->set_surrounding (context, text, len, cursor_index);
460 * gtk_im_context_get_surrounding:
461 * @context: a #GtkIMContext
462 * @text: location to store a UTF-8 encoded string of text
463 * holding context around the insertion point.
464 * If the function returns %TRUE, then you must free
465 * the result stored in this location with g_free().
466 * @cursor_index: location to store byte index of the insertion cursor
469 * Retrieves context around the insertion point. Input methods
470 * typically want context in order to constrain input text based on
471 * existing text; this is important for languages such as Thai where
472 * only some sequences of characters are allowed.
474 * This function is implemented by emitting the
475 * GtkIMContext::retrieve_context signal on the input method; in
476 * response to this signal, a widget should provide as much context as
477 * is available, up to an entire paragraph, by calling
478 * gtk_im_context_set_surrounding(). Note that there is no obligation
479 * for a widget to respond to the ::retrieve_context signal, so input
480 * methods must be prepared to function without context.
482 * Return value: %TRUE if surrounding text was provided; in this case
483 * you must free the result stored in *text.
486 gtk_im_context_get_surrounding (GtkIMContext *context,
490 GtkIMContextClass *klass;
491 gchar *local_text = NULL;
493 gboolean result = FALSE;
495 g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
497 klass = GTK_IM_CONTEXT_GET_CLASS (context);
498 if (klass->get_surrounding)
499 result = klass->get_surrounding (context,
500 text ? text : &local_text,
501 cursor_index ? cursor_index : &local_index);
510 * gtk_im_context_delete_surrounding:
511 * @context: a #GtkIMContext
512 * @offset: offset from cursor position in chars;
513 * a negative value means start before the cursor.
514 * @n_chars: number of characters to delete.
516 * Asks the widget that the input context is attached to to delete
517 * characters around the cursor position by emitting the
518 * GtkIMContext::delete_context signal. Note that @offset and @n_chars
519 * are in characters not in bytes, which differs from the usage other
520 * places in #GtkIMContext.
522 * In order to use this function, you should first call
523 * gtk_im_context_get_surrounding() to get the current context, and
524 * call this function immediately afterwards to make sure that you
525 * know what you are deleting. You should also account for the fact
526 * that even if the signal was handled, the input context might not
527 * have deleted all the characters that were requested to be deleted.
529 * This function is used by an input method that wants to make
530 * subsitutions in the existing text in response to new input. It is
531 * not useful for applications.
533 * Return value: %TRUE if the signal was handled.
536 gtk_im_context_delete_surrounding (GtkIMContext *context,
542 g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
544 g_signal_emit (context,
545 im_context_signals[DELETE_SURROUNDING], 0,
546 offset, n_chars, &result);