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 Toplevel
16
17       For derived widget classes:
18
19        use base qw/ Tk::Derived Tk::DerivedWidget /;
20
21       Install the new widget in Tk's namespace and establish class and
22       instance constructors.
23
24        Construct Tk::Widget 'MyNewWidget';
25
26        sub ClassInit { my ($self, $args) = @_; ... }
27
28        sub Populate { my ($self, $args) = @_; ... }
29

DESCRIPTION

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

MEGA-WIDGET SUPPORT

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

PITFALLS

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

MISSING

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

KEYWORDS

353       mega, composite, derived, widget
354