


options(n)             Tk Built-In Commands            options(n)


NAME
       options - Standard options supported by widgets


DESCRIPTION
       This  manual entry describes the common configuration options supported
       by widgets in the Tk toolkit.  Every widget does not  necessarily  sup-
       port  every option (see the manual entries for individual widgets for a
       list of the standard options supported by that widget), but if a widget
       does  support  an  option  with one of the names listed below, then the
       option has exactly the effect described below.

       In the descriptions below, ``Command-Line Name'' refers to  the  switch
       used in class commands and configure widget commands to set this value.
       For example, if an option's  command-line  switch  is  :foreground  and
       there     exists     a     widget     .a.b.c,    then    the    command
       (.a.b.c  'configure  :foreground "black") may be used  to  specify  the
       value  black  for  the  option  in the the widget .a.b.c.  Command-line
       switches may be abbreviated, as long as the abbreviation  is  unambigu-
       ous.  ``Name'' refers to the option's name in the option database (e.g.
       in .Xdefaults files).  ``Class'' refers to the option's class value  in
       the  option  database.  For each option, the STklos name is also speci-
       fied. The STklos name is usually the same as the  option  name,  except
       when  it  is a composite word, in which case words are separated with a
       dash.


       Specifies background color to use when  drawing  active  elements.   An
       element (a widget or portion of a widget) is active if the mouse cursor
       is positioned over the element and pressing a mouse button  will  cause
       some action to occur.  If strict Motif compliance has been requested by
       setting the *tk-strict-motif* variable, this option  will  normally  be
       ignored;   the  normal background color will be used instead.  For some
       elements on Windows  systems, the active color will only be used  while
       mouse  button  1 is pressed over the element.  Specifies a non-negative
       value indicating the width of the 3-D border drawn around  active  ele-
       ments.   See  above  for  definition of active elements.  The value may
       have any of the forms acceptable to Tk_GetPixels.  This option is typi-
       cally  only  available in widgets displaying more than one element at a
       time (e.g. menus but not buttons).  Specifies foreground color  to  use
       when  drawing active elements.  See above for definition of active ele-
       ments.  Specifies how the information in  a  widget  (e.g.  text  or  a
       bitmap) is to be displayed in the widget.  Must be one of the values n,
       ne, e, se, s, sw, w, nw, or center.  For example, nw means display  the
       information  such that its top-left corner is at the top-left corner of
       the widget.  Specifies the normal background color to use when display-
       ing  the widget. This option can also be specified as :bg.  Specifies a
       bitmap to display in the widget, in any  of  the  forms  acceptable  to
       Tk_GetBitmap.   The  exact  way in which the bitmap is displayed may be
       affected by other options such as anchor  or  justify.   Typically,  if
       this option is specified then it overrides other options that specify a
       textual value to display in the widget; the bitmap option may be  reset
       to  an  empty string to re-enable a text display.  In widgets that sup-
       port both bitmap and image options, image will usually override bitmap.



STk                            4.0                              1





options(n)             Tk Built-In Commands            options(n)


       Specifies  a  non-negative value indicating the width of the 3-D border
       to draw around the outside of the widget (if such  a  border  is  being
       drawn;   the  relief  option typically determines this).  The value may
       also be used when drawing 3-D effects in the interior  of  the  widget.
       The  value  may have any of the forms acceptable to Tk_GetPixels.  This
       option can also be specified as :bd.  Specifies the mouse cursor to  be
       used for the widget.  The value may have any of the forms acceptable to
       Tk_GetCursor.  Specifies foreground color to use when  drawing  a  dis-
       abled element.  If the option is specified as an empty string (which is
       typically the case on monochrome displays), disabled elements are drawn
       with  the  normal  foreground color but they are dimmed by drawing them
       with a stippled fill pattern.  Specifies whether or not a selection  in
       the widget should also be the X selection.  The value must be a boolean
       value. If the selection is exported, then selecting in the widget dese-
       lects  the  current X selection, selecting outside the widget deselects
       any  widget  selection,  and  the  widget  will  respond  to  selection
       retrieval requests when it has a selection.  The default is usually for
       widgets to export selections.  Specifies the font to use  when  drawing
       text  inside  the widget.  Specifies the normal foreground color to use
       when displaying the widget.  This option can also be specified as  :fg.
       Specifies  the  color to display in the traversal highlight region when
       the widget does not have the input focus.  Specifies the color  to  use
       for  the  traversal highlight rectangle that is drawn around the widget
       when it has the input focus.  Specifies a non-negative value indicating
       the  width of the highlight rectangle to draw around the outside of the
       widget when it has the input focus.  The value  may  have  any  of  the
       forms acceptable to Tk_GetPixels.  If the value is zero, no focus high-
       light is drawn around the widget.  Specifies an image to display in the
       widget,  which  must  have  been created with the image create command.
       Typically, if the image option is specified  then  it  overrides  other
       options  that  specify a bitmap or textual value to display in the wid-
       get; the image option may be reset to an empty string  to  re-enable  a
       bitmap  or  text  display.  Specifies the color to use as background in
       the area covered by the insertion cursor.   This  color  will  normally
       override  either the normal background for the widget (or the selection
       background if the insertion cursor happens to fall in  the  selection).
       Specifies  a  non-negative value indicating the width of the 3-D border
       to draw around the insertion cursor.  The value may  have  any  of  the
       forms  acceptable  to  Tk_GetPixels.   Specifies a non-negative integer
       value indicating the number of milliseconds the insertion cursor should
       remain  ``off''  in  each blink cycle.  If this option is zero then the
       cursor doesn't blink:  it is on all the time.  Specifies a non-negative
       integer  value indicating the number of milliseconds the insertion cur-
       sor should remain ``on'' in each blink cycle.  Specifies a  value indi-
       cating the total width of the insertion cursor.  The value may have any
       of the forms acceptable to Tk_GetPixels.  If a border has  been  speci-
       fied for the insertion cursor (using the insertBorderWidth option), the
       border will be drawn inside the  width  specified  by  the  insertWidth
       option.   For  widgets  with  a  slider that can be dragged to adjust a
       value, such as scrollbars, this option  determines  when  notifications
       are  made  about  changes  in  the value.  The option's value must be a
       boolean of the form accepted by Tcl_GetBoolean.  If the value is false,
       updates  are  made continuously as the slider is dragged.  If the value
       is true, updates are delayed until the mouse button is released to  end



STk                            4.0                              2





options(n)             Tk Built-In Commands            options(n)


       the  drag;   at  that  point  a  single notification is made (the value
       ``jumps'' rather than changing  smoothly).   When  there  are  multiple
       lines  of  text  displayed  in a widget, this option determines how the
       lines line up with each other.  Must be one of left, center, or  right.
       Left  means  that  the lines' left edges all line up, center means that
       the lines' centers are aligned, and right means that the  lines'  right
       edges  line  up.  For widgets that can lay themselves out with either a
       horizontal or vertical orientation, such  as  scrollbars,  this  option
       specifies  which orientation should be used.  Must be either horizontal
       or vertical or an abbreviation of one of these.  Specifies a  non-nega-
       tive value indicating how much extra space to request for the widget in
       the X-direction.  The value may have any of  the  forms  acceptable  to
       Tk_GetPixels.   When  computing how large a window it needs, the widget
       will add this amount to the width it would normally need (as determined
       by  the  width of the things displayed in the widget);  if the geometry
       manager can satisfy this request, the widget will  end  up  with  extra
       internal  space  to  the  left and/or right of what it displays inside.
       Most widgets only use this option for padding text:  if they  are  dis-
       playing  a  bitmap  or image, then they usually ignore padding options.
       Specifies a non-negative value  indicating  how  much  extra  space  to
       request  for  the widget in the Y-direction.  The value may have any of
       the forms acceptable to Tk_GetPixels.  When computing how large a  win-
       dow  it  needs,  the widget will add this amount to the height it would
       normally need (as determined by the height of the things  displayed  in
       the  widget);   if  the  geometry manager can satisfy this request, the
       widget will end up with extra internal space above and/or below what it
       displays  inside.   Most widgets only use this option for padding text:
       if they are displaying a bitmap or  image,  then  they  usually  ignore
       padding  options.   Specifies  the  3-D  effect desired for the widget.
       Acceptable values are raised, sunken, flat, ridge, solid,  and  groove.
       The  value indicates how the interior of the widget should appear rela-
       tive to its exterior;  for example, raised means the  interior  of  the
       widget should appear to protrude from the screen, relative to the exte-
       rior of the widget.  Specifies the number of milliseconds a  button  or
       key must be held down before it begins to auto-repeat.  Used, for exam-
       ple, on the up- and down-arrows in  scrollbars.   Used  in  conjunction
       with  repeatDelay:  once auto-repeat begins, this option determines the
       number of milliseconds between auto-repeats.  Specifies the  background
       color  to use when displaying selected items.  Specifies a non-negative
       value indicating the width of the 3-D border to  draw  around  selected
       items.  The value may have any of the forms acceptable to Tk_GetPixels.
       Specifies the foreground color to use when displaying  selected  items.
       Specifies  a boolean value that determines whether this widget controls
       the resizing grid for its top-level window.  This option  is  typically
       used in text widgets, where the information in the widget has a natural
       size (the size of a character) and it  makes  sense  for  the  window's
       dimensions to be integral numbers of these units.  These natural window
       sizes form a grid.  If the setGrid option is set to true then the  wid-
       get  will  communicate  with  the  window manager so that when the user
       interactively resizes the top-level window that  contains  the  widget,
       the  dimensions  of  the  window  will be displayed to the user in grid
       units and the window size will be constrained to  integral  numbers  of
       grid units.  See the section GRIDDED GEOMETRY MANAGEMENT in the wm man-
       ual entry for more details.  Determines whether the window accepts  the



STk                            4.0                              3





options(n)             Tk Built-In Commands            options(n)


       focus during keyboard traversal (e.g., Tab and Shift-Tab).  Before set-
       ting the focus to a window, the traversal scripts consult the value  of
       the  takeFocus  option.   A value of #f means that the window should be
       skipped entirely during keyboard traversal.  #t means that  the  window
       should receive the input focus as long as it is viewable (it and all of
       its ancestors are mapped).  An empty string for the option  means  that
       the  traversal  scripts make the decision about whether or not to focus
       on the window:  the current algorithm is to skip the window  if  it  is
       disabled,  if  it has no key bindings, or if it is not viewable.  Value
       can also be a one parameter procedure. This procedure is called by  the
       traversal  algorithm with the window as parameter. The value retuned by
       he procedure must be #f, #t, or an empty string:   a  #f  or  #t  value
       specifies whether the window will receive the input focus, and an empty
       string results in the default decision described above. See the  focus-
       next page for the focus-on and focus-off procedures.  Note: this inter-
       pretation of the option is defined entirely by  the  STk  scripts  that
       implement  traversal:   the  widget  implementations  ignore the option
       entirely, so you can change its meaning if you  redefine  the  keyboard
       traversal  scripts.  Specifies a string to be displayed inside the wid-
       get.  The way in which the string is displayed depends on the  particu-
       lar  widget  and  may be determined by other options, such as anchor or
       justify.  Specifies the name of a variable.  The value of the  variable
       is  a  text  string to be displayed inside the widget;  if the variable
       value changes then the  widget  will  automatically  update  itself  to
       reflect the new value.  The way in which the string is displayed in the
       widget depends on the particular widget and may be determined by  other
       options, such as anchor or justify.  Specifies the color to use for the
       rectangular trough areas in widgets  such  as  scrollbars  and  scales.
       Specifies  the integer index of a character to underline in the widget.
       This option is used by  the  default  bindings  to  implement  keyboard
       traversal  for  menu  buttons  and  menu entries.  0 corresponds to the
       first character of the text displayed in the  widget,  1  to  the  next
       character, and so on.  For widgets that can perform word-wrapping, this
       option specifies the maximum line length.  Lines that would exceed this
       length  are  wrapped onto the next line, so that no line is longer than
       the specified length.  The value may be specified in any of  the  stan-
       dard  forms  for screen distances.  If this value is less than or equal
       to 0 then no wrapping is done:  lines will break only at newline  char-
       acters  in  the text.  Specifies the procedure used to communicate with
       horizontal scrollbars.  When the view in the  widget's  window  changes
       (or  whenever  anything  else occurs that could change the display in a
       scrollbar, such as a change in the total  size  of  the  widget's  con-
       tents),  the widget call this procedure with two numbers as parameters.
       Each of the numbers is a fraction between 0 and 1,  which  indicates  a
       position in the document.  0 indicates the beginning of the document, 1
       indicates the end, .333 indicates a position one third the way  through
       the document, and so on.  The first fraction indicates the first infor-
       mation in the document that is visible in the window,  and  the  second
       fraction  indicates the information just after the last portion that is
       visible.  Typically the xScrollCommand option consists of  a  procedure
       of  the form (lambda l (apply .x.scrollbar 'set l)) this will cause the
       scrollbar to be updated whenever the view in the  window  changes.   If
       this option is not specified, then no command will be executed.  Speci-
       fies the prefix  for  a  command  used  to  communicate  with  vertical



STk                            4.0                              4





options(n)             Tk Built-In Commands            options(n)


       scrollbars.   This option is treated in the same way as the xScrollCom-
       mand option, except that it is used for vertical scrollbars and is pro-
       vided  by widgets that support vertical scrolling.  See the description
       of xScrollCommand for details on how this option is used.





















































STk                            4.0                              5


