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
  34 <!-- ##### FUNCTION gtk_entry_new ##### -->
  35 <para>
  36 Creates a new #GtkEntry widget.
  37 </para>
  38
  39 @Returns: a new #GtkEntry.
  40
  41
  42 <!-- ##### FUNCTION gtk_entry_new_with_max_length ##### -->
  43 <para>
  44 </para>
  45
  46 @max:
  47 @Returns:
  48
  49
  50 <!-- ##### FUNCTION gtk_entry_set_text ##### -->
  51 <para>
  52 Sets the text in the widget to the given
  53 value, replacing the current contents.
  54 </para>
  55
  56 @entry: a #GtkEntry.
  57 @text: the new text.
  58
  59
  60 <!-- ##### FUNCTION gtk_entry_append_text ##### -->
  61 <para>
  62 Appends the given text to the contents of the widget.
  63 </para>
  64
  65 @entry: a #GtkEntry.
  66 @text: the text to append.
  67
  68
  69 <!-- ##### FUNCTION gtk_entry_prepend_text ##### -->
  70 <para>
  71 Prepends the given text to the contents of th ewidget.
  72 </para>
  73
  74 @entry: a #GtkEntry.
  75 @text: the text to prepend.
  76
  77
  78 <!-- ##### FUNCTION gtk_entry_set_position ##### -->
  79 <para>
  80 Sets the cursor position in an entry to the given
  81 value. This function is obsolete. You should use
  82 gtk_editable_set_position() instead.
  83 </para>
  84
  85 @entry: a #GtkEntry.
  86 @position: the position of the cursor. The cursor is displayed
  87            before the character with the given (base 0) index
  88            in the widget. The value must be less than or
  89            equal to the number of characters in the widget.
  90            A value of -1 indicates that the position should
  91            be set after the last character in the entry.
  92            Note that this position is in characters, not in
  93            bytes.
  94
  95
  96 <!-- ##### FUNCTION gtk_entry_get_text ##### -->
  97 <para>
  98 Retrieve the contents of the entry widget. The returned
  99 pointer points to internally allocated storage in the
 100 widget and must not be freed, modified or stored.
 101 See also gtk_editable_get_chars().
 102 </para>
 103
 104 @entry: a #GtkEntry.
 105 @Returns: the pointer the the contents of the text widget as a
 106           string.
 107
 108
 109 <!-- ##### FUNCTION gtk_entry_select_region ##### -->
 110 <para>
 111 Selects a region of text. The characters that
 112 are selected are those characters at positions from
 113 @start_pos up to, but not including @end_pos. If
 114 @end_pos is negative, then the the characters selected
 115 will be those characters from @start_pos to the end
 116 of the text. This function is obsolete. You should
 117 use gtk_editable_select_region() instead.
 118 </para>
 119
 120 @entry: a #GtkEntry.
 121 @start: the starting position.
 122 @end: the end position.
 123
 124
 125 <!-- ##### FUNCTION gtk_entry_set_visibility ##### -->
 126 <para>
 127 Sets whether the contents of the entry are visible or
 128 not. When visibility is set to %FALSE, characters
 129 are displayed as the invisible char, and will also appear
 130 that way when the text in the entry widget is copied
 131 elsewhere.
 132 </para>
 133 <para>
 134 The default invisible char is the asterisk '*', but it can
 135 be changed with gtk_entry_set_invisible_char().
 136 </para>
 137
 138 @entry: a #GtkEntry.
 139 @visible: %TRUE if the contents of the entry are displayed
 140           as plaintext.
 141
 142
 143 <!-- ##### FUNCTION gtk_entry_set_invisible_char ##### -->
 144 <para>
 145
 146 </para>
 147
 148 @entry:
 149 @ch:
 150
 151
 152 <!-- ##### FUNCTION gtk_entry_set_editable ##### -->
 153 <para>
 154 Determines if the user can edit the text in the editable
 155 widget or not. This function is obsolete. You should
 156 use gtk_editable_set_editable() instead.
 157 </para>
 158
 159 @entry: a #GtkEntry.
 160 @editable: %TRUE if the user is allowed to edit the text
 161   in the widget.
 162
 163
 164 <!-- ##### FUNCTION gtk_entry_set_max_length ##### -->
 165 <para>
 166 </para>
 167
 168 @entry:
 169 @max:
 170
 171
 172 <!-- ##### FUNCTION gtk_entry_get_activates_default ##### -->
 173 <para>
 174
 175 </para>
 176
 177 @entry:
 178 @Returns:
 179
 180
 181 <!-- ##### FUNCTION gtk_entry_get_has_frame ##### -->
 182 <para>
 183
 184 </para>
 185
 186 @entry:
 187 @Returns:
 188
 189
 190 <!-- ##### FUNCTION gtk_entry_get_width_chars ##### -->
 191 <para>
 192
 193 </para>
 194
 195 @entry:
 196 @Returns:
 197
 198
 199 <!-- ##### FUNCTION gtk_entry_set_activates_default ##### -->
 200 <para>
 201
 202 </para>
 203
 204 @entry:
 205 @setting:
 206
 207
 208 <!-- ##### FUNCTION gtk_entry_set_has_frame ##### -->
 209 <para>
 210
 211 </para>
 212
 213 @entry:
 214 @setting:
 215
 216
 217 <!-- ##### FUNCTION gtk_entry_set_width_chars ##### -->
 218 <para>
 219
 220 </para>
 221
 222 @entry:
 223 @n_chars:
 224
 225
 226 <!-- ##### FUNCTION gtk_entry_get_invisible_char ##### -->
 227 <para>
 228
 229 </para>
 230
 231 @entry:
 232 @Returns:
 233
 234
 235 <!-- ##### FUNCTION gtk_entry_get_layout ##### -->
 236 <para>
 237
 238 </para>
 239
 240 @entry:
 241 @Returns:
 242
 243
 244 <!-- ##### FUNCTION gtk_entry_get_layout_offsets ##### -->
 245 <para>
 246
 247 </para>
 248
 249 @entry:
 250 @x:
 251 @y:
 252
 253
 254 <!-- ##### FUNCTION gtk_entry_get_max_length ##### -->
 255 <para>
 256
 257 </para>
 258
 259 @entry:
 260 @Returns:
 261
 262
 263 <!-- ##### FUNCTION gtk_entry_get_visibility ##### -->
 264 <para>
 265
 266 </para>
 267
 268 @entry:
 269 @Returns:
 270
 271
 272 <!-- ##### SIGNAL GtkEntry::activate ##### -->
 273 <para>
 274
 275 </para>
 276
 277 @entry: the object which received the signal.
 278
 279 <!-- ##### SIGNAL GtkEntry::copy-clipboard ##### -->
 280 <para>
 281
 282 </para>
 283
 284 @entry: the object which received the signal.
 285
 286 <!-- ##### SIGNAL GtkEntry::cut-clipboard ##### -->
 287 <para>
 288
 289 </para>
 290
 291 @entry: the object which received the signal.
 292
 293 <!-- ##### SIGNAL GtkEntry::delete-from-cursor ##### -->
 294 <para>
 295
 296 </para>
 297
 298 @entry: the object which received the signal.
 299 @arg1:
 300 @arg2:
 301
 302 <!-- ##### SIGNAL GtkEntry::insert-at-cursor ##### -->
 303 <para>
 304
 305 </para>
 306
 307 @entry: the object which received the signal.
 308 @arg1:
 309
 310 <!-- ##### SIGNAL GtkEntry::move-cursor ##### -->
 311 <para>
 312
 313 </para>
 314
 315 @entry: the object which received the signal.
 316 @arg1:
 317 @arg2:
 318 @arg3:
 319
 320 <!-- ##### SIGNAL GtkEntry::paste-clipboard ##### -->
 321 <para>
 322
 323 </para>
 324
 325 @entry: the object which received the signal.
 326
 327 <!-- ##### SIGNAL GtkEntry::populate-popup ##### -->
 328 <para>
 329
 330 </para>
 331
 332 @entry: the object which received the signal.
 333 @arg1:
 334
 335 <!-- ##### SIGNAL GtkEntry::toggle-overwrite ##### -->
 336 <para>
 337
 338 </para>
 339
 340 @entry: the object which received the signal.
 341
 342 <!-- ##### ARG GtkEntry:cursor-position ##### -->
 343 <para>
 344
 345 </para>
 346
 347 <!-- ##### ARG GtkEntry:selection-bound ##### -->
 348 <para>
 349
 350 </para>
 351
 352 <!-- ##### ARG GtkEntry:editable ##### -->
 353 <para>
 354
 355 </para>
 356
 357 <!-- ##### ARG GtkEntry:max-length ##### -->
 358 <para>
 359 Determines the maximum allowed length of the contents
 360 of the widget. See gtk_entry_set_max_length().
 361 </para>
 362
 363 <!-- ##### ARG GtkEntry:visibility ##### -->
 364 <para>
 365 Determines whether the contents of the entry widget
 366 are visible or not. See gtk_entry_set_visibility().
 367 </para>
 368
 369 <!-- ##### ARG GtkEntry:has-frame ##### -->
 370 <para>
 371
 372 </para>
 373
 374 <!-- ##### ARG GtkEntry:invisible-char ##### -->
 375 <para>
 376
 377 </para>
 378
 379 <!-- ##### ARG GtkEntry:activates-default ##### -->
 380 <para>
 381
 382 </para>
 383
 384 <!-- ##### ARG GtkEntry:width-chars ##### -->
 385 <para>
 386
 387 </para>
 388
 389 <!-- ##### ARG GtkEntry:scroll-offset ##### -->
 390 <para>
 391
 392 </para>
 393
 394 <!-- ##### ARG GtkEntry:text ##### -->
 395 <para>
 396
 397 </para>
 398