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 enum {
  29   PREEDIT_START,
  30   PREEDIT_END,
  31   PREEDIT_CHANGED,
  32   COMMIT,
  33   RETRIEVE_SURROUNDING,
  34   DELETE_SURROUNDING,
  35   LAST_SIGNAL
  36 };
  37
  38 static guint im_context_signals[LAST_SIGNAL] = { 0 };
  39
  40 static void     gtk_im_context_real_get_preedit_string (GtkIMContext   *context,
  41                                                         gchar         **str,
  42                                                         PangoAttrList **attrs,
  43                                                         gint           *cursor_pos);
  44 static gboolean gtk_im_context_real_filter_keypress    (GtkIMContext   *context,
  45                                                         GdkEventKey    *event);
  46 static gboolean gtk_im_context_real_get_surrounding    (GtkIMContext   *context,
  47                                                         gchar         **text,
  48                                                         gint           *cursor_index);
  49 static void     gtk_im_context_real_set_surrounding    (GtkIMContext   *context,
  50                                                         const char     *text,
  51                                                         gint            len,
  52                                                         gint            cursor_index);
  53
  54 G_DEFINE_ABSTRACT_TYPE (GtkIMContext, gtk_im_context, G_TYPE_OBJECT)
  55
  56 static void
  57 gtk_im_context_class_init (GtkIMContextClass *klass)
  58 {
  59   klass->get_preedit_string = gtk_im_context_real_get_preedit_string;
  60   klass->filter_keypress = gtk_im_context_real_filter_keypress;
  61   klass->get_surrounding = gtk_im_context_real_get_surrounding;
  62   klass->set_surrounding = gtk_im_context_real_set_surrounding;
  63
  64   im_context_signals[PREEDIT_START] =
  65     g_signal_new (I_("preedit_start"),
  66                   G_TYPE_FROM_CLASS (klass),
  67                   G_SIGNAL_RUN_LAST,
  68                   G_STRUCT_OFFSET (GtkIMContextClass, preedit_start),
  69                   NULL, NULL,
  70                   _gtk_marshal_VOID__VOID,
  71                   G_TYPE_NONE, 0);
  72
  73   im_context_signals[PREEDIT_END] =
  74     g_signal_new (I_("preedit_end"),
  75                   G_TYPE_FROM_CLASS (klass),
  76                   G_SIGNAL_RUN_LAST,
  77                   G_STRUCT_OFFSET (GtkIMContextClass, preedit_end),
  78                   NULL, NULL,
  79                   _gtk_marshal_VOID__VOID,
  80                   G_TYPE_NONE, 0);
  81
  82   im_context_signals[PREEDIT_CHANGED] =
  83     g_signal_new (I_("preedit_changed"),
  84                   G_TYPE_FROM_CLASS (klass),
  85                   G_SIGNAL_RUN_LAST,
  86                   G_STRUCT_OFFSET (GtkIMContextClass, preedit_changed),
  87                   NULL, NULL,
  88                   _gtk_marshal_VOID__VOID,
  89                   G_TYPE_NONE, 0);
  90
  91   im_context_signals[COMMIT] =
  92     g_signal_new (I_("commit"),
  93                   G_TYPE_FROM_CLASS (klass),
  94                   G_SIGNAL_RUN_LAST,
  95                   G_STRUCT_OFFSET (GtkIMContextClass, commit),
  96                   NULL, NULL,
  97                   _gtk_marshal_VOID__STRING,
  98                   G_TYPE_NONE, 1,
  99                   G_TYPE_STRING);
 100
 101   im_context_signals[RETRIEVE_SURROUNDING] =
 102     g_signal_new (I_("retrieve_surrounding"),
 103                   G_TYPE_FROM_CLASS (klass),
 104                   G_SIGNAL_RUN_LAST,
 105                   G_STRUCT_OFFSET (GtkIMContextClass, retrieve_surrounding),
 106                   _gtk_boolean_handled_accumulator, NULL,
 107                   _gtk_marshal_BOOLEAN__VOID,
 108                   G_TYPE_BOOLEAN, 0);
 109   im_context_signals[DELETE_SURROUNDING] =
 110     g_signal_new (I_("delete_surrounding"),
 111                   G_TYPE_FROM_CLASS (klass),
 112                   G_SIGNAL_RUN_LAST,
 113                   G_STRUCT_OFFSET (GtkIMContextClass, delete_surrounding),
 114                   _gtk_boolean_handled_accumulator, NULL,
 115                   _gtk_marshal_BOOLEAN__INT_INT,
 116                   G_TYPE_BOOLEAN, 2,
 117                   G_TYPE_INT,
 118                   G_TYPE_INT);
 119 }
 120
 121 static void
 122 gtk_im_context_init (GtkIMContext *im_context)
 123 {
 124 }
 125
 126 static void
 127 gtk_im_context_real_get_preedit_string (GtkIMContext       *context,
 128                                         gchar             **str,
 129                                         PangoAttrList     **attrs,
 130                                         gint               *cursor_pos)
 131 {
 132   if (str)
 133     *str = g_strdup ("");
 134   if (attrs)
 135     *attrs = pango_attr_list_new ();
 136   if (cursor_pos)
 137     *cursor_pos = 0;
 138 }
 139
 140 static gboolean
 141 gtk_im_context_real_filter_keypress (GtkIMContext       *context,
 142                                      GdkEventKey        *event)
 143 {
 144   return FALSE;
 145 }
 146
 147 typedef struct
 148 {
 149   gchar *text;
 150   gint cursor_index;
 151 } SurroundingInfo;
 152
 153 static void
 154 gtk_im_context_real_set_surrounding (GtkIMContext  *context,
 155                                      const gchar   *text,
 156                                      gint           len,
 157                                      gint           cursor_index)
 158 {
 159   SurroundingInfo *info = g_object_get_data (G_OBJECT (context), "gtk-im-surrounding-info");
 160
 161   if (info)
 162     {
 163       g_free (info->text);
 164       info->text = g_strndup (text, len);
 165       info->cursor_index = cursor_index;
 166     }
 167 }
 168
 169 static gboolean
 170 gtk_im_context_real_get_surrounding (GtkIMContext *context,
 171                                      gchar       **text,
 172                                      gint         *cursor_index)
 173 {
 174   gboolean result;
 175   gboolean info_is_local = FALSE;
 176   SurroundingInfo local_info = { NULL, 0 };
 177   SurroundingInfo *info;
 178
 179   info = g_object_get_data (G_OBJECT (context), "gtk-im-surrounding-info");
 180   if (!info)
 181     {
 182       info = &local_info;
 183       g_object_set_data (G_OBJECT (context), I_("gtk-im-surrounding-info"), info);
 184       info_is_local = TRUE;
 185     }
 186
 187   g_signal_emit (context,
 188                  im_context_signals[RETRIEVE_SURROUNDING], 0,
 189                  &result);
 190
 191   if (result)
 192     {
 193       *text = g_strdup (info->text ? info->text : "");
 194       *cursor_index = info->cursor_index;
 195     }
 196   else
 197     {
 198       *text = NULL;
 199       *cursor_index = 0;
 200     }
 201
 202   if (info_is_local)
 203     {
 204       g_free (info->text);
 205       g_object_set_data (G_OBJECT (context), I_("gtk-im-surrounding-info"), NULL);
 206     }
 207
 208   return result;
 209 }
 210
 211 /**
 212  * gtk_im_context_set_client_window:
 213  * @context: a #GtkIMContext
 214  * @window:  the client window. This may be %NULL to indicate
 215  *           that the previous client window no longer exists.
 216  *
 217  * Set the client window for the input context; this is the
 218  * #GdkWindow in which the input appears. This window is
 219  * used in order to correctly position status windows, and may
 220  * also be used for purposes internal to the input method.
 221  **/
 222 void
 223 gtk_im_context_set_client_window (GtkIMContext *context,
 224                                   GdkWindow    *window)
 225 {
 226   GtkIMContextClass *klass;
 227
 228   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 229
 230   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 231   if (klass->set_client_window)
 232     klass->set_client_window (context, window);
 233 }
 234
 235 /**
 236  * gtk_im_context_get_preedit_string:
 237  * @context:    a #GtkIMContext
 238  * @str:        location to store the retrieved string. The
 239  *              string retrieved must be freed with g_free ().
 240  * @attrs:      location to store the retrieved attribute list.
 241  *              When you are done with this list, you must
 242  *              unreference it with pango_attr_list_unref().
 243  * @cursor_pos: location to store position of cursor (in characters)
 244  *              within the preedit string.
 245  *
 246  * Retrieve the current preedit string for the input context,
 247  * and a list of attributes to apply to the string.
 248  * This string should be displayed inserted at the insertion
 249  * point.
 250  **/
 251 void
 252 gtk_im_context_get_preedit_string (GtkIMContext   *context,
 253                                    gchar         **str,
 254                                    PangoAttrList **attrs,
 255                                    gint           *cursor_pos)
 256 {
 257   GtkIMContextClass *klass;
 258
 259   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 260
 261   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 262   klass->get_preedit_string (context, str, attrs, cursor_pos);
 263   g_return_if_fail (str == NULL || g_utf8_validate (*str, -1, NULL));
 264 }
 265
 266 /**
 267  * gtk_im_context_filter_keypress:
 268  * @context: a #GtkIMContext
 269  * @event: the key event
 270  *
 271  * Allow an input method to internally handle key press and release
 272  * events. If this function returns %TRUE, then no further processing
 273  * should be done for this key event.
 274  *
 275  * Return value: %TRUE if the input method handled the key event.
 276  *
 277  **/
 278 gboolean
 279 gtk_im_context_filter_keypress (GtkIMContext *context,
 280                                 GdkEventKey  *key)
 281 {
 282   GtkIMContextClass *klass;
 283
 284   g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
 285   g_return_val_if_fail (key != NULL, FALSE);
 286
 287   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 288   return klass->filter_keypress (context, key);
 289 }
 290
 291 /**
 292  * gtk_im_context_focus_in:
 293  * @context: a #GtkIMContext
 294  *
 295  * Notify the input method that the widget to which this
 296  * input context corresponds has gained focus. The input method
 297  * may, for example, change the displayed feedback to reflect
 298  * this change.
 299  **/
 300 void
 301 gtk_im_context_focus_in (GtkIMContext   *context)
 302 {
 303   GtkIMContextClass *klass;
 304
 305   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 306
 307   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 308   if (klass->focus_in)
 309     klass->focus_in (context);
 310 }
 311
 312 /**
 313  * gtk_im_context_focus_out:
 314  * @context: a #GtkIMContext
 315  *
 316  * Notify the input method that the widget to which this
 317  * input context corresponds has lost focus. The input method
 318  * may, for example, change the displayed feedback or reset the contexts
 319  * state to reflect this change.
 320  **/
 321 void
 322 gtk_im_context_focus_out (GtkIMContext   *context)
 323 {
 324   GtkIMContextClass *klass;
 325
 326   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 327
 328   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 329   if (klass->focus_out)
 330     klass->focus_out (context);
 331 }
 332
 333 /**
 334  * gtk_im_context_reset:
 335  * @context: a #GtkIMContext
 336  *
 337  * Notify the input method that a change such as a change in cursor
 338  * position has been made. This will typically cause the input
 339  * method to clear the preedit state.
 340  **/
 341 void
 342 gtk_im_context_reset (GtkIMContext   *context)
 343 {
 344   GtkIMContextClass *klass;
 345
 346   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 347
 348   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 349   if (klass->reset)
 350     klass->reset (context);
 351 }
 352
 353
 354 /**
 355  * gtk_im_context_set_cursor_location:
 356  * @context: a #GtkIMContext
 357  * @area: new location
 358  *
 359  * Notify the input method that a change in cursor
 360  * position has been made. The location is relative to the client
 361  * window.
 362  **/
 363 void
 364 gtk_im_context_set_cursor_location (GtkIMContext *context,
 365                                     GdkRectangle *area)
 366 {
 367   GtkIMContextClass *klass;
 368
 369   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 370
 371   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 372   if (klass->set_cursor_location)
 373     klass->set_cursor_location (context, area);
 374 }
 375
 376 /**
 377  * gtk_im_context_set_use_preedit:
 378  * @context: a #GtkIMContext
 379  * @use_preedit: whether the IM context should use the preedit string.
 380  *
 381  * Sets whether the IM context should use the preedit string
 382  * to display feedback. If @use_preedit is FALSE (default
 383  * is TRUE), then the IM context may use some other method to display
 384  * feedback, such as displaying it in a child of the root window.
 385  **/
 386 void
 387 gtk_im_context_set_use_preedit (GtkIMContext *context,
 388                                 gboolean      use_preedit)
 389 {
 390   GtkIMContextClass *klass;
 391
 392   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 393
 394   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 395   if (klass->set_use_preedit)
 396     klass->set_use_preedit (context, use_preedit);
 397 }
 398
 399 /**
 400  * gtk_im_context_set_surrounding:
 401  * @context: a #GtkIMContext
 402  * @text: text surrounding the insertion point, as UTF-8.
 403  *        the preedit string should not be included within
 404  *        @text.
 405  * @len: the length of @text, or -1 if @text is nul-terminated
 406  * @cursor_index: the byte index of the insertion cursor within @text.
 407  *
 408  * Sets surrounding context around the insertion point and preedit
 409  * string. This function is expected to be called in response to the
 410  * GtkIMContext::retrieve_surrounding signal, and will likely have no
 411  * effect if called at other times.
 412  **/
 413 void
 414 gtk_im_context_set_surrounding (GtkIMContext  *context,
 415                                 const gchar   *text,
 416                                 gint           len,
 417                                 gint           cursor_index)
 418 {
 419   GtkIMContextClass *klass;
 420
 421   g_return_if_fail (GTK_IS_IM_CONTEXT (context));
 422   g_return_if_fail (text != NULL || len == 0);
 423
 424   if (text == NULL && len == 0)
 425     text = "";
 426   if (len < 0)
 427     len = strlen (text);
 428
 429   g_return_if_fail (cursor_index >= 0 && cursor_index <= len);
 430
 431   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 432   if (klass->set_surrounding)
 433     klass->set_surrounding (context, text, len, cursor_index);
 434 }
 435
 436 /**
 437  * gtk_im_context_get_surrounding:
 438  * @context: a #GtkIMContext
 439  * @text: location to store a UTF-8 encoded string of text
 440  *        holding context around the insertion point.
 441  *        If the function returns %TRUE, then you must free
 442  *        the result stored in this location with g_free().
 443  * @cursor_index: location to store byte index of the insertion cursor
 444  *        within @text.
 445  *
 446  * Retrieves context around the insertion point. Input methods
 447  * typically want context in order to constrain input text based on
 448  * existing text; this is important for languages such as Thai where
 449  * only some sequences of characters are allowed.
 450  *
 451  * This function is implemented by emitting the
 452  * GtkIMContext::retrieve_surrounding signal on the input method; in
 453  * response to this signal, a widget should provide as much context as
 454  * is available, up to an entire paragraph, by calling
 455  * gtk_im_context_set_surrounding(). Note that there is no obligation
 456  * for a widget to respond to the ::retrieve_surrounding signal, so input
 457  * methods must be prepared to function without context.
 458  *
 459  * Return value: %TRUE if surrounding text was provided; in this case
 460  *    you must free the result stored in *text.
 461  **/
 462 gboolean
 463 gtk_im_context_get_surrounding (GtkIMContext *context,
 464                                 gchar       **text,
 465                                 gint         *cursor_index)
 466 {
 467   GtkIMContextClass *klass;
 468   gchar *local_text = NULL;
 469   gint local_index;
 470   gboolean result = FALSE;
 471
 472   g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
 473
 474   klass = GTK_IM_CONTEXT_GET_CLASS (context);
 475   if (klass->get_surrounding)
 476     result = klass->get_surrounding (context,
 477                                      text ? text : &local_text,
 478                                      cursor_index ? cursor_index : &local_index);
 479
 480   if (result)
 481     g_free (local_text);
 482
 483   return result;
 484 }
 485
 486 /**
 487  * gtk_im_context_delete_surrounding:
 488  * @context: a #GtkIMContext
 489  * @offset: offset from cursor position in chars;
 490  *    a negative value means start before the cursor.
 491  * @n_chars: number of characters to delete.
 492  *
 493  * Asks the widget that the input context is attached to to delete
 494  * characters around the cursor position by emitting the
 495  * GtkIMContext::delete_surrounding signal. Note that @offset and @n_chars
 496  * are in characters not in bytes which differs from the usage other
 497  * places in #GtkIMContext.
 498  *
 499  * In order to use this function, you should first call
 500  * gtk_im_context_get_surrounding() to get the current context, and
 501  * call this function immediately afterwards to make sure that you
 502  * know what you are deleting. You should also account for the fact
 503  * that even if the signal was handled, the input context might not
 504  * have deleted all the characters that were requested to be deleted.
 505  *
 506  * This function is used by an input method that wants to make
 507  * subsitutions in the existing text in response to new input. It is
 508  * not useful for applications.
 509  *
 510  * Return value: %TRUE if the signal was handled.
 511  **/
 512 gboolean
 513 gtk_im_context_delete_surrounding (GtkIMContext *context,
 514                                    gint          offset,
 515                                    gint          n_chars)
 516 {
 517   gboolean result;
 518
 519   g_return_val_if_fail (GTK_IS_IM_CONTEXT (context), FALSE);
 520
 521   g_signal_emit (context,
 522                  im_context_signals[DELETE_SURROUNDING], 0,
 523                  offset, n_chars, &result);
 524
 525   return result;
 526 }
 527
 528 #define __GTK_IM_CONTEXT_C__
 529 #include "gtkaliasdef.c"