---
name: "Curses::Widgets::ListBox"
section: "3pm"
platform: "linux"
package: "libcurses-widgets-perl"
version: "1.997-8"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Curses::Widgets::ListBox"
---

# Curses::Widgets::ListBox(3pm)

List Box Widgets

## NAME

Curses::Widgets::ListBox - List Box Widgets

## MODULE VERSION

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

## SYNOPSIS

```
  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);
  See the Curses::Widgets pod for other methods.
```

## REQUIREMENTS

- Curses

  - Curses::Widgets

  ## DESCRIPTION

Curses::Widgets::ListBox provides simplified OO access to Curses-based single/multi-select list boxes.  Each object maintains its own state  information.

## 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.  The only mandatory key/value pairs in the configuration hash are **X** and **Y**.  All others have the following defaults:

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

The value of **VALUE** should be an array reference when in multiple selection mode.  Otherwise it should either undef or an integer.

### draw

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

The draw method renders the list box in its current state.  This requires a valid handle to a curses window in which it will render itself.  The optional second argument, if true, will cause the field's text cursor to be rendered as well.

## HISTORY

- 1999/12/29 Ω- Original list box widget in functional model

  - 2001/07/05 Ω- First incarnation in OO architecture

  ## AUTHOR/COPYRIGHT

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