Man Linux: Main Page and Category List


       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 qw(Application);
               use Prima::VB::VBLoader;
               Prima::VBLoad( './',
                       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/ dialog is used by "Prima::PS::Setup".


       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.

           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

           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.

           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.

           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( '' )


                           Prima::Utils::find_image( 'Module' ''))

           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, 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.

           Called after the creation of a form, which reference is contained
           in ROOT_WIDGET.

           Called after the creation of the widget. The newly created widget
           is passed in WIDGET

           Called before child of WIDGET is created with CHILD_NAME as name.

           Called after child of WIDGET is created; the newly created widget
           is passed in CHILD_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:

                       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.


       Dmitry Karasik, <>.


       Prima, VB