home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _5c62b4551a18243e2b820c9033ca738d < prev    next >
Text File  |  2000-03-23  |  9KB  |  226 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Tk::composite - Defining a new composite widget class</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::composite - Defining a new composite widget class</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="#glory details">GLORY DETAILS</A></LI>
  26.     <UL>
  27.  
  28.         <LI><A HREF="#composite widget">Composite Widget</A></LI>
  29.         <LI><A HREF="#creating subwidgets">Creating Subwidgets</A></LI>
  30.         <LI><A HREF="#further steps for frame based composites">Further steps for Frame based composites</A></LI>
  31.     </UL>
  32.  
  33.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  34. </UL>
  35. <!-- INDEX END -->
  36.  
  37. <HR>
  38. <P>
  39. <H1><A NAME="name">NAME</A></H1>
  40. <P>Tk::composite - Defining a new composite widget class</P>
  41. <P>
  42. <HR>
  43. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  44. <UL>
  45. <LI>Linux</LI>
  46. <LI>Solaris</LI>
  47. <LI>Windows</LI>
  48. </UL>
  49. <HR>
  50. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  51. <PRE>
  52.     package Tk::Whatever;</PRE>
  53. <PRE>
  54.     require Tk::Derived;
  55.     require Tk::Frame;                    # or Tk::Toplevel
  56.     @ISA = qw(Tk::Derived Tk::Frame)';    # or Tk::Toplevel</PRE>
  57. <PRE>
  58.     Construct Tk::Widget 'Whatever';</PRE>
  59. <PRE>
  60.     sub ClassInit
  61.     {
  62.      my ($class,$mw) = @_;</PRE>
  63. <PRE>
  64.      #... e.g., class bindings here ...
  65.      $class->SUPER::ClassInit($mw);
  66.     }</PRE>
  67. <PRE>
  68.     sub Populate
  69.     {
  70.      my ($cw,$args) = @_;</PRE>
  71. <PRE>
  72.      my $flag = delete $args->{-flag};
  73.      if (defined $flag)
  74.       {
  75.        # handle -flag => xxx which can only be done at create
  76.        # time the delete above ensures that new() does not try
  77.        # and do  $cw->configure(-flag => xxx);
  78.       }</PRE>
  79. <PRE>
  80.      $cw->SUPER::Populate($args);</PRE>
  81. <PRE>
  82.      $w = $cw->Component(...);</PRE>
  83. <PRE>
  84.      $cw->Delegates(...);</PRE>
  85. <PRE>
  86.      $cw->ConfigSpecs(
  87.                 '-cursor'    => [SELF,'cursor','Cursor',undef],
  88.                 '-something' => [METHOD,dbName,dbClass,'default'],
  89.                 '-text'      => [$label,dbName,dbClass,'default'],
  90.                 '-heading'   => [{-text=>$head},
  91.                                  heading,Heading,'My Heading'],
  92.                 );
  93.    }</PRE>
  94. <PRE>
  95.    sub something
  96.    {
  97.     my ($cw,$value) = @_;
  98.     if (@_ > 1)
  99.      {
  100.       # set it
  101.      }
  102.     return # current value
  103.    }</PRE>
  104. <PRE>
  105.    1;</PRE>
  106. <PRE>
  107.    __END__</PRE>
  108. <PRE>
  109.    # Anything not documented is *private* - your POD is god, so to speak.</PRE>
  110. <PRE>
  111.    =head1 NAME</PRE>
  112. <PRE>
  113.    Tk::Whatever - a whatever widget</PRE>
  114. <PRE>
  115.    =head1 SYNOPSIS</PRE>
  116. <PRE>
  117.      use Tk::Whatever;</PRE>
  118. <PRE>
  119.      $widget = $parent->Whatever(...);</PRE>
  120. <PRE>
  121.    =head1 DESCRIPTION</PRE>
  122. <PRE>
  123.    You forgot to document your widget, didn't you? :-)</PRE>
  124. <PRE>
  125.    ...</PRE>
  126. <P>
  127. <HR>
  128. <H1><A NAME="description">DESCRIPTION</A></H1>
  129. <P>The intention behind a composite is to create a higher-level widget,
  130. sometimes called a ``super-widget'' or ``meta-widget''.  Most often,
  131. a composite will be
  132. built upon other widgets by <STRONG>using</STRONG> them, as opposed to specializing on them.
  133. For example, the supplied composite widget <STRONG>LabEntry</STRONG> is <EM>made of</EM> an
  134. <STRONG>Entry</STRONG> and a <STRONG>Label</STRONG>; it is neither a <EM>kind-of</EM> <STRONG>Label</STRONG>
  135. nor is it a <EM>kind-of</EM> <STRONG>Entry</STRONG>.</P>
  136. <P>Most of the work of a composite widget consist in creating subwidgets,
  137. arrange to dispatch configure options to the proper subwidgets and manage
  138. composite-specific configure options.</P>
  139. <P>
  140. <HR>
  141. <H1><A NAME="glory details">GLORY DETAILS</A></H1>
  142. <P>Depending on your perl/Tk knowledget this section may be enlighting
  143. or confusing.</P>
  144. <P>
  145. <H2><A NAME="composite widget">Composite Widget</A></H2>
  146. <P>Since perl/Tk is heavilly using an object-oriented approach, it is no
  147. suprise that creating a composite goes through a <STRONG>new()</STRONG> method.
  148. However, the composite does not normally define a <STRONG>new()</STRONG> method
  149. itself: it is usually sufficient to simply inherit it from
  150. <STRONG>Tk::Widget</STRONG>.</P>
  151. <P>This is what happens when the composite use</P>
  152. <PRE>
  153.     @ISA = qw(Tk::Frame);  # or Tk::Toplevel</PRE>
  154. <P>to specify its inheritance chain.  To complete the initialisation of the
  155. widget, it must call the <STRONG>Construct</STRONG> method from class <STRONG>Widget</STRONG>.  That
  156. method accepts the name of the new class to create, i.e. the package name
  157. of your composite widget:</P>
  158. <PRE>
  159.     Construct Tk::Widget 'Whatever';</PRE>
  160. <P>Here, <STRONG>Whatever</STRONG> is the package name (aka the widget's <STRONG>class</STRONG>).  This
  161. will define a constructor method for <STRONG>Whatever</STRONG>, normally named after the
  162. widget's class.  Instanciating that composite in client code would
  163. the look like:</P>
  164. <PRE>
  165.     $mw = MainWindow->new();   # Creates a top-level main window</PRE>
  166. <PRE>
  167.     $cw = $mw->Whatever();     # Creates an instance of the
  168.                                # composite widget Whatever</PRE>
  169. <P>Whenever a composite is instanciated in client code,
  170. <CODE>Tk::Widget::new()</CODE> will be invoked via the widget's class
  171. constructor.  That <STRONG>new</STRONG> method will call</P>
  172. <PRE>
  173.     $cw->InitObject(\%args);</PRE>
  174. <P>where <EM>%args</EM> is the arguments passed to the widget's constructor.  Note
  175. that <STRONG>InitObject</STRONG> receives a <STRONG>reference</STRONG> to the hash array
  176. containing all arguments.</P>
  177. <P>For composite widgets that needs an underlying frame, <STRONG>InitObject</STRONG>
  178. will typically be inherited from <STRONG>Tk::Frame</STRONG>, that is, no method of
  179. this name will appear in the composite package.  For composites that
  180. don't need a frame, <STRONG>InitObject</STRONG> will typically be defined in the
  181. composite class (package).  Compare the <STRONG>LabEntry</STRONG> composite with
  182. <STRONG>Optionmenu</STRONG>: the former is <STRONG>Frame</STRONG> based while the latter is <STRONG>Widget</STRONG>
  183. based.</P>
  184. <P>In <STRONG>Frame</STRONG> based composites, <STRONG>Tk::Frame::InitObject()</STRONG> will call
  185. <STRONG>Populate()</STRONG>, which should be defined to create the characteristic
  186. subwidgets of the class.</P>
  187. <P><STRONG>Widget</STRONG> based composites don't need an extra <STRONG>Populate</STRONG> layer; they
  188. typically have their own <STRONG>InitObject</STRONG> method that will create subwidgets.</P>
  189. <P>
  190. <H2><A NAME="creating subwidgets">Creating Subwidgets</A></H2>
  191. <P>Subwidget creation happens usually in <STRONG>Populate()</STRONG> (<STRONG>Frame</STRONG> based)
  192. or <STRONG>InitObject()</STRONG> (<STRONG>Widget</STRONG> based).  The composite usually calls the
  193. subwidget's constructor method either directly, for ``private'' subwidgets,
  194. or indirectly through the <STRONG>Component</STRONG> method for subwidgets that should
  195. be advertised to clients.</P>
  196. <P><STRONG>Populate</STRONG> may call <STRONG>Delegates</STRONG> to direct calls to methods
  197. of chosen subwidgets. For simple composites, typically most if not all
  198. methods are directed
  199. to a single subwidget - e.g. <STRONG>ScrListbox</STRONG> directs all methods to the core
  200. <STRONG>Listbox</STRONG> so that <EM>$composite</EM>-><STRONG>get</STRONG>(...) calls
  201. <EM>$listbox</EM>-><STRONG>get</STRONG>(...).</P>
  202. <P>
  203. <H2><A NAME="further steps for frame based composites">Further steps for Frame based composites</A></H2>
  204. <P><STRONG>Populate</STRONG> should also call <STRONG>ConfigSpecs()</STRONG> to specify the
  205. way that configure-like options should be handled in the composite.
  206. Once <STRONG>Populate</STRONG> returns, method <STRONG>Tk::Frame::ConfigDefault</STRONG>
  207. walks through the <STRONG>ConfigSpecs</STRONG> entries and populates
  208. %$args hash with defaults for options from X resources (<EM>.Xdefaults</EM>, etc).</P>
  209. <P>When  <STRONG>InitObject()</STRONG> returns to <STRONG>Tk::Widget::new()</STRONG>,
  210. a call to <STRONG>$cw</STRONG>-><EM>configure</EM>(%$args) is made which sets *all*
  211. the options.</P>
  212. <P>
  213. <HR>
  214. <H1><A NAME="see also">SEE ALSO</A></H1>
  215. <P><A HREF="../../../Tk/ConfigSpecs.html">Tk::ConfigSpecs</A>
  216. <A HREF="../../../site/lib/Tk/Derived.html">Tk::Derived</A></P>
  217. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  218. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  219. <STRONG><P CLASS=block> Tk::composite - Defining a new composite widget class</P></STRONG>
  220. </TD></TR>
  221. </TABLE>
  222.  
  223. </BODY>
  224.  
  225. </HTML>
  226.