Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Tk::Internals.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 "INTERNALS 1"
.TH INTERNALS 1 "2000-12-30" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
CallingTk \-  what is Perl Tk interface doing when you call Tk functions.
.PP
This information is worse than useless for \f(CW\*(C`perlTk\*(C'\fR users, but can of
some help for people interested in using modified Tk source with
\&\f(CW\*(C`perlTk\*(C'\fR.
.PP
\&\fIThis document is under construction. The information is believed to
be pertinent to the version of\fR \f(CW\*(C`portableTk\*(C'\fR \fIavailable when it was
created. All the details are subject to change.\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.IP "PreCompiling" 4
.IX Item "PreCompiling"
Before the actual compilation stage a script scans the source
and extracts the subcommands of different commands. This information
resides in the file \f(CW\*(C`pTk/Methods.def\*(C'\fR.
.IP "Compilation" 4
.IX Item "Compilation"
During compilation the above file is included in the source of booting
routine of dynamic (or static) library. More precisely, the booting
code of module \f(CW\*(C`Tk\*(C'\fR calls the subroutine \fIBoot_Glue()\fR from the module
\&\f(CW\*(C`tkGlue.c\*(C'\fR, and this subroutine includes the file (with appropriate
macro definitions).
.ie n .IP "Inside ""use Tk;""" 4
.el .IP "Inside \f(CWuse Tk;\fR" 4
.IX Item "Inside use Tk;"
The module bootstraps the C code, then loads the Perl libraries. The
heart of the Perl code is contained in the \f(CW\*(C`Tk::Widget\*(C'\fR library, all the
widgets inherit from this module. Code for toplevels is loaded from
\&\f(CW\*(C`Tk::MainWindow\*(C'\fR.
.Sp
During bootstrap of the C glue code the \f(CW\*(C`Xevent::?\*(C'\fR codes and a
handful of \f(CW\*(C`Tk::Widget\*(C'\fR and \f(CW\*(C`Tk::Image\*(C'\fR routines are defined. (Much
more XSUBs are created from \f(CW\*(C`Tk.xs\*(C'\fR code.) The widget subcommands are
glued to Perl basing on the list included from \f(CW\*(C`pTk/Methods.def\*(C'\fR. In
fact all the subcommands are glued to XSUBs that are related to the
same C subroutine \fIXStoWidget()\fR, but have different data parts.
.Sp
During the Perl code bootstrap the method \f(CW\*(C`Tk::Widget::import\*(C'\fR is
called. This call requires all the code from particular widget
packages.
.Sp
Code from the widget packages calls an obscure command like
.Sp
.Vb 1
\&  (bless \e"Text")->WidgetClass;
.Ve
.Sp
This command (actually \fITk::Widget::WidgetClass()\fR) creates three
routines: \fITk::Widget::Text()\fR, \fITk::Widget::isText()\fR, and
\&\fITk::Text::isText()\fR. The first one is basically \f(CW\*(C`new\*(C'\fR of \f(CW\*(C`Tk::Text\*(C'\fR,
the other two return constants. It also puts the class into
depository.
.ie n .IP "Inside ""$top = MainWindow\->new;""" 4
.el .IP "Inside \f(CW$top = MainWindow\->new;\fR" 4
.IX Item "Inside $top = MainWindow->new;"
This is quite intuitive. This call goes direct to
\&\f(CW\*(C`Tk::MainWindow::new\*(C'\fR, that calls \s-1XSUB\s0
\&\f(CW\*(C`Tk::MainWindow::CreateMainWindow\*(C'\fR, that calls C subroutine
\&\fITk_CreateMainWindow()\fR. It is a \f(CW\*(C`Tk\*(C'\fR subroutine, so here black magic
ends (almost).
.Sp
The only remaining black magic is that the \f(CW\*(C`Tk\*(C'\fR initialization
routine creates a lot of commands, but the subroutine for creation is
usurped by \fBportableTk\fR and the commands are created in the package
\&\f(CW\*(C`Tk\*(C'\fR. They are associated to XSUBs that are related to one of three C
subroutines \fIXStoSubCmd()\fR, \fIXStoBind()\fR, or \fIXStoTk()\fR, but have different
data parts.
.Sp
The result of the call is blessed into \f(CW\*(C`Tk::MainWindow\*(C'\fR, as it should.
.ie n .IP "Inside ""$top\->title('Text demo');""" 4
.el .IP "Inside \f(CW$top\->title('Text demo');\fR" 4
.IX Item "Inside $top->title('Text demo');"
The package \f(CW\*(C`Tk::Toplevel\*(C'\fR defines a lot of subroutines on the fly on
some list. All the commands from the list are converted to the
corresponding subcommands of \f(CW\*(C`wm\*(C'\fR method of the widget. Here
subcommand is a command with some particular second argument (in this
case \f(CW"title"\fR). Recall that the first argument is \f(CW$self\fR.
.Sp
Now \f(CW\*(C`Tk::Toplevel\*(C'\fR \f(CW@ISA\fR \f(CW\*(C`Tk::Widget\*(C'\fR, that in turn \f(CW@ISA\fR \f(CW\*(C`Tk\*(C'\fR. So a
call to \f(CW\*(C`$top\->wm('title','Text demo')\*(C'\fR calls \f(CW\*(C`Tk::wm\*(C'\fR, that is
defined during call to \fITk_CreateMainWindow()\fR. As it is described
above, the \s-1XSUB\s0 associated to \fIXStoSubCmd()\fR is called.
.Sp
This C routine is defined in \f(CW\*(C`tkGlue.c\*(C'\fR. It gets the data part of
\&\s-1XSUB\s0, creates a \f(CW\*(C`SV\*(C'\fR with the name of the command, and calls
\&\fICall_Tk()\fR with the \s-1XSUB\s0 data as the first argument, and with the name
of \s-1XSUB\s0 stuffed into the Perl stack in the place there \f(CW\*(C`tk\*(C'\fR expects
it. (In fact it can also reorder the arguments if it thinks it is
what you want).
.Sp
The latter procedure extracts name of \f(CW\*(C`tk\*(C'\fR procedure and
\&\f(CW\*(C`clientData\*(C'\fR from the first argument and makes a call, using Perl
stack as \f(CW\*(C`argv\*(C'\fR for the procedure. A lot of black magic is performed
afterwards to convert result of the procedure to a Perl array return.
.ie n .IP "Inside ""$text = $top\->Text(background => $txtBg);""" 4
.el .IP "Inside \f(CW$text = $top\->Text(background => $txtBg);\fR" 4
.IX Item "Inside $text = $top->Text(background => $txtBg);"
Above we discussed how the command \f(CW\*(C`Tk::Widget::Text\*(C'\fR is created. The
above command calls it via inheritance. It is translated to
.Sp
.Vb 1
\&  Tk::Text::new($top, background => $txtBg);
.Ve
.Sp
The package \f(CW\*(C`Tk::Text\*(C'\fR has no method \f(CW\*(C`new\*(C'\fR, so the
\&\f(CW\*(C`Tk::Widget::new\*(C'\fR is called. In turn it calls
\&\f(CW\*(C`Tk::Text\->DoInit($top)\*(C'\fR, that is
\&\f(CW\*(C`Tk::Widget::DoInit(Tk::Text,$top)\*(C'\fR, that initializes the bindings if
necessary. Then it creates the name for the widget of the form
\&\f(CW\*(C`.text0\*(C'\fR, and calls \f(CW\*(C`Tk::text('.text0', background => $txtBg)\*(C'\fR
(note lowercase). The result of the call is blessed into \f(CW\*(C`Tk::Text\*(C'\fR,
and the method \f(CW\*(C`bindtags\*(C'\fR for this object is called.
.Sp
Now the only thing to discuss is who defines the methods \f(CW\*(C`text\*(C'\fR and
\&\f(CW\*(C`bindtags\*(C'\fR. The answer is that they are defined in \f(CW\*(C`tkWindow.c\*(C'\fR,
and these commands are created in the package \f(CW\*(C`Tk\*(C'\fR in the same sweep
that created the command \f(CW\*(C`Tk::wm\*(C'\fR discussed above.
.Sp
So the the same C code that corresponds to the processing of
corresponding \s-1TCL\s0 commands is called here as well (this time via
\&\f(CW\*(C`XStoTk\*(C'\fR interface).
.ie n .IP "Inside ""$text\->insert('insert','Hello, world!');""" 4
.el .IP "Inside \f(CW$text\->insert('insert','Hello, world!');\fR" 4
.IX Item "Inside $text->insert('insert','Hello, world!');"
As we discussed above, the subcommands of widget procedures correspond
to \s-1XSUB\s0 \f(CW\*(C`XStoWidget\*(C'\fR. This \s-1XSUB\s0 substitutes the first argument \f(CW$text\fR
(that is a hash reference) to an appropriate value from this hash,
adds the additional argument after the first one that contains the
name of the subcommand extracted from the data part of \s-1XSUB\s0, and calls
the corresponding Tk C subroutine via \f(CW\*(C`Call_Tk\*(C'\fR.
.PP
Ilya Zakharevich <ilya@math.ohio\-state.edu>