NAME

JBrowseEntry is a full-featured "Combo-box" (Text-entry combined with drop-down listbox).

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

OPTIONS

JBrowseEntry supports 5 different states:

normal

-state => 'normal'

Default operation -- Both text entry field and dropdown list button function normally.

readonly

-state => '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

-state => '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

-state => '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

-state => 'disabled'

Widget is completely disabled and greyed out. It will not activate or take focus.

JBrowseEntry supports all the options that BrowseEntry supports with the addition of the following options:

-btntakesfocus

The dropdown list button is normally activated with the mouse and is skipped in the focusing circuit. If this option is set, then the button will take keyboard focus. Pressing <Return>, <Spacebar>, or <Downarrow> will cause the list to be dropped down, repeating causes the list to be removed again. Normally, the text entry widget receives the keyboard focus. This option can be used in combination with "-takefocus" so that either the text entry widget, the button, or both or neither receive keyboard focus. If both options are set, the entry field first receives focus, then pressing <Tab> causes the button to be focused.

-farrowimage

Allows one to specify a second alternate bitmap for the image on the button which activates the dropdown list when the button has the keyboard focus. The default is to use the "-arrowimage" image. This option should only be specified if the "-arrowimage" option is also specified. See the "-arrowimage" option under Standard BrowseEntry options for more details.

-height

Specify the maximum number of items to be displayed in the listbox before a vertical scrollbar is automatically added. Default is infinity (listbox will not be given a scrollbar regardless of the number of items added).

-labelPack

Specify alternate packing options for the label. The default is: "[-side => 'left', -anchor => 'e']". The argument is an arrayref. Note: if no label is specified, none is packed or displayed.

-listfont

Specify an alternate font for the text in the listbox. Use "-font" to change the text of the text entry field. For best results, "-font" and "-listfont" should specify fonts of similar size.

-noselecttext

Normally, when the widget has the focus, the current value is "selected" (highlighted and in the cut-buffer). Some consider this unattractive in appearance, particularly with the "readonly" state, which appears as a raised button in Unix, similar to an "Optionmenu". Setting this option will cause the text to not be selected.

-width

The number of characters (average if proportional font used) wide to make the entry field. The dropdown list will be set the same width as the entry widget plus the width of the button. If not specified, the default is to calculate the width to the width of the longest item in the choices list and if items are later added or removed the width will be recalculated.

Standard BrowseEntry options alsu supported by JBrowseEntry:

-listwidth

Specifies the width of the popup listbox.

-variable

Specifies the variable in which the entered value is to be stored.

-browsecmd

Specifies a function to call when a selection is made in the popped up listbox. It is passed the widget and the text of the entry selected. This function is called after the entry variable has been assigned the value.

-listcmd

Specifies the function to call when the button next to the entry is pressed to popup the choices in the listbox. This is called before popping up the listbox, so can be used to populate the entries in the listbox.

-listrelief

Specifies relief for the dropdown list (default is "sunken").

-maxwidth

Specifies the maximum width the entry and listbox widgets can expand to in characters. The default is zero, meaning expand to the width to accomodate the widest string in the list.

-tabcomplete

If set to "1", pressing the "<Tab>" key will cause the string in the entry field to be "auto-completed" to the next matching item in the list. If there is no match, the typed text is not changed. If it already matches a list item, then the listbox is removed from view and keyboard focus transfers to the next widget. If set to "2" and there is no match in the list, then entry is set to the default value or empty string.

-arrowimage

Specifies the image to be used in the arrow button beside the entry widget. The default is an downward arrow image in the file cbxarrow.xbm

-choices

Specifies the list of choices to pop up. This is a reference to an array of strings specifying the choices.

-state

Specifies one of four states for the widget: "normal", "readonly", "textonly", or "disabled". If the widget is "disabled" then the value may not be changed and the arrow button won't activate. If the widget is "readonly", the entry may not be edited, but it may be changed by choosing a value from the popup listbox. "textonly" means the listbox will not activate. "normal" is the default.

-colorstate

Depreciated -- Appears to force the background of the entry widget on the Unix version to "grey95" if state is normal and a "-background" color is not specified.

Additional options tested and known to work as expected:

-altbinding

Allows one to specify alternate binding schema for certain keys. Currently valid values are "Return=Next" (which causes pressing the [Return] key to advance the focus to the next widget in the main window); and "Down=Popup", which causes the [Down-arrow] key to pop up the selection listbox.

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;