   This is a Texinfo GCL TK Manual

   Copyright 1994 William F. Schelter

message
=======

   message \- Create and manipulate message widgets

Synopsis
--------

   message pathName ?options?

Standard Options
----------------

     anchor            cursor          padX        text
     background        font            padY        textVariable
     borderWidth       foreground      relief      width

   See options, for more information.

Arguments for Message
---------------------

`:aspect'
                                       Name=`"aspect" Class=`"'Aspect"'

     Specifies a non-negative integer value indicating desired aspect
     ratio for the text.  The aspect ratio is specified as
     100*width/height.  100 means the text should be as wide as it is
     tall, 200 means the text should be twice as wide as it is tall, 50
     means the text should be twice as tall as it is wide, and so on.
     Used to choose line length for text if width option isn't
     specified.  Defaults to 150.

`:justify'
                                     Name=`"justify" Class=`"'Justify"'

     Specifies how to justify lines of text.  Must be one of left,
     center, or right.  Defaults to left.  This option works together
     with the anchor, aspect, padX, padY, and width options to provide
     a variety of arrangements of the text within the window.  The
     aspect and width options determine the amount of screen space
     needed to display the text.  The anchor, padX, and padY options
     determine where this rectangular area is displayed within the
     widget's window, and the justify option determines how each line
     is displayed within that rectangular region.  For example, suppose
     anchor is e and justify is left, and that the message window is
     much larger than needed for the text.  The the text will displayed
     so that the left edges of all the lines line up and the right edge
     of the longest line is padX from the right side of the window;
     the entire text block will be centered in the vertical span of the
     window.

`:width'
                                         Name=`"width" Class=`"'Width"'

     Specifies the length of lines in the window.  The value may have
     any of the forms acceptable to Tk_GetPixels.  If this option has a
     value greater than zero then the aspect option is ignored and the
     width option determines the line length.  If this option has a
     value less than or equal to zero, then the aspect option
     determines the line length.

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

   The message command creates a new window (given by the pathName
argument) and makes it into a message widget.  Additional options,
described above, may be specified on the command line or in the option
database to configure aspects of the message such as its colors, font,
text, and initial relief.  The message command returns its pathName
argument.  At the time this command is invoked, there must not exist a
window named pathName, but pathName's parent must exist.

   A message is a widget that displays a textual string.  A message
widget has three special features.  First, it breaks up its string into
lines in order to produce a given aspect ratio for the window.  The
line breaks are chosen at word boundaries wherever possible (if not
even a single word would fit on a line, then the word will be split
across lines).  Newline characters in the string will force line
breaks;  they can be used, for example, to leave blank lines in the
display.

   The second feature of a message widget is justification.  The text
may be displayed left-justified (each line starts at the left side of
the window), centered on a line-by-line basis, or right-justified (each
line ends at the right side of the window).

   The third feature of a message widget is that it handles control
characters and non-printing characters specially.  Tab characters are
replaced with enough blank space to line up on the next 8-character
boundary.  Newlines cause line breaks.  Other control characters (ASCII
code less than 0x20) and characters not defined in the font are
displayed as a four-character sequence \fB\exhh where hh is the
two-digit hexadecimal number corresponding to the character.  In the
unusual case where the font doesn't contain all of the characters in
"0123456789abcdef\ex" then control characters and undefined characters
are not displayed at all.

A Message Widget's Arguments
----------------------------

   The message command creates a new Tcl command whose name is
pathName.  This command may be used to invoke various operations on the
widget.  It has the following general form:

     pathName option ?arg arg ...?

   Option and the args determine the exact behavior of the command.
The following commands are possible for message widgets:

pathName :configure ?option? ?value option value ...?
     Query or modify the configuration options of the widget.  If no
     option is specified, returns a list describing all of the
     available options for pathName (see Tk_ConfigureInfo for
     information on the format of this list).  If option is specified
     with no value, then the command returns a list describing the one
     named option (this list will be identical to the corresponding
     sublist of the value returned if no option is specified).  If one
     or more option:value pairs are specified, then the command
     modifies the given widget option(s) to have the given value(s);  in
     this case the command returns an empty string.  Option may have
     any of the values accepted by the message command.

"Default Bindings"
------------------

   When a new message is created, it has no default event bindings:
messages are intended for output purposes only.

Bugs
----

   Tabs don't work very well with text that is centered or
right-justified.  The most common result is that the line is justified
wrong.

Keywords
--------

   message, widget

frame
=====

   frame \- Create and manipulate frame widgets

Synopsis
--------

   frame pathName ?:class className? ?options?

Standard Options
----------------

     background             cursor             relief
     borderWidth            geometry

   See options, for more information.

Arguments for Frame
-------------------

`:height'
                                       Name=`"height" Class=`"'Height"'

     Specifies the desired height for the window in any of the forms
     acceptable to Tk_GetPixels.  This option is only used if the
     :geometry option is unspecified.  If this option is less than or
     equal to zero (and :geometry is not specified) then the window
     will not request any size at all.

`:width'
                                         Name=`"width" Class=`"'Width"'

     Specifies the desired width for the window in any of the forms
     acceptable to Tk_GetPixels.  This option is only used if the
     :geometry option is unspecified.  If this option is less than or
     equal to zero (and :geometry is not specified) then the window
     will not request any size at all.

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

   The frame command creates a new window (given by the pathName
argument) and makes it into a frame widget.  Additional options,
described above, may be specified on the command line or in the option
database to configure aspects of the frame such as its background color
and relief.  The frame command returns the path name of the new window.

   A frame is a simple widget.  Its primary purpose is to act as a
spacer or container for complex window layouts.  The only features of a
frame are its background color and an optional 3-D border to make the
frame appear raised or sunken.

   In addition to the standard options listed above, a :class option
may be specified on the command line.  If it is specified, then the new
widget's class will be set to className instead of Frame.  Changing the
class of a frame widget may be useful in order to use a special class
name in database options referring to this widget and its children.
Note:  :class is handled differently than other command-line options
and cannot be specified using the option database (it has to be
processed before the other options are even looked up, since the new
class name will affect the lookup of the other options).  In addition,
the :class option may not be queried or changed using the config
command described below.

A Frame Widget's Arguments
--------------------------

   The frame command creates a new Tcl command whose name is the same
as the path name of the frame's window.  This command may be used to
invoke various operations on the widget.  It has the following general
form:

     pathName option ?arg arg ...?

   PathName is the name of the command, which is the same as the frame
widget's path name.  Option and the args determine the exact behavior
of the command.  The following commands are possible for frame widgets:

pathName :configure ?option? ?value option value ...?
     Query or modify the configuration options of the widget.  If no
     option is specified, returns a list describing all of the
     available options for pathName (see Tk_ConfigureInfo for
     information on the format of this list).  If option is specified
     with no value, then the command returns a list describing the one
     named option (this list will be identical to the corresponding
     sublist of the value returned if no option is specified).  If one
     or more option:value pairs are specified, then the command
     modifies the given widget option(s) to have the given value(s);  in
     this case the command returns an empty string.  Option may have
     any of the values accepted by the frame command.

Bindings
--------

   When a new frame is created, it has no default event bindings:
frames are not intended to be interactive.

Keywords
--------

   frame, widget

label
=====

   label \- Create and manipulate label widgets

Synopsis
--------

   label pathName ?options?

Standard Options
----------------

     anchor           borderWidth     foreground     relief
     background       cursor          padX           text
     bitmap           font            padY           textVariable

   See options, for more information.

Arguments for Label
-------------------

`:height'
                                       Name=`"height" Class=`"'Height"'

     Specifies a desired height for the label.  If a bitmap is being
     displayed in the label then the value is in screen units (i.e. any
     of the forms acceptable to Tk_GetPixels); for text it is in lines
     of text.  If this option isn't specified, the label's desired
     height is computed from the size of the bitmap or text being
     displayed in it.

`:width'
                                         Name=`"width" Class=`"'Width"'

     Specifies a desired width for the label.  If a bitmap is being
     displayed in the label then the value is in screen units (i.e. any
     of the forms acceptable to Tk_GetPixels); for text it is in
     characters.  If this option isn't specified, the label's desired
     width is computed from the size of the bitmap or text being
     displayed in it.

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

   The label command creates a new window (given by the pathName
argument) and makes it into a label widget.  Additional options,
described above, may be specified on the command line or in the option
database to configure aspects of the label such as its colors, font,
text, and initial relief.  The label command returns its pathName
argument.  At the time this command is invoked, there must not exist a
window named pathName, but pathName's parent must exist.

   A label is a widget that displays a textual string or bitmap.  The
label can be manipulated in a few simple ways, such as changing its
relief or text, using the commands described below.

A Label Widget's Arguments
--------------------------

   The label command creates a new Tcl command whose name is pathName.
This command may be used to invoke various operations on the widget.
It has the following general form:

     pathName option ?arg arg ...?

   Option and the args determine the exact behavior of the command.
The following commands are possible for label widgets:

pathName :configure ?option? ?value option value ...?
     Query or modify the configuration options of the widget.  If no
     option is specified, returns a list describing all of the
     available options for pathName (see Tk_ConfigureInfo for
     information on the format of this list).  If option is specified
     with no value, then the command returns a list describing the one
     named option (this list will be identical to the corresponding
     sublist of the value returned if no option is specified).  If one
     or more option:value pairs are specified, then the command
     modifies the given widget option(s) to have the given value(s);  in
     this case the command returns an empty string.  Option may have
     any of the values accepted by the label command.

Bindings
--------

   When a new label is created, it has no default event bindings:
labels are not intended to be interactive.

Keywords
--------

   label, widget

radiobutton
===========

   radiobutton \- Create and manipulate radio-button widgets

Synopsis
--------

   radiobutton pathName ?options?

Standard Options
----------------

     activeBackground  bitmap              font        relief
     activeForeground  borderWidth         foreground  text
     anchor            cursor              padX        textVariable
     background        disabledForeground  padX

   See options, for more information.

Arguments for Radiobutton
-------------------------

`:command'
                                     Name=`"command" Class=`"'Command"'

     Specifies a Tcl command to associate with the button.  This command
     is typically invoked when mouse button 1 is released over the
     button window.  The button's global variable (:variable option)
     will be updated before the command is invoked.

`:height'
                                       Name=`"height" Class=`"'Height"'

     Specifies a desired height for the button.  If a bitmap is being
     displayed in the button then the value is in screen units (i.e.
     any of the forms acceptable to Tk_GetPixels); for text it is in
     lines of text.  If this option isn't specified, the button's
     desired height is computed from the size of the bitmap or text
     being displayed in it.

`:selector'
                                 Name=`"selector" Class=`"'Foreground"'

     Specifies the color to draw in the selector when this button is
     selected.  If specified as an empty string then no selector is
     drawn for the button.

`:state'
                                         Name=`"state" Class=`"'State"'

     Specifies one of three states for the radio button:  normal,
     active, or disabled.  In normal state the radio button is
     displayed using the foreground and background options.  The active
     state is typically used when the pointer is over the radio button.
     In active state the radio button is displayed using the
     activeForeground and activeBackground options.  Disabled state
     means that the radio button is insensitive:  it doesn't activate
     and doesn't respond to mouse button presses.  In this state the
     disabledForeground and background options determine how the radio
     button is displayed.

`:value'
                                         Name=`"value" Class=`"'Value"'

     Specifies value to store in the button's associated variable
     whenever this button is selected.  Defaults to the name of the
     radio button.

`:variable'
                                   Name=`"variable" Class=`"'Variable"'

     Specifies name of global variable to set whenever this button is
     selected.  Changes in this variable also cause the button to select
     or deselect itself.  Defaults to the value selectedButton.

`:width'
                                         Name=`"width" Class=`"'Width"'

     Specifies a desired width for the button.  If a bitmap is being
     displayed in the button then the value is in screen units (i.e.
     any of the forms acceptable to Tk_GetPixels); for text it is in
     characters.  If this option isn't specified, the button's desired
     width is computed from the size of the bitmap or text being
     displayed in it.

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

   The radiobutton command creates a new window (given by the pathName
argument) and makes it into a radiobutton widget.  Additional options,
described above, may be specified on the command line or in the option
database to configure aspects of the radio button such as its colors,
font, text, and initial relief.  The radiobutton command returns its
pathName argument.  At the time this command is invoked, there must not
exist a window named pathName, but pathName's parent must exist.

   A radio button is a widget that displays a textual string or bitmap
and a diamond called a selector.  A radio button has all of the
behavior of a simple button: it can display itself in either of three
different ways, according to the state option; it can be made to appear
raised, sunken, or flat; it can be made to flash; and it invokes a Tcl
command whenever mouse button 1 is clicked over the check button.

   In addition, radio buttons can be selected.  If a radio button is
selected then a special highlight appears in the selector and a Tcl
variable associated with the radio button is set to a particular value.
If the radio button is not selected then the selector is drawn in a
different fashion.  Typically, several radio buttons share a single
variable and the value of the variable indicates which radio button is
to be selected.  When a radio button is selected it sets the value of
the variable to indicate that fact;  each radio button also monitors
the value of the variable and automatically selects and deselects
itself when the variable's value changes.  By default the variable
selectedButton is used;  its contents give the name of the button that
is selected, or the empty string if no button associated with that
variable is selected.  The name of the variable for a radio button,
plus the variable to be stored into it, may be modified with options on
the command line or in the option database.  By default a radio button
is configured to select itself on button clicks.

A Radiobutton Widget's Arguments
--------------------------------

   The radiobutton command creates a new Tcl command whose name is
pathName.  This command may be used to invoke various operations on the
widget.  It has the following general form:

     pathName option ?arg arg ...?

   Option and the args determine the exact behavior of the command.
The following commands are possible for radio-button widgets:

pathName :activate
     Change the radio button's state to active and redisplay the button
     using its active foreground and background colors instead of normal
     colors.  This command is ignored if the radio button's state is
     disabled.  This command is obsolete and will eventually be removed;
     use "pathName :configure :state active" instead.

pathName :configure ?option? ?value option value ...?
     Query or modify the configuration options of the widget.  If no
     option is specified, returns a list describing all of the
     available options for pathName (see Tk_ConfigureInfo for
     information on the format of this list).  If option is specified
     with no value, then the command returns a list describing the one
     named option (this list will be identical to the corresponding
     sublist of the value returned if no option is specified).  If one
     or more option:value pairs are specified, then the command
     modifies the given widget option(s) to have the given value(s);  in
     this case the command returns an empty string.  Option may have
     any of the values accepted by the radiobutton command.

pathName :deactivate
     Change the radio button's state to normal and redisplay the button
     using its normal foreground and background colors.  This command
     is ignored if the radio button's state is disabled.  This command
     is obsolete and will eventually be removed; use "pathName
     :configure :state normal" instead.

pathName :deselect
     Deselect the radio button:  redisplay it without a highlight in
     the selector and set the associated variable to an empty string.
     If this radio button was not currently selected, then the command
     has no effect.

pathName :flash
     Flash the radio button.  This is accomplished by redisplaying the
     radio button several times, alternating between active and normal
     colors.  At the end of the flash the radio button is left in the
     same normal/active state as when the command was invoked.  This
     command is ignored if the radio button's state is disabled.

pathName :invoke
     Does just what would have happened if the user invoked the radio
     button with the mouse: select the button and invoke its associated
     Tcl command, if there is one.  The return value is the return
     value from the Tcl command, or an empty string if there is no
     command associated with the radio button.  This command is ignored
     if the radio button's state is disabled.

pathName :select
     Select the radio button:  display it with a highlighted selector
     and set the associated variable to the value corresponding to this
     widget.

Bindings
--------

   Tk automatically creates class bindings for radio buttons that give
them the following default behavior:
     [1] The radio button activates whenever the mouse passes over it
     and deactivates whenever the mouse leaves the radio button.

     [2] The radio button's relief is changed to sunken whenever mouse
     button 1 is pressed over it, and the relief is restored to its
     original value when button 1 is later released.

     [3] If mouse button 1 is pressed over the radio button and later
     released over the radio button, the radio button is invoked (i.e.
     it is selected and the command associated with the button is
     invoked, if there is one).  However, if the mouse is not over the
     radio button when button 1 is released, then no invocation occurs.

   The behavior of radio buttons can be changed by defining new
bindings for individual widgets or by redefining the class bindings.

Keywords
--------

   radio button, widget

toplevel
========

   toplevel \- Create and manipulate toplevel widgets

Synopsis
--------

   toplevel pathName ?:screen screenName? ?:class className? ?options?

Standard Options
----------------

     background                  geometry
     borderWidth                 relief

   See options, for more information.

Arguments for Toplevel
----------------------

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

   The toplevel command creates a new toplevel widget (given by the
pathName argument).  Additional options, described above, may be
specified on the command line or in the option database to configure
aspects of the toplevel such as its background color and relief.  The
toplevel command returns the path name of the new window.

   A toplevel is similar to a frame except that it is created as a
top-level window:  its X parent is the root window of a screen rather
than the logical parent from its path name.  The primary purpose of a
toplevel is to serve as a container for dialog boxes and other
collections of widgets.  The only features of a toplevel are its
background color and an optional 3-D border to make the toplevel appear
raised or sunken.

   Two special command-line options may be provided to the toplevel
command:  :class and :screen.  If :class is specified, then the new
widget's class will be set to className instead of Toplevel.  Changing
the class of a toplevel widget may be useful in order to use a special
class name in database options referring to this widget and its
children.  The :screen option may be used to place the window on a
different screen than the window's logical parent.  Any valid screen
name may be used, even one associated with a different display.

   Note:  :class and :screen are handled differently than other
command-line options.  They may not be specified using the option
database (these options must have been processed before the new window
has been created enough to use the option database; in particular, the
new class name will affect the lookup of options in the database).  In
addition, :class and :screen may not be queried or changed using the
config command described below.  However, the winfo :class command may
be used to query the class of a window, and winfo :screen may be used
to query its screen.

A Toplevel Widget's Arguments
-----------------------------

   The toplevel command creates a new Tcl command whose name is the
same as the path name of the toplevel's window.  This command may be
used to invoke various operations on the widget.  It has the following
general form:

     pathName option ?arg arg ...?

   PathName is the name of the command, which is the same as the
toplevel widget's path name.  Option and the args determine the exact
behavior of the command.  The following commands are possible for
toplevel widgets:

pathName :configure ?option? ?value option value ...?
     Query or modify the configuration options of the widget.  If no
     option is specified, returns a list describing all of the
     available options for pathName (see Tk_ConfigureInfo for
     information on the format of this list).  If option is specified
     with no value, then the command returns a list describing the one
     named option (this list will be identical to the corresponding
     sublist of the value returned if no option is specified).  If one
     or more option:value pairs are specified, then the command
     modifies the given widget option(s) to have the given value(s);  in
     this case the command returns an empty string.  Option may have
     any of the values accepted by the toplevel command.

Bindings
--------

   When a new toplevel is created, it has no default event bindings:
toplevels are not intended to be interactive.

Keywords
--------

   toplevel, widget

Control
*******

after
=====

   after - Execute a command after a time delay

Synopsis
--------

   after ms ?arg1 arg2 arg3 ...?

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

   This command is used to delay execution of the program or to execute
a command in background after a delay.  The ms argument gives a time in
milliseconds.  If ms is the only argument to after then the command
sleeps for ms milliseconds and returns.  While the command is sleeping
the application does not respond to X events and other events.

   If additional arguments are present after ms, then a Tcl command is
formed by concatenating all the additional arguments in the same
fashion as the concat command.  After returns immediately but arranges
for the command to be executed ms milliseconds later in background.
The command will be executed at global level (outside the context of
any Tcl procedure).  If an error occurs while executing the delayed
command then the tkerror mechanism is used to report the error.

   The after command always returns an empty string.

   See tkerror

Keywords
--------

   delay, sleep, time

bind
====

   bind \- Arrange for X events to invoke Tcl commands

Synopsis
--------

bind windowSpec
bind windowSpec sequence
bind windowSpec sequence command
bind windowSpec sequence +command

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

   If all three arguments are specified, bind will arrange for command
(a Tcl command) to be executed whenever the sequence of events given by
sequence occurs in the window(s) identified by windowSpec.  If command
is prefixed with a "+", then it is appended to any existing binding for
sequence;  otherwise command replaces the existing binding, if any.  If
command is an empty string then the current binding for sequence is
destroyed, leaving sequence unbound.  In all of the cases where a
command argument is provided, bind returns an empty string.

   If sequence is specified without a command, then the command
currently bound to sequence is returned, or an empty string if there is
no binding for sequence.  If neither sequence nor command is specified,
then the return value is a list whose elements are all the sequences
for which there exist bindings for windowSpec.

   The windowSpec argument selects which window(s) the binding applies
to.  It may have one of three forms.  If windowSpec is the path name
for a window, then the binding applies to that particular window.  If
windowSpec is the name of a class of widgets, then the binding applies
to all widgets in that class.  Lastly, windowSpec may have the value
all, in which case the binding applies to all windows in the
application.

   The sequence argument specifies a sequence of one or more event
patterns, with optional white space between the patterns.  Each event
pattern may take either of two forms.  In the simplest case it is a
single printing ASCII character, such as a or [.  The character may not
be a space character or the character <.  This form of pattern matches
a KeyPress event for the particular character.  The second form of
pattern is longer but more general.  It has the following syntax:

     <modifier-modifier-type-detail>

   The entire event pattern is surrounded by angle brackets.  Inside
the angle brackets are zero or more modifiers, an event type, and an
extra piece of information (detail) identifying a particular button or
keysym.  Any of the fields may be omitted, as long as at least one of
type and detail is present.  The fields must be separated by white
space or dashes.

   Modifiers may consist of any of the values in the following list:

     Control                  Any
     Shift                    Double
     Lock                     Triple
     Button1, B1              Mod1, M1, Meta, M
     Button2, B2              Mod2, M2, Alt
     Button3, B3              Mod3, M3
     Button4, B4              Mod4, M4
     Button5, B5              Mod5, M5

   Where more than one value is listed, separated by commas, the values
are equivalent.   All of the modifiers except Any, Double, and Triple
have the obvious X meanings.  For example, Button1 requires that button
1 be depressed when the event occurs.  Under normal conditions the
button and modifier state at the time of the event must match exactly
those specified in the bind command.  If no modifiers are specified,
then events will match only if no modifiers are present.  If the Any
modifier is specified, then additional modifiers may be present besides
those specified explicitly.  For example, if button 1 is pressed while
the shift and control keys are down, the specifier
<Any-Control-Button-1> will match the event, but the specifier
<Control-Button-1> will not.

   The Double and Triple modifiers are a convenience for specifying
double mouse clicks and other repeated events. They cause a particular
event pattern to be repeated 2 or 3 times, and also place a time and
space requirement on the sequence:  for a sequence of events to match a
Double or Triple pattern, all of the events must occur close together
in time and without substantial mouse motion in between.  For example,
<Double-Button-1> is equivalent to <Button-1><Button-1> with the extra
time and space requirement.

   The type field may be any of the standard X event types, with a few
extra abbreviations.  Below is a list of all the valid types; where two
name appear together, they are synonyms.

     ButtonPress, Button      Expose             Leave
     ButtonRelease            FocusIn            Map
     Circulate                FocusOut           Property
     CirculateRequest         Gravity            Reparent
     Colormap                 Keymap             ResizeRequest
     Configure                KeyPress, Key      Unmap
     ConfigureRequest         KeyRelease         Visibility
     Destroy                  MapRequest
     Enter                    Motion

   The last part of a long event specification is detail.  In the case
of a ButtonPress or ButtonRelease event, it is the number of a button
(1-5).  If a button number is given, then only an event on that
particular button will match;  if no button number is given, then an
event on any button will match.  Note:  giving a specific button number
is different than specifying a button modifier; in the first case, it
refers to a button being pressed or released, while in the second it
refers to some other button that is already depressed when the matching
event occurs.  If a button number is given then type may be omitted:
if will default to ButtonPress.  For example, the specifier <1> is
equivalent to <ButtonPress-1>.

   If the event type is KeyPress or KeyRelease, then detail may be
specified in the form of an X keysym.  Keysyms are textual
specifications for particular keys on the keyboard; they include all
the alphanumeric ASCII characters (e.g. "a" is the keysym for the ASCII
character "a"), plus descriptions for non-alphanumeric characters
("comma" is the keysym for the comma character), plus descriptions for
all the non-ASCII keys on the keyboard ("Shift_L" is the keysm for the
left shift key, and "F1" is the keysym for the F1 function key, if it
exists).  The complete list of keysyms is not presented here;  it
should be available in other X documentation.  If necessary, you can
use the %K notation described below to print out the keysym name for an
arbitrary key.  If a keysym detail is given, then the type field may be
omitted;  it will default to KeyPress.  For example, <Control-comma> is
equivalent to <Control-KeyPress-comma>.  If a keysym detail is specified
then the Shift modifier need not be specified and will be ignored if
specified:  each keysym already implies a particular state for the
shift key.

   The command argument to bind is a Tcl command string, which will be
executed whenever the given event sequence occurs.  Command will be
executed in the same interpreter that the bind command was executed in.
If command contains any % characters, then the command string will not
be executed directly.  Instead, a new command string will be generated
by replacing each %, and the character following it, with information
from the current event.  The replacement depends on the character
following the %, as defined in the list below.  Unless otherwise
indicated, the replacement string is the decimal value of the given
field from the current event.  Some of the substitutions are only valid
for certain types of events;  if they are used for other types of events
the value substituted is undefined.

%%
     Replaced with a single percent.

|%#|
     The number of the last client request processed by the server (the
     serial field from the event).  Valid for all event types.

|%a|
     The above field from the event.  Valid only for ConfigureNotify
     events.

|%b|
     The number of the button that was pressed or released.  Valid only
     for ButtonPress and ButtonRelease events.

|%c|
     The count field from the event.  Valid only for Expose,
     GraphicsExpose, and MappingNotify events.

|%d|
     The detail field from the event.  The |%d| is replaced by a string
     identifying the detail.  For EnterNotify, LeaveNotify, FocusIn,
     and FocusOut events, the string will be one of the following:

          NotifyAncestor            NotifyNonlinearVirtual
          NotifyDetailNone          NotifyPointer
          NotifyInferior            NotifyPointerRoot
          NotifyNonlinear           NotifyVirtual

     For ConfigureRequest events, the substituted string will be one of
     the following:

          Above                     Opposite
          Below                     TopIf
          BottomIf

     For events other than these, the substituted string is undefined.
     .RE

|%f|
     The focus field from the event (0 or 1).  Valid only for
     EnterNotify and LeaveNotify events.

|%h|
     The height field from the event.  Valid only for Configure,
     ConfigureNotify, Expose, GraphicsExpose, and ResizeRequest events.

|%k|
     The keycode field from the event.  Valid only for KeyPress and
     KeyRelease events.

|%m|
     The mode field from the event.  The substituted string is one of
     NotifyNormal, NotifyGrab, NotifyUngrab, or NotifyWhileGrabbed.
     Valid only for EnterWindow, FocusIn, FocusOut, and LeaveWindow
     events.

|%o|
     The override_redirect field from the event.  Valid only for
     CreateNotify, MapNotify, ReparentNotify, and ConfigureNotify
     events.

|%p|
     The place field from the event, substituted as one of the strings
     PlaceOnTop or PlaceOnBottom.  Valid only for CirculateNotify and
     CirculateRequest events.

|%s|
     The state field from the event.  For ButtonPress, ButtonRelease,
     EnterNotify, KeyPress, KeyRelease, LeaveNotify, and MotionNotify
     events, a decimal string is substituted.  For VisibilityNotify,
     one of the strings VisibilityUnobscured,
     VisibilityPartiallyObscured, and VisibilityFullyObscured is
     substituted.

|%t|
     The time field from the event.  Valid only for events that contain
     a time field.

|%v|
     The value_mask field from the event.  Valid only for
     ConfigureRequest events.

|%w|
     The width field from the event.  Valid only for Configure,
     ConfigureRequest, Expose, GraphicsExpose, and ResizeRequest events.

|%x|
     The x field from the event.  Valid only for events containing an x
     field.

|%y|
     The y field from the event.  Valid only for events containing a y
     field.

%A
     Substitutes the ASCII character corresponding to the event, or the
     empty string if the event doesn't correspond to an ASCII character
     (e.g. the shift key was pressed).  XLookupString does all the work
     of translating from the event to an ASCII character.  Valid only
     for KeyPress and KeyRelease events.

%B
     The border_width field from the event.  Valid only for
     ConfigureNotify and CreateWindow events.

%D
     The display field from the event.  Valid for all event types.

%E
     The send_event field from the event.  Valid for all event types.

%K
     The keysym corresponding to the event, substituted as a textual
     string.  Valid only for KeyPress and KeyRelease events.

%N
     The keysym corresponding to the event, substituted as a decimal
     number.  Valid only for KeyPress and KeyRelease events.

%R
     The root window identifier from the event.  Valid only for events
     containing a root field.

%S
     The subwindow window identifier from the event.  Valid only for
     events containing a subwindow field.

%T
     The type field from the event.  Valid for all event types.

%W
     The path name of the window to which the event was reported (the
     window field from the event).  Valid for all event types.

%X
     The x_root field from the event.  If a virtual-root window manager
     is being used then the substituted value is the corresponding
     x-coordinate in the virtual root.  Valid only for ButtonPress,
     ButtonRelease, KeyPress, KeyRelease, and MotionNotify events.

%Y
     The y_root field from the event.  If a virtual-root window manager
     is being used then the substituted value is the corresponding
     y-coordinate in the virtual root.  Valid only for ButtonPress,
     ButtonRelease, KeyPress, KeyRelease, and MotionNotify events.

   If the replacement string for a %-replacement contains characters
that are interpreted specially by the Tcl parser (such as backslashes
or square brackets or spaces) additional backslashes are added during
replacement so that the result after parsing is the original
replacement string.  For example, if command is

     insert %A

and the character typed is an open square bracket, then the command
actually executed will be

     insert \e[

   This will cause the insert to receive the original replacement
string (open square bracket) as its first argument.  If the extra
backslash hadn't been added, Tcl would not have been able to parse the
command correctly.

   At most one binding will trigger for any given X event.  If several
bindings match the recent events, the most specific binding is chosen
and its command will be executed.  The following tests are applied, in
order, to determine which of several matching sequences is more
specific: (a) a binding whose windowSpec names a particular window is
more specific than a binding for a class, which is more specific than a
binding whose windowSpec is all; (b) a longer sequence (in terms of
number of events matched) is more specific than a shorter sequence; (c)
an event pattern that specifies a specific button or key is more
specific than one that doesn't;  (e) an event pattern that requires a
particular modifier is more specific than one that doesn't require the
modifier; (e) an event pattern specifying the Any modifier is less
specific than one that doesn't.  If the matching sequences contain more
than one event, then tests (c)-(e) are applied in order from the most
recent event to the least recent event in the sequences.  If these
tests fail to determine a winner, then the most recently registered
sequence is the winner.

   If an X event does not match any of the existing bindings, then the
event is ignored (an unbound event is not considered to be an error).

   When a sequence specified in a bind command contains more than one
event pattern, then its command is executed whenever the recent events
(leading up to and including the current event) match the given
sequence.  This means, for example, that if button 1 is clicked
repeatedly the sequence <Double-ButtonPress-1> will match each button
press but the first.  If extraneous events that would prevent a match
occur in the middle of an event sequence then the extraneous events are
ignored unless they are KeyPress or ButtonPress events.  For example,
<Double-ButtonPress-1> will match a sequence of presses of button 1,
even though there will be ButtonRelease events (and possibly
MotionNotify events) between the ButtonPress events.  Furthermore, a
KeyPress event may be preceded by any number of other KeyPress events
for modifier keys without the modifier keys preventing a match.  For
example, the event sequence aB will match a press of the a key, a
release of the a key, a press of the Shift key, and a press of the b
key:  the press of Shift is ignored because it is a modifier key.
Finally, if several MotionNotify events occur in a row, only the last
one is used for purposes of matching binding sequences.

   If an error occurs in executing the command for a binding then the
tkerror mechanism is used to report the error.  The command will be
executed at global level (outside the context of any Tcl procedure).

   See tkerror

Keywords
--------

   form, manual

destroy
=======

   destroy \- Destroy one or more windows

Synopsis
--------

   destroy ?window window ...?

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

   This command deletes the windows given by the window arguments, plus
all of their descendants.  If a window "." is deleted then the entire
application will be destroyed.  The windows are destroyed in order, and
if an error occurs in destroying a window the command aborts without
destroying the remaining windows.

Keywords
--------

   application, destroy, window

tk-dialog
=========

   tk-dialog \- Create modal dialog and wait for response

Synopsis
--------

   tk-dialog window title text bitmap default string string ...

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

   This procedure is part of the Tk script library.  Its arguments
describe a dialog box:

window
     Name of top-level window to use for dialog.  Any existing window
     by this name is destroyed.

title
     Text to appear in the window manager's title bar for the dialog.

text
     Message to appear in the top portion of the dialog box.

bitmap
     If non-empty, specifies a bitmap to display in the top portion of
     the dialog, to the left of the text.  If this is an empty string
     then no bitmap is displayed in the dialog.

default
     If this is an integer greater than or equal to zero, then it gives
     the index of the button that is to be the default button for the
     dialog (0 for the leftmost button, and so on).  If less than zero
     or an empty string then there won't be any default button.

string
     There will be one button for each of these arguments.  Each string
     specifies text to display in a button, in order from left to right.

     After creating a dialog box, tk-dialog waits for the user to
     select one of the buttons either by clicking on the button with the
     mouse or by typing return to invoke the default button (if any).
     Then it returns the index of the selected button:  0 for the
     leftmost button, 1 for the button next to it, and so on.

     While waiting for the user to respond, tk-dialog sets a local
     grab.  This prevents the user from interacting with the application
     in any way except to invoke the dialog box.

Keywords
--------

   bitmap, dialog, modal

exit
====

   exit \- Exit the process

Synopsis
--------

   exit ?returnCode?

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

   Terminate the process, returning returnCode (an integer) to the
system as the exit status.  If returnCode isn't specified then it
defaults to 0.  This command replaces the Tcl command by the same name.
It is identical to Tcl's exit command except that before exiting it
destroys all the windows managed by the process.  This allows various
cleanup operations to be performed, such as removing application names
from the global registry of applications.

Keywords
--------

   exit, process