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.

       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).

       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.

       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
       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
              acceptable to Tk_GetCursor.

       Name:           cursorBackground
       Class:          Foreground
       Command-Line Switch:-cursorbackground

              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).
              This option is  obsolete  and  is  gradually  being
              replaced by the insertBackground option.

       Name:           cursorBorderWidth
       Class:          BorderWidth
       Command-Line Switch:-cursorborderwidth

              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.  This option is obsolete  and
              is  gradually  being  replaced by the insertBorder-
              Width option.

       Name:           cursorOffTime
       Class:          OffTime
       Command-Line Switch:-cursorofftime

              Specifies a non-negative integer  value  indicating
              the number of milliseconds the 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.  This option is obsolete and is gradually
              being replaced by the insertOffTime option.

       Name:           cursorOnTime
       Class:          OnTime
       Command-Line Switch:-cursorontime

              Specifies  a  non-negative integer value indicating
              the number of milliseconds the cursor should remain
              ``on''  in  each blink cycle.  This option is obso-
              lete and is gradually being replaced by the  inser-
              tOnTime option.

       Name:           cursorWidth
       Class:          CursorWidth
       Command-Line Switch:-cursorwidth

              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  cursor  (using  the
              cursorBorderWidth option), the border will be drawn
              inside  the  width  specified  by  the  cursorWidth
              option.   This  option is obsolete and is gradually
              being replaced by the insertWidth option.

       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
              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:           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
              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:           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.

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

       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:           scrollCommand
       Class:          ScrollCommand
       Command-Line Switch:-scrollcommand

              Specifies the prefix for a command used to communi-
              cate with scrollbar widgets.  When the view in  the
              widget's  window changes (or whenever anything else
              occurs that could change the display in  a  scroll-
              bar, such as a change in the total size of the wid-
              get's contents), the widget  will  generate  a  Tcl
              command  by  concatenating  the  scroll command and
              four numbers.  The four numbers are, in order:  the
              total size of the widget's contents, in unspecified
              units (``unit'' is  a  widget-specific  term;   for
              widgets  displaying text, the unit is a line);  the
              maximum number of units that may  be  displayed  at
              once  in  the  widget's  window,  given its current
              size;  the index of the top-most or left-most  unit
              currently  visible  in  the  window (index 0 corre-
              sponds to the first unit); and  the  index  of  the
              bottom-most or right-most unit currently visible in
              the window.  This command is then passed to the Tcl
              interpreter  for  execution.  Typically the scroll-
              Command option consists  of  the  path  name  of  a
              scrollbar   widget   followed   by   ``set'',  e.g.
              ``.x.scrollbar set'':  this will cause the  scroll-
              bar  to  be updated whenever the view in the window
              changes.  If this option is not specified, then  no
              command will be executed.

              The  scrollCommand  option is used for widgets that
              support scrolling in only one direction.  For  wid-
              gets  that  support  scrolling  in both directions,
              this option is replaced with the xScrollCommand and
              yScrollCommand options.

       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
       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:           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:           underline
       Class:          Underline
       Command-Line Switch:-underline

              Specifies the  integer  index  of  a  character  to
              underline  in the widget.  This option is typically
              used to indicate keyboard traversal  characters  in
              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.

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

              Specifies the prefix for a command used to communi-
              cate with horizontal scrollbars.   This  option  is
              treated  in  the  same  way  as  the  scrollCommand
              option, except  that  it  is  used  for  horizontal
              scrollbars  associated  with  widgets  that support
              both horizontal and vertical  scrolling.   See  the
              description  of  scrollCommand for complete details
              on how this option is used.

       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  scrollCommand
              option, except that it is used for vertical scroll-
              bars associated with widgets that support both hor-
              izontal  and  vertical scrolling.  See the descrip-
              tion of scrollCommand for complete details  on  how
              this option is used.


KEYWORDS
       class, name, standard option, switch
