blt::container(3tcl)

💖 NAME 💖

okay bestie, welcome to the blt::container(3tcl) manual page from the BLT Built-In Commands collection. this whole thing is about the container widget, and its entire personality is: a widget to contain a foreign window. that's the gig. no cap. 🫶

---

✨ SYNOPSIS ✨

container pathName ?options?

---

🌸 DESCRIPTION 🌸

the container widget lets you swallow another X11/Win32 toplevel, or embed an X11 window from a foreign application right into your Tk application. the foreign window gets reparented inside of the widget. after that, you can place and arrange the container just as you would any Tk widget. iconic behavior, honestly. 💅

---

🦋 INTRODUCTION 🦋

Notebooks are a popular graphical paradigm. they let you organize many windows in a single widget. for example, you might have an application that displays several X-Y graphs at the same time. typically, you can't pack the graphs into the same frame because they are too large. the other alternative is to pack the graphs into several toplevel widgets, allowing them to overlap on the screen. the problem is that all the different toplevel windows clutter the screen and are difficult to manage. 😭

the container widget lets you organize your application by displaying each graph as a page in a folder of a notebook. only one page is visible at a time. when you click on a tab, the folder (graph) corresponding to the tab is displayed in the container widget. the container also lets you temporarily tear pages out of the notebook into a separate toplevel widget, and put them back in the container later. for example, you could compare two graphs side-by-side by tearing them out, and then replace them when you are finished. bestie, that's lowkey main character energy. 👑

A container may contain an unlimited number of folders. if there are too many tabs to view, you can arrange them as multiple tiers or scroll the tabs. the container uses the conventional Tk scrollbar syntax, so you can attach a scrollbar too. ✨

---

🔥 EXAMPLE 🔥

You create a container widget with the container command.

# Create a new container
container .c

A new Tcl command .c is also created. this command can be used to query and modify the container. for example, to change the default borderwidth, you use the new command and the container's configure operation.

# Change the default font.
.c configure -borderwidth 2

You can then add folders using the insert operation.

# Create a new folder "f1"
.c coinsert 0 "f1"

this inserts the new tab named "f1" into the container. the index 0 indicates location to insert the new tab. you can also use the index end to append a tab to the end of the container. by default, the text of the tab is the name of the tab. you can change this by configuring the -text option.

# Change the label of "f1"
.ts tab configure "f1" -label "Tab #1"

The insert operation lets you add one or more folders at a time.

.ts insert end "f2" -label "Tab #2" "f3" "f4"

The tab on each folder contains a label. a label may display both an image and a text string. you can reconfigure the tab's attributes (foreground/background colors, font, rotation, etc) using the tab configure operation.

# Add an image to the label of "f1"
set image [image create photo -file stopsign.gif]
.ts tab configure "f1" -image $image
.ts tab configure "f2" -rotate 90

Each folder may contain an embedded widget to represent its contents. the widget to be embedded must be a child of the container widget. using the -window option, you specify the name of widget to be embedded. but don't pack the widget, the container takes care of placing and arranging the widget for you.

🚨 bestie, seriously: do not pack it. the container handles the placement and arrangement. periodt.

graph .ts.graph
.ts tab configure "f1" -window ".ts.graph" \
    -fill both -padx 0.25i -pady 0.25i

The size of the folder is determined by the sizes of the Tk widgets embedded inside each folder. the folder will be as wide as the widest widget in any folder. the tallest determines the height. you can use the tab's -pagewidth and -pageheight options override this.

Other options control how the widget appears in the folder. the -fill option says that you wish to have the widget stretch to fill the available space in the folder.

.ts tab configure "f1" -fill both -padx 0.25i -pady 0.25i

Now when you click the left mouse button on "f1", the graph will be displayed in the folder. it will be automatically hidden when another folder is selected. if you click on the right mouse button, the embedded widget will be moved into a toplevel widget of its own. clicking again on the right mouse button puts it back into the folder. 🦋

If you want to share a page between two different folders, the -command option lets you specify a Tcl command to be invoked whenever the folder is selected. you can reset the -window option for the tab whenever it's clicked.

.ts tab configure "f2" -command {
    .ts tab configure "f2" -window ".ts.graph"
}
.ts tab configure "f1" -command {
    .ts tab configure "f1" -window ".ts.graph"
}

If you have many folders, you may wish to stack tabs in multiple tiers. the container's -tiers option requests a maximum number of tiers. the default is one tier.

.ts configure -tiers 2

If the tabs can fit in less tiers, the widget will use that many. whenever there are more tabs than can be displayed in the maximum number of tiers, the container will automatically let you scroll the tabs. you can even attach a scrollbar to the container.

.ts configure -scrollcommand { .sbar set }  -scrollincrement 20
.sbar configure -orient horizontal -command { .ts view }

By default tabs are along the top of the container from left to right. but tabs can be placed on any side of the container using the -side option.

# Arrange tabs along the right side of the container.
.ts configure -side right -rotate 270

---

👑 SYNTAX 👑

The container command creates a new window using the pathName argument and makes it into a container widget.

container pathName ?option value?...

Additional options may be specified on the command line or in the option database to configure aspects of the container such as its colors, font, text, and relief. the container command returns its pathName argument. at the time this command is invoked, there must not exist a window named pathName, but pathName's parent must exist. 🫶

When first created, a new container contains no tabs. tabs are added or deleted using widget operations described below. it is not necessary for all the tabs to be displayed in the container window at once; commands described below may be used to change the view in the window. containers allow scrolling of tabs using the -scrollcommand option. they also support scanning (see the scan operation). tabs may be arranged along any side of the container window using the -side option.

The size of the container window is determined by the number of tiers of tabs and the sizes of the Tk widgets embedded inside each folder. the widest widget determines the width of the folder. the tallest determines the height. if no folders contain an embedded widget, the size is determined solely by the size of the tabs.

You can override either dimension with the container's -width and -height options. 💖

✨ CONTAINER OPERATIONS ✨

okay bestie so every single thing you wanna do to a container, you do it by shouting at it like this: its pathname, then the operation, then whatever args that operation needs. the general form is literally:

pathName operation ?arg arg ...?

the operation + the args together decide exactly what happens. and these are the operations container widgets vibe with: 💖

• pathName cget option — hands you back the current value of the config option named by option. and guess what, option can be literally anything that the configure operation down below is willing to accept. so it's the "just tell me what it is rn" move.
• pathName configure ?option? ?value option value ...? — this is the query-or-modify-the-config-options one, the multitasker. if you pass no option, it returns a list describing all the available options for pathName (peep Tk_ConfigureInfo if you're curious about the format of that list). if you pass option with no value, the command returns a list describing just that one named option (and that list is identical to the matching sublist of the value you'd get with no option at all — cute, consistent). and if you pass one or more option-value pairs, it modifies the given widget option(s) to have the given value(s), and in that case the command returns an empty string. slay. Option and value are described right here:
  • -background color — sets the border color of the container.
  • -borderwidth pixels — sets the width of the 3-D border around the outside edge of the widget. the -relief option decides how that border gets drawn. default is 2.
  • -command pattern — says "go search for a window whose WM_COMMAND property matches this pattern" (X11 only, bestie). if no windows match, or more than one window matches, an error gets generated. if pattern is the empty string, then no command search happens at all. default is "".
  • -cursor cursor — specifies the widget's cursor. the default cursor is "".
  • -height pixels — specifies the requested height of the widget. if pixels is 0, then the height is height the embedded window plus the specified borderwidth. default is 0.
  • -highlightbackground color — sets the color to display in the traversal highlight region when the container does not have the input focus.
  • -highlightcolor color — sets the color to use for the traversal highlight rectangle that gets drawn around the widget when it has the input focus. default is black.
  • -highlightthickness pixels — sets the width of that highlight rectangle around the outside of the widget when it has the input focus. Pixels is a non-negative value and may take any of the forms acceptable to Tk_GetPixels. if the value is zero, no focus highlight is drawn around the widget at all. default is 2.
  • -name pattern — says "go search for a window whose WM_NAME property matches this pattern" (X11 only again 💅). if no windows match, or more than one window matches, an error is generated. if pattern is the empty string, then no name search is performed. default is "".
  • -relief relief — specifies the 3-D effect for the container widget. Relief says how the container should appear relative to the widget it's packed into; for example, raised means the container should look like it's protruding. default is sunken.
  • -takefocus focus — gives info used when the focus moves from window to window via keyboard traversal (think Tab and Shift-Tab). if focus is 0, that means this window gets skipped entirely during keyboard traversal. 1 means this window should always receive the input focus. an empty value means the traversal scripts decide whether to focus on the window. default is 1.
  • -width pixels — specifies the requested width of the widget. if pixels is 0, then the width is the width the embedded window and the specified borderwidth. default is 0.
  • -window id — specifies the foreign embedded using its path or X window id.
• pathName find -command|-name pattern — searches for all the windows that match the given pattern. if the -command switch is given, all windows whose WWM_COMMAND property match pattern are returned in a list (X11 only). if the -name switch is given, all windows whose WWM_NAME property match pattern are returned in a list. and the list that comes back contains pairs of the window id and the matching property. so it's giving "here's everybody who matched, with receipts". 🫶

---

🌈 KEYWORDS 🌈

container, widget

---

and that's the whole page, bestie, you ate it 💅✨ this was blt::container(3tcl) from BLT 2.5 — go forth and containerize, no cap 🎀🦋💖