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, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 #include "config.h"
  21 #include <string.h>
  22 #include "gtkimcontext.h"
  23 #include "gtkmainprivate.h"
  24 #include "gtkmarshalers.h"
  25 #include "gtkintl.h"
  26
  27 /**
  28  * SECTION:gtkimcontext
  29  * @title: GtkIMContext
  30  * @short_description: Base class for input method contexts
  31  * @include: gtk/gtk.h,gtk/gtkimmodule.h
  32  *
  33  * #GtkIMContext defines the interface for GTK+ input methods. An input method
  34  * is used by GTK+ text input widgets like #GtkEntry to map from key events to
  35  * Unicode character strings.
  36  *
  37  * The user may change the current input method via a context menu, unless the
  38  * #GtkSettings:gtk-show-input-method-menu GtkSettings property is set to FALSE.
  39  * The default input method can be set programmatically via the
  40  * #GtkSettings:gtk-im-module GtkSettings property. Alternatively, you may set
  41  * the GTK_IM_MODULE environment variable as documented in #gtk-running.
  42  *
  43  * The #GtkEntry #GtkEntry:im-module and #GtkTextView #GtkTextView:im-module
  44  * properties may also be used to set input methods for specific widget
  45  * instances. For instance, a certain entry widget might be expected to contain
  46  * certain characters which would be easier to input with a certain input
  47  * method.
  48  *
  49  * An input method may consume multiple key events in sequence and finally
  50  * output the composed result. This is called preediting, and an input method
  51  * may provide feedback about this process by displaying the intermediate
  52  * composition states as preedit text. For instance, the default GTK+ input
  53  * method implements the input of arbitrary Unicode code points by holding down
  54  * the Control and Shift keys and then typing "U" followed by the hexadecimal
  55  * digits of the code point.  When releasing the Control and Shift keys,
  56  * preediting ends and the character is inserted as text. Ctrl+Shift+u20AC for
  57  * example results in the € sign.
  58  *
  59  * Additional input methods can be made available for use by GTK+ widgets as
  60  * loadable modules. An input method module is a small shared library which
  61  * implements a subclass of #GtkIMContext or #GtkIMContextSimple and exports
  62  * these four functions:
  63  *
  64  * <informalexample><programlisting>
  65  * void im_module_init(#GTypeModule *module);
  66  * </programlisting></informalexample>
  67  * This function should register the #GType of the #GtkIMContext subclass which
  68  * implements the input method by means of g_type_module_register_type(). Note
  69  * that g_type_register_static() cannot be used as the type needs to be
  70  * registered dynamically.
  71  *
  72  * <informalexample><programlisting>
  73  * void im_module_exit(void);
  74  * </programlisting></informalexample>
  75  * Here goes any cleanup code your input method might require on module unload.
  76  *
  77  * <informalexample><programlisting>
  78  * void im_module_list(const #GtkIMContextInfo ***contexts, int *n_contexts)
  79  * {
  80  *   *contexts = info_list;
  81  *   *n_contexts = G_N_ELEMENTS (info_list);
  82  * }
  83  * </programlisting></informalexample>
  84  * This function returns the list of input methods provided by the module. The
  85  * example implementation above shows a common solution and simply returns a
  86  * pointer to statically defined array of #GtkIMContextInfo items for each
  87  * provided input method.
  88  *
  89  * <informalexample><programlisting>
  90  * #GtkIMContext * im_module_create(const #gchar *context_id);
  91  * </programlisting></informalexample>
  92  * This function should return a pointer to a newly created instance of the
  93  * #GtkIMContext subclass identified by @context_id. The context ID is the same
  94  * as specified in the #GtkIMContextInfo array returned by im_module_list().
  95  *
  96  * After a new loadable input method module has been installed on the system,
  97  * the configuration file <filename>gtk.immodules</filename> needs to be
  98  * regenerated by <link linkend="gtk-query-immodules-3.0">gtk-query-immodules-3.0</link>,
  99  * in order for the new input method to become available to GTK+ applications.
 100  */
 101
 102 enum {
 103   PREEDIT_START,
 104   PREEDIT_END,
 105   PREEDIT_CHANGED,
 106   COMMIT,
 107   RETRIEVE_SURROUNDING,
 108   DELETE_SURROUNDING,
 109   LAST_SIGNAL
 110 };
 111
 112 static guint im_context_signals[LAST_SIGNAL] = { 0 };
 113
 114 static void     gtk_im_context_real_get_preedit_string (GtkIMContext   *context,
 115                                                         gchar         **str,
 116                                                         PangoAttrList **attrs,
 117                                                         gint           *cursor_pos);
 118 static gboolean gtk_im_context_real_filter_keypress    (GtkIMContext   *context,
 119                                                         GdkEventKey    *event);
 120 static gboolean gtk_im_context_real_get_surrounding    (GtkIMContext   *context,
 121                                                         gchar         **text,
 122                                                         gint           *cursor_index);
 123 static void     gtk_im_context_real_set_surrounding    (GtkIMContext   *context,
 124                                                         const char     *text,
 125                                                         gint            len,
 126                                                         gint            cursor_index);
 127
 128 G_DEFINE_ABSTRACT_TYPE (GtkIMContext, gtk_im_context, G_TYPE_OBJECT)
 129
 130 /**
 131  * GtkIMContextClass:
 132  * @preedit_start: Default handler of the #GtkIMContext::preedit-start signal.
 133  * @preedit_end: Default handler of the #GtkIMContext::preedit-end signal.
 134  * @preedit_changed: Default handler of the #GtkIMContext::preedit-changed
 135  *   signal.
 136  * @commit: Default handler of the #GtkIMContext::commit signal.
 137  * @retrieve_surrounding: Default handler of the
 138  *   #GtkIMContext::retrieve-surrounding signal.
 139  * @delete_surrounding: Default handler of the
 140  *   #GtkIMContext::delete-surrounding signal.
 141  * @set_client_window: Called via gtk_im_context_set_client_window() when the
 142  *   input window where the entered text will appear changes. Override this to
 143  *   keep track of the current input window, for instance for the purpose of
 144  *   positioning a status display of your input method.
 145  * @get_preedit_string: Called via gtk_im_context_get_preedit_string() to
 146  *   retrieve the text currently being preedited for display at the cursor
 147  *   position. Any input method which composes complex characters or any
 148  *   other compositions from multiple sequential key presses should override
 149  *   this method to provide feedback.
 150  * @filter_keypress: Called via gtk_im_context_filter_keypress() on every
 151  *   key press or release event. Every non-trivial input method needs to
 152  *   override this in order to implement the mapping from key events to text.
 153  *   A return value of %TRUE indicates to the caller that the event was
 154  *   consumed by the input method. In that case, the #GtkIMContext::commit
 155  *   signal should be emitted upon completion of a key sequence to pass the
 156  *   resulting text back to the input widget. Alternatively, %FALSE may be
 157  *   returned to indicate that the event wasn't handled by the input method.
 158  *   If a builtin mapping exists for the key, it is used to produce a
 159  *   character.
 160  * @focus_in: Called via gtk_im_context_focus_in() when the input widget
 161  *   has gained focus. May be overridden to keep track of the current focus.
 162  * @focus_out: Called via gtk_im_context_focus_out() when the input widget
 163  *   has lost focus. May be overridden to keep track of the current focus.
 164  * @reset: Called via gtk_im_context_reset() to signal a change such as a
 165  *   change in cursor position. An input method that implements preediting
 166  *   should override this method to clear the preedit state on reset.
 167  * @set_cursor_location: Called via gtk_im_context_set_cursor_location()
 168  *   to inform the input method of the current cursor location relative to
 169  *   the client window. May be overridden to implement the display of popup
 170  *   windows at the cursor position.
 171  * @set_use_preedit: Called via gtk_im_context_set_use_preedit() to control
 172  *   the use of the preedit string. Override this to display feedback by some
 173  *   other means if turned off.
 174  * @set_surrounding: Called via gtk_im_context_set_surrounding() in response
 175  *   to signal #GtkIMContext::retrieve-surrounding to update the input
 176  *   method's idea of the context around the cursor. It is not necessary to
 177  *   override this method even with input methods which implement
 178  *   context-dependent behavior. The base implementation is sufficient for
 179  *   gtk_im_context_get_surrounding() to work.
 180  * @get_surrounding: Called via gtk_im_context_get_surrounding() to update
 181  *   the context around the cursor location. It is not necessary to override
 182  *   this method even with input methods which implement context-dependent
 183  *   behavior. The base implementation emits
 184  *   #GtkIMContext::retrieve-surrounding and records the context received
 185  *   by the subsequent invocation of @get_surrounding.
 186  */
 187 static void
 188 gtk_im_context_class_init (GtkIMContextClass *klass)
 189 {
 190   klass->get_preedit_string = gtk_im_context_real_get_preedit_string;
 191   klass->filter_keypress = gtk_im_context_real_filter_keypress;
 192   klass->get_surrounding = gtk_im_context_real_get_surrounding;
 193   klass->set_surrounding = gtk_im_context_real_set_surrounding;
 194
 195   /**
 196    * GtkIMContext::preedit-start:
 197    * @context: the object on which the signal is emitted
 198    *
 199    * The ::preedit-start signal is emitted when a new preediting sequence
 200    * starts.
 201    */
 202   im_context_signals[PREEDIT_START] =
 203     g_signal_new (I_("preedit-start"),
 204                   G_TYPE_FROM_CLASS (klass),
 205                   G_SIGNAL_RUN_LAST,
 206                   G_STRUCT_OFFSET (GtkIMContextClass, preedit_start),
 207                   NULL, NULL,
 208                   _gtk_marshal_VOID__VOID,
 209                   G_TYPE_NONE, 0);
 210   /**
 211    * GtkIMContext::preedit-end:
 212    * @context: the object on which the signal is emitted
 213    *
 214    * The ::preedit-end signal is emitted when a preediting sequence
 215    * has been completed or canceled.
 216    */
 217   im_context_signals[PREEDIT_END] =
 218     g_signal_new (I_("preedit-end"),
 219                   G_TYPE_FROM_CLASS (klass),
 220                   G_SIGNAL_RUN_LAST,
 221                   G_STRUCT_OFFSET (GtkIMContextClass, preedit_end),
 222                   NULL, NULL,
 223                   _gtk_marshal_VOID__VOID,
 224                   G_TYPE_NONE, 0);
 225   /**
 226    * GtkIMContext::preedit-changed:
 227    * @context: the object on which the signal is emitted
 228    *
 229    * The ::preedit-changed signal is emitted whenever the preedit sequence
 230    * currently being entered has changed.  It is also emitted at the end of
 231    * a preedit sequence, in which case
 232    * gtk_im_context_get_preedit_string() returns the empty string.
 233    */
 234   im_context_signals[PREEDIT_CHANGED] =
 235     g_signal_new (I_("preedit-changed"),
 236                   G_TYPE_FROM_CLASS (klass),
 237                   G_SIGNAL_RUN_LAST,
 238                   G_STRUCT_OFFSET (GtkIMContextClass, preedit_changed),
 239                   NULL, NULL,
 240                   _gtk_marshal_VOID__VOID,
 241                   G_TYPE_NONE, 0);
 242   /**
 243    * GtkIMContext::commit:
 244    * @context: the object on which the signal is emitted
 245    * @str: the completed character(s) entered by the user
 246    *
 247    * The ::commit signal is emitted when a complete input sequence
 248    * has been entered by the user. This can be a single character
 249    * immediately after a key press or the final result of preediting.
 250    */
 251   im_context_signals[COMMIT] =
 252     g_signal_new (I_("commit"),
 253                   G_TYPE_FROM_CLASS (klass),
 254                   G_SIGNAL_RUN_LAST,
 255                   G_STRUCT_OFFSET (GtkIMContextClass, commit),
 256                   NULL, NULL,
 257                   _gtk_marshal_VOID__STRING,
 258                   G_TYPE_NONE, 1,
 259                   G_TYPE_STRING);
 260   /**
 261    * GtkIMContext::retrieve-surrounding:
 262    * @context: the object on which the signal is emitted
 263    *
 264    * The ::retrieve-surrounding signal is emitted when the input method
 265    * requires the context surrounding the cursor.  The callback should set
 266    * the input method surrounding context by calling the
 267    * gtk_im_context_set_surrounding() method.
 268    *
 269    * Return value: %TRUE if the signal was handled.
 270    */
 271   im_context_signals[RETRIEVE_SURROUNDING] =
 272     g_signal_new (I_("retrieve-surrounding"),
 273                   G_TYPE_FROM_CLASS (klass),
 274                   G_SIGNAL_RUN_LAST,
 275                   G_STRUCT_OFFSET (GtkIMContextClass, retrieve_surrounding),
 276                   _gtk_boolean_handled_accumulator, NULL,
 277                   _gtk_marshal_BOOLEAN__VOID,
 278                   G_TYPE_BOOLEAN, 0);
 279   /**
 280    * GtkIMContext::delete-surrounding:
 281    * @context: the object on which the signal is emitted
 282    * @offset:  the character offset from the cursor position of the text
 283    *           to be deleted. A negative value indicates a position before
 284    *           the cursor.
 285    * @n_chars: the number of characters to be deleted
 286    *
 287    * The ::delete-surrounding signal is emitted when the input method
 288    * needs to delete all or part of the context surrounding the cursor.
 289    *
 290    * Return value: %TRUE if the signal was handled.
 291    */
 292   im_context_signals[DELETE_SURROUNDING] =
 293     g_signal_new (I_("delete-surrounding"),
 294                   G_TYPE_FROM_CLASS (klass),
 295                   G_SIGNAL_RUN_LAST,
 296                   G_STRUCT_OFFSET (GtkIMContextClass, delete_surrounding),
 297                   _gtk_boolean_handled_accumulator, NULL,
 298                   _gtk_marshal_BOOLEAN__INT_INT,
 299                   G_TYPE_BOOLEAN, 2,
 300                   G_TYPE_INT,
 301                   G_TYPE_INT);
 302 }
 303
 304 static void
 305 gtk_im_context_init (GtkIMContext *im_context)
 306 {
 307 }
 308
 309 static void
 310 gtk_im_context_real_get_preedit_string (GtkIMContext       *context,
 311                                         gchar             **str,
 312                                         PangoAttrList     **attrs,
 313                                         gint               *cursor_pos)
 314 {
 315   if (str)
 316     *str = g_strdup ("");
 317   if (attrs)
 318     *attrs = pango_attr_list_new ();
 319   if (cursor_pos)
 320     *cursor_pos = 0;
 321 }
 322
 323 static gboolean
 324 gtk_im_context_real_filter_keypress (GtkIMContext       *context,
 325                                      GdkEventKey        *event)
 326 {
 327   return FALSE;
 328 }
 329
 330 typedef struct
 331 {
 332   gchar *text;
 333   gint cursor_index;
 334 } SurroundingInfo;
 335
 336 static void
 337 gtk_im_context_real_set_surrounding (GtkIMContext  *context,
 338                                      const gchar   *text,
 339                                      gint           len,
 340                                      gint           cursor_index)
 341 {
 342   SurroundingInfo *info = g_object_get_data (G_OBJECT (context),
 343                                              "gtk-im-surrounding-info");
 344
 345   if (info)
 346     {
 347       g_free (info->text);
 348       info->text = g_strndup (text, len);
 349       info->cursor_index = cursor_index;
 350     }
 351 }
 352
 353 static gboolean
 354 gtk_im_context_real_get_surrounding (GtkIMContext *context,
 355                                      gchar       **text,
 356                                      gint         *cursor_index)
 357 {
 358   gboolean result;
 359   gboolean info_is_local = FALSE;
 360   SurroundingInfo local_info = { NULL, 0 };
 361   SurroundingInfo *info;
 362
 363   info = g_object_get_data (G_OBJECT (context), "gtk-im-surrounding-info");
 364   if (!info)
 365     {
 366       info = &local_info;
 367       g_object_set_data (G_OBJECT (context), I_("gtk-im-surrounding-info"), info);
 368       info_is_local = TRUE;
 369     }
 370
 371   g_signal_emit (context,
 372                  im_context_signals[RETRIEVE_SURROUNDING], 0,
 373                  &result);
 374
 375   if (result)
 376     {
 377       *text = g_strdup (info->text ? info->text : "");
 378       *cursor_index = info->cursor_index;
 379     }
 380   else
 381     {
 382       *text = NULL;
 383       *cursor_index = 0;
 384     }
 385
 386   if (info_is_local)
 387     {
 388       g_free (info->text);
 389       g_object_set_data (G_OBJECT (context), I_("gtk-im-surrounding-info"), NULL);
 390     }
 391
 392   return result;
 393 }
 394
 395 /**
 396  * gtk_im_context_set_client_window:
 397  * @context: a #GtkIMContext
 398  * @window: (allow-none):  the client window. This may be %NULL to indicate
 399  *           that the previous client window no longer exists.
 400  *
 401  * Set the client window for the input context; this is the
 402  * #GdkWindow in which the input appears. This window is
 403  * used in order to correctly position status windows, and may
 404  * also be used for purposes internal to the input method.
 405  **/
 406 void
 407 gtk_im_context_set_client_window (GtkIMContext *context,
 408                                   GdkWindow    *window)
 409 {
 410   GtkIMContextClass *klass;
 411
 412   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 413
 414   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 415   if (klass->set_client_window)
 416     klass->set_client_window (context, window);
 417 }
 418
 419 /**
 420  * gtk_im_context_get_preedit_string:
 421  * @context:    a #GtkIMContext
 422  * @str:        (out) (transfer full): location to store the retrieved
 423  *              string. The string retrieved must be freed with g_free().
 424  * @attrs:      (out) (transfer full): location to store the retrieved
 425  *              attribute list.  When you are done with this list, you
 426  *              must unreference it with pango_attr_list_unref().
 427  * @cursor_pos: (out): location to store position of cursor (in characters)
 428  *              within the preedit string.
 429  *
 430  * Retrieve the current preedit string for the input context,
 431  * and a list of attributes to apply to the string.
 432  * This string should be displayed inserted at the insertion
 433  * point.
 434  **/
 435 void
 436 gtk_im_context_get_preedit_string (GtkIMContext   *context,
 437                                    gchar         **str,
 438                                    PangoAttrList **attrs,
 439                                    gint           *cursor_pos)
 440 {
 441   GtkIMContextClass *klass;
 442
 443   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 444
 445   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 446   klass->get_preedit_string (context, str, attrs, cursor_pos);
 447   g_return_if_fail (str == NULL || g_utf8_validate (*str, -1, NULL));
 448 }
 449
 450 /**
 451  * gtk_im_context_filter_keypress:
 452  * @context: a #GtkIMContext
 453  * @event: the key event
 454  *
 455  * Allow an input method to internally handle key press and release
 456  * events. If this function returns %TRUE, then no further processing
 457  * should be done for this key event.
 458  *
 459  * Return value: %TRUE if the input method handled the key event.
 460  *
 461  **/
 462 gboolean
 463 gtk_im_context_filter_keypress (GtkIMContext *context,
 464                                 GdkEventKey  *key)
 465 {
 466   GtkIMContextClass *klass;
 467
 468   g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
 469   g_return_val_if_fail (key != NULL, FALSE);
 470
 471   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 472   return klass->filter_keypress (context, key);
 473 }
 474
 475 /**
 476  * gtk_im_context_focus_in:
 477  * @context: a #GtkIMContext
 478  *
 479  * Notify the input method that the widget to which this
 480  * input context corresponds has gained focus. The input method
 481  * may, for example, change the displayed feedback to reflect
 482  * this change.
 483  **/
 484 void
 485 gtk_im_context_focus_in (GtkIMContext   *context)
 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   if (klass->focus_in)
 493     klass->focus_in (context);
 494 }
 495
 496 /**
 497  * gtk_im_context_focus_out:
 498  * @context: a #GtkIMContext
 499  *
 500  * Notify the input method that the widget to which this
 501  * input context corresponds has lost focus. The input method
 502  * may, for example, change the displayed feedback or reset the contexts
 503  * state to reflect this change.
 504  **/
 505 void
 506 gtk_im_context_focus_out (GtkIMContext   *context)
 507 {
 508   GtkIMContextClass *klass;
 509
 510   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 511
 512   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 513   if (klass->focus_out)
 514     klass->focus_out (context);
 515 }
 516
 517 /**
 518  * gtk_im_context_reset:
 519  * @context: a #GtkIMContext
 520  *
 521  * Notify the input method that a change such as a change in cursor
 522  * position has been made. This will typically cause the input
 523  * method to clear the preedit state.
 524  **/
 525 void
 526 gtk_im_context_reset (GtkIMContext   *context)
 527 {
 528   GtkIMContextClass *klass;
 529
 530   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 531
 532   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 533   if (klass->reset)
 534     klass->reset (context);
 535 }
 536
 537
 538 /**
 539  * gtk_im_context_set_cursor_location:
 540  * @context: a #GtkIMContext
 541  * @area: new location
 542  *
 543  * Notify the input method that a change in cursor
 544  * position has been made. The location is relative to the client
 545  * window.
 546  **/
 547 void
 548 gtk_im_context_set_cursor_location (GtkIMContext       *context,
 549                                     const GdkRectangle *area)
 550 {
 551   GtkIMContextClass *klass;
 552
 553   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 554
 555   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 556   if (klass->set_cursor_location)
 557     klass->set_cursor_location (context, (GdkRectangle *) area);
 558 }
 559
 560 /**
 561  * gtk_im_context_set_use_preedit:
 562  * @context: a #GtkIMContext
 563  * @use_preedit: whether the IM context should use the preedit string.
 564  *
 565  * Sets whether the IM context should use the preedit string
 566  * to display feedback. If @use_preedit is FALSE (default
 567  * is TRUE), then the IM context may use some other method to display
 568  * feedback, such as displaying it in a child of the root window.
 569  **/
 570 void
 571 gtk_im_context_set_use_preedit (GtkIMContext *context,
 572                                 gboolean      use_preedit)
 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->set_use_preedit)
 580     klass->set_use_preedit (context, use_preedit);
 581 }
 582
 583 /**
 584  * gtk_im_context_set_surrounding:
 585  * @context: a #GtkIMContext
 586  * @text: text surrounding the insertion point, as UTF-8.
 587  *        the preedit string should not be included within
 588  *        @text.
 589  * @len: the length of @text, or -1 if @text is nul-terminated
 590  * @cursor_index: the byte index of the insertion cursor within @text.
 591  *
 592  * Sets surrounding context around the insertion point and preedit
 593  * string. This function is expected to be called in response to the
 594  * GtkIMContext::retrieve_surrounding signal, and will likely have no
 595  * effect if called at other times.
 596  **/
 597 void
 598 gtk_im_context_set_surrounding (GtkIMContext  *context,
 599                                 const gchar   *text,
 600                                 gint           len,
 601                                 gint           cursor_index)
 602 {
 603   GtkIMContextClass *klass;
 604
 605   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 606   g_return_if_fail (text != NULL || len == 0);
 607
 608   if (text == NULL && len == 0)
 609     text = "";
 610   if (len < 0)
 611     len = strlen (text);
 612
 613   g_return_if_fail (cursor_index >= 0 && cursor_index <= len);
 614
 615   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 616   if (klass->set_surrounding)
 617     klass->set_surrounding (context, text, len, cursor_index);
 618 }
 619
 620 /**
 621  * gtk_im_context_get_surrounding:
 622  * @context: a #GtkIMContext
 623  * @text: (out) (transfer full): location to store a UTF-8 encoded
 624  *        string of text holding context around the insertion point.
 625  *        If the function returns %TRUE, then you must free the result
 626  *        stored in this location with g_free().
 627  * @cursor_index: (out) location to store byte index of the insertion
 628  *        cursor within @text.
 629  *
 630  * Retrieves context around the insertion point. Input methods
 631  * typically want context in order to constrain input text based on
 632  * existing text; this is important for languages such as Thai where
 633  * only some sequences of characters are allowed.
 634  *
 635  * This function is implemented by emitting the
 636  * GtkIMContext::retrieve_surrounding signal on the input method; in
 637  * response to this signal, a widget should provide as much context as
 638  * is available, up to an entire paragraph, by calling
 639  * gtk_im_context_set_surrounding(). Note that there is no obligation
 640  * for a widget to respond to the ::retrieve_surrounding signal, so input
 641  * methods must be prepared to function without context.
 642  *
 643  * Return value: %TRUE if surrounding text was provided; in this case
 644  *    you must free the result stored in *text.
 645  **/
 646 gboolean
 647 gtk_im_context_get_surrounding (GtkIMContext *context,
 648                                 gchar       **text,
 649                                 gint         *cursor_index)
 650 {
 651   GtkIMContextClass *klass;
 652   gchar *local_text = NULL;
 653   gint local_index;
 654   gboolean result = FALSE;
 655
 656   g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
 657
 658   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 659   if (klass->get_surrounding)
 660     result = klass->get_surrounding (context,
 661                                      text ? text : &local_text,
 662                                      cursor_index ? cursor_index : &local_index);
 663
 664   if (result)
 665     g_free (local_text);
 666
 667   return result;
 668 }
 669
 670 /**
 671  * gtk_im_context_delete_surrounding:
 672  * @context: a #GtkIMContext
 673  * @offset: offset from cursor position in chars;
 674  *    a negative value means start before the cursor.
 675  * @n_chars: number of characters to delete.
 676  *
 677  * Asks the widget that the input context is attached to to delete
 678  * characters around the cursor position by emitting the
 679  * GtkIMContext::delete_surrounding signal. Note that @offset and @n_chars
 680  * are in characters not in bytes which differs from the usage other
 681  * places in #GtkIMContext.
 682  *
 683  * In order to use this function, you should first call
 684  * gtk_im_context_get_surrounding() to get the current context, and
 685  * call this function immediately afterwards to make sure that you
 686  * know what you are deleting. You should also account for the fact
 687  * that even if the signal was handled, the input context might not
 688  * have deleted all the characters that were requested to be deleted.
 689  *
 690  * This function is used by an input method that wants to make
 691  * subsitutions in the existing text in response to new input. It is
 692  * not useful for applications.
 693  *
 694  * Return value: %TRUE if the signal was handled.
 695  **/
 696 gboolean
 697 gtk_im_context_delete_surrounding (GtkIMContext *context,
 698                                    gint          offset,
 699                                    gint          n_chars)
 700 {
 701   gboolean result;
 702
 703   g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
 704
 705   g_signal_emit (context,
 706                  im_context_signals[DELETE_SURROUNDING], 0,
 707                  offset, n_chars, &result);
 708
 709   return result;
 710 }