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