options(3tk)

✨ NAME ✨

options — standard options supported by widgets. 💅

---

🌸 DESCRIPTION 🌸

Okay bestie, gather round. This man page is the master list of the common configuration options supported by widgets in the Tk toolkit. Every widget does not necessarily support every single option — if you need the receipts for a specific widget, check the manual entries for individual widgets for the list of the standard options supported by that widget. But if a widget does support an option with one of the names listed below, then that option has exactly the effect described below. Periodt. 💖

In the descriptions below, “Command-Line Name” is the switch used in class commands and configure widget commands to set this value. For example, if an option's command-line switch is -foreground and there exists a widget .a.b.c, then this command:

.a.b.c  configure  -foreground black

may be used to specify the value black for the option in the widget .a.b.c. Command-line switches may be abbreviated, as long as the abbreviation is unambiguous. “Database Name” refers to the option's name in the option database (e.g. in .Xdefaults files). “Database Class” refers to the option's class value in the option database. Slay. ✨

---

👑 OPTIONS 👑

• -activebackground — specifies the background color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. If strict Motif compliance has been requested by setting the tk_strictMotif variable, this option will normally be ignored; the normal background color will be used instead. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. 💅
  • Database Name: activeBackground
  • Database Class: Foreground
• -activeborderwidth — specifies a non-negative value indicating the width of the 3-D border drawn around active elements. See above for definition of active elements. The value may have any of the forms acceptable to Tk_GetPixels. This option is typically only available in widgets displaying more than one element at a time (e.g. menus but not buttons). ✨
  • Database Name: activeBorderWidth
  • Database Class: BorderWidth
• -activeforeground — specifies foreground color to use when drawing active elements. See above for definition of active elements. 🌸
  • Database Name: activeForeground
  • Database Class: Background
• -activerelief — specifies the 3-D effect desired for the active item of the widget. See the -relief option for details. 💖
  • Database Name: activeRelief
  • Database Class: Relief
• -anchor — specifies how the information in a widget (e.g. text or a bitmap) is to be displayed in the widget. Must be one of the values n, ne, e, se, s, sw, w, nw, or center. For example, nw means display the information such that its top-left corner is at the top-left corner of the widget. 🦋
  • Database Name: anchor
  • Database Class: Anchor
• -background or -bg — specifies the normal background color to use when displaying the widget. 🌈
  • Database Name: background
  • Database Class: Background
• -bitmap — specifies a bitmap to display in the widget, in any of the forms acceptable to Tk_GetBitmap. The exact way in which the bitmap is displayed may be affected by other options such as -anchor or -justify. Typically, if this option is specified then it overrides other options that specify a textual value to display in the widget but this is controlled by the -compound option; the -bitmap option may be reset to an empty string to re-enable a text display. In widgets that support both -bitmap and -image options, -image will usually override -bitmap. 👑
  • Database Name: bitmap
  • Database Class: Bitmap
• -borderwidth or -bd — specifies a non-negative value indicating the width of the 3-D border to draw around the outside of the widget (if such a border is being drawn; the -relief option typically determines this). The value may also be used when drawing 3-D effects in the interior of the widget. The value may have any of the forms acceptable to Tk_GetPixels. 💅
  • Database Name: borderWidth
  • Database Class: BorderWidth
• -cursor — specifies the mouse cursor to be used for the widget. The value may have any of the forms acceptable to Tk_GetCursor. In addition, if an empty string is specified, it indicates that the widget should defer to its parent for cursor specification. ✨
  • Database Name: cursor
  • Database Class: Cursor
• -compound — specifies if the widget should display text and bitmaps/images at the same time, and if so, where the bitmap/image should be placed relative to the text. Must be one of the values 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, the value left specifies that the bitmap or image should be displayed to the left of the text, and the value center specifies that the bitmap or image should be displayed on top of the text. 🌸
  • Database Name: compound
  • Database Class: Compound
• -disabledforeground — specifies foreground color to use when drawing a disabled element. If the option is specified as an empty string (which is typically the case on monochrome displays), disabled elements are drawn with the normal foreground color but they are dimmed by drawing them with a stippled fill pattern. 💀
  • Database Name: disabledForeground
  • Database Class: DisabledForeground
• -exportselection — specifies whether or not a selection in the widget should also be the X selection. The value may have any of the forms accepted by Tcl_GetBoolean, such as true, false, 0, 1, yes, or no. If the selection is exported, then 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. 🫶
  • Database Name: exportSelection
  • Database Class: ExportSelection
• -font — specifies the font to use when drawing text inside the widget. The value may have any of the forms described in the font manual page under FONT DESCRIPTION. 🔥
  • Database Name: font
  • Database Class: Font
• -foreground or -fg — specifies the normal foreground color to use when displaying the widget. 💜
  • Database Name: foreground
  • Database Class: Foreground
• -highlightbackground — specifies the color to display in the traversal highlight region when the widget does not have the input focus. 🌈
  • Database Name: highlightBackground
  • Database Class: HighlightBackground
• -highlightcolor — specifies the color to use for the traversal highlight rectangle that is drawn around the widget when it has the input focus. ✨
  • Database Name: highlightColor
  • Database Class: HighlightColor
• -highlightthickness — specifies a non-negative value indicating the width of the highlight rectangle to draw around the outside of the widget when it has the input focus. The value may have any of the forms acceptable to Tk_GetPixels. If the value is zero, no focus highlight is drawn around the widget. 💅
  • Database Name: highlightThickness
  • Database Class: HighlightThickness
• -image — specifies an image to display in the widget, which must have been created with the image create command. Typically, if the -image option is specified then it overrides other options that specify a bitmap or textual value to display in the widget, though this is controlled by the -compound option; the -image option may be reset to an empty string to re-enable a bitmap or text display. 👑
  • Database Name: image
  • Database Class: Image
• -insertbackground — specifies the color to use as background in the area covered by the insertion cursor. This color will normally override either the normal background for the widget (or the selection background if the insertion cursor happens to fall in the selection). 🎀
  • Database Name: insertBackground
  • Database Class: Foreground
• -insertborderwidth — specifies a non-negative value indicating the width of the 3-D border to draw around the insertion cursor. The value may have any of the forms acceptable to Tk_GetPixels. ✨
  • Database Name: insertBorderWidth
  • Database Class: BorderWidth
• -insertofftime — specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain “off” in each blink cycle. If this option is zero then the cursor does not blink: it is on all the time. 😭
  • Database Name: insertOffTime
  • Database Class: OffTime
• -insertontime — specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain “on” in each blink cycle. 🔥
  • Database Name: insertOnTime
  • Database Class: OnTime
• -insertwidth
  • Database Name: insertWidth
  • Database Class: InsertWidth

Specifies a non-negative value indicating the total width of the insertion cursor. The value may have any of the forms acceptable to Tk_GetPixels. If a border has been specified for the insertion cursor (using the -insertborderwidth option), the border will be drawn inside the width specified by the -insertwidth option. 💅

---

• -jump — Command-Line Name: -jump · Database Name: jump · Database Class: Jump
  • For widgets rockin' a slider you can drag around to adjust a value (scrollbars, hi bestie 🫶), this option decides when you get notified about value changes. Its value has to be a boolean of the form Tcl_GetBoolean accepts. If it's false, updates happen continuously while you drag the slider. If it's true, the updates get delayed until you release the mouse button and the drag ends — and at that exact moment one single notification drops, so the value literally "jumps" instead of sliding smoothly. no cap ✨
• -justify — Command-Line Name: -justify · Database Name: justify · Database Class: Justify
  • When a widget is showing multiple lines of text, this option says how those lines line up with each other. Gotta be one of left, center, or right. left means all the left edges line up, center means the centers are aligned, and right means the right edges line up. it's giving ✨alignment✨
• -orient — Command-Line Name: -orient · Database Name: orient · Database Class: Orient
  • For widgets that can lay themselves out either horizontally or vertically (scrollbars, looking at you 👀), this one picks which orientation gets used. Must be either horizontal or vertical, or an abbreviation of one of those two. 💫
• -padx — Command-Line Name: -padx · Database Name: padX · Database Class: Pad
  • Specifies a non-negative value for how much extra space to request for the widget in the X-direction. Value can be in any form Tk_GetPixels accepts. When the widget is figuring out how big a window it needs, it adds this amount to the width it would normally need (that width coming from the things displayed inside it); if the geometry manager can actually satisfy that request, the widget ends up with extra internal space to the left and/or right of what it's displaying. Most widgets only use this for padding text: if they're showing a bitmap or an image, they usually just ignore the padding options entirely. 🙈
• -pady — Command-Line Name: -pady · Database Name: padY · Database Class: Pad
  • Specifies a non-negative value for how much extra space to request for the widget in the Y-direction. Value can be in any form Tk_GetPixels accepts. When the widget is computing how big a window it needs, it adds this amount to the height it would normally need (determined by the height of the stuff displayed inside it); if the geometry manager can satisfy that request, the widget ends up with extra internal space above and/or below what it's displaying. Most widgets only use this for padding text: if they're showing a bitmap or image, they usually ignore the padding options. same energy as -padx fr fr 🦋
• -placeholder — Command-Line Name: -placeholder · Database Name: placeHolder · Database Class: PlaceHolder
  • Specifies a help-text string to display when no text is otherwise being displayed — i.e. when the widget is empty. That placeholder text gets rendered using the values of the -font and -justify options. so cute 🎀
• -placeholderforeground — Command-Line Name: -placeholderforeground · Database Name: placeholderForeground · Database Class: PlaceholderForeground
  • Specifies the foreground color to use while the placeholder text is being displayed. The default color is platform-specific — so don't come for me, it depends on your setup 💅
• -relief — Command-Line Name: -relief · Database Name: relief · Database Class: Relief
  • Specifies the 3-D effect the widget should have. Acceptable values are raised, sunken, flat, ridge, solid, and groove. The value says how the interior of the widget should look compared to its exterior; for example, raised means the inside of the widget should appear to pop out from the screen relative to the outside of the widget. main character energy honestly 👑
• -repeatdelay — Command-Line Name: -repeatdelay · Database Name: repeatDelay · Database Class: RepeatDelay
  • Specifies the number of milliseconds a button or key has to be held down before it starts to auto-repeat. Used, for example, on the up- and down-arrows in scrollbars. ⏱️
• -repeatinterval — Command-Line Name: -repeatinterval · Database Name: repeatInterval · Database Class: RepeatInterval
  • Used together with -repeatdelay: once auto-repeat kicks off, this option sets the number of milliseconds between each auto-repeat. the duo we didn't know we needed 🫶
• -selectbackground — Command-Line Name: -selectbackground · Database Name: selectBackground · Database Class: Foreground
  • Specifies the background color to use when displaying selected items. 🌈
• -selectborderwidth — Command-Line Name: -selectborderwidth · Database Name: selectBorderWidth · Database Class: BorderWidth
  • Specifies a non-negative value indicating the width of the 3-D border to draw around selected items. The value may take any of the forms acceptable to Tk_GetPixels. ✨
• -selectforeground — Command-Line Name: -selectforeground · Database Name: selectForeground · Database Class: Background
  • Specifies the foreground color to use when displaying selected items. 💜
• -setgrid — Command-Line Name: -setgrid · Database Name: setGrid · Database Class: SetGrid
  • Specifies a boolean value that decides whether this widget controls the resizing grid for its top-level window. This option is typically used in text widgets, where the info in the widget has a natural size (the size of a character) and it just 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, the widget talks to the window manager so that when the user interactively resizes the top-level window containing the widget, the window's dimensions get displayed to the user in grid units and the window size gets constrained to integral numbers of grid units. Peep the section GRIDDED GEOMETRY MANAGEMENT in the wm manual entry for more details. 🦋
• -takefocus — Command-Line Name: -takefocus · Database Name: takeFocus · Database Class: TakeFocus
  • Decides whether the window accepts the focus during keyboard traversal (think Tab and Shift-Tab). Before focusing a window, the traversal scripts check the value of the -takefocus option. A value of 0 means the window should be skipped entirely during keyboard traversal. 1 means the window should receive the input focus as long as it's viewable (it and all of its ancestors are mapped). An empty value means the traversal scripts make the call themselves on 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. If the value is any other form, the traversal scripts take that 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 will receive the input focus, and an empty string falls back to the default decision described above. Heads up bestie — this interpretation of the option is defined entirely by the Tcl scripts that implement traversal: the widget implementations ignore the option completely, so you can change what it means if you redefine the keyboard traversal scripts. 💀

iykyk: the widgets themselves literally do not care about this option. it's all the scripts, periodt.

• -text — Command-Line Name: -text · Database Name: text · Database Class: Text
  • Specifies a string to display inside the widget. How that string gets displayed depends on the particular widget, and may also be decided by other options like -anchor or -justify. 🌸
• -textvariable — Command-Line Name: -textvariable · Database Name: textVariable · Database 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 show the new value. How the string is displayed in the widget depends on the particular widget and may be decided by other options like -anchor or -justify. not me being obsessed with a live-updating variable 🫶
• -troughcolor — Command-Line Name: -troughcolor · Database Name: troughColor · Database Class: Background
  • Specifies the color to use for the rectangular trough areas in widgets like scrollbars and scales. This option is ignored for scrollbars on Windows (the native widget doesn't recognize this option). 💀
• -underline — Command-Line Name: -underline · Database Name: underline · Database Class: Underline
  • Specifies the integer index of a character to underline in the widget. This option is what the default bindings use 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 corresponds to the last character, end-1 to the one before last, and so on. 🎀
• -wraplength — Command-Line Name: -wraplength · Database Name: wrapLength · Database Class: WrapLength
  • For widgets that can do word-wrapping, this option specifies the maximum line length. Lines that would exceed that length get wrapped onto the next line, so no line ends up longer than the length you specified. The value may be given in any of the standard forms for screen distances. If the value is negative or zero then no wrapping happens at all: lines break only at newline characters in the text. 🌈
• -xscrollcommand — Command-Line Name: -xscrollcommand · Database Name: xScrollCommand · Database Class: ScrollCommand

...and that's exactly where this part hands things off 💅

Specifies the prefix for a command used to talk to horizontal scrollbars. 🎀

So here's the vibe: whenever the view in the widget's window changes — or literally anything else happens that could change what a scrollbar is showing, like when the total size of the widget's contents changes — the widget rolls up a Tcl command by gluing the scroll command together with two numbers. ✨

Each of those numbers is a fraction between 0 and 1, and it tells you a position in the document:

• 0 = the very beginning of the document 🍼
• 1 = the end, periodt 🏁
• .333 = a position one third of the way through the document
• and so on, you get the math bestie 💅

The first fraction is the first information in the document that's visible in the window, and the second fraction is the information just after the last portion that's visible. Then that command gets handed off to the Tcl interpreter to be executed. 👑

Typically the -xscrollcommand option is the path name of a scrollbar widget followed by set, e.g. .x.scrollbar set — and doing that means the scrollbar gets updated whenever the view in the window changes. Iconic behaviour honestly. 🦋

If this option isn't specified, then no command will be executed. Yeah. Nothing happens. The scrollbar's just gonna sit there. 😭

---

🫶 -yscrollcommand

• Command-Line Name: -yscrollcommand
• Database Name: yScrollCommand
• Database Class: ScrollCommand

Specifies the prefix for a command used to communicate with vertical scrollbars. Same treatment as the -xscrollcommand option in every way, except this one is for vertical scrollbars and it's provided by widgets that support vertical scrolling. 🔥

For the full details on how this option gets used, go read the description of -xscrollcommand — it's all there, no cap. 👀

---

🌈 SEE ALSO 🌈

• colors
• cursors
• font

---

⭐ KEYWORDS ⭐

• class
• name
• standard option
• switch

---

and that's a wrap on options(3tk) bestie!! 🎀✨ this whole thing is from Tk 4.4, dated way back in the day, and it lives under the options section — go forth and configure your widgets, you absolute main character 👑💖