Tk::mega(3pm)

1mega(3)               User Contributed Perl Documentation              mega(3)
2
3
4

NAME

6       Tk::mega - Perl/Tk support for writing widgets in pure Perl
7

SYNOPSIS

9       Define the widget's new class name:
10
11           package Tk::MyNewWidget;
12
13       For composite widget classes:
14
15           use base qw/ Tk::container /; # where container is Frame or
16       Toplevel
17
18       For derived widget classes:
19
20           use base qw/ Tk::Derived Tk::DerivedWidget /;
21
22       Install the new widget in Tk's namespace and establish class and
23       instance constructors.
24
25           Construct Tk::Widget 'MyNewWidget';
26
27           sub ClassInit { my ($self, $args) = @_; ... }
28
29           sub Populate { my ($self, $args) = @_; ... }
30

DESCRIPTION

32       The goal of the mega-widget support of Perl/Tk is to make it easy to
33       write mega-widgets that obey the same protocol and interface that the
34       Tk core widgets support.  For mega-widget sample code please run the
35       widget demonstration program and go to the section Sample Perl Mega-
36       Widgets.
37
38       There are two kinds of mega-widgets:
39
40       •   Composite Widgets
41
42           A composite widget is composed with one or more existing widgets.
43           The composite widget looks to the user like a simple single widget.
44           A well known example is the file selection box.
45
46       •   Derived Widgets
47
48           A derived widget adds/modifies/removes properties and methods from
49           a single widget (this widget may itself be a mega-widget).
50

MEGA-WIDGET SUPPORT

52   Advertise
53       Give a subwidget a symbolic name.
54
55       Usage:
56
57           $self->Advertise(name=>$widget);
58
59       Gives a subwidget $widget of the mega-widget $self the name name.  One
60       can retrieve the reference of an advertised subwidget with the
61       Subwidget method.
62
63       Comment: Mega-Widget Writers: Please make sure to document the
64       advertised widgets that are intended for public use.  If there are
65       none, document this fact, e.g.:
66
67               =head1 ADVERTISED WIDGETS
68
69               None.
70
71   Callback
72       Invoke a callback specified with an option.
73
74       Usage:
75
76           $self->Callback(-option ?,args ...?);
77
78       Callback executes the callback defined with $self->ConfigSpecs(-option,
79       [CALLBACK, ...]); If args are given they are passed to the callback. If
80       -option is not defined it does nothing.
81
82   ClassInit
83       Initialization of the mega-widget class.
84
85       Usage:
86
87           sub ClassInit { my ($class, $mw) = @_; ...  }
88
89       ClassInit is called once for each MainWindow just before the first
90       widget instance of a class is created in the widget tree of MainWindow.
91
92       ClassInit is often used to define bindings and/or other resources
93       shared by all instances, e.g., images.
94
95       Examples:
96
97        $mw->bind($class,"<Tab>", sub { my $w = shift; $w->Insert("\t"); $w->focus; $w->break});
98        $mw->bind($class,"<Return>", ['Insert',"\n"]);
99        $mw->bind($class,"<Delete>",'Delete');
100
101       Notice that $class is the class name (e.g. Tk::MyText) and $mw is the
102       mainwindow.
103
104       Don't forget to call $class->SUPER::ClassInit($mw) in ClassInit.
105
106   Component
107       Convenience function to create subwidgets.
108
109       Usage:
110
111           $cw->Component('Whatever', 'AdvertisedName',
112               -delegate => ['method1', 'method2', ...],
113               ... more widget options ...,
114           );
115
116       Component does several things for you with one call:
117
118           o Creates the widget
119
120           o Advertises it with a given name (overridden by 'Name' option)
121
122           o Delegates a set of methods to this widget (optional)
123
124       Example:
125
126           $cw->Component('Button', 'quitButton', -command => sub{$mw->'destroy'});
127
128   ConfigSpecs
129       Defines options and their treatment
130
131       Usage:
132
133           $cw->ConfigSpecs(
134               -option => [ where, dbname, dbclass, default],
135               ...,
136               DEFAULT => [where],
137           );
138
139       Defines the options of a mega-widget and what actions are triggered by
140       configure/cget of an option (see Tk::ConfigSpecs and Tk::Derived for
141       details).
142
143   Construct
144       Make the new mega-widget known to Tk.
145
146       Usage:
147
148           Construct baseclass 'Name';
149
150       Construct declares the new widget class so that your mega-widget works
151       like normal Perl/Tk widgets.
152
153       Examples:
154
155           Construct Tk::Widget 'Whatever';     Construct Tk::Menu   'MyItem';
156
157       First example lets one use $widget->Whatever to create new Whatever
158       widget.
159
160       The second example restricts the usage of the MyItem constructor method
161       to widgets that are derived from Menu: $isamenu->MyItem.
162
163   CreateArgs
164       Process options before any widget is created:
165
166           sub CreateArgs { my ($package, $parent, $args) = @_; ...; return
167       @newargs; }
168
169       $package is the package of the mega-widget (e.g., Tk::MyText, $parent
170       the parent of the widget to be created and $args the hash reference to
171       the options specified in the widget constructor call.
172
173       Don't forget to call $package->SUPER::CreateArgs($parent, $args) in
174       CreateArgs.
175
176   Delegates
177       Redirect a method of the mega-widget to a subwidget of the composite
178       widget
179
180       Usage:
181
182           $cw->Delegates(
183               'method1' => $subwidget1,
184               'method2' => 'advertived_name',
185               ...,
186               'Construct' => $subwidget2,
187               'DEFAULT'   => $subwidget3,
188           );
189
190       The 'Construct' delegation has a special meaning.  After 'Construct' is
191       delegated all Widget constructors are redirected.  E.g. after
192
193           $self->Delegates('Construct'=>$subframe);
194
195       a $self->Button does really a $subframe->Button so the created button
196       is a child of $subframe and not $self.
197
198       Comment: Delegates works only with methods that $cw does not have
199       itself.
200
201   InitObject
202       Note: this method should not, in general, be used, as it has been
203       superceeded by Populate and specifying Tk::Derived as one of the base
204       classes.
205
206       Defines construction and interface of derived widgets.
207
208       Usage:
209
210           sub InitObject {
211               my ($derived, $args) = @_;
212               ...
213           }
214
215       where $derived is the widget reference of the already created baseclass
216       widget and $args is the reference to a hash of -option-value pairs.
217
218       InitObject is almost identical to Populate method.  Populate does some
219       more 'magic' things useful for mega-widgets with several widgets.
220
221       Don't forget to call $derived->SUPER::InitObject($args) in InitObject.
222
223   OnDestroy
224       Define a callback invoked when the mega-widget is destroyed.
225
226       Usage:
227
228           $widget->OnDestroy(callback);
229
230       OnDestroy installs a callback that's called when a widget is going to
231       to be destroyed.  Useful for special cleanup actions.  It differs from
232       a normal destroy in that all the widget's data structures are still
233       intact.
234
235       Comment: This method could be used with any widgets not just for mega-
236       widgets.  It's listed here because of its usefulness.
237
238   Populate
239       Defines construction and interface of the composite widget.
240
241       Usage:
242
243           sub Populate {
244               my ($self, $args) = @_;
245               ...
246           }
247
248       where $self is the widget reference of the already created baseclass
249       widget and $args is the reference to a hash of -option-value pairs.
250
251       Most the other support function are normally used inside the Populate
252       subroutine.
253
254       Don't forget to call $cw->SUPER::Populate($args) in Populate.
255
256   privateData
257       Set/get a private hash of a widget to storage composite internal data
258
259       Usage:
260
261           $hashref = $self->privateData();
262
263           $another = $self->privateData(unique_key|package);
264
265   Subwidget
266       Get the widget reference of an advertised subwidget.
267
268           @subwidget = $cw->Subwidget();
269
270           $subwidget = $cw->Subwidget(name);
271
272           @subwidget = $cw->Subwidget(name ?,...?);
273
274       Returns the widget reference(s) of the subwidget known under the given
275       name(s). Without arguments, return all known subwidgets of $cw. See
276       Advertise method how to define name for a subwidget.
277
278       Comment: Mega-Widget Users: Use Subwidget to get only documented
279       subwidgets.
280

PITFALLS

282       •   Resource DB class name
283
284           Some of the standard options use a resource date base class that is
285           not equal to the resource database name.  E.g.,
286
287             Switch:            Name:             Class:
288
289             -padx              padX              Pad
290             -activerelief      activeRelief      Relief
291             -activebackground  activeBackground  Foreground
292             -status            undef             undef
293
294           One should do the same when one defines one of these options via
295           ConfigSpecs.
296
297       •   Method delegation
298
299           Redirecting methods to a subwidget with Delegate can only work if
300           the base widget itself does have a method with this name.
301           Therefore one can't ``delegate'' any of the methods listed in
302           Tk::Widget.  A common problematic method is bind.  In this case one
303           as to explicitely redirect the method.
304
305             sub bind {
306                 my $self = shift;
307                 my $to = $self->privateData->{'my_bind_target'};
308                 $to->bind(@_);
309             }
310
311       •   privateData
312
313           Graham Barr wrote: ... It is probably more private than most people
314           think. Not all calls to privateData will return that same HASH
315           reference. The HASH reference that is returned depends on the
316           package it was called from, a different HASH is returned for each
317           package. This allows a widget to hold private data, but then if it
318           is sub-classed the sub-class will get a different HASH and so not
319           cause duplicate name clashes.
320
321           But privateData does take an optional argument if you want to force
322           which HASH is returned.
323
324       •   Scrolled and Composite
325
326           Scrolled(Kind,...) constructor can not be used with Composite.  One
327           has to use $cw->Composite(ScrlKind => 'name', ...);
328

MISSING

330       Of course Perl/Tk does not define support function for all necessities.
331       Here's a short list of things you have to handle yourself:
332
333       •   No support to define construction-time only options.
334
335       •   No support to remove an option that is known to the base widget.
336
337       •   It's hard to define undef as fallback for an widget option that is
338           not already undef.
339
340       •   Frame in Perl/Tk carries magic and overhead not needed for
341           composite widget class definition.
342
343       •   No support methods for bindings that are shared between all widgets
344           of a composite widget (makes sense at all?)
345

KEYWORDS

347       mega, composite, derived, widget
348