options(n)

📦
version 9.0.3 · 5 versions
, in alpine 3.23, alpine 3.24, fedora 43, fedora 44, nixos 26.05

✨ options(n) — Tk Built-In Commands ✨

okay bestie, buckle up — this is the manual page for options, from the Tk Built-In Commands corner of the universe. it's the master list of the standard configuration options that widgets in the Tk toolkit support. 💅 grab a snack, this one's a long one.

🌸 NAME 🌸

options — the standard options that widgets support, like, all of them 💖

🎀 DESCRIPTION 🎀

so this little entry describes the common configuration options supported by widgets in the Tk toolkit. real talk: not every widget supports every single option — check the manual entries for each individual widget if you wanna know exactly which standard options that widget rocks. but the rule is sacred: if a widget does support an option with one of the names listed down below, then that option does exactly what's described here. no cap. ✨

now, quick vocab check before we go, because these three labels show up for every single option and you're gonna see them a LOT:

  • "Command-Line Name" — this is the switch you use in class commands and configure widget commands to set the value. like, say an option's command-line switch is -foreground and you've got a widget .a.b.c — then you can run this:
.a.b.c configure -foreground black

and boom, you've set the value black for the option in the widget .a.b.c. 🫶 command-line switches can be abbreviated as long as the abbreviation is unambiguous (so don't get cute and make it vague, bestie).

  • "Database Name" — the option's name in the option database (think .Xdefaults files, iykyk).
  • "Database Class" — the option's class value in the option database.

cool? cool. let's go, one option at a time. 🦋

💜 the options themselves 💜

Command-Line Name:-activebackground
Database Name:  activeBackground
Database Class: Foreground

Specifies the background color to use when drawing active elements. and what even is an active element? it's an element (a widget, or a portion of a widget) that counts as active if the mouse cursor is sitting over it and pressing a mouse button would cause some action to happen. ✨

⚠️ but here's the catch: if strict Motif compliance has been requested by setting the tk_strictMotif variable, this option will normally be ignored and the normal background color gets used instead. also, for some elements on Windows and Macintosh systems, the active color only gets used while mouse button 1 is pressed over the element. so specific 😭
Command-Line Name:-activeborderwidth
Database Name:  activeBorderWidth
Database Class: BorderWidth

Specifies a non-negative value indicating the width of the 3-D border drawn around active elements. see above for the whole definition of active elements 👆 the value can be in any of the forms acceptable to Tk_GetPixels. this option is typically only available in widgets that display more than one element at a time — like, menus yes, buttons no. 🎀

Command-Line Name:-activeforeground
Database Name:  activeForeground
Database Class: Background

Specifies the foreground color to use when drawing active elements. see above for the definition of active elements. that's it, that's the whole thing 🫶

Command-Line Name:-activerelief
Database Name:  activeRelief
Database Class: Relief

Specifies the 3-D effect you want for the active item of the widget. head down to the -relief option for the details, bestie — it's all explained there 💅

Command-Line Name:-anchor
Database Name:  anchor
Database Class: Anchor

Specifies how the info inside a widget (text, a bitmap, whatever) gets displayed inside that widget. must be one of these values: n, ne, e, se, s, sw, w, nw, or center. 🌈

like, for example: nw means display the info so its top-left corner is at the top-left corner of the widget. iconic compass behavior, honestly 🧭

Command-Line Name:-background or -bg
Database Name:  background
Database Class: Background

Specifies the normal background color to use when displaying the widget. simple, slay, done. 💖

Command-Line Name:-bitmap
Database Name:  bitmap
Database Class: Bitmap

Specifies a bitmap to display in the widget, in any of the forms acceptable to Tk_GetBitmap. the exact way the bitmap shows up may be affected by other options — hi -anchor and -justify 👋

typically, if you specify this option it overrides other options that specify a textual value to display in the widget — but that's controlled by the -compound option. also: you can reset -bitmap to an empty string to re-enable a text display. 🔁

and in widgets that support both -bitmap and -image, -image will usually override -bitmap. fight fight fight, but -image wins 💀

Command-Line Name:-borderwidth or -bd
Database Name:  borderWidth
Database Class: BorderWidth

Specifies a non-negative value indicating the width of the 3-D border drawn around the outside of the widget (if such a border is being drawn at all — the -relief option typically decides that). this value may also be used when drawing 3-D effects in the interior of the widget. any of the forms acceptable to Tk_GetPixels works here. ✨

Command-Line Name:-cursor
Database Name:  cursor
Database Class: Cursor

Specifies the mouse cursor to use for the widget. value can be any of the forms acceptable to Tk_GetCursor. plus: if you give it an empty string, that means the widget should defer to its parent for cursor specification. "mom, what cursor are we using" energy 🙈

Command-Line Name:-compound
Database Name:  compound
Database Class: Compound

Specifies if the widget should display text AND bitmaps/images at the same time — and if so, where the bitmap/image goes relative to the text. must be one of: none, bottom, top, left, right, or center. 💫

for example:

  • the default value none specifies that the bitmap or image should (if defined) be displayed instead of the text
  • left specifies the bitmap or image should be displayed to the left of the text
  • center specifies the bitmap or image should be displayed on top of the text

choose your fighter, bestie 🎀

Command-Line Name:-disabledforeground
Database Name:  disabledForeground
Database Class: DisabledForeground

Specifies the foreground color to use when drawing a disabled element. but here's the cute little twist: if this option is specified as an empty string (which is typically the case on monochrome displays), disabled elements get drawn with the normal foreground color — except they're dimmed by drawing them with a stippled fill pattern. retro 💀

Command-Line Name:-exportselection
Database Name:  exportSelection
Database Class: ExportSelection

Specifies whether or not a selection in the widget should also be the X selection. the value can be any of the forms accepted by Tcl_GetBoolean — like true, false, 0, 1, yes, or no.

so if the selection is exported:

  • selecting in the widget deselects the current X selection
  • selecting outside the widget deselects any widget selection
  • and the widget will respond to selection retrieval requests when it has a selection ✨

the default is usually for widgets to export selections. sharing is caring 🫶

Command-Line Name:-font
Database Name:  font
Database Class: Font

Specifies the font to use when drawing text inside the widget. the value can be any of the forms described in the font manual page under FONT DESCRIPTION. go read that one too, bestie, it's a whole vibe 🌸

Command-Line Name:-foreground or -fg
Database Name:  foreground
Database Class: Foreground

Specifies the normal foreground color to use when displaying the widget. yes, the other half of -background. the duo. the OTP. 💜

Command-Line Name:-highlightbackground
Database Name:  highlightBackground
Database Class: HighlightBackground

Specifies the color to display in the traversal highlight region when the widget does not have the input focus. so like, the unbothered, not-famous-yet state of the highlight 🎀

Command-Line Name:-highlightcolor
Database Name:  highlightColor
Database Class: HighlightColor

Specifies the color to use for the traversal highlight rectangle that gets drawn around the widget when it has the input focus. main character moment. 👑

Command-Line Name:-highlightthickness
Database Name:  highlightThickness
Database Class: HighlightThickness

Specifies a non-negative value indicating the width of the highlight rectangle drawn around the outside of the widget when it has the input focus. any of the forms acceptable to Tk_GetPixels works. and if the value is zero, no focus highlight is drawn around the widget at all. ✨

Command-Line Name:-image
Database Name:  image
Database Class: Image

Specifies an image to display in the widget — which must have been created with the image create command, no impostors allowed. 🦋

typically, if -image is specified it overrides other options that specify a bitmap or textual value to display in the widget, though this is controlled by the -compound option. and -image may be reset to an empty string to re-enable a bitmap or text display. 🔁

Command-Line Name:-insertbackground
Database Name:  insertBackground
Database Class: Foreground

Specifies the color to use as the background in the area covered by the insertion cursor. this color will normally override either the normal background of the widget — or the selection background, if the insertion cursor happens to fall inside the selection. it said "excuse me, my area, my color" 💅

Command-Line Name:-insertborderwidth
Database Name:  insertBorderWidth
Database Class: BorderWidth

Specifies a non-negative value indicating the width of the 3-D border drawn around the insertion cursor. any of the forms acceptable to Tk_GetPixels. 🎀

Command-Line Name:-insertofftime
Database Name:  insertOffTime
Database Class: OffTime

Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should stay “off” in each blink cycle. and if this option is zero, the cursor does not blink at all — it's on all the time. permanent main character energy. 😭

Command-Line Name:-insertontime
Database Name:  insertOnTime
Database Class: OnTime

Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should stay “on” in each blink cycle. the other half of the blink duo 🫶

Command-Line Name:-insertwidth
Database Name:  insertWidth
Database Class: InsertWidth

…and that's exactly where our page cuts off, bestie! 😭 the -insertwidth header is here but the description is coming in part 2 — do NOT panic, we're literally mid-sentence, not done. stay tuned ✨💖

  • -insertwidth — this one sets the total width of the insertion cursor, and it's gotta be non-negative. Any form that Tk_GetPixels accepts works here. Little detail that lowkey matters: if you've given the insertion cursor a border (that's the -insertborderwidth option, hi bestie 👋), that border gets drawn inside the width you set with -insertwidth, not outside. So the width stays the width. Periodt. 💅
  • -jump — database name jump, class Jump. For widgets with a slider you can drag to adjust a value (scrollbars, you know the ones), this decides when the widget tells you the value changed. The value has to be a boolean, in the form Tcl_GetBoolean accepts.
    • false → updates happen continuously while you drag the slider. Live. Nonstop. Very main character. 🔥
    • true → updates are delayed until you let go of the mouse button and the drag ends; at that point one single notification is made. That's literally why it's called jump — the value jumps instead of sliding smooth. 🦘
  • -justify — database name justify, class Justify. When a widget shows multiple lines of text, this says how those lines line up with each other. Has to be one of left, center, or right.
    • left → all the left edges line up
    • center → all the line centers are aligned
    • right → all the right edges line up

Alignment is a vibe, not a look ✨

  • -orient — database name orient, class Orient. For widgets that can lay themselves out either horizontal or vertical (scrollbars, iconic), this picks which orientation to use. Must be either horizontal or vertical, or an abbreviation of one of those. iykyk 🎀
  • -padx — database name padX, class Pad (yes, capital X, don't come for her). Specifies a non-negative value for how much extra space to request for the widget in the X-direction. The value can be any of the forms acceptable to Tk_GetPixels.

When the widget is computing how large a window it needs, it adds this amount to the width it would normally need (which is determined by the width of the things displayed inside it). If the geometry manager can satisfy that request, the widget ends up with extra internal space to the left and/or right of what it displays inside.

Most widgets only use this option for padding text: if they're displaying a bitmap or image, they usually just ignore padding options. Ignored. Not seen. 💀

  • -pady — database name padY, class Pad. The Y-direction twin of -padx, fr fr. Non-negative value indicating how much extra space to request for the widget in the Y-direction, in any of the forms acceptable to Tk_GetPixels.

When computing how large a window it needs, the widget adds this amount to the height it would normally need (as determined by the height of the things displayed inside it). If the geometry manager can satisfy it, the widget gets extra internal space above and/or below what it displays inside.

Same disclaimer as padx: most widgets only use this for padding text, and if they're showing a bitmap or image, they usually ignore padding options entirely. 🙈

  • -placeholder — database name placeHolder, class PlaceHolder. Specifies a help text string to display if no text is otherwise displayed — basically when the widget is empty. Empty widget, placeholder steps in and does its lil moment. 🌸 The placeholder text is displayed using the values of the -font and -justify options.
  • -placeholderforeground — database name placeholderForeground, class PlaceholderForeground. Specifies the foreground color to use when the placeholder text is displayed. The default color is platform-specific — so it's giving ✨wherever you're running✨, don't hardcode a vibe.
  • -relief — database name relief, class Relief. Specifies the 3-D effect desired for the widget. Acceptable values are raised, sunken, flat, ridge, solid, and groove. The value says how the interior of the widget should appear relative to its exterior — for example, raised means the interior should look like it's protruding out of the screen relative to the exterior. Depth, but make it fashion. 💅
  • -repeatdelay — database name repeatDelay, class RepeatDelay. Specifies the number of milliseconds a button or key must be held down before it starts to auto-repeat. Used, for example, on the up- and down-arrows in scrollbars. Hold… hold… and go. ⏱️
  • -repeatinterval — database name repeatInterval, class RepeatInterval. BFFs with -repeatdelay: once auto-repeat has begun, this option determines the number of milliseconds between each auto-repeat. So delay is the wait, interval is the rhythm. 🎵
  • -selectbackground — database name selectBackground, class Foreground. Specifies the background color to use when displaying selected items. (And yes, the class really is Foreground while the option is a background — that's just how she is, no notes. 😭)
  • -selectborderwidth — database name selectBorderWidth, class BorderWidth. Specifies a non-negative value indicating the width of the 3-D border drawn around selected items. The value may have any of the forms acceptable to Tk_GetPixels.
  • -selectforeground — database name selectForeground, class Background. Specifies the foreground color to use when displaying selected items. (Class is Background this time. They're swapped besties. It's a whole thing. 🫶)
  • -setgrid — database name setGrid, class SetGrid. A boolean that decides whether this widget controls the resizing grid for its top-level window.

This is typically used in text widgets, where the info in the widget has a natural size (the size of a character) and it makes sense for the window's dimensions to be integral numbers of those units. Those natural window sizes form a grid.

If -setgrid is true, then the widget communicates with the window manager so that when the user interactively resizes the top-level window containing the widget, the window's dimensions are displayed to the user in grid units, and the window size is constrained to integral numbers of grid units. Slay, snapped to the grid. 📐

See the section GRIDDED GEOMETRY MANAGEMENT in the wm manual entry for more details.
  • -takefocus — database name takeFocus, class TakeFocus. Determines whether the window accepts the focus during keyboard traversal (e.g. Tab and Shift-Tab). Before setting focus to a window, the traversal scripts consult the value of the -takefocus option.
    • 0 → the window should be skipped entirely during keyboard traversal. Not invited to the party. 💀
    • 1 → the window should receive the input focus as long as it's viewable (meaning it and all of its ancestors are mapped).
    • an empty value → the traversal scripts make the decision about whether or not to focus the window. The current algorithm is to skip the window if it's disabled, if it has no key bindings, or if it's not viewable.
    • any other form → the traversal scripts take the value, append the name of the window to it (with a separator space), and evaluate the resulting string as a Tcl script. That script must return 0, 1, or an empty string: 0 or 1 says whether the window receives the input focus, and an empty string gets you the default decision described above.
Big note, no cap: this interpretation of the option is defined entirely by the Tcl scripts that implement traversal. The widget implementations ignore the option entirely — so you can literally change its meaning if you redefine the keyboard traversal scripts. Your house, your rules. 👑
  • -text — database name text, class Text. Specifies a string to be displayed inside the widget. How that string actually gets displayed depends on the particular widget, and may be determined by other options too, like -anchor or -justify.
  • -textvariable — database name textVariable, class Variable. Specifies the name of a global variable. The value of that variable is a text string to be displayed inside the widget; if the variable's value changes, the widget automatically updates itself to reflect the new value. Iconic behaviour honestly. 🌈

And same as -text: how the string is displayed depends on the particular widget, and may be determined by other options such as -anchor or -justify.

  • -troughcolor — database name troughColor, class Background. Specifies the color to use for the rectangular trough areas in widgets like scrollbars and scales. 🛁
Heads up: this option is ignored for scrollbars on Windows — the native widget does not recognize this option. So on Windows, she simply does not see it. 🪟
  • -underline — database name underline, class Underline. Specifies the integer index of a character to underline in the widget. This option is used by the default bindings to implement keyboard traversal for menu buttons and menu entries.
    • 0 corresponds to the first character of the text displayed in the widget, 1 to the next character, and so on.
    • end gets you the last character, end-1 the one before last, and so on down the line. ✨
  • -wraplength — database name wrapLength, class WrapLength. For widgets that can do word-wrapping, this specifies the maximum line length. Lines that would go past this length get wrapped onto the next line, so no line ends up longer than the length you specified. The value can be given in any of the standard forms for screen distances.
If this value is negative or zero, then no wrapping is done: lines will break only at newline characters in the text. Respect the newline, and only the newline. 🚫📏
  • -xscrollcommand — database name xScrollCommand, class ScrollCommand

...so the first fraction is literally telling you where the visible bit starts in the document, and the second one is pointing at the info right after the last visible portion. Then the whole command gets handed off to the Tcl interpreter to run. Normally your -xscrollcommand is just the path name of a scrollbar widget with set tacked on the end, like .x.scrollbar set — and that's what makes the scrollbar update every time the view in the window changes. And if you don't specify this option at all? No command runs. Nothing happens. It's giving silent treatment. 💅

  • -yscrollcommand — the exact same energy, but vertical. 🌈
Command-Line Name: -yscrollcommand
Database Name:     yScrollCommand
Database Class:    ScrollCommand

It specifies the prefix for a command that talks to vertical scrollbars. This option is treated the same way as -xscrollcommand, except it's the one for vertical scrollbars and it comes from widgets that support vertical scrolling. For the full rundown on how it actually works, go look at the -xscrollcommand description above — same rules, just rotated 90 degrees. 🦋

💖 SEE ALSO 💖

colors, cursors, font

🎀 KEYWORDS 🎀

class, name, standard option, switch

okay bestie that's the whole page, you made it to the end, I'm so proud of you 🫶 this was the Tk manual page for options(n), version 4.4 — no cap, that's the version and the page name right there in the footer, so you always know which vintage of Tk you're reading. now go make some widgets iconically pretty ✨👑💜

📦 where this page comes from