home *** CD-ROM | disk | FTP | other *** search
/ Netrunner 2004 October / NETRUNNER0410.ISO / regular / ActivePerl-5.8.4.810-MSWin32-x86.msi / _cc47b0f462b72a69affa10b4111c9c16 < prev    next >
Text File  |  2004-06-01  |  5KB  |  172 lines
  1. # $Id: composite.pod 1.2 Wed, 12 Nov 1997 00:30:45 +0100 ach $
  2.  
  3. =head1 NAME
  4.  
  5. Tk::composite - Defining a new composite widget class
  6.  
  7. =for category Derived Widgets
  8.  
  9. =head1 SYNOPSIS
  10.  
  11.     package Tk::MyNewWidget;
  12.  
  13.     use Tk:widgets qw/ list of Tk widgets /;
  14.     use base qw/ Tk::Frame /;    # or Tk::Toplevel
  15.  
  16.     Construct Tk::Widget 'MyNewWidget';
  17.  
  18.     sub ClassInit {
  19.         my( $class, $mw ) = @_;
  20.         #... e.g., class bindings here ...
  21.         $class->SUPER::ClassInit( $mw );
  22.     }
  23.  
  24.     sub Populate {
  25.         my( $self, $args ) = @_;
  26.  
  27.         my $flag = delete $args->{-flag};
  28.         if( defined $flag ) {
  29.             # handle -flag => xxx which can only be done at create
  30.             # time the delete above ensures that new() does not try
  31.             # and do  $self->configure( -flag => xxx );
  32.         }
  33.  
  34.         $self->SUPER::Populate( $args );
  35.  
  36.         $self = $self->Component( ... );
  37.  
  38.         $self->Delegates( ... );
  39.  
  40.         $self->ConfigSpecs(
  41.             '-cursor'    => [ SELF, 'cursor', 'Cursor',   undef ],
  42.             '-something' => [ METHOD, dbName,  dbClass, default ],
  43.             '-text'      => [ $label, dbName,  dbClass, default ],
  44.             '-heading'   => [ {-text => $head},
  45.                                 heading, Heading,  'My Heading' ],
  46.        ); 
  47.    }
  48.  
  49.    sub something {
  50.        my( $self, $value) = @_;
  51.        if ( @_ > 1 ) {
  52.           # set it
  53.        }
  54.        return # current value
  55.    }
  56.  
  57.    1;
  58.  
  59.    __END__
  60.  
  61.  
  62.    =head1 NAME
  63.  
  64.    Tk::Whatever - a whatever widget
  65.  
  66.    =head1 SYNOPSIS
  67.  
  68.      use Tk::Whatever;
  69.  
  70.      $widget = $parent->Whatever(...);
  71.  
  72.    =head1 DESCRIPTION
  73.  
  74.    ...
  75.  
  76. =head1 DESCRIPTION
  77.  
  78. The intention behind a composite is to create a higher-level widget,
  79. sometimes called a "super-widget" or "mega-widget".  Most often,
  80. a composite will be
  81. built upon other widgets by B<using> them, as opposed to specializing on them.
  82. For example, the supplied composite widget B<LabEntry> is I<made of> an
  83. B<Entry> and a B<Label>; it is neither a I<kind-of> B<Label>
  84. nor is it a I<kind-of> B<Entry>.
  85.  
  86. Most of the work of a composite widget consistd in creating subwidgets,
  87. arranging to dispatch configure options to the proper subwidgets and manage
  88. composite-specific configure options.
  89.  
  90. =head1 GLORY DETAILS
  91.  
  92. Depending on your Perl/Tk knowledge this section may be enlighting
  93. or confusing.
  94.  
  95. =head2 Composite Widget
  96.  
  97. Since Perl/Tk is heavilly using an object-oriented approach, it is no
  98. suprise that creating a composite goes through a B<new()> method.
  99. However, the composite does not normally define a B<new()> method
  100. itself: it is usually sufficient to simply inherit it from
  101. B<Tk::Widget>.
  102.  
  103. This is what happens when the composite uses
  104.  
  105.     use base qw/ Tk::Frame /;  # or Tk::Toplevel
  106.  
  107. to specify its inheritance chain.  To complete the initialisation of the
  108. widget, it must call the B<Construct> method from class B<Widget>.  That
  109. method accepts the name of the new class to create, i.e. the package name
  110. of your composite widget:
  111.  
  112.     Construct Tk::Widget 'MyNewWidget';
  113.  
  114. Here, B<MyNewWidget> is the package name (aka the widget's B<class>).  This
  115. will define a constructor method for B<MyNewWidget>, normally named after the
  116. widget's class.  Instanciating that composite in client code would
  117. the look like:
  118.  
  119.     $mw = MainWindow->new;       # creates a top-level MainWindow
  120.  
  121.     $self = $mw->MyNewWidget();  # creates an instance of the
  122.                                  # composite widget MyNewWidget
  123.  
  124. Whenever a composite is instanciated in client code,
  125. C<Tk::Widget::new()> will be invoked via the widget's class
  126. constructor.  That B<new> method will call
  127.  
  128.     $self->Populate(\%args);
  129.  
  130. where I<%args> is the arguments passed to the widget's constructor.  Note
  131. that B<Populate> receives a B<reference> to the hash array
  132. containing all arguments.
  133.  
  134. B<Populate> is typically defined in the composite class (package),
  135. which creates the characteristic subwidgets of the class.
  136.  
  137. =head2 Creating Subwidgets
  138.  
  139. Subwidget creation happens usually in B<Populate()>.
  140. The composite usually calls the
  141. subwidget's constructor method either directly, for "private" subwidgets,
  142. or indirectly through the B<Component> method for subwidgets that should
  143. be advertised to clients.
  144.  
  145. B<Populate> may call B<Delegates> to direct calls to methods
  146. of chosen subwidgets. For simple composites, typically most if not all
  147. methods are directed
  148. to a single subwidget - e.g. B<ScrListbox> directs all methods to the core
  149. B<Listbox> so that I<$composite>-E<gt>B<get>(...) calls
  150. I<$listbox>-E<gt>B<get>(...).
  151.  
  152. =head2 Defining mega-widget options
  153.  
  154. B<Populate> should also call B<ConfigSpecs()> to specify the
  155. way that configure-like options should be handled in the composite.
  156. Once B<Populate> returns, method B<Tk::Frame::ConfigDefault>
  157. walks through the B<ConfigSpecs> entries and populates
  158. %$args hash with defaults for options from X resources (F<.Xdefaults>, etc).
  159.  
  160. When  B<Populate> returns to B<Tk::Widget::new()>,
  161. a call to B<$self>-E<gt>I<configure>(%$args) is made which sets *all*
  162. the options.
  163.  
  164. =head1 SEE ALSO
  165.  
  166. L<Tk::ConfigSpecs|Tk::ConfigSpecs>
  167. L<Tk::mega|Tk::mega>
  168. L<Tk::Derived|Tk::Derived>
  169.  
  170. =cut
  171.  
  172.