Prima::...VBLoader(3)

💅 Prima::VB::VBLoader(3) — the User Contributed Perl Documentation glow-up ✨

okay so bestie, welcome to Prima::VB::VBLoader — the module that loads your Visual Builder resource files. That's literally it. That's the vibe. 🎀

---

🌸 NAME 🌸

Prima::VB::VBLoader — the Visual Builder file loader 💖

---

🦋 DESCRIPTION 🦋

So this module gives you the whole functionality for loading resource files that Visual Builder created. And the best part? Once the load goes through successfully, you get back the freshly-created window with all its children — the whole little widget family, returned to you. 🫶

---

✨ SYNOPSIS ✨

The simple, no-thoughts-just-vibes way to use the loader is literally this:

use Prima qw(Application VB::VBLoader);
my $form = Prima::VBLoad( './your_resource.fm',
        Form1 => { centered => 1 },
);
die $@ unless $form;
$form-> execute;

Kay so — every form widget can be handed custom parameters, all bundled up in a hash of hashes, and passed as the second parameter to the VBLoad() function. In the example above, we're feeding values into the ::centered property of the Form1 widget — and Form1 is the default name for a form window that Visual Builder makes. All the other widgets? You reach them by their names the exact same way, no cap. And after creation, the widget hierarchy is fully accessible the standard way:

$form = Prima::VBLoad( $fi,
        ....
        StartButton => {
                onMouseOver => sub { die "No start buttons here\n" },
        }
);
...
$form-> StartButton-> hide;

Now, if a form is not being included from another data source (iykyk), you can use the AUTOFORM_REALIZE method to transform that array of hashes describing the form widget hierarchy into a whole set of actual widgets:

$form = AUTOFORM_REALIZE( [ Form1 => {
        class   => 'Prima::Window',
        parent  => 1,
        profile => {
                name => 'Form1',
                size => [ 330, 421],
        }], {});

There are several examples floating around of how form files get used in the toolkit — for instance, the Prima/PS/setup.fm dialog is used by the Prima::PS::Setup package. 👑

---

💜 API 💜

🧚 Methods 🧚

• check_version HEADER — scans HEADER, aka the first line of the .fm file, for the version info. Returns two scalars: the first is a boolean flag that's set to 1 if the file can be used and loaded (and 0 otherwise), and the second scalar is the version string. Two-for-one deal, we love to see it. 💅
• GO_SUB SUB [ @EXTRA_DATA ] — depending on the value of the boolean flag Prima::VB::VBLoader::builderActive, it does one of these: if it's 1, the SUB text gets returned as-is. If it's 0, it evaluates it in the sub{} context and returns the code reference. And if that evaluation fails? EXTRA_DATA gets stored in the Prima::VB::VBLoader::eventContext array and the exception is re-thrown. Also, heads up: Prima::VB::VBLoader::builderActive is an internal flag that helps the Visual Builder use the module interface without actually evaluating the SUB code. 😭
• AUTOFORM_REALIZE WIDGETS, PARAMETERS — WIDGETS is an array reference holding the evaluated data of a .fm file's content, assuming its format is preserved. PARAMETERS is a hash reference with the custom parameters passed to widgets during creation. Widgets are distinguished by their names, and Visual Builder guarantees that no widgets have equal names. 🔥

AUTOFORM_REALIZE creates a tree of widgets and returns the root window, which is usually named Form1. It automatically resolves the parent-child relations for you, so the order in which WIDGETS are specified genuinely does not matter. Also — if a parent widget is passed as a parameter to a child widget, that parameter is deferred and only passed after creation, using the ::set call.

During the parsing and creation process, some internal notifications may be invoked. These notifications (events) are stored in the .fm file and usually provide class-specific loading instructions. See Events for the details. 🦋

• AUTOFORM_CREATE FILENAME, %PARAMETERS — reads FILENAME in the .fm file format, checks its version, loads it, and creates the widget tree. Upon a successful load, the root widget is returned. The parsing and creation are done by calling AUTOFORM_REALIZE. And if loading fails? die() is called. periodt. 💀
• Prima::VBLoad FILENAME, %PARAMETERS — a wrapper around AUTOFORM_CREATE, exported into the Prima namespace. FILENAME can be given either as a file system path name or as a relative module name. So basically,

Prima::VBLoad( 'Module::form.fm' )

and

Prima::VBLoad(
        Prima::Utils::find_image( 'Module', 'form.fm'))

are identical. If the procedure finds that FILENAME is a relative module name, it calls Prima::Utils::find_image automatically. To say explicitly that FILENAME is a file system path name, FILENAME must be prefixed with the "<" symbol (the syntax is influenced by CORE::open). 🙈

%PARAMETERS is a hash with custom parameters passed to the widgets during creation. Widgets are distinguished by their names, and Visual Builder makes sure no widgets have equal names.

If the form file loads successfully, you get the form object reference back. Otherwise, undef is returned and the error string is stored in the $@ variable. 😭

---

🎀 Events 🎀

The events stored in the .fm file get executed during the loading process. The module provides no functionality for supplying extra events during the load — this interface is only useful for developers of new widget classes for Visual Builder, so don't come for it unless that's you, bestie.

The events section lives in the "actions" section of the widget entry. There can be more than one event of each type, registered to different widgets. The NAME parameter is a string with the name of the widget. INSTANCE is a hash created during load for every widget, provided so you can keep internal event-specific or class-specific data in there. The "extras" section of the widget entry is present there as the place to store local data. ✨

• Begin NAME, INSTANCE — called before the creation of a widget tree.
• FormCreate NAME, INSTANCE, ROOT_WIDGET — called after the creation of the form, whose reference is contained in ROOT_WIDGET.
• Create NAME, INSTANCE, WIDGET. — called after the creation of a widget. The newly created widget is passed in WIDGET.
• Child NAME, INSTANCE, WIDGET, CHILD_NAME — called before a child of WIDGET is created with CHILD_NAME as a name.
• ChildCreate NAME, INSTANCE, WIDGET, CHILD_WIDGET. — called after a child of WIDGET is created; the newly created widget is passed in CHILD_WIDGET.
• End NAME, INSTANCE, WIDGET — called after the creation of all widgets is finished. 🏁

---

🌈 FILE FORMAT 🌈

The whole idea behind the .fm file format is that it should be evaluatable by perl's eval() call without any special manipulations, and kept as plain text. The file starts with a header that's a #-prefixed string, and it contains a signature, the version of the file format, and the version of the creator of the file:

# VBForm version file=1 builder=0.1

The header can also contain additional headers, also prefixed with #. These can be used to tell the loader that another perl module needs to be loaded before parsing — which is useful, for example, if a constant is declared in the module:

# [preload] Prima::ComboBox

The main part of the file is enclosed in a sub{} statement. After evaluation, this sub returns an array of paired scalars, where each first item is a widget name and the second item is a hash of its parameters and other associated data:

sub
{
        return (
                'Form1' => {
                        class   => 'Prima::Window',
                        module  => 'Prima::Classes',
                        parent => 1,
                        code   => GO_SUB('init()'),
                        profile => {
                                width => 144,
                                name => 'Form1',
                                origin => [ 490, 412],
                                size => [ 144, 100],
                }},
        );
}

That hash has several predefined keys:

• actions HASH — contains a hash of events. These events are evaluated via the GO_SUB mechanism and executed during the creation of the widget tree. See Events for details.
• code STRING — contains the code executed before the form is created. This key is present only on the root widget record.
• class STRING — contains the name of the class to be instantiated.
• extras HASH — contains class-specific parameters used by the events.
• module STRING — contains the name of the perl module that contains the class. The module will be use'd by the loader.
• parent BOOLEAN — a boolean flag; it's set to 1 for the root widget only.
• profile HASH — contains the profile hash passed as a set of parameters to the widget during its creation. If custom parameters are passed to AUTOFORM_CREATE, these are merged with profile (the custom parameters take precedence) before passing the result to the new() call. 💖

---

👑 AUTHOR 👑

Dmitry Karasik, <dmitry@karasik.eu.org>. 🫶

---

🔗 SEE ALSO 🔗

Prima, VB — go read those too bestie, they ate. 💅

---

okay that's the whole page, slay. ✨

and finally, the cute little sign-off at the very end: this beauty is from perl v5.42.0, dated 2024-08-20 — mwah, iconic. 🎀💖