   This is a Texinfo GCL TK Manual

   Copyright 1994 William F. Schelter

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