1Internals(3) User Contributed Perl Documentation Internals(3)
2
6 CallingTk - what is Perl Tk interface doing when you call Tk func‐
7 tions.
8 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 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
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 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 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 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 "pTk/Meth‐
40 ods.def". In fact all the subcommands are glued to XSUBs that are
41 related to the same C subroutine XStoWidget(), but have different
42 data parts.
43 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 Code from the widget packages calls an obscure command like
49 (bless \"Text")->WidgetClass;
51 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 deposi‐
56 tory.
57 Inside "$top = MainWindow->new;"
59 This is quite intuitive. This call goes direct to "Tk::MainWin‐
60 dow::new", that calls XSUB "Tk::MainWindow::CreateMainWindow", that
61 calls C subroutine Tk_CreateMainWindow(). It is a "Tk" subroutine,
62 so here black magic ends (almost).
63 The only remaining black magic is that the "Tk" initialization rou‐
65 tine creates a lot of commands, but the subroutine for creation is
66 usurped by portableTk and the commands are created in the package
67 "Tk". They are associated to XSUBs that are related to one of three
68 C subroutines XStoSubCmd(), XStoBind(), or XStoTk(), but have dif‐
69 ferent data parts.
70 The result of the call is blessed into "Tk::MainWindow", as it
72 should.
73 Inside "$top->title('Text demo');"
75 The package "Tk::Toplevel" defines a lot of subroutines on the fly
76 on some list. All the commands from the list are converted to the
77 corresponding subcommands of "wm" method of the widget. Here sub‐
78 command is a command with some particular second argument (in this
79 case "title"). Recall that the first argument is $self.
80 Now "Tk::Toplevel" @ISA "Tk::Widget", that in turn @ISA "Tk". So a
82 call to "$top->wm('title','Text demo')" calls "Tk::wm", that is
83 defined during call to Tk_CreateMainWindow(). As it is described
84 above, the XSUB associated to XStoSubCmd() is called.
85 This C routine is defined in "tkGlue.c". It gets the data part of
87 XSUB, creates a "SV" with the name of the command, and calls
88 Call_Tk() with the XSUB data as the first argument, and with the
89 name of XSUB stuffed into the Perl stack in the place there "tk"
90 expects it. (In fact it can also reorder the arguments if it thinks
91 it is what you want).
92 The latter procedure extracts name of "tk" procedure and "client‐
94 Data" from the first argument and makes a call, using Perl stack as
95 "argv" for the procedure. A lot of black magic is performed after‐
96 wards to convert result of the procedure to a Perl array return.
97 Inside "$text = $top->Text(background => $txtBg);"
99 Above we discussed how the command "Tk::Widget::Text" is created.
100 The above command calls it via inheritance. It is translated to
101 Tk::Text::new($top, background => $txtBg);
103 The package "Tk::Text" has no method "new", so the "Tk::Wid‐
105 get::new" is called. In turn it calls "Tk::Text->DoInit($top)",
106 that is "Tk::Widget::DoInit(Tk::Text,$top)", that initializes the
107 bindings if necessary. Then it creates the name for the widget of
108 the form ".text0", and calls "Tk::text('.text0', background =>
109 $txtBg)" (note lowercase). The result of the call is blessed into
110 "Tk::Text", and the method "bindtags" for this object is called.
111 Now the only thing to discuss is who defines the methods "text" and
113 "bindtags". The answer is that they are defined in "tkWindow.c",
114 and these commands are created in the package "Tk" in the same
115 sweep that created the command "Tk::wm" discussed above.
116 So the the same C code that corresponds to the processing of corre‐
118 sponding TCL commands is called here as well (this time via
119 "XStoTk" interface).
120 Inside "$text->insert('insert','Hello, world!');"
122 As we discussed above, the subcommands of widget procedures corre‐
123 spond to XSUB "XStoWidget". This XSUB substitutes the first argu‐
124 ment $text (that is a hash reference) to an appropriate value from
125 this hash, adds the additional argument after the first one that
126 contains the name of the subcommand extracted from the data part of
127 XSUB, and calls the corresponding Tk C subroutine via "Call_Tk".
128 Ilya Zakharevich <ilya@math.ohio-state.edu>
130perl v5.8.8 2008-02-05 Internals(3)