NAME
VB - Visual Builder for the Prima toolkit
DESCRIPTION
Visual Builder is a RAD-style suite for designing forms under the Prima
toolkit. It provides rich set of perl-composed widgets, whose can be
inserted into a form by simple actions. The form can be stored in a
file and loaded by either user program or a simple wrapper,
"utils/fmview.pl"; the form can be also stored as a valid perl program.
A form file typically has .fm extension, an can be loaded by using
Prima::VB::VBLoader module. The following example is the only content
of "fmview.pl":
use Prima qw(Application VB::VBLoader);
my $ret = Prima::VBLoad( $ARGV[0] );
die "$@\n" unless $ret;
$ret-> execute;
and is usually sufficient for executing a form file.
Help
The builder provides three main windows, that are used for designing.
These are called main panel, object inspector and form window. When the
builder is started, the form window is empty.
The main panel consists of the menu bar, speed buttons and the widget
buttons. If the user presses a widget button, and then clicks the mouse
on the form window, the designated widget is inserted into the form and
becomes a child of the form window. If the click was made on a visible
widget in the form window, the newly inserted widget becomes a children
of that widget. After the widget is inserted, its properties are
accessible via the object inspector window.
The menu bar contains the following commands:
File
New Closes the current form and opens a new, empty form. If the
old form was not saved, the user is asked if the changes made
have to be saved.
This command is an alias to a ’new file’ icon on the panel.
Open
Invokes a file open dialog, so a .fm form file can be opened.
After the successful file load, all form widgets are visible
and available for editing.
This command is an alias to an ’open folder’ icon on the panel.
Save
Stores the form into a file. The user here can select a type of
the file to be saved. If the form is saved as .fm form file,
then it can be re-loaded either in the builder or in the user
program ( see Prima::VB::VBLoader for details ). If the form
is saved as .pl program, then it can not be loaded; instead,
the program can be run immediately without the builder or any
supplementary code.
Once the user assigned a name and a type for the form, it is
never asked when selecting this command.
This command is an alias to a ’save on disk’ icon on the panel.
Save as
Same as Save, except that a new name or type of file are asked
every time the command is invoked.
Close
Closes the form and removes the form window. If the form window
was changed, the user is asked if the changes made have to be
saved.
Edit
Copy
Copies the selected widgets into the clipboard, so they can be
inserted later by using Paste command. The form window can not
be copied.
Paste
Reads the information, put by the builder Copy command into the
clipboard, and inserts the widgets into the form window. The
child-parent relation is kept by names of the widgets; if the
widget with the name of the parent of the clipboard-read
widgets is not found, the widgets are inserted into the form
window. The form window is not affected by this command.
Delete
Deletes the selected widgets. The form window can not be
deleted.
Select all
Selects all of the widgets, inserted in the form window, except
the form window itself.
Duplicate
Duplicates the selected widgets. The form window is not
affected by this command.
Align
This menu item contains z-ordering actions, that are performed
on selected widgets. These are:
Bring to front Send to back Step forward Step backward Restore
order
Change class
Changes the class of an inserted widget. This is an advanced
option, and can lead to confusions or errors, if the default widget
class and the supplied class differ too much. It is used when the
widget that has to be inserted is not present in the builder
installation. Also, it is called implicitly when a loaded form does
not contain a valid widget class; in such case Prima::Widget class
is assigned.
Creation order
Opens the dialog, that manages the creation order of the widgets.
It is not that important for the widget child-parent relation,
since the builder tracks these, and does not allow a child to be
created before its parent. However, the explicit order might be
helpful in a case, when, for example, "tabOrder" property is left
to its default value, so it is assigned according to the order of
widget creation.
Toggle lock
Changes the lock status for selected widgets. The lock, if set,
prevents a widget from being selected by mouse, to avoid occasional
positional changes. This is useful when a widget is used as owner
for many sub-widgets.
Ctrl+mouse click locks and unlocks a widget.
View
Object inspector
Brings the object inspector window, if it was hidden or closed.
Add widgets
Opens a file dialog, where the additional VB modules can be
located. The modules are used for providing custom widgets and
properties for the builder. As an example, the
Prima/VB/examples/Widgety.pm module is provided with the
builder and the toolkit. Look inside this file for the
implementation details.
Reset guidelines
Reset the guidelines on the form window into a center position.
Snap to guidelines
Specifies if the moving and resizing widget actions must treat
the form window guidelines as snapping areas.
Snap to grid
Specifies if the moving and resizing widget actions must use
the form window grid granularity instead of the pixel
granularity.
Run This command hides the form and object inspector windows and
’executes’ the form, as if it would be run by "fmview.pl". The
execution session ends either by closing the form window or by
calling Break command.
This command is an alias to a ’run’ icon on the panel.
Break
Explicitly terminates the execution session, initiated by Run
command.
Help
About
Displays the information about the visual builder.
Help
Displays the information about the usage of the visual builder.
Widget property
Invokes a help viewer on Prima::Widget manpage and tries to
open a topic, corresponding to the current selection of the
object inspector property or event list. While this manpage
covers far not all ( but still many ) properties and events, it
is still a little bit more convenient than nothing.
Form window
The form widget is a common parent for all widgets, created by the
builder. The form window provides the following basic navigation
functionality.
Guidelines
The form window contains two guidelines, the horizontal and the
vertical, drawn as blue dashed lines. Dragging with the mouse can
move these lines. If menu option "Snap to guidelines" is on, the
widgets moving and sizing operations treat the guidelines as the
snapping areas.
Selection
A widget can be selected by clicking with the mouse on it. There
can be more than one selected widget at a time, or none at all. To
explicitly select a widget in addition to the already selected
ones, hold the "shift" key while clicking on a widget. This
combination also deselects the widget. To select all widgets on the
form window, call "Select all" command from the menu. To prevent
widgets from being occasionally selected, lock them with
"Edit/Toggle lock" command or Ctrl+mouse click.
Moving
Dragging the mouse can move the selected widgets. The widgets can
be snapped to the grid or the guidelines during the move. If one of
the moving widgets is selected in the object inspector window, the
coordinate changes are reflected in the "origin" property.
If the "Tab" key is pressed during the move, the mouse pointer is
changed between three states, each reflecting the currently
accessible coordinates for dragging. The default accessible
coordinates are both the horizontal and the vertical; other two are
the horizontal only and the vertical only.
Sizing
The sizeable widgets can be dynamically resized. Regardless to the
amount of the selected widgets, only one widget at a time can be
resized. If the resized widget is selected in the object inspector
window, the size changes are reflected in the "size" property.
Context menus
The right-click ( or the other system-defined pop-up menu
invocation command) provides the menu, identical to the main
panel’s Edit submenu.
The alternative context menus can be provided with some widgets (
for example, "TabbedNotebook" ), and are accessible with "control +
right click" combination.
Object inspector window
The inspector window reflects the events and properties of a widget.
To explicitly select a widget, it must be either clicked by the mouse
on the form window, or selected in the widget combo-box. Depending on
whether the properties or the events are selected, the left panel of
the inspector provides the properties or events list, and the right
panel - a value of the currently selected property or event. To toggle
between the properties and the events, use the button below the list.
The adjustable properties of a widget include an incomplete set of the
properties, returned by the class method "profile_default" ( the
detailed explanation see in Prima::Object). Among these are such basic
properties as "origin", "size", "name", "color", "font", "visible",
"enabled", "owner" and many others. All the widgets share some common
denominator, but almost all provide their own intrinsic properties.
Each property can be selected by the right-pane hosted property
selector; in such case, the name of a property is highlighted in the
list - that means, that the property is initialized. To remove a
property from the initialization list, double-click on it, so it is
grayed again. Some very basic properties as "name" can not be
deselected. This is because the builder keeps a name-keyed list;
another consequence of this fact is that no widgets of same name can
exist simultaneously within the builder.
The events, much like the properties, are accessible for direct change.
All the events provide a small editor, so the custom code can be
supplied. This code is executed when the form is run or loaded via
"Prima::VB::VBLoader" interface.
The full explanation of properties and events is not provided here. It
is not even the goal of this document, because the builder can work
with the widgets irrespective of their property or event capabilities;
this information is extracted by native toolkit functionality. To read
on what each property or event means, use the documentation on the
class of interest; Prima::Widget is a good start because it encompasses
the ground "Prima::Widget" functionality. The other widgets are (
hopefully ) documented in their modules, for example,
"Prima::ScrollBar" documentation can be found in Prima::ScrollBar.
SEE ALSO
Prima, Prima::VB::VBLoader
AUTHOR
Dmitry Karasik, <dmitry@karasik.eu.org>.
COPYRIGHT
This program is distributed under the BSD License.