1VB(1)                 User Contributed Perl Documentation                VB(1)
2
3
4

NAME

6       VB - Visual Builder for the Prima toolkit
7

DESCRIPTION

9       Visual Builder is a RAD-style suite for designing forms under the Prima
10       toolkit. It provides rich set of perl-composed widgets, whose can be
11       inserted into a form by simple actions. The form can be stored in a
12       file and loaded by either user program or a simple wrapper,
13       "utils/prima-fmview.pl"; the form can be also stored as a valid perl
14       program.
15
16       A form file typically has .fm extension, an can be loaded by using
17       Prima::VB::VBLoader module. The following example is the only content
18       of "prima-fmview.pl":
19
20               use Prima qw(Application VB::VBLoader);
21               my $ret = Prima::VBLoad( $ARGV[0] );
22               die "$@\n" unless $ret;
23               $ret-> execute;
24
25       and is usually sufficient for executing a form file.
26

Help

28       The builder provides three main windows, that are used for designing.
29       These are called main panel, object inspector and form window. When the
30       builder is started, the form window is empty.
31
32       The main panel consists of the menu bar, speed buttons and the widget
33       buttons. If the user presses a widget button, and then clicks the mouse
34       on the form window, the designated widget is inserted into the form and
35       becomes a child of the form window.  If the click was made on a visible
36       widget in the form window, the newly inserted widget becomes a children
37       of that widget. After the widget is inserted, its properties are
38       accessible via the object inspector window.
39
40       The menu bar contains the following commands:
41
42       File
43           New Closes the current form and opens a new, empty form.  If the
44               old form was not saved, the user is asked if the changes made
45               have to be saved.
46
47               This command is an alias to a 'new file' icon on the panel.
48
49           Open
50               Invokes a file open dialog, so a .fm form file can be opened.
51               After the successful file load, all form widgets are visible
52               and available for editing.
53
54               This command is an alias to an 'open folder' icon on the panel.
55
56           Save
57               Stores the form into a file. The user here can select a type of
58               the file to be saved. If the form is saved as .fm form file,
59               then it can be re-loaded either in the builder or in the user
60               program ( see Prima::VB::VBLoader for details ).  If the form
61               is saved as .pl program, then it can not be loaded; instead,
62               the program can be run immediately without the builder or any
63               supplementary code.
64
65               Once the user assigned a name and a type for the form, it is
66               never asked when selecting this command.
67
68               This command is an alias to a 'save on disk' icon on the panel.
69
70           Save as
71               Same as Save, except that a new name or type of file are asked
72               every time the command is invoked.
73
74           Close
75               Closes the form and removes the form window. If the form window
76               was changed, the user is asked if the changes made have to be
77               saved.
78
79       Edit
80           Copy
81               Copies the selected widgets into the clipboard, so they can be
82               inserted later by using Paste command.  The form window can not
83               be copied.
84
85           Paste
86               Reads the information, put by the builder Copy command into the
87               clipboard, and inserts the widgets into the form window. The
88               child-parent relation is kept by names of the widgets; if the
89               widget with the name of the parent of the clipboard-read
90               widgets is not found, the widgets are inserted into the form
91               window.  The form window is not affected by this command.
92
93           Delete
94               Deletes the selected widgets.  The form window can not be
95               deleted.
96
97           Select all
98               Selects all of the widgets, inserted in the form window, except
99               the form window itself.
100
101           Duplicate
102               Duplicates the selected widgets.  The form window is not
103               affected by this command.
104
105           Align
106               This menu item contains z-ordering actions, that are performed
107               on selected widgets.  These are:
108
109               Bring to front Send to back Step forward Step backward Restore
110               order
111
112       Change class
113           Changes the class of an inserted widget. This is an advanced
114           option, and can lead to confusions or errors, if the default widget
115           class and the supplied class differ too much. It is used when the
116           widget that has to be inserted is not present in the builder
117           installation. Also, it is called implicitly when a loaded form does
118           not contain a valid widget class; in such case Prima::Widget class
119           is assigned.
120
121       Creation order
122           Opens the dialog, that manages the creation order of the widgets.
123           It is not that important for the widget child-parent relation,
124           since the builder tracks these, and does not allow a child to be
125           created before its parent. However, the explicit order might be
126           helpful in a case, when, for example, "tabOrder" property is left
127           to its default value, so it is assigned according to the order of
128           widget creation.
129
130       Toggle lock
131           Changes the lock status for selected widgets. The lock, if set,
132           prevents a widget from being selected by mouse, to avoid occasional
133           positional changes.  This is useful when a widget is used as owner
134           for many sub-widgets.
135
136           Ctrl+mouse click locks and unlocks a widget.
137
138       View
139           Object inspector
140               Brings the object inspector window, if it was hidden or closed.
141
142           Add widgets
143               Opens a file dialog, where the additional VB modules can be
144               located.  The modules are used for providing custom widgets and
145               properties for the builder. As an example, the
146               Prima/VB/examples/Widgety.pm module is provided with the
147               builder and the toolkit. Look inside this file for the
148               implementation details.
149
150           Reset guidelines
151               Reset the guidelines on the form window into a center position.
152
153           Snap to guidelines
154               Specifies if the moving and resizing widget actions must treat
155               the form window guidelines as snapping areas.
156
157           Snap to grid
158               Specifies if the moving and resizing widget actions must use
159               the form window grid granularity instead of the pixel
160               granularity.
161
162           Run This command hides the form and object inspector windows and
163               'executes' the form, as if it would be run by
164               "prima-fmview.pl".  The execution session ends either by
165               closing the form window or by calling Break command.
166
167               This command is an alias to a 'run' icon on the panel.
168
169           Break
170               Explicitly terminates the execution session, initiated by Run
171               command.
172
173       Help
174           About
175               Displays the information about the visual builder.
176
177           Help
178               Displays the information about the usage of the visual builder.
179
180           Widget property
181               Invokes a help viewer on Prima::Widget manpage and tries to
182               open a topic, corresponding to the current selection of the
183               object inspector property or event list. While this manpage
184               covers far not all ( but still many ) properties and events, it
185               is still a little bit more convenient than nothing.
186
187   Form window
188       The form widget is a common parent for all widgets, created by the
189       builder. The form window provides the following basic navigation
190       functionality.
191
192       Guidelines
193           The form window contains two guidelines, the horizontal and the
194           vertical, drawn as blue dashed lines. Dragging with the mouse can
195           move these lines.  If menu option "Snap to guidelines" is on, the
196           widgets moving and sizing operations treat the guidelines as the
197           snapping areas.
198
199       Selection
200           A widget can be selected by clicking with the mouse on it. There
201           can be more than one selected widget at a time, or none at all.  To
202           explicitly select a widget in addition to the already selected
203           ones, hold the "shift" key while clicking on a widget. This
204           combination also deselects the widget. To select all widgets on the
205           form window, call "Select all" command from the menu. To prevent
206           widgets from being occasionally selected, lock them with
207           "Edit/Toggle lock" command or Ctrl+mouse click.
208
209       Moving
210           Dragging the mouse can move the selected widgets. The widgets can
211           be snapped to the grid or the guidelines during the move. If one of
212           the moving widgets is selected in the object inspector window, the
213           coordinate changes are reflected in the "origin" property.
214
215           If the "Tab" key is pressed during the move, the mouse pointer is
216           changed between three states, each reflecting the currently
217           accessible coordinates for dragging. The default accessible
218           coordinates are both the horizontal and the vertical; other two are
219           the horizontal only and the vertical only.
220
221       Sizing
222           The sizeable widgets can be dynamically resized. Regardless to the
223           amount of the selected widgets, only one widget at a time can be
224           resized.  If the resized widget is selected in the object inspector
225           window, the size changes are reflected in the "size" property.
226
227       Context menus
228           The right-click ( or the other system-defined pop-up menu
229           invocation command) provides the menu, identical to the main
230           panel's Edit submenu.
231
232           The alternative context menus can be provided with some widgets (
233           for example, "TabbedNotebook" ), and are accessible with "control +
234           right click" combination.
235
236   Object inspector window
237       The inspector window reflects the events and properties of a widget.
238       To explicitly select a widget, it must be either clicked by the mouse
239       on the form window, or selected in the widget combo-box. Depending on
240       whether the properties or the events are selected, the left panel of
241       the inspector provides the properties or events list, and the right
242       panel - a value of the currently selected property or event. To toggle
243       between the properties and the events, use the button below the list.
244
245       The adjustable properties of a widget include an incomplete set of the
246       properties, returned by the class method "profile_default" ( the
247       detailed explanation see in Prima::Object). Among these are such basic
248       properties as "origin", "size", "name", "color", "font", "visible",
249       "enabled", "owner" and many others.  All the widgets share some common
250       denominator, but almost all provide their own intrinsic properties.
251       Each property can be selected by the right-pane hosted property
252       selector; in such case, the name of a property is highlighted in the
253       list - that means, that the property is initialized. To remove a
254       property from the initialization list, double-click on it, so it is
255       grayed again. Some very basic properties as "name" can not be
256       deselected. This is because the builder keeps a name-keyed list;
257       another consequence of this fact is that no widgets of same name can
258       exist simultaneously within the builder.
259
260       The events, much like the properties, are accessible for direct change.
261       All the events provide a small editor, so the custom code can be
262       supplied.  This code is executed when the form is run or loaded via
263       "Prima::VB::VBLoader" interface.
264
265       The full explanation of properties and events is not provided here. It
266       is not even the goal of this document, because the builder can work
267       with the widgets irrespective of their property or event capabilities;
268       this information is extracted by native toolkit functionality. To read
269       on what each property or event means, use the documentation on the
270       class of interest; Prima::Widget is a good start because it encompasses
271       the ground "Prima::Widget" functionality.  The other widgets are (
272       hopefully ) documented in their modules, for example,
273       "Prima::ScrollBar" documentation can be found in Prima::ScrollBar.
274

SEE ALSO

276       Prima, Prima::VB::VBLoader
277

AUTHOR

279       Dmitry Karasik, <dmitry@karasik.eu.org>.
280
282       This program is distributed under the BSD License.
283
284
285
286perl v5.38.0                      2023-07-21                             VB(1)
Impressum