1Menubutton(3) User Contributed Perl Documentation Menubutton(3)
2
6 Tk::Menubutton - Create and manipulate Menubutton widgets
7
9 $menubutton = $parent->Menubutton(?options?);
10
12 -activebackground -cursor -highlightthickness -takefocus
13 -activeforeground -disabledforeground -image -text
14 -anchor -font -justify -textvariable
15 -background -foreground -padx -underline
16 -bitmap -highlightbackground -pady -wraplength
17 -borderwidth -highlightcolor -relief
18 See Tk::options for details of the standard options.
20
22 Command-Line Name: -compound
23 Database Name: compound
24 Database Class: Compound
25 Specifies whether the button should display both an image and text,
26 and if so, where the image should be placed relative to the text.
27 Valid values for this option are bottom, center, left, none, right
28 and top. The default value is none, meaning that the button will
29 display either an image or text, depending on the values of the
30 -image and -bitmap options.
31 Name: direction
33 Class: Height
34 Switch: -direction
35 Specifies where the menu is going to be popup up. above tries to
36 pop the menu above the menubutton. below tries to pop the menu
37 below the menubutton. left tries to pop the menu to the left of the
38 menubutton. right tries to pop the menu to the right of the menu
39 button. flush pops the menu directly over the menubutton.
40 Name: height
42 Class: Height
43 Switch: -height
44 Specifies a desired height for the menubutton. If an image or
45 bitmap is being displayed in the menubutton then the value is in
46 screen units (i.e. any of the forms acceptable to Tk_GetPixels);
47 for text it is in lines of text. If this option isn't specified,
48 the menubutton's desired height is computed from the size of the
49 image or bitmap or text being displayed in it.
50 Name: indicatorOn
52 Class: IndicatorOn
53 Switch: -indicatoron
54 The value must be a proper boolean value. If it is true then a
55 small indicator rectangle will be displayed on the right side of
56 the menubutton and the default menu bindings will treat this as an
57 option menubutton. If false then no indicator will be displayed.
58 Name: menu
60 Class: MenuName
61 Switch: -menu
62 Specifies the path name of the menu associated with this
63 menubutton. The menu must be a child of the menubutton.
64 Name: state
66 Class: State
67 Switch: -state
68 Specifies one of three states for the menubutton: normal, active,
69 or disabled. In normal state the menubutton is displayed using the
70 foreground and background options. The active state is typically
71 used when the pointer is over the menubutton. In active state the
72 menubutton is displayed using the activeForeground and
73 activeBackground options. Disabled state means that the menubutton
74 should be insensitive: the default bindings will refuse to
75 activate the widget and will ignore mouse button presses. In this
76 state the disabledForeground and background options determine how
77 the button is displayed.
78 Name: width
80 Class: Width
81 Switch: -width
82 Specifies a desired width for the menubutton. If an image or
83 bitmap is being displayed in the menubutton then the value is in
84 screen units (i.e. any of the forms acceptable to Tk_GetPixels);
85 for text it is in characters. If this option isn't specified, the
86 menubutton's desired width is computed from the size of the image
87 or bitmap or text being displayed in it.
88
90 The Menubutton method creates a new window (given by the $widget
91 argument) and makes it into a menubutton widget. Additional options,
92 described above, may be specified on the command line or in the option
93 database to configure aspects of the menubutton such as its colors,
94 font, text, and initial relief. The menubutton command returns its
95 $widget argument. At the time this command is invoked, there must not
96 exist a window named $widget, but $widget's parent must exist.
97 A menubutton is a widget that displays a textual string, bitmap, or
99 image and is associated with a menu widget. If text is displayed, it
100 must all be in a single font, but it can occupy multiple lines on the
101 screen (if it contains newlines or if wrapping occurs because of the
102 wrapLength option) and one of the characters may optionally be
103 underlined using the underline option. In normal usage, pressing mouse
104 button 1 over the menubutton causes the associated menu to be posted
105 just underneath the menubutton. If the mouse is moved over the menu
106 before releasing the mouse button, the button release causes the
107 underlying menu entry to be invoked. When the button is released, the
108 menu is unposted.
109 Menubuttons are typically organized into groups called menu bars that
111 allow scanning: if the mouse button is pressed over one menubutton
112 (causing it to post its menu) and the mouse is moved over another
113 menubutton in the same menu bar without releasing the mouse button,
114 then the menu of the first menubutton is unposted and the menu of the
115 new menubutton is posted instead.
116 There are several interactions between menubuttons and menus; see the
118 menu manual entry for information on various menu configurations, such
119 as pulldown menus and option menus.
120
122 The Menubutton method creates a widget object. This object supports
123 the configure and cget methods described in Tk::options which can be
124 used to enquire and modify the options described above. The menu
125 method returns the menu associated with the widget. The widget also
126 inherits all the methods provided by the generic Tk::Widget class.
127
129 Tk automatically creates class bindings for menubuttons that give them
130 the following default behavior:
131 [1] A menubutton activates whenever the mouse passes over it and
133 deactivates whenever the mouse leaves it.
134 [2] Pressing mouse button 1 over a menubutton posts the menubutton: its
136 relief changes to raised and its associated menu is posted under
137 the menubutton. If the mouse is dragged down into the menu with
138 the button still down, and if the mouse button is then released
139 over an entry in the menu, the menubutton is unposted and the menu
140 entry is invoked.
141 [3] If button 1 is pressed over a menubutton and then released over
143 that menubutton, the menubutton stays posted: you can still move
144 the mouse over the menu and click button 1 on an entry to invoke
145 it. Once a menu entry has been invoked, the menubutton unposts
146 itself.
147 [4] If button 1 is pressed over a menubutton and then dragged over some
149 other menubutton, the original menubutton unposts itself and the
150 new menubutton posts.
151 [5] If button 1 is pressed over a menubutton and released outside any
153 menubutton or menu, the menubutton unposts without invoking any
154 menu entry.
155 [6] When a menubutton is posted, its associated menu claims the input
157 focus to allow keyboard traversal of the menu and its submenus.
158 See the menu documentation for details on these bindings.
159 [7] If the underline option has been specified for a menubutton then
161 keyboard traversal may be used to post the menubutton: Alt+x, where
162 x is the underlined character (or its lower-case or upper-case
163 equivalent), may be typed in any window under the menubutton's
164 toplevel to post the menubutton.
165 [8] The F10 key may be typed in any window to post the first menubutton
167 under its toplevel window that isn't disabled.
168 [9] If a menubutton has the input focus, the space and return keys post
170 the menubutton.
171 If the menubutton's state is disabled then none of the above
173 actions occur: the menubutton is completely non-responsive.
174 The behavior of menubuttons can be changed by defining new bindings
176 for individual widgets or by redefining the class bindings.
177
179 menubutton, widget
180perl v5.36.0 2023-01-20 Menubutton(3)