1options(3) User Contributed Perl Documentation options(3)
2
6 Tk::options - Standard options supported by widgets and their manipula‐
7 tion
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., "back‐
39 ground".
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 pars‐
59 ing rules. Something more subtle using tie might look better.
60 The following paragraphs describe the common configuration options sup‐
62 ported by widgets in the Tk toolkit. Every widget does not necessarily
63 support every option (see the the documentation entries for individual
64 widgets for a list of the standard options supported by that widget),
65 but if a widget does support an option with one of the names listed
66 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-cre‐
71 ation and configure widget methods to set this value. For example, if
72 an option's configure option is -foreground and there exists a widget
73 $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 abbrevi‐
79 ation 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 cre‐
84 ated, and cannot be changed with configure. These options determine
85 the widget's identity and how Tk applies resource values from the
86 option database (see Tk::option) and so they cannot be assigned by the
87 options database.
88 Name: name
90 Switch: Name
91 Specifies the path element for the widget. Names generally begin
92 with a lowercase letter.
93 Each widget has a unique pathname that follows the hierarchy from
95 the MainWindow to the widget itself. Since the widget's PathName
96 is used to assign options from the options database, it is impor‐
97 tant to specify a distinctive Name for any widget that will have
98 non-default options. See Tk::option for details.
99 Name: class
101 Switch: -class
102 Specifies a class for the window. Classes generally begin with an
103 uppercase letter.
104 This class will be used when querying the option database for the
106 window's other options (see Tk::options), and it will also be used
107 later for other purposes such as bindings. One typically assigns a
108 class to a TopLevel or Frame so that the class will apply to all of
109 that widget's children.
110 Reconfigurable options
112 These options can be set at widget creation or changed later via con‐
114 figure.
115 Name: activeBackground
117 Class: Foreground
118 Switch: -activebackground
119 Specifies background color to use when drawing active elements. An
120 element (a widget or portion of a widget) is active if the mouse
121 cursor is positioned over the element and pressing a mouse button
122 will cause some action to occur. If strict Motif compliance has
123 been requested by setting the $Tk::strictMotif variable, this
124 option will normally be ignored; the normal background color will
125 be used instead. For some elements on Windows and Macintosh sys‐
126 tems, the active color will only be used while mouse button 1 is
127 pressed over the element.
128 Name: activeBorderWidth
130 Class: BorderWidth
131 Switch: -activeborderwidth
132 Specifies a non-negative value indicating the width of the 3-D bor‐
133 der drawn around active elements. See above for definition of
134 active elements. The value may have any of the forms acceptable to
135 Tk_GetPixels. This option is typically only available in widgets
136 displaying more than one element at a time (e.g. menus but not but‐
137 tons).
138 Name: activeForeground
140 Class: Background
141 Switch: -activeforeground
142 Specifies foreground color to use when drawing active elements.
143 See above for definition of active elements.
144 Name: activetile
146 Class: Tile
147 Switch: -activetile
148 Specifies image used to display inside active elements of the wid‐
149 get. See above for definition of active elements.
150 Name: anchor
152 Class: Anchor
153 Switch: -anchor
154 Specifies how the information in a widget (e.g. text or a bitmap)
155 is to be displayed in the widget. Must be one of the values n, ne,
156 e, se, s, sw, w, nw, or center. For example, nw means display the
157 information such that its top-left corner is at the top-left corner
158 of the widget.
159 Name: background
161 Class: Background
162 Switch: -background
163 Alias: -bg
164 Specifies the normal background color to use when displaying the
165 widget.
166 Name: bitmap
168 Class: Bitmap
169 Switch: -bitmap
170 Specifies a bitmap to display in the widget, in any of the forms
171 acceptable to Tk_GetBitmap. The exact way in which the bitmap is
172 displayed may be affected by other options such as -anchor or -jus‐
173 tify. Typically, if this option is specified then it overrides
174 other options that specify a textual value to display in the wid‐
175 get; the -bitmap option may be reset to an empty string to re-
176 enable a text display. In widgets that support both -bitmap and
177 -image options, -image will usually override -bitmap.
178 Name: borderWidth
180 Class: BorderWidth
181 Switch: -borderwidth
182 Alias: -bd
183 Specifies a non-negative value indicating the width of the 3-D bor‐
184 der to draw around the outside of the widget (if such a border is
185 being drawn; the relief option typically determines this). The
186 value may also be used when drawing 3-D effects in the interior of
187 the widget. The value may have any of the forms acceptable to
188 Tk_GetPixels.
189 Name: compound
191 Class: Compound
192 Switch: -compound
193 Specifies if the widget should display text and bitmaps/images at
194 the same time, and if so, where the bitmap/image should be placed
195 relative to the text. Must be one of the values none, bottom, top,
196 left, right, or center. For example, the (default) value none spec‐
197 ifies that the bitmap or image should (if defined) be displayed
198 instead of the text, the value left specifies that the bitmap or
199 image should be displayed to the left of the text, and the value
200 center specifies that the bitmap or image should be displayed on
201 top of the text.
202 Name: cursor
204 Class: Cursor
205 Switch: -cursor
206 Specifies the mouse cursor to be used for the widget. The value
207 may have any of the forms acceptable to Tk_GetCursor.
208 Name: dash
210 Class: Dash
211 Switch: -dash
212 The value may have any of the forms accepted by Tk_GetDash, such as
213 4, [6,4], ., -, -., or -...
214 Name: dashoffset
216 Class: Dashoffset
217 Switch: -dashoffset
218 Specifies the offset in the dash list where the drawing starts.
219 Name: disabledForeground
221 Class: DisabledForeground
222 Switch: -disabledforeground
223 Specifies foreground color to use when drawing a disabled element.
224 If the option is specified as an empty string (which is typically
225 the case on monochrome displays), disabled elements are drawn with
226 the normal foreground color but they are dimmed by drawing them
227 with a stippled fill pattern.
228 Name: disabledtile
230 Class: Tile
231 Switch: -disabledtile
232 Specifies image to use when drawing a disabled element.
233 Name: exportSelection
235 Class: ExportSelection
236 Switch: -exportselection
237 Specifies whether or not a selection in the widget should also be
238 the X selection. The value may have any of the forms accepted by
239 Tcl_GetBoolean, such as true, false, 0, 1, yes, or no. If the
240 selection is exported, then selecting in the widget deselects the
241 current X selection, selecting outside the widget deselects any
242 widget selection, and the widget will respond to selection
243 retrieval requests when it has a selection. The default is usually
244 for widgets to export selections.
245 Name: font
247 Class: Font
248 Switch: -font
249 Specifies the font to use when drawing text inside the widget.
250 Name: foreground
252 Class: Foreground
253 Switch: -foreground
254 Alias: -fg
255 Specifies the normal foreground color to use when displaying the
256 widget.
257 Name: highlightBackground
259 Class: HighlightBackground
260 Switch: -highlightbackground
261 Specifies the color to display in the traversal highlight region
262 when the widget does not have the input focus.
263 Name: highlightColor
265 Class: HighlightColor
266 Switch: -highlightcolor
267 Specifies the color to use for the traversal highlight rectangle
268 that is drawn around the widget when it has the input focus.
269 Name: highlightThickness
271 Class: HighlightThickness
272 Switch: -highlightthickness
273 Specifies a non-negative value indicating the width of the high‐
274 light rectangle to draw around the outside of the widget when it
275 has the input focus. The value may have any of the forms accept‐
276 able to Tk_GetPixels. If the value is zero, no focus highlight is
277 drawn around the widget.
278 Name: image
280 Class: Image
281 Switch: -image
282 Specifies an image to display in the widget, which must have been
283 created with an image create. (See Tk::Image for details of image
284 creation.) Typically, if the -image option is specified then it
285 overrides other options that specify a bitmap or textual value to
286 display in the widget; the -image option may be reset to an empty
287 string to re-enable a bitmap or text display.
288 Name: insertBackground
290 Class: Foreground
291 Switch: -insertbackground
292 Specifies the color to use as background in the area covered by the
293 insertion cursor. This color will normally override either the
294 normal background for the widget (or the selection background if
295 the insertion cursor happens to fall in the selection).
296 Name: insertBorderWidth
298 Class: BorderWidth
299 Switch: -insertborderwidth
300 Specifies a non-negative value indicating the width of the 3-D bor‐
301 der to draw around the insertion cursor. The value may have any of
302 the forms acceptable to Tk_GetPixels.
303 Name: insertOffTime
305 Class: OffTime
306 Switch: -insertofftime
307 Specifies a non-negative integer value indicating the number of
308 milliseconds the insertion cursor should remain ``off'' in each
309 blink cycle. If this option is zero then the cursor doesn't blink:
310 it is on all the time.
311 Name: insertOnTime
313 Class: OnTime
314 Switch: -insertontime
315 Specifies a non-negative integer value indicating the number of
316 milliseconds the insertion cursor should remain ``on'' in each
317 blink cycle.
318 Name: insertWidth
320 Class: InsertWidth
321 Switch: -insertwidth
322 Specifies a value indicating the total width of the insertion cur‐
323 sor. The value may have any of the forms acceptable to Tk_GetPix‐
324 els. If a border has been specified for the insertion cursor
325 (using the insertBorderWidth option), the border will be drawn
326 inside the width specified by the insertWidth option.
327 Name: jump
329 Class: Jump
330 Switch: -jump
331 For widgets with a slider that can be dragged to adjust a value,
332 such as scrollbars, this option determines when notifications are
333 made about changes in the value. The option's value must be a
334 boolean of the form accepted by Tcl_GetBoolean. If the value is
335 false, updates are made continuously as the slider is dragged. If
336 the value is true, updates are delayed until the mouse button is
337 released to end the drag; at that point a single notification is
338 made (the value ``jumps'' rather than changing smoothly).
339 Name: justify
341 Class: Justify
342 Switch: -justify
343 When there are multiple lines of text displayed in a widget, this
344 option determines how the lines line up with each other. Must be
345 one of left, center, or right. Left means that the lines' left
346 edges all line up, center means that the lines' centers are
347 aligned, and right means that the lines' right edges line up.
348 Name: offset
350 Class: Offset
351 Switch: -offset
352 Specifies the offset of tiles (see also -tile option). It can have
353 two different formats -offset x,y or -offset side, where side can
354 be n, ne, e, se, s, sw, w, nw, or center. In the first case the
355 origin is the origin of the toplevel of the current window. For
356 the canvas itself and canvas objects the origin is the canvas ori‐
357 gin, but putting # in front of the coordinate pair indicates using
358 the toplevel origin in stead. For canvas objects, the -offset
359 option is used for stippling as well. For the line and polygon
360 canvas items you can also specify an index as argument, which con‐
361 nects the stipple or tile origin to one of the coordinate points of
362 the line/polygon.
363 Name: orient
365 Class: Orient
366 Switch: -orient
367 For widgets that can lay themselves out with either a horizontal or
368 vertical orientation, such as scrollbars, this option specifies
369 which orientation should be used. Must be either horizontal or
370 vertical or an abbreviation of one of these.
371 Name: padX
373 Class: Pad
374 Switch: -padx
375 Specifies a non-negative value indicating how much extra space to
376 request for the widget in the X-direction. The value may have any
377 of the forms acceptable to Tk_GetPixels. When computing how large
378 a window it needs, the widget will add this amount to the width it
379 would normally need (as determined by the width of the things dis‐
380 played in the widget); if the geometry manager can satisfy this
381 request, the widget will end up with extra internal space to the
382 left and/or right of what it displays inside. Most widgets only
383 use this option for padding text: if they are displaying a bitmap
384 or image, then they usually ignore padding options.
385 Name: padY
387 Class: Pad
388 Switch: -pady
389 Specifies a non-negative value indicating how much extra space to
390 request for the widget in the Y-direction. The value may have any
391 of the forms acceptable to Tk_GetPixels. When computing how large
392 a window it needs, the widget will add this amount to the height it
393 would normally need (as determined by the height of the things dis‐
394 played in the widget); if the geometry manager can satisfy this
395 request, the widget will end up with extra internal space above
396 and/or below what it displays inside. Most widgets only use this
397 option for padding text: if they are displaying a bitmap or image,
398 then they usually ignore padding options.
399 Name: relief
401 Class: Relief
402 Switch: -relief
403 Specifies the 3-D effect desired for the widget. Acceptable values
404 are raised, sunken, flat, ridge, solid, and groove. The value
405 indicates how the interior of the widget should appear relative to
406 its exterior; for example, raised means the interior of the widget
407 should appear to protrude from the screen, relative to the exterior
408 of the widget.
409 Name: repeatDelay
411 Class: RepeatDelay
412 Switch: -repeatdelay
413 Specifies the number of milliseconds a button or key must be held
414 down before it begins to auto-repeat. Used, for example, on the
415 up- and down-arrows in scrollbars.
416 Name: repeatInterval
418 Class: RepeatInterval
419 Switch: -repeatinterval
420 Used in conjunction with repeatDelay: once auto-repeat begins,
421 this option determines the number of milliseconds between
422 auto-repeats.
423 Name: selectBackground
425 Class: Foreground
426 Switch: -selectbackground
427 Specifies the background color to use when displaying selected
428 items.
429 Name: selectBorderWidth
431 Class: BorderWidth
432 Switch: -selectborderwidth
433 Specifies a non-negative value indicating the width of the 3-D bor‐
434 der to draw around selected items. The value may have any of the
435 forms acceptable to Tk_GetPixels.
436 Name: selectForeground
438 Class: Background
439 Switch: -selectforeground
440 Specifies the foreground color to use when displaying selected
441 items.
442 Name: setGrid
444 Class: SetGrid
445 Switch: -setgrid
446 Specifies a boolean value that determines whether this widget con‐
447 trols the resizing grid for its top-level window. This option is
448 typically used in text widgets, where the information in the widget
449 has a natural size (the size of a character) and it makes sense for
450 the window's dimensions to be integral numbers of these units.
451 These natural window sizes form a grid. If the setGrid option is
452 set to true then the widget will communicate with the window man‐
453 ager so that when the user interactively resizes the top-level win‐
454 dow that contains the widget, the dimensions of the window will be
455 displayed to the user in grid units and the window size will be
456 constrained to integral numbers of grid units. See "GRIDDED GEOME‐
457 TRY MANAGEMENT" in Tk::Wm for more details.
458 Name: takeFocus
460 Class: TakeFocus
461 Switch: -takefocus
462 Determines whether the window accepts the focus during keyboard
463 traversal (e.g., Tab and Shift-Tab). Before setting the focus to a
464 window, the traversal scripts consult the value of the takeFocus
465 option. A value of 0 means that the window should be skipped
466 entirely during keyboard traversal. 1 means that the window should
467 receive the input focus as long as it is viewable (it and all of
468 its ancestors are mapped). An empty value for the option means
469 that the traversal scripts make the decision about whether or not
470 to focus on the window: the current algorithm is to skip the win‐
471 dow if it is disabled, if it has no key bindings, or if it is not
472 viewable. If the value has any other form, then the traversal
473 scripts take the value, append the name of the window to it (with a
474 separator space), and evaluate the resulting string as a Callback.
475 The script must return 0, 1, or an empty string: a 0 or 1 value
476 specifies whether the window will receive the input focus, and an
477 empty string results in the default decision described above.
478 Note: this interpretation of the option is defined entirely by the
479 Callbacks that implement traversal: the widget implementations
480 ignore the option entirely, so you can change its meaning if you
481 redefine the keyboard traversal scripts.
482 Name: text
484 Class: Text
485 Switch: -text
486 Specifies a string to be displayed inside the widget. The way in
487 which the string is displayed depends on the particular widget and
488 may be determined by other options, such as anchor or justify.
489 Name: textVariable
491 Class: Variable
492 Switch: -textvariable
493 Specifies the name of a variable. The value of the variable is a
494 text string to be displayed inside the widget; if the variable
495 value changes then the widget will automatically update itself to
496 reflect the new value. The way in which the string is displayed in
497 the widget depends on the particular widget and may be determined
498 by other options, such as anchor or justify.
499 Name: tile
501 Class: Tile
502 Switch: -tile
503 Specifies image used to display the widget. If image is the empty
504 string, then the normal background color is displayed.
505 Name: troughColor
507 Class: Background
508 Switch: -troughcolor
509 Specifies the color to use for the rectangular trough areas in wid‐
510 gets such as scrollbars and scales.
511 Name: troughTile
513 Class: Tile
514 Switch: -troughtile
515 Specifies image used to display in the rectangular trough areas in
516 widgets such as scrollbars and scales.
517 Name: underline
519 Class: Underline
520 Switch: -underline
521 Specifies the integer index of a character to underline in the wid‐
522 get. This option is used by the default bindings to implement key‐
523 board traversal for menu buttons and menu entries. 0 corresponds
524 to the first character of the text displayed in the widget, 1 to
525 the next character, and so on.
526 Name: wrapLength
528 Class: WrapLength
529 Switch: -wraplength
530 For widgets that can perform word-wrapping, this option specifies
531 the maximum line length. Lines that would exceed this length are
532 wrapped onto the next line, so that no line is longer than the
533 specified length. The value may be specified in any of the stan‐
534 dard forms for screen distances. If this value is less than or
535 equal to 0 then no wrapping is done: lines will break only at new‐
536 line characters in the text.
537 Name: xScrollCommand
539 Class: ScrollCommand
540 Switch: -xscrollcommand
541 Specifies a callback used to communicate with horizontal scroll‐
542 bars. When the view in the widget's window changes (or whenever
543 anything else occurs that could change the display in a scrollbar,
544 such as a change in the total size of the widget's contents), the
545 widget will make a callback passing two numeric arguments in addi‐
546 tion to any specified in the callback. Each of the numbers is a
547 fraction between 0 and 1, which indicates a position in the docu‐
548 ment. 0 indicates the beginning of the document, 1 indicates the
549 end, .333 indicates a position one third the way through the docu‐
550 ment, and so on. The first fraction indicates the first informa‐
551 tion in the document that is visible in the window, and the second
552 fraction indicates the information just after the last portion that
553 is visible. Typically the xScrollCommand option consists of the
554 scrollbar widget object and the method ``set'' i.e. [set => $sb]:
555 this will cause the scrollbar to be updated whenever the view in
556 the window changes. If this option is not specified, then no com‐
557 mand will be executed.
558 Name: yScrollCommand
560 Class: ScrollCommand
561 Switch: -yscrollcommand
562 Specifies a calback used to communicate with vertical scrollbars.
563 This option is treated in the same way as the xScrollCommand
564 option, except that it is used for vertical scrollbars and is pro‐
565 vided by widgets that support vertical scrolling. See the descrip‐
566 tion of xScrollCommand for details on how this option is used.
567
569 Tk::option Tk::callbacks Tk::ConfigSpecs Tk_GetPixels
570
572 class, name, standard option, switch
573perl v5.8.8 2008-02-05 options(3)