1Prima::VB::Classes(3) User Contributed Perl DocumentationPrima::VB::Classes(3)
2
6 Prima::VB::Classes - Visual Builder widgets and types
7
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 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
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 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 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 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 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 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 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 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 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
79 Properties
80 class STRING
81 Selects the original widget class. Create-only property.
82 creationOrder INTEGER
84 Selects the creation order of the widget.
85 module STRING
87 Selects the module that contains the original widget class. Create-
88 only property.
89 profile HASH
91 Selects the original widget profile. Create-only property. Changes
92 to profile at run-time performed by "prf_set" method.
93 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 Called when the builder writes a form file.
103 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 Special name 'DESTROY' can be used to set a hook on object
110 destruction event.
111 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 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 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 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 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 sub prf_events { return (
139 $_[0]-> SUPER::prf_events,
140 onSelectItem => 'my ( $self, $index, $selectState) = @_;',
141 )}
142 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 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 This callback returns an inverse mapping of properties by the
154 types.
155 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 prf_types_delete PROFILE, @NAMES
161 Removes @NAMES from PROFILE. Need to be called if property type if
162 redefined through the inheritance.
163 remove_hooks @PROPERTIES
165 Cancels watch for set of PROPERTIES.
166 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
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 sizeable BOOLEAN
183 If 1, the widget can be resized by the user. If 0, in can only be
184 moved.
185 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 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 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 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 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 altpopup
210 Invokes an alternative, class-specific popup menu, if present. The
211 popup object must be named 'AltPopup'.
212 Events
214 Load
215 Called when the widget is loaded from a file or the clipboard.
216
218 Root of all type classes.
219 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 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 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 renew ID, WIDGET
237 Resets property name and the widget.
238 quotable STRING
240 Returns quotable STRING.
241 printable STRING
243 Returns a string that can be stored in a file.
244 Callbacks
246 change
247 Called when the widget property value is changed.
248 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 get Returns property value, based on the selector widgets value.
255 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 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 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 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 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
281 Dmitry Karasik, <dmitry@karasik.eu.org>.
282
284 VB, Prima::VB::VBLoader, Prima::VB::CfgMaint.
285perl v5.32.0 2020-07-28 Prima::VB::Classes(3)