NAME
       button - Create and manipulate button widgets

SYNOPSIS
       button pathName ?options?

STANDARD OPTIONS
       -activebackground              -cursor         -highlightthickness-takefocus
       -activeforeground              -disabledforeground-image-text
       -anchor         -font          -justify        -textvariable
       -background     -foreground    -padx           -underline
       -bitmap         -highlightbackground           -pady-wraplength
       -borderwidth    -highlightcolor                -relief

       See  the  options manual entry for details on the standard
       options.

WIDGET-SPECIFIC OPTIONS
       Command-Line Name:-command
       Database Name:  command
       Database Class: 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.

       Command-Line Name:-default
       Database Name:  default
       Database Class: Default

              Specifies one of three states for the default ring:
              normal,  active, or disabled.  In active state, the
              button is drawn with the platform specific  appear-
              ance  for  a  default button.  In normal state, the
              button is drawn with the platform specific  appear-
              ance for a non-default button, leaving enough space
              to draw the default button appearance.  The  normal
              and  active  states  will  result in buttons of the
              same size.  In disabled state, the button is  drawn
              with  the  non-default  button  appearance  without
              leaving space for the default appearance.  The dis-
              abled state may result in a smaller button than the
              active state.  ring.

       Command-Line Name:-height
       Database Name:  height
       Database Class: Height

              Specifies a desired height for the button.   If  an
              image  or  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 image or bitmap or text being displayed
              in it.

       Command-Line Name:-state
       Database Name:  state
       Database Class: 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 should be  insensitive:
              the  default  bindings  will refuse to activate the
              widget and will ignore mouse  button  presses.   In
              this  state  the  disabledForeground and background
              options determine how the button is displayed.

       Command-Line Name:-width
       Database Name:  width
       Database Class: Width

              Specifies a desired width for the  button.   If  an
              image  or  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 image or 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,
       bitmap or image.  If text is displayed, it must all be  in
       a  single  font,  but  it can occupy multiple lines on the
       screen (if it contains  newlines  or  if  wrapping  occurs
       because  of  the wrapLength option) and one of the charac-
       ters may optionally  be  underlined  using  the  underline
       option.   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 cget option
              Returns  the  current  value  of  the configuration
              option given by option.  Option may have any of the
              values accepted by the button command.

       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 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 default behavior:

       [1]    A button activates whenever the mouse  passes  over
              it  and  deactivates  whenever the mouse leaves the
              button.  Under Windows, this binding is only active
              when  mouse button 1 has been pressed over the but-
              ton.

       [2]    A 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 a 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.

       [4]    When  a  button  has the input focus, the space key
              causes the button to be invoked.

       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
