NAME
       menubutton - Create and manipulate menubutton widgets

SYNOPSIS
       menubutton pathName ?options?

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

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

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

       Name:           menu
       Class:          MenuName
       Command-Line Switch:-menu

              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 opera-
              tion to work via the mouse.

       Name:           state
       Class:          State
       Command-Line Switch:-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 insen-
              sitive:  it doesn't activate and doesn't respond to
              mouse button presses.  In this state the  disabled-
              Foreground and background options determine how the
              button is displayed.
       Name:           width
       Class:          Width
       Command-Line Switch:-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 path-
       Name'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_menuBar proce-
       dure is used to set up menu bars for  scanning;  see  that
       procedure for more details.


WIDGET COMMAND
       The  menubutton  command  creates  a new Tcl command whose
       name is pathName.  This command may be used to invoke var-
       ious  operations on the widget.  It has the following gen-
       eral form:

              pathName option ?arg arg ...?
       Option and the args determine the exact  behavior  of  the
       command.  The following commands are possible for menubut-
       ton widgets:
       pathName activate
              Change the menu button's state to active and redis-
              play  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 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 menubutton command.

       pathName deactivate
              Change the menu button's state to normal and redis-
              play  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  obso-
              lete 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 when-
              ever mouse button 1 is pressed  over  it,  and  the
              relief  is restored to its original value when but-
              ton 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 but-
              ton.  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_menuBar.

       [5]    Menubuttons may also be posted by typing characters
              on  the  keyboard.   See  the  manual   entry   for
              tk_menuBar   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 asso-
              ciated 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
