Pileus Git - ~andy/gtk/blob - gtk/gtkimcontext.c

   1 /* GTK - The GIMP Toolkit
   2  * Copyright (C) 2000 Red Hat, Inc.
   3  *
   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.
   8  *
   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.
  13  *
  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/>.
  16  */
  17
  18 #include "config.h"
  19 #include <string.h>
  20 #include "gtkimcontext.h"
  21 #include "gtkprivate.h"
  22 #include "gtktypebuiltins.h"
  23 #include "gtkmarshalers.h"
  24 #include "gtkintl.h"
  25
  26 /**
  27  * SECTION:gtkimcontext
  28  * @title: GtkIMContext
  29  * @short_description: Base class for input method contexts
  30  * @include: gtk/gtk.h,gtk/gtkimmodule.h
  31  *
  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.
  35  *
  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.
  41  *
  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
  46  * method.
  47  *
  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.
  57  *
  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:
  62  *
  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.
  70  *
  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.
  75  *
  76  * <informalexample><programlisting>
  77  * void im_module_list(const #GtkIMContextInfo ***contexts, int *n_contexts)
  78  * {
  79  *   *contexts = info_list;
  80  *   *n_contexts = G_N_ELEMENTS (info_list);
  81  * }
  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.
  87  *
  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().
  94  *
  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.
  99  */
 100
 101 enum {
 102   PREEDIT_START,
 103   PREEDIT_END,
 104   PREEDIT_CHANGED,
 105   COMMIT,
 106   RETRIEVE_SURROUNDING,
 107   DELETE_SURROUNDING,
 108   LAST_SIGNAL
 109 };
 110
 111 enum {
 112   PROP_INPUT_PURPOSE = 1,
 113   PROP_INPUT_HINTS,
 114   LAST_PROPERTY
 115 };
 116
 117 static guint im_context_signals[LAST_SIGNAL] = { 0, };
 118 static GParamSpec *properties[LAST_PROPERTY] = { NULL, };
 119
 120 typedef struct _GtkIMContextPrivate GtkIMContextPrivate;
 121 struct _GtkIMContextPrivate {
 122   GtkInputPurpose purpose;
 123   GtkInputHints hints;
 124 };
 125
 126 static void     gtk_im_context_real_get_preedit_string (GtkIMContext   *context,
 127                                                         gchar         **str,
 128                                                         PangoAttrList **attrs,
 129                                                         gint           *cursor_pos);
 130 static gboolean gtk_im_context_real_filter_keypress    (GtkIMContext   *context,
 131                                                         GdkEventKey    *event);
 132 static gboolean gtk_im_context_real_get_surrounding    (GtkIMContext   *context,
 133                                                         gchar         **text,
 134                                                         gint           *cursor_index);
 135 static void     gtk_im_context_real_set_surrounding    (GtkIMContext   *context,
 136                                                         const char     *text,
 137                                                         gint            len,
 138                                                         gint            cursor_index);
 139
 140 static void     gtk_im_context_get_property            (GObject        *obj,
 141                                                         guint           property_id,
 142                                                         GValue         *value,
 143                                                         GParamSpec     *pspec);
 144 static void     gtk_im_context_set_property            (GObject        *obj,
 145                                                         guint           property_id,
 146                                                         const GValue   *value,
 147                                                         GParamSpec     *pspec);
 148
 149
 150 G_DEFINE_ABSTRACT_TYPE (GtkIMContext, gtk_im_context, G_TYPE_OBJECT)
 151
 152 /**
 153  * GtkIMContextClass:
 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
 157  *   signal.
 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
 181  *   character.
 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.
 208  */
 209 static void
 210 gtk_im_context_class_init (GtkIMContextClass *klass)
 211 {
 212   GObjectClass *object_class = G_OBJECT_CLASS (klass);
 213
 214   object_class->get_property = gtk_im_context_get_property;
 215   object_class->set_property = gtk_im_context_set_property;
 216
 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;
 221
 222   /**
 223    * GtkIMContext::preedit-start:
 224    * @context: the object on which the signal is emitted
 225    *
 226    * The ::preedit-start signal is emitted when a new preediting sequence
 227    * starts.
 228    */
 229   im_context_signals[PREEDIT_START] =
 230     g_signal_new (I_("preedit-start"),
 231                   G_TYPE_FROM_CLASS (klass),
 232                   G_SIGNAL_RUN_LAST,
 233                   G_STRUCT_OFFSET (GtkIMContextClass, preedit_start),
 234                   NULL, NULL,
 235                   _gtk_marshal_VOID__VOID,
 236                   G_TYPE_NONE, 0);
 237   /**
 238    * GtkIMContext::preedit-end:
 239    * @context: the object on which the signal is emitted
 240    *
 241    * The ::preedit-end signal is emitted when a preediting sequence
 242    * has been completed or canceled.
 243    */
 244   im_context_signals[PREEDIT_END] =
 245     g_signal_new (I_("preedit-end"),
 246                   G_TYPE_FROM_CLASS (klass),
 247                   G_SIGNAL_RUN_LAST,
 248                   G_STRUCT_OFFSET (GtkIMContextClass, preedit_end),
 249                   NULL, NULL,
 250                   _gtk_marshal_VOID__VOID,
 251                   G_TYPE_NONE, 0);
 252   /**
 253    * GtkIMContext::preedit-changed:
 254    * @context: the object on which the signal is emitted
 255    *
 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.
 260    */
 261   im_context_signals[PREEDIT_CHANGED] =
 262     g_signal_new (I_("preedit-changed"),
 263                   G_TYPE_FROM_CLASS (klass),
 264                   G_SIGNAL_RUN_LAST,
 265                   G_STRUCT_OFFSET (GtkIMContextClass, preedit_changed),
 266                   NULL, NULL,
 267                   _gtk_marshal_VOID__VOID,
 268                   G_TYPE_NONE, 0);
 269   /**
 270    * GtkIMContext::commit:
 271    * @context: the object on which the signal is emitted
 272    * @str: the completed character(s) entered by the user
 273    *
 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.
 277    */
 278   im_context_signals[COMMIT] =
 279     g_signal_new (I_("commit"),
 280                   G_TYPE_FROM_CLASS (klass),
 281                   G_SIGNAL_RUN_LAST,
 282                   G_STRUCT_OFFSET (GtkIMContextClass, commit),
 283                   NULL, NULL,
 284                   _gtk_marshal_VOID__STRING,
 285                   G_TYPE_NONE, 1,
 286                   G_TYPE_STRING);
 287   /**
 288    * GtkIMContext::retrieve-surrounding:
 289    * @context: the object on which the signal is emitted
 290    *
 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.
 295    *
 296    * Return value: %TRUE if the signal was handled.
 297    */
 298   im_context_signals[RETRIEVE_SURROUNDING] =
 299     g_signal_new (I_("retrieve-surrounding"),
 300                   G_TYPE_FROM_CLASS (klass),
 301                   G_SIGNAL_RUN_LAST,
 302                   G_STRUCT_OFFSET (GtkIMContextClass, retrieve_surrounding),
 303                   _gtk_boolean_handled_accumulator, NULL,
 304                   _gtk_marshal_BOOLEAN__VOID,
 305                   G_TYPE_BOOLEAN, 0);
 306   /**
 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
 311    *           the cursor.
 312    * @n_chars: the number of characters to be deleted
 313    *
 314    * The ::delete-surrounding signal is emitted when the input method
 315    * needs to delete all or part of the context surrounding the cursor.
 316    *
 317    * Return value: %TRUE if the signal was handled.
 318    */
 319   im_context_signals[DELETE_SURROUNDING] =
 320     g_signal_new (I_("delete-surrounding"),
 321                   G_TYPE_FROM_CLASS (klass),
 322                   G_SIGNAL_RUN_LAST,
 323                   G_STRUCT_OFFSET (GtkIMContextClass, delete_surrounding),
 324                   _gtk_boolean_handled_accumulator, NULL,
 325                   _gtk_marshal_BOOLEAN__INT_INT,
 326                   G_TYPE_BOOLEAN, 2,
 327                   G_TYPE_INT,
 328                   G_TYPE_INT);
 329
 330   properties[PROP_INPUT_PURPOSE] =
 331     g_param_spec_enum ("input-purpose",
 332                          P_("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);
 337
 338   properties[PROP_INPUT_HINTS] =
 339     g_param_spec_flags ("input-hints",
 340                          P_("hints"),
 341                          P_("Hints for the text field behaviour"),
 342                          GTK_TYPE_INPUT_HINTS,
 343                          GTK_INPUT_HINT_NONE,
 344                          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
 345
 346   g_type_class_add_private (klass, sizeof (GtkIMContextPrivate));
 347   g_object_class_install_properties (object_class, LAST_PROPERTY, properties);
 348 }
 349
 350 static void
 351 gtk_im_context_init (GtkIMContext *im_context)
 352 {
 353 }
 354
 355 static void
 356 gtk_im_context_real_get_preedit_string (GtkIMContext       *context,
 357                                         gchar             **str,
 358                                         PangoAttrList     **attrs,
 359                                         gint               *cursor_pos)
 360 {
 361   if (str)
 362     *str = g_strdup ("");
 363   if (attrs)
 364     *attrs = pango_attr_list_new ();
 365   if (cursor_pos)
 366     *cursor_pos = 0;
 367 }
 368
 369 static gboolean
 370 gtk_im_context_real_filter_keypress (GtkIMContext       *context,
 371                                      GdkEventKey        *event)
 372 {
 373   return FALSE;
 374 }
 375
 376 typedef struct
 377 {
 378   gchar *text;
 379   gint cursor_index;
 380 } SurroundingInfo;
 381
 382 static void
 383 gtk_im_context_real_set_surrounding (GtkIMContext  *context,
 384                                      const gchar   *text,
 385                                      gint           len,
 386                                      gint           cursor_index)
 387 {
 388   SurroundingInfo *info = g_object_get_data (G_OBJECT (context),
 389                                              "gtk-im-surrounding-info");
 390
 391   if (info)
 392     {
 393       g_free (info->text);
 394       info->text = g_strndup (text, len);
 395       info->cursor_index = cursor_index;
 396     }
 397 }
 398
 399 static gboolean
 400 gtk_im_context_real_get_surrounding (GtkIMContext *context,
 401                                      gchar       **text,
 402                                      gint         *cursor_index)
 403 {
 404   gboolean result;
 405   gboolean info_is_local = FALSE;
 406   SurroundingInfo local_info = { NULL, 0 };
 407   SurroundingInfo *info;
 408
 409   info = g_object_get_data (G_OBJECT (context), "gtk-im-surrounding-info");
 410   if (!info)
 411     {
 412       info = &local_info;
 413       g_object_set_data (G_OBJECT (context), I_("gtk-im-surrounding-info"), info);
 414       info_is_local = TRUE;
 415     }
 416
 417   g_signal_emit (context,
 418                  im_context_signals[RETRIEVE_SURROUNDING], 0,
 419                  &result);
 420
 421   if (result)
 422     {
 423       *text = g_strdup (info->text ? info->text : "");
 424       *cursor_index = info->cursor_index;
 425     }
 426   else
 427     {
 428       *text = NULL;
 429       *cursor_index = 0;
 430     }
 431
 432   if (info_is_local)
 433     {
 434       g_free (info->text);
 435       g_object_set_data (G_OBJECT (context), I_("gtk-im-surrounding-info"), NULL);
 436     }
 437
 438   return result;
 439 }
 440
 441 /**
 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.
 446  *
 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.
 451  **/
 452 void
 453 gtk_im_context_set_client_window (GtkIMContext *context,
 454                                   GdkWindow    *window)
 455 {
 456   GtkIMContextClass *klass;
 457
 458   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 459
 460   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 461   if (klass->set_client_window)
 462     klass->set_client_window (context, window);
 463 }
 464
 465 /**
 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.
 475  *
 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
 479  * point.
 480  **/
 481 void
 482 gtk_im_context_get_preedit_string (GtkIMContext   *context,
 483                                    gchar         **str,
 484                                    PangoAttrList **attrs,
 485                                    gint           *cursor_pos)
 486 {
 487   GtkIMContextClass *klass;
 488
 489   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 490
 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));
 494 }
 495
 496 /**
 497  * gtk_im_context_filter_keypress:
 498  * @context: a #GtkIMContext
 499  * @event: the key event
 500  *
 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.
 504  *
 505  * Return value: %TRUE if the input method handled the key event.
 506  *
 507  **/
 508 gboolean
 509 gtk_im_context_filter_keypress (GtkIMContext *context,
 510                                 GdkEventKey  *key)
 511 {
 512   GtkIMContextClass *klass;
 513
 514   g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
 515   g_return_val_if_fail (key != NULL, FALSE);
 516
 517   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 518   return klass->filter_keypress (context, key);
 519 }
 520
 521 /**
 522  * gtk_im_context_focus_in:
 523  * @context: a #GtkIMContext
 524  *
 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
 528  * this change.
 529  **/
 530 void
 531 gtk_im_context_focus_in (GtkIMContext   *context)
 532 {
 533   GtkIMContextClass *klass;
 534
 535   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 536
 537   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 538   if (klass->focus_in)
 539     klass->focus_in (context);
 540 }
 541
 542 /**
 543  * gtk_im_context_focus_out:
 544  * @context: a #GtkIMContext
 545  *
 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.
 550  **/
 551 void
 552 gtk_im_context_focus_out (GtkIMContext   *context)
 553 {
 554   GtkIMContextClass *klass;
 555
 556   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 557
 558   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 559   if (klass->focus_out)
 560     klass->focus_out (context);
 561 }
 562
 563 /**
 564  * gtk_im_context_reset:
 565  * @context: a #GtkIMContext
 566  *
 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.
 570  **/
 571 void
 572 gtk_im_context_reset (GtkIMContext   *context)
 573 {
 574   GtkIMContextClass *klass;
 575
 576   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 577
 578   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 579   if (klass->reset)
 580     klass->reset (context);
 581 }
 582
 583
 584 /**
 585  * gtk_im_context_set_cursor_location:
 586  * @context: a #GtkIMContext
 587  * @area: new location
 588  *
 589  * Notify the input method that a change in cursor
 590  * position has been made. The location is relative to the client
 591  * window.
 592  **/
 593 void
 594 gtk_im_context_set_cursor_location (GtkIMContext       *context,
 595                                     const GdkRectangle *area)
 596 {
 597   GtkIMContextClass *klass;
 598
 599   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 600
 601   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 602   if (klass->set_cursor_location)
 603     klass->set_cursor_location (context, (GdkRectangle *) area);
 604 }
 605
 606 /**
 607  * gtk_im_context_set_use_preedit:
 608  * @context: a #GtkIMContext
 609  * @use_preedit: whether the IM context should use the preedit string.
 610  *
 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.
 615  **/
 616 void
 617 gtk_im_context_set_use_preedit (GtkIMContext *context,
 618                                 gboolean      use_preedit)
 619 {
 620   GtkIMContextClass *klass;
 621
 622   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 623
 624   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 625   if (klass->set_use_preedit)
 626     klass->set_use_preedit (context, use_preedit);
 627 }
 628
 629 /**
 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
 634  *        @text.
 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.
 637  *
 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.
 642  **/
 643 void
 644 gtk_im_context_set_surrounding (GtkIMContext  *context,
 645                                 const gchar   *text,
 646                                 gint           len,
 647                                 gint           cursor_index)
 648 {
 649   GtkIMContextClass *klass;
 650
 651   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 652   g_return_if_fail (text != NULL || len == 0);
 653
 654   if (text == NULL && len == 0)
 655     text = "";
 656   if (len < 0)
 657     len = strlen (text);
 658
 659   g_return_if_fail (cursor_index >= 0 && cursor_index <= len);
 660
 661   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 662   if (klass->set_surrounding)
 663     klass->set_surrounding (context, text, len, cursor_index);
 664 }
 665
 666 /**
 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.
 675  *
 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.
 680  *
 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.
 688  *
 689  * Return value: %TRUE if surrounding text was provided; in this case
 690  *    you must free the result stored in *text.
 691  **/
 692 gboolean
 693 gtk_im_context_get_surrounding (GtkIMContext *context,
 694                                 gchar       **text,
 695                                 gint         *cursor_index)
 696 {
 697   GtkIMContextClass *klass;
 698   gchar *local_text = NULL;
 699   gint local_index;
 700   gboolean result = FALSE;
 701
 702   g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
 703
 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);
 709
 710   if (result)
 711     g_free (local_text);
 712
 713   return result;
 714 }
 715
 716 /**
 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.
 722  *
 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.
 728  *
 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.
 735  *
 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.
 739  *
 740  * Return value: %TRUE if the signal was handled.
 741  **/
 742 gboolean
 743 gtk_im_context_delete_surrounding (GtkIMContext *context,
 744                                    gint          offset,
 745                                    gint          n_chars)
 746 {
 747   gboolean result;
 748
 749   g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
 750
 751   g_signal_emit (context,
 752                  im_context_signals[DELETE_SURROUNDING], 0,
 753                  offset, n_chars, &result);
 754
 755   return result;
 756 }
 757
 758 static void
 759 gtk_im_context_get_property (GObject    *obj,
 760                              guint       property_id,
 761                              GValue     *value,
 762                              GParamSpec *pspec)
 763 {
 764   GtkIMContextPrivate *priv = G_TYPE_INSTANCE_GET_PRIVATE (obj, GTK_TYPE_IM_CONTEXT, GtkIMContextPrivate);
 765
 766   switch (property_id)
 767     {
 768     case PROP_INPUT_PURPOSE:
 769       g_value_set_enum (value, priv->purpose);
 770       break;
 771     case PROP_INPUT_HINTS:
 772       g_value_set_flags (value, priv->hints);
 773       break;
 774     default:
 775       G_OBJECT_WARN_INVALID_PROPERTY_ID (obj, property_id, pspec);
 776       break;
 777     }
 778 }
 779
 780 static void
 781 gtk_im_context_set_property (GObject      *obj,
 782                              guint         property_id,
 783                              const GValue *value,
 784                              GParamSpec   *pspec)
 785 {
 786   GtkIMContextPrivate *priv = G_TYPE_INSTANCE_GET_PRIVATE (obj, GTK_TYPE_IM_CONTEXT, GtkIMContextPrivate);
 787
 788   switch (property_id)
 789     {
 790     case PROP_INPUT_PURPOSE:
 791       priv->purpose = g_value_get_enum (value);
 792       break;
 793     case PROP_INPUT_HINTS:
 794       priv->hints = g_value_get_flags (value);
 795       break;
 796     default:
 797       G_OBJECT_WARN_INVALID_PROPERTY_ID (obj, property_id, pspec);
 798       break;
 799     }
 800 }