tabset(n)

📦 version 2.5.3, in nixpkgs unstable

okay so bestie, welcome to the tabset(n) manual page from BLT Built-In Commands — we’re gonna make tabs make sense, no cap. 🍓✨

✨ NAME ✨

tabset — Create and manipulate tabset widgets. Periodt. 💅

🎀 SYNOPSIS 🎀

tabset pathName ?options?

🌸 DESCRIPTION 🌸

The tabset widget displays a series of overlapping folders. Only the contents of one folder at a time is displayed. By clicking on the tab of a folder, you can view other folders. Each folder may contain any Tk widget that can be automatically positioned and resized in the folder.

There’s no limit to the number of folders. Tabs can be tiered or scrolled. Pages (i.e. embedded widgets) can be torn off and displayed in another toplevel widget, and also restored. A tabset can also be used as just a set of tabs, without displaying any pages. You can bind events to individual tabs, so it’s easy to add features like "balloon help".

🌈 INTRODUCTION 🌈

Notebooks are a popular graphical paradigm. They allow you to organize several windows that are too big to display at the same time as pages of a notebook. For example, your application may display several X-Y graphs at the same time. The graphs are too big to pack into the same frame. Managing them in several toplevel widgets is also cumbersome and clutters the screen. Instead, the tabset widget organizes the graphs as folders in a notebook.

Only one page is visible at a time. When you click on a tab, the folder corresponding to the tab is displayed in the tabset widget. The tabset also lets you temporarily tear pages out of the notebook into a separate toplevel widget, and put them back in the tabset later. For example, you could compare two graphs side-by-side by tearing them out, and then replace them when you are finished.

A tabset can contain any number of folders. If there are too many tabs to view, you can arrange them as multiple tiers or scroll the tabs. You can also attach Tk scrollbars to the tabset to scroll the tabs.

🦋 SYNTAX 🦋

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

tabset pathName ?option value?...

Additional options may be specified on the command line or in the option database to configure aspects of the tabset such as its colors, font, text, and relief. The tabset 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 tabset 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 tabset window at once; commands described below may be used to change the view in the window. Tabsets 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 tabset window using the -side option.

The size of the tabset 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 tabset’s -width and -height options.

👑 INDICES 👑

Indices refer to individual tabs/folders in the tabset. Many of the operations for tabset widgets take one or more indices as arguments. An index may take several forms:

  • number — unique index offset of the tab.
  • @x,y — tab that covers the point in the tabset window specified by x and y (in screen coordinates). If no tab covers that point, then the index is ignored.
  • select — the currently selected tab. The select index is typically changed by either clicking on the tab with the left mouse button or using the widget’s invoke operation.
  • active — the tab where the mouse pointer is currently located. The label is drawn using its active colors (see the -activebackground and -activeforeground options). The active index is typically changed by moving the mouse pointer over a tab or using the widget’s activate operation. There can be only one active tab at a time. If there is no tab located under the mouse pointer, the index is ignored.
  • begin — first tab in the tabset. If there are no tabs in the tabset then the index is ignored.
  • current — tab that is currently being operated upon. Used within bindings.
  • focus — tab that currently has the widget’s focus. This tab is displayed with a dashed line around its label. You can change this using the focus operation. If no tab has focus, then the index is ignored.
  • down — tab immediately below the tab that currently has focus, if there is one. If there is no tab below, the current tab is returned.
  • left — tab immediately to the left of the tab that currently has focus, if there is one. If there is no tab to the left, the current tab is returned.
  • next — the next tab. Wraps to the first tab if at end.
  • prev — the previous tab. Wraps to the last tab if at start.
  • right — tab immediately to the right of the tab that currently has focus, if there is one. If there is no tab to the right, the current tab is returned.
  • up — tab immediately above, if there is one, to the tab that currently has focus. If there is no tab above, the current tab is returned.
  • end — last tab in the tabset. If there are no tabs in the tabset then the index is ignored.

Some indices may not always be available. For example, if the mouse is not over any tab, active does not have an index. For most tabset operations this is harmless and ignored.

💅 OPERATIONS 💅

All tabset operations are invoked by specifying the widget’s pathname, the operation, and any arguments that pertain to that operation. The general form is:

pathName operation ?arg arg ...?

Operation and the args determine the exact behavior of the command. The following operations are available for tabset widgets:

🌟 pathName activate index

Sets the active tab to the one indicated by index. The active tab is drawn with its active colors (see the -activebackground and -activeforeground options) and may be retrieved with the index active. Only one tab may be active at a time. If index is the empty string, then all tabs will be drawn with their normal foreground and background colors.

🎯 pathName bind tagName ?sequence? ?command?

Associates command with tagName such that whenever the event sequence given by sequence occurs for a tab with this tag, command will be invoked. The syntax is similar to the bind command except that it operates on tabs, rather than widgets. The tagName is one of all, Perforation, Image, Leftimage, Startimage, Endimage, or the name label used to create a Tab. See the bind manual entry for complete details on sequence and the substitutions performed on command.

If all arguments are specified then a new binding is created, replacing any existing binding for the same sequence and tagName. If the first character of command is + then command augments an existing binding rather than replacing it. If no command argument is provided then the command currently associated with tagName and sequence (it’s an error if there’s no such binding) is returned. If both command and sequence are missing then a list of all the event sequences for which bindings have been defined for tagName.

🧚 pathName cget option

Returns the current value of the configuration option given by option. option may have any of the values accepted by the configure operation described in the section WIDGET OPTIONS below.

🍓 pathName configure ?option? ?value option value ...?

Query or modify the configuration options of the widget. If no option is specified, returns a list describing all the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. option and value are described in the section WIDGET OPTIONS below.

🦋 pathName coords element ?index?

Returns the screen coordinates for the given element, which is one of: text, image, leftimage, startimage, endimage, or perforation. All except startimage and endimage must also provide a tab index.

🌸 pathName delete first ?last?

Deletes one or more tabs from the tabset. first and last are the first and last indices, defining a range of tabs to be deleted. If last isn’t specified, then only the tab at first is deleted.

💖 pathName focus index

Designates a tab to get the widget’s focus. This tab is displayed with a dashed line around its label.

🎀 pathName get index

Returns the name of the tab. The value of index may be in any form described in the section INDICES.

⭐ pathName hightlight index

Highlight a tab.

That operation name is literally spelled hightlight here — copy it exactly, bestie. 💅

💜 pathName index ?flag? string

Returns the index offset of the tab specified by string. If flag is -name, then string is the name of a tab. If flag is -index, string is an index such as "active" or "focus". If flag is -both, string is either. If flag isn’t specified, it defaults to -index.

  • pathName insert position ?name ...? ?option value?... — drops brand-new tabs into the tabset, right before whatever tab position points at 🎀 position is either a number (where in the list the new tab goes) or the literal word end, which means, yeah, the end of the list. name is the tab's symbolic name — and bestie, please do not make it a number, because then the tabset will confuse it with tab indices and everything gets weird 😭 Returns a list of indices for all the new tabs. If a tab name is an empty string, or ends in #auto, it gets generated for you using the given prefix. You get back the list of created tab names.
  • pathName invoke index — selects the tab at index, maps that tab's embedded widget, and invokes the Tcl command associated with the tab, if there is one ✨ The return value is whatever that Tcl command returned, or an empty string if the tab has no command tied to it. Heads up: this whole thing is ignored if the tab's state (see the -state option) is disabled 💀
  • pathName move index before|after index — moves a tab from one index to a new position in the tabset. That's it, that's the whole vibe 🦋
  • pathName nearest x y ?varName? ?coordsVar? — returns the name of the tab nearest to the given X-Y screen coordinate 👑 If varName is present, it's a Tcl variable that gets set to one of text, image, leftimage, startimage, endimage, perforation, or the empty string, depending on which part of the tab the coordinate is sitting over. If coordsVar is present, you also get the bounding box coordinates for the matching item that got set in varName.
  • pathName perforation operation ?args? — this one controls the perforation on the tab label 🎟️
    • pathName perforation activate boolean — sets the perforation's active state to on or off.
    • pathName perforation invoke — invokes the command specified for perforations (see the -perforationcommand widget option). Typically that command places the page into a top level widget. The name of that toplevel is the concatenation of pathName, -, and tabName. The return value is the return value from the Tcl command, or an empty string if there's no command associated with the tab. This command is ignored if the tab's state (see the -state option) is disabled 🙈
  • pathName scan option args — implements scanning on tabsets. Two forms, depending on option:
    • pathName scan mark x y — records x and y and the current view in the tabset window; used with later scan dragto commands. Usually hooked up to a mouse button press in the widget. Returns an empty string ⭐
    • pathName scan dragto x y — computes the difference between its x and y arguments and the x and y arguments from the last scan mark command for the widget. Then it adjusts the view by 10 times the difference in coordinates 🔥 Typically hooked up to mouse motion events, so it feels like you're dragging the list at high speed through the window. Returns an empty string.
  • pathName see index — scrolls the tabset so the tab at index is actually visible in the widget's window. "bestie I can't see you, come here" energy 🫶
  • pathName select index — selects the tab. Short, sweet, slay 💅
  • pathName size — returns the number of tabs in the tabset 🌸
  • pathName tab operation ?args? — the big tab-management toolbox:
    • pathName tab cget nameOrIndex option — returns the current value of the configuration option given by option. option can be any of the values accepted by the tab configure operation described in the TAB OPTIONS section below.
    • pathName tab configure nameOrIndex ?nameOrIndex...? option? ?value option value ...? — queries or modifies the configuration options of one or more tabs. If no option is given, this returns a list describing all the available options for nameOrIndex. nameOrIndex can be either the name of a tab or its index — but names take precedence over indices 👀 meaning a tab literally named focus gets picked over the "focus" tab.

If option is specified but no value, you get back a list describing that one named option. If one or more option-value pairs are given, then each named tab (specified by nameOrIndex) gets its configuration option(s) set to the given value(s) — and in that last case, the empty string is returned. option and value are described in the TAB OPTIONS section below ✨

  • pathName tab dockall — docks all tearoffs 🧚
  • pathName tab names ?pattern? — returns the names of all the tabs matching the given pattern. No pattern argument? Then you get all the tab names, the whole roster 👑
  • pathName tab pageheight — the page doesn't actually describe this one, so I'm not gonna make something up, that's not the move 😭
  • pathName tab pagewidth — same deal, no description given. We simply do not know and we do not pretend 💀
  • pathName tab select nameOrindex — selects a tab by name or index, and makes it visible, selected, activated, and focused. It's a shortform for using separate commands, i.e. the "do it all for me" button 🎀
  • pathName tab tearoff ?index? — with no ?index?, returns a list of all torn-off tabs. Otherwise, returns the window for the given torn-off tab.
  • pathName tab tearoff ?index? — with no ?index?, returns a list of all torn-off tabs. Otherwise, toggles the torn-off state of the tab. (Yes, this one is listed twice in the docs and yes, the second one toggles. Not a typo of mine, I promise 🫠)
  • pathName view args — queries or changes the position of the tabset in the widget's window. Comes in these forms:
    • pathName view — returns a list of two numbers between 0.0 and 1.0 describing how much and which part of the tabset is visible in the window. For example, if view is "0.2 0.6", then 20% of the tabset's text is off-screen to the left, 40% is visible in the window, and 40% of the tabset is off-screen to the right 🦋 These are the exact same values passed to scrollbars via the -scrollcommand option.
    • pathName view moveto fraction — adjusts the view so that fraction of the total width of the tabset text is off-screen to the left. fraction must be a number between 0.0 and 1.0 ⭐
    • pathName view scroll number what — shifts the view in the window (left/top or right/bottom) according to number and what. number must be an integer. what must be either units or pages, or an abbreviation of those. If what is units, the view adjusts left or right by number scroll units (see the -scrollincrement option); if it's pages, the view adjusts by number widget windows. If number is negative, tabs farther to the left become visible; if it's positive, tabs farther to the right become visible 💅

✨ WIDGET OPTIONS ✨

Widget configuration options can be set either by the configure operation or the Tk option command. The resource class is Tabset. The resource name is the name of the widget 🌈

option add *Tabset.Foreground white
option add *Tabset.Background blue

Here are all the widget options available, no gatekeeping 💖

  • -activebackground color — sets the default active background color for tabs. A tab is active when the mouse is sitting over it, or when it's set by the activate operation. Individual tabs can override this by setting the tab's own -activebackground option.
  • -activeforeground color — sets the default active foreground color for tabs. Same deal: a tab is active when the mouse is over it or when activate sets it, and individual tabs can override it with their own -activeforeground option.
  • -anchor anchor — anchors the tab's text (and images) to a particular edge of the tab. The default value is center 🎀
  • -background color — sets the background color of the tabset.
  • -borderwidth pixels — sets the width of the 3-D border around the outside edge of the widget. The -relief option determines how that border gets drawn. The default is 2.
  • -cursor cursor — specifies the widget's cursor. The default cursor is "".
  • -dashes dashList — sets the dash style of the focus outline. When a tab has the widget's focus, it gets drawn with a dashed outline around its label. dashList is a list of up to 11 numbers that alternately represent the lengths of the dashes and gaps on the cross hair lines, and each number must be between 1 and 255. If dashList is "", the outline is a solid line instead. The default value is 5 2 ✨
  • -ellipsis string — the string appended to displayed labels that got truncated because they exceeded -labelmax. The default is ... 😭 (the little "there was more text here" dots)
  • -endimage imageName — specifies an image to be drawn after tabs (i.e., on the right if -side = top). This is used by a binding looking for endimage from the nearest subcommand.
  • -fillwidth boolean — indicates whether extra space should be allocated to tabs when multiple tiers are displayed. The default is yes 🫶
  • -font fontName — sets the default font for the text in tab labels. Individual tabs can override it by setting their own -font option. The default value is *-Helvetica-Bold-R-Normal-*-12-120-* 👑
  • -foreground color — sets the default color of tab labels. Individual tabs can override this with their own -foreground option. The default value is black.
  • -gap size — sets the gap (in pixels) between tabs. The default value is 2.
  • -gapleft size — sets a gap (in pixels) left between the text and -leftimage. The default value is 2.
  • -height pixels — specifies the requested height of the widget. If pixels is 0, the height of the widget gets calculated based on the size of the tabs and their pages. The default is 0.
  • -highlightbackground color — sets the color shown in the traversal highlight region when the tabset does not have input focus. focus-adjacent but make it cute 💖
  • -highlightcolor color — sets the color of the traversal highlight rectangle drawn around the widget when it does have input focus. The default is black. black, but make it focused ✨
  • -highlightthickness pixels — sets the width of that highlight rectangle around the outside of the widget when it has input focus. pixels is a non-negative value and may have any of the forms acceptable to Tk_GetPixels. If the value is zero, no focus highlight is drawn around the widget. The default is 2. zero means no glow-up, bestie 🫶
  • -labelbackground color — sets a background color for the label. The default is ". yes, a lonely quote, that's literally what the page says 😭
  • -labelmax length — the length at which displayed label text gets truncated after appending the value of -ellipsis. This enables a user implementation of truncating labels as the number of tabs increases. Default is 0, meaning do no truncation. iykyk, tab overflow is real 🍓
  • -outerpad pixels — padding around the exterior of the tabset and folder. personal space, but for widgets 💅
  • -pageheight pixels — sets the requested height of the page. The page is the area under the tab used to display the page contents. If pixels is 0, the maximum height of all embedded tab windows is used. The default is 0. page height main character energy 👑
  • -pagewidth pixels — sets the requested width of the page. The page is the area under the tab used to display the page contents. If pixels is 0, the maximum width of all embedded tab windows is used. The default is 0. same vibes, width edition 🌸
  • -perforationcommand string — specifies a Tcl script to be invoked to tear off the current page in the tabset. This command is typically invoked when the left mouse button is released over the tab perforation. The default action is to tear off the page and place it into a new toplevel window. tear-off drama, but make it Tcl 🔥
  • -relief relief — specifies the 3-D effect for the tabset widget. relief says how the tabset should appear relative to the widget it is packed into; for example, raised means the tabset should appear to protrude. The default is sunken. sunken, not sunk-cost 💀
  • -rotate theta — specifies the degrees to rotate text in tab labels. theta is a real value representing the number of degrees to rotate the tick labels. The default is 0.0 degrees. angled text is highkey iconic ⭐
  • -samewidth boolean — indicates if each tab should be the same width. If true, each tab will be as wide as the widest tab. The default is no. equal-width besties, no cap 💖
  • -scrollcommand string — specifies the prefix for a command for communicating with scrollbars. Whenever the view in the widget's window changes, the widget will generate a Tcl command by concatenating the scroll command and two numbers. If this option is not specified, then no command will be executed. scroll gossip, passed along 🎀
  • -scrollincrement pixels — sets the smallest number of pixels to scroll the tabs. If pixels is greater than 0, this sets the units for scrolling (e.g., when you change the view by clicking on the left and right arrows of a scrollbar). tiny scroll steps, tiny steps only 🦋
  • -selectbackground color — sets the color used when displaying the background of the selected tab. Individual tabs can override this option by setting the tab's -selectbackground option. selected-tab background said slay 💅
  • -selectcommand string — specifies a default Tcl script to be invoked when tabs are selected. This command is typically invoked when the left mouse button is pressed over the tab. Individual tabs may override this with the tab's -command option. Alternatively, the <<TabsetSelect>> virtual event may be bound to instead. The default value is "". bind it or command it, your call bestie 🫶
  • -selectforeground color — sets the default color of the selected tab's text label. Individual tabs can override this option by setting the tab's -selectforeground option. The default value is black. selected text, but make it readable ✨
  • -selectpad pixels — specifies extra padding to be displayed around the selected tab. The default value is 3. a lil breathing room for the chosen tab 🌈
  • -shadow colorAndOffset — sets the shadow color for the text in all tab labels. If an offset isn't given, it defaults to 1. Drop shadows are useful when both the foreground and background of the tab have similar color intensities. If color is the empty string, no shadow is drawn. The default value is "". shadow work, but for legibility 💜
  • -shadowcolor color — sets the folder shadow color. folder shadow, folder aura 🎀
  • -side side — specifies the side of the widget to place tabs. The default value is top. Valid values for side:
    • top — tabs are drawn along the top.
    • left — tabs are drawn along the left side.
    • right — tabs are drawn along the right side.
    • both — tabs are drawn along the bottom side. yes, that's what it says, copy-pasted energy 😭
  • -slant slant — specifies if the tabs should be slanted 45 degrees on the left and/or right sides. The default is none. Valid values for slant:
    • none — tabs are drawn as a rectangle.
    • left — the left side of the tab is slanted.
    • right — the right side of the tab is slanted.
    • both — both sides of the tab are slanted. angled tabs, angled vibes 🦋
  • -startimage imageName — specifies an image to be drawn before tabs (i.e., on the left if -side = top). This is used by a binding looking for startimage from the nearest subcommand. starter image, starter aesthetic ⭐
  • -tabbackground color — sets the default background color of tabs. Individual tabs can override this option by setting the tab's -background option. tab background, but the tab can still choose violence 💅
  • -tabborderwidth pixels — sets the width of the 3-D border around the outside edge of the tab. The -tabrelief option determines how the border is to be drawn. The default is 2. border width, but make it 3-D 🎀
  • -tabforeground color — specifies the color to use when displaying a tab's label. Individual tabs can override this option by setting the tab's -foreground option. label color, tab-level override unlocked 🔥
  • -tabrelief relief — specifies the 3-D effect for both tabs and folders. relief says how the tabs should appear relative to the background of the widget; for example, raised means the tab should appear to protrude. The default is raised. raised tabs, raised standards 👑
  • -tabtile image — specifies a tiled background for tabs. The default is "". tiled tab texture, obsessed 🧚
  • -takefocus focus — provides info used when moving focus from window to window via keyboard traversal (e.g. Tab and Shift+Tab). If focus is 0, this window should be 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. The default is 1. focus behavior, but make it keyboard-lore 💖
  • -tearoff boolean — display tearoff. tearoff toggle, periodt 💅
  • -textside side — if both images and text are specified for a tab, this option determines on which side of the tab the text is to be displayed. The valid sides are left, right, top, and bottom. The default value is left. text placement, but make it fashion 🌸
  • -tiers number — specifies the maximum number of tiers to use to display the tabs. The default value is 1. tiers of tabs, tiers of drama 🌈
  • -tile image — specifies a tiled background for the widget background excluding the tabs. If image isn't "", the background is tiled using image. Otherwise, the normal background color is drawn (see the -background option). image must be an image created using the Tk image command. The default is "". And yes: it specifies a tiled background image for the background of the widget — this does not include the tabs. background tile, but stay out of the tabs' lane 🫶
  • -transient boolean — tearoff window should be transient. transient tearoff window, very mysterious of it ✨
  • -width pixels — specifies the requested width of the widget. If pixels is 0, then the width of the widget will be calculated based on the size of the tabs and their pages. The default is 0. width request, auto-sized when zero 💖

✨ TAB OPTIONS ✨

Okay so, besides the configure operation, widget configuration options can also be set by the Tk option command. The class resource name is Tab.

option add *Tabset.Tab.Foreground white
option add *Tabset.name.Background blue

The following widget options are available:

  • -activebackground color — Sets the active background color for nameOrIndex. A tab is active when the mouse is positioned over it or set by the activate operation. This overrides the widget's -activebackground option.
  • -activeforeground color — Sets the default active foreground color for nameOrIndex. A tab is "active" when the mouse is positioned over it or set by the activate operation. Individual tabs may override this option by setting the tab's -activeforeground option.
  • -anchor anchor — Anchors the tab's embedded widget to a particular edge of the folder. This option has effect only if the space in the folder surrounding the embedded widget is larger than the widget itself. anchor specifies how the widget will be positioned in the extra space. For example, if anchor is center then the window is centered in the folder; if anchor is w then the window will be aligned with the leftmost edge of the folder. The default value is center.
  • -background color — Sets the background color for nameOrIndex. Setting this option overrides the widget's -tabbackground option.
  • -bindtags tagList — Specifies the binding tags for this tab. tagList is a list of binding tag names. The tags and their order will determine how commands for events in tabs are invoked. Each tag in the list matching the event sequence will have its Tcl command executed. Implicitly the name of the tab is always the first tag in the list. The default value is all.
  • -command string — Specifies a Tcl script to be associated with nameOrIndex. This command is typically invoked when left mouse button is pressed over the tab. Setting this option overrides the widget's -selectcommand option.
  • -data string — Specifies a string to be associated with nameOrIndex. This value isn't used in the widget code. It may be used in Tcl bindings to associate extra data (other than the image or text) with the tab. The default value is "".
  • -fill fill — If the space in the folder surrounding the tab's embedded widget is larger than the widget, then fill indicates if the embedded widget should be stretched to occupy the extra space. fill is either none, x, y, both. For example, if fill is x, then the widget is stretched horizontally. If fill is y, the widget is stretched vertically. The default is none.
  • -font fontName — Sets the font for the text in tab labels. If fontName is not the empty string, this overrides the tabset's -font option. The default value is "".
  • -foreground color — Sets the color of the label for nameOrIndex. If color is not the empty string, this overrides the widget's -tabforeground option. The default value is "".
  • -hidden bool — Hide the tab. The default is 0. The tab should be changed to not be the selected tab before setting it to hidden.
  • -image imageName — Specifies the image to be drawn in label for nameOrIndex. If image is "", no image will be drawn. Both text and images may be displayed at the same time in tab labels. The default value is "".
  • -leftimage imageName — Specify a second image to be drawn to the left before text/image when the widget's -textside = right. This image might represent a close icon when used with a binding that looks for leftimage from the nearest subcommand.
  • -ipadx pad — Sets the padding to the left and right of the label. pad can be a list of one or two screen distances. If pad has two elements, the left side of the label is padded by the first distance and the right side by the second. If pad has just one distance, both the left and right sides are padded evenly. The default value is 0.
  • -ipady pad — Sets the padding to the top and bottom of the label. pad can be a list of one or two screen distances. If pad has two elements, the top of the label is padded by the first distance and the bottom by the second. If pad has just one distance, both the top and bottom sides are padded evenly. The default value is 0.
  • -padx pad — Sets the padding around the left and right of the embedded widget, if one exists. pad can be a list of one or two screen distances. If pad has two elements, the left side of the widget is padded by the first distance and the right side by the second. If pad has just one distance, both the left and right sides are padded evenly. The default value is 0.
  • -pady pad — Sets the padding around the top and bottom of the embedded widget, if one exists. pad can be a list of one or two screen distances. If pad has two elements, the top of the widget is padded by the first distance and the bottom by the second. If pad has just one distance, both the top and bottom sides are padded evenly. The default value is 0.
  • -selectbackground color — Sets the color to use when displaying background of the selected tab. If color is not the empty string, this overrides the widget's -selectbackground option. The default value is "".
  • -shadow color — Sets the shadow color for the text in the tab's label. Drop shadows are useful when both the foreground and background of the tab have similar color intensities. If color is the empty string, no shadow is drawn. The default value is "".
  • -state state — Sets the state of the tab. If state is disable the text of the tab is drawn as engraved and operations on the tab (such as invoke and tab tearoff) are ignored. The default is normal.
  • -stipple bitmap — Specifies a stipple pattern to use for the background of the folder when the window is torn off. bitmap specifies a bitmap to use as the stipple pattern. The default is BLT.
  • -text text — Specifies the text of the tab's label. The exact way the text is drawn may be affected by other options such as -state or -rotate.
  • -tornwindow text — Name of window that was torn off.
  • -underline num — Character to underline in text. Default is -1.
  • -window pathName — Specifies the widget to be embedded into the tab. pathName must be a child of the tabset widget. The tabset will "pack" and manage the size and placement of pathName. The default value is "".
  • -windowheight pixels — Sets the requested height of the page. The page is the area under the tab used to display the page contents. If pixels is 0, the maximum height of all embedded tab windows is used. The default is 0.
  • -windowwidth pixels — Sets the requested width of the page. The page is the area under the tab used to display the page contents. If pixels is 0, the maximum width of all embedded tab windows is used. The default is 0.

🌈 DEFAULT BINDINGS 🌈

Bestie, BLT automatically generates class bindings that supply tabsets their default behaviors. The following event sequences are set by default for tabsets (via the class bind tag Tabset):

  • <ButtonPress-2>, <B2-Motion>, <ButtonRelease-2> — Mouse button 2 may be used for scanning. If it is pressed and dragged over the tabset, the contents of the tabset drag at high speed in the direction the mouse moves.
  • <KeyPress-Up>, <KeyPress-Down> — The up and down arrow keys move the focus to the tab immediately above or below the current focus tab. The tab with focus is drawn with a dashed outline around the tab label.
  • <KeyPress-Left>, <KeyPress-Right> — The left and right arrow keys move the focus to the tab immediately to the left or right of the current focus tab. The tab with focus is drawn with a dashed outline around the tab label.
  • <KeyPress-space>, <KeyPress-Return> — The space and return keys select the current tab given focus. When a folder is selected, its command is invoked and the embedded widget is mapped.

Each tab, by default, also has a set of bindings (via the tag all). These bindings may be reset using the tabset's bind operation.

  • <Enter>, <Leave> — When the mouse pointer enters a tab, it is activated (i.e. drawn in its active colors) and when the pointer leaves, it is redrawn in its normal colors.
  • <ButtonRelease-1> — Clicking with the left mouse button on a tab causes the tab to be selected and its Tcl script (see the -command or -selectcommand options) to be invoked. The folder and any embedded widget (if one is specified) is automatically mapped.
  • <ButtonRelease-3>, <Control-ButtonRelease-1> — Clicking on the right mouse button (or the left mouse button with the Control key held down) tears off the current page into its own toplevel widget. The embedded widget is re-packed into a new toplevel and an outline of the widget is drawn in the folder. Clicking again (toggling) will reverse this operation and replace the page back in the folder.

💅 BIND TAGS 💅

Okay so you can bind commands to tabs that fire when a particular event sequence happens in them — lowkey the same energy as canvas items in Tk's canvas widget. But bestie, not all event sequences are valid. The only binding events you're allowed to specify are the mouse-and-keyboard ones, like Enter, Leave, ButtonPress, Motion, and KeyPress. That's the whole vibe check.

Multiple bindings can match one event, which is exactly the kind of chaos that happens when one binding is tied to the tab name and another is tied to the tab's tags (peep the -bindtags option). When that happens, all the matching bindings get invoked — no picking favorites. The binding associated with the tab name runs first, then one binding for each of the tab's bindtags. If there are multiple matching bindings for a single tag, only the most specific binding is invoked. A continue command in a binding script terminates that script, and a break command terminates that script and skips any remaining scripts for the event — just like for the bind command. Periodt.

The -bindtags option for tabs controls additional tag names that can be matched. Implicitly, the first tag for each tab is its name. Setting the value of the -bindtags option doesn't change this — it's giving “iconic rule stays iconic.”

Note: the <<TabsetTearoff>> virtual event is generated on tearoff, and the <<TabsetSelect>> virtual event is generated on selection. 💫

🦋 EXAMPLE 🦋

You create a tabset widget with the tabset command. It's giving main character energy from the very first line:

# Create a new tabset
tabset .ts -relief sunken -borderwidth 2

A new Tcl command .ts is also created. This command can be used to query and modify the tabset. For example, to change the default font used by all the tab labels, you use the new command and the tabset's configure operation:

# Change the default font.
.ts configure -font "fixed"

Then you can add folders using the insert operation. Look at her go:

# Create a new folder "f1"
.ts insert 0 "f1"

This inserts the new tab named "f1" into the tabset. The index 0 indicates the location to insert the new tab. You can also use the index end to append a tab to the end of the tabset. By default, the text of the tab is the name of the tab — cute, but maybe not the vibe you want. You can change this by configuring the -text option:

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

The insert operation lets you add one or more folders at a time, bestie:

.ts insert end "f2" -text "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 tabset widget. Using the -window option, you specify the name of the widget to be embedded. But don't pack the widget — the tabset takes care of placing and arranging the widget for you. No cap.

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 to override this. Iconic.

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. It's giving magical little tab portal. ✨

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 tabset'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 tabset will automatically let you scroll the tabs. You can even attach a scrollbar to the tabset:

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

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

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

🎀 KEYWORDS 🎀

tabset, widget — that's the keyword lineup, bestie. 💅

Okay that’s the whole page, babes 💖 — footer sign-off deets: source/version BLT 2.5, page tabset(n), and the date as printed on the page. Go be iconic with your tabs. 🫶

📦 where this page comes from
  • nixpkgs unstable: blt 2.5.3
  • Copyright 1998 by Bell Labs Innovations for Lucent Technologies
  • 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms