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 /* Padding for future expansion */
166 void (*_gtk_reserved1) (void);
167 void (*_gtk_reserved2) (void);
168 void (*_gtk_reserved3) (void);
169 void (*_gtk_reserved4) (void);
170 void (*_gtk_reserved5) (void);
171 void (*_gtk_reserved6) (void);
172};
173
174GDK_AVAILABLE_IN_ALL
175GType gtk_entry_get_type (void) G_GNUC_CONST;
176GDK_AVAILABLE_IN_ALL
177GtkWidget* gtk_entry_new (void);
178GDK_AVAILABLE_IN_ALL
179GtkWidget* gtk_entry_new_with_buffer (GtkEntryBuffer *buffer);
180
181GDK_AVAILABLE_IN_ALL
182GtkEntryBuffer* gtk_entry_get_buffer (GtkEntry *entry);
183GDK_AVAILABLE_IN_ALL
184void gtk_entry_set_buffer (GtkEntry *entry,
185 GtkEntryBuffer *buffer);
186
187GDK_AVAILABLE_IN_ALL
188void gtk_entry_get_text_area (GtkEntry *entry,
189 GdkRectangle *text_area);
190
191GDK_AVAILABLE_IN_ALL
192void gtk_entry_set_visibility (GtkEntry *entry,
193 gboolean visible);
194GDK_AVAILABLE_IN_ALL
195gboolean gtk_entry_get_visibility (GtkEntry *entry);
196
197GDK_AVAILABLE_IN_ALL
198void gtk_entry_set_invisible_char (GtkEntry *entry,
199 gunichar ch);
200GDK_AVAILABLE_IN_ALL
201gunichar gtk_entry_get_invisible_char (GtkEntry *entry);
202GDK_AVAILABLE_IN_ALL
203void gtk_entry_unset_invisible_char (GtkEntry *entry);
204
205GDK_AVAILABLE_IN_ALL
206void gtk_entry_set_has_frame (GtkEntry *entry,
207 gboolean setting);
208GDK_AVAILABLE_IN_ALL
209gboolean gtk_entry_get_has_frame (GtkEntry *entry);
210
211GDK_DEPRECATED_IN_3_4
212void gtk_entry_set_inner_border (GtkEntry *entry,
213 const GtkBorder *border);
214GDK_DEPRECATED_IN_3_4
215const GtkBorder* gtk_entry_get_inner_border (GtkEntry *entry);
216
217GDK_AVAILABLE_IN_ALL
218void gtk_entry_set_overwrite_mode (GtkEntry *entry,
219 gboolean overwrite);
220GDK_AVAILABLE_IN_ALL
221gboolean gtk_entry_get_overwrite_mode (GtkEntry *entry);
222
223/* text is truncated if needed */
224GDK_AVAILABLE_IN_ALL
225void gtk_entry_set_max_length (GtkEntry *entry,
226 gint max);
227GDK_AVAILABLE_IN_ALL
228gint gtk_entry_get_max_length (GtkEntry *entry);
229GDK_AVAILABLE_IN_ALL
230guint16 gtk_entry_get_text_length (GtkEntry *entry);
231
232GDK_AVAILABLE_IN_ALL
233void gtk_entry_set_activates_default (GtkEntry *entry,
234 gboolean setting);
235GDK_AVAILABLE_IN_ALL
236gboolean gtk_entry_get_activates_default (GtkEntry *entry);
237
238GDK_AVAILABLE_IN_ALL
239void gtk_entry_set_width_chars (GtkEntry *entry,
240 gint n_chars);
241GDK_AVAILABLE_IN_ALL
242gint gtk_entry_get_width_chars (GtkEntry *entry);
243
244GDK_AVAILABLE_IN_3_12
245void gtk_entry_set_max_width_chars (GtkEntry *entry,
246 gint n_chars);
247GDK_AVAILABLE_IN_3_12
248gint gtk_entry_get_max_width_chars (GtkEntry *entry);
249
250/* Somewhat more convenient than the GtkEditable generic functions
251 */
252GDK_AVAILABLE_IN_ALL
253void gtk_entry_set_text (GtkEntry *entry,
254 const gchar *text);
255/* returns a reference to the text */
256GDK_AVAILABLE_IN_ALL
257const gchar* gtk_entry_get_text (GtkEntry *entry);
258
259GDK_AVAILABLE_IN_ALL
260PangoLayout* gtk_entry_get_layout (GtkEntry *entry);
261GDK_AVAILABLE_IN_ALL
262void gtk_entry_get_layout_offsets (GtkEntry *entry,
263 gint *x,
264 gint *y);
265GDK_AVAILABLE_IN_ALL
266void gtk_entry_set_alignment (GtkEntry *entry,
267 gfloat xalign);
268GDK_AVAILABLE_IN_ALL
269gfloat gtk_entry_get_alignment (GtkEntry *entry);
270
271GDK_AVAILABLE_IN_ALL
272void gtk_entry_set_completion (GtkEntry *entry,
273 GtkEntryCompletion *completion);
274GDK_AVAILABLE_IN_ALL
275GtkEntryCompletion *gtk_entry_get_completion (GtkEntry *entry);
276
277GDK_AVAILABLE_IN_ALL
278gint gtk_entry_layout_index_to_text_index (GtkEntry *entry,
279 gint layout_index);
280GDK_AVAILABLE_IN_ALL
281gint gtk_entry_text_index_to_layout_index (GtkEntry *entry,
282 gint text_index);
283
284/* For scrolling cursor appropriately
285 */
286GDK_AVAILABLE_IN_ALL
287void gtk_entry_set_cursor_hadjustment (GtkEntry *entry,
288 GtkAdjustment *adjustment);
289GDK_AVAILABLE_IN_ALL
290GtkAdjustment* gtk_entry_get_cursor_hadjustment (GtkEntry *entry);
291
292/* Progress API
293 */
294GDK_AVAILABLE_IN_ALL
295void gtk_entry_set_progress_fraction (GtkEntry *entry,
296 gdouble fraction);
297GDK_AVAILABLE_IN_ALL
298gdouble gtk_entry_get_progress_fraction (GtkEntry *entry);
299
300GDK_AVAILABLE_IN_ALL
301void gtk_entry_set_progress_pulse_step (GtkEntry *entry,
302 gdouble fraction);
303GDK_AVAILABLE_IN_ALL
304gdouble gtk_entry_get_progress_pulse_step (GtkEntry *entry);
305
306GDK_AVAILABLE_IN_ALL
307void gtk_entry_progress_pulse (GtkEntry *entry);
308GDK_AVAILABLE_IN_3_2
309const gchar* gtk_entry_get_placeholder_text (GtkEntry *entry);
310GDK_AVAILABLE_IN_3_2
311void gtk_entry_set_placeholder_text (GtkEntry *entry,
312 const gchar *text);
313/* Setting and managing icons
314 */
315GDK_AVAILABLE_IN_ALL
316void gtk_entry_set_icon_from_pixbuf (GtkEntry *entry,
317 GtkEntryIconPosition icon_pos,
318 GdkPixbuf *pixbuf);
319GDK_DEPRECATED_IN_3_10_FOR(gtk_entry_set_icon_from_icon_name)
320void gtk_entry_set_icon_from_stock (GtkEntry *entry,
321 GtkEntryIconPosition icon_pos,
322 const gchar *stock_id);
323GDK_AVAILABLE_IN_ALL
324void gtk_entry_set_icon_from_icon_name (GtkEntry *entry,
325 GtkEntryIconPosition icon_pos,
326 const gchar *icon_name);
327GDK_AVAILABLE_IN_ALL
328void gtk_entry_set_icon_from_gicon (GtkEntry *entry,
329 GtkEntryIconPosition icon_pos,
330 GIcon *icon);
331GDK_AVAILABLE_IN_ALL
332GtkImageType gtk_entry_get_icon_storage_type (GtkEntry *entry,
333 GtkEntryIconPosition icon_pos);
334GDK_AVAILABLE_IN_ALL
335GdkPixbuf* gtk_entry_get_icon_pixbuf (GtkEntry *entry,
336 GtkEntryIconPosition icon_pos);
337GDK_DEPRECATED_IN_3_10_FOR(gtk_entry_get_icon_name)
338const gchar* gtk_entry_get_icon_stock (GtkEntry *entry,
339 GtkEntryIconPosition icon_pos);
340GDK_AVAILABLE_IN_ALL
341const gchar* gtk_entry_get_icon_name (GtkEntry *entry,
342 GtkEntryIconPosition icon_pos);
343GDK_AVAILABLE_IN_ALL
344GIcon* gtk_entry_get_icon_gicon (GtkEntry *entry,
345 GtkEntryIconPosition icon_pos);
346GDK_AVAILABLE_IN_ALL
347void gtk_entry_set_icon_activatable (GtkEntry *entry,
348 GtkEntryIconPosition icon_pos,
349 gboolean activatable);
350GDK_AVAILABLE_IN_ALL
351gboolean gtk_entry_get_icon_activatable (GtkEntry *entry,
352 GtkEntryIconPosition icon_pos);
353GDK_AVAILABLE_IN_ALL
354void gtk_entry_set_icon_sensitive (GtkEntry *entry,
355 GtkEntryIconPosition icon_pos,
356 gboolean sensitive);
357GDK_AVAILABLE_IN_ALL
358gboolean gtk_entry_get_icon_sensitive (GtkEntry *entry,
359 GtkEntryIconPosition icon_pos);
360GDK_AVAILABLE_IN_ALL
361gint gtk_entry_get_icon_at_pos (GtkEntry *entry,
362 gint x,
363 gint y);
364GDK_AVAILABLE_IN_ALL
365void gtk_entry_set_icon_tooltip_text (GtkEntry *entry,
366 GtkEntryIconPosition icon_pos,
367 const gchar *tooltip);
368GDK_AVAILABLE_IN_ALL
369gchar * gtk_entry_get_icon_tooltip_text (GtkEntry *entry,
370 GtkEntryIconPosition icon_pos);
371GDK_AVAILABLE_IN_ALL
372void gtk_entry_set_icon_tooltip_markup (GtkEntry *entry,
373 GtkEntryIconPosition icon_pos,
374 const gchar *tooltip);
375GDK_AVAILABLE_IN_ALL
376gchar * gtk_entry_get_icon_tooltip_markup (GtkEntry *entry,
377 GtkEntryIconPosition icon_pos);
378GDK_AVAILABLE_IN_ALL
379void gtk_entry_set_icon_drag_source (GtkEntry *entry,
380 GtkEntryIconPosition icon_pos,
381 GtkTargetList *target_list,
382 GdkDragAction actions);
383GDK_AVAILABLE_IN_ALL
384gint gtk_entry_get_current_icon_drag_source (GtkEntry *entry);
385GDK_AVAILABLE_IN_ALL
386void gtk_entry_get_icon_area (GtkEntry *entry,
387 GtkEntryIconPosition icon_pos,
388 GdkRectangle *icon_area);
389
390GDK_AVAILABLE_IN_ALL
391gboolean gtk_entry_im_context_filter_keypress (GtkEntry *entry,
392 GdkEventKey *event);
393GDK_AVAILABLE_IN_ALL
394void gtk_entry_reset_im_context (GtkEntry *entry);
395
396GDK_AVAILABLE_IN_3_6
397void gtk_entry_set_input_purpose (GtkEntry *entry,
398 GtkInputPurpose purpose);
399GDK_AVAILABLE_IN_3_6
400GtkInputPurpose gtk_entry_get_input_purpose (GtkEntry *entry);
401
402GDK_AVAILABLE_IN_3_6
403void gtk_entry_set_input_hints (GtkEntry *entry,
404 GtkInputHints hints);
405GDK_AVAILABLE_IN_3_6
406GtkInputHints gtk_entry_get_input_hints (GtkEntry *entry);
407
408GDK_AVAILABLE_IN_3_6
409void gtk_entry_set_attributes (GtkEntry *entry,
410 PangoAttrList *attrs);
411GDK_AVAILABLE_IN_3_6
412PangoAttrList *gtk_entry_get_attributes (GtkEntry *entry);
413
414GDK_AVAILABLE_IN_3_10
415void gtk_entry_set_tabs (GtkEntry *entry,
416 PangoTabArray *tabs);
417
418GDK_AVAILABLE_IN_3_10
419PangoTabArray *gtk_entry_get_tabs (GtkEntry *entry);
420
421GDK_AVAILABLE_IN_3_16
422void gtk_entry_grab_focus_without_selecting (GtkEntry *entry);
423
424G_END_DECLS
425
426#endif /* __GTK_ENTRY_H__ */
427