1Prima::VB::VBLoader(3)User Contributed Perl DocumentationPrima::VB::VBLoader(3)
2
6 Prima::VB::VBLoader - Visual Builder file loader
7
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
14 The simple way to use the loader is as that:
15 use Prima qw(Application);
17 use Prima::VB::VBLoader;
18 Prima::VBLoad( './your_resource.fm',
19 Form1 => { centered => 1 },
20 )-> execute;
21 A more complicated but more proof code can be met in the toolkit:
23 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 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 $form = Prima::VBLoad( $fi,
40 ....
41 'StartButton' => {
42 onMouseOver => sub { die "No start buttons here\n" },
43 }
44 );
45 ...
46 $form-> StartButton-> hide;
47 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 $form = AUTOFORM_REALIZE( [ Form1 => {
53 class => 'Prima::Window',
54 parent => 1,
55 profile => {
56 name => 'Form1',
57 size => [ 330, 421],
58 }], {});
59 Real-life examples are met across the toolkit; for instance,
61 Prima/PS/setup.fm dialog is used by "Prima::PS::Setup".
62
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 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 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 "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 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 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 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 Prima::VBLoad( 'Module::form.fm' )
113 and
115 Prima::VBLoad(
117 Prima::Utils::find_image( 'Module' 'form.fm'))
118 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 %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 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 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 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 Begin NAME, INSTANCE
147 Called upon beginning of widget tree creation.
148 FormCreate NAME, INSTANCE, ROOT_WIDGET
150 Called after the creation of a form, which reference is contained
151 in ROOT_WIDGET.
152 Create NAME, INSTANCE, WIDGET.
154 Called after the creation of the widget. The newly created widget
155 is passed in WIDGET
156 Child NAME, INSTANCE, WIDGET, CHILD_NAME
158 Called before child of WIDGET is created with CHILD_NAME as name.
159 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 End NAME, INSTANCE, WIDGET
165 Called after the creation of all widgets is finished.
166
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 # VBForm version file=1 builder=0.1
175 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 # [preload] Prima::ComboBox
182 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 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 The hash has several predefined keys:
206 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 code STRING
213 Contains a code, executed before the form is created. This key is
214 present only on the root widget record.
215 class STRING
217 Contains name of a class to be instantiated.
218 extras HASH
220 Contains a class-specific parameters, used by events.
221 module STRING
223 Contains name of perl module that contains the class. The module
224 will be "use"'d by the loader.
225 parent BOOLEAN
227 A boolean flag; set to 1 for the root widget only.
228 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
236 Dmitry Karasik, <dmitry@karasik.eu.org>.
237
239 Prima, VB
240perl v5.38.0 2023-07-21 Prima::VB::VBLoader(3)