gtkeditable.c 13.9 KB
Newer Older
Cody Russell's avatar
Cody Russell committed
1
/* GTK - The GIMP Toolkit
2 3 4
 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
 *
 * This library is free software; you can redistribute it and/or
5
 * modify it under the terms of the GNU Lesser General Public
6 7 8 9 10 11
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * 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
Javier Jardón's avatar
Javier Jardón committed
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 21 22 23 24
 * file for a list of people on the GTK+ Team.  See the ChangeLog
 * files for a list of changes.  These files are distributed with
 * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
 */

25 26 27 28 29 30
/**
 * SECTION:gtkeditable
 * @Short_description: Interface for text-editing widgets
 * @Title: GtkEditable
 *
 * The #GtkEditable interface is an interface which should be implemented by
31
 * text editing widgets, such as #GtkEntry and #GtkSpinButton. It contains functions
32 33 34 35 36
 * for generically manipulating an editable widget, a large number of action
 * signals used for key bindings, and several signals that an application can
 * connect to to modify the behavior of a widget.
 *
 * As an example of the latter usage, by connecting
37
 * the following handler to #GtkEditable::insert-text, an application
38 39
 * can convert all entry into a widget into uppercase.
 *
40 41
 * ## Forcing entry to uppercase.
 *
42
 * |[<!-- language="C" -->
43
 * #include <ctype.h>;
44 45
 *
 * void
46 47
 * insert_text_handler (GtkEditable *editable,
 *                      const gchar *text,
48
 *                      gint         length,
49
 *                      gint        *position,
50 51
 *                      gpointer     data)
 * {
52
 *   gchar *result = g_utf8_strup (text, length);
53 54 55 56 57 58 59 60 61 62 63
 *
 *   g_signal_handlers_block_by_func (editable,
 *                                (gpointer) insert_text_handler, data);
 *   gtk_editable_insert_text (editable, result, length, position);
 *   g_signal_handlers_unblock_by_func (editable,
 *                                      (gpointer) insert_text_handler, data);
 *
 *   g_signal_stop_emission_by_name (editable, "insert_text");
 *
 *   g_free (result);
 * }
64
 * ]|
65 66
 */

67
#include "config.h"
68
#include <string.h>
Owen Taylor's avatar
Owen Taylor committed
69

70
#include "gtkeditable.h"
71
#include "gtkmarshalers.h"
72
#include "gtkintl.h"
73

74

Matthias Clasen's avatar
Matthias Clasen committed
75
static void gtk_editable_base_init (gpointer g_class);
76 77


Manish Singh's avatar
Manish Singh committed
78
GType
79
gtk_editable_get_type (void)
80
{
Manish Singh's avatar
Manish Singh committed
81
  static GType editable_type = 0;
82 83 84

  if (!editable_type)
    {
85
      const GTypeInfo editable_info =
86
      {
87
	sizeof (GtkEditableInterface),  /* class_size */
88
	gtk_editable_base_init,	    /* base_init */
Owen Taylor's avatar
Owen Taylor committed
89
	NULL,			    /* base_finalize */
90 91
      };

92
      editable_type = g_type_register_static (G_TYPE_INTERFACE, I_("GtkEditable"),
Manish Singh's avatar
Manish Singh committed
93
					      &editable_info, 0);
94 95 96 97 98
    }

  return editable_type;
}

99 100 101 102 103 104 105
static void
gtk_editable_base_init (gpointer g_class)
{
  static gboolean initialized = FALSE;

  if (! initialized)
    {
Matthias Clasen's avatar
Matthias Clasen committed
106 107 108 109 110 111
      /**
       * GtkEditable::insert-text:
       * @editable: the object which received the signal
       * @new_text: the new text to insert
       * @new_text_length: the length of the new text, in bytes,
       *     or -1 if new_text is nul-terminated
112 113 114 115
       * @position: (inout) (type int): the position, in characters,
       *     at which to insert the new text. this is an in-out
       *     parameter.  After the signal emission is finished, it
       *     should point after the newly inserted text.
Matthias Clasen's avatar
Matthias Clasen committed
116 117 118 119 120 121 122 123 124
       *
       * This signal is emitted when text is inserted into
       * the widget by the user. The default handler for
       * this signal will normally be responsible for inserting
       * the text, so by connecting to this signal and then
       * stopping the signal with g_signal_stop_emission(), it
       * is possible to modify the inserted text, or prevent
       * it from being inserted entirely.
       */
125
      g_signal_new (I_("insert-text"),
126 127
		    GTK_TYPE_EDITABLE,
		    G_SIGNAL_RUN_LAST,
128
		    G_STRUCT_OFFSET (GtkEditableInterface, insert_text),
129
		    NULL, NULL,
130
		    _gtk_marshal_VOID__STRING_INT_POINTER,
131
		    G_TYPE_NONE, 3,
Manish Singh's avatar
Manish Singh committed
132 133 134
		    G_TYPE_STRING,
		    G_TYPE_INT,
		    G_TYPE_POINTER);
Matthias Clasen's avatar
Matthias Clasen committed
135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151

      /**
       * GtkEditable::delete-text:
       * @editable: the object which received the signal
       * @start_pos: the starting position
       * @end_pos: the end position
       * 
       * This signal is emitted when text is deleted from
       * the widget by the user. The default handler for
       * this signal will normally be responsible for deleting
       * the text, so by connecting to this signal and then
       * stopping the signal with g_signal_stop_emission(), it
       * is possible to modify the range of deleted text, or
       * prevent it from being deleted entirely. The @start_pos
       * and @end_pos parameters are interpreted as for
       * gtk_editable_delete_text().
       */
152
      g_signal_new (I_("delete-text"),
153 154
		    GTK_TYPE_EDITABLE,
		    G_SIGNAL_RUN_LAST,
155
		    G_STRUCT_OFFSET (GtkEditableInterface, delete_text),
156
		    NULL, NULL,
157
		    _gtk_marshal_VOID__INT_INT,
Manish Singh's avatar
Manish Singh committed
158 159 160
		    G_TYPE_NONE, 2,
		    G_TYPE_INT,
		    G_TYPE_INT);
Matthias Clasen's avatar
Matthias Clasen committed
161 162 163 164 165 166 167 168 169 170 171 172 173
      /**
       * GtkEditable::changed:
       * @editable: the object which received the signal
       *
       * The ::changed signal is emitted at the end of a single
       * user-visible operation on the contents of the #GtkEditable.
       *
       * E.g., a paste operation that replaces the contents of the
       * selection will cause only one signal emission (even though it
       * is implemented by first deleting the selection, then inserting
       * the new content, and may cause multiple ::notify::text signals
       * to be emitted).
       */ 
174
      g_signal_new (I_("changed"),
175 176
		    GTK_TYPE_EDITABLE,
		    G_SIGNAL_RUN_LAST,
177
		    G_STRUCT_OFFSET (GtkEditableInterface, changed),
178
		    NULL, NULL,
179
		    _gtk_marshal_VOID__VOID,
Manish Singh's avatar
Manish Singh committed
180
		    G_TYPE_NONE, 0);
181 182 183 184 185

      initialized = TRUE;
    }
}

186
/**
Jasper St. Pierre's avatar
Jasper St. Pierre committed
187
 * gtk_editable_insert_text: (virtual do_insert_text)
188 189
 * @editable: a #GtkEditable
 * @new_text: the text to append
190
 * @new_text_length: the length of the text in bytes, or -1
191
 * @position: (inout): location of the position text will be inserted at
Matthias Clasen's avatar
Matthias Clasen committed
192
 *
193 194
 * Inserts @new_text_length bytes of @new_text into the contents of the
 * widget, at position @position.
195
 *
Matthias Clasen's avatar
Matthias Clasen committed
196 197 198
 * Note that the position is in characters, not in bytes. 
 * The function updates @position to point after the newly inserted text.
 */
199 200 201
void
gtk_editable_insert_text (GtkEditable *editable,
			  const gchar *new_text,
202 203
			  gint         new_text_length,
			  gint        *position)
204 205
{
  g_return_if_fail (GTK_IS_EDITABLE (editable));
Owen Taylor's avatar
Owen Taylor committed
206
  g_return_if_fail (position != NULL);
207

208 209 210
  if (new_text_length < 0)
    new_text_length = strlen (new_text);
  
211
  GTK_EDITABLE_GET_IFACE (editable)->do_insert_text (editable, new_text, new_text_length, position);
212 213
}

214
/**
Jasper St. Pierre's avatar
Jasper St. Pierre committed
215
 * gtk_editable_delete_text: (virtual do_delete_text)
216 217 218 219
 * @editable: a #GtkEditable
 * @start_pos: start position
 * @end_pos: end position
 *
Matthias Clasen's avatar
Matthias Clasen committed
220 221
 * Deletes a sequence of characters. The characters that are deleted are 
 * those characters at positions from @start_pos up to, but not including 
222
 * @end_pos. If @end_pos is negative, then the characters deleted
Matthias Clasen's avatar
Matthias Clasen committed
223 224 225 226
 * are those from @start_pos to the end of the text.
 *
 * Note that the positions are specified in characters, not bytes.
 */
227 228
void
gtk_editable_delete_text (GtkEditable *editable,
229 230
			  gint         start_pos,
			  gint         end_pos)
231 232 233
{
  g_return_if_fail (GTK_IS_EDITABLE (editable));

234
  GTK_EDITABLE_GET_IFACE (editable)->do_delete_text (editable, start_pos, end_pos);
235 236
}

237 238 239
/**
 * gtk_editable_get_chars:
 * @editable: a #GtkEditable
Matthias Clasen's avatar
Matthias Clasen committed
240 241
 * @start_pos: start of text
 * @end_pos: end of text
242
 *
Matthias Clasen's avatar
Matthias Clasen committed
243 244
 * Retrieves a sequence of characters. The characters that are retrieved 
 * are those characters at positions from @start_pos up to, but not 
245
 * including @end_pos. If @end_pos is negative, then the characters
Matthias Clasen's avatar
Matthias Clasen committed
246 247
 * retrieved are those characters from @start_pos to the end of the text.
 * 
248 249
 * Note that positions are specified in characters, not bytes.
 *
250
 * Returns: a pointer to the contents of the widget as a
251 252
 *      string. This string is allocated by the #GtkEditable
 *      implementation and should be freed by the caller.
Matthias Clasen's avatar
Matthias Clasen committed
253
 */
254
gchar *    
Owen Taylor's avatar
Owen Taylor committed
255
gtk_editable_get_chars (GtkEditable *editable,
Matthias Clasen's avatar
Matthias Clasen committed
256 257
			gint         start_pos,
			gint         end_pos)
258
{
259
  g_return_val_if_fail (GTK_IS_EDITABLE (editable), NULL);
260

261
  return GTK_EDITABLE_GET_IFACE (editable)->get_chars (editable, start_pos, end_pos);
262 263
}

264 265 266
/**
 * gtk_editable_set_position:
 * @editable: a #GtkEditable
Matthias Clasen's avatar
Matthias Clasen committed
267
 * @position: the position of the cursor 
268 269
 *
 * Sets the cursor position in the editable to the given value.
Matthias Clasen's avatar
Matthias Clasen committed
270 271 272 273 274 275 276
 *
 * The cursor is displayed before the character with the given (base 0) 
 * index in the contents of the editable. The value must be less than or 
 * equal to the number of characters in the editable. A value of -1 
 * indicates that the position should be set after the last character 
 * of the editable. Note that @position is in characters, not in bytes.
 */
Owen Taylor's avatar
Owen Taylor committed
277
void
278 279
gtk_editable_set_position (GtkEditable      *editable,
			   gint              position)
Owen Taylor's avatar
Owen Taylor committed
280 281 282
{
  g_return_if_fail (GTK_IS_EDITABLE (editable));

283
  GTK_EDITABLE_GET_IFACE (editable)->set_position (editable, position);
Owen Taylor's avatar
Owen Taylor committed
284 285
}

286 287 288 289 290
/**
 * gtk_editable_get_position:
 * @editable: a #GtkEditable
 *
 * Retrieves the current position of the cursor relative to the start
Matthias Clasen's avatar
Matthias Clasen committed
291 292 293
 * of the content of the editable. 
 * 
 * Note that this position is in characters, not in bytes.
294
 *
295
 * Returns: the cursor position
Matthias Clasen's avatar
Matthias Clasen committed
296
 */
Owen Taylor's avatar
Owen Taylor committed
297
gint
298
gtk_editable_get_position (GtkEditable *editable)
Owen Taylor's avatar
Owen Taylor committed
299
{
Owen Taylor's avatar
Owen Taylor committed
300
  g_return_val_if_fail (GTK_IS_EDITABLE (editable), 0);
Owen Taylor's avatar
Owen Taylor committed
301

302
  return GTK_EDITABLE_GET_IFACE (editable)->get_position (editable);
303 304
}

305 306 307
/**
 * gtk_editable_get_selection_bounds:
 * @editable: a #GtkEditable
308 309
 * @start_pos: (out) (allow-none): location to store the starting position, or %NULL
 * @end_pos: (out) (allow-none): location to store the end position, or %NULL
310
 *
Matthias Clasen's avatar
Matthias Clasen committed
311
 * Retrieves the selection bound of the editable. start_pos will be filled
312 313
 * with the start of the selection and @end_pos with end. If no text was
 * selected both will be identical and %FALSE will be returned.
314
 *
Matthias Clasen's avatar
Matthias Clasen committed
315
 * Note that positions are specified in characters, not bytes.
316
 *
317
 * Returns: %TRUE if an area is selected, %FALSE otherwise
Matthias Clasen's avatar
Matthias Clasen committed
318
 */
Owen Taylor's avatar
Owen Taylor committed
319 320 321 322
gboolean
gtk_editable_get_selection_bounds (GtkEditable *editable,
				   gint        *start_pos,
				   gint        *end_pos)
323
{
Owen Taylor's avatar
Owen Taylor committed
324 325
  gint tmp_start, tmp_end;
  gboolean result;
326
  
Owen Taylor's avatar
Owen Taylor committed
327
  g_return_val_if_fail (GTK_IS_EDITABLE (editable), FALSE);
328

329
  result = GTK_EDITABLE_GET_IFACE (editable)->get_selection_bounds (editable, &tmp_start, &tmp_end);
330

Owen Taylor's avatar
Owen Taylor committed
331 332 333 334
  if (start_pos)
    *start_pos = MIN (tmp_start, tmp_end);
  if (end_pos)
    *end_pos = MAX (tmp_start, tmp_end);
335

Owen Taylor's avatar
Owen Taylor committed
336
  return result;
337 338
}

339 340 341 342 343
/**
 * gtk_editable_delete_selection:
 * @editable: a #GtkEditable
 *
 * Deletes the currently selected text of the editable.
344
 * This call doesn’t do anything if there is no selected text.
Matthias Clasen's avatar
Matthias Clasen committed
345
 */
346 347 348
void
gtk_editable_delete_selection (GtkEditable *editable)
{
Owen Taylor's avatar
Owen Taylor committed
349
  gint start, end;
350

351 352
  g_return_if_fail (GTK_IS_EDITABLE (editable));

Owen Taylor's avatar
Owen Taylor committed
353 354
  if (gtk_editable_get_selection_bounds (editable, &start, &end))
    gtk_editable_delete_text (editable, start, end);
355 356
}

357
/**
Jasper St. Pierre's avatar
Jasper St. Pierre committed
358
 * gtk_editable_select_region: (virtual set_selection_bounds)
359
 * @editable: a #GtkEditable
Matthias Clasen's avatar
Matthias Clasen committed
360 361
 * @start_pos: start of region
 * @end_pos: end of region
362
 *
Matthias Clasen's avatar
Matthias Clasen committed
363 364
 * Selects a region of text. The characters that are selected are 
 * those characters at positions from @start_pos up to, but not 
365
 * including @end_pos. If @end_pos is negative, then the
Matthias Clasen's avatar
Matthias Clasen committed
366 367 368 369 370
 * characters selected are those characters from @start_pos to 
 * the end of the text.
 * 
 * Note that positions are specified in characters, not bytes.
 */
371 372
void
gtk_editable_select_region (GtkEditable *editable,
Matthias Clasen's avatar
Matthias Clasen committed
373 374
			    gint         start_pos,
			    gint         end_pos)
375
{
376 377
  g_return_if_fail (GTK_IS_EDITABLE (editable));
  
378
  GTK_EDITABLE_GET_IFACE (editable)->set_selection_bounds (editable, start_pos, end_pos);
379 380
}

381 382 383 384 385 386
/**
 * gtk_editable_cut_clipboard:
 * @editable: a #GtkEditable
 *
 * Removes the contents of the currently selected content in the editable and
 * puts it on the clipboard.
Matthias Clasen's avatar
Matthias Clasen committed
387
 */
388
void
389
gtk_editable_cut_clipboard (GtkEditable *editable)
390
{
391 392
  g_return_if_fail (GTK_IS_EDITABLE (editable));
  
393
  g_signal_emit_by_name (editable, "cut-clipboard");
394 395
}

396 397 398 399 400 401
/**
 * gtk_editable_copy_clipboard:
 * @editable: a #GtkEditable
 *
 * Copies the contents of the currently selected content in the editable and
 * puts it on the clipboard.
Matthias Clasen's avatar
Matthias Clasen committed
402
 */
403 404 405
void
gtk_editable_copy_clipboard (GtkEditable *editable)
{
406 407
  g_return_if_fail (GTK_IS_EDITABLE (editable));
  
408
  g_signal_emit_by_name (editable, "copy-clipboard");
409 410
}

411 412 413 414 415 416
/**
 * gtk_editable_paste_clipboard:
 * @editable: a #GtkEditable
 *
 * Pastes the content of the clipboard to the current position of the
 * cursor in the editable.
Matthias Clasen's avatar
Matthias Clasen committed
417
 */
418
void
419
gtk_editable_paste_clipboard (GtkEditable *editable)
420
{
421 422
  g_return_if_fail (GTK_IS_EDITABLE (editable));
  
423
  g_signal_emit_by_name (editable, "paste-clipboard");
424 425
}

426 427 428 429 430 431 432 433
/**
 * gtk_editable_set_editable:
 * @editable: a #GtkEditable
 * @is_editable: %TRUE if the user is allowed to edit the text
 *   in the widget
 *
 * Determines if the user can edit the text in the editable
 * widget or not. 
Matthias Clasen's avatar
Matthias Clasen committed
434
 */
435 436 437 438 439 440
void
gtk_editable_set_editable (GtkEditable    *editable,
			   gboolean        is_editable)
{
  g_return_if_fail (GTK_IS_EDITABLE (editable));

441
  g_object_set (editable,
Manish Singh's avatar
Manish Singh committed
442 443
		"editable", is_editable != FALSE,
		NULL);
444
}
445 446 447 448 449 450 451 452

/**
 * gtk_editable_get_editable:
 * @editable: a #GtkEditable
 *
 * Retrieves whether @editable is editable. See
 * gtk_editable_set_editable().
 *
453
 * Returns: %TRUE if @editable is editable.
Matthias Clasen's avatar
Matthias Clasen committed
454
 */
455 456 457 458 459 460 461
gboolean
gtk_editable_get_editable (GtkEditable *editable)
{
  gboolean value;

  g_return_val_if_fail (GTK_IS_EDITABLE (editable), FALSE);

462
  g_object_get (editable, "editable", &value, NULL);
463 464 465

  return value;
}