.\" 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 3pm"
.TH CGI::Test::Form::Widget 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 \- Ancestor of all form widget classes
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& # Deferred class, only heirs can be created
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`CGI::Test::Form::Widget\*(C'\fR class is deferred.
It is an abstract representation of a <\s-1FORM\s0> widget, i.e. a graphical control
element like a popup menu or a submit button.
.PP
Here is an outline of the class hierarchy tree, with the leading
\&\f(CW\*(C`CGI::Test::Form::\*(C'\fR string stripped for readability, and a trailing \f(CW\*(C`*\*(C'\fR
indicating deferred classes:
.PP
.Vb 10
\&    Widget*
\&    . Widget::Box*
\&    . . Widget::Box::Check
\&    . . Widget::Box::Radio
\&    . Widget::Button*
\&    . . Widget::Button::Plain
\&    . . Widget::Button::Submit
\&    . .   Widget::Button::Image
\&    . . Widget::Button::Reset
\&    . Widget::Hidden
\&    . Widget::Input*
\&    . . Widget::Input::Text_Area
\&    . . Widget::Input::Text_Field
\&    . .   Widget::Input::File
\&    . .   Widget::Input::Password
\&    . Widget::Menu*
\&    . . Widget::Menu::List
\&    . . Widget::Menu::Popup
.Ve
.PP
Only leaf nodes are concrete classes, and there is one such class for each
known control type that can appear in the <\s-1FORM\s0> element.
.PP
Those classes are constructed as needed by \f(CW\*(C`CGI::Test\*(C'\fR.  They are the
programmatic artefacts which can be used to manipulate those graphical
elements, on which you would otherwise click and fill within a browser.
.SH "INTERFACE"
.IX Header "INTERFACE"
This is the interface defined at the \f(CW\*(C`CGI::Test::Form::Widget\*(C'\fR level,
and which is therefore common to all classes in the hierarchy.
Each subclass may naturally add further specific features.
.PP
It is very important to stick to using common widget features when
writing a matching callback for the \f(CW\*(C`widgets_matching\*(C'\fR routine in
\&\f(CW\*(C`CGI::Test::Form\*(C'\fR, or you run the risk of getting a runtime error
since Perl is not statically typed.
.SS "Attributes"
.IX Subsection "Attributes"
.ie n .IP """form""" 4
.el .IP "\f(CWform\fR" 4
.IX Item "form"
The \f(CW\*(C`CGI::Test::Form\*(C'\fR to which this widget belongs.
.ie n .IP """gui_type""" 4
.el .IP "\f(CWgui_type\fR" 4
.IX Item "gui_type"
A human readable description of the widget, as it would appear on a \s-1GUI,\s0
like \*(L"popup menu\*(R" or \*(L"radio button\*(R".  Meant for logging only, not to
determine the object type.
.ie n .IP """name""" 4
.el .IP "\f(CWname\fR" 4
.IX Item "name"
The \s-1CGI\s0 parameter name.
.ie n .IP """value""" 4
.el .IP "\f(CWvalue\fR" 4
.IX Item "value"
The current \s-1CGI\s0 parameter value.
.SS "Attribute Setting"
.IX Subsection "Attribute Setting"
.ie n .IP """set_value"" \fInew_value\fR" 4
.el .IP "\f(CWset_value\fR \fInew_value\fR" 4
.IX Item "set_value new_value"
Change the \f(CW\*(C`value\*(C'\fR attribute to \fInew_value\fR.
The widget must not be \f(CW\*(C`is_read_only\*(C'\fR nor \f(CW\*(C`is_disabled\*(C'\fR.
.SS "Widget Modification Predicates"
.IX Subsection "Widget Modification Predicates"
Those predicates may be used to determine whether it is possible to
change the value of a widget from the user interface.
.ie n .IP """is_disabled""" 4
.el .IP "\f(CWis_disabled\fR" 4
.IX Item "is_disabled"
When \fItrue\fR, the widget is disabled, i.e. not available for editing.
It would typically appear as being \fIgrayed out\fR within a browser.
.Sp
This predicate is not architecturally defined: a widget may or may not
be marked as disabled in \s-1HTML\s0 via a suitable attribute.
.ie n .IP """is_mutable"" [\fIwarn_flag\fR]" 4
.el .IP "\f(CWis_mutable\fR [\fIwarn_flag\fR]" 4
.IX Item "is_mutable [warn_flag]"
Test whether widget can change value.  Returns \fIfalse\fR when
the widget \f(CW\*(C`is_read_only\*(C'\fR or \f(CW\*(C`is_disabled\*(C'\fR.
.Sp
When the optional \fIwarn_flag\fR is true, \f(CW\*(C`carp\*(C'\fR is called
to emit a warning from the perspective of the caller.
.ie n .IP """is_read_only""" 4
.el .IP "\f(CWis_read_only\fR" 4
.IX Item "is_read_only"
When \fIfalse\fR, the \f(CW\*(C`value\*(C'\fR parameter can be changed with \f(CW\*(C`set_value\*(C'\fR.
This is an architecturally defined predicate, i.e. its value depends only
on the widget type.
.SS "Widget Classification Predicates"
.IX Subsection "Widget Classification Predicates"
Those predicates may be used to determine the overall widget type.
The classification is rather high level and only helps determining
the kind of calls that may be used on a given widget object.
.ie n .IP """is_box""" 4
.el .IP "\f(CWis_box\fR" 4
.IX Item "is_box"
Returns true for radio buttons and checkboxes.
.ie n .IP """is_button""" 4
.el .IP "\f(CWis_button\fR" 4
.IX Item "is_button"
Returns true for all buttons that are not boxes.
.ie n .IP """is_file""" 4
.el .IP "\f(CWis_file\fR" 4
.IX Item "is_file"
Returns true for a \fIfile upload\fR widget, which allows file selection.
.ie n .IP """is_hidden""" 4
.el .IP "\f(CWis_hidden\fR" 4
.IX Item "is_hidden"
Returns true for hidden fields, which have no graphical representation
by definition.
.ie n .IP """is_input""" 4
.el .IP "\f(CWis_input\fR" 4
.IX Item "is_input"
Returns true for all input fields, where the user can type text.
.ie n .IP """is_menu""" 4
.el .IP "\f(CWis_menu\fR" 4
.IX Item "is_menu"
Returns true for popup menus and scrolling lists.
.SS "Miscellaneous Features"
.IX Subsection "Miscellaneous Features"
Although documented, those features are more targetted for internal use...
.ie n .IP """delete""" 4
.el .IP "\f(CWdelete\fR" 4
.IX Item "delete"
Breaks circular references.
This is normally done by the \f(CW\*(C`delete\*(C'\fR routine on the enclosing form.
.ie n .IP """is_submitable""" 4
.el .IP "\f(CWis_submitable\fR" 4
.IX Item "is_submitable"
Returns \fItrue\fR when the name/value tupple of this widget need to be
part of the submitted parameters.  The rules for determining the submitable
nature of a widget vary depending on the widget type.
.ie n .IP """reset_state""" 4
.el .IP "\f(CWreset_state\fR" 4
.IX Item "reset_state"
Reset the widget's \f(CW\*(C`value\*(C'\fR to the one it had initially.  Invoked internally
when a reset button is pressed.
.ie n .IP """submit_tuples""" 4
.el .IP "\f(CWsubmit_tuples\fR" 4
.IX Item "submit_tuples"
For submitable widgets, return the list of (name => value) tupples that
should be part of the submitted data.  Widgets like scrolling list may return
more than one tuple.
.Sp
This routine is invoked to compute the parameter list that must be sent back
when pressing a submit button.
.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\fR\|(3),
\&\fBCGI::Test::Form::Widget::Box\fR\|(3),
\&\fBCGI::Test::Form::Widget::Button\fR\|(3),
\&\fBCGI::Test::Form::Widget::Input\fR\|(3),
\&\fBCGI::Test::Form::Widget::Hidden\fR\|(3),
\&\fBCGI::Test::Form::Widget::Menu\fR\|(3).