   This is a Texinfo GCL TK Manual

   Copyright 1994 William F. Schelter

focus
=====

   focus \- Direct keyboard events to a particular window

Synopsis
--------

focus
focus window
focus option ?arg arg ...?

Description
-----------

   The focus command is used to manage the Tk input focus.  At any
given time, one window in an application is designated as the focus
window for that application;  any key press or key release events
directed to any window in the application will be redirected instead to
the focus window.  If there is no focus window for an application then
keyboard events are discarded.  Typically, windows that are prepared to
deal with the focus (e.g. entries and other widgets that display
editable text) will claim the focus when mouse button 1 is pressed in
them.  When an application is created its main window is initially given
the focus.

   The focus command can take any of the following forms:

focus
     If invoked with no arguments, focus returns the path name of the
     current focus window, or none if there is no focus window.

focus window
     If invoked with a single argument consisting of a window's path
     name, focus sets the input focus to that window.  The return value
     is an empty string.

focus :default ?window?
     If window is specified, it becomes the default focus window (the
     window that receives the focus whenever the focus window is
     deleted) and the command returns an empty string.  If window isn't
     specified, the command returns the path name of the current
     default focus window, or none if there is no default.  Window may
     be specified as none to clear its existing value.  The default
     window is initially none.

focus :none
     Clears the focus window, so that keyboard input to this application
     will be discarded.

"Focus Events"
--------------

   Tk's model of the input focus is different than X's model, and the
focus window set with the focus command is not usually the same as the
X focus window.  Tk never explicitly changes the official X focus
window.  It waits for the window manager to direct the X input focus to
and from the application's top-level windows, and it intercepts FocusIn
and FocusOut events coming from the X server to detect these changes.
All of the focus events received from X are discarded by Tk;  they
never reach the application.  Instead, Tk generates a different stream
of FocusIn and FocusOut for the application.  This means that FocusIn
and and FocusOut events seen by the application will not obey the
conventions described in the documentation for Xlib.

   Tk applications receive two kinds of FocusIn and FocusOut events,
which can be distinguished by their detail fields.  Events with a
detail of NotifyAncestor are directed to the current focus window when
it becomes active or inactive.  A window is the active focus whenever
two conditions are simultaneously true: (a) the window is the focus
window for its application, and (b) some top-level window in the
application has received the X focus.  When this happens Tk generates a
FocusIn event for the focus window with detail NotifyAncestor.  When a
window loses the active focus (either because the window manager
removed the focus from the application or because the focus window
changed within the application) then it receives a FocusOut event with
detail NotifyAncestor.

   The events described above are directed to the application's focus
window regardless of which top-level window within the application has
received the focus.  The second kind of focus event is provided for
applications that need to know which particular top-level window has
the X focus.  Tk generates FocusIn and FocusOut events with detail
NotifyVirtual for top-level windows whenever they receive or lose the X
focus.  These events are generated regardless of which window in the
application has the Tk input focus.  They do not imply that keystrokes
will be directed to the window that receives the event;  they simply
indicate which top-level window is active as far as the window manager
is concerned.  If a top-level window is also the application's focus
window, then it will receive both NotifyVirtual and NotifyAncestor
events when it receives or loses the X focus.

   Tk does not generate the hierarchical chains of FocusIn and FocusOut
events described in the Xlib documentation (e.g.  a window can get a
FocusIn or FocusOut event without all of its ancestors getting events
too).  Furthermore, the mode field in focus events is always
NotifyNormal and the only values ever present in the detail field are
NotifyAncestor and NotifyVirtual.

Keywords
--------

   events, focus, keyboard, top-level, window manager

grab
====

   grab \- Confine pointer and keyboard events to a window sub-tree

Synopsis
--------

grab ?:global? window
grab option ?arg arg ...?

Description
-----------

   This command implements simple pointer and keyboard grabs for Tk.
Tk's grabs are different than the grabs described in the Xlib
documentation.  When a grab is set for a particular window, Tk
restricts all pointer events to the grab window and its descendants in
Tk's window hierarchy.  Whenever the pointer is within the grab
window's subtree, the pointer will behave exactly the same as if there
had been no grab at all and all events will be reported in the normal
fashion.  When the pointer is outside window's tree, button presses and
releases and mouse motion events are reported to window, and window
entry and window exit events are ignored.  The grab subtree "owns" the
pointer: windows outside the grab subtree will be visible on the screen
but they will be insensitive until the grab is released.  The tree of
windows underneath the grab window can include top-level windows, in
which case all of those top-level windows and their descendants will
continue to receive mouse events during the grab.

   Two forms of grabs are possible:  local and global.  A local grab
affects only the grabbing application:  events will be reported to
other applications as if the grab had never occurred.  Grabs are local
by default.  A global grab locks out all applications on the screen, so
that only the given subtree of the grabbing application will be
sensitive to pointer events (mouse button presses, mouse button
releases, pointer motions, window entries, and window exits).  During
global grabs the window manager will not receive pointer events either.

   During local grabs, keyboard events (key presses and key releases)
are delivered as usual:  the window manager controls which application
receives keyboard events, and if they are sent to any window in the
grabbing application then they are redirected to the focus window.
During a global grab Tk grabs the keyboard so that all keyboard events
are always sent to the grabbing application.  The focus command is
still used to determine which window in the application receives the
keyboard events.  The keyboard grab is released when the grab is
released.

   Grabs apply to particular displays.  If an application has windows
on multiple displays then it can establish a separate grab on each
display.  The grab on a particular display affects only the windows on
that display.  It is possible for different applications on a single
display to have simultaneous local grabs, but only one application can
have a global grab on a given display at once.

   The grab command can take any of the following forms:

grab ?:global? window
     Same as grab :set, described below.

grab :current ?window?
     If window is specified, returns the name of the current grab
     window in this application for window's display, or an empty
     string if there is no such window.  If window is omitted, the
     command returns a list whose elements are all of the windows
     grabbed by this application for all displays, or an empty string
     if the application has no grabs.

grab :release window
     Releases the grab on window if there is one, otherwise does
     nothing.  Returns an empty string.

grab :set ?:global? window
     Sets a grab on window.  If :global is specified then the grab is
     global, otherwise it is local.  If a grab was already in effect
     for this application on window's display then it is automatically
     released.  If there is already a grab on window and it has the same
     global/local form as the requested grab, then the command does
     nothing.  Returns an empty string.

grab :status window
     Returns none if no grab is currently set on window, local if a
     local grab is set on window, and global if a global grab is set.

Bugs
----

   It took an incredibly complex and gross implementation to produce
the simple grab effect described above.  Given the current
implementation, it isn't safe for applications to use the Xlib grab
facilities at all except through the Tk grab procedures.  If
applications try to manipulate X's grab mechanisms directly, things
will probably break.

   If a single process is managing several different Tk applications,
only one of those applications can have a local grab for a given
display at any given time.  If the applications are in different
processes, this restriction doesn't exist.

Keywords
--------

   grab, keyboard events, pointer events, window

tk-listbox-single-select
========================

   tk-listbox-single-select \- Allow only one selected element in
listbox(es)

Synopsis
--------

   tk-listbox-single-select arg ?arg arg ...?

Description
-----------

   This command is a Tcl procedure provided as part of the Tk script
library.  It takes as arguments the path names of one or more listbox
widgets, or the value Listbox.  For each named widget,
tk-listbox-single-select modifies the bindings of the widget so that
only a single element may be selected at a time (the normal
configuration allows multiple elements to be selected).  If the keyword
Listbox is among the window arguments, then the class bindings for
listboxes are changed so that all listboxes have the
one-selection-at-a-time behavior.

Keywords
--------

   listbox, selection

lower
=====

   lower \- Change a window's position in the stacking order

Synopsis
--------

   lower window ?belowThis?

Description
-----------

   If the belowThis argument is omitted then the command lowers window
so that it is below all of its siblings in the stacking order (it will
be obscured by any siblings that overlap it and will not obscure any
siblings).  If belowThis is specified then it must be the path name of
a window that is either a sibling of window or the descendant of a
sibling of window.  In this case the lower command will insert window
into the stacking order just below belowThis (or the ancestor of
belowThis that is a sibling of window); this could end up either
raising or lowering window.

Keywords
--------

   lower, obscure, stacking order

tk-menu-bar
===========

   tk-menu-bar, tk_bindForTraversal \- Support for menu bars

Synopsis
--------

   tk-menu-bar frame ?menu menu ...?

   tk_bindForTraversal arg arg ...

Description
-----------

   These two commands are Tcl procedures in the Tk script library.
They provide support for menu bars.  A menu bar is a frame that
contains a collection of menu buttons that work together, so that the
user can scan from one menu to another with the mouse: if the mouse
button is pressed over one menubutton (causing it to post its menu) and
the mouse is moved over another menubutton in the same menu bar without
releasing the mouse button, then the menu of the first menubutton is
unposted and the menu of the new menubutton is posted instead.  Menus
in a menu bar can also be accessed using keyboard traversal (i.e.  by
typing keystrokes instead of using the mouse).  In order for an
application to use these procedures, it must do three things, which are
described in the paragraphs below.

   First, each application must call tk-menu-bar to provide information
about the menubar.  The frame argument gives the path name of the frame
that contains all of the menu buttons, and the menu arguments give path
names for all of the menu buttons associated with the menu bar.
Normally frame is the parent of each of the menu's.  This need not be
the case, but frame must be an ancestor of each of the menu's in order
for grabs to work correctly when the mouse is used to pull down menus.
The order of the menu arguments determines the traversal order for the
menu buttons.  If tk-menu-bar is called without any menu arguments, it
returns a list containing the current menu buttons for frame, or an
empty string if frame isn't currently set up as a menu bar.  If
tk-menu-bar is called with a single menu argument consisting of an
empty string, any menubar information for frame is removed;  from now
on the menu buttons will function independently without keyboard
traversal.  Only one menu bar may be defined at a time within each
top-level window.

   The second thing an application must do is to identify the traversal
characters for menu buttons and menu entries.  This is done by
underlining those characters using the :underline options for the
widgets.  The menu traversal system uses this information to traverse
the menus under keyboard control (see below).

   The third thing that an application must do is to make sure that the
input focus is always in a window that has been configured to support
menu traversal.  If the input focus is none then input characters will
be discarded and no menu traversal will be possible.  If you have no
other place to set the focus, set it to the menubar widget:
tk-menu-bar creates bindings for its frame argument to support menu
traversal.

   The Tk startup scripts configure all the Tk widget classes with
bindings to support menu traversal, so menu traversal will be possible
regardless of which widget has the focus.  If your application defines
new classes of widgets that support the input focus, then you should
call tk_bindForTraversal for each of these classes.
Tk_bindForTraversal takes any number of arguments, each of which is a
widget path name or widget class name.  It sets up bindings for all the
named widgets and classes so that the menu traversal system will be
invoked when appropriate keystrokes are typed in those widgets or
classes.

"Menu Traversal Bindings"
-------------------------

   Once an application has made the three arrangements described above,
menu traversal will be available.  At any given time, the only menus
available for traversal are those associated with the top-level window
containing the input focus.  Menu traversal is initiated by one of the
following actions:
     [1] If <F10> is typed, then the first menu button in the list for
     the top-level window is posted and the first entry within that
     menu is selected.

     [2] If <Alt-key> is pressed, then the menu button that has key as
     its underlined character is posted and the first entry within that
     menu is selected.  The comparison between key and the underlined
     characters ignores case differences.  If no menu button matches
     key then the keystroke has no effect.

     [3] Clicking mouse button 1 on a menu button posts that menu and
     selects its first entry.

   Once a menu has been posted, the input focus is switched to that
menu and the following actions are possible:
     [1] Typing <ESC> or clicking mouse button 1 outside the menu
     button or its menu will abort the menu traversal.

     [2] If <Alt-key> is pressed, then the entry in the posted menu
     whose underlined character is key is invoked.  This causes the
     menu to be unposted, the entry's action to be taken, and the menu
     traversal to end.  The comparison between key and underlined
     characters ignores case differences.  If no menu entry matches key
     then the keystroke is ignored.

     [3] The arrow keys may be used to move among entries and menus.
     The left and right arrow keys move circularly among the available
     menus and the up and down arrow keys move circularly among the
     entries in the current menu.

     [4] If <Return> is pressed, the selected entry in the posted menu
     is invoked, which causes the menu to be unposted, the entry's
     action to be taken, and the menu traversal to end.

   When a menu traversal completes, the input focus reverts to the
window that contained it when the traversal started.

Keywords
--------

   keyboard traversal, menu, menu bar, post

option
======

   option \- Add/retrieve window options to/from the option database

Synopsis
--------

   option :add pattern value ?priority?

   option :clear

   option :get window name class

   option :readfile fileName ?priority?

Description
-----------

   The option command allows you to add entries to the Tk option
database or to retrieve options from the database.  The add form of the
command adds a new option to the database.  Pattern contains the option
being specified, and consists of names and/or classes separated by
asterisks or dots, in the usual X format.  Value contains a text string
to associate with pattern;  this is the value that will be returned in
calls to Tk_GetOption or by invocations of the option :get command.  If
priority is specified, it indicates the priority level for this option
(see below for legal values);  it defaults to interactive.  This
command always returns an empty string.

   The option :clear command clears the option database.  Default
options (in the RESOURCE_MANAGER property or the .Xdefaults file) will
be reloaded automatically the next time an option is added to the
database or removed from it.  This command always returns an empty
string.

   The option :get command returns the value of the option specified
for window under name and class.  If several entries in the option
database match window, name, and class, then the command returns
whichever was created with highest priority level.  If there are
several matching entries at the same priority level, then it returns
whichever entry was most recently entered into the option database.  If
there are no matching entries, then the empty string is returned.

   The readfile form of the command reads fileName, which should have
the standard format for an X resource database such as .Xdefaults, and
adds all the options specified in that file to the option database.  If
priority is specified, it indicates the priority level at which to
enter the options;  priority defaults to interactive.

   The priority arguments to the option command are normally specified
symbolically using one of the following values:

widgetDefault
     Level 20.  Used for default values hard-coded into widgets.

startupFile
     Level 40.  Used for options specified in application-specific
     startup files.

userDefault
     Level 60.  Used for options specified in user-specific defaults
     files, such as .Xdefaults, resource databases loaded into the X
     server, or user-specific startup files.

interactive
     Level 80.  Used for options specified interactively after the
     application starts running.  If priority isn't specified, it
     defaults to this level.

   Any of the above keywords may be abbreviated.  In addition,
priorities may be specified numerically using integers between 0 and
100, inclusive.  The numeric form is probably a bad idea except for new
priority levels other than the ones given above.

Keywords
--------

   database, option, priority, retrieve

options
=======

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

`:activebackground'
                         Name=`"activeBackground" Class=`"'Foreground"'

     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.

`:activeborderwidth'
                       Name=`"activeBorderWidth" Class=`"'BorderWidth"'

     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 available in
     widgets displaying more than one element at a time (e.g. menus but
     not buttons).

`:activeforeground'
                         Name=`"activeForeground" Class=`"'Background"'

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

`:anchor'
                                       Name=`"anchor" Class=`"'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.

`:background or :bg'
                               Name=`"background" Class=`"'Background"'

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

`:bitmap'
                                       Name=`"bitmap" Class=`"'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
     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.

`:borderwidth or :bd'
                             Name=`"borderWidth" Class=`"'BorderWidth"'

     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.

`:cursor'
                                       Name=`"cursor" Class=`"'Cursor"'

     Specifies the mouse cursor to be used for the widget.  The value
     may have any of the forms acceptable to Tk_GetCursor.

`:cursorbackground'
                         Name=`"cursorBackground" Class=`"'Foreground"'

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

`:cursorborderwidth'
                       Name=`"cursorBorderWidth" Class=`"'BorderWidth"'

     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.  \fIThis option is
     obsolete and is gradually being replaced by the insertBorderWidth
     option.

`:cursorofftime'
                               Name=`"cursorOffTime" Class=`"'OffTime"'

     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.  \fIThis option is obsolete and is gradually being
     replaced by the insertOffTime option.

`:cursorontime'
                                 Name=`"cursorOnTime" Class=`"'OnTime"'

     Specifies a non-negative integer value indicating the number of
     milliseconds the cursor should remain "on" in each blink cycle.
     \fIThis option is obsolete and is gradually being replaced by the
     insertOnTime option.

`:cursorwidth'
                             Name=`"cursorWidth" Class=`"'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.  \fIThis
     option is obsolete and is gradually being replaced by the
     insertWidth option.

`:disabledforeground'
               Name=`"disabledForeground" Class=`"'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 pattern.

`:exportselection'
                     Name=`"exportSelection" Class=`"'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 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.

`:font'
                                           Name=`"font" Class=`"'Font"'

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

`:foreground or :fg'
                               Name=`"foreground" Class=`"'Foreground"'

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

`:geometry'
                                   Name=`"geometry" Class=`"'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 displaying text the
     units are usually the size of the characters in the font being
     displayed;  for other widgets the units are usually pixels.

`:insertbackground'
                         Name=`"insertBackground" Class=`"'Foreground"'

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

`:insertborderwidth'
                       Name=`"insertBorderWidth" Class=`"'BorderWidth"'

     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.

`:insertofftime'
                               Name=`"insertOffTime" Class=`"'OffTime"'

     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.

`:insertontime'
                                 Name=`"insertOnTime" Class=`"'OnTime"'

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

`:insertwidth'
                             Name=`"insertWidth" Class=`"'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.

`:orient'
                                       Name=`"orient" Class=`"'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
     vertical or an abbreviation of one of these.

`:padx'
                                            Name=`"padX" Class=`"'Pad"'

     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.

`:pady'
                                            Name=`"padY" Class=`"'Pad"'

     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.

`:relief'
                                       Name=`"relief" Class=`"'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 exterior;  for example, raised means the interior of the
     widget should appear to protrude from the screen, relative to the
     exterior of the widget.

`:repeatdelay'
                             Name=`"repeatDelay" Class=`"'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.

`:repeatinterval'
                       Name=`"repeatInterval" Class=`"'RepeatInterval"'

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

`:scrollcommand'
                         Name=`"scrollCommand" Class=`"'ScrollCommand"'

     Specifies the prefix for a command used to communicate with
     scrollbar widgets.  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 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 corresponds 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 scrollCommand 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
     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 widgets that support scrolling in both
     directions, this option is replaced with the xScrollCommand and
     yScrollCommand options.

`:selectbackground'
                         Name=`"selectBackground" Class=`"'Foreground"'

     Specifies the background color to use when displaying selected
     items.

`:selectborderwidth'
                       Name=`"selectBorderWidth" Class=`"'BorderWidth"'

     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.

`:selectforeground'
                         Name=`"selectForeground" Class=`"'Background"'

     Specifies the foreground color to use when displaying selected
     items.

`:setgrid'
                                     Name=`"setGrid" Class=`"'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 integral 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
     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 manual entry for
     more details.

`:text'
                                           Name=`"text" Class=`"'Text"'

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

`:textvariable'
                               Name=`"textVariable" Class=`"'Variable"'

     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.

`:underline'
                                 Name=`"underline" Class=`"'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.

`:xscrollcommand'
                        Name=`"xScrollCommand" Class=`"'ScrollCommand"'

     Specifies the prefix for a command used to communicate 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.

`:yscrollcommand'
                        Name=`"yScrollCommand" Class=`"'ScrollCommand"'

     Specifies the prefix for a command used to communicate with
     vertical scrollbars.  This option is treated in the same way as the
     scrollCommand option, except that it is used for vertical
     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.

Keywords
--------

   class, name, standard option, switch

pack-old
========

   pack \- Obsolete syntax for packer geometry manager

Synopsis
--------

   pack after sibling window options ?window options ...?

   pack append parent window options ?window options ...?

   pack before sibling window options ?window options ...?

   pack info parent

   pack unpack window

Description
-----------

   Note: this manual entry describes the syntax for the pack\fI command
as it before Tk version 3.3.  Although this syntax continues to be
supported for backward compatibility, it is obsolete and should not be
used anymore.  At some point in the future it may cease to be supported.

   The packer is a geometry manager that arranges the children of a
parent by packing them in order around the edges of the parent.  The
first child is placed against one side of the window, occupying the
entire span of the window along that side.  This reduces the space
remaining for other children as if the side had been moved in by the
size of the first child.  Then the next child is placed against one
side of the remaining cavity, and so on until all children have been
placed or there is no space left in the cavity.

   The before, after, and append forms of the pack command are used to
insert one or more children into the packing order for their parent.
The before form inserts the children before window sibling in the
order;  all of the other windows must be siblings of sibling.  The
after form inserts the windows after sibling, and the append form
appends one or more windows to the end of the packing order for parent.
If a window named in any of these commands is already packed in its
parent, it is removed from its current position in the packing order
and repositioned as indicated by the command.  All of these commands
return an empty string as result.

   The unpack form of the pack command removes window from the packing
order of its parent and unmaps it.  After the execution of this command
the packer will no longer manage window's geometry.

   The placement of each child is actually a four-step process; the
options argument following each window consists of a list of one or
more fields that govern the placement of that window.  In the
discussion below, the term cavity refers to the space left in a parent
when a particular child is placed (i.e. all the space that wasn't
claimed by earlier children in the packing order).  The term parcel
refers to the space allocated to a particular child;  this is not
necessarily the same as the child window's final geometry.

   The first step in placing a child is to determine which side of the
cavity it will lie against.  Any one of the following options may be
used to specify a side:

top
     Position the child's parcel against the top of the cavity,
     occupying the full width of the cavity.

bottom
     Position the child's parcel against the bottom of the cavity,
     occupying the full width of the cavity.

left
     Position the child's parcel against the left side of the cavity,
     occupying the full height of the cavity.

right
     Position the child's parcel against the right side of the cavity,
     occupying the full height of the cavity.

   At most one of these options should be specified for any given
window.  If no side is specified, then the default is top.

   The second step is to decide on a parcel for the child.  For top and
bottom windows, the desired parcel width is normally the cavity width
and the desired parcel height is the window's requested height, as
passed to Tk_GeometryRequest. For left and right windows, the desired
parcel height is normally the cavity height and the desired width is
the window's requested width.  However, extra space may be requested
for the window using any of the following options:

padx num
     Add num pixels to the window's requested width before computing
     the parcel size as described above.

pady num
     Add num pixels to the window's requested height before computing
     the parcel size as described above.

expand
     This option requests that the window's parcel absorb any extra
     space left over in the parent's cavity after packing all the
     children.  The amount of space left over depends on the sizes
     requested by the other children, and may be zero.  If several
     windows have all specified expand then the extra width will be
     divided equally among all the left and right windows that
     specified expand and the extra height will be divided equally
     among all the top and bottom windows that specified expand.

   If the desired width or height for a parcel is larger than the
corresponding dimension of the cavity, then the cavity's dimension is
used instead.

   The third step in placing the window is to decide on the window's
width and height.  The default is for the window to receive either its
requested width and height or the those of the parcel, whichever is
smaller.  If the parcel is larger than the window's requested size,
then the following options may be used to expand the window to
partially or completely fill the parcel:

fill
     Set the window's size to equal the parcel size.

fillx
     Increase the window's width to equal the parcel's width, but retain
     the window's requested height.

filly
     Increase the window's height to equal the parcel's height, but
     retain the window's requested width.

     The last step is to decide the window's location within its parcel.
     If the window's size equals the parcel's size, then the window
     simply fills the entire parcel.  If the parcel is larger than the
     window, then one of the following options may be used to specify
     where the window should be positioned within its parcel:

frame center
     Center the window in its parcel.  This is the default if no framing
     option is specified.

frame n
     Position the window with its top edge centered on the top edge of
     the parcel.

frame ne
     Position the window with its upper-right corner at the upper-right
     corner of the parcel.

frame e
     Position the window with its right edge centered on the right edge
     of the parcel.

frame se
     Position the window with its lower-right corner at the lower-right
     corner of the parcel.

frame s
     Position the window with its bottom edge centered on the bottom
     edge of the parcel.

frame sw
     Position the window with its lower-left corner at the lower-left
     corner of the parcel.

frame w
     Position the window with its left edge centered on the left edge of
     the parcel.

frame nw
     Position the window with its upper-left corner at the upper-left
     corner of the parcel.

     The pack info command may be used to retrieve information about
     the packing order for a parent.  It returns a list in the form

          window options window options ...

     Each window is a name of a window packed in parent, and the
     following options describes all of the options for that window,
     just as they would be typed to pack append.  The order of the list
     is the same as the packing order for parent.

     The packer manages the mapped/unmapped state of all the packed
     children windows.  It automatically maps the windows when it packs
     them, and it unmaps any windows for which there was no space left
     in the cavity.

     The packer makes geometry requests on behalf of the parent windows
     it manages.  For each parent window it requests a size large enough
     to accommodate all the options specified by all the packed
     children, such that zero space would be leftover for expand
     options.

Keywords
--------

   geometry manager, location, packer, parcel, size