Widgets
*******

button
======

button \- Create and manipulate button widgets

Synopsis
--------

button pathName ?options?

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

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

See options, for more information.

Arguments for Button
--------------------

:command

     Name="command" Class="Command"

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

:height

     Name="height" Class="Height"

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

:state

     Name="state" Class="State"

     Specifies one of three states for the button:  normal, active, or disabled.  In normal state the button is displayed using the foreground and background options.  The active state is typically used when the pointer is over the button.  In active state the button is displayed using the activeForeground and 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 disabledForeground and background options determine how the button is displayed.

:width

     Name="width" Class="Width"

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

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

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

A button is a widget that displays a textual string or bitmap. It can display itself in either of three different ways, according to the state option; it can be made to appear raised, sunken, or flat; 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 :command option is invoked.

A Button Widget's Arguments
---------------------------

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

     pathName option ?arg arg ...?

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

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

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

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

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

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

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

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

  [1] The button activates whenever the mouse passes over it and deactivates whenever the mouse leaves the button.

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

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

If the button's state is 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.

Keywords
--------

button, widget

listbox
=======

listbox \- Create and manipulate listbox widgets

Synopsis
--------

listbox pathName ?options?

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

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

See options, for more information.

Arguments for Listbox
---------------------

None.

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

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

A 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 exportSelection option), then it will observe the standard X11 protocols for handling the selection;  listbox selections are available as type 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 xScrollCommand and yScrollCommand options. They also support scanning, as described below.

A Listbox's Arguments
---------------------

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

     pathName option ?arg arg ...?

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

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

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

pathName :delete first ?last?
     Delete one or more elements of the listbox.  First and last give the integer indices of the first and last elements in the range to be deleted.  If last isn't specified it defaults to first, i.e. a single element is deleted.  An index of 0 corresponds to the first element in the listbox.  Either first or last may be specified as end, in which case it refers to the last element of the listbox.  This command returns an empty string

pathName :get index
     Return the contents of the listbox element indicated by index. Index must be a non-negative integer (0 corresponds to the first element in the listbox), or it may also be specified as end to indicate the last element in the listbox.

pathName :insert index ?element element ...?
     Insert zero or more new elements in the list just before the element given by index.  If index is specified as end then the new elements are added to the end of the list.  Returns an empty string.

pathName :nearest y
     Given a y-coordinate within the listbox window, this command returns the index of the (visible) listbox element nearest to that y-coordinate.

pathName :scan option args
     This command is used to implement scanning on listboxes.  It has two forms, depending on option:

     pathName :scan :mark x y
          Records x and y and the current view in the listbox window;  used in conjunction with later scan dragto commands. Typically this command is associated with a mouse button press in the widget.  It returns an empty string.

     pathName :scan :dragto x y.
          This command computes the difference between its x and y arguments and the x and y arguments to the last 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.

pathName :select option arg
     This command is used to adjust the selection within a listbox.  It has several forms, depending on option.  In all of the forms the index end refers to the last element in the listbox.

     pathName :select :adjust index
          Locate the end of the selection nearest to the element given by index, and adjust that end of the selection to be at index (i.e including but not going beyond index).  The other end of the selection is made the anchor point for future select to commands.  If the selection isn't currently in the listbox, then this command is identical to the select from widget command. Returns an empty string.

     pathName :select :clear
          If the selection is in this listbox then it is cleared so that none of the listbox's elements are selected anymore.

     pathName :select :from index
          Set the selection to consist of element index, and make index the anchor point for future select to widget commands.  Returns an empty string.

     pathName :select :to index
          Set the selection to consist of the elements from the anchor point to element index, inclusive.  The anchor point is determined by the most recent select from or select adjust command in this widget.  If the selection isn't in this widget, this command is identical to select from. Returns an empty string.

pathName :size
     Returns a decimal string indicating the total number of elements in the listbox.

pathName :xview index
     Adjust the view in the listbox so that character position index is displayed at the left edge of the widget. Returns an empty string.

pathName :yview index
     Adjust the view in the listbox so that element index is displayed at the top of the widget. If index is specified as end it indicates the last element of the listbox.  Returns an empty string.

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

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

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

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

  [3] The view in the listbox can be adjusted by dragging with mouse button 2.

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

Keywords
--------

listbox, widget

scale
=====

scale \- Create and manipulate scale widgets

Synopsis
--------

scale pathName ?options?

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

     activeForeground     borderWidth     font           orient
     background           cursor          foreground     relief

See options, for more information.

Arguments for Scale
-------------------

:command

     Name="command" Class="Command"

     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.

:from

     Name="from" Class="From"

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

:label

     Name="label" Class="Label"

     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.

:length

     Name="length" Class="Length"

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

:showvalue

     Name="showValue" Class="ShowValue"

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

:sliderforeground

     Name="sliderForeground" Class="sliderForeground"

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

:sliderlength

     Name="sliderLength" Class="SliderLength"

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

:state

     Name="state" Class="State"

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

:tickinterval

     Name="tickInterval" Class="TickInterval"

     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.

:to

     Name="to" Class="To"

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

:width

     Name="width" Class="Width"

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

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

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

A scale is a widget that displays a rectangular region and a small slider.  The rectangular region corresponds to a range of integer values (determined by the from and 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 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.

A Scale's"Argumentsommand"
--------------------------

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

     pathName option ?arg arg ...?

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

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

pathName :get
     Returns a decimal string giving the current value of the scale.

pathName :set value
     This command is invoked to change the current value of the scale, and hence the position at which the slider is displayed.  Value gives the new value for the scale.

Bindings
--------

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

<Enter>
     Change the slider display to use activeForeground instead of sliderForeground.

<Leave>
     Reset the slider display to use sliderForeground instead of activeForeground.

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

<Button1-Motion>
     Move the slider (and adjust the scale's value) to correspond to the current mouse position.

<ButtonRelease-1>
     Reset the slider display so that the slider appears raised again.

Keywords
--------

scale, widget

canvas
======

canvas \- Create and manipulate canvas widgets

Synopsis
--------

canvas pathName ?options?

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

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

See options, for more information.

Arguments for Canvas
--------------------

:closeenough

     Name="closeEnough" Class="CloseEnough"

     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.

:confine

     Name="confine" Class="Confine"

     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 scrollRegion argument. Defaults to true, which means that the view will be constrained within the scroll region.

:height

     Name="height" Class="Height"

     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.

:scrollincrement

     Name="scrollIncrement" Class="ScrollIncrement"

     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.

:scrollregion

     Name="scrollRegion" Class="ScrollRegion"

     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.

:width

     Name="width" Class="width"

     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.

Introduction
------------

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

Canvas widgets implement structured graphics. A canvas displays any number of 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 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.

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.

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 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 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 current is managed automatically by Tk; it applies to the 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 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 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 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.

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 m then the distance is in millimeters on the screen;  if it is c then the distance is in centimeters; i means inches, and 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.

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

Indices
-------

Text items support the notion of an 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.

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.

end
     Refers to the character just after the last one in the item (same as the number of characters in the item).

insert
     Refers to the character just before which the insertion cursor is drawn in this item.

sel.first
     Refers to the first selected character in the item. If the selection isn't in this item then this form is illegal.

sel.last
     Refers to the last selected character in the item. If the selection isn't in this item then this form is illegal.

@x,y
     Refers to the character at the point given by x and y, where x and y are specified in the coordinate system of the canvas. If x and 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.

A Canvas Widget's Arguments
---------------------------

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

     pathName option ?arg arg ...?

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

pathName :addtag tag searchSpec ?arg arg ...?
     For each item that meets the constraints specified by searchSpec and the args, add 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 searchSpec and args, in which case the command has no effect. This command returns an empty string as result. SearchSpec and arg's may take any of the following forms:

     above tagOrId
          Selects the item just after (above) the one given by tagOrId in the display list. If tagOrId denotes more than one item, then the last (topmost) of these items in the display list is used.

     all
          Selects all the items in the canvas.

     below tagOrId
          Selects the item just before (below) the one given by tagOrId in the display list. If tagOrId denotes more than one item, then the first (lowest) of these items in the display list is used.

     closest x y ?halo? ?start?
          Selects the item closest to the point given by x and 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 halo is specified, then it must be a non-negative value. Any item closer than halo to the point is considered to overlap it. The start argument may be used to step circularly through all the closest items. If 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 start in the display list;  if no such item exists, then the selection behaves as if the start argument had not been specified.

     enclosed x1 y1 x2 y2
          Selects all the items completely enclosed within the rectangular region given by x1, y1, x2, and y2. X1 must be no greater then x2 and y1 must be no greater than y2.

     overlapping x1 y1 x2 y2
          Selects all the items that overlap or are enclosed within the rectangular region given by x1, y1, x2, and y2. X1 must be no greater then x2 and y1 must be no greater than y2.

     withtag tagOrId
          Selects all the items given by tagOrId.

pathName :bbox tagOrId ?tagOrId tagOrId ...?
     Returns a list with four elements giving an approximate bounding box for all the items named by the tagOrId arguments. The list has the form ``x1 y1 x2 y2'' such that the drawn areas of all the named elements are within the region bounded by x1 on the left, x2 on the right, y1 on the top, and y2 on the bottom. The return value may overestimate the actual bounding box by a few pixels. If no items match any of the tagOrId arguments then an empty string is returned.

pathName :bind tagOrId ?sequence? ?command?
     This command associates command with all the items given by tagOrId such that whenever the event sequence given by sequence occurs for one of the items the command will be invoked. This widget command is similar to the bind command except that it operates on items in a canvas rather than entire widgets. See the bind manual entry for complete details on the syntax of sequence and the substitutions performed on command before invoking it. If all arguments are specified then a new binding is created, replacing any existing binding for the same sequence and tagOrId (if the first character of command is ``+'' then command augments an existing binding rather than replacing it). In this case the return value is an empty string. If command is omitted then the command returns the command associated with tagOrId and sequence (an error occurs if there is no such binding). If both command and sequence are omitted then the command returns a list of all the sequences for which bindings have been defined for tagOrId.

The only events for which bindings may be specified are those related to the mouse and keyboard, such as Enter, Leave, ButtonPress, Motion, and KeyPress. The handling of events in canvases uses the current item defined in ITEM IDS AND TAGS above. Enter and 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 Enter and 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 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 all, the binding will have lower priority than all other bindings associated with the item.

pathName :canvasx screenx ?gridspacing?
     Given a screen x-coordinate screenx this command returns the canvas x-coordinate that is displayed at that location. If gridspacing is specified, then the canvas coordinate is rounded to the nearest multiple of gridspacing units.

pathName :canvasy screeny ?gridspacing?
     Given a screen y-coordinate screeny this command returns the canvas y-coordinate that is displayed at that location. If gridspacing is specified, then the canvas coordinate is rounded to the nearest multiple of gridspacing units.

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

pathName :coords tagOrId ?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 tagOrId. If coordinates are specified, then they replace the current coordinates for the named item. If tagOrId refers to multiple items, then the first one in the display list is used.

pathName :create type x y ?x y ...? ?option value ...?
     Create a new item in pathName of type type. The exact format of the arguments after type depends on 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.

pathName :dchars tagOrId first ?last?
     For each item given by tagOrId, delete the characters in the range given by first and last, inclusive. If some of the items given by tagOrId don't support text operations, then they are ignored. First and last are indices of characters within the item(s) as described in INDICES above. If last is omitted, it defaults to first. This command returns an empty string.

pathName :delete ?tagOrId tagOrId ...?
     Delete each of the items given by each tagOrId, and return an empty string.

pathName :dtag tagOrId ?tagToDelete?
     For each of the items given by tagOrId, delete the tag given by tagToDelete from the list of those associated with the item. If an item doesn't have the tag tagToDelete then the item is unaffected by the command. If tagToDelete is omitted then it defaults to tagOrId. This command returns an empty string.

pathName :find searchCommand ?arg arg ...?
     This command returns a list consisting of all the items that meet the constraints specified by searchCommand and arg's. SearchCommand and args have any of the forms accepted by the addtag command.

pathName :focus ?tagOrId?
     Set the keyboard focus for the canvas widget to the item given by tagOrId. If 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 tagOrId doesn't refer to any items, or if none of them support the insertion cursor, then the focus isn't changed. If tagOrId is an empty string, then the focus item is reset so that no item has the focus. If 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.

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 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 focus widget command with the focus command to set the focus window to the canvas (if it wasn't there already).

pathName :gettags tagOrId
     Return a list whose elements are the tags associated with the item given by tagOrId. If tagOrId refers to more than one item, then the tags are returned from the first such item in the display list. If tagOrId doesn't refer to any items, or if the item contains no tags, then an empty string is returned.

pathName :icursor tagOrId index
     Set the position of the insertion cursor for the item(s) given by tagOrId to just before the character whose position is given by index. If some or all of the items given by 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 index. Note:  the insertion cursor is only displayed in an item if that item currently has the keyboard focus (see the widget command focus, below), but the cursor position may be set even when the item doesn't have the focus. This command returns an empty string.

pathName :index tagOrId index
     This command returns a decimal string giving the numerical index within tagOrId corresponding to index. 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 tagOrId refers to multiple items, then the index is processed in the first of these items that supports indexing operations (in display list order).

pathName :insert tagOrId beforeThis string
     For each of the items given by tagOrId, if the item supports text insertion then string is inserted into the item's text just before the character whose index is beforeThis. See INDICES above for information about the forms allowed for beforeThis. This command returns an empty string.

pathName :itemconfigure tagOrId ?option? ?value? ?option value ...?
     This command is similar to the configure widget command except that it modifies item-specific options for the items given by tagOrId instead of modifying options for the overall canvas widget. If no option is specified, returns a list describing all of the available options for the first item given by tagOrId (see Tk_ConfigureInfo for information on the format of this list).  If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified).  If one or more option:value pairs are specified, then the command modifies the given widget option(s) to have the given value(s) in each of the items given by tagOrId;  in this case the command returns an empty string. The options and values are the same as those permissible in the create widget command when the item(s) were created; see the sections describing individual item types below for details on the legal options.

pathName :lower tagOrId ?belowThis?
     Move all of the items given by tagOrId to a new position in the display list just before the item given by belowThis. If tagOrId refers to more than one item then all are moved but the relative order of the moved items will not be changed. 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.

pathName :move tagOrId xAmount yAmount
     Move each of the items given by tagOrId in the canvas coordinate space by adding xAmount to the x-coordinate of each point associated with the item and yAmount to the y-coordinate of each point associated with the item. This command returns an empty string.

pathName :postscript ?option value option value ...?
     Generate a Postscript representation for part or all of the canvas. If the :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 option\-value argument pairs provide additional information to control the generation of Postscript.  The following options are supported:

     :colormap varName
          VarName must be the name of a global array variable that specifies a color mapping to use in the Postscript. Each element of varName must consist of Postscript code to set a particular color value (e.g. ``1.0 1.0 0.0 setrgbcolor''). When outputting color information in the Postscript, Tk checks to see if there is an element of 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 varName for a given color, then Tk uses the red, green, and blue intensities from the X color.

     :colormode mode
          Specifies how to output color information.  Mode must be either color (for full color output), gray (convert all colors to their gray-scale equivalents) or mono (convert all colors to black or white).

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

     :fontmap varName
          VarName must be the name of a global array variable that specifies a font mapping to use in the Postscript. Each element of 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 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).

     :height size
          Specifies the height of the area of the canvas to print. Defaults to the height of the canvas window.

     :pageanchor anchor
          Specifies which point of the printed area should be appear over the positioning point on the page (which is given by the :pagex and :pagey options). For example, :pageanchor n means that the top center of the printed area should be over the positioning point. Defaults to center.

     :pageheight size
          Specifies that the Postscript should be scaled in both x and y so that the printed area is size high on the Postscript page. Size consists of a floating-point number followed by c for centimeters, i for inches, m for millimeters, or p or nothing for printer's points (1/72 inch). Defaults to the height of the printed area on the screen. If both :pageheight and :pagewidth are specified then the scale factor from the later option is used (non-uniform scaling is not implemented).

     :pagewidth size
          Specifies that the Postscript should be scaled in both x and y so that the printed area is size wide on the Postscript page. Size has the same form as for :pageheight. Defaults to the width of the printed area on the screen. If both :pageheight and :pagewidth are specified then the scale factor from the later option is used (non-uniform scaling is not implemented).

     :pagex position
          Position gives the x-coordinate of the positioning point on the Postscript page, using any of the forms allowed for :pageheight. Used in conjunction with the :pagey and :pageanchor options to determine where the printed area appears on the Postscript page. Defaults to the center of the page.

     :pagey position
          Position gives the y-coordinate of the positioning point on the Postscript page, using any of the forms allowed for :pageheight. Used in conjunction with the :pagex and :pageanchor options to determine where the printed area appears on the Postscript page. Defaults to the center of the page.

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

     :width size
          Specifies the width of the area of the canvas to print. Defaults to the width of the canvas window.

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

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

pathName :raise tagOrId ?aboveThis?
     Move all of the items given by tagOrId to a new position in the display list just after the item given by aboveThis. If tagOrId refers to more than one item then all are moved but the relative order of the moved items will not be changed. 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.

pathName :scale tagOrId xOrigin yOrigin xScale yScale
     Rescale all of the items given by tagOrId in canvas coordinate space. XOrigin and yOrigin identify the origin for the scaling operation and xScale and 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 xOrigin by a factor of xScale. Similarly, each y-coordinate is adjusted to change the distance from yOrigin by a factor of yScale. This command returns an empty string.

pathName :scan option args
     This command is used to implement scanning on canvases.  It has two forms, depending on option:

     pathName :scan :mark x y
          Records x and y and the canvas's current view;  used in conjunction with later scan dragto commands. Typically this command is associated with a mouse button press in the widget and x and y are the coordinates of the mouse.  It returns an empty string.

     pathName :scan :dragto x y.
          This command computes the difference between its x and y arguments (which are typically mouse coordinates) and the x and y arguments to the last 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.

pathName :select option ?tagOrId arg?
     Manipulates the selection in one of several ways, depending on option. The command may take any of the forms described below. In all of the descriptions below, 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. Index gives a textual description of a position within tagOrId, as described in INDICES above.

     pathName :select :adjust tagOrId index
          Locate the end of the selection in tagOrId nearest to the character given by index, and adjust that end of the selection to be at index (i.e. including but not going beyond index). The other end of the selection is made the anchor point for future select to commands. If the selection isn't currently in tagOrId then this command behaves the same as the select to widget command. Returns an empty string.

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

     pathName :select :from tagOrId index
          Set the selection anchor point for the widget to be just before the character given by index in the item given by tagOrId. This command doesn't change the selection;  it just sets the fixed end of the selection for future select to commands. Returns an empty string.

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

     pathName :select :to tagOrId index
          Set the selection to consist of those characters of tagOrId between the selection anchor point and index. The new selection will include the character given by index; it will include the character given by the anchor point only if index is greater than or equal to the anchor point. The anchor point is determined by the most recent select adjust or select from command for this widget. If the selection anchor point for the widget isn't currently in tagOrId, then it is set to the same character given by index. Returns an empty string.

pathName :type tagOrId
     Returns the type of the item given by tagOrId, such as rectangle or text. If tagOrId refers to more than one item, then the type of the first item in the display list is returned. If tagOrId doesn't refer to any items at all then an empty string is returned.

pathName :xview index
     Change the view in the canvas so that the canvas position given by index appears at the left edge of the window. This command is typically used by scrollbars to scroll the canvas. Index counts in units of scroll increments (the value of the scrollIncrement option):  a value of 0 corresponds to the left edge of the scroll region (as defined by the 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.

pathName :yview index
     Change the view in the canvas so that the canvas position given by index appears at the top edge of the window. This command is typically used by scrollbars to scroll the canvas. Index counts in units of scroll increments (the value of the scrollIncrement option):  a value of 0 corresponds to the top edge of the scroll region (as defined by the scrollRegion option),  a value of 1 means one scroll unit below this, and so on.  The return value is an empty string.

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 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 create and itemconfigure widget commands. Most items don't support indexing or selection or the commands related to them, such as index and insert. Where items do support these facilities, it is noted explicitly in the descriptions below (at present, only text items provide this support).

Arc Items
---------

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

pathName :create arc x1 y1 x2 y2 ?option value option value ...?
     The arguments x1, y1, x2, and 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 option-value pairs, each of which sets one of the configuration options for the item.  These same option\-value pairs may be used in itemconfigure widget commands to change the item's configuration. The following options are supported for arcs:

     :extent degrees
          Specifies the size of the angular range occupied by the arc. The arc's range extends for degrees degrees counter-clockwise from the starting angle given by the :start option. Degrees may be negative.

     :fill color
          Fill the region of the arc with color. Color may have any of the forms accepted by Tk_GetColor. If color is an empty string (the default), then then the arc will not be filled.

     :outline color
          Color specifies a color to use for drawing the arc's outline;  it may have any of the forms accepted by Tk_GetColor. This option defaults to black.  If the arc's style is arc then this option is ignored (the section of perimeter is filled using the :fill option).  If color is specified as an empty string then no outline is drawn for the arc.

     :start degrees
          Specifies the beginning of the angular range occupied by the arc. Degrees is given in units of degrees measured counter-clockwise from the 3-o'clock position;  it may be either positive or negative.

     :stipple bitmap
          Indicates that the arc should be filled in a stipple pattern; bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the :fill option hasn't been specified then this option has no effect. If bitmap is an empty string (the default), then filling is done in a solid fashion.

     :style type
          Specifies how to draw the arc.  If type is 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 type is 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 type is 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 :outline option is ignored.

     :tags tagList
          Specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.

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

Bitmap Items
------------

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

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

     :anchor anchorPos
          AnchorPos tells how to position the bitmap relative to the positioning point for the item;  it may have any of the forms accepted by Tk_GetAnchor.  For example, if anchorPos is center then the bitmap is centered on the point;  if anchorPos is n then the bitmap will be drawn so that its top center point is at the positioning point. This option defaults to center.

     :background color
          Specifies a color to use for each of the bitmap pixels whose value is 0. Color may have any of the forms accepted by 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.

     :bitmap bitmap
          Specifies the bitmap to display in the item. Bitmap may have any of the forms accepted by Tk_GetBitmap.

     :foreground color
          Specifies a color to use for each of the bitmap pixels whose value is 1. Color may have any of the forms accepted by Tk_GetColor and defaults to black.

     :tags tagList
          Specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.

Line Items
----------

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

pathName :create line x1 y1... xn yn ?option value option value ...?

     The arguments x1 through 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 option-value pairs, each of which sets one of the configuration options for the item.  These same option\-value pairs may be used in itemconfigure widget commands to change the item's configuration. The following options are supported for lines:

     :arrow where
          Indicates whether or not arrowheads are to be drawn at one or both ends of the line. Where must have one of the values none (for no arrowheads), first (for an arrowhead at the first point of the line), last (for an arrowhead at the last point of the line), or both (for arrowheads at both ends). This option defaults to none.

     :arrowshape shape
          This option indicates how to draw arrowheads. The 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.

     :capstyle style
          Specifies the ways in which caps are to be drawn at the endpoints of the line. Style may have any of the forms accepted by Tk_GetCapStyle (butt, projecting, or round). If this option isn't specified then it defaults to butt. Where arrowheads are drawn the cap style is ignored.

     :fill color
          Color specifies a color to use for drawing the line; it may have any of the forms acceptable to Tk_GetColor.  It may also be an empty string, in which case the line will be transparent. This option defaults to black.

     :joinstyle style
          Specifies the ways in which joints are to be drawn at the vertices of the line. Style may have any of the forms accepted by Tk_GetCapStyle (bevel, miter, or round). If this option isn't specified then it defaults to miter. If the line only contains two points then this option is irrelevant.

     :smooth boolean
          Boolean must have one of the forms accepted by 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.

     :splinesteps number
          Specifies the degree of smoothness desired for curves:  each spline will be approximated with number line segments.  This option is ignored unless the :smooth option is true.

     :stipple bitmap
          Indicates that the line should be filled in a stipple pattern; bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If bitmap is an empty string (the default), then filling is done in a solid fashion.

     :tags tagList
          Specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.

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

Oval Items
----------

Items of type 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:

pathName :create oval x1 y1 x2 y2 ?option value option value ...?

     The arguments x1, y1, x2, and 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 option-value pairs, each of which sets one of the configuration options for the item.  These same option\-value pairs may be used in itemconfigure widget commands to change the item's configuration. The following options are supported for ovals:

     :fill color
          Fill the area of the oval with color. Color may have any of the forms accepted by Tk_GetColor. If color is an empty string (the default), then then the oval will not be filled.

     :outline color
          Color specifies a color to use for drawing the oval's outline;  it may have any of the forms accepted by Tk_GetColor. This option defaults to black. If color is an empty string then no outline will be drawn for the oval.

     :stipple bitmap
          Indicates that the oval should be filled in a stipple pattern; bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the :fill option hasn't been specified then this option has no effect. If bitmap is an empty string (the default), then filling is done in a solid fashion.

     :tags tagList
          Specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.

     :width outlineWidth
          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 :outline option hasn't been specified then this option has no effect. Wide outlines are drawn centered on the oval path defined by x1, y1, x2, and y2. This option defaults to 1.0.

Polygon Items
-------------

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

pathName :create polygon x1 y1 ... xn yn ?option value option value ...?

     The arguments x1 through 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 option-value pairs, each of which sets one of the configuration options for the item.  These same option\-value pairs may be used in itemconfigure widget commands to change the item's configuration. The following options are supported for polygons:

     :fill color
          Color specifies a color to use for filling the area of the polygon; it may have any of the forms acceptable to Tk_GetColor. If color is an empty string then the polygon will be transparent. This option defaults to black.

     :smooth boolean
          Boolean must have one of the forms accepted by 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.

     :splinesteps number
          Specifies the degree of smoothness desired for curves:  each spline will be approximated with number line segments.  This option is ignored unless the :smooth option is true.

     :stipple bitmap
          Indicates that the polygon should be filled in a stipple pattern; bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If bitmap is an empty string (the default), then filling is done in a solid fashion.

     :tags tagList
          Specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.

Rectangle Items
---------------

Items of type 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:

pathName :create rectangle x1 y1 x2 y2 ?option value option value ...?

     The arguments x1, y1, x2, and 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 option-value pairs, each of which sets one of the configuration options for the item.  These same option\-value pairs may be used in itemconfigure widget commands to change the item's configuration. The following options are supported for rectangles:

     :fill color
          Fill the area of the rectangle with color, which may be specified in any of the forms accepted by Tk_GetColor. If color is an empty string (the default), then then the rectangle will not be filled.

     :outline color
          Draw an outline around the edge of the rectangle in color. Color may have any of the forms accepted by Tk_GetColor. This option defaults to black. If color is an empty string then no outline will be drawn for the rectangle.

     :stipple bitmap
          Indicates that the rectangle should be filled in a stipple pattern; bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the :fill option hasn't been specified then this option has no effect. If bitmap is an empty string (the default), then filling is done in a solid fashion.

     :tags tagList
          Specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.

     :width outlineWidth
          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 :outline option hasn't been specified then this option has no effect. Wide outlines are drawn centered on the rectangular path defined by x1, y1, x2, and y2. This option defaults to 1.0.

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:  dchars, focus, icursor, index, insert, select. Text items are created with widget commands of the following form:

pathName :create text x y ?option value option value ...?

     The arguments x and 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 option-value pairs, each of which sets one of the configuration options for the item.  These same option\-value pairs may be used in itemconfigure widget commands to change the item's configuration. The following options are supported for text items:

     :anchor anchorPos
          AnchorPos tells how to position the text relative to the positioning point for the text;  it may have any of the forms accepted by Tk_GetAnchor.  For example, if anchorPos is center then the text is centered on the point;  if anchorPos is 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 center.

     :fill color
          Color specifies a color to use for filling the text characters; it may have any of the forms accepted by Tk_GetColor. If this option isn't specified then it defaults to black.

     :font fontName
          Specifies the font to use for the text item. FontName may be any string acceptable to Tk_GetFontStruct. If this option isn't specified, it defaults to a system-dependent font.

     :justify how
          Specifies how to justify the text within its bounding region. How must be one of the values left, right, or center. This option will only matter if the text is displayed as multiple lines. If the option is omitted, it defaults to left.

     :stipple bitmap
          Indicates that the text should be drawn in a stippled pattern rather than solid; bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If bitmap is an empty string (the default) then the text is drawn in a solid fashion.

     :tags tagList
          Specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.

     :text string
          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 insert and delete widget commands. This option defaults to an empty string.

     :width 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 lineLength is broken just before a space character to make the line shorter than lineLength;  the space character is treated as if it were a newline character.

Window Items
------------

Items of type 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:

     pathName :create window x y ?option value option value ...?

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

:anchor anchorPos
     AnchorPos tells how to position the window relative to the positioning point for the item;  it may have any of the forms accepted by Tk_GetAnchor.  For example, if anchorPos is center then the window is centered on the point;  if anchorPos is n then the window will be drawn so that its top center point is at the positioning point. This option defaults to center.

:height pixels
     Specifies the height to assign to the item's window. 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.

:tags tagList
     Specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.

:width pixels
     Specifies the width to assign to the item's window. 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.

:window pathName
     Specifies the window to associate with this item. The window specified by pathName must either be a child of the canvas widget or a child of some ancestor of the canvas widget. PathName may not refer to a top-level window.

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.

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.

Credits
-------

Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's ezd program.  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.

Keywords
--------

canvas, widget

menu
====

menu \- Create and manipulate menu widgets

Synopsis
--------

menu pathName ?options?

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

     activeBackground       background       disabledForeground
     activeBorderWidth      borderWidth      font
     activeForeground       cursor           foreground

See options, for more information.

Arguments for Menu
------------------

:postcommand

     Name="postCommand" Class="Command"

     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 post widget command before posting the menu.

:selector

     Name="selector" Class="Foreground"

     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.

Introduction
------------

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

A 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 :label or :bitmap option for the entry. If the  :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 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 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 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.

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

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.

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 :onvalue and :variable options for the entry);  when the entry is deselected another value (determined by the :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 selector option for the menu; otherwise the box's center is displayed in the background color for the menu.  If a :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.

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 :value and :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 selector option for the menu; otherwise the diamond's center is displayed in the background color for the menu.  If a :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.

Cascade Entries
---------------

A cascade entry is one with an associated menu (determined by the :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

menu :post x y

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

menu:unpost
     where menu is the name of the associated menu.

If a :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).

A Menu Widget's Arguments
-------------------------

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

pathName option ?arg arg ...?
     Option and the args determine the exact behavior of the command.

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 indexes and may be specified in any of the following forms:

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.

active
     Indicates the entry that is currently active.  If no entry is active then this form is equivalent to none.  This form may not be abbreviated.

last
     Indicates the bottommost entry in the menu.  If there are no entries in the menu then this form is equivalent to none. This form may not be abbreviated.

none
     Indicates ``no entry at all'';  this is used most commonly with the activate option to deactivate all the entries in the menu.  In most cases the specification of none causes nothing to happen in the widget command. This form may not be abbreviated.

@number
     In this form, number is treated as a y-coordinate in the menu's window;  the entry spanning that y-coordinate is used. For example, ``@0'' indicates the top-most entry in the window.  If number is outside the range of the window then this form is equivalent to none.

pattern
     If the index doesn't satisfy one of the above forms then this form is used.  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 Tcl_StringMatch are used.

     The following widget commands are possible for menu widgets:

pathName :activate index
     Change the state of the entry indicated by index to active and redisplay it using its active colors. Any previously-active entry is deactivated.  If index is specified as none, or if the specified entry is disabled, then the menu ends up with no active entry. Returns an empty string.

pathName :add type ?option value option value ...?
     Add a new entry to the bottom of the menu.  The new entry's type is given by type and must be one of cascade, checkbutton, command, radiobutton, or separator, or a unique abbreviation of one of the above.  If additional arguments are present, they specify any of the following options:

     :activebackground 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 activeBackground option for the overall menu is used. This option is not available for separator entries.

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

     :background 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 background option for the overall menu is used. This option is not available for separator entries.

     :bitmap value
          Specifies a bitmap to display in the menu instead of a textual label, in any of the forms accepted by Tk_GetBitmap. This option overrides the :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.

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

     :font 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 font option for the overall menu is used. This option is not available for separator entries.

     :label value
          Specifies a string to display as an identifying label in the menu entry.  Not available for separator entries.

     :menu value
          Available only for cascade entries.  Specifies the path name of the menu associated with this entry.

     :offvalue value
          Available only for check-button entries.  Specifies the value to store in the entry's associated variable when the entry is deselected.

     :onvalue value
          Available only for check-button entries.  Specifies the value to store in the entry's associated variable when the entry is selected.

     :state value
          Specifies one of three states for the entry:  normal, active, or disabled.  In normal state the entry is displayed using the foreground option for the menu and the 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 activeForeground option for the menu along with the 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 disabledForeground option for the menu and the background option from the entry. This option is not available for separator entries.

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

     :value value
          Available only for radio-button entries.  Specifies the value to store in the entry's associated variable when the entry is selected.

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

The add widget command returns an empty string.

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

pathName :delete index1 ?index2?
     Delete all of the menu entries between index1 and index2 inclusive. If index2 is omitted then it defaults to index1. Returns an empty string.

pathName :disable index
     Change the state of the entry given by index to disabled and redisplay the entry using its disabled colors. Returns an empty string. This command is obsolete and will eventually be removed; use ``pathName :entryconfigure index :state disabled'' instead.

pathName :enable index
     Change the state of the entry given by index to normal and redisplay the entry using its normal colors. Returns an empty string. This command is obsolete and will eventually be removed; use ``pathName :entryconfigure index :state normal'' instead.

pathName :entryconfigure index ?options?
     This command is similar to the configure command, except that it applies to the options for an individual entry, whereas configure applies to the options for the menu as a whole. Options may have any of the values accepted by the add widget command.  If options are specified, options are modified as indicated in the command and the command returns an empty string. If no options are specified, returns a list describing the current options for entry index (see Tk_ConfigureInfo for information on the format of this list).

pathName :index index
     Returns the numerical index corresponding to index, or none if index was specified as none.

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

pathName :post x y
     Arrange for the menu to be displayed on the screen at the root-window coordinates given by x and 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 :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 post widget command. If an error returns while executing the command, then the error is returned without posting the menu.

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

pathName :yposition index
     Returns a decimal string giving the y-coordinate within the menu window of the topmost pixel in the entry specified by index.

Default Bindings
----------------

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

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

  [2] When button 1 is released over a menu, the active entry (if any) is invoked.

  [3] A menu can be repositioned on the screen by dragging it with mouse button 2.

  [4] A number of other bindings are created to support keyboard menu traversal. See the manual entry for tk_bindForTraversal for details on these bindings.

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.

Bugs
----

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

Keywords
--------

menu, widget

scrollbar
=========

scrollbar \- Create and manipulate scrollbar widgets

Synopsis
--------

scrollbar pathName ?options?

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

     activeForeground       cursor           relief
     background             foreground       repeatDelay
     borderWidth            orient           repeatInterval

See options, for more information.

Arguments for Scrollbar
-----------------------

:command

     Name="command" Class="Command"

     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.

:width

     Name="width" Class="Width"

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

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

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

A scrollbar is a widget that displays two arrows, one at each end of the scrollbar, and a slider in the middle portion of the scrollbar.  A scrollbar is used to provide information about what is visible in an 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.

A Scrollbar Widget's Arguments
------------------------------

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

     pathName option ?arg arg ...?

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

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

pathName :get
     Returns a Tcl list containing four decimal values, which are the current totalUnits, widnowUnits, firstUnit, and lastUnit values for the scrollbar.  These are the values from the most recent set widget command on the scrollbar.

pathName :set totalUnits windowUnits firstUnit lastUnit
     This command is invoked to give the scrollbar information about the widget associated with the scrollbar.  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.  WindowUnits indicates the total number of units that can fit in the associated window at one time.  FirstUnit and 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.

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:

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.

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.

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.

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.

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 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 set widget command to change what is displayed in the scrollbar.

Keywords
--------

scrollbar, widget

checkbutton
===========

checkbutton \- Create and manipulate check-button widgets

Synopsis
--------

checkbutton pathName ?options?

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

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

See options, for more information.

Arguments for Checkbutton
-------------------------

:command

     Name="command" Class="Command"

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

:height

     Name="height" Class="Height"

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

:offvalue

     Name="offValue" Class="Value"

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

:onvalue

     Name="onValue" Class="Value"

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

:selector

     Name="selector" Class="Foreground"

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

:state

     Name="state" Class="State"

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

:variable

     Name="variable" Class="Variable"

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

:width

     Name="width" Class="Width"

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

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

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

A check button is a widget that displays a textual string or bitmap and a square called a 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 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 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 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.

A Checkbutton Widget's Arguments
--------------------------------

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

     pathName option ?arg arg ...?

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

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

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

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

pathName :deselect
     Deselect the check button:  redisplay it without a highlight in the selector and set the associated variable to its ``off'' value.

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

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

pathName :select
     Select the check button:  display it with a highlighted selector and set the associated variable to its ``on'' value.

pathName :toggle
     Toggle the selection state of the button, redisplaying it and modifying its associated variable to reflect the new state.

Bindings
--------

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

  [1] The check button activates whenever the mouse passes over it and deactivates whenever the mouse leaves the check button.

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

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

If the check button's state is 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.

Keywords
--------

check button, widget

menubutton
==========

menubutton \- Create and manipulate menubutton widgets

Synopsis
--------

menubutton pathName ?options?

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

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

See options, for more information.

Arguments for Menubutton
------------------------

:height

     Name="height" Class="Height"

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

:menu

     Name="menu" Class="MenuName"

     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.

:state

     Name="state" Class="State"

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

:width

     Name="width" Class="Width"

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

Introduction
------------

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

A 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 tk-menu-bar procedure is used to set up menu bars for scanning; see that procedure for more details.

A Menubutton Widget's Arguments
-------------------------------

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

     pathName option ?arg arg ...?

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

pathName :activate
     Change the menu button's state to 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 disabled. This command is obsolete and will eventually be removed; use ``pathName :configure :state active'' instead.

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

pathName :deactivate
     Change the menu button's state to 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 disabled. This command is obsolete and will eventually be removed; use ``pathName :configure :state normal'' instead.

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

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

  [1] A menu button activates whenever the mouse passes over it and deactivates whenever the mouse leaves it.

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

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

  [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 tk-menu-bar.

  [5] Menubuttons may also be posted by typing characters on the keyboard. See the manual entry for tk-menu-bar for full details on keyboard menu traversal.

  [6] If mouse button 2 is pressed over a menu button then the associated menu is posted and also 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.

If the menu button's state is 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.

Keywords
--------

menubutton, widget

text
====

text \- Create and manipulate text widgets

Synopsis
--------

text pathName ?options?

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

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

See options, for more information.

Arguments for Text
------------------

:height

     Name="height" Class="Height"

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

:state

     Name="state" Class="State"

     Specifies one of two states for the text:  normal or 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.

:width

     Name="width" Class="Width"

     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.

:wrap

     Name="wrap" Class="Wrap"

     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 none or char or word. A wrap mode of 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 char mode a screen line break may occur after any character; in word mode a line break will only be made at word boundaries.

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

The text command creates a new window (given by the 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 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.

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

base modifier modifier modifier ...

Where base gives a starting point and the modifiers adjust the index from the starting point (e.g. move forward or backward one character).  Every index must contain a base, but the modifiers are optional.

The base for an index must have one of the following forms:

line.char
     Indicates char'th character on line 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.

@x,y
     Indicates the character that covers the pixel whose x and y coordinates within the text's window are x and y.

end
     Indicates the last character in the text, which is always a newline character.

mark
     Indicates the character just after the mark whose name is mark.

tag.first
     Indicates the first character in the text that has been tagged with tag. This form generates an error if no characters are currently tagged with tag.

tag.last
     Indicates the character just after the last one in the text that has been tagged with tag. This form generates an error if no characters are currently tagged with tag.

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

+ count chars
     Adjust the index forward by count characters, moving to later lines in the text if necessary.  If there are fewer than 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 count are optional.

- count chars
     Adjust the index backward by count characters, moving to earlier lines in the text if necessary.  If there are fewer than 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 count are optional.

+ count lines
     Adjust the index forward by count lines, retaining the same character position within the line.  If there are fewer than 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 count are optional.

- count lines
     Adjust the index backward by count lines, retaining the same character position within the line.  If there are fewer than 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 count are optional.

linestart
     Adjust the index to refer to the first character on the line.

lineend
     Adjust the index to refer to the last character on the line (the newline).

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.

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.

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.

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 ``pathName :tag :raise'' and ``pathName :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 background, font, and foreground options for the text widget. However, display options may be associated with individual tags using the ``pathName :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:

:background color
     Color specifies the background color to use for characters associated with the tag. It may have any of the forms accepted by Tk_GetColor.

:bgstipple bitmap
     Bitmap specifies a bitmap that is used as a stipple pattern for the background. It may have any of the forms accepted by Tk_GetBitmap. If bitmap hasn't been specified, or if it is specified as an empty string, then a solid fill will be used for the background.

:borderwidth pixels
     Pixels specifies the width of a 3-D border to draw around the background. It may have any of the forms accepted by Tk_GetPixels. This option is used in conjunction with the :relief option to give a 3-D appearance to the background for characters; it is ignored unless the :background option has been set for the tag.

:fgstipple bitmap
     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 Tk_GetBitmap. If bitmap hasn't been specified, or if it is specified as an empty string, then a solid fill will be used.

:font fontName
     FontName is the name of a font to use for drawing characters. It may have any of the forms accepted by Tk_GetFontStruct.

:foreground color
     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 Tk_GetColor.

:relief relief
     \fIRelief specifies the 3-D relief to use for drawing backgrounds, in any of the forms accepted by Tk_GetRelief. This option is used in conjunction with the :borderwidth option to give a 3-D appearance to the background for characters; it is ignored unless the :background option has been set for the tag.

:underline boolean
     Boolean specifies whether or not to draw an underline underneath characters. It may have any of the forms accepted by 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 tag bind widget command below.

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

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 ``pathName :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 insert is associated with the insertion cursor, as described under THE INSERTION CURSOR below. Second, the mark 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:  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.

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.

The Selection
-------------

Text widgets support the standard X selection. Selection support is implemented via tags. If the exportSelection option for the text widget is true then the sel tag will be associated with the selection:

  * [1] Whenever characters are tagged with sel the text widget will claim ownership of the selection.

  * [2] Attempts to retrieve the selection will be serviced by the text widget, returning all the charaters with the sel tag.

  * [3] If the selection is claimed away by another application or by another window within this application, then the sel tag will be removed from all characters in the text.

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

The Insertion Cursor
--------------------

The mark named 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 ``pathName :mark unset'' widget command. The 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.

A Text Widget's Arguments
-------------------------

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

     pathName option ?arg arg ...?

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

pathName :compare index1 op index2
     Compares the indices given by index1 and index2 according to the relational operator given by op, and returns 1 if the relationship is satisfied and 0 if it isn't. Op must be one of the operators <, <=, ==, >=, >, or !=. If op is == then 1 is returned if the two indices refer to the same character, if op is < then 1 is returned if index1 refers to an earlier character in the text than index2, and so on.

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

pathName :debug ?boolean?
     If 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 boolean has a false value then the debugging checks will be turned off. In either case the command returns an empty string. If boolean is not specified then the command returns on or 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.

pathName :delete index1 ?index2?
     Delete a range of characters from the text. If both index1 and index2 are specified, then delete all the characters starting with the one given by index1 and stopping just before index2 (i.e. the character at index2 is not deleted). If index2 doesn't specify a position later in the text than index1 then no characters are deleted. If index2 isn't specified then the single character at 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.

pathName :get index1 ?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 index1 and ending just before the one whose index is index2 (the character at index2 will not be returned). If index2 is omitted then the single character at index1 is returned. If there are no characters in the specified range (e.g. index1 is past the end of the file or index2 is less than or equal to index1) then an empty string is returned.

pathName :index index
     Returns the position corresponding to index in the form line.char where line is the line number and char is the character number. Index may have any of the forms described under INDICES above.

pathName :insert \fIindex chars
     Inserts chars into the text just before the character at index and returns an empty string. It is not possible to insert characters after the last newline of the text.

pathName :mark option ?arg arg ...?
     This command is used to manipulate marks.  The exact behavior of the command depends on the option argument that follows the mark argument.  The following forms of the command are currently supported:

     pathName :mark :names
          Returns a list whose elements are the names of all the marks that are currently set.

     pathName :mark :set markName index
          Sets the mark named markName to a position just before the character at index. If 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.

     pathName :mark :unset markName ?markName markName ...?
          Remove the mark corresponding to each of the markName arguments. The removed marks will not be usable in indices and will not be returned by future calls to ``pathName :mark names''. This command returns an empty string.

pathName :scan option args
     This command is used to implement scanning on texts.  It has two forms, depending on option:

     pathName :scan :mark y
          Records y and the current view in the text window;  used in conjunction with later scan dragto commands.  Typically this command is associated with a mouse button press in the widget.  It returns an empty string.

     pathName :scan :dragto y
          This command computes the difference between its y argument and the y argument to the last 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.

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

     pathName :tag :add tagName index1 ?index2?
          Associate the tag tagName with all of the characters starting with index1 and ending just before index2 (the character at index2 isn't tagged). If index2 is omitted then the single character at index1 is tagged. If there are no characters in the specified range (e.g. index1 is past the end of the file or index2 is less than or equal to index1) then the command has no effect. This command returns an empty string.

     pathName :tag :bind tagName ?sequence? ?command?
          This command associates command with the tag given by tagName. Whenever the event sequence given by sequence occurs for a character that has been tagged with tagName, the command will be invoked. This widget command is similar to the bind command except that it operates on characters in a text rather than entire widgets. See the bind manual entry for complete details on the syntax of sequence and the substitutions performed on command before invoking it. If all arguments are specified then a new binding is created, replacing any existing binding for the same sequence and tagName (if the first character of command is ``+'' then command augments an existing binding rather than replacing it). In this case the return value is an empty string. If command is omitted then the command returns the command associated with tagName and sequence (an error occurs if there is no such binding). If both command and sequence are omitted then the command returns a list of all the sequences for which bindings have been defined for tagName.

          The only events for which bindings may be specified are those related to the mouse and keyboard, such as Enter, Leave, ButtonPress, Motion, and KeyPress. Event bindings for a text widget use the current mark described under MARKS above. Enter events trigger for a character when it becomes the current character (i.e. the current mark moves to just in front of that character). Leave events trigger for a character when it ceases to be the current item (i.e. the current mark moves away from that character, or the character is deleted). These events are different than Enter and 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 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.

     pathName :tag :configure tagName ?option? ?value? ?option value ...?
          This command is similar to the configure widget command except that it modifies options associated with the tag given by tagName instead of modifying options for the overall text widget. If no option is specified, the command returns a list describing all of the available options for tagName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option:value pairs are specified, then the command modifies the given option(s) to have the given value(s) in tagName; in this case the command returns an empty string. See TAGS above for details on the options available for tags.

     pathName :tag :delete tagName ?tagName ...?
          Deletes all tag information for each of the 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.

     pathName :tag :lower tagName ?belowThis?
          Changes the priority of tag tagName so that it is just lower in priority than the tag whose name is belowThis. If belowThis is omitted, then tagName's priority is changed to make it lowest priority of all tags.

     pathName :tag :names ?index?
          Returns a list whose elements are the names of all the tags that are active at the character position given by index. If 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 ``pathName :tag'' widget command but haven't been deleted by a ``pathName :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.

     pathName :tag :nextrange tagName index1 ?index2?
          This command searches the text for a range of characters tagged with tagName where the first character of the range is no earlier than the character at index1 and no later than the character just before index2 (a range starting at 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 index2 is not given then it defaults to the end of the text.

     pathName :tag :raise tagName ?aboveThis?
          Changes the priority of tag tagName so that it is just higher in priority than the tag whose name is aboveThis. If aboveThis is omitted, then tagName's priority is changed to make it highest priority of all tags.

     pathName :tag :ranges tagName
          Returns a list describing all of the ranges of text that have been tagged with 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 tag then an empty string is returned.

     pathName :tag :remove tagName index1 ?index2?
          Remove the tag tagName from all of the characters starting at index1 and ending just before index2 (the character at index2 isn't affected). If index2 is omitted then the single character at index1 is untagged. If there are no characters in the specified range (e.g. index1 is past the end of the file or index2 is less than or equal to index1) then the command has no effect. This command returns an empty string.

pathName :yview ?:pickplace? what
     This command changes the view in the widget's window so that the line given by what is visible in the window. 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 :pickplace option isn't specified then what will appear at the top of the window. If :pickplace is specified then the widget chooses where what appears in the window:

       [1] If what is already visible somewhere in the window then the command does nothing.

       [2] If what is only a few lines off-screen above the window then it will be positioned at the top of the window.

       [3] If what is only a few lines off-screen below the window then it will be positioned at the bottom of the window.

       [4] Otherwise, what will be centered in the window.

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

Bindings
--------

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

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

  [2] Dragging with mouse button 1 strokes out a selection between the insertion cursor and the character under the mouse.

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

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

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

  [6] The view in the text can be adjusted by dragging with mouse button 2.

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

  [8] Control+h and the Backspace and Delete keys erase the character just before the insertion cursor.

  [9] Control+v inserts the current selection just before the insertion cursor.

  [10] Control+d deletes the selected characters;  an error occurs if the selection is not in this widget.

If the text is disabled using the 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.

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

Keywords
--------

text, widget

entry
=====

entry \- Create and manipulate entry widgets

Synopsis
--------

entry pathName ?options?

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

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

See options, for more information.

Arguments for Entry
-------------------

:state

     Name="state" Class="State"

     Specifies one of two states for the entry:  normal or 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.

:width

     Name="width" Class="Width"

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

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

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

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 exportSelection option), then it will observe the standard X11 protocols for handling the selection;  entry selections are available as type STRING. Entries also observe the standard Tk rules for dealing with the input focus.  When an entry has the input focus it displays an 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 scrollCommand mechanism for interacting with scrollbars (see the description of the scrollCommand option for details).  They also support scanning, as described below.

A Entry Widget's Arguments
--------------------------

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

     pathName option ?arg arg ...?

Option and the args determine the exact behavior of the command.

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:

number
     Specifies the character as a numerical index, where 0 corresponds to the first character in the string.

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.

insert
     Indicates the character adjacent to and immediately following the insertion cursor.

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.

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.

@number
     In this form, number is treated as an x-coordinate in the entry's window;  the character spanning that x-coordinate is used. For example, ``@0'' indicates the left-most character in the window.

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

The following commands are possible for entry widgets:

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

pathName :delete first ?last?
     Delete one or more elements of the entry.  First and last are indices of of the first and last characters in the range to be deleted.   If last isn't specified it defaults to first, i.e. a single character is deleted.  This command returns an empty string.

pathName :get
     Returns the entry's string.

pathName :icursor index
     Arrange for the insertion cursor to be displayed just before the character given by index.  Returns an empty string.

pathName :index index
     Returns the numerical index corresponding to index.

pathName :insert index string
     Insert the characters of string just before the character indicated by index.  Returns an empty string.

pathName :scan option args
     This command is used to implement scanning on entries.  It has two forms, depending on option:

     pathName :scan :mark x
          Records x and the current view in the entry window;  used in conjunction with later scan dragto commands.  Typically this command is associated with a mouse button press in the widget.  It returns an empty string.

     pathName :scan :dragto x
          This command computes the difference between its x argument and the x argument to the last 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.

pathName :select option arg
     This command is used to adjust the selection within an entry.  It has several forms, depending on option:

     pathName :select :adjust index
          Locate the end of the selection nearest to the character given by index, and adjust that end of the selection to be at index (i.e including but not going beyond index).  The other end of the selection is made the anchor point for future select to commands.  If the selection isn't currently in the entry, then a new selection is created to include the characters between index and the most recent selection anchor point, inclusive. Returns an empty string.

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

     pathName :select :from index
          Set the selection anchor point to just before the character given by index.  Doesn't change the selection. Returns an empty string.

     pathName :select :to index
          Set the selection to consist of the elements from the anchor point to element index, inclusive.  The anchor point is determined by the most recent select from or 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.

pathName :view index
     Adjust the view in the entry so that element index is at the left edge of the window.  Returns an empty string.

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

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

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

  [2] Dragging with mouse button 1 strokes out a selection between the insertion cursor and the character under the mouse.

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

  [4] The view in the entry can be adjusted by dragging with mouse button 2.

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

  [6] Control-h and the Backspace and Delete keys erase the character just before the insertion cursor.

  [7] Control-w erases the word just before the insertion cursor.

  [8] Control-u clears the entry to an empty string.

  [9] Control-v inserts the current selection just before the insertion cursor.

  [10] Control-d deletes the selected characters;  an error occurs if the selection is not in this widget.

If the entry is disabled using the 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.

Keywords
--------

entry, widget

message
=======

message \- Create and manipulate message widgets

Synopsis
--------

message pathName ?options?

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

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

See options, for more information.

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

:aspect

     Name="aspect" Class="Aspect"

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

:justify

     Name="justify" Class="Justify"

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

:width

     Name="width" Class="Width"

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

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

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

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

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

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

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

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

     pathName option ?arg arg ...?

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

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

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

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

Bugs
----

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

Keywords
--------

message, widget

frame
=====

frame \- Create and manipulate frame widgets

Synopsis
--------

frame pathName ?:class className? ?options?

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

     background             cursor             relief
     borderWidth            geometry

See options, for more information.

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

:height

     Name="height" Class="Height"

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

:width

     Name="width" Class="Width"

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

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

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

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

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

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

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

     pathName option ?arg arg ...?

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

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

Bindings
--------

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

Keywords
--------

frame, widget

label
=====

label \- Create and manipulate label widgets

Synopsis
--------

label pathName ?options?

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

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

See options, for more information.

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

:height

     Name="height" Class="Height"

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

:width

     Name="width" Class="Width"

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

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

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

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

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

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

     pathName option ?arg arg ...?

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

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

Bindings
--------

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

Keywords
--------

label, widget

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

radiobutton \- Create and manipulate radio-button widgets

Synopsis
--------

radiobutton pathName ?options?

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

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

See options, for more information.

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

:command

     Name="command" Class="Command"

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

:height

     Name="height" Class="Height"

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

:selector

     Name="selector" Class="Foreground"

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

:state

     Name="state" Class="State"

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

:value

     Name="value" Class="Value"

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

:variable

     Name="variable" Class="Variable"

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

:width

     Name="width" Class="Width"

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

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

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

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

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

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

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

     pathName option ?arg arg ...?

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

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

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

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

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

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

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

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

Bindings
--------

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

  [1] The radio button activates whenever the mouse passes over it and deactivates whenever the mouse leaves the radio button.

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

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

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

Keywords
--------

radio button, widget

toplevel
========

toplevel \- Create and manipulate toplevel widgets

Synopsis
--------

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

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

     background                  geometry
     borderWidth                 relief

See options, for more information.

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

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

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

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

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

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

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

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

     pathName option ?arg arg ...?

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

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

Bindings
--------

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

Keywords
--------

toplevel, widget