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