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          =head1 NAME
60
61          Tk::Whatever - a whatever widget
62
63          =head1 SYNOPSIS
64
65            use Tk::Whatever;
66
67            $widget = $parent->Whatever(...);
68
69          =head1 DESCRIPTION
70
71          ...
72

DESCRIPTION

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

GLORY DETAILS

86       Depending on your Perl/Tk knowledge this section may be enlighting or
87       confusing.
88
89       Composite Widget
90
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.  How‐
93       ever, the composite does not normally define a new() method itself: it
94       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, "Tk::Wid‐
118       get::new()" will be invoked via the widget's class constructor.  That
119       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
132       Subwidget creation happens usually in Populate().  The composite usu‐
133       ally calls the subwidget's constructor method either directly, for
134       "private" subwidgets, or indirectly through the Component method for
135       subwidgets that should be advertised to clients.
136
137       Populate may call Delegates to direct calls to methods of chosen sub‐
138       widgets. For simple composites, typically most if not all methods are
139       directed to a single subwidget - e.g. ScrListbox directs all methods to
140       the core Listbox so that $composite->get(...) calls $listbox->get(...).
141
142       Defining mega-widget options
143
144       Populate should also call ConfigSpecs() to specify the way that config‐
145       ure-like options should be handled in the composite.  Once Populate
146       returns, method Tk::Frame::ConfigDefault walks through the ConfigSpecs
147       entries and populates %$args hash with defaults for options from X
148       resources (.Xdefaults, etc).
149
150       When  Populate returns to Tk::Widget::new(), a call to $self->config‐
151       ure(%$args) is made which sets *all* the options.
152

NAME

SYNOPSIS

DESCRIPTION

GLORY DETAILS

SEE ALSO