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 <!-- ##### STRUCT GtkEntryCompletion ##### -->
  50 <para>
  51 The GtkEntryCompletion struct contains only private data.
  52 </para>
  53
  54
  55 <!-- ##### SIGNAL GtkEntryCompletion::action-activated ##### -->
  56 <para>
  57
  58 </para>
  59
  60 @entrycompletion: the object which received the signal.
  61 @arg1:
  62
  63 <!-- ##### SIGNAL GtkEntryCompletion::insert-prefix ##### -->
  64 <para>
  65
  66 </para>
  67
  68 @entrycompletion: the object which received the signal.
  69 @arg1:
  70 @Returns:
  71
  72 <!-- ##### SIGNAL GtkEntryCompletion::match-selected ##### -->
  73 <para>
  74
  75 </para>
  76
  77 @entrycompletion: the object which received the signal.
  78 @arg1:
  79 @arg2:
  80 @Returns:
  81
  82 <!-- ##### ARG GtkEntryCompletion:inline-completion ##### -->
  83 <para>
  84
  85 </para>
  86
  87 <!-- ##### ARG GtkEntryCompletion:minimum-key-length ##### -->
  88 <para>
  89
  90 </para>
  91
  92 <!-- ##### ARG GtkEntryCompletion:model ##### -->
  93 <para>
  94
  95 </para>
  96
  97 <!-- ##### ARG GtkEntryCompletion:popup-completion ##### -->
  98 <para>
  99
 100 </para>
 101
 102 <!-- ##### ARG GtkEntryCompletion:popup-set-width ##### -->
 103 <para>
 104
 105 </para>
 106
 107 <!-- ##### ARG GtkEntryCompletion:popup-single-match ##### -->
 108 <para>
 109
 110 </para>
 111
 112 <!-- ##### ARG GtkEntryCompletion:text-column ##### -->
 113 <para>
 114
 115 </para>
 116
 117 <!-- ##### USER_FUNCTION GtkEntryCompletionMatchFunc ##### -->
 118 <para>
 119 A function which decides whether the row indicated by @iter matches a given
 120 @key, and should be displayed as a possible completion for @key. Note that
 121 @key is normalized and case-folded (see g_utf8_normalize() and
 122 g_utf8_casefold()). If this is not appropriate, match functions have access
 123 to the unmodified key via <literal>gtk_entry_get_text (GTK_ENTRY (gtk_entry_completion_get_entry (<!-- -->)))</literal>.
 124 </para>
 125
 126 @completion: the #GtkEntryCompletion
 127 @key: the string to match, normalized and case-folded
 128 @iter: a #GtkTreeIter indicating the row to match
 129 @user_data: user data given to gtk_entry_completion_set_match_func()
 130 @Returns: %TRUE if @iter should be displayed as a possible completion for @key
 131
 132
 133 <!-- ##### FUNCTION gtk_entry_completion_new ##### -->
 134 <para>
 135
 136 </para>
 137
 138 @Returns:
 139
 140
 141 <!-- ##### FUNCTION gtk_entry_completion_get_entry ##### -->
 142 <para>
 143
 144 </para>
 145
 146 @completion:
 147 @Returns:
 148
 149
 150 <!-- ##### FUNCTION gtk_entry_completion_set_model ##### -->
 151 <para>
 152
 153 </para>
 154
 155 @completion:
 156 @model:
 157
 158
 159 <!-- ##### FUNCTION gtk_entry_completion_get_model ##### -->
 160 <para>
 161
 162 </para>
 163
 164 @completion:
 165 @Returns:
 166
 167
 168 <!-- ##### FUNCTION gtk_entry_completion_set_match_func ##### -->
 169 <para>
 170
 171 </para>
 172
 173 @completion:
 174 @func:
 175 @func_data:
 176 @func_notify:
 177
 178
 179 <!-- ##### FUNCTION gtk_entry_completion_set_minimum_key_length ##### -->
 180 <para>
 181
 182 </para>
 183
 184 @completion:
 185 @length:
 186
 187
 188 <!-- ##### FUNCTION gtk_entry_completion_get_minimum_key_length ##### -->
 189 <para>
 190
 191 </para>
 192
 193 @completion:
 194 @Returns:
 195
 196
 197 <!-- ##### FUNCTION gtk_entry_completion_complete ##### -->
 198 <para>
 199
 200 </para>
 201
 202 @completion:
 203
 204
 205 <!-- ##### FUNCTION gtk_entry_completion_insert_prefix ##### -->
 206 <para>
 207
 208 </para>
 209
 210 @completion:
 211
 212
 213 <!-- ##### FUNCTION gtk_entry_completion_insert_action_text ##### -->
 214 <para>
 215
 216 </para>
 217
 218 @completion:
 219 @index_:
 220 @text:
 221
 222
 223 <!-- ##### FUNCTION gtk_entry_completion_insert_action_markup ##### -->
 224 <para>
 225
 226 </para>
 227
 228 @completion:
 229 @index_:
 230 @markup:
 231
 232
 233 <!-- ##### FUNCTION gtk_entry_completion_delete_action ##### -->
 234 <para>
 235
 236 </para>
 237
 238 @completion:
 239 @index_:
 240
 241
 242 <!-- ##### FUNCTION gtk_entry_completion_set_text_column ##### -->
 243 <para>
 244
 245 </para>
 246
 247 @completion:
 248 @column:
 249
 250
 251 <!-- ##### FUNCTION gtk_entry_completion_get_text_column ##### -->
 252 <para>
 253
 254 </para>
 255
 256 @completion:
 257 @Returns:
 258
 259
 260 <!-- ##### FUNCTION gtk_entry_completion_set_inline_completion ##### -->
 261 <para>
 262
 263 </para>
 264
 265 @completion:
 266 @inline_completion:
 267
 268
 269 <!-- ##### FUNCTION gtk_entry_completion_get_inline_completion ##### -->
 270 <para>
 271
 272 </para>
 273
 274 @completion:
 275 @Returns:
 276
 277
 278 <!-- ##### FUNCTION gtk_entry_completion_set_popup_completion ##### -->
 279 <para>
 280
 281 </para>
 282
 283 @completion:
 284 @popup_completion:
 285
 286
 287 <!-- ##### FUNCTION gtk_entry_completion_get_popup_completion ##### -->
 288 <para>
 289
 290 </para>
 291
 292 @completion:
 293 @Returns:
 294
 295
 296 <!-- ##### FUNCTION gtk_entry_completion_set_popup_set_width ##### -->
 297 <para>
 298
 299 </para>
 300
 301 @completion:
 302 @popup_set_width:
 303
 304
 305 <!-- ##### FUNCTION gtk_entry_completion_get_popup_set_width ##### -->
 306 <para>
 307
 308 </para>
 309
 310 @completion:
 311 @Returns:
 312
 313
 314 <!-- ##### FUNCTION gtk_entry_completion_set_popup_single_match ##### -->
 315 <para>
 316
 317 </para>
 318
 319 @completion:
 320 @popup_single_match:
 321
 322
 323 <!-- ##### FUNCTION gtk_entry_completion_get_popup_single_match ##### -->
 324 <para>
 325
 326 </para>
 327
 328 @completion:
 329 @Returns:
 330
 331