gtk.EntryCompletioncompletion
functionality for gtk.Entry (new in
PyGTK 2.4)Synopsisgtk.EntryCompletiongobject.GObjectgtk.CellLayoutgtk.EntryCompletionget_entryset_modelmodelNoneget_modelset_match_funcfuncfunc_dataset_minimum_key_lengthlengthget_minimum_key_lengthcompleteinsert_action_textindextextinsert_action_markupindexmarkupdelete_actionindexinsert_prefixset_text_columncolumnget_text_columnset_inline_completioninline_completionget_inline_completionset_inline_selectioninline_selectionget_inline_selectionset_popup_completionpopup_completionget_popup_completionset_popup_set_widthpopup_set_widthget_popup_set_widthset_popup_single_matchpopup_single_matchget_popup_single_matchget_completion_prefixAncestry+-- gobject.GObject
+-- gtk.EntryCompletion
Implemented Interfacesgtk.EntryCompletion
implements
gtk.Buildablegtk.CellLayoutgtk.EntryCompletion Properties
"inline-completion"Read-WriteIf True the common prefix should be
inserted automatically. Default value:
False. Available in GTK+ 2.6 and
above."inline-selection"Read-WriteDetermines 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-WriteMinimum length of the search key in order to look up
matches. Allowed values >= 0. Default value: 1"model"Read-WriteThe gtk.TreeModel
to find matches in."popup-completion"Read-WriteIf True the completions should be
shown in a popup window. Default value:
True. Available in GTK+ 2.6 and
above."popup-set-width"Read-WriteIf 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-WriteIf 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-WriteThe column of the model containing the strings. Allowed
values: >= -1. Default value: -1. Available in GTK+ 2.6 and
above.
gtk.EntryCompletion Signal Prototypesgobject.GObject Signal Prototypes"action-activated"callbackcompletionindexuser_param1..."cursor-on-match"callbackcompletionmodeliteruser_param1..."insert-prefix"callbackcompletionprefixuser_param1..."match-selected"callbackcompletionmodeliteruser_param1...DescriptionThis 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.Constructorgtk.EntryCompletionReturns :A newly created gtk.EntryCompletion object.This constructor is available in PyGTK 2.4 and above.Creates a new gtk.EntryCompletion
object.Methodsgtk.EntryCompletion.get_entryget_entryReturns :The gtk.Entry
that the completion is attached to.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_modelset_modelmodelNonemodel :The gtk.TreeModel
to use with the entry completion.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.In PyGTK 2.4.0 the model could not be None
and did not default to None.gtk.EntryCompletion.get_modelget_modelReturns :The current gtk.TreeModel,
or None if not set.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_funcset_match_funcfuncfunc_datafunc :A function to be used.func_data :The user data for func.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_lengthset_minimum_key_lengthlengthlength :The minimum length of the key string in order
to start completing.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_lengthget_minimum_key_lengthReturns :The currently used minimum key
length.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.completecompleteThis 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_textinsert_action_textindextextindex :The index in the action list where the item
should be inserted.text :The text of the item to
insert.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_markupinsert_action_markupindexmarkupindex :The index in the action list where the item
should be inserted.markup :The Pango markup of the item to
insert.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_actiondelete_actionindexindex :The index of the item to
delete.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_prefixinsert_prefixThis method is available in PyGTK 2.6 and above.The insert_prefix() method requests a
prefix insertion.gtk.EntryCompletion.set_text_columnset_text_columncolumncolumn :The column in the model to get strings
from.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_columnget_text_columnReturns :The column containing the text
strings.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_completionset_inline_completioninline_completioninline_completion :if True do inline
completionThis 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_completionget_inline_completionReturns :True if automatic inline
completion is enabled.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_selectionset_inline_selectioninline_selectioninline_selection :if True do inline
selectionThis 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_selectionget_inline_selectionReturns :True if automatic inline
selection is enabled.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_completionset_popup_completionpopup_completionpopup_completion :If True do popup
completion.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_completionget_popup_completionReturns :True if completions should
be displayed in a popup.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_widthset_popup_set_widthpopup_set_widthpopup_set_width :If True the completions
popup window will be resized to the width of the
completion.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_widthget_popup_set_widthReturns :True if the completions popup
window will be resized to the width of the completion.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_matchset_popup_single_matchpopup_single_matchpopup_single_match :If True the completions popup
window will appear even for a single match.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_completionget_popup_single_matchReturns :True if the completions popup
window should appear even for a single match.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 get_completion_prefixReturns :The prefix for the current completion.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.SignalsThe "action-activated" gtk.EntryCompletion Signalcallbackcompletionindexuser_param1...completion :the entry completion that received the
signalindex :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)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 Signalcallbackcompletionmodeliteruser_param1...completion :the entry completion that received the
signalmodel :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)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 Signalcallbackcompletionprefixuser_param1...completion :the entry completion that received the
signalprefix : the common prefix of all possible
completionsuser_param1 :the first user parameter (if any) specified
with the connect()
method... :additional user parameters (if
any)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 Signalcallbackcompletionmodeliteruser_param1...completion :the entry completion that received the
signalmodel :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)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.