---
name: "CGI::Test::Form::Widget::Menu"
section: "3pm"
platform: "linux"
package: "libcgi-test-perl"
version: "1.111-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/CGI::Test::Form::Widget::Menu"
---

# CGI::Test::Form::Widget::Menu(3pm)

Abstract representation of a menu

## NAME

CGI::Test::Form::Widget::Menu - Abstract representation of a menu

## SYNOPSIS

```
 # Inherits from CGI::Test::Form::Widget
```

## DESCRIPTION

This class is the abstract representation of a menu from which one can choose one or several items, i.e. either a popup menu or a scrollable list (with possibly multiple selections).

There is an interface to query the selected items, get at the presented labels and associated values, and naturally `"select()"` or `"unselect()"` items.

## INTERFACE

The interface is the same as the one described in CGI::Test::Form::Widget, with the following additions:

### Attributes

- "known\_values"

  An hash reference, recording valid menu values, as tuples (*value* =\> *count*), with *count* set to the number of times the same value is re-used amongst the proposed options.

- "multiple"

  Whether menu allows multiple selections.

- "option\_labels"

  A list reference, providing the labels to choose from, in the order in which they appear.  The retained labels are either the content of the \<OPTION\> elements, or the value of their `"label"` attribute, when specified.

- "option\_values"

  A list reference, providing the underlying values that the user chooses from when he selects labels, in the order in which they appear in the menu.

- "selected"

  An hash reference, whose keys are the selected values.

- "selected\_count"

  The amount of currently selected items.

### Attribute Setting

- "select" *value*

  Mark the option *value* as selected.  If `"multiple"` is false, any previously selected value is automatically unselected.

  Note that this takes a *value*, not a *label*.

- "unselect" *value*

  Unselect an option *value*.  It is not possible to do that on a popup menu: you must `"select"` another item to unselect any previously selected one.

### Menu Probing

- "is\_selected" *value*

  Test whether an option *value* is currently selected or not.  This is not testing a label, but a value, which is what the script will get back eventually: labels are there for human consumption only.

### Widget Classification Predicates

There is an additional predicate to distinguish between a popup menu (single selection mandatory) from a scrolling list (multiple selection allowed, and may select nothing).

- "is\_popup"

  Returns *true* for a popup menu.

### Miscellaneous Features

Although documented, those features are more targetted for internal use...

- "set\_selected" *value*, *flag*

  Change the selection status of an option *value*.

  You should use the `"select"` and `"unselect"` convenience routines instead of calling this feature.

## AUTHORS

The original author is Raphael Manfredi.

Steven Hilton was long time maintainer of this module.

Current maintainer is Alexander Tokarev *\<tokarev@cpan.org\>*.

## SEE ALSO

**CGI::Test::Form::Widget**(3), **CGI::Test::Form::Widget::Menu::List**(3), **CGI::Test::Form::Widget::Menu::Popup**(3).