| Tk::JBrowseEntry - Full-featured "Combo-box" derived from Tk::BrowseEntry with many additional features and options. |
Tk::JBrowseEntry - Full-featured ``Combo-box'' (Text-entry combined with drop-down listbox) derived from Tk::BrowseEntry with many additional features and options.
use Tk;
use Tk::JBrowseEntry;
my $mw = MainWindow->new;
my $var;
my $widget = $mw->JBrowseEntry(
-label => 'Normal:',
-variable => \$var,
-state => 'normal',
-choices => [qw(pigs cows foxes goats)],
-width => 12
)->pack(
-side => 'top',
-pady => '10',
-anchor => 'w');
MainLoop;
Tk::JBrowseEntry is a derived widget from Tk::BrowseEntry, but adds numerous features and options. Among them are hash lists (one set of values is displayed for the user, but another is used as data), ability to disable either the text entry widget or the listbox, ability to allow user to delete items from the list, additional keyboard bindings, and much more.
JBrowseEntry widgets allow one to specify a full combo-box, a ``readonly'' box (text field allows user to type the 1st letter of an item to search for, but user may only ultimately select one of the items in the list), or a ``textonly'' version (drop-down list disabled), or a completely disabled widget.
This widget is similar to other combo-boxes, ie. JComboBox, but has good keyboard bindings and allows for quick lookup/search within the listbox. pressing <RETURN> in entry field displays the dropdown box with the first entry most closly matching whatever's in the entry field highlighted. Pressing <RETURN> or <SPACE> in the listbox selects the highlighted entry and copies it to the text field and removes the listbox. <ESC> removes the listbox from view. <UP> and <DOWN> arrows work the listbox as well as pressing a key, which will move the highlight to the next item starting with that letter/number, etc. <UP> and <DOWN> arrows pressed within the entry field circle through the various list options as well (unless ``-state'' is set to 'textonly'). Set ``-state'' to ``text'' to disable the dropdown list, but allow <UP> and <DOWN> to cycle among the choices. Setting ``-state'' to 'textonly' completely hides the choices list from the user - he must type in his choice just like a normal entry widget.
One may also specify whether or not the button which activates the dropdown list via the mouse can take focus or not (-btntakesfocus) or whether the widget itself can take focus or is skipped in the focusing order. The developer can also specify alternate bitmap images for the button (-arrowimage and -farrowimage). The developer can also specify the maximum length of the dropdown list such that if more than that number of items is added, a vertical scrollbar is automatically added (-height). A fixed width in characters (-width) can be specified, or the widget can be allowed to resize itself to the width of the longest string in the list. The listbox and text entry field are automatically kept to the same width.
One can optionally specify a label (-label), similar to the ``LabEntry'' widget. By default, the label appears packed to the left of the widget. The positioning can be specified via the ``-labelPack'' option. For example, to position the label above the widget, use ``-labelPack => [-side => 'top']''.
It is easiest to illustrate this widget's capabilities via examples:
use Tk;
use Tk::JBrowseEntry;
$MainWin = MainWindow->new;
#SET UP SOME DEFAULT VALUES.
$dbname1 = 'cows';
$dbname2 = 'foxes';
$dbname3 = 'goats';
$dbname5 = 'default';
#HERE'S A NORMAL COMBO-BOX.
$jb1 = $MainWin->JBrowseEntry(
-label => 'Normal:',
-variable => \$dbname1,
-state => 'normal',
-choices => [qw(pigs cows foxes goats)],
-width => 12);
$jb1->pack(
-side => 'top', -pady => '10', -anchor => 'w');
#THIS ONE HAS THE DROPDOWN LIST DISABLED.
$jb2 = $MainWin->JBrowseEntry(
-label => 'TextOnly:',
-variable => \$dbname2,
-state => 'text',
-choices => [qw(pigs cows foxes goats)],
-width => 12);
$jb2->pack(
-side => 'top', -pady => '10', -anchor => 'w');
#THIS ONE'S "READONLY" (USER MUST PICK FROM THE LIST, TEXT BOX ALLOWS QUICK
#SEARCH.
$jb3 = $MainWin->JBrowseEntry(
-label => 'ReadOnly:',
-variable => \$dbname3,
-choices => [qw(pigs cows foxes goats)],
-state => 'readonly',
-width => 12);
$jb3->pack(
-side => 'top', -pady => '10', -anchor => 'w');
#THIS ONE'S COMPLETELY DISABLED!
$jb4 = $MainWin->JBrowseEntry(
-label => 'Disabled:',
-variable => \$dbname3,
-state => 'disabled',
-choices => [qw(pigs cows foxes goats)],
-width => 12);
$jb4->pack(
-side => 'top', -pady => '10', -anchor => 'w');
#HERE'S ONE WITH A SCROLLBAR (NOTE THE "-height" ATTRIBUTE).
$jb5 = $MainWin->JBrowseEntry(
-label => 'Scrolled List:',
-width => 12,
-default => $dbname5,
-height => 4,
-variable => \$dbname5,
-browsecmd => sub {print "-browsecmd!\n";},
-listcmd => sub {print "-listcmd!\n";},
-state => 'normal',
-choices => [qw(pigs cows foxes goats horses sheep dogs cats ardvarks default)]);
$jb5->pack(
-side => 'top', -pady => '10', -anchor => 'w');
#HERE'S ONE THAT THE BUTTON TAKES KEYBOARD FOCUS.
$jb6 = $MainWin->JBrowseEntry(
-label => 'Button Focus:',
-btntakesfocus => 1,
-arrowimage => $MainWin->Getimage('balArrow'), #SPECIFY A DIFFERENT BUTTON IMAGE.
-farrowimage => $MainWin->Getimage('cbxarrow'), #OPTIONAL 2ND IMAGE FOR BUTTON WHEN FOCUSED.
-width => 12,
-height => 4,
-variable => \$dbname6,
-browsecmd => sub {print "-browsecmd!\n";},
-listcmd => sub {print "-listcmd!\n";},
-state => 'normal',
-choices => [qw(pigs cows foxes goats horses sheep dogs cats ardvarks default)]);
$jb6->pack(
-side => 'top', -pady => '10', -anchor => 'w');
#HERE'S ONE THAT DOWS NOT TAKE KEYBOARD FOCUS.
$jb7 = $MainWin->JBrowseEntry(
-label => 'Skip Focus:',
-takefocus => 0,
-width => 12,
-height => 4,
-variable => \$dbname7,
-browsecmd => sub {print "-browsecmd!\n";},
-listcmd => sub {print "-listcmd!\n";},
-state => 'normal',
-choices => [qw(pigs cows foxes goats horses sheep dogs cats ardvarks default)]);
$jb7->pack(
-side => 'top', -pady => '10', -anchor => 'w');
$jb7->choices([qw(First Second Fifth Sixth)]); #REPLACE LIST CHOICES!
$jb7->insert(2, 'Third', 'Fourth'); #ADD MORE AFTER 1ST 2.
$jb7->insert('end', [qw(Seventh Oops Eighth)]); #ADD STILL MORE AT END.
$jb7->delete(7); #REMOVE ONE.
$b = $MainWin->Button(-text => 'Quit', -command => sub {exit(); });
$b->pack(-side => 'top');
$jb1->focus; #PICK ONE TO START WITH KEYBOARD FOCUS.
MainLoop;
the Tk::JComboBox manpage the Tk::BrowseEntry manpage the Tk::Listbox manpage the Tk::Entry manpage
JBrowseEntry supports 5 different states:
normal: Default operation -- Both text entry field and dropdown list button function normally.
readonly: Dropdown list functions normally. When text entry field has focus, user may type in a letter, and the dropdown list immediately drops down and the first/ next matching item becomes highlighted. The user must ultimately select from the list of valid entries and may not enter anything else.
text: Text entry functions normally, but dropdown list button is disabled. User must type in an entry or use the up and down arrows to choose from among the list items.
textonly: Similar to ``text'': Text entry functions normally, but dropdown list button is disabled. User must type in an entry. The list choices are completely hidden from the user.
disabled: Widget is completely disabled and greyed out. It will not activate or take focus.
Allow relief of the label portion of the widget to be specified.
Prevents dropdown list button from being displayed.
activate() invokes the activate() option on the listbox to make the item with the
index specified by the first argument ``active''. Unless a second argument is
passed containing a false value, the value of the ``-textvariable'' variable is also
set to this now active value.
dereference() and
dereferenceOnly().
get() with no arguments returns the current value of the ``-textvariable'' variable.
If any arguments are passed, they are passed directly to the listbox->get()
function, ie. ``0'', ``end'' to return all values of the listbox.
get() of
the value specified by ``hashkey''.
index() function.
get() function are the corresponding
hash key(s).
size() function (the number of items in
the list.
Jim Turner, <http://home.mesh.net/turnerjw/jim>
Copyright 2001-2011 (c) Jim Turner <http://home.mesh.net/turnerjw/jim>. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
This is a derived work from Tk::BrowseEntry. Tk::BrowseEntry is copyrighted by Rajappa Iyer
| Tk::JBrowseEntry - Full-featured "Combo-box" derived from Tk::BrowseEntry with many additional features and options. |