MENUBUTTON(9)                                       MENUBUTTON(9)

     NAME
          menubutton - Create and manipulate menubutton widgets

     SYNOPSIS
          menubutton pathName ?options?

     STANDARD OPTIONS
          -activebackground -borderwidth      -padx
          -activeforeground -font             -pady
          -anchor           -foreground       -relief
          -background       -image            -text
          -bitmap           -justify          -underline

     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-
               abledForeground 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 on the
          command line or in the option database to configure aspects

     Page 1                       Plan 9             (printed 3/29/24)

     MENUBUTTON(9)                                       MENUBUTTON(9)

          of the menubutton such as its colors, font, text, and ini-
          tial relief.  The menubutton command returns its pathName
          argument.  At the time this command is invoked, there must
          not exist a window named pathName, but pathName'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 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 is moved over the menu before releasing the mouse but-
          ton, 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.

     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.

     Page 2                       Plan 9             (printed 3/29/24)

     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
               menubutton: its relief changes to raised and its asso-
               ciated 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]  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.

          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
          options(9), types(9)

     Page 3                       Plan 9             (printed 3/29/24)