/ 
Term-Fabulous-0.05
/ Term::Fabulous::Widget::Dropdown::List

NAME

Term::Fabulous::Widget::Dropdown::List - The option list of an open dropdown

DESCRIPTION

This class is internal to Term::Fabulous::Widget::Dropdown. Applications never create a list themselves: the dropdown creates one each time it opens, adds it as a floating child of itself (so it is drawn over the other widgets), and removes it when it closes. In every frame the list floats where the dropdown places it (Term::Fabulous::Placement): below or above the dropdown, attached to the root and kept on the screen.

The list is a Term::Fabulous::Widget::Display that paints the dropdown's options with a one-column margin on both sides, highlights one of them, scrolls through them when there are more options than rows, and then shows a scrollbar in its rightmost column. It turns mouse presses into highlights and mouse releases into choices, and scrolls on the mouse wheel. It never takes the keyboard focus; the dropdown keeps the focus and handles the keys.

The methods below are documented for authors of dropdown subclasses and for tests.

CONSTRUCTOR

new

my $list = Term::Fabulous::Widget::Dropdown::List->new(
	dropdown     => $dropdown,
	visible_rows => 8,
	...
);

Called by the dropdown with these parameters, plus bordered, layout and floating (see "floating" in Term::Fabulous::Widget). Its background, border color and border style follow the dropdown when they are not given. Unknown parameters die.

Required. The Term::Fabulous::Widget::Dropdown the list belongs to. Held as a weak reference.

visible_rows

Required. A positive integer: how many options the list shows at once.

METHODS

visible_rows

my $rows = $list->visible_rows;

How many options the list shows at once.

top_option

my $index = $list->top_option;

The index of the first option shown (from 0).

show_highlight

$list->show_highlight;

Scrolls the dropdown's highlighted option into view and marks the list changed. Returns the list.

scroll

$list->scroll(-1);

Scrolls by a number of options (negative: towards the first), staying within the options. Returns the list.

option_at_row

my $index = $list->option_at_row($row);

The index of the option shown at a row of the list's content (from 0), or undef for a row without an option.

my $position = $list->popup_position;    # { x => 34, y => 6 }

Where the list floats in this frame: the dropdown's list_position. The list composes Term::Fabulous::Role::Popup, which calls it.

paint, paint_key, natural_size

The Term::Fabulous::Widget::Display interface. paint draws the visible options and, when the list scrolls, the scrollbar. The paint key adds the first option shown, the number of options and the label and colors of each shown row, so the list paints again whenever that changed, also when the change came from the dropdown (its colors, its highlight, its options). The natural size (the widest label with its margins and the scrollbar column, by visible_rows) is used only for an axis the dropdown leaves unsized; it always sizes both.

MOUSE

A left press on an option highlights it; releasing the left button over an option chooses it (see "choose" in Term::Fabulous::Widget::Dropdown). Presses on the scrollbar column are ignored. Each notch of the mouse wheel scrolls by one option.

SEE ALSO

Term::Fabulous::Widget::Dropdown.