CGI::T...:Widget(3pm)

💖 CGI::Test::Form::Widget 💖

okay bestie, gather round, because we're about to talk about the ancestor of all form widget classes — that's the whole vibe of CGI::Test::Form::Widget(3pm), and she is literally the mother of the entire widget family. 🌸

This page lives in the User Contributed Perl Documentation corner of the manual, and she's the blueprint every other widget class is descended from. No cap. 👑

---

✨ SYNOPSIS ✨

# Deferred class, only heirs can be created

like. she cannot be instantiated. she is a concept. her children carry the legacy. 💅

---

🦋 DESCRIPTION 🦋

So CGI::Test::Form::Widget is deferred. That means it's an abstract representation of a <FORM> widget — aka a graphical control element, the kind of thing like a popup menu or a submit button. You know, the clicky stuff. 🎀

Here's the whole class hierarchy tree, with the leading CGI::Test::Form:: string stripped off for readability (because who has time for that prefix repeated 18 times), and a trailing * marking the 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

So the tea is: only leaf nodes are concrete classes, and there's exactly one of those for every known control type that can show up in the <FORM> element. One leaf, one control type, iconic behaviour honestly. 🍓

Those classes get constructed as needed by CGI::Test. They're the programmatic artefacts — the little digital stand-ins — that you use to manipulate those graphical elements, the exact same ones you'd otherwise be clicking and filling in inside a browser. It's giving remote control energy. 🌈

---

💜 INTERFACE 💜

This is the interface defined right at the CGI::Test::Form::Widget level, which means it's common to every single class in the hierarchy. Each subclass can of course add its own extra specific features, because growth is beautiful. 🫶

real talk though: it is very important to stick to using common widget features when you're writing a matching callback for the widgets_matching routine in CGI::Test::Form. Otherwise you run the risk of getting a runtime error, because Perl is not statically typed. she will not catch your mistakes for you, bestie. 😭

---

🌸 Attributes 🌸

• form — the CGI::Test::Form that this widget belongs to. her home. her chosen family. 🏠
• gui_type — a human readable description of the widget, exactly as it would appear on a GUI, like popup menu or radio button. This is meant for logging only — do not use it to determine the object type. it's a label, not a personality test. 🙈
• name — the CGI parameter name. ✨
• value — the current CGI parameter value. the moment. the now. 💫

---

💅 Attribute Setting 💅

• set_value new_value — change the value attribute to new_value. But heads up: the widget must not be is_read_only, and must not be is_disabled. otherwise? no change for you. 🚫

---

🔥 Widget Modification Predicates 🔥

These predicates are how you figure out whether it's even possible to change a widget's value from the user interface. vibe check, but for mutability.

• is_disabled — when true, the widget is disabled, i.e. not available for editing. In a browser it would typically show up grayed out. ngl, we've all been there. 🩶

This predicate is not architecturally defined: a widget may or may not be marked as disabled in HTML via a suitable attribute. So it's a maybe, bestie. not a guarantee.

• is_mutable [warn_flag] — tests whether the widget can change value. Returns false when the widget is_read_only or is_disabled. When the optional warn_flag is true, carp gets called to emit a warning from the perspective of the caller. so you get the tea and the receipt. 📢
• is_read_only — when false, the value parameter can be changed with set_value. This one is an architecturally defined predicate, i.e. its value depends only on the widget type. consistent queen. 👑

---

🧚 Widget Classification Predicates 🧚

Use these to figure out the overall widget type. The classification is rather high level — it just helps you determine the kind of calls you can make on a given widget object. not deep, just useful. 💅

• 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 by definition have no graphical representation. she's there but you can't see her. main character energy, honestly. 👻
• 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 ⭐

okay so these are documented, but ngl they're more targeted for internal use... you've been warned. 🫣

• delete — breaks circular references. This is normally done by the delete routine on the enclosing form. cutting ties, respectfully. ✂️
• is_submitable — returns true when the name/value tupple of this widget needs to be part of the submitted parameters. The rules for determining the submitable nature of a widget vary depending on the widget type. so it's case by case, no universal answer. 🤷
• reset_state — resets the widget's value to the one it had initially. Invoked internally when a reset button is pressed. we're going back to the beginning, babe. 🔄
• submit_tuples — for submitable widgets, returns the list of (name => value) tupples that should be part of the submitted data. Widgets like scrolling list may return more than one tuple, because she contains multitudes. 🌈

This routine is invoked to compute the parameter list that must be sent back when pressing a submit button. it's the behind-the-scenes girlie making the magic happen. ✨

---

👑 AUTHORS 👑

• The original author is Raphael Manfredi.
• Steven Hilton was long time maintainer of this module.
• Current maintainer is Alexander Tokarev <tokarev@cpan.org>.

we stan all three. thank you for your service. 🫡💖

---

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

---

and that's the whole page, bestie!! 🎀 this was CGI::T...:Widget(3pm) from perl v5.34.0, dated 2022-06-10 — so yeah, slightly vintage but still absolutely slaying. go forth and manipulate those form widgets responsibly. periodt. 💅✨🦋