1options(3)            User Contributed Perl Documentation           options(3)
2
3
4

NAME

6       Tk::options - Standard options supported by widgets and their
7       manipulation
8

SYNOPSIS

10           $value = $widget->cget('-option');
11
12           $widget->configure(-option=>value ?,-option=>value ...?);
13
14           @list = $widget->configure('-option');
15
16           @lol = $widget->configure;
17

DESCRIPTION

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
23       $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
28       $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
35           Option Name
36                   The value of -option, e.g., -background.
37
38           Name    The option's name in the option database, e.g.,
39                   "background".
40
41           Class   The option's class value in the option database, e.g.,
42                   "Background".
43
44           Default The default value for the option if not specified or in the
45                   option database, e.g., "grey".
46
47           Value   The current value (as returned by cget), e.g., "white".
48
49       $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
55       $widget->cget('-option')
56           Returns the current value of -option for $widget.
57
58           cget('-option') is clumsy with the need for '' due to perl's
59           parsing rules. Something more subtle using tie might look better.
60
61       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
68       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
75           $widget->configure(-foreground=>'black')
76
77       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
81   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
88       Name:     name
89       Switch:   Name
90           Specifies the path element for the widget.  Names generally begin
91           with a lowercase letter.
92
93           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
99       Name:     class
100       Switch:   -class
101           Specifies a class for the window.  Classes generally begin with an
102           uppercase letter.
103
104           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
110   Reconfigurable options
111       These options can be set at widget creation or changed later via
112       configure.
113
114       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
127       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
137       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
143       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
149       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
158       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
165       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
177       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
188       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
201       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
207       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
213       Name:     dashoffset
214       Class:    Dashoffset
215       Switch:   -dashoffset
216           Specifies the offset in the dash list where the drawing starts.
217
218       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
227       Name:     disabledtile
228       Class:    Tile
229       Switch:   -disabledtile
230           Specifies image to use when drawing a disabled element.
231
232       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
244       Name:     font
245       Class:    Font
246       Switch:   -font
247           Specifies the font to use when drawing text inside the widget.
248
249       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
256       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
262       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
268       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
277       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
287       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
295       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
302       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
310       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
317       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
326       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
338       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
347       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
362       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
370       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
384       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
398       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
408       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
415       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
422       Name:     selectBackground
423       Class:    Foreground
424       Switch:   -selectbackground
425           Specifies the background color to use when displaying selected
426           items.
427
428       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
435       Name:     selectForeground
436       Class:    Background
437       Switch:   -selectforeground
438           Specifies the foreground color to use when displaying selected
439           items.
440
441       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
457       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
481       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
488       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
498       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
504       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
510       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
516       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
525       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
536       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
557       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

SEE ALSO

568       Tk::option Tk::callbacks Tk::ConfigSpecs Tk_GetPixels
569

KEYWORDS

571       class, name, standard option, switch
572
573
574
575perl v5.12.0                      2010-05-13                        options(3)
Impressum