Toplevel(3pm)

📦
version 804.036 · 15 versions
, in debian trixie, ubuntu questing

💖 Toplevel — the manual page, but make it a group chat 💖

so this is Toplevel(3pm), from the User Contributed Perl Documentation, and bestie it is SO much less scary than it looks. it's literally just "how to make a window." that's the whole assignment. 💅

✨ NAME ✨

Tk::Toplevel — create and manipulate Toplevel widgets 🦋

like. that's it. that's the name section. slay.

✨ SYNOPSIS ✨

$toplevel = $parent->Toplevel(?options?);

one line. one lil line and you have a whole window. iconic behavior honestly 🎀

✨ STANDARD OPTIONS ✨

okay so these are the standard ones you already know and love:

  • -borderwidth
  • -highlightbackground
  • -highlightthickness
  • -takefocus
  • -class
  • -highlightcolor
  • -relief
  • -cursor

go read Tk::options for the full tea on what all of those do — I'm not gonna re-explain them here and neither should you, iykyk 💜

✨ WIDGET-SPECIFIC OPTIONS ✨

these are the ones that are, like, specifically about Toplevel. the main character options, if you will 👑

  • -background — Name: background, Class: Background, Switch: -background. this is the same as the standard background option EXCEPT its value can also be an undefined value. and when it's undefined?? the widget displays no background or border at all, and no colors get consumed from its colormap for its background and border. ghost mode. invisible. we love a minimal queen 💀
  • -colormap — Name: colormap, Class: Colormap, Switch: -colormap. tells you which colormap this window uses. the value can be new — in which case a fresh new colormap gets created for the window and its children — OR it can be the name of another window (and that window has to be on the same screen and have the same visual as $widget), in which case the new window just borrows the colormap from that window. if you don't specify it, the new window uses the default colormap of its screen. 🚨 this option may not be changed with the configure method 🚨 so pick a lane and stay in it.
  • -container — Name: container, Class: Container, Switch: -container. value has to be a boolean. if it's true, it means this window is gonna be used as a container that some other application gets embedded into (for example, a Tk toplevel can be embedded using the -use option). the window will support the appropriate window manager protocols for things like geometry requests. and here's the important part — the window should NOT have any children of its own in this application. 🚨 this option may not be changed with the configure method 🚨
  • -height — Name: height, Class: Height, Switch: -height. the desired height for the window, in any of the forms that Tk_GetPixels accepts. and if this value is less than or equal to zero?? the window doesn't request any size at all. zero thoughts, head empty 🍓
  • -menu — Name: menu, Class: Menu, Switch: -menu. gives you a menu widget to use as a menubar. on the Macintosh, the menubar shows up across the top of the main monitor. on Microsoft Windows and all UNIX platforms, the menu appears across the toplevel window as part of the window dressing that the window manager maintains. cross-platform icon behavior 🌈
  • -screen — Name: "", Class: "", Switch: -screen. picks the screen to put the new window on. any valid screen name works, even one that's associated with a different display. defaults to the same screen as its parent. this one is special though — it may not be specified via the option database, and it may not be modified with the configure method. a diva. respect it. 💅
  • -title — Switch: -title. sets the title of the toplevel window. yep, no Name or Class here, just the switch, that's just how it is. the title. on the window. slay 🎀
  • -use — Name: use, Class: Use, Switch: -use. this one is for embedding. if the value isn't an empty string, it has to be the window identifier of a container window, written as a hexadecimal string like the ones the winfo id command returns. the toplevel widget then gets created as a child of that given container instead of the root window for the screen. if the container window is in a Tk application, it must be a frame or toplevel widget that had the -container option specified. 🚨 this option may not be changed with the configure method 🚨
  • -visual — Name: visual, Class: Visual, Switch: -visual. visual information for the new window, in any of the forms Tk_GetVisual accepts. if you don't specify it, the new window uses the default visual for its screen. 🚨 the visual option may not be modified with the configure method 🚨
  • -width — Name: width, Class: Width, Switch: -width. the desired width for the window, in any of the forms Tk_GetPixels accepts. and if this is less than or equal to zero, the window requests no size at all. same energy as -height. they're twins 💜

✨ DESCRIPTION ✨

The Toplevel method creates a new toplevel widget — that's the one given by the $widget argument. extra options, all the ones described above, can be specified on the command line or in the option database to configure stuff about the toplevel like its background color and relief. and the toplevel command hands you back the path name of the new window. ✨

A toplevel is basically a frame, except it gets created as a top-level window: its X parent is the root window of a screen, not the logical parent from its path name. so like… different parent, same vibe. the primary purpose of a toplevel is to be a container for dialog boxes and other collections of widgets. and the ONLY visible features of a toplevel are its background color and an optional 3-D border that makes the toplevel look raised or sunken. that's the whole look. minimalism. we stan 🦋

✨ WIDGET METHODS ✨

The Toplevel method creates a widget object. this object supports the configure and cget methods described in Tk::options, which you can use to ask about and modify all the options we just talked about. and the widget also inherits every single method from the generic Tk::Widget class and from the Tk::Wm class. nepotism baby, but make it inheritance 💅

✨ BINDINGS ✨

when a new toplevel is created, it has no default event bindings. like, none. zero. because toplevels are not intended to be interactive. they're the stage, not the performer 🎭

✨ SEE ALSO ✨

  • Tk::Widget
  • Tk::Wm

✨ KEYWORDS ✨

toplevel, widget

and that's the whole page bestie!! 🫶 you now officially know everything Toplevel(3pm) has to say. go make a window. go be a container. go set a -title. main character energy only ✨💖

this was perl v5.40.1, dated 2025-04-13 — tysm for reading, ily, drink some water 💧🌸
📦 where this page comes from