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;

SEE ALSO
   Tk::JComboBox Tk::BrowseEntry Tk::Listbox Tk::Entry

WIDGET-SPECIFIC OPTIONS
   -state => *normal | readonly | text | textonly | disabled*
       Default: normal

       JBrowseEntry supports 5 different states:

           *normal*: Default operation -- Both text entry field and
           drop-down list button function normally.

           *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, 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. If "Tab=Popup" is also specified,
       it implies "KeepList" as well on Unixish systems where the list is
       not "fixed" as this avoids trapping the user in a "tab loop" between
       the text-entry field and the drop-down list. 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. 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, (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.

   -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 -
       drop-down list is not fixed (pre-v5.10 behavior).

   -indicator
       Only used if -listboxtype is set to HListbox, otherwise ignored.
       Specifies whether an indicator image may be included with HListbox
       entries. Default 0 (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.

   -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"*. Default is
       *"Listbox"* (Tk::Listbox). If *"HListbox"* is specified, you must
       have Tk::HListbox (v2.1+) installed or the application will fail
       with an error.

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

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

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

   -listwidth
       Specifies the width of the popup listbox.

   -nobutton
       Whether or not to display the button that toggles the drop-down
       list. Set to 1 to hide. Default 0 (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.

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

   -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. (Ignored if -width > 0
       (a fixed width) is specified).

   -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 METHODS
   $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 "-textvariable" 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() and referenceOnly(). 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->dereferenceOnly(hashkey)
       Returns 1 if the key specified by "hashkey" is one of the valid
       choices and the list of choices is a hash, otherwise undef is
       returned.

   $widget->get_hashref_byname()
       Returns a reference to the current hash of choices (keyed by the
       option visable to the 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
       "-textvariable" 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 "-textvariable" 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
   Copyright (c) 2001-2018 Jim Turner "<mailto:[email protected]>". 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::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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.