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.