|
|
| |
VB(1) |
User Contributed Perl Documentation |
VB(1) |
VB - Visual Builder for the Prima toolkit
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/prima-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 "prima-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.
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
"prima-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.
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.
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.
Prima, Prima::VB::VBLoader
Dmitry Karasik, <dmitry@karasik.eu.org>.
This program is distributed under the BSD License.
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |