File: //usr/local/ssl/local/share/man/man3/Tk::composite.3
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.\"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "composite 3"
.TH composite 3 "2007-02-10" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Tk::composite \- Defining a new composite widget class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& package Tk::MyNewWidget;
.Ve
.PP
.Vb 2
\& use Tk:widgets qw/ list of Tk widgets /;
\& use base qw/ Tk::Frame /; # or Tk::Toplevel
.Ve
.PP
.Vb 1
\& Construct Tk::Widget 'MyNewWidget';
.Ve
.PP
.Vb 5
\& sub ClassInit {
\& my( $class, $mw ) = @_;
\& #... e.g., class bindings here ...
\& $class->SUPER::ClassInit( $mw );
\& }
.Ve
.PP
.Vb 2
\& sub Populate {
\& my( $self, $args ) = @_;
.Ve
.PP
.Vb 6
\& my $flag = delete $args->{-flag};
\& if( defined $flag ) {
\& # handle -flag => xxx which can only be done at create
\& # time the delete above ensures that new() does not try
\& # and do $self->configure( -flag => xxx );
\& }
.Ve
.PP
.Vb 1
\& $self->SUPER::Populate( $args );
.Ve
.PP
.Vb 1
\& $self = $self->Component( ... );
.Ve
.PP
.Vb 1
\& $self->Delegates( ... );
.Ve
.PP
.Vb 8
\& $self->ConfigSpecs(
\& '-cursor' => [ SELF, 'cursor', 'Cursor', undef ],
\& '-something' => [ METHOD, dbName, dbClass, default ],
\& '-text' => [ $label, dbName, dbClass, default ],
\& '-heading' => [ {-text => $head},
\& heading, Heading, 'My Heading' ],
\& );
\& }
.Ve
.PP
.Vb 7
\& sub something {
\& my( $self, $value) = @_;
\& if ( @_ > 1 ) {
\& # set it
\& }
\& return # current value
\& }
.Ve
.PP
.Vb 1
\& 1;
.Ve
.PP
.Vb 1
\& __END__
.Ve
.PP
.Vb 1
\& =head1 NAME
.Ve
.PP
.Vb 1
\& Tk::Whatever - a whatever widget
.Ve
.PP
.Vb 1
\& =head1 SYNOPSIS
.Ve
.PP
.Vb 1
\& use Tk::Whatever;
.Ve
.PP
.Vb 1
\& $widget = $parent->Whatever(...);
.Ve
.PP
.Vb 1
\& =head1 DESCRIPTION
.Ve
.PP
.Vb 1
\& ...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The intention behind a composite is to create a higher-level widget,
sometimes called a \*(L"super\-widget\*(R" or \*(L"mega\-widget\*(R". Most often,
a composite will be
built upon other widgets by \fBusing\fR them, as opposed to specializing on them.
For example, the supplied composite widget \fBLabEntry\fR is \fImade of\fR an
\&\fBEntry\fR and a \fBLabel\fR; it is neither a \fIkind-of\fR \fBLabel\fR
nor is it a \fIkind-of\fR \fBEntry\fR.
.PP
Most of the work of a composite widget consistd in creating subwidgets,
arranging to dispatch configure options to the proper subwidgets and manage
composite-specific configure options.
.SH "GLORY DETAILS"
.IX Header "GLORY DETAILS"
Depending on your Perl/Tk knowledge this section may be enlighting
or confusing.
.Sh "Composite Widget"
.IX Subsection "Composite Widget"
Since Perl/Tk is heavilly using an object-oriented approach, it is no
suprise that creating a composite goes through a \fB\f(BInew()\fB\fR method.
However, the composite does not normally define a \fB\f(BInew()\fB\fR method
itself: it is usually sufficient to simply inherit it from
\&\fBTk::Widget\fR.
.PP
This is what happens when the composite uses
.PP
.Vb 1
\& use base qw/ Tk::Frame /; # or Tk::Toplevel
.Ve
.PP
to specify its inheritance chain. To complete the initialisation of the
widget, it must call the \fBConstruct\fR method from class \fBWidget\fR. That
method accepts the name of the new class to create, i.e. the package name
of your composite widget:
.PP
.Vb 1
\& Construct Tk::Widget 'MyNewWidget';
.Ve
.PP
Here, \fBMyNewWidget\fR is the package name (aka the widget's \fBclass\fR). This
will define a constructor method for \fBMyNewWidget\fR, normally named after the
widget's class. Instanciating that composite in client code would
the look like:
.PP
.Vb 1
\& $mw = MainWindow->new; # creates a top-level MainWindow
.Ve
.PP
.Vb 2
\& $self = $mw->MyNewWidget(); # creates an instance of the
\& # composite widget MyNewWidget
.Ve
.PP
Whenever a composite is instanciated in client code,
\&\f(CW\*(C`Tk::Widget::new()\*(C'\fR will be invoked via the widget's class
constructor. That \fBnew\fR method will call
.PP
.Vb 1
\& $self->Populate(\e%args);
.Ve
.PP
where \fI%args\fR is the arguments passed to the widget's constructor. Note
that \fBPopulate\fR receives a \fBreference\fR to the hash array
containing all arguments.
.PP
\&\fBPopulate\fR is typically defined in the composite class (package),
which creates the characteristic subwidgets of the class.
.Sh "Creating Subwidgets"
.IX Subsection "Creating Subwidgets"
Subwidget creation happens usually in \fB\f(BIPopulate()\fB\fR.
The composite usually calls the
subwidget's constructor method either directly, for \*(L"private\*(R" subwidgets,
or indirectly through the \fBComponent\fR method for subwidgets that should
be advertised to clients.
.PP
\&\fBPopulate\fR may call \fBDelegates\fR to direct calls to methods
of chosen subwidgets. For simple composites, typically most if not all
methods are directed
to a single subwidget \- e.g. \fBScrListbox\fR directs all methods to the core
\&\fBListbox\fR so that \fI$composite\fR\->\fBget\fR(...) calls
\&\fI$listbox\fR\->\fBget\fR(...).
.Sh "Defining mega-widget options"
.IX Subsection "Defining mega-widget options"
\&\fBPopulate\fR should also call \fB\f(BIConfigSpecs()\fB\fR to specify the
way that configure-like options should be handled in the composite.
Once \fBPopulate\fR returns, method \fBTk::Frame::ConfigDefault\fR
walks through the \fBConfigSpecs\fR entries and populates
%$args hash with defaults for options from X resources (\fI.Xdefaults\fR, etc).
.PP
When \fBPopulate\fR returns to \fB\f(BITk::Widget::new()\fB\fR,
a call to \fB$self\fR\->\fIconfigure\fR(%$args) is made which sets *all*
the options.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Tk::ConfigSpecs
Tk::mega
Tk::Derived