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
  16 <!-- ##### SECTION See_Also ##### -->
  17 <para>
  18 <variablelist>
  19
  20 <varlistentry>
  21 <term>#GtkText</term>
  22 <listitem><para>a widget for handling multi-line text entry.</para></listitem>
  23 </varlistentry>
  24
  25 </variablelist>
  26 </para>
  27
  28 <!-- ##### STRUCT GtkEntry ##### -->
  29 <para>
  30 The #GtkEntry-struct struct contains only private data.
  31 </para>
  32
  33 @editable:
  34 @text_area:
  35 @backing_pixmap:
  36 @cursor:
  37 @text:
  38 @text_size:
  39 @text_length:
  40 @text_max_length:
  41 @scroll_offset:
  42 @visible:
  43 @timer:
  44 @button:
  45 @char_offset:
  46 @text_mb:
  47 @text_mb_dirty:
  48 @use_wchar:
  49
  50 <!-- ##### FUNCTION gtk_entry_new ##### -->
  51 <para>
  52 Creates a new #GtkEntry widget.
  53 </para>
  54
  55 @Returns: a new #GtkEntry.
  56
  57
  58 <!-- ##### FUNCTION gtk_entry_new_with_max_length ##### -->
  59 <para>
  60 Creates a new #GtkEntry widget with the given maximum
  61 length.
  62 </para>
  63 <para>
  64 Note: the existance of this function is inconsistent
  65 with the rest of the GTK+ API. The normal setup would
  66 be to just require the user to make an extra call
  67 to gtk_entry_set_max_length() instead. It is not
  68 expected that this function will be removed, but
  69 it would be better practice not to use it.
  70 </para>
  71
  72 @max: the new maximum length.
  73 @Returns: a new #GtkEntry.
  74
  75
  76 <!-- ##### FUNCTION gtk_entry_set_text ##### -->
  77 <para>
  78 Sets the text in the widget to the given
  79 value, replacing the current contents.
  80 </para>
  81
  82 @entry: a #GtkEntry.
  83 @text: the new text.
  84
  85
  86 <!-- ##### FUNCTION gtk_entry_append_text ##### -->
  87 <para>
  88 Appends the given text to the contents of the widget.
  89 </para>
  90
  91 @entry: a #GtkEntry.
  92 @text: the text to append.
  93
  94
  95 <!-- ##### FUNCTION gtk_entry_prepend_text ##### -->
  96 <para>
  97 Prepends the given text to the contents of th ewidget.
  98 </para>
  99
 100 @entry: a #GtkEntry.
 101 @text: the text to prepend.
 102
 103
 104 <!-- ##### FUNCTION gtk_entry_set_position ##### -->
 105 <para>
 106 Sets the cursor position in an entry to the given
 107 value. This function is obsolete. You should use
 108 gtk_editable_set_position() instead.
 109 </para>
 110
 111 @entry: a #GtkEntry.
 112 @position: the position of the cursor. The cursor is displayed
 113            before the character with the given (base 0) index
 114            in the widget. The value must be less than or
 115            equal to the number of characters in the widget.
 116            A value of -1 indicates that the position should
 117            be set after the last character in the entry.
 118            Note that this position is in characters, not in
 119            bytes.
 120
 121
 122 <!-- ##### FUNCTION gtk_entry_get_text ##### -->
 123 <para>
 124 Retrieve the contents of the entry widget. The returned
 125 pointer points to internally allocated storage in the
 126 widget and must not be freed, modified or stored. For
 127 this reason, this function is deprecated. Use
 128 gtk_editable_get_chars() instead.
 129 </para>
 130
 131 @entry: a #GtkEntry.
 132 @Returns: the pointer the the contents of the text widget as a
 133           string.
 134
 135
 136 <!-- ##### FUNCTION gtk_entry_select_region ##### -->
 137 <para>
 138 Selects a region of text. The characters that
 139 are selected are those characters at positions from
 140 @start_pos up to, but not including @end_pos. If
 141 @end_pos is negative, then the the characters selected
 142 will be those characters from @start_pos to the end
 143 of the text. This function is obsolete. You should
 144 use gtk_editable_select_region() instead.
 145 </para>
 146
 147 @entry: a #GtkEntry.
 148 @start: the starting position.
 149 @end: the end position.
 150
 151
 152 <!-- ##### FUNCTION gtk_entry_set_visibility ##### -->
 153 <para>
 154 Sets whether the contents of the entry are visible or
 155 not. When visibility is set to %FALSE, characters
 156 are displayed as asterisks (*'s), and will also appear
 157 that way when the text in the entry widget is copied
 158 elsewhere.
 159 </para>
 160
 161 @entry: a #GtkEntry.
 162 @visible: %TRUE if the contents of the entry are displayd
 163           as plaintext.
 164
 165
 166 <!-- ##### FUNCTION gtk_entry_set_editable ##### -->
 167 <para>
 168 Determines if the user can edit the text in the editable
 169 widget or not. This function is obsolete. You should
 170 use gtk_editable_set_editable() instead.
 171 </para>
 172
 173 @entry: a #GtkEntry.
 174 @editable: %TRUE if the user is allowed to edit the text
 175   in the widget.
 176
 177
 178 <!-- ##### FUNCTION gtk_entry_set_max_length ##### -->
 179 <para>
 180 Sets the maximum allowed length of the contents
 181 of the widget. If the current contents are longer
 182 than the given length, then they will be truncated
 183 to fit.
 184 </para>
 185
 186 @entry: a #GtkEntry.
 187 @max: the new maximum length.
 188
 189
 190 <!-- ##### ARG GtkEntry:max_length ##### -->
 191 <para>
 192 Determines the maximum allowed length of the contents
 193 of the widget. See gtk_entry_set_max_length().
 194 </para>
 195
 196 <!-- ##### ARG GtkEntry:visibility ##### -->
 197 <para>
 198 Determines whether the contents of the entry widget
 199 are visible or not. See gtk_entry_set_visibility().
 200 </para>
 201