Pileus Git - ~andy/gtk/blob - 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-pressed ##### -->
 114 <para>
 115
 116 </para>
 117
 118 @entry: the object which received the signal.
 119 @arg1:
 120 @event:
 121
 122 <!-- ##### SIGNAL GtkEntry::icon-released ##### -->
 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::toggle-overwrite ##### -->
 165 <para>
 166
 167 </para>
 168
 169 @entry: the object which received the signal.
 170
 171 <!-- ##### ARG GtkEntry:activatable-primary ##### -->
 172 <para>
 173
 174 </para>
 175
 176 <!-- ##### ARG GtkEntry:activatable-secondary ##### -->
 177 <para>
 178
 179 </para>
 180
 181 <!-- ##### ARG GtkEntry:activates-default ##### -->
 182 <para>
 183
 184 </para>
 185
 186 <!-- ##### ARG GtkEntry:caps-lock-warning ##### -->
 187 <para>
 188
 189 </para>
 190
 191 <!-- ##### ARG GtkEntry:cursor-position ##### -->
 192 <para>
 193
 194 </para>
 195
 196 <!-- ##### ARG GtkEntry:editable ##### -->
 197 <para>
 198
 199 </para>
 200
 201 <!-- ##### ARG GtkEntry:gicon-primary ##### -->
 202 <para>
 203
 204 </para>
 205
 206 <!-- ##### ARG GtkEntry:gicon-secondary ##### -->
 207 <para>
 208
 209 </para>
 210
 211 <!-- ##### ARG GtkEntry:has-frame ##### -->
 212 <para>
 213
 214 </para>
 215
 216 <!-- ##### ARG GtkEntry:icon-name-primary ##### -->
 217 <para>
 218
 219 </para>
 220
 221 <!-- ##### ARG GtkEntry:icon-name-secondary ##### -->
 222 <para>
 223
 224 </para>
 225
 226 <!-- ##### ARG GtkEntry:inner-border ##### -->
 227 <para>
 228
 229 </para>
 230
 231 <!-- ##### ARG GtkEntry:invisible-char ##### -->
 232 <para>
 233
 234 </para>
 235
 236 <!-- ##### ARG GtkEntry:invisible-char-set ##### -->
 237 <para>
 238
 239 </para>
 240
 241 <!-- ##### ARG GtkEntry:max-length ##### -->
 242 <para>
 243
 244 </para>
 245
 246 <!-- ##### ARG GtkEntry:overwrite-mode ##### -->
 247 <para>
 248
 249 </para>
 250
 251 <!-- ##### ARG GtkEntry:pixbuf-primary ##### -->
 252 <para>
 253
 254 </para>
 255
 256 <!-- ##### ARG GtkEntry:pixbuf-secondary ##### -->
 257 <para>
 258
 259 </para>
 260
 261 <!-- ##### ARG GtkEntry:progress-fraction ##### -->
 262 <para>
 263
 264 </para>
 265
 266 <!-- ##### ARG GtkEntry:progress-pulse-step ##### -->
 267 <para>
 268
 269 </para>
 270
 271 <!-- ##### ARG GtkEntry:scroll-offset ##### -->
 272 <para>
 273
 274 </para>
 275
 276 <!-- ##### ARG GtkEntry:selection-bound ##### -->
 277 <para>
 278
 279 </para>
 280
 281 <!-- ##### ARG GtkEntry:sensitive-primary ##### -->
 282 <para>
 283
 284 </para>
 285
 286 <!-- ##### ARG GtkEntry:sensitive-secondary ##### -->
 287 <para>
 288
 289 </para>
 290
 291 <!-- ##### ARG GtkEntry:shadow-type ##### -->
 292 <para>
 293
 294 </para>
 295
 296 <!-- ##### ARG GtkEntry:stock-primary ##### -->
 297 <para>
 298
 299 </para>
 300
 301 <!-- ##### ARG GtkEntry:stock-secondary ##### -->
 302 <para>
 303
 304 </para>
 305
 306 <!-- ##### ARG GtkEntry:storage-type-primary ##### -->
 307 <para>
 308
 309 </para>
 310
 311 <!-- ##### ARG GtkEntry:storage-type-secondary ##### -->
 312 <para>
 313
 314 </para>
 315
 316 <!-- ##### ARG GtkEntry:text ##### -->
 317 <para>
 318
 319 </para>
 320
 321 <!-- ##### ARG GtkEntry:text-length ##### -->
 322 <para>
 323
 324 </para>
 325
 326 <!-- ##### ARG GtkEntry:truncate-multiline ##### -->
 327 <para>
 328
 329 </para>
 330
 331 <!-- ##### ARG GtkEntry:visibility ##### -->
 332 <para>
 333
 334 </para>
 335
 336 <!-- ##### ARG GtkEntry:width-chars ##### -->
 337 <para>
 338
 339 </para>
 340
 341 <!-- ##### ARG GtkEntry:xalign ##### -->
 342 <para>
 343
 344 </para>
 345
 346 <!-- ##### ARG GtkEntry:inner-border ##### -->
 347 <para>
 348
 349 </para>
 350
 351 <!-- ##### ARG GtkEntry:prelight ##### -->
 352 <para>
 353
 354 </para>
 355
 356 <!-- ##### ARG GtkEntry:state-hint ##### -->
 357 <para>
 358
 359 </para>
 360
 361 <!-- ##### FUNCTION gtk_entry_new ##### -->
 362 <para>
 363
 364 </para>
 365
 366 @Returns:
 367
 368
 369 <!-- ##### FUNCTION gtk_entry_new_with_max_length ##### -->
 370 <para>
 371 </para>
 372
 373 @max:
 374 @Returns:
 375
 376
 377 <!-- ##### FUNCTION gtk_entry_set_text ##### -->
 378 <para>
 379
 380 </para>
 381
 382 @entry:
 383 @text:
 384
 385
 386 <!-- ##### FUNCTION gtk_entry_append_text ##### -->
 387 <para>
 388
 389 </para>
 390
 391 @entry:
 392 @text:
 393
 394
 395 <!-- ##### FUNCTION gtk_entry_prepend_text ##### -->
 396 <para>
 397
 398 </para>
 399
 400 @entry:
 401 @text:
 402
 403
 404 <!-- ##### FUNCTION gtk_entry_set_position ##### -->
 405 <para>
 406
 407 </para>
 408
 409 @entry:
 410 @position:
 411
 412
 413 <!-- ##### FUNCTION gtk_entry_get_text ##### -->
 414 <para>
 415
 416 </para>
 417
 418 @entry:
 419 @Returns:
 420
 421
 422 <!-- ##### FUNCTION gtk_entry_get_text_length ##### -->
 423 <para>
 424
 425 </para>
 426
 427 @entry:
 428 @Returns:
 429
 430
 431 <!-- ##### FUNCTION gtk_entry_select_region ##### -->
 432 <para>
 433
 434 </para>
 435
 436 @entry:
 437 @start:
 438 @end:
 439
 440
 441 <!-- ##### FUNCTION gtk_entry_set_visibility ##### -->
 442 <para>
 443
 444 </para>
 445
 446 @entry:
 447 @visible:
 448
 449
 450 <!-- ##### FUNCTION gtk_entry_set_invisible_char ##### -->
 451 <para>
 452
 453 </para>
 454
 455 @entry:
 456 @ch:
 457
 458
 459 <!-- ##### FUNCTION gtk_entry_unset_invisible_char ##### -->
 460 <para>
 461
 462 </para>
 463
 464 @entry:
 465
 466
 467 <!-- ##### FUNCTION gtk_entry_set_editable ##### -->
 468 <para>
 469
 470 </para>
 471
 472 @entry:
 473 @editable:
 474
 475
 476 <!-- ##### FUNCTION gtk_entry_set_max_length ##### -->
 477 <para>
 478 </para>
 479
 480 @entry:
 481 @max:
 482
 483
 484 <!-- ##### FUNCTION gtk_entry_get_activates_default ##### -->
 485 <para>
 486
 487 </para>
 488
 489 @entry:
 490 @Returns:
 491
 492
 493 <!-- ##### FUNCTION gtk_entry_get_has_frame ##### -->
 494 <para>
 495
 496 </para>
 497
 498 @entry:
 499 @Returns:
 500
 501
 502 <!-- ##### FUNCTION gtk_entry_get_inner_border ##### -->
 503 <para>
 504
 505 </para>
 506
 507 @entry:
 508 @Returns:
 509
 510
 511 <!-- ##### FUNCTION gtk_entry_get_width_chars ##### -->
 512 <para>
 513
 514 </para>
 515
 516 @entry:
 517 @Returns:
 518
 519
 520 <!-- ##### FUNCTION gtk_entry_set_activates_default ##### -->
 521 <para>
 522
 523 </para>
 524
 525 @entry:
 526 @setting:
 527
 528
 529 <!-- ##### FUNCTION gtk_entry_set_has_frame ##### -->
 530 <para>
 531
 532 </para>
 533
 534 @entry:
 535 @setting:
 536
 537
 538 <!-- ##### FUNCTION gtk_entry_set_inner_border ##### -->
 539 <para>
 540
 541 </para>
 542
 543 @entry:
 544 @border:
 545
 546
 547 <!-- ##### FUNCTION gtk_entry_set_width_chars ##### -->
 548 <para>
 549
 550 </para>
 551
 552 @entry:
 553 @n_chars:
 554
 555
 556 <!-- ##### FUNCTION gtk_entry_get_invisible_char ##### -->
 557 <para>
 558
 559 </para>
 560
 561 @entry:
 562 @Returns:
 563
 564
 565 <!-- ##### FUNCTION gtk_entry_set_alignment ##### -->
 566 <para>
 567
 568 </para>
 569
 570 @entry:
 571 @xalign:
 572
 573
 574 <!-- ##### FUNCTION gtk_entry_get_alignment ##### -->
 575 <para>
 576
 577 </para>
 578
 579 @entry:
 580 @Returns:
 581
 582
 583 <!-- ##### FUNCTION gtk_entry_set_overwrite_mode ##### -->
 584 <para>
 585
 586 </para>
 587
 588 @entry:
 589 @overwrite:
 590
 591
 592 <!-- ##### FUNCTION gtk_entry_get_overwrite_mode ##### -->
 593 <para>
 594
 595 </para>
 596
 597 @entry:
 598 @Returns:
 599
 600
 601 <!-- ##### FUNCTION gtk_entry_get_layout ##### -->
 602 <para>
 603
 604 </para>
 605
 606 @entry:
 607 @Returns:
 608
 609
 610 <!-- ##### FUNCTION gtk_entry_get_layout_offsets ##### -->
 611 <para>
 612
 613 </para>
 614
 615 @entry:
 616 @x:
 617 @y:
 618
 619
 620 <!-- ##### FUNCTION gtk_entry_layout_index_to_text_index ##### -->
 621 <para>
 622
 623 </para>
 624
 625 @entry:
 626 @layout_index:
 627 @Returns:
 628
 629
 630 <!-- ##### FUNCTION gtk_entry_text_index_to_layout_index ##### -->
 631 <para>
 632
 633 </para>
 634
 635 @entry:
 636 @text_index:
 637 @Returns:
 638
 639
 640 <!-- ##### FUNCTION gtk_entry_get_max_length ##### -->
 641 <para>
 642
 643 </para>
 644
 645 @entry:
 646 @Returns:
 647
 648
 649 <!-- ##### FUNCTION gtk_entry_get_visibility ##### -->
 650 <para>
 651
 652 </para>
 653
 654 @entry:
 655 @Returns:
 656
 657
 658 <!-- ##### FUNCTION gtk_entry_set_completion ##### -->
 659 <para>
 660
 661 </para>
 662
 663 @entry:
 664 @completion:
 665
 666
 667 <!-- ##### FUNCTION gtk_entry_get_completion ##### -->
 668 <para>
 669
 670 </para>
 671
 672 @entry:
 673 @Returns:
 674
 675
 676 <!-- ##### FUNCTION gtk_entry_set_cursor_hadjustment ##### -->
 677 <para>
 678
 679 </para>
 680
 681 @entry:
 682 @adjustment:
 683
 684
 685 <!-- ##### FUNCTION gtk_entry_get_cursor_hadjustment ##### -->
 686 <para>
 687
 688 </para>
 689
 690 @entry:
 691 @Returns:
 692
 693
 694 <!-- ##### FUNCTION gtk_entry_set_progress_fraction ##### -->
 695 <para>
 696
 697 </para>
 698
 699 @entry:
 700 @fraction:
 701
 702
 703 <!-- ##### FUNCTION gtk_entry_get_progress_fraction ##### -->
 704 <para>
 705
 706 </para>
 707
 708 @entry:
 709 @Returns:
 710
 711
 712 <!-- ##### FUNCTION gtk_entry_set_progress_pulse_step ##### -->
 713 <para>
 714
 715 </para>
 716
 717 @entry:
 718 @fraction:
 719
 720
 721 <!-- ##### FUNCTION gtk_entry_get_progress_pulse_step ##### -->
 722 <para>
 723
 724 </para>
 725
 726 @entry:
 727 @Returns:
 728
 729
 730 <!-- ##### FUNCTION gtk_entry_progress_pulse ##### -->
 731 <para>
 732
 733 </para>
 734
 735 @entry:
 736
 737
 738 <!-- ##### ENUM GtkEntryIconPosition ##### -->
 739 <para>
 740 Specifies the side of the entry at which an icon is placed.
 741 </para>
 742
 743 @GTK_ENTRY_ICON_PRIMARY: At the beginning of the entry (depending on the text direction).
 744 @GTK_ENTRY_ICON_SECONDARY: At the end of the entry (depending on the text direction).
 745
 746 <!-- ##### FUNCTION gtk_entry_set_icon_from_pixbuf ##### -->
 747 <para>
 748
 749 </para>
 750
 751 @entry:
 752 @icon_pos:
 753 @pixbuf:
 754
 755
 756 <!-- ##### FUNCTION gtk_entry_set_icon_from_stock ##### -->
 757 <para>
 758
 759 </para>
 760
 761 @entry:
 762 @icon_pos:
 763 @stock_id:
 764
 765
 766 <!-- ##### FUNCTION gtk_entry_set_icon_from_icon_name ##### -->
 767 <para>
 768
 769 </para>
 770
 771 @entry:
 772 @icon_pos:
 773 @icon_name:
 774
 775
 776 <!-- ##### FUNCTION gtk_entry_set_icon_from_gicon ##### -->
 777 <para>
 778
 779 </para>
 780
 781 @entry:
 782 @icon_pos:
 783 @icon:
 784
 785
 786 <!-- ##### FUNCTION gtk_entry_get_storage_type ##### -->
 787 <para>
 788
 789 </para>
 790
 791 @entry:
 792 @icon_pos:
 793 @Returns:
 794
 795
 796 <!-- ##### FUNCTION gtk_entry_get_pixbuf ##### -->
 797 <para>
 798
 799 </para>
 800
 801 @entry:
 802 @icon_pos:
 803 @Returns:
 804
 805
 806 <!-- ##### FUNCTION gtk_entry_get_stock ##### -->
 807 <para>
 808
 809 </para>
 810
 811 @entry:
 812 @icon_pos:
 813 @Returns:
 814
 815
 816 <!-- ##### FUNCTION gtk_entry_get_icon_name ##### -->
 817 <para>
 818
 819 </para>
 820
 821 @entry:
 822 @icon_pos:
 823 @Returns:
 824
 825
 826 <!-- ##### FUNCTION gtk_entry_get_gicon ##### -->
 827 <para>
 828
 829 </para>
 830
 831 @entry:
 832 @icon_pos:
 833 @Returns:
 834
 835
 836 <!-- ##### FUNCTION gtk_entry_set_icon_activatable ##### -->
 837 <para>
 838
 839 </para>
 840
 841 @entry:
 842 @icon_pos:
 843 @activatable:
 844
 845
 846 <!-- ##### FUNCTION gtk_entry_get_icon_activatable ##### -->
 847 <para>
 848
 849 </para>
 850
 851 @entry:
 852 @icon_pos:
 853 @Returns:
 854
 855
 856 <!-- ##### FUNCTION gtk_entry_set_icon_sensitive ##### -->
 857 <para>
 858
 859 </para>
 860
 861 @entry:
 862 @icon_pos:
 863 @sensitive:
 864
 865
 866 <!-- ##### FUNCTION gtk_entry_get_icon_sensitive ##### -->
 867 <para>
 868
 869 </para>
 870
 871 @entry:
 872 @icon_pos:
 873 @Returns:
 874
 875
 876 <!-- ##### FUNCTION gtk_entry_get_icon_at_pos ##### -->
 877 <para>
 878
 879 </para>
 880
 881 @entry:
 882 @x:
 883 @y:
 884 @Returns:
 885
 886
 887 <!-- ##### FUNCTION gtk_entry_set_icon_tooltip_text ##### -->
 888 <para>
 889
 890 </para>
 891
 892 @entry:
 893 @icon_pos:
 894 @tooltip:
 895
 896
 897 <!-- ##### FUNCTION gtk_entry_set_icon_tooltip_markup ##### -->
 898 <para>
 899
 900 </para>
 901
 902 @entry:
 903 @icon_pos:
 904 @tooltip:
 905
 906
 907 <!-- ##### FUNCTION gtk_entry_set_icon_drag_source ##### -->
 908 <para>
 909
 910 </para>
 911
 912 @entry:
 913 @icon_pos:
 914 @target_list:
 915 @actions:
 916
 917
 918 <!-- ##### FUNCTION gtk_entry_get_current_icon_drag_source ##### -->
 919 <para>
 920
 921 </para>
 922
 923 @entry:
 924 @Returns:
 925
 926