Widgets::ListBox(3pm)

💖 NAME 💖

Curses::Widgets::ListBox — List Box Widgets, bestie. That's the whole vibe. 👑

---

🌈 MODULE VERSION 🌈

$Id: ListBox.pm,v 1.104 2002/11/14 01:20:28 corliss Exp corliss $

no cap, that's the version string, keep it safe 🫶

---

✨ SYNOPSIS ✨

okay so this is how you actually summon one:

use Curses::Widgets::ListBox;

$lb = Curses::Widgets::ListBox->new({
  CAPTION     => 'List',
  CAPTIONCOL  => 'yellow',
  COLUMNS     => 10,
  LINES       => 3,
  VALUE       => 0,
  INPUTFUNC   => \&scankey,
  FOREGROUND  => 'white',
  BACKGROUND  => 'black',
  SELECTEDCOL => 'green',
  BORDER      => 1,
  BORDERCOL   => 'red',
  FOCUSSWITCH => "\t",
  X           => 1,
  Y           => 1,
  TOPELEMENT  => 0,
  LISTITEMS   => [@list],
  });

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

then like… go read the Curses::Widgets pod for the other methods, because there's more where that came from 💅

---

🎀 REQUIREMENTS 🎀

• Curses
• Curses::Widgets

you need both, fr fr. no skipping.

---

🦋 DESCRIPTION 🦋

Curses::Widgets::ListBox gives you simplified OO access to Curses-based single-select and multi-select list boxes. literally that's the whole job. and the way each object maintains its own state information?? obsessed. every single one is its own little main character with its own state. 💖

---

👑 METHODS 👑

🌸 new (inherited from Curses::Widgets)

$tm = Curses::Widgets::ListBox->new({
  CAPTION     => 'List',
  CAPTIONCOL  => 'yellow',
  COLUMNS     => 10,
  LINES       => 3,
  VALUE       => 0,
  INPUTFUNC   => \&scankey,
  FOREGROUND  => 'white',
  BACKGROUND  => 'black',
  SELECTEDCOL => 'green',
  BORDER      => 1,
  BORDERCOL   => 'red',
  FOCUSSWITCH => "\t",
  X           => 1,
  Y           => 1,
  TOPELEMENT  => 0,
  LISTITEMS   => [@list],
  });

the new method instantiates a new ListBox object. and bestie, listen — the only mandatory key/value pairs in that config hash are X and Y. everything else? optional, they've all got defaults waiting for you like the loyal besties they are:

• CAPTION — default undef — Caption superimposed on border
• CAPTIONCOL — default undef — Foreground colour for caption text
• COLUMNS — default 10 — Number of columns displayed
• LINES — default 3 — Number of lines in the window
• INPUTFUNC — default \&scankey — Function to use to scan for keystrokes
• FOREGROUND — default undef — Default foreground colour
• BACKGROUND — default undef — Default background colour
• SELECTEDCOL — default undef — Default colour of selected items
• BORDER — default 1 — Display a border around the field
• BORDERCOL — default undef — Foreground colour for border
• FOCUSSWITCH — default "\t" — Characters which signify end of input
• TOPELEMENT — default 0 — Index of element displayed on line 1
• LISTITEMS — default [] — List of list items
• MULTISEL — default 0 — Whether or not multiple items can be selected
• TOGGLE — default "\n\s" — What input toggles selection of the current item
• VALUE — default 0 or [] — Index(es) of selected items
• CURSORPOS — default 0 — Index of the item the cursor is currently on

the CAPTION is only valid when the BORDER is enabled. if the border is disabled, the field will be underlined — provided the terminal supports it. so like, vibe check your terminal first 🫶

and about VALUE: it should be an array reference when you're in multiple selection mode. otherwise it should either be undef or an integer. periodt. ✨

---

💅 draw

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

the draw method renders the list box in its current state. it needs a valid handle to a curses window to render itself into — non-negotiable, that's the whole stage. 🎭

the optional second argument, if it's true, will also cause the field's text cursor to be rendered. cute little bonus. 😌

---

💀 HISTORY 💀

• 1999/12/29 — Original list box widget in functional model
• 2001/07/05 — First incarnation in OO architecture

look at the glow-up. we love an evolution arc. 🦋✨

---

🌟 AUTHOR/COPYRIGHT 🌟

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

---

and that's a wrap, bestie 🎀 this was Widgets::ListBox(3pm), generated by perl v5.34.0 on 2022-06-12 — go forth and render some gorgeous little list boxes, iykyk 💖🌈👑