NAME

Prima::VB::VBLoader - Visual Builder file loader

DESCRIPTION

The module provides functionality for loading resource files created by Visual Builder. After a successful load, the newly created window with all children is returned.

SYNOPSIS

A simple way to use the loader is as follows:

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

All form widgets can be supplied with custom parameters, combined in a hash of hashes, and passed as the second parameter to the VBLoad() function. The example above supplies values for the ::centered property to the Form1 widget, which is the default name for 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 another data source, the AUTOFORM_REALIZE method can be used to transform the array of hashes that describes the form widget hierarchy into a set of widgets:

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

There are several examples of how the form files are 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 that the first line of the .fm file for the 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 the version string.

GO_SUB SUB [ @EXTRA_DATA ]

Depending on the value of the 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 the sub{} context and returns the code reference. If the evaluation fails, EXTRA_DATA is stored in the Prima::VB::VBLoader::eventContext array and the exception is re-thrown. Prima::VB::VBLoader::builderActive is an internal flag that helps the Visual Builder to use the module interface without actual evaluation of the SUB code.

AUTOFORM_REALIZE WIDGETS, PARAMETERS

WIDGETS is an array reference which contains evaluated data of the content of a .fm file, assuming its format is preserved. PARAMETERS is a hash reference with custom parameters passed to widgets during the creation. The widgets are distinguished by their names. Visual Builder ensures 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 parent-child relations, so the order in which WIDGETS are specified does not matter. Moreover, if a parent widget is passed as a parameter to a child widget, the parameter is deferred and passed only after the creation using the ::set call.

During the parsing and the 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 details.

AUTOFORM_CREATE FILENAME, %PARAMETERS

Reads FILENAME in the .fm file format, checks its version, loads, and creates a widget tree. Upon successful load, the root widget is returned. The parsing and creation are performed by calling AUTOFORM_REALIZE. If loading fails, die() is called.

Prima::VBLoad FILENAME, %PARAMETERS

A wrapper around AUTOFORM_CREATE is exported in the 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 the < symbol ( the syntax is influenced by CORE::open ).

%PARAMETERS is a hash with custom parameters passed to the widgets during the creation. The widgets are distinguished by their 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 the $@ variable.

Events

The events stored in the .fm file are executed during the loading process. The module provides no functionality for supplying extra events during the load. This interface is useful only for developers of new widget classes for Visual Builder.

The events section is located in the actions section of the widget entry. There can be more than one event of each type, registered to different widgets. NAME parameter is a string with the name of the widget. INSTANCE is a hash created during load for every widget, and is provided to keep internal event-specific or class-specific data 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, which 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 idea of the format of the .fm file is that it should be evaluated by the perl eval() call without special manipulations and kept as plain text. The file starts with a header which is a #-prefixed string, and contains a signature, the version of 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 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 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],
                        }},
                );
        }

The hash has several predefined keys:

actions HASH

Contains a hash of events. The 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; is 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

cpanm Prima

perl -MCPAN -e shell
install Prima