Seth Woolley's Man Viewer

options(n) - options, options - Standard options supported by widgets - man n options

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

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(1,8) 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(3,n) 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(1,n)
       used in(1,8) class commands and configure widget commands to set(7,n,1 builtins) this value.
       For example, if(3,n) an option's  command-line  switch(1,n)  is  -foreground  and
       there   exists  a  widget  .a.b.c,  then  the  command  .a.b.c  config-
       ure  -foreground black may be used to specify the value black  for  the
       option in(1,8) the the widget .a.b.c.  Command-line switches may be abbrevi-
       ated, as long as the abbreviation is  unambiguous.   ``Database  Name''
       refers to the option's name in(1,8) the option database (e.g.  in(1,8) .Xdefaults
       files).  ``Database Class'' refers to the option's class value  in(1,8)  the
       option database.  Specifies background color to use when drawing active
       elements.  An element (a widget or portion of a widget)  is  active  if(3,n)
       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_strictMotif variable, this option will
       normally be ignored;  the normal background color will be used instead.
       For  some  elements  on Windows and Macintosh 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 elements.  See above for definition of active  ele-
       ments.  The value may have any of the forms acceptable to Tk_GetPixels.
       This option is typically only available in(1,8) widgets displaying more than
       one  element  at  a time(1,2,n) (e.g. menus but not buttons).  Specifies fore-
       ground color to use when drawing active elements.  See above for  defi-
       nition  of  active elements.  Specifies how the information in(1,8) a widget
       (e.g. text or a bitmap) is to be displayed in(1,8) 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 displaying the widget.  Specifies a bitmap  to  display  in(1,8)
       the  widget, in(1,8) any of the forms acceptable to Tk_GetBitmap.  The exact
       way in(1,8) which the bitmap is displayed may be affected by  other  options
       such as anchor or justify.  Typically, if(3,n) this option is specified then
       it overrides other options that specify a textual value to  display  in(1,8)
       the  widget;  the  bitmap option may be reset(1,7,1 tput) to an empty string(3,n) to re-
       enable a text display.  In widgets that support both bitmap  and  image
       options,  image will usually override bitmap.  Specifies a non-negative
       value indicating the width of the 3-D border to draw around the outside
       of the widget (if(3,n) such a border is being drawn;  the relief option typ-
       ically determines this).  The value may also be used when  drawing  3-D
       effects  in(1,8)  the interior of the widget.  The value may have any of the
       forms acceptable to Tk_GetPixels.  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(3,n) (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(1,8)
       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(1,8) the widget des-
       elects 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.  The value may have any of the  forms  accepted
       by  Tk_GetFont.  Specifies the normal foreground color to use when dis-
       playing the widget.  Specifies the color to display  in(1,8)  the  traversal
       highlight region when the widget does not have the input focus.  Speci-
       fies 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 highlight is drawn around the widget.  Speci-
       fies an image to display in(1,8) the widget, which must  have  been  created
       with the image create command.  Typically, if(3,n) the image option is spec-
       ified then it overrides other options that specify a bitmap or  textual
       value  to  display  in(1,8)  the widget; the image option may be reset(1,7,1 tput) to an
       empty string(3,n) to re-enable a bitmap  or  text  display.   Specifies  the
       color to use as background in(1,8) the area covered by the insertion cursor.
       This color will normally override either the normal background for  the
       widget  (or the selection background if(3,n) the insertion cursor happens to
       fall in(1,8) 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 inser-
       tion cursor should remain ``off'' in(1,8) each blink cycle.  If this  option
       is  zero then the cursor doesn't blink:  it is on all the time.  Speci-
       fies a non-negative integer value indicating the number of milliseconds
       the  insertion cursor should remain ``on'' in(1,8) each blink cycle.  Speci-
       fies a  value indicating the total width of the insertion cursor.   The
       value  may have any of the forms acceptable to Tk_GetPixels.  If a bor-
       der has been specified for the insertion cursor (using  the  insertBor-
       derWidth  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(1,8) 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 notification is  made
       (the  value  ``jumps''  rather than changing smoothly).  When there are
       multiple lines of text displayed in(1,8) 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 hor-
       izontal  or  vertical  or an abbreviation of one of these.  Specifies a
       non-negative value indicating how much extra space to request  for  the
       widget in(1,8) the X-direction.  The value may have any of the forms accept-
       able 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(1,8) the widget);  if(3,n) 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(3,n) they
       are displaying 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(1,8) 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 dis-
       played in(1,8) the widget);   if(3,n)  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(3,n) they are displaying a bitmap or image, then they usu-
       ally 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  relative  to its exterior;  for example, raised means the inte-
       rior of the widget should appear to protrude from the screen,  relative
       to  the exterior of the widget.  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(1,8) scrollbars.  Used in(1,8) con-
       junction with repeatDelay:  once auto-repeat begins, this option deter-
       mines  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(1,8) text widgets, where the information in(1,8)  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(7,n,1 builtins)
       to true then the widget will communicate with  the  window  manager  so
       that when the user interactively resizes the top-level window that con-
       tains the widget, the dimensions of the window will be displayed to the
       user  in(1,8) grid units(1,7) and the window size will be constrained to integral
       numbers of grid units.  See the section GRIDDED GEOMETRY MANAGEMENT  in(1,8)
       the  wm  manual  entry for more details.  Determines whether the window
       accepts the focus during keyboard traversal (e.g., Tab and  Shift-Tab).
       Before setting the focus to a window, the traversal scripts consult the
       value of the takeFocus option.  A value of  0  means  that  the  window
       should be skipped entirely during keyboard traversal.  1 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 value 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(3,n) it
       is disabled, if(3,n) it has no key bindings, or if(3,n) it is not  viewable.   If
       the  value  has  any  other  form,  then the traversal scripts take the
       value, append the name of the window to it (with  a  separator  space),
       and  evaluate  the  resulting  string(3,n) as a Tcl script.  The script must
       return 0, 1, or an empty string:  a 0 or 1 value specifies whether  the
       window will receive the input focus, and an empty string(3,n) results in(1,8) the
       default decision described above.  Note:  this  interpretation  of  the
       option is defined entirely by the Tcl scripts that implement traversal:
       the widget implementations ignore  the  option  entirely,  so  you  can
       change  its  meaning  if(3,n)  you  redefine the keyboard traversal scripts.
       Specifies a string(3,n) to be displayed inside the widget.  The way in(1,8) which
       the  string(3,n)  is  displayed  depends on the particular 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(3,n) to be
       displayed inside the widget;  if(3,n) the variable value  changes  then  the
       widget  will automatically update(7,n) itself to reflect the new value.  The
       way in(1,8) which the string(3,n) is displayed in(1,8) the widget depends on the  par-
       ticular  widget  and may be determined by other options, such as anchor
       or justify.  Specifies the color to  use  for  the  rectangular  trough
       areas in(1,8) widgets such as scrollbars and scales.  This option is ignored
       for  scrollbars  on  Windows  (native  widget  doesn't  recognize  this
       option).   Specifies  the  integer index of a character to underline in(1,8)
       the widget.  This option is used by the default bindings  to  implement
       keyboard traversal for menu(3x,n,n tk_menuSetFocus) buttons and menu(3x,n,n tk_menuSetFocus) entries.  0 corresponds to
       the first character of the text displayed in(1,8) 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(1,8) any of  the  stan-
       dard  forms  for screen distances.  If this value is less(1,3) than or equal
       to 0 then no wrapping is done:  lines will break only at newline  char-
       acters  in(1,8) the text.  Specifies the prefix for a command used to commu-
       nicate with horizontal scrollbars.  When the view in(1,8) the widget's  win-
       dow  changes  (or  whenever  anything else occurs that could change the
       display in(1,8) a scrollbar, such as a change in(1,8) the total size of the  wid-
       get's  contents), the widget will generate a Tcl command by concatenat-
       ing the scroll command and two numbers.  Each of the numbers is a frac-
       tion  between  0  and 1, which indicates a position in(1,8) 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 information in(1,8) the document that
       is  visible in(1,8) the window, and the second fraction indicates the infor-
       mation 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(7,n,1 builtins)'',  e.g. ``.x.scrollbar set(7,n,1 builtins)'':  this will cause the
       scrollbar to be updated whenever the view in(1,8) 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 scroll-
       bars.   This  option  is  treated in(1,8) the same way as the xScrollCommand
       option, except that it is used for vertical scrollbars and is  provided
       by  widgets  that  support  vertical scrolling.  See the description of
       xScrollCommand for details on how this option is used.


SEE ALSO
       colors, cursors, font


KEYWORDS
       class, name, standard option, switch(1,n)



Tk                                    4.4                           options(n)

References for this manual (incoming links)