gtk.EntryCompletion
Prev | The gtk Class Reference | Next

## gtk.EntryCompletion

gtk.EntryCompletion — completion functionality for `gtk.Entry` (new in PyGTK 2.4)

## Synopsis

    class gtk.EntryCompletion(gobject.GObject, gtk.CellLayout):
        gtk.EntryCompletion()
        def get_entry()
        def set_model(model=None)
        def get_model()
        def set_match_func(func, func_data)
        def set_minimum_key_length(length)
        def get_minimum_key_length()
        def complete()
        def insert_action_text(index, text)
        def insert_action_markup(index, markup)
        def delete_action(index)
        def insert_prefix()
        def set_text_column(column)
        def get_text_column()
        def set_inline_completion(inline_completion)
        def get_inline_completion()
        def set_inline_selection(inline_selection)
        def get_inline_selection()
        def set_popup_completion(popup_completion)
        def get_popup_completion()
        def set_popup_set_width(popup_set_width)
        def get_popup_set_width()
        def set_popup_single_match(popup_single_match)
        def get_popup_single_match()
        def get_completion_prefix()

## Ancestry

    +-- gobject.GObject
      +-- gtk.EntryCompletion

## Implemented Interfaces

`gtk.EntryCompletion` implements `gtk.Buildable` `gtk.CellLayout`

## gtk.EntryCompletion Properties

"inline-completion" | Read-Write | If `True` the common prefix should be inserted automatically. Default value: `False`. Available in GTK+ 2.6 and above.
"inline-selection" | Read-Write | Determines whether the possible completions on the popup will appear in the entry as you navigate through them. Default value: `False`. Available in GTK+ 2.12 and above.
"minimum-key-length" | Read-Write | Minimum length of the search key in order to look up matches. Allowed values >= 0. Default value: 1
"model" | Read-Write | The `gtk.TreeModel` to find matches in.
"popup-completion" | Read-Write | If `True` the completions should be shown in a popup window. Default value: `True`. Available in GTK+ 2.6 and above.
"popup-set-width" | Read-Write | If `True` the completions popup window will be resized to the width of the entry. Default value: `True`. Available in GTK+ 2.8 and above.
"popup-single-match" | Read-Write | If `True` the completions popup window will be for a single possible completion. Default value: `True`. Available in GTK+ 2.8 and above.
"text-column" | Read-Write | The column of the model containing the strings. Allowed values: >= -1. Default value: -1. Available in GTK+ 2.6 and above.

## gtk.EntryCompletion Signal Prototypes

gobject.GObject Signal Prototypes

"action-activated" | `def callback(`completion`, `index`, `user_param1`, `...`)`
"cursor-on-match" | `def callback(`completion`, `model`, `iter`, `user_param1`, `...`)`
"insert-prefix" | `def callback(`completion`, `prefix`, `user_param1`, `...`)`
"match-selected" | `def callback(`completion`, `model`, `iter`, `user_param1`, `...`)`

## Description

### Note

This widget is available in PyGTK 2.4 and above.

`gtk.EntryCompletion` is an auxiliary object to be used in conjunction with `gtk.Entry` to provide completion functionality. It implements the `gtk.CellLayout` interface, to allow the user to add extra cells to the popup display of completions.

To add completion functionality to an entry, use the `gtk.Entry.set_completion`() method. In addition to regular completion matches, that will be inserted into the entry when they are selected, `gtk.EntryCompletion` also allows "actions" to be displayed in the popup window below any completions. Their appearance is similar to menuitems, to differentiate them clearly from completion strings. When an action is selected, the "action-activated" signal is emitted.

When the user selects a completion, the content of the entry is updated. By default, the content of the entry is replaced by the text column of the model, but this can be overridden by connecting to the "match-selected" signal and updating the entry in the signal handler. Note that you should return `True` from the signal handler to suppress the default behaviour.

A `gtk.TreeModel` (e.g. a `gtk.ListStore`) containing the completion strings is associated with the `gtk.EntryCompletion` using the `set_model`() method. The tree model column containing the completion strings can be set using the convenience method `set_text_column`() that also creates a `gtk.CellRendererText` and packs it into the entry completion.

Otherwise, you can create `gtk.CellRenderer` objects and pack them into the `gtk.EntryCompletion` using the `gtk.CellLayout` methods `gtk.CellLayout.pack_start`() or `gtk.CellLayout.pack_start`(). However, you will also have to define a match function and set it with the `set_match_func`() method.

If you wanted to create a completion list with the strings to insert and some additional info e.g. an icon or description you could do something like:

      entry = gtk.Entry()
      completion = gtk.EntryCompletion()
      entry.set_completion(completion)
      liststore = gtk.ListStore(gobject.TYPE_STRING, gtk.gdk.Pixbuf)
      completion.set_model(liststore)
      pixbufcell = gtk.CellRendererPixbuf()
      completion.pack_start(pixbufcell)
      completion.add_attribute(pixbufcell, 'pixbuf', 1)
      # create a gtk.CellRendererText and pack it in the completion. Also set the
      # 'text' attribute
      completion.set_text_column(0)
      # load up the liststore with string - pixbuf data - assuming pixbuf created
      liststore.append(['string text', pixbuf])

This will create an entry that will display a pixbuf and the text string during completion.

Actions are easily managed using the `insert_action_text`(), `insert_action_markup`() and `delete_action`() methods.

## Constructor

        gtk.EntryCompletion()

Returns : | A newly created `gtk.EntryCompletion` object.

### Note

This constructor is available in PyGTK 2.4 and above.

Creates a new `gtk.EntryCompletion` object.

## Methods

### gtk.EntryCompletion.get_entry

        def get_entry()

Returns : | The `gtk.Entry` that the completion is attached to.

### Note

This method is available in PyGTK 2.4 and above.

The `get_entry`() method retrieves the `gtk.Entry` that the entry completion is attached to.

### gtk.EntryCompletion.set_model

        def set_model(model=None)

`model` : | The `gtk.TreeModel` to use with the entry completion.

### Note

This method is available in PyGTK 2.4 and above.

The `set_model`() method sets the `gtk.TreeModel` specified by `model` to be used with the entry completion. A previously set model will be removed before the new model is set. If `model` is `None` or not specified, the old model will be unset.

### Note

In PyGTK 2.4.0 the model could not be `None` and did not default to `None`.

### gtk.EntryCompletion.get_model

        def get_model()

Returns : | The current `gtk.TreeModel`, or `None` if not set.

### Note

This method is available in PyGTK 2.4 and above.

The `get_model`() method returns the `gtk.TreeModel` that the entry completion is using as data source. Returns `None` if the model is unset.

### gtk.EntryCompletion.set_match_func

        def set_match_func(func, func_data)

`func` : | A function to be used.
`func_data` : | The user data for `func`.

### Note

This method is available in PyGTK 2.4 and above.

The `set_match_func`() method sets the match function specified by `func`. The match function is used by the entry completion to determine if a row of the associated tree model should be in the completion list.

The signature of the match function is:

      def match_func(completion, key_string, iter, func_data):

where `completion` is the `gtk.EntryCompletion` that the match function is invoked on, `key_string` is the current contents of the `gtk.Entry` to be matched, `iter` is a `gtk.TreeIter` pointing at a row in the `gtk.TreeModel` associated with completion and `func_data` is the data specified when the `set_match_func`() method was called. The match function should return `True` if the completion string should be displayed; otherwise, `False`.

A simple example match function is:

      # Assumes that the func_data is set to the number of the text column in the
      # model.
      def match_func(completion, key, iter, column):
        model = completion.get_model()
        text = model.get_value(iter, column)
        if text.startswith(key):
          return True
        return False

You must use the `set_match_func`() method to display completions if you don't use the `set_text_column`() method.

### gtk.EntryCompletion.set_minimum_key_length

        def set_minimum_key_length(length)

`length` : | The minimum length of the key string in order to start completing.

### Note

This method is available in PyGTK 2.4 and above.

The `set_minimum_key_length`() method sets the minimum length of the search key to the value specified by `length`. This means that the key string (contents of the `gtk.Entry`) must be at least `length` characters before a completion list will be displayed. This is useful for long lists, where completing using a small key will take too much time and will likely return too large a dataset.

### gtk.EntryCompletion.get_minimum_key_length

        def get_minimum_key_length()

Returns : | The currently used minimum key length.

### Note

This method is available in PyGTK 2.4 and above.

The `get_minimum_key_length`() method returns the minimum key length set for the entry completion. See the `set_minimum_key_length`() method for more information.

### gtk.EntryCompletion.complete

        def complete()

### Note

This method is available in PyGTK 2.4 and above.

The `complete`() method requests a completion operation, i.e. a refiltering of the current list with completions, using the current key. The completion list view will be updated accordingly.

### gtk.EntryCompletion.insert_action_text

        def insert_action_text(index, text)

`index` : | The index in the action list where the item should be inserted.
`text` : | The text of the item to insert.

### Note

This method is available in PyGTK 2.4 and above.

The `insert_action_text`() method inserts an action in the action item list of the entry completion at the position specified by `index` with the text specified by `text`. If you want the action item to have markup, use the `gtk.EntryCompletion.insert_action_markup()` method.

### gtk.EntryCompletion.insert_action_markup

        def insert_action_markup(index, markup)

`index` : | The index in the action list where the item should be inserted.
`markup` : | The Pango markup of the item to insert.

### Note

This method is available in PyGTK 2.4 and above.

The `insert_action_markup`() method inserts an action item in the action item list of the entry completion at the position specified by `index` with the Pango markup specified by `markup`.

### gtk.EntryCompletion.delete_action

        def delete_action(index)

`index` : | The index of the item to delete.

### Note

This method is available in PyGTK 2.4 and above.

The `delete_action`() method deletes the action item at the position in the action item list specified by `index`.

### gtk.EntryCompletion.insert_prefix

        def insert_prefix()

### Note

This method is available in PyGTK 2.6 and above.

The `insert_prefix`() method requests a prefix insertion.

### gtk.EntryCompletion.set_text_column

        def set_text_column(column)

`column` : | The column in the model to get strings from.

### Note

This method is available in PyGTK 2.4 and above.

The `set_text_column`() method is a convenience method for setting up the most common completion scenario: a completion list with just strings. This method creates and adds a `gtk.CellRendererText` using the column specified by `column` as the source for completion strings. If you don't use this method you will have to install a `gtk.CellRendererText` in the entry completion and set a match function using the `set_match_func`() method to display the completion strings. In GTK+ 2.6 the "text-column" property is set to the value of `column`.

### gtk.EntryCompletion.get_text_column

        def get_text_column()

Returns : | The column containing the text strings.

### Note

This method is available in PyGTK 2.8 and above.

The `get_text_column`() method returns the value of the "text-column" property. The "text-column" property contains the index of the column in the completion model to get strings from. See the `set_text_column`() method for more information.

### gtk.EntryCompletion.set_inline_completion

        def set_inline_completion(inline_completion)

`inline_completion` : | if `True` do inline completion

### Note

This method is available in PyGTK 2.6 and above.

The `set_inline_completion`() method sets the "inline-completion" property to the value of `inline_completion`. If `inline_completion` is `True`, the common prefix of the possible completions should be automatically inserted in the entry.

### gtk.EntryCompletion.get_inline_completion

        def get_inline_completion()

Returns : | `True` if automatic inline completion is enabled.

### Note

This method is available in PyGTK 2.6 and above.

The `get_inline_completion`() method returns the value of the "inline-completion" property. If the value of the "inline-completion" property is `True` the common prefix of possible completions is automatically inserted in the entry.

### gtk.EntryCompletion.set_inline_selection

        def set_inline_selection(inline_selection)

`inline_selection` : | if `True` do inline selection

### Note

This method is available in PyGTK 2.12 and above.

The `set_inline_selection`() method Sets whether it is possible to cycle through the possible completions inside the entry.

### gtk.EntryCompletion.get_inline_selection

        def get_inline_selection()

Returns : | `True` if automatic inline selection is enabled.

### Note

This method is available in PyGTK 2.12 and above.

The `get_inline_selection`() method returns `True` if inline-selection mode is turned on.

### gtk.EntryCompletion.set_popup_completion

        def set_popup_completion(popup_completion)

`popup_completion` : | If `True` do popup completion.

### Note

This method is available in PyGTK 2.6 and above.

The `set_popup_completion`() method sets the "popup-completion" property to the value of `popup_completion`. If `popup_completion` is `True` the completions should be presented in a popup window.

### gtk.EntryCompletion.get_popup_completion

        def get_popup_completion()

Returns : | `True` if completions should be displayed in a popup.

### Note

This method is available in PyGTK 2.6 and above.

The `get_popup_completion`() method returns the value of the "popup-completion" property. If the value of "popup-completion" property is `True` the completions should be presented in a popup window.

### gtk.EntryCompletion.set_popup_set_width

        def set_popup_set_width(popup_set_width)

`popup_set_width` : | If `True` the completions popup window will be resized to the width of the completion.

### Note

This method is available in PyGTK 2.8 and above.

The `set_popup_set_width`() method sets the "popup-set-width" property to the value of `popup_set_width`. If `popup_set_width` is `True` the completions popup window will be resized to the width of the completion.

### gtk.EntryCompletion.get_popup_set_width

        def get_popup_set_width()

Returns : | `True` if the completions popup window will be resized to the width of the completion.

### Note

This method is available in PyGTK 2.8 and above.

The `get_popup_set_width`() method returns the value of the "popup-set-width" property. If the value of "popup-set-width" property is `True` the completions popup window will be resized to the width of the completion.

### gtk.EntryCompletion.set_popup_single_match

        def set_popup_single_match(popup_single_match)

`popup_single_match` : | If `True` the completions popup window will appear even for a single match.

### Note

This method is available in PyGTK 2.8 and above.

The `set_popup_single_match`() method sets the "popup-single-match" property to the value of `popup_single_match`. If `popup_single_match` is `True` the completions popup window will appear even for a single match.

### gtk.EntryCompletion.get_popup_completion

        def get_popup_single_match()

Returns : | `True` if the completions popup window should appear even for a single match.

### Note

This method is available in PyGTK 2.8 and above.

The `get_popup_single_match`() method returns the value of the "popup-single-match" property. If the value of "popup-single-match" property is `True` the completions popup window should appear even for a single match.

### gtk.EntryCompletion.get_completion_prefix

        def get_completion_prefix()

Returns : | The prefix for the current completion.

### Note

This method is available in PyGTK 2.12 and above.

The `get_completion_prefix`() method gets the original text entered by the user that triggered the completion or `None` if there's no completion ongoing.

## Signals

### The "action-activated" gtk.EntryCompletion Signal

        def callback(completion, index, user_param1, ...)

`completion` : | the entry completion that received the signal
`index` : | the index of the action item that was activated.
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in GTK+ 2.4 and above.

The "action-activated" signal is emitted when an action item is selected from the popup action list.

### The "cursor-on-match" gtk.EntryCompletion Signal

        def callback(completion, model, iter, user_param1, ...)

`completion` : | the entry completion that received the signal
`model` : | The `gtk.TreeModel` containing the matches.
`iter` : | A `gtk.TreeIter` positioned at the selected match.
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in GTK+ 2.12 and above.

The "cursor-on-match" signal gets emitted when a match from the cursor is on a match of the list.The default behaviour is to replace the contents of the entry with the contents of the text column in the row pointed to by iter.

### The "insert-prefix" gtk.EntryCompletion Signal

        def callback(completion, prefix, user_param1, ...)

`completion` : | the entry completion that received the signal
`prefix` : | the common prefix of all possible completions
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in GTK+ 2.6 and above.

The "insert-prefix" signal is emitted when the inline auto-completion is triggered. The default behavior is to make the entry display the whole prefix and select the newly inserted part.

Applications may connect to this signal in order to insert only a smaller part of the prefix into the entry - e.g. the entry used in the `gtk.FileChooser` inserts only the part of the prefix up to the next '/'.

### The "match-selected" gtk.EntryCompletion Signal

        def callback(completion, model, iter, user_param1, ...)

`completion` : | the entry completion that received the signal
`model` : | the `gtk.TreeModel` that `iter` points into.
`iter` : | a `gtk.TreeIter` pointing at the selection completion string row in `model`.
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in GTK+ 2.4 and above.

The "match-selected" signal is emitted when a completion string was selected from the completion list. `iter` points at the row in `model` that contains the completion string.

Prev | Up | Next
gtk.EntryBuffer | Home | gtk.EventBox