NAME
       menubutton - Create and manipulate menubutton widgets

SYNOPSIS
       menubutton 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:-direction
       Database Name:  direction
       Database Class: Height

              Specifies where the menu is going to be  popup  up.
              above  tries  to pop the menu above the menubutton.
              below tries to pop the menu below  the  menubutton.
              left  tries  to  pop  the  menu  to the left of the
              menubutton. right tries to  pop  the  menu  to  the
              right  of  the  menu  button.  flush  pops the menu
              directly over the menubutton.

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

              Specifies a desired height for the menubutton.   If
              an  image  or  bitmap  is  being  displayed  in the
              menubutton 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 menubutton's desired height is com-
              puted from the size of the image or bitmap or  text
              being displayed in it.

       Command-Line Name:-indicatoron
       Database Name:  indicatorOn
       Database Class: IndicatorOn

              The value must be a proper boolean value.  If it is
              true then a small indicator rectangle will be  dis-
              played  on the right side of the menubutton and the
              default menu bindings will treat this as an  option
              menubutton.   If  false  then  no indicator will be
              displayed.
       Command-Line Name:-menu
       Database Name:  menu
       Database Class: MenuName

              Specifies the path name of the menu associated with
              this  menubutton.   The menu must be a child of the
              menubutton.

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

              Specifies one of three states for  the  menubutton:
              normal,  active,  or disabled.  In normal state the
              menubutton is displayed using  the  foreground  and
              background  options.  The active state is typically
              used when the pointer is over the  menubutton.   In
              active  state the menubutton is displayed using the
              activeForeground  and   activeBackground   options.
              Disabled  state means that the menubutton 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 dis-
              played.

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

              Specifies a desired width for the  menubutton.   If
              an  image  or  bitmap  is  being  displayed  in the
              menubutton 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  menubutton's desired width is com-
              puted from the size of the image or 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,
       bitmap, or image and is associated with a menu widget.  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 characters may optionally be under-
       lined using the underline option.  In normal usage, press-
       ing mouse button 1 over the menubutton causes the  associ-
       ated 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.

       There  are  several  interactions  between menubuttons and
       menus;  see the menu manual entry for information on vari-
       ous menu configurations, such as pulldown menus and option
       menus.


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 cget option
              Returns  the  current  value  of  the configuration
              option given by option.  Option may have any of the
              values accepted by the menubutton 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 menubutton command.


DEFAULT BINDINGS
       Tk automatically creates class  bindings  for  menubuttons
       that give them the following default behavior:

       [1]    A  menubutton  activates  whenever the mouse passes
              over it and deactivates whenever the  mouse  leaves
              it.

       [2]    Pressing mouse button 1 over a menubutton posts the
              menubutton: its relief changes to  raised  and  its
              associated menu is posted under the menubutton.  If
              the mouse is dragged down into the  menu  with  the
              button  still down, and if the mouse button is then
              released over an entry in the menu, the  menubutton
              is unposted and the menu entry is invoked.

       [3]    If  button  1 is pressed over a menubutton and then
              released over that menubutton, the menubutton stays
              posted:  you can still move the mouse over the menu
              and click button 1 on an entry to invoke it.   Once
              a  menu  entry  has  been  invoked,  the menubutton
              unposts itself.

       [4]    If button 1 is pressed over a menubutton  and  then
              dragged  over  some  other menubutton, the original
              menubutton unposts itself and  the  new  menubutton
              posts.

       [5]    If  button  1  is  pressed  over  a  menubutton and
              released  outside  any  menubutton  or  menu,   the
              menubutton unposts without invoking any menu entry.

       [6]    When a menubutton is posted,  its  associated  menu
              claims  the input focus to allow keyboard traversal
              of the menu and its submenus.  See the menu  manual
              entry for details on these bindings.

       [7]    If  the  underline  option has been specified for a
              menubutton then keyboard traversal may be  used  to
              post  the  menubutton: Alt+x, where x is the under-
              lined character (or its  lower-case  or  upper-case
              equivalent),  may  be typed in any window under the
              menubutton's toplevel to post the menubutton.

       [8]    The F10 key may be typed in any window to post  the
              first  menubutton  under  its  toplevel window that
              isn't disabled.

       [9]    If a menubutton has the input focus, the space  and
              return keys post the menubutton.
       If  the  menubutton's  state  is disabled then none of the
       above actions occur:  the menubutton  is  completely  non-
       responsive.

       The behavior of menubuttons can be changed by defining new
       bindings for individual widgets or by redefining the class
       bindings.


KEYWORDS
       menubutton, widget
