NAME

Tk::JBrowseEntry - Full-featured "Combo-box" (Text-entry combined with drop-down listbox) derived from Tk::BrowseEntry with many additional features and options.

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

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, ability to have the drop-down list "fixed" (always displayed, ability to use Tk::HListbox, ie. to include thumbnail icons in the list), customized key bindings and behaviour, 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); a "textonly" version (drop-down list and list pattern-matching disabled); a "text" version (drop-down list disabled), but the up, down, and right arrows will still do text-completion by matching against the choices in the list; or a completely disabled widget.

This widget is similar to other combo-boxes, ie. JComboBox, but has better keyboard bindings and allows for quick lookup/search within the listbox. pressing <RETURN> in entry field displays the drop-down 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 drop-down 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 drop-down 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 / or -farrowimage). The developer can also specify the maximum length of the drop-down 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 DROP-DOWN 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;

readonly: Drop-down list functions normally. When text entry field has focus, user may type in a letter, and the drop-down 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 drop-down 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 drop-down 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.

-altbinding

Allows one to specify alternate binding schema for certain keys. Each binding pair may be separated by a comma, semicolon, colon, space, or virtical bar. Case is insensitive. Currently valid values are:

"Return=Go" - causes [Return] key to roll up the drop-down list and invoke the -browsecmd callback, if any.

"Return=NonEmptyGo" - same as "Return=Go" if the text field is non-empty, otherwises pops up the drop-down list.

"Return=SingleGo" - same as "Return=Go" if there are no choices in the drop-down list (instead of popping up the drop-down list).

"Return=Next" - causes pressing the [Return] key to advance the focus to the next widget in the main window.

"Right=NoSearch" - Do not complete the text in the text field with the next matching value found in the choices list when the [Right-arrow] key is pressed in the entry field, rather leave it unchanged.

"Down=Popup" - causes the [Down-arrow] key pressed in the entry field to pop up the selection listbox. Useful particularly if the [arrow-button] isn't displayed, ie. (-nobutton => 1) and/or the [Return] key is bound with an -altbinding, etc. to do something other than pop up the drop-down list.

"List=Bouncy" - causes the drop-down list to behave more like a popup menu and immediately roll back up (after matching text with nearest entry) if the mouse button is pressed and released on the drop-down list button. (Normally, the drop-down list state is simply toggled when mouse is pressed and released on the button.)

"Nolistbox=actions" - causes certain actions to NOT invoke the -browsecmd callback when activated within the listbox widget, ie. "Nolistbox=listbox.space" means don't invoke -browsecmd callback if <spacebar> pressed in the listbox. Valid values are ([listbox.]{space|return|button1|*button1|mod[.{shift|Control|alt|*}-]button1}: "space,button1,return,mod.Shift-button1,mod.Control-button1,mod.Alt-button1,mod,*button1", etc. Multiple values can be separated by commas. "mod" means any modifier (Shift|Control|Alt), "*button1" means button1 regardless of modifier.

"Tab=KeepList" - Normally, if the [Tab] key is pressed while the drop-down list is displayed and focused, the drop-down list is removed from view (rolled up) and the focus simply returns to the text entry field.

Specifying "Tab=KeepList" (on Unixish systems) makes Tk::JBrowseEntry keep the drop-down list displayed while returning the focus back to the text field when either tabbing off of the listbox or selecting an entry via the spacebar key. To roll the listbox back up (unless -fixedlist is specified), simply press the Enter or Tab key, or click on the entry-field.

"Tab=Popup" - Normally, if the [Tab] key is pressed while the text-entry field is displayed and focused, the focus advances to the next widget.

Specifying "Tab=Popup" will cause the listbox to be popped up and receive the focus. Either way, the listbox is undisplayed anyway when the JBrowseEntry widget itself goes out of focus, or either the [Enter] or [Esc] key is pressed. If the drop-down list is a "fixed" list (-fixedlist is specified), then the list always remains in view and only the focus changes and this setting is ignored. This setting is also ignored on M$-Windows platforms, which is beyond our control.

"Down=None", "Up=None", "Right=None", "Esc=None", "Return=None", "Space=None" - causes pressing that respective key to NOT perform it's default binding action. User can still add their own bindings within their calling program though.

-arrowimage

Allows one to specify an alternate image for the the button which activates the drop-down list when the button has the keyboard focus. The default is: $MainWin->Getimage('cbxarrow') on Linux and a custom bitmap on M$-Windows. Also see the "-farrowimage" option below, as well as the "-arrowimage" option under Standard BrowseEntry options for more details. On Linux, this is used regardless of the focus status of the button, which is indicated by the border, unless a "-farrowimage" image is specified. On M$-Windows, a separate custom bitmap is provided for the focused version, since Windows does not change the border color when the button takes focus.

-browse

Adds several additional triggering events which invoke the -browsecmd callback: entry.tab, frame.tab, and key.<character-typed>, if set to 1. Default is 0. This likely is rarely needed in practice, but allows the calling program to know whenever a key is typed into the entry field or if the field is tabbed away from. The one case the author uses this option on is the "drive-letter" field in the M$-Windows version of his Tk::JFileDialog widget.

-browsecmd

Specifies a callback function to call when a selection is made in the popped up listbox. This function is called after the entry variable has been assigned the value, (so the programmer can validate and override the user's entry if desired).

The function is passed the widget reference itself (self), the content of the entry field (not necessarily equal to the -variable reference value), and the triggering "event" as described below.

Specific cases (events) where it is invoked: entry.[-mod.{Shift|Control|Alt}]return[.{go|browse}], listbox.return, listbox.space, or listbox.[-mod.{Shift|Control|Alt}]button1. If -browse is set to 1, then additional triggering events are: entry.tab, frame.tab, and key.<character-typed>.

-btntakesfocus

The drop-down 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.

-buttonbackground

Specify alternate background for the drop-down list button.

-buttonforeground

Specify alternate foreground for the drop-down list button.

-colorstate

Archaic carryover from Tk::BrowseEntry -- Appears to force the background of the text-entry widget to "lightgray" if set to "1" and state is readonly or disabled, and no -background color has been set; and a slightly darker shade of gray ("gray95 ") otherwise. We also set the foreground color to gray30 for readonly or disabled states and black otherwise to ensure that the text remains readable regardless of what foreground color is otherwise set. I've also added special value of "2" (or "dark") to set a darker version of the readonly and disabled colors. To only make one or the other use the "darker" shades, one can instead specify "readonlydark" or "disableddark". NOTE: Once the widget has been set to a "readonly" state, the "-textreadonlybackground" color remains fixed thru future calls to setPalette! This seems to be a limitation of Tk and setPalette. Also note that in general, changing the widget's -foreground and / or -background options later via "$widget->configure() may not completely change all the colors of every part of every subwidget, and setPalette may not completely correct everything until the widget's -state is changed, therefore, it's a good idea to also call $w->state($w->state()); after dynamically changing foreground or background colors for the widget.

-default

(string) - If set, it becomes the default value, ie. if the user presses the Esc (escape) key inside the text box (pressing Esc a second time blanks out the field unless -state == 'readonly'). It's recommended to set this to either the -variable variable (the variable itself, not it's reference) or to a string representing one of the values in the dropdown listbox, to avoid possibly confusing users.

NOTE: The initial value set in the text field will be whatever's in the -variable, NOT the -default value unless -variable is not defined! If neither option is defined, the initial value will be empty string ('').

-deleteitemsok

If set, allows user to delete individual items in the drop-down list by pressing the <Delete> key to delete the current (active) item. No effect if the state is "text" or "textonly".

-deletecmd

(ADDED v4.9): Specifies a callback function to call when the user deletes an entry (if -deleteitemsok is set to true) in the popped up listbox. It is passed the widget and either the index of the entry being deleted OR -1. This function is called BOTH before AND after the entry is deleted. The entry parameter is -1 on the second call, and the first call if $_[1] (the index to be deleted) >= 0, the function should return false/undef to permit the delete or true to SUPPRESS the delete (in which case, the callback will NOT be called a second time)! No effect if the state is "text" or "textonly".

-farrowimage

Allows one to specify a second, alternate bitmap for the image on the button which activates the drop-down list when the button has the keyboard focus. The default is to use the "-arrowimage" image, EXCEPT in M$-Windows, in which case, the default remains the default "focused" bitmap, since Windows does not use a focus border, but rather, the image itself must change to indicate focus status. See the "-arrowimage" option under Standard BrowseEntry options for more details. The default image for Linux is: $MainWin->Getimage('cbxarrow') and a custom bitmap for M$-Windows.

-fixedlist

Normally the drop-down list pops up and down when requested, rolling up (hiding) when not. Setting this option to a true value will cause the drop-down list to be a fixed listbox widget packed below the rest of the widget. Specifying -fixedlist => "top" will instead display the listbox above the rest of the widget.

Default: 0 (false) - drop-down list is not fixed (pre-v5.10 behavior).

NOTE: A list can be set to both "fixed" (-fixedlist = ...>) and "bouncy" (-altbinding = 'list=bouncy'>) at the same time. This will ensure that the focus always jumps right back to the text field whenever the user selects an entry from the list. Otherwise, "fixed" lists alternate focus between the list and the entry field when the user clicks on the list to select a value, as if the list is alternating between "popped down" and "popped up" - this is not considered a bug, but a feature.

-indicator

Only used if -listboxtype is set to HListbox, otherwise ignored. Specifies whether an indicator image may be included with HListbox entries.

Default: 0 (false - no indicator image).

-itemtype

Only used if -listboxtype is set to HListbox, otherwise ignored. Specifies the type of data permitted for HListbox entries. Valid values are: "text", "image", and "imagetext".

Default: "text".

-label

Specify a label to be displayed next to the widget. The default is undef - do not display (or pack) a label next to the widget. If you do not wish to specify a label initially, but plan to set a label later, you should set -label to ''. By default the label is displayed to the left of the widget (as part of it). This can be changed using the -labelPack option.

-labelbackground

Specify alternate background for the label.

-labelforeground

Specify alternate foreground for the label.

-labelfont

Specify alternate font for the label.

NOTE: To change the font for the text entry field, use -font. See also -listfont below for changing the font of the items in the listbox.

-labelPack

Specify alternate packing options for the label. The default is: "[-side => 'left', -anchor => 'e']" ("[-side => 'left', -anchor => 'n'|'s', -pady => 1, -ipady => 2] if -fixedlist is set ('s' if 'top', 'n' otherwise)). The argument is an arrayref. Note: if no label is specified, none is packed or displayed, therefore, if you do not wish to specify a label initially, but plan to set a label later, you should set -label to ''.

-labelrelief

Default: "flat"

Allow relief of the label portion of the widget to be specified.

-listboxtype

Specifies tye type of listbox widget to use for the drop-down list. Valid values are "Listbox" and "HListbox". If "HListbox" is specified, you must have Tk::HListbox (v2.1+) installed or the application will fail with an error.

Default: "Listbox" (Tk::Listbox).

-listcmd

Specifies a callback 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. It passes the widget itself, and now also passes in the current value string in the text-entry field (when the list was popped up).

Default: none (no callback function)

-listfont

Specify an alternate font for the text in the listbox.

NOTE: Use -font to change the text of the text entry field. For best results, -font and -listfont should usually specify fonts of similar size.

-listrelief

Specifies relief for the drop-down list (default is "sunken").

-listwidth

Specifies the width of the popup listbox.

Default: The same width (including any scrollbar) as the text entry field's width.

-nobutton

Whether or not to display the button that toggles the drop-down list. Set to 1 (true) to hide.

Default: 0 (false - display the button).

Prevents drop-down list button from being displayed if set to 1 (true).

-noselecttext

Normally, when the widget has the focus and is set by listbox selection, the text will then be "selected" (highlighted and in the cut-buffer), and will not "appear" to be selected in the drop-down listbox, if visible. Some consider this annoying. Setting this option will cause the text to not be selected, but will still appear selected in the drop-down listbox (if visible). The user can still select the text themself, but either way, the selected item is in the cut buffer.

-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 reset to the default value or empty string. If set to "0", focus is simply advanced to the next widget in the main window. In either case, if the text field is changed, focus remains on the text field, otherwise focus advances to next widget, so, after completing, pressing [Tab] again advances to next widget. (NEW in v5.30): If set to 3, then tab-completion will only occur when tabbing off of a focused and visible listbox.

-textbackground

Specify alternate background for the entry field (when editable).

-textforeground

Specify alternate foreground for the entry field (when editable).

-textdisabledbackground

Specify alternate background for the entry field (when -state is disabled).

-textdisabledforeground

Specify alternate foreground for the entry field (when -state is disabled).

Default: -disabledforeground or a dark grey.

-textreadonlybackground

Specify alternate background for the entry field (when -state is readonly).

-textreadonlyforeground

Specify alternate foreground for the entry field (when -state is readonly).

Default: a light gray.

INHERITED OPTIONS

-activestyle

Specifies the style in which to draw the active element. This must be one of dotbox (show a focus ring around the active element), none (no special indication of active element) or underline (underline the active element). The default is underline. Ignored (not supported) if -listboxtype is set to HListbox, in which case, "dotbox" is always used.

-background

Specifies the background color for the widget and it's subwidgets. NOTE: In general, changing the widget's -foreground and / or -background options later via "$widget->configure() may not completely change all the colors of every part of every subwidget, and setPalette may not completely correct everything until the widget's -state is changed, therefore, it's a good idea to also call $w->state($w->state()); after dynamically changing foreground or background colors for the widget.

-choices

Specifies the list of initial choices to pop up. This is a reference to an array or hash of strings specifying the choices. If a hashref is specified, the keys represent the actual data values and the values represent the corresponding values the user sees displayed in the listbox. NOTE: If a hashref is specified, the -variable should be initialized to one of the hash VALUES rather than it's corresponding key. The individual items in the referenced array are normally simple text strings unless -listboxtype is set to "HListbox", in which case, each can be either a simple text string or a hashref to a hash of attributes and values representing a valid Tk::HListbox entry, for example: {-image => $thumbnailimage, -text => 'text string'}.

-foreground

Specifies the foreground color for the widget and it's subwidgets.

-height

Specify the maximum number of items (rows) 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).

NOTE: This can overflow below the user's screen, so it is recommended to set this to a sane value to cause a scrollbar to be added automatically if needed, if there are going to be potentially say a dozen or more items.

-maxwidth

Specifies the maximum width the entry and listbox widgets can expand to in characters. Default is 0 (zero), meaning expand to the width to accomodate the widest string in the list. (Ignored if -width > 0 (a fixed width) is specified).

-textvariable

Depreciated - use -variable now.

-variable

Specifies a scalar reference to the variable in which the entered value is to be stored/retrieved (tied).

-width

The number of characters (average if proportional font used) wide to make the entry field. The drop-down 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.

$widget->activate(index): 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 "-variable" variable is also set to this now active value.
$widget->choices([listref]): Sets the drop-down list listbox to the list of values referenced by listref, if specified. Returns the current list of choices in the listbox if no arguments provided. If a hashref is specified, the keys represent the actual data values and the values represent the corresponding values the user sees displayed in the listbox. NOTE: If a hashref is specified, the -variable should be initialized to one of the hash VALUES rather than it's corresponding key. The individual items in the referenced array are normally simple text strings unless -listboxtype is set to "HListbox", in which case, each can be either a simple text string or a hashref to a hash of attributes and values representing a valid Tk::HListbox entry, for example: {-image => $thumbnailimage, -text => 'text string'}.
$widget->curselection(): Returns the currently-selected element in the listbox, if any, otherwise, undef.
$widget->delete(first [, last]): Deletes one or more elements of the listbox. First and last are indices specifying the first and last elements in the range to delete. If last isn't specified it defaults to first, i.e. a single element is deleted.
$widget->delete_byvalue(hashkey): Deletes one or more elements of the listbox. "hashkey" specifies the element to be deleted by the value visible to the user.
$widget->reference(hashkey): Returns the value (displayed in the listbox) that corresponds to the choice key specified by "hashkey". If the key is not one of the valid choices or the choices are a list instead of a hash, then the hashkey itself is returned. If the choices are a list rather than a hash, then the value is returned as is. Returns undef on error.
$widget->dereference(hashvalue): Returns the actual option key value that corresponds to the choice value displayed in the listbox. (undef if there is none). (Opposite of reference(). Use this function on the -variable reference variable to get the actual data (hash key), since the reference variable will contain the VALUE displayed to the user! If the choices are a list rather than a hash, then the value is returned as is. Returns undef on error.
$widget->get_hashref_byname(): Returns a reference to the current hash of choices (keyed by the option visable tothe user) if the choice list is a hash (reversed from the hash passed to choices()), otherwise, undef is returned.
$widget->get_hashref_byvalue(): Returns a reference to the current hash of choices (keyed by actual option value) if the choice list is a hash (same as the hash passed to choices()), otherwise, undef is returned.
$widget->get([first [, last]]): get() with no arguments returns the current value of the "-variable" variable. If any arguments are passed, they are passed directly to the listbox->get() function, ie. "0", "end" to return all text values of the listbox. For choice hashes, the value returned is what is displayed to the user. If Tk::HListbox is used, only the text part of the entries are returned. The arguments are indices.
$widget->get_icursor([index]): Return the location of index in the text-entry field. Values known to be valid are: "insert" and "end", which return the character position of the insertion cursor and the location of the "end" of the current input string (ie. it's length). The cursor is set by the $widget->icursor function. If no argument (index) is given, the index of the insertion cursor ("insert") is returned.
$widget->get_index(value): Returns the index number in the list (zero-based) that can be used by get() of the value specified by "value", or undef if "value" is not in the list of choices. If the choice list is a hash, then "value" should be the value displayed (stored in the -variable reference variable), not the hash key. This function is the reverse of the get() function.
$widget->hasreference(hashkey): Returns the value (displayed in the listbox) that corresponds to the choice key specified by "hashkey". If the key is not one of the valid choices or the choices are a list instead of a hash, then undef is returned.
$widget->icursor(index): Sets the location of the text-entry field's text cursor to index. Valid values are numeric (zero for beginning) and "end" for placing the cursor at the end of the text. The index can be retrieved by using the $widget->get_icursor(index) function.
$widget->index(index): Invokes and returns the result of the listbox->index() function.
$widget->insert(index, [item | list | listref | hashref]): Inserts one or more elements in the list just before the element given by index. If index is specified as "end" then the new elements are added to the end of the list. List can be a reference to a list (listref). If a hash reference is specified, then the values are displayed to the user in the drop-down list, but the values returned by the "-variable" variable or the get() function are the corresponding hash key(s). The individual items in the referenced array are normally simple text strings unless -listboxtype is set to "HListbox", in which case, each can be either a simple text string or a hashref to a hash of attributes and values representing a valid Tk::HListbox entry, for example: {-image => $thumbnailimage, -text => 'text string'}.
$widget->selectionRange(index1, index2): Select (highlight) the text in the text-entry field between index1 and index2. Valid values are numeric (zero for beginning), "insert" and "end".
$widget->size(): Invokes and returns the result of the listbox size() function (the number of items in the list).
$widget->state([normal | readonly | text | textonly | disabled]): Get or set the state of the widget.
$widget->Popdown([nofocusrestore]): Roll up (undisplay) the drop-down list. If nofocusrestore is specified and is true, no attempt will be made to refocus the previous widget focused when the drop-down list was popped up. This is useful when the developer intends to immediately focus somewhere else.
$widget->PressButton([nofocussave]): Activates drop-down list as if user pressed the button (unless state is "text" or "textonly" or "disabled". Returns 1 if drop-down list activated, zero otherwise. If the drop-down list is already visible, then removes it (pops it back down) and returns zero.Available in versions 5.0 and later. The current keyboard focus is saved for restoration when the drop-down list is rolled up unless nofocussave is specified and is true, in which case, focus will remain with the JBrowseEntry widget whose button was "pressed".

AUTHOR

Jim Turner, <https://metacpan.org/author/TURNERJW>.

COPYRIGHT

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::Listbox and Tk::HList.

This code may be distributed under the same conditions as Perl itself.

This is a derived work from Tk::BrowseEntry. Tk::BrowseEntry is copyrighted by Rajappa Iyer

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

To install Tk::JBrowseEntry, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Tk::JBrowseEntry

CPAN shell

perl -MCPAN -e shell
install Tk::JBrowseEntry

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

EXAMPLES

SEE ALSO

WIDGET-SPECIFIC OPTIONS

INHERITED OPTIONS

WIDGET METHODS

AUTHOR

COPYRIGHT

LICENSE AND COPYRIGHT

NAME

SYNOPSIS

DESCRIPTION

EXAMPLES

SEE ALSO

WIDGET-SPECIFIC OPTIONS

INHERITED OPTIONS

WIDGET METHODS

AUTHOR

COPYRIGHT

LICENSE AND COPYRIGHT

Module Install Instructions