ttk::notebook(3tk)

📦
version 9.0.4 · 6 versions
, in ubuntu stonking

💖 ttk::notebook — from the ttk::notebook(3tk) manual, Tk Themed Widget, bestie edition 💖

okay so. sit down. hydrate. because this widget is a whole vibe and you're gonna be obsessed.

✨ NAME ✨

ttk::notebook — the multi-paned container widget. it's giving "binder full of tabs," it's giving "one thing visible at a time," it's iconic.

✨ SYNOPSIS ✨

ttk::notebook pathname ?options...?
pathname add window ?options...?
pathname insert index window ?options...?

🦋 DESCRIPTION 🦋

A ttk::notebook widget manages a collection of windows and shows exactly one of them at a time. no cap. each content window gets paired up with a tab, and the user can click that tab to swap which window is currently the main character on screen.

so like: many windows, one spotlight. the way that it just… rotates them. 💅

🌸 STANDARD OPTIONS 🌸

  • -class
  • -cursor
  • -takefocus
  • -style

these are the regulars, the ones every themed widget shows up with. for the full tea on what each one does, go read the ttk_widget manual entry. i'm not about to re-explain stuff that's already slaying elsewhere.

🎀 WIDGET-SPECIFIC OPTIONS 🎀

these are the options this widget brought to the party specifically.

  • -height — Command-Line Name: -height; Database Name: height; Database Class: Height.

if you pass it and it's greater than zero, it sets the height you want for the pane area — and lowkey important: that's not counting internal padding or tabs. if you don't pass it (or it's not > 0), the height used is the maximum height across all the panes.

  • -padding — Command-Line Name: -padding; Database Name: padding; Database Class: Padding.

how much extra space to add around the outside of the notebook. it's a list of up to four length specifications, in this order: left top right bottom. if you give fewer than four, the defaults kick in: bottom defaults to top, right defaults to left, and top defaults to left. so, translated:

  • three numbers → left, vertical, right padding
  • two numbers → horizontal and vertical padding
  • one number → same padding all the way around the widget 🫶
  • -width — Command-Line Name: -width; Database Name: width; Database Class: Width.

if you pass it and it's greater than zero, it sets the width you want for the pane area (again, not including internal padding). otherwise, the width used is the maximum width of all the panes.

🌈 TAB OPTIONS 🌈

these are the options you can set on individual notebook panes. per-tab customization, we love to see it.

  • -state — Command-Line Name: -state; Database Name: state; Database Class: State.

one of normal, disabled or hidden. if it's disabled, the tab can't be selected. if it's hidden, the tab isn't shown at all. 🙈

  • -sticky — Command-Line Name: -sticky; Database Name: sticky; Database Class: Sticky.

how the content window sits inside the pane area. the value is a string with zero or more of the characters n, s, e, or w. each letter means a side — north, south, east, or west — and the content window will "stick" to that side, exactly like the grid geometry manager does it.

  • -padding — Command-Line Name: -padding; Database Name: padding; Database Class: Padding.

how much extra space to add between the notebook and this specific pane. syntax works the same as the widget's -padding option. same rules, smaller scale.

  • -text — Command-Line Name: -text; Database Name: text; Database Class: Text.

the string shown in the tab. the label. the name tag. 🎀

  • -image — Command-Line Name: -image; Database Name: image; Database Class: Image.

an image to display in the tab. head to ttk_widget(3tk) for the details on that one.

  • -compound — Command-Line Name: -compound; Database Name: compound; Database Class: Compound.

when both -text and -image are present, this says how the image is displayed relative to the text. label(3tk) has the legal values, go check it.

  • -underline — Command-Line Name: -underline; Database Name: underline; Database Class: Underline.

the integer index (0-based, bestie, don't forget) of a character to underline in the text string. and here's why that matters: that underlined character is the one used for mnemonic activation if ttk::notebook::enableTraversal gets called. so yes, the underline is doing actual work.

💜 TAB IDENTIFIERS 💜

the tabid argument to the commands below can take any of these forms:

  • an integer between zero and the number of tabs;
  • the name of a content window;
  • a positional specification of the form @x,y, which identifies the tab;
  • the literal string current, which identifies the currently-selected tab; or:
  • the literal string end, which returns the number of tabs (only valid for pathname index).

indexes support the same simple interpretation as for the command string index, with simple integer index arithmetic and indexing relative to end. so yes, you can do math on them. periodt. ✨

👑 WIDGET COMMAND 👑

on top of the standard cget, configure, instate, state and style commands (peep ttk::widget for those), notebook widgets also support these extra commands:

  • pathname add window ?options...? — adds a new tab to the notebook. the list of available options lives in TAB OPTIONS. if window is currently managed by the notebook but hidden, it gets restored to its previous position. glow-up, reclaimed. 🫶
  • pathname forget tabid — removes the tab specified by tabid, and unmaps and unmanages the associated window. gone gone.
  • pathname hide tabid — hides the tab specified by tabid. the tab isn't displayed, but hear me out: the associated window stays managed by the notebook and its configuration is remembered. hidden tabs can be brought back with the add command. it's not a goodbye, it's a pause. 💅
  • pathname identify component x y — returns the name of the element under the point given by x and y, or the empty string if there's no component at that location. the following subcommands are supported:
    • pathname identify element x y — returns the name of the element at the specified location.
    • pathname identify tab x y — returns the index of the tab at the specified location.
  • pathname index tabid — returns the numeric index of the tab specified by tabid, or the total number of tabs if tabid is the string end.
  • pathname insert pos subwindow options... — inserts a pane at the specified position. pos is either the string end, an integer index, or the name of a managed subwindow. if subwindow is already managed by the notebook, it gets moved to the specified position. see TAB OPTIONS for the list of available options.
  • pathname select ?tabid? — selects the specified tab. the associated content window gets displayed, and the previously-selected window (if it's a different one) is unmapped. if you omit tabid, it returns the widget name of the currently selected pane. ✨
  • pathname tab tabid ?-option ?value ... — query or modify the options of a specific tab. if you pass no -option, you get back a dictionary of the tab's option values. if you pass one -option, you get the value of that option. otherwise, it sets the -options to the corresponding values. see TAB OPTIONS for what's available.
  • pathname tabs — returns the list of windows managed by the notebook, in the index order of their associated tabs.

🧚 KEYBOARD TRAVERSAL 🧚

to turn on keyboard traversal for a toplevel window containing a notebook widget $nb, you just call:

ttk::notebook::enableTraversal $nb

this extends the bindings for the toplevel window containing the notebook, like so:

  • Control+Tab selects the tab following the currently selected one.
  • Control+Shift+Tab selects the tab preceding the currently selected one.
  • Alt+K, where K is the mnemonic (underlined) character of any tab, will select that tab.

you can enable multiple notebooks in a single toplevel for traversal, nested notebooks included. however — and this is a real one — notebook traversal only works properly if all panes are direct children of the notebook. so don't get cute with the hierarchy, bestie. 💀

⭐ VIRTUAL EVENTS ⭐

the notebook widget generates a <<NotebookTabChanged>> virtual event after a new tab is selected. so you can listen for the tab-switch moment. obsession-worthy hook, fr fr.

💖 EXAMPLE 💖

pack [ttk::notebook .nb]
.nb add [frame .nb.f1] -text "First tab"
.nb add [frame .nb.f2] -text "Second tab"
.nb select .nb.f2
ttk::notebook::enableTraversal .nb

that's a notebook, two tabs, a select, and traversal turned on. chef's kiss. 😭✨

okay that's part one, there's more coming — do not scroll away, we're not done being iconic 🌈

✨ STYLING OPTIONS ✨

okay so bestie, style o'clock. The class name for a ttk::notebook is TNotebook. The tab has a class name of TNotebook.Tab. not me knowing all the class names by heart.

Dynamic states: active, disabled, selected. that's the whole mood ring.

TNotebook styling options configurable with ttk::style are:

  • -background color — the background color. duh.
  • -bordercolor color — the border color. border tea.
  • -darkcolor color — the dark color. dark mode energy.
  • -foreground color — the foreground color. foreground tea.
  • -lightcolor color — the light color. light mode energy.
  • -padding padding — the padding. personal space, but for pixels.
  • -tabmargins padding — the tab margins. margins, but make it tab.
  • -tabposition position — Specifies the position of the tab row or column as a string of length 1 or 2. The first character indicates the side as n, s, w, or e, while the second character (if present) is the sticky bit (specified as w, e, n, or s) within the tab position. The default position is n for the aqua theme and nw for all the other built-in themes. this one is the blueprint.
  • -tabplacement placement — Specifies the placement (anchor) of the tabs within the tab row or column as a string of length 1 or 2. The first character indicates the side as w, e, n, or s, while the second character (if present) is the sticky bit (specified as s, n, e, or w) within the tab placement. For example, the tab placement ws means: attach the west (left) side of each tab to the previous one and align the south (bottom) edges with each other. Similarly, the tab placement se specifies to attach the south (bottom) side of each tab to the previous one and align the east (right) edges with each other. The default placement depends on the first character of the tab position: ws for n*, wn for s*, ne for w*, and nw for e*. the way the compass ate.

TNotebook.Tab styling options configurable with ttk::style are:

  • -background color — the background color. again, but for the tab.
  • -bordercolor color — the border color. again, but tab.
  • -compound compound — the compound setting. iykyk.
  • -expand padding — Defines how much the tab grows in size. Usually used with the selected dynamic state. -tabmargins should be set appropriately so that there is room for the tab growth. For example, the Ttk library file vistaTheme.tcl contains the lines
ttk::style configure TNotebook -tabmargins {2 2 2 0}
ttk::style map TNotebook.Tab -expand {selected {2 2 2 2}}

which are valid for the default value nw of the -tabposition style option. For a ttk::notebook style nbStyle defined by

set nbStyle SW.TNotebook
ttk::style configure $nbStyle -tabposition sw

you will have to adapt the above settings as follows:

ttk::style configure $nbStyle -tabmargins {2 0 2 2}
ttk::style map $nbStyle.Tab -expand {selected {2 2 2 2}}

The easiest way to do this is to invoke the library procedure ttk::configureNotebookStyle with $nbStyle as argument, after setting the style's -tabposition option. copy-paste with confidence, bestie.

  • -font font — the font. typography moment.
  • -foreground color — the foreground color. text tea, but tab.
  • -padding padding — Some themes use a different padding for the selected tab. For example, the Ttk library file clamTheme.tcl contains the lines
ttk::style configure TNotebook.Tab \
    -padding {4.5p 1.5p 4.5p 1.5p}
ttk::style map TNotebook.Tab \
    -padding {selected {4.5p 3p 4.5p 1.5p}}

which are valid for the default value nw of the -tabposition style option. For a ttk::notebook style having a different tab position you will have to adapt the above settings accordingly. Again, the easiest way to do this is to invoke the library procedure ttk::configureNotebookStyle with the style name as argument, after setting the style's -tabposition option. adaptive queen.

Some options are only available for specific themes.

See the ttk::style manual page for information on how to configure ttk styles.

👀 SEE ALSO 👀

🔑 KEYWORDS 🔑

  • pane
  • tab

💖 and that's a wrap! source/version: Tk 8.5, page ttk::notebook(3tk). no date on the footer, just vibes. periodt. 💅

📦 where this page comes from