1menubutton(n) Tk Built-In Commands menubutton(n)
2______________________________________________________________________________
6
8 menubutton - Create and manipulate 'menubutton' pop-up menu indicator
9 widgets
10
12 menubutton pathName ?options?
13
15 -activebackground -disabledforeground -padx
16 -activeforeground -font -pady
17 -anchor -foreground -relief
18 -background -highlightbackground -takefocus
19 -bitmap -highlightcolor -text
20 -borderwidth -highlightthickness -textvariable
21 -cursor -image -underline
22 -compound -justify -wraplength
23 See the options manual entry for details on the standard options.
25
27 Command-Line Name:-direction
28 Database Name: direction
29 Database Class: Height
30 Specifies where the menu is going to be popup up. above tries to
32 pop the menu above the menubutton. below tries to pop the menu
33 below the menubutton. left tries to pop the menu to the left of
34 the menubutton. right tries to pop the menu to the right of the
35 menu button. flush pops the menu directly over the menubutton.
36 In the case of above or below, the direction will be reversed if
37 the menu would show offscreen.
38 Command-Line Name:-height
40 Database Name: height
41 Database Class: Height
42 Specifies a desired height for the menubutton. If an image or
44 bitmap is being displayed in the menubutton then the value is in
45 screen units (i.e. any of the forms acceptable to Tk_GetPixels);
46 for text it is in lines of text. If this option is not speci‐
47 fied, the menubutton's desired height is computed from the size
48 of the image or bitmap or text being displayed in it.
49 Command-Line Name:-indicatoron
51 Database Name: indicatorOn
52 Database Class: IndicatorOn
53 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
57 an option menubutton. If false then no indicator will be dis‐
58 played.
59 Command-Line Name:-menu
61 Database Name: menu
62 Database Class: MenuName
63 Specifies the path name of the menu associated with this
65 menubutton. The menu must be a child of the menubutton.
66 Command-Line Name:-state
68 Database Name: state
69 Database Class: State
70 Specifies one of three states for the menubutton: normal, ac‐
72 tive, or disabled. In normal state the menubutton is displayed
73 using the foreground and background options. The active state
74 is typically used when the pointer is over the menubutton. In
75 active state the menubutton is displayed using the -activefore‐
76 ground and -activebackground options. Disabled state means that
77 the menubutton should be insensitive: the default bindings will
78 refuse to activate the widget and will ignore mouse button
79 presses. In this state the -disabledforeground and -background
80 options determine how the button is displayed.
81 Command-Line Name:-width
83 Database Name: width
84 Database Class: Width
85 Specifies a desired width for the menubutton. If an image or
87 bitmap is being displayed in the menubutton then the value is in
88 screen units (i.e. any of the forms acceptable to Tk_GetPixels);
89 for text it is in characters. If this option is not specified,
90 the menubutton's desired width is computed from the size of the
91 image or bitmap or text being displayed in it.
92______________________________________________________________________________
93
95 The menubutton command creates a new window (given by the pathName ar‐
96 gument) and makes it into a menubutton widget. Additional options, de‐
97 scribed above, may be specified on the command line or in the option
98 database to configure aspects of the menubutton such as its colors,
99 font, text, and initial relief. The menubutton command returns its
100 pathName argument. At the time this command is invoked, there must not
101 exist a window named pathName, but pathName's parent must exist.
102 A menubutton is a widget that displays a textual string, bitmap, or im‐
104 age and is associated with a menu widget. If text is displayed, it
105 must all be in a single font, but it can occupy multiple lines on the
106 screen (if it contains newlines or if wrapping occurs because of the
107 -wraplength option) and one of the characters may optionally be under‐
108 lined using the -underline option. In normal usage, pressing mouse
109 button 1 over the menubutton causes the associated menu to be posted
110 just underneath the menubutton. If the mouse is moved over the menu
111 before releasing the mouse button, the button release causes the under‐
112 lying menu entry to be invoked. When the button is released, the menu
113 is unposted.
114 Menubuttons are used to construct a tk_optionMenu, which is the pre‐
116 ferred mechanism for allowing a user to select one item from a list on
117 Mac OS X.
118 Menubuttons were also typically organized into groups called menu bars
120 that allow scanning: if the mouse button is pressed over one menubutton
121 (causing it to post its menu) and the mouse is moved over another
122 menubutton in the same menu bar without releasing the mouse button,
123 then the menu of the first menubutton is unposted and the menu of the
124 new menubutton is posted instead. This use is deprecated in favor of
125 setting a menu directly as a menubar; see the toplevel's -menu option
126 for how to do that.
127 There are several interactions between menubuttons and menus; see the
129 menu manual entry for information on various menu configurations, such
130 as pulldown menus and option menus.
131
133 The menubutton command creates a new Tcl command whose name is path‐
134 Name. This command may be used to invoke various operations on the
135 widget. It has the following general form:
136 pathName option ?arg arg ...?
137 Option and the args determine the exact behavior of the command. The
138 following commands are possible for menubutton widgets:
139 pathName cget option
141 Returns the current value of the configuration option given by
142 option. Option may have any of the values accepted by the
143 menubutton command.
144 pathName configure ?option? ?value option value ...?
146 Query or modify the configuration options of the widget. If no
147 option is specified, returns a list describing all of the avail‐
148 able options for pathName (see Tk_ConfigureInfo for information
149 on the format of this list). If option is specified with no
150 value, then the command returns a list describing the one named
151 option (this list will be identical to the corresponding sublist
152 of the value returned if no option is specified). If one or
153 more option-value pairs are specified, then the command modifies
154 the given widget option(s) to have the given value(s); in this
155 case the command returns an empty string. Option may have any
156 of the values accepted by the menubutton command.
157
159 Tk automatically creates class bindings for menubuttons that give them
160 the following default behavior:
161 [1] A menubutton activates whenever the mouse passes over it and de‐
163 activates whenever the mouse leaves it.
164 [2] Pressing mouse button 1 over a menubutton posts the menubutton:
166 its relief changes to raised and its associated menu is posted
167 under the menubutton. If the mouse is dragged down into the
168 menu with the button still down, and if the mouse button is then
169 released over an entry in the menu, the menubutton is unposted
170 and the menu entry is invoked.
171 [3] If button 1 is pressed over a menubutton and then released over
173 that menubutton, the menubutton stays posted: you can still move
174 the mouse over the menu and click button 1 on an entry to invoke
175 it. Once a menu entry has been invoked, the menubutton unposts
176 itself.
177 [4] If button 1 is pressed over a menubutton and then dragged over
179 some other menubutton, the original menubutton unposts itself
180 and the new menubutton posts.
181 [5] If button 1 is pressed over a menubutton and released outside
183 any menubutton or menu, the menubutton unposts without invoking
184 any menu entry.
185 [6] When a menubutton is posted, its associated menu claims the in‐
187 put focus to allow keyboard traversal of the menu and its sub‐
188 menus. See the menu manual entry for details on these bindings.
189 [7] If the -underline option has been specified for a menubutton
191 then keyboard traversal may be used to post the menubutton:
192 Alt+x, where x is the underlined character (or its lower-case or
193 upper-case equivalent), may be typed in any window under the
194 menubutton's toplevel to post the menubutton.
195 [8] The F10 key may be typed in any window to post the first
197 menubutton under its toplevel window that is not disabled.
198 [9] If a menubutton has the input focus, the space and return keys
200 post the menubutton.
201 If the menubutton's state is disabled then none of the above actions
203 occur: the menubutton is completely non-responsive.
204 The behavior of menubuttons can be changed by defining new bindings for
206 individual widgets or by redefining the class bindings.
207
209 ttk::menubutton(n), menu(n)
210
212 menubutton, widget
213Tk 4.0 menubutton(n)