menubutton(n)                Tk Built-In Commands                menubutton(n)



NAME
       menubutton - Create and manipulate menubutton widgets

SYNOPSIS
       (menubutton widget-name ?options?)
       :activebackground   :cursor   :highlightthickness :takefocus
       :activeforeground   :disabledforeground :image    :text
       :anchor   :font     :justify  :textvariable
       :background    :foreground    :padx     :underline
       :bitmap   :highlightbackground     :pady     :wraplength
       :borderwidth   :highlightcolor     :relief

WIDGET-SPECIFIC OPTIONS
       [:direction direction] 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.
       [:environment environment] Specifies the environment in which the
       :textvariable must be taken.  By default, the value of this option is
       the STk global environment.  [:height 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 computed
       from the size of the image or bitmap or text being displayed in it.
       [:indicatoron indicatorOn] 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
       displayed.  [:menu menu] 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:
       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
       displayed.  [:width 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 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 widget-name
       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
       widget-name argument.  At the time this command is invoked, there must
       not exist a window named widget-name, but widget-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
       underlined 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 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 various menu configurations, such
       as pulldown menus and option menus.


WIDGET COMMAND
       The menubutton command creates a new STk command whose name is
       widget-name.  This command may be used to invoke various operations on
       the widget.  It has the following general form: (widget-name option
       ?arg arg ...?)  Option and the args determine the exact behavior of the
       command.  The following commands are possible for menubutton widgets:

       (widget-name '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.

       (widget-name '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 widget-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 describing the
              one named option (this list will be identical 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 underlined 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.


SEE ALSO
       menu option-menu



STk                                   4.0                        menubutton(n)
