home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _74a24c0a065c3f425380fc6f542c03ed < prev    next >
Text File  |  2000-03-23  |  16KB  |  369 lines

  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Tk::mega - perl/Tk support to write widgets in perl</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> Tk::mega - perl/Tk support to write widgets in perl</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#mega widget support">MEGA WIDGET SUPPORT</A></LI>
  26.     <UL>
  27.  
  28.         <LI><A HREF="#advertise">Advertise</A></LI>
  29.         <LI><A HREF="#callback">Callback</A></LI>
  30.         <LI><A HREF="#classinit">ClassInit</A></LI>
  31.         <LI><A HREF="#component">Component</A></LI>
  32.         <LI><A HREF="#configspecs">ConfigSpecs</A></LI>
  33.         <LI><A HREF="#construct">Construct</A></LI>
  34.         <LI><A HREF="#createargs">CreateArgs</A></LI>
  35.         <LI><A HREF="#delegates">Delegates</A></LI>
  36.         <LI><A HREF="#initobject">InitObject</A></LI>
  37.         <LI><A HREF="#ondestroy">OnDestroy</A></LI>
  38.         <LI><A HREF="#populate">Populate</A></LI>
  39.         <LI><A HREF="#privatedata">privateData</A></LI>
  40.         <LI><A HREF="#subwidget">Subwidget</A></LI>
  41.     </UL>
  42.  
  43.     <LI><A HREF="#pitfalls">PITFALLS</A></LI>
  44.     <LI><A HREF="#missing">MISSING</A></LI>
  45.     <LI><A HREF="#keywords">KEYWORDS</A></LI>
  46.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  47. </UL>
  48. <!-- INDEX END -->
  49.  
  50. <HR>
  51. <P>
  52. <H1><A NAME="name">NAME</A></H1>
  53. <P>Tk::mega - perl/Tk support to write widgets in perl</P>
  54. <P>
  55. <HR>
  56. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  57. <UL>
  58. <LI>Linux</LI>
  59. <LI>Solaris</LI>
  60. <LI>Windows</LI>
  61. </UL>
  62. <HR>
  63. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  64. <P>    <STRONG>package Tk::</STRONG><EM>Whatever</EM>;</P>
  65. <P>    <STRONG>Construct Tk::</STRONG><EM>ValidFor</EM> <EM>'Whatever'</EM>;</P>
  66. <P>    <STRONG>sub ClassInit</STRONG> { <EM>my ($mega, $args) = @_; ...</EM> }</P>
  67. <P>For composite widget classes:</P>
  68. <P>    <STRONG>sub Populate</STRONG> { <EM>my ($composite, $args) = @_; ...</EM> }</P>
  69. <P>For derived widget classes:</P>
  70. <P>    <STRONG>sub InitObject</STRONG> { <EM>my ($derived, $args) = @_; ...</EM> }</P>
  71. <P>
  72. <HR>
  73. <H1><A NAME="description">DESCRIPTION</A></H1>
  74. <P>The goal of the mega widget support of perl/Tk is to make it
  75. easy to write mega widgets that obey the same protocol and
  76. interface that the Tk core widgets support.  There are two
  77. kinds of mega widgets:</P>
  78. <UL>
  79. <LI><STRONG><A NAME="item_Composite_Widgets">Composite Widgets</A></STRONG><BR>
  80.  
  81. A composite widget is composed with one or more existing widgets.
  82. The composite widget looks to the user like a simple single widget.
  83. A well known example is the file selection box.
  84. <P></P>
  85. <LI><STRONG><A NAME="item_Derived_Widgets">Derived Widgets</A></STRONG><BR>
  86.  
  87. A derived widget adds/modifies/removes properties and methods
  88. from a single widget (this widget may itself be a mega widget).
  89. <P></P></UL>
  90. <P>
  91. <HR>
  92. <H1><A NAME="mega widget support">MEGA WIDGET SUPPORT</A></H1>
  93. <P>
  94. <H2><A NAME="advertise">Advertise</A></H2>
  95. <P>Give a subwidget a symbolic name.</P>
  96. <P>Usage:</P>
  97. <P>    <EM>$cw</EM>-><STRONG>Advertise</STRONG>(<STRONG>name</STRONG>=><EM>$widget</EM>);</P>
  98. <P>Gives a subwidget <EM>$widget</EM> of the composite widget <EM>$cw</EM> the
  99. name <STRONG>name</STRONG>.  One can retrieve the reference of an advertised subwidget
  100. with the <A HREF="#subwidget">Subwidget</A> method.</P>
  101. <P><STRONG>Comment:</STRONG> Mega Widget Writers: Please make sure to document the
  102. advertised widgets that are intended for <EM>public</EM> use.
  103. If there are none, document this fact, e.g.:</P>
  104. <PRE>
  105.         =head1 ADVERTISED WIDGETS</PRE>
  106. <PRE>
  107.         None.</PRE>
  108. <P>
  109. <H2><A NAME="callback">Callback</A></H2>
  110. <P>Invoke a callback specified with an option.</P>
  111. <P>Usage:</P>
  112. <P>    <EM>$mega</EM>-><STRONG>Callback</STRONG>(<EM>-option</EM> ?,<EM>args</EM> ...?);</P>
  113. <P><STRONG>Callback</STRONG> executes the <A HREF="../../../site/lib/Tk/callbacks.html">callback</A> defined with
  114. <EM>$mega</EM>-><STRONG>ConfigSpecs</STRONG>(<EM>-option</EM>, [<STRONG>CALLBACK</STRONG>, ...]);
  115. If <EM>args</EM> are given they are passed to the callback. If
  116. <EM>-option</EM> is not defined it does nothing.</P>
  117. <P>
  118. <H2><A NAME="classinit">ClassInit</A></H2>
  119. <P>Initialization of the mega widget class.</P>
  120. <P>Usage:</P>
  121. <P>    <STRONG>sub ClassInit</STRONG> { <EM>my ($class, $mw) = @_;</EM> ...  }</P>
  122. <P><STRONG>ClassInit</STRONG> is called once for <EM>each</EM> <A HREF="../../../site/lib/Tk/MainWindow.html">MainWindow</A>
  123. just before the first widget instance of a class is created in
  124. the widget tree of <STRONG>MainWindow</STRONG>.</P>
  125. <P><STRONG>ClassInit</STRONG> is often used to define bindings and/or other
  126. resources shared by all instances, e.g., images.</P>
  127. <P>Examples:</P>
  128. <PRE>
  129.  $mw->bind($class,"<Tab>", sub { my $w = shift; $w->Insert("\t"); $w->focus; $w->break});
  130.  $mw->bind($class,"<Return>", ['Insert',"\n"]);
  131.  $mw->bind($class,"<Delete>",'Delete');</PRE>
  132. <P>Notice that <EM>$class</EM> is the class name (e.g. <STRONG>Tk::MyText</STRONG>) and <EM>$mw</EM> is the mainwindow.</P>
  133. <P>Don't forget to call <EM>$class</EM>-><STRONG>SUPER::ClassInit($mw)</STRONG> in
  134. <STRONG>ClassInit</STRONG>.</P>
  135. <P>
  136. <H2><A NAME="component">Component</A></H2>
  137. <P>Convenience function to create subwidgets.</P>
  138. <P>Usage:</P>
  139. <PRE>
  140.     $cw->Component('Whatever', 'AdvertisedName',
  141.                    -delegate => ['method1', 'method2', ...],
  142.                    ... Whatever widget options ...,
  143.                   );</PRE>
  144. <P><STRONG>Component</STRONG> does several things for you with one call:</P>
  145. <P>o Creates the widget</P>
  146. <P>o Advertises it with a given name (overridden by 'Name' option)</P>
  147. <P>o Delegates a set of methods to this widget (optional)</P>
  148. <P>Example:</P>
  149. <PRE>
  150.     $cw->Component('Button', 'quitButton', -command => sub{$mw->'destroy'});</PRE>
  151. <P>
  152. <H2><A NAME="configspecs">ConfigSpecs</A></H2>
  153. <P>Defines options and their treatment</P>
  154. <P>Usage:</P>
  155. <PRE>
  156.     $cw->ConfigSpecs(
  157.             -option => [ where, dbname, dbclass, default],
  158.             ...,
  159.             DEFAULT => [where],
  160.             );</PRE>
  161. <P>Defines the options of a mega widget and what actions
  162. are triggered by configure/cget of an option
  163. (see <A HREF="../../../Tk/ConfigSpecs.html">the Tk::ConfigSpecs manpage</A> and <A HREF="../../../site/lib/Tk/Derived.html">the Tk::Derived manpage</A> for details).</P>
  164. <P>
  165. <H2><A NAME="construct">Construct</A></H2>
  166. <P>Make the new mega widget known to <STRONG>Tk</STRONG>.</P>
  167. <P>Usage:</P>
  168. <P>    <STRONG>Construct</STRONG> <EM>baseclass</EM> <STRONG>'Name'</STRONG>;</P>
  169. <P><STRONG>Construct</STRONG> declares the new widget class so that your mega widget
  170. works like normal Perl/Tk widgets.</P>
  171. <P>Examples:</P>
  172. <P>    <STRONG>Construct Tk::Widget</STRONG> <EM>'Whatever'</EM>;
  173.     <STRONG>Construct Tk::Menu</STRONG>   <EM>'MyItem'</EM>;</P>
  174. <P>First example lets one use <EM>$widget</EM>-><STRONG>Whatever</STRONG> to create
  175. new <STRONG>Whatever</STRONG> widget.</P>
  176. <P>The second example restricts the usage of the <STRONG>MyItem</STRONG> constructor
  177. method to widgets that are derived from <STRONG>Menu</STRONG>:
  178. <EM>$isamenu</EM>-><EM>MyItem</EM>.</P>
  179. <P>
  180. <H2><A NAME="createargs">CreateArgs</A></H2>
  181. <P>Mess with options before any widget is created</P>
  182. <P>    <STRONG>sub CreateArgs</STRONG> { <EM>my ($package, $parent, $args) = @_; ...; return @newargs;</EM> }</P>
  183. <P><EM>$package</EM> is the package of the mega widget (e.g., <STRONG>Tk::MyText</STRONG>,
  184. <EM>$parent</EM> the parent of the widget to be created and $args the hash
  185. reference to the options specified in the widget constructor call.</P>
  186. <P>Don't forget to call <EM>$package</EM>-><STRONG>SUPER::CreateArgs</STRONG>(<EM>$parent</EM>, <EM>$args</EM>) in
  187. <STRONG>CreateArgs</STRONG>.</P>
  188. <P>
  189. <H2><A NAME="delegates">Delegates</A></H2>
  190. <P>Redirect a method of the mega widget to a subwidget of
  191. the composite widget</P>
  192. <P>Usage:</P>
  193. <PRE>
  194.     $cw->Delegates(
  195.                 'method1' => $subwidget1,
  196.                 'method2' => 'advertived_name',
  197.                 ...,
  198.                 'Construct' => $subwidget2,
  199.                 'DEFAULT'   => $subwidget3,
  200.                 );</PRE>
  201. <P>The <STRONG>'Construct'</STRONG> delegation has a special meaning.  After
  202. 'Construct' is delegated all Widget constructors are redirected.
  203. E.g. after</P>
  204. <P>    <EM>$mega</EM>-><STRONG>Delegates</STRONG>(<STRONG>'Construct'</STRONG>=><EM>$subframe</EM>);</P>
  205. <P>a <EM>$mega</EM>-><STRONG>Button</STRONG> does really a <EM>$subframe</EM>-><STRONG>Button</STRONG>
  206. so the created button is a child of <EM>$subframe</EM> and not <EM>$mega</EM>.</P>
  207. <P><STRONG>Comment:</STRONG> Delegates works only with methods that <EM>$cw</EM> does
  208. not have itself.</P>
  209. <P>
  210. <H2><A NAME="initobject">InitObject</A></H2>
  211. <P>Defines construction and interface of derived widgets.</P>
  212. <P>Usage:</P>
  213. <PRE>
  214.     sub InitObject {
  215.         my ($derived, $args) = @_;
  216.         ...
  217.     }</PRE>
  218. <P>where <EM>$derived</EM> is the widget reference of the already created
  219. baseclass widget and <EM>$args</EM> is the reference to a hash of
  220. <EM>-option-value</EM> pairs.</P>
  221. <P><STRONG>InitObject</STRONG> is almost identical to <A HREF="#populate">Populate</A> method.
  222. <STRONG>Populate</STRONG> does some more 'magic' things useful for mega widgets
  223. with several widgets.</P>
  224. <P>Don't forget to call <EM>$derived</EM>-><STRONG>SUPER::InitObject</STRONG>(<EM>$args</EM>) in
  225. <STRONG>InitObject</STRONG>.</P>
  226. <P>
  227. <H2><A NAME="ondestroy">OnDestroy</A></H2>
  228. <P>Define callback invoked when widget is destroyed.</P>
  229. <P>Usage:</P>
  230. <P>    <EM>$widget</EM>-><STRONG>OnDestroy</STRONG>(<EM>callback</EM>);</P>
  231. <P><STRONG>OnDestroy</STRONG> installs a <A HREF="../../../site/lib/Tk/callbacks.html">callback</A> that's called
  232. when a widget is going to to be destroyed.  Useful
  233. for special cleanup actions.  It differs from a normal <STRONG>destroy</STRONG>
  234. in that all the widget's data structures are still intact.</P>
  235. <P><STRONG>Comment:</STRONG> This method could be used with any widgets not just
  236. for mega widgets.  It's listed here because of it's usefulness.</P>
  237. <P>
  238. <H2><A NAME="populate">Populate</A></H2>
  239. <P>Defines construction and interface of the composite
  240. widget.</P>
  241. <P>Usage:</P>
  242. <PRE>
  243.     sub Populate {
  244.         my ($mega, $args) = @_;
  245.         ...
  246.     }</PRE>
  247. <P>where <EM>$mega</EM> is the widget reference of the already created baseclass
  248. widget and <EM>$args</EM> is the
  249. reference to a hash of <EM>-option-value</EM> pairs.</P>
  250. <P>Most the other support function are normally used inside the <STRONG>Populate</STRONG>
  251. subroutine.</P>
  252. <P>Don't forget to call <EM>$cw</EM>-><STRONG>SUPER::Populate</STRONG>(<EM>$args</EM>) in
  253. <STRONG>Populate</STRONG>.</P>
  254. <P>
  255. <H2><A NAME="privatedata">privateData</A></H2>
  256. <P>Set/get a private hash of a widget to storage
  257. composite internal data</P>
  258. <P>Usage:</P>
  259. <P>    <EM>$hashref</EM> = <EM>$mega</EM>-><STRONG>privateData</STRONG>();</P>
  260. <P>    <EM>$another</EM> = <EM>$mega</EM>-><STRONG>privateData</STRONG>(<EM>unique_key</EM>|<EM>package</EM>);</P>
  261. <P>
  262. <H2><A NAME="subwidget">Subwidget</A></H2>
  263. <P>Get the widget reference of an advertised subwidget.</P>
  264. <P>    <EM>$subwidget</EM> = <EM>$cw</EM>-><STRONG>Subwidget</STRONG>(<EM>name</EM>);</P>
  265. <P>    <EM>@subwidget</EM> = <EM>$cw</EM>-><STRONG>Subwidget</STRONG>(<EM>name</EM> ?,...?);</P>
  266. <P>Returns the widget <CODE>reference(s)</CODE> of the subwidget known under the
  267. name <EM>name</EM>.  See <A HREF="#advertise">Advertise</A> method how to define
  268. <EM>name</EM> for a subwidget.</P>
  269. <P><STRONG>Comment:</STRONG> Mega Widget Users: Use <STRONG>Subwidget</STRONG> to get <EM>only</EM>
  270. documented subwidgets.</P>
  271. <P>
  272. <HR>
  273. <H1><A NAME="pitfalls">PITFALLS</A></H1>
  274. <UL>
  275. <LI><STRONG><A NAME="item_Resource_DB_class_name">Resource DB class name</A></STRONG><BR>
  276.  
  277. Some of the standard options use a resource date base class
  278. that is not equal to the resource database name.  E.g.,
  279. <PRE>
  280.   Switch:            Name:             Class:</PRE>
  281. <PRE>
  282.   -padx              padX              Pad
  283.   -activerelief      activeRelief      Relief
  284.   -activebackground  activeBackground  Foreground
  285.   -status            undef             undef</PRE>
  286. <P>One should do the same when one defines one of these
  287. options via <STRONG>ConfigSpecs</STRONG>.</P>
  288. <P></P>
  289. <LI><STRONG><A NAME="item_Method_delegation">Method delegation</A></STRONG><BR>
  290.  
  291. Redirecting methods to a subwidget with <STRONG>Delegate</STRONG>
  292. can only work if the base widget itself does have a
  293. method with this name.  Therefore one can't ``<EM>delegate</EM>''
  294. any of the methods listed in <A HREF="../../../site/lib/Tk/Widget.html">Tk::Widget</A>.
  295. A common problematic method is <STRONG>bind</STRONG>.  In this case
  296. one as to explicitely redirect the method.
  297. <PRE>
  298.   sub bind
  299.     {
  300.       my $mega = shift;
  301.       my $to = $mega->privateData->{'my_bind_target'};
  302.       $to->bind(@_);
  303.     }</PRE>
  304. <P></P>
  305. <LI><STRONG><A NAME="item_privateData">privateData</A></STRONG><BR>
  306.  
  307. Graham Barr wrote: ... It is probably
  308. more private than most people think. Not all calls to privateData will
  309. return that same HASH reference. The HASH reference that is returned
  310. depends on the package it was called from, a different HASH is returned
  311. for each package. This allows a widget to hold private data, but then
  312. if it is sub-classed the sub-class will get a different HASH and so not
  313. cause duplicate name clashes.
  314. <P>But privateData does take an optional argument if you want to
  315. force which HASH is returned.</P>
  316. <P></P>
  317. <LI><STRONG><A NAME="item_Scrolled_and_Composite">Scrolled and Composite</A></STRONG><BR>
  318.  
  319. <STRONG>Scrolled</STRONG>(<EM>Kind</EM>,...) constructor can not be used with <STRONG>Composite</STRONG>.
  320. One has to use $cw-><STRONG>Composite</STRONG>(<STRONG>Scrl</STRONG><EM>Kind</EM> => <STRONG>'name'</STRONG>, ...);
  321. <P></P></UL>
  322. <P>
  323. <HR>
  324. <H1><A NAME="missing">MISSING</A></H1>
  325. <P>Of course perl/Tk does not define support function for
  326. all necessities.  Here's a short list of things you have to
  327. handle yourself:</P>
  328. <UL>
  329. <LI>
  330. no support to define construction-time only options.
  331. <P></P>
  332. <LI>
  333. no support to remove an option that is known to the
  334. base widget.
  335. <P></P>
  336. <LI>
  337. it's hard to define <STRONG>undef</STRONG> as fallback for an widget
  338. option that is not already <STRONG>undef</STRONG>.
  339. <P></P>
  340. <LI>
  341. Frame in perl/Tk carries magic and overhead not needed
  342. for composite widget class definition.
  343. <P></P>
  344. <LI>
  345. No support methods for bindings that are shared between all
  346. widgets of a composite widget (makes sense at all?)
  347. <P></P></UL>
  348. <P>
  349. <HR>
  350. <H1><A NAME="keywords">KEYWORDS</A></H1>
  351. <P>mega, composite, derived, widget</P>
  352. <P>
  353. <HR>
  354. <H1><A NAME="see also">SEE ALSO</A></H1>
  355. <P><A HREF="../../../site/lib/Tk/composite.html">Tk::composite</A>
  356. <A HREF="../../../Tk/ConfigSpecs.html">Tk::ConfigSpecs</A>
  357. <A HREF="../../../site/lib/Tk/option.html">Tk::option</A>
  358. <A HREF="../../../site/lib/Tk/callbacks.html">Tk::callbacks</A>
  359. <A HREF="../../../site/lib/Tk/bind.html">Tk::bind</A></P>
  360. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  361. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  362. <STRONG><P CLASS=block> Tk::mega - perl/Tk support to write widgets in perl</P></STRONG>
  363. </TD></TR>
  364. </TABLE>
  365.  
  366. </BODY>
  367.  
  368. </HTML>
  369.