NAME
       button - Create and manipulate button widgets

SYNOPSIS
       button pathName ?options?

STANDARD OPTIONS
       activeBackground               bitmap          fontrelief
       activeForeground               borderWidth     foregroundtext
       anchor          cursor         padX            textVariable
       background      disabledForeground             padY

       See  the ``options'' manual entry for details on the stan-
       dard options.

WIDGET-SPECIFIC OPTIONS
       Name:           command
       Class:          Command
       Command-Line Switch:-command

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

       Name:           height
       Class:          Height
       Command-Line Switch:-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.

       Name:           state
       Class:          State
       Command-Line Switch:-state

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

       Name:           width
       Class:          Width
       Command-Line Switch:-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  differ-
       ent 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.


WIDGET COMMAND
       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 back-
              ground colors instead of normal colors.  This  com-
              mand  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  path-
              Name  (see  Tk_ConfigureInfo for information on the
              format of this list).  If option is specified  with
              no  value, then the command returns a list describ-
              ing the one named option (this list will be identi-
              cal  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  back-
              ground colors.  This command is ignored if the but-
              ton's state is disabled.  This command is  obsolete
              and will eventually be removed; use ``pathName con-
              figure -state normal'' instead.

       pathName flash
              Flash the button.  This is accomplished  by  redis-
              playing   the  button  several  times,  alternating
              between active and normal colors.  At  the  end  of
              the  flash  the  button  is  left  in the same nor-
              mal/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  but-
              ton 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  invoca-
              tion 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
