MENUBUTTON(9)                                       MENUBUTTON(9)

     NAME
          menubutton - Create and manipulate menubutton widgets

     SYNOPSIS
          menubutton pathName ?options?

     STANDARD OPTIONS
          -activebackground -disabledcolor      -justify
          -activeforeground -font               -relief
          -anchor           -foreground         -takefocus
          -background       -highlightcolor     -text
          -bitmap           -highlightthickness -underline
          -borderwidth      -image

     WIDGET-SPECIFIC OPTIONS
          -height state
               Specifies a desired height for the menubutton.  If this
               option is not specified, the menubutton's desired
               height is computed from the size of the image or bitmap
               or text being displayed in it.

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

          -state state
               Specifies one of three states for the menubutton:  nor-
               mal, active, or disabled.  In normal state the menubut-
               ton 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 dis-
               abledcolor and background options determine how the
               button is displayed.

          -width dist
               Specifies a desired width for the menubutton.  If this
               option is not specified, the menubutton's desired width
               is computed 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 to

     MENUBUTTON(9)                                       MENUBUTTON(9)

          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.

          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 new-
          lines) and one of the characters may optionally be under-
          lined using the underline option.  In normal usage, pressing
          mouse button 1 over the menubutton causes the associated
          menu to be posted just underneath the menubutton.  If the
          mouse button is released over the menubutton then the menu
          remains posted; clicking on the menubutton again unposts the
          menu.  Releasing the mouse button over a menu entry invokes
          the entry, while releasing mouse button elsewhere unposts
          the menu.

          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 without releasing the
          mouse button, then the menu of the first menubutton is
          unposted and the menu of the new menubutton is posted
          instead.

     WIDGET COMMAND
          The menubutton command creates a new Tk 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 behaviour of the
          command.  The following commands are possible for menubutton
          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 wid-
               get.  If no option is specified, returns a list of all
               of the available options for pathName.  If one or more
               option-value pairs are specified, then the command mod-
               ifies 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.

     MENUBUTTON(9)                                       MENUBUTTON(9)

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

          [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
               menu specified by the -menu option.  If the menu is
               already posted then it is unposted.

          [3]  Releasing mouse button 1 over the menubutton leaves the
               menu posted.  Releasing the button over a menu entry,
               if the menu is posted, invokes that entry.  Releaseing
               the button anywhere else unposts the menu.

          [4]  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(9) manual entry for
               details on these bindings.

          If the menubutton's state is disabled then none of the above
          actions occur:  the menubutton is completely non-responsive.

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

     SEE ALSO
          menu(9), options(9), types(9)