.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "CGI::Test::Form::Widget::Menu 3pm"
.TH CGI::Test::Form::Widget::Menu 3pm "2022-06-10" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CGI::Test::Form::Widget::Menu \- Abstract representation of a menu
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& # Inherits from CGI::Test::Form::Widget
.Ve
.SH "DESCRIPTION"
.IX Header "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).
.PP
There is an interface to query the selected items, get at the presented
labels and associated values, and naturally \f(CW\*(C`select()\*(C'\fR or \f(CW\*(C`unselect()\*(C'\fR
items.
.SH "INTERFACE"
.IX Header "INTERFACE"
The interface is the same as the one described in CGI::Test::Form::Widget,
with the following additions:
.SS "Attributes"
.IX Subsection "Attributes"
.ie n .IP """known_values""" 4
.el .IP "\f(CWknown_values\fR" 4
.IX Item "known_values"
An hash reference, recording valid menu values, as tuples
(\fIvalue\fR => \fIcount\fR), with \fIcount\fR set to the number of times the same
value is re-used amongst the proposed options.
.ie n .IP """multiple""" 4
.el .IP "\f(CWmultiple\fR" 4
.IX Item "multiple"
Whether menu allows multiple selections.
.ie n .IP """option_labels""" 4
.el .IP "\f(CWoption_labels\fR" 4
.IX Item "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 <\s-1OPTION\s0>
elements, or the value of their \f(CW\*(C`label\*(C'\fR attribute, when specified.
.ie n .IP """option_values""" 4
.el .IP "\f(CWoption_values\fR" 4
.IX Item "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.
.ie n .IP """selected""" 4
.el .IP "\f(CWselected\fR" 4
.IX Item "selected"
An hash reference, whose keys are the selected values.
.ie n .IP """selected_count""" 4
.el .IP "\f(CWselected_count\fR" 4
.IX Item "selected_count"
The amount of currently selected items.
.SS "Attribute Setting"
.IX Subsection "Attribute Setting"
.ie n .IP """select"" \fIvalue\fR" 4
.el .IP "\f(CWselect\fR \fIvalue\fR" 4
.IX Item "select value"
Mark the option \fIvalue\fR as selected.  If \f(CW\*(C`multiple\*(C'\fR is false, any
previously selected value is automatically unselected.
.Sp
Note that this takes a \fIvalue\fR, not a \fIlabel\fR.
.ie n .IP """unselect"" \fIvalue\fR" 4
.el .IP "\f(CWunselect\fR \fIvalue\fR" 4
.IX Item "unselect value"
Unselect an option \fIvalue\fR.  It is not possible to do that on a popup
menu: you must \f(CW\*(C`select\*(C'\fR another item to unselect any previously selected one.
.SS "Menu Probing"
.IX Subsection "Menu Probing"
.ie n .IP """is_selected"" \fIvalue\fR" 4
.el .IP "\f(CWis_selected\fR \fIvalue\fR" 4
.IX Item "is_selected value"
Test whether an option \fIvalue\fR 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.
.SS "Widget Classification Predicates"
.IX Subsection "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).
.ie n .IP """is_popup""" 4
.el .IP "\f(CWis_popup\fR" 4
.IX Item "is_popup"
Returns \fItrue\fR for a popup menu.
.SS "Miscellaneous Features"
.IX Subsection "Miscellaneous Features"
Although documented, those features are more targetted for
internal use...
.ie n .IP """set_selected"" \fIvalue\fR, \fIflag\fR" 4
.el .IP "\f(CWset_selected\fR \fIvalue\fR, \fIflag\fR" 4
.IX Item "set_selected value, flag"
Change the selection status of an option \fIvalue\fR.
.Sp
You should use the \f(CW\*(C`select\*(C'\fR and \f(CW\*(C`unselect\*(C'\fR convenience routines instead
of calling this feature.
.SH "AUTHORS"
.IX Header "AUTHORS"
The original author is Raphael Manfredi.
.PP
Steven Hilton was long time maintainer of this module.
.PP
Current maintainer is Alexander Tokarev \fI<tokarev@cpan.org>\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBCGI::Test::Form::Widget\fR\|(3),
\&\fBCGI::Test::Form::Widget::Menu::List\fR\|(3),
\&\fBCGI::Test::Form::Widget::Menu::Popup\fR\|(3).