


button(n)              Tk Built-In Commands             button(n)


NAME
       button - Create and manipulate button widgets

SYNOPSIS
       (button                      widget-name                     ?options?)
       :activebackground   :cursor   :highlightthickness :takefocus
       :activeforeground   :disabledforeground :image    :text
       :anchor   :font     :justify  :textvariable
       :background    :foreground    :padx     :underline
       :bitmap   :highlightbackground     :pady     :wraplength
       :borderwidth   :highlightcolor     :relief

WIDGET-SPECIFIC OPTIONS
       Specifies a STk procedure to associate with the button.  This procedure
       is typically invoked when mouse button 1 is released  over  the  button
       window.   OP  :default  default  Default 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 appearance
       for a default button.  In normal state, the button is  drawn  with  the
       platform  specific  appearance 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 disabled state may result in a
       smaller button than the active state.  ring.  Specifies the environment
       in  which  the  :textvariable  must be taken.  By default, the value of
       this option is the STk global environment.  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.  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  should
       be  insensitive:  the default bindings will refuse to activate the wid-
       get and will ignore mouse button presses.  In this state the  disabled-
       Foreground  and  background  options  determine  how the button is dis-
       played.  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  procedure  creates  a new window (given by the widget-name
       argument) and makes it  into  a  button  widget.   Additional  options,
       described  above,  may  be  specified  on  the procedure line or in the
       option database to configure aspects of the button such as its  colors,
       font,  text,  and  initial  relief.   The  button procedure returns its



STk                            4.0                              1





button(n)              Tk Built-In Commands             button(n)


       widget-name argument.  At the time this  procedure  is  invoked,  there
       must  not  exist  a  window named widget-name, but widget-name'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 char-
       acters may optionally be underlined using the underline option.  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 STk procedure
       specified in the :command option is invoked.


WIDGET PROCEDURE
       The  button  procedure  creates  a new STk procedure whose name is wid-
       get-name.  This procedure may be used to invoke various  operations  on
       the  widget.   It  has  the following general form: (widget-name option
       ?arg arg ...?)  Option and the args determine the exact behavior of the
       procedure.  The following procedures are possible for button widgets:

       (widget-name 'cget option)
              Returns  the  current value of the configuration option given by
              option.  Option may have any of the values accepted by the  but-
              ton procedure.

       (widget-name '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 avail-
              able  options for widget-name (see Tk_ConfigureInfo for informa-
              tion on the format of this list).  If option is  specified  with
              no  value,  then the procedure 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 procedure
              modifies  the given widget option(s) to have the given value(s);
              in this case the procedure returns an empty string.  Option  may
              have any of the values accepted by the button procedure.

       (widget-name 'flash)
              Flash the button.  This is accomplished by redisplaying the but-
              ton 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 procedure was invoked.  This proce-
              dure is ignored if the button's state is disabled.

       (widget-name 'invoke)
              Invoke the STk procedure associated with the button, if there is
              one (return value is undefined).  This procedure is  ignored  if
              the button's state is disabled.





STk                            4.0                              2





button(n)              Tk Built-In Commands             button(n)


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 deacti-
              vates whenever the mouse leaves the button.  Under Windows, this
              binding is only active when mouse button 1 has been pressed over
              the button.

       [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 button 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 invo-
              cation occurs.

       [4]    When a button has the input focus, the space key causes the but-
              ton 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.


SEE ALSO
       checkbutton, radiobutton



























STk                            4.0                              3


