1mNAME0m
       menubutton - Create and manipulate menubutton widgets

1mSYNOPSIS0m
       1mmenubutton 4m22mpathName24m ?4moptions24m?

1mSTANDARD OPTIONS0m
       1m-activebackground     -cursor              -highlightthickness-takefocus0m
       1m-activeforeground     -disabledforeground  -image-text0m
       1m-anchor               -font                -justify-textvariable0m
       1m-background           -foreground          -padx-underline0m
       1m-bitmap               -highlightbackground -pady-wraplength0m
       1m-borderwidth          -highlightcolor      -relief0m

       See the 1moptions 22mmanual entry for details on the standard options.

1mWIDGET-SPECIFIC OPTIONS0m
       Command-Line Name:1m-direction0m
       Database Name:  1mdirection0m
       Database Class: 1mHeight0m

              Specifies where the menu is going to be popup up. 1mabove 22mtries to
              pop the menu above the menubutton. 1mbelow 22mtries to pop  the  menu
              below  the menubutton. 1mleft 22mtries to pop the menu to the left of
              the menubutton. 1mright 22mtries to pop the menu to the right of  the
              menu button. 1mflush 22mpops the menu directly over the menubutton.

       Command-Line Name:1m-height0m
       Database Name:  1mheight0m
       Database Class: 1mHeight0m

              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 1mTk_GetPixels22m);
              for text it is in lines of text.  If this  option  isn't  speci-
              fied,  the menubutton's desired height is computed from the size
              of the image or bitmap or text being displayed in it.

       Command-Line Name:1m-indicatoron0m
       Database Name:  1mindicatorOn0m
       Database Class: 1mIndicatorOn0m

              The value must be a proper boolean value.  If it is true then  a
              small indicator rectangle will be displayed 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 dis-
              played.

       Command-Line Name:1m-menu0m
       Database Name:  1mmenu0m
       Database Class: 1mMenuName0m

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

       Command-Line Name:1m-state0m
       Database Name:  1mstate0m
       Database Class: 1mState0m

              Specifies  one  of  three  states  for  the menubutton:  1mnormal22m,
              1mactive22m, or 1mdisabled22m.  In normal state  the  menubutton  is  dis-
              played  using the 1mforeground 22mand 1mbackground 22moptions.  The active
              state is typically used when the pointer is over the menubutton.
              In  active  state  the menubutton is displayed using the 1mactive-0m
              1mForeground 22mand 1mactiveBackground 22moptions.  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 1mdisabledForeground 22mand 1mbackground0m
              options determine how the button is displayed.

       Command-Line Name:1m-width0m
       Database Name:  1mwidth0m
       Database Class: 1mWidth0m

              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 1mTk_GetPixels22m);
              for  text  it is in characters.  If this option isn't specified,
              the menubutton's desired width is computed from the size of  the
              image or bitmap or text being displayed in it.


1mINTRODUCTION0m
       The  1mmenubutton  22mcommand  creates  a  new window (given by the 4mpathName0m
       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 1mmenubutton 22mcommand returns its
       4mpathName24m argument.  At the time this command is invoked, there must not
       exist a window named 4mpathName24m, but 4mpathName24m'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
       1mwrapLength  22moption)  and one of the characters may optionally be under-
       lined using the 1munderline 22moption.  In normal usage, pressing mouse but-
       ton  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.

       There are several interactions between menubuttons and menus;  see  the
       1mmenu  22mmanual entry for information on various menu configurations, such
       as pulldown menus and option menus.


1mWIDGET COMMAND0m
       The 1mmenubutton 22mcommand creates a new Tcl command whose  name  is  4mpath-0m
       4mName24m.   This  command  may  be used to invoke various operations on the
       widget.  It has the following general form:
              4mpathName24m 4moption24m ?4marg24m 4marg24m 4m...24m?
       4mOption24m and the 4marg24ms determine the exact behavior of the  command.   The
       following commands are possible for menubutton widgets:

       4mpathName24m 1mcget 4m22moption0m
              Returns  the  current value of the configuration option given by
              4moption24m.  4mOption24m may have any  of  the  values  accepted  by  the
              1mmenubutton 22mcommand.

       4mpathName24m 1mconfigure 22m?4moption24m? ?4mvalue24m 4moption24m 4mvalue24m 4m...24m?
              Query  or modify the configuration options of the widget.  If no
              4moption24m is specified, returns a list describing all of the avail-
              able  options for 4mpathName24m (see 1mTk_ConfigureInfo 22mfor information
              on the format of this list).  If 4moption24m  is  specified  with  no
              4mvalue24m,  then the command returns a list describing the one named
              option (this list will be identical to the corresponding sublist
              of  the  value  returned  if no 4moption24m is specified).  If one or
              more 4moption-value24m 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.  4mOption24m may  have  any
              of the values accepted by the 1mmenubutton 22mcommand.


1mDEFAULT BINDINGS0m
       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 sub-
              menus.  See the 1mmenu 22mmanual entry for details on these bindings.

       [7]    If the 1munderline 22moption has been specified for a menubutton then
              keyboard traversal may be used to post  the  menubutton:  Alt+4mx24m,
              where 4mx24m is the underlined character (or its lower-case or upper-
              case equivalent), may be typed in any window under the  menubut-
              ton'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 1mdisabled 22mthen 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.


1mKEYWORDS0m
