CGI::Test::Form::Widget - Ancestor of all form widget classes
# Deferred class, only heirs can be created
The "CGI::Test::Form::Widget" class is deferred. It is an abstract
representation of a <FORM> widget, i.e. a graphical control element like
a popup menu or a submit button.
Here is an outline of the class hierarchy tree, with the leading
"CGI::Test::Form::" string stripped for readability, and a trailing
"*" indicating deferred classes:
. . Widget::Box::Check
. . Widget::Box::Radio
. . Widget::Button::Plain
. . Widget::Button::Submit
. . Widget::Button::Image
. . Widget::Button::Reset
. . Widget::Input::Text_Area
. . Widget::Input::Text_Field
. . Widget::Input::File
. . Widget::Input::Password
. . Widget::Menu::List
. . Widget::Menu::Popup
Only leaf nodes are concrete classes, and there is one such class for each known
control type that can appear in the <FORM> element.
Those classes are constructed as needed by "CGI::Test". 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.
This is the interface defined at the "CGI::Test::Form::Widget" level,
and which is therefore common to all classes in the hierarchy. Each subclass
may naturally add further specific features.
It is very important to stick to using common widget features when writing a
matching callback for the "widgets_matching" routine in
"CGI::Test::Form", or you run the risk of getting a runtime error
since Perl is not statically typed.
- The "CGI::Test::Form" to which this widget
- A human readable description of the widget, as it would
appear on a GUI, like "popup menu" or "radio button".
Meant for logging only, not to determine the object type.
- The CGI parameter name.
- The current CGI parameter value.
- "set_value" new_value
- Change the "value" attribute to new_value.
The widget must not be "is_read_only" nor
Those predicates may be used to determine whether it is possible to change the
value of a widget from the user interface.
- When true, the widget is disabled, i.e. not
available for editing. It would typically appear as being grayed
out within a browser.
This predicate is not architecturally defined: a widget may or may not be
marked as disabled in HTML via a suitable attribute.
- "is_mutable" [warn_flag]
- Test whether widget can change value. Returns false
when the widget "is_read_only" or "is_disabled".
When the optional warn_flag is true, "carp" is called to
emit a warning from the perspective of the caller.
- When false, the "value" parameter can be
changed with "set_value". This is an architecturally defined
predicate, i.e. its value depends only on the widget type.
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.
- Returns true for radio buttons and checkboxes.
- Returns true for all buttons that are not boxes.
- Returns true for a file upload widget, which allows
- Returns true for hidden fields, which have no graphical
representation by definition.
- Returns true for all input fields, where the user can type
- Returns true for popup menus and scrolling lists.
Although documented, those features are more targetted for internal use...
- Breaks circular references. This is normally done by the
"delete" routine on the enclosing form.
- Returns true 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
- Reset the widget's "value" to the one it had
initially. Invoked internally when a reset button is pressed.
- 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.
This routine is invoked to compute the parameter list that must be sent back
when pressing a submit button.
The original author is Raphael Manfredi.
Steven Hilton was long time maintainer of this module.
Current maintainer is Alexander Tokarev <email@example.com>