Provided by: libprima-perl_1.28-1.2_amd64 bug

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.

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