Pileus Git - ~andy/gtk/blob - gtk/gtkeditable.c

   1 /* GTK - The GIMP Toolkit
   2  * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
   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, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 /*
  19  * Modified by the GTK+ Team and others 1997-2000.  See the AUTHORS
  20  * file for a list of people on the GTK+ Team.  See the ChangeLog
  21  * files for a list of changes.  These files are distributed with
  22  * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
  23  */
  24
  25 /**
  26  * SECTION:gtkeditable
  27  * @Short_description: Interface for text-editing widgets
  28  * @Title: GtkEditable
  29  *
  30  * The #GtkEditable interface is an interface which should be implemented by
  31  * text editing widgets, such as #GtkEntry and #GtkSpinButton. It contains functions
  32  * for generically manipulating an editable widget, a large number of action
  33  * signals used for key bindings, and several signals that an application can
  34  * connect to to modify the behavior of a widget.
  35  *
  36  * As an example of the latter usage, by connecting
  37  * the following handler to #GtkEditable::insert-text, an application
  38  * can convert all entry into a widget into uppercase.
  39  *
  40  * <example>
  41  * <title>Forcing entry to uppercase.</title>
  42  * <programlisting>
  43  * #include &lt;ctype.h&gt;
  44  *
  45  * void
  46  * insert_text_handler (GtkEditable &ast;editable,
  47  *                      const gchar &ast;text,
  48  *                      gint         length,
  49  *                      gint        &ast;position,
  50  *                      gpointer     data)
  51  * {
  52  *   gchar &ast;result = g_utf8_strup (text, length);
  53  *
  54  *   g_signal_handlers_block_by_func (editable,
  55  *                                (gpointer) insert_text_handler, data);
  56  *   gtk_editable_insert_text (editable, result, length, position);
  57  *   g_signal_handlers_unblock_by_func (editable,
  58  *                                      (gpointer) insert_text_handler, data);
  59  *
  60  *   g_signal_stop_emission_by_name (editable, "insert_text");
  61  *
  62  *   g_free (result);
  63  * }
  64  * </programlisting>
  65  * </example>
  66  */
  67
  68 #include "config.h"
  69 #include <string.h>
  70
  71 #include "gtkeditable.h"
  72 #include "gtkmarshalers.h"
  73 #include "gtkintl.h"
  74
  75
  76 static void gtk_editable_base_init (gpointer g_class);
  77
  78
  79 GType
  80 gtk_editable_get_type (void)
  81 {
  82   static GType editable_type = 0;
  83
  84   if (!editable_type)
  85     {
  86       const GTypeInfo editable_info =
  87       {
  88         sizeof (GtkEditableInterface),  /* class_size */
  89         gtk_editable_base_init,     /* base_init */
  90         NULL,                       /* base_finalize */
  91       };
  92
  93       editable_type = g_type_register_static (G_TYPE_INTERFACE, I_("GtkEditable"),
  94                                               &editable_info, 0);
  95     }
  96
  97   return editable_type;
  98 }
  99
 100 static void
 101 gtk_editable_base_init (gpointer g_class)
 102 {
 103   static gboolean initialized = FALSE;
 104
 105   if (! initialized)
 106     {
 107       /**
 108        * GtkEditable::insert-text:
 109        * @editable: the object which received the signal
 110        * @new_text: the new text to insert
 111        * @new_text_length: the length of the new text, in bytes,
 112        *     or -1 if new_text is nul-terminated
 113        * @position: (inout) (type int): the position, in characters,
 114        *     at which to insert the new text. this is an in-out
 115        *     parameter.  After the signal emission is finished, it
 116        *     should point after the newly inserted text.
 117        *
 118        * This signal is emitted when text is inserted into
 119        * the widget by the user. The default handler for
 120        * this signal will normally be responsible for inserting
 121        * the text, so by connecting to this signal and then
 122        * stopping the signal with g_signal_stop_emission(), it
 123        * is possible to modify the inserted text, or prevent
 124        * it from being inserted entirely.
 125        */
 126       g_signal_new (I_("insert-text"),
 127                     GTK_TYPE_EDITABLE,
 128                     G_SIGNAL_RUN_LAST,
 129                     G_STRUCT_OFFSET (GtkEditableInterface, insert_text),
 130                     NULL, NULL,
 131                     _gtk_marshal_VOID__STRING_INT_POINTER,
 132                     G_TYPE_NONE, 3,
 133                     G_TYPE_STRING,
 134                     G_TYPE_INT,
 135                     G_TYPE_POINTER);
 136
 137       /**
 138        * GtkEditable::delete-text:
 139        * @editable: the object which received the signal
 140        * @start_pos: the starting position
 141        * @end_pos: the end position
 142        *
 143        * This signal is emitted when text is deleted from
 144        * the widget by the user. The default handler for
 145        * this signal will normally be responsible for deleting
 146        * the text, so by connecting to this signal and then
 147        * stopping the signal with g_signal_stop_emission(), it
 148        * is possible to modify the range of deleted text, or
 149        * prevent it from being deleted entirely. The @start_pos
 150        * and @end_pos parameters are interpreted as for
 151        * gtk_editable_delete_text().
 152        */
 153       g_signal_new (I_("delete-text"),
 154                     GTK_TYPE_EDITABLE,
 155                     G_SIGNAL_RUN_LAST,
 156                     G_STRUCT_OFFSET (GtkEditableInterface, delete_text),
 157                     NULL, NULL,
 158                     _gtk_marshal_VOID__INT_INT,
 159                     G_TYPE_NONE, 2,
 160                     G_TYPE_INT,
 161                     G_TYPE_INT);
 162       /**
 163        * GtkEditable::changed:
 164        * @editable: the object which received the signal
 165        *
 166        * The ::changed signal is emitted at the end of a single
 167        * user-visible operation on the contents of the #GtkEditable.
 168        *
 169        * E.g., a paste operation that replaces the contents of the
 170        * selection will cause only one signal emission (even though it
 171        * is implemented by first deleting the selection, then inserting
 172        * the new content, and may cause multiple ::notify::text signals
 173        * to be emitted).
 174        */
 175       g_signal_new (I_("changed"),
 176                     GTK_TYPE_EDITABLE,
 177                     G_SIGNAL_RUN_LAST,
 178                     G_STRUCT_OFFSET (GtkEditableInterface, changed),
 179                     NULL, NULL,
 180                     _gtk_marshal_VOID__VOID,
 181                     G_TYPE_NONE, 0);
 182
 183       initialized = TRUE;
 184     }
 185 }
 186
 187 /**
 188  * gtk_editable_insert_text:
 189  * @editable: a #GtkEditable
 190  * @new_text: the text to append
 191  * @new_text_length: the length of the text in bytes, or -1
 192  * @position: (inout): location of the position text will be inserted at
 193  *
 194  * Inserts @new_text_length bytes of @new_text into the contents of the
 195  * widget, at position @position.
 196  *
 197  * Note that the position is in characters, not in bytes.
 198  * The function updates @position to point after the newly inserted text.
 199  *
 200  * Virtual: do_insert_text
 201  */
 202 void
 203 gtk_editable_insert_text (GtkEditable *editable,
 204                           const gchar *new_text,
 205                           gint         new_text_length,
 206                           gint        *position)
 207 {
 208   g_return_if_fail (GTK_IS_EDITABLE (editable));
 209   g_return_if_fail (position != NULL);
 210
 211   if (new_text_length < 0)
 212     new_text_length = strlen (new_text);
 213
 214   GTK_EDITABLE_GET_IFACE (editable)->do_insert_text (editable, new_text, new_text_length, position);
 215 }
 216
 217 /**
 218  * gtk_editable_delete_text:
 219  * @editable: a #GtkEditable
 220  * @start_pos: start position
 221  * @end_pos: end position
 222  *
 223  * Deletes a sequence of characters. The characters that are deleted are
 224  * those characters at positions from @start_pos up to, but not including
 225  * @end_pos. If @end_pos is negative, then the characters deleted
 226  * are those from @start_pos to the end of the text.
 227  *
 228  * Note that the positions are specified in characters, not bytes.
 229  *
 230  * Virtual: do_delete_text
 231  */
 232 void
 233 gtk_editable_delete_text (GtkEditable *editable,
 234                           gint         start_pos,
 235                           gint         end_pos)
 236 {
 237   g_return_if_fail (GTK_IS_EDITABLE (editable));
 238
 239   GTK_EDITABLE_GET_IFACE (editable)->do_delete_text (editable, start_pos, end_pos);
 240 }
 241
 242 /**
 243  * gtk_editable_get_chars:
 244  * @editable: a #GtkEditable
 245  * @start_pos: start of text
 246  * @end_pos: end of text
 247  *
 248  * Retrieves a sequence of characters. The characters that are retrieved
 249  * are those characters at positions from @start_pos up to, but not
 250  * including @end_pos. If @end_pos is negative, then the characters
 251  * retrieved are those characters from @start_pos to the end of the text.
 252  *
 253  * Note that positions are specified in characters, not bytes.
 254  *
 255  * Return value: a pointer to the contents of the widget as a
 256  *      string. This string is allocated by the #GtkEditable
 257  *      implementation and should be freed by the caller.
 258  */
 259 gchar *
 260 gtk_editable_get_chars (GtkEditable *editable,
 261                         gint         start_pos,
 262                         gint         end_pos)
 263 {
 264   g_return_val_if_fail (GTK_IS_EDITABLE (editable), NULL);
 265
 266   return GTK_EDITABLE_GET_IFACE (editable)->get_chars (editable, start_pos, end_pos);
 267 }
 268
 269 /**
 270  * gtk_editable_set_position:
 271  * @editable: a #GtkEditable
 272  * @position: the position of the cursor
 273  *
 274  * Sets the cursor position in the editable to the given value.
 275  *
 276  * The cursor is displayed before the character with the given (base 0)
 277  * index in the contents of the editable. The value must be less than or
 278  * equal to the number of characters in the editable. A value of -1
 279  * indicates that the position should be set after the last character
 280  * of the editable. Note that @position is in characters, not in bytes.
 281  */
 282 void
 283 gtk_editable_set_position (GtkEditable      *editable,
 284                            gint              position)
 285 {
 286   g_return_if_fail (GTK_IS_EDITABLE (editable));
 287
 288   GTK_EDITABLE_GET_IFACE (editable)->set_position (editable, position);
 289 }
 290
 291 /**
 292  * gtk_editable_get_position:
 293  * @editable: a #GtkEditable
 294  *
 295  * Retrieves the current position of the cursor relative to the start
 296  * of the content of the editable.
 297  *
 298  * Note that this position is in characters, not in bytes.
 299  *
 300  * Return value: the cursor position
 301  */
 302 gint
 303 gtk_editable_get_position (GtkEditable *editable)
 304 {
 305   g_return_val_if_fail (GTK_IS_EDITABLE (editable), 0);
 306
 307   return GTK_EDITABLE_GET_IFACE (editable)->get_position (editable);
 308 }
 309
 310 /**
 311  * gtk_editable_get_selection_bounds:
 312  * @editable: a #GtkEditable
 313  * @start_pos: (out) (allow-none): location to store the starting position, or %NULL
 314  * @end_pos: (out) (allow-none): location to store the end position, or %NULL
 315  *
 316  * Retrieves the selection bound of the editable. start_pos will be filled
 317  * with the start of the selection and @end_pos with end. If no text was
 318  * selected both will be identical and %FALSE will be returned.
 319  *
 320  * Note that positions are specified in characters, not bytes.
 321  *
 322  * Return value: %TRUE if an area is selected, %FALSE otherwise
 323  */
 324 gboolean
 325 gtk_editable_get_selection_bounds (GtkEditable *editable,
 326                                    gint        *start_pos,
 327                                    gint        *end_pos)
 328 {
 329   gint tmp_start, tmp_end;
 330   gboolean result;
 331
 332   g_return_val_if_fail (GTK_IS_EDITABLE (editable), FALSE);
 333
 334   result = GTK_EDITABLE_GET_IFACE (editable)->get_selection_bounds (editable, &tmp_start, &tmp_end);
 335
 336   if (start_pos)
 337     *start_pos = MIN (tmp_start, tmp_end);
 338   if (end_pos)
 339     *end_pos = MAX (tmp_start, tmp_end);
 340
 341   return result;
 342 }
 343
 344 /**
 345  * gtk_editable_delete_selection:
 346  * @editable: a #GtkEditable
 347  *
 348  * Deletes the currently selected text of the editable.
 349  * This call doesn't do anything if there is no selected text.
 350  */
 351 void
 352 gtk_editable_delete_selection (GtkEditable *editable)
 353 {
 354   gint start, end;
 355
 356   g_return_if_fail (GTK_IS_EDITABLE (editable));
 357
 358   if (gtk_editable_get_selection_bounds (editable, &start, &end))
 359     gtk_editable_delete_text (editable, start, end);
 360 }
 361
 362 /**
 363  * gtk_editable_select_region:
 364  * @editable: a #GtkEditable
 365  * @start_pos: start of region
 366  * @end_pos: end of region
 367  *
 368  * Selects a region of text. The characters that are selected are
 369  * those characters at positions from @start_pos up to, but not
 370  * including @end_pos. If @end_pos is negative, then the
 371  * characters selected are those characters from @start_pos to
 372  * the end of the text.
 373  *
 374  * Note that positions are specified in characters, not bytes.
 375  *
 376  * Virtual: set_selection_bounds
 377  */
 378 void
 379 gtk_editable_select_region (GtkEditable *editable,
 380                             gint         start_pos,
 381                             gint         end_pos)
 382 {
 383   g_return_if_fail (GTK_IS_EDITABLE (editable));
 384
 385   GTK_EDITABLE_GET_IFACE (editable)->set_selection_bounds (editable, start_pos, end_pos);
 386 }
 387
 388 /**
 389  * gtk_editable_cut_clipboard:
 390  * @editable: a #GtkEditable
 391  *
 392  * Removes the contents of the currently selected content in the editable and
 393  * puts it on the clipboard.
 394  */
 395 void
 396 gtk_editable_cut_clipboard (GtkEditable *editable)
 397 {
 398   g_return_if_fail (GTK_IS_EDITABLE (editable));
 399
 400   g_signal_emit_by_name (editable, "cut-clipboard");
 401 }
 402
 403 /**
 404  * gtk_editable_copy_clipboard:
 405  * @editable: a #GtkEditable
 406  *
 407  * Copies the contents of the currently selected content in the editable and
 408  * puts it on the clipboard.
 409  */
 410 void
 411 gtk_editable_copy_clipboard (GtkEditable *editable)
 412 {
 413   g_return_if_fail (GTK_IS_EDITABLE (editable));
 414
 415   g_signal_emit_by_name (editable, "copy-clipboard");
 416 }
 417
 418 /**
 419  * gtk_editable_paste_clipboard:
 420  * @editable: a #GtkEditable
 421  *
 422  * Pastes the content of the clipboard to the current position of the
 423  * cursor in the editable.
 424  */
 425 void
 426 gtk_editable_paste_clipboard (GtkEditable *editable)
 427 {
 428   g_return_if_fail (GTK_IS_EDITABLE (editable));
 429
 430   g_signal_emit_by_name (editable, "paste-clipboard");
 431 }
 432
 433 /**
 434  * gtk_editable_set_editable:
 435  * @editable: a #GtkEditable
 436  * @is_editable: %TRUE if the user is allowed to edit the text
 437  *   in the widget
 438  *
 439  * Determines if the user can edit the text in the editable
 440  * widget or not.
 441  */
 442 void
 443 gtk_editable_set_editable (GtkEditable    *editable,
 444                            gboolean        is_editable)
 445 {
 446   g_return_if_fail (GTK_IS_EDITABLE (editable));
 447
 448   g_object_set (editable,
 449                 "editable", is_editable != FALSE,
 450                 NULL);
 451 }
 452
 453 /**
 454  * gtk_editable_get_editable:
 455  * @editable: a #GtkEditable
 456  *
 457  * Retrieves whether @editable is editable. See
 458  * gtk_editable_set_editable().
 459  *
 460  * Return value: %TRUE if @editable is editable.
 461  */
 462 gboolean
 463 gtk_editable_get_editable (GtkEditable *editable)
 464 {
 465   gboolean value;
 466
 467   g_return_val_if_fail (GTK_IS_EDITABLE (editable), FALSE);
 468
 469   g_object_get (editable, "editable", &value, NULL);
 470
 471   return value;
 472 }