gtk.EntryCompletion completion functionality for gtk.Entry (new in PyGTK 2.4) Synopsis gtk.EntryCompletion gobject.GObject gtk.CellLayout gtk.EntryCompletion get_entry set_model modelNone get_model set_match_func func func_data set_minimum_key_length length get_minimum_key_length complete insert_action_text index text insert_action_markup index markup delete_action index insert_prefix set_text_column column get_text_column set_inline_completion inline_completion get_inline_completion set_inline_selection inline_selection get_inline_selection set_popup_completion popup_completion get_popup_completion set_popup_set_width popup_set_width get_popup_set_width set_popup_single_match popup_single_match get_popup_single_match 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" callback completion index user_param1 ... "cursor-on-match" callback completion model iter user_param1 ... "insert-prefix" callback completion prefix user_param1 ... "match-selected" callback completion model iter user_param1 ... Description 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. 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. This constructor is available in PyGTK 2.4 and above. Creates a new gtk.EntryCompletion object. Methods gtk.EntryCompletion.get_entry get_entry Returns : 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_model set_model modelNone model : 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_model get_model Returns : 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_func set_match_func func func_data func : 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_length set_minimum_key_length length length : 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_length get_minimum_key_length Returns : 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.complete complete 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 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. 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 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. 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 delete_action index index : 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_prefix insert_prefix This method is available in PyGTK 2.6 and above. The insert_prefix() method requests a prefix insertion. gtk.EntryCompletion.set_text_column set_text_column column column : 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_column get_text_column Returns : 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_completion set_inline_completion inline_completion inline_completion : if True do inline completion 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 get_inline_completion Returns : 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_selection set_inline_selection inline_selection inline_selection : if True do inline selection 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 get_inline_selection Returns : 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_completion set_popup_completion popup_completion popup_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_completion get_popup_completion Returns : 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_width 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. 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 get_popup_set_width Returns : 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_match set_popup_single_match popup_single_match popup_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_completion get_popup_single_match Returns : 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_prefix Returns : 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. Signals The "action-activated" gtk.EntryCompletion Signal 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) 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 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) 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 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) 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 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) 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.