1/* GTK - The GIMP Toolkit
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
3 *
4 * Copyright (C) 2004-2006 Christian Hammond
5 * Copyright (C) 2008 Cody Russell
6 * Copyright (C) 2008 Red Hat, Inc.
7 *
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
12 *
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
20 */
21
22/*
23 * Modified by the GTK+ Team and others 1997-2000. See the AUTHORS
24 * file for a list of people on the GTK+ Team. See the ChangeLog
25 * files for a list of changes. These files are distributed with
26 * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
27 */
28
29#ifndef __GTK_ENTRY_H__
30#define __GTK_ENTRY_H__
31
32
33#if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
34#error "Only <gtk/gtk.h> can be included directly."
35#endif
36
37#include <gtk/gtkeditable.h>
38#include <gtk/gtkimcontext.h>
39#include <gtk/gtkmenu.h>
40#include <gtk/gtkentrybuffer.h>
41#include <gtk/gtkentrycompletion.h>
42#include <gtk/gtkimage.h>
43#include <gtk/gtkselection.h>
44
45
46G_BEGIN_DECLS
47
48#define GTK_TYPE_ENTRY (gtk_entry_get_type ())
49#define GTK_ENTRY(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_ENTRY, GtkEntry))
50#define GTK_ENTRY_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GTK_TYPE_ENTRY, GtkEntryClass))
51#define GTK_IS_ENTRY(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_ENTRY))
52#define GTK_IS_ENTRY_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_ENTRY))
53#define GTK_ENTRY_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_ENTRY, GtkEntryClass))
54
55/**
56 * GtkEntryIconPosition:
57 * @GTK_ENTRY_ICON_PRIMARY: At the beginning of the entry (depending on the text direction).
58 * @GTK_ENTRY_ICON_SECONDARY: At the end of the entry (depending on the text direction).
59 *
60 * Specifies the side of the entry at which an icon is placed.
61 *
62 * Since: 2.16
63 */
64typedef enum
65{
66 GTK_ENTRY_ICON_PRIMARY,
67 GTK_ENTRY_ICON_SECONDARY
68} GtkEntryIconPosition;
69
70typedef struct _GtkEntry GtkEntry;
71typedef struct _GtkEntryPrivate GtkEntryPrivate;
72typedef struct _GtkEntryClass GtkEntryClass;
73
74struct _GtkEntry
75{
76 /*< private >*/
77 GtkWidget parent_instance;
78
79 GtkEntryPrivate *priv;
80};
81
82/**
83 * GtkEntryClass:
84 * @parent_class: The parent class.
85 * @populate_popup: Class handler for the #GtkEntry::populate-popup signal. If
86 * non-%NULL, this will be called to add additional entries to the context
87 * menu when it is displayed.
88 * @activate: Class handler for the #GtkEntry::activate signal. The default
89 * implementation calls gtk_window_activate_default() on the entry’s top-level
90 * window.
91 * @move_cursor: Class handler for the #GtkEntry::move-cursor signal. The
92 * default implementation specifies the standard #GtkEntry cursor movement
93 * behavior.
94 * @insert_at_cursor: Class handler for the #GtkEntry::insert-at-cursor signal.
95 * The default implementation inserts text at the cursor.
96 * @delete_from_cursor: Class handler for the #GtkEntry::delete-from-cursor
97 * signal. The default implementation deletes the selection or the specified
98 * number of characters or words.
99 * @backspace: Class handler for the #GtkEntry::backspace signal. The default
100 * implementation deletes the selection or a single character or word.
101 * @cut_clipboard: Class handler for the #GtkEntry::cut-clipboard signal. The
102 * default implementation cuts the selection, if one exists.
103 * @copy_clipboard: Class handler for the #GtkEntry::copy-clipboard signal. The
104 * default implementation copies the selection, if one exists.
105 * @paste_clipboard: Class handler for the #GtkEntry::paste-clipboard signal.
106 * The default implementation pastes at the current cursor position or over
107 * the current selection if one exists.
108 * @toggle_overwrite: Class handler for the #GtkEntry::toggle-overwrite signal.
109 * The default implementation toggles overwrite mode and blinks the cursor.
110 * @get_text_area_size: Calculate the size of the text area, which is its
111 * allocated width and requested height, minus space for margins and borders.
112 * This virtual function must be non-%NULL.
113 * @get_frame_size: Calculate the size of the text area frame, which is its
114 * allocated width and requested height, minus space for margins and borders,
115 * and taking baseline and text height into account. This virtual function
116 * must be non-%NULL.
117 *
118 * Class structure for #GtkEntry. All virtual functions have a default
119 * implementation. Derived classes may set the virtual function pointers for the
120 * signal handlers to %NULL, but must keep @get_text_area_size and
121 * @get_frame_size non-%NULL; either use the default implementation, or provide
122 * a custom one.
123 */
124struct _GtkEntryClass
125{
126 GtkWidgetClass parent_class;
127
128 /* Hook to customize right-click popup */
129 void (* populate_popup) (GtkEntry *entry,
130 GtkWidget *popup);
131
132 /* Action signals
133 */
134 void (* activate) (GtkEntry *entry);
135 void (* move_cursor) (GtkEntry *entry,
136 GtkMovementStep step,
137 gint count,
138 gboolean extend_selection);
139 void (* insert_at_cursor) (GtkEntry *entry,
140 const gchar *str);
141 void (* delete_from_cursor) (GtkEntry *entry,
142 GtkDeleteType type,
143 gint count);
144 void (* backspace) (GtkEntry *entry);
145 void (* cut_clipboard) (GtkEntry *entry);
146 void (* copy_clipboard) (GtkEntry *entry);
147 void (* paste_clipboard) (GtkEntry *entry);
148 void (* toggle_overwrite) (GtkEntry *entry);
149
150 /* hooks to add other objects beside the entry (like in GtkSpinButton) */
151 void (* get_text_area_size) (GtkEntry *entry,
152 gint *x,
153 gint *y,
154 gint *width,
155 gint *height);
156 void (* get_frame_size) (GtkEntry *entry,
157 gint *x,
158 gint *y,
159 gint *width,
160 gint *height);
161 void (* insert_emoji) (GtkEntry *entry);
162
163 /*< private >*/
164
165 void (* toggle_direction) (GtkEntry *entry);
166
167 /* Padding for future expansion */
168 void (*_gtk_reserved1) (void);
169 void (*_gtk_reserved2) (void);
170 void (*_gtk_reserved3) (void);
171 void (*_gtk_reserved4) (void);
172 void (*_gtk_reserved5) (void);
173};
174
175GDK_AVAILABLE_IN_ALL
176GType gtk_entry_get_type (void) G_GNUC_CONST;
177GDK_AVAILABLE_IN_ALL
178GtkWidget* gtk_entry_new (void);
179GDK_AVAILABLE_IN_ALL
180GtkWidget* gtk_entry_new_with_buffer (GtkEntryBuffer *buffer);
181
182GDK_AVAILABLE_IN_ALL
183GtkEntryBuffer* gtk_entry_get_buffer (GtkEntry *entry);
184GDK_AVAILABLE_IN_ALL
185void gtk_entry_set_buffer (GtkEntry *entry,
186 GtkEntryBuffer *buffer);
187
188GDK_AVAILABLE_IN_ALL
189void gtk_entry_get_text_area (GtkEntry *entry,
190 GdkRectangle *text_area);
191
192GDK_AVAILABLE_IN_ALL
193void gtk_entry_set_visibility (GtkEntry *entry,
194 gboolean visible);
195GDK_AVAILABLE_IN_ALL
196gboolean gtk_entry_get_visibility (GtkEntry *entry);
197
198GDK_AVAILABLE_IN_ALL
199void gtk_entry_set_invisible_char (GtkEntry *entry,
200 gunichar ch);
201GDK_AVAILABLE_IN_ALL
202gunichar gtk_entry_get_invisible_char (GtkEntry *entry);
203GDK_AVAILABLE_IN_ALL
204void gtk_entry_unset_invisible_char (GtkEntry *entry);
205
206GDK_AVAILABLE_IN_ALL
207void gtk_entry_set_has_frame (GtkEntry *entry,
208 gboolean setting);
209GDK_AVAILABLE_IN_ALL
210gboolean gtk_entry_get_has_frame (GtkEntry *entry);
211
212GDK_DEPRECATED_IN_3_4
213void gtk_entry_set_inner_border (GtkEntry *entry,
214 const GtkBorder *border);
215GDK_DEPRECATED_IN_3_4
216const GtkBorder* gtk_entry_get_inner_border (GtkEntry *entry);
217
218GDK_AVAILABLE_IN_ALL
219void gtk_entry_set_overwrite_mode (GtkEntry *entry,
220 gboolean overwrite);
221GDK_AVAILABLE_IN_ALL
222gboolean gtk_entry_get_overwrite_mode (GtkEntry *entry);
223
224/* text is truncated if needed */
225GDK_AVAILABLE_IN_ALL
226void gtk_entry_set_max_length (GtkEntry *entry,
227 gint max);
228GDK_AVAILABLE_IN_ALL
229gint gtk_entry_get_max_length (GtkEntry *entry);
230GDK_AVAILABLE_IN_ALL
231guint16 gtk_entry_get_text_length (GtkEntry *entry);
232
233GDK_AVAILABLE_IN_ALL
234void gtk_entry_set_activates_default (GtkEntry *entry,
235 gboolean setting);
236GDK_AVAILABLE_IN_ALL
237gboolean gtk_entry_get_activates_default (GtkEntry *entry);
238
239GDK_AVAILABLE_IN_ALL
240void gtk_entry_set_width_chars (GtkEntry *entry,
241 gint n_chars);
242GDK_AVAILABLE_IN_ALL
243gint gtk_entry_get_width_chars (GtkEntry *entry);
244
245GDK_AVAILABLE_IN_3_12
246void gtk_entry_set_max_width_chars (GtkEntry *entry,
247 gint n_chars);
248GDK_AVAILABLE_IN_3_12
249gint gtk_entry_get_max_width_chars (GtkEntry *entry);
250
251/* Somewhat more convenient than the GtkEditable generic functions
252 */
253GDK_AVAILABLE_IN_ALL
254void gtk_entry_set_text (GtkEntry *entry,
255 const gchar *text);
256/* returns a reference to the text */
257GDK_AVAILABLE_IN_ALL
258const gchar* gtk_entry_get_text (GtkEntry *entry);
259
260GDK_AVAILABLE_IN_ALL
261PangoLayout* gtk_entry_get_layout (GtkEntry *entry);
262GDK_AVAILABLE_IN_ALL
263void gtk_entry_get_layout_offsets (GtkEntry *entry,
264 gint *x,
265 gint *y);
266GDK_AVAILABLE_IN_ALL
267void gtk_entry_set_alignment (GtkEntry *entry,
268 gfloat xalign);
269GDK_AVAILABLE_IN_ALL
270gfloat gtk_entry_get_alignment (GtkEntry *entry);
271
272GDK_AVAILABLE_IN_ALL
273void gtk_entry_set_completion (GtkEntry *entry,
274 GtkEntryCompletion *completion);
275GDK_AVAILABLE_IN_ALL
276GtkEntryCompletion *gtk_entry_get_completion (GtkEntry *entry);
277
278GDK_AVAILABLE_IN_ALL
279gint gtk_entry_layout_index_to_text_index (GtkEntry *entry,
280 gint layout_index);
281GDK_AVAILABLE_IN_ALL
282gint gtk_entry_text_index_to_layout_index (GtkEntry *entry,
283 gint text_index);
284
285/* For scrolling cursor appropriately
286 */
287GDK_AVAILABLE_IN_ALL
288void gtk_entry_set_cursor_hadjustment (GtkEntry *entry,
289 GtkAdjustment *adjustment);
290GDK_AVAILABLE_IN_ALL
291GtkAdjustment* gtk_entry_get_cursor_hadjustment (GtkEntry *entry);
292
293/* Progress API
294 */
295GDK_AVAILABLE_IN_ALL
296void gtk_entry_set_progress_fraction (GtkEntry *entry,
297 gdouble fraction);
298GDK_AVAILABLE_IN_ALL
299gdouble gtk_entry_get_progress_fraction (GtkEntry *entry);
300
301GDK_AVAILABLE_IN_ALL
302void gtk_entry_set_progress_pulse_step (GtkEntry *entry,
303 gdouble fraction);
304GDK_AVAILABLE_IN_ALL
305gdouble gtk_entry_get_progress_pulse_step (GtkEntry *entry);
306
307GDK_AVAILABLE_IN_ALL
308void gtk_entry_progress_pulse (GtkEntry *entry);
309GDK_AVAILABLE_IN_3_2
310const gchar* gtk_entry_get_placeholder_text (GtkEntry *entry);
311GDK_AVAILABLE_IN_3_2
312void gtk_entry_set_placeholder_text (GtkEntry *entry,
313 const gchar *text);
314/* Setting and managing icons
315 */
316GDK_AVAILABLE_IN_ALL
317void gtk_entry_set_icon_from_pixbuf (GtkEntry *entry,
318 GtkEntryIconPosition icon_pos,
319 GdkPixbuf *pixbuf);
320GDK_DEPRECATED_IN_3_10_FOR(gtk_entry_set_icon_from_icon_name)
321void gtk_entry_set_icon_from_stock (GtkEntry *entry,
322 GtkEntryIconPosition icon_pos,
323 const gchar *stock_id);
324GDK_AVAILABLE_IN_ALL
325void gtk_entry_set_icon_from_icon_name (GtkEntry *entry,
326 GtkEntryIconPosition icon_pos,
327 const gchar *icon_name);
328GDK_AVAILABLE_IN_ALL
329void gtk_entry_set_icon_from_gicon (GtkEntry *entry,
330 GtkEntryIconPosition icon_pos,
331 GIcon *icon);
332GDK_AVAILABLE_IN_ALL
333GtkImageType gtk_entry_get_icon_storage_type (GtkEntry *entry,
334 GtkEntryIconPosition icon_pos);
335GDK_AVAILABLE_IN_ALL
336GdkPixbuf* gtk_entry_get_icon_pixbuf (GtkEntry *entry,
337 GtkEntryIconPosition icon_pos);
338GDK_DEPRECATED_IN_3_10_FOR(gtk_entry_get_icon_name)
339const gchar* gtk_entry_get_icon_stock (GtkEntry *entry,
340 GtkEntryIconPosition icon_pos);
341GDK_AVAILABLE_IN_ALL
342const gchar* gtk_entry_get_icon_name (GtkEntry *entry,
343 GtkEntryIconPosition icon_pos);
344GDK_AVAILABLE_IN_ALL
345GIcon* gtk_entry_get_icon_gicon (GtkEntry *entry,
346 GtkEntryIconPosition icon_pos);
347GDK_AVAILABLE_IN_ALL
348void gtk_entry_set_icon_activatable (GtkEntry *entry,
349 GtkEntryIconPosition icon_pos,
350 gboolean activatable);
351GDK_AVAILABLE_IN_ALL
352gboolean gtk_entry_get_icon_activatable (GtkEntry *entry,
353 GtkEntryIconPosition icon_pos);
354GDK_AVAILABLE_IN_ALL
355void gtk_entry_set_icon_sensitive (GtkEntry *entry,
356 GtkEntryIconPosition icon_pos,
357 gboolean sensitive);
358GDK_AVAILABLE_IN_ALL
359gboolean gtk_entry_get_icon_sensitive (GtkEntry *entry,
360 GtkEntryIconPosition icon_pos);
361GDK_AVAILABLE_IN_ALL
362gint gtk_entry_get_icon_at_pos (GtkEntry *entry,
363 gint x,
364 gint y);
365GDK_AVAILABLE_IN_ALL
366void gtk_entry_set_icon_tooltip_text (GtkEntry *entry,
367 GtkEntryIconPosition icon_pos,
368 const gchar *tooltip);
369GDK_AVAILABLE_IN_ALL
370gchar * gtk_entry_get_icon_tooltip_text (GtkEntry *entry,
371 GtkEntryIconPosition icon_pos);
372GDK_AVAILABLE_IN_ALL
373void gtk_entry_set_icon_tooltip_markup (GtkEntry *entry,
374 GtkEntryIconPosition icon_pos,
375 const gchar *tooltip);
376GDK_AVAILABLE_IN_ALL
377gchar * gtk_entry_get_icon_tooltip_markup (GtkEntry *entry,
378 GtkEntryIconPosition icon_pos);
379GDK_AVAILABLE_IN_ALL
380void gtk_entry_set_icon_drag_source (GtkEntry *entry,
381 GtkEntryIconPosition icon_pos,
382 GtkTargetList *target_list,
383 GdkDragAction actions);
384GDK_AVAILABLE_IN_ALL
385gint gtk_entry_get_current_icon_drag_source (GtkEntry *entry);
386GDK_AVAILABLE_IN_ALL
387void gtk_entry_get_icon_area (GtkEntry *entry,
388 GtkEntryIconPosition icon_pos,
389 GdkRectangle *icon_area);
390
391GDK_AVAILABLE_IN_ALL
392gboolean gtk_entry_im_context_filter_keypress (GtkEntry *entry,
393 GdkEventKey *event);
394GDK_AVAILABLE_IN_ALL
395void gtk_entry_reset_im_context (GtkEntry *entry);
396
397GDK_AVAILABLE_IN_3_6
398void gtk_entry_set_input_purpose (GtkEntry *entry,
399 GtkInputPurpose purpose);
400GDK_AVAILABLE_IN_3_6
401GtkInputPurpose gtk_entry_get_input_purpose (GtkEntry *entry);
402
403GDK_AVAILABLE_IN_3_6
404void gtk_entry_set_input_hints (GtkEntry *entry,
405 GtkInputHints hints);
406GDK_AVAILABLE_IN_3_6
407GtkInputHints gtk_entry_get_input_hints (GtkEntry *entry);
408
409GDK_AVAILABLE_IN_3_6
410void gtk_entry_set_attributes (GtkEntry *entry,
411 PangoAttrList *attrs);
412GDK_AVAILABLE_IN_3_6
413PangoAttrList *gtk_entry_get_attributes (GtkEntry *entry);
414
415GDK_AVAILABLE_IN_3_10
416void gtk_entry_set_tabs (GtkEntry *entry,
417 PangoTabArray *tabs);
418
419GDK_AVAILABLE_IN_3_10
420PangoTabArray *gtk_entry_get_tabs (GtkEntry *entry);
421
422GDK_AVAILABLE_IN_3_16
423void gtk_entry_grab_focus_without_selecting (GtkEntry *entry);
424
425G_END_DECLS
426
427#endif /* __GTK_ENTRY_H__ */
428