1options(n) Tk Built-In Commands options(n)
2______________________________________________________________________________
6
8 options - Standard options supported by widgets
9______________________________________________________________________________
10
12 This manual entry describes the common configuration options supported
13 by widgets in the Tk toolkit. Every widget does not necessarily sup‐
14 port every option (see the manual entries for individual widgets for a
15 list of the standard options supported by that widget), but if a widget
16 does support an option with one of the names listed below, then the
17 option has exactly the effect described below.
18 In the descriptions below, “Command-Line Name” refers to the switch
20 used in class commands and configure widget commands to set this value.
21 For example, if an option's command-line switch is -foreground and
22 there exists a widget .a.b.c, then the command
23 .a.b.c configure -foreground black
24 may be used to specify the value black for the option in the widget
25 .a.b.c. Command-line switches may be abbreviated, as long as the
26 abbreviation is unambiguous. “Database Name” refers to the option's
27 name in the option database (e.g. in .Xdefaults files). “Database
28 Class” refers to the option's class value in the option database.
29 Command-Line Name:-activebackground
31 Database Name: activeBackground
32 Database Class: Foreground
33 Specifies background color to use when drawing active elements.
35 An element (a widget or portion of a widget) is active if the
36 mouse cursor is positioned over the element and pressing a mouse
37 button will cause some action to occur. If strict Motif compli‐
38 ance has been requested by setting the tk_strictMotif variable,
39 this option will normally be ignored; the normal background
40 color will be used instead. For some elements on Windows and
41 Macintosh systems, the active color will only be used while
42 mouse button 1 is pressed over the element.
43 Command-Line Name:-activeborderwidth
45 Database Name: activeBorderWidth
46 Database Class: BorderWidth
47 Specifies a non-negative value indicating the width of the 3-D
49 border drawn around active elements. See above for definition
50 of active elements. The value may have any of the forms accept‐
51 able to Tk_GetPixels. This option is typically only available
52 in widgets displaying more than one element at a time (e.g.
53 menus but not buttons).
54 Command-Line Name:-activeforeground
56 Database Name: activeForeground
57 Database Class: Background
58 Specifies foreground color to use when drawing active elements.
60 See above for definition of active elements.
61 Command-Line Name:-anchor
63 Database Name: anchor
64 Database Class: Anchor
65 Specifies how the information in a widget (e.g. text or a bit‐
67 map) is to be displayed in the widget. Must be one of the val‐
68 ues n, ne, e, se, s, sw, w, nw, or center. For example, nw
69 means display the information such that its top-left corner is
70 at the top-left corner of the widget.
71 Command-Line Name:-background or -bg
73 Database Name: background
74 Database Class: Background
75 Specifies the normal background color to use when displaying the
77 widget.
78 Command-Line Name:-bitmap
80 Database Name: bitmap
81 Database Class: Bitmap
82 Specifies a bitmap to display in the widget, in any of the forms
84 acceptable to Tk_GetBitmap. The exact way in which the bitmap
85 is displayed may be affected by other options such as -anchor or
86 -justify. Typically, if this option is specified then it over‐
87 rides other options that specify a textual value to display in
88 the widget but this is controlled by the -compound option; the
89 -bitmap option may be reset to an empty string to re-enable a
90 text display. In widgets that support both -bitmap and -image
91 options, -image will usually override -bitmap.
92 Command-Line Name:-borderwidth or -bd
94 Database Name: borderWidth
95 Database Class: BorderWidth
96 Specifies a non-negative value indicating the width of the 3-D
98 border to draw around the outside of the widget (if such a bor‐
99 der is being drawn; the -relief option typically determines
100 this). The value may also be used when drawing 3-D effects in
101 the interior of the widget. The value may have any of the forms
102 acceptable to Tk_GetPixels.
103 Command-Line Name:-cursor
105 Database Name: cursor
106 Database Class: Cursor
107 Specifies the mouse cursor to be used for the widget. The value
109 may have any of the forms acceptable to Tk_GetCursor. In addi‐
110 tion, if an empty string is specified, it indicates that the
111 widget should defer to its parent for cursor specification.
112 Command-Line Name:-compound
114 Database Name: compound
115 Database Class: Compound
116 Specifies if the widget should display text and bitmaps/images
118 at the same time, and if so, where the bitmap/image should be
119 placed relative to the text. Must be one of the values none,
120 bottom, top, left, right, or center. For example, the (default)
121 value none specifies that the bitmap or image should (if
122 defined) be displayed instead of the text, the value left speci‐
123 fies that the bitmap or image should be displayed to the left of
124 the text, and the value center specifies that the bitmap or
125 image should be displayed on top of the text.
126 Command-Line Name:-disabledforeground
128 Database Name: disabledForeground
129 Database Class: DisabledForeground
130 Specifies foreground color to use when drawing a disabled ele‐
132 ment. If the option is specified as an empty string (which is
133 typically the case on monochrome displays), disabled elements
134 are drawn with the normal foreground color but they are dimmed
135 by drawing them with a stippled fill pattern.
136 Command-Line Name:-exportselection
138 Database Name: exportSelection
139 Database Class: ExportSelection
140 Specifies whether or not a selection in the widget should also
142 be the X selection. The value may have any of the forms
143 accepted by Tcl_GetBoolean, such as true, false, 0, 1, yes, or
144 no. If the selection is exported, then selecting in the widget
145 deselects the current X selection, selecting outside the widget
146 deselects any widget selection, and the widget will respond to
147 selection retrieval requests when it has a selection. The
148 default is usually for widgets to export selections.
149 Command-Line Name:-font
151 Database Name: font
152 Database Class: Font
153 Specifies the font to use when drawing text inside the widget.
155 The value may have any of the forms described in the font manual
156 page under FONT DESCRIPTION.
157 Command-Line Name:-foreground or -fg
159 Database Name: foreground
160 Database Class: Foreground
161 Specifies the normal foreground color to use when displaying the
163 widget.
164 Command-Line Name:-highlightbackground
166 Database Name: highlightBackground
167 Database Class: HighlightBackground
168 Specifies the color to display in the traversal highlight region
170 when the widget does not have the input focus.
171 Command-Line Name:-highlightcolor
173 Database Name: highlightColor
174 Database Class: HighlightColor
175 Specifies the color to use for the traversal highlight rectangle
177 that is drawn around the widget when it has the input focus.
178 Command-Line Name:-highlightthickness
180 Database Name: highlightThickness
181 Database Class: HighlightThickness
182 Specifies a non-negative value indicating the width of the high‐
184 light rectangle to draw around the outside of the widget when it
185 has the input focus. The value may have any of the forms
186 acceptable to Tk_GetPixels. If the value is zero, no focus
187 highlight is drawn around the widget.
188 Command-Line Name:-image
190 Database Name: image
191 Database Class: Image
192 Specifies an image to display in the widget, which must have
194 been created with the image create command. Typically, if the
195 -image option is specified then it overrides other options that
196 specify a bitmap or textual value to display in the widget,
197 though this is controlled by the -compound option; the -image
198 option may be reset to an empty string to re-enable a bitmap or
199 text display.
200 Command-Line Name:-insertbackground
202 Database Name: insertBackground
203 Database Class: Foreground
204 Specifies the color to use as background in the area covered by
206 the insertion cursor. This color will normally override either
207 the normal background for the widget (or the selection back‐
208 ground if the insertion cursor happens to fall in the selec‐
209 tion).
210 Command-Line Name:-insertborderwidth
212 Database Name: insertBorderWidth
213 Database Class: BorderWidth
214 Specifies a non-negative value indicating the width of the 3-D
216 border to draw around the insertion cursor. The value may have
217 any of the forms acceptable to Tk_GetPixels.
218 Command-Line Name:-insertofftime
220 Database Name: insertOffTime
221 Database Class: OffTime
222 Specifies a non-negative integer value indicating the number of
224 milliseconds the insertion cursor should remain “off” in each
225 blink cycle. If this option is zero then the cursor does not
226 blink: it is on all the time.
227 Command-Line Name:-insertontime
229 Database Name: insertOnTime
230 Database Class: OnTime
231 Specifies a non-negative integer value indicating the number of
233 milliseconds the insertion cursor should remain “on” in each
234 blink cycle.
235 Command-Line Name:-insertwidth
237 Database Name: insertWidth
238 Database Class: InsertWidth
239 Specifies a value indicating the total width of the insertion
241 cursor. The value may have any of the forms acceptable to
242 Tk_GetPixels. If a border has been specified for the insertion
243 cursor (using the -insertborderwidth option), the border will be
244 drawn inside the width specified by the -insertwidth option.
245 Command-Line Name:-jump
247 Database Name: jump
248 Database Class: Jump
249 For widgets with a slider that can be dragged to adjust a value,
251 such as scrollbars, this option determines when notifications
252 are made about changes in the value. The option's value must be
253 a boolean of the form accepted by Tcl_GetBoolean. If the value
254 is false, updates are made continuously as the slider is
255 dragged. If the value is true, updates are delayed until the
256 mouse button is released to end the drag; at that point a sin‐
257 gle notification is made (the value “jumps” rather than changing
258 smoothly).
259 Command-Line Name:-justify
261 Database Name: justify
262 Database Class: Justify
263 When there are multiple lines of text displayed in a widget,
265 this option determines how the lines line up with each other.
266 Must be one of left, center, or right. Left means that the
267 lines' left edges all line up, center means that the lines' cen‐
268 ters are aligned, and right means that the lines' right edges
269 line up.
270 Command-Line Name:-orient
272 Database Name: orient
273 Database Class: Orient
274 For widgets that can lay themselves out with either a horizontal
276 or vertical orientation, such as scrollbars, this option speci‐
277 fies which orientation should be used. Must be either horizon‐
278 tal or vertical or an abbreviation of one of these.
279 Command-Line Name:-padx
281 Database Name: padX
282 Database Class: Pad
283 Specifies a non-negative value indicating how much extra space
285 to request for the widget in the X-direction. The value may
286 have any of the forms acceptable to Tk_GetPixels. When comput‐
287 ing how large a window it needs, the widget will add this amount
288 to the width it would normally need (as determined by the width
289 of the things displayed in the widget); if the geometry manager
290 can satisfy this request, the widget will end up with extra
291 internal space to the left and/or right of what it displays
292 inside. Most widgets only use this option for padding text: if
293 they are displaying a bitmap or image, then they usually ignore
294 padding options.
295 Command-Line Name:-pady
297 Database Name: padY
298 Database Class: Pad
299 Specifies a non-negative value indicating how much extra space
301 to request for the widget in the Y-direction. The value may
302 have any of the forms acceptable to Tk_GetPixels. When comput‐
303 ing how large a window it needs, the widget will add this amount
304 to the height it would normally need (as determined by the
305 height of the things displayed in the widget); if the geometry
306 manager can satisfy this request, the widget will end up with
307 extra internal space above and/or below what it displays inside.
308 Most widgets only use this option for padding text: if they are
309 displaying a bitmap or image, then they usually ignore padding
310 options.
311 Command-Line Name:-relief
313 Database Name: relief
314 Database Class: Relief
315 Specifies the 3-D effect desired for the widget. Acceptable
317 values are raised, sunken, flat, ridge, solid, and groove. The
318 value indicates how the interior of the widget should appear
319 relative to its exterior; for example, raised means the inte‐
320 rior of the widget should appear to protrude from the screen,
321 relative to the exterior of the widget.
322 Command-Line Name:-repeatdelay
324 Database Name: repeatDelay
325 Database Class: RepeatDelay
326 Specifies the number of milliseconds a button or key must be
328 held down before it begins to auto-repeat. Used, for example,
329 on the up- and down-arrows in scrollbars.
330 Command-Line Name:-repeatinterval
332 Database Name: repeatInterval
333 Database Class: RepeatInterval
334 Used in conjunction with -repeatdelay: once auto-repeat begins,
336 this option determines the number of milliseconds between auto-
337 repeats.
338 Command-Line Name:-selectbackground
340 Database Name: selectBackground
341 Database Class: Foreground
342 Specifies the background color to use when displaying selected
344 items.
345 Command-Line Name:-selectborderwidth
347 Database Name: selectBorderWidth
348 Database Class: BorderWidth
349 Specifies a non-negative value indicating the width of the 3-D
351 border to draw around selected items. The value may have any of
352 the forms acceptable to Tk_GetPixels.
353 Command-Line Name:-selectforeground
355 Database Name: selectForeground
356 Database Class: Background
357 Specifies the foreground color to use when displaying selected
359 items.
360 Command-Line Name:-setgrid
362 Database Name: setGrid
363 Database Class: SetGrid
364 Specifies a boolean value that determines whether this widget
366 controls the resizing grid for its top-level window. This
367 option is typically used in text widgets, where the information
368 in the widget has a natural size (the size of a character) and
369 it makes sense for the window's dimensions to be integral num‐
370 bers of these units. These natural window sizes form a grid.
371 If the -setgrid option is set to true then the widget will com‐
372 municate with the window manager so that when the user interac‐
373 tively resizes the top-level window that contains the widget,
374 the dimensions of the window will be displayed to the user in
375 grid units and the window size will be constrained to integral
376 numbers of grid units. See the section GRIDDED GEOMETRY MANAGE‐
377 MENT in the wm manual entry for more details.
378 Command-Line Name:-takefocus
380 Database Name: takeFocus
381 Database Class: TakeFocus
382 Determines whether the window accepts the focus during keyboard
384 traversal (e.g., Tab and Shift-Tab). Before setting the focus
385 to a window, the traversal scripts consult the value of the
386 -takefocus option. A value of 0 means that the window should be
387 skipped entirely during keyboard traversal. 1 means that the
388 window should receive the input focus as long as it is viewable
389 (it and all of its ancestors are mapped). An empty value for
390 the option means that the traversal scripts make the decision
391 about whether or not to focus on the window: the current algo‐
392 rithm is to skip the window if it is disabled, if it has no key
393 bindings, or if it is not viewable. If the value has any other
394 form, then the traversal scripts take the value, append the name
395 of the window to it (with a separator space), and evaluate the
396 resulting string as a Tcl script. The script must return 0, 1,
397 or an empty string: a 0 or 1 value specifies whether the window
398 will receive the input focus, and an empty string results in the
399 default decision described above. Note: this interpretation of
400 the option is defined entirely by the Tcl scripts that implement
401 traversal: the widget implementations ignore the option
402 entirely, so you can change its meaning if you redefine the key‐
403 board traversal scripts.
404 Command-Line Name:-text
406 Database Name: text
407 Database Class: Text
408 Specifies a string to be displayed inside the widget. The way
410 in which the string is displayed depends on the particular wid‐
411 get and may be determined by other options, such as -anchor or
412 -justify.
413 Command-Line Name:-textvariable
415 Database Name: textVariable
416 Database Class: Variable
417 Specifies the name of a global variable. The value of the vari‐
419 able is a text string to be displayed inside the widget; if the
420 variable value changes then the widget will automatically update
421 itself to reflect the new value. The way in which the string is
422 displayed in the widget depends on the particular widget and may
423 be determined by other options, such as -anchor or -justify.
424 Command-Line Name:-troughcolor
426 Database Name: troughColor
427 Database Class: Background
428 Specifies the color to use for the rectangular trough areas in
430 widgets such as scrollbars and scales. This option is ignored
431 for scrollbars on Windows (native widget does not recognize this
432 option).
433 Command-Line Name:-underline
435 Database Name: underline
436 Database Class: Underline
437 Specifies the integer index of a character to underline in the
439 widget. This option is used by the default bindings to imple‐
440 ment keyboard traversal for menu buttons and menu entries. 0
441 corresponds to the first character of the text displayed in the
442 widget, 1 to the next character, and so on.
443 Command-Line Name:-wraplength
445 Database Name: wrapLength
446 Database Class: WrapLength
447 For widgets that can perform word-wrapping, this option speci‐
449 fies the maximum line length. Lines that would exceed this
450 length are wrapped onto the next line, so that no line is longer
451 than the specified length. The value may be specified in any of
452 the standard forms for screen distances. If this value is less
453 than or equal to 0 then no wrapping is done: lines will break
454 only at newline characters in the text.
455 Command-Line Name:-xscrollcommand
457 Database Name: xScrollCommand
458 Database Class: ScrollCommand
459 Specifies the prefix for a command used to communicate with hor‐
461 izontal scrollbars. When the view in the widget's window
462 changes (or whenever anything else occurs that could change the
463 display in a scrollbar, such as a change in the total size of
464 the widget's contents), the widget will generate a Tcl command
465 by concatenating the scroll command and two numbers. Each of
466 the numbers is a fraction between 0 and 1, which indicates a
467 position in the document. 0 indicates the beginning of the doc‐
468 ument, 1 indicates the end, .333 indicates a position one third
469 the way through the document, and so on. The first fraction
470 indicates the first information in the document that is visible
471 in the window, and the second fraction indicates the information
472 just after the last portion that is visible. The command is
473 then passed to the Tcl interpreter for execution. Typically the
474 -xscrollcommand option consists of the path name of a scrollbar
475 widget followed by “set”, e.g. “.x.scrollbar set”: this will
476 cause the scrollbar to be updated whenever the view in the win‐
477 dow changes. If this option is not specified, then no command
478 will be executed.
479 Command-Line Name:-yscrollcommand
481 Database Name: yScrollCommand
482 Database Class: ScrollCommand
483 Specifies the prefix for a command used to communicate with ver‐
485 tical scrollbars. This option is treated in the same way as the
486 -xscrollcommand option, except that it is used for vertical
487 scrollbars and is provided by widgets that support vertical
488 scrolling. See the description of -xscrollcommand for details
489 on how this option is used.
490
492 colors, cursors, font
493
495 class, name, standard option, switch
496Tk 4.4 options(n)