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