Gtk.EntryCompletion

Gtk.EntryCompletion — Completion functionality for Gtk.Entry

Object Hierarchy:

    GObject
    ╰── Gtk.EntryCompletion

Functions:

Signals:

  • “action-activated” (widget, index, user_data)
  • “cursor-on-match” (widget, model, iter, user_data)
  • “insert-prefix” (widget, prefix, user_data)
  • “match-selected” (widget, model, iter, user_data)
  • “no-matches” (widget, user_data)

Description:

Gtk.EntryCompletion is an auxiliary object to be used in conjunction with Gtk.Entry to provide the completion functionality. It implements the Gtk.CellLayout interface, to allow the user to add extra cells to the Gtk.TreeView with completion matches.

Completion functionality means that when the user modifies the text in the entry, Gtk.EntryCompletion checks which rows in the model match the current content of the entry, and displays a list of matches.

By default, the matching is done by comparing the entry text case-insensitively against the text column of the model (see Gtk.EntryCompletion::set_text_column()), but this can be overridden with a custom match function (see Gtk.EntryCompletion::set_match_func()).

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 Gtk.EntryCompletion::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.

To add completion functionality to an entry, use Gtk.Entry::set_completion().

In addition to regular completion matches, which will be inserted into the entry when they are selected, Gtk.EntryCompletion also allows to display actions in the popup window. Their appearance is similar to menuitems, to differentiate them clearly from completion strings. When an action is selected, the Gtk.EntryCompletion::action-activated signal is emitted.

Gtk.EntryCompletion uses a Gtk.TreeModelFilter model to represent the subset of the entire model that is currently matching. While the Gtk.EntryCompletion signals Gtk.EntryCompletion::match-selected and iter pointing to that model as arguments, other callbacks and signals (such as Gtk.CellLayoutDataFuncs or GtkCellArea::apply-attributes) will generally take the filter model as argument. As long as you are only calling Gtk.TreeModel::get(), this will make no difference to you. If for some reason, you need the original model, use Gtk.TreeModelFilter::get_model(). Don’t forget to use Gtk.TreeModelFilter::convert_iter_to_child_iter() to obtain a matching iter.

Function Details:

new()

new () -> Gtk.EntryCompletion

Creates a new Gtk.EntryCompletion object.

  • Returns: A newly created Gtk.EntryCompletion object

  • Since: 2.4

new_with_area()

new_with_area (area:Gtk.CellArea) -> Gtk.EntryCompletion

Creates a new Gtk.EntryCompletion object using thespecified area to layout cells in the underlyingGtk.TreeViewColumn for the drop-down menu.

  • Returns: A newly created Gtk.EntryCompletion object

  • Since: 3.0

get_entry()

get_entry (self) -> Gtk.Widget

Gets the entry completion has been attached to.

  • Returns: The entry completionhas been attached to.

  • Since: 2.4

set_model()

set_model (self, model:Gtk.TreeModel=None)

Sets the model for a Gtk.EntryCompletion. If completion already hasa model set, it will remove it before setting the new model.If model is None, then it will unset the model.

  • Since: 2.4

get_model()

get_model (self) -> Gtk.TreeModel

Returns the model the Gtk.EntryCompletion is using as data source.Returns None if the model is unset.

  • Returns: A Gtk.TreeModel, or None if noneis currently being used.

  • Since: 2.4

set_match_func()

set_match_func (self, func:Gtk.EntryCompletionMatchFunc, func_data=None)

Sets the match function for completion to be func. The match functionis used to determine if a row should or should not be in the completionlist.

  • Since: 2.4

set_minimum_key_length()

set_minimum_key_length (self, length:int)

Requires the length of the search key for completion to be at leastlength. This is useful for long lists, where completing using a smallkey takes a lot of time and will come up with meaningless results anyway(ie, a too large dataset).

  • Since: 2.4

get_minimum_key_length()

get_minimum_key_length (self) -> int

Returns the minimum key length as set for completion.

  • Returns: The currently used minimum key length

  • Since: 2.4

compute_prefix()

compute_prefix (self, key:str) -> str

Computes the common prefix that is shared by all rows in completionthat start with key. If no row matches key, None will be returned.Note that a text column must have been set for this function to work,see Gtk.EntryCompletion:set_text_column() for details.

  • Returns: The common prefix all rows starting with keyor None if no row matches key.

  • Since: 3.4

complete()

complete (self)

Requests a completion operation, or in other words a refiltering of thecurrent list with completions, using the current key. The completion listview will be updated accordingly.

  • Since: 2.4

get_completion_prefix()

get_completion_prefix (self) -> str

Get the original text entered by the user that triggeredthe completion or None if there’s no completion ongoing.

  • Returns: the prefix for the current completion

  • Since: 2.12

insert_prefix()

insert_prefix (self)

Requests a prefix insertion.

  • Since: 2.6

insert_action_text()

insert_action_text (self, index_:int, text:str)

Inserts an action in completion’s action item list at position index_with text text. If you want the action item to have markup, useGtk.EntryCompletion:insert_action_markup(). Note that index_ is a relative position in the list of actions andthe position of an action can change when deleting a different action.

  • Since: 2.4

insert_action_markup()

insert_action_markup (self, index_:int, markup:str)

Inserts an action in completion’s action item list at position index_with markup markup.

  • Since: 2.4

delete_action()

delete_action (self, index_:int)

Deletes the action at index_ from completion’s action list. Note that index_ is a relative position and the position of anaction may have changed since it was inserted.

  • Since: 2.4

set_text_column()

set_text_column (self, column:int)

Convenience function for setting up the most used case of this code: acompletion list with just strings. This function will set up completionto have a list displaying all (and just) strings in the completion list,and to get those strings from column in the model of completion. This functions creates and adds a Gtk.CellRendererText for the selectedcolumn. If you need to set the text column, but don't want the cellrenderer, use g_object_set() to set the “text-column”property directly.

  • Since: 2.4

get_text_column()

get_text_column (self) -> int

Returns the column in the model of completion to get strings from.

  • Returns: the column containing the strings

  • Since: 2.6

set_inline_completion()

set_inline_completion (self, inline_completion:bool)

Sets whether the common prefix of the possible completions shouldbe automatically inserted in the entry.

  • Since: 2.6

get_inline_completion()

get_inline_completion (self) -> bool

Returns whether the common prefix of the possible completions shouldbe automatically inserted in the entry.

  • Returns: True if inline completion is turned on

  • Since: 2.6

set_inline_selection()

set_inline_selection (self, inline_selection:bool)

Sets whether it is possible to cycle through the possible completionsinside the entry.

  • Since: 2.12

get_inline_selection()

get_inline_selection (self) -> bool

Returns True if inline-selection mode is turned on.

  • Returns: True if inline-selection mode is on

  • Since: 2.12

set_popup_completion()

set_popup_completion (self, popup_completion:bool)

Sets whether the completions should be presented in a popup window.

  • Since: 2.6

get_popup_completion()

get_popup_completion (self) -> bool

Returns whether the completions should be presented in a popup window.

  • Returns: True if popup completion is turned on

  • Since: 2.6

set_popup_set_width()

set_popup_set_width (self, popup_set_width:bool)

Sets whether the completion popup window will be resized to be the samewidth as the entry.

  • Since: 2.8

get_popup_set_width()

get_popup_set_width (self) -> bool

Returns whether the completion popup window will be resized to thewidth of the entry.

  • Returns: True if the popup window will be resized to the width ofthe entry

  • Since: 2.8

set_popup_single_match()

set_popup_single_match (self, popup_single_match:bool)

Sets whether the completion popup window will appear even if there isonly a single match. You may want to set this to FALSE if youare using inline completion.

  • Since: 2.8

get_popup_single_match()

get_popup_single_match (self) -> bool

Returns whether the completion popup window will appear even if there isonly a single match.

  • Returns: True if the popup window will appear regardless of thenumber of matches

  • Since: 2.8

Example:

import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk

class EntryCompletion(Gtk.Window):
    def __init__(self):
        Gtk.Window.__init__(self)
        self.set_title("EntryCompletion")
        self.connect("destroy", Gtk.main_quit)

        grid = Gtk.Grid()
        self.add(grid)

        liststore = Gtk.ListStore(str)

        for item in ["Andrew", "Natalie", "Mark", "David", "Daniel", "Anita", "Matthew"]:
            liststore.append([item])

        self.entrycompletion = Gtk.EntryCompletion()
        self.entrycompletion.set_model(liststore)
        self.entrycompletion.set_text_column(0)

        entry = Gtk.Entry()
        entry.set_completion(self.entrycompletion)
        grid.attach(entry, 0, 0, 1, 1)

        radiobuttonPopup = Gtk.RadioButton("Popup Completion")
        radiobuttonPopup.mode = 0
        radiobuttonPopup.connect("toggled", self.on_radiobutton_toggled)
        grid.attach(radiobuttonPopup, 0, 1, 1, 1)
        radiobuttonInline = Gtk.RadioButton("Inline Completion")
        radiobuttonInline.mode = 1
        radiobuttonInline.join_group(radiobuttonPopup)
        radiobuttonInline.connect("toggled", self.on_radiobutton_toggled)
        grid.attach(radiobuttonInline, 0, 2, 1, 1)

    def on_radiobutton_toggled(self, radiobutton):
        if radiobutton.get_active():
            if radiobutton.mode == 0:
                self.entrycompletion.set_popup_completion(True)
                self.entrycompletion.set_inline_completion(False)
            elif radiobutton.mode == 1:
                self.entrycompletion.set_popup_completion(False)
                self.entrycompletion.set_inline_completion(True)


window = EntryCompletion()
window.show_all()

Gtk.main()

results matching ""

    No results matching ""