1Prima::VB::VBLoader(3)User Contributed Perl DocumentationPrima::VB::VBLoader(3)
2
3
4

NAME

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

DESCRIPTION

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

SYNOPSIS

14       The simple way to use the loader is as that:
15
16               use Prima qw(Application);
17               use Prima::VB::VBLoader;
18               Prima::VBLoad( './your_resource.fm',
19                       Form1 => { centered => 1 },
20               )-> execute;
21
22       A more complicated but more proof code can be met in the toolkit:
23
24               use Prima qw(Application);
25               eval "use Prima::VB::VBLoader"; die "$@\n" if $@;
26               $form = Prima::VBLoad( $fi,
27                       'Form1'     => { visible => 0, centered => 1},
28               );
29               die "$@\n" unless $form;
30
31       All form widgets can be supplied with custom parameters, all together
32       combined in a hash of hashes and passed as the second parameter to
33       VBLoad() function.  The example above supplies values for "::visible"
34       and "::centered" to "Form1" widget, which is default name of a form
35       window created by Visual Builder. All other widgets are accessible by
36       their names in a similar fashion; after the creation, the widget
37       hierarchy can be accessed in the standard way:
38
39               $form = Prima::VBLoad( $fi,
40                       ....
41                       'StartButton' => {
42                               onMouseOver => sub { die "No start buttons here\n" },
43                       }
44               );
45               ...
46               $form-> StartButton-> hide;
47
48       In case a form is to be included not from a fm file but from other data
49       source, AUTOFORM_REALIZE call can be used to transform perl array into
50       set of widgets:
51
52               $form = AUTOFORM_REALIZE( [ Form1 => {
53                       class   => 'Prima::Window',
54                       parent  => 1,
55                       profile => {
56                               name => 'Form1',
57                               size => [ 330, 421],
58                       }], {});
59
60       Real-life examples are met across the toolkit; for instance,
61       Prima/PS/setup.fm dialog is used by "Prima::PS::Setup".
62

API

64   Methods
65       check_version HEADER
66           Scans HEADER, - the first line of a .fm file for version info.
67           Returns two scalars - the first is a boolean flag, which is set to
68           1 if the file can be used and loaded, 0 otherwise. The second
69           scalar is a version string.
70
71       GO_SUB SUB [ @EXTRA_DATA ]
72           Depending on value of boolean flag
73           "Prima::VB::VBLoader::builderActive" performs the following: if it
74           is 1, the SUB text is returned as is.  If it is 0, evaluates it in
75           "sub{}" context and returns the code reference.  If evaluation
76           fails, EXTRA_DATA is stored in "Prima::VB::VBLoader::eventContext"
77           array and the exception is re-thrown.
78           "Prima::VB::VBLoader::builderActive" is an internal flag that helps
79           the Visual Builder use the module interface without actual SUB
80           evaluation.
81
82       AUTOFORM_REALIZE WIDGETS, PARAMETERS
83           WIDGETS is an array reference that contains evaluated data of the
84           read content of .fm file ( its data format is preserved).
85           PARAMETERS is a hash reference with custom parameters passed to
86           widgets during creation. The widgets are distinguished by the
87           names.  Visual Builder ensures that no widgets have equal names.
88
89           "AUTOFORM_REALIZE" creates the tree of widgets and returns the root
90           window, which is usually named "Form1". It automatically resolves
91           parent-child relations, so the order of WIDGETS does not matter.
92           Moreover, if a parent widget is passed as a parameter to a children
93           widget, the parameter is deferred and passed after the creation
94           using "::set" call.
95
96           During the parsing and creation process internal notifications can
97           be invoked.  These notifications (events) are stored in .fm file
98           and usually provide class-specific loading instructions. See Events
99           for details.
100
101       AUTOFORM_CREATE FILENAME, %PARAMETERS
102           Reads FILENAME in .fm file format, checks its version, loads, and
103           creates widget tree. Upon successful load the root widget is
104           returned. The parsing and creation is performed by calling
105           "AUTOFORM_REALIZE". If loading fails, die() is called.
106
107       Prima::VBLoad FILENAME, %PARAMETERS
108           A wrapper around "AUTOFORM_CREATE", exported in "Prima" namespace.
109           FILENAME can be specified either as a file system path name, or as
110           a relative module name. In a way,
111
112                   Prima::VBLoad( 'Module::form.fm' )
113
114           and
115
116                   Prima::VBLoad(
117                           Prima::Utils::find_image( 'Module' 'form.fm'))
118
119           are identical. If the procedure finds that FILENAME is a relative
120           module name, it calls "Prima::Utils::find_image" automatically. To
121           tell explicitly that FILENAME is a file system path name, FILENAME
122           must be prefixed with "<" symbol ( the syntax is influenced by
123           "CORE::open" ).
124
125           %PARAMETERS is a hash with custom parameters passed to widgets
126           during creation. The widgets are distinguished by the names.
127           Visual Builder ensures that no widgets have equal names.
128
129           If the form file loaded successfully, returns the form object
130           reference.  Otherwise, "undef" is returned and the error string is
131           stored in $@ variable.
132
133   Events
134       The events, stored in .fm file are called during the loading process.
135       The module provides no functionality for supplying the events during
136       the load. This interface is useful only for developers of Visual
137       Builder - ready classes.
138
139       The events section is located in "actions" section of widget entry.
140       There can be more than one event of each type, registered to different
141       widgets.  NAME parameter is a string with name of the widget; INSTANCE
142       is a hash, created during load for every widget provided to keep
143       internal event-specific or class-specific data there. "extras" section
144       of widget entry is present there as an only predefined key.
145
146       Begin NAME, INSTANCE
147           Called upon beginning of widget tree creation.
148
149       FormCreate NAME, INSTANCE, ROOT_WIDGET
150           Called after the creation of a form, which reference is contained
151           in ROOT_WIDGET.
152
153       Create NAME, INSTANCE, WIDGET.
154           Called after the creation of the widget. The newly created widget
155           is passed in WIDGET
156
157       Child NAME, INSTANCE, WIDGET, CHILD_NAME
158           Called before child of WIDGET is created with CHILD_NAME as name.
159
160       ChildCreate NAME, INSTANCE, WIDGET, CHILD_WIDGET.
161           Called after child of WIDGET is created; the newly created widget
162           is passed in CHILD_WIDGET.
163
164       End NAME, INSTANCE, WIDGET
165           Called after the creation of all widgets is finished.
166

FILE FORMAT

168       The idea of format of .fm file is that is should be evaluated by perl
169       eval() call without special manipulations, and kept as plain text.  The
170       file begins with a header, which is a #-prefixed string, and contains a
171       signature, version of file format, and version of the creator of the
172       file:
173
174               # VBForm version file=1 builder=0.1
175
176       The header can also contain additional headers, also prefixed with #.
177       These can be used to tell the loader that another perl module is needed
178       to be loaded before the parsing; this is useful, for example, if a
179       constant is declared in the module.
180
181               # [preload] Prima::ComboBox
182
183       The main part of a file is enclosed in "sub{}" statement.  After
184       evaluation, this sub returns array of paired scalars, where each first
185       item is a widget name and second item is hash of its parameters and
186       other associated data:
187
188               sub
189               {
190                       return (
191                               'Form1' => {
192                                       class   => 'Prima::Window',
193                                       module  => 'Prima::Classes',
194                                       parent => 1,
195                                       code   => GO_SUB('init()'),
196                                       profile => {
197                                               width => 144,
198                                               name => 'Form1',
199                                               origin => [ 490, 412],
200                                               size => [ 144, 100],
201                               }},
202                       );
203               }
204
205       The hash has several predefined keys:
206
207       actions HASH
208           Contains hash of events. The events are evaluated via "GO_SUB"
209           mechanism and executed during creation of the widget tree. See
210           Events for details.
211
212       code STRING
213           Contains a code, executed before the form is created.  This key is
214           present only on the root widget record.
215
216       class STRING
217           Contains name of a class to be instantiated.
218
219       extras HASH
220           Contains a class-specific parameters, used by events.
221
222       module STRING
223           Contains name of perl module that contains the class. The module
224           will be "use"'d by the loader.
225
226       parent BOOLEAN
227           A boolean flag; set to 1 for the root widget only.
228
229       profile HASH
230           Contains profile hash, passed as parameters to the widget during
231           its creation. If custom parameters were passed to
232           "AUTOFORM_CREATE", these are coupled with "profile" ( the custom
233           parameters take precedence ) before passing to the create() call.
234

AUTHOR

236       Dmitry Karasik, <dmitry@karasik.eu.org>.
237

SEE ALSO

239       Prima, VB
240
241
242
243perl v5.38.0                      2023-07-21            Prima::VB::VBLoader(3)
Impressum