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