trusty (3) Prima::VB::Classes.3.gz
NAME
Prima::VB::Classes - Visual Builder widgets and types
DESCRIPTION
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.
USAGE
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.
Prima::VB::Object
Properties
class STRING
Selects the original widget class. Create-only property.
creationOrder INTEGER
Selects the creation order of the widget.
module STRING
Selects the module that contains the original widget class. Create-only property.
profile HASH
Selects the original widget profile. Create-only property. Changes to profile at run-time performed
by "prf_set" method.
Methods
act_profile
Returns 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 VBLoader events and values - strings with code
to be eval'ed. See "Events" in Prima::VB::VBLoader for description and format of the callbacks.
Called when the builder writes a form file.
add_hooks @PROPERTIES
Registers the object as a watcher to set of PROPERTIES. When any object changes a property listed in
the hook record, "on_hook" callback is triggered.
Special name 'DESTROY' can be used to set a hook on object destruction event.
ext_profile
Returns a class-specific hash, written in a form file. Its use is to serve as a set of extra
parameters, passed from the builder to "act_profile" events.
prf_set %PROIFLE
A main method for setting a property of an object. PROFILE keys are property names, and value are
property values.
prf_adjust_default PROFILE, DEFAULT_PROFILE
DEFAULT_PROFILE is a result of "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.
prf_delete @PROPERTIES
Removes PROPERTIES from internal properties hash. This action results in that the PROPERTIES in the
object inspector are set back to their default values.
prf_events
Returns hash of a class-specific events. These appear in the object inspector on "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) = @_;',
)}
prf @PROPERTIES
Maps array of PROPERTIES names to their values. If called in scalar context, returns the first value
only; if in array context, returns array of property values.
prf_types
Returns an anonymous hash, where keys are names of the type class without "Prima::VB::Types::"
prefix, and values are arrays of property names.
This callback returns an inverse mapping of properties by the types.
prf_types_add PROFILE1, PROFILE2
Adds PROFILE2 content to PROFILE1. PROFILE1 and PROFILE2 are hashes in format of result of
"prf_types" method.
prf_types_delete PROFILE, @NAMES
Removes @NAMES from PROFILE. Need to be called if property type if redefined through the inheritance.
remove_hooks @PROPERTIES
Cancels watch for set of PROPERTIES.
Events
on_hook NAME, PROPERTY, OLD_VALUE, NEW_VALUE
Called for all objects, registered as watchers by "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.
Prima::VB::Component
Properties
marked MARKED , EXCLUSIVE
Selects marked state of a widget. If MARKED flag is 1, the widget is selected as marked. If 0, it is
selected as unmarked. If EXCLUSIVE flag is set to 1, then all marked widgets are unmarked before the
object mark flag is set.
sizeable BOOLEAN
If 1, the widget can be resized by the user. If 0, in can only be moved.
mainEvent STRING
Selects the event name, that will be opened in the object inspector when the user double clicks on
the widget.
Methods
common_paint CANVAS
Draws selection and resize marks on the widget if it is in the selected state. To be called from all
"on_paint" callbacks.
get_o_delta
Returns offset 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 children widgets relative
positions.
xy2part X, Y
Maps X, Y point into part of widget. If result is not equal to 'client' string, the event in X, Y
point must be ignored.
iterate_children SUB, @ARGS
Traverses all children widget in the hierarchy, calling SUB routine with widget, self, and @ARGS
parameters on each.
altpopup
Invokes an alternative, class-specific popup menu, if present. The popup object must be named
'AltPopup'.
Events
Load
Called when the widget is loaded from a file or the clipboard.
Prima::VB::Types::generic
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.
Methods
new CONTAINER, ID, WIDGET
Constructor method. CONTAINER is a panel widget in the object inspector, where the type object can
insert property value selector widgets.
renew ID, WIDGET
Resets property name and the widget.
quotable STRING
Returns quotable STRING.
printable STRING
Returns a string that can be stored in a file.
Callbacks
change
Called when the widget property value is changed.
change_id
Called when the property name ( ID ) is changed. The type object may consider update its look or
eventual internal variables on this event.
get Returns property value, based on the selector widgets value.
open
Called when the type object is to be visualized first time. The object must create property value
selector widgets in the "{container}" panel widget.
preload_modules
Returns array of strings of modules, needed to be pre-loaded before a form file with type class-
specific information can be loaded. Usually it is used when "write" method exports constant values,
which are defined in another module.
set DATA
Called when a new value is set to the widget property by means other than the selector widgets, so
these can be updated. DATA is the property new value.
valid
Checks internal state of data and returns a boolean flag, if the type object data can be exported and
set to widget profile.
write CLASS, ID, DATA
Called when DATA is to be written in form. "write" must return such a string that can be loaded by
"Prima::VB::VBLoader" later.
AUTHOR
Dmitry Karasik, <dmitry@karasik.eu.org>.
SEE ALSO
VB, Prima::VB::VBLoader, Prima::VB::CfgMaint.