NAME

       CGI::Test::Form::Widget - Ancestor of all form widget classes

SYNOPSIS

        # Deferred class, only heirs can be created

DESCRIPTION

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

       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.

INTERFACE

       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.

   Attributes
       "form"
           The "CGI::Test::Form" to which this widget belongs.

       "gui_type"
           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.

       "name"
           The CGI parameter name.

       "value"
           The current CGI parameter value.

   Attribute Setting
       "set_value" new_value
           Change the "value" attribute to new_value.  The widget must not be "is_read_only" nor
           "is_disabled".

   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.

       "is_disabled"
           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.

       "is_read_only"
           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.

   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.

       "is_box"
           Returns true for radio buttons and checkboxes.

       "is_button"
           Returns true for all buttons that are not boxes.

       "is_file"
           Returns true for a file upload widget, which allows file selection.

       "is_hidden"
           Returns true for hidden fields, which have no graphical representation by definition.

       "is_input"
           Returns true for all input fields, where the user can type text.

       "is_menu"
           Returns true for popup menus and scrolling lists.

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

       "delete"
           Breaks circular references.  This is normally done by the "delete" routine on the
           enclosing form.

       "is_submitable"
           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 type.

       "reset_state"
           Reset the widget's "value" to the one it had initially.  Invoked internally when a
           reset button is pressed.

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

           This routine is invoked to compute the parameter list that must be sent back when
           pressing a submit button.

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(3), CGI::Test::Form::Widget::Box(3), CGI::Test::Form::Widget::Button(3),
       CGI::Test::Form::Widget::Input(3), CGI::Test::Form::Widget::Hidden(3),
       CGI::Test::Form::Widget::Menu(3).