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