]> Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkentry.sgml
2.19.5
[~andy/gtk] / docs / reference / gtk / tmpl / gtkentry.sgml
1 <!-- ##### SECTION Title ##### -->
2 GtkEntry
3
4 <!-- ##### SECTION Short_Description ##### -->
5 A single line text entry field
6
7 <!-- ##### SECTION Long_Description ##### -->
8 <para>
9 The #GtkEntry widget is a single line text entry
10 widget. A fairly large set of key bindings are supported
11 by default. If the entered text is longer than the allocation
12 of the widget, the widget will scroll so that the cursor
13 position is visible. 
14 </para>
15 <para>
16 When using an entry for passwords and other sensitive information,
17 it can be put into "password mode" using gtk_entry_set_visibility(). 
18 In this mode, entered text is displayed using a 'invisible' character.
19 By default, GTK+ picks the best invisible character that is available
20 in the current font, but it can be changed with 
21 gtk_entry_set_invisible_char(). Since 2.16, GTK+ displays a warning
22 when Caps Lock or input methods might interfere with entering text in
23 a password entry. The warning can be turned off with the 
24 #GtkEntry::caps-lock-warning property.
25 </para>
26 <para>
27 Since 2.16, GtkEntry has the ability to display progress or activity 
28 information behind the text. To make an entry display such information, 
29 use gtk_entry_set_progress_fraction() or gtk_entry_set_progress_pulse_step().
30 </para>
31 <para>
32 Additionally, GtkEntry can show icons at either side of the entry. These
33 icons can be activatable by clicking, can be set up as drag source and
34 can have tooltips. To add an icon, use gtk_entry_set_icon_from_gicon() or
35 one of the various other functions that set an icon from a stock id, an
36 icon name or a pixbuf. To trigger an action when the user clicks an icon,
37 connect to the #GtkEntry::icon-press signal. To allow DND operations
38 from an icon, use gtk_entry_set_icon_drag_source(). To set a tooltip on 
39 an icon, use gtk_entry_set_icon_tooltip_text() or the corresponding function
40 for markup.
41 </para>
42 <para>
43 Note that functionality or information that is only available by clicking 
44 on an icon in an entry may not be accessible at all to users which are not 
45 able to use a mouse or other pointing device. It is therefore recommended 
46 that any such functionality should also be available by other means, e.g. 
47 via the context menu of the entry.
48 </para>
49
50 <!-- ##### SECTION See_Also ##### -->
51 <para>
52 <variablelist>
53
54 <varlistentry>
55 <term>#GtkTextView</term>
56 <listitem><para>a widget for handling multi-line text entry.</para></listitem>
57 </varlistentry>
58
59 <varlistentry>
60 <term>#GtkEntryCompletion</term>
61 <listitem><para>adds completion functionality to GtkEntry.</para></listitem>
62 </varlistentry>
63
64 </variablelist>
65 </para>
66
67 <!-- ##### SECTION Stability_Level ##### -->
68
69
70 <!-- ##### STRUCT GtkEntry ##### -->
71 <para>
72 The #GtkEntry-struct struct contains only private data.
73 </para>
74
75
76 <!-- ##### SIGNAL GtkEntry::activate ##### -->
77 <para>
78
79 </para>
80
81 @entry: the object which received the signal.
82
83 <!-- ##### SIGNAL GtkEntry::backspace ##### -->
84 <para>
85
86 </para>
87
88 @entry: the object which received the signal.
89
90 <!-- ##### SIGNAL GtkEntry::copy-clipboard ##### -->
91 <para>
92
93 </para>
94
95 @entry: the object which received the signal.
96
97 <!-- ##### SIGNAL GtkEntry::cut-clipboard ##### -->
98 <para>
99
100 </para>
101
102 @entry: the object which received the signal.
103
104 <!-- ##### SIGNAL GtkEntry::delete-from-cursor ##### -->
105 <para>
106
107 </para>
108
109 @entry: the object which received the signal.
110 @arg1: 
111 @arg2: 
112
113 <!-- ##### SIGNAL GtkEntry::icon-press ##### -->
114 <para>
115
116 </para>
117
118 @entry: the object which received the signal.
119 @arg1: 
120 @event: 
121
122 <!-- ##### SIGNAL GtkEntry::icon-release ##### -->
123 <para>
124
125 </para>
126
127 @entry: the object which received the signal.
128 @arg1: 
129 @event: 
130
131 <!-- ##### SIGNAL GtkEntry::insert-at-cursor ##### -->
132 <para>
133
134 </para>
135
136 @entry: the object which received the signal.
137 @arg1: 
138
139 <!-- ##### SIGNAL GtkEntry::move-cursor ##### -->
140 <para>
141
142 </para>
143
144 @entry: the object which received the signal.
145 @arg1: 
146 @arg2: 
147 @arg3: 
148
149 <!-- ##### SIGNAL GtkEntry::paste-clipboard ##### -->
150 <para>
151
152 </para>
153
154 @entry: the object which received the signal.
155
156 <!-- ##### SIGNAL GtkEntry::populate-popup ##### -->
157 <para>
158
159 </para>
160
161 @entry: the object which received the signal.
162 @arg1: 
163
164 <!-- ##### SIGNAL GtkEntry::preedit-changed ##### -->
165 <para>
166
167 </para>
168
169 @entry: the object which received the signal.
170 @arg1: 
171
172 <!-- ##### SIGNAL GtkEntry::toggle-overwrite ##### -->
173 <para>
174
175 </para>
176
177 @entry: the object which received the signal.
178
179 <!-- ##### ARG GtkEntry:activates-default ##### -->
180 <para>
181
182 </para>
183
184 <!-- ##### ARG GtkEntry:buffer ##### -->
185 <para>
186
187 </para>
188
189 <!-- ##### ARG GtkEntry:caps-lock-warning ##### -->
190 <para>
191
192 </para>
193
194 <!-- ##### ARG GtkEntry:cursor-position ##### -->
195 <para>
196
197 </para>
198
199 <!-- ##### ARG GtkEntry:editable ##### -->
200 <para>
201
202 </para>
203
204 <!-- ##### ARG GtkEntry:has-frame ##### -->
205 <para>
206
207 </para>
208
209 <!-- ##### ARG GtkEntry:im-module ##### -->
210 <para>
211
212 </para>
213
214 <!-- ##### ARG GtkEntry:inner-border ##### -->
215 <para>
216
217 </para>
218
219 <!-- ##### ARG GtkEntry:invisible-char ##### -->
220 <para>
221
222 </para>
223
224 <!-- ##### ARG GtkEntry:invisible-char-set ##### -->
225 <para>
226
227 </para>
228
229 <!-- ##### ARG GtkEntry:max-length ##### -->
230 <para>
231
232 </para>
233
234 <!-- ##### ARG GtkEntry:overwrite-mode ##### -->
235 <para>
236
237 </para>
238
239 <!-- ##### ARG GtkEntry:primary-icon-activatable ##### -->
240 <para>
241
242 </para>
243
244 <!-- ##### ARG GtkEntry:primary-icon-gicon ##### -->
245 <para>
246
247 </para>
248
249 <!-- ##### ARG GtkEntry:primary-icon-name ##### -->
250 <para>
251
252 </para>
253
254 <!-- ##### ARG GtkEntry:primary-icon-pixbuf ##### -->
255 <para>
256
257 </para>
258
259 <!-- ##### ARG GtkEntry:primary-icon-sensitive ##### -->
260 <para>
261
262 </para>
263
264 <!-- ##### ARG GtkEntry:primary-icon-stock ##### -->
265 <para>
266
267 </para>
268
269 <!-- ##### ARG GtkEntry:primary-icon-storage-type ##### -->
270 <para>
271
272 </para>
273
274 <!-- ##### ARG GtkEntry:primary-icon-tooltip-markup ##### -->
275 <para>
276
277 </para>
278
279 <!-- ##### ARG GtkEntry:primary-icon-tooltip-text ##### -->
280 <para>
281
282 </para>
283
284 <!-- ##### ARG GtkEntry:progress-fraction ##### -->
285 <para>
286
287 </para>
288
289 <!-- ##### ARG GtkEntry:progress-pulse-step ##### -->
290 <para>
291
292 </para>
293
294 <!-- ##### ARG GtkEntry:scroll-offset ##### -->
295 <para>
296
297 </para>
298
299 <!-- ##### ARG GtkEntry:secondary-icon-activatable ##### -->
300 <para>
301
302 </para>
303
304 <!-- ##### ARG GtkEntry:secondary-icon-gicon ##### -->
305 <para>
306
307 </para>
308
309 <!-- ##### ARG GtkEntry:secondary-icon-name ##### -->
310 <para>
311
312 </para>
313
314 <!-- ##### ARG GtkEntry:secondary-icon-pixbuf ##### -->
315 <para>
316
317 </para>
318
319 <!-- ##### ARG GtkEntry:secondary-icon-sensitive ##### -->
320 <para>
321
322 </para>
323
324 <!-- ##### ARG GtkEntry:secondary-icon-stock ##### -->
325 <para>
326
327 </para>
328
329 <!-- ##### ARG GtkEntry:secondary-icon-storage-type ##### -->
330 <para>
331
332 </para>
333
334 <!-- ##### ARG GtkEntry:secondary-icon-tooltip-markup ##### -->
335 <para>
336
337 </para>
338
339 <!-- ##### ARG GtkEntry:secondary-icon-tooltip-text ##### -->
340 <para>
341
342 </para>
343
344 <!-- ##### ARG GtkEntry:selection-bound ##### -->
345 <para>
346
347 </para>
348
349 <!-- ##### ARG GtkEntry:shadow-type ##### -->
350 <para>
351
352 </para>
353
354 <!-- ##### ARG GtkEntry:text ##### -->
355 <para>
356
357 </para>
358
359 <!-- ##### ARG GtkEntry:text-length ##### -->
360 <para>
361
362 </para>
363
364 <!-- ##### ARG GtkEntry:truncate-multiline ##### -->
365 <para>
366
367 </para>
368
369 <!-- ##### ARG GtkEntry:visibility ##### -->
370 <para>
371
372 </para>
373
374 <!-- ##### ARG GtkEntry:width-chars ##### -->
375 <para>
376
377 </para>
378
379 <!-- ##### ARG GtkEntry:xalign ##### -->
380 <para>
381
382 </para>
383
384 <!-- ##### ARG GtkEntry:icon-prelight ##### -->
385 <para>
386
387 </para>
388
389 <!-- ##### ARG GtkEntry:inner-border ##### -->
390 <para>
391
392 </para>
393
394 <!-- ##### ARG GtkEntry:invisible-char ##### -->
395 <para>
396
397 </para>
398
399 <!-- ##### ARG GtkEntry:progress-border ##### -->
400 <para>
401
402 </para>
403
404 <!-- ##### ARG GtkEntry:state-hint ##### -->
405 <para>
406
407 </para>
408
409 <!-- ##### FUNCTION gtk_entry_new ##### -->
410 <para>
411
412 </para>
413
414 @Returns: 
415
416
417 <!-- ##### FUNCTION gtk_entry_new_with_buffer ##### -->
418 <para>
419
420 </para>
421
422 @buffer: 
423 @Returns: 
424
425
426 <!-- ##### FUNCTION gtk_entry_new_with_max_length ##### -->
427 <para>
428 </para>
429
430 @max: 
431 @Returns: 
432
433
434 <!-- ##### FUNCTION gtk_entry_get_buffer ##### -->
435 <para>
436
437 </para>
438
439 @entry: 
440 @Returns: 
441
442
443 <!-- ##### FUNCTION gtk_entry_set_buffer ##### -->
444 <para>
445
446 </para>
447
448 @entry: 
449 @buffer: 
450
451
452 <!-- ##### FUNCTION gtk_entry_set_text ##### -->
453 <para>
454
455 </para>
456
457 @entry: 
458 @text: 
459
460
461 <!-- ##### FUNCTION gtk_entry_append_text ##### -->
462 <para>
463
464 </para>
465
466 @entry: 
467 @text: 
468
469
470 <!-- ##### FUNCTION gtk_entry_prepend_text ##### -->
471 <para>
472
473 </para>
474
475 @entry: 
476 @text: 
477
478
479 <!-- ##### FUNCTION gtk_entry_set_position ##### -->
480 <para>
481
482 </para>
483
484 @entry: 
485 @position: 
486
487
488 <!-- ##### FUNCTION gtk_entry_get_text ##### -->
489 <para>
490
491 </para>
492
493 @entry: 
494 @Returns: 
495
496
497 <!-- ##### FUNCTION gtk_entry_get_text_length ##### -->
498 <para>
499
500 </para>
501
502 @entry: 
503 @Returns: 
504
505
506 <!-- ##### FUNCTION gtk_entry_select_region ##### -->
507 <para>
508
509 </para>
510
511 @entry: 
512 @start: 
513 @end: 
514
515
516 <!-- ##### FUNCTION gtk_entry_set_visibility ##### -->
517 <para>
518
519 </para>
520
521 @entry: 
522 @visible: 
523
524
525 <!-- ##### FUNCTION gtk_entry_set_invisible_char ##### -->
526 <para>
527
528 </para>
529
530 @entry: 
531 @ch: 
532
533
534 <!-- ##### FUNCTION gtk_entry_unset_invisible_char ##### -->
535 <para>
536
537 </para>
538
539 @entry: 
540
541
542 <!-- ##### FUNCTION gtk_entry_set_editable ##### -->
543 <para>
544
545 </para>
546
547 @entry: 
548 @editable: 
549
550
551 <!-- ##### FUNCTION gtk_entry_set_max_length ##### -->
552 <para>
553 </para>
554
555 @entry: 
556 @max: 
557
558
559 <!-- ##### FUNCTION gtk_entry_get_activates_default ##### -->
560 <para>
561
562 </para>
563
564 @entry: 
565 @Returns: 
566
567
568 <!-- ##### FUNCTION gtk_entry_get_has_frame ##### -->
569 <para>
570
571 </para>
572
573 @entry: 
574 @Returns: 
575
576
577 <!-- ##### FUNCTION gtk_entry_get_inner_border ##### -->
578 <para>
579
580 </para>
581
582 @entry: 
583 @Returns: 
584
585
586 <!-- ##### FUNCTION gtk_entry_get_width_chars ##### -->
587 <para>
588
589 </para>
590
591 @entry: 
592 @Returns: 
593
594
595 <!-- ##### FUNCTION gtk_entry_set_activates_default ##### -->
596 <para>
597
598 </para>
599
600 @entry: 
601 @setting: 
602
603
604 <!-- ##### FUNCTION gtk_entry_set_has_frame ##### -->
605 <para>
606
607 </para>
608
609 @entry: 
610 @setting: 
611
612
613 <!-- ##### FUNCTION gtk_entry_set_inner_border ##### -->
614 <para>
615
616 </para>
617
618 @entry: 
619 @border: 
620
621
622 <!-- ##### FUNCTION gtk_entry_set_width_chars ##### -->
623 <para>
624
625 </para>
626
627 @entry: 
628 @n_chars: 
629
630
631 <!-- ##### FUNCTION gtk_entry_get_invisible_char ##### -->
632 <para>
633
634 </para>
635
636 @entry: 
637 @Returns: 
638
639
640 <!-- ##### FUNCTION gtk_entry_set_alignment ##### -->
641 <para>
642
643 </para>
644
645 @entry: 
646 @xalign: 
647
648
649 <!-- ##### FUNCTION gtk_entry_get_alignment ##### -->
650 <para>
651
652 </para>
653
654 @entry: 
655 @Returns: 
656
657
658 <!-- ##### FUNCTION gtk_entry_set_overwrite_mode ##### -->
659 <para>
660
661 </para>
662
663 @entry: 
664 @overwrite: 
665
666
667 <!-- ##### FUNCTION gtk_entry_get_overwrite_mode ##### -->
668 <para>
669
670 </para>
671
672 @entry: 
673 @Returns: 
674
675
676 <!-- ##### FUNCTION gtk_entry_get_layout ##### -->
677 <para>
678
679 </para>
680
681 @entry: 
682 @Returns: 
683
684
685 <!-- ##### FUNCTION gtk_entry_get_layout_offsets ##### -->
686 <para>
687
688 </para>
689
690 @entry: 
691 @x: 
692 @y: 
693
694
695 <!-- ##### FUNCTION gtk_entry_layout_index_to_text_index ##### -->
696 <para>
697
698 </para>
699
700 @entry: 
701 @layout_index: 
702 @Returns: 
703
704
705 <!-- ##### FUNCTION gtk_entry_text_index_to_layout_index ##### -->
706 <para>
707
708 </para>
709
710 @entry: 
711 @text_index: 
712 @Returns: 
713
714
715 <!-- ##### FUNCTION gtk_entry_get_max_length ##### -->
716 <para>
717
718 </para>
719
720 @entry: 
721 @Returns: 
722
723
724 <!-- ##### FUNCTION gtk_entry_get_visibility ##### -->
725 <para>
726
727 </para>
728
729 @entry: 
730 @Returns: 
731
732
733 <!-- ##### FUNCTION gtk_entry_set_completion ##### -->
734 <para>
735
736 </para>
737
738 @entry: 
739 @completion: 
740
741
742 <!-- ##### FUNCTION gtk_entry_get_completion ##### -->
743 <para>
744
745 </para>
746
747 @entry: 
748 @Returns: 
749
750
751 <!-- ##### FUNCTION gtk_entry_set_cursor_hadjustment ##### -->
752 <para>
753
754 </para>
755
756 @entry: 
757 @adjustment: 
758
759
760 <!-- ##### FUNCTION gtk_entry_get_cursor_hadjustment ##### -->
761 <para>
762
763 </para>
764
765 @entry: 
766 @Returns: 
767
768
769 <!-- ##### FUNCTION gtk_entry_set_progress_fraction ##### -->
770 <para>
771
772 </para>
773
774 @entry: 
775 @fraction: 
776
777
778 <!-- ##### FUNCTION gtk_entry_get_progress_fraction ##### -->
779 <para>
780
781 </para>
782
783 @entry: 
784 @Returns: 
785
786
787 <!-- ##### FUNCTION gtk_entry_set_progress_pulse_step ##### -->
788 <para>
789
790 </para>
791
792 @entry: 
793 @fraction: 
794
795
796 <!-- ##### FUNCTION gtk_entry_get_progress_pulse_step ##### -->
797 <para>
798
799 </para>
800
801 @entry: 
802 @Returns: 
803
804
805 <!-- ##### FUNCTION gtk_entry_progress_pulse ##### -->
806 <para>
807
808 </para>
809
810 @entry: 
811
812
813 <!-- ##### ENUM GtkEntryIconPosition ##### -->
814 <para>
815 Specifies the side of the entry at which an icon is placed.
816 </para>
817
818 @GTK_ENTRY_ICON_PRIMARY: At the beginning of the entry (depending on the text direction).
819 @GTK_ENTRY_ICON_SECONDARY: At the end of the entry (depending on the text direction).
820
821 <!-- ##### FUNCTION gtk_entry_set_icon_from_pixbuf ##### -->
822 <para>
823
824 </para>
825
826 @entry: 
827 @icon_pos: 
828 @pixbuf: 
829
830
831 <!-- ##### FUNCTION gtk_entry_set_icon_from_stock ##### -->
832 <para>
833
834 </para>
835
836 @entry: 
837 @icon_pos: 
838 @stock_id: 
839
840
841 <!-- ##### FUNCTION gtk_entry_set_icon_from_icon_name ##### -->
842 <para>
843
844 </para>
845
846 @entry: 
847 @icon_pos: 
848 @icon_name: 
849
850
851 <!-- ##### FUNCTION gtk_entry_set_icon_from_gicon ##### -->
852 <para>
853
854 </para>
855
856 @entry: 
857 @icon_pos: 
858 @icon: 
859
860
861 <!-- ##### FUNCTION gtk_entry_get_icon_storage_type ##### -->
862 <para>
863
864 </para>
865
866 @entry: 
867 @icon_pos: 
868 @Returns: 
869
870
871 <!-- ##### FUNCTION gtk_entry_get_icon_pixbuf ##### -->
872 <para>
873
874 </para>
875
876 @entry: 
877 @icon_pos: 
878 @Returns: 
879
880
881 <!-- ##### FUNCTION gtk_entry_get_icon_stock ##### -->
882 <para>
883
884 </para>
885
886 @entry: 
887 @icon_pos: 
888 @Returns: 
889
890
891 <!-- ##### FUNCTION gtk_entry_get_icon_name ##### -->
892 <para>
893
894 </para>
895
896 @entry: 
897 @icon_pos: 
898 @Returns: 
899
900
901 <!-- ##### FUNCTION gtk_entry_get_icon_gicon ##### -->
902 <para>
903
904 </para>
905
906 @entry: 
907 @icon_pos: 
908 @Returns: 
909
910
911 <!-- ##### FUNCTION gtk_entry_set_icon_activatable ##### -->
912 <para>
913
914 </para>
915
916 @entry: 
917 @icon_pos: 
918 @activatable: 
919
920
921 <!-- ##### FUNCTION gtk_entry_get_icon_activatable ##### -->
922 <para>
923
924 </para>
925
926 @entry: 
927 @icon_pos: 
928 @Returns: 
929
930
931 <!-- ##### FUNCTION gtk_entry_set_icon_sensitive ##### -->
932 <para>
933
934 </para>
935
936 @entry: 
937 @icon_pos: 
938 @sensitive: 
939
940
941 <!-- ##### FUNCTION gtk_entry_get_icon_sensitive ##### -->
942 <para>
943
944 </para>
945
946 @entry: 
947 @icon_pos: 
948 @Returns: 
949
950
951 <!-- ##### FUNCTION gtk_entry_get_icon_at_pos ##### -->
952 <para>
953
954 </para>
955
956 @entry: 
957 @x: 
958 @y: 
959 @Returns: 
960
961
962 <!-- ##### FUNCTION gtk_entry_set_icon_tooltip_text ##### -->
963 <para>
964
965 </para>
966
967 @entry: 
968 @icon_pos: 
969 @tooltip: 
970
971
972 <!-- ##### FUNCTION gtk_entry_get_icon_tooltip_text ##### -->
973 <para>
974
975 </para>
976
977 @entry: 
978 @icon_pos: 
979 @Returns: 
980
981
982 <!-- ##### FUNCTION gtk_entry_set_icon_tooltip_markup ##### -->
983 <para>
984
985 </para>
986
987 @entry: 
988 @icon_pos: 
989 @tooltip: 
990
991
992 <!-- ##### FUNCTION gtk_entry_get_icon_tooltip_markup ##### -->
993 <para>
994
995 </para>
996
997 @entry: 
998 @icon_pos: 
999 @Returns: 
1000
1001
1002 <!-- ##### FUNCTION gtk_entry_set_icon_drag_source ##### -->
1003 <para>
1004
1005 </para>
1006
1007 @entry: 
1008 @icon_pos: 
1009 @target_list: 
1010 @actions: 
1011
1012
1013 <!-- ##### FUNCTION gtk_entry_get_current_icon_drag_source ##### -->
1014 <para>
1015
1016 </para>
1017
1018 @entry: 
1019 @Returns: 
1020
1021
1022 <!-- ##### FUNCTION gtk_entry_get_icon_window ##### -->
1023 <para>
1024
1025 </para>
1026
1027 @entry: 
1028 @icon_pos: 
1029 @Returns: 
1030
1031
1032 <!-- ##### FUNCTION gtk_entry_get_text_window ##### -->
1033 <para>
1034
1035 </para>
1036
1037 @entry: 
1038 @Returns: 
1039
1040