BrowseEntry(3pm)

💖 BrowseEntry — the Tk module where your entry widget gets a lil popup menu of choices 💖

okay bestie, so this is BrowseEntry, a Perl/Tk module. It's the manual page for Tk::BrowseEntry, and it's literally an entry widget that has a popup list of choices attached. ComboBox vibes, but make it Perl. Let's get into it 💅

---

✨ NAME ✨

Tk::BrowseEntry — an entry widget with popup choices. That's the whole thing. Entry. Popup. Choices. Iconic.

---

🌸 SYNOPSIS 🌸

here's how you actually use it, no cap:

use Tk::BrowseEntry;

$b = $frame->BrowseEntry(-label => "Label", -variable => \$var);
$b->insert("end", "opt1");
$b->insert("end", "opt2");
$b->insert("end", "opt3");
...
$b->pack;

so you construct it off a $frame, you shove your options in with insert, and then you pack it like the main character it is. the ... is you adding as many as you want btw, go off 🦋

---

👑 SUPER-CLASS 👑

BrowseEntry is derived from the Frame class, so it inherits all the methods, options and subwidgets of its super-class. full inheritance moment. ✨

and here's the cute part: by default, options and methods are delegated to the entry subwidget. so it acts like an entry unless you say otherwise. lowkey genius.

---

💖 DESCRIPTION 💖

BrowseEntry is a poor man's ComboBox. that's the official wording and honestly? we respect the honesty.

you can think of it as an enhanced version of LabEntry — it gives you a button that pops up the possible values your Entry can take. it supports all the options LabEntry supports, except -textvariable. that one got replaced by -variable instead. noted. 📝

and here are the other options it supports, one by one, because we are not skipping a single one:

• -arrowimage — specifies the image used in the arrow button sitting beside the entry widget. the default is a downward arrow image in the file cbxarrow.xbm. 🏹
• -autolimitheight — if you set this to a true value, the height of the listbox will be at most the number of entries in the list. the overall maximum of -listheight still applies tho, so don't get it twisted.
• -autolistwidth — if set to a true value, the width of the listbox will match the width of the largest entry. size-matching queen ✨
• -browsecmd — specifies a function to call when a selection is made in the popped up listbox. it's passed the widget and the text of the entry selected. important detail: this function is called after the entry variable has been assigned the value. so the value's already there, okay?
• -browse2cmd — like -browsecmd, but the callback is called with the listbox index instead of the selected value. same energy, different argument.
• -buttontakefocus — sets the -takefocus option of the button subwidget. that's it, that's the option.
• -choices — specifies the list of choices to pop up. this is a reference to an array of strings specifying the choices. 🍓
• -colorstate — the state of the widget is reflected by color. a non-editable entry widget will get a light gray background, while an editable entry will be almost white. [This may change] — yes that bracket is literally in the original, we're keeping it, we don't make the rules 💀
• -listcmd — specifies the function to call when the button next to the entry is pressed to popup the choices in the listbox. it's called before popping up the listbox, so you can use it to populate the entries in the listbox. perfect little pre-game hook 🎀
• -listheight — sets the height of the listbox. see also -autolimitheight.
• -listwidth — specifies the width of the popup listbox.
• -state — specifies one of three states for the widget: normal, readonly, or disabled.
  • if the widget is disabled, the value may not be changed and the arrow button won't activate. it's just... sitting there. 🙈
  • if the widget is readonly, the entry may not be edited, but it may be changed by choosing a value from the popup listbox. read-only not read-never, bestie.
  • normal is the default.
• -style — sets the style of the widget. permitted values are MSWin32 and unix. by default -style is set to the current platform. widgets with the unix style will look like a normal BrowseEntry widget, whereas with the MSWin32 style the arrow will look close to the Windows' standard combobox widget, while moving the mouse the entries will be highlighted, and probably includes other changes. (yes, "probably" — we're quoting, not guessing. 🔥)
• -variable — specifies the variable in which the entered value is to be stored. this is the one that replaced -textvariable, remember?

---

🌈 METHODS 🌈

• insert(index, string) — inserts the text of string at the specified index. this string then becomes available as one of the choices. boom, new option in the dropdown ✨
• delete(index1, index2) — deletes items from index1 to index2. bye bestie 👋
• get — the get method is delegated to the choices listbox. so when you call it, you're really talking to the listbox, not the entry. iykyk.

---

🦋 ADVERTISED WIDGETS 🦋

the following widgets are advertised (that's Tk-speak for "you can reach in and grab these by name"):

• entry — the entry widget.
• arrow — the button with the arrow image. 🏹
• choices — the toplevel widget containing the choice listbox.
• slistbox — the scrolled listbox with the choices.

---

💜 SUBCLASSING 💜

to make subclassing easier, the following methods may be overridden so you can use other standard widgets when composing the mega widget:

• LabEntryWidget — a widget class compatible with Tk::LabEntry, used for the entry.
• ButtonWidget — a widget class compatible with Tk::Button, used for the arrow button.
• ListboxWidget — a widget class compatible with Tk::Listbox, used for the choices listbox.

for example, to use a NumEntry widget (from the Tk-GBARR CPAN distribution) instead of the normal Entry widget:

package Tk::NumBrowseEntry;
use base qw(Tk::BrowseEntry);
use Tk::NumEntry;
Construct Tk::Widget 'NumBrowseEntry';
sub LabEntryWidget { "NumEntry" }

literally just swap the widget class and you're done. slay 🎀

---

💀 BUGS 💀

BrowseEntry should really provide more of the ComboBox options. that's the entire bug report. they said it, not me. 😭

---

🌸 AUTHOR 🌸

• Rajappa Iyer — rsi@earthling.net
• Chris Dean — ctdean@cogit.com made additions.
• More additions by Slaven Rezic — slaven@rezic.de

this code was inspired by ComboBox.tcl in Tix4.0 by Ioi Lam and bears more than a passing resemblance to ComboBox code. and — important, so listen up — this may be distributed under the same conditions as Perl. 🫶

---

quick reminder bestie: everything above is straight from the docs, we just gave it a glow-up. no facts were harmed, invented, or merged in the making of this page. 💅

and that's the whole page!! this one shipped as part of perl v5.40.1, dated 2025-04-13. go forth and pop up some choices, you absolute icon 👑✨🎀