1 /* GTK - The GTK+ 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.
22 #include "gtkimcontext.h"
23 #include "gtkmain.h" /* For _gtk_boolean_handled_accumulator */
24 #include "gtkmarshalers.h"
38 static guint im_context_signals[LAST_SIGNAL] = { 0 };
40 static void gtk_im_context_real_get_preedit_string (GtkIMContext *context,
42 PangoAttrList **attrs,
44 static gboolean gtk_im_context_real_filter_keypress (GtkIMContext *context,
46 static gboolean gtk_im_context_real_get_surrounding (GtkIMContext *context,
49 static void gtk_im_context_real_set_surrounding (GtkIMContext *context,
54 G_DEFINE_ABSTRACT_TYPE (GtkIMContext, gtk_im_context, G_TYPE_OBJECT)
57 gtk_im_context_class_init (GtkIMContextClass *klass)
59 klass->get_preedit_string = gtk_im_context_real_get_preedit_string;
60 klass->filter_keypress = gtk_im_context_real_filter_keypress;
61 klass->get_surrounding = gtk_im_context_real_get_surrounding;
62 klass->set_surrounding = gtk_im_context_real_set_surrounding;
64 im_context_signals[PREEDIT_START] =
65 g_signal_new (I_("preedit_start"),
66 G_TYPE_FROM_CLASS (klass),
68 G_STRUCT_OFFSET (GtkIMContextClass, preedit_start),
70 _gtk_marshal_VOID__VOID,
73 im_context_signals[PREEDIT_END] =
74 g_signal_new (I_("preedit_end"),
75 G_TYPE_FROM_CLASS (klass),
77 G_STRUCT_OFFSET (GtkIMContextClass, preedit_end),
79 _gtk_marshal_VOID__VOID,
82 im_context_signals[PREEDIT_CHANGED] =
83 g_signal_new (I_("preedit_changed"),
84 G_TYPE_FROM_CLASS (klass),
86 G_STRUCT_OFFSET (GtkIMContextClass, preedit_changed),
88 _gtk_marshal_VOID__VOID,
91 im_context_signals[COMMIT] =
92 g_signal_new (I_("commit"),
93 G_TYPE_FROM_CLASS (klass),
95 G_STRUCT_OFFSET (GtkIMContextClass, commit),
97 _gtk_marshal_VOID__STRING,
101 im_context_signals[RETRIEVE_SURROUNDING] =
102 g_signal_new (I_("retrieve_surrounding"),
103 G_TYPE_FROM_CLASS (klass),
105 G_STRUCT_OFFSET (GtkIMContextClass, retrieve_surrounding),
106 _gtk_boolean_handled_accumulator, NULL,
107 _gtk_marshal_BOOLEAN__VOID,
109 im_context_signals[DELETE_SURROUNDING] =
110 g_signal_new (I_("delete_surrounding"),
111 G_TYPE_FROM_CLASS (klass),
113 G_STRUCT_OFFSET (GtkIMContextClass, delete_surrounding),
114 _gtk_boolean_handled_accumulator, NULL,
115 _gtk_marshal_BOOLEAN__INT_INT,
122 gtk_im_context_init (GtkIMContext *im_context)
127 gtk_im_context_real_get_preedit_string (GtkIMContext *context,
129 PangoAttrList **attrs,
133 *str = g_strdup ("");
135 *attrs = pango_attr_list_new ();
141 gtk_im_context_real_filter_keypress (GtkIMContext *context,
154 gtk_im_context_real_set_surrounding (GtkIMContext *context,
159 SurroundingInfo *info = g_object_get_data (G_OBJECT (context), "gtk-im-surrounding-info");
164 info->text = g_strndup (text, len);
165 info->cursor_index = cursor_index;
170 gtk_im_context_real_get_surrounding (GtkIMContext *context,
175 gboolean info_is_local = FALSE;
176 SurroundingInfo local_info = { NULL, 0 };
177 SurroundingInfo *info;
179 info = g_object_get_data (G_OBJECT (context), "gtk-im-surrounding-info");
183 g_object_set_data (G_OBJECT (context), I_("gtk-im-surrounding-info"), info);
184 info_is_local = TRUE;
187 g_signal_emit (context,
188 im_context_signals[RETRIEVE_SURROUNDING], 0,
193 *text = g_strdup (info->text ? info->text : "");
194 *cursor_index = info->cursor_index;
205 g_object_set_data (G_OBJECT (context), I_("gtk-im-surrounding-info"), NULL);
212 * gtk_im_context_set_client_window:
213 * @context: a #GtkIMContext
214 * @window: the client window. This may be %NULL to indicate
215 * that the previous client window no longer exists.
217 * Set the client window for the input context; this is the
218 * #GdkWindow in which the input appears. This window is
219 * used in order to correctly position status windows, and may
220 * also be used for purposes internal to the input method.
223 gtk_im_context_set_client_window (GtkIMContext *context,
226 GtkIMContextClass *klass;
228 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
230 klass = GTK_IM_CONTEXT_GET_CLASS (context);
231 if (klass->set_client_window)
232 klass->set_client_window (context, window);
236 * gtk_im_context_get_preedit_string:
237 * @context: a #GtkIMContext
238 * @str: location to store the retrieved string. The
239 * string retrieved must be freed with g_free ().
240 * @attrs: location to store the retrieved attribute list.
241 * When you are done with this list, you must
242 * unreference it with pango_attr_list_unref().
243 * @cursor_pos: location to store position of cursor (in characters)
244 * within the preedit string.
246 * Retrieve the current preedit string for the input context,
247 * and a list of attributes to apply to the string.
248 * This string should be displayed inserted at the insertion
252 gtk_im_context_get_preedit_string (GtkIMContext *context,
254 PangoAttrList **attrs,
257 GtkIMContextClass *klass;
259 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
261 klass = GTK_IM_CONTEXT_GET_CLASS (context);
262 klass->get_preedit_string (context, str, attrs, cursor_pos);
263 g_return_if_fail (str == NULL || g_utf8_validate (*str, -1, NULL));
267 * gtk_im_context_filter_keypress:
268 * @context: a #GtkIMContext
269 * @event: the key event
271 * Allow an input method to internally handle key press and release
272 * events. If this function returns %TRUE, then no further processing
273 * should be done for this key event.
275 * Return value: %TRUE if the input method handled the key event.
279 gtk_im_context_filter_keypress (GtkIMContext *context,
282 GtkIMContextClass *klass;
284 g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
285 g_return_val_if_fail (key != NULL, FALSE);
287 klass = GTK_IM_CONTEXT_GET_CLASS (context);
288 return klass->filter_keypress (context, key);
292 * gtk_im_context_focus_in:
293 * @context: a #GtkIMContext
295 * Notify the input method that the widget to which this
296 * input context corresponds has gained focus. The input method
297 * may, for example, change the displayed feedback to reflect
301 gtk_im_context_focus_in (GtkIMContext *context)
303 GtkIMContextClass *klass;
305 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
307 klass = GTK_IM_CONTEXT_GET_CLASS (context);
309 klass->focus_in (context);
313 * gtk_im_context_focus_out:
314 * @context: a #GtkIMContext
316 * Notify the input method that the widget to which this
317 * input context corresponds has lost focus. The input method
318 * may, for example, change the displayed feedback or reset the contexts
319 * state to reflect this change.
322 gtk_im_context_focus_out (GtkIMContext *context)
324 GtkIMContextClass *klass;
326 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
328 klass = GTK_IM_CONTEXT_GET_CLASS (context);
329 if (klass->focus_out)
330 klass->focus_out (context);
334 * gtk_im_context_reset:
335 * @context: a #GtkIMContext
337 * Notify the input method that a change such as a change in cursor
338 * position has been made. This will typically cause the input
339 * method to clear the preedit state.
342 gtk_im_context_reset (GtkIMContext *context)
344 GtkIMContextClass *klass;
346 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
348 klass = GTK_IM_CONTEXT_GET_CLASS (context);
350 klass->reset (context);
355 * gtk_im_context_set_cursor_location:
356 * @context: a #GtkIMContext
357 * @area: new location
359 * Notify the input method that a change in cursor
360 * position has been made. The location is relative to the client
364 gtk_im_context_set_cursor_location (GtkIMContext *context,
365 const GdkRectangle *area)
367 GtkIMContextClass *klass;
369 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
371 klass = GTK_IM_CONTEXT_GET_CLASS (context);
372 if (klass->set_cursor_location)
373 klass->set_cursor_location (context, (GdkRectangle *) area);
377 * gtk_im_context_set_use_preedit:
378 * @context: a #GtkIMContext
379 * @use_preedit: whether the IM context should use the preedit string.
381 * Sets whether the IM context should use the preedit string
382 * to display feedback. If @use_preedit is FALSE (default
383 * is TRUE), then the IM context may use some other method to display
384 * feedback, such as displaying it in a child of the root window.
387 gtk_im_context_set_use_preedit (GtkIMContext *context,
388 gboolean use_preedit)
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_use_preedit)
396 klass->set_use_preedit (context, use_preedit);
400 * gtk_im_context_set_surrounding:
401 * @context: a #GtkIMContext
402 * @text: text surrounding the insertion point, as UTF-8.
403 * the preedit string should not be included within
405 * @len: the length of @text, or -1 if @text is nul-terminated
406 * @cursor_index: the byte index of the insertion cursor within @text.
408 * Sets surrounding context around the insertion point and preedit
409 * string. This function is expected to be called in response to the
410 * GtkIMContext::retrieve_surrounding signal, and will likely have no
411 * effect if called at other times.
414 gtk_im_context_set_surrounding (GtkIMContext *context,
419 GtkIMContextClass *klass;
421 g_return_if_fail (GTK_IS_IM_CONTEXT (context));
422 g_return_if_fail (text != NULL || len == 0);
424 if (text == NULL && len == 0)
429 g_return_if_fail (cursor_index >= 0 && cursor_index <= len);
431 klass = GTK_IM_CONTEXT_GET_CLASS (context);
432 if (klass->set_surrounding)
433 klass->set_surrounding (context, text, len, cursor_index);
437 * gtk_im_context_get_surrounding:
438 * @context: a #GtkIMContext
439 * @text: location to store a UTF-8 encoded string of text
440 * holding context around the insertion point.
441 * If the function returns %TRUE, then you must free
442 * the result stored in this location with g_free().
443 * @cursor_index: location to store byte index of the insertion cursor
446 * Retrieves context around the insertion point. Input methods
447 * typically want context in order to constrain input text based on
448 * existing text; this is important for languages such as Thai where
449 * only some sequences of characters are allowed.
451 * This function is implemented by emitting the
452 * GtkIMContext::retrieve_surrounding signal on the input method; in
453 * response to this signal, a widget should provide as much context as
454 * is available, up to an entire paragraph, by calling
455 * gtk_im_context_set_surrounding(). Note that there is no obligation
456 * for a widget to respond to the ::retrieve_surrounding signal, so input
457 * methods must be prepared to function without context.
459 * Return value: %TRUE if surrounding text was provided; in this case
460 * you must free the result stored in *text.
463 gtk_im_context_get_surrounding (GtkIMContext *context,
467 GtkIMContextClass *klass;
468 gchar *local_text = NULL;
470 gboolean result = FALSE;
472 g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
474 klass = GTK_IM_CONTEXT_GET_CLASS (context);
475 if (klass->get_surrounding)
476 result = klass->get_surrounding (context,
477 text ? text : &local_text,
478 cursor_index ? cursor_index : &local_index);
487 * gtk_im_context_delete_surrounding:
488 * @context: a #GtkIMContext
489 * @offset: offset from cursor position in chars;
490 * a negative value means start before the cursor.
491 * @n_chars: number of characters to delete.
493 * Asks the widget that the input context is attached to to delete
494 * characters around the cursor position by emitting the
495 * GtkIMContext::delete_surrounding signal. Note that @offset and @n_chars
496 * are in characters not in bytes which differs from the usage other
497 * places in #GtkIMContext.
499 * In order to use this function, you should first call
500 * gtk_im_context_get_surrounding() to get the current context, and
501 * call this function immediately afterwards to make sure that you
502 * know what you are deleting. You should also account for the fact
503 * that even if the signal was handled, the input context might not
504 * have deleted all the characters that were requested to be deleted.
506 * This function is used by an input method that wants to make
507 * subsitutions in the existing text in response to new input. It is
508 * not useful for applications.
510 * Return value: %TRUE if the signal was handled.
513 gtk_im_context_delete_surrounding (GtkIMContext *context,
519 g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
521 g_signal_emit (context,
522 im_context_signals[DELETE_SURROUNDING], 0,
523 offset, n_chars, &result);
528 #define __GTK_IM_CONTEXT_C__
529 #include "gtkaliasdef.c"