Gtk2::E...::Widget(3)

📦
version 0.67 · 2 versions
, in fedora 43

💖 Gtk2::E...::Widget — the perl manpage, but make it make sense 💖

okay bestie, listen up. This is the Gtk2::E...::Widget(3) page from the User Contributed Perl Documentation, and we're gonna get through it together, no cap. Grab a snack. 🍓

✨ NAME ✨

Gtk2::Ex::FormFactory::Widget — the base class that every single FormFactory Widget inherits from. Like, the OG parent. The mother of all widgets. 👑

✨ SYNOPSIS ✨

Here's the whole constructor in all its glory — every arg, verbatim, because we do NOT play fast and loose with signatures in this house:

Gtk2::Ex::FormFactory::Widget->new (
  name                 => Name of this Widget,
  object               => Name of the associated application object,
  attr                 => Attribute represented by the Widget,
  label                => Label text,
  label_markup         => Boolean, indicating whether the label has markup,
  label_group          => Name of a Gtk2::SizeGroup for the label,
  widget_group         => Name of a Gtk2::SizeGroup for the widget,
  tip                  => Tooltip text,
  properties           => { Gtk2 Properties ... }
  inactive             => 'insensitive' | 'invisible',
  rules                => [ Rules for this Widget ],
  expand               => Boolean: should the Widget expand?,
  expand_h             => Boolean: should the Widget expand horizontally?,
  expand_v             => Boolean: should the Widget expand vertically?,
  scrollbars           => [ hscrollbar_policy, vscrollbar_policy ],
  signal_connect       => { signal => CODREF, ... },
  signal_connect_after => { signal => CODREF, ... },
  width                => Desired width,
  height               => Desired height,
  customize_hook       => CODEREF: Customize the underlying Gtk2 Widget,
  changed_hook         => CODEREF: Track changes made to the Widget,
  changed_hook_after   => CODEREF: Track changes made to the Widget,
  active_cond          => CODEREF: Condition for Widget being active
  active_depends       => SCALAR|ARRAYREF: Attribute(s) activity depends on
);

look at all those options. we will absolutely be getting into all of them later, don't you worry. 💅

✨ DESCRIPTION ✨

So. This is an abstract base class. Which basically means: you, the humble application developer, are not supposed to use it directly. It's giving "backstage crew, not the main character". 🎭

BUT — and this is the important part — for your everyday programming, the attributes defined right here in this class are literally the most important ones, because every single Widget in the whole Gtk2::Ex::FormFactory framework shares them. So even though you never touch this class by name, you're lowkey using it every single time. iykyk. ✨

✨ OBJECT HIERARCHY ✨

Here's the family tree, bestie. Note that Expander shows up twice in this list — once under Container and once as a direct child of Widget — and we are reporting that faithfully because that's what the original says. No editing the lore. 📜

Gtk2::Ex::FormFactory::Intro

Gtk2::Ex::FormFactory::Widget
+--- Gtk2::Ex::FormFactory::Container
|    +--- Gtk2::Ex::FormFactory
|    +--- Gtk2::Ex::FormFactory::Expander
|    +--- Gtk2::Ex::FormFactory::Form
|    +--- Gtk2::Ex::FormFactory::HBox
|    +--- Gtk2::Ex::FormFactory::Notebook
|    +--- Gtk2::Ex::FormFactory::Table
|    +--- Gtk2::Ex::FormFactory::VBox
|    +--- Gtk2::Ex::FormFactory::Window
+--- Gtk2::Ex::FormFactory::Button
+--- Gtk2::Ex::FormFactory::CheckButton
+--- Gtk2::Ex::FormFactory::CheckButtonGroup
+--- Gtk2::Ex::FormFactory::Combo
+--- Gtk2::Ex::FormFactory::DialogButtons
+--- Gtk2::Ex::FormFactory::Entry
+--- Gtk2::Ex::FormFactory::Expander
+--- Gtk2::Ex::FormFactory::ExecFlow
+--- Gtk2::Ex::FormFactory::GtkWidget
+--- Gtk2::Ex::FormFactory::HPaned
+--- Gtk2::Ex::FormFactory::HSeparator
+--- Gtk2::Ex::FormFactory::Image
+--- Gtk2::Ex::FormFactory::Label
+--- Gtk2::Ex::FormFactory::List
+--- Gtk2::Ex::FormFactory::Menu
+--- Gtk2::Ex::FormFactory::Popup
+--- Gtk2::Ex::FormFactory::ProgressBar
+--- Gtk2::Ex::FormFactory::RadioButton
+--- Gtk2::Ex::FormFactory::TextView
+--- Gtk2::Ex::FormFactory::Timestamp
+--- Gtk2::Ex::FormFactory::ToggleButton
+--- Gtk2::Ex::FormFactory::VPaned
+--- Gtk2::Ex::FormFactory::VSeparator
+--- Gtk2::Ex::FormFactory::YesNo

Gtk2::Ex::FormFactory::Layout
Gtk2::Ex::FormFactory::Rules
Gtk2::Ex::FormFactory::Context
Gtk2::Ex::FormFactory::Proxy
+--- Gtk2::Ex::FormFactory::ProxyBuffered

that's a LOT of children. like, this Widget is a whole parent of a whole friend group. 🫶

okay we're not done yet — more of this page is coming, so don't go anywhere. 💜

✨ ATTRIBUTES ✨

Okay bestie, so attributes all work through the classic get_ATTR() / set_ATTR() accessor situation 💅 — but here's the tea: you're mostly passing them in once, at object construction time. After the associated FormFactory was built, you must not alter them. Like, that's the rule. Don't poke the bear. 🐻

name = SCALAR [optional]

Every widget has its own unique name, periodt. If you don't hand one over explicitly, a name just gets generated for you automatically. ✨ Later on, you can grab named widgets using the get_widget and lookup_widget methods described below. iykyk 👑

object = SCALAR [optional]

This is the name of the object that controls this widget. Important: that object name has to be registered at the Gtk2::Ex::FormFactory::Context of the Gtk2::Ex::FormFactory that's associated with this Widget. No registration, no vibes. 🫶

You're also allowed to just skip the object property entirely and use the fully qualified "object.attr" notation in the attr attribute (described right down there 👇). And if you want your Widget associated with only an object but not with an attribute — like, say, you just want a container widget's activity managed automatically with no object attribute attached — then simply omit attr and put only object here. Easy. 🍓

attr = SCALAR [optional]

Usually a Widget represents one specific object attribute. Example: a text entry shows the current value of whatever attribute you name here. How that attribute actually gets accessed is defined over in the Gtk2::Ex::FormFactory::Context instance. 🌸

So if you already used the object property, just pass the name of your attribute here. But convenience queens, you may also omit object and pass "object.attr" straight to the attr property. Do what feels right. 💖

label = SCALAR [optional]

Each Widget may have a label attached. How that label actually renders is entirely up to the Gtk2::Ex::FormFactory::Container this Widget got added to. For example, Gtk2::Ex::FormFactory::Form does a simple two column table situation — labels on the left, widgets on the right. Simple. Clean. Iconic. ✨

label_markup = BOOLEAN [optional]

Set this to a true value and your label renders with HTML-like markup. 🎀 For the details on which markup tags exist, go read the chapter "Pango Text Attribute Markup" in the official Gtk documentation.

label_group = SCALAR [optional]

Complex layout? Want your labels all aligned even though they're not in the same container? Just drop an arbitrary name for a label group here. 🌈 A corresponding Gtk2::SizeGroup is managed automatically for you — you literally don't have to do anything. Just use the same name for every Widget whose labels you want sized the same. That's it. Slay. 💅

widget_group = SCALAR [optional]

Super similar to the label_group attribute, but the plot twist is that the size allocated by the Widget is what's under the control of a Gtk2::SizeGroup. 🦋

tip = SCALAR [optional]

Optional text for this Widget's tooltip. Hover content. The little lore drop. 😌

properties = HASHREF [optional]

A hash of Gtk+ properties for this Widget. Like, you can pass { border_width => 5 } here to mess with the border-width of this one specific Widget. ⭐

Use this with care, bestie. It breaks the strict isolation of GUI structure and appearance. The probably-better move is implementing your own Gtk2::Ex::FormFactory::Layout class, where you can control how your widgets look in a way more generic way. 🔥

inactive = 'insensitive' | 'invisible' [optional]

Gtk2::Ex::FormFactory automatically manages the activity state of your Widgets — that's just its job. 💁 Specify here whether you want the Widget going insensitive or invisible when the Widget is deactivated. Defaults to 'insensitive'.

rules = rule | [ rule, ... ] [optional]

Any data the user enters has to apply the rules you specify here. For all the details about rules, go read Gtk2::Ex::FormFactory::Rules. 📜

expand = BOOL [optional]

By default, a Widget does not expand into the space available from its container. Specify a TRUE value to activate Widget expansion. 🔥 Whether it expands vertically or horizontally depends on its Container — like, in a VBox it expands vertically, and in a HBox it expands horizontally. Physics. 💫

expand_h = BOOL [optional]

expand_v = BOOL [optional]

Some containers can expand the Widget in both directions, e.g. a Gtk2::Table. If your widget is added to one of those (say, a Gtk2::Ex::FormFactory::Form, which is implemented with a Gtk2::Table), you can specify both directions of expansion right here. 🎀

expand_h defaults to TRUE and expand_v to FALSE, or to expand if that was specified.

scrollbars = [ h_policy, v_policy ] [optional]

Want your Widget inside a Gtk2::ScrolledWindow? Just specify the policy for horizontal and vertical scrollbars here. The possible values are: "always", "automatic" or "never". 🌊

changed_hook = CODEREF(ApplicationObject, WidgetObject) [optional]

This code reference gets called after the user changed a value of the Widget, but before those changes are applied to the underlying application object. The application object is the first argument of the call, and the Widget object is the second. 💖

changed_hook_after = CODEREF(ApplicationObject, WidgetObject) [optional]

Same energy, different timing: this one is called after the user changed a value of the Widget and after those changes are applied to the underlying application object. Application object first argument, Widget object second. ✨

signal_connect = HASHREF [optional]

Drop all your signal connections into a single hash reference. 🔑 Key is the name of the signal, value is the callback (a static subroutine reference or a closure).

Note, bestie: do NOT use this to track changes made on the GUI! Gtk2::Ex::FormFactory manages that for you already. If you want to be notified about changes, use the Widget transparent changed_hook described above. 😭

signal_connect_after = HASHREF [optional]

Same as signal_connect, except the signals get connected using Gtk2's signal_connect_after method. 🌟

width = INTEGER [optional]

height = INTEGER [optional]

You can specify a desired width and/or height. Internally, Gtk2::Widget->set_default_size is used on windows and Gtk2::Widget->set_size_request on all other widgets. 📐

customize_hook = CODEREF(Gtk2::Widget) [optional]

This code reference is called after the Gtk2::Widget's are built. The Gtk2::Widget object of this Gtk2::Ex::FormFactory::Widget is the first argument of the call. 🛠️

You can use this hook to do very specific customization with this Widget. But again — use this with care, and probably just implement your own Gtk2::Ex::FormFactory::Layout class to control the layout instead. 😅

active_cond = CODEREF(ApplicationObject) [optional]

The Widget's activity state (visible/sensitive) is controlled by this condition — or rather, by the return value of this code reference. 💅 Use this if you want fine control over the activity state of the widget with arbitrary conditions. And note: widgets get automatically inactive if the object they're bound to gets undef. 💀

The return value works like this:

0   Widget gets inactive. According to the B<inactive>
    attribute it gets either invisible or insensitive.

1   Widget gets active. According to the B<inactive>
    attribute it gets either visible or sensitive.

Or you can return one of these strings

'insensitive'
'invisible'
'sensitive'
'visible'

to get the corresponding widget state. 🎀

active_depends = SCALAR | ARRAYREF [optional]

This lists the attribute(s) that the activity condition above depends on — i.e. which attributes are variables in that condition. It may point to objects or to attributes (in "object.attr" notation). 🔗

With this knowledge, Gtk2::Ex::FormFactory is able to update the activity automatically whenever one of the corresponding objects or attributes changes. Magic, honestly. ✨

💅 METHODS 💅

Okay bestie, here's where the magic actually happens. Buckle up. 🎀

  • $widget->update () — This updates this specific Widget, like, sets its state to whatever value lives in the associated application object attribute. Heads up though: if you're dealing with a Container, the child widgets do not get updated. Just the one. Periodt.
  • $widget->update_all () — Same vibe as update, but containers will drag their children along for the update too. Family outing energy. 🫶
  • $widget->update_widget_activity () — Only updates the Widget's activity state. That's it. That's the whole job. ✨
  • $app_object_attr_value = $widget->get_object_value ([$attr]) — A lil convenience method to grab the actual value of an associated application object attribute. If you don't pass $attr, it just uses the default attribute. Easy.
  • $widget->set_object_value ( [$attr, ] $value ) — Convenience method to set the actual value of an associated application object attribute to $value. Omit $attr and it goes with the default attribute. Slay.
  • $widget->check_widget_value () — Checks the current Widget value against the rules set up for this Widget. If the rule check fails? An error dialog pops open and the previous value gets restored automatically. If everything's fine, literally nothing happens. No drama. 💀
  • $widget->widget_value_changed () — This method gets called when the Widget value was changed. Every single Widget implementation of Gtk2::Ex::FormFactory must connect their specific "changed" signal to this method call. Non-negotiable, bestie.
  • $widget->apply_changes () — Copies the Widget value over to the associated application object attribute. In a FormFactory where the sync flag is set to TRUE, this happens on each change. If the FormFactory is asynchronous, it only gets called when the user hits the Ok button. 👑
  • $widget->show_error_message ( message => $message, type => $type ) — A small convenience method that opens a Gtk+ error dialog with $message. The $type defaults to 'error', but you can also pass 'info', 'warning' and 'question' to get the corresponding dialogs. Choose your fighter. 🌈
  • $proxy = $widget->get_proxy () — Convenience method returning the Gtk2::Ex::FormFactory::Proxy instance for the object associated with this Widget.
  • $another_widget = $widget->get_widget ( $name ) — Returns the Gtk2::Ex::FormFactory::Widget object named $name from the FormFactory of this widget.
  • $another_widget = $widget->lookup_widget ($name) — The same as get_widget when you pass a widget name, but additionally you can dereference sibling widgets by passing this:
sibling($n)

This returns the $n-th sibling of this Widget, and yes, $n is allowed to be negative. Go backwards, queen. 🦋

This method is what looks up widgets assigned to a Gtk2::Ex::FormFactory::Label using the Label's for attribute.

The following methods are used by the Gtk2::Ex::FormFactory::Layout module, so you only need them if you're implementing your own layout. iykyk. 🧚

  • $widget->set_gtk_widget (Gtk2::Widget) — The Gtk2::Widget which represents the associated application object attribute. Like, for a Gtk2::Ex::FormFactory::Entry widget, this is a Gtk2::Entry.
  • $widget->set_gtk_parent_widget (Gtk2::Widget) — Often the real Gtk2 widget is tucked inside a container, like a Gtk2::Frame. The Gtk2 widget of that container needs to be set explicitly using this method. (Yes, the original says "explicetly". We love a typo moment. 💖)

🌸 IMPLEMENT NEW WIDGETS 🌸

You can implement new widgets by subclassing Gtk2::Ex::FormFactory::Widget or Gtk2::Ex::FormFactory::Container. Main character behavior honestly. ✨

You need to implement the following methods — not all of them are mandatory though. Like, if your Widget is a container that doesn't actually represent any application object value, you can just skip most of them. No pressure bestie:

  • $self->get_type() [mandatory] — Returns the short name of your Widget. It should be lower case and may contain underscores. If you're wrapping an existing Gtk2 widget, try to derive the type name from the widget's name. Stay consistent, it's giving organized. 🎀
  • $self->object_to_widget [optional] — Transfers the value of the associated application object attribute to your widget. You may use the convenience method $self->get_object_value() to get the value of the default attribute of this widget.
  • $self->widget_to_object [optional] — Transfers the value of your widget to the associated application object attribute. You may use the convenience method $self->set_object_value($value) to set the value of the default attribute of this widget.
  • $self->empty_widget [optional] — Sets your widget to an empty value. Like, an Image widget should display nothing, or the text of some sort of text entry should be deleted. Clean slate energy. 🫧
  • $self->backup_widget_value [optional] — Makes a backup of the current widget value. Gtk2::Ex::FormFactory::Widget has a convenience method for setting the backup value you can use: $self->set_backup_widget_value($value). If your widget has a more complex value that can't be covered by a single scalar, then your implementation has to handle that itself. Sorry bestie, them's the rules. 💅
  • $self->restore_widget_value [optional] — Restores a value from the backup created with $self->backup_widget_value().
  • $self->get_gtk_check_widget [optional] — Returns the Gtk widget that the focus-in and focus-out signals should be connected to for rule checking. Defaults to $self->get_gtk_widget().
  • $self->get_widget_check_value [optional] — Currently Gtk2::Ex::FormFactory::Rules can only check a single scalar value. Your widget must implement this method to return the correspondent value. One value only, no collections, we don't make the rules. 😭
  • $self->connect_changed_signal [optional] — This method must connect the "changed" signal of the specific Gtk2 widget your implementation uses. The connected callback must call the $self->widget_value_changed() method, so Gtk2::Ex::FormFactory can track all changes on the GUI. Don't forget this or the whole tracking thing falls apart fr fr.
  • $gtk_widget = $self->get_gtk_signal_widget() [optional] — This defaults to $self->get_gtk_widget() and returns the Gtk2 widget that additional user specified signals should be connected to.
  • $gtk_widget = $self->get_gtk_properties_widget() [optional] — This defaults to $self->get_gtk_widget() and returns the Gtk2 widget which should get the properties defined for this Gtk2::Ex::FormFactory widget. Super useful when the actual GtkWidget isn't the gtk_widget — like, Gtk2::Ex::FormFactory::Window needs this, since it's finally a VBox, but you want to apply properties like default_width to the GtkWindow and not to the VBox. Iconic workaround, honestly.
  • $widgets_lref = $self->get_gtk_tip_widgets() [optional] — This defaults to [ $self->get_gtk_widget() ] and returns a list reference of Gtk2 widgets that should get a tooltip, if the user specified one.
  • $self->has_additional_attrs() [optional] — If your widget supports additional application object attributes that should be managed automatically, this method returns a list reference of symbolic names for those attributes. Go check out the implementation of Gtk2::Ex::FormFactory::List, which uses this feature to store the actually selected item(s) in the application object. Chef's kiss. 👑
  • BOOL = $self->has_label() [optional] — This defaults to 0. Set it to 1 if your widget manages its label by itself (like a Gtk2::CheckBox does). Independent queen. 💜

🦋 Creating the Gtk2 widget(s) 🦋

So you probably noticed there's no method here that actually builds the Gtk2 widgets of your widget. Not a mistake, bestie — that's covered by the Gtk2::Ex::FormFactory::Layout module. So go create your own layouter and add the $layouter->build_TYPE($widget) method for your widget to it. If your widget is a container you also need to implement at least the generic $layouter->add_widget_to_TYPE method. For the deets on all of this, go read the documentation of Gtk2::Ex::FormFactory::Layout. ✨

That said, if your widget is super specific to your application — like, because it displays a very specific data structure — then creating your own Layout module just for that purpose is somewhat involved. In that case you can implement this method instead:

  • $self->build_widget() — If implemented, this method is called to actually create the Gtk2 widgets for your Gtk2::Ex::FormFactory widget. Do it your way. 💅

💖 AUTHORS 💖

 Jörn Reder <joern at zyn dot de>

Copyright 2004-2006 by Jörn Reder.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.

You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307 USA.

🙈 POD ERRORS 🙈

Hey! The above document had some coding errors, which are explained below:

Around line 1379:

    Non-ASCII character seen before =encoding in 'Jörn'. Assuming UTF-8
Not the encoding police showing up at the very last second. 💀 The ö in Jörn said "I contain multitudes" and Perl was like "assuming UTF-8, hope that's fine." It was fine. Everything's fine. 😭

And that's a wrap on the whole page, bestie! 🎀 This one came from perl v5.42.0, dated 2025-07-25, and it's the Gtk2::E...::Widget(3) page from the User Contributed Perl Documentation. Go forth and build widgets, you gorgeous genius. Periodt. 💖✨👑

📦 where this page comes from