iwidgets::shell(1)

✨ iwidgets::shell ✨

okay bestie, so this is iwidgets::shell(1) from the [incr Widgets] crew — a whole manual page about making a shell widget, and yes it's as iconic as it sounds 💅

---

🌸 NAME 🌸

iwidgets::shell — create and manipulate a shell widget

---

🦋 SYNOPSIS 🦋

iwidgets::shell pathName ?options?

---

💜 INHERITANCE 💜

itk::Toplevel <- iwidgets::Shell

so it's inheriting from itk::Toplevel, slay ✨

---

🎀 STANDARD OPTIONS 🎀

• background
• cursor
• foreground

these are the basics bestie, and the "options" manual entry has the deets on all of them 📖

---

👑 INHERITED OPTIONS 👑

• title

the "Toplevel" manual entry is where you go for the lowdown on that one 🫶

---

💖 WIDGET-SPECIFIC OPTIONS 💖

• -height — Name: height, Class: Height, Command-Line Switch: -height

Sets the height of the shell, and you can write the value in literally any form that Tk_GetPixels is happy with. If you pass zero, the height just auto-adjusts to whatever the components in the childsite actually need (size requests, bestie). Any other value and the height is locked in, fixed, no takebacks. Default is zero. ⚠️ NOTE: this can make things flicker a lil bit on slower machines — and the fix is to just set width and height to an appropriate value. periodt.

• -master — Name: master, Class: Window, Command-Line Switch: -master

This declares the shell a transient window, with the master window given by the master option. That master window should either be another existing toplevel window, or {} for no master at all. Default is {} for shells and . for dialogs. no cap 🫡

• -modality — Name: modality, Class: Modality, Command-Line Switch: -modality

Lets the shell grab control of the screen, and there are three flavors: application, system, or none.

• application modal stops any other toplevel windows inside the application that are direct children of . from gaining focus.
• system modal goes feral and locks the whole screen, preventing all windows from gaining focus no matter what application they belong to.
• none does no grabs at all.

Default is none. 💀

• -padx — Name: padX, Class: Pad, Command-Line Switch: -padx

Padding distance for the childsite in the X-direction, in any form Tk_GetPixels accepts. Default is 10.

• -pady — Name: padY, Class: Pad, Command-Line Switch: -pady

Padding distance for the childsite in the Y-direction, again in any form Tk_GetPixels accepts. Default is 10.

• -width — Name: width, Class: Width, Command-Line Switch: -width

Sets the width of the shell, in any form Tk_GetPixels accepts. Pass zero and the width auto-adjusts to fit what the components in the childsite are asking for. Otherwise the width is fixed, full stop. Default is zero. ⚠️ NOTE: same flickering situation as height on slower machines — set width and height to an appropriate value to avoid it, iykyk.

---

🌈 DESCRIPTION 🌈

The iwidgets::shell command creates a shell — which is a top level widget that supports modal operation. main character energy, honestly 👑

---

⭐ METHODS ⭐

The iwidgets::shell command creates a new Tcl command whose name is pathName. You use that command to invoke various operations on the widget, and the general form is:

pathName option ?arg arg ...?

option and the args decide exactly what the command does. Here's everything shell widgets can do:

🧚 WIDGET-SPECIFIC METHODS 🧚

• pathName activate — Displays the shell and waits, and how it waits depends on the modality. For application and system modal activations it performs a grab operation and waits for the result. That result can get returned through an argument to the deactivate method.
• pathName center ?widget? — Centers the shell relative to another widget. The widget argument is optional. If you pass it, it should be the path of another widget to center upon. If you don't, the shell gets centered on the screen as a whole. 🎯
• pathName cget option — Returns the current value of the configuration option given by option. option can be any of the values that the iwidgets::shell command accepts.
• pathName childsite — Returns the pathname of the child site widget. 🍓
• pathName configure ?option? ?value option value ...? — Query or modify the widget's configuration options.
  • No option at all → returns a list describing all the available options for pathName (peep Tk_ConfigureInfo for the format of that list).
  • option with no value → returns a list describing that one named option (identical to the matching sublist from the no-option case).
  • One or more option-value pairs → modifies the given widget option(s) to the given value(s), and the command returns an empty string.

option can be any of the values that the iwidgets::shell command accepts.

• pathName deactivate ?arg? — Deactivates the display of the shell. Takes an optional arg that gets passed to the activate method, which returns the value. Heads up: that optional argument only actually does anything for application and system modal dialogs. 🫠

---

🎁 COMPONENTS 🎁

• Name: shellchildsite, Class: frame

The shellchildsite component is the user child site for the shell. Go read the "frame" widget manual entry for the details on the shellchildsite component item.

---

🌟 EXAMPLE 🌟

package require Iwidgets 4.0
iwidgets::shell .sh -modality application -padx 20 -pady 20 -title Shell

pack [label [.sh childsite].l -text SHELL]

.sh center
.sh activate

look at that, it's giving flawless 😭💖

---

💌 AUTHOR 💌

Mark L. Ulferts Kris Raney

---

🔑 KEYWORDS 🔑

shell, widget

---

and that's the whole page bestie!! this one came to you from Tk, page iwidgets::shell(1) — go forth and make shells, you absolute icon 🫶✨🎀