gtk.EntryCompletion — completion
functionality for gtk.Entry
(new in
PyGTK 2.4)
class gtk.EntryCompletion( |
|
def callback( | |
def callback( | |
def callback( | |
def callback( |
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.
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.
def 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.
def set_model(model
=None)
| 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
.
def 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.
def set_match_func(func
, func_data
)
| A function to be used. |
| 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.
def set_minimum_key_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.
def 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.
def 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.
def insert_action_text(index
, text
)
| The index in the action list where the item should be inserted. |
| 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.
def insert_action_markup(index
, markup
)
| The index in the action list where the item should be inserted. |
| 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
.
def delete_action(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
.
def insert_prefix()
This method is available in PyGTK 2.6 and above.
The insert_prefix
() method requests a
prefix insertion.
def set_text_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
.
def 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.
def set_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.
def 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.
def set_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.
def 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.
def set_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.
def 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.
def set_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.
def 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.
def set_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.
def 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.
def 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.
def callback(completion
, index
, user_param1
, ...
)
| the entry completion that received the signal |
| the index of the action item that was activated. |
| the first user parameter (if any) specified
with the connect () |
| 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.
def callback(completion
, model
, iter
, user_param1
, ...
)
| the entry completion that received the signal |
| The gtk.TreeModel
containing the matches. |
| A gtk.TreeIter
positioned at the selected match. |
| the first user parameter (if any) specified
with the connect () |
| 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.
def callback(completion
, prefix
, user_param1
, ...
)
| the entry completion that received the signal |
| the common prefix of all possible completions |
| the first user parameter (if any) specified
with the connect () |
| 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 '/'.
def callback(completion
, model
, iter
, user_param1
, ...
)
| the entry completion that received the signal |
| the gtk.TreeModel
that iter points into. |
| a gtk.TreeIter
pointing at the selection completion string row in
model . |
| the first user parameter (if any) specified
with the connect () |
| 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.