NAME

Tk::JBrowseEntry - Full-featured "Combo-box" (Text-entry combined with drop-down listbox.

SYNOPSIS

        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;

DESCRIPTION

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']".

EXAMPLES

 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;