foreach my $val (@$choices) {
            $self->insert('end', $val);
            $h{$val} = 1;
        }

        $old = (@$choices) ? $choices->[0] : undef 
            unless exists $h{$old};

            # don't change old entry content (as opposed to Tk::BrowseEntry)
            # $$var = $old; 

NAME

Tk::MatchEntry - Entry widget with advanced auto-completion capability

SYNOPSIS

use Tk::MatchEntry;

$match_entry = $top->MatchEntry(-textvariable => \$var1, -choices => @choices);

DESCRIPTION

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.

OPTIONS

Besides the options which can be applied to the entry and slistbox subwidgets, MatchEntry provides the following specific options:

-textvariable or -variable

The variable which is tied to the MatchEntry widget. -variable, as used in BrowseEntry, is just an alias for -textvariable. This variable will contain the entry widget's text.

-choices

Array of strings which the auto-completion feature attempts to match. Used the same way as in Tk::BrowseEntry.

-complete

If set to a true value, auto-completion is attempted whenever the user enters another character in the widget. This is what 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.

-ignorecase

If not false, auto-completion works case-insensitive. Thus, if you have a choice 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.

-autopopup

If set to a true value, the listbox with auto-completion choices will automatically pop up if the user has entered at least one character in the widget yet AND there's at least two possible choices. Defaults to 1.

-maxheight

Sets the maximum number of entries per page in the (scrolled) popup listbox with auto-completion choices. Defaults to 5.

-autoshrink

If set to a true value, the popup listbox's height will decrease if there's less than -maxheight items to display. For example, if -maxheight is set to 5, but there's only 3 choices, and -autoshrink is set to 1, then the listbox will show only those 3 choices instead of the 3 choices plus two empty rows.

-fixedwidth

If set to a true value, the popup listbox will always have the same width as the entry widget. Otherwise, the width of the listbox is calculated the same way as in Tk::BrowseEntry. Defaults to 1.

-listwidth

If -fixedwidth is set to 0, -listwidth can be used to specify the popup listbox's width.

The following options specify callbacks:

-listcmd

Executed when the listbox is about to be popped up. This is a good place for changes to the -choices.

-entercmd

Executed when the user hits the Return key.

-tabcmd

Executed when the user hits the Tab key.

-zerocmd

Executed when the insert cursor moves back to position 0 in the entry widget (see -onecmd).

-onecmd

Executed when the insert cursor moves to position 1 in the entry widget (i.e. after the first character).

-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.

-command or -browsecmd

Executed when the user has selected an entry from the auto-completion popup-listbox. Provided for compatibility with Tk::BrowseEntry.

METHODS

popup

Pops the auto-completion listbox up if there are enough possible choices. This should only be used if -autopopup is set to 0. As 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.

KEY BINDINGS

Up, Down

Navigates through the auto-completion listbox. Forces the listbox to pop up when used at entry widget cursor position 0 if there are any choices to display.

Tab, Return

Accepts the currently suggested or selected auto-completion. The insert cursor will be placed at the end of the entry widget. The callback -tabcmd or -entercmd will be executed.

Escape

Pressed once it closes the auto-completion listbox if it's open. On pressing it twice the currently auto-completed text will be erased. For example, if you have a choice 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.

NOTES

The -choices are automatically sorted alphabetically.

BUGS/TODO

There should be a way to influence how the choices are sorted.

Execution of the -browsecmd callback needs improvement.

EXAMPLES

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, # -font => "10x16", -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;

AUTHOR

Wolfgang Hommel <wolf (at) code-wizards.com>

SEE ALSO

The following widgets are similar to Tk::MatchEntry to a certain extent:

Tk::BrowseEntry - basic combination of entry and listbox widgets

Tk::HistEntry by Slaven Rezic - excellent readline-like entry widget with basic auto-completion capability.

CREDITS

Thanks to Slaven Rezic for Tk::HistEntry. Some of the auto-completion ideas are based on it.

COPYRIGHT

Copyright (c) 2003 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.

cpanm Tk::MatchEntry

perl -MCPAN -e shell
install Tk::MatchEntry