.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Prima::VB::VBLoader 3"
.TH Prima::VB::VBLoader 3 "2009-02-24" "perl v5.20.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Prima::VB::VBLoader \- Visual Builder file loader
.SH "DESCRIPTION"
.IX Header "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.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
The simple way to use the loader is as that:
.PP
.Vb 5
\&        use Prima qw(Application);
\&        use Prima::VB::VBLoader;
\&        Prima::VBLoad( \*(Aq./your_resource.fm\*(Aq,
\&                Form1 => { centered => 1 },
\&        )\-> execute;
.Ve
.PP
A more complicated but more proof code can be met in the toolkit:
.PP
.Vb 6
\&        use Prima qw(Application);
\&        eval "use Prima::VB::VBLoader"; die "$@\en" if $@;
\&        $form = Prima::VBLoad( $fi,
\&                \*(AqForm1\*(Aq     => { visible => 0, centered => 1},
\&        );
\&        die "$@\en" unless $form;
.Ve
.PP
All form widgets can be supplied with custom parameters, all together combined
in a hash of hashes and passed as the second parameter to \f(CW\*(C`VBLoad()\*(C'\fR function.
The example above supplies values for \f(CW\*(C`::visible\*(C'\fR and \f(CW\*(C`::centered\*(C'\fR to
\&\f(CW\*(C`Form1\*(C'\fR 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:
.PP
.Vb 8
\&        $form = Prima::VBLoad( $fi,
\&                ....
\&                \*(AqStartButton\*(Aq => {
\&                        onMouseOver => sub { die "No start buttons here\en" },
\&                }
\&        );
\&        ...
\&        $form\-> StartButton\-> hide;
.Ve
.PP
In case a form is to be included not from a fm file but from other data source,
\&\s-1AUTOFORM_REALIZE\s0 call can be used to transform perl array into set of
widgets:
.PP
.Vb 7
\&        $form = AUTOFORM_REALIZE( [ Form1 => {
\&                class   => \*(AqPrima::Window\*(Aq,
\&                parent  => 1,
\&                profile => {
\&                        name => \*(AqForm1\*(Aq,
\&                        size => [ 330, 421],
\&                }], {});
.Ve
.PP
Real-life examples are met across the toolkit; for instance,
\&\fIPrima/PS/setup.fm\fR dialog is used by \f(CW\*(C`Prima::PS::Setup\*(C'\fR.
.SH "API"
.IX Header "API"
.SS "Methods"
.IX Subsection "Methods"
.IP "check_version \s-1HEADER\s0" 4
.IX Item "check_version HEADER"
Scans \s-1HEADER, \-\s0 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.
.ie n .IP "\s-1GO_SUB SUB\s0 [ @EXTRA_DATA ]" 4
.el .IP "\s-1GO_SUB SUB\s0 [ \f(CW@EXTRA_DATA\fR ]" 4
.IX Item "GO_SUB SUB [ @EXTRA_DATA ]"
Depending on value of boolean flag \f(CW\*(C`Prima::VB::VBLoader::builderActive\*(C'\fR
performs the following: if it is 1, the \s-1SUB\s0 text is returned as is.
If it is 0, evaluates it in \f(CW\*(C`sub{}\*(C'\fR context and returns the code reference.
If evaluation fails, \s-1EXTRA_DATA\s0 is stored in \f(CW\*(C`Prima::VB::VBLoader::eventContext\*(C'\fR
array and the exception is re-thrown.
\&\f(CW\*(C`Prima::VB::VBLoader::builderActive\*(C'\fR is an internal flag that helps the
Visual Builder use the module interface without actual \s-1SUB\s0 evaluation.
.IP "\s-1AUTOFORM_REALIZE WIDGETS, PARAMETERS\s0" 4
.IX Item "AUTOFORM_REALIZE WIDGETS, PARAMETERS"
\&\s-1WIDGETS\s0 is an array reference that contains evaluated data of
the read content of .fm file ( its data format is preserved).  
\&\s-1PARAMETERS\s0 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.
.Sp
\&\f(CW\*(C`AUTOFORM_REALIZE\*(C'\fR creates the tree of widgets and returns the root
window, which is usually named \f(CW\*(C`Form1\*(C'\fR. It automatically resolves
parent-child relations, so the order of \s-1WIDGETS\s0 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 \f(CW\*(C`::set\*(C'\fR call.
.Sp
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.
.ie n .IP "\s-1AUTOFORM_CREATE FILENAME,\s0 %PARAMETERS" 4
.el .IP "\s-1AUTOFORM_CREATE FILENAME,\s0 \f(CW%PARAMETERS\fR" 4
.IX Item "AUTOFORM_CREATE FILENAME, %PARAMETERS"
Reads \s-1FILENAME\s0 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
\&\f(CW\*(C`AUTOFORM_REALIZE\*(C'\fR. If loading fails, \f(CW\*(C`die()\*(C'\fR is called.
.ie n .IP "Prima::VBLoad \s-1FILENAME,\s0 %PARAMETERS" 4
.el .IP "Prima::VBLoad \s-1FILENAME,\s0 \f(CW%PARAMETERS\fR" 4
.IX Item "Prima::VBLoad FILENAME, %PARAMETERS"
A wrapper around \f(CW\*(C`AUTOFORM_CREATE\*(C'\fR, exported in \f(CW\*(C`Prima\*(C'\fR
namespace. \s-1FILENAME\s0 can be specified either as a file system
path name, or as a relative module name. In a way,
.Sp
.Vb 1
\&        Prima::VBLoad( \*(AqModule::form.fm\*(Aq )
.Ve
.Sp
and
.Sp
.Vb 2
\&        Prima::VBLoad( 
\&                Prima::Utils::find_image( \*(AqModule\*(Aq \*(Aqform.fm\*(Aq))
.Ve
.Sp
are identical. If the procedure finds that \s-1FILENAME\s0 is a relative
module name, it calls \f(CW\*(C`Prima::Utils::find_image\*(C'\fR automatically. To
tell explicitly that \s-1FILENAME\s0 is a file system path name, \s-1FILENAME\s0
must be prefixed with \f(CW\*(C`<\*(C'\fR symbol ( the syntax is influenced by \f(CW\*(C`CORE::open\*(C'\fR ).
.Sp
\&\f(CW%PARAMETERS\fR 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.
.Sp
If the form file loaded successfully, returns the form object reference.
Otherwise, \f(CW\*(C`undef\*(C'\fR is returned and the error string is stored in \f(CW$@\fR
variable.
.SS "Events"
.IX Subsection "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.
.PP
The events section is located in \f(CW\*(C`actions\*(C'\fR section of widget entry.  There can
be more than one event of each type, registered to different widgets.  \s-1NAME\s0
parameter is a string with name of the widget; \s-1INSTANCE\s0 is a hash, created
during load for every widget provided to keep internal event-specific or
class-specific data there. \f(CW\*(C`extras\*(C'\fR section of widget entry is present there
as an only predefined key.
.IP "Begin \s-1NAME, INSTANCE\s0" 4
.IX Item "Begin NAME, INSTANCE"
Called upon beginning of widget tree creation.
.IP "FormCreate \s-1NAME, INSTANCE, ROOT_WIDGET\s0" 4
.IX Item "FormCreate NAME, INSTANCE, ROOT_WIDGET"
Called after the creation of a form, which reference is
contained in \s-1ROOT_WIDGET.\s0
.IP "Create \s-1NAME, INSTANCE, WIDGET.\s0" 4
.IX Item "Create NAME, INSTANCE, WIDGET."
Called after the creation of the widget. The newly created
widget is passed in \s-1WIDGET\s0
.IP "Child \s-1NAME, INSTANCE, WIDGET, CHILD_NAME\s0" 4
.IX Item "Child NAME, INSTANCE, WIDGET, CHILD_NAME"
Called before child of \s-1WIDGET\s0 is created with \s-1CHILD_NAME\s0 as name.
.IP "ChildCreate \s-1NAME, INSTANCE, WIDGET, CHILD_WIDGET.\s0" 4
.IX Item "ChildCreate NAME, INSTANCE, WIDGET, CHILD_WIDGET."
Called after child of \s-1WIDGET\s0 is created; the newly created
widget is passed in \s-1CHILD_WIDGET.\s0
.IP "End \s-1NAME, INSTANCE, WIDGET\s0" 4
.IX Item "End NAME, INSTANCE, WIDGET"
Called after the creation of all widgets is finished.
.SH "FILE FORMAT"
.IX Header "FILE FORMAT"
The idea of format of .fm file is that is should be evaluated by perl \f(CW\*(C`eval()\*(C'\fR
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:
.PP
.Vb 1
\&        # VBForm version file=1 builder=0.1
.Ve
.PP
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.
.PP
.Vb 1
\&        # [preload] Prima::ComboBox
.Ve
.PP
The main part of a file is enclosed in \f(CW\*(C`sub{}\*(C'\fR 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:
.PP
.Vb 10
\&        sub
\&        {
\&                return (
\&                        \*(AqForm1\*(Aq => {
\&                                class   => \*(AqPrima::Window\*(Aq,
\&                                module  => \*(AqPrima::Classes\*(Aq,
\&                                parent => 1,
\&                                code   => GO_SUB(\*(Aqinit()\*(Aq),
\&                                profile => {
\&                                        width => 144,
\&                                        name => \*(AqForm1\*(Aq,
\&                                        origin => [ 490, 412],
\&                                        size => [ 144, 100],
\&                        }},
\&                );
\&        }
.Ve
.PP
The hash has several predefined keys:
.IP "actions \s-1HASH\s0" 4
.IX Item "actions HASH"
Contains hash of events. The events are evaluated via \f(CW\*(C`GO_SUB\*(C'\fR mechanism
and executed during creation of the widget tree. See Events for details.
.IP "code \s-1STRING\s0" 4
.IX Item "code STRING"
Contains a code, executed before the form is created.
This key is present only on the root widget record.
.IP "class \s-1STRING\s0" 4
.IX Item "class STRING"
Contains name of a class to be instantiated.
.IP "extras \s-1HASH\s0" 4
.IX Item "extras HASH"
Contains a class-specific parameters, used by events.
.IP "module \s-1STRING\s0" 4
.IX Item "module STRING"
Contains name of perl module that contains the class. The module 
will be \f(CW\*(C`use\*(C'\fR'd by the loader.
.IP "parent \s-1BOOLEAN\s0" 4
.IX Item "parent BOOLEAN"
A boolean flag; set to 1 for the root widget only.
.IP "profile \s-1HASH\s0" 4
.IX Item "profile HASH"
Contains profile hash, passed as parameters to the widget
during its creation. If custom parameters were passed to
\&\f(CW\*(C`AUTOFORM_CREATE\*(C'\fR, these are coupled with \f(CW\*(C`profile\*(C'\fR
( the custom parameters take precedence ) before passing
to the \f(CW\*(C`create()\*(C'\fR call.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dmitry Karasik, <dmitry@karasik.eu.org>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Prima, \s-1VB\s0