Toplevel(3itk)

✨ Toplevel ✨

okay bestie, welcome to the Toplevel page from the [incr Tk] manual, section 3itk 💖 this is the one that gives your mega-widget its very own window to live in, and honestly? iconic behavior.

---

🌸 NAME 🌸

Toplevel — the base class for mega-widgets that live inside a top-level window 🪟✨

---

🦋 INHERITANCE 🦋

so the family tree is giving:

itk::Archetype <- itk::Toplevel

meaning itk::Toplevel is the child, itk::Archetype is the parent. genetics, but make it Tk 💅

---

🎀 STANDARD OPTIONS 🎀

these two come standard, no notes:

• background
• cursor

if you want the whole lore on these, go read the options manual entry, bestie — it's all in there 📖

---

💅 WIDGET-SPECIFIC OPTIONS 💅

okay so this one's special to Toplevel:

• -title — Name: title, Class: Title, Command-Line Switch: -title
  • sets the title that the window manager shows in the title bar above the window 🏷️
  • the default title is the null string (so, empty, blank, a whole lotta nothing 🙈)

---

👑 DESCRIPTION 👑

so here's the tea ☕ Toplevel inherits everything from the Archetype class — every last bit — and then adds a Tk toplevel called the "hull" component to represent the body of the mega-widget. the hull is basically the main character's body, and the window class name for the hull is set to the most-specific class name for the mega-widget. very "dress for the job you want" energy ✨

the protected variable itk_interior holds the window path name for the "hull" component. and derived classes specialize this widget by packing other widget components into the hull — like accessorizing, but with widgets 🎀

and because the hull for the Toplevel class is implemented with a Tk toplevel, mega-widgets in the Toplevel class get their own toplevel window. that's the whole point, that's the serve 💁‍♀️ this class is used to create dialog boxes and other pop-up windows. pop off, fr fr 🔥

---

🧚 COMPONENTS 🧚

• hull — Name: hull, Class: Toplevel
  • the "hull" component acts as the body for the entire mega-widget 🫶
  • other components get packed into the hull to further specialize the widget — that's how you build the whole look, layer by layer 🌈

---

⭐ EXAMPLE ⭐

not me giving you a full worked example, because I love you 🫶 the following example implements a MessageInfo mega-widget. it creates a pop-up message that the user can dismiss by pushing the "Dismiss" button.

option add *MessageInfo.title "Notice" widgetDefault

itcl::class MessageInfo {
    inherit itk::Toplevel

    constructor {args} {
        itk_component add dismiss {
            button $itk_interior.dismiss -text "Dismiss"                 -command "destroy $itk_component(hull)"
        }
        pack $itk_component(dismiss) -side bottom -pady 4

        itk_component add separator {
            frame $itk_interior.sep -height 2 -borderwidth 1 -relief sunken
        }
        pack $itk_component(separator) -side bottom -fill x -padx 4

        itk_component add icon {
            label $itk_interior.icon -bitmap info
        }
        pack $itk_component(icon) -side left -padx 8 -pady 8

        itk_component add infoFrame {
            frame $itk_interior.info
        }
        pack $itk_component(infoFrame) -side left -expand yes             -fill both -padx 4 -pady 4

        itk_component add message {
            label $itk_interior.mesg -width 20
        } {
            usual
            rename -text -message message Text
        }
        pack $itk_component(message) -expand yes -fill both

        eval itk_initialize $args

        after idle [code $this centerOnScreen]
    }

    protected method centerOnScreen {} {
        update idletasks
        set wd [winfo reqwidth $itk_component(hull)]
        set ht [winfo reqheight $itk_component(hull)]
        set x [expr ([winfo screenwidth $itk_component(hull)]-$wd)/2]
        set y [expr ([winfo screenheight $itk_component(hull)]-$ht)/2]
        wm geometry $itk_component(hull) +$x+$y
    }
}

itk::usual MessageInfo {
    keep -background -cursor -foreground -font
    keep -activebackground -activeforeground -disabledforeground
    keep -highlightcolor -highlightthickness
}

#
# EXAMPLE:  Create a notice window:
#
MessageInfo .m -message "File not found:\n/usr/local/bin/foo"

---

💜 KEYWORDS 💜

itk, Archetype, Widget, mega-widget — that's the tag cloud, bestie 🏷️✨

---

and that's the whole page! this was itk version 3.0, Toplevel(3itk), and yeah — ily, go build something gorgeous with it 💖🎀🦋 no cap, periodt.