NAME¶
Prima::VB::VBLoader - Visual Builder file loader
DESCRIPTION¶
The module provides functionality for loading resource files, created by Visual
Builder. After the successful load, the newly created window with all children
is returned.
SYNOPSIS¶
The simple way to use the loader is as that:
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".
API¶
Methods¶
- check_version HEADER
- Scans HEADER, - the first line of a .fm file for version info. Returns two
scalars - the first is a boolean flag, which is set to 1 if the file can
be used and loaded, 0 otherwise. The second scalar is a version
string.
- GO_SUB SUB [ @EXTRA_DATA ]
- Depending on value of boolean flag
"Prima::VB::VBLoader::builderActive" performs the following: if
it is 1, the SUB text is returned as is. If it is 0, evaluates it in
"sub{}" context and returns the code reference. If evaluation
fails, EXTRA_DATA is stored in
"Prima::VB::VBLoader::eventContext" array and the exception is
re-thrown. "Prima::VB::VBLoader::builderActive" is an internal
flag that helps the Visual Builder use the module interface without actual
SUB evaluation.
- AUTOFORM_REALIZE WIDGETS, PARAMETERS
- WIDGETS is an array reference that contains evaluated data of the read
content of .fm file ( its data format is preserved). PARAMETERS is a hash
reference with custom parameters passed to widgets during creation. The
widgets are distinguished by the names. Visual Builder ensures that no
widgets have equal names.
"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.
- AUTOFORM_CREATE FILENAME, %PARAMETERS
- Reads FILENAME in .fm file format, checks its version, loads, and creates
widget tree. Upon successful load the root widget is returned. The parsing
and creation is performed by calling "AUTOFORM_REALIZE". If
loading fails, "die()" is called.
- Prima::VBLoad FILENAME, %PARAMETERS
- A wrapper around "AUTOFORM_CREATE", exported in
"Prima" namespace. FILENAME can be specified either as a file
system path name, or as a relative module name. In a way,
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.
Events¶
The events, stored in .fm file are called during the loading process. The module
provides no functionality for supplying the events during the load. This
interface is useful only for developers of Visual Builder - ready classes.
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.
- Begin NAME, INSTANCE
- Called upon beginning of widget tree creation.
- FormCreate NAME, INSTANCE, ROOT_WIDGET
- Called after the creation of a form, which reference is contained in
ROOT_WIDGET.
- Create NAME, INSTANCE, WIDGET.
- Called after the creation of the widget. The newly created widget is
passed in WIDGET
- Child NAME, INSTANCE, WIDGET, CHILD_NAME
- Called before child of WIDGET is created with CHILD_NAME as name.
- ChildCreate NAME, INSTANCE, WIDGET, CHILD_WIDGET.
- Called after 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.
The idea of format of .fm file is that is should be evaluated by perl
"eval()" call without special manipulations, and kept as plain text.
The file begins with a header, which is a #-prefixed string, and contains a
signature, version of file format, and 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 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:
- actions HASH
- Contains hash of events. The events are evaluated via "GO_SUB"
mechanism and executed during creation of the widget tree. See Events for
details.
- code STRING
- Contains a code, executed before the form is created. This key is present
only on the root widget record.
- class STRING
- Contains name of a class to be instantiated.
- extras HASH
- Contains a class-specific parameters, used by events.
- module STRING
- Contains name of perl module that contains the class. The module will be
"use"'d by the loader.
- parent BOOLEAN
- A boolean flag; set to 1 for the root widget only.
- profile HASH
- Contains profile hash, passed as parameters to the widget during its
creation. If custom parameters were passed to "AUTOFORM_CREATE",
these are coupled with "profile" ( the custom parameters take
precedence ) before passing to the "create()" call.
AUTHOR¶
Dmitry Karasik, <dmitry@karasik.eu.org>.
SEE ALSO¶
Prima, VB