use Prima qw(Application);
use Prima::VB::VBLoader;
Prima::VBLoad( './your_resource.fm',
Form1 => { centered => 1 },
)-> execute;
A more complicated but more proof code can be met in the toolkit:
use Prima qw(Application);
eval "use Prima::VB::VBLoader"; die "$@\n" if $@;
$form = Prima::VBLoad( $fi,
'Form1' => { visible => 0, centered => 1},
);
die "$@\n" unless $form;
All form widgets can be supplied with custom parameters, all together combined in a hash of hashes and passed as the second parameter to "VBLoad()" function. The example above supplies values for "::visible" and "::centered" to "Form1" widget, which is default name of a form window created by Visual Builder. All other widgets are accessible by their names in a similar fashion; after the creation, the widget hierarchy can be accessed in the standard way:
$form = Prima::VBLoad( $fi,
....
'StartButton' => {
onMouseOver => sub { die "No start buttons here\n" },
}
);
...
$form-> StartButton-> hide;
In case a form is to be included not from a fm file but from other data source, AUTOFORM_REALIZE call can be used to transform perl array into set of widgets:
$form = AUTOFORM_REALIZE( [ Form1 => {
class => 'Prima::Window',
parent => 1,
profile => {
name => 'Form1',
size => [ 330, 421],
}], {});
Real-life examples are met across the toolkit; for instance, Prima/PS/setup.fm dialog is used by "Prima::PS::Setup".
"AUTOFORM_REALIZE" creates the tree of widgets and returns the root window, which is usually named "Form1". It automatically resolves parent-child relations, so the order of WIDGETS does not matter. Moreover, if a parent widget is passed as a parameter to a children widget, the parameter is deferred and passed after the creation using "::set" call.
During the parsing and creation process internal notifications can be invoked. These notifications (events) are stored in .fm file and usually provide class-specific loading instructions. See Events for details.
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 tell explicitly that FILENAME is a file system path name, FILENAME must be prefixed with "<" symbol ( the syntax is influenced by "CORE::open" ).
%PARAMETERS is a hash with custom parameters passed to widgets during creation. The widgets are distinguished by the names. Visual Builder ensures that no widgets have equal names.
If the form file loaded successfully, returns the form object reference. Otherwise, "undef" is returned and the error string is stored in $@ variable.
The events section is located in "actions" section of widget entry. There can be more than one event of each type, registered to different widgets. NAME parameter is a string with name of the widget; INSTANCE is a hash, created during load for every widget provided to keep internal event-specific or class-specific data there. "extras" section of widget entry is present there as an only predefined key.
# 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 is needed to be loaded before the parsing; this is useful, for example, if a constant is declared in the module.
# [preload] Prima::ComboBox
The main part of a file is enclosed in "sub{}" statement. After evaluation, this sub returns array of paired scalars, where each first item is a widget name and second item is 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],
}},
);
}
The hash has several predefined keys: