1Prima::VB::Classes(3) User Contributed Perl DocumentationPrima::VB::Classes(3)
2
3
4

NAME

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

DESCRIPTION

9       Visual Builder is designed without a prior knowledge of the widget
10       classes that would be contained in its widget palette.  Instead, it
11       provides a registration interface for new widgets and their specific
12       properties.
13
14       This document describes API, provided by the builder, and the widget
15       interface. Through the document, widget or widget class mean not the
16       original widget or class, but their representatives.
17

USAGE

19       The widget must provide specific methods to cooperate with the builder.
20       It is not required, however, to contain these methods in its base
21       module or package; it can delegate its representation to another,
22       usually very light class, which is used by the builder.
23
24       Such a class must be derived from "Prima::VB::Object", which provides
25       base functionality. One of basic features here is overloading of
26       property change method. Since the user can change any property
27       interactively, the class can catch the properties of interest by
28       declaring "prf_XXX" method, where XXX is the property name.
29       "Prima::VB::Widget" declares set of these methods, assuming that a
30       widget would repaint when, for example, its "color" or "font"
31       properties change.
32
33       The hierarchy of VB classes mimics the one of the core toolkit classes,
34       but this is a mere resemblance, no other dependencies except the names
35       are present. The hierarchy is as follows:
36
37               Prima::VB::Object   Prima::Widget
38                       Prima::VB::Component
39                               Prima::VB::Drawable
40                                       Prima::VB::Widget
41                                               Prima::VB::Control
42                                                       Prima::VB::Window
43
44       NB: "Prima::VB::CoreClasses" extends the hierarchy to the full set of
45       default widget palette in the builder. This module is not provided with
46       documentation though since its function is obvious and its code is
47       trivial.
48
49       Since the real widgets are used in the interaction with the builder,
50       their properties are not touched when changed by the object inspector
51       or otherwise. The widgets keep the set of properties in a separated
52       hash. The properties are accessible by "prf" and "prf_set" methods.
53
54       A type object is a class used to represent a particular type of
55       property in object inspector window in the builder.  The type objects,
56       like the widget classes, also are not hard-coded. The builder presents
57       a basic set of the type objects, which can be easily expanded.  The
58       hierarchy ( incomplete ) of the type objects classes is as follows:
59
60               Prima::VB::Types::generic
61                       Prima::VB::Types::bool
62                       Prima::VB::Types::color
63                       Prima::VB::Types::point
64                       Prima::VB::Types::icon
65                       Prima::VB::Types::Handle
66                       Prima::VB::Types::textee
67                               Prima::VB::Types::text
68                               Prima::VB::Types::string
69                                       Prima::VB::Types::char
70                                       Prima::VB::Types::name
71                                       Prima::VB::Types::iv
72                                               Prima::VB::Types::uiv
73
74       The document does not describe the types, since their function can be
75       observed at runtime in the object inspector.  Only
76       "Prima::VB::Types::generic" API is documented.
77

Prima::VB::Object

79   Properties
80       class STRING
81           Selects the original widget class. Create-only property.
82
83       creationOrder INTEGER
84           Selects the creation order of the widget.
85
86       module STRING
87           Selects the module that contains the original widget class. Create-
88           only property.
89
90       profile HASH
91           Selects the original widget profile. Create-only property.  Changes
92           to profile at run-time performed by "prf_set" method.
93
94   Methods
95       act_profile
96           Returns hash of callbacks to be stored in the form file and
97           executed by "Prima::VB::VBLoader" when the form file is loaded.
98           The hash keys are names of VBLoader events and values - strings
99           with code to be eval'ed. See "Events" in Prima::VB::VBLoader for
100           description and format of the callbacks.
101
102           Called when the builder writes a form file.
103
104       add_hooks @PROPERTIES
105           Registers the object as a watcher to set of PROPERTIES.  When any
106           object changes a property listed in the hook record, "on_hook"
107           callback is triggered.
108
109           Special name 'DESTROY' can be used to set a hook on object
110           destruction event.
111
112       ext_profile
113           Returns a class-specific hash, written in a form file.  Its use is
114           to serve as a set of extra parameters, passed from the builder to
115           "act_profile" events.
116
117       prf_set %PROIFLE
118           A main method for setting a property of an object.  PROFILE keys
119           are property names, and value are property values.
120
121       prf_adjust_default PROFILE, DEFAULT_PROFILE
122           DEFAULT_PROFILE is a result of "profile_default" call of the real
123           object class. However, not all properties usually are exported to
124           the object inspector. "prf_adjust_default" deletes the unneeded
125           property keys from PROFILE hash.
126
127       prf_delete @PROPERTIES
128           Removes PROPERTIES from internal properties hash.  This action
129           results in that the PROPERTIES in the object inspector are set back
130           to their default values.
131
132       prf_events
133           Returns hash of a class-specific events. These appear in the object
134           inspector on "Events" page. The hash keys are event names; the hash
135           values are default code pieces, that describe format of the event
136           parameters. Example:
137
138                   sub prf_events { return (
139                           $_[0]-> SUPER::prf_events,
140                           onSelectItem  => 'my ( $self, $index, $selectState) = @_;',
141                   )}
142
143       prf @PROPERTIES
144           Maps array of PROPERTIES names to their values. If called in scalar
145           context, returns the first value only; if in array context, returns
146           array of property values.
147
148       prf_types
149           Returns an anonymous hash, where keys are names of the type class
150           without "Prima::VB::Types::" prefix, and values are arrays of
151           property names.
152
153           This callback returns an inverse mapping of properties by the
154           types.
155
156       prf_types_add PROFILE1, PROFILE2
157           Adds PROFILE2 content to PROFILE1. PROFILE1 and PROFILE2 are hashes
158           in format of result of "prf_types" method.
159
160       prf_types_delete PROFILE, @NAMES
161           Removes @NAMES from PROFILE. Need to be called if property type if
162           redefined through the inheritance.
163
164       remove_hooks @PROPERTIES
165           Cancels watch for set of PROPERTIES.
166
167   Events
168       on_hook NAME, PROPERTY, OLD_VALUE, NEW_VALUE, WIDGET
169           Called for all objects, registered as watchers by "add_hooks" when
170           PROPERTY on object NAME is changed from OLD_VALUE to NEW_VALUE.
171           Special PROPERTY 'DESTROY' hook is called when object NAME is
172           destroyed.
173

Prima::VB::Component

175   Properties
176       marked MARKED , EXCLUSIVE
177           Selects marked state of a widget. If MARKED flag is 1, the widget
178           is selected as marked. If 0, it is selected as unmarked.  If
179           EXCLUSIVE flag is set to 1, then all marked widgets are unmarked
180           before the object mark flag is set.
181
182       sizeable BOOLEAN
183           If 1, the widget can be resized by the user.  If 0, in can only be
184           moved.
185
186       mainEvent STRING
187           Selects the event name, that will be opened in the object inspector
188           when the user double clicks on the widget.
189
190   Methods
191       common_paint CANVAS
192           Draws selection and resize marks on the widget if it is in the
193           selected state. To be called from all "on_paint" callbacks.
194
195       get_o_delta
196           Returns offset to the owner widget. Since the builder does not
197           insert widgets in widgets to reflect the user-designed object
198           hierarchy, this method is to be used to calculate children widgets
199           relative positions.
200
201       xy2part X, Y
202           Maps X, Y point into part of widget. If result is not equal to
203           'client' string, the event in X, Y point must be ignored.
204
205       iterate_children SUB, @ARGS
206           Traverses all children widget in the hierarchy, calling SUB routine
207           with widget, self, and @ARGS parameters on each.
208
209       altpopup
210           Invokes an alternative, class-specific popup menu, if present.  The
211           popup object must be named 'AltPopup'.
212
213   Events
214       Load
215           Called when the widget is loaded from a file or the clipboard.
216

Prima::VB::Types::generic

218       Root of all type classes.
219
220       A type class can be used with and without object instance. The
221       instantiated class contains reference to ID string, which is a property
222       name that the object presents in the object inspector, and WIDGET,
223       which is the property applied to. When the object inspector switches
224       widgets, the type object is commanded to update the references.
225
226       A class must also be usable without object instance, in particular, in
227       "write" method. It is called to export the property value in a storable
228       format as a string, better as a perl-evaluable expression.
229
230   Methods
231       new CONTAINER, ID, WIDGET
232           Constructor method. CONTAINER is a panel widget in the object
233           inspector, where the type object can insert property value selector
234           widgets.
235
236       renew ID, WIDGET
237           Resets property name and the widget.
238
239       quotable STRING
240           Returns quotable STRING.
241
242       printable STRING
243           Returns a string that can be stored in a file.
244
245   Callbacks
246       change
247           Called when the widget property value is changed.
248
249       change_id
250           Called when the property name ( ID ) is changed.  The type object
251           may consider update its look or eventual internal variables on this
252           event.
253
254       get Returns property value, based on the selector widgets value.
255
256       open
257           Called when the type object is to be visualized first time.  The
258           object must create property value selector widgets in the
259           "{container}" panel widget.
260
261       preload_modules
262           Returns array of strings of modules, needed to be pre-loaded before
263           a form file with type class-specific information can be loaded.
264           Usually it is used when "write" method exports constant values,
265           which are defined in another module.
266
267       set DATA
268           Called when a new value is set to the widget property by means
269           other than the selector widgets, so these can be updated. DATA is
270           the property new value.
271
272       valid
273           Checks internal state of data and returns a boolean flag, if the
274           type object data can be exported and set to widget profile.
275
276       write CLASS, ID, DATA
277           Called when DATA is to be written in form.  "write" must return
278           such a string that can be loaded by "Prima::VB::VBLoader" later.
279

AUTHOR

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

SEE ALSO

284       VB, Prima::VB::VBLoader, Prima::VB::CfgMaint.
285
286
287
288perl v5.32.1                      2021-01-27             Prima::VB::Classes(3)
Impressum