


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 support every option (see the
       manual entries for individual widgets for a  list  of  the
       standard  options supported by that widget), but if a wid-
       get does support an option with one of  the  names  listed
       below,  then  the  option has exactly the effect described
       below.

       In the descriptions below, ``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.   ``Command-Line  Switch''  refers to the switch
       used in widget-creation 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 unambiguous.

       Name:           activeBackground
       Class:          Foreground
       Command-Line Switch:-activebackground

              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 posi-
              tioned 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_strictMotif  variable, this option will normally
              be ignored;  the normal background  color  will  be
              used instead.

       Name:           activeBorderWidth
       Class:          BorderWidth
       Command-Line Switch:-activeborderwidth

              Specifies a non-negative value indicating the width
              of the 3-D border  drawn  around  active  elements.
              See  above  for definition of active elements.  The
              value may have  any  of  the  forms  acceptable  to
              Tk_GetPixels.  This option is typically only avail-
              able in widgets displaying more than one element at
              a time (e.g. menus but not buttons).



Tk                             4.0                              1





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


       Name:           activeForeground
       Class:          Background
       Command-Line Switch:-activeforeground

              Specifies  foreground  color  to  use  when drawing
              active  elements.   See  above  for  definition  of
              active elements.

       Name:           anchor
       Class:          Anchor
       Command-Line Switch:-anchor

              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.

       Name:           background
       Class:          Background
       Command-Line Switch:-background or -bg

              Specifies the normal background color to  use  when
              displaying the widget.

       Name:           bitmap
       Class:          Bitmap
       Command-Line Switch:-bitmap

              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  jus-
              tify.   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 support both bitmap and
              image options, image will usually override  bitmap.

       Name:           borderWidth
       Class:          BorderWidth
       Command-Line Switch:-borderwidth or -bd

              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.

       Name:           cursor



Tk                             4.0                              2





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


       Class:          Cursor
       Command-Line Switch:-cursor

              Specifies  the mouse cursor to be used for the wid-
              get.  The value may have any of the  forms  accept-
              able to Tk_GetCursor.

       Name:           disabledForeground
       Class:          DisabledForeground
       Command-Line Switch:-disabledforeground

              Specifies  foreground  color  to use when drawing a
              disabled 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  fooreground  color  but they are
              dimmed by drawing them with a  stippled  fill  pat-
              tern.

       Name:           exportSelection
       Class:          ExportSelection
       Command-Line Switch:-exportselection

              Specifies  whether or not a selection in the widget
              should also be the X selection.  The value may have
              any  of  the forms accepted by Tcl_GetBoolean, such
              as true, false, 0, 1, yes, or no.  If the selection
              is exported, then selecting in the widget deselects
              the current X selection, selecting outside the wid-
              get  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.

       Name:           font
       Class:          Font
       Command-Line Switch:-font

              Specifies the font to use when drawing text  inside
              the widget.

       Name:           foreground
       Class:          Foreground
       Command-Line Switch:-foreground or -fg

              Specifies  the  normal foreground color to use when
              displaying the widget.

       Name:           geometry
       Class:          Geometry
       Command-Line Switch:-geometry

              Specifies the desired  geometry  for  the  widget's
              window,  in  the  form widthxheight, where width is



Tk                             4.0                              3





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


              the desired width of the window and height  is  the
              desired  height.   The  units  for width and height
              depend on the particular widget.  For widgets  dis-
              playing  text the units are usually the size of the
              characters in the font being displayed;  for  other
              widgets the units are usually pixels.

       Name:           highlightBackground
       Class:          HighlightBackground
       Command-Line Switch:-highlightbackground

              Specifies  the  color  to  display in the traversal
              highlight region when the widget does not have  the
              input focus.

       Name:           highlightColor
       Class:          HighlightColor
       Command-Line Switch:-highlightcolor

              Specifies  the color to use for the traversal high-
              light rectangle that is  drawn  around  the  widget
              when it has the input focus.

       Name:           highlightThickness
       Class:          HighlightThickness
       Command-Line Switch:-highlightthickness

              Specifies a non-negative value indicating the width
              of the highlight rectangle to draw around the  out-
              side  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.

       Name:           image
       Class:          Image
       Command-Line Switch:-image

              Specifies an image to display in the widget,  which
              must  have  been created with the image create com-
              mand.  Typically, if the image option is  specified
              then  it  overrides  other  options  that specify a
              bitmap or textual value to display in  the  widget;
              the image option may be reset to an empty string to
              re-enable a bitmap or text display.

       Name:           insertBackground
       Class:          Foreground
       Command-Line Switch:-insertbackground

              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



Tk                             4.0                              4





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


              insertion cursor happens to fall in the selection).

       Name:           insertBorderWidth
       Class:          BorderWidth
       Command-Line Switch:-insertborderwidth

              Specifies a non-negative value indicating the width
              of the 3-D border to draw around the insertion cur-
              sor.   The  value may have any of the forms accept-
              able to Tk_GetPixels.

       Name:           insertOffTime
       Class:          OffTime
       Command-Line Switch:-insertofftime

              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.

       Name:           insertOnTime
       Class:          OnTime
       Command-Line Switch:-insertontime

              Specifies a non-negative integer  value  indicating
              the  number  of  milliseconds  the insertion cursor
              should remain ``on'' in each blink cycle.

       Name:           insertWidth
       Class:          InsertWidth
       Command-Line Switch:-insertwidth

              Specifies a  value indicating the  total  width  of
              the  insertion  cursor.   The value may have any of
              the forms acceptable to Tk_GetPixels.  If a  border
              has  been specified for the insertion cursor (using
              the insertBorderWidth option), the border  will  be
              drawn inside the width specified by the insertWidth
              option.

       Name:           jump
       Class:          Jump
       Command-Line Switch:-jump

              For widgets with a slider that can  be  dragged  to
              adjust a value, such as scrollbars and scales, 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 the drag;  at that point  a  single



Tk                             4.0                              5





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


              notification  is  made  (the value ``jumps'' rather
              than changing smoothly).

       Name:           justify
       Class:          Justify
       Command-Line Switch:-justify

              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.

       Name:           orient
       Class:          Orient
       Command-Line Switch:-orient

              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 ver-
              tical or an abbreviation of one of these.

       Name:           padX
       Class:          Pad
       Command-Line Switch:-padx

              Specifies a non-negative 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 displaying a bitmap
              or image, then they usually ignore padding options.

       Name:           padY
       Class:          Pad
       Command-Line Switch:-pady

              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  window 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



Tk                             4.0                              6





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


              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.

       Name:           relief
       Class:          Relief
       Command-Line Switch:-relief

              Specifies  the  3-D  effect desired for the widget.
              Acceptable values are raised, sunken, flat,  ridge,
              and  groove.   The value indicates how the interior
              of the widget should appear relative to  its  exte-
              rior;   for  example,  raised means the interior of
              the widget  should  appear  to  protrude  from  the
              screen, relative to the exterior of the widget.

       Name:           repeatDelay
       Class:          RepeatDelay
       Command-Line Switch:-repeatdelay

              Specifies  the  number  of milliseconds a button or
              key must be held down before  it  begins  to  auto-
              repeat.   Used,  for  example, on the up- and down-
              arrows in scrollbars.

       Name:           repeatInterval
       Class:          RepeatInterval
       Command-Line Switch:-repeatinterval

              Used in conjunction with repeatDelay:   once  auto-
              repeat begins, this option determines the number of
              milliseconds between auto-repeats.

       Name:           selectBackground
       Class:          Foreground
       Command-Line Switch:-selectbackground

              Specifies the background color to use when display-
              ing selected items.

       Name:           selectBorderWidth
       Class:          BorderWidth
       Command-Line Switch:-selectborderwidth

              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.

       Name:           selectForeground
       Class:          Background



Tk                             4.0                              7





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


       Command-Line Switch:-selectforeground

              Specifies the foreground color to use when display-
              ing selected items.

       Name:           setGrid
       Class:          SetGrid
       Command-Line Switch:-setgrid

              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 inte-
              gral  numbers of these units.  These natural window
              sizes form a grid.  If the setGrid option is set to
              true then the widget will communicate with the win-
              dow manager so that  when  the  user  interactively
              resizes the top-level window that contains the wid-
              get, 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 manual entry for more details.

       Name:           takeFocus
       Class:          TakeFocus
       Command-Line Switch:-takefocus

              Provides information used  when  moving  the  focus
              from window to window via keyboard traversal (e.g.,
              Tab and Shift-Tab).  Before setting the focus to  a
              window,  the  traversal scripts first check whether
              the window is viewable (it and  all  its  ancestors
              are  mapped); if not, the window is skipped.  Next,
              the scripts consult  the  value  of  the  takeFocus
              option.  A value of 0 means that this window should
              be skipped entirely during keyboard  traversal.   1
              means  that  the  this window should always receive
              the input focus.  An empty  value  means  that  the
              traversal  scripts  make the decision about whether
              or not to focus on the window:  the  current  algo-
              rithm is to skip the window if it is disabled or if
              it has no key bindings.  If the value has any other
              form,  then  the  traversal scripts take the value,
              append the name of the window to it (with a separa-
              tor  space), and evaluate the resulting string as a
              Tcl script.  The script must return  0,  1,  or  an
              empty  string;   this  value is used just as if the
              option had that value in the  first  place.   Note:
              this   interpretation  of  the  option  is  defined
              entirely by the Tcl scripts that implement  traver-
              sal:   the widget implementations ignore the option



Tk                             4.0                              8





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


              entirely, so you can  change  its  meaning  if  you
              redefine the keyboard traversal scripts.

       Name:           text
       Class:          Text
       Command-Line Switch:-text

              Specifies  a string to be displayed inside the wid-
              get.  The way in  which  the  string  is  displayed
              depends  on the particular widget and may be deter-
              mined by other options, such as anchor or  justify.

       Name:           textVariable
       Class:          Variable
       Command-Line Switch:-textvariable

              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 dis-
              played in the widget depends on the particular wid-
              get and may be determined by other options, such as
              anchor or justify.

       Name:           troughColor
       Class:          Background
       Command-Line Switch:-troughcolor

              Specifies the color  to  use  for  the  rectangular
              trough  areas  in  widgets  such  as scrollbars and
              scales.

       Name:           underline
       Class:          Underline
       Command-Line Switch:-underline

              Specifies the  integer  index  of  a  character  to
              underline  in  the  widget.  This option is used by
              the default bindings to implement keyboard  traver-
              sal  for  menu  buttons and menu entries.  0 corre-
              sponds to the first character of the text displayed
              in  the widget, 1 to the next character, and so on.

       Name:           wrapLength
       Class:          WrapLength
       Command-Line Switch:-wraplength

              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 spec-
              ified length.  The value may be specified in any of
              the  standard  forms for screen distances.  If this



Tk                             4.0                              9





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


              value is less than or equal to 0 then  no  wrapping
              is  done:  lines will break only at newline charac-
              ters in the text.

       Name:           xScrollCommand
       Class:          ScrollCommand
       Command-Line Switch:-xscrollcommand

              Specifies the prefix for a command used to communi-
              cate  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 contents), the widget will generate a
              Tcl command by concatenating the scroll command and
              two  numbers.   Each  of  the numbers is a fraction
              between 0 and 1, which indicates a position in  the
              document.   0  indicates the beginning of the docu-
              ment, 1 indicates the end, .333 indicates  a  posi-
              tion 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 win-
              dow, and the second fraction indicates the informa-
              tion  just  after the last portion that is visible.
              The command is then passed to the  Tcl  interpreter
              for execution.  Typically the xScrollCommand option
              consists of the path name  of  a  scrollbar  widget
              followed  by  ``set'',  e.g.  ``.x.scrollbar set'':
              this will cause the scrollbar to be  updated  when-
              ever  the  view  in  the  window  changes.  If this
              option is not specified, then no  command  will  be
              executed.

       Name:           yScrollCommand
       Class:          ScrollCommand
       Command-Line Switch:-yscrollcommand

              Specifies the prefix for a command used to communi-
              cate with  vertical  scrollbars.   This  option  is
              treated  in  the  same  way  as  the xScrollCommand
              option, except that it is used for vertical scroll-
              bars and is provided by widgets that support verti-
              cal scrolling.  See the description of  xScrollCom-
              mand for details on how this option is used.


KEYWORDS
       class, name, standard option, switch
