1options(n)                   Tk Built-In Commands                   options(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       options - Standard options supported by widgets
9_________________________________________________________________
10
11

DESCRIPTION

13       This  manual entry describes the common configuration options supported
14       by widgets in the Tk toolkit.  Every widget does not  necessarily  sup‐
15       port  every option (see the manual entries for individual widgets for a
16       list of the standard options supported by that widget), but if a widget
17       does  support  an  option  with one of the names listed below, then the
18       option has exactly the effect described below.
19
20       In the descriptions below, “Command-Line Name”  refers  to  the  switch
21       used in class commands and configure widget commands to set this value.
22       For example, if an option's  command-line  switch  is  -foreground  and
23       there exists a widget .a.b.c, then the command
24              .a.b.c  configure  -foreground black
25       may  be  used  to  specify the value black for the option in the widget
26       .a.b.c.  Command-line switches may  be  abbreviated,  as  long  as  the
27       abbreviation  is  unambiguous.   “Database Name” refers to the option's
28       name in the option database  (e.g.  in  .Xdefaults  files).   “Database
29       Class”  refers  to  the  option's  class  value in the option database.
30       [-activebackground activeBackground] Specifies background color to  use
31       when  drawing  active  elements.   An element (a widget or portion of a
32       widget) is active if the mouse cursor is positioned  over  the  element
33       and pressing a mouse button will cause some action to occur.  If strict
34       Motif compliance has been requested by setting the tk_strictMotif vari‐
35       able,  this  option  will  normally  be ignored;  the normal background
36       color will be used instead.  For some elements on Windows and Macintosh
37       systems,  the  active  color  will only be used while mouse button 1 is
38       pressed over the element.  [-activeborderwidth activeBorderWidth] Spec‐
39       ifies a non-negative value indicating the width of the 3-D border drawn
40       around active elements.  See above for definition of  active  elements.
41       The  value  may have any of the forms acceptable to Tk_GetPixels.  This
42       option is typically only available in widgets displaying more than  one
43       element  at  a  time  (e.g.  menus  but  not  buttons).   [-activefore‐
44       ground activeForeground] Specifies foreground color to use when drawing
45       active   elements.   See  above  for  definition  of  active  elements.
46       [-anchor anchor] Specifies how the information in a widget  (e.g.  text
47       or a bitmap) is to be displayed in the widget.  Must be one of the val‐
48       ues n, ne, e, se, s, sw, w, nw, or center.  For example, nw means  dis‐
49       play  the  information such that its top-left corner is at the top-left
50       corner of the widget.  [-background or  -bg background]  Specifies  the
51       normal  background  color  to  use  when displaying the widget.  [-bit‐
52       map bitmap] Specifies a bitmap to display in the widget, in any of  the
53       forms acceptable to Tk_GetBitmap.  The exact way in which the bitmap is
54       displayed may be affected by other options such as anchor  or  justify.
55       Typically,  if this option is specified then it overrides other options
56       that specify a textual value to display in the widget but this is  con‐
57       trolled  by  the  compound option; the bitmap option may be reset to an
58       empty string to re-enable a text display.  In widgets that support both
59       bitmap  and  image options, image will usually override bitmap.  [-bor‐
60       derwidth or -bd borderWidth] Specifies a non-negative value  indicating
61       the  width  of  the 3-D border to draw around the outside of the widget
62       (if such a border is being drawn;  the relief option  typically  deter‐
63       mines  this).   The  value may also be used when drawing 3-D effects in
64       the interior of the widget.  The  value  may  have  any  of  the  forms
65       acceptable  to Tk_GetPixels.  [-cursor cursor] Specifies the mouse cur‐
66       sor to be used for the widget.  The value may have  any  of  the  forms
67       acceptable  to Tk_GetCursor.  In addition, if an empty string is speci‐
68       fied, it indicates that the widget should defer to its parent for  cur‐
69       sor specification.  [-compound compound] Specifies if the widget should
70       display text and bitmaps/images at the same time, and if so, where  the
71       bitmap/image should be placed relative to the text.  Must be one of the
72       values none, bottom, top, left, right, or  center.   For  example,  the
73       (default)  value  none  specifies  that  the bitmap or image should (if
74       defined) be displayed instead of the text,  the  value  left  specifies
75       that  the  bitmap or image should be displayed to the left of the text,
76       and the value center specifies that the bitmap or image should be  dis‐
77       played  on  top  of the text.  [-disabledforeground disabledForeground]
78       Specifies foreground color to use when drawing a disabled element.   If
79       the option is specified as an empty string (which is typically the case
80       on monochrome displays), disabled elements are drawn  with  the  normal
81       foreground  color  but  they are dimmed by drawing them with a stippled
82       fill pattern.  [-exportselection exportSelection] Specifies whether  or
83       not  a  selection  in  the  widget should also be the X selection.  The
84       value may have any of the forms accepted  by  Tcl_GetBoolean,  such  as
85       true,  false,  0,  1,  yes,  or no.  If the selection is exported, then
86       selecting in the widget deselects the current  X  selection,  selecting
87       outside  the widget deselects any widget selection, and the widget will
88       respond to selection retrieval requests when it has a  selection.   The
89       default  is  usually  for  widgets  to export selections.  [-font font]
90       Specifies the font to use when drawing text  inside  the  widget.   The
91       value may have any of the forms described in the font manual page under
92       FONT DESCRIPTION.  [-foreground or -fg foreground] Specifies the normal
93       foreground  color  to use when displaying the widget.  [-highlightback‐
94       ground highlightBackground] Specifies the color to display in the  tra‐
95       versal  highlight region when the widget does not have the input focus.
96       [-highlightcolor highlightColor] Specifies the color  to  use  for  the
97       traversal  highlight  rectangle that is drawn around the widget when it
98       has the input focus.   [-highlightthickness highlightThickness]  Speci‐
99       fies a non-negative value indicating the width of the highlight rectan‐
100       gle to draw around the outside of the widget  when  it  has  the  input
101       focus.  The value may have any of the forms acceptable to Tk_GetPixels.
102       If the value is zero, no focus highlight is drawn  around  the  widget.
103       [-image image]  Specifies an image to display in the widget, which must
104       have been created with the image create  command.   Typically,  if  the
105       image  option is specified then it overrides other options that specify
106       a bitmap or textual value to display in the widget, though this is con‐
107       trolled  by  the  compound  option; the image option may be reset to an
108       empty string to re-enable a  bitmap  or  text  display.   [-insertback‐
109       ground insertBackground]  Specifies  the  color to use as background in
110       the area covered by the insertion cursor.   This  color  will  normally
111       override  either the normal background for the widget (or the selection
112       background if the insertion cursor happens to fall in  the  selection).
113       [-insertborderwidth insertBorderWidth]  Specifies  a non-negative value
114       indicating the width of the 3-D border to  draw  around  the  insertion
115       cursor.   The  value may have any of the forms acceptable to Tk_GetPix‐
116       els.  [-insertofftime insertOffTime] Specifies a  non-negative  integer
117       value indicating the number of milliseconds the insertion cursor should
118       remain “off” in each blink cycle.  If this option is zero then the cur‐
119       sor  does  not blink:  it is on all the time.  [-insertontime insertOn‐
120       Time] Specifies a non-negative integer value indicating the  number  of
121       milliseconds  the  insertion  cursor  should  remain “on” in each blink
122       cycle.  [-insertwidth insertWidth] Specifies a   value  indicating  the
123       total  width  of  the  insertion cursor.  The value may have any of the
124       forms acceptable to Tk_GetPixels.  If a border has been  specified  for
125       the  insertion  cursor (using the insertBorderWidth option), the border
126       will be drawn inside the width specified  by  the  insertWidth  option.
127       [-jump jump]  For widgets with a slider that can be dragged to adjust a
128       value, such as scrollbars, this option  determines  when  notifications
129       are  made  about  changes  in  the value.  The option's value must be a
130       boolean of the form accepted by Tcl_GetBoolean.  If the value is false,
131       updates  are  made continuously as the slider is dragged.  If the value
132       is true, updates are delayed until the mouse button is released to  end
133       the  drag;   at  that  point  a  single notification is made (the value
134       “jumps” rather than changing smoothly).  [-justify justify] When  there
135       are  multiple  lines  of text displayed in a widget, this option deter‐
136       mines how the lines line up with each other.  Must be one of left, cen‐
137       ter, or right.  Left means that the lines' left edges all line up, cen‐
138       ter means that the lines' centers are aligned, and right means that the
139       lines'  right edges line up.  [-orient orient] For widgets that can lay
140       themselves out with either a horizontal or vertical  orientation,  such
141       as  scrollbars, this option specifies which orientation should be used.
142       Must be either horizontal or vertical or  an  abbreviation  of  one  of
143       these.  [-padx padX] Specifies a non-negative value indicating how much
144       extra space to request for the widget in the  X-direction.   The  value
145       may  have  any of the forms acceptable to Tk_GetPixels.  When computing
146       how large a window it needs, the widget will add  this  amount  to  the
147       width  it would normally need (as determined by the width of the things
148       displayed in the widget);  if the geometry  manager  can  satisfy  this
149       request,  the  widget will end up with extra internal space to the left
150       and/or right of what it displays inside.  Most widgets  only  use  this
151       option  for  padding  text:   if they are displaying a bitmap or image,
152       then they usually ignore padding  options.   [-pady padY]  Specifies  a
153       non-negative  value  indicating how much extra space to request for the
154       widget in the Y-direction.  The value may have any of the forms accept‐
155       able  to Tk_GetPixels.  When computing how large a window it needs, the
156       widget will add this amount to the height it would  normally  need  (as
157       determined  by  the  height of the things displayed in the widget);  if
158       the geometry manager can satisfy this request, the widget will  end  up
159       with  extra  internal space above and/or below what it displays inside.
160       Most widgets only use this option for padding text:  if they  are  dis‐
161       playing  a  bitmap  or image, then they usually ignore padding options.
162       [-relief relief] Specifies the  3-D  effect  desired  for  the  widget.
163       Acceptable  values  are raised, sunken, flat, ridge, solid, and groove.
164       The value indicates how the interior of the widget should appear  rela‐
165       tive  to  its  exterior;  for example, raised means the interior of the
166       widget should appear to protrude from the screen, relative to the exte‐
167       rior of the widget.  [-repeatdelay repeatDelay] Specifies the number of
168       milliseconds a button or key must be held  down  before  it  begins  to
169       auto-repeat.   Used, for example, on the up- and down-arrows in scroll‐
170       bars.   [-repeatinterval repeatInterval]  Used  in   conjunction   with
171       repeatDelay:   once auto-repeat begins, this option determines the num‐
172       ber of milliseconds between  auto-repeats.   [-selectbackground select‐
173       Background]  Specifies  the  background  color  to  use when displaying
174       selected  items.   [-selectborderwidth selectBorderWidth]  Specifies  a
175       non-negative  value  indicating  the  width  of  the 3-D border to draw
176       around selected items.  The value may have any of the forms  acceptable
177       to  Tk_GetPixels.   [-selectforeground selectForeground]  Specifies the
178       foreground color to use when displaying selected items.  [-setgrid set‐
179       Grid]  Specifies  a  boolean  value that determines whether this widget
180       controls the resizing grid for its top-level window.   This  option  is
181       typically used in text widgets, where the information in the widget has
182       a natural size (the size of a character) and it  makes  sense  for  the
183       window's dimensions to be integral numbers of these units.  These natu‐
184       ral window sizes form a grid.  If the setGrid option  is  set  to  true
185       then  the  widget will communicate with the window manager so that when
186       the user interactively resizes the top-level window that  contains  the
187       widget,  the  dimensions of the window will be displayed to the user in
188       grid units and the window size will be constrained to integral  numbers
189       of  grid  units.  See the section GRIDDED GEOMETRY MANAGEMENT in the wm
190       manual  entry  for  more  details.   [-takefocus takeFocus]  Determines
191       whether  the  window accepts the focus during keyboard traversal (e.g.,
192       Tab and Shift-Tab).  Before setting the focus to a window, the  traver‐
193       sal  scripts  consult  the value of the takeFocus option.  A value of 0
194       means that the window should be skipped entirely during  keyboard  tra‐
195       versal.  1 means that the window should receive the input focus as long
196       as it is viewable (it and all of its ancestors are mapped).   An  empty
197       value for the option means that the traversal scripts make the decision
198       about whether or not to focus on the window:  the current algorithm  is
199       to  skip the window if it is disabled, if it has no key bindings, or if
200       it is not viewable.  If the value has any other form, then the  traver‐
201       sal scripts take the value, append the name of the window to it (with a
202       separator space), and evaluate the resulting string as  a  Tcl  script.
203       The script must return 0, 1, or an empty string:  a 0 or 1 value speci‐
204       fies whether the window will receive the  input  focus,  and  an  empty
205       string  results  in  the  default decision described above.  Note: this
206       interpretation of the option is defined entirely  by  the  Tcl  scripts
207       that implement traversal:  the widget implementations ignore the option
208       entirely, so you can change its meaning if you  redefine  the  keyboard
209       traversal  scripts.   [-text text]  Specifies  a string to be displayed
210       inside the widget.  The way in which the string is displayed depends on
211       the  particular  widget and may be determined by other options, such as
212       anchor or justify.  [-textvariable textVariable] Specifies the name  of
213       a variable.  The value of the variable is a text string to be displayed
214       inside the widget;  if the variable value changes then the widget  will
215       automatically update itself to reflect the new value.  The way in which
216       the string is displayed in the widget depends on the particular  widget
217       and  may  be  determined  by  other options, such as anchor or justify.
218       [-troughcolor troughColor] Specifies the color to use for the rectangu‐
219       lar trough areas in widgets such as scrollbars and scales.  This option
220       is ignored for scrollbars on Windows (native widget does not  recognize
221       this  option).  [-underline underline] Specifies the integer index of a
222       character to underline in the widget.   This  option  is  used  by  the
223       default  bindings  to implement keyboard traversal for menu buttons and
224       menu entries.  0 corresponds to the first character of  the  text  dis‐
225       played   in   the   widget,  1  to  the  next  character,  and  so  on.
226       [-wraplength wrapLength] For widgets that  can  perform  word-wrapping,
227       this option specifies the maximum line length.  Lines that would exceed
228       this length are wrapped onto the next line, so that no line  is  longer
229       than  the  specified  length.  The value may be specified in any of the
230       standard forms for screen distances.  If this value  is  less  than  or
231       equal  to 0 then no wrapping is done:  lines will break only at newline
232       characters in the text.  [-xscrollcommand xScrollCommand] Specifies the
233       prefix  for  a  command used to communicate with horizontal scrollbars.
234       When the view in the widget's window changes (or whenever anything else
235       occurs  that  could change the display in a scrollbar, such as a change
236       in the total size of the widget's contents), the widget will generate a
237       Tcl  command by concatenating the scroll command and two numbers.  Each
238       of the numbers is a fraction between 0 and 1, which indicates  a  posi‐
239       tion  in  the  document.   0 indicates the beginning of the document, 1
240       indicates the end, .333 indicates a position one third the way  through
241       the document, and so on.  The first fraction indicates the first infor‐
242       mation in the document that is visible in the window,  and  the  second
243       fraction  indicates the information just after the last portion that is
244       visible.  The command is then passed to the Tcl interpreter for  execu‐
245       tion.  Typically the xScrollCommand option consists of the path name of
246       a scrollbar widget followed by “set”, e.g.   “.x.scrollbar  set”:  this
247       will  cause the scrollbar to be updated whenever the view in the window
248       changes.  If this option is not specified, then no command will be exe‐
249       cuted.   [-yscrollcommand yScrollCommand]  Specifies  the  prefix for a
250       command used to communicate with vertical scrollbars.  This  option  is
251       treated in the same way as the xScrollCommand option, except that it is
252       used for vertical scrollbars and is provided by  widgets  that  support
253       vertical  scrolling.  See the description of xScrollCommand for details
254       on how this option is used.
255
256

SEE ALSO

258       colors, cursors, font
259
260

KEYWORDS

262       class, name, standard option, switch
263
264
265
266Tk                                    4.4                           options(n)
Impressum