1. Manuals
  2. Tumbleweed
  3. perl-Prima
  4. Prima::VB::Classes(3pm)

Scroll to navigation

Prima::VB::Classes(3) User Contributed Perl Documentation Prima::VB::Classes(3)

NAME

Prima::VB::Classes - Visual Builder widgets and types

DESCRIPTION

Visual Builder is designed without prior knowledge of the widget classes that would be contained in its widget palette. Instead, it provides the registration interface for new widgets and their specific properties.

This document describes the API provided by the builder and its widget interface. Through the document, widget or widget class mean not the original widget or class, but their representative proxies in the Visual Builder.

USAGE

The widget must provide specific methods to cooperate with the builder. It is not required, however, to define these methods in its base module or package; it can delegate its representation to another, usually very light class, which is used by the builder.

Such a class must be derived from "Prima::VB::Object" which provides the minimal base functionality. One of the basic features here is the overloading of the property change method. Since the user can change any property interactively, the class can catch the properties of interest by declaring a "prf_XXX" method where "XXX" is the property name. "Prima::VB::Widget" declares a set of these methods, assuming that a widget would repaint when, for example, its "color" or "font" properties change.

The hierarchy of VB classes mimics the one of the core toolkit classes, but this is a mere resemblance, there are no other dependencies except the names themselves. The hierarchy is as follows:

        Prima::VB::Object   Prima::Widget
                Prima::VB::Component
                        Prima::VB::Drawable
                                Prima::VB::Widget
                                        Prima::VB::Control
                                                Prima::VB::Window

Note: "Prima::VB::CoreClasses" extends the hierarchy to the full set of default widget palette in the builder.

The proxy widgets provide access to the profile properties with the "prf" and "prf_set" methods. The profile is stored as a hash in each proxy widget and is used when generating a VB form file. The proxy widgets usually don't change their own properties when the user changes for example a font or a color on a proxy widget; the proxy widgets draw themselves using the profile properties.

A type object is a class used to represent a particular type of property in the object inspector window in the builder. The type objects, like the widget classes, also are not hard-coded. The builder presents a basic set of the type objects, which can be easily expanded. The hierarchy ( incomplete ) of the type objects classes is as follows:

        Prima::VB::Types::generic
                Prima::VB::Types::bool
                Prima::VB::Types::color
                Prima::VB::Types::point
                Prima::VB::Types::icon
                Prima::VB::Types::Handle
                Prima::VB::Types::textee
                        Prima::VB::Types::text
                        Prima::VB::Types::string
                                Prima::VB::Types::char
                                Prima::VB::Types::name
                                Prima::VB::Types::iv
                                        Prima::VB::Types::uiv

The document does not describe all the types, since their function can be observed at runtime in the object inspector. Only the "Prima::VB::Types::generic" API is documented.

Prima::VB::Object

Properties

Selects the original widget class. A create-only property.
Sets the creation order of the widget.
Selects the module that contains the original widget class. A create-only property.
Sets the original widget profile. A create-only property. Changes to the profile at run-time are performed by the "prf_set" method.

Methods

Returns a hash of callbacks to be stored in the form file and executed by "Prima::VB::VBLoader" when the form file is loaded. The hash keys are names of the VBLoader events, and the values are strings with code to be eval'ed. See "Events" in Prima::VB::VBLoader for the description and the format of the callbacks.

Called when the builder writes a form file.

Registers the object as a watcher of PROPERTIES. When any object changes a property listed in the hook record, the "on_hook" callback is triggered.

The special name 'DESTROY' can be used to set a hook on the object destruction event.

Returns a class-specific hash, written in a form file. Can be used as a set of extra parameters passed from the builder to the "act_profile" events.
The main method for setting a property of an object. PROFILE keys are property names, and values are property values.
DEFAULT_PROFILE is a result of the "profile_default" call on the real object class. However, not all properties usually are exported to the object inspector. "prf_adjust_default" deletes the unnecessary or rarely used property keys from the PROFILE hash.
Removes PROPERTIES from the internal properties hash. This action results in the PROPERTIES in the object inspector being grayed and reassigned to their default values.
Returns a hash of class-specific events. These appear in the object inspector on the "Events" page. The hash keys are event names; the hash values are default code pieces, that describe the format of the event parameters. For example: 

        sub prf_events { return (
                $_[0]-> SUPER::prf_events,
                onSelectItem  => 'my ( $self, $index, $selectState) = @_;',
        )}
Maps an array of PROPERTIES names to their values. If called in the scalar context, returns the first value only; in the array context returns an array of property values.
Returns an anonymous hash, where keys are names of the type class without the "Prima::VB::Types::" prefix and values are arrays of property names.

This callback returns an inverse mapping of properties by their types.

Adds PROFILE2 content to PROFILE1. PROFILE1 and PROFILE2 are hashes in the format of the "prf_types" method.
Removes @NAMES from PROFILE. Need to be called if the property type is redefined through the inheritance.
Stops watching PROPERTIES.

Events

Called for all objects registered as watchers through the "add_hooks" method, when PROPERTY on object NAME is changed from OLD_VALUE to NEW_VALUE. A special PROPERTY 'DESTROY' hook is called when object NAME is destroyed.

Prima::VB::Component

Properties

Selects the marked state of a widget. If the MARKED flag is 1, the widget is selected as marked. If 0, it is selected as unmarked. If the EXCLUSIVE flag is set to 1, then all marked widgets are unmarked before the object mark flag is set.
If 1, the widget can be resized by the user. If 0, it can only be moved.
Selects the event name, that will be opened in the object inspector when the user double-clicks on the widget.

Methods

Draws the selection and resize marks on the widget if it is in the selected state. To be called from all "on_paint" callbacks.
Returns the offset in pixels to the owner widget. Since the builder does not insert widgets in widgets to reflect the user-designed object hierarchy, this method is to be used to calculate the relative positions of the children widgets.
Maps an X,Y point to a part of the widget. If the result is not equal to the 'client' string, the mouse event in this coordinate must be ignored.
Traverses all children widgets in the hierarchy, calling the SUB routine with widget, self, and @ARGS parameters on each.
Invokes an alternative, class-specific popup menu, if present. The popup object must be named 'AltPopup'.

Events

Called when the widget is loaded from a file or the clipboard.

Prima::VB::Types::generic

The root of all type classes.

A type class can be used with and without an object instance. The instantiated class contains a reference to an ID string, which is a property name that the object presents in the object inspector, and a WIDGET, which is the property applied to. When the object inspector switches widgets, the type object is commanded to update the references.

A class must also be usable without an object instance, in particular, in the "write" method. It is called to export the property value in a storable format as a perl-evaluable string.

Methods

A constructor method. CONTAINER is a panel widget in the object inspector, where the type object can insert its own controls to manage the properties of this type.
Resets the property name and the widget.
Returns a quotable STRING.
Returns a string that can be stored in a file.

Callbacks

Called when the widget property value is changed.
Called when the property name ( ID ) is changed. The type object may consider updating its look or eventual internal variables on this event.
Returns the property value based on the selector widgets value.
Called when the type object is to be visualized for the first time. The object must populate the "{container}" panel widget with its specific type controls.
Returns an array of strings of modules needed to be preloaded before a form file with type class-specific information can be loaded. Usually, it is used when the "write" method exports constant values which are defined in another module.
Called when a new value is set to the widget property by means other than the selector widgets, so the latter can be updated. DATA is the property's new value.
Checks the internal state of data and returns a boolean flag if the type object data can be safely exported and applied to the widget profile.
Called when DATA is to be written in the form file. "write" must return a string that can be later loaded by "Prima::VB::VBLoader" .

AUTHOR

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

SEE ALSO

VB, Prima::VB::VBLoader, Prima::VB::CfgMaint.

2024-08-20 perl v5.40.0