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
Page 1 Plan 9 (printed 12/21/24)
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.
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
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)
Page 3 Plan 9 (printed 12/21/24)