|
Prima::VB::Classes - Visual Builder widgets and types |
Prima::VB::Classes - Visual Builder widgets and types
Visual Builder is designed without a prior knowledge of the widget classes that would be contained in its widget palette. Instead, it provides a registration interface for new widgets and their specific properties.
This document describes API, provided by the builder, and the widget interface. Through the document, widget or widget class mean not the original widget or class, but their representatives.
The widget must provide specific methods to cooperate with the builder. It is not required, however, to contain 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
base functionality. One of basic features here is overloading of
property change method. Since the user can change any property interactively,
the class can catch the properties of interest by declaring prf_XXX
method, where XXX is the property name. Prima::VB::Widget declares
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, no other dependencies except the names are present. 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
NB: Prima::VB::CoreClasses extends the hierarchy to the full set of default
widget palette in the builder. This module is not provided with documentation
though since its function is obvious and its code is trivial.
Since the real widgets are used in the interaction with the builder,
their properties are not touched when changed by the object inspector
or otherwise. The widgets
keep the set of properties in a separated hash. The properties are
accessible by prf and prf_set methods.
A type object is a class used to represent a particular type of property in 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 the types, since their function
can be observed at runtime in the object inspector.
Only Prima::VB::Types::generic API is documented.
prf_set method.
Prima::VB::VBLoader when the form file is loaded.
The hash keys are names of VBLoader events and values - strings
with code to be eval'ed. See Events in the Prima::VB::VBLoader manpage
for description and format of the callbacks.
Called when the builder writes a form file.
on_hook callback is triggered.
Special name 'DESTROY' can be used to set a hook on object destruction event.
act_profile events.
profile_default call
of the real object class. However, not all properties usually
are exported to the object inspector. prf_adjust_default
deletes the unneeded property keys from PROFILE hash.
Events page. The hash keys are
event names; the hash values are default code pieces,
that describe format of the event parameters. Example:
sub prf_events { return (
$_[0]-> SUPER::prf_events,
onSelectItem => 'my ( $self, $index, $selectState) = @_;',
)}
Prima::VB::Types:: prefix,
and values are arrays of property names.
This callback returns an inverse mapping of properties by the types.
prf_types method.
add_hooks when PROPERTY on object NAME is changed
from OLD_VALUE to NEW_VALUE. Special PROPERTY 'DESTROY'
hook is called when object NAME is destroyed.
on_paint callbacks.
'client' string, the event in X, Y point
must be ignored.
'AltPopup'.
Root of all type classes.
A type class can be used with and without object instance. The instantiated class contains reference to ID string, which is a property name that the object presents in the object inspector, and 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 object instance,
in particular, in write method. It is called to
export the property value in a storable format
as a string, better as a perl-evaluable expression.
{container} panel widget.
write method
exports constant values, which are defined in another module.
write must return such a string that
can be loaded by Prima::VB::VBLoader later.
Dmitry Karasik, <dmitry@karasik.eu.org>.
VB, the Prima::VB::VBLoader manpage, the Prima::VB::CfgMaint manpage.
|
Prima::VB::Classes - Visual Builder widgets and types |