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