Widget...omboBox(3pm)

💖 Widget...omboBox(3pm) — Curses::Widgets::ComboBox 💖

okay bestie, sit down, hydrate, because we're talking about Curses::Widgets::ComboBox — a lil Perl module from the User Contributed Perl Documentation corner of the manual. It's giving drop-down-menu realness for your terminal, and honestly? iconic. 🎀

---

🌸 NAME 🌸

Curses::Widgets::ComboBox — Combo-Box Widgets. yes, that's it, that's the whole name. slay.

---

🦋 MODULE VERSION 🦋

$Id: ComboBox.pm,v 1.103 2002/11/03 23:34:50 corliss Exp corliss $

literally the receipts. 💅

---

✨ SYNOPSIS ✨

so here's the vibe — you make one like this:

use Curses::Widgets::ComboBox;

$cb = Curses::Widgets::ComboBox->new({
  CAPTION     => 'Select',
  CAPTIONCOL  => 'yellow',
  COLUMNS     => 10,
  MAXLENGTH   => 255,
  MASK        => undef,
  VALUE       => '',
  INPUTFUNC   => \&scankey,
  FOREGROUND  => 'white',
  BACKGROUND  => 'black',
  BORDER      => 1,
  BORDERCOL   => 'red',
  FOCUSSWITCH => "\t\n",
  CURSORPOS   => 0,
  TEXTSTART   => 0,
  PASSWORD    => 0,
  X           => 1,
  Y           => 1,
  READONLY    => 0,
  LISTITEMS   => [qw(foo bar wop)],
  });

$cb->draw($mwh, 1);

and then, yk, go read the Curses::Widgets pod for all the other methods, because that's where the rest of the lore lives. 📚

---

🫶 REQUIREMENTS 🫶

you're gonna need all of these, no skipping:

• Curses
• Curses::Widgets
• Curses::Widgets::TextField
• Curses::Widgets::ListBox

---

👑 DESCRIPTION 👑

Curses::Widgets::ComboBox gives you simplified OO access to Curses-based combo-boxes. periodt.

here's the tea on how it actually behaves: this widget is basically a text field widget at heart, BUT — and this is the main character moment — when you hit a KEY_DOWN or a "\n", a drop-down list pops up, and whatever item you pick gets dropped right into the text field as the value. it's giving "text field with a secret second personality". 😭

---

💅 METHODS 💅

⭐ new (inherited from Curses::Widgets)

$cb = Curses::Widgets::ComboBox->new({
  CAPTION     => 'Select',
  CAPTIONCOL  => 'yellow',
  COLUMNS     => 10,
  MAXLENGTH   => 255,
  MASK        => undef,
  VALUE       => '',
  INPUTFUNC   => \&scankey,
  FOREGROUND  => 'white',
  BACKGROUND  => 'black',
  BORDER      => 1,
  BORDERCOL   => 'red',
  FOCUSSWITCH => "\t\n",
  CURSORPOS   => 0,
  TEXTSTART   => 0,
  PASSWORD    => 0,
  X           => 1,
  Y           => 1,
  READONLY    => 0,
  LISTITEMS   => [qw(foo bar wop)],
  });

new spins up a brand new ComboBox object for you. and listen — the only mandatory key/value pairs in that config hash are X and Y. everything else is optional and comes with defaults, which I am listing below because I love you:

• CAPTION — default undef — caption superimposed on border
• CAPTIONCOL — default undef — foreground colour for caption text
• COLUMNS — default 10 — number of columns displayed
• MAXLENGTH — default 255 — maximum string length allowed
• MASK — default undef — not yet implemented
• VALUE — default '' — current field text
• INPUTFUNC — default \&scankey — function to use to scan for keystrokes
• FOREGROUND — default undef — default foreground colour
• BACKGROUND — default undef — default background colour
• BORDER — default 1 — display a border around the field
• BORDERCOL — default undef — foreground colour for border
• FOCUSSWITCH — default "\t\n" — characters which signify end of input
• CURSORPOS — default 0 — starting position of the cursor
• TEXTSTART — default 0 — position in string to start displaying
• PASSWORD — default 0 — substitutes '*' instead of characters
• READONLY — default 0 — prevents alteration to content
• LISTLINES — default 5 — number of lines to display at a time in the drop-down list
• LISTCOLUMNS[COLUMNS] — width of the drop-down list; defaults to the same length specified for the CombBox widget
• LISTITEMS — default [] — items listed in drop-down list

some extra notes because details matter, bestie:

• the CAPTION is only valid when the BORDER is enabled. if the border is disabled, the field will be underlined — provided your terminal supports it. 💅
• if MAXLENGTH is undefined, no limit gets placed on the string length. go wild, I guess. 🌈

---

🎀 draw (inherited from Curses::Widgets::TextField)

$cb->draw($mwh, 1);

draw renders the text field in its current state. you must hand it a valid handle to a curses window, because that's where it's gonna render itself. the optional second argument — if it's true — makes the field's text cursor get rendered too. cute, right? ✨

---

🧚 popup

$combo->popup;

popup makes the drop-down list show up. and since, theoretically, that list should never be seen unless somebody's actively using it, we always assume we need to draw a cursor on the list as well. no cap. 🦋

---

📜 HISTORY 📜

• 2001/12/09 — First version of the combo box

the origin story. 🍼

---

💜 AUTHOR/COPYRIGHT 💜

(c) 2001 Arthur Corliss (corliss@digitalmages.com)

---

okay that's the whole page, you ate it, you understood it, you're basically a Curses combo-box sommelier now. 🍓

so like, this was page Widget...omboBox(3pm) from perl v5.34.0, dated 2022-06-12 — and yeah, that's the User Contributed Perl Documentation collection, so go forth and pop up them lists. mwah. 💖👑