Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Tk::overview.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" 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 "OVERVIEW 1"
.TH OVERVIEW 1 "2000-12-30" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
\&\fBTk\fR \- An overview of an Object Oriented Tk8.0 extension for perl5
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use Tk;
.PP
$main = MainWindow\->\fInew()\fR;
.PP
$widget = \f(CW$main\fR\->\fIWidget\fR(...);
.PP
$widget\->pack(...);
.PP
\&...
.PP
MainLoop;
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
In writing the perl Tk extension, the goals were to provide a complete
interface to the latest production version of John Ousterhout's Tk, while providing
an Object Oriented interface to perl code.
.SH "CONTENTS"
.IX Header "CONTENTS"
The package is composed of three loosely connected parts:
.IP "\fIpTk\fR \- Converted Tk source" 4
.IX Item "pTk - Converted Tk source"
The \fIpTk\fR sub-directory is a copy of the C code of Tk4.0, modified
to allow use by languages other than the original Tcl.
(The pTk can be read as 'perl' Tk or 'portable' Tk, depending on
your sensibilities.)
.IP "\fBTk\fR to Perl 'Glue'" 4
.IX Item "Tk to Perl 'Glue'"
The top level directory provides \fITk.xs\fR and \fItkGlue.c\fR
which provide the perl-callable interfaces to pTk
.IP "Perl code for 'Widget' Classes" 4
.IX Item "Perl code for 'Widget' Classes"
The \fITk/Tk\fR sub-directory contains the various perl modules that comprise
the \*(L"Classes\*(R" that are visible to Tk applications.
.Sp
The \*(L"major\*(R" widgets such as \fBTk::Text\fR are actually in separate directories
at the top level (e.g. \fIText/*\fR for \fBTk::Text\fR) and are dynamically
loaded as needed on platforms which support perl5's \fBDynaLoader\fR.
.SH "CLASS HIERARCHY"
.IX Header "CLASS HIERARCHY"
.IP "\fBpackage Tk;\fR \- the 'base class'" 4
.IX Item "package Tk; - the 'base class'"
All the \*(L"command names\*(R" documented in Tcl/Tk are made to look like perl
sub's and reside in the Tk package. Their names are all lower case.
Typically there are very few commands at this level which are called
directly by applications.
.IP "\fBpackage Tk::Widget;\fR \- the 'Widget class'" 4
.IX Item "package Tk::Widget; - the 'Widget class'"
There are no actual objects of the \fBTk::Widget\fR class; however all
the various Tk window \*(L"widgets\*(R" inherit from it, and it in turn
inherits all the core Tk functions from Tk.
.Sp
\&\fBTk::Widget\fR provides various functions and interfaces which are
common to all Widgets.
.Sp
A widget is represented to perl as a blessed reference to a hash. There are some
members of the hash which are private to Tk and its tkGlue code.  Keys
starting with \fB'.'\fR and of the form  \fB/_[A\-Z][A\-Za\-z_]+_/\fR
(i.e. starting and ending in _ and with  first char after _ being upper case) should be
considered reserved to \fBTk\fR.
.IP "\fBTk::Button\fR, \fBTk::Entry\fR, \fBTk::Text\fR ..." 4
.IX Item "Tk::Button, Tk::Entry, Tk::Text ..."
There is one class for each of the \*(L"Tk\*(R" widget item types.
Some of them like \fBTk::Frame\fR do very little indeed, and really
only exist so that they can be derived from or so that focus or menu
traversal can discover the \*(L"kind\*(R" of window being processed.
.Sp
Other classes, \fBTk::Text\fR for example, provide a lot of methods
used with Tk's \*(L"bind\*(R" to provide a rich keyboard/mouse interface
to the widgets' data.
.Sp
These widget classes also include conversions of the Tcl code for
event bindings, keyboard focus traversal, menu bars, and menu keyboard
traversal. All the Tcl functions have been converted, but the names have
changed (systematically) and they have been split up between the various
classes in what I hope is an appropriate manner.
Name changes are normally: dropping initial tk_ as the Tk-ness is implicit
in the \fBTk::\fR prefix, and similarly dropping say Menu from the name if it
has been moved the Tk::Menu class.
Thus 'proc tkMenuNextEntry' becomes 'sub NextEntry' in the Tk::Menu package.
.IP "\fBTk::Image\fR" 4
.IX Item "Tk::Image"
This does for Tk4.0's \*(L"images\*(R" what \fBTk::Widget\fR does for widgets.
Images are new to Tk4.0 and the class structure is not mature either.
.Sp
There are three sub-classes \fBTk::Bitmap\fR, \fBTk::Pixmap\fR and \fBTk::Photo\fR.
.Sp
It is expected that \fBTk::Image\fR hierarchy will evolve during the \*(L"beta\*(R"
phase of Tk to allow dynamic or auto-loaded image types or photo formats
(e.g. support for \s-1JPEG\s0 format for photos).
.IP "Composite Widgets" 4
.IX Item "Composite Widgets"
A composite is some kind of 'frame' with subwidgets which give it useful behaviour.
\&\fBTk::Dialog\fR is an example of
a composite widget classes built from the basic \fBTk\fR ones.
It is intended that user code should not need to be aware that a particular
class is a composite, and create and configure such widgets in the same manner
as any other kind. The \fBconfigure\fR mechanism and the methods of the
class manipulate the subwidgets as required.
.Sp
Composite widgets are implemented via \fBTk::Frame\fR and multiple inheritance.
The two 'frame' base classes \fBTk::Frame\fR and
\&\fBTk::Toplevel\fR include the additional class \fBTk::Derived\fR
in their inheritance. \fBTk::Derived\fR provides methods to allow additional
\&\fBconfigure\fR options to be defined for a widget.
.Sp
A Composite widget is typically defined as derived
from \fBTk::Frame\fR or \fBTk::Toplevel\fR
(e.g. \fBTk::Dialog\fR).