1options(3) User Contributed Perl Documentation options(3)
2
6 Tk::options - Standard options supported by widgets and their
7 manipulation
8
10 $value = $widget->cget('-option');
11 $widget->configure(-option=>value ?,-option=>value ...?);
13 @list = $widget->configure('-option');
15 @lol = $widget->configure;
17
19 All widgets, and images have a standard mechanism for setting and
20 querying attibutes or options. The mechanism is based on two methods
21 configure and cget. The behaviour of these methods is as follows:
22 $widget->configure(-option=>value ?,-option=>value ...?);
24 Sets the values of -option to value for each -option=>value pair.
25 The internal new method does an implicit configure in this form
26 with options passed in at widget create time.
27 $widget->configure('-option')
29 In array context returns a list of five or two elements. If
30 -option is an alias for another options it return a list consisting
31 of the alias option and the name for the option is is an alias for,
32 e.g., "('-bg', 'background')". If -option is not an alias the
33 returned list has the following five elements:
34 Option Name
36 The value of -option, e.g., -background.
37 Name The option's name in the option database, e.g.,
39 "background".
40 Class The option's class value in the option database, e.g.,
42 "Background".
43 Default The default value for the option if not specified or in the
45 option database, e.g., "grey".
46 Value The current value (as returned by cget), e.g., "white".
48 $widget->configure
50 Returns a list of lists for all the options supported by $widget.
51 Each sub-list is in the form returned by configure('-option').
52 (This mechanism is used by the Tk::Derived class to determine the
53 options available from base class.)
54 $widget->cget('-option')
56 Returns the current value of -option for $widget.
57 cget('-option') is clumsy with the need for '' due to perl's
59 parsing rules. Something more subtle using tie might look better.
60 The following paragraphs describe the common configuration options
62 supported by widgets in the Tk toolkit. Every widget does not
63 necessarily support every option (see the the documentation entries for
64 individual widgets for a list of the standard options supported by that
65 widget), but if a widget does support an option with one of the names
66 listed below, then the option has exactly the effect described below.
67 In the descriptions below, ``Name'' refers to the option's name in the
69 option database. ``Class'' refers to the option's class value in the
70 option database. ``Switch'' refers to the switch used in widget-
71 creation and configure widget methods to set this value. For example,
72 if an option's configure option is -foreground and there exists a
73 widget $widget, then the call:
74 $widget->configure(-foreground=>'black')
76 may be used to specify the value black for the option in the widget
78 $widget. Configure options may be abbreviated, as long as the
79 abbreviation is unambiguous (abbreviation is deprecated in perl/Tk).
80 Creation options: Widget Name and Class
82 The Name and -class options can only be specified when a widget is
83 created, and cannot be changed with configure. These options determine
84 the widget's identity and how Tk applies resource values from the
85 option database (see Tk::option) and so they cannot be assigned by the
86 options database.
87 Name: name
89 Switch: Name
90 Specifies the path element for the widget. Names generally begin
91 with a lowercase letter.
92 Each widget has a unique pathname that follows the hierarchy from
94 the MainWindow to the widget itself. Since the widget's PathName
95 is used to assign options from the options database, it is
96 important to specify a distinctive Name for any widget that will
97 have non-default options. See Tk::option for details.
98 Name: class
100 Switch: -class
101 Specifies a class for the window. Classes generally begin with an
102 uppercase letter.
103 This class will be used when querying the option database for the
105 window's other options (see Tk::options), and it will also be used
106 later for other purposes such as bindings. One typically assigns a
107 class to a TopLevel or Frame so that the class will apply to all of
108 that widget's children.
109 Reconfigurable options
111 These options can be set at widget creation or changed later via
112 configure.
113 Name: activeBackground
115 Class: Foreground
116 Switch: -activebackground
117 Specifies background color to use when drawing active elements. An
118 element (a widget or portion of a widget) is active if the mouse
119 cursor is positioned over the element and pressing a mouse button
120 will cause some action to occur. If strict Motif compliance has
121 been requested by setting the $Tk::strictMotif variable, this
122 option will normally be ignored; the normal background color will
123 be used instead. For some elements on Windows and Macintosh
124 systems, the active color will only be used while mouse button 1 is
125 pressed over the element.
126 Name: activeBorderWidth
128 Class: BorderWidth
129 Switch: -activeborderwidth
130 Specifies a non-negative value indicating the width of the 3-D
131 border drawn around active elements. See above for definition of
132 active elements. The value may have any of the forms acceptable to
133 Tk_GetPixels. This option is typically only available in widgets
134 displaying more than one element at a time (e.g. menus but not
135 buttons).
136 Name: activeForeground
138 Class: Background
139 Switch: -activeforeground
140 Specifies foreground color to use when drawing active elements.
141 See above for definition of active elements.
142 Name: activetile
144 Class: Tile
145 Switch: -activetile
146 Specifies image used to display inside active elements of the
147 widget. See above for definition of active elements.
148 Name: anchor
150 Class: Anchor
151 Switch: -anchor
152 Specifies how the information in a widget (e.g. text or a bitmap)
153 is to be displayed in the widget. Must be one of the values n, ne,
154 e, se, s, sw, w, nw, or center. For example, nw means display the
155 information such that its top-left corner is at the top-left corner
156 of the widget.
157 Name: background
159 Class: Background
160 Switch: -background
161 Alias: -bg
162 Specifies the normal background color to use when displaying the
163 widget.
164 Name: bitmap
166 Class: Bitmap
167 Switch: -bitmap
168 Specifies a bitmap to display in the widget, in any of the forms
169 acceptable to Tk_GetBitmap. The exact way in which the bitmap is
170 displayed may be affected by other options such as -anchor or
171 -justify. Typically, if this option is specified then it overrides
172 other options that specify a textual value to display in the
173 widget; the -bitmap option may be reset to an empty string to re-
174 enable a text display. In widgets that support both -bitmap and
175 -image options, -image will usually override -bitmap.
176 Name: borderWidth
178 Class: BorderWidth
179 Switch: -borderwidth
180 Alias: -bd
181 Specifies a non-negative value indicating the width of the 3-D
182 border to draw around the outside of the widget (if such a border
183 is being drawn; the relief option typically determines this). The
184 value may also be used when drawing 3-D effects in the interior of
185 the widget. The value may have any of the forms acceptable to
186 Tk_GetPixels.
187 Name: compound
189 Class: Compound
190 Switch: -compound
191 Specifies if the widget should display text and bitmaps/images at
192 the same time, and if so, where the bitmap/image should be placed
193 relative to the text. Must be one of the values none, bottom, top,
194 left, right, or center. For example, the (default) value none
195 specifies that the bitmap or image should (if defined) be displayed
196 instead of the text, the value left specifies that the bitmap or
197 image should be displayed to the left of the text, and the value
198 center specifies that the bitmap or image should be displayed on
199 top of the text.
200 Name: cursor
202 Class: Cursor
203 Switch: -cursor
204 Specifies the mouse cursor to be used for the widget. The value
205 may have any of the forms acceptable to Tk_GetCursor.
206 Name: dash
208 Class: Dash
209 Switch: -dash
210 The value may have any of the forms accepted by Tk_GetDash, such as
211 4, [6,4], ., -, -., or -...
212 Name: dashoffset
214 Class: Dashoffset
215 Switch: -dashoffset
216 Specifies the offset in the dash list where the drawing starts.
217 Name: disabledForeground
219 Class: DisabledForeground
220 Switch: -disabledforeground
221 Specifies foreground color to use when drawing a disabled element.
222 If the option is specified as an empty string (which is typically
223 the case on monochrome displays), disabled elements are drawn with
224 the normal foreground color but they are dimmed by drawing them
225 with a stippled fill pattern.
226 Name: disabledtile
228 Class: Tile
229 Switch: -disabledtile
230 Specifies image to use when drawing a disabled element.
231 Name: exportSelection
233 Class: ExportSelection
234 Switch: -exportselection
235 Specifies whether or not a selection in the widget should also be
236 the X selection. The value may have any of the forms accepted by
237 Tcl_GetBoolean, such as true, false, 0, 1, yes, or no. If the
238 selection is exported, then selecting in the widget deselects the
239 current X selection, selecting outside the widget deselects any
240 widget selection, and the widget will respond to selection
241 retrieval requests when it has a selection. The default is usually
242 for widgets to export selections.
243 Name: font
245 Class: Font
246 Switch: -font
247 Specifies the font to use when drawing text inside the widget.
248 Name: foreground
250 Class: Foreground
251 Switch: -foreground
252 Alias: -fg
253 Specifies the normal foreground color to use when displaying the
254 widget.
255 Name: highlightBackground
257 Class: HighlightBackground
258 Switch: -highlightbackground
259 Specifies the color to display in the traversal highlight region
260 when the widget does not have the input focus.
261 Name: highlightColor
263 Class: HighlightColor
264 Switch: -highlightcolor
265 Specifies the color to use for the traversal highlight rectangle
266 that is drawn around the widget when it has the input focus.
267 Name: highlightThickness
269 Class: HighlightThickness
270 Switch: -highlightthickness
271 Specifies a non-negative value indicating the width of the
272 highlight rectangle to draw around the outside of the widget when
273 it has the input focus. The value may have any of the forms
274 acceptable to Tk_GetPixels. If the value is zero, no focus
275 highlight is drawn around the widget.
276 Name: image
278 Class: Image
279 Switch: -image
280 Specifies an image to display in the widget, which must have been
281 created with an image create. (See Tk::Image for details of image
282 creation.) Typically, if the -image option is specified then it
283 overrides other options that specify a bitmap or textual value to
284 display in the widget; the -image option may be reset to an empty
285 string to re-enable a bitmap or text display.
286 Name: insertBackground
288 Class: Foreground
289 Switch: -insertbackground
290 Specifies the color to use as background in the area covered by the
291 insertion cursor. This color will normally override either the
292 normal background for the widget (or the selection background if
293 the insertion cursor happens to fall in the selection).
294 Name: insertBorderWidth
296 Class: BorderWidth
297 Switch: -insertborderwidth
298 Specifies a non-negative value indicating the width of the 3-D
299 border to draw around the insertion cursor. The value may have any
300 of the forms acceptable to Tk_GetPixels.
301 Name: insertOffTime
303 Class: OffTime
304 Switch: -insertofftime
305 Specifies a non-negative integer value indicating the number of
306 milliseconds the insertion cursor should remain ``off'' in each
307 blink cycle. If this option is zero then the cursor doesn't blink:
308 it is on all the time.
309 Name: insertOnTime
311 Class: OnTime
312 Switch: -insertontime
313 Specifies a non-negative integer value indicating the number of
314 milliseconds the insertion cursor should remain ``on'' in each
315 blink cycle.
316 Name: insertWidth
318 Class: InsertWidth
319 Switch: -insertwidth
320 Specifies a value indicating the total width of the insertion
321 cursor. The value may have any of the forms acceptable to
322 Tk_GetPixels. If a border has been specified for the insertion
323 cursor (using the insertBorderWidth option), the border will be
324 drawn inside the width specified by the insertWidth option.
325 Name: jump
327 Class: Jump
328 Switch: -jump
329 For widgets with a slider that can be dragged to adjust a value,
330 such as scrollbars, this option determines when notifications are
331 made about changes in the value. The option's value must be a
332 boolean of the form accepted by Tcl_GetBoolean. If the value is
333 false, updates are made continuously as the slider is dragged. If
334 the value is true, updates are delayed until the mouse button is
335 released to end the drag; at that point a single notification is
336 made (the value ``jumps'' rather than changing smoothly).
337 Name: justify
339 Class: Justify
340 Switch: -justify
341 When there are multiple lines of text displayed in a widget, this
342 option determines how the lines line up with each other. Must be
343 one of left, center, or right. Left means that the lines' left
344 edges all line up, center means that the lines' centers are
345 aligned, and right means that the lines' right edges line up.
346 Name: offset
348 Class: Offset
349 Switch: -offset
350 Specifies the offset of tiles (see also -tile option). It can have
351 two different formats -offset x,y or -offset side, where side can
352 be n, ne, e, se, s, sw, w, nw, or center. In the first case the
353 origin is the origin of the toplevel of the current window. For
354 the canvas itself and canvas objects the origin is the canvas
355 origin, but putting # in front of the coordinate pair indicates
356 using the toplevel origin in stead. For canvas objects, the -offset
357 option is used for stippling as well. For the line and polygon
358 canvas items you can also specify an index as argument, which
359 connects the stipple or tile origin to one of the coordinate points
360 of the line/polygon.
361 Name: orient
363 Class: Orient
364 Switch: -orient
365 For widgets that can lay themselves out with either a horizontal or
366 vertical orientation, such as scrollbars, this option specifies
367 which orientation should be used. Must be either horizontal or
368 vertical or an abbreviation of one of these.
369 Name: padX
371 Class: Pad
372 Switch: -padx
373 Specifies a non-negative value indicating how much extra space to
374 request for the widget in the X-direction. The value may have any
375 of the forms acceptable to Tk_GetPixels. When computing how large
376 a window it needs, the widget will add this amount to the width it
377 would normally need (as determined by the width of the things
378 displayed in the widget); if the geometry manager can satisfy this
379 request, the widget will end up with extra internal space to the
380 left and/or right of what it displays inside. Most widgets only
381 use this option for padding text: if they are displaying a bitmap
382 or image, then they usually ignore padding options.
383 Name: padY
385 Class: Pad
386 Switch: -pady
387 Specifies a non-negative value indicating how much extra space to
388 request for the widget in the Y-direction. The value may have any
389 of the forms acceptable to Tk_GetPixels. When computing how large
390 a window it needs, the widget will add this amount to the height it
391 would normally need (as determined by the height of the things
392 displayed in the widget); if the geometry manager can satisfy this
393 request, the widget will end up with extra internal space above
394 and/or below what it displays inside. Most widgets only use this
395 option for padding text: if they are displaying a bitmap or image,
396 then they usually ignore padding options.
397 Name: relief
399 Class: Relief
400 Switch: -relief
401 Specifies the 3-D effect desired for the widget. Acceptable values
402 are raised, sunken, flat, ridge, solid, and groove. The value
403 indicates how the interior of the widget should appear relative to
404 its exterior; for example, raised means the interior of the widget
405 should appear to protrude from the screen, relative to the exterior
406 of the widget.
407 Name: repeatDelay
409 Class: RepeatDelay
410 Switch: -repeatdelay
411 Specifies the number of milliseconds a button or key must be held
412 down before it begins to auto-repeat. Used, for example, on the
413 up- and down-arrows in scrollbars.
414 Name: repeatInterval
416 Class: RepeatInterval
417 Switch: -repeatinterval
418 Used in conjunction with repeatDelay: once auto-repeat begins,
419 this option determines the number of milliseconds between auto-
420 repeats.
421 Name: selectBackground
423 Class: Foreground
424 Switch: -selectbackground
425 Specifies the background color to use when displaying selected
426 items.
427 Name: selectBorderWidth
429 Class: BorderWidth
430 Switch: -selectborderwidth
431 Specifies a non-negative value indicating the width of the 3-D
432 border to draw around selected items. The value may have any of
433 the forms acceptable to Tk_GetPixels.
434 Name: selectForeground
436 Class: Background
437 Switch: -selectforeground
438 Specifies the foreground color to use when displaying selected
439 items.
440 Name: setGrid
442 Class: SetGrid
443 Switch: -setgrid
444 Specifies a boolean value that determines whether this widget
445 controls the resizing grid for its top-level window. This option
446 is typically used in text widgets, where the information in the
447 widget has a natural size (the size of a character) and it makes
448 sense for the window's dimensions to be integral numbers of these
449 units. These natural window sizes form a grid. If the setGrid
450 option is set to true then the widget will communicate with the
451 window manager so that when the user interactively resizes the top-
452 level window that contains the widget, the dimensions of the window
453 will be displayed to the user in grid units and the window size
454 will be constrained to integral numbers of grid units. See
455 "GRIDDED GEOMETRY MANAGEMENT" in Tk::Wm for more details.
456 Name: takeFocus
458 Class: TakeFocus
459 Switch: -takefocus
460 Determines whether the window accepts the focus during keyboard
461 traversal (e.g., Tab and Shift-Tab). Before setting the focus to a
462 window, the traversal scripts consult the value of the takeFocus
463 option. A value of 0 means that the window should be skipped
464 entirely during keyboard traversal. 1 means that the window should
465 receive the input focus as long as it is viewable (it and all of
466 its ancestors are mapped). An empty value for the option means
467 that the traversal scripts make the decision about whether or not
468 to focus on the window: the current algorithm is to skip the
469 window if it is disabled, if it has no key bindings, or if it is
470 not viewable. If the value has any other form, then the traversal
471 scripts take the value, append the name of the window to it (with a
472 separator space), and evaluate the resulting string as a Callback.
473 The script must return 0, 1, or an empty string: a 0 or 1 value
474 specifies whether the window will receive the input focus, and an
475 empty string results in the default decision described above.
476 Note: this interpretation of the option is defined entirely by the
477 Callbacks that implement traversal: the widget implementations
478 ignore the option entirely, so you can change its meaning if you
479 redefine the keyboard traversal scripts.
480 Name: text
482 Class: Text
483 Switch: -text
484 Specifies a string to be displayed inside the widget. The way in
485 which the string is displayed depends on the particular widget and
486 may be determined by other options, such as anchor or justify.
487 Name: textVariable
489 Class: Variable
490 Switch: -textvariable
491 Specifies the name of a variable. The value of the variable is a
492 text string to be displayed inside the widget; if the variable
493 value changes then the widget will automatically update itself to
494 reflect the new value. The way in which the string is displayed in
495 the widget depends on the particular widget and may be determined
496 by other options, such as anchor or justify.
497 Name: tile
499 Class: Tile
500 Switch: -tile
501 Specifies image used to display the widget. If image is the empty
502 string, then the normal background color is displayed.
503 Name: troughColor
505 Class: Background
506 Switch: -troughcolor
507 Specifies the color to use for the rectangular trough areas in
508 widgets such as scrollbars and scales.
509 Name: troughTile
511 Class: Tile
512 Switch: -troughtile
513 Specifies image used to display in the rectangular trough areas in
514 widgets such as scrollbars and scales.
515 Name: underline
517 Class: Underline
518 Switch: -underline
519 Specifies the integer index of a character to underline in the
520 widget. This option is used by the default bindings to implement
521 keyboard traversal for menu buttons and menu entries. 0
522 corresponds to the first character of the text displayed in the
523 widget, 1 to the next character, and so on.
524 Name: wrapLength
526 Class: WrapLength
527 Switch: -wraplength
528 For widgets that can perform word-wrapping, this option specifies
529 the maximum line length. Lines that would exceed this length are
530 wrapped onto the next line, so that no line is longer than the
531 specified length. The value may be specified in any of the
532 standard forms for screen distances. If this value is less than or
533 equal to 0 then no wrapping is done: lines will break only at
534 newline characters in the text.
535 Name: xScrollCommand
537 Class: ScrollCommand
538 Switch: -xscrollcommand
539 Specifies a callback used to communicate with horizontal
540 scrollbars. When the view in the widget's window changes (or
541 whenever anything else occurs that could change the display in a
542 scrollbar, such as a change in the total size of the widget's
543 contents), the widget will make a callback passing two numeric
544 arguments in addition to any specified in the callback. Each of
545 the numbers is a fraction between 0 and 1, which indicates a
546 position in the document. 0 indicates the beginning of the
547 document, 1 indicates the end, .333 indicates a position one third
548 the way through the document, and so on. The first fraction
549 indicates the first information in the document that is visible in
550 the window, and the second fraction indicates the information just
551 after the last portion that is visible. Typically the
552 xScrollCommand option consists of the scrollbar widget object and
553 the method ``set'' i.e. [set => $sb]: this will cause the scrollbar
554 to be updated whenever the view in the window changes. If this
555 option is not specified, then no command will be executed.
556 Name: yScrollCommand
558 Class: ScrollCommand
559 Switch: -yscrollcommand
560 Specifies a calback used to communicate with vertical scrollbars.
561 This option is treated in the same way as the xScrollCommand
562 option, except that it is used for vertical scrollbars and is
563 provided by widgets that support vertical scrolling. See the
564 description of xScrollCommand for details on how this option is
565 used.
566
568 Tk::option Tk::callbacks Tk::ConfigSpecs Tk_GetPixels
569
571 class, name, standard option, switch
572perl v5.38.0 2023-07-21 options(3)