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 12/21/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 12/21/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 12/21/24)