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

NAME

6       Tk::Internals -  what is Perl Tk interface doing when you call Tk
7       functions.
8
9       This information is worse than useless for "perlTk" users, but can of
10       some help for people interested in using modified Tk source with
11       "perlTk".
12
13       This document is under construction. The information is believed to be
14       pertinent to the version of "portableTk" available when it was created.
15       All the details are subject to change.
16

DESCRIPTION

18       PreCompiling
19           Before the actual compilation stage a script scans the source and
20           extracts the subcommands of different commands. This information
21           resides in the file "pTk/Methods.def".
22
23       Compilation
24           During compilation the above file is included in the source of
25           booting routine of dynamic (or static) library. More precisely, the
26           booting code of module "Tk" calls the subroutine Boot_Glue() from
27           the module "tkGlue.c", and this subroutine includes the file (with
28           appropriate macro definitions).
29
30       Inside "use Tk;"
31           The module bootstraps the C code, then loads the Perl libraries.
32           The heart of the Perl code is contained in the "Tk::Widget"
33           library, all the widgets inherit from this module. Code for
34           toplevels is loaded from "Tk::MainWindow".
35
36           During bootstrap of the C glue code the "Xevent::?" codes and a
37           handful of "Tk::Widget" and "Tk::Image" routines are defined. (Much
38           more XSUBs are created from "Tk.xs" code.) The widget subcommands
39           are glued to Perl basing on the list included from
40           "pTk/Methods.def". In fact all the subcommands are glued to XSUBs
41           that are related to the same C subroutine XStoWidget(), but have
42           different data parts.
43
44           During the Perl code bootstrap the method "Tk::Widget::import" is
45           called. This call requires all the code from particular widget
46           packages.
47
48           Code from the widget packages calls an obscure command like
49
50             (bless \"Text")->WidgetClass;
51
52           This command (actually Tk::Widget::WidgetClass()) creates three
53           routines: Tk::Widget::Text(), Tk::Widget::isText(), and
54           Tk::Text::isText(). The first one is basically "new" of "Tk::Text",
55           the other two return constants. It also puts the class into
56           depository.
57
58       Inside "$top = MainWindow->new;"
59           This is quite intuitive. This call goes direct to
60           "Tk::MainWindow::new", that calls XSUB
61           "Tk::MainWindow::CreateMainWindow", that calls C subroutine
62           Tk_CreateMainWindow(). It is a "Tk" subroutine, so here black magic
63           ends (almost).
64
65           The only remaining black magic is that the "Tk" initialization
66           routine creates a lot of commands, but the subroutine for creation
67           is usurped by portableTk and the commands are created in the
68           package "Tk". They are associated to XSUBs that are related to one
69           of three C subroutines XStoSubCmd(), XStoBind(), or XStoTk(), but
70           have different data parts.
71
72           The result of the call is blessed into "Tk::MainWindow", as it
73           should.
74
75       Inside "$top->title('Text demo');"
76           The package "Tk::Toplevel" defines a lot of subroutines on the fly
77           on some list. All the commands from the list are converted to the
78           corresponding subcommands of "wm" method of the widget. Here
79           subcommand is a command with some particular second argument (in
80           this case "title"). Recall that the first argument is $self.
81
82           Now "Tk::Toplevel" @ISA "Tk::Widget", that in turn @ISA "Tk". So a
83           call to "$top->wm('title','Text demo')" calls "Tk::wm", that is
84           defined during call to Tk_CreateMainWindow(). As it is described
85           above, the XSUB associated to XStoSubCmd() is called.
86
87           This C routine is defined in "tkGlue.c". It gets the data part of
88           XSUB, creates a "SV" with the name of the command, and calls
89           Call_Tk() with the XSUB data as the first argument, and with the
90           name of XSUB stuffed into the Perl stack in the place there "tk"
91           expects it. (In fact it can also reorder the arguments if it thinks
92           it is what you want).
93
94           The latter procedure extracts name of "tk" procedure and
95           "clientData" from the first argument and makes a call, using Perl
96           stack as "argv" for the procedure. A lot of black magic is
97           performed afterwards to convert result of the procedure to a Perl
98           array return.
99
100       Inside "$text = $top->Text(background => $txtBg);"
101           Above we discussed how the command "Tk::Widget::Text" is created.
102           The above command calls it via inheritance. It is translated to
103
104             Tk::Text::new($top, background => $txtBg);
105
106           The package "Tk::Text" has no method "new", so the
107           "Tk::Widget::new" is called. In turn it calls
108           "Tk::Text->DoInit($top)", that is
109           "Tk::Widget::DoInit(Tk::Text,$top)", that initializes the bindings
110           if necessary. Then it creates the name for the widget of the form
111           ".text0", and calls "Tk::text('.text0', background => $txtBg)"
112           (note lowercase). The result of the call is blessed into
113           "Tk::Text", and the method "bindtags" for this object is called.
114
115           Now the only thing to discuss is who defines the methods "text" and
116           "bindtags". The answer is that they are defined in "tkWindow.c",
117           and these commands are created in the package "Tk" in the same
118           sweep that created the command "Tk::wm" discussed above.
119
120           So the the same C code that corresponds to the processing of
121           corresponding TCL commands is called here as well (this time via
122           "XStoTk" interface).
123
124       Inside "$text->insert('insert','Hello, world!');"
125           As we discussed above, the subcommands of widget procedures
126           correspond to XSUB "XStoWidget". This XSUB substitutes the first
127           argument $text (that is a hash reference) to an appropriate value
128           from this hash, adds the additional argument after the first one
129           that contains the name of the subcommand extracted from the data
130           part of XSUB, and calls the corresponding Tk C subroutine via
131           "Call_Tk".
132
133       Ilya Zakharevich <ilya@math.ohio-state.edu>
134
135
136
137perl v5.38.0                      2023-07-21                      Internals(3)
Impressum