itclvars(n)

💖 itclvars(n) — the [incr Tcl] variable lore, explained bestie-to-bestie 💖

okay so this page is itclvars, from the [incr Tcl] manual, and it's literally just about the ✨global variables✨ that [incr Tcl] makes for you. short page, big vibes. let's get into it 🫶

🌸 NAME 🌸

itclvars — variables used by [incr Tcl]

no cap, that's the whole name section. iconic brevity. 💅

✨ DESCRIPTION ✨

so here's the tea: the following global variables are created and managed automatically by the [incr Tcl] library. and unless it says otherwise down below, you (and your application-specific code) should treat them as read-only. they're not yours to poke at, bestie, they're the library's. 🙈

• itcl::library — when an interpreter gets created, [incr Tcl] sets this one up to hold the name of a directory that contains the system library of [incr Tcl] scripts. the initial value comes from the ITCL_LIBRARY environment variable if that exists, and if it doesn't, it comes from a compiled-in value instead.
• itcl::patchLevel — again, when an interpreter is created, [incr Tcl] initializes this to hold the current patch level for [incr Tcl]. for example, a value of "2.0p1" means [incr Tcl] version 2.0 with the first set of patches applied. so like, p1 = patch drop #1, she's been updated. 🌈
• itcl::purist — okay this one is the main character of the page, ngl. when an interpreter is created containing Tcl/Tk and the [incr Tcl] namespace facility, this variable controls a "backward-compatibility" mode for widget access. let me explain, because this is the whole plot. 🎀

in vanilla Tcl/Tk there's a single pool of commands, so the access command for a widget is the same as the window name. simple. one pool, one name, no drama.

but the moment a widget gets created within a namespace? its access command gets installed in that namespace, and from outside the namespace you're supposed to reach it with a qualified name. like so:

namespace foo {
    namespace bar {
        button .b -text "Testing"
    }
}
foo::bar::.b configure -background red
pack .b

note that the window name ".b" is still what you use with commands like pack and destroy. but the access command for the widget — i.e. the name that shows up as the first argument on a command line — has to be more specific than that. two different things, don't mix them up bestie 💀

the "winfo command" command can be used to query the fully-qualified access command for any widget, so you can write:

[winfo command .b] configure -background red

and honestly? that's good practice when you're writing library procedures. also, in conjunction with the bind command, the "%q" field can be used in place of "%W" as the access command:

bind Button <Key-Return> {%q flash; %q invoke}

okay so while this behavior totally makes sense from the standpoint of encapsulation, it causes problems with existing Tcl/Tk applications. 😭 a lot of existing apps are written with bindings that use "%W", and a lot of library procedures just assume the window name is the access command. awkward.

so this is where itcl::purist comes in — it controls a backward-compatibility mode:

• by default, this variable is "0", and the window name can be used as an access command in any context. whenever the unknown procedure stumbles across a widget name, it simply uses "winfo command" to figure out the appropriate command name. easy, forgiving, old-school.
• if this variable is set to "1", that backward-compatibility mode is disabled. this gives you better encapsulation, but heads up — using the window name as the access command may lead to "invalid command" errors. so like, you asked for strict mode, you got strict mode. 🫶

• itcl::version — when an interpreter is created, [incr Tcl] initializes this variable to hold the version number in the form x.y. changes to x represent major changes with probable incompatibilities, and changes to y represent small enhancements and bug fixes that retain backward compatibility. so if the first number moves, brace yourself. if the second one moves, you're fine. iykyk. 💜

🔑 KEYWORDS 🔑

itcl, variables

and that's the whole page, bestie!! 🦋 no notes, she ate, we love a short manpage. this was the itclvars(n) page from itcl, version 3.0 — so if anyone asks, it's itcl 3.0 energy all the way down, periodt. 💖✨🎀