1menubutton(n)                Tk Built-In Commands                menubutton(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       menubutton  -  Create and manipulate 'menubutton' pop-up menu indicator
9       widgets
10

SYNOPSIS

12       menubutton pathName ?options?
13

STANDARD OPTIONS

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
24       See the options manual entry for details on the standard options.
25

WIDGET-SPECIFIC OPTIONS

27       Command-Line Name:-direction
28       Database Name:  direction
29       Database Class: Height
30
31              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
39       Command-Line Name:-height
40       Database Name:  height
41       Database Class: Height
42
43              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
50       Command-Line Name:-indicatoron
51       Database Name:  indicatorOn
52       Database Class: IndicatorOn
53
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
57              an option menubutton.  If false then no indicator will  be  dis‐
58              played.
59
60       Command-Line Name:-menu
61       Database Name:  menu
62       Database Class: MenuName
63
64              Specifies  the  path  name  of  the  menu  associated  with this
65              menubutton.  The menu must be a child of the menubutton.
66
67       Command-Line Name:-state
68       Database Name:  state
69       Database Class: State
70
71              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
82       Command-Line Name:-width
83       Database Name:  width
84       Database Class: Width
85
86              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

INTRODUCTION

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
103       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
115       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
119       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
128       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

WIDGET COMMAND

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
140       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
145       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

DEFAULT BINDINGS

159       Tk automatically creates class bindings for menubuttons that give  them
160       the following default behavior:
161
162       [1]    A menubutton activates whenever the mouse passes over it and de‐
163              activates whenever the mouse leaves it.
164
165       [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
172       [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
178       [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
182       [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
186       [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
190       [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
196       [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
199       [9]    If a menubutton has the input focus, the space and  return  keys
200              post the menubutton.
201
202       If  the  menubutton's  state is disabled then none of the above actions
203       occur:  the menubutton is completely non-responsive.
204
205       The behavior of menubuttons can be changed by defining new bindings for
206       individual widgets or by redefining the class bindings.
207

SEE ALSO

209       ttk::menubutton(n), menu(n)
210

KEYWORDS

212       menubutton, widget
213
214
215
216Tk                                    4.0                        menubutton(n)
Impressum