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).