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

FILE FORMAT

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