Tk::composite(3pm)

1composite(3)          User Contributed Perl Documentation         composite(3)
2
3
4

NAME

6       Tk::composite - Defining a new composite widget class
7

SYNOPSIS

9           package Tk::MyNewWidget;
10
11           use Tk:widgets qw/ list of Tk widgets /;
12           use base qw/ Tk::Frame /;    # or Tk::Toplevel
13
14           Construct Tk::Widget 'MyNewWidget';
15
16           sub ClassInit {
17               my( $class, $mw ) = @_;
18               #... e.g., class bindings here ...
19               $class->SUPER::ClassInit( $mw );
20           }
21
22           sub Populate {
23               my( $self, $args ) = @_;
24
25               my $flag = delete $args->{-flag};
26               if( defined $flag ) {
27                   # handle -flag => xxx which can only be done at create
28                   # time the delete above ensures that new() does not try
29                   # and do  $self->configure( -flag => xxx );
30               }
31
32               $self->SUPER::Populate( $args );
33
34               $self = $self->Component( ... );
35
36               $self->Delegates( ... );
37
38               $self->ConfigSpecs(
39                   '-cursor'    => [ SELF, 'cursor', 'Cursor',   undef ],
40                   '-something' => [ METHOD, dbName,  dbClass, default ],
41                   '-text'      => [ $label, dbName,  dbClass, default ],
42                   '-heading'   => [ {-text => $head},
43                                       heading, Heading,  'My Heading' ],
44              );
45          }
46
47          sub something {
48              my( $self, $value) = @_;
49              if ( @_ > 1 ) {
50                 # set it
51              }
52              return # current value
53          }
54
55          1;
56
57          __END__
58
59
60          =head1 NAME
61
62          Tk::Whatever - a whatever widget
63
64          =head1 SYNOPSIS
65
66            use Tk::Whatever;
67
68            $widget = $parent->Whatever(...);
69
70          =head1 DESCRIPTION
71
72          ...
73

DESCRIPTION

75       The intention behind a composite is to create a higher-level widget,
76       sometimes called a "super-widget" or "mega-widget".  Most often, a
77       composite will be built upon other widgets by using them, as opposed to
78       specializing on them.  For example, the supplied composite widget
79       LabEntry is made of an Entry and a Label; it is neither a kind-of Label
80       nor is it a kind-of Entry.
81
82       Most of the work of a composite widget consistd in creating subwidgets,
83       arranging to dispatch configure options to the proper subwidgets and
84       manage composite-specific configure options.
85

GLORY DETAILS

87       Depending on your Perl/Tk knowledge this section may be enlighting or
88       confusing.
89
90   Composite Widget
91       Since Perl/Tk is heavilly using an object-oriented approach, it is no
92       suprise that creating a composite goes through a new() method.
93       However, the composite does not normally define a new() method itself:
94       it is usually sufficient to simply inherit it from Tk::Widget.
95
96       This is what happens when the composite uses
97
98           use base qw/ Tk::Frame /;  # or Tk::Toplevel
99
100       to specify its inheritance chain.  To complete the initialisation of
101       the widget, it must call the Construct method from class Widget.  That
102       method accepts the name of the new class to create, i.e. the package
103       name of your composite widget:
104
105           Construct Tk::Widget 'MyNewWidget';
106
107       Here, MyNewWidget is the package name (aka the widget's class).  This
108       will define a constructor method for MyNewWidget, normally named after
109       the widget's class.  Instanciating that composite in client code would
110       the look like:
111
112           $mw = MainWindow->new;       # creates a top-level MainWindow
113
114           $self = $mw->MyNewWidget();  # creates an instance of the
115                                        # composite widget MyNewWidget
116
117       Whenever a composite is instanciated in client code,
118       "Tk::Widget::new()" will be invoked via the widget's class constructor.
119       That new method will call
120
121           $self->Populate(\%args);
122
123       where %args is the arguments passed to the widget's constructor.  Note
124       that Populate receives a reference to the hash array containing all
125       arguments.
126
127       Populate is typically defined in the composite class (package), which
128       creates the characteristic subwidgets of the class.
129
130   Creating Subwidgets
131       Subwidget creation happens usually in Populate().  The composite
132       usually calls the subwidget's constructor method either directly, for
133       "private" subwidgets, or indirectly through the Component method for
134       subwidgets that should be advertised to clients.
135
136       Populate may call Delegates to direct calls to methods of chosen
137       subwidgets. For simple composites, typically most if not all methods
138       are directed to a single subwidget - e.g. ScrListbox directs all
139       methods to the core Listbox so that $composite->get(...) calls
140       $listbox->get(...).
141
142   Defining mega-widget options
143       Populate should also call ConfigSpecs() to specify the way that
144       configure-like options should be handled in the composite.  Once
145       Populate returns, method Tk::Frame::ConfigDefault walks through the
146       ConfigSpecs entries and populates %$args hash with defaults for options
147       from X resources (.Xdefaults, etc).
148
149       When  Populate returns to Tk::Widget::new(), a call to
150       $self->configure(%$args) is made which sets *all* the options.
151

NAME

SYNOPSIS

DESCRIPTION

GLORY DETAILS

SEE ALSO