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