|
Prima::VB::VBLoader - Visual Builder file loader |
Prima::VB::VBLoader - Visual Builder file loader
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.
The simple way to use the loader is as that:
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:
eval "use Prima::VB::VBLoader"; die "$@\n" if $@;
$form = Prima::VBLoad( $fi,
'Form1' => { visible => 0, centered => 1},
);
die "$@\n" unless $form;
Prima::message("Error in setup resource: $@");
return;
}
Prima::VB::VBLoader::builderActive
perrofms 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 forwarded.
Prima::VB::VBLoader::builderActive is an internal flag that helps the
Visual Builder use the module interface without actual SUB evaluation.
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 some events can be are invoked. These events are stored in .fm file and usually provide class-specific loading instructions. See Events for details.
AUTOFORM_REALIZE. If loading fails, die() is called.
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::find_image( 'Module' 'form.fm')
are identical. If the procedure finds that FILENAME is a relative
module name, it calls Prima::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, 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.
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:
GO_SUB mechanism
and executed during creation of the widget tree. See Events for details.
use'd by the loader.
AUTOFORM_CREATE, these are coupled with profile
( the custom parameters take precedence ) before passing
to the create() call.
Dmitry Karasik, <dmitry@karasik.eu.org>.
Prima, VB
|
Prima::VB::VBLoader - Visual Builder file loader |