| Tk::MatchEntry - Entry widget with advanced auto-completion capability |
Tk::MatchEntry - Entry widget with advanced auto-completion capability
use Tk::MatchEntry;
$match_entry = $top->MatchEntry(-textvariable => \$var1,
-choices => @choices);
Tk::MatchEntry is an Entry widget with focus on user-friendly
auto-completion. Its usage is similar to Tk::BrowseEntry and
Tk::HistEntry.
With each character the user types in the widget, automatic completion can be attempted based on a list of choices you as programmer specify.
If there's more than one of the choices matching the text which the user has entered so far, she can optionally select the desired auto-completion choice from an up-popping listbox, either by using the mouse or by browsing them with the Up and Down cursor keys.
This listbox with auto-completion choices pops up automatically by default and only shows these choices which still can match the manually entered text, i.e. the number of displayed items usually decreases with the length of text entered by the user.
The auto-completed part of the text in the Entry widget always gets selected so the next manually entered character overwrites it. Thus, the auto-completion feature never prevents the user from typing what she really wants to.
Starting with version 0.2, Tk::MatchEntry has a multi-match mode in which
each word the user types can be auto-completed. For example, if you've got the
four choices Another, Hacker, Just and Perl, the user can write
Just Another Perl Hacker for example by hitting J, Return, A, Return, P,
Return, H, Return.
Besides the options which can be applied to the entry and slistbox
subwidgets, MatchEntry provides the following specific options:
Tk::BrowseEntry.
Tk::MatchEntry
is all about, so it defaults to 1. Auto-completion is hopefully smart
enough to know what the user wants to do and doesn't mess up the text
she's entering.
John Doe and the user starts with a j, auto-completion
will be john Doe. However, if auto-completion is set to case-insensitivity
AND the text in the entry widget matches one of the choices when the
MatchEntry widget is left, the text will be replaced by the choice, i.e.
in our example, john Doe would turn into John Doe. Defaults to 0.
Tk::BrowseEntry. Defaults to 1.
Tk::MatchEntry attempts to match and auto-complete
the whole text in the entry widget. In multi-match mode, it does
the same for each word the user enters. Don't use this unless you're
sure that's what you want. When using multi-match mode, the choices
should be single words (as opposed to phrases, i.e. multiple
blank-separated words). Defaults to 0.
The value of this option defaults to undef and you should only change it if you know what you're doing: both matching this regular expression against each key pressed by the user and unnecessarily often calling resort can decrease performance.
Example usage:
... -sorttrigger => '^Left|^Right|^space|^Home|^End', ... (The lower case s in I<^space> is actually not a typo)
http://www.cpan.org
and you would like to allow the user typing either of these:
http://www.cpan.org www.cpan.org cpan.org
while still getting the benefits of auto-completion and the up-popping choices listbox, then you should set -matchprefix to
'(?:http:\/\/)?(?:www\.)?'
In fact, -matchprefix is a regular expression which must fulfill the following criteria:
1) You must use non-capturing brackets if you're using grouping. That's why we use
(?:http:\/\/)?
in the above example and NOT
(http:\/\/)?
2) Prefix matches must be optional, i.e. you always should use the ? quantifier (using * would work, too, but might be bad for performance).
Here's another example for matching HTTP and FTP URLs like in the above example, i.e. both the http:// and www. parts are optional.
... -matchprefix => '(?:(?:ftp|http):\/\/)?(?:(?:ftp|www)\.)?', ...
=back
The following options specify callbacks:
-zerocmd and -onecmd are supposed to be used together in applications where you want totally different choices depending on whether the user has already entered any text yet. For example, if a MatchEntry widget is used for the recipient's name in an email client, the choices
a) when the user has not entered anything yet could be the names of the 10 last persons he had sent an email to.
b) after entering the first character could be appropriate names from his address book.
Tk::BrowseEntry.
A reference to the array of choices is passed to the custom sorting function and it must return a reference to the sorted array.
Trivial example:
sub mysort {
my $ref = shift;
my @choices = @$ref;
my @sorted_choices = sort @choices;
return \@sorted_choices;
}
You can abuse this callback to insert or delete choices while sorting them. Normally, the standard choices method is used to update the choices array, of course.
Tk::MatchEntry does, compared to Tk::BrowseEntry and
Tk::HistEntry, not provide an arrow button for popping up the
listbox, you might want to use a button of your own for this
purpose.
If the listbox is already open, calling this method closes it.
If given an array as parameter, it will set the choices. Unless autosort is turned off, the choices will be sorted automatically, either using Perl's built-in sort function or the -sortcmd callback you've specified.
John Doe, but the user just wants
to enter John, she actually has to press Escape (or Delete)
to remove the auto-completed Doe part.
If you need to configure the subwidgets, for example to set different background colors for the entry and the listbox widget, you can access them like this:
my $entry_subwidget = $matchentry->Subwidget('entry');
my $listbox_subwidget =
$matchentry->Subwidget('slistbox')->Subwidget('listbox');
slistbox is the scrolled listbox.
=head1 BUGS
This is a primitive example for Tk::MatchEntry which you can use to get to know the look and feel.
use Tk;
use Tk::MatchEntry;
my $mw = MainWindow->new(-title => "MatchEntry Test");
my @choices = [ qw/one one.green one.blue one.yellow two.blue two.green
two.cyan three.red three.white three.yellow/ ];
$mw->Button->pack(-side => 'left');
my $me = $mw->MatchEntry(
-choices => @choices,
-fixedwidth => 1,
-ignorecase => 1,
-maxheight => 5,
-entercmd => sub { print "callback: -entercmd\n"; },
-onecmd => sub { print "callback: -onecmd \n"; },
-tabcmd => sub { print "callback: -tabcmd \n"; },
-zerocmd => sub { print "callback: -zerocmd \n"; },
)->pack(-side => 'left', -padx => 50);
$mw->Button(-text => 'popup',
-command => sub{$me->popup}
)->pack(-side => 'left');
MainLoop;
Wolfgang Hommel <wolf (at) code-wizards.com>
The following widgets are similar to Tk::MatchEntry to a certain extent:
Thanks to
Copyright (c) 2003 - 2005 Wolfgang Hommel. All rights reserved.
This package is free software; you can redistribute it and/or modifiy it under the same terms as Perl itself.
| Tk::MatchEntry - Entry widget with advanced auto-completion capability |