.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Prima::VB::Classes 3"
.TH Prima::VB::Classes 3 "2009-02-24" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Prima::VB::Classes \- Visual Builder widgets and types
.SH "DESCRIPTION"
.IX Header "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.
.PP
This document describes \s-1API\s0, provided by the builder, and the widget
interface. Through the document, \fIwidget\fR or \fIwidget class\fR mean
not the original widget or class, but their representatives.
.SH "USAGE"
.IX Header "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.
.PP
Such a class must be derived from \f(CW\*(C`Prima::VB::Object\*(C'\fR, 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 \f(CW\*(C`prf_XXX\*(C'\fR
method, where \s-1XXX\s0 is the property name. \f(CW\*(C`Prima::VB::Widget\*(C'\fR declares
set of these methods, assuming that a widget would repaint when, for example,
its \f(CW\*(C`color\*(C'\fR or \f(CW\*(C`font\*(C'\fR properties change.
.PP
The hierarchy of \s-1VB\s0 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:
.PP
.Vb 6
\&        Prima::VB::Object   Prima::Widget
\&                Prima::VB::Component
\&                        Prima::VB::Drawable
\&                                Prima::VB::Widget
\&                                        Prima::VB::Control
\&                                                Prima::VB::Window
.Ve
.PP
\&\s-1NB:\s0 \f(CW\*(C`Prima::VB::CoreClasses\*(C'\fR 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.
.PP
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 \f(CW\*(C`prf\*(C'\fR and \f(CW\*(C`prf_set\*(C'\fR methods.
.PP
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:
.PP
.Vb 10
\&        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
.Ve
.PP
The document does not describe the types, since their function
can be observed at runtime in the object inspector.
Only \f(CW\*(C`Prima::VB::Types::generic\*(C'\fR \s-1API\s0 is documented.
.SH "Prima::VB::Object"
.IX Header "Prima::VB::Object"
.SS "Properties"
.IX Subsection "Properties"
.IP "class \s-1STRING\s0" 4
.IX Item "class STRING"
Selects the original widget class. Create-only property.
.IP "creationOrder \s-1INTEGER\s0" 4
.IX Item "creationOrder INTEGER"
Selects the creation order of the widget.
.IP "module \s-1STRING\s0" 4
.IX Item "module STRING"
Selects the module that contains the original widget class. Create-only property.
.IP "profile \s-1HASH\s0" 4
.IX Item "profile HASH"
Selects the original widget profile. Create-only property.
Changes to profile at run-time performed by \f(CW\*(C`prf_set\*(C'\fR method.
.SS "Methods"
.IX Subsection "Methods"
.IP "act_profile" 4
.IX Item "act_profile"
Returns hash of callbacks to be stored in the form file and
executed by \f(CW\*(C`Prima::VB::VBLoader\*(C'\fR when the form file is loaded.
The hash keys are names of VBLoader events and values \- strings
with code to be eval'ed. See \*(L"Events\*(R" in Prima::VB::VBLoader
for description and format of the callbacks.
.Sp
Called when the builder writes a form file.
.ie n .IP "add_hooks @PROPERTIES" 4
.el .IP "add_hooks \f(CW@PROPERTIES\fR" 4
.IX Item "add_hooks @PROPERTIES"
Registers the object as a watcher to set of \s-1PROPERTIES\s0.
When any object changes a property listed in the hook record,
\&\f(CW\*(C`on_hook\*(C'\fR callback is triggered.
.Sp
Special name \f(CW\*(AqDESTROY\*(Aq\fR can be used to set a hook on object destruction event.
.IP "ext_profile" 4
.IX Item "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 \f(CW\*(C`act_profile\*(C'\fR events.
.ie n .IP "prf_set %PROIFLE" 4
.el .IP "prf_set \f(CW%PROIFLE\fR" 4
.IX Item "prf_set %PROIFLE"
A main method for setting a property of an object.
\&\s-1PROFILE\s0 keys are property names, and value are property values.
.IP "prf_adjust_default \s-1PROFILE\s0, \s-1DEFAULT_PROFILE\s0" 4
.IX Item "prf_adjust_default PROFILE, DEFAULT_PROFILE"
\&\s-1DEFAULT_PROFILE\s0 is a result of \f(CW\*(C`profile_default\*(C'\fR call 
of the real object class. However, not all properties usually
are exported to the object inspector. \f(CW\*(C`prf_adjust_default\*(C'\fR
deletes the unneeded property keys from \s-1PROFILE\s0 hash.
.ie n .IP "prf_delete @PROPERTIES" 4
.el .IP "prf_delete \f(CW@PROPERTIES\fR" 4
.IX Item "prf_delete @PROPERTIES"
Removes \s-1PROPERTIES\s0 from internal properties hash.
This action results in that the \s-1PROPERTIES\s0 in the object inspector
are set back to their default values.
.IP "prf_events" 4
.IX Item "prf_events"
Returns hash of a class-specific events. These appear in
the object inspector on \f(CW\*(C`Events\*(C'\fR page. The hash keys are
event names; the hash values are default code pieces,
that describe format of the event parameters. Example:
.Sp
.Vb 4
\&        sub prf_events { return (
\&                $_[0]\-> SUPER::prf_events,
\&                onSelectItem  => \*(Aqmy ( $self, $index, $selectState) = @_;\*(Aq,
\&        )}
.Ve
.ie n .IP "prf @PROPERTIES" 4
.el .IP "prf \f(CW@PROPERTIES\fR" 4
.IX Item "prf @PROPERTIES"
Maps array of \s-1PROPERTIES\s0 names to their values. If called
in scalar context, returns the first value only; if in array 
context, returns array of property values.
.IP "prf_types" 4
.IX Item "prf_types"
Returns an anonymous hash, where keys are names of
the type class without \f(CW\*(C`Prima::VB::Types::\*(C'\fR prefix,
and values are arrays of property names.
.Sp
This callback returns an inverse mapping of properties
by the types.
.IP "prf_types_add \s-1PROFILE1\s0, \s-1PROFILE2\s0" 4
.IX Item "prf_types_add PROFILE1, PROFILE2"
Adds \s-1PROFILE2\s0 content to \s-1PROFILE1\s0. \s-1PROFILE1\s0 and \s-1PROFILE2\s0 are 
hashes in format of result of \f(CW\*(C`prf_types\*(C'\fR method.
.ie n .IP "prf_types_delete \s-1PROFILE\s0, @NAMES" 4
.el .IP "prf_types_delete \s-1PROFILE\s0, \f(CW@NAMES\fR" 4
.IX Item "prf_types_delete PROFILE, @NAMES"
Removes \f(CW@NAMES\fR from \s-1PROFILE\s0. Need to be called if property type if redefined
through the inheritance.
.ie n .IP "remove_hooks @PROPERTIES" 4
.el .IP "remove_hooks \f(CW@PROPERTIES\fR" 4
.IX Item "remove_hooks @PROPERTIES"
Cancels watch for set of \s-1PROPERTIES\s0.
.SS "Events"
.IX Subsection "Events"
.IP "on_hook \s-1NAME\s0, \s-1PROPERTY\s0, \s-1OLD_VALUE\s0, \s-1NEW_VALUE\s0" 4
.IX Item "on_hook NAME, PROPERTY, OLD_VALUE, NEW_VALUE"
Called for all objects, registered as watchers
by \f(CW\*(C`add_hooks\*(C'\fR when \s-1PROPERTY\s0 on object \s-1NAME\s0 is changed
from \s-1OLD_VALUE\s0 to \s-1NEW_VALUE\s0. Special \s-1PROPERTY\s0 \f(CW\*(AqDESTROY\*(Aq\fR
hook is called when object \s-1NAME\s0 is destroyed.
.SH "Prima::VB::Component"
.IX Header "Prima::VB::Component"
.SS "Properties"
.IX Subsection "Properties"
.IP "marked \s-1MARKED\s0 , \s-1EXCLUSIVE\s0" 4
.IX Item "marked MARKED , EXCLUSIVE"
Selects marked state of a widget. If \s-1MARKED\s0 flag is 1, the widget is
selected as marked. If 0, it is selected as unmarked.
If \s-1EXCLUSIVE\s0 flag is set to 1, then all marked widgets are unmarked
before the object mark flag is set.
.IP "sizeable \s-1BOOLEAN\s0" 4
.IX Item "sizeable BOOLEAN"
If 1, the widget can be resized by the user.
If 0, in can only be moved.
.IP "mainEvent \s-1STRING\s0" 4
.IX Item "mainEvent STRING"
Selects the event name, that will be opened in the object inspector
when the user double clicks on the widget.
.SS "Methods"
.IX Subsection "Methods"
.IP "common_paint \s-1CANVAS\s0" 4
.IX Item "common_paint CANVAS"
Draws selection and resize marks on the widget
if it is in the selected state. To be called from
all \f(CW\*(C`on_paint\*(C'\fR callbacks.
.IP "get_o_delta" 4
.IX Item "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.
.IP "xy2part X, Y" 4
.IX Item "xy2part X, Y"
Maps X, Y point into part of widget. If result is not
equal to \f(CW\*(Aqclient\*(Aq\fR string, the event in X, Y point
must be ignored.
.ie n .IP "iterate_children \s-1SUB\s0, @ARGS" 4
.el .IP "iterate_children \s-1SUB\s0, \f(CW@ARGS\fR" 4
.IX Item "iterate_children SUB, @ARGS"
Traverses all children widget in the hierarchy,
calling \s-1SUB\s0 routine with widget, self, and \f(CW@ARGS\fR
parameters on each.
.IP "altpopup" 4
.IX Item "altpopup"
Invokes an alternative, class-specific popup menu, if present.
The popup object must be named \f(CW\*(AqAltPopup\*(Aq\fR.
.SS "Events"
.IX Subsection "Events"
.IP "Load" 4
.IX Item "Load"
Called when the widget is loaded from a file or the clipboard.
.SH "Prima::VB::Types::generic"
.IX Header "Prima::VB::Types::generic"
Root of all type classes.
.PP
A type class can be used with 
and without object instance. The instantiated class
contains reference to \s-1ID\s0 string, which is a property
name that the object presents in the object inspector,
and \s-1WIDGET\s0, which is the property applied to. When
the object inspector switches widgets, the type object
is commanded to update the references.
.PP
A class must also be usable without object instance,
in particular, in \f(CW\*(C`write\*(C'\fR method. It is called to
export the property value in a storable format
as a string, better as a perl-evaluable expression.
.SS "Methods"
.IX Subsection "Methods"
.IP "new \s-1CONTAINER\s0, \s-1ID\s0, \s-1WIDGET\s0" 4
.IX Item "new CONTAINER, ID, WIDGET"
Constructor method. \s-1CONTAINER\s0 is a panel widget in the object
inspector, where the type object can insert property value
selector widgets.
.IP "renew \s-1ID\s0, \s-1WIDGET\s0" 4
.IX Item "renew ID, WIDGET"
Resets property name and the widget.
.IP "quotable \s-1STRING\s0" 4
.IX Item "quotable STRING"
Returns quotable \s-1STRING\s0.
.IP "printable \s-1STRING\s0" 4
.IX Item "printable STRING"
Returns a string that can be stored in a file.
.SS "Callbacks"
.IX Subsection "Callbacks"
.IP "change" 4
.IX Item "change"
Called when the widget property value is changed.
.IP "change_id" 4
.IX Item "change_id"
Called when the property name ( \s-1ID\s0 ) is changed.
The type object may consider update its look
or eventual internal variables on this event.
.IP "get" 4
.IX Item "get"
Returns property value, based on the selector widgets value.
.IP "open" 4
.IX Item "open"
Called when the type object is to be visualized first time.
The object must create property value selector widgets
in the \f(CW\*(C`{container}\*(C'\fR panel widget.
.IP "preload_modules" 4
.IX Item "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 \f(CW\*(C`write\*(C'\fR method
exports constant values, which are defined in another module.
.IP "set \s-1DATA\s0" 4
.IX Item "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. \s-1DATA\s0 is the property new value.
.IP "valid" 4
.IX Item "valid"
Checks internal state of data and returns a boolean
flag, if the type object data can be exported and
set to widget profile.
.IP "write \s-1CLASS\s0, \s-1ID\s0, \s-1DATA\s0" 4
.IX Item "write CLASS, ID, DATA"
Called when \s-1DATA\s0 is to be written in form.
\&\f(CW\*(C`write\*(C'\fR must return such a string that 
can be loaded by \f(CW\*(C`Prima::VB::VBLoader\*(C'\fR later.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dmitry Karasik, <dmitry@karasik.eu.org>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1VB\s0, Prima::VB::VBLoader, Prima::VB::CfgMaint.