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