home *** CD-ROM | disk | FTP | other *** search
/ Netrunner 2004 October / NETRUNNER0410.ISO / regular / ActivePerl-5.8.4.810-MSWin32-x86.msi / _6baecd4e34cb92f8659d2b3ba1832d85 < prev    next >
Text File  |  2004-06-01  |  11KB  |  424 lines
  1.  
  2. ## Author: Achim Bohnet <ach@mpe.mpg.de>
  3. ##
  4. ## Copyright (c) 1997-1998 Achim Bohnet. All rights reserved.
  5. ## You can redistribute this document and/or modify it under the
  6. ## same terms as Perl itself.
  7. ##
  8. ## Update for Tk804.025, Steve Lidie, 2004/01/11.
  9.  
  10. =head1 NAME
  11.  
  12. Tk::mega - Perl/Tk support for writing widgets in pure Perl
  13.  
  14. =for category Derived Widgets
  15.  
  16. =head1 SYNOPSIS
  17.  
  18. Define the widget's new class name:
  19.  
  20. S<    >B<package Tk::>I<MyNewWidget>;
  21.  
  22. For composite widget classes:
  23.  
  24. S<    >B<use base qw/ Tk::container />; # where B<container> is I<Frame> or I<Toplevel>
  25.  
  26. For derived widget classes:
  27.  
  28. S<    >B<use base qw/ Tk::Derived Tk::DerivedWidget /;>
  29.  
  30. Install the new widget in Tk's namespace and establish class and instance
  31. constructors.
  32.  
  33. S<    >B<Construct Tk::>I<Widget> I<'MyNewWidget'>;
  34.  
  35. S<    >B<sub ClassInit> { I<my ($self, $args) = @_; ...> }
  36.  
  37. S<    >B<sub Populate> { I<my ($self, $args) = @_; ...> }
  38.  
  39. =head1 DESCRIPTION
  40.  
  41. The goal of the mega-widget support of Perl/Tk is to make it
  42. easy to write mega-widgets that obey the same protocol and
  43. interface that the Tk core widgets support.
  44. I<For mega-widget sample code please run the B<widget> demonstration program and go to the section B<Sample Perl Mega-Widgets>.>
  45.  
  46. There are two kinds of mega-widgets:
  47.  
  48. =over 4
  49.  
  50. =item * Composite Widgets
  51.  
  52. A composite widget is composed with one or more existing widgets.
  53. The composite widget looks to the user like a simple single widget.
  54. A well known example is the file selection box.
  55.  
  56. =item * Derived Widgets
  57.  
  58. A derived widget adds/modifies/removes properties and methods
  59. from a single widget (this widget may itself be a mega-widget).
  60.  
  61. =back
  62.  
  63. =head1 MEGA-WIDGET SUPPORT
  64.  
  65. =head2 Advertise
  66.  
  67. Give a subwidget a symbolic name.
  68.  
  69. Usage:
  70.  
  71. S<    >I<$self>-E<gt>B<Advertise>(B<name>=E<gt>I<$widget>);
  72.  
  73. Gives a subwidget I<$widget> of the mega-widget I<$self> the
  74. name B<name>.  One can retrieve the reference of an advertised subwidget
  75. with the L<Subwidget|"Subwidget"> method.
  76.  
  77. B<Comment:> Mega-Widget Writers: Please make sure to document the
  78. advertised widgets that are intended for I<public> use.
  79. If there are none, document this fact, e.g.:
  80.  
  81.     =head1 ADVERTISED WIDGETS
  82.  
  83.     None.
  84.  
  85. =head2 Callback
  86.  
  87. Invoke a callback specified with an option.
  88.  
  89. Usage:
  90.  
  91. S<    >I<$self>-E<gt>B<Callback>(I<-option> ?,I<args> ...?);
  92.  
  93. B<Callback> executes the L<callback|Tk::callbacks> defined with
  94. I<$self>-E<gt>B<ConfigSpecs>(I<-option>, [B<CALLBACK>, ...]);
  95. If I<args> are given they are passed to the callback. If
  96. I<-option> is not defined it does nothing.
  97.  
  98. =head2 ClassInit
  99.  
  100. Initialization of the mega-widget class.
  101.  
  102. Usage:
  103.  
  104. S<    >B<sub ClassInit> { I<my ($class, $mw) = @_;> ...  }
  105.  
  106. B<ClassInit> is called once for I<each> L<MainWindow|Tk::MainWindow>
  107. just before the first widget instance of a class is created in
  108. the widget tree of B<MainWindow>.
  109.  
  110. B<ClassInit> is often used to define bindings and/or other
  111. resources shared by all instances, e.g., images.
  112.  
  113. Examples:
  114.  
  115.  $mw->bind($class,"<Tab>", sub { my $w = shift; $w->Insert("\t"); $w->focus; $w->break});
  116.  $mw->bind($class,"<Return>", ['Insert',"\n"]);
  117.  $mw->bind($class,"<Delete>",'Delete');
  118.  
  119. Notice that I<$class> is the class name (e.g. B<Tk::MyText>) and I<$mw> is the mainwindow.
  120.  
  121. Don't forget to call I<$class>-E<gt>B<SUPER::ClassInit($mw)> in
  122. B<ClassInit>.
  123.  
  124. =head2 Component
  125.  
  126. Convenience function to create subwidgets.
  127.  
  128. Usage:
  129.  
  130.     $cw->Component('Whatever', 'AdvertisedName',
  131.         -delegate => ['method1', 'method2', ...],
  132.         ... more widget options ...,
  133.     );
  134.  
  135. B<Component> does several things for you with one call:
  136.  
  137. =over 4
  138.  
  139. o Creates the widget
  140.  
  141. o Advertises it with a given name (overridden by 'Name' option)
  142.  
  143. o Delegates a set of methods to this widget (optional)
  144.  
  145. =back
  146.  
  147. Example:
  148.  
  149.     $cw->Component('Button', 'quitButton', -command => sub{$mw->'destroy'});
  150.  
  151. =head2 ConfigSpecs
  152.  
  153. Defines options and their treatment
  154.  
  155. Usage:
  156.  
  157.     $cw->ConfigSpecs(
  158.         -option => [ where, dbname, dbclass, default],
  159.         ...,
  160.         DEFAULT => [where],
  161.     );
  162.  
  163. Defines the options of a mega-widget and what actions
  164. are triggered by configure/cget of an option
  165. (see L<Tk::ConfigSpecs> and L<Tk::Derived> for details).
  166.  
  167. =head2 Construct
  168.  
  169. Make the new mega-widget known to B<Tk>.
  170.  
  171. Usage:
  172.  
  173. S<    >B<Construct> I<baseclass> B<'Name'>;
  174.  
  175. B<Construct> declares the new widget class so that your mega-widget
  176. works like normal Perl/Tk widgets.
  177.  
  178. Examples:
  179.  
  180. S<    >B<Construct Tk::Widget> I<'Whatever'>;
  181. S<    >B<Construct Tk::Menu>   I<'MyItem'>;
  182.  
  183. First example lets one use I<$widget>-E<gt>B<Whatever> to create
  184. new B<Whatever> widget.
  185.  
  186. The second example restricts the usage of the B<MyItem> constructor
  187. method to widgets that are derived from B<Menu>:
  188. I<$isamenu>-E<gt>I<MyItem>.
  189.  
  190. =head2 CreateArgs
  191.  
  192. Process options before any widget is created:
  193.  
  194. S<    >B<sub CreateArgs> { I<my ($package, $parent, $args) = @_; ...; return @newargs;> }
  195.  
  196. I<$package> is the package of the mega-widget (e.g., B<Tk::MyText>,
  197. I<$parent> the parent of the widget to be created and $args the hash
  198. reference to the options specified in the widget constructor call.
  199.  
  200. Don't forget to call I<$package>-E<gt>B<SUPER::CreateArgs>(I<$parent>, I<$args>) in
  201. B<CreateArgs>.
  202.  
  203. =head2 Delegates
  204.  
  205. Redirect a method of the mega-widget to a subwidget of
  206. the composite widget
  207.  
  208. Usage:
  209.  
  210.     $cw->Delegates(
  211.         'method1' => $subwidget1,
  212.         'method2' => 'advertived_name',
  213.         ...,
  214.         'Construct' => $subwidget2,
  215.         'DEFAULT'   => $subwidget3,
  216.     );
  217.  
  218. The B<'Construct'> delegation has a special meaning.  After
  219. 'Construct' is delegated all Widget constructors are redirected.
  220. E.g. after
  221.  
  222. S<    >I<$self>-E<gt>B<Delegates>(B<'Construct'>=E<gt>I<$subframe>);
  223.  
  224. a I<$self>-E<gt>B<Button> does really a I<$subframe>-E<gt>B<Button>
  225. so the created button is a child of I<$subframe> and not I<$self>.
  226.  
  227. B<Comment:> Delegates works only with methods that I<$cw> does
  228. not have itself.
  229.  
  230. =head2 InitObject
  231.  
  232. I<Note: this method should not, in general, be used, as it has been
  233. superceeded by B<Populate> and specifying B<Tk::Derived> as one of the base
  234. classes.>
  235.  
  236. Defines construction and interface of derived widgets.
  237.  
  238. Usage:
  239.  
  240.     sub InitObject {
  241.     my ($derived, $args) = @_;
  242.     ...
  243.     }
  244.  
  245. where I<$derived> is the widget reference of the already created
  246. baseclass widget and I<$args> is the reference to a hash of
  247. I<-option-value> pairs.
  248.  
  249. B<InitObject> is almost identical to L<Populate|"Populate"> method.
  250. B<Populate> does some more 'magic' things useful for mega-widgets
  251. with several widgets.
  252.  
  253. Don't forget to call I<$derived>-E<gt>B<SUPER::InitObject>(I<$args>) in
  254. B<InitObject>.
  255.  
  256. =head2 OnDestroy
  257.  
  258. Define a callback invoked when the mega-widget is destroyed.
  259.  
  260. Usage:
  261.  
  262. S<    >I<$widget>-E<gt>B<OnDestroy>(I<callback>);
  263.  
  264. B<OnDestroy> installs a L<callback|Tk::callbacks> that's called
  265. when a widget is going to to be destroyed.  Useful
  266. for special cleanup actions.  It differs from a normal B<destroy>
  267. in that all the widget's data structures are still intact.
  268.  
  269. B<Comment:> This method could be used with any widgets not just
  270. for mega-widgets.  It's listed here because of it's usefulness.
  271.  
  272. =head2 Populate
  273.  
  274. Defines construction and interface of the composite
  275. widget.
  276.  
  277. Usage:
  278.  
  279.     sub Populate {
  280.     my ($self, $args) = @_;
  281.     ...
  282.     }
  283.  
  284. where I<$self> is the widget reference of the already created baseclass
  285. widget and I<$args> is the
  286. reference to a hash of I<-option-value> pairs.
  287.  
  288. Most the other support function are normally used inside the B<Populate>
  289. subroutine.
  290.  
  291. Don't forget to call I<$cw>-E<gt>B<SUPER::Populate>(I<$args>) in
  292. B<Populate>.
  293.  
  294. =head2 privateData
  295.  
  296. Set/get a private hash of a widget to storage
  297. composite internal data
  298.  
  299. Usage:
  300.  
  301. S<    >I<$hashref> = I<$self>-E<gt>B<privateData>();
  302.  
  303. S<    >I<$another> = I<$self>-E<gt>B<privateData>(I<unique_key>|I<package>);
  304.  
  305. =head2 Subwidget
  306.  
  307. Get the widget reference of an advertised subwidget.
  308.  
  309. S<    >I<@subwidget> = I<$cw>-E<gt>B<Subwidget>();
  310.  
  311. S<    >I<$subwidget> = I<$cw>-E<gt>B<Subwidget>(I<name>);
  312.  
  313. S<    >I<@subwidget> = I<$cw>-E<gt>B<Subwidget>(I<name> ?,...?);
  314.  
  315. Returns the widget reference(s) of the subwidget known under the given
  316. name(s). Without arguments, return all known subwidgets of I<$cw>. See
  317. L<Advertise|"Advertise"> method how to define I<name> for a subwidget.
  318.  
  319. B<Comment:> Mega-Widget Users: Use B<Subwidget> to get I<only>
  320. documented subwidgets.
  321.  
  322. =head1 PITFALLS
  323.  
  324. =over 4
  325.  
  326. =item * Resource DB class name
  327.  
  328. Some of the standard options use a resource date base class
  329. that is not equal to the resource database name.  E.g.,
  330.  
  331.   Switch:            Name:             Class:
  332.  
  333.   -padx              padX              Pad
  334.   -activerelief      activeRelief      Relief
  335.   -activebackground  activeBackground  Foreground
  336.   -status            undef             undef
  337.  
  338. One should do the same when one defines one of these
  339. options via B<ConfigSpecs>.
  340.  
  341. =item * Method delegation
  342.  
  343. Redirecting methods to a subwidget with B<Delegate>
  344. can only work if the base widget itself does have a
  345. method with this name.  Therefore one can't ``I<delegate>''
  346. any of the methods listed in L<Tk::Widget|Tk::Widget>.
  347. A common problematic method is B<bind>.  In this case
  348. one as to explicitely redirect the method.
  349.  
  350.   sub bind {
  351.       my $self = shift;
  352.       my $to = $self->privateData->{'my_bind_target'};
  353.       $to->bind(@_);
  354.   }
  355.  
  356. =item * privateData
  357.  
  358. Graham Barr wrote: ... It is probably
  359. more private than most people think. Not all calls to privateData will
  360. return that same HASH reference. The HASH reference that is returned
  361. depends on the package it was called from, a different HASH is returned
  362. for each package. This allows a widget to hold private data, but then
  363. if it is sub-classed the sub-class will get a different HASH and so not
  364. cause duplicate name clashes.
  365.  
  366. But privateData does take an optional argument if you want to
  367. force which HASH is returned.
  368.  
  369. =item * Scrolled and Composite
  370.  
  371. B<Scrolled>(I<Kind>,...) constructor can not be used with B<Composite>.
  372. One has to use $cw->B<Composite>(B<Scrl>I<Kind> =E<gt> B<'name'>, ...);
  373.  
  374. =back
  375.  
  376. =head1 MISSING
  377.  
  378. Of course Perl/Tk does not define support function for
  379. all necessities.  Here's a short list of things you have to
  380. handle yourself:
  381.  
  382. =over 4
  383.  
  384. =item *
  385.  
  386. No support to define construction-time only options.
  387.  
  388. =item *
  389.  
  390. No support to remove an option that is known to the
  391. base widget.
  392.  
  393. =item *
  394.  
  395. It's hard to define B<undef> as fallback for an widget
  396. option that is not already B<undef>.
  397.  
  398. =item *
  399.  
  400. Frame in Perl/Tk carries magic and overhead not needed
  401. for composite widget class definition.
  402.  
  403. =item *
  404.  
  405. No support methods for bindings that are shared between all
  406. widgets of a composite widget (makes sense at all?)
  407.  
  408. =back
  409.  
  410. =head1 KEYWORDS
  411.  
  412. mega, composite, derived, widget
  413.  
  414. =head1 SEE ALSO
  415.  
  416. L<Tk::composite|Tk::composite>
  417. L<Tk::ConfigSpecs|Tk::ConfigSpecs>
  418. L<Tk::option|Tk::option>
  419. L<Tk::callbacks|Tk::callbacks>
  420. L<Tk::bind|Tk::bind>
  421.  
  422. =cut
  423.  
  424.