VB(1)

💖 NAME 💖

okay so bestie, welcome to VB(1) from the User Contributed Perl Documentation — manual name? literally VB, and we are obsessed 🫶. VB - Visual Builder for the Prima toolkit. That's the whole icon behavior right there.

🦋 SYNOPSIS 🦋

Run the VB command in your terminal. That's the entrance. That's the whole move. 🎀

✨ DESCRIPTION ✨

Visual Builder is a RAD-style suite for designing forms using the Prima toolkit, and it is highkey giving "build a whole form without suffering" energy. It provides a rich set of perl-based widgets which can be inserted into a window-based form by simple actions. No cap, the widgets just go in. 🧚

The form can be stored in a file and loaded by either a user program or a simple wrapper, utils/prima-fmview.pl; the form can be also stored as a valid perl program. So yes, bestie, your form can live as a file, get loaded by a user program or that wrapper, or be saved as actual valid perl. 💅

A form file has the .fm extension and can be loaded fairly simply by using the Prima::VB::VBLoader module. The following code is the only content of the prima-fmview.pl program:

use Prima qw(Application VB::VBLoader);
my $ret = Prima::VBLoad( $ARGV[0] );
die "$@\n" unless $ret;
$ret-> execute;

Such code is usually sufficient for executing a form file. 🫶

🫶 Help 🫶

Okay so the builder gives you three main windows for interactive design, bestie, and they're called the main panel, the object inspector, and the form window. When the builder starts up, the form window is literally empty. Fresh slate energy. ✨

The main panel is made up of the menu bar, the speed buttons, and the widget buttons. Here's the move: you press a widget button, then click the mouse on the form window, and boom — the selected widget gets inserted into the form and becomes a child of the form window. And if that click landed on a visible widget that's already in the form window? Then the newly inserted widget becomes a child of that widget instead. Nested vibes 🪆. Once a widget is inserted, its properties are all accessible in the object inspector window.

The menu bar has these commands, bestie — buckle up:

🗂️ File

• New — closes the current form and opens a new empty one. If the old form wasn't saved, you get asked whether the changes you made should be saved. (Politeness icon 💅) This command is an alias to the 'new file' icon on the panel.
• Open — invokes the file open dialog so a .fm form file can be opened. After a successful file load, all form widgets are visible and available for editing. This command is an alias to the 'open folder' icon on the panel.
• Save — stores the form into a file. You get to pick the type of file to save as. If the form is saved as a .fm form file then it can be re-loaded either in the builder or a user program (see Prima::VB::VBLoader for details). If the form is saved as a .pl program, then it can not be loaded — instead, the program can be run immediately without the builder or any supplementary code. Slay. This command is an alias to the 'save on disk' icon on the panel.
• Save as — same as Save, except that a new name or type of file is asked every single time the command is invoked. Every time. 👀
• Close — closes the form and removes the form window. If the form window was changed, you get asked whether the changes made are to be saved.

✂️ Edit

• Copy — copies the selected widgets into the clipboard so they can be inserted later using the Paste command. Heads up: the form window itself can not be copied, only the widgets it contains. 🙈
• Paste — reads the information put into the clipboard by the builder Copy command and inserts the widgets into the form window. The child-parent relation is kept by the 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 instead. The form window is not affected by this command.
• Delete — deletes the selected widgets. And again: the form window itself can not be deleted. (Iconic of it, honestly.)
• Select all — selects all of the widgets inserted in the form window, except the form window itself. Obviously. 😌
• Duplicate — duplicates the selected widgets. The form window is not affected by this command.
• Align — this menu item contains z-ordering actions performed on selected widgets. These are:
  • Bring to front
  • Send to back
  • Step forward
  • Step backward
  • Restore order

🔄 Change class

Changes the class of the selected widget. This is an advanced option and can lead to confusion or errors if the default widget class and the supplied class differ too much — so, like, be careful fr. It's used when the widget that has to be inserted isn't present in the builder installation. Also, it gets called implicitly when the loaded form does not contain a valid widget class; in that case the Prima::Widget class is assigned. 🫡

🔢 Creation order

Opens the dialog that manages the creation order of the widgets. Ngl it's not that important for the widget child-parent relation, since the builder tracks those and does not allow a child to be created before its parent. But the explicit order might be helpful in a case when, for example, the "tabOrder" property is left to its default value, so it is assigned according to the order of widget creation. iykyk ✨

🔒 Toggle lock

Changes the lock status for selected widgets. The lock, if set, prevents widgets from being selected by the mouse, to avoid occasional positional changes. Super useful when a widget is used as an owner for many sub-widgets. 🧚

The ctrl+mouse combination click locks and unlocks widgets.

👀 View

• Object inspector — brings the object inspector window back, if it was hidden or closed. Come back bestie 😭
• Add widgets — opens the file dialog to install additional VB widgets. 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 — resets the guidelines on the form window back into the center.
• 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 the Break command. Main character energy 🔥 This command is an alias to the 'run' icon on the panel.
• Break — explicitly terminates the execution session initiated by the Run command. Stop button, but make it syntax. 💀

💜 Help

• About — displays the information about the visual builder.
• Help — displays the information about the usage of the visual builder.
• Widget property — invokes the help viewer on the Prima::Widget manpage and tries to open the topic corresponding to the current selection of the object inspector property or event. While the manpage covers far not all ( but still many ) properties and events, it is still a little bit more convenient than nothing. Lowkey relatable 🫠

---

🦋 Form window 🦋

The form widget is the common parent for all widgets created by the builder — the mother of the whole situation, honestly 👑. The form window provides the following basic navigation:

📏 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 the menu option "Snap to guidelines" is checked, the widgets' moving and sizing operations treat the guidelines as snapping areas. Snappy 💅

🖱️ 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 — and this combination also deselects the widget. Two-for-one ✨ To select all widgets on the form window, call the "Select all" command from the menu. To prevent widgets from being occasionally selected, lock them with the "Edit/Toggle lock" command or Ctrl+mouse click.

🚚 Moving

Dragging the mouse can move the selected widgets. 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; the other two are the horizontal only and the vertical only. Three modes, one vibe check. ⭐

📐 Sizing

The sizeable widgets can be dynamically resized. Only one widget at a time can be resized — one at a time, bestie, don't get greedy. 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 the "control + right click" combination. Secret menu, iykyk 🤫

---

🎀 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 properties or events are selected, the left panel of the inspector provides a list of properties or events, 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. Toggle queen 👑

The adjustable properties of a widget include an incomplete set of the properties returned by the class method profile_default ( for a detailed explanation see Prima::Object ). Among these are such basic properties as origin, size, name, color, font, visible, enabled, owner, and many others. Each property can be selected by the property selector; in such a 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 no widgets of the same name can coexist simultaneously in the builder. No duplicates allowed, name twins are cancelled 🚫

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 the 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 provided by the toolkit.

To read what each property or event means, use the documentation on the class of interest; Prima::Widget is a good start because it encompasses the basic Prima::Widget functionality. The other widgets are documented in their respective modules, for example, the Prima::ScrollBar documentation can be found in Prima::ScrollBar. Go read the docs bestie, they ate 📚✨

🦋 SEE ALSO 🦋

Prima, Prima::VB::VBLoader

👑 AUTHOR 👑

Dmitry Karasik, <dmitry@karasik.eu.org>.

🎀 COPYRIGHT 🎀

okay so the legal bit, and it's literally so chill bestie 💖 this whole program is distributed under the BSD License — that's it, that's the whole flex. no weird fine print, no jump scare, just a nice permissive license doing its thing ✨

if you're out here redistributing it, that's the license you're working with, periodt 🫶

---

and that's a wrap on VB(1), bestie!! 🎉 this page was rendered by perl v5.42.0 and dated 2024-08-20 — iconic little footer energy, ngl 💅 go forth and slay your build scripts, mwah 🧚💜