Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkentrycompletion.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkEntryCompletion
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Completion functionality for GtkEntry
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 #GtkEntryCompletion is an auxiliary object to be used in conjunction with
  10 #GtkEntry to provide the completion functionality. It implements the
  11 #GtkCellLayout interface, to allow the user to add extra cells to the
  12 #GtkTreeView with completion matches.
  13 </para>
  14 <para>
  15 "Completion functionality" means that when the user modifies the text
  16 in the entry, #GtkEntryCompletion checks which rows in the model match
  17 the current content of the entry, and displays a list of matches.
  18 By default, the matching is done by comparing the entry text
  19 case-insensitively against the text column of the model (see
  20 gtk_entry_completion_set_text_column()), but this can be overridden with
  21 a custom match function (see gtk_entry_completion_set_match_func()).
  22 </para>
  23 <para>
  24 When the user selects a completion, the content of the entry is updated.
  25 By default, the content of the entry is replaced by the text column of the
  26 model, but this can be overridden by connecting to the ::match-selected signal
  27 and updating the entry in the signal handler. Note that you should return
  28 %TRUE from the signal handler to suppress the default behaviour.
  29 </para>
  30 <para>
  31 To add completion functionality to an entry, use gtk_entry_set_completion().
  32 </para>
  33 <para>
  34 In addition to regular completion matches, which will be inserted into the
  35 entry when they are selected, #GtkEntryCompletion also allows to display
  36 "actions" in the popup window. Their appearance is similar to menuitems,
  37 to differentiate them clearly from completion strings. When an action is
  38 selected, the ::action-activated signal is emitted.
  39 </para>
  40
  41 <!-- ##### SECTION See_Also ##### -->
  42 <para>
  43
  44 </para>
  45
  46 <!-- ##### SECTION Stability_Level ##### -->
  47
  48
  49 <!-- ##### SECTION Image ##### -->
  50
  51
  52 <!-- ##### STRUCT GtkEntryCompletion ##### -->
  53 <para>
  54 The GtkEntryCompletion struct contains only private data.
  55 </para>
  56
  57
  58 <!-- ##### SIGNAL GtkEntryCompletion::action-activated ##### -->
  59 <para>
  60
  61 </para>
  62
  63 @entrycompletion: the object which received the signal.
  64 @arg1:
  65
  66 <!-- ##### SIGNAL GtkEntryCompletion::cursor-on-match ##### -->
  67 <para>
  68
  69 </para>
  70
  71 @entrycompletion: the object which received the signal.
  72 @arg1:
  73 @arg2:
  74 @Returns:
  75
  76 <!-- ##### SIGNAL GtkEntryCompletion::insert-prefix ##### -->
  77 <para>
  78
  79 </para>
  80
  81 @entrycompletion: the object which received the signal.
  82 @arg1:
  83 @Returns:
  84
  85 <!-- ##### SIGNAL GtkEntryCompletion::match-selected ##### -->
  86 <para>
  87
  88 </para>
  89
  90 @entrycompletion: the object which received the signal.
  91 @arg1:
  92 @arg2:
  93 @Returns:
  94
  95 <!-- ##### ARG GtkEntryCompletion:inline-completion ##### -->
  96 <para>
  97
  98 </para>
  99
 100 <!-- ##### ARG GtkEntryCompletion:inline-selection ##### -->
 101 <para>
 102
 103 </para>
 104
 105 <!-- ##### ARG GtkEntryCompletion:minimum-key-length ##### -->
 106 <para>
 107
 108 </para>
 109
 110 <!-- ##### ARG GtkEntryCompletion:model ##### -->
 111 <para>
 112
 113 </para>
 114
 115 <!-- ##### ARG GtkEntryCompletion:popup-completion ##### -->
 116 <para>
 117
 118 </para>
 119
 120 <!-- ##### ARG GtkEntryCompletion:popup-set-width ##### -->
 121 <para>
 122
 123 </para>
 124
 125 <!-- ##### ARG GtkEntryCompletion:popup-single-match ##### -->
 126 <para>
 127
 128 </para>
 129
 130 <!-- ##### ARG GtkEntryCompletion:text-column ##### -->
 131 <para>
 132
 133 </para>
 134
 135 <!-- ##### USER_FUNCTION GtkEntryCompletionMatchFunc ##### -->
 136 <para>
 137 A function which decides whether the row indicated by @iter matches a given
 138 @key, and should be displayed as a possible completion for @key. Note that
 139 @key is normalized and case-folded (see g_utf8_normalize() and
 140 g_utf8_casefold()). If this is not appropriate, match functions have access
 141 to the unmodified key via <literal>gtk_entry_get_text (GTK_ENTRY (gtk_entry_completion_get_entry (<!-- -->)))</literal>.
 142 </para>
 143
 144 @completion: the #GtkEntryCompletion
 145 @key: the string to match, normalized and case-folded
 146 @iter: a #GtkTreeIter indicating the row to match
 147 @user_data: user data given to gtk_entry_completion_set_match_func()
 148 @Returns: %TRUE if @iter should be displayed as a possible completion for @key
 149
 150
 151 <!-- ##### FUNCTION gtk_entry_completion_new ##### -->
 152 <para>
 153
 154 </para>
 155
 156 @void:
 157 @Returns:
 158
 159
 160 <!-- ##### FUNCTION gtk_entry_completion_get_entry ##### -->
 161 <para>
 162
 163 </para>
 164
 165 @completion:
 166 @Returns:
 167
 168
 169 <!-- ##### FUNCTION gtk_entry_completion_set_model ##### -->
 170 <para>
 171
 172 </para>
 173
 174 @completion:
 175 @model:
 176
 177
 178 <!-- ##### FUNCTION gtk_entry_completion_get_model ##### -->
 179 <para>
 180
 181 </para>
 182
 183 @completion:
 184 @Returns:
 185
 186
 187 <!-- ##### FUNCTION gtk_entry_completion_set_match_func ##### -->
 188 <para>
 189
 190 </para>
 191
 192 @completion:
 193 @func:
 194 @func_data:
 195 @func_notify:
 196
 197
 198 <!-- ##### FUNCTION gtk_entry_completion_set_minimum_key_length ##### -->
 199 <para>
 200
 201 </para>
 202
 203 @completion:
 204 @length:
 205
 206
 207 <!-- ##### FUNCTION gtk_entry_completion_get_minimum_key_length ##### -->
 208 <para>
 209
 210 </para>
 211
 212 @completion:
 213 @Returns:
 214
 215
 216 <!-- ##### FUNCTION gtk_entry_completion_complete ##### -->
 217 <para>
 218
 219 </para>
 220
 221 @completion:
 222
 223
 224 <!-- ##### FUNCTION gtk_entry_completion_get_completion_prefix ##### -->
 225 <para>
 226
 227 </para>
 228
 229 @completion:
 230 @Returns:
 231
 232
 233 <!-- ##### FUNCTION gtk_entry_completion_insert_prefix ##### -->
 234 <para>
 235
 236 </para>
 237
 238 @completion:
 239
 240
 241 <!-- ##### FUNCTION gtk_entry_completion_insert_action_text ##### -->
 242 <para>
 243
 244 </para>
 245
 246 @completion:
 247 @index_:
 248 @text:
 249
 250
 251 <!-- ##### FUNCTION gtk_entry_completion_insert_action_markup ##### -->
 252 <para>
 253
 254 </para>
 255
 256 @completion:
 257 @index_:
 258 @markup:
 259
 260
 261 <!-- ##### FUNCTION gtk_entry_completion_delete_action ##### -->
 262 <para>
 263
 264 </para>
 265
 266 @completion:
 267 @index_:
 268
 269
 270 <!-- ##### FUNCTION gtk_entry_completion_set_text_column ##### -->
 271 <para>
 272
 273 </para>
 274
 275 @completion:
 276 @column:
 277
 278
 279 <!-- ##### FUNCTION gtk_entry_completion_get_text_column ##### -->
 280 <para>
 281
 282 </para>
 283
 284 @completion:
 285 @Returns:
 286
 287
 288 <!-- ##### FUNCTION gtk_entry_completion_set_inline_completion ##### -->
 289 <para>
 290
 291 </para>
 292
 293 @completion:
 294 @inline_completion:
 295
 296
 297 <!-- ##### FUNCTION gtk_entry_completion_get_inline_completion ##### -->
 298 <para>
 299
 300 </para>
 301
 302 @completion:
 303 @Returns:
 304
 305
 306 <!-- ##### FUNCTION gtk_entry_completion_set_inline_selection ##### -->
 307 <para>
 308
 309 </para>
 310
 311 @completion:
 312 @inline_selection:
 313
 314
 315 <!-- ##### FUNCTION gtk_entry_completion_get_inline_selection ##### -->
 316 <para>
 317
 318 </para>
 319
 320 @completion:
 321 @Returns:
 322
 323
 324 <!-- ##### FUNCTION gtk_entry_completion_set_popup_completion ##### -->
 325 <para>
 326
 327 </para>
 328
 329 @completion:
 330 @popup_completion:
 331
 332
 333 <!-- ##### FUNCTION gtk_entry_completion_get_popup_completion ##### -->
 334 <para>
 335
 336 </para>
 337
 338 @completion:
 339 @Returns:
 340
 341
 342 <!-- ##### FUNCTION gtk_entry_completion_set_popup_set_width ##### -->
 343 <para>
 344
 345 </para>
 346
 347 @completion:
 348 @popup_set_width:
 349
 350
 351 <!-- ##### FUNCTION gtk_entry_completion_get_popup_set_width ##### -->
 352 <para>
 353
 354 </para>
 355
 356 @completion:
 357 @Returns:
 358
 359
 360 <!-- ##### FUNCTION gtk_entry_completion_set_popup_single_match ##### -->
 361 <para>
 362
 363 </para>
 364
 365 @completion:
 366 @popup_single_match:
 367
 368
 369 <!-- ##### FUNCTION gtk_entry_completion_get_popup_single_match ##### -->
 370 <para>
 371
 372 </para>
 373
 374 @completion:
 375 @Returns:
 376
 377