EntryCompletion
Deprecated since version 4.10: Please do not use it in newly written code
Superclasses: Object
Implemented Interfaces: Buildable
, CellLayout
GtkEntryCompletion
is an auxiliary object to provide completion functionality
for GtkEntry
.
It implements the CellLayout
interface, to allow the user
to add extra cells to the GtkTreeView
with completion matches.
“Completion functionality” means that when the user modifies the text
in the entry, GtkEntryCompletion
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
set_text_column
), but this can be overridden
with a custom match function (see 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 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
set_completion
.
GtkEntryCompletion
uses a TreeModelFilter
model to
represent the subset of the entire model that is currently matching.
While the GtkEntryCompletion
signals
match_selected
and
cursor_on_match
take the original model
and an iter pointing to that model as arguments, other callbacks and
signals (such as GtkCellLayoutDataFunc
or
apply_attributes)
will generally take the filter model as argument. As long as you are
only calling get
, this will make no difference to
you. If for some reason, you need the original model, use
get_model
. Don’t forget to use
convert_iter_to_child_iter
to obtain a
matching iter.
Constructors
- class EntryCompletion
- classmethod new() EntryCompletion
Creates a new
GtkEntryCompletion
object.Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- classmethod new_with_area(area: CellArea) EntryCompletion
Creates a new
GtkEntryCompletion
object using the specifiedarea
.The
GtkCellArea
is used to layout cells in the underlyingGtkTreeViewColumn
for the drop-down menu.Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- Parameters:
area – the
GtkCellArea
used to layout cells
Methods
- class EntryCompletion
- complete() None
Requests a completion operation, or in other words a refiltering of the current list with completions, using the current key.
The completion list view will be updated accordingly.
Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- compute_prefix(key: str) str | None
Computes the common prefix that is shared by all rows in
completion
that start withkey
.If no row matches
key
,None
will be returned. Note that a text column must have been set for this function to work, seeset_text_column
for details.Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- Parameters:
key – The text to complete for
- get_completion_prefix() str | None
Get the original text entered by the user that triggered the completion or
None
if there’s no completion ongoing.Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- get_entry() Widget
Gets the entry
completion
has been attached to.Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- get_inline_completion() bool
Returns whether the common prefix of the possible completions should be automatically inserted in the entry.
Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- get_inline_selection() bool
Returns
True
if inline-selection mode is turned on.Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- get_minimum_key_length() int
Returns the minimum key length as set for
completion
.Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- get_model() TreeModel | None
Returns the model the
GtkEntryCompletion
is using as data source.Returns
None
if the model is unset.Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- get_popup_completion() bool
Returns whether the completions should be presented in a popup window.
Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- get_popup_set_width() bool
Returns whether the completion popup window will be resized to the width of the entry.
Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- get_popup_single_match() bool
Returns whether the completion popup window will appear even if there is only a single match.
Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- get_text_column() int
Returns the column in the model of
completion
to get strings from.Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- insert_prefix() None
Requests a prefix insertion.
Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- set_inline_completion(inline_completion: bool) None
Sets whether the common prefix of the possible completions should be automatically inserted in the entry.
Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- Parameters:
inline_completion –
True
to do inline completion
- set_inline_selection(inline_selection: bool) None
Sets whether it is possible to cycle through the possible completions inside the entry.
Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- Parameters:
inline_selection –
True
to do inline selection
- set_match_func(func: Callable[[...], bool], *func_data: Any) None
Sets the match function for
completion
to befunc
.The match function is used to determine if a row should or should not be in the completion list.
Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- Parameters:
func – the ``GtkEntryCompletion``MatchFunc to use
func_data – user data for
func
- set_minimum_key_length(length: int) None
Requires the length of the search key for
completion
to be at leastlength
.This is useful for long lists, where completing using a small key takes a lot of time and will come up with meaningless results anyway (ie, a too large dataset).
Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- Parameters:
length – the minimum length of the key in order to start completing
- set_model(model: TreeModel | None = None) None
Sets the model for a
GtkEntryCompletion
.If
completion
already has a model set, it will remove it before setting the new model. If model isNone
, then it will unset the model.Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- Parameters:
model – the
GtkTreeModel
- set_popup_completion(popup_completion: bool) None
Sets whether the completions should be presented in a popup window.
Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- Parameters:
popup_completion –
True
to do popup completion
- set_popup_set_width(popup_set_width: bool) None
Sets whether the completion popup window will be resized to be the same width as the entry.
Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- Parameters:
popup_set_width –
True
to make the width of the popup the same as the entry
- set_popup_single_match(popup_single_match: bool) None
Sets whether the completion popup window will appear even if there is only a single match.
You may want to set this to
False
if you are usinginline_completion
.Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- Parameters:
popup_single_match –
True
if the popup should appear even for a single match
- set_text_column(column: int) None
Convenience function for setting up the most used case of this code: a completion list with just strings.
This function will set up
completion
to have a list displaying all (and just) strings in the completion list, and to get those strings fromcolumn
in the model ofcompletion
.This functions creates and adds a
GtkCellRendererText
for the selected column. If you need to set the text column, but don’t want the cell renderer, useset()
to set thetext_column
property directly.Deprecated since version 4.10: GtkEntryCompletion will be removed in GTK 5.
- Parameters:
column – the column in the model of
completion
to get strings from
Properties
- class EntryCompletion
- props.cell_area: CellArea
The
GtkCellArea
used to layout cell renderers in the treeview column.If no area is specified when creating the entry completion with
new_with_area
, a horizontally orientedCellAreaBox
will be used.
- props.inline_completion: bool
Determines whether the common prefix of the possible completions should be inserted automatically in the entry.
Note that this requires text-column to be set, even if you are using a custom match function.
- props.inline_selection: bool
Determines whether the possible completions on the popup will appear in the entry as you navigate through them.
- props.popup_completion: bool
Determines whether the possible completions should be shown in a popup window.
- props.popup_set_width: bool
Determines whether the completions popup window will be resized to the width of the entry.
- props.popup_single_match: bool
Determines whether the completions popup window will shown for a single possible completion.
You probably want to set this to
False
if you are usinginline_completion
.
Signals
- class EntryCompletion.signals
- cursor_on_match(model: TreeModel, iter: TreeIter) bool
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
.Note that
model
is the model that was passed toset_model
.- Parameters:
model – the
GtkTreeModel
containing the matchesiter – a
GtkTreeIter
positioned at the selected match
- insert_prefix(prefix: str) bool
Emitted when the inline autocompletion is triggered.
The default behaviour 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 theGtkFileChooser
inserts only the part of the prefix up to the next ‘/’.- Parameters:
prefix – the common prefix of all possible completions
- match_selected(model: TreeModel, iter: TreeIter) bool
Emitted when a match from the list is selected.
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
.Note that
model
is the model that was passed toset_model
.- Parameters:
model – the
GtkTreeModel
containing the matchesiter – a
GtkTreeIter
positioned at the selected match