Internals(3pm)

👑 NAME 💖

Tk::Internals — what is Perl Tk interface doing when you call Tk functions.

okay so real talk bestie: this info is worse than useless for actual "perlTk" users 🫠 but it can be of some help if you're the kind of person who messes with a modified Tk source and pairs it with "perlTk". iykyk.

also this doc is literally under construction 🚧 — the info is believed to be pertinent to the version of "portableTk" that was available when it got written, and every single detail is subject to change. no cap. 🙈

---

🦋 DESCRIPTION 🦋

✨ PreCompiling ✨

before we even get to the actual compilation stage, a script scans the source and pulls out the subcommands of the different commands. all that info lives in the file pTk/Methods.def 📂.

🧚 Compilation 🧚

during compilation, that file above gets included into the source of the booting routine of the dynamic (or static) library. more precisely: the booting code of the module Tk calls the subroutine Boot_Glue() from the module tkGlue.c, and that subroutine includes the file (with appropriate macro definitions). slay. 💅

🌸 Inside use Tk; 🌸

the module bootstraps the C code, then loads the Perl libraries. the heart of the Perl code is contained in the Tk::Widget library, and all the widgets inherit from this module. code for toplevels gets loaded from Tk::MainWindow 👑.

during bootstrap of the C glue code, the Xevent::? codes and a handful of Tk::Widget and Tk::Image routines are defined. (much, much more XSUBs are created from Tk.xs code, bestie.) the widget subcommands are glued to Perl basing on the list included from pTk/Methods.def. in fact all the subcommands are glued to XSUBs that are related to the same C subroutine XStoWidget(), but they have different data parts. the way that works?? iconic.

during the Perl code bootstrap, the method Tk::Widget::import is called. this call requires all the code from the particular widget packages.

code from the widget packages calls an obscure command like

(bless \"Text")->WidgetClass;

this command (actually Tk::Widget::WidgetClass()) creates three routines: Tk::Widget::Text(), Tk::Widget::isText(), and Tk::Text::isText(). the first one is basically new of Tk::Text, the other two return constants. it also puts the class into the depository. 💖

🎀 Inside $top = MainWindow->new; 🎀

this one is quite intuitive, honestly. the call goes direct to Tk::MainWindow::new, that calls XSUB Tk::MainWindow::CreateMainWindow, that calls C subroutine Tk_CreateMainWindow(). it's a Tk subroutine, so here the black magic ends (almost 😭).

the only remaining black magic is that the Tk initialization routine creates a lot of commands, but the subroutine for creation is usurped by portableTk and the commands are created in the package Tk. they're associated to XSUBs that are related to one of three C subroutines — XStoSubCmd(), XStoBind(), or XStoTk() — but with different data parts. three flavors, one vibe. 🌈

the result of the call is blessed into Tk::MainWindow, as it should be. periodt.

💜 Inside $top->title('Text demo'); 💜

the package Tk::Toplevel defines a lot of subroutines on the fly on some list. all the commands from that list get converted to the corresponding subcommands of the wm method of the widget. here, subcommand = a command with some particular second argument (in this case title). and recall that the first argument is $self. ✨

now Tk::Toplevel @ISA Tk::Widget, which in turn @ISA Tk. so a call to $top->wm('title','Text demo') calls Tk::wm, which is defined during the call to Tk_CreateMainWindow(). and as described above, the XSUB associated to XStoSubCmd() is the one that gets called.

this C routine is defined in tkGlue.c. it gets the data part of the XSUB, creates a SV with the name of the command, and calls Call_Tk() with the XSUB data as the first argument, and with the name of the XSUB stuffed into the Perl stack in the place where tk expects it. (in fact it can also reorder the arguments if it thinks that's what you want 👀).

the latter procedure extracts the name of the tk procedure and clientData from the first argument, and makes a call, using the Perl stack as argv for the procedure. a lot of black magic is performed afterwards to convert the result of the procedure to a Perl array return. 🪄

🍓 Inside $text = $top->Text(background => $txtBg); 🍓

above we discussed how the command Tk::Widget::Text is created. the command up there calls it via inheritance, and it gets translated to

Tk::Text::new($top, background => $txtBg);

the package Tk::Text has no method new, so Tk::Widget::new is what gets called. in turn it calls Tk::Text->DoInit($top), that is Tk::Widget::DoInit(Tk::Text,$top), which initializes the bindings if necessary. then it creates the name for the widget of the form .text0, and calls Tk::text('.text0', background => $txtBg) (note lowercase 🫶). the result of the call is blessed into Tk::Text, and the method bindtags for this object is called.

now the only thing left to discuss is who defines the methods text and bindtags. the answer: they're defined in tkWindow.c, and these commands are created in the package Tk in the same sweep that created the command Tk::wm we talked about above. ⭐

so the same C code that corresponds to the processing of the corresponding TCL commands is called here as well (this time via the XStoTk interface).

💀 Inside $text->insert('insert','Hello, world!'); 💀

as we discussed above, the subcommands of widget procedures correspond to XSUB XStoWidget. this XSUB substitutes the first argument $text (which 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 the XSUB, and calls the corresponding Tk C subroutine via Call_Tk.

---

shoutout to the author of all this chaos: Ilya Zakharevich <ilya@math.ohio-state.edu> 🫶 you built something truly wild and we are all just living in it.

and that's the whole page bestie 💖 — this one's from perl v5.40.1, dated 2025-04-13. go forth and read some C, mwah 💅✨