File: widgets.texi

package info (click to toggle)
gcl 2.6.14-19
links: PTS
area: main
in suites: forky, sid, trixie
size: 60,804 kB
sloc: ansic: 177,407; lisp: 151,508; asm: 128,169; sh: 22,510; cpp: 11,923; tcl: 3,181; perl: 2,930; makefile: 2,360; sed: 334; yacc: 226; lex: 95; awk: 30; fortran: 24; csh: 23
file content (5033 lines) | stat: -rwxr-xr-x 204,005 bytes
parent folder | download | duplicates (7)
@c  Copyright (c) 1994 William Schelter.


@c  Copyright (c) 1990 The Regents of the University of California.
@c  All rights reserved.
@c 
@c  Permission is hereby granted, without written agreement and without
@c  license or royalty fees, to use, copy, modify, and distribute this
@c  documentation for any purpose, provided that the above copyright
@c  notice and the following two paragraphs appear in all copies.
@c 
@c  IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
@c  FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
@c  ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
@c  CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@c 
@c  THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
@c  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
@c  AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
@c  ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
@c  PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

@node Widgets, Control, General, Top
@chapter Widgets

@menu
* button::			
* listbox::			
* scale::			
* canvas::			
* menu::			
* scrollbar::			
* checkbutton::			
* menubutton::			
* text::			
* entry::			
* message::			
* frame::			
* label::			
* radiobutton::			
* toplevel::			
@end menu

@node button, listbox, Widgets, Widgets
@section button
@c @cartouche

button \- Create and manipulate button widgets
@unnumberedsubsec Synopsis
@b{button}@i{ }@i{pathName }@r{?}@i{options}?
@unnumberedsubsec Standard Options


@example
activeBackground  bitmap              font        relief        
activeForeground  borderWidth         foreground  text          
anchor            cursor              padX        textVariable  
background        disabledForeground  padY        
@end example      


@xref{options}, for more information.
@unnumberedsubsec Arguments for Button


@table  @asis
@item @code{@b{:command}}
@flushright
Name=@code{"@b{command}@r{"} Class=@code{"}@b{Command}"}
@end flushright
@sp 1

Specifies a Tcl command to associate with the button.  This command
is typically invoked when mouse button 1 is released over the button
window.
@end table


@table @asis
@item @code{@b{:height}}
@flushright
Name=@code{"@b{height}@r{"} Class=@code{"}@b{Height}"}
@end flushright
@sp 1

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 @b{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.
@end table


@table @asis
@item @code{@b{:state}}
@flushright
Name=@code{"@b{state}@r{"} Class=@code{"}@b{State}"}
@end flushright
@sp 1

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


@table @asis
@item @code{@b{:width}}
@flushright
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
@end flushright
@sp 1

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 @b{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.
@end table
@c @end cartouche

@unnumberedsubsec Description

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

A button is a widget
that displays a textual string or bitmap.
It can display itself in either of three different ways, according
to
the @b{state} option; 
it can be made to appear raised, sunken, or flat;
and it can be made to flash.  When a user invokes the
button (by pressing mouse button 1 with the cursor over the
button), then the Tcl command specified in the @b{:command}
option is invoked.

@unnumberedsubsec A Button Widget's Arguments

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

@example
@i{pathName option }@r{?}@i{arg arg ...}?
@end example

@i{Option}@r{ and the }@i{arg}s
determine the exact behavior of the command.  The following
commands are possible for button widgets:

@table @asis
@item @i{pathName }@b{:activate}
Change the button's state to @b{active} and redisplay the button
using its active foreground and background colors instead of normal
colors.
This command is ignored if the button's state is @b{disabled}.
This command is obsolete and will eventually be removed;
use ``@i{pathName }@b{:configure :state active}'' instead.
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
Query or modify the configuration options of the widget.
If no @i{option} is specified, returns a list describing all of
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
information on the format of this list).  If @i{option} is specified
with no @i{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 @i{option} is specified).  If
one or more @i{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.
@i{Option}@r{ may have any of the values accepted by the }@b{button}
command.
@item @i{pathName }@b{:deactivate}
Change the button's state to @b{normal} and redisplay the button
using its normal foreground and background colors.
This command is ignored if the button's state is @b{disabled}.
This command is obsolete and will eventually be removed;
use ``@i{pathName }@b{:configure :state normal}'' instead.
@item @i{pathName }@b{:flash}
Flash the button.  This is accomplished by redisplaying the button
several times, alternating between active and normal colors.  At
the end of the flash the button is left in the same normal/active
state as when the command was invoked.
This command is ignored if the button's state is @b{disabled}.
@item @i{pathName }@b{:invoke}
Invoke the Tcl command associated with the button, 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 button.
This command is ignored if the button's state is @b{disabled}.

@end table
@unnumberedsubsec "Default Bindings"

Tk automatically creates class bindings for buttons that give them
the following default behavior:
@itemize @asis{}
@item
[1]
The button activates whenever the mouse passes over it and deactivates
whenever the mouse leaves the button.
@item
[2]
The button's relief is changed to sunken whenever mouse button 1 is
pressed over the button, and the relief is restored to its original
value when button 1 is later released.
@item
[3]
If mouse button 1 is pressed over the button and later released over
the button, the button is invoked.  However, if the mouse is not
over the button when button 1 is released, then no invocation occurs.
@end itemize

If the button's state is @b{disabled} then none of the above
actions occur:  the button is completely non-responsive.

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

@unnumberedsubsec Keywords
button, widget
@node listbox, scale, button, Widgets
@section listbox
@c @cartouche

listbox \- Create and manipulate listbox widgets
@unnumberedsubsec Synopsis
@b{listbox}@i{ }@i{pathName }@r{?}@i{options}?
@unnumberedsubsec Standard Options


@example
background       foreground  selectBackground   xScrollCommand  
borderWidth      font        selectBorderWidth  yScrollCommand  
cursor           geometry    selectForeground   
exportSelection  relief      setGrid            
@end example     


@xref{options}, for more information.
@unnumberedsubsec Arguments for Listbox


None.
@c @end cartouche

@unnumberedsubsec Description

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

A listbox is a widget that displays a list of strings, one per line.
When first created, a new listbox has no elements in its list.
Elements may be added or deleted using widget commands described
below.  In addition, one or more elements may be selected as described
below.
If a listbox is exporting its selection (see @b{exportSelection}
option), then it will observe the standard X11 protocols
for handling the selection;  listbox selections are available
as type @b{STRING}, consisting of a Tcl list with one entry
for each selected element.

For large lists only a subset of the list elements will be
displayed in the listbox window at once;  commands described below
may be used to change the view in the window.  Listboxes allow
scrolling in both directions using the standard @b{xScrollCommand}
and @b{yScrollCommand} options.
They also support scanning, as described below.

@unnumberedsubsec A Listbox's Arguments

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

@example
@i{pathName option }@r{?}@i{arg arg ...}?
@end example

@i{Option}@r{ and the }@i{arg}s
determine the exact behavior of the command.  The following
commands are possible for listbox widgets:

@table @asis
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
Query or modify the configuration options of the widget.
If no @i{option} is specified, returns a list describing all of
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
information on the format of this list).  If @i{option} is specified
with no @i{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 @i{option} is specified).  If
one or more @i{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.
@i{Option}@r{ may have any of the values accepted by the }@b{listbox}
command.
@item @i{pathName }@b{:curselection}
Returns a list containing the indices of
all of the elements in the listbox that are currently selected.
If there are no elements selected in the listbox then an empty
string is returned.
@item @i{pathName }@b{:delete }@i{first }@r{?}@i{last}?
Delete one or more elements of the listbox.  @i{First}@r{ and }@i{last}
give the integer indices of the first and last elements in the range
to be deleted.  If @i{last} isn't specified it defaults to
@i{first}, i.e. a single element is deleted.  An index of
@b{0} corresponds to the first element in the listbox.  Either
@i{first}@r{ or }@i{last}@r{ may be specified as }@b{end}, in which
case it refers to the last element of the listbox.  This command
returns an empty string
@item @i{pathName }@b{:get }@i{index}
Return the contents of the listbox element indicated by @i{index}.
@i{Index} must be a non-negative integer (0 corresponds to
the first element in the listbox), or it may also be specified as
@b{end} to indicate the last element in the listbox.
@item @i{pathName }@b{:insert }@i{index }@r{?}@i{element element ...}?
Insert zero or more new elements in the list just before the
element given by @i{index}@r{.  If }@i{index} is specified as
@b{end} then the new elements are added to the end of the
list.  Returns an empty string.
@item @i{pathName }@b{:nearest }@i{y}
Given a y-coordinate within the listbox window, this command returns
the index of the (visible) listbox element nearest to that y-coordinate.
@item @i{pathName }@b{:scan}@r{ }@i{option args}
This command is used to implement scanning on listboxes.  It has
two forms, depending on @i{option}:
@table @asis
@item @i{pathName }@b{:scan :mark }@i{x y}
Records @i{x}@r{ and }@i{y} and the current view in the listbox
window;  used in conjunction with later @b{scan dragto} commands.
Typically this command is associated with a mouse button press in
the widget.  It returns an empty string.
@item @i{pathName }@b{:scan :dragto }@i{x y}.
This command computes the difference between its @i{x}@r{ and }@i{y}
arguments and the @i{x}@r{ and }@i{y} arguments to the last
@b{scan mark} command for the widget.
It then adjusts the view by 10 times the
difference in coordinates.  This command is typically associated
with mouse motion events in the widget, to produce the effect of
dragging the list at high speed through the window.  The return
value is an empty string.
@end table
@item @i{pathName }@b{:select }@i{option arg}
This command is used to adjust the selection within a listbox.  It
has several forms, depending on @i{option}.  In all of the forms
the index @b{end} refers to the last element in the listbox.
@table @asis
@item @i{pathName }@b{:select :adjust }@i{index}
Locate the end of the selection nearest to the element given by
@i{index}@r{, and adjust that end of the selection to be at }@i{index}
(i.e including but not going beyond @i{index}).  The other
end of the selection is made the anchor point for future
@b{select to} commands.  If the selection
isn't currently in the listbox, then this command is identical to
the @b{select from} widget command.
Returns an empty string.
@item @i{pathName }@b{:select :clear}
If the selection is in this listbox then it is cleared so that
none of the listbox's elements are selected anymore.
@item @i{pathName }@b{:select :from }@i{index}
Set the selection to consist of element @i{index}, and make
@i{index}@r{ the anchor point for future }@b{select to} widget
commands.  Returns an empty string.
@item @i{pathName }@b{:select :to }@i{index}
Set the selection to consist of the elements from the anchor
point to element @i{index}, inclusive.  The anchor point is
determined by the most recent @b{select from}@r{ or }@b{select adjust}
command in this widget.  If the selection isn't in this widget,
this command is identical to @b{select from}.
Returns an empty string.
@end table

@item @i{pathName }@b{:size}
Returns a decimal string indicating the total number of elements
in the listbox.
@item @i{pathName }@b{:xview }@i{index}
Adjust the view in the listbox so that character position @i{index}
is displayed at the left edge of the widget.
Returns an empty string.
@item @i{pathName }@b{:yview }@i{index}
Adjust the view in the listbox so that element @i{index} is
displayed at the top of the widget.
If @i{index}@r{ is specified as }@b{end} it indicates the last
element of the listbox.  Returns an empty string.

@end table
@unnumberedsubsec "Default Bindings"

Tk automatically creates class bindings for listboxes that give them
the following default behavior:
@itemize @asis{}
@item
[1]
When button 1 is pressed over a listbox, the element underneath the
mouse cursor is selected.  The mouse can be dragged to select a
range of elements.
@item
[2]
The ends of the selection can be adjusted by dragging with mouse
button 1 while the shift key is down;  this will adjust the end
of the selection that was nearest to the mouse cursor when button
1 was pressed.
@item
[3]
The view in the listbox can be adjusted by dragging with mouse button 2.
@end itemize

The behavior of listboxes can be changed by defining new bindings for
individual widgets or by redefining the class bindings.
In addition, the procedure @b{tk_listboxSingleSelect} may be
invoked to change listbox behavior so that only a single element
may be selected at once.

@unnumberedsubsec Keywords
listbox, widget
@node scale, canvas, listbox, Widgets
@section scale
@c @cartouche

scale \- Create and manipulate scale widgets
@unnumberedsubsec Synopsis
@b{scale}@i{ }@i{pathName }@r{?}@i{options}?
@unnumberedsubsec Standard Options


@example
activeForeground     borderWidth     font           orient     
background           cursor          foreground     relief     
@end example         


@xref{options}, for more information.
@unnumberedsubsec Arguments for Scale


@table @asis
@item @code{@b{:command}}
@flushright
Name=@code{"@b{command}@r{"} Class=@code{"}@b{Command}"}
@end flushright
@sp 1

Specifies the prefix of a Tcl command to invoke whenever the value of
the scale is changed interactively.  The actual command consists
of this option followed by
a space and a number.  The number indicates the new value of the
scale.
@end table


@table @asis
@item @code{@b{:from}}
@flushright
Name=@code{"@b{from}@r{"} Class=@code{"}@b{From}"}
@end flushright
@sp 1

Specifies the value corresponding to the left or top end of the
scale.  Must be an integer.
@end table


@table @asis
@item @code{@b{:label}}
@flushright
Name=@code{"@b{label}@r{"} Class=@code{"}@b{Label}"}
@end flushright
@sp 1

Specifies a string to displayed  as a label for the scale.  For
vertical scales the label is displayed just to the right of the
top end of the scale.  For horizontal scales the label is displayed
just above the left end of the scale.
@end table


@table @asis
@item @code{@b{:length}}
@flushright
Name=@code{"@b{length}@r{"} Class=@code{"}@b{Length}"}
@end flushright
@sp 1

Specifies the desired long dimension of the scale in screen units,
that is in any of the forms acceptable to @b{Tk_GetPixels}.
For vertical scales this is the scale's height;  for horizontal scales
it is the scale's width.
@end table


@table @asis
@item @code{@b{:showvalue}}
@flushright
Name=@code{"@b{showValue}@r{"} Class=@code{"}@b{ShowValue}"}
@end flushright
@sp 1

Specifies a boolean value indicating whether or not the current
value of the scale is to be displayed.
@end table


@table @asis
@item @code{@b{:sliderforeground}}
@flushright
Name=@code{"@b{sliderForeground}@r{"} Class=@code{"}@b{sliderForeground}"}
@end flushright
@sp 1

Specifies the color to use for drawing the slider under normal conditions.
When the mouse is in the slider window then the slider's color is
determined by the @b{activeForeground} option.
@end table


@table @asis
@item @code{@b{:sliderlength}}
@flushright
Name=@code{"@b{sliderLength}@r{"} Class=@code{"}@b{SliderLength}"}
@end flushright
@sp 1

Specfies the size of the slider, measured in screen units along the slider's
long dimension.  The value may be specified in any of the forms acceptable
to @b{Tk_GetPixels}.
@end table


@table @asis
@item @code{@b{:state}}
@flushright
Name=@code{"@b{state}@r{"} Class=@code{"}@b{State}"}
@end flushright
@sp 1

Specifies one of two states for the scale:  @b{normal}@r{ or }@b{disabled}.
If the scale is disabled then the value may not be changed and the scale
won't activate when the mouse enters it.
@end table


@table @asis
@item @code{@b{:tickinterval}}
@flushright
Name=@code{"@b{tickInterval}@r{"} Class=@code{"}@b{TickInterval}"}
@end flushright
@sp 1

Must be an integer value.  Determines the spacing between numerical
tick-marks displayed below or to the left of the slider.  If specified
as 0, then no tick-marks will be displayed.
@end table


@table @asis
@item @code{@b{:to}}
@flushright
Name=@code{"@b{to}@r{"} Class=@code{"}@b{To}"}
@end flushright
@sp 1

Specifies the value corresponding to the right or bottom end of the
scale.  Must be an integer.  This value may be either less than or
greater than the @b{from} option.
@end table


@table @asis
@item @code{@b{:width}}
@flushright
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
@end flushright
@sp 1

Specifies the desired narrow dimension of the scale in screen units
(i.e. any of the forms acceptable to @b{Tk_GetPixels}).
For vertical scales this is the scale's width;  for horizontal scales
this is the scale's height.
@end table
@c @end cartouche

@unnumberedsubsec Description

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

A scale is a widget that displays a rectangular region and a
small @i{slider}.  The rectangular region corresponds to a range
of integer values (determined by the @b{from}@r{ and }@b{to} options),
and the position of the slider selects a particular integer value.
The slider's position (and hence the scale's value) may be adjusted
by clicking or dragging with the mouse as described in the BINDINGS
section below.  Whenever the scale's value is changed, a Tcl
command is invoked (using the @b{command} option) to notify
other interested widgets of the change.

Three annotations may be displayed in a scale widget:  a label
appearing at the top-left of the widget (top-right for vertical
scales), a number displayed just underneath the slider
(just to the left of the slider for vertical scales), and a collection
of numerical tick-marks just underneath the current value (just to the left of
the current value for vertical scales).  Each of these three
annotations may be selectively enabled or disabled using the
configuration options.

@unnumberedsubsec A Scale's"Argumentsommand"

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

@example
@i{pathName option }@r{?}@i{arg arg ...}?
@end example

@i{Option}@r{ and the }@i{arg}s
determine the exact behavior of the command.  The following
commands are possible for scale widgets:

@table @asis
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
Query or modify the configuration options of the widget.
If no @i{option} is specified, returns a list describing all of
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
information on the format of this list).  If @i{option} is specified
with no @i{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 @i{option} is specified).  If
one or more @i{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.
@i{Option}@r{ may have any of the values accepted by the }@b{scale}
command.
@item @i{pathName }@b{:get}
Returns a decimal string giving the current value of the scale.
@item @i{pathName }@b{:set}@r{ }@i{value}
This command is invoked to change the current value of the scale,
and hence the position at which the slider is displayed.  @i{Value}
gives the new value for the scale.

@end table
@unnumberedsubsec Bindings

When a new scale is created, it is given the following initial
behavior by default:

@table @asis
@item @b{<Enter>}
Change the slider display to use @b{activeForeground} instead of
@b{sliderForeground}.
@item @b{<Leave>}
Reset the slider display to use @b{sliderForeground} instead of
@b{activeForeground}.
@item @b{<ButtonPress-1>}
Change the slider display so that the slider appears sunken rather
than raised.  Move the slider (and adjust the scale's value)
to correspond to the current mouse position.
@item @b{<Button1-Motion>}
Move the slider (and adjust the scale's value) to correspond to
the current mouse position.
@item @b{<ButtonRelease-1>}
Reset the slider display so that the slider appears raised again.

@end table
@unnumberedsubsec Keywords
scale, widget
@node canvas, menu, scale, Widgets
@section canvas
@c @cartouche

canvas \- Create and manipulate canvas widgets
@unnumberedsubsec Synopsis
@b{canvas}@i{ }@i{pathName }@r{?}@i{options}?
@unnumberedsubsec Standard Options


@example
background       insertBorderWidth relief            xScrollCommand 
borderWidth      insertOffTime     selectBackground  yScrollCommand 
cursor           insertOnTime      selectBorderWidth 
insertBackground insertWidth       selectForeground  
@end example     


@xref{options}, for more information.
@unnumberedsubsec Arguments for Canvas


@table @asis
@item @code{@b{:closeenough}}
@flushright
Name=@code{"@b{closeEnough}@r{"} Class=@code{"}@b{CloseEnough}"}
@end flushright
@sp 1

Specifies a floating-point value indicating how close the mouse cursor
must be to an item before it is considered to be ``inside'' the item.
Defaults to 1.0.
@end table


@table @asis
@item @code{@b{:confine}}
@flushright
Name=@code{"@b{confine}@r{"} Class=@code{"}@b{Confine}"}
@end flushright
@sp 1

Specifies a boolean value that indicates whether or not it should be
allowable to set the canvas's view outside the region defined by the
@b{scrollRegion} argument.
Defaults to true, which means that the view will
be constrained within the scroll region.
@end table


@table @asis
@item @code{@b{:height}}
@flushright
Name=@code{"@b{height}@r{"} Class=@code{"}@b{Height}"}
@end flushright
@sp 1

Specifies a desired window height that the canvas widget should request from
its geometry manager.  The value may be specified in any
of the forms described in the COORDINATES section below.
@end table


@table @asis
@item @code{@b{:scrollincrement}}
@flushright
Name=@code{"@b{scrollIncrement}@r{"} Class=@code{"}@b{ScrollIncrement}"}
@end flushright
@sp 1

Specifies a distance used as increment during scrolling:  when one of
the arrow buttons on an associated scrollbar is pressed, the picture
will shift by this distance.  The distance may be specified in any
of the forms described in the COORDINATES section below.
@end table


@table @asis
@item @code{@b{:scrollregion}}
@flushright
Name=@code{"@b{scrollRegion}@r{"} Class=@code{"}@b{ScrollRegion}"}
@end flushright
@sp 1

Specifies a list with four coordinates describing the left, top, right, and
bottom coordinates of a rectangular region.
This region is used for scrolling purposes and is considered to be
the boundary of the information in the canvas.
Each of the coordinates may be specified
in any of the forms given in the COORDINATES section below.
@end table


@table @asis
@item @code{@b{:width}}
@flushright
Name=@code{"@b{width}@r{"} Class=@code{"}@b{width}"}
@end flushright
@sp 1

Specifies a desired window width that the canvas widget should request from
its geometry manager.  The value may be specified in any
of the forms described in the COORDINATES section below.
@end table
@c @end cartouche

@unnumberedsubsec Introduction

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

Canvas widgets implement structured graphics.
A canvas displays any number of @i{items}, which may be things like
rectangles, circles, lines, and text.
Items may be manipulated (e.g. moved or re-colored) and commands may
be associated with items in much the same way that the @b{bind}
command allows commands to be bound to widgets.  For example,
a particular command may be associated with the <Button-1> event
so that the command is invoked whenever button 1 is pressed with
the mouse cursor over an item.
This means that items in a canvas can have behaviors defined by
the Tcl scripts bound to them.

@unnumberedsubsec Display List

The items in a canvas are ordered for purposes of display,
with the first item in the display list being displayed
first, followed by the next item in the list, and so on.
Items later in the display list obscure those that are
earlier in the display list and are sometimes referred to
as being ``on top'' of earlier items.
When a new item is created it is placed at the end of the
display list, on top of everything else.
Widget commands may be used to re-arrange the order of the
display list.

@unnumberedsubsec Item Ids And Tags

Items in a canvas widget may be named in either of two ways:
by id or by tag.
Each item has a unique identifying number which is assigned to
that item when it is created.  The id of an item never changes
and id numbers are never re-used within the lifetime of a
canvas widget.

Each item may also have any number of @i{tags} associated
with it.  A tag is just a string of characters, and it may
take any form except that of an integer.
For example, ``x123'' is OK but ``123'' isn't.
The same tag may be associated with many different items.
This is commonly done to group items in various interesting
ways;  for example, all selected items might be given the
tag ``selected''.

The tag @b{all} is implicitly associated with every item
in the canvas;  it may be used to invoke operations on
all the items in the canvas.

The tag @b{current} is managed automatically by Tk;
it applies to the @i{current item}, which is the
topmost item whose drawn area covers the position of
the mouse cursor.
If the mouse is not in the canvas widget or is not over
an item, then no item has the @b{current} tag.

When specifying items in canvas widget commands, if the
specifier is an integer then it is assumed to refer to
the single item with that id.
If the specifier is not an integer, then it is assumed to
refer to all of the items in the canvas that have a tag
matching the specifier.
The symbol @i{tagOrId} is used below to indicate that
an argument specifies either an id that selects a single
item or a tag that selects zero or more items.
Some widget commands only operate on a single item at a
time;  if @i{tagOrId} is specified in a way that
names multiple items, then the normal behavior is for
the command to use the first (lowest) of these items in
the display list that is suitable for the command.
Exceptions are noted in the widget command descriptions
below.

@unnumberedsubsec Coordinates

All coordinates related to canvases are stored as floating-point
numbers.
Coordinates and distances are specified in screen units,
which are floating-point numbers optionally followed
by one of several letters.
If no letter is supplied then the distance is in pixels.
If the letter is @b{m} then the distance is in millimeters on
the screen;  if it is @b{c} then the distance is in centimeters;
@b{i}@r{ means inches, and }@b{p} means printers points (1/72 inch).
Larger y-coordinates refer to points lower on the screen;  larger
x-coordinates refer to points farther to the right.

@unnumberedsubsec Transformations

Normally the origin of the canvas coordinate system is at the
upper-left corner of the window containing the canvas.
It is possible to adjust the origin of the canvas
coordinate system relative to the origin of the window using the
@b{xview}@r{ and }@b{yview} widget commands;  this is typically used
for scrolling.
Canvases do not support scaling or rotation of the canvas coordinate
system relative to the window coordinate system.

Indidividual items may be moved or scaled using widget commands
described below, but they may not be rotated.

@unnumberedsubsec Indices

Text items support the notion of an @i{index} for identifying
particular positions within the item.
Indices are used for commands such as inserting text, deleting
a range of characters, and setting the insertion cursor position.
An index may be specified in any of a number of ways, and
different types of items may support different forms for
specifying indices.
Text items support the following forms for an index;  if you
define new types of text-like items, it would be advisable to
support as many of these forms as practical.
Note that it is possible to refer to the character just after
the last one in the text item;  this is necessary for such
tasks as inserting new text at the end of the item.

@table @asis
@item @i{number}
A decimal number giving the position of the desired character
within the text item.
0 refers to the first character, 1 to the next character, and
so on.
A number less than 0 is treated as if it were zero, and a
number greater than the length of the text item is treated
as if it were equal to the length of the text item.
@item @b{end}
Refers to the character just after the last one in the item
(same as the number of characters in the item).
@item @b{insert}
Refers to the character just before which the insertion cursor
is drawn in this item.
@item @b{sel.first}
Refers to the first selected character in the item.
If the selection isn't in this item then this form is illegal.
@item @b{sel.last}
Refers to the last selected character in the item.
If the selection isn't in this item then this form is illegal.
@item @b{@@}@i{x,y}
Refers to the character at the point given by @i{x} and
@i{y}@r{, where }@i{x}@r{ and }@i{y} are specified in the coordinate
system of the canvas.
If @i{x}@r{ and }@i{y} lie outside the coordinates covered by the
text item, then they refer to the first or last character in the
line that is closest to the given point.

@end table
@unnumberedsubsec A Canvas Widget's Arguments

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

@example
@i{pathName option }@r{?}@i{arg arg ...}?
@end example

@i{Option}@r{ and the }@i{arg}s
determine the exact behavior of the command.
The following widget commands are possible for canvas widgets:

@table @asis
@item @i{pathName }@b{:addtag }@i{tag searchSpec }@r{?}@i{arg arg ...}?
For each item that meets the constraints specified by
@i{searchSpec}@r{ and the }@i{arg}s, add
@i{tag} to the list of tags associated with the item if it
isn't already present on that list.
It is possible that no items will satisfy the constraints
given by @i{searchSpec and }@i{arg}s, in which case the
command has no effect.
This command returns an empty string as result.
@i{SearchSpec}@r{ and }@i{arg}'s may take any of the following
forms:

@table @asis
@item @b{above }@i{tagOrId}
Selects the item just after (above) the one given by @i{tagOrId}
in the display list.
If @i{tagOrId} denotes more than one item, then the last (topmost)
of these items in the display list is used.
@item @b{all}
Selects all the items in the canvas.
@item @b{below }@i{tagOrId}
Selects the item just before (below) the one given by @i{tagOrId}
in the display list.
If @i{tagOrId} denotes more than one item, then the first (lowest)
of these items in the display list is used.
@item @b{closest }@i{x y }@r{?}@i{halo}@r{? ?}@i{start}?
Selects the item closest to the point given by @i{x}@r{ and }@i{y}.
If more than one item is at the same closest distance (e.g. two
items overlap the point), then the top-most of these items (the
last one in the display list) is used.
If @i{halo} is specified, then it must be a non-negative
value.
Any item closer than @i{halo} to the point is considered to
overlap it.
The @i{start} argument may be used to step circularly through
all the closest items.
If @i{start} is specified, it names an item using a tag or id
(if by tag, it selects the first item in the display list with
the given tag).
Instead of selecting the topmost closest item, this form will
select the topmost closest item that is below @i{start} in
the display list;  if no such item exists, then the selection
behaves as if the @i{start} argument had not been specified.
@item @b{enclosed}@r{ }@i{x1}@r{ }@i{y1}@r{ }@i{x2}@r{ }@i{y2}
Selects all the items completely enclosed within the rectangular
region given by @i{x1}@r{, }@i{y1}@r{, }@i{x2}@r{, and }@i{y2}.
@i{X1}@r{ must be no greater then }@i{x2}@r{ and }@i{y1} must be
no greater than @i{y2}.
@item @b{overlapping}@r{ }@i{x1}@r{ }@i{y1}@r{ }@i{x2}@r{ }@i{y2}
Selects all the items that overlap or are enclosed within the
rectangular region given by @i{x1}@r{, }@i{y1}@r{, }@i{x2},
and @i{y2}.
@i{X1}@r{ must be no greater then }@i{x2}@r{ and }@i{y1} must be
no greater than @i{y2}.
@item @b{withtag }@i{tagOrId}
Selects all the items given by @i{tagOrId}.
@end table

@item @i{pathName }@b{:bbox }@i{tagOrId}@r{ ?}@i{tagOrId tagOrId ...}?
Returns a list with four elements giving an approximate bounding box
for all the items named by the @i{tagOrId} arguments.
The list has the form ``@i{x1 y1 x2 y2}'' such that the drawn
areas of all the named elements are within the region bounded by
@i{x1}@r{ on the left, }@i{x2}@r{ on the right, }@i{y1} on the top,
and @i{y2} on the bottom.
The return value may overestimate the actual bounding box by
a few pixels.
If no items match any of the @i{tagOrId} arguments then an
empty string is returned.
@item @i{pathName }@b{:bind }@i{tagOrId}@r{ ?}@i{sequence}@r{? ?}@i{command}?
This command associates @i{command} with all the items given by
@i{tagOrId} such that whenever the event sequence given by
@i{sequence} occurs for one of the items the command will
be invoked.
This widget command is similar to the @b{bind} command except that
it operates on items in a canvas rather than entire widgets.
See the @b{bind} manual entry for complete details
on the syntax of @i{sequence} and the substitutions performed
on @i{command} before invoking it.
If all arguments are specified then a new binding is created, replacing
any existing binding for the same @i{sequence}@r{ and }@i{tagOrId}
(if the first character of @i{command}@r{ is ``+'' then }@i{command}
augments an existing binding rather than replacing it).
In this case the return value is an empty string.
If @i{command}@r{ is omitted then the command returns the }@i{command}
associated with @i{tagOrId}@r{ and }@i{sequence} (an error occurs
if there is no such binding).
If both @i{command}@r{ and }@i{sequence} are omitted then the command
returns a list of all the sequences for which bindings have been
defined for @i{tagOrId}.
@end table


The only events for which bindings may be specified are those related
to the mouse and keyboard, such as @b{Enter}@r{, }@b{Leave},
@b{ButtonPress}@r{, }@b{Motion}@r{, and }@b{KeyPress}.
The handling of events in canvases uses the current item defined
in ITEM IDS AND TAGS above.
@b{Enter}@r{ and }@b{Leave} events trigger for an item when it
becomes the current item or ceases to be the current item;  note
that these events are different than @b{Enter}@r{ and }@b{Leave}
events for windows.
Mouse-related events are directed to the current item, if any.
Keyboard-related events are directed to the focus item, if any
(see the @b{focus} widget command below for more on this).


It is possible for multiple commands to be bound to a single
event sequence for a single object.
This occurs, for example, if one command is associated with the
item's id and another is associated with one of the item's tags.
When this occurs, the first matching binding is used.
A binding for the item's id has highest priority, followed by
the oldest tag for the item and proceeding through all of the
item's tags up through the most-recently-added one.
If a binding is associated with the tag @b{all}, the binding
will have lower priority than all other bindings associated
with the item.

@table @asis
@item @i{pathName }@b{:canvasx }@i{screenx}@r{ ?}@i{gridspacing}?
Given a screen x-coordinate @i{screenx} this command returns
the canvas x-coordinate that is displayed at that location.
If @i{gridspacing} is specified, then the canvas coordinate is
rounded to the nearest multiple of @i{gridspacing} units.
@item @i{pathName }@b{:canvasy }@i{screeny}@r{ ?}@i{gridspacing}?
Given a screen y-coordinate @i{screeny} this command returns
the canvas y-coordinate that is displayed at that location.
If @i{gridspacing} is specified, then the canvas coordinate is
rounded to the nearest multiple of @i{gridspacing} units.
@item @i{pathName }@b{:configure ?}@i{option}@r{? ?}@i{value}@r{? ?}@i{option value ...}?
Query or modify the configuration options of the widget.
If no @i{option} is specified, returns a list describing all of
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
information on the format of this list).  If @i{option} is specified
with no @i{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 @i{option} is specified).  If
one or more @i{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.
@i{Option}@r{ may have any of the values accepted by the }@b{canvas}
command.
@item @i{pathName}@r{ }@b{:coords }@i{tagOrId }@r{?}@i{x0 y0 ...}?
Query or modify the coordinates that define an item.
If no coordinates are specified, this command returns a list
whose elements are the coordinates of the item named by
@i{tagOrId}.
If coordinates are specified, then they replace the current
coordinates for the named item.
If @i{tagOrId} refers to multiple items, then
the first one in the display list is used.
@item @i{pathName }@b{:create }@i{type x y }@r{?}@i{x y ...}@r{? ?}@i{option value ...}?
Create a new item in @i{pathName}@r{ of type }@i{type}.
The exact format of the arguments after @b{type} depends
on @b{type}, but usually they consist of the coordinates for
one or more points, followed by specifications for zero or
more item options.
See the subsections on individual item types below for more
on the syntax of this command.
This command returns the id for the new item.
@item @i{pathName }@b{:dchars }@i{tagOrId first }@r{?}@i{last}?
For each item given by @i{tagOrId}, delete the characters
in the range given by @i{first}@r{ and }@i{last},
inclusive.
If some of the items given by @i{tagOrId} don't support
text operations, then they are ignored.
@i{First}@r{ and }@i{last} are indices of characters
within the item(s) as described in INDICES above.
If @i{last}@r{ is omitted, it defaults to }@i{first}.
This command returns an empty string.
@item @i{pathName }@b{:delete }@r{?}@i{tagOrId tagOrId ...}?
Delete each of the items given by each @i{tagOrId}, and return
an empty string.
@item @i{pathName }@b{:dtag }@i{tagOrId }@r{?tagToDelete}?
For each of the items given by @i{tagOrId}, delete the
tag given by @i{tagToDelete} from the list of those
associated with the item.
If an item doesn't have the tag @i{tagToDelete} then
the item is unaffected by the command.
If @i{tagToDelete}@r{ is omitted then it defaults to }@i{tagOrId}.
This command returns an empty string.
@item @i{pathName }@b{:find }@i{searchCommand }@r{?}@i{arg arg ...}?
This command returns a list consisting of all the items that
meet the constraints specified by @i{searchCommand} and
@i{arg}'s.
@i{SearchCommand}@r{ and }@i{args} have any of the forms
accepted by the @b{addtag} command.
@item @i{pathName }@b{:focus }@r{?}@i{tagOrId}?
Set the keyboard focus for the canvas widget to the item given by
@i{tagOrId}.
If @i{tagOrId} refers to several items, then the focus is set
to the first such item in the display list that supports the
insertion cursor.
If @i{tagOrId} doesn't refer to any items, or if none of them
support the insertion cursor, then the focus isn't changed.
If @i{tagOrId} is an empty
string, then the focus item is reset so that no item has the focus.
If @i{tagOrId} is not specified then the command returns the
id for the item that currently has the focus, or an empty string
if no item has the focus.
@end table


Once the focus has been set to an item, the item will display
the insertion cursor and all keyboard events will be directed
to that item.
The focus item within a canvas and the focus window on the
screen (set with the @b{focus} command) are totally independent:
a given item doesn't actually have the input focus unless (a)
its canvas is the focus window and (b) the item is the focus item
within the canvas.
In most cases it is advisable to follow the @b{focus} widget
command with the @b{focus} command to set the focus window to
the canvas (if it wasn't there already).

@table @asis
@item @i{pathName }@b{:gettags}@r{ }@i{tagOrId}
Return a list whose elements are the tags associated with the
item given by @i{tagOrId}.
If @i{tagOrId} refers to more than one item, then the tags
are returned from the first such item in the display list.
If @i{tagOrId} doesn't refer to any items, or if the item
contains no tags, then an empty string is returned.
@item @i{pathName }@b{:icursor }@i{tagOrId index}
Set the position of the insertion cursor for the item(s)
given by @i{tagOrId}
to just before the character whose position is given by @i{index}.
If some or all of the items given by @i{tagOrId} don't support
an insertion cursor then this command has no effect on them.
See INDICES above for a description of the
legal forms for @i{index}.
Note:  the insertion cursor is only displayed in an item if
that item currently has the keyboard focus (see the widget
command @b{focus}, below), but the cursor position may
be set even when the item doesn't have the focus.
This command returns an empty string.
@item @i{pathName }@b{:index }@i{tagOrId index}
This command returns a decimal string giving the numerical index
within @i{tagOrId}@r{ corresponding to }@i{index}.
@i{Index} gives a textual description of the desired position
as described in INDICES above.
The return value is guaranteed to lie between 0 and the number
of characters within the item, inclusive.
If @i{tagOrId} refers to multiple items, then the index
is processed in the first of these items that supports indexing
operations (in display list order).
@item @i{pathName }@b{:insert }@i{tagOrId beforeThis string}
For each of the items given by @i{tagOrId}, if the item supports
text insertion then @i{string} is inserted into the item's
text just before the character whose index is @i{beforeThis}.
See INDICES above for information about the forms allowed
for @i{beforeThis}.
This command returns an empty string.
@item @i{pathName }@b{:itemconfigure }@i{tagOrId}@r{ ?}@i{option}@r{? ?}@i{value}@r{? ?}@i{option value ...}?
This command is similar to the @b{configure} widget command except
that it modifies item-specific options for the items given by
@i{tagOrId} instead of modifying options for the overall
canvas widget.
If no @i{option} is specified, returns a list describing all of
the available options for the first item given by @i{tagOrId}
(see @b{Tk_ConfigureInfo} for
information on the format of this list).  If @i{option} is specified
with no @i{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 @i{option} is specified).  If
one or more @i{option:value} pairs are specified, then the command
modifies the given widget option(s) to have the given value(s) in
each of the items given by @i{tagOrId};  in
this case the command returns an empty string.
The @i{option}@r{s and }@i{value}s are the same as those permissible
in the @b{create} widget command when the item(s) were created;
see the sections describing individual item types below for details
on the legal options.
@item @i{pathName }@b{:lower }@i{tagOrId }@r{?}@i{belowThis}?
Move all of the items given by @i{tagOrId} to a new position
in the display list just before the item given by @i{belowThis}.
If @i{tagOrId} refers to more than one item then all are moved
but the relative order of the moved items will not be changed.
@i{BelowThis} is a tag or id;  if it refers to more than one
item then the first (lowest) of these items in the display list is used
as the destination location for the moved items.
This command returns an empty string.
@item @i{pathName }@b{:move }@i{tagOrId xAmount yAmount}
Move each of the items given by @i{tagOrId} in the canvas coordinate
space by adding @i{xAmount} to the x-coordinate of each point
associated with the item and @i{yAmount} to the y-coordinate of
each point associated with the item.
This command returns an empty string.
@item @i{pathName }@b{:postscript }@r{?}@i{option value option value ...}?
Generate a Postscript representation for part or all of the canvas.
If the @b{:file} option is specified then the Postscript is written
to a file and an empty string is returned;  otherwise the Postscript
is returned as the result of the command.
The Postscript is created in Encapsulated Postscript form using
version 3.0 of the Document Structuring Conventions.
The @i{option}\-@i{value} argument pairs provide additional
information to control the generation of Postscript.  The following
options are supported:

@table @asis
@item @b{:colormap }@i{varName}
@i{VarName} must be the name of a global array variable
that specifies a color mapping to use in the Postscript.
Each element of @i{varName} must consist of Postscript
code to set a particular color value (e.g. ``@b{1.0 1.0 0.0 setrgbcolor}'').
When outputting color information in the Postscript, Tk checks
to see if there is an element of @i{varName} with the same
name as the color.
If so, Tk uses the value of the element as the Postscript command
to set the color.
If this option hasn't been specified, or if there isn't an entry
in @i{varName} for a given color, then Tk uses the red, green,
and blue intensities from the X color.
@item @b{:colormode }@i{mode}
Specifies how to output color information.  @i{Mode} must be either
@b{color}@r{ (for full color output), }@b{gray} (convert all colors
to their gray-scale equivalents) or @b{mono} (convert all colors
to black or white).
@item @b{:file }@i{fileName}
Specifies the name of the file in which to write the Postscript.
If this option isn't specified then the Postscript is returned as the
result of the command instead of being written to a file.
@item @b{:fontmap }@i{varName}
@i{VarName} must be the name of a global array variable
that specifies a font mapping to use in the Postscript.
Each element of @i{varName} must consist of a Tcl list with
two elements, which are the name and point size of a Postscript font.
When outputting Postscript commands for a particular font, Tk
checks to see if @i{varName} contains an element with the same
name as the font.
If there is such an element, then the font information contained in
that element is used in the Postscript.
Otherwise Tk attempts to guess what Postscript font to use.
Tk's guesses generally only work for well-known fonts such as
Times and Helvetica and Courier, and only if the X font name does not
omit any dashes up through the point size.
For example, \fB\-*\-Courier\-Bold\-R\-Normal\-\-*\-120\-* will work but
\fB*Courier\-Bold\-R\-Normal*120* will not;  Tk needs the dashes to
parse the font name).
@item @b{:height }@i{size}
Specifies the height of the area of the canvas to print.
Defaults to the height of the canvas window.
@item @b{:pageanchor }@i{anchor}
Specifies which point of the printed area should be appear over
the positioning point on the page (which is given by the @b{:pagex}
and @b{:pagey} options).
For example, @b{:pageanchor n} means that the top center of the
printed area should be over the positioning point.
Defaults to @b{center}.
@item @b{:pageheight }@i{size}
Specifies that the Postscript should be scaled in both x and y so
that the printed area is @i{size} high on the Postscript page.
@i{Size} consists of a floating-point number followed by
@b{c}@r{ for centimeters, }@b{i}@r{ for inches, }@b{m} for millimeters,
or @b{p} or nothing for printer's points (1/72 inch).
Defaults to the height of the printed area on the screen.
If both @b{:pageheight}@r{ and }@b{:pagewidth} are specified then
the scale factor from the later option is used (non-uniform scaling
is not implemented).
@item @b{:pagewidth }@i{size}
Specifies that the Postscript should be scaled in both x and y so
that the printed area is @i{size} wide on the Postscript page.
@i{Size}@r{ has the same form as for }@b{:pageheight}.
Defaults to the width of the printed area on the screen.
If both @b{:pageheight}@r{ and }@b{:pagewidth} are specified then
the scale factor from the later option is used (non-uniform scaling
is not implemented).
@item @b{:pagex }@i{position}
@i{Position} gives the x-coordinate of the positioning point on
the Postscript page, using any of the forms allowed for @b{:pageheight}.
Used in conjunction with the @b{:pagey}@r{ and }@b{:pageanchor} options
to determine where the printed area appears on the Postscript page.
Defaults to the center of the page.
@item @b{:pagey }@i{position}
@i{Position} gives the y-coordinate of the positioning point on
the Postscript page, using any of the forms allowed for @b{:pageheight}.
Used in conjunction with the @b{:pagex}@r{ and }@b{:pageanchor} options
to determine where the printed area appears on the Postscript page.
Defaults to the center of the page.
@item @b{:rotate }@i{boolean}
@i{Boolean} specifies whether the printed area is to be rotated 90
degrees.
In non-rotated output the x-axis of the printed area runs along
the short dimension of the page (``portrait'' orientation);
in rotated output the x-axis runs along the long dimension of the
page (``landscape'' orientation).
Defaults to non-rotated.
@item @b{:width }@i{size}
Specifies the width of the area of the canvas to print.
Defaults to the width of the canvas window.
@item @b{:x }@i{position}
Specifies the x-coordinate of the left edge of the area of the
canvas that is to be printed, in canvas coordinates, not window
coordinates.
Defaults to the coordinate of the left edge of the window.
@item @b{:y }@i{position}
Specifies the y-coordinate of the top edge of the area of the
canvas that is to be printed, in canvas coordinates, not window
coordinates.
Defaults to the coordinate of the top edge of the window.
@end table

@item @i{pathName }@b{:raise }@i{tagOrId }@r{?}@i{aboveThis}?
Move all of the items given by @i{tagOrId} to a new position
in the display list just after the item given by @i{aboveThis}.
If @i{tagOrId} refers to more than one item then all are moved
but the relative order of the moved items will not be changed.
@i{AboveThis} is a tag or id;  if it refers to more than one
item then the last (topmost) of these items in the display list is used
as the destination location for the moved items.
This command returns an empty string.
@item @i{pathName }@b{:scale }@i{tagOrId xOrigin yOrigin xScale yScale}
Rescale all of the items given by @i{tagOrId} in canvas coordinate
space.
@i{XOrigin}@r{ and }@i{yOrigin} identify the origin for the scaling
operation and @i{xScale}@r{ and }@i{yScale} identify the scale
factors for x- and y-coordinates, respectively (a scale factor of
1.0 implies no change to that coordinate).
For each of the points defining each item, the x-coordinate is
adjusted to change the distance from @i{xOrigin} by a factor
of @i{xScale}.
Similarly, each y-coordinate is adjusted to change the distance
from @i{yOrigin}@r{ by a factor of }@i{yScale}.
This command returns an empty string.
@item @i{pathName }@b{:scan}@r{ }@i{option args}
This command is used to implement scanning on canvases.  It has
two forms, depending on @i{option}:

@table @asis
@item @i{pathName }@b{:scan :mark }@i{x y}
Records @i{x}@r{ and }@i{y} and the canvas's current view;  used
in conjunction with later @b{scan dragto} commands.
Typically this command is associated with a mouse button press in
the widget and @i{x}@r{ and }@i{y} are the coordinates of the
mouse.  It returns an empty string.
@item @i{pathName }@b{:scan :dragto }@i{x y}.
This command computes the difference between its @i{x}@r{ and }@i{y}
arguments (which are typically mouse coordinates) and the @i{x} and
@i{y}@r{ arguments to the last }@b{scan mark} command for the widget.
It then adjusts the view by 10 times the
difference in coordinates.  This command is typically associated
with mouse motion events in the widget, to produce the effect of
dragging the canvas at high speed through its window.  The return
value is an empty string.
@end table

@item @i{pathName }@b{:select }@i{option}@r{ ?}@i{tagOrId arg}?
Manipulates the selection in one of several ways, depending on
@i{option}.
The command may take any of the forms described below.
In all of the descriptions below, @i{tagOrId} must refer to
an item that supports indexing and selection;  if it refers to
multiple items then the first of
these that supports indexing and the selection is used.
@i{Index} gives a textual description of a position
within @i{tagOrId}, as described in INDICES above.

@table @asis
@item @i{pathName }@b{:select :adjust }@i{tagOrId index}
Locate the end of the selection in @i{tagOrId} nearest
to the character given by @i{index}, and adjust that
end of the selection to be at @i{index} (i.e. including
but not going beyond @i{index}).
The other end of the selection is made the anchor point
for future @b{select to} commands.
If the selection isn't currently in @i{tagOrId} then
this command behaves the same as the @b{select to} widget
command.
Returns an empty string.
@item @i{pathName }@b{:select :clear}
Clear the selection if it is in this widget.
If the selection isn't in this widget then the command
has no effect.
Returns an empty string.
@item @i{pathName }@b{:select :from }@i{tagOrId index}
Set the selection anchor point for the widget to be just
before the character
given by @i{index}@r{ in the item given by }@i{tagOrId}.
This command doesn't change the selection;  it just sets
the fixed end of the selection for future @b{select to}
commands.
Returns an empty string.
@item @i{pathName }@b{:select :item}
Returns the id of the selected item, if the selection is in an
item in this canvas.
If the selection is not in this canvas then an empty string
is returned.
@item @i{pathName }@b{:select :to }@i{tagOrId index}
Set the selection to consist of those characters of @i{tagOrId}
between the selection anchor point and
@i{index}.
The new selection will include the character given by @i{index};
it will include the character given by the anchor point only if
@i{index} is greater than or equal to the anchor point.
The anchor point is determined by the most recent @b{select adjust}
or @b{select from} command for this widget.
If the selection anchor point for the widget isn't currently in
@i{tagOrId}, then it is set to the same character given
by @i{index}.
Returns an empty string.
@end table

@item @i{pathName }@b{:type}@i{ tagOrId}
Returns the type of the item given by @i{tagOrId}, such as
@b{rectangle}@r{ or }@b{text}.
If @i{tagOrId} refers to more than one item, then the type
of the first item in the display list is returned.
If @i{tagOrId} doesn't refer to any items at all then
an empty string is returned.
@item @i{pathName }@b{:xview}@i{ index}
Change the view in the canvas so that the canvas position given by
@i{index} appears at the left edge of the window.
This command is typically used by scrollbars to scroll the
canvas.
@i{Index} counts in units of scroll increments (the value of the
@b{scrollIncrement} option):  a value of 0 corresponds to the left
edge of the scroll region (as defined by the @b{scrollRegion}
option),  a value of 1 means one scroll unit to the right of this,
and so on.  The return value is an empty string.
@item @i{pathName }@b{:yview}@i{ index}
Change the view in the canvas so that the canvas position given by
@i{index} appears at the top edge of the window.
This command is typically used by scrollbars to scroll the
canvas.
@i{Index} counts in units of scroll increments (the value of the
@b{scrollIncrement} option):  a value of 0 corresponds to the top
edge of the scroll region (as defined by the @b{scrollRegion}
option),  a value of 1 means one scroll unit below this,
and so on.  The return value is an empty string.

@end table
@unnumberedsubsec Overview Of Item Types

The sections below describe the various types of items supported
by canvas widgets.  Each item type is characterized by two things:
first, the form of the @b{create} command used to create
instances of the type;  and second, a set of configuration options
for items of that type, which may be used in the
@b{create}@r{ and }@b{itemconfigure} widget commands.
Most items don't support indexing or selection or the commands
related to them, such as @b{index}@r{ and }@b{insert}.
Where items do support these facilities, it is noted explicitly
in the descriptions below (at present, only text items provide
this support).

@unnumberedsubsec Arc Items

Items of type @b{arc} appear on the display as arc-shaped regions.
An arc is a section of an oval delimited by two angles (specified
by the @b{:start}@r{ and }@b{:extent} options) and displayed in
one of several ways (specified by the @b{:style} option).
Arcs are created with widget commands of the following form:

@table @asis
@item @i{pathName }@b{:create arc }@i{x1 y1 x2 y2 }@r{?}@i{option value option value ...}?
The arguments @i{x1}@r{, }@i{y1}@r{, }@i{x2}@r{, and }@i{y2} give
the coordinates of two diagonally opposite corners of a
rectangular region enclosing the oval that defines the arc.
After the coordinates there may be any number of @i{option}@r{-}@i{value}
pairs, each of which sets one of the configuration options
for the item.  These same @i{option}\-@i{value} pairs may be
used in @b{itemconfigure} widget commands to change the item's
configuration.
The following options are supported for arcs:

@table @asis
@item @b{:extent }@i{degrees}
Specifies the size of the angular range occupied by the arc.
The arc's range extends for @i{degrees} degrees counter-clockwise
from the starting angle given by the @b{:start} option.
@i{Degrees} may be negative.
@item @b{:fill }@i{color}
Fill the region of the arc with @i{color}.
@i{Color}@r{ may have any of the forms accepted by }@b{Tk_GetColor}.
If @i{color} is an empty string (the default), then
then the arc will not be filled.
@item @b{:outline }@i{color}
@i{Color} specifies a color to use for drawing the arc's
outline;  it may have any of the forms accepted by @b{Tk_GetColor}.
This option defaults to @b{black}.  If the arc's style is
@b{arc} then this option is ignored (the section of perimeter is
filled using the @b{:fill}@r{ option).  If }@i{color} is specified
as an empty string then no outline is drawn for the arc.
@item @b{:start }@i{degrees}
Specifies the beginning of the angular range occupied by the
arc.
@i{Degrees} is given in units of degrees measured counter-clockwise
from the 3-o'clock position;  it may be either positive or negative.
@item @b{:stipple }@i{bitmap}
Indicates that the arc should be filled in a stipple pattern;
@i{bitmap} specifies the stipple pattern to use, in any of the
forms accepted by @b{Tk_GetBitmap}.
If the @b{:fill} option hasn't been specified then this option
has no effect.
If @i{bitmap} is an empty string (the default), then filling is done
in a solid fashion.
@item @b{:style }@i{type}
Specifies how to draw the arc.  If @i{type}@r{ is }@b{pieslice}
(the default) then the arc's region is defined by a section
of the oval's perimeter plus two line segments, one between the center
of the oval and each end of the perimeter section.
If @i{type}@r{ is }@b{chord} then the arc's region is defined
by a section of the oval's perimeter plus a single line segment
connecting the two end points of the perimeter section.
If @i{type}@r{ is }@b{arc} then the arc's region consists of
a section of the perimeter alone.  In this last case there is
no outline for the arc and the @b{:outline} option is ignored.
@item @b{:tags }@i{tagList}
Specifies a set of tags to apply to the item.
@i{TagList} consists of a list of tag names, which replace any
existing tags for the item.
@i{TagList} may be an empty list.
@item @b{:width }@i{outlineWidth}
Specifies the width of the outline to be drawn around
the arc's region, in any of the forms described in the COORDINATES
section above.
If the @b{:outline} option has been specified as an empty string
then this option has no effect.
Wide outlines will be drawn centered on the edges of the arc's region.
This option defaults to 1.0.
@end table
@end table

@unnumberedsubsec Bitmap Items

Items of type @b{bitmap} appear on the display as images with
two colors, foreground and background.
Bitmaps are created with widget commands of the following form:

@table @asis
@item @i{pathName }@b{:create bitmap }@i{x y }@r{?}@i{option value option value ...}?
The arguments @i{x}@r{ and }@i{y} specify the coordinates of a
point used to position the bitmap on the display (see the @b{:anchor}
option below for more information on how bitmaps are displayed).
After the coordinates there may be any number of @i{option}@r{-}@i{value}
pairs, each of which sets one of the configuration options
for the item.  These same @i{option}\-@i{value} pairs may be
used in @b{itemconfigure} widget commands to change the item's
configuration.
The following options are supported for bitmaps:

@table @asis
@item @b{:anchor }@i{anchorPos}
@i{AnchorPos} tells how to position the bitmap relative to the
positioning point for the item;  it may have any of the forms
accepted by @b{Tk_GetAnchor}@r{.  For example, if }@i{anchorPos}
is @b{center} then the bitmap is centered on the point;  if
@i{anchorPos}@r{ is }@b{n} then the bitmap will be drawn so that
its top center point is at the positioning point.
This option defaults to @b{center}.
@item @b{:background }@i{color}
Specifies a color to use for each of the bitmap pixels
whose value is 0.
@i{Color}@r{ may have any of the forms accepted by }@b{Tk_GetColor}.
If this option isn't specified, or if it is specified as an empty
string, then the background color for the canvas is used.
@item @b{:bitmap }@i{bitmap}
Specifies the bitmap to display in the item.
@i{Bitmap}@r{ may have any of the forms accepted by }@b{Tk_GetBitmap}.
@item @b{:foreground }@i{color}
Specifies a color to use for each of the bitmap pixels
whose value is 1.
@i{Color}@r{ may have any of the forms accepted by }@b{Tk_GetColor} and
defaults to @b{black}.
@item @b{:tags }@i{tagList}
Specifies a set of tags to apply to the item.
@i{TagList} consists of a list of tag names, which replace any
existing tags for the item.
@i{TagList} may be an empty list.
@end table
@end table
@unnumberedsubsec Line Items

Items of type @b{line} appear on the display as one or more connected
line segments or curves.
Lines are created with widget commands of the following form:

@table @asis
@item @i{pathName }@b{:create line }@i{x1 y1... xn yn }@r{?}@i{option value option value ...}?

The arguments @i{x1}@r{ through }@i{yn} give
the coordinates for a series of two or more points that describe
a series of connected line segments.
After the coordinates there may be any number of @i{option}@r{-}@i{value}
pairs, each of which sets one of the configuration options
for the item.  These same @i{option}\-@i{value} pairs may be
used in @b{itemconfigure} widget commands to change the item's
configuration.
The following options are supported for lines:

@table @asis
@item @b{:arrow }@i{where}
Indicates whether or not arrowheads are to be drawn at one or both
ends of the line.
@i{Where}@r{ must have one of the values }@b{none} (for no arrowheads),
@b{first} (for an arrowhead at the first point of the line),
@b{last} (for an arrowhead at the last point of the line), or
@b{both} (for arrowheads at both ends).
This option defaults to @b{none}.
@item @b{:arrowshape }@i{shape}
This option indicates how to draw arrowheads.
The @i{shape} argument must be a list with three elements, each
specifying a distance in any of the forms described in
the COORDINATES section above.
The first element of the list gives the distance along the line
from the neck of the arrowhead to its tip.
The second element gives the distance along the line from the
trailing points of the arrowhead to the tip, and the third
element gives the distance from the outside edge of the line to the
trailing points.
If this option isn't specified then Tk picks a ``reasonable'' shape.
@item @b{:capstyle }@i{style}
Specifies the ways in which caps are to be drawn at the endpoints
of the line.
@i{Style}@r{ may have any of the forms accepted by }@b{Tk_GetCapStyle}
(@b{butt}@r{, }@b{projecting}@r{, or }@b{round}).
If this option isn't specified then it defaults to @b{butt}.
Where arrowheads are drawn the cap style is ignored.
@item @b{:fill }@i{color}
@i{Color} specifies a color to use for drawing the line; it may have
any of the forms acceptable to @b{Tk_GetColor}.  It may also be an
empty string, in which case the line will be transparent.
This option defaults to @b{black}.
@item @b{:joinstyle }@i{style}
Specifies the ways in which joints are to be drawn at the vertices
of the line.
@i{Style}@r{ may have any of the forms accepted by }@b{Tk_GetCapStyle}
(@b{bevel}@r{, }@b{miter}@r{, or }@b{round}).
If this option isn't specified then it defaults to @b{miter}.
If the line only contains two points then this option is
irrelevant.
@item @b{:smooth }@i{boolean}
@i{Boolean}@r{ must have one of the forms accepted by }@b{Tk_GetBoolean}.
It indicates whether or not the line should be drawn as a curve.
If so, the line is rendered as a set of Bezier splines: one spline
is drawn for the first and second line segments, one for the second
and third, and so on.  Straight-line segments can be generated within
a curve by duplicating the end-points of the desired line segment.
@item @b{:splinesteps }@i{number}
Specifies the degree of smoothness desired for curves:  each spline
will be approximated with @i{number} line segments.  This
option is ignored unless the @b{:smooth} option is true.
@item @b{:stipple }@i{bitmap}
Indicates that the line should be filled in a stipple pattern;
@i{bitmap} specifies the stipple pattern to use, in any of the
forms accepted by @b{Tk_GetBitmap}.
If @i{bitmap} is an empty string (the default), then filling is
done in a solid fashion.
@item @b{:tags }@i{tagList}
Specifies a set of tags to apply to the item.
@i{TagList} consists of a list of tag names, which replace any
existing tags for the item.
@i{TagList} may be an empty list.
@item @b{:width }@i{lineWidth}
@i{LineWidth} specifies the width of the line, in any of the forms
described in the COORDINATES section above.
Wide lines will be drawn centered on the path specified by the
points.
If this option isn't specified then it defaults to 1.0.
@end table
@end table
@unnumberedsubsec Oval Items

Items of type @b{oval} appear as circular or oval regions on
the display.  Each oval may have an outline, a fill, or
both.  Ovals are created with widget commands of the
following form:

@table @asis
@item @i{pathName }@b{:create oval }@i{x1 y1 x2 y2 }@r{?}@i{option value option value ...}?

The arguments @i{x1}@r{, }@i{y1}@r{, }@i{x2}@r{, and }@i{y2} give
the coordinates of two diagonally opposite corners of a
rectangular region enclosing the oval.
The oval will include the top and left edges of the rectangle
not the lower or right edges.
If the region is square then the resulting oval is circular;
otherwise it is elongated in shape.
After the coordinates there may be any number of @i{option}@r{-}@i{value}
pairs, each of which sets one of the configuration options
for the item.  These same @i{option}\-@i{value} pairs may be
used in @b{itemconfigure} widget commands to change the item's
configuration.
The following options are supported for ovals:

@table @asis
@item @b{:fill }@i{color}
Fill the area of the oval with @i{color}.
@i{Color}@r{ may have any of the forms accepted by }@b{Tk_GetColor}.
If @i{color} is an empty string (the default), then
then the oval will not be filled.
@item @b{:outline }@i{color}
@i{Color} specifies a color to use for drawing the oval's
outline;  it may have any of the forms accepted by @b{Tk_GetColor}.
This option defaults to @b{black}.
If @i{color} is an empty string then no outline will be
drawn for the oval.
@item @b{:stipple }@i{bitmap}
Indicates that the oval should be filled in a stipple pattern;
@i{bitmap} specifies the stipple pattern to use, in any of the
forms accepted by @b{Tk_GetBitmap}.
If the @b{:fill} option hasn't been specified then this option
has no effect.
If @i{bitmap} is an empty string (the default), then filling is done
in a solid fashion.
@item @b{:tags }@i{tagList}
Specifies a set of tags to apply to the item.
@i{TagList} consists of a list of tag names, which replace any
existing tags for the item.
@i{TagList} may be an empty list.
@item @b{:width }@i{outlineWidth}
@i{outlineWidth} specifies the width of the outline to be drawn around
the oval, in any of the forms described in the COORDINATES section above.
If the @b{:outline} option hasn't been specified then this option
has no effect.
Wide outlines are drawn centered on the oval path defined by
@i{x1}@r{, }@i{y1}@r{, }@i{x2}@r{, and }@i{y2}.
This option defaults to 1.0.
@end table
@end table
@unnumberedsubsec Polygon Items

Items of type @b{polygon} appear as polygonal or curved filled regions
on the display.
Polygons are created with widget commands of the following form:

@table @asis
@item @i{pathName }@b{:create polygon }@i{x1 y1 ... xn yn }@r{?}@i{option value option value ...}?


The arguments @i{x1}@r{ through }@i{yn} specify the coordinates for
three or more points that define a closed polygon.
The first and last points may be the same;  whether they are or not,
Tk will draw the polygon as a closed polygon.
After the coordinates there may be any number of @i{option}@r{-}@i{value}
pairs, each of which sets one of the configuration options
for the item.  These same @i{option}\-@i{value} pairs may be
used in @b{itemconfigure} widget commands to change the item's
configuration.
The following options are supported for polygons:

@table @asis
@item @b{:fill }@i{color}
@i{Color} specifies a color to use for filling the area of the
polygon; it may have any of the forms acceptable to @b{Tk_GetColor}.
If @i{color} is an empty string then the polygon will be
transparent.
This option defaults to @b{black}.
@item @b{:smooth }@i{boolean}
@i{Boolean}@r{ must have one of the forms accepted by }@b{Tk_GetBoolean}
It indicates whether or not the polygon should be drawn with a
curved perimeter.
If so, the outline of the polygon becomes a set of Bezier splines,
one spline for the first and second line segments, one for the second
and third, and so on.  Straight-line segments can be generated in a
smoothed polygon by duplicating the end-points of the desired line segment.
@item @b{:splinesteps }@i{number}
Specifies the degree of smoothness desired for curves:  each spline
will be approximated with @i{number} line segments.  This
option is ignored unless the @b{:smooth} option is true.
@item @b{:stipple }@i{bitmap}
Indicates that the polygon should be filled in a stipple pattern;
@i{bitmap} specifies the stipple pattern to use, in any of the
forms accepted by @b{Tk_GetBitmap}.
If @i{bitmap} is an empty string (the default), then filling is
done in a solid fashion.
@item @b{:tags }@i{tagList}
Specifies a set of tags to apply to the item.
@i{TagList} consists of a list of tag names, which replace any
existing tags for the item.
@i{TagList} may be an empty list.
@end table
@end table

@unnumberedsubsec Rectangle Items

Items of type @b{rectangle} appear as rectangular regions on
the display.  Each rectangle may have an outline, a fill, or
both.  Rectangles are created with widget commands of the
following form:

@table @asis
@item @i{pathName }@b{:create rectangle }@i{x1 y1 x2 y2 }@r{?}@i{option value option value ...}?

The arguments @i{x1}@r{, }@i{y1}@r{, }@i{x2}@r{, and }@i{y2} give
the coordinates of two diagonally opposite corners of the rectangle
(the rectangle will include its upper and left edges but not
its lower or right edges).
After the coordinates there may be any number of @i{option}@r{-}@i{value}
pairs, each of which sets one of the configuration options
for the item.  These same @i{option}\-@i{value} pairs may be
used in @b{itemconfigure} widget commands to change the item's
configuration.
The following options are supported for rectangles:

@table @asis
@item @b{:fill }@i{color}
Fill the area of the rectangle with @i{color}, which may be
specified in any of the forms accepted by @b{Tk_GetColor}.
If @i{color} is an empty string (the default), then
then the rectangle will not be filled.
@item @b{:outline }@i{color}
Draw an outline around the edge of the rectangle in @i{color}.
@i{Color}@r{ may have any of the forms accepted by }@b{Tk_GetColor}.
This option defaults to @b{black}.
If @i{color} is an empty string then no outline will be
drawn for the rectangle.
@item @b{:stipple }@i{bitmap}
Indicates that the rectangle should be filled in a stipple pattern;
@i{bitmap} specifies the stipple pattern to use, in any of the
forms accepted by @b{Tk_GetBitmap}.
If the @b{:fill} option hasn't been specified then this option
has no effect.
If @i{bitmap} is an empty string (the default), then filling
is done in a solid fashion.
@item @b{:tags }@i{tagList}
Specifies a set of tags to apply to the item.
@i{TagList} consists of a list of tag names, which replace any
existing tags for the item.
@i{TagList} may be an empty list.
@item @b{:width }@i{outlineWidth}
@i{OutlineWidth} specifies the width of the outline to be drawn around
the rectangle, in any of the forms described in the COORDINATES section above.
If the @b{:outline} option hasn't been specified then this option
has no effect.
Wide outlines are drawn centered on the rectangular path
defined by @i{x1}@r{, }@i{y1}@r{, }@i{x2}@r{, and }@i{y2}.
This option defaults to 1.0.
@end table
@end table
@unnumberedsubsec Text Items

A text item displays a string of characters on the screen in one
or more lines.
Text items support indexing and selection, along with the
following text-related canvas widget commands:  @b{dchars},
@b{focus}@r{, }@b{icursor}@r{, }@b{index}@r{, }@b{insert},
@b{select}.
Text items are created with widget commands of the following
form:

@table @asis
@item @i{pathName }@b{:create text }@i{x y }@r{?}@i{option value option value ...}?

The arguments @i{x}@r{ and }@i{y} specify the coordinates of a
point used to position the text on the display (see the options
below for more information on how text is displayed).
After the coordinates there may be any number of @i{option}@r{-}@i{value}
pairs, each of which sets one of the configuration options
for the item.  These same @i{option}\-@i{value} pairs may be
used in @b{itemconfigure} widget commands to change the item's
configuration.
The following options are supported for text items:

@table @asis
@item @b{:anchor }@i{anchorPos}
@i{AnchorPos} tells how to position the text relative to the
positioning point for the text;  it may have any of the forms
accepted by @b{Tk_GetAnchor}@r{.  For example, if }@i{anchorPos}
is @b{center} then the text is centered on the point;  if
@i{anchorPos}@r{ is }@b{n} then the text will be drawn such that
the top center point of the rectangular region occupied by the
text will be at the positioning point.
This option defaults to @b{center}.
@item @b{:fill }@i{color}
@i{Color} specifies a color to use for filling the text characters;
it may have any of the forms accepted by @b{Tk_GetColor}.
If this option isn't specified then it defaults to @b{black}.
@item @b{:font }@i{fontName}
Specifies the font to use for the text item.
@i{FontName}@r{ may be any string acceptable to }@b{Tk_GetFontStruct}.
If this option isn't specified, it defaults to a system-dependent
font.
@item @b{:justify }@i{how}
Specifies how to justify the text within its bounding region.
@i{How}@r{ must be one of the values }@b{left}@r{, }@b{right},
or @b{center}.
This option will only matter if the text is displayed as multiple
lines.
If the option is omitted, it defaults to @b{left}.
@item @b{:stipple }@i{bitmap}
Indicates that the text should be drawn in a stippled pattern
rather than solid;
@i{bitmap} specifies the stipple pattern to use, in any of the
forms accepted by @b{Tk_GetBitmap}.
If @i{bitmap} is an empty string (the default) then the text
is drawn in a solid fashion.
@item @b{:tags }@i{tagList}
Specifies a set of tags to apply to the item.
@i{TagList} consists of a list of tag names, which replace any
existing tags for the item.
@i{TagList} may be an empty list.
@item @b{:text }@i{string}
@i{String} specifies the characters to be displayed in the text item.
Newline characters cause line breaks.
The characters in the item may also be changed with the
@b{insert}@r{ and }@b{delete} widget commands.
This option defaults to an empty string.
@item @b{:width }@i{lineLength}
Specifies a maximum line length for the text, in any of the forms
described in the COORDINATES section abov.
If this option is zero (the default) the text is broken into
lines only at newline characters.
However, if this option is non-zero then any line that would
be longer than @i{lineLength} is broken just before a space
character to make the line shorter than @i{lineLength};  the
space character is treated as if it were a newline
character.

@end table
@end table
@unnumberedsubsec Window Items

Items of type @b{window} cause a particular window to be displayed
at a given position on the canvas.
Window items are created with widget commands of the following form:

@example
@i{pathName }@b{:create window }@i{x y }@r{?}@i{option value option value ...}?
@end example

The arguments @i{x}@r{ and }@i{y} specify the coordinates of a
point used to position the window on the display (see the @b{:anchor}
option below for more information on how bitmaps are displayed).
After the coordinates there may be any number of @i{option}@r{-}@i{value}
pairs, each of which sets one of the configuration options
for the item.  These same @i{option}\-@i{value} pairs may be
used in @b{itemconfigure} widget commands to change the item's
configuration.
The following options are supported for window items:

@table @asis
@item @b{:anchor }@i{anchorPos}
@i{AnchorPos} tells how to position the window relative to the
positioning point for the item;  it may have any of the forms
accepted by @b{Tk_GetAnchor}@r{.  For example, if }@i{anchorPos}
is @b{center} then the window is centered on the point;  if
@i{anchorPos}@r{ is }@b{n} then the window will be drawn so that
its top center point is at the positioning point.
This option defaults to @b{center}.
@item @b{:height }@i{pixels}
Specifies the height to assign to the item's window.
@i{Pixels} may have any of the
forms described in the COORDINATES section above.
If this option isn't specified, or if it is specified as an empty
string, then the window is given whatever height it requests internally.
@item @b{:tags }@i{tagList}
Specifies a set of tags to apply to the item.
@i{TagList} consists of a list of tag names, which replace any
existing tags for the item.
@i{TagList} may be an empty list.
@item @b{:width }@i{pixels}
Specifies the width to assign to the item's window.
@i{Pixels} may have any of the
forms described in the COORDINATES section above.
If this option isn't specified, or if it is specified as an empty
string, then the window is given whatever width it requests internally.
@item @b{:window }@i{pathName}
Specifies the window to associate with this item.
The window specified by @i{pathName} must either be a child of
the canvas widget or a child of some ancestor of the canvas widget.
@i{PathName} may not refer to a top-level window.

@end table
@unnumberedsubsec Application-Defined Item Types

It is possible for individual applications to define new item
types for canvas widgets using C code.
The interfaces for this mechanism are not presently documented,
and it's possible they may change, but you should be able to
see how they work by examining the code for some of the existing
item types.

@unnumberedsubsec Bindings

In the current implementation, new canvases are not given any
default behavior:  you'll have to execute explicit Tcl commands
to give the canvas its behavior.

@unnumberedsubsec Credits

Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's
@i{ezd}@r{ program.  }@i{Ezd} provides structured graphics in a Scheme
environment and preceded canvases by a year or two.  Its simple
mechanisms for placing and animating graphical objects inspired the
functions of canvases.

@unnumberedsubsec Keywords
canvas, widget
@node menu, scrollbar, canvas, Widgets
@section menu
@c @cartouche

menu \- Create and manipulate menu widgets
@unnumberedsubsec Synopsis
@b{menu}@i{ }@i{pathName }@r{?}@i{options}?
@unnumberedsubsec Standard Options


@example
activeBackground       background       disabledForeground      
activeBorderWidth      borderWidth      font                    
activeForeground       cursor           foreground              
@end example           


@xref{options}, for more information.
@unnumberedsubsec Arguments for Menu


@table @asis
@item @code{@b{:postcommand}}
@flushright
Name=@code{"@b{postCommand}@r{"} Class=@code{"}@b{Command}"}
@end flushright
@sp 1

If this option is specified then it provides a Tcl command to execute
each time the menu is posted.  The command is invoked by the @b{post}
widget command before posting the menu.
@end table


@table @asis
@item @code{@b{:selector}}
@flushright
Name=@code{"@b{selector}@r{"} Class=@code{"}@b{Foreground}"}
@end flushright
@sp 1

For menu entries that are check buttons or radio buttons, this option
specifies the color to display in the selector when the check button
or radio button is selected.
@end table
@c @end cartouche

@unnumberedsubsec Introduction

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

A menu is a widget that displays a collection of one-line entries arranged
in a column.  There exist several different types of entries,
each with different properties.  Entries of different types may be
combined in a single menu.  Menu entries are not the same as
entry widgets.  In fact, menu entries are not even distinct widgets;
the entire menu is one widget.

Menu entries are displayed with up to three
separate fields.  The main field is a label in the form of text or
a bitmap, which is determined by the @b{:label}@r{ or }@b{:bitmap}
option for the entry.
If the  @b{:accelerator} option is specified for an entry then a second
textual field is displayed to the right of the label.  The accelerator
typically describes a keystroke sequence that may be typed in the
application to cause the same result as invoking the menu entry.
The third field is a @i{selector}.  The selector is present only for
check-button or radio-button entries.  It indicates whether the entry
is selected or not, and is displayed to the left of the entry's
string.

In normal use, an entry becomes active (displays itself differently)
whenever the mouse pointer is over the entry.  If a mouse
button is released over the entry then the entry is @i{invoked}.
The effect of invocation is different for each type of entry;
these effects are described below in the sections on individual
entries.

Entries may be @i{disabled}, which causes their labels
and accelerators to be displayed
with dimmer colors.  A disabled entry cannot be activated or invoked.
Disabled entries may be re-enabled, at which point it becomes
possible to activate and invoke them again.

@unnumberedsubsec Command Entries

The most common kind of menu entry is a command entry, which
behaves much like a button widget.  When a command entry is
invoked, a Tcl command is executed.  The Tcl
command is specified with the @b{:command} option.

@unnumberedsubsec Separator Entries

A separator is an entry that is displayed as a horizontal dividing
line.  A separator may not be activated or invoked, and it has
no behavior other than its display appearance.

@unnumberedsubsec Check-Button Entries

A check-button menu entry behaves much like a check-button widget.
When it is invoked it toggles back and forth between the selected
and deselected states.  When the entry is selected, a particular
value is stored in a particular global variable (as determined by
the @b{:onvalue}@r{ and }@b{:variable} options for the entry);  when
the entry is deselected another value (determined by the
@b{:offvalue} option) is stored in the global variable.
A selector box is displayed to the left of the label in a check-button
entry.  If the entry is selected then the box's center is displayed
in the color given by the @b{selector} option for the menu;
otherwise the box's center is displayed in the background color for
the menu.  If a @b{:command} option is specified for a check-button
entry, then its value is evaluated as a Tcl command each time the entry
is invoked;  this happens after toggling the entry's
selected state.

@unnumberedsubsec Radio-Button Entries

A radio-button menu entry behaves much like a radio-button widget.
Radio-button entries are organized in groups of which only one
entry may be selected at a time.  Whenever a particular entry
becomes selected it stores a particular value into a particular
global variable (as determined by the @b{:value} and
@b{:variable} options for the entry).  This action
causes any previously-selected entry in the same group
to deselect itself.
Once an entry has become selected, any change to the entry's
associated variable will cause the entry to deselect itself.
Grouping of radio-button entries is determined by their
associated variables:  if two entries have the same associated
variable then they are in the same group.
A selector diamond is displayed to the left of the label in each
radio-button entry.  If the entry is selected then the diamond's
center is displayed in the color given by the @b{selector} option
for the menu;
otherwise the diamond's center is displayed in the background color for
the menu.  If a @b{:command} option is specified for a radio-button
entry, then its value is evaluated as a Tcl command each time the entry
is invoked;  this happens after selecting the entry.

@unnumberedsubsec Cascade Entries

A cascade entry is one with an associated menu (determined
by the @b{:menu} option).  Cascade entries allow the construction
of cascading menus.  When the entry is activated, the
associated menu is posted just to the right of the entry;
that menu remains posted until the higher-level menu is unposted or
until some other entry is activated in the higher-level menu.
The associated menu should normally be a child of the menu containing
the cascade entry, in order for menu traversal to work correctly.

A cascade entry posts its associated menu by invoking a
Tcl command of the form

@table @asis
@item @i{menu}@b{ :post }@i{x y}



where @i{menu}@r{ is the path name of the associated menu, }@i{x}
and @i{y} are the root-window coordinates of the upper-right
corner of the cascade entry, and @i{group} is the name of the
menu's group (as determined in its last @b{post} widget command).
The lower-level menu is unposted by executing a Tcl command with
the form

@item @i{menu}@b{:unpost}
where @i{menu} is the name of the associated menu.
@end table

If a @b{:command} option is specified for a cascade entry then it is
evaluated as a Tcl command each time the associated menu is posted (the
evaluation occurs before the menu is posted).

@unnumberedsubsec A Menu Widget's Arguments

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

@table @asis
@item @i{pathName option }@r{?}@i{arg arg ...}?
@i{Option}@r{ and the }@i{arg}s
determine the exact behavior of the command.
@end table

Many of the widget commands for a menu take as one argument an
indicator of which entry of the menu to operate on.  These
indicators are called @i{index}es and may be specified in
any of the following forms:

@table @asis
@item @i{number}
Specifies the entry numerically, where 0 corresponds
to the top-most entry of the menu, 1 to the entry below it, and
so on.
@item @b{active}
Indicates the entry that is currently active.  If no entry is
active then this form is equivalent to @b{none}.  This form may
not be abbreviated.
@item @b{last}
Indicates the bottommost entry in the menu.  If there are no
entries in the menu then this form is equivalent to @b{none}.
This form may not be abbreviated.
@item @b{none}
Indicates ``no entry at all'';  this is used most commonly with
the @b{activate} option to deactivate all the entries in the
menu.  In most cases the specification of @b{none} causes
nothing to happen in the widget command.
This form may not be abbreviated.
@item @b{@@}@i{number}
In this form, @i{number} is treated as a y-coordinate in the
menu's window;  the entry spanning that y-coordinate is used.
For example, ``@b{@@0}'' indicates the top-most entry in the
window.  If @i{number} is outside the range of the window
then this form is equivalent to @b{none}.
@item @i{pattern}
If the index doesn't satisfy one of the above forms then this
form is used.  @i{Pattern} is pattern-matched against the label of
each entry in the menu, in order from the top down, until a
matching entry is found.  The rules of @b{Tcl_StringMatch}
are used.

The following widget commands are possible for menu widgets:
@item @i{pathName }@b{:activate }@i{index}
Change the state of the entry indicated by @i{index}@r{ to }@b{active}
and redisplay it using its active colors.
Any previously-active entry is deactivated.  If @i{index}
is specified as @b{none}, or if the specified entry is
disabled, then the menu ends up with no active entry.
Returns an empty string.
@item @i{pathName }@b{:add }@i{type }@r{?}@i{option value option value ...}?
Add a new entry to the bottom of the menu.  The new entry's type
is given by @i{type}@r{ and must be one of }@b{cascade},
@b{checkbutton}@r{, }@b{command}@r{, }@b{radiobutton}@r{, or }@b{separator},
or a unique abbreviation of one of the above.  If additional arguments
are present, they specify any of the following options:

@table @asis
@item @b{:activebackground }@i{value}
Specifies a background color to use for displaying this entry when it
is active.
If this option is specified as an empty string (the default), then the
@b{activeBackground} option for the overall menu is used.
This option is not available for separator entries.
@item @b{:accelerator }@i{value}
Specifies a string to display at the right side of the menu entry.
Normally describes an accelerator keystroke sequence that may be
typed to invoke the same function as the menu entry.  This option
is not available for separator entries.
@item @b{:background }@i{value}
Specifies a background color to use for displaying this entry when it
is in the normal state (neither active nor disabled).
If this option is specified as an empty string (the default), then the
@b{background} option for the overall menu is used.
This option is not available for separator entries.
@item @b{:bitmap }@i{value}
Specifies a bitmap to display in the menu instead of a textual
label, in any of the forms accepted by @b{Tk_GetBitmap}.
This option overrides the @b{:label} option but may be reset
to an empty string to enable a textual label to be displayed.
This option is not available for separator entries.
@item @b{:command }@i{value}
For command, checkbutton, and radiobutton entries, specifies a
Tcl command to execute when the menu entry is invoked.
For cascade entries, specifies a Tcl command to execute
when the entry is activated (i.e. just before its submenu is
posted).
Not available for separator entries.
@item @b{:font }@i{value}
Specifies the font to use when drawing the label or accelerator
string in this entry.
If this option is specified as an empty string (the default) then
the @b{font} option for the overall menu is used.
This option is not available for separator entries.
@item @b{:label }@i{value}
Specifies a string to display as an identifying label in the menu
entry.  Not available for separator entries.
@item @b{:menu }@i{value}
Available only for cascade entries.  Specifies the path name of
the menu associated with this entry.
@item @b{:offvalue }@i{value}
Available only for check-button entries.  Specifies the value to
store in the entry's associated variable when the entry is
deselected.
@item @b{:onvalue }@i{value}
Available only for check-button entries.  Specifies the value to
store in the entry's associated variable when the entry is selected.
@item @b{:state }@i{value}
Specifies one of three states for the entry:  @b{normal}@r{, }@b{active},
or @b{disabled}.  In normal state the entry is displayed using the
@b{foreground}@r{ option for the menu and the }@b{background}
option from the entry or the menu.
The active state is typically used when the pointer is over the entry.
In active state the entry is displayed using the @b{activeForeground}
option for the menu along with the @b{activebackground} option from
the entry.
Disabled state means that the entry is insensitive:  it doesn't activate
and doesn't respond to mouse button presses or releases.
In this state the entry is displayed according to the 
@b{disabledForeground} option for the menu and the
@b{background} option from the entry.
This option is not available for separator entries.
@item @b{:underline }@i{value}
Specifies the integer index of a character to underline in the entry.
This option is typically used to indicate keyboard traversal characters.
0 corresponds to the first character of the text displayed in the entry,
1 to the next character, and so on.
If a bitmap is displayed in the entry then this option is ignored.
This option is not available for separator entries.
@item @b{:value }@i{value}
Available only for radio-button entries.  Specifies the value to
store in the entry's associated variable when the entry is selected.
@item @b{:variable }@i{value}
Available only for check-button and radio-button entries.  Specifies
the name of a global value to set when the entry is selected.
For check-button entries the variable is also set when the entry
is deselected.  For radio-button entries, changing the variable
causes the currently-selected entry to deselect itself.
@end table
@end table

The @b{add} widget command returns an empty string.


@table @asis
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
Query or modify the configuration options of the widget.
If no @i{option} is specified, returns a list describing all of
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
information on the format of this list).  If @i{option} is specified
with no @i{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 @i{option} is specified).  If
one or more @i{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.
@i{Option}@r{ may have any of the values accepted by the }@b{menu}
command.
@item @i{pathName }@b{:delete }@i{index1}@r{ ?}@i{index2}?
Delete all of the menu entries between @i{index1} and
@i{index2} inclusive.
If @i{index2}@r{ is omitted then it defaults to }@i{index1}.
Returns an empty string.
@item @i{pathName }@b{:disable }@i{index}
Change the state of the entry given by @i{index}@r{ to }@b{disabled}
and redisplay the entry using its disabled colors.
Returns an empty string.
This command is obsolete and will eventually be removed;
use ``@i{pathName }@b{:entryconfigure }@i{index}@r{ :state disabled}'' instead.
@item @i{pathName }@b{:enable }@i{index}
Change the state of the entry given by @i{index}@r{ to }@b{normal}
and redisplay the entry using its normal colors.
Returns an empty string.
This command is obsolete and will eventually be removed;
use ``@i{pathName }@b{:entryconfigure }@i{index}@r{ :state normal}'' instead.
@item @i{pathName }@b{:entryconfigure }@i{index}@r{ }@r{?}@i{options}?
This command is similar to the @b{configure} command, except that
it applies to the options for an individual entry, whereas @b{configure}
applies to the options for the menu as a whole.
@i{Options}@r{ may have any of the values accepted by the }@b{add}
widget command.  If @i{options} are specified, options are modified
as indicated
in the command and the command returns an empty string.
If no @i{options} are specified, returns a list describing
the current options for entry @i{index}@r{ (see }@b{Tk_ConfigureInfo} for
information on the format of this list).
@item @i{pathName }@b{:index }@i{index}
Returns the numerical index corresponding to @i{index}, or
@b{none}@r{ if }@i{index}@r{ was specified as }@b{none}.
@item @i{pathName }@b{:invoke }@i{index}
Invoke the action of the menu entry.  See the sections on the
individual entries above for details on what happens.  If the
menu entry is disabled then nothing happens.  If the
entry has a command associated with it then the result of that
command is returned as the result of the @b{invoke} widget
command.  Otherwise the result is an empty string.  Note:  invoking
a menu entry does not automatically unpost the menu.  Normally
the associated menubutton will take care of unposting the menu.
@item @i{pathName }@b{:post }@i{x y}
Arrange for the menu to be displayed on the screen at the root-window
coordinates given by @i{x}@r{ and }@i{y}.  These coordinates are
adjusted if necessary to guarantee that the entire menu is visible on
the screen.  This command normally returns an empty string.
If the @b{:postcommand} option has been specified, then its value is
executed as a Tcl script before posting the menu and the result of
that script is returned as the result of the @b{post} widget
command.
If an error returns while executing the command, then the error is
returned without posting the menu.
@item @i{pathName }@b{:unpost}
Unmap the window so that it is no longer displayed.  If a
lower-level cascaded menu is posted, unpost that menu.  Returns an
empty string.
@item @i{pathName }@b{:yposition }@i{index}
Returns a decimal string giving the y-coordinate within the menu
window of the topmost pixel in the entry specified by @i{index}.


@end table
@unnumberedsubsec Default Bindings


Tk automatically creates class bindings for menus that give them
the following default behavior:
@itemize @asis{}
@item
[1]
When the mouse cursor enters a menu, the entry underneath the mouse
cursor is activated;  as the mouse moves around the menu, the active
entry changes to track the mouse.
@item
[2]
When button 1 is released over a menu, the active entry (if any) is invoked.
@item
[3]
A menu can be repositioned on the screen by dragging it with mouse
button 2.
@item
[4]
A number of other bindings are created to support keyboard menu traversal.
See the manual entry for @b{tk_bindForTraversal} for details on these
bindings.
@end itemize

Disabled menu entries are non-responsive:  they don't activate and
ignore mouse button presses and releases.

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

@unnumberedsubsec Bugs

At present it isn't possible to use the
option database to specify values for the options to individual
entries.

@unnumberedsubsec Keywords
menu, widget
@node scrollbar, checkbutton, menu, Widgets
@section scrollbar
@c @cartouche

scrollbar \- Create and manipulate scrollbar widgets
@unnumberedsubsec Synopsis
@b{scrollbar}@i{ pathName }@r{?}@i{options}?
@unnumberedsubsec Standard Options


@example
activeForeground       cursor           relief               
background             foreground       repeatDelay          
borderWidth            orient           repeatInterval       
@end example           


@xref{options}, for more information.
@unnumberedsubsec Arguments for Scrollbar


@table @asis
@item @code{@b{:command}}
@flushright
Name=@code{"@b{command}@r{"} Class=@code{"}@b{Command}"}
@end flushright
@sp 1

Specifies the prefix of a Tcl command to invoke to change the view
in the widget associated with the scrollbar.  When a user requests
a view change by manipulating the scrollbar, a Tcl command is
invoked.  The actual command consists of this option followed by
a space and a number.  The number indicates the logical unit that
should appear at the top of the associated window.
@end table


@table @asis
@item @code{@b{:width}}
@flushright
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
@end flushright
@sp 1

Specifies the desired narrow dimension of the scrollbar window,
not including 3-D border, if any.  For vertical
scrollbars this will be the width and for horizontal scrollbars
this will be the height.
The value may have any of the forms acceptable to @b{Tk_GetPixels}.
@end table
@c @end cartouche

@unnumberedsubsec Description

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

A scrollbar is a widget that displays two arrows, one at each end of
the scrollbar, and a @i{slider} in the middle portion of the
scrollbar.  A scrollbar is used to provide information about what
is visible in an @i{associated window} that displays an object
of some sort (such as a file being edited or a drawing).
The position and size of the slider indicate which portion of the
object is visible in the associated window.  For example, if the
slider in a vertical scrollbar covers the top third of the area
between the two arrows, it means that the associated window displays
the top third of its object.

Scrollbars can be used to adjust the view in the associated window
by clicking or dragging with the mouse.  See the BINDINGS section
below for details.

@unnumberedsubsec A Scrollbar Widget's Arguments

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

@example
@i{pathName option }@r{?}@i{arg arg ...}?
@end example

@i{Option}@r{ and the }@i{arg}s
determine the exact behavior of the command.  The following
commands are possible for scrollbar widgets:

@table @asis
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
Query or modify the configuration options of the widget.
If no @i{option} is specified, returns a list describing all of
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
information on the format of this list).  If @i{option} is specified
with no @i{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 @i{option} is specified).  If
one or more @i{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.
@i{Option}@r{ may have any of the values accepted by the }@b{scrollbar}
command.
@item @i{pathName }@b{:get}
Returns a Tcl list containing four decimal values, which are
the current @i{totalUnits}@r{, }@i{widnowUnits}@r{, }@i{firstUnit},
and @i{lastUnit} values for the scrollbar.  These are the values
from the most recent @b{set} widget command on the scrollbar.
@item @i{pathName }@b{:set}@r{ }@i{totalUnits windowUnits firstUnit lastUnit}
This command is invoked to give the scrollbar information about the
widget associated with the scrollbar.  @i{TotalUnits} is an integer
value giving the total size of the object being displayed in the
associated widget.  The meaning of one unit depends on the associated
widget;  for example, in a text editor widget units might
correspond to lines of
text.  @i{WindowUnits} indicates the total number of units that
can fit in the associated window at one time.  @i{FirstUnit}
and @i{lastUnit} give the indices of the first and last units
currently visible in the associated window (zero corresponds to the
first unit of the object).  This command should
be invoked by the associated widget whenever its object or window
changes size and whenever it changes the view in its window.

@end table
@unnumberedsubsec Bindings

The description below assumes a vertically-oriented scrollbar.
For a horizontally-oriented scrollbar replace the words ``up'', ``down'',
``top'', and ``bottom'' with ``left'', ``right'', ``left'',
and ``right'', respectively

A scrollbar widget is divided into five distinct areas.  From top
to bottom, they are:  the top arrow, the top gap (the empty space
between the arrow and the slider), the slider, the bottom gap,
and the bottom arrow.  Pressing mouse button 1 in each area has
a different effect:

@table @asis
@item @b{top arrow}
Causes the view in the associated window to shift up by one unit
(i.e. the object appears to move down one unit in its window).
If the button is held down the action will auto-repeat.
@item @b{top gap}
Causes the view in the associated window to shift up by one
less than the number of units in the window
(i.e. the portion of the object that used to appear at the very
top of the window will now appear at the very bottom).
If the button is held down the action will auto-repeat.
@item @b{slider}
Pressing button 1 in this area has no immediate effect except to
cause the slider to appear sunken rather than raised.  However,
if the mouse is moved with the button down then the slider will
be dragged, adjusting the view as the mouse is moved.
@item @b{bottom gap}
Causes the view in the associated window to shift down by one
less than the number of units in the window
(i.e. the portion of the object that used to appear at the very
bottom of the window will now appear at the very top).
If the button is held down the action will auto-repeat.
@item @b{bottom arrow}
Causes the view in the associated window to shift down by one unit
(i.e. the object appears to move up one unit in its window).
If the button is held down the action will auto-repeat.

Note:  none of the actions described above has an immediate impact
on the position of the slider in the scrollbar.  It simply invokes
the command specified in the @b{command} option to notify the
associated widget that a change in view is desired.  If the view is
actually changed then the associated widget must invoke the
scrollbar's @b{set} widget command to change what is displayed in
the scrollbar.

@end table
@unnumberedsubsec Keywords
scrollbar, widget
@node checkbutton, menubutton, scrollbar, Widgets
@section checkbutton
@c @cartouche

checkbutton \- Create and manipulate check-button widgets
@unnumberedsubsec Synopsis
@b{checkbutton}@i{ pathName }@r{?}@i{options}?
@unnumberedsubsec Standard Options


@example
activeBackground  bitmap              font        relief        
activeForeground  borderWidth         foreground  text          
anchor            cursor              padX        textVariable  
background        disabledForeground  padY        
@end example      


@xref{options}, for more information.
@unnumberedsubsec Arguments for Checkbutton


@table @asis
@item @code{@b{:command}}
@flushright
Name=@code{"@b{command}@r{"} Class=@code{"}@b{Command}"}
@end flushright
@sp 1

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 (@b{:variable} option) will
be updated before the command is invoked.
@end table


@table @asis
@item @code{@b{:height}}
@flushright
Name=@code{"@b{height}@r{"} Class=@code{"}@b{Height}"}
@end flushright
@sp 1

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 @b{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.
@end table


@table @asis
@item @code{@b{:offvalue}}
@flushright
Name=@code{"@b{offValue}@r{"} Class=@code{"}@b{Value}"}
@end flushright
@sp 1

Specifies value to store in the button's associated variable whenever
this button is deselected.  Defaults to ``0''.
@end table


@table @asis
@item @code{@b{:onvalue}}
@flushright
Name=@code{"@b{onValue}@r{"} Class=@code{"}@b{Value}"}
@end flushright
@sp 1

Specifies value to store in the button's associated variable whenever
this button is selected.  Defaults to ``1''.
@end table


@table @asis
@item @code{@b{:selector}}
@flushright
Name=@code{"@b{selector}@r{"} Class=@code{"}@b{Foreground}"}
@end flushright
@sp 1

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.
@end table


@table @asis
@item @code{@b{:state}}
@flushright
Name=@code{"@b{state}@r{"} Class=@code{"}@b{State}"}
@end flushright
@sp 1

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


@table @asis
@item @code{@b{:variable}}
@flushright
Name=@code{"@b{variable}@r{"} Class=@code{"}@b{Variable}"}
@end flushright
@sp 1

Specifies name of global variable to set to indicate whether
or not this button is selected.  Defaults to the name of the
button within its parent (i.e. the last element of the button
window's path name).
@end table


@table @asis
@item @code{@b{:width}}
@flushright
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
@end flushright
@sp 1

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 @b{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.
@end table
@c @end cartouche

@unnumberedsubsec Description

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

A check button is a widget
that displays a textual string or bitmap
and a square called a @i{selector}.
A check button has
all of the behavior of a simple button, including the
following: it can display itself in either of three different
ways, according to the @b{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, check buttons can be @i{selected}.  If a check button is
selected then a special highlight appears in the selector, and
a Tcl variable associated with the check button is set to a particular
value (normally 1).  If the check button is not selected, then
the selector is drawn in a different fashion and the associated
variable is set to a different value (typically 0).  By default,
the name of the variable associated with a check button is the
same as the @i{name} used to create the check button.  The
variable name, and the ``on'' and ``off'' values stored in it,
may be modified with options on the command line or in the option
database.  By default a check button is configured to select and deselect
itself on alternate button clicks.
In addition, each check button monitors its associated variable and
automatically selects and deselects itself when the variables value
changes to and from the button's ``on'' value.

@unnumberedsubsec A Checkbutton Widget's Arguments

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

@example
@i{pathName option }@r{?}@i{arg arg ...}?
@end example

@i{Option}@r{ and the }@i{arg}s
determine the exact behavior of the command.  The following
commands are possible for check button widgets:

@table @asis
@item @i{pathName }@b{:activate}
Change the check button's state to @b{active} and redisplay the button
using its active foreground and background colors instead of normal
colors.
This command is ignored if the check button's state is @b{disabled}.
This command is obsolete and will eventually be removed;
use ``@i{pathName }@b{:configure :state active}'' instead.
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
Query or modify the configuration options of the widget.
If no @i{option} is specified, returns a list describing all of
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
information on the format of this list).  If @i{option} is specified
with no @i{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 @i{option} is specified).  If
one or more @i{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.
@i{Option}@r{ may have any of the values accepted by the }@b{checkbutton}
command.
@item @i{pathName }@b{:deactivate}
Change the check button's state to @b{normal} and redisplay the button
using its normal foreground and background colors.
This command is ignored if the check button's state is @b{disabled}.
This command is obsolete and will eventually be removed;
use ``@i{pathName }@b{:configure :state normal}'' instead.
@item @i{pathName }@b{:deselect}
Deselect the check button:  redisplay it without a highlight in
the selector and set the associated variable to its ``off''
value.
@item @i{pathName }@b{:flash}
Flash the check button.  This is accomplished by redisplaying the check button
several times, alternating between active and normal colors.  At
the end of the flash the check button is left in the same normal/active
state as when the command was invoked.
This command is ignored if the check button's state is @b{disabled}.
@item @i{pathName }@b{:invoke}
Does just what would have happened if the user invoked the check button
with the mouse: toggle the selection state of the button and invoke
the Tcl command associated with the check button, 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 check button.
This command is ignored if the check button's state is @b{disabled}.
@item @i{pathName }@b{:select}
Select the check button:  display it with a highlighted
selector and set the associated variable to its ``on''
value.
@item @i{pathName }@b{:toggle}
Toggle the selection state of the button, redisplaying it and
modifying its associated variable to reflect the new state.

@end table
@unnumberedsubsec Bindings

Tk automatically creates class bindings for check buttons that give them
the following default behavior:
@itemize @asis{}
@item
[1]
The check button activates whenever the mouse passes over it and deactivates
whenever the mouse leaves the check button.
@item
[2]
The check 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.
@item
[3]
If mouse button 1 is pressed over the check button and later released over
the check button, the check button is invoked (i.e. its selection
state toggles and the command associated with the button is invoked,
if there is one).  However, if the mouse is not
over the check button when button 1 is released, then no invocation occurs.
@end itemize

If the check button's state is @b{disabled} then none of the above
actions occur:  the check button is completely non-responsive.

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

@unnumberedsubsec Keywords
check button, widget
@node menubutton, text, checkbutton, Widgets
@section menubutton
@c @cartouche

menubutton \- Create and manipulate menubutton widgets
@unnumberedsubsec Synopsis
@b{menubutton}@i{ }@i{pathName }@r{?}@i{options}?
@unnumberedsubsec Standard Options


@example
activeBackground  bitmap              font        relief        
activeForeground  borderWidth         foreground  text          
anchor            cursor              padX        textVariable  
background        disabledForeground  padY        underline     
@end example      


@xref{options}, for more information.
@unnumberedsubsec Arguments for Menubutton


@table @asis
@item @code{@b{:height}}
@flushright
Name=@code{"@b{height}@r{"} Class=@code{"}@b{Height}"}
@end flushright
@sp 1

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


@table @asis
@item @code{@b{:menu}}
@flushright
Name=@code{"@b{menu}@r{"} Class=@code{"}@b{MenuName}"}
@end flushright
@sp 1

Specifies the path name of the menu associated with this menubutton.
The menu must be a descendant of the menubutton in order for normal pull-down
operation to work via the mouse.
@end table


@table @asis
@item @code{@b{:state}}
@flushright
Name=@code{"@b{state}@r{"} Class=@code{"}@b{State}"}
@end flushright
@sp 1

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


@table @asis
@item @code{@b{:width}}
@flushright
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
@end flushright
@sp 1

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

@unnumberedsubsec Introduction

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

A menubutton is a widget that displays a
textual string or bitmap
and is associated with a menu widget.  In normal usage, pressing
mouse button 1 over the menubutton causes the associated menu to
be posted just underneath the menubutton.  If the mouse is moved over
the menu before releasing the mouse button, the button release
causes the underlying menu entry to be invoked.  When the button
is released, the menu is unposted.

Menubuttons are typically organized into groups called menu bars
that allow scanning:
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.
The @b{tk-menu-bar} procedure is used to set up menu bars for
scanning; see that procedure for more details.

@unnumberedsubsec A Menubutton Widget's Arguments

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

@example
@i{pathName option }@r{?}@i{arg arg ...}?
@end example

@i{Option}@r{ and the }@i{arg}s
determine the exact behavior of the command.  The following
commands are possible for menubutton widgets:

@table @asis
@item @i{pathName }@b{:activate}
Change the menu button's state to @b{active} and redisplay the menu
button using its active foreground and background colors instead of normal
colors.
The command returns an empty string.
This command is ignored if the menu button's state is @b{disabled}.
This command is obsolete and will eventually be removed;
use ``@i{pathName }@b{:configure :state active}'' instead.
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
Query or modify the configuration options of the widget.
If no @i{option} is specified, returns a list describing all of
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
information on the format of this list).  If @i{option} is specified
with no @i{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 @i{option} is specified).  If
one or more @i{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.
@i{Option}@r{ may have any of the values accepted by the }@b{menubutton}
command.
@item @i{pathName }@b{:deactivate}
Change the menu button's state to @b{normal} and redisplay the menu
button using its normal foreground and background colors.
The command returns an empty string.
This command is ignored if the menu button's state is @b{disabled}.
This command is obsolete and will eventually be removed;
use ``@i{pathName }@b{:configure :state normal}'' instead.

@end table
@unnumberedsubsec "Default Bindings"


Tk automatically creates class bindings for menu buttons that give them
the following default behavior:
@itemize @asis{}
@item
[1]
A menu button activates whenever the mouse passes over it and deactivates
whenever the mouse leaves it.
@item
[2]
A menu button's relief is changed to raised whenever mouse button 1 is
pressed over it, and the relief is restored to its original value
when button 1 is later released or the mouse is dragged into another
menu button in the same menu bar.
@item
[3]
When mouse button 1 is pressed over a menu button, or when the mouse
is dragged into a menu button with mouse button 1 pressed, the associated
menu is posted;  the mouse can be dragged across the menu and released
over an entry in the menu to invoke that entry.  The menu is unposted
when button 1 is released outside either the menu or the menu button.
The menu is also unposted when the mouse is dragged into another
menu button in the same menu bar.
@item
[4]
If mouse button 1 is pressed and released within the menu button,
then the menu stays posted and keyboard traversal is possible as
described in the manual entry for @b{tk-menu-bar}.
@item
[5]
Menubuttons may also be posted by typing characters on the keyboard.
See the manual entry for @b{tk-menu-bar} for full details on keyboard
menu traversal.
@item
[6]
If mouse button 2 is pressed over a menu button then the associated
menu is posted and also @i{torn off}:  it can then be dragged around on
the screen with button 2 and the menu will not automatically unpost when
entries in it are invoked.
To close a torn off menu, click mouse button 1 over the associated
menu button.
@end itemize

If the menu button's state is @b{disabled} then none of the above
actions occur:  the menu button is completely non-responsive.

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

@unnumberedsubsec Keywords
menubutton, widget
@node text, entry, menubutton, Widgets
@section text
@c @cartouche

text \- Create and manipulate text widgets
@unnumberedsubsec Synopsis
@b{text}@i{ }@i{pathName }@r{?}@i{options}?
@unnumberedsubsec Standard Options


@example
background      foreground        insertWidth      selectBorderWidth 
borderWidth     insertBackground  padX             selectForeground  
cursor          insertBorderWidth padY             setGrid           
exportSelection insertOffTime     relief           yScrollCommand    
font            insertOnTime      selectBackground 
@end example    


@xref{options}, for more information.
@unnumberedsubsec Arguments for Text


@table @asis
@item @code{@b{:height}}
@flushright
Name=@code{"@b{height}@r{"} Class=@code{"}@b{Height}"}
@end flushright
@sp 1

Specifies the desired height for the window, in units of characters.
Must be at least one.
@end table


@table @asis
@item @code{@b{:state}}
@flushright
Name=@code{"@b{state}@r{"} Class=@code{"}@b{State}"}
@end flushright
@sp 1

Specifies one of two states for the text:  @b{normal}@r{ or }@b{disabled}.
If the text is disabled then characters may not be inserted or deleted
and no insertion cursor will be displayed, even if the input focus is
in the widget.
@end table


@table @asis
@item @code{@b{:width}}
@flushright
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
@end flushright
@sp 1

Specifies the desired width for the window in units of characters.
If the font doesn't have a uniform width then the width of the
character ``0'' is used in translating from character units to
screen units.
@end table


@table @asis
@item @code{@b{:wrap}}
@flushright
Name=@code{"@b{wrap}@r{"} Class=@code{"}@b{Wrap}"}
@end flushright
@sp 1

Specifies how to handle lines in the text that are too long to be
displayed in a single line of the text's window.
The value must be @b{none}@r{ or }@b{char}@r{ or }@b{word}.
A wrap mode of @b{none} means that each line of text appears as
exactly one line on the screen;  extra characters that don't fit
on the screen are not displayed.
In the other modes each line of text will be broken up into several
screen lines if necessary to keep all the characters visible.
In @b{char} mode a screen line break may occur after any character;
in @b{word} mode a line break will only be made at word boundaries.
@end table
@c @end cartouche

@unnumberedsubsec Description

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

A text widget displays one or more lines of text and allows that
text to be edited.
Text widgets support three different kinds of annotations on the
text, called tags, marks, and windows.
Tags allow different portions of the text
to be displayed with different fonts and colors.
In addition, Tcl commands can be associated with tags so
that commands are invoked when particular actions such as keystrokes
and mouse button presses occur in particular ranges of the text.
See TAGS below for more details.

The second form of annotation consists of marks, which are floating
markers in the text.
Marks are used to keep track of various interesting positions in the
text as it is edited.
See MARKS below for more details.

The third form of annotation allows arbitrary windows to be displayed
in the text widget.
See WINDOWS below for more details.

@unnumberedsubsec Indices

Many of the widget commands for texts take one or more indices
as arguments.
An index is a string used to indicate a particular place within
a text, such as a place to insert characters or one endpoint of a
range of characters to delete.
Indices have the syntax

@i{base modifier modifier modifier ...}


Where @i{base}@r{ gives a starting point and the }@i{modifier}s
adjust the index from the starting point (e.g. move forward or
backward one character).  Every index must contain a @i{base},
but the @i{modifier}s are optional.


The @i{base} for an index must have one of the following forms:

@table @asis
@item @i{line}@b{.}@i{char}
Indicates @i{char}@r{'th character on line }@i{line}.
Lines are numbered from 1 for consistency with other UNIX programs
that use this numbering scheme.
Within a line, characters are numbered from 0.
@item @b{@@}@i{x}@b{,}@i{y}
Indicates the character that covers the pixel whose x and y coordinates
within the text's window are @i{x}@r{ and }@i{y}.
@item @b{end}
Indicates the last character in the text, which is always a newline
character.
@item @i{mark}
Indicates the character just after the mark whose name is @i{mark}.
@item @i{tag}@b{.first}
Indicates the first character in the text that has been tagged with
@i{tag}.
This form generates an error if no characters are currently tagged
with @i{tag}.
@item @i{tag}@b{.last}
Indicates the character just after the last one in the text that has
been tagged with @i{tag}.
This form generates an error if no characters are currently tagged
with @i{tag}.
@end table


If modifiers follow the base index, each one of them must have one
of the forms listed below.  Keywords such as @b{chars}@r{ and }@b{wordend}
may be abbreviated as long as the abbreviation is unambiguous.

@table @asis
@item @b{+ }@i{count}@b{ chars}
Adjust the index forward by @i{count} characters, moving to later
lines in the text if necessary.  If there are fewer than @i{count}
characters in the text after the current index, then set the index
to the last character in the text.
Spaces on either side of @i{count} are optional.
@item @b{-} @i{count}@b{ chars}
Adjust the index backward by @i{count} characters, moving to earlier
lines in the text if necessary.  If there are fewer than @i{count}
characters in the text before the current index, then set the index
to the first character in the text.
Spaces on either side of @i{count} are optional.
@item @b{+ }@i{count}@b{ lines}
Adjust the index forward by @i{count} lines, retaining the same
character position within the line.  If there are fewer than @i{count}
lines after the line containing the current index, then set the index
to refer to the same character position on the last line of the text.
Then, if the line is not long enough to contain a character at the indicated
character position, adjust the character position to refer to the last
character of the line (the newline).
Spaces on either side of @i{count} are optional.
@item @b{-} @i{count}@b{ lines}
Adjust the index backward by @i{count} lines, retaining the same
character position within the line.  If there are fewer than @i{count}
lines before the line containing the current index, then set the index
to refer to the same character position on the first line of the text.
Then, if the line is not long enough to contain a character at the indicated
character position, adjust the character position to refer to the last
character of the line (the newline).
Spaces on either side of @i{count} are optional.
@item @b{linestart}
Adjust the index to refer to the first character on the line.
@item @b{lineend}
Adjust the index to refer to the last character on the line (the newline).
@item @b{wordstart}
Adjust the index to refer to the first character of the word containing
the current index.  A word consists of any number of adjacent characters
that are letters, digits, or underscores, or a single character that
is not one of these.
@item @b{wordend}
Adjust the index to refer to the character just after the last one of the
word containing the current index.  If the current index refers to the last
character of the text then it is not modified.
@end table


If more than one modifier is present then they are applied in
left-to-right order.  For example, the index ``\fBend \- 1 chars''
refers to the next-to-last character in the text and
``\fBinsert wordstart \- 1 c'' refers to the character just before
the first one in the word containing the insertion cursor.

@unnumberedsubsec Tags

The first form of annotation in text widgets is a tag.
A tag is a textual string that is associated with some of the characters
in a text.
There may be any number of tags associated with characters in a
text.
Each tag may refer to a single character, a range of characters, or
several ranges of characters.
An individual character may have any number of tags associated with it.

A priority order is defined among tags, and this order is used in
implementing some of the tag-related functions described below.
When a tag is defined (by associating it with characters or setting
its display options or binding commands to it), it is given
a priority higher than any existing tag.
The priority order of tags may be redefined using the
``@i{pathName }@b{:tag :raise}@r{'' and ``}@i{pathName }@b{:tag :lower}''
widget commands.

Tags serve three purposes in text widgets.
First, they control the way information is displayed on the screen.
By default, characters are displayed as determined by the
@b{background}@r{, }@b{font}@r{, and }@b{foreground} options for the
text widget.
However, display options may be associated with individual tags
using the ``@i{pathName }@b{:tag configure}'' widget command.
If a character has been tagged, then the display options associated
with the tag override the default display style.
The following options are currently supported for tags:

@table @asis
@item @b{:background }@i{color}
@i{Color} specifies the background color to use for characters
associated with the tag.
It may have any of the forms accepted by @b{Tk_GetColor}.
@item @b{:bgstipple }@i{bitmap}
@i{Bitmap} specifies a bitmap that is used as a stipple pattern
for the background.
It may have any of the forms accepted by @b{Tk_GetBitmap}.
If @i{bitmap} hasn't been specified, or if it is specified
as an empty string, then a solid fill will be used for the
background.
@item @b{:borderwidth }@i{pixels}
@i{Pixels} specifies the width of a 3-D border to draw around
the background.
It may have any of the forms accepted by @b{Tk_GetPixels}.
This option is used in conjunction with the @b{:relief}
option to give a 3-D appearance to the background for characters;
it is ignored unless the @b{:background} option
has been set for the tag.
@item @b{:fgstipple }@i{bitmap}
@i{Bitmap} specifies a bitmap that is used as a stipple pattern
when drawing text and other foreground information such as
underlines.
It may have any of the forms accepted by @b{Tk_GetBitmap}.
If @i{bitmap} hasn't been specified, or if it is specified
as an empty string, then a solid fill will be used.
@item @b{:font }@i{fontName}
@i{FontName} is the name of a font to use for drawing characters.
It may have any of the forms accepted by @b{Tk_GetFontStruct}.
@item @b{:foreground }@i{color}
@i{Color} specifies the color to use when drawing text and other
foreground information such as underlines.
It may have any of the forms accepted by @b{Tk_GetColor}.
@item @b{:relief }@i{relief}
\fIRelief specifies the 3-D relief to use for drawing backgrounds,
in any of the forms accepted by @b{Tk_GetRelief}.
This option is used in conjunction with the @b{:borderwidth}
option to give a 3-D appearance to the background for characters;
it is ignored unless the @b{:background} option
has been set for the tag.
@item @b{:underline }@i{boolean}
@i{Boolean} specifies whether or not to draw an underline underneath
characters.
It may have any of the forms accepted by @b{Tk_GetBoolean}.

If a character has several tags associated with it, and if their
display options conflict, then the options of the highest priority
tag are used.
If a particular display option hasn't been specified for a
particular tag, or if it is specified as an empty string, then
that option will never be used;  the next-highest-priority
tag's option will used instead.
If no tag specifies a particular display optionl, then the default
style for the widget will be used.

The second purpose for tags is event bindings.
You can associate bindings with a tag in much the same way you can
associate bindings with a widget class:  whenever particular X
events occur on characters with the given tag, a given
Tcl command will be executed.
Tag bindings can be used to give behaviors to ranges of characters;
among other things, this allows hypertext-like
features to be implemented.
For details, see the description of the @b{tag bind} widget
command below.

The third use for tags is in managing the selection.
See THE SELECTION below.

@end table
@unnumberedsubsec Marks

The second form of annotation in text widgets is a mark.
Marks are used for remembering particular places in a text.
They are something like tags, in that they have names and
they refer to places in the file, but a mark isn't associated
with particular characters.
Instead, a mark is associated with the gap between two characters.
Only a single position may be associated with a mark at any given
time.
If the characters around a mark are deleted the mark will still
remain;  it will just have new neighbor characters.
In contrast, if the characters containing a tag are deleted then
the tag will no longer have an association with characters in
the file.
Marks may be manipulated with the ``@i{pathName }@b{:mark}'' widget
command, and their current locations may be determined by using the
mark name as an index in widget commands.

The name space for marks is different from that for tags:  the
same name may be used for both a mark and a tag, but they will refer
to different things.

Two marks have special significance.
First, the mark @b{insert} is associated with the insertion cursor,
as described under THE INSERTION CURSOR below.
Second, the mark @b{current} is associated with the character
closest to the mouse and is adjusted automatically to track the
mouse position and any changes to the text in the widget (one
exception:  @b{current} is not updated in response to mouse
motions if a mouse button is down;  the update will be deferred
until all mouse buttons have been released).
Neither of these special marks may be unset.

@unnumberedsubsec Windows

The third form of annotation in text widgets is a window.
Window support isn't implemented yet, but when it is it will be
described here.

@unnumberedsubsec The Selection

Text widgets support the standard X selection.
Selection support is implemented via tags.
If the @b{exportSelection} option for the text widget is true
then the @b{sel} tag will be associated with the selection:
@itemize  @asis{}
@item
[1]
Whenever characters are tagged with @b{sel} the text widget
will claim ownership of the selection.
@item
[2]
Attempts to retrieve the
selection will be serviced by the text widget, returning all the
charaters with the @b{sel} tag.
@item
[3]
If the selection is claimed away by another application or by another
window within this application, then the @b{sel} tag will be removed
from all characters in the text.
@end itemize

The @b{sel} tag is automatically defined when a text widget is
created, and it may not be deleted with the ``@i{pathName }@b{:tag delete}''
widget command.  Furthermore, the @b{selectBackground},
@b{selectBorderWidth}@r{, and }@b{selectForeground} options for
the text widget are tied to the @b{:background},
@b{:borderwidth}@r{, and }@b{:foreground}@r{ options for the }@b{sel}
tag:  changes in either will automatically be reflected in the
other.

@unnumberedsubsec The Insertion Cursor

The mark named @b{insert} has special significance in text widgets.
It is defined automatically when a text widget is created and it
may not be unset with the ``@i{pathName }@b{:mark unset}'' widget
command.
The @b{insert} mark represents the position of the insertion
cursor, and the insertion cursor will automatically be drawn at
this point whenever the text widget has the input focus.

@unnumberedsubsec A Text Widget's Arguments

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

@example
@i{pathName option }@r{?}@i{arg arg ...}?
@end example

@i{PathName} is the name of the command, which is the same as
the text widget's path name.  @i{Option}@r{ and the }@i{arg}s
determine the exact behavior of the command.  The following
commands are possible for text widgets:

@table @asis
@item @i{pathName }@b{:compare}@r{ }@i{index1 op index2}
Compares the indices given by @i{index1}@r{ and }@i{index2} according
to the relational operator given by @i{op}, and returns 1 if
the relationship is satisfied and 0 if it isn't.
@i{Op} must be one of the operators <, <=, ==, >=, >, or !=.
If @i{op} is == then 1 is returned if the two indices refer to
the same character, if @i{op}@r{ is < then 1 is returned if }@i{index1}
refers to an earlier character in the text than @i{index2}, and
so on.
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? }@i{?value option value ...}?
Query or modify the configuration options of the widget.
If no @i{option} is specified, returns a list describing all of
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
information on the format of this list).  If @i{option} is specified
with no @i{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 @i{option} is specified).  If
one or more @i{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.
@i{Option}@r{ may have any of the values accepted by the }@b{text}
command.
@item @i{pathName }@b{:debug }@r{?}@i{boolean}?
If @i{boolean} is specified, then it must have one of the true or
false values accepted by Tcl_GetBoolean.
If the value is a true one then internal consistency checks will be
turned on in the B-tree code associated with text widgets.
If @i{boolean} has a false value then the debugging checks will
be turned off.
In either case the command returns an empty string.
If @i{boolean}@r{ is not specified then the command returns }@b{on}
or @b{off} to indicate whether or not debugging is turned on.
There is a single debugging switch shared by all text widgets:  turning
debugging on or off in any widget turns it on or off for all widgets.
For widgets with large amounts of text, the consistency checks may
cause a noticeable slow-down.
@item @i{pathName }@b{:delete }@i{index1 }@r{?}@i{index2}?
Delete a range of characters from the text.
If both @i{index1}@r{ and }@i{index2} are specified, then delete
all the characters starting with the one given by @i{index1}
and stopping just before @i{index2} (i.e. the character at
@i{index2} is not deleted).
If @i{index2} doesn't specify a position later in the text
than @i{index1} then no characters are deleted.
If @i{index2} isn't specified then the single character at
@i{index1} is deleted.
It is not allowable to delete characters in a way that would leave
the text without a newline as the last character.
The command returns an empty string.
@item @i{pathName }@b{:get }@i{index1 }@r{?}@i{index2}?
Return a range of characters from the text.
The return value will be all the characters in the text starting
with the one whose index is @i{index1} and ending just before
the one whose index is @i{index2}@r{ (the character at }@i{index2}
will not be returned).
If @i{index2}@r{ is omitted then the single character at }@i{index1}
is returned.
If there are no characters in the specified range (e.g. @i{index1}
is past the end of the file or @i{index2} is less than or equal
to @i{index1}) then an empty string is returned.
@item @i{pathName }@b{:index }@i{index}
Returns the position corresponding to @i{index} in the form
@i{line.char}@r{ where }@i{line}@r{ is the line number and }@i{char}
is the character number.
@i{Index} may have any of the forms described under INDICES above.
@item @i{pathName }@b{:insert }\fIindex chars
Inserts @i{chars} into the text just before the character at
@i{index} and returns an empty string.
It is not possible to insert characters after the last newline
of the text.
@item @i{pathName }@b{:mark }@i{option }@r{?}@i{arg arg ...}?
This command is used to manipulate marks.  The exact behavior of
the command depends on the @i{option} argument that follows
the @b{mark} argument.  The following forms of the command
are currently supported:
@table @asis
@item @i{pathName }@b{:mark :names}
Returns a list whose elements are the names of all the marks that
are currently set.
@item @i{pathName }@b{:mark :set }@i{markName index}
Sets the mark named @i{markName} to a position just before the
character at @i{index}.
If @i{markName} already exists, it is moved from its old position;
if it doesn't exist, a new mark is created.
This command returns an empty string.
@item @i{pathName }@b{:mark :unset }@i{markName }@r{?}@i{markName markName ...}?
Remove the mark corresponding to each of the @i{markName} arguments.
The removed marks will not be usable in indices and will not be
returned by future calls to ``@i{pathName }@b{:mark names}''.
This command returns an empty string.
@end table

@item @i{pathName }@b{:scan}@r{ }@i{option args}
This command is used to implement scanning on texts.  It has
two forms, depending on @i{option}:
@table @asis
@item @i{pathName }@b{:scan :mark }@i{y}
Records @i{y} and the current view in the text window;  used in
conjunction with later @b{scan dragto} commands.  Typically this
command is associated with a mouse button press in the widget.  It
returns an empty string.
@item @i{pathName }@b{:scan :dragto }@i{y}
This command computes the difference between its @i{y} argument
and the @i{y}@r{ argument to the last }@b{scan mark} command for
the widget.  It then adjusts the view up or down by 10 times the
difference in y-coordinates.  This command is typically associated
with mouse motion events in the widget, to produce the effect of
dragging the text at high speed through the window.  The return
value is an empty string.
@end table

@item @i{pathName }@b{:tag }@i{option }@r{?}@i{arg arg ...}?
This command is used to manipulate tags.  The exact behavior of the
command depends on the @i{option} argument that follows the
@b{tag} argument.  The following forms of the command are currently
supported:

@table @asis
@item @i{pathName }@b{:tag :add }@i{tagName index1 }@r{?}@i{index2}?
Associate the tag @i{tagName} with all of the characters starting
with @i{index1} and ending just before
@i{index2}@r{ (the character at }@i{index2} isn't tagged).
If @i{index2} is omitted then the single character at
@i{index1} is tagged.
If there are no characters in the specified range (e.g. @i{index1}
is past the end of the file or @i{index2} is less than or equal
to @i{index1}) then the command has no effect.
This command returns an empty string.
@item @i{pathName }@b{:tag :bind }@i{tagName}@r{ ?}@i{sequence}@r{? ?}@i{command}?
This command associates @i{command} with the tag given by
@i{tagName}.
Whenever the event sequence given by @i{sequence} occurs for a
character that has been tagged with @i{tagName},
the command will be invoked.
This widget command is similar to the @b{bind} command except that
it operates on characters in a text rather than entire widgets.
See the @b{bind} manual entry for complete details
on the syntax of @i{sequence} and the substitutions performed
on @i{command} before invoking it.
If all arguments are specified then a new binding is created, replacing
any existing binding for the same @i{sequence}@r{ and }@i{tagName}
(if the first character of @i{command}@r{ is ``+'' then }@i{command}
augments an existing binding rather than replacing it).
In this case the return value is an empty string.
If @i{command}@r{ is omitted then the command returns the }@i{command}
associated with @i{tagName}@r{ and }@i{sequence} (an error occurs
if there is no such binding).
If both @i{command}@r{ and }@i{sequence} are omitted then the command
returns a list of all the sequences for which bindings have been
defined for @i{tagName}.


The only events for which bindings may be specified are those related
to the mouse and keyboard, such as @b{Enter}@r{, }@b{Leave},
@b{ButtonPress}@r{, }@b{Motion}@r{, and }@b{KeyPress}.
Event bindings for a text widget use the @b{current} mark
described under MARKS above.
@b{Enter} events trigger for a character when it
becomes the current character (i.e. the @b{current} mark moves
to just in front of that character).
@b{Leave} events trigger for a character when it ceases to be
the current item (i.e. the @b{current} mark moves away from
that character, or the character is deleted).
These events are different than @b{Enter}@r{ and }@b{Leave}
events for windows.
Mouse and keyboard events are directed to the current character.


It is possible for the current character to have multiple tags,
and for each of them to have a binding for a particular event
sequence.
When this occurs, the binding from the highest priority tag is
used.
If a particular tag doesn't have a binding that matches an
event, then the tag is ignored and tags with lower priority
will be checked.


If bindings are created for the widget as a whole using the
@b{bind} command, then those bindings will supplement the
tag bindings.
This means that a single event can trigger two Tcl scripts,
one for a widget-level binding and one for a tag-level
binding.


@item @i{pathName }@b{:tag :configure }@i{tagName}@r{ ?}@i{option}@r{? ?}@i{value}@r{? ?}@i{option value ...}?
This command is similar to the @b{configure} widget command except
that it modifies options associated with the tag given by @i{tagName}
instead of modifying options for the overall text widget.
If no @i{option} is specified, the command returns a list describing
all of the available options for @i{tagName}@r{ (see }@b{Tk_ConfigureInfo}
for information on the format of this list).
If @i{option}@r{ is specified with no }@i{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 @i{option}
is specified).
If one or more @i{option:value} pairs are specified, then the command
modifies the given option(s) to have the given value(s) in @i{tagName};
in this case the command returns an empty string.
See TAGS above for details on the options available for tags.
@item @i{pathName }@b{:tag :delete }@i{tagName }@r{?}@i{tagName ...}?
Deletes all tag information for each of the @i{tagName}
arguments.
The command removes the tags from all characters in the file
and also deletes any other information associated with the tags,
such as bindings and display information.
The command returns an empty string.
@item @i{pathName }@b{:tag :lower }@i{tagName }@r{?}@i{belowThis}?
Changes the priority of tag @i{tagName} so that it is just lower
in priority than the tag whose name is @i{belowThis}.
If @i{belowThis}@r{ is omitted, then }@i{tagName}'s priority
is changed to make it lowest priority of all tags.
@item @i{pathName }@b{:tag :names }@r{?}@i{index}?
Returns a list whose elements are the names of all the tags that
are active at the character position given by @i{index}.
If @i{index} is omitted, then the return value will describe
all of the tags that exist for the text (this includes all tags
that have been named in a ``@i{pathName }@b{:tag}'' widget
command but haven't been deleted by a ``@i{pathName }@b{:tag :delete}''
widget command, even if no characters are currently marked with
the tag).
The list will be sorted in order from lowest priority to highest
priority.
@item @i{pathName }@b{:tag :nextrange }@i{tagName index1 }@r{?}@i{index2}?
This command searches the text for a range of characters tagged
with @i{tagName} where the first character of the range is
no earlier than the character at @i{index1} and no later than
the character just before @i{index2} (a range starting at
@i{index2} will not be considered).
If several matching ranges exist, the first one is chosen.
The command's return value is a list containing
two elements, which are the index of the first character of the
range and the index of the character just after the last one in
the range.
If no matching range is found then the return value is an
empty string.
If @i{index2} is not given then it defaults to the end of the text.
@item @i{pathName }@b{:tag :raise }@i{tagName }@r{?}@i{aboveThis}?
Changes the priority of tag @i{tagName} so that it is just higher
in priority than the tag whose name is @i{aboveThis}.
If @i{aboveThis}@r{ is omitted, then }@i{tagName}'s priority
is changed to make it highest priority of all tags.
@item @i{pathName }@b{:tag :ranges }@i{tagName}
Returns a list describing all of the ranges of text that have been
tagged with @i{tagName}.
The first two elements of the list describe the first tagged range
in the text, the next two elements describe the second range, and
so on.
The first element of each pair contains the index of the first
character of the range, and the second element of the pair contains
the index of the character just after the last one in the
range.
If there are no characters tagged with @i{tag} then an
empty string is returned.
@item @i{pathName }@b{:tag :remove }@i{tagName index1 }@r{?}@i{index2}?
Remove the tag @i{tagName} from all of the characters starting
at @i{index1} and ending just before
@i{index2}@r{ (the character at }@i{index2} isn't affected).
If @i{index2} is omitted then the single character at
@i{index1} is untagged.
If there are no characters in the specified range (e.g. @i{index1}
is past the end of the file or @i{index2} is less than or equal
to @i{index1}) then the command has no effect.
This command returns an empty string.

@end table
@item @i{pathName }@b{:yview }@r{?}@b{:pickplace}@r{? }@i{what}
This command changes the view in the widget's window so that the line
given by @i{what} is visible in the window.
@i{What} may be either an absolute line number, where 0 corresponds
to the first line of the file, or an index with any of the forms
described under INDICES above.
The first form (absolute line number) is used in the commands issued
by scrollbars to control the widget's view.
If the @b{:pickplace}@r{ option isn't specified then }@i{what} will
appear at the top of the window.
If @b{:pickplace} is specified then the widget chooses where
@i{what} appears in the window:
@itemize @asis{}
@item
[1]
If @i{what} is already visible somewhere in the window then the
command does nothing.
@item
[2]
If @i{what} is only a few lines off-screen above the window then
it will be positioned at the top of the window.
@item
[3]
If @i{what} is only a few lines off-screen below the window then
it will be positioned at the bottom of the window.
@item
[4]
Otherwise, @i{what} will be centered in the window.
@end itemize

The @b{:pickplace} option is typically used after inserting text
to make sure that the insertion cursor is still visible on the screen.
This command returns an empty string.
@end table


@unnumberedsubsec Bindings

Tk automatically creates class bindings for texts that give them
the following default behavior:
@itemize @asis{}
@item
[1]
Pressing mouse button 1 in an text positions the insertion cursor
just before the character underneath the mouse cursor and sets the
input focus to this widget.
@item
[2]
Dragging with mouse button 1 strokes out a selection between
the insertion cursor and the character under the mouse.
@item
[3]
If you double-press mouse button 1 then the word under the mouse cursor
will be selected, the insertion cursor will be positioned at the
beginning of the word, and dragging the mouse will stroke out a selection
whole words at a time.
@item
[4]
If you triple-press mouse button 1 then the line under the mouse cursor
will be selected, the insertion cursor will be positioned at the
beginning of the line, and dragging the mouse will stroke out a selection
whole line at a time.
@item
[5]
The ends of the selection can be adjusted by dragging with mouse
button 1 while the shift key is down;  this will adjust the end
of the selection that was nearest to the mouse cursor when button
1 was pressed.  If the selection was made in word or line mode then
it will be adjusted in this same mode.
@item
[6]
The view in the text can be adjusted by dragging with mouse button 2.
@item
[7]
If the input focus is in a text widget and characters are typed on the
keyboard, the characters are inserted just before the insertion cursor.
@item
[8]
Control+h and the Backspace and Delete keys erase the character just
before the insertion cursor.
@item
[9]
Control+v inserts the current selection just before the insertion cursor.
@item
[10]
Control+d deletes the selected characters;  an error occurs if the selection
is not in this widget.
@end itemize

If the text is disabled using the @b{state} option, then the text's
view can still be adjusted and text in the text can still be selected,
but no insertion cursor will be displayed and no text modifications will
take place.

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

@unnumberedsubsec "Performance Issues"

Text widgets should run efficiently under a variety
of conditions.  The text widget uses about 2-3 bytes of
main memory for each byte of text, so texts containing a megabyte
or more should be practical on most workstations.
Text is represented internally with a modified B-tree structure
that makes operations relatively efficient even with large texts.
Tags are included in the B-tree structure in a way that allows
tags to span large ranges or have many disjoint smaller ranges
without loss of efficiency.
Marks are also implemented in a way that allows large numbers of
marks.
The only known mode of operation where a text widget may not run
efficiently is if it has a very large number of different tags.
Hundreds of tags should be fine, or even a thousand,
but tens of thousands of tags will make texts consume a lot of
memory and run slowly.

@unnumberedsubsec Keywords
text, widget
@node entry, message, text, Widgets
@section entry
@c @cartouche

entry \- Create and manipulate entry widgets
@unnumberedsubsec Synopsis
@b{entry}@i{ }@i{pathName }@r{?}@i{options}?
@unnumberedsubsec Standard Options


@example
background      foreground        insertWidth       selectForeground 
borderWidth     insertBackground  relief            textVariable     
cursor          insertBorderWidth scrollCommand     
exportSelection insertOffTime     selectBackground  
font            insertOnTime      selectBorderWidth 
@end example    


@xref{options}, for more information.
@unnumberedsubsec Arguments for Entry


@table @asis
@item @code{@b{:state}}
@flushright
Name=@code{"@b{state}@r{"} Class=@code{"}@b{State}"}
@end flushright
@sp 1

Specifies one of two states for the entry:  @b{normal}@r{ or }@b{disabled}.
If the entry is disabled then the value may not be changed using widget
commands and no insertion cursor will be displayed, even if the input focus is
in the widget.
@end table


@table @asis
@item @code{@b{:width}}
@flushright
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
@end flushright
@sp 1

Specifies an integer value indicating the desired width of the entry window,
in average-size characters of the widget's font.
@end table
@c @end cartouche

@unnumberedsubsec Description

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

An entry is a widget that displays a one-line text string and
allows that string to be edited using widget commands described below, which
are typically bound to keystrokes and mouse actions.
When first created, an entry's string is empty.
A portion of the entry may be selected as described below.
If an entry is exporting its selection (see the @b{exportSelection}
option), then it will observe the standard X11 protocols for handling the
selection;  entry selections are available as type @b{STRING}.
Entries also observe the standard Tk rules for dealing with the
input focus.  When an entry has the input focus it displays an
@i{insertion cursor} to indicate where new characters will be
inserted.

Entries are capable of displaying strings that are too long to
fit entirely within the widget's window.  In this case, only a
portion of the string will be displayed;  commands described below
may be used to change the view in the window.  Entries use
the standard @b{scrollCommand} mechanism for interacting with
scrollbars (see the description of the @b{scrollCommand} option
for details).  They also support scanning, as described below.

@unnumberedsubsec A Entry Widget's Arguments

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

@example
@i{pathName option }@r{?}@i{arg arg ...}?
@end example

@i{Option}@r{ and the }@i{arg}s
determine the exact behavior of the command.

Many of the widget commands for entries take one or more indices as
arguments.  An index specifies a particular character in the entry's
string, in any of the following ways:

@table @asis
@item @i{number}
Specifies the character as a numerical index, where 0 corresponds
to the first character in the string.
@item @b{end}
Indicates the character just after the last one in the entry's string.
This is equivalent to specifying a numerical index equal to the length
of the entry's string.
@item @b{insert}
Indicates the character adjacent to and immediately following the
insertion cursor.
@item @b{sel.first}
Indicates the first character in the selection.  It is an error to
use this form if the selection isn't in the entry window.
@item @b{sel.last}
Indicates the last character in the selection.  It is an error to
use this form if the selection isn't in the entry window.
@item @b{@@}@i{number}
In this form, @i{number} is treated as an x-coordinate in the
entry's window;  the character spanning that x-coordinate is used.
For example, ``@b{@@0}'' indicates the left-most character in the
window.
@end table


Abbreviations may be used for any of the forms above, e.g. ``@b{e}''
or ``@b{sel.f}''.  In general, out-of-range indices are automatically
rounded to the nearest legal value.

The following commands are possible for entry widgets:

@table @asis
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
Query or modify the configuration options of the widget.
If no @i{option} is specified, returns a list describing all of
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
information on the format of this list).  If @i{option} is specified
with no @i{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 @i{option} is specified).  If
one or more @i{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.
@i{Option}@r{ may have any of the values accepted by the }@b{entry}
command.
@item @i{pathName }@b{:delete }@i{first }@r{?}@i{last}?
Delete one or more elements of the entry.  @i{First}@r{ and }@i{last}
are indices of of the first and last characters in the range to
be deleted.   If @i{last} isn't specified it defaults to
@i{first}, i.e. a single character is deleted.  This command
returns an empty string.
@item @i{pathName }@b{:get}
Returns the entry's string.
@item @i{pathName }@b{:icursor }@i{index}
Arrange for the insertion cursor to be displayed just before the character
given by @i{index}.  Returns an empty string.
@item @i{pathName }@b{:index}@i{ index}
Returns the numerical index corresponding to @i{index}.
@item @i{pathName }@b{:insert }@i{index string}
Insert the characters of @i{string} just before the character
indicated by @i{index}.  Returns an empty string.
@item @i{pathName }@b{:scan}@r{ }@i{option args}
This command is used to implement scanning on entries.  It has
two forms, depending on @i{option}:
@table @asis
@item @i{pathName }@b{:scan :mark }@i{x}
Records @i{x} and the current view in the entry window;  used in
conjunction with later @b{scan dragto} commands.  Typically this
command is associated with a mouse button press in the widget.  It
returns an empty string.
@item @i{pathName }@b{:scan :dragto }@i{x}
This command computes the difference between its @i{x} argument
and the @i{x}@r{ argument to the last }@b{scan mark} command for
the widget.  It then adjusts the view left or right by 10 times the
difference in x-coordinates.  This command is typically associated
with mouse motion events in the widget, to produce the effect of
dragging the entry at high speed through the window.  The return
value is an empty string.
@end table
@item @i{pathName }@b{:select }@i{option arg}
This command is used to adjust the selection within an entry.  It
has several forms, depending on @i{option}:
@table @asis
@item @i{pathName }@b{:select :adjust }@i{index}
Locate the end of the selection nearest to the character given by
@i{index}@r{, and adjust that end of the selection to be at }@i{index}
(i.e including but not going beyond @i{index}).  The other
end of the selection is made the anchor point for future
@b{select to} commands.  If the selection
isn't currently in the entry, then a new selection is created to
include the characters between @i{index} and the most recent
selection anchor point, inclusive.
Returns an empty string.
@item @i{pathName }@b{:select :clear}
Clear the selection if it is currently in this widget.  If the
selection isn't in this widget then the command has no effect.
Returns an empty string.
@item @i{pathName }@b{:select :from }@i{index}
Set the selection anchor point to just before the character
given by @i{index}.  Doesn't change the selection.
Returns an empty string.
@item @i{pathName }@b{:select :to }@i{index}
Set the selection to consist of the elements from the anchor
point to element @i{index}, inclusive.  The anchor point is
determined by the most recent @b{select from}@r{ or }@b{select adjust}
command in this widget.  If the selection isn't in this widget
then a new selection is created using the most recent anchor point
specified for the widget.  Returns an empty string.
@end table
@item @i{pathName }@b{:view }@i{index}
Adjust the view in the entry so that element @i{index} is
at the left edge of the window.  Returns an empty string.

@end table
@unnumberedsubsec "Default Bindings"

Tk automatically creates class bindings for entries that give them
the following default behavior:

@itemize @asis{}
@item
[1]
Clicking mouse button 1 in an entry positions the insertion cursor
just before the character underneath the mouse cursor and sets the
input focus to this widget.
@item
[2]
Dragging with mouse button 1 strokes out a selection between
the insertion cursor and the character under the mouse.
@item
[3]
The ends of the selection can be adjusted by dragging with mouse
button 1 while the shift key is down;  this will adjust the end
of the selection that was nearest to the mouse cursor when button
1 was pressed.
@item
[4]
The view in the entry can be adjusted by dragging with mouse button 2.
@item
[5]
If the input focus is in an entry widget and characters are typed on the
keyboard, the characters are inserted just before the insertion cursor.
@item
[6]
Control-h and the Backspace and Delete keys erase the character just
before the insertion cursor.
@item
[7]
Control-w erases the word just before the insertion cursor.
@item
[8]
Control-u clears the entry to an empty string.
@item
[9]
Control-v inserts the current selection just before the insertion cursor.
@item
[10]
Control-d deletes the selected characters;  an error occurs if the selection
is not in this widget.
@end itemize

If the entry is disabled using the @b{state} option, then the entry's
view can still be adjusted and text in the entry can still be selected,
but no insertion cursor will be displayed and no text modifications will
take place.

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

@unnumberedsubsec Keywords
entry, widget
@node message, frame, entry, Widgets
@section message
@c @cartouche

message \- Create and manipulate message widgets
@unnumberedsubsec Synopsis
@b{message}@i{ }@i{pathName }@r{?}@i{options}?
@unnumberedsubsec Standard Options


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


@xref{options}, for more information.
@unnumberedsubsec Arguments for Message


@table @asis
@item @code{@b{:aspect}}
@flushright
Name=@code{"@b{aspect}@r{"} Class=@code{"}@b{Aspect}"}
@end flushright
@sp 1

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 @b{width} option
isn't specified.
Defaults to 150.
@end table


@table @asis
@item @code{@b{:justify}}
@flushright
Name=@code{"@b{justify}@r{"} Class=@code{"}@b{Justify}"}
@end flushright
@sp 1

Specifies how to justify lines of text.
Must be one of @b{left}@r{, }@b{center}@r{, or }@b{right}.  Defaults
to @b{left}.
This option works together with the @b{anchor}@r{, }@b{aspect},
@b{padX}@r{, }@b{padY}@r{, and }@b{width} options to provide a variety
of arrangements of the text within the window.
The @b{aspect}@r{ and }@b{width} options determine the amount of
screen space needed to display the text.
The @b{anchor}@r{, }@b{padX}@r{, and }@b{padY} options determine where this
rectangular area is displayed within the widget's window, and the
@b{justify} option determines how each line is displayed within that
rectangular region.
For example, suppose @b{anchor}@r{ is }@b{e}@r{ and }@b{justify} is
@b{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 @b{padX} from
the right side of the window;  the entire text block will be centered
in the vertical span of the window.
@end table


@table @asis
@item @code{@b{:width}}
@flushright
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
@end flushright
@sp 1

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

@unnumberedsubsec Description

The @b{message} command creates a new window (given by the
@i{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 @b{message} command returns its
@i{pathName} argument.  At the time this command is invoked,
there must not exist a window named @i{pathName}, but
@i{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\ex@i{hh} where
@i{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.

@unnumberedsubsec A Message Widget's Arguments

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

@example
@i{pathName option }@r{?}@i{arg arg ...}?
@end example

@i{Option}@r{ and the }@i{arg}s
determine the exact behavior of the command.  The following
commands are possible for message widgets:

@table @asis
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
Query or modify the configuration options of the widget.
If no @i{option} is specified, returns a list describing all of
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
information on the format of this list).  If @i{option} is specified
with no @i{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 @i{option} is specified).  If
one or more @i{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.
@i{Option}@r{ may have any of the values accepted by the }@b{message}
command.

@end table
@unnumberedsubsec "Default Bindings"

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

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

@unnumberedsubsec Keywords
message, widget
@node frame, label, message, Widgets
@section frame
@c @cartouche

frame \- Create and manipulate frame widgets
@unnumberedsubsec Synopsis
@b{frame}@i{ }@i{pathName }@r{?}@b{:class }@i{className}@r{? ?}@i{options}?
@unnumberedsubsec Standard Options


@example
background             cursor             relief           
borderWidth            geometry           
@end example           


@xref{options}, for more information.
@unnumberedsubsec Arguments for Frame


@table @asis
@item @code{@b{:height}}
@flushright
Name=@code{"@b{height}@r{"} Class=@code{"}@b{Height}"}
@end flushright
@sp 1

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


@table @asis
@item @code{@b{:width}}
@flushright
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
@end flushright
@sp 1

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

@unnumberedsubsec Description

The @b{frame} command creates a new window (given by the
@i{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 @b{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 @b{:class}
option may be specified on the command line.  If it is specified, then
the new widget's class will be set to @i{className} instead of
@b{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:  @b{: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 @b{:class} option may not be queried or changed using the
@b{config} command described below.

@unnumberedsubsec A Frame Widget's Arguments

The @b{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:

@example
@i{pathName option }@r{?}@i{arg arg ...}?
@end example

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

@table @asis
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? }@i{?value option value ...}?
Query or modify the configuration options of the widget.
If no @i{option} is specified, returns a list describing all of
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
information on the format of this list).  If @i{option} is specified
with no @i{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 @i{option} is specified).  If
one or more @i{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.
@i{Option}@r{ may have any of the values accepted by the }@b{frame}
command.

@end table
@unnumberedsubsec Bindings

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

@unnumberedsubsec Keywords
frame, widget
@node label, radiobutton, frame, Widgets
@section label
@c @cartouche

label \- Create and manipulate label widgets
@unnumberedsubsec Synopsis
@b{label}@i{ }@i{pathName }@r{?}@i{options}?
@unnumberedsubsec Standard Options


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


@xref{options}, for more information.
@unnumberedsubsec Arguments for Label


@table @asis
@item @code{@b{:height}}
@flushright
Name=@code{"@b{height}@r{"} Class=@code{"}@b{Height}"}
@end flushright
@sp 1

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 @b{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.
@end table


@table @asis
@item @code{@b{:width}}
@flushright
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
@end flushright
@sp 1

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 @b{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.
@end table
@c @end cartouche

@unnumberedsubsec Description

The @b{label} command creates a new window (given by the
@i{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 @b{label} command returns its
@i{pathName} argument.  At the time this command is invoked,
there must not exist a window named @i{pathName}, but
@i{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.

@unnumberedsubsec A Label Widget's Arguments

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

@example
@i{pathName option }@r{?}@i{arg arg ...}?
@end example

@i{Option}@r{ and the }@i{arg}s
determine the exact behavior of the command.  The following
commands are possible for label widgets:

@table @asis
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
Query or modify the configuration options of the widget.
If no @i{option} is specified, returns a list describing all of
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
information on the format of this list).  If @i{option} is specified
with no @i{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 @i{option} is specified).  If
one or more @i{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.
@i{Option}@r{ may have any of the values accepted by the }@b{label}
command.

@end table
@unnumberedsubsec Bindings

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

@unnumberedsubsec Keywords
label, widget
@node radiobutton, toplevel, label, Widgets
@section radiobutton
@c @cartouche

radiobutton \- Create and manipulate radio-button widgets
@unnumberedsubsec Synopsis
@b{radiobutton}@i{ }@i{pathName }@r{?}@i{options}?
@unnumberedsubsec Standard Options


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


@xref{options}, for more information.
@unnumberedsubsec Arguments for Radiobutton


@table @asis
@item @code{@b{:command}}
@flushright
Name=@code{"@b{command}@r{"} Class=@code{"}@b{Command}"}
@end flushright
@sp 1

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 (@b{:variable} option) will
be updated before the command is invoked.
@end table


@table @asis
@item @code{@b{:height}}
@flushright
Name=@code{"@b{height}@r{"} Class=@code{"}@b{Height}"}
@end flushright
@sp 1

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 @b{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.
@end table


@table @asis
@item @code{@b{:selector}}
@flushright
Name=@code{"@b{selector}@r{"} Class=@code{"}@b{Foreground}"}
@end flushright
@sp 1

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.
@end table


@table @asis
@item @code{@b{:state}}
@flushright
Name=@code{"@b{state}@r{"} Class=@code{"}@b{State}"}
@end flushright
@sp 1

Specifies one of three states for the radio button:  @b{normal}@r{, }@b{active},
or @b{disabled}.  In normal state the radio button is displayed using the
@b{foreground}@r{ and }@b{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 @b{activeForeground} and
@b{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 @b{disabledForeground} and
@b{background} options determine how the radio button is displayed.
@end table


@table @asis
@item @code{@b{:value}}
@flushright
Name=@code{"@b{value}@r{"} Class=@code{"}@b{Value}"}
@end flushright
@sp 1

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


@table @asis
@item @code{@b{:variable}}
@flushright
Name=@code{"@b{variable}@r{"} Class=@code{"}@b{Variable}"}
@end flushright
@sp 1

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 @b{selectedButton}.
@end table


@table @asis
@item @code{@b{:width}}
@flushright
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
@end flushright
@sp 1

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 @b{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.
@end table
@c @end cartouche

@unnumberedsubsec Description

The @b{radiobutton} command creates a new window (given by the
@i{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 @b{radiobutton} command returns its
@i{pathName} argument.  At the time this command is invoked,
there must not exist a window named @i{pathName}, but
@i{pathName}'s parent must exist.

A radio button is a widget
that displays a textual string or bitmap
and a diamond called a @i{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 @b{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 @i{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 @b{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.

@unnumberedsubsec A Radiobutton Widget's Arguments

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

@example
@i{pathName option }@r{?}@i{arg arg ...}?
@end example

@i{Option}@r{ and the }@i{arg}s
determine the exact behavior of the command.  The following
commands are possible for radio-button widgets:

@table @asis
@item @i{pathName }@b{:activate}
Change the radio button's state to @b{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 @b{disabled}.
This command is obsolete and will eventually be removed;
use ``@i{pathName }@b{:configure :state active}'' instead.
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
Query or modify the configuration options of the widget.
If no @i{option} is specified, returns a list describing all of
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
information on the format of this list).  If @i{option} is specified
with no @i{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 @i{option} is specified).  If
one or more @i{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.
@i{Option}@r{ may have any of the values accepted by the }@b{radiobutton}
command.
@item @i{pathName }@b{:deactivate}
Change the radio button's state to @b{normal} and redisplay the button
using its normal foreground and background colors.
This command is ignored if the radio button's state is @b{disabled}.
This command is obsolete and will eventually be removed;
use ``@i{pathName }@b{:configure :state normal}'' instead.
@item @i{pathName }@b{: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.
@item @i{pathName }@b{: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 @b{disabled}.
@item @i{pathName }@b{: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 @b{disabled}.
@item @i{pathName }@b{:select}
Select the radio button:  display it with a highlighted
selector and set the associated variable to the value corresponding
to this widget.

@end table
@unnumberedsubsec Bindings

Tk automatically creates class bindings for radio buttons that give them
the following default behavior:
@itemize @asis{}
@item
[1]
The radio button activates whenever the mouse passes over it and deactivates
whenever the mouse leaves the radio button.
@item
[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.
@item
[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.
@end itemize

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

@unnumberedsubsec Keywords
radio button, widget
@node toplevel,  , radiobutton, Widgets
@section toplevel
@c @cartouche

toplevel \- Create and manipulate toplevel widgets
@unnumberedsubsec Synopsis
@b{toplevel}@i{ }@i{pathName }@r{?}@b{:screen }@i{screenName}@r{? ?}@b{:class }@i{className}@r{? ?}@i{options}?
@unnumberedsubsec Standard Options


@example
background                  geometry                
borderWidth                 relief                  
@end example                


@xref{options}, for more information.
@unnumberedsubsec Arguments for Toplevel
@c @end cartouche

@unnumberedsubsec Description

The @b{toplevel} command creates a new toplevel widget (given
by the @i{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 @b{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 @b{toplevel}
command:  @b{:class}@r{ and }@b{:screen}@r{.  If }@b{:class}
is specified, then the new widget's class will be set to
@i{className}@r{ instead of }@b{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 @b{: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:  @b{:class}@r{ and }@b{: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, @b{:class}@r{ and }@b{:screen}
may not be queried or changed using the @b{config} command described
below.  However, the @b{winfo :class} command may be used to query
the class of a window, and @b{winfo :screen} may be used to query
its screen.

@unnumberedsubsec A Toplevel Widget's Arguments 

The @b{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:

@example
@i{pathName option }@r{?}@i{arg arg ...}?
@end example

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

@table @asis
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
Query or modify the configuration options of the widget.
If no @i{option} is specified, returns a list describing all of
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
information on the format of this list).  If @i{option} is specified
with no @i{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 @i{option} is specified).  If
one or more @i{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.
@i{Option}@r{ may have any of the values accepted by the }@b{toplevel}
command.

@end table
@unnumberedsubsec Bindings

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

@unnumberedsubsec Keywords
toplevel, widget